@michaelthielemann/kestrel 3.0.1 → 4.0.1

package/layers/core/server/schema/model.ts

@@ -1,61 +0,0 @@
-// Normalized, dialect-agnostic schema model for the migration engine (ADR-0002). Both sides of a diff
-// are expressed in this shape: the *desired* snapshot (built from collection tables via getTableConfig)
-// and the *actual* snapshot (introspected from the live DB). `diffSchema` compares them; a dialect
-// renderer turns the resulting ops into DDL. SQLite is the first dialect.
-
-export interface ColumnShape {
-  name: string
-  /** SQLite storage type as it appears in DDL: `integer` | `text` | `real` | `blob`. */
-  type: string
-  notNull: boolean
-  primaryKey: boolean
-  autoIncrement: boolean
-  /** Raw SQL default token, exactly as it follows `DEFAULT` (e.g. `'draft'`, `0`), or null for none. */
-  default: string | null
-  /** The column's previous name (from a `renamedFrom` field hint) — the diff renames in place rather
-   *  than dropping the old column and losing its data. */
-  renamedFrom?: string
-  /** A relation/media `single↔multiple` toggle: the column moved between `<col>_id` (scalar) and `<col>`
-   *  (json array), so the rename needs a data shape transform. `wrap` = scalar→array, `unwrap` = array→scalar. */
-  renameTransform?: 'wrap' | 'unwrap'
-}
-
-export interface IndexShape {
-  name: string
-  table: string
-  columns: string[]
-  unique: boolean
-  /** Partial-index predicate (the text after `WHERE`), or null for a full index. */
-  where: string | null
-}
-
-export interface TableShape {
-  name: string
-  columns: ColumnShape[]
-  indexes: IndexShape[]
-}
-
-/** A whole schema, keyed by table name. */
-export type SchemaSnapshot = Record<string, TableShape>
-
-/**
- * One structured, dialect-agnostic schema change. The first four variants are **additive** (no data
- * loss): create table/column/index, and drop_index (indexes hold no row data, so dropping one is
- * reversible). The last two are **destructive** (see `isDestructive`):
- *  - `drop_table` — a collection was removed.
- *  - `rebuild_table` — a column was dropped or its definition changed; since SQLite has no in-place
- *    ALTER COLUMN, the table is recreated and the surviving columns (`copy`) are carried over.
- * Destructive ops are never auto-applied; they require an explicit opt-in (ADR-0002).
- */
-export type SchemaOp =
-  | { type: 'create_table'; table: TableShape }
-  | { type: 'add_column'; table: string; column: ColumnShape }
-  | { type: 'create_index'; index: IndexShape }
-  | { type: 'drop_index'; index: IndexShape }
-  // `rename_column` is additive (data-preserving, `ALTER TABLE … RENAME COLUMN`); it runs before any
-  // rebuild, so a rebuilt table sees the column under its new name.
-  | { type: 'rename_column'; table: string; from: string; to: string }
-  | { type: 'drop_table'; name: string }
-  // `transforms` maps a copied column to a shape transform of a differently-named source column (a
-  // relation/media single↔multiple toggle); plain copies just use the column's own (new) name.
-  | { type: 'rebuild_table'; table: TableShape; copy: string[]; transforms?: Record<string, { from: string; type: 'wrap' | 'unwrap' }> }

package/layers/core/server/schema/render-sqlite.ts

