ArcSight CLI - Deterministic Platform Skeleton

Purpose

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.

What ArcSight Is

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.

⚠️ Important: NO BUSINESS LOGIC YET

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.

Determinism Philosophy

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

Project Structure

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

Folder Responsibilities

src/envelope.ts

Defines the AnalysisEnvelope contract - the deterministic structure for all CLI output.

src/formatters/

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

src/commands/

Command handlers:

• analyze.ts - Main analysis command
• demo.ts - Demo command
• explainCycle.ts - Cycle explanation command
• utils.ts - Command utilities

src/determinism/

Determinism utilities (placeholders):

• deepFreeze.ts - Immutability enforcement
• stableSort.ts - Deterministic sorting
• stableKeys.ts - Deterministic key extraction
• stableJson.ts - Deterministic JSON encoding

src/safety/

Safety ledger for tracking safety-related decisions and warnings.

src/lifecycle/

Lifecycle hooks for CLI execution phases.

src/startup/

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

Prerequisites

• Node.js >= 18.0.0 (see .nvmrc)
• TypeScript 5.0+

Build

npm run build

Test

npm test

Future Implementation

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

License

Apache License 2.0. See LICENSE.