@intentius/chant 0.45.0 → 0.49.0

package/src/components/starter-plugin.ts

@@ -41,6 +41,10 @@ import {
   waitEndpointCapability,
   healthGateCapability,
   shellCapability,
+  ensureSecretCapability,
+  wranglerDeployCapability,
+  wranglerVersionsPromoteCapability,
+  r2SyncCapability,
 } from "./verbs/index";
 import { ownPackageVersion, type CapabilityPlugin } from "./capability-plugin";
 
@@ -64,7 +68,16 @@ export const STARTER_VERB_FAMILIES = {
   // cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`) are
   // contributed by the relevant lexicon (aws) — see docs/components/cloud-boundary.
   waitVerify: ["wait-cluster-healthy", "wait-endpoint", "health-gate"],
+  // generated-once secret materialization (#1829, epic #1365): read-then-write,
+  // present means done; the k8s store adapter is #1830.
+  secrets: ["ensure-secret"],
   escapeHatch: ["shell"],
+  // The Cloudflare Workers apply leaves (#1293, epic #1296) — placed in core
+  // rather than a cloudflare lexicon (decided explicitly, see ./verbs/wrangler.ts's
+  // module doc): the epic cedes the Workers plane to `wrangler` entirely, and
+  // there is no cloudflare lexicon for these three verbs to live in. Revisit
+  // if/when the zone-plane lexicon (#1294) lands.
+  cloudflare: ["wrangler-deploy", "wrangler-versions-promote", "r2-sync"],
 } as const;
 
 /**
@@ -88,7 +101,11 @@ function starterCapabilities(): Array<Capability<never, unknown>> {
     waitClusterHealthyCapability,
     waitEndpointCapability,
     healthGateCapability,
+    ensureSecretCapability,
     shellCapability,
+    wranglerDeployCapability,
+    wranglerVersionsPromoteCapability,
+    r2SyncCapability,
   ] as unknown as Array<Capability<never, unknown>>;
 }
 

package/src/components/verbs/ensure-secret.test.ts

@@ -0,0 +1,130 @@
+/**
+ * `ensure-secret` capability surface tests (#1829, epic #1365 decision 3):
+ * the verb is the same engine as the `ensureSecret(...)` op builder, its
+ * rollback disposition is `needs-opt-out`, and COMP003 fires on a component
+ * that uses it without acknowledging the compensation gap — through the same
+ * registry-derived policy map `chant lint` builds, not a hard-coded list.
+ */
+
+import { describe, expect, it, vi } from "vitest";
+import type { DeployContext } from "../capability";
+import { CapabilityNotImplementedError, type RollbackPolicy } from "../capability";
+import { createCapabilityRegistry } from "../registry";
+import { createEnsureSecretCapability, ensureSecretCapability } from "./ensure-secret";
+import {
+  SecretMaterial,
+  SecretContractMismatchError,
+  consumeSecretMaterial,
+  type SecretMaterialGenerator,
+  type SecretStoreAdapter,
+} from "../../secret-materialization";
+import { loadComponentChecks } from "../../lint/rules/comp";
+
+const ctx: DeployContext = { env: "dev", component: "fountain" };
+
+function fakeStore(seed?: Record<string, Record<string, string>>) {
+  const secrets = new Map<string, Record<string, string>>(Object.entries(seed ?? {}));
+  const adapter: SecretStoreAdapter = {
+    exists: vi.fn(async (name: string) => secrets.has(name)),
+    describe: vi.fn(async (name: string) => ({ keys: Object.keys(secrets.get(name) ?? {}) })),
+    create: vi.fn(async (name: string, keys: readonly string[], generate: SecretMaterialGenerator) => {
+      const data: Record<string, string> = {};
+      for (const key of keys) data[key] = consumeSecretMaterial(await generate(key));
+      secrets.set(name, data);
+    }),
+  };
+  return { adapter, secrets };
+}
+
+describe("ensure-secret capability", () => {
+  it("creates an absent secret, then treats present-and-matching as done (create fires once across reruns)", async () => {
+    const { adapter } = fakeStore();
+    const capability = createEnsureSecretCapability({
+      store: adapter,
+      generator: (key) => SecretMaterial.mint(`v:${key}`),
+    });
+    const first = await capability.run(ctx, { name: "app-secret", keys: ["token"] });
+    const second = await capability.run(ctx, { name: "app-secret", keys: ["token"] });
+    expect(first.outcome).toBe("created");
+    expect(second.outcome).toBe("present");
+    expect(adapter.create).toHaveBeenCalledTimes(1);
+  });
+
+  it("propagates the loud mismatch from the shared engine", async () => {
+    const { adapter } = fakeStore({ "app-secret": { other: "x" } });
+    const capability = createEnsureSecretCapability({ store: adapter });
+    await expect(capability.run(ctx, { name: "app-secret", keys: ["token"] })).rejects.toThrowError(
+      SecretContractMismatchError,
+    );
+  });
+
+  it("output carries names only — no field of the outcome can hold material", async () => {
+    const { adapter } = fakeStore();
+    const capability = createEnsureSecretCapability({
+      store: adapter,
+      generator: (key) => SecretMaterial.mint(`v:${key}`),
+    });
+    const outcome = await capability.run(ctx, { name: "app-secret", keys: ["token"] });
+    expect(outcome).toEqual({ outcome: "created", name: "app-secret", keys: ["token"] });
+    expect(JSON.stringify(outcome)).not.toContain("v:token");
+  });
+
+  it("is registered in the starter set as a typed stub until a provider row (#1830) wires an adapter", async () => {
+    const registry = createCapabilityRegistry();
+    const starter = registry.resolve("ensure-secret");
+    expect(starter.rollbackPolicy).toBe("needs-opt-out");
+    await expect(starter.run(ctx as never, {} as never)).rejects.toThrowError(CapabilityNotImplementedError);
+  });
+});
+
+describe("COMP003 over ensure-secret", () => {
+  /** The same derivation chant lint's resolveRegistryContext performs. */
+  function registryRollbackPolicies(): Map<string, RollbackPolicy> {
+    const registry = createCapabilityRegistry();
+    const policies = new Map<string, RollbackPolicy>();
+    for (const kind of registry.kinds()) {
+      const capability = registry.resolve(kind);
+      policies.set(kind, capability.rollbackPolicy ?? (capability.rollback ? "native" : "none-by-design"));
+    }
+    return policies;
+  }
+
+  const [comp003] = loadComponentChecks().filter((c) => c.id === "COMP003");
+
+  function checkComponent(step: Record<string, unknown>) {
+    const checkCtx = {
+      rollbackPolicies: registryRollbackPolicies(),
+      components: new Map([
+        [
+          "fountain",
+          {
+            component: {
+              name: "fountain",
+              dependsOn: [],
+              deploy: [{ phase: "Secrets", steps: [step] }],
+            },
+            filePath: "fountain.component.ts",
+          },
+        ],
+      ]),
+    };
+    return comp003.check(checkCtx as never);
+  }
+
+  it("flags a bare ensure-secret step — minting has no safe undo, so the gap needs an explicit opt-out", () => {
+    const diagnostics = checkComponent({ kind: "ensure-secret", name: "master-key", keys: ["MASTER_SECRETS_KEY"] });
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0].checkId).toBe("COMP003");
+    expect(diagnostics[0].message).toContain("ensure-secret");
+  });
+
+  it("accepts the step once the component acknowledges the gap via noRollback", () => {
+    const diagnostics = checkComponent({
+      kind: "ensure-secret",
+      name: "master-key",
+      keys: ["MASTER_SECRETS_KEY"],
+      noRollback: "generated-once: un-creating would destroy the only copy of the material",
+    });
+    expect(diagnostics).toHaveLength(0);
+  });
+});

