@intentius/chant 0.124.45 → 0.124.48

package/dist/components/verbs/publish-artifact.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `publish-artifact` (aliased `publish-asset`): the object-storage half of the
+ * publish family, owned by core (#4408), the same way `publish-image` is.
+ * "Put this archive file at the deploy target" is one agnostic verb; what
+ * differs per cloud is the upload. Each cloud lexicon contributes that as an
+ * {@link ArtifactStorageBackend} through `CapabilityPlugin.storageBackends()`
+ * (aws: S3, azure: Blob, gcp: GCS), and the environment picks one (see
+ * {@link selectStorageBackend}).
+ *
+ * This is a sibling of `registryBackends()` rather than a reuse of it: a
+ * registry backend only logs a docker client in, while a storage backend
+ * moves bytes, and the two are matched against different destinations.
+ *
+ * Core computes the content digest and the final object URI; the backend only
+ * uploads. No rollback.
+ */
+import type { Capability } from "../capability.js";
+export interface PublishArtifactInput {
+    /** Path of the artifact inside the build archive (e.g. a jar or zip). */
+    from: string;
+    /** Destination (e.g. `$env.s3` resolved by the orchestrator). A trailing `/` appends the file's basename. */
+    to: string;
+    /** Which storage backend to use ("s3", "azure-blob", "gcs"). Normally left out: `$env.publish.backend` or the destination URI picks it. */
+    backend?: string;
+}
+export interface PublishArtifactOutput {
+    /** Location the artifact was published to, referenced downstream as `@<component>.publish.uri`. */
+    uri: string;
+    /** Content hash of the published artifact. */
+    digest: string;
+}
+/** A cloud's way of putting one local file at a storage URI. */
+export interface ArtifactStorageBackend {
+    /** Stable name an environment selects by: "s3", "azure-blob", "gcs". */
+    readonly name: string;
+    /** True when this backend owns the destination URI. */
+    matches(uri: string): boolean;
+    /** Upload the local file `from` to the full object URI `to`. */
+    upload(args: {
+        from: string;
+        to: string;
+    }): Promise<void>;
+}
+export declare class StorageBackendError extends Error {
+    constructor(message: string);
+}
+/**
+ * Pick the storage backend for one publish. Order: the step's `backend`, then
+ * the environment's `ctx.vars.publish.backend`, then the single backend whose
+ * `matches` claims the destination, then the only backend there is.
+ */
+export declare function selectStorageBackend(backends: readonly ArtifactStorageBackend[], uri: string, named?: string): ArtifactStorageBackend;
+/** Implemented by a capability that wants the plugins' storage backends injected when a registry is built. */
+export interface StorageBackendConsumer {
+    withStorageBackends(backends: readonly ArtifactStorageBackend[]): Capability<never, unknown>;
+}
+export declare function isStorageBackendConsumer(value: unknown): value is StorageBackendConsumer;
+export type PublishArtifactCapability = Capability<PublishArtifactInput, PublishArtifactOutput> & StorageBackendConsumer;
+/** Build the `publish-artifact` verb over the storage backends available. */
+export declare function createPublishArtifactCapability(options?: {
+    backends?: readonly ArtifactStorageBackend[];
+}): PublishArtifactCapability;
+/** The starter plugin's `publish-artifact`: storage backends injected from the loaded plugins. */
+export declare const publishArtifactCapability: PublishArtifactCapability;
+//# sourceMappingURL=publish-artifact.d.ts.map

package/dist/components/verbs/publish-artifact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-artifact.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/publish-artifact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,6GAA6G;IAC7G,EAAE,EAAE,MAAM,CAAC;IACX,2IAA2I;IAC3I,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,mGAAmG;IACnG,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,gEAAgE;IAChE,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,EAC3C,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,GACb,sBAAsB,CAsBxB;AAED,8GAA8G;AAC9G,MAAM,WAAW,sBAAsB;IACrC,mBAAmB,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;CAC9F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,sBAAsB,CAExF;AAED,MAAM,MAAM,yBAAyB,GAAG,UAAU,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,GAAG,sBAAsB,CAAC;AAEzH,6EAA6E;AAC7E,wBAAgB,+BAA+B,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,SAAS,sBAAsB,EAAE,CAAA;CAAO,GAAG,yBAAyB,CAkBzI;AAED,kGAAkG;AAClG,eAAO,MAAM,yBAAyB,EAAE,yBAA6D,CAAC"}

package/dist/components/verbs/publish-artifact.js

@@ -0,0 +1,74 @@
+/**
+ * `publish-artifact` (aliased `publish-asset`): the object-storage half of the
+ * publish family, owned by core (#4408), the same way `publish-image` is.
+ * "Put this archive file at the deploy target" is one agnostic verb; what
+ * differs per cloud is the upload. Each cloud lexicon contributes that as an
+ * {@link ArtifactStorageBackend} through `CapabilityPlugin.storageBackends()`
+ * (aws: S3, azure: Blob, gcp: GCS), and the environment picks one (see
+ * {@link selectStorageBackend}).
+ *
+ * This is a sibling of `registryBackends()` rather than a reuse of it: a
+ * registry backend only logs a docker client in, while a storage backend
+ * moves bytes, and the two are matched against different destinations.
+ *
+ * Core computes the content digest and the final object URI; the backend only
+ * uploads. No rollback.
+ */
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { archiveRelativePath } from "./build-archive.js";
+export class StorageBackendError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StorageBackendError";
+    }
+}
+/**
+ * Pick the storage backend for one publish. Order: the step's `backend`, then
+ * the environment's `ctx.vars.publish.backend`, then the single backend whose
+ * `matches` claims the destination, then the only backend there is.
+ */
+export function selectStorageBackend(backends, uri, named) {
+    const names = backends.map((b) => b.name).sort().join(", ") || "none";
+    if (named) {
+        const found = backends.find((b) => b.name === named);
+        if (!found) {
+            throw new StorageBackendError(`publish-artifact: no storage backend "${named}" is registered (available: ${names}); declare the lexicon that contributes it in chant.config.ts`);
+        }
+        return found;
+    }
+    const matched = backends.filter((b) => b.matches(uri));
+    if (matched.length === 1)
+        return matched[0];
+    if (matched.length > 1) {
+        throw new StorageBackendError(`publish-artifact: destination "${uri}" matches several backends (${matched.map((b) => b.name).join(", ")}); set $env.publish.backend`);
+    }
+    if (backends.length === 1)
+        return backends[0];
+    throw new StorageBackendError(`publish-artifact: cannot tell which storage backend serves "${uri}" (available: ${names}); set $env.publish.backend`);
+}
+export function isStorageBackendConsumer(value) {
+    return typeof value === "object" && value !== null && typeof value.withStorageBackends === "function";
+}
+/** Build the `publish-artifact` verb over the storage backends available. */
+export function createPublishArtifactCapability(options = {}) {
+    const backends = options.backends ?? [];
+    return {
+        kind: "publish-artifact",
+        withStorageBackends(next) {
+            return createPublishArtifactCapability({ backends: next });
+        },
+        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;
+            const envBackend = ctx.vars?.publish?.backend;
+            const backend = selectStorageBackend(backends, uri, input.backend ?? (typeof envBackend === "string" ? envBackend : undefined));
+            await backend.upload({ from: localPath, to: uri });
+            return { uri, digest };
+        },
+    };
+}
+/** The starter plugin's `publish-artifact`: storage backends injected from the loaded plugins. */
+export const publishArtifactCapability = createPublishArtifactCapability();

