@michaelthielemann/kestrel 3.0.1 → 4.0.0

package/layers/core/server/api/[collection]/translations.get.test.ts

@@ -1,90 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
-import { createError } from 'h3'
-import Database from 'better-sqlite3'
-import { drizzle } from 'drizzle-orm/better-sqlite3'
-import { buildCollection } from '../../../../fields/server/utils/buildCollection'
-import { defineCollection } from '../../utils/defineCollection'
-import { create, resolveTranslations } from '../../utils/crud'
-import { requireCollection } from '../../utils/http'
-import { clearRegistry, registerCollection } from '../../utils/registry'
-import { desiredSchema } from '../../schema/desired'
-import { diffSchema } from '../../schema/diff'
-import { renderSqlite } from '../../schema/render-sqlite'
-
-const pages = buildCollection(defineCollection({
-  name: 'pages', mode: 'multi', translatable: true, pageLike: true,
-  fields: { title: { type: 'text', required: true } },
-}))
-const notes = buildCollection(defineCollection({
-  name: 'notes', mode: 'multi', translatable: false,
-  fields: { title: { type: 'text', required: true } },
-}))
-
-// `context.params` is where Nitro puts the route params the real `requireCollection` reads via h3.
-interface FakeEvent { query: Record<string, unknown>; context: { params: Record<string, string> } }
-
-let db: ReturnType<typeof drizzle>
-
-// The handler is a Nitro route: its auto-imported helpers are plain globals in a node test — bound to the
-// REAL implementations so nothing here can pass against a stub the server does not have.
-Object.assign(globalThis, {
-  defineEventHandler: (handler: unknown) => handler,
-  createError,
-  getQuery: (event: FakeEvent) => event.query,
-  useDb: () => db,
-  requireCollection,
-  resolveTranslations,
-})
-
-// Calling the handler directly says nothing about the path ever reaching it: that the literal `translations`
-// segment wins over the sibling `[id]` route is only provable on a real server → `test/e2e/api.test.ts`.
-const handler = (await import('./translations.get')).default as unknown as (event: FakeEvent) => Record<string, number | null>
-const get = (collection: string, query: Record<string, unknown>) => handler({ query, context: { params: { collection } } })
-
-beforeEach(() => {
-  const sqlite = new Database(':memory:')
-  for (const stmt of renderSqlite(diffSchema(desiredSchema([pages.table, notes.table]), {}))) sqlite.exec(stmt)
-  db = drizzle(sqlite)
-  clearRegistry()
-  registerCollection(pages)
-  registerCollection(notes)
-})
-afterEach(() => clearRegistry())
-
-describe('GET /api/{collection}/translations?group=', () => {
-  it('resolves the group\'s locale → sibling id map without a record id', () => {
-    const en = create(db, pages, { title: 'Home' }) as Record<string, unknown>
-    const de = create(db, pages, { title: 'Start', locale: 'de', translationGroup: en.translationGroup as string }) as Record<string, unknown>
-    expect(get('pages', { group: en.translationGroup })).toEqual({ en: en.id, de: de.id })
-  })
-
-  it('reports a locale with no sibling as null (what the "+ create" affordance keys off)', () => {
-    const en = create(db, pages, { title: 'Only EN' }) as Record<string, unknown>
-    expect(get('pages', { group: en.translationGroup })).toEqual({ en: en.id, de: null })
-  })
-
-  it('returns exactly the per-record map for the same group (one map builder, two entry points)', () => {
-    const en = create(db, pages, { title: 'Home' }) as Record<string, unknown>
-    create(db, pages, { title: 'Start', locale: 'de', translationGroup: en.translationGroup as string })
-    expect(get('pages', { group: en.translationGroup })).toEqual(resolveTranslations(db, pages, en.id as number))
-  })
-
-  it('400s without a group rather than answering for an arbitrary one', () => {
-    expect(() => get('pages', {})).toThrowError(expect.objectContaining({ statusCode: 400 }))
-    expect(() => get('pages', { group: '  ' })).toThrowError(expect.objectContaining({ statusCode: 400 }))
-  })
-
-  it('404s for a group that has no rows', () => {
-    create(db, pages, { title: 'Home' })
-    expect(() => get('pages', { group: 'nope' })).toThrowError(expect.objectContaining({ statusCode: 404 }))
-  })
-
-  it('400s (never 500s) for a collection without translations — it has no group column at all', () => {
-    create(db, notes, { title: 'Note' })
-    expect(() => get('notes', { group: 'g1' })).toThrowError(/Translations are not enabled/)
-  })
-
-  it('404s for an unknown collection', () => {
-    expect(() => get('nope', { group: 'g1' })).toThrowError(expect.objectContaining({ statusCode: 404 }))
-  })
-})

