@llm-cms/core 0.0.1

package/bin/llmcms.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/node/cli.ts";

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@llm-cms/core",
+  "version": "0.0.1",
+  "description": "Experimental LLMCMS SDK. APIs will break. Not ready for production.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./node": "./src/node/index.ts",
+    "./preview": "./src/preview.ts",
+    "./generate": "./src/node/generate.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!**/test-fixtures"
+  ],
+  "bin": {
+    "llmcms": "./bin/llmcms.js"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "zod": "^4.6.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  }
+}

package/src/api-loader.ts

@@ -0,0 +1,72 @@
+// packages/core/src/api-loader.ts
+import type { LlmcmsDoc, LlmcmsDocSummary } from "./doc";
+
+export type PublicDocsQuery = {
+  branch?: string;
+  type?: string;
+  locale?: string;
+  /** When set, Next Data Cache uses these tags instead of `cache: "no-store"`. */
+  tags?: string[];
+};
+
+function fetchInit(
+  contentToken: string | undefined,
+  tags?: string[],
+): RequestInit & { next?: { tags: string[] } } {
+  const headers: Record<string, string> = {};
+  if (contentToken) headers.Authorization = `Bearer ${contentToken}`;
+  if (tags?.length) return { headers, next: { tags } };
+  return { headers, cache: "no-store" };
+}
+
+function publicDocsUrl(
+  apiUrl: string,
+  workspaceId: string,
+  path: string,
+  query: PublicDocsQuery = {},
+): string {
+  const url = new URL(
+    `${apiUrl.replace(/\/$/, "")}/public/workspaces/${workspaceId}/docs${path}`,
+  );
+  if (query.branch) url.searchParams.set("branch", query.branch);
+  if (query.type) url.searchParams.set("type", query.type);
+  if (query.locale) url.searchParams.set("locale", query.locale);
+  return url.toString();
+}
+
+export async function listDocsFromApi(
+  apiUrl: string,
+  workspaceId: string,
+  contentToken: string | undefined,
+  query: PublicDocsQuery = {},
+): Promise<LlmcmsDocSummary[]> {
+  const res = await fetch(publicDocsUrl(apiUrl, workspaceId, "", query), {
+    ...fetchInit(contentToken, query.tags),
+  });
+  if (!res.ok) {
+    throw new Error(`llmcms listDocs failed: ${res.status}`);
+  }
+  const data = (await res.json()) as { docs: LlmcmsDocSummary[] };
+  return data.docs;
+}
+
+export async function getDocFromApi(
+  apiUrl: string,
+  workspaceId: string,
+  contentToken: string | undefined,
+  locale: string,
+  type: string,
+  slug: string,
+  query: Pick<PublicDocsQuery, "branch" | "tags"> = {},
+): Promise<LlmcmsDoc | null> {
+  const res = await fetch(
+    publicDocsUrl(apiUrl, workspaceId, `/${locale}/${type}/${slug}`, query),
+    fetchInit(contentToken, query.tags),
+  );
+  if (res.status === 404) return null;
+  if (!res.ok) {
+    throw new Error(`llmcms getDoc failed: ${res.status}`);
+  }
+  const data = (await res.json()) as { doc: LlmcmsDoc };
+  return data.doc;
+}

package/src/config.ts

