@michaelthielemann/kestrel 3.0.1 → 4.0.0

package/layers/fields/server/utils/block-populate.ts

@@ -1,41 +0,0 @@
-import type { FieldDef } from '../../../core/server/utils/defineCollection'
-import { getBlock } from './defineBlock'
-
-/** A per-block-props mutation: populate/resolve one block's props in place, given its field defs. */
-export type ApplyBlockFields = (props: Record<string, unknown>, fields: Record<string, FieldDef>) => void
-
-/**
- * The shared block-content walker for server-side populators (media `$media`, internal-link resolution,
- * …). Maps a `content` array, deep-cloning each block node, applying `applyFields` to a clone of its
- * `props` (block type looked up via the registry), and recursing into every declared slot. The differing
- * per-field work lives in `applyFields`; only this clone-and-recurse traversal is shared. Returns a fresh
- * array (server populators hand back new rows); nodes that aren't block objects pass through untouched.
- */
-export function buildBlockPopulator(applyFields: ApplyBlockFields): (nodes: unknown) => unknown[] {
-  const walk = (nodes: unknown): unknown[] => {
-    if (!Array.isArray(nodes)) return []
-    return nodes.map((node) => {
-      if (!node || typeof node !== 'object') return node
-      const original = node as { type?: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
-      const cloned: Record<string, unknown> = { ...original }
-
-      const blockDef = original.type ? getBlock(original.type) : undefined
-      if (blockDef && original.props) {
-        const props: Record<string, unknown> = { ...original.props }
-        cloned.props = props
-        applyFields(props, blockDef.fields)
-      }
-
-      if (original.slots && typeof original.slots === 'object') {
-        const slots: Record<string, unknown> = {}
-        for (const [slotName, slotNodes] of Object.entries(original.slots)) {
-          slots[slotName] = walk(slotNodes)
-        }
-        cloned.slots = slots
-      }
-
-      return cloned
-    })
-  }
-  return walk
-}

package/layers/fields/server/utils/buildCollection.ts

@@ -1,90 +0,0 @@
-import { createInsertSchema, createUpdateSchema, createSelectSchema } from 'drizzle-zod'
-import { z } from 'zod'
-import type { ZodType } from 'zod'
-import type { CollectionDef } from '../../../core/server/utils/defineCollection'
-import type { BuiltCollection, CollectionSchema } from '../../../core/server/utils/collection-types'
-import { seoSchema } from '../../../core/server/utils/seo'
-import { evaluateCondition, isEmptyValue } from '../../app/utils/condition'
-import { buildTable } from './buildTable'
-import { buildFieldSchema } from './buildFieldSchema'
-import { resolveColumnName } from '../field-registry/naming'
-import { allBlocks, buildBlocksSchema } from './defineBlock'
-
-/** A page path is consumed verbatim at build time to derive prerender routes / output file paths,
- *  so it must be incapable of traversal: url-path-safe charset only, no `.`/`..` segments. */
-export function isSafePagePath(p: string): boolean {
-  if (!/^[A-Za-z0-9._~%/-]*$/.test(p)) return false
-  return !p.split('/').some((seg) => seg === '.' || seg === '..')
-}
-
-export function systemRefinements(def: CollectionDef): Record<string, unknown> {
-  const refine: Record<string, unknown> = {}
-  if (def.translatable) refine.locale = z.string().optional()
-  if (def.mode === 'single') refine.singletonKey = z.string().optional()
-  else if (def.translatable) refine.translationGroup = z.string().optional()
-  if (def.pageLike) refine.path = z.string().refine(isSafePagePath, 'Invalid path').nullable().optional()
-  // The status column is a two-state enum; without this the schema accepts any string and a typo
-  // ('publushed') stores verbatim and silently unpublishes the record (every gate matches only 'published').
-  if (def.status) refine.status = z.enum(['draft', 'published']).optional()
-  if (def.blocks?.enabled) refine.content = z.lazy(() => buildBlocksSchema(allBlocks(def.blocks?.allowed))).optional()
-  if (def.seo) refine.seo = seoSchema.partial().optional()
-  return refine
-}
-
-// Update is a partial PATCH: every field may be omitted, so the field refinements
-// must be optional on update (a required validator would otherwise override
-// drizzle-zod's partial column schema and force the field on every update).
-function optionalize(refine: Record<string, ZodType>): Record<string, ZodType> {
-  const out: Record<string, ZodType> = {}
-  for (const [key, schema] of Object.entries(refine)) out[key] = schema.optional()
-  return out
-}
-
-/**
- * Accept either a plain `CollectionDef` (the common consumer form: `export default defineCollection(…)`)
- * or an already-built collection (the advanced form, when a server route needs the drizzle table object
- * directly: `const built = buildCollection(…); export const t = built.table; export default built`).
- * The discriminator is the presence of `table`, which only a BuiltCollection has.
- */
-export function ensureBuilt(c: CollectionDef | BuiltCollection): BuiltCollection {
-  return 'table' in c ? c : buildCollection(c)
-}
-
-/**
- * Build the `applyConditions` hook — every pre-write check the per-field schema can't do — or `undefined`
- * when the collection needs none (so CRUD skips it). Two sources, both of which need the whole record:
- * the per-field schema relaxed every conditional field to optional (it can't see siblings), so `required`
- * is re-enforced here for the ones whose condition is met; and the collection's own `def.validate`, for a
- * rule spanning fields. Issues are keyed by the field's def name (so they map to the editor's per-field
- * errors), resolving each value at its column key (`<name>Id` for single relation/media).
- */
-function buildApplyConditions(def: CollectionDef): BuiltCollection['applyConditions'] {
-  const required = Object.entries(def.fields).filter(([, f]) => f.condition && f.required)
-  if (!required.length && !def.validate) return undefined
-  if (!required.length) return (record) => ({ issues: def.validate!(record) })
-  return (record) => {
-    const scope: Record<string, unknown> = {}
-    for (const [key, field] of Object.entries(def.fields)) scope[key] = record[resolveColumnName(key, field).jsKey]
-    const issues = required
-      .filter(([key, field]) => evaluateCondition(field.condition!, scope) && isEmptyValue(record[resolveColumnName(key, field).jsKey]))
-      .map(([key]) => ({ path: [key], message: 'This field is required.' }))
-    return { issues: [...issues, ...(def.validate?.(record) ?? [])] }
-  }
-}
-
-export function buildCollection(def: CollectionDef): BuiltCollection {
-  const table = buildTable(def)
-  const fieldRefine = buildFieldSchema(def.fields)
-  const system = systemRefinements(def)
-  return {
-    name: def.name,
-    def,
-    table,
-    // Cast through the loose `CollectionSchema`: drizzle-zod's overloads otherwise infer mismatched (ZodEnum)
-    // types that don't unify across the three builders (see CollectionSchema's note).
-    insert: createInsertSchema(table, { ...fieldRefine, ...system } as never) as unknown as CollectionSchema,
-    update: createUpdateSchema(table, { ...optionalize(fieldRefine), ...system } as never) as unknown as CollectionSchema,
-    select: createSelectSchema(table) as unknown as CollectionSchema,
-    applyConditions: buildApplyConditions(def),
-  }
-}

package/layers/fields/server/utils/buildFieldSchema.ts

@@ -1,22 +0,0 @@
-import type { ZodType } from 'zod'
-import type { FieldDef } from '../../../core/server/utils/defineCollection'
-import { getFieldType } from '../field-registry'
-import { resolveColumnName } from '../field-registry/naming'
-
-function buildShape(fields: Record<string, FieldDef>, keyOf: (key: string, field: FieldDef) => string): Record<string, ZodType> {
-  const out: Record<string, ZodType> = {}
-  for (const [key, field] of Object.entries(fields)) {
-    out[keyOf(key, field)] = getFieldType(field.type).validator(field)
-  }
-  return out
-}
-
-/** Collection columns: keyed by jsKey (matches buildTable's column keys). */
-export function buildFieldSchema(fields: Record<string, FieldDef>): Record<string, ZodType> {
-  return buildShape(fields, (key, field) => resolveColumnName(key, field).jsKey)
-}
-
-/** Block props: keyed by the raw field name (props are not DB columns). */
-export function buildFieldObjectSchema(fields: Record<string, FieldDef>): Record<string, ZodType> {
-  return buildShape(fields, (key) => key)
-}

package/layers/fields/server/utils/buildTable.ts

@@ -1,113 +0,0 @@
-import { sqliteTable, integer, text, uniqueIndex, index } from 'drizzle-orm/sqlite-core'
-import type { SQLiteColumnBuilderBase, SQLiteTable } from 'drizzle-orm/sqlite-core'
-import { sql } from 'drizzle-orm'
-import type { Block } from '../../../core/server/utils/blocks'
-import type { SeoMeta } from '../../../core/server/utils/seo'
-import type { CollectionDef } from '../../../core/server/utils/defineCollection'
-import { getFieldType, fieldCanEnforceUnique } from '../field-registry'
-import { resolveColumnName } from '../field-registry/naming'
-
-/** The system columns this def actually emits (jsKey + DB-name forms), gated by the SAME flags that add
- *  them in `buildTable` — so a field may only use e.g. `content`/`status` on a collection that doesn't
- *  enable blocks/status. A field resolving to one of these would silently overwrite a system column. */
-function reservedColumns(def: CollectionDef): { js: Set<string>; db: Set<string> } {
-  const js = new Set(['id', 'createdAt', 'updatedAt'])
-  const db = new Set(['id', 'created_at', 'updated_at'])
-  const add = (j: string, d: string) => { js.add(j); db.add(d) }
-  if (def.translatable) add('locale', 'locale')
-  if (def.mode === 'single') add('singletonKey', 'singleton_key')
-  else if (def.translatable) add('translationGroup', 'translation_group')
-  if (def.pageLike) { add('path', 'path'); add('layout', 'layout') }
-  if (def.status) add('status', 'status')
-  if (def.seo) add('seo', 'seo')
-  if (def.blocks?.enabled) add('content', 'content')
-  return { js, db }
-}
-
-function buildIndexes(def: CollectionDef, t: Record<string, never>) {
-  const out = []
-  const names = new Set<string>()
-  // System indexes are named first, so a colliding field index (below) is the one that fails loud —
-  // the fixed system naming scheme can't be the thing that has to change.
-  const system = (name: string) => { names.add(name); return name }
-  if (def.mode === 'single') {
-    out.push(def.translatable
-      ? uniqueIndex(system(`${def.name}_key_locale`)).on(t.singletonKey, t.locale)
-      : uniqueIndex(system(`${def.name}_key`)).on(t.singletonKey))
-  } else if (def.translatable) {
-    out.push(uniqueIndex(system(`${def.name}_group_locale`)).on(t.translationGroup, t.locale))
-    out.push(index(system(`${def.name}_group`)).on(t.translationGroup))
-  }
-  if (def.pageLike) {
-    out.push(def.translatable
-      ? uniqueIndex(system(`${def.name}_path_locale`)).on(t.path, t.locale).where(sql`path is not null`)
-      : uniqueIndex(system(`${def.name}_path`)).on(t.path).where(sql`path is not null`))
-  }
-  // Opt-in non-unique field indexes (`index: true`) — for columns that are frequently filtered/sorted but
-  // not unique (e.g. media.folder). `unique` fields already get an index from the field-type's `.unique()`.
-  // A name that collides with a system index (e.g. a field named "key" on a singleton) would otherwise mint
-  // TWO indexes of the same name — drizzle-kit's `syncSchema` then throws at DEPLOY time, not authoring
-  // time. Fail loud here instead, same style as the reserved-column / duplicate-column guards above.
-  for (const [key, field] of Object.entries(def.fields)) {
-    if (!field.index || field.unique) continue
-    const { jsKey, dbName } = resolveColumnName(key, field)
-    const name = `${def.name}_${dbName}`
-    if (names.has(name)) {
-      throw new Error(`kestrel: collection "${def.name}" field "${key}" produces the index name "${name}", which collides with a system index — rename the field.`)
-    }
-    names.add(name)
-    out.push(index(name).on(t[jsKey as keyof typeof t]))
-  }
-  return out
-}
-
-export function buildTable(def: CollectionDef): SQLiteTable {
-  const cols: Record<string, SQLiteColumnBuilderBase> = {}
-  cols.id = integer('id').primaryKey({ autoIncrement: true })
-  if (def.translatable) cols.locale = text('locale').notNull()
-  if (def.mode === 'single') cols.singletonKey = text('singleton_key').notNull()
-  else if (def.translatable) cols.translationGroup = text('translation_group').notNull()
-  if (def.pageLike) {
-    cols.path = text('path')
-    // Nullable with no default: an editor's "inherit" must be distinguishable from an explicit `default`,
-    // and the render decides the fallback (see resolvePageLayout) so a deleted layout file degrades in one
-    // place instead of being frozen into every row.
-    cols.layout = text('layout')
-  }
-  if (def.status) cols.status = text('status').notNull().default('draft')
-  if (def.seo) cols.seo = text('seo', { mode: 'json' }).$type<SeoMeta>().notNull().default(sql`'{}'`)
-  if (def.blocks?.enabled) cols.content = text('content', { mode: 'json' }).$type<Block[]>().notNull().default(sql`'[]'`)
-
-  const reserved = reservedColumns(def)
-  const seenJsKeys = new Set<string>()
-  const seenDbNames = new Set<string>()
-  for (const [key, field] of Object.entries(def.fields)) {
-    const { jsKey, dbName } = resolveColumnName(key, field)
-    // Fail loud (matching defineCollection's pageLike guard) rather than silently overwriting a system
-    // column — e.g. a field named `id`/`status` would clobber the PK / publish-gating column — or
-    // shadowing a sibling whose resolved key collides (a single-ref `foo` → `fooId` vs a literal `fooId`).
-    if (reserved.js.has(jsKey) || reserved.db.has(dbName)) {
-      throw new Error(`kestrel: collection "${def.name}" field "${key}" resolves to the reserved system column "${jsKey}" — rename the field.`)
-    }
-    if (seenJsKeys.has(jsKey) || seenDbNames.has(dbName)) {
-      throw new Error(`kestrel: collection "${def.name}" field "${key}" resolves to column "${jsKey}"/"${dbName}", which collides with another field — rename one of them.`)
-    }
-    // `unique` on a json/array-backed column (multi-choice, multi-media, many-relation, repeater, json) is
-    // a silent no-op — the column type never carries a DB constraint for it. Warn rather than throw: the
-    // flag is inert, so a definition that boots today must keep booting.
-    if (field.unique && !fieldCanEnforceUnique(field)) {
-      console.warn(`kestrel: collection "${def.name}" field "${key}" is "unique", but its storage (${field.type}, multi-valued) can never enforce a DB uniqueness constraint — the flag is ignored.`)
-    }
-    seenJsKeys.add(jsKey)
-    seenDbNames.add(dbName)
-    cols[jsKey] = getFieldType(field.type).column(dbName, field)
-  }
-
-  // `timestamp_ms` (not `timestamp`) keeps MILLISECOND precision: the optimistic-concurrency check compares
-  // `updatedAt` exactly, and second-granularity would let two saves in the same wall-clock second share a
-  // token — a stale tab could then silently revert a newer save. Same INTEGER column type, so no DDL change.
-  cols.createdAt = integer('created_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date())
-  cols.updatedAt = integer('updated_at', { mode: 'timestamp_ms' }).notNull().$defaultFn(() => new Date())
-
-  return sqliteTable(def.name, cols, (t) => buildIndexes(def, t as unknown as Record<string, never>))
-}

package/layers/fields/server/utils/conditional-required.ts

@@ -1,25 +0,0 @@
-import { z } from 'zod'
-import type { FieldDef } from '../../../core/server/utils/defineCollection'
-import { evaluateCondition, isEmptyValue } from '../../app/utils/condition'
-
-/**
- * Re-enforce `required` for conditional sub-fields whose condition is met, at the object level where their
- * sibling values are visible (a block's props, a repeater entry). The per-field validator relaxed a
- * `required + condition` field to optional (it can't see siblings), and the collection-level applyConditions
- * hook only walks TOP-LEVEL fields — so without this, a conditional-required prop inside a block or repeater
- * is a silent server no-op. Adds a superRefine that checks each such field against the parsed object; a no-op
- * (returns the schema unchanged) when the shape has no conditional-required fields.
- */
-export function refineConditionalRequired<T extends z.ZodTypeAny>(schema: T, fields: Record<string, FieldDef>): z.ZodTypeAny {
-  const conditional = Object.entries(fields).filter(([, f]) => f.condition && f.required)
-  if (!conditional.length) return schema
-  return schema.superRefine((val, ctx) => {
-    if (!val || typeof val !== 'object') return
-    const scope = val as Record<string, unknown>
-    for (const [key, field] of conditional) {
-      if (evaluateCondition(field.condition!, scope) && isEmptyValue(scope[key])) {
-        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [key], message: 'This field is required.' })
-      }
-    }
-  })
-}

