opensip-cli 0.1.5 → 0.1.7

package/dist/bootstrap/register-tools.js

@@ -1,18 +1,189 @@
+// @fitness-ignore-file performance-anti-patterns -- sequential await across discovered tool packages preserves load order for plugin-conflict detection; bounded by installed plugin count
 /**
- * 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 { buildToolDiscoverySources, discoverAndRegisterToolPackages, discoverAndRegisterAuthoredTools, } from './register-tools-discovery.js';
-export { admitProjectLocalTool, admitUserGlobalTool, } from './authored-tool-admission.js';
-export { mountAllToolCommands } from './register-tools-mount.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { logger, PluginIncompatibleError, } from '@opensip-cli/core';
+import { admitToolPackage } from './admit-tool-package.js';
+import { BUNDLED_TOOL_PACKAGES } from './bundled-manifest.js';
+import { BOOTSTRAP_MODULE } from './constants.js';
+export { BUNDLED_CAPABILITY_PACKS, BUNDLED_TOOL_PACKAGES, EXPECTED_SCAFFOLDING_TOOL_IDS, } from './bundled-manifest.js';
+/** Used to resolve the bundled engine package dirs from the CLI's own module graph. */
+const requireFromHere = createRequire(import.meta.url);
+/**
+ * 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' });
+}
+// 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' });
+}
+export { admitProjectLocalTool, admitUserGlobalTool, buildToolDiscoverySources, discoverAndRegisterAuthoredTools, discoverAndRegisterToolPackages, emitInstalledLoadFailure, } from './register-tools-discovery.js';
+export { mountAllToolCommands, mountOneTool } from './register-tools-mount.js';
 //# sourceMappingURL=register-tools.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"register-tools.js","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,EAEL,yBAAyB,EACzB,+BAA+B,EAC/B,gCAAgC,GACjC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAEL,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"register-tools.js","sourceRoot":"","sources":["../../src/bootstrap/register-tools.ts"],"names":[],"mappings":"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"}

package/dist/bootstrap/root-version.d.ts

@@ -0,0 +1,26 @@
+/**
+ * root-version — host-owned detection of the bare `opensip --version` request.
+ *
+ * The root program deliberately carries NO Commander `.version()` option: a root
+ * version option is GLOBAL and would intercept `--version` even after a known
+ * subcommand, so `opensip fit --version` would print the CLI version instead of
+ * the tool's. The per-tool `--version` is a subcommand-local Commander version
+ * option (`decorateToolPrimary`); the bare CLI form is detected here, before
+ * Commander parses, so the two never collide.
+ *
+ * Kept in its own module (rather than inline in the composition root) so it is
+ * unit-testable without importing `index.ts` — whose top-level `await main()`
+ * side-effect would run the whole CLI on import.
+ */
+/**
+ * Is this argv a BARE `opensip --version` / `-V` (the CLI version), as opposed to
+ * a tool primary's own `opensip <tool> --version`?
+ *
+ * The bare form has `--version` / `-V` with NO subcommand (positional) token
+ * before it. A `--version` that follows a subcommand belongs to that subcommand
+ * and is left for Commander (and `decorateToolPrimary`).
+ *
+ * @param argv `process.argv.slice(2)` — the user-supplied args after the binary.
+ */
+export declare function isRootVersionRequest(argv: readonly string[]): boolean;
+//# sourceMappingURL=root-version.d.ts.map

package/dist/bootstrap/root-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-version.d.ts","sourceRoot":"","sources":["../../src/bootstrap/root-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAQrE"}

package/dist/bootstrap/root-version.js

