lib.cli-runtime

@lssm-tech/lib.cli-runtime

Deterministic command-pack discovery and registration for ContractSpec CLI hosts.

./workspace/analysis, ./workspace/types, and ./workspace/formatters provide the canonical source scanner, authoring path conventions, structure validator, spec data types, and Markdown/DocBlock rendering used by CLI packs. The analysis leaf also owns the existing semantic diff, snapshot, impact classification, and static DocBlock manifest extraction closure. These implementations retain the original workspace behavior; the TypeScript AST supplier reaches them through the typescript runtime port (see below). @lssm-tech/module.workspace forwards its existing exports to the same files. Use the explicit leaf exports when a consumer needs only parsing or rendering.

The runtime inspects only the consumer's direct dependencies and optionalDependencies. A package participates by declaring contractspec.commandPack metadata in its published package.json.

{
  "contractspec": {
    "commandPack": {
      "entry": "./dist/command-pack.js",
      "spec": {
        "schemaVersion": 1,
        "id": "contractspec-ai",
        "version": "1.0.0",
        "commands": ["agent", "chat", "llm", "mcp", "vibe"],
        "extends": ["build", "create", "validate"]
      }
    }
  }
}

discoverCommandPacks() applies .contractsrc include and exclude controls; exclusion wins. loadCommandPacks() loads every selected pack before registration, and registerCommandPacks() rejects command conflicts before any pack mutates the Commander program. Package-name ordering makes discovery and registration deterministic.

Utiliser createMissingCommandPackDiagnostic() to render an actionable install hint for known optional commands.

./host-program owns neutral Commander assembly. createCoreHostProgram() accepts explicit identity, core/inline registration, optional hints, and help bindings. createHostProgram() preserves that order, then discovers and loads direct dependency packs, rejects conflicts through the existing registration runtime, and reapplies host help after registration. Concrete command handlers, providers, version lookup, and parsing remain host/composition responsibilities. The existing CLI createCoreProgram() and createProgram(options) signatures remain compatible wrappers over this shared implementation.

./host-command-packs binds concrete registrations to one Commander program. Higher composers call bindHostCommandPackRegistrations() once; optional packs call registerHostCommandPack() with their exact pack ID. Missing/inherited bindings and rebinding are rejected when no portable declaration callback is supplied. Portable packs retain complete registration and help without a composer. Their action callbacks resolve explicitly bound, per-program actions only when selected; missing actions fail with missingHostBinding. The per-program binding store is process-shared, so a self-contained host bundle and separately installed packs observe the same bindings. Concrete registrations belong to higher composers, never to this generic runtime.

./inline-ai-dependencies owns the shared per-program mutable AI dependency object. Higher hosts retain complete structural dependency types and forward configuration synchronously. Existing command callbacks keep the same object and observe later bindings; lookup neither discovers nor invokes a supplier. Its state is process-shared across bundled and installed runtime copies.

Generic host ports

./ports/fs and ./ports/logger expose the canonical filesystem and logger interface closure previously owned by the workspace bundle. These type-only entries preserve the complete existing method and optional-property shapes without loading Commander. The generic concrete adapters and complete adapter aggregate now live in the ./workspace entries; product composition remains higher.

./ports/runtime holds the three runtime ports through which this package reaches suppliers it does not depend on:

@lssm-tech/bundle.workspace binds all three when its root entry is imported and whenever it creates a program, so every ContractSpec CLI host (contractspec, sdd, the app CLI) and every library host of that bundle (the VS Code extension, the JetBrains bridge) is covered. Other programmatic callers, including direct callers of the @lssm-tech/module.workspace DocBlock analysis forwards, bind them first:

import { bindCliRuntimePorts } from '@lssm-tech/lib.cli-runtime/ports/runtime';
import * as typescript from '@lssm-tech/lib.typescript-runtime';

bindCliRuntimePorts({ typescript });

An unbound port throws CliRuntimePortError (code: 'missingHostBinding') naming the port and its consumer. Bindings are process-shared, so a bundled host copy and separately installed command packs see the same suppliers. Any code in the process can rebind a port, so governance-critical callers such as the Connect hook pass the channel to createConnectControlPlaneRuntime explicitly.