package/dist/components/verbs/publish-image.d.ts

@@ -0,0 +1,129 @@
+/**
+ * `publish-image`: the registry half of the publish family, owned by core
+ * (#3142, #3143). "Make the image available at the deploy target" is one
+ * agnostic verb; what differs per cloud is how the local docker client logs in
+ * to the registry. Each cloud lexicon contributes that as a
+ * {@link RegistryLoginBackend} through `CapabilityPlugin.registryBackends()`
+ * (aws: ECR, azure: ACR, gcp: Artifact Registry), and the environment picks
+ * one (see {@link selectRegistryBackend}). So a project may declare several
+ * clouds without two plugins registering the same verb.
+ *
+ * Promotion is by digest and unchanged from the aws-only implementation: load
+ * the archived tarball, tag for the destination, log in, push, read the digest
+ * back from the push. Optional SBOM/BOM referrers attach via `oras`, best
+ * effort. No rollback: a pushed, content-addressed image is not something to
+ * undo. See docs/components/build-archive.mdx.
+ */
+import type { Capability } from "../capability.js";
+import { type DockerClient } from "./cloud-executor.js";
+import { type ProcessRunner } from "./process-runner.js";
+/**
+ * Common input shape both image-publish backends accept (`publish-image` here, `load-image-on-host` in the aws lexicon): promote the image
+ * bytes at archive path `from` to wherever the deploy target can consume
+ * them. `to` (registry) and `host` (bare host) are each meaningful to only
+ * one backend, so a component authors one step shape (see
+ * docs/components/build-archive.mdx) and the env-selected backend (see
+ * `selectPublishBackend` below) reads whichever field it needs — the
+ * unselected backend's field is simply unused, never a pipeline fork.
+ */
+export interface PublishImageInput {
+    /** Path of the image tarball inside the build archive (as produced by `docker-build`; an `archive:`-prefixed reference is accepted and stripped). */
+    from: string;
+    /** Destination registry — required by `publish-image`, ignored by `load-image-on-host` (e.g. `$env.registry` resolved by the orchestrator). */
+    to?: string;
+    /** Target host — required by `load-image-on-host`, ignored by `publish-image` (SSM instance id, hostname, or host group). */
+    host?: string;
+    /** Destination path for the tarball on the host, used only by `load-image-on-host`. Default: `/tmp/chant-archive/<basename of from>`. */
+    hostPath?: string;
+    /**
+     * Which registry login backend to use ("ecr", "acr", "artifact-registry").
+     * Normally left out: the environment config (`ctx.vars.publish.backend`) or
+     * the registry host picks it.
+     */
+    backend?: string;
+    /** Additional tags to apply alongside the digest, used only by `publish-image`. */
+    tags?: string[];
+    /**
+     * #610: the artifact's software SBOM (typically wired from a prior
+     * `generate-sbom` step's `sbom` output — see ./sbom.ts's
+     * `GenerateSbomOutput`) to attach as an OCI referrer on the pushed image
+     * digest, via `oras attach`. Used only by `publish-image`; ignored by
+     * `load-image-on-host` (registry-less — nothing to attach to). Omit to
+     * skip the attach step entirely (the archive-carried copy remains the
+     * SBOM's home either way).
+     */
+    sbom?: {
+        bytes: string;
+        mediaType: string;
+    };
+    /**
+     * #610: the component-level aggregate BOM (wired from
+     * ./component-bom.ts's `aggregateComponentBom` output), attached as a
+     * second OCI referrer alongside `sbom` when supplied. Optional and
+     * independent of `sbom` — a caller may attach either, both, or neither.
+     */
+    componentBom?: {
+        bytes: string;
+        mediaType: string;
+    };
+}
+/** Result of `publish-image`'s best-effort OCI-referrer attach step (#610) — always present when `input.sbom`/`input.componentBom` was supplied, `undefined` when neither was (nothing to attach, attach step skipped entirely). */
+export interface ReferrerAttachResult {
+    /** True once every requested attach (`sbom`, `componentBom`) succeeded. `false` if `oras` was unavailable or any `oras attach` invocation failed. */
+    attached: boolean;
+    /** Human-readable reason `attached` is `false` (e.g. "oras is not installed"), omitted when `attached` is `true`. */
+    reason?: string;
+}
+export interface PublishImageOutput {
+    /** Content-addressed digest of the promoted image (`sha256:...`) — what the apply step references. */
+    digest: string;
+    /** Image reference the apply step can pull/run: `registry/repo@sha256:...` for `publish-image`, a host-local reference for `load-image-on-host`. */
+    uri: string;
+    /** #610: outcome of the best-effort SBOM/component-BOM referrer attach, when `input.sbom`/`input.componentBom` was supplied. `undefined` for `load-image-on-host` (no attach concept — registry-less) and for `publish-image` calls that supplied neither. */
+    referrerAttach?: ReferrerAttachResult;
+}
+/**
+ * Common shape both image-publish backends satisfy: promote the image bytes
+ * held in the build archive to wherever the deploy target can consume them,
+ * and return the identity the apply step references. The backend is
+ * selected per environment (`selectPublishBackend`), never per component.
+ */
+export type PublishImageBackend = Capability<PublishImageInput, PublishImageOutput>;
+/** A cloud's way of authenticating the local docker client to its registry. */
+export interface RegistryLoginBackend {
+    /** Stable name an environment selects by: "ecr", "acr", "artifact-registry". */
+    readonly name: string;
+    /** True when this backend owns the registry host (used when the environment does not name one). */
+    matches(registry: string): boolean;
+    /** Authenticate docker against `registry` (host part of the destination). */
+    login(registry: string): Promise<void>;
+}
+export declare class RegistryBackendError extends Error {
+    constructor(message: string);
+}
+/**
+ * Pick the login backend for one publish. Order: the step's `backend`, then the
+ * environment's `ctx.vars.publish.backend`, then the single backend whose
+ * `matches` claims the registry host, then the only backend there is.
+ */
+export declare function selectRegistryBackend(backends: readonly RegistryLoginBackend[], registry: string, named?: string): RegistryLoginBackend;
+/** Implemented by a capability that wants the plugins' registry backends injected when a registry is built. */
+export interface RegistryBackendConsumer {
+    withRegistryBackends(backends: readonly RegistryLoginBackend[]): Capability<never, unknown>;
+}
+export declare function isRegistryBackendConsumer(value: unknown): value is RegistryBackendConsumer;
+export interface PublishImageOptions {
+    docker: DockerClient;
+    backends?: readonly RegistryLoginBackend[];
+    processRunner?: ProcessRunner;
+}
+export type PublishImageCapability = PublishImageBackend & RegistryBackendConsumer;
+/**
+ * Build the `publish-image` verb over a docker client and the registry login
+ * backends available. Load, tag, log in via the selected backend, push, and
+ * return the pushed digest.
+ */
+export declare function createPublishImageCapability(options: PublishImageOptions): PublishImageCapability;
+/** The starter plugin's `publish-image`: real docker, backends injected from the loaded plugins. */
+export declare const publishImageCapability: PublishImageCapability;
+//# sourceMappingURL=publish-image.d.ts.map

