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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "8.0.0",
+  "version": "8.1.0-next.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -17,7 +17,9 @@
     "deco-audit-observability": "./scripts/audit-observability-config.ts",
     "deco-migrate-blocks-to-kv": "./scripts/migrate-blocks-to-kv.ts",
     "deco-sync-blocks-to-kv": "./scripts/sync-blocks-to-kv.ts",
-    "deco-upgrade-6-to-7": "./scripts/upgrade-6-to-7.ts"
+    "deco-sync-blocks-bot": "./scripts/sync-blocks-bot.ts",
+    "deco-upgrade-6-to-7": "./scripts/upgrade-6-to-7.ts",
+    "deco-reconcile": "./scripts/reconcile.ts"
   },
   "//exports": "Deliberately narrow. ./generate is the ONE public module entry (unified orchestrator); ./generate-blocks stays only because @decocms/tanstack's vite plugin tsImports it (readBlockDelta + programmatic generateBlocks) — each surviving entry must name its consumer here. The other scripts remain shipped FILES (the orchestrator spawns them; sites' existing `tsx node_modules/@decocms/blocks-cli/scripts/generate-*.ts` invocations keep working) but are internal implementation details of ./generate, not module subpaths. CLIs are exposed via bin, not exports.",
   "exports": {
@@ -31,7 +33,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0",
+    "@decocms/blocks": "8.1.0-next.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/analyze-traces.mjs

@@ -361,6 +361,7 @@ function imageStats(events, ns) {
   const imgDomains = [
     "vtexassets",
     "decoims",
+    "assets.decocms.com",
     "decoazn",
     "decocache",
     "deco-sites-assets",

package/scripts/cdn-rules.test.ts

@@ -0,0 +1,105 @@
+import { BOT_UA_SUBSTRINGS, isBot } from "@decocms/blocks/cms";
+import { DECO_MATCHERS_OVERRIDE_PARAM } from "@decocms/blocks/matchers/override";
+import { SEGMENT_COOKIE } from "@decocms/blocks/sdk/flags";
+import { describe, expect, it } from "vitest";
+import { AUTH_COOKIE_PREFIXES, bypassExpression, cacheRuleset } from "./cdn-rules";
+
+/**
+ * These are drift tests, not behaviour tests. The CDN rules and the Worker's
+ * cache key are two descriptions of the same segmentation; when they disagree,
+ * one visitor gets another's response. Each assertion below pins one dimension
+ * to the constant the Worker actually uses.
+ */
+describe("CDN bypass expression tracks the worker cache key", () => {
+  const expr = bypassExpression();
+
+  it("bypasses authenticated visitors", () => {
+    // Without this, a logged-in request is answered from the anonymous CDN
+    // entry and the Worker never runs — no header can save it.
+    for (const name of AUTH_COOKIE_PREFIXES) {
+      expect(expr).toContain(`http.cookie contains "${name}"`);
+    }
+  });
+
+  it("bypasses the A/B cohort cookie by its real name (__abf)", () => {
+    expect(expr).toContain(`${SEGMENT_COOKIE}=`);
+  });
+
+  it("bypasses every bot UA the framework renders eagerly (__bot)", () => {
+    for (const ua of BOT_UA_SUBSTRINGS) {
+      expect(expr).toContain(ua);
+      // The list is only meaningful if it really is what isBot() matches.
+      expect(isBot(`Mozilla/5.0 (compatible; ${ua}/1.0)`)).toBe(true);
+    }
+  });
+
+  it("bypasses programmatic fetches (__fetch)", () => {
+    expect(expr).toContain("sec-fetch-dest");
+  });
+
+  it("bypasses matcher overrides by their real param name", () => {
+    expect(expr).toContain(DECO_MATCHERS_OVERRIDE_PARAM);
+  });
+
+  it("bypasses draft preview", () => {
+    expect(expr).toContain("__draft=");
+    expect(expr).toContain("__deco_draft");
+  });
+
+  it("is scoped to hostnames that opted in", () => {
+    // A shared zone: an unscoped rule would enable every site at once.
+    expect(expr).toContain("cf.hostname.metadata");
+    for (const rule of cacheRuleset().rules) {
+      expect(rule.expression).toContain("cf.hostname.metadata");
+    }
+  });
+});
+
+describe("cache ruleset", () => {
+  const [bypass, cache] = cacheRuleset().rules;
+
+  it("does not rely on rule order — the two rules are mutually exclusive", () => {
+    // Cloudflare's cache phase is LAST-match-wins for non-terminating actions,
+    // so a catch-all `cache: true` listed after `cache: false` silently
+    // overrides it and the whole bypass list becomes inert. An earlier version
+    // of this file had exactly that bug, and an earlier version of THIS test
+    // asserted "bypass is evaluated first", certifying it. Correctness must
+    // come from the expressions, not the array order.
+    expect(bypass.action_parameters.cache).toBe(false);
+    expect(cache.action_parameters.cache).toBe(true);
+
+    const clauses = bypass.expression.slice(bypass.expression.indexOf(") and (") + 7, -1);
+    expect(cache.expression).toContain(`and not (${clauses})`);
+  });
+
+  it("does not bypass /_serverFn on sec-fetch-dest, which is what it exists to cache", () => {
+    // Every /_serverFn call is an XHR and sends `sec-fetch-dest: empty`. A bare
+    // clause would bypass exactly the traffic `serverfn-segment` caches,
+    // reducing the feature to a no-op. `buildCacheKey` excludes server-fn paths
+    // from `__fetch` for the same reason.
+    expect(bypass.expression).toContain('not starts_with(http.request.uri.path, "/_serverFn/")');
+    expect(bypass.expression).toContain('not starts_with(http.request.uri.path, "/_server/")');
+  });
+
+  it("keys by device, since deviceSpecificKeys defaults to true", () => {
+    expect(cache.action_parameters.cache_key?.cache_by_device_type).toBe(true);
+  });
+
+  it("takes the TTL from the origin, not a copy of the profile table", () => {
+    expect(cache.action_parameters.edge_ttl?.mode).toBe("respect_origin");
+  });
+});
+
+describe("geo in the cache key", () => {
+  it("is off by default — a site without regional content must not pay for it", () => {
+    const [, cache] = cacheRuleset().rules;
+    expect(cache.action_parameters.cache_key?.custom_key).toBeUndefined();
+  });
+
+  it("is opt-in, for sites whose content actually varies by region", () => {
+    const [, cache] = cacheRuleset({ geo: true }).rules;
+    expect(cache.action_parameters.cache_key?.custom_key?.user?.geo).toBe(true);
+    // device stays keyed either way
+    expect(cache.action_parameters.cache_key?.cache_by_device_type).toBe(true);
+  });
+});

package/scripts/cdn-rules.ts

@@ -0,0 +1,192 @@
+#!/usr/bin/env tsx
+/**
+ * Generate (and optionally apply) the Cloudflare Cache Rules that let the CDN
+ * serve deco storefronts without invoking the Worker.
+ *
+ * ## Why this is generated and not hand-written
+ *
+ * The Worker keys its edge cache on a SYNTHETIC Request carrying
+ * `__seg`/`__cf_device`/`__cf_geo`/`__bot`/`__fetch`/`__abf` (`buildCacheKey`
+ * in `@decocms/tanstack`). Cloudflare's CDN keys on the raw URL and ignores
+ * `Vary` beyond `Accept-Encoding`. Every dimension the CDN cannot reproduce has
+ * to become a bypass here — and each one corresponds to a constant on the
+ * Worker side. Two hand-maintained copies of that list drift, and the failure
+ * mode is not a slow page, it is one visitor being served another's response.
+ * So the expressions below are DERIVED from the same constants the Worker uses.
+ *
+ * ## Division of labour
+ *
+ * The Worker stays the source of truth for *whether* a response may be cached:
+ * private routes, logged-in requests, drafts and set-cookie responses already
+ * go out with `CDN-Cache-Control: no-store`, and Cloudflare honours that. So
+ * these rules deliberately do NOT enumerate private paths — a site adding
+ * `registerPrivatePaths([...])` propagates to the CDN on its own.
+ *
+ * What the rules must cover is the narrower case the header cannot reach: when
+ * the CDN answers from cache WITHOUT consulting the Worker, and would hand one
+ * visitor an entry that belongs to another segment.
+ *
+ * ## Scoping in a shared zone
+ *
+ * Sites are custom hostnames under one deco zone (Cloudflare for SaaS), so a
+ * rule applies to every site at once. Enablement therefore rides on per-hostname
+ * custom metadata rather than a rule per site:
+ *
+ *   curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID/custom_hostnames/$ID" \
+ *     --request PATCH --header "Authorization: Bearer $TOKEN" \
+ *     --json '{"custom_metadata": {"deco_cdn_html": "on"}}'
+ *
+ * Rolling out to a site is that PATCH; rolling back is setting it to "off".
+ * Neither touches the ruleset.
+ *
+ * ## Why zone rules, and not Workers Cache
+ *
+ * `/_serverFn` is already handled without touching the zone: the client carries
+ * a segment marker in the URL (`sdk/cdnSegment`), which makes the URL a
+ * complete key. HTML cannot do that — the initial navigation is a browser
+ * request with no hook to attach a marker to.
+ *
+ * Workers Cache does not close the gap either. Its documented mechanisms are
+ * `Vary` and per-entrypoint disable, and neither expresses "not for a logged-in
+ * visitor": `Vary: Cookie` compares verbatim, so every visitor's analytics
+ * cookies produce a distinct entry and the cache is dead on arrival. There is
+ * no per-request opt-out before the Worker runs — and on a cache HIT the Worker
+ * does not run, so the `no-store` it would have emitted never exists.
+ *
+ * Zone rules are the only layer that can decline BEFORE the Worker, which is
+ * exactly what a logged-in visitor needs.
+ *
+ * Usage:
+ *   tsx scripts/cdn-rules.ts                  # print the ruleset as JSON
+ *   tsx scripts/cdn-rules.ts --expression     # print just the bypass expression
+ *   tsx scripts/cdn-rules.ts --geo            # include geo in the cache key
+ */
+
+import { BOT_UA_SUBSTRINGS } from "@decocms/blocks/cms";
+import { DECO_MATCHERS_OVERRIDE_PARAM } from "@decocms/blocks/matchers/override";
+import { SEGMENT_COOKIE } from "@decocms/blocks/sdk/flags";
+
+/** Metadata key read off the custom hostname to enable CDN caching per site. */
+export const CDN_ENABLED_METADATA_KEY = "deco_cdn_html";
+
+/**
+ * Auth cookie names that mean "this visitor must never be served a shared CDN
+ * entry". VTEX sets both the bare name and an account-suffixed variant
+ * (`VtexIdclientAutCookie_<account>`); matching on the prefix covers both.
+ */
+export const AUTH_COOKIE_PREFIXES = ["VtexIdclientAutCookie"];
+
+const enabled = `lookup_json_string(cf.hostname.metadata, "${CDN_ENABLED_METADATA_KEY}") eq "on"`;
+
+/** Path prefix for TanStack server-function requests. */
+const SERVER_FN_PREFIXES = ["/_serverFn/", "/_server/"];
+
+/**
+ * The individual bypass clauses, each annotated with the `buildCacheKey`
+ * dimension it mirrors. If you add a dimension to the cache key, it belongs
+ * here too.
+ */
+function bypassClauses(): string[] {
+  const notServerFn = SERVER_FN_PREFIXES.map(
+    (p) => `not starts_with(http.request.uri.path, "${p}")`,
+  ).join(" and ");
+
+  return [
+    // Worker key: no equivalent — an authenticated visitor would otherwise be
+    // served the cached anonymous entry without the Worker ever running. This
+    // is the single most important clause in the file.
+    ...AUTH_COOKIE_PREFIXES.map((name) => `http.cookie contains "${name}"`),
+
+    // Worker key: `__abf` — the sticky A/B cohort cookie.
+    `http.cookie contains "${SEGMENT_COOKIE}="`,
+
+    // Worker key: `__bot` — bots render every section eagerly (~10x payload).
+    `lower(http.user_agent) matches "${BOT_UA_SUBSTRINGS.join("|")}"`,
+
+    // Worker key: `__fetch` — programmatic fetches also render eagerly.
+    //
+    // Carved out for `/_serverFn`, which ALWAYS sends `sec-fetch-dest: empty`
+    // (it is an XHR). Without the carve-out this single clause would bypass
+    // exactly the traffic `cdnCacheControl: "serverfn-segment"` exists to
+    // cache, silently reducing the whole feature to a no-op. `buildCacheKey`
+    // excludes server-fn paths from `__fetch` for the same reason, so this
+    // mirrors it rather than diverging.
+    `(http.request.headers["sec-fetch-dest"][0] eq "empty" and ${notServerFn})`,
+
+    // Worker: `isCacheable()` bypasses these outright. Duplicated here so a
+    // draft never depends on the response header alone.
+    'http.request.uri.query contains "__draft="',
+    'http.request.uri.query contains "__deco_preview"',
+    'http.request.uri.query contains "pathTemplate"',
+    `http.request.uri.query contains "${DECO_MATCHERS_OVERRIDE_PARAM}"`,
+    `any(http.request.headers.names[*] eq "${DECO_MATCHERS_OVERRIDE_PARAM}")`,
+    'http.cookie contains "__deco_draft"',
+  ];
+}
+
+/** Requests that must never be served from a shared CDN entry. */
+export function bypassExpression(): string {
+  return `(${enabled}) and (${bypassClauses().join(" or ")})`;
+}
+
+/**
+ * The ruleset.
+ *
+ * The two rules are MUTUALLY EXCLUSIVE by expression, not by ordering. That is
+ * deliberate and load-bearing: Cloudflare's cache phase is **last-match-wins**
+ * for non-terminating actions like `set_cache_settings`, so a catch-all
+ * `cache: true` rule listed after a `cache: false` one silently overrides it.
+ * Scoping rule 2 with `and not (<bypass clauses>)` means correctness no longer
+ * depends on rule order at all — reorder them freely, or apply them via an API
+ * that does not preserve order, and the behaviour is unchanged.
+ *
+ * https://developers.cloudflare.com/cache/how-to/cache-rules/order/
+ *
+ * Note what is NOT set here: the edge TTL. `respect_origin` keeps the TTL
+ * coming from the `CDN-Cache-Control` the Worker already derives per cache
+ * profile, so the profile table stays in one place.
+ */
+/**
+ * @param opts.geo Include country/region in the cache key. Required for a site
+ *   whose content varies by region (a `website/matchers/location.ts` in the
+ *   decofile). Leave it off otherwise: it multiplies the number of entries that
+ *   have to warm, for content that is identical across them.
+ *
+ *   NOTE: this keys on country+region. A site whose matchers discriminate by
+ *   CITY or coordinates needs finer granularity than this, and enabling CDN
+ *   caching there serves the wrong variant — worse than today, since the Worker
+ *   at least evaluates the matcher on every request.
+ */
+export function cacheRuleset(opts: { geo?: boolean } = {}) {
+  const clauses = bypassClauses().join(" or ");
+
+  return {
+    rules: [
+      {
+        description: "deco: bypass CDN for segment-sensitive requests",
+        expression: `(${enabled}) and (${clauses})`,
+        action: "set_cache_settings",
+        action_parameters: { cache: false },
+      },
+      {
+        description: "deco: cache by device type, TTL from origin",
+        expression: `(${enabled}) and not (${clauses})`,
+        action: "set_cache_settings",
+        action_parameters: {
+          cache: true,
+          cache_key: {
+            cache_by_device_type: true,
+            ...(opts.geo ? { custom_key: { user: { geo: true } } } : {}),
+          },
+          edge_ttl: { mode: "respect_origin" },
+        },
+      },
+    ],
+  };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const expressionOnly = process.argv.includes("--expression");
+  const geo = process.argv.includes("--geo");
+  console.log(expressionOnly ? bypassExpression() : JSON.stringify(cacheRuleset({ geo }), null, 2));
+}

package/scripts/deco-migrate-cli.ts

@@ -123,15 +123,15 @@ function showHelp() {
     npx tsx scripts/deco-migrate-cli.ts https://github.com/org/my-site
 
     ${dim("# Migrate local dir, compare against golden reference:")}
-    npx tsx scripts/deco-migrate-cli.ts ./casaevideo \\
-      --ref ./casaevideo-storefront
+    npx tsx scripts/deco-migrate-cli.ts ./acme \\
+      --ref ./acme-storefront
 
     ${dim("# Quick re-run (wipe previous output first):")}
-    npx tsx scripts/deco-migrate-cli.ts ./casaevideo \\
-      -o ./casaevideo-migrated --clean
+    npx tsx scripts/deco-migrate-cli.ts ./acme \\
+      -o ./acme-migrated --clean
 
     ${dim("# Dry run to preview what would change:")}
-    npx tsx scripts/deco-migrate-cli.ts ./casaevideo --dry-run -v
+    npx tsx scripts/deco-migrate-cli.ts ./acme --dry-run -v
 `);
 }
 
@@ -429,8 +429,7 @@ async function main() {
       console.log(`\n  ${bold("Next steps:")}`);
       console.log(`    cd ${outputDir}`);
       console.log(`    npm install`);
-      console.log(`    npm run generate:blocks`);
-      console.log(`    npm run generate:schema`);
+      console.log(`    npm run generate`);
       console.log(`    npx tsr generate`);
       console.log(`    npm run dev`);
     }

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

@@ -9,12 +9,15 @@ import {
   revisionKey,
   snapshotKey,
 } from "@decocms/blocks/cms";
+import { splitExactRedirects } from "@decocms/blocks/sdk/redirects";
 import { createKvRestClient, type KvRestClient, kvConfigFromEnv } from "./lib/cf-kv-rest";
+import { readDecofileFromDir } from "./lib/read-decofile";
 import { kvNamespaceIdFromToml, kvNamespaceIdFromWrangler } from "./lib/wrangler-config";
 import {
   buildSnapshot,
   recordAndGcDeployment,
   setLiveDeployment,
+  syncRedirectsToKv,
   verifySnapshotInKv,
   writeSnapshotToKv,
 } from "./lib/kv-snapshot";
@@ -45,6 +48,14 @@ function makeClient(initial: Record<string, string> = {}) {
       Promise.resolve(
         [...store.keys()].filter((k) => !prefix || k.startsWith(prefix)),
       ),
+    putMany: (entries) => {
+      for (const e of entries) store.set(e.key, e.value);
+      return Promise.resolve();
+    },
+    deleteMany: (keys) => {
+      for (const k of keys) store.delete(k);
+      return Promise.resolve();
+    },
   };
   return { client, store, putOrder };
 }
@@ -341,3 +352,164 @@ describe("sync-helpers", () => {
     expect(paths).not.toContain(undefined);
   });
 });
+
+describe("readDecofileFromDir — CSV redirects", () => {
+  /** A site tree: `.deco/blocks/*.json` + `public/*.csv`. Returns the blocks dir. */
+  function makeSite(blocks: Record<string, unknown>, csv: Record<string, string>): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "decofile-csv-"));
+    const blocksDir = path.join(root, ".deco", "blocks");
+    fs.mkdirSync(blocksDir, { recursive: true });
+    fs.mkdirSync(path.join(root, "public"), { recursive: true });
+    for (const [name, value] of Object.entries(blocks)) {
+      fs.writeFileSync(path.join(blocksDir, name), JSON.stringify(value));
+    }
+    for (const [name, value] of Object.entries(csv)) {
+      fs.writeFileSync(path.join(root, "public", name), value);
+    }
+    return blocksDir;
+  }
+
+  it("materializes a CSV loader nested under site.routes[] into a top-level block", () => {
+    // The shape that broke production: the CSV loader is nested inside
+    // `site.json -> routes[]`, where `loadRedirects` (top-level only) can't see
+    // it, and the CSV itself was only ever read by the unported Fresh loader.
+    const blocksDir = makeSite(
+      {
+        "site.json": {
+          __resolveType: "site/apps/site.ts",
+          routes: [{ __resolveType: "website/loaders/redirectsFromCsv.ts", from: "static/r.csv" }],
+        },
+      },
+      { "r.csv": "from,to,type\n/old,/new,permanent\n/tmp,/other\n" },
+    );
+
+    const { blocks } = readDecofileFromDir(blocksDir, { silent: true });
+
+    expect(blocks["__csv_redirects__r.csv"]).toEqual({
+      __resolveType: "website/loaders/redirects.ts",
+      redirects: [
+        { from: "/old", to: "/new", type: "permanent" },
+        { from: "/tmp", to: "/other", type: "temporary" },
+      ],
+    });
+    // The real blocks are untouched.
+    expect(blocks.site).toBeDefined();
+  });
+
+  it("splits CSV-derived exact redirects out of the snapshot", () => {
+    const blocksDir = makeSite(
+      {
+        "site.json": {
+          __resolveType: "site/apps/site.ts",
+          routes: [{ __resolveType: "website/loaders/redirectsFromCsv.ts", from: "static/r.csv" }],
+        },
+      },
+      { "r.csv": "from,to,type\n/old,/new,permanent\n/g/*,/h/*\n" },
+    );
+    const { blocks } = readDecofileFromDir(blocksDir, { silent: true });
+    const split = splitExactRedirects(blocks);
+
+    expect(split.exact).toEqual([{ path: "/old", to: "/new", status: 301 }]);
+    expect(JSON.stringify(split.blocks)).not.toContain('"/old"');
+    expect(split.blocks["__csv_redirects__r.csv"]).toMatchObject({ redirects: [{ from: "/g/*" }] });
+  });
+
+  it("lets a real block win over the synthetic one on a key collision", () => {
+    const blocksDir = makeSite(
+      {
+        "site.json": {
+          routes: [{ __resolveType: "website/loaders/redirectsFromCsv.ts", from: "r.csv" }],
+        },
+        // Decodes to exactly the synthetic key the CSV materializer produces.
+        "__csv_redirects__r.csv.json": { curated: true },
+      },
+      { "r.csv": "/old,/new\n" },
+    );
+
+    const { blocks } = readDecofileFromDir(blocksDir, { silent: true });
+
+    // `{ ...csv, ...blocks }` — the curated block wins, never the synthetic one.
+    expect(blocks["__csv_redirects__r.csv"]).toEqual({ curated: true });
+  });
+
+  it("is a no-op when no CSV loader is referenced", () => {
+    const blocksDir = makeSite({ "site.json": { __resolveType: "site/apps/site.ts" } }, {});
+    const { blocks } = readDecofileFromDir(blocksDir, { silent: true });
+    expect(Object.keys(blocks)).toEqual(["site"]);
+  });
+});
+
+describe("syncRedirectsToKv", () => {
+  /** In-memory client with the bulk ops the redirect sync uses. */
+  function makeBulkClient(initial: Record<string, string> = {}) {
+    const store = new Map(Object.entries(initial));
+    const client = {
+      get: (k: string) => Promise.resolve(store.get(k) ?? null),
+      put: (k: string, v: string) => {
+        store.set(k, v);
+        return Promise.resolve();
+      },
+      delete: (k: string) => {
+        store.delete(k);
+        return Promise.resolve();
+      },
+      list: (prefix?: string) =>
+        Promise.resolve([...store.keys()].filter((k) => !prefix || k.startsWith(prefix))),
+      putMany: (entries: Array<{ key: string; value: string }>) => {
+        for (const e of entries) store.set(e.key, e.value);
+        return Promise.resolve();
+      },
+      deleteMany: (keys: string[]) => {
+        for (const k of keys) store.delete(k);
+        return Promise.resolve();
+      },
+    };
+    return { client: client as unknown as KvRestClient, store };
+  }
+
+  const rule = (path: string, to: string, status: 301 | 302 = 301) => ({ path, to, status });
+
+  it("adds new rules under redirect:<id>:<path>", async () => {
+    const { client, store } = makeBulkClient();
+    const out = await syncRedirectsToKv(client, [rule("/old", "/new")], ID);
+
+    expect(out).toEqual({ written: 1, deleted: 0 });
+    expect(store.get(`redirect:${ID}:/old`)).toBe('{"to":"/new","status":301}');
+  });
+
+  it("updates a changed target in place", async () => {
+    const { client, store } = makeBulkClient({
+      [`redirect:${ID}:/old`]: '{"to":"/stale","status":302}',
+    });
+    await syncRedirectsToKv(client, [rule("/old", "/fresh")], ID);
+    expect(store.get(`redirect:${ID}:/old`)).toBe('{"to":"/fresh","status":301}');
+  });
+
+  it("removes rules that no longer exist", async () => {
+    // The reason this diffs against a prefix LIST: KV has no "replace
+    // everything under this prefix", so a deleted rule would redirect forever.
+    const { client, store } = makeBulkClient({
+      [`redirect:${ID}:/keep`]: '{"to":"/a","status":301}',
+      [`redirect:${ID}:/gone`]: '{"to":"/b","status":301}',
+    });
+    const out = await syncRedirectsToKv(client, [rule("/keep", "/a")], ID);
+
+    expect(out).toEqual({ written: 1, deleted: 1 });
+    expect(store.has(`redirect:${ID}:/gone`)).toBe(false);
+    expect(store.has(`redirect:${ID}:/keep`)).toBe(true);
+  });
+
+  it("never touches another deployment's keys", async () => {
+    const { client, store } = makeBulkClient({
+      "redirect:other-sha:/gone": '{"to":"/x","status":301}',
+    });
+    await syncRedirectsToKv(client, [], ID);
+    expect(store.has("redirect:other-sha:/gone")).toBe(true);
+  });
+
+  it("does not disturb the decofile keys", async () => {
+    const { client, store } = makeBulkClient({ [snapshotKey(ID)]: "{}" });
+    await syncRedirectsToKv(client, [rule("/a", "/b")], ID);
+    expect(store.has(snapshotKey(ID))).toBe(true);
+  });
+});

