@decocms/blocks-cli 7.3.1 → 7.5.0

package/package.json

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

package/scripts/generate-blocks.ts

@@ -14,7 +14,14 @@
  *
  * Env / CLI:
  *   --blocks-dir  override input  (default: .deco/blocks)
- *   --out-file    override output (default: src/server/cms/blocks.gen.ts)
+ *   --out-file    override output (default: .deco/blocks.gen.ts, with a sibling
+ *                 .deco/blocks.gen.json — the .json path is always derived from
+ *                 --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";
@@ -33,6 +40,7 @@ import {
   mergeCandidates,
   singleDecodeBlockName,
 } from "./lib/blocks-dedupe";
+import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 const TS_STUB = [
   "// Auto-generated — thin wrapper around blocks.gen.json.",
@@ -291,7 +299,13 @@ if (isMainModule()) {
   };
 
   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 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.ts

@@ -11,6 +11,16 @@
  * This script generates an equivalent file where each server function is a
  * top-level const, which the compiler can correctly transform into RPC stubs.
  *
+ * Unlike the other four generators (generate-blocks, generate-loaders,
+ * generate-sections, generate-schema), this one's default output stays under
+ * `src/`, not `.deco/`. The other four emit inert framework artifacts (data
+ * snapshots / metadata) that the framework loads at runtime — those belong
+ * next to the rest of the framework's own generated state. This file emits
+ * actual app server-function code (`createServerFn().handler()` calls) that
+ * TanStack Start's own build-time compiler transforms into RPC stubs; it's
+ * compiled and shipped as part of the site's application code, so it lives
+ * in `src/` alongside the code it's compiled with, not in `.deco/`.
+ *
  * Usage (from site root):
  *   npx tsx node_modules/@decocms/blocks-cli/scripts/generate-invoke.ts
  *

package/scripts/generate-loaders.ts

@@ -34,13 +34,18 @@
  * CLI:
  *   --loaders-dir         override loaders input  (default: src/loaders)
  *   --actions-dir         override actions input  (default: src/actions)
- *   --out-file            override output         (default: src/server/cms/loaders.gen.ts)
+ *   --out-file            override output         (default: .deco/loaders.gen.ts)
  *   --exclude             comma-separated list of loader keys to skip (they have custom wiring)
  *   --prune-by-decofile   only emit entries whose key appears as `__resolveType` in any JSON
  *   --decofile-dir        @deprecated alias for --prune-by-decofile
+ *
+ * If no `--out-file` is passed and the OLD default (src/server/cms/loaders.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.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -50,7 +55,13 @@ function arg(name: string, fallback: string): string {
 
 const loadersDir = path.resolve(process.cwd(), arg("loaders-dir", "src/loaders"));
 const actionsDir = path.resolve(process.cwd(), arg("actions-dir", "src/actions"));
-const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/loaders.gen.ts"));
+const OUT_FILE_EXPLICIT = args.includes("--out-file");
+const NEW_DEFAULT_OUT_FILE = ".deco/loaders.gen.ts";
+const OLD_DEFAULT_OUT_FILE = "src/server/cms/loaders.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);
+}
 const excludeRaw = arg("exclude", "");
 const excludeSet = new Set(excludeRaw.split(",").map((s) => s.trim()).filter(Boolean));
 

package/scripts/generate-schema.test.ts

@@ -1,6 +1,33 @@
+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 { Project } from "ts-morph";
-import { describe, expect, it } from "vitest";
-import { WIDGET_TYPE_FORMATS, applyWidgetFormat, typeToJsonSchema } from "./generate-schema";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import {
+  WIDGET_TYPE_FORMATS,
+  applyWidgetFormat,
+  definitionIdForPath,
+  typeToJsonSchema,
+} from "./generate-schema";
+
+describe("definitionIdForPath", () => {
+  it("is repo-relative, never absolute", () => {
+    const id = definitionIdForPath(
+      "/Users/anyone/code/mysite/src/sections/Hero.tsx",
+      "/Users/anyone/code/mysite",
+    );
+    expect(Buffer.from(id, "base64").toString()).toBe("src/sections/Hero.tsx");
+  });
+
+  it("normalizes file:// prefixes from ts-morph", () => {
+    const id = definitionIdForPath(
+      "file:///Users/anyone/code/mysite/src/sections/Hero.tsx",
+      "/Users/anyone/code/mysite",
+    );
+    expect(Buffer.from(id, "base64").toString()).toBe("src/sections/Hero.tsx");
+  });
+});
 
 describe("applyWidgetFormat", () => {
   it("recovers an unresolved widget alias (empty schema) as string + format", () => {
@@ -72,3 +99,95 @@ describe("typeToJsonSchema with an unresolvable widget alias import", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Default output path (.deco/) + legacy warning — subprocess, mirrors the
+// pattern in generate-sections.test.ts. generate-schema.ts IS guarded by
+// isMainModule(), but it's still driven as a subprocess here so the CLI's
+// argv-parsed OUT_REL/legacy-check top-level code runs against a real cwd.
+// ---------------------------------------------------------------------------
+
+const SCRIPT = path.resolve(__dirname, "generate-schema.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("generate-schema default output path (.deco/)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-schema-defaults-"));
+    fs.writeFileSync(
+      path.join(tmpDir, "tsconfig.json"),
+      JSON.stringify({
+        compilerOptions: {
+          target: "ES2020",
+          module: "ESNext",
+          moduleResolution: "Bundler",
+          jsx: "react-jsx",
+          skipLibCheck: true,
+          strict: true,
+        },
+      }),
+    );
+    const sectionsDir = path.join(tmpDir, "src", "sections");
+    fs.mkdirSync(sectionsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      [
+        "export interface Props {",
+        "  title: string;",
+        "}",
+        "export default function Hero(props: Props) { return null; }",
+      ].join("\n"),
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("writes to .deco/meta.gen.json when no --out flag is passed", () => {
+    const { code } = runGenerator(["--skip-apps"], { cwd: tmpDir });
+    expect(code).toBe(0);
+
+    const newDefault = path.join(tmpDir, ".deco", "meta.gen.json");
+    expect(fs.existsSync(newDefault)).toBe(true);
+    const meta = JSON.parse(fs.readFileSync(newDefault, "utf-8"));
+    expect(meta.manifest.blocks.sections).toHaveProperty("site/sections/Hero.tsx");
+  });
+
+  it("warns once to stderr naming both paths when the OLD default file exists and no --out is passed, but still writes the NEW default", () => {
+    const oldDefaultDir = path.join(tmpDir, "src", "server", "admin");
+    fs.mkdirSync(oldDefaultDir, { recursive: true });
+    fs.writeFileSync(path.join(oldDefaultDir, "meta.gen.json"), "{}");
+
+    const { code, stderr } = runGenerator(["--skip-apps"], { cwd: tmpDir });
+    expect(code).toBe(0);
+
+    expect(stderr).toContain("src/server/admin/meta.gen.json");
+    expect(stderr).toContain(".deco/meta.gen.json");
+    expect(stderr).toContain("Move the file and update its importers");
+
+    const newDefault = path.join(tmpDir, ".deco", "meta.gen.json");
+    expect(fs.existsSync(newDefault)).toBe(true);
+  });
+
+  it("does not warn when an explicit --out is passed, even if the OLD default file exists", () => {
+    const oldDefaultDir = path.join(tmpDir, "src", "server", "admin");
+    fs.mkdirSync(oldDefaultDir, { recursive: true });
+    fs.writeFileSync(path.join(oldDefaultDir, "meta.gen.json"), "{}");
+
+    const explicitOut = path.join(tmpDir, "custom", "meta.gen.json");
+    const { code, stderr } = runGenerator(["--skip-apps", "--out", explicitOut], { cwd: tmpDir });
+    expect(code).toBe(0);
+
+    expect(stderr).not.toContain("Generator default output moved");
+    expect(fs.existsSync(explicitOut)).toBe(true);
+  });
+});

package/scripts/generate-schema.ts

@@ -20,8 +20,12 @@ import { fileURLToPath } from "node:url";
  *   --loaders     Loaders directory  (default: "src/loaders")
  *   --apps        Apps directory     (default: "src/apps")
  *   --skip-apps   Skip app schema generation
- *   --out         Output file        (default: "src/server/admin/meta.gen.json")
+ *   --out         Output file        (default: ".deco/meta.gen.json")
  *   --platform    Platform name      (default: "cloudflare")
+ *
+ * If no `--out` is passed and the OLD default (src/server/admin/meta.gen.json)
+ * still exists on disk, a one-line legacy warning is printed to stderr and the
+ * NEW default is written anyway — see lib/legacyArtifact.ts.
  */
 import {
   type Symbol as MorphSymbol,
@@ -31,6 +35,8 @@ import {
   SyntaxKind,
   type Type,
 } from "ts-morph";
+import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
@@ -48,8 +54,14 @@ const SECTIONS_REL = arg("sections", "src/sections");
 const LOADERS_REL = arg("loaders", "src/loaders");
 const APPS_REL = arg("apps", "src/apps");
 const SKIP_APPS = argv.includes("--skip-apps");
-const OUT_REL = arg("out", "src/server/admin/meta.gen.json");
+const OUT_FILE_EXPLICIT = argv.includes("--out");
+const NEW_DEFAULT_OUT_REL = ".deco/meta.gen.json";
+const OLD_DEFAULT_OUT_REL = "src/server/admin/meta.gen.json";
+const OUT_REL = arg("out", NEW_DEFAULT_OUT_REL);
 const PLATFORM = arg("platform", "cloudflare");
+if (!OUT_FILE_EXPLICIT && fs.existsSync(path.resolve(process.cwd(), OLD_DEFAULT_OUT_REL))) {
+  warnLegacyArtifact(OLD_DEFAULT_OUT_REL, NEW_DEFAULT_OUT_REL);
+}
 
 // ---------------------------------------------------------------------------
 // Interfaces
@@ -72,6 +84,18 @@ function toBase64(str: string): string {
   return Buffer.from(str).toString("base64");
 }
 
+/**
+ * Definition IDs must be stable across machines: the raw ts-morph path is
+ * absolute (`file:///Users/<user>/...`), which made meta.gen.json differ
+ * per machine and destabilized the /live/_meta ETag. IDs are opaque to the
+ * admin — only internal $ref consistency matters — so relativize to root.
+ */
+export function definitionIdForPath(filePath: string, rootDir: string): string {
+  const cleaned = filePath.replace(/^file:\/+/, "/");
+  const rel = path.relative(rootDir, cleaned).replaceAll("\\", "/");
+  return toBase64(rel.startsWith("..") ? cleaned : rel);
+}
+
 /**
  * Map JSDoc tags to JSON Schema 7 keywords.
  * Supports all 20+ tags from deco-cx/deco.
@@ -734,6 +758,7 @@ function findTsxFiles(dir: string): string[] {
   const results: string[] = [];
   if (!fs.existsSync(dir)) return results;
   for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (isExcludedCodegenFile(entry.name)) continue;
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) results.push(...findTsxFiles(full));
     else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) results.push(full);
@@ -1141,7 +1166,7 @@ function generateMeta(): MetaResponse {
 
       const propCount = Object.keys(propsSchema.properties || {}).length;
 
-      const propsDefKey = toBase64(`file:///${filePath.replaceAll("\\", "/")}`) + "@Props";
+      const propsDefKey = definitionIdForPath(filePath, root) + "@Props";
       definitions[propsDefKey] = propsSchema;
 
       const sectionDefKey = toBase64(blockKey);
@@ -1232,7 +1257,7 @@ function generateMeta(): MetaResponse {
 
         const propCount = Object.keys(propsSchema.properties || {}).length;
 
-        const propsDefKey = toBase64(`file:///${filePath.replaceAll("\\", "/")}`) + "@Props";
+        const propsDefKey = definitionIdForPath(filePath, root) + "@Props";
         definitions[propsDefKey] = propsSchema;
 
         const appDefKey = toBase64(blockKey);

package/scripts/generate-sections.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Integration test for `generate-sections.ts`.
+ *
+ * Drives the script as a child process against a tmp sections-dir fixture,
+ * mirroring the pattern used by migrate-to-cf-observability.test.ts. The
+ * script has no `isMainModule()` guard (unlike generate-schema.ts) — it runs
+ * its filesystem walk and write on import — so it's exercised as a subprocess
+ * rather than imported directly.
+ *
+ * Verifies the operationally important behavior: a co-located test/spec/
+ * stories/gen file sitting next to a real section must never be walked into
+ * sectionMeta (the fila incident this generator's `walkDir` reproduced:
+ * `sections.test.ts` became a bogus section in a site's generated output).
+ */
+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 { pathToFileURL } from "node:url";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const SCRIPT = path.resolve(__dirname, "generate-sections.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("generate-sections walkDir exclusions", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-"));
+    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("excludes co-located test/spec/stories/gen files from the generated sectionMeta", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      `export const eager = true;\nexport default function Hero() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.test.tsx"),
+      `export const eager = true;\nexport default function HeroTest() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.stories.tsx"),
+      `export const eager = true;\nexport default function HeroStories() { return null; }\n`,
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "sections.gen.ts"),
+      `export const eager = true;\n`,
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated).toContain("site/sections/Hero.tsx");
+    expect(generated).not.toContain("Hero.test.tsx");
+    expect(generated).not.toContain("Hero.stories.tsx");
+    expect(generated).not.toContain("sections.gen.ts");
+  });
+});
+
+describe("generate-sections default output path (.deco/)", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-defaults-"));
+    sectionsDir = path.join(tmpDir, "src", "sections");
+    fs.mkdirSync(sectionsDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      "export const eager = true;\nexport default function Hero() { return null; }\n",
+    );
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("writes to .deco/sections.gen.ts when no --out-file flag is passed", () => {
+    const { code, stderr } = runGenerator([], { cwd: tmpDir });
+    expect(code).toBe(0);
+
+    const newDefault = path.join(tmpDir, ".deco", "sections.gen.ts");
+    expect(fs.existsSync(newDefault)).toBe(true);
+    expect(fs.readFileSync(newDefault, "utf-8")).toContain("site/sections/Hero.tsx");
+    // No legacy file present, so no warning is expected.
+    expect(stderr).not.toContain("Generator default output moved");
+  });
+
+  it("warns once to stderr naming both paths when the OLD default file exists and no --out-file is passed, but still writes the NEW default", () => {
+    const oldDefaultDir = path.join(tmpDir, "src", "server", "cms");
+    fs.mkdirSync(oldDefaultDir, { recursive: true });
+    fs.writeFileSync(path.join(oldDefaultDir, "sections.gen.ts"), "// stale\n");
+
+    const { code, stderr } = runGenerator([], { cwd: tmpDir });
+    expect(code).toBe(0);
+
+    expect(stderr).toContain("src/server/cms/sections.gen.ts");
+    expect(stderr).toContain(".deco/sections.gen.ts");
+    expect(stderr).toContain("Move the file and update its importers");
+
+    const newDefault = path.join(tmpDir, ".deco", "sections.gen.ts");
+    expect(fs.existsSync(newDefault)).toBe(true);
+    expect(fs.readFileSync(newDefault, "utf-8")).toContain("site/sections/Hero.tsx");
+  });
+
+  it("does not warn when an explicit --out-file is passed, even if the OLD default file exists", () => {
+    const oldDefaultDir = path.join(tmpDir, "src", "server", "cms");
+    fs.mkdirSync(oldDefaultDir, { recursive: true });
+    fs.writeFileSync(path.join(oldDefaultDir, "sections.gen.ts"), "// stale\n");
+
+    const explicitOut = path.join(tmpDir, "custom", "sections.gen.ts");
+    const { code, stderr } = runGenerator(["--out-file", explicitOut], { cwd: tmpDir });
+    expect(code).toBe(0);
+
+    expect(stderr).not.toContain("Generator default output moved");
+    expect(fs.existsSync(explicitOut)).toBe(true);
+  });
+});
+
+describe("generate-sections --registry", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-registry-"));
+    sectionsDir = path.join(tmpDir, "sections");
+    outFile = path.join(tmpDir, "out", "sections.gen.ts");
+    fs.mkdirSync(path.join(sectionsDir, "Nested"), { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  function expectedImportPath(filePath: string): string {
+    let rel = path.relative(path.dirname(outFile), filePath).replace(/\\/g, "/");
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    return rel.replace(/\.tsx?$/, "");
+  }
+
+  it("emits sectionImports keyed glob-style with relative dynamic imports, built from all scanned section files (not just convention-carrying ones)", () => {
+    const heroPath = path.join(sectionsDir, "Hero.tsx");
+    const promoPath = path.join(sectionsDir, "Nested", "Promo.tsx");
+    fs.writeFileSync(
+      heroPath,
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+    // No convention exports — regression guard: without --registry this file
+    // never makes it into `entries`, so the registry must be built from the
+    // raw `sectionFiles` walk, not from `entries`.
+    fs.writeFileSync(
+      promoPath,
+      "export default function Promo() { return null }\n",
+    );
+
+    const { code } = runGenerator([
+      "--sections-dir", sectionsDir,
+      "--out-file", outFile,
+      "--registry",
+    ]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated).toContain("export const sectionImports");
+    expect(generated).toContain(
+      `"./sections/Hero.tsx": () => import("${expectedImportPath(heroPath)}")`,
+    );
+    expect(generated).toContain(
+      `"./sections/Nested/Promo.tsx": () => import("${expectedImportPath(promoPath)}")`,
+    );
+  });
+
+  it("does not emit sectionImports without the --registry flag", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "Hero.tsx"),
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+    fs.writeFileSync(
+      path.join(sectionsDir, "Nested", "Promo.tsx"),
+      "export default function Promo() { return null }\n",
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    expect(generated).not.toContain("sectionImports");
+  });
+
+  it("emits a doc comment that does not self-terminate early, and the resulting file is importable (regression: a literal `**/` inside the emitted /** */ comment used to close it prematurely, leaving prose as bare statements and making every --registry output invalid TypeScript)", () => {
+    const heroPath = path.join(sectionsDir, "Hero.tsx");
+    fs.writeFileSync(
+      heroPath,
+      "export const sync = true\nexport default function Hero() { return null }\n",
+    );
+
+    const { code } = runGenerator([
+      "--sections-dir", sectionsDir,
+      "--out-file", outFile,
+      "--registry",
+    ]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+
+    // Pin the regression directly: the doc comment's body (everything
+    // between the opening `/**` and its own closing `*/`) must contain
+    // exactly one `*/` — the intended closing marker itself, at the very
+    // end. A premature `*/` embedded in the prose (e.g. from a literal
+    // `**/*.tsx` glob pattern) would close the block comment early and
+    // leave the rest of the doc text as bare top-level statements.
+    const docCommentStart = generated.indexOf("/**\n * Lazy section registry");
+    const exportStart = generated.indexOf("export const sectionImports");
+    expect(docCommentStart).toBeGreaterThan(-1);
+    expect(exportStart).toBeGreaterThan(docCommentStart);
+    const docComment = generated.slice(docCommentStart + "/**".length, exportStart);
+    const closeMarkerCount = (docComment.match(/\*\//g) ?? []).length;
+    expect(closeMarkerCount).toBe(1);
+    expect(docComment.trimEnd().endsWith("*/")).toBe(true);
+
+    // Strongest available check: actually import the generated file through
+    // tsx (esbuild) and confirm it parses/executes as valid TS/ESM and
+    // exports `sectionImports`. A premature `*/` would leave trailing prose
+    // as bare top-level statements, which fails to parse. `tsx -e` evaluates
+    // its argument as CommonJS (named exports of a dynamic `import()` come
+    // back CJS-interop-wrapped), so write a real `.mjs` file instead and run
+    // that — mirrors the check used to hand-verify this fix.
+    const checkerFile = path.join(tmpDir, "check-import.mjs");
+    fs.writeFileSync(
+      checkerFile,
+      [
+        `import { pathToFileURL } from "node:url";`,
+        `const m = await import(${JSON.stringify(pathToFileURL(outFile).href)});`,
+        `if (typeof m.sectionImports !== "object" || m.sectionImports === null) {`,
+        `  throw new Error("sectionImports missing or not an object");`,
+        `}`,
+      ].join("\n"),
+    );
+
+    const importResult = cp.spawnSync("npx", ["tsx", checkerFile], { encoding: "utf8" });
+    expect(importResult.status, importResult.stderr).toBe(0);
+  }, 30_000);
+});

package/scripts/generate-sections.ts

@@ -16,10 +16,22 @@
  *
  * CLI:
  *   --sections-dir  override input  (default: src/sections)
- *   --out-file      override output (default: src/server/cms/sections.gen.ts)
+ *   --out-file      override output (default: .deco/sections.gen.ts)
+ *   --registry      also emit `sectionImports` — a lazy section-import map
+ *                   keyed glob-style (`./sections/...`), the Next.js/webpack
+ *                   equivalent of Vite's `import.meta.glob("./sections/**\/*.tsx")`.
+ *                   Built from every scanned section file, not just the ones
+ *                   carrying convention exports. Off by default so existing
+ *                   Vite sites regenerating sections.gen.ts in CI see zero diff.
+ *
+ * If no `--out-file` is passed and the OLD default (src/server/cms/sections.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.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -28,7 +40,14 @@ function arg(name: string, fallback: string): string {
 }
 
 const sectionsDir = path.resolve(process.cwd(), arg("sections-dir", "src/sections"));
-const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/sections.gen.ts"));
+const OUT_FILE_EXPLICIT = args.includes("--out-file");
+const NEW_DEFAULT_OUT_FILE = ".deco/sections.gen.ts";
+const OLD_DEFAULT_OUT_FILE = "src/server/cms/sections.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);
+}
+const EMIT_REGISTRY = args.includes("--registry");
 
 interface SectionMeta {
   eager?: boolean;
@@ -92,7 +111,10 @@ function walkDir(dir: string, base: string = dir): string[] {
     const fullPath = path.join(dir, entry.name);
     if (entry.isDirectory()) {
       results.push(...walkDir(fullPath, base));
-    } else if (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) {
+    } else if (
+      (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) &&
+      !isExcludedCodegenFile(entry.name)
+    ) {
       results.push(fullPath);
     }
   }
@@ -223,6 +245,25 @@ if (allFallbacks.length > 0) {
 }
 lines.push("");
 
+// Lazy section-import registry — opt-in via --registry, built from every
+// scanned section file (not just convention-carrying `entries`).
+if (EMIT_REGISTRY) {
+  lines.push("");
+  lines.push("/**");
+  lines.push(" * Lazy section registry — the Next.js/webpack equivalent of Vite's");
+  lines.push(" * `import.meta.glob` scan over every file under ./sections, recursively.");
+  lines.push(" * Keys use the glob-style `./sections/...` form so this map drops");
+  lines.push(" * straight into `createSiteSetup({ sections })` / `createNextSetup({ sections })`.");
+  lines.push(" */");
+  lines.push("export const sectionImports: Record<string, () => Promise<any>> = {");
+  for (const filePath of sectionFiles) {
+    const rel = path.relative(sectionsDir, filePath).replace(/\\/g, "/");
+    const importPath = relativeImportPath(outFile, filePath);
+    lines.push(`  "./sections/${rel}": () => import("${importPath}"),`);
+  }
+  lines.push("};");
+}
+
 fs.mkdirSync(path.dirname(outFile), { recursive: true });
 fs.writeFileSync(outFile, lines.join("\n"));
 

package/scripts/lib/codegenExclusions.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { isExcludedCodegenFile } from "./codegenExclusions";
+
+describe("isExcludedCodegenFile", () => {
+  it.each([
+    "Hero.test.tsx",
+    "Hero.test.ts",
+    "Hero.spec.tsx",
+    "Hero.stories.tsx",
+    "sections.gen.ts",
+    "meta.gen.json",
+  ])("excludes %s", (name) => {
+    expect(isExcludedCodegenFile(name)).toBe(true);
+  });
+
+  it.each(["Hero.tsx", "Product/SearchResult.tsx", "testimonials.tsx", "generic.ts"])(
+    "keeps %s",
+    (name) => {
+      expect(isExcludedCodegenFile(name)).toBe(false);
+    },
+  );
+});

package/scripts/lib/codegenExclusions.ts

@@ -0,0 +1,11 @@
+/**
+ * Files the codegen scanners must never treat as section/loader sources.
+ * `generate-schema.ts` once emitted a site's co-located test file as a
+ * section block (it scans every .ts/.tsx under the sections dir), so both
+ * generators route their directory walks through this predicate.
+ */
+const EXCLUDED_SUFFIX_RE = /\.(test|spec|stories|gen)\.(ts|tsx|js|jsx|json)$/;
+
+export function isExcludedCodegenFile(fileName: string): boolean {
+  return EXCLUDED_SUFFIX_RE.test(fileName);
+}

package/scripts/lib/legacyArtifact.ts

@@ -0,0 +1,20 @@
+/**
+ * Generator default output paths flipped from `src/server/{cms,admin}/` to
+ * `.deco/` (framework artifacts live in the framework's folder, not mixed
+ * into app source). Sites that never pass an explicit `--out`/`--out-file`
+ * flag pick up the new default silently — except when the OLD default file
+ * is still sitting on disk, which almost always means something (an
+ * importer, a `.gitignore` entry, a stale CI cache check) still points at
+ * it. In that case we warn once, to stderr, and then write to the NEW
+ * default anyway: the artifact is regenerated code, so there's no reason to
+ * block the run — the warning is just a nudge to go clean up the stale file
+ * and its importers.
+ *
+ * An explicit flag means the caller made a deliberate choice about where
+ * output goes; it gets no warning and no guard.
+ */
+export function warnLegacyArtifact(oldPath: string, newPath: string): void {
+  console.warn(
+    `[deco] Generator default output moved: ${oldPath} -> ${newPath}. Move the file and update its importers.`,
+  );
+}

package/scripts/migrate/templates/commerce-loaders.ts

@@ -64,7 +64,7 @@ export function generateCommerceLoaders(ctx: MigrationContext): string {
     }
 
     // Always import siteLoaders — the generate:loaders script creates this file
-    lines.push(`import { siteLoaders } from "../server/cms/loaders.gen";`);
+    lines.push(`import { siteLoaders } from "../../.deco/loaders.gen";`);
     lines.push(``);
 
     lines.push(`const DOMAIN_RE = /;\\s*domain=[^;]*/gi;`);

package/scripts/migrate/templates/knip-config.ts

@@ -12,7 +12,6 @@ const config: KnipConfig = {
   project: ["src/**/*.{ts,tsx}"],
   ignore: [
     "src/server/invoke.gen.ts",
-    "src/server/cms/blocks.gen.ts",
     "src/routeTree.gen.ts",
   ],
   ignoreDependencies: [

package/scripts/migrate/templates/setup.ts

@@ -99,8 +99,8 @@ import { setInvokeLoaders } from "@decocms/start/admin";${isVtex ? `
 import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
 import { initVtexFromBlocks, setVtexFetch } from "@decocms/apps/vtex";` : ""}${hasLocationMatcher ? `
 import { registerLocationMatcher } from "./matchers/location";` : ""}
-import { blocks as generatedBlocks } from "./server/cms/blocks.gen";
-import { sectionMeta, syncComponents, loadingFallbacks } from "./server/cms/sections.gen";
+import { blocks as generatedBlocks } from "../.deco/blocks.gen";
+import { sectionMeta, syncComponents, loadingFallbacks } from "../.deco/sections.gen";
 import { PreviewProviders } from "@decocms/start/hooks";
 // @ts-ignore Vite ?url import
 import appCss from "./styles/app.css?url";
@@ -112,7 +112,7 @@ import "./setup/section-loaders";
 createSiteSetup({
   sections: import.meta.glob("./sections/**/*.tsx") as Record<string, () => Promise<any>>,
   blocks: generatedBlocks,
-  meta: () => import("./server/admin/meta.gen.json").then((m) => m.default),
+  meta: () => import("../.deco/meta.gen.json").then((m) => m.default),
   css: appCss,
   fonts: [${fontEntries}],
   productionOrigins: [