package/layers/core/server/api/[collection]/translations.get.ts

@@ -1,25 +0,0 @@
-import { eq, getTableColumns } from 'drizzle-orm'
-import type { AnySQLiteColumn } from 'drizzle-orm/sqlite-core'
-
-// The sibling map keyed by translation GROUP — the twin of `/:id/translations` for the editor of a record
-// that does not exist yet (`/admin/pages/new?locale=de&group=…`), which knows its group but has no id. It
-// resolves one member of the group and hands off to the per-id map builder, so both entry points can never
-// answer differently. The literal `translations` segment beats the dynamic `[id]` route (as `options.get.ts`
-// already relies on). Admin-only: `resourceForPath` maps it to the `<collection>/translations` resource, the
-// same gate as the per-record route (the map enumerates draft ids).
-export default defineEventHandler((event) => {
-  const collection = requireCollection(event)
-  // Checked here, not left to resolveTranslations: a collection without translations has no
-  // translationGroup column, so the member lookup below would blow up on an undefined column.
-  if (collection.def.mode === 'single' || !collection.def.translatable) {
-    throw createError({ statusCode: 400, statusMessage: 'Translations are not enabled for this collection' })
-  }
-  const group = String(getQuery(event).group ?? '').trim()
-  if (!group) throw createError({ statusCode: 400, statusMessage: 'A translation group is required' })
-
-  const db = useDb()
-  const cols = getTableColumns(collection.table) as Record<string, AnySQLiteColumn>
-  const member = db.select({ id: cols.id }).from(collection.table).where(eq(cols.translationGroup, group)).get() as { id: number } | undefined
-  if (!member) throw createError({ statusCode: 404, statusMessage: `Unknown translation group: ${group}` })
-  return resolveTranslations(db, collection, member.id)
-})

package/layers/core/server/api/collections/[name].get.ts

@@ -1,4 +0,0 @@
-export default defineEventHandler((event) => {
-  const collection = getCollectionOr404(getRouterParam(event, 'name') as string)
-  return serializeCollection(collection.def)
-})

package/layers/core/server/api/collections/index.get.ts

@@ -1,3 +0,0 @@
-export default defineEventHandler(() => {
-  return { data: allCollections().map((c) => serializeCollection(c.def)) }
-})

package/layers/core/server/api/references/broken.get.ts

@@ -1,9 +0,0 @@
-// Every reference in the index whose target is currently deleted or unpublished — the global broken-
-// references report. Admin-only (the `references` resource is not in the public set). Derived on read.
-// A `null` scan means the index itself could not be read (e.g. record_refs not migrated yet); answering
-// `[]` there would report a verified-clean site when nothing was actually checked.
-export default defineEventHandler(() => {
-  const rows = findBrokenRefs(useDb())
-  if (rows === null) throw createError({ statusCode: 503, statusMessage: 'Reference index unavailable' })
-  return rows
-})

package/layers/core/server/api/references/referrers.get.ts

@@ -1,24 +0,0 @@
-import { MAX_BULK_IDS } from '../../../app/utils/list-limits'
-
-// The distinct records that reference a given target — the reverse "what links here" lookup. Admin-only
-// (the `references` resource is not in the public set). Powers the editor's pre-delete referrer warning.
-// Two arms:
-//   ?collection=X&id=1        -> FieldRef[]                    (single target; the editor's warning)
-//   ?collection=X&ids=1,2,3   -> { counts: Record<id, count>, checked: boolean }  (a selection; the bulk-delete warning)
-// `checked` is false when the lookup itself failed (e.g. record_refs not migrated yet) — an empty `counts`
-// then means "could not check", NOT "no referrers", so a caller must not read it as a green light to delete.
-export default defineEventHandler((event) => {
-  const q = getQuery(event)
-  const collection = String(q.collection ?? '')
-  if (q.ids != null) {
-    if (!collection) throw createError({ statusCode: 400, statusMessage: 'collection and ids query params are required' })
-    const ids = parseIdList(q.ids, MAX_BULK_IDS)
-    const counts = findReferrersForMany(useDb(), collection, ids)
-    return { counts: counts ?? {}, checked: counts !== null }
-  }
-  const id = Number(q.id)
-  if (!collection || !Number.isInteger(id) || id <= 0) {
-    throw createError({ statusCode: 400, statusMessage: 'collection and id query params are required' })
-  }
-  return findReferrers(useDb(), collection, id) ?? []
-})

