@llm-cms/core 0.0.1

package/src/node/discover.ts

@@ -0,0 +1,116 @@
+// 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.
+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, also the 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]*$/;
+
+export function listBlockFiles(
+  root: string,
+  blocksDir = "blocks",
+): { blocks: BlockFile[]; skipped: string[] } {
+  const blocks: BlockFile[] = [];
+  const skipped: string[] = [];
+  for (const file of listSourceFiles(path.resolve(root, blocksDir))) {
+    const name = path.basename(file).replace(SOURCE_EXT, "");
+    if (JSX_TAG.test(name)) blocks.push({ file, name });
+    else skipped.push(path.relative(root, file));
+  }
+  return { blocks, skipped };
+}
+
+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 `@llm-cms/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;
+}

package/src/node/fs-loader.ts

@@ -0,0 +1,89 @@
+// packages/core/src/node/fs-loader.ts
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  matchAnyModelPath,
+  parseMdx,
+  repoPathFromModel,
+  type ModelSnapshot,
+} from "../index";
+import type { LlmcmsDoc, LlmcmsDocSummary } from "../doc";
+
+const SKIP_DIRS = new Set(["node_modules", ".next", ".git"]);
+
+export async function walkMdxFiles(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() && entry.name.endsWith(".mdx")) {
+        out.push(full);
+      }
+    }
+  }
+
+  await walk(rootDir);
+  return out.sort();
+}
+
+export async function listDocsFromFs(
+  siteRoot: string,
+  models: ModelSnapshot[],
+): Promise<LlmcmsDocSummary[]> {
+  const files = await walkMdxFiles(siteRoot);
+  const docs: LlmcmsDocSummary[] = [];
+  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<LlmcmsDoc | 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 = parseMdx(raw);
+  return {
+    locale,
+    type,
+    slug,
+    source: "head",
+    frontmatter: parsed.frontmatter,
+    body: parsed.body,
+    raw,
+  };
+}

package/src/node/generate.ts

@@ -0,0 +1,158 @@
+// packages/core/src/node/generate.ts
+// Writes the `.llmcms/` registry: a models barrel + typed `cms` client, and a
+// blocks barrel. Pure filesystem (no TS import) so it can run inside
+// next.config and on every file change in dev.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { DEFAULT_DIRS } from "../config";
+import { listBlockFiles, listModelFiles, type BlockFile, type ModelFile } from "./discover";
+
+// Re-exported so `@llm-cms/core/generate` is a self-sufficient, dependency-light
+// entry for bundler-side code (no zod / yaml pulled in).
+export { DEFAULT_DIRS };
+
+export const GENERATED_HEADER = "// Generated by llmcms — do not edit. Re-run `llmcms generate`.";
+export const DEFAULT_OUT_DIR = ".llmcms";
+export const CONFIG_FILES = ["llmcms.config.ts", "llmcms.config.mts", "llmcms.config.js", "llmcms.config.mjs"];
+
+export type GenerateOptions = {
+  /** Customer repo root. */
+  root: string;
+  /** Where to write. Default: ".llmcms". */
+  outDir?: string;
+  modelsDir?: string;
+  blocksDir?: string;
+  /** Module that exports `createLlmcms`. Auto-detected from package.json when omitted. */
+  sdk?: string;
+  /** Write to disk. Default: true. `false` only renders (used by the bundler loader). */
+  write?: boolean;
+};
+
+export type GeneratedFile = {
+  /** Absolute path. */
+  file: string;
+  /** Root-relative path with `/` separators. */
+  rel: string;
+  content: string;
+  /** True when the on-disk content differed (or the file was missing). */
+  changed: boolean;
+};
+
+export type GenerateResult = {
+  /** Every registry file, rendered. */
+  outputs: GeneratedFile[];
+  /** Root-relative paths of all registry files. */
+  files: string[];
+  /** Root-relative paths whose content differed from disk. */
+  changed: string[];
+  models: ModelFile[];
+  blocks: BlockFile[];
+  skippedBlocks: string[];
+  /** Absolute path of `llmcms.config.*` when present. */
+  configFile: string | null;
+};
+
+function importSpecifier(fromDir: string, file: string): string {
+  const rel = path.relative(fromDir, file).split(path.sep).join("/").replace(/\.(ts|tsx|mts|js|jsx|mjs)$/, "");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+export function findConfigFile(root: string): string | null {
+  for (const name of CONFIG_FILES) {
+    const full = path.join(root, name);
+    if (existsSync(full)) return full;
+  }
+  return null;
+}
+
+/** `@llm-cms/next` when the host depends on it, otherwise `@llm-cms/core/node`. */
+export function detectSdk(root: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf-8")) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps["@llm-cms/next"]) return "@llm-cms/next";
+  } catch {
+    // no package.json → core
+  }
+  return "@llm-cms/core/node";
+}
+
+export function renderModelsBarrel(input: {
+  outDir: string;
+  models: ModelFile[];
+  configFile: string | null;
+  sdk: string;
+}): string {
+  const lines = [GENERATED_HEADER, `import { createLlmcms } from "${input.sdk}";`];
+  if (input.configFile) {
+    lines.push(`import config from "${importSpecifier(input.outDir, input.configFile)}";`);
+  } else {
+    lines.push("const config = {};");
+  }
+  for (const m of input.models) {
+    lines.push(`import ${m.importName} from "${importSpecifier(input.outDir, m.file)}";`);
+  }
+  lines.push("");
+  lines.push(`export const models = [${input.models.map((m) => m.importName).join(", ")}] as const;`);
+  lines.push("export type Models = typeof models;");
+  lines.push("");
+  lines.push("/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */");
+  lines.push("export const cms = createLlmcms({ ...config, models });");
+  return `${lines.join("\n")}\n`;
+}
+
+export function renderBlocksBarrel(input: { outDir: string; blocks: BlockFile[] }): string {
+  const lines = [GENERATED_HEADER];
+  for (const b of input.blocks) {
+    lines.push(`import ${b.name} from "${importSpecifier(input.outDir, b.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** MDX component map: <Hero /> in content resolves to blocks/Hero.tsx. */");
+  const names = input.blocks.map((b) => b.name).join(", ");
+  lines.push(`export const blocks = ${names ? `{ ${names} }` : "{}"};`);
+  return `${lines.join("\n")}\n`;
+}
+
+function differsOnDisk(file: string, content: string): boolean {
+  return !existsSync(file) || readFileSync(file, "utf-8") !== content;
+}
+
+/** Registry file names inside the out dir. */
+export const REGISTRY_FILES = ["index.ts", "blocks.ts"] as const;
+
+export function generate(options: GenerateOptions): GenerateResult {
+  const root = path.resolve(options.root);
+  const outDir = path.resolve(root, options.outDir ?? DEFAULT_OUT_DIR);
+  const models = listModelFiles(root, options.modelsDir ?? DEFAULT_DIRS.models);
+  const { blocks, skipped } = listBlockFiles(root, options.blocksDir ?? DEFAULT_DIRS.blocks);
+  const sdk = options.sdk ?? detectSdk(root);
+  const configFile = findConfigFile(root);
+  const write = options.write ?? true;
+
+  const rendered: Record<(typeof REGISTRY_FILES)[number], string> = {
+    "index.ts": renderModelsBarrel({ outDir, models, configFile, sdk }),
+    "blocks.ts": renderBlocksBarrel({ outDir, blocks }),
+  };
+  const outputs: GeneratedFile[] = REGISTRY_FILES.map((name) => {
+    const file = path.join(outDir, name);
+    const content = rendered[name];
+    const changed = differsOnDisk(file, content);
+    if (changed && write) {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, content);
+    }
+    return { file, rel: path.relative(root, file).split(path.sep).join("/"), content, changed };
+  });
+  return {
+    outputs,
+    files: outputs.map((o) => o.rel),
+    changed: outputs.filter((o) => o.changed).map((o) => o.rel),
+    models,
+    blocks,
+    skippedBlocks: skipped,
+    configFile,
+  };
+}

