opensip-cli 0.1.2 → 0.1.3

package/dist/bootstrap/register-tools-discovery.d.ts

@@ -0,0 +1,154 @@
+import { type ToolPluginManifest, type ToolProvenance, type ToolRegistry, type ToolDiscoverySource } from '@opensip-cli/core';
+export interface DiscoveryOptions {
+    /**
+     * Ordered tool-discovery sources (precedence: first wins on duplicate
+     * name). Built by {@link buildToolDiscoverySources} at the composition
+     * root; passed in here so this function reads no ambient HOME/cwd state
+     * and stays unit-testable with explicit anchors.
+     */
+    readonly sources: readonly ToolDiscoverySource[];
+}
+/**
+ * Build the ordered tool-discovery sources. Order is precedence
+ * (first-occurrence-wins on duplicate name):
+ *
+ *   1. project-local `.runtime/plugins/tool`  — `plugin add --project`
+ *   2. project tree (walk up from cwd)          — plain `npm install @tool`
+ *   3. user-global `~/.opensip-cli/plugins/tool` — `plugin add` (default)
+ *   4. CLI install dir (walk up)                 — `npm i -g @tool`
+ *
+ * A project-local pin therefore shadows a user-global install of the same
+ * tool. Project-root resolution is best-effort: an unresolvable context
+ * (e.g. running outside any project) simply contributes no `.runtime`
+ * source.
+ */
+export declare function buildToolDiscoverySources(cwd: string, cliInstallDir: string): ToolDiscoverySource[];
+/**
+ * Discover and register third-party tool packages from npm — any
+ * `package.json` declaring `opensipTools.kind === 'tool'`. Built-in
+ * ids are skipped to avoid double-registration warnings. Discovery spans
+ * the supplied sources (the user-global tool host dir, the project tree +
+ * its `.runtime` tool host dir, and the CLI install dir — see
+ * {@link buildToolDiscoverySources}).
+ *
+ * Each discovered package runs through the SAME `admitTool` gate the
+ * bundled path uses (launch, Phase 3) BEFORE its module is imported:
+ * the static `package.json#opensipTools` manifest is read with source
+ * `'installed'`, the compatibility gate runs, and only an `admit` verdict
+ * proceeds to import + register. An installed tool is best-effort
+ * `explicitlyRequested: false`, so an incompatible one `skip`s (logged)
+ * rather than failing the whole CLI — a stray incompatible plugin must not
+ * take fit/graph/sim down. Admitted tools' `ToolProvenance` is pushed onto
+ * the optional `provenance` collector for Phase 4's `plugin list`.
+ *
+ * @param provenance Optional sink for admitted tools' provenance records.
+ */
+export declare function discoverAndRegisterToolPackages(registry: ToolRegistry, opts: DiscoveryOptions, builtInIds: ReadonlySet<string>, provenance?: ToolProvenance[], manifests?: ToolPluginManifest[]): Promise<void>;
+/**
+ * The outcome of admitting a tool — the recorded `ToolProvenance` plus the
+ * loaded `ToolPluginManifest`. Returned by the authored legs
+ * ({@link admitUserGlobalTool} / {@link admitProjectLocalTool}) and the
+ * installed leg ({@link admitInstalledTool}) alike. The manifest is returned
+ * (not re-read) so the register step can run the drift guard
+ * (`assertManifestMatchesTool`) against the imported runtime and seed the
+ * per-run capability registry, without a second filesystem read.
+ */
+export interface AuthoredAdmission {
+    readonly provenance: ToolProvenance;
+    readonly manifest: ToolPluginManifest;
+}
+/**
+ * Admit (or reject) a single PROJECT-LOCAL authored tool under the
+ * deny-by-default trust policy (launch, Phase 3 Task 3.2; wired into
+ * production discovery in the launch contract).
+ *
+ * A project-local tool is authored code under
+ * `<project>/opensip-cli/tools/<name>/` declaring its identity via a JSON
+ * sidecar (`opensip-tool.manifest.json`). It is read + gated WITHOUT importing
+ * its module:
+ *
+ *   1. `loadToolManifest('project-local', dir)` — identity only, no code run.
+ *   2. Trust check — {@link isProjectLocalToolTrusted}. Not allowlisted ⇒
+ *      throw {@link PluginIncompatibleError} (fail-closed, exit 5) before any
+ *      import. Allowlisted ⇒ run the shared compatibility tail; an incompatible
+ *      explicitly-trusted tool is likewise fail-closed.
+ *
+ * Returns the admitted tool's `{ provenance, manifest }` on success. The trust
+ * decision always precedes import (it is the FIRST statement here, ahead of the
+ * shared {@link admitAuthoredTool} tail).
+ *
+ * @throws {PluginIncompatibleError} when the tool has no conformant sidecar
+ *   manifest, is not allowlisted, or is compatibility-incompatible.
+ */
+export declare function admitProjectLocalTool(args: {
+    readonly dir: string;
+    readonly env?: NodeJS.ProcessEnv;
+}): AuthoredAdmission;
+/**
+ * Admit a single USER-GLOBAL authored tool — the trusted-by-default sibling of
+ * {@link admitProjectLocalTool}.
+ *
+ * A user-global tool is an authored sidecar under
+ * `~/.opensip-cli/tools/<name>/`. The user deliberately placed it in their
+ * own home dir (the `npm i -g` analogue for authored code), so there is **no
+ * allowlist gate** — it is trusted-by-default. It still reads the static
+ * sidecar and runs `admitTool` BEFORE the module could be imported (the shared
+ * {@link admitAuthoredTool} tail), so trust-before-import holds for this leg
+ * too: a global tool the user explicitly authored is fail-closed on a
+ * missing/incompatible manifest, never a silent skip.
+ *
+ * @throws {PluginIncompatibleError} when the tool has no conformant sidecar
+ *   manifest or is compatibility-incompatible.
+ */
+export declare function admitUserGlobalTool(args: {
+    readonly dir: string;
+}): AuthoredAdmission;
+/**
+ * Discover + admit + register AUTHORED Tool sidecars from the two authored
+ * roots, then dynamic-import each admitted runtime through the shared
+ * `importToolRuntime` seam — the same admit → import → register path the
+ * bundled and installed legs travel (ADR-0027; this is the leg that makes the
+ * dormant {@link admitProjectLocalTool} live).
+ *
+ * Two roots, two trust postures:
+ *   - **global** (`~/.opensip-cli/tools/`) → {@link admitUserGlobalTool},
+ *     trusted-by-default.
+ *   - **project** (`<project>/opensip-cli/tools/`) → {@link admitProjectLocalTool},
+ *     deny-by-default (allowlist via `OPENSIP_CLI_ALLOW_PROJECT_TOOLS`).
+ *
+ * Global is processed FIRST so a project-authored tool cannot shadow a same-id
+ * global one — matching the `~/.opensip-cli/plugins` precedence note in
+ * {@link buildToolDiscoverySources} (first-writer-wins via the registry).
+ * `builtInIds` are skipped so an authored tool never shadows a bundled one.
+ *
+ * **Trust-before-import.** For each candidate, the admit step (which EMBEDS the
+ * trust decision — deny-by-default inside `admitProjectLocalTool`) runs to
+ * completion BEFORE `importToolRuntime`. A non-allowlisted project tool THROWS
+ * `PluginIncompatibleError` (exit 5) here, propagated out of the walk: it must
+ * fail the run loudly — that is the clone-protection contract.
+ *
+ * **Error-posture asymmetry (deliberate).** An un-allowlisted *project* tool is
+ * fail-closed by policy (clone-risk; the user must opt in). A *global* tool that
+ * fails to load is also fail-closed (the user explicitly authored it into
+ * `$HOME`). This differs from the *installed* npm leg, where a stray bad plugin
+ * skips-with-diagnostic so it can't take fit/graph/sim down — authored tools are
+ * first-party-intent, installed tools are ambient.
+ *
+ * @param registry The per-invocation tool registry to populate.
+ * @param opts.projectAuthoredDir `resolveProjectPaths(root).authoredToolsDir`,
+ *   or `undefined` when there is no resolvable project context.
+ * @param opts.globalAuthoredDir `resolveUserPaths().authoredToolsDir`.
+ * @param opts.env Environment carrying the project allowlist (default
+ *   `process.env`); injectable for tests.
+ * @param builtInIds Bundled-tool ids to skip on a name collision.
+ * @param provenance Sink for admitted authored tools' provenance records.
+ * @param manifests Sink for admitted authored tools' manifests (§5.3).
+ * @throws {PluginIncompatibleError} for an un-allowlisted project tool, or any
+ *   authored tool whose sidecar/runtime is missing/incompatible (fail-closed).
+ */
+export declare function discoverAndRegisterAuthoredTools(registry: ToolRegistry, opts: {
+    readonly projectAuthoredDir?: string;
+    readonly globalAuthoredDir: string;
+    readonly env?: NodeJS.ProcessEnv;
+}, builtInIds: ReadonlySet<string>, provenance?: ToolProvenance[], manifests?: ToolPluginManifest[]): Promise<void>;
+//# sourceMappingURL=register-tools-discovery.d.ts.map

