@opensip-cli/core 0.1.0

package/dist/plugins/scope-validation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Shared npm-scope validation + resolution for scoped plugin
+ * auto-discovery (scenario packs, future package families).
+ *
+ * Discovery code maps a scope string to `node_modules/<scope>/` and
+ * scans for packages. Untrusted scope strings reach `path.join`, so we
+ * enforce strict npm-scope syntax before they're used as path
+ * segments. A stray `..` or `/` would otherwise scan the wrong
+ * directory.
+ *
+ * Hoisted into core so every scoped discovery surface enforces the
+ * same invariant. The `@opensip-cli/scenarios-*` discovery in sim
+ * flows through this helper.
+ */
+/**
+ * npm scope syntax: `@` followed by a kebab-case identifier. We anchor
+ * strictly because scope strings end up in `path.join('node_modules', scope)`
+ * — a stray `..` or `/` would scan the wrong directory.
+ */
+export declare const VALID_NPM_SCOPE_REGEX: RegExp;
+/**
+ * Resolve the effective list of npm scopes to scan: the platform
+ * default is always included; customer additions are appended after
+ * deduplication and format validation. Invalid scope strings are
+ * dropped with a structured warning rather than throwing — consistent
+ * with how discovery handles unresolved explicit packages elsewhere.
+ *
+ * @param defaultScope  The platform default (e.g. `@opensip-cli`)
+ * @param extraScopes   Customer-configured additions
+ * @param evt           Log event name to use when warning about invalid
+ *                       entries — lets each caller emit a domain-specific
+ *                       event name (`plugin.scenario_package.invalid_scope`).
+ */
+export declare function resolveScopes(defaultScope: string, extraScopes: readonly string[], evt: string): readonly string[];
+//# sourceMappingURL=scope-validation.d.ts.map

package/dist/plugins/scope-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-validation.d.ts","sourceRoot":"","sources":["../../src/plugins/scope-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAA4B,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,GAAG,EAAE,MAAM,GACV,SAAS,MAAM,EAAE,CAkBnB"}

package/dist/plugins/scope-validation.js

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Shared npm-scope validation + resolution for scoped plugin
+ * auto-discovery (scenario packs, future package families).
+ *
+ * Discovery code maps a scope string to `node_modules/<scope>/` and
+ * scans for packages. Untrusted scope strings reach `path.join`, so we
+ * enforce strict npm-scope syntax before they're used as path
+ * segments. A stray `..` or `/` would otherwise scan the wrong
+ * directory.
+ *
+ * Hoisted into core so every scoped discovery surface enforces the
+ * same invariant. The `@opensip-cli/scenarios-*` discovery in sim
+ * flows through this helper.
+ */
+import { logger } from '../lib/logger.js';
+/**
+ * npm scope syntax: `@` followed by a kebab-case identifier. We anchor
+ * strictly because scope strings end up in `path.join('node_modules', scope)`
+ * — a stray `..` or `/` would scan the wrong directory.
+ */
+export const VALID_NPM_SCOPE_REGEX = /^@[a-z0-9][a-z0-9._-]*$/;
+/**
+ * Resolve the effective list of npm scopes to scan: the platform
+ * default is always included; customer additions are appended after
+ * deduplication and format validation. Invalid scope strings are
+ * dropped with a structured warning rather than throwing — consistent
+ * with how discovery handles unresolved explicit packages elsewhere.
+ *
+ * @param defaultScope  The platform default (e.g. `@opensip-cli`)
+ * @param extraScopes   Customer-configured additions
+ * @param evt           Log event name to use when warning about invalid
+ *                       entries — lets each caller emit a domain-specific
+ *                       event name (`plugin.scenario_package.invalid_scope`).
+ */
+export function resolveScopes(defaultScope, extraScopes, evt) {
+    const out = [defaultScope];
+    const seen = new Set(out);
+    for (const scope of extraScopes) {
+        if (!VALID_NPM_SCOPE_REGEX.test(scope)) {
+            logger.warn({
+                evt,
+                module: 'core:plugins',
+                scope,
+                msg: `plugins.packageScopes entry "${scope}" is not a valid npm scope (expected "@kebab-case") — skipping`,
+            });
+            continue;
+        }
+        if (seen.has(scope))
+            continue;
+        seen.add(scope);
+        out.push(scope);
+    }
+    return out;
+}
+//# sourceMappingURL=scope-validation.js.map

