@intentius/chant 0.13.0 → 0.15.0

package/src/components/auto-release.test.ts

@@ -0,0 +1,217 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import type { DriverStepRecord } from "./driver";
+
+const getHeadCommitMock = vi.fn();
+const pushLifecycleMock = vi.fn();
+const appendReleaseRecordMock = vi.fn();
+
+vi.mock("../lifecycle/git", () => ({
+  getHeadCommit: (...args: unknown[]) => getHeadCommitMock(...args),
+  pushLifecycle: (...args: unknown[]) => pushLifecycleMock(...args),
+  StaleLifecycleBranchError: class StaleLifecycleBranchError extends Error {},
+}));
+
+vi.mock("../lifecycle/release-ledger", async () => {
+  const actual = await vi.importActual<typeof import("../lifecycle/release-ledger")>("../lifecycle/release-ledger");
+  return {
+    ...actual,
+    appendReleaseRecord: (...args: unknown[]) => appendReleaseRecordMock(...args),
+  };
+});
+
+const {
+  maybeRecordAutoRelease,
+  extractRunDigest,
+  extractRunDigestFromPhaseOutputs,
+} = await import("./auto-release");
+
+function publishRecord(digest: string): DriverStepRecord {
+  return { component: "svc", phase: "Publish", kind: "publish-image", status: "ok", durationMs: 5, output: { digest, uri: `repo@${digest}` } };
+}
+
+function applyRecord(): DriverStepRecord {
+  return { component: "svc", phase: "Apply", kind: "cfn-deploy", status: "ok", durationMs: 5, output: { ok: true } };
+}
+
+// A generate-sbom step output: carries the SBOM document's own content `digest`
+// but no location `uri` — must NOT count as a promoted artifact (#665).
+function sbomRecord(digest: string): DriverStepRecord {
+  return { component: "svc", phase: "Sbom", kind: "generate-sbom", status: "ok", durationMs: 5, output: { digest, archivePath: "sbom.spdx.json" } };
+}
+
+describe("extractRunDigest", () => {
+  test("finds the digest from a publish-shaped step output", () => {
+    expect(extractRunDigest([publishRecord("sha256:abc"), applyRecord()])).toBe("sha256:abc");
+  });
+
+  test("returns undefined when no step published a digest", () => {
+    expect(extractRunDigest([applyRecord()])).toBeUndefined();
+  });
+
+  test("ignores failed/skipped steps", () => {
+    const failed: DriverStepRecord = { component: "svc", phase: "Publish", kind: "publish-image", status: "fail", durationMs: 5, error: "boom" };
+    expect(extractRunDigest([failed])).toBeUndefined();
+  });
+
+  test("takes the last digest-bearing output when multiple steps publish", () => {
+    expect(extractRunDigest([publishRecord("sha256:first"), publishRecord("sha256:second")])).toBe("sha256:second");
+  });
+
+  test("ignores an SBOM output's content digest — no uri means nothing was promoted (#665)", () => {
+    expect(extractRunDigest([sbomRecord("sha256:sbombytes")])).toBeUndefined();
+    // an SBOM step alongside a real publish still yields the publish digest, not the SBOM's
+    expect(extractRunDigest([sbomRecord("sha256:sbombytes"), publishRecord("sha256:real")])).toBe("sha256:real");
+  });
+});
+
+describe("extractRunDigestFromPhaseOutputs", () => {
+  test("finds the digest across phase outputs (Temporal workflow result shape)", () => {
+    expect(extractRunDigestFromPhaseOutputs({ Publish: { digest: "sha256:abc", uri: "repo@sha256:abc" }, Apply: { ok: true } })).toBe("sha256:abc");
+  });
+
+  test("returns undefined for undefined/empty phaseOutputs", () => {
+    expect(extractRunDigestFromPhaseOutputs(undefined)).toBeUndefined();
+    expect(extractRunDigestFromPhaseOutputs({})).toBeUndefined();
+  });
+
+  test("ignores a phase output carrying only a content digest (SBOM, #665)", () => {
+    expect(extractRunDigestFromPhaseOutputs({ Sbom: { digest: "sha256:sbombytes" } })).toBeUndefined();
+  });
+});
+
+describe("maybeRecordAutoRelease", () => {
+  beforeEach(() => {
+    getHeadCommitMock.mockReset().mockResolvedValue("abc123headsha");
+    pushLifecycleMock.mockReset().mockResolvedValue(true);
+    appendReleaseRecordMock.mockReset();
+    delete process.env.GITHUB_ACTOR;
+    delete process.env.GITLAB_USER_LOGIN;
+    delete process.env.USER;
+  });
+
+  test("success -> writes exactly one record and pushes", async () => {
+    appendReleaseRecordMock.mockResolvedValue({
+      commit: "a".repeat(40),
+      record: {
+        version: 1, component: "svc", env: "prod", digest: "sha256:abc",
+        gitSha: "abc123headsha", runId: "run-1", timestamp: "2026-01-01T00:00:00.000Z", actor: "alice",
+      },
+    });
+
+    const outcome = await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+      { actor: "alice" },
+    );
+
+    expect(outcome.recorded).toBe(true);
+    expect(appendReleaseRecordMock).toHaveBeenCalledTimes(1);
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input).toMatchObject({ component: "svc", env: "prod", digest: "sha256:abc", gitSha: "abc123headsha", runId: "run-1", actor: "alice" });
+    expect(typeof input.timestamp).toBe("string");
+    expect(pushLifecycleMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("a pre-resolved digest (Temporal path) takes precedence and is used directly", async () => {
+    appendReleaseRecordMock.mockResolvedValue({
+      commit: "b".repeat(40),
+      record: { version: 1, component: "svc", env: "prod", digest: "sha256:temporal", gitSha: "x", runId: "r", timestamp: "t", actor: "a" },
+    });
+
+    await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, digest: "sha256:temporal", records: [publishRecord("sha256:ignored")], runId: "run-1" },
+      { actor: "alice" },
+    );
+
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input.digest).toBe("sha256:temporal");
+  });
+
+  test("failure (run.success = false) -> writes nothing", async () => {
+    const outcome = await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: false, records: [publishRecord("sha256:abc")], runId: "run-1" },
+      { actor: "alice" },
+    );
+    expect(outcome).toEqual({ recorded: false, reason: "run-not-successful" });
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+  });
+
+  test("opt-out (options.disabled) -> writes nothing, even on a successful run with a digest", async () => {
+    const outcome = await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+      { actor: "alice", disabled: true },
+    );
+    expect(outcome).toEqual({ recorded: false, reason: "opted-out" });
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+    expect(getHeadCommitMock).not.toHaveBeenCalled();
+  });
+
+  test("no digest in the run's records -> skipped, not an error", async () => {
+    const outcome = await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [applyRecord()], runId: "run-1" },
+      { actor: "alice" },
+    );
+    expect(outcome).toMatchObject({ recorded: false, reason: "no-digest" });
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("no resolvable actor -> skipped, not an error", async () => {
+    const outcome = await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+    );
+    expect(outcome).toMatchObject({ recorded: false, reason: "no-actor" });
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("falls back to GITHUB_ACTOR/GITLAB_USER_LOGIN/USER when --actor is not passed", async () => {
+    process.env.GITHUB_ACTOR = "octocat";
+    appendReleaseRecordMock.mockResolvedValue({
+      commit: "c".repeat(40),
+      record: { version: 1, component: "svc", env: "prod", digest: "sha256:abc", gitSha: "x", runId: "r", timestamp: "t", actor: "octocat" },
+    });
+
+    await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+    );
+
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input.actor).toBe("octocat");
+  });
+
+  test("git sha resolution failure -> reported as an error result, not thrown", async () => {
+    getHeadCommitMock.mockRejectedValue(new Error("not a git repo"));
+    const outcome = await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+      { actor: "alice" },
+    );
+    expect(outcome).toMatchObject({ recorded: false, reason: "error" });
+    expect(appendReleaseRecordMock).not.toHaveBeenCalled();
+  });
+
+  test("ledger write failure -> reported as an error result, not thrown, and never masks the successful deploy", async () => {
+    appendReleaseRecordMock.mockRejectedValue(new Error("ledger write failed"));
+    const outcome = await expect(maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+      { actor: "alice" },
+    )).resolves.toMatchObject({ recorded: false, reason: "error", error: "ledger write failed" });
+    void outcome;
+    expect(pushLifecycleMock).not.toHaveBeenCalled();
+  });
+
+  test("an explicit gitSha override skips getHeadCommit entirely", async () => {
+    appendReleaseRecordMock.mockResolvedValue({
+      commit: "d".repeat(40),
+      record: { version: 1, component: "svc", env: "prod", digest: "sha256:abc", gitSha: "override-sha", runId: "r", timestamp: "t", actor: "alice" },
+    });
+
+    await maybeRecordAutoRelease(
+      { component: "svc", env: "prod", success: true, records: [publishRecord("sha256:abc")], runId: "run-1" },
+      { actor: "alice", gitSha: "override-sha" },
+    );
+
+    expect(getHeadCommitMock).not.toHaveBeenCalled();
+    const [input] = appendReleaseRecordMock.mock.calls[0];
+    expect(input.gitSha).toBe("override-sha");
+  });
+});