@@ -1,89 +0,0 @@
-import type { ColumnShape, IndexShape, TableShape, SchemaOp } from './model'
-
-// SQLite dialect renderer: structured ops → DDL strings. Kept separate from `diffSchema` (which is
-// dialect-agnostic) so a future Postgres renderer can sit behind the same op interface (ADR-0002).
-
-const q = (id: string) => `\`${id.replace(/`/g, '``')}\``
-const lit = (s: string) => `'${s.replace(/'/g, "''")}'`
-
-/**
- * A column definition, shared by CREATE TABLE and ALTER TABLE ADD COLUMN. Clause order matches the
- * committed drizzle-kit migrations: `<type> [PRIMARY KEY [AUTOINCREMENT]] [DEFAULT <x>] [NOT NULL]`.
- * (SQLite rejects a NOT-NULL ADD COLUMN without a default on a non-empty table — that guard belongs to
- * the apply/validation layer, not here.)
- */
-function columnClause(c: ColumnShape): string {
-  let s = `${q(c.name)} ${c.type}`
-  if (c.primaryKey) s += c.autoIncrement ? ' PRIMARY KEY AUTOINCREMENT' : ' PRIMARY KEY'
-  if (c.default !== null) s += ` DEFAULT ${c.default}`
-  if (c.notNull) s += ' NOT NULL'
-  return s
-}
-
-// Indexes are emitted as separate create_index ops, so CREATE TABLE renders columns only.
-function createTableSql(name: string, columns: ColumnShape[]): string {
-  const cols = columns.map((c) => `  ${columnClause(c)}`).join(',\n')
-  return `CREATE TABLE ${q(name)} (\n${cols}\n);`
-}
-
-/**
- * SQLite has no ALTER COLUMN / safe DROP COLUMN, so a destructive column change is a table rebuild:
- * create a new table at the desired shape, copy the surviving columns' data, drop the old, rename the
- * new into place, then recreate the indexes. (No foreign keys exist in this schema, so the usual
- * `PRAGMA foreign_keys` dance is unnecessary.)
- */
-/** SELECT source for a copied column: itself, or a single↔multiple shape transform of a differently-named source. */
-function copySource(col: string, transforms?: Record<string, { from: string; type: 'wrap' | 'unwrap' }>): string {
-  const t = transforms?.[col]
-  if (!t) return q(col)
-  return t.type === 'wrap'
-    ? `CASE WHEN ${q(t.from)} IS NULL THEN '[]' ELSE json_array(${q(t.from)}) END`
-    : `json_extract(${q(t.from)}, '$[0]')`
-}
-
-function rebuildTable(table: TableShape, copy: string[], transforms?: Record<string, { from: string; type: 'wrap' | 'unwrap' }>): string[] {
-  const tmp = `__kestrel_new_${table.name}`
-  // `DROP TABLE IF EXISTS` first so an orphan temp from an interrupted earlier rebuild self-heals
-  // instead of colliding on CREATE and wedging the migration.
-  const stmts = [`DROP TABLE IF EXISTS ${q(tmp)};`, createTableSql(tmp, table.columns)]
-  if (copy.length) {
-    const into = copy.map(q).join(', ')
-    const select = copy.map((c) => copySource(c, transforms)).join(', ')
-    stmts.push(`INSERT INTO ${q(tmp)} (${into}) SELECT ${select} FROM ${q(table.name)};`)
-  }
-  // Preserve the AUTOINCREMENT high-water mark across the rebuild so ids are never reused (a reused id
-  // could silently repoint a stale internal-link / relation reference). `sqlite_sequence` has no UNIQUE
-  // on `name`, so INSERT-OR-REPLACE won't work — ensure the temp row exists, then bump it to the old
-  // table's mark. Must run while the old table's seq row still exists (before its DROP); the RENAME then
-  // carries the row's name across.
-  if (table.columns.some((c) => c.autoIncrement)) {
-    stmts.push(`INSERT INTO sqlite_sequence (name, seq) SELECT ${lit(tmp)}, 0 WHERE NOT EXISTS (SELECT 1 FROM sqlite_sequence WHERE name = ${lit(tmp)});`)
-    stmts.push(`UPDATE sqlite_sequence SET seq = MAX(seq, COALESCE((SELECT seq FROM sqlite_sequence WHERE name = ${lit(table.name)}), 0)) WHERE name = ${lit(tmp)};`)
-  }
-  stmts.push(`DROP TABLE ${q(table.name)};`)
-  stmts.push(`ALTER TABLE ${q(tmp)} RENAME TO ${q(table.name)};`)
-  for (const index of table.indexes) stmts.push(createIndex(index))
-  return stmts
-}
-
-function createIndex(i: IndexShape): string {
-  const unique = i.unique ? 'UNIQUE ' : ''
-  const cols = i.columns.map(q).join(',')
-  const where = i.where ? ` WHERE ${i.where}` : ''
-  return `CREATE ${unique}INDEX ${q(i.name)} ON ${q(i.table)} (${cols})${where};`
-}
-
-/** Render structured ops into SQLite DDL, preserving order. Most ops are one statement; a rebuild is several. */
-export function renderSqlite(ops: SchemaOp[]): string[] {
-  return ops.flatMap((op): string[] => {
-    switch (op.type) {
-      case 'create_table': return [createTableSql(op.table.name, op.table.columns)]
-      case 'add_column': return [`ALTER TABLE ${q(op.table)} ADD COLUMN ${columnClause(op.column)};`]
-      case 'create_index': return [createIndex(op.index)]
-      case 'drop_index': return [`DROP INDEX IF EXISTS ${q(op.index.name)};`]
-      case 'rename_column': return [`ALTER TABLE ${q(op.table)} RENAME COLUMN ${q(op.from)} TO ${q(op.to)};`]
-      case 'drop_table': return [`DROP TABLE ${q(op.name)};`]
-      case 'rebuild_table': return rebuildTable(op.table, op.copy, op.transforms)
-    }
-  })
-}

