koguma 0.4.0

package/src/config/define.ts

@@ -0,0 +1,157 @@
+/**
+ * contentType, group, defineConfig, Infer — the schema definition API.
+ */
+import { z } from 'zod/v4';
+import type { FieldBuilder, FieldMeta } from './field.ts';
+
+// ── Group ────────────────────────────────────────────────────────────
+
+export interface GroupConfig {
+  groupId: string;
+  name: string;
+  helpText?: string;
+  collapsed?: boolean;
+  fields: Record<string, FieldBuilder>;
+}
+
+export function group(opts: {
+  id: string;
+  name: string;
+  helpText?: string;
+  collapsed?: boolean;
+  fields: Record<string, FieldBuilder>;
+}): GroupConfig {
+  return {
+    groupId: opts.id,
+    name: opts.name,
+    helpText: opts.helpText,
+    collapsed: opts.collapsed,
+    fields: opts.fields
+  };
+}
+
+// ── ContentType ──────────────────────────────────────────────────────
+
+export interface ContentTypeConfig<S extends z.ZodType = z.ZodType> {
+  id: string;
+  name: string;
+  displayField: string;
+  singleton?: boolean;
+  /** The resolved Zod schema for z.infer */
+  schema: S;
+  /** Field metadata for the admin + schema generator */
+  fieldMeta: Record<string, FieldMeta>;
+  /** Group layout for the admin */
+  groups: GroupConfig[];
+  /** Flat fields (no groups) — for simple content types */
+  flatFields: Record<string, FieldBuilder>;
+}
+
+/**
+ * Define a content type.
+ *
+ * Fields can be defined directly (flat) or organized into groups:
+ *
+ * ```ts
+ * // Flat
+ * contentType("card", {
+ *   name: "Card",
+ *   displayField: "title",
+ *   fields: {
+ *     title: field.text("Title").required(),
+ *     body:  field.richText("Body"),
+ *   },
+ * });
+ *
+ * // Grouped
+ * contentType("page", {
+ *   name: "Page",
+ *   displayField: "title",
+ *   fields: [
+ *     group({ id: "hero", name: "1 · Hero", fields: { title: field.text("Title") } }),
+ *     group({ id: "about", name: "2 · About", fields: { heading: field.text("Heading") } }),
+ *   ],
+ * });
+ * ```
+ */
+export function contentType<
+  F extends Record<string, FieldBuilder> | GroupConfig[]
+>(opts: {
+  id: string;
+  name: string;
+  displayField: string;
+  singleton?: boolean;
+  fields: F;
+}): ContentTypeConfig {
+  // Collect all field builders (from groups or flat)
+  const allFields: Record<string, FieldBuilder> = {};
+  const groups: GroupConfig[] = [];
+  let flatFields: Record<string, FieldBuilder> = {};
+
+  if (Array.isArray(opts.fields)) {
+    // Grouped fields
+    for (const g of opts.fields) {
+      groups.push(g);
+      Object.assign(allFields, g.fields);
+    }
+  } else {
+    // Flat fields
+    flatFields = opts.fields as Record<string, FieldBuilder>;
+    Object.assign(allFields, flatFields);
+  }
+
+  // Build Zod object schema from all fields
+  const shape: Record<string, z.ZodType> = {};
+  const fieldMeta: Record<string, FieldMeta> = {};
+
+  for (const [key, builder] of Object.entries(allFields)) {
+    shape[key] = builder._schema;
+    fieldMeta[key] = builder._meta;
+  }
+
+  const schema = z.object(shape);
+
+  return {
+    id: opts.id,
+    name: opts.name,
+    displayField: opts.displayField,
+    singleton: opts.singleton,
+    schema: schema as z.ZodType,
+    fieldMeta,
+    groups,
+    flatFields
+  };
+}
+
+// ── defineConfig ─────────────────────────────────────────────────────
+
+export interface KogumaConfig {
+  siteName: string;
+  contentTypes: ContentTypeConfig[];
+  hooks?: {
+    beforeSave?: (
+      entry: Record<string, unknown>,
+      ctx: { contentType: string }
+    ) => Record<string, unknown> | Promise<Record<string, unknown>>;
+    afterSave?: (
+      entry: Record<string, unknown>,
+      ctx: { contentType: string }
+    ) => void | Promise<void>;
+  };
+}
+
+export function defineConfig(config: KogumaConfig): KogumaConfig {
+  return config;
+}
+
+// ── Infer ────────────────────────────────────────────────────────────
+
+/**
+ * Extract the TypeScript type from a content type definition.
+ *
+ * ```ts
+ * const page = contentType({ ... });
+ * type Page = Infer<typeof page>;
+ * ```
+ */
+export type Infer<T extends ContentTypeConfig> = z.infer<T['schema']>;

