@frontera-sdk/cli 1.52.39 → 1.52.40

package/src/local/local-component-health.ts

@@ -0,0 +1,119 @@
+import { connect } from 'node:net'
+
+import { containerState } from './local-docker'
+import { isAlive, type ComponentName, type ComponentState, type LocalState } from './local-state'
+
+/**
+ * Whether each part of a running local runtime is up now, not what the state
+ * file said when it started: a container can exit under the supervisor (the
+ * container engine restarted, the laptop slept), and the state file still says
+ * `running`. `local status` shows what this finds, and `local start` brings
+ * back what is down instead of saying "Already running".
+ */
+
+export interface ComponentProbe {
+  container: (name: string) => ReturnType<typeof containerState>
+  port: (port: number) => Promise<boolean>
+  alive: (pid: number) => boolean
+}
+
+/** A part of the runtime that is down, and why, in words. `cache` is the service's Redis, not a listed component. */
+export interface DownComponent {
+  name: ComponentName | 'cache'
+  why: string
+}
+
+/** Whether something accepts a TCP connection on 127.0.0.1 at `port`, within `timeoutMs`. */
+export function portAnswers(port: number, timeoutMs = 1500): Promise<boolean> {
+  return new Promise((resolvePromise) => {
+    const socket = connect({ host: '127.0.0.1', port })
+    const done = (ok: boolean) => {
+      socket.removeAllListeners()
+      socket.destroy()
+      resolvePromise(ok)
+    }
+    socket.setTimeout(timeoutMs, () => done(false))
+    socket.once('connect', () => done(true))
+    socket.once('error', () => done(false))
+  })
+}
+
+const defaultProbe: ComponentProbe = {
+  container: (name) => {
+    try {
+      return containerState(name)
+    } catch {
+      // No docker on PATH: nothing of the runtime's runs.
+      return 'missing'
+    }
+  },
+  port: (port) => portAnswers(port),
+  alive: isAlive,
+}
+
+const containerOf = (state: LocalState, c: ComponentState) => c.container ?? `frontera-${state.projectId}-${c.name}`
+
+async function whyDown(state: LocalState, c: ComponentState, probe: ComponentProbe): Promise<string | null> {
+  if (c.kind === 'container') {
+    const now = probe.container(containerOf(state, c))
+    if (now === 'missing') return 'its container is gone'
+    if (now !== 'running') return 'its container exited'
+  } else if (c.kind === 'process') {
+    if (!c.pid || !probe.alive(c.pid)) return 'its process exited'
+  } else if (!state.supervisorPid || !probe.alive(state.supervisorPid)) {
+    return 'the supervisor exited'
+  }
+  if (c.port && !(await probe.port(c.port))) return `nothing answers on its port ${c.port}`
+  return null
+}
+
+/**
+ * The runtime's components as they are now, and the ones that are down. Only
+ * a component the state file says is running is checked (one that is off,
+ * stopped or already failed says so itself), and only while the supervisor is
+ * up: a stopped runtime is stopped, nothing more to find. The service's cache
+ * is checked with Postgres, which it starts beside.
+ */
+export async function liveComponents(state: LocalState, probe: ComponentProbe = defaultProbe): Promise<{ components: ComponentState[]; down: DownComponent[] }> {
+  if (state.phase !== 'ready' || !state.supervisorPid || !probe.alive(state.supervisorPid)) return { components: state.components, down: [] }
+  const down: DownComponent[] = []
+  const components = await Promise.all(
+    state.components.map(async (c) => {
+      if (c.status !== 'running') return c
+      const why = await whyDown(state, c, probe)
+      if (!why) return c
+      down.push({ name: c.name, why })
+      return { ...c, status: 'failed' as const, detail: `${why}; ${BRING_BACK}` }
+    }),
+  )
+  const postgres = state.components.find((c) => c.name === 'postgres')
+  if (postgres?.status === 'running' && postgres.kind === 'container') {
+    const cache = probe.container(`frontera-${state.projectId}-cache`)
+    if (cache !== 'running') down.push({ name: 'cache', why: cache === 'missing' ? 'its container is gone' : 'its container exited' })
+  }
+  down.sort((a, b) => ORDER.indexOf(a.name) - ORDER.indexOf(b.name))
+  return { components, down }
+}
+
+/**
+ * What `local start` brings back on a runtime whose supervisor is up and
+ * ready: each component that is down now, and each one the supervisor saw
+ * fail (a native process that crashed). Null when nothing is down, or when it
+ * is not a ready runtime (one still starting is left to finish).
+ */
+export async function downToRestart(state: LocalState, probe: ComponentProbe = defaultProbe): Promise<DownComponent[] | null> {
+  if (state.phase !== 'ready' || !state.supervisorPid || !probe.alive(state.supervisorPid)) return null
+  const { down } = await liveComponents(state, probe)
+  for (const c of state.components) if (c.status === 'failed' && !down.some((d) => d.name === c.name)) down.push({ name: c.name, why: c.detail ?? 'it failed' })
+  return down.length ? down : null
+}
+
+const ORDER: Array<DownComponent['name']> = ['postgres', 'cache', 'storage', 'service', 'jobs', 'runner', 'studio']
+
+/** What brings a down component back, said on its line. */
+export const BRING_BACK = '`frontera local start` brings it back (the data is kept)'
+
+/** The header's phase when something is down: `down: postgres (its container exited), cache (…)`. */
+export function downPhase(down: DownComponent[]): string {
+  return `not answering: ${down.map((d) => `${d.name} down (${d.why})`).join(', ')}`
+}

