@curia-sh/cli 0.4.1

package/src/archive.mjs

@@ -0,0 +1,154 @@
+import { gunzipSync } from 'node:zlib'
+import { chmodSync, mkdirSync, symlinkSync, writeFileSync } from 'node:fs'
+import { dirname, join, normalize, resolve, sep } from 'node:path'
+
+// A reader and an extractor for the gzipped tar archives a release is made
+// of: the npm tarball of `@curia-sh/cli`, the Compose bundle archive, and the
+// Node.js runtime distribution. The questions asked of an archive are "which
+// files are in it", "what do they hold", and, for `curia update` (#883),
+// "put it on disk as the runtime and the package". A reader for that is
+// short, and it keeps the package free of dependencies and the tests free of
+// a system `tar`.
+//
+// It reads ustar and the pax and GNU variants that `npm pack`, GNU tar, and
+// the Node.js release build produce: regular files by their full path, with
+// the ustar prefix field and a pax `path` header honored, directories,
+// symbolic links, and file modes. It refuses bytes it cannot read as an
+// archive rather than returning a partial result, and an extraction refuses
+// an entry or a link target that would land outside the destination.
+
+export class ArchiveError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'ArchiveError'
+  }
+}
+
+const BLOCK = 512
+
+// Returns a Map from each regular file's path to its bytes.
+export function readArchive(bytes) {
+  const files = new Map()
+  for (const entry of entries(bytes)) {
+    if (entry.type === '0') files.set(entry.name, Buffer.from(entry.data))
+  }
+  return files
+}
+
+// Lands the archive under `dir`, which must exist, with the first `strip`
+// path segments of every entry removed, so `node-v24.19.0-linux-x64/bin/node`
+// becomes `<dir>/bin/node`. Regular files keep their mode bits, directories
+// are created as needed, symbolic links are recreated with their targets.
+// An entry that is not a file, a directory, or a symbolic link is skipped.
+export function extractArchive(bytes, dir, { strip = 0 } = {}) {
+  const base = resolve(dir)
+  const inside = (name) => {
+    const parts = name.split('/').filter((p) => p !== '' && p !== '.')
+    if (parts.length <= strip) return null
+    const target = resolve(base, ...parts.slice(strip))
+    if (target !== base && !target.startsWith(base + sep)) throw new ArchiveError(`the archive entry ${name} would land outside ${dir}`)
+    return target
+  }
+  for (const entry of entries(bytes)) {
+    const target = inside(entry.name)
+    if (target === null) continue
+    if (entry.type === '5') {
+      mkdirSync(target, { recursive: true })
+    } else if (entry.type === '0') {
+      mkdirSync(dirname(target), { recursive: true })
+      writeFileSync(target, entry.data, { mode: entry.mode })
+      chmodSync(target, entry.mode)
+    } else if (entry.type === '2') {
+      const pointed = normalize(join(dirname(target), entry.linkName))
+      if (pointed !== base && !pointed.startsWith(base + sep)) throw new ArchiveError(`the archive link ${entry.name} points outside ${dir}`)
+      mkdirSync(dirname(target), { recursive: true })
+      symlinkSync(entry.linkName, target)
+    }
+  }
+}
+
+// Walks the archive one entry at a time: `{ name, type, mode, data, linkName }`
+// for each entry that is not a pax or GNU header, with those headers already
+// applied to the entry that follows them.
+function* entries(bytes) {
+  let tar
+  try {
+    tar = gunzipSync(bytes)
+  } catch (e) {
+    throw new ArchiveError(`not a gzip stream: ${e.message}`)
+  }
+  if (tar.length < BLOCK * 2 || tar.length % BLOCK !== 0) throw new ArchiveError('not a tar archive: the length is not whole blocks')
+
+  let at = 0
+  let paxPath = null
+  let paxLink = null
+  let longName = null
+  let longLink = null
+  while (at + BLOCK <= tar.length) {
+    const header = tar.subarray(at, at + BLOCK)
+    if (header.every((b) => b === 0)) break
+
+    const magic = header.toString('latin1', 257, 263)
+    if (!/^ustar/.test(magic)) throw new ArchiveError(`not a tar archive: no ustar header at block ${at / BLOCK}`)
+    if (!checksumHolds(header)) throw new ArchiveError(`not a tar archive: the header checksum at block ${at / BLOCK} does not hold`)
+
+    const size = parseInt(field(header, 124, 12), 8)
+    if (!Number.isInteger(size) || size < 0) throw new ArchiveError(`not a tar archive: an unreadable size at block ${at / BLOCK}`)
+    const type = header[156] === 0 ? '0' : String.fromCharCode(header[156])
+    const dataStart = at + BLOCK
+    const dataEnd = dataStart + size
+    if (dataEnd > tar.length) throw new ArchiveError('the archive is truncated')
+    const data = tar.subarray(dataStart, dataEnd)
+
+    if (type === 'x') {
+      paxPath = paxField(data, 'path')
+      paxLink = paxField(data, 'linkpath')
+    } else if (type === 'L') {
+      longName = data.toString('utf8').replace(/\0+$/, '')
+    } else if (type === 'K') {
+      longLink = data.toString('utf8').replace(/\0+$/, '')
+    } else {
+      let name = paxPath ?? longName ?? field(header, 0, 100)
+      if (!paxPath && !longName) {
+        const prefix = field(header, 345, 155)
+        if (prefix) name = `${prefix}/${name}`
+      }
+      const mode = parseInt(field(header, 100, 8).trim(), 8) & 0o777
+      const linkName = paxLink ?? longLink ?? field(header, 157, 100)
+      yield { name, type, mode: Number.isInteger(mode) ? mode : 0o644, data, linkName }
+      paxPath = null
+      paxLink = null
+      longName = null
+      longLink = null
+    }
+    at = dataStart + Math.ceil(size / BLOCK) * BLOCK
+  }
+}
+
+function field(header, start, length) {
+  return header.toString('utf8', start, start + length).replace(/\0.*$/s, '')
+}
+
+function checksumHolds(header) {
+  const stored = parseInt(field(header, 148, 8).trim(), 8)
+  let sum = 0
+  for (let i = 0; i < BLOCK; i += 1) sum += i >= 148 && i < 156 ? 32 : header[i]
+  return sum === stored
+}
+
+// A pax extended header is `<length> <key>=<value>\n` records.
+function paxField(data, key) {
+  const text = data.toString('utf8')
+  let at = 0
+  while (at < text.length) {
+    const space = text.indexOf(' ', at)
+    if (space < 0) break
+    const length = parseInt(text.slice(at, space), 10)
+    if (!Number.isInteger(length) || length <= 0) break
+    const record = text.slice(space + 1, at + length - 1)
+    const eq = record.indexOf('=')
+    if (eq > 0 && record.slice(0, eq) === key) return record.slice(eq + 1)
+    at += length
+  }
+  return null
+}

