@crombolo/server 0.11.0 → 0.13.1

package/src/boot-failure.ts

@@ -0,0 +1,147 @@
+/**
+ * Why a server could not start, said so a person can fix it, and how long to
+ * wait before trying again. Pure: `crombolo start` serves the page and does the
+ * waiting. Nothing here may carry a secret — the database is named by host and
+ * database only, never by its URL.
+ */
+import { MigrationStepError } from '@crombolo/data'
+import { DatabaseNotReadyError, UpgradePendingError } from './database.ts'
+import { SchemaBootError } from './schema.ts'
+
+export interface BootFailure {
+  title: string
+  detail: string
+  /** The setting or command that fixes it. */
+  remedy: string
+}
+
+const sqlState = (error: { code?: unknown; errno?: unknown }) =>
+  typeof error.errno === 'string' ? error.errno : typeof error.code === 'string' ? error.code : ''
+
+export function describeBootFailure(error: unknown, database: string): BootFailure {
+  if (error instanceof UpgradePendingError)
+    return {
+      title: 'An upgrade is waiting',
+      detail: `The database at ${database} needs upgrading before this version can use it.`,
+      remedy: 'Run `crombolo upgrade check`, then `crombolo upgrade`. This page retries by itself.',
+    }
+  if (error instanceof DatabaseNotReadyError)
+    return {
+      title: 'The database has not been prepared yet',
+      detail: `The database at ${database} is behind this version, and this server only reads.`,
+      remedy: 'Start the server that edits the site first, or run `crombolo upgrade`.',
+    }
+  if (error instanceof MigrationStepError)
+    return {
+      title: 'An upgrade step failed',
+      detail: error.message,
+      remedy: 'Fix the cause named above; the next attempt carries on from that step.',
+    }
+  if (error instanceof SchemaBootError)
+    return {
+      title: "The site's content types could not be loaded",
+      detail: error.message,
+      remedy: 'Correct the files named above in `schema/`, then deploy again.',
+    }
+  const e = (error ?? {}) as { code?: unknown; errno?: unknown; message?: unknown }
+  const state = sqlState(e)
+  if (state === 'ERR_POSTGRES_CONNECTION_REFUSED' || state === 'ECONNREFUSED')
+    return {
+      title: "Can't reach the database",
+      detail: `Nothing answered at ${database}.`,
+      remedy:
+        'Check the host and port in `CROMBOLO_POSTGRES_URL`, and that the database server is running and reachable from here.',
+    }
+  if (state === '28P01' || state === '28000')
+    return {
+      title: 'The database refused the sign-in',
+      detail: `${database} did not accept the user name and password it was given.`,
+      remedy: 'Check the user name and password in `CROMBOLO_POSTGRES_URL`.',
+    }
+  if (state === '3D000')
+    return {
+      title: 'The database does not exist',
+      detail: `The server at ${database} has no database by that name.`,
+      remedy: 'Create the database, or correct its name in `CROMBOLO_POSTGRES_URL`.',
+    }
+  if (state === 'SQLITE_CANTOPEN')
+    return {
+      title: "Can't open the database file",
+      detail: `${database} could not be opened or created.`,
+      remedy:
+        'Check `CROMBOLO_SQLITE_FILE`, and that its folder exists and this server may write to it.',
+    }
+  if (/no connection string/i.test(String(e.message ?? '')))
+    return {
+      title: 'No database is configured',
+      detail: 'Postgres was selected, but no connection string was given.',
+      remedy: 'Set `CROMBOLO_POSTGRES_URL`, or unset `CROMBOLO_DB` to use SQLite.',
+    }
+  return {
+    title: 'The site could not start',
+    detail: 'Something unexpected stopped it. The server log has the details.',
+    remedy: 'Read the latest error in the server log.',
+  }
+}
+
+/** Waits between attempts: doubling from `baseMs`, never longer than `capMs`. */
+export function bootRetryDelays(attempts: number, baseMs = 2_000, capMs = 60_000): number[] {
+  return Array.from({ length: Math.max(0, attempts - 1) }, (_, i) =>
+    Math.min(capMs, baseMs * 2 ** i),
+  )
+}
+
+const escapeHtml = (value: string): string =>
+  value.replace(
+    /[&<>"']/g,
+    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] as string,
+  )
+
+const withCode = (value: string) =>
+  escapeHtml(value).replace(/`([^`]+)`/g, (_, code: string) => `<code>${code}</code>`)
+
+/** The page a starting server serves while it cannot start. */
+export function bootFailurePage(
+  failure: BootFailure | undefined,
+  progress: { attempt: number; attempts: number; retryInSeconds: number | undefined },
+): string {
+  const title = failure?.title ?? 'The site is starting'
+  const next =
+    progress.retryInSeconds === undefined
+      ? 'It will not try again; the server is stopping.'
+      : `Trying again in ${progress.retryInSeconds} seconds (attempt ${progress.attempt} of ${progress.attempts}).`
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<meta http-equiv="refresh" content="10">
+<title>${escapeHtml(title)}</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; min-height: 100vh; display: grid; place-items: center;
+    font: 16px/1.6 ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+    background: #f6f5f3; color: #1b1b1b; }
+  main { max-width: 34rem; padding: 2.5rem 1rem; }
+  h1 { font-size: 1.6rem; margin: 0 0 .75rem; }
+  p { margin: 0 0 1rem; white-space: pre-line; }
+  code { font-size: .9em; background: #e9e7e2; padding: .1em .35em; border-radius: 3px; }
+  .fine { font-size: .85rem; color: #6b6b63; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #16171a; color: #e8e6e3; }
+    code { background: #26282c; }
+    .fine { color: #9a9a93; }
+  }
+</style>
+</head>
+<body>
+<main>
+  <h1>${escapeHtml(title)}</h1>
+  ${failure ? `<p>${withCode(failure.detail)}</p>\n  <p><strong>To fix it:</strong> ${withCode(failure.remedy)}</p>` : '<p>This takes a few seconds.</p>'}
+  <p class="fine">${escapeHtml(next)}</p>
+</main>
+</body>
+</html>
+`
+}

