@intentius/chant 0.13.1 → 0.15.1

package/dist/components/presets/lambda.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Preset: `LambdaComponent` (#566, epic #551 §"6. Presets (Level 2 reuse)").
+ *
+ * The named-composition builder for the container-image Lambda shape
+ * (`../pilots/lambda.pilot.ts`): `docker-build` -> `publish-image` ->
+ * `lambda-deploy` -> `health-gate` against the function's alias. Distinct
+ * from `EcsFargateComponent`'s apply family on purpose — no CloudFormation
+ * stack in Apply at all, matching the pilot's documented "first pilot whose
+ * Apply phase contains no cfn-deploy" shape.
+ */
+import type { Component } from "../component.js";
+export interface LambdaComponentConfig {
+    /** Component name (kebab-case) — becomes both the component's `name` and, by default, the Lambda function name. */
+    name: string;
+    /** Lambda function name. Default: `name`. */
+    functionName?: string;
+    /** Docker build context. Default: ".". */
+    context?: string;
+    /** Alias to repoint at the new version after publish. Default: "live". */
+    alias?: string;
+    /** Destination registry `publish-image` promotes to. Default: `"$env.registry"`. */
+    registry?: string;
+    /** Other components that must complete first. */
+    dependsOn?: string[];
+}
+/**
+ * Expand a container-image AWS Lambda function to its standard
+ * Publish/Apply/Verify composition — the reference shape
+ * `lambda.pilot.ts` hand-composes. Reuses `docker-build`/`publish-image`
+ * unchanged from `EcsFargateComponent`'s build axis (build + promote-by-digest
+ * is identical for a container-image Lambda); only the apply/verify shape
+ * differs.
+ */
+export declare function LambdaComponent(config: LambdaComponentConfig): Component;
+//# sourceMappingURL=lambda.d.ts.map

package/dist/components/presets/lambda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lambda.d.ts","sourceRoot":"","sources":["../../../src/components/presets/lambda.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,MAAM,WAAW,qBAAqB;IACpC,mHAAmH;IACnH,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,SAAS,CAexE"}

package/dist/components/presets/single-host-compose.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Preset: `SingleHostComposeComponent` (#566, epic #551 §"6. Presets (Level 2
+ * reuse)").
+ *
+ * The named-composition builder for the registry-less single-host Docker
+ * Compose shape (`../__fixtures__/single-host-compose.json`): `docker-build`
+ * -> `load-image-on-host` (registry-free promotion, see
+ * ../verbs/publish.ts's `load-image-on-host` docstring) -> `copy-to-host` the
+ * compose file -> `remote-exec` a `docker compose up -d` -> `wait-endpoint`
+ * against the service's health path. This is the N=1 case of the fan-out
+ * shape `neo4j-fanout.pilot.ts` composes by hand at N=3 — single-host compose
+ * and a host fleet are the same composition shape at different N (see
+ * docs/components/composition-and-wiring.mdx#fan-out-is-composition-not-orchestrator-knowledge).
+ */
+import type { Component } from "../component.js";
+export interface SingleHostComposeComponentConfig {
+    /** Component name (kebab-case). */
+    name: string;
+    /** Docker build context. Default: ".". */
+    context?: string;
+    /** Path to the compose file inside the archive. Default: "archive:compose.yaml". */
+    composeFile?: string;
+    /** Destination path for the compose file on the host. Default: `/opt/<name>/compose.yaml`. */
+    hostComposePath?: string;
+    /** Target host (SSM instance id, hostname, or host group). Default: `"$env.host"`. */
+    host?: string;
+    /** Health check path polled after `docker compose up -d`. */
+    healthPath: string;
+    /** Port the health check listens on. */
+    healthPort: number;
+    /** Other components that must complete first. */
+    dependsOn?: string[];
+}
+/**
+ * Expand a single-host Docker Compose deploy to its standard
+ * Publish/Apply/Verify composition. No registry ever in the path: the built
+ * image tarball is copied straight onto the host and `docker load`ed there
+ * (`load-image-on-host`), the compose file follows the same way, and
+ * `docker compose up -d` runs via `remote-exec` — the registry-less backend
+ * axis documented in docs/components/build-archive.mdx.
+ */
+export declare function SingleHostComposeComponent(config: SingleHostComposeComponentConfig): Component;
+//# sourceMappingURL=single-host-compose.d.ts.map

package/dist/components/presets/single-host-compose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"single-host-compose.d.ts","sourceRoot":"","sources":["../../../src/components/presets/single-host-compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,MAAM,WAAW,gCAAgC;IAC/C,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8FAA8F;IAC9F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gCAAgC,GAAG,SAAS,CAkB9F"}

package/dist/components/registry.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The starter capability registry — one `CapabilityRegistry` pre-seeded with
+ * every verb in the starter set (epic #551, issue #554). All stubs; no cloud
+ * calls except for the #557/#558 AWS leaves (real implementations).
+ *
+ * Phase 2 (#559) promotes this convention to a first-class plugin contract
+ * (./capability-plugin.ts): the starter verb set now ships as
+ * `starterCapabilityPlugin` (./starter-plugin.ts), and `createCapabilityRegistry`
+ * below builds its registry from that plugin's `capabilities()` instead of
+ * registering each verb inline. This is a pure refactor — same kinds, same
+ * capability instances, same registration order — so every existing caller
+ * (the driver, the pilots, ./registry.test.ts) is unaffected. New code
+ * should prefer `buildCapabilityRegistry` (./capability-plugin-loader.ts),
+ * which additionally supports loading third-party capability plugins on top
+ * of this same starter set, the way lexicons are discovered today.
+ */
+import { CapabilityRegistry } from "./capability.js";
+import { STARTER_VERB_FAMILIES } from "./starter-plugin.js";
+/** Build a fresh `CapabilityRegistry` containing every starter-set verb stub. */
+export declare function createCapabilityRegistry(): CapabilityRegistry;
+/**
+ * Every `kind` in the starter verb set, grouped by family — useful for tests
+ * and docs generation. Re-exported here (source of truth moved to
+ * ./starter-plugin.ts to avoid a module cycle with `starterCapabilityPlugin`)
+ * so every existing import of `STARTER_VERB_FAMILIES` from this module keeps
+ * working unchanged.
+ */
+export { STARTER_VERB_FAMILIES };
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/components/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAA2B,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAElF,iFAAiF;AACjF,wBAAgB,wBAAwB,IAAI,kBAAkB,CAM7D;AAED;;;;;;GAMG;AACH,OAAO,EAAE,qBAAqB,EAAE,CAAC"}

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

@@ -0,0 +1,51 @@
+/**
+ * The starter verb set (epic #551, #554/#557/#558), wrapped as a
+ * `CapabilityPlugin` (#559) — the built-in, always-loaded plugin that
+ * carries every Phase 1 capability forward under the Phase 2 plugin
+ * contract with **no behavior change**.
+ *
+ * Migration path from Phase 1 to Phase 2: Phase 1 (`createCapabilityRegistry`,
+ * ./registry.ts) constructed a `CapabilityRegistry` by registering each
+ * starter verb directly. Phase 2 introduces `CapabilityPlugin` as the
+ * discoverable, typed package contract (./capability-plugin.ts) that
+ * mirrors how lexicons are packaged (../lexicon.ts). Rather than rewrite the
+ * starter verbs, this module packages the *exact same* verb list as one
+ * `CapabilityPlugin` named "starter" — so:
+ *
+ *  - `createCapabilityRegistry()` (./registry.ts) now builds its registry by
+ *    registering `starterCapabilityPlugin.capabilities()` instead of calling
+ *    `registry.register(...)` once per verb inline. Same kinds, same
+ *    instances, same order, same resulting registry — verified by
+ *    ./registry.test.ts, unchanged.
+ *  - `buildCapabilityRegistry()` (./capability-plugin-loader.ts), the new
+ *    Phase 2 entry point, always loads this plugin first, then layers any
+ *    additional third-party capability plugins on top by `kind`.
+ *  - The driver (./driver.ts) and every pilot (./pilots/*.pilot.ts) consume
+ *    only a `CapabilityRegistry` instance and never construct one directly
+ *    from verb modules, so neither needed to change for this migration —
+ *    the compatibility guarantee #559 asks for.
+ */
+import type { CapabilityPlugin } from "./capability-plugin.js";
+/**
+ * Every `kind` in the starter verb set, grouped by family, per epic #551 and
+ * docs/components/capabilities.mdx. Source of truth (moved here from
+ * ./registry.ts in #559 to avoid a module cycle: ./registry.ts's
+ * `createCapabilityRegistry` depends on `starterCapabilityPlugin`, so this
+ * plugin module cannot depend back on ./registry.ts). Re-exported from
+ * ./registry.ts unchanged for existing importers.
+ */
+export declare const STARTER_VERB_FAMILIES: {
+    readonly build: readonly ["docker-build", "zip-package", "jvm-build"];
+    readonly sbom: readonly ["generate-sbom"];
+    readonly supplyChainSecurity: readonly ["sign", "attest-provenance", "verify"];
+    readonly supplyChainPolicy: readonly ["scan-vulnerabilities", "vuln-gate"];
+    readonly waitVerify: readonly ["wait-cluster-healthy", "wait-endpoint", "health-gate"];
+    readonly escapeHatch: readonly ["shell"];
+};
+/**
+ * The built-in capability plugin carrying the entire Phase 1 starter verb
+ * set forward under the Phase 2 contract. Always loaded first by
+ * `buildCapabilityRegistry` (./capability-plugin-loader.ts).
+ */
+export declare const starterCapabilityPlugin: CapabilityPlugin;
+//# sourceMappingURL=starter-plugin.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"starter-plugin.d.ts","sourceRoot":"","sources":["../../src/components/starter-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAkBH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB;;;;;;;CAaxB,CAAC;AA2BX;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAKrC,CAAC"}

package/dist/components/temporal-codegen-loader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Dynamic loader for the durable component → Temporal codegen (#589, epic
+ * #551 §5/§8). The actual `serializeComponent` generator lives in
+ * `@intentius/chant-lexicon-temporal` (`src/component-op/serializer.ts`),
+ * mirroring `Temporal::Op` codegen — core never statically depends on the
+ * Temporal lexicon, the same boundary `../op/activity-registry.ts`'s
+ * `loadActivities`/`loadProfiles` already keep for Op activities.
+ */
+import type { DriverComponent } from "./driver.js";
+/** Target environment (and env-config) baked into the generated workflow at compile time — see `serializeComponent`'s docstring in the Temporal lexicon for why this can't be resolved at workflow-run time instead. */
+export interface ComponentTemporalCodegenOptions {
+    env?: string;
+    vars?: Record<string, unknown>;
+}
+export interface ComponentTemporalCodegen {
+    /** Serialize one component into `{ "components/<name>/workflow.ts": "...", ... }`. */
+    serializeComponent(component: DriverComponent, options?: ComponentTemporalCodegenOptions): Record<string, string>;
+    /** Deterministic workflow function name for a component (mirrors the generated `export async function <fn>()`). */
+    componentWorkflowFnName(componentName: string): string;
+}
+/**
+ * Dynamically import the Temporal lexicon's component codegen. Throws a
+ * friendly error if the lexicon is not installed — the durable component
+ * path needs the generator even though discovery/local execution never do.
+ */
+export declare function loadComponentTemporalCodegen(): Promise<ComponentTemporalCodegen>;
+//# sourceMappingURL=temporal-codegen-loader.d.ts.map

package/dist/components/temporal-codegen-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-codegen-loader.d.ts","sourceRoot":"","sources":["../../src/components/temporal-codegen-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,wNAAwN;AACxN,MAAM,WAAW,+BAA+B;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,sFAAsF;IACtF,kBAAkB,CAAC,SAAS,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,+BAA+B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClH,mHAAmH;IACnH,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;CACxD;AAED;;;;GAIG;AACH,wBAAsB,4BAA4B,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAWtF"}

package/dist/components/verbs/__tests__/mock-cloud-executor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `MockCloudExecutor` — an in-memory fake of the *agnostic* `CloudExecutor`
+ * (../cloud-executor.ts) for tests: the `docker` build/push client and the
+ * Neo4j bolt probe, the two clients core still owns. No live docker, ever, in
+ * a test run — every method records its call and returns a canned result.
+ *
+ * The AWS clients' mock moved to the aws lexicon alongside their
+ * implementations (`@intentius/chant-lexicon-aws/components`).
+ */
+import type { CloudExecutor } from "../cloud-executor.js";
+export interface RecordedCall {
+    client: string;
+    method: string;
+    args: unknown;
+}
+export interface FakeClusterConfig {
+    /** Number of bolt endpoints (out of however many `cluster` lists) that report healthy. Default: all of them. */
+    healthyCount?: number;
+}
+export interface MockCloudExecutorOptions {
+    /** Neo4j cluster health, keyed by the comma-joined endpoint string `wait-cluster-healthy` probes. */
+    clusters?: Record<string, FakeClusterConfig>;
+    /** Force every docker call to fail (simulates a build/push failure). */
+    failDocker?: boolean;
+}
+/** An injected agnostic `CloudExecutor` plus the call log and cluster-health controls tests use. */
+export interface MockCloudExecutor {
+    executor: CloudExecutor;
+    calls: RecordedCall[];
+    /** Change how many cluster members report healthy after construction (simulates a follower catching up). */
+    setClusterHealth(cluster: string, healthyCount: number): void;
+}
+/** Build a fresh mock agnostic `CloudExecutor`. Every method is deterministic and synchronous-fast — no real polling delay. */
+export declare function createMockCloudExecutor(options?: MockCloudExecutorOptions): MockCloudExecutor;
+//# sourceMappingURL=mock-cloud-executor.d.ts.map

package/dist/components/verbs/__tests__/mock-cloud-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-cloud-executor.d.ts","sourceRoot":"","sources":["../../../../src/components/verbs/__tests__/mock-cloud-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkG,MAAM,mBAAmB,CAAC;AAEvJ,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,gHAAgH;IAChH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,wBAAwB;IACvC,qGAAqG;IACrG,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC7C,wEAAwE;IACxE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,oGAAoG;AACpG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,4GAA4G;IAC5G,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/D;AAED,+HAA+H;AAC/H,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,iBAAiB,CAoDjG"}

package/dist/components/verbs/__tests__/mock-process-runner.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `MockProcessRunner` — an in-memory fake of `ProcessRunner`
+ * (../process-runner.ts) for tests. No live `syft`/`buildx`/
+ * `cyclonedx-maven`/`cdxgen`/`oras`, no child process spawned at all: every
+ * call is recorded, and `run`/`available` return scripted results — the same
+ * convention `../__tests__/mock-cloud-executor.ts` uses for `CloudExecutor`.
+ *
+ * Every test that exercises a #610 real backend (`ToolSbomGenerator`,
+ * `OrasReferrerLookup`, `publish-image`'s referrer-attach step) builds one
+ * `MockProcessRunner`, scripts which tools are "installed" and what each
+ * command's canned stdout is, and passes it in — never touching the real,
+ * `child_process`-backed runner.
+ */
+import type { ProcessRunner, RunOptions } from "../process-runner.js";
+export interface RecordedProcessCall {
+    command: string;
+    options?: RunOptions;
+}
+export interface MockProcessRunnerOptions {
+    /** Which tools `available()` reports as installed. Default: every tool is available (opt a test into "missing tool" by naming it here with `false`, or by omitting it when `defaultAvailable` is `false`). */
+    tools?: Record<string, boolean>;
+    /** `available()`'s answer for a tool not named in `tools`. Default: `true` (most tests aren't about the missing-tool path). */
+    defaultAvailable?: boolean;
+    /**
+     * Canned stdout per command, matched by a substring (the first entry whose
+     * key is included in the command string wins) — this is deliberately loose
+     * rather than an exact-string map, since the SUT constructs full shell
+     * command lines the test doesn't want to hand-reconstruct byte-for-byte
+     * just to script a response.
+     */
+    responses?: Record<string, string>;
+    /** Command substrings that should reject (simulates the tool exiting non-zero), mapped to the error message. */
+    failures?: Record<string, string>;
+}
+export interface MockProcessRunner {
+    runner: ProcessRunner;
+    calls: RecordedProcessCall[];
+    /** Change a tool's reported availability after construction. */
+    setAvailable(tool: string, available: boolean): void;
+    /** Script (or replace) a command substring's canned stdout after construction. */
+    setResponse(commandSubstring: string, stdout: string): void;
+}
+/** Build a fresh mock `ProcessRunner`. Every method is deterministic and synchronous-fast — no real process spawned, no real delay. */
+export declare function createMockProcessRunner(options?: MockProcessRunnerOptions): MockProcessRunner;
+//# sourceMappingURL=mock-process-runner.d.ts.map

package/dist/components/verbs/__tests__/mock-process-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-process-runner.d.ts","sourceRoot":"","sources":["../../../../src/components/verbs/__tests__/mock-process-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAiB,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAElF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,UAAU,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,8MAA8M;IAC9M,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,+HAA+H;IAC/H,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,gHAAgH;IAChH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,gEAAgE;IAChE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACrD,kFAAkF;IAClF,WAAW,CAAC,gBAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7D;AAED,uIAAuI;AACvI,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,iBAAiB,CA8BjG"}

package/dist/components/verbs/__tests__/mock-sbom-generator.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `MockSbomGenerator` — an in-memory fake of `SbomGenerator`
+ * (../sbom-generator.ts) for tests. No live `syft`/`docker buildx`/
+ * `cyclonedx-maven`/`cdxgen`, no network: every method records its call and
+ * returns a deterministic, canned `SbomDocument` derived from its inputs, the
+ * same convention `../__tests__/mock-cloud-executor.ts` uses for
+ * `CloudExecutor` (a fake digest suffix derived from the call's arguments,
+ * stable across calls with the same args).
+ *
+ * Every test that exercises `generate-sbom` (../sbom.ts) builds one
+ * `MockSbomGenerator` and passes it to `createGenerateSbomCapability`,
+ * never touching a real scanner.
+ */
+import type { SbomGenerator } from "../sbom-generator.js";
+export interface RecordedSbomCall {
+    method: "forImage" | "forJar" | "forZip" | "forDir";
+    args: unknown;
+}
+export interface MockSbomGeneratorOptions {
+    /** Force every call to fail (simulates a scanner crash/timeout). */
+    fail?: boolean;
+    /** Package count reported for every generated SBOM. Default: 3. */
+    packageCount?: number;
+    /** Generator/tool name reported. Default: "mock-syft". */
+    generatorName?: string;
+}
+export interface MockSbomGenerator {
+    generator: SbomGenerator;
+    calls: RecordedSbomCall[];
+}
+/** Build a fresh mock `SbomGenerator`. Every method is deterministic and synchronous-fast — no real scan delay. */
+export declare function createMockSbomGenerator(options?: MockSbomGeneratorOptions): MockSbomGenerator;
+//# sourceMappingURL=mock-sbom-generator.d.ts.map

package/dist/components/verbs/__tests__/mock-sbom-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-sbom-generator.d.ts","sourceRoot":"","sources":["../../../../src/components/verbs/__tests__/mock-sbom-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAOV,aAAa,EACd,MAAM,mBAAmB,CAAC;AAG3B,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0DAA0D;IAC1D,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,aAAa,CAAC;IACzB,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,mHAAmH;AACnH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,wBAA6B,GAAG,iBAAiB,CAuCjG"}

package/dist/components/verbs/bom-writer.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Native JSON BOM writer (#613, epic #551 follow-up to #606). Pure
+ * TypeScript, no external binaries (no `syft`/`buildx --sbom`/`cyclonedx-maven`/
+ * `oras`/`cosign`), no network — every document below is assembled entirely
+ * from in-memory data and `JSON.stringify`.
+ *
+ * This module is the shared serialization core both real `SbomGenerator`
+ * backends in this directory build on: the software leaf
+ * (./lockfile-sbom-generator.ts, lockfile/manifest-derived package lists) and
+ * the IaC leaf (./config-bom.ts, synthesized-template-derived component
+ * lists). Neither backend hand-rolls its own SPDX/CycloneDX shape — both
+ * call `writeSpdx`/`writeCycloneDx` here so the two document standards have
+ * exactly one writer each in the whole codebase.
+ *
+ * **Why hand-write the JSON instead of a library.** No SPDX/CycloneDX SDK is
+ * a dependency of this package (matching ./cloud-executor.ts's stance on the
+ * AWS SDK: shell out or hand-roll rather than add a heavy dependency for a
+ * narrow need). Both standards' JSON forms are simple enough — a handful of
+ * required top-level fields plus an array of package/component records — that
+ * a ~100-line writer is more auditable than a dependency. Structural
+ * correctness (required fields, enum values) is verified in
+ * ./bom-writer.test.ts against each standard's own published JSON Schema
+ * (vendored as devDep test fixtures, the same convention #553 used for the
+ * Component contract schema — see ./__fixtures__/schemas/).
+ *
+ * **Format decisions, recorded for reviewers:**
+ *  - SPDX **2.3** (not 2.2 or 3.0): 2.3 is what BuildKit's native `--sbom`
+ *    attestation emits (referenced in ./sbom-generator.ts's module doc), so
+ *    matching that version keeps a future BuildKit-backed `forImage` and this
+ *    lockfile-backed backend speaking the same SPDX dialect. SPDX 3.0 is a
+ *    substantially different (JSON-LD/RDF-shaped) model not yet the de facto
+ *    tooling default as of this writing.
+ *  - CycloneDX **1.5** (not 1.4 or 1.6): 1.5 is the version most broadly
+ *    supported by consumer tooling (Dependency-Track, `cyclonedx-cli`) at
+ *    time of writing and has a stable published JSON Schema; 1.6 adds fields
+ *    this writer doesn't need yet.
+ *  - `documentNamespace`/`serialNumber` are deterministic, derived from the
+ *    subject's digest/path rather than a random UUID, so two BOM generations
+ *    of byte-identical inputs produce byte-identical documents — the same
+ *    content-addressing property ./build-archive.ts's `contentDigest`
+ *    depends on for its "identical inputs -> identical manifest digest"
+ *    guarantee (see ./sbom.test.ts's existing test of that property).
+ *
+ * **Assembly (#614).** `BomInput.subDocuments`, when present, projects each
+ * sub-document as a real nested unit rather than flattening its packages into
+ * the root's own list — CycloneDX's `metadata.component.components` +
+ * `compositions` (`aggregate: "incomplete"`, since a component BOM only
+ * composes the leaf BOMs it was given, never a closed-world claim over
+ * everything the artifact might contain), SPDX's `hasFiles`-style `CONTAINS`
+ * relationship from the root package to each sub-document's own root package
+ * plus that sub-document's own `DEPENDS_ON` edges. This is what
+ * ./component-bom.ts's `aggregateComponentBom` uses to compose a component's
+ * leaf BOMs (a software SBOM plus an IaC config-BOM) into one document
+ * without flattening away which packages came from which leaf — still one
+ * writer per standard, extended rather than duplicated.
+ */
+import { type SbomFormat } from "./sbom-generator.js";
+/**
+ * One dependency/component the BOM enumerates — the standard-agnostic unit
+ * both `writeSpdx` and `writeCycloneDx` project into their own per-format
+ * package/component record shape. A generator backend (lockfile parser,
+ * config-BOM template walker) builds a `BomPackage[]` once and hands it to
+ * whichever writer the requested `format` selects.
+ */
+export interface BomPackage {
+    /** Package/component name (npm package name, Maven artifactId, or — for a config-BOM — a resource's logical name/type). */
+    name: string;
+    /** Version string, when known. Omitted for resources with no version concept (e.g. a CFN resource). */
+    version?: string;
+    /** Package manager / ecosystem this entry came from (e.g. "npm", "maven"), surfaced in SPDX's `externalRefs`/CycloneDX's `purl` when derivable. */
+    type?: "npm" | "maven" | "config" | "external-reference";
+    /** Package URL (purl), when derivable — e.g. `pkg:npm/left-pad@1.3.0`. */
+    purl?: string;
+    /** SPDX download location, when known. Defaults to `"NOASSERTION"` per the SPDX spec's requirement that every package declare one. */
+    downloadLocation?: string;
+    /** Names of other `BomPackage.name` entries this one depends on — projected into SPDX's `relationships` (`DEPENDS_ON`) and CycloneDX's `dependencies`. */
+    dependsOn?: string[];
+}
+/**
+ * One nested BOM unit an assembly (#614) composes into its root document —
+ * projected as a real nested `components` entry in CycloneDX and a
+ * `CONTAINS`-linked sub-package group in SPDX, never flattened into the
+ * root's own package list. Typically one leaf BOM (a software SBOM or an IaC
+ * config-BOM) a component produced, see ./component-bom.ts.
+ */
+export interface BomSubDocument {
+    /** Human-readable name for this sub-document's own subject (e.g. an artifact's archive path). */
+    subjectName: string;
+    /** Version of this sub-document's subject, when known. */
+    subjectVersion?: string;
+    /** Stable identity for this sub-document's subject — typically the artifact digest it describes, so the assembly's `CONTAINS`/nested-component edge is traceable back to a real `BuildArchiveEntry.digest`. */
+    subjectId: string;
+    /** Every package/component this sub-document enumerates. */
+    packages: BomPackage[];
+}
+/** Input to both writers: the subject the BOM describes plus its enumerated packages/components. */
+export interface BomInput {
+    /** Human-readable name for the BOM's subject (a package name, a template/stack name). */
+    subjectName: string;
+    /** Version of the subject itself, when known. */
+    subjectVersion?: string;
+    /** Stable identity for the subject, used to derive deterministic namespace/serial IDs — typically a digest or an archive-relative path. */
+    subjectId: string;
+    /** Every package/component the BOM enumerates. */
+    packages: BomPackage[];
+    /** Name of the tool that produced this document (surfaced in SPDX's `creationInfo.creators` / CycloneDX's `metadata.tools`). */
+    generator: string;
+    /**
+     * Nested BOM units to compose into this document as an assembly (#614) —
+     * present only for a component-level aggregation BOM (see
+     * ./component-bom.ts). When omitted, `writeSpdx`/`writeCycloneDx` behave
+     * exactly as before #614: a flat single-subject document.
+     */
+    subDocuments?: BomSubDocument[];
+}
+/**
+ * Native SPDX-2.3 JSON writer. Emits the required top-level fields
+ * (`spdxVersion`, `dataLicense`, `SPDXID`, `name`, `documentNamespace`,
+ * `creationInfo`, `packages`) plus a `relationships` array recording the
+ * document's `DESCRIBES` edge to the subject package and each package's
+ * declared `DEPENDS_ON` edges — the "valid relationships section where
+ * applicable" #613 calls for.
+ *
+ * When `input.subDocuments` is present (#614 assembly), each sub-document's
+ * own root package is emitted alongside the top-level subject, linked from
+ * the top-level subject via a `CONTAINS` relationship, with that
+ * sub-document's own packages and `DEPENDS_ON` edges nested under an
+ * SPDX-ID namespace unique to it (`SPDXRef-Package-sub<n>-...`) so packages
+ * from different leaf BOMs never collide even if same-named.
+ */
+export declare function writeSpdx(input: BomInput, now?: () => Date): string;
+/**
+ * Native CycloneDX-1.5 JSON writer. Emits the required top-level fields
+ * (`bomFormat`, `specVersion`, `serialNumber`, `version`, `metadata`,
+ * `components`) plus a `dependencies` array recording the root subject's
+ * direct dependencies and each component's own declared dependencies.
+ *
+ * When `input.subDocuments` is present (#614 assembly), each sub-document is
+ * projected as a real nested component under `metadata.component.components`
+ * (CycloneDX's own "hierarchical representation of component assemblies,
+ * similar to system -> subsystem -> parts" per its schema doc) — never
+ * flattened into the root's own `components` array — with a `compositions`
+ * entry recording the aggregate as `"incomplete"` (this document composes
+ * exactly the leaf BOMs it was given, not a closed-world claim over
+ * everything the artifact might contain) and a root `dependencies` edge from
+ * the top-level subject to each sub-document's root.
+ */
+export declare function writeCycloneDx(input: BomInput, now?: () => Date): string;
+/** Serialize `input` in the requested `format` and wrap it as the project-wide `{ format, mediaType, bytes }` doc shape (./sbom-generator.ts's `SbomDocument`, minus `generator`/`packageCount` which the caller fills in). */
+export declare function writeBom(format: SbomFormat, input: BomInput, now?: () => Date): {
+    format: SbomFormat;
+    mediaType: string;
+    bytes: string;
+};
+//# sourceMappingURL=bom-writer.d.ts.map

package/dist/components/verbs/bom-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bom-writer.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/bom-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAIrE;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,2HAA2H;IAC3H,IAAI,EAAE,MAAM,CAAC;IACb,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mJAAmJ;IACnJ,IAAI,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,oBAAoB,CAAC;IACzD,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sIAAsI;IACtI,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0JAA0J;IAC1J,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,iGAAiG;IACjG,WAAW,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,+MAA+M;IAC/M,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED,oGAAoG;AACpG,MAAM,WAAW,QAAQ;IACvB,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,2IAA2I;IAC3I,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,gIAAgI;IAChI,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;CACjC;AAyDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,GAAE,MAAM,IAAuB,GAAG,MAAM,CAyErF;AAsBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,GAAE,MAAM,IAAuB,GAAG,MAAM,CAgE1F;AAUD,+NAA+N;AAC/N,wBAAgB,QAAQ,CACtB,MAAM,EAAE,UAAU,EAClB,KAAK,EAAE,QAAQ,EACf,GAAG,CAAC,EAAE,MAAM,IAAI,GACf;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAG1D"}