package/dist/plugins/scope-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-validation.js","sourceRoot":"","sources":["../../src/plugins/scope-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAE1C;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAC3B,YAAoB,EACpB,WAA8B,EAC9B,GAAW;IAEX,MAAM,GAAG,GAAa,CAAC,YAAY,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,GAAG,CAAC,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,IAAI,CAAC;gBACV,GAAG;gBACH,MAAM,EAAE,cAAc;gBACtB,KAAK;gBACL,GAAG,EAAE,gCAAgC,KAAK,gEAAgE;aAC3G,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,SAAS;QAC9B,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAChB,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/plugins/single-core-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Single-`@opensip-cli/core` guard for discovered packages.
+ *
+ * A capability pack (check pack, scenario pack, graph adapter) that resolves a
+ * DIFFERENT physical `@opensip-cli/core` than the running engine registers its
+ * contributions against a core whose `currentScope()` is always `undefined` here
+ * (a different `AsyncLocalStorage`). That silently degrades the run — the failure
+ * mode seen when a globally-installed CLI discovers packs in a project that
+ * vendors its own `@opensip-cli/*`. Such packs are refused at discovery time.
+ *
+ * Packs that don't depend on core at all resolve nothing and pass. The guard is
+ * tool-agnostic: the generic discovery substrate applies it to EVERY domain's
+ * packs, so the policy lives here once instead of in each tool's loader.
+ */
+/** The canonical `@opensip-cli/core` path this runtime resolves (for diagnostics). */
+export declare function selfCore(): string | undefined;
+/** The pack's resolved `@opensip-cli/core` if it differs from {@link selfCore}; else undefined. */
+export declare function foreignCorePath(packageDir: string): string | undefined;
+/**
+ * Keep only the packages that resolve THIS runtime's `@opensip-cli/core`
+ * (or none at all). `onForeign` is invoked for each dropped pack with the foreign
+ * core path it resolved, for a caller-shaped diagnostic.
+ */
+export declare function filterSameCorePackages<T extends {
+    readonly name: string;
+    readonly packageDir: string;
+}>(packages: readonly T[], onForeign?: (pkg: T, foreignCore: string) => void): T[];
+//# sourceMappingURL=single-core-guard.d.ts.map

package/dist/plugins/single-core-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-core-guard.d.ts","sourceRoot":"","sources":["../../src/plugins/single-core-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAqBH,sFAAsF;AACtF,wBAAgB,QAAQ,IAAI,MAAM,GAAG,SAAS,CAE7C;AAED,mGAAmG;AACnG,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYtE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAChE,QAAQ,EAAE,SAAS,CAAC,EAAE,EAAE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,GAAG,CAAC,EAAE,CAQhF"}

package/dist/plugins/single-core-guard.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Single-`@opensip-cli/core` guard for discovered packages.
+ *
+ * A capability pack (check pack, scenario pack, graph adapter) that resolves a
+ * DIFFERENT physical `@opensip-cli/core` than the running engine registers its
+ * contributions against a core whose `currentScope()` is always `undefined` here
+ * (a different `AsyncLocalStorage`). That silently degrades the run — the failure
+ * mode seen when a globally-installed CLI discovers packs in a project that
+ * vendors its own `@opensip-cli/*`. Such packs are refused at discovery time.
+ *
+ * Packs that don't depend on core at all resolve nothing and pass. The guard is
+ * tool-agnostic: the generic discovery substrate applies it to EVERY domain's
+ * packs, so the policy lives here once instead of in each tool's loader.
+ */
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * The `@opensip-cli/core` THIS module resolves — the canonical core whose
+ * `runWithScope` populates `currentScope()`. Captured once. `undefined` disables
+ * the guard (fail-open; defensive only — core always resolves from itself).
+ */
+const selfCorePath = (() => {
+    try {
+        return createRequire(import.meta.url).resolve('@opensip-cli/core');
+    }
+    catch {
+        /* v8 ignore next 2 -- core resolves from itself; defensive only */
+        // @fitness-ignore-next-line error-handling-quality -- an unresolvable self-core disables the guard (fail-open), not an error.
+        return;
+    }
+})();
+/** The canonical `@opensip-cli/core` path this runtime resolves (for diagnostics). */
+export function selfCore() {
+    return selfCorePath;
+}
+/** The pack's resolved `@opensip-cli/core` if it differs from {@link selfCore}; else undefined. */
+export function foreignCorePath(packageDir) {
+    if (selfCorePath === undefined)
+        return undefined;
+    try {
+        // The anchor file need not exist — createRequire only uses its directory as
+        // the resolution base, walking up node_modules from the pack.
+        const anchor = pathToFileURL(join(packageDir, 'noop.js')).href;
+        const packCore = createRequire(anchor).resolve('@opensip-cli/core');
+        return packCore === selfCorePath ? undefined : packCore;
+    }
+    catch {
+        // @fitness-ignore-next-line error-handling-quality -- resolution probe: a pack with no core dep throws here, and "no foreign core → allow" is the contract.
+        return undefined;
+    }
+}
+/**
+ * Keep only the packages that resolve THIS runtime's `@opensip-cli/core`
+ * (or none at all). `onForeign` is invoked for each dropped pack with the foreign
+ * core path it resolved, for a caller-shaped diagnostic.
+ */
+export function filterSameCorePackages(packages, onForeign) {
+    if (selfCorePath === undefined)
+        return [...packages];
+    return packages.filter((pkg) => {
+        const foreign = foreignCorePath(pkg.packageDir);
+        if (foreign === undefined)
+            return true;
+        onForeign?.(pkg, foreign);
+        return false;
+    });
+}
+//# sourceMappingURL=single-core-guard.js.map

