opensip-cli 0.1.5 → 0.1.7

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

@@ -1,9 +1,122 @@
 // @fitness-ignore-file performance-anti-patterns -- sequential await across discovered tool packages preserves load order for plugin-conflict detection; bounded by installed plugin count
-import { assertManifestMatchesTool, discoverAuthoredToolSidecars, discoverToolPackagesFromAnchors, logger, PluginIncompatibleError, resolveProjectContext, resolveProjectPaths, resolveUserPaths, } from '@opensip-cli/core';
-import { importToolRuntime } from './admit-tool-package.js';
-import { admitProjectLocalTool, admitUserGlobalTool, } from './authored-tool-admission.js';
-import { admitInstalledTool, emitInstalledLoadFailure } from './installed-tool-admission.js';
-import { BOOTSTRAP_MODULE } from './register-tools-shared.js';
+/**
+ * register-tools-discovery — installed + authored tool admission and discovery.
+ *
+ * Extracted from register-tools.ts so the bundled registration path stays a
+ * focused module under the file-length soft limit.
+ */
+import { admitTool, assertManifestMatchesTool, discoverAuthoredToolSidecars, discoverToolPackagesFromAnchors, logger, PluginIncompatibleError, PROJECT_LOCAL_MANIFEST_FILE, resolveProjectContext, resolveProjectPaths, resolveUserPaths, loadToolManifest, } from '@opensip-cli/core';
+import { hostRuntimeImportPolicyFor, importToolRuntime, } from './admit-tool-package.js';
+import { BOOTSTRAP_MODULE } from './constants.js';
+import { isProjectLocalToolTrusted } from './tool-trust.js';
+/**
+ * The shared admission tail for both authored sources. When `preloadedManifest`
+ * is supplied we use that snapshot so the trust decision and compatibility gate
+ * see the identical declaration.
+ *
+ * @throws {PluginIncompatibleError} When the sidecar manifest is missing,
+ * malformed, or rejected by the compatibility gate.
+ */
+function admitAuthoredTool(source, dir, preloadedManifest) {
+    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,
+        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 PROJECT-LOCAL authored tool under the deny-by-default trust
+ * policy. The trust decision always precedes module import; a non-allowlisted
+ * tool fails closed before any authored code can run.
+ *
+ * @throws {PluginIncompatibleError} When the sidecar manifest is missing,
+ * malformed, incompatible, or not trusted by the project-tool allowlist.
+ */
+export function admitProjectLocalTool(args) {
+    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)' });
+    }
+    return admitAuthoredTool('project-local', args.dir, manifest);
+}
+/**
+ * Admit a USER-GLOBAL authored tool — trusted-by-default because the user placed
+ * it in their own home-dir tool host, but still fail-closed on a missing or
+ * incompatible manifest.
+ */
+export function admitUserGlobalTool(args) {
+    return admitAuthoredTool('user-global', args.dir);
+}
+/**
+ * Run the admission gate over a discovered INSTALLED tool package before its
+ * module is imported. Installed tools are best-effort: incompatible or malformed
+ * ambient packages skip with diagnostics rather than crashing unrelated commands.
+ */
+function admitInstalledTool(pkg, builtInIds) {
+    const manifest = loadToolManifest('installed', pkg.packageDir);
+    if (manifest === undefined) {
+        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;
+    const result = admitTool({
+        manifest,
+        source: 'installed',
+        dir: pkg.packageDir,
+        packageName: pkg.name,
+        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 failure reason maps to its
+ * own diagnostic while preserving the installed leg's skip-not-crash posture.
+ */
+export 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,
+    });
+}
 /**
  * Build the ordered tool-discovery sources. Order is precedence
  * (first-occurrence-wins on duplicate name):
@@ -58,42 +171,33 @@ export function buildToolDiscoverySources(cwd, cliInstallDir) {
  * @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);
+    // Stable-UUID collision guard (ADR-0048): a discovered package whose runtime
+    // `metadata.id` (the stable UUID) is already registered is the SAME tool
+    // re-discovered via a stray anchor — e.g. a second copy of `@opensip-cli/*`
+    // in a node_modules ABOVE the project root. The human-name skip alone misses
+    // it when the two copies disagree on `metadata.name` (e.g. one built before
+    // the verb-rename), which would otherwise double-register and trip the
+    // session-replay duplicate guard. UUID is identity; skip on a UUID match.
+    const registeredStableIds = new Set(registry.list().map((t) => t.metadata.id));
     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);
+            const load = await importToolRuntime(pkg.packageDir, hostRuntimeImportPolicyFor('installed'));
             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.
+            // Stable-UUID collision (see above): the same tool already registered
+            // under a possibly-different human name. Skip the re-discovered copy.
+            if (registeredStableIds.has(load.tool.metadata.id))
+                continue;
             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);
         }
@@ -112,48 +216,9 @@ export async function discoverAndRegisterToolPackages(registry, opts, builtInIds
 /**
  * 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).
+ * `importToolRuntime` seam.
  */
 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,
@@ -166,8 +231,6 @@ export async function discoverAndRegisterAuthoredTools(registry, opts, builtInId
     }
     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 }),
