@intentius/chant 0.13.1 → 0.15.1

package/src/components/verbs/sbom-generator.ts

@@ -0,0 +1,209 @@
+/**
+ * SBOM document type + the injectable, artifact-type-keyed `SbomGenerator`
+ * boundary (#606, epic #551 "Build & deploy observability" follow-up to
+ * #564/#568). Mirrors ./cloud-executor.ts's `CloudExecutor` pattern: a real
+ * backend may shell out to `syft`/`docker buildx --sbom`/`cyclonedx-maven`,
+ * but no test and no default import ever does — every backend here is
+ * injected, and tests construct a `MockSbomGenerator`
+ * (./__tests__/mock-sbom-generator.ts) instead.
+ *
+ * **Format-agnostic by construction.** An SBOM is stored as an opaque typed
+ * doc: `{ format, mediaType, bytes }`. Nothing downstream (the build-archive
+ * manifest, the build ledger, `chant components status`) branches on
+ * `format` — every consumer keys off `mediaType`, the same convention
+ * `BuildArchiveEntry.mediaType` already uses for image/template/asset
+ * entries (./build-archive.ts). SPDX (`application/spdx+json`) and
+ * CycloneDX (`application/vnd.cyclonedx+json`) are both first-class; neither
+ * is hardcoded as *the* format anywhere in this module or its consumers.
+ *
+ * **Default format:** SPDX, matching the epic's refinement from the
+ * devops-cloud.news SBOM article — BuildKit natively emits SPDX attestations
+ * for images, so the image/BuildKit backend defaults to SPDX; the `syft`
+ * backend can emit either and defaults to SPDX here too, for one predictable
+ * default across artifact types. Override via `chant.config.ts`'s
+ * `sbom.format` (see ../../config.ts) and/or a component's own `build.sbom`
+ * (see ../component.ts's `BuildSpec`). Documented in
+ * docs/components/build-archive.mdx.
+ *
+ * **Artifact-type-keyed generation.** "Generate an SBOM" has a different
+ * real implementation per artifact type — an image asks BuildKit or scans
+ * the built image with `syft`; a JAR is scanned with `syft` or
+ * `cyclonedx-maven`; a zip/Lambda package is scanned with `syft`; a bare
+ * source directory is scanned with `syft`/`cdxgen`. `SbomGenerator` is one
+ * interface with one method per artifact type — analogous to
+ * `PublishImageBackend` being one interface satisfied by two backends
+ * (./publish.ts) — so the *capability* (./sbom.ts) stays artifact-type
+ * agnostic and simply calls the method matching the archive entry it was
+ * handed.
+ */
+
+// `lockfileSbomGenerator` (#630's hermetic default, below) lives in
+// ./lockfile-sbom-generator.ts, which itself imports `DEFAULT_SBOM_FORMAT`/
+// `SbomGeneratorNotImplementedError` from *this* module — a deliberate
+// circular import. Safe here because the only use of `lockfileSbomGenerator`
+// in this file is inside `defaultSbomGenerator()`'s function body (evaluated
+// lazily, on first call), never at this module's own top-level/import time,
+// so it doesn't matter which module's evaluation finishes first.
+import { lockfileSbomGenerator } from "./lockfile-sbom-generator";
+
+// ── the SBOM document ────────────────────────────────────────────────────────
+
+/** The two SBOM standards this module supports. Never hardcode one — consumers key off `mediaType`. */
+export type SbomFormat = "spdx" | "cyclonedx";
+
+/** Canonical media type per format, mirroring `BuildArchiveEntry.mediaType`'s convention (./build-archive.ts). */
+export const SBOM_MEDIA_TYPES: Record<SbomFormat, string> = {
+  spdx: "application/spdx+json",
+  cyclonedx: "application/vnd.cyclonedx+json",
+};
+
+/** Project-wide default SBOM format when neither `chant.config.ts`'s `sbom.format` nor a component's `build.sbom.format` says otherwise. Documented in docs/components/build-archive.mdx. */
+export const DEFAULT_SBOM_FORMAT: SbomFormat = "spdx";
+
+/**
+ * The artifact types an `SbomGenerator` backend can be asked to scan —
+ * mirrors the build-family's artifact shapes (`docker-build` -> `image`,
+ * `jvm-build` -> `jar`, `zip-package` -> `zip`, a bare source tree -> `dir`),
+ * never a component/cloud name.
+ */
+export type SbomArtifactType = "image" | "jar" | "zip" | "dir";
+
+/**
+ * An SBOM as an opaque typed document: format, its media type (what every
+ * consumer actually keys off), and the serialized bytes. Never inspected or
+ * re-parsed by chant itself — chant's job is to generate, store, and surface
+ * it, not to interpret SBOM content (that is the scan-result/VEX policy-gate
+ * fast-follow, out of scope here — see #606's "out of scope" section).
+ */
+export interface SbomDocument {
+  /** Which standard this document is. Informational — consumers should key off `mediaType`, not this field, for anything that dispatches on the wire format. */
+  format: SbomFormat;
+  /** The document's IANA/OCI media type (`application/spdx+json` or `application/vnd.cyclonedx+json`). This is the format-agnostic key every consumer (build-archive manifest, build ledger, `chant components status`) actually reads. */
+  mediaType: string;
+  /** Serialized SBOM content (the actual SPDX/CycloneDX JSON document, as bytes/string). */
+  bytes: string;
+  /** Number of packages/components the SBOM enumerates, when the generator reports it — surfaced by `chant components status` without parsing `bytes`. */
+  packageCount?: number;
+  /** Which tool produced this document (e.g. "syft", "buildkit", "cyclonedx-maven") — surfaced alongside format/package count so `chant components status` can report SBOM *source*, not just presence. */
+  generator: string;
+}
+
+// ── per-artifact-type generator inputs ───────────────────────────────────────
+
+export interface GenerateImageSbomInput {
+  /** Archive-relative or local path to the image tarball (OCI layout, as `docker save` produces — see ./build.ts's `DockerBuildOutput.archivePath`). */
+  imagePath: string;
+  /** Image digest the SBOM is being generated for (the join key with the build-archive manifest / build ledger). */
+  digest: string;
+  format?: SbomFormat;
+}
+
+export interface GenerateJarSbomInput {
+  /** Path to the built jar (see ./build.ts's `JvmBuildOutput.archivePath`). */
+  jarPath: string;
+  digest: string;
+  format?: SbomFormat;
+}
+
+export interface GenerateZipSbomInput {
+  /** Path to the built zip/Lambda package (see ./build.ts's `ZipPackageOutput.archivePath`). */
+  zipPath: string;
+  digest: string;
+  format?: SbomFormat;
+}
+
+export interface GenerateDirSbomInput {
+  /** Source directory to scan (a config-only/producer component with no packaged artifact, or a pre-build source scan). */
+  path: string;
+  format?: SbomFormat;
+}
+
+/**
+ * Injectable, artifact-type-keyed SBOM generation boundary — the SBOM-side
+ * analogue of `CloudExecutor` (./cloud-executor.ts). A real implementation
+ * shells out (BuildKit `docker buildx build --sbom=true`/`syft <target>
+ * -o spdx-json`/`cyclonedx-maven`/`cdxgen`); every method here is injected so
+ * tests substitute `MockSbomGenerator`
+ * (./__tests__/mock-sbom-generator.ts) and never invoke a real tool or the
+ * network.
+ */
+export interface SbomGenerator {
+  /** Generate (or attest) an SBOM for a built container image. A real implementation may prefer BuildKit's native `--sbom` attestation (defaults to SPDX, per the epic's refinement) or fall back to a `syft` scan of the saved tarball. */
+  forImage(input: GenerateImageSbomInput): Promise<SbomDocument>;
+  /** Generate an SBOM for a built JVM jar (`syft`/`cyclonedx-maven`). */
+  forJar(input: GenerateJarSbomInput): Promise<SbomDocument>;
+  /** Generate an SBOM for a built zip/Lambda deployment package (`syft` on the archive). */
+  forZip(input: GenerateZipSbomInput): Promise<SbomDocument>;
+  /** Generate an SBOM for a bare source directory (`syft`/`cdxgen`). */
+  forDir(input: GenerateDirSbomInput): Promise<SbomDocument>;
+}
+
+/**
+ * Thrown by `NotImplementedSbomGenerator` — the "no real backend wired yet"
+ * signal, matching `CapabilityNotImplementedError`'s role for verb stubs
+ * (../capability.ts). Kept distinct from a generic `Error` so callers (and
+ * tests) can assert on it specifically.
+ */
+export class SbomGeneratorNotImplementedError extends Error {
+  constructor(public readonly method: string) {
+    super(
+      `SbomGenerator.${method} has no real implementation configured — inject a real generator ` +
+        `(shelling out to syft/buildx/cyclonedx-maven/cdxgen) or use a mock in tests`,
+    );
+    this.name = "SbomGeneratorNotImplementedError";
+  }
+}
+
+/**
+ * All-throwing `SbomGenerator`: every method throws
+ * `SbomGeneratorNotImplementedError`. No longer the process-wide default (see
+ * `defaultSbomGenerator` below, #630) — kept exported for callers that
+ * deliberately want the loud, no-backend-at-all behavior (e.g. a test
+ * asserting on the thrown error itself, or a caller that wants to force
+ * "nothing is wired" rather than silently getting the hermetic backend).
+ */
+export const notImplementedSbomGenerator: SbomGenerator = {
+  async forImage(): Promise<SbomDocument> {
+    throw new SbomGeneratorNotImplementedError("forImage");
+  },
+  async forJar(): Promise<SbomDocument> {
+    throw new SbomGeneratorNotImplementedError("forJar");
+  },
+  async forZip(): Promise<SbomDocument> {
+    throw new SbomGeneratorNotImplementedError("forZip");
+  },
+  async forDir(): Promise<SbomDocument> {
+    throw new SbomGeneratorNotImplementedError("forDir");
+  },
+};
+
+/** Lazily-constructed process-wide default, mirroring ./cloud-executor.ts's `defaultCloudExecutor`. */
+let defaultGenerator: SbomGenerator | undefined;
+
+/**
+ * The default `SbomGenerator` the `generate-sbom` capability falls back to
+ * when none is supplied.
+ *
+ * **Hermetic by default (#630).** This is `./lockfile-sbom-generator.ts`'s
+ * `lockfileSbomGenerator` — `forDir`/`forZip`/`forJar` parse a
+ * `package-lock.json`/`pom.xml` already on disk (no `syft`, no network, no
+ * external tool) and emit a real SPDX/CycloneDX document. That means a
+ * newcomer composing `generate-sbom` over a source directory, a zip/Lambda
+ * package, or a JAR gets a working SBOM the moment they `chant run
+ * --components`, with nothing to install first — the whole point of #630's
+ * "runnable proof" bar. `forImage` still throws
+ * `SbomGeneratorNotImplementedError`: no hermetic backend can see an image's
+ * base layers, so an image SBOM still needs the real deep-scan tool backend
+ * (`syft`/`docker buildx --sbom`/`cyclonedx-maven`/`cdxgen`, #610) — a
+ * documented, deliberate gap, not an oversight. This was previously
+ * `notImplementedSbomGenerator` (every method throwing); switching the
+ * default is intentional per #630 — the prior "loud failure by default"
+ * traded newcomer runnability for a default nobody exercised without opting
+ * in, which #613 already built a hermetic backend to fix but never wired up.
+ * A project that truly wants the old all-throwing behavior can construct
+ * `createGenerateSbomCapability(notImplementedSbomGenerator)` explicitly.
+ */
+export function defaultSbomGenerator(): SbomGenerator {
+  if (!defaultGenerator) defaultGenerator = lockfileSbomGenerator;
+  return defaultGenerator;
+}

