kilo-cms 0.1.0

package/src/collections/values.ts

@@ -0,0 +1,181 @@
+import { emptyRichText, type RichTextDocument, type RichTextNode } from '../richtext'
+import { fallbackLocaleConfig, type LocaleConfig } from './locale'
+import type { AnyFieldConfig, EntryConfig } from './types'
+
+// Set once by `defineKiloConfig({ currency })` — a live ES-module binding, same pattern as
+// `fallbackLocaleConfig` in ./locale. Defaults to USD/en-US rather than assuming any one
+// host's currency.
+export let currencyConfig = { locale: 'en-US', currency: 'USD' }
+
+/** Called by `defineKiloConfig()` — not meant to be called directly from app code. */
+export function __setCurrencyConfig(config: { locale: string; currency: string }) {
+  currencyConfig = config
+}
+
+/** Value written when a field is absent/blank, or when a role lacks field permission on create.
+ *  Also used to build a fresh row's default value for each sub-field of an `array`/`blocks`/
+ *  `group` field. `localeConfig` defaults to the static fallback — pass the live admin-configured
+ *  one (from `getLocaleConfig()`/`useCmsLocales()`) wherever it's actually available. */
+export function blankValueForField(field: AnyFieldConfig, localeConfig: LocaleConfig = fallbackLocaleConfig): unknown {
+  // Checked first (and recurses into the non-localized blank per locale) — 'localized' only
+  // exists on FieldBase, never on an array/block item field, hence the 'in' guard.
+  if ('localized' in field && field.localized) {
+    const perLocale = blankValueForField({ ...field, localized: false } as AnyFieldConfig, localeConfig)
+    return Object.fromEntries(localeConfig.codes.map((locale) => [locale, perLocale]))
+  }
+  if (field.nullable) return null
+  switch (field.type) {
+    case 'text':
+    case 'textarea':
+    case 'image':
+    case 'file':
+      return ''
+    case 'color':
+      return '#000000'
+    case 'number':
+    case 'rating':
+      return 0
+    case 'boolean':
+      return false
+    case 'select':
+      return field.options[0]?.value ?? ''
+    case 'date':
+    case 'time':
+    case 'datetime':
+      return null
+    case 'richtext':
+      return emptyRichText
+    case 'relation':
+      return field.hasMany ? [] : ''
+    case 'tags':
+    case 'multiselect':
+    case 'array':
+    case 'blocks':
+    case 'join':
+      return []
+    case 'group':
+      return Object.fromEntries(field.fields.map((subfield) => [subfield.key, blankValueForField(subfield)]))
+    case 'json':
+      return {}
+    case 'point':
+      return { lat: 0, lng: 0 }
+  }
+}
+
+/** Evaluates a field's `visibleIf` against the record it lives in (or, for an array/block item
+ *  field, the row it lives in) — `field` names a sibling key in that same object. Used both
+ *  client-side (hide the control) and server-side (relax `required` when not visible). */
+export function isFieldVisible(field: AnyFieldConfig, values: Record<string, unknown>): boolean {
+  if (!field.visibleIf) return true
+  const condition = field.visibleIf
+  const value = values[condition.field]
+  if ('equals' in condition) return value === condition.equals
+  if ('notEquals' in condition) return value !== condition.notEquals
+  if ('in' in condition) return condition.in.includes(value)
+  if ('gt' in condition) return Number(value) > condition.gt
+  if ('gte' in condition) return Number(value) >= condition.gte
+  if ('lt' in condition) return Number(value) < condition.lt
+  return Number(value) <= condition.lte
+}
+
+/** Flattens a tiptap doc to plain text for list cells, previews, and required-ness checks. */
+export function richTextToText(value: unknown, limit = 120): string {
+  const doc = value as RichTextDocument | null | undefined
+  if (!doc || doc.type !== 'doc' || !Array.isArray(doc.content)) return ''
+  const parts: string[] = []
+  const walk = (nodes: RichTextNode[]) => {
+    for (const node of nodes) {
+      if (typeof node.text === 'string') parts.push(node.text)
+      if (Array.isArray(node.content)) walk(node.content)
+      if (parts.join(' ').length > limit) return
+    }
+  }
+  walk(doc.content)
+  const text = parts.join(' ').replace(/\s+/g, ' ').trim()
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text
+}
+
+/** Blank record used by the "new record" editor state. */
+export function emptyRecord(config: EntryConfig, localeConfig: LocaleConfig = fallbackLocaleConfig): Record<string, unknown> {
+  return Object.fromEntries(config.fields.map((field) => [field.key, blankValueForField(field, localeConfig)]))
+}
+
+/** Human-readable cell/summary text. `relationLabels` is an id -> label map for the field's
+ *  target collection (covers both single and `hasMany` relations); the caller resolves it once
+ *  per field (e.g. via `labelsForIds`), not per row. Also used to render an array/group field's
+ *  contents in read-only mode. */
+export function formatFieldValue(field: AnyFieldConfig, value: unknown, relationLabels?: Record<string, string>, localeConfig: LocaleConfig = fallbackLocaleConfig): string {
+  if ('localized' in field && field.localized) {
+    const perLocale = (value ?? {}) as Record<string, unknown>
+    return formatFieldValue({ ...field, localized: false } as AnyFieldConfig, perLocale[localeConfig.default], relationLabels, localeConfig)
+  }
+  if (field.type === 'relation') {
+    const ids = field.hasMany ? (Array.isArray(value) ? (value as string[]) : []) : (typeof value === 'string' && value ? [value] : [])
+    return ids.length ? ids.map((id) => relationLabels?.[id] ?? id.slice(0, 8)).join(', ') : '—'
+  }
+  if (field.type === 'join') {
+    const rows = Array.isArray(value) ? (value as Array<{ label?: unknown }>) : []
+    return rows.length ? rows.map((row) => String(row.label ?? '?')).join(', ') : '—'
+  }
+  if (field.type === 'group') return field.fields.map((subfield) => formatFieldValue(subfield, (value as Record<string, unknown> | undefined)?.[subfield.key])).filter((text) => text && text !== '—').join(', ') || '—'
+  if (field.type === 'json') return value && typeof value === 'object' ? (Array.isArray(value) ? `[${value.length}]` : '{…}') : String(value ?? '—')
+  if (field.type === 'point') { const point = value as { lat?: number; lng?: number } | null; return point && typeof point.lat === 'number' ? `${point.lat}, ${point.lng}` : '—' }
+  if (field.type === 'file') return typeof value === 'string' && value ? value.split('/').pop() || value : '—'
+  if (value === null || value === undefined || value === '') return '—'
+  if (field.type === 'boolean') return value ? 'Yes' : 'No'
+  if (field.type === 'number')
+    return field.display === 'currency'
+      ? new Intl.NumberFormat(currencyConfig.locale, { style: 'currency', currency: currencyConfig.currency, maximumFractionDigits: 0 }).format(Number(value))
+      : field.display === 'percentage'
+        ? `${value}%`
+        : String(value)
+  if (field.type === 'rating') {
+    const max = field.max ?? 5
+    const filled = Math.max(0, Math.min(Number(value), max))
+    return '★'.repeat(filled) + '☆'.repeat(max - filled)
+  }
+  if (field.type === 'datetime') return new Date(String(value)).toLocaleString('en-US', { dateStyle: 'medium', timeStyle: 'short' })
+  if (field.type === 'select') return field.options.find((option) => option.value === value)?.label ?? String(value)
+  if (field.type === 'richtext') return richTextToText(value, 80) || '—'
+  if (field.type === 'tags') return Array.isArray(value) && value.length ? (value as string[]).join(', ') : '—'
+  if (field.type === 'image') return typeof value === 'string' && value ? value : '—'
+  if (field.type === 'time') return String(value).slice(0, 5)
+  if (field.type === 'multiselect')
+    return Array.isArray(value) && value.length
+      ? (value as string[]).map((item) => field.options.find((option) => option.value === item)?.label ?? item).join(', ')
+      : '—'
+  if (field.type === 'array')
+    return Array.isArray(value) && value.length ? `${value.length} ${value.length === 1 ? 'item' : 'items'}` : '—'
+  if (field.type === 'blocks')
+    return Array.isArray(value) && value.length
+      ? (value as Array<{ blockType?: unknown }>)
+          .map((row) => field.blockTypes.find((def) => def.type === row.blockType)?.label ?? String(row.blockType ?? '?'))
+          .join(', ')
+      : '—'
+  if (field.type === 'text' && field.format === 'password') return '••••••••' // never echo the value
+  return String(value)
+}
+
+export function slugify(value: string): string {
+  return value.toLowerCase().trim().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '')
+}
+
+/** Fills blank `format: 'slug'` fields: from `slugFrom` when declared, else `draft-<id>`.
+ *  Reproduces the hand-written `slug: data.slug || `draft-${id}`` fallback exactly, and lets a
+ *  collection like `categories` be created from a bare `{ name }` body. */
+export function applySlugFallbacks(config: EntryConfig, data: Record<string, unknown>, id: string): Record<string, unknown> {
+  const next = { ...data }
+  for (const field of config.fields) {
+    if (field.type !== 'text' || field.format !== 'slug' || field.readOnly) continue
+    const current = next[field.key]
+    if (typeof current === 'string' && current) continue
+    const source = field.slugFrom ? next[field.slugFrom] : null
+    next[field.key] = (typeof source === 'string' ? slugify(source) : '') || `draft-${id}`
+  }
+  return next
+}
+
+/** ':<fieldKey>' segments substituted from the row, e.g. '/services/:slug'. */
+export function resolvePreviewPath(template: string, row: Record<string, unknown>): string {
+  return template.replace(/:([a-zA-Z0-9_]+)/g, (_, key: string) => encodeURIComponent(String(row[key] ?? '')))
+}

