@setzkasten-cms/core 0.4.2

package/src/index.ts

@@ -0,0 +1,85 @@
+// ---------------------------------------------------------------------------
+// @setzkasten-cms/core – Public API
+// ---------------------------------------------------------------------------
+
+// Schema
+export { defineConfig, defineSection, defineCollection } from './schema/define-config'
+export type {
+  SetzKastenConfig,
+  SectionDefinition,
+  ProductDefinition,
+  CollectionDefinition,
+  StorageConfig,
+  AuthConfig,
+  ThemeConfig,
+  IconsConfig,
+} from './schema/define-config'
+
+// Fields
+export { f } from './fields/factories'
+export type {
+  FieldType,
+  FieldPath,
+  FieldDefinition,
+  FieldRecord,
+  InferFieldValue,
+  InferSchemaValues,
+  AnyFieldDef,
+  TextFieldDef,
+  NumberFieldDef,
+  BooleanFieldDef,
+  SelectFieldDef,
+  IconFieldDef,
+  ImageFieldDef,
+  ImageValue,
+  ArrayFieldDef,
+  ObjectFieldDef,
+  ColorFieldDef,
+  OverrideFieldDef,
+  SelectOption,
+} from './fields/field-definition'
+
+// Validation
+export { fieldToZod, schemaToZod } from './validation/schema-to-zod'
+
+// Serialization
+export { serializeEntry, deserializeEntry } from './serialization/serializer'
+export type { FieldSerializer, SerializerRegistry } from './serialization/serializer'
+export { jsonSerializerRegistry } from './serialization/json-serializer'
+
+// Commands
+export { createCommandHistory } from './commands/command'
+export type { Command, CommandHistory } from './commands/command'
+
+// Events
+export { createEventBus } from './events/content-event-bus'
+export type { ContentEvent, ContentEventType, ContentEventBus, Unsubscribe } from './events/content-event-bus'
+
+// Errors
+export {
+  ok,
+  err,
+  validationError,
+  conflictError,
+  rateLimitError,
+  authError,
+  networkError,
+  notFoundError,
+  serializationError,
+} from './errors/errors'
+export type {
+  Result,
+  SetzKastenError,
+  ValidationError,
+  ConflictError,
+  RateLimitError,
+  AuthError,
+  NetworkError,
+  NotFoundError,
+  SerializationError,
+} from './errors/errors'
+
+// Ports (interfaces only)
+export type { ContentRepository, EntryData, Asset, CommitResult, TreeNode, EntryListItem } from './ports/content-repository'
+export type { AuthProvider, AuthUser, AuthSession } from './ports/auth-provider'
+export type { AssetStore, AssetMetadata } from './ports/asset-store'

package/src/ports/asset-store.ts

@@ -0,0 +1,36 @@
+import type { Result } from '../errors/errors'
+
+export interface AssetMetadata {
+  readonly path: string
+  readonly size: number
+  readonly mimeType: string
+  readonly width?: number
+  readonly height?: number
+}
+
+/**
+ * Asset store port – abstracts image/file storage.
+ * Default implementation uses GitHub Contents API.
+ * Could be swapped for S3, Cloudinary, etc.
+ */
+export interface AssetStore {
+  /** Upload an asset, preserving the original filename */
+  upload(
+    directory: string,
+    filename: string,
+    content: Uint8Array,
+    mimeType: string,
+  ): Promise<Result<AssetMetadata>>
+
+  /** Delete an asset */
+  delete(path: string): Promise<Result<void>>
+
+  /** List assets in a directory */
+  list(directory: string): Promise<Result<AssetMetadata[]>>
+
+  /** Get a public URL for an asset (for the deployed website) */
+  getUrl(path: string): string
+
+  /** Get a preview URL that works immediately (e.g. raw GitHub URL) */
+  getPreviewUrl?(path: string): string
+}

package/src/ports/auth-provider.ts