package/dist/plugins/single-core-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-core-guard.js","sourceRoot":"","sources":["../../src/plugins/single-core-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;GAIG;AACH,MAAM,YAAY,GAAuB,CAAC,GAAG,EAAE;IAC7C,IAAI,CAAC;QACH,OAAO,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrE,CAAC;IAAC,MAAM,CAAC;QACP,mEAAmE;QACnE,8HAA8H;QAC9H,OAAO;IACT,CAAC;AACH,CAAC,CAAC,EAAE,CAAC;AAEL,sFAAsF;AACtF,MAAM,UAAU,QAAQ;IACtB,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACjD,IAAI,CAAC;QACH,4EAA4E;QAC5E,8DAA8D;QAC9D,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC;QAC/D,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACpE,OAAO,QAAQ,KAAK,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,4JAA4J;QAC5J,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAEpC,QAAsB,EAAE,SAAiD;IACzE,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAG,eAAe,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAChD,IAAI,OAAO,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QACvC,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/plugins/tool-package-discovery.d.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Thin domain-typed wrapper around the generic marker
+ * walker for `kind: "tool"`.
+ *
+ * A Tool plugin is any npm package (scoped or unscoped, first- or third-
+ * party) whose `package.json` declares:
+ *
+ *   { "opensipTools": { "kind": "tool" } }
+ *
+ * The walker itself lives in `marker-discovery.ts` — this file preserves
+ * the public surface (`discoverToolPackages`, `DiscoveredToolPackage`)
+ * existing CLI consumers depend on, and delegates the actual node_modules
+ * traversal to the shared primitive.
+ *
+ * Direct dependencies of opensip-cli are always loaded by the
+ * CLI's own import statements; this discovery exists so a user can
+ * install a third-party tool via `npm install` and have it picked up
+ * with no further wiring.
+ */
+export interface ToolPackageDiscoveryOptions {
+    /** Absolute path to the project root. */
+    readonly projectDir: string;
+}
+export interface DiscoveredToolPackage {
+    /** npm package name, e.g. '@opensip-cli/fitness' or '@my-co/audit'. */
+    readonly name: string;
+    /** Absolute path to the package's directory inside node_modules. */
+    readonly packageDir: string;
+}
+/**
+ * Walk up from `projectDir` looking for `node_modules/` directories
+ * containing packages with `opensipTools.kind === 'tool'`. Returns the
+ * deduplicated list (first-occurrence-wins by package name).
+ */
+export declare function discoverToolPackages(options: ToolPackageDiscoveryOptions): DiscoveredToolPackage[];
+/**
+ * One discovery source for {@link discoverToolPackagesFromAnchors}.
+ *
+ *  - `walkUp`: walk ancestor `node_modules` from `dir` (project trees, the
+ *    CLI install dir — covers a plain `npm install @tool` and global CLI
+ *    siblings).
+ *  - `scanDir`: scan exactly `<dir>/node_modules`, no walk (the fixed
+ *    plugin host dirs — `~/.opensip-cli/plugins/tool`,
+ *    `<project>/.runtime/plugins/tool`).
+ */
+export interface ToolDiscoverySource {
+    readonly dir: string;
+    readonly mode: 'walkUp' | 'scanDir';
+}
+/**
+ * Discover tool packages across an ORDERED list of sources, deduplicated
+ * by package name with first-occurrence-wins. Order encodes precedence:
+ * an earlier source's package shadows a later same-named one (e.g. a
+ * project-local pin shadows a user-global install). Mirrors the
+ * ToolRegistry's own first-writer-wins on duplicate ids.
+ *
+ * **Provenance contract.** Every anchor yields `source: 'installed'`
+ * provenance regardless of which anchor it came from — the anchor distinction
+ * encodes PRECEDENCE/SHADOWING, NOT source. So the caller
+ * (`admitInstalledTool` in `register-tools.ts`) assigns `source: 'installed'`
+ * UNIFORMLY; a per-anchor source tag here would add no information and is
+ * deliberately NOT threaded. *Authored* provenance (`project-local` /
+ * `user-global`) comes from the separate `discoverAuthoredToolSidecars` walk,
+ * keyed by its calling root — not from this npm-anchor walk.
+ *
+ * Scope flag: if a future release adds a third installed sub-source that needs
+ * distinct provenance, revisit whether the anchors walk should carry a source
+ * enum. Out of scope today.
+ */
+export declare function discoverToolPackagesFromAnchors(sources: readonly ToolDiscoverySource[]): DiscoveredToolPackage[];
+/**
+ * Read `name` and the resolved main entry of a discovered tool package.
+ * Mirrors readCheckPackageMetadata in shape but is exposed at the kernel
+ * level so any consumer (CLI, tests, future tooling) can resolve a tool
+ * package without depending on fitness.
+ */
+export interface ToolPackageMetadata {
+    readonly name: string;
+    readonly mainEntry: string;
+}
+/**
+ * Resolve a tool directory's runtime entry.
+ *
+ * An INSTALLED npm tool resolves via `package.json` (`exports['.']` → `main` →
+ * `./index.js`). An AUTHORED tool has no `package.json` — it declares identity
+ * via an `opensip-tool.manifest.json` sidecar, so when the package.json resolver
+ * finds nothing, fall back to the sidecar: its `main` field (or `./index.js`
+ * default), with the directory name as the package name. This keeps the two
+ * discovery surfaces symmetric — one entry resolver serves both the npm and
+ * authored legs.
+ */
+export declare function readToolPackageMetadata(packageDir: string): ToolPackageMetadata | undefined;
+//# sourceMappingURL=tool-package-discovery.d.ts.map

