@decocms/blocks-cli 7.9.0 → 7.11.0

package/package.json

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

package/scripts/generate-app-schemas.test.ts

@@ -0,0 +1,238 @@
+/**
+ * Tests for generate-app-schemas.ts — the build-time extractor that gives app
+ * packages (apps-vtex, …) real loader/action props schemas in the admin meta,
+ * replacing the `__resolveType`-only stubs auto-registered at runtime.
+ *
+ * Drives generateAppSchemas() directly (the script is import-safe, guarded by
+ * isMainModule()) against a tmp fixture app package covering both key
+ * universes: file-path loader keys and manifest-flattened module keys.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import {
+  type AppSchemasResult,
+  generateAppSchemas,
+  renderSchemasModule,
+} from "./generate-app-schemas";
+
+let tmpDir: string;
+let result: AppSchemasResult;
+
+function write(rel: string, content: string) {
+  const full = path.join(tmpDir, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content);
+}
+
+beforeAll(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-app-schemas-"));
+
+  write(
+    "package.json",
+    JSON.stringify({ name: "@decocms/apps-fixture", version: "0.0.0", type: "module" }),
+  );
+  write(
+    "tsconfig.json",
+    JSON.stringify({
+      compilerOptions: {
+        target: "ES2022",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        lib: ["ES2022", "DOM"],
+        strict: true,
+      },
+    }),
+  );
+
+  // File-path-keyed loader with a Props interface + JSDoc metadata.
+  write(
+    "src/loaders/detail/page.ts",
+    `export interface Props {
+  /** @title Slug */
+  slug?: string;
+  /** @description How many variants to fetch */
+  variantCount: number;
+}
+export default async function loader(props: Props): Promise<string | null> {
+  return props.slug ?? null;
+}
+`,
+  );
+
+  // Loader that takes no input at all.
+  write(
+    "src/loaders/noProps.ts",
+    `export default async function loader(): Promise<number> {
+  return 1;
+}
+`,
+  );
+
+  // Loader whose props are untyped — input exists but can't be described.
+  write(
+    "src/loaders/anyProps.ts",
+    `export default async function loader(props: any): Promise<unknown> {
+  return props;
+}
+`,
+  );
+
+  // Runtime-injected platform types (url: URL) must be hidden, not expanded,
+  // and must not stay required.
+  write(
+    "src/loaders/listing.ts",
+    `export interface Props {
+  url: URL;
+  sort?: "asc" | "desc";
+  count: number;
+}
+export default async function loader(props: Props): Promise<unknown[]> {
+  return [props];
+}
+`,
+  );
+
+  // Barrel — must not become a loader key.
+  write("src/loaders/index.ts", `export { default as page } from "./detail/page";\n`);
+
+  // Manifest module with named exports → flattened keys.
+  write(
+    "src/actions/cart.ts",
+    `export interface AddItemProps {
+  id: string;
+  qty?: number;
+}
+/** @title Add item to cart */
+export async function addItem(props: AddItemProps): Promise<string> {
+  return props.id;
+}
+export async function clearCart(): Promise<void> {}
+export type IgnoredType = { nope: true };
+export const IGNORED_CONST = 42;
+`,
+  );
+  write(
+    "src/loaders/things.ts",
+    `export async function listThings(props: { filter?: string }): Promise<string[]> {
+  return [props.filter ?? ""];
+}
+export default async function defaultThings(props: { limit: number }): Promise<string[]> {
+  return [String(props.limit)];
+}
+`,
+  );
+  write(
+    "src/manifest.gen.ts",
+    `import * as actions_cart from "./actions/cart";
+import * as loaders_things from "./loaders/things";
+
+const manifest = {
+\tname: "fixture",
+\tloaders: {
+\t\t"fixture/loaders/things": loaders_things,
+\t},
+\tactions: {
+\t\t"fixture/actions/cart": actions_cart,
+\t},
+\tsections: {},
+} as const;
+
+export default manifest;
+`,
+  );
+
+  result = generateAppSchemas(tmpDir, "fixture");
+}, 120_000);
+
+afterAll(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+describe("file-path-keyed loaders", () => {
+  it("emits real props from the Props interface, under both bare and .ts keys", () => {
+    const withTs = result.loaders["fixture/loaders/detail/page.ts"];
+    const bare = result.loaders["fixture/loaders/detail/page"];
+    expect(withTs).toBeDefined();
+    expect(bare).toBe(withTs);
+
+    expect(withTs.properties?.slug).toMatchObject({ type: "string", title: "Slug" });
+    expect(withTs.properties?.variantCount).toMatchObject({
+      type: "number",
+      description: "How many variants to fetch",
+    });
+    expect(withTs.required).toEqual(["variantCount"]);
+    expect(withTs.additionalProperties).toBeUndefined();
+  });
+
+  it("emits an empty-props schema WITHOUT additionalProperties for no-input loaders", () => {
+    const schema = result.loaders["fixture/loaders/noProps.ts"];
+    expect(schema).toEqual({ type: "object", properties: {} });
+  });
+
+  it("falls back to the JSON-editor shape (additionalProperties) for untyped props", () => {
+    const schema = result.loaders["fixture/loaders/anyProps.ts"];
+    expect(schema).toEqual({ type: "object", additionalProperties: true });
+  });
+
+  it("hides runtime-injected platform types and drops them from required", () => {
+    const schema = result.loaders["fixture/loaders/listing.ts"];
+    expect(schema.properties?.url).toMatchObject({ type: "object", hide: "true" });
+    expect(schema.properties?.url.properties).toBeUndefined();
+    expect(schema.properties?.sort).toMatchObject({ type: "string", enum: ["asc", "desc"] });
+    expect(schema.required).toEqual(["count"]);
+  });
+
+  it("skips barrel index files", () => {
+    expect(result.loaders["fixture/loaders/index.ts"]).toBeUndefined();
+    expect(result.loaders["fixture/loaders/index"]).toBeUndefined();
+  });
+});
+
+describe("manifest-flattened keys", () => {
+  it("flattens named function exports to <moduleKey>/<fnName>", () => {
+    const addItem = result.actions["fixture/actions/cart/addItem"];
+    expect(addItem).toBeDefined();
+    expect(result.actions["fixture/actions/cart/addItem.ts"]).toBe(addItem);
+    expect(addItem.title).toBe("Add item to cart");
+    expect(addItem.properties?.id).toMatchObject({ type: "string" });
+    expect(addItem.required).toEqual(["id"]);
+  });
+
+  it("emits no-props actions without additionalProperties", () => {
+    expect(result.actions["fixture/actions/cart/clearCart"]).toEqual({
+      type: "object",
+      properties: {},
+    });
+  });
+
+  it("ignores type and constant exports", () => {
+    const keys = Object.keys(result.actions);
+    expect(keys.filter((k) => k.includes("IgnoredType"))).toEqual([]);
+    expect(keys.filter((k) => k.includes("IGNORED_CONST"))).toEqual([]);
+  });
+
+  it("registers a module's default export at the moduleKey itself", () => {
+    const def = result.loaders["fixture/loaders/things"];
+    expect(def.properties?.limit).toMatchObject({ type: "number" });
+    expect(result.loaders["fixture/loaders/things/listThings"].properties?.filter).toMatchObject({
+      type: "string",
+    });
+  });
+});
+
+describe("renderSchemasModule", () => {
+  it("emits a typed module with deduplicated schema consts shared across alias keys", () => {
+    const out = renderSchemasModule(result);
+    expect(out).toContain('import type { BlockPropsSchema } from "@decocms/blocks/cms/client";');
+    expect(out).toContain("export const loaderSchemas: Record<string, BlockPropsSchema>");
+    expect(out).toContain("export const actionSchemas: Record<string, BlockPropsSchema>");
+
+    // Alias keys must point at the same const (dedup by content).
+    const bare = out.match(/"fixture\/loaders\/detail\/page": (s\d+),/)?.[1];
+    const withTs = out.match(/"fixture\/loaders\/detail\/page\.ts": (s\d+),/)?.[1];
+    expect(bare).toBeDefined();
+    expect(bare).toBe(withTs);
+  });
+});

package/scripts/generate-app-schemas.ts

@@ -0,0 +1,394 @@
+#!/usr/bin/env tsx
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * App Schema Generator — real loader/action props schemas for app packages.
+ *
+ * The admin builds a block's props form from `/deco/meta`'s
+ * `schema.definitions[b64(key)]`. Site loaders get real schemas from
+ * generate-schema.ts, but app loaders/actions (@decocms/apps-vtex, ...) were
+ * only ever auto-registered as `__resolveType`-only stubs by
+ * registerCommerceLoaders() — the admin couldn't render any form for them.
+ *
+ * This script runs at app-package build time (Props are TS types, erased at
+ * runtime — this CANNOT run in the site) and emits a committed
+ * `src/schemas.gen.ts` artifact mapping every CMS-reachable key to its real
+ * props schema. The app's entrypoints feed it to registerAppSchemas()
+ * (@decocms/blocks/cms), which beats the runtime stubs by key.
+ *
+ * Two key universes are covered, matching how keys reach the CMS at runtime:
+ *
+ * 1. File-path keys — `<ns>/loaders/<relpath>.ts` (+ bare alias): what
+ *    commerceLoaders maps and site decofiles reference. Every file under
+ *    src/loaders/ with a default export.
+ * 2. Manifest-flattened keys — what setupApps() registers from
+ *    src/manifest.gen.ts: `<moduleKey>` for a module's default export,
+ *    `<moduleKey>/<fnName>` for named function exports (+ `.ts` siblings).
+ *    e.g. "vtex/loaders/legacy" × `productListingPage` →
+ *    "vtex/loaders/legacy/productListingPage". Covers actions too.
+ *
+ * Usage (from the app package root):
+ *   bun ../blocks-cli/scripts/generate-app-schemas.ts [options]
+ *
+ * Options:
+ *   --namespace   CMS namespace (default: derived from package.json name,
+ *                 "@decocms/apps-<ns>" → "<ns>")
+ *   --pkg         App package root (default: cwd)
+ *   --out         Output file (default: src/schemas.gen.ts, relative to --pkg)
+ */
+import { type Symbol as MorphSymbol, Node, Project, type SourceFile, type Type } from "ts-morph";
+import { getJsDocTags, typeToJsonSchema } from "./generate-schema";
+import { isExcludedCodegenFile } from "./lib/codegenExclusions";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Mirrors BlockPropsSchema in @decocms/blocks/cms — kept structural so this
+ * script has no runtime dependency on the blocks package. */
+export interface AppBlockPropsSchema {
+  type?: "object";
+  title?: string;
+  description?: string;
+  properties?: Record<string, any>;
+  required?: string[];
+  additionalProperties?: boolean;
+  /** Any other JSON Schema keyword or JSDoc passthrough tag (nullable, …). */
+  [keyword: string]: any;
+}
+
+export interface AppSchemasResult {
+  loaders: Record<string, AppBlockPropsSchema>;
+  actions: Record<string, AppBlockPropsSchema>;
+}
+
+// ---------------------------------------------------------------------------
+// Schema extraction helpers
+// ---------------------------------------------------------------------------
+
+/** Props whose declared type is any/unknown — the block DOES take input, we
+ * just can't describe it. The stub shape keeps the admin's JSON editor. */
+const UNKNOWN_PROPS: AppBlockPropsSchema = { type: "object", additionalProperties: true };
+/** The block takes no input at all. Deliberately WITHOUT additionalProperties
+ * so the admin can say "takes no input". */
+const NO_PROPS: AppBlockPropsSchema = { type: "object", properties: {} };
+
+/**
+ * Normalize whatever typeToJsonSchema produced into a props-object schema.
+ * Handlers are invoked with a single props object; a first parameter that
+ * isn't object-shaped (e.g. `getCategoryTree(levels: number)`) can't be
+ * described as a props form — fall back to the JSON-editor shape.
+ */
+function toPropsSchema(schema: any): AppBlockPropsSchema {
+  if (!schema || typeof schema !== "object") return UNKNOWN_PROPS;
+  // any/unknown → {} from typeToJsonSchema
+  if (Object.keys(schema).length === 0) return UNKNOWN_PROPS;
+  if (schema.type === "object" && schema.properties) return schema;
+  // Record<string, T> → { type: "object", additionalProperties: <T> }
+  if (schema.type === "object" && schema.additionalProperties !== undefined) {
+    return { type: "object", additionalProperties: true };
+  }
+  if (schema.type === "object") return { ...schema, properties: schema.properties ?? {} };
+  return UNKNOWN_PROPS;
+}
+
+/** Schema for a function's first parameter (a loader/action handler). */
+function functionInputSchema(fnType: Type, location: Node): AppBlockPropsSchema | null {
+  const callSigs = fnType.getCallSignatures();
+  if (callSigs.length === 0) return null;
+  const params = callSigs[0].getParameters();
+  if (params.length === 0) return NO_PROPS;
+  const paramType = params[0].getTypeAtLocation(location);
+  if (paramType.isAny() || paramType.isUnknown()) return UNKNOWN_PROPS;
+  return toPropsSchema(typeToJsonSchema(paramType));
+}
+
+/** Apply a symbol's JSDoc @title (slash-free only) and description. */
+function applyDocMeta(schema: AppBlockPropsSchema, symbol: MorphSymbol): AppBlockPropsSchema {
+  const tags = getJsDocTags(symbol);
+  const title = tags.title && !tags.title.includes("/") ? tags.title : undefined;
+  const description = tags.description;
+  if (!title && !description) return schema;
+  return {
+    ...(title ? { title } : {}),
+    ...(description ? { description } : {}),
+    ...schema,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Discovery 1: file-path-keyed loaders (src/loaders/**)
+// ---------------------------------------------------------------------------
+
+function walkTsFiles(dir: string): string[] {
+  const results: string[] = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "__tests__" || entry.name === "__test__") continue;
+      results.push(...walkTsFiles(full));
+    } else if (
+      !isExcludedCodegenFile(entry.name) &&
+      (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx")) &&
+      entry.name !== "index.ts" &&
+      !entry.name.startsWith("_")
+    ) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+function extractFileLoaderSchema(sourceFile: SourceFile): AppBlockPropsSchema | null {
+  const defaultSym = sourceFile.getDefaultExportSymbol();
+  if (!defaultSym) return null; // barrel/utility module, not a loader file
+
+  // Same extraction order as generate-schema.ts's app-loaders pass: a named
+  // Props interface/alias wins over the default export's first parameter.
+  let schema: any = null;
+  const propsInterface = sourceFile.getInterface("Props");
+  if (propsInterface) schema = typeToJsonSchema(propsInterface.getType());
+
+  if (!schema) {
+    const propsAlias = sourceFile.getTypeAlias("Props");
+    if (propsAlias) schema = typeToJsonSchema(propsAlias.getType());
+  }
+
+  if (schema) return applyDocMeta(toPropsSchema(schema), defaultSym);
+
+  const fnSchema = functionInputSchema(defaultSym.getTypeAtLocation(sourceFile), sourceFile);
+  return fnSchema ? applyDocMeta(fnSchema, defaultSym) : NO_PROPS;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery 2: manifest-flattened keys (src/manifest.gen.ts)
+// ---------------------------------------------------------------------------
+
+/** moduleKey → absolute module file path, per manifest category. */
+function parseManifestModules(manifestFile: SourceFile): {
+  loaders: Map<string, string>;
+  actions: Map<string, string>;
+} {
+  const result = { loaders: new Map<string, string>(), actions: new Map<string, string>() };
+
+  // identifier → module specifier, from `import * as loaders_x from "./loaders/x"`
+  const importMap = new Map<string, string>();
+  for (const imp of manifestFile.getImportDeclarations()) {
+    const ns = imp.getNamespaceImport();
+    if (ns) importMap.set(ns.getText(), imp.getModuleSpecifierValue());
+  }
+
+  const manifestVar = manifestFile.getVariableDeclaration("manifest");
+  let init = manifestVar?.getInitializer();
+  while (init && Node.isAsExpression(init)) init = init.getExpression();
+  if (!init || !Node.isObjectLiteralExpression(init)) return result;
+
+  const manifestDir = path.dirname(manifestFile.getFilePath());
+  for (const category of ["loaders", "actions"] as const) {
+    const prop = init.getProperty(category);
+    if (!prop || !Node.isPropertyAssignment(prop)) continue;
+    const value = prop.getInitializer();
+    if (!value || !Node.isObjectLiteralExpression(value)) continue;
+
+    for (const entry of value.getProperties()) {
+      if (!Node.isPropertyAssignment(entry)) continue;
+      const keyNode = entry.getNameNode();
+      const moduleKey = Node.isStringLiteral(keyNode) ? keyNode.getLiteralValue() : entry.getName();
+      const ident = entry.getInitializer()?.getText();
+      const spec = ident ? importMap.get(ident) : undefined;
+      if (!spec?.startsWith(".")) continue;
+
+      const base = path.resolve(manifestDir, spec);
+      for (const candidate of [base, `${base}.ts`, `${base}.tsx`, path.join(base, "index.ts")]) {
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+          result[category].set(moduleKey, candidate);
+          break;
+        }
+      }
+    }
+  }
+  return result;
+}
+
+/** Flatten a manifest module's function exports, mirroring setupApps():
+ * default → moduleKey; named fn → `${moduleKey}/${fnName}`. */
+function flattenModuleSchemas(
+  moduleKey: string,
+  sourceFile: SourceFile,
+  into: Record<string, AppBlockPropsSchema>,
+) {
+  for (const sym of sourceFile.getExportSymbols()) {
+    const name = sym.getName();
+    const fnType = sym.getTypeAtLocation(sourceFile);
+    const schema = functionInputSchema(fnType, sourceFile);
+    if (!schema) continue; // type/constant export, not a handler
+
+    const key = name === "default" ? moduleKey : `${moduleKey}/${name}`;
+    into[key] = applyDocMeta(schema, sym);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main generation
+// ---------------------------------------------------------------------------
+
+/** Add the `.ts` sibling for every bare key and vice versa, both pointing at
+ * the same schema object — mirrors runtime alias registration. */
+function withKeyAliases(
+  schemas: Record<string, AppBlockPropsSchema>,
+): Record<string, AppBlockPropsSchema> {
+  const out: Record<string, AppBlockPropsSchema> = {};
+  for (const [key, schema] of Object.entries(schemas)) {
+    const bare = key.endsWith(".ts") ? key.slice(0, -3) : key;
+    // Bare-key entry wins ties with a .ts entry for the same block — both
+    // describe the same file, so any difference is extraction noise.
+    out[bare] = out[bare] ?? schema;
+    out[`${bare}.ts`] = out[`${bare}.ts`] ?? schema;
+  }
+  return out;
+}
+
+export function generateAppSchemas(pkgDir: string, namespace: string): AppSchemasResult {
+  const project = new Project({
+    tsConfigFilePath: path.join(pkgDir, "tsconfig.json"),
+    skipAddingFilesFromTsConfig: true,
+  });
+
+  const loaders: Record<string, AppBlockPropsSchema> = {};
+  const actions: Record<string, AppBlockPropsSchema> = {};
+
+  // Manifest-flattened keys first; file-path keys second so the more
+  // path-accurate extraction wins any (same-file) collision.
+  const manifestPath = path.join(pkgDir, "src", "manifest.gen.ts");
+  if (fs.existsSync(manifestPath)) {
+    const manifestFile = project.addSourceFileAtPath(manifestPath);
+    const modules = parseManifestModules(manifestFile);
+    for (const [category, into] of [
+      ["loaders", loaders],
+      ["actions", actions],
+    ] as const) {
+      for (const [moduleKey, filePath] of modules[category]) {
+        try {
+          flattenModuleSchemas(moduleKey, project.addSourceFileAtPath(filePath), into);
+        } catch (e) {
+          console.warn(`  ✗ manifest module ${moduleKey}: ${(e as Error).message}`);
+        }
+      }
+    }
+  }
+
+  const loadersDir = path.join(pkgDir, "src", "loaders");
+  for (const filePath of walkTsFiles(loadersDir)) {
+    const rel = path.relative(loadersDir, filePath).replaceAll("\\", "/");
+    const cmsKey = `${namespace}/loaders/${rel}`;
+    try {
+      const schema = extractFileLoaderSchema(project.addSourceFileAtPath(filePath));
+      if (schema) loaders[cmsKey] = schema;
+    } catch (e) {
+      console.warn(`  ✗ loader ${cmsKey}: ${(e as Error).message}`);
+    }
+  }
+
+  return {
+    loaders: withKeyAliases(loaders),
+    actions: withKeyAliases(actions),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Module rendering
+// ---------------------------------------------------------------------------
+
+/** Render the schemas.gen.ts module. Schemas are deduplicated: each unique
+ * schema is emitted once and shared by all keys aliasing it. */
+export function renderSchemasModule(result: AppSchemasResult): string {
+  const constByJson = new Map<string, string>();
+  const constDecls: string[] = [];
+
+  const constFor = (schema: AppBlockPropsSchema): string => {
+    const json = JSON.stringify(schema);
+    let name = constByJson.get(json);
+    if (!name) {
+      name = `s${constByJson.size}`;
+      constByJson.set(json, name);
+      constDecls.push(`const ${name}: BlockPropsSchema = ${JSON.stringify(schema, null, "\t")};`);
+    }
+    return name;
+  };
+
+  const renderRecord = (schemas: Record<string, AppBlockPropsSchema>): string => {
+    const entries = Object.keys(schemas)
+      .sort()
+      .map((key) => `\t${JSON.stringify(key)}: ${constFor(schemas[key])},`);
+    return `{\n${entries.join("\n")}\n}`;
+  };
+
+  // Records must render before constDecls is final, but constDecls prints first.
+  const loadersRecord = renderRecord(result.loaders);
+  const actionsRecord = renderRecord(result.actions);
+
+  return [
+    "// AUTO-GENERATED by @decocms/blocks-cli scripts/generate-app-schemas.ts — DO NOT EDIT",
+    "// Regenerate from this package's root: bun run generate:schemas",
+    "//",
+    "// Real props schemas for this app's loaders/actions, keyed by CMS key",
+    "// (both bare and `.ts` forms). Registered into the admin meta via",
+    "// registerAppSchemas() so the Studio can render real props forms instead",
+    "// of the __resolveType-only stubs from registerCommerceLoaders().",
+    'import type { BlockPropsSchema } from "@decocms/blocks/cms/client";',
+    "",
+    ...constDecls,
+    "",
+    `export const loaderSchemas: Record<string, BlockPropsSchema> = ${loadersRecord};`,
+    "",
+    `export const actionSchemas: Record<string, BlockPropsSchema> = ${actionsRecord};`,
+    "",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+function isMainModule(): boolean {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fs.realpathSync(path.resolve(entry)) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  const argv = process.argv.slice(2);
+  const arg = (name: string, fallback: string): string => {
+    const idx = argv.indexOf(`--${name}`);
+    return idx !== -1 && argv[idx + 1] ? argv[idx + 1] : fallback;
+  };
+
+  const pkgDir = path.resolve(arg("pkg", process.cwd()));
+  const pkgJsonPath = path.join(pkgDir, "package.json");
+  const pkgName: string = fs.existsSync(pkgJsonPath)
+    ? (JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8")).name ?? "")
+    : "";
+  const defaultNamespace = pkgName.match(/^@decocms\/apps-(.+)$/)?.[1] ?? "";
+  const namespace = arg("namespace", defaultNamespace);
+  if (!namespace) {
+    console.error(
+      "Could not derive --namespace from package.json (expected @decocms/apps-<ns>); pass --namespace explicitly.",
+    );
+    process.exit(1);
+  }
+
+  const outPath = path.resolve(pkgDir, arg("out", "src/schemas.gen.ts"));
+  const result = generateAppSchemas(pkgDir, namespace);
+  fs.writeFileSync(outPath, renderSchemasModule(result));
+
+  const count = (r: Record<string, unknown>) => Object.keys(r).length;
+  console.log(
+    `Generated ${count(result.loaders)} loader keys, ${count(result.actions)} action keys → ${path.relative(pkgDir, outPath)}`,
+  );
+}

package/scripts/generate-schema.ts

@@ -284,6 +284,23 @@ const REACT_INTERNAL_PROPS = new Set([
   "_store",
 ]);
 
+// Platform types injected at runtime, never configured through the CMS form.
+// Collapsed to a hidden object in typeToJsonSchema (guarded by "is it really
+// the lib declaration" so same-named site types still expand).
+const RUNTIME_INJECTED_TYPES = new Set([
+  "URL",
+  "URLSearchParams",
+  "Request",
+  "Response",
+  "Headers",
+  "AbortSignal",
+  "ReadableStream",
+  "WritableStream",
+  "Blob",
+  "File",
+  "FormData",
+]);
+
 interface GenerationContext {
   outputTypeToLoaderKeys: Map<string, string[]>;
 }
@@ -409,6 +426,18 @@ export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?:
     }
 
     if (type.isObject() || type.isInterface()) {
+      // Runtime-injected platform types (loader `url: URL`, `req: Request`, …)
+      // are not CMS-configurable — hide instead of expanding the whole DOM
+      // interface into the form. Only collapse the real lib types: a site
+      // interface merely NAMED `Request` should still be expanded.
+      const symName = type.getSymbol()?.getName();
+      if (symName && RUNTIME_INJECTED_TYPES.has(symName)) {
+        const declFile = type.getSymbol()?.getDeclarations()?.[0]?.getSourceFile().getFilePath();
+        if (declFile?.includes("typescript/lib/") || declFile?.includes("@types/")) {
+          return { type: "object", hide: "true" };
+        }
+      }
+
       // Record<K,V> → { type: "object", additionalProperties: V-schema }
       const stringIdx = type.getStringIndexType();
       const numberIdx = type.getNumberIndexType();
@@ -435,6 +464,12 @@ export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?:
         if (!decl) continue;
         const propType = prop.getTypeAtLocation(decl);
 
+        // Methods (e.g. URL#toString on platform-ish objects) aren't data —
+        // a pure function type has no place in a props form.
+        if (propType.getCallSignatures().length > 0 && propType.getProperties().length === 0) {
+          continue;
+        }
+
         const tags = getJsDocTags(prop);
         if (tags.ignore) continue;
 
@@ -527,7 +562,9 @@ export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?:
         if (!schema.title) schema.title = name.charAt(0).toUpperCase() + name.slice(1);
 
         properties[name] = schema;
-        if (!prop.isOptional()) required.push(name);
+        // A hidden prop (runtime-injected type, ReactNode, @hide) can never be
+        // filled in by the CMS user — requiring it would deadlock the form.
+        if (!prop.isOptional() && schema.hide !== "true") required.push(name);
       }
 
       const result: any = { type: "object", properties };
@@ -548,7 +585,7 @@ export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?:
   }
 }
 
-function getJsDocTags(symbol: MorphSymbol): Record<string, string> {
+export function getJsDocTags(symbol: MorphSymbol): Record<string, string> {
   const tags: Record<string, string> = {};
   for (const decl of symbol.getDeclarations()) {
     const jsDocs = Node.isJSDocable(decl) ? decl.getJsDocs() : [];

package/scripts/migrate/templates/routes.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import type { MigrationContext } from "../types";
+import { createContext } from "../types";
+import { generateRoutes } from "./routes";
+
+function makeCtx(platform: MigrationContext["platform"]): MigrationContext {
+  const ctx = createContext("/tmp/routes-template-fixture-site");
+  ctx.siteName = "acme-storefront";
+  ctx.platform = platform;
+  ctx.vtexAccount = platform === "vtex" ? "acme" : null;
+  return ctx;
+}
+
+/**
+ * Regression guard: the scaffolded deco admin route files must use the
+ * dev-HMR-safe `*RouteConfig()` factories — the only form @decocms/tanstack
+ * exports since 7.10.0 — never the removed pre-7.10.0 module-scope literals
+ * passed by reference. router-core's `update()` mutates the options object it
+ * receives (injects id/path); a shared literal got polluted on first
+ * execution, and any dev-HMR re-execution of the route file then threw
+ * "Route cannot have both an 'id' and a 'path' option", 500ing every route
+ * until the dev server restarted.
+ */
+describe("scaffolded deco admin routes use HMR-safe factories", () => {
+  const routeCases = [
+    { file: "src/routes/deco/meta.ts", factory: "decoMetaRouteConfig", literal: "decoMetaRoute" },
+    {
+      file: "src/routes/deco/render.ts",
+      factory: "decoRenderRouteConfig",
+      literal: "decoRenderRoute",
+    },
+    {
+      file: "src/routes/deco/invoke.$.ts",
+      factory: "decoInvokeRouteConfig",
+      literal: "decoInvokeRoute",
+    },
+  ] as const;
+
+  for (const platform of ["vtex", "custom"] as const) {
+    describe(`platform: ${platform}`, () => {
+      const files = generateRoutes(makeCtx(platform));
+
+      for (const { file, factory, literal } of routeCases) {
+        it(`${file} calls ${factory}() and never passes ${literal} by reference`, () => {
+          const content = files[file];
+          expect(content, `${file} must be emitted`).toBeTypeOf("string");
+
+          // Factory form: createFileRoute("...")(decoXRouteConfig())
+          expect(content).toContain(`${factory}()`);
+          expect(content).toContain(`import { ${factory} } from "@decocms/tanstack"`);
+
+          // Forbidden form: createFileRoute("...")(decoXRoute) — shared
+          // literal by reference. `(?!Config)` keeps the factory call legal.
+          expect(content).not.toMatch(new RegExp(`\\)\\(${literal}(?!Config)\\s*\\)`));
+        });
+      }
+    });
+  }
+});

package/scripts/migrate/templates/routes.ts

@@ -210,26 +210,34 @@ function NotFoundPage() {
 `;
 }
 
