@llm-cms/core 0.0.1 → 0.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llm-cms/core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Experimental LLMCMS SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/block.ts

@@ -0,0 +1,103 @@
+// packages/core/src/block.ts
+import {
+  type FieldDef,
+  type FieldKind,
+  type FieldSnapshot,
+  parseFieldSnapshot,
+  serializeField,
+} from "./fields";
+
+export type BlockInstance = {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+};
+
+export type BlockDef<C = unknown> = {
+  name: string;
+  fields: Record<string, FieldDef>;
+  component: C;
+};
+
+export type BlockSnapshot = {
+  name: string;
+  fields: Record<string, FieldSnapshot>;
+};
+
+const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
+
+export function defineBlock<const D extends BlockDef>(def: D): D {
+  if (!def.name || typeof def.name !== "string") {
+    throw new Error("block.name is required");
+  }
+  if (!PASCAL.test(def.name)) {
+    throw new Error('block.name must be PascalCase (e.g. "Hero")');
+  }
+  if (!def.fields || typeof def.fields !== "object") {
+    throw new Error("block.fields is required");
+  }
+  if (def.component === undefined) {
+    throw new Error("block.component is required");
+  }
+  return def;
+}
+
+type Simplify<T> = { -readonly [K in keyof T]: T[K] } & {};
+
+type ScalarOf<K extends FieldKind> = K extends "number"
+  ? number
+  : K extends "boolean"
+    ? boolean
+    : K extends "blocks"
+      ? BlockInstance[]
+      : string;
+
+type IsRequired<F> = F extends { required?: infer R }
+  ? [Exclude<R, undefined>] extends [true]
+    ? true
+    : false
+  : false;
+
+/** TypeScript shape of a block's props, derived from `field.*` calls. */
+export type InferBlockProps<Fields extends Record<string, FieldDef>> = Simplify<
+  {
+    [N in keyof Fields as IsRequired<Fields[N]> extends true ? N : never]: ScalarOf<
+      Fields[N]["kind"]
+    >;
+  } & {
+    [N in keyof Fields as IsRequired<Fields[N]> extends true ? never : N]?: ScalarOf<
+      Fields[N]["kind"]
+    >;
+  }
+>;
+
+export function serializeBlock(block: BlockDef): BlockSnapshot {
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, def] of Object.entries(block.fields)) {
+    fields[name] = serializeField(def);
+  }
+  return { name: block.name, fields };
+}
+
+export function parseBlockSnapshot(input: unknown): BlockSnapshot {
+  if (!input || typeof input !== "object") {
+    throw new Error("block must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  if (typeof value.name !== "string" || !value.name) {
+    throw new Error("block.name is required");
+  }
+  if (!value.fields || typeof value.fields !== "object" || Array.isArray(value.fields)) {
+    throw new Error("block.fields must be an object");
+  }
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, fieldRaw] of Object.entries(value.fields as Record<string, unknown>)) {
+    try {
+      fields[name] = parseFieldSnapshot(fieldRaw);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "invalid field";
+      throw new Error(`block.fields.${name}: ${msg}`);
+    }
+  }
+  return { name: value.name, fields };
+}

package/src/config.ts

