@llm-cms/core 0.0.1

package/src/model.ts

@@ -0,0 +1,182 @@
+// packages/core/src/model.ts
+import {
+  type FieldDef,
+  type FieldKind,
+  type FieldSnapshot,
+  parseFieldSnapshot,
+  serializeField,
+} from "./fields";
+
+export type ModelDef = {
+  type: string;
+  /** Repo-relative path template, e.g. content/{locale}/blog/{slug}.mdx */
+  path: string;
+  /**
+   * URL template for the host catch-all route, e.g. "/blog/{slug}".
+   * Defaults to "/{locale}/{type}/{slug}" when omitted (see routes.ts).
+   */
+  route?: string;
+  fields: Record<string, FieldDef>;
+};
+
+/** What `defineModel` accepts: `path` falls back to the folder convention. */
+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 function defaultModelPath(type: string): string {
+  return DEFAULT_MODEL_PATH.replaceAll("{type}", type);
+}
+
+export type ModelSnapshot = {
+  type: string;
+  path: string;
+  route?: string;
+  fields: Record<string, FieldSnapshot>;
+};
+
+export type SchemaSnapshot = {
+  version: number;
+  models: ModelSnapshot[];
+};
+
+type WithPath<D extends ModelInput> = D extends { path: string } ? D : D & { path: string };
+
+/**
+ * Validates the definition at runtime and preserves its literal types.
+ * `path` defaults to `content/{locale}/{type}/{slug}.mdx`.
+ */
+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 (typeof path !== "string" || !path) {
+    throw new Error("model.path must be a non-empty string");
+  }
+  if (!path.includes("{locale}") || !path.includes("{slug}")) {
+    throw new Error("model.path must include {locale} and {slug}");
+  }
+  if (def.route !== undefined) {
+    if (typeof def.route !== "string" || !def.route.startsWith("/")) {
+      throw new Error('model.route must start with "/"');
+    }
+    if (!def.route.includes("{slug}")) {
+      throw new Error("model.route must include {slug}");
+    }
+  }
+  if (!def.fields || typeof def.fields !== "object") {
+    throw new Error("model.fields is required");
+  }
+  return (def.path === undefined ? { ...def, path } : def) as WithPath<D>;
+}
+
+type Simplify<T> = { -readonly [K in keyof T]: T[K] } & {};
+
+type ScalarOf<K extends FieldKind> = K extends "number"
+  ? number
+  : K extends "boolean"
+    ? boolean
+    : string;
+
+type IsRequired<F> = F extends { required?: infer R }
+  ? [Exclude<R, undefined>] extends [true]
+    ? true
+    : false
+  : false;
+
+/** TypeScript shape of a model's frontmatter, derived from `field.*` calls. */
+export type InferFrontmatter<M extends ModelDef> = Simplify<
+  {
+    [N in keyof M["fields"] as IsRequired<M["fields"][N]> extends true
+      ? N
+      : never]: ScalarOf<M["fields"][N]["kind"]>;
+  } & {
+    [N in keyof M["fields"] as IsRequired<M["fields"][N]> extends true
+      ? never
+      : N]?: ScalarOf<M["fields"][N]["kind"]>;
+  }
+>;
+
+export function serializeModel(model: ModelDef): ModelSnapshot {
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, def] of Object.entries(model.fields)) {
+    fields[name] = serializeField(def);
+  }
+  const snapshot: ModelSnapshot = {
+    type: model.type,
+    path: model.path,
+    fields,
+  };
+  if (model.route !== undefined) snapshot.route = model.route;
+  return snapshot;
+}
+
+export function serializeSchema(models: ModelDef[]): SchemaSnapshot {
+  return {
+    version: 1,
+    models: models.map(serializeModel),
+  };
+}
+
+export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
+  if (!input || typeof input !== "object") {
+    throw new Error("schema must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  const version = value.version;
+  if (typeof version !== "number" || !Number.isInteger(version) || version < 1) {
+    throw new Error("schema.version must be a positive integer");
+  }
+  if (!Array.isArray(value.models)) {
+    throw new Error("schema.models must be an array");
+  }
+  const models: ModelSnapshot[] = value.models.map((raw, i) => {
+    if (!raw || typeof raw !== "object") {
+      throw new Error(`schema.models[${i}] must be an object`);
+    }
+    const m = raw as Record<string, unknown>;
+    if (typeof m.type !== "string" || !m.type) {
+      throw new Error(`schema.models[${i}].type is required`);
+    }
+    if (typeof m.path !== "string" || !m.path) {
+      throw new Error(`schema.models[${i}].path is required`);
+    }
+    if (!m.path.includes("{locale}") || !m.path.includes("{slug}")) {
+      throw new Error(
+        `schema.models[${i}].path must include {locale} and {slug}`,
+      );
+    }
+    if (m.route !== undefined && (typeof m.route !== "string" || !m.route.startsWith("/"))) {
+      throw new Error(`schema.models[${i}].route must be a string starting with "/"`);
+    }
+    if (!m.fields || typeof m.fields !== "object" || Array.isArray(m.fields)) {
+      throw new Error(`schema.models[${i}].fields must be an object`);
+    }
+    const fields: Record<string, FieldSnapshot> = {};
+    for (const [name, fieldRaw] of Object.entries(
+      m.fields as Record<string, unknown>,
+    )) {
+      try {
+        fields[name] = parseFieldSnapshot(fieldRaw);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "invalid field";
+        throw new Error(`schema.models[${i}].fields.${name}: ${msg}`);
+      }
+    }
+    const snapshot: ModelSnapshot = { type: m.type, path: m.path, fields };
+    if (typeof m.route === "string") snapshot.route = m.route;
+    return snapshot;
+  });
+
+  const types = new Set<string>();
+  for (const m of models) {
+    if (types.has(m.type)) {
+      throw new Error(`duplicate model type: ${m.type}`);
+    }
+    types.add(m.type);
+  }
+
+  return { version, models };
+}

package/src/node/cli.ts

@@ -0,0 +1,387 @@
+#!/usr/bin/env bun
+// packages/core/src/node/cli.ts
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  frontmatterJsonSchema,
+  serializeModel,
+  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 { detectSdk, findConfigFile, generate, type GenerateResult } from "./generate";
+
+export type CliArgs = {
+  command?: string;
+  root: string;
+  /** Optional barrel module exporting `models`; default is folder discovery. */
+  models?: string;
+  out: string;
+  json: boolean;
+};
+
+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 validate  [--root <dir>] [--models <file>] [--json]
+  llmcms schema    [--root <dir>] [--models <file>] [--out <dir>]
+
+Defaults: --root .  --out .llmcms/schemas
+Models are discovered from models/*.ts (one \`export default defineModel(...)\` per
+file, file name = model type). Pass --models <file> to use a module that exports
+\`models\` instead. Importing your code sets LLMCMS_CLI=1 so createLlmcms never
+syncs the schema from the CLI.`;
+
+export function parseArgs(argv: string[]): CliArgs {
+  const args: CliArgs = {
+    command: undefined,
+    root: ".",
+    models: undefined,
+    out: ".llmcms/schemas",
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--root") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error("usage: missing value for --root");
+      }
+      args.root = value;
+    } else if (arg === "--models") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error("usage: missing value for --models");
+      }
+      args.models = value;
+    } else if (arg === "--out") {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error("usage: missing value for --out");
+      }
+      args.out = value;
+    } else if (arg === "--json") {
+      args.json = true;
+    } else if (arg.startsWith("--")) {
+      throw new Error(`usage: unknown flag ${arg}`);
+    } else if (args.command === undefined) {
+      args.command = arg;
+    } else {
+      throw new Error("usage: unexpected positional argument");
+    }
+  }
+  return args;
+}
+
+/** Run `fn` with LLMCMS_CLI=1 so imported host code never syncs the schema. */
+async function withCliFlag<T>(fn: () => Promise<T>): Promise<T> {
+  const prevCli = process.env.LLMCMS_CLI;
+  process.env.LLMCMS_CLI = "1";
+  try {
+    return await fn();
+  } finally {
+    if (prevCli === undefined) delete process.env.LLMCMS_CLI;
+    else process.env.LLMCMS_CLI = prevCli;
+  }
+}
+
+/** Import `llmcms.config.ts` (default export) when present; `{}` otherwise. */
+export async function loadConfig(root: string): Promise<ResolvedConfig> {
+  const file = findConfigFile(root);
+  if (!file) return resolveConfig({});
+  const mod = await withCliFlag(
+    () =>
+      import(/* webpackIgnore: true */ /* turbopackIgnore: true */ pathToFileURL(file).href) as Promise<{ default?: unknown; config?: unknown }>,
+  );
+  const candidate = mod.default ?? mod.config;
+  if (candidate !== undefined && (typeof candidate !== "object" || candidate === null)) {
+    throw new Error(`${path.basename(file)} must \`export default defineConfig({ ... })\``);
+  }
+  return resolveConfig((candidate ?? {}) as LlmcmsConfig);
+}
+
+/**
+ * Models from the `models/` folder (default) or from an explicit barrel module
+ * that exports `models` / a default array.
+ */
+export async function loadModels(root: string, modelsPath?: string): Promise<ModelDef[]> {
+  if (modelsPath === undefined) {
+    const config = await loadConfig(root);
+    return withCliFlag(() => discoverModels(root, config.dirs.models));
+  }
+  const full = path.resolve(root, modelsPath);
+  const mod = await withCliFlag(
+    () =>
+      import(/* webpackIgnore: true */ /* turbopackIgnore: true */ pathToFileURL(full).href) as Promise<{ models?: unknown; default?: unknown }>,
+  );
+  const candidate = mod.models ?? mod.default;
+  if (!Array.isArray(candidate)) {
+    throw new Error(
+      `${modelsPath} must export \`models\` (array of defineModel results) or a default array`,
+    );
+  }
+  return candidate as ModelDef[];
+}
+
+/**
+ * Static directory roots the models' path templates live under, e.g.
+ * `content/{locale}/blog/{slug}.mdx` → `content`. Roots that are sub-paths of
+ * another root are dropped; a template with no static leading segment yields ".".
+ */
+export function contentRoots(models: ModelSnapshot[]): string[] {
+  const candidates = new Set<string>();
+  for (const model of models) {
+    const segments = model.path.split("/").slice(0, -1); // drop the filename segment
+    const leading: string[] = [];
+    for (const segment of segments) {
+      if (segment.includes("{")) break;
+      leading.push(segment);
+    }
+    candidates.add(leading.length > 0 ? leading.join("/") : ".");
+  }
+  const list = [...candidates];
+  return list
+    .filter(
+      (root) =>
+        !list.some(
+          (other) =>
+            other !== root && (other === "." || root.startsWith(`${other}/`)),
+        ),
+    )
+    .sort();
+}
+
+export async function runValidate(
+  args: CliArgs,
+): Promise<{ results: ContentFileResult[]; roots: string[]; exitCode: 0 | 1 }> {
+  const root = path.resolve(args.root);
+  const models = (await loadModels(root, args.models)).map(serializeModel);
+  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.sort();
+  const inputs = await Promise.all(
+    files.map(async (full) => ({
+      path: path.relative(root, full).split(path.sep).join("/"),
+      raw: await readFile(full, "utf-8"),
+    })),
+  );
+  const results = validateContentTree({ models, files: inputs });
+  return { results, roots, exitCode: results.some((r) => !r.ok) ? 1 : 0 };
+}
+
+export function formatResults(results: ContentFileResult[]): string[] {
+  const lines: string[] = [];
+  for (const r of results) {
+    if (!r.ok) {
+      for (const err of r.errors) lines.push(`${r.path}: ${err}`);
+    } else if ("skipped" in r) {
+      lines.push(`${r.path}: no matching model (skipped)`);
+    }
+  }
+  return lines;
+}
+
+export async function runSchema(args: CliArgs): Promise<string[]> {
+  const root = path.resolve(args.root);
+  const models = (await loadModels(root, args.models)).map(serializeModel);
+  const outDir = path.resolve(root, args.out);
+  await mkdir(outDir, { recursive: true });
+  const written: string[] = [];
+  for (const model of models) {
+    const file = path.join(outDir, `${model.type}.json`);
+    await writeFile(file, `${JSON.stringify(frontmatterJsonSchema(model), null, 2)}\n`);
+    written.push(path.relative(root, file).split(path.sep).join("/"));
+  }
+  return written;
+}
+
+export async function runGenerate(args: CliArgs): Promise<GenerateResult> {
+  const root = path.resolve(args.root);
+  // Codegen must not depend on the host's dependencies being installed yet
+  // (e.g. right after `init`); fall back to default folders if the config
+  // cannot be imported.
+  let config: ResolvedConfig;
+  try {
+    config = await loadConfig(root);
+  } catch (err) {
+    console.error(
+      `llmcms: could not load llmcms.config (${err instanceof Error ? err.message : String(err)}); using default folders`,
+    );
+    config = resolveConfig({});
+  }
+  return generate({ root, modelsDir: config.dirs.models, blocksDir: config.dirs.blocks });
+}
+
+const CATCH_ALL_DIR = "[...llmcms]";
+
+function renderConfigFile(sdk: string): string {
+  const from = sdk === "@llm-cms/next" ? "@llm-cms/next" : "@llm-cms/core";
+  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.
+// workspaceId / apiUrl / tokens fall back to LLMCMS_* env vars when omitted.
+export default defineConfig({
+  defaultLocale: "en",
+});
+`;
+}
+
+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 { blocks } from "${registryImport}/blocks";
+
+const route = createCatchAll(cms, { components: blocks });
+
+export const generateStaticParams = route.generateStaticParams;
+export default route.Page;
+`;
+}
+
+function renderRevalidateRoute(registryImport: string): string {
+  return `// api/llmcms/revalidate/route.ts — content.committed from the LLMCMS server.
+import { createRevalidateRoute } from "@llm-cms/next/revalidate";
+import { cms } from "${registryImport}";
+
+export const POST = createRevalidateRoute(cms);
+`;
+}
+
+export async function runInit(args: CliArgs): Promise<string[]> {
+  const root = path.resolve(args.root);
+  const sdk = detectSdk(root);
+  const notes: string[] = [];
+
+  if (!findConfigFile(root)) {
+    await writeFile(path.join(root, "llmcms.config.ts"), renderConfigFile(sdk));
+    notes.push("wrote llmcms.config.ts");
+  } else {
+    notes.push("kept existing llmcms.config.*");
+  }
+
+  const gitignore = path.join(root, ".gitignore");
+  const current = existsSync(gitignore) ? await readFile(gitignore, "utf-8") : "";
+  if (!current.split("\n").some((line) => line.trim() === ".llmcms/" || line.trim() === ".llmcms")) {
+    const prefix = current.length && !current.endsWith("\n") ? "\n" : "";
+    await appendFile(gitignore, `${prefix}# llmcms generated registry\n.llmcms/\n`);
+    notes.push("added .llmcms/ to .gitignore");
+  }
+
+  if (sdk === "@llm-cms/next") {
+    const appDir = existsSync(path.join(root, "src", "app")) ? path.join("src", "app") : "app";
+    const pageDir = path.join(root, appDir, CATCH_ALL_DIR);
+    const page = path.join(pageDir, "page.tsx");
+    if (!existsSync(page)) {
+      const registry = path.relative(pageDir, path.join(root, ".llmcms")).split(path.sep).join("/");
+      await mkdir(pageDir, { recursive: true });
+      await writeFile(page, renderCatchAllPage(registry.startsWith(".") ? registry : `./${registry}`));
+      notes.push(`wrote ${path.join(appDir, CATCH_ALL_DIR, "page.tsx")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, CATCH_ALL_DIR, "page.tsx")}`);
+    }
+
+    const revalidateDir = path.join(root, appDir, "api", "llmcms", "revalidate");
+    const revalidateFile = path.join(revalidateDir, "route.ts");
+    if (!existsSync(revalidateFile)) {
+      const registry = path.relative(revalidateDir, path.join(root, ".llmcms")).split(path.sep).join("/");
+      await mkdir(revalidateDir, { recursive: true });
+      await writeFile(
+        revalidateFile,
+        renderRevalidateRoute(registry.startsWith(".") ? registry : `./${registry}`),
+      );
+      notes.push(`wrote ${path.join(appDir, "api/llmcms/revalidate/route.ts")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, "api/llmcms/revalidate/route.ts")}`);
+    }
+  } else {
+    notes.push("no @llm-cms/next dependency: skipped the catch-all route");
+  }
+
+  for (const dir of ["models", "content", "blocks"]) {
+    await mkdir(path.join(root, dir), { recursive: true });
+  }
+
+  const result = await runGenerate(args);
+  notes.push(...result.files.map((f) => `wrote ${f}`));
+  return notes;
+}
+
+async function main(argv: string[]): Promise<number> {
+  let args: CliArgs;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("usage:")) {
+      console.error(err.message);
+      console.error(USAGE);
+      return 2;
+    }
+    console.error(`llmcms: ${err instanceof Error ? err.message : String(err)}`);
+    return 2;
+  }
+  try {
+    if (args.command === "validate") {
+      const { results, roots, exitCode } = await runValidate(args);
+      if (results.length === 0) {
+        console.error(
+          `llmcms: no .mdx files found under ${roots.join(", ")} (check --root)`,
+        );
+      }
+      if (args.json) {
+        console.log(JSON.stringify(results, null, 2));
+      } else {
+        for (const line of formatResults(results)) console.log(line);
+        const checked = results.filter((r) => !("skipped" in r)).length;
+        console.log(
+          exitCode === 0
+            ? `llmcms: ${checked} document(s) valid`
+            : `llmcms: validation failed`,
+        );
+      }
+      return exitCode;
+    }
+    if (args.command === "schema") {
+      const written = await runSchema(args);
+      for (const file of written) console.log(`wrote ${file}`);
+      return 0;
+    }
+    if (args.command === "generate") {
+      const result = await runGenerate(args);
+      for (const file of result.files) {
+        console.log(`${result.changed.includes(file) ? "wrote" : "unchanged"} ${file}`);
+      }
+      for (const skipped of result.skippedBlocks) {
+        console.error(`llmcms: skipped ${skipped} (block file names must be PascalCase)`);
+      }
+      return 0;
+    }
+    if (args.command === "init") {
+      for (const note of await runInit(args)) console.log(note);
+      return 0;
+    }
+    console.error(USAGE);
+    return 2;
+  } catch (err) {
+    console.error(`llmcms: ${err instanceof Error ? err.message : String(err)}`);
+    return 2;
+  }
+}
+
+if (import.meta.main) {
+  main(process.argv.slice(2)).then((code) => process.exit(code));
+}