+// The deco admin routes use the `*RouteConfig()` factories — the only form
+// @decocms/tanstack exports since 7.10.0. The pre-7.10.0 module-scope
+// literals (decoMetaRoute/decoRenderRoute/decoInvokeRoute) were removed:
+// passed by reference, router-core's update() mutated the shared object
+// (injecting id/path), and any dev-HMR re-execution of the route file then
+// threw "Route cannot have both an 'id' and a 'path' option", 500ing every
+// route until dev restart.
+
 function generateDecoMeta(): string {
   return `import { createFileRoute } from "@tanstack/react-router";
-import { decoMetaRoute } from "@decocms/tanstack";
+import { decoMetaRouteConfig } from "@decocms/tanstack";
 
-export const Route = createFileRoute("/deco/meta")(decoMetaRoute);
+export const Route = createFileRoute("/deco/meta")(decoMetaRouteConfig());
 `;
 }
 
 function generateDecoInvoke(): string {
   return `import { createFileRoute } from "@tanstack/react-router";
-import { decoInvokeRoute } from "@decocms/tanstack";
+import { decoInvokeRouteConfig } from "@decocms/tanstack";
 
-export const Route = createFileRoute("/deco/invoke/$")(decoInvokeRoute);
+export const Route = createFileRoute("/deco/invoke/$")(decoInvokeRouteConfig());
 `;
 }
 
 function generateDecoRender(): string {
   return `import { createFileRoute } from "@tanstack/react-router";
-import { decoRenderRoute } from "@decocms/tanstack";
+import { decoRenderRouteConfig } from "@decocms/tanstack";
 
-export const Route = createFileRoute("/deco/render")(decoRenderRoute);
+export const Route = createFileRoute("/deco/render")(decoRenderRouteConfig());
 `;
 }