package/dist/components/verbs/publish-image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-image.d.ts","sourceRoot":"","sources":["../../../src/components/verbs/publish-image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAA2B,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE/E;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,qJAAqJ;IACrJ,IAAI,EAAE,MAAM,CAAC;IACb,+IAA+I;IAC/I,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6HAA6H;IAC7H,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yIAAyI;IACzI,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C;;;;;OAKG;IACH,YAAY,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACrD;AAED,oOAAoO;AACpO,MAAM,WAAW,oBAAoB;IACnC,qJAAqJ;IACrJ,QAAQ,EAAE,OAAO,CAAC;IAClB,qHAAqH;IACrH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,sGAAsG;IACtG,MAAM,EAAE,MAAM,CAAC;IACf,oJAAoJ;IACpJ,GAAG,EAAE,MAAM,CAAC;IACZ,8PAA8P;IAC9P,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC;AAED;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAAC;AAIpF,+EAA+E;AAC/E,MAAM,WAAW,oBAAoB;IACnC,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mGAAmG;IACnG,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,6EAA6E;IAC7E,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,EACzC,QAAQ,EAAE,MAAM,EAChB,KAAK,CAAC,EAAE,MAAM,GACb,oBAAoB,CAsBtB;AAED,+GAA+G;AAC/G,MAAM,WAAW,uBAAuB;IACtC,oBAAoB,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;CAC7F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAE1F;AA4DD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC3C,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AAED,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,GAAG,uBAAuB,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,mBAAmB,GAAG,sBAAsB,CAqCjG;AAED,oGAAoG;AACpG,eAAO,MAAM,sBAAsB,EAAE,sBAA6E,CAAC"}