package/src/collections/workflow.ts

@@ -0,0 +1,90 @@
+import 'server-only'
+
+import { contentRequiresApproval } from '../publishing-workflow-db'
+import { triggerWebhooks } from '../webhooks'
+import type { EntryConfig } from './types'
+import type { Row } from './query'
+
+export type ReviewStatus = 'draft' | 'in_review' | 'reviewed' | 'approved'
+
+export async function entryRequiresApproval(config: EntryConfig): Promise<boolean> {
+  const workflow = config.workflow
+  if (!workflow?.review) return false
+  if (workflow.approval === 'always') return true
+  if (workflow.approval === 'never') return false
+  return contentRequiresApproval(config.slug)
+}
+
+export function creationWorkflowValues(config: EntryConfig, userId: string, published: boolean, sortOrder: number): Row {
+  const workflow = config.workflow
+  if (!workflow) return {}
+  return {
+    ...(workflow.audit ? { createdBy: userId, ownerId: userId, updatedBy: userId } : {}),
+    ...(workflow.review ? { reviewStatus: 'draft' } : {}),
+    published,
+    publishedAt: published ? new Date() : null,
+    ...(workflow.sortOrder ? { sortOrder } : {}),
+  }
+}
+
+export function updateWorkflowValues(config: EntryConfig, userId: string, published: boolean | null): Row {
+  const workflow = config.workflow
+  if (!workflow) return {}
+  return {
+    ...(workflow.audit ? { updatedBy: userId } : {}),
+    ...(published === null
+      ? {}
+      : {
+          published,
+          // Publishing always clears a pending schedule — matches blog/[id]/route.ts's PATCH.
+          ...(published ? { publishedAt: new Date(), ...(workflow.scheduling ? { scheduledAt: null } : {}) } : {}),
+        }),
+  }
+}
+
+export function duplicateResetValues(config: EntryConfig, userId: string, sortOrder: number): Row {
+  const workflow = config.workflow
+  if (!workflow) return {}
+  return {
+    published: false,
+    publishedAt: null,
+    ...(workflow.scheduling ? { scheduledAt: null } : {}),
+    ...(workflow.trash ? { deletedAt: null } : {}),
+    ...(workflow.audit ? { createdBy: userId, ownerId: userId, updatedBy: userId } : {}),
+    ...(workflow.review ? { reviewStatus: 'draft', reviewerId: null, approverId: null, reviewedAt: null, approvedAt: null } : {}),
+    ...(workflow.sortOrder ? { sortOrder } : {}),
+  }
+}
+
+/** Scheduling a row also forces it out of `published` — matches the hand-written blog editor,
+ *  whose schedule() always sends `published: false`. */
+export function scheduleValues(config: EntryConfig, when: Date, userId: string): Row {
+  if (!config.workflow?.scheduling) return {}
+  return { scheduledAt: when, published: false, ...(config.workflow.audit ? { updatedBy: userId } : {}) }
+}
+
+export function unscheduleValues(config: EntryConfig, userId: string): Row {
+  if (!config.workflow?.scheduling) return {}
+  return { scheduledAt: null, ...(config.workflow.audit ? { updatedBy: userId } : {}) }
+}
+
+export const transitions = {
+  submitReview: (reviewerId: string, userId: string) => ({
+    reviewStatus: 'in_review',
+    reviewerId,
+    approverId: null,
+    reviewedAt: null,
+    approvedAt: null,
+    updatedBy: userId,
+  }),
+  passReview: (userId: string) => ({ reviewStatus: 'reviewed', reviewedAt: new Date(), updatedBy: userId }),
+  requestChanges: (userId: string) => ({ reviewStatus: 'draft', reviewerId: null, reviewedAt: null, updatedBy: userId }),
+  approve: (userId: string) => ({ reviewStatus: 'approved', approverId: userId, approvedAt: new Date(), updatedBy: userId }),
+  trash: (userId: string) => ({ deletedAt: new Date(), published: false, updatedBy: userId }),
+  restore: () => ({ deletedAt: null }),
+}
+
+export function fireWebhook(config: EntryConfig, event: 'created' | 'updated' | 'published' | 'unpublished' | 'deleted', row: unknown) {
+  if (!config.workflow?.webhooks) return
+  void triggerWebhooks(`${config.slug}.${event}`, row)
+}