package/layers/core/server/database/record-refs.ts

@@ -1,20 +0,0 @@
-import { sqliteTable, integer, text, index } from 'drizzle-orm/sqlite-core'
-
-// Durable reference index: one row per `(source record) → (target record)` edge, over ALL reference
-// types (relation / media / internal link / richtext links / link fields). Maintained on every content
-// write (see `maintainRecordRefs`) and queried on read to DERIVE stale-reference warnings — never stores
-// a warning message (a stored "X deleted" goes stale when X is restored). A non-collection system table,
-// so it lives here (not `server/collections`, which would wire it into the CRUD API/admin). Indexed both
-// forward (what a record references) and reverse (what references a record). `createdAt` via `$defaultFn`
-// (no SQL default → it won't perpetually diff as a rebuild).
-export const recordRefs = sqliteTable('record_refs', {
-  id: integer('id').primaryKey({ autoIncrement: true }),
-  sourceColl: text('source_coll').notNull(),
-  sourceId: integer('source_id').notNull(),
-  targetColl: text('target_coll').notNull(),
-  targetId: integer('target_id').notNull(),
-  createdAt: integer('created_at', { mode: 'timestamp' }).notNull().$defaultFn(() => new Date()),
-}, (t) => [
-  index('record_refs_source').on(t.sourceColl, t.sourceId),
-  index('record_refs_target').on(t.targetColl, t.targetId),
-])

package/layers/core/server/plugins/03.record-refs.ts

@@ -1,12 +0,0 @@
-import { registerWriteListener } from '../utils/write-events'
-import { maintainRecordRefs } from '../utils/record-ref-index'
-
-/**
- * Keep the durable `record_refs` index current on every content write — in ALL environments (the dead-
- * reference warnings it powers are an editor feature, not gated on publishing, so unlike the publish
- * plugin this is never skipped in dev). Its own listener, so it coexists with the publish listener; the
- * bus try/catch-isolates each, so an index-maintenance failure never breaks the content write.
- */
-export default defineNitroPlugin(() => {
-  registerWriteListener((event) => maintainRecordRefs(useDb(), event))
-})

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

@@ -1,41 +0,0 @@
-import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
-import type { BuiltCollection } from '../utils/collection-types'
-import type { CollectionDef } from '../utils/defineCollection'
-import { ensureBuilt } from '../../../fields/server/utils/buildCollection'
-import { recordRefs } from '../database/record-refs'
-import { desiredSchema } from './desired'
-import type { SchemaSnapshot } from './model'
-
-/** The ONE rule for whether a discovered collection is active: built-ins (`pages`, `media`, …) can be
- *  disabled per consumer via `kestrel: { collections: { <name>: false } }`. Shared by the registry
- *  plugin AND the schema engine, so the runtime surface and the desired schema can never diverge —
- *  a disabled built-in neither registers routes nor keeps (or creates) its table. */
-export function collectionEnabled(def: CollectionDef, toggles?: Record<string, boolean>): boolean {
-  return !(def.builtin && toggles?.[def.name] === false)
-}
-
-export interface DesiredOptions {
-  /** Built-in collection toggles (see `collectionEnabled`). Omitted → everything discovered is desired. */
-  toggles?: Record<string, boolean>
-  /** Standalone (non-collection) tables owned by upper layers — discovered via `#kestrel/schema-tables`
-   *  (each layer's `server/schema-tables/*.ts` default-exports one table) and passed in by the Nitro
-   *  callers, so core hardcodes no upper-layer schema. `record_refs` is core-owned and always included. */
-  extraTables?: AnySQLiteTable[]
-}
-
-/**
- * The desired DB schema for the discovered collections (the `#kestrel/collections` virtual, passed in
- * so this stays pure and unit-testable): every ENABLED collection's table plus core's `record_refs` and
- * the callers' discovered standalone tables. The single definition of "what the live DB should look
- * like", shared by the dev auto-sync plugin (02.schema-sync) and the `db:migrate` task so the two can
- * never disagree on the target schema. Discovered files may default-export a plain def (consumer form)
- * or an already-built collection.
- */
-export function desiredFromCollections(
-  collections: (CollectionDef | BuiltCollection)[],
-  opts: DesiredOptions = {},
-): SchemaSnapshot {
-  const built = collections.map(ensureBuilt).filter((c) => collectionEnabled(c.def, opts.toggles))
-  const tables = [...built.map((c) => c.table), recordRefs, ...(opts.extraTables ?? [])]
-  return desiredSchema(tables, new Map(built.map((c) => [c.def.name, c.def])))
-}

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