@@ -0,0 +1,32 @@
+import type { Result } from '../errors/errors'
+
+export interface AuthUser {
+  readonly id: string
+  readonly email: string
+  readonly name?: string
+  readonly avatarUrl?: string
+  readonly provider: 'github' | 'google' | 'email'
+}
+
+export interface AuthSession {
+  readonly user: AuthUser
+  readonly expiresAt: number
+}
+
+/**
+ * Auth provider port – abstracts authentication.
+ * Determines WHO can access the CMS, separate from HOW content is committed.
+ */
+export interface AuthProvider {
+  /** Get current session (null if not authenticated) */
+  getSession(): Promise<Result<AuthSession | null>>
+
+  /** Get the OAuth redirect URL for login */
+  getLoginUrl(provider: 'github' | 'google' | 'email'): string
+
+  /** Exchange auth callback for session */
+  handleCallback(code: string, provider: string): Promise<Result<AuthSession>>
+
+  /** End session */
+  logout(): Promise<void>
+}

package/src/ports/content-repository.ts

@@ -0,0 +1,59 @@
+import type { Result } from '../errors/errors'
+
+// ---------------------------------------------------------------------------
+// Content Repository Port – the core abstraction over storage
+// ---------------------------------------------------------------------------
+
+export interface EntryData {
+  readonly content: Record<string, unknown>
+  readonly sha?: string // for conflict detection (GitHub file SHA)
+}
+
+export interface Asset {
+  readonly path: string
+  readonly content: Uint8Array
+  readonly mimeType: string
+}
+
+export interface CommitResult {
+  readonly sha: string
+  readonly message: string
+  readonly url?: string
+}
+
+export interface TreeNode {
+  readonly path: string
+  readonly type: 'file' | 'dir'
+  readonly sha?: string
+}
+
+export interface EntryListItem {
+  readonly slug: string
+  readonly name: string
+}
+
+/**
+ * Repository pattern: abstracts content storage.
+ * Implemented by github-adapter (and potentially local-filesystem, GitLab, etc.)
+ */
+export interface ContentRepository {
+  /** List all entries in a collection/singleton directory */
+  listEntries(collection: string): Promise<Result<EntryListItem[]>>
+
+  /** Read a single entry's content */
+  getEntry(collection: string, slug: string): Promise<Result<EntryData>>
+
+  /** Save an entry with optional assets (images). Creates a single atomic commit. */
+  saveEntry(
+    collection: string,
+    slug: string,
+    data: EntryData,
+    assets?: Asset[],
+  ): Promise<Result<CommitResult>>
+
+  /** Delete an entry */
+  deleteEntry(collection: string, slug: string): Promise<Result<CommitResult>>
+
+  /** Get the full repository tree (for navigation) */
+  getTree(ref?: string): Promise<Result<TreeNode[]>>
+}

package/src/schema/define-config.ts