package/src/node/index.ts

@@ -0,0 +1,36 @@
+// packages/core/src/node/index.ts
+// Node/Bun-only entry: filesystem loaders, createLlmcms, folder discovery,
+// codegen and the CLI helpers. Browser code must import `@llm-cms/core` or
+// `@llm-cms/core/preview` instead.
+export { createLlmcms } from "./create-llmcms";
+export type { CreateLlmcmsOptions, LlmcmsClient } from "./create-llmcms";
+export { getDocFromFs, listDocsFromFs, walkMdxFiles } from "./fs-loader";
+export {
+  discoverModels,
+  listBlockFiles,
+  listModelFiles,
+  toIdentifier,
+} from "./discover";
+export type { BlockFile, ModelFile } from "./discover";
+export {
+  detectSdk,
+  findConfigFile,
+  generate,
+  renderBlocksBarrel,
+  renderModelsBarrel,
+  DEFAULT_OUT_DIR,
+  REGISTRY_FILES,
+} from "./generate";
+export type { GenerateOptions, GenerateResult, GeneratedFile } from "./generate";
+export {
+  contentRoots,
+  formatResults,
+  loadConfig,
+  loadModels,
+  parseArgs,
+  runGenerate,
+  runInit,
+  runSchema,
+  runValidate,
+} from "./cli";
+export type { CliArgs } from "./cli";