package/src/config.ts

@@ -0,0 +1,34 @@
+import 'server-only'
+import { __registerCollections, __registerSingles } from './collections/registry'
+import { __setLocaleConfig, type LocaleConfig } from './collections/locale'
+import { __setCurrencyConfig } from './collections/values'
+import { __recomputeContentTypes } from './content-types'
+import { __setDb } from './db'
+import type { CollectionConfig, SingleConfig } from './collections/types'
+
+export type KiloConfig = {
+  /** The host's own drizzle instance — created against the host's own DATABASE_URL, with a
+   *  schema that merges `kilo-cms/schema` with the host's own content tables. */
+  db: unknown
+  /** Every collection this host defines, via `defineCollectionFields()` — see
+   *  kilo-cms/collections. Order here is the sidebar order. */
+  collections?: CollectionConfig[]
+  singles?: SingleConfig[]
+  locales?: LocaleConfig
+  currency?: { locale: string; currency: string }
+}
+
+/** The one call a host app makes to wire everything up — collections, the database
+ *  connection, locales, currency. Call it once, at app startup, BEFORE any request handler or
+ *  admin page runs (e.g. import it at the top of your root layout, or from a Next.js
+ *  `instrumentation.ts` `register()` hook). See apps/site/kilo.config.ts for the reference
+ *  host wiring, and this repo's own `kilo-cms` package docs for the full config shape. */
+export function defineKiloConfig(config: KiloConfig) {
+  __setDb(config.db)
+  if (config.collections?.length) __registerCollections(config.collections)
+  if (config.singles?.length) __registerSingles(config.singles)
+  __recomputeContentTypes()
+  if (config.locales) __setLocaleConfig(config.locales)
+  if (config.currency) __setCurrencyConfig(config.currency)
+  return config
+}

