@bettercms-ai/codegen 0.5.0

package/README.md

@@ -0,0 +1,102 @@
+# @bettercms-ai/codegen
+
+Generate TypeScript types from your BetterCMS content schema.
+
+Your models are defined once — in the dashboard schema builder **or** by your AI through
+the MCP tools. Both write the same underlying field schema, so the types this generates can
+never drift from what your editors and agents actually create. This is the **deterministic
+floor** under the AI integration: even if an agent mis-wires something, you still have exact,
+committed types to fall back on.
+
+## Use it
+
+```bash
+# In your site repo (key from the dashboard → Settings → API Keys, content:manage scope)
+BETTERCMS_API_KEY=bcms_xxx npx @bettercms-ai/codegen --out src/bettercms.generated.ts
+```
+
+```
+✓ Generated 2 model types → src/bettercms.generated.ts
+```
+
+Commit the generated file and re-run codegen after any schema change (a CI step or the
+BetterCMS GitHub Action does this for you on every build).
+
+### Options
+
+| Flag | Env | Default |
+|------|-----|---------|
+| `--out, -o` | — | `bettercms.generated.ts` |
+| `--bindings-out` | — | _(off)_ — also emit Live Preview bindings to this path |
+| `--api-url` | `BETTERCMS_API_URL` | `https://api.bettercms.ai/api/v1` |
+| `--key` | `BETTERCMS_API_KEY` | — |
+
+## What it emits
+
+For a `blog` model with `title` (text, required), `body` (richtext), `hero` (group):
+
+```ts
+export interface BlogFields {
+  readonly title: string;
+  readonly body?: RichText;
+  readonly hero?: {
+    readonly heading: string;
+  };
+}
+
+export interface BetterCMSSchema {
+  readonly "blog": BlogFields;
+}
+export type BetterCMSModelSlug = keyof BetterCMSSchema;
+```
+
+The `BetterCMSSchema` registry lets the Next.js adapter type `getEntry("blog", …)` by slug.
+
+## Field type → TypeScript
+
+| Field | TS |
+|-------|-----|
+| text · date · datetime | `string` |
+| richtext | `RichText` |
+| image | `BetterCMSImage` |
+| boolean / number | `boolean` / `number` |
+| select | `"a" \| "b"` (or `string`) |
+| reference / multi-reference | `string` / `string[]` (entry ids) |
+| array | `string[]` / `number[]` |
+| group | `{ …nested }` |
+| repeater | `Array<{ …nested }>` |
+
+## Live Preview bindings (`--bindings-out`)
+
+Pass `--bindings-out src/bettercms.bindings.generated.ts` to also emit a tiny, schema-derived
+helper that powers the dashboard's **Live Preview** editor. Spread a binding onto the element
+that renders each field — the editor reads the resulting `data-bcms-field` attribute to make the
+real, running site editable in place:
+
+```tsx
+import { bcms } from "./bettercms.bindings.generated";
+
+<h1 {...bcms.blog.title}>{entry.fields.title}</h1>            // scalar
+<li {...bcms.blog.tags.value(i)}>{tag}</li>                   // primitive-array item
+<article {...bcms.blog.features.$(i)}>                        // array item root
+  <h3 {...bcms.blog.features.label(i)}>{f.label}</h3>         // array item sub-field
+</article>
+```
+
+The attributes are emitted **only** when the site is built with `BCMS_ANNOTATE` set (preview
+builds); a normal production build ships zero extra attributes (`bcmsField` returns `{}`). Same
+generated file for both — no separate mode. Bindings follow the editor's one-level path grammar
+(`field`, `field[i]`, `field[i].sub`); non-repeatable zones and deeper nesting aren't
+index-addressable yet, so they're omitted rather than emitted as paths that can't bind.
+
+## Library API
+
+```ts
+import { generateTypes, generateBindings, fetchModels } from "@bettercms-ai/codegen";
+
+const models = await fetchModels({ apiUrl, apiKey });
+const types = generateTypes(models);       // pure, deterministic
+const bindings = generateBindings(models); // pure, deterministic (Live Preview)
+```
+
+`generateTypes` and `generateBindings` are pure and deterministic — same models in, byte-identical output out.

package/dist/cli.js

@@ -0,0 +1,501 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { writeFile, mkdir } from "fs/promises";
+import { dirname, resolve } from "path";
+
+// src/fetch-models.ts
+async function fetchModels(opts) {
+  const doFetch = opts.fetchImpl ?? globalThis.fetch;
+  const base = opts.apiUrl.replace(/\/+$/, "");
+  const url = `${base}/management/content/models`;
+  let res;
+  try {
+    res = await doFetch(url, {
+      // No Content-Type: this is a bodyless GET; the header is incorrect here and
+      // strict edge runtimes/proxies may reject it.
+      headers: { Authorization: `Bearer ${opts.apiKey}`, Accept: "application/json" }
+    });
+  } catch (err) {
+    throw new Error(
+      `Could not reach the BetterCMS Management API at ${url}: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  if (!res.ok) {
+    const hint = res.status === 401 || res.status === 403 ? " \u2014 check your management API key (it must have the content:manage scope)." : "";
+    throw new Error(`Management API returned ${res.status} ${res.statusText}${hint}`);
+  }
+  const body = await res.json();
+  const rows = body.data ?? [];
+  return rows.map((r) => ({
+    slug: r.slug,
+    name: r.name,
+    description: r.description ?? null,
+    fields: r.fields ?? []
+  }));
+}
+
+// src/generate.ts
+var PREAMBLE = `/**
+ * Rich-text field value returned by the Delivery API.
+ *
+ * - \`format\`/\`value\`: the portable, editor-agnostic payload (Lexical EditorState) \u2014
+ *   render it with your editor's serializer for full fidelity.
+ * - \`html\`: server-rendered, sanitized HTML (computed render-on-write). Present on
+ *   Delivery reads; the simplest path for non-React consumers \u2014 safe to inject directly
+ *   (e.g. \`dangerouslySetInnerHTML\`). Optional: legacy/un-normalized values may omit it.
+ *
+ * The \`{ format, value }\` contract is unchanged; \`html\` is additive.
+ */
+export type RichText = {
+  readonly format: string;
+  readonly value: unknown;
+  readonly html?: string;
+};
+
+/**
+ * Image / media field value as stored and returned verbatim by the Delivery API
+ * (server-normalized on write to the canonical shape). \`url\` is always present; an
+ * unresolved/external value may carry only \`url\`. \`altText\` is the accessibility text
+ * for \`<img alt>\`.
+ */
+export interface BetterCMSImage {
+  readonly id?: string;
+  readonly url: string;
+  readonly name?: string;
+  readonly altText?: string | null;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+/**
+ * Delivery envelope around a model's typed \`data\`. \`getEntry\`/\`listEntries\` in the
+ * Next adapter return this shape, with \`fields\` typed by the model.
+ */
+export interface BetterCMSEntry<TFields> {
+  readonly slug: string;
+  readonly status: "draft" | "published";
+  readonly fields: TFields;
+  readonly updatedAt: string;
+}
+`;
+function pascalCase(slug) {
+  const parts = slug.split(/[-_\s]+/).filter(Boolean);
+  const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  return /^[0-9]/.test(pascal) ? `Model${pascal}` : pascal || "Model";
+}
+function escapeJsDoc(text) {
+  return text.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ").trim();
+}
+var VALID_IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function propName(key) {
+  return VALID_IDENT.test(key) ? key : JSON.stringify(key);
+}
+function scalarType(field) {
+  const t = field.type;
+  switch (t) {
+    case "text":
+      return "string";
+    case "richtext":
+      return "RichText";
+    case "image":
+      return "BetterCMSImage";
+    case "boolean":
+      return "boolean";
+    case "number":
+      return "number";
+    case "date":
+    case "datetime":
+      return "string";
+    // ISO 8601
+    case "select": {
+      const opts = field.options?.filter((o) => typeof o === "string") ?? [];
+      return opts.length > 0 ? opts.map((o) => JSON.stringify(o)).join(" | ") : "string";
+    }
+    case "reference":
+      return "string";
+    // referenced entry id
+    case "multi-reference":
+      return "string[]";
+    // referenced entry ids
+    case "array": {
+      const itemType = field.config?.itemType ?? "text";
+      const inner = itemType === "number" ? "number" : "string";
+      return `${inner}[]`;
+    }
+    default: {
+      const _exhaustive = t;
+      return "unknown";
+    }
+  }
+}
+function arrayZoneType(field, indent) {
+  const zones = field.config?.zones;
+  const parts = [];
+  if (zones?.nonRepeatable?.length) {
+    const nested = fieldsToBody(zones.nonRepeatable, indent + "  ");
+    parts.push(`${indent}  readonly nonRepeatable?: {
+${nested}
+${indent}  };`);
+  }
+  if (zones?.repeatable?.fields?.length) {
+    const nested = fieldsToBody(zones.repeatable.fields, indent + "    ");
+    parts.push(`${indent}  readonly repeatable?: Array<{
+${nested}
+${indent}  }>;`);
+  }
+  if (parts.length === 0) return "Record<string, unknown>";
+  return `{
+${parts.join("\n")}
+${indent}}`;
+}
+function fieldsToBody(fields, indent) {
+  const lines = [];
+  for (const field of fields) {
+    const optional = field.required ? "" : "?";
+    let typeExpr;
+    if (field.type === "array" && field.config?.zones) {
+      typeExpr = arrayZoneType(field, indent);
+    } else {
+      typeExpr = scalarType(field);
+    }
+    const safeLabel = field.label ? escapeJsDoc(field.label) : "";
+    if (safeLabel && safeLabel !== field.key) {
+      lines.push(`${indent}/** ${safeLabel} */`);
+    }
+    lines.push(`${indent}readonly ${propName(field.key)}${optional}: ${typeExpr};`);
+  }
+  return lines.join("\n");
+}
+function generateTypes(models, opts = {}) {
+  const version = opts.version ?? "0.1.0";
+  const sorted = [...models].sort(
+    (a, b) => a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0
+  );
+  const header = `// \u26A0\uFE0F  AUTO-GENERATED by @bettercms-ai/codegen v${version} \u2014 DO NOT EDIT.
+// Regenerate with: npx @bettercms-ai/codegen
+// Source of truth: your BetterCMS content models (the same schema the dashboard
+// builder and the MCP tools write). Re-run codegen after any schema change.
+${opts.bannerComment ? `// ${opts.bannerComment}
+` : ""}`;
+  const interfaces = [];
+  const mapEntries = [];
+  const usedNames = /* @__PURE__ */ new Set();
+  for (const model of sorted) {
+    const base = `${pascalCase(model.slug)}Fields`;
+    let typeName = base;
+    for (let n = 2; usedNames.has(typeName); n++) typeName = `${base}_${n}`;
+    usedNames.add(typeName);
+    const name = model.name ? escapeJsDoc(model.name) : "";
+    const desc = model.description ? escapeJsDoc(model.description) : "";
+    const doc = name ? `/**
+ * ${name}${desc ? ` \u2014 ${desc}` : ""}
+ * Model slug: \`${model.slug}\`
+ */
+` : "";
+    const body = model.fields.length ? fieldsToBody(model.fields, "  ") : "  // (no fields defined yet)";
+    interfaces.push(`${doc}export interface ${typeName} {
+${body}
+}`);
+    mapEntries.push(`  readonly ${JSON.stringify(model.slug)}: ${typeName};`);
+  }
+  const schemaMap = `/**
+ * Registry mapping each model slug to its typed fields. The Next adapter uses this to
+ * type \`getEntry("blog", ...)\` by slug \u2014 autocomplete and exhaustiveness for free.
+ */
+export interface BetterCMSSchema {
+${mapEntries.join("\n") || "  // (no models defined yet)"}
+}
+
+/** Union of all model slugs. */
+export type BetterCMSModelSlug = keyof BetterCMSSchema;`;
+  return [header, PREAMBLE, interfaces.join("\n\n"), schemaMap, ""].join("\n");
+}
+
+// src/bindings.ts
+var VALID_IDENT2 = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+function propName2(key) {
+  return VALID_IDENT2.test(key) ? key : JSON.stringify(key);
+}
+function bindingKind(t) {
+  switch (t) {
+    case "text":
+    case "richtext":
+    case "image":
+    case "boolean":
+    case "number":
+    case "select":
+    case "array":
+      return t;
+    // reference / multi-reference / date / datetime → plain text in the editor v1.
+    default:
+      return "text";
+  }
+}
+function indexedPath(prefix, suffix) {
+  return `${JSON.stringify(prefix)} + i + ${JSON.stringify(suffix)}`;
+}
+function repeaterBinding(itemFields, path, indent) {
+  const lines = [
+    `${indent}  $: (i: number) => bcmsField(${indexedPath(`${path}[`, "]")}, "array"),`
+  ];
+  for (const sub of itemFields) {
+    if (sub.type === "array") continue;
+    lines.push(
+      `${indent}  ${propName2(sub.key)}: (i: number) => bcmsField(${indexedPath(`${path}[`, `].${sub.key}`)}, ${JSON.stringify(bindingKind(sub.type))}),`
+    );
+  }
+  return `{
+${lines.join("\n")}
+${indent}}`;
+}
+function fieldBinding(field, prefix, indent) {
+  const path = prefix ? `${prefix}.${field.key}` : field.key;
+  const name = propName2(field.key);
+  if (field.type !== "array") {
+    return `${indent}${name}: bcmsField(${JSON.stringify(path)}, ${JSON.stringify(bindingKind(field.type))}),`;
+  }
+  const zones = field.config?.zones;
+  if (zones?.nonRepeatable?.length) {
+    const body = zones.nonRepeatable.map((child) => fieldBinding(child, path, `${indent}  `)).join("\n");
+    return `${indent}${name}: {
+${body}
+${indent}},`;
+  }
+  if (zones?.repeatable?.fields?.length) {
+    return `${indent}${name}: ${repeaterBinding(zones.repeatable.fields, path, indent)},`;
+  }
+  const lines = [
+    `${indent}  $: (i: number) => bcmsField(${indexedPath(`${path}[`, "]")}, "array"),`,
+    `${indent}  value: (i: number) => bcmsField(${indexedPath(`${path}[`, "].value")}, "text"),`
+  ];
+  return `${indent}${name}: {
+${lines.join("\n")}
+${indent}},`;
+}
+function fieldsToBindings(fields, indent) {
+  return fields.map((field) => fieldBinding(field, "", indent)).join("\n");
+}
+var PREAMBLE2 = `/**
+ * True when this site is built for Live Preview annotation. Set \`BCMS_ANNOTATE=1\`
+ * in the preview build only; unset (the default) ships zero binding attributes.
+ * Read defensively so the module is safe in any runtime (browser, Node, edge).
+ */
+const BCMS_ANNOTATE: boolean = (() => {
+  try {
+    const v = (globalThis as { process?: { env?: Record<string, string | undefined> } })
+      .process?.env?.BCMS_ANNOTATE;
+    return v != null && v !== "" && v !== "0" && v !== "false";
+  } catch {
+    return false;
+  }
+})();
+
+/**
+ * Binding attributes for a CMS-bound element. Spread onto the element that renders a
+ * field: \`<h1 {...bcmsField("title", "text")}>\`. Returns \`{}\` unless BCMS_ANNOTATE
+ * is set, so production markup is untouched.
+ */
+export function bcmsField(path: string, kind: string): Record<string, string> {
+  return BCMS_ANNOTATE ? { "data-bcms-field": path, "data-bcms-kind": kind } : {};
+}
+`;
+function generateBindings(models, opts = {}) {
+  const version = opts.version ?? "0.1.0";
+  const sorted = [...models].sort(
+    (a, b) => a.slug < b.slug ? -1 : a.slug > b.slug ? 1 : 0
+  );
+  const header = `// \u26A0\uFE0F  AUTO-GENERATED by @bettercms-ai/codegen v${version} \u2014 DO NOT EDIT.
+// Live Preview field bindings. Regenerate with: npx @bettercms-ai/codegen --bindings-out <path>
+// Spread these onto the elements that render your content; they emit
+// data-bcms-field/data-bcms-kind only when the site is built with BCMS_ANNOTATE set.
+${opts.bannerComment ? `// ${opts.bannerComment}
+` : ""}`;
+  const entries = sorted.map((model) => {
+    const body = model.fields.length ? `
+${fieldsToBindings(model.fields, "    ")}
+  ` : "";
+    return `  ${JSON.stringify(model.slug)}: {${body}},`;
+  });
+  const bcms = `/**
+ * Field bindings keyed by model slug. Spread a binding onto the element that renders
+ * that field. Arrays expose \`$(i)\` for the item element and one accessor per
+ * (one-level) sub-field; primitive arrays expose \`value(i)\` for the item's scalar.
+ */
+export const bcms = {
+${entries.join("\n") || "  // (no models defined yet)"}
+} as const;`;
+  return [header, PREAMBLE2, bcms, ""].join("\n");
+}
+
+// src/components.ts
+function generateComponents(opts = {}) {
+  const version = opts.version ?? "0.1.0";
+  const header = `// \u26A0\uFE0F  AUTO-GENERATED by @bettercms-ai/codegen v${version} \u2014 DO NOT EDIT.
+// Regenerate with: npx @bettercms-ai/codegen --components-out <path>
+// Typed render components for BetterCMS field shapes. Use these instead of
+// hand-rendering richtext/image values \u2014 they render the canonical shapes correctly.
+${opts.bannerComment ? `// ${opts.bannerComment}
+` : ""}`;
+  const body = `import * as React from "react";
+
+/** Rich-text value from the Delivery API. \`html\` is server-rendered + sanitized. */
+export type RichTextValue = {
+  readonly format: string;
+  readonly value: unknown;
+  readonly html?: string;
+};
+
+/** Normalized image/media value from the Delivery API. */
+export interface BetterCMSImageValue {
+  readonly url: string;
+  readonly altText?: string | null;
+  readonly width?: number;
+  readonly height?: number;
+}
+
+type RichTextProps = {
+  /** The richtext field value (\`entry.fields.someRichText\`). */
+  field?: RichTextValue | null;
+  /** Element/component to render as. Default: \`"div"\`. */
+  as?: React.ElementType;
+} & Omit<React.HTMLAttributes<HTMLElement>, "dangerouslySetInnerHTML" | "children">;
+
+/**
+ * Render a richtext field as HTML. Uses the server-sanitized \`html\` via
+ * \`dangerouslySetInnerHTML\` \u2014 NEVER interpolate a richtext value as a JSX child
+ * (React escapes it, so the page shows literal tags). Renders nothing when unset.
+ */
+export function RichText({ field, as: Tag = "div", ...rest }: RichTextProps) {
+  if (!field || !field.html) return null;
+  return <Tag {...rest} dangerouslySetInnerHTML={{ __html: field.html }} />;
+}
+
+type ImageProps = {
+  /** The image field value (\`entry.fields.someImage\`). */
+  field?: BetterCMSImageValue | null;
+  /** Alt text override; defaults to the field's \`altText\`, then \`""\`. */
+  alt?: string;
+} & Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src">;
+
+/**
+ * Render an image field as an \`<img>\` from its normalized \`.url\`/\`.altText\`.
+ * Renders nothing when unset. Pass \`alt\` to override the stored alt text.
+ */
+export function Image({ field, alt, ...rest }: ImageProps) {
+  if (!field || !field.url) return null;
+  return (
+    <img
+      src={field.url}
+      alt={alt ?? field.altText ?? ""}
+      width={field.width}
+      height={field.height}
+      {...rest}
+    />
+  );
+}
+`;
+  return [header, body].join("\n");
+}
+
+// src/cli.ts
+var VERSION = "0.2.0";
+var DEFAULT_API_URL = "https://api.bettercms.ai/api/v1";
+var DEFAULT_OUT = "bettercms.generated.ts";
+function parseArgs(argv) {
+  const args = {
+    apiUrl: process.env.BETTERCMS_API_URL ?? DEFAULT_API_URL,
+    apiKey: process.env.BETTERCMS_API_KEY,
+    out: DEFAULT_OUT,
+    bindingsOut: void 0,
+    componentsOut: void 0,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const next = () => argv[++i];
+    switch (arg) {
+      case "--api-url":
+        args.apiUrl = next() ?? args.apiUrl;
+        break;
+      case "--key":
+      case "--api-key":
+        args.apiKey = next();
+        break;
+      case "--out":
+      case "-o":
+        args.out = next() ?? args.out;
+        break;
+      case "--bindings-out":
+        args.bindingsOut = next();
+        break;
+      case "--components-out":
+        args.componentsOut = next();
+        break;
+      case "--help":
+      case "-h":
+        args.help = true;
+        break;
+    }
+  }
+  return args;
+}
+var HELP = `bettercms-codegen v${VERSION} \u2014 generate TypeScript types from your BetterCMS schema
+
+Usage:
+  npx @bettercms-ai/codegen [options]
+
+Options:
+  -o, --out <path>      Output file (default: ${DEFAULT_OUT})
+      --bindings-out <path>  Also emit the Live Preview bindings module to <path>
+      --components-out <path>  Also emit typed <RichText>/<Image> React components (.tsx) to <path>
+      --api-url <url>   Management API base (default: ${DEFAULT_API_URL})
+      --key <key>       Management API key (or set BETTERCMS_API_KEY)
+  -h, --help            Show this help
+
+Env:
+  BETTERCMS_API_KEY     Management-scoped key (content:manage)
+  BETTERCMS_API_URL     Override the API base
+`;
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (!args.apiKey) {
+    process.stderr.write(
+      "error: no API key. Pass --key <key> or set BETTERCMS_API_KEY.\n"
+    );
+    process.exit(1);
+  }
+  const models = await fetchModels({ apiUrl: args.apiUrl, apiKey: args.apiKey });
+  const outPath = resolve(process.cwd(), args.out);
+  await mkdir(dirname(outPath), { recursive: true });
+  await writeFile(outPath, generateTypes(models, { version: VERSION }), "utf8");
+  const plural = models.length === 1 ? "" : "s";
+  process.stdout.write(
+    `\u2713 Generated ${models.length} model type${plural} \u2192 ${args.out}
+`
+  );
+  if (args.bindingsOut) {
+    const bindingsPath = resolve(process.cwd(), args.bindingsOut);
+    await mkdir(dirname(bindingsPath), { recursive: true });
+    await writeFile(bindingsPath, generateBindings(models, { version: VERSION }), "utf8");
+    process.stdout.write(`\u2713 Generated Live Preview bindings \u2192 ${args.bindingsOut}
+`);
+  }
+  if (args.componentsOut) {
+    const componentsPath = resolve(process.cwd(), args.componentsOut);
+    await mkdir(dirname(componentsPath), { recursive: true });
+    await writeFile(componentsPath, generateComponents({ version: VERSION }), "utf8");
+    process.stdout.write(`\u2713 Generated render components \u2192 ${args.componentsOut}
+`);
+  }
+}
+main().catch((err) => {
+  process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}
+`);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map