package/src/path.ts

@@ -0,0 +1,179 @@
+// packages/core/src/path.ts
+import type { ModelSnapshot } from "./model";
+
+export type PathMatch = {
+  locale: string;
+  slug: string;
+  type: string;
+};
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Compile a model path template into a regex with named locale/slug captures. */
+export function compilePathPattern(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);
+  }
+  pattern += "$";
+  return new RegExp(pattern);
+}
+
+export function matchModelPath(
+  model: Pick<ModelSnapshot, "type" | "path">,
+  repoPath: string,
+): PathMatch | null {
+  const normalized = repoPath.replace(/^\/+/, "");
+  const re = compilePathPattern(model.path);
+  const m = re.exec(normalized);
+  if (!m?.groups?.locale || !m.groups.slug) return null;
+  // Strip trailing .mdx from slug if the template baked the extension into the capture.
+  let slug = m.groups.slug;
+  if (model.path.endsWith(".mdx") && slug.endsWith(".mdx")) {
+    slug = slug.slice(0, -".mdx".length);
+  }
+  if (!slug) return null;
+  return { locale: m.groups.locale, slug, type: model.type };
+}
+
+export function matchAnyModelPath(
+  models: Array<Pick<ModelSnapshot, "type" | "path">>,
+  repoPath: string,
+): PathMatch | null {
+  for (const model of models) {
+    const hit = matchModelPath(model, repoPath);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+export function repoPathFromModel(
+  model: Pick<ModelSnapshot, "path">,
+  locale: string,
+  slug: string,
+): string {
+  return model.path
+    .replaceAll("{locale}", locale)
+    .replaceAll("{slug}", slug);
+}
+
+// ---------------------------------------------------------------------------
+// S3 layout (git working tree model)
+//
+//   workspaces/{ws}/branches/{branch}/head/{locale}/{type}/{slug}.mdx
+//     mirror of the git branch HEAD — what the public site reads
+//   workspaces/{ws}/branches/{branch}/trees/{userId}/{locale}/{type}/{slug}.mdx
+//     one user's uncommitted file on that branch
+//   workspaces/{ws}/branches/{branch}/meta/shas/{locale}/{type}/{slug}.json
+//     HEAD blob sha per file (conflict base)
+// ---------------------------------------------------------------------------
+
+/** Where a doc's bytes came from: the branch HEAD mirror or the caller's working tree. */
+export type ContentSource = "head" | "tree";
+
+export function encodeGitBranch(branch: string): string {
+  return encodeURIComponent(branch);
+}
+
+export function decodeGitBranch(encoded: string): string {
+  return decodeURIComponent(encoded);
+}
+
+function branchRoot(workspaceId: string, branch: string): string {
+  return `workspaces/${workspaceId}/branches/${encodeGitBranch(branch)}`;
+}
+
+export function s3HeadPrefix(workspaceId: string, branch: string): string {
+  return `${branchRoot(workspaceId, branch)}/head/`;
+}
+
+export function s3TreePrefix(
+  workspaceId: string,
+  branch: string,
+  userId: string,
+): string {
+  return `${branchRoot(workspaceId, branch)}/trees/${encodeURIComponent(userId)}/`;
+}
+
+export function s3HeadKey(
+  workspaceId: string,
+  branch: string,
+  locale: string,
+  type: string,
+  slug: string,
+): string {
+  return `${s3HeadPrefix(workspaceId, branch)}${locale}/${type}/${slug}.mdx`;
+}
+
+export function s3TreeKey(
+  workspaceId: string,
+  branch: string,
+  userId: string,
+  locale: string,
+  type: string,
+  slug: string,
+): string {
+  return `${s3TreePrefix(workspaceId, branch, userId)}${locale}/${type}/${slug}.mdx`;
+}
+
+/** HEAD blob sha for conflict checks. */
+export function s3ShaMetaKey(
+  workspaceId: string,
+  branch: string,
+  locale: string,
+  type: string,
+  slug: string,
+): string {
+  return `${branchRoot(workspaceId, branch)}/meta/shas/${locale}/${type}/${slug}.json`;
+}
+
+export type ParsedContentKey = {
+  branch: string;
+  source: ContentSource;
+  /** Owner of the working tree; null for head keys. */
+  userId: string | null;
+  locale: string;
+  type: string;
+  slug: string;
+};
+
+/** Parse a head/ or trees/{userId}/ key into identity parts. */
+export function parseS3ContentKey(
+  workspaceId: string,
+  key: string,
+): ParsedContentKey | null {
+  const prefix = `workspaces/${workspaceId}/branches/`;
+  if (!key.startsWith(prefix)) return null;
+  const rest = key.slice(prefix.length);
+
+  const head = /^([^/]+)\/head\/([^/]+)\/([^/]+)\/(.+)\.mdx$/.exec(rest);
+  if (head) {
+    return {
+      branch: decodeGitBranch(head[1]!),
+      source: "head",
+      userId: null,
+      locale: head[2]!,
+      type: head[3]!,
+      slug: head[4]!,
+    };
+  }
+
+  const tree =
+    /^([^/]+)\/trees\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)\.mdx$/.exec(rest);
+  if (tree) {
+    return {
+      branch: decodeGitBranch(tree[1]!),
+      source: "tree",
+      userId: decodeURIComponent(tree[2]!),
+      locale: tree[3]!,
+      type: tree[4]!,
+      slug: tree[5]!,
+    };
+  }
+  return null;
+}

package/src/preview-hotkeys.ts

@@ -0,0 +1,71 @@
+// packages/core/src/preview-hotkeys.ts
+export const PREVIEW_HOTKEY_TYPE = "llmcms:hotkey";
+
+export type PreviewHotkeyMessage = {
+  type: typeof PREVIEW_HOTKEY_TYPE;
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+};
+
+export type KeyboardHotkeyLike = {
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+};
+
+const FORWARDED = new Set(["s", "k"]);
+
+export function previewHotkeyFromKeyboardEvent(
+  event: KeyboardHotkeyLike,
+): PreviewHotkeyMessage | null {
+  const key = event.key.length === 1 ? event.key.toLowerCase() : event.key;
+  if (!(event.metaKey || event.ctrlKey)) return null;
+  if (!FORWARDED.has(key)) return null;
+  return {
+    type: PREVIEW_HOTKEY_TYPE,
+    key,
+    metaKey: event.metaKey,
+    ctrlKey: event.ctrlKey,
+    shiftKey: event.shiftKey,
+    altKey: event.altKey,
+  };
+}
+
+export function parsePreviewHotkey(data: unknown): PreviewHotkeyMessage | null {
+  if (!data || typeof data !== "object") return null;
+  const record = data as Record<string, unknown>;
+  if (record.type !== PREVIEW_HOTKEY_TYPE) return null;
+  if (typeof record.key !== "string") return null;
+  return {
+    type: PREVIEW_HOTKEY_TYPE,
+    key: record.key,
+    metaKey: Boolean(record.metaKey),
+    ctrlKey: Boolean(record.ctrlKey),
+    shiftKey: Boolean(record.shiftKey),
+    altKey: Boolean(record.altKey),
+  };
+}
+
+/** Forward cmd/ctrl+s and cmd/ctrl+k to the parent CMS when this page is iframed. */
+export function installPreviewHotkeys(): () => void {
+  function onKey(event: KeyboardEvent) {
+    if (window.parent === window) return;
+    const message = previewHotkeyFromKeyboardEvent(event);
+    if (!message) return;
+    event.preventDefault();
+    let target = "*";
+    try {
+      if (document.referrer) target = new URL(document.referrer).origin;
+    } catch {
+      target = "*";
+    }
+    window.parent.postMessage(message, target);
+  }
+  window.addEventListener("keydown", onKey);
+  return () => window.removeEventListener("keydown", onKey);
+}