@decocms/blocks-cli 7.8.0 → 7.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.8.0",
+  "version": "7.10.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -19,7 +19,9 @@
     "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",
     "./generate-invoke": "./scripts/generate-invoke.ts",
     "./migrate": "./scripts/migrate.ts",
@@ -34,7 +36,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.8.0",
+    "@decocms/blocks": "7.10.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-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-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() : [];