package/src/components/verbs/ensure-secret.ts

@@ -0,0 +1,79 @@
+/**
+ * secrets family — `ensure-secret` (#1829, epic #1365 decision 3). The
+ * capability surface over the one generated-once materialization engine
+ * (../../secret-materialization.ts); the op step builder `ensureSecret(...)`
+ * (../../op/builders.ts) is the other surface over the same engine.
+ *
+ * Contract (read-then-write): present means done. The verb never mints over
+ * an existing value and never rotates implicitly; an existing secret that
+ * does not match the declared key-set/metadata stops the apply with a
+ * `SecretContractMismatchError` naming key names and metadata keys — never
+ * values. There is no safe undo for minting a secret others may already have
+ * consumed, and un-creating it would destroy the only copy of the material —
+ * so `rollbackPolicy: "needs-opt-out"`: COMP003 requires a component using
+ * this verb to acknowledge the compensation gap explicitly.
+ *
+ * The store adapter is per-provider (#1830 is the k8s row). Core registers a
+ * typed stub; a provider builds the real capability with
+ * {@link createEnsureSecretCapability}.
+ */
+
+import type { Capability } from "../capability";
+import { CapabilityNotImplementedError } from "../capability";
+import {
+  ensureSecretMaterialization,
+  defaultSecretMaterialGenerator,
+  type EnsureSecretOutcome,
+  type SecretMaterialGenerator,
+  type SecretStoreAdapter,
+} from "../../secret-materialization";
+
+export interface EnsureSecretInput {
+  /** The secret's name as the store knows it. */
+  name: string;
+  /** The declared key-set. Creation mints one value per key; verification compares names only. */
+  keys: string[];
+  /** Declared metadata an existing secret must carry. Mismatches are reported by KEY. */
+  metadata?: Record<string, string>;
+}
+
+/** Names only — no field of the output can carry material. */
+export type EnsureSecretOutput = EnsureSecretOutcome;
+
+/**
+ * Build the real `ensure-secret` capability over a provider's
+ * {@link SecretStoreAdapter}. The generator seam defaults to 32 CSPRNG bytes
+ * per key; the material it mints flows straight through the adapter to the
+ * store and is never returned, logged, or retained (see
+ * ../../secret-materialization.ts).
+ */
+export function createEnsureSecretCapability(deps: {
+  store: SecretStoreAdapter;
+  generator?: SecretMaterialGenerator;
+}): Capability<EnsureSecretInput, EnsureSecretOutput> {
+  return {
+    kind: "ensure-secret",
+    rollbackPolicy: "needs-opt-out",
+    async run(_ctx, input) {
+      return ensureSecretMaterialization(
+        deps.store,
+        { name: input.name, keys: input.keys, metadata: input.metadata },
+        deps.generator ?? defaultSecretMaterialGenerator,
+      );
+    },
+  };
+}
+
+/**
+ * The starter-set registration: fully typed, correct `rollbackPolicy` for
+ * COMP003, but no store adapter — running it throws
+ * `CapabilityNotImplementedError` until a provider row (#1830, k8s) wires a
+ * real adapter via {@link createEnsureSecretCapability}.
+ */
+export const ensureSecretCapability: Capability<EnsureSecretInput, EnsureSecretOutput> = {
+  kind: "ensure-secret",
+  rollbackPolicy: "needs-opt-out",
+  async run(): Promise<EnsureSecretOutput> {
+    throw new CapabilityNotImplementedError("ensure-secret");
+  },
+};

