app.cli-contractspec

@lssm-tech/app.cli-contractspec

Website: https://contractspec.io

Slim CLI host for authoring, materializing, and validating ContractSpec targets.

The optional AI, Builder and examples contribution exports include generated declarations under dist/types/optional-contributions. build:all emits these from their explicitly typed sources with isolated declaration generation; the ordinary build still runs the complete CLI typecheck before bundling. Published type exports therefore resolve without shipping the source tree.

What It Does

• Core commands (src/commands/) - Authoring, validation, workspace, release, registry, OpenAPI, Connect, CI, doctor, and maintenance surfaces.
• Command packs - Optional command families discovered from direct consumer dependencies carrying contractspec.commandPack metadata.
• Prompts (src/commands/create/wizards/) - Interactive UI using @inquirer/prompts.
• CLI setup (src/index.ts, src/cli.ts) - Commander.js configuration.
• Types (src/types.ts) - CLI-specific types.
• Services (@lssm-tech/bundle.workspace/services/) - Core use-cases.
• create.ts - Authored target creation logic.
• build.ts - Runtime/package materialization from authored targets.
• openapi.ts - OpenAPI export.

Delivery onboarding and orchestration

Initialize incrementally without selecting a CI or cloud provider:

contractspec init --preset delivery-local
contractspec init --preset delivery-hybrid
contractspec init --preset delivery-managed

The public orchestration commands retain the specialist Connect, Builder, and Harness commands underneath them:

contractspec delivery plan --input delivery-material.json
contractspec delivery profile --input project-profile-material.json --output project-profile.json --json
contractspec delivery autonomy --policies autonomy-policies.json --context authenticated-scope.json --json
contractspec delivery status
contractspec delivery verify --plan .contractspec/delivery/plan.json
contractspec delivery replay --digest sha256:...
contractspec quality plan --input quality-material.json
contractspec quality run --plan quality-plan.json --registry quality-registry.ts --config runner.json
contractspec quality verify --plan quality-plan.json --receipt quality-receipt.json

The local ledger is content-addressed and tamper-evident for replay, but it is not production authority. Managed promotion still requires durable Connect read-back and an exact promotion permit.

Running Locally

From packages/apps/cli-contractspec:

• bun run dev
• bun run build
• bun run test
• bun run typecheck

Usage

bun run dev

Optional command packs

The default install intentionally excludes specialist command families. Install only the packs a workspace uses:

bun add @lssm-tech/integration.cli-contractspec-design
bun add @lssm-tech/integration.cli-contractspec-ai
bun add @lssm-tech/integration.cli-contractspec-builder
bun add @lssm-tech/integration.cli-contractspec-examples

The host discovers packs only from the consuming workspace's direct dependencies. Loading is deterministic by package name, duplicate command names and pack load failures stop startup before argument parsing, and .contractsrc can explicitly include or exclude packages (exclusion wins):

{
  "commandPacks": {
    "include": ["@lssm-tech/integration.cli-contractspec-design"],
    "exclude": []
  }
}

Utiliser createCoreProgram() when an embedding needs the synchronous, pack-free program. createProgram() performs discovery and is asynchronous:

import {
  createCoreProgram,
  createProgram,
} from "@lssm-tech/app.cli-contractspec";

const coreProgram = createCoreProgram();
const program = await createProgram({ consumerRoot: process.cwd() });

Calling an optional command without its pack prints the corresponding install hint. See docs/migrations/cli-command-packs-v7.md for the major-version migration.

Local Connect review authority

Durable host-hook authority

Contracts-spec host hooks deny by default unless the repository host injects a trusted HookAuthorityPort. Environment-selected modules are never loaded as authority. Production hosts construct the port with createSingleNodeHookAuthorityPort from @lssm-tech/integration.lssm-os-state-sqlite, a migrated driver, the real Connect signature verifier, and a live binding resolver. Hook payloads carry the signed V1 request as authorityRequest; session start also carries a caller-generated sessionCapability through the dedicated one-use input. Only its signed SHA-256 commitment and opaque session reference reach durable state, receipts, and output. Local patch-verdict JSON is never treated as signature or live-binding authority.

Host hook run modes

With --host claudecode|codex|cursor and no durable authority wired, a hook evaluates Connect policy first (deny and rewrite always block), then lets the agent host's permission_mode decide whether the operator is asked:

