@decocms/blocks-cli 7.7.0 → 7.9.0

package/package.json

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

package/scripts/generate-blocks-manifest.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Integration test for `generate-blocks-manifest.ts`.
+ *
+ * Drives the programmatic entry against a tmp fixture of hostile-but-real
+ * block filenames (the shapes found in production `.deco/blocks` corpora:
+ * double-encoded `%2520`, single-encoded `%20`, parentheses, encoded slashes
+ * `%2F`, raw UTF-8), then verifies the emitted module the way a site would
+ * consume it: keys verbatim, `tsc` accepts it, and importing it (via a tsx
+ * child process from the fixture dir, resolving the raw-filename JSON import
+ * specifiers against the real files on disk) yields the parsed contents.
+ */
+import * as cp from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { generateBlocksManifest } from "./generate-blocks-manifest";
+
+const SCRIPT = path.resolve(__dirname, "generate-blocks-manifest.ts");
+
+const HOSTILE_FIXTURE: Record<string, unknown> = {
+  "pages-PDP%2520Box-102215": { path: "/pdp-box", encoded: "double" },
+  "pages-Home%20(principal)-287364": { path: "/", parens: true },
+  "collections%2Fblog%2Fauthors%2Fx": { nested: "encoded-slash" },
+  "pages-Calçados-42": { utf8: "çãé" },
+};
+
+describe("generate-blocks-manifest", () => {
+  let tmpDir: string;
+  let blocksDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-blocks-manifest-"));
+    blocksDir = path.join(tmpDir, ".deco", "blocks");
+    outFile = path.join(tmpDir, ".deco", "blocksManifest.gen.ts");
+    fs.mkdirSync(blocksDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  const writeFixture = (fixture: Record<string, unknown> = HOSTILE_FIXTURE) => {
+    for (const [key, value] of Object.entries(fixture)) {
+      fs.writeFileSync(path.join(blocksDir, `${key}.json`), JSON.stringify(value));
+    }
+  };
+
+  it("emits verbatim keys and raw-filename import specifiers for hostile names", async () => {
+    writeFixture();
+    const result = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(result.count).toBe(4);
+    expect(result.empty).toBe(false);
+    expect(result.written).toBe(true);
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    for (const key of Object.keys(HOSTILE_FIXTURE)) {
+      // Key: filename minus .json, verbatim — no decoding of %2520/%20/%2F.
+      expect(emitted).toContain(`${JSON.stringify(key)}: `);
+      // Specifier: the raw on-disk filename, relative to the emitted module.
+      expect(emitted).toContain(`from ${JSON.stringify(`./blocks/${key}.json`)};`);
+    }
+    // Never URL-decoded anywhere in the module.
+    expect(emitted).not.toContain("pages-PDP%20Box");
+    expect(emitted).not.toContain("pages-Home (principal)");
+    expect(emitted).not.toContain("collections/blog");
+  });
+
+  it("compiles under tsc (module esnext, bundler resolution, resolveJsonModule)", async () => {
+    writeFixture();
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const r = cp.spawnSync(
+      "npx",
+      [
+        "tsc",
+        "--noEmit",
+        "--strict",
+        "--module",
+        "esnext",
+        "--moduleResolution",
+        "bundler",
+        "--target",
+        "es2022",
+        "--resolveJsonModule",
+        "--skipLibCheck",
+        outFile,
+      ],
+      { encoding: "utf8" },
+    );
+    expect(r.stdout + r.stderr).not.toMatch(/error TS/);
+    expect(r.status).toBe(0);
+  }, 30_000);
+
+  it("importing the emitted module (tsx, from the fixture dir) yields the parsed contents", async () => {
+    writeFixture();
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const runner = path.join(tmpDir, ".deco", "runner.ts");
+    fs.writeFileSync(
+      runner,
+      'import blocks from "./blocksManifest.gen";\nconsole.log(JSON.stringify(blocks));\n',
+    );
+    const r = cp.spawnSync("npx", ["tsx", runner], { encoding: "utf8", cwd: tmpDir });
+    expect(r.stderr).toBe("");
+    expect(r.status).toBe(0);
+    expect(JSON.parse(r.stdout)).toEqual(HOSTILE_FIXTURE);
+  }, 30_000);
+
+  it("is idempotent: regeneration over an unchanged block set writes nothing", async () => {
+    writeFixture();
+    const first = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(first.written).toBe(true);
+    const emittedFirst = fs.readFileSync(outFile, "utf-8");
+
+    const second = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(second.written).toBe(false);
+    expect(fs.readFileSync(outFile, "utf-8")).toBe(emittedFirst);
+  });
+
+  it("orders imports deterministically regardless of readdir order (sorted filenames)", async () => {
+    writeFixture({ "z-last": { z: 1 }, "a-first": { a: 1 }, "m-mid": { m: 1 } });
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    const importOrder = [...emitted.matchAll(/from "\.\/blocks\/([^"]+)\.json";/g)].map(
+      (m) => m[1],
+    );
+    expect(importOrder).toEqual(["a-first", "m-mid", "z-last"]);
+  });
+
+  it("ignores non-json entries and subdirectories (top-level *.json only)", async () => {
+    writeFixture({ real: { ok: true } });
+    fs.writeFileSync(path.join(blocksDir, "notes.txt"), "not a block");
+    fs.mkdirSync(path.join(blocksDir, "nested"));
+    fs.writeFileSync(path.join(blocksDir, "nested", "deep.json"), "{}");
+
+    const result = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(result.count).toBe(1);
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    expect(emitted).toContain('"real": _b0');
+    expect(emitted).not.toContain("notes.txt");
+    expect(emitted).not.toContain("deep.json");
+  });
+
+  it("emits an empty manifest when the blocks dir is missing", async () => {
+    fs.rmSync(blocksDir, { recursive: true, force: true });
+    const result = await generateBlocksManifest({ blocksDir, outFile, silent: true });
+    expect(result.count).toBe(0);
+    expect(result.empty).toBe(true);
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    expect(emitted).toContain("const blocks: Record<string, unknown> = {");
+    expect(emitted).toContain("export default blocks;");
+    expect(emitted).not.toContain("import _b");
+  });
+
+  it("never lets a generated comment contain the block-comment terminator", async () => {
+    // Filenames land ONLY inside JSON.stringify-quoted string literals — a
+    // name containing `*` + `/` must not be able to truncate any comment in
+    // the emitted module (past incident with interpolated doc comments).
+    writeFixture({ "weird-*∕name": { ok: true }, "star*": { s: 1 } });
+    await generateBlocksManifest({ blocksDir, outFile, silent: true });
+
+    const emitted = fs.readFileSync(outFile, "utf-8");
+    const commentLines = emitted.split("\n").filter((l) => l.startsWith("//"));
+    for (const line of commentLines) {
+      expect(line).not.toContain("*/");
+      expect(line).not.toContain("weird");
+    }
+  });
+
+  it("runs as a CLI with --blocks-dir/--out-file overrides", () => {
+    writeFixture({ "cli-block": { via: "cli" } });
+    const cliOut = path.join(tmpDir, "custom", "manifest.gen.ts");
+
+    const r = cp.spawnSync(
+      "npx",
+      ["tsx", SCRIPT, "--blocks-dir", blocksDir, "--out-file", cliOut],
+      { encoding: "utf8", cwd: tmpDir },
+    );
+    expect(r.status).toBe(0);
+    expect(r.stdout).toContain("Generated static-import manifest for 1 blocks");
+
+    const emitted = fs.readFileSync(cliOut, "utf-8");
+    expect(emitted).toContain('"cli-block": _b0');
+    // Specifier is relative to the out file's own directory.
+    expect(emitted).toContain('from "../.deco/blocks/cli-block.json";');
+  }, 30_000);
+});