package/scripts/generate-blocks.test.ts

@@ -1,9 +1,20 @@
+import * as cp from "node:child_process";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { readBlockDelta } from "./generate-blocks";
 
+const SCRIPT = path.resolve(__dirname, "generate-blocks.ts");
+
+function runGenerator(
+  args: string[],
+  opts: { cwd?: string } = {},
+): { stdout: string; stderr: string; code: number } {
+  const r = cp.spawnSync("npx", ["tsx", SCRIPT, ...args], { encoding: "utf8", cwd: opts.cwd });
+  return { stdout: r.stdout || "", stderr: r.stderr || "", code: r.status ?? 0 };
+}
+
 describe("readBlockDelta", () => {
   let dir: string;
 

package/scripts/generate-blocks.ts

@@ -27,10 +27,6 @@
  *                 --out-file by swapping its extension, so passing --out-file
  *                 moves both artifacts together)
  *
- * If no `--out-file` is passed and the OLD default (src/server/cms/blocks.gen.ts)
- * still exists on disk, a one-line legacy warning is printed to stderr and the
- * NEW default is written anyway — see lib/legacyArtifact.ts.
- *
  * Programmatic:
  *   import { generateBlocks } from "@decocms/blocks-cli/generate-blocks";
  *   await generateBlocks({ blocksDir, outFile });
@@ -49,7 +45,6 @@ import {
   singleDecodeBlockName,
 } from "./lib/blocks-dedupe";
 import { buildCsvRedirectBlocks } from "./lib/csv-redirects";
-import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 const TS_STUB = [
   "// Auto-generated — thin wrapper around blocks.gen.json.",
@@ -321,13 +316,8 @@ if (isMainModule()) {
   };
 
   const blocksDir = path.resolve(process.cwd(), arg("blocks-dir", ".deco/blocks"));
-  const OUT_FILE_EXPLICIT = args.includes("--out-file");
   const NEW_DEFAULT_OUT_FILE = ".deco/blocks.gen.ts";
-  const OLD_DEFAULT_OUT_FILE = "src/server/cms/blocks.gen.ts";
   const outFile = path.resolve(process.cwd(), arg("out-file", NEW_DEFAULT_OUT_FILE));
-  if (!OUT_FILE_EXPLICIT && fs.existsSync(path.resolve(process.cwd(), OLD_DEFAULT_OUT_FILE))) {
-    warnLegacyArtifact(OLD_DEFAULT_OUT_FILE, NEW_DEFAULT_OUT_FILE);
-  }
 
   generateBlocks({ blocksDir, outFile }).catch((err) => {
     console.error(err);

package/scripts/generate-invoke.test.ts

@@ -197,8 +197,8 @@ describe("generate-invoke.ts — default --apps-dir resolution", () => {
   // 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,
+  // `--apps-dir node_modules/@decocms/apps-vtex/src` by hand (a production
+  // site'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 } {