Shell policy covers every command a line runs: cd <dir> && git push --force, git -C <dir> push -f, git push origin +ref, bash -c "..." and pwsh -Command "..." are denied like the plain force push, in every run mode. The generated Claude Code hooks govern both the Bash and PowerShell tools.

An operator can grant a bounded mode for the current worktree, including full (never asks; only policy denies block):

contractspec connect mode show
contractspec connect mode set autonomous --for 8h --scope packages/domains --reason "overnight refactor"
contractspec connect mode clear

.contractsrc.json connect.runModes sets default (hosts that report no mode), hostModes, maxLevel, and extra highCriticalityPaths; connect.durableAuthorityRequired: true caps every run mode at supervised. Agent tool calls cannot raise their own autonomy: edits to hook settings or the grant file and executed connect mode set|clear are asked in supervised and assisted modes and denied in autonomous and full. Every decision taken without asking is appended to .contractspec/connect/run-mode-decisions.ndjson.

Durable local review uses PostgreSQL and does not require a separate database or a control-plane API token. Configure CHANNEL_RUNTIME_DATABASE_URL, DATABASE_URL, or reuse the managed CompanyOS LSSM_STUDIO_DATABASE_URL, then inspect readiness and decisions:

contractspec connect doctor --json
contractspec connect review get <decision-id> --json
contractspec connect review status <decision-id> --json
contractspec connect review approve <decision-id> --stdin --json
contractspec connect review reject <decision-id> --stdin --json

After tracked migrations reach 006a, migration owners must run the conflict-aware connect review provision-authority dry run and then apply with exact role, issuer actor, authorization fingerprint, reviewer email/fingerprint, authority-ref, and proof-ref confirmations. The command stores public metadata only, verifies the explicit role equals the authenticated session_user/current_user, and accepts no private key. This direct, fully confirmed command is the deliberately narrow out-of-band bootstrap for the first reviewer; applying it through shell composition is denied, and later authority changes remain subject to Connect review. Migration owners can then idempotently enroll a human reviewer from a pending decision with connect review enroll, then create the exact short-lived signing packet with connect review challenge. Enrollment accepts only an Ed25519 public key (--public-key or --stdin) plus provenance/audit metadata; scope and capability always come from the stored decision, and private key material is rejected.

Approve/reject stdin must be a fresh human-signed challenge packet. Capability claims, TTY confirmation, packet actor fields, fixture keys, and agent-authored signatures do not establish authority. See docs/runbooks/connect-local-review.md for role setup and verification.

Recommended OSS Onboarding

contractspec init --preset connect
contractspec validate

Example-backed onboarding is provided by @lssm-tech/integration.cli-contractspec-examples.

Discover capabilities ("can it help?")

Ask whether ContractSpec already provides a capability — or whether your repo already has one — before building it yourself. Fully offline, no model required.

contractspec can-help "render a data table from a contract"
contractspec ask "capture an invoice from a customer" --scope workspace
contractspec can-help "replace FastAPI" --runtime node --stability stable --json

Returns a have-it / can-help / gap verdict over a two-tier corpus (the shipped ContractSpec + ecosystem adoption catalog plus a local overlay of your own surfaces), with the canonical surface to adopt and a confidence score. --scope accepts all (default), workspace, installed, contractspec, or ecosystem; local remains a compatibility alias for workspace. Results include installed state, target version, install command, canonical imports, documentation, alternatives, score reasons, and catalog provenance.

The same query is exposed to agents as the offline MCP tool contractspec.can_help (served by contractspec mcp).

Enforce reuse (Connect ladder)

# Graduated verdict: permit(0) / rewrite(10) / require_review(20) / deny(30)
contractspec connect leverage --intent "build a multi-agent AI chat surface"

# Opt-in hard-deny at high confidence; bypass with a recorded override
contractspec connect leverage --intent "..." --deny --override "need a bespoke variant" --actor you

deny is opt-in and high-confidence only; an --override justification is persisted to .contractspec/connect/leverage-overrides.json as audit evidence.

Leverage-gap report & catalog freshness (CI)