@@ -179,31 +242,17 @@ export async function discoverAndRegisterAuthoredTools(registry, opts, builtInId
         }
     }
 }
-/**
- * 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.
- */
+/** @throws {PluginIncompatibleError} When the authored tool runtime fails to load. */
 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);
+    const load = await importToolRuntime(dir, hostRuntimeImportPolicyFor(prov.source));
     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);

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

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

@@ -1,5 +1,5 @@
 import { type CliProgram } from '@opensip-cli/contracts';
-import { type ToolCliContext, type ToolRegistry } from '@opensip-cli/core';
+import { type Tool, 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
@@ -22,4 +22,21 @@ import { type ToolCliContext, type ToolRegistry } from '@opensip-cli/core';
  * @param ctx The per-invocation handler context (render/emit/scope — no program).
  */
 export declare function mountAllToolCommands(registry: ToolRegistry, program: CliProgram, ctx: ToolCliContext): void;
+/**
+ * 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`.
+ *
+ * Nesting (`CommandSpec.parent`, tool-command-surface-taxonomy Task 0.4): a spec
+ * declaring `parent` is mounted as a SUBCOMMAND of the same-tool spec whose name
+ * matches `parent` (the tool's primary verb) — enabling the `<tool> <verb>`
+ * grammar (`graph export`, `fit list`). This is the SAME generic parent+leaf
+ * pattern the host already uses for `sessions`/`plugin`/`tools`
+ * (`host-command-specs.ts:mountHostCommands`): the parent's mounted Commander
+ * command (which also carries its own action) hosts the child via
+ * `mountCommandSpec(primaryCmd, child, ctx)`. No per-tool special case. Specs
+ * with no `parent` mount flat onto the root program exactly as before.
+ */
+export declare function mountOneTool(program: CliProgram, tool: Tool, ctx: ToolCliContext): void;
 //# sourceMappingURL=register-tools-mount.d.ts.map

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

@@ -1 +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"}
+{"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,EAAU,KAAK,IAAI,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAY9F;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CA2BN;AAqCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI,CA4BvF"}

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

@@ -1,7 +1,9 @@
 import { logger } from '@opensip-cli/core';
+import { internalCommandNames, showInternalCommands, } from '../commands/internal-command-visibility.js';
 import { mountCommandSpec } from '../commands/mount-command-spec.js';
 import { bindToolCliContext } from './bind-tool-context.js';
-import { BOOTSTRAP_MODULE } from './register-tools-shared.js';
+import { BOOTSTRAP_MODULE } from './constants.js';
+import { decorateToolPrimary } from './decorate-tool-primary.js';
 /**
  * Walk the registry and mount each tool's commands onto `program`. This is
  * **step 8** of the tool lifecycle (launch, §5.4) — see
@@ -41,37 +43,135 @@ export function mountAllToolCommands(registry, program, ctx) {
             });
         }
     }
+    // tool-command-surface-taxonomy Task 1.2: hide Tier-3 internal commands from
+    // `--help`. This is the single place that has walked EVERY tool's commands, so
+    // the descriptor-driven hide policy lives here (the host owns it; tools never
+    // pass a hidden flag). The commands stay mounted + invocable — only their
+    // `--help` listing is suppressed. `OPENSIP_CLI_SHOW_INTERNAL=1` reveals them.
+    hideInternalCommands(registry, program);
     // 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);
 }
+/**
+ * Hide every mounted command the tools declared `visibility: 'internal'`
+ * (Tier-3) from `--help`, unless `OPENSIP_CLI_SHOW_INTERNAL=1`
+ * ({@link showInternalCommands}).
+ *
+ * Mechanism: Commander omits a command from help when its `_hidden` property is
+ * `true`; the command stays fully invocable (`opensip graph-shard-worker <spec>`
+ * still runs). That is the documented, minimal "keep the subcommand but hide it"
+ * mechanism — there is no post-hoc public `.command(name, desc, { hidden })`
+ * path, so we set the property Commander itself reads for help filtering.
+ *
+ * The internal-name set is descriptor-driven ({@link internalCommandNames}) — the
+ * SAME source the completion inventory filters on — so help and completion stay
+ * in lockstep. Walks the full command tree (including nested `<tool> <verb>`
+ * children) so a future internal nested command is hidden too.
+ */
+function hideInternalCommands(registry, program) {
+    if (showInternalCommands())
+        return; // reveal override — leave everything visible
+    const internal = internalCommandNames(registry);
+    if (internal.size === 0)
+        return;
+    const hide = (cmd) => {
+        for (const sub of cmd.commands) {
+            if (internal.has(sub.name())) {
+                // Commander 15 reads `_hidden` when filtering help; setting it true hides
+                // the command from `--help` while leaving it invocable. Typed via a
+                // narrow structural cast — `_hidden` is Commander-internal, not on the
+                // public `Command` type, but it is the property the help renderer reads.
+                sub._hidden = true;
+            }
+            hide(sub);
+        }
+    };
+    hide(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`.
+ *
+ * Nesting (`CommandSpec.parent`, tool-command-surface-taxonomy Task 0.4): a spec
+ * declaring `parent` is mounted as a SUBCOMMAND of the same-tool spec whose name
+ * matches `parent` (the tool's primary verb) — enabling the `<tool> <verb>`
+ * grammar (`graph export`, `fit list`). This is the SAME generic parent+leaf
+ * pattern the host already uses for `sessions`/`plugin`/`tools`
+ * (`host-command-specs.ts:mountHostCommands`): the parent's mounted Commander
+ * command (which also carries its own action) hosts the child via
+ * `mountCommandSpec(primaryCmd, child, ctx)`. No per-tool special case. Specs
+ * with no `parent` mount flat onto the root program exactly as before.
+ */
+export function mountOneTool(program, tool, ctx) {
+    if (tool.commandSpecs === undefined || tool.commandSpecs.length === 0) {
+        // 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',
+        });
+        return;
+    }
+    const toolCtx = bindToolCliContext(tool, ctx);
+    const mountedByName = mountFlatSpecs(program, tool, toolCtx);
+    // Host-owned uniform decoration of the tool PRIMARY (the flat run command
+    // whose name === metadata.name): per-tool `--version`, guaranteed
+    // `--cwd`/`--json`/`--config`, and `--quiet`/`--verbose`. Applied ONCE here
+    // in the mount layer (not re-declared per tool) and ONLY to the primary —
+    // never the nested `<tool> <verb>` children or Tier-3 workers. A tool that
+    // declares no primary (its name doesn't match a flat spec) gets no
+    // decoration, exactly as before.
+    const primaryCmd = mountedByName.get(tool.metadata.name);
+    if (primaryCmd !== undefined)
+        decorateToolPrimary(primaryCmd, tool);
+    mountNestedSpecs(program, tool, toolCtx, mountedByName);
+}
+/**
+ * First pass: mount every flat (no-`parent`) spec onto the root program,
+ * recording each mounted command by name so nested children can resolve their
+ * declared parent. `Tool.commandSpecs` is `CommandSpec<unknown, ToolCliContext>[]`,
+ * which is assignable to the mounter's `HostCommandSpec` (handler contravariance).
  */
-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.
+function mountFlatSpecs(program, tool, toolCtx) {
+    const mountedByName = new Map();
+    for (const spec of tool.commandSpecs ?? []) {
+        if (spec.parent !== undefined)
+            continue;
+        mountedByName.set(spec.name, mountCommandSpec(program, spec, toolCtx));
+    }
+    return mountedByName;
+}
+/**
+ * Second pass: mount each `parent`-nested spec onto its parent's mounted command
+ * (the `<tool> <verb>` grammar). A spec whose declared parent was not mounted in
+ * this tool is surfaced loudly (and mounted flat at root) rather than silently
+ * dropped.
+ */
+function mountNestedSpecs(program, tool, toolCtx, mountedByName) {
+    for (const spec of tool.commandSpecs ?? []) {
+        if (spec.parent === undefined)
+            continue;
+        const parentCmd = mountedByName.get(spec.parent);
+        if (parentCmd === undefined) {
+            logger.warn({
+                evt: 'cli.tool.unknown_command_parent',
+                module: BOOTSTRAP_MODULE,
+                toolId: tool.metadata.id, // stable
+                toolName: tool.metadata.name ?? tool.metadata.id,
+                detail: `command '${spec.name}' declares parent '${spec.parent}', which is not a flat command on this tool; mounting flat at root instead`,
+            });
             mountCommandSpec(program, spec, toolCtx);
+            continue;
         }
-        return;
+        mountCommandSpec(parentCmd, spec, toolCtx);
     }
-    // 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';
 /**

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

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

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

@@ -1,18 +1,62 @@
 /**
- * register-tools — populate the kernel `ToolRegistry` with first-party
- * tools (fitness / simulation / graph) plus any third-party tool
- * packages discovered on disk.
+ * register-tools — populate the kernel ToolRegistry with bundled, installed,
+ * and authored tools (ADR-0027 / ADR-0041).
  *
- * Extracted from `index.ts`. The bundled-id skip below is defense in
- * depth: as of Layer 1 Phase 1 the registry itself enforces
- * first-writer-wins on duplicate ids and logs a structured
- * `tool.registry.duplicate` warning. Keeping the explicit guard avoids
- * a noisy warning when a third-party package happens to ship under a
- * built-in id.
+ * Merged registration cluster: manifest constants, bundled admission,
+ * installed/authored admission, and discovery walkers. Command mounting lives
+ * in register-tools-mount.ts.
  */
-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, discoverAndRegisterAuthoredTools, } from './register-tools-discovery.js';
-export { type AuthoredAdmission, admitProjectLocalTool, admitUserGlobalTool, } from './authored-tool-admission.js';
-export { mountAllToolCommands } from './register-tools-mount.js';
+import { type ToolPluginManifest, type ToolProvenance, type ToolRegistry } from '@opensip-cli/core';
+export { BUNDLED_CAPABILITY_PACKS, BUNDLED_TOOL_PACKAGES, EXPECTED_SCAFFOLDING_TOOL_IDS, } from './bundled-manifest.js';
+/**
+ * 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;
+/**
+ * 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 { admitProjectLocalTool, admitUserGlobalTool, buildToolDiscoverySources, discoverAndRegisterAuthoredTools, discoverAndRegisterToolPackages, emitInstalledLoadFailure, type AuthoredAdmission, type DiscoveryOptions, } from './register-tools-discovery.js';
+export { mountAllToolCommands, mountOneTool } 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":"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,gCAAgC,GACjC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EACL,KAAK,iBAAiB,EACtB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"register-tools.d.ts","sourceRoot":"","sources":["../../src/bootstrap/register-tools.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAMH,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,GAC9B,MAAM,uBAAuB,CAAC;AAK/B;;;;;;;;;;;;;;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;AAQD;;;;;;;;;;;;;;;;;;;;;;;;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,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,yBAAyB,EACzB,gCAAgC,EAChC,+BAA+B,EAC/B,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,GACtB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC"}