opensip-cli 0.1.2 → 0.1.3

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

@@ -0,0 +1,91 @@
+import { logger } from '@opensip-cli/core';
+import { mountCommandSpec } from '../commands/mount-command-spec.js';
+import { bindToolCliContext } from './bind-tool-context.js';
+import { BOOTSTRAP_MODULE } from './register-tools-shared.js';
+/**
+ * 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 function mountAllToolCommands(registry, program, ctx) {
+    for (const tool of registry.list()) {
+        try {
+            mountOneTool(program, tool, ctx);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            const human = tool.metadata.name ?? tool.metadata.id;
+            process.stderr.write(`opensip: tool ${human} failed to mount: ${msg}\n`);
+            logger.warn({
+                evt: 'cli.tool.register_failed',
+                module: BOOTSTRAP_MODULE,
+                toolId: tool.metadata.id, // stable UUID
+                toolName: human,
+                error: msg,
+            });
+        }
+    }
+    // ADR-0021: one shared help shape across every mounted command — uniform
+    // option/subcommand ordering and a docs footer — applied here (the single
+    // place that has walked every tool's commands) rather than per tool.
+    applySharedHelpConfiguration(program);
+}
+/**
+ * Mount ONE tool's commands from its declared `commandSpecs` — the only command
+ * surface (public launch). Extracted so {@link mountAllToolCommands} keeps its
+ * per-tool failure isolation around a single call. A tool with no `commandSpecs`
+ * contributes nothing and is surfaced via `cli.tool.no_command_surface`.
+ */
+function mountOneTool(program, tool, ctx) {
+    if (tool.commandSpecs !== undefined && tool.commandSpecs.length > 0) {
+        const toolCtx = bindToolCliContext(tool, ctx);
+        for (const spec of tool.commandSpecs) {
+            // `Tool.commandSpecs` is `CommandSpec<unknown, ToolCliContext>[]`, which
+            // is assignable to the mounter's `HostCommandSpec` (handler contravariance
+            // — an `unknown`-opts handler accepts a `Record`-opts call). No cast.
+            mountCommandSpec(program, spec, toolCtx);
+        }
+        return;
+    }
+    // No declarative command surface — a mis-declared tool contributes no commands.
+    // Surface it rather than silently mounting nothing.
+    logger.warn({
+        evt: 'cli.tool.no_command_surface',
+        module: BOOTSTRAP_MODULE,
+        toolId: tool.metadata.id, // stable
+        toolName: tool.metadata.name ?? tool.metadata.id,
+        detail: 'tool declares no commandSpecs; no commands mounted',
+    });
+}
+const DOCS_HELP_FOOTER = '\nDocs: https://opensip.ai/docs/opensip-cli';
+/**
+ * Apply one help configuration to the root program and every (sub)command:
+ * options + subcommands sort alphabetically so the help reads the same across
+ * `fit`/`graph`/`sim`, and the root help ends with a docs pointer (ADR-0021).
+ */
+function applySharedHelpConfiguration(program) {
+    const configure = (cmd) => {
+        cmd.configureHelp({ sortOptions: true, sortSubcommands: true });
+        for (const sub of cmd.commands)
+            configure(sub);
+    };
+    configure(program);
+    program.addHelpText('after', DOCS_HELP_FOOTER);
+}
+//# sourceMappingURL=register-tools-mount.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-tools-mount.js","sourceRoot":"","sources":["../../src/bootstrap/register-tools-mount.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAqD,MAAM,mBAAmB,CAAC;AAE9F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAErE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAsB,EACtB,OAAmB,EACnB,GAAmB;IAEnB,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YACnE,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACrD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iBAAiB,KAAK,qBAAqB,GAAG,IAAI,CAAC,CAAC;YACzE,MAAM,CAAC,IAAI,CAAC;gBACV,GAAG,EAAE,0BAA0B;gBAC/B,MAAM,EAAE,gBAAgB;gBACxB,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,cAAc;gBACxC,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAE,GAAG;aACX,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,yEAAyE;IACzE,0EAA0E;IAC1E,qEAAqE;IACrE,4BAA4B,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,OAAmB,EAAE,IAAU,EAAE,GAAmB;IACxE,IAAI,IAAI,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpE,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC9C,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACrC,yEAAyE;YACzE,2EAA2E;YAC3E,sEAAsE;YACtE,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO;IACT,CAAC;IACD,gFAAgF;IAChF,oDAAoD;IACpD,MAAM,CAAC,IAAI,CAAC;QACV,GAAG,EAAE,6BAA6B;QAClC,MAAM,EAAE,gBAAgB;QACxB,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE;QAChD,MAAM,EAAE,oDAAoD;KAC7D,CAAC,CAAC;AACL,CAAC;AAED,MAAM,gBAAgB,GAAG,6CAA6C,CAAC;AAEvE;;;;GAIG;AACH,SAAS,4BAA4B,CAAC,OAAmB;IACvD,MAAM,SAAS,GAAG,CAAC,GAAe,EAAQ,EAAE;QAC1C,GAAG,CAAC,aAAa,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ;YAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IACjD,CAAC,CAAC;IACF,SAAS,CAAC,OAAO,CAAC,CAAC;IACnB,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;AACjD,CAAC"}

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