package/dist/plugins/tool-package-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-package-discovery.d.ts","sourceRoot":"","sources":["../../src/plugins/tool-package-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,MAAM,WAAW,2BAA2B;IAC1C,yCAAyC;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,qBAAqB;IACpC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,2BAA2B,GACnC,qBAAqB,EAAE,CAKzB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,SAAS,mBAAmB,EAAE,GACtC,qBAAqB,EAAE,CAezB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAI3F"}

package/dist/plugins/tool-package-discovery.js

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Thin domain-typed wrapper around the generic marker
+ * walker for `kind: "tool"`.
+ *
+ * A Tool plugin is any npm package (scoped or unscoped, first- or third-
+ * party) whose `package.json` declares:
+ *
+ *   { "opensipTools": { "kind": "tool" } }
+ *
+ * The walker itself lives in `marker-discovery.ts` — this file preserves
+ * the public surface (`discoverToolPackages`, `DiscoveredToolPackage`)
+ * existing CLI consumers depend on, and delegates the actual node_modules
+ * traversal to the shared primitive.
+ *
+ * Direct dependencies of opensip-cli are always loaded by the
+ * CLI's own import statements; this discovery exists so a user can
+ * install a third-party tool via `npm install` and have it picked up
+ * with no further wiring.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { isRecord } from './json-guards.js';
+import { PROJECT_LOCAL_MANIFEST_FILE } from './manifest-loader.js';
+import { discoverPackagesByMarker, discoverPackagesInNodeModules } from './marker-discovery.js';
+import { resolvePackageEntryPoint } from './package-entry.js';
+/**
+ * Walk up from `projectDir` looking for `node_modules/` directories
+ * containing packages with `opensipTools.kind === 'tool'`. Returns the
+ * deduplicated list (first-occurrence-wins by package name).
+ */
+export function discoverToolPackages(options) {
+    return discoverPackagesByMarker({ projectDir: options.projectDir, kind: 'tool' }).map((pkg) => ({
+        name: pkg.name,
+        packageDir: pkg.packageDir,
+    }));
+}
+/**
+ * Discover tool packages across an ORDERED list of sources, deduplicated
+ * by package name with first-occurrence-wins. Order encodes precedence:
+ * an earlier source's package shadows a later same-named one (e.g. a
+ * project-local pin shadows a user-global install). Mirrors the
+ * ToolRegistry's own first-writer-wins on duplicate ids.
+ *
+ * **Provenance contract.** Every anchor yields `source: 'installed'`
+ * provenance regardless of which anchor it came from — the anchor distinction
+ * encodes PRECEDENCE/SHADOWING, NOT source. So the caller
+ * (`admitInstalledTool` in `register-tools.ts`) assigns `source: 'installed'`
+ * UNIFORMLY; a per-anchor source tag here would add no information and is
+ * deliberately NOT threaded. *Authored* provenance (`project-local` /
+ * `user-global`) comes from the separate `discoverAuthoredToolSidecars` walk,
+ * keyed by its calling root — not from this npm-anchor walk.
+ *
+ * Scope flag: if a future release adds a third installed sub-source that needs
+ * distinct provenance, revisit whether the anchors walk should carry a source
+ * enum. Out of scope today.
+ */
+export function discoverToolPackagesFromAnchors(sources) {
+    const seen = new Set();
+    const out = [];
+    for (const src of sources) {
+        const found = src.mode === 'walkUp'
+            ? discoverPackagesByMarker({ projectDir: src.dir, kind: 'tool' })
+            : discoverPackagesInNodeModules(join(src.dir, 'node_modules'), 'tool');
+        for (const pkg of found) {
+            if (seen.has(pkg.name))
+                continue;
+            seen.add(pkg.name);
+            out.push({ name: pkg.name, packageDir: pkg.packageDir });
+        }
+    }
+    return out;
+}
+/**
+ * Resolve a tool directory's runtime entry.
+ *
+ * An INSTALLED npm tool resolves via `package.json` (`exports['.']` → `main` →
+ * `./index.js`). An AUTHORED tool has no `package.json` — it declares identity
+ * via an `opensip-tool.manifest.json` sidecar, so when the package.json resolver
+ * finds nothing, fall back to the sidecar: its `main` field (or `./index.js`
+ * default), with the directory name as the package name. This keeps the two
+ * discovery surfaces symmetric — one entry resolver serves both the npm and
+ * authored legs.
+ */
+export function readToolPackageMetadata(packageDir) {
+    const resolved = resolvePackageEntryPoint(packageDir);
+    if (resolved)
+        return { name: resolved.name, mainEntry: resolved.entry };
+    return readAuthoredSidecarEntry(packageDir);
+}
+/**
+ * Resolve an authored tool's entry from its `opensip-tool.manifest.json`
+ * sidecar. Reads the sidecar's `main` (default `./index.js`) and `name`/`id`
+ * for the package name. Returns `undefined` when the sidecar is absent or
+ * unreadable (the caller treats that as "no resolvable entry").
+ */
+function readAuthoredSidecarEntry(dir) {
+    const sidecarPath = join(dir, PROJECT_LOCAL_MANIFEST_FILE);
+    if (!existsSync(sidecarPath))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(sidecarPath, 'utf8'));
+    }
+    catch {
+        // @fitness-ignore-next-line error-handling-quality -- malformed sidecar surfaces via undefined return; caller treats as "no resolvable entry" (mirrors resolvePackageEntryPoint's package.json contract).
+        return undefined;
+    }
+    if (!isRecord(parsed))
+        return undefined;
+    const rawMain = typeof parsed.main === 'string' && parsed.main.length > 0 ? parsed.main : './index.js';
+    // Name from the sidecar's name/id, falling back to the directory name (always
+    // present for a real authored-tool dir).
+    const name = (typeof parsed.name === 'string' && parsed.name) ||
+        (typeof parsed.id === 'string' && parsed.id) ||
+        basename(dir);
+    return { name, mainEntry: join(dir, rawMain) };
+}
+//# sourceMappingURL=tool-package-discovery.js.map