package/src/local/local-control.ts

@@ -4,12 +4,11 @@ import { join, resolve } from 'node:path'
 
 import { credentialStore } from '../credential-store'
 import { findContext, writeContext } from '../project-context'
-import { fingerprint, putProfile } from '../profiles'
-import { containersForProject, removeContainer, removeVolume, stopContainer } from './local-docker'
+import { fingerprint, getProfile, putProfile } from '../profiles'
+import { containersForProject, removeRuntimeResources, stopContainer } from './local-docker'
 import { stopProcess } from './local-process'
 import type { LocalProject } from './local-project'
 import { isAlive, logPath, readState, type LocalState } from './local-state'
-import { volumeName } from './local-supervisor'
 
 /**
  * What the `frontera local` commands share: finding the platform source,
@@ -89,9 +88,7 @@ export async function stopRuntime(project: LocalProject): Promise<void> {
 }
 
 export function destroyRuntimeData(project: LocalProject): void {
-  for (const name of containersForProject(project.id)) removeContainer(name)
-  removeVolume(volumeName(project))
-  removeVolume(`frontera-${project.id}-storage`)
+  removeRuntimeResources(project.id)
 }
 
 export const localProfileName = (project: LocalProject) => `local-${project.id}`.slice(0, 64)
@@ -137,7 +134,37 @@ export async function registerLocalProfile(project: LocalProject, state: LocalSt
   })
   await store.set(orgProfile, creds.orgKey)
   const existing = findContext(project.root)
-  if (existing && existing.profile !== profile) return { profile, bound: false }
+  if (existing && existing.profile !== profile && !copiedLocalBinding(project, existing)) return { profile, bound: false }
   writeContext(project.root, profile)
   return { profile, bound: true }
 }
+
+/**
+ * Whether a binding is one a copy of the project carried here: it is in this
+ * directory, this machine never made it, and it names another directory's
+ * local runtime (`local-<other id>`). Rebinding such a one to this
+ * directory's own runtime is safe (a local key reaches only a runtime on this
+ * machine) and is what the copy meant. A binding to anything else (a
+ * platform profile) is never replaced: that is the person's to choose.
+ */
+export function copiedLocalBinding(project: LocalProject, found: { profile: string; root: string; trusted: boolean }): boolean {
+  return !found.trusted && resolve(found.root) === resolve(project.root) && found.profile.startsWith('local-') && found.profile !== localProfileName(project)
+}
+
+/**
+ * Bind a copied project to its own local runtime (`copiedLocalBinding`), when
+ * that runtime's profile is registered here: the line that says so, or null
+ * when nothing changed.
+ */
+export function rebindCopiedProject(project: LocalProject): string | null {
+  let found: ReturnType<typeof findContext>
+  try {
+    found = findContext(project.root)
+  } catch {
+    return null
+  }
+  const own = localProfileName(project)
+  if (!found || !copiedLocalBinding(project, found) || !getProfile(own)) return null
+  writeContext(project.root, own)
+  return `  bound this directory to its own local runtime (${own}): .frontera/context.json named ${found.profile}, another directory's runtime, which it was copied from`
+}

