@opensip-cli/core 0.1.0

package/dist/tools/command-spec.d.ts

@@ -0,0 +1,211 @@
+/**
+ * @fileoverview Command-plane types (launch, north-star §5.4).
+ *
+ * The declarative command surface a tool exports so the **host** can mount it
+ * — replacing each tool's raw-Commander access (`program.command(...).option(...).
+ * action(...)`). A tool returns typed {@link CommandSpec}s; the host's
+ * `mountCommandSpec` (cli, Phase 1) translates them into Commander commands,
+ * applies the common flags, declares the options/args, and owns the
+ * parse → handler → dispatch → error → exit pipeline.
+ *
+ * Why this lives in **core**: these are kernel-level contract types, declared
+ * beside the {@link Tool} contract. core stays Commander-free — there is no
+ * `commander` import here, only plain data shapes. The Commander-touching
+ * mounting runtime lives in cli; the Commander-touching `applyCommonFlags`
+ * runtime lives in contracts. Only the pure KEY TYPE ({@link CommonFlagKey})
+ * lives here.
+ *
+ * `OptionSpec` is grounded in the *real* first-party flag corpus (graph 26 +
+ * fit 10 + sim 1 + host commands), enumerated in the Phase 0 flag-corpus table.
+ * Every flag shape maps to a field below — there is no raw-Commander escape
+ * hatch by design (the the "one command surface" invariant). Any future flag
+ * that cannot be expressed is an OptionSpec EXTENSION, never an escape.
+ */
+/**
+ * The canonical common-flag keys shared across tool run commands (ADR-0021).
+ *
+ * The KEY TYPE lives here in core so {@link CommandSpec.commonFlags} can be
+ * statically typed at the kernel layer without core importing contracts
+ * (a layering inversion forbidden by dependency-cruiser). The Commander-touching
+ * runtime that turns these keys into `.option(...)` calls — `applyCommonFlags`,
+ * the `commonFlags` registry, and `CommonFlagSpec` — stays in
+ * `@opensip-cli/contracts/cli-flags`, which re-exports this type so existing
+ * `import { CommonFlagKey } from '@opensip-cli/contracts'` sites keep working.
+ *
+ * Keep this union in lockstep with the `commonFlags` registry keys in
+ * contracts (the `cross-tool-flag-parity` check guards the run-command set).
+ */
+export type CommonFlagKey = 'json' | 'cwd' | 'quiet' | 'verbose' | 'debug' | 'reportTo' | 'apiKey' | 'open';
+/** The full set of {@link CommonFlagKey} values — the validation source for `defineCommand`. */
+export declare const COMMON_FLAG_KEYS: readonly CommonFlagKey[];
+/**
+ * A single tool-specific option declaration.
+ *
+ * Expresses every shape in the first-party corpus:
+ * - boolean (`--gate-save`, default `false`): `{ flag, default: false }`
+ * - negatable (`--no-cache`): `{ flag: '--no-cache', negatable: true }`
+ * - value (`--recipe <name>`, `--profile <path>`): `{ flag, value: '<name>' }`
+ * - value + default (`--resolution <mode>` default `exact`): add `default`
+ * - choices (`--resolution` ∈ `exact|fast`): add `choices`
+ * - custom coercion (`--concurrency <n>` → Number; `--exclude <slug>` repeatable;
+ *   `--older-than <days>` validated): declared as a pure `parse`
+ * - short alias (`-y, --yes`, `-q, --quiet`): carried verbatim in `flag`
+ * - required value (`--out <path>` via `.requiredOption`): `{ value, required: true }`
+ */
+export interface OptionSpec {
+    /**
+     * The Commander flag string, including any short alias — e.g. `'--no-cache'`,
+     * `'--resolution'`, `'-y, --yes'`. Does NOT include the value placeholder; put
+     * that in {@link value}.
+     */
+    readonly flag: string;
+    /**
+     * The value placeholder (`'<mode>'`, `'<path>'`, `'[path]'`). Presence marks
+     * this as a value-taking option; absence marks it boolean. Optional-value
+     * placeholders use square brackets (`'[path]'`), matching Commander.
+     */
+    readonly value?: string;
+    /** Help text (the single source of truth for this option's description). */
+    readonly description: string;
+    /**
+     * Literal default applied at mount. A boolean default models a boolean flag's
+     * resting state (`false`); a string default models a value flag's fallback
+     * (`'exact'`). Computed-per-invocation defaults (e.g. `process.cwd()`) belong
+     * to {@link CommonFlagKey} common flags, not here.
+     */
+    readonly default?: string | boolean;
+    /**
+     * Repeatable/array default (e.g. `--exclude`, `--changed-file` accumulate into
+     * `string[]`). Kept distinct from {@link default} so the mount layer can pass a
+     * fresh array as Commander's `defaultValue` alongside a {@link parse} reducer.
+     */
+    readonly arrayDefault?: readonly string[];
+    /** `--no-cache` style negatable boolean. The flag already carries the `--no-` prefix. */
+    readonly negatable?: boolean;
+    /** Variadic value option (rare for options; carried for completeness). */
+    readonly variadic?: boolean;
+    /** Whether the option is required (`.requiredOption`). Value options only. */
+    readonly required?: boolean;
+    /** Declared allowed values — the mount layer enforces membership (was handler-side, e.g. `--resolution`). */
+    readonly choices?: readonly string[];
+    /**
+     * Declared pure coercion/validation. Covers Commander's `(value, previous) =>
+     * next` reducer shape used by repeatable flags (`--exclude`, `--changed-file`)
+     * and scalar parsers (`--concurrency` → Number, `--older-than` → validated int).
+     * MUST be pure — no I/O, no scope reads. Runs at parse time in the mount layer.
+     */
+    readonly parse?: (raw: string, previous: unknown) => unknown;
+}
+/** A positional argument declaration (`.argument(...)`). */
+export interface ArgSpec {
+    /** The argument name as it appears in help (`'paths'`, `'name'`, `'shell'`). */
+    readonly name: string;
+    /** Help text for the argument. */
+    readonly description: string;
+    /** Variadic positional (`[paths...]` / `<paths...>`). */
+    readonly variadic?: boolean;
+    /** Optional positional (`[name]` rather than `<name>`). */
+    readonly optional?: boolean;
+}
+/**
+ * What the handler returns and how the host renders it through the single
+ * dispatch seam (Phase 1). The launch `CommandOutcome` swap happens at this seam
+ * without changing the handler contract.
+ *
+ * - `signal-envelope` — handler yields a `SignalEnvelope` (fit/graph runs); the
+ *   host renders it (`--json` → emitEnvelope, else render).
+ * - `command-result` — handler yields a `CommandResult` variant (list/export/host).
+ * - `raw-stream` — the host renders NOTHING; the handler owns its entire output
+ *   surface. Covers two cases: (a) a handler that writes directly to stdout/a
+ *   file (completion script, SARIF/baseline export, shard-worker); and (b) a
+ *   handler that owns a runtime-conditional render+egress flow no single static
+ *   mode captures — e.g. `sim`, which branches between an interactive Ink live
+ *   view and a static render/JSON path depending on the TTY, then performs its
+ *   own cloud egress, report auto-open, and exit-code decision. In both cases
+ *   the handler returns `void` and the host does not touch the stream.
+ * - `live-view` — interactive Ink view path (graph/fit live default on a TTY)
+ *   where the command is UNCONDITIONALLY a live view; the host dispatches to the
+ *   tool's registered renderer via `renderLive(name, …)`.
+ */
+export type CommandOutputMode = 'signal-envelope' | 'command-result' | 'raw-stream' | 'live-view';
+/**
+ * Narrow categories for the `raw-stream` escape hatch. A raw-stream command must
+ * explain why the host-owned render seam cannot handle its output.
+ */
+export type RawStreamReason = 'completion-script' | 'file-export' | 'worker-ipc' | 'runtime-render-dispatch' | 'session-replay' | 'diagnostic-gate' | 'lookup';
+export declare const RAW_STREAM_REASONS: readonly RawStreamReason[];
+/**
+ * Whether the command needs a resolved project scope (RunScope project context,
+ * datastore, recipe config) entered before the handler runs.
+ *
+ * - `project` — needs the entered RunScope (every run/list/export command).
+ * - `none` — scope-agnostic (e.g. `completion`, `configure`).
+ */
+export type CommandScopeRequirement = 'project' | 'none';
+/**
+ * The context the host passes to a handler when it invokes it. The concrete
+ * shape is finalized in Phase 1 (mounting) — it carries the per-invocation scope
+ * and the output emitters (`render` / `emitJson` / `renderLive` / `writeSarif` /
+ * `deliverSignals` / `setExitCode`), i.e. today's `ToolCliContext` surface minus
+ * raw `program` access.
+ *
+ * Declared here as an empty marker interface (NOT a bare `unknown` alias): core
+ * stays Commander-free and does not pin the cli/contracts-owned context shape, so
+ * the kernel cannot name the concrete emitters. Handlers parameterize `TCtx` with
+ * the real context type (`ToolCliContext`) at the cli/tool layer; this marker is
+ * the unconstrained default.
+ */
+export type CommandContext = Readonly<Record<string, unknown>>;
+/**
+ * A command handler: pure-ish business logic the host invokes after parsing.
+ * Receives the parsed, typed options and the host {@link CommandContext}; returns
+ * whatever the declared {@link CommandSpec.output} mode dispatches (sync or a
+ * promise), or void for `raw-stream` / `live-view`, which side-effect directly.
+ */
+export type CommandHandler<TOpts = unknown, TCtx = CommandContext> = (opts: TOpts, ctx: TCtx) => unknown;
+/**
+ * The declarative spec a tool exports for one command. The host mounts it; the
+ * tool never touches Commander.
+ */
+export interface CommandSpec<TOpts = unknown, TCtx = CommandContext> {
+    /** The command name as typed on the CLI (`'graph'`, `'fit-list'`). */
+    readonly name: string;
+    /** One-line description shown in help. */
+    readonly description: string;
+    /** Alternate names (`'inspect'` for `'analyze'`). */
+    readonly aliases?: readonly string[];
+    /** The common flags this command exposes, applied via `applyCommonFlags` at mount. */
+    readonly commonFlags: readonly CommonFlagKey[];
+    /** Tool-specific options. */
+    readonly options?: readonly OptionSpec[];
+    /** Positional arguments (declaration order is mount order). */
+    readonly args?: readonly ArgSpec[];
+    /** Whether the host enters a project scope before the handler. */
+    readonly scope: CommandScopeRequirement;
+    /** How the host dispatches the handler's return value. */
+    readonly output: CommandOutputMode;
+    /** Required when `output` is `raw-stream`, forbidden otherwise. */
+    readonly rawStreamReason?: RawStreamReason;
+    /** The business-logic handler the host invokes after parse. */
+    readonly handler: CommandHandler<TOpts, TCtx>;
+}
+/**
+ * Identity helper that validates and returns a {@link CommandSpec}. Mirrors
+ * `defineCheck` / `defineTool`: returns the value so the caller registers it
+ * explicitly (no module-import side effects). Validation is structural and pure
+ * — it catches authoring mistakes at construction time:
+ *
+ * - `name` non-empty
+ * - `description` non-empty
+ * - every `commonFlags` key is a valid {@link CommonFlagKey}
+ * - no duplicate `commonFlags` keys
+ * - `handler` is a function
+ *
+ * Deeper, Commander-coupled validation (e.g. choices ⊆ enum, flag-string syntax)
+ * happens at mount in cli — core cannot import Commander.
+ *
+ * @throws {Error | TypeError} When `name`/`description` is empty, `handler` is not
+ *   a function, or `commonFlags` contains an unknown or duplicate key.
+ */
+export declare function defineCommand<TOpts = unknown, TCtx = CommandContext>(spec: CommandSpec<TOpts, TCtx>): CommandSpec<TOpts, TCtx>;
+//# sourceMappingURL=command-spec.d.ts.map

