@decocms/blocks-cli 8.0.0 → 8.1.0-next.0

package/scripts/generate-workspaces.test.ts

@@ -0,0 +1,179 @@
+// @vitest-environment node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildPlan, parseCliOptions } from "./generate";
+
+const tsx = createRequire(import.meta.url).resolve("tsx/cli");
+const script = fileURLToPath(new URL("./generate.ts", import.meta.url));
+
+describe("generation in a workspace with hoisted dependencies", () => {
+  let workspace: string;
+  let site: string;
+
+  function write(root: string, relative: string, content: string): string {
+    const file = path.join(root, relative);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    return file;
+  }
+
+  function install(root: string, name: string, version = "7.48.4"): string {
+    const dir = path.join(root, "node_modules", name);
+    // Published packages need not export their root or package.json.
+    write(
+      dir,
+      "package.json",
+      JSON.stringify({ name, version, exports: { "./mod": "./src/mod.ts" } }),
+    );
+    return dir;
+  }
+
+  function plans(args: string[] = []) {
+    return Object.fromEntries(buildPlan(site, parseCliOptions(args)).map((p) => [p.name, p]));
+  }
+
+  function run(args: string[]) {
+    // Exercise --root too: the caller's cwd is the workspace, not the site.
+    const result = spawnSync(process.execPath, [tsx, script, "--root", "apps/website", ...args], {
+      cwd: workspace,
+      encoding: "utf8",
+      timeout: 30_000,
+    });
+    expect(result.status, result.stdout + result.stderr).toBe(0);
+    return result.stdout;
+  }
+
+  beforeEach(() => {
+    workspace = fs.mkdtempSync(path.join(os.tmpdir(), "generate-workspaces-"));
+    site = path.join(workspace, "apps", "website");
+    write(workspace, "package.json", JSON.stringify({ private: true, workspaces: ["apps/*"] }));
+    write(site, "package.json", JSON.stringify({ name: "website", type: "module" }));
+    write(site, "tsconfig.json", JSON.stringify({ compilerOptions: { jsx: "react-jsx" } }));
+    write(site, ".deco/blocks/Home.json", JSON.stringify({ name: "Home", path: "/" }));
+    write(site, "src/sections/Hero.tsx", "export default function Hero() { return null; }\n");
+    install(workspace, "@decocms/blocks");
+  });
+
+  afterEach(() => {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  });
+
+  it("detects hoisted Next.js and enables its manifest and section registry", () => {
+    install(workspace, "@decocms/nextjs");
+    const plan = plans();
+    expect(plan.manifest.enabled).toBe(true);
+    expect(plan.blocks.enabled).toBe(false);
+    expect(plan.sections.args).toContain("--registry");
+  });
+
+  it.each([
+    "nextjs",
+    "tanstack",
+  ])("uses the site's %s binding when siblings hoist both frameworks", (framework) => {
+    write(
+      site,
+      "package.json",
+      JSON.stringify({
+        name: "website",
+        dependencies: { [`@decocms/${framework}`]: "7.48.4" },
+      }),
+    );
+    install(workspace, "@decocms/nextjs");
+    install(workspace, "@decocms/tanstack");
+    install(workspace, "@tanstack/react-start");
+    const app = install(workspace, "@decocms/apps-vtex");
+    write(app, "src/invoke.ts", "export const invoke = {} as const;\n");
+    const plan = plans();
+    expect(plan.manifest.enabled).toBe(framework === "nextjs");
+    expect(plan.sections.args.includes("--registry")).toBe(framework === "nextjs");
+    expect(plan.blocks.enabled).toBe(framework === "tanstack");
+    expect(plan.invoke.enabled).toBe(framework === "tanstack");
+  });
+
+  it.each([
+    false,
+    true,
+  ])("generates invoke from hoisted packages (explicit apps directory: %s)", (explicit) => {
+    install(workspace, "@tanstack/react-start", "1.166.8");
+    const app = install(workspace, "@decocms/apps-vtex");
+    write(
+      app,
+      "src/invoke.ts",
+      `
+import { createInvokeFn } from "@decocms/tanstack/sdk/createInvoke";
+import { getOrCreateCart } from "./actions/checkout";
+import type { OrderForm } from "./types";
+export const invoke = {
+  vtex: { actions: {
+    getOrCreateCart: createInvokeFn(
+      (data: { orderFormId?: string }) => getOrCreateCart(data),
+    ) as unknown as (ctx: { data: { orderFormId?: string } }) => Promise<OrderForm>,
+  } },
+} as const;
+`,
+    );
+    expect(plans().invoke.enabled).toBe(true);
+    run([
+      "--only",
+      "invoke",
+      ...(explicit ? ["--apps-dir", "../../node_modules/@decocms/apps-vtex"] : []),
+    ]);
+    const output = fs.readFileSync(path.join(site, "src/server/invoke.gen.ts"), "utf8");
+    expect(output).toContain("getOrCreateCart");
+    expect(output).toContain("@decocms/apps-vtex/actions/checkout");
+  });
+
+  it("does not use a parent invoke contract when a local package shadows it", () => {
+    install(workspace, "@tanstack/react-start");
+    const hoisted = install(workspace, "@decocms/apps-vtex");
+    write(hoisted, "src/invoke.ts", "export const invoke = {};\n");
+    install(site, "@decocms/apps-vtex");
+    expect(plans().invoke.enabled).toBe(false);
+  });
+
+  it("fingerprints hoisted app sources and respects local package precedence and --skip-apps", () => {
+    const hoisted = install(workspace, "@decocms/apps-vtex");
+    const parentSource = write(hoisted, "src/loaders/product.ts", "export default () => [];\n");
+    const inputPaths = (args: string[] = []) =>
+      plans(args)
+        .schema.inputs()
+        .map(([rel]) => path.resolve(site, rel));
+    expect(inputPaths()).toContain(parentSource);
+    expect(inputPaths(["--skip-apps"])).not.toContain(parentSource);
+
+    const local = install(site, "@decocms/apps-vtex", "7.48.5");
+    const localSource = write(local, "src/loaders/local.ts", "export default () => [];\n");
+    expect(inputPaths()).toContain(localSource);
+    expect(inputPaths()).not.toContain(parentSource);
+  });
+
+  it("invalidates cached generation when a hoisted package version changes", () => {
+    run(["--only", "loaders"]);
+    const digests = JSON.parse(
+      fs.readFileSync(path.join(site, ".deco/generate.digests.json"), "utf8"),
+    );
+    expect(digests.generators.loaders.deco).toContain("@decocms/blocks@7.48.4");
+    expect(run(["--only", "loaders", "--dry-run"])).toContain("loaders: skip — cached");
+
+    install(workspace, "@decocms/blocks", "7.48.5");
+    expect(run(["--only", "loaders", "--dry-run"])).toContain("loaders: would run");
+  });
+
+  it("fingerprints the nearest package version, ignoring a shadowed parent's updates", () => {
+    install(site, "@decocms/blocks", "7.48.6");
+    run(["--only", "loaders"]);
+    const digests = JSON.parse(
+      fs.readFileSync(path.join(site, ".deco/generate.digests.json"), "utf8"),
+    );
+    expect(digests.generators.loaders.deco).toContain("@decocms/blocks@7.48.6");
+    expect(digests.generators.loaders.deco).not.toContain("@decocms/blocks@7.48.4");
+
+    install(workspace, "@decocms/blocks", "7.48.7");
+    expect(run(["--only", "loaders", "--dry-run"])).toContain("loaders: skip — cached");
+  });
+});