package/src/content-types.ts

@@ -0,0 +1,218 @@
+import { entries, entrySlugs, isCollectionSlug } from './collections/registry'
+import { blankValueForField } from './collections/values'
+import { workflowColumnKeys, type EntryConfig, type EntrySlug } from './collections/types'
+
+// submit_review/review/approve only ever appear in a type's `actions` (and are only grantable)
+// when that type has `workflow.review` — see `entryActions`. Previously a separate global
+// `StoredRolePermissions.workflow` array; folded into the same per-content-type actions/fields
+// structure as create/read/update/delete/publish so "review Blog but not Services" is possible.
+export type ActionKey = 'create' | 'read' | 'update' | 'delete' | 'publish' | 'submit_review' | 'review' | 'approve'
+
+// `settings` is the last hand-written content type: cms_site_settings stores cmsAppearance and
+// publishingWorkflow as bespoke jsonb blobs that no engine field type can render. Everything
+// else — including homepage, now the `homepage` single type — is generated from the registry.
+export type CoreContentTypeKey = 'settings'
+export type ContentTypeKey = CoreContentTypeKey | EntrySlug
+export type FieldDef = { key: string; label: string }
+export type ContentTypeDef = { label: string; kind: 'collection' | 'single'; actions: ActionKey[]; fields: FieldDef[] }
+
+// A generic slug may never be 'settings' — the spread in `contentTypeDefs` below would
+// silently shadow the hand-written settings content type.
+type NoSlugCollision = Extract<EntrySlug, CoreContentTypeKey> extends never ? true : ['slug collides with a core content type key']
+const _assertNoSlugCollision: NoSlugCollision = true
+void _assertNoSlugCollision
+
+const coreContentTypeDefs: Record<CoreContentTypeKey, ContentTypeDef> = {
+  settings: {
+    label: 'Settings', kind: 'single', actions: ['read', 'update'],
+    fields: [
+      { key: 'siteName', label: 'Site name' },
+      { key: 'logoLight', label: 'Logo (light mode)' },
+      { key: 'logoDark', label: 'Logo (dark mode)' },
+      { key: 'metaTitle', label: 'Default meta title' },
+      { key: 'metaDescription', label: 'Default meta description' },
+      { key: 'metaImage', label: 'Default social image' },
+      { key: 'cmsAppearance', label: 'CMS appearance' },
+      { key: 'publishingWorkflow', label: 'Publishing workflow' },
+    ],
+  },
+}
+
+const genericCollectionActions: ActionKey[] = ['create', 'read', 'update', 'delete']
+const genericWorkflowCollectionActions: ActionKey[] = ['create', 'read', 'update', 'delete', 'publish']
+const genericSingleActions: ActionKey[] = ['read', 'update']
+const genericWorkflowSingleActions: ActionKey[] = ['read', 'update', 'publish']
+
+function entryActions(config: EntryConfig): ActionKey[] {
+  const publish = Boolean(config.workflow?.publish)
+  const actions: ActionKey[] = config.kind === 'single'
+    ? [...(publish ? genericWorkflowSingleActions : genericSingleActions)]
+    : [...(publish ? genericWorkflowCollectionActions : genericCollectionActions)]
+  if (config.workflow?.review) actions.push('submit_review', 'review', 'approve')
+  return actions
+}
+
+function entryContentTypeDef(config: EntryConfig): ContentTypeDef {
+  return {
+    label: config.label,
+    kind: config.kind,
+    actions: entryActions(config),
+    // `join` has no backing column — never writable, so it's meaningless as a field permission.
+    fields: config.fields
+      .filter((field) => !field.readOnly && field.type !== 'join' && !(workflowColumnKeys as readonly string[]).includes(field.key))
+      .map((field) => ({ key: field.key, label: field.label })),
+  }
+}
+
+// `contentTypeDefs`/`contentTypeKeys`/`blankFieldValues` below are live ES-module bindings,
+// recomputed by `__recomputeContentTypes()` — called once by `defineKiloConfig()` after it
+// registers the host's collections/singles. They start as just the hand-written `settings`
+// type; every importer sees the real, full set automatically once config has run, the same
+// live-binding pattern `./collections/registry` uses for `entrySlugs`/`entries`/etc.
+export let contentTypeDefs: Record<ContentTypeKey, ContentTypeDef> = { ...coreContentTypeDefs }
+export let contentTypeKeys: ContentTypeKey[] = Object.keys(contentTypeDefs) as ContentTypeKey[]
+
+export const systemPermissions = ['users.manage', 'roles.manage', 'ai.manage', 'views.manage', 'developers.manage', 'locales.manage'] as const
+export type SystemPermission = typeof systemPermissions[number]
+export const systemPermissionLabels: Record<SystemPermission, string> = {
+  'users.manage': 'Manage users',
+  'roles.manage': 'Manage roles',
+  'ai.manage': 'Manage AI provider keys',
+  'views.manage': 'Manage View settings (field layout)',
+  'developers.manage': 'Manage email, API tokens & webhooks',
+  'locales.manage': 'Manage locales (for localized fields)',
+}
+
+export const actionLabels: Record<ActionKey, string> = {
+  create: 'Create', read: 'Read', update: 'Update', delete: 'Delete / Trash', publish: 'Publish',
+  submit_review: 'Submit for review', review: 'Review submissions', approve: 'Approve for publish',
+}
+
+export type StoredRolePermissions = {
+  contentTypes: Partial<Record<ContentTypeKey, { actions: ActionKey[]; fields: string[] }>>
+  system: SystemPermission[]
+}
+
+export const emptyRolePermissions: StoredRolePermissions = { contentTypes: {}, system: [] }
+
+export function fullRolePermissions(): StoredRolePermissions {
+  return {
+    contentTypes: Object.fromEntries(contentTypeKeys.map((key) => [key, { actions: [...contentTypeDefs[key].actions], fields: contentTypeDefs[key].fields.map((field) => field.key) }])) as StoredRolePermissions['contentTypes'],
+    system: [...systemPermissions],
+  }
+}
+
+// Blank defaults used server-side when a role lacks permission for a field on CREATE
+// (the submitted value is dropped in favor of this instead of the row's — nonexistent —
+// prior value).
+// `approvalRequired` used to hand-list this app's own collection slugs (`['services',
+// 'projects', 'blog']`) — computed instead, from whichever registered collections actually
+// declare `workflow.review`, so the package never needs to know a host's specific slugs.
+function coreBlankFieldValues(): Record<CoreContentTypeKey, Record<string, unknown>> {
+  return {
+    settings: { siteName: 'Kilo CMS', logoLight: null, logoDark: null, metaTitle: '', metaDescription: '', metaImage: null, cmsAppearance: { preset: 'acid', light: {}, dark: {} }, publishingWorkflow: { approvalRequired: entrySlugs.filter((slug) => entries[slug].workflow?.review) } },
+  }
+}
+
+export let blankFieldValues: Record<ContentTypeKey, Record<string, unknown>> = { ...coreBlankFieldValues() }
+
+// Overwrites any field the caller isn't allowed to change with a fallback value
+// (the row's existing value on update, or a static blank on create).
+export function applyFieldPermissions<T extends Record<string, unknown>>(type: ContentTypeKey, data: T, allowedFields: string[], fallback: Record<string, unknown>): T {
+  const result: Record<string, unknown> = { ...data }
+  for (const field of contentTypeDefs[type].fields) {
+    if (!allowedFields.includes(field.key) && field.key in result && field.key in fallback) result[field.key] = fallback[field.key]
+  }
+  return result as T
+}
+
+// Same shape as `applyFieldPermissions`, but for READ: a field the caller has no permission for
+// is removed from the response entirely (not just blanked) — closes the "create/update are
+// per-field, read is all-or-nothing" gap, and doesn't even reveal that the field has SOME value
+// (blanking would still leak "this row has this field set to something", just not what).
+export function redactFieldsForRead<T extends Record<string, unknown>>(type: ContentTypeKey, data: T, allowedFields: string[]): T {
+  const result: Record<string, unknown> = { ...data }
+  for (const field of contentTypeDefs[type].fields) {
+    if (!allowedFields.includes(field.key) && field.key in result) delete result[field.key]
+  }
+  return result as T
+}
+
+/** Called once by `defineKiloConfig()`, after it registers the host's collections/singles —
+ *  not meant to be called directly from app code. Recomputes the three live-binding exports
+ *  above, then re-runs the same config-integrity checks that used to run once at module load
+ *  (back when the registry was a static object literal fully known at that point). */
+export function __recomputeContentTypes() {
+  contentTypeDefs = {
+    ...coreContentTypeDefs,
+    ...(Object.fromEntries(entrySlugs.map((slug) => [slug, entryContentTypeDef(entries[slug])])) as Record<EntrySlug, ContentTypeDef>),
+  }
+  contentTypeKeys = Object.keys(contentTypeDefs) as ContentTypeKey[]
+  blankFieldValues = {
+    ...coreBlankFieldValues(),
+    ...(Object.fromEntries(entrySlugs.map((slug) => [
+      slug,
+      Object.fromEntries(entries[slug].fields
+        .filter((field) => !field.readOnly && !(workflowColumnKeys as readonly string[]).includes(field.key))
+        .map((field) => [field.key, blankValueForField(field)])),
+    ])) as Record<EntrySlug, Record<string, unknown>>),
+  }
+  runConfigIntegrityChecks()
+}
+
+function runConfigIntegrityChecks() {
+  if (process.env.NODE_ENV === 'production') return
+  for (const slug of entrySlugs) {
+    const config = entries[slug]
+    const stray = config.fields.find((field) => (workflowColumnKeys as readonly string[]).includes(field.key))
+    if (stray) console.error(`[collections] ${slug}: "${stray.key}" is an engine-owned workflow column and must not be declared as a field.`)
+    if (config.workflow?.review && !config.workflow.audit) console.error(`[collections] ${slug}: workflow.review requires workflow.audit.`)
+    if (config.kind === 'single' && (config.workflow?.review || config.workflow?.trash || config.workflow?.scheduling))
+      console.error(`[collections] ${slug}: single types support workflow.publish/audit only in v1.`)
+    const scheduling = config.workflow?.scheduling
+    if (scheduling) {
+      const dateField = config.fields.find((field) => field.key === scheduling.dateField)
+      if (dateField?.type !== 'date') console.error(`[collections] ${slug}: workflow.scheduling.dateField "${scheduling.dateField}" must be a declared 'date' field.`)
+      if (scheduling.timeField) {
+        const timeField = config.fields.find((field) => field.key === scheduling.timeField)
+        if (timeField?.type !== 'time') console.error(`[collections] ${slug}: workflow.scheduling.timeField "${scheduling.timeField}" must be a declared 'time' field.`)
+      }
+    }
+    for (const field of config.fields) {
+      if (field.type === 'text' && field.slugFrom && field.format !== 'slug')
+        console.error(`[collections] ${slug}.${field.key}: slugFrom is only honored with format: 'slug'.`)
+      if (field.type === 'text' && field.slugFrom && !config.fields.some((other) => other.key === field.slugFrom))
+        console.error(`[collections] ${slug}.${field.key}: slugFrom "${field.slugFrom}" is not a declared field.`)
+      if (field.type === 'text' && field.suggestionsFrom && !isCollectionSlug(field.suggestionsFrom.collection))
+        console.error(`[collections] ${slug}.${field.key}: suggestionsFrom targets an unknown collection.`)
+      if (field.type === 'text' && field.format === 'password' && (field.searchable || field.sortable))
+        console.error(`[collections] ${slug}.${field.key}: a password field must not be searchable/sortable.`)
+      if (field.type === 'relation' && field.hasMany && (field.filterable || field.searchable || field.sortable))
+        console.error(`[collections] ${slug}.${field.key}: a hasMany relation must not be filterable/searchable/sortable.`)
+      if (field.type === 'join' && (field.readOnly === false))
+        console.error(`[collections] ${slug}.${field.key}: join has no backing column — never declare readOnly: false on it.`)
+      if (field.type === 'join' && (field.filterable || field.searchable || field.sortable))
+        console.error(`[collections] ${slug}.${field.key}: join must not be filterable/searchable/sortable — no backing column to query against. (listColumn IS supported.)`)
+      if (field.type === 'join') {
+        const target = entries[field.collection]
+        const onField = target?.fields.find((other) => other.key === field.on)
+        if (!onField || onField.type !== 'relation' || onField.hasMany)
+          console.error(`[collections] ${slug}.${field.key}: "on" must name a declared non-hasMany 'relation' field on "${field.collection}".`)
+      }
+      if (field.localized && field.type !== 'text' && field.type !== 'textarea' && field.type !== 'richtext')
+        console.error(`[collections] ${slug}.${field.key}: localized is only honored on text/textarea/richtext.`)
+      if (field.type === 'array' || field.type === 'blocks' || field.type === 'group') {
+        const nested = field.type === 'group' || field.type === 'array' ? field.fields : field.blockTypes.flatMap((blockDef) => blockDef.fields)
+        for (const item of nested) if ('localized' in item && (item as { localized?: boolean }).localized)
+          console.error(`[collections] ${slug}.${field.key}: localized is not supported on array/block/group item fields.`)
+      }
+      if (field.type === 'blocks') {
+        const seen = new Set<string>()
+        for (const blockDef of field.blockTypes) {
+          if (seen.has(blockDef.type)) console.error(`[collections] ${slug}.${field.key}: duplicate block type "${blockDef.type}".`)
+          seen.add(blockDef.type)
+        }
+      }
+    }
+  }
+}