package/dist/tools/command-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-spec.d.ts","sourceRoot":"","sources":["../../src/tools/command-spec.ts"],"names":[],"mappings":"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"}

package/dist/tools/command-spec.js

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Command-plane types (launch, north-star §5.4).
+ *
+ * The declarative command surface a tool exports so the **host** can mount it
+ * — replacing each tool's raw-Commander access (`program.command(...).option(...).
+ * action(...)`). A tool returns typed {@link CommandSpec}s; the host's
+ * `mountCommandSpec` (cli, Phase 1) translates them into Commander commands,
+ * applies the common flags, declares the options/args, and owns the
+ * parse → handler → dispatch → error → exit pipeline.
+ *
+ * Why this lives in **core**: these are kernel-level contract types, declared
+ * beside the {@link Tool} contract. core stays Commander-free — there is no
+ * `commander` import here, only plain data shapes. The Commander-touching
+ * mounting runtime lives in cli; the Commander-touching `applyCommonFlags`
+ * runtime lives in contracts. Only the pure KEY TYPE ({@link CommonFlagKey})
+ * lives here.
+ *
+ * `OptionSpec` is grounded in the *real* first-party flag corpus (graph 26 +
+ * fit 10 + sim 1 + host commands), enumerated in the Phase 0 flag-corpus table.
+ * Every flag shape maps to a field below — there is no raw-Commander escape
+ * hatch by design (the the "one command surface" invariant). Any future flag
+ * that cannot be expressed is an OptionSpec EXTENSION, never an escape.
+ */
+/** The full set of {@link CommonFlagKey} values — the validation source for `defineCommand`. */
+export const COMMON_FLAG_KEYS = [
+    'json',
+    'cwd',
+    'quiet',
+    'verbose',
+    'debug',
+    'reportTo',
+    'apiKey',
+    'open',
+];
+export const RAW_STREAM_REASONS = [
+    'completion-script',
+    'file-export',
+    'worker-ipc',
+    'runtime-render-dispatch',
+    'session-replay',
+    'diagnostic-gate',
+    'lookup',
+];
+/**
+ * Identity helper that validates and returns a {@link CommandSpec}. Mirrors
+ * `defineCheck` / `defineTool`: returns the value so the caller registers it
+ * explicitly (no module-import side effects). Validation is structural and pure
+ * — it catches authoring mistakes at construction time:
+ *
+ * - `name` non-empty
+ * - `description` non-empty
+ * - every `commonFlags` key is a valid {@link CommonFlagKey}
+ * - no duplicate `commonFlags` keys
+ * - `handler` is a function
+ *
+ * Deeper, Commander-coupled validation (e.g. choices ⊆ enum, flag-string syntax)
+ * happens at mount in cli — core cannot import Commander.
+ *
+ * @throws {Error | TypeError} When `name`/`description` is empty, `handler` is not
+ *   a function, or `commonFlags` contains an unknown or duplicate key.
+ */
+export function defineCommand(spec) {
+    if (spec.name.trim() === '') {
+        throw new Error('defineCommand: `name` must be a non-empty string.');
+    }
+    if (spec.description.trim() === '') {
+        throw new Error(`defineCommand: command '${spec.name}' must have a non-empty description.`);
+    }
+    if (typeof spec.handler !== 'function') {
+        throw new TypeError(`defineCommand: command '${spec.name}' must have a function handler.`);
+    }
+    validateRawStreamDeclaration(spec);
+    const seen = new Set();
+    for (const key of spec.commonFlags) {
+        if (!COMMON_FLAG_KEYS.includes(key)) {
+            throw new Error(`defineCommand: command '${spec.name}' declares unknown common flag '${String(key)}'. ` +
+                `Valid keys: ${COMMON_FLAG_KEYS.join(', ')}.`);
+        }
+        if (seen.has(key)) {
+            throw new Error(`defineCommand: command '${spec.name}' declares duplicate common flag '${key}'.`);
+        }
+        seen.add(key);
+    }
+    return spec;
+}
+/**
+ * Validate that a `raw-stream` command documents why it owns its own output.
+ *
+ * @throws {Error} when `output` is `'raw-stream'` but no `rawStreamReason` is
+ *   declared (or the reason is not a recognized value).
+ */
+function validateRawStreamDeclaration(spec) {
+    if (spec.output === 'raw-stream') {
+        if (spec.rawStreamReason === undefined) {
+            throw new Error(`defineCommand: command '${spec.name}' declares output 'raw-stream' without ` +
+                'rawStreamReason. Raw-stream commands must document why the host render seam ' +
+                'cannot own their output.');
+        }
+        if (!RAW_STREAM_REASONS.includes(spec.rawStreamReason)) {
+            throw new Error(`defineCommand: command '${spec.name}' declares unknown rawStreamReason ` +
+                `'${String(spec.rawStreamReason)}'. Valid reasons: ${RAW_STREAM_REASONS.join(', ')}.`);
+        }
+        return;
+    }
+    if (spec.rawStreamReason !== undefined) {
+        throw new Error(`defineCommand: command '${spec.name}' declares rawStreamReason but output is ` +
+            `'${spec.output}'. rawStreamReason is only valid for raw-stream commands.`);
+    }
+}
+//# sourceMappingURL=command-spec.js.map

package/dist/tools/command-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-spec.js","sourceRoot":"","sources":["../../src/tools/command-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AA0BH,gGAAgG;AAChG,MAAM,CAAC,MAAM,gBAAgB,GAA6B;IACxD,MAAM;IACN,KAAK;IACL,OAAO;IACP,SAAS;IACT,OAAO;IACP,UAAU;IACV,QAAQ;IACR,MAAM;CACE,CAAC;AA4GX,MAAM,CAAC,MAAM,kBAAkB,GAA+B;IAC5D,mBAAmB;IACnB,aAAa;IACb,YAAY;IACZ,yBAAyB;IACzB,gBAAgB;IAChB,iBAAiB;IACjB,QAAQ;CACT,CAAC;AAgEF;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAC3B,IAA8B;IAE9B,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,CAAC,IAAI,sCAAsC,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACvC,MAAM,IAAI,SAAS,CAAC,2BAA2B,IAAI,CAAC,IAAI,iCAAiC,CAAC,CAAC;IAC7F,CAAC;IACD,4BAA4B,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAiB,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,IAAI,mCAAmC,MAAM,CAAC,GAAG,CAAC,KAAK;gBACrF,eAAe,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAChD,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,IAAI,qCAAqC,GAAG,IAAI,CACjF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,SAAS,4BAA4B,CAAC,IAIrC;IACC,IAAI,IAAI,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;QACjC,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,IAAI,yCAAyC;gBAC3E,8EAA8E;gBAC9E,0BAA0B,CAC7B,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,IAAI,qCAAqC;gBACvE,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,qBAAqB,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACxF,CAAC;QACJ,CAAC;QACD,OAAO;IACT,CAAC;IACD,IAAI,IAAI,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,2BAA2B,IAAI,CAAC,IAAI,2CAA2C;YAC7E,IAAI,IAAI,CAAC,MAAM,2DAA2D,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/tools/compatibility.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview The single pure compatibility gate.
+ *
+ * One decision function the bundled and external admission paths share
+ * (north-star §5.2): given the epoch a tool was compiled against
+ * (`apiVersion`) and the epoch the engine implements
+ * (`PLUGIN_API_VERSION`), return a `CompatibilityVerdict` — pure data.
+ * The loader (Phase 2) and CLI (Phase 3) act on the verdict; this module
+ * never logs, never exits, never touches the filesystem.
+ *
+ * Policy for the launch API:
+ *   - `apiVersion` omitted ⇒ **incompatible**. A tool MUST declare the epoch
+ *     it was compiled against; an unversioned plugin input is no longer admitted
+ *     (north-star Principle 5 — version the inputs).
+ *   - `apiVersion === engine` ⇒ compatible.
+ *   - otherwise ⇒ incompatible, carrying both integers + a human reason
+ *     (future vs. past epoch).
+ */
+/**
+ * The outcome of the compatibility gate — pure data the caller acts on.
+ *
+ *   - `compatible`   — admit the tool.
+ *   - `incompatible` — reject; carries the declared + engine epochs and a
+ *                      human-readable reason for diagnostics / logs.
+ */
+export type CompatibilityVerdict = {
+    readonly kind: 'compatible';
+} | {
+    readonly kind: 'incompatible';
+    readonly declared: number;
+    readonly engine: number;
+    readonly reason: string;
+};
+/**
+ * Decide whether a tool declaring `apiVersion` is compatible with the
+ * engine epoch.
+ *
+ * @param apiVersion The epoch the tool was compiled against, or `undefined`
+ *   (a missing epoch is incompatible).
+ * @param engine The epoch the running engine implements. Defaults to
+ *   `PLUGIN_API_VERSION`; overridable for tests / as-if-external probes.
+ * @returns A `CompatibilityVerdict` — never throws.
+ */
+export declare function checkCompatibility(apiVersion: number | undefined, engine?: number): CompatibilityVerdict;
+//# sourceMappingURL=compatibility.d.ts.map

package/dist/tools/compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../../src/tools/compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;CAAE,GAC/B;IACE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEN;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,GAAE,MAA2B,GAClC,oBAAoB,CAsBtB"}

package/dist/tools/compatibility.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview The single pure compatibility gate.
+ *
+ * One decision function the bundled and external admission paths share
+ * (north-star §5.2): given the epoch a tool was compiled against
+ * (`apiVersion`) and the epoch the engine implements
+ * (`PLUGIN_API_VERSION`), return a `CompatibilityVerdict` — pure data.
+ * The loader (Phase 2) and CLI (Phase 3) act on the verdict; this module
+ * never logs, never exits, never touches the filesystem.
+ *
+ * Policy for the launch API:
+ *   - `apiVersion` omitted ⇒ **incompatible**. A tool MUST declare the epoch
+ *     it was compiled against; an unversioned plugin input is no longer admitted
+ *     (north-star Principle 5 — version the inputs).
+ *   - `apiVersion === engine` ⇒ compatible.
+ *   - otherwise ⇒ incompatible, carrying both integers + a human reason
+ *     (future vs. past epoch).
+ */
+import { PLUGIN_API_VERSION } from './manifest.js';
+/**
+ * Decide whether a tool declaring `apiVersion` is compatible with the
+ * engine epoch.
+ *
+ * @param apiVersion The epoch the tool was compiled against, or `undefined`
+ *   (a missing epoch is incompatible).
+ * @param engine The epoch the running engine implements. Defaults to
+ *   `PLUGIN_API_VERSION`; overridable for tests / as-if-external probes.
+ * @returns A `CompatibilityVerdict` — never throws.
+ */
+export function checkCompatibility(apiVersion, engine = PLUGIN_API_VERSION) {
+    // A tool that declares no `apiVersion` is incompatible: unversioned plugin
+    // input is not admitted off the marker alone.
+    if (apiVersion === undefined) {
+        return {
+            kind: 'incompatible',
+            declared: Number.NaN,
+            engine,
+            reason: `tool declares no plugin apiVersion; declare \`apiVersion: ${engine}\` in its manifest`,
+        };
+    }
+    if (apiVersion === engine) {
+        return { kind: 'compatible' };
+    }
+    const reason = apiVersion > engine
+        ? `tool targets plugin API v${apiVersion} but this engine implements v${engine}; upgrade OpenSIP CLI to load it`
+        : `tool targets plugin API v${apiVersion} which this engine (v${engine}) no longer supports; upgrade the tool`;
+    return { kind: 'incompatible', declared: apiVersion, engine, reason };
+}
+//# sourceMappingURL=compatibility.js.map

