@crombolo/data 0.9.1 → 0.11.0

package/src/database.ts

@@ -1,5 +1,7 @@
 /** Driver-agnostic database handle. */
+
 import { Database as BunSqlite } from 'bun:sqlite'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import { type Dialect, type DialectName, dialectFor } from './dialect.ts'
 import { createLockManager, type LockManager } from './locks.ts'
 
@@ -22,16 +24,32 @@ export interface ConnectOptions {
   url?: string
 }
 
+/** The connection the current async chain holds a transaction on. */
+const transacting = new AsyncLocalStorage<BunSqlite>()
+
+/**
+ * One connection has one transaction at a time, but async chains interleave:
+ * a background job's BEGIN between a request's BEGIN and COMMIT would fail, or
+ * worse, land its statements in the request's transaction. So top-level
+ * transactions queue here, and a chain already inside one joins it.
+ */
 class SqliteDb implements Db {
   readonly dialect = dialectFor('sqlite')
   readonly locks: LockManager
   #db: BunSqlite
   #inTransaction: boolean
-
-  constructor(db: BunSqlite, locks?: LockManager, inTransaction = false) {
+  #gate: { tail: Promise<void> }
+
+  constructor(
+    db: BunSqlite,
+    locks?: LockManager,
+    inTransaction = false,
+    gate: { tail: Promise<void> } = { tail: Promise.resolve() },
+  ) {
     this.#db = db
     this.locks = locks ?? createLockManager(this)
     this.#inTransaction = inTransaction
+    this.#gate = gate
   }
 
   async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
@@ -44,14 +62,26 @@ class SqliteDb implements Db {
 
   async transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T> {
     if (this.#inTransaction) return fn(this)
-    this.#db.exec('BEGIN')
+    const tx = new SqliteDb(this.#db, this.locks, true, this.#gate)
+    if (transacting.getStore() === this.#db) return fn(tx)
+    const previous = this.#gate.tail
+    let release!: () => void
+    this.#gate.tail = new Promise<void>((resolve) => {
+      release = resolve
+    })
+    await previous
     try {
-      const result = await fn(new SqliteDb(this.#db, this.locks, true))
-      this.#db.exec('COMMIT')
-      return result
-    } catch (error) {
-      this.#db.exec('ROLLBACK')
-      throw error
+      this.#db.exec('BEGIN')
+      try {
+        const result = await transacting.run(this.#db, () => fn(tx))
+        this.#db.exec('COMMIT')
+        return result
+      } catch (error) {
+        this.#db.exec('ROLLBACK')
+        throw error
+      }
+    } finally {
+      release()
     }
   }
 

package/src/dialect.ts

@@ -15,6 +15,10 @@ export interface ColumnTypes {
   textCi: string
   text: string
   varchar: (n: number) => string
+  /** A varchar that compares case-sensitively on both dialects, as a bundle's tables do. */
+  varcharExact: (n: number) => string
+  /** JSON, held as text and parsed by whoever reads it. */
+  json: string
   timestamp: string
   numeric: string
   blob: string
@@ -32,6 +36,16 @@ export interface Dialect {
   /** Appended to a SELECT that must block a concurrent state change; empty where the engine is single-writer. */
   readonly forShare: string
   readonly forUpdate: string
+  /** Appended to a SELECT that claims rows, passing over any another connection holds. */
+  readonly forUpdateSkipLocked: string
+  /**
+   * The full-text match over `search_document`: a subquery of `node_id` and
+   * `score`, higher being better, for each item holding every term as a word
+   * prefix. Its one parameter is `fullTextQuery(terms)`. docs/search.md.
+   */
+  readonly fullTextHits: string
+  /** Terms are already folded words: letters and digits only. */
+  fullTextQuery(terms: readonly string[]): string
   /**
    * SQL that moves a table's identity past rows inserted with explicit ids, or
    * undefined where the engine does that itself.
@@ -53,6 +67,8 @@ export const sqliteDialect: Dialect = {
     textCi: 'TEXT COLLATE NOCASE',
     text: 'TEXT',
     varchar: (n) => `VARCHAR(${n}) COLLATE NOCASE`,
+    varcharExact: (n) => `VARCHAR(${n})`,
+    json: 'TEXT',
     timestamp: 'TEXT',
     // REAL would be lossy for decimal property values.
     numeric: 'TEXT',
@@ -65,6 +81,15 @@ export const sqliteDialect: Dialect = {
   boolValue: (value) => (value ? 1 : 0),
   forShare: '',
   forUpdate: '',
+  forUpdateSkipLocked: '',
+  // Name hits weigh ten times body hits; bm25 is lower-is-better, so negated.
+  // bm25 cannot be called under an aggregate, and `LIMIT -1` (no limit) keeps
+  // SQLite from flattening the inner query into the outer one, which would.
+  fullTextHits: `SELECT sd.node_id AS node_id, MAX(f.score) AS score
+    FROM (SELECT rowid AS id, -bm25(search_document_fts, 10.0, 1.0) AS score
+          FROM search_document_fts WHERE search_document_fts MATCH ? LIMIT -1) f
+    JOIN search_document sd ON sd.id = f.id GROUP BY sd.node_id`,
+  fullTextQuery: (terms) => terms.map((term) => `"${term}"*`).join(' AND '),
   syncIdentity: () => undefined,
 }
 
@@ -80,6 +105,8 @@ export const postgresDialect: Dialect = {
     textCi: 'CITEXT',
     text: 'TEXT',
     varchar: (n) => `VARCHAR(${n})`,
+    varcharExact: (n) => `VARCHAR(${n})`,
+    json: 'TEXT',
     timestamp: 'TIMESTAMPTZ',
     numeric: 'NUMERIC',
     blob: 'BYTEA',
@@ -94,6 +121,11 @@ export const postgresDialect: Dialect = {
   boolValue: (value) => value,
   forShare: 'FOR SHARE',
   forUpdate: 'FOR UPDATE',
+  forUpdateSkipLocked: 'FOR UPDATE SKIP LOCKED',
+  fullTextHits: `SELECT sd.node_id AS node_id, MAX(ts_rank(sd.terms, q)) AS score
+    FROM search_document sd, to_tsquery('simple', ?) q
+    WHERE sd.terms @@ q GROUP BY sd.node_id`,
+  fullTextQuery: (terms) => terms.map((term) => `${term}:*`).join(' & '),
   syncIdentity: (table) =>
     `SELECT setval(pg_get_serial_sequence('${table}', 'id'), (SELECT COALESCE(MAX(id), 1) FROM ${table}))`,
 }

package/src/index.ts

@@ -1,3 +1,5 @@
+export * from './audit.ts'
+export * from './bundle-tables/index.ts'
 export * from './change-report.ts'
 export * from './cluster.ts'
 export * from './database.ts'
@@ -30,9 +32,11 @@ export * from './repositories/transfer-runs.ts'
 export * from './repositories/user-data.ts'
 export * from './repositories/users.ts'
 export * from './schema/assistant.ts'
+export * from './schema/audit-log.ts'
 export * from './schema/built-in-content-types.ts'
 export * from './schema/built-in-media-types.ts'
 export * from './schema/built-in-member-types.ts'
+export * from './schema/bundle-package.ts'
 export * from './schema/bundles-rename.ts'
 export * from './schema/change-report.ts'
 export * from './schema/client-id-prefix.ts'
@@ -47,14 +51,19 @@ export * from './schema/log-viewer.ts'
 export * from './schema/member-property-type.ts'
 export * from './schema/members.ts'
 export * from './schema/plan.ts'
+export * from './schema/property-searchable.ts'
 export * from './schema/public-access.ts'
 export * from './schema/recycle-bin.ts'
 export * from './schema/rich-text-ui.ts'
+export * from './schema/search-index.ts'
 export * from './schema/seed.ts'
 export * from './schema/since-version.ts'
+export * from './schema/transfer-run-package.ts'
 export * from './schema/transfer-runs.ts'
 export * from './schema/upgrade-report.ts'
 export * from './schema/users-localisation.ts'
 export * from './schema/values.ts'
 export * from './schema-ops.ts'
 export * from './schema-state.ts'
+export * from './search.ts'
+export * from './search-text.ts'

package/src/migrations.ts

@@ -3,7 +3,7 @@
  * version number and not a list of applied migrations: the plan is a chain of
  * transitions walked forward to its final state. That design handles concurrent
  * development branches far better than sequence numbers, so we keep it — and
- * harden it (docs/10-packaging-and-upgrades.md): a ledger of every step that
+ * harden it (docs/packaging-and-upgrades.md): a ledger of every step that
  * ran, expand/contract declared and linted, a recorded plan, and an explicit
  * refusal when the database is newer than the code.
  */
@@ -29,7 +29,24 @@ export interface Migration {
   release?: string
   /** For a contract: the name of the expand migration it removes. */
   contracts?: string
+  /** Recorded in the ledger, and compared when the plan verifies what ran. Defaults to `name`. */
+  checksum?: string
   up(db: Db): Promise<void>
+  /**
+   * Writes data once `up` has run, in the same transaction. `planUpgrade` cannot
+   * predict what it writes, so a step that has one is reported as unplannable.
+   */
+  backfill?(db: Db): Promise<void>
+}
+
+/** Where a chain keeps its state, and what it calls itself in the ledger. */
+export interface ChainOptions {
+  /** The `key_value` key holding the chain's state. */
+  stateKey?: string
+  /** The state before the first step. */
+  initialState?: string
+  /** A bundle's id, for a bundle's chain; absent for core's. */
+  bundle?: string
 }
 
 function compareRelease(a: string, b: string): number {
@@ -71,10 +88,16 @@ export function isMajorRelease(release: string): boolean {
 
 export class MigrationPlan {
   readonly migrations: readonly Migration[]
+  readonly stateKey: string
+  readonly initialState: string
+  readonly bundle: string | undefined
 
-  constructor(migrations: readonly Migration[]) {
+  constructor(migrations: readonly Migration[], options: ChainOptions = {}) {
     this.migrations = migrations
-    let expected = INITIAL_STATE
+    this.stateKey = options.stateKey ?? MIGRATION_STATE_KEY
+    this.initialState = options.initialState ?? INITIAL_STATE
+    this.bundle = options.bundle
+    let expected = this.initialState
     const seen = new Map<string, Migration>()
     for (const migration of migrations) {
       if (migration.from !== expected) {
@@ -111,7 +134,14 @@ export class MigrationPlan {
   }
 
   get finalState(): string {
-    return this.migrations.at(-1)?.to ?? INITIAL_STATE
+    return this.migrations.at(-1)?.to ?? this.initialState
+  }
+
+  /** The steps that have run when the chain is at a state; undefined when the state is not in it. */
+  appliedAt(state: string): Migration[] | undefined {
+    if (state === this.initialState) return []
+    const index = this.migrations.findIndex((m) => m.to === state)
+    return index < 0 ? undefined : this.migrations.slice(0, index + 1)
   }
 
   /** The steps still to run from a state; empty when current. Undefined when the state is not in the plan. */
@@ -123,7 +153,11 @@ export class MigrationPlan {
   }
 }
 
+/** Connections whose ledger tables are known to exist with every column. */
+const ensured = new WeakSet<Db>()
+
 async function ensureTables(db: Db): Promise<void> {
+  if (ensured.has(db)) return
   const t = db.dialect.types
   await db.exec(
     `CREATE TABLE IF NOT EXISTS key_value (
@@ -143,36 +177,62 @@ async function ensureTables(db: Db): Promise<void> {
        duration_ms ${t.integer} NOT NULL,
        checksum ${t.varchar(64)},
        applied_by ${t.varchar(255)},
-       note ${t.text}
+       note ${t.text},
+       bundle ${t.varchar(64)}
      )`,
   )
+  // A ledger from before bundles could own tables has no `bundle` column. It is
+  // added here, where the table is, rather than by a core migration: the ledger
+  // has to be able to record a bundle's step whatever state core is at.
+  if (!(await hasColumn(db, 'migration_history', 'bundle')))
+    await db.exec(`ALTER TABLE migration_history ADD COLUMN bundle ${t.varchar(64)}`)
+  ensured.add(db)
+}
+
+async function hasColumn(db: Db, table: string, column: string): Promise<boolean> {
+  const rows =
+    db.dialect.name === 'sqlite'
+      ? await db.query<{ name: string }>(`SELECT name FROM pragma_table_info('${table}')`)
+      : await db.query<{ name: string }>(
+          'SELECT column_name AS name FROM information_schema.columns WHERE table_schema = current_schema() AND table_name = ?',
+          [table],
+        )
+  return rows.some((row) => row.name === column)
 }
 
-export async function readState(db: Db): Promise<string> {
+/** A chain's state: core's unless a plan says otherwise. */
+export async function readState(
+  db: Db,
+  chain: Pick<MigrationPlan, 'stateKey' | 'initialState'> = {
+    stateKey: MIGRATION_STATE_KEY,
+    initialState: INITIAL_STATE,
+  },
+): Promise<string> {
   await ensureTables(db)
   const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
-    MIGRATION_STATE_KEY,
+    chain.stateKey,
   ])
-  return rows[0]?.value ?? INITIAL_STATE
+  return rows[0]?.value ?? chain.initialState
 }
 
-async function writeState(db: Db, state: string): Promise<void> {
+async function writeState(db: Db, state: string, key = MIGRATION_STATE_KEY): Promise<void> {
   const now = db.dialect.now()
-  await db.query(`UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ?`, [
-    state,
-    MIGRATION_STATE_KEY,
-  ])
-  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [
-    MIGRATION_STATE_KEY,
-  ])
+  await db.query(`UPDATE key_value SET value = ?, update_date = ${now} WHERE key = ?`, [state, key])
+  const rows = await db.query<{ value: string }>('SELECT value FROM key_value WHERE key = ?', [key])
   if (rows.length === 0) {
     await db.exec(
       `INSERT INTO key_value (key, value, update_date) VALUES (${db.dialect.placeholder(1)}, ${db.dialect.placeholder(2)}, ${now})`,
-      [MIGRATION_STATE_KEY, state],
+      [key, state],
     )
   }
 }
 
+/** Forgets a setting entirely, as a purged bundle's state is forgotten. */
+export async function deleteKeyValue(db: Db, key: string): Promise<void> {
+  await ensureTables(db)
+  await db.exec('DELETE FROM key_value WHERE key = ?', [key])
+}
+
 export interface LedgerEntry {
   name: string
   /** 'expand' | 'contract' for framework steps; 'value' for a value migration; 'upgrade' for a cut-over. */
@@ -183,6 +243,8 @@ export interface LedgerEntry {
   checksum?: string | null
   appliedBy?: string | null
   note?: string | null
+  /** The bundle whose chain this step belongs to; null for core. */
+  bundle?: string | null
 }
 
 /**
@@ -226,8 +288,8 @@ export async function ensureKeyValue(db: Db, key: string, create: () => string):
 export async function recordInLedger(db: Db, entry: LedgerEntry): Promise<void> {
   await ensureTables(db)
   await db.exec(
-    `INSERT INTO migration_history (name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note)
-     VALUES (?, ?, ?, ?, ${db.dialect.now()}, ?, ?, ?, ?)`,
+    `INSERT INTO migration_history (name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note, bundle)
+     VALUES (?, ?, ?, ?, ${db.dialect.now()}, ?, ?, ?, ?, ?)`,
     [
       entry.name,
       entry.kind,
@@ -237,6 +299,7 @@ export async function recordInLedger(db: Db, entry: LedgerEntry): Promise<void>
       entry.checksum ?? null,
       entry.appliedBy ?? null,
       entry.note ?? null,
+      entry.bundle ?? null,
     ],
   )
 }
@@ -248,10 +311,14 @@ export async function latestLedgerId(db: Db): Promise<number> {
   return Number(rows[0]?.n ?? 0)
 }
 
-/** How many contract steps — framework contracts and site purges — were ledgered after a row id. */
+/**
+ * How many contract steps — framework contracts and site purges — were ledgered
+ * after a row id. A bundle's contract is not counted: it removes only the
+ * bundle's own tables, which no read of core's depends on.
+ */
 export async function contractsLedgeredAfter(db: Db, afterId: number): Promise<number> {
   const rows = await db.query<{ n: number }>(
-    "SELECT COUNT(*) AS n FROM migration_history WHERE id > ? AND kind = 'contract'",
+    "SELECT COUNT(*) AS n FROM migration_history WHERE id > ? AND kind = 'contract' AND bundle IS NULL",
     [afterId],
   )
   return Number(rows[0]?.n ?? 0)
@@ -265,7 +332,7 @@ export interface LedgerRow extends LedgerEntry {
 export async function readLedger(db: Db): Promise<LedgerRow[]> {
   await ensureTables(db)
   const rows = await db.query(
-    'SELECT id, name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note FROM migration_history ORDER BY id',
+    'SELECT id, name, kind, from_state, to_state, applied_at, duration_ms, checksum, applied_by, note, bundle FROM migration_history ORDER BY id',
   )
   return rows.map((row) => ({
     id: Number(row.id),
@@ -278,6 +345,7 @@ export async function readLedger(db: Db): Promise<LedgerRow[]> {
     checksum: (row.checksum as string | null) ?? null,
     appliedBy: (row.applied_by as string | null) ?? null,
     note: (row.note as string | null) ?? null,
+    bundle: (row.bundle as string | null) ?? null,
   }))
 }
 
@@ -286,22 +354,66 @@ export class UpgradeStateError extends Error {
   constructor(
     readonly databaseState: string,
     readonly codeState: string,
+    /** The bundle whose chain it is, when it is not core's. */
+    readonly bundle?: string,
+  ) {
+    super(
+      bundle
+        ? `The database holds the bundle "${bundle}"'s tables at state ${databaseState}, which this version of the bundle (its steps end at ${codeState}) does not know. ` +
+            'A newer release of the bundle wrote them; install that release, or restore the backup taken before the upgrade.'
+        : `The database is at migration state ${databaseState}, which this version of crombolo (plan ends at ${codeState}) does not know. ` +
+            'It was upgraded by a newer version; run that version, or restore the backup taken before the upgrade.',
+    )
+  }
+}
+
+/** A bundle step changed after it ran here: what is in the database is not what the code says made it. */
+export class BundleStepEditedError extends Error {
+  constructor(
+    readonly bundle: string,
+    readonly step: string,
   ) {
     super(
-      `The database is at migration state ${databaseState}, which this version of crombolo (plan ends at ${codeState}) does not know. ` +
-        'It was upgraded by a newer version; run that version, or restore the backup taken before the upgrade.',
+      `The bundle "${bundle}"'s step "${step}" is not the step that ran on this database: it was edited after it shipped. ` +
+        'A shipped step is never changed; put the change in a new step.',
     )
   }
 }
 
 /** Steps pending on this database, in order. Throws when the database is ahead of the code. */
 export async function pendingMigrations(db: Db, plan: MigrationPlan): Promise<Migration[]> {
-  const state = await readState(db)
+  const state = await readState(db, plan)
   const pending = plan.pendingFrom(state)
-  if (!pending) throw new UpgradeStateError(state, plan.finalState)
+  if (!pending) throw new UpgradeStateError(state, plan.finalState, plan.bundle)
   return pending
 }
 
+/**
+ * Refuses a bundle chain whose applied steps no longer match the code. Only the
+ * rows since the bundle was last purged count: a purge starts its chain again.
+ */
+async function verifyApplied(db: Db, plan: MigrationPlan, state: string): Promise<void> {
+  if (!plan.bundle) return
+  const applied = plan.appliedAt(state) ?? []
+  if (applied.length === 0) return
+  const rows = await db.query<{ name: string; kind: string; checksum: string | null }>(
+    'SELECT name, kind, checksum FROM migration_history WHERE bundle = ? ORDER BY id',
+    [plan.bundle],
+  )
+  const purged = rows.map((row) => row.kind).lastIndexOf('purge')
+  const ran = new Map(
+    rows
+      .slice(purged + 1)
+      .filter((row) => row.kind === 'expand' || row.kind === 'contract')
+      .map((row) => [row.name, row.checksum]),
+  )
+  for (const step of applied) {
+    const recorded = ran.get(step.name)
+    if (recorded !== undefined && recorded !== (step.checksum ?? step.name))
+      throw new BundleStepEditedError(plan.bundle, step.name)
+  }
+}
+
 export interface MigrateResult {
   from: string
   to: string
@@ -320,27 +432,30 @@ export async function migrate(
   options: MigrateOptions = {},
 ): Promise<MigrateResult> {
   return db.locks.withLock(Locks.KeyValues, async () => {
-    const from = await readState(db)
+    const from = await readState(db, plan)
     let state = from
     const applied: string[] = []
     const pending = plan.pendingFrom(state)
-    if (!pending) throw new UpgradeStateError(state, plan.finalState)
+    if (!pending) throw new UpgradeStateError(state, plan.finalState, plan.bundle)
+    await verifyApplied(db, plan, state)
     for (const next of pending) {
       const started = performance.now()
       await db.transaction(async (tx) => {
         await next.up(tx)
+        await next.backfill?.(tx)
       })
       state = next.to
-      await writeState(db, state)
+      await writeState(db, state, plan.stateKey)
       await recordInLedger(db, {
         name: next.name,
         kind: next.kind ?? 'expand',
         fromState: next.from,
         toState: next.to,
         durationMs: Math.round(performance.now() - started),
-        checksum: next.name,
+        checksum: next.checksum ?? next.name,
         appliedBy: options.by ?? null,
         note: next.release ? `release ${next.release}` : null,
+        bundle: plan.bundle ?? null,
       })
       applied.push(next.name)
     }
@@ -351,7 +466,7 @@ export async function migrate(
 /** A fresh install stamps the final state so no migrations then run. */
 export async function stampFinalState(db: Db, plan: MigrationPlan): Promise<void> {
   await ensureTables(db)
-  await writeState(db, plan.finalState)
+  await writeState(db, plan.finalState, plan.stateKey)
 }
 
 // ---------------------------------------------------------------- the plan
@@ -421,6 +536,7 @@ export async function planUpgrade(db: Db, plan: MigrationPlan): Promise<PlannedS
     try {
       await migration.up(recorder)
       step.statements = recorder.statements
+      if (migration.backfill) step.unplannable = 'backfills data, which only running it can show'
     } catch (error) {
       if (error instanceof UnplannableError) step.unplannable = error.message
       else throw error

package/src/pending.ts

@@ -1,7 +1,7 @@
 /**
  * An element is pending on a node when the deployment that created it is newer
  * than the node, or its file says `since` a version the node has not reached.
- * The one place the rule lives. docs/09-schema-as-code.md, "since".
+ * The one place the rule lives. docs/schema-as-code.md, "since".
  */
 import { compareStates, compareVersions, type NodeSchemaState } from './schema-state.ts'
 

package/src/repositories/bundles.ts

@@ -1,6 +1,6 @@
 /**
  * The bundle definitions: what a bundle would contain, not a built bundle.
- * `docs/17-bundles.md`.
+ * `docs/bundles.md`.
  *
  * The selection lists travel as JSON text in single columns. A malformed list
  * reads back as empty rather than throwing: a definition whose row was edited
@@ -26,12 +26,21 @@ export interface Bundle {
   scripts: string[]
   languages: string[]
   dictionaryItems: string[]
+  /**
+   * The npm package the bundle is built as. Not in Umbraco's definition, so the
+   * contract never writes these; null until someone sets them.
+   */
+  packageName: string | null
+  packageVersion: string | null
   createDate: Date
   updateDate: Date
 }
 
 /** A definition to store; `id` is assigned when it is new, the dates always. */
-export type BundleInput = Omit<Bundle, 'id' | 'createDate' | 'updateDate'>
+export type BundleInput = Omit<
+  Bundle,
+  'id' | 'createDate' | 'updateDate' | 'packageName' | 'packageVersion'
+>
 
 interface Row {
   id: string
@@ -49,6 +58,8 @@ interface Row {
   scripts: string
   languages: string
   dictionary_items: string
+  package_name: string | null
+  package_version: string | null
   create_date: unknown
   update_date: unknown
 }
@@ -56,7 +67,8 @@ interface Row {
 const SELECT = `SELECT id, name, content_node_id, content_load_child_nodes,
                        media_load_child_nodes, media_ids, element_ids, content_types,
                        media_types, data_types, components, stylesheets,
-                       scripts, languages, dictionary_items, create_date, update_date
+                       scripts, languages, dictionary_items, package_name, package_version,
+                       create_date, update_date
                   FROM bundle`
 
 const list = (value: string | null): string[] => {
@@ -87,6 +99,8 @@ const hydrate = (row: Row): Bundle => ({
   scripts: list(row.scripts),
   languages: list(row.languages),
   dictionaryItems: list(row.dictionary_items),
+  packageName: row.package_name ?? null,
+  packageVersion: row.package_version ?? null,
   createDate: DbDate.fromDb(row.create_date) ?? new Date(0),
   updateDate: DbDate.fromDb(row.update_date) ?? new Date(0),
 })
@@ -152,7 +166,14 @@ export class BundleRepository {
         DbDate.toDb(now),
       ],
     )
-    return { ...input, id, createDate: now, updateDate: now }
+    return {
+      ...input,
+      id,
+      packageName: null,
+      packageVersion: null,
+      createDate: now,
+      updateDate: now,
+    }
   }
 
   async update(id: string, input: BundleInput): Promise<void> {
@@ -185,6 +206,17 @@ export class BundleRepository {
     )
   }
 
+  /** The npm package a definition is built as; null clears a value back to its default. */
+  async setPackage(
+    id: string,
+    pkg: { name: string | null; version: string | null },
+  ): Promise<void> {
+    await this.#db.exec(
+      'UPDATE bundle SET package_name = ?, package_version = ?, update_date = ? WHERE id = ?',
+      [pkg.name, pkg.version, DbDate.toDb(new Date()), id],
+    )
+  }
+
   async delete(id: string): Promise<void> {
     await this.#db.exec('DELETE FROM bundle WHERE id = ?', [id])
   }