@intentius/chant 0.124.13 → 0.124.15

package/dist/components/auto-release.js

@@ -0,0 +1,143 @@
+/**
+ * Auto-emit a release-ledger record from a successful `chant run --components
+ * <name> --env <env>` (#597, follow-up to #568/epic #551). Before this, the
+ * release ledger (../lifecycle/release-ledger.ts) was only populated by the
+ * standalone `chant components release <env>` command — a deploy that never
+ * called it left the ledger silently empty. This module makes recording
+ * happen *by construction*: the CLI's post-run step (`runOpComponents`)
+ * calls `maybeRecordAutoRelease` after the run reports success.
+ *
+ * Deliberately CLI-side, not driver-side or workflow-side:
+ *  - `../components/driver.ts` stays capability-agnostic — it already
+ *    resists per-component/per-capability branching, and "write to git"
+ *    is exactly the kind of side effect that doesn't belong in a step
+ *    dispatcher tests exercise against a bare `CapabilityRegistry`.
+ *  - A ledger write is a non-idempotent git push with real-world side
+ *    effects (network, `Date.now()`, file writes) — the kind of thing that
+ *    belongs at the edge of a run rather than inside a step a retry may run
+ *    a second time. It happens in the CLI, once the run has reported a
+ *    terminal outcome.
+ *
+ * Reuses ../lifecycle/release-ledger.ts's `appendReleaseRecord` verbatim —
+ * this module only decides *whether* to call it and *what digest* to record,
+ * mirroring the field-resolution `runComponentsReleaseRecord`
+ * (../cli/handlers/components.ts) already does for the standalone command
+ * (`--git-sha` defaults to HEAD, `--run-id`/`--actor` fall back to common CI
+ * env vars, timestamp is a real `new Date()` taken at record time).
+ */
+import { getHeadCommit, pushLifecycle, StaleLifecycleBranchError } from "../lifecycle/git.js";
+import { appendReleaseRecord, InvalidReleaseRecordError } from "../lifecycle/release-ledger.js";
+/**
+ * A step output that represents a *promoted* artifact — a publish-family result
+ * (publish-image / publish-artifact / load-image-on-host), identified by the
+ * location `uri` all three carry (`repo@sha256:…`, `host:…#…`, an artifact URL).
+ * This deliberately excludes outputs that carry only a content `digest`: e.g.
+ * `generate-sbom`'s `digest` is the SBOM document's own bytes, and
+ * `extract-config-bom` likewise *describes* an artifact rather than promoting
+ * one. Those must not trigger a release record (#665) — a release means "we
+ * promoted this by digest to a location", not "we hashed some bytes". The
+ * driver's own `collectComponentOutputs` stays looser (uri/digest/key) because it
+ * only feeds `@<component>.publish.*` wiring, where a false positive is harmless.
+ */
+export function isPromotedArtifact(output) {
+    return !!output && typeof output === "object" && "uri" in output && typeof output.uri === "string";
+}
+/**
+ * Extract the artifact digest a component run promoted, by scanning its step
+ * records for the last {@link isPromotedArtifact promoted-artifact} output (a
+ * publish-family result carrying a location `uri`) and taking its `digest`, so
+ * a release record is only ever attempted when the run actually promoted
+ * something by digest. Returns undefined when no step promoted an artifact —
+ * e.g. a component whose deploy has no publish step, even if it ran
+ * `generate-sbom` (whose content `digest` is not a promotion, #665) — the
+ * caller treats that as "nothing to record", not an error. Used by the
+ * local-executor CLI path, which has the full `DriverStepRecord[]` from
+ * `runComponentDeploy`.
+ */
+export function extractRunDigest(records) {
+    let found;
+    for (const record of records) {
+        if (record.status !== "ok")
+            continue;
+        if (isPromotedArtifact(record.output) && typeof record.output.digest === "string") {
+            found = record.output.digest;
+        }
+    }
+    return found;
+}
+function resolveActor(override) {
+    return override ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+}
+/**
+ * After a successful `chant run --components <name> --env <env>`, append
+ * exactly one immutable release record to the ledger and push it — or
+ * explain, without throwing, why it didn't. Never called for a failed run
+ * (`run.success` must be true before the caller invokes this at all; see
+ * `runOpComponents`) — a failed
+ * deploy writes nothing, by construction, since this function is simply
+ * never reached on that path.
+ *
+ * Skips (returns `{ recorded: false, reason }`, never throws for these
+ * expected cases):
+ *  - `options.disabled` — the opt-out flag/config was set.
+ *  - `run.success` false — defensive; callers should not reach here on failure.
+ *  - no digest found in the run's records — a component with no publish step
+ *    has nothing to bind a release record to.
+ *  - no resolvable actor — mirrors `runComponentsReleaseRecord`'s hard
+ *    requirement; an unattributed record defeats the ledger's purpose.
+ *
+ * Git-sha resolution failure and ledger-write failures
+ * (`InvalidReleaseRecordError`, `StaleLifecycleBranchError`, or any other
+ * error `appendReleaseRecord`/`pushLifecycle` throw) are reported as `{
+ * recorded: false, reason: "error", error }` rather than propagated — an
+ * auto-recorded ledger write is a best-effort observability side effect of a
+ * successful deploy; it must never turn a successful `chant run --components`
+ * into a failing CLI invocation. The caller should still surface the message
+ * as a warning.
+ */
+export async function maybeRecordAutoRelease(run, options = {}) {
+    if (options.disabled) {
+        return { recorded: false, reason: "opted-out" };
+    }
+    if (!run.success) {
+        return { recorded: false, reason: "run-not-successful" };
+    }
+    const digest = run.digest ?? extractRunDigest(run.records ?? []);
+    if (!digest) {
+        return { recorded: false, reason: "no-digest", detail: `component "${run.component}" published no digest-bearing artifact` };
+    }
+    const actor = resolveActor(options.actor);
+    if (!actor) {
+        return { recorded: false, reason: "no-actor", detail: "could not resolve an actor from GITHUB_ACTOR/GITLAB_USER_LOGIN/USER" };
+    }
+    let gitSha = options.gitSha;
+    try {
+        gitSha ?? (gitSha = await getHeadCommit({ cwd: options.cwd }));
+    }
+    catch (err) {
+        return { recorded: false, reason: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+    const timestamp = new Date().toISOString();
+    try {
+        const { commit, record } = await appendReleaseRecord({
+            component: run.component,
+            env: run.env,
+            digest,
+            gitSha,
+            runId: run.runId,
+            ...(run.runOrigin ? { runOrigin: run.runOrigin } : {}),
+            timestamp,
+            actor,
+            ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
+            ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
+        }, { cwd: options.cwd });
+        await pushLifecycle({ cwd: options.cwd });
+        return { recorded: true, commit, record };
+    }
+    catch (err) {
+        if (err instanceof InvalidReleaseRecordError || err instanceof StaleLifecycleBranchError) {
+            return { recorded: false, reason: "error", error: err.message };
+        }
+        return { recorded: false, reason: "error", error: err instanceof Error ? err.message : String(err) };
+    }
+}

package/dist/components/builders.js

@@ -0,0 +1,47 @@
+/**
+ * Typed step-builder API (#658) — ergonomic sugar over the kind-literal
+ * `Step`/`BuildSpec` contract. `phase("Verify", [healthGate({ path })])`
+ * is exactly `phase("Verify", [{ kind: "health-gate", path }])`, but
+ * with per-verb argument checking and autocomplete from each capability's own
+ * `Input` type. Core exports the agnostic verbs' builders; a lexicon exports
+ * its own (e.g. the aws lexicon's `cfnDeploy`, reusing the exported `step`).
+ *
+ * These are pure projections: a builder returns the same kind-literal the
+ * driver dispatches on (see ./component.ts's `Step`), so the JSON contract
+ * (component.schema.json) stays authoritative and a hand-written or
+ * non-chant-authored component keeps working. The runtime `Capability`
+ * objects live under `*Capability` names (./verbs/*), registered by `.kind`.
+ */
+/**
+ * Build a `(input) => Step` for one deploy verb: tags the input with its
+ * `kind`. Exported so a lexicon's capability plugin (e.g. the aws lexicon,
+ * which owns the `cfn-deploy`/`emr-*`/… builders) can offer the same typed
+ * sugar for its own verbs without re-implementing this projection.
+ */
+export function step(kind) {
+    return (input) => ({ kind, ...input });
+}
+/** Build a `(input) => BuildSpec` for one build verb (the `build` field, not `deploy`). */
+function buildSpec(kind) {
+    return (input) => ({ kind, ...input });
+}
+// ── build family → BuildSpec (the component's `build` field) ─────────────────
+export const dockerBuild = buildSpec("docker-build");
+export const zipPackage = buildSpec("zip-package");
+export const jvmBuild = buildSpec("jvm-build");
+// ── sbom ─────────────────────────────────────────────────────────────────────
+export const generateSbom = step("generate-sbom");
+// ── supply-chain security / policy ───────────────────────────────────────────
+export const sign = step("sign");
+export const attestProvenance = step("attest-provenance");
+export const verify = step("verify");
+export const scanVulnerabilities = step("scan-vulnerabilities");
+export const vulnGate = step("vuln-gate");
+// ── wait / verify (agnostic) ─────────────────────────────────────────────────
+// The cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`)
+// ship as builders from the aws lexicon, alongside their capabilities.
+export const waitClusterHealthy = step("wait-cluster-healthy");
+export const waitEndpoint = step("wait-endpoint");
+export const healthGate = step("health-gate");
+// ── escape hatch ─────────────────────────────────────────────────────────────
+export const shell = step("shell");

package/dist/components/capability-plugin-loader.js

@@ -0,0 +1,175 @@
+/**
+ * Discovery + loading for capability plugins — the capability-side analogue
+ * of ../cli/plugins.ts's `loadPlugin`/`loadPlugins` for lexicons.
+ *
+ * Naming convention mirrors lexicons exactly, substituting "capability" for
+ * "lexicon": a capability plugin package is
+ * `@intentius/chant-capability-<name>` and is expected to export a value
+ * satisfying `CapabilityPlugin` (./capability-plugin.ts), detected at
+ * runtime with `isCapabilityPlugin` — the same dynamic-import + shape-guard
+ * strategy `loadPlugin` uses for `@intentius/chant-lexicon-<name>`.
+ *
+ * `buildCapabilityRegistry` is the Phase 2 replacement for Phase 1's
+ * `createCapabilityRegistry` (./registry.ts): it always loads the built-in
+ * `starterCapabilityPlugin` (./starter-plugin.ts) first — preserving every
+ * Phase 1 kind with zero behavior change — then loads any additional
+ * requested plugin packages on top, registering every capability they
+ * contribute into one `CapabilityRegistry` the driver resolves verbs
+ * through. Duplicate `kind` registration across plugins throws (via
+ * `CapabilityRegistry.register`'s existing guard), the same hard-conflict
+ * discipline `checkConflicts` (../cli/conflict-check.ts) applies to
+ * duplicate lexicon rule IDs.
+ */
+import { CapabilityRegistry } from "./capability.js";
+import { lexiconModulePath, importLexiconPackage } from "../lexicon-module.js";
+import { isCapabilityPlugin } from "./capability-plugin.js";
+import { starterCapabilityPlugin } from "./starter-plugin.js";
+/** Thrown when a dynamically-imported capability package does not satisfy `CapabilityPlugin` — the "malformed capability package" case #559 asks doctor/validation to detect. */
+export class MalformedCapabilityPluginError extends Error {
+    constructor(packageName, reason) {
+        super(`capability plugin package "${packageName}" is malformed: ${reason}`);
+        this.packageName = packageName;
+        this.name = "MalformedCapabilityPluginError";
+    }
+}
+/** Thrown when two loaded capability plugins register the same `kind` — mirrors the lexicon loader's hard rule-ID conflict. */
+export class DuplicateCapabilityKindError extends Error {
+    constructor(kind, plugins) {
+        super(`capability "${kind}" is registered by more than one plugin: ${plugins.join(", ")}`);
+        this.kind = kind;
+        this.plugins = plugins;
+        this.name = "DuplicateCapabilityKindError";
+    }
+}
+/**
+ * Dynamically import and validate a single capability plugin package by
+ * name. Mirrors ../cli/plugins.ts's `loadPlugin` for lexicons: imports
+ * `@intentius/chant-capability-{name}`, scans its exports for a value
+ * satisfying `isCapabilityPlugin`, and throws a descriptive
+ * `MalformedCapabilityPluginError` if the package exists but exports nothing
+ * usable (the malformed-package case), or the original import error if the
+ * package cannot be found at all.
+ */
+export async function loadCapabilityPlugin(name) {
+    const packageName = `@intentius/chant-capability-${name}`;
+    let mod;
+    try {
+        mod = (await importLexiconPackage(packageName));
+    }
+    catch (err) {
+        throw new Error(`capability plugin package "${packageName}" could not be loaded: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    for (const value of Object.values(mod)) {
+        if (isCapabilityPlugin(value)) {
+            return value;
+        }
+    }
+    throw new MalformedCapabilityPluginError(packageName, `does not export a CapabilityPlugin (expected an export with string "name", string "version", and a "capabilities" function)`);
+}
+/**
+ * Load and initialize multiple named capability plugins, in order. Calls
+ * `init()` on each plugin if present — mirrors `loadPlugins`'s lexicon
+ * `init()` hook.
+ */
+export async function loadCapabilityPlugins(names) {
+    const plugins = [];
+    for (const name of names) {
+        const plugin = await loadCapabilityPlugin(name);
+        if (plugin.init) {
+            await plugin.init();
+        }
+        plugins.push(plugin);
+    }
+    return plugins;
+}
+/**
+ * Load the capability plugin a *lexicon* package contributes, if any. A cloud
+ * lexicon (`@intentius/chant-lexicon-<name>`) is the natural home for that
+ * cloud's operational leaves (`cfn-deploy`, `emr-*`, …) — the same seam that
+ * already carries the lexicon's synthesis, `describeResources`, and ownership
+ * markers (docs/components/cloud-boundary). So when a project declares
+ * `lexicons: ["aws"]`, its aws leaves come along automatically: this imports
+ * the lexicon package and returns the first export satisfying
+ * `isCapabilityPlugin`.
+ *
+ * Tolerant by design — a lexicon that contributes *no* capabilities (most do
+ * not yet) simply returns `null` rather than throwing, unlike
+ * `loadCapabilityPlugin`'s strict `@intentius/chant-capability-<name>` contract
+ * where the package's whole reason to exist is the plugin.
+ */
+export async function loadCapabilityPluginFromLexicon(name) {
+    // chant #2520 — a lexicon declared by module path is imported from that path.
+    const packageName = lexiconModulePath(name) ?? `@intentius/chant-lexicon-${name}`;
+    let mod;
+    try {
+        mod = (await importLexiconPackage(packageName));
+    }
+    catch {
+        return null; // lexicon not installed / not resolvable here — nothing to contribute.
+    }
+    for (const value of Object.values(mod)) {
+        if (isCapabilityPlugin(value))
+            return value;
+    }
+    return null; // lexicon present but contributes no capability plugin.
+}
+/** Load the capability plugins contributed by the given lexicons (skipping those that contribute none), initializing each. */
+export async function loadCapabilityPluginsFromLexicons(names) {
+    const plugins = [];
+    for (const name of names) {
+        const plugin = await loadCapabilityPluginFromLexicon(name);
+        if (!plugin)
+            continue;
+        if (plugin.init)
+            await plugin.init();
+        plugins.push(plugin);
+    }
+    return plugins;
+}
+/**
+ * Register every capability every plugin contributes into one registry, in
+ * plugin order. Throws `DuplicateCapabilityKindError` if two plugins
+ * register the same `kind` (via a pre-check, so the error names every
+ * offending plugin rather than surfacing only the second registration
+ * attempt's generic `CapabilityRegistry.register` message).
+ */
+export function registerCapabilityPlugins(registry, plugins) {
+    const owners = new Map();
+    for (const plugin of plugins) {
+        for (const capability of plugin.capabilities()) {
+            const existing = owners.get(capability.kind) ?? [];
+            existing.push(plugin.name);
+            owners.set(capability.kind, existing);
+        }
+    }
+    for (const [kind, pluginNames] of owners) {
+        if (pluginNames.length > 1) {
+            throw new DuplicateCapabilityKindError(kind, pluginNames);
+        }
+    }
+    for (const plugin of plugins) {
+        for (const capability of plugin.capabilities()) {
+            registry.register(capability);
+        }
+    }
+    return registry;
+}
+/**
+ * Build a `CapabilityRegistry` through the Phase 2 plugin contract: always
+ * registers the built-in `starterCapabilityPlugin` first (preserving every
+ * Phase 1 `kind` — see ./starter-plugin.ts), then loads and registers any
+ * additional named plugin packages. This is the Phase 2 entry point;
+ * `createCapabilityRegistry` (./registry.ts) remains available and now
+ * delegates to this same starter plugin, so existing Phase 1 callers (and
+ * the pilots) are unaffected.
+ */
+export async function buildCapabilityRegistry(options = {}) {
+    const registry = new CapabilityRegistry();
+    const plugins = [];
+    if (options.includeStarter !== false) {
+        plugins.push(starterCapabilityPlugin);
+    }
+    plugins.push(...(await loadCapabilityPluginsFromLexicons(options.lexicons ?? [])));
+    plugins.push(...(await loadCapabilityPlugins(options.plugins ?? [])));
+    return registerCapabilityPlugins(registry, plugins);
+}

package/dist/components/capability-plugin-schema.js

@@ -0,0 +1,46 @@
+/**
+ * Zod schema + validation for `CapabilityManifest` (./capability-plugin.ts) —
+ * the capability-side analogue of ../lexicon-schema.ts's
+ * `LexiconManifestSchema`/`validateManifest`. Used to detect a malformed
+ * capability package's manifest (#559 acceptance criteria: "Doctor/validation
+ * covers a malformed capability package") with the same descriptive-error
+ * shape lexicon manifest validation uses.
+ */
+import { z } from "zod";
+const semverRegex = /^\d+\.\d+\.\d+(-[a-zA-Z0-9.]+)?(\+[a-zA-Z0-9.]+)?$/;
+export const CapabilityManifestSchema = z.object({
+    name: z.string().min(1, "manifest name must not be empty"),
+    version: z.string().regex(semverRegex, "version must be valid semver (X.Y.Z)"),
+    chantVersion: z.string().optional(),
+    kinds: z.array(z.string().min(1)).optional(),
+});
+/**
+ * Validate a capability manifest from unknown input (object or JSON string).
+ * Throws a descriptive error on invalid input — mirrors
+ * ../lexicon-schema.ts's `validateManifest`.
+ */
+export function validateCapabilityManifest(data) {
+    if (data === null || data === undefined) {
+        throw new Error("capability manifest data is empty");
+    }
+    if (typeof data === "string") {
+        try {
+            data = JSON.parse(data);
+        }
+        catch (err) {
+            const msg = err instanceof SyntaxError ? err.message : String(err);
+            throw new Error(`invalid JSON in capability manifest: ${msg}`);
+        }
+    }
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        throw new Error("capability manifest must be a JSON object");
+    }
+    const result = CapabilityManifestSchema.safeParse(data);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const path = issue.path.length > 0 ? issue.path.join(".") : undefined;
+        const prefix = path ? `capability manifest field ${path}` : "capability manifest";
+        throw new Error(`${prefix}: ${issue.message}`);
+    }
+    return result.data;
+}

package/dist/components/capability-plugin.js

@@ -0,0 +1,99 @@
+/**
+ * Capability plugin contract — Phase 2 (#559, epic #551).
+ *
+ * Promotes the Phase 1 capability registry convention
+ * (`createCapabilityRegistry`/`STARTER_VERB_FAMILIES`, ./registry.ts) to a
+ * first-class chant plugin contract, mirroring the lexicon plugin contract
+ * (../lexicon.ts, ../cli/plugins.ts) so capabilities become typed,
+ * discoverable packages resolved by `kind`, the same way lexicons are
+ * discovered and resolved by resource type.
+ *
+ * Shape parity with `LexiconPlugin` (../lexicon.ts):
+ *  - `name`/`version` mirror `LexiconManifest.name`/`.version`.
+ *  - `capabilities()` is the required lifecycle method (like a lexicon's
+ *    `serializer`/`generate`/`validate`) every capability package must
+ *    implement — it returns the typed `Capability` instances this package
+ *    contributes, registered by `kind` the same way a lexicon's resource
+ *    types are registered by `resourceType`.
+ *  - `families()`, `init()` are optional extensions, mirroring
+ *    `LexiconPlugin`'s optional `lintRules`/`init`/etc.
+ *  - `isCapabilityPlugin` is the runtime type guard `loadCapabilityPlugin`
+ *    (./capability-plugin-loader.ts) uses to validate a dynamically-imported
+ *    package before trusting it — the same defensive shape check
+ *    `isLexiconPlugin` performs for lexicons.
+ *
+ * The starter verb set (./registry.ts) becomes the built-in, always-loaded
+ * plugin (`starterCapabilityPlugin`, ./starter-plugin.ts) under this same
+ * contract — see that module's docstring for the Phase 1 -> Phase 2
+ * migration path and the "no behavior change" guarantee.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Type guard to check if a value is a `CapabilityPlugin`. Checks for the
+ * required `name`/`version`/`capabilities` shape, the same defensive check
+ * `isLexiconPlugin` (../lexicon.ts) performs before a dynamically-imported
+ * package is trusted and registered. This is also chant's detector for a
+ * *malformed* capability package (#559 acceptance criteria): a package
+ * missing any of these fails the guard and is rejected by the loader with a
+ * descriptive error rather than registered half-working.
+ */
+export function isCapabilityPlugin(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("name" in value) ||
+        typeof value.name !== "string" ||
+        !("version" in value) ||
+        typeof value.version !== "string") {
+        return false;
+    }
+    const obj = value;
+    return typeof obj.capabilities === "function";
+}
+/**
+ * The calling module's own package version, read from the nearest
+ * `package.json` above it (chant #1505).
+ *
+ * `CapabilityPlugin.version` documents itself as the plugin package's semver,
+ * but chant's packages release in lockstep, so a hardcoded literal goes stale
+ * on every `just release` — the aws plugin shipped `"1.0.0"` from the day it
+ * was extracted from the starter set (#681), and the k8s plugin's authoring-
+ * time `"0.41.0"` was stale one release later. Walking up from the module's
+ * own URL survives both the `src/` (development condition) and `dist/`
+ * layouts, and an npm install, without any build-time stamping.
+ *
+ * Returns `"0.0.0"` when no versioned `package.json` is found — a visible
+ * sentinel rather than a guess; nothing gates on the field.
+ *
+ * Call it lazily (from a `get version()` accessor, as the built-in plugins
+ * do), not at module scope: the read touches the filesystem, and a plugin
+ * module must stay importable where `fs` is absent (workerd, chant #1081).
+ * The result is cached per module URL, so the walk happens once.
+ */
+export function ownPackageVersion(moduleUrl) {
+    const cached = ownVersionCache.get(moduleUrl);
+    if (cached !== undefined)
+        return cached;
+    const found = findPackageVersion(moduleUrl);
+    ownVersionCache.set(moduleUrl, found);
+    return found;
+}
+const ownVersionCache = new Map();
+function findPackageVersion(moduleUrl) {
+    let dir = dirname(fileURLToPath(moduleUrl));
+    for (;;) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf-8"));
+            if (typeof pkg.version === "string")
+                return pkg.version;
+        }
+        catch {
+            // No package.json here (or unreadable) — keep walking up.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return "0.0.0";
+        dir = parent;
+    }
+}

package/dist/components/capability.js

@@ -0,0 +1,60 @@
+/**
+ * Capability contract — the typed leaf behavior components compose from.
+ *
+ * A capability is a verb ("docker-build", "cfn-deploy", "wait-steady-state"),
+ * never a noun (never named after the component that happens to use it).
+ * Registered once by `kind`, dispatched by the orchestrator, composed by an
+ * unbounded number of components. See:
+ * https://intentius.io/chant/components/capabilities/
+ *
+ * This module defines the interface and registry only. Verb implementations
+ * live under `./verbs/*` as typed stubs — no cloud calls, no side effects.
+ * Cloud implementations are a later phase (see epic #551, issue #554).
+ */
+/**
+ * Thrown by a stub `run`/`rollback` — the verb is specified and typed but has
+ * no cloud implementation yet. Distinguishes "not implemented" from a runtime
+ * failure so callers (and tests) can assert on it specifically.
+ */
+export class CapabilityNotImplementedError extends Error {
+    constructor(kind) {
+        super(`capability "${kind}" is not implemented`);
+        this.kind = kind;
+        this.name = "CapabilityNotImplementedError";
+    }
+}
+/**
+ * Resolves capabilities by `kind`. One registry instance is the composition
+ * root the orchestrator dispatches through; `createCapabilityRegistry` builds
+ * one pre-seeded with the starter verb set (see `./verbs`).
+ */
+export class CapabilityRegistry {
+    constructor() {
+        this.capabilities = new Map();
+    }
+    /** Register a capability. Throws if `kind` is already registered — a capability is a verb, registered once. */
+    register(capability) {
+        if (this.capabilities.has(capability.kind)) {
+            throw new Error(`capability "${capability.kind}" is already registered`);
+        }
+        this.capabilities.set(capability.kind, capability);
+        return this;
+    }
+    /** Resolve a capability by `kind`. Throws a friendly error listing known kinds if absent. */
+    resolve(kind) {
+        const capability = this.capabilities.get(kind);
+        if (!capability) {
+            const known = [...this.capabilities.keys()].sort().join(", ");
+            throw new Error(`no capability registered for kind "${kind}" (known: ${known})`);
+        }
+        return capability;
+    }
+    /** True if a capability is registered for `kind`. */
+    has(kind) {
+        return this.capabilities.has(kind);
+    }
+    /** All registered kinds, sorted. */
+    kinds() {
+        return [...this.capabilities.keys()].sort();
+    }
+}

package/dist/components/changed-files.js

@@ -0,0 +1,72 @@
+/**
+ * The files a change touched, and the units lexicons own that those files
+ * belong to (#3183).
+ *
+ * `lifecycle affected` judges chant source by diffing what it builds. A unit
+ * that is not chant source, such as a hand-written Terraform root, never
+ * shows in that diff, so a lexicon that owns such units answers from the
+ * changed paths instead (`LexiconPlugin.changedUnits`).
+ */
+import { execFile } from "node:child_process";
+import { posix } from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+async function git(cwd, args) {
+    const { stdout } = await execFileAsync("git", args, { cwd, maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+}
+/**
+ * The commit a change is measured from: the merge base of `base` and `head`.
+ * A pull request's head that branched before `base` moved is measured from
+ * where it branched, so the other changes on `base` are not counted as its
+ * own; a merge commit's first parent is its own merge base.
+ */
+export async function resolveMergeBase(cwd, base, head = "HEAD") {
+    try {
+        return (await git(cwd, ["merge-base", base, head])).trim();
+    }
+    catch (err) {
+        const detail = err.stderr?.trim();
+        throw new Error(`cannot find where ${head} and ${base} meet${detail ? `: ${detail}` : ""}. ` +
+            "Is the base fetched? A CI checkout needs the history (fetch-depth: 0, GIT_DEPTH: 0).");
+    }
+}
+/** The full commit `ref` names. */
+export async function resolveCommit(cwd, ref) {
+    return (await git(cwd, ["rev-parse", "--verify", `${ref}^{commit}`])).trim();
+}
+/**
+ * Files changed between `base` and `head`, relative to `cwd`, with `/`
+ * separators. A rename counts as its old and its new path.
+ *
+ * Every changed file in the repository is listed, not only those under
+ * `cwd`: one outside it reads `../...`. A project in a workspace member
+ * (#3465) can call a module that lives in another member or beside the
+ * members, and a change there reaches it; `changedUnits` decides which of
+ * these paths matter.
+ */
+export async function changedFilesBetween(cwd, base, head = "HEAD") {
+    const prefix = (await git(cwd, ["rev-parse", "--show-prefix"])).trim().replace(/\/+$/, "");
+    const out = await git(cwd, ["diff", "--name-only", "-z", "--no-renames", "--no-relative", base, head]);
+    return out
+        .split("\0")
+        .filter(Boolean)
+        .map((file) => {
+        const rel = posix.relative(prefix, file);
+        return rel === "" ? "." : rel;
+    })
+        .sort();
+}
+/** The union of every plugin's `changedUnits` answer, sorted. */
+export async function lexiconChangedUnits(plugins, ctx) {
+    if (ctx.changedFiles.length === 0)
+        return [];
+    const units = new Set();
+    for (const plugin of plugins) {
+        if (!plugin.changedUnits)
+            continue;
+        for (const unit of await plugin.changedUnits(ctx))
+            units.add(unit);
+    }
+    return [...units].sort();
+}