package/layers/fields/server/utils/defineBlock.ts

@@ -1,86 +0,0 @@
-import { z } from 'zod'
-import type { ZodObject } from 'zod'
-import type { FieldDef, Localized } from '../../../core/server/utils/defineCollection'
-import { buildFieldObjectSchema } from './buildFieldSchema'
-import { refineConditionalRequired } from './conditional-required'
-
-export interface BlockDef {
-  name: string
-  fields: Record<string, FieldDef>
-  slots?: string[]
-  label?: Localized
-  /** Optional icon name for the admin block picker (e.g. a lucide name). Set via the SFC's `defineBlock`. */
-  icon?: string
-  /** Optional preview image (URL/path, e.g. '/block-previews/hero.png') shown above the name in the picker. */
-  image?: string
-}
-
-const blocks = new Map<string, BlockDef>()
-
-export function defineBlock(def: BlockDef): BlockDef {
-  return def
-}
-export function registerBlock(def: BlockDef): void {
-  blocks.set(def.name, def)
-}
-export function getBlock(name: string): BlockDef | undefined {
-  return blocks.get(name)
-}
-export function clearBlocks(): void {
-  blocks.clear()
-}
-export function allBlocks(allowed?: string[]): BlockDef[] {
-  const all = [...blocks.values()]
-  return allowed?.length ? all.filter((b) => allowed.includes(b.name)) : all
-}
-
-const MAX_BLOCK_DEPTH = 60
-const MAX_BLOCK_NODES = 10_000
-
-// Iterative (no recursion) traversal so the guard itself can't stack-overflow.
-function withinBlockBounds(value: unknown): boolean {
-  const stack: Array<{ v: unknown; depth: number }> = [{ v: value, depth: 0 }]
-  let nodes = 0
-  while (stack.length) {
-    const top = stack.pop() as { v: unknown; depth: number }
-    const { v, depth } = top
-    if (v === null || typeof v !== 'object') continue
-    if (depth > MAX_BLOCK_DEPTH) return false
-    if (++nodes > MAX_BLOCK_NODES) return false
-    if (Array.isArray(v)) {
-      for (const item of v) stack.push({ v: item, depth: depth + 1 })
-    } else {
-      for (const key of Object.keys(v as Record<string, unknown>)) {
-        stack.push({ v: (v as Record<string, unknown>)[key], depth: depth + 1 })
-      }
-    }
-  }
-  return true
-}
-
-export function buildBlocksSchema(blockDefs: BlockDef[]): z.ZodType {
-  const node: z.ZodType = blockDefs.length
-    ? z.lazy(() =>
-        z.discriminatedUnion(
-          'type',
-          blockDefs.map((b) =>
-            z.object({
-              id: z.string().min(1),
-              type: z.literal(b.name),
-              props: refineConditionalRequired(z.object(buildFieldObjectSchema(b.fields)), b.fields),
-              slots: b.slots?.length
-                ? z.object(Object.fromEntries(b.slots.map((s) => [s, z.array(node)]))).partial().optional()
-                : z.undefined().optional(),
-            }),
-          ) as unknown as [ZodObject, ...ZodObject[]],
-        ),
-      )
-    : z.never()
-  return z.unknown()
-    .superRefine((val, ctx) => {
-      if (!withinBlockBounds(val)) {
-        ctx.addIssue({ code: 'custom', message: 'Block tree exceeds the maximum depth or size' })
-      }
-    })
-    .pipe(z.array(node))
-}