contractspec can-help report                 # where this repo reinvented existing capabilities
contractspec can-help catalog sync --json    # refresh the complete V2 local mirror
contractspec can-help catalog status --json  # source/hash/freshness/degraded state
contractspec can-help catalog search "Pydantic" --json
contractspec can-help catalog get "@lssm-tech/lib.schema" --json
contractspec can-help catalog --snapshot capability-catalog.json
contractspec can-help catalog --check capability-catalog.json   # exit 1 if stale (CI gate)

contractspec connect adoption sync --json and can-help catalog sync select the newest hash-valid registry, installed, local-mirror, or CLI-embedded V2 catalog. In a workspace that contains @lssm-tech/lib.contractspec-catalog, that package's own catalog.json is an installed candidate ranked above the local mirror, reported with the catalog.workspace-package diagnostic. Offline fallback is explicit in the returned diagnostics; the written .contractspec/adoption/catalog.json always contains the complete selected document rather than only local release artifacts.

Repository lifecycle

contractspec update --json            # read-only V2 compatibility plan
contractspec update --check --json    # CI: non-zero for updates, blockers, or stale artifacts
contractspec update --apply --wave framework.expo-57
contractspec update --apply --wave peer-normalization
contractspec update --wave compatible.patch-minor --json # deprecated read-only aggregate
contractspec update --apply --wave compatible.ai
contractspec update --apply --wave compatible.tooling
contractspec update --apply --wave breaking.better-auth  # explicit migration review
contractspec update --apply --wave major.frontend
contractspec doctor --format json     # read-only health and provenance
contractspec doctor --fix             # sequential safe waves, then fresh checks
contractspec spec update <file>        # canonical spec editing command

