@backmatter/core 0.0.6

package/bin/backmatter.js

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@backmatter/core",
+  "version": "0.0.6",
+  "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./node": "./src/node/index.ts",
+    "./node/create-backmatter": "./src/node/create-backmatter.ts",
+    "./preview": "./src/preview.ts",
+    "./generate": "./src/node/generate.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!**/test-fixtures"
+  ],
+  "bin": {
+    "backmatter": "./bin/backmatter.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 { BackmatterDoc, BackmatterDocSummary } 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<BackmatterDocSummary[]> {
+  const res = await fetch(publicDocsUrl(apiUrl, workspaceId, "", query), {
+    ...fetchInit(contentToken, query.tags),
+  });
+  if (!res.ok) {
+    throw new Error(`backmatter listDocs failed: ${res.status}`);
+  }
+  const data = (await res.json()) as { docs: BackmatterDocSummary[] };
+  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<BackmatterDoc | 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(`backmatter getDoc failed: ${res.status}`);
+  }
+  const data = (await res.json()) as { doc: BackmatterDoc };
+  return data.doc;
+}

package/src/block.ts

@@ -0,0 +1,103 @@
+// packages/core/src/block.ts
+import {
+  type FieldDef,
+  type FieldKind,
+  type FieldSnapshot,
+  parseFieldSnapshot,
+  serializeField,
+} from "./fields";
+
+export type BlockInstance = {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+};
+
+export type BlockDef<C = unknown> = {
+  name: string;
+  fields: Record<string, FieldDef>;
+  component: C;
+};
+
+export type BlockSnapshot = {
+  name: string;
+  fields: Record<string, FieldSnapshot>;
+};
+
+const PASCAL = /^[A-Z][A-Za-z0-9]*$/;
+
+export function defineBlock<const D extends BlockDef>(def: D): D {
+  if (!def.name || typeof def.name !== "string") {
+    throw new Error("block.name is required");
+  }
+  if (!PASCAL.test(def.name)) {
+    throw new Error('block.name must be PascalCase (e.g. "Hero")');
+  }
+  if (!def.fields || typeof def.fields !== "object") {
+    throw new Error("block.fields is required");
+  }
+  if (def.component === undefined) {
+    throw new Error("block.component is required");
+  }
+  return def;
+}
+
+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 block's props, derived from `field.*` calls. */
+export type InferBlockProps<Fields extends Record<string, FieldDef>> = Simplify<
+  {
+    [N in keyof Fields as IsRequired<Fields[N]> extends true ? N : never]: ScalarOf<
+      Fields[N]["kind"]
+    >;
+  } & {
+    [N in keyof Fields as IsRequired<Fields[N]> extends true ? never : N]?: ScalarOf<
+      Fields[N]["kind"]
+    >;
+  }
+>;
+
+export function serializeBlock(block: BlockDef): BlockSnapshot {
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, def] of Object.entries(block.fields)) {
+    fields[name] = serializeField(def);
+  }
+  return { name: block.name, fields };
+}
+
+export function parseBlockSnapshot(input: unknown): BlockSnapshot {
+  if (!input || typeof input !== "object") {
+    throw new Error("block must be an object");
+  }
+  const value = input as Record<string, unknown>;
+  if (typeof value.name !== "string" || !value.name) {
+    throw new Error("block.name is required");
+  }
+  if (!value.fields || typeof value.fields !== "object" || Array.isArray(value.fields)) {
+    throw new Error("block.fields must be an object");
+  }
+  const fields: Record<string, FieldSnapshot> = {};
+  for (const [name, fieldRaw] of Object.entries(value.fields as Record<string, unknown>)) {
+    try {
+      fields[name] = parseFieldSnapshot(fieldRaw);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "invalid field";
+      throw new Error(`block.fields.${name}: ${msg}`);
+    }
+  }
+  return { name: value.name, fields };
+}

package/src/coerce.ts

@@ -0,0 +1,74 @@
+// packages/core/src/coerce.ts
+import type { BlockSnapshot } from "./block";
+import type { FieldKind, FieldSnapshot } from "./fields";
+import type { Frontmatter } from "./mdx";
+import type { ModelSnapshot } from "./model";
+
+const IMAGE_URL_KEYS = ["src", "url", "href"] as const;
+
+/** Models often write `{ src, alt }` for image fields; storage is a URL string. */
+export function coerceFieldValue(kind: FieldKind, value: unknown): unknown {
+  if (kind !== "image") return value;
+  return imageUrlFromUnknown(value);
+}
+
+export function imageUrlFromUnknown(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value;
+  const rec = value as Record<string, unknown>;
+  for (const key of IMAGE_URL_KEYS) {
+    const candidate = rec[key];
+    if (typeof candidate === "string") return candidate;
+  }
+  return value;
+}
+
+function coerceRecord(
+  fields: Record<string, FieldSnapshot>,
+  data: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...data };
+  for (const [name, field] of Object.entries(fields)) {
+    if (!(name in out)) continue;
+    out[name] = coerceFieldValue(field.kind, out[name]);
+  }
+  return out;
+}
+
+function coerceBlocks(value: unknown, catalog: BlockSnapshot[]): unknown {
+  if (!Array.isArray(value)) return value;
+  const byName = new Map(catalog.map((b) => [b.name, b]));
+  return value.map((item) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) return item;
+    const block = item as Record<string, unknown>;
+    const propsRaw = block.props;
+    const props =
+      propsRaw && typeof propsRaw === "object" && !Array.isArray(propsRaw)
+        ? { ...(propsRaw as Record<string, unknown>) }
+        : {};
+    const def = typeof block.type === "string" ? byName.get(block.type) : undefined;
+    const nextProps = def
+      ? coerceRecord(def.fields, props)
+      : Object.fromEntries(
+          Object.entries(props).map(([k, v]) => [k, imageUrlFromUnknown(v)]),
+        );
+    return { ...block, props: nextProps };
+  });
+}
+
+/** Flatten image-like objects in model fields and nested block props. */
+export function coerceDocValues(
+  model: Pick<ModelSnapshot, "fields">,
+  frontmatter: Frontmatter,
+  catalog: BlockSnapshot[] = [],
+): Frontmatter {
+  const out: Frontmatter = { ...frontmatter };
+  for (const [name, field] of Object.entries(model.fields)) {
+    if (!(name in out)) continue;
+    if (field.kind === "blocks") {
+      out[name] = coerceBlocks(out[name], catalog);
+    } else {
+      out[name] = coerceFieldValue(field.kind, out[name]);
+    }
+  }
+  return out;
+}

package/src/config.ts

@@ -0,0 +1,125 @@
+// packages/core/src/config.ts
+// General host configuration (`backmatter.config.ts`). Models are never listed
+// here; they are discovered from the `models/` folder.
+import { detectGitBranch } from "./sync-schema";
+
+export type BackmatterDirs = {
+  /** Folder with one `defineModel` default export per file. Default: "models". */
+  models?: string;
+  /** Folder with one `defineBlock` default export per file. Default: "blocks". */
+  blocks?: string;
+  /** Folder with one MDX tag component default export per file. Default: "mdx". */
+  mdx?: string;
+  /** Folder with one layout default export per model type. Default: "layouts". */
+  layouts?: string;
+};
+
+export type BackmatterConfig = {
+  /** Required only when talking to the BACKMATTER API. Env: BACKMATTER_WORKSPACE_ID. */
+  workspaceId?: string;
+  /** Env: BACKMATTER_API_URL. When set with workspaceId, published docs load from the API. */
+  apiUrl?: string;
+  /** Env: BACKMATTER_CONTENT_TOKEN. Required only to read non-default branches. */
+  contentToken?: string;
+  /** Env: BACKMATTER_PREVIEW_TOKEN. Working-tree reads and signed preview cookies. */
+  previewToken?: string;
+  /** Env: BACKMATTER_HOST_TOKEN. When set with apiUrl, the schema snapshot syncs on boot. */
+  hostToken?: string;
+  /** Git branch for the schema sync. Env: BACKMATTER_GIT_BRANCH / VERCEL_GIT_COMMIT_REF. */
+  branch?: string;
+  /**
+   * Public origin of this host (no trailing slash). Used to register the
+   * revalidate webhook. Env: BACKMATTER_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?: BackmatterDirs;
+};
+
+export type ResolvedConfig = Omit<BackmatterConfig, "dirs" | "defaultLocale"> & {
+  defaultLocale: string;
+  dirs: Required<BackmatterDirs>;
+};
+
+export const DEFAULT_DIRS: Required<BackmatterDirs> = {
+  models: "models",
+  blocks: "blocks",
+  mdx: "mdx",
+  layouts: "layouts",
+};
+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.BACKMATTER_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 `backmatter.config.ts` a typed default export. */
+export function defineConfig(config: BackmatterConfig): BackmatterConfig {
+  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: BackmatterConfig = {},
+  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, "BACKMATTER_WORKSPACE_ID"),
+    apiUrl: pick(config.apiUrl, "BACKMATTER_API_URL"),
+    contentToken: pick(config.contentToken, "BACKMATTER_CONTENT_TOKEN"),
+    previewToken: pick(config.previewToken, "BACKMATTER_PREVIEW_TOKEN"),
+    hostToken: pick(config.hostToken, "BACKMATTER_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,
+      mdx: config.dirs?.mdx ?? DEFAULT_DIRS.mdx,
+      layouts: config.dirs?.layouts ?? DEFAULT_DIRS.layouts,
+    },
+  };
+}

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 BACKMATTER_REVALIDATE_PATH = "/api/backmatter/revalidate";
+
+export const BACKMATTER_CACHE_TAG = "backmatter";
+
+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(/\/$/, "")}${BACKMATTER_REVALIDATE_PATH}`;
+}
+
+export function contentCacheTags(locale: string, type: string, slug: string): string[] {
+  return [BACKMATTER_CACHE_TAG, `backmatter:${type}`, `backmatter:${locale}:${type}:${slug}`];
+}
+
+export function listCacheTags(type?: string): string[] {
+  return type ? [BACKMATTER_CACHE_TAG, `backmatter:${type}`] : [BACKMATTER_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-format.ts

@@ -0,0 +1,32 @@
+// packages/core/src/doc-format.ts
+import { parseMdx, serializeMdx, type Frontmatter, type ParsedMdx } from "./mdx";
+
+export type DocFormat = "mdx" | "page";
+
+export function modelFormat(model: { format?: string } | null | undefined): DocFormat {
+  return model?.format === "page" ? "page" : "mdx";
+}
+
+export function parseDoc(raw: string, format: DocFormat = "mdx"): ParsedMdx {
+  if (format !== "page") return parseMdx(raw);
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "invalid JSON";
+    throw new Error(`JSON: ${msg}`);
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("page document must be a JSON object");
+  }
+  return { frontmatter: value as Frontmatter, body: "" };
+}
+
+export function serializeDoc(
+  format: DocFormat,
+  frontmatter: Frontmatter,
+  body: string,
+): string {
+  if (format !== "page") return serializeMdx(frontmatter, body);
+  return `${JSON.stringify(frontmatter, null, 2)}\n`;
+}

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 BackmatterDocSummary = {
+  locale: string;
+  type: string;
+  slug: string;
+};
+
+export type BackmatterDoc = {
+  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,92 @@
+// packages/core/src/fields.ts
+
+export type FieldKind =
+  | "text"
+  | "slug"
+  | "locale"
+  | "image"
+  | "relation"
+  | "number"
+  | "boolean"
+  | "blocks";
+
+/**
+ * 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 }),
+  blocks: <const R extends boolean = false>(opts?: Opts<R>) => base("blocks", opts),
+};
+
+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",
+    "blocks",
+  ];
+  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;
+}