@decocms/blocks-cli 7.6.0 → 7.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.6.0",
+  "version": "7.8.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -34,7 +34,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.6.0",
+    "@decocms/blocks": "7.8.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/fast-deploy-kv.test.ts

@@ -1,13 +1,54 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import { describe, expect, it, vi } from "vitest";
-import { computeRevision, KV_KEYS } from "@decocms/blocks/cms";
-import { createKvRestClient, kvConfigFromEnv } from "./lib/cf-kv-rest";
-import { buildSnapshot, verifySnapshotInKv, writeSnapshotToKv } from "./lib/kv-snapshot";
+import {
+  computeRevision,
+  DEPLOYMENTS_KEY,
+  LIVE_KEY,
+  revisionKey,
+  snapshotKey,
+} from "@decocms/blocks/cms";
+import { createKvRestClient, type KvRestClient, kvConfigFromEnv } from "./lib/cf-kv-rest";
+import { kvNamespaceIdFromToml, kvNamespaceIdFromWrangler } from "./lib/wrangler-config";
+import {
+  buildSnapshot,
+  recordAndGcDeployment,
+  setLiveDeployment,
+  verifySnapshotInKv,
+  writeSnapshotToKv,
+} from "./lib/kv-snapshot";
 import {
   changedBlockFiles,
   changedBlockKeys,
   purgePathsForChangedKeys,
 } from "./lib/sync-helpers";
 
