kilo-cms 0.1.0

package/src/ai-writer.ts

@@ -0,0 +1,84 @@
+import 'server-only'
+
+import { getAiProviderKey } from './ai-config'
+import type { AiAction, AiProvider } from './ai-types'
+
+export type AiWriteInput = { action: AiAction; prompt?: string; selection?: string; documentText?: string }
+export type AiWriteResult = { state: 'complete'; text: string } | { state: 'pending'; taskId: string } | { state: 'error'; error: string }
+
+const models = { deepseek: 'deepseek-v4-flash', openai: 'gpt-5', anthropic: 'claude-sonnet-4-6' } as const
+const system = 'You are an expert CMS writing assistant. Return only the requested final prose as plain text. Do not use Markdown, headings made from symbols, preambles, explanations, or quotation marks around the result. Preserve the language of the source text unless the user asks otherwise.'
+
+function writingPrompt({ action, prompt, selection, documentText }: AiWriteInput) {
+  const source = selection?.trim() || documentText?.trim() || ''
+  if (action === 'prompt') return selection?.trim()
+    ? `${system}\n\nSelected text:\n${selection}\n\nUser request: ${prompt}\n\nReturn only the replacement text for the selection.`
+    : `${system}\n\nDocument context:\n${documentText || '(empty document)'}\n\nUser request: ${prompt}\n\nWrite content that satisfies the request.`
+  if (action === 'continue') return `${system}\n\nContinue this document naturally from where it ends. Return only the new continuation, without repeating any existing text:\n\n${documentText || '(empty document)'}`
+  if (action === 'improve') return `${system}\n\nImprove and rewrite this selected text for clarity, flow, and impact. Keep its meaning and approximate length unless a rewrite clearly benefits from changing it. Return only the replacement text:\n\n${source}`
+  return `${system}\n\nSummarize this selected text concisely while retaining its essential points. Return only the summary:\n\n${source}`
+}
+
+async function responseJson(response: Response) {
+  const body = await response.text()
+  let data: unknown = null
+  try { data = body ? JSON.parse(body) : null } catch {}
+  if (!response.ok) {
+    const message = typeof data === 'object' && data && 'error' in data ? JSON.stringify((data as { error: unknown }).error) : body
+    throw new Error(message || `Provider request failed (${response.status}).`)
+  }
+  return data as Record<string, unknown>
+}
+
+function readOpenAiText(data: Record<string, unknown>) {
+  if (typeof data.output_text === 'string' && data.output_text.trim()) return data.output_text.trim()
+  const output = Array.isArray(data.output) ? data.output : []
+  const text = output.flatMap((item) => typeof item === 'object' && item && 'content' in item && Array.isArray(item.content) ? item.content : []).map((part) => typeof part === 'object' && part && 'text' in part && typeof part.text === 'string' ? part.text : '').join('').trim()
+  if (!text) throw new Error('OpenAI returned no text.')
+  return text
+}
+
+async function directWrite(provider: Exclude<AiProvider, 'manus'>, prompt: string) {
+  const key = await getAiProviderKey(provider)
+  if (provider === 'deepseek') {
+    const response = await fetch('https://api.deepseek.com/chat/completions', { method: 'POST', signal: AbortSignal.timeout(60_000), headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: models.deepseek, messages: [{ role: 'system', content: system }, { role: 'user', content: prompt }], temperature: 0.7, max_tokens: 1800 }) })
+    const data = await responseJson(response)
+    const text = Array.isArray(data.choices) ? (data.choices[0] as { message?: { content?: string } } | undefined)?.message?.content : undefined
+    if (!text?.trim()) throw new Error('DeepSeek returned no text.')
+    return text.trim()
+  }
+  if (provider === 'openai') {
+    const response = await fetch('https://api.openai.com/v1/responses', { method: 'POST', signal: AbortSignal.timeout(60_000), headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ model: models.openai, input: prompt }) })
+    return readOpenAiText(await responseJson(response))
+  }
+  const response = await fetch('https://api.anthropic.com/v1/messages', { method: 'POST', signal: AbortSignal.timeout(60_000), headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01', 'Content-Type': 'application/json' }, body: JSON.stringify({ model: models.anthropic, max_tokens: 1800, system, messages: [{ role: 'user', content: prompt }] }) })
+  const data = await responseJson(response)
+  const text = Array.isArray(data.content) ? data.content.filter((part): part is { type: string; text: string } => typeof part === 'object' && part !== null && 'type' in part && 'text' in part && (part as { type: unknown }).type === 'text' && typeof (part as { text: unknown }).text === 'string').map((part) => part.text).join('').trim() : ''
+  if (!text) throw new Error('Anthropic returned no text.')
+  return text
+}
+
+export async function startAiWrite(provider: AiProvider, input: AiWriteInput): Promise<AiWriteResult> {
+  const prompt = writingPrompt(input)
+  if (provider !== 'manus') return { state: 'complete', text: await directWrite(provider, prompt) }
+  const key = await getAiProviderKey('manus')
+  const response = await fetch('https://api.manus.ai/v2/task.create', { method: 'POST', signal: AbortSignal.timeout(30_000), headers: { 'x-manus-api-key': key, 'Content-Type': 'application/json' }, body: JSON.stringify({ message: { content: prompt }, interactive_mode: false, hide_in_task_list: true, share_visibility: 'private', agent_profile: 'lite', structured_output_schema: { type: 'object', properties: { content: { type: 'string' } }, required: ['content'], additionalProperties: false } }) })
+  const data = await responseJson(response)
+  if (!data.ok || typeof data.task_id !== 'string') throw new Error('Manus could not start the writing task.')
+  return { state: 'pending', taskId: data.task_id }
+}
+
+export async function pollManusWrite(taskId: string): Promise<AiWriteResult> {
+  const key = await getAiProviderKey('manus')
+  const response = await fetch(`https://api.manus.ai/v2/task.listMessages?task_id=${encodeURIComponent(taskId)}&order=desc&limit=50`, { headers: { 'x-manus-api-key': key }, signal: AbortSignal.timeout(30_000) })
+  const data = await responseJson(response)
+  const messages = Array.isArray(data.messages) ? data.messages as Array<Record<string, unknown>> : []
+  const structured = messages.find((message) => message.type === 'structured_output_result')?.structured_output_result as { success?: boolean; value?: { content?: string }; error?: string | null } | undefined
+  if (structured) return structured.success && structured.value?.content?.trim() ? { state: 'complete', text: structured.value.content.trim() } : { state: 'error', error: structured.error || 'Manus could not produce a usable result.' }
+  const error = messages.find((message) => message.type === 'error_message')?.error_message as { content?: string } | undefined
+  if (error?.content) return { state: 'error', error: error.content }
+  const status = messages.find((message) => message.type === 'status_update')?.status_update as { agent_status?: string; status_detail?: { waiting_description?: string } } | undefined
+  if (status?.agent_status === 'waiting') return { state: 'error', error: status.status_detail?.waiting_description || 'Manus needs additional input. Try a more specific request.' }
+  if (status?.agent_status === 'error') return { state: 'error', error: 'Manus task failed.' }
+  return { state: 'pending', taskId }
+}

package/src/api-tokens.ts

@@ -0,0 +1,25 @@
+import 'server-only'
+
+import { randomBytes, createHash } from 'node:crypto'
+import { eq } from 'drizzle-orm'
+import { db } from './db'
+import { apiTokens } from './schema'
+
+export function hashToken(raw: string) {
+  return createHash('sha256').update(raw).digest('hex')
+}
+
+export function generateToken() {
+  const raw = `sk_${randomBytes(32).toString('base64url')}`
+  return { raw, hash: hashToken(raw), prefix: raw.slice(0, 10) }
+}
+
+export async function requireApiToken(request: Request) {
+  const header = request.headers.get('authorization') ?? ''
+  const match = /^Bearer\s+(.+)$/i.exec(header)
+  if (!match) return null
+  const [token] = await db.select().from(apiTokens).where(eq(apiTokens.tokenHash, hashToken(match[1]))).limit(1)
+  if (!token) return null
+  db.update(apiTokens).set({ lastUsedAt: new Date() }).where(eq(apiTokens.id, token.id)).catch(() => {})
+  return token
+}

package/src/auth-client.ts

@@ -0,0 +1,5 @@
+'use client'
+
+import { createAuthClient } from 'better-auth/react'
+
+export const authClient = createAuthClient({ baseURL: process.env.NEXT_PUBLIC_SITE_URL })

package/src/auth.ts

@@ -0,0 +1,33 @@
+import { betterAuth } from 'better-auth/minimal'
+import { drizzleAdapter } from '@better-auth/drizzle-adapter'
+import { schema } from './schema'
+import { __setAuth } from './db'
+
+export type KiloAuthConfig = {
+  /** The host's own drizzle instance — same one passed to `defineKiloConfig({ db })`. */
+  db: unknown
+  secret: string
+  baseURL: string
+  trustedOrigins?: string[]
+}
+
+/** Config-factory, same shape as calling `betterAuth({...})` directly — the host calls this
+ *  once (see apps/site/src/lib/auth.ts for the reference host wiring) instead of this package
+ *  hardcoding one app's secrets/URL. Only kilo-cms's OWN auth tables (user/session/account/
+ *  verification) are passed to the adapter; the host's own content tables are irrelevant to
+ *  better-auth and never need to be threaded through here. */
+export function createKiloAuth(config: KiloAuthConfig) {
+  const instance = betterAuth({
+    database: drizzleAdapter(config.db as never, { provider: 'pg', schema }),
+    secret: config.secret,
+    baseURL: config.baseURL,
+    trustedOrigins: config.trustedOrigins ?? [config.baseURL],
+    emailAndPassword: { enabled: true, disableSignUp: false, requireEmailVerification: false },
+    disabledPaths: ['/sign-up/email'],
+    user: { additionalFields: { role: { type: 'string', defaultValue: 'editor', input: false } } },
+  })
+  // permissions.ts (and anything else inside the package doing session lookups) reads `auth`
+  // from ./db's lazy proxy rather than assuming a global instance — this is what feeds it.
+  __setAuth(instance)
+  return instance
+}

package/src/calendar-grid.ts

@@ -0,0 +1,12 @@
+export const weekdayLabels = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa']
+const pad2 = (value: number) => String(value).padStart(2, '0')
+export const toISODate = (date: Date) => `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`
+export function parseISODate(value: string | null) { if (!value) return null; const [year, month, day] = value.split('-').map(Number); return new Date(year, month - 1, day) }
+export function monthGrid(viewMonth: Date) {
+  const year = viewMonth.getFullYear(); const month = viewMonth.getMonth()
+  const startOffset = new Date(year, month, 1).getDay()
+  const daysInMonth = new Date(year, month + 1, 0).getDate()
+  const cells: Array<Date | null> = Array.from({ length: startOffset }, () => null)
+  for (let day = 1; day <= daysInMonth; day++) cells.push(new Date(year, month, day))
+  return cells
+}

package/src/cli/index.mjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+// Plain ESM — deliberately not TypeScript, so this runs on any Node (22.6+) without a loader,
+// build step, or dependency on how the host project executes TS. Run from the HOST app's own
+// directory (e.g. `cd apps/site && npx kilo-cms <command>`), same way `drizzle-kit` is run.
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const cliDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = join(cliDir, '..', '..') // packages/kilo-cms
+const cwd = process.cwd() // the host app's directory
+
+const [, , command, ...args] = process.argv
+
+function fail(message) {
+  console.error(`kilo-cms: ${message}`)
+  process.exit(1)
+}
+
+function slugToLabel(slug) {
+  const words = slug.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_]/g, ' ').trim()
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
+function singularize(label) {
+  return label.endsWith('ies') ? `${label.slice(0, -3)}y` : label.endsWith('s') ? label.slice(0, -1) : label
+}
+
+// --- add-collection ---------------------------------------------------------------------
+
+function addCollection(slug) {
+  if (!slug) fail('usage: kilo-cms add-collection <slug>')
+  if (!/^[a-z][a-zA-Z0-9]*$/.test(slug)) fail(`"${slug}" should be camelCase, starting with a lowercase letter (e.g. "projectCategories").`)
+
+  const collectionsDir = join(cwd, 'src', 'collections')
+  const targetDir = join(collectionsDir, slug)
+  if (existsSync(targetDir)) fail(`src/collections/${slug} already exists.`)
+  if (!existsSync(collectionsDir)) fail(`src/collections/ not found — run this from a host app that has kilo-cms installed (e.g. apps/site).`)
+
+  mkdirSync(targetDir, { recursive: true })
+  const label = slugToLabel(slug)
+  const labelSingular = singularize(label)
+  const varName = `${slug}Fields`
+
+  const fieldsFile = `import { defineCollectionFields } from 'kilo-cms/collections'
+
+export const ${varName} = defineCollectionFields({
+  kind: 'collection',
+  slug: '${slug}',
+  label: '${label}',
+  labelSingular: '${labelSingular}',
+  titleField: 'title',
+  defaultSort: { field: 'sortOrder', dir: 'asc' },
+  touchUpdatedAt: true,
+  groups: [
+    { id: 'overview', label: 'Overview' },
+    { id: 'record', label: 'Record', description: 'Managed by the CMS' },
+  ],
+  fields: [
+    { key: 'title', type: 'text', label: 'Title', group: 'overview', required: true, maxLength: 120, listColumn: true, listPrimary: true, searchable: true, sortable: true },
+    { key: 'slug', type: 'text', label: 'Slug', group: 'overview', width: 'half', required: true, format: 'slug', slugFrom: 'title', maxLength: 120, listColumn: true, searchable: true, sortable: true },
+    { key: 'sortOrder', type: 'number', label: 'Sort order', group: 'overview', integer: true, readOnly: true },
+    { key: 'createdAt', type: 'datetime', label: 'Created', group: 'record', readOnly: true, nullable: true, width: 'half', sortable: true },
+    { key: 'updatedAt', type: 'datetime', label: 'Last updated', group: 'record', readOnly: true, nullable: true, width: 'half', sortable: true, listColumn: true },
+  ],
+})
+`
+
+  const tableFile = `import 'server-only'
+import { pgTable, text, integer } from 'drizzle-orm/pg-core'
+import { timestamps } from 'kilo-cms/schema'
+import { defineCollectionTable } from 'kilo-cms/collections/table'
+
+export const ${slug} = defineCollectionTable('${slug}', pgTable('cms_${slug.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}', {
+  id: text('id').primaryKey(),
+  slug: text('slug').notNull().unique(),
+  title: text('title').notNull(),
+  sortOrder: integer('sort_order').notNull().default(0),
+  ...timestamps,
+}))
+`
+
+  writeFileSync(join(targetDir, 'fields.ts'), fieldsFile)
+  writeFileSync(join(targetDir, 'table.ts'), tableFile)
+
+  console.log(`Created src/collections/${slug}/fields.ts and table.ts.\n`)
+  console.log('Add these 3 lines to kilo.config.ts to register it:\n')
+  console.log(`  import { ${varName} } from './src/collections/${slug}/fields'`)
+  console.log(`  import './src/collections/${slug}/table'`)
+  console.log(`  // then add ${varName} to the \`collections: [...]\` array\n`)
+  console.log('Adjust the scaffolded fields to match what this collection actually needs, then run `npx kilo-cms sync`.')
+}
+
+// --- sync ---------------------------------------------------------------------------------
+
+function sync() {
+  const collectionsDir = join(cwd, 'src', 'collections')
+  if (!existsSync(collectionsDir)) fail('src/collections/ not found — run this from a host app that has kilo-cms installed.')
+
+  const slugs = readdirSync(collectionsDir).filter((name) => statSync(join(collectionsDir, name)).isDirectory()).sort()
+  if (!slugs.length) fail('No collections found under src/collections/.')
+
+  const unionBody = slugs.map((slug) => `  | '${slug}'`).join('\n')
+  const out = `// Generated by \`npx kilo-cms sync\` from src/collections/*/ — do not hand-edit.
+// A real, checkable union for THIS app's collections, layered on top of the engine's own
+// generic \`CollectionSlug = string\` (kilo-cms/collections) — import this type in your own
+// app code where you want real exhaustiveness/autocomplete instead of a bare string.
+export type CollectionSlug =
+${unionBody}
+`
+  const outDir = join(cwd, '.kilo')
+  mkdirSync(outDir, { recursive: true })
+  writeFileSync(join(outDir, 'types.gen.ts'), out)
+  console.log(`Wrote .kilo/types.gen.ts with ${slugs.length} collection${slugs.length === 1 ? '' : 's'}: ${slugs.join(', ')}`)
+}
+
+// --- migrate --------------------------------------------------------------------------------
+
+function migrate() {
+  console.log('Applying kilo-cms\'s own package-owned migrations (auth, RBAC, media, settings, dev-tools, admin-ui, locales)...')
+  const result = spawnSync('npx', ['drizzle-kit', 'migrate', '--config', join(packageRoot, 'drizzle.kilo.config.ts')], {
+    stdio: 'inherit',
+    cwd,
+    env: process.env,
+  })
+  if (result.status !== 0) process.exit(result.status ?? 1)
+  console.log('\nRun your own `db:generate`/`db:migrate` next for this app\'s own content tables.')
+}
+
+// --- dispatch -------------------------------------------------------------------------------
+
+switch (command) {
+  case 'add-collection':
+    addCollection(args[0])
+    break
+  case 'sync':
+    sync()
+    break
+  case 'migrate':
+    migrate()
+    break
+  default:
+    console.log(`kilo-cms — usage:
+  kilo-cms add-collection <slug>   scaffold a new collection's fields.ts + table.ts
+  kilo-cms sync                    regenerate .kilo/types.gen.ts from src/collections/*
+  kilo-cms migrate                 apply kilo-cms's own package-owned migrations`)
+    process.exit(command ? 1 : 0)
+}

