@crombolo/cli 0.9.1 → 0.11.0

package/src/operations/commands.ts

@@ -5,17 +5,23 @@
  * a platform's own tooling — gets the same results as data. One implementation,
  * so the two can never disagree about what an import or an upgrade does.
  */
-import { ObjectTypes, ROOT_ACCESS } from '@crombolo/core'
+import { userInfo } from 'node:os'
+import { ROOT_ACCESS } from '@crombolo/core'
 import {
+  type AuditCategory,
+  bundleStateKey,
+  bundleTablesIn,
   connect,
   cromboloPlan,
   type Db,
   describeRefFailure,
   type NodeRow,
+  type PlannedStep,
   pauseWrites,
+  pendingMigrations,
   planUpgrade,
+  purgeBundleTables,
   readWritesPaused,
-  recordInLedger,
   resolveNodeRef,
   resumeWrites,
   type WritesPaused,
@@ -24,66 +30,65 @@ import {
 import { loadSchemaDirectory, loadValueMigrations, runFix, runUpgrade } from '@crombolo/schema'
 import {
   type BackupResult,
+  type BundleChain,
+  BundleConfigurationError,
   backupBefore,
   bootSchema,
   bootstrapDatabase,
+  bundleChainsFor,
+  CONTENT_OBJECT_TYPES,
+  CommandError,
+  type ContentCheckResult,
+  type ContentImportInput,
+  type ContentImportResult,
   type CromboloConfig,
+  checkBundleContent,
   checkSchemaDirectory,
-  componentAliasesIn,
   createFileIntake,
   createMediaPort,
+  installBundleContent,
   installDatabase,
   MediaFileStore,
   mediaStoreFor,
-  placeBlobs,
+  pendingBundleSteps,
+  planBundleUpgrades,
   readBlobs,
+  readBundle,
+  recordAudit,
   syncOptionsFor,
+  type TransferInput,
+  VERSION,
 } from '@crombolo/server'
 import {
-  type CheckOptions,
-  type ContentSet,
-  checkBundle,
+  bundleIdFor,
   exportBundle,
-  importBundle,
-  loadBundle,
-  loadResolutions,
-  type Resolution,
-  type TransferCheck,
+  isPackageName,
+  packageNameFor,
   writeBundle,
+  writeBundlePackage,
 } from '@crombolo/transfer'
-import {
-  applySections,
-  type CarriedSections,
-  carriedSections,
-  carriesSections,
-  planSections,
-  promoteBackups,
-  replacementsNeedingPermission,
-  type SectionFile,
-  type SectionOptions,
-  type SectionPlan,
-  type SectionResult,
-  stageBackups,
-} from './sections.ts'
 
-export {
-  isResolution,
-  RESOLUTIONS,
-  type Resolution,
-  type TransferCheck,
-} from '@crombolo/transfer'
-// The section half of an install, exported for the same reason the commands
-// are: tooling that applies a bundle without a terminal needs the plan too.
+// The installer lives in the server, so the backoffice can run it too; these
+// are exported for the same reason the commands are: tooling that applies a
+// bundle without a terminal needs the plan and the refusals as well.
 export {
   applySections,
+  type BundleSummary,
   type CarriedSections,
+  CONTENT_OBJECT_TYPES,
+  CommandError,
+  type ContentCheckResult,
+  type ContentImportInput,
+  type ContentImportResult,
   carriedSections,
   carriesSections,
   type FileAction,
   planSections,
   promoteBackups,
+  type ResolvedBundle,
   type RestoredFiles,
   RUN_BACKUP_DIR,
+  readBundle,
   replacementsNeedingPermission,
   restoreSectionFiles,
   type SectionFile,
@@ -91,299 +96,41 @@ export {
   type SectionPlan,
   type SectionResult,
   stageBackups,
-} from './sections.ts'
+  type TransferInput,
+  transferOptions,
+} from '@crombolo/server'
+export {
+  isResolution,
+  RESOLUTIONS,
+  type Resolution,
+  type TransferCheck,
+} from '@crombolo/transfer'
 export type { BackupResult, WritesPaused }
 
-/** The trees a content selector or placement may name. */
-export const CONTENT_OBJECT_TYPES = [ObjectTypes.Document, ObjectTypes.Media, ObjectTypes.Element]
-
-/** A refusal the caller should read: nothing was written. */
-export class CommandError extends Error {
-  constructor(
-    message: string,
-    readonly problems: string[] = [],
-  ) {
-    super(message)
-  }
-}
-
-export interface BundleSummary {
-  id: string
-  from: string
-  schemaVersion: string
-  schemaRevision: string
-  snapshot: string
-  nodes: number
-  blobsCarried: number
-  blobBytes: number
-}
-
-/**
- * The check an install that never reached the content reports.
- *
- * Nothing was examined, so nothing is outstanding: the refusal is in
- * `problems`, and a caller reading `outstanding.length` must not be told there
- * were content findings when there were none.
- */
-const emptyCheck = (bundleId = ''): TransferCheck => ({
-  bundleId,
-  findings: [],
-  outstanding: [],
-  plan: [],
-  counts: { create: 0, update: 0, unchanged: 0, skip: 0 },
-})
-
-function summarise(set: ContentSet): BundleSummary {
-  const carried = set.manifest.blobs.filter((blob) => blob.included)
-  return {
-    id: set.manifest.id,
-    from: set.manifest.provenance.siteName || '',
-    schemaVersion: set.manifest.provenance.schemaVersion,
-    schemaRevision: set.manifest.provenance.schemaRevision,
-    snapshot: set.manifest.snapshot,
-    nodes: set.nodes.length,
-    blobsCarried: carried.length,
-    blobBytes: carried.reduce((total, blob) => total + (blob.size ?? 0), 0),
-  }
-}
-
-/** Reads a bundle whole, or refuses: a half-copied bundle must never be checked as though complete. */
-export function readBundle(dir: string): {
-  set: ContentSet
-  blobs: ReadonlyMap<string, string>
-  /** The sections it carries beyond its content; empty for a content-only bundle. */
-  carried: CarriedSections
-} {
-  const loaded = loadBundle(dir)
-  const problems = loaded.problems.map((problem) => `${problem.file}: ${problem.message}`)
-  if (!loaded.set || problems.length > 0)
-    throw new CommandError(
-      'The bundle is incomplete or damaged; nothing was read from it.',
-      problems,
-    )
-  return { set: loaded.set, blobs: loaded.blobs, carried: carriedSections(loaded) }
-}
-
-export interface TransferInput extends SectionOptions {
-  /** The bundle's directory on this machine. */
-  dir: string
-  /** Where the bundle's roots go: a path or a key. */
-  under?: string
-  /** A decision per node key, on top of any the bundle carries. */
-  resolutions?: Record<string, Resolution>
-  resolveAll?: Resolution
-  allowMissingBlobs?: boolean
-}
-
-/** The options `check` and `import` share: saved decisions, then the caller's, then placement. */
-export async function transferOptions(
-  db: Db,
-  config: CromboloConfig,
-  set: ContentSet,
-  input: TransferInput,
-): Promise<{ options: CheckOptions; under: NodeRow | undefined; problems: string[] }> {
-  const saved = loadResolutions(input.dir, set.manifest.id)
-  const resolutions = { ...(saved.file?.byNode ?? {}), ...(input.resolutions ?? {}) }
-  const resolveAll = input.resolveAll ?? saved.file?.all ?? undefined
-  const underRef = input.under ?? saved.file?.under ?? undefined
-  let under: NodeRow | undefined
-  if (underRef) {
-    const resolved = await resolveNodeRef(db, CONTENT_OBJECT_TYPES, underRef)
-    if (!resolved.ok) throw new CommandError(describeRefFailure(underRef, resolved))
-    under = resolved.node
-  }
-  // Whether this environment has a media file is a question only its store can
-  // answer; without it `missing-blob` is a finding the check could never raise.
-  const store = await mediaStoreFor(config)
-  return {
-    options: {
-      under,
-      resolutions,
-      resolveAll,
-      componentAliases: componentAliasesIn(config.componentsDir),
-      allowMissingBlobs: input.allowMissingBlobs ?? false,
-      hasBlob: async (key: string) => Boolean(await store.get(key)),
-      backOfficePath: config.backOfficePath,
-    },
-    under,
-    problems: saved.problems,
-  }
-}
-
-export interface ContentCheckResult {
-  bundle: BundleSummary
-  under: string | null
-  check: TransferCheck
-  /** What the carried sections would do here; undefined for a content-only bundle. */
-  sections: SectionPlan | undefined
-  /** Nothing outstanding: the bundle would import cleanly. */
-  clean: boolean
-  /** The decisions this check ran with — the bundle's saved ones under the caller's. */
-  decisions: { all: Resolution | null; byNode: Record<string, Resolution> }
-  problems: string[]
-}
-
-/** Read-only: what importing a bundle here would do. Its findings go to the Changes dashboard. */
+/** Read-only: what installing a bundle here would do. Its findings go to the Changes dashboard. */
 export async function contentCheck(
   config: CromboloConfig,
   input: TransferInput,
 ): Promise<ContentCheckResult> {
-  const { set, carried } = readBundle(input.dir)
   const { db } = await bootstrapDatabase(config)
   try {
-    const prepared = await transferOptions(db, config, set, input)
-    const check = await checkBundle(db, set, prepared.options)
-    // Under this bundle's own scope, so two bundles in flight do not resolve each other's.
-    await writeReport(db, check.findings, { source: 'transfer', scope: set.manifest.id })
-    return {
-      bundle: summarise(set),
-      under: prepared.under ? (prepared.under.text ?? prepared.under.key) : null,
-      check,
-      sections: carriesSections(carried)
-        ? await planSections(db, config, carried, input)
-        : undefined,
-      clean: check.outstanding.length === 0,
-      decisions: {
-        all: prepared.options.resolveAll ?? null,
-        byNode: prepared.options.resolutions ?? {},
-      },
-      problems: prepared.problems,
-    }
+    return await checkBundleContent(db, config, input)
   } finally {
     await db.close()
   }
 }
 
-export interface ContentImportInput extends TransferInput {
-  publish?: boolean
-  label?: string
-  /** Postgres: the caller has taken a backup itself. */
-  backupTaken?: boolean
-}
-
-export interface ContentImportResult {
-  bundle: BundleSummary
-  backup: BackupResult
-  /**
-   * What the carried sections did, when the bundle carried any.
-   *
-   * Applied before the content and outside the content run's ledger entry: the
-   * files are now in `schema/` and the views directory, where the repository
-   * owns them — so a revert takes the content back and git takes the files.
-   */
-  sections: SectionResult | undefined
-  /** Where the originals of any replaced files were kept, for a revert. */
-  replacedFilesKept?: string | undefined
-  /** Undefined when the import was refused; then nothing was written. */
-  runId: string | undefined
-  check: TransferCheck
-  blobs: { placed: number; bytes: number } | null
-  published: number
-  publishFailures: { key: string; reason: string }[]
-  problems: string[]
-}
-
-/** Re-check, back up, then apply in one transaction and record the run. */
+/** Back up, re-check, then apply in one transaction and record the run. */
 export async function contentImport(
   config: CromboloConfig,
   input: ContentImportInput,
 ): Promise<ContentImportResult> {
-  const { set, blobs, carried } = readBundle(input.dir)
-  // The coarse layer, under the fine-grained revert: in-place conversion is not
-  // reversible by itself, so the same rule as `upgrade` applies here.
-  const backup = await backupBefore(config, {
-    reason: 'content-import',
-    backupTaken: input.backupTaken,
-  })
+  // Read before anything is opened or backed up, so a bundle that is not one is
+  // refused before a backup is taken on its behalf.
+  readBundle(input.bundle, config.siteDir)
   const { db } = await bootstrapDatabase(config)
   try {
-    const prepared = await transferOptions(db, config, set, input)
-    const started = performance.now()
-
-    /**
-     * Structure first, but planned before anything is written.
-     *
-     * The order is forced: content naming a type this bundle brings cannot pass
-     * a check until that type exists, so the schema has to land before the
-     * content is checked. Which means a blocking schema change has to be caught
-     * *before* the first file is written — otherwise a refused install leaves a
-     * half-applied site behind. `planSections` answers that from an overlay
-     * copy, so the site is untouched until it is known the schema can apply.
-     */
-    const plan = carriesSections(carried)
-      ? await planSections(db, config, carried, input)
-      : undefined
-    const refuse = (problems: string[]): ContentImportResult => ({
-      bundle: summarise(set),
-      backup,
-      runId: undefined,
-      check: emptyCheck(set.manifest.id),
-      blobs: null,
-      published: 0,
-      publishFailures: [],
-      problems,
-      sections: undefined,
-    })
-
-    if (plan?.schema?.classification === 'breaking')
-      return refuse([
-        'the schema this bundle carries cannot be applied here without data work',
-        ...plan.schema.findings,
-      ])
-
-    /**
-     * A file this site already has is not replaced without being asked.
-     *
-     * Every section is editable in the backoffice — a stylesheet, a template, a
-     * content type — so an overwrite destroys somebody's work, and the site
-     * may have no git to recover it from. Refused by name, like any other
-     * finding a person has to answer.
-     */
-    const needingPermission = plan ? replacementsNeedingPermission(plan, input) : []
-    if (needingPermission.length > 0)
-      return refuse([
-        `${needingPermission.length} file(s) here would be replaced; pass --replace-files to allow it`,
-        ...needingPermission.map((file: SectionFile) => file.path),
-      ])
-
-    // Staged whenever something *will* be replaced — which is decided by the
-    // plan, not by the permission check: by this point permission has been
-    // given, so the files needing it are exactly the ones to back up.
-    const willReplace = (plan?.files ?? []).some((file) => file.action === 'overwrite')
-    const staging = plan && willReplace ? stageBackups(config) : undefined
-    const sections = plan
-      ? await applySections(db, config, carried, { ...input, backupDir: staging })
-      : undefined
-    const result = await importBundle(db, set, {
-      ...prepared.options,
-      publish: input.publish ?? false,
-      nodeId: config.nodeId,
-      label: input.label,
-    })
-    await writeReport(db, result.check.findings, { source: 'transfer', scope: set.manifest.id })
-    const outcome: ContentImportResult = {
-      bundle: summarise(set),
-      backup,
-      runId: result.runId,
-      check: result.check,
-      blobs: null,
-      published: result.published.length,
-      publishFailures: result.publishFailures,
-      problems: prepared.problems,
-      sections,
-    }
-    if (!result.runId) return outcome
-    // The backups become the run's, so `content revert` can find them.
-    if (staging) outcome.replacedFilesKept = promoteBackups(config, staging, result.runId)
-    if (blobs.size > 0) outcome.blobs = await placeBlobs(await mediaStoreFor(config), blobs)
-    await recordInLedger(db, {
-      name: `content import ${set.manifest.id}`,
-      kind: 'transfer',
-      durationMs: Math.round(performance.now() - started),
-      appliedBy: config.nodeId,
-      note: `run ${result.runId}`,
-    })
-    return outcome
+    return await installBundleContent(db, config, input)
   } finally {
     await db.close()
   }
@@ -396,24 +143,38 @@ export interface ContentExportInput {
   drafts?: boolean
   withBlobs?: boolean
   withBlueprints?: boolean
+  /**
+   * The private package the export is written as. The name defaults to one
+   * derived from the bundle's id, the version to `1.0.0`.
+   */
+  package?: { name?: string; version?: string }
 }
 
 export interface ContentExportResult {
   bundleId: string
+  /** The package the files make up. */
+  package: { name: string; version: string }
   snapshot: string
   counts: Record<string, number>
   expected: { key: string; name: string; why: string }[]
-  /** The bundle's files, for the caller to write wherever it is going. */
+  /** The package's files — `package.json` and the payload under `content/` — for the caller to place. */
   files: { path: string; bytes?: Uint8Array; text?: string }[]
   blobs: { carried: number; bytes: number; missing: string[]; notCarried: number }
 }
 
-/** Writes nothing: returns the bundle's files for the caller to place. */
+/**
+ * Writes nothing: returns the export as a private package's files, for the
+ * caller to place. An environment's export is a bundle like any other, but one
+ * applied from its directory and never published or depended on.
+ */
 export async function contentExport(
   config: CromboloConfig,
   input: ContentExportInput,
 ): Promise<ContentExportResult> {
   if (input.roots.length === 0) throw new CommandError('An export needs at least one root.')
+  const requested = input.package?.name
+  if (requested !== undefined && !isPackageName(requested))
+    throw new CommandError(`"${requested}" is not a package name npm accepts.`)
   const { db } = await bootstrapDatabase(config)
   try {
     // A path is resolved against the tree it is exported from, and the key is
@@ -443,8 +204,13 @@ export async function contentExport(
       carried = read.bytes
       missing = read.missing
     }
+    const pkg = {
+      name: requested ?? packageNameFor(`export-${set.manifest.id}`),
+      version: input.package?.version ?? '1.0.0',
+    }
     return {
       bundleId: set.manifest.id,
+      package: pkg,
       snapshot: set.manifest.snapshot,
       counts: { ...set.manifest.counts },
       expected: set.manifest.dependencies.expected.map((e) => ({
@@ -452,7 +218,13 @@ export async function contentExport(
         name: e.name,
         why: e.why,
       })),
-      files: writeBundle(set, carried),
+      files: writeBundlePackage(writeBundle(set, carried), {
+        ...pkg,
+        id: bundleIdFor(pkg.name.replace(/^@[^/]+\//, '')),
+        label: `Content from ${config.siteName}`,
+        private: true,
+        peerRange: `^${VERSION}`,
+      }),
       blobs: {
         carried: carried.size,
         bytes: [...carried.values()].reduce((total, file) => total + file.length, 0),
@@ -465,7 +237,21 @@ export async function contentExport(
   }
 }
 
+/** The wired bundles' chains, checked as boot checks them, or a refusal naming every problem. */
+function chainsFor(config: CromboloConfig): BundleChain[] {
+  try {
+    return bundleChainsFor(config)
+  } catch (error) {
+    if (error instanceof BundleConfigurationError)
+      throw new CommandError('The configured bundles cannot be used.', error.problems)
+    throw error
+  }
+}
+
+const flat = (sql: string) => sql.replace(/\s+/g, ' ').trim()
+
 async function upgradeContext(config: CromboloConfig, set: Record<string, unknown>) {
+  const chains = chainsFor(config)
   const db = await connect({ file: config.sqliteFile })
   const node = { nodeId: config.nodeId, revision: config.schemaRevision }
   const loaded = () => loadSchemaDirectory(config.schemaDir)
@@ -476,33 +262,45 @@ async function upgradeContext(config: CromboloConfig, set: Record<string, unknow
     migrations: await loadValueMigrations(config.schemaDir),
     backOfficePath: config.backOfficePath,
   })
-  return { db, node, loaded, syncNode, checkOptions }
+  return { db, node, loaded, syncNode, checkOptions, chains }
+}
+
+export interface PlannedStepResult {
+  name: string
+  kind: string
+  release: string | null
+  statements: string[]
+  unplannable: string | null
 }
 
 export interface UpgradePlanResult {
-  steps: {
-    name: string
-    kind: string
-    release: string | null
-    statements: string[]
-    unplannable: string | null
-  }[]
+  steps: PlannedStepResult[]
+  /** Each wired bundle that owns tables, with the steps it would run after core's. */
+  bundles: { id: string; name: string; steps: PlannedStepResult[] }[]
   site: { checked: boolean; action: string | null; classification: string | null }
 }
 
+const plannedStep = (step: PlannedStep): PlannedStepResult => ({
+  name: step.name,
+  kind: step.kind,
+  release: step.release ?? null,
+  statements: (step.statements ?? []).map(flat),
+  unplannable: step.unplannable ?? null,
+})
+
 /** The DDL every pending framework step would run, and what the site's schema would do. Writes nothing. */
 export async function upgradePlan(config: CromboloConfig): Promise<UpgradePlanResult> {
-  const { db, node } = await upgradeContext(config, {})
+  const { db, node, chains } = await upgradeContext(config, {})
   try {
     const steps = await planUpgrade(db, cromboloPlan)
+    const bundles = await planBundleUpgrades(db, chains)
     const check = await checkSchemaDirectory(db, config, node)
     return {
-      steps: steps.map((step) => ({
-        name: step.name,
-        kind: step.kind,
-        release: step.release ?? null,
-        statements: (step.statements ?? []).map((sql) => sql.replace(/\s+/g, ' ').trim()),
-        unplannable: step.unplannable ?? null,
+      steps: steps.map(plannedStep),
+      bundles: bundles.map((bundle) => ({
+        id: bundle.id,
+        name: bundle.name,
+        steps: bundle.steps.map(plannedStep),
       })),
       site: {
         checked: check.siteChecked,
@@ -520,11 +318,17 @@ export async function upgradeCheck(
   config: CromboloConfig,
   input: { set?: Record<string, unknown> } = {},
 ) {
-  const { db, node } = await upgradeContext(config, input.set ?? {})
+  const { db, node, chains } = await upgradeContext(config, input.set ?? {})
   try {
     const report = await checkSchemaDirectory(db, config, node, { set: input.set ?? {} })
     if (report.siteChecked) await writeReport(db, report.findings, { source: 'upgrade' })
+    const bundles = await pendingBundleSteps(db, chains)
     return {
+      bundles: bundles.map((bundle) => ({
+        id: bundle.id,
+        name: bundle.name,
+        pending: bundle.pending.map((step) => ({ name: step.name, kind: step.kind ?? 'expand' })),
+      })),
       siteChecked: report.siteChecked,
       classification: report.classification,
       findings: report.findings,
@@ -542,9 +346,12 @@ export async function upgradeFix(
   input: { set?: Record<string, unknown>; backupTaken?: boolean } = {},
 ) {
   const backup = await backupBefore(config, { reason: 'fix', backupTaken: input.backupTaken })
-  const { db, loaded, syncNode, checkOptions } = await upgradeContext(config, input.set ?? {})
+  const { db, loaded, syncNode, checkOptions, chains } = await upgradeContext(
+    config,
+    input.set ?? {},
+  )
   try {
-    await installDatabase(db, config)
+    await installDatabase(db, config, chains)
     const fix = await runFix(db, loaded(), syncNode(), {
       ...(await checkOptions()),
       by: config.nodeId,
@@ -574,6 +381,8 @@ export type UpgradeRunResult =
       action: 'upgraded'
       backup: BackupResult
       frameworkApplied: string[]
+      /** Each bundle's steps that ran, after core's. */
+      bundlesApplied: { id: string; applied: string[] }[]
       schema: { action: string; version: string | null; revision: string | null } | null
     }
 
@@ -583,9 +392,19 @@ export async function upgradeRun(
   input: { force?: string; set?: Record<string, unknown>; backupTaken?: boolean } = {},
 ): Promise<UpgradeRunResult> {
   const backup = await backupBefore(config, { reason: 'upgrade', backupTaken: input.backupTaken })
-  const { db, loaded, syncNode, checkOptions } = await upgradeContext(config, input.set ?? {})
+  const { db, loaded, syncNode, checkOptions, chains } = await upgradeContext(
+    config,
+    input.set ?? {},
+  )
   try {
-    await installDatabase(db, config)
+    // Read before anything runs: `installDatabase` applies core's steps and then
+    // each bundle's, so this is what the upgrade itself applied.
+    const corePending = (await pendingMigrations(db, cromboloPlan)).map((step) => step.name)
+    const bundlesPending = await pendingBundleSteps(db, chains)
+    await installDatabase(db, config, chains)
+    const bundlesApplied = bundlesPending
+      .filter((bundle) => bundle.pending.length > 0)
+      .map((bundle) => ({ id: bundle.id, applied: bundle.pending.map((step) => step.name) }))
     const result = await runUpgrade(db, loaded(), syncNode(), {
       ...(await checkOptions()),
       by: config.nodeId,
@@ -598,11 +417,14 @@ export async function upgradeRun(
         backup,
         reasons: result.reasons.map((f) => ({ kind: f.kind, message: f.message, link: f.link })),
       }
-    if (result.action === 'nothing') return { action: 'nothing', backup }
+    const frameworkApplied = [...corePending, ...result.frameworkApplied]
+    if (result.action === 'nothing' && frameworkApplied.length === 0 && bundlesApplied.length === 0)
+      return { action: 'nothing', backup }
     return {
       action: 'upgraded',
       backup,
-      frameworkApplied: result.frameworkApplied,
+      frameworkApplied,
+      bundlesApplied,
       schema: result.sync
         ? {
             action: result.sync.action,
@@ -746,6 +568,44 @@ export async function backup(
   })
 }
 
+export interface CommandAudit {
+  category: AuditCategory
+  action: string
+  /** The command as typed, without its arguments, which can hold a password. */
+  command: string
+  entityType?: string
+  entityKey?: string
+}
+
+/**
+ * Records a command that changed this environment, in the audit log, as the
+ * account that ran it — `CROMBOLO_ACTOR` when a pipeline names who it runs for.
+ * Never fails the command: what it records has already happened.
+ */
+export async function recordCommand(config: CromboloConfig, entry: CommandAudit): Promise<void> {
+  let actor = Bun.env.CROMBOLO_ACTOR
+  try {
+    actor ??= userInfo().username
+  } catch {
+    actor ??= undefined
+  }
+  try {
+    await withDatabase(config, (db) =>
+      recordAudit(db, {
+        category: entry.category,
+        action: entry.action,
+        source: 'cli',
+        userName: actor ?? null,
+        entityType: entry.entityType ?? null,
+        entityKey: entry.entityKey ?? null,
+        detail: entry.command,
+      }),
+    )
+  } catch {
+    // No database to write to, or one without the log yet: the command still happened.
+  }
+}
+
 async function withDatabase<T>(config: CromboloConfig, use: (db: Db) => Promise<T>): Promise<T> {
   const db = await connect({ file: config.sqliteFile })
   try {
@@ -773,3 +633,54 @@ export function resumeEditing(config: CromboloConfig): Promise<void> {
 export function editingPaused(config: CromboloConfig): Promise<WritesPaused | undefined> {
   return withDatabase(config, readWritesPaused)
 }
+
+export interface BundlePurgePlan {
+  id: string
+  /** The tables that would be dropped, as the database names them. */
+  tables: string[]
+}
+
+/** Refuses a purge of a bundle the site still wires: its code would recreate what was dropped. */
+function refuseWired(config: CromboloConfig, id: string): void {
+  if (config.bundles.some((bundle) => bundle.id === id))
+    throw new CommandError(
+      `The bundle "${id}" is still wired in crombolo.config.ts. Take it out of \`bundles\` and deploy that first.`,
+    )
+}
+
+/** Read-only: what purging a bundle would drop. */
+export async function bundlePurgePlan(
+  config: CromboloConfig,
+  id: string,
+): Promise<BundlePurgePlan> {
+  refuseWired(config, id)
+  const db = await connect({ file: config.sqliteFile })
+  try {
+    return { id, tables: await bundleTablesIn(db, id) }
+  } finally {
+    await db.close()
+  }
+}
+
+/**
+ * Backs up, then drops every table under the bundle's prefix and forgets its
+ * state, ledgered as a `purge` against the bundle.
+ */
+export async function bundlePurge(
+  config: CromboloConfig,
+  id: string,
+  input: { backupTaken?: boolean } = {},
+): Promise<{ backup: BackupResult; dropped: string[] }> {
+  refuseWired(config, id)
+  const backup = await backupBefore(config, { reason: 'purge', backupTaken: input.backupTaken })
+  const db = await connect({ file: config.sqliteFile })
+  try {
+    const dropped = await purgeBundleTables(db, id, {
+      by: config.nodeId,
+      stateKey: bundleStateKey(id),
+    })
+    return { backup, dropped }
+  } finally {
+    await db.close()
+  }
+}