package/src/components/auto-release.ts

@@ -0,0 +1,216 @@
+/**
+ * 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 post-run step for both the local
+ * executor (`runOpComponents`) and the durable Temporal path
+ * (`runComponentTemporal`) 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`.
+ *  - The Temporal workflow (lexicons/temporal/src/component-op/) must stay
+ *    deterministic and replay-safe. A ledger write is a non-idempotent git
+ *    push with real-world side effects (network, `Date.now()`, file writes
+ *    outside workflow state) — precisely what Temporal workflow code must
+ *    never do directly. It happens in the CLI, after `handle.describe()`
+ *    reports a terminal COMPLETED status, the same place `runOpTemporal`
+ *    already writes its deployment report post-run.
+ *
+ * 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";
+import { appendReleaseRecord, InvalidReleaseRecordError, type ReleaseRecord } from "../lifecycle/release-ledger";
+import type { DriverStepRecord } from "./driver";
+
+/**
+ * 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 `findPublishOutput` stays looser (uri/digest/key) because it
+ * only feeds `@<component>.publish.*` wiring, where a false positive is harmless.
+ */
+function isPromotedArtifact(output: unknown): output is { uri: string; digest?: string } {
+  return !!output && typeof output === "object" && "uri" in output && typeof (output as { uri?: unknown }).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: DriverStepRecord[]): string | undefined {
+  let found: string | undefined;
+  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;
+}
+
+/**
+ * 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 function extractRunDigestFromPhaseOutputs(
+  phaseOutputs: Record<string, Record<string, unknown>> | undefined,
+): string | undefined {
+  let found: string | undefined;
+  for (const output of Object.values(phaseOutputs ?? {})) {
+    if (isPromotedArtifact(output) && typeof output.digest === "string") {
+      found = output.digest;
+    }
+  }
+  return found;
+}
+
+/** 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;
+}
+
+function resolveActor(override?: string): string | undefined {
+  return override ?? process.env.GITHUB_ACTOR ?? process.env.GITLAB_USER_LOGIN ?? process.env.USER;
+}
+
+/**
+ * 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 async function maybeRecordAutoRelease(
+  run: AutoReleaseRunInfo,
+  options: AutoReleaseOptions = {},
+): Promise<AutoReleaseResult> {
+  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: string | undefined = options.gitSha;
+  try {
+    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,
+        timestamp,
+        actor,
+      },
+      { 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/src/components/builders.test.ts

@@ -0,0 +1,45 @@
+import { describe, test, expect } from "vitest";
+import { phase, projectToJson, type Component } from "./component";
+import { dockerBuild, jvmBuild, healthGate, waitEndpoint, waitClusterHealthy } from "./builders";
+
+describe("step builders (#658)", () => {
+  test("a step builder tags its input with the verb kind", () => {
+    expect(healthGate({ path: "/healthz" })).toEqual({ kind: "health-gate", path: "/healthz" });
+    expect(waitEndpoint({ url: "http://x/health" })).toEqual({ kind: "wait-endpoint", url: "http://x/health" });
+    expect(waitClusterHealthy({ cluster: "h:7687", size: 1 })).toEqual({
+      kind: "wait-cluster-healthy",
+      cluster: "h:7687",
+      size: 1,
+    });
+  });
+
+  test("build-family builders produce a BuildSpec (for the `build` field)", () => {
+    expect(dockerBuild({ context: ".", into: "archive" })).toEqual({
+      kind: "docker-build",
+      context: ".",
+      into: "archive",
+    });
+    expect(jvmBuild({ tool: "maven", path: ".", into: "archive" })).toEqual({
+      kind: "jvm-build",
+      tool: "maven",
+      path: ".",
+      into: "archive",
+    });
+  });
+
+  test("a component authored with builders projects identically to kind-literals", () => {
+    const built: Component = {
+      name: "svc",
+      dependsOn: [],
+      build: dockerBuild({ context: ".", into: "archive" }),
+      deploy: [phase("Verify", [healthGate({ path: "/healthz" })])],
+    };
+    const literal: Component = {
+      name: "svc",
+      dependsOn: [],
+      build: { kind: "docker-build", context: ".", into: "archive" },
+      deploy: [phase("Verify", [{ kind: "health-gate", path: "/healthz" }])],
+    };
+    expect(projectToJson(built)).toEqual(projectToJson(literal));
+  });
+});

package/src/components/builders.ts

@@ -0,0 +1,71 @@
+/**
+ * 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";
+import type {
+  DockerBuildInput,
+  ZipPackageInput,
+  JvmBuildInput,
+  GenerateSbomInput,
+  SignInput,
+  AttestProvenanceInput,
+  VerifyInput,
+  ScanVulnerabilitiesInput,
+  VulnGateInput,
+  WaitClusterHealthyInput,
+  WaitEndpointInput,
+  HealthGateInput,
+  ShellInput,
+} from "./verbs/index";
+
+/**
+ * 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<In extends object>(kind: string): (input: In) => Step {
+  return (input) => ({ kind, ...input }) as Step;
+}
+
+/** Build a `(input) => BuildSpec` for one build verb (the `build` field, not `deploy`). */
+function buildSpec<In extends object>(kind: string): (input: In) => BuildSpec {
+  return (input) => ({ kind, ...input }) as BuildSpec;
+}
+
+// ── build family → BuildSpec (the component's `build` field) ─────────────────
+export const dockerBuild = buildSpec<DockerBuildInput>("docker-build");
+export const zipPackage = buildSpec<ZipPackageInput>("zip-package");
+export const jvmBuild = buildSpec<JvmBuildInput>("jvm-build");
+
+// ── sbom ─────────────────────────────────────────────────────────────────────
+export const generateSbom = step<GenerateSbomInput>("generate-sbom");
+
+// ── supply-chain security / policy ───────────────────────────────────────────
+export const sign = step<SignInput>("sign");
+export const attestProvenance = step<AttestProvenanceInput>("attest-provenance");
+export const verify = step<VerifyInput>("verify");
+export const scanVulnerabilities = step<ScanVulnerabilitiesInput>("scan-vulnerabilities");
+export const vulnGate = step<VulnGateInput>("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<WaitClusterHealthyInput>("wait-cluster-healthy");
+export const waitEndpoint = step<WaitEndpointInput>("wait-endpoint");
+export const healthGate = step<HealthGateInput>("health-gate");
+
+// ── escape hatch ─────────────────────────────────────────────────────────────
+export const shell = step<ShellInput>("shell");