package/layers/fields/server/utils/defineFieldType.ts

@@ -1,33 +0,0 @@
-import type { FieldTypeDescriptor } from '../field-registry/types'
-import { registerFieldType } from '../field-registry'
-
-export type { FieldTypeDescriptor }
-// Re-export the descriptor helpers so a consumer's field-type file can build the Drizzle column + Zod with
-// the SAME optionality/constraint logic the built-ins use — all auto-imported in a `server/field-types/` file.
-export { constrain, opt, optArr, isHardRequired, getFieldType, registerFieldType } from '../field-registry'
-
-/**
- * A consumer-defined field type: a `name` plus the server contract — a Drizzle `column` and a Zod
- * `validator`. Drop a file in `server/field-types/` that default-exports `defineFieldType({...})`; it is
- * auto-discovered and registered BEFORE any table is built. Pair it with a client editor widget via
- * `registerFieldComponent('<name>', Component)` in an `app/plugins/*.client.ts`.
- *
- * @example
- * // server/field-types/color.ts
- * import { text } from 'drizzle-orm/sqlite-core'
- * import { z } from 'zod'
- * export default defineFieldType({
- *   name: 'color',
- *   column: (n, f) => constrain(text(n), f),
- *   validator: (f) => opt(z.string().regex(/^#[0-9a-f]{6}$/i), f),
- * })
- */
-export interface FieldTypeDef extends FieldTypeDescriptor {
-  name: string
-}
-
-export function defineFieldType(def: FieldTypeDef): FieldTypeDescriptor {
-  const { name, ...descriptor } = def // keep column, validator AND transform — don't drop a consumer's transform
-  registerFieldType(name, descriptor)
-  return descriptor
-}

