opensip-cli 0.1.0

package/dist/commands/uninstall.js

@@ -0,0 +1,184 @@
+// @fitness-ignore-file error-handling-quality -- file/dir walks for uninstall planning and best-effort tidy-up: missing/unreadable entries (TOCTOU vanish between readdir+stat, permission-denied subdirs, already-removed parent shells) are the expected non-terminal signal to skip; failure-IS-the-signal is the function contract in each catch.
+// @fitness-ignore-file only-documented-toolcli-seams -- interactive TTY UX: the readline confirmation prompt + human-readable removal-progress notes go to stdout via an injectable `write` (defaulted to process.stdout for the real run, stubbed in tests); this is not machine run output through a ToolCliContext seam (same category as clear.ts/configure.ts).
+/**
+ * @fileoverview `opensip uninstall` — remove opensip-cli state
+ * from a user account and/or project.
+ *
+ * Two modes:
+ *
+ *  • Default (no flag) — remove the user-level directory
+ *    `~/.opensip-cli/`. Contract: this dir holds `config.yml` only
+ *    (cloud API key + per-user defaults). Persistence and logging code
+ *    throws if asked to write anywhere user-global, so the dir does
+ *    not grow over time. Any pre-existing `sessions/`, `reports/`,
+ *    `logs/`, or `fit/` subdirectories on disk are legacy cruft from
+ *    earlier versions and are swept up by the same removal.
+ *
+ *  • `--project [path]` — remove project-local state at `[path]` (or
+ *    cwd if omitted): both `<path>/opensip-cli/` (user-authored
+ *    checks + recipes plus the gitignored `.runtime/` cache) and
+ *    `<path>/opensip-cli.config.yml`. Refuses to run if neither
+ *    target exists at the resolved path, to avoid `rm -rf`-ing an
+ *    unrelated directory.
+ *
+ *    The recursive removal of `<path>/opensip-cli/` transitively
+ *    sweeps up `.runtime/datastore.sqlite` and its `-wal`/`-shm` SQLite
+ *    sidecars — no datastore-specific path needs to be
+ *    enumerated here. Caveat for Windows: open file handles can block
+ *    removal of WAL/SHM files; ensure no opensip-cli CLI process is
+ *    active when running uninstall.
+ *
+ * Does NOT remove the npm global install — the running binary can't
+ * safely self-delete. Prints the exact next-step command for that.
+ *
+ * Flags:
+ *   --project [path]   Remove project-local state instead of user-level.
+ *   --yes              Skip confirmation prompt.
+ *   --dry-run          Print what would be removed; take no action.
+ *
+ * Result-shape contract (audit 2026-05-23 G5)
+ * -------------------------------------------
+ * `executeUninstall` returns a discriminated `UninstallDoneResult` whose
+ * `type === 'uninstall-done'` makes it a valid `CommandResult`. The
+ * trailing success / cancelled / dry-run / empty notice — previously
+ * raw-stdout writes that bypassed the theme — is rendered via Ink in
+ * `App.tsx`'s `case 'uninstall-done':` branch. The pre-confirmation
+ * target listing stays as a direct `write()` because it must appear
+ * BEFORE the readline confirmation prompt; same pattern as
+ * `configure.ts` printing the "current key" hint above the prompt.
+ *
+ * Module layout
+ * -------------
+ * - This file owns `executeUninstall` and removal orchestration.
+ * - `uninstall/targets.ts` owns Target collection + pre-prompt display.
+ */
+import { existsSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { resolveProjectPaths } from '@opensip-cli/core';
+import { collectTargets, printProjectDefault, printProjectPurge, printUserModeTargets, } from './uninstall/targets.js';
+const DEFAULT_USER_ROOT = join(homedir(), '.opensip-cli');
+async function confirm(prompt, message) {
+    const raw = await prompt(message);
+    const answer = raw.trim().toLowerCase();
+    return answer === 'y' || answer === 'yes';
+}
+function defaultPrompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return rl.question(question).finally(() => rl.close());
+}
+/** Resolve the project directory for `--project [path]`. */
+function resolveProjectDir(opts) {
+    if (typeof opts.project === 'string')
+        return resolve(opts.project);
+    // Prefer the discovered project root (set by pre-action-hook). Falls
+    // back to literal cwd, then process.cwd(). Without the discovered
+    // root, `uninstall` from a subdir would target the wrong .runtime/.
+    return opts.projectContext?.projectRoot ?? opts.cwd ?? process.cwd();
+}
+/** Project a `Target[]` into the result-shape `{path, kind}[]`. */
+function targetsForResult(targets) {
+    return targets.map((t) => ({ path: t.path, kind: t.kind }));
+}
+/**
+ * Build the canonical "no-op" / "post-removal" result. The `action`
+ * discriminator is the single source of truth for what happened
+ * (`removed` / `dry-run` / `cancelled` / `empty`); consumers branch on
+ * it rather than on derived boolean flags.
+ */
+function buildResult(args) {
+    const sizeBytes = args.targets.reduce((sum, t) => sum + t.sizeBytes, 0);
+    return {
+        type: 'uninstall-done',
+        action: args.action,
+        mode: args.mode,
+        targets: targetsForResult(args.targets),
+        sizeBytes,
+        rootPath: args.rootPath,
+    };
+}
+/** Filter all-targets into (toDelete, toKeep) per mode + purge flag. */
+function filterTargetsForAction(mode, purge, allTargets) {
+    if (mode === 'user' || purge) {
+        return { toDelete: allTargets, toKeep: [] };
+    }
+    return {
+        toDelete: allTargets.filter((t) => t.bucket === 'runtime'),
+        toKeep: allTargets.filter((t) => t.bucket !== 'runtime'),
+    };
+}
+/** Print the pre-prompt summary appropriate to mode + purge state. */
+function printPreambleForRun(write, input) {
+    const { mode, purge, toDelete, toKeep, rootPath } = input;
+    if (mode === 'user') {
+        printUserModeTargets(write, toDelete);
+    }
+    else if (purge) {
+        printProjectPurge(write, toDelete, rootPath);
+    }
+    else {
+        printProjectDefault(write, toDelete, toKeep, rootPath);
+    }
+}
+export async function executeUninstall(opts = {}) {
+    const mode = opts.project === undefined ? 'user' : 'project';
+    const userRoot = opts.rootDir ?? DEFAULT_USER_ROOT;
+    const projectDir = resolveProjectDir(opts);
+    const rootPath = mode === 'user' ? userRoot : projectDir;
+    const write = opts.write ?? ((s) => process.stdout.write(s));
+    const purge = opts.purge === true;
+    const allTargets = collectTargets(mode, userRoot, projectDir);
+    if (allTargets.length === 0) {
+        const where = mode === 'user' ? userRoot : projectDir;
+        const note = mode === 'project'
+            ? `\nNothing to remove — no OpenSIP CLI state found at ${where}.\n\n`
+            : `\nNothing to remove — ${where} does not exist.\n\n`;
+        write(note);
+        return buildResult({ action: 'empty', mode, targets: [], rootPath });
+    }
+    const { toDelete, toKeep } = filterTargetsForAction(mode, purge, allTargets);
+    // Empty-after-filter (project default with no .runtime/ but existing
+    // user content). Print the KEPT block so the user sees what survived.
+    if (mode === 'project' && toDelete.length === 0) {
+        printProjectDefault(write, [], toKeep, rootPath);
+        return buildResult({ action: 'empty', mode, targets: [], rootPath });
+    }
+    printPreambleForRun(write, { mode, purge, toDelete, toKeep, rootPath });
+    if (opts.dryRun) {
+        return buildResult({ action: 'dry-run', mode, targets: toDelete, rootPath });
+    }
+    if (opts.yes !== true) {
+        const prompt = opts.prompt ?? defaultPrompt;
+        const ok = await confirm(prompt, `Proceed? [y/N] `);
+        if (!ok) {
+            return buildResult({ action: 'cancelled', mode, targets: toDelete, rootPath });
+        }
+    }
+    performRemoval(toDelete, mode, purge, projectDir);
+    return buildResult({ action: 'removed', mode, targets: toDelete, rootPath });
+}
+/**
+ * Delete the resolved targets and, after --purge, tidy the now-empty
+ * `opensip-cli/` shell. Extracted so executeUninstall stays under the
+ * cognitive-complexity threshold.
+ */
+function performRemoval(toDelete, mode, purge, projectDir) {
+    for (const t of toDelete) {
+        rmSync(t.path, { recursive: true, force: true });
+    }
+    if (mode !== 'project' || !purge)
+        return;
+    // --purge removed children individually (each enumerated for display).
+    // Tidy the parent shell so --purge matches "removes EVERYTHING."
+    const paths = resolveProjectPaths(projectDir);
+    if (existsSync(paths.userSourceDir)) {
+        try {
+            rmSync(paths.userSourceDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+//# sourceMappingURL=uninstall.js.map

package/dist/commands/uninstall.js.map

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

package/dist/env/host-env-specs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * host-env-specs — the CLI's environment-variable surface (launch, §5.12).
+ *
+ * The env surface is governed exactly like the config document: every variable is
+ * declared as an immutable {@link EnvVarSpec} and read through the {@link EnvRegistry}
+ * primitive, so it can be documented (the generated env-surface reference) and
+ * deprecated coherently. The `env-via-registry` guardrail fails CI on any raw
+ * `process.env` read outside the registry.
+ *
+ * This module owns the CLI-layer infra variables (telemetry + update-notifier) and
+ * AGGREGATES the per-package specs (config, graph) plus the documented pre-scope
+ * exceptions into one `describeHostEnv()` for the reference doc — the CLI is the
+ * composition root, so it is the one place that can name every layer's specs.
+ *
+ * Pre-scope exceptions: the terminal-theme color vars (`@opensip-cli/cli-ui` has
+ * no `core` dependency and resolves colors before any scope exists) and
+ * `NODE_OPTIONS` (the graph heap-preflight mutates it before any opensip module
+ * loads) are read raw at their sites. They are declared here for documentation
+ * only and allow-listed by the `env-via-registry` guardrail.
+ */
+import { EnvRegistry, type EnvVarSpec } from '@opensip-cli/core';
+/** CLI-layer infra variables: OpenTelemetry + the update-notifier opt-outs. */
+export declare const CLI_ENV_SPECS: readonly EnvVarSpec<unknown>[];
+/** The composed CLI-layer registry. Telemetry + update-notifier read through it. */
+export declare const hostEnv: EnvRegistry;
+/**
+ * Env vars a BUNDLED TOOL reads through its own `EnvRegistry`, documented here
+ * at the composition root for the env-surface reference.
+ *
+ * The host does not statically import tool packages just to read env specs
+ * (e.g. `GRAPH_ENV_SPECS` from `@opensip-cli/graph`) — that would couple the
+ * host to a tool runtime and break the install-source-independence the
+ * `no-bootstrap-tool-import` guardrail enforces. The tool keeps OWNING the
+ * runtime read (its registry, its coercion); the composition root names the
+ * variable for documentation only, the same way it already documents the
+ * graph-related `NODE_OPTIONS` below. The `host-env-specs` drift test asserts
+ * this list stays a superset of each bundled tool's actual specs (e.g. graph's
+ * `GRAPH_ENV_SPECS`), so a tool adding an env var fails CI until it is
+ * documented here.
+ */
+export declare const BUNDLED_TOOL_ENV_SPECS: readonly EnvVarSpec<unknown>[];
+/**
+ * Pre-scope variables read raw at their sites (documented `env-via-registry`
+ * allowance), declared here so the env-surface reference is complete.
+ */
+export declare const PRE_SCOPE_ENV_SPECS: readonly EnvVarSpec<unknown>[];
+/**
+ * Every environment variable the platform reads, across all layers — the source
+ * of truth for the generated env-surface reference (Phase 6).
+ */
+export declare function describeHostEnv(): readonly EnvVarSpec<unknown>[];
+//# sourceMappingURL=host-env-specs.d.ts.map

package/dist/env/host-env-specs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-env-specs.d.ts","sourceRoot":"","sources":["../../src/env/host-env-specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEjE,+EAA+E;AAC/E,eAAO,MAAM,aAAa,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAwDvD,CAAC;AAEF,oFAAoF;AAEpF,eAAO,MAAM,OAAO,aAAiC,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAKhE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,CAAC,OAAO,CAAC,EAgB7D,CAAC;AAEF;;;GAGG;AACH,wBAAgB,eAAe,IAAI,SAAS,UAAU,CAAC,OAAO,CAAC,EAAE,CAEhE"}

package/dist/env/host-env-specs.js

@@ -0,0 +1,129 @@
+/**
+ * host-env-specs — the CLI's environment-variable surface (launch, §5.12).
+ *
+ * The env surface is governed exactly like the config document: every variable is
+ * declared as an immutable {@link EnvVarSpec} and read through the {@link EnvRegistry}
+ * primitive, so it can be documented (the generated env-surface reference) and
+ * deprecated coherently. The `env-via-registry` guardrail fails CI on any raw
+ * `process.env` read outside the registry.
+ *
+ * This module owns the CLI-layer infra variables (telemetry + update-notifier) and
+ * AGGREGATES the per-package specs (config, graph) plus the documented pre-scope
+ * exceptions into one `describeHostEnv()` for the reference doc — the CLI is the
+ * composition root, so it is the one place that can name every layer's specs.
+ *
+ * Pre-scope exceptions: the terminal-theme color vars (`@opensip-cli/cli-ui` has
+ * no `core` dependency and resolves colors before any scope exists) and
+ * `NODE_OPTIONS` (the graph heap-preflight mutates it before any opensip module
+ * loads) are read raw at their sites. They are declared here for documentation
+ * only and allow-listed by the `env-via-registry` guardrail.
+ */
+import { CONFIG_ENV_SPECS } from '@opensip-cli/config';
+import { EnvRegistry } from '@opensip-cli/core';
+/** CLI-layer infra variables: OpenTelemetry + the update-notifier opt-outs. */
+export const CLI_ENV_SPECS = [
+    {
+        canonical: 'OTEL_EXPORTER_OTLP_ENDPOINT',
+        docs: 'OTLP/HTTP endpoint. When set, the CLI enables OpenTelemetry tracing; unset is a hard no-op.',
+    },
+    {
+        canonical: 'OPENSIP_PROFILING',
+        docs: 'Explicit gate for the optional CPU profiling path (ADR-0049). "1" or "true" forces on when OTEL_EXPORTER_OTLP_ENDPOINT is set; "0"/"false" forces off. When omitted and the OTLP endpoint is present, falls back to the documented OTEL-only mode (with cost warnings emitted).',
+    },
+    {
+        canonical: 'TRACEPARENT',
+        docs: 'W3C traceparent of a parent trace (read only when telemetry is on); run spans nest under it.',
+    },
+    {
+        canonical: 'OPENSIP_NO_UPDATE',
+        coerce: (raw) => raw.length > 0,
+        default: false,
+        docs: 'Set to any non-empty value to skip the CLI update check.',
+    },
+    {
+        canonical: 'NO_UPDATE_NOTIFIER',
+        coerce: (raw) => raw.length > 0,
+        default: false,
+        docs: 'npm-convention update-notifier opt-out; honoured as an equivalent of OPENSIP_NO_UPDATE.',
+    },
+    {
+        canonical: 'OPENSIP_CLI_SKIP_BUNDLED',
+        coerce: (raw) => raw
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0),
+        default: [],
+        docs: 'Comma-separated bundled-tool ids (fitness/simulation/graph) to NOT load as bundled. ' +
+            'A skipped tool can instead be loaded from an installed/project-local package of the same id ' +
+            '— the install-source-independence escape hatch. Unset = load all bundled tools.',
+    },
+    {
+        canonical: 'OPENSIP_CLI_ALLOW_PROJECT_TOOLS',
+        // Mirror parseAllowlist's split (whitespace AND comma) so the registry value
+        // and tool-trust's set agree exactly — including the `*` token, which passes
+        // through as a plain id the trust check tests for.
+        coerce: (raw) => raw
+            .split(/[\s,]+/)
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0),
+        default: [],
+        docs: 'Comma/whitespace-separated project-authored Tool ids to admit (deny-by-default). ' +
+            "Use '*' to admit all project-authored tools. A project-authored sidecar tool under " +
+            '<project>/opensip-cli/tools/ is NOT loaded unless its id (or *) appears here — it ' +
+            'rides in with git clone, so loading it runs untrusted code. Global-authored tools ' +
+            '(~/.opensip-cli/tools/) are trusted-by-default and ignore this list.',
+    },
+];
+/** The composed CLI-layer registry. Telemetry + update-notifier read through it. */
+// @allow-module-singleton EnvRegistry is IMMUTABLE — a constant spec table + on-demand process.env reads; it holds no per-run mutable state, so it is not the scope-isolation hazard no-module-singleton targets (spec §5.12 resolved decision: the env definition table is a permitted module constant).
+export const hostEnv = new EnvRegistry(CLI_ENV_SPECS);
+/**
+ * Env vars a BUNDLED TOOL reads through its own `EnvRegistry`, documented here
+ * at the composition root for the env-surface reference.
+ *
+ * The host does not statically import tool packages just to read env specs
+ * (e.g. `GRAPH_ENV_SPECS` from `@opensip-cli/graph`) — that would couple the
+ * host to a tool runtime and break the install-source-independence the
+ * `no-bootstrap-tool-import` guardrail enforces. The tool keeps OWNING the
+ * runtime read (its registry, its coercion); the composition root names the
+ * variable for documentation only, the same way it already documents the
+ * graph-related `NODE_OPTIONS` below. The `host-env-specs` drift test asserts
+ * this list stays a superset of each bundled tool's actual specs (e.g. graph's
+ * `GRAPH_ENV_SPECS`), so a tool adding an env var fails CI until it is
+ * documented here.
+ */
+export const BUNDLED_TOOL_ENV_SPECS = [
+    {
+        canonical: 'OPENSIP_HEAP_NO_MONITOR',
+        docs: 'Set to 1 to disable the graph V8 heap-pressure monitor (REPL embedding / custom allocators).',
+    },
+];
+/**
+ * Pre-scope variables read raw at their sites (documented `env-via-registry`
+ * allowance), declared here so the env-surface reference is complete.
+ */
+export const PRE_SCOPE_ENV_SPECS = [
+    {
+        canonical: 'NO_COLOR',
+        docs: 'Disable ANSI colours (https://no-color.org). Resolved by the terminal theme.',
+    },
+    { canonical: 'FORCE_COLOR', docs: 'Force ANSI colours even when the stream is not a TTY.' },
+    { canonical: 'COLORTERM', docs: 'Terminal colour capability hint (e.g. truecolor).' },
+    { canonical: 'TERM', docs: 'Terminal type; consulted for colour support.' },
+    {
+        canonical: 'TERM_PROGRAM',
+        docs: 'Terminal program (e.g. iTerm.app); consulted for colour support.',
+    },
+    {
+        canonical: 'NODE_OPTIONS',
+        docs: 'Node flags; the graph heap-preflight reads/extends this before relaunch (pre-module).',
+    },
+];
+/**
+ * Every environment variable the platform reads, across all layers — the source
+ * of truth for the generated env-surface reference (Phase 6).
+ */
+export function describeHostEnv() {
+    return [...CONFIG_ENV_SPECS, ...BUNDLED_TOOL_ENV_SPECS, ...CLI_ENV_SPECS, ...PRE_SCOPE_ENV_SPECS];
+}
+//# sourceMappingURL=host-env-specs.js.map

package/dist/env/host-env-specs.js.map

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

package/dist/error-handler.d.ts

@@ -0,0 +1,64 @@
+/**
+ * error-handler — single-responsibility catch handler for the
+ * top-level `parseAsync().catch(...)` block.
+ *
+ * Goals:
+ *  - One `process.exitCode` write path: route every exit-code change
+ *    through the supplied `setExitCode` callback (which `cli-context.ts`
+ *    centralises).
+ *  - Match on `instanceof` against the typed error hierarchy in
+ *    `@opensip-cli/core`; fall back to the data-driven
+ *    `getErrorSuggestion` (Layer 2 Phase 1) for unknown shapes.
+ *  - The typed-error → exit-code policy lives in contracts'
+ *    `mapToolErrorToExitCode` (audit-round-2 Finding C). This handler
+ *    keeps only the *CLI-specific* layer: per-class action hints (e.g.
+ *    "Run opensip fit --list...") that don't belong in the
+ *    headless contracts package.
+ *  - Keep the renderer pluggable so unit tests can capture the rendered
+ *    `ErrorResult` without touching Ink.
+ */
+import { type ErrorResult } from '@opensip-cli/contracts';
+export interface HandleParseErrorOptions {
+    readonly setExitCode: (code: number) => void;
+    readonly render: (result: ErrorResult) => Promise<void>;
+    /**
+     * Whether `--json` was requested (read from argv at the composition root —
+     * these errors fire outside a handler, so no parsed opts are available). When
+     * true, every error becomes a structured `CommandOutcome` on stdout (the
+     * `one-outcome-shape` contract, §5.5); when false, human rendering is
+     * byte-identical to launch.
+     */
+    readonly jsonRequested: boolean;
+}
+/**
+ * The catch handler for `program.parseAsync()`. Maps the thrown error to a
+ * `CommandOutcome` (launch, §5.5): `--json` emits the structured outcome
+ * on stdout, human mode renders byte-identically to launch. Routes the exit code
+ * through `setExitCode`. Never throws.
+ */
+export declare function handleParseError(error: unknown, opts: HandleParseErrorOptions): Promise<void>;
+/**
+ * Top-level fatal-error handler for failures BEFORE Commander's parse
+ * loop runs (bootstrap registration, dynamic plugin imports, preflight
+ * I/O). Sets `process.exitCode` (not `process.exit(N)` — the latter
+ * skips the pending stderr flush, and any structured-logging hook on
+ * bootstrap failure has nowhere to attach), writes the error line to
+ * stderr, and emits a `cli.bootstrap.failed` log event so observability
+ * pipelines see the failure. Audit 2026-05-23 G1.
+ *
+ * Exit code: a typed `ToolError` (e.g. the `PluginIncompatibleError` the
+ * Phase-3 fail-closed admission path throws) routes through the canonical
+ * `mapToolErrorToExitCode` policy so a fail-closed plugin yields exit 5
+ * (`PLUGIN_INCOMPATIBLE`) even when it surfaces from bootstrap rather than
+ * Commander's parse loop. Untyped errors keep the historical exit 1.
+ *
+ * Synchronous because every step here is sync — stderr write,
+ * structured-log call, exit-code set. The top-level caller doesn't
+ * need to `await` it (Node exits naturally with the configured
+ * `process.exitCode` after the event loop drains), but the call site
+ * is fine to `await` either way.
+ */
+export declare function handleFatalBootstrapError(error: unknown, log: {
+    error: (entry: Record<string, unknown>) => void;
+}): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../src/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAIL,KAAK,WAAW,EAEjB,MAAM,wBAAwB,CAAC;AAgFhC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAKD;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA0Df;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE;IAAE,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;CAAE,GACvD,IAAI,CAaN"}

package/dist/error-handler.js

@@ -0,0 +1,180 @@
+/**
+ * error-handler — single-responsibility catch handler for the
+ * top-level `parseAsync().catch(...)` block.
+ *
+ * Goals:
+ *  - One `process.exitCode` write path: route every exit-code change
+ *    through the supplied `setExitCode` callback (which `cli-context.ts`
+ *    centralises).
+ *  - Match on `instanceof` against the typed error hierarchy in
+ *    `@opensip-cli/core`; fall back to the data-driven
+ *    `getErrorSuggestion` (Layer 2 Phase 1) for unknown shapes.
+ *  - The typed-error → exit-code policy lives in contracts'
+ *    `mapToolErrorToExitCode` (audit-round-2 Finding C). This handler
+ *    keeps only the *CLI-specific* layer: per-class action hints (e.g.
+ *    "Run opensip fit --list...") that don't belong in the
+ *    headless contracts package.
+ *  - Keep the renderer pluggable so unit tests can capture the rendered
+ *    `ErrorResult` without touching Ink.
+ */
+import { EXIT_CODES, getErrorSuggestion, mapToolErrorToExitCode, } from '@opensip-cli/contracts';
+import { ConfigurationError, NetworkError, NotFoundError, PluginIncompatibleError, ToolError, } from '@opensip-cli/core';
+import { CommanderError } from 'commander';
+import { BootstrapError } from './bootstrap/bootstrap-error.js';
+import { outcomeFromError, outcomeFromErrorMessage } from './commands/assemble-outcome.js';
+import { renderOutcome } from './commands/render-outcome.js';
+/**
+ * Commander error codes that denote an INVALID ARGUMENT VALUE — a declared
+ * `choices` rejection or a custom `argParser` that threw `InvalidArgumentError`
+ * (e.g. graph's `--resolution` once its value validation moved from an
+ * in-handler `ValidationError` to a declarative `choices` in the launch command
+ * plane). These are usage errors and must exit `CONFIGURATION_ERROR` (2) — the
+ * same code `mapToolErrorToExitCode(ValidationError)` yields — preserving the
+ * pre-command-plane contract. Every OTHER Commander code (unknown command /
+ * option, missing argument, help/version display) keeps Commander's own
+ * `exitCode`, which already matched launch.
+ */
+const COMMANDER_INVALID_ARGUMENT_CODES = new Set([
+    'commander.invalidArgument',
+    'commander.invalidOptionArgument',
+]);
+/**
+ * Map a Commander `exitOverride` error to an exit code, re-mapping only the
+ * invalid-argument-value codes to `CONFIGURATION_ERROR` (2) to match the typed
+ * `ValidationError` semantics the declarative `choices` replaced. All other
+ * Commander conditions retain Commander's own `exitCode`.
+ */
+function commanderExitCode(error) {
+    return COMMANDER_INVALID_ARGUMENT_CODES.has(error.code)
+        ? EXIT_CODES.CONFIGURATION_ERROR
+        : error.exitCode;
+}
+/**
+ * Per-class action hints. Adding a new ToolError subclass with a
+ * suggested user action is one tuple here; the exit code comes from
+ * `mapToolErrorToExitCode` so the policy stays in one place.
+ */
+const ACTION_HINTS = [
+    {
+        is: (e) => e instanceof NotFoundError,
+        action: 'Run opensip fit --list to see available checks.',
+    },
+    {
+        is: (e) => e instanceof ConfigurationError,
+        action: 'Check opensip-cli.config.yml or your --language flag.',
+    },
+    {
+        is: (e) => e instanceof NetworkError,
+        action: 'Check the --report-to URL and your network connection.',
+    },
+    {
+        is: (e) => e instanceof PluginIncompatibleError,
+        action: 'Upgrade OpenSIP CLI (or the tool), or allowlist a project-local tool via OPENSIP_CLI_ALLOW_PROJECT_TOOLS.',
+    },
+];
+function suggestionFromTypedError(error) {
+    if (!(error instanceof ToolError))
+        return null;
+    const hint = ACTION_HINTS.find((rule) => rule.is(error));
+    return {
+        message: error.message,
+        ...(hint ? { action: hint.action } : {}),
+        exitCode: mapToolErrorToExitCode(error),
+    };
+}
+/** Inert renderer for the `--json` paths — `renderOutcome` never renders in JSON mode. */
+const NOOP_RENDER = () => Promise.resolve();
+/**
+ * The catch handler for `program.parseAsync()`. Maps the thrown error to a
+ * `CommandOutcome` (launch, §5.5): `--json` emits the structured outcome
+ * on stdout, human mode renders byte-identically to launch. Routes the exit code
+ * through `setExitCode`. Never throws.
+ */
+export async function handleParseError(error, opts) {
+    // Commander's own parse failures (surfaced because the root program calls
+    // `.exitOverride()`). Commander has ALREADY written its error/usage line to
+    // stderr (or the help text to stdout), so we set the exit code and render
+    // nothing — re-rendering would duplicate Commander's output and regress the
+    // legacy-identical stderr for unknown-command/option/missing-arg cases. Only
+    // the invalid-argument-value codes are re-mapped to exit 2 (ValidationError
+    // parity); every other code keeps Commander's exit code.
+    if (error instanceof CommanderError) {
+        opts.setExitCode(commanderExitCode(error));
+        return;
+    }
+    // Pre-handler bootstrap failures (§4.7): no-project, schema-too-old,
+    // config-resolve, tool-init. The guard threw a typed BootstrapError carrying its
+    // own exit code, a clean message, and the original multi-line human text. In
+    // human mode we write that text to stderr verbatim — byte-identical to the
+    // legacy guard output; in `--json` we emit a structured `bootstrap.error`.
+    if (error instanceof BootstrapError) {
+        opts.setExitCode(error.exitCode);
+        if (opts.jsonRequested) {
+            await renderOutcome(outcomeFromErrorMessage({
+                message: error.message,
+                exitCode: error.exitCode,
+                kind: 'bootstrap.error',
+                ...(error.suggestion ? { suggestion: error.suggestion } : {}),
+            }), { jsonRequested: true, render: NOOP_RENDER });
+        }
+        else {
+            process.stderr.write(`${error.humanMessage}\n`);
+        }
+        return;
+    }
+    const typed = suggestionFromTypedError(error);
+    const suggestion = typed ?? getErrorSuggestion(error);
+    const message = error instanceof Error ? error.message : String(error);
+    const exitCode = suggestion?.exitCode ?? EXIT_CODES.RUNTIME_ERROR;
+    opts.setExitCode(exitCode);
+    // `--json`: one outcome shape for every error (no Ink to stdout).
+    if (opts.jsonRequested) {
+        await renderOutcome(outcomeFromError(error, { kind: 'command.error' }), {
+            jsonRequested: true,
+            render: NOOP_RENDER,
+        });
+        return;
+    }
+    // Human: the existing Ink `ErrorResult` render (byte-identical to launch).
+    await opts.render({
+        type: 'error',
+        message: suggestion?.message ?? message,
+        ...(suggestion?.action ? { suggestion: suggestion.action } : {}),
+        exitCode,
+    });
+}
+/**
+ * Top-level fatal-error handler for failures BEFORE Commander's parse
+ * loop runs (bootstrap registration, dynamic plugin imports, preflight
+ * I/O). Sets `process.exitCode` (not `process.exit(N)` — the latter
+ * skips the pending stderr flush, and any structured-logging hook on
+ * bootstrap failure has nowhere to attach), writes the error line to
+ * stderr, and emits a `cli.bootstrap.failed` log event so observability
+ * pipelines see the failure. Audit 2026-05-23 G1.
+ *
+ * Exit code: a typed `ToolError` (e.g. the `PluginIncompatibleError` the
+ * Phase-3 fail-closed admission path throws) routes through the canonical
+ * `mapToolErrorToExitCode` policy so a fail-closed plugin yields exit 5
+ * (`PLUGIN_INCOMPATIBLE`) even when it surfaces from bootstrap rather than
+ * Commander's parse loop. Untyped errors keep the historical exit 1.
+ *
+ * Synchronous because every step here is sync — stderr write,
+ * structured-log call, exit-code set. The top-level caller doesn't
+ * need to `await` it (Node exits naturally with the configured
+ * `process.exitCode` after the event loop drains), but the call site
+ * is fine to `await` either way.
+ */
+export function handleFatalBootstrapError(error, log) {
+    const message = error instanceof Error ? error.message : String(error);
+    const exitCode = error instanceof ToolError ? mapToolErrorToExitCode(error) : EXIT_CODES.RUNTIME_ERROR;
+    process.stderr.write(`opensip: fatal error: ${message}\n`);
+    log.error({
+        evt: 'cli.bootstrap.failed',
+        module: 'cli:bootstrap',
+        error: message,
+        exitCode,
+        stack: error instanceof Error ? error.stack : undefined,
+    });
+    process.exitCode = exitCode;
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/error-handler.js.map

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