@intentius/chant 0.124.13 → 0.124.15

package/dist/components/verbs/process-runner.js

@@ -0,0 +1,78 @@
+/**
+ * Injectable external-process boundary for the #610 deep-scan/attach
+ * backends (`ToolSbomGenerator` in ./tool-sbom-generator.ts,
+ * `OrasReferrerLookup` in ../../lifecycle/oras-referrer-lookup.ts, and
+ * `publish-image`'s referrer-attach step in ./publish.ts). Mirrors
+ * ./cloud-executor.ts's `CloudExecutor` pattern exactly: production code gets
+ * a `RealProcessRunner` that shells out via `node:child_process`, tests get a
+ * `MockProcessRunner` (./__tests__/mock-process-runner.ts) that records calls
+ * and returns canned output — no live `syft`/`buildx`/`cyclonedx-maven`/
+ * `cdxgen`/`oras`, ever, in a test run.
+ *
+ * Kept deliberately narrower than `CloudExecutor`: every one of #610's real
+ * backends reduces to "run this external CLI, capture stdout, tell me if the
+ * tool exists" — a single `ProcessRunner` interface (`run` + `available`)
+ * covers `syft`, `docker buildx`, `cyclonedx-maven`, `cdxgen`, and `oras`
+ * alike, rather than one bespoke client per tool the way `CloudExecutor`
+ * models AWS's genuinely distinct service APIs (CloudFormation, ECS,
+ * CodeDeploy, ...).
+ */
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+const execAsync = promisify(exec);
+/** Shell-quote a single argument for POSIX shells (wrap in single quotes, escaping embedded ones) — same convention as ./cloud-executor.ts's `q`. */
+export function q(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+const realProcessRunner = {
+    async run(command, options) {
+        return execAsync(command, {
+            cwd: options?.cwd,
+            maxBuffer: options?.maxBuffer ?? 64 * 1024 * 1024,
+        });
+    },
+    async available(tool) {
+        try {
+            // `command -v` is POSIX-portable (works in sh/bash/zsh) and prints
+            // nothing to stderr for a normal miss, unlike `which` on some systems.
+            await execAsync(`command -v ${q(tool)}`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+/** Build a `ProcessRunner` that shells out for real via `node:child_process`. Never used in tests. */
+export function realProcessExecutor() {
+    return realProcessRunner;
+}
+/** Lazily-constructed process-wide default, mirroring ./cloud-executor.ts's `defaultCloudExecutor`. */
+let defaultRunner;
+/** The default `ProcessRunner` each real #610 backend falls back to when none is supplied. */
+export function defaultProcessRunner() {
+    if (!defaultRunner)
+        defaultRunner = realProcessExecutor();
+    return defaultRunner;
+}
+/**
+ * Thrown when a #610 real backend needs a CLI tool that `ProcessRunner.available`
+ * reports as absent — the "graceful, actionable error if the tool is absent"
+ * #610 asks for, distinct from a generic `Error` so callers (and tests) can
+ * assert on it specifically, mirroring `SbomGeneratorNotImplementedError`'s
+ * role in ./sbom-generator.ts.
+ */
+export class ToolNotAvailableError extends Error {
+    constructor(tool, purpose) {
+        super(`"${tool}" is not installed or not on PATH — required to ${purpose}. Install it and retry.`);
+        this.tool = tool;
+        this.purpose = purpose;
+        this.name = "ToolNotAvailableError";
+    }
+}
+/** Throw `ToolNotAvailableError` unless `tool` is available, per `runner.available`. Shared guard every #610 real backend calls before shelling out. */
+export async function requireTool(runner, tool, purpose) {
+    if (!(await runner.available(tool))) {
+        throw new ToolNotAvailableError(tool, purpose);
+    }
+}

package/dist/components/verbs/r2-sync.js

@@ -0,0 +1,93 @@
+/**
+ * `r2-sync` — bulk object upload to a Cloudflare R2 bucket (chant #1293,
+ * epic #1296), the direct analogue of `s3-sync`
+ * (lexicons/aws/src/components/apply.ts): same input shape (`from`/`to`/
+ * `delete`), same mutating-no-native-rollback disposition
+ * (`rollbackPolicy: "needs-opt-out"`, ../../lint/rules/comp/comp003-mutating-no-rollback.ts),
+ * learnable as the same idea per #1293's own verification bullet. See
+ * ./wrangler.ts's module doc for why this lives in core rather than a
+ * cloudflare lexicon.
+ *
+ * R2 has no first-party bulk-sync CLI the way S3 has `aws s3 sync`, but its
+ * API is S3-compatible, so it takes any S3-compatible sync tool — this wraps
+ * `rclone` (its `sync`/`copy` distinguish "mirror, deleting extras" from
+ * "upload only" exactly the way `s3-sync`'s `delete` flag does) through the
+ * same injectable `ProcessRunner` (./process-runner.ts) `./sign.ts` and
+ * `./wrangler.ts` use. No live `rclone`, no network, ever, in a test run —
+ * every test substitutes `MockProcessRunner`.
+ */
+import { defaultProcessRunner, q, requireTool } from "./process-runner.js";
+const RCLONE_TOOL = "rclone";
+/** Matches an `r2://bucket[/prefix]` destination — mirrors `s3-sync`'s `s3://bucket/prefix` shape. */
+const R2_URI_RE = /^r2:\/\/([^/]+)(?:\/(.*))?$/;
+/** Thrown when `R2SyncInput.to` is not an `r2://bucket[/prefix]` URI. */
+export class R2SyncInvalidDestinationError extends Error {
+    constructor(to) {
+        super(`r2-sync: destination "${to}" is not an "r2://bucket[/prefix]" URI — mirror s3-sync's "s3://bucket/prefix" shape.`);
+        this.to = to;
+        this.name = "R2SyncInvalidDestinationError";
+    }
+}
+/**
+ * Translate an `r2://bucket/prefix` destination to rclone's `<remote>:<path>`
+ * form. `remote` is the name of an rclone remote already configured against
+ * R2's S3-compatible endpoint (`<account-id>.r2.cloudflarestorage.com`) —
+ * out of this capability's scope the same way `s3-sync` doesn't configure
+ * AWS credentials; default `"r2"` is the conventional alias. Exported for
+ * tests, mirroring ./sign.ts's `buildSignArgs`.
+ */
+export function toRcloneDest(to, remote = "r2") {
+    const match = R2_URI_RE.exec(to);
+    if (!match)
+        throw new R2SyncInvalidDestinationError(to);
+    const [, bucket, prefix] = match;
+    return `${remote}:${bucket}${prefix ? `/${prefix}` : ""}`;
+}
+/**
+ * Build the `rclone` invocation for `input`. `rclone sync` deletes
+ * destination-only files by default (matching `s3-sync`'s opt-in `delete:
+ * true`); `rclone copy` never deletes (matching the `s3-sync` default) — so
+ * the verb dispatches on `input.delete` rather than passing a `--delete`
+ * flag rclone doesn't have. `-v` gives the per-file action lines
+ * `parseRcloneStats` reads. Exported for tests, mirroring ./sign.ts's
+ * `buildSignArgs`.
+ */
+export function buildR2SyncArgs(input) {
+    const dest = toRcloneDest(input.to, input.remote);
+    const verb = input.delete ? "sync" : "copy";
+    return `rclone ${verb} ${q(input.from)} ${q(dest)} -v`;
+}
+// rclone's `-v` per-file log lines end e.g. "path/to/file: Copied (new)",
+// "path/to/file: Copied (replaced existing)", "path/to/file: Deleted".
+const COPIED_NEW_RE = /: Copied \(new\)/g;
+const COPIED_REPLACED_RE = /: Copied \(replaced existing\)/g;
+const DELETED_RE = /: Deleted$/gm;
+/** Count uploaded/deleted objects out of `rclone -v`'s stdout. Exported for tests. */
+export function parseRcloneStats(stdout) {
+    const uploaded = (stdout.match(COPIED_NEW_RE) ?? []).length + (stdout.match(COPIED_REPLACED_RE) ?? []).length;
+    const deleted = (stdout.match(DELETED_RE) ?? []).length;
+    return { uploaded, deleted };
+}
+/**
+ * Bulk-sync a directory of objects to an R2 bucket via `rclone`
+ * (endpoint-aware only through the rclone remote's own config — this
+ * capability never touches R2 credentials directly). Mutating, no native
+ * undo (an overwritten or deleted object is gone), so — like `s3-sync` —
+ * `rollbackPolicy: "needs-opt-out"`: COMP003 requires the component to
+ * acknowledge the compensation gap explicitly (a `noRollback` reason, a
+ * component-level `rollback` phase, or a sibling `rollback-previous`/
+ * `snapshot-before` step).
+ */
+export function createR2SyncCapability(processRunner = defaultProcessRunner()) {
+    return {
+        kind: "r2-sync",
+        rollbackPolicy: "needs-opt-out",
+        async run(_ctx, input) {
+            await requireTool(processRunner, RCLONE_TOOL, `sync ${input.from} to ${input.to}`);
+            const { stdout } = await processRunner.run(buildR2SyncArgs(input));
+            return parseRcloneStats(stdout);
+        },
+    };
+}
+/** Default `r2-sync` capability, backed by the real `ProcessRunner`. */
+export const r2SyncCapability = createR2SyncCapability();

package/dist/components/verbs/reproducibility.js

@@ -0,0 +1,62 @@
+/**
+ * Per-artifact reproducibility + provenance record (#614, epic #551 follow-up
+ * to #613's BOM-doc model). Attaches to a `BuildArchiveEntry`
+ * (./build-archive.ts) alongside the BOM entries #613 already added, so every
+ * artifact in a build archive carries not just "what's in it" (the BOM) but
+ * also "can this be reproduced, and from what source."
+ *
+ * **Honesty over convenience.** A single blanket "reproducible: true/false"
+ * bit on a *component* would misrepresent a component that builds more than
+ * one artifact type — a synthesized IaC template and a container image are
+ * not equally reproducible, and collapsing them into one flag would either
+ * overstate the image's reproducibility or understate the template's. This
+ * module therefore records `basis` **per artifact entry**, never per
+ * component:
+ *
+ *  - `"deterministic-synthesis"` — chant's own synthesis produced this
+ *    artifact from declarative input (a `template`-kind entry, see
+ *    ../../build.ts). Re-running `chant build` against the same source
+ *    reproduces byte-identical output — the same content-addressing property
+ *    ./build-archive.ts's `contentDigest`/`manifestDigest` already rely on.
+ *    Verification is exactly "re-synth and compare digests," expressed here
+ *    as `verifyBy: "re-synth"`.
+ *  - `"best-effort"` — an `image`/`asset` entry built by an external tool
+ *    (`docker build`, a JVM/zip packager). Nothing here observes whether the
+ *    underlying build was actually bit-for-bit reproducible (timestamps,
+ *    build-arg ordering, and base-image drift are common, unglamorous causes
+ *    of non-determinism that chant does not control) — `"best-effort"` is
+ *    the honest default absent a real reproducible-build attestation. A
+ *    future SLSA/reproducible-build-flagged backend can upgrade this to a
+ *    stronger basis; nothing here forecloses that, it just refuses to claim
+ *    it today.
+ *
+ * **Provenance** is the companion source -> output link: which source
+ * ref/commit produced this artifact's digest. Recorded per artifact for the
+ * same reason `basis` is — two artifacts from one component build may trace
+ * to different source trees (e.g. an image built from `services/search/` vs
+ * a template synthesized from `infra/search.component.ts`), so the link
+ * belongs on the entry, not hoisted to the component.
+ */
+/**
+ * Default reproducibility basis for a given `BuildArchiveEntryKind`, absent
+ * an explicit override. A `template` entry is chant's own synthesized IaC
+ * output — deterministic by construction (the same synthesis run over the
+ * same source produces the same bytes, per ./build-archive.ts's module doc).
+ * `image`/`asset` entries are produced by an external build tool chant only
+ * orchestrates (`docker build`, a JVM/zip packager) — best-effort absent a
+ * real reproducible-build attestation. `sbom` entries describe another
+ * artifact rather than being one themselves, so they carry no
+ * reproducibility claim of their own (`undefined`) — see
+ * `../build-archive.ts`'s `BuildArchiveEntry.reproducibility` doc.
+ */
+export function defaultReproducibility(kind) {
+    switch (kind) {
+        case "template":
+            return { basis: "deterministic-synthesis", verifyBy: "re-synth" };
+        case "image":
+        case "asset":
+            return { basis: "best-effort" };
+        case "sbom":
+            return undefined;
+    }
+}