package/layers/core/server/schema/sync.ts

@@ -1,201 +0,0 @@
-import type { IntrospectDb } from './introspect'
-import { diffSchema } from './diff'
-import { sqlite, type Dialect } from './dialect'
-import type { SchemaSnapshot, SchemaOp } from './model'
-
-export interface SyncDb extends IntrospectDb {
-  exec(sql: string): unknown
-  transaction(fn: () => void): () => void
-}
-
-/** Destructive ops drop or rebuild a table (potential data loss); they require an explicit opt-in (ADR-0002). */
-export function isDestructive(op: SchemaOp): boolean {
-  return op.type === 'drop_table' || op.type === 'rebuild_table'
-}
-
-/** Human description of an op, for dry-run reports and the dev skipped-warning so data loss is visible. */
-export function describeOp(op: SchemaOp): string {
-  if (op.type === 'drop_table') return `drop table \`${op.name}\``
-  if (op.type === 'rebuild_table') {
-    // Name the carried columns + any transform sources (not just a count), so the operator can see exactly
-    // what survives — everything else that is live but NOT in this list has its data dropped by the rebuild.
-    const carried = op.copy.join(', ') || '—'
-    const sources = [...new Set(Object.values(op.transforms ?? {}).map((t) => t.from))]
-    const from = sources.length ? ` (+ transform source(s): ${sources.join(', ')})` : ''
-    return `rebuild table \`${op.table.name}\` — keeps: ${carried}${from}; any other live column's data is dropped`
-  }
-  if (op.type === 'create_table') return `create table \`${op.table.name}\` (${op.table.columns.length} column(s))`
-  if (op.type === 'add_column') return `add column \`${op.table}\`.\`${op.column.name}\` ${op.column.type}`
-  if (op.type === 'create_index') return `create index \`${op.index.name}\` on \`${op.index.table}\` (${op.index.columns.join(', ')})`
-  if (op.type === 'drop_index') return `drop index \`${op.index.name}\` on \`${op.index.table}\``
-  if (op.type === 'rename_column') return `rename column \`${op.table}\`.\`${op.from}\` to \`${op.to}\``
-  return (op as SchemaOp).type
-}
-
-/**
- * Reasons SQLite would reject a rebuild's `INSERT…SELECT` — surfaced up-front as a clear error instead
- * of an opaque "NOT NULL constraint failed" inside an aborted transaction:
- *  - a NOT NULL column with no default that isn't carried over (a new required field on a populated table)
- *  - a carried-over column that became NOT NULL but whose existing rows still hold NULL
- * Identifier quoting comes from the dialect (the feasibility probes run against the live DB).
- */
-function rebuildProblems(db: SyncDb, op: Extract<SchemaOp, { type: 'rebuild_table' }>, quote: Dialect['quote'], renames: Map<string, string>): string[] {
-  const carried = new Set(op.copy)
-  const problems: string[] = []
-  // The probes run against the LIVE table, which still holds the PRE-migration column names: rename_column
-  // ops and the rebuild's INSERT…SELECT only run later, inside the transaction. So resolve each carried
-  // column to its live SOURCE expression — a transform's `from`, else its own name — and skip when no live
-  // source exists yet (a plain rename we can't map here), rather than probe a name that doesn't exist and
-  // abort the whole migration with `no such column`. The expressions mirror render-sqlite's `copySource`.
-  const liveCols = new Set((db.pragma(`table_info("${op.table.name.replace(/"/g, '""')}")`) as { name: string }[]).map((r) => r.name))
-  const liveSourceIsNull = (c: string): boolean | null => {
-    const t = op.transforms?.[c]
-    if (t) {
-      // `wrap` (single→multiple) coalesces NULL to '[]' → never NULL. `unwrap` (multiple→single) is
-      // `json_extract(from, '$[0]')` → NULL for a NULL or empty source array.
-      if (t.type === 'wrap') return false
-      if (!liveCols.has(t.from)) return null
-      return db.prepare(`SELECT 1 FROM ${quote(op.table.name)} WHERE json_extract(${quote(t.from)}, '$[0]') IS NULL LIMIT 1`).all().length > 0
-    }
-    if (!liveCols.has(c)) {
-      // The column isn't live under its NEW name yet — it arrives via a plain `rename_column` that runs
-      // first. Probe its OLD live name instead (the rename preserves data, so a NOT NULL target still
-      // fails on rows the old column left NULL). Only skip when even the source name isn't live.
-      const from = renames.get(`${op.table.name} ${c}`)
-      if (from && liveCols.has(from)) return db.prepare(`SELECT 1 FROM ${quote(op.table.name)} WHERE ${quote(from)} IS NULL LIMIT 1`).all().length > 0
-      return null
-    }
-    return db.prepare(`SELECT 1 FROM ${quote(op.table.name)} WHERE ${quote(c)} IS NULL LIMIT 1`).all().length > 0
-  }
-  for (const c of op.table.columns) {
-    if (!c.notNull || c.default !== null || c.autoIncrement) continue
-    if (!carried.has(c.name)) {
-      problems.push(`${op.table.name}.${c.name}: new NOT NULL column has no default and no data to copy`)
-    } else if (liveSourceIsNull(c.name) === true) {
-      problems.push(`${op.table.name}.${c.name}: became NOT NULL but existing rows hold NULL`)
-    }
-  }
-  // A UNIQUE index recreated by the rebuild over carried-over data that already holds duplicates would
-  // abort the migration; flag it up front. (SQLite treats NULLs as distinct, so only non-null rows count.)
-  // Only probe when every index column already exists live (a renamed/transformed column can't be checked
-  // here without a live name — skip rather than crash, same as the NULL probe above).
-  for (const idx of op.table.indexes) {
-    if (!idx.unique || !idx.columns.every((c) => carried.has(c) && liveCols.has(c))) continue
-    const cols = idx.columns.map(quote).join(', ')
-    const notNull = idx.columns.map((c) => `${quote(c)} IS NOT NULL`).join(' AND ')
-    const partial = idx.where ? ` AND (${idx.where})` : ''
-    const dup = db.prepare(`SELECT 1 FROM ${quote(op.table.name)} WHERE ${notNull}${partial} GROUP BY ${cols} HAVING COUNT(*) > 1 LIMIT 1`).all().length > 0
-    if (dup) problems.push(`${op.table.name}.(${idx.columns.join(', ')}): UNIQUE index "${idx.name}" has duplicate values in existing rows`)
-  }
-  return problems
-}
-
-/**
- * A plain `ALTER TABLE … ADD COLUMN` can't add a NOT NULL column with no default to a table that
- * already holds rows (SQLite rejects it; an empty table is fine). This is reachable purely additively —
- * adding a required field with no default to a populated collection emits a standalone `add_column`,
- * never a rebuild — so the rebuild pre-flight misses it. Surface it as the same up-front 'infeasible'
- * message instead of an opaque mid-transaction abort.
- */
-function addColumnProblems(db: SyncDb, op: Extract<SchemaOp, { type: 'add_column' }>, quote: Dialect['quote']): string[] {
-  const c = op.column
-  if (!c.notNull || c.default !== null || c.autoIncrement) return []
-  const hasRows = db.prepare(`SELECT 1 FROM ${quote(op.table)} LIMIT 1`).all().length > 0
-  return hasRows ? [`${op.table}.${c.name}: new NOT NULL column has no default and the table already has rows`] : []
-}
-
-/**
- * A new standalone UNIQUE index (e.g. flipping an existing populated column to `unique: true`) aborts if
- * current rows already hold duplicate non-null values. Same duplicate probe `rebuildProblems` runs, but
- * for a `create_index` op against the live table. Skip when an index column isn't live yet (it arrives
- * via a rename that runs first) rather than probe a missing column and abort with `no such column`.
- */
-function createIndexProblems(db: SyncDb, op: Extract<SchemaOp, { type: 'create_index' }>, quote: Dialect['quote']): string[] {
-  const idx = op.index
-  if (!idx.unique) return []
-  const liveCols = new Set((db.pragma(`table_info("${idx.table.replace(/"/g, '""')}")`) as { name: string }[]).map((r) => r.name))
-  if (!idx.columns.every((c) => liveCols.has(c))) return []
-  const cols = idx.columns.map(quote).join(', ')
-  const notNull = idx.columns.map((c) => `${quote(c)} IS NOT NULL`).join(' AND ')
-  const partial = idx.where ? ` AND (${idx.where})` : ''
-  const dup = db.prepare(`SELECT 1 FROM ${quote(idx.table)} WHERE ${notNull}${partial} GROUP BY ${cols} HAVING COUNT(*) > 1 LIMIT 1`).all().length > 0
-  return dup ? [`${idx.table}.(${idx.columns.join(', ')}): UNIQUE index "${idx.name}" has duplicate values in existing rows`] : []
-}
-
-/** Compute the ops needed to bring `db` to `desired` WITHOUT applying them — the dry-run / `--check`
- *  source. Reads the live schema through `dialect.introspect` (defaults to SQLite). */
-export function planOps(db: SyncDb, desired: SchemaSnapshot, dialect: Dialect = sqlite): SchemaOp[] {
-  return diffSchema(desired, dialect.introspect(db))
-}
-
-export interface SyncOptions {
-  /** Apply `rebuild_table` ops (a managed collection's columns were dropped or changed). */
-  allowDestructive?: boolean
-  /** Table names allowed to be dropped. A `drop_table` applies ONLY if its table is listed here, so an
-   *  unmanaged / unrelated table is never dropped just because `allowDestructive` was set. */
-  dropTables?: string[]
-}
-
-export interface SyncResult {
-  /** DDL statements applied, in order (empty when already in sync). */
-  applied: string[]
-  /** Destructive ops withheld (not opted into) — the DB was left intact for them. */
-  skipped: SchemaOp[]
-}
-
-/**
- * Reconcile a live database to `desired` through `dialect` (defaults to SQLite). Additive ops always
- * apply. Destructive ops need an explicit, op-specific opt-in: `rebuild_table` requires
- * `allowDestructive`; `drop_table` requires the table to be named in `dropTables` (a blanket
- * `allowDestructive` never drops tables). Withheld ops are returned in `skipped`. Everything applied runs
- * in one transaction.
- */
-export function syncSchema(db: SyncDb, desired: SchemaSnapshot, opts: SyncOptions = {}, dialect: Dialect = sqlite): SyncResult {
-  const droppable = new Set(opts.dropTables ?? [])
-  const allowed = (op: SchemaOp): boolean => {
-    if (op.type === 'rebuild_table') return opts.allowDestructive === true
-    if (op.type === 'drop_table') return droppable.has(op.name)
-    return true
-  }
-  const ops = planOps(db, desired, dialect)
-  let toApply = ops.filter(allowed)
-  let skipped = ops.filter((op) => !allowed(op))
-
-  // A `rename_column` queued ahead of a `rebuild_table` is only sound as that rebuild's prologue (diff.ts
-  // never re-gates it on the rebuild being applied). If the rebuild was withheld, ship neither half — a
-  // bare rename would leave the table renamed but not rebuilt, silently diverging from `desired`.
-  const withheldRebuildTables = new Set(skipped.filter((op) => op.type === 'rebuild_table').map((op) => op.table.name))
-  if (withheldRebuildTables.size) {
-    const demoted = toApply.filter((op) => op.type === 'rename_column' && withheldRebuildTables.has(op.table))
-    if (demoted.length) {
-      toApply = toApply.filter((op) => !demoted.includes(op))
-      skipped = [...skipped, ...demoted]
-    }
-  }
-
-  // Validate feasibility BEFORE opening the transaction, so an impossible migration fails loud and
-  // changes nothing (rather than aborting the transaction with an opaque constraint error). Every
-  // apply-time-fatal op is pre-flighted: rebuilds, plus the purely-additive add_column(NOT NULL, no
-  // default) on a populated table and create_index(UNIQUE) over existing duplicates.
-  // Plain renames (`ALTER TABLE … RENAME COLUMN`) run BEFORE the rebuilds, so a rebuild's carried column
-  // may be probed under its OLD live name — build a PER-TABLE new→old map so the NOT NULL feasibility check
-  // can. Keyed by table: two tables renaming a different column to the SAME new name must not collide.
-  const renames = new Map<string, string>() // `${table} ${to}` → from
-  for (const op of toApply) if (op.type === 'rename_column') renames.set(`${op.table} ${op.to}`, op.from)
-  const problems = toApply.flatMap((op) =>
-    op.type === 'rebuild_table' ? rebuildProblems(db, op, dialect.quote, renames)
-    : op.type === 'add_column' ? addColumnProblems(db, op, dialect.quote)
-    : op.type === 'create_index' ? createIndexProblems(db, op, dialect.quote)
-    : [])
-  if (problems.length) {
-    throw new Error(`kestrel: schema migration is infeasible — fix the collection or its data, then retry:\n  - ${problems.join('\n  - ')}`)
-  }
-
-  const applied = dialect.render(toApply)
-  if (applied.length) {
-    db.transaction(() => {
-      for (const sql of applied) db.exec(sql)
-    })()
-  }
-  return { applied, skipped }
-}