package/scripts/generate.test.ts

@@ -242,8 +242,7 @@ describe("buildPlan --platform eitri", () => {
         expect(byName[name].disabledReason).toBe("not used by --platform eitri");
       }
 
-      // schema is asked to bake composeMeta's framework block types in.
-      expect(byName.schema.args).toContain("--compose");
+      // schema tags the composed meta with the eitri framework name.
       const fwIdx = byName.schema.args.indexOf("--framework");
       expect(byName.schema.args[fwIdx + 1]).toBe("eitri");
     } finally {

package/scripts/generate.ts

@@ -88,7 +88,7 @@
  *   - args:   the exact argv forwarded to that generator,
  *   - cli:    blocks-cli's own package version,
  *   - deco:   the resolved versions of every @decocms/* package in the
- *             site's node_modules (a lockstep bump invalidates everything),
+ *             site's module search path (a lockstep bump invalidates everything),
  *   - inputs: sha256 over the sorted (relPath, contentSha256) pairs of the
  *             generator's input set — CONTENT hashes, machine-independent.
  * Because the record is content-addressed, a FRESH CLONE with unchanged
@@ -127,6 +127,8 @@ import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+import { listScopedPackages, resolvePackageDirectory } from "./lib/installedPackages";
+import { resolveInvokeSource } from "./lib/invokeSource";
 
 // Bump when the digests file format or digest recipe changes — recorded in
 // every digest record so old files self-bust instead of mis-validating.
@@ -463,16 +465,9 @@ function readPkgVersion(pkgDir: string): string | null {
 
 function decoPackageVersions(cwd: string): Record<string, string> {
   const versions: Record<string, string> = {};
-  const scopeDir = path.join(cwd, "node_modules", "@decocms");
-  let names: string[];
-  try {
-    names = fs.readdirSync(scopeDir);
-  } catch {
-    return versions;
-  }
-  for (const name of names.sort()) {
-    const v = readPkgVersion(path.join(scopeDir, name));
-    if (v) versions[`@decocms/${name}`] = v;
+  for (const [name, dir] of listScopedPackages(cwd, "@decocms")) {
+    const v = readPkgVersion(dir);
+    if (v) versions[name] = v;
   }
   return versions;
 }
@@ -485,7 +480,25 @@ function ownVersion(): string {
 }
 
 function hasPackage(cwd: string, name: string): boolean {
-  return fs.existsSync(path.join(cwd, "node_modules", ...name.split("/"), "package.json"));
+  const dir = resolvePackageDirectory(cwd, name);
+  return dir !== null && fs.existsSync(path.join(dir, "package.json"));
+}
+
+function isNextjsSite(cwd: string): boolean {
+  // Sibling sites can hoist both bindings. Prefer this site's declaration so
+  // a TanStack workspace does not adopt a sibling's Next.js generation mode.
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const dependencies = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+      ...pkg.peerDependencies,
+      ...pkg.optionalDependencies,
+    };
+    if ("@decocms/nextjs" in dependencies) return hasPackage(cwd, "@decocms/nextjs");
+    if ("@decocms/tanstack" in dependencies) return false;
+  } catch {}
+  return hasPackage(cwd, "@decocms/nextjs");
 }
 
 // ---------------------------------------------------------------------------
@@ -508,20 +521,6 @@ export interface GeneratorPlan {
   outputs: string[];
 }
 
-/** Resolve generate-invoke's apps dir exactly like the generator does
- * (minus the legacy ../apps-start/vtex fallback, which is dev-checkout-only). */
-function resolveInvokeSource(cwd: string, appsDir: string | null): string | null {
-  const roots = appsDir
-    ? [path.resolve(cwd, appsDir)]
-    : [path.resolve(cwd, "node_modules/@decocms/apps-vtex")];
-  for (const root of roots) {
-    for (const c of [root, path.join(root, "src")]) {
-      if (fs.existsSync(path.join(c, "invoke.ts"))) return path.join(c, "invoke.ts");
-    }
-  }
-  return null;
-}
-
 export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
   const scriptsDir = path.dirname(fileURLToPath(import.meta.url));
   const blocksDirAbs = path.resolve(cwd, opts.blocksDir);
@@ -531,7 +530,7 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
 
   const blocksDirExists = fs.existsSync(blocksDirAbs);
   const sectionsDirExists = fs.existsSync(sectionsDirAbs);
-  const isNext = hasPackage(cwd, "@decocms/nextjs");
+  const isNext = isNextjsSite(cwd);
   const hasTanstackStart = hasPackage(cwd, "@tanstack/react-start");
 
   const blocksGenJson = path.join(".deco", "blocks.gen.json");
@@ -635,10 +634,12 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
       args: opts.appsDir ? ["--apps-dir", opts.appsDir] : [],
       stage: 1,
       ...enabledIf(
-        invokeSource !== null && hasTanstackStart,
+        invokeSource !== null && hasTanstackStart && !isNext,
         invokeSource === null
           ? "no apps invoke.ts found (@decocms/apps-vtex not installed and no --apps-dir)"
-          : "@tanstack/react-start not installed (invoke.gen.ts targets TanStack Start)",
+          : isNext
+            ? "@decocms/nextjs site (invoke.gen.ts targets TanStack Start)"
+            : "@tanstack/react-start not installed (invoke.gen.ts targets TanStack Start)",
       ),
       // invoke.ts is the file the generator parses; the surrounding package's
       // action/type sources are fingerprinted via the @decocms/* version set
@@ -658,15 +659,15 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
         ...(opts.namespace ? ["--namespace", opts.namespace] : []),
         ...(opts.platform ? ["--platform", opts.platform] : []),
         ...(opts.skipApps ? ["--skip-apps"] : []),
-        // Always bake composeMeta's framework block types (Page, matchers,
-        // __SECTION_REF__, Resolvable) into meta.gen.json so the file is
-        // SELF-CONTAINED for every consumer that reads it straight from disk —
-        // the FS-based Studio and the Eitri stack, but also anyone diffing the
-        // committed artifact against /live/_meta. The tanstack runtime re-runs
-        // composeMeta on load, which is now idempotent (it returns an
-        // already-composed meta unchanged — see composeMeta's `framework`
-        // sentinel), so this is a no-op there rather than a double-compose.
-        "--compose",
+        // generate-schema always bakes composeMeta's framework block types
+        // (Page, matchers, __SECTION_REF__, Resolvable) into meta.gen.json, so
+        // the file is SELF-CONTAINED for every consumer that reads it straight
+        // from disk — the FS-based Studio and the Eitri stack, but also anyone
+        // diffing the committed artifact against /live/_meta. The tanstack
+        // runtime re-runs composeMeta on load, which is idempotent (it returns
+        // an already-composed meta unchanged — see composeMeta's `framework`
+        // sentinel), so that's a no-op rather than a double-compose.
+        //
         // Non-React stacks (Eitri) tag the composed meta with their own
         // framework name; everyone else gets composeMeta's default
         // ("tanstack-start").
@@ -692,13 +693,10 @@ export function buildPlan(cwd: string, opts: CliOptions): GeneratorPlan[] {
           ),
         ];
         if (!opts.skipApps) {
-          const scopeDir = path.join(cwd, "node_modules", "@decocms");
-          let names: string[] = [];
-          try {
-            names = fs.readdirSync(scopeDir).filter((n) => n.startsWith("apps-"));
-          } catch {}
-          for (const name of names.sort()) {
-            entries.push(...walkTree(cwd, path.join(scopeDir, name, "src"), [".ts", ".tsx"]));
+          for (const [name, dir] of listScopedPackages(cwd, "@decocms")) {
+            if (name.startsWith("@decocms/apps-")) {
+              entries.push(...walkTree(cwd, path.join(dir, "src"), [".ts", ".tsx"]));
+            }
           }
         }
         return sortEntries(entries);

package/scripts/lib/blocks-dedupe.test.ts

@@ -83,7 +83,7 @@ describe("pickWinner", () => {
   });
 
   it("prefers higher decode-pass count when path-status matches", () => {
-    // The lebiscuit reproduction case: a stale single-encoded leftover with a
+    // A production reproduction case: a stale single-encoded leftover with a
     // newer mtime and larger size loses to the bot's double-encoded fresh file.
     const stale = cand({
       file: "pages-Home%20-%20LB-618509.json",

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

@@ -3,7 +3,9 @@
  *
  * CI has no Worker KV binding, so the fast-deploy sync/migrate scripts write to
  * 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.
+ * GET/PUT/DELETE, prefix LIST (for per-deployment GC), and BULK put/delete (for
+ * the per-path redirect keys, which number in the tens of thousands) — are
+ * implemented.
  *
  * Auth/config via env (read by the scripts, passed to `createKvRestClient`):
  *   - CF_ACCOUNT_ID       Cloudflare account id      (or CLOUDFLARE_ACCOUNT_ID)
@@ -37,6 +39,21 @@ export interface KvRestClient {
   delete(key: string): Promise<void>;
   /** List key names, optionally filtered by prefix. Follows pagination. */
   list(prefix?: string): Promise<string[]>;
+  /** Write many keys. Chunked to the API's per-request ceiling. A site can have
+   *  tens of thousands of redirects; one PUT each would be as many round trips. */
+  putMany(entries: Array<{ key: string; value: string }>): Promise<void>;
+  /** Delete many keys. Same chunking. */
+  deleteMany(keys: string[]): Promise<void>;
+}
+
+/** Cloudflare's per-request ceiling for the bulk KV endpoints. */
+const BULK_CHUNK = 10_000;
+
+/** Split `items` into chunks of at most `size`. */
+function chunk<T>(items: T[], size: number): T[][] {
+  const out: T[][] = [];
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size));
+  return out;
 }
 
 const DEFAULT_BASE = "https://api.cloudflare.com/client/v4";
@@ -108,6 +125,37 @@ export function createKvRestClient(config: KvRestConfig): KvRestClient {
       }
     },
 
+    async putMany(entries) {
+      for (const batch of chunk(entries, BULK_CHUNK)) {
+        const res = await fetchImpl(`${root}/bulk`, {
+          method: "PUT",
+          headers: { ...authHeaders, "Content-Type": "application/json" },
+          body: JSON.stringify(batch),
+        });
+        if (!res.ok) {
+          throw new Error(
+            `KV bulk PUT (${batch.length} keys) failed: ${res.status} ${await res.text()}`,
+          );
+        }
+      }
+    },
+
+    async deleteMany(keys) {
+      for (const batch of chunk(keys, BULK_CHUNK)) {
+        const res = await fetchImpl(`${root}/bulk`, {
+          method: "DELETE",
+          headers: { ...authHeaders, "Content-Type": "application/json" },
+          body: JSON.stringify(batch),
+        });
+        // 404 is fine — the keys are already gone (idempotent delete).
+        if (!res.ok && res.status !== 404) {
+          throw new Error(
+            `KV bulk DELETE (${batch.length} keys) failed: ${res.status} ${await res.text()}`,
+          );
+        }
+      }
+    },
+
     async list(prefix) {
       const names: string[] = [];
       let cursor: string | undefined;

package/scripts/lib/installedPackages.ts

@@ -0,0 +1,42 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/** Search from the consuming site, including ancestor node_modules directories
+ * used by workspace hoisting. Directory lookup also works with source-only
+ * checkouts and packages whose exports expose neither the root nor package.json. */
+function moduleDirectories(cwd: string, name: string): string[] {
+  return createRequire(path.resolve(cwd, "package.json")).resolve.paths(name) ?? [];
+}
+
+export function resolvePackageDirectory(cwd: string, name: string): string | null {
+  for (const modules of moduleDirectories(cwd, name)) {
+    const dir = path.join(modules, name);
+    if (fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) return dir;
+  }
+  return null;
+}
+
+/** Installed packages in a scope, keyed by full package name. The nearest
+ * copy wins, matching resolvePackageDirectory even with mixed local/hoisted
+ * installs; shadowed ancestor copies must not enter codegen fingerprints. */
+export function listScopedPackages(cwd: string, scope: string): Map<string, string> {
+  const packages = new Map<string, string>();
+  for (const modules of moduleDirectories(cwd, `${scope}/_`)) {
+    const scopeDir = path.join(modules, scope);
+    let names: string[];
+    try {
+      names = fs.readdirSync(scopeDir);
+    } catch {
+      continue;
+    }
+    for (const name of names) {
+      const fullName = `${scope}/${name}`;
+      const dir = path.join(scopeDir, name);
+      if (!packages.has(fullName) && fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory()) {
+        packages.set(fullName, dir);
+      }
+    }
+  }
+  return new Map([...packages].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}

package/scripts/lib/invokeSource.ts

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolvePackageDirectory } from "./installedPackages";
+
+/** Both the orchestrator and its child must parse the same invoke contract.
+ * Resolve the package first so a local copy without invoke.ts cannot silently
+ * pick up a different contract from a shadowed ancestor package. */
+export function resolveInvokeSource(cwd: string, appsDir: string | null): string | null {
+  const root = appsDir
+    ? path.resolve(cwd, appsDir)
+    : resolvePackageDirectory(cwd, "@decocms/apps-vtex");
+  if (!root) return null;
+  for (const dir of [root, path.join(root, "src")]) {
+    const file = path.join(dir, "invoke.ts");
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}

package/scripts/lib/kv-snapshot.ts

@@ -12,9 +12,12 @@ import {
   computeRevision,
   DEPLOYMENTS_KEY,
   LIVE_KEY,
+  redirectKey,
+  redirectPrefix,
   revisionKey,
   snapshotKey,
 } from "@decocms/blocks/cms";
+import type { ExactRedirect } from "@decocms/blocks/sdk/redirects";
 import type { KvRestClient } from "./cf-kv-rest";
 
 export interface Snapshot {
@@ -71,6 +74,42 @@ export async function verifySnapshotInKv(
   return { ok: true };
 }
 
+/**
+ * Reconcile deployment `id`'s exact redirects in KV: write the ones that are
+ * new or changed, delete the ones that no longer exist.
+ *
+ * KV has no "replace everything under this prefix" operation, so the desired
+ * set is diffed against what is actually stored. The source of truth for
+ * "what's there now" is a prefix LIST rather than a manifest key — a manifest
+ * is one more thing that can drift out of sync with reality, and the list is
+ * free enough at build time.
+ *
+ * Updates are not detected by value: re-PUTting an unchanged key is one bulk
+ * write, while reading every current value back to compare would be one GET per
+ * key. So every desired rule is written, and only deletions need the diff.
+ */
+export async function syncRedirectsToKv(
+  client: KvRestClient,
+  redirects: ExactRedirect[],
+  id: string,
+): Promise<{ written: number; deleted: number }> {
+  const desired = new Map(
+    redirects.map((r) => [redirectKey(id, r.path), JSON.stringify({ to: r.to, status: r.status })]),
+  );
+
+  const existing = await client.list(redirectPrefix(id));
+  const stale = existing.filter((key) => !desired.has(key));
+
+  if (desired.size > 0) {
+    await client.putMany([...desired].map(([key, value]) => ({ key, value })));
+  }
+  if (stale.length > 0) {
+    await client.deleteMany(stale);
+  }
+
+  return { written: desired.size, deleted: stale.length };
+}
+
 /** 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);
@@ -121,6 +160,11 @@ export async function recordAndGcDeployment(
       }
       await client.delete(snapshotKey(entry.id));
       await client.delete(revisionKey(entry.id));
+      // The per-path redirect keys are keyed by deployment too, so they are
+      // part of this snapshot and must go with it — otherwise every deploy
+      // leaks tens of thousands of orphans into the namespace forever.
+      const staleRedirects = await client.list(redirectPrefix(entry.id));
+      if (staleRedirects.length > 0) await client.deleteMany(staleRedirects);
       pruned.push(entry.id);
     }
     await client.put(DEPLOYMENTS_KEY, JSON.stringify([...keptOld, ...recent]));

package/scripts/lib/read-decofile.ts

@@ -6,7 +6,7 @@
  * the fast-deploy CI scripts (`migrate-blocks-to-kv.ts`, `sync-blocks-to-kv.ts`)
  * produce a decofile byte-identical to the bundled `blocks.gen` snapshot.
  *
- * Reuses `scripts/lib/blocks-dedupe.ts`.
+ * Reuses `scripts/lib/blocks-dedupe.ts` and `scripts/lib/csv-redirects.ts`.
  */
 
 import * as fs from "node:fs";
@@ -18,6 +18,7 @@ import {
   decodeBlockNameWithPasses,
   mergeCandidates,
 } from "./blocks-dedupe";
+import { buildCsvRedirectBlocks } from "./csv-redirects";
 
 export interface ReadDecofileResult {
   /** Decoded block key → parsed block JSON. */
@@ -66,5 +67,15 @@ export function readDecofileFromDir(blocksDir: string, opts: { silent?: boolean
   for (const [key, candidate] of Object.entries(winners)) {
     blocks[key] = candidate.parsed;
   }
-  return { blocks, collisions };
+
+  // Synthetic `__csv_redirects__*` blocks, exactly as `generate-blocks` builds
+  // them. Without this the KV snapshot is NOT byte-identical to `blocks.gen`:
+  // a site whose redirects come from a CSV would lose every one of them the
+  // moment the bundled snapshot stops being the fallback (the fastDeploy stub
+  // makes KV the only source), turning migration 301s into silent 404s.
+  // Same precedence as the generator — a curated CMS redirect wins over CSV.
+  const csvBlocks = buildCsvRedirectBlocks(blocks, { blocksDir, silent: opts.silent });
+  const merged = Object.keys(csvBlocks).length ? { ...csvBlocks, ...blocks } : blocks;
+
+  return { blocks: merged, collisions };
 }

package/scripts/lib/upgrade-6-to-7.ts

@@ -7,7 +7,7 @@
  * only the package dependency that needs to move.
  *
  * Mapping derived by hand against a real production site
- * (montecarlo-tanstack) — see the issue for the full worked table. Symbol
+ * (a production VTEX storefront) — see the issue for the full worked table. Symbol
  * renames and relocations mean a pure specifier-string rewrite is not
  * enough for every case; those are called out below.
  */

package/scripts/lib/wrangler-config.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { setKvNamespaceIdInJsonc } from "./wrangler-config";
+
+describe("setKvNamespaceIdInJsonc", () => {
+  // The scaffolded wrangler.jsonc carries the comments explaining why each
+  // binding exists; a parse-and-restringify round trip would drop every one.
+  const WRANGLER = `{
+  "name": "acme",
+  "kv_namespaces": [
+    // Fast Deploy content store.
+    { "binding": "DECO_KV", "id": "" },
+    // A/B testing assignments.
+    { "binding": "SITES_KV", "id": "" }
+  ],
+  "vars": { "DECO_FAST_DEPLOY": "1" }
+}`;
+
+  it("writes the id into the DECO_KV entry and leaves comments intact", () => {
+    const out = setKvNamespaceIdInJsonc(WRANGLER, "ns-123");
+    expect(out).toContain('{ "binding": "DECO_KV", "id": "ns-123" }');
+    expect(out).toContain("// Fast Deploy content store.");
+    expect(out).toContain("// A/B testing assignments.");
+  });
+
+  it("does not touch a different binding's id", () => {
+    const out = setKvNamespaceIdInJsonc(WRANGLER, "ns-123");
+    expect(out).toContain('{ "binding": "SITES_KV", "id": "" }');
+  });
+
+  it("targets the requested binding", () => {
+    const out = setKvNamespaceIdInJsonc(WRANGLER, "ab-9", "SITES_KV");
+    expect(out).toContain('{ "binding": "SITES_KV", "id": "ab-9" }');
+    expect(out).toContain('{ "binding": "DECO_KV", "id": "" }');
+  });
+
+  it("handles reversed field order and an entry with no id yet", () => {
+    const src = '{ "kv_namespaces": [{ "id": "old", "binding": "DECO_KV" }] }';
+    expect(setKvNamespaceIdInJsonc(src, "new")).toContain('"id": "new"');
+    const noId = '{ "kv_namespaces": [{ "binding": "DECO_KV" }] }';
+    expect(setKvNamespaceIdInJsonc(noId, "new")).toContain('"id": "new"');
+  });
+
+  it("returns the source unchanged when the binding is absent", () => {
+    // Not an error: the builder re-forces the id from CF_KV_NAMESPACE_ID on
+    // every build, so a repo without the binding is just nothing to personalize.
+    const src = '{ "kv_namespaces": [{ "binding": "SITES_KV", "id": "x" }] }';
+    expect(setKvNamespaceIdInJsonc(src, "ns-123")).toBe(src);
+  });
+});