package/src/dashboard.ts

@@ -0,0 +1,39 @@
+import { entries, entrySlugs } from './collections/registry'
+import type { EntrySlug } from './collections/types'
+
+// Any registered collection/single can be a dashboard widget's data source — no longer a
+// hardcoded literal union of one host's specific slugs.
+export type DashboardSource = EntrySlug
+export type DashboardMetric = 'count' | 'sum' | 'avg' | 'true' | 'false'
+export type DashboardVisual = 'number' | 'bar' | 'line' | 'donut' | 'table'
+export type DashboardSize = 'small' | 'medium' | 'large'
+export type DashboardWidget = {
+  id: string
+  title: string
+  source: DashboardSource
+  metric: DashboardMetric
+  field?: string
+  groupBy?: string
+  visual: DashboardVisual
+  limit: number
+  size: DashboardSize
+}
+export type DashboardConfig = { widgets: DashboardWidget[] }
+
+// A genuinely empty starter — a host's specific collections (and which fields are worth
+// charting) aren't something the package can guess at. Build your own default from the
+// Dashboard Builder UI; this is only what a brand-new install sees before anyone has.
+export const defaultDashboard: DashboardConfig = { widgets: [] }
+
+/** Computed from whichever collections/singles are actually registered — not a hardcoded
+ *  list. `fields` always offers the engine-owned workflow columns every entry has, plus
+ *  whichever of that entry's own fields are `filterable` (a reasonable proxy for "meaningful
+ *  to group/count by"). */
+export function getDashboardSources(): Array<{ value: DashboardSource; label: string; fields: string[] }> {
+  return entrySlugs.map((slug) => {
+    const config = entries[slug]
+    const ownFields = config.fields.filter((field) => 'filterable' in field && field.filterable).map((field) => field.key)
+    const workflowFields = config.workflow ? ['published', 'reviewStatus', 'sortOrder'].filter((key) => key === 'published' ? config.workflow?.publish : key === 'reviewStatus' ? config.workflow?.review : config.workflow?.sortOrder) : []
+    return { value: slug, label: config.label, fields: [...ownFields, ...workflowFields] }
+  })
+}