package/dist/plugins/tool-package-discovery.js.map

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

package/dist/plugins/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Plugin contract types for opensip-cli
+ *
+ * Plugins can be npm packages or loose JS/MJS files.
+ *
+ * Tool-specific plugin export shapes (e.g. fitness's `FitPluginExports`,
+ * which references Check / FitnessRecipe types) live with the tool that
+ * owns them. This file holds the kernel-level types that any tool
+ * loader can use without dragging in tool-specific symbols.
+ */
+import type { LanguageAdapter } from '../languages/adapter.js';
+/** What a language plugin package/file exports */
+export interface LangPluginExports {
+    readonly adapters?: readonly LanguageAdapter[];
+}
+/**
+ * Union of all plugin export shapes — kept open so tool-specific exports
+ * (e.g. fitness's FitPluginExports) can be assigned through structural
+ * compatibility. Each tool owns its own export-shape interface.
+ */
+export type PluginExports = LangPluginExports | Record<string, unknown>;
+/**
+ * Where a tool's project-local plugins live. Supplied by the tool (via
+ * its `Tool.pluginLayout` descriptor) and threaded into `discoverPlugins`
+ * / `loadAllPlugins`. The kernel never enumerates tool domains itself —
+ * this descriptor is the seam that keeps core tool-agnostic
+ * (ADR-0009 corollary 1 / M2).
+ */
+export interface PluginLayout {
+    /**
+     * Path/domain segment. User loose-file plugins live under
+     * `<project>/opensip-cli/<domain>/<kind>/` and npm plugins under
+     * `<project>/opensip-cli/.runtime/plugins/<domain>/`. Also the key
+     * read from `opensip-cli.config.yml#plugins.<domain>`.
+     */
+    readonly domain: string;
+    /**
+     * User-source subdirectories walked for loose `.mjs`/`.js` plugins —
+     * e.g. `['checks', 'recipes']` for fitness, `['scenarios', 'recipes']`
+     * for simulation. Empty means no loose-file layout (npm plugins only).
+     */
+    readonly userSubdirs: readonly string[];
+}
+/** Discovered plugin before loading */
+export interface DiscoveredPlugin {
+    readonly type: 'package' | 'file';
+    /** Absolute path to the entry point */
+    readonly entryPoint: string;
+    /** Namespace derived from package name or filename */
+    readonly namespace: string;
+    /** Package name (for npm packages) or filename (for loose files) */
+    readonly source: string;
+}
+/**
+ * Result of loading a single plugin. `registered` is a generic count
+ * map keyed by whatever artifact kinds the tool's `registerExports`
+ * callback reports (e.g. `{ checks: 3, recipes: 1 }`, `{ scenarios: 2 }`,
+ * `{ adapters: 1 }`). The kernel carries no tool-specific counter names
+ * (ADR-0009 M2) — it only sums the map.
+ */
+export interface LoadedPlugin {
+    readonly namespace: string;
+    readonly source: string;
+    readonly type: 'package' | 'file';
+    /** Per-kind registration counts reported by the domain callback. */
+    readonly registered: Readonly<Record<string, number>>;
+    readonly error?: string;
+}
+/**
+ * Result of loading all plugins for a layout. `totals` is the
+ * per-kind sum across every loaded plugin's `registered` map.
+ */
+export interface PluginLoadResult {
+    readonly plugins: readonly LoadedPlugin[];
+    readonly totals: Readonly<Record<string, number>>;
+    readonly errors: readonly string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAM/D,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAMxE;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAClC,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAMD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC"}

package/dist/plugins/types.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Plugin contract types for opensip-cli
+ *
+ * Plugins can be npm packages or loose JS/MJS files.
+ *
+ * Tool-specific plugin export shapes (e.g. fitness's `FitPluginExports`,
+ * which references Check / FitnessRecipe types) live with the tool that
+ * owns them. This file holds the kernel-level types that any tool
+ * loader can use without dragging in tool-specific symbols.
+ */
+export {};
+// Note: there is deliberately NO `PluginDomain` type. A plugin domain is a
+// plain `string` segment (see `PluginLayout.domain`); the kernel does not
+// enumerate — nor even name — the first-party domains (ADR-0009 corollary 1).
+//# sourceMappingURL=types.js.map

package/dist/plugins/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/plugins/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;;AAwFH,2EAA2E;AAC3E,0EAA0E;AAC1E,8EAA8E"}

package/dist/recipes/__tests__/registry.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=registry.test.d.ts.map

package/dist/recipes/__tests__/registry.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.test.d.ts","sourceRoot":"","sources":["../../../src/recipes/__tests__/registry.test.ts"],"names":[],"mappings":""}