@frontera-sdk/cli 1.52.23 → 1.52.24

package/src/local/local-apply-error.ts

@@ -0,0 +1,35 @@
+/**
+ * A failed apply command's error, as `frontera local dev` prints it: the error
+ * line and the detail lines under it (validation issues, the hint), at most
+ * seven.
+ *
+ * A Blueprint apply that fails part-way first lists what it applied before
+ * failing, one line per step. That list is counted rather than shown, so a
+ * long one cannot push the reason it failed out of the seven lines.
+ */
+export function applyErrorText(output: string): string {
+  const lines = output.split('\n').filter((l) => l.trim())
+  const at = Math.max(0, lines.findIndex((l) => /^error/i.test(l.trim())))
+  const kept: string[] = []
+  let applied = 0
+  let inList = false
+  for (const raw of lines.slice(at)) {
+    const line = raw.trim()
+    const header = /^(.*?)\s*Applied before failing:\s*$/i.exec(line)
+    if (header) {
+      inList = true
+      if (header[1]) kept.push(header[1])
+      continue
+    }
+    if (inList && /^(create|update|delete|publish|grant)\s/i.test(line)) {
+      applied += 1
+      continue
+    }
+    inList = false
+    kept.push(line)
+  }
+  if (applied) kept.push(`(${applied} ${applied === 1 ? 'step' : 'steps'} applied before it failed)`)
+  const shown = kept.slice(0, 7)
+  if (!shown.length) return 'failed with no output'
+  return [shown[0], ...shown.slice(1).map((l) => `      ${l}`)].join('\n')
+}

package/src/local/local-control.ts

