opensip-cli 0.1.8 → 0.1.9

package/dist/bootstrap/tool-command-worker-entry.js

@@ -0,0 +1,298 @@
+/**
+ * tool-command-worker-entry — the WORKER side of the out-of-process external
+ * tool command dispatch plane (ADR-0054, increments M4-C / M4-D / M4-E).
+ *
+ * This is a HOST internal `CommandSpec` (`__tool-command-worker`), forked by the
+ * supervisor as `node <cliScript> __tool-command-worker <specPath> --cwd <cwd>`.
+ * Forking the CLI binary as a subcommand (the SAME pattern graph's
+ * `graph-run-worker` uses) means the FULL CLI bootstrap runs first: the preAction
+ * hook discovers + imports the external tool runtime IN THE WORKER, registers it,
+ * runs its `contributeScope`, composes + validates config, and builds the full
+ * per-run scope — so by the time this handler runs, `currentScope()` carries the
+ * tool's subscope (`scope.fitness`/…), the check/recipe registries, project
+ * context, and `toolConfig` exactly as an in-process run (ADR-0054 M4-C `scope`
+ * mapping: "the worker re-bootstraps its OWN scope … exactly like graph's
+ * worker"). This is the isolation move — the untrusted runtime loads HERE, in the
+ * worker, never in the host.
+ *
+ * The handler then resolves the dispatched tool from the re-bootstrapped registry
+ * and runs ITS command handler against the WORKER-side `ToolCliContext` shim
+ * (`tool-command-worker-context.ts`): FRR seams (render/json/envelope/raw/error/
+ * exit) record the value and return it once in the {@link ToolCommandResult}; the
+ * host-RPC seams (datastore / egress / SARIF / baselines / toolState / hostPlanes
+ * / report-open / exit-code re-affirm) UPCALL the host over the rpc-reply channel
+ * (the host performs the privileged effect — datastore/network/FS/exit stay
+ * host-owned). Only the live-view seams fail loud (`unsupported-seam`).
+ *
+ * A handler that calls `process.exit`, throws, crashes the native layer, or spins
+ * the event loop is contained: the supervisor turns a premature child exit /
+ * timeout / `error` message into a structured parent-side failure, and the host
+ * process survives.
+ */
+import { readFileSync } from 'node:fs';
+import { createRunTimer, currentScope, defineCommand, resolveToolHooks, } from '@opensip-cli/core';
+import { runDeepConfigPass } from './tool-command-worker-config-pass.js';
+import { buildWorkerContext, UnsupportedSeamError, } from './tool-command-worker-context.js';
+import { createWorkerRpcClient } from './tool-command-worker-rpc.js';
+/** Post one IPC message to the parent (no-op when not forked — e.g. a unit call). */
+function send(msg) {
+    process.send?.(msg);
+}
+/**
+ * Resolve the dispatched tool from the re-bootstrapped registry. The bootstrap
+ * already imported + registered it (the isolation import happened in this worker
+ * during preAction). Match by the registry's human key first, then by stable id /
+ * human name — symmetric to the host provenance/dispatch matchers.
+ *
+ * @throws {Error & {failureClass}} `runtime-load-failed` when the tool is not in
+ *   the worker's registry (the bootstrap did not admit it — e.g. a trust-policy
+ *   or discovery miss). Surfaces as a structured IPC error; the host survives.
+ */
+function resolveTool(spec) {
+    const tools = currentScope()?.tools;
+    const tool = tools?.get(spec.toolId) ??
+        tools?.list().find((t) => t.metadata.id === spec.toolId || t.metadata.name === spec.toolId);
+    if (tool === undefined) {
+        const err = new Error(`tool command worker: tool '${spec.toolId}' is not registered in the worker scope ` +
+            '(the bootstrap did not discover/admit it — check provenance/trust policy)');
+        err.failureClass = 'runtime-load-failed';
+        throw err;
+    }
+    return tool;
+}
+/** Resolve the command spec the worker should run, or throw `command-not-found`. */
+function findCommandSpec(tool, commandName) {
+    const spec = tool.commandSpecs?.find((s) => s.name === commandName);
+    if (spec === undefined) {
+        const err = new Error(`tool command worker: tool '${tool.metadata.id}' has no command '${commandName}'`);
+        err.failureClass = 'command-not-found';
+        throw err;
+    }
+    return spec;
+}
+/**
+ * ADR-0054 M4-F: run the dispatched tool's `initialize()` once, worker-side,
+ * before its handler. The host no longer runs an EXTERNAL owning tool's
+ * `initialize` (that would execute untrusted runtime in the kernel) — and the
+ * worker bootstraps the host `__tool-command-worker` subcommand (owned by NO
+ * tool), so the worker's own preflight never resolves the dispatched tool as the
+ * "owning tool". Running it here is the only place an external tool's
+ * `initialize` runs under worker dispatch. A throw propagates to
+ * {@link runToolCommandWorker}'s catch → structured `tool-handler-throw`; the
+ * host survives (fail loud, never a half-initialised silent run).
+ */
+async function runWorkerInitialize(tool) {
+    const initialize = resolveToolHooks(tool).initialize;
+    if (initialize === undefined)
+        return;
+    await initialize();
+}
+/** Build a structured `error` IPC message with a failure class (+ stack when present). */
+function errorMessage(message, failureClass, stack) {
+    return {
+        kind: 'error',
+        message,
+        failureClass,
+        ...(stack === undefined ? {} : { stack }),
+    };
+}
+/** Read + parse the worker spec file, or return a `bad-spec` error message. */
+function readSpec(specPath) {
+    try {
+        return JSON.parse(readFileSync(specPath, 'utf8'));
+    }
+    catch (error) {
+        return errorMessage(`tool command worker: unreadable spec at '${specPath}': ${error instanceof Error ? error.message : String(error)}`, 'bad-spec');
+    }
+}
+/**
+ * The output modes whose PAYLOAD is the handler's RETURN value (routed by the
+ * in-process `dispatchOutput`): `command-result` (a `CommandResult`) and
+ * `signal-envelope` (a `SignalEnvelope`). For these, the worker must carry the
+ * return back UNROUTED in `returned` so the supervisor replays it through the SAME
+ * `dispatchOutput`. `raw-stream` / `live-view` produce no routable return payload.
+ */
+function isReturnValuedOutput(output) {
+    return output === 'command-result' || output === 'signal-envelope';
+}
+/** Drain the accumulator + the handler's return into a serializable result. */
+function toResult(output, acc, session, returned) {
+    return {
+        output,
+        ...(acc.render === undefined ? {} : { render: acc.render }),
+        ...(acc.envelope === undefined ? {} : { envelope: acc.envelope }),
+        ...(acc.json === undefined ? {} : { json: acc.json }),
+        ...(acc.raw === undefined ? {} : { raw: acc.raw }),
+        ...(acc.error === undefined ? {} : { error: acc.error }),
+        ...(acc.exitCode === undefined ? {} : { exitCode: acc.exitCode }),
+        ...(session === undefined ? {} : { session }),
+        // Carry the handler's return for the return-valued modes so the supervisor
+        // routes it via the same `dispatchOutput` the in-process path uses (parity).
+        ...(returned === undefined || !isReturnValuedOutput(output) ? {} : { returned }),
+    };
+}
+/** Map a thrown error to its structured failure class for the IPC `error` message. */
+function classifyThrow(error) {
+    if (error instanceof UnsupportedSeamError)
+        return error.failureClass;
+    return error.failureClass ?? 'tool-handler-throw';
+}
+/**
+ * Resolve the dispatched tool from the re-bootstrapped scope, run the deep config
+ * pass, then run its command handler against the worker-side context shim, and
+ * build the result. Throws on a handler error (caught by
+ * {@link runToolCommandWorker}); returns an `error` message for the structured
+ * pre-handler failures (config-invalid; tool / command-not-found are thrown with
+ * a failureClass tag).
+ *
+ * `currentScope()` here is the FULL per-run scope the CLI bootstrap built for the
+ * `__tool-command-worker` subcommand (project/config/registries/contributeScope),
+ * so the handler reads `cli.scope.toolConfig`/`cli.scope.<subscope>`/checks
+ * worker-LOCAL while datastore/egress cross to the host via the RPC shim.
+ */
+async function runLoadedCommand(spec) {
+    const tool = resolveTool(spec);
+    // ADR-0054 M4-F hook mode: when the spec names a lifecycle HOOK (not a command),
+    // run that hook worker-side and return its plain-data result. This is how the
+    // host gathers an external tool's `collectReportData` / `sessionReplay` without
+    // executing the untrusted runtime in the kernel process.
+    if (spec.hook !== undefined) {
+        return await runLoadedHook(tool, spec);
+    }
+    if (spec.commandName === undefined) {
+        return errorMessage(`tool command worker: spec for tool '${spec.toolId}' names neither a command nor a hook`, 'bad-spec');
+    }
+    const commandSpec = findCommandSpec(tool, spec.commandName);
+    // ADR-0054 M4-E DEEP config pass: run the tool's REAL Zod against its config
+    // namespace IN THE WORKER (the host validated only the coarse manifest shape
+    // pre-fork). A failure crosses IPC as `config-invalid` — never a host crash —
+    // and the supervisor maps it to the SAME typed config error the host coarse
+    // pass uses. Runs BEFORE building the context: a config failure must
+    // short-circuit before any handler effect.
+    const configFailure = runDeepConfigPass(tool, spec.config);
+    if (configFailure !== undefined)
+        return errorMessage(configFailure, 'config-invalid');
+    // ADR-0054 M4-F: run the dispatched tool's `initialize()` worker-side before the
+    // handler (the host no longer runs an external owning tool's initialize). A
+    // throw becomes a structured `tool-handler-throw` via the outer catch.
+    await runWorkerInitialize(tool);
+    // The host-RPC upcall client over the live IPC channel (M4-C). `process` is the
+    // duplex: requests post via `process.send`; replies arrive on
+    // `process.on('message')`. Disposed in the finally so the listener is removed.
+    const rpcClient = createWorkerRpcClient(process);
+    // The handler runs against the bootstrapped scope (worker-local reads) but with
+    // the WORKER context shim (FRR records + RPC upcalls for privileged effects).
+    const scope = currentScope();
+    if (scope === undefined) {
+        return errorMessage('tool command worker: no scope is entered (bootstrap did not run before the worker handler)', 'runtime-load-failed');
+    }
+    try {
+        const acc = {};
+        const ctx = buildWorkerContext(scope, createRunTimer(), acc, rpcClient);
+        // Run the handler. A `process.exit` / crash / hang here is contained by the
+        // supervisor (premature-exit / timeout → structured parent failure); a throw
+        // propagates to runToolCommandWorker's catch and becomes a structured error.
+        // The handler's RETURN serves two roles: (1) for `command-result` /
+        // `signal-envelope` it IS the output payload (routed by `dispatchOutput`
+        // host-side); (2) it may carry a `session` leg (ToolRunCompletion) the host
+        // persists after the worker resolves (host-owned-run-timing). Capture it once.
+        const returned = (await commandSpec.handler({ ...spec.opts, _args: spec.positionals }, ctx));
+        return {
+            kind: 'result',
+            value: toResult(commandSpec.output, acc, returned?.session, returned),
+        };
+    }
+    finally {
+        // @fitness-ignore-next-line detached-promises -- WorkerRpcClient.dispose() returns void (removes the reply listener + clears the pending map, synchronous); the name-based heuristic misfires inside this async fn.
+        rpcClient.dispose();
+    }
+}
+/**
+ * ADR-0054 M4-F: run a dispatched tool's LIFECYCLE HOOK worker-side and return its
+ * plain-data result in `hookResult`. This is how the host gathers an EXTERNAL
+ * tool's `collectReportData` / `sessionReplay` data WITHOUT executing the
+ * untrusted runtime in the kernel process. The hook runs against the worker's own
+ * re-bootstrapped scope (`currentScope()`), exactly the contract the in-host path
+ * gives a bundled tool — just inside the isolation boundary. The host owns the
+ * merge/render/replay-emit (privileged effect). A throw propagates to
+ * {@link runToolCommandWorker}'s catch → structured failure; the host survives.
+ *
+ * The hook's runtime is resolved from the re-bootstrapped registry (the worker
+ * `initialize()` does NOT run for a hook-mode dispatch — hooks read data; an
+ * external tool that needs `initialize` for its report/replay should run it in
+ * the hook body, which is OUT of M4-F's first-party scope).
+ */
+async function runLoadedHook(tool, spec) {
+    const scope = currentScope();
+    if (scope === undefined) {
+        return errorMessage('tool command worker: no scope is entered for the hook run (bootstrap did not run)', 'runtime-load-failed');
+    }
+    const hooks = resolveToolHooks(tool);
+    // `collectReportData(scope)` takes the tool-facing ToolScope view; the worker
+    // RunScope IS a ToolScope (it extends it), so pass it directly — it returns a
+    // plain-data Record<string, unknown>. `sessionReplay` rebuilds the
+    // ToolSessionReplay from the stored row (`hookArg` is the serialized
+    // ToolSessionRecord the host read from the datastore).
+    const hookResult = spec.hook === 'collectReportData'
+        ? await hooks.collectReportData?.(scope)
+        : hooks.sessionReplay?.replaySession(spec.hookArg);
+    return {
+        kind: 'result',
+        // `output` is required on the result; the host never replays output for a
+        // hook-mode dispatch (it reads `hookResult`), so a benign default suffices.
+        value: { output: 'command-result', ...(hookResult === undefined ? {} : { hookResult }) },
+    };
+}
+/**
+ * The testable core: produce the {@link DispatchWorkerMessage} the worker would
+ * post, without touching `process.send`. Never throws — every failure becomes a
+ * structured `error` message (the supervisor rejects on it). Must run inside an
+ * entered scope (the bootstrap enters it for the real subcommand; unit tests wrap
+ * it in `runWithScope`).
+ */
+export async function runToolCommandWorker(specPath) {
+    const spec = readSpec(specPath);
+    if ('kind' in spec)
+        return spec; // bad-spec error message
+    try {
+        return await runLoadedCommand(spec);
+    }
+    catch (error) {
+        return errorMessage(error instanceof Error ? error.message : String(error), classifyThrow(error), error instanceof Error ? error.stack : undefined);
+    }
+}
+/**
+ * Run one external tool command headless in this worker and post the slim
+ * {@link ToolCommandResult} (or a structured `error`) over IPC. Never throws to
+ * the caller — every failure becomes an `error` IPC message so the supervisor
+ * rejects cleanly. This is the host CommandSpec handler's body.
+ */
+export async function executeToolCommandWorker(specPath) {
+    // @fitness-ignore-next-line detached-promises -- the promise IS awaited; `send(...)` is a synchronous void IPC post of the already-resolved value. The name-based heuristic misfires on `send(await ...)`.
+    send(await runToolCommandWorker(specPath));
+}
+/**
+ * `__tool-command-worker <specPath>` — the [internal] host subcommand the
+ * dispatch supervisor forks. Mirrors `graphRunWorkerCommandSpec`: `raw-stream`
+ * (it owns its own IPC output surface), `scope: 'project'` (the full bootstrap
+ * runs first), `visibility: 'internal'`. The supervisor passes `--cwd` so the
+ * bootstrap targets the right project. The handler ignores the host `ctx` it is
+ * given (the worker builds its OWN context shim over the bootstrapped scope) and
+ * posts the result over the IPC channel.
+ */
+export const toolCommandWorkerCommandSpec = defineCommand({
+    name: '__tool-command-worker',
+    visibility: 'internal',
+    description: '[internal] Run one external tool command headless in a forked worker and stream the result over IPC (forked by the ADR-0054 dispatch supervisor)',
+    // The supervisor passes `--cwd`; bootstrap uses it to resolve the project.
+    commonFlags: ['cwd'],
+    args: [{ name: 'specPath', description: 'Path to the JSON tool-command worker spec file' }],
+    scope: 'project',
+    output: 'raw-stream',
+    rawStreamReason: 'worker-ipc',
+    handler: async (rawOpts) => {
+        const specPath = rawOpts._args?.[0] ?? '';
+        await executeToolCommandWorker(specPath);
+    },
+});
+//# sourceMappingURL=tool-command-worker-entry.js.map