package/dist/bootstrap/register-tools-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-tools-discovery.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-discovery.ts"],"names":[],"mappings":"AAEA,OAAO,EAYL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAEzB,MAAM,mBAAmB,CAAC;AAM3B,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GACpB,mBAAmB,EAAE,CAqBvB;AA6FD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,GACnC,OAAO,CAAC,IAAI,CAAC,CAoDf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;CACvC;AAgDD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,GAAG,iBAAiB,CAuBpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CAGrF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,YAAY,EACtB,IAAI,EAAE;IACJ,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC,EACD,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,EAC/B,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,GACnC,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/bootstrap/register-tools-discovery.js

@@ -0,0 +1,385 @@
+// @fitness-ignore-file performance-anti-patterns -- sequential await across discovered tool packages preserves load order for plugin-conflict detection; bounded by installed plugin count
+// @fitness-ignore-file file-length-limit -- discovery admission remains one policy unit after the register-tools split; below the hard limit and slated for a later source-boundary split.
+import { admitTool, assertManifestMatchesTool, discoverAuthoredToolSidecars, discoverToolPackagesFromAnchors, loadToolManifest, logger, PluginIncompatibleError, PROJECT_LOCAL_MANIFEST_FILE, resolveProjectContext, resolveProjectPaths, resolveUserPaths, } from '@opensip-cli/core';
+import { importToolRuntime } from './admit-tool-package.js';
+import { BOOTSTRAP_MODULE } from './register-tools-shared.js';
+import { isProjectLocalToolTrusted } from './tool-trust.js';
+/**
+ * Build the ordered tool-discovery sources. Order is precedence
+ * (first-occurrence-wins on duplicate name):
+ *
+ *   1. project-local `.runtime/plugins/tool`  — `plugin add --project`
+ *   2. project tree (walk up from cwd)          — plain `npm install @tool`
+ *   3. user-global `~/.opensip-cli/plugins/tool` — `plugin add` (default)
+ *   4. CLI install dir (walk up)                 — `npm i -g @tool`
+ *
+ * A project-local pin therefore shadows a user-global install of the same
+ * tool. Project-root resolution is best-effort: an unresolvable context
+ * (e.g. running outside any project) simply contributes no `.runtime`
+ * source.
+ */
+export function buildToolDiscoverySources(cwd, cliInstallDir) {
+    const sources = [];
+    try {
+        const project = resolveProjectContext({ cwd, cwdExplicit: false });
+        if (project.scope === 'project') {
+            sources.push({
+                dir: resolveProjectPaths(project.projectRoot).pluginsDir('tool'),
+                mode: 'scanDir',
+            });
+        }
+    }
+    catch {
+        // @swallow-ok no resolvable project context (e.g. running outside any
+        // project) → contribute no project-local tool source. Best-effort by
+        // documented contract; see the JSDoc on buildToolDiscoverySources.
+    }
+    sources.push({ dir: cwd, mode: 'walkUp' }, { dir: resolveUserPaths().pluginsDir('tool'), mode: 'scanDir' }, { dir: cliInstallDir, mode: 'walkUp' });
+    return sources;
+}
+/**
+ * Run the admission gate over a discovered INSTALLED tool package
+ * before its module is imported. Reads the static
+ * `package.json#opensipTools` manifest and runs the shared `admitTool` gate
+ * (source `'installed'`, best-effort `explicitlyRequested: false` so an
+ * incompatible installed tool skips rather than failing the whole CLI).
+ *
+ * Returns:
+ *   - `undefined` — skip this package (no conformant manifest, gate skipped
+ *     it, or its id collides with a built-in). The reason is logged.
+ *   - the admission `{ provenance, manifest }` — the manifest is conformant +
+ *     compatible; the caller continues to import + register, and records the
+ *     provenance/manifest only AFTER the runtime actually registered (so
+ *     `plugin list` and the capability registry never see a tool whose import
+ *     subsequently failed — matching the bundled/authored legs).
+ *
+ * Public launch: the grace window ended. A discovered `kind:'tool'` package whose
+ * manifest is missing/malformed (`loadToolManifest` → undefined) or declares no
+ * `apiVersion` (`admitTool` → skip via {@link checkCompatibility}) is no longer
+ * admitted off the marker alone — it is rejected with a diagnostic.
+ */
+function admitInstalledTool(pkg, builtInIds) {
+    const manifest = loadToolManifest('installed', pkg.packageDir);
+    if (manifest === undefined) {
+        // Launch: a discovered tool with no conformant manifest is no longer admitted
+        // off the `kind:'tool'` marker alone (the grace window ended) — skip it.
+        process.stderr.write(`opensip: tool package ${pkg.name} has no conformant package.json#opensipTools manifest — skipping\n`);
+        logger.warn({
+            evt: 'cli.tool.manifest_invalid',
+            module: BOOTSTRAP_MODULE,
+            name: pkg.name,
+        });
+        return undefined;
+    }
+    if (builtInIds.has(manifest.id))
+        return undefined; // builtInIds are human ids from manifests (compat)
+    const result = admitTool({
+        manifest,
+        source: 'installed',
+        dir: pkg.packageDir,
+        packageName: pkg.name,
+        // Best-effort: discovery alone can't tell whether THIS run targets this
+        // tool's command, so default false → incompatible installed tools skip.
+        explicitlyRequested: false,
+    });
+    if (result.decision !== 'admit')
+        return undefined;
+    return { provenance: result.provenance, manifest: result.manifest };
+}
+/**
+ * Emit the best-effort stderr line + structured warning for a discovered
+ * INSTALLED tool whose runtime failed to load. Each `ToolRuntimeLoad` failure
+ * reason maps to its own message + event (preserving the admission diagnostics) —
+ * an installed tool's load failure skips it, never crashing the CLI.
+ */
+function emitInstalledLoadFailure(name, load) {
+    if (load.reason === 'no-entry') {
+        process.stderr.write(`opensip: tool package ${name} has no resolvable entry point — skipping\n`);
+        logger.warn({ evt: 'cli.tool.no_entry', module: BOOTSTRAP_MODULE, name });
+        return;
+    }
+    if (load.reason === 'invalid-shape') {
+        process.stderr.write(`opensip: tool package ${name} does not export a valid \`tool\` — skipping\n`);
+        logger.warn({
+            evt: 'cli.tool.invalid_shape',
+            module: BOOTSTRAP_MODULE,
+            name,
+        });
+        return;
+    }
+    process.stderr.write(`opensip: failed to load tool ${name}: ${load.detail ?? 'import failed'}\n`);
+    logger.warn({
+        evt: 'cli.tool.load_failed',
+        module: BOOTSTRAP_MODULE,
+        name,
+        error: load.detail,
+    });
+}
+/**
+ * Discover and register third-party tool packages from npm — any
+ * `package.json` declaring `opensipTools.kind === 'tool'`. Built-in
+ * ids are skipped to avoid double-registration warnings. Discovery spans
+ * the supplied sources (the user-global tool host dir, the project tree +
+ * its `.runtime` tool host dir, and the CLI install dir — see
+ * {@link buildToolDiscoverySources}).
+ *
+ * Each discovered package runs through the SAME `admitTool` gate the
+ * bundled path uses (launch, Phase 3) BEFORE its module is imported:
+ * the static `package.json#opensipTools` manifest is read with source
+ * `'installed'`, the compatibility gate runs, and only an `admit` verdict
+ * proceeds to import + register. An installed tool is best-effort
+ * `explicitlyRequested: false`, so an incompatible one `skip`s (logged)
+ * rather than failing the whole CLI — a stray incompatible plugin must not
+ * take fit/graph/sim down. Admitted tools' `ToolProvenance` is pushed onto
+ * the optional `provenance` collector for Phase 4's `plugin list`.
+ *
+ * @param provenance Optional sink for admitted tools' provenance records.
+ */
+export async function discoverAndRegisterToolPackages(registry, opts, builtInIds, provenance = [], manifests = []) {
+    // `builtInIds` is the set of already-registered bundled-tool *human ids* (manifest.id)
+    // to skip on a name collision (launch — passed explicitly by the composition root, which
+    // derives it from the bundled MANIFESTS it just loaded; compare against runtime
+    // metadata.name for the human key).
+    const discovered = discoverToolPackagesFromAnchors(opts.sources);
+    for (const pkg of discovered) {
+        try {
+            // Compatibility gate BEFORE import (launch). `undefined` means the
+            // gate skipped it (or it's a built-in id); an admission means import +
+            // register as before.
+            const admission = admitInstalledTool(pkg, builtInIds);
+            if (admission === undefined)
+                continue;
+            // Load the runtime through the SHARED dynamic-import path (launch) — the
+            // same `importToolRuntime` the bundled path uses. Resolves the entry
+            // from `packageDir` so a tool living in a host dir off the CLI's own
+            // module-resolution path still loads. An installed tool is best-effort:
+            // any load failure skips-with-diagnostic (it must not take fit/graph/sim
+            // down), in contrast to the bundled path's fail-closed.
+            const load = await importToolRuntime(pkg.packageDir);
+            if (!load.ok) {
+                emitInstalledLoadFailure(pkg.name, load);
+                continue;
+            }
+            // builtInIds holds human ids (from bundled manifests); compare against runtime human name
+            if (builtInIds.has(load.tool.metadata.name ?? load.tool.metadata.id))
+                continue;
+            // Drift guard — the SAME manifest⇔runtime identity check the bundled and
+            // authored legs run. For an installed tool a mismatch throws into the
+            // surrounding catch (skip-with-diagnostic posture), never crashing the CLI.
+            assertManifestMatchesTool(admission.manifest, load.tool);
+            registry.register(load.tool, { sourcePackage: pkg.name });
+            // Record provenance + manifest only now that the tool actually
+            // registered — `plugin list` and the per-run capability registry must
+            // never include a tool whose runtime failed to load (parity with the
+            // bundled/authored legs, which also record after registration).
+            provenance.push(admission.provenance);
+            manifests.push(admission.manifest);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`opensip: failed to load tool ${pkg.name}: ${msg}\n`);
+            logger.warn({
+                evt: 'cli.tool.load_failed',
+                module: BOOTSTRAP_MODULE,
+                name: pkg.name,
+                error: msg,
+            });
+        }
+    }
+}
+/**
+ * The shared admission TAIL for both authored sources.
+ * When `preloadedManifest` is supplied we use that snapshot (no re-read) so a
+ * prior trust decision (project-local) and the compat gate see the identical
+ * declaration. This removes the TOCTOU between the trust-bearing read and the
+ * gate read for the deny-by-default authored path.
+ *
+ * @throws {PluginIncompatibleError} when the sidecar is missing/malformed or
+ *   the tool is compatibility-incompatible.
+ */
+function admitAuthoredTool(source, dir, preloadedManifest) {
+    // When a preloaded manifest is supplied (project-local trust path), we use
+    // that exact snapshot for the compat gate. This eliminates a TOCTOU between
+    // the read that decided "this id is allowlisted" and the read that feeds the
+    // compatibility check. The later dynamic import of the .mjs still sees
+    // whatever is on disk at execution time (inherent for authored code).
+    const rawManifest = preloadedManifest ?? loadToolManifest(source, dir);
+    if (rawManifest === undefined) {
+        throw new PluginIncompatibleError(`${source} tool at '${dir}' has no conformant ${PROJECT_LOCAL_MANIFEST_FILE} sidecar`, { diagnostic: 'manifest missing or malformed' });
+    }
+    const result = admitTool({
+        manifest: rawManifest,
+        source,
+        dir,
+        // An authored tool (placed in the project tree or the user's home dir) was
+        // explicitly authored by the user, so an incompatible one fails the run
+        // rather than skipping silently.
+        explicitlyRequested: true,
+    });
+    if (result.decision !== 'admit') {
+        throw new PluginIncompatibleError(`${source} tool '${rawManifest.id}' is incompatible: ${result.diagnostic ?? 'compatibility gate rejected it'}`, { diagnostic: result.diagnostic });
+    }
+    return { provenance: result.provenance, manifest: result.manifest };
+}
+/**
+ * Admit (or reject) a single PROJECT-LOCAL authored tool under the
+ * deny-by-default trust policy (launch, Phase 3 Task 3.2; wired into
+ * production discovery in the launch contract).
+ *
+ * A project-local tool is authored code under
+ * `<project>/opensip-cli/tools/<name>/` declaring its identity via a JSON
+ * sidecar (`opensip-tool.manifest.json`). It is read + gated WITHOUT importing
+ * its module:
+ *
+ *   1. `loadToolManifest('project-local', dir)` — identity only, no code run.
+ *   2. Trust check — {@link isProjectLocalToolTrusted}. Not allowlisted ⇒
+ *      throw {@link PluginIncompatibleError} (fail-closed, exit 5) before any
+ *      import. Allowlisted ⇒ run the shared compatibility tail; an incompatible
+ *      explicitly-trusted tool is likewise fail-closed.
+ *
+ * Returns the admitted tool's `{ provenance, manifest }` on success. The trust
+ * decision always precedes import (it is the FIRST statement here, ahead of the
+ * shared {@link admitAuthoredTool} tail).
+ *
+ * @throws {PluginIncompatibleError} when the tool has no conformant sidecar
+ *   manifest, is not allowlisted, or is compatibility-incompatible.
+ */
+export function admitProjectLocalTool(args) {
+    // Trust decision FIRST — deny-by-default, before any compatibility maths
+    // and (critically) before the tool's module could ever be imported. The id
+    // is read from the sidecar identity, so load the manifest once here for the
+    // trust check, then hand the same dir to the shared tail.
+    const manifest = loadToolManifest('project-local', args.dir);
+    if (manifest === undefined) {
+        throw new PluginIncompatibleError(`project-local tool at '${args.dir}' has no conformant ${PROJECT_LOCAL_MANIFEST_FILE} sidecar`, { diagnostic: 'manifest missing or malformed' });
+    }
+    if (!isProjectLocalToolTrusted(manifest.id, args.env)) {
+        throw new PluginIncompatibleError(`project-local tool '${manifest.id}' is not trusted to load (deny-by-default). ` +
+            `Allowlist it via OPENSIP_CLI_ALLOW_PROJECT_TOOLS='${manifest.id}' to admit it.`, { diagnostic: 'project-local tool not allowlisted (deny-by-default)' });
+    }
+    // Pass the manifest we just loaded (and whose id we just trusted) so the
+    // compat gate in the tail sees the identical declaration. Closes the
+    // read-re-read TOCTOU for the deny-by-default path.
+    return admitAuthoredTool('project-local', args.dir, manifest);
+}
+/**
+ * Admit a single USER-GLOBAL authored tool — the trusted-by-default sibling of
+ * {@link admitProjectLocalTool}.
+ *
+ * A user-global tool is an authored sidecar under
+ * `~/.opensip-cli/tools/<name>/`. The user deliberately placed it in their
+ * own home dir (the `npm i -g` analogue for authored code), so there is **no
+ * allowlist gate** — it is trusted-by-default. It still reads the static
+ * sidecar and runs `admitTool` BEFORE the module could be imported (the shared
+ * {@link admitAuthoredTool} tail), so trust-before-import holds for this leg
+ * too: a global tool the user explicitly authored is fail-closed on a
+ * missing/incompatible manifest, never a silent skip.
+ *
+ * @throws {PluginIncompatibleError} when the tool has no conformant sidecar
+ *   manifest or is compatibility-incompatible.
+ */
+export function admitUserGlobalTool(args) {
+    // No trust gate — `user-global` is trusted-by-shipping-into-$HOME.
+    return admitAuthoredTool('user-global', args.dir);
+}
+/**
+ * Discover + admit + register AUTHORED Tool sidecars from the two authored
+ * roots, then dynamic-import each admitted runtime through the shared
+ * `importToolRuntime` seam — the same admit → import → register path the
+ * bundled and installed legs travel (ADR-0027; this is the leg that makes the
+ * dormant {@link admitProjectLocalTool} live).
+ *
+ * Two roots, two trust postures:
+ *   - **global** (`~/.opensip-cli/tools/`) → {@link admitUserGlobalTool},
+ *     trusted-by-default.
+ *   - **project** (`<project>/opensip-cli/tools/`) → {@link admitProjectLocalTool},
+ *     deny-by-default (allowlist via `OPENSIP_CLI_ALLOW_PROJECT_TOOLS`).
+ *
+ * Global is processed FIRST so a project-authored tool cannot shadow a same-id
+ * global one — matching the `~/.opensip-cli/plugins` precedence note in
+ * {@link buildToolDiscoverySources} (first-writer-wins via the registry).
+ * `builtInIds` are skipped so an authored tool never shadows a bundled one.
+ *
+ * **Trust-before-import.** For each candidate, the admit step (which EMBEDS the
+ * trust decision — deny-by-default inside `admitProjectLocalTool`) runs to
+ * completion BEFORE `importToolRuntime`. A non-allowlisted project tool THROWS
+ * `PluginIncompatibleError` (exit 5) here, propagated out of the walk: it must
+ * fail the run loudly — that is the clone-protection contract.
+ *
+ * **Error-posture asymmetry (deliberate).** An un-allowlisted *project* tool is
+ * fail-closed by policy (clone-risk; the user must opt in). A *global* tool that
+ * fails to load is also fail-closed (the user explicitly authored it into
+ * `$HOME`). This differs from the *installed* npm leg, where a stray bad plugin
+ * skips-with-diagnostic so it can't take fit/graph/sim down — authored tools are
+ * first-party-intent, installed tools are ambient.
+ *
+ * @param registry The per-invocation tool registry to populate.
+ * @param opts.projectAuthoredDir `resolveProjectPaths(root).authoredToolsDir`,
+ *   or `undefined` when there is no resolvable project context.
+ * @param opts.globalAuthoredDir `resolveUserPaths().authoredToolsDir`.
+ * @param opts.env Environment carrying the project allowlist (default
+ *   `process.env`); injectable for tests.
+ * @param builtInIds Bundled-tool ids to skip on a name collision.
+ * @param provenance Sink for admitted authored tools' provenance records.
+ * @param manifests Sink for admitted authored tools' manifests (§5.3).
+ * @throws {PluginIncompatibleError} for an un-allowlisted project tool, or any
+ *   authored tool whose sidecar/runtime is missing/incompatible (fail-closed).
+ */
+export async function discoverAndRegisterAuthoredTools(registry, opts, builtInIds, provenance = [], manifests = []) {
+    // Global FIRST (trusted-by-default), then project (deny-by-default).
+    for (const candidate of discoverAuthoredToolSidecars(opts.globalAuthoredDir)) {
+        await admitAndRegisterAuthored({
+            registry,
+            admission: admitUserGlobalTool({ dir: candidate.dir }),
+            dir: candidate.dir,
+            builtInIds,
+            provenance,
+            manifests,
+        });
+    }
+    if (opts.projectAuthoredDir !== undefined) {
+        for (const candidate of discoverAuthoredToolSidecars(opts.projectAuthoredDir)) {
+            // admitProjectLocalTool embeds the deny-by-default trust gate; a
+            // non-allowlisted tool THROWS here, BEFORE importToolRuntime below.
+            await admitAndRegisterAuthored({
+                registry,
+                admission: admitProjectLocalTool({ dir: candidate.dir, env: opts.env }),
+                dir: candidate.dir,
+                builtInIds,
+                provenance,
+                manifests,
+            });
+        }
+    }
+}
+/**
+ * Shared register-step for an already-ADMITTED authored tool: skip a
+ * built-in-id collision, dynamic-import the runtime (fail-closed on failure —
+ * an authored tool is first-party-intent), run the manifest⇔runtime drift
+ * guard, register, and record provenance + manifest. Admission (incl. the trust
+ * decision) has already happened by the time this is called — so import here
+ * never precedes a trust decision.
+ *
+ * @throws {PluginIncompatibleError} when the authored tool's runtime fails to
+ *   load via the plugin path — an authored tool is first-party-intent, so a
+ *   load failure is fail-closed (surfaced), never silently skipped.
+ */
+async function admitAndRegisterAuthored(args) {
+    const { registry, admission, dir, builtInIds, provenance, manifests } = args;
+    const { provenance: prov, manifest } = admission;
+    // Never shadow a bundled tool (defense in depth; the registry also dedupes).
+    if (builtInIds.has(prov.id))
+        return;
+    const load = await importToolRuntime(dir);
+    if (!load.ok) {
+        const detailSuffix = load.detail ? `: ${load.detail}` : '';
+        throw new PluginIncompatibleError(`${prov.source} tool '${prov.id}' failed to load via the plugin path (${load.reason}${detailSuffix})`, { diagnostic: `authored tool runtime load failed: ${load.reason}` });
+    }
+    // Drift guard: the static sidecar and the runtime tool are two declarations
+    // of the same identity — catch a sidecar that fell out of sync.
+    assertManifestMatchesTool(manifest, load.tool);
+    registry.register(load.tool);
+    provenance.push(prov);
+    manifests.push(manifest);
+}
+//# sourceMappingURL=register-tools-discovery.js.map

