kilo-cms 0.1.0

package/src/collections/locale.ts

@@ -0,0 +1,22 @@
+// The live, admin-editable locale list lives in the `cms_locales` table — see
+// `src/lib/locale-settings.ts` (server, DB-backed, request-cached) and `CmsLocalesProvider`
+// (client, populated once per admin page load from the same table). This module is just the
+// SHAPE of that config plus the fallback used wherever no live config was threaded through
+// (mainly internal recursive calls that don't need it, since only the one top-level `localized`
+// check in `blankValueForField`/`fieldSchema`/`formatFieldValue` ever reads it).
+export type LocaleConfig = { codes: string[]; default: string; labels: Record<string, string> }
+
+// Set once by `defineKiloConfig({ locales })` — a live ES-module binding, so every importer of
+// `fallbackLocaleConfig` sees the host's real value once config runs. Starts as a single-locale
+// no-op rather than a hardcoded language pair, since the package can't assume any host's
+// locales — a host that never calls `locales` in its config just gets one default locale.
+export let fallbackLocaleConfig: LocaleConfig = {
+  codes: ['en'],
+  default: 'en',
+  labels: { en: 'English' },
+}
+
+/** Called by `defineKiloConfig()` — not meant to be called directly from app code. */
+export function __setLocaleConfig(config: LocaleConfig) {
+  fallbackLocaleConfig = config
+}

package/src/collections/query.ts