package/dist/bootstrap/tool-command-worker-entry.js.map

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

package/dist/bootstrap/tool-command-worker-rpc.d.ts

@@ -0,0 +1,53 @@
+/**
+ * tool-command-worker-rpc — the WORKER side of the ADR-0054 host-RPC upcall
+ * channel (increment M4-C).
+ *
+ * A host-RPC seam in the worker shim (`tool-command-worker-context.ts`) calls
+ * `hostRpc(request)`: it stamps a monotonic `rpcId`, posts the request to the
+ * parent over the transport's `progress` arm
+ * (`WorkerMessage<HostRpcRequest, ToolCommandResult>`), and BLOCKS on the
+ * matching {@link RpcReply} the parent posts back via `child.send`. The host
+ * performs the privileged effect through the real `ToolCliContext` and replies;
+ * a host-side fault crosses back as `{ ok: false, error }`, which this re-throws
+ * so the handler sees a normal thrown error (never a host crash, never a silent
+ * no-op).
+ *
+ * Replies are delivered on the worker's single `process.on('message')` listener,
+ * installed once and demultiplexed by `rpcId` into the pending-request map. The
+ * listener ignores anything that is not an `rpc-reply` (the channel is otherwise
+ * child → parent), so it never races the worker's own outbound posts.
+ */
+import type { HostRpcCall, HostRpcRequest } from './tool-command-dispatch-types.js';
+import type { WorkerMessage } from '@opensip-cli/core';
+/** The worker's outbound IPC type binding: requests stream on `progress`. */
+type WorkerOutbound = WorkerMessage<HostRpcRequest, unknown>;
+/**
+ * A worker RPC client: `call` issues one upcall and resolves with the host's
+ * reply value (or rejects with the host's structured error). `dispose` removes
+ * the reply listener (hygiene for the short-lived fork; the process exits on
+ * settle regardless).
+ */
+export interface WorkerRpcClient {
+    /**
+     * Issue one host-RPC upcall (sans `rpcId` — assigned here) and await the
+     * host's reply.
+     *
+     * @throws {Error} when the host reply is `{ ok: false }` (the host-side fault
+     *   re-thrown into the handler), or when the worker is not forked with an IPC
+     *   channel (no `process.send`, an integration-only misuse).
+     */
+    readonly call: (request: HostRpcCall) => Promise<unknown>;
+    readonly dispose: () => void;
+}
+/**
+ * Create the worker's RPC client over the live IPC channel. Installs the single
+ * reply listener; `send` posts requests on the `progress` arm. The caller passes
+ * `process` so unit tests can supply a fake duplex.
+ */
+export declare function createWorkerRpcClient(channel: {
+    send?: (msg: WorkerOutbound) => unknown;
+    on: (event: 'message', listener: (msg: unknown) => void) => unknown;
+    off?: (event: 'message', listener: (msg: unknown) => void) => unknown;
+}): WorkerRpcClient;
+export {};
+//# sourceMappingURL=tool-command-worker-rpc.d.ts.map