+const ID = "sha-abc123";
+
+/** In-memory KvRestClient backed by a Map, recording put order. */
+function makeClient(initial: Record<string, string> = {}) {
+  const store = new Map<string, string>(Object.entries(initial));
+  const putOrder: string[] = [];
+  const client: KvRestClient = {
+    get: (k) => Promise.resolve(store.get(k) ?? null),
+    put: (k, v) => {
+      putOrder.push(k);
+      store.set(k, v);
+      return Promise.resolve();
+    },
+    delete: (k) => {
+      store.delete(k);
+      return Promise.resolve();
+    },
+    list: (prefix) =>
+      Promise.resolve(
+        [...store.keys()].filter((k) => !prefix || k.startsWith(prefix)),
+      ),
+  };
+  return { client, store, putOrder };
+}
+
 describe("kvConfigFromEnv", () => {
   it("reads the three CF vars", () => {
     expect(
@@ -15,29 +56,128 @@ describe("kvConfigFromEnv", () => {
     ).toEqual({ accountId: "a", namespaceId: "n", token: "t" });
   });
 
-  it("throws listing all missing vars", () => {
+  it("falls back to the CLOUDFLARE_* names CF Workers Builds injects", () => {
+    expect(
+      kvConfigFromEnv({
+        CLOUDFLARE_ACCOUNT_ID: "a",
+        CLOUDFLARE_API_TOKEN: "t",
+        CF_KV_NAMESPACE_ID: "n",
+      }),
+    ).toEqual({ accountId: "a", namespaceId: "n", token: "t" });
+  });
+
+  it("prefers explicit CF_* over CLOUDFLARE_*", () => {
+    expect(
+      kvConfigFromEnv({
+        CF_ACCOUNT_ID: "cf",
+        CLOUDFLARE_ACCOUNT_ID: "cloudflare",
+        CF_API_TOKEN: "t",
+        CF_KV_NAMESPACE_ID: "n",
+      }).accountId,
+    ).toBe("cf");
+  });
+
+  it("reads the namespace id from wrangler config when CF_KV_NAMESPACE_ID is unset", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "wrangler-"));
+    fs.writeFileSync(
+      path.join(dir, "wrangler.jsonc"),
+      JSON.stringify({ kv_namespaces: [{ binding: "DECO_KV", id: "ns-from-config" }] }),
+    );
+    expect(
+      kvConfigFromEnv({ CF_ACCOUNT_ID: "a", CF_API_TOKEN: "t" }, { wranglerDir: dir }),
+    ).toEqual({ accountId: "a", namespaceId: "ns-from-config", token: "t" });
+  });
+
+  it("throws listing all missing config", () => {
     expect(() => kvConfigFromEnv({ CF_ACCOUNT_ID: "a" })).toThrow(
-      /CF_KV_NAMESPACE_ID, CF_API_TOKEN/,
+      /CF_KV_NAMESPACE_ID.*CF_API_TOKEN/,
     );
   });
 });
 
+describe("kvNamespaceIdFromWrangler / kvNamespaceIdFromToml", () => {
+  it("reads the DECO_KV id from wrangler.jsonc (with comments + trailing comma)", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "wrangler-"));
+    fs.writeFileSync(
+      path.join(dir, "wrangler.jsonc"),
+      `{
+        // deco fast-deploy
+        "kv_namespaces": [
+          { "binding": "OTHER", "id": "nope" },
+          { "binding": "DECO_KV", "id": "abc123" },
+        ],
+      }`,
+    );
+    expect(kvNamespaceIdFromWrangler(dir)).toBe("abc123");
+  });
+
+  it("returns null when no wrangler config is present", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "wrangler-"));
+    expect(kvNamespaceIdFromWrangler(dir)).toBeNull();
+  });
+
+  it("parses [[kv_namespaces]] blocks from wrangler.toml", () => {
+    const toml = `
+name = "my-site"
+
+[[kv_namespaces]]
+binding = "OTHER"
+id = "nope"
+
+[[kv_namespaces]]
+binding = "DECO_KV"
+id = "toml-id"
+
+[vars]
+DECO_FAST_DEPLOY = "1"
+`;
+    expect(kvNamespaceIdFromToml(toml)).toBe("toml-id");
+    expect(kvNamespaceIdFromToml(toml, "MISSING")).toBeNull();
+  });
+});
+
 describe("createKvRestClient", () => {
   const config = { accountId: "acc", namespaceId: "ns", token: "tok" };
 
   it("PUTs to the values endpoint with auth + body", async () => {
     const fetchImpl = vi.fn(async () => new Response("", { status: 200 })) as unknown as typeof fetch;
     const client = createKvRestClient({ ...config, fetchImpl });
-    await client.put(KV_KEYS.REVISION, "rev1");
+    const key = revisionKey(ID);
+    await client.put(key, "rev1");
 
     const [url, init] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0];
     expect(url).toContain("/accounts/acc/storage/kv/namespaces/ns/values/");
-    expect(url).toContain(encodeURIComponent(KV_KEYS.REVISION));
+    expect(url).toContain(encodeURIComponent(key));
     expect(init.method).toBe("PUT");
     expect(init.headers.Authorization).toBe("Bearer tok");
     expect(init.body).toBe("rev1");
   });
 
+  it("DELETE tolerates a 404 (idempotent)", async () => {
+    const fetchImpl = vi.fn(async () => new Response("nope", { status: 404 })) as unknown as typeof fetch;
+    const client = createKvRestClient({ ...config, fetchImpl });
+    await expect(client.delete("gone")).resolves.toBeUndefined();
+  });
+
+  it("LIST follows the pagination cursor and filters by prefix", async () => {
+    const pages = [
+      { result: [{ name: "decofile:a" }], result_info: { cursor: "c1" } },
+      { result: [{ name: "decofile:b" }], result_info: { cursor: "" } },
+    ];
+    let call = 0;
+    const fetchImpl = vi.fn(
+      async () => new Response(JSON.stringify(pages[call++]), { status: 200 }),
+    ) as unknown as typeof fetch;
+    const client = createKvRestClient({ ...config, fetchImpl });
+    await expect(client.list("decofile:")).resolves.toEqual(["decofile:a", "decofile:b"]);
+
+    const [url0] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[0];
+    expect(url0).toContain("/keys?");
+    expect(url0).toContain("prefix=decofile");
+    const [url1] = (fetchImpl as unknown as ReturnType<typeof vi.fn>).mock.calls[1];
+    expect(url1).toContain("cursor=c1");
+  });
+
   it("GET returns null on 404", async () => {
     const fetchImpl = vi.fn(async () => new Response("nope", { status: 404 })) as unknown as typeof fetch;
     const client = createKvRestClient({ ...config, fetchImpl });
@@ -67,33 +207,105 @@ describe("kv-snapshot helpers", () => {
     expect(snap.count).toBe(2);
   });
 
-  it("writes snapshot before revision, then verifies round-trip", async () => {
-    const store = new Map<string, string>();
-    const order: string[] = [];
-    const client = {
-      get: (k: string) => Promise.resolve(store.get(k) ?? null),
-      put: (k: string, v: string) => {
-        order.push(k);
-        store.set(k, v);
-        return Promise.resolve();
-      },
-    };
+  it("writes the keyed snapshot before revision, then verifies round-trip", async () => {
+    const { client, putOrder } = makeClient();
     const snap = buildSnapshot(blocks);
-    await writeSnapshotToKv(client, snap);
+    await writeSnapshotToKv(client, snap, ID);
 
-    expect(order).toEqual([KV_KEYS.SNAPSHOT, KV_KEYS.REVISION]);
-    await expect(verifySnapshotInKv(client, snap.revision)).resolves.toEqual({ ok: true });
+    expect(putOrder).toEqual([snapshotKey(ID), revisionKey(ID)]);
+    await expect(verifySnapshotInKv(client, snap.revision, ID)).resolves.toEqual({ ok: true });
   });
 
   it("verify fails when the revision mismatches", async () => {
-    const store = new Map<string, string>([
-      [KV_KEYS.SNAPSHOT, "{}"],
-      [KV_KEYS.REVISION, "other"],
-    ]);
-    const client = { get: (k: string) => Promise.resolve(store.get(k) ?? null), put: () => Promise.resolve() };
-    const res = await verifySnapshotInKv(client, "expected");
+    const { client } = makeClient({
+      [snapshotKey(ID)]: "{}",
+      [revisionKey(ID)]: "other",
+    });
+    const res = await verifySnapshotInKv(client, "expected", ID);
     expect(res.ok).toBe(false);
   });
+
+  it("setLiveDeployment writes index:live", async () => {
+    const { client, store } = makeClient();
+    await setLiveDeployment(client, ID);
+    expect(store.get(LIVE_KEY)).toBe(ID);
+  });
+});
+
+describe("recordAndGcDeployment", () => {
+  it("appends to index:deployments (newest last, deduped)", async () => {
+    const { client, store } = makeClient({
+      [DEPLOYMENTS_KEY]: JSON.stringify([{ id: "old", ts: 1 }]),
+    });
+    await recordAndGcDeployment(client, "new", 2, 10);
+    expect(JSON.parse(store.get(DEPLOYMENTS_KEY)!)).toEqual([
+      { id: "old", ts: 1 },
+      { id: "new", ts: 2 },
+    ]);
+  });
+
+  it("re-recording an existing id moves it to newest without duplicating", async () => {
+    const { client, store } = makeClient({
+      [DEPLOYMENTS_KEY]: JSON.stringify([
+        { id: "a", ts: 1 },
+        { id: "b", ts: 2 },
+      ]),
+    });
+    await recordAndGcDeployment(client, "a", 3, 10);
+    expect(JSON.parse(store.get(DEPLOYMENTS_KEY)!)).toEqual([
+      { id: "b", ts: 2 },
+      { id: "a", ts: 3 },
+    ]);
+  });
+
+  it("prunes snapshots beyond the retain window", async () => {
+    const entries = [
+      { id: "d1", ts: 1 },
+      { id: "d2", ts: 2 },
+    ];
+    const initial: Record<string, string> = { [DEPLOYMENTS_KEY]: JSON.stringify(entries) };
+    for (const e of entries) {
+      initial[snapshotKey(e.id)] = "{}";
+      initial[revisionKey(e.id)] = "r";
+    }
+    const { client, store } = makeClient(initial);
+
+    // retain=2 → adding d3 evicts the oldest (d1).
+    const { pruned } = await recordAndGcDeployment(client, "d3", 3, 2);
+    expect(pruned).toEqual(["d1"]);
+    expect(store.has(snapshotKey("d1"))).toBe(false);
+    expect(store.has(revisionKey("d1"))).toBe(false);
+    expect(store.has(snapshotKey("d2"))).toBe(true);
+    expect(JSON.parse(store.get(DEPLOYMENTS_KEY)!).map((e: { id: string }) => e.id)).toEqual([
+      "d2",
+      "d3",
+    ]);
+  });
+
+  it("never prunes the currently-live deployment even if it is old", async () => {
+    const entries = [
+      { id: "d1", ts: 1 },
+      { id: "d2", ts: 2 },
+    ];
+    const initial: Record<string, string> = {
+      [DEPLOYMENTS_KEY]: JSON.stringify(entries),
+      [LIVE_KEY]: "d1", // live points at the oldest
+    };
+    for (const e of entries) {
+      initial[snapshotKey(e.id)] = "{}";
+      initial[revisionKey(e.id)] = "r";
+    }
+    const { client, store } = makeClient(initial);
+
+    const { pruned } = await recordAndGcDeployment(client, "d3", 3, 2);
+    expect(pruned).toEqual([]); // d1 would be evicted but it's live → kept
+    expect(store.has(snapshotKey("d1"))).toBe(true);
+    expect(JSON.parse(store.get(DEPLOYMENTS_KEY)!).map((e: { id: string }) => e.id)).toEqual([
+      "d1",
+      "d2",
+      "d3",
+    ]);
+  });
 });
 
 describe("sync-helpers", () => {

package/scripts/generate-invoke.test.ts

@@ -190,3 +190,81 @@ describe("generate-invoke.ts — output shape", () => {
     expect(generatedOutput).toContain("const result = await simulateCart(data);");
   });
 });
+
+describe("generate-invoke.ts — default --apps-dir resolution", () => {
+  // Regression for the published-tarball layout: @decocms/apps-vtex 7.x
+  // ships its sources under src/ (`"files": ["src"]`), so invoke.ts lives
+  // at node_modules/@decocms/apps-vtex/src/invoke.ts — NOT at the package
+  // root. The old default only probed the root, never resolved on a site
+  // with npm-installed packages, and forced sites to pass
+  // `--apps-dir node_modules/@decocms/apps-vtex/src` by hand (granadobr's
+  // migration workaround). The default must probe <pkg>/invoke.ts first,
+  // then <pkg>/src/invoke.ts.
+
+  function makeSite(layout: "root" | "src"): { siteDir: string; cleanup: () => void } {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gen-invoke-default-"));
+    const siteDir = path.join(tmp, "site");
+    const pkgDir = path.join(siteDir, "node_modules", "@decocms", "apps-vtex");
+    const appsDir = layout === "src" ? path.join(pkgDir, "src") : pkgDir;
+    fs.mkdirSync(path.join(appsDir, "actions"), { recursive: true });
+    fs.writeFileSync(path.join(appsDir, "invoke.ts"), FIXTURE_INVOKE_TS);
+    fs.writeFileSync(path.join(appsDir, "actions", "checkout.ts"), FIXTURE_ACTIONS_CHECKOUT_TS);
+    fs.writeFileSync(path.join(appsDir, "actions", "session.ts"), FIXTURE_ACTIONS_SESSION_TS);
+    fs.writeFileSync(path.join(appsDir, "types.ts"), FIXTURE_TYPES_TS);
+    return { siteDir, cleanup: () => fs.rmSync(tmp, { recursive: true, force: true }) };
+  }
+
+  it("resolves the published layout (node_modules/@decocms/apps-vtex/src/invoke.ts) without --apps-dir", () => {
+    const { siteDir, cleanup } = makeSite("src");
+    try {
+      const outFile = path.join(siteDir, "src", "server", "invoke.gen.ts");
+      const result = spawnSync("npx", ["tsx", GENERATOR, "--out-file", outFile], {
+        cwd: siteDir,
+        encoding: "utf8",
+      });
+      expect(result.status, result.stderr).toBe(0);
+      const generated = fs.readFileSync(outFile, "utf8");
+      // Relative `./actions/*` imports must still be rewritten to package
+      // subpaths — the exports map points them back into src/, so the src/
+      // nesting must not leak into the emitted specifiers.
+      expect(generated).toContain('from "@decocms/apps-vtex/actions/checkout"');
+      expect(generated).not.toContain("apps-vtex/src/");
+      expect(generated).toContain("export const vtexActions");
+    } finally {
+      cleanup();
+    }
+  }, 30_000);
+
+  it("still resolves invoke.ts at the package root (legacy dev-checkout layout) without --apps-dir", () => {
+    const { siteDir, cleanup } = makeSite("root");
+    try {
+      const outFile = path.join(siteDir, "src", "server", "invoke.gen.ts");
+      const result = spawnSync("npx", ["tsx", GENERATOR, "--out-file", outFile], {
+        cwd: siteDir,
+        encoding: "utf8",
+      });
+      expect(result.status, result.stderr).toBe(0);
+      const generated = fs.readFileSync(outFile, "utf8");
+      expect(generated).toContain('from "@decocms/apps-vtex/actions/checkout"');
+      expect(generated).toContain("export const vtexActions");
+    } finally {
+      cleanup();
+    }
+  }, 30_000);
+
+  it("fails with a clear error when @decocms/apps-vtex cannot be found", () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "gen-invoke-missing-"));
+    try {
+      const outFile = path.join(tmp, "src", "server", "invoke.gen.ts");
+      const result = spawnSync("npx", ["tsx", GENERATOR, "--out-file", outFile], {
+        cwd: tmp,
+        encoding: "utf8",
+      });
+      expect(result.status).not.toBe(0);
+      expect(result.stderr).toContain("Could not find @decocms/apps-vtex");
+      expect(result.stderr).toContain("--apps-dir");
+    } finally {
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  }, 30_000);
+});

package/scripts/generate-invoke.ts

@@ -55,17 +55,26 @@ function resolveAppsDir(): string {
   const explicit = arg("apps-dir", "");
   if (explicit) return path.resolve(cwd, explicit);
 
-  // Try common locations. Both point at the directory that contains
-  // invoke.ts directly at its root: the installed @decocms/apps-vtex
-  // package (no more vtex/ nesting — that directory IS the package root
-  // now), or a raw apps-start checkout's vtex/ subdirectory as a legacy
-  // fallback for anyone still developing against the pre-split monorepo.
-  const candidates = [
+  // Try common locations: the installed @decocms/apps-vtex package first,
+  // then a raw apps-start checkout's vtex/ subdirectory as a legacy fallback
+  // for anyone still developing against the pre-split monorepo.
+  //
+  // For each root, invoke.ts may sit directly at the root (legacy dev
+  // checkouts) or under src/ — the published @decocms/apps-vtex tarball
+  // ships its sources under src/ (`"files": ["src"]`, `"main":
+  // "./src/index.ts"`), so on any site with npm-installed 7.x packages the
+  // file lives at node_modules/@decocms/apps-vtex/src/invoke.ts. The src/
+  // nesting doesn't affect the emitted imports: relative `./actions/*`
+  // specifiers are rewritten to `@decocms/apps-vtex/actions/*`, which the
+  // package's exports map points back into src/.
+  const roots = [
     path.resolve(cwd, "node_modules/@decocms/apps-vtex"),
     path.resolve(cwd, "../apps-start/vtex"),
   ];
-  for (const c of candidates) {
-    if (fs.existsSync(path.join(c, "invoke.ts"))) return c;
+  for (const root of roots) {
+    for (const c of [root, path.join(root, "src")]) {
+      if (fs.existsSync(path.join(c, "invoke.ts"))) return c;
+    }
   }
   throw new Error("Could not find @decocms/apps-vtex. Use --apps-dir to specify its location.");
 }

package/scripts/generate-sections.test.ts

@@ -281,6 +281,75 @@ describe("generate-sections --registry", () => {
   }, 30_000);
 });
 
+describe("generate-sections neverDefer convention", () => {
+  // Regression: the scanner recognized `export const neverDefer = true` and
+  // emitted `neverDefer: true` on the section's sectionMeta entry, but the
+  // SectionMetaEntry interface the SAME file declares omitted the field —
+  // so every generated file containing a neverDefer section failed the
+  // site's typecheck (TS2353 excess property), and sites hand-patched the
+  // interface only to have the next regeneration wipe the patch (miess's
+  // .deco/sections.gen.ts carried exactly that TODO). The emitted interface
+  // must match SectionMetaEntry in @decocms/blocks/cms.
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-neverdefer-"));
+    sectionsDir = path.join(tmpDir, "sections");
+    outFile = path.join(tmpDir, "out", "sections.gen.ts");
+    fs.mkdirSync(sectionsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("declares neverDefer on the emitted SectionMetaEntry interface and the generated file typechecks + imports", () => {
+    // Mirrors miess's src/sections/Product/SearchResult.tsx.
+    fs.writeFileSync(
+      path.join(sectionsDir, "SearchResult.tsx"),
+      "export const neverDefer = true;\nexport default function SearchResult() { return null; }\n",
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    // Entry carries the convention…
+    expect(generated).toMatch(/"site\/sections\/SearchResult\.tsx": \{ neverDefer: true \}/);
+    // …and the interface declares the field (optional boolean, matching
+    // SectionMetaEntry in @decocms/blocks/cms/applySectionConventions.ts).
+    expect(generated).toContain("neverDefer?: boolean;");
+
+    // The actual failure mode was a TYPECHECK error (excess property on the
+    // Record<string, SectionMetaEntry> literal), which a runtime import
+    // through tsx/esbuild would never catch — so run tsc on the output.
+    const tscResult = cp.spawnSync(
+      "npx",
+      ["tsc", "--noEmit", "--strict", "--skipLibCheck", outFile],
+      { encoding: "utf8" },
+    );
+    expect(tscResult.status, tscResult.stdout + tscResult.stderr).toBe(0);
+
+    // And keep the importability guarantee from the earlier template
+    // regression: the file must load as valid TS/ESM with the expected
+    // exports.
+    const checkerFile = path.join(tmpDir, "check-import.mjs");
+    fs.writeFileSync(
+      checkerFile,
+      [
+        `const m = await import(${JSON.stringify(pathToFileURL(outFile).href)});`,
+        `if (m.sectionMeta?.["site/sections/SearchResult.tsx"]?.neverDefer !== true) {`,
+        `  throw new Error("neverDefer entry missing from sectionMeta");`,
+        `}`,
+      ].join("\n"),
+    );
+    const importResult = cp.spawnSync("npx", ["tsx", checkerFile], { encoding: "utf8" });
+    expect(importResult.status, importResult.stderr).toBe(0);
+  }, 60_000);
+});
+
 describe("generate-sections output hygiene (non-registry)", () => {
   let tmpDir: string;
   let sectionsDir: string;

package/scripts/generate-sections.ts

@@ -194,8 +194,14 @@ for (let i = 0; i < nonSyncFallbacks.length; i++) {
 lines.push("");
 
 // Metadata map
+// Keep this emitted interface in sync with SectionMetaEntry in
+// @decocms/blocks/cms (applySectionConventions.ts) — every convention the
+// scanner can set on an entry must be declared here, or the generated file
+// fails the site's typecheck (excess-property error) and sites end up
+// hand-patching a file that the next regeneration wipes.
 lines.push("export interface SectionMetaEntry {");
 lines.push("  eager?: boolean;");
+lines.push("  neverDefer?: boolean;");
 lines.push("  cache?: string;");
 lines.push("  layout?: boolean;");
 lines.push("  sync?: boolean;");

package/scripts/lib/cf-kv-rest.ts

@@ -2,17 +2,25 @@
  * Minimal Cloudflare KV REST API client for CI.
  *
  * CI has no Worker KV binding, so the fast-deploy sync/migrate scripts write to
- * KV over the REST API instead. Only the two operations the scripts need —
- * single-key GET and PUT — are implemented.
+ * KV over the REST API instead. Only the operations the scripts need — single-key
+ * GET/PUT/DELETE plus prefix LIST (for per-deployment GC) — are implemented.
  *
  * Auth/config via env (read by the scripts, passed to `createKvRestClient`):
- *   - CF_ACCOUNT_ID       Cloudflare account id
- *   - CF_KV_NAMESPACE_ID  target KV namespace id
- *   - CF_API_TOKEN        API token with "Workers KV Storage:Edit"
+ *   - CF_ACCOUNT_ID       Cloudflare account id      (or CLOUDFLARE_ACCOUNT_ID)
+ *   - CF_API_TOKEN        API token, "Workers KV Storage:Edit" (or CLOUDFLARE_API_TOKEN)
+ *   - CF_KV_NAMESPACE_ID  target KV namespace id     (or read from wrangler config)
+ *
+ * The `CLOUDFLARE_*` fallbacks + wrangler-config namespace lookup make the sync
+ * seamless inside Cloudflare Workers Builds, which injects `CLOUDFLARE_ACCOUNT_ID`
+ * / `CLOUDFLARE_API_TOKEN` (the default build token has Workers KV: Edit) and
+ * declares the namespace id in `wrangler.jsonc` — so no extra env wiring is
+ * needed there. Explicit `CF_*` still wins (e.g. the operator's k8s sync Job).
  *
  * `fetch` is injectable so the client is unit-testable without network.
  */
 
+import { kvNamespaceIdFromWrangler } from "./wrangler-config";
+
 export interface KvRestConfig {
   accountId: string;
   namespaceId: string;
@@ -26,22 +34,36 @@ export interface KvRestConfig {
 export interface KvRestClient {
   get(key: string): Promise<string | null>;
   put(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+  /** List key names, optionally filtered by prefix. Follows pagination. */
+  list(prefix?: string): Promise<string[]>;
 }
 
 const DEFAULT_BASE = "https://api.cloudflare.com/client/v4";
 
-/** Resolve the three required env vars or throw a clear error. */
-export function kvConfigFromEnv(env: NodeJS.ProcessEnv = process.env): Omit<KvRestConfig, "fetchImpl" | "baseUrl"> {
-  const accountId = env.CF_ACCOUNT_ID;
-  const namespaceId = env.CF_KV_NAMESPACE_ID;
-  const token = env.CF_API_TOKEN;
+/**
+ * Resolve the required KV config or throw a clear error. Accepts the `CF_*`
+ * names (explicit, win) or the `CLOUDFLARE_*` names CF Workers Builds injects.
+ * When `CF_KV_NAMESPACE_ID` is unset and `opts.wranglerDir` is given, the
+ * namespace id is read from that dir's wrangler config (`DECO_KV` binding).
+ */
+export function kvConfigFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  opts: { wranglerDir?: string } = {},
+): Omit<KvRestConfig, "fetchImpl" | "baseUrl"> {
+  const accountId = env.CF_ACCOUNT_ID || env.CLOUDFLARE_ACCOUNT_ID;
+  const token = env.CF_API_TOKEN || env.CLOUDFLARE_API_TOKEN;
+  let namespaceId = env.CF_KV_NAMESPACE_ID;
+  if (!namespaceId && opts.wranglerDir) {
+    namespaceId = kvNamespaceIdFromWrangler(opts.wranglerDir) ?? undefined;
+  }
   const missing = [
-    !accountId && "CF_ACCOUNT_ID",
-    !namespaceId && "CF_KV_NAMESPACE_ID",
-    !token && "CF_API_TOKEN",
+    !accountId && "CF_ACCOUNT_ID (or CLOUDFLARE_ACCOUNT_ID)",
+    !namespaceId && "CF_KV_NAMESPACE_ID (or a DECO_KV binding in wrangler config)",
+    !token && "CF_API_TOKEN (or CLOUDFLARE_API_TOKEN)",
   ].filter(Boolean);
   if (missing.length) {
-    throw new Error(`missing required env var(s): ${missing.join(", ")}`);
+    throw new Error(`missing required KV config: ${missing.join(", ")}`);
   }
   return { accountId: accountId!, namespaceId: namespaceId!, token: token! };
 }
@@ -74,5 +96,38 @@ export function createKvRestClient(config: KvRestConfig): KvRestClient {
         throw new Error(`KV PUT ${key} failed: ${res.status} ${await res.text()}`);
       }
     },
+
+    async delete(key) {
+      const res = await fetchImpl(`${root}/values/${encodeURIComponent(key)}`, {
+        method: "DELETE",
+        headers: authHeaders,
+      });
+      // 404 is fine — the key is already gone (idempotent delete).
+      if (!res.ok && res.status !== 404) {
+        throw new Error(`KV DELETE ${key} failed: ${res.status} ${await res.text()}`);
+      }
+    },
+
+    async list(prefix) {
+      const names: string[] = [];
+      let cursor: string | undefined;
+      do {
+        const qs = new URLSearchParams();
+        if (prefix) qs.set("prefix", prefix);
+        if (cursor) qs.set("cursor", cursor);
+        const suffix = qs.toString() ? `?${qs.toString()}` : "";
+        const res = await fetchImpl(`${root}/keys${suffix}`, { headers: authHeaders });
+        if (!res.ok) {
+          throw new Error(`KV LIST ${prefix ?? ""} failed: ${res.status} ${await res.text()}`);
+        }
+        const body = (await res.json()) as {
+          result?: Array<{ name: string }>;
+          result_info?: { cursor?: string };
+        };
+        for (const k of body.result ?? []) names.push(k.name);
+        cursor = body.result_info?.cursor || undefined;
+      } while (cursor);
+      return names;
+    },
   };
 }

package/scripts/lib/kv-snapshot.ts

@@ -1,24 +1,37 @@
 /**
  * Shared fast-deploy snapshot helpers for the CI scripts.
  *
- * Both `migrate-blocks-to-kv.ts` and `sync-blocks-to-kv.ts` write the same two
- * keys (`decofile:current` + `index:revision`). The revision is computed with
- * the SAME `computeRevision` the runtime uses (`src/cms/blockSource.ts`) so a
- * hydrating isolate computes a matching revision and the poller doesn't loop.
+ * Both `migrate-blocks-to-kv.ts` and `sync-blocks-to-kv.ts` write a snapshot
+ * keyed by DEPLOYMENT ID (`decofile:<id>` + `index:revision:<id>`) so every code
+ * deployment reads its own content. The revision is computed with the SAME
+ * `computeRevision` the runtime uses (`src/cms/blockSource.ts`) so a hydrating
+ * isolate computes a matching revision and the poller doesn't loop.
  */
 
-import { computeRevision, KV_KEYS } from "@decocms/blocks/cms";
+import {
+  computeRevision,
+  DEPLOYMENTS_KEY,
+  LIVE_KEY,
+  revisionKey,
+  snapshotKey,
+} from "@decocms/blocks/cms";
 import type { KvRestClient } from "./cf-kv-rest";
 
 export interface Snapshot {
-  /** Serialized decofile written to `decofile:current`. */
+  /** Serialized decofile written to `decofile:<id>`. */
   snapshot: string;
-  /** DJB2 revision written to `index:revision`. */
+  /** DJB2 revision written to `index:revision:<id>`. */
   revision: string;
   /** Block count, for logging. */
   count: number;
 }
 
+/** One entry in the `index:deployments` GC bookkeeping list. */
+export interface DeploymentEntry {
+  id: string;
+  ts: number;
+}
+
 export function buildSnapshot(blocks: Record<string, unknown>): Snapshot {
   return {
     snapshot: JSON.stringify(blocks),
@@ -27,25 +40,93 @@ export function buildSnapshot(blocks: Record<string, unknown>): Snapshot {
   };
 }
 
-/** Write the snapshot + revision to KV. Snapshot first, then revision, so a
- * poller never sees a new revision pointing at an old snapshot. */
-export async function writeSnapshotToKv(client: KvRestClient, snap: Snapshot): Promise<void> {
-  await client.put(KV_KEYS.SNAPSHOT, snap.snapshot);
-  await client.put(KV_KEYS.REVISION, snap.revision);
+/** Write the snapshot + revision for deployment `id`. Snapshot first, then
+ * revision, so a poller never sees a new revision pointing at an old snapshot. */
+export async function writeSnapshotToKv(
+  client: KvRestClient,
+  snap: Snapshot,
+  id: string,
+): Promise<void> {
+  await client.put(snapshotKey(id), snap.snapshot);
+  await client.put(revisionKey(id), snap.revision);
 }
 
-/** Read both keys back and confirm the revision matches what we wrote. */
+/** Read both keys for deployment `id` back and confirm the revision matches. */
 export async function verifySnapshotInKv(
   client: KvRestClient,
   expectedRevision: string,
+  id: string,
 ): Promise<{ ok: boolean; reason?: string }> {
   const [snapshot, revision] = await Promise.all([
-    client.get(KV_KEYS.SNAPSHOT),
-    client.get(KV_KEYS.REVISION),
+    client.get(snapshotKey(id)),
+    client.get(revisionKey(id)),
   ]);
-  if (snapshot === null) return { ok: false, reason: `${KV_KEYS.SNAPSHOT} missing` };
+  if (snapshot === null) return { ok: false, reason: `${snapshotKey(id)} missing` };
   if (revision !== expectedRevision) {
-    return { ok: false, reason: `${KV_KEYS.REVISION} is "${revision}", expected "${expectedRevision}"` };
+    return {
+      ok: false,
+      reason: `${revisionKey(id)} is "${revision}", expected "${expectedRevision}"`,
+    };
   }
   return { ok: true };
 }
+
+/** Point `index:live` at deployment `id` (post-activation, from the deploy step). */
+export async function setLiveDeployment(client: KvRestClient, id: string): Promise<void> {
+  await client.put(LIVE_KEY, id);
+}
+
+async function readDeployments(client: KvRestClient): Promise<DeploymentEntry[]> {
+  const raw = await client.get(DEPLOYMENTS_KEY);
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (Array.isArray(parsed)) {
+      return parsed.filter(
+        (e): e is DeploymentEntry =>
+          !!e && typeof e === "object" && typeof (e as DeploymentEntry).id === "string",
+      );
+    }
+  } catch {
+    // Corrupt bookkeeping key — start fresh rather than fail the sync.
+  }
+  return [];
+}
+
+/**
+ * Record deployment `id` in `index:deployments` (newest last, deduped) and GC
+ * snapshots beyond the last `retain`. The currently-live deployment
+ * (`index:live`) is never pruned even if it falls outside the window (protects
+ * a rollback to an older version). Returns the list of pruned ids.
+ */
+export async function recordAndGcDeployment(
+  client: KvRestClient,
+  id: string,
+  ts: number,
+  retain: number,
+): Promise<{ pruned: string[] }> {
+  const list = (await readDeployments(client)).filter((e) => e.id !== id);
+  list.push({ id, ts });
+
+  const pruned: string[] = [];
+  if (list.length > retain) {
+    const live = await client.get(LIVE_KEY);
+    const excess = list.slice(0, list.length - retain);
+    const recent = list.slice(list.length - retain);
+    const keptOld: DeploymentEntry[] = [];
+    for (const entry of excess) {
+      if (entry.id === live) {
+        keptOld.push(entry); // never GC the live deployment
+        continue;
+      }
+      await client.delete(snapshotKey(entry.id));
+      await client.delete(revisionKey(entry.id));
+      pruned.push(entry.id);
+    }
+    await client.put(DEPLOYMENTS_KEY, JSON.stringify([...keptOld, ...recent]));
+  } else {
+    await client.put(DEPLOYMENTS_KEY, JSON.stringify(list));
+  }
+
+  return { pruned };
+}

package/scripts/lib/wrangler-config.ts

@@ -0,0 +1,74 @@
+/**
+ * Read the KV namespace id for a binding straight out of a site's wrangler
+ * config, so the fast-deploy sync scripts need no `CF_KV_NAMESPACE_ID` env when
+ * run at the repo root (e.g. inside Cloudflare Workers Builds). Supports
+ * `wrangler.jsonc` / `wrangler.json` (preferred) and `wrangler.toml`.
+ *
+ * The namespace id is the one value CF Workers Builds does NOT inject into the
+ * build env — but it's declared right here in the worker config, next to the
+ * `DECO_KV` binding.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parseJsonc } from "./jsonc";
+
+const DEFAULT_BINDING = "DECO_KV";
+
+interface KvNamespaceEntry {
+  binding?: string;
+  id?: string;
+}
+
+/** Resolve the KV namespace id for `binding` from the wrangler config in `dir`,
+ * or `null` when no config / binding is found. */
+export function kvNamespaceIdFromWrangler(dir: string, binding = DEFAULT_BINDING): string | null {
+  for (const file of ["wrangler.jsonc", "wrangler.json"]) {
+    const p = path.join(dir, file);
+    if (fs.existsSync(p)) {
+      try {
+        const parsed = parseJsonc<{ kv_namespaces?: KvNamespaceEntry[] }>(
+          fs.readFileSync(p, "utf-8"),
+        );
+        const id = findKvId(parsed.kv_namespaces, binding);
+        if (id) return id;
+      } catch {
+        // Malformed config — fall through to the next candidate / return null.
+      }
+    }
+  }
+  const toml = path.join(dir, "wrangler.toml");
+  if (fs.existsSync(toml)) {
+    return kvNamespaceIdFromToml(fs.readFileSync(toml, "utf-8"), binding);
+  }
+  return null;
+}
+
+function findKvId(entries: KvNamespaceEntry[] | undefined, binding: string): string | null {
+  if (!Array.isArray(entries)) return null;
+  for (const e of entries) {
+    if (e && e.binding === binding && typeof e.id === "string" && e.id) return e.id;
+  }
+  return null;
+}
+
+/** Parse `[[kv_namespaces]]` table-array blocks from a `wrangler.toml` string
+ * and return the id whose `binding` matches. Exported for unit tests. */
+export function kvNamespaceIdFromToml(src: string, binding = DEFAULT_BINDING): string | null {
+  // Split on the [[kv_namespaces]] header; each following chunk is one block
+  // until the next table header ("\n[").
+  const blocks = src.split(/\[\[\s*kv_namespaces\s*\]\]/).slice(1);
+  for (const block of blocks) {
+    const body = block.split(/\n\s*\[/)[0];
+    if (matchTomlString(body, "binding") === binding) {
+      const id = matchTomlString(body, "id");
+      if (id) return id;
+    }
+  }
+  return null;
+}
+
+function matchTomlString(body: string, key: string): string | null {
+  const m = body.match(new RegExp(`(?:^|\\n)\\s*${key}\\s*=\\s*["']([^"']+)["']`));
+  return m ? m[1] : null;
+}

package/scripts/migrate/phase-scaffold.ts

@@ -159,7 +159,7 @@ export function scaffold(ctx: MigrationContext): void {
   }
 
   // Migration tooling policy pointer rule (D1–D5 + priorities).
-  // The canonical rule lives in decocms/deco-start; this is a tiny
+  // The canonical rule lives in decocms/blocks; this is a tiny
   // pointer that loads on every Cursor session in the migrated site
   // so agents working on the site know where the policy is and what
   // it means here. See MIGRATION_TOOLING_PLAN.md (Wave 12-H).

package/scripts/migrate/templates/cursor-rules.test.ts

@@ -14,12 +14,12 @@ describe("generateMigrationPolicyPointerRule", () => {
 		expect(body).toContain("`acme`");
 	});
 
-	it("links to the canonical rule and plan in decocms/deco-start", () => {
+	it("links to the canonical rule and plan in decocms/blocks", () => {
 		expect(body).toContain(
-			"https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc",
+			"https://github.com/decocms/blocks/blob/main/.cursor/rules/migration-tooling-policy.mdc",
 		);
 		expect(body).toContain(
-			"https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md",
+			"https://github.com/decocms/blocks/blob/main/MIGRATION_TOOLING_PLAN.md",
 		);
 	});
 
@@ -38,7 +38,7 @@ describe("generateMigrationPolicyPointerRule", () => {
 
 	it("does NOT restate the canonical rule body verbatim (pointer, not a copy)", () => {
 		// Length budget: pointer must stay short to discourage drift.
-		// The canonical rule in decocms/deco-start is ~110 lines / 4–5 KB;
+		// The canonical rule in decocms/blocks is ~110 lines / 4–5 KB;
 		// the pointer must be substantially smaller than a copy.
 		expect(body.length).toBeLessThan(3000);
 	});

package/scripts/migrate/templates/cursor-rules.ts

@@ -2,7 +2,7 @@
  * Cursor rule scaffolding for migrated sites.
  *
  * The canonical migration tooling policy (D1–D5, priorities, process)
- * lives in `decocms/deco-start`. We don't duplicate it into every site
+ * lives in `decocms/blocks`. We don't duplicate it into every site
  * — that would drift the moment the canonical changes. Instead the
  * migration scaffolds a tiny pointer rule, marked `alwaysApply: true`,
  * that loads on every agent session inside the migrated site and tells
@@ -35,11 +35,11 @@ alwaysApply: true
 ## Where to read
 
 - **Rule (always-applied) — full text:**
-  https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc
+  https://github.com/decocms/blocks/blob/main/.cursor/rules/migration-tooling-policy.mdc
 - **Plan (living tracker, decisions + waves):**
-  https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md
+  https://github.com/decocms/blocks/blob/main/MIGRATION_TOOLING_PLAN.md
 - **Migration skill (phase playbook):**
-  https://github.com/decocms/deco-start/blob/main/.agents/skills/deco-to-tanstack-migration/SKILL.md
+  https://github.com/decocms/blocks/blob/main/.agents/skills/deco-to-tanstack-migration/SKILL.md
 
 ## What you need to know in this site
 

package/scripts/migrate/templates/lockfile-check-yml.ts

@@ -7,7 +7,7 @@
  *
  * Lives in the site repo (per-site, not centralised) because per
  * D6.3 we are NOT scaffolding caller stubs that pull in
- * `decocms/deco-start@vN` reusable workflows. The check is small
+ * `decocms/blocks@vN` reusable workflows. The check is small
  * enough that copy-paste-per-site is the right tradeoff.
  *
  * Bun version pinning matches the `packageManager` field in the

package/scripts/migrate-blocks-to-kv.ts

@@ -4,19 +4,21 @@
  * bundled decofile so the worker can serve content KV-first.
  *
  * Reads `.deco/blocks/*.json` (the same merge the block generator does),
- * writes `decofile:current` + `index:revision` to the site's KV namespace via
- * the REST API, then reads both keys back to verify. Run ONCE per site before
+ * writes `decofile:<id>` + `index:revision:<id>` (keyed by deployment id) to
+ * the site's KV namespace via the REST API, then reads both keys back to
+ * verify. Run ONCE per site to seed the first deployment's content before
  * flipping it to KV-first (i.e. before adding the `DECO_KV` binding +
  * deploying the fast-deploy framework version).
  *
  * Usage (from the site root):
  *   # dry-run (default): reads blocks, prints what would be written, no writes
  *   CF_ACCOUNT_ID=... CF_KV_NAMESPACE_ID=... CF_API_TOKEN=... \
- *     npx -p @decocms/start deco-migrate-blocks-to-kv
+ *     npx -p @decocms/start deco-migrate-blocks-to-kv --deployment-id "$COMMIT_SHA"
  *   # apply:
- *   ... npx -p @decocms/start deco-migrate-blocks-to-kv --write
+ *   ... npx -p @decocms/start deco-migrate-blocks-to-kv --deployment-id "$COMMIT_SHA" --write
  *
  * Options:
+ *   --deployment-id <id> Deployment id (git commit sha) to key the write under (required to write)
  *   --blocks-dir <dir>   Input blocks dir (default: .deco/blocks)
  *   --write              Perform the KV writes (otherwise dry-run, exit 0)
  *   --help, -h           Show this help
@@ -24,7 +26,7 @@
  * Env:
  *   CF_ACCOUNT_ID, CF_KV_NAMESPACE_ID, CF_API_TOKEN  (required with --write)
  *
- * Exit codes: 0 ok / dry-run; 2 error (bad dir, missing env, verify failed)
+ * Exit codes: 0 ok / dry-run; 2 error (bad dir, missing env/args, verify failed)
  */
 
 import * as path from "node:path";
@@ -41,6 +43,7 @@ function parseArgs(argv: string[]) {
   return {
     help: has("--help") || has("-h"),
     write: has("--write"),
+    deploymentId: val("--deployment-id", ""),
     blocksDir: val("--blocks-dir", ".deco/blocks"),
   };
 }
@@ -49,12 +52,17 @@ async function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) {
     console.log(
-      "Usage: deco-migrate-blocks-to-kv [--blocks-dir .deco/blocks] [--write]\n" +
+      "Usage: deco-migrate-blocks-to-kv --deployment-id <sha> [--blocks-dir .deco/blocks] [--write]\n" +
         "Env: CF_ACCOUNT_ID, CF_KV_NAMESPACE_ID, CF_API_TOKEN",
     );
     process.exit(0);
   }
 
+  if (!opts.deploymentId && opts.write) {
+    console.error("error: --deployment-id <sha> is required to write to KV.");
+    process.exit(2);
+  }
+
   const blocksDir = path.resolve(process.cwd(), opts.blocksDir);
 
   let blocks: Record<string, unknown>;
@@ -79,15 +87,15 @@ async function main() {
 
   let client: ReturnType<typeof createKvRestClient>;
   try {
-    client = createKvRestClient(kvConfigFromEnv());
+    client = createKvRestClient(kvConfigFromEnv(process.env, { wranglerDir: process.cwd() }));
   } catch (e) {
     console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
     process.exit(2);
   }
 
   try {
-    await writeSnapshotToKv(client, snap);
-    const verify = await verifySnapshotInKv(client, snap.revision);
+    await writeSnapshotToKv(client, snap, opts.deploymentId);
+    const verify = await verifySnapshotInKv(client, snap.revision, opts.deploymentId);
     if (!verify.ok) {
       console.error(`error: KV verify failed — ${verify.reason}`);
       process.exit(2);
@@ -97,7 +105,7 @@ async function main() {
     process.exit(2);
   }
 
-  console.log(`\nwrote + verified decofile:current (rev ${snap.revision}) → KV.`);
+  console.log(`\nwrote + verified decofile:${opts.deploymentId} (rev ${snap.revision}) → KV.`);
   console.log("Next: add the DECO_KV binding in wrangler.toml and deploy the fast-deploy build.");
 }
 

package/scripts/sync-blocks-to-kv.ts

@@ -1,28 +1,39 @@
 #!/usr/bin/env tsx
 /**
- * CI fast-deploy content sync: push the site's current decofile to KV when
- * content changed, WITHOUT a worker redeploy.
+ * CI fast-deploy content sync: push the site's current decofile to KV under a
+ * DEPLOYMENT ID, WITHOUT a worker redeploy.
  *
- * Because the runtime swaps whole snapshots (not per-block), this always writes
- * the FULL current decofile (`decofile:current`) and bumps `index:revision`.
- * The default mode first checks whether any `.deco/blocks/*.json` changed since
- * a base ref — if nothing changed, it exits 0 without writing (the "content
- * unchanged → nothing to do" path). `--all` skips that check and always syncs
- * (use post-deploy for bootstrap/paranoia).
+ * Content is keyed per deployment (`decofile:<id>` + `index:revision:<id>`, id =
+ * git commit sha) so each running version reads its own snapshot. Two roles:
  *
- * After writing, it optionally purges the edge cache for the changed pages.
+ *   1. Build-time seed (code deploy): `--write --all --deployment-id <sha>`
+ *      writes this build's snapshot up-front, then appends `index:deployments`
+ *      and GCs old snapshots. The version reads its content the instant it goes
+ *      live — no window where new code sees old content.
+ *   2. Content-only fast deploy (operator): `--write --all --deployment-id <liveId>`
+ *      against the currently-live id — the live isolate's revision poll picks it
+ *      up in ~10s.
  *
- * Usage (in CI, on push to main):
+ * A separate, cheap `--set-live --deployment-id <sha>` run (post-activation, in
+ * the deploy step) flips the `index:live` pointer.
+ *
+ * The default (non-`--all`) mode first checks whether any `.deco/blocks/*.json`
+ * changed since a base ref — nothing changed ⇒ exit 0 without writing.
+ *
+ * Usage:
+ *   # build-time seed (whole snapshot for this commit):
  *   CF_ACCOUNT_ID=... CF_KV_NAMESPACE_ID=... CF_API_TOKEN=... \
- *     npx -p @decocms/start deco-sync-blocks-to-kv --write \
- *       --since "$GITHUB_BEFORE" --purge-url https://site.example --purge-token "$PURGE_TOKEN"
- *   # bootstrap (always write the whole snapshot):
- *   ... deco-sync-blocks-to-kv --write --all
+ *     npx -p @decocms/start deco-sync-blocks-to-kv --write --all --deployment-id "$COMMIT_SHA"
+ *   # post-deploy: flip the live pointer
+ *   ... deco-sync-blocks-to-kv --set-live --deployment-id "$COMMIT_SHA"
  *
  * Options:
+ *   --deployment-id <id>  Deployment id (git commit sha) to key the write under (required to write)
+ *   --set-live            Only write `index:live` = <id> (no blocks read); implies a write
  *   --all                 Always sync (skip the git-diff content check)
  *   --since <ref>         Base git ref for the diff (default: HEAD~1)
  *   --blocks-dir <dir>    Input blocks dir (default: .deco/blocks)
+ *   --retain <n>          Deployment snapshots to keep for GC (default: 10)
  *   --purge-url <origin>  Site origin to POST /_cache/purge after sync
  *   --purge-token <tok>   Purge bearer token (or PURGE_TOKEN env)
  *   --write               Perform writes (otherwise dry-run, exit 0)
@@ -30,16 +41,24 @@
  *
  * Env: CF_ACCOUNT_ID, CF_KV_NAMESPACE_ID, CF_API_TOKEN (required with --write)
  *
- * Exit codes: 0 ok / no-op / dry-run; 2 error (bad dir, missing env, verify failed)
+ * Exit codes: 0 ok / no-op / dry-run; 2 error (bad dir, missing env/args, verify failed)
  */
 
 import { execSync } from "node:child_process";
 import * as path from "node:path";
 import { createKvRestClient, kvConfigFromEnv } from "./lib/cf-kv-rest";
-import { buildSnapshot, verifySnapshotInKv, writeSnapshotToKv } from "./lib/kv-snapshot";
+import {
+  buildSnapshot,
+  recordAndGcDeployment,
+  setLiveDeployment,
+  verifySnapshotInKv,
+  writeSnapshotToKv,
+} from "./lib/kv-snapshot";
 import { readDecofileFromDir } from "./lib/read-decofile";
 import { changedBlockFiles, changedBlockKeys, purgePathsForChangedKeys } from "./lib/sync-helpers";
 
+const DEFAULT_RETAIN = 10;
+
 function parseArgs(argv: string[]) {
   const has = (f: string) => argv.includes(f);
   const val = (f: string, d: string) => {
@@ -50,6 +69,9 @@ function parseArgs(argv: string[]) {
     help: has("--help") || has("-h"),
     all: has("--all"),
     write: has("--write"),
+    setLive: has("--set-live"),
+    deploymentId: val("--deployment-id", ""),
+    retain: Number(val("--retain", String(DEFAULT_RETAIN))) || DEFAULT_RETAIN,
     since: val("--since", "HEAD~1"),
     blocksDir: val("--blocks-dir", ".deco/blocks"),
     purgeUrl: val("--purge-url", ""),
@@ -78,10 +100,37 @@ async function purgeCache(origin: string, token: string, paths: string[]): Promi
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
   if (opts.help) {
-    console.log("Usage: deco-sync-blocks-to-kv [--all] [--since <ref>] [--write] [--purge-url <origin>]");
+    console.log(
+      "Usage: deco-sync-blocks-to-kv --deployment-id <sha> [--all] [--set-live] [--write] [--retain 10] [--purge-url <origin>]",
+    );
     process.exit(0);
   }
 
+  // A deployment id is mandatory for any write — content is always keyed.
+  if (!opts.deploymentId && (opts.write || opts.setLive)) {
+    console.error("error: --deployment-id <sha> is required to write to KV.");
+    process.exit(2);
+  }
+
+  // --set-live: cheap pointer flip only, no blocks read.
+  if (opts.setLive) {
+    let client: ReturnType<typeof createKvRestClient>;
+    try {
+      client = createKvRestClient(kvConfigFromEnv(process.env, { wranglerDir: process.cwd() }));
+    } catch (e) {
+      console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(2);
+    }
+    try {
+      await setLiveDeployment(client, opts.deploymentId);
+    } catch (e) {
+      console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
+      process.exit(2);
+    }
+    console.log(`set index:live → ${opts.deploymentId}.`);
+    return;
+  }
+
   const blocksDir = path.resolve(process.cwd(), opts.blocksDir);
   const blocksDirRel = opts.blocksDir;
 
@@ -112,36 +161,38 @@ async function main() {
   }
 
   const snap = buildSnapshot(blocks);
-  const purgePaths = opts.all
-    ? ["/"]
-    : purgePathsForChangedKeys(blocks, changedKeys);
-  console.log(`decofile: ${snap.count} blocks, revision ${snap.revision}`);
+  const purgePaths = opts.all ? ["/"] : purgePathsForChangedKeys(blocks, changedKeys);
+  console.log(`decofile: ${snap.count} blocks, revision ${snap.revision} → deployment ${opts.deploymentId}`);
 
   if (!opts.write) {
-    console.log(`\nDry-run only. Would write snapshot + revision and purge: ${purgePaths.join(", ")}`);
+    console.log(`\nDry-run only. Would write decofile:${opts.deploymentId} + revision, GC to ${opts.retain}, purge: ${purgePaths.join(", ")}`);
     process.exit(0);
   }
 
   let client: ReturnType<typeof createKvRestClient>;
   try {
-    client = createKvRestClient(kvConfigFromEnv());
+    client = createKvRestClient(kvConfigFromEnv(process.env, { wranglerDir: process.cwd() }));
   } catch (e) {
     console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
     process.exit(2);
   }
 
   try {
-    await writeSnapshotToKv(client, snap);
-    const verify = await verifySnapshotInKv(client, snap.revision);
+    await writeSnapshotToKv(client, snap, opts.deploymentId);
+    const verify = await verifySnapshotInKv(client, snap.revision, opts.deploymentId);
     if (!verify.ok) {
       console.error(`error: KV verify failed — ${verify.reason}`);
       process.exit(2);
     }
+    const { pruned } = await recordAndGcDeployment(client, opts.deploymentId, Date.now(), opts.retain);
+    if (pruned.length) {
+      console.log(`GC: pruned ${pruned.length} old snapshot(s): ${pruned.join(", ")}`);
+    }
   } catch (e) {
     console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
     process.exit(2);
   }
-  console.log(`synced decofile:current (rev ${snap.revision}) → KV.`);
+  console.log(`synced decofile:${opts.deploymentId} (rev ${snap.revision}) → KV.`);
 
   if (opts.purgeUrl && opts.purgeToken) {
     await purgeCache(opts.purgeUrl, opts.purgeToken, purgePaths);