package/src/local/local-db-snapshot.ts

@@ -0,0 +1,348 @@
+import { createHash } from 'node:crypto'
+import { readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeFileAtomic } from '../fs-atomic'
+import { loadHashes } from './local-applied'
+import { appDeployments, appsLostByRestore, appsLostWords, markAppsLostByRestore, type AppLostByRestore } from './local-app-restore'
+import { execInContainer, queryInContainer } from './local-docker'
+import { POSTGRES_DB, POSTGRES_USER } from './local-env'
+import type { LocalProject } from './local-project'
+import { carrySecrets, readSecrets, type QueryFn, type SecretsCarried } from './local-secret-carry'
+import { isAlive } from './local-state'
+import { containerName } from './local-supervisor'
+
+/**
+ * The runtime's database as the project's files applied it: a Postgres
+ * template copy (`frontera_baseline`) taken after an apply, so what the tests
+ * write (a workflow test always writes for real, as does an Agent case with
+ * `realActions` or a `decision`) is rolled back afterwards instead of growing
+ * the data on every `local check`.
+ *
+ * The baseline is keyed by the applied build: a digest of what `local dev`
+ * recorded as applied (`applied-hashes.json`). It is taken again only when
+ * that changed. A copy of the hash and build records is kept with it, so a
+ * restore puts the CLI's record of what is applied back with the database:
+ * anything applied after the baseline counts as not applied, and the next
+ * `local dev` applies it again.
+ *
+ * Only the platform database is copied. The managed datasets' catalog
+ * database, object storage and local traces are left as they are.
+ *
+ * Workspace secrets are configuration, not test data: a restore keeps them as
+ * they are now (`local-secret-carry.ts`: the rows and the data keys they are
+ * encrypted under, copied as stored), unless it is asked for the baseline's
+ * (`secrets: 'baseline'`, `frontera local snapshot restore --exact`).
+ *
+ * The service, job engine and runner keep running: connections to the
+ * database are refused for the second or two it takes (`ALLOW_CONNECTIONS
+ * false`), the open ones ended (`pg_terminate_backend`), and the pools
+ * reconnect. The service's cache (Redis) is emptied after a restore. A save
+ * or restore then waits (bounded) until the service's database-backed health
+ * route answers on every pooled connection it asks (`serviceAnswers`, given
+ * `waitForDatabaseReady`), so the first request after it does not land on a
+ * connection that was ended.
+ */
+
+export const BASELINE_DB = `${POSTGRES_DB}_baseline`
+/** The database psql connects to while it copies, drops and creates the platform's. */
+const MAINTENANCE_DB = 'postgres'
+
+export interface BaselineRecord {
+  version: 1
+  organizationId: string
+  database: string
+  baseline: string
+  /** The applied build the baseline is of (`buildHash`). */
+  buildHash: string
+  savedAt: string
+  saveMs: number
+  /** `applied-hashes.json` and `build.json` as they were when the baseline was taken; null when absent. */
+  applied: string | null
+  build: string | null
+  /**
+   * Each Custom App folder's deployment when the baseline was taken (its
+   * `.frontera/state.json`): a deployment in the database copy. A restore puts
+   * these back in the folders and marks what it took away (`local-app-restore.ts`).
+   * Absent on a baseline taken before it was kept.
+   */
+  apps?: Record<string, string | null>
+  restoredAt?: string
+  restoreMs?: number
+}
+
+export interface SnapshotDeps {
+  /** `docker exec <container> <cmd…>`: true when it exited 0. */
+  exec?: (container: string, cmd: string[]) => boolean
+  /** Whether the service reaches its database again after a save or restore (`waitForDatabaseReady`). */
+  serviceAnswers?: () => Promise<boolean>
+  now?: () => number
+  /** How long the pools get to see their ended connections closed (500 ms). */
+  settleMs?: number
+  /**
+   * `docker exec -i <container> <cmd…>` with stdin, and what it printed: reads
+   * and writes the secrets a restore keeps. Without it, a stand-in `exec`
+   * carries no secrets (the real one carries them through `docker`).
+   */
+  query?: QueryFn
+}
+
+/** What a restore does with the workspace secrets: keeps the ones set now (the default), or puts back the baseline's. */
+export type RestoreSecrets = 'keep' | 'baseline'
+
+export interface SnapshotOutcome {
+  ok: boolean
+  /** What happened, in a line. */
+  note: string
+  ms: number
+  /** save: false when the stored baseline is already of this build. */
+  took?: boolean
+  /** restore: items applied after the baseline, now counted as not applied (Custom Apps deployed after it included). */
+  reapply?: number
+  /** restore: the Custom Apps deployed after the baseline, which the restored database does not have. */
+  appsLost?: AppLostByRestore[]
+  /** restore: the workspace secrets kept as they were before it, or `baseline` when the baseline's were put back. */
+  secrets?: (SecretsCarried & { mode: 'keep' }) | { mode: 'baseline' }
+}
+
+/** The secrets part of a restore's line: what was kept, what has to be set again, or that the baseline's are back. */
+export function secretsWords(secrets: SnapshotOutcome['secrets']): string {
+  if (!secrets) return ''
+  if (secrets.mode === 'baseline') return 'the workspace secrets are as the baseline holds them (--exact)'
+  if (!secrets.ok) return `the workspace secrets couldn’t be kept (${secrets.problem ?? 'unknown'}), so they are as the baseline holds them: set any changed since again with \`frontera secret set\``
+  const kept = secrets.kept ? `kept the ${secrets.kept === 1 ? 'workspace secret as it was' : `${secrets.kept} workspace secrets as they were`}` : 'the workspace secrets are as they were (none set)'
+  return secrets.notKept.length ? `${kept}; set again: ${secrets.notKept.join(', ')} (its value would not decrypt in the restored database)` : kept
+}
+
+const recordPath = (project: LocalProject) => join(project.stateDir, 'db-baseline.json')
+const lockPath = (project: LocalProject) => join(project.stateDir, 'db-snapshot.lock')
+const hashesFile = (project: LocalProject) => join(project.stateDir, 'applied-hashes.json')
+const buildFile = (project: LocalProject) => join(project.stateDir, 'build.json')
+
+function readText(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What is applied to this runtime, as one digest: the hash record, in a stable
+ * order, and each Custom App's deployment. An App deployed since the baseline
+ * changes it, so `local check` takes the baseline again rather than rolling the
+ * App back out of the runtime after its tests.
+ */
+export function buildHash(project: LocalProject, organizationId: string): string {
+  const entries = [...loadHashes(project, organizationId)].sort(([a], [b]) => a.localeCompare(b))
+  const apps = Object.entries(appDeployments(project.root)).filter(([, d]) => d).sort(([a], [b]) => a.localeCompare(b))
+  const hash = createHash('sha256').update(organizationId).update('\0').update(JSON.stringify(entries))
+  // Only when there is one, so a project without Apps keeps the digest its baseline was taken under.
+  if (apps.length) hash.update('\0apps\0').update(JSON.stringify(apps))
+  return hash.digest('hex')
+}
+
+/** The stored baseline's record, for this organization (after a reset the runtime is another one). */
+export function readBaseline(project: LocalProject, organizationId: string): BaselineRecord | null {
+  try {
+    const saved = JSON.parse(readFileSync(recordPath(project), 'utf8')) as Partial<BaselineRecord>
+    return saved.version === 1 && saved.organizationId === organizationId && typeof saved.buildHash === 'string' ? (saved as BaselineRecord) : null
+  } catch {
+    return null
+  }
+}
+
+function writeBaseline(project: LocalProject, record: BaselineRecord): void {
+  writeFileAtomic(recordPath(project), `${JSON.stringify(record, null, 2)}\n`, 0o644)
+}
+
+/**
+ * Whether a save or restore holds the database now: an apply that fails in
+ * that window failed because the database refused connections, not for its
+ * files (`local dev` retries it).
+ */
+export function snapshotInProgress(project: LocalProject, now = Date.now()): boolean {
+  const text = readText(lockPath(project))
+  if (!text) return false
+  const [pid, at] = text.trim().split(' ').map(Number)
+  return isAlive(pid) && now - (at ?? 0) < 5 * 60_000
+}
+
+function sqlName(name: string): string {
+  if (!/^[a-z_][a-z0-9_]*$/.test(name)) throw new Error(`not a plain database name: ${name}`)
+  return name
+}
+
+/** One statement on the maintenance database, stopping at the first error. */
+function psqlFor(project: LocalProject, exec: NonNullable<SnapshotDeps['exec']>) {
+  const container = containerName(project, 'postgres')
+  return (sql: string) => exec(container, ['psql', '-U', POSTGRES_USER, '-d', MAINTENANCE_DB, '-v', 'ON_ERROR_STOP=1', '-q', '-c', sql])
+}
+
+const exists = (db: string) => `DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_database WHERE datname = '${sqlName(db)}') THEN RAISE EXCEPTION 'no database ${sqlName(db)}'; END IF; END $$`
+const refuse = (db: string, allow: boolean) => `ALTER DATABASE ${sqlName(db)} ALLOW_CONNECTIONS ${allow}`
+const terminate = (db: string) => `SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = '${sqlName(db)}' AND pid <> pg_backend_pid()`
+/** FILE_COPY: the copy is a file copy, not a WAL-logged one; the runtime runs with fsync off. */
+const copy = (to: string, from: string) => `CREATE DATABASE ${sqlName(to)} TEMPLATE ${sqlName(from)} STRATEGY FILE_COPY`
+
+/**
+ * The database copied while nobody holds it: connections refused, the open
+ * ones ended, the copy made (retried: an ended backend takes a moment to go).
+ */
+function copyWhileHeld(psql: (sql: string) => boolean, to: string, from: string, attempts = 3): boolean {
+  for (let i = 0; i < attempts; i++) {
+    psql(terminate(from))
+    if (psql(copy(to, from))) return true
+  }
+  return false
+}
+
+/**
+ * A moment for the pools to see their ended connections closed: a query sent
+ * on one before its close arrives fails (`CONNECTION_CLOSED`), so the first
+ * test right after a save would.
+ */
+function settle(deps: SnapshotDeps): Promise<void> {
+  const ms = deps.settleMs ?? 500
+  return ms > 0 ? Bun.sleep(ms) : Promise.resolve()
+}
+
+function withLock<T>(project: LocalProject, run: () => Promise<T>): Promise<T> {
+  try {
+    writeFileSync(lockPath(project), `${process.pid} ${Date.now()}\n`)
+  } catch {
+    // The lock only tells `local dev` why an apply failed; the snapshot does not need it.
+  }
+  return run().finally(() => rmSync(lockPath(project), { force: true }))
+}
+
+/**
+ * Take the baseline of the database as it is now, unless the stored one is of
+ * this build already (`force` takes it regardless).
+ */
+export async function saveBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, force = false): Promise<SnapshotOutcome> {
+  const exec = deps.exec ?? execInContainer
+  const now = deps.now ?? Date.now
+  const psql = psqlFor(project, exec)
+  const hash = buildHash(project, organizationId)
+  const stored = readBaseline(project, organizationId)
+  const started = now()
+  if (!force && stored?.buildHash === hash && psql(exists(BASELINE_DB))) {
+    return { ok: true, took: false, ms: 0, note: `the stored baseline is of this build (taken ${stored.savedAt})` }
+  }
+  return withLock(project, async () => {
+    // The copy before last is dropped first: a template is only ever this one build.
+    if (!psql(`DROP DATABASE IF EXISTS ${BASELINE_DB}`)) {
+      return { ok: false, took: false, ms: now() - started, note: `couldn’t drop the previous baseline (${BASELINE_DB}); see \`frontera local logs postgres\`` }
+    }
+    psql(refuse(POSTGRES_DB, false))
+    let copied = false
+    try {
+      copied = copyWhileHeld(psql, BASELINE_DB, POSTGRES_DB)
+    } finally {
+      psql(refuse(POSTGRES_DB, true))
+    }
+    const ms = now() - started
+    if (!copied) return { ok: false, took: false, ms, note: `couldn’t copy the database to ${BASELINE_DB}: something kept a connection open; see \`frontera local logs postgres\`` }
+    // Nothing connects to the baseline: it is only ever a template.
+    psql(refuse(BASELINE_DB, false))
+    await settle(deps)
+    const answering = deps.serviceAnswers ? await deps.serviceAnswers() : true
+    writeBaseline(project, {
+      version: 1,
+      organizationId,
+      database: POSTGRES_DB,
+      baseline: BASELINE_DB,
+      buildHash: hash,
+      savedAt: new Date(now()).toISOString(),
+      saveMs: ms,
+      applied: readText(hashesFile(project)),
+      build: readText(buildFile(project)),
+      apps: appDeployments(project.root),
+    })
+    const late = answering ? '' : '; the service isn’t answering since (see `frontera local logs service`)'
+    return { ok: true, took: true, ms, note: `took a baseline of the applied database (${ms} ms)${late}` }
+  })
+}
+
+/** How many targets the hash record says are applied differently from the baseline's copy. */
+function changedSince(baseline: string | null, current: string | null): number {
+  const read = (text: string | null): Record<string, string> => {
+    try {
+      return (JSON.parse(text ?? '{}') as { hashes?: Record<string, string> }).hashes ?? {}
+    } catch {
+      return {}
+    }
+  }
+  const was = read(baseline)
+  const now = read(current)
+  return new Set([...Object.keys(was), ...Object.keys(now)].filter((k) => was[k] !== now[k])).size
+}
+
+/**
+ * Put the database back as the baseline holds it: connections refused and
+ * ended, the database dropped and made again from the baseline, the cache
+ * emptied. The CLI's record of what is applied is put back with it.
+ */
+export async function restoreBaseline(project: LocalProject, organizationId: string, deps: SnapshotDeps = {}, opts: { secrets?: RestoreSecrets } = {}): Promise<SnapshotOutcome> {
+  const exec = deps.exec ?? execInContainer
+  // A stand-in `exec` without a stand-in `query` carries nothing: tests never reach docker.
+  const query = deps.query ?? (deps.exec ? undefined : queryInContainer)
+  const keepSecrets = (opts.secrets ?? 'keep') === 'keep'
+  const now = deps.now ?? Date.now
+  const psql = psqlFor(project, exec)
+  const stored = readBaseline(project, organizationId)
+  if (!stored) return { ok: false, ms: 0, note: 'there is no baseline for this runtime yet: `frontera local snapshot save` takes one (`local check` takes one after it applies)' }
+  if (!psql(exists(BASELINE_DB))) return { ok: false, ms: 0, note: `the baseline database ${BASELINE_DB} is gone (a reset removes it): \`frontera local snapshot save\` takes a new one` }
+  const started = now()
+  return withLock(project, async () => {
+    // The secrets as they are now, read before the database goes: configuration, kept across the restore.
+    const pg = containerName(project, 'postgres')
+    const held = keepSecrets && query ? readSecrets(query, pg) : null
+    psql(refuse(POSTGRES_DB, false))
+    psql(terminate(POSTGRES_DB))
+    if (!psql(`DROP DATABASE ${POSTGRES_DB} WITH (FORCE)`)) {
+      psql(refuse(POSTGRES_DB, true))
+      return { ok: false, ms: now() - started, note: `couldn’t drop ${POSTGRES_DB} to restore it; the database is as the tests left it (see \`frontera local logs postgres\`)` }
+    }
+    // A new database takes connections: nothing is left refused, whichever way this ends.
+    if (!copyWhileHeld(psql, POSTGRES_DB, BASELINE_DB)) {
+      return { ok: false, ms: now() - started, note: `the database was dropped and couldn’t be made again from ${BASELINE_DB}: run \`frontera local snapshot restore\` to try again, or \`frontera local reset\`` }
+    }
+    // Before the cache is emptied and the service reads them: the secrets as they were.
+    const secrets: SnapshotOutcome['secrets'] = !keepSecrets
+      ? { mode: 'baseline' }
+      : held && query
+        ? { mode: 'keep', ...('problem' in held ? { ok: false, kept: 0, notKept: [], problem: held.problem } : carrySecrets(query, pg, held)) }
+        : undefined
+    // The service's cache holds rows of the database that was dropped.
+    exec(`frontera-${project.id}-cache`, ['redis-cli', 'FLUSHALL'])
+    await settle(deps)
+    // What is applied is what the baseline holds: anything applied after it is applied again.
+    const reapply = changedSince(stored.applied, readText(hashesFile(project)))
+    if (reapply) {
+      if (stored.applied !== null) writeFileAtomic(hashesFile(project), stored.applied, 0o600)
+      else rmSync(hashesFile(project), { force: true })
+      if (stored.build !== null) writeFileAtomic(buildFile(project), stored.build, 0o644)
+    }
+    // A Custom App deployed after the baseline: the restored database has no such deployment (or no such App).
+    // Its folder is put back as the baseline holds it, and marked, so status says so and `local dev` deploys it again.
+    const restoredAt = new Date(now()).toISOString()
+    const appsLost = appsLostByRestore(project.root, { atBaseline: stored.apps ?? null, savedAt: stored.savedAt })
+    markAppsLostByRestore(project.root, appsLost, restoredAt)
+    const answering = deps.serviceAnswers ? await deps.serviceAnswers() : true
+    const ms = now() - started
+    // Written last: a watching `local dev` reads it to take the record above.
+    writeBaseline(project, { ...stored, restoredAt, restoreMs: ms })
+    const kept = secretsWords(secrets)
+    const lostApps = appsLostWords(appsLost)
+    const tail = `${reapply ? `; ${reapply} item${reapply === 1 ? '' : 's'} applied after the baseline will apply again on the next \`frontera local dev\`` : ''}${lostApps ? `; ${lostApps}` : ''}${kept ? `; ${kept}` : ''}`
+    const withSecrets = secrets ? { secrets } : {}
+    const counted = { reapply: reapply + appsLost.length, ...(appsLost.length ? { appsLost } : {}) }
+    if (!answering) return { ok: false, ms, ...counted, ...withSecrets, note: `restored the database (${ms} ms), but the service isn’t answering since: see \`frontera local logs service\`${tail}` }
+    return { ok: true, ms, ...counted, ...withSecrets, note: `restored the database as applied (${ms} ms)${tail}` }
+  })
+}
+
+/** The record file's path relative to the project, which `local dev` watches for a restore. */
+export const BASELINE_RECORD = join('.frontera', 'local', 'db-baseline.json')