@@ -0,0 +1,40 @@
+/** `module` field on every structured log event emitted from this file. */
+export declare const BOOTSTRAP_MODULE = "cli:bootstrap";
+export declare const BUNDLED_TOOL_PACKAGES: readonly string[];
+/**
+ * The ADR-0038 back-compat pin: the tool IDS whose `init` scaffold dirs the
+ * pre-registry-driven CLI ALWAYS created (fit/sim). The composition root warns
+ * (`cli.tool.expected_bundled_absent`) when one of these is missing from the
+ * populated registry, so a build whose {@link BUNDLED_TOOL_PACKAGES} drifted
+ * (a tool removed, a packaging variant) under-scaffolds LOUDLY instead of
+ * silently.
+ *
+ * Now derived from the same manifest as BUNDLED_TOOL_PACKAGES (Workstream A)
+ * so a single edit keeps them in sync. `graph` is correctly absent: it never
+ * scaffolded (`pluginLayout` undefined).
+ */
+export declare const EXPECTED_SCAFFOLDING_TOOL_IDS: readonly string[];
+/**
+ * Resolve a bundled tool's PACKAGE DIR — the directory whose `package.json`
+ * carries the `opensipTools` manifest.
+ *
+ * The `./package.json` subpath is not declared in each engine's `exports`,
+ * so `require.resolve('<pkg>/package.json')` throws. Instead we resolve the
+ * package's MAIN entry (a bare-name resolve, always permitted by `exports`)
+ * and walk up to the nearest ancestor directory that has a `package.json`
+ * whose `name` matches `packageName`. That ancestor IS the tool's own
+ * package dir under both the source layout and pnpm's workspace-injected
+ * `node_modules` layout (verified against fitness/simulation/graph here).
+ *
+ * @returns the resolved package directory, or `undefined` when the package
+ *   cannot be resolved (should never happen for a bundled direct dep).
+ */
+export declare function resolveBundledPackageDir(packageName: string): string | undefined;
+/**
+ * Resolve a bundled tool package's on-disk directory, requiring success.
+ *
+ * @throws {PluginIncompatibleError} when the package directory cannot be
+ *   resolved on disk (its manifest is unreadable).
+ */
+export declare function resolveRequiredBundledPackageDir(packageName: string): string;
+//# sourceMappingURL=register-tools-shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-tools-shared.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools-shared.ts"],"names":[],"mappings":"AAOA,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,kBAAkB,CAAC;AAmBhD,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAAuC,CAAC;AAEnG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkChF;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAO5E"}

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

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { logger, PluginIncompatibleError } from '@opensip-cli/core';
+/** `module` field on every structured log event emitted from this file. */
+export const BOOTSTRAP_MODULE = 'cli:bootstrap';
+/** Used to resolve the bundled engine package dirs from the CLI's own module graph. */
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * Bundled first-party tools are now data-driven (platform-ergonomics Workstream A).
+ * The source of truth is the co-located JSON manifest (single edit site when
+ * adding a first-party tool). Loaded via fs + import.meta.url (works in both
+ * src dev and dist/ after tsc; the json is committed under src/ and must be
+ * present next to the .js in dist at runtime — ensured by package "files": ["dist"]
+ * + manual cp in build or future asset plugin; no resolveJsonModule dep).
+ */
+const manifestUrl = new URL('bundled-tools.manifest.json', import.meta.url);
+const bundledManifest = JSON.parse(readFileSync(fileURLToPath(manifestUrl), 'utf8'));
+export const BUNDLED_TOOL_PACKAGES = bundledManifest.bundledPackages;
+/**
+ * The ADR-0038 back-compat pin: the tool IDS whose `init` scaffold dirs the
+ * pre-registry-driven CLI ALWAYS created (fit/sim). The composition root warns
+ * (`cli.tool.expected_bundled_absent`) when one of these is missing from the
+ * populated registry, so a build whose {@link BUNDLED_TOOL_PACKAGES} drifted
+ * (a tool removed, a packaging variant) under-scaffolds LOUDLY instead of
+ * silently.
+ *
+ * Now derived from the same manifest as BUNDLED_TOOL_PACKAGES (Workstream A)
+ * so a single edit keeps them in sync. `graph` is correctly absent: it never
+ * scaffolded (`pluginLayout` undefined).
+ */
+export const EXPECTED_SCAFFOLDING_TOOL_IDS = bundledManifest.scaffoldingToolIds;
+/**
+ * Resolve a bundled tool's PACKAGE DIR — the directory whose `package.json`
+ * carries the `opensipTools` manifest.
+ *
+ * The `./package.json` subpath is not declared in each engine's `exports`,
+ * so `require.resolve('<pkg>/package.json')` throws. Instead we resolve the
+ * package's MAIN entry (a bare-name resolve, always permitted by `exports`)
+ * and walk up to the nearest ancestor directory that has a `package.json`
+ * whose `name` matches `packageName`. That ancestor IS the tool's own
+ * package dir under both the source layout and pnpm's workspace-injected
+ * `node_modules` layout (verified against fitness/simulation/graph here).
+ *
+ * @returns the resolved package directory, or `undefined` when the package
+ *   cannot be resolved (should never happen for a bundled direct dep).
+ */
+export function resolveBundledPackageDir(packageName) {
+    let resolvedEntry;
+    try {
+        resolvedEntry = requireFromHere.resolve(packageName);
+    }
+    catch (error) {
+        // A bundled direct dep failing to resolve is a packaging fault — log it
+        // so the subsequent fail-closed throw is diagnosable, then signal the
+        // unresolved state to the caller (which raises PluginIncompatibleError).
+        logger.debug({
+            evt: 'cli.tool.bundled_unresolved',
+            module: BOOTSTRAP_MODULE,
+            packageName,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    let dir = dirname(resolvedEntry);
+    for (let i = 0; i < 50; i++) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            try {
+                const json = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (json.name === packageName)
+                    return dir;
+            }
+            catch {
+                // @swallow-ok unreadable package.json on the walk-up — keep climbing.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Resolve a bundled tool package's on-disk directory, requiring success.
+ *
+ * @throws {PluginIncompatibleError} when the package directory cannot be
+ *   resolved on disk (its manifest is unreadable).
+ */
+export function resolveRequiredBundledPackageDir(packageName) {
+    const dir = resolveBundledPackageDir(packageName);
+    if (dir !== undefined)
+        return dir;
+    throw new PluginIncompatibleError(`bundled tool '${packageName}' could not be resolved on disk; its manifest is unreadable`, { diagnostic: 'package directory not resolvable' });
+}
+//# sourceMappingURL=register-tools-shared.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register-tools-shared.js","sourceRoot":"","sources":["../../src/bootstrap/register-tools-shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAEpE,2EAA2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,eAAe,CAAC;AAEhD,uFAAuF;AACvF,MAAM,eAAe,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,6BAA6B,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC5E,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAGlF,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAsB,eAAe,CAAC,eAAe,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAsB,eAAe,CAAC,kBAAkB,CAAC;AAEnG;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,IAAI,aAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,aAAa,GAAG,eAAe,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACvD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,wEAAwE;QACxE,sEAAsE;QACtE,yEAAyE;QACzE,MAAM,CAAC,KAAK,CAAC;YACX,GAAG,EAAE,6BAA6B;YAClC,MAAM,EAAE,gBAAgB;YACxB,WAAW;YACX,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAC9D,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACjC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC1C,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAEpD,CAAC;gBACF,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW;oBAAE,OAAO,GAAG,CAAC;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,sEAAsE;YACxE,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gCAAgC,CAAC,WAAmB;IAClE,MAAM,GAAG,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC;IAClD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAClC,MAAM,IAAI,uBAAuB,CAC/B,iBAAiB,WAAW,6DAA6D,EACzF,EAAE,UAAU,EAAE,kCAAkC,EAAE,CACnD,CAAC;AACJ,CAAC"}

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

@@ -10,200 +10,8 @@
  * a noisy warning when a third-party package happens to ship under a
  * built-in id.
  */
-import { type CliProgram } from '@opensip-cli/contracts';
-import { type ToolCliContext, type ToolDiscoverySource, type ToolPluginManifest, type ToolProvenance, type ToolRegistry } from '@opensip-cli/core';
-export declare const BUNDLED_TOOL_PACKAGES: readonly string[];
-/**
- * The ADR-0038 back-compat pin: the tool IDS whose `init` scaffold dirs the
- * pre-registry-driven CLI ALWAYS created (fit/sim). The composition root warns
- * (`cli.tool.expected_bundled_absent`) when one of these is missing from the
- * populated registry, so a build whose {@link BUNDLED_TOOL_PACKAGES} drifted
- * (a tool removed, a packaging variant) under-scaffolds LOUDLY instead of
- * silently.
- *
- * Now derived from the same manifest as BUNDLED_TOOL_PACKAGES (Workstream A)
- * so a single edit keeps them in sync. `graph` is correctly absent: it never
- * scaffolded (`pluginLayout` undefined).
- */
-export declare const EXPECTED_SCAFFOLDING_TOOL_IDS: readonly string[];
-/**
- * Register the bundled first-party tools into the supplied registry, each one
- * flowing through the SAME admit → dynamic-import → register path the external
- * path uses (launch cutover — replaces the static-import + gate path).
- *
- * Per package name: `resolveBundledPackageDir` → `loadToolManifest('bundled')`
- * → `admitTool({ source: 'bundled', explicitlyRequested: true })` →
- * `importToolRuntime` (dynamic import + shape validation) → drift guard →
- * `registry.register`. A bundled tool ships with the CLI, so it is always
- * explicitly present: a missing/incompatible manifest or a runtime that fails
- * to load is FAIL-CLOSED (never a silent skip). The recorded `ToolProvenance`
- * (source `'bundled'`, trusted-by-shipping) and manifest are pushed onto the
- * optional collectors so the composition root can surface provenance
- * (`plugin list`) and seed the per-run capability registry (§5.3).
- *
- * @param registry The per-invocation tool registry to populate.
- * @param provenance Optional sink for the admitted tools' provenance records.
- * @param manifests Optional sink for the admitted tools' manifests (§5.3).
- * @param packages The bundled package names to load (defaults to
- *   {@link BUNDLED_TOOL_PACKAGES}; injectable so the fail-closed paths are
- *   testable with fixture packages).
- * @throws {PluginIncompatibleError} when a bundled tool cannot be resolved,
- *   has no conformant manifest, is out of range, or its runtime fails to load
- *   — mapped to `EXIT_CODES.PLUGIN_INCOMPATIBLE` (exit 5) by the CLI boundary.
- */
-export declare function registerFirstPartyTools(registry: ToolRegistry, provenance?: ToolProvenance[], manifests?: ToolPluginManifest[], packages?: readonly string[]): Promise<void>;
-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[];
-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>;
-/**
- * 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;
+export { BUNDLED_TOOL_PACKAGES, EXPECTED_SCAFFOLDING_TOOL_IDS } from './register-tools-shared.js';
+export { registerFirstPartyTools } from './register-tools-bundled.js';
+export { type DiscoveryOptions, buildToolDiscoverySources, discoverAndRegisterToolPackages, type AuthoredAdmission, admitProjectLocalTool, admitUserGlobalTool, discoverAndRegisterAuthoredTools, } from './register-tools-discovery.js';
+export { mountAllToolCommands } from './register-tools-mount.js';
 //# sourceMappingURL=register-tools.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAOH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAaL,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EAElB,MAAM,mBAAmB,CAAC;AAgC3B,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAoC,CAAC;AAExF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,6BAA6B,EAAE,SAAS,MAAM,EAAuC,CAAC;AA0EnG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,YAAY,EACtB,UAAU,GAAE,cAAc,EAAO,EACjC,SAAS,GAAE,kBAAkB,EAAO,EACpC,QAAQ,GAAE,SAAS,MAAM,EAA0B,GAClD,OAAO,CAAC,IAAI,CAAC,CAwCf;AA8DD,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;AAiHD,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;AAqDD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CAqBN"}
+{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAElG,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,EACL,KAAK,gBAAgB,EACrB,yBAAyB,EACzB,+BAA+B,EAC/B,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,mBAAmB,EACnB,gCAAgC,GACjC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}