@@ -6,8 +6,10 @@ import { detectGitBranch } from "./sync-schema";
 export type LlmcmsDirs = {
   /** Folder with one `defineModel` default export per file. Default: "models". */
   models?: string;
-  /** Folder with one React component default export per file. Default: "blocks". */
+  /** Folder with one `defineBlock` default export per file. Default: "blocks". */
   blocks?: string;
+  /** Folder with one MDX tag component default export per file. Default: "mdx". */
+  mdx?: string;
 };
 
 export type LlmcmsConfig = {
@@ -40,7 +42,11 @@ export type ResolvedConfig = Omit<LlmcmsConfig, "dirs" | "defaultLocale"> & {
   dirs: Required<LlmcmsDirs>;
 };
 
-export const DEFAULT_DIRS: Required<LlmcmsDirs> = { models: "models", blocks: "blocks" };
+export const DEFAULT_DIRS: Required<LlmcmsDirs> = {
+  models: "models",
+  blocks: "blocks",
+  mdx: "mdx",
+};
 export const DEFAULT_LOCALE = "en";
 
 function withHttps(url: string): string {
@@ -106,6 +112,7 @@ export function resolveConfig(
     dirs: {
       models: config.dirs?.models ?? DEFAULT_DIRS.models,
       blocks: config.dirs?.blocks ?? DEFAULT_DIRS.blocks,
+      mdx: config.dirs?.mdx ?? DEFAULT_DIRS.mdx,
     },
   };
 }

package/src/doc-format.ts

@@ -0,0 +1,32 @@
+// packages/core/src/doc-format.ts
+import { parseMdx, serializeMdx, type Frontmatter, type ParsedMdx } from "./mdx";
+
+export type DocFormat = "mdx" | "page";
+
+export function modelFormat(model: { format?: string } | null | undefined): DocFormat {
+  return model?.format === "page" ? "page" : "mdx";
+}
+
+export function parseDoc(raw: string, format: DocFormat = "mdx"): ParsedMdx {
+  if (format !== "page") return parseMdx(raw);
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "invalid JSON";
+    throw new Error(`JSON: ${msg}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("page document must be a JSON object");
+  }
+  return { frontmatter: value as Frontmatter, body: "" };
+}
+
+export function serializeDoc(
+  format: DocFormat,
+  frontmatter: Frontmatter,
+  body: string,
+): string {
+  if (format !== "page") return serializeMdx(frontmatter, body);
+  return `${JSON.stringify(frontmatter, null, 2)}\n`;
+}

package/src/fields.ts

@@ -7,7 +7,8 @@ export type FieldKind =
   | "image"
   | "relation"
   | "number"
-  | "boolean";
+  | "boolean"
+  | "blocks";
 
 /**
  * Field definition. Generic parameters only exist for type inference
@@ -52,6 +53,7 @@ export const field = {
   boolean: <const R extends boolean = false>(opts?: Opts<R>) => base("boolean", opts),
   relation: <To extends string, const R extends boolean = false>(to: To, opts?: Opts<R>) =>
     base("relation", { ...opts, relationTo: to }),
+  blocks: <const R extends boolean = false>(opts?: Opts<R>) => base("blocks", opts),
 };
 
 export function serializeField(def: FieldDef): FieldSnapshot {
@@ -76,6 +78,7 @@ export function parseFieldSnapshot(input: unknown): FieldSnapshot {
     "relation",
     "number",
     "boolean",
+    "blocks",
   ];
   if (typeof kind !== "string" || !allowed.includes(kind as FieldKind)) {
     throw new Error(`invalid field.kind: ${String(kind)}`);

package/src/index.ts

@@ -20,11 +20,27 @@ export {
   defineModel,
   defaultModelPath,
   DEFAULT_MODEL_PATH,
+  DEFAULT_PAGE_PATH,
   serializeModel,
   serializeSchema,
   parseSchemaSnapshot,
 } from "./model";
 
+export type {
+  BlockInstance,
+  BlockDef,
+  BlockSnapshot,
+  InferBlockProps,
+} from "./block";
+export {
+  defineBlock,
+  serializeBlock,
+  parseBlockSnapshot,
+} from "./block";
+
+export type { DocFormat } from "./doc-format";
+export { modelFormat, parseDoc, serializeDoc } from "./doc-format";
+
 export type { LlmcmsConfig, LlmcmsDirs, ResolvedConfig } from "./config";
 export { defineConfig, resolveConfig, detectSiteUrl, DEFAULT_DIRS, DEFAULT_LOCALE } from "./config";
 
@@ -46,6 +62,8 @@ export {
   matchModelPath,
   matchAnyModelPath,
   repoPathFromModel,
+  contentExtFromPath,
+  contentExtForType,
   encodeGitBranch,
   decodeGitBranch,
   s3HeadKey,
@@ -63,6 +81,8 @@ export type { ValidationResult, ContentFileResult } from "./validate";
 export {
   validateFrontmatter,
   validateMdxFile,
+  validateDocFile,
+  validateBlocks,
   validateContentTree,
 } from "./validate";
 

package/src/model.ts

@@ -6,6 +6,9 @@ import {
   parseFieldSnapshot,
   serializeField,
 } from "./fields";
+import { parseBlockSnapshot, serializeBlock, type BlockDef, type BlockSnapshot } from "./block";
+import type { BlockInstance } from "./block";
+import type { DocFormat } from "./doc-format";
 
 export type ModelDef = {
   type: string;
@@ -16,6 +19,8 @@ export type ModelDef = {
    * Defaults to "/{locale}/{type}/{slug}" when omitted (see routes.ts).
    */
   route?: string;
+  /** File format. Default `"mdx"`. `"page"` stores JSON with a blocks array. */
+  format?: DocFormat;
   fields: Record<string, FieldDef>;
 };
 
@@ -24,21 +29,25 @@ export type ModelInput = Omit<ModelDef, "path"> & { path?: string };
 
 /** Default repo path when a model does not declare one. */
 export const DEFAULT_MODEL_PATH = "content/{locale}/{type}/{slug}.mdx";
+export const DEFAULT_PAGE_PATH = "content/{locale}/{type}/{slug}.json";
 
-export function defaultModelPath(type: string): string {
-  return DEFAULT_MODEL_PATH.replaceAll("{type}", type);
+export function defaultModelPath(type: string, format: DocFormat = "mdx"): string {
+  const template = format === "page" ? DEFAULT_PAGE_PATH : DEFAULT_MODEL_PATH;
+  return template.replaceAll("{type}", type);
 }
 
 export type ModelSnapshot = {
   type: string;
   path: string;
   route?: string;
+  format?: DocFormat;
   fields: Record<string, FieldSnapshot>;
 };
 
 export type SchemaSnapshot = {
   version: number;
   models: ModelSnapshot[];
+  blocks?: BlockSnapshot[];
 };
 
 type WithPath<D extends ModelInput> = D extends { path: string } ? D : D & { path: string };
@@ -51,7 +60,10 @@ export function defineModel<const D extends ModelInput>(def: D): WithPath<D> {
   if (!def.type || typeof def.type !== "string") {
     throw new Error("model.type is required");
   }
-  const path = def.path ?? defaultModelPath(def.type);
+  if (def.format !== undefined && def.format !== "mdx" && def.format !== "page") {
+    throw new Error('model.format must be "mdx" or "page"');
+  }
+  const path = def.path ?? defaultModelPath(def.type, def.format ?? "mdx");
   if (typeof path !== "string" || !path) {
     throw new Error("model.path must be a non-empty string");
   }
@@ -78,7 +90,9 @@ type ScalarOf<K extends FieldKind> = K extends "number"
   ? number
   : K extends "boolean"
     ? boolean
-    : string;
+    : K extends "blocks"
+      ? BlockInstance[]
+      : string;
 
 type IsRequired<F> = F extends { required?: infer R }
   ? [Exclude<R, undefined>] extends [true]
@@ -110,14 +124,22 @@ export function serializeModel(model: ModelDef): ModelSnapshot {
     fields,
   };
   if (model.route !== undefined) snapshot.route = model.route;
+  if (model.format === "page") snapshot.format = "page";
   return snapshot;
 }
 
-export function serializeSchema(models: ModelDef[]): SchemaSnapshot {
-  return {
+export function serializeSchema(
+  models: ModelDef[],
+  blocks?: BlockDef[],
+): SchemaSnapshot {
+  const snapshot: SchemaSnapshot = {
     version: 1,
     models: models.map(serializeModel),
   };
+  if (blocks && blocks.length > 0) {
+    snapshot.blocks = blocks.map(serializeBlock);
+  }
+  return snapshot;
 }
 
 export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
@@ -167,6 +189,10 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     }
     const snapshot: ModelSnapshot = { type: m.type, path: m.path, fields };
     if (typeof m.route === "string") snapshot.route = m.route;
+    if (m.format === "page") snapshot.format = "page";
+    else if (m.format !== undefined && m.format !== "mdx") {
+      throw new Error(`schema.models[${i}].format must be "mdx" or "page"`);
+    }
     return snapshot;
   });
 
@@ -178,5 +204,28 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
     types.add(m.type);
   }
 
-  return { version, models };
+  let blocks: BlockSnapshot[] = [];
+  const catalogRaw = value.blocks ?? value.pageblocks;
+  if (catalogRaw !== undefined) {
+    if (!Array.isArray(catalogRaw)) {
+      throw new Error("schema.blocks must be an array");
+    }
+    blocks = catalogRaw.map((raw, i) => {
+      try {
+        return parseBlockSnapshot(raw);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "invalid block";
+        throw new Error(`schema.blocks[${i}]: ${msg}`);
+      }
+    });
+    const names = new Set<string>();
+    for (const block of blocks) {
+      if (names.has(block.name)) {
+        throw new Error(`duplicate block name: ${block.name}`);
+      }
+      names.add(block.name);
+    }
+  }
+
+  return { version, models, blocks };
 }

package/src/node/cli.ts

@@ -7,14 +7,15 @@ import { pathToFileURL } from "node:url";
 import {
   frontmatterJsonSchema,
   serializeModel,
+  serializeBlock,
   validateContentTree,
   type ContentFileResult,
   type ModelDef,
   type ModelSnapshot,
 } from "../index";
 import { resolveConfig, type LlmcmsConfig, type ResolvedConfig } from "../config";
-import { discoverModels } from "./discover";
-import { walkMdxFiles } from "./fs-loader";
+import { discoverModels, discoverBlocks } from "./discover";
+import { walkContentFiles } from "./fs-loader";
 import { detectSdk, findConfigFile, generate, type GenerateResult } from "./generate";
 
 export type CliArgs = {
@@ -28,7 +29,7 @@ export type CliArgs = {
 
 const USAGE = `Usage:
   llmcms init                          scaffold llmcms.config.ts, the catch-all route and .llmcms/
-  llmcms generate  [--root <dir>]      write .llmcms/index.ts (typed cms) and .llmcms/blocks.ts
+  llmcms generate  [--root <dir>]      write .llmcms/index.ts (typed cms), blocks.ts and mdx.ts
   llmcms validate  [--root <dir>] [--models <file>] [--json]
   llmcms schema    [--root <dir>] [--models <file>] [--out <dir>]
 
@@ -162,13 +163,21 @@ export async function runValidate(
 ): Promise<{ results: ContentFileResult[]; roots: string[]; exitCode: 0 | 1 }> {
   const root = path.resolve(args.root);
   const models = (await loadModels(root, args.models)).map(serializeModel);
+  const config = await loadConfig(root);
+  let catalog: ReturnType<typeof serializeBlock>[] = [];
+  try {
+    const defs = await discoverBlocks(root, config.dirs.blocks);
+    catalog = defs.map((d) => serializeBlock(d as never));
+  } catch {
+    catalog = [];
+  }
   const roots = contentRoots(models);
   const files: string[] = [];
   for (const contentRoot of roots) {
     const dir = path.join(root, contentRoot);
     const info = await stat(dir).catch(() => null);
     if (!info?.isDirectory()) continue; // missing roots are simply skipped
-    files.push(...(await walkMdxFiles(dir)));
+    files.push(...(await walkContentFiles(dir)));
   }
   files.sort();
   const inputs = await Promise.all(
@@ -177,7 +186,7 @@ export async function runValidate(
       raw: await readFile(full, "utf-8"),
     })),
   );
-  const results = validateContentTree({ models, files: inputs });
+  const results = validateContentTree({ models, files: inputs, catalog });
   return { results, roots, exitCode: results.some((r) => !r.ok) ? 1 : 0 };
 }
 
@@ -221,7 +230,12 @@ export async function runGenerate(args: CliArgs): Promise<GenerateResult> {
     );
     config = resolveConfig({});
   }
