opensip-cli 0.1.0

package/dist/commands/shared.d.ts

@@ -0,0 +1,107 @@
+/**
+ * shared — the registrar context type used by every CLI-owned (host) command.
+ *
+ * Launch Phase 6 moved the host commands onto the declarative
+ * `CommandSpec` plane (`host-command-specs.ts` / `host-subcommand-groups.ts`),
+ * which sources `--cwd` / `--json` from the ADR-0021 common-flag registry
+ * directly (via `commonFlags: ['cwd', 'json']`). The former
+ * `CWD_OPTION_SPEC` / `JSON_DESC` re-export constants — used only by the
+ * deleted `register-*.ts` registrars — are gone; this module now carries just
+ * the shared context type.
+ */
+import type { SpecLike } from './completion.js';
+import type { SessionReplayRegistry } from '../session-replay-registry.js';
+import type { CommandResult } from '@opensip-cli/contracts';
+import type { PluginLayout, ScaffoldContext, ScaffoldFile } from '@opensip-cli/core';
+/**
+ * One registered tool's `init`-scaffold contribution (ADR-0038): its structural
+ * `pluginLayout` (domain + userSubdirs the host `mkdir`s) plus the optional
+ * tool-owned example/config hooks. Derived from the tool registry by the host; the
+ * init command iterates these instead of hardcoding fit/sim.
+ */
+export interface ToolScaffold {
+    readonly layout: PluginLayout;
+    readonly scaffoldExamples?: (ctx: ScaffoldContext) => readonly ScaffoldFile[];
+    readonly stableExampleIds?: () => readonly string[];
+    readonly scaffoldConfigBlock?: () => string;
+}
+/**
+ * Context the orchestrator (`registerCliCommands`) hands to every
+ * sub-registrar. The `setExitCode` write path mirrors `ToolCliContext`'s
+ * — exit-code mutations route through here, never through direct
+ * `process.exitCode` writes.
+ */
+export interface CliCommandsContext {
+    readonly setExitCode: (code: number) => void;
+    readonly render: (result: CommandResult) => Promise<void>;
+    /**
+     * Success machine-output seam — wraps the value in a `CommandOutcome` via the
+     * single `renderOutcome` seam (launch, §5.5). Always supplied by the host
+     * (sourced from {@link ToolCliContext.emitJson}); required so raw-stream host
+     * commands (`sessions show`) never fall back to a direct `process.stdout.write`.
+     */
+    readonly emitJson: (value: unknown) => void;
+    /**
+     * RAW_STREAM machine-output seam — the host-command mirror of
+     * {@link ToolCliContext.emitRaw}. Emits the bare, unwrapped payload for a host
+     * command that declares `output:'raw-stream'` (`sessions show --raw`), so it
+     * never falls back to a direct `process.stdout.write`; the actual write lives
+     * in the single `renderRaw` seam.
+     */
+    readonly emitRaw: (value: unknown) => void;
+    /**
+     * Structured-error machine-output seam (launch, §5.5) — the host-command
+     * mirror of {@link ToolCliContext.emitError}. A failed `--json` host command
+     * (e.g. `sessions show`) emits its diagnosed failure through here so it rides
+     * the single `renderOutcome` seam as a `status:'error'` `CommandOutcome`,
+     * never a bare `emitJson({ error })`. Sourced from the same context closure as
+     * the tool seam, so exit code and reported outcome stay in agreement.
+     */
+    readonly emitError: (detail: {
+        readonly message: string;
+        readonly exitCode: number;
+        readonly suggestion?: string;
+        readonly code?: string;
+    }) => void;
+    /**
+     * Project-local plugin layouts contributed by the registered tools
+     * (each tool's `Tool.pluginLayout`). The `plugin` command reads these
+     * to know which domains support project-local plugins instead of
+     * hardcoding `['fit', 'sim']` — the kernel stays tool-agnostic and the
+     * tools remain the single source of truth (ADR-0009 corollary 1).
+     */
+    readonly pluginLayouts: readonly PluginLayout[];
+    /**
+     * Per-tool `init`-scaffold contributions (ADR-0038), derived from the tool
+     * registry. The `init` command iterates these — each tool's `pluginLayout` +
+     * `scaffoldExamples` — instead of hardcoding the fit/sim directories + example
+     * content. A tool with no `pluginLayout` contributes nothing (e.g. `graph`).
+     */
+    readonly toolScaffolds: readonly ToolScaffold[];
+    readonly sessionReplayRegistry?: SessionReplayRegistry;
+    /**
+     * The live tool command specs (each registered tool's `commandSpecs`),
+     * supplied by the composition root. The `completion` command derives its
+     * shell-completion subcommands + flags from these — the same source of truth
+     * the runtime mounts — so the emitted script can never drift from the real
+     * tool command surface. Typed structurally ({@link SpecLike}) to keep this
+     * module free of the full `CommandSpec` generic. Optional so test harnesses
+     * that don't exercise completion can omit it (completion then offers the host
+     * surface only).
+     */
+    readonly toolCommandSpecs?: readonly SpecLike[];
+    /**
+     * Persistence accessor (thunk). Calling this returns the project-local
+     * DataStore, opening it lazily on first access. Commands that don't read
+     * the datastore (dry-runs, list-style commands, completion) never trigger
+     * the SQLite open and therefore don't materialise `.runtime/`. Loosely
+     * typed `unknown` to keep this module free of `@opensip-cli/datastore`
+     * at the type level; consumers cast to `DataStore` at use time.
+     *
+     * Throws when called in a non-project context — CLI commands that need
+     * the datastore should already have errored on `project.scope === 'none'`
+     * before reaching this call.
+     */
+    readonly datastore: () => unknown;
+}
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/commands/shared.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErF;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,SAAS,YAAY,EAAE,CAAC;IAC9E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE;QAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;KACxB,KAAK,IAAI,CAAC;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,YAAY,EAAE,CAAC;IAChD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IACvD;;;;;;;;;OASG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAChD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;CACnC"}

