@intentius/chant 0.46.0 → 0.49.0

package/src/cli/reporters/stylish.ts

@@ -1,4 +1,5 @@
 import type { LintDiagnostic, LintRule, Severity } from "../../lint/rule";
+import type { OkfBundle } from "../../okf-read";
 import { pathToFileURL } from "node:url";
 
 /**
@@ -33,64 +34,184 @@ function color(text: string, colorCode: string): string {
 /**
  * Format diagnostics in stylish format (similar to ESLint)
  * Groups by file, shows severity, message, and rule ID
+ *
+ * @param diagnostics - Active (non-suppressed) diagnostics
+ * @param suppressed - Suppressed diagnostics with optional reason (optional). When
+ *   present and non-empty, a "Suppressed" section is appended (#1866, design #1059)
+ *   below the active diagnostics, mirroring SARIF's `suppressed` param on
+ *   {@link formatSarif} rather than changing what "diagnostics" means here.
+ * @param bundle - The project's loaded OKF knowledge bundle (`../../okf-read`'s
+ *   `loadOkfBundle`), used to resolve `okf:` citations in suppression reasons.
+ *   Omitted (or a bundle with no matching concept) falls back to printing the
+ *   raw reason with a warning — this never affects suppression itself, only
+ *   how a cited reason renders.
  */
