ArcSight CLI - Deterministic Platform Skeleton
npm install @arcsight-ai/cli
This is the deterministic platform skeleton for the ArcSight CLI. This skeleton provides the structural foundation for ArcSight's deterministic UX platform and follows strict wedge-aligned engineering rules.
ArcSight reports deterministic architectural signals.
It surfaces only provable structural issues and prefers silence to uncertainty.
It does not enforce policy, block CI, or suggest fixes.
Details are always opt-in.
This skeleton contains ONLY structural elements:
- Type definitions and interfaces
- Placeholder function signatures
- Command routing structure
- Formatter skeletons
- Documentation
NO business logic has been implemented.
NO wedge imports or dependencies.
NO analysis behavior.
The ArcSight CLI is designed around core determinism principles:
1. No Mutation: Envelopes and data structures are immutable
2. Stable Output: All outputs are deterministic and reproducible
3. Wedge Isolation: The CLI platform is isolated from wedge implementation details
4. Safety First: Safety ledger tracks all safety-related decisions
5. Versioned Contracts: Envelope schema is versioned and backward-compatible
```
arcsight-cli/
├── src/
│ ├── index.ts # CLI entrypoint (commander setup)
│ ├── envelope.ts # AnalysisEnvelope contract
│ ├── envelopeVersioning.ts # Schema versioning map
│ ├── runtime/ # Runtime context
│ ├── errors/ # Error classification
│ ├── determinism/ # Determinism utilities (placeholders)
│ ├── stability/ # Stability utilities (placeholders)
│ ├── safety/ # Safety ledger
│ ├── lifecycle/ # Lifecycle hooks
│ ├── startup/ # Startup checks (placeholders)
│ ├── formatters/ # Output formatters (placeholders)
│ ├── commands/ # Command handlers (placeholders)
│ └── types/ # Type definitions
├── tests/ # Test suite
├── demos/ # Demo scenarios
└── docs/ # Documentation
contract - the deterministic structure for all CLI output.$3
Formatter modules for different output profiles:
- human.ts - Human-readable output
- json.ts - JSON output
- ci.ts - CI/CD output
- cycles.ts - Cycle detection output
- graph.ts - Dependency graph output
- silent.ts - Silent mode output
- determinism.ts - Determinism verification output
- profile.ts - Profile routing$3
Command handlers:
- analyze.ts - Main analysis command
- demo.ts - Demo command
- explainCycle.ts - Cycle explanation command
- utils.ts - Command utilities$3
Determinism utilities (placeholders):
- deepFreeze.ts - Immutability enforcement
- stableSort.ts - Deterministic sorting
- stableKeys.ts - Deterministic key extraction
- stableJson.ts - Deterministic JSON encoding$3
Safety ledger for tracking safety-related decisions and warnings.$3
Lifecycle hooks for CLI execution phases.$3
Startup validation checks (environment, node version, wedge compatibility).CLI Contract
See docs/cli-contract.md for the complete CLI contract documentation, including:
- Deterministic design principles
- No-mutation rules
- Envelope architecture
- Error handling rules
- Formatter constraints
- Extension boundaries
- Versioning scheme
Wedge Isolation Rules
CRITICAL: This CLI skeleton must NOT:
- Import
@arcsight/wedge or any wedge dependencies
- Implement analysis logic
- Call wedge functions
- Assume wedge shapes or structures
- Mutate "raw" outputs (placeholders only)The CLI platform is a deterministic framework that will eventually consume wedge output, but the skeleton maintains strict isolation.
Development
$3
- Node.js >= 18.0.0 (see .nvmrc)
- TypeScript 5.0+$3
`bash
npm run build
`$3
`bash
npm test
``When implementing business logic:
1. Maintain determinism guarantees
2. Follow the CLI contract
3. Implement formatters without mutation
4. Use the safety ledger for all safety decisions
5. Preserve envelope immutability
Apache License 2.0. See LICENSE.