package/src/cms-appearance.ts

@@ -0,0 +1,55 @@
+export const cmsColorKeys = ['ink', 'paper', 'acid', 'acidHover', 'acidInk', 'muted', 'line', 'danger', 'dangerSoft', 'canvas', 'surface', 'surfaceSoft'] as const
+export const cmsSizeKeys = ['radius', 'radiusSm', 'space1', 'space2', 'space3', 'space4', 'space5'] as const
+
+export type CmsColorKey = typeof cmsColorKeys[number]
+export type CmsSizeKey = typeof cmsSizeKeys[number]
+export type CmsAppearanceTokens = Record<CmsColorKey, string> & Record<CmsSizeKey, number>
+export type CmsAppearance = { preset: string; light: Partial<CmsAppearanceTokens>; dark: Partial<CmsAppearanceTokens> }
+
+type CmsAppearancePreset = { id: string; name: string; description: string; light: Partial<CmsAppearanceTokens>; dark: Partial<CmsAppearanceTokens> }
+
+const sizes = { radius: 8, radiusSm: 6, space1: 4, space2: 8, space3: 12, space4: 16, space5: 24 }
+const acidLight = { ink: '#171717', paper: '#f3f1ed', acid: '#d9ff55', acidHover: '#ecff9b', acidInk: '#171717', muted: '#696863', line: '#c9c6be', danger: '#c43b2d', dangerSoft: '#ff9c8f', canvas: '#e5e1d9', surface: '#ffffff', surfaceSoft: '#f8f7f4' }
+const acidDark = { ink: '#f3f1ed', paper: '#171717', acid: '#d9ff55', acidHover: '#ecff9b', acidInk: '#171717', muted: '#a6a39b', line: '#54524d', danger: '#ff6b57', dangerSoft: '#ffb0a5', canvas: '#242424', surface: '#2d2d2d', surfaceSoft: '#353535' }
+
+export const cmsAppearancePresets: CmsAppearancePreset[] = [
+  { id: 'acid', name: 'Acid', description: 'The current Kilo CMS signature.', light: acidLight, dark: acidDark },
+  { id: 'pink', name: 'Pink', description: 'Warm, expressive pink.', light: { ...acidLight, acid: '#ff75c6', acidHover: '#ffaadf' }, dark: { ...acidDark, acid: '#ff75c6', acidHover: '#ffaadf' } },
+  { id: 'sky', name: 'Sky blue', description: 'Crisp and airy blue.', light: { ...acidLight, acid: '#73d9ff', acidHover: '#a9e9ff' }, dark: { ...acidDark, acid: '#73d9ff', acidHover: '#a9e9ff' } },
+  { id: 'navy', name: 'Navy', description: 'Calm navy with blue accent.', light: { ...acidLight, ink: '#13213b', acid: '#74b8ff', acidHover: '#a9d4ff' }, dark: { ...acidDark, paper: '#101827', canvas: '#172033', surface: '#202c42', surfaceSoft: '#2a3850', acid: '#74b8ff', acidHover: '#a9d4ff' } },
+  { id: 'rose', name: 'Rose', description: 'Soft rose editorial palette.', light: { ...acidLight, acid: '#ff9eae', acidHover: '#ffc2cc' }, dark: { ...acidDark, acid: '#ff9eae', acidHover: '#ffc2cc' } },
+  { id: 'amber', name: 'Amber', description: 'Golden amber contrast.', light: { ...acidLight, acid: '#ffc44d', acidHover: '#ffda87' }, dark: { ...acidDark, acid: '#ffc44d', acidHover: '#ffda87' } },
+  { id: 'mono', name: 'Black & white', description: 'No accent colour, maximum restraint.', light: { ...acidLight, acid: '#171717', acidHover: '#3d3d3d', acidInk: '#ffffff' }, dark: { ...acidDark, acid: '#f3f1ed', acidHover: '#ffffff', acidInk: '#171717' } },
+  { id: 'maroon-gold', name: 'Maroon gold', description: 'Dark maroon, gold, and ivory.', light: { ...acidLight, ink: '#341017', paper: '#fff9eb', acid: '#d6a72c', acidHover: '#efc95c', canvas: '#eee1cd', surface: '#fffdf7' }, dark: { ...acidDark, paper: '#1d0a0d', canvas: '#291012', surface: '#351417', surfaceSoft: '#451d20', acid: '#d6a72c', acidHover: '#efc95c', acidInk: '#24170a', muted: '#d2bda5', line: '#664245' } },
+]
+
+export const defaultCmsAppearance: CmsAppearance = { preset: 'acid', light: {}, dark: {} }
+
+function normalizeOverrides(value: unknown) {
+  if (!value || typeof value !== 'object') return {}
+  const source = value as Record<string, unknown>
+  const colors = Object.fromEntries(cmsColorKeys.flatMap((key) => typeof source[key] === 'string' && /^#[0-9a-fA-F]{6}$/.test(source[key]) ? [[key, source[key]]] : []))
+  const numbers = Object.fromEntries(cmsSizeKeys.flatMap((key) => typeof source[key] === 'number' && Number.isInteger(source[key]) && source[key] >= 0 && source[key] <= 64 ? [[key, source[key]]] : []))
+  return { ...colors, ...numbers }
+}
+
+export function normalizeCmsAppearance(value: unknown): CmsAppearance {
+  if (!value || typeof value !== 'object') return defaultCmsAppearance
+  const candidate = value as Partial<CmsAppearance>
+  const preset = cmsAppearancePresets.some((item) => item.id === candidate.preset) ? candidate.preset! : defaultCmsAppearance.preset
+  return { preset, light: normalizeOverrides(candidate.light), dark: normalizeOverrides(candidate.dark) }
+}
+
+export function presetForAppearance(appearance: CmsAppearance) { return cmsAppearancePresets.find((item) => item.id === appearance.preset) ?? cmsAppearancePresets[0] }
+
+export function resolvedAppearanceTokens(appearance: CmsAppearance, mode: 'light' | 'dark'): CmsAppearanceTokens {
+  const preset = presetForAppearance(appearance)
+  return { ...sizes, ...(mode === 'light' ? preset.light : preset.dark), ...(mode === 'light' ? appearance.light : appearance.dark) } as CmsAppearanceTokens
+}
+
+const cssNames: Record<keyof CmsAppearanceTokens, string> = { ink: '--ink', paper: '--paper', acid: '--acid', acidHover: '--acid-hover', acidInk: '--acid-ink', muted: '--muted', line: '--line', danger: '--danger', dangerSoft: '--danger-soft', canvas: '--canvas', surface: '--surface', surfaceSoft: '--surface-soft', radius: '--radius', radiusSm: '--radius-sm', space1: '--space-1', space2: '--space-2', space3: '--space-3', space4: '--space-4', space5: '--space-5' }
+
+export function appearanceCssVariables(appearance: CmsAppearance, mode: 'light' | 'dark') {
+  const tokens = resolvedAppearanceTokens(appearance, mode)
+  return Object.fromEntries(Object.entries(tokens).map(([key, value]) => [cssNames[key as keyof CmsAppearanceTokens], typeof value === 'number' ? `${value}px` : value]))
+}

package/src/collections/content-view.ts

@@ -0,0 +1,69 @@
+import { getEntry } from './registry'
+import type { EntryConfig } from './types'
+
+// Named distinctly from FieldConfig's own `FieldWidth` (./types) to avoid an ambiguous-export
+// collision in the client-safe barrel (kilo-cms/collections re-exports both files) — the two
+// are coincidentally the same shape but serve different purposes (this one is a saved layout
+// preference; the other governs a field's actual rendered width).
+export type ContentViewFieldWidth = 'full' | 'half' | 'third'
+export type ContentViewGroup = { id: string; label: string; description?: string }
+export type ContentViewField = { key: string; label: string; description?: string; groupId: string | null; width: ContentViewFieldWidth }
+export type ContentViewSettings = { groups: ContentViewGroup[]; fields: ContentViewField[] }
+
+const validWidths: ContentViewFieldWidth[] = ['full', 'half', 'third']
+const cleanId = (value: string) => value.toLowerCase().trim().replace(/[^a-z0-9-]+/g, '-').replace(/(^-|-$)/g, '').slice(0, 40)
+
+export function isContentViewType(value: string): boolean {
+  return getEntry(value) !== null
+}
+
+/** For a caller that already HAS the resolved `EntryConfig` (e.g. a client component that
+ *  received it as a prop from its server-rendered page, rather than looking it up itself) —
+ *  see `defaultContentView` below for why that distinction matters. Pure, no registry lookup. */
+export function defaultContentViewFor(config: EntryConfig): ContentViewSettings {
+  return {
+    groups: config.groups.map((group) => ({ ...group })),
+    // Hidden fields never render a form control (see FieldConfig.hidden) — leaving them out here
+    // means the View settings drag-and-drop UI never offers a slot that ContentEditorForm would
+    // then silently drop.
+    fields: config.fields.filter((field) => !field.hidden).map((field) => ({ key: field.key, label: field.label, description: field.hint, groupId: field.group, width: field.width ?? 'full' })),
+  }
+}
+
+/** Looks `type` up in the registry itself — safe to call server-side (or anywhere the registry
+ *  is known to be populated), but NEVER from a client component: the registry is only ever
+ *  populated by `defineKiloConfig()`, which is server-only, so a client-side call always sees
+ *  an empty registry and silently falls back to the generic default below. Client code that
+ *  already has the resolved config (typically passed down as a prop from its server page)
+ *  should call `defaultContentViewFor(config)` instead. */
+export function defaultContentView(type: string): ContentViewSettings {
+  const config = getEntry(type)
+  if (config) return defaultContentViewFor(config)
+  return { groups: [{ id: 'overview', label: 'Overview' }], fields: [] }
+}
+
+export function normalizeContentView(type: string, input: unknown): ContentViewSettings {
+  const fallback = defaultContentView(type)
+  if (!input || typeof input !== 'object') return fallback
+  const raw = input as Partial<ContentViewSettings>
+  const groups = Array.isArray(raw.groups) ? raw.groups.map((group) => ({ id: typeof group?.id === 'string' ? cleanId(group.id) : '', label: typeof group?.label === 'string' ? group.label.trim().slice(0, 60) : '', description: typeof group?.description === 'string' ? group.description.trim().slice(0, 180) : undefined })).filter((group) => group.id && group.label).slice(0, 12) : []
+  const safeGroups = groups.length ? groups : fallback.groups
+  const groupIds = new Set(safeGroups.map((group) => group.id))
+  const rawFields = Array.isArray(raw.fields) ? raw.fields : []
+  const byKey = new Map(rawFields.filter((field): field is ContentViewField => Boolean(field && typeof field.key === 'string')).map((field) => [field.key, field]))
+  const fields = fallback.fields.map((fallbackField) => {
+    const field = byKey.get(fallbackField.key)
+    return {
+      key: fallbackField.key,
+      label: typeof field?.label === 'string' && field.label.trim() ? field.label.trim().slice(0, 80) : fallbackField.label,
+      description: typeof field?.description === 'string' ? field.description.trim().slice(0, 180) : undefined,
+      groupId: field?.groupId === null ? null : typeof field?.groupId === 'string' && groupIds.has(field.groupId) ? field.groupId : fallbackField.groupId && groupIds.has(fallbackField.groupId) ? fallbackField.groupId : safeGroups[0].id,
+      width: field && validWidths.includes(field.width) ? field.width : fallbackField.width,
+    }
+  })
+  const fieldOrder = rawFields.map((field) => typeof field?.key === 'string' ? field.key : '').filter((key) => fields.some((field) => field.key === key))
+  return { groups: safeGroups, fields: [...fieldOrder.map((key) => fields.find((field) => field.key === key)!), ...fields.filter((field) => !fieldOrder.includes(field.key))] }
+}
+
+export function contentViewField(settings: ContentViewSettings, key: string) { return settings.fields.find((field) => field.key === key) }
+export function contentViewLabels(settings: ContentViewSettings) { return Object.fromEntries(settings.fields.map((field) => [field.key, field.label])) }

package/src/collections/define.ts

@@ -0,0 +1,17 @@
+// Client-safe. MUST NOT import 'drizzle-orm', './query', '../db', or 'server-only' — a host's
+// `fields.ts` files (which call `defineCollectionFields`) are imported from client editor
+// components (e.g. CollectionRecordEditor) to know what to render.
+import type { CollectionConfig, SingleConfig } from './types'
+
+/** Identity helper — mostly for type inference/DX (so a host's `fields.ts` gets full
+ *  `CollectionConfig` autocomplete/checking without spelling out the type by hand) and a
+ *  future home for config-shape validation. Registration itself happens later, when the
+ *  config object this returns is listed in `defineKiloConfig({ collections: [...] })` — this
+ *  function has no side effect, so it's safe to call from client-reachable code. */
+export function defineCollectionFields(config: CollectionConfig): CollectionConfig {
+  return config
+}
+
+export function defineSingleFields(config: SingleConfig): SingleConfig {
+  return config
+}

package/src/collections/filters.ts

@@ -0,0 +1,92 @@
+import 'server-only'
+import { and, asc, desc, eq, ilike, isNotNull, isNull, ne, or, type SQL } from 'drizzle-orm'
+import { z } from 'zod'
+import type { ListQuery } from '../listQuery'
+import { collectionColumns } from './query'
+import { workflowListFilters, workflowSortKeys } from './types'
+import type { EntryConfig } from './types'
+
+const filterRuleSchema = z.object({
+  field: z.string().max(60),
+  operator: z.enum(['is', 'isNot', 'isEmpty', 'isNotEmpty']),
+  value: z.string().max(200).optional().default(''),
+})
+
+export function buildWhere(config: EntryConfig, query: ListQuery): SQL | undefined {
+  const columns = collectionColumns(config.slug)
+  const conditions: SQL[] = []
+
+  if (config.workflow?.trash && columns.deletedAt) {
+    conditions.push(query.trashed ? isNotNull(columns.deletedAt) : isNull(columns.deletedAt))
+  }
+
+  if (query.q) {
+    const clauses = config.fields
+      .filter((field) => field.searchable && (field.type === 'text' || field.type === 'textarea') && columns[field.key])
+      .map((field) => ilike(columns[field.key], `%${query.q}%`))
+    if (clauses.length) conditions.push(clauses.length === 1 ? clauses[0] : or(...clauses)!)
+  }
+
+  let rules: z.infer<typeof filterRuleSchema>[] = []
+  try {
+    const parsed = filterRuleSchema.array().safeParse(JSON.parse(query.filtersRaw))
+    if (parsed.success) rules = parsed.data
+  } catch {
+    // ignore malformed filters, same as the hand-written routes
+  }
+
+  for (const rule of rules) {
+    const workflowFilter = config.workflow
+      ? workflowListFilters.find((item) => item.key === rule.field && Boolean(config.workflow?.[item.requires]))
+      : undefined
+    if (workflowFilter && columns[workflowFilter.key]) {
+      const column = columns[workflowFilter.key]
+      if (workflowFilter.type === 'boolean') {
+        const scheduledAt = config.workflow?.scheduling ? columns.scheduledAt : undefined
+        if (scheduledAt && rule.value === 'scheduled') {
+          // Matches api/admin/blog/route.ts: isScheduled / isDraftOnly.
+          if (rule.operator === 'is') conditions.push(and(eq(column, false), isNotNull(scheduledAt))!)
+          else if (rule.operator === 'isNot') conditions.push(and(eq(column, false), isNull(scheduledAt))!)
+          continue
+        }
+        const wanted = rule.value === 'true'
+        if (rule.operator === 'is') conditions.push(scheduledAt && !wanted ? and(eq(column, false), isNull(scheduledAt))! : eq(column, wanted))
+        else if (rule.operator === 'isNot') conditions.push(eq(column, !wanted))
+      } else {
+        if (rule.operator === 'is') conditions.push(eq(column, rule.value))
+        else if (rule.operator === 'isNot') conditions.push(ne(column, rule.value))
+      }
+      continue
+    }
+
+    const field = config.fields.find((item) => item.key === rule.field && item.filterable)
+    const column = field && columns[field.key]
+    if (!field || !column) continue
+    if (field.type === 'boolean') {
+      const wanted = rule.value === 'true'
+      if (rule.operator === 'is') conditions.push(eq(column, wanted))
+      else if (rule.operator === 'isNot') conditions.push(eq(column, !wanted))
+      continue
+    }
+    if (rule.operator === 'is') conditions.push(eq(column, rule.value))
+    else if (rule.operator === 'isNot') conditions.push(ne(column, rule.value))
+    else if (rule.operator === 'isEmpty') conditions.push(field.nullable ? isNull(column) : eq(column, ''))
+    else if (rule.operator === 'isNotEmpty') conditions.push(field.nullable ? isNotNull(column) : ne(column, ''))
+  }
+
+  return conditions.length ? and(...conditions) : undefined
+}
+
+export function buildOrderBy(config: EntryConfig, query: ListQuery): SQL[] {
+  const columns = collectionColumns(config.slug)
+  const requested = config.fields.find((field) => field.key === query.sortBy && field.sortable)
+  const workflowSort = !requested && config.workflow && (workflowSortKeys as readonly string[]).includes(query.sortBy) && columns[query.sortBy]
+    ? query.sortBy
+    : null
+  const defaultKey = config.kind === 'collection' ? config.defaultSort.field : 'id'
+  const defaultDir = config.kind === 'collection' ? config.defaultSort.dir : 'asc'
+  const key = requested?.key ?? workflowSort ?? defaultKey
+  const column = columns[key] ?? columns[defaultKey] ?? columns.id
+  const dir = requested || workflowSort ? query.sortDir : defaultDir
+  return [dir === 'desc' ? desc(column) : asc(column)]
+}

package/src/collections/index.ts

@@ -0,0 +1,11 @@
+// Client-safe barrel. Every file re-exported here has NO 'server-only'/drizzle-orm import —
+// this is the one path admin editor client components use to know what to render. Server-only
+// engine pieces (validation, workflow, filters, join, single, query, table) are NOT here — see
+// 'kilo-cms/collections/server'.
+export * from './types'
+export * from './define'
+export * from './registry'
+export * from './values'
+export * from './content-view'
+export * from './locale'
+export * from './schedule'

package/src/collections/join.ts

@@ -0,0 +1,64 @@
+import 'server-only'
+import { eq, inArray } from 'drizzle-orm'
+import { collectionColumn, selectRows, type Row } from './query'
+import { getEntry } from './registry'
+import type { EntryConfig, FieldConfig } from './types'
+
+type JoinField = Extract<FieldConfig, { type: 'join' }>
+
+function titleFieldFor(field: JoinField): string {
+  const target = getEntry(field.collection)
+  return target && target.kind === 'collection' ? target.titleField : 'id'
+}
+
+/** `join` fields have no backing column — resolved at GET time by querying `field.collection`
+ *  for rows whose `field.on` (a `relation` field there) points back at this record's id.
+ *  Single-row version: used by the two GET-by-id routes. */
+export async function resolveJoinFields(config: EntryConfig, row: Row): Promise<Row> {
+  const joinFields = config.fields.filter((field): field is JoinField => field.type === 'join')
+  if (!joinFields.length) return row
+  const next = { ...row }
+  const id = String(row.id)
+  for (const field of joinFields) {
+    const column = collectionColumn(field.collection, field.on)
+    if (!column) { next[field.key] = []; continue }
+    const matches = await selectRows(field.collection, { where: eq(column, id) })
+    const titleField = titleFieldFor(field)
+    next[field.key] = matches.map((match) => ({ id: String(match.id), label: match[titleField] }))
+  }
+  return next
+}
+
+/** Batched version for the list route: ONE query per `listColumn: true` join field covering
+ *  every row on the current page (`inArray(on, ids)`), grouped by which parent row each match
+ *  belongs to — not one query per row. Join fields without `listColumn: true` are left alone
+ *  (the list route never needs their value). */
+export async function resolveJoinFieldsForList(config: EntryConfig, rows: Row[]): Promise<Row[]> {
+  const joinFields = config.fields.filter((field): field is JoinField => field.type === 'join' && Boolean(field.listColumn))
+  if (!joinFields.length || !rows.length) return rows
+  const ids = rows.map((row) => String(row.id))
+
+  const byField = new Map<string, Map<string, Array<{ id: string; label: unknown }>>>()
+  for (const field of joinFields) {
+    const column = collectionColumn(field.collection, field.on)
+    const grouped = new Map<string, Array<{ id: string; label: unknown }>>()
+    if (column) {
+      const matches = await selectRows(field.collection, { where: inArray(column, ids) })
+      const titleField = titleFieldFor(field)
+      for (const match of matches) {
+        const parentId = String(match[field.on])
+        const list = grouped.get(parentId)
+        const entry = { id: String(match.id), label: match[titleField] }
+        if (list) list.push(entry)
+        else grouped.set(parentId, [entry])
+      }
+    }
+    byField.set(field.key, grouped)
+  }
+
+  return rows.map((row) => {
+    const next = { ...row }
+    for (const field of joinFields) next[field.key] = byField.get(field.key)?.get(String(row.id)) ?? []
+    return next
+  })
+}