package/scripts/generate-blocks-manifest.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * Reads .deco/blocks/*.json and emits blocksManifest.gen.ts — a module that
+ * STATICALLY imports every block file and re-exports them as one
+ * `Record<string, unknown>` keyed exactly like
+ * `@decocms/blocks/cms/loadDecofileDirectory`: filename minus the `.json`
+ * extension, verbatim (no URL-decoding, no renaming — the `pages-` filename
+ * prefix on page blocks is load-bearing, see loadDecofileDirectory's doc
+ * comment).
+ *
+ * Why static imports instead of the runtime fs read: a plain
+ * `loadDecofileDirectory(".deco/blocks")` is invisible to the bundler, so in
+ * `next dev` editing a block JSON invalidates nothing (no CMS content
+ * hot-reload) and production deploys need `outputFileTracingIncludes` hacks
+ * to ship the directory. With the manifest, Next's own module graph owns the
+ * files: editing an imported JSON re-evaluates the server module graph
+ * (~120–165ms measured), which also resets module-scope memos like
+ * `createNextSetup`'s bootstrap cache — content edits reload naturally, and
+ * the JSON is bundled into the build output. The trade-off: adding or
+ * removing a block FILE requires re-running this generator (content edits do
+ * not), so wire it into the site's `generate` chain.
+ *
+ * Import specifiers use the RAW on-disk filename. Verified against webpack,
+ * Turbopack, and Vite: specifiers are opaque strings to all three — `%2520`,
+ * `%20`, parentheses, `%C3%A7`, `%2F` etc. pass through verbatim and nothing
+ * URL-decodes, so JSON.stringify-quoting the specifier (and the key) is all
+ * the escaping needed.
+ *
+ * Usage (from site root):
+ *   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks-manifest.ts
+ *
+ * CLI:
+ *   --blocks-dir  override input  (default: .deco/blocks)
+ *   --out-file    override output (default: .deco/blocksManifest.gen.ts)
+ *
+ * Programmatic:
+ *   import { generateBlocksManifest } from "@decocms/blocks-cli/generate-blocks-manifest";
+ *   await generateBlocksManifest({ blocksDir, outFile });
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+// Header of the emitted module. Kept as line comments and deliberately free
+// of interpolated filenames: block filenames can contain almost any
+// character, and a filename containing the sequence `*` + `/` inside a
+// generated /** ... */ block would terminate the comment early and corrupt
+// the module (a past incident). Filenames only ever appear inside
+// JSON.stringify-quoted string literals below.
+const HEADER = [
+  "// Auto-generated by @decocms/blocks-cli/scripts/generate-blocks-manifest.ts — do not edit.",
+  "//",
+  "// Static-import manifest of every JSON decofile in the blocks directory,",
+  "// keyed by filename minus the .json extension, VERBATIM — the same key",
+  "// format @decocms/blocks/cms/loadDecofileDirectory produces (page blocks",
+  "// keep their load-bearing `pages-` filename prefix).",
+  "//",
+  "// Because every block file is a static import, the bundler's module graph",
+  "// owns them: in `next dev`, editing a block JSON re-evaluates the server",
+  "// module graph (CMS content hot-reload), and production builds bundle the",
+  "// content (no outputFileTracingIncludes needed). Adding or removing a",
+  "// block FILE requires re-running the generator; editing content does not.",
+  "//",
+  "// Regenerate:",
+  "//   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-blocks-manifest.ts",
+  "",
+].join("\n");
+
+export interface GenerateBlocksManifestOptions {
+  blocksDir: string;
+  outFile: string;
+  /** Suppress the per-run summary log. Defaults to false. */
+  silent?: boolean;
+}
+
+export interface GenerateBlocksManifestResult {
+  count: number;
+  outFile: string;
+  /** True when the blocks dir was missing and an empty manifest was emitted. */
+  empty: boolean;
+  /**
+   * True when the manifest on disk actually changed. Regeneration is
+   * idempotent: an unchanged block set rewrites nothing, so watchers (and
+   * Next's module graph) are not tickled by no-op runs.
+   */
+  written: boolean;
+}
+
+function renderManifest(blocksDir: string, outFile: string, files: string[]): string {
+  const lines: string[] = [HEADER];
+
+  const sorted = [...files].sort(); // code-unit sort — locale-independent, diff-stable
+
+  for (let i = 0; i < sorted.length; i++) {
+    // Import specifier: the RAW filename, relative to the emitted module.
+    // JSON.stringify provides all necessary escaping — bundlers do not
+    // URL-decode specifiers, so no percent-escaping/normalizing here.
+    let spec = path
+      .relative(path.dirname(outFile), path.join(blocksDir, sorted[i]))
+      .replace(/\\/g, "/");
+    if (!spec.startsWith(".")) spec = `./${spec}`;
+    lines.push(`import _b${i} from ${JSON.stringify(spec)};`);
+  }
+
+  lines.push("");
+  lines.push("const blocks: Record<string, unknown> = {");
+  for (let i = 0; i < sorted.length; i++) {
+    const key = sorted[i].slice(0, -".json".length);
+    lines.push(`  ${JSON.stringify(key)}: _b${i},`);
+  }
+  lines.push("};");
+  lines.push("");
+  lines.push("export default blocks;");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+async function writeIfChanged(outFile: string, content: string): Promise<boolean> {
+  let existing: string | undefined;
+  try {
+    existing = await fs.promises.readFile(outFile, "utf-8");
+  } catch {}
+  if (existing === content) return false;
+  await fs.promises.mkdir(path.dirname(outFile), { recursive: true });
+  await fs.promises.writeFile(outFile, content);
+  return true;
+}
+
+export async function generateBlocksManifest(
+  options: GenerateBlocksManifestOptions,
+): Promise<GenerateBlocksManifestResult> {
+  const blocksDir = path.resolve(options.blocksDir);
+  const outFile = path.resolve(options.outFile);
+  const silent = options.silent ?? false;
+
+  if (!fs.existsSync(blocksDir)) {
+    if (!silent) {
+      console.warn(`Blocks directory not found: ${blocksDir} — generating empty manifest.`);
+    }
+    const written = await writeIfChanged(outFile, renderManifest(blocksDir, outFile, []));
+    return { count: 0, outFile, empty: true, written };
+  }
+
+  // Top-level *.json files only — mirrors loadDecofileDirectory, which
+  // filters `entry.isFile()` and never recurses (nested paths live encoded
+  // in the FILENAME, e.g. `collections%2Fblog%2F....json`).
+  const files = (await fs.promises.readdir(blocksDir, { withFileTypes: true }))
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+    .map((entry) => entry.name);
+
+  const written = await writeIfChanged(outFile, renderManifest(blocksDir, outFile, files));
+
+  if (!silent) {
+    console.log(
+      `Generated static-import manifest for ${files.length} blocks → ` +
+        `${path.relative(process.cwd(), outFile)}${written ? "" : " (unchanged)"}`,
+    );
+  }
+
+  return { count: files.length, outFile, empty: false, written };
+}
+
+// ---------------------------------------------------------------------------
+// CLI shim — same pattern as generate-blocks.ts.
+// ---------------------------------------------------------------------------
+
+function isMainModule(): boolean {
+  // tsx/node ESM: import.meta.url matches process.argv[1] when invoked directly.
+  // Use a forgiving comparison so it works under both `tsx script.ts` and
+  // `node --import tsx script.ts`.
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    const entryUrl = new URL(`file://${path.resolve(entry)}`).href;
+    return import.meta.url === entryUrl;
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  const args = process.argv.slice(2);
+  const arg = (name: string, fallback: string): string => {
+    const idx = args.indexOf(`--${name}`);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : fallback;
+  };
+
+  const blocksDir = path.resolve(process.cwd(), arg("blocks-dir", ".deco/blocks"));
+  const outFile = path.resolve(process.cwd(), arg("out-file", ".deco/blocksManifest.gen.ts"));
+
+  generateBlocksManifest({ blocksDir, outFile }).catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

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;");