@llm-cms/core 0.0.1

package/src/preview.ts

@@ -0,0 +1,127 @@
+// packages/core/src/preview.ts
+import type { LlmcmsDoc } from "./doc";
+
+export type PreviewDocRef = {
+  locale: string;
+  type: string;
+  slug: string;
+  /** Editor checkout branch. Omit to read the workspace default branch. */
+  branch?: string;
+  /**
+   * Working tree owner (the editing user's id). With it the preview shows that
+   * user's uncommitted copy and streams their saves; without it, branch HEAD.
+   */
+  tree?: string;
+};
+
+export type PreviewChangeEvent = PreviewDocRef & {
+  updatedAt: string;
+  frontmatter?: Record<string, unknown>;
+  body?: string;
+  raw?: string;
+};
+
+export type PreviewClientOptions = {
+  apiUrl: string;
+  workspaceId: string;
+  previewToken: string;
+};
+
+export {
+  installPreviewHotkeys,
+  parsePreviewHotkey,
+  previewHotkeyFromKeyboardEvent,
+} from "./preview-hotkeys";
+export type { PreviewHotkeyMessage } from "./preview-hotkeys";
+
+function baseUrl(apiUrl: string) {
+  return apiUrl.replace(/\/$/, "");
+}
+
+/** First non-empty value from a Next.js `searchParams` field. */
+function queryValue(value: string | string[] | undefined): string | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  const trimmed = raw?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+/**
+ * Read `branch` and `tree` off the host preview URL so the snapshot and SSE
+ * match the editor checkout. Empty values mean branch HEAD (no live stream).
+ */
+export function previewCheckoutFromQuery(query: {
+  branch?: string | string[];
+  tree?: string | string[];
+}): Pick<PreviewDocRef, "branch" | "tree"> {
+  const branch = queryValue(query.branch);
+  const tree = queryValue(query.tree);
+  return {
+    ...(branch ? { branch } : {}),
+    ...(tree ? { tree } : {}),
+  };
+}
+
+function previewParams(options: PreviewClientOptions, ref: PreviewDocRef) {
+  const params = new URLSearchParams({ token: options.previewToken });
+  if (ref.branch) params.set("branch", ref.branch);
+  if (ref.tree) params.set("tree", ref.tree);
+  return params;
+}
+
+function docPath(options: PreviewClientOptions, ref: PreviewDocRef) {
+  return `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/docs/${ref.locale}/${ref.type}/${ref.slug}`;
+}
+
+export function previewDocRequestUrl(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+): string {
+  return `${docPath(options, ref)}?${previewParams(options, ref)}`;
+}
+
+export function previewStreamUrl(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+): string {
+  return `${docPath(options, ref)}/stream?${previewParams(options, ref)}`;
+}
+
+export async function fetchPreviewDoc(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+): Promise<LlmcmsDoc | null> {
+  const url = previewDocRequestUrl(options, ref);
+  const res = await fetch(url, { cache: "no-store" });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`preview getDoc failed: ${res.status}`);
+  const data = (await res.json()) as { doc: LlmcmsDoc };
+  return data.doc;
+}
+
+/** Browser EventSource subscribe to one working tree's saves; returns unsubscribe. */
+export function subscribePreview(
+  options: PreviewClientOptions,
+  ref: PreviewDocRef,
+  onEvent: (event: PreviewChangeEvent) => void,
+): () => void {
+  if (typeof EventSource === "undefined") {
+    throw new Error("subscribePreview requires a browser EventSource");
+  }
+  const source = new EventSource(previewStreamUrl(options, ref));
+
+  const onChange = (ev: MessageEvent) => {
+    try {
+      const data = JSON.parse(String(ev.data)) as PreviewChangeEvent;
+      onEvent(data);
+    } catch {
+      // ignore malformed
+    }
+  };
+
+  source.addEventListener("change", onChange as EventListener);
+
+  return () => {
+    source.removeEventListener("change", onChange as EventListener);
+    source.close();
+  };
+}

package/src/query.ts