package/src/components/verbs/index.ts

@@ -26,6 +26,11 @@
  * `ProvenanceLink` material. `verify` (#622, ./verify.ts) is the matching
  * deploy-time gate — `cosign verify`/`verify-attestation` against a
  * configured identity policy, mirroring ../../lint/policy.ts's `policyGate`.
+ * `wrangler-deploy`/`wrangler-versions-promote` (#1293, epic #1296,
+ * ./wrangler.ts) and `r2-sync` (#1293, ./r2-sync.ts) are the Cloudflare
+ * Workers apply leaves — real implementations over the same injectable
+ * `ProcessRunner` `sign` uses, shelling to `wrangler`/`rclone` rather than an
+ * AWS-shaped SDK client.
  */
 
 export * from "./build-archive";
@@ -39,11 +44,14 @@ export * from "./component-bom";
 export * from "./reproducibility";
 export * from "./sign";
 export * from "./verify";
+export * from "./wrangler";
+export * from "./r2-sync";
 export * from "./vuln-scan";
 export * from "./vex";
 export * from "./license-policy";
 export * from "./vuln-gate";
 export * from "./wait-verify";
 export * from "./shell";
+export * from "./ensure-secret";
 export * from "./cloud-executor";
 export * from "./process-runner";

package/src/components/verbs/r2-sync.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Tests `r2-sync` (#1293, epic #1296, ./r2-sync.ts) against a
+ * `MockProcessRunner` — no live `rclone`, no network call, ever. Asserts the
+ * `r2://` destination shape mirrors `s3-sync`'s `s3://` shape, the
+ * copy-vs-sync dispatch on `delete`, the uploaded/deleted count parsing, and
+ * the `needs-opt-out` rollback disposition `s3-sync` also carries.
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  buildR2SyncArgs,
+  createR2SyncCapability,
+  parseRcloneStats,
+  R2SyncInvalidDestinationError,
+  toRcloneDest,
+} from "./r2-sync";
+import { ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "prod", component: "assets" };
+
+describe("toRcloneDest", () => {
+  it("translates r2://bucket/prefix to the default 'r2' rclone remote", () => {
+    expect(toRcloneDest("r2://my-bucket/assets")).toBe("r2:my-bucket/assets");
+  });
+
+  it("translates a bare bucket with no prefix", () => {
+    expect(toRcloneDest("r2://my-bucket")).toBe("r2:my-bucket");
+  });
+
+  it("honours an explicit remote name override", () => {
+    expect(toRcloneDest("r2://my-bucket/assets", "cf-r2")).toBe("cf-r2:my-bucket/assets");
+  });
+
+  it("throws R2SyncInvalidDestinationError for a non-r2:// URI (e.g. an s3:// one passed by mistake)", () => {
+    expect(() => toRcloneDest("s3://my-bucket/assets")).toThrow(R2SyncInvalidDestinationError);
+  });
+});
+
+describe("buildR2SyncArgs", () => {
+  it("uses 'rclone copy' by default — never deletes destination-only keys, matching s3-sync's default", () => {
+    const cmd = buildR2SyncArgs({ from: "dist/assets", to: "r2://my-bucket/assets" });
+    expect(cmd).toBe(`rclone copy 'dist/assets' 'r2:my-bucket/assets' -v`);
+  });
+
+  it("uses 'rclone sync' when delete: true — matching s3-sync's opt-in delete", () => {
+    const cmd = buildR2SyncArgs({ from: "dist/assets", to: "r2://my-bucket/assets", delete: true });
+    expect(cmd).toBe(`rclone sync 'dist/assets' 'r2:my-bucket/assets' -v`);
+  });
+});
+
+describe("parseRcloneStats", () => {
+  it("counts new and replaced uploads together as 'uploaded'", () => {
+    const stdout = [
+      "2026/08/24 10:00:00 INFO  : a.txt: Copied (new)",
+      "2026/08/24 10:00:00 INFO  : b.txt: Copied (replaced existing)",
+      "2026/08/24 10:00:00 INFO  : c.txt: Copied (new)",
+    ].join("\n");
+    expect(parseRcloneStats(stdout)).toEqual({ uploaded: 3, deleted: 0 });
+  });
+
+  it("counts deletions separately", () => {
+    const stdout = [
+      "2026/08/24 10:00:00 INFO  : a.txt: Copied (new)",
+      "2026/08/24 10:00:00 INFO  : stale.txt: Deleted",
+    ].join("\n");
+    expect(parseRcloneStats(stdout)).toEqual({ uploaded: 1, deleted: 1 });
+  });
+
+  it("returns zeros for a no-op sync", () => {
+    expect(parseRcloneStats("2026/08/24 10:00:00 INFO  : There was nothing to transfer\n")).toEqual({
+      uploaded: 0,
+      deleted: 0,
+    });
+  });
+});
+
+describe("r2-sync capability", () => {
+  it("round-trips a directory upload and reports the object count", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "rclone copy": "2026/08/24 10:00:00 INFO  : a.txt: Copied (new)\n2026/08/24 10:00:00 INFO  : b.txt: Copied (new)\n",
+      },
+    });
+    const capability = createR2SyncCapability(mock.runner);
+
+    const output = await capability.run(ctx, { from: "dist/assets", to: "r2://my-bucket/assets" });
+
+    expect(output).toEqual({ uploaded: 2, deleted: 0 });
+    expect(mock.calls.some((c) => c.command === `rclone copy 'dist/assets' 'r2:my-bucket/assets' -v`)).toBe(true);
+  });
+
+  it("throws ToolNotAvailableError when rclone is absent, rather than silently skipping the sync", async () => {
+    const mock = createMockProcessRunner({ tools: { rclone: false } });
+    const capability = createR2SyncCapability(mock.runner);
+
+    await expect(capability.run(ctx, { from: "dist/assets", to: "r2://my-bucket/assets" })).rejects.toBeInstanceOf(
+      ToolNotAvailableError,
+    );
+  });
+
+  it("declares rollbackPolicy: needs-opt-out — a mutating, destructive-capable sync with no native undo, same as s3-sync", () => {
+    const capability = createR2SyncCapability(createMockProcessRunner().runner);
+    expect(capability.rollbackPolicy).toBe("needs-opt-out");
+    expect(capability.rollback).toBeUndefined();
+  });
+});