@@ -1,99 +0,0 @@
-import { getTableConfig, SQLiteSyncDialect, type SQLiteTable } from 'drizzle-orm/sqlite-core'
-import { SQL, is } from 'drizzle-orm'
-import { resolveColumnName, toSnakeCase } from '../../../fields/server/field-registry/naming'
-import type { CollectionDef } from '../utils/defineCollection'
-import { fieldIs } from '../utils/defineCollection'
-import type { ColumnShape, IndexShape, TableShape, SchemaSnapshot } from './model'
-
-// Build the *desired* schema snapshot from the Drizzle tables that collections compile to (the
-// counterpart to introspect's *actual* snapshot). Reads drizzle's table metadata via getTableConfig and
-// normalizes it into the same model `diffSchema` consumes (ADR-0002).
-
-const dialect = new SQLiteSyncDialect()
-const sqlText = (value: SQL) => dialect.sqlToQuery(value).sql
-
-/** Map a Drizzle column default to its raw DDL token: a `sql\`…\`` default renders verbatim, a JS literal is quoted. */
-export function defaultToken(value: unknown): string | null {
-  if (value === undefined || value === null) return null
-  if (is(value, SQL)) return sqlText(value)
-  if (typeof value === 'string') return `'${value.replace(/'/g, "''")}'`
-  if (typeof value === 'boolean') return value ? '1' : '0'
-  // Object / array default (a json-backed column — e.g. a custom field type): emit a quoted JSON string
-  // literal, matching how json/repeater columns default via sql`'{}'`. Else String({}) → "[object Object]".
-  if (typeof value === 'object') return `'${JSON.stringify(value).replace(/'/g, "''")}'`
-  return String(value)
-}
-
-export function desiredTable(table: SQLiteTable, def?: CollectionDef): TableShape {
-  const cfg = getTableConfig(table)
-
-  // new column name -> old column name (and any single↔multiple shape transform). Two sources:
-  //  - an explicit `renamedFrom` field hint (same field type → same naming rule for both keys);
-  //  - a relation/media field, which maps to its opposite-multiplicity column name (`<col>` ↔ `<col>_id`)
-  //    so toggling `multiple`/`many` renames + reshapes the data instead of dropping it. Inert unless the
-  //    opposite column actually exists in the live DB.
-  const renames = new Map<string, string>()
-  const transforms = new Map<string, 'wrap' | 'unwrap'>()
-  if (def) {
-    for (const [key, field] of Object.entries(def.fields)) {
-      if (field.renamedFrom) {
-        renames.set(resolveColumnName(key, field).dbName, resolveColumnName(field.renamedFrom, field).dbName)
-        continue
-      }
-      if (fieldIs(field, 'media') || fieldIs(field, 'relation')) {
-        const multiple = fieldIs(field, 'media') ? field.options?.multiple === true : field.relation.many === true
-        const base = toSnakeCase(key)
-        const col = multiple ? base : `${base}_id`
-        renames.set(col, multiple ? `${base}_id` : base)
-        transforms.set(col, multiple ? 'wrap' : 'unwrap')
-      }
-    }
-  }
-
-  const columns: ColumnShape[] = cfg.columns.map((c) => ({
-    name: c.name,
-    type: c.getSQLType(),
-    notNull: c.notNull,
-    primaryKey: c.primary,
-    autoIncrement: (c as unknown as { autoIncrement?: boolean }).autoIncrement === true,
-    default: defaultToken(c.default),
-    ...(renames.has(c.name) ? { renamedFrom: renames.get(c.name) } : {}),
-    ...(transforms.has(c.name) ? { renameTransform: transforms.get(c.name) } : {}),
-  }))
-
-  const indexes: IndexShape[] = cfg.indexes.map((i) => {
-    const cfgI = i.config as unknown as { name: string; unique: boolean; columns: { name: string }[]; where?: SQL }
-    return {
-      name: cfgI.name,
-      table: cfg.name,
-      columns: cfgI.columns.map((x) => x.name),
-      unique: cfgI.unique,
-      where: cfgI.where ? sqlText(cfgI.where) : null,
-    }
-  })
-
-  // A column-level `.unique()` is materialized by drizzle-kit as a named unique index
-  // (`<table>_<column>_unique`) — surface it the same way so introspect's view and ours agree.
-  for (const c of cfg.columns) {
-    const u = c as unknown as { isUnique?: boolean; uniqueName?: string }
-    if (u.isUnique) {
-      indexes.push({ name: u.uniqueName ?? `${cfg.name}_${c.name}_unique`, table: cfg.name, columns: [c.name], unique: true, where: null })
-    }
-  }
-
-  return { name: cfg.name, columns, indexes }
-}
-
-/**
- * Build a full desired snapshot from a set of Drizzle tables (registered collections + standalone tables).
- * `defsByName` supplies each collection's def so `renamedFrom` field hints become column renames; tables
- * without a def (e.g. `folders`) simply carry no renames.
- */
-export function desiredSchema(tables: SQLiteTable[], defsByName?: Map<string, CollectionDef>): SchemaSnapshot {
-  const snapshot: SchemaSnapshot = {}
-  for (const table of tables) {
-    const shape = desiredTable(table, defsByName?.get(getTableConfig(table).name))
-    snapshot[shape.name] = shape
-  }
-  return snapshot
-}

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