package/dist/components/verbs/publish-image.js

@@ -0,0 +1,145 @@
+/**
+ * `publish-image`: the registry half of the publish family, owned by core
+ * (#3142, #3143). "Make the image available at the deploy target" is one
+ * agnostic verb; what differs per cloud is how the local docker client logs in
+ * to the registry. Each cloud lexicon contributes that as a
+ * {@link RegistryLoginBackend} through `CapabilityPlugin.registryBackends()`
+ * (aws: ECR, azure: ACR, gcp: Artifact Registry), and the environment picks
+ * one (see {@link selectRegistryBackend}). So a project may declare several
+ * clouds without two plugins registering the same verb.
+ *
+ * Promotion is by digest and unchanged from the aws-only implementation: load
+ * the archived tarball, tag for the destination, log in, push, read the digest
+ * back from the push. Optional SBOM/BOM referrers attach via `oras`, best
+ * effort. No rollback: a pushed, content-addressed image is not something to
+ * undo. See docs/components/build-archive.mdx.
+ */
+import { archiveRelativePath } from "./build-archive.js";
+import { realDocker } from "./cloud-executor.js";
+import { defaultProcessRunner, q } from "./process-runner.js";
+export class RegistryBackendError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RegistryBackendError";
+    }
+}
+/**
+ * Pick the login backend for one publish. Order: the step's `backend`, then the
+ * environment's `ctx.vars.publish.backend`, then the single backend whose
+ * `matches` claims the registry host, then the only backend there is.
+ */
+export function selectRegistryBackend(backends, registry, named) {
+    const names = backends.map((b) => b.name).sort().join(", ") || "none";
+    if (named) {
+        const found = backends.find((b) => b.name === named);
+        if (!found) {
+            throw new RegistryBackendError(`publish-image: no registry backend "${named}" is registered (available: ${names}); declare the lexicon that contributes it in chant.config.ts`);
+        }
+        return found;
+    }
+    const matched = backends.filter((b) => b.matches(registry));
+    if (matched.length === 1)
+        return matched[0];
+    if (matched.length > 1) {
+        throw new RegistryBackendError(`publish-image: registry "${registry}" matches several backends (${matched.map((b) => b.name).join(", ")}); set $env.publish.backend`);
+    }
+    if (backends.length === 1)
+        return backends[0];
+    throw new RegistryBackendError(`publish-image: cannot tell which registry backend serves "${registry}" (available: ${names}); set $env.publish.backend`);
+}
+export function isRegistryBackendConsumer(value) {
+    return typeof value === "object" && value !== null && typeof value.withRegistryBackends === "function";
+}
+// ── publish-image ────────────────────────────────────────────────────────────
+/**
+ * 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 };
+}
+/**
+ * Build the `publish-image` verb over a docker client and the registry login
+ * backends available. Load, tag, log in via the selected backend, push, and
+ * return the pushed digest.
+ */
+export function createPublishImageCapability(options) {
+    const { docker } = options;
+    const backends = options.backends ?? [];
+    const processRunner = options.processRunner ?? defaultProcessRunner();
+    return {
+        kind: "publish-image",
+        withRegistryBackends(next) {
+            return createPublishImageCapability({ docker, processRunner, backends: next });
+        },
+        async run(ctx, input) {
+            if (!input.to)
+                throw new Error(`publish-image "${input.from}": "to" (destination registry) is required`);
+            const repo = input.to.replace(/\/+$/, "");
+            const registry = repo.split("/")[0];
+            const envBackend = ctx.vars?.publish?.backend;
+            const backend = selectRegistryBackend(backends, registry, input.backend ?? (typeof envBackend === "string" ? envBackend : undefined));
+            // `docker load` reports the archived image's local reference: a name:tag
+            // for a tagged build, or an image id. It is a valid `docker tag` source
+            // but never a registry digest, so the promoted digest is read back from
+            // the push below.
+            const { digest: localRef } = await docker.load({ inFile: archiveRelativePath(input.from) });
+            // Publish under a tag: docker can neither tag nor push a digest-qualified
+            // reference, so the transport is a tag and the stable identifier is the
+            // digest the push returns.
+            const pushRef = `${repo}:latest`;
+            await docker.tag({ source: localRef, target: pushRef });
+            await backend.login(registry);
+            const { digest: pushed } = await docker.push({ image: pushRef });
+            const digest = pushed.includes("@") ? pushed.slice(pushed.indexOf("@") + 1) : pushed;
+            for (const tag of input.tags ?? []) {
+                const tagged = `${repo}:${tag}`;
+                await docker.tag({ source: localRef, target: tagged });
+                await docker.push({ image: tagged });
+            }
+            const referrerAttach = await attachReferrers(processRunner, `${repo}@${digest}`, input);
+            return { digest, uri: `${repo}@${digest}`, ...(referrerAttach ? { referrerAttach } : {}) };
+        },
+    };
+}
+/** The starter plugin's `publish-image`: real docker, backends injected from the loaded plugins. */
+export const publishImageCapability = createPublishImageCapability({ docker: realDocker });