package/dist/commands/shared.js

@@ -0,0 +1,13 @@
+/**
+ * shared — the registrar context type used by every CLI-owned (host) command.
+ *
+ * Launch Phase 6 moved the host commands onto the declarative
+ * `CommandSpec` plane (`host-command-specs.ts` / `host-subcommand-groups.ts`),
+ * which sources `--cwd` / `--json` from the ADR-0021 common-flag registry
+ * directly (via `commonFlags: ['cwd', 'json']`). The former
+ * `CWD_OPTION_SPEC` / `JSON_DESC` re-export constants — used only by the
+ * deleted `register-*.ts` registrars — are gone; this module now carries just
+ * the shared context type.
+ */
+export {};
+//# sourceMappingURL=shared.js.map

package/dist/commands/shared.js.map

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

package/dist/commands/tools/data-purge.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `tools data-purge <tool-id>` — per-tool project-data removal (ADR-0042).
+ *
+ * Rows, never tables: one tool's sessions (payload rows cascade via the
+ * schema FK), baseline entries + meta, and tool_state rows, all through
+ * repository APIs — no SQL in command code (`restrict-raw-db-access`).
+ * Project-scoped by nature (the datastore is per-project). Works for ANY
+ * tool id including bundled ones (purging fit history is legitimate).
+ *
+ * Surface note: the spec drafted `tools data purge` (a nested group); the
+ * host group machinery is deliberately one level deep (a nested action-less
+ * `data` shell would need its own parity-allowlist entry, completion
+ * inventory, and mounter recursion for one leaf), so this ships flattened as
+ * `data-purge`. Recorded as a plan deviation.
+ */
+import { type DataStore } from '@opensip-cli/datastore';
+import type { ToolsDataPurgeResult } from '@opensip-cli/contracts';
+/** Purge one tool's rows from the project datastore; reports counts. */
+export declare function toolsDataPurge(toolId: string, datastore: DataStore): ToolsDataPurgeResult;
+//# sourceMappingURL=data-purge.d.ts.map

package/dist/commands/tools/data-purge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-purge.d.ts","sourceRoot":"","sources":["../../../src/commands/tools/data-purge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,OAAO,EAA+B,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAGrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAgBnE,wEAAwE;AACxE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,oBAAoB,CAwBzF"}