@@ -0,0 +1,96 @@
+import type { FieldRecord } from '../fields/field-definition'
+
+// ---------------------------------------------------------------------------
+// Section definition
+// ---------------------------------------------------------------------------
+
+export interface SectionDefinition<TFields extends FieldRecord = FieldRecord> {
+  readonly label: string
+  readonly icon?: string
+  readonly fields: TFields
+}
+
+export function defineSection<TFields extends FieldRecord>(options: {
+  label: string
+  icon?: string
+  fields: TFields
+}): SectionDefinition<TFields> {
+  return Object.freeze({
+    label: options.label,
+    icon: options.icon,
+    fields: options.fields,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Product definition
+// ---------------------------------------------------------------------------
+
+export interface ProductDefinition {
+  readonly label: string
+  readonly sections: Record<string, SectionDefinition>
+}
+
+// ---------------------------------------------------------------------------
+// Collection definition
+// ---------------------------------------------------------------------------
+
+export interface CollectionDefinition<TFields extends FieldRecord = FieldRecord> {
+  readonly label: string
+  readonly path: string
+  readonly slugField: string
+  readonly fields: TFields
+}
+
+export function defineCollection<TFields extends FieldRecord>(options: {
+  label: string
+  path: string
+  slugField: string
+  fields: TFields
+}): CollectionDefinition<TFields> {
+  return Object.freeze({
+    label: options.label,
+    path: options.path,
+    slugField: options.slugField,
+    fields: options.fields,
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Config definition
+// ---------------------------------------------------------------------------
+
+export interface StorageConfig {
+  readonly kind: 'github' | 'local'
+  readonly repo?: string
+  readonly branch?: string
+}
+
+export interface AuthConfig {
+  readonly providers: readonly ('github' | 'google' | 'email')[]
+  readonly allowedEmails?: readonly string[]
+}
+
+export interface ThemeConfig {
+  readonly primaryColor: string
+  readonly logo?: string
+  readonly brandName?: string
+}
+
+export interface IconsConfig {
+  /** Icon sets to enable. Default: ['lucide'] */
+  readonly sets: readonly string[]
+}
+
+export interface SetzKastenConfig {
+  readonly storage: StorageConfig
+  readonly auth: AuthConfig
+  readonly theme?: ThemeConfig
+  readonly icons?: IconsConfig
+  readonly products: Record<string, ProductDefinition>
+  readonly collections?: Record<string, CollectionDefinition>
+}
+
+export function defineConfig(config: SetzKastenConfig): SetzKastenConfig {
+  return Object.freeze(config)
+}

package/src/serialization/json-serializer.ts

@@ -0,0 +1,87 @@
+import type {
+  ArrayFieldDef,
+  FieldRecord,
+  ObjectFieldDef,
+  OverrideFieldDef,
+} from '../fields/field-definition'
+import type { FieldSerializer, SerializerRegistry } from './serializer'
+
+/**
+ * JSON serializers – backward-compatible with Keystatic's JSON format.
+ *
+ * Most fields serialize as-is (text → string, number → number, etc.)
+ * Complex fields (array, object, override) recurse into their children.
+ */
+
+const textSerializer: FieldSerializer<string, string> = {
+  serialize: (value) => value,
+  deserialize: (raw) => (typeof raw === 'string' ? raw : String(raw ?? '')),
+}
+
+const numberSerializer: FieldSerializer<number, number> = {
+  serialize: (value) => value,
+  deserialize: (raw) => (typeof raw === 'number' ? raw : Number(raw ?? 0)),
+}
+
+const booleanSerializer: FieldSerializer<boolean, boolean> = {
+  serialize: (value) => value,
+  deserialize: (raw) => Boolean(raw),
+}
+
+const selectSerializer: FieldSerializer<string, string> = {
+  serialize: (value) => value,
+  deserialize: (raw) => String(raw ?? ''),
+}
+
+const imageSerializer: FieldSerializer = {
+  serialize: (value) => {
+    if (typeof value === 'string') return value
+    if (value && typeof value === 'object' && 'path' in value) {
+      return (value as { path: string }).path
+    }
+    return ''
+  },
+  deserialize: (raw) => {
+    // Keystatic stores image paths as plain strings
+    if (typeof raw === 'string') return { path: raw, alt: '' }
+    if (raw && typeof raw === 'object' && 'path' in raw) return raw
+    return { path: '', alt: '' }
+  },
+}
+
+const colorSerializer: FieldSerializer<string, string> = {
+  serialize: (value) => value,
+  deserialize: (raw) => String(raw ?? '#000000'),
+}
+
+/**
+ * Default JSON serializer registry.
+ * Compatible with Keystatic's JSON output format.
+ */
+export const jsonSerializerRegistry: SerializerRegistry = {
+  text: textSerializer,
+  number: numberSerializer,
+  boolean: booleanSerializer,
+  select: selectSerializer,
+  image: imageSerializer,
+  color: colorSerializer,
+  // array, object, override are handled recursively by serializeEntry/deserializeEntry
+  array: {
+    serialize: (value) => (Array.isArray(value) ? value : []),
+    deserialize: (raw) => (Array.isArray(raw) ? raw : []),
+  },
+  object: {
+    serialize: (value) => (value && typeof value === 'object' ? value : {}),
+    deserialize: (raw) => (raw && typeof raw === 'object' ? raw : {}),
+  },
+  override: {
+    serialize: (value) => {
+      if (value && typeof value === 'object') return value
+      return { active: false }
+    },
+    deserialize: (raw) => {
+      if (raw && typeof raw === 'object') return raw
+      return { active: false }
+    },
+  },
+}

package/src/serialization/serializer.ts

@@ -0,0 +1,65 @@
+import type { FieldDefinition, FieldRecord } from '../fields/field-definition'
+
+/**
+ * Strategy interface for field serialization.
+ * Each field type defines how it converts between editor values and stored format.
+ */
+export interface FieldSerializer<TValue = unknown, TSerialized = unknown> {
+  serialize(value: TValue): TSerialized
+  deserialize(raw: TSerialized): TValue
+}
+
+/**
+ * Registry of serializers keyed by field type.
+ */
+export type SerializerRegistry = Record<string, FieldSerializer>
+
+/**
+ * Serialize an entire schema's values to a flat JSON object.
+ */
+export function serializeEntry(
+  fields: FieldRecord,
+  values: Record<string, unknown>,
+  registry: SerializerRegistry,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+
+  for (const [key, field] of Object.entries(fields)) {
+    const serializer = registry[field.type]
+    const value = values[key]
+
+    if (serializer && value !== undefined) {
+      result[key] = serializer.serialize(value)
+    } else if (value !== undefined) {
+      result[key] = value
+    }
+  }
+
+  return result
+}
+
+/**
+ * Deserialize a stored JSON object back to editor values.
+ */
+export function deserializeEntry(
+  fields: FieldRecord,
+  raw: Record<string, unknown>,
+  registry: SerializerRegistry,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+
+  for (const [key, field] of Object.entries(fields)) {
+    const serializer = registry[field.type]
+    const rawValue = raw[key]
+
+    if (serializer && rawValue !== undefined) {
+      result[key] = serializer.deserialize(rawValue)
+    } else if (rawValue !== undefined) {
+      result[key] = rawValue
+    } else if (field.defaultValue !== undefined) {
+      result[key] = field.defaultValue
+    }
+  }
+
+  return result
+}

package/src/testing/index.ts

@@ -0,0 +1,72 @@
+/**
+ * @setzkasten-cms/core/testing – Test utilities for other packages
+ */
+
+import { f } from '../fields/factories'
+import { defineConfig, defineSection } from '../schema/define-config'
+
+/**
+ * Creates a minimal test config for use in tests.
+ */
+export function createTestConfig() {
+  return defineConfig({
+    storage: { kind: 'local' },
+    auth: { providers: ['email'] },
+    products: {
+      test: {
+        label: 'Test Product',
+        sections: {
+          hero: defineSection({
+            label: 'Hero',
+            fields: {
+              heading: f.text({ label: 'Heading', required: true }),
+              subtitle: f.text({ label: 'Subtitle', multiline: true }),
+              badge: f.text({ label: 'Badge' }),
+            },
+          }),
+          benefits: defineSection({
+            label: 'Benefits',
+            fields: {
+              items: f.array(
+                f.object(
+                  {
+                    title: f.text({ label: 'Title' }),
+                    description: f.text({ label: 'Description', multiline: true }),
+                    icon: f.select({
+                      label: 'Icon',
+                      options: [
+                        { label: 'Check', value: 'check' },
+                        { label: 'Star', value: 'star' },
+                      ],
+                    }),
+                  },
+                  { label: 'Benefit' },
+                ),
+                { label: 'Benefits', minItems: 1 },
+              ),
+            },
+          }),
+        },
+      },
+    },
+  })
+}
+
+/**
+ * Creates sample content data matching the test config schema.
+ */
+export function createTestContent() {
+  return {
+    hero: {
+      heading: 'Test Heading',
+      subtitle: 'Test Subtitle',
+      badge: 'New',
+    },
+    benefits: {
+      items: [
+        { title: 'Benefit 1', description: 'Description 1', icon: 'check' },
+        { title: 'Benefit 2', description: 'Description 2', icon: 'star' },
+      ],
+    },
+  }
+}

package/src/validation/schema-to-zod.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+import { f } from '../fields/factories'
+import { fieldToZod, schemaToZod } from './schema-to-zod'
+
+describe('Schema to Zod', () => {
+  describe('fieldToZod()', () => {
+    it('validates required text fields', () => {
+      const field = f.text({ label: 'Title', required: true })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse('Hello').success).toBe(true)
+      expect(schema.safeParse('').success).toBe(false)
+    })
+
+    it('validates text maxLength', () => {
+      const field = f.text({ label: 'Short', maxLength: 5 })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse('Hi').success).toBe(true)
+      expect(schema.safeParse('Too long text').success).toBe(false)
+    })
+
+    it('validates text pattern', () => {
+      const field = f.text({ label: 'Email', pattern: /^.+@.+\..+$/ })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse('test@example.com').success).toBe(true)
+      expect(schema.safeParse('not-an-email').success).toBe(false)
+    })
+
+    it('validates number min/max', () => {
+      const field = f.number({ label: 'Rating', min: 1, max: 5 })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse(3).success).toBe(true)
+      expect(schema.safeParse(0).success).toBe(false)
+      expect(schema.safeParse(6).success).toBe(false)
+    })
+
+    it('validates boolean', () => {
+      const field = f.boolean({ label: 'Active' })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse(true).success).toBe(true)
+      expect(schema.safeParse(false).success).toBe(true)
+      expect(schema.safeParse('yes').success).toBe(false)
+    })
+
+    it('validates select options', () => {
+      const field = f.select({
+        label: 'Style',
+        options: [
+          { label: 'Primary', value: 'primary' },
+          { label: 'Secondary', value: 'secondary' },
+        ],
+      })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse('primary').success).toBe(true)
+      expect(schema.safeParse('tertiary').success).toBe(false)
+    })
+
+    it('validates color hex format', () => {
+      const field = f.color({ label: 'Color' })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse('#a2c617').success).toBe(true)
+      expect(schema.safeParse('#fff').success).toBe(false)
+      expect(schema.safeParse('red').success).toBe(false)
+    })
+
+    it('validates arrays with min/max items', () => {
+      const field = f.array(f.text({ label: 'Tag' }), {
+        label: 'Tags',
+        minItems: 1,
+        maxItems: 3,
+      })
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse(['a']).success).toBe(true)
+      expect(schema.safeParse(['a', 'b', 'c']).success).toBe(true)
+      expect(schema.safeParse([]).success).toBe(false)
+      expect(schema.safeParse(['a', 'b', 'c', 'd']).success).toBe(false)
+    })
+
+    it('validates nested objects', () => {
+      const field = f.object(
+        {
+          name: f.text({ label: 'Name', required: true }),
+          age: f.number({ label: 'Age', min: 0 }),
+        },
+        { label: 'Person' },
+      )
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse({ name: 'Alice', age: 30 }).success).toBe(true)
+      expect(schema.safeParse({ name: '', age: 30 }).success).toBe(false)
+    })
+
+    it('validates override fields', () => {
+      const field = f.override(
+        {
+          heading: f.text({ label: 'Heading' }),
+        },
+        { label: 'Override' },
+      )
+      const schema = fieldToZod(field)
+
+      expect(schema.safeParse({ active: true, heading: 'Test' }).success).toBe(true)
+      expect(schema.safeParse({ active: false }).success).toBe(true)
+      expect(schema.safeParse({}).success).toBe(false) // missing active
+    })
+  })
+
+  describe('schemaToZod()', () => {
+    it('converts a full schema to Zod', () => {
+      const fields = {
+        title: f.text({ label: 'Title', required: true }),
+        description: f.text({ label: 'Description', multiline: true }),
+        rating: f.number({ label: 'Rating', min: 1, max: 5 }),
+        published: f.boolean({ label: 'Published' }),
+      }
+
+      const schema = schemaToZod(fields)
+
+      const valid = { title: 'Hello', description: 'World', rating: 3, published: true }
+      expect(schema.safeParse(valid).success).toBe(true)
+
+      const invalid = { title: '', rating: 3, published: true }
+      expect(schema.safeParse(invalid).success).toBe(false)
+    })
+  })
+})