-  return generate({ root, modelsDir: config.dirs.models, blocksDir: config.dirs.blocks });
+  return generate({
+    root,
+    modelsDir: config.dirs.models,
+    blocksDir: config.dirs.blocks,
+    mdxDir: config.dirs.mdx,
+  });
 }
 
 const CATCH_ALL_DIR = "[...llmcms]";
@@ -231,8 +245,9 @@ function renderConfigFile(sdk: string): string {
   return `// llmcms.config.ts
 import { defineConfig } from "${from}";
 
-// General settings only. Models live in models/*.ts, blocks in blocks/*.tsx and
-// content in content/{locale}/{type}/{slug}.mdx — all discovered automatically.
+// General settings only. Models live in models/*.ts, composer blocks in
+// blocks/*.tsx, MDX tags in mdx/*.tsx, and content in
+// content/{locale}/{type}/{slug}.{mdx,json} — all discovered automatically.
 // workspaceId / apiUrl / tokens fall back to LLMCMS_* env vars when omitted.
 export default defineConfig({
   defaultLocale: "en",
@@ -244,9 +259,10 @@ function renderCatchAllPage(registryImport: string): string {
   return `// ${CATCH_ALL_DIR}/page.tsx — mounts every model at its route (default /{locale}/{type}/{slug}).
 import { createCatchAll } from "@llm-cms/next/routes";
 import { cms } from "${registryImport}";
+import { components } from "${registryImport}/mdx";
 import { blocks } from "${registryImport}/blocks";
 
-const route = createCatchAll(cms, { components: blocks });
+const route = createCatchAll(cms, { components, blocks });
 
 export const generateStaticParams = route.generateStaticParams;
 export default route.Page;
@@ -312,7 +328,7 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     notes.push("no @llm-cms/next dependency: skipped the catch-all route");
   }
 