Update selects the highest version compatible with framework constraints, runtime engines, package peers, singleton requirements, configured pins, and the currently adopted stable or prerelease channel. V2 JSON includes the selected channel, constraint provenance, registry provenance, risk, blocked reasons, and deterministic waves. @lssm-tech/* metadata comes from public npmjs package records; local workspace versions prevent publisher-repository downgrades.

Applying requires one explicit wave. Compatible patch/minor updates are split into deterministic compatible.<ecosystem> transactions; the legacy compatible.patch-minor selector remains read-only. Semver-zero minor jumps, 0.0.x changes, and version transitions with catalog migration metadata are reported as high-risk breaking.<ecosystem> waves. Doctor only auto-applies framework, peer-normalization, and compatible waves.

Expo apps use Expo SDK API compatibility data and fall back offline to the installed expo/bundledNativeModules.json. Shared React and React Native stay singletons, while mobile TypeScript is isolated in catalog:native. Existing broad peer ranges remain unchanged; incompatible peers are widened without narrowing already published compatibility. File, Git, workspace, and unsupported alias ranges stay unchanged with diagnostics. Receipts and rollback snapshots live under .contractspec/update/transactions/. The legacy upgrade command forwards to this lifecycle for compatibility and also requires --wave when applying. When installation or verification fails, rollback restores owned files and then reconciles the install tree from the restored lockfile; a failed frozen reinstall is reported as a failed rollback rather than a successful one. Selected waves verify the packages whose manifests changed, plus migration and Doctor checks. Repository-wide typecheck, lint, and tests remain final release gates rather than being repeated twice for every ecosystem wave.

Core Authoring/Build Model

• create authors both runtime specs and package-oriented targets such as module-bundle, builder-spec, and provider-spec.
• build materializes one authored target into runtime artifacts or package scaffolds.
• generate runs workspace-wide generation for docs and derived artifacts.
• validate checks authored targets, package scaffolds, and optional runtime implementations.
• contractspec create visual-scenario scaffolds a provider-neutral .visual-scenario.ts contract with safe synthetic capture defaults.
• contractspec build --target storybook [visual-scenario-file] generates the configured Storybook catalog; add --check in CI to fail on generated drift.
• Example-backed onboarding is an optional command-pack responsibility rather than part of the default CLI closure.

LSSM OS durable operation status

The CLI and default MCP server reuse the canonical LSSM OS operation client. They do not define their own status, receipt, or error mappings.

export LSSM_OS_AUTHORIZATION='Bearer <opaque-token>'
export LSSM_OS_AGENT_HOST_ORIGIN='https://agent-host.example.com'

contractspec lssm-os operation status operation-123 \
  --origin "$LSSM_OS_AGENT_HOST_ORIGIN" \
  --tenant-id tenant --workspace-id workspace --environment-id production

The command writes the canonical CLI projection as JSON and exits 5 while the durable operation is nonterminal, 0 after success, and 1 for terminal failure or a closed canonical error. The MCP tool contractspec.lssm_os.operation_status uses the configured origin and returns the exact canonical MCP structured content. Authorization is read only from LSSM_OS_AUTHORIZATION; it is never accepted as a command argument, MCP input, or returned evidence.

The package qualification suite also dereferences one real Agent Host HTTP 202 response through the SDK, this CLI exit-5 path, MCP structured content, and the canonical React hook. All five surfaces must retain the same operation and projection digests; this is credential-free simulated parity, not live product or provider qualification.

Model Context Protocol (MCP) servers

The CLI ships two local, offline-first MCP servers over stdio. They replace the previously hosted api.contractspec.io MCP endpoints (docs/cli/internal/contracts), which have been Retiré — point your editor/agent at the local commands below.

# Knowledge + author tools (default). Offline, zero setup, no network.
contractspec mcp

# Runtime projection of THIS repo's own contracts (opt-in, fail-closed).
contractspec mcp --runtime

# Operate against a different working directory:
contractspec mcp --cwd /path/to/project

• contractspec mcp (knowledge + author tools) — fully offline. Exposes docs search/get/resolve-route/contract-reference/facets, CLI usage/suggest, the internal endpoint catalog, examples browsing, and author tools over the consumer's cwd: contracts.list/get/validate/build/update/delete plus the new contracts.create spec scaffold. The knowledge corpus is generated at build time from the docblock manifest + docs registry + example metadata (plus a small curated getting-started/patterns overlay) and bundled into the published package, so it works with no network and no setup.
• contractspec mcp --runtime (runtime projection) — opt-in. Discovers and loads the consumer's own OperationSpecRegistry and projects it as MCP tools. It is fail-closed:
  • Projets only handler-backed operations (spec-only ops are never surfaced).
  • Read-only queries are allowed; every write/command is DENIED by default (destructive and admin operations included). Permit specific writes by name via .contractsrc.json.
  • On no registry / zero bound ops / load failure it prints a clear error to stderr, exits non-zero, and registers nothing.

Security notes

• Author server has no policy gate (scope to trusted workspaces). contractspec mcp (the default knowledge + author server) exposes write tools — contracts.create, contracts.update, contracts.delete, and contracts.build — that create, modify, delete, and generate spec files in the working directory. There is no per-tool policy check on this server, so only run it against a workspace you trust the connected agent to modify (and prefer --cwd to scope it explicitly).
• --runtime handlers run as actor: 'anonymous'. Every operation projected by the runtime server is executed with an anonymous actor context. Consumers MUST NOT treat anonymous as an elevated or privileged identity inside their handlers; gate any sensitive behavior on explicit policy, not on the absence of an actor.

.contractsrc.json mcp.runtime keys (runtime server)

{
  "mcp": {
    "runtime": {
      // Path to a module exporting an OperationSpecRegistry (named `registry`/
      // `operations`/`ops`, or default). Overrides convention-based discovery.
      "registry": "dist/registry.js",
      // Operation keys allowed to be projected as writable tools (opt-in).
      "allowWrites": ["project.create"]
    }
  }
}

When mcp.runtime.registry is omitted, the server resolves candidate registry modules from the contractsrc operations layout (and common defaults like operations/, src/operations/). v1 limitation: the mcp.runtime block is read directly (not yet part of the typed contractsrc.schema.json), so editor schema autocomplete is not available for these keys.

Editor wiring (mcp.json / settings)

"contractspec": { "command": "npx", "args": ["-y", "@lssm-tech/app.cli-contractspec", "mcp"], "env": {} },
"contractspec-runtime": { "command": "npx", "args": ["-y", "@lssm-tech/app.cli-contractspec", "mcp", "--runtime"], "env": {} }

Migration from the removed hosted MCP: replace the old api.contractspec.io MCP entries in your mcp.json (or .claude/.cursor/.zed config) with the two stdio entries above. Zed entries also need "type": "stdio". All MCP logging goes to stderr; stdout is the JSON-RPC channel.

Help and command discovery

contractspec --help is the canonical public command index. It groups root commands by category and includes implemented public command families such as intelligence, connect, release, and changelog. Subcommand help uses the same grouped renderer, so contractspec intelligence --help and contractspec connect --help preserve clean descriptions and category headings instead of falling back to an unstructured command list.

Release capsule guardrails

Prefer guided release authoring over raw YAML edits:

contractspec release prepare --baseline main
contractspec release edit <slug>
contractspec release fix <slug> --write
contractspec release check --strict --baseline main

contractspec connect hook release-capsule after-file-edit --stdin validates .changeset/*.release.yaml and paired .changeset/*.md edits without mutating files. When malformed YAML is recoverable, contractspec release fix <slug> --write rewrites the canonical .release.yaml and preserves unsupported fields in .changeset/<slug>.release.quarantine.yaml; scalar values of the string-list fields (deprecations, affectedRuntimes, affectedFrameworks, knownGaps) are quarantined there too. The default dry run previews the plan and exits non-zero while a repair would change capsule content or quarantine something; capsules that differ from the canonical layout only in YAML formatting are listed as formatting-only and do not fail the preview (--write normalizes them).

contractspec release check also reports advisory validation-entries warnings, which never fail the check: validation commands that read as labels, outcomes, placeholders or prose, commands that cite packages/ or examples/ paths missing from the workspace, and evidence that quotes a run of a command not listed in validation.commands.

Generative Core Preview Commands

Generative Core commands are thin CLI wrappers over workspace/bundle services. They expose graph and regeneration evidence without bypassing Connect review gates:

• contractspec graph inspect --json reads authored contracts and workspace evidence and reports schema-versioned counts, diagnostics, and artifact paths.
• contractspec graph export --json writes only canonical graph artifacts under generated/contractspec/graphs/** after deterministic artifact metadata is available.
• contractspec drift check --json classifies contract, code, generated artifact, docs, tests, and downstream-consumer drift for advisory CI before strict gates.
• contractspec generate plan --dry-run --json produces planned writes and provenance hashes without mutating files.
• contractspec generate apply --json and future repair apply flows require contractspec connect verify to allow or review the protected/generated write.

Shell Completion

Install the package so the contractspec executable is available on your PATH, then choose one of the supported shells:

contractspec completion script bash
contractspec completion script zsh
contractspec completion script fish

For managed installation, write the completion file and optionally patch the shell profile:

contractspec completion install bash
contractspec completion install zsh --write-profile
contractspec completion install fish

completion install always writes the generated completion script to a managed user config path. By default it does not edit startup files in non-interactive sessions. Use --write-profile to append an idempotent source block automatically.

Initialization Presets

contractspec init is now preset-driven. The shared setup layer owns the flow, and the CLI just forwards the preset and renders the resulting next steps.

# Generic ContractSpec workspace setup
contractspec init --preset core

# Enable ContractSpec Connect defaults and local artifacts
contractspec init --preset connect

# Prepare Builder for a managed runtime
contractspec init --preset builder-managed

# Prepare Builder for a local runtime
contractspec init --preset builder-local

# Prepare Builder for a hybrid runtime
contractspec init --preset builder-hybrid

In non-interactive mode, setup remains config-first: it writes .contractsrc.json, editor wiring, and tailored follow-up commands, but it does not call live Builder bootstrap APIs for you.

contractspec builder remains control-plane-backed for managed, local, and hybrid runtime flows. The CLI resolves the Builder API base URL from CONTRACTSPEC_API_BASE_URL, then .contractsrc.json builder.api.baseUrl, then https://api.contractspec.io, and reads auth from the configured control-plane token environment variable.

Builder execution aliases are additive shorthands over canonical execution-lane artifacts:

contractspec builder ralphone "Finish this change" --json
contractspec builder ultrawork "Parallelize this rollout" --json
contractspec builder ulw "Parallelize this rollout" --json
contractspec builder background --dry-run --json
contractspec builder tools doctor --json
contractspec builder tools diagnostics --json

ralphone starts the complete.persistent lane, while ultrawork and ulw start the team.coordinated lane. Persisted lane artifacts keep those canonical lane keys; aliases are only command-entry metadata.

Builder specs-pack dry-runs and Connect-gated apply

Utiliser contractspec builder pack when product intent lives in an external zip or folder and must be inspected before any repository mutation. Import, analyze, and plan emit structured JSON; implement remains dry-run only, while apply requires an explicit Connect decision and returns a fail-closed task ledger until approved Connect, replay, verifier, and test evidence are present.

contractspec builder pack import specs/autonomous-company-specs --json
contractspec builder pack analyze specs/autonomous-company-specs --json
contractspec builder pack plan specs/autonomous-company-specs --dry-run --json
contractspec builder pack implement specs/autonomous-company-specs --dry-run --json
contractspec builder pack apply specs/autonomous-company-specs --connect-decision connect:decision:1 --json

The pack report keeps external product intent separate from repository implementation reality, preserves source refs for README/AGENTS/prompts/examples/fixtures, surfaces ambiguity/readiness blockers, and recommends whole-pack versus layer-by-layer follow-up planning. The apply ledger records Contract Steward tasks before handwritten work, reviewed write scopes, required artifact kinds, and verifier blockers. Use $ralplan for reviewable implementation planning, $ralph for one-owner completion, and $team only when the Builder plan marks layers or package scopes safe to parallelize.

Translation diagnostics

Utiliser contractspec i18n check to run the reusable ContractSpec static translation diagnostics from the CLI. The command scans packages/**/src/i18n/catalogs by default, compares en/fr/es, and reports missing catalogs, missing or extra keys, blank values, ICU syntax failures, and placeholder parity issues.

