@intentius/chant 0.124.13 → 0.124.14

package/dist/components/verbs/vuln-scan.js

@@ -0,0 +1,288 @@
+/**
+ * Vulnerability scanning of an already-generated SBOM (#626, epic #551
+ * supply-chain follow-up to the SBOM stack #606/#613/#614/#609/#610). An SBOM
+ * says *what's in* an artifact; a scanner says *which of those have known
+ * CVEs*. This module produces findings; ./vex.ts suppresses the ones that
+ * don't matter and ./vuln-gate.ts fails the deploy on the ones that do.
+ *
+ * Prefer scanning the **SBOM** (already generated + persisted, keyed by
+ * digest) over re-scanning the image: deterministic (same SBOM -> same
+ * findings), fast, and reuses work already done. Real backends shell out to
+ * `grype`/`trivy` through the injectable `ProcessRunner` (./process-runner.ts),
+ * exactly like ./tool-sbom-generator.ts's deep-scan backend — tests inject an
+ * inline fake `VulnScanner` (an object literal with a canned `scan()`, see
+ * ./vuln-gate.test.ts) and never invoke a real scanner, network, or vuln DB.
+ * The scanner's vuln DB currency is the tool's job, not chant's.
+ *
+ * `createDatabaseVulnScanner` (ws-056, INTENTIUS/chant#2735) is the one
+ * hermetic exception: a `VulnScanner` matched against a local, offline
+ * advisory-database file instead of a real scanner binary — no `grype`/
+ * `trivy` required, deterministic, at the cost of covering only the
+ * advisories the database names. Ported from chud's `supply-chain.mjs`
+ * (`scanWithDatabase`/`sbomPackages`/`compareVersions`), which built its own
+ * copy of this because `scan-vulnerabilities` had no offline backend.
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+import { defaultProcessRunner, q, requireTool, ToolNotAvailableError } from "./process-runner.js";
+/** Severity rank (higher = more severe) so a gate can ask "severity >= critical". */
+export const SEVERITY_RANK = {
+    critical: 5,
+    high: 4,
+    medium: 3,
+    low: 2,
+    negligible: 1,
+    unknown: 0,
+};
+/** Normalize a scanner's free-form severity string ("High", "CRITICAL", "Negligible", …) to a `Severity`. Unrecognized -> `unknown`. */
+export function normalizeSeverity(raw) {
+    const s = (raw ?? "").toLowerCase();
+    if (s === "critical" || s === "high" || s === "medium" || s === "low" || s === "negligible")
+        return s;
+    return "unknown";
+}
+/** Parse `grype -o json` stdout into findings. Exported for tests to assert parsing without a live tool. */
+export function parseGrypeOutput(stdout) {
+    const doc = JSON.parse(stdout);
+    return (doc.matches ?? []).map((m) => {
+        const fixVersions = m.vulnerability?.fix?.versions ?? [];
+        const epss = m.vulnerability?.epss?.[0];
+        const kev = m.vulnerability?.knownExploited?.[0];
+        return {
+            cveId: m.vulnerability?.id ?? "UNKNOWN",
+            severity: normalizeSeverity(m.vulnerability?.severity),
+            package: m.artifact?.name ?? "unknown",
+            installedVersion: m.artifact?.version ?? "",
+            fixedVersion: fixVersions[0],
+            fixable: m.vulnerability?.fix?.state === "fixed" || fixVersions.length > 0,
+            epss: epss?.epss,
+            epssPercentile: epss?.percentile,
+            // grype omits `knownExploited` for a non-KEV vuln, so `undefined` here
+            // means "no KEV annotation reported" — never coerced to `false`.
+            inKev: kev ? true : undefined,
+            kevDateAdded: kev?.dateAdded,
+            kevDueDate: kev?.dueDate,
+            // KEV's ransomware field is "known"/"unknown" — "unknown" is not "no",
+            // so only an explicit "known" becomes `true`; everything else stays unset.
+            kevRansomware: kev?.knownRansomwareCampaignUse?.toLowerCase() === "known" ? true : undefined,
+        };
+    });
+}
+/** Parse `trivy sbom --format json` stdout into findings. */
+export function parseTrivyOutput(stdout) {
+    const doc = JSON.parse(stdout);
+    const out = [];
+    for (const r of doc.Results ?? []) {
+        for (const v of r.Vulnerabilities ?? []) {
+            out.push({
+                cveId: v.VulnerabilityID ?? "UNKNOWN",
+                severity: normalizeSeverity(v.Severity),
+                package: v.PkgName ?? "unknown",
+                installedVersion: v.InstalledVersion ?? "",
+                fixedVersion: v.FixedVersion || undefined,
+                fixable: Boolean(v.FixedVersion),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The packages an SPDX or CycloneDX document lists, by purl (SPDX's
+ * `externalRefs` with `referenceType: "purl"`, CycloneDX's `components[].purl`),
+ * deduplicated by ecosystem/name/version. Parses `doc.bytes` (a string, as
+ * every `SbomDocument` carries it) rather than requiring a pre-parsed object,
+ * so a caller can pass a `scan-vulnerabilities` input's `sbom` straight
+ * through.
+ */
+export function sbomPackages(doc) {
+    const parsed = JSON.parse(doc.bytes);
+    const purls = [
+        ...(parsed.packages ?? []).flatMap((p) => (p.externalRefs ?? []).filter((r) => r.referenceType === "purl").map((r) => r.referenceLocator ?? "")),
+        ...(parsed.components ?? []).map((c) => c.purl).filter((p) => Boolean(p)),
+    ];
+    const seen = new Map();
+    for (const purl of purls) {
+        const m = /^pkg:([^/]+)\/(.+)@([^?#]+)/.exec(purl);
+        if (!m)
+            continue;
+        const pkg = { ecosystem: m[1], name: decodeURIComponent(m[2]), version: decodeURIComponent(m[3]) };
+        seen.set(`${pkg.ecosystem}:${pkg.name}@${pkg.version}`, pkg);
+    }
+    return [...seen.values()];
+}
+/**
+ * Compare two dotted version strings numerically, a pre-release sorting
+ * before its release (`1.2.0-rc.1` < `1.2.0`). Not full semver (no build
+ * metadata, no ordering between differing pre-release labels beyond "a
+ * pre-release exists") — just enough to place an installed version between
+ * an advisory's `introduced` and `fixed`.
+ */
+export function compareVersions(a, b) {
+    const parse = (v) => {
+        const [core, pre] = String(v).replace(/^v/, "").split("-", 2);
+        return { nums: core.split(".").map((n) => Number.parseInt(n, 10) || 0), pre };
+    };
+    const x = parse(a);
+    const y = parse(b);
+    for (let i = 0; i < Math.max(x.nums.length, y.nums.length); i++) {
+        const d = (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+        if (d)
+            return Math.sign(d);
+    }
+    if (x.pre && !y.pre)
+        return -1;
+    if (!x.pre && y.pre)
+        return 1;
+    if (x.pre === y.pre)
+        return 0;
+    return x.pre < y.pre ? -1 : 1;
+}
+/**
+ * Match an SBOM's packages against a local, offline advisory database —
+ * no scanner binary, no network, deterministic. A package is affected when
+ * `introduced <= installedVersion < fixed` (or unconditionally affected when
+ * the advisory names no `fixed`). Findings are `VulnFinding`-shaped, so they
+ * feed `vuln-gate` exactly like `grype`/`trivy` output does; every
+ * exploitability field (`epss`, `inKev`, …) an offline database can't supply
+ * is left `undefined`, never defaulted to a false negative.
+ */
+export function scanWithDatabase(doc, db) {
+    const advisories = Array.isArray(db) ? db : (db.advisories ?? []);
+    const findings = [];
+    for (const pkg of sbomPackages(doc)) {
+        for (const a of advisories) {
+            if ((a.ecosystem ?? "npm") !== pkg.ecosystem || a.package !== pkg.name)
+                continue;
+            if (compareVersions(pkg.version, a.introduced ?? "0") < 0)
+                continue;
+            if (a.fixed && compareVersions(pkg.version, a.fixed) >= 0)
+                continue;
+            findings.push({
+                cveId: a.id,
+                severity: normalizeSeverity(a.severity),
+                package: pkg.name,
+                installedVersion: pkg.version,
+                ...(a.fixed ? { fixedVersion: a.fixed } : {}),
+                fixable: Boolean(a.fixed),
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * A `VulnScanner` backed by a local, offline advisory database file (JSON:
+ * `{ "advisories": [...] }`, see `AdvisoryDatabase`) instead of a real
+ * scanner binary — the hermetic fallback `autoDetectVulnScanner`'s doc
+ * comment says a scan doesn't have ("there is no hermetic fallback, a scan
+ * needs a real vuln DB"): deterministic, offline, no `grype`/`trivy`
+ * install required, at the cost of covering only the advisories the
+ * database names. Reads the file once per call (a database pinned in the
+ * repo changes rarely; callers that scan repeatedly should cache the parsed
+ * `AdvisoryDatabase` and call `scanWithDatabase` directly instead).
+ */
+export function createDatabaseVulnScanner(dbFile) {
+    return {
+        async scan(input) {
+            const db = JSON.parse(readFileSync(dbFile, "utf8"));
+            return scanWithDatabase(input.sbom, db);
+        },
+    };
+}
+/**
+ * A real `VulnScanner` that writes the SBOM to a temp file and scans it with
+ * `grype` (default) or `trivy`, through the injectable `ProcessRunner`.
+ * `requireTool` throws `ToolNotAvailableError` if the scanner is absent — a
+ * missing scanner is a hard stop (like ./verify.ts's missing `cosign`), never
+ * a silent "no vulns found," because that would let an unscanned artifact
+ * through a gate. Never used in tests.
+ */
+export function createToolVulnScanner(tool = "grype", processRunner = defaultProcessRunner()) {
+    return {
+        async scan(input) {
+            await requireTool(processRunner, tool, `scan the SBOM for known vulnerabilities`);
+            // Content-address the temp file so concurrent scans never collide and we
+            // avoid Date.now()/Math.random() (blocked in some chant runtimes).
+            const hash = createHash("sha256").update(input.sbom.bytes).digest("hex").slice(0, 16);
+            const ext = input.sbom.format === "cyclonedx" ? "cdx.json" : "spdx.json";
+            const path = join(tmpdir(), `chant-scan-${hash}.${ext}`);
+            writeFileSync(path, input.sbom.bytes);
+            if (tool === "trivy") {
+                const { stdout } = await processRunner.run(`trivy sbom --quiet --format json ${q(path)}`);
+                return parseTrivyOutput(stdout);
+            }
+            const { stdout } = await processRunner.run(`grype sbom:${q(path)} -o json`);
+            return parseGrypeOutput(stdout);
+        },
+    };
+}
+/**
+ * Thrown by `notImplementedVulnScanner` — the "no real scanner wired yet"
+ * signal, mirroring `SbomGeneratorNotImplementedError` (./sbom-generator.ts).
+ * The default is loud-and-specific rather than a silent empty scan, so a
+ * caller that forgets to inject a scanner (or a mock in tests) fails obviously
+ * instead of appearing to find zero vulnerabilities.
+ */
+export class VulnScannerNotImplementedError extends Error {
+    constructor() {
+        super(`VulnScanner has no real scanner configured — inject a real scanner ` +
+            `(createToolVulnScanner("grype"|"trivy")) or a mock in tests`);
+        this.name = "VulnScannerNotImplementedError";
+    }
+}
+/** Kept for tests and for a caller that wants the old loud "no scanner wired" behavior; no longer the registered default (#634). */
+export const notImplementedVulnScanner = {
+    async scan() {
+        throw new VulnScannerNotImplementedError();
+    },
+};
+/**
+ * A `VulnScanner` that picks a real backend at scan time — `grype` if present,
+ * else `trivy`. Unlike SBOM generation there is no hermetic fallback (a scan
+ * needs a real vuln DB), so when neither tool is on `PATH` this throws a
+ * `ToolNotAvailableError` naming what to install — an error a config-only user
+ * can act on — rather than `VulnScannerNotImplementedError`, which told them to
+ * edit code. This is the vuln-side analog of #630's hermetic-by-default SBOM
+ * generator: the registered `scan-vulnerabilities`/`vuln-gate` capabilities now
+ * work the moment a scanner is installed, with no code wiring.
+ */
+export function autoDetectVulnScanner(processRunner = defaultProcessRunner()) {
+    return {
+        async scan(input) {
+            const tool = (await processRunner.available("grype"))
+                ? "grype"
+                : (await processRunner.available("trivy"))
+                    ? "trivy"
+                    : undefined;
+            if (!tool) {
+                throw new ToolNotAvailableError("grype or trivy", "scan the SBOM for known vulnerabilities");
+            }
+            return createToolVulnScanner(tool, processRunner).scan(input);
+        },
+    };
+}
+let defaultScanner;
+/** The default `VulnScanner` the `scan-vulnerabilities`/`vuln-gate` capabilities fall back to when none is supplied: auto-detects `grype`/`trivy` and throws `ToolNotAvailableError` if neither is installed (#634). */
+export function defaultVulnScanner() {
+    if (!defaultScanner)
+        defaultScanner = autoDetectVulnScanner();
+    return defaultScanner;
+}
+/**
+ * `scan-vulnerabilities` capability — scan an SBOM for known CVEs via the
+ * injectable `VulnScanner`. Produces findings only; suppression (VEX) and the
+ * pass/fail decision live in ./vuln-gate.ts, so a composition can scan once
+ * and reuse the findings, or run the gate directly (which scans for you).
+ */
+export function createScanVulnerabilitiesCapability(scanner = defaultVulnScanner()) {
+    return {
+        kind: "scan-vulnerabilities",
+        async run(_ctx, input) {
+            const findings = await scanner.scan({ sbom: input.sbom, digest: input.digest });
+            return { findings, digest: input.digest };
+        },
+    };
+}
+/** Default `scan-vulnerabilities` capability, backed by the not-implemented scanner (inject a real/mock one). */
+export const scanVulnerabilitiesCapability = createScanVulnerabilitiesCapability();

package/dist/components/verbs/wait-verify.js

@@ -0,0 +1,106 @@
+/**
+ * wait / verify family — poll until a deploy reaches a terminal or healthy
+ * state. The *agnostic* members live here: `wait-cluster-healthy` (a Neo4j
+ * bolt/quorum probe over the core `CloudExecutor`), and the HTTP waits
+ * `wait-endpoint` / `health-gate` (over an injectable `fetch`). The
+ * cloud-specific members — `wait-for-stack` (CloudFormation),
+ * `wait-steady-state` (ECS), `wait-job` (EMR) — moved to the aws lexicon
+ * alongside their executor clients (see docs/components/cloud-boundary).
+ */
+import { defaultCloudExecutor, sleep } from "./cloud-executor.js";
+const defaultFetcher = (url) => fetch(url);
+/**
+ * Poll a multi-node cluster (e.g. Neo4j) via a bolt-port TCP probe until it
+ * reports healthy: `size` members reachable (exact-count mode, used by a
+ * cluster's seed instance) or a majority of the expected member list
+ * (`quorum` mode, used once followers exist). No rollback: a health probe is
+ * read-only.
+ */
+export function createWaitClusterHealthyCapability(executor = defaultCloudExecutor()) {
+    return {
+        kind: "wait-cluster-healthy",
+        async run(ctx, input) {
+            const cluster = input.cluster ?? ctx.vars?.clusterEndpoints ?? ctx.component;
+            const intervalMs = input.intervalMs ?? 5000;
+            const deadline = Date.now() + (input.timeoutMs ?? 5 * 60000);
+            while (true) {
+                const { healthyCount, total } = await executor.neo4j.probe({ cluster });
+                const required = input.quorum ? Math.floor(total / 2) + 1 : (input.size ?? total);
+                if (healthyCount >= required)
+                    return { healthyCount };
+                if (Date.now() > deadline) {
+                    throw new Error(`wait-cluster-healthy "${cluster}" timed out: ${healthyCount}/${total} healthy, needed ${required}`);
+                }
+                await sleep(intervalMs);
+            }
+        },
+    };
+}
+/** Default `wait-cluster-healthy` capability, backed by the real `CloudExecutor`. */
+export const waitClusterHealthyCapability = createWaitClusterHealthyCapability();
+/** Poll an HTTP(S) endpoint until it responds with an expected status. Cloud-agnostic. */
+export function createWaitEndpointCapability(fetcher = defaultFetcher) {
+    return {
+        kind: "wait-endpoint",
+        async run(_ctx, input) {
+            const expect = input.expectStatus ?? [200];
+            const intervalMs = input.intervalMs ?? 5000;
+            const timeoutMs = input.timeoutMs ?? 5 * 60000;
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                try {
+                    const res = await fetcher(input.url);
+                    if (expect.includes(res.status))
+                        return { status: res.status };
+                }
+                catch {
+                    // not reachable yet — keep polling until the deadline
+                }
+                if (Date.now() >= deadline) {
+                    throw new Error(`wait-endpoint: ${input.url} did not return ${expect.join("/")} within ${timeoutMs}ms`);
+                }
+                await sleep(intervalMs);
+            }
+        },
+    };
+}
+/** Default `wait-endpoint` capability, backed by the global `fetch`. */
+export const waitEndpointCapability = createWaitEndpointCapability();
+/** Compose the fetchable URL: `host` set → resolve `path` against it (bare host → `http://` prepended); else `path` as-is. */
+function healthGateUrl(input) {
+    if (!input.host)
+        return input.path;
+    const base = /^https?:\/\//.test(input.host) ? input.host : `http://${input.host}`;
+    return new URL(input.path, base).toString();
+}
+/** Block progression until a health check passes — the generic post-deploy verification gate. Cloud-agnostic. */
+export function createHealthGateCapability(fetcher = defaultFetcher) {
+    return {
+        kind: "health-gate",
+        async run(_ctx, input) {
+            const need = input.consecutiveSuccesses ?? 1;
+            const intervalMs = input.intervalMs ?? 5000;
+            // HealthGateInput has no timeout field; cap the wait so a never-healthy target fails rather than hangs.
+            const deadline = Date.now() + 5 * 60000;
+            let streak = 0;
+            for (;;) {
+                let ok = false;
+                try {
+                    ok = (await fetcher(healthGateUrl(input))).ok;
+                }
+                catch {
+                    ok = false;
+                }
+                streak = ok ? streak + 1 : 0;
+                if (streak >= need)
+                    return { healthy: true };
+                if (Date.now() >= deadline) {
+                    throw new Error(`health-gate: ${healthGateUrl(input)} did not reach ${need} consecutive healthy check(s) within 300000ms`);
+                }
+                await sleep(intervalMs);
+            }
+        },
+    };
+}
+/** Default `health-gate` capability, backed by the global `fetch`. */
+export const healthGateCapability = createHealthGateCapability();

package/dist/components/verbs/wrangler.js

@@ -0,0 +1,179 @@
+/**
+ * `wrangler-deploy` / `wrangler-versions-promote` — the Cloudflare Workers
+ * apply leaves (chant #1293, epic #1296). The epic cedes the Workers plane
+ * entirely to `wrangler` (first-party, schema-backed, already owns the
+ * config format, bindings model, local dev, and deploy) — these two verbs
+ * are a typed wrapper over that CLI, not a reimplementation of it.
+ *
+ * Placement: core, not a cloudflare lexicon. #1293's own analysis weighed
+ * three options — core (generic verb, fastest, costs a little conceptual
+ * tidiness since `wrangler-deploy` shells a specific vendor CLI), a
+ * capability-only cloudflare lexicon (the "correct" home, but `LexiconPlugin`
+ * tier-1 completeness — serializer, lint rules, post-synth, LSP, examples,
+ * docs — is heavy ceremony for three verbs and no resource types), or
+ * generalizing to a `cli-deploy` verb parameterised by tool (tempting, but
+ * premature and it re-opens the verb set the bounded-primitives thesis
+ * depends on staying closed). Core wins on the same precedent `sign`/
+ * `attest-provenance` (./sign.ts) already set: a specific vendor CLI
+ * (`cosign`) shelled out through the injectable `ProcessRunner`
+ * (./process-runner.ts), no cloud-specific SDK client needed the way AWS's
+ * `CloudExecutor` (./cloud-executor.ts) models CloudFormation/ECS/Lambda.
+ * `wrangler` fits that exact shape. Revisit if/when the zone-plane lexicon
+ * (#1294) lands and gives these three verbs a natural cloudflare-owned home.
+ *
+ * `wrangler-versions-promote` is also the direct evidence for #1296's
+ * "three new verbs cover a whole new cloud" claim: Cloudflare's native
+ * Worker version rollback maps onto the existing `RollbackPolicy: "native"`
+ * (../capability.ts) with no compensation code to hand-write — both verbs
+ * here declare a `rollback` (auto-derived "native" per ../capability.ts's
+ * `Capability.rollbackPolicy` doc) that re-promotes to whichever version was
+ * live before the step ran, the same best-effort captured-previous-state
+ * pattern lexicons/aws/src/components/apply.ts's `lambda-deploy` uses for
+ * its alias rollback.
+ *
+ * No real Cloudflare control-plane emulator exists yet (#1295, epic #1296),
+ * so — like ./sign.ts — every real path here shells out through the
+ * injectable `ProcessRunner` and every test substitutes `MockProcessRunner`
+ * (./__tests__/mock-process-runner.ts): no live `wrangler`, no network, ever,
+ * in a test run. CI coverage is plan-shape/invocation-shape assertions only,
+ * per #1293's own "Verification" section.
+ */
+import { defaultProcessRunner, q, requireTool } from "./process-runner.js";
+const WRANGLER_TOOL = "wrangler";
+/** Distinguishes one deploy target (a wrangler config + optional named environment) from another, so the best-effort previous-version tracking below never conflates two different Workers sharing a process. */
+function targetKey(config, env) {
+    return env ? `${config}#${env}` : config;
+}
+function buildWranglerDeployArgs(input) {
+    const args = ["wrangler", "deploy", "--config", q(input.config)];
+    if (input.env)
+        args.push("--env", q(input.env));
+    return args.join(" ");
+}
+function buildVersionsListArgs(config, env) {
+    const args = ["wrangler", "versions", "list", "--config", q(config), "--json"];
+    if (env)
+        args.push("--env", q(env));
+    return args.join(" ");
+}
+function buildVersionsPromoteArgs(config, versionId, percentage, env) {
+    const args = ["wrangler", "versions", "deploy", q(`${versionId}@${percentage}`), "--config", q(config), "--yes"];
+    if (env)
+        args.push("--env", q(env));
+    return args.join(" ");
+}
+/** Thrown when `wrangler deploy`'s stdout carries no parseable Version ID — fail-closed rather than returning a capability output downstream steps (`wrangler-versions-promote`, wired via `"@Deploy.versionId"`) would silently receive as `undefined`. */
+export class WranglerVersionIdNotFoundError extends Error {
+    constructor(stdout) {
+        super(`wrangler-deploy: could not find a Version ID in wrangler's output. Got:\n${stdout}`);
+        this.stdout = stdout;
+        this.name = "WranglerVersionIdNotFoundError";
+    }
+}
+// wrangler's deploy/versions-upload output names the new version as e.g.
+// "Version ID: 07bcb198-... " (gradual deployments) — accept either "Version
+// ID:" or the bare "Version:" wording across wrangler versions, and require a
+// UUID-shaped token so a stray "Version: 2" summary line can't be mistaken
+// for it.
+const VERSION_ID_RE = /Version(?: ID)?:\s*([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})/;
+/** Extract the deployed Worker version id from `wrangler deploy`'s stdout. Exported so tests can assert on it directly, mirroring ./sign.ts's `buildSignArgs`. */
+export function parseWranglerVersionId(stdout) {
+    const match = VERSION_ID_RE.exec(stdout);
+    if (!match)
+        throw new WranglerVersionIdNotFoundError(stdout);
+    return match[1];
+}
+/**
+ * Best-effort: the currently-live (100%) version id, from `wrangler versions
+ * list --json` — `undefined` for a first deploy (no versions yet) or if
+ * listing fails/parses oddly. Never throws: capturing "what to roll back to"
+ * must not block the deploy/promote itself, the same fail-soft stance
+ * `lambda-deploy`'s alias-version capture takes.
+ */
+async function currentLiveVersionId(runner, config, env) {
+    try {
+        const { stdout } = await runner.run(buildVersionsListArgs(config, env));
+        const entries = JSON.parse(stdout);
+        return entries.find((entry) => entry.percentage === 100)?.id;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Deploy a Worker from a `wrangler.jsonc`/`wrangler.toml` via `wrangler
+ * deploy`, and return the version id it published — the analogue of
+ * `lambda-deploy` (../../lexicons/aws/src/components/apply.ts) for the
+ * Workers plane.
+ *
+ * Rollback: `wrangler-versions-promote` back to whichever version was live
+ * before this step ran (captured up front via `wrangler versions list`, the
+ * same best-effort captured-previous pattern `lambda-deploy` uses for its
+ * alias). A no-op on a first deploy — nothing was live to restore.
+ */
+export function createWranglerDeployCapability(processRunner = defaultProcessRunner()) {
+    const previousVersionByTarget = new Map();
+    return {
+        kind: "wrangler-deploy",
+        async run(_ctx, input) {
+            await requireTool(processRunner, WRANGLER_TOOL, `deploy the Worker in ${input.config}`);
+            const target = targetKey(input.config, input.env);
+            if (!previousVersionByTarget.has(target)) {
+                previousVersionByTarget.set(target, await currentLiveVersionId(processRunner, input.config, input.env));
+            }
+            const { stdout } = await processRunner.run(buildWranglerDeployArgs(input));
+            return { versionId: parseWranglerVersionId(stdout) };
+        },
+        async rollback(_ctx, input) {
+            const target = targetKey(input.config, input.env);
+            const previousVersionId = previousVersionByTarget.get(target);
+            if (!previousVersionId)
+                return; // first deploy — nothing was live before it.
+            await requireTool(processRunner, WRANGLER_TOOL, `roll back the Worker in ${input.config}`);
+            await processRunner.run(buildVersionsPromoteArgs(input.config, previousVersionId, 100, input.env));
+        },
+    };
+}
+/** Default `wrangler-deploy` capability, backed by the real `ProcessRunner`. */
+export const wranglerDeployCapability = createWranglerDeployCapability();
+/**
+ * Promote a Worker version to (some percentage of) live traffic via
+ * `wrangler versions deploy <version-id>@<percentage> --yes` — both the
+ * gradual-deployment lever (`percentage` < 100) and, at `percentage: 100`,
+ * the rollback mechanism: Cloudflare's native version rollback is a promote
+ * to a prior version id, not a redeploy, so this same verb composes as the
+ * explicit compensation step a component wires up (#1293's "verification"
+ * example: forced failure after `wrangler-deploy` -> `wrangler-versions-promote`
+ * back to the prior version, no hand-written compensation needed).
+ *
+ * Also declares its own `rollback` (native, no `rollbackPolicy` override
+ * needed — see ../capability.ts): re-promotes to whichever version was live
+ * before *this* promote call, for the case where the promote step itself is
+ * composed directly (not just as `wrangler-deploy`'s compensation).
+ */
+export function createWranglerVersionsPromoteCapability(processRunner = defaultProcessRunner()) {
+    const previousVersionByTarget = new Map();
+    return {
+        kind: "wrangler-versions-promote",
+        async run(_ctx, input) {
+            await requireTool(processRunner, WRANGLER_TOOL, `promote version ${input.versionId} in ${input.config}`);
+            const percentage = input.percentage ?? 100;
+            const target = targetKey(input.config, input.env);
+            if (!previousVersionByTarget.has(target)) {
+                previousVersionByTarget.set(target, await currentLiveVersionId(processRunner, input.config, input.env));
+            }
+            await processRunner.run(buildVersionsPromoteArgs(input.config, input.versionId, percentage, input.env));
+            return { versionId: input.versionId, percentage };
+        },
+        async rollback(_ctx, input) {
+            const target = targetKey(input.config, input.env);
+            const previousVersionId = previousVersionByTarget.get(target);
+            if (!previousVersionId)
+                return; // nothing was live before this promote.
+            await requireTool(processRunner, WRANGLER_TOOL, `roll back version promotion in ${input.config}`);
+            await processRunner.run(buildVersionsPromoteArgs(input.config, previousVersionId, 100, input.env));
+        },
+    };
+}
+/** Default `wrangler-versions-promote` capability, backed by the real `ProcessRunner`. */
+export const wranglerVersionsPromoteCapability = createWranglerVersionsPromoteCapability();

package/dist/components/wave-plan.js

@@ -0,0 +1,102 @@
+/**
+ * Plan one wave of a gated-wave fan-out (#3049).
+ *
+ * Each component in the wave is asked what it would change: every deploy
+ * step whose capability has a `plan` (`Capability.plan`, ./capability.ts) is
+ * planned, with its wiring resolved against the outputs the earlier waves
+ * left behind. That is the point of planning at the wave rather than up
+ * front: a root that reads an upstream output plans against the value the
+ * upstream wave actually wrote.
+ *
+ * A component with no plannable step is still a member of the wave. Its plan
+ * digest is the composition digest a gate inside it would bind
+ * (`componentPlanDigest`, ./gate-plan.ts, #2574), so a wave mixing roots and
+ * other components still has one digest that moves when any of them does.
+ *
+ * Known limit: a step input that reads an earlier step of the same
+ * component (`@Phase.field`) has no value before the component runs, so it
+ * plans as `undefined`. Cross-component wiring (`stackOutput()`,
+ * `@<component>.publish.*`) resolves.
+ */
+import { resolveStepInput } from "./driver.js";
+import { componentPlanDigest } from "./gate-plan.js";
+/** A part with no entries, for a member whose planner describes no changes. */
+function emptyPart(member) {
+    return {
+        member: { member: member.member, lexicon: "chant", planner: "chant", status: "planned", planDigest: member.planDigest, holes: [] },
+        entries: [],
+    };
+}
+/** Every capability step in a composition, nested phases included, gates left out. */
+function capabilitySteps(phases) {
+    const out = [];
+    const walk = (steps) => {
+        for (const step of steps) {
+            if (typeof step.phase === "string" && Array.isArray(step.steps)) {
+                walk(step.steps);
+                continue;
+            }
+            if (step.kind === "gate")
+                continue;
+            out.push(step);
+        }
+    };
+    for (const phase of phases)
+        walk(phase.steps);
+    return out;
+}
+/** Plan one component against the outputs earlier waves produced. Never throws: a failure comes back as `error`. */
+export async function planWaveComponent(component, registry, ctx, componentOutputs) {
+    try {
+        const members = [];
+        const plans = {};
+        const parts = [];
+        for (const step of capabilitySteps(component.deploy)) {
+            const capability = registry.resolve(step.kind);
+            if (!capability.plan)
+                continue;
+            const { kind: _kind, ...rest } = step;
+            const input = resolveStepInput(rest, {}, componentOutputs);
+            const planned = await capability.plan(ctx, input);
+            const member = { member: planned.member, planDigest: planned.planDigest };
+            members.push(member);
+            parts.push(planned.changeSet ?? emptyPart(member));
+            if (planned.artifact !== undefined)
+                plans[planned.member] = planned.artifact;
+        }
+        if (members.length === 0) {
+            const member = {
+                member: component.name,
+                planDigest: componentPlanDigest({
+                    environment: ctx.env,
+                    component,
+                    ...(ctx.vars ? { vars: ctx.vars } : {}),
+                }),
+            };
+            members.push(member);
+            parts.push(emptyPart(member));
+        }
+        return { component: component.name, members, plans, parts };
+    }
+    catch (err) {
+        return { component: component.name, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * The outputs `component` exposes now, read from each step whose capability
+ * has `outputs` (#3183), merged the way the driver merges a run's outputs.
+ * `undefined` when no step can say. A pull request's plan reads these for
+ * the components a planned one depends on, before anything has applied.
+ */
+export async function readComponentOutputs(component, registry, ctx, componentOutputs) {
+    let found;
+    for (const step of capabilitySteps(component.deploy)) {
+        const capability = registry.resolve(step.kind);
+        if (!capability.outputs)
+            continue;
+        const { kind: _kind, ...rest } = step;
+        const input = resolveStepInput(rest, {}, componentOutputs);
+        found = { ...found, ...(await capability.outputs(ctx, input)) };
+    }
+    return found;
+}