@backmatter/core 0.0.6

package/src/node/discover.ts

@@ -0,0 +1,191 @@
+// packages/core/src/node/discover.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";
+import type { ModelDef } from "../model";
+
+export type ModelFile = {
+  /** Absolute path. */
+  file: string;
+  /** File stem, also the expected `model.type`. */
+  stem: string;
+  /** Valid JS identifier derived from the stem, used in generated imports. */
+  importName: string;
+};
+
+export type BlockFile = {
+  file: string;
+  /** File stem: block name or MDX tag name. */
+  name: string;
+};
+
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
+const IGNORED = /(\.test\.|\.spec\.|\.d\.ts$|\.stories\.)/;
+
+export function toIdentifier(stem: string): string {
+  const camel = stem
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part, i) => (i === 0 ? part : part[0]!.toUpperCase() + part.slice(1)))
+    .join("");
+  const safe = camel.replace(/^[^A-Za-z_$]/, (c) => `_${c}`);
+  return safe || "_";
+}
+
+function listSourceFiles(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isFile() && SOURCE_EXT.test(e.name) && !IGNORED.test(e.name))
+    .filter((e) => !e.name.startsWith("_") && !e.name.startsWith("."))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+}
+
+export function listModelFiles(root: string, modelsDir = "models"): ModelFile[] {
+  const files = listSourceFiles(path.resolve(root, modelsDir));
+  const seen = new Map<string, string>();
+  return files.map((file) => {
+    const stem = path.basename(file).replace(SOURCE_EXT, "");
+    const importName = toIdentifier(stem);
+    const clash = seen.get(importName);
+    if (clash) {
+      throw new Error(
+        `models/${path.basename(clash)} and models/${path.basename(file)} both map to "${importName}"`,
+      );
+    }
+    seen.set(importName, file);
+    return { file, stem, importName };
+  });
+}
+
+const JSX_TAG = /^[A-Z][A-Za-z0-9]*$/;
+const FALLBACK_STEM = /^([A-Z][A-Za-z0-9]*)\.fallback$/;
+
+function listPascalCaseFiles(
+  root: string,
+  dir: string,
+): { files: BlockFile[]; skipped: string[] } {
+  const files: BlockFile[] = [];
+  const skipped: string[] = [];
+  for (const file of listSourceFiles(path.resolve(root, dir))) {
+    const name = path.basename(file).replace(SOURCE_EXT, "");
+    if (FALLBACK_STEM.test(name)) continue;
+    if (JSX_TAG.test(name)) files.push({ file, name });
+    else skipped.push(path.relative(root, file));
+  }
+  return { files, skipped };
+}
+
+export function listBlockFallbackFiles(
+  root: string,
+  blocksDir = "blocks",
+): BlockFile[] {
+  const files: BlockFile[] = [];
+  for (const file of listSourceFiles(path.resolve(root, blocksDir))) {
+    const stem = path.basename(file).replace(SOURCE_EXT, "");
+    const match = FALLBACK_STEM.exec(stem);
+    if (match) files.push({ file, name: match[1]! });
+  }
+  return files.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+export function listLayoutFiles(root: string, layoutsDir = "layouts"): ModelFile[] {
+  return listModelFiles(root, layoutsDir);
+}
+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 {
+  if (!value || typeof value !== "object") return false;
+  const m = value as Record<string, unknown>;
+  return typeof m.type === "string" && typeof m.path === "string" && typeof m.fields === "object";
+}
+
+/**
+ * Import every model file and return its default export. The file stem must
+ * equal `model.type` so `content/{locale}/{type}/` and `models/{type}.ts` line up.
+ */
+export async function discoverModels(root: string, modelsDir = "models"): Promise<ModelDef[]> {
+  const models: ModelDef[] = [];
+  const types = new Set<string>();
+  for (const { file, stem } of listModelFiles(root, modelsDir)) {
+    const rel = path.relative(root, file);
+    // CLI-only runtime import. The ignore hints stop webpack/Turbopack from
+    // trying to bundle an expression request when this module ends up in a
+    // host app graph via `@backmatter/core/node`.
+    const mod = (await import(
+      /* webpackIgnore: true */ /* turbopackIgnore: true */ pathToFileURL(file).href
+    )) as { default?: unknown };
+    if (!isModelDef(mod.default)) {
+      throw new Error(`${rel} must \`export default defineModel({ ... })\``);
+    }
+    if (mod.default.type !== stem) {
+      throw new Error(
+        `${rel} defines type "${mod.default.type}" but the file is named "${stem}"; rename one so they match`,
+      );
+    }
+    if (types.has(mod.default.type)) {
+      throw new Error(`duplicate model type "${mod.default.type}" (${rel})`);
+    }
+    types.add(mod.default.type);
+    models.push(mod.default);
+  }
+  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;
+}

package/src/node/eval-block.ts

@@ -0,0 +1,202 @@
+// packages/core/src/node/eval-block.ts
+// Sandbox-eval a convention `blocks/{Name}.tsx` blob (GitHub import).
+// `defineBlock` / `field` come from core; other imports are stubbed so the
+// SaaS never loads customer React, Next, or the host checkout.
+import { runInNewContext } from "node:vm";
+import { field } from "../fields";
+import { defineBlock, type BlockDef } from "../block";
+
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
+const IGNORED = /(\.test\.|\.spec\.|\.d\.ts$|\.stories\.)/;
+const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
+const CORE_IMPORT =
+  /^\s*import\s+\{([^}]+)\}\s+from\s+["'](@backmatter\/core|@backmatter\/next)["']\s*;?\s*$/gm;
+const TYPE_IMPORT = /^\s*import\s+type\s+[\s\S]*?from\s+["'][^"']+["']\s*;?\s*$/gm;
+const VALUE_IMPORT = /^\s*import\s+([\s\S]*?)\s+from\s+["'][^"']+["']\s*;?\s*$/gm;
+const USE_CLIENT = /^["']use client["'];?\s*$/gm;
+const ALLOWED_NAMES = new Set(["defineBlock", "field", "InferBlockProps"]);
+const FORBIDDEN = [
+  { re: /\brequire\s*\(/, name: "require" },
+  { re: /\bimport\s*\(/, name: "import" },
+  { re: /\bprocess\b/, name: "process" },
+  { re: /\bBun\b/, name: "Bun" },
+  { re: /\bDeno\b/, name: "Deno" },
+  { re: /\bglobalThis\b/, name: "globalThis" },
+  { re: /\bFunction\s*\(/, name: "Function" },
+  { re: /\beval\s*\(/, name: "eval" },
+];
+const EVAL_TIMEOUT_MS = 1000;
+
+function isBlockDef(value: unknown): value is BlockDef {
+  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;
+}
+
+/** True for a repo-relative `blocks/{Name}.tsx` (PascalCase stem). */
+export function isBlockSourcePath(
+  repoPath: string,
+  blocksDir = "blocks",
+): boolean {
+  const normalized = repoPath.split("\\").join("/");
+  const prefix = `${blocksDir.replace(/\/+$/, "")}/`;
+  if (!normalized.startsWith(prefix)) return false;
+  const name = normalized.slice(prefix.length);
+  if (!name || name.includes("/")) return false;
+  if (name.startsWith("_") || name.startsWith(".")) return false;
+  if (!SOURCE_EXT.test(name) || IGNORED.test(name)) return false;
+  return PASCAL.test(name.replace(SOURCE_EXT, ""));
+}
+
+function stemOf(repoPath: string): string {
+  const name = repoPath.split("\\").join("/").split("/").pop() ?? "";
+  return name.replace(SOURCE_EXT, "");
+}
+
+function identifierOf(part: string): string | null {
+  const trimmed = part.trim();
+  if (!trimmed || trimmed.startsWith("type ")) return null;
+  const aliased = trimmed.split(/\s+as\s+/);
+  const name = (aliased[1] ?? aliased[0] ?? "").trim();
+  return name || null;
+}
+
+function stubImportSpec(spec: string): string {
+  const stubs: string[] = [];
+  const named = spec.match(/\{([^}]*)\}/);
+  if (named) {
+    for (const part of named[1].split(",")) {
+      const id = identifierOf(part);
+      if (id) stubs.push(`var ${id} = function () { return null; };`);
+    }
+  }
+  const before = spec.split("{")[0] ?? "";
+  const defaultName = before.replace(/,\s*$/, "").trim();
+  if (defaultName.startsWith("*")) {
+    const as = defaultName.match(/as\s+(\w+)/);
+    if (as) stubs.push(`var ${as[1]} = {};`);
+  } else if (defaultName) {
+    stubs.push(`var ${defaultName} = function () { return null; };`);
+  }
+  return stubs.join("\n");
+}
+
+function rewriteSource(source: string): string {
+  let body = source.replace(USE_CLIENT, "");
+  body = body.replace(TYPE_IMPORT, "");
+  body = body.replace(CORE_IMPORT, (_full, specifiers: string) => {
+    for (const part of specifiers.split(",")) {
+      const raw = part.trim();
+      if (!raw) continue;
+      const name = raw.replace(/^type\s+/, "").split(/\s+as\s+/)[0]?.trim();
+      if (!name) continue;
+      if (!ALLOWED_NAMES.has(name)) {
+        throw new Error(`import "${name}" is not allowed from @backmatter/core`);
+      }
+    }
+    return "";
+  });
+  body = body.replace(VALUE_IMPORT, (line) => {
+    const m = line.match(/^\s*import\s+([\s\S]*?)\s+from\s+["'][^"']+["']\s*;?\s*$/);
+    if (!m) throw new Error("import is not allowed");
+    return stubImportSpec(m[1]);
+  });
+  if (/^\s*import\b/m.test(body)) {
+    throw new Error("import is not allowed except defineBlock/field from @backmatter/core");
+  }
+  if (!/\bexport\s+default\b/.test(body)) {
+    throw new Error("must export default defineBlock({ ... })");
+  }
+  const rewritten = stripNamedExports(body.replace(/\bexport\s+default\s+/, "return "));
+  if (/\bexport\b/.test(rewritten)) {
+    throw new Error("must export default defineBlock({ ... })");
+  }
+  return rewritten;
+}
+
+/** Host files also `export function Hero` for the Next composer map. */
+function stripNamedExports(source: string): string {
+  return source
+    .replace(/\bexport\s+\{[^}]*\}\s*;?/g, "")
+    .replace(/\bexport\s+(async\s+)?function\s+/g, "$1function ")
+    .replace(/\bexport\s+const\s+/g, "const ")
+    .replace(/\bexport\s+let\s+/g, "let ")
+    .replace(/\bexport\s+class\s+/g, "class ");
+}
+
+function assertNoForbidden(source: string): void {
+  for (const { re, name } of FORBIDDEN) {
+    if (re.test(source)) throw new Error(`${name} is not allowed in block files`);
+  }
+}
+
+function transpile(source: string): string {
+  const transpiler = new Bun.Transpiler({ loader: "tsx", target: "node" });
+  return transpiler.transformSync(source);
+}
+
+/** Evaluate one convention block file. `stem` must equal `block.name`. */
+export function evalBlockSource(source: string, stem: string): BlockDef {
+  const body = rewriteSource(source);
+  assertNoForbidden(body);
+  const wrapped = `(function () {\n${body}\n})()`;
+  const js = transpile(wrapped);
+  const sandbox = Object.create(null) as {
+    defineBlock: typeof defineBlock;
+    field: typeof field;
+    React: { createElement: (...args: unknown[]) => null; Fragment: string };
+    jsx: (...args: unknown[]) => null;
+    jsxs: (...args: unknown[]) => null;
+    jsxDEV: (...args: unknown[]) => null;
+  };
+  const el = () => null;
+  sandbox.defineBlock = defineBlock;
+  sandbox.field = field;
+  sandbox.React = { createElement: el, Fragment: "Fragment" };
+  sandbox.jsx = el;
+  sandbox.jsxs = el;
+  sandbox.jsxDEV = el;
+  Object.freeze(sandbox);
+
+  let result: unknown;
+  try {
+    result = runInNewContext(js, sandbox, {
+      timeout: EVAL_TIMEOUT_MS,
+      filename: `${stem}.js`,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`block "${stem}" failed to evaluate: ${message}`);
+  }
+
+  if (!isBlockDef(result)) {
+    throw new Error("must export default defineBlock({ ... })");
+  }
+  if (result.name !== stem) {
+    throw new Error(
+      `defines name "${result.name}" but the file is named "${stem}"; rename one so they match`,
+    );
+  }
+  return result;
+}
+
+export function evalBlocksFromTree(
+  files: Array<{ path: string; source: string }>,
+  blocksDir = "blocks",
+): BlockDef[] {
+  const blocks: BlockDef[] = [];
+  const names = new Set<string>();
+  const sorted = files
+    .filter((f) => isBlockSourcePath(f.path, blocksDir))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  for (const file of sorted) {
+    const stem = stemOf(file.path);
+    const block = evalBlockSource(file.source, stem);
+    if (names.has(block.name)) {
+      throw new Error(`duplicate block name "${block.name}" (${file.path})`);
+    }
+    names.add(block.name);
+    blocks.push(block);
+  }
+  return blocks;
+}

package/src/node/eval-model.ts

@@ -0,0 +1,143 @@
+// packages/core/src/node/eval-model.ts
+// Sandbox-eval a convention `models/{type}.ts` blob (GitHub import). Only
+// `defineModel` / `field` from @backmatter/core or @backmatter/next are in scope —
+// never import() the customer checkout.
+import { runInNewContext } from "node:vm";
+import { defineModel, type ModelDef } from "../model";
+import { field } from "../fields";
+
+const SOURCE_EXT = /\.(ts|tsx|js|jsx|mjs)$/;
+const IGNORED = /(\.test\.|\.spec\.|\.d\.ts$|\.stories\.)/;
+const ALLOWED_IMPORT = /^\s*import\s+\{([^}]+)\}\s+from\s+["'](@backmatter\/core|@backmatter\/next)["']\s*;?\s*$/gm;
+const ALLOWED_NAMES = new Set(["defineModel", "field"]);
+const FORBIDDEN = [
+  { re: /\brequire\s*\(/, name: "require" },
+  { re: /\bimport\s*\(/, name: "import" },
+  { re: /\bprocess\b/, name: "process" },
+  { re: /\bBun\b/, name: "Bun" },
+  { re: /\bDeno\b/, name: "Deno" },
+  { re: /\bglobalThis\b/, name: "globalThis" },
+  { re: /\bFunction\s*\(/, name: "Function" },
+  { re: /\beval\s*\(/, name: "eval" },
+];
+const EVAL_TIMEOUT_MS = 1000;
+
+function isModelDef(value: unknown): value is ModelDef {
+  if (!value || typeof value !== "object") return false;
+  const m = value as Record<string, unknown>;
+  return typeof m.type === "string" && typeof m.path === "string" && typeof m.fields === "object";
+}
+
+/** True for a repo-relative `models/{type}.ts` (flat folder, same filters as listModelFiles). */
+export function isModelSourcePath(repoPath: string, modelsDir = "models"): boolean {
+  const normalized = repoPath.split("\\").join("/");
+  const prefix = `${modelsDir.replace(/\/+$/, "")}/`;
+  if (!normalized.startsWith(prefix)) return false;
+  const name = normalized.slice(prefix.length);
+  if (!name || name.includes("/")) return false;
+  if (name.startsWith("_") || name.startsWith(".")) return false;
+  return SOURCE_EXT.test(name) && !IGNORED.test(name);
+}
+
+function stemOf(repoPath: string): string {
+  const name = repoPath.split("\\").join("/").split("/").pop() ?? "";
+  return name.replace(SOURCE_EXT, "");
+}
+
+function stripAllowedImports(source: string): string {
+  const names = new Set<string>();
+  const stripped = source.replace(ALLOWED_IMPORT, (_full, specifiers: string) => {
+    for (const part of specifiers.split(",")) {
+      const name = part.trim();
+      if (!name) continue;
+      if (/\bas\b/.test(name) || !ALLOWED_NAMES.has(name)) {
+        throw new Error(`import "${name}" is not allowed; only defineModel and field`);
+      }
+      names.add(name);
+    }
+    return "";
+  });
+  if (/^\s*import\b/m.test(stripped)) {
+    throw new Error("import is not allowed except defineModel/field from @backmatter/core or @backmatter/next");
+  }
+  return stripped;
+}
+
+function assertNoForbidden(source: string): void {
+  for (const { re, name } of FORBIDDEN) {
+    if (re.test(source)) throw new Error(`${name} is not allowed in model files`);
+  }
+}
+
+function rewriteDefaultExport(source: string): string {
+  if (!/\bexport\s+default\b/.test(source)) {
+    throw new Error("must export default defineModel({ ... })");
+  }
+  const rewritten = source.replace(/\bexport\s+default\s+/, "return ");
+  if (/\bexport\b/.test(rewritten)) {
+    throw new Error("must export default defineModel({ ... })");
+  }
+  return rewritten;
+}
+
+function transpile(source: string): string {
+  const transpiler = new Bun.Transpiler({ loader: "ts", target: "node" });
+  return transpiler.transformSync(source);
+}
+
+/**
+ * Evaluate one convention model file. `stem` is the file name without extension
+ * and must equal `model.type`.
+ */
+export function evalModelSource(source: string, stem: string): ModelDef {
+  const body = rewriteDefaultExport(stripAllowedImports(source));
+  assertNoForbidden(body);
+  const wrapped = `(function () {\n${body}\n})()`;
+  const js = transpile(wrapped);
+  const sandbox = Object.create(null) as { defineModel: typeof defineModel; field: typeof field };
+  sandbox.defineModel = defineModel;
+  sandbox.field = field;
+  Object.freeze(sandbox);
+
+  let result: unknown;
+  try {
+    result = runInNewContext(js, sandbox, {
+      timeout: EVAL_TIMEOUT_MS,
+      filename: `${stem}.js`,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`model "${stem}" failed to evaluate: ${message}`);
+  }
+
+  if (!isModelDef(result)) {
+    throw new Error("must export default defineModel({ ... })");
+  }
+  if (result.type !== stem) {
+    throw new Error(
+      `defines type "${result.type}" but the file is named "${stem}"; rename one so they match`,
+    );
+  }
+  return result;
+}
+
+export function evalModelsFromTree(
+  files: Array<{ path: string; source: string }>,
+  modelsDir = "models",
+): ModelDef[] {
+  const models: ModelDef[] = [];
+  const types = new Set<string>();
+  const sorted = files
+    .filter((f) => isModelSourcePath(f.path, modelsDir))
+    .sort((a, b) => a.path.localeCompare(b.path));
+  for (const file of sorted) {
+    const stem = stemOf(file.path);
+    const model = evalModelSource(file.source, stem);
+    if (types.has(model.type)) {
+      throw new Error(`duplicate model type "${model.type}" (${file.path})`);
+    }
+    types.add(model.type);
+    models.push(model);
+  }
+  return models;
+}

package/src/node/fs-loader.ts

@@ -0,0 +1,96 @@
+// packages/core/src/node/fs-loader.ts
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  matchAnyModelPath,
+  modelFormat,
+  parseDoc,
+  repoPathFromModel,
+  type ModelSnapshot,
+} from "../index";
+import type { BackmatterDoc, BackmatterDocSummary } from "../doc";
+
+const SKIP_DIRS = new Set(["node_modules", ".next", ".git"]);
+
+const CONTENT_EXT = /\.(mdx|json)$/;
+
+export async function walkMdxFiles(rootDir: string): Promise<string[]> {
+  return walkContentFiles(rootDir);
+}
+
+export async function walkContentFiles(rootDir: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function walk(dir: string) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full);
+      } else if (entry.isFile() && CONTENT_EXT.test(entry.name)) {
+        out.push(full);
+      }
+    }
+  }
+
+  await walk(rootDir);
+  return out.sort();
+}
+
+export async function listDocsFromFs(
+  siteRoot: string,
+  models: ModelSnapshot[],
+): Promise<BackmatterDocSummary[]> {
+  const files = await walkContentFiles(siteRoot);
+  const docs: BackmatterDocSummary[] = [];
+  for (const full of files) {
+    const rel = path.relative(siteRoot, full).split(path.sep).join("/");
+    const hit = matchAnyModelPath(models, rel);
+    if (!hit) continue;
+    docs.push({
+      locale: hit.locale,
+      type: hit.type,
+      slug: hit.slug,
+    });
+  }
+  return docs.sort((a, b) => {
+    const ak = `${a.locale}/${a.type}/${a.slug}`;
+    const bk = `${b.locale}/${b.type}/${b.slug}`;
+    return ak.localeCompare(bk);
+  });
+}
+
+export async function getDocFromFs(
+  siteRoot: string,
+  models: ModelSnapshot[],
+  locale: string,
+  type: string,
+  slug: string,
+): Promise<BackmatterDoc | null> {
+  const model = models.find((m) => m.type === type);
+  if (!model) return null;
+  const rel = repoPathFromModel(model, locale, slug);
+  const full = path.join(siteRoot, rel);
+  let raw: string;
+  try {
+    raw = await readFile(full, "utf-8");
+  } catch {
+    return null;
+  }
+  const parsed = parseDoc(raw, modelFormat(model));
+  return {
+    locale,
+    type,
+    slug,
+    source: "head",
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+    raw,
+  };
+}