@@ -0,0 +1,111 @@
+// packages/core/src/config.ts
+// General host configuration (`llmcms.config.ts`). Models are never listed
+// here; they are discovered from the `models/` folder.
+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". */
+  blocks?: string;
+};
+
+export type LlmcmsConfig = {
+  /** Required only when talking to the LLMCMS API. Env: LLMCMS_WORKSPACE_ID. */
+  workspaceId?: string;
+  /** Env: LLMCMS_API_URL. When set with workspaceId, published docs load from the API. */
+  apiUrl?: string;
+  /** Env: LLMCMS_CONTENT_TOKEN. Required only to read non-default branches. */
+  contentToken?: string;
+  /** Env: LLMCMS_HOST_TOKEN. When set with apiUrl, the schema snapshot syncs on boot. */
+  hostToken?: string;
+  /** Git branch for the schema sync. Env: LLMCMS_GIT_BRANCH / VERCEL_GIT_COMMIT_REF. */
+  branch?: string;
+  /**
+   * Public origin of this host (no trailing slash). Used to register the
+   * revalidate webhook. Env: LLMCMS_SITE_URL / VERCEL_* .
+   */
+  siteUrl?: string;
+  /** Site root for filesystem mode. Default: process.cwd(). */
+  siteRoot?: string;
+  /** Locales the catch-all route accepts in `{locale}`. Unset → any segment. */
+  locales?: readonly string[];
+  /** Locale used by routes without a `{locale}` placeholder. Default: "en". */
+  defaultLocale?: string;
+  dirs?: LlmcmsDirs;
+};
+
+export type ResolvedConfig = Omit<LlmcmsConfig, "dirs" | "defaultLocale"> & {
+  defaultLocale: string;
+  dirs: Required<LlmcmsDirs>;
+};
+
+export const DEFAULT_DIRS: Required<LlmcmsDirs> = { models: "models", blocks: "blocks" };
+export const DEFAULT_LOCALE = "en";
+
+function withHttps(url: string): string {
+  if (url.startsWith("http://") || url.startsWith("https://")) return url;
+  return `https://${url}`;
+}
+
+function stripTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+/** Public origin of the host that should receive `content.committed`. */
+export function detectSiteUrl(
+  config: { siteUrl?: string } = {},
+  env: Record<string, string | undefined> = {},
+): string | undefined {
+  const explicit = config.siteUrl?.trim() || env.LLMCMS_SITE_URL?.trim();
+  if (explicit) return stripTrailingSlash(withHttps(explicit));
+  const production = env.VERCEL_PROJECT_PRODUCTION_URL?.trim();
+  if (env.VERCEL_ENV === "production" && production) {
+    return stripTrailingSlash(withHttps(production));
+  }
+  const vercel = env.VERCEL_URL?.trim();
+  if (vercel) return stripTrailingSlash(withHttps(vercel));
+  return undefined;
+}
+
+/** Identity helper that gives `llmcms.config.ts` a typed default export. */
+export function defineConfig(config: LlmcmsConfig): LlmcmsConfig {
+  if (config.defaultLocale !== undefined && !config.defaultLocale) {
+    throw new Error("config.defaultLocale must be a non-empty string");
+  }
+  if (config.locales && config.defaultLocale && !config.locales.includes(config.defaultLocale)) {
+    throw new Error(`config.defaultLocale "${config.defaultLocale}" is not in config.locales`);
+  }
+  return config;
+}
+
+function envOf(): Record<string, string | undefined> {
+  return typeof process === "undefined" ? {} : process.env;
+}
+
+/** Explicit config wins; env vars fill the gaps; folder defaults last. */
+export function resolveConfig(
+  config: LlmcmsConfig = {},
+  env: Record<string, string | undefined> = envOf(),
+): ResolvedConfig {
+  const pick = (value: string | undefined, key: string) => {
+    if (value !== undefined) return value;
+    const fromEnv = env[key]?.trim();
+    return fromEnv ? fromEnv : undefined;
+  };
+  return {
+    workspaceId: pick(config.workspaceId, "LLMCMS_WORKSPACE_ID"),
+    apiUrl: pick(config.apiUrl, "LLMCMS_API_URL"),
+    contentToken: pick(config.contentToken, "LLMCMS_CONTENT_TOKEN"),
+    hostToken: pick(config.hostToken, "LLMCMS_HOST_TOKEN"),
+    branch: config.branch?.trim() || detectGitBranch(env) || undefined,
+    siteUrl: detectSiteUrl(config, env),
+    siteRoot: config.siteRoot,
+    locales: config.locales,
+    defaultLocale: config.defaultLocale ?? DEFAULT_LOCALE,
+    dirs: {
+      models: config.dirs?.models ?? DEFAULT_DIRS.models,
+      blocks: config.dirs?.blocks ?? DEFAULT_DIRS.blocks,
+    },
+  };
+}