package/src/components/verbs/r2-sync.ts

@@ -0,0 +1,124 @@
+/**
+ * `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 type { Capability } from "../capability";
+import { defaultProcessRunner, q, requireTool, type ProcessRunner } from "./process-runner";
+
+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(public readonly to: string) {
+    super(
+      `r2-sync: destination "${to}" is not an "r2://bucket[/prefix]" URI — mirror s3-sync's "s3://bucket/prefix" shape.`,
+    );
+    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: string, remote = "r2"): string {
+  const match = R2_URI_RE.exec(to);
+  if (!match) throw new R2SyncInvalidDestinationError(to);
+  const [, bucket, prefix] = match;
+  return `${remote}:${bucket}${prefix ? `/${prefix}` : ""}`;
+}
+
+export interface R2SyncInput {
+  /** Local path, or archive-relative path, to sync from. */
+  from: string;
+  /** Destination bucket URI, `"r2://bucket/prefix"` — mirrors `s3-sync`'s `S3SyncInput.to` shape. */
+  to: string;
+  /** Delete destination keys not present in the source. Default: false. */
+  delete?: boolean;
+  /** rclone remote name pointed at R2. Default: `"r2"`. */
+  remote?: string;
+}
+
+export interface R2SyncOutput {
+  /** Number of objects uploaded (new or changed). */
+  uploaded: number;
+  /** Number of objects deleted (only possible when `delete: true`). */
+  deleted: number;
+}
+
+/**
+ * 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: R2SyncInput): string {
+  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: string): R2SyncOutput {
+  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: ProcessRunner = defaultProcessRunner(),
+): Capability<R2SyncInput, R2SyncOutput> {
+  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: Capability<R2SyncInput, R2SyncOutput> = createR2SyncCapability();

package/src/components/verbs/wrangler.test.ts

@@ -0,0 +1,170 @@
+/**
+ * Tests `wrangler-deploy`/`wrangler-versions-promote` (#1293, epic #1296,
+ * ./wrangler.ts) against a `MockProcessRunner` — no live `wrangler`, no
+ * network call, ever. Asserts the constructed invocations, the version-id
+ * extraction, the wired output -> promote input handoff, and the
+ * captured-previous-version rollback (the "no hand-written compensation"
+ * claim from #1293's verification section).
+ */
+
+import { describe, expect, it } from "vitest";
+import {
+  createWranglerDeployCapability,
+  createWranglerVersionsPromoteCapability,
+  parseWranglerVersionId,
+  WranglerVersionIdNotFoundError,
+} from "./wrangler";
+import { ToolNotAvailableError } from "./process-runner";
+import { createMockProcessRunner } from "./__tests__/mock-process-runner";
+
+const ctx = { env: "prod", component: "api-worker" };
+const VERSION_A = "07bcb198-9633-4172-a1f0-b09f6f1a1a11";
+const VERSION_B = "aa11bb22-cc33-dd44-ee55-ff6677889900";
+
+describe("wrangler-deploy", () => {
+  it("shells `wrangler deploy` with --config, extracts the Version ID from stdout", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "wrangler deploy": `Uploaded api-worker (1.23 sec)\nVersion ID: ${VERSION_A}\n` },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    const output = await capability.run(ctx, { config: "api/wrangler.jsonc" });
+
+    expect(output).toEqual({ versionId: VERSION_A });
+    const deployCall = mock.calls.find((c) => c.command.startsWith("wrangler deploy"))!;
+    expect(deployCall.command).toBe(`wrangler deploy --config 'api/wrangler.jsonc'`);
+  });
+
+  it("passes --env through when supplied", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "wrangler deploy": `Version ID: ${VERSION_A}\n` },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    await capability.run(ctx, { config: "api/wrangler.jsonc", env: "staging" });
+
+    const deployCall = mock.calls.find((c) => c.command.startsWith("wrangler deploy"))!;
+    expect(deployCall.command).toBe(`wrangler deploy --config 'api/wrangler.jsonc' --env 'staging'`);
+  });
+
+  it("throws WranglerVersionIdNotFoundError when stdout carries no Version ID", async () => {
+    const mock = createMockProcessRunner({ responses: { "wrangler deploy": "Uploaded, nothing else.\n" } });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    await expect(capability.run(ctx, { config: "api/wrangler.jsonc" })).rejects.toBeInstanceOf(
+      WranglerVersionIdNotFoundError,
+    );
+  });
+
+  it("throws ToolNotAvailableError when wrangler is absent, rather than silently no-op'ing", async () => {
+    const mock = createMockProcessRunner({ tools: { wrangler: false } });
+    const capability = createWranglerDeployCapability(mock.runner);
+
+    await expect(capability.run(ctx, { config: "api/wrangler.jsonc" })).rejects.toBeInstanceOf(
+      ToolNotAvailableError,
+    );
+  });
+
+  it("declares a rollback (native rollback disposition, no rollbackPolicy override needed)", () => {
+    const capability = createWranglerDeployCapability(createMockProcessRunner().runner);
+    expect(typeof capability.rollback).toBe("function");
+    expect(capability.rollbackPolicy).toBeUndefined();
+  });
+
+  it("rollback is a no-op on a first deploy — nothing was live before it", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "versions list": "[]", "wrangler deploy": `Version ID: ${VERSION_A}\n` },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+    await capability.run(ctx, { config: "api/wrangler.jsonc" });
+
+    await capability.rollback!(ctx, { config: "api/wrangler.jsonc" });
+
+    expect(mock.calls.some((c) => c.command.includes("versions deploy"))).toBe(false);
+  });
+
+  it("rollback promotes back to whichever version was live before this deploy — the wrangler-versions-promote back-to-prior-version claim, with no hand-written compensation", async () => {
+    const mock = createMockProcessRunner({
+      responses: {
+        "versions list": JSON.stringify([{ id: VERSION_A, percentage: 100 }]),
+        "wrangler deploy": `Version ID: ${VERSION_B}\n`,
+      },
+    });
+    const capability = createWranglerDeployCapability(mock.runner);
+    await capability.run(ctx, { config: "api/wrangler.jsonc" });
+
+    await capability.rollback!(ctx, { config: "api/wrangler.jsonc" });
+
+    const promoteCall = mock.calls.find((c) => c.command.startsWith("wrangler versions deploy"))!;
+    expect(promoteCall.command).toBe(
+      `wrangler versions deploy '${VERSION_A}@100' --config 'api/wrangler.jsonc' --yes`,
+    );
+  });
+});
+
+describe("wrangler-versions-promote", () => {
+  it("shells `wrangler versions deploy <id>@<pct> --yes`, defaulting percentage to 100", async () => {
+    const mock = createMockProcessRunner();
+    const capability = createWranglerVersionsPromoteCapability(mock.runner);
+
+    const output = await capability.run(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_A });
+
+    expect(output).toEqual({ versionId: VERSION_A, percentage: 100 });
+    const promoteCall = mock.calls.find((c) => c.command.startsWith("wrangler versions deploy"))!;
+    expect(promoteCall.command).toBe(
+      `wrangler versions deploy '${VERSION_A}@100' --config 'api/wrangler.jsonc' --yes`,
+    );
+  });
+
+  it("consumes a wired wrangler-deploy output as its versionId input", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "wrangler deploy": `Version ID: ${VERSION_A}\n` },
+    });
+    const deploy = createWranglerDeployCapability(mock.runner);
+    const promote = createWranglerVersionsPromoteCapability(mock.runner);
+
+    const { versionId } = await deploy.run(ctx, { config: "api/wrangler.jsonc" });
+    const promoted = await promote.run(ctx, { config: "api/wrangler.jsonc", versionId, percentage: 10 });
+
+    expect(promoted).toEqual({ versionId: VERSION_A, percentage: 10 });
+    const promoteCall = mock.calls.find((c) => c.command.startsWith("wrangler versions deploy"))!;
+    expect(promoteCall.command).toContain(`'${VERSION_A}@10'`);
+  });
+
+  it("declares a rollback (native): re-promotes to whichever version was live before this promote call", async () => {
+    const mock = createMockProcessRunner({
+      responses: { "versions list": JSON.stringify([{ id: VERSION_A, percentage: 100 }]) },
+    });
+    const capability = createWranglerVersionsPromoteCapability(mock.runner);
+    await capability.run(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_B });
+
+    await capability.rollback!(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_B });
+
+    const calls = mock.calls.filter((c) => c.command.startsWith("wrangler versions deploy"));
+    expect(calls).toHaveLength(2);
+    expect(calls[0]!.command).toContain(`'${VERSION_B}@100'`);
+    expect(calls[1]!.command).toContain(`'${VERSION_A}@100'`);
+  });
+
+  it("throws ToolNotAvailableError when wrangler is absent", async () => {
+    const mock = createMockProcessRunner({ tools: { wrangler: false } });
+    const capability = createWranglerVersionsPromoteCapability(mock.runner);
+
+    await expect(
+      capability.run(ctx, { config: "api/wrangler.jsonc", versionId: VERSION_A }),
+    ).rejects.toBeInstanceOf(ToolNotAvailableError);
+  });
+});
+
+describe("parseWranglerVersionId", () => {
+  it("accepts both 'Version ID:' and bare 'Version:' wording", () => {
+    expect(parseWranglerVersionId(`Version ID: ${VERSION_A}`)).toBe(VERSION_A);
+    expect(parseWranglerVersionId(`Version: ${VERSION_A}`)).toBe(VERSION_A);
+  });
+
+  it("throws on stdout with no UUID-shaped version token", () => {
+    expect(() => parseWranglerVersionId("Version: 2 (a plain counter, not a version id)")).toThrow(
+      WranglerVersionIdNotFoundError,
+    );
+  });
+});