@intentius/chant-lexicon-aws 0.124.31 → 0.124.32

package/dist/components/config-bom.js

@@ -0,0 +1,207 @@
+/**
+ * `extract-config-bom` capability (#613, epic #551 follow-up to #606).
+ *
+ * chant synthesis is deterministic, so a synthesized IaC template (the
+ * CloudFormation JSON `chant build` already produces — see ../../build.ts
+ * and lexicons/aws/src/serializer.ts's `CFTemplate`) is itself a
+ * reproducible artifact with a legitimate bill-of-materials: it declares
+ * resources, may nest child stacks, and references external artifacts
+ * (container image digests, AMI ids, other lexicons' versions) that are not
+ * declared dependencies in any lockfile. This module is the config-BOM
+ * analogue of ./sbom.ts's `generate-sbom`: same archive/manifest wiring,
+ * same SPDX/CycloneDX writer (./bom-writer.ts), different subject (a
+ * template's structure instead of a lockfile's package list).
+ *
+ * **Scope.** The extractor is a pure, hermetic AST-ish walk over the
+ * template's already-parsed JSON — no cloud calls, no `cfn describe-stacks`,
+ * no network. It only reads chant's own synthesized output, so it works
+ * identically for any lexicon whose serializer emits a JSON document shaped
+ * like CloudFormation's `{ Resources: { name: { Type, Properties } } }` (the
+ * ../../serializer.ts `SerializerResult.primary`/`files` convention every
+ * lexicon serializer already produces). Non-JSON serializer output (a raw
+ * Kubernetes YAML manifest, say) is out of scope for this first cut — see
+ * `extractConfigBom`'s doc comment.
+ *
+ * **Why config-only/infra components get a BOM.** #606 shipped
+ * `generate-sbom` keyed to *artifact* types (image/jar/zip/dir); a
+ * config-only component (no `build` phase, e.g. a DynamoDB table or an EMR
+ * cluster definition — see epic #551's "Infra" archetype) has none of those
+ * and so was previously assumed to have nothing to attach a BOM to. That
+ * assumption undercounts what's true: the synthesized template *is* that
+ * component's build output. Treating it as a first-class archive artifact
+ * (a `template`-kind entry with its own content digest, peer to `image`/
+ * `asset` — see ./build-archive.ts's `addArchiveTemplate`) means a
+ * config-BOM can attach to it exactly the way a software SBOM attaches to
+ * an image digest, closing the gap.
+ */
+import { addArchiveEntry, archiveRelativePath, contentDigest, createBuildArchiveManifest, } from "@intentius/chant/components/verbs/build-archive";
+import { writeBom } from "@intentius/chant/components/verbs/bom-writer";
+import { DEFAULT_SBOM_FORMAT } from "@intentius/chant/components/verbs/sbom-generator";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+/** CloudFormation resource type used for nested stacks (see lexicons/aws/src/nested-stack.ts). Other lexicons' nesting resource types can be added here as they gain the same concept. */
+const NESTED_STACK_TYPES = new Set(["AWS::CloudFormation::Stack"]);
+/** Property names known to carry a nested stack's child template location, checked in order. */
+function extractTemplatePath(properties) {
+    const templateUrl = properties?.TemplateURL;
+    if (typeof templateUrl === "string")
+        return templateUrl;
+    if (templateUrl && typeof templateUrl === "object") {
+        // { "Fn::Sub": "${TemplateBasePath}/network.template.json" } — pull the filename back out.
+        const sub = templateUrl["Fn::Sub"];
+        if (typeof sub === "string") {
+            const match = sub.match(/([^/{}$]+\.template\.json)$/);
+            if (match)
+                return match[1];
+        }
+    }
+    return undefined;
+}
+/** AMI id pattern (`ami-` followed by 8 or 17 hex chars, matching both legacy and current EC2 id formats). */
+const AMI_PATTERN = /^ami-[0-9a-f]{8}([0-9a-f]{9})?$/;
+/** OCI/Docker content digest pattern (`sha256:<64 hex chars>`), the same form ./build-archive.ts's `contentDigest` produces. */
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
+/** A bare `image:tag@sha256:digest` or `image@sha256:digest` reference. */
+const IMAGE_DIGEST_REF_PATTERN = /@(sha256:[0-9a-f]{64})$/;
+/** Property names likely to carry a lexicon version string, so a bare semver value there is attributed as `lexicon-version` rather than left unclassified. */
+const LEXICON_VERSION_PROPERTY_NAMES = new Set(["LexiconVersion", "lexiconVersion", "ChantLexiconVersion"]);
+/** Walk one resource's `Properties` tree (recursively, since a reference can be nested inside e.g. a container definition list) collecting external references. */
+function scanPropertiesForReferences(resourceName, properties, propertyKeyHint, out) {
+    if (properties === null || properties === undefined)
+        return;
+    if (typeof properties === "string") {
+        if (AMI_PATTERN.test(properties)) {
+            out.push({ kind: "ami", value: properties, resourceName });
+        }
+        else if (DIGEST_PATTERN.test(properties) || IMAGE_DIGEST_REF_PATTERN.test(properties)) {
+            const digestMatch = properties.match(IMAGE_DIGEST_REF_PATTERN);
+            out.push({ kind: "image-digest", value: digestMatch ? digestMatch[1] : properties, resourceName });
+        }
+        else if (propertyKeyHint && LEXICON_VERSION_PROPERTY_NAMES.has(propertyKeyHint) && /^\d+\.\d+\.\d+/.test(properties)) {
+            out.push({ kind: "lexicon-version", value: properties, resourceName });
+        }
+        return;
+    }
+    if (Array.isArray(properties)) {
+        for (const item of properties)
+            scanPropertiesForReferences(resourceName, item, propertyKeyHint, out);
+        return;
+    }
+    if (typeof properties === "object") {
+        for (const [key, value] of Object.entries(properties)) {
+            scanPropertiesForReferences(resourceName, value, key, out);
+        }
+    }
+}
+/**
+ * Walk a synthesized template's parsed JSON, enumerating declared resources,
+ * nested stack/module references, and external artifact references (image
+ * digests, AMI ids, lexicon versions found in resource properties).
+ *
+ * Deliberately structural, not semantic: this never talks to AWS/any cloud
+ * to resolve what an AMI id or image digest actually *is* — it only records
+ * that a resource's properties reference one, the same "surface the
+ * reference, don't interpret it" stance ./sbom-generator.ts's module doc
+ * takes for SBOM content generally.
+ */
+export function inventoryTemplate(templateJson) {
+    const template = JSON.parse(templateJson);
+    const resources = [];
+    const nestedStacks = [];
+    const externalReferences = [];
+    for (const [name, resource] of Object.entries(template.Resources ?? {})) {
+        const type = resource.Type ?? "Unknown";
+        resources.push({ name, type });
+        if (NESTED_STACK_TYPES.has(type)) {
+            nestedStacks.push({ resourceName: name, templatePath: extractTemplatePath(resource.Properties) });
+        }
+        scanPropertiesForReferences(name, resource.Properties, undefined, externalReferences);
+    }
+    return { resources, nestedStacks, externalReferences };
+}
+/** Project a `ConfigBomInventory` into the standard-agnostic `BomPackage[]` shape ./bom-writer.ts's writers consume. Every declared resource becomes a `type: "config"` component; every external reference becomes a `type: "external-reference"` component, so a config-BOM reader sees "what chant declared" and "what chant points at but doesn't own" as distinguishable entries rather than a flat, ambiguous list. */
+export function inventoryToBomPackages(inventory) {
+    const resourcePackages = inventory.resources.map((r) => ({
+        name: r.name,
+        version: r.type,
+        type: "config",
+    }));
+    const nestedStackNames = new Set(inventory.nestedStacks.map((n) => n.resourceName));
+    for (const pkg of resourcePackages) {
+        if (nestedStackNames.has(pkg.name)) {
+            const nested = inventory.nestedStacks.find((n) => n.resourceName === pkg.name);
+            if (nested?.templatePath)
+                pkg.purl = `chant:nested-stack/${nested.templatePath}`;
+        }
+    }
+    const referencePackages = inventory.externalReferences.map((ref, i) => ({
+        name: `${ref.kind}:${ref.resourceName ?? "unknown"}:${i}`,
+        version: ref.value,
+        type: "external-reference",
+    }));
+    return [...resourcePackages, ...referencePackages];
+}
+/** Default archive path for a generated config-BOM when `into` is omitted: `<template path>.config-bom.json`. */
+function defaultConfigBomPath(templatePath) {
+    return `${archiveRelativePath(templatePath)}.config-bom.json`;
+}
+/** Tool name recorded on the archive entry / BOM document — surfaced the same way `generate-sbom` records `sbom.generator` (e.g. "syft-1.2.3"). */
+const CONFIG_BOM_GENERATOR = "chant-config-bom-extractor";
+/**
+ * Extract a config-BOM from a synthesized IaC template's declared resources,
+ * nested stacks, and external references, and fold the result into the
+ * build-archive manifest as an `sbom`-kind entry (`bomKind: "config"`) linked
+ * to the template artifact's digest — the config-BOM peer of `generate-sbom`
+ * (./sbom.ts). No rollback, for the same reason `generate-sbom` declares
+ * none: an already-generated, content-addressed BOM is evidence, not mutable
+ * state to compensate.
+ */
+export function createExtractConfigBomCapability() {
+    return {
+        kind: "extract-config-bom",
+        async run(ctx, input) {
+            const templatePath = archiveRelativePath(input.path);
+            const format = input.format ?? DEFAULT_SBOM_FORMAT;
+            const inventory = inventoryTemplate(input.content);
+            const packages = inventoryToBomPackages(inventory);
+            const doc = writeBom(format, {
+                subjectName: templatePath,
+                subjectId: input.digest ?? contentDigest(input.content),
+                packages,
+                generator: CONFIG_BOM_GENERATOR,
+            }, input.now);
+            const bom = { ...doc, packageCount: packages.length, generator: CONFIG_BOM_GENERATOR };
+            if (input.outDir) {
+                mkdirSync(input.outDir, { recursive: true });
+                writeFileSync(join(input.outDir, `config-bom.${format}.json`), bom.bytes);
+            }
+            const into = input.into ?? defaultConfigBomPath(input.path);
+            const digest = contentDigest(bom.bytes);
+            const base = input.manifest ?? createBuildArchiveManifest(ctx.component);
+            const manifest = addArchiveEntry(base, {
+                kind: "sbom",
+                bomKind: "config",
+                path: into,
+                digest,
+                mediaType: bom.mediaType,
+                subjectDigest: input.digest,
+                packageCount: bom.packageCount,
+                generator: bom.generator,
+            });
+            return { bom, inventory, archivePath: into, digest, manifest };
+        },
+    };
+}
+/**
+ * Default `extract-config-bom` capability. Pure/hermetic — no injectable
+ * backend needed since template inventory is a structural walk, not a scan
+ * requiring an external tool.
+ *
+ * Typically composed immediately after `addArchiveTemplate` (./build.ts) in
+ * a config-only/infra component's build phase — `addArchiveTemplate` folds
+ * the synthesized template into the archive as a first-class `template`-kind
+ * entry with its own content digest (#613 — IaC as a first-class build
+ * artifact, peer to `image`/`jar`), and this capability attaches the
+ * resulting config-BOM to that same digest.
+ */
+export const extractConfigBomCapability = createExtractConfigBomCapability();