package/dist/config-environments.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The pure helpers over a loaded config's `environments` and `ownership`:
+ * names, patterns, endpoints and the ownership stack. ./config.ts re-exports
+ * them. They import nothing at runtime, so ./components/pr-environment.ts and
+ * ./live-endpoint.ts use them without bundling the config loader.
+ */
+import type { ChantConfig } from "./config.js";
+/**
+ * One project-declared environment (chant #1166). Historically always a bare
+ * name (`"floci"`); an entry can now instead carry the endpoint that
+ * environment's `--live` reads should target (`{ name: "floci", endpoint:
+ * "http://localhost:4566" }`), so a project pointed at a local emulator is
+ * self-sufficient — no ambient `AWS_ENDPOINT_URL` export required to avoid
+ * silently querying real AWS. See {@link environmentName}, {@link
+ * environmentNames}, {@link environmentEndpoint} below, and
+ * `./live-endpoint.ts`'s `applyLiveEndpoint`, the CLI-side consumer.
+ *
+ * The array's order is the member's promotion order (#4030, see
+ * `./workspace/promotion-order.ts`), and `canary: true` marks a step as the
+ * canary step of that order. The canary is declared and surfaced; chant does
+ * not yet act on it.
+ *
+ * `executor` names the forge and the committed workflow that deploys the
+ * environment (#4402), so a reader such as behold knows a release there runs
+ * through CI rather than a local `chant run`. chant declares and prints it
+ * (`chant workspace graph --composites`); it never dispatches it.
+ */
+export type EnvironmentDeclaration = string | {
+    name: string;
+    endpoint?: string;
+    canary?: boolean;
+    executor?: EnvironmentExecutor;
+};
+/** The forges an environment's executor can name (#4402). */
+export declare const EXECUTOR_FORGES: readonly ["github", "gitlab", "forgejo"];
+/** The forge workflow that deploys one environment (#4402). */
+export interface EnvironmentExecutor {
+    forge: (typeof EXECUTOR_FORGES)[number];
+    /** The committed workflow file the forge runs, such as `deploy-prod.yml` under `.github/workflows/`, or `.gitlab-ci.yml`. */
+    workflow: string;
+}
+/**
+ * `ownership.env`: a literal environment identity, or a reference to a
+ * declared build parameter whose resolved value becomes the identity (#1396).
+ */
+export type OwnershipEnv = string | {
+    param: string;
+};
+/** The declared name of one `environments` entry, whichever form it takes. */
+export declare function environmentName(entry: EnvironmentDeclaration): string;
+/**
+ * Every declared environment's name, in `environments` order. `undefined` in,
+ * `undefined` out — mirrors the field itself being optional, so a caller that
+ * already writes `config.environments?.something` can keep doing so:
+ * `environmentNames(config.environments)?.includes(name)`.
+ */
+export declare function environmentNames(environments: EnvironmentDeclaration[] | undefined): string[] | undefined;
+/**
+ * Whether a declared environment name is a glob pattern rather than a literal
+ * (#1221) — it contains at least one `*`.
+ */
+export declare function isEnvironmentPattern(declaredName: string): boolean;
+/**
+ * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
+ * characters (possibly empty); everything else matches itself. Deliberately
+ * the whole surface — no `?`, no character classes, no regex. A pattern with
+ * no `*` degenerates to string equality.
+ */
+export declare function matchesEnvironmentPattern(pattern: string, name: string): boolean;
+/**
+ * Environment-membership test (#1221): is `name` covered by this project's
+ * declared `environments`? A literal entry matches by equality; an entry
+ * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
+ * Literals are checked first across the whole list, then patterns — so a
+ * name that is declared outright never depends on pattern order. `undefined`
+ * / empty `environments` returns `false`; callers that treat "no declared
+ * environments" as "anything goes" (e.g. {@link unknownEnvError} in
+ * `./env.ts`) guard that case themselves.
+ */
+export declare function matchesDeclaredEnvironment(environments: EnvironmentDeclaration[] | undefined, name: string): boolean;
+/**
+ * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
+ * entry, an entry with no `endpoint` set, or a name this project doesn't
+ * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
+ * it injects this into the ambient env var each observing lexicon's CLI
+ * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
+ * ambient always wins.
+ *
+ * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
+ * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
+ * entry always wins over a pattern — declaring `pr-special` alongside
+ * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
+ */
+export declare function environmentEndpoint(environments: EnvironmentDeclaration[] | undefined, name: string): string | undefined;
+/**
+ * The executor `name` declares (#4402), resolved like {@link
+ * environmentEndpoint}: a literal entry wins over a pattern, and a literal
+ * entry with no executor does not fall through to a pattern's.
+ */
+export declare function environmentExecutor(environments: EnvironmentDeclaration[] | undefined, name: string): EnvironmentExecutor | undefined;
+/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
+export declare function isOwnershipParamRef(env: OwnershipEnv | undefined): env is {
+    param: string;
+};
+/**
+ * The ownership stack identity alone — `ownership.stack` when marking is on
+ * (no `stack`, or `enabled: false`, means off). For callers that need the
+ * stack and nothing else (a field manager, a prune selector) and so have no
+ * build parameters to resolve `env` against.
+ */
+export declare function resolveOwnershipStack(config: Pick<ChantConfig, "ownership">): string | undefined;
+//# sourceMappingURL=config-environments.d.ts.map