package/src/components/verbs/sbom.test.ts

@@ -0,0 +1,184 @@
+import { describe, expect, it } from "vitest";
+import { createGenerateSbomCapability } from "./sbom";
+import { createMockSbomGenerator } from "./__tests__/mock-sbom-generator";
+import { addArchiveTemplate } from "./build";
+import { findArchiveEntry, findSbomForSubject } from "./build-archive";
+import { DEFAULT_SBOM_FORMAT, SBOM_MEDIA_TYPES } from "./sbom-generator";
+
+const ctx = { env: "dev", component: "search-service" };
+
+describe("generate-sbom (#606)", () => {
+  it("defaults to SPDX when no format is requested", async () => {
+    expect(DEFAULT_SBOM_FORMAT).toBe("spdx");
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    const output = await capability.run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+    });
+
+    expect(output.sbom.format).toBe("spdx");
+    expect(output.sbom.mediaType).toBe("application/spdx+json");
+  });
+
+  it("dispatches image artifacts to forImage (BuildKit/syft)", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    await capability.run(ctx, { artifactType: "image", path: "archive/search.tar", digest: "sha256:image1" });
+
+    expect(mock.calls.map((c) => c.method)).toEqual(["forImage"]);
+    expect(mock.calls[0]!.args).toMatchObject({ imagePath: "archive/search.tar", digest: "sha256:image1" });
+  });
+
+  it("dispatches jar artifacts to forJar (syft/cyclonedx-maven)", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    const output = await capability.run(ctx, {
+      artifactType: "jar",
+      path: "archive/lib.jar",
+      digest: "sha256:jar1",
+      format: "cyclonedx",
+    });
+
+    expect(mock.calls.map((c) => c.method)).toEqual(["forJar"]);
+    expect(output.sbom.format).toBe("cyclonedx");
+    expect(output.sbom.mediaType).toBe("application/vnd.cyclonedx+json");
+  });
+
+  it("dispatches zip artifacts to forZip (syft on the archive)", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    await capability.run(ctx, { artifactType: "zip", path: "archive/fn.zip", digest: "sha256:zip1" });
+
+    expect(mock.calls.map((c) => c.method)).toEqual(["forZip"]);
+    expect(mock.calls[0]!.args).toMatchObject({ zipPath: "archive/fn.zip" });
+  });
+
+  it("dispatches dir artifacts to forDir (syft/cdxgen) — no artifact digest required", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    const output = await capability.run(ctx, { artifactType: "dir", path: "src/" });
+
+    expect(mock.calls.map((c) => c.method)).toEqual(["forDir"]);
+    expect(mock.calls[0]!.args).toMatchObject({ path: "src/" });
+    expect(output.manifest.contents[0]!.subjectDigest).toBeUndefined();
+  });
+
+  it("writes an sbom-kind entry into the build-archive manifest, linked to the subject digest", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    const output = await capability.run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+    });
+
+    expect(output.manifest.component).toBe("search-service");
+    const entry = findArchiveEntry(output.manifest, output.archivePath);
+    expect(entry).toMatchObject({
+      kind: "sbom",
+      digest: output.digest,
+      mediaType: SBOM_MEDIA_TYPES.spdx,
+      subjectDigest: "sha256:image1",
+    });
+    expect(findSbomForSubject(output.manifest, "sha256:image1")).toBe(entry);
+  });
+
+  it("defaults the archive path to <artifact path>.sbom.json", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+    const output = await capability.run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+    });
+    expect(output.archivePath).toBe("archive/search.tar.sbom.json");
+  });
+
+  it("accepts an explicit `into` path", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+    const output = await capability.run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+      into: "sbom/search.spdx.json",
+    });
+    expect(output.archivePath).toBe("sbom/search.spdx.json");
+  });
+
+  it("accepts an archive: wiring reference the same way publish-image's from does", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+    await capability.run(ctx, { artifactType: "image", path: "archive:search.tar", digest: "sha256:image1" });
+    expect(mock.calls[0]!.args).toMatchObject({ imagePath: "search.tar" });
+  });
+
+  it("accumulates onto a manifest threaded through from a prior build/template step", async () => {
+    const mock = createMockSbomGenerator();
+    const capability = createGenerateSbomCapability(mock.generator);
+
+    const { manifest: templateManifest } = addArchiveTemplate({
+      path: "search.template.json",
+      content: JSON.stringify({ Resources: {} }),
+    });
+    const output = await capability.run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+      manifest: templateManifest,
+    });
+
+    expect(output.manifest.contents.map((e) => e.kind).sort()).toEqual(["sbom", "template"]);
+  });
+
+  it("surfaces package count and generator name from the SbomDocument onto the archive entry", async () => {
+    const mock = createMockSbomGenerator({ packageCount: 42, generatorName: "syft-1.2.3" });
+    const capability = createGenerateSbomCapability(mock.generator);
+    const output = await capability.run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+    });
+    const entry = findArchiveEntry(output.manifest, output.archivePath)!;
+    expect(entry.packageCount).toBe(42);
+    expect(entry.generator).toBe("syft-1.2.3");
+  });
+
+  it("two generations from identical inputs produce the same manifest digest (content-addressed)", async () => {
+    const mockA = createMockSbomGenerator();
+    const mockB = createMockSbomGenerator();
+    const outputA = await createGenerateSbomCapability(mockA.generator).run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+    });
+    const outputB = await createGenerateSbomCapability(mockB.generator).run(ctx, {
+      artifactType: "image",
+      path: "archive/search.tar",
+      digest: "sha256:image1",
+    });
+    expect(outputA.digest).toBe(outputB.digest);
+    expect(outputA.manifest.manifestDigest).toBe(outputB.manifest.manifestDigest);
+  });
+
+  it("surfaces a generation failure (e.g. scanner crash) as a rejected promise (never swallowed)", async () => {
+    const mock = createMockSbomGenerator({ fail: true });
+    const capability = createGenerateSbomCapability(mock.generator);
+    await expect(
+      capability.run(ctx, { artifactType: "image", path: "archive/search.tar", digest: "sha256:image1" }),
+    ).rejects.toThrow(/sbom generation failed/);
+  });
+
+  it("declares no rollback — an already-generated, content-addressed SBOM is not itself something to undo", () => {
+    const capability = createGenerateSbomCapability(createMockSbomGenerator().generator);
+    expect(capability.rollback).toBeUndefined();
+  });
+});

