@opensip-cli/core 0.1.0

package/dist/plugins/capability-registry.js

@@ -0,0 +1,319 @@
+/**
+ * @fileoverview Scope-owned capability registry (launch, §5.3).
+ *
+ * The host-side runtime for the capability model in `tools/capability.ts`.
+ * A tool declares the domains it OWNS in its static manifest; the host
+ * registers each declared domain here alongside the owner-supplied
+ * REGISTRAR, then routes incoming contributions to the owning registrar
+ * after a Zod-free schema check. The host never interprets a
+ * contribution — it only confirms "targets a declared domain + passes its
+ * schema" and hands off (north-star §4.5).
+ *
+ * **Per-`RunScope`, no module singleton.** Mirrors the simulation §5.11
+ * template (`createScenarioRegistry` / `currentScenarioRegistry`):
+ *
+ *   - `createCapabilityRegistry()`  — factory the CLI bootstrap calls once
+ *     per invocation, attaching the result to `scope.capabilities`.
+ *   - `currentCapabilityRegistry()` — reads the scope-bound registry off
+ *     `currentScope()`; throws when called outside a `RunScope`.
+ *
+ * Unlike a tool subscope, the capability registry is a KERNEL concern (the
+ * host owns it, not any one tool), so its slot lives directly on
+ * `ToolScope` (`capabilities?`) rather than under a tool's name. A run that
+ * never constructs one carries `scope.capabilities === undefined` and reads
+ * return `undefined`.
+ *
+ * Errors are typed + structured (§ Steps 2.1.3): an unknown domain is a
+ * `NotFoundError` (`CAPABILITY.DOMAIN.UNKNOWN`); a schema mismatch is a
+ * `ValidationError` (`CAPABILITY.CONTRIBUTION.SCHEMA_MISMATCH`), both
+ * carrying a structured `diagnostic` for the CLI error boundary.
+ */
+import { CapabilitySchemaMismatchError, SystemError, UnknownCapabilityDomainError, } from '../lib/errors.js';
+import { logger as defaultLogger } from '../lib/logger.js';
+import { currentScope } from '../lib/run-scope.js';
+import { isCapabilityValidator, isStructuralContributionSchema, } from '../tools/capability.js';
+/**
+ * Per-`RunScope` capability registry. Holds the declared domains (by id)
+ * and routes contributions to their owners. Construct one per CLI
+ * invocation via {@link createCapabilityRegistry}; read the scope-bound
+ * instance via {@link currentCapabilityRegistry}.
+ */
+export class CapabilityRegistry {
+    domains = new Map();
+    /**
+     * Per-domain discovery load-state, keyed by domain id. This is the per-scope
+     * memoization that the capability loader reads/writes so a domain's
+     * contributions are discovered + routed exactly once per project per scope.
+     * Because the registry is itself per-`RunScope`, this state is per-scope too —
+     * a second run for the same project re-loads into its own fresh registry.
+     * This is the structural fix for the audit's F1 (sim's module-level
+     * `scenariosLoadedFor`): the marker lives on a scope-owned object, not a module.
+     */
+    loadState = new Map();
+    logger;
+    constructor(logger = defaultLogger) {
+        this.logger = logger;
+    }
+    /** True when domain `domainId` has been discovery-loaded for `projectKey` in this scope. */
+    isDomainLoaded(domainId, projectKey) {
+        return this.loadState.get(domainId)?.loadedFor === projectKey;
+    }
+    /** Record that `domainId` finished discovery-loading for `projectKey`, with any routing errors. */
+    markDomainLoaded(domainId, projectKey, errors) {
+        this.loadState.set(domainId, { loadedFor: projectKey, errors });
+    }
+    /** Routing errors recorded during the most recent load of `domainId` (empty if none / never loaded). */
+    domainLoadErrors(domainId) {
+        return this.loadState.get(domainId)?.errors ?? [];
+    }
+    /**
+     * Register a capability domain + its owner's registrar. First-writer-wins
+     * on duplicate domain id: a second registration of the same id is a no-op
+     * (logged at debug) — mirrors the discovery walker's nearest-ancestor
+     * dedup, so re-running discovery is idempotent.
+     *
+     * @param spec The domain description (id, owner, epoch, schema, kind).
+     * @param registrar The owner callback invoked for a validated contribution.
+     */
+    registerDomain(spec, registrar) {
+        if (this.domains.has(spec.id)) {
+            this.logger.debug({
+                evt: 'capability.domain.duplicate',
+                module: 'core:plugins',
+                domainId: spec.id,
+                ownerToolId: spec.ownerToolId,
+                msg: `capability domain '${spec.id}' already registered — keeping incumbent`,
+            });
+            return;
+        }
+        this.domains.set(spec.id, { spec, registrar });
+        this.logger.debug({
+            evt: 'capability.domain.registered',
+            module: 'core:plugins',
+            domainId: spec.id,
+            ownerToolId: spec.ownerToolId,
+            apiVersion: spec.apiVersion,
+            contributionKind: spec.contributionKind,
+        });
+    }
+    /**
+     * Replace the registrar for an ALREADY-REGISTERED domain (Phase 4). The
+     * manifest-read path ({@link registerCapabilityDomainsFromManifest})
+     * registers each declared domain with a DEFERRED placeholder registrar that
+     * throws on any contribution; once the owning tool's runtime module loads,
+     * the host calls this to swap in the tool's REAL registrar.
+     *
+     * This is the deliberate complement to {@link registerDomain}'s
+     * first-writer-wins: a domain's REGISTRAR is owner-replaceable (the owner
+     * supplies it late), but its SPEC is not — the spec stays exactly as the
+     * manifest declared it, so identity/epoch/schema cannot be overwritten by a
+     * late registrar wiring. Only the owning tool should call this (the host
+     * routes by `ownerToolId`); the spec is left untouched.
+     *
+     * @param domainId The domain whose registrar to replace.
+     * @param registrar The owner's real registrar.
+     * @throws {NotFoundError} (`CAPABILITY.DOMAIN.UNKNOWN`) when no domain
+     *   `domainId` is registered — a registrar cannot be wired for a domain the
+     *   host never declared (a manifest/tool-id mismatch).
+     */
+    setRegistrar(domainId, registrar) {
+        const entry = this.domains.get(domainId);
+        if (entry === undefined) {
+            const known = [...this.domains.keys()];
+            throw new UnknownCapabilityDomainError(`capability: cannot wire a registrar for undeclared domain '${domainId}'` +
+                (known.length > 0 ? ` (known domains: ${known.join(', ')})` : ' (no domains declared)'), { domainId, knownDomains: known });
+        }
+        // Replace the registrar; keep the manifest-declared spec verbatim.
+        this.domains.set(domainId, { spec: entry.spec, registrar });
+        this.logger.debug({
+            evt: 'capability.domain.registrar_wired',
+            module: 'core:plugins',
+            domainId,
+            ownerToolId: entry.spec.ownerToolId,
+        });
+    }
+    /** Whether a domain with `domainId` is registered. */
+    hasDomain(domainId) {
+        return this.domains.has(domainId);
+    }
+    /** Look up a registered domain's spec, or `undefined`. */
+    getDomain(domainId) {
+        return this.domains.get(domainId)?.spec;
+    }
+    /** All registered domain specs (registration order). */
+    listDomains() {
+        return [...this.domains.values()].map((d) => d.spec);
+    }
+    /**
+     * Route a contribution to the owner of `domainId`. The host (a) confirms
+     * the domain is declared, (b) validates `contribution` against the
+     * domain's `contributionSchema`, then (c) hands it to the owner's
+     * registrar. The host never interprets the contribution beyond the
+     * schema check — the domain owner does.
+     *
+     * @throws {NotFoundError} (`CAPABILITY.DOMAIN.UNKNOWN`) when no domain
+     *   `domainId` is registered.
+     * @throws {ValidationError} (`CAPABILITY.CONTRIBUTION.SCHEMA_MISMATCH`)
+     *   when the contribution fails the domain's schema check.
+     */
+    routeContribution(domainId, contribution) {
+        const entry = this.domains.get(domainId);
+        if (entry === undefined) {
+            const known = [...this.domains.keys()];
+            throw new UnknownCapabilityDomainError(`capability: no domain '${domainId}' is declared` +
+                (known.length > 0 ? ` (known domains: ${known.join(', ')})` : ' (no domains declared)'), { domainId, knownDomains: known });
+        }
+        const verdict = validateContribution(entry.spec.contributionSchema, contribution);
+        if (verdict !== true) {
+            throw new CapabilitySchemaMismatchError(`capability: contribution to domain '${domainId}' (owner '${entry.spec.ownerToolId}') ` +
+                `failed its schema: ${verdict}`, { domainId, ownerToolId: entry.spec.ownerToolId, diagnostic: verdict });
+        }
+        entry.registrar(contribution);
+    }
+}
+/**
+ * Validate a contribution against a domain's `contributionSchema` WITHOUT
+ * Zod. Three kinds of schema are accepted:
+ *
+ *   - a {@link CapabilityValidator} function — called; its `true | string`
+ *     result IS the verdict.
+ *   - a {@link StructuralContributionSchema} (`{ requiredKeys }`) — each
+ *     listed key must be present (and non-`undefined`) on a record-shaped
+ *     contribution.
+ *   - `undefined` / anything else — treated as "no constraint": any
+ *     contribution passes (a domain may opt out of host-side checking and
+ *     validate entirely inside its own registrar).
+ *
+ * @returns `true` when the contribution satisfies the schema, otherwise a
+ *   human-readable reason string (surfaced in the `ValidationError`).
+ */
+function validateContribution(schema, contribution) {
+    if (isCapabilityValidator(schema)) {
+        return schema(contribution);
+    }
+    if (isStructuralContributionSchema(schema)) {
+        if (typeof contribution !== 'object' || contribution === null) {
+            return `expected an object contribution with keys [${schema.requiredKeys.join(', ')}], got ${contribution === null ? 'null' : typeof contribution}`;
+        }
+        const record = contribution;
+        const missing = schema.requiredKeys.filter((k) => record[k] === undefined);
+        if (missing.length > 0) {
+            return `missing required key(s): ${missing.join(', ')}`;
+        }
+        return true;
+    }
+    // No declared constraint — defer all validation to the owner's registrar.
+    return true;
+}
+/** Construct a fresh capability registry for a single `RunScope`. */
+export function createCapabilityRegistry(logger) {
+    return new CapabilityRegistry(logger);
+}
+/**
+ * Read the current scope's capability registry. Throws when no scope is
+ * active or when the scope has no capability registry — both indicate the
+ * caller is running outside the CLI's pre-action-hook (or a test fixture
+ * forgot to construct + attach one).
+ *
+ * @throws {Error} When called outside `runWithScope(...)`, or when the
+ *   active scope carries no `capabilities` registry.
+ */
+export function currentCapabilityRegistry() {
+    const scope = currentScope();
+    if (!scope) {
+        throw new Error('core: currentCapabilityRegistry() called outside a RunScope. ' +
+            'Wrap the call site in runWithScope (production: the pre-action-hook ' +
+            'constructs the scope; tests: construct a RunScope, attach ' +
+            'createCapabilityRegistry() to scope.capabilities, then runWithScope).');
+    }
+    if (!scope.capabilities) {
+        throw new Error('core: scope.capabilities is missing. The CLI bootstrap must attach ' +
+            'createCapabilityRegistry() to the scope before capability reads ' +
+            '(production: the pre-action-hook seeds it; tests: assign ' +
+            'scope.capabilities = createCapabilityRegistry()).');
+    }
+    return scope.capabilities;
+}
+/**
+ * Register every capability domain a manifest declares into the per-run
+ * {@link CapabilityRegistry}, stamping `ownerToolId = manifest.stableId ??
+ * manifest.id` on each (§5.3 / Task 2.2; ADR-0048 — the owner key must equal the
+ * owning tool's `metadata.id`, which is the stable UUID for modern tools). This
+ * is how `MARKER_KINDS` becomes a BOOTSTRAP DEFAULT:
+ * the marker enum still seeds the discovery vocabulary, and a
+ * manifest-declared domain EXTENDS that set — registered here without any
+ * host-enum edit. Additive: a manifest with no `capabilities` registers
+ * nothing.
+ *
+ * The owner-supplied registrar is NOT known at manifest-read time (the
+ * tool's runtime module hasn't been imported), so this registers the
+ * domain with a deferred-registrar placeholder that THROWS if a
+ * contribution is routed before the owning tool wires its real registrar
+ * (Phase 4). The host knows the domain EXISTS and who owns it; the owner
+ * supplies the actual registrar when its module loads.
+ *
+ * Emits one structured `capability.domain.from_manifest` evt per domain so
+ * a manifest-sourced domain is observable in structured logs (Task 2.2.3).
+ *
+ * @param manifest The validated manifest carrying the declarations.
+ * @param registry The per-run capability registry to populate.
+ * @returns The {@link CapabilityDomainSpec}s registered (owner-stamped).
+ */
+export function registerCapabilityDomainsFromManifest(manifest, registry) {
+    const declarations = manifest.capabilities ?? [];
+    const registered = [];
+    for (const decl of declarations) {
+        const spec = {
+            id: decl.id,
+            // ADR-0048: `ownerToolId` must equal the OWNING TOOL'S `metadata.id`, which
+            // the capability loader filters on (`d.ownerToolId === owningTool.metadata.id`).
+            // Post-ADR-0048 `metadata.id` is the stable UUID (== `manifest.stableId`) and
+            // `manifest.id` is the human name (== `metadata.name`). Prefer the stableId so
+            // the owner match works; fall back to the human `id` for legacy tools that
+            // declare no `stableId` (where `metadata.id` is still the human id).
+            ownerToolId: manifest.stableId ?? manifest.id,
+            apiVersion: decl.apiVersion,
+            contributionSchema: decl.contributionSchema,
+            contributionKind: decl.contributionKind,
+            // Carry the discovery descriptor onto the spec so the scope-owned capability
+            // loader can drive the generic substrate for this domain (§5.3). Absent →
+            // the domain auto-discovers nothing.
+            ...(decl.discovery === undefined ? {} : { discovery: decl.discovery }),
+        };
+        registry.registerDomain(spec, makeDeferredRegistrar(spec));
+        defaultLogger.info({
+            evt: 'capability.domain.from_manifest',
+            module: 'core:plugins',
+            domainId: spec.id,
+            ownerToolId: spec.ownerToolId,
+            apiVersion: spec.apiVersion,
+            contributionKind: spec.contributionKind,
+        });
+        registered.push(spec);
+    }
+    return registered;
+}
+/**
+ * A placeholder registrar for a manifest-declared domain whose owning tool
+ * has not wired its real registrar (Phase 4). Routing a contribution
+ * before then is a programming error — the host knows the domain exists,
+ * but no one can yet accept a contribution to it — so it throws a clear
+ * diagnostic rather than silently dropping the contribution.
+ *
+ * @param spec The domain being registered with this placeholder.
+ * @returns A {@link CapabilityRegistrar} that throws a {@link SystemError} on
+ *   any invocation, until Phase 4 replaces it with the owning tool's real
+ *   registrar.
+ */
+function makeDeferredRegistrar(spec) {
+    return () => {
+        // A SystemError (internal invariant violation): the domain exists but its
+        // owning tool has not wired a real registrar yet, so a contribution arrived
+        // before anyone can accept it. Self-documenting typed error — the throw is
+        // intentional (placeholder until Phase 4 wires real registrars).
+        throw new SystemError(`capability: domain '${spec.id}' (owner '${spec.ownerToolId}') was declared in a ` +
+            `manifest but its owning tool has not registered a runtime registrar yet ` +
+            `(Phase 4 wires real registrars). Cannot accept a contribution.`);
+    };
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/plugins/capability-registry.js.map

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

package/dist/plugins/discover.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Plugin discovery for the project-local layout.
+ *
+ * Discovery is descriptor-driven: the caller passes a `PluginLayout`
+ * (`{ domain, userSubdirs }`) declared by the owning tool. The kernel
+ * never enumerates tool domains itself (ADR-0009 corollary 1). Two
+ * artifact sources are walked for the layout:
+ *
+ *   1. USER SOURCE — recursive `.js` / `.mjs` files under
+ *      `<project>/opensip-cli/<domain>/<kind>/`
+ *      for each `kind` in `layout.userSubdirs` (e.g. `checks`/`recipes`
+ *      for fitness, `scenarios`/`recipes` for simulation). Auto-loaded
+ *      by directory presence; no config opt-in.
+ *
+ *   2. NPM PLUGINS — packages installed under
+ *      `<project>/opensip-cli/.runtime/plugins/<domain>/node_modules/`
+ *      whose names appear in the project's
+ *      `opensip-cli.config.yml#plugins.<domain>: [...]`. The explicit
+ *      list is required so a `plugin install` step is intentional, not
+ *      an accidental load of every transitive devDep.
+ *
+ * A layout with an empty `userSubdirs` and no declared npm plugins
+ * (e.g. the language-adapter domain, whose adapters ship as direct CLI
+ * deps) discovers nothing — an emergent property, not a special case.
+ */
+import type { DiscoveredPlugin, PluginLayout } from './types.js';
+/**
+ * Discover all plugins for a layout in the project layout.
+ *
+ * Returns a list of `DiscoveredPlugin` entries (loose .mjs files +
+ * npm packages) for the loader to import. Discovery is silent on a
+ * missing project directory or absent subdirs — callers that care
+ * about "did we find anything?" should check the returned length.
+ *
+ * @param layout      The owning tool's `PluginLayout` (`{ domain,
+ *                    userSubdirs }`).
+ * @param projectDir  Project root. Required — there is no user-global
+ *                    fallback. Pass undefined to discover nothing
+ *                    (used by callers that don't have a project
+ *                    context yet).
+ */
+export declare function discoverPlugins(layout: PluginLayout, projectDir?: string): DiscoveredPlugin[];
+/**
+ * Read the declared plugin list for a domain from the project config.
+ * Returns undefined when the config is absent, unreadable, or has no
+ * entry for the domain. Does NOT throw on YAML parse errors — returns
+ * undefined so discovery falls through gracefully and the config-layer
+ * schema validation surfaces parse errors on its own path.
+ *
+ * Config-path resolution mirrors `resolveProjectConfigPath` (the same
+ * helper the targets loader uses): --config flag → `package.json#
+ * opensip-cli.configPath` pointer → default `<projectDir>/opensip-
+ * tools.config.yml`. Without this, projects that locate their config
+ * via the package.json pointer have their `plugins.<domain>: [...]`
+ * declaration silently ignored — discovery falls through to the empty
+ * default path and the plugin pack never registers.
+ *
+ * The `--config` precedence is honored only when callers pass through
+ * their explicit value via `explicitConfigPath`; this entry point is
+ * the implicit one (no --config available at the discovery seam), so
+ * we resolve without an explicit path and rely on the pointer + default.
+ */
+export declare function readProjectPluginsList(projectDir: string, domain: string): readonly string[] | undefined;
+//# sourceMappingURL=discover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/plugins/discover.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAYH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AASjE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAuC7F;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,SAAS,MAAM,EAAE,GAAG,SAAS,CAqB/B"}