package/src/db.ts

@@ -0,0 +1,50 @@
+import 'server-only'
+
+// kilo-cms doesn't own the database connection — the HOST app creates its own drizzle client
+// (its own DATABASE_URL, its own merged schema) and hands it to `defineKiloConfig({ db, ... })`.
+// Everything inside the package that needs to run a query imports `db` from here instead of
+// creating/importing a connection directly, so the package never hardcodes one specific host's
+// connection. The lazy Proxy means every existing `db.select()...`-style call site inside the
+// package keeps working unchanged — only this file's import path is new, not the usage.
+//
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- the real type is the host's
+// own drizzle instance, whatever schema it was created with; kilo-cms only needs the parts of
+// the query builder API it actually calls, so a precise generic isn't worth chasing here.
+type AnyDb = any
+
+let _db: AnyDb | null = null
+
+/** Called once by `defineKiloConfig()` — never call this directly from application code. */
+export function __setDb(instance: AnyDb) {
+  _db = instance
+}
+
+export const db: AnyDb = new Proxy(
+  {},
+  {
+    get(_target, prop) {
+      if (!_db) throw new Error('kilo-cms: defineKiloConfig() must run before the database is used — import and call it from your app entry (e.g. instrumentation.ts or the root layout) before any request touches the CMS.')
+      return _db[prop]
+    },
+  },
+)
+
+// Same lazy-injection pattern, for the better-auth instance the host creates via
+// `createKiloAuth()` (see ./auth) — `createKiloAuth` calls `__setAuth` itself as its last step,
+// so anything inside the package needing `auth` (permissions.ts's session lookups) just imports
+// it from here rather than assuming there's one global instance it can create/import directly.
+let _auth: AnyDb | null = null
+
+export function __setAuth(instance: AnyDb) {
+  _auth = instance
+}
+
+export const auth: AnyDb = new Proxy(
+  {},
+  {
+    get(_target, prop) {
+      if (!_auth) throw new Error('kilo-cms: createKiloAuth() must run before auth is used.')
+      return _auth[prop]
+    },
+  },
+)