@@ -1,23 +0,0 @@
-import { syncSchema, describeOp, type SyncDb } from './sync'
-import { sqlite, type Dialect } from './dialect'
-import type { SchemaSnapshot } from './model'
-
-/**
- * The body of the dev-only schema auto-sync plugin, isolated so a failure can NEVER take down the whole
- * server. syncSchema throws by design on an infeasible migration (and on any transient DDL error); if
- * that escaped the Nitro plugin it would 500 every route — including the admin UI needed to diagnose it.
- * Here we log loudly and let the server keep running on the previous schema. The operator-triggered
- * db:migrate task is one-shot and keeps failing hard; only this always-on plugin must isolate.
- */
-export function runDevSchemaSync(client: SyncDb, desired: SchemaSnapshot, dialect: Dialect = sqlite): void {
-  try {
-    const { applied, skipped } = syncSchema(client, desired, {}, dialect)
-    if (applied.length) console.info(`[kestrel] dev schema auto-sync applied ${applied.length} statement(s)`)
-    // Destructive changes are never auto-applied — name them so the data loss is visible before opting in.
-    if (skipped.length) {
-      console.warn(`[kestrel] ${skipped.length} destructive schema change(s) detected — not auto-applied:\n  - ${skipped.map(describeOp).join('\n  - ')}\n  apply with the db:migrate task ({ force: true }) — dev: GET /_nitro/tasks/db:migrate, prod: runTask('db:migrate', { payload: { force: true } })`)
-    }
-  } catch (err) {
-    console.error('[kestrel] dev schema auto-sync FAILED — the server keeps running on the PREVIOUS schema; fix the collection or its data and restart:\n ', err instanceof Error ? err.message : err)
-  }
-}

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