@@ -0,0 +1,160 @@
+import 'server-only'
+/* eslint-disable @typescript-eslint/no-explicit-any -- drizzle's builder types cannot
+   express a table chosen at runtime; every call here is re-typed at the function boundary. */
+import { count as sqlCount, eq, getTableColumns, inArray, isNotNull, isNull, max, type SQL } from 'drizzle-orm'
+import type { PgColumn, PgTable } from 'drizzle-orm/pg-core'
+import { db } from '../db'
+import { relationFields } from './registry'
+import type { EntryConfig, EntrySlug } from './types'
+
+export type Row = Record<string, unknown>
+
+// slug -> drizzle table, populated by `defineCollectionTable()` calls in the host's own
+// `table.ts` files (see kilo-cms/collections) — never a hardcoded import of specific tables.
+const tables: Record<string, PgTable> = {}
+
+/** Called by `defineCollectionTable()` — not meant to be called directly from app code. */
+export function __registerTable(slug: string, table: PgTable) {
+  tables[slug] = table
+}
+
+export function collectionTable(slug: EntrySlug): PgTable { return tables[slug] }
+
+export function collectionColumns(slug: EntrySlug): Record<string, PgColumn> {
+  return getTableColumns(tables[slug]) as Record<string, PgColumn>
+}
+
+export function collectionColumn(slug: EntrySlug, key: string): PgColumn | null {
+  return collectionColumns(slug)[key] ?? null
+}
+
+export function idColumn(slug: EntrySlug): PgColumn {
+  const column = collectionColumn(slug, 'id')
+  if (!column) throw new Error(`Entry ${slug} has no id column`)
+  return column
+}
+
+export async function selectRows(slug: EntrySlug, options: { where?: SQL; orderBy?: SQL[]; limit?: number; offset?: number } = {}): Promise<Row[]> {
+  let query: any = db.select().from(tables[slug] as any)
+  if (options.where) query = query.where(options.where)
+  if (options.orderBy?.length) query = query.orderBy(...options.orderBy)
+  if (typeof options.limit === 'number') query = query.limit(options.limit)
+  if (typeof options.offset === 'number') query = query.offset(options.offset)
+  return (await query) as Row[]
+}
+
+export async function countRows(slug: EntrySlug, where?: SQL): Promise<number> {
+  let query: any = db.select({ value: sqlCount() }).from(tables[slug] as any)
+  if (where) query = query.where(where)
+  const [row] = (await query) as Array<{ value: number }>
+  return Number(row?.value ?? 0)
+}
+
+export async function findRow(slug: EntrySlug, id: string): Promise<Row | null> {
+  const rows = await selectRows(slug, { where: eq(idColumn(slug), id), limit: 1 })
+  return rows[0] ?? null
+}
+
+export async function insertRow(slug: EntrySlug, values: Row): Promise<Row> {
+  const rows = (await (db.insert(tables[slug] as any) as any).values(values).returning()) as Row[]
+  return rows[0]
+}
+
+export async function updateRow(slug: EntrySlug, id: string, values: Row): Promise<Row | null> {
+  const rows = (await (db.update(tables[slug] as any) as any).set(values).where(eq(idColumn(slug), id)).returning()) as Row[]
+  return rows[0] ?? null
+}
+
+export async function deleteRow(slug: EntrySlug, id: string): Promise<boolean> {
+  const rows = (await (db.delete(tables[slug] as any) as any).where(eq(idColumn(slug), id)).returning()) as Row[]
+  return rows.length > 0
+}
+
+export async function deleteRows(slug: EntrySlug, ids: string[]): Promise<number> {
+  if (!ids.length) return 0
+  const rows = (await (db.delete(tables[slug] as any) as any).where(inArray(idColumn(slug), ids)).returning()) as Row[]
+  return rows.length
+}
+
+/** id -> title, for rendering relation cells and select options without N+1 queries. */
+export async function labelsForIds(slug: EntrySlug, ids: string[], labelKey: string): Promise<Record<string, string>> {
+  if (!ids.length) return {}
+  const label = collectionColumn(slug, labelKey) ?? idColumn(slug)
+  const rows = (await (db.select({ id: idColumn(slug), label }).from(tables[slug] as any) as any)
+    .where(inArray(idColumn(slug), ids))) as Array<{ id: string; label: unknown }>
+  return Object.fromEntries(rows.map((row) => [row.id, String(row.label ?? row.id)]))
+}
+
+/** Returns the subset of `ids` that exist — used for FK pre-validation. */
+export async function existingIds(slug: EntrySlug, ids: string[]): Promise<Set<string>> {
+  if (!ids.length) return new Set()
+  const rows = (await (db.select({ id: idColumn(slug) }).from(tables[slug] as any) as any)
+    .where(inArray(idColumn(slug), ids))) as Array<{ id: string }>
+  return new Set(rows.map((row) => row.id))
+}
+
+/** FK pre-validation for every `relation` field on `data` (single or `hasMany`) — returns the
+ *  first broken reference's error message, or null if everything referenced still exists. Shared
+ *  by the collection create/update routes and the single-type update route. */
+export async function findInvalidRelation(config: EntryConfig, data: Row): Promise<string | null> {
+  for (const field of relationFields(config)) {
+    const value = data[field.key]
+    const ids = field.hasMany
+      ? (Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string' && item !== '') : [])
+      : (typeof value === 'string' && value ? [value] : [])
+    if (!ids.length) continue
+    const exists = await existingIds(field.relationTo, ids)
+    if (ids.some((id) => !exists.has(id))) return `${field.label}: that record no longer exists.`
+  }
+  return null
+}
+
+export function isForeignKeyViolation(error: unknown): boolean { return pgCode(error) === '23503' }
+export function isUniqueViolation(error: unknown): boolean { return pgCode(error) === '23505' }
+function pgCode(error: unknown): string | null {
+  return typeof error === 'object' && error !== null && typeof (error as { code?: unknown }).code === 'string'
+    ? (error as { code: string }).code
+    : null
+}
+
+export async function updateWhere(slug: EntrySlug, where: SQL, values: Row): Promise<Row[]> {
+  return (await (db.update(tables[slug] as any) as any).set(values).where(where).returning()) as Row[]
+}
+
+export async function updateRows(slug: EntrySlug, ids: string[], values: Row): Promise<number> {
+  if (!ids.length) return 0
+  return (await updateWhere(slug, inArray(idColumn(slug), ids), values)).length
+}
+
+export async function findRowBy(slug: EntrySlug, key: string, value: string): Promise<Row | null> {
+  const column = collectionColumn(slug, key)
+  if (!column) throw new Error(`Entry ${slug} has no ${key} column`)
+  const rows = await selectRows(slug, { where: eq(column, value), limit: 1 })
+  return rows[0] ?? null
+}
+
+export async function upsertRowBy(slug: EntrySlug, key: string, values: Row, set: Row): Promise<Row> {
+  const column = collectionColumn(slug, key)
+  if (!column) throw new Error(`Entry ${slug} has no ${key} column`)
+  const rows = (await (db.insert(tables[slug] as any) as any).values(values).onConflictDoUpdate({ target: column, set }).returning()) as Row[]
+  return rows[0]
+}
+
+export async function nextSortOrder(slug: EntrySlug): Promise<number> {
+  const column = collectionColumn(slug, 'sortOrder')
+  if (!column) return 0
+  const rows = (await (db.select({ value: max(column) }).from(tables[slug] as any) as any)) as Array<{ value: number | null }>
+  return Number(rows[0]?.value ?? -1) + 1
+}
+
+export async function applyOrder(slug: EntrySlug, ids: string[]): Promise<void> {
+  const column = collectionColumn(slug, 'sortOrder')
+  if (!column) throw new Error(`Entry ${slug} has no sortOrder column`)
+  await db.transaction(async (tx: any) => {
+    for (const [index, id] of ids.entries()) {
+      await (tx.update(tables[slug] as any) as any).set({ sortOrder: index }).where(eq(idColumn(slug), id))
+    }
+  })
+}
+
+export { isNotNull, isNull }

package/src/collections/registry.ts

@@ -0,0 +1,88 @@
+// Runtime registry: a host app registers its own collections/singles by calling
+// `defineKiloConfig({ collections: [...], singles: [...] })` once, at app startup (see
+// kilo-cms/config). Nothing here hand-lists a fixed set of slugs — that's the whole point:
+// this file used to require 4 manually-touched places to add one collection; now a host adds
+// one `fields.ts` + `table.ts` pair and lists it in their own `kilo.config.ts`.
+//
+// The exported `let`s below (`collectionSlugs`, `entries`, etc.) are live ES-module bindings —
+// every importer sees the up-to-date value automatically once `__registerCollections`/
+// `__registerSingles` run, with no change needed at any call site that already did
+// `import { collectionSlugs } from 'kilo-cms/collections'`.
+import { workflowColumnKeys } from './types'
+import type { CollectionConfig, CollectionSlug, EntryConfig, EntrySlug, FieldConfig, SingleConfig, SingleSlug } from './types'
+
+const collections: Record<string, CollectionConfig> = {}
+const singles: Record<string, SingleConfig> = {}
+
+export let collectionSlugs: CollectionSlug[] = []
+export let singleSlugs: SingleSlug[] = []
+export let entries: Record<EntrySlug, EntryConfig> = {}
+export let entrySlugs: EntrySlug[] = []
+export let workflowSlugs: EntrySlug[] = []
+export let reviewableSlugs: EntrySlug[] = []
+export let trashableSlugs: EntrySlug[] = []
+export let schedulingSlugs: EntrySlug[] = []
+
+function recompute() {
+  collectionSlugs = Object.keys(collections)
+  singleSlugs = Object.keys(singles)
+  entries = { ...collections, ...singles }
+  entrySlugs = Object.keys(entries)
+  workflowSlugs = entrySlugs.filter((slug) => Boolean(entries[slug].workflow))
+  reviewableSlugs = entrySlugs.filter((slug) => entries[slug].workflow?.review)
+  trashableSlugs = entrySlugs.filter((slug) => entries[slug].workflow?.trash)
+  schedulingSlugs = entrySlugs.filter((slug) => Boolean(entries[slug].workflow?.scheduling))
+}
+
+/** Called once by `defineKiloConfig()` — not meant to be called directly from app code. */
+export function __registerCollections(configs: CollectionConfig[]) {
+  for (const config of configs) {
+    // Catches the one mistake a hand-authored config can still make now that there's no
+    // `Record<CollectionSlug, ...>` object-literal shape forcing key === config.slug: a
+    // duplicate or mistyped slug across two `defineCollectionFields()` calls.
+    if (process.env.NODE_ENV !== 'production' && collections[config.slug]) {
+      console.error(`[kilo-cms] duplicate collection slug "${config.slug}" registered more than once.`)
+    }
+    collections[config.slug] = config
+  }
+  recompute()
+}
+
+/** Called once by `defineKiloConfig()` — not meant to be called directly from app code. */
+export function __registerSingles(configs: SingleConfig[]) {
+  for (const config of configs) singles[config.slug] = config
+  recompute()
+}
+
+export function isCollectionSlug(value: string): value is CollectionSlug {
+  return Object.prototype.hasOwnProperty.call(collections, value)
+}
+
+export function getCollection(slug: string): CollectionConfig | null {
+  return isCollectionSlug(slug) ? collections[slug] : null
+}
+
+export function collectionField(config: CollectionConfig, key: string): FieldConfig | undefined {
+  return config.fields.find((field) => field.key === key)
+}
+
+/** Fields a client may submit (everything except readOnly). */
+export function writableFields(config: EntryConfig): FieldConfig[] {
+  return config.fields.filter((field) => !field.readOnly && !(workflowColumnKeys as readonly string[]).includes(field.key))
+}
+
+export function relationFields(config: EntryConfig) {
+  return config.fields.filter((field): field is Extract<FieldConfig, { type: 'relation' }> => field.type === 'relation')
+}
+
+export function isSingleSlug(value: string): value is SingleSlug {
+  return Object.prototype.hasOwnProperty.call(singles, value)
+}
+
+export function getSingle(slug: string): SingleConfig | null {
+  return isSingleSlug(slug) ? singles[slug] : null
+}
+
+export function getEntry(slug: string): EntryConfig | null {
+  return Object.prototype.hasOwnProperty.call(entries, slug) ? entries[slug] : null
+}

package/src/collections/schedule.ts

@@ -0,0 +1,12 @@
+// Pure. MUST NOT import 'drizzle-orm', '../schema', '../db', or 'server-only' —
+// reachable from client editors.
+
+/** Combines a 'YYYY-MM-DD' date and an optional 'HH:MM[:SS]' clock into a UTC ISO string,
+ *  interpreting both in the browser's local timezone. Lifted verbatim from
+ *  BlogEditor.combineScheduledAt() so scheduled times land on the same instant as today. */
+export function combineScheduledAt(date: string | null, time: string | null): string | null {
+  if (!date) return null
+  const clock = time && /^\d{2}:\d{2}/.test(time) ? (time.length === 5 ? `${time}:00` : time) : '00:00:00'
+  const local = new Date(`${date}T${clock}`)
+  return Number.isNaN(local.getTime()) ? null : local.toISOString()
+}

package/src/collections/server.ts

@@ -0,0 +1,12 @@
+// Server-only barrel — every file here has 'server-only' and/or a drizzle-orm import. NEVER
+// import this from a client component; use 'kilo-cms/collections' (the client-safe barrel)
+// for anything an editor UI needs to know about a field/collection shape.
+import 'server-only'
+
+export * from './validation'
+export * from './workflow'
+export * from './filters'
+export * from './join'
+export * from './single'
+export * from './query'
+export * from './table'

package/src/collections/single.ts

@@ -0,0 +1,26 @@
+import 'server-only'
+
+import { findRowBy, upsertRowBy, type Row } from './query'
+import { emptyRecord } from './values'
+import type { SingleConfig } from './types'
+
+export async function readSingle(config: SingleConfig): Promise<Row> {
+  const row = await findRowBy(config.slug, config.fixedKey.column, config.fixedKey.value)
+  if (row) return row
+  return {
+    ...emptyRecord(config),
+    id: config.fixedKey.column === 'id' ? config.fixedKey.value : '',
+    [config.fixedKey.column]: config.fixedKey.value,
+    ...(config.workflow?.publish ? { published: false, publishedAt: null } : {}),
+  }
+}
+
+export async function writeSingle(config: SingleConfig, data: Row, extra: Row): Promise<Row> {
+  const set = { ...data, ...extra, ...(config.touchUpdatedAt ? { updatedAt: new Date() } : {}) }
+  const values = {
+    id: config.fixedKey.column === 'id' ? config.fixedKey.value : crypto.randomUUID(),
+    [config.fixedKey.column]: config.fixedKey.value,
+    ...set,
+  }
+  return upsertRowBy(config.slug, config.fixedKey.column, values, set)
+}

package/src/collections/table.ts

@@ -0,0 +1,14 @@
+import 'server-only'
+import type { PgTable } from 'drizzle-orm/pg-core'
+import { __registerTable } from './query'
+
+/** Registers a host's drizzle table against a collection/single slug so the generic engine
+ *  (query.ts) can run CRUD against it — this is the runtime replacement for query.ts's old
+ *  hardcoded `tables` map. Call it once per collection, in that collection's own `table.ts`
+ *  (server-only — never import this from a `fields.ts` file, which must stay client-safe).
+ *  Returns the table unchanged so it can still be exported/used normally elsewhere (e.g. a
+ *  host's own `/api/v1/*` route doing its own direct query). */
+export function defineCollectionTable<T extends PgTable>(slug: string, table: T): T {
+  __registerTable(slug, table)
+  return table
+}