package/dist/components/host-delivery.js

@@ -0,0 +1,117 @@
+/**
+ * host / code delivery family — run against a mutable host.
+ *
+ * `code-deploy` (AWS CodeDeploy) is the managed, nearly AWS-only leaf: create
+ * a deployment of a revision (S3/GitHub) to a deployment group, appspec-driven
+ * lifecycle hooks (BeforeInstall/AfterInstall/ApplicationStart/ValidateService),
+ * in-place or blue/green, native automatic rollback, wait for terminal status.
+ * Pairs with `publish-artifact` — the revision is the published S3 bundle
+ * (`@publish.uri`).
+ *
+ * `copy-to-host` / `remote-exec` (SSM Run Command or SSH) are the portable,
+ * lower-level generic verbs for host bootstrap, on-host migrations, and
+ * single-host compose where CodeDeploy is not used or not available
+ * (no clean Azure/GCP peer — see docs/components/cloud-boundary).
+ *
+ * `code-deploy` is a real implementation (#557, epic #551) over the
+ * injectable `CloudExecutor` (./cloud-executor.ts) — the capability the
+ * Neo4j fan-out pilot uses once per instance. `copy-to-host` and `remote-exec`
+ * are also real, over the executor's `host.exec` (SSM Run Command, waited to
+ * completion); the SSH transport is not yet implemented.
+ */
+import { defaultCloudExecutor } from "./cloud-executor.js";
+import { releaseEnvironment } from "@intentius/chant/telemetry-attribution";
+/** Normalize `CodeDeployInput.revision` to the strict `{type, uri|repository+commitId}` shape the executor takes. */
+function normalizeRevision(revision) {
+    return typeof revision === "string" ? { type: "s3", uri: revision } : revision;
+}
+/** Resolve the application/deployment-group names, defaulting from `ctx.component`/`instance` when the input omits them (matches the Neo4j pilot's per-instance shorthand). */
+function resolveTargets(ctx, input) {
+    const application = input.application ?? ctx.component;
+    const deploymentGroup = input.deploymentGroup ?? (input.instance !== undefined ? `${application}-${input.instance}` : application);
+    return { application, deploymentGroup };
+}
+/**
+ * Deploy a revision to a host (fleet) via AWS CodeDeploy: create the
+ * deployment, then wait for a terminal status. Rollback re-invokes
+ * `stopAndRollback` against the deployment id this step created (captured in
+ * a closure-scoped map keyed by application/deploymentGroup; the driver now
+ * also passes `run`'s output as `rollback`'s optional third arg (#1944), but
+ * this capability's input-derived key needs neither channel to resolve
+ * identity) — riding CodeDeploy's own native automatic rollback to the
+ * last known-good revision rather than a chant-scripted compensation, the
+ * "auto" rollback style the Neo4j pilot's docs comment contrasts with the
+ * ALB/ECS pilot's component-declared one.
+ */
+export function createCodeDeployCapability(executor = defaultCloudExecutor()) {
+    const lastDeploymentByTarget = new Map();
+    return {
+        kind: "code-deploy",
+        async run(ctx, input) {
+            const { application, deploymentGroup } = resolveTargets(ctx, input);
+            const { deploymentId } = await executor.codeDeploy.createDeployment({
+                application,
+                deploymentGroup,
+                revision: normalizeRevision(input.revision),
+                strategy: input.strategy,
+            });
+            lastDeploymentByTarget.set(`${application}/${deploymentGroup}`, deploymentId);
+            const { status } = await executor.codeDeploy.waitForDeployment(deploymentId);
+            if (status !== "Succeeded") {
+                throw new Error(`code-deploy "${application}/${deploymentGroup}": deployment ${deploymentId} ended ${status}`);
+            }
+            return { deploymentId, status };
+        },
+        async rollback(ctx, input) {
+            const { application, deploymentGroup } = resolveTargets(ctx, input);
+            const deploymentId = lastDeploymentByTarget.get(`${application}/${deploymentGroup}`);
+            if (!deploymentId)
+                return; // nothing this capability instance deployed for this target — nothing to unwind.
+            await executor.codeDeploy.stopAndRollback(deploymentId);
+        },
+    };
+}
+/** Default `code-deploy` capability, backed by the real `CloudExecutor`. */
+export const codeDeployCapability = createCodeDeployCapability();
+/**
+ * Copy a file to a host via SSM Run Command: the host pulls `from` (an S3 URI)
+ * to `to` with `aws s3 cp`, then `stat`s the result for the byte count. `from`
+ * must be reachable from the host (typically a prior `publish-artifact`'s URI).
+ */
+export function createCopyToHostCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "copy-to-host",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            const { stdout } = await executor.host.exec({
+                host: input.host,
+                command: `aws s3 cp ${input.from} ${input.to} >/dev/null 2>&1 && stat -c %s ${input.to}`,
+            });
+            return { bytesCopied: Number.parseInt(stdout.trim(), 10) || 0 };
+        },
+    };
+}
+/** Default `copy-to-host` capability, backed by the real `CloudExecutor`. */
+export const copyToHostCapability = createCopyToHostCapability();
+/**
+ * Run a command on a remote host via SSM Run Command, waiting for it to finish
+ * and returning its stdout + exit code. SSH transport is not yet supported.
+ */
+export function createRemoteExecCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "remote-exec",
+        rollbackPolicy: "needs-opt-out",
+        async run(ctx, input) {
+            if (input.via === "ssh") {
+                throw new Error(`remote-exec: ssh transport not yet supported for host "${input.host}" — use the default ssm transport`);
+            }
+            // A release run exports its attributes on the host (#3061, ws-081), so a `docker compose up`
+            // fills the Compose file's `${CHANT_RELEASE_ATTRIBUTES:-}`. The value is percent-encoded, so
+            // single quotes hold it.
+            const exports = Object.entries(releaseEnvironment(ctx.release)).map(([k, v]) => `export ${k}='${v}'; `).join("");
+            return executor.host.exec({ host: input.host, command: `${exports}${input.command}`, cwd: input.cwd });
+        },
+    };
+}
+/** Default `remote-exec` capability, backed by the real `CloudExecutor`. */
+export const remoteExecCapability = createRemoteExecCapability();