@@ -0,0 +1,36 @@
+/**
+ * root-version — host-owned detection of the bare `opensip --version` request.
+ *
+ * The root program deliberately carries NO Commander `.version()` option: a root
+ * version option is GLOBAL and would intercept `--version` even after a known
+ * subcommand, so `opensip fit --version` would print the CLI version instead of
+ * the tool's. The per-tool `--version` is a subcommand-local Commander version
+ * option (`decorateToolPrimary`); the bare CLI form is detected here, before
+ * Commander parses, so the two never collide.
+ *
+ * Kept in its own module (rather than inline in the composition root) so it is
+ * unit-testable without importing `index.ts` — whose top-level `await main()`
+ * side-effect would run the whole CLI on import.
+ */
+/**
+ * Is this argv a BARE `opensip --version` / `-V` (the CLI version), as opposed to
+ * a tool primary's own `opensip <tool> --version`?
+ *
+ * The bare form has `--version` / `-V` with NO subcommand (positional) token
+ * before it. A `--version` that follows a subcommand belongs to that subcommand
+ * and is left for Commander (and `decorateToolPrimary`).
+ *
+ * @param argv `process.argv.slice(2)` — the user-supplied args after the binary.
+ */
+export function isRootVersionRequest(argv) {
+    for (const token of argv) {
+        if (token === '--version' || token === '-V')
+            return true;
+        // The first non-flag token is the subcommand verb — any `--version` after it
+        // is the subcommand's, not the root's.
+        if (!token.startsWith('-'))
+            return false;
+    }
+    return false;
+}
+//# sourceMappingURL=root-version.js.map

package/dist/bootstrap/root-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-version.js","sourceRoot":"","sources":["../../src/bootstrap/root-version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAuB;IAC1D,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACzD,6EAA6E;QAC7E,uCAAuC;QACvC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/bootstrap/scope-access.d.ts

@@ -65,4 +65,15 @@ export declare function getOrOpenDatastore(_log?: Logger): DataStore;
  *   datastore); other datastore-open failures propagate unchanged.
  */
 export declare function getProjectDatastore(): DataStore;
+/** How a datastore resolver should behave when scope or project context is absent. */
+export type DatastoreResolverMode = 'strict' | 'project-seam' | 'best-effort';
+/**
+ * Unified lazy datastore accessor for host planes and the run plane.
+ *
+ * - `strict` — throws when outside a project scope (via `getOrOpenDatastore`).
+ * - `project-seam` — maps outside-project to `ConfigurationError` for documented seams.
+ * - `best-effort` — returns `undefined` when scope or datastore is unavailable.
+ */
+export declare function createDatastoreResolver(mode: 'strict' | 'project-seam', logger?: Logger): () => DataStore;
+export declare function createDatastoreResolver(mode: 'best-effort', logger?: Logger): () => DataStore | undefined;
 //# sourceMappingURL=scope-access.d.ts.map

package/dist/bootstrap/scope-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-access.d.ts","sourceRoot":"","sources":["../../src/bootstrap/scope-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,QAAQ,EAKd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,QAAQ,CAWpC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAS9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,GAAG,GAAE,MAAsB,GAC1B,MAAM,SAAS,CAoBjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAsB,GAAG,SAAS,CAG1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAgB/C"}
+{"version":3,"file":"scope-access.d.ts","sourceRoot":"","sources":["../../src/bootstrap/scope-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,QAAQ,EAKd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,SAAS,IAAI,QAAQ,CAWpC;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAS9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,GAAG,GAAE,MAAsB,GAC1B,MAAM,SAAS,CAoBjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,MAAsB,GAAG,SAAS,CAG1E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAgB/C;AAED,sFAAsF;AACtF,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,CAAC;AAE9E;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,QAAQ,GAAG,cAAc,EAC/B,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,SAAS,CAAC;AACnB,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,aAAa,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,SAAS,GAAG,SAAS,CAAC"}

package/dist/bootstrap/scope-access.js

@@ -112,4 +112,30 @@ export function getProjectDatastore() {
         throw error;
     }
 }