package/src/components/verbs/sbom.ts

@@ -0,0 +1,152 @@
+/**
+ * `generate-sbom` capability (#606, epic #551 follow-up to #564's build
+ * archive / #568's build ledger — closes the "produce" side #568 explicitly
+ * deferred).
+ *
+ * One capability, artifact-type-keyed via the injectable `SbomGenerator`
+ * (./sbom-generator.ts — mirrors ./cloud-executor.ts's `CloudExecutor`
+ * pattern), so a build-producing component of *any* artifact type — image,
+ * JAR, zip/Lambda package, or a bare source directory for a config-only
+ * producer — generates its SBOM through the same verb. Never docker-only:
+ * dispatch is on `input.artifactType`, not on which build capability
+ * produced the artifact.
+ *
+ * Writes the result into the build-archive manifest as an `sbom`-kind entry
+ * (../verbs/build-archive.ts), content-addressed and linked to its subject
+ * artifact's digest via `subjectDigest` — the **universal home** for the
+ * SBOM regardless of artifact type or registry availability. Registering the
+ * SBOM as an OCI referrer for image artifacts at publish time is a separate,
+ * later concern (the publish step/registry tooling's job, see
+ * ../../lifecycle/build-ledger.ts's `ReferrerLookup` for the consume side);
+ * this capability only ever writes the archive-carried copy, so it works
+ * unconditionally — including the registry-less `load-image-on-host` path.
+ *
+ * Config-only / infra components have no built artifact and simply never
+ * compose this step into their `deploy`/`build` phase — "skips cleanly" is
+ * structural (no step to run), not a special case this module needs to
+ * detect. Opt-out is the same: a component that wants no SBOM omits the
+ * `generate-sbom` step from its composition.
+ */
+
+import type { Capability } from "../capability";
+import {
+  addArchiveEntry,
+  archiveRelativePath,
+  contentDigest,
+  createBuildArchiveManifest,
+  type BuildArchiveManifest,
+} from "./build-archive";
+import {
+  defaultSbomGenerator,
+  DEFAULT_SBOM_FORMAT,
+  type SbomArtifactType,
+  type SbomDocument,
+  type SbomFormat,
+  type SbomGenerator,
+} from "./sbom-generator";
+
+// ── generate-sbom ────────────────────────────────────────────────────────────
+
+export interface GenerateSbomInput {
+  /** Which artifact type to generate an SBOM for — selects the `SbomGenerator` method dispatched to (image -> BuildKit/syft, jar -> syft/cyclonedx-maven, zip -> syft, dir -> syft/cdxgen). */
+  artifactType: SbomArtifactType;
+  /** Archive-relative (or local, for `dir`) path to the artifact being scanned — the archive entry's `path` for `image`/`jar`/`zip`, or a source directory for `dir`. An `archive:`-prefixed reference is accepted and stripped, matching `publish-image`'s `from` convention. */
+  path: string;
+  /** Digest of the artifact this SBOM describes (the `image`/`asset` archive entry's `digest`) — omitted for `dir` scans that precede any build (no artifact digest exists yet), in which case the SBOM entry's `subjectDigest` is left unset. */
+  digest?: string;
+  /** SBOM format to request. Defaults to `chant.config.ts`'s `sbom.format`, then `DEFAULT_SBOM_FORMAT` (SPDX) when neither this input nor project config says otherwise — see ./sbom-generator.ts. */
+  format?: SbomFormat;
+  /** Where the SBOM document is written inside the build archive (e.g. `"search.sbom.json"`). Defaults to `<path>.sbom.json`. */
+  into?: string;
+  /** Manifest to extend with this SBOM's entry, rather than starting a fresh one — the same accumulation convention `docker-build`'s `manifest` input uses (./build.ts), so a component's whole build phase (image + SBOM, or JAR + SBOM) shares one manifest. */
+  manifest?: BuildArchiveManifest;
+}
+
+export interface GenerateSbomOutput {
+  /** The generated SBOM document (format, media type, bytes, package count, generator) — see ./sbom-generator.ts. */
+  sbom: SbomDocument;
+  /** Where the SBOM was written inside the build archive. */
+  archivePath: string;
+  /** Content-addressed digest of the SBOM document's own bytes. */
+  digest: string;
+  /** The build archive's manifest, now including this SBOM's entry alongside whatever `input.manifest` already held. */
+  manifest: BuildArchiveManifest;
+}
+
+/** Default archive path for a generated SBOM when `into` is omitted: `<artifact path>.sbom.json`. */
+function defaultSbomPath(artifactPath: string): string {
+  return `${archiveRelativePath(artifactPath)}.sbom.json`;
+}
+
+/**
+ * Dispatch one `SbomGenerator` call by `artifactType` — the only place this
+ * capability branches on artifact type, matching how `selectPublishBackend`
+ * (./publish.ts) is the only place the publish family branches on backend
+ * kind. Never a component/cloud name, always an artifact shape.
+ */
+async function generate(
+  generator: SbomGenerator,
+  input: GenerateSbomInput,
+  artifactPath: string,
+): Promise<SbomDocument> {
+  switch (input.artifactType) {
+    case "image":
+      return generator.forImage({ imagePath: artifactPath, digest: input.digest ?? "", format: input.format });
+    case "jar":
+      return generator.forJar({ jarPath: artifactPath, digest: input.digest ?? "", format: input.format });
+    case "zip":
+      return generator.forZip({ zipPath: artifactPath, digest: input.digest ?? "", format: input.format });
+    case "dir":
+      return generator.forDir({ path: artifactPath, format: input.format });
+  }
+}
+
+/**
+ * Generate an SBOM for a build-producing component's artifact (image, JAR,
+ * zip, or source directory) via the artifact-type-keyed `SbomGenerator`, and
+ * fold the result into the build-archive manifest as an `sbom`-kind entry
+ * linked to the subject artifact's digest. Format defaults to
+ * `DEFAULT_SBOM_FORMAT` (SPDX) when neither `input.format` nor the injected
+ * generator overrides it — see ./sbom-generator.ts's module doc for the
+ * full default-resolution story. `chant.config.ts`'s `sbom.format` (see
+ * ../../config.ts's `ChantConfig.sbom` and `resolveSbomFormat`) is resolved
+ * by the caller/orchestrator into `input.format` before this capability
+ * runs, the same way env config is resolved before any other capability's
+ * `run` (this module never imports ../../config.ts directly, matching how
+ * no other verb module does either).
+ *
+ * No rollback: an already-generated SBOM sitting in the archive (or, later,
+ * projected as a registry referrer) is immutable, content-addressed
+ * evidence — nothing to compensate, the same opt-out `docker-build` and
+ * `publish-image` already take for their own no-mutable-remote-state reason.
+ */
+export function createGenerateSbomCapability(
+  generator: SbomGenerator = defaultSbomGenerator(),
+): Capability<GenerateSbomInput, GenerateSbomOutput> {
+  return {
+    kind: "generate-sbom",
+    async run(ctx, input) {
+      const artifactPath = archiveRelativePath(input.path);
+      const format = input.format ?? DEFAULT_SBOM_FORMAT;
+      const sbom = await generate(generator, { ...input, format }, artifactPath);
+
+      const into = input.into ?? defaultSbomPath(input.path);
+      const digest = contentDigest(sbom.bytes);
+      const base = input.manifest ?? createBuildArchiveManifest(ctx.component);
+      const manifest = addArchiveEntry(base, {
+        kind: "sbom",
+        path: into,
+        digest,
+        mediaType: sbom.mediaType,
+        subjectDigest: input.digest,
+        packageCount: sbom.packageCount,
+        generator: sbom.generator,
+      });
+
+      return { sbom, archivePath: into, digest, manifest };
+    },
+  };
+}
+
+/** Default `generate-sbom` capability, backed by the process-wide default `SbomGenerator` (throws until a real backend is injected — see ./sbom-generator.ts's `notImplementedSbomGenerator`). */
+export const generateSbomCapability: Capability<GenerateSbomInput, GenerateSbomOutput> = createGenerateSbomCapability();