@@ -1,61 +0,0 @@
-import type { SchemaSnapshot, SchemaOp } from './model'
-import type { IntrospectDb } from './introspect'
-import { introspect } from './introspect'
-import { renderSqlite } from './render-sqlite'
-
-// The dialect seam (ADR-0002). `model.ts` + `diffSchema` are dialect-agnostic: a diff is computed as a
-// `SchemaOp[]` over the normalized model, independent of any database. A `Dialect` is what binds that
-// core to a concrete backend — it knows how to read the backend's live schema back into the model
-// (`introspect`), how to turn ops into the backend's DDL (`render`), and how to quote an identifier.
-// `sync.ts` is threaded with a Dialect (defaulting to `sqlite`), so DDL rendering, introspection and
-// identifier quoting are swappable without touching the diff. The seam stops there: `diff.ts` emits
-// `rebuild_table` because SQLite has no ALTER/DROP COLUMN, and sync's pre-flight feasibility probes are
-// SQLite SQL (`PRAGMA table_info`, `json_extract`) — a second backend needs both adjusted alongside its
-// new Dialect. SQLite is the only implementation today; `postgres` is a reserved, fail-loud slot.
-export interface Dialect {
-  /** Stable identifier, e.g. `sqlite` | `postgres`. */
-  readonly name: string
-  /** Read the live database's actual schema into the normalized model, for `diffSchema` to compare. */
-  introspect(db: IntrospectDb): SchemaSnapshot
-  /** Render structured ops into this backend's DDL statements, preserving the apply-safe order. */
-  render(ops: SchemaOp[]): string[]
-  /** Quote an identifier for this backend (backticks for SQLite, double-quotes for Postgres). */
-  quote(id: string): string
-}
-
-/** The SQLite dialect: the current engine, now behind the seam. `render`/`introspect` are the existing
- *  pure functions; `quote` is SQLite's backtick quoting (matching `render-sqlite`'s own internal escape). */
-export const sqlite: Dialect = {
-  name: 'sqlite',
-  introspect,
-  render: renderSqlite,
-  quote: (id) => `\`${id.replace(/`/g, '``')}\``,
-}
-
-const pgNotImplemented = (op: string) =>
-  new Error(
-    `kestrel: the postgres dialect is not implemented yet (Dialect.${op}). It is a reserved slot ` +
-      `(ADR-0002) — a Postgres backend needs its own DDL renderer (real ALTER/DROP COLUMN, not SQLite's ` +
-      `table rebuild), information_schema introspection, and a pg-typed desired snapshot. Use \`sqlite\`.`,
-  )
-
-/** Reserved Postgres slot. Every substantive entry point fails loud so a misconfiguration can never
- *  silently fall back to emitting SQLite DDL against a non-SQLite database. `quote` is the one piece that
- *  is trivially correct (standard double-quote escaping), so it is implemented rather than thrown. */
-export const postgres: Dialect = {
-  name: 'postgres',
-  introspect() { throw pgNotImplemented('introspect') },
-  render() { throw pgNotImplemented('render') },
-  quote: (id) => `"${id.replace(/"/g, '""')}"`,
-}
-
-const dialects: Record<string, Dialect> = { sqlite, postgres }
-
-/** Resolve a dialect by name (the config-driven selection point for the migration engine). Throws a
- *  clear error naming the supported dialects rather than silently defaulting, so a typo'd or unsupported
- *  backend fails at startup instead of mis-migrating. */
-export function resolveDialect(name: string): Dialect {
-  const d = dialects[name]
-  if (!d) throw new Error(`kestrel: unknown database dialect "${name}" — supported: ${Object.keys(dialects).join(', ')}`)
-  return d
-}

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