package/layers/fields/server/utils/extract-refs.ts

@@ -1,152 +0,0 @@
-import type { CollectionDef, FieldDef } from '../../../core/server/utils/defineCollection'
-import { fieldIs } from '../../../core/server/utils/defineCollection'
-import type { KeyMode } from '../../../core/server/utils/populate'
-import { seoPopulateFields } from '../../../core/server/utils/seo'
-import { getBlock } from './defineBlock'
-import { collectRichtextRefs } from '../../app/utils/richtext-links'
-
-/**
- * Static reference extraction over a record's fields — the pure core of the `record_refs` durable index
- * and the derived stale-reference warnings. Walks every reference-bearing field type (relation, media,
- * internal link, richtext internal-link markers, repeater) plus the block tree, and yields the
- * `(collection, id)` targets it points at. PURE (no DB / no Nuxt) so it unit-tests hard.
- */
-export interface FieldRef {
-  collection: string
-  id: number
-}
-
-/** A ref tagged with WHERE it lives, for the editor's per-field / per-block dead-reference notes. */
-export interface LocatedRef extends FieldRef {
-  /** The top-level field key (a repeater attributes all its entries' refs to the repeater key). */
-  field: string
-  /** The id of the block node the ref lives in, or undefined at the record root. */
-  blockId?: string
-}
-
-// `KeyMode` (columns vs props storage asymmetry) is owned by core's populate seam and imported above —
-// the same asymmetry the field-tree populator walks, so both share one definition.
-
-/** The internal-link guard, reimplemented locally to keep this `core`/`fields`-side extractor from
- *  importing the `public` layer's private `isInternal` (which would invert the layer dependency). */
-function internalLinkRef(value: unknown): FieldRef | null {
-  if (!value || typeof value !== 'object') return null
-  const v = value as Record<string, unknown>
-  if (v.type === 'internal' && typeof v.collection === 'string' && typeof v.id === 'number') {
-    return { collection: v.collection, id: v.id }
-  }
-  return null
-}
-
-/** Located refs inside one flat value bag (top-level row | block props | a repeater entry). */
-function bagRefs(fields: Record<string, FieldDef>, bag: Record<string, unknown>, keyMode: KeyMode): LocatedRef[] {
-  const out: LocatedRef[] = []
-  for (const [key, field] of Object.entries(fields)) {
-    // `if (fieldIs(...))` not `switch (field.type)`: the open consumer arm makes `type` a non-discriminant,
-    // so a switch wouldn't narrow `field` to its arm. (text / number / boolean / datetime / choice / json
-    // carry no typed references, so they're not handled here.)
-    if (fieldIs(field, 'relation')) {
-      const coll = field.relation.collection
-      if (field.relation.many) {
-        const ids = bag[key]
-        if (Array.isArray(ids)) for (const id of ids) if (typeof id === 'number') out.push({ field: key, collection: coll, id })
-      } else {
-        const value = bag[keyMode === 'columns' ? `${key}Id` : key]
-        if (typeof value === 'number') out.push({ field: key, collection: coll, id: value })
-      }
-    } else if (fieldIs(field, 'media')) {
-      if (field.options?.multiple) {
-        const ids = bag[key]
-        if (Array.isArray(ids)) for (const id of ids) if (typeof id === 'number') out.push({ field: key, collection: 'media', id })
-      } else {
-        const value = bag[keyMode === 'columns' ? `${key}Id` : key]
-        if (typeof value === 'number') out.push({ field: key, collection: 'media', id: value })
-      }
-    } else if (field.type === 'link') {
-      const ref = internalLinkRef(bag[key])
-      if (ref) out.push({ field: key, collection: ref.collection, id: ref.id })
-    } else if (field.type === 'richtext') {
-      const value = bag[key]
-      if (typeof value === 'string') for (const r of collectRichtextRefs(value)) out.push({ field: key, collection: r.collection, id: r.id })
-    } else if (fieldIs(field, 'repeater')) {
-      const entries = bag[key]
-      if (Array.isArray(entries)) {
-        for (const entry of entries) {
-          if (entry && typeof entry === 'object') {
-            // A repeater entry is keyed bare (props mode); attribute its refs to the repeater field.
-            for (const r of bagRefs(field.options.fields, entry as Record<string, unknown>, 'props')) {
-              out.push({ field: key, collection: r.collection, id: r.id })
-            }
-          }
-        }
-      }
-    }
-  }
-  return out
-}
-
-/** Located refs inside a block `content` array, recursing slots; each ref carries the innermost block id. */
-function blockRefs(content: unknown): LocatedRef[] {
-  const out: LocatedRef[] = []
-  const walk = (nodes: unknown): void => {
-    if (!Array.isArray(nodes)) return
-    for (const node of nodes) {
-      if (!node || typeof node !== 'object') continue
-      const n = node as { id?: string; type?: string; props?: Record<string, unknown>; slots?: Record<string, unknown> }
-      const def = n.type ? getBlock(n.type) : undefined
-      if (def && n.props && typeof n.props === 'object') {
-        for (const r of bagRefs(def.fields, n.props, 'props')) out.push({ field: r.field, blockId: n.id, collection: r.collection, id: r.id })
-      }
-      if (n.slots && typeof n.slots === 'object') {
-        for (const slotNodes of Object.values(n.slots)) walk(slotNodes)
-      }
-    }
-  }
-  walk(content)
-  return out
-}
-
-function dedupe(refs: FieldRef[]): FieldRef[] {
-  const seen = new Set<string>()
-  const out: FieldRef[] = []
-  for (const r of refs) {
-    const k = `${r.collection}:${r.id}`
-    if (!seen.has(k)) { seen.add(k); out.push({ collection: r.collection, id: r.id }) }
-  }
-  return out
-}
-
-function dedupeLocated(refs: LocatedRef[]): LocatedRef[] {
-  const seen = new Set<string>()
-  const out: LocatedRef[] = []
-  for (const r of refs) {
-    const k = `${r.blockId ?? ''} ${r.field} ${r.collection}:${r.id}`
-    if (!seen.has(k)) { seen.add(k); out.push(r) }
-  }
-  return out
-}
-
-/** Deduped `(collection,id)` refs in a single flat value bag (one field set), honouring the key-mode. */
-export function extractFieldRefs(fields: Record<string, FieldDef>, bag: Record<string, unknown>, keyMode: KeyMode): FieldRef[] {
-  return dedupe(bagRefs(fields, bag, keyMode))
-}
-
-/** Every distinct `(collection,id)` a record points at — its top-level columns plus, if blocks are
- *  enabled, its whole block tree. The forward edges stored in `record_refs`. */
-export function extractRecordRefs(def: CollectionDef, row: Record<string, unknown>): FieldRef[] {
-  return dedupe(extractLocatedRecordRefs(def, row))
-}
-
-/** Like `extractRecordRefs` but each ref carries its field + block-node location (for editor warnings). */
-export function extractLocatedRecordRefs(def: CollectionDef, row: Record<string, unknown>): LocatedRef[] {
-  const refs = bagRefs(def.fields, row, 'columns')
-  // The `seo` system column carries a media ref (the social image) — track it like any media field so
-  // dead-link warnings and the published-media GC see a record whose ONLY use of an image is og:image.
-  if (def.seo && row.seo && typeof row.seo === 'object') {
-    for (const r of bagRefs(seoPopulateFields, row.seo as Record<string, unknown>, 'props')) {
-      refs.push({ ...r, field: `seo.${r.field}` })
-    }
-  }
-  if (def.blocks?.enabled) refs.push(...blockRefs(row.content))
-  return dedupeLocated(refs)
-}