package/src/email.ts

@@ -0,0 +1,39 @@
+import 'server-only'
+
+import { eq } from 'drizzle-orm'
+import nodemailer from 'nodemailer'
+import { db } from './db'
+import { emailSettings } from './schema'
+import { decryptSecret } from './secrets'
+
+const DOMAIN = 'cms-email-secrets'
+
+export async function getEmailSettings() {
+  const [settings] = await db.select().from(emailSettings).where(eq(emailSettings.id, 'default')).limit(1)
+  return settings ?? null
+}
+
+export function isEmailConfigured(settings: { host: string | null; port: number | null; fromAddress: string | null } | null) {
+  return Boolean(settings?.host && settings.port && settings.fromAddress)
+}
+
+export async function sendEmail({ to, subject, html, text }: { to: string; subject: string; html?: string; text?: string }) {
+  const settings = await getEmailSettings()
+  if (!isEmailConfigured(settings)) throw new Error('Email isn\'t configured yet. Add SMTP settings first.')
+  const password = settings!.encryptedPassword ? decryptSecret(settings!.encryptedPassword, DOMAIN) : undefined
+  const transport = nodemailer.createTransport({
+    host: settings!.host!,
+    port: settings!.port!,
+    secure: settings!.secure,
+    auth: settings!.username ? { user: settings!.username, pass: password } : undefined,
+  })
+  await transport.sendMail({
+    from: settings!.fromName ? `"${settings!.fromName}" <${settings!.fromAddress}>` : settings!.fromAddress!,
+    to,
+    subject,
+    html,
+    text: text ?? (html ? undefined : subject),
+  })
+}
+
+export { DOMAIN as EMAIL_SECRET_DOMAIN }