package/src/content-committed.ts

@@ -0,0 +1,57 @@
+// packages/core/src/content-committed.ts
+// Wire format for "HEAD changed on this branch" — the host revalidate route
+// and the central server share this. No GitHub, no Next imports.
+import { routeFor, type RouteModel } from "./routes";
+
+export const CONTENT_COMMITTED_EVENT = "content.committed" as const;
+
+export const LLMCMS_REVALIDATE_PATH = "/api/llmcms/revalidate";
+
+export const LLMCMS_CACHE_TAG = "llmcms";
+
+export type ContentCommittedDoc = {
+  locale: string;
+  type: string;
+  slug: string;
+};
+
+export type ContentCommittedEvent = {
+  event: typeof CONTENT_COMMITTED_EVENT;
+  workspaceId: string;
+  branch: string;
+  headSha: string | null;
+  docs: ContentCommittedDoc[];
+  /** True when the whole branch mirror was rebuilt (force push / truncated). */
+  full?: boolean;
+};
+
+export function revalidateUrl(siteUrl: string): string {
+  return `${siteUrl.replace(/\/$/, "")}${LLMCMS_REVALIDATE_PATH}`;
+}
+
+export function contentCacheTags(locale: string, type: string, slug: string): string[] {
+  return [LLMCMS_CACHE_TAG, `llmcms:${type}`, `llmcms:${locale}:${type}:${slug}`];
+}
+
+export function listCacheTags(type?: string): string[] {
+  return type ? [LLMCMS_CACHE_TAG, `llmcms:${type}`] : [LLMCMS_CACHE_TAG];
+}
+
+/** Site paths the host should `revalidatePath` for these docs. */
+export function pathsForCommittedDocs(
+  models: readonly RouteModel[],
+  docs: readonly ContentCommittedDoc[],
+): string[] {
+  const byType = new Map(models.map((m) => [m.type, m]));
+  const paths: string[] = [];
+  const seen = new Set<string>();
+  for (const doc of docs) {
+    const model = byType.get(doc.type);
+    if (!model) continue;
+    const path = routeFor(model, doc.locale, doc.slug);
+    if (seen.has(path)) continue;
+    seen.add(path);
+    paths.push(path);
+  }
+  return paths;
+}

package/src/doc-ref.ts