package/src/components/verbs/shell.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest";
+import { createShellCapability } from "./shell";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "dev", component: "svc" };
+
+describe("shell (#557)", () => {
+  it("runs the command and returns its stdout with exit 0", async () => {
+    const mock = createMockProcessRunner({ responses: { "echo hi": "hi\n" } });
+    const out = await createShellCapability(mock.runner).run(ctx, { cmd: "echo hi", reason: "demo" });
+    expect(out).toEqual({ stdout: "hi\n", exitCode: 0 });
+    expect(mock.calls.at(-1)?.command).toBe("echo hi");
+  });
+
+  it("prefixes env vars and passes cwd through", async () => {
+    const mock = createMockProcessRunner();
+    await createShellCapability(mock.runner).run(ctx, {
+      cmd: "deploy.sh",
+      cwd: "/app",
+      env: { FOO: "bar" },
+      reason: "vendor CLI not yet wrapped by a capability",
+    });
+    const call = mock.calls.at(-1)!;
+    expect(call.command).toBe("env FOO='bar' deploy.sh");
+    expect(call.options?.cwd).toBe("/app");
+  });
+
+  it("rejects when the command exits non-zero (surfaces the tool's error)", async () => {
+    const mock = createMockProcessRunner({ failures: { "bad-cmd": "boom" } });
+    await expect(createShellCapability(mock.runner).run(ctx, { cmd: "bad-cmd", reason: "x" })).rejects.toThrow("boom");
+  });
+
+  it("declares no rollback — an escape-hatch shell owns its own compensation", () => {
+    expect(createShellCapability(createMockProcessRunner().runner).rollback).toBeUndefined();
+  });
+});