+export function createDatastoreResolver(mode, logger = defaultLogger) {
+    switch (mode) {
+        case 'strict': {
+            return () => getOrOpenDatastore(logger);
+        }
+        case 'project-seam': {
+            return () => getProjectDatastore();
+        }
+        case 'best-effort': {
+            return () => {
+                try {
+                    const thunk = readScope().datastore;
+                    return thunk ? thunk() : undefined;
+                }
+                catch (error) {
+                    logger.debug({
+                        evt: 'cli.context.datastore_unavailable',
+                        module: 'cli:context',
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return;
+                }
+            };
+        }
+    }
+}
 //# sourceMappingURL=scope-access.js.map

package/dist/bootstrap/scope-access.js.map

@@ -1 +1 @@
-{"version":3,"file":"scope-access.js","sourceRoot":"","sources":["../../src/bootstrap/scope-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,kBAAkB,EAIlB,WAAW,EACX,YAAY,EACZ,MAAM,IAAI,aAAa,EACvB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,gBAAgB,EAAkB,MAAM,wBAAwB,CAAC;AAE1E;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS;IACvB,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;IAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,WAAW,CACnB,2FAA2F;YACzF,yFAAyF;YACzF,2FAA2F,EAC7F,EAAE,IAAI,EAAE,0BAA0B,EAAE,CACrC,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAG,SAAS,EAAE,CAAC,cAAc,CAAC;IAC3C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,WAAW,CACnB,6EAA6E,EAC7E,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAC3C,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAuB,EACvB,MAAc,aAAa;IAE3B,IAAI,MAA6B,CAAC;IAClC,OAAO,GAAG,EAAE;QACV,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,IAAI,WAAW,CACnB,2EAA2E;gBACzE,2EAA2E,EAC7E,EAAE,IAAI,EAAE,4CAA4C,EAAE,CACvD,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,mBAAmB,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,UAAU,mBAAmB,CAAC;QACvF,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,GAAG,CAAC,IAAI,CAAC;YACP,GAAG,EAAE,sBAAsB;YAC3B,MAAM,EAAE,aAAa;YACrB,IAAI;SACL,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,aAAa;IAC7D,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC,SAAS,CAAC;IACpC,OAAO,KAAK,EAAe,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB;IACjC,IAAI,CAAC;QACH,OAAO,kBAAkB,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IACE,KAAK,YAAY,WAAW;YAC5B,KAAK,CAAC,IAAI,KAAK,4CAA4C,EAC3D,CAAC;YACD,MAAM,IAAI,kBAAkB,CAC1B,+GAA+G;gBAC7G,+EAA+E,EACjF,EAAE,IAAI,EAAE,gCAAgC,EAAE,CAC3C,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"scope-access.js","sourceRoot":"","sources":["../../src/bootstrap/scope-access.ts"],"names":[],"mappings":"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"}

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

@@ -48,8 +48,6 @@
  * one ordered entry point. The driver is intentionally THIN: it sequences the
  * pre-existing helpers, it does not reimplement them.
  */
-import type { CliProgram } from '@opensip-cli/contracts';
-import type { ToolCliContext, ToolRegistry } from '@opensip-cli/core';
 /**
  * Canonical, ordered tool-lifecycle steps (launch, §5.4). The numeric
  * values are the step ordinals used in the JSDoc above and in
@@ -79,24 +77,4 @@ export declare const TOOL_LIFECYCLE_STEPS: {
     /** 10 — Commander dispatches the action body through the mount pipeline. */
     readonly dispatch: 10;
 };
-/**
- * Drive the STARTUP-phase command-mount step (step 8) for every registered
- * tool. By the time this runs, steps 1-4 have already populated `registry`
- * inside {@link bootstrapCli} (provenance no longer matters — bundled and
- * installed tools mount identically). This is the single ordered entry point
- * the composition root calls for step 8, replacing the bare
- * `mountAllToolCommands(...)` call so the lifecycle has one named seam.
- *
- * Kept THIN deliberately: it delegates straight to
- * {@link mountAllToolCommands}, which mounts each tool's declared `commandSpecs`
- * (the one command surface, launch) with per-tool failure isolation. The naming +
- * ordering is the value here, not new logic.
- *
- * @param registry The per-invocation tool registry, already populated by
- *   steps 1-4.
- * @param program The root Commander program (host-owned; passed in since the tool
- *   context no longer carries it, §8).
- * @param ctx The per-invocation handler context handed to each mounted command.
- */
-export declare function mountToolCommands(registry: ToolRegistry, program: CliProgram, ctx: ToolCliContext): void;
 //# sourceMappingURL=tool-lifecycle.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-lifecycle.d.ts","sourceRoot":"","sources":["../../src/bootstrap/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B,oDAAoD;;IAEpD,mEAAmE;;IAEnE,0EAA0E;;IAE1E,uEAAuE;;IAEvE,+DAA+D;;IAE/D,sDAAsD;;IAEtD,gFAAgF;;IAEhF,mDAAmD;;IAEnD,0EAA0E;;IAE1E,4EAA4E;;CAEpE,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,UAAU,EACnB,GAAG,EAAE,cAAc,GAClB,IAAI,CAEN"}
+{"version":3,"file":"tool-lifecycle.d.ts","sourceRoot":"","sources":["../../src/bootstrap/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB;IAC/B,oDAAoD;;IAEpD,mEAAmE;;IAEnE,0EAA0E;;IAE1E,uEAAuE;;IAEvE,+DAA+D;;IAE/D,sDAAsD;;IAEtD,gFAAgF;;IAEhF,mDAAmD;;IAEnD,0EAA0E;;IAE1E,4EAA4E;;CAEpE,CAAC"}

package/dist/bootstrap/tool-lifecycle.js

@@ -48,7 +48,6 @@
  * one ordered entry point. The driver is intentionally THIN: it sequences the
  * pre-existing helpers, it does not reimplement them.
  */
-import { mountAllToolCommands } from './register-tools.js';
 /**
  * Canonical, ordered tool-lifecycle steps (launch, §5.4). The numeric
  * values are the step ordinals used in the JSDoc above and in
@@ -78,26 +77,4 @@ export const TOOL_LIFECYCLE_STEPS = {
     /** 10 — Commander dispatches the action body through the mount pipeline. */
     dispatch: 10,
 };
-/**
- * Drive the STARTUP-phase command-mount step (step 8) for every registered
- * tool. By the time this runs, steps 1-4 have already populated `registry`
- * inside {@link bootstrapCli} (provenance no longer matters — bundled and
- * installed tools mount identically). This is the single ordered entry point
- * the composition root calls for step 8, replacing the bare
- * `mountAllToolCommands(...)` call so the lifecycle has one named seam.
- *
- * Kept THIN deliberately: it delegates straight to
- * {@link mountAllToolCommands}, which mounts each tool's declared `commandSpecs`
- * (the one command surface, launch) with per-tool failure isolation. The naming +
- * ordering is the value here, not new logic.
- *
- * @param registry The per-invocation tool registry, already populated by
- *   steps 1-4.
- * @param program The root Commander program (host-owned; passed in since the tool
- *   context no longer carries it, §8).
- * @param ctx The per-invocation handler context handed to each mounted command.
- */
-export function mountToolCommands(registry, program, ctx) {
-    mountAllToolCommands(registry, program, ctx);
-}
 //# sourceMappingURL=tool-lifecycle.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"tool-lifecycle.js","sourceRoot":"","sources":["../../src/bootstrap/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAK3D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oDAAoD;IACpD,QAAQ,EAAE,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,CAAC;IACT,0EAA0E;IAC1E,KAAK,EAAE,CAAC;IACR,uEAAuE;IACvE,MAAM,EAAE,CAAC;IACT,+DAA+D;IAC/D,MAAM,EAAE,CAAC;IACT,sDAAsD;IACtD,KAAK,EAAE,CAAC;IACR,gFAAgF;IAChF,YAAY,EAAE,CAAC;IACf,mDAAmD;IACnD,KAAK,EAAE,CAAC;IACR,0EAA0E;IAC1E,UAAU,EAAE,CAAC;IACb,4EAA4E;IAC5E,QAAQ,EAAE,EAAE;CACJ,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAsB,EACtB,OAAmB,EACnB,GAAmB;IAEnB,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"tool-lifecycle.js","sourceRoot":"","sources":["../../src/bootstrap/tool-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,oDAAoD;IACpD,QAAQ,EAAE,CAAC;IACX,mEAAmE;IACnE,MAAM,EAAE,CAAC;IACT,0EAA0E;IAC1E,KAAK,EAAE,CAAC;IACR,uEAAuE;IACvE,MAAM,EAAE,CAAC;IACT,+DAA+D;IAC/D,MAAM,EAAE,CAAC;IACT,sDAAsD;IACtD,KAAK,EAAE,CAAC;IACR,gFAAgF;IAChF,YAAY,EAAE,CAAC;IACf,mDAAmD;IACnD,KAAK,EAAE,CAAC;IACR,0EAA0E;IAC1E,UAAU,EAAE,CAAC;IACb,4EAA4E;IAC5E,QAAQ,EAAE,EAAE;CACJ,CAAC"}

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

@@ -4,11 +4,12 @@
  * an arbitrary npm package and inspects whatever it exports.
  *
  * Verifies the minimal contract the registry depends on: a
- * `metadata.id` string (used for dedupe + listing), a `commands` array,
- * and a command surface — a non-empty `commandSpecs` array (the one command
+ * `metadata.id` string (used for dedupe + listing), and a command surface —
+ * a non-empty `commandSpecs` array (the one command
  * surface as of launch; `register()` was removed). A tool with no `commandSpecs`
- * cannot mount any command, so it fails the shape check. `initialize` and
- * `contributeScope` stay optional per the Tool interface.
+ * cannot mount any command, so it fails the shape check. Lifecycle hooks belong
+ * under `extensionPoints` only — top-level hooks are rejected with an actionable
+ * diagnostic.
  *
  * Ordering vs. the admission gate: this shape check runs AFTER a
  * tool's module is imported. The compatibility gate (`admitTool`) and the
@@ -18,5 +19,10 @@
  * and never reaches `isValidTool`.
  */
 import { type Tool } from '@opensip-cli/core';
+/**
+ * Human-readable rejection reason for an exported `tool` value.
+ * `undefined` means the export satisfies {@link isValidTool}.
+ */
+export declare function toolValidationFailure(value: unknown): string | undefined;
 export declare function isValidTool(value: unknown): value is Tool;
 //# sourceMappingURL=validate-tool.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate-tool.d.ts","sourceRoot":"","sources":["../../src/bootstrap/validate-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAuB,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEnE,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAkBzD"}
+{"version":3,"file":"validate-tool.d.ts","sourceRoot":"","sources":["../../src/bootstrap/validate-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAuB,KAAK,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAuDnE;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAqBxE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,IAAI,CAEzD"}

package/dist/bootstrap/validate-tool.js

@@ -4,11 +4,12 @@
  * an arbitrary npm package and inspects whatever it exports.
  *
  * Verifies the minimal contract the registry depends on: a
- * `metadata.id` string (used for dedupe + listing), a `commands` array,
- * and a command surface — a non-empty `commandSpecs` array (the one command
+ * `metadata.id` string (used for dedupe + listing), and a command surface —
+ * a non-empty `commandSpecs` array (the one command
  * surface as of launch; `register()` was removed). A tool with no `commandSpecs`
- * cannot mount any command, so it fails the shape check. `initialize` and
- * `contributeScope` stay optional per the Tool interface.
+ * cannot mount any command, so it fails the shape check. Lifecycle hooks belong
+ * under `extensionPoints` only — top-level hooks are rejected with an actionable
+ * diagnostic.
  *
  * Ordering vs. the admission gate: this shape check runs AFTER a
  * tool's module is imported. The compatibility gate (`admitTool`) and the
@@ -18,25 +19,78 @@
  * and never reaches `isValidTool`.
  */
 import { validateCommandSpec } from '@opensip-cli/core';
-export function isValidTool(value) {
-    if (typeof value !== 'object' || value === null)
-        return false;
+/** Top-level hook keys removed in the tool-author-simplify contract. */
+const LEGACY_TOP_LEVEL_HOOK_KEYS = [
+    'initialize',
+    'contributeScope',
+    'collectReportData',
+    'sessionReplay',
+    'config',
+    'capabilityRegistrars',
+    'fingerprintStrategy',
+    'scaffoldExamples',
+    'stableExampleIds',
+    'scaffoldConfigBlock',
+];
+function legacyTopLevelHookKeys(candidate) {
+    return LEGACY_TOP_LEVEL_HOOK_KEYS.filter((key) => candidate[key] !== undefined);
+}
+function metadataValidationFailure(metadata) {
+    if (typeof metadata !== 'object' || metadata === null) {
+        return 'tool.metadata is missing or not an object';
+    }
+    if (typeof metadata.id !== 'string') {
+        return 'tool.metadata.id must be a string';
+    }
+    return undefined;
+}
+function commandSpecsValidationFailure(commandSpecs) {
+    if (!Array.isArray(commandSpecs) || commandSpecs.length === 0) {
+        return 'tool.commandSpecs must be a non-empty array (the declarative command surface)';
+    }
+    for (const spec of commandSpecs) {
+        if (!validateCommandSpec(spec)) {
+            return 'tool.commandSpecs contains an invalid CommandSpec';
+        }
+    }
+    return undefined;
+}
+function optionalCommandsValidationFailure(commands) {
+    if (!Array.isArray(commands))
+        return undefined;
+    for (const cmd of commands) {
+        if (typeof cmd !== 'object' || cmd === null) {
+            return 'tool.commands contains a non-object entry';
+        }
+        if (typeof cmd.name !== 'string') {
+            return 'tool.commands entries must include a string name';
+        }
+    }
+    return undefined;
+}
+/**
+ * Human-readable rejection reason for an exported `tool` value.
+ * `undefined` means the export satisfies {@link isValidTool}.
+ */
+export function toolValidationFailure(value) {
+    if (typeof value !== 'object' || value === null) {
+        return 'tool export is not an object';
+    }
     const candidate = value;
-    if (typeof candidate.metadata !== 'object' || candidate.metadata === null)
-        return false;
-    if (typeof candidate.metadata.id !== 'string')
-        return false;
-    if (!Array.isArray(candidate.commands))
-        return false;
-    // A tool must expose a command surface: a non-empty declarative `commandSpecs`
-    // array (the one command surface, launch — `register()` was removed). A tool
-    // with no commandSpecs cannot contribute any command and is rejected.
-    if (!Array.isArray(candidate.commandSpecs) || candidate.commandSpecs.length === 0)
-        return false;
-    for (const spec of candidate.commandSpecs) {
-        if (!validateCommandSpec(spec))
-            return false;
+    const metadataFailure = metadataValidationFailure(candidate.metadata);
+    if (metadataFailure !== undefined)
+        return metadataFailure;
+    const legacy = legacyTopLevelHookKeys(candidate);
+    if (legacy.length > 0) {
+        return (`tool declares deprecated top-level hooks [${legacy.join(', ')}]; ` +
+            'move them under extensionPoints (see opensip tool authoring docs)');
     }
-    return true;
+    const specsFailure = commandSpecsValidationFailure(candidate.commandSpecs);
+    if (specsFailure !== undefined)
+        return specsFailure;
+    return optionalCommandsValidationFailure(candidate.commands);
+}
+export function isValidTool(value) {
+    return toolValidationFailure(value) === undefined;
 }
 //# sourceMappingURL=validate-tool.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"validate-tool.js","sourceRoot":"","sources":["../../src/bootstrap/validate-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,mBAAmB,EAAa,MAAM,mBAAmB,CAAC;AAEnE,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,SAAS,GAAG,KAIjB,CAAC;IACF,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,QAAQ,IAAI,SAAS,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IACxF,IAAI,OAAQ,SAAS,CAAC,QAA6B,CAAC,EAAE,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,+EAA+E;IAC/E,6EAA6E;IAC7E,sEAAsE;IACtE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAChG,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;QAC1C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"validate-tool.js","sourceRoot":"","sources":["../../src/bootstrap/validate-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,mBAAmB,EAAa,MAAM,mBAAmB,CAAC;AAEnE,wEAAwE;AACxE,MAAM,0BAA0B,GAAG;IACjC,YAAY;IACZ,iBAAiB;IACjB,mBAAmB;IACnB,eAAe;IACf,QAAQ;IACR,sBAAsB;IACtB,qBAAqB;IACrB,kBAAkB;IAClB,kBAAkB;IAClB,qBAAqB;CACb,CAAC;AAEX,SAAS,sBAAsB,CAAC,SAAkC;IAChE,OAAO,0BAA0B,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;AAClF,CAAC;AAED,SAAS,yBAAyB,CAAC,QAAiB;IAClD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtD,OAAO,2CAA2C,CAAC;IACrD,CAAC;IACD,IAAI,OAAQ,QAA6B,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;QAC1D,OAAO,mCAAmC,CAAC;IAC7C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,6BAA6B,CAAC,YAAqB;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,YAAY,CAAC,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9D,OAAO,+EAA+E,CAAC;IACzF,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,OAAO,mDAAmD,CAAC;QAC7D,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,iCAAiC,CAAC,QAAiB;IAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;QAAE,OAAO,SAAS,CAAC;IAC/C,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;YAC5C,OAAO,2CAA2C,CAAC;QACrD,CAAC;QACD,IAAI,OAAQ,GAA0B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACzD,OAAO,kDAAkD,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,8BAA8B,CAAC;IACxC,CAAC;IACD,MAAM,SAAS,GAAG,KAAgC,CAAC;IAEnD,MAAM,eAAe,GAAG,yBAAyB,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACtE,IAAI,eAAe,KAAK,SAAS;QAAE,OAAO,eAAe,CAAC;IAE1D,MAAM,MAAM,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,CACL,6CAA6C,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YACnE,mEAAmE,CACpE,CAAC;IACJ,CAAC;IAED,MAAM,YAAY,GAAG,6BAA6B,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC3E,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,YAAY,CAAC;IAEpD,OAAO,iCAAiC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,qBAAqB,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;AACpD,CAAC"}

package/dist/cli-context.d.ts

@@ -17,10 +17,10 @@
  * `.runtime/datastore.sqlite`.
  */
 import { type Logger, type ToolCliContext } from '@opensip-cli/core';
-import { type LiveViewRegistry } from './bootstrap/live-plane.js';
+import { type LiveViewRegistry } from './bootstrap/io-plane.js';
 import type { CommandResult } from '@opensip-cli/contracts';
 export { buildDatastoreThunk, getCurrentProjectRoot, getOrOpenDatastore, } from './bootstrap/scope-access.js';
-export { createLiveViewRegistry, type LiveViewRegistry } from './bootstrap/live-plane.js';
+export { createLiveViewRegistry, type LiveViewRegistry } from './bootstrap/io-plane.js';
 export interface BuildToolCliContextOptions {
     readonly render: (result: CommandResult) => Promise<void>;
     readonly liveViews: LiveViewRegistry;

package/dist/cli-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../src/cli-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAM3B,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAWnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAsB5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAE1F,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE;QAC/B,aAAa,EAAE,OAAO,CAAC;QACvB,UAAU,EAAE,OAAO,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,oBAAoB,CA2F1F"}
+{"version":3,"file":"cli-context.d.ts","sourceRoot":"","sources":["../src/cli-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,MAAM,EACX,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAI3B,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAW/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAmB5D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAExF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,CAAC,IAAI,EAAE;QAC/B,aAAa,EAAE,OAAO,CAAC;QACvB,UAAU,EAAE,OAAO,CAAC;KACrB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,MAAM,GAAG,SAAS,CAAC;CAChD;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,0BAA0B,GAAG,oBAAoB,CAgF1F"}