package/layers/fields/server/utils/field-populate.ts

@@ -1,68 +0,0 @@
-import type { FieldDef } from '../../../core/server/utils/defineCollection'
-import { fieldIs } from '../../../core/server/utils/defineCollection'
-import { seoPopulateFields } from '../../../core/server/utils/seo'
-import type { Populator, PopulateCtx, KeyMode, FieldPopulator } from '../../../core/server/utils/populate'
-import { getFieldPopulator } from '../../../core/server/utils/populate'
-import { buildBlockPopulator } from './block-populate'
-
-/** How the walker finds the populator for a field type — the global registry by default, or an explicit
- *  map (used by tests + the media/link whole-row compatibility builders to run one populator in isolation). */
-export type PopulatorLookup = (type: string) => FieldPopulator | undefined
-
-/**
- * Apply the registered per-field-type populators over ONE flat value bag (top-level row | block props | a
- * repeater entry). For each field: dispatch to its type's populator (which reads by `keyMode` and mutates
- * `bag`), then — for a repeater — clone its entries and recurse in PROPS mode. Cloning the array + entries
- * keeps the ORIGINAL row untouched (population is non-destructive). Mutates `bag` in place. This is the
- * `bagRefs` recursion (see `extract-refs.ts`), generalised from "collect refs" to "run a visitor".
- */
-export function applyFieldPopulators(
-  bag: Record<string, unknown>,
-  fields: Record<string, FieldDef>,
-  keyMode: KeyMode,
-  ctx: PopulateCtx,
-  lookup: PopulatorLookup,
-): void {
-  for (const [key, field] of Object.entries(fields)) {
-    // A per-instance `field.populate` (Pruvious `additional.population`) wins over the type's default.
-    const fn = field.populate ?? lookup(field.type)
-    if (fn) fn(bag, key, field, ctx, keyMode)
-    if (fieldIs(field, 'repeater')) {
-      const entries = bag[key]
-      if (Array.isArray(entries)) {
-        const cloned = entries.map((e) => (e && typeof e === 'object' ? { ...(e as Record<string, unknown>) } : e))
-        bag[key] = cloned
-        for (const entry of cloned) {
-          if (entry && typeof entry === 'object') {
-            applyFieldPopulators(entry as Record<string, unknown>, field.options.fields, 'props', ctx, lookup)
-          }
-        }
-      }
-    }
-  }
-}
-
-/**
- * The single global row populator: walks a row's top-level fields (COLUMNS mode) and, when blocks are
- * enabled, its block tree (each node's props in PROPS mode + every slot), dispatching each field to its
- * registered per-type populator and recursing repeaters. Non-destructive (returns a fresh row; block
- * nodes/props are cloned by `buildBlockPopulator`, repeater entries by `applyFieldPopulators`).
- */
-export function buildFieldTreePopulator(lookup: PopulatorLookup = getFieldPopulator): Populator {
-  return (row, ctx) => {
-    const out: Record<string, unknown> = { ...row }
-    applyFieldPopulators(out, ctx.def.fields, 'columns', ctx, lookup)
-    // The `seo` system column carries a media reference (the social image) — walk it like a props bag
-    // so the id resolves under `seo.$media.image` with the same read-capture as any media field.
-    if (ctx.def.seo && out.seo && typeof out.seo === 'object') {
-      const seoBag = { ...(out.seo as Record<string, unknown>) }
-      applyFieldPopulators(seoBag, seoPopulateFields, 'props', ctx, lookup)
-      out.seo = seoBag
-    }
-    if (ctx.def.blocks?.enabled && Array.isArray(out.content)) {
-      const walk = buildBlockPopulator((props, fields) => applyFieldPopulators(props, fields, 'props', ctx, lookup))
-      out.content = walk(out.content)
-    }
-    return out
-  }
-}

package/layers/media/server/api/media/[id]/usages.get.ts

@@ -1,8 +0,0 @@
-import { findMediaUsages } from '../../../utils/usages'
-import { requireMediaCollection } from '../../../utils/media-enabled'
-
-export default defineEventHandler((event) => {
-  requireMediaCollection()
-  const id = requireId(event)
-  return { id, usages: findMediaUsages(useDb(), id) }
-})