package/src/components/verbs/shell.ts

@@ -0,0 +1,51 @@
+/**
+ * escape hatch family — `shell`. Typed, but flagged: a raw shell step run by
+ * exactly one component is the "capability-per-component" smell the model
+ * exists to avoid (see docs/components/capabilities.mdx#the-discipline).
+ * `reason` is required so lint (COMP006) can flag an escape hatch used without
+ * a stated justification.
+ */
+
+import type { Capability } from "../capability";
+import { defaultProcessRunner, q, type ProcessRunner } from "./process-runner";
+
+export interface ShellInput {
+  /** Command to run. */
+  cmd: string;
+  /** Working directory. Default: process cwd. */
+  cwd?: string;
+  /** Additional environment variables. */
+  env?: Record<string, string>;
+  /** Required justification for reaching past the capability set — lint-checked. */
+  reason: string;
+}
+
+export interface ShellOutput {
+  /** Captured stdout. */
+  stdout: string;
+  /** Process exit code. Always 0 on success — a non-zero exit rejects the run. */
+  exitCode: number;
+}
+
+/**
+ * Run an arbitrary shell command through the injectable {@link ProcessRunner}.
+ * The escape hatch — typed, lint-flagged, and requires a `reason`. A non-zero
+ * exit rejects (with the command's own stderr), failing the step like any other
+ * capability error, so `onFailure`/rollback fires.
+ */
+export function createShellCapability(processRunner: ProcessRunner = defaultProcessRunner()): Capability<ShellInput, ShellOutput> {
+  return {
+    kind: "shell",
+    async run(_ctx, input) {
+      const envPrefix =
+        input.env && Object.keys(input.env).length > 0
+          ? `env ${Object.entries(input.env).map(([k, v]) => `${k}=${q(v)}`).join(" ")} `
+          : "";
+      const { stdout } = await processRunner.run(`${envPrefix}${input.cmd}`, { cwd: input.cwd });
+      return { stdout, exitCode: 0 };
+    },
+  };
+}
+
+/** Default `shell` capability, backed by the real process runner. */
+export const shellCapability: Capability<ShellInput, ShellOutput> = createShellCapability();