-  for (const dir of ["models", "content", "blocks"]) {
+  for (const dir of ["models", "content", "blocks", "mdx"]) {
     await mkdir(path.join(root, dir), { recursive: true });
   }
 
@@ -339,7 +355,7 @@ async function main(argv: string[]): Promise<number> {
       const { results, roots, exitCode } = await runValidate(args);
       if (results.length === 0) {
         console.error(
-          `llmcms: no .mdx files found under ${roots.join(", ")} (check --root)`,
+          `llmcms: no .mdx or .json files found under ${roots.join(", ")} (check --root)`,
         );
       }
       if (args.json) {
@@ -368,6 +384,9 @@ async function main(argv: string[]): Promise<number> {
       for (const skipped of result.skippedBlocks) {
         console.error(`llmcms: skipped ${skipped} (block file names must be PascalCase)`);
       }
+      for (const skipped of result.skippedMdx) {
+        console.error(`llmcms: skipped ${skipped} (MDX file names must be PascalCase)`);
+      }
       return 0;
     }
     if (args.command === "init") {

package/src/node/create-llmcms.ts

@@ -1,5 +1,6 @@
 // packages/core/src/node/create-llmcms.ts
 import type { ModelDef, ModelSnapshot } from "../model";
+import type { BlockDef } from "../block";
 import { getDocFromApi, listDocsFromApi } from "../api-loader";
 import { getDocFromFs, listDocsFromFs } from "./fs-loader";
 import { createQuery, type DocLoader, type Query } from "../query";
@@ -15,6 +16,7 @@ import { contentCacheTags, listCacheTags } from "../content-committed";
 export type CreateLlmcmsOptions<Models extends readonly ModelDef[] = readonly ModelDef[]> =
   LlmcmsConfig & {
     models: Models;
+    blocks?: readonly BlockDef[];
     /**
      * When true, API fetches use Next cache tags instead of `cache: "no-store"`.
      * `@llm-cms/next` turns this on.
@@ -48,6 +50,7 @@ function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
       fields: m.fields as ModelSnapshot["fields"],
     };
     if (m.route !== undefined) snapshot.route = m.route;
+    if (m.format === "page") snapshot.format = "page";
     return snapshot;
   });
 }
@@ -55,7 +58,7 @@ function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
 export function createLlmcms<const Models extends readonly ModelDef[]>(
   options: CreateLlmcmsOptions<Models>,
 ): LlmcmsClient<Models> {
-  const { models: modelDefs, taggedApiFetch, ...rest } = options;
+  const { models: modelDefs, blocks: blockDefs, taggedApiFetch, ...rest } = options;
   const config = resolveConfig(rest);
   const models = toSnapshots(modelDefs);
   const siteRoot = config.siteRoot ?? process.cwd();
@@ -78,6 +81,7 @@ export function createLlmcms<const Models extends readonly ModelDef[]>(
         workspaceId,
         hostToken,
         models: [...modelDefs],
+        blocks: blockDefs ? [...blockDefs] : undefined,
         branch: config.branch,
         siteUrl,
       }).catch((err) => {

package/src/node/discover.ts

@@ -1,7 +1,8 @@
 // packages/core/src/node/discover.ts
-// Folder conventions: `models/{type}.ts` (default export = defineModel) and
-// `blocks/{Name}.tsx` (default export = React component). Listing is pure
-// filesystem so it can run inside next.config; importing needs Bun/TS.
+// Folder conventions: `models/{type}.ts` (default export = defineModel),
+// `blocks/{Name}.tsx` (default export = defineBlock), and `mdx/{Name}.tsx`
+// (default export = MDX tag component). Listing is pure filesystem so it can
+// run inside next.config; importing needs Bun/TS.
 import { existsSync, readdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -18,7 +19,7 @@ export type ModelFile = {
 
 export type BlockFile = {
   file: string;
-  /** File stem, also the MDX tag name. */
+  /** File stem: block name or MDX tag name. */
   name: string;
 };
 
@@ -63,18 +64,42 @@ export function listModelFiles(root: string, modelsDir = "models"): ModelFile[]
 
 const JSX_TAG = /^[A-Z][A-Za-z0-9]*$/;
 
-export function listBlockFiles(
+function listPascalCaseFiles(
   root: string,
-  blocksDir = "blocks",
-): { blocks: BlockFile[]; skipped: string[] } {
-  const blocks: BlockFile[] = [];
+  dir: string,
+): { files: BlockFile[]; skipped: string[] } {
+  const files: BlockFile[] = [];
   const skipped: string[] = [];
-  for (const file of listSourceFiles(path.resolve(root, blocksDir))) {
+  for (const file of listSourceFiles(path.resolve(root, dir))) {
     const name = path.basename(file).replace(SOURCE_EXT, "");
-    if (JSX_TAG.test(name)) blocks.push({ file, name });
+    if (JSX_TAG.test(name)) files.push({ file, name });
     else skipped.push(path.relative(root, file));
   }
-  return { blocks, skipped };
+  return { files, skipped };
+}
+
+/** Structured composer blocks (`defineBlock`). */
+export function listBlockFiles(
+  root: string,
+  blocksDir = "blocks",
+): { blocks: BlockFile[]; skipped: string[] } {
+  const { files, skipped } = listPascalCaseFiles(root, blocksDir);
+  return { blocks: files, skipped };
+}
+
+/** MDX tag components. */
+export function listMdxFiles(
+  root: string,
+  mdxDir = "mdx",
+): { blocks: BlockFile[]; skipped: string[] } {
+  const { files, skipped } = listPascalCaseFiles(root, mdxDir);
+  return { blocks: files, skipped };
+}
+
+function isBlockDef(value: unknown): boolean {
+  if (!value || typeof value !== "object") return false;
+  const m = value as Record<string, unknown>;
+  return typeof m.name === "string" && typeof m.fields === "object" && "component" in m;
 }
 
 function isModelDef(value: unknown): value is ModelDef {
@@ -114,3 +139,36 @@ export async function discoverModels(root: string, modelsDir = "models"): Promis
   }
   return models;
 }
+
+/**
+ * Import every block file. The file stem must equal `block.name`.
+ */
+export async function discoverBlocks(
+  root: string,
+  blocksDir = "blocks",
+): Promise<Array<{ name: string; fields: Record<string, unknown>; component: unknown }>> {
+  const blocks: Array<{ name: string; fields: Record<string, unknown>; component: unknown }> = [];
+  const names = new Set<string>();
+  const { blocks: files } = listBlockFiles(root, blocksDir);
+  for (const { file, name } of files) {
+    const rel = path.relative(root, file);
+    const mod = (await import(
+      /* webpackIgnore: true */ /* turbopackIgnore: true */ pathToFileURL(file).href
+    )) as { default?: unknown };
+    if (!isBlockDef(mod.default)) {
+      throw new Error(`${rel} must \`export default defineBlock({ ... })\``);
+    }
+    const def = mod.default as { name: string; fields: Record<string, unknown>; component: unknown };
+    if (def.name !== name) {
+      throw new Error(
+        `${rel} defines name "${def.name}" but the file is named "${name}"; rename one so they match`,
+      );
+    }
+    if (names.has(def.name)) {
+      throw new Error(`duplicate block name "${def.name}" (${rel})`);
+    }
+    names.add(def.name);
+    blocks.push(def);
+  }
+  return blocks;
+}