opensip-cli 0.1.2 → 0.1.4

package/dist/bootstrap/register-tools.js

@@ -1,5 +1,3 @@
-// @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 -- bootstrap composition root: one cohesive tool-admission lifecycle (resolve bundled dir → loadToolManifest → admitTool, across bundled / installed / project-local sources) plus discovery-source ordering and command mounting; splitting fragments the unified admission dispatch (cf. graph.ts's identical waiver for its subcommand-dispatch surface).
 /**
  * register-tools — populate the kernel `ToolRegistry` with first-party
  * tools (fitness / simulation / graph) plus any third-party tool
@@ -12,670 +10,8 @@
  * a noisy warning when a third-party package happens to ship under a
  * built-in id.
  */
-import { existsSync, readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { admitTool, assertManifestMatchesTool, discoverAuthoredToolSidecars, discoverToolPackagesFromAnchors, loadToolManifest, logger, PluginIncompatibleError, PROJECT_LOCAL_MANIFEST_FILE, resolveProjectContext, resolveProjectPaths, resolveUserPaths, } from '@opensip-cli/core';
-import { mountCommandSpec } from '../commands/mount-command-spec.js';
-import { admitToolPackage, importToolRuntime, } from './admit-tool-package.js';
-import { isProjectLocalToolTrusted } from './tool-trust.js';
-/** `module` field on every structured log event emitted from this file. */
-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).
- */
-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).
- */
-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' });
-}
-// The runtime-load primitive (`importToolRuntime` + `ToolRuntimeLoad`) and the
-// full admission SEQUENCE (`admitToolPackage`) live in `admit-tool-package.ts`
-// (ADR-0041: one validator, four consumers). This file keeps the per-source
-// POLICY: bundled fails closed below; the installed/authored legs skip with
-// diagnostics.
-/**
- * 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 async function registerFirstPartyTools(registry, provenance = [], manifests = [], packages = BUNDLED_TOOL_PACKAGES) {
-    for (const packageName of packages) {
-        const dir = resolveRequiredBundledPackageDir(packageName);
-        // The shared admission SEQUENCE (ADR-0041). The bundled POLICY below maps
-        // each failed section to the exact fail-closed error this path always
-        // threw — a bundled tool ships with the CLI, so every failure is a
-        // packaging fault, never a silent skip.
-        const report = await admitToolPackage({
-            dir,
-            source: 'bundled',
-            packageName,
-            // A bundled tool ships with the CLI; it is always explicitly present,
-            // so an incompatible manifest fails the run rather than skipping.
-            explicitlyRequested: true,
-        });
-        if (!report.ok) {
-            // @fitness-ignore-next-line detached-promises -- synchronous never-returning thrower; the heuristic mistakes the bare call for an unawaited promise
-            throwBundledAdmissionFailure(packageName, report);
-        }
-        /* v8 ignore next 3 -- throwBundledAdmissionFailure never returns on a failed report; this guard narrows types */
-        if (report.tool === undefined ||
-            report.provenance === undefined ||
-            report.manifest === undefined) {
-            throw new PluginIncompatibleError(`bundled tool '${packageName}' produced an incomplete admission report`, { diagnostic: 'incomplete admission report' });
-        }
-        registry.register(report.tool);
-        provenance.push(report.provenance);
-        // Record the manifest so the pre-action-hook can register this tool's
-        // declared capability domains into the per-run capability registry
-        // (launch, §5.3).
-        manifests.push(report.manifest);
-    }
-}
-/**
- * The bundled FAIL-CLOSED policy: convert a failed {@link AdmissionReport}
- * into the same `PluginIncompatibleError` (message + diagnostic) the inline
- * pipeline threw before the ADR-0041 factoring. Never returns.
- *
- * @throws {PluginIncompatibleError} always (or rethrows the original
- *   coherence error from `assertManifestMatchesTool`, preserving its type).
- */
-function throwBundledAdmissionFailure(packageName, report) {
-    const failed = report.sections.find((s) => !s.ok);
-    const failedSection = failed?.section;
-    if (failedSection === 'manifest') {
-        throw new PluginIncompatibleError(`bundled tool '${packageName}' has no conformant package.json#opensipTools manifest`, { diagnostic: 'manifest missing or malformed' });
-    }
-    const id = report.manifest?.id ?? packageName;
-    if (failedSection === 'compatibility') {
-        if (report.compatibilityDecision === 'fail-closed') {
-            throw new PluginIncompatibleError(`bundled tool '${id}' is incompatible: ${failed?.diagnostic ?? 'compatibility gate rejected it'}`, { diagnostic: failed?.diagnostic });
-        }
-        if (report.compatibilityDecision === 'skip') {
-            // Should not happen for an in-range bundled tool, but never silently
-            // drop a bundled tool — surface it loudly.
-            throw new PluginIncompatibleError(`bundled tool '${id}' was skipped by the compatibility gate: ${failed?.diagnostic ?? 'unknown reason'}`, { diagnostic: failed?.diagnostic });
-        }
-        throw new PluginIncompatibleError(`bundled tool '${id}' reached an unknown admission decision`, { diagnostic: 'unknown admission decision' });
-    }
-    if (failedSection === 'runtime-load' || failedSection === 'tool-shape') {
-        const reason = report.runtimeLoadReason ?? 'import-failed';
-        const detailSuffix = report.runtimeLoadDetail ? `: ${report.runtimeLoadDetail}` : '';
-        throw new PluginIncompatibleError(`bundled tool '${id}' failed to load via the plugin path (${reason}${detailSuffix})`, { diagnostic: `bundled tool runtime load failed: ${reason}` });
-    }
-    if (failedSection === 'manifest-runtime-coherence' && report.coherenceError instanceof Error) {
-        // Preserve the original drift-guard error type + message untouched.
-        // (assertManifestMatchesTool always throws Error subclasses; the
-        // instanceof narrowing satisfies only-throw-error without a cast.)
-        throw report.coherenceError;
-    }
-    /* v8 ignore next 4 -- defensive: a failed report always carries a failed section */
-    throw new PluginIncompatibleError(`bundled tool '${packageName}' failed admission for an unknown reason`, { diagnostic: 'unknown admission failure' });
-}
-/**
- * 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 };
-}
-/**
- * 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.
- */
-/**
- * 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,
-    });
-}
-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);
-}
-/**
- * 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) {
-        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, ctx);
-        }
-        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);
-}
+export { BUNDLED_TOOL_PACKAGES, EXPECTED_SCAFFOLDING_TOOL_IDS } from './register-tools-shared.js';
+export { registerFirstPartyTools } from './register-tools-bundled.js';
+export { buildToolDiscoverySources, discoverAndRegisterToolPackages, admitProjectLocalTool, admitUserGlobalTool, discoverAndRegisterAuthoredTools, } from './register-tools-discovery.js';
+export { mountAllToolCommands } from './register-tools-mount.js';
 //# sourceMappingURL=register-tools.js.map