@@ -0,0 +1,152 @@
+// packages/core/src/query.ts
+import type { LlmcmsDoc, LlmcmsDocSummary } from "./doc";
+import type { FieldKind } from "./fields";
+import type { InferFrontmatter, ModelDef } from "./model";
+import { normalizeFrontmatter } from "./zod";
+
+/** Loader the query layer sits on: the FS or API loaders behind createLlmcms. */
+export type DocLoader = {
+  listDocs(filter?: { type?: string; locale?: string }): Promise<LlmcmsDocSummary[]>;
+  getDoc(locale: string, type: string, slug: string): Promise<LlmcmsDoc | null>;
+};
+
+export type TypedDoc<M extends ModelDef> = Omit<LlmcmsDoc, "type" | "frontmatter"> & {
+  type: M["type"];
+  frontmatter: InferFrontmatter<M>;
+};
+
+type KeysOfKind<M extends ModelDef, K extends FieldKind> = {
+  [N in keyof M["fields"]]: M["fields"][N]["kind"] extends K ? N : never;
+}[keyof M["fields"]];
+
+type ScalarKind = "text" | "slug" | "locale" | "number" | "boolean";
+
+/** Equality filters on slug and scalar frontmatter fields. */
+export type Where<M extends ModelDef> = Partial<
+  { slug: string } & Pick<
+    InferFrontmatter<M>,
+    Extract<KeysOfKind<M, ScalarKind>, keyof InferFrontmatter<M>>
+  >
+>;
+
+/** Relation fields that may be resolved (depth 1, same locale). */
+export type Include<M extends ModelDef> = Partial<Record<KeysOfKind<M, "relation">, true>>;
+
+type RelationTarget<
+  M extends ModelDef,
+  N extends keyof M["fields"],
+  Models extends readonly ModelDef[],
+> = M["fields"][N] extends { relationTo?: infer To }
+  ? Extract<Models[number], { type: Exclude<To, undefined> }>
+  : never;
+
+export type Resolved<
+  M extends ModelDef,
+  Models extends readonly ModelDef[],
+  I extends Include<M>,
+> = {
+  [N in keyof I as I[N] extends true ? N : never]: N extends keyof M["fields"]
+    ? TypedDoc<RelationTarget<M, N, Models>> | null
+    : never;
+};
+
+export type ModelQuery<M extends ModelDef, Models extends readonly ModelDef[]> = {
+  get(locale: string, slug: string): Promise<TypedDoc<M> | null>;
+  findMany<I extends Include<M> = {}>(opts?: {
+    locale?: string;
+    where?: Where<M>;
+    include?: I;
+  }): Promise<Array<TypedDoc<M> & Resolved<M, Models, I>>>;
+};
+
+export type Query<Models extends readonly ModelDef[]> = {
+  [M in Models[number] as M["type"]]: ModelQuery<M, Models>;
+};
+
+type RawOpts = {
+  locale?: string;
+  where?: Record<string, unknown>;
+  include?: Record<string, boolean | undefined>;
+};
+
+export function createQuery<const Models extends readonly ModelDef[]>(
+  models: Models,
+  loader: DocLoader,
+): Query<Models> {
+  const byType = new Map<string, ModelDef>(models.map((m) => [m.type, m]));
+
+  async function get(type: string, locale: string, slug: string): Promise<LlmcmsDoc | null> {
+    const doc = await loader.getDoc(locale, type, slug);
+    if (!doc) return null;
+    return { ...doc, frontmatter: normalizeFrontmatter(doc.frontmatter) };
+  }
+
+  function matchesWhere(doc: LlmcmsDoc, where: Record<string, unknown>): boolean {
+    for (const [key, expected] of Object.entries(where)) {
+      if (expected === undefined) continue;
+      const actual = key === "slug" ? doc.slug : doc.frontmatter[key];
+      if (actual !== expected) return false;
+    }
+    return true;
+  }
+
+  async function findMany(type: string, opts?: RawOpts): Promise<LlmcmsDoc[]> {
+    const model = byType.get(type);
+    const whereSlug = opts?.where?.slug;
+
+    let docs: LlmcmsDoc[];
+    // Truthy gate: the loaders' locale filter is truthiness-based, so a falsy
+    // locale ("") must fall back to the list path like an omitted one.
+    if (typeof whereSlug === "string" && opts?.locale) {
+      // Slug fast-path: identity lookup instead of list + load fan-out.
+      const doc = await get(type, opts.locale, whereSlug);
+      docs = doc ? [doc] : [];
+    } else {
+      const summaries = await loader.listDocs({ type, locale: opts?.locale });
+      const loaded = await Promise.all(summaries.map((s) => get(type, s.locale, s.slug)));
+      docs = loaded.filter((d): d is LlmcmsDoc => d !== null);
+    }
+
+    const filtered = opts?.where ? docs.filter((d) => matchesWhere(d, opts.where!)) : docs;
+    const include = opts?.include;
+    if (!include || !model) return filtered;
+
+    // Memoize relation loads per call: N posts sharing one author load it once.
+    const relationCache = new Map<string, Promise<LlmcmsDoc | null>>();
+    const getCached = (target: string, locale: string, slug: string) => {
+      const key = `${target}:${locale}:${slug}`;
+      let promise = relationCache.get(key);
+      if (!promise) {
+        promise = get(target, locale, slug);
+        relationCache.set(key, promise);
+      }
+      return promise;
+    };
+
+    return Promise.all(
+      filtered.map(async (doc) => {
+        const extra: Record<string, LlmcmsDoc | null> = {};
+        for (const [name, on] of Object.entries(include)) {
+          if (!on) continue;
+          const field = model.fields[name];
+          const target = field?.kind === "relation" ? field.relationTo : undefined;
+          const slug = doc.frontmatter[name];
+          extra[name] =
+            target && typeof slug === "string" && slug.length > 0
+              ? await getCached(target, doc.locale, slug)
+              : null;
+        }
+        return { ...doc, ...extra };
+      }),
+    );
+  }
+
+  const query: Record<string, unknown> = {};
+  for (const m of models) {
+    query[m.type] = {
+      get: (locale: string, slug: string) => get(m.type, locale, slug),
+      findMany: (opts?: RawOpts) => findMany(m.type, opts),
+    };
+  }
+  return query as Query<Models>;
+}