package/dist/config-environments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-environments.d.ts","sourceRoot":"","sources":["../src/config-environments.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAA;CAAE,CAAC;AAEpI,6DAA6D;AAC7D,eAAO,MAAM,eAAe,YAAI,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAU,CAAC;AAExE,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;IACxC,6HAA6H;IAC7H,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAErE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,sBAAsB,EAAE,GAAG,SAAS,GAAG,MAAM,EAAE,GAAG,SAAS,CAEzG;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAehF;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,YAAY,EAAE,sBAAsB,EAAE,GAAG,SAAS,EAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAIT;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,sBAAsB,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKxH;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,sBAAsB,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAKrI;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,GAAG,GAAG,IAAI;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAE3F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,MAAM,GAAG,SAAS,CAIhG"}

package/dist/config-environments.js

@@ -0,0 +1,114 @@
+/**
+ * The pure helpers over a loaded config's `environments` and `ownership`:
+ * names, patterns, endpoints and the ownership stack. ./config.ts re-exports
+ * them. They import nothing at runtime, so ./components/pr-environment.ts and
+ * ./live-endpoint.ts use them without bundling the config loader.
+ */
+/** The forges an environment's executor can name (#4402). */
+export const EXECUTOR_FORGES = ["github", "gitlab", "forgejo"];
+/** The declared name of one `environments` entry, whichever form it takes. */
+export function environmentName(entry) {
+    return typeof entry === "string" ? entry : entry.name;
+}
+/**
+ * Every declared environment's name, in `environments` order. `undefined` in,
+ * `undefined` out — mirrors the field itself being optional, so a caller that
+ * already writes `config.environments?.something` can keep doing so:
+ * `environmentNames(config.environments)?.includes(name)`.
+ */
+export function environmentNames(environments) {
+    return environments?.map(environmentName);
+}
+/**
+ * Whether a declared environment name is a glob pattern rather than a literal
+ * (#1221) — it contains at least one `*`.
+ */
+export function isEnvironmentPattern(declaredName) {
+    return declaredName.includes("*");
+}
+/**
+ * Anchored `*`-glob match (#1221): each `*` in `pattern` matches any run of
+ * characters (possibly empty); everything else matches itself. Deliberately
+ * the whole surface — no `?`, no character classes, no regex. A pattern with
+ * no `*` degenerates to string equality.
+ */
+export function matchesEnvironmentPattern(pattern, name) {
+    const parts = pattern.split("*");
+    if (parts.length === 1)
+        return pattern === name;
+    const first = parts[0];
+    const last = parts[parts.length - 1];
+    if (!name.startsWith(first))
+        return false;
+    let cursor = first.length;
+    for (let i = 1; i < parts.length - 1; i++) {
+        const part = parts[i];
+        if (part === "")
+            continue;
+        const at = name.indexOf(part, cursor);
+        if (at === -1)
+            return false;
+        cursor = at + part.length;
+    }
+    return name.length - cursor >= last.length && name.endsWith(last);
+}
+/**
+ * Environment-membership test (#1221): is `name` covered by this project's
+ * declared `environments`? A literal entry matches by equality; an entry
+ * containing `*` matches as a glob pattern (`"pr-*"` covers `pr-42`).
+ * Literals are checked first across the whole list, then patterns — so a
+ * name that is declared outright never depends on pattern order. `undefined`
+ * / empty `environments` returns `false`; callers that treat "no declared
+ * environments" as "anything goes" (e.g. {@link unknownEnvError} in
+ * `./env.ts`) guard that case themselves.
+ */
+export function matchesDeclaredEnvironment(environments, name) {
+    const names = environmentNames(environments) ?? [];
+    if (names.includes(name))
+        return true;
+    return names.some((declared) => isEnvironmentPattern(declared) && matchesEnvironmentPattern(declared, name));
+}
+/**
+ * The endpoint `name` declares (chant #1166) — `undefined` for a bare-string
+ * entry, an entry with no `endpoint` set, or a name this project doesn't
+ * declare at all. `./live-endpoint.ts`'s `applyLiveEndpoint` is the consumer:
+ * it injects this into the ambient env var each observing lexicon's CLI
+ * shell-out reads (e.g. `AWS_ENDPOINT_URL`), unless that var is already set —
+ * ambient always wins.
+ *
+ * A pattern entry (#1221) can carry an endpoint too: `{ name: "pr-*",
+ * endpoint }` supplies the endpoint for every `pr-<n>` environment. A literal
+ * entry always wins over a pattern — declaring `pr-special` alongside
+ * `pr-*` resolves `pr-special` to the literal entry's endpoint (or none).
+ */
+export function environmentEndpoint(environments, name) {
+    const found = environments?.find((e) => environmentName(e) === name) ??
+        environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+    return found && typeof found !== "string" ? found.endpoint : undefined;
+}
+/**
+ * The executor `name` declares (#4402), resolved like {@link
+ * environmentEndpoint}: a literal entry wins over a pattern, and a literal
+ * entry with no executor does not fall through to a pattern's.
+ */
+export function environmentExecutor(environments, name) {
+    const found = environments?.find((e) => environmentName(e) === name) ??
+        environments?.find((e) => isEnvironmentPattern(environmentName(e)) && matchesEnvironmentPattern(environmentName(e), name));
+    return found && typeof found !== "string" ? found.executor : undefined;
+}
+/** Whether an `ownership.env` entry is a build-parameter reference rather than a literal. */
+export function isOwnershipParamRef(env) {
+    return typeof env === "object" && env !== null && typeof env.param === "string";
+}
+/**
+ * The ownership stack identity alone — `ownership.stack` when marking is on
+ * (no `stack`, or `enabled: false`, means off). For callers that need the
+ * stack and nothing else (a field manager, a prune selector) and so have no
+ * build parameters to resolve `env` against.
+ */
+export function resolveOwnershipStack(config) {
+    const o = config.ownership;
+    if (!o || !o.stack || o.enabled === false)
+        return undefined;
+    return o.stack;
+}