@backmatter/core 0.0.6

package/src/index.ts

@@ -0,0 +1,132 @@
+// 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,
+  DEFAULT_PAGE_PATH,
+  serializeModel,
+  serializeSchema,
+  parseSchemaSnapshot,
+} from "./model";
+
+export type {
+  BlockInstance,
+  BlockDef,
+  BlockSnapshot,
+  InferBlockProps,
+} from "./block";
+export {
+  defineBlock,
+  serializeBlock,
+  parseBlockSnapshot,
+} from "./block";
+
+export type { DocFormat } from "./doc-format";
+export { modelFormat, parseDoc, serializeDoc } from "./doc-format";
+
+export type { BackmatterConfig, BackmatterDirs, 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,
+  contentExtFromPath,
+  contentExtForType,
+  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,
+  validateDocFile,
+  validateBlocks,
+  validateContentTree,
+} from "./validate";
+export { coerceFieldValue, coerceDocValues, imageUrlFromUnknown } from "./coerce";
+
+export type { FrontmatterJsonSchema } from "./zod";
+export {
+  expectedTypeFor,
+  exampleValueFor,
+  frontmatterJsonSchema,
+  frontmatterZod,
+  normalizeFrontmatter,
+} from "./zod";
+
+// Runtime-agnostic content access (no Node builtins). Filesystem loading,
+// createBackmatter and the CLI live in `@backmatter/core/node`.
+export type { BackmatterDoc, BackmatterDocSummary } from "./doc";
+export { createQuery } from "./query";
+export type { Query, ModelQuery, TypedDoc, Where, Include, DocLoader } from "./query";
+export type { PreviewCheckout, PreviewTicket } from "./preview-session";
+export {
+  PREVIEW_COOKIE,
+  PREVIEW_ENABLE_PATH,
+  PREVIEW_QUERY,
+  isSafeRedirectPath,
+  mintPreviewTicket,
+  previewMiddlewareDecision,
+  readPreviewCookie,
+  readPreviewTicket,
+  writePreviewCookie,
+  PREVIEW_TICKET_TTL_MS,
+  PREVIEW_COOKIE_TTL_MS,
+} from "./preview-session";
+export { signPayload, verifyPayload } from "./signed-token";
+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,
+  BACKMATTER_CACHE_TAG,
+  BACKMATTER_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}`;
+}

package/src/model.ts

@@ -0,0 +1,258 @@
+// packages/core/src/model.ts
+import {
+  type FieldDef,
+  type FieldKind,
+  type FieldSnapshot,
+  parseFieldSnapshot,
+  serializeField,
+} from "./fields";
+import { parseBlockSnapshot, serializeBlock, type BlockDef, type BlockSnapshot } from "./block";
+import type { BlockInstance } from "./block";
+import type { DocFormat } from "./doc-format";
+
+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;
+  /** File format. Default `"mdx"`. `"page"` stores JSON with a blocks array. */
+  format?: DocFormat;
+  /**
+   * Document slug served at `/` by the host catch-all. At most one model
+   * in a schema may set this.
+   */
+  indexSlug?: 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 const DEFAULT_PAGE_PATH = "content/{locale}/{type}/{slug}.json";
+
+export function defaultModelPath(type: string, format: DocFormat = "mdx"): string {
+  const template = format === "page" ? DEFAULT_PAGE_PATH : DEFAULT_MODEL_PATH;
+  return template.replaceAll("{type}", type);
+}
+
+export type ModelSnapshot = {
+  type: string;
+  path: string;
+  route?: string;
+  format?: DocFormat;
+  indexSlug?: string;
+  fields: Record<string, FieldSnapshot>;
+};
+
+export type SchemaSnapshot = {
+  version: number;
+  models: ModelSnapshot[];
+  blocks?: BlockSnapshot[];
+};
+
+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");
+  }
+  if (def.format !== undefined && def.format !== "mdx" && def.format !== "page") {
+    throw new Error('model.format must be "mdx" or "page"');
+  }
+  const path = def.path ?? defaultModelPath(def.type, def.format ?? "mdx");
+  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.indexSlug !== undefined) {
+    if (typeof def.indexSlug !== "string" || !def.indexSlug.trim()) {
+      throw new Error("model.indexSlug must be a non-empty string");
+    }
+  }
+  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
+    : K extends "blocks"
+      ? BlockInstance[]
+      : 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;
+  if (model.format === "page") snapshot.format = "page";
+  if (model.indexSlug !== undefined) snapshot.indexSlug = model.indexSlug.trim();
+  return snapshot;
+}
+
+export function serializeSchema(
+  models: ModelDef[],
+  blocks?: BlockDef[],
+): SchemaSnapshot {
+  const snapshot: SchemaSnapshot = {
+    version: 1,
+    models: models.map(serializeModel),
+  };
+  if (blocks && blocks.length > 0) {
+    snapshot.blocks = blocks.map(serializeBlock);
+  }
+  return snapshot;
+}
+
+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;
+    if (m.format === "page") snapshot.format = "page";
+    else if (m.format !== undefined && m.format !== "mdx") {
+      throw new Error(`schema.models[${i}].format must be "mdx" or "page"`);
+    }
+    if (m.indexSlug !== undefined) {
+      if (typeof m.indexSlug !== "string" || !m.indexSlug.trim()) {
+        throw new Error(`schema.models[${i}].indexSlug must be a non-empty string`);
+      }
+      snapshot.indexSlug = m.indexSlug.trim();
+    }
+    return snapshot;
+  });
+
+  const types = new Set<string>();
+  let indexOwner: string | undefined;
+  for (const m of models) {
+    if (types.has(m.type)) {
+      throw new Error(`duplicate model type: ${m.type}`);
+    }
+    types.add(m.type);
+    if (m.indexSlug) {
+      if (indexOwner) {
+        throw new Error(
+          `duplicate indexSlug: models "${indexOwner}" and "${m.type}" both claim /`,
+        );
+      }
+      indexOwner = m.type;
+    }
+  }
+
+  let blocks: BlockSnapshot[] = [];
+  const catalogRaw = value.blocks ?? value.pageblocks;
+  if (catalogRaw !== undefined) {
+    if (!Array.isArray(catalogRaw)) {
+      throw new Error("schema.blocks must be an array");
+    }
+    blocks = catalogRaw.map((raw, i) => {
+      try {
+        return parseBlockSnapshot(raw);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "invalid block";
+        throw new Error(`schema.blocks[${i}]: ${msg}`);
+      }
+    });
+    const names = new Set<string>();
+    for (const block of blocks) {
+      if (names.has(block.name)) {
+        throw new Error(`duplicate block name: ${block.name}`);
+      }
+      names.add(block.name);
+    }
+  }
+
+  return { version, models, blocks };
+}