package/src/node/create-llmcms.ts

@@ -0,0 +1,125 @@
+// packages/core/src/node/create-llmcms.ts
+import type { ModelDef, ModelSnapshot } from "../model";
+import { getDocFromApi, listDocsFromApi } from "../api-loader";
+import { getDocFromFs, listDocsFromFs } from "./fs-loader";
+import { createQuery, type DocLoader, type Query } from "../query";
+import { syncSchema } from "../sync-schema";
+import type { LlmcmsDoc, LlmcmsDocSummary } from "../doc";
+import { resolveConfig, type LlmcmsConfig, type ResolvedConfig } from "../config";
+import { contentCacheTags, listCacheTags } from "../content-committed";
+
+/**
+ * `LlmcmsConfig` (usually spread from `llmcms.config.ts`) plus the discovered
+ * models. Unset fields fall back to `LLMCMS_*` env vars.
+ */
+export type CreateLlmcmsOptions<Models extends readonly ModelDef[] = readonly ModelDef[]> =
+  LlmcmsConfig & {
+    models: Models;
+    /**
+     * When true, API fetches use Next cache tags instead of `cache: "no-store"`.
+     * `@llm-cms/next` turns this on.
+     */
+    taggedApiFetch?: boolean;
+  };
+
+export type LlmcmsClient<Models extends readonly ModelDef[] = readonly ModelDef[]> = {
+  listDocs: (filter?: {
+    type?: string;
+    locale?: string;
+  }) => Promise<LlmcmsDocSummary[]>;
+  getDoc: (
+    locale: string,
+    type: string,
+    slug: string,
+  ) => Promise<LlmcmsDoc | null>;
+  /** Typed access keyed by model.type: cms.query.blog.get / findMany */
+  query: Query<Models>;
+  /** The registered models, e.g. for route matching. */
+  models: Models;
+  /** Effective config after env fallbacks. */
+  config: ResolvedConfig;
+};
+
+function toSnapshots(models: readonly ModelDef[]): ModelSnapshot[] {
+  return models.map((m) => {
+    const snapshot: ModelSnapshot = {
+      type: m.type,
+      path: m.path,
+      fields: m.fields as ModelSnapshot["fields"],
+    };
+    if (m.route !== undefined) snapshot.route = m.route;
+    return snapshot;
+  });
+}
+
+export function createLlmcms<const Models extends readonly ModelDef[]>(
+  options: CreateLlmcmsOptions<Models>,
+): LlmcmsClient<Models> {
+  const { models: modelDefs, taggedApiFetch, ...rest } = options;
+  const config = resolveConfig(rest);
+  const models = toSnapshots(modelDefs);
+  const siteRoot = config.siteRoot ?? process.cwd();
+  const useApi = Boolean(config.apiUrl && config.workspaceId);
+  const { workspaceId, apiUrl, contentToken, hostToken, branch, siteUrl } = config;
+
+  if (apiUrl && !workspaceId) {
+    throw new Error(
+      "llmcms: workspaceId is required when apiUrl is set (llmcms.config.ts or LLMCMS_WORKSPACE_ID)",
+    );
+  }
+
+  // llmcms CLI imports the config to read models; never sync from there.
+  if (apiUrl && hostToken && workspaceId) {
+    if (process.env.LLMCMS_CLI === "1") {
+      console.warn("llmcms: schema sync skipped (LLMCMS_CLI=1)");
+    } else {
+      void syncSchema({
+        apiUrl,
+        workspaceId,
+        hostToken,
+        models: [...modelDefs],
+        branch: config.branch,
+        siteUrl,
+      }).catch((err) => {
+        console.error("llmcms schema sync failed", err);
+      });
+    }
+  }
+
+  const loader: DocLoader = {
+    async listDocs(filter) {
+      const docs = useApi
+        ? await listDocsFromApi(apiUrl!, workspaceId!, contentToken, {
+            branch,
+            type: filter?.type,
+            locale: filter?.locale,
+            tags: taggedApiFetch ? listCacheTags(filter?.type) : undefined,
+          })
+        : await listDocsFromFs(siteRoot, models);
+
+      return docs.filter((d) => {
+        if (filter?.type && d.type !== filter.type) return false;
+        if (filter?.locale && d.locale !== filter.locale) return false;
+        return true;
+      });
+    },
+
+    async getDoc(locale, type, slug) {
+      if (useApi) {
+        return getDocFromApi(apiUrl!, workspaceId!, contentToken, locale, type, slug, {
+          branch,
+          tags: taggedApiFetch ? contentCacheTags(locale, type, slug) : undefined,
+        });
+      }
+      return getDocFromFs(siteRoot, models, locale, type, slug);
+    },
+  };
+
+  return {
+    listDocs: loader.listDocs,
+    getDoc: loader.getDoc,
+    query: createQuery(modelDefs, loader),
+    models: modelDefs,
+    config,
+  };
+}