package/dist/bootstrap/register-tools-discovery.js.map

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

package/dist/bootstrap/register-tools-mount.d.ts

@@ -0,0 +1,25 @@
+import { type CliProgram } from '@opensip-cli/contracts';
+import { type ToolCliContext, type ToolRegistry } from '@opensip-cli/core';
+/**
+ * Walk the registry and mount each tool's commands onto `program`. This is
+ * **step 8** of the tool lifecycle (launch, §5.4) — see
+ * {@link runToolLifecycle}.
+ *
+ * Public launch: there is ONE command surface — the tool's declared `commandSpecs`,
+ * mounted by `mountCommandSpec`. `register()` and the raw-Commander `program`
+ * handle on the tool context are gone, so the host owns `program` and passes it
+ * in here (the tool never touches Commander). A tool with no `commandSpecs` is a
+ * mis-declaration: it contributes no commands, surfaced loudly via
+ * `cli.tool.no_command_surface`.
+ *
+ * Failures are isolated per tool — one tool whose spec fails to mount must not
+ * take the whole CLI down. The failure is logged + stderr-warned, then we
+ * continue with the next tool.
+ *
+ * @param registry The per-invocation tool registry to walk.
+ * @param program The root Commander program (host-owned; the composition root
+ *   passes it — it is no longer reachable through the tool context, §8).
+ * @param ctx The per-invocation handler context (render/emit/scope — no program).
+ */
+export declare function mountAllToolCommands(registry: ToolRegistry, program: CliProgram, ctx: ToolCliContext): void;
+//# sourceMappingURL=register-tools-mount.d.ts.map

package/dist/bootstrap/register-tools-mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-tools-mount.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAO9F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CAqBN"}