-export function formatStylish(diagnostics: LintDiagnostic[]): string {
-  if (diagnostics.length === 0) {
+export function formatStylish(
+  diagnostics: LintDiagnostic[],
+  suppressed?: Array<LintDiagnostic & { reason?: string }>,
+  bundle?: OkfBundle,
+): string {
+  const hasSuppressed = suppressed !== undefined && suppressed.length > 0;
+
+  if (diagnostics.length === 0 && !hasSuppressed) {
     return formatSummary(0, 0);
   }
 
-  // Group by file
-  const byFile = new Map<string, LintDiagnostic[]>();
-  for (const diag of diagnostics) {
+  const lines: string[] = [];
+  let errorCount = 0;
+  let warningCount = 0;
+
+  if (diagnostics.length > 0) {
+    // Group by file
+    const byFile = new Map<string, LintDiagnostic[]>();
+    for (const diag of diagnostics) {
+      const existing = byFile.get(diag.file) ?? [];
+      existing.push(diag);
+      byFile.set(diag.file, existing);
+    }
+
+    for (const [file, fileDiags] of byFile) {
+      // File header with underline
+      lines.push("");
+      lines.push(color(file, colors.underline));
+
+      // Sort by line, then column
+      fileDiags.sort((a, b) => {
+        if (a.line !== b.line) return a.line - b.line;
+        return a.column - b.column;
+      });
+
+      for (const diag of fileDiags) {
+        // Count errors and warnings
+        if (diag.severity === "error") {
+          errorCount++;
+        } else if (diag.severity === "warning") {
+          warningCount++;
+        }
+
+        // Format: "  line:col  severity  message  ruleId"
+        const location = color(
+          `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`,
+          colors.gray
+        );
+
+        const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
+        const severity = color(diag.severity.padEnd(7), severityColor);
+
+        const ruleId = color(diag.ruleId, colors.gray);
+
+        lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+      }
+    }
+  }
+
+  if (hasSuppressed) {
+    lines.push(...formatSuppressedSection(suppressed!, bundle));
+  }
+
+  // Summary line
+  lines.push("");
+  const summary = formatSummary(errorCount, warningCount);
+  lines.push(summary);
+
+  return lines.join("\n");
+}
+
+/**
+ * A suppression reason's `okf:` citation, resolved against a loaded bundle.
+ */
+interface ResolvedCitation {
+  /** What to print beside the rule id: the concept title when resolved, the raw reason otherwise. */
+  label: string;
+  /** The concept's bundle-relative path, printed on the line below — only set when resolved. */
+  path?: string;
+  /** True when the reason carried an `okf:` token that named no concept in `bundle`. */
+  unresolved: boolean;
+}
+
+/**
+ * Resolve a suppression reason's `okf:<path>` citation (#1866, design #1059)
+ * against a loaded bundle's concepts, matched on `OkfConcept.path`. Not an
+ * `okf:` citation at all: returns `null`, and the reason renders as plain
+ * text, same as before this section existed. A leading `/` on the cited path
+ * is accepted and stripped — `okf-read.ts`'s bundle-relative paths never
+ * carry one, but the design doc's worked example writes citations with one
+ * (mirroring an absolute-from-bundle-root reading), so both forms resolve.
+ */
+function resolveOkfCitation(reason: string, bundle: OkfBundle | undefined): ResolvedCitation | null {
+  const prefix = "okf:";
+  if (!reason.startsWith(prefix)) return null;
+
+  const token = reason.slice(prefix.length).trim().replace(/^\/+/, "");
+  const concept = bundle?.concepts.find((c) => c.path === token);
+
+  if (concept) {
+    return { label: concept.title ?? concept.path, path: concept.path, unresolved: false };
+  }
+
+  return { label: reason, unresolved: true };
+}
+
+/**
+ * Render the "Suppressed" section: every suppressed diagnostic, grouped by
+ * file like the active section above, with an `okf:` reason resolved to its
+ * concept's title (and bundle-relative path on the line below) when
+ * `bundle` has a match. A citation naming no concept — including when no
+ * `bundle` was loaded at all — prints the raw reason plus a warning; a
+ * plain (non-`okf:`) reason prints as-is. Never affects which diagnostics
+ * are suppressed, only how the reason renders (design #1059: "a cited
+ * suppression suppresses exactly as an uncited one does").
+ */
+function formatSuppressedSection(
+  suppressed: Array<LintDiagnostic & { reason?: string }>,
+  bundle: OkfBundle | undefined,
+): string[] {
+  const lines: string[] = [];
+
+  const byFile = new Map<string, Array<LintDiagnostic & { reason?: string }>>();
+  for (const diag of suppressed) {
     const existing = byFile.get(diag.file) ?? [];
     existing.push(diag);
     byFile.set(diag.file, existing);
   }
 
-  const lines: string[] = [];
-  let errorCount = 0;
-  let warningCount = 0;
+  lines.push("");
+  lines.push(color("Suppressed", colors.underline));
 
   for (const [file, fileDiags] of byFile) {
-    // File header with underline
     lines.push("");
     lines.push(color(file, colors.underline));
 
-    // Sort by line, then column
     fileDiags.sort((a, b) => {
       if (a.line !== b.line) return a.line - b.line;
       return a.column - b.column;
     });
 
     for (const diag of fileDiags) {
-      // Count errors and warnings
-      if (diag.severity === "error") {
-        errorCount++;
-      } else if (diag.severity === "warning") {
-        warningCount++;
-      }
-
-      // Format: "  line:col  severity  message  ruleId"
-      const location = color(
-        `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`,
-        colors.gray
-      );
-
-      const severityColor = diag.severity === "error" ? colors.red : colors.yellow;
-      const severity = color(diag.severity.padEnd(7), severityColor);
-
+      const locationPlain = `${String(diag.line).padStart(4)}:${String(diag.column).padEnd(3)}`;
+      const location = color(locationPlain, colors.gray);
+      const severity = color("suppressed", colors.cyan);
       const ruleId = color(diag.ruleId, colors.gray);
 
-      lines.push(`  ${location}  ${severity}  ${diag.message}  ${ruleId}`);
+      const citation = diag.reason ? resolveOkfCitation(diag.reason, bundle) : null;
+      const indent = " ".repeat(2 + locationPlain.length + 2 + "suppressed".length + 2 + diag.ruleId.length + 2);
+
+      if (citation) {
+        lines.push(`  ${location}  ${severity}  ${ruleId}  ${citation.label}`);
+        if (!citation.unresolved) {
+          lines.push(`${indent}${color(citation.path!, colors.gray)}`);
+        } else {
+          lines.push(`${indent}${color("⚠ unresolved okf citation", colors.yellow)}`);
+        }
+      } else if (diag.reason) {
+        lines.push(`  ${location}  ${severity}  ${ruleId}  ${diag.reason}`);
+      } else {
+        lines.push(`  ${location}  ${severity}  ${ruleId}`);
+      }
     }
   }
 
-  // Summary line
-  lines.push("");
-  const summary = formatSummary(errorCount, warningCount);
-  lines.push(summary);
-
-  return lines.join("\n");
+  return lines;
 }
 
 /**

package/src/components/auto-release.ts

@@ -117,6 +117,10 @@ export interface AutoReleaseRunInfo {
   digest?: string;
   /** Orchestrator run identifier — a Temporal `runId`, or a locally generated id for the local executor (mirrors `runComponentsReleaseRecord`'s `--run-id` default). */
   runId: string;
+  /** The bypassed capability-profile divergences, when the caller deliberately overrode a deploy-time profile assertion (chant #1244) — recorded verbatim as the release record's `profileOverride`. */
+  profileOverride?: string;
+  /** The deploy's input-side digest, when `digest` is a rendered-content identity (a pinned helm deploy, chant #1242) — recorded as the release record's `inputDigest` so ledger queries can still join on inputs across clusters whose bytes legitimately differ. */
+  inputDigest?: string;
 }
 
 /** Opt-out + field-override knobs for auto-release recording, threaded from CLI flags/config (#597: "opt-out-able (flag/config), documented default"). */
@@ -202,6 +206,8 @@ export async function maybeRecordAutoRelease(
         runId: run.runId,
         timestamp,
         actor,
+        ...(run.profileOverride ? { profileOverride: run.profileOverride } : {}),
+        ...(run.inputDigest ? { inputDigest: run.inputDigest } : {}),
       },
       { cwd: options.cwd },
     );

package/src/components/registry.test.ts

@@ -92,9 +92,14 @@ describe("createCapabilityRegistry", () => {
     }
   });
 
-  test("family table lists exactly the agnostic starter families (cloud leaves moved to lexicons)", () => {
+  // Every AWS/k8s cloud leaf moved out to its lexicon — but the three
+  // Cloudflare Workers apply verbs (#1293, epic #1296) stay in core by
+  // deliberate decision (see ./verbs/wrangler.ts's module doc): the epic
+  // cedes the Workers plane to `wrangler` and there is no cloudflare lexicon
+  // for them to live in instead.
+  test("family table lists exactly the agnostic starter families plus the Cloudflare apply leaves (#1293)", () => {
     expect(Object.keys(STARTER_VERB_FAMILIES).sort()).toEqual(
-      ["build", "escapeHatch", "sbom", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
+      ["build", "cloudflare", "escapeHatch", "sbom", "secrets", "supplyChainPolicy", "supplyChainSecurity", "waitVerify"].sort(),
     );
   });
 

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();
+  });
+});