package/dist/tools/compatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compatibility.js","sourceRoot":"","sources":["../../src/tools/compatibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAkBnD;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAA8B,EAC9B,SAAiB,kBAAkB;IAEnC,2EAA2E;IAC3E,8CAA8C;IAC9C,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,QAAQ,EAAE,MAAM,CAAC,GAAG;YACpB,MAAM;YACN,MAAM,EAAE,6DAA6D,MAAM,oBAAoB;SAChG,CAAC;IACJ,CAAC;IAED,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,MAAM,GACV,UAAU,GAAG,MAAM;QACjB,CAAC,CAAC,4BAA4B,UAAU,gCAAgC,MAAM,kCAAkC;QAChH,CAAC,CAAC,4BAA4B,UAAU,wBAAwB,MAAM,wCAAwC,CAAC;IAEnH,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACxE,CAAC"}

package/dist/tools/ids.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical first-party tool id registry.
+ *
+ * Two distinct forms exist for historical reasons:
+ *
+ *   - **Long form** (`'fitness' | 'simulation' | 'graph'`) — used by
+ *     `Tool.metadata.id` and most human-facing copy. Each tool
+ *     self-identifies with this form.
+ *
+ *   - **Short form** (`'fit' | 'sim' | 'graph'`) — used as the storage
+ *     discriminator in `StoredSession.tool`, `SignalEnvelope.tool`,
+ *     path-domain names (`<project>/opensip-cli/fit/`,
+ *     `<project>/opensip-cli/sim/`), and CLI subcommand names. SQL
+ *     rows, generated dashboards, and on-disk layout all use it.
+ *
+ * Prior to audit-round-3 Finding H, the same literal union appeared
+ * inline in 5+ places (`StoredSession.tool`, the JSON output `tool`,
+ * `PathDomain`, `VALID_TOOLS` set, etc.) with no shared source of
+ * truth. Adding a 4th first-party tool risked editing N − 1 sites and
+ * silently passing tests until a SQL row carried an unknown
+ * discriminator at runtime.
+ *
+ * Third-party tools (registered via `discoverToolPackages`) MAY use
+ * any short / long id. The unions below are first-party-only; the
+ * persistence + path layers do NOT today store rows for third-party
+ * tools (they'd need an extension).
+ */
+/** First-party canonical short ids — storage/output discriminators. */
+export declare const TOOL_SHORT_IDS: readonly ["fit", "sim", "graph"];
+/** First-party short id type (storage discriminator). */
+export type ToolShortId = (typeof TOOL_SHORT_IDS)[number];
+/** First-party canonical long ids — `Tool.metadata.id` values. */
+export declare const TOOL_LONG_IDS: readonly ["fitness", "simulation", "graph"];
+/** First-party long id type (Tool metadata). */
+export type ToolLongId = (typeof TOOL_LONG_IDS)[number];
+/** Canonical long → short mapping for the first-party tools. */
+export declare const TOOL_LONG_TO_SHORT: {
+    readonly fitness: "fit";
+    readonly simulation: "sim";
+    readonly graph: "graph";
+};
+/** Canonical short → long mapping (inverse of `TOOL_LONG_TO_SHORT`). */
+export declare const TOOL_SHORT_TO_LONG: {
+    readonly fit: "fitness";
+    readonly sim: "simulation";
+    readonly graph: "graph";
+};
+/**
+ * Runtime predicate for short ids. Use at trust boundaries where a
+ * value crosses from `unknown` into the typed domain — most notably
+ * `SessionRepo.hydrateSession` validating the SQLite `tool` column,
+ * which has no CHECK constraint.
+ */
+export declare function isToolShortId(value: unknown): value is ToolShortId;
+/**
+ * Runtime predicate for long ids. Use where a value claims to be a
+ * `Tool.metadata.id` for a first-party tool (e.g. cross-checking the
+ * long form a tool reported against the canonical mapping).
+ */
+export declare function isToolLongId(value: unknown): value is ToolLongId;
+//# sourceMappingURL=ids.d.ts.map

package/dist/tools/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/tools/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,uEAAuE;AACvE,eAAO,MAAM,cAAc,kCAAmC,CAAC;AAE/D,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,kEAAkE;AAClE,eAAO,MAAM,aAAa,6CAA8C,CAAC;AAEzE,gDAAgD;AAChD,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAExD,gEAAgE;AAChE,eAAO,MAAM,kBAAkB;;;;CAIqB,CAAC;AAErD,wEAAwE;AACxE,eAAO,MAAM,kBAAkB;;;;CAIqB,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE"}

package/dist/tools/ids.js

@@ -0,0 +1,61 @@
+/**
+ * Canonical first-party tool id registry.
+ *
+ * Two distinct forms exist for historical reasons:
+ *
+ *   - **Long form** (`'fitness' | 'simulation' | 'graph'`) — used by
+ *     `Tool.metadata.id` and most human-facing copy. Each tool
+ *     self-identifies with this form.
+ *
+ *   - **Short form** (`'fit' | 'sim' | 'graph'`) — used as the storage
+ *     discriminator in `StoredSession.tool`, `SignalEnvelope.tool`,
+ *     path-domain names (`<project>/opensip-cli/fit/`,
+ *     `<project>/opensip-cli/sim/`), and CLI subcommand names. SQL
+ *     rows, generated dashboards, and on-disk layout all use it.
+ *
+ * Prior to audit-round-3 Finding H, the same literal union appeared
+ * inline in 5+ places (`StoredSession.tool`, the JSON output `tool`,
+ * `PathDomain`, `VALID_TOOLS` set, etc.) with no shared source of
+ * truth. Adding a 4th first-party tool risked editing N − 1 sites and
+ * silently passing tests until a SQL row carried an unknown
+ * discriminator at runtime.
+ *
+ * Third-party tools (registered via `discoverToolPackages`) MAY use
+ * any short / long id. The unions below are first-party-only; the
+ * persistence + path layers do NOT today store rows for third-party
+ * tools (they'd need an extension).
+ */
+/** First-party canonical short ids — storage/output discriminators. */
+export const TOOL_SHORT_IDS = ['fit', 'sim', 'graph'];
+/** First-party canonical long ids — `Tool.metadata.id` values. */
+export const TOOL_LONG_IDS = ['fitness', 'simulation', 'graph'];
+/** Canonical long → short mapping for the first-party tools. */
+export const TOOL_LONG_TO_SHORT = {
+    fitness: 'fit',
+    simulation: 'sim',
+    graph: 'graph',
+};
+/** Canonical short → long mapping (inverse of `TOOL_LONG_TO_SHORT`). */
+export const TOOL_SHORT_TO_LONG = {
+    fit: 'fitness',
+    sim: 'simulation',
+    graph: 'graph',
+};
+/**
+ * Runtime predicate for short ids. Use at trust boundaries where a
+ * value crosses from `unknown` into the typed domain — most notably
+ * `SessionRepo.hydrateSession` validating the SQLite `tool` column,
+ * which has no CHECK constraint.
+ */
+export function isToolShortId(value) {
+    return typeof value === 'string' && TOOL_SHORT_IDS.includes(value);
+}
+/**
+ * Runtime predicate for long ids. Use where a value claims to be a
+ * `Tool.metadata.id` for a first-party tool (e.g. cross-checking the
+ * long form a tool reported against the canonical mapping).
+ */
+export function isToolLongId(value) {
+    return typeof value === 'string' && TOOL_LONG_IDS.includes(value);
+}
+//# sourceMappingURL=ids.js.map

package/dist/tools/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/tools/ids.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,uEAAuE;AACvE,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAU,CAAC;AAK/D,kEAAkE;AAClE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,CAAU,CAAC;AAKzE,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,OAAO,EAAE,KAAK;IACd,UAAU,EAAE,KAAK;IACjB,KAAK,EAAE,OAAO;CACoC,CAAC;AAErD,wEAAwE;AACxE,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,GAAG,EAAE,SAAS;IACd,GAAG,EAAE,YAAY;IACjB,KAAK,EAAE,OAAO;CACoC,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,cAAoC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5F,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3F,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Tool plugin barrel.
+ *
+ * Public API for the Tool contract — the kernel-level plugin shape
+ * that fitness, simulation, and future tools implement.
+ */
+export type { Tool, ToolMetadata, ToolCommandDescriptor, ToolCliContext, GateCompareResult, SignalDeliveryResult, ScaffoldContext, ScaffoldFile, ToolPluginExports, ToolSessionRecord, ToolSessionReplayContribution, LiveViewRenderer, LiveViewContext, ToolRunSessionInput, ToolSessionContribution, ToolRunCompletion, RecordedToolRunSession, ToolRunSessions, ToolExtensionPoints, HostGovernance, HostAudit, HostEntitlements, } from './types.js';
+export { UnknownLiveViewError } from './types.js';
+export { TOOL_CONTRACT_VERSION } from './types.js';
+export { ToolRegistry } from './registry.js';
+export { PLUGIN_API_VERSION } from './manifest.js';
+export { defineCommand, COMMON_FLAG_KEYS, RAW_STREAM_REASONS } from './command-spec.js';
+export type { CommandSpec, OptionSpec, ArgSpec, CommandHandler, CommandContext, CommandOutputMode, CommandScopeRequirement, CommonFlagKey, RawStreamReason, } from './command-spec.js';
+export type { RawToolPluginManifest, ToolPluginManifest, ToolCommandManifest, ToolProvenance, ToolSource, } from './manifest.js';
+export { isCapabilityValidator, isStructuralContributionSchema } from './capability.js';
+export type { CapabilityDomainSpec, CapabilityContributionKind, CapabilityDiscoveryDescriptor, CapabilityDiscoveryMode, CapabilityCoContribution, CapabilityValidator, StructuralContributionSchema, ToolCapabilityDeclaration, ToolConfigContribution, } from './capability.js';
+export { checkCompatibility } from './compatibility.js';
+export type { CompatibilityVerdict } from './compatibility.js';
+export { assertManifestMatchesTool } from './manifest-assert.js';
+export { TOOL_LONG_IDS, TOOL_LONG_TO_SHORT, TOOL_SHORT_IDS, TOOL_SHORT_TO_LONG, isToolLongId, isToolShortId, } from './ids.js';
+export type { ToolLongId, ToolShortId } from './ids.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,IAAI,EACJ,YAAY,EACZ,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,EACjB,6BAA6B,EAC7B,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,mBAAmB,EAEnB,cAAc,EACd,SAAS,EACT,gBAAgB,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAKnD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACxF,YAAY,EACV,WAAW,EACX,UAAU,EACV,OAAO,EACP,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,uBAAuB,EACvB,aAAa,EACb,eAAe,GAChB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,cAAc,EACd,UAAU,GACX,MAAM,eAAe,CAAC;AAIvB,OAAO,EAAE,qBAAqB,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EACV,oBAAoB,EACpB,0BAA0B,EAC1B,6BAA6B,EAC7B,uBAAuB,EACvB,wBAAwB,EACxB,mBAAmB,EACnB,4BAA4B,EAC5B,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Tool plugin barrel.
+ *
+ * Public API for the Tool contract — the kernel-level plugin shape
+ * that fitness, simulation, and future tools implement.
+ */
+export { UnknownLiveViewError } from './types.js';
+export { TOOL_CONTRACT_VERSION } from './types.js';
+export { ToolRegistry } from './registry.js';
+// Static tool-plugin manifest + the plugin-API epoch + provenance types
+// (launch raw-vs-admitted contract).
+export { PLUGIN_API_VERSION } from './manifest.js';
+// Command-plane types (launch, §5.4): the declarative command surface a
+// tool exports for the host to mount, plus the CommonFlagKey key type (the pure
+// type lives in core; the Commander-touching applyCommonFlags runtime stays in
+// contracts). Re-exported by @opensip-cli/contracts for the public surface.
+export { defineCommand, COMMON_FLAG_KEYS, RAW_STREAM_REASONS } from './command-spec.js';
+// Capability domain model (launch, §5.3): the data shape a tool
+// uses to declare an extension point it owns. The runtime registry lives
+// in `plugins/capability-registry.ts`.
+export { isCapabilityValidator, isStructuralContributionSchema } from './capability.js';
+// The single pure compatibility gate shared by the bundled + external
+// admission paths.
+export { checkCompatibility } from './compatibility.js';
+// Load-time manifest⇔Tool drift guard.
+export { assertManifestMatchesTool } from './manifest-assert.js';
+export { TOOL_LONG_IDS, TOOL_LONG_TO_SHORT, TOOL_SHORT_IDS, TOOL_SHORT_TO_LONG, isToolLongId, isToolShortId, } from './ids.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2BH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,wEAAwE;AACxE,qCAAqC;AACrC,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,wEAAwE;AACxE,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAmBxF,gEAAgE;AAChE,yEAAyE;AACzE,uCAAuC;AACvC,OAAO,EAAE,qBAAqB,EAAE,8BAA8B,EAAE,MAAM,iBAAiB,CAAC;AAYxF,sEAAsE;AACtE,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,uCAAuC;AACvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,YAAY,EACZ,aAAa,GACd,MAAM,UAAU,CAAC"}