package/dist/commands/tools/data-purge.js

@@ -0,0 +1,59 @@
+/**
+ * `tools data-purge <tool-id>` — per-tool project-data removal (ADR-0042).
+ *
+ * Rows, never tables: one tool's sessions (payload rows cascade via the
+ * schema FK), baseline entries + meta, and tool_state rows, all through
+ * repository APIs — no SQL in command code (`restrict-raw-db-access`).
+ * Project-scoped by nature (the datastore is per-project). Works for ANY
+ * tool id including bundled ones (purging fit history is legitimate).
+ *
+ * Surface note: the spec drafted `tools data purge` (a nested group); the
+ * host group machinery is deliberately one level deep (a nested action-less
+ * `data` shell would need its own parity-allowlist entry, completion
+ * inventory, and mounter recursion for one leaf), so this ships flattened as
+ * `data-purge`. Recorded as a plan deviation.
+ */
+import { isToolLongId, isToolShortId, TOOL_LONG_TO_SHORT, TOOL_SHORT_TO_LONG, } from '@opensip-cli/core';
+import { BaselineRepo, ToolStateRepo } from '@opensip-cli/datastore';
+import { SessionRepo } from '@opensip-cli/session-store';
+/**
+ * Every id form one user-supplied tool id may appear under across the stores.
+ * The stores key inconsistently for historical reasons (`core/tools/ids.ts`):
+ * sessions key the SHORT form (`fit`); the baseline plane keys the LONG form
+ * (`fitness`); tool-state keys whatever the tool passed. Purging clears every
+ * form — a per-store key namespace makes clearing an absent form a 0-count
+ * no-op, so this is robust rather than wasteful.
+ */
+function idFormsFor(toolId) {
+    if (isToolLongId(toolId))
+        return [...new Set([toolId, TOOL_LONG_TO_SHORT[toolId]])];
+    if (isToolShortId(toolId))
+        return [...new Set([toolId, TOOL_SHORT_TO_LONG[toolId]])];
+    return [toolId];
+}
+/** Purge one tool's rows from the project datastore; reports counts. */
+export function toolsDataPurge(toolId, datastore) {
+    const sessionRepo = new SessionRepo(datastore);
+    const baselineRepo = new BaselineRepo(datastore);
+    const stateRepo = new ToolStateRepo(datastore);
+    let sessions = 0;
+    let baselineEntries = 0;
+    let baselineMeta = false;
+    let stateRows = 0;
+    for (const form of idFormsFor(toolId)) {
+        sessions += sessionRepo.clearForTool(form);
+        const baseline = baselineRepo.clear(form);
+        baselineEntries += baseline.entries;
+        baselineMeta = baselineMeta || baseline.meta;
+        stateRows += stateRepo.clear(form);
+    }
+    return {
+        type: 'tools-data-purge',
+        toolId,
+        sessions,
+        baselineEntries,
+        baselineMeta,
+        stateRows,
+    };
+}
+//# sourceMappingURL=data-purge.js.map

package/dist/commands/tools/data-purge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-purge.js","sourceRoot":"","sources":["../../../src/commands/tools/data-purge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,YAAY,EACZ,aAAa,EACb,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,YAAY,EAAE,aAAa,EAAkB,MAAM,wBAAwB,CAAC;AACrF,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAIzD;;;;;;;GAOG;AACH,SAAS,UAAU,CAAC,MAAc;IAChC,IAAI,YAAY,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACpF,IAAI,aAAa,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,OAAO,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,SAAoB;IACjE,MAAM,WAAW,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,IAAI,YAAY,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,SAAS,CAAC,CAAC;IAE/C,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,QAAQ,IAAI,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1C,eAAe,IAAI,QAAQ,CAAC,OAAO,CAAC;QACpC,YAAY,GAAG,YAAY,IAAI,QAAQ,CAAC,IAAI,CAAC;QAC7C,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC;IACD,OAAO;QACL,IAAI,EAAE,kBAAkB;QACxB,MAAM;QACN,QAAQ;QACR,eAAe;QACf,YAAY;QACZ,SAAS;KACV,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,16 @@
+/**
+ * tools — the customer-facing whole-tool management group (ADR-0041).
+ *
+ * Leaf {@link CommandSpec} builders for the `tools` subcommand group, mounted
+ * by `host-subcommand-groups.ts` exactly as the `sessions`/`plugin` groups
+ * are. Subcommands ONLY — no flag aliases, no `tool` singular (the parity
+ * snapshot pins this). Later phases append leaves here
+ * (validate/install/uninstall/data purge).
+ */
+import { type CommandSpec } from '@opensip-cli/core';
+import type { CliCommandsContext } from '../shared.js';
+type HostSpec = CommandSpec<unknown, CliCommandsContext>;
+/** Build the `tools` group's leaf specs (consumed by the group mounter). */
+export declare function buildToolsGroupLeaves(ctx: CliCommandsContext): readonly HostSpec[];
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,mBAAmB,CAAC;AAQ3B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGvD,KAAK,QAAQ,GAAG,WAAW,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;AA8MzD,4EAA4E;AAC5E,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,QAAQ,EAAE,CAQlF"}