package/src/routes.ts

@@ -0,0 +1,102 @@
+// packages/core/src/routes.ts
+// Pure URL ↔ document mapping for the host catch-all route. No framework code.
+import type { ModelSnapshot } from "./model";
+
+export const DEFAULT_ROUTE = "/{locale}/{type}/{slug}";
+
+export type RouteModel = Pick<ModelSnapshot, "type" | "route">;
+
+export type RouteMatch = {
+  type: string;
+  locale: string;
+  slug: string;
+};
+
+export type MatchRouteOptions = {
+  /** Locale for routes without a `{locale}` placeholder. */
+  defaultLocale: string;
+  /** When set, `{locale}` only matches one of these values. */
+  locales?: readonly string[];
+};
+
+/** The model's route template with `{type}` already substituted. */
+export function routeTemplate(model: RouteModel): string {
+  return (model.route ?? DEFAULT_ROUTE).replaceAll("{type}", model.type);
+}
+
+/** Build the public URL path for a document, e.g. "/en/blog/hello". */
+export function routeFor(model: RouteModel, locale: string, slug: string): string {
+  return routeTemplate(model)
+    .replaceAll("{locale}", encodeURIComponent(locale))
+    .replaceAll("{slug}", slug.split("/").map(encodeURIComponent).join("/"));
+}
+
+/** URL segments for Next `generateStaticParams` (["en", "blog", "hello"]). */
+export function routeSegments(model: RouteModel, locale: string, slug: string): string[] {
+  return routeFor(model, locale, slug)
+    .split("/")
+    .filter(Boolean)
+    .map(decodeURIComponent);
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function compileRoutePattern(template: string): RegExp {
+  const parts = template.split(/(\{locale\}|\{slug\})/g);
+  let pattern = "^";
+  for (const part of parts) {
+    if (part === "{locale}") pattern += "(?<locale>[^/]+)";
+    else if (part === "{slug}") pattern += "(?<slug>[^/]+)";
+    else pattern += escapeRegex(part);
+  }
+  return new RegExp(`${pattern}/?$`);
+}
+
+function specificity(template: string): [staticSegments: number, placeholders: number] {
+  const segments = template.split("/").filter(Boolean);
+  const placeholders = segments.filter((s) => s.includes("{")).length;
+  return [segments.length - placeholders, placeholders];
+}
+
+/** Most static segments first, then fewer placeholders, then declaration order. */
+export function sortByRouteSpecificity<M extends RouteModel>(models: readonly M[]): M[] {
+  return models
+    .map((model, index) => ({ model, index, spec: specificity(routeTemplate(model)) }))
+    .sort((a, b) => {
+      if (a.spec[0] !== b.spec[0]) return b.spec[0] - a.spec[0];
+      if (a.spec[1] !== b.spec[1]) return a.spec[1] - b.spec[1];
+      return a.index - b.index;
+    })
+    .map((entry) => entry.model);
+}
+
+export function normalizePathname(pathname: string): string {
+  let out = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  if (out.length > 1) out = out.replace(/\/+$/, "");
+  return out;
+}
+
+/** Resolve a URL path to a document identity, or null when no model claims it. */
+export function matchRoute(
+  models: readonly RouteModel[],
+  pathname: string,
+  options: MatchRouteOptions,
+): RouteMatch | null {
+  const target = normalizePathname(pathname);
+  for (const model of sortByRouteSpecificity(models)) {
+    const template = routeTemplate(model);
+    const m = compileRoutePattern(template).exec(target);
+    if (!m?.groups?.slug) continue;
+    let locale = options.defaultLocale;
+    if (template.includes("{locale}")) {
+      const raw = m.groups.locale;
+      if (!raw) continue;
+      locale = decodeURIComponent(raw);
+      if (options.locales && !options.locales.includes(locale)) continue;
+    }
+    return { type: model.type, locale, slug: decodeURIComponent(m.groups.slug) };
+  }
+  return null;
+}

package/src/sync-schema.ts

@@ -0,0 +1,50 @@
+// packages/core/src/sync-schema.ts
+import {
+  serializeSchema,
+  type ModelDef,
+  type ModelSnapshot,
+} from "./model";
+
+export function detectGitBranch(
+  env: Record<string, string | undefined> = process.env,
+): string | null {
+  const override = env.LLMCMS_GIT_BRANCH?.trim();
+  if (override) return override;
+  const vercel = env.VERCEL_GIT_COMMIT_REF?.trim();
+  if (vercel) return vercel;
+  return null;
+}
+
+export type SyncSchemaOptions = {
+  apiUrl: string;
+  workspaceId: string;
+  hostToken: string;
+  models: Array<ModelDef | ModelSnapshot>;
+  branch?: string;
+  siteUrl?: string;
+};
+
+export async function syncSchema(options: SyncSchemaOptions): Promise<void> {
+  const branch = options.branch ?? detectGitBranch() ?? "main";
+  const payload = serializeSchema(options.models as ModelDef[]);
+  const body: { payload: ReturnType<typeof serializeSchema>; branch: string; siteUrl?: string } = {
+    payload,
+    branch,
+  };
+  if (options.siteUrl) body.siteUrl = options.siteUrl;
+  const res = await fetch(
+    `${options.apiUrl.replace(/\/$/, "")}/workspaces/${options.workspaceId}/schema`,
+    {
+      method: "PUT",
+      headers: {
+        Authorization: `Bearer ${options.hostToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    },
+  );
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`schema sync failed: ${res.status} ${text}`);
+  }
+}

package/src/validate.ts

@@ -0,0 +1,83 @@
+// packages/core/src/validate.ts
+import type { Frontmatter } from "./mdx";
+import { parseMdx } from "./mdx";
+import type { ModelSnapshot } from "./model";
+import { matchAnyModelPath } from "./path";
+import { expectedTypeFor, frontmatterZod, normalizeFrontmatter } from "./zod";
+
+export type ValidationResult =
+  | { ok: true }
+  | { ok: false; errors: string[] };
+
+/**
+ * Frontmatter must satisfy the model: required fields present and non-blank,
+ * every declared field of the right primitive type. Unknown keys are ignored.
+ */
+export function validateFrontmatter(
+  model: Pick<ModelSnapshot, "fields">,
+  frontmatter: Frontmatter,
+): ValidationResult {
+  const data = normalizeFrontmatter(frontmatter);
+  const result = frontmatterZod(model).safeParse(data);
+  if (result.success) return { ok: true };
+
+  const errors: string[] = [];
+  const seen = new Set<string>();
+  for (const issue of result.error.issues) {
+    const name = String(issue.path[0] ?? "");
+    const field = model.fields[name];
+    if (!field || seen.has(name)) continue;
+    seen.add(name);
+    const missing = data[name] === undefined;
+    if (issue.code === "too_small" || (issue.code === "invalid_type" && missing)) {
+      errors.push(`${name} is required`);
+    } else {
+      errors.push(`${name} must be a ${expectedTypeFor(field.kind)}`);
+    }
+  }
+  // Never fail open: if every issue was filtered above, still report invalid.
+  // Unreachable through the public API today (normalizeFrontmatter always yields
+  // a plain object and looseObject only raises issues on declared fields), so
+  // there is no test exercising this branch.
+  if (errors.length === 0) return { ok: false, errors: ["frontmatter is invalid"] };
+  return { ok: false, errors };
+}
+
+/**
+ * Parse a raw MDX string and validate its frontmatter. Never throws on
+ * malformed frontmatter (an unknown field kind in `model` still throws).
+ */
+export function validateMdxFile(
+  model: Pick<ModelSnapshot, "fields">,
+  raw: string,
+): ValidationResult {
+  let frontmatter: Frontmatter;
+  try {
+    frontmatter = parseMdx(raw).frontmatter;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "invalid";
+    return { ok: false, errors: [`frontmatter: ${msg}`] };
+  }
+  return validateFrontmatter(model, frontmatter);
+}
+
+export type ContentFileResult =
+  | { path: string; type: string; ok: true }
+  | { path: string; type: string; ok: false; errors: string[] }
+  | { path: string; type: null; ok: true; skipped: true };
+
+/** Validate many repo-relative files against a model set. Order is preserved. */
+export function validateContentTree(input: {
+  models: ModelSnapshot[];
+  files: Array<{ path: string; raw: string }>;
+}): ContentFileResult[] {
+  return input.files.map((file) => {
+    const hit = matchAnyModelPath(input.models, file.path);
+    if (!hit) return { path: file.path, type: null, ok: true, skipped: true };
+    const model = input.models.find((m) => m.type === hit.type);
+    if (!model) return { path: file.path, type: null, ok: true, skipped: true };
+    const result = validateMdxFile(model, file.raw);
+    if (result.ok) return { path: file.path, type: model.type, ok: true };
+    return { path: file.path, type: model.type, ok: false, errors: result.errors };
+  });
+}

package/src/zod.ts

@@ -0,0 +1,74 @@
+// packages/core/src/zod.ts
+import { z } from "zod";
+import type { FieldKind, FieldSnapshot } from "./fields";
+import type { Frontmatter } from "./mdx";
+import type { ModelSnapshot } from "./model";
+
+/** Primitive a field kind is stored as in frontmatter; used in error messages. */
+export function expectedTypeFor(kind: FieldKind): "string" | "number" | "boolean" {
+  switch (kind) {
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "text":
+    case "slug":
+    case "locale":
+    case "image":
+    case "relation":
+      return "string";
+    default: {
+      const _exhaustive: never = kind;
+      throw new Error(`unknown field kind: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+function fieldZod(field: FieldSnapshot): z.ZodType {
+  let base: z.ZodType;
+  switch (expectedTypeFor(field.kind)) {
+    case "number":
+      base = z.number();
+      break;
+    case "boolean":
+      base = z.boolean();
+      break;
+    default:
+      // Required strings must be non-blank; trim happens before min(1).
+      base = field.required ? z.string().trim().min(1) : z.string();
+  }
+  return field.required ? base : base.optional();
+}
+
+/**
+ * Zod object for a model's frontmatter.
+ * Loose: keys not in the model pass through untouched (drift is not an error).
+ */
+export function frontmatterZod(model: Pick<ModelSnapshot, "fields">) {
+  const shape: Record<string, z.ZodType> = {};
+  for (const [name, field] of Object.entries(model.fields)) {
+    shape[name] = fieldZod(field);
+  }
+  return z.looseObject(shape);
+}
+
+/** YAML `key:` with no value parses to null; treat null as "not set". */
+export function normalizeFrontmatter(frontmatter: Frontmatter): Frontmatter {
+  const out: Frontmatter = {};
+  for (const [key, value] of Object.entries(frontmatter)) {
+    if (value !== null) out[key] = value;
+  }
+  return out;
+}
+
+export type FrontmatterJsonSchema = z.core.JSONSchema.BaseSchema & {
+  title: string;
+};
+
+/** JSON Schema (draft 2020-12) for editor tooling. */
+export function frontmatterJsonSchema(model: ModelSnapshot): FrontmatterJsonSchema {
+  const schema = z.toJSONSchema(frontmatterZod(model), {
+    target: "draft-2020-12",
+  });
+  return { ...schema, title: model.type };
+}