opensip-cli 0.1.0

package/dist/bootstrap/scope-access.js

@@ -0,0 +1,115 @@
+/**
+ * scope-access — per-run scope + datastore readers.
+ *
+ * Extracted from `cli-context.ts` so that module stays focused on context
+ * ASSEMBLY (live-view registry + `buildToolCliContext`). This module owns the
+ * complementary concern: reading the entered `RunScope` and opening the
+ * project-local SQLite datastore lazily.
+ *
+ * After Phase 3 hygiene the ONLY way to obtain the per-run scope is
+ * `currentScope()` (entered by the pre-action-hook, or explicit `runWithScope`
+ * in tests). There are no holder fallbacks. Non-action paths (report, errors)
+ * that need scope must ensure entry or restructure to run inside an entered
+ * action.
+ */
+import { ConfigurationError, SystemError, currentScope, logger as defaultLogger, resolveProjectPaths, } from '@opensip-cli/core';
+import { DataStoreFactory } from '@opensip-cli/datastore';
+/**
+ * Strict reader: the only way to obtain the per-run scope is `currentScope()`
+ * (entered by pre-action-hook or explicit runWithScope in tests). All previous
+ * holder fallbacks were removed.
+ *
+ * @throws {SystemError} (`SYSTEM.SCOPE.NOT_ENTERED`) When accessed before the
+ *   pre-action-hook constructed and entered the scope.
+ */
+export function readScope() {
+    const bound = currentScope();
+    if (!bound) {
+        throw new SystemError('CLI scope accessed before pre-action-hook constructed and entered it (enterScope + ALS). ' +
+            'All production paths (tool actions, host commands, report/error seams) must run inside ' +
+            'an entered RunScope. See host-planes-scope-seams-hygiene plan Phase 3 and currentScope().', { code: 'SYSTEM.SCOPE.NOT_ENTERED' });
+    }
+    return bound;
+}
+/**
+ * Read the current project root. Convenience for non-tool bootstrap
+ * helpers (e.g. `maybeOpenReport`) that need the project root but
+ * don't carry a ToolCliContext.
+ *
+ * @throws {SystemError} (`SYSTEM.BOOTSTRAP.PROJECT_UNSET`) When accessed before
+ *   the pre-action-hook resolved the context.
+ */
+export function getCurrentProjectRoot() {
+    const project = readScope().projectContext;
+    if (!project) {
+        throw new SystemError('getCurrentProjectRoot() called before pre-action-hook resolved the context.', { code: 'SYSTEM.BOOTSTRAP.PROJECT_UNSET' });
+    }
+    return project.projectRoot;
+}
+/**
+ * Build a closure-based datastore thunk for the given project.
+ * Caches the open DataStore on first access. The pre-action-hook
+ * wires the result into `RunScope.datastore` so tools and CLI
+ * commands reach the same instance.
+ *
+ * @throws {SystemError} (`SYSTEM.BOOTSTRAP.DATASTORE_OUTSIDE_PROJECT`) When the
+ *   returned thunk is invoked outside a project scope — callers must check
+ *   `project.scope === 'project'` first or handle the throw as a "no project
+ *   found" error.
+ */
+export function buildDatastoreThunk(project, log = defaultLogger) {
+    let cached;
+    return () => {
+        if (cached)
+            return cached;
+        if (project.scope !== 'project') {
+            throw new SystemError('Datastore accessed in a non-project context. The action body should have ' +
+                'errored earlier with "No OpenSIP CLI project found" before touching this.', { code: 'SYSTEM.BOOTSTRAP.DATASTORE_OUTSIDE_PROJECT' });
+        }
+        const path = `${resolveProjectPaths(project.projectRoot).runtimeDir}/datastore.sqlite`;
+        cached = DataStoreFactory.open({ backend: 'sqlite', path });
+        log.info({
+            evt: 'cli.datastore.opened',
+            module: 'cli:context',
+            path,
+        });
+        return cached;
+    };
+}
+/**
+ * Open (or return cached) project-local SQLite DataStore via the
+ * scope's datastore thunk. Shared between tool action bodies and
+ * the host commands (e.g. `sessions`, in `host-subcommand-groups.ts`) so
+ * both paths are equally lazy.
+ *
+ * @throws {SystemError} When called outside a project scope — see
+ *   `buildDatastoreThunk`'s contract.
+ */
+export function getOrOpenDatastore(_log = defaultLogger) {
+    const thunk = readScope().datastore;
+    return thunk();
+}
+/**
+ * Project-scoped datastore accessor for the host-owned planes (baseline,
+ * toolState, hostPlanes). Converts the internal DATASTORE_OUTSIDE_PROJECT
+ * SystemError into a clear ConfigurationError so callers of the documented
+ * ToolCliContext seams get a user-actionable error (exit 2) instead of an
+ * internal SYSTEM.* code.
+ *
+ * @throws {ConfigurationError} When called outside a project scope (no open
+ *   datastore); other datastore-open failures propagate unchanged.
+ */
+export function getProjectDatastore() {
+    try {
+        return getOrOpenDatastore();
+    }
+    catch (error) {
+        if (error instanceof SystemError &&
+            error.code === 'SYSTEM.BOOTSTRAP.DATASTORE_OUTSIDE_PROJECT') {
+            throw new ConfigurationError('This operation requires an OpenSIP CLI project (an opensip-cli.config.yml with a targets: block or similar). ' +
+                'Run from within a project directory, or pass --cwd to an initialized project.', { code: 'CONFIGURATION.REQUIRES_PROJECT' });
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=scope-access.js.map

package/dist/bootstrap/scope-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-access.js","sourceRoot":"","sources":["../../src/bootstrap/scope-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,kBAAkB,EAIlB,WAAW,EACX,YAAY,EACZ,MAAM,IAAI,aAAa,EACvB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAkB,MAAM,wBAAwB,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CACnB,2FAA2F;YACzF,yFAAyF;YACzF,2FAA2F,EAC7F,EAAE,IAAI,EAAE,0BAA0B,EAAE,CACrC,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC,cAAc,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,6EAA6E,EAC7E,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAC3C,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAuB,EACvB,MAAc,aAAa;IAE3B,IAAI,MAA6B,CAAC;IAClC,OAAO,GAAG,EAAE;QACV,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,WAAW,CACnB,2EAA2E;gBACzE,2EAA2E,EAC7E,EAAE,IAAI,EAAE,4CAA4C,EAAE,CACvD,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,mBAAmB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,UAAU,mBAAmB,CAAC;QACvF,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,GAAG,CAAC,IAAI,CAAC;YACP,GAAG,EAAE,sBAAsB;YAC3B,MAAM,EAAE,aAAa;YACrB,IAAI;SACL,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,aAAa;IAC7D,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC,SAAS,CAAC;IACpC,OAAO,KAAK,EAAe,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,OAAO,kBAAkB,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,WAAW;YAC5B,KAAK,CAAC,IAAI,KAAK,4CAA4C,EAC3D,CAAC;YACD,MAAM,IAAI,kBAAkB,CAC1B,+GAA+G;gBAC7G,+EAA+E,EACjF,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAC3C,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/bootstrap/state-seams.d.ts

@@ -0,0 +1,14 @@
+/**
+ * state-seams — the host implementation behind the `ToolCliContext.toolState`
+ * grouped seam (ADR-0042): durable keyed JSON persistence over the host-owned
+ * `tool_state` table via `ToolStateRepo`. Mirrors `baseline-seams.ts`
+ * structurally (lazy datastore resolver; sync SQLite bodies typed Promise so a
+ * sync throw still rejects for an awaiting caller).
+ */
+import { type DataStore } from '@opensip-cli/datastore';
+import type { ToolCliContext } from '@opensip-cli/core';
+/** Build the `toolState` seam group over a lazy datastore resolver. */
+export declare function buildStateSeams(deps: {
+    readonly getDatastore: () => DataStore;
+}): ToolCliContext['toolState'];
+//# sourceMappingURL=state-seams.d.ts.map

package/dist/bootstrap/state-seams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-seams.d.ts","sourceRoot":"","sources":["../../src/bootstrap/state-seams.ts"],"names":[],"mappings":"AACA;;;;;;GAMG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,SAAS,CAAC;CACxC,GAAG,cAAc,CAAC,WAAW,CAAC,CAc9B"}

package/dist/bootstrap/state-seams.js

@@ -0,0 +1,26 @@
+// @fitness-ignore-file null-safety -- repoFor() returns a freshly constructed ToolStateRepo (never null); the heuristic misreads the fluent .put/.list calls
+/**
+ * state-seams — the host implementation behind the `ToolCliContext.toolState`
+ * grouped seam (ADR-0042): durable keyed JSON persistence over the host-owned
+ * `tool_state` table via `ToolStateRepo`. Mirrors `baseline-seams.ts`
+ * structurally (lazy datastore resolver; sync SQLite bodies typed Promise so a
+ * sync throw still rejects for an awaiting caller).
+ */
+import { ToolStateRepo } from '@opensip-cli/datastore';
+/** Build the `toolState` seam group over a lazy datastore resolver. */
+export function buildStateSeams(deps) {
+    const repoFor = () => new ToolStateRepo(deps.getDatastore());
+    return {
+        get: (tool, key) => Promise.resolve(repoFor().get(tool, key)),
+        put: (tool, key, payload) => {
+            repoFor().put(tool, key, payload);
+            return Promise.resolve();
+        },
+        delete: (tool, key) => {
+            repoFor().delete(tool, key);
+            return Promise.resolve();
+        },
+        list: (tool) => Promise.resolve(repoFor().list(tool)),
+    };
+}
+//# sourceMappingURL=state-seams.js.map

package/dist/bootstrap/state-seams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-seams.js","sourceRoot":"","sources":["../../src/bootstrap/state-seams.ts"],"names":[],"mappings":"AAAA,6JAA6J;AAC7J;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAkB,MAAM,wBAAwB,CAAC;AAIvE,uEAAuE;AACvE,MAAM,UAAU,eAAe,CAAC,IAE/B;IACC,MAAM,OAAO,GAAG,GAAkB,EAAE,CAAC,IAAI,aAAa,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAC5E,OAAO;QACL,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7D,GAAG,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE;YAC1B,OAAO,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;YAClC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;YACpB,OAAO,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC5B,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACtD,CAAC;AACJ,CAAC"}

package/dist/bootstrap/tool-lifecycle.d.ts

@@ -0,0 +1,102 @@
+/**
+ * tool-lifecycle — the NAMED, ordered tool-admission lifecycle (release
+ * launch, §5.4). A thin sequencer/driver that documents + orders the existing
+ * bootstrap calls into one canonical sequence, rather than re-architecting the
+ * individual hooks (which keep their own homes and contracts).
+ *
+ * The 10 steps span two temporal phases of a CLI invocation:
+ *
+ *   ── STARTUP (once per process, composition root) ──────────────────────────
+ *   1. DISCOVER  — enumerate tool sources: bundled first-party
+ *      ({@link registerFirstPartyTools}) + on-disk packages
+ *      ({@link discoverAndRegisterToolPackages} via
+ *      `discoverToolPackagesFromAnchors`).
+ *   2. COMPAT    — run each candidate's static `package.json#opensipTools`
+ *      manifest through the `admitTool` compatibility gate. Bundled = fail-
+ *      closed; installed = best-effort skip; project-local = trust-gated.
+ *   3. TRUST     — deny-by-default trust check for project-local executable
+ *      tools (`admitProjectLocalTool`), BEFORE any module import.
+ *   4. IMPORT    — dynamic-`import()` an admitted installed/project-local
+ *      package's entry, then VALIDATE the exported `tool` shape
+ *      (`isValidTool`) and REGISTER it into the `ToolRegistry`
+ *      (first-writer-wins). Steps 1-4 all complete inside {@link bootstrapCli}.
+ *   8. MOUNT     — walk the registry and mount each tool's declared
+ *      `commandSpecs` ({@link mountAllToolCommands}). Provenance stops mattering
+ *      here, so bundled and installed tools share the identical mount path.
+ *
+ *   ── PER-RUN (per invocation, pre-action hook) ─────────────────────────────
+ *   5. CONFIG    — compose every tool's `config` Zod block into one strict
+ *      whole-document schema and validate the config file once
+ *      (`composeAndValidateToolConfig`).
+ *   6. SCOPE     — each tool contributes its per-run subscope
+ *      (`tool.contributeScope()`); the kernel `Object.assign`s it onto the
+ *      `RunScope` before `enterScope`.
+ *   7. CAPABILITIES — wire the per-run capability registry: register each
+ *      manifest's declared domains, then replace the deferred placeholder with
+ *      the owning tool's real registrar (`wireCapabilityRegistry`).
+ *   9. INITIALIZE — lazy, memoized `tool.initialize()` for the tool owning the
+ *      invoked subcommand, exactly once per process, after `enterScope`
+ *      (`maybeInitializeOwningTool`).
+ *   10. DISPATCH — Commander invokes the command's action body; the
+ *       `mountCommandSpec` pipeline (parse → handler → dispatch → error → exit)
+ *       runs the tool's handler.
+ *
+ * Steps 5-7, 9, 10 are inherently per-invocation (they read the entered
+ * `RunScope`) and live in `pre-action-hook.ts`; this module does NOT move them
+ * — it names them so the full lifecycle has one documented source of truth and
+ * drives the contiguous STARTUP steps (discover→…→register, then mount) through
+ * one ordered entry point. The driver is intentionally THIN: it sequences the
+ * pre-existing helpers, it does not reimplement them.
+ */
+import type { CliProgram } from '@opensip-cli/contracts';
+import type { ToolCliContext, ToolRegistry } from '@opensip-cli/core';
+/**
+ * Canonical, ordered tool-lifecycle steps (launch, §5.4). The numeric
+ * values are the step ordinals used in the JSDoc above and in
+ * lifecycle-ordering tests; the string keys name each step. This is the single
+ * source of truth for the sequence — a test asserts the STARTUP driver fires
+ * its steps in this order.
+ */
+export declare const TOOL_LIFECYCLE_STEPS: {
+    /** 1 — enumerate bundled + on-disk tool sources. */
+    readonly discover: 1;
+    /** 2 — `admitTool` compatibility gate over the static manifest. */
+    readonly compat: 2;
+    /** 3 — deny-by-default trust check for project-local executable tools. */
+    readonly trust: 3;
+    /** 4 — import an admitted package, validate its shape, register it. */
+    readonly import: 4;
+    /** 5 — compose + strict-validate every tool's config block. */
+    readonly config: 5;
+    /** 6 — each tool contributes its per-run subscope. */
+    readonly scope: 6;
+    /** 7 — wire the per-run capability registry (manifest domains → registrars). */
+    readonly capabilities: 7;
+    /** 8 — mount each tool's declared commandSpecs. */
+    readonly mount: 8;
+    /** 9 — lazy, memoized initialize() for the invoked subcommand's owner. */
+    readonly initialize: 9;
+    /** 10 — Commander dispatches the action body through the mount pipeline. */
+    readonly dispatch: 10;
+};
+/**
+ * Drive the STARTUP-phase command-mount step (step 8) for every registered
+ * tool. By the time this runs, steps 1-4 have already populated `registry`
+ * inside {@link bootstrapCli} (provenance no longer matters — bundled and
+ * installed tools mount identically). This is the single ordered entry point
+ * the composition root calls for step 8, replacing the bare
+ * `mountAllToolCommands(...)` call so the lifecycle has one named seam.
+ *
+ * Kept THIN deliberately: it delegates straight to
+ * {@link mountAllToolCommands}, which mounts each tool's declared `commandSpecs`
+ * (the one command surface, launch) with per-tool failure isolation. The naming +
+ * ordering is the value here, not new logic.
+ *
+ * @param registry The per-invocation tool registry, already populated by
+ *   steps 1-4.
+ * @param program The root Commander program (host-owned; passed in since the tool
+ *   context no longer carries it, §8).
+ * @param ctx The per-invocation handler context handed to each mounted command.
+ */
+export declare function mountToolCommands(registry: ToolRegistry, program: CliProgram, ctx: ToolCliContext): void;
+//# sourceMappingURL=tool-lifecycle.d.ts.map

package/dist/bootstrap/tool-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-lifecycle.d.ts","sourceRoot":"","sources":["../../src/bootstrap/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B,oDAAoD;;IAEpD,mEAAmE;;IAEnE,0EAA0E;;IAE1E,uEAAuE;;IAEvE,+DAA+D;;IAE/D,sDAAsD;;IAEtD,gFAAgF;;IAEhF,mDAAmD;;IAEnD,0EAA0E;;IAE1E,4EAA4E;;CAEpE,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CAEN"}

package/dist/bootstrap/tool-lifecycle.js

@@ -0,0 +1,103 @@
+/**
+ * tool-lifecycle — the NAMED, ordered tool-admission lifecycle (release
+ * launch, §5.4). A thin sequencer/driver that documents + orders the existing
+ * bootstrap calls into one canonical sequence, rather than re-architecting the
+ * individual hooks (which keep their own homes and contracts).
+ *
+ * The 10 steps span two temporal phases of a CLI invocation:
+ *
+ *   ── STARTUP (once per process, composition root) ──────────────────────────
+ *   1. DISCOVER  — enumerate tool sources: bundled first-party
+ *      ({@link registerFirstPartyTools}) + on-disk packages
+ *      ({@link discoverAndRegisterToolPackages} via
+ *      `discoverToolPackagesFromAnchors`).
+ *   2. COMPAT    — run each candidate's static `package.json#opensipTools`
+ *      manifest through the `admitTool` compatibility gate. Bundled = fail-
+ *      closed; installed = best-effort skip; project-local = trust-gated.
+ *   3. TRUST     — deny-by-default trust check for project-local executable
+ *      tools (`admitProjectLocalTool`), BEFORE any module import.
+ *   4. IMPORT    — dynamic-`import()` an admitted installed/project-local
+ *      package's entry, then VALIDATE the exported `tool` shape
+ *      (`isValidTool`) and REGISTER it into the `ToolRegistry`
+ *      (first-writer-wins). Steps 1-4 all complete inside {@link bootstrapCli}.
+ *   8. MOUNT     — walk the registry and mount each tool's declared
+ *      `commandSpecs` ({@link mountAllToolCommands}). Provenance stops mattering
+ *      here, so bundled and installed tools share the identical mount path.
+ *
+ *   ── PER-RUN (per invocation, pre-action hook) ─────────────────────────────
+ *   5. CONFIG    — compose every tool's `config` Zod block into one strict
+ *      whole-document schema and validate the config file once
+ *      (`composeAndValidateToolConfig`).
+ *   6. SCOPE     — each tool contributes its per-run subscope
+ *      (`tool.contributeScope()`); the kernel `Object.assign`s it onto the
+ *      `RunScope` before `enterScope`.
+ *   7. CAPABILITIES — wire the per-run capability registry: register each
+ *      manifest's declared domains, then replace the deferred placeholder with
+ *      the owning tool's real registrar (`wireCapabilityRegistry`).
+ *   9. INITIALIZE — lazy, memoized `tool.initialize()` for the tool owning the
+ *      invoked subcommand, exactly once per process, after `enterScope`
+ *      (`maybeInitializeOwningTool`).
+ *   10. DISPATCH — Commander invokes the command's action body; the
+ *       `mountCommandSpec` pipeline (parse → handler → dispatch → error → exit)
+ *       runs the tool's handler.
+ *
+ * Steps 5-7, 9, 10 are inherently per-invocation (they read the entered
+ * `RunScope`) and live in `pre-action-hook.ts`; this module does NOT move them
+ * — it names them so the full lifecycle has one documented source of truth and
+ * drives the contiguous STARTUP steps (discover→…→register, then mount) through
+ * one ordered entry point. The driver is intentionally THIN: it sequences the
+ * pre-existing helpers, it does not reimplement them.
+ */
+import { mountAllToolCommands } from './register-tools.js';
+/**
+ * Canonical, ordered tool-lifecycle steps (launch, §5.4). The numeric
+ * values are the step ordinals used in the JSDoc above and in
+ * lifecycle-ordering tests; the string keys name each step. This is the single
+ * source of truth for the sequence — a test asserts the STARTUP driver fires
+ * its steps in this order.
+ */
+export const TOOL_LIFECYCLE_STEPS = {
+    /** 1 — enumerate bundled + on-disk tool sources. */
+    discover: 1,
+    /** 2 — `admitTool` compatibility gate over the static manifest. */
+    compat: 2,
+    /** 3 — deny-by-default trust check for project-local executable tools. */
+    trust: 3,
+    /** 4 — import an admitted package, validate its shape, register it. */
+    import: 4,
+    /** 5 — compose + strict-validate every tool's config block. */
+    config: 5,
+    /** 6 — each tool contributes its per-run subscope. */
+    scope: 6,
+    /** 7 — wire the per-run capability registry (manifest domains → registrars). */
+    capabilities: 7,
+    /** 8 — mount each tool's declared commandSpecs. */
+    mount: 8,
+    /** 9 — lazy, memoized initialize() for the invoked subcommand's owner. */
+    initialize: 9,
+    /** 10 — Commander dispatches the action body through the mount pipeline. */
+    dispatch: 10,
+};
+/**
+ * Drive the STARTUP-phase command-mount step (step 8) for every registered
+ * tool. By the time this runs, steps 1-4 have already populated `registry`
+ * inside {@link bootstrapCli} (provenance no longer matters — bundled and
+ * installed tools mount identically). This is the single ordered entry point
+ * the composition root calls for step 8, replacing the bare
+ * `mountAllToolCommands(...)` call so the lifecycle has one named seam.
+ *
+ * Kept THIN deliberately: it delegates straight to
+ * {@link mountAllToolCommands}, which mounts each tool's declared `commandSpecs`
+ * (the one command surface, launch) with per-tool failure isolation. The naming +
+ * ordering is the value here, not new logic.
+ *
+ * @param registry The per-invocation tool registry, already populated by
+ *   steps 1-4.
+ * @param program The root Commander program (host-owned; passed in since the tool
+ *   context no longer carries it, §8).
+ * @param ctx The per-invocation handler context handed to each mounted command.
+ */
+export function mountToolCommands(registry, program, ctx) {
+    mountAllToolCommands(registry, program, ctx);
+}
+//# sourceMappingURL=tool-lifecycle.js.map

package/dist/bootstrap/tool-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-lifecycle.js","sourceRoot":"","sources":["../../src/bootstrap/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAK3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oDAAoD;IACpD,QAAQ,EAAE,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,CAAC;IACT,0EAA0E;IAC1E,KAAK,EAAE,CAAC;IACR,uEAAuE;IACvE,MAAM,EAAE,CAAC;IACT,+DAA+D;IAC/D,MAAM,EAAE,CAAC;IACT,sDAAsD;IACtD,KAAK,EAAE,CAAC;IACR,gFAAgF;IAChF,YAAY,EAAE,CAAC;IACf,mDAAmD;IACnD,KAAK,EAAE,CAAC;IACR,0EAA0E;IAC1E,UAAU,EAAE,CAAC;IACb,4EAA4E;IAC5E,QAAQ,EAAE,EAAE;CACJ,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAsB,EACtB,OAAmB,EACnB,GAAmB;IAEnB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC"}

package/dist/bootstrap/tool-trust.d.ts

@@ -0,0 +1,49 @@
+/**
+ * tool-trust — the project-local executable-tool trust policy (release
+ * launch, Phase 3 Task 3.2).
+ *
+ * A `project-local` tool is authored code under `<project>/opensip-cli/…`
+ * that changes with the repo (§5.2.1). Running it imports arbitrary code
+ * from the working tree, so the host MUST make the trust decision explicit
+ * rather than load-by-presence.
+ *
+ * Policy for launch (signed off): **deny-by-default for non-interactive
+ * runs; admit-with-allowlist when configured.** No interactive prompt UX
+ * in this release. The allowlist is a comma/whitespace-separated list of
+ * tool ids in the `OPENSIP_CLI_ALLOW_PROJECT_TOOLS` environment variable
+ * — a minimal, documented opt-in:
+ *
+ *   OPENSIP_CLI_ALLOW_PROJECT_TOOLS="my-audit, my-lint"   # admit by id
+ *   OPENSIP_CLI_ALLOW_PROJECT_TOOLS="*"                    # admit all
+ *
+ * The decision is made BEFORE the tool's module is imported: a disallowed
+ * project-local tool is fail-closed (exit 5) without its code ever running.
+ */
+/**
+ * Environment variable carrying the project-local tool allowlist. Read
+ * once per decision (cheap), never cached, so a test can set/unset it
+ * around a single call.
+ */
+export declare const PROJECT_TOOL_ALLOWLIST_ENV = "OPENSIP_CLI_ALLOW_PROJECT_TOOLS";
+/**
+ * Decide whether a project-local executable tool with the given `id` is
+ * trusted to load, under the deny-by-default + allowlist-opt-in policy.
+ *
+ * **Env governance (pre-scope exception).** The allowlist var is declared as a
+ * first-class `EnvVarSpec` in `CLI_ENV_SPECS`
+ * (`OPENSIP_CLI_ALLOW_PROJECT_TOOLS`, `host-env-specs.ts`) — that declaration
+ * is the documentation home, so it appears in the generated env-surface
+ * reference. The read here stays on the INJECTED `env` param rather than
+ * `hostEnv.get(...)`: this trust check runs at BOOTSTRAP, before any `RunScope`
+ * exists, and the injectable seam is what keeps it unit-testable without
+ * mutating global `process.env` (the same posture the repo takes for
+ * `NODE_OPTIONS`). The `env-via-registry` guardrail is satisfied because this is
+ * an injected-param read (`env[...]`), not a raw `process.env.<NAME>` read.
+ *
+ * @param id The tool's stable id (from its sidecar manifest).
+ * @param env The environment to read the allowlist from (defaults to
+ *   `process.env`; injectable for tests).
+ * @returns `true` iff the allowlist contains `id` or the wildcard `'*'`.
+ */
+export declare function isProjectLocalToolTrusted(id: string, env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=tool-trust.d.ts.map

package/dist/bootstrap/tool-trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-trust.d.ts","sourceRoot":"","sources":["../../src/bootstrap/tool-trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,oCAAoC,CAAC;AAiB5E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,yBAAyB,CACvC,EAAE,EAAE,MAAM,EACV,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT"}

package/dist/bootstrap/tool-trust.js

@@ -0,0 +1,65 @@
+/**
+ * tool-trust — the project-local executable-tool trust policy (release
+ * launch, Phase 3 Task 3.2).
+ *
+ * A `project-local` tool is authored code under `<project>/opensip-cli/…`
+ * that changes with the repo (§5.2.1). Running it imports arbitrary code
+ * from the working tree, so the host MUST make the trust decision explicit
+ * rather than load-by-presence.
+ *
+ * Policy for launch (signed off): **deny-by-default for non-interactive
+ * runs; admit-with-allowlist when configured.** No interactive prompt UX
+ * in this release. The allowlist is a comma/whitespace-separated list of
+ * tool ids in the `OPENSIP_CLI_ALLOW_PROJECT_TOOLS` environment variable
+ * — a minimal, documented opt-in:
+ *
+ *   OPENSIP_CLI_ALLOW_PROJECT_TOOLS="my-audit, my-lint"   # admit by id
+ *   OPENSIP_CLI_ALLOW_PROJECT_TOOLS="*"                    # admit all
+ *
+ * The decision is made BEFORE the tool's module is imported: a disallowed
+ * project-local tool is fail-closed (exit 5) without its code ever running.
+ */
+/**
+ * Environment variable carrying the project-local tool allowlist. Read
+ * once per decision (cheap), never cached, so a test can set/unset it
+ * around a single call.
+ */
+export const PROJECT_TOOL_ALLOWLIST_ENV = 'OPENSIP_CLI_ALLOW_PROJECT_TOOLS';
+/**
+ * Parse the allowlist env var into a set of permitted tool ids. Empty/
+ * unset ⇒ empty set (deny-by-default). The wildcard `'*'` admits all
+ * (surfaced via {@link isProjectLocalToolTrusted}).
+ */
+function parseAllowlist(raw) {
+    if (!raw)
+        return new Set();
+    return new Set(raw
+        .split(/[\s,]+/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0));
+}
+/**
+ * Decide whether a project-local executable tool with the given `id` is
+ * trusted to load, under the deny-by-default + allowlist-opt-in policy.
+ *
+ * **Env governance (pre-scope exception).** The allowlist var is declared as a
+ * first-class `EnvVarSpec` in `CLI_ENV_SPECS`
+ * (`OPENSIP_CLI_ALLOW_PROJECT_TOOLS`, `host-env-specs.ts`) — that declaration
+ * is the documentation home, so it appears in the generated env-surface
+ * reference. The read here stays on the INJECTED `env` param rather than
+ * `hostEnv.get(...)`: this trust check runs at BOOTSTRAP, before any `RunScope`
+ * exists, and the injectable seam is what keeps it unit-testable without
+ * mutating global `process.env` (the same posture the repo takes for
+ * `NODE_OPTIONS`). The `env-via-registry` guardrail is satisfied because this is
+ * an injected-param read (`env[...]`), not a raw `process.env.<NAME>` read.
+ *
+ * @param id The tool's stable id (from its sidecar manifest).
+ * @param env The environment to read the allowlist from (defaults to
+ *   `process.env`; injectable for tests).
+ * @returns `true` iff the allowlist contains `id` or the wildcard `'*'`.
+ */
+export function isProjectLocalToolTrusted(id, env = process.env) {
+    const allow = parseAllowlist(env[PROJECT_TOOL_ALLOWLIST_ENV]);
+    return allow.has('*') || allow.has(id);
+}
+//# sourceMappingURL=tool-trust.js.map

package/dist/bootstrap/tool-trust.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-trust.js","sourceRoot":"","sources":["../../src/bootstrap/tool-trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,iCAAiC,CAAC;AAE5E;;;;GAIG;AACH,SAAS,cAAc,CAAC,GAAuB;IAC7C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,GAAG,EAAE,CAAC;IAC3B,OAAO,IAAI,GAAG,CACZ,GAAG;SACA,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,yBAAyB,CACvC,EAAU,EACV,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAC,CAAC;IAC9D,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACzC,CAAC"}

package/dist/bootstrap/validate-tool.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Runtime shape validation for third-party `tool` exports — the
+ * untrusted boundary where `discoverAndRegisterToolPackages` imports
+ * an arbitrary npm package and inspects whatever it exports.
+ *
+ * Verifies the minimal contract the registry depends on: a
+ * `metadata.id` string (used for dedupe + listing), a `commands` array,
+ * and a command surface — a non-empty `commandSpecs` array (the one command
+ * surface as of launch; `register()` was removed). A tool with no `commandSpecs`
+ * cannot mount any command, so it fails the shape check. `initialize` and
+ * `contributeScope` stay optional per the Tool interface.
+ *
+ * Ordering vs. the admission gate: this shape check runs AFTER a
+ * tool's module is imported. The compatibility gate (`admitTool`) and the
+ * project-local TRUST gate (`admitProjectLocalTool`, deny-by-default) run
+ * on the STATIC manifest *before* import — so a project-local executable
+ * tool that is not allowlisted is fail-closed without its code ever running,
+ * and never reaches `isValidTool`.
+ */
+import type { Tool } from '@opensip-cli/core';
+export declare function isValidTool(value: unknown): value is Tool;
+//# sourceMappingURL=validate-tool.d.ts.map

package/dist/bootstrap/validate-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-tool.d.ts","sourceRoot":"","sources":["../../src/bootstrap/validate-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAgBzD"}

package/dist/bootstrap/validate-tool.js

@@ -0,0 +1,38 @@
+/**
+ * Runtime shape validation for third-party `tool` exports — the
+ * untrusted boundary where `discoverAndRegisterToolPackages` imports
+ * an arbitrary npm package and inspects whatever it exports.
+ *
+ * Verifies the minimal contract the registry depends on: a
+ * `metadata.id` string (used for dedupe + listing), a `commands` array,
+ * and a command surface — a non-empty `commandSpecs` array (the one command
+ * surface as of launch; `register()` was removed). A tool with no `commandSpecs`
+ * cannot mount any command, so it fails the shape check. `initialize` and
+ * `contributeScope` stay optional per the Tool interface.
+ *
+ * Ordering vs. the admission gate: this shape check runs AFTER a
+ * tool's module is imported. The compatibility gate (`admitTool`) and the
+ * project-local TRUST gate (`admitProjectLocalTool`, deny-by-default) run
+ * on the STATIC manifest *before* import — so a project-local executable
+ * tool that is not allowlisted is fail-closed without its code ever running,
+ * and never reaches `isValidTool`.
+ */
+export function isValidTool(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    if (typeof candidate.metadata !== 'object' || candidate.metadata === null)
+        return false;
+    if (typeof candidate.metadata.id !== 'string')
+        return false;
+    if (!Array.isArray(candidate.commands))
+        return false;
+    // A tool must expose a command surface: a non-empty declarative `commandSpecs`
+    // array (the one command surface, launch — `register()` was removed). A tool
+    // with no commandSpecs cannot contribute any command and is rejected.
+    const hasSpecs = Array.isArray(candidate.commandSpecs) && candidate.commandSpecs.length > 0;
+    if (!hasSpecs)
+        return false;
+    return true;
+}
+//# sourceMappingURL=validate-tool.js.map

package/dist/bootstrap/validate-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-tool.js","sourceRoot":"","sources":["../../src/bootstrap/validate-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAIjB,CAAC;IACF,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,QAAQ,IAAI,SAAS,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACxF,IAAI,OAAQ,SAAS,CAAC,QAA6B,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,+EAA+E;IAC/E,6EAA6E;IAC7E,sEAAsE;IACtE,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5F,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/cli-context.d.ts

@@ -0,0 +1,38 @@
+/**
+ * cli-context — the thin `ToolCliContext` assembler (host-owned-run-timing
+ * Phase 6). `buildToolCliContext` wires together the focused host planes —
+ * output, egress, run, live, baseline, state, host-planes — into the single
+ * coherent context handed to each tool and host command. Each concern's logic
+ * lives in its own `bootstrap/*-plane` (or `*-seams`) module; this file only
+ * composes them and exposes the `scope` getter + the assembled context.
+ *
+ * There is NO module-global bootstrap-handoff bag. The populated registries +
+ * admitted-tool manifests/provenance are captured in the pre-action-hook closure
+ * (`installPreActionHook` is called AFTER `bootstrapCli` in `main()`), the hook
+ * builds + enters the per-run `RunScope`, and from there every per-run read
+ * (project, datastore, manifests, provenance, …) goes through `currentScope()`.
+ *
+ * Lazy datastore: a closure-based thunk caches the open DataStore on first access and
+ * lands on `RunScope.datastore`; paths that never touch it never materialise
+ * `.runtime/datastore.sqlite`.
+ */
+import { type Logger, type ToolCliContext } from '@opensip-cli/core';
+import { type LiveViewRegistry } from './bootstrap/live-plane.js';
+import type { CommandResult } from '@opensip-cli/contracts';
+export { buildDatastoreThunk, getCurrentProjectRoot, getOrOpenDatastore, } from './bootstrap/scope-access.js';
+export { createLiveViewRegistry, type LiveViewRegistry } from './bootstrap/live-plane.js';
+export interface BuildToolCliContextOptions {
+    readonly render: (result: CommandResult) => Promise<void>;
+    readonly liveViews: LiveViewRegistry;
+    readonly maybeOpenReport: (opts: {
+        openRequested: boolean;
+        jsonOutput: boolean;
+    }) => Promise<void>;
+    readonly logger?: Logger;
+}
+export interface ToolCliContextHandle {
+    readonly ctx: ToolCliContext;
+    readonly getExitCode: () => number | undefined;
+}
+export declare function buildToolCliContext(opts: BuildToolCliContextOptions): ToolCliContextHandle;
+//# sourceMappingURL=cli-context.d.ts.map

package/dist/cli-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../src/cli-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAWnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAsB5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE1F,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE;QAC/B,aAAa,EAAE,OAAO,CAAC;QACvB,UAAU,EAAE,OAAO,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,oBAAoB,CA2F1F"}