@bettercms-ai/codegen 0.6.0 → 0.7.0

package/dist/cli.js

@@ -0,0 +1,733 @@
+#!/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.
+ */
+/**
+ * One Portable Text block, or a block object (an image, an embed, a placed component).
+ *
+ * Inlined rather than imported: this preamble is emitted INTO your repo and is deliberately
+ * dependency-free. To render structure, \`npm i @portabletext/react\` and pass
+ * \`portableText(field)\` to it; to render without adding anything, keep using \`rich()\`.
+ */
+export type PortableTextBlock = {
+  readonly _type: string;
+  readonly _key: string;
+  readonly style?: string;
+  readonly listItem?: string;
+  readonly level?: number;
+  readonly markDefs?: readonly { readonly _type: string; readonly _key: string; readonly [k: string]: unknown }[];
+  readonly children?: readonly { readonly _type: string; readonly _key: string; readonly text?: string; readonly marks?: readonly string[] }[];
+  readonly [k: string]: unknown;
+};
+
+export type RichText = {
+  /**
+   * The storage format. Deliberately \`string\` and NOT a literal union: a project mid-backfill
+   * holds both \`"lexical-\u2026"\` and \`"portable-text-1"\` values, and narrowing this would give a
+   * type error to anyone regenerating types against it.
+   */
+  readonly format: string;
+  /** Portable Text blocks when \`format\` is \`"portable-text-1"\`; editor state otherwise. */
+  readonly value: unknown;
+  /**
+   * Server-rendered, sanitized HTML. ALWAYS present, in every format, forever \u2014 sites built
+   * before Portable Text existed read this directly and cannot be rebuilt.
+   */
+  readonly html?: string;
+  /**
+   * @deprecated Superseded by Portable Text \u2014 read \`portableText(field)\` instead. Retained so
+   * entries written before the migration keep type-checking; nothing mints it any more.
+   *
+   * Structured blocks. Present on Body (\`document\`) fields ONLY, and optional even there \u2014
+   * it is derived at write time, so an entry saved before this existed carries none until its
+   * next save, and there is no backfill. Branch on its absence; \`html\` is always there.
+   *
+   * \`id\` is stable within ONE document, never a global key \u2014 two entries both have a "0.0".
+   * A cross-document anchor is (entryId, fieldKey, id).
+   */
+  readonly doc?: {
+    readonly version: 1;
+    readonly blocks: readonly { readonly id: string; readonly type: string; readonly [k: string]: unknown }[];
+  };
+};
+
+/**
+ * A field that may arrive as EITHER shape.
+ *
+ * Switching a field between \`text\` and \`richtext\` in the CMS switches what Delivery
+ * returns for it \u2014 a bare string becomes \`{ format, value, html }\`. Type author-editable
+ * text with this and read it through \`plain()\`/\`rich()\` below, and that switch stops being
+ * a site-breaking change. Interpolating the value directly renders \`[object Object]\`.
+ */
+export type TextOrRich = string | RichText | null | undefined;
+
+/** True when the value is a rich-text envelope rather than a bare string. */
+export function isRichText(value: unknown): value is RichText {
+  return (
+    typeof value === "object" && value !== null && !Array.isArray(value) &&
+    ("html" in value || "format" in value)
+  );
+}
+
+/** The marker on a Portable Text envelope. */
+export const PORTABLE_TEXT_FORMAT = "portable-text-1";
+
+/**
+ * Portable Text blocks when the field stores them, otherwise null.
+ *
+ * ADDITIVE. \`rich()\` and \`plain()\` keep working exactly as before on every format, so
+ * nothing you have already shipped needs to change. Use this only if you want to render the
+ * structure yourself \u2014 for example with \`@portabletext/react\`.
+ */
+export function portableText(value: TextOrRich): readonly PortableTextBlock[] | null {
+  if (!isRichText(value)) return null;
+  return value.format === PORTABLE_TEXT_FORMAT && Array.isArray(value.value)
+    ? (value.value as readonly PortableTextBlock[])
+    : null;
+}
+
+/** Plain text for attribute contexts \u2014 \`<title>\`, meta description, JSON-LD, \`alt\`. */
+export function plain(value: TextOrRich): string {
+  if (typeof value === "string") return value;
+  if (!isRichText(value) || typeof value.html !== "string") return "";
+  return decodeEntities(value.html.replace(/<[^>]+>/g, "")).trim();
+}
+
+/**
+ * Renderable HTML, for \`set:html\` / \`dangerouslySetInnerHTML\`. Rich text keeps its inline
+ * marks (the server sanitizes \`html\` on write); a bare string is escaped, so a plain field
+ * can never inject markup. A LONE wrapping block is unwrapped \u2014 a field switched from
+ * \`text\` stores \`<p>\u2026</p>\`, and \`<h1><p>\u2026</p></h1>\` is invalid HTML (the parser closes the
+ * heading early, dropping the text out of it). Real block structure is left alone.
+ */
+export function rich(value: TextOrRich, fallback = ""): string {
+  const html = (
+    typeof value === "string" ? escapeHtml(value) : isRichText(value) ? (value.html ?? "") : ""
+  ).trim();
+  return html ? unwrapLoneBlock(html) : escapeHtml(fallback);
+}
+
+function unwrapLoneBlock(html: string): string {
+  const m = html.match(/^<(p|div|h[1-6])(?:\\s[^>]*)?>([\\s\\S]*)<\\/\\1>$/i);
+  return m && !new RegExp(\`</\${m[1]}>\`, "i").test(m[2]) ? m[2] : html;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"')
+    .replace(/&#0?39;/g, "'").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&");
+}
+
+/**
+ * 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;
+}
+
+/**
+ * A component slot's value, as stored and delivered.
+ *
+ * \`componentId\` points at a component definition; \`overrides\` are the author's values,
+ * keyed by the component's declared prop keys.
+ *
+ * \`resolved\` is the SNAPSHOT: at publish time the component is resolved (its block tree
+ * with the overrides applied) and frozen onto the published value. That is why editing a
+ * component does not silently rewrite entries that were already published \u2014 a published
+ * entry carries what it was published with until it is published again.
+ *
+ * Read \`resolved\` when it is there; it is absent on draft-perspective reads, where you
+ * should resolve \`componentId\` yourself against the components endpoint.
+ */
+export interface BetterCMSComponentRef {
+  readonly componentId: string;
+  readonly overrides?: Readonly<Record<string, unknown>>;
+  readonly resolved?: readonly unknown[];
+}
+
+/**
+ * One block in a section zone, as stored and delivered.
+ *
+ * This is the SAME shape a page's \`blockJson\` holds \u2014 a section zone is a composable page
+ * region, so it delivers page blocks, not a shape of its own. Deliberately structural rather
+ * than a discriminated union over every block type: the container blocks
+ * (\`columns\`, \`section\`, \`slider\`, \`tabs\`) nest \`BetterCMSBlock\` inside \`props\`,
+ * and the block vocabulary is server-side and versioned independently of any generated SDK.
+ * Narrow on \`type\` at the call site.
+ *
+ * \`style\` carries the block's design tokens when the author set any.
+ */
+export interface BetterCMSBlock {
+  readonly type: string;
+  readonly id: string;
+  readonly props?: Readonly<Record<string, unknown>>;
+  readonly style?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * 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;
+}
+
+/** Fully resolved published or preview Layout returned beside a delivered page. */
+export interface BetterCMSLayout {
+  readonly version: 1;
+  readonly nodes: ReadonlyArray<
+    | { readonly kind: "page-content"; readonly id: "page-content" }
+    | {
+        readonly kind: "section";
+        readonly id: string;
+        readonly slug: string;
+        readonly name: string;
+        readonly source: "inherit" | "override-content" | "customize-structure" | "page-only" | "detached";
+      }
+  >;
+  readonly sections: Readonly<Record<string, {
+    readonly id: string;
+    readonly slug: string;
+    readonly name: string;
+    /** Headless Section values, including values represented by direct field items. */
+    readonly fields: Readonly<Record<string, unknown>>;
+    readonly items: ReadonlyArray<
+      | { readonly id: string; readonly kind: "field"; readonly fieldId: string; readonly value: unknown }
+      | {
+          readonly id: string;
+          readonly kind: "component";
+          readonly componentId: string;
+          readonly variantGroupId?: string;
+          readonly canonicalInputs: readonly BetterCMSLayoutInput[];
+          readonly bindings: ReadonlyArray<{ readonly inputId: string; readonly fieldId: string }>;
+          readonly canonicalValues: Readonly<Record<string, unknown>>;
+          readonly resolvedProps: Readonly<Record<string, unknown>>;
+          readonly blocks: readonly unknown[];
+        }
+    >;
+  }>>;
+}
+
+/** Recursive canonical input description exposed with each delivered Component item. */
+export interface BetterCMSLayoutInput {
+  readonly id: string;
+  readonly slug: string;
+  readonly label: string;
+  readonly type: string;
+  readonly required?: boolean;
+  readonly defaultValue?: unknown;
+  readonly config?: Readonly<Record<string, unknown>>;
+  readonly fields?: readonly BetterCMSLayoutInput[];
+}
+`;
+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":
+    // A document field stores the SAME {format, value, html} envelope as richtext — the
+    // difference is the editor and the placement, not the wire shape. So it maps to the same
+    // generated type, and the `doc` rendition lands on `RichText` itself rather than here.
+    case "document":
+      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
+    // Both spellings are live (see ContentModelFieldType). Template- and Webflow-seeded
+    // models carry the camelCase one; until it was handled here it fell through to the
+    // exhaustiveness default, so generated types for every template-created collection
+    // typed this field as `unknown` instead of `string[]`.
+    case "multi-reference":
+    case "multiReference":
+      return "string[]";
+    // referenced entry ids
+    case "array": {
+      const itemType = field.config?.itemType ?? "text";
+      const inner = itemType === "number" ? "number" : "string";
+      return `${inner}[]`;
+    }
+    // ── Builder scalars ────────────────────────────────────────────────────────
+    // All string-shaped on the wire; each is value-validated on write (see
+    // src/lib/content/reference-validation.ts), so the generated type is the
+    // narrowest thing that is actually true of the stored value.
+    case "longtext":
+    case "slug":
+    case "email":
+    case "phone":
+    case "link":
+    case "color":
+      return "string";
+    case "json":
+      return "unknown";
+    case "component-ref":
+      return "BetterCMSComponentRef";
+    case "modular":
+      return "ReadonlyArray<{ readonly __id: string; readonly __type: string; readonly data: Record<string, unknown> }>";
+    case "sections": {
+      const config = field.config;
+      const unresolvedLegacy = config?.mode === "authored-v2" && Object.prototype.hasOwnProperty.call(config, "allowedSections") && config.legacyResolved !== true;
+      if (config?.mode === "authored-v2" && !unresolvedLegacy) {
+        return "ReadonlyArray<{ readonly __id: string; readonly __section: string; readonly __type: string; readonly data: Record<string, unknown> }>";
+      }
+      return "ReadonlyArray<BetterCMSBlock>";
+    }
+    case "location":
+      return "{ readonly lat: number; readonly lng: number; readonly label?: string }";
+    case "file":
+      return "BetterCMSImage";
+    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;
+    case "document":
+      return "richtext";
+    // 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 = `/**
+ * Binding attributes for a CMS-bound element. Spread onto the element that renders a
+ * field: \`<h1 {...bcmsField("title", "text")}>\`. Always emitted, on every build \u2014
+ * two inert \`data-*\` attributes are what makes the site editable in Live Preview.
+ */
+export function bcmsField(path: string, kind: string): Record<string, string> {
+  return { "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 on every build.
+${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;
+  /**
+   * Structured blocks \u2014 Body (\`document\`) fields only, and optional even there: derived at
+   * write time, so entries saved before it existed carry none until re-saved. No backfill.
+   * Block ids are stable within one document only, never a global key.
+   */
+  readonly doc?: { readonly version: 1; readonly blocks: readonly { readonly id: string; readonly type: string; readonly [k: string]: unknown }[] };
+};
+
+/** 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