contractspec i18n check
contractspec i18n check --format json
contractspec i18n check packages/platform/agents/ai-agent --base-locale en --locales en fr es

JSON output is the stable automation surface and contains { ok, summary, issues }. Optional .contractsrc.json i18n settings provide workspace defaults; command flags override config values.

Builder tmux Sessions

Utiliser contractspec builder tmux for full interactive Builder terminal work: REPLs, debuggers, TUIs, long-running dev servers, and local agent sessions that need a durable terminal instead of a one-shot command.

contractspec builder tmux doctor
contractspec builder tmux start --session builder-debug -- node --inspect
contractspec builder tmux attach --session builder-debug
contractspec builder tmux send --session builder-debug -- npm test
contractspec builder tmux capture --session builder-debug --lines 120
contractspec builder tmux stop --session builder-debug

Sessions default to contractspec-builder, use argv-based tmux calls, fail on existing sessions unless --reuse is set, and support JSON output for automation.

Builder agent lanes and diagnostics

Builder agent-lane commands keep persisted lane identity canonical even when operators use shorthand aliases:

Aliases are compatibility metadata, not new lane keys. Downstream state, release notes, workbench summaries, and replay artifacts should continue to branch on the canonical lane key and may display sourceAlias for human traceability.

Architecture

• Commandes (src/commands/) - Thin wrappers that call bundle services.
• Prompts (src/commands/create/wizards/) - Interactive UI using @inquirer/prompts.
• CLI setup (src/index.ts, src/cli.ts) - Commander.js configuration.
• Types (src/types.ts) - CLI-specific types.
• Services (@lssm-tech/bundle.workspace/services/) - Core use-cases.
• create.ts - Authored target creation logic.
• build.ts - Runtime/package materialization from authored targets.
• openapi.ts - OpenAPI export.
• registry.ts - Registry client.
• examples.ts - Examples management.

