@decocms/start 2.28.0 → 2.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.28.0",
+  "version": "2.28.1",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/generate-blocks.ts

@@ -18,6 +18,12 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import {
+  blockHasPath,
+  type Candidate,
+  decodeBlockNameWithPasses,
+  mergeCandidates,
+} from "./lib/blocks-dedupe";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -29,20 +35,6 @@ const blocksDir = path.resolve(process.cwd(), arg("blocks-dir", ".deco/blocks"))
 const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/blocks.gen.ts"));
 const jsonFile = outFile.replace(/\.ts$/, ".json");
 
-function decodeBlockName(filename: string): string {
-  let name = filename.replace(/\.json$/, "");
-  while (name.includes("%")) {
-    try {
-      const next = decodeURIComponent(name);
-      if (next === name) break;
-      name = next;
-    } catch {
-      break; // literal % in the decoded name — nothing left to decode
-    }
-  }
-  return name;
-}
-
 const TS_STUB = [
   "// Auto-generated — thin wrapper around blocks.gen.json.",
   "// The Vite plugin replaces this at load time with JSON.parse(...).",
@@ -62,30 +54,53 @@ if (!fs.existsSync(blocksDir)) {
 
 const files = fs.readdirSync(blocksDir).filter((f) => f.endsWith(".json"));
 
-// Deduplicate: when multiple files decode to the same key, prefer the one
-// with actual content (largest file size wins over empty {} stubs).
-const blockFiles: Record<string, string> = {};
+// Read each file into a Candidate, then let the dedupe lib pick the winner
+// per decoded key and report any collisions. See `lib/blocks-dedupe.ts` for
+// the priority order and the rationale behind it (TL;DR: never use file size,
+// don't trust mtime alone in CI clones).
+const candidatesWithKeys: Array<{ candidate: Candidate; key: string }> = [];
 for (const file of files) {
-  const name = decodeBlockName(file);
-  if (blockFiles[name]) {
-    const existingSize = fs.statSync(path.join(blocksDir, blockFiles[name])).size;
-    const newSize = fs.statSync(path.join(blocksDir, file)).size;
-    if (newSize > existingSize) {
-      blockFiles[name] = file;
-    }
+  const { name, passes } = decodeBlockNameWithPasses(file);
+  const fp = path.join(blocksDir, file);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(fp, "utf-8"));
+  } catch (e) {
+    console.warn(`Failed to parse ${file}:`, e);
     continue;
   }
-  blockFiles[name] = file;
+  candidatesWithKeys.push({
+    key: name,
+    candidate: {
+      file,
+      passes,
+      mtimeMs: fs.statSync(fp).mtimeMs,
+      hasPath: blockHasPath(parsed),
+      parsed,
+    },
+  });
 }
 
-const blocks: Record<string, unknown> = {};
-for (const [name, file] of Object.entries(blockFiles)) {
-  try {
-    const content = fs.readFileSync(path.join(blocksDir, file), "utf-8");
-    blocks[name] = JSON.parse(content);
-  } catch (e) {
-    console.warn(`Failed to parse ${file}:`, e);
+const { winners, collisions } = mergeCandidates(candidatesWithKeys);
+
+if (collisions.length > 0) {
+  console.warn(
+    `Detected ${collisions.length} filename collision(s) in ${path.relative(process.cwd(), blocksDir)}:`,
+  );
+  for (const c of collisions) {
+    const losers = c.files.filter((f) => f !== c.winner);
+    console.warn(`  - ${c.key}`);
+    console.warn(`      winner: ${c.winner}`);
+    for (const l of losers) console.warn(`      ignore: ${l}`);
   }
+  console.warn("    Cause: multiple writers (manual sync vs deco-sync-bot) producing");
+  console.warn("    different filename encodings for the same logical key. Delete the");
+  console.warn("    stale file(s) listed under 'ignore' to silence this warning.");
+}
+
+const blocks: Record<string, unknown> = {};
+for (const [name, c] of Object.entries(winners)) {
+  blocks[name] = c.parsed;
 }
 
 fs.mkdirSync(path.dirname(outFile), { recursive: true });

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

@@ -0,0 +1,179 @@
+import { describe, expect, it } from "vitest";
+import {
+  blockHasPath,
+  type Candidate,
+  decodeBlockName,
+  decodeBlockNameWithPasses,
+  mergeCandidates,
+  pickWinner,
+} from "./blocks-dedupe";
+
+const cand = (overrides: Partial<Candidate> & { file: string }): Candidate => ({
+  passes: 0,
+  mtimeMs: 0,
+  hasPath: true,
+  parsed: { path: "/" },
+  ...overrides,
+});
+
+describe("decodeBlockNameWithPasses", () => {
+  it("returns the literal key with a 0 pass count when filename has no encoding", () => {
+    expect(decodeBlockNameWithPasses("Header.json")).toEqual({ name: "Header", passes: 0 });
+  });
+
+  it("decodes a single layer of URL encoding", () => {
+    expect(decodeBlockNameWithPasses("pages-Home%20-%20LB-618509.json")).toEqual({
+      name: "pages-Home - LB-618509",
+      passes: 1,
+    });
+  });
+
+  it("decodes the bot's double-encoded scheme through to the literal key", () => {
+    // Bot encodes the raw prod URL-encoded key once: `encodeURIComponent("pages-Home%20-%20LB-618509")`.
+    expect(decodeBlockNameWithPasses("pages-Home%2520-%2520LB-618509.json")).toEqual({
+      name: "pages-Home - LB-618509",
+      passes: 2,
+    });
+  });
+
+  it("stops decoding when a literal % survives a round", () => {
+    // `%` alone isn't valid encoding — the loop catches the throw and stops.
+    expect(decodeBlockNameWithPasses("weird%percent.json")).toEqual({
+      name: "weird%percent",
+      passes: 0,
+    });
+  });
+});
+
+describe("decodeBlockName", () => {
+  it("matches decodeBlockNameWithPasses on the name", () => {
+    expect(decodeBlockName("pages-Home%2520-%2520LB-618509.json")).toBe("pages-Home - LB-618509");
+  });
+});
+
+describe("blockHasPath", () => {
+  it("returns true for live page blocks", () => {
+    expect(blockHasPath({ path: "/", sections: [] })).toBe(true);
+  });
+
+  it("returns false when path is null (zombie entry)", () => {
+    expect(blockHasPath({ path: null, sections: [] })).toBe(false);
+  });
+
+  it("returns false when path is missing", () => {
+    expect(blockHasPath({ sections: [] })).toBe(false);
+  });
+
+  it("returns false for empty path strings", () => {
+    expect(blockHasPath({ path: "" })).toBe(false);
+  });
+
+  it("returns false for non-objects", () => {
+    expect(blockHasPath(null)).toBe(false);
+    expect(blockHasPath("/")).toBe(false);
+  });
+});
+
+describe("pickWinner", () => {
+  it("prefers a candidate with a real path over a zombie", () => {
+    const live = cand({ file: "live.json", hasPath: true });
+    const zombie = cand({ file: "zombie.json", hasPath: false, parsed: { path: null } });
+    expect(pickWinner(live, zombie)).toBe(live);
+    expect(pickWinner(zombie, live)).toBe(live);
+  });
+
+  it("prefers higher decode-pass count when path-status matches", () => {
+    // The lebiscuit 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",
+      passes: 1,
+      mtimeMs: 2_000_000,
+    });
+    const fresh = cand({
+      file: "pages-Home%2520-%2520LB-618509.json",
+      passes: 2,
+      mtimeMs: 1_000_000,
+    });
+    expect(pickWinner(stale, fresh)).toBe(fresh);
+  });
+
+  it("falls through to mtime when pass count ties", () => {
+    const older = cand({ file: "a.json", passes: 1, mtimeMs: 1 });
+    const newer = cand({ file: "b.json", passes: 1, mtimeMs: 2 });
+    expect(pickWinner(older, newer)).toBe(newer);
+  });
+
+  it("falls through to lex filename when everything else ties", () => {
+    const a = cand({ file: "a.json", passes: 0, mtimeMs: 5 });
+    const b = cand({ file: "b.json", passes: 0, mtimeMs: 5 });
+    expect(pickWinner(a, b)).toBe(a);
+    expect(pickWinner(b, a)).toBe(a);
+  });
+});
+
+describe("mergeCandidates", () => {
+  it("returns each candidate unchanged when there are no collisions", () => {
+    const a = cand({ file: "Header.json" });
+    const b = cand({ file: "Footer.json" });
+    const result = mergeCandidates([
+      { candidate: a, key: "Header" },
+      { candidate: b, key: "Footer" },
+    ]);
+    expect(result.collisions).toEqual([]);
+    expect(result.winners).toEqual({ Header: a, Footer: b });
+  });
+
+  it("records a collision and picks the winner", () => {
+    const stale = cand({ file: "pages-Home%20-%20LB-618509.json", passes: 1, mtimeMs: 5 });
+    const fresh = cand({ file: "pages-Home%2520-%2520LB-618509.json", passes: 2, mtimeMs: 1 });
+    const result = mergeCandidates([
+      { candidate: stale, key: "pages-Home - LB-618509" },
+      { candidate: fresh, key: "pages-Home - LB-618509" },
+    ]);
+    expect(result.winners["pages-Home - LB-618509"]).toBe(fresh);
+    expect(result.collisions).toEqual([
+      {
+        key: "pages-Home - LB-618509",
+        files: ["pages-Home%20-%20LB-618509.json", "pages-Home%2520-%2520LB-618509.json"],
+        winner: "pages-Home%2520-%2520LB-618509.json",
+      },
+    ]);
+  });
+
+  it("collapses three-way collisions into one record without dropping the winner", () => {
+    const a = cand({ file: "a.json", passes: 0, mtimeMs: 1 });
+    const b = cand({ file: "b.json", passes: 1, mtimeMs: 2 });
+    const c = cand({ file: "c.json", passes: 2, mtimeMs: 3 });
+    const result = mergeCandidates([
+      { candidate: a, key: "k" },
+      { candidate: b, key: "k" },
+      { candidate: c, key: "k" },
+    ]);
+    expect(result.winners.k).toBe(c);
+    expect(result.collisions).toHaveLength(1);
+    expect(result.collisions[0].winner).toBe("c.json");
+    // a, b, and c should all be tracked (a and b as ignored, c as winner).
+    expect(new Set(result.collisions[0].files)).toEqual(new Set(["a.json", "b.json", "c.json"]));
+  });
+
+  it("prefers the live page over a zombie even when zombie has more passes", () => {
+    const livePlain = cand({
+      file: "Home.json",
+      passes: 0,
+      hasPath: true,
+      parsed: { path: "/" },
+    });
+    const zombieEncoded = cand({
+      file: "Home%2520.json",
+      passes: 2,
+      hasPath: false,
+      parsed: { path: null },
+    });
+    const result = mergeCandidates([
+      { candidate: zombieEncoded, key: "Home" },
+      { candidate: livePlain, key: "Home" },
+    ]);
+    expect(result.winners.Home).toBe(livePlain);
+  });
+});

package/scripts/lib/blocks-dedupe.ts

@@ -0,0 +1,128 @@
+/**
+ * Pure helpers used by `generate-blocks.ts` to choose between multiple files
+ * that decode to the same logical CMS block key.
+ *
+ * Background: the live decofile snapshot lives under `.deco/blocks/`, with
+ * one file per block. The filename is `encodeURIComponent(<rawProdKey>) +
+ * ".json"`. The Deco admin sometimes serves URL-encoded keys (e.g.
+ * `pages-Home%20-%20LB-618509`), so a single block can land on disk with
+ * different filenames depending on which writer produced it:
+ *
+ *   - The `deco-sync-bot` (CI) encodes the raw prod key as-is, producing
+ *     `pages-Home%2520-%2520LB-618509.json` (two decode passes back to the
+ *     literal key).
+ *   - The legacy manual `sync-decofile.ts` decoded keys to literal first,
+ *     so it wrote `pages-Home%20-%20LB-618509.json` (one decode pass).
+ *
+ * Both files decode to the same logical key, so the block generator must
+ * pick one. Picking by file size is wrong (a shrunk live page gives a
+ * smaller JSON than the stale older snapshot, so size silently prefers
+ * stale); picking by mtime alone is wrong (fresh `git clone` writes all
+ * files with the clone time and erases temporal ordering).
+ */
+
+export interface Candidate {
+  file: string;
+  passes: number;
+  mtimeMs: number;
+  hasPath: boolean;
+  parsed: unknown;
+}
+
+/**
+ * Repeatedly URL-decode the basename of `filename` until no `%` sequence
+ * remains. Returns the fully-decoded canonical key plus the number of
+ * decode rounds it took. Higher pass count = the writer encoded a key
+ * that itself contained `%XX` sequences = bot scheme. See module-level
+ * comment for why this matters.
+ */
+export function decodeBlockNameWithPasses(filename: string): {
+  name: string;
+  passes: number;
+} {
+  let name = filename.replace(/\.json$/, "");
+  let passes = 0;
+  while (name.includes("%")) {
+    try {
+      const next = decodeURIComponent(name);
+      if (next === name) break;
+      name = next;
+      passes++;
+    } catch {
+      break;
+    }
+  }
+  return { name, passes };
+}
+
+export function decodeBlockName(filename: string): string {
+  return decodeBlockNameWithPasses(filename).name;
+}
+
+/**
+ * Tie-break two candidates that decode to the same key. Priority:
+ *   1. Block has a non-null `path`     — beats zombie/orphan entries.
+ *   2. More decode passes              — bot's "encode raw prod key"
+ *                                        scheme wins over legacy
+ *                                        "decode-then-encode" leftovers
+ *                                        when prod uses URL-encoded keys
+ *                                        (the only case that collides).
+ *   3. Newer mtime                     — last-write-wins for same scheme.
+ *   4. Lexicographic filename          — deterministic last resort.
+ */
+export function pickWinner(a: Candidate, b: Candidate): Candidate {
+  if (a.hasPath !== b.hasPath) return a.hasPath ? a : b;
+  if (a.passes !== b.passes) return a.passes > b.passes ? a : b;
+  if (a.mtimeMs !== b.mtimeMs) return a.mtimeMs > b.mtimeMs ? a : b;
+  return a.file < b.file ? a : b;
+}
+
+/** True iff a parsed block JSON looks like a live page (non-empty `.path`). */
+export function blockHasPath(parsed: unknown): boolean {
+  return (
+    typeof parsed === "object" &&
+    parsed !== null &&
+    "path" in parsed &&
+    typeof (parsed as { path?: unknown }).path === "string" &&
+    (parsed as { path: string }).path.length > 0
+  );
+}
+
+export interface CollisionRecord {
+  key: string;
+  files: string[];
+  winner: string;
+}
+
+export interface MergeResult {
+  winners: Record<string, Candidate>;
+  collisions: CollisionRecord[];
+}
+
+/**
+ * Reduce a list of candidates into one winner per decoded key, recording
+ * every collision so the caller can surface it as a build warning.
+ */
+export function mergeCandidates(
+  candidates: Array<{ candidate: Candidate; key: string }>,
+): MergeResult {
+  const winners: Record<string, Candidate> = {};
+  // Track every file that decoded to a given key so three-way (and beyond)
+  // collisions don't lose the eventual winner from the file list.
+  const filesByKey: Record<string, string[]> = {};
+  for (const { candidate, key } of candidates) {
+    if (!filesByKey[key]) filesByKey[key] = [];
+    const list = filesByKey[key];
+    if (!list.includes(candidate.file)) list.push(candidate.file);
+
+    const existing = winners[key];
+    winners[key] = existing ? pickWinner(existing, candidate) : candidate;
+  }
+
+  const collisions: CollisionRecord[] = [];
+  for (const [key, files] of Object.entries(filesByKey)) {
+    if (files.length < 2) continue;
+    collisions.push({ key, files, winner: winners[key].file });
+  }
+  return { winners, collisions };
+}