package/dist/commands/tools/index.js

@@ -0,0 +1,213 @@
+/**
+ * tools — the customer-facing whole-tool management group (ADR-0041).
+ *
+ * Leaf {@link CommandSpec} builders for the `tools` subcommand group, mounted
+ * by `host-subcommand-groups.ts` exactly as the `sessions`/`plugin` groups
+ * are. Subcommands ONLY — no flag aliases, no `tool` singular (the parity
+ * snapshot pins this). Later phases append leaves here
+ * (validate/install/uninstall/data purge).
+ */
+import { EXIT_CODES } from '@opensip-cli/contracts';
+import { currentScope, defineCommand, } from '@opensip-cli/core';
+import { toolsDataPurge } from './data-purge.js';
+import { toolsInstall } from './install.js';
+import { toolsList } from './list.js';
+import { toolsUninstall } from './uninstall.js';
+import { runToolValidation } from './validate.js';
+const COMMAND_RESULT_OUTPUT = 'command-result';
+/**
+ * Prefer the discovered project root; fall back to literal cwd; finally
+ * process.cwd(). (Local copy of the group module's `effectiveCwd` — importing
+ * it from `host-subcommand-groups.ts` would close a module cycle, since that
+ * module imports this group's leaves.)
+ */
+function effectiveCwd(opts) {
+    return opts.projectContext?.projectRoot ?? opts.cwd ?? process.cwd();
+}
+function buildToolsListSpec() {
+    return defineCommand({
+        name: 'list',
+        description: 'List the effective tool set (bundled, global, and project-local)',
+        commonFlags: ['json'],
+        options: [
+            { flag: '--global', description: 'Only user-global installed tools', default: false },
+            { flag: '--project', description: 'Only project-local installed tools', default: false },
+        ],
+        // Listing must work outside a project too (global tools are still
+        // visible); the project host dir simply scans empty there.
+        scope: 'none',
+        output: COMMAND_RESULT_OUTPUT,
+        handler: (rawOpts) => {
+            const opts = rawOpts;
+            // The admitted-tool set is per-run state on the entered RunScope (stamped
+            // by the bootstrap), read here and passed into the pure `toolsList`.
+            const scope = currentScope();
+            return Promise.resolve(toolsList({
+                cwd: effectiveCwd(opts),
+                global: opts.global,
+                project: opts.project,
+                provenance: scope?.toolProvenance ?? [],
+                manifests: scope?.toolManifests ?? [],
+            }));
+        },
+    });
+}
+function buildToolsValidateSpec(ctx) {
+    return defineCommand({
+        name: 'validate',
+        description: 'Validate a tool package against the Tool contract (runs the package module — see docs)',
+        commonFlags: ['json'],
+        args: [{ name: 'spec', description: 'npm spec, tarball, or local directory path' }],
+        options: [
+            {
+                flag: '--install-deps',
+                description: 'For a local path: stage via npm install so the runtime sections can load',
+                default: false,
+            },
+        ],
+        scope: 'none',
+        output: COMMAND_RESULT_OUTPUT,
+        handler: async (rawOpts) => {
+            const opts = rawOpts;
+            const spec = opts._args[0] ?? '';
+            const { result } = await runToolValidation({
+                spec,
+                cwd: effectiveCwd(opts),
+                installDeps: opts.installDeps,
+            });
+            if (result.verdict !== 'passed')
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+            return result;
+        },
+    });
+}
+function buildToolsInstallSpec(ctx) {
+    return defineCommand({
+        name: 'install',
+        description: 'Validate, then install a tool package (global by default; see tools validate)',
+        commonFlags: ['json'],
+        args: [{ name: 'spec', description: 'npm spec, tarball, or local directory path' }],
+        options: [
+            { flag: '--global', description: 'Install user-global (the default)', default: false },
+            {
+                flag: '--project',
+                description: 'Install into this project’s runtime tool host instead',
+                default: false,
+            },
+        ],
+        scope: 'none',
+        output: COMMAND_RESULT_OUTPUT,
+        handler: async (rawOpts) => {
+            const opts = rawOpts;
+            if (opts.global === true && opts.project === true) {
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+                return {
+                    type: 'tools-uninstall',
+                    target: opts._args[0] ?? '',
+                    success: false,
+                    error: '--global and --project are mutually exclusive',
+                };
+            }
+            const result = await toolsInstall({
+                spec: opts._args[0] ?? '',
+                cwd: effectiveCwd(opts),
+                project: opts.project,
+            });
+            if (!result.success)
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+            return result;
+        },
+    });
+}
+function buildToolsUninstallSpec(ctx) {
+    return defineCommand({
+        name: 'uninstall',
+        description: 'Uninstall a tool by id or package name (never deletes project SQLite data)',
+        commonFlags: ['json'],
+        args: [{ name: 'name-or-id', description: 'Tool id or npm package name' }],
+        options: [
+            { flag: '--global', description: 'Target the user-global install', default: false },
+            { flag: '--project', description: 'Target the project-local install', default: false },
+            {
+                flag: '--purge-data',
+                description: 'Also purge the tool’s project SQLite rows (project scope only)',
+                default: false,
+            },
+        ],
+        scope: 'none',
+        output: COMMAND_RESULT_OUTPUT,
+        // eslint-disable-next-line @typescript-eslint/require-await -- async keeps the CommandSpec handler signature; the bodies are synchronous SQLite + fs
+        handler: async (rawOpts) => {
+            const opts = rawOpts;
+            // --purge-data is project-local only: runtime data lives per project
+            // (the spec's explicit rejection for --global).
+            if (opts.purgeData === true && opts.global === true) {
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+                return {
+                    type: 'tools-uninstall',
+                    target: opts._args[0] ?? '',
+                    success: false,
+                    error: '--purge-data is project-local only (runtime data lives per project); it cannot combine with --global',
+                };
+            }
+            const result = toolsUninstall({
+                target: opts._args[0] ?? '',
+                cwd: effectiveCwd(opts),
+                global: opts.global,
+                project: opts.project,
+                // Per-run admitted-tool provenance (bundled-id guard) from the scope.
+                provenance: currentScope()?.toolProvenance ?? [],
+            });
+            if (!result.success) {
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+                return result;
+            }
+            if (opts.purgeData === true && result.removed?.scope === 'project') {
+                const datastore = ctx.datastore();
+                if (datastore !== undefined) {
+                    // Purge AFTER a successful project uninstall; counts ride stderr so
+                    // the uninstall result stays the command's one payload.
+                    const purge = toolsDataPurge(result.removed.id, datastore);
+                    process.stderr.write(`opensip: purged ${purge.sessions} session(s), ${purge.baselineEntries} baseline entr(ies), ` +
+                        `${purge.stateRows} state row(s) for '${purge.toolId}'\n`);
+                }
+            }
+            return result;
+        },
+    });
+}
+function buildToolsDataPurgeSpec(ctx) {
+    return defineCommand({
+        name: 'data-purge',
+        description: 'Delete one tool’s project SQLite rows (sessions, baselines, state) — never tables',
+        commonFlags: ['json'],
+        args: [{ name: 'tool-id', description: 'The tool id whose rows to delete' }],
+        scope: 'project',
+        output: COMMAND_RESULT_OUTPUT,
+        handler: (rawOpts) => {
+            const opts = rawOpts;
+            const datastore = ctx.datastore();
+            if (datastore === undefined) {
+                ctx.setExitCode(EXIT_CODES.CONFIGURATION_ERROR);
+                return Promise.resolve({
+                    type: 'tools-uninstall',
+                    target: opts._args[0] ?? '',
+                    success: false,
+                    error: 'tools data-purge requires the project datastore (run inside a project)',
+                });
+            }
+            return Promise.resolve(toolsDataPurge(opts._args[0] ?? '', datastore));
+        },
+    });
+}
+/** Build the `tools` group's leaf specs (consumed by the group mounter). */
+export function buildToolsGroupLeaves(ctx) {
+    return [
+        buildToolsListSpec(),
+        buildToolsValidateSpec(ctx),
+        buildToolsInstallSpec(ctx),
+        buildToolsUninstallSpec(ctx),
+        buildToolsDataPurgeSpec(ctx),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/tools/index.js.map

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

package/dist/commands/tools/install.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `tools install` — atomic stage → validate → activate (ADR-0041).
+ *
+ * The candidate stages into a temp host (npm `--ignore-scripts`) and the FULL
+ * validation (`runToolValidation`, keepStaged) runs against the staged bytes.
+ * Only a `passed` verdict activates — and activation installs a tarball
+ * `npm pack`ed FROM THE STAGED DIR, never a re-resolve of the original spec
+ * (a registry re-resolve between validate and activate could deliver
+ * different bytes than the ones validated; and `npm install <dir>` would
+ * symlink the about-to-be-deleted temp host). A failed install leaves no
+ * discoverable tool behind: the temp host is removed in `finally` and the
+ * scope host is never touched.
+ */
+import type { ToolsInstallResult } from '@opensip-cli/contracts';
+/** Options for {@link toolsInstall}. */
+export interface ToolsInstallOptions {
+    readonly spec: string;
+    readonly cwd: string;
+    /** Install into the project `.runtime` tool host instead of user-global. */
+    readonly project?: boolean;
+}
+/** Stage, validate, and (on a `passed` verdict only) activate one tool package. */
+export declare function toolsInstall(opts: ToolsInstallOptions): Promise<ToolsInstallResult>;
+//# sourceMappingURL=install.d.ts.map

package/dist/commands/tools/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/commands/tools/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAaD,mFAAmF;AACnF,wBAAsB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0DzF"}

package/dist/commands/tools/install.js

@@ -0,0 +1,83 @@
+/**
+ * `tools install` — atomic stage → validate → activate (ADR-0041).
+ *
+ * The candidate stages into a temp host (npm `--ignore-scripts`) and the FULL
+ * validation (`runToolValidation`, keepStaged) runs against the staged bytes.
+ * Only a `passed` verdict activates — and activation installs a tarball
+ * `npm pack`ed FROM THE STAGED DIR, never a re-resolve of the original spec
+ * (a registry re-resolve between validate and activate could deliver
+ * different bytes than the ones validated; and `npm install <dir>` would
+ * symlink the about-to-be-deleted temp host). A failed install leaves no
+ * discoverable tool behind: the temp host is removed in `finally` and the
+ * scope host is never touched.
+ */
+import { execFileSync } from 'node:child_process';
+import { admitToolPackage } from '../../bootstrap/admit-tool-package.js';
+import { addToolPlugin } from '../plugin-host-ops.js';
+import { runToolValidation } from './validate.js';
+/** Pack the staged package dir into a tarball beside it; returns the tarball path. */
+function packStagedDir(stagedPkgDir) {
+    const out = execFileSync('npm', ['pack', '--pack-destination', stagedPkgDir, '.'], {
+        cwd: stagedPkgDir,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', process.stderr],
+    });
+    const name = out.trim().split('\n').at(-1)?.trim() ?? '';
+    return `${stagedPkgDir}/${name}`;
+}
+/** Stage, validate, and (on a `passed` verdict only) activate one tool package. */
+export async function toolsInstall(opts) {
+    const scope = opts.project === true ? 'project' : 'global';
+    const { result, stagedPkgDir, cleanup } = await runToolValidation({ spec: opts.spec, cwd: opts.cwd, installDeps: true }, { keepStaged: true });
+    try {
+        if (result.verdict !== 'passed') {
+            return { type: 'tools-install', spec: opts.spec, success: false, scope, validation: result };
+        }
+        /* v8 ignore next 9 -- defensive: a passed verdict from a keepStaged run always carries the staged dir */
+        if (stagedPkgDir === undefined) {
+            return {
+                type: 'tools-install',
+                spec: opts.spec,
+                success: false,
+                scope,
+                validation: result,
+                error: 'validation passed but no staged package dir was retained',
+            };
+        }
+        // Activate the VALIDATED bytes: pack the staged dir, install the tarball.
+        const tarball = packStagedDir(stagedPkgDir);
+        const activation = addToolPlugin(tarball, opts.cwd, opts.project === true);
+        if (activation.type !== 'plugin-add' || activation.success !== true) {
+            const error = 'error' in activation ? (activation.error ?? 'activation failed') : 'activation failed';
+            return {
+                type: 'tools-install',
+                spec: opts.spec,
+                success: false,
+                scope,
+                validation: result,
+                error,
+            };
+        }
+        // Inventory row from the ACTIVATED install (manifest file read — no import).
+        const report = await admitToolPackage({
+            dir: stagedPkgDir,
+            source: 'installed',
+            explicitlyRequested: true,
+            staticOnly: true,
+        });
+        return {
+            type: 'tools-install',
+            spec: opts.spec,
+            success: true,
+            scope,
+            validation: result,
+            ...(report.manifest === undefined
+                ? {}
+                : { toolId: report.manifest.id, version: report.manifest.version }),
+        };
+    }
+    finally {
+        cleanup();
+    }
+}
+//# sourceMappingURL=install.js.map

package/dist/commands/tools/install.js.map

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

package/dist/commands/tools/list.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `tools list` — the read-only effective-tool inventory (ADR-0041).
+ *
+ * HARD RULE: this command performs ZERO dynamic imports of tool runtimes. A
+ * listing command that executes plugin code is both slow and a consent
+ * violation (the trust posture reserves code execution for validate/install).
+ * Every row derives from
+ *
+ *   - the CURRENT RUN's admitted set — the provenance + manifest pairs the
+ *     bootstrap recorded, passed in by the command handler from the entered
+ *     RunScope (`currentScope().toolProvenance` / `?.toolManifests`),
+ *     status `loaded`; and
+ *   - marker scans of the two install hosts (user-global + project
+ *     `.runtime`), `loadToolManifest` only (a file read), status
+ *     `manifest-only` — covering installed-but-not-loaded packages (and, by
+ *     construction, a package whose module top-level would throw).
+ *
+ * Shadow-marking: discovery is first-occurrence-wins (project before global in
+ * `buildToolDiscoverySources`), so when a project row and a global row share a
+ * tool id the GLOBAL row is marked shadowed.
+ */
+import { type ToolPluginManifest, type ToolProvenance } from '@opensip-cli/core';
+import type { ToolsListResult } from '@opensip-cli/contracts';
+/** Options for {@link toolsList}. */
+export interface ToolsListOptions {
+    readonly cwd: string;
+    /** Restrict to one install scope (mutually exclusive; neither = effective set). */
+    readonly global?: boolean;
+    readonly project?: boolean;
+    /**
+     * The admitted-tool provenance + manifests for this run (paired index-wise),
+     * read by the command handler from the entered RunScope and passed in so this
+     * function stays a pure function of its inputs. Default `[]` (no admitted set
+     * — e.g. an isolated unit test).
+     */
+    readonly provenance?: readonly ToolProvenance[];
+    readonly manifests?: readonly ToolPluginManifest[];
+}
+/** Build the effective tool inventory. Read-only; never imports a runtime. */
+export declare function toolsList(opts: ToolsListOptions): ToolsListResult;
+//# sourceMappingURL=list.d.ts.map

package/dist/commands/tools/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/commands/tools/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAKL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,wBAAwB,CAAC;AAK5E,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAwBD,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,eAAe,CA2DjE"}