Public Entry Points

• Export ./run resolves through bun, node, default.

Local Commands

Managed CompanyOS historical approval databases may materialize a migration-007 decision while the database stores the exact legacy text value "1"; only that value or integer 1 is normalized at the database read boundary. Enroll and activate the human reviewer, resolve the signed approval, and replay before applying 007_approval_canonicalization_v1_integer. The migration command dry-runs by default; apply requires the exact migration ID through --confirm-migration, uses only CHANNEL_RUNTIME_DATABASE_URL, and ledger-replays as existing.

The tracked 001-006a chain preserves every historical ledger ID while adding the nonce table, issuer fields, and nonce RLS required by reviewer runtime queries. Authority provisioning is a separate dry-run-first command so reusable migrations contain no operator-specific trust record.

Managed CompanyOS Connect review uses contractspec connect review materialize --request <workspace-relative-json> before connect review enroll. Materialization accepts no caller scope or capability and only creates pending review authority. It is dry-run-first; apply requires --apply, the exact packet/source-diff confirmations, and CHANNEL_RUNTIME_DATABASE_URL (never the generic DATABASE_URL fallback). See docs/runbooks/connect-local-review.md.

• bun run dev — bun build ./src/cli.ts --outfile ./dist/cli.js --target node --watch
• bun run build — bun run prebuild && bun run build:types && bun run build:all
• bun run test — isolated CLI black-box checks, then bun test
• bun run lint — bun run lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist
• bun run build:bun — bun scripts/build-runtime-bundle.mjs bun (self-contained Bun bundle)
• bun run build:node — bun scripts/build-runtime-bundle.mjs node (self-contained Node bundle)
• bun run build:all — bun run build:bun && bun run build:node
• bun run build:types — tsgo --noEmit
• bun run dev:bun — bun build ./src/cli.ts --outfile ./dist/cli.bun.js --target bun --watch
• bun run test:watch — bun test --watch