@@ -0,0 +1,143 @@
+import { spawn } from 'node:child_process'
+import { existsSync, openSync } from 'node:fs'
+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 { 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,
+ * spawning and stopping the supervisor, and the CLI profile that points every
+ * other command at the local runtime.
+ */
+
+/** The platform checkout this CLI runs from, when it runs from one. */
+export function detectPlatformSource(): string | null {
+  // packages/frontera-cli/src/local → repository root
+  const root = resolve(import.meta.dir, '..', '..', '..', '..')
+  return existsSync(join(root, 'packages', 'service', 'src', 'index.ts')) ? root : null
+}
+
+export function isPlatformSource(dir: string): boolean {
+  return existsSync(join(dir, 'packages', 'service', 'src', 'index.ts'))
+}
+
+/** Spawn the supervisor detached, so it outlives the terminal that started it. */
+export function spawnSupervisor(project: LocalProject, sessionToken: string): number {
+  const compiled = Bun.main.startsWith('/$bunfs') || Bun.main.startsWith('B:\\~BUN')
+  const args = compiled ? ['local', 'daemon'] : [Bun.main, 'local', 'daemon']
+  const out = openSync(logPath(project, 'studio'), 'a')
+  const child = spawn(process.execPath, args, {
+    cwd: project.root,
+    detached: true,
+    stdio: ['ignore', out, out],
+    env: { ...process.env, FRONTERA_LOCAL_SESSION: sessionToken },
+  })
+  child.unref()
+  return child.pid!
+}
+
+export async function waitForPhase(
+  project: LocalProject,
+  supervisorPid: number,
+  onPhase: (state: LocalState) => void,
+  timeoutMs = 10 * 60_000,
+): Promise<LocalState> {
+  const since = Date.now() - 1000
+  const deadline = Date.now() + timeoutMs
+  let last = ''
+  while (Date.now() < deadline) {
+    const state = readState(project)
+    // Only the supervisor just spawned speaks for this start; an earlier run's
+    // state file still says `stopped` until the new one rewrites it.
+    if (state && state.supervisorPid !== supervisorPid && state.phase !== 'failed') {
+      if (!isAlive(supervisorPid)) {
+        // A supervisor that failed and shut down clears its pid but leaves its error.
+        const fresh = state.error && state.updatedAt && Date.parse(state.updatedAt) >= since
+        return { ...state, phase: 'failed', error: fresh ? state.error : 'the supervisor exited before writing its state; see `frontera local logs studio`' }
+      }
+      await Bun.sleep(300)
+      continue
+    }
+    if (state) {
+      const signature = `${state.phase}:${state.components.map((c) => `${c.name}=${c.status}`).join(',')}`
+      if (signature !== last) {
+        last = signature
+        onPhase(state)
+      }
+      if (state.phase === 'ready' || state.phase === 'failed' || state.phase === 'stopped') return state
+      if (state.supervisorPid && !isAlive(state.supervisorPid)) return { ...state, phase: 'failed', error: state.error ?? 'the supervisor exited; see `frontera local logs studio`' }
+    }
+    await Bun.sleep(400)
+  }
+  throw new Error('the local runtime did not finish starting within 10 minutes')
+}
+
+export async function stopRuntime(project: LocalProject): Promise<void> {
+  const state = readState(project)
+  if (state?.supervisorPid && isAlive(state.supervisorPid)) {
+    await stopProcess(state.supervisorPid, 30_000)
+  }
+  // Belt and braces: anything labelled for this project that is still up.
+  for (const name of containersForProject(project.id)) stopContainer(name)
+}
+
+export function destroyRuntimeData(project: LocalProject): void {
+  for (const name of containersForProject(project.id)) removeContainer(name)
+  removeVolume(volumeName(project))
+  removeVolume(`frontera-${project.id}-storage`)
+}
+
+export const localProfileName = (project: LocalProject) => `local-${project.id}`.slice(0, 64)
+
+/**
+ * Register the seeded organization key as a CLI profile, and bind this
+ * directory to it when the directory is not already bound to something else.
+ *
+ * Binding is what makes `frontera agent list` in the solution directory talk
+ * to the local runtime with no flags. An existing binding (a real deployment)
+ * is left alone: overwriting it silently would point the FDE's next `publish`
+ * at the wrong place. They pass `--profile` instead, which `status` prints.
+ */
+export async function registerLocalProfile(project: LocalProject, state: LocalState): Promise<{ profile: string; bound: boolean }> {
+  const profile = localProfileName(project)
+  const creds = state.credentials
+  if (!creds) return { profile, bound: false }
+  const now = new Date().toISOString()
+  const store = credentialStore(process.env, { allowPlaintext: true })
+  // The workspace key (`mcp` scope) reaches every workspace command; the
+  // organization key is a second profile for Blueprint authoring.
+  if (creds.workspaceKey) {
+    putProfile(profile, {
+      apiUrl: `http://127.0.0.1:${state.ports.service}`,
+      credentialKind: 'workspace',
+      workspaceId: creds.workspaceId,
+      orgId: creds.organizationId,
+      fingerprint: fingerprint(creds.workspaceKey),
+      createdAt: now,
+      lastVerifiedAt: now,
+    })
+    await store.set(profile, creds.workspaceKey)
+  }
+  const orgProfile = `${profile}-org`.slice(0, 64)
+  putProfile(orgProfile, {
+    apiUrl: `http://127.0.0.1:${state.ports.service}`,
+    credentialKind: 'organization',
+    workspaceId: null,
+    orgId: creds.organizationId,
+    fingerprint: fingerprint(creds.orgKey),
+    createdAt: now,
+    lastVerifiedAt: now,
+  })
+  await store.set(orgProfile, creds.orgKey)
+  const existing = findContext(project.root)
+  if (existing && existing.profile !== profile) return { profile, bound: false }
+  writeContext(project.root, profile)
+  return { profile, bound: true }
+}

package/src/local/local-dev-sync.ts

@@ -0,0 +1,256 @@
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs'
+import { basename, dirname, join, relative, resolve, sep } from 'node:path'
+
+/**
+ * What `frontera local dev` applies when a file in the solution changes.
+ *
+ * The solution layout from the delivery design, mapped onto the commands that
+ * exist today, one target per change:
+ *
+ *   datasets/<apiName>.json + .csv      → dataset create -f …       (dataset upload once it exists)
+ *   agents/<slug>/agent.json            → agent apply <slug> -f …   (agent create first when new)
+ *   agents/<slug>/operating.json        → the Agent's behavior settings, staged over the API (no CLI command)
+ *   workflows/<slug>.yaml|.yml|.json    → workflow push <slug> …    (`<slug>.workflow.yaml` too)
+ *   functions/<name>.ts                 → function deploy …
+ *   blueprint/**                        → blueprint apply --yes, then publish and grant (organization profile)
+ *
+ * Evaluation cases (`agents/<slug>/evals/`), fixtures and anything else are
+ * not applied: they are read by `local test` and Studio, not stored on the
+ * runtime.
+ */
+
+export type SyncTarget =
+  | { kind: 'dataset'; key: string; apiName: string; file: string }
+  | { kind: 'agent'; key: string; slug: string; file: string }
+  | { kind: 'operating'; key: string; slug: string; file: string }
+  | { kind: 'workflow'; key: string; slug: string; file: string }
+  | { kind: 'function'; key: string; file: string }
+  | { kind: 'blueprint'; key: string }
+
+const IGNORED_DIRS = new Set(['node_modules', '.frontera', '.git', 'dist', 'fixtures'])
+
+/** Hidden files and editor leftovers: `.#x.yaml` locks, `#x#` autosaves, `x~` backups, `.swp`. */
+export function isIgnoredName(name: string): boolean {
+  return name.startsWith('.') || name.startsWith('#') || name.endsWith('~') || name.endsWith('.swp')
+}
+
+export function targetFor(root: string, absolute: string): SyncTarget | null {
+  const rel = relative(root, absolute)
+  if (!rel || rel.startsWith('..')) return null
+  const parts = rel.split(sep)
+  if (parts.some((p) => IGNORED_DIRS.has(p) || isIgnoredName(p))) return null
+  const [top, second, third] = parts
+
+  // A dataset is its definition and the CSV beside it; either changing applies both.
+  if (top === 'datasets' && parts.length === 2 && second && /\.(json|csv)$/.test(second)) {
+    const apiName = second.replace(/\.(json|csv)$/, '')
+    return { kind: 'dataset', key: `dataset:${apiName}`, apiName, file: join('datasets', `${apiName}.json`) }
+  }
+  if (top === 'agents' && second && third === 'agent.json' && parts.length === 3) {
+    return { kind: 'agent', key: `agent:${second}`, slug: second, file: rel }
+  }
+  if (top === 'agents' && second && third === 'operating.json' && parts.length === 3) {
+    return { kind: 'operating', key: `operating:${second}`, slug: second, file: rel }
+  }
+  if (top === 'workflows' && parts.length === 2 && second && /\.(ya?ml|json)$/.test(second)) {
+    const slug = second.replace(/\.workflow\.(ya?ml|json)$/, '').replace(/\.(ya?ml|json)$/, '')
+    return { kind: 'workflow', key: `workflow:${slug}`, slug, file: rel }
+  }
+  if (top === 'functions' && parts.length === 2 && second && /\.ts$/.test(second) && !second.endsWith('.d.ts') && !second.endsWith('.test.ts')) {
+    return { kind: 'function', key: `function:${second}`, file: rel }
+  }
+  if (top === 'blueprint' && parts.length >= 2 && /\.(ya?ml|json)$/.test(basename(rel))) {
+    return { kind: 'blueprint', key: 'blueprint' }
+  }
+  return null
+}
+
+/** Every applicable target in the solution, for the initial sync. */
+export function allTargets(root: string): SyncTarget[] {
+  const out = new Map<string, SyncTarget>()
+  const walk = (dir: string, depth: number) => {
+    if (depth > 6 || !existsSync(dir)) return
+    let names: string[]
+    try {
+      names = readdirSync(dir)
+    } catch {
+      return
+    }
+    for (const name of names) {
+      if (IGNORED_DIRS.has(name) || isIgnoredName(name)) continue
+      const path = join(dir, name)
+      let stat
+      try {
+        stat = lstatSync(path)
+      } catch {
+        continue
+      }
+      if (stat.isDirectory()) walk(path, depth + 1)
+      else if (stat.isFile()) {
+        const t = targetFor(root, path)
+        if (t && !out.has(t.key)) out.set(t.key, t)
+      }
+    }
+  }
+  for (const top of ['datasets', 'blueprint', 'functions', 'workflows', 'agents']) walk(join(root, top), 1)
+  // Datasets first (object types read them), then the Blueprint (Agents and
+  // workflows read its objects), then Functions (workflows and Agents call
+  // them), then workflows, then Agents, then their behavior settings.
+  return [...out.values()].sort(byApplyOrder)
+}
+
+const ORDER = { dataset: 0, blueprint: 1, function: 2, workflow: 3, agent: 4, operating: 5 }
+
+/** Dependencies first: what a later kind reads or calls is applied before it. */
+export function byApplyOrder(a: SyncTarget, b: SyncTarget): number {
+  return ORDER[a.kind] - ORDER[b.kind]
+}
+
+/**
+ * A dataset definition's own name, kind and CSV (resolved from the solution
+ * root). The file is `datasets/<apiName>.json` by convention, but the document
+ * is what `dataset create` reads, so it decides.
+ */
+export function datasetDocument(root: string, target: SyncTarget): { apiName: string; kind: string; csv: string | null } | null {
+  if (target.kind !== 'dataset') return null
+  try {
+    const doc = JSON.parse(readFileSync(join(root, target.file), 'utf8')) as { apiName?: unknown; kind?: unknown; path?: unknown }
+    const apiName = typeof doc.apiName === 'string' && doc.apiName ? doc.apiName : target.apiName
+    const kind = typeof doc.kind === 'string' ? doc.kind : 'blank'
+    const csv = kind === 'file' && typeof doc.path === 'string' ? relative(root, resolve(join(root, dirname(target.file)), doc.path)) : null
+    return { apiName, kind, csv }
+  } catch {
+    return null
+  }
+}
+
+export interface SyncProfiles {
+  /** Workspace profile: Agents, workflows, Functions. */
+  workspace: string
+  /** Organization profile: datasets and Blueprint. */
+  organization: string
+}
+
+/**
+ * The CLI arguments that apply a target. Every command names its local
+ * profile explicitly, so a solution folder bound to a deployment is never
+ * written to by `local dev`.
+ */
+export function commandFor(target: SyncTarget, profiles: SyncProfiles): string[] {
+  switch (target.kind) {
+    case 'dataset':
+      return ['dataset', 'create', '-f', target.file, '--profile', profiles.organization]
+    case 'agent':
+      return ['agent', 'apply', target.slug, '-f', target.file, '--profile', profiles.workspace]
+    case 'workflow':
+      return ['workflow', 'push', target.slug, target.file, '--profile', profiles.workspace]
+    case 'function':
+      return ['function', 'deploy', target.file, '--profile', profiles.workspace]
+    case 'blueprint':
+      return ['blueprint', 'apply', '--yes', '--profile', profiles.organization]
+    case 'operating':
+      // Session-only route; `local dev` calls it itself (see local-operating.ts).
+      throw new Error('behavior settings are applied over the API, not with a CLI command')
+  }
+}
+
+/** When the first command fails with `when`, run `then` instead. */
+export interface Fallback {
+  when: RegExp
+  then: string[][]
+}
+
+/**
+ * The second attempt for a target the first command cannot handle alone: an
+ * Agent applied for the first time is created, then applied (`agent apply`
+ * stages onto an existing draft); a dataset that exists already gets its CSV
+ * as a new snapshot (`dataset create` refuses a name in use). A dataset with
+ * no CSV that exists already has nothing more to load: an empty `then`.
+ *
+ * Only rows reach an existing dataset. A changed definition (columns, keys)
+ * is a new revision of the dataset, which `local dev` does not make; after a
+ * `frontera local reset` the definition is created as written.
+ */
+export function fallbackFor(target: SyncTarget, profiles: SyncProfiles, root: string): Fallback | null {
+  if (target.kind === 'agent') {
+    return { when: /NOT_FOUND/, then: [['agent', 'create', target.slug, '--profile', profiles.workspace], commandFor(target, profiles)] }
+  }
+  if (target.kind === 'dataset') {
+    const doc = datasetDocument(root, target)
+    const upload = doc?.csv ? [['dataset', 'upload', doc.apiName, doc.csv, '--profile', profiles.organization]] : []
+    return { when: /already in use/i, then: upload }
+  }
+  return null
+}
+
+export interface FollowUp {
+  args: string[]
+  /** Output that means the step had nothing to do, not that it failed. */
+  alreadyDone?: RegExp
+}
+
+/**
+ * After a Blueprint apply, what makes it usable at once: Agents, workflows
+ * and queries read the published Blueprint, and only the object types granted
+ * to their workspace. Locally there is one person and one workspace, so the
+ * draft is published and every object type in the tree granted to it.
+ */
+export function followUpsFor(
+  target: SyncTarget,
+  profiles: SyncProfiles,
+  opts: { publish: boolean; workspaceId: string; objectTypes: string[] },
+): FollowUp[] {
+  if (target.kind !== 'blueprint' || !opts.publish) return []
+  const steps: FollowUp[] = [{
+    // The instruction is sent only when the service asks for one (a change that
+    // needs migrating); locally the data is rebuilt from the solution's files.
+    args: [
+      'blueprint', 'publish',
+      '--label', `local-${Date.now().toString(36)}`,
+      '--notes', 'Published by frontera local dev.',
+      '--instruction', "Local development: rebuilt from the project's files.",
+      '--profile', profiles.organization,
+    ],
+    alreadyDone: /no unpublished changes/i,
+  }]
+  if (opts.objectTypes.length) {
+    steps.push({ args: ['blueprint', 'grant', 'workspace', opts.workspaceId, ...opts.objectTypes, '--profile', profiles.organization] })
+  }
+  return steps
+}
+
+/** The API names of the object types in the solution's Blueprint tree. */
+export function blueprintObjectTypes(root: string): string[] {
+  const dir = join(root, 'blueprint', 'object-types')
+  if (!existsSync(dir)) return []
+  const names: string[] = []
+  for (const file of readdirSync(dir).sort()) {
+    if (!/\.(ya?ml|json)$/.test(file) || isIgnoredName(file)) continue
+    let text: string
+    try {
+      text = readFileSync(join(dir, file), 'utf8')
+    } catch {
+      continue
+    }
+    const name = /^\s*"?apiName"?\s*:\s*["']?([A-Za-z][A-Za-z0-9_]*)/m.exec(text)?.[1]
+    if (name && !names.includes(name)) names.push(name)
+  }
+  return names
+}
+
+export function describeTarget(target: SyncTarget): string {
+  switch (target.kind) {
+    case 'dataset':
+      return `dataset ${target.apiName}`
+    case 'agent':
+      return `Agent ${target.slug}`
+    case 'operating':
+      return `Agent ${target.slug} behavior`
+    case 'workflow':
+      return `workflow ${target.slug}`
+    case 'function':
+      return `Function ${basename(target.file).replace(/\.ts$/, '')}`
+    case 'blueprint':
+      return 'Blueprint'
+  }
+}

package/src/local/local-docker.ts

@@ -0,0 +1,146 @@
+import { spawn, spawnSync } from 'node:child_process'
+import { openSync, readFileSync } from 'node:fs'
+
+/**
+ * The container runtime, through its CLI.
+ *
+ * Supabase's CLI drives Docker the same way: one `docker run -d` per service,
+ * named and labelled per project, no Compose file. Shelling out keeps the CLI
+ * free of a Docker SDK and works unchanged on Docker Desktop, OrbStack, Colima
+ * and Podman's docker shim.
+ */
+
+export const PROJECT_LABEL = 'dev.frontera.local.project'
+
+export interface DockerRunSpec {
+  name: string
+  image: string
+  projectId: string
+  ports?: Array<{ host: number; container: number }>
+  env?: Record<string, string>
+  volumes?: Array<{ name: string; path: string }>
+  args?: string[]
+  /** Extra docker flags, e.g. `--add-host`. */
+  flags?: string[]
+  /** Memory ceiling, e.g. `512m`, so one runaway container cannot take the laptop. */
+  memory?: string
+  cpus?: string
+}
+
+export class DockerError extends Error {}
+
+function docker(args: string[], opts: { input?: string } = {}): { ok: boolean; out: string; err: string } {
+  const res = spawnSync('docker', args, { encoding: 'utf8', input: opts.input })
+  if (res.error) {
+    throw new DockerError(
+      (res.error as NodeJS.ErrnoException).code === 'ENOENT'
+        ? 'docker was not found on PATH'
+        : res.error.message,
+    )
+  }
+  return { ok: res.status === 0, out: (res.stdout ?? '').trim(), err: (res.stderr ?? '').trim() }
+}
+
+/** Whether a container runtime answers. */
+export function dockerAvailable(): { ok: true } | { ok: false; reason: string } {
+  try {
+    const r = docker(['info', '--format', '{{.ServerVersion}}'])
+    if (r.ok && r.out) return { ok: true }
+    return { ok: false, reason: r.err.split('\n')[0] || 'the docker daemon did not answer' }
+  } catch (err) {
+    return { ok: false, reason: (err as Error).message }
+  }
+}
+
+export function imagePresent(image: string): boolean {
+  return docker(['image', 'inspect', image, '--format', '{{.Id}}']).ok
+}
+
+/** Pull an image, writing progress to a log file instead of the terminal. */
+export function pullImage(image: string, logFile: string): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const fd = openSync(logFile, 'a')
+    const child = spawn('docker', ['pull', image], { stdio: ['ignore', fd, fd] })
+    child.on('error', reject)
+    child.on('exit', (code) => {
+      if (code === 0) return resolvePromise()
+      // The private release images are the usual failure: say what grants access.
+      let tail = ''
+      try {
+        tail = readFileSync(logFile, 'utf8').slice(-2000)
+      } catch {
+        // The log is a convenience; the exit code is the fact.
+      }
+      const denied = /unauthorized|denied|authentication required/i.test(tail)
+      const host = image.split('/')[0]
+      const reason = denied
+        ? image.startsWith('ghcr.io/')
+          ? `the registry refused access to ${image}: run \`gh auth refresh -s read:packages\`, then \`gh auth token | docker login ghcr.io -u <github-user> --password-stdin\`, or run from a platform checkout without --image`
+          : `the registry refused access to ${image}: sign in with \`docker login ${host}\`, or run from a platform checkout without --image`
+        : /manifest unknown|not found/i.test(tail)
+          ? `${image} is not in the registry: check --registry and --version, or push that release there first`
+          : `docker pull ${image} failed (exit ${code}); see ${logFile}`
+      reject(new DockerError(reason))
+    })
+  })
+}
+
+export function containerState(name: string): 'running' | 'exited' | 'missing' | 'other' {
+  const r = docker(['inspect', name, '--format', '{{.State.Status}}'])
+  if (!r.ok) return 'missing'
+  if (r.out === 'running') return 'running'
+  if (r.out === 'exited' || r.out === 'created') return 'exited'
+  return 'other'
+}
+
+export function runContainer(spec: DockerRunSpec): void {
+  const args = ['run', '-d', '--name', spec.name, '--label', `${PROJECT_LABEL}=${spec.projectId}`]
+  for (const p of spec.ports ?? []) args.push('-p', `127.0.0.1:${p.host}:${p.container}`)
+  for (const [k, v] of Object.entries(spec.env ?? {})) args.push('-e', `${k}=${v}`)
+  for (const v of spec.volumes ?? []) args.push('-v', `${v.name}:${v.path}`)
+  if (spec.memory) args.push('--memory', spec.memory)
+  if (spec.cpus) args.push('--cpus', spec.cpus)
+  args.push(...(spec.flags ?? []))
+  args.push(spec.image, ...(spec.args ?? []))
+  const r = docker(args)
+  if (!r.ok) throw new DockerError(`could not start ${spec.name}: ${r.err.split('\n').slice(-1)[0]}`)
+}
+
+export function startContainer(name: string): void {
+  const r = docker(['start', name])
+  if (!r.ok) throw new DockerError(`could not start ${name}: ${r.err}`)
+}
+
+export function stopContainer(name: string): void {
+  docker(['stop', '-t', '10', name])
+}
+
+export function removeContainer(name: string): void {
+  docker(['rm', '-f', name])
+}
+
+export function removeVolume(name: string): void {
+  docker(['volume', 'rm', '-f', name])
+}
+
+/** Copy a file out of a container to a path on the host. */
+export function copyFromContainer(name: string, path: string, dest: string): boolean {
+  return docker(['cp', `${name}:${path}`, dest]).ok
+}
+
+/** Run a command inside a running container; used for readiness probes. */
+export function execInContainer(name: string, cmd: string[]): boolean {
+  return docker(['exec', name, ...cmd]).ok
+}
+
+/** Follow a container's logs into a file for as long as the container lives. */
+export function followLogs(name: string, logFile: string): void {
+  const fd = openSync(logFile, 'a')
+  const child = spawn('docker', ['logs', '-f', '--since', '0s', name], { stdio: ['ignore', fd, fd], detached: false })
+  child.unref()
+}
+
+export function containersForProject(projectId: string): string[] {
+  const r = docker(['ps', '-a', '--filter', `label=${PROJECT_LABEL}=${projectId}`, '--format', '{{.Names}}'])
+  return r.ok && r.out ? r.out.split('\n') : []
+}