package/dist/bootstrap/tool-command-worker-rpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-command-worker-rpc.d.ts","sourceRoot":"","sources":["../../src/bootstrap/tool-command-worker-rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAY,MAAM,kCAAkC,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,6EAA6E;AAC7E,KAAK,cAAc,GAAG,aAAa,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;AAE7D;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAyBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC;IACxC,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAAK,OAAO,CAAC;IACpE,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,KAAK,OAAO,CAAC;CACvE,GAAG,eAAe,CAuClB"}

package/dist/bootstrap/tool-command-worker-rpc.js

@@ -0,0 +1,78 @@
+/**
+ * tool-command-worker-rpc — the WORKER side of the ADR-0054 host-RPC upcall
+ * channel (increment M4-C).
+ *
+ * A host-RPC seam in the worker shim (`tool-command-worker-context.ts`) calls
+ * `hostRpc(request)`: it stamps a monotonic `rpcId`, posts the request to the
+ * parent over the transport's `progress` arm
+ * (`WorkerMessage<HostRpcRequest, ToolCommandResult>`), and BLOCKS on the
+ * matching {@link RpcReply} the parent posts back via `child.send`. The host
+ * performs the privileged effect through the real `ToolCliContext` and replies;
+ * a host-side fault crosses back as `{ ok: false, error }`, which this re-throws
+ * so the handler sees a normal thrown error (never a host crash, never a silent
+ * no-op).
+ *
+ * Replies are delivered on the worker's single `process.on('message')` listener,
+ * installed once and demultiplexed by `rpcId` into the pending-request map. The
+ * listener ignores anything that is not an `rpc-reply` (the channel is otherwise
+ * child → parent), so it never races the worker's own outbound posts.
+ */
+/** Reconstruct an Error from a host reply's structured error (preserving stack). */
+function rpcError(detail) {
+    const err = new Error(detail.message);
+    if (detail.code !== undefined)
+        err.code = detail.code;
+    if (detail.stack !== undefined)
+        err.stack = detail.stack;
+    return err;
+}
+/** Narrow an arbitrary IPC message to a {@link RpcReply}. */
+function isRpcReply(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        msg.kind === 'rpc-reply' &&
+        typeof msg.rpcId === 'number');
+}
+/**
+ * Create the worker's RPC client over the live IPC channel. Installs the single
+ * reply listener; `send` posts requests on the `progress` arm. The caller passes
+ * `process` so unit tests can supply a fake duplex.
+ */
+export function createWorkerRpcClient(channel) {
+    const pending = new Map();
+    let nextId = 1;
+    const onMessage = (msg) => {
+        if (!isRpcReply(msg))
+            return; // not a reply — the channel is otherwise outbound
+        const waiter = pending.get(msg.rpcId);
+        if (waiter === undefined)
+            return; // unknown/duplicate rpcId — defensively ignore
+        pending.delete(msg.rpcId);
+        if (msg.ok)
+            waiter.resolve(msg.value);
+        else
+            waiter.reject(rpcError(msg.error));
+    };
+    channel.on('message', onMessage);
+    return {
+        call: (request) => new Promise((resolve, reject) => {
+            if (channel.send === undefined) {
+                reject(new Error('tool command worker: no IPC channel to issue a host-RPC upcall ' +
+                    `('${request.seam}') — the worker must be forked with an 'ipc' stdio channel.`));
+                return;
+            }
+            const rpcId = nextId++;
+            pending.set(rpcId, { resolve, reject });
+            const event = { ...request, rpcId };
+            // Call through `channel.send(...)` (not an extracted reference) so the
+            // method keeps its `this` binding — `process.send` reads `this.connected`
+            // internally and throws if invoked unbound.
+            channel.send({ kind: 'progress', event });
+        }),
+        dispose: () => {
+            channel.off?.('message', onMessage);
+            pending.clear();
+        },
+    };
+}
+//# sourceMappingURL=tool-command-worker-rpc.js.map

