@opensip-cli/contracts 0.1.0

package/dist/cli-flags.js

@@ -0,0 +1,85 @@
+/**
+ * Cross-tool CLI flag currency (ADR-0021).
+ *
+ * The single source of truth for the common flags every tool's run command
+ * shares (`--json`, `--cwd`, `--quiet`, `--verbose`, `--debug`,
+ * `--report-to`/`--api-key`, `--open`). Each tool builds its command with
+ * `applyCommonFlags(...)` for the shared flags and adds only its
+ * genuinely tool-specific options by hand — so a flag's text/short-alias/default
+ * is declared once and cannot drift (it already had: `--report-to` read three
+ * different ways across the three tools before this registry).
+ *
+ * `commander` is referenced ONLY as a type (`import type`), matching the rest of
+ * contracts: `applyCommonFlags` calls `.option(...)` on a `Command` instance the
+ * caller passes in, so no runtime `commander` require lands in `dist`. The
+ * package keeps `commander` as an optional peer dependency (see index.ts).
+ */
+/**
+ * The canonical common-flag registry. Adding a tool means calling
+ * {@link applyCommonFlags} with the relevant keys — never re-declaring a flag.
+ */
+export const commonFlags = {
+    json: { flags: '--json', description: 'Output structured JSON', defaultValue: false },
+    cwd: { flags: '--cwd <path>', description: 'Target directory' },
+    quiet: {
+        flags: '-q, --quiet',
+        description: 'Suppress banner / boxes; print only the pass-fail summary',
+        defaultValue: false,
+    },
+    verbose: {
+        flags: '-v, --verbose',
+        description: 'Show the detailed report body inline',
+        defaultValue: false,
+    },
+    debug: {
+        flags: '--debug',
+        description: 'Enable debug mode for structured log output',
+        defaultValue: false,
+    },
+    reportTo: {
+        flags: '--report-to <url>',
+        description: 'POST findings to OpenSIP Cloud or a compatible endpoint',
+    },
+    apiKey: { flags: '--api-key <key>', description: 'API key for --report-to authentication' },
+    open: {
+        flags: '--open',
+        description: 'Launch the HTML report in your browser after the run completes',
+        defaultValue: false,
+    },
+};
+/**
+ * Apply the given common flags to a Commander command in registry order.
+ *
+ * `overrides` supplies per-invocation defaults for flags whose default is not a
+ * literal — notably `cwd`, where callers pass `{ cwd: process.cwd() }`. An
+ * override also wins over a spec's `defaultValue` when both are present.
+ *
+ * Returns the same `command` for chaining. No runtime `commander` dependency is
+ * introduced — only methods on the passed-in instance are called.
+ */
+export function applyCommonFlags(command, keys, overrides) {
+    for (const key of keys) {
+        const spec = commonFlags[key];
+        const def = overrides?.[key] ?? spec.defaultValue;
+        if (def === undefined)
+            command.option(spec.flags, spec.description);
+        else
+            command.option(spec.flags, spec.description, def);
+    }
+    return command;
+}
+/**
+ * The flags every tool's run command MUST declare (the parity set enforced by
+ * the `cross-tool-flag-parity` fitness check, ADR-0021). `open` is intentionally
+ * NOT mandatory — only report-producing tools expose it.
+ */
+export const MANDATORY_COMMON_FLAGS = [
+    'json',
+    'cwd',
+    'quiet',
+    'verbose',
+    'debug',
+    'reportTo',
+    'apiKey',
+];
+//# sourceMappingURL=cli-flags.js.map

package/dist/cli-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-flags.js","sourceRoot":"","sources":["../src/cli-flags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA4BH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAoD;IAC1E,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,wBAAwB,EAAE,YAAY,EAAE,KAAK,EAAE;IACrF,GAAG,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE;IAC/D,KAAK,EAAE;QACL,KAAK,EAAE,aAAa;QACpB,WAAW,EAAE,2DAA2D;QACxE,YAAY,EAAE,KAAK;KACpB;IACD,OAAO,EAAE;QACP,KAAK,EAAE,eAAe;QACtB,WAAW,EAAE,sCAAsC;QACnD,YAAY,EAAE,KAAK;KACpB;IACD,KAAK,EAAE;QACL,KAAK,EAAE,SAAS;QAChB,WAAW,EAAE,6CAA6C;QAC1D,YAAY,EAAE,KAAK;KACpB;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,yDAAyD;KACvE;IACD,MAAM,EAAE,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,wCAAwC,EAAE;IAC3F,IAAI,EAAE;QACJ,KAAK,EAAE,QAAQ;QACf,WAAW,EAAE,gEAAgE;QAC7E,YAAY,EAAE,KAAK;KACpB;CACO,CAAC;AAEX;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAgB,EAChB,IAA8B,EAC9B,SAA4D;IAE5D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC;QAClD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;;YAC/D,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAA6B;IAC9D,MAAM;IACN,KAAK;IACL,OAAO;IACP,SAAS;IACT,OAAO;IACP,UAAU;IACV,QAAQ;CACA,CAAC"}