@@ -0,0 +1,29 @@
+export type DocRef = {
+  workspaceId: string;
+  locale: string;
+  type: string;
+  slug: string;
+};
+
+export function parseDocRef(input: unknown): DocRef {
+  if (!input || typeof input !== "object") {
+    throw new Error("docRef must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  for (const key of ["workspaceId", "locale", "type", "slug"] as const) {
+    if (typeof value[key] !== "string" || value[key].length === 0) {
+      throw new Error(`docRef.${key} is required`);
+    }
+  }
+  return {
+    workspaceId: value.workspaceId as string,
+    locale: value.locale as string,
+    type: value.type as string,
+    slug: value.slug as string,
+  };
+}
+
+/** Relative content path (no workspace prefix) used under head/ and trees/{userId}/. */
+export function docRefPath(ref: DocRef): string {
+  return `${ref.locale}/${ref.type}/${ref.slug}`;
+}

package/src/doc.ts

@@ -0,0 +1,18 @@
+// packages/core/src/doc.ts
+
+export type LlmcmsDocSummary = {
+  locale: string;
+  type: string;
+  slug: string;
+};
+
+export type LlmcmsDoc = {
+  locale: string;
+  type: string;
+  slug: string;
+  /** `head` = committed on the branch; `tree` = the caller's uncommitted working copy. */
+  source: "head" | "tree";
+  frontmatter: Record<string, unknown>;
+  body: string;
+  raw: string;
+};

package/src/fields.ts

@@ -0,0 +1,89 @@
+// packages/core/src/fields.ts
+
+export type FieldKind =
+  | "text"
+  | "slug"
+  | "locale"
+  | "image"
+  | "relation"
+  | "number"
+  | "boolean";
+
+/**
+ * Field definition. Generic parameters only exist for type inference
+ * (`InferFrontmatter`); the runtime object is `{ kind, required?, relationTo? }`.
+ */
+export type FieldDef<
+  K extends FieldKind = FieldKind,
+  R extends boolean = boolean,
+  To extends string = string,
+> = {
+  kind: K;
+  required?: R;
+  /** For relation fields: target model type. */
+  relationTo?: To;
+};
+
+export type FieldSnapshot = {
+  kind: FieldKind;
+  required?: boolean;
+  relationTo?: string;
+};
+
+type Opts<R extends boolean> = { required?: R };
+
+function base<K extends FieldKind, R extends boolean, To extends string>(
+  kind: K,
+  opts?: { required?: R; relationTo?: To },
+): FieldDef<K, R, To> {
+  return {
+    kind,
+    ...(opts?.required ? { required: opts.required } : {}),
+    ...(opts?.relationTo ? { relationTo: opts.relationTo } : {}),
+  } as FieldDef<K, R, To>;
+}
+
+export const field = {
+  text: <const R extends boolean = false>(opts?: Opts<R>) => base("text", opts),
+  slug: <const R extends boolean = false>(opts?: Opts<R>) => base("slug", opts),
+  locale: <const R extends boolean = false>(opts?: Opts<R>) => base("locale", opts),
+  image: <const R extends boolean = false>(opts?: Opts<R>) => base("image", opts),
+  number: <const R extends boolean = false>(opts?: Opts<R>) => base("number", opts),
+  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 }),
+};
+
+export function serializeField(def: FieldDef): FieldSnapshot {
+  return {
+    kind: def.kind,
+    ...(def.required ? { required: true } : {}),
+    ...(def.relationTo ? { relationTo: def.relationTo } : {}),
+  };
+}
+
+export function parseFieldSnapshot(input: unknown): FieldSnapshot {
+  if (!input || typeof input !== "object") {
+    throw new Error("field must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  const kind = value.kind;
+  const allowed: FieldKind[] = [
+    "text",
+    "slug",
+    "locale",
+    "image",
+    "relation",
+    "number",
+    "boolean",
+  ];
+  if (typeof kind !== "string" || !allowed.includes(kind as FieldKind)) {
+    throw new Error(`invalid field.kind: ${String(kind)}`);
+  }
+  const snap: FieldSnapshot = { kind: kind as FieldKind };
+  if (value.required === true) snap.required = true;
+  if (typeof value.relationTo === "string" && value.relationTo.length > 0) {
+    snap.relationTo = value.relationTo;
+  }
+  return snap;
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+// packages/core/src/index.ts
+export type { DocRef } from "./doc-ref";
+export { parseDocRef, docRefPath } from "./doc-ref";
+
+export type {
+  FieldDef,
+  FieldKind,
+  FieldSnapshot,
+} from "./fields";
+export { field, serializeField, parseFieldSnapshot } from "./fields";
+
+export type {
+  ModelDef,
+  ModelInput,
+  ModelSnapshot,
+  SchemaSnapshot,
+  InferFrontmatter,
+} from "./model";
+export {
+  defineModel,
+  defaultModelPath,
+  DEFAULT_MODEL_PATH,
+  serializeModel,
+  serializeSchema,
+  parseSchemaSnapshot,
+} from "./model";
+
+export type { LlmcmsConfig, LlmcmsDirs, ResolvedConfig } from "./config";
+export { defineConfig, resolveConfig, detectSiteUrl, DEFAULT_DIRS, DEFAULT_LOCALE } from "./config";
+
+export type { RouteMatch, RouteModel, MatchRouteOptions } from "./routes";
+export {
+  DEFAULT_ROUTE,
+  compileRoutePattern,
+  matchRoute,
+  normalizePathname,
+  routeFor,
+  routeSegments,
+  routeTemplate,
+  sortByRouteSpecificity,
+} from "./routes";
+
+export type { PathMatch, ContentSource, ParsedContentKey } from "./path";
+export {
+  compilePathPattern,
+  matchModelPath,
+  matchAnyModelPath,
+  repoPathFromModel,
+  encodeGitBranch,
+  decodeGitBranch,
+  s3HeadKey,
+  s3TreeKey,
+  s3HeadPrefix,
+  s3TreePrefix,
+  s3ShaMetaKey,
+  parseS3ContentKey,
+} from "./path";
+
+export type { Frontmatter, ParsedMdx } from "./mdx";
+export { parseMdx, serializeMdx } from "./mdx";
+
+export type { ValidationResult, ContentFileResult } from "./validate";
+export {
+  validateFrontmatter,
+  validateMdxFile,
+  validateContentTree,
+} from "./validate";
+
+export type { FrontmatterJsonSchema } from "./zod";
+export {
+  expectedTypeFor,
+  frontmatterJsonSchema,
+  frontmatterZod,
+  normalizeFrontmatter,
+} from "./zod";
+
+// Runtime-agnostic content access (no Node builtins). Filesystem loading,
+// createLlmcms and the CLI live in `@llm-cms/core/node`.
+export type { LlmcmsDoc, LlmcmsDocSummary } from "./doc";
+export { createQuery } from "./query";
+export type { Query, ModelQuery, TypedDoc, Where, Include, DocLoader } from "./query";
+export { getDocFromApi, listDocsFromApi } from "./api-loader";
+export type { PublicDocsQuery } from "./api-loader";
+export { syncSchema, detectGitBranch } from "./sync-schema";
+export type { SyncSchemaOptions } from "./sync-schema";
+export type { ContentCommittedDoc, ContentCommittedEvent } from "./content-committed";
+export {
+  CONTENT_COMMITTED_EVENT,
+  LLMCMS_CACHE_TAG,
+  LLMCMS_REVALIDATE_PATH,
+  contentCacheTags,
+  listCacheTags,
+  pathsForCommittedDocs,
+  revalidateUrl,
+} from "./content-committed";

package/src/mdx.ts

@@ -0,0 +1,44 @@
+// packages/core/src/mdx.ts
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+export type Frontmatter = Record<string, unknown>;
+
+export type ParsedMdx = {
+  frontmatter: Frontmatter;
+  body: string;
+};
+
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+export function parseMdx(raw: string): ParsedMdx {
+  const match = FM_RE.exec(raw);
+  if (!match) {
+    return { frontmatter: {}, body: raw };
+  }
+  const yamlText = match[1] ?? "";
+  const body = match[2] ?? "";
+  let frontmatter: Frontmatter = {};
+  if (yamlText.trim()) {
+    const parsed = parseYaml(yamlText);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      frontmatter = parsed as Frontmatter;
+    } else {
+      throw new Error("frontmatter must be a YAML mapping");
+    }
+  }
+  return { frontmatter, body };
+}
+
+export function serializeMdx(frontmatter: Frontmatter, body: string): string {
+  const keys = Object.keys(frontmatter);
+  if (keys.length === 0) {
+    return body.startsWith("---") ? `\n${body}` : body;
+  }
+  const yaml = stringifyYaml(frontmatter, {
+    lineWidth: 0,
+    defaultStringType: "PLAIN",
+    defaultKeyType: "PLAIN",
+  }).trimEnd();
+  const normalizedBody = body.replace(/^\r?\n/, "");
+  return `---\n${yaml}\n---\n${normalizedBody}`;
+}