package/dist/bootstrap/tool-command-worker-rpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-command-worker-rpc.js","sourceRoot":"","sources":["../../src/bootstrap/tool-command-worker-rpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAgCH,oFAAoF;AACpF,SAAS,QAAQ,CAAC,MAA0D;IAC1E,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAA8B,CAAC;IACnE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,GAAG,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACtD,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS;QAAE,GAAG,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IACzD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,6DAA6D;AAC7D,SAAS,UAAU,CAAC,GAAY;IAC9B,OAAO,CACL,OAAO,GAAG,KAAK,QAAQ;QACvB,GAAG,KAAK,IAAI;QACX,GAA0B,CAAC,IAAI,KAAK,WAAW;QAChD,OAAQ,GAA2B,CAAC,KAAK,KAAK,QAAQ,CACvD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAIrC;IACC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAuB,CAAC;IAC/C,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,MAAM,SAAS,GAAG,CAAC,GAAY,EAAQ,EAAE;QACvC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,CAAC,kDAAkD;QAChF,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO,CAAC,+CAA+C;QACjF,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,GAAG,CAAC,EAAE;YAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;;YACjC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAEjC,OAAO;QACL,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAChB,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACvC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC/B,MAAM,CACJ,IAAI,KAAK,CACP,iEAAiE;oBAC/D,KAAK,OAAO,CAAC,IAAI,6DAA6D,CACjF,CACF,CAAC;gBACF,OAAO;YACT,CAAC;YACD,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC;YACvB,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YACxC,MAAM,KAAK,GAAmB,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC;YACpD,uEAAuE;YACvE,0EAA0E;YAC1E,4CAA4C;YAC5C,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,CAAC,CAAC;QACJ,OAAO,EAAE,GAAG,EAAE;YACZ,OAAO,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACpC,OAAO,CAAC,KAAK,EAAE,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,85 @@
+/**
+ * tool-provenance — the shared per-run provenance classifier + the host/worker
+ * hook-execution gate (ADR-0054 M4-F).
+ *
+ * Three sites resolve a tool's `ToolProvenance.source` from the per-run
+ * provenance array (recorded by the bootstrap, matched by stable id then human
+ * name): `bind-external-dispatch.ts` (dispatch gate), `config-and-capabilities.ts`
+ * (config two-pass fold + capability wiring), and now the lifecycle host loops
+ * (contributeScope / initialize / report / replay). This module is the ONE matcher
+ * so they never drift.
+ *
+ * It also owns the **host-vs-worker** gate that makes the M4-F lifecycle skip
+ * correct. M4-F stops the HOST from executing external-provenance lifecycle +
+ * capability hooks — but the dispatch WORKER re-runs the SAME bootstrap code
+ * (`build-per-run-scope` / `config-and-capabilities`) and MUST run the dispatched
+ * external tool's hooks there (the worker is the legitimate isolation boundary —
+ * that is the whole point: external runtime executes in the worker, not the host).
+ *
+ * So the skip is gated on "this process is the HOST, not a dispatch worker." The
+ * supervisor sets {@link IN_TOOL_WORKER_ENV} on the forked child's env; inside the
+ * worker {@link isExternalHookHostSkipActive} returns `false`, so the worker runs
+ * ALL its registered tools' hooks worker-local exactly as a normal in-process
+ * bootstrap would. In the host it returns `true`, so external hooks are skipped.
+ */
+import { type Tool, type ToolProvenance, type ToolSource } from '@opensip-cli/core';
+/**
+ * Env flag the dispatch supervisor sets on the forked `__tool-command-worker`
+ * child so the worker can tell it is the isolation boundary (NOT the host). The
+ * worker bootstrap runs the SAME lifecycle loops as the host; this flag disables
+ * the M4-F external-hook host-skip inside the worker so the dispatched tool's
+ * hooks run there. A separate process + env channel (symmetric to OPENSIP_RUN_ID
+ * injection) keeps it deterministic and unit-testable.
+ */
+export declare const IN_TOOL_WORKER_ENV = "OPENSIP_CLI_IN_TOOL_WORKER";
+/**
+ * Is the M4-F external-hook host-skip ACTIVE in this process? `true` in the host
+ * (skip external hooks), `false` inside a dispatch worker (run them — the worker
+ * is the isolation boundary). Reads the injected env (defaults to `process.env`)
+ * so tests can flip it deterministically without a fork.
+ */
+export declare function isExternalHookHostSkipActive(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Must this process REFUSE to import external tool runtimes (ADR-0054 M4-G
+ * capstone)? `true` in the HOST — the host registers a manifest-derived synthetic
+ * Tool for external provenance and NEVER loads its runtime; `false` inside a
+ * dispatch worker (`OPENSIP_CLI_IN_TOOL_WORKER=1`) — the worker IS the isolation
+ * boundary, where the untrusted external runtime legitimately loads + runs.
+ *
+ * This is the same host-vs-worker hinge as the M4-F lifecycle gate (the worker
+ * re-runs the SAME bootstrap, so discovery must branch on which process it is),
+ * named for the capstone's discovery decision. Reads the injected env (defaults
+ * to `process.env`) so tests flip it deterministically without a fork.
+ */
+export declare function isHostRuntimeImportForbidden(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Resolve a tool's provenance source from the per-run provenance array. Mirrors
+ * the dispatch/config matchers: prefer the stable-id match (UUID → `metadata.id`),
+ * fall back to the human key (`ToolProvenance.id` → `metadata.name`). A tool with
+ * NO recorded provenance is the trusted/unknown path → `'bundled'` semantics (its
+ * hooks run in-host, exactly as before M4-F).
+ */
+export declare function provenanceSourceFor(tool: Tool, provenance: readonly ToolProvenance[]): ToolSource;
+/** Find the full provenance record for a tool (stable-id then human-name match). */
+export declare function provenanceRecordFor(tool: Tool, provenance: readonly ToolProvenance[]): ToolProvenance | undefined;
+/**
+ * Is this tool external-provenance (installed / project-local / user-global)? A
+ * tool with no recorded provenance is treated as bundled (trusted/unknown path).
+ */
+export declare function isExternalToolProvenance(tool: Tool, provenance: readonly ToolProvenance[]): boolean;
+/**
+ * The M4-F gate: should this tool's lifecycle/capability hook run IN THE HOST
+ * process this invocation?
+ *
+ *   - Bundled (or no provenance recorded) → `true` (trusted computing base; runs
+ *     in-host exactly as before M4-F).
+ *   - External, host-skip ACTIVE (we are the host) → `false` (the host never
+ *     executes external runtime hooks; they run worker-side).
+ *   - External, host-skip INACTIVE (we are inside a dispatch worker) → `true`
+ *     (the worker IS the isolation boundary — run the dispatched tool's hooks
+ *     worker-local).
+ *
+ * @param env Injected env (defaults to `process.env`) for the worker-flag read.
+ */
+export declare function shouldRunHookInHost(tool: Tool, provenance: readonly ToolProvenance[], env?: NodeJS.ProcessEnv): boolean;
+//# sourceMappingURL=tool-provenance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-provenance.d.ts","sourceRoot":"","sources":["../../src/bootstrap/tool-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE1F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE1F;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,CAKjG;AAED,oFAAoF;AACpF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,cAAc,EAAE,GACpC,cAAc,GAAG,SAAS,CAK5B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,cAAc,EAAE,GACpC,OAAO,CAET;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,cAAc,EAAE,EACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAGT"}

package/dist/bootstrap/tool-provenance.js

@@ -0,0 +1,101 @@
+/**
+ * tool-provenance — the shared per-run provenance classifier + the host/worker
+ * hook-execution gate (ADR-0054 M4-F).
+ *
+ * Three sites resolve a tool's `ToolProvenance.source` from the per-run
+ * provenance array (recorded by the bootstrap, matched by stable id then human
+ * name): `bind-external-dispatch.ts` (dispatch gate), `config-and-capabilities.ts`
+ * (config two-pass fold + capability wiring), and now the lifecycle host loops
+ * (contributeScope / initialize / report / replay). This module is the ONE matcher
+ * so they never drift.
+ *
+ * It also owns the **host-vs-worker** gate that makes the M4-F lifecycle skip
+ * correct. M4-F stops the HOST from executing external-provenance lifecycle +
+ * capability hooks — but the dispatch WORKER re-runs the SAME bootstrap code
+ * (`build-per-run-scope` / `config-and-capabilities`) and MUST run the dispatched
+ * external tool's hooks there (the worker is the legitimate isolation boundary —
+ * that is the whole point: external runtime executes in the worker, not the host).
+ *
+ * So the skip is gated on "this process is the HOST, not a dispatch worker." The
+ * supervisor sets {@link IN_TOOL_WORKER_ENV} on the forked child's env; inside the
+ * worker {@link isExternalHookHostSkipActive} returns `false`, so the worker runs
+ * ALL its registered tools' hooks worker-local exactly as a normal in-process
+ * bootstrap would. In the host it returns `true`, so external hooks are skipped.
+ */
+/**
+ * Env flag the dispatch supervisor sets on the forked `__tool-command-worker`
+ * child so the worker can tell it is the isolation boundary (NOT the host). The
+ * worker bootstrap runs the SAME lifecycle loops as the host; this flag disables
+ * the M4-F external-hook host-skip inside the worker so the dispatched tool's
+ * hooks run there. A separate process + env channel (symmetric to OPENSIP_RUN_ID
+ * injection) keeps it deterministic and unit-testable.
+ */
+export const IN_TOOL_WORKER_ENV = 'OPENSIP_CLI_IN_TOOL_WORKER';
+/**
+ * Is the M4-F external-hook host-skip ACTIVE in this process? `true` in the host
+ * (skip external hooks), `false` inside a dispatch worker (run them — the worker
+ * is the isolation boundary). Reads the injected env (defaults to `process.env`)
+ * so tests can flip it deterministically without a fork.
+ */
+export function isExternalHookHostSkipActive(env = process.env) {
+    return env[IN_TOOL_WORKER_ENV] !== '1';
+}
+/**
+ * Must this process REFUSE to import external tool runtimes (ADR-0054 M4-G
+ * capstone)? `true` in the HOST — the host registers a manifest-derived synthetic
+ * Tool for external provenance and NEVER loads its runtime; `false` inside a
+ * dispatch worker (`OPENSIP_CLI_IN_TOOL_WORKER=1`) — the worker IS the isolation
+ * boundary, where the untrusted external runtime legitimately loads + runs.
+ *
+ * This is the same host-vs-worker hinge as the M4-F lifecycle gate (the worker
+ * re-runs the SAME bootstrap, so discovery must branch on which process it is),
+ * named for the capstone's discovery decision. Reads the injected env (defaults
+ * to `process.env`) so tests flip it deterministically without a fork.
+ */
+export function isHostRuntimeImportForbidden(env = process.env) {
+    return isExternalHookHostSkipActive(env);
+}
+/**
+ * Resolve a tool's provenance source from the per-run provenance array. Mirrors
+ * the dispatch/config matchers: prefer the stable-id match (UUID → `metadata.id`),
+ * fall back to the human key (`ToolProvenance.id` → `metadata.name`). A tool with
+ * NO recorded provenance is the trusted/unknown path → `'bundled'` semantics (its
+ * hooks run in-host, exactly as before M4-F).
+ */
+export function provenanceSourceFor(tool, provenance) {
+    const recorded = provenance.find((p) => p.stableId !== undefined && p.stableId === tool.metadata.id) ??
+        provenance.find((p) => p.id === tool.metadata.name);
+    return recorded?.source ?? 'bundled';
+}
+/** Find the full provenance record for a tool (stable-id then human-name match). */
+export function provenanceRecordFor(tool, provenance) {
+    return (provenance.find((p) => p.stableId !== undefined && p.stableId === tool.metadata.id) ??
+        provenance.find((p) => p.id === tool.metadata.name));
+}
+/**
+ * Is this tool external-provenance (installed / project-local / user-global)? A
+ * tool with no recorded provenance is treated as bundled (trusted/unknown path).
+ */
+export function isExternalToolProvenance(tool, provenance) {
+    return provenanceSourceFor(tool, provenance) !== 'bundled';
+}
+/**
+ * The M4-F gate: should this tool's lifecycle/capability hook run IN THE HOST
+ * process this invocation?
+ *
+ *   - Bundled (or no provenance recorded) → `true` (trusted computing base; runs
+ *     in-host exactly as before M4-F).
+ *   - External, host-skip ACTIVE (we are the host) → `false` (the host never
+ *     executes external runtime hooks; they run worker-side).
+ *   - External, host-skip INACTIVE (we are inside a dispatch worker) → `true`
+ *     (the worker IS the isolation boundary — run the dispatched tool's hooks
+ *     worker-local).
+ *
+ * @param env Injected env (defaults to `process.env`) for the worker-flag read.
+ */
+export function shouldRunHookInHost(tool, provenance, env = process.env) {
+    if (!isExternalToolProvenance(tool, provenance))
+        return true;
+    return !isExternalHookHostSkipActive(env);
+}
+//# sourceMappingURL=tool-provenance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-provenance.js","sourceRoot":"","sources":["../../src/bootstrap/tool-provenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,4BAA4B,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC/E,OAAO,GAAG,CAAC,kBAAkB,CAAC,KAAK,GAAG,CAAC;AACzC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC/E,OAAO,4BAA4B,CAAC,GAAG,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAU,EAAE,UAAqC;IACnF,MAAM,QAAQ,GACZ,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnF,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,QAAQ,EAAE,MAAM,IAAI,SAAS,CAAC;AACvC,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,mBAAmB,CACjC,IAAU,EACV,UAAqC;IAErC,OAAO,CACL,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnF,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CACpD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAU,EACV,UAAqC;IAErC,OAAO,mBAAmB,CAAC,IAAI,EAAE,UAAU,CAAC,KAAK,SAAS,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAU,EACV,UAAqC,EACrC,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,CAAC,wBAAwB,CAAC,IAAI,EAAE,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,OAAO,CAAC,4BAA4B,CAAC,GAAG,CAAC,CAAC;AAC5C,CAAC"}