package/src/atomic.mjs

@@ -0,0 +1,38 @@
+import { closeSync, fsyncSync, openSync, renameSync, unlinkSync, writeSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { randomBytes } from 'node:crypto'
+
+// The one way a lifecycle command writes a critical file: the installation
+// record, operator configuration, a secret. The content goes to a fresh
+// temporary file beside the target, is fsynced, and is renamed over the target
+// in one step. A reader sees the old file or the new one, never a partial one,
+// and a crash leaves at most a temporary file that the next write ignores.
+//
+// The mode is set on the temporary file at creation, so the target never
+// spends a moment with broader permissions than requested. Because rename
+// replaces the directory entry, a symbolic link sitting at the target is
+// replaced by the file rather than followed. The directory is fsynced after the
+// rename so the new entry is durable too.
+export function writeAtomically(path, content, { mode }) {
+  const dir = dirname(path)
+  const temp = join(dir, `.${basename(path)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`)
+  let fd
+  try {
+    fd = openSync(temp, 'wx', mode)
+    writeSync(fd, content)
+    fsyncSync(fd)
+    closeSync(fd)
+    fd = undefined
+    renameSync(temp, path)
+  } catch (e) {
+    if (fd !== undefined) closeSync(fd)
+    try { unlinkSync(temp) } catch {}
+    throw e
+  }
+  const dirFd = openSync(dir, 'r')
+  try {
+    fsyncSync(dirFd)
+  } finally {
+    closeSync(dirFd)
+  }
+}

package/src/bundle.mjs

@@ -0,0 +1,119 @@
+import { isAbsolute } from 'node:path'
+
+// The versioned Compose bundle (#869, implementing #849, #851, and #854).
+//
+// A release is one immutable set of container images plus one Compose file
+// that names them by digest. This module is the contract between the three
+// parties that touch that file: the release workflow that renders it from
+// `deploy/bundle/compose.yaml`, the tests that inspect what was rendered, and
+// the lifecycle interface that starts it under an installation root. It is
+// text in and text out, with no YAML reader, because the package has no
+// dependencies and the questions are answerable by line.
+//
+// Three facts every party shares:
+//
+//   - the Compose project is always `curia`, so `docker compose -p curia` and
+//     the labels Compose adds name one installation's containers, network, and
+//     volume on a host;
+//   - every container, the network, and the volume carry the installation ID
+//     under `sh.curia.installation`, which is what `curia purge` (#855) removes
+//     by and never a name prefix;
+//   - the bundle interpolates paths and numbers only, the five variables in
+//     `BUNDLE_VARIABLES`, which `curia install` (#873) writes into an env file
+//     under `run/` from facts it holds. Never a secret.
+//
+// The release manifest (#870) binds the bundle's checksum and the same
+// digests; the publication order and the stable index are #871's.
+
+export class BundleError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'BundleError'
+  }
+}
+
+export const COMPOSE_PROJECT = 'curia'
+export const INSTALLATION_LABEL = 'sh.curia.installation'
+export const IMAGE_REGISTRY = 'ghcr.io/alp82'
+
+// The four images a release builds, keyed by the service that runs them. The
+// attach surface (`ttyd`) runs the tmux image, so it has no image of its own.
+// The agent image is not here: the service builds it on the host from the
+// recipe the service image carries, content-addressed by its pins.
+export const RELEASE_IMAGES = Object.freeze({
+  daemon: 'curia-daemon',
+  tmux: 'curia-tmux',
+  dashboard: 'curia-dashboard',
+  overseer: 'curia-overseer',
+})
+
+// What a started bundle interpolates, in the order the env file lists them.
+export const BUNDLE_VARIABLES = Object.freeze(['CURIA_ROOT', 'CURIA_UID', 'CURIA_GID', 'DOCKER_GID', 'CURIA_INSTALLATION_ID'])
+
+const DIGEST = /^sha256:[0-9a-f]{64}$/
+const INSTALLATION_ID = /^[0-9a-f]{32}$/
+const IMAGE_VARIABLE = /\$\{CURIA_([A-Z]+)_IMAGE(?::\?[^}]*)?\}/g
+const ANY_VARIABLE = /\$\{([A-Za-z_][A-Za-z0-9_]*)/g
+const IMAGE_LINE = /^\s*image:\s*(\S+)\s*$/
+const OPERATOR_PATH = /\/home\/[A-Za-z0-9_-]+/
+
+export function imageReference(service, digest) {
+  const name = RELEASE_IMAGES[service]
+  if (!name) throw new BundleError(`no release image is built for ${service}`)
+  if (typeof digest !== 'string' || !DIGEST.test(digest)) {
+    throw new BundleError(`the ${service} image needs a sha256 digest, got ${JSON.stringify(digest)}`)
+  }
+  return `${IMAGE_REGISTRY}/${name}@${digest}`
+}
+
+// The template with each `${CURIA_<SERVICE>_IMAGE...}` replaced by that
+// service's digest reference. Every other variable is left as it is.
+export function renderBundle(template, digests) {
+  return template.replace(IMAGE_VARIABLE, (whole, upper) => {
+    const service = upper.toLowerCase()
+    if (!RELEASE_IMAGES[service]) throw new BundleError(`the template names ${whole.slice(2, whole.indexOf('_IMAGE') + 6)}, which no release builds`)
+    return imageReference(service, digests?.[service])
+  })
+}
+
+const referencePattern = new RegExp(`^${IMAGE_REGISTRY.replace(/[.]/g, '\\.')}/(${Object.values(RELEASE_IMAGES).join('|')})@sha256:[0-9a-f]{64}$`)
+
+// The problems a rendered bundle has, as one line each. Empty means it is fit
+// to publish: one fixed project name, every image an exact digest under the
+// registry, only the run-time variables, no build, no env file, no path of
+// anyone's home.
+export function inspectBundle(text) {
+  const problems = []
+  const lines = text.split('\n')
+  if (!lines.some((l) => l === `name: ${COMPOSE_PROJECT}`)) {
+    problems.push(`the project name must be \`name: ${COMPOSE_PROJECT}\` at the top level`)
+  }
+  lines.forEach((line, i) => {
+    const n = i + 1
+    const image = IMAGE_LINE.exec(line)
+    if (image && !referencePattern.test(image[1])) {
+      problems.push(`line ${n}: image ${image[1]} is not a digest reference under ${IMAGE_REGISTRY}`)
+    }
+    for (const m of line.matchAll(ANY_VARIABLE)) {
+      if (!BUNDLE_VARIABLES.includes(m[1])) problems.push(`line ${n}: variable ${m[1]} is not one the lifecycle interface writes`)
+    }
+    if (/^\s*build:/.test(line)) problems.push(`line ${n}: a build stanza; the bundle runs published images only`)
+    if (/^\s*env_file:/.test(line)) problems.push(`line ${n}: env_file; the bundle loads no env file`)
+    if (OPERATOR_PATH.test(line)) problems.push(`line ${n}: an operator path, ${OPERATOR_PATH.exec(line)[0]}`)
+  })
+  return problems
+}
+
+// The env file `curia install` writes under `run/` and passes with
+// `--env-file`. Paths and numbers, one per line, never a secret.
+export function bundleEnvironment({ root, uid, gid, dockerGid, installationId }) {
+  if (typeof root !== 'string' || !isAbsolute(root)) throw new BundleError(`CURIA_ROOT must be an absolute path, got ${JSON.stringify(root)}`)
+  for (const [name, value] of [['CURIA_UID', uid], ['CURIA_GID', gid], ['DOCKER_GID', dockerGid]]) {
+    if (!(Number.isInteger(value) && value >= 0)) throw new BundleError(`${name} must be a non-negative whole number, got ${JSON.stringify(value)}`)
+  }
+  if (typeof installationId !== 'string' || !INSTALLATION_ID.test(installationId)) {
+    throw new BundleError(`CURIA_INSTALLATION_ID must be the 32-hex installation ID, got ${JSON.stringify(installationId)}`)
+  }
+  const values = { CURIA_ROOT: root, CURIA_UID: uid, CURIA_GID: gid, DOCKER_GID: dockerGid, CURIA_INSTALLATION_ID: installationId }
+  return BUNDLE_VARIABLES.map((name) => `${name}=${values[name]}\n`).join('')
+}

package/src/cli.mjs

@@ -0,0 +1,73 @@
+import { EXIT, Refusal, UsageError } from './exit.mjs'
+import { commands as lifecycleCommands, packageVersion } from './commands.mjs'
+import { installationRoot } from './root.mjs'
+
+// The lifecycle interface's one entry point. `bin/curia.mjs` calls it with the
+// process's argv, env, and streams and exits with what it returns. Tests call
+// it with their own, hand in a `uid` and `gid` to stand in for another operator, and can
+// hand in a `commands` table to observe how the core treats a command that
+// throws.
+export async function runCli({ argv, env, stdout, stderr, uid = process.getuid(), gid = process.getgid(), commands = lifecycleCommands }) {
+  const [name, ...args] = argv
+
+  if (name === undefined) {
+    stderr.write(usage(commands))
+    return EXIT.usage
+  }
+  if (name === '--version' || name === '-V') {
+    stdout.write(`curia ${packageVersion}\n`)
+    return EXIT.ok
+  }
+  if (name === 'help' || name === '--help' || name === '-h') {
+    stdout.write(usage(commands))
+    return EXIT.ok
+  }
+
+  const command = commands[name]
+  if (!command) {
+    stderr.write(`curia: unknown command: ${name}\nRun 'curia help' for the command vocabulary.\n`)
+    return EXIT.usage
+  }
+
+  // A command that declares no options takes none: an option it does not know
+  // is a usage error before anything runs, never something a stub swallows. A
+  // command that declares `options` reads its own and throws a `UsageError`
+  // for one it does not know.
+  const options = args.filter((a) => a.startsWith('-'))
+  if (!command.options && options.length > 0) {
+    stderr.write(`curia ${name}: unknown option: ${options[0]}\nRun 'curia help' for the command vocabulary.\n`)
+    return EXIT.usage
+  }
+
+  try {
+    return await command.run({ env, args, stdout, stderr, uid, gid, root: installationRoot(env) })
+  } catch (e) {
+    if (e instanceof UsageError) {
+      stderr.write(`curia ${name}: ${e.message}\nRun 'curia help' for the command vocabulary.\n`)
+      return EXIT.usage
+    }
+    stderr.write(`curia ${name}: ${e.message}\n`)
+    return e instanceof Refusal ? EXIT.refused : EXIT.failed
+  }
+}
+
+export function usage(commands = lifecycleCommands) {
+  const width = Math.max(...Object.keys(commands).map((n) => n.length))
+  const lines = Object.entries(commands).map(([n, c]) => `  ${n.padEnd(width)}  ${c.summary}`)
+  return [
+    'usage: curia <command>',
+    '',
+    'Commands:',
+    ...lines,
+    `  ${'help'.padEnd(width)}  Print this text.`,
+    '',
+    'Exit codes:',
+    `  ${EXIT.ok}  ok       The command did what it said.`,
+    `  ${EXIT.failed}  failed   The operation started and failed. The message says what to do next.`,
+    `  ${EXIT.usage}  usage    The command line was wrong. Nothing ran.`,
+    `  ${EXIT.refused}  refused  Curia refused to start. Nothing changed. The message names the condition.`,
+    '',
+    'The installation root comes from CURIA_ROOT, which the installed launcher sets.',
+    '',
+  ].join('\n')
+}

package/src/commands.mjs

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs'
+
+import { EXIT } from './exit.mjs'
+import { installationRoot, readInstallationRecord } from './root.mjs'
+import { installCommand } from './install.mjs'
+import { runDoctor } from './doctor.mjs'
+import { updateCommand } from './update.mjs'
+import { rollbackCommand } from './rollback.mjs'
+import { uninstallCommand } from './uninstall.mjs'
+import { purgeCommandRun } from './purge.mjs'
+
+export const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+// One lifecycle command. `run(context)` gets `{ env, args, stdout, stderr, uid, root }`
+// and returns an exit code, throws a `Refusal` to exit `refused` without a
+// change, or throws any other error to exit `failed`. Commands print on their
+// own streams and never call `process.exit`, which keeps every one of them
+// callable from a test.
+//
+// Every lifecycle command enters its root through `openRoot` first, so the
+// boundary refusals (root execution, foreign ownership, broad permissions,
+// symbolic links, an unknown nonempty root) come before anything the command
+// itself does. `version` is read-only and skips the boundary on purpose: it
+// reports the root even when a lifecycle command would refuse it.
+
+async function version({ env, stdout }) {
+  stdout.write(`curia ${packageVersion}\n`)
+  const root = installationRoot(env)
+  const record = readInstallationRecord(root)
+  stdout.write(`active version: ${record ? record.activeVersion : 'none (no installation record)'}\n`)
+  stdout.write(`installation root: ${root}\n`)
+  return EXIT.ok
+}
+
+// Order matters: `curia help` lists the commands in lifecycle order.
+export const commands = {
+  install: { summary: 'Install Curia into the installation root and start it.', run: installCommand('install') },
+  reinstall: { summary: 'Reinstall this version over a preserved installation root, keeping its identity, configuration, secrets, state, and work.', run: installCommand('reinstall') },
+  update: { summary: 'Stage, verify, and switch to the latest stable release, or to an exact version (--prerelease for an exact prerelease).', run: updateCommand, options: true },
+  rollback: { summary: 'Switch back to the one retained previous release, after it validates the current configuration.', run: rollbackCommand },
+  doctor: { summary: 'Check the host, configuration, integrations, and services. Read-only.', run: runDoctor },
+  uninstall: { summary: 'Stop Curia and remove the launcher, versions/, cache/, run/, the installation\'s containers, networks, volumes, and Serve routes; keep config/, secrets/, state/, and work/ for a reinstall.', run: uninstallCommand },
+  purge: { summary: 'Remove the entire installation root, every Curia-labelled Docker resource, the unused release images, and the Serve routes, after one confirmation (type the root, or pass --confirm <root>).', run: purgeCommandRun, options: true },
+  version: { summary: 'Print the lifecycle interface version and the active installed version.', run: version },
+}

package/src/compose.mjs

@@ -0,0 +1,137 @@
+import { execFile } from 'node:child_process'
+import { join } from 'node:path'
+
+import { writeAtomically } from './atomic.mjs'
+import { bundleEnvironment } from './bundle.mjs'
+import { SERVICES } from './layout.mjs'
+import { versionPaths } from './root.mjs'
+
+// The one seam between the lifecycle interface and Docker Compose (#873,
+// implementing #851 and #854).
+//
+// An installed version's Compose bundle is started, watched, and later
+// switched or torn down through this module and nothing else. It knows three
+// things: where the project's files are for one version of one root, how to
+// run `docker compose` against them, and what "healthy" means for the five
+// services the bundle declares. Every Docker call goes through `dockerRunner`,
+// which a test replaces with a fake, so the install sequence is proven against
+// packaged fixtures without a Docker daemon.
+//
+// The project name is in the bundle itself (`name: curia`), so no command here
+// passes one. What a command passes is the env file under `run/` with the five
+// run-time values (paths and numbers, never a secret) and the bundle file of
+// the version.
+
+export class ComposeError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'ComposeError'
+  }
+}
+
+// How long a start may take before a service that is still starting counts
+// as failed: the daemon's start period is 60 s and every check allows three
+// 30 s retries, so four minutes covers a slow first pull of the agent image
+// recipe and a cold journal open.
+export const HEALTH_TIMEOUT_MS = 240_000
+export const HEALTH_POLL_MS = 2_000
+
+export function composeEnvPath(root) {
+  return join(root, 'run', 'compose.env')
+}
+
+// The project of `version` under `root`: the env file, the bundle file, and
+// the `docker` arguments for one Compose verb against them.
+export function composeProject({ root, version }) {
+  const envFile = composeEnvPath(root)
+  const file = versionPaths(root, version).bundle
+  return Object.freeze({
+    root,
+    version,
+    envFile,
+    file,
+    args: (...verb) => ['compose', '--env-file', envFile, '-f', file, ...verb],
+  })
+}
+
+// Writes `run/compose.env` owner-only. `run/` exists because `ensureLayout`
+// created it.
+export function writeComposeEnvironment(project, { uid, gid, dockerGid, installationId }) {
+  writeAtomically(project.envFile, bundleEnvironment({ root: project.root, uid, gid, dockerGid, installationId }), { mode: 0o600 })
+}
+
+// The real runner: one `docker` invocation, its output captured. Compose
+// prints progress on stderr, which is returned with the result so a failure
+// can quote it.
+export const dockerRunner = (args, { timeoutMs = 600_000 } = {}) => new Promise((resolve) => {
+  execFile('docker', args, { timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
+    if (!error) return resolve({ ok: true, stdout, stderr, code: 0 })
+    resolve({ ok: false, stdout, stderr: stderr || error.message, code: error.code, missing: error.code === 'ENOENT', timedOut: Boolean(error.killed) })
+  })
+})
+
+export async function compose(project, verb, { docker }) {
+  const args = project.args(...verb)
+  const result = await docker(args)
+  if (result.ok) return result
+  const detail = result.missing ? 'docker is not on the path' : (result.stderr || result.stdout || `exit ${result.code}`).trim().split('\n').slice(-5).join('\n')
+  throw new ComposeError(`docker ${args.join(' ')} failed:\n${detail}`)
+}
+
+// Pulls every image by its digest, then brings the project up detached.
+// `--remove-orphans` retires a container of a service the bundle no longer
+// declares, which is what a reinstall over an older bundle needs.
+export async function startProject(project, { docker = dockerRunner, stdout }) {
+  stdout?.write(`pulling the images of ${project.version} by digest\n`)
+  await compose(project, ['pull'], { docker })
+  stdout?.write(`starting the Compose project\n`)
+  await compose(project, ['up', '--detach', '--remove-orphans', '--quiet-pull'], { docker })
+}
+
+// `docker compose ps --format json` prints one object per line since Compose
+// 2.21 and one array before that. Both read into the same list.
+export function parseServiceStates(text) {
+  const trimmed = text.trim()
+  if (trimmed === '') return []
+  const rows = trimmed.startsWith('[') ? JSON.parse(trimmed) : trimmed.split('\n').map((line) => JSON.parse(line))
+  return rows.map((row) => ({
+    service: row.Service,
+    state: row.State ?? '',
+    health: row.Health ?? '',
+    exitCode: Number.isInteger(row.ExitCode) ? row.ExitCode : null,
+  }))
+}
+
+export async function serviceStates(project, { docker = dockerRunner }) {
+  const result = await compose(project, ['ps', '--all', '--format', 'json'], { docker })
+  return parseServiceStates(result.stdout)
+}
+
+// Waits until every service the bundle declares reports healthy. A service
+// that exited, or that Docker marks unhealthy, fails at once: waiting cannot
+// fix it. A service still starting when the deadline passes fails too. The
+// failure names the service and the log command that shows why.
+export async function waitForHealth(project, { docker = dockerRunner, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now, timeoutMs = HEALTH_TIMEOUT_MS, stdout } = {}) {
+  const started = now()
+  const logs = (service) => `Read its log with 'docker compose --env-file ${project.envFile} -f ${project.file} logs ${service}', fix the cause, and run the command again.`
+  for (;;) {
+    const states = await serviceStates(project, { docker })
+    const pending = []
+    for (const service of SERVICES) {
+      const s = states.find((x) => x.service === service)
+      if (!s) throw new ComposeError(`${service} is not in the project. ${logs(service)}`)
+      if (s.state === 'exited' || s.state === 'dead') throw new ComposeError(`${service} exited with code ${s.exitCode ?? '?'}. ${logs(service)}`)
+      if (s.health === 'unhealthy') throw new ComposeError(`${service} is unhealthy. ${logs(service)}`)
+      if (s.health !== 'healthy') pending.push(service)
+    }
+    if (pending.length === 0) {
+      stdout?.write(`every service is healthy: ${SERVICES.join(', ')}\n`)
+      return states
+    }
+    if (now() - started >= timeoutMs) {
+      throw new ComposeError(`${pending[0]} is still starting after ${Math.round(timeoutMs / 1000)} seconds. ${logs(pending[0])}`)
+    }
+    stdout?.write(`waiting for ${pending.join(', ')}\n`)
+    await sleep(HEALTH_POLL_MS)
+  }
+}