@opensip-cli/core 0.1.0

package/dist/tools/manifest-assert.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Load-time manifest⇔Tool drift guard (launch, Phase 1).
+ *
+ * The static `ToolPluginManifest` (declared in `package.json#opensipTools`)
+ * and the runtime `Tool` are two declarations of the same tool. Per ADR-0048
+ * the runtime uses `metadata.id` for the stable UUID and `metadata.name` for
+ * the human key (matching the manifest's `id` for the human key). Manifests
+ * may also declare `stableId` (additive) for the UUID.
+ *
+ * This guard asserts:
+ *   - manifest's human `id` === runtime `metadata.name`
+ *   - if manifest declares `stableId`, it === runtime `metadata.id`
+ *   - the **set** of command names is identical (order-insensitive).
+ *
+ * Descriptions/aliases are NOT compared. The guard runs after dynamic import
+ * for bundled, installed, and authored tools.
+ */
+import type { ToolPluginManifest } from './manifest.js';
+import type { Tool } from './types.js';
+/**
+ * Assert that a static `ToolPluginManifest` matches the runtime `Tool` it
+ * declares — same `id`, same set of command names. Throws `ValidationError`
+ * on any mismatch; returns `void` when they agree.
+ *
+ * This is the drift guard between the two identity declarations: the
+ * `package.json#opensipTools` manifest (read before importing the module)
+ * and the imported `Tool` (`metadata.id` + `commands[]`). Catches a manifest
+ * that fell out of sync with the tool's runtime command surface.
+ *
+ * @param manifest The static manifest read from `package.json#opensipTools`.
+ * @param tool The runtime tool the manifest is supposed to describe.
+ * @throws {ValidationError} when `id` differs, or the command-name sets differ.
+ */
+export declare function assertManifestMatchesTool(manifest: ToolPluginManifest, tool: Tool): void;
+//# sourceMappingURL=manifest-assert.d.ts.map

package/dist/tools/manifest-assert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-assert.d.ts","sourceRoot":"","sources":["../../src/tools/manifest-assert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,CA6CxF"}

package/dist/tools/manifest-assert.js

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Load-time manifest⇔Tool drift guard (launch, Phase 1).
+ *
+ * The static `ToolPluginManifest` (declared in `package.json#opensipTools`)
+ * and the runtime `Tool` are two declarations of the same tool. Per ADR-0048
+ * the runtime uses `metadata.id` for the stable UUID and `metadata.name` for
+ * the human key (matching the manifest's `id` for the human key). Manifests
+ * may also declare `stableId` (additive) for the UUID.
+ *
+ * This guard asserts:
+ *   - manifest's human `id` === runtime `metadata.name`
+ *   - if manifest declares `stableId`, it === runtime `metadata.id`
+ *   - the **set** of command names is identical (order-insensitive).
+ *
+ * Descriptions/aliases are NOT compared. The guard runs after dynamic import
+ * for bundled, installed, and authored tools.
+ */
+import { ValidationError } from '../lib/errors.js';
+/**
+ * Assert that a static `ToolPluginManifest` matches the runtime `Tool` it
+ * declares — same `id`, same set of command names. Throws `ValidationError`
+ * on any mismatch; returns `void` when they agree.
+ *
+ * This is the drift guard between the two identity declarations: the
+ * `package.json#opensipTools` manifest (read before importing the module)
+ * and the imported `Tool` (`metadata.id` + `commands[]`). Catches a manifest
+ * that fell out of sync with the tool's runtime command surface.
+ *
+ * @param manifest The static manifest read from `package.json#opensipTools`.
+ * @param tool The runtime tool the manifest is supposed to describe.
+ * @throws {ValidationError} when `id` differs, or the command-name sets differ.
+ */
+export function assertManifestMatchesTool(manifest, tool) {
+    // Human key resolution:
+    // - For tools using the post-ADR-0048 shape (stable UUID in .id, human key in .name): use .name
+    // - For legacy-shaped fixtures/tests (human key still in .id, or .name is display-only): fall back to .id
+    // This keeps authored/installed test fixtures working without mass updates while enforcing the split for real tools.
+    const isModernShape = typeof tool.metadata.id === 'string' && /^[0-9a-fA-F]{8}-/.test(tool.metadata.id);
+    const runtimeHuman = isModernShape && tool.metadata.name ? tool.metadata.name : tool.metadata.id;
+    if (manifest.id !== runtimeHuman) {
+        throw new ValidationError(`tool manifest id '${manifest.id}' does not match runtime tool name '${runtimeHuman}'`);
+    }
+    // If the manifest declares a stableId (additive per ADR-0048), it must match
+    // the runtime's stable UUID in `metadata.id`.
+    if (manifest.stableId !== undefined && manifest.stableId !== tool.metadata.id) {
+        throw new ValidationError(`tool manifest stableId '${manifest.stableId}' does not match runtime tool id '${tool.metadata.id}'`);
+    }
+    const manifestNames = new Set(manifest.commands.map((c) => c.name));
+    const toolNames = new Set(tool.commands.map((c) => c.name));
+    const missingFromManifest = [...toolNames]
+        .filter((n) => !manifestNames.has(n))
+        .sort((a, b) => a.localeCompare(b));
+    const extraInManifest = [...manifestNames]
+        .filter((n) => !toolNames.has(n))
+        .sort((a, b) => a.localeCompare(b));
+    if (missingFromManifest.length > 0 || extraInManifest.length > 0) {
+        const parts = [];
+        if (missingFromManifest.length > 0) {
+            parts.push(`missing from manifest: [${missingFromManifest.join(', ')}]`);
+        }
+        if (extraInManifest.length > 0) {
+            parts.push(`declared in manifest but not in tool: [${extraInManifest.join(', ')}]`);
+        }
+        throw new ValidationError(`tool manifest commands for '${manifest.id}' do not match runtime tool commands (${parts.join('; ')})`);
+    }
+}
+//# sourceMappingURL=manifest-assert.js.map

package/dist/tools/manifest-assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-assert.js","sourceRoot":"","sources":["../../src/tools/manifest-assert.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAKnD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAA4B,EAAE,IAAU;IAChF,wBAAwB;IACxB,gGAAgG;IAChG,0GAA0G;IAC1G,qHAAqH;IACrH,MAAM,aAAa,GACjB,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,KAAK,QAAQ,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACpF,MAAM,YAAY,GAAG,aAAa,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAEjG,IAAI,QAAQ,CAAC,EAAE,KAAK,YAAY,EAAE,CAAC;QACjC,MAAM,IAAI,eAAe,CACvB,qBAAqB,QAAQ,CAAC,EAAE,uCAAuC,YAAY,GAAG,CACvF,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,8CAA8C;IAC9C,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QAC9E,MAAM,IAAI,eAAe,CACvB,2BAA2B,QAAQ,CAAC,QAAQ,qCAAqC,IAAI,CAAC,QAAQ,CAAC,EAAE,GAAG,CACrG,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpE,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAE5D,MAAM,mBAAmB,GAAG,CAAC,GAAG,SAAS,CAAC;SACvC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACpC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,eAAe,GAAG,CAAC,GAAG,aAAa,CAAC;SACvC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SAChC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;IAEtC,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjE,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,2BAA2B,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC3E,CAAC;QACD,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC/B,KAAK,CAAC,IAAI,CAAC,0CAA0C,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,IAAI,eAAe,CACvB,+BAA+B,QAAQ,CAAC,EAAE,yCAAyC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACvG,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/tools/manifest.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @fileoverview Static tool-plugin manifest + the plugin-API epoch +
+ * provenance types (launch, raw-vs-admitted compatibility contract).
+ *
+ * The **manifest** is the static front matter the host reads *before*
+ * importing a tool's runtime `Tool` module (north-star §5.1). It is
+ * declared in `package.json#opensipTools` for bundled + installed tools
+ * (one read for both) and as a JSON sidecar for project-local tools.
+ *
+ * `PLUGIN_API_VERSION` is a coarse integer **epoch** for the plugin
+ * *input* contract. A tool declares the epoch it was compiled against
+ * via `RawToolPluginManifest.apiVersion`; the host's single
+ * `checkCompatibility()` gate (see `compatibility.ts`) admits or rejects
+ * on that integer alone — no semver range maths. Once admitted, the manifest is
+ * represented as `ToolPluginManifest`, whose `apiVersion` is required.
+ *
+ * The host consumes identity + command metadata and, as of ADR-0029, the
+ * concrete `capabilities` descriptor that declares owned capability domains.
+ * Remaining fields (`config`/`dashboard`/…) stay typed-but-not-consumed
+ * placeholders so a manifest authored today stays forward-shaped.
+ *
+ * These types live in **core** (next to the `Tool` contract). `contracts`
+ * re-exports them for the public surface; core cannot import contracts.
+ */
+import type { ToolCapabilityDeclaration } from './capability.js';
+/**
+ * The plugin-API epoch the running engine implements.
+ *
+ * A coarse integer, bumped only on a breaking change to the plugin
+ * *input* contract. A tool manifest's `apiVersion` is compared against
+ * this single value by `checkCompatibility()`. A missing `apiVersion`
+ * is incompatible as of launch; raw manifests stay representable so the
+ * admission gate can diagnose unversioned inputs before rejecting them.
+ */
+export declare const PLUGIN_API_VERSION = 1;
+/**
+ * Where a tool plugin came from. Drives the trust policy and the
+ * provenance record surfaced in structured logs + `plugin list`.
+ *
+ *   - `bundled`       — a first-party tool shipped with the CLI
+ *                       (trusted-by-shipping).
+ *   - `installed`     — an npm package discovered via tool-package-discovery
+ *                       (incl. `plugin add` / `plugin add --project`). Trusted
+ *                       as an installed dependency.
+ *   - `user-global`   — an authored sidecar under
+ *                       `~/.opensip-cli/tools/<name>/`
+ *                       (`opensip-tool.manifest.json`). The user placed it in
+ *                       their own home dir (the `npm i -g` analogue for
+ *                       authored code) → **trusted-by-default**.
+ *   - `project-local` — an authored sidecar under
+ *                       `<project>/opensip-cli/tools/<name>/`
+ *                       (`opensip-tool.manifest.json`). It rides in with
+ *                       `git clone` → **deny-by-default**; admitted only when
+ *                       its id (or `*`) is allowlisted via
+ *                       `OPENSIP_CLI_ALLOW_PROJECT_TOOLS`.
+ */
+export type ToolSource = 'bundled' | 'installed' | 'user-global' | 'project-local';
+/**
+ * Identity of a command a tool contributes, as declared in the static
+ * manifest. Mirrors the runtime `ToolCommandDescriptor` (`types.ts`) so
+ * the bundled path can assert manifest⇔`Tool.commands` equality (Phase 1).
+ */
+export interface ToolCommandManifest {
+    /** CLI subcommand name — 'fit', 'sim', 'fit-list', etc. */
+    readonly name: string;
+    readonly description: string;
+    readonly aliases?: readonly string[];
+}
+/**
+ * The static front matter a tool plugin declares (in
+ * `package.json#opensipTools` or a JSON sidecar) so the host can inspect
+ * its identity + contract epoch **without importing the runtime module**.
+ *
+ * The host consumes the identity subset
+ * (`kind`/`id`/`name`/`version`/`apiVersion`/`commands`) plus the concrete
+ * `capabilities` descriptor. The remaining fields are typed-but-not-consumed
+ * placeholders for later releases so a manifest authored today is
+ * forward-shaped; they are deliberately `unknown`-shaped until a release gives
+ * them concrete semantics.
+ *
+ * Launch (§5.3) gives `capabilities` its concrete shape — an
+ * array of {@link ToolCapabilityDeclaration} (the capability domains the
+ * tool OWNS). It stays OPTIONAL and additive: a manifest with no
+ * `capabilities` declares no domains, and `MARKER_KINDS` remains the
+ * bootstrap-default domain vocabulary. The other slots stay `unknown`.
+ */
+interface ToolPluginManifestBase {
+    /** Discriminator — always `'tool'` (matches `opensipTools.kind`). */
+    readonly kind: 'tool';
+    /**
+     * Human/programmatic key (the value used for current storage, short ids,
+     * config, etc.). For published tools this is the "declared" identifier.
+     * This remains the manifest-side key for backward compat (ADR-0048).
+     * The tool's stable machine identity (UUID) is declared here as `stableId`
+     * (additive) when the tool author pins one; at runtime it appears as
+     * `ToolMetadata.id` (with the human key in `ToolMetadata.name`).
+     */
+    readonly id: string;
+    /**
+     * Stable machine identity (real UUID) for this tool, matching the semantics
+     * and field name of Checks' `id`. Declared additively by tools that opt into
+     * durable identity (first-party tools declare it; community tools should too).
+     * When present, the drift guard and provenance capture it.
+     */
+    readonly stableId?: string;
+    /** Human-facing display name. */
+    readonly name: string;
+    /** Display semver of the tool itself (NOT the contract epoch). */
+    readonly version: string;
+    /** Command identities the tool contributes — `--help` / conflict detection. */
+    readonly commands: readonly ToolCommandManifest[];
+    /**
+     * §5.3 → Launch: the capability domains this tool OWNS. Each entry is a
+     * {@link ToolCapabilityDeclaration} (id + contribution epoch + schema +
+     * kind); the host stamps `ownerToolId = this.stableId ?? this.id` (ADR-0048:
+     * the owner key must equal the owning tool's `metadata.id` — the stable UUID
+     * for modern tools) and registers each into the per-run capability registry,
+     * EXTENDING the `MARKER_KINDS` bootstrap vocabulary without a host-enum edit.
+     * Optional + additive.
+     */
+    readonly capabilities?: readonly ToolCapabilityDeclaration[];
+    /** §5.7 → 2.9.0: tool-owned config schema descriptor. */
+    readonly config?: unknown;
+    /** Later: dashboard-contribution descriptor. */
+    readonly dashboard?: unknown;
+    /** Later: sessions-contribution descriptor. */
+    readonly sessions?: unknown;
+    /** Later: declared plugin domains the tool hosts. */
+    readonly pluginDomains?: readonly unknown[];
+    /** Later: declared host/peer requirements. */
+    readonly requires?: readonly unknown[];
+    /** Reserved: compatibility metadata (minApiVersion, languages, etc.). */
+    readonly compatibility?: unknown;
+    /** Reserved: distribution posture for community/catalog. */
+    readonly distribution?: 'private' | 'public-free' | 'public-paid' | unknown;
+    /** General bag for future extension metadata (publisher, pricing, etc.). */
+    readonly extensionMetadata?: unknown;
+}
+/**
+ * Structurally valid manifest front matter before compatibility admission.
+ * `apiVersion` is optional here only so the loader can represent and diagnose
+ * manifest-incompatible unversioned tools without pretending they are admitted.
+ */
+export interface RawToolPluginManifest extends ToolPluginManifestBase {
+    /** The plugin-API epoch this tool was compiled against, if declared. */
+    readonly apiVersion?: number;
+}
+/**
+ * A manifest that passed the compatibility gate and can seed runtime surfaces
+ * such as command mounting, provenance, and capability registration.
+ */
+export interface ToolPluginManifest extends ToolPluginManifestBase {
+    /** The plugin-API epoch this admitted tool was compiled against. */
+    readonly apiVersion: number;
+}
+/**
+ * The provenance record the host attaches when it admits a tool —
+ * source + identity + a hash of the manifest it read. Surfaced via
+ * structured logs on load and via `plugin list` (Phase 4).
+ */
+export interface ToolProvenance {
+    /** Where the tool came from. */
+    readonly source: ToolSource;
+    /** The tool's human/programmatic key (from the manifest). */
+    readonly id: string;
+    /** The tool's stable identity (real UUID) when declared (additive per ADR-0048). */
+    readonly stableId?: string;
+    /** The tool's display version (from the manifest). */
+    readonly version: string;
+    /** npm package name, when the tool is an installed/bundled package. */
+    readonly packageName?: string;
+    /** Filesystem path the manifest was resolved from, when applicable. */
+    readonly resolvedPath?: string;
+    /** Stable hash of the manifest bytes the host read — tamper/identity check. */
+    readonly manifestHash: string;
+}
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/tools/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAEjE;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,eAAe,CAAC;AAEnF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,UAAU,sBAAsB;IAC9B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,iCAAiC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAMlD;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC7D,yDAAyD;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC5C,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAWvC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG,OAAO,CAAC;IAC5E,4EAA4E;IAC5E,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,sBAAsB;IACnE,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IAChE,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B"}

package/dist/tools/manifest.js

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Static tool-plugin manifest + the plugin-API epoch +
+ * provenance types (launch, raw-vs-admitted compatibility contract).
+ *
+ * The **manifest** is the static front matter the host reads *before*
+ * importing a tool's runtime `Tool` module (north-star §5.1). It is
+ * declared in `package.json#opensipTools` for bundled + installed tools
+ * (one read for both) and as a JSON sidecar for project-local tools.
+ *
+ * `PLUGIN_API_VERSION` is a coarse integer **epoch** for the plugin
+ * *input* contract. A tool declares the epoch it was compiled against
+ * via `RawToolPluginManifest.apiVersion`; the host's single
+ * `checkCompatibility()` gate (see `compatibility.ts`) admits or rejects
+ * on that integer alone — no semver range maths. Once admitted, the manifest is
+ * represented as `ToolPluginManifest`, whose `apiVersion` is required.
+ *
+ * The host consumes identity + command metadata and, as of ADR-0029, the
+ * concrete `capabilities` descriptor that declares owned capability domains.
+ * Remaining fields (`config`/`dashboard`/…) stay typed-but-not-consumed
+ * placeholders so a manifest authored today stays forward-shaped.
+ *
+ * These types live in **core** (next to the `Tool` contract). `contracts`
+ * re-exports them for the public surface; core cannot import contracts.
+ */
+/**
+ * The plugin-API epoch the running engine implements.
+ *
+ * A coarse integer, bumped only on a breaking change to the plugin
+ * *input* contract. A tool manifest's `apiVersion` is compared against
+ * this single value by `checkCompatibility()`. A missing `apiVersion`
+ * is incompatible as of launch; raw manifests stay representable so the
+ * admission gate can diagnose unversioned inputs before rejecting them.
+ */
+export const PLUGIN_API_VERSION = 1;
+//# sourceMappingURL=manifest.js.map

package/dist/tools/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/tools/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Tool registry — in-memory list of registered Tool implementations.
+ *
+ * The CLI populates the registry at startup (first-party tools as
+ * direct imports, third-party tools via tool-package-discovery), then
+ * iterates `list()` to build its command tree.
+ *
+ * **Duplicate-id policy: first writer wins.** Re-registering the same
+ * id keeps the existing entry and emits a structured warning. This
+ * matches `LanguageRegistry`'s policy and prevents third-party plugins
+ * from accidentally clobbering first-party registrations.
+ *
+ * Implemented on top of the kernel's `Registry<T>` base. Tools don't
+ * naturally satisfy `Registerable` (no `name` field on metadata), so
+ * the registry wraps each Tool in a `{ id, name: id, tool }` envelope
+ * before storing it. `list()` / `get()` unwrap.
+ */
+import type { Tool } from './types.js';
+/** Per-run registry of {@link Tool} plugins, indexed by the human name (metadata.name). */
+export declare class ToolRegistry {
+    private readonly inner;
+    /**
+     * Register a tool. **First writer wins** — re-registering the same
+     * (human) id is a no-op and emits a `tool.registry.duplicate` warning.
+     *
+     * The registry is keyed by the human `metadata.name` (the former `id` value)
+     * for continuity with callers that do registry.get('fitness') etc. The stable
+     * UUID lives in metadata.id and is not used as the registry key.
+     */
+    register(tool: Tool, opts?: {
+        sourcePackage?: string;
+    }): void;
+    list(): readonly Tool[];
+    get(id: string): Tool | undefined;
+    clear(): void;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAQvC,2FAA2F;AAC3F,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAInB;IAEH;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,GAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,IAAI;IAKjE,IAAI,IAAI,SAAS,IAAI,EAAE;IAIvB,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIjC,KAAK,IAAI,IAAI;CAGd"}

package/dist/tools/registry.js

@@ -0,0 +1,49 @@
+// @fitness-ignore-file batch-operation-limits -- getAll() over the registered tool set (a handful of first-party + plugin tools per CLI invocation)
+/**
+ * Tool registry — in-memory list of registered Tool implementations.
+ *
+ * The CLI populates the registry at startup (first-party tools as
+ * direct imports, third-party tools via tool-package-discovery), then
+ * iterates `list()` to build its command tree.
+ *
+ * **Duplicate-id policy: first writer wins.** Re-registering the same
+ * id keeps the existing entry and emits a structured warning. This
+ * matches `LanguageRegistry`'s policy and prevents third-party plugins
+ * from accidentally clobbering first-party registrations.
+ *
+ * Implemented on top of the kernel's `Registry<T>` base. Tools don't
+ * naturally satisfy `Registerable` (no `name` field on metadata), so
+ * the registry wraps each Tool in a `{ id, name: id, tool }` envelope
+ * before storing it. `list()` / `get()` unwrap.
+ */
+import { Registry } from '../lib/registry.js';
+/** Per-run registry of {@link Tool} plugins, indexed by the human name (metadata.name). */
+export class ToolRegistry {
+    inner = new Registry({
+        module: 'core:tools',
+        duplicatePolicy: 'warn-first-wins',
+        evtPrefix: 'tool.registry',
+    });
+    /**
+     * Register a tool. **First writer wins** — re-registering the same
+     * (human) id is a no-op and emits a `tool.registry.duplicate` warning.
+     *
+     * The registry is keyed by the human `metadata.name` (the former `id` value)
+     * for continuity with callers that do registry.get('fitness') etc. The stable
+     * UUID lives in metadata.id and is not used as the registry key.
+     */
+    register(tool, opts = {}) {
+        const key = tool.metadata.name ?? tool.metadata.id;
+        this.inner.register({ id: key, name: key, tool }, { sourcePackage: opts.sourcePackage });
+    }
+    list() {
+        return this.inner.getAll().map((r) => r.tool);
+    }
+    get(id) {
+        return this.inner.getById(id)?.tool;
+    }
+    clear() {
+        this.inner.clear();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AAAA,oJAAoJ;AACpJ;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,QAAQ,EAAqB,MAAM,oBAAoB,CAAC;AAUjE,2FAA2F;AAC3F,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,QAAQ,CAAmB;QACtD,MAAM,EAAE,YAAY;QACpB,eAAe,EAAE,iBAAiB;QAClC,SAAS,EAAE,eAAe;KAC3B,CAAC,CAAC;IAEH;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAU,EAAE,OAAmC,EAAE;QACxD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAChD,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC;IACtC,CAAC;IAED,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;CACF"}