package/dist/components/index.js

@@ -0,0 +1,18 @@
+/**
+ * The aws lexicon's component/release surface: the AWS-leaf capabilities, their
+ * typed step-builders, the injectable aws `CloudExecutor`, and the
+ * `awsCapabilityPlugin` core loads when a project declares `lexicons: ["aws"]`.
+ * Component authors import the AWS verbs' builders from here
+ * (`@intentius/chant-lexicon-aws/components`), the way agnostic verbs come from
+ * `@intentius/chant/components`.
+ */
+export { awsCapabilityPlugin, AWS_VERB_FAMILIES } from "./capability-plugin.js";
+export * from "./builders.js";
+export * from "./config-bom.js";
+export * from "./apply.js";
+export * from "./job-submission.js";
+export * from "./host-delivery.js";
+export * from "./safety.js";
+export * from "./wait-aws.js";
+export * from "./publish.js";
+export * from "./cloud-executor.js";

package/dist/components/job-submission.js

@@ -0,0 +1,77 @@
+/**
+ * job submission family — point a running compute service at an artifact.
+ * Cloud-shaped (EMR here; the same shape reuses for Glue / Batch / Step
+ * Functions / SageMaker per docs/components/cloud-boundary). Typically
+ * consumes a producer component's published artifact, e.g.
+ * `jar: "@jar-lib.publish.uri"`.
+ *
+ * `emr-start-job-run` is a real implementation (#561, epic #551) — just
+ * enough against the injectable `CloudExecutor` (./cloud-executor.ts) to run
+ * the JAR-producer -> EMR-consumer cross-component example end to end (a
+ * mocked cloud is acceptable per #561's acceptance criteria; the full EMR
+ * surface — retries, Serverless vs EMR-on-EC2 branching, Glue/Batch peers —
+ * stays out of scope, per #561 explicitly deferring "the emr-start-job-run
+ * cloud impl beyond what the example needs"). `emr-submit-step` is a
+ * different verb (submit a step to an already-running EMR-on-EC2 cluster
+ * rather than starting an ephemeral job run), also real over the executor
+ * (`aws emr add-steps`) and unit-tested against the mock — the same
+ * "mocked cloud is acceptable" basis #561 set for its sibling, since a live
+ * long-running EMR cluster is not part of gating CI.
+ */
+import { defaultCloudExecutor } from "./cloud-executor.js";
+/**
+ * Start an EMR job run (Serverless application or EMR-on-EC2 cluster)
+ * against a published artifact. `input.jar` arrives already resolved by the
+ * driver's graph-driven wiring (`@<component>.publish.uri`) — this capability
+ * never resolves the reference itself, keeping cross-component wiring
+ * entirely the graph's job (../driver.ts's `resolveWiring`), never a
+ * capability- or orchestrator-level special case. No rollback: starting a
+ * job run has no "undo" that restores prior state — a failed/cancelled run
+ * simply produced no usable output, matching `wait-for-stack`/`wait-job`'s
+ * read-only-observation story (there is nothing to compensate for having
+ * asked the cluster to run something).
+ */
+export function createEmrStartJobRunCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "emr-start-job-run",
+        rollbackPolicy: "needs-opt-out",
+        async run(ctx, input) {
+            const clusterOrApplicationId = input.clusterOrApplicationId ?? ctx.vars?.emrApplicationId ?? ctx.component;
+            const { runId } = await executor.emr.startJobRun({
+                clusterOrApplicationId,
+                jar: input.jar,
+                args: input.args,
+                executionRoleArn: input.executionRoleArn,
+            });
+            return { runId };
+        },
+    };
+}
+/** Default `emr-start-job-run` capability, backed by the real `CloudExecutor`. */
+export const emrStartJobRunCapability = createEmrStartJobRunCapability();
+/**
+ * Submit a step to a long-running EMR-on-EC2 cluster (as opposed to
+ * `emr-start-job-run`, which starts an ephemeral Serverless/EC2 job run) via
+ * `aws emr add-steps` through the injectable `CloudExecutor`. Returns the step
+ * id for polling via `wait-job`. Like its sibling, `input.jar` arrives
+ * already resolved by the driver's graph-driven wiring, and there is no
+ * rollback — a submitted step has no "undo" that restores prior state.
+ */
+export function createEmrSubmitStepCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "emr-submit-step",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            const { stepId } = await executor.emr.addStep({
+                clusterId: input.clusterId,
+                name: input.name,
+                jar: input.jar,
+                args: input.args,
+                actionOnFailure: input.actionOnFailure,
+            });
+            return { stepId };
+        },
+    };
+}
+/** Default `emr-submit-step` capability, backed by the real `CloudExecutor`. */
+export const emrSubmitStepCapability = createEmrSubmitStepCapability();