@@ -1,110 +0,0 @@
-import type { SchemaSnapshot, SchemaOp, IndexShape, ColumnShape } from './model'
-
-/** Two indexes are equivalent when uniqueness, partial predicate, and ordered columns all match. */
-function sameIndex(a: IndexShape, b: IndexShape): boolean {
-  return a.unique === b.unique
-    && a.where === b.where
-    && a.columns.length === b.columns.length
-    && a.columns.every((c, i) => c === b.columns[i])
-}
-
-/** A column's definition drifted (same name, different shape) — only fixable by a table rebuild in SQLite. */
-function columnDiffers(a: ColumnShape, b: ColumnShape): boolean {
-  return a.type !== b.type || a.notNull !== b.notNull || a.primaryKey !== b.primaryKey
-    || a.autoIncrement !== b.autoIncrement || a.default !== b.default
-}
-
-/**
- * Schema diff (ADR-0002). Additive changes (create table/column/index, drop_index) are always emitted.
- * Destructive changes are emitted too but kept distinct: a table only in `actual` becomes `drop_table`;
- * a table whose columns were dropped or whose definitions drifted becomes a `rebuild_table` (SQLite has
- * no in-place ALTER COLUMN). A table needing a rebuild takes the rebuild path WHOLE — its added columns
- * and indexes are recreated by the rebuild, not emitted separately.
- *
- * Returned in an apply-safe order: additive first (create_table → add_column → drop_index →
- * create_index), destructive last (rebuild_table → drop_table). The additive/destructive split lets the
- * apply layer gate destructive ops behind an explicit opt-in (see `isDestructive`).
- */
-export function diffSchema(desired: SchemaSnapshot, actual: SchemaSnapshot): SchemaOp[] {
-  const createTables: SchemaOp[] = []
-  const renames: SchemaOp[] = []
-  const addColumns: SchemaOp[] = []
-  const dropIndexes: SchemaOp[] = []
-  const createIndexes: SchemaOp[] = []
-  const rebuilds: SchemaOp[] = []
-  const dropTables: SchemaOp[] = []
-
-  for (const name of Object.keys(desired)) {
-    const want = desired[name]
-    const have = actual[name]
-
-    if (!have) {
-      createTables.push({ type: 'create_table', table: want })
-      for (const index of want.indexes) createIndexes.push({ type: 'create_index', index })
-      continue
-    }
-
-    const haveByName = new Map(have.columns.map((c) => [c.name, c]))
-    const wantNames = new Set(want.columns.map((c) => c.name))
-
-    // Resolve renames: a desired column whose `renamedFrom` exists in actual while its own name does not.
-    // `rename_column` is additive and ordered before any rebuild, so the rest of the diff can treat the
-    // column as already present under its NEW name (the "effective" actual view).
-    const renameMap = new Map<string, string>() // newName -> oldName
-    const transformMap = new Map<string, { from: string; type: 'wrap' | 'unwrap' }>() // single↔multiple toggles
-    for (const c of want.columns) {
-      if (c.renamedFrom && haveByName.has(c.renamedFrom) && !haveByName.has(c.name)) {
-        renameMap.set(c.name, c.renamedFrom)
-        if (c.renameTransform) transformMap.set(c.name, { from: c.renamedFrom, type: c.renameTransform })
-      }
-    }
-    const renamedOld = new Set(renameMap.values())
-    // A name vacated by a rename (renamedOld) reads as absent unless something else renamed INTO it —
-    // otherwise a field re-using a just-freed name is mistaken for the column that just moved away.
-    const effectiveHas = (n: string) => (haveByName.has(n) && !renamedOld.has(n)) || renameMap.has(n)
-    const actualColOf = (n: string) => (renameMap.has(n) || !renamedOld.has(n)) ? haveByName.get(renameMap.get(n) ?? n) : undefined
-
-    const dropped = have.columns.some((c) => !wantNames.has(c.name) && !renamedOld.has(c.name))
-    const changed = want.columns.some((c) => { const a = actualColOf(c.name); return a !== undefined && columnDiffers(a, c) })
-
-    // Plain renames are an in-place ALTER RENAME; a single↔multiple toggle reshapes the data, so it is
-    // handled by the rebuild's transformed copy below (NO rename_column for those).
-    for (const [to, from] of renameMap) {
-      if (!transformMap.has(to)) renames.push({ type: 'rename_column', table: name, from, to })
-    }
-
-    if (dropped || changed || transformMap.size > 0) {
-      // Rebuild recreates the table at `want`, copying columns present in both (by effective/new name —
-      // plain renames already ran). A toggled column is copied from its old, differently-named source via
-      // a shape transform. Columns dropped without a rename hint are not copied: the data loss line.
-      const copy = want.columns.filter((c) => effectiveHas(c.name)).map((c) => c.name)
-      const transforms = Object.fromEntries(copy.filter((c) => transformMap.has(c)).map((c) => [c, transformMap.get(c)!]))
-      rebuilds.push({ type: 'rebuild_table', table: want, copy, ...(Object.keys(transforms).length ? { transforms } : {}) })
-      continue
-    }
-
-    // Purely additive for this table (renames already queued above).
-    for (const column of want.columns) {
-      if (!effectiveHas(column.name)) addColumns.push({ type: 'add_column', table: name, column })
-    }
-    const haveIdx = new Map(have.indexes.map((i) => [i.name, i]))
-    const wantIdx = new Map(want.indexes.map((i) => [i.name, i]))
-    for (const index of want.indexes) {
-      const existing = haveIdx.get(index.name)
-      if (!existing) { createIndexes.push({ type: 'create_index', index }); continue }
-      if (!sameIndex(existing, index)) {
-        dropIndexes.push({ type: 'drop_index', index: existing })
-        createIndexes.push({ type: 'create_index', index })
-      }
-    }
-    for (const index of have.indexes) {
-      if (!wantIdx.has(index.name)) dropIndexes.push({ type: 'drop_index', index })
-    }
-  }
-
-  for (const name of Object.keys(actual)) {
-    if (!desired[name]) dropTables.push({ type: 'drop_table', name })
-  }
-
-  return [...createTables, ...renames, ...addColumns, ...dropIndexes, ...createIndexes, ...rebuilds, ...dropTables]
-}

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