Recent Updates

• Replace eslint+prettier by biomejs to optimize speed.
• Add table capabilities.
• Stability.
• Vnext ai-native.
• Add latest models and align defaults.
• Resolve lint and build errors in workspace bundle and integrations lib.

Notes

• Works alongside @lssm-tech/bundle.workspace, @lssm-tech/lib.ai-agent, @lssm-tech/lib.ai-providers, @lssm-tech/lib.contracts-integrations, @lssm-tech/lib.contracts-spec, ...
• contractspec apply has been retired; use contractspec generate for write-generation flows.

Contract Intelligence

The CLI includes a dry-run-first contractspec intelligence workflow for analyzing the current repository, exporting a portable bundle, importing it into another target, reconciling reality, and producing a selective import plan. analyze defaults to repo-derived evidence; pass --fixture <name> only for deterministic examples and regression fixtures. adopt --apply is intentionally blocked until ContractSpec Connect review and replay evidence exist. See docs/contract-intelligence.md.

contractspec list --json, contractspec integrity --json, and contractspec integrity --format mermaid are machine-output surfaces: stdout is reserved for the requested JSON or diagram, while human diagnostics belong in text mode or stderr. Discovery reports only authored contract/spec evidence and skips prompt/template implementation files that merely contain strings such as key:.

contractspec portfolio index|centralize|propagate|radar creates advisory portfolio envelopes over bundle refs without mutating shared cores or vertical projects. See docs/portfolio-centralization.md.

i18n diagnostics

Run static translation catalog diagnostics from a workspace or catalog directory:

contractspec i18n check [path] --locales en fr es --format json

The command reports reusable ContractSpec diagnostics for missing catalogs/keys, extra keys, blank values, malformed message shapes, invalid ICU syntax, and placeholder parity. JSON output is stable for CI and exits 1 for diagnostic failures or 2 for fatal config/import errors.

Restricted agent Markdown archives

These subcommands belong to the optional AI command contribution that provides agent; they are not registered by the base CLI alone. Configure that command pack before use.

contractspec agent migration archive --input selected.json --output archive.json validates explicitly selected Markdown content and writes a new owner-readable archive. The input contains id, agent scope, sourceRuntime (hermes or openclaw), sourceVersion, sourceRootRef, createdAt, and files entries with path and content. No home-directory scan or instruction execution occurs.

contractspec agent migration inspect --input archive.json verifies hashes and prints only counts and archive identity. Archive files contain private data; retain them in restricted storage. These commands do not submit proposals, promote memory, install skills, reconnect credentials, or activate schedules/channels.

The package-local Turbo configuration lists the CLI's public workspace build and typecheck dependencies explicitly. Its private Agent Host development dependency is used only by the source-level durable-operation parity test; compiling the host's deployable server is not a prerequisite for the CLI. The parity test and development dependency remain in place. When changing CLI workspace dependencies, update both task lists and run bun test scripts/delivery/cli-build-dependencies.test.mjs from the repository root; this check also rejects unexpected private dependencies.

Published CLI artifact verification

bun run verify:pack builds the actual CLI and verifies its canonical local publication projection without publishing. It requires every conditional root, bin, optional contribution and declaration target, plus exactly the emitted JavaScript dependency closure. Unreferenced chunks, source/test/map/cache files and unsafe archive members are rejected. Executable CLI targets retain the Node shebang; declaration files and imported contributions do not require a shebang. The installed Node/Bun consumer keeps runtime authority and network policy gates.