Shared command helper compatibility

The additive ./connect/io and ./utils/errors entries own the existing CLI stdin, actor-reference, argument-validation, verdict-exit-code and error-message helpers. Their signatures, explicit environment keys and error behavior are unchanged. The workspace CLI's previous paths forward to these same functions. Moving these helpers does not authorize Connect decisions or runtime effects.

The narrow ./workspace/detection, ./utils/config, ./logging/application and ./connect/catalog-fetch entries retain the existing concrete workspace detection, config precedence, logger identities and explicit catalog fetch behavior. ./example-catalog/registry supplies metadata-only discovery through the original Foundation ExampleRegistry class, and ./example-catalog/stub (createExampleStubPlan) plans the lightweight .contractspec/examples/<key> manifest/README stub that hosts write. Runnable examples and preview imports stay in examples/registry; production command discovery loads only the generated literals. scripts/generate-example-registry.ts owns those literals and writes them to this canonical owner, while retaining the preview outputs in the example registry. No catalog entries have changed in this relocation.

./workspace/templates/defaults (generateDefaultSpecContent) owns the default scaffold for every file-posture authoring target. The CLI create command, the IDE wizards and the MCP contracts.create tool share it; bundle.workspace re-exports it. Each scaffold parses as TypeScript and passes validateSpecStructure (the presentation scaffold still uses the legacy content block). ./workspace/templates/visual-scenario.template owns generateVisualScenarioSpec; module.workspace forwards to it.

Workspace authoring runtime ownership

Compatibility: generic concrete Node filesystem/git/watcher/logger adapters, authored-module loading, discovery and deterministic authoring services move into ./workspace lower entries. Existing bundle entries forward to those same implementations and preserve defaults and signatures. No provider or product command composition moves into this closure. Scanner and render dependencies must use the canonical lower source owner; no module or bundle back-edge is admitted. Source migration requires source-bound adoption and affected-consumer qualification before acceptance.

The generic setup managed-Markdown helpers, AGENTS/usage targets and config generators also use the lower ./workspace/services/setup owner. Compatibility forwards preserve markers, user-owned content, package/workspace scope and emitted guidance byte-for-byte. The schema reference remains relative to explicitly supplied configRoot/workspaceRoot and names the existing contractspec package artifact; relocation adds no source or generated-schema fallback.

./workspace/services/connect (also ./workspace/services/connect/index) owns Connect host-hook run modes: run-mode resolution from the host permission mode, connect.runModes and operator grants (run-mode), action criticality grading with operator-only path and shell-command detection (run-mode-criticality), and the worktree-bound grant store (run-mode-grant). Generated AGENTS/usage guidance tells agents that connect mode set|clear and hook settings are operator-only.

./workspace-services/llm/index and ./workspace-services/vibe/index own the original reusable LLM authoring and workflow services. ./authoring-mcp/* owns the original contracts, CLI, documentation, and internal MCP builders and transport helpers. Existing workspace and library bundle imports forward to these same functions and registries. Concrete AI providers, command actions, and environment-bound operation clients remain in their integration owners.

Portable filesystem and logging contracts now have one canonical owner in @lssm-tech/lib.utils-typescript/ports/fs and /ports/logger. Their complete interfaces are unchanged. Existing CLI /ports/fs and /ports/logger imports remain compatible type exports; Builder delivery uses the portable contracts directly and no longer depends on the CLI host.

Adoption catalog selection ignores version build metadata when comparing release precedence. For the same release, registry, installed, local mirror, and embedded candidates retain their existing source priority. Inventory digests, hash validation, split-brain detection, and stale diagnostics remain unchanged.

The Node filesystem adapter schedules overlapping glob traversals in FIFO order when running under Bun on Windows. Each adapter owns its queue; patterns, options, sorted discovery results and rejection values remain unchanged. Node and other platforms retain concurrent traversal. This bounds overlapping native filesystem traversal without narrowing workspace discovery.