package/src/bundle-install.ts

@@ -25,11 +25,13 @@ import {
 } from '@crombolo/backoffice-host'
 import { ObjectTypes } from '@crombolo/core'
 import {
+  answersByNode,
   type Db,
   describeRefFailure,
   type NodeRow,
   recordInLedger,
   resolveNodeRef,
+  TransferAnswerRepository,
   writeReport,
 } from '@crombolo/data'
 import {
@@ -40,8 +42,15 @@ import {
   isPackageName,
   loadBundle,
   loadResolutions,
+  mergeResolutions,
+  type NodeResolutions,
+  openBundle,
   type Resolution,
+  rehearsePublish,
+  SealedFileError,
   type TransferCheck,
+  WrongPassphraseError,
+  writeResolutions,
 } from '@crombolo/transfer'
 import { type BackupResult, backupBefore } from './backup.ts'
 import {
@@ -75,6 +84,9 @@ export class CommandError extends Error {
   }
 }
 
+/** The bundle is encrypted, and the passphrase given does not open it, or none was. */
+export class PassphraseError extends CommandError {}
+
 export interface BundleSummary {
   id: string
   from: string
@@ -95,10 +107,14 @@ export interface ResolvedBundle {
   payloadDir: string
   /** Whether it was found as one of the site's dependencies rather than a directory. */
   dependency: boolean
+  /** The package's directory. */
+  directory: string
   set: ContentSet
   blobs: ReadonlyMap<string, string>
   /** The sections it carries beyond its content; empty for a content-only bundle. */
   carried: CarriedSections
+  /** A carried media file's bytes as exported: opened, when the bundle sealed them. */
+  openBlob: (key: string, bytes: Uint8Array) => Uint8Array
 }
 
 /** Where a package directory or a dependency's name points, before anything is read. */
@@ -122,7 +138,7 @@ function locate(target: string, siteDir: string): { directory: string; dependenc
  * The bundle a path or a package name names, read whole, or a refusal: a
  * half-copied bundle must never be checked as though complete.
  */
-export function readBundle(target: string, siteDir: string): ResolvedBundle {
+export function readBundle(target: string, siteDir: string, passphrase?: string): ResolvedBundle {
   const { directory, dependency } = locate(target, siteDir)
   const json = readPackageJson(join(directory, 'package.json'))
   if (!json) {
@@ -154,13 +170,34 @@ export function readBundle(target: string, siteDir: string): ResolvedBundle {
       'The bundle is incomplete or damaged; nothing was read from it.',
       problems,
     )
+  // Opened only when given the passphrase: without one the set stays sealed,
+  // and the check says what it needs rather than comparing what it cannot read.
+  let opened: ReturnType<typeof openBundle> = {
+    set: loaded.set,
+    people: undefined,
+    openBlob: (_key, bytes) => bytes,
+  }
+  if (passphrase !== undefined && passphrase !== '')
+    try {
+      opened = openBundle(loaded, passphrase)
+    } catch (error) {
+      if (error instanceof WrongPassphraseError)
+        throw new PassphraseError(
+          'The passphrase does not open this bundle; nothing was read from it.',
+        )
+      if (error instanceof SealedFileError)
+        throw new CommandError('The bundle is damaged; nothing was read from it.', [error.message])
+      throw error
+    }
   return {
     package: pkg,
     payloadDir: pkg.contentDir,
     dependency,
-    set: loaded.set,
+    directory,
+    set: opened.set,
     blobs: loaded.blobs,
     carried: carriedSections(loaded),
+    openBlob: opened.openBlob,
   }
 }
 
@@ -200,13 +237,22 @@ export interface TransferInput extends SectionOptions {
   bundle: 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>
+  /** Decisions by node key, on top of any the bundle carries: `"*"` and per property. */
+  resolutions?: Record<string, NodeResolutions>
   resolveAll?: Resolution
   allowMissingBlobs?: boolean
+  /** Publish what was live at the source; the check then says which pages would be refused. */
+  publish?: boolean
+  /** Who asked, recorded on the pending import. */
+  by?: string
+  /** Opens what the bundle sealed; used for this request only, never stored. */
+  passphrase?: string
 }
 
-/** The options `check` and `import` share: saved decisions, then the caller's, then placement. */
+/**
+ * The options `check` and `import` share: the bundle's saved decisions, then
+ * those given in the backoffice, then the caller's; then placement.
+ */
 export async function transferOptions(
   db: Db,
   config: CromboloConfig,
@@ -214,7 +260,16 @@ export async function transferOptions(
   input: Omit<TransferInput, 'bundle'>,
 ): Promise<{ options: CheckOptions; under: NodeRow | undefined; problems: string[] }> {
   const saved = loadResolutions(bundle.payloadDir, bundle.set.manifest.id)
-  const resolutions = { ...(saved.file?.byNode ?? {}), ...(input.resolutions ?? {}) }
+  const answers = new TransferAnswerRepository(db)
+  const given = answersByNode(await answers.answers(bundle.set.manifest.id)) as Record<
+    string,
+    NodeResolutions
+  >
+  const pending = await answers.pending(bundle.set.manifest.id)
+  const resolutions = mergeResolutions(
+    mergeResolutions(saved.file?.byNode ?? {}, given),
+    input.resolutions ?? {},
+  )
   const resolveAll = input.resolveAll ?? saved.file?.all ?? undefined
   const underRef = input.under ?? saved.file?.under ?? undefined
   let under: NodeRow | undefined
@@ -232,7 +287,7 @@ export async function transferOptions(
       resolutions,
       resolveAll,
       componentAliases: componentAliasesIn(config.componentsDir),
-      allowMissingBlobs: input.allowMissingBlobs ?? false,
+      allowMissingBlobs: input.allowMissingBlobs ?? pending?.allowMissingBlobs ?? false,
       hasBlob: async (key: string) => Boolean(await store.get(key)),
       backOfficePath: config.backOfficePath,
     },
@@ -251,8 +306,10 @@ export interface ContentCheckResult {
   sections: SectionPlan | undefined
   /** Nothing outstanding: the bundle would import cleanly. */
   clean: boolean
+  /** With `publish`: the pages the import would not publish, and the reason publish gives. */
+  publishRefusals: { key: string; reason: string }[]
   /** The decisions this check ran with — the bundle's saved ones under the caller's. */
-  decisions: { all: Resolution | null; byNode: Record<string, Resolution> }
+  decisions: { all: Resolution | null; byNode: Record<string, NodeResolutions> }
   problems: string[]
 }
 
@@ -262,10 +319,30 @@ export async function checkBundleContent(
   config: CromboloConfig,
   input: TransferInput,
 ): Promise<ContentCheckResult> {
-  const bundle = readBundle(input.bundle, config.siteDir)
+  const bundle = readBundle(input.bundle, config.siteDir, input.passphrase)
   const set = bundle.set
   const prepared = await transferOptions(db, config, bundle, input)
   const check = await checkBundle(db, set, prepared.options)
+  await recordPending(db, bundle, input, prepared.options.allowMissingBlobs ?? false)
+  // Rehearsed rather than predicted, so the refusals are publish's own, word
+  // for word; only once nothing is outstanding, since the import stops there.
+  const refusals =
+    input.publish && check.outstanding.length === 0
+      ? ((await rehearsePublish(db, set, prepared.options)) ?? [])
+      : []
+  const names = new Map(set.nodes.map((node) => [node.key, node.variants[0]?.name ?? node.key]))
+  for (const refusal of refusals)
+    check.findings.push({
+      kind: 'auto',
+      code: 'publish-refused',
+      subjectType: 'document',
+      subjectKey: refusal.key,
+      subjectName: names.get(refusal.key) ?? refusal.key,
+      propertyAlias: null,
+      culture: null,
+      message: `"${names.get(refusal.key) ?? refusal.key}" would not be published: ${refusal.reason}`,
+      link: null,
+    })
   // 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 {
@@ -277,9 +354,10 @@ export async function checkBundleContent(
       ? await planSections(db, config, bundle.carried, input)
       : undefined,
     clean: check.outstanding.length === 0,
+    publishRefusals: refusals,
     decisions: {
       all: prepared.options.resolveAll ?? null,
-      byNode: prepared.options.resolutions ?? {},
+      byNode: { ...(prepared.options.resolutions ?? {}) },
     },
     problems: prepared.problems,
   }
@@ -314,14 +392,66 @@ export interface ContentImportResult {
   problems: string[]
 }
 
+/**
+ * What the dashboard needs to run this bundle's import again: where it was
+ * found and what it was asked to do. A directory is this server's path.
+ */
+async function recordPending(
+  db: Db,
+  bundle: ResolvedBundle,
+  input: TransferInput,
+  allowMissingBlobs: boolean,
+): Promise<void> {
+  const manifest = bundle.set.manifest
+  await new TransferAnswerRepository(db).recordCheck({
+    bundleId: manifest.id,
+    label: manifest.label ?? (bundle.package.name || bundle.package.packageName),
+    target: bundle.dependency ? bundle.package.packageName : bundle.directory,
+    targetKind: bundle.dependency ? 'package' : 'directory',
+    under: input.under ?? null,
+    publish: input.publish ?? false,
+    allowMissingBlobs,
+    checkedAt: new Date(),
+    checkedBy: input.by ?? null,
+  })
+}
+
+/**
+ * The decisions an import of this bundle would run with — saved, then given
+ * in the backoffice — as the `resolutions.json` the CLI's `--save` writes.
+ */
+export async function pendingResolutionsFile(
+  db: Db,
+  config: CromboloConfig,
+  bundleId: string,
+): Promise<string | undefined> {
+  const pending = await new TransferAnswerRepository(db).pending(bundleId)
+  if (!pending) return undefined
+  const bundle = readBundle(pending.target, config.siteDir)
+  const saved = loadResolutions(bundle.payloadDir, bundleId)
+  const given = answersByNode(await new TransferAnswerRepository(db).answers(bundleId))
+  return writeResolutions({
+    bundleId,
+    under: pending.under ?? saved.file?.under ?? null,
+    all: saved.file?.all ?? null,
+    byNode: mergeResolutions(saved.file?.byNode ?? {}, given as Record<string, NodeResolutions>),
+  })
+}
+
 /** Back up, re-check, then apply in one transaction and record the run. */
 export async function installBundleContent(
   db: Db,
   config: CromboloConfig,
   input: ContentImportInput,
 ): Promise<ContentImportResult> {
-  const bundle = readBundle(input.bundle, config.siteDir)
+  const bundle = readBundle(input.bundle, config.siteDir, input.passphrase)
   const { set, blobs, carried } = bundle
+  // Before the backup and the sections: nothing of a bundle that cannot be
+  // opened is applied.
+  if (set.sealed)
+    throw new PassphraseError(
+      'This bundle is encrypted: give the passphrase it was exported with. Nothing was written.',
+    )
   // 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, {
@@ -402,10 +532,15 @@ export async function installBundleContent(
     problems: prepared.problems,
     sections,
   }
-  if (!result.runId) return outcome
+  if (!result.runId) {
+    await recordPending(db, bundle, input, prepared.options.allowMissingBlobs ?? false)
+    return outcome
+  }
+  await new TransferAnswerRepository(db).clear(set.manifest.id)
   // 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)
+  if (blobs.size > 0)
+    outcome.blobs = await placeBlobs(await mediaStoreFor(config), blobs, bundle.openBlob)
   await recordInLedger(db, {
     name: `content import ${set.manifest.id}`,
     kind: 'transfer',

package/src/bundles.ts

@@ -40,6 +40,7 @@
  * Deliberately not offered: raw SQL, a `Db`, and anything that writes the
  * site's files.
  */
+
 import { hasCultureAccess, hasSection, type Principal } from '@crombolo/api-management'
 import { BUNDLE_ID, type BundlePackage, peerRangeProblem } from '@crombolo/backoffice-host'
 import {
@@ -60,6 +61,8 @@ import {
   type RedirectTargetKind,
 } from '@crombolo/data'
 import { normaliseRedirectPath, type PublishedCache } from '@crombolo/render'
+import type { BundleForms } from './form-types.ts'
+import type { BundleEvents } from './webhooks.ts'
 
 /** The segment every bundle's routes hang below, inside the plugin API. */
 export const BUNDLE_API_SEGMENT = 'bundle'
@@ -232,6 +235,17 @@ export interface ServerBundle<
   routes: readonly ServerBundleRoute<C, T>[]
   /** Tables the bundle owns, from `defineBundleTables`, under its own id. */
   tables?: T
+  /**
+   * Form field and workflow types it adds. Unlike its routes and tables these
+   * are honoured on every node, because forms render and submit on `web` nodes.
+   */
+  forms?: BundleForms
+  /**
+   * Handlers for webhook events, by alias. Each event reaches each handler
+   * through the webhook delivery queue: once per cluster, after the change,
+   * retried on failure, and in the delivery log (docs/webhooks.md).
+   */
+  events?: BundleEvents
 }
 
 /** A bundle as mounted, with the prefix its routes answer below. */

package/src/busy.ts

@@ -0,0 +1,13 @@
+/** Contention a write could not get past, answered as a retryable 503 rather than a 500. */
+import { problemResponse, serviceBusy } from '@crombolo/core'
+import { ContentBusyError, classifyContention } from '@crombolo/data'
+
+/** The response for an error that is lock contention; undefined for anything else. */
+export function busyResponse(error: unknown): Response | undefined {
+  const contention = classifyContention(error)
+  if (!contention) return undefined
+  const busy = error instanceof ContentBusyError ? error : new ContentBusyError(contention)
+  return problemResponse(serviceBusy(busy.message), {
+    'retry-after': String(busy.retryAfterSeconds),
+  })
+}

package/src/config.ts

@@ -1,5 +1,6 @@
 import { hostname, tmpdir } from 'node:os'
 import { join, resolve } from 'node:path'
+import type { DeliveryApiOptions } from '@crombolo/api-delivery'
 import { DEFAULT_BACKOFFICE_PATH } from '@crombolo/core'
 import { DEFAULT_RENDER_TIMEOUT_MS, type RedirectRule, type SnapshotLimits } from '@crombolo/render'
 import type { AssistantConfig } from './assistant.ts'
@@ -65,8 +66,15 @@ export interface CromboloConfig {
   /** SQLite file, or ':memory:'. Ignored when CROMBOLO_DB=postgres. */
   sqliteFile: string
   adminLogin: string
-  /** When unset, a password is generated on first run and printed once. */
+  /**
+   * Seeds the first administrator of a fresh database. Unset in development, one
+   * is generated and printed; unset in production, the site waits to be set up.
+   */
   adminPassword: string | undefined
+  /** Guards "Set up your new site". Chosen by the owner; never printed, logged or shown. */
+  setupCode: string | undefined
+  /** Seals secrets kept in the database, such as a webhook's headers; never stored. */
+  secretKey: string | undefined
   /**
    * The `__Host-` cookie prefix requires Secure. Browsers treat http://localhost
    * as secure, so this stays on in local development.
@@ -242,6 +250,13 @@ export interface CromboloConfig {
    * answers on. Every field may also be set in the backoffice, which wins.
    */
   seo: SeoConfig
+  /**
+   * Umbraco's Delivery API (`docs/delivery-api.md`): off unless enabled.
+   * `CROMBOLO_DELIVERY_API`, `CROMBOLO_DELIVERY_API_KEY`,
+   * `CROMBOLO_DELIVERY_API_PUBLIC` and `CROMBOLO_DELIVERY_API_MEDIA`; member
+   * sign-in is configured here, since its clients and secrets are a list.
+   */
+  deliveryApi: DeliveryApiOptions
   /**
    * Bundles whose server half this site runs, each the result of calling the
    * factory its package exports. Imported and listed here by hand on purpose:
@@ -257,6 +272,16 @@ export interface CromboloConfig {
    * deploy turns it off, and an install can decline it for itself.
    */
   applyBundleContentOnInstall: boolean
+  /**
+   * Whether the Packages section may install and remove packages on the running
+   * site (`bun add` on the node that served the request). Off, the Marketplace
+   * still lists packages and says to add them to `package.json` and deploy:
+   * what a site of several nodes, or of containers that start afresh, needs —
+   * an install there reaches one node and is lost at its next restart. On unless
+   * set, or unless a schema store is configured, which says the same thing
+   * about the nodes' disks. `CROMBOLO_RUNTIME_INSTALLS`.
+   */
+  runtimeInstalls: boolean
   /**
    * Where the Packages section's Marketplace sends someone browsing for
    * extensions. Never framed — npm refuses to be framed — so the native view
@@ -393,6 +418,8 @@ export function loadConfig(
     sqliteFile: Bun.env.CROMBOLO_SQLITE_FILE ?? DEFAULTS.sqliteFile,
     adminLogin: Bun.env.CROMBOLO_ADMIN_LOGIN ?? DEFAULTS.adminLogin,
     adminPassword: Bun.env.CROMBOLO_ADMIN_PASSWORD,
+    setupCode: Bun.env.CROMBOLO_SETUP_CODE,
+    secretKey: Bun.env.CROMBOLO_SECRET_KEY,
     secureCookies: Bun.env.CROMBOLO_INSECURE_COOKIES !== 'true',
     siteName: Bun.env.CROMBOLO_SITE_NAME ?? DEFAULTS.siteName,
     siteDir: cwd,
@@ -478,10 +505,21 @@ export function loadConfig(
     redirects: [],
     trackRedirects: Bun.env.CROMBOLO_TRACK_REDIRECTS !== 'false',
     applyBundleContentOnInstall: Bun.env.CROMBOLO_APPLY_BUNDLE_CONTENT !== 'false',
+    // Resolved again below, once it is known whether a store was configured.
+    runtimeInstalls: Bun.env.CROMBOLO_RUNTIME_INSTALLS !== 'false',
     seo: stripUndefined({
       sitemap: envFlag(Bun.env.CROMBOLO_SITEMAP),
       indexable: envFlag(Bun.env.CROMBOLO_INDEXABLE),
     }),
+    deliveryApi: stripUndefined({
+      enabled: envFlag(Bun.env.CROMBOLO_DELIVERY_API),
+      apiKey: Bun.env.CROMBOLO_DELIVERY_API_KEY || undefined,
+      publicAccess: envFlag(Bun.env.CROMBOLO_DELIVERY_API_PUBLIC),
+      media:
+        envFlag(Bun.env.CROMBOLO_DELIVERY_API_MEDIA) === undefined
+          ? undefined
+          : { enabled: envFlag(Bun.env.CROMBOLO_DELIVERY_API_MEDIA) },
+    }),
     // No environment variable: a bundle is an import, which is code.
     bundles: [],
     marketplaceUrl: Bun.env.CROMBOLO_MARKETPLACE_URL ?? DEFAULTS.marketplaceUrl,
@@ -493,6 +531,11 @@ export function loadConfig(
   const merged: CromboloConfig = { ...fromEnv, ...stripUndefined(overrides) }
   // Field by field, so a site setting its title suffix keeps the environment's switches.
   merged.seo = { ...fromEnv.seo, ...stripUndefined(overrides.seo ?? {}) }
+  merged.deliveryApi = {
+    ...fromEnv.deliveryApi,
+    ...stripUndefined(overrides.deliveryApi ?? {}),
+    media: { ...fromEnv.deliveryApi.media, ...(overrides.deliveryApi?.media ?? {}) },
+  }
   // A schema store makes backoffice writes durable, so it carries writability with
   // it — that is the point of configuring one. An explicit setting still wins.
   if (
@@ -502,6 +545,15 @@ export function loadConfig(
   ) {
     merged.schemaWritable = true
   }
+  // Likewise a store says the nodes' disks do not last, so an install on one of
+  // them would not either. An explicit setting still wins.
+  if (
+    merged.schemaStore &&
+    Bun.env.CROMBOLO_RUNTIME_INSTALLS === undefined &&
+    overrides.runtimeInstalls === undefined
+  ) {
+    merged.runtimeInstalls = false
+  }
   // Relative paths are relative to the site, not to wherever the process started.
   merged.siteDir = resolve(cwd, merged.siteDir)
   // Against the site rather than the working directory: it has to sit where the
@@ -566,4 +618,4 @@ export function describeDatabase(
   }
 }
 
-export const VERSION = '0.11.0'
+export const VERSION = '0.13.1'

package/src/database.ts

@@ -14,6 +14,7 @@ import {
   ensureSystemMediaTypes,
   ensureSystemMemberTypes,
   INITIAL_STATE,
+  markSetupPending,
   migrate,
   pendingMigrations,
   readState,
@@ -125,17 +126,18 @@ export async function installDatabase(
   // Core first, so a bundle step always runs against a core it declared itself compatible with.
   await migrateBundles(db, chains, { by: config.nodeId })
 
+  // In production a password is never made up: the pipeline supplies one, or
+  // the owner sets the site up in the browser (docs/operations.md).
+  const settingUp = !config.development && !config.adminPassword
   const password = config.adminPassword ?? crypto.randomUUID().replaceAll('-', '').slice(0, 20)
   const seeded = await seedIdentity(db, {
-    admin: {
-      name: 'Administrator',
-      login: config.adminLogin,
-      email: config.adminLogin,
-      password,
-    },
+    admin: settingUp
+      ? undefined
+      : { name: 'Administrator', login: config.adminLogin, email: config.adminLogin, password },
     hashPassword,
     passwordConfig: passwordConfigJson(),
   })
+  if (seeded && settingUp) await markSetupPending(db)
 
   await seedContent(db)
   // A database from an older version gains the built-ins it lacks.
@@ -144,5 +146,5 @@ export async function installDatabase(
   await ensureSystemMemberTypes(db)
   await ensureSystemContentTypes(db)
 
-  return seeded && !config.adminPassword ? password : undefined
+  return seeded && !settingUp && !config.adminPassword ? password : undefined
 }