package/layers/core/server/utils/blocks.ts

@@ -1,6 +0,0 @@
-export interface Block {
-  id: string
-  type: string
-  props: Record<string, unknown>
-  slots?: Record<string, Block[]>
-}

package/layers/core/server/utils/collection-types.ts

@@ -1,28 +0,0 @@
-import type { SQLiteTable } from 'drizzle-orm/sqlite-core'
-import type { z } from 'zod'
-import type { CollectionDef } from './defineCollection'
-
-/** The validation schemas are loose `ZodObject`s. drizzle-zod's builders are overloaded such that
- *  `ReturnType<typeof createInsertSchema>` resolves to the WRONG (ZodEnum) overload, so the shape is stated
- *  directly — `ZodObject` carries the `.safeParse()` / `.partial()` the CRUD layer calls; `buildCollection`
- *  casts the builder results to it. */
-export type CollectionSchema = z.ZodObject<z.ZodRawShape>
-
-export interface ConditionIssue {
-  path: (string | number)[]
-  message: string
-}
-
-export interface BuiltCollection {
-  name: string
-  def: CollectionDef
-  table: SQLiteTable
-  insert: CollectionSchema
-  update: CollectionSchema
-  select: CollectionSchema
-  /** Every pre-write check the per-field schema can't do because it sees one field at a time: `required`
-   *  re-enforced for conditional fields whose condition is met against the whole record, plus the
-   *  collection's own `def.validate`. Returns Zod-shaped issues keyed by the field's def name. Present
-   *  only when the collection has conditional required fields or a `validate`. */
-  applyConditions?: (record: Record<string, unknown>) => { issues: ConditionIssue[] }
-}