@decocms/blocks-cli 7.4.0 → 7.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.4.0",
+  "version": "7.5.1",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -34,9 +34,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.4.0",
+    "@decocms/blocks": "7.5.1",
     "ts-morph": "^27.0.0",
-    "tsx": "^4.19.0"
+    "tsx": "^4.22.5"
   },
   "devDependencies": {
     "knip": "^5.86.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,5 +1,9 @@
+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 { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   WIDGET_TYPE_FORMATS,
   applyWidgetFormat,
@@ -93,5 +97,97 @@ describe("typeToJsonSchema with an unresolvable widget alias import", () => {
       type: "string",
       format: "color",
     });
+  }, 30_000);
+});
+
+// ---------------------------------------------------------------------------
+// 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");
+  }, 30_000);
+
+  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);
+  }, 30_000);
+
+  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);
+  }, 30_000);
 });

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,
@@ -32,6 +36,7 @@ import {
   type Type,
 } from "ts-morph";
 import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
@@ -49,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

package/scripts/generate-sections.test.ts

@@ -21,8 +21,11 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 const SCRIPT = path.resolve(__dirname, "generate-sections.ts");
 
-function runGenerator(args: string[]): { stdout: string; stderr: string; code: number } {
-  const r = cp.spawnSync("npx", ["tsx", SCRIPT, ...args], { encoding: "utf8" });
+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 };
 }
 
@@ -68,7 +71,67 @@ describe("generate-sections walkDir exclusions", () => {
     expect(generated).not.toContain("Hero.test.tsx");
     expect(generated).not.toContain("Hero.stories.tsx");
     expect(generated).not.toContain("sections.gen.ts");
+  }, 30_000);
+});
+
+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");
+  }, 30_000);
+
+  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");
+  }, 30_000);
+
+  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);
+  }, 30_000);
 });
 
 describe("generate-sections --registry", () => {
@@ -123,7 +186,7 @@ describe("generate-sections --registry", () => {
     expect(generated).toContain(
       `"./sections/Nested/Promo.tsx": () => import("${expectedImportPath(promoPath)}")`,
     );
-  });
+  }, 30_000);
 
   it("does not emit sectionImports without the --registry flag", () => {
     fs.writeFileSync(
@@ -140,7 +203,7 @@ describe("generate-sections --registry", () => {
 
     const generated = fs.readFileSync(outFile, "utf-8");
     expect(generated).not.toContain("sectionImports");
-  });
+  }, 30_000);
 
   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");

package/scripts/generate-sections.ts

@@ -16,17 +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 {
@@ -35,7 +40,13 @@ 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 {

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: [