package/dist/components/publish.js

@@ -0,0 +1,234 @@
+/**
+ * publish family — deploy-time promotion by identity to the env location.
+ *
+ * "Make the image available at the deploy target" has more than one backend:
+ * `publish-image` promotes into a registry (ECR/ACR/Artifact Registry, pulled
+ * by the target); `load-image-on-host` copies the tarball straight onto a host
+ * and `docker load`s it (registry-less). Both satisfy the same
+ * `PublishImageBackend` interface — the backend is env config, not a pipeline
+ * fork. `publish-asset`/`publish-artifact` is the non-image sibling (S3 /
+ * CodeArtifact) used by producer/library components (e.g. a jar for EMR).
+ * See docs/components/build-archive.mdx.
+ *
+ * `publish-image` is a real implementation (#557, epic #551): it loads the
+ * archived image tarball, tags it for the destination registry, logs in via
+ * ECR, and pushes — promoting by digest, per the epic's build-once invariant.
+ *
+ * `load-image-on-host` is a real implementation (#564, epic #551 "4. Build
+ * archive + deferred publish"): it copies the archived tarball onto a host
+ * and runs `docker load` there via the injected `CloudExecutor.host` — no
+ * registry in the path at all. Both backends promote **by digest**, never
+ * rebuilding: the bytes they move are exactly what `docker-build` produced
+ * into the archive (see ./build-archive.ts). `selectPublishBackend` below is
+ * the per-environment choice between them — env config, not a pipeline fork,
+ * per docs/components/build-archive.mdx#backend-selection-is-per-environment.
+ *
+ * `publish-artifact` (aliased `publish-asset`) uploads a single archive
+ * artifact (jar/zip/asset) to S3 via `aws s3 cp` through the same
+ * endpoint-aware `CloudExecutor`, returning the object URI and a content digest
+ * of the uploaded bytes — the non-image sibling of `publish-image`.
+ *
+ * **#610 addition: publish-time SBOM/BOM referrer attach.** `publish-image`
+ * optionally registers the archive's SBOM (and, when given, the
+ * component-level aggregate BOM) as an OCI referrer on the just-pushed image
+ * digest via `oras attach` — a registry-side convenience for `oras
+ * discover`/`cosign tree` layered on top of the archive-carried copy, never a
+ * replacement for it (see ../../lifecycle/build-ledger.ts's module doc: the
+ * archive remains the universal home, working for every artifact type and
+ * the registry-less `load-image-on-host` path, which this attach step
+ * deliberately does not touch — non-image/registry-less publishes stay
+ * archive-carried only). Attach is opt-in per call (`input.sbom` supplied),
+ * guarded on `oras` availability, and never fails the publish itself: a
+ * missing `oras` binary or a failed attach is reported back on the output
+ * (`referrerAttach.attached: false` + a reason) rather than thrown, since the
+ * image is already successfully promoted by the time this step runs — the
+ * one part of this capability that is genuinely best-effort.
+ */
+import { readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { defaultCloudExecutor } from "./cloud-executor.js";
+import { archiveRelativePath } from "@intentius/chant/components/verbs/build-archive";
+import { defaultProcessRunner, q } from "@intentius/chant/components/verbs/process-runner";
+// ── publish-image (registry backend) ────────────────────────────────────────
+/**
+ * Attempt to `oras attach` one referrer document (SBOM or component BOM) to
+ * `imageRef`'s digest. Writes the document's bytes to a scratch file (`oras
+ * attach` reads from a file path, not stdin) and shells out through
+ * `runner`. Never throws — a failure here is reported back to the caller as
+ * `{ ok: false, reason }` so a missing/erroring `oras` never fails the
+ * publish itself (see `attachReferrers`'s doc comment for why).
+ */
+async function attachOneReferrer(runner, imageRef, doc, label) {
+    try {
+        const scratchFile = `/tmp/chant-referrer-attach/${label}-${Date.now()}.json`;
+        await runner.run(`mkdir -p ${q("/tmp/chant-referrer-attach")}`);
+        await runner.run(`printf '%s' ${q(doc.bytes)} > ${q(scratchFile)}`);
+        await runner.run(`oras attach --artifact-type ${q(doc.mediaType)} ${q(imageRef)} ${q(scratchFile)}:${q(doc.mediaType)}`);
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Best-effort OCI-referrer attach for a just-pushed image (#610): attaches
+ * `input.sbom` and/or `input.componentBom`, when supplied, to `imageRef` via
+ * `oras attach`. Guarded on `oras` availability — a missing binary is
+ * reported back as `{ attached: false, reason }` rather than thrown, since
+ * the image itself is already successfully promoted by the time this step
+ * runs (attach is additive registry-side convenience on top of the
+ * archive-carried copy, per this module's doc comment, never a condition the
+ * core promote-by-digest job depends on). Returns `undefined` when neither
+ * `input.sbom` nor `input.componentBom` was supplied — nothing to attach,
+ * skipped entirely, no `oras` call at all.
+ */
+async function attachReferrers(runner, imageRef, input) {
+    if (!input.sbom && !input.componentBom)
+        return undefined;
+    if (!(await runner.available("oras"))) {
+        return { attached: false, reason: `"oras" is not installed or not on PATH — required to attach OCI referrers` };
+    }
+    const results = [];
+    if (input.sbom)
+        results.push(await attachOneReferrer(runner, imageRef, input.sbom, "sbom"));
+    if (input.componentBom)
+        results.push(await attachOneReferrer(runner, imageRef, input.componentBom, "component-bom"));
+    const failed = results.find((r) => !r.ok);
+    return failed ? { attached: false, reason: failed.reason } : { attached: true };
+}
+/**
+ * Promote a built image from the archive into the environment's container
+ * registry: `docker load` the archived tarball, tag it for `to` (the env
+ * registry), `aws ecr get-login-password | docker login`, then `docker push`.
+ * Returns the pushed image's registry digest — what `cfn-deploy`/
+ * `ecs-update-service` reference via `imageRef: "@Publish.digest"`. No
+ * rollback: an already-pushed, still-valid image in the registry is not
+ * itself a problem to compensate (immutable, content-addressed, and simply
+ * unreferenced if a later step fails) — the opt-out this capability takes.
+ *
+ * #610: when `input.sbom` and/or `input.componentBom` are supplied, also
+ * attaches them as OCI referrers on the pushed digest via `oras attach` (see
+ * `attachReferrers` above) — best-effort, guarded on `oras` availability,
+ * surfaced on the output's `referrerAttach` rather than failing the publish.
+ */
+export function createPublishImageCapability(executor = defaultCloudExecutor(), processRunner = defaultProcessRunner()) {
+    return {
+        kind: "publish-image",
+        async run(_ctx, input) {
+            if (!input.to)
+                throw new Error(`publish-image "${input.from}": "to" (destination registry) is required`);
+            // `docker load` reports the archived image's local reference — a name:tag
+            // for a tagged build, or an image id. It's a valid `docker tag` source but
+            // never a registry digest, so the promoted digest is read back from the
+            // push below, not constructed from this.
+            const { digest: localRef } = await executor.docker.load({ inFile: archiveRelativePath(input.from) });
+            const repo = input.to.replace(/\/+$/, "");
+            // Publish under a tag: docker can neither tag nor push a digest-qualified
+            // reference (`repo@sha256:...`), so the transport is a tag and the stable
+            // identifier is the digest the push returns.
+            const pushRef = `${repo}:latest`;
+            await executor.docker.tag({ source: localRef, target: pushRef });
+            const registry = repo.split("/")[0];
+            await executor.ecr.login(registry);
+            const { digest: pushed } = await executor.docker.push({ image: pushRef });
+            // Normalize to a bare `sha256:...`, whether the client returned that or a
+            // full `repo@sha256:...` RepoDigest.
+            const digest = pushed.includes("@") ? pushed.slice(pushed.indexOf("@") + 1) : pushed;
+            for (const tag of input.tags ?? []) {
+                const tagged = `${repo}:${tag}`;
+                await executor.docker.tag({ source: localRef, target: tagged });
+                await executor.docker.push({ image: tagged });
+            }
+            const referrerAttach = await attachReferrers(processRunner, `${repo}@${digest}`, input);
+            return { digest, uri: `${repo}@${digest}`, ...(referrerAttach ? { referrerAttach } : {}) };
+        },
+    };
+}
+/** Default `publish-image` capability, backed by the real `CloudExecutor`. */
+export const publishImageCapability = createPublishImageCapability();
+// ── load-image-on-host (host backend) ───────────────────────────────────────
+/** Default on-host tarball destination when `hostPath` is omitted, derived from the archive path's basename. */
+function defaultHostPath(from) {
+    const base = archiveRelativePath(from).split("/").pop() ?? "image.tar";
+    return `/tmp/chant-archive/${base}`;
+}
+/**
+ * Copy the image tarball straight onto a host and `docker load` it there —
+ * genuinely registry-free promotion (#564): no `docker.push`, no ECR login,
+ * no registry ever in the path. Still promotes **by digest**: the tarball
+ * copied is the exact archive artifact `docker-build` produced, so the image
+ * loaded on the host is byte-identical to the one tested in any other
+ * environment, satisfying the same build-once invariant `publish-image`
+ * does. No rollback, for the same reason `publish-image` declares none: an
+ * already-loaded, content-addressed image sitting in a host's local Docker
+ * store is not itself a problem to compensate.
+ *
+ * See docs/components/build-archive.mdx#registry-less-caveat: this makes
+ * *your built* image registry-free. Third-party images a compose file
+ * references (`postgres:16`, `redis`) still pull from their upstream
+ * registry at `compose up` unless they are archived and loaded the same way.
+ */
+export function createLoadImageOnHostCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "load-image-on-host",
+        async run(_ctx, input) {
+            if (!input.host)
+                throw new Error(`load-image-on-host "${input.from}": "host" is required`);
+            const from = archiveRelativePath(input.from);
+            const to = input.hostPath ?? defaultHostPath(input.from);
+            await executor.host.copyFile({ host: input.host, from, to });
+            const { digest } = await executor.host.dockerLoad({ host: input.host, path: to });
+            return { digest, uri: `host:${input.host}#${digest}` };
+        },
+    };
+}
+/** Default `load-image-on-host` capability, backed by the real `CloudExecutor`. */
+export const loadImageOnHostCapability = createLoadImageOnHostCapability();
+/**
+ * Resolve which publish backend an environment uses, given its declared
+ * `kind` (`$env.publish.kind` in the component's env config — see
+ * docs/components/build-archive.mdx#backend-selection-is-per-environment).
+ * The decision is per environment, not per component: the same component's
+ * `Publish` phase runs `publish-image` against dev's ECR and
+ * `load-image-on-host` against a locked-down prod host, with no change to
+ * the component's own composition — only the env config `kind` differs.
+ *
+ * Accepts an optional registry of backends so a caller can extend the set
+ * (e.g. a third-party plugin registering another `PublishImageBackend`)
+ * without this function needing to change; defaults to the two starter-set
+ * backends built above.
+ */
+export function selectPublishBackend(kind, backends = {
+    "publish-image": publishImageCapability,
+    "load-image-on-host": loadImageOnHostCapability,
+}) {
+    const backend = backends[kind];
+    if (!backend) {
+        throw new Error(`no publish backend registered for kind "${kind}" (known: ${Object.keys(backends).sort().join(", ")})`);
+    }
+    return backend;
+}
+/** Promote a non-image artifact (jar, zip, arbitrary asset) from the archive to S3/CodeArtifact. */
+/**
+ * Publish a single archive artifact (a jar, zip, or asset) to S3 via `aws s3 cp`
+ * (endpoint-aware through the `CloudExecutor`). Returns the object's URI —
+ * referenced downstream as `@<component>.publish.uri` — and a content digest of
+ * the exact bytes uploaded.
+ */
+export function createPublishArtifactCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "publish-artifact",
+        async run(_ctx, input) {
+            const localPath = archiveRelativePath(input.from);
+            const digest = `sha256:${createHash("sha256").update(readFileSync(localPath)).digest("hex")}`;
+            const basename = localPath.split("/").pop() ?? localPath;
+            const uri = input.to.endsWith("/") ? `${input.to}${basename}` : input.to;
+            await executor.s3.cp({ from: localPath, to: uri });
+            return { uri, digest };
+        },
+    };
+}
+/** Default `publish-artifact` capability, backed by the real `CloudExecutor`. */
+export const publishArtifactCapability = createPublishArtifactCapability();
+/** Alias for `publish-artifact` — same capability, the docs/epic use both names for the same verb. */
+export const publishAssetCapability = publishArtifactCapability;