@@ -1,68 +0,0 @@
-import type { ColumnShape, IndexShape, SchemaSnapshot } from './model'
-
-// Read the *actual* schema of a live SQLite database into the normalized model, so `diffSchema` can
-// compare it against the desired schema (ADR-0002). Typed structurally (prepare + pragma) to keep the
-// native module out of this file — but the shape is narrower than better-sqlite3's own (which types
-// `pragma` as returning `unknown`), so a real connection only reaches these entry points through a cast.
-
-interface Row { [key: string]: unknown }
-export interface IntrospectDb {
-  prepare(sql: string): { all(...params: unknown[]): Row[] }
-  pragma(source: string): Row[]
-}
-
-/** Double-quote an identifier for a PRAGMA argument (names come from sqlite_master, but quote defensively). */
-const dq = (id: string) => `"${id.replace(/"/g, '""')}"`
-
-export function introspect(db: IntrospectDb): SchemaSnapshot {
-  // Exclude sqlite internals, the drizzle migrations ledger, and any `__kestrel_new_*` rebuild temp
-  // table left by an interrupted rebuild — so an orphan is never mistaken for a real (droppable) table.
-  const tables = db.prepare(
-    "SELECT name, sql FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__kestrel_new_%' AND name <> '__drizzle_migrations'",
-  ).all() as { name: string; sql: string | null }[]
-
-  const snapshot: SchemaSnapshot = {}
-  for (const { name, sql } of tables) {
-    snapshot[name] = { name, columns: columnsOf(db, name, sql ?? ''), indexes: indexesOf(db, name) }
-  }
-  return snapshot
-}
-
-function columnsOf(db: IntrospectDb, table: string, tableSql: string): ColumnShape[] {
-  // PRAGMA exposes no AUTOINCREMENT flag — it only ever applies to the INTEGER PRIMARY KEY, so detect
-  // it from the table's stored CREATE statement.
-  const hasAutoInc = /\bAUTOINCREMENT\b/i.test(tableSql)
-  const rows = db.pragma(`table_info(${dq(table)})`) as
-    { name: string; type: string; notnull: number; dflt_value: unknown; pk: number }[]
-  return rows.map((r) => ({
-    name: r.name,
-    type: r.type.toLowerCase(),
-    notNull: r.notnull === 1,
-    primaryKey: r.pk > 0,
-    autoIncrement: r.pk > 0 && hasAutoInc,
-    default: r.dflt_value == null ? null : String(r.dflt_value),
-  }))
-}
-
-function indexesOf(db: IntrospectDb, table: string): IndexShape[] {
-  const uniqueByName = new Map(
-    (db.pragma(`index_list(${dq(table)})`) as { name: string; unique: number }[]).map((m) => [m.name, m.unique === 1]),
-  )
-  // Only explicitly-created indexes carry a non-null `sql`; auto-indexes from UNIQUE/PK constraints are
-  // null-sql and excluded (they mirror column constraints, not declared indexes).
-  const rows = db.prepare(
-    "SELECT name, sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL",
-  ).all(table) as { name: string; sql: string }[]
-
-  return rows.map(({ name, sql }) => {
-    const columns = (db.pragma(`index_info(${dq(name)})`) as { name: string }[]).map((c) => c.name)
-    const where = sql.match(/\bWHERE\b\s+(.+)$/is)
-    return {
-      name,
-      table,
-      columns,
-      unique: uniqueByName.get(name) ?? /\bCREATE\s+UNIQUE\b/i.test(sql),
-      where: where ? where[1].trim() : null,
-    }
-  })
-}