package/dist/cli-flags.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli-flags.test.d.ts.map

package/dist/cli-flags.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-flags.test.d.ts","sourceRoot":"","sources":["../src/cli-flags.test.ts"],"names":[],"mappings":""}

package/dist/cli-flags.test.js

@@ -0,0 +1,51 @@
+import { Command } from 'commander';
+import { describe, expect, it } from 'vitest';
+import { applyCommonFlags, commonFlags, MANDATORY_COMMON_FLAGS, } from './cli-flags.js';
+describe('commonFlags registry', () => {
+    it('pins the canonical flag strings + descriptions (drift fails here)', () => {
+        expect(commonFlags.json).toEqual({
+            flags: '--json',
+            description: 'Output structured JSON',
+            defaultValue: false,
+        });
+        expect(commonFlags.cwd).toEqual({ flags: '--cwd <path>', description: 'Target directory' });
+        expect(commonFlags.verbose.flags).toBe('-v, --verbose');
+        expect(commonFlags.quiet.flags).toBe('-q, --quiet');
+        // The drift this registry exists to prevent: one canonical --report-to string.
+        expect(commonFlags.reportTo.description).toBe('POST findings to OpenSIP Cloud or a compatible endpoint');
+        expect(commonFlags.apiKey.description).toBe('API key for --report-to authentication');
+    });
+    it('mandatory set is the parity-enforced flags (open is optional)', () => {
+        expect([...MANDATORY_COMMON_FLAGS].sort()).toEqual(['apiKey', 'cwd', 'debug', 'json', 'quiet', 'reportTo', 'verbose'].sort());
+        expect(MANDATORY_COMMON_FLAGS).not.toContain('open');
+    });
+});
+describe('applyCommonFlags', () => {
+    it('registers exactly the requested flags with their registry specs', () => {
+        const cmd = new Command('demo');
+        applyCommonFlags(cmd, ['json', 'verbose', 'reportTo']);
+        const longNames = cmd.options.map((o) => o.long);
+        expect(longNames).toEqual(['--json', '--verbose', '--report-to']);
+        const verbose = cmd.options.find((o) => o.long === '--verbose');
+        expect(verbose?.short).toBe('-v');
+        expect(verbose?.description).toBe('Show the detailed report body inline');
+    });
+    it('applies literal defaults and honors the cwd override', () => {
+        const cmd = new Command('demo');
+        applyCommonFlags(cmd, ['json', 'cwd'], { cwd: '/work/proj' });
+        const parsed = cmd.opts();
+        expect(parsed.json).toBe(false); // literal default from the registry
+        expect(parsed.cwd).toBe('/work/proj'); // per-invocation override
+    });
+    it('returns the same command for chaining', () => {
+        const cmd = new Command('demo');
+        expect(applyCommonFlags(cmd, ['debug'])).toBe(cmd);
+    });
+    it('covers every registry key without throwing', () => {
+        const cmd = new Command('demo');
+        const allKeys = Object.keys(commonFlags);
+        applyCommonFlags(cmd, allKeys, { cwd: process.cwd() });
+        expect(cmd.options.length).toBe(allKeys.length);
+    });
+});
+//# sourceMappingURL=cli-flags.test.js.map

package/dist/cli-flags.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-flags.test.js","sourceRoot":"","sources":["../src/cli-flags.test.ts"],"names":[],"mappings":"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"}

package/dist/command-outcome.d.ts

@@ -0,0 +1,87 @@
+/**
+ * CommandOutcome — the standard OUTER currency wrapping every command result and
+ * error (north-star §5.5, launch).
+ *
+ * `SignalEnvelope` (ADR-0011) is the strong INNER currency, but the outer shape
+ * drifted: run commands emitted a bare envelope, list/report commands a bare
+ * `CommandResult`, errors a bare `ErrorResult`, and the bootstrap bypassed all of
+ * it (`process.exit` + raw stream writes). So a machine consumer could not rely on
+ * one schema for every outcome — and `--json` produced nothing structured for the
+ * highest-friction failures (no project, bad schema), the ones that happen before
+ * a handler ever runs.
+ *
+ * `CommandOutcome<T>` is that one schema. It wraps the **unchanged** inner
+ * envelope under `.envelope` (run commands) or the domain `CommandResult` under
+ * `.data` (list/report/…); an error or bootstrap outcome carries `errors` +
+ * `diagnostics` with neither payload. The host ASSEMBLES it — stamping
+ * `kind`/`status`/`exitCode`/`diagnostics` from the handler's pure-domain return —
+ * so no tool, first-party or external, chooses its own error JSON or success
+ * carrier. The handler contract does not change (the command-plane spec's
+ * "no handler contract change"); all the outer-shape change lands at the host
+ * dispatch seam.
+ *
+ * This is the one user-visible breaking change before GA: `--json` now nests the
+ * envelope one level down (consumers read `.envelope`/`.data`). The inner envelope
+ * is byte-identical to 2.7.0+. Shipped as a 2.x minor with a migration note, like
+ * the 2.7.0 `--json` change (ADR-0024).
+ *
+ * Types-only (the contracts charter): every field is a primitive, a sibling
+ * contract type, or a readonly array thereof.
+ */
+import type { SignalEnvelope } from './signal-envelope.js';
+import type { RunDiagnostics } from '@opensip-cli/core';
+/** Outer status of a command outcome. `partial` = ran but with non-fatal gaps. */
+export type CommandOutcomeStatus = 'ok' | 'error' | 'partial';
+/**
+ * One error attached to a `status:'error'` outcome. The structured successor to
+ * the bare `ErrorResult` shape — `message` plus an optional actionable
+ * `suggestion` (the field `--json` consumers most need on a bootstrap failure)
+ * and an optional machine `code` (e.g. a `ToolError` code).
+ */
+export interface ErrorDetail {
+    readonly message: string;
+    readonly suggestion?: string;
+    readonly code?: string;
+}
+/** One non-fatal warning attached to an outcome. */
+export interface WarningDetail {
+    readonly message: string;
+    readonly code?: string;
+}
+/**
+ * Hints the renderer consumes when materializing the outcome. RESERVED for
+ * launch — populated only with what the existing renderer already branches on
+ * (`quiet`, `noColor`, `preferredFormat`); the field exists so later releases can
+ * extend rendering policy without another outer-shape break. Do not invent new
+ * hints here.
+ */
+export interface RenderHints {
+    readonly quiet?: boolean;
+    readonly noColor?: boolean;
+    readonly preferredFormat?: 'json' | 'human';
+}
+/**
+ * The one outer outcome shape every command — and the bootstrap — emits.
+ *
+ * - `kind` identifies the command/source (`'<name>.run'` for envelope output,
+ *   `'<name>'` for a `CommandResult`, `'bootstrap.error'` for a pre-handler
+ *   failure). Derived by the host assembler from the `CommandSpec`, not chosen by
+ *   the tool.
+ * - `data` (a `CommandResult`) and `envelope` (a `SignalEnvelope`) are the two
+ *   mutually-informative payload slots — BOTH optional, because an error or
+ *   bootstrap outcome has neither, only `errors` + `diagnostics`.
+ * - `diagnostics` is attached by the host from the scope-owned diagnostics bus
+ *   (north-star §5.10).
+ */
+export interface CommandOutcome<T = unknown> {
+    readonly kind: string;
+    readonly status: CommandOutcomeStatus;
+    readonly exitCode: number;
+    readonly data?: T;
+    readonly envelope?: SignalEnvelope;
+    readonly errors?: readonly ErrorDetail[];
+    readonly warnings?: readonly WarningDetail[];
+    readonly diagnostics?: RunDiagnostics;
+    readonly renderHints?: RenderHints;
+}
+//# sourceMappingURL=command-outcome.d.ts.map

package/dist/command-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-outcome.d.ts","sourceRoot":"","sources":["../src/command-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,kFAAkF;AAClF,MAAM,MAAM,oBAAoB,GAAG,IAAI,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC7C;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,CAAC,EAAE,cAAc,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC"}

package/dist/command-outcome.js

@@ -0,0 +1,32 @@
+/**
+ * CommandOutcome — the standard OUTER currency wrapping every command result and
+ * error (north-star §5.5, launch).
+ *
+ * `SignalEnvelope` (ADR-0011) is the strong INNER currency, but the outer shape
+ * drifted: run commands emitted a bare envelope, list/report commands a bare
+ * `CommandResult`, errors a bare `ErrorResult`, and the bootstrap bypassed all of
+ * it (`process.exit` + raw stream writes). So a machine consumer could not rely on
+ * one schema for every outcome — and `--json` produced nothing structured for the
+ * highest-friction failures (no project, bad schema), the ones that happen before
+ * a handler ever runs.
+ *
+ * `CommandOutcome<T>` is that one schema. It wraps the **unchanged** inner
+ * envelope under `.envelope` (run commands) or the domain `CommandResult` under
+ * `.data` (list/report/…); an error or bootstrap outcome carries `errors` +
+ * `diagnostics` with neither payload. The host ASSEMBLES it — stamping
+ * `kind`/`status`/`exitCode`/`diagnostics` from the handler's pure-domain return —
+ * so no tool, first-party or external, chooses its own error JSON or success
+ * carrier. The handler contract does not change (the command-plane spec's
+ * "no handler contract change"); all the outer-shape change lands at the host
+ * dispatch seam.
+ *
+ * This is the one user-visible breaking change before GA: `--json` now nests the
+ * envelope one level down (consumers read `.envelope`/`.data`). The inner envelope
+ * is byte-identical to 2.7.0+. Shipped as a 2.x minor with a migration note, like
+ * the 2.7.0 `--json` change (ADR-0024).
+ *
+ * Types-only (the contracts charter): every field is a primitive, a sibling
+ * contract type, or a readonly array thereof.
+ */
+export {};
+//# sourceMappingURL=command-outcome.js.map

package/dist/command-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-outcome.js","sourceRoot":"","sources":["../src/command-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG"}

package/dist/command-outcome.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CommandOutcome shape — the three outcome flavours construct and serialize.
+ *
+ * The contract is "one outer schema for every result and error". The load-bearing
+ * checks: a run outcome nests the UNCHANGED envelope under `.envelope`; a
+ * command-result outcome uses `.data`; a bootstrap/error outcome carries neither
+ * payload, only `errors` (+ diagnostics). All three JSON round-trip.
+ */
+export {};
+//# sourceMappingURL=command-outcome.test.d.ts.map

package/dist/command-outcome.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-outcome.test.d.ts","sourceRoot":"","sources":["../src/command-outcome.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/command-outcome.test.js

@@ -0,0 +1,68 @@
+/**
+ * CommandOutcome shape — the three outcome flavours construct and serialize.
+ *
+ * The contract is "one outer schema for every result and error". The load-bearing
+ * checks: a run outcome nests the UNCHANGED envelope under `.envelope`; a
+ * command-result outcome uses `.data`; a bootstrap/error outcome carries neither
+ * payload, only `errors` (+ diagnostics). All three JSON round-trip.
+ */
+import { HOST_VERDICT_POLICY_FALLBACK } from '@opensip-cli/core';
+import { describe, it, expect } from 'vitest';
+import { buildSignalEnvelope } from './signal-envelope.js';
+const DIAGNOSTICS = { runId: 'run_1', events: [] };
+describe('CommandOutcome', () => {
+    it('wraps a run as .envelope without altering the inner envelope', () => {
+        const envelope = buildSignalEnvelope({
+            tool: 'fit',
+            runId: 'run_1',
+            createdAt: '2026-06-07T00:00:00.000Z',
+            units: [{ slug: 'a', passed: true, durationMs: 1 }],
+            signals: [],
+            policy: HOST_VERDICT_POLICY_FALLBACK,
+            runFaulted: false,
+        });
+        const outcome = {
+            kind: 'fit.run',
+            status: 'ok',
+            exitCode: 0,
+            envelope,
+            diagnostics: DIAGNOSTICS,
+        };
+        // The inner envelope is byte-identical — the break is purely the new wrapper.
+        expect(outcome.envelope).toBe(envelope);
+        expect(outcome.data).toBeUndefined();
+        const wire = JSON.stringify(outcome);
+        expect(JSON.parse(wire).envelope).toEqual(envelope);
+    });
+    it('wraps a command result as .data', () => {
+        const outcome = {
+            kind: 'sessions.list',
+            status: 'ok',
+            exitCode: 0,
+            data: { type: 'history', count: 4 },
+        };
+        expect(outcome.data).toEqual({ type: 'history', count: 4 });
+        expect(outcome.envelope).toBeUndefined();
+    });
+    it('carries a bootstrap error with neither payload, only errors + diagnostics', () => {
+        const outcome = {
+            kind: 'bootstrap.error',
+            status: 'error',
+            exitCode: 2,
+            errors: [
+                {
+                    message: 'No OpenSIP CLI project found.',
+                    suggestion: 'Run opensip init.',
+                    code: 'CONFIGURATION_ERROR',
+                },
+            ],
+            diagnostics: DIAGNOSTICS,
+        };
+        expect(outcome.data).toBeUndefined();
+        expect(outcome.envelope).toBeUndefined();
+        expect(outcome.errors?.[0]?.suggestion).toBe('Run opensip init.');
+        const wire = JSON.stringify(outcome);
+        expect(JSON.parse(wire)).toEqual(outcome);
+    });
+});
+//# sourceMappingURL=command-outcome.test.js.map

package/dist/command-outcome.test.js.map

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