@intentius/chant 0.13.1 → 0.15.1

package/dist/components/auto-release.d.ts

@@ -0,0 +1,93 @@
+import { type ReleaseRecord } from "../lifecycle/release-ledger.js";
+import type { DriverStepRecord } from "./driver.js";
+/**
+ * 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 declare function extractRunDigest(records: DriverStepRecord[]): string | undefined;
+/**
+ * Same digest extraction as `extractRunDigest`, but over a component
+ * Temporal workflow's returned `phaseOutputs` (`{ [phase]: output }`) instead
+ * of a `DriverStepRecord[]` — the shape `handle.result()` resolves to for a
+ * COMPLETED component workflow (see lexicons/temporal/src/component-op/
+ * serializer.ts's generated `return { phaseOutputs, componentOutputs }`).
+ * Used by the `--temporal` CLI path, which never sees individual step
+ * records (those exist only inside the workflow/activities).
+ */
+export declare function extractRunDigestFromPhaseOutputs(phaseOutputs: Record<string, Record<string, unknown>> | undefined): string | undefined;
+/** Explicit reasons `maybeRecordAutoRelease` declined to write a record — never a thrown error, since "nothing to record" (or "opted out") is an expected, common outcome. */
+export type AutoReleaseSkipReason = "opted-out" | "run-not-successful" | "no-digest" | "no-actor";
+export type AutoReleaseResult = {
+    recorded: true;
+    commit: string;
+    record: ReleaseRecord;
+} | {
+    recorded: false;
+    reason: AutoReleaseSkipReason;
+    detail?: string;
+} | {
+    recorded: false;
+    reason: "error";
+    error: string;
+};
+/** Input describing one component's completed run, common to both the local-executor and Temporal-durable CLI paths. */
+export interface AutoReleaseRunInfo {
+    component: string;
+    env: string;
+    /** Whether the run reported overall success — `DriverRunResult.ok` (local) or a terminal `COMPLETED` Temporal status. A caller must not call this for a non-terminal/in-progress run. */
+    success: boolean;
+    /** The component's step records (local executor), used to locate the published digest via `extractRunDigest`. Mutually exclusive with `digest` — pass whichever the caller already has. */
+    records?: DriverStepRecord[];
+    /** A digest already resolved by the caller (e.g. the `--temporal` path, via `extractRunDigestFromPhaseOutputs` over the workflow's `handle.result()`). Takes precedence over `records` when both are given. */
+    digest?: string;
+    /** Orchestrator run identifier — a Temporal `runId`, or a locally generated id for the local executor (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
+    runId: string;
+}
+/** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
+export interface AutoReleaseOptions {
+    /** `--no-release-record` / `chant.config.ts`'s `release.autoRecord: false` — skip emission entirely. Default: emission is ON. */
+    disabled?: boolean;
+    /** Override the git sha to record (tests, or a caller that already resolved it). Defaults to `git rev-parse HEAD`. */
+    gitSha?: string;
+    /** Override the actor to record. Defaults to `$GITHUB_ACTOR`/`$GITLAB_USER_LOGIN`/`$USER`, matching `runComponentsReleaseRecord`. */
+    actor?: string;
+    /** Working directory for the git plumbing calls (tests). */
+    cwd?: string;
+}
+/**
+ * After a successful `chant run --components <name> --env <env>` (local or
+ * `--temporal`), 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`/`runComponentTemporal`) — 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 declare function maybeRecordAutoRelease(run: AutoReleaseRunInfo, options?: AutoReleaseOptions): Promise<AutoReleaseResult>;
+//# sourceMappingURL=auto-release.d.ts.map

package/dist/components/auto-release.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-release.d.ts","sourceRoot":"","sources":["../../src/components/auto-release.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAkD,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AACjH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAkBjD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,GAAG,SAAS,CAShF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAC9C,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,GAChE,MAAM,GAAG,SAAS,CAQpB;AAED,8KAA8K;AAC9K,MAAM,MAAM,qBAAqB,GAC7B,WAAW,GACX,oBAAoB,GACpB,WAAW,GACX,UAAU,CAAC;AAEf,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,GACzD;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,qBAAqB,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,QAAQ,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,wHAAwH;AACxH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,yLAAyL;IACzL,OAAO,EAAE,OAAO,CAAC;IACjB,2LAA2L;IAC3L,OAAO,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC7B,+MAA+M;IAC/M,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sKAAsK;IACtK,KAAK,EAAE,MAAM,CAAC;CACf;AAED,0JAA0J;AAC1J,MAAM,WAAW,kBAAkB;IACjC,iIAAiI;IACjI,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sHAAsH;IACtH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qIAAqI;IACrI,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,kBAAkB,EACvB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAgD5B"}

package/dist/components/builders.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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`.
+ */
+import type { BuildSpec, Step } from "./component.js";
+import type { DockerBuildInput, ZipPackageInput, JvmBuildInput, GenerateSbomInput, SignInput, AttestProvenanceInput, VerifyInput, ScanVulnerabilitiesInput, VulnGateInput, WaitClusterHealthyInput, WaitEndpointInput, HealthGateInput, ShellInput } from "./verbs/index.js";
+/**
+ * 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 declare function step<In extends object>(kind: string): (input: In) => Step;
+export declare const dockerBuild: (input: DockerBuildInput) => BuildSpec;
+export declare const zipPackage: (input: ZipPackageInput) => BuildSpec;
+export declare const jvmBuild: (input: JvmBuildInput) => BuildSpec;
+export declare const generateSbom: (input: GenerateSbomInput) => Step;
+export declare const sign: (input: SignInput) => Step;
+export declare const attestProvenance: (input: AttestProvenanceInput) => Step;
+export declare const verify: (input: VerifyInput) => Step;
+export declare const scanVulnerabilities: (input: ScanVulnerabilitiesInput) => Step;
+export declare const vulnGate: (input: VulnGateInput) => Step;
+export declare const waitClusterHealthy: (input: WaitClusterHealthyInput) => Step;
+export declare const waitEndpoint: (input: WaitEndpointInput) => Step;
+export declare const healthGate: (input: HealthGateInput) => Step;
+export declare const shell: (input: ShellInput) => Step;
+//# sourceMappingURL=builders.d.ts.map

package/dist/components/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/components/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,SAAS,EACT,qBAAqB,EACrB,WAAW,EACX,wBAAwB,EACxB,aAAa,EACb,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACX,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,KAAK,EAAE,EAAE,KAAK,IAAI,CAEzE;AAQD,eAAO,MAAM,WAAW,+BAL4C,SAKE,CAAC;AACvE,eAAO,MAAM,UAAU,8BAN6C,SAMD,CAAC;AACpE,eAAO,MAAM,QAAQ,4BAP+C,SAOP,CAAC;AAG9D,eAAO,MAAM,YAAY,gCAf6C,IAeF,CAAC;AAGrE,eAAO,MAAM,IAAI,wBAlBqD,IAkB3B,CAAC;AAC5C,eAAO,MAAM,gBAAgB,oCAnByC,IAmBU,CAAC;AACjF,eAAO,MAAM,MAAM,0BApBmD,IAoBrB,CAAC;AAClD,eAAO,MAAM,mBAAmB,uCArBsC,IAqBmB,CAAC;AAC1F,eAAO,MAAM,QAAQ,4BAtBiD,IAsBd,CAAC;AAKzD,eAAO,MAAM,kBAAkB,sCA3BuC,IA2BiB,CAAC;AACxF,eAAO,MAAM,YAAY,gCA5B6C,IA4BF,CAAC;AACrE,eAAO,MAAM,UAAU,8BA7B+C,IA6BR,CAAC;AAG/D,eAAO,MAAM,KAAK,yBAhCoD,IAgCxB,CAAC"}

package/dist/components/capability-plugin-loader.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 type { CapabilityPlugin } from "./capability-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 declare class MalformedCapabilityPluginError extends Error {
+    readonly packageName: string;
+    constructor(packageName: string, reason: string);
+}
+/** Thrown when two loaded capability plugins register the same `kind` — mirrors the lexicon loader's hard rule-ID conflict. */
+export declare class DuplicateCapabilityKindError extends Error {
+    readonly kind: string;
+    readonly plugins: string[];
+    constructor(kind: string, plugins: string[]);
+}
+/**
+ * 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 declare function loadCapabilityPlugin(name: string): Promise<CapabilityPlugin>;
+/**
+ * Load and initialize multiple named capability plugins, in order. Calls
+ * `init()` on each plugin if present — mirrors `loadPlugins`'s lexicon
+ * `init()` hook.
+ */
+export declare function loadCapabilityPlugins(names: string[]): Promise<CapabilityPlugin[]>;
+/**
+ * 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 declare function loadCapabilityPluginFromLexicon(name: string): Promise<CapabilityPlugin | null>;
+/** Load the capability plugins contributed by the given lexicons (skipping those that contribute none), initializing each. */
+export declare function loadCapabilityPluginsFromLexicons(names: string[]): Promise<CapabilityPlugin[]>;
+/**
+ * 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 declare function registerCapabilityPlugins(registry: CapabilityRegistry, plugins: CapabilityPlugin[]): CapabilityRegistry;
+export interface BuildCapabilityRegistryOptions {
+    /**
+     * Additional capability plugin package names to load and register on top
+     * of the built-in starter plugin (e.g. third-party/cloud-specific
+     * capability packages `@intentius/chant-capability-<name>`). Defaults to
+     * none — Phase 1 behavior (just the starter set) is preserved when omitted.
+     */
+    plugins?: string[];
+    /**
+     * Lexicon names (from `chant.config.ts`'s `lexicons`) whose packages may
+     * *also* contribute a capability plugin — the primary way a cloud's
+     * operational leaves are loaded (e.g. `["aws"]` pulls the aws lexicon's
+     * `cfn-deploy`/`emr-*`/… leaves). Lexicons contributing no capabilities are
+     * silently skipped; see `loadCapabilityPluginsFromLexicons`.
+     */
+    lexicons?: string[];
+    /**
+     * Skip loading the built-in starter plugin. Only meaningful for tests that
+     * want a registry seeded purely from explicit `plugins`; real callers
+     * should leave this unset so the Phase 1 verb set is always present.
+     */
+    includeStarter?: boolean;
+}
+/**
+ * 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 declare function buildCapabilityRegistry(options?: BuildCapabilityRegistryOptions): Promise<CapabilityRegistry>;
+//# sourceMappingURL=capability-plugin-loader.d.ts.map

package/dist/components/capability-plugin-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-plugin-loader.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI5D,iLAAiL;AACjL,qBAAa,8BAA+B,SAAQ,KAAK;aAErC,WAAW,EAAE,MAAM;gBAAnB,WAAW,EAAE,MAAM,EACnC,MAAM,EAAE,MAAM;CAKjB;AAED,+HAA+H;AAC/H,qBAAa,4BAA6B,SAAQ,KAAK;aAEnC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM,EAAE;gBADjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE;CAKpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqBlF;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAUxF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,+BAA+B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAYpG;AAED,8HAA8H;AAC9H,wBAAsB,iCAAiC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CASpG;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,gBAAgB,EAAE,GAC1B,kBAAkB,CAqBpB;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,8BAAmC,GAC3C,OAAO,CAAC,kBAAkB,CAAC,CAS7B"}

package/dist/components/capability-plugin-schema.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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";
+import type { CapabilityManifest } from "./capability-plugin.js";
+export declare const CapabilityManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    chantVersion: z.ZodOptional<z.ZodString>;
+    kinds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type CapabilityManifestParsed = z.infer<typeof CapabilityManifestSchema>;
+/**
+ * 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 declare function validateCapabilityManifest(data: unknown): CapabilityManifest;
+//# sourceMappingURL=capability-plugin-schema.d.ts.map

package/dist/components/capability-plugin-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-plugin-schema.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAI9D,eAAO,MAAM,wBAAwB;;;;;iBAKnC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,CA2B5E"}

package/dist/components/capability-plugin.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 type { Capability } from "./capability.js";
+/**
+ * Manifest for a packaged capability plugin — the capability-side analogue
+ * of `LexiconManifest` (../lexicon.ts). Kept as a plain data shape (rather
+ * than folded into `CapabilityPlugin`) so it can be serialized alongside a
+ * package (e.g. into a future tarball/`meta.json`, matching how lexicons
+ * carry `LexiconManifest` in their `BundleSpec`) independent of the runtime
+ * plugin object.
+ */
+export interface CapabilityManifest {
+    /** Package/plugin name (e.g. "aws", "gcp"), not a capability `kind`. */
+    name: string;
+    /** Plugin package version (semver). */
+    version: string;
+    /** Minimum/compatible chant core version, checked the same way as `LexiconManifest.chantVersion` (see ../lexicon-manifest.ts's `checkVersionCompatibility`). */
+    chantVersion?: string;
+    /** Every capability `kind` this plugin contributes — informational/validation aid; must match what `capabilities()` actually returns. */
+    kinds?: string[];
+}
+/**
+ * Plugin interface for capability packages — the capability-side analogue of
+ * `LexiconPlugin` (../lexicon.ts). A capability plugin ships one or more
+ * typed `Capability` implementations, discovered and loaded the same way a
+ * lexicon plugin is: dynamically imported by a package-naming convention
+ * (`@intentius/chant-capability-<name>`, see ./capability-plugin-loader.ts),
+ * validated with a runtime shape guard, then registered into a
+ * `CapabilityRegistry` the driver resolves verbs through by `kind`.
+ *
+ * Required lifecycle method enforces consistency: every capability package
+ * must be able to enumerate the capabilities it contributes.
+ */
+export interface CapabilityPlugin {
+    /** Human-readable plugin/package name (e.g. "aws", "gcp"), not a capability `kind`. */
+    readonly name: string;
+    /** Plugin package version (semver), mirrors `LexiconManifest.version`. */
+    readonly version: string;
+    /** Return every `Capability` this plugin contributes, keyed for registration by its own `kind`. */
+    capabilities(): Array<Capability<never, unknown>>;
+    /** Minimum/compatible chant core version this plugin requires (checked via ../lexicon-manifest.ts's `checkVersionCompatibility`). */
+    readonly chantVersion?: string;
+    /** Capability kinds grouped by family, informational — mirrors `STARTER_VERB_FAMILIES` (./registry.ts) shape for third-party plugins that want to publish the same grouping. */
+    families?(): Record<string, readonly string[]>;
+    /** Optional initialization hook, called once after load (mirrors `LexiconPlugin.init`). */
+    init?(): void | Promise<void>;
+}
+/**
+ * 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 declare function isCapabilityPlugin(value: unknown): value is CapabilityPlugin;
+//# sourceMappingURL=capability-plugin.d.ts.map

package/dist/components/capability-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,gKAAgK;IAChK,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yIAAyI;IACzI,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAE/B,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,mGAAmG;IACnG,YAAY,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;IAGlD,qIAAqI;IACrI,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B,gLAAgL;IAChL,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAE/C,2FAA2F;IAC3F,IAAI,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAa5E"}

package/dist/components/capability.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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).
+ */
+/**
+ * Ambient information a capability's `run`/`rollback` receives, independent of
+ * its typed `input`. Deliberately minimal for this phase: the orchestrator
+ * (interpret-mode driver, #556) will thread through the resolved environment,
+ * a logger, and step-output wiring (`@Phase.output`) once it exists. Kept as
+ * an extensible interface so a later phase can widen it without breaking the
+ * `Capability` signature.
+ */
+export interface DeployContext {
+    /** Target environment name (e.g. "dev", "staging", "prod"). */
+    env: string;
+    /** Component name this run belongs to, for logging/attribution. */
+    component: string;
+    /** Arbitrary environment config resolved by the orchestrator (registry URLs, cluster names, ...). */
+    vars?: Record<string, unknown>;
+}
+/**
+ * A typed leaf behavior. `kind` is the verb string components reference in
+ * their composition (`{ kind: "cfn-deploy", ... }`); `run` performs the
+ * operation; `rollback` is the optional paired compensation the orchestrator
+ * calls, in reverse step order, on saga unwind.
+ *
+ * Typed `In`/`Out` let a composition wire one step's output into the next
+ * step's input (`imageRef: "@Publish.digest"`) and let lint check the wiring
+ * before anything runs.
+ */
+export interface Capability<In = unknown, Out = unknown> {
+    /** The verb this capability implements — e.g. "docker-build", "cfn-deploy". Never a component name. */
+    readonly kind: string;
+    /** Perform the operation. */
+    run(ctx: DeployContext, input: In): Promise<Out>;
+    /** Optional paired compensation, invoked in reverse order on saga rollback. */
+    rollback?(ctx: DeployContext, input: In): Promise<void>;
+    /**
+     * How this verb relates to rollback, for the COMP003 composition check.
+     * Usually derivable and left unset: a capability with a `rollback` method is
+     * treated as `"native"`, everything else as `"none-by-design"` (build/publish/
+     * wait — nothing to compensate). Set it explicitly to `"needs-opt-out"` on a
+     * *mutating* verb that has no rollback and no safe undo (e.g. `s3-sync`,
+     * `run-migration`), so COMP003 requires the component to acknowledge the
+     * compensation gap. See ../lint/rules/comp/comp003-mutating-no-rollback.ts.
+     */
+    readonly rollbackPolicy?: RollbackPolicy;
+}
+/** A capability's relationship to rollback — see `Capability.rollbackPolicy`. */
+export type RollbackPolicy = "native" | "none-by-design" | "needs-opt-out";
+/** Extract a capability's `In` type. */
+export type CapabilityInput<C> = C extends Capability<infer In, unknown> ? In : never;
+/** Extract a capability's `Out` type. */
+export type CapabilityOutput<C> = C extends Capability<unknown, infer Out> ? Out : never;
+/**
+ * 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 declare class CapabilityNotImplementedError extends Error {
+    readonly kind: string;
+    constructor(kind: string);
+}
+/**
+ * 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 declare class CapabilityRegistry {
+    private readonly capabilities;
+    /** Register a capability. Throws if `kind` is already registered — a capability is a verb, registered once. */
+    register<In, Out>(capability: Capability<In, Out>): this;
+    /** Resolve a capability by `kind`. Throws a friendly error listing known kinds if absent. */
+    resolve(kind: string): Capability<never, unknown>;
+    /** True if a capability is registered for `kind`. */
+    has(kind: string): boolean;
+    /** All registered kinds, sorted. */
+    kinds(): string[];
+}
+//# sourceMappingURL=capability.d.ts.map

package/dist/components/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/components/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU,CAAC,EAAE,GAAG,OAAO,EAAE,GAAG,GAAG,OAAO;IACrD,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6BAA6B;IAC7B,GAAG,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACjD,+EAA+E;IAC/E,QAAQ,CAAC,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAED,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE3E,wCAAwC;AACxC,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;AACtF,yCAAyC;AACzC,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC;AAEzF;;;;GAIG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;aAC1B,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAIzC;AAED;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiD;IAE9E,+GAA+G;IAC/G,QAAQ,CAAC,EAAE,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI;IAQxD,6FAA6F;IAC7F,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC;IASjD,qDAAqD;IACrD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,oCAAoC;IACpC,KAAK,IAAI,MAAM,EAAE;CAGlB"}