package/src/config/field.ts

@@ -0,0 +1,182 @@
+/**
+ * field.* builders — the user-facing API for defining content fields.
+ *
+ * Each method returns a FieldBuilder that wraps a Zod schema internally.
+ * The admin label is always the first argument for readability:
+ *
+ *   field.text("Page Title").required().max(100)
+ *   field.richText("Body Text")
+ *   field.image("Hero Photo")
+ *   field.refs("featureCard", "Highlights")
+ */
+import { z } from "zod/v4";
+import type { KogumaAsset, RichTextDocument, EntryReference } from "./types.ts";
+
+// ── Field metadata (extracted by the admin + schema generator) ──────
+
+export type FieldType =
+  | "text"
+  | "longText"
+  | "richText"
+  | "url"
+  | "image"
+  | "boolean"
+  | "number"
+  | "date"
+  | "select"
+  | "reference"
+  | "references";
+
+export interface FieldMeta {
+  label: string;
+  fieldType: FieldType;
+  required: boolean;
+  refContentType?: string;
+  options?: string[];
+}
+
+// ── FieldBuilder ────────────────────────────────────────────────────
+
+export class FieldBuilder<T extends z.ZodType = z.ZodType> {
+  /** @internal */
+  readonly _schema: T;
+  /** @internal */
+  readonly _meta: FieldMeta;
+
+  constructor(schema: T, meta: FieldMeta) {
+    this._schema = schema;
+    this._meta = meta;
+  }
+
+  /** Mark as required (fields are optional by default) */
+  required(): FieldBuilder<T> {
+    return new FieldBuilder(this._schema, { ...this._meta, required: true });
+  }
+
+  /** Set maximum length (text) or value (number) */
+  max(value: number): FieldBuilder<T> {
+    const s = this._schema;
+    if (s instanceof z.ZodString) {
+      return new FieldBuilder(s.max(value) as unknown as T, this._meta);
+    }
+    if (s instanceof z.ZodNumber) {
+      return new FieldBuilder(s.max(value) as unknown as T, this._meta);
+    }
+    return this;
+  }
+
+  /** Set minimum length (text) or value (number) */
+  min(value: number): FieldBuilder<T> {
+    const s = this._schema;
+    if (s instanceof z.ZodString) {
+      return new FieldBuilder(s.min(value) as unknown as T, this._meta);
+    }
+    if (s instanceof z.ZodNumber) {
+      return new FieldBuilder(s.min(value) as unknown as T, this._meta);
+    }
+    if (s instanceof z.ZodArray) {
+      return new FieldBuilder(s.min(value) as unknown as T, this._meta);
+    }
+    return this;
+  }
+
+  /** Set a default value */
+  default(value: z.infer<T>): FieldBuilder {
+    return new FieldBuilder((this._schema as z.ZodType).default(value as never), this._meta);
+  }
+}
+
+// ── Factory functions ──────────────────────────────────────────────
+
+export const field = {
+  /** Short text field */
+  text(label: string) {
+    return new FieldBuilder(
+      z.string().optional().describe(label),
+      { label, fieldType: "text", required: false },
+    );
+  },
+
+  /** Multi-line text field */
+  longText(label: string) {
+    return new FieldBuilder(
+      z.string().optional().describe(label),
+      { label, fieldType: "longText", required: false },
+    );
+  },
+
+  /** Rich text field (Tiptap JSON document) */
+  richText(label: string) {
+    return new FieldBuilder(
+      z.custom<RichTextDocument>().optional().describe(label),
+      { label, fieldType: "richText", required: false },
+    );
+  },
+
+  /** URL field with validation */
+  url(label: string) {
+    return new FieldBuilder(
+      z.string().url().optional().describe(label),
+      { label, fieldType: "url", required: false },
+    );
+  },
+
+  /** Image/media field (reference to R2 asset) */
+  image(label: string) {
+    return new FieldBuilder(
+      z.custom<KogumaAsset>().optional().describe(label),
+      { label, fieldType: "image", required: false },
+    );
+  },
+
+  /** Boolean toggle */
+  boolean(label: string) {
+    return new FieldBuilder(
+      z.boolean().optional().describe(label),
+      { label, fieldType: "boolean", required: false },
+    );
+  },
+
+  /** Numeric field */
+  number(label: string) {
+    return new FieldBuilder(
+      z.number().optional().describe(label),
+      { label, fieldType: "number", required: false },
+    );
+  },
+
+  /** Date field */
+  date(label: string) {
+    return new FieldBuilder(
+      z.string().datetime().optional().describe(label),
+      { label, fieldType: "date", required: false },
+    );
+  },
+
+  /** Dropdown select */
+  select(label: string, opts: { options: string[] }) {
+    const enumSchema = z.enum(opts.options as [string, ...string[]]).optional().describe(label);
+    return new FieldBuilder(enumSchema, {
+      label,
+      fieldType: "select",
+      required: false,
+      options: opts.options,
+    });
+  },
+
+  /** Single reference to another content type */
+  ref(contentType: string, label: string) {
+    return new FieldBuilder(
+      z.custom<EntryReference>().optional().describe(label),
+      { label, fieldType: "reference", required: false, refContentType: contentType },
+    );
+  },
+
+  /** Ordered array of references to another content type */
+  refs(contentType: string, label: string) {
+    return new FieldBuilder(
+      z.array(z.custom<EntryReference>()).optional().describe(label),
+      { label, fieldType: "references", required: false, refContentType: contentType },
+    );
+  },
+};

package/src/config/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Koguma — public API
+ *
+ * Everything the user needs comes from this single import:
+ *
+ *   import { defineConfig, contentType, group, field, type Infer } from "koguma";
+ */
+
+// Config helpers
+export { defineConfig, contentType, group } from './define.ts';
+export type {
+  Infer,
+  KogumaConfig,
+  ContentTypeConfig,
+  GroupConfig
+} from './define.ts';
+
+// Field builders
+export { field } from './field.ts';
+export type { FieldBuilder, FieldType, FieldMeta } from './field.ts';
+
+// Runtime types
+export type { KogumaAsset, RichTextDocument, EntryReference } from './types.ts';
+
+// Meta registry (for dev tools like the Schema Builder)
+export { fieldRegistry, fieldSuggestions } from './meta.ts';
+export type { FieldTypeMeta, FieldSuggestion } from './meta.ts';

package/src/config/meta.ts

@@ -0,0 +1,189 @@
+/**
+ * koguma/meta — field type registry for tooling.
+ *
+ * This module exports metadata about every field type Koguma supports.
+ * The Schema Builder (and any future dev tools) reads this registry
+ * instead of hardcoding field type lists.
+ *
+ * Zero breaking changes — purely additive. Infer<T> and all existing
+ * APIs are untouched.
+ */
+import type { FieldType } from './field.ts';
+
+// ── Field Type Metadata ─────────────────────────────────────────────
+
+export interface FieldTypeMeta {
+  type: FieldType;
+  label: string;
+  icon: string;
+  description: string;
+  category: 'basics' | 'data' | 'relations';
+  args: 'label' | 'label+options' | 'ref+label';
+  modifiers: ('required' | 'min' | 'max' | 'default')[];
+}
+
+export const fieldRegistry: FieldTypeMeta[] = [
+  // Basics
+  {
+    type: 'text',
+    label: 'Text',
+    icon: 'Aa',
+    category: 'basics',
+    description: 'Short text',
+    args: 'label',
+    modifiers: ['required', 'min', 'max', 'default']
+  },
+  {
+    type: 'longText',
+    label: 'Long Text',
+    icon: '¶',
+    category: 'basics',
+    description: 'Multi-line text',
+    args: 'label',
+    modifiers: ['required', 'min', 'max', 'default']
+  },
+  {
+    type: 'richText',
+    label: 'Rich Text',
+    icon: '📝',
+    category: 'basics',
+    description: 'Rich text editor',
+    args: 'label',
+    modifiers: ['required']
+  },
+  // Data
+  {
+    type: 'url',
+    label: 'URL',
+    icon: '🔗',
+    category: 'data',
+    description: 'URL with validation',
+    args: 'label',
+    modifiers: ['required']
+  },
+  {
+    type: 'boolean',
+    label: 'Boolean',
+    icon: '☑',
+    category: 'data',
+    description: 'True/false toggle',
+    args: 'label',
+    modifiers: ['required', 'default']
+  },
+  {
+    type: 'number',
+    label: 'Number',
+    icon: '#',
+    category: 'data',
+    description: 'Numeric value',
+    args: 'label',
+    modifiers: ['required', 'min', 'max', 'default']
+  },
+  {
+    type: 'date',
+    label: 'Date',
+    icon: '📅',
+    category: 'data',
+    description: 'Date picker',
+    args: 'label',
+    modifiers: ['required']
+  },
+  {
+    type: 'select',
+    label: 'Select',
+    icon: '▾',
+    category: 'data',
+    description: 'Dropdown options',
+    args: 'label+options',
+    modifiers: ['required', 'default']
+  },
+  // Relations
+  {
+    type: 'image',
+    label: 'Image',
+    icon: '🖼️',
+    category: 'relations',
+    description: 'Image from R2',
+    args: 'label',
+    modifiers: ['required']
+  },
+  {
+    type: 'reference',
+    label: 'Reference',
+    icon: '→',
+    category: 'relations',
+    description: 'Link to entry',
+    args: 'ref+label',
+    modifiers: ['required']
+  },
+  {
+    type: 'references',
+    label: 'References',
+    icon: '⇉',
+    category: 'relations',
+    description: 'List of links',
+    args: 'ref+label',
+    modifiers: ['required', 'min']
+  }
+];
+
+// ── Intent-based field suggestions ───────────────────────────────────
+
+export interface FieldSuggestion {
+  type: FieldType;
+  modifiers?: string;
+}
+
+/**
+ * Maps common label keywords to suggested field types.
+ * The builder uses this to auto-select the type dropdown when
+ * the user types a label.
+ */
+export const fieldSuggestions: Record<string, FieldSuggestion> = {
+  // Text fields
+  title: { type: 'text', modifiers: 'required' },
+  name: { type: 'text', modifiers: 'required' },
+  slug: { type: 'text', modifiers: 'required' },
+  heading: { type: 'text' },
+  tagline: { type: 'text' },
+  // Long text
+  description: { type: 'longText' },
+  bio: { type: 'longText' },
+  notes: { type: 'longText' },
+  excerpt: { type: 'longText' },
+  // Rich text
+  body: { type: 'richText' },
+  content: { type: 'richText' },
+  story: { type: 'richText' },
+  // URL
+  email: { type: 'url' },
+  website: { type: 'url' },
+  url: { type: 'url' },
+  link: { type: 'url' },
+  // Image
+  photo: { type: 'image' },
+  image: { type: 'image' },
+  avatar: { type: 'image' },
+  cover: { type: 'image' },
+  logo: { type: 'image' },
+  poster: { type: 'image' },
+  // Boolean
+  published: { type: 'boolean', modifiers: 'default(false)' },
+  active: { type: 'boolean', modifiers: 'default(true)' },
+  featured: { type: 'boolean', modifiers: 'default(false)' },
+  // Number
+  price: { type: 'number', modifiers: 'min(0)' },
+  weight: { type: 'number' },
+  count: { type: 'number' },
+  order: { type: 'number' },
+  // Date
+  date: { type: 'date' },
+  birthday: { type: 'date' },
+  // Select
+  category: { type: 'select' },
+  status: { type: 'select' },
+  role: { type: 'select' },
+  type: { type: 'select' },
+  genre: { type: 'select' },
+  format: { type: 'select' }
+};

package/src/config/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Core CMS types used across Koguma.
+ * These are the runtime types for assets and rich text — not Zod schemas.
+ */
+
+/** A media asset stored in R2 */
+export interface KogumaAsset {
+  id: string;
+  url: string;
+  title: string;
+  contentType: string;
+  width?: number;
+  height?: number;
+}
+
+/** A Tiptap/ProseMirror-compatible rich text document */
+export interface RichTextDocument {
+  type: "doc";
+  content: RichTextNode[];
+}
+
+export interface RichTextNode {
+  type: string;
+  content?: RichTextNode[];
+  text?: string;
+  marks?: { type: string; attrs?: Record<string, unknown> }[];
+  attrs?: Record<string, unknown>;
+}
+
+/** Reference to another entry */
+export interface EntryReference<T = Record<string, unknown>> {
+  id: string;
+  contentType: string;
+  fields?: T;
+}