@gamecrate/cli 0.1.0

package/src/index.ts

@@ -0,0 +1,875 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs'
+import { chown, cp, mkdir, readdir, readFile, rm, rmdir, stat, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { basename, dirname, join } from 'node:path'
+import { setTimeout as sleep } from 'node:timers/promises'
+
+import { parseArgs } from './cli/args'
+import { renderCompletion, renderHelp } from './cli/help'
+import { openRunLog, planWarnings, printPlan, redirectOutput, reportProblems, status, warn } from './cli/output'
+import {
+  defaultConfigPath,
+  loadConfig,
+  loadProjectDefaults,
+  profileDataDir,
+  profileDirs,
+  resolveProfile,
+} from './config/load'
+import { resolveIdentity } from './docker/identity'
+import { preflight } from './docker/preflight'
+import { capture, exited, spawnArgv, runContainer, stopContainer, STDOUT_LOG, waitForMarker } from './docker/run'
+import { buildRunSpec, containerName, windowTitle } from './docker/spec'
+import { adoptNewWindow } from './docker/window'
+import { generateModsConfig, mergePrefs } from './launch/generate'
+import {
+  acquireImage,
+  buildLocalMods,
+  captureScreenshot,
+  ensureRuntimeLayer,
+  replacePrevious,
+  takeLock,
+  writeLaunchRecord,
+} from './launch/prepare'
+import { resolveInstance } from './launch/instance'
+import { resolvePlan } from './launch/resolve'
+import { detectForeignOwnership, ensureProfileTree, stageMods } from './launch/stage'
+import { buildIndex } from './mods/modindex'
+import { requirePlugin } from './plugin'
+import type { GamePlugin } from './plugin'
+import { ago, decideStale, duration, scanBuildTimes, staleReport } from './mods/staleness'
+import { resolveWorktree } from './mods/worktree'
+import { GamecrateError, Exit } from './types'
+import type {
+  DockerRunSpec,
+  Identity,
+  LaunchPlan,
+  ParsedArgs,
+  Problem,
+  ProfileConfig,
+  RootConfig,
+  StaleReport,
+} from './types'
+
+const VERSION = '0.1.0'
+const STOP_TIMEOUT_SECONDS = 10
+
+async function main(argv: string[]): Promise<number> {
+  const probe = parseArgs(argv)
+  if (probe.subcommand === 'version') {
+    process.stdout.write(`gamecrate ${VERSION}\n`)
+    return Exit.Ok
+  }
+
+  const [{ config, plugins }, defaults] = await Promise.all([loadConfig(), loadProjectDefaults()])
+  const args = parseArgs(argv, { games: Object.keys(config.games), defaults })
+
+  if (args.help) {
+    process.stdout.write(renderHelp(helpTopic(args), config))
+    return Exit.Ok
+  }
+  const redirect =
+    args.log !== undefined && (args.subcommand === 'run' || args.subcommand === 'shell')
+      ? redirectOutput(args.log)
+      : undefined
+
+  try {
+    return await dispatch(args, config, plugins)
+  } catch (error) {
+    // Printed here, not at the top level: with --log the failure belongs in the log file,
+    // and the top-level printer only runs once the redirect is already closed.
+    return reportFatal(error)
+  } finally {
+    redirect?.close()
+  }
+}
+
+async function dispatch(
+  args: ParsedArgs,
+  config: RootConfig,
+  plugins: Map<string, GamePlugin>,
+): Promise<number> {
+  switch (args.subcommand) {
+    case 'help':
+      return help(args, config)
+    case 'list':
+      return list(args, config)
+    case 'mods':
+      return mods(args, config, plugins)
+    case 'doctor':
+      return doctor(config, plugins)
+    case 'clean':
+      return clean(args, config)
+    case 'clone':
+      return clone(args, config)
+    case 'logs':
+      return logs(args, config)
+    case 'verify':
+      return verify(args, config, plugins)
+    case 'build':
+      return build(args, config)
+    case 'shell':
+      return run(args, config, plugins, true)
+    case 'config':
+      return configEdit(args)
+    case 'fix-perms':
+      return fixPerms(args, config)
+    case 'run':
+      return run(args, config, plugins, false)
+    default:
+      throw new GamecrateError(`no such subcommand ${args.subcommand}`, Exit.Usage)
+  }
+}
+
+function helpTopic(args: ParsedArgs): string | undefined {
+  if (args.subcommand === 'help') return args.rest[0]
+  if (args.subcommand === 'run') return args.game
+  return args.subcommand
+}
+
+function help(args: ParsedArgs, config: RootConfig): number {
+  const topic = args.rest[0]
+  if (topic === 'completion') {
+    const shell = args.rest[1]
+    if (shell !== 'bash' && shell !== 'zsh') {
+      throw new GamecrateError('help completion takes bash or zsh', Exit.Usage)
+    }
+    process.stdout.write(renderCompletion(shell))
+    return Exit.Ok
+  }
+  process.stdout.write(renderHelp(topic, config))
+  return Exit.Ok
+}
+
+function requireGame(args: ParsedArgs, config: RootConfig): string {
+  const game = args.game
+  if (game === undefined) {
+    throw new GamecrateError(
+      `${args.subcommand} needs a game`,
+      Exit.Usage,
+      `known games: ${Object.keys(config.games).join(', ')}`,
+    )
+  }
+  if (!Object.hasOwn(config.games, game)) {
+    throw new GamecrateError(
+      `unknown game "${game}"`,
+      Exit.Config,
+      `known games: ${Object.keys(config.games).join(', ')}`,
+    )
+  }
+  return game
+}
+
+/**
+ * Where a subcommand should look when `--instance` or `--worktree` names one. Resolving the
+ * profile can throw on a name that was never defined, which is not this helper's business.
+ */
+function instanceDir(args: ParsedArgs, config: RootConfig, game: string, profile: string): string {
+  const dir = profileDataDir(config, game, profile)
+  let spec: ProfileConfig | undefined
+  try {
+    spec = resolveProfile(config.games[game]!, profile)
+  } catch {
+    spec = undefined
+  }
+  return resolveInstance({ profileDir: dir, ...(spec === undefined ? {} : { profile: spec }), args }).dir
+}
+
+/** Environment problems are exit 5, never 4: they are about this machine, not the config. */
+function reportEnvironment(problems: Problem[]): never {
+  process.stderr.write(`${problems.length} environment problem(s):\n`)
+  for (const problem of problems) {
+    process.stderr.write(`  ${problem.where}\n    ${problem.message}\n`)
+    if (problem.suggestion) process.stderr.write(`      try: ${problem.suggestion}\n`)
+  }
+  process.exit(Exit.Environment)
+}
+
+/**
+ * config -> index -> resolve -> stage -> generate -> run spec -> execute.
+ * `--dry-run` and `--print-plan` stop after validation, before the first write.
+ */
+async function run(
+  args: ParsedArgs,
+  config: RootConfig,
+  plugins: Map<string, GamePlugin>,
+  asShell: boolean,
+): Promise<number> {
+  const game = requireGame(args, config)
+  const profile = args.profile ?? 'modless'
+
+  const index = await buildIndex(game, config.games[game]!, requirePlugin(plugins, game))
+  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args, index })
+  if (problems.length > 0) reportProblems(problems)
+
+  const identity = resolveIdentity(args.root)
+
+  if (args.printPlan || args.dryRun) {
+    const environment = await preflight(plan)
+    // buildRunSpec is a validation gate of its own: the "=" landmine throws here.
+    buildRunSpec(plan, [], identity)
+    if (args.printPlan) printPlan(plan, args.json)
+    for (const warning of planWarnings(plan)) warn(warning)
+    if (environment.length > 0) return reportEnvironment(environment)
+    if (!args.printPlan) {
+      const what = plan.instance === undefined ? profile : `${profile}/${plan.instance}`
+      status(`${game} ${what}: ${plan.mods.length} mods resolve cleanly`)
+    }
+    return Exit.Ok
+  }
+
+  const environment = await preflight(plan)
+  if (environment.length > 0) return reportEnvironment(environment)
+
+  await ensureProfileTree(plan)
+  if (args.replace) await replacePrevious(plan)
+  const lock = await takeLock(plan)
+  try {
+    return await launch(plan, args, config, identity, asShell)
+  } finally {
+    await lock.release()
+  }
+}
+
+async function launch(
+  plan: LaunchPlan,
+  args: ParsedArgs,
+  config: RootConfig,
+  identity: Identity,
+  asShell: boolean,
+): Promise<number> {
+  const game = plan.game
+  const profile = plan.profile
+  const foreign = await detectForeignOwnership(plan.dataDirHost, identity.uid, 5)
+  if (foreign.length > 0) {
+    throw new GamecrateError(
+      `${foreign.length} path(s) under ${plan.dataDirHost} are not owned by uid ${identity.uid}`,
+      Exit.Environment,
+      `${foreign.join('\n')}\nrun: gamecrate fix-perms ${game} ${profile}`,
+    )
+  }
+
+  const runDir = openRunLog(plan.logsDirHost)
+  plan.runDirHost = runDir
+
+  await buildLocalMods(plan, args.build ?? 'auto')
+  await acquireImage(game, config.games[game]!, args.pull ?? 'missing')
+  // Offscreen modes need an X server the published images do not ship; add it once, on top.
+  const runtimeImage =
+    plan.mode === 'headed'
+      ? config.games[game]!.image.ref
+      : await ensureRuntimeLayer(config.games[game]!.image.ref)
+
+  const modMounts = await stageMods(plan)
+  await generateModsConfig(plan)
+  await mergePrefs(plan)
+  for (const warning of planWarnings(plan)) warn(warning)
+
+  const spec = buildRunSpec(plan, modMounts, identity)
+  spec.image = runtimeImage
+  if (asShell) {
+    spec.command = ['/bin/bash']
+    spec.extraArgs = [...spec.extraArgs, '--interactive', '--tty']
+  }
+  await writeLaunchRecord(plan, spec.image)
+
+  try {
+    // Every path below hands the container to runContainer, which owns SIGINT/SIGTERM: its
+    // handler stops the container, returns 130, and still flushes the log.
+    if (plan.marker !== undefined && !asShell) return await runWithMarker(spec, plan, runDir)
+    if (plan.mode === 'screenshot' && !asShell) return await runWithScreenshot(spec, plan, runDir)
+    // An offscreen run has nobody to close the window, so --timeout bounds it even with no
+    // marker. Without this it runs forever and keeps the profile lock.
+    if (plan.mode !== 'headed' && !asShell) return await runBounded(spec, plan, runDir)
+    // Only X11 lets us touch the window from out here; a wayland client owns its own caption
+    // and its own close button.
+    let windowClosed = false
+    const window =
+      asShell || plan.settings.display !== 'x11'
+        ? null
+        : await adoptNewWindow({
+            executable: plan.gameConfig.executable,
+            title: windowTitle(plan),
+            stripDelete: plan.gameConfig.ignoresWmDelete === true,
+            onClosed: () => {
+              windowClosed = true
+              void stopContainer(spec.name, STOP_TIMEOUT_SECONDS)
+            },
+          })
+    try {
+      const code = await runContainer(spec, {
+        logDir: runDir,
+        stopTimeoutSeconds: STOP_TIMEOUT_SECONDS,
+      })
+      return windowClosed ? Exit.Ok : normalize(code)
+    } finally {
+      window?.stop()
+    }
+  } finally {
+    await copyOutLogs(plan)
+  }
+}
+
+/**
+ * Where a marker can appear. An engine may route its own log away from stdout, and a
+ * copy-out dir is bind-mounted, so both are readable live.
+ */
+function markerSources(plan: LaunchPlan, logDir: string): string[] {
+  const sources = [join(logDir, STDOUT_LOG)]
+  const { logFile } = plan.gameConfig
+  if (logFile.mode === 'arg') sources.push(join(logDir, 'Player.log'))
+  else sources.push(join(plan.dataDirHost, logFile.from))
+  return sources
+}
+
+/** Offscreen run with no marker: the deadline is the only thing that can end it. */
+async function runBounded(
+  spec: DockerRunSpec,
+  plan: LaunchPlan,
+  logDir: string,
+): Promise<number> {
+  const container = runContainer(spec, { logDir, stopTimeoutSeconds: STOP_TIMEOUT_SECONDS })
+  const winner = await Promise.race([
+    container.then((code) => ({ kind: 'exit' as const, code })),
+    sleep(plan.timeoutSeconds * 1000).then(() => ({ kind: 'timeout' as const })),
+  ])
+  if (winner.kind === 'exit') return normalize(winner.code)
+
+  status(`no marker given; stopping after ${plan.timeoutSeconds}s`)
+  await stopContainer(spec.name, STOP_TIMEOUT_SECONDS)
+  await container
+  return Exit.Ok
+}
+
+/** Waits for the game to render, grabs one frame, then stops the container. */
+async function runWithScreenshot(
+  spec: DockerRunSpec,
+  plan: LaunchPlan,
+  logDir: string,
+): Promise<number> {
+  const container = runContainer(spec, { logDir, stopTimeoutSeconds: STOP_TIMEOUT_SECONDS })
+  const settled = sleep(plan.renderWaitSeconds * 1000).then(() => 'ready' as const)
+
+  const winner = await Promise.race([
+    container.then((code) => ({ kind: 'exit' as const, code })),
+    settled.then(() => ({ kind: 'ready' as const })),
+  ])
+  if (winner.kind === 'exit') {
+    status(`game exited before the ${plan.renderWaitSeconds}s render wait finished; no frame captured`)
+    return normalize(winner.code)
+  }
+
+  const shot = await grabFrame(spec.name, plan)
+  await stopContainer(spec.name, STOP_TIMEOUT_SECONDS)
+  await container
+  return shot === null ? Exit.Environment : Exit.Ok
+}
+
+async function grabFrame(container: string, plan: LaunchPlan): Promise<string | null> {
+  const path = await captureScreenshot(container, plan)
+  if (path === null) warn('screenshot capture failed; is imagemagick in the image?')
+  else status(`screenshot: ${path}`)
+  return path
+}
+/** The marker races the container; whichever finishes first decides the exit code. */
+async function runWithMarker(
+  spec: DockerRunSpec,
+  plan: LaunchPlan,
+  logDir: string,
+): Promise<number> {
+  const marker = plan.marker!
+  const container = runContainer(spec, { logDir, stopTimeoutSeconds: STOP_TIMEOUT_SECONDS })
+  const seen = waitForMarker(markerSources(plan, logDir), marker, plan.timeoutSeconds)
+
+  const winner = await Promise.race([
+    container.then((code) => ({ kind: 'exit' as const, code })),
+    seen.then((hit) => ({ kind: 'marker' as const, hit })),
+  ])
+  if (winner.kind === 'exit') return normalize(winner.code)
+
+  if (plan.mode === 'screenshot') await grabFrame(spec.name, plan)
+  await stopContainer(spec.name, STOP_TIMEOUT_SECONDS)
+  await container
+  if (winner.hit) {
+    status(`marker seen: ${marker}`)
+    return Exit.Ok
+  }
+  status(`marker "${marker}" not seen within ${plan.timeoutSeconds}s`)
+  return Exit.MarkerTimeout
+}
+
+function normalize(code: number): number {
+  return Number.isInteger(code) && code >= 0 && code <= 255 ? code : Exit.GameFailed
+}
+
+/** A copy-out game writes logs under its own data root with no flag, so they move after. */
+async function copyOutLogs(plan: LaunchPlan): Promise<void> {
+  const spec = plan.gameConfig.logFile
+  if (spec.mode !== 'copy-out') return
+  const source = join(plan.dataDirHost, spec.from)
+  if (!existsSync(source)) return
+  const target = join(plan.runDirHost, basename(spec.from.replace(/\/+$/, '')))
+  try {
+    await cp(source, target, { recursive: true, force: true })
+  } catch (error) {
+    warn(`could not copy ${source}: ${describe(error)}`)
+  }
+}
+
+
+function list(args: ParsedArgs, config: RootConfig): number {
+  const games = args.game === undefined ? Object.keys(config.games) : [requireGame(args, config)]
+
+  if (args.json) {
+    const payload = games.map((name) => {
+      const game = config.games[name]!
+      return {
+        game: name,
+        core: game.core,
+        dlc: game.dlc,
+        modes: game.modes,
+        profiles: Object.entries(game.profiles).map(([profile, spec]) => ({
+          profile,
+          alias: spec.alias ?? null,
+          extends: spec.extends ?? null,
+          mods: spec.mods?.length ?? 0,
+          instances: Object.keys(spec.instances ?? {}),
+        })),
+      }
+    })
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
+    return Exit.Ok
+  }
+
+  const out: string[] = []
+  for (const name of games) {
+    const game = config.games[name]!
+    const width = Math.max(7, ...Object.keys(game.profiles).map((n) => n.length))
+    out.push(`${name}  (${game.modes.join(', ')})`)
+    out.push(`  ${'modless'.padEnd(width)}  built-in: core + official DLC`)
+    for (const [profile, spec] of Object.entries(game.profiles)) {
+      const notes: string[] = []
+      if (spec.alias) notes.push(`alias for ${spec.alias}`)
+      if (spec.extends) notes.push(`extends ${spec.extends}`)
+      const count = spec.mods?.length ?? 0
+      if (!spec.alias) notes.push(count === 1 ? '1 entry' : `${count} entries`)
+      if (spec.aliases?.length) notes.push(`aka ${spec.aliases.join(', ')}`)
+      out.push(`  ${profile.padEnd(width)}  ${notes.join(', ')}`)
+      const instances = Object.keys(spec.instances ?? {})
+      if (instances.length > 0) out.push(`  ${' '.repeat(width)}  instances: ${instances.join(', ')}`)
+    }
+  }
+  process.stdout.write(`${out.join('\n')}\n`)
+  return Exit.Ok
+}
+
+async function mods(args: ParsedArgs, config: RootConfig, plugins: Map<string, GamePlugin>): Promise<number> {
+  const game = requireGame(args, config)
+  const profile = args.profile ?? 'modless'
+  const index = await buildIndex(game, config.games[game]!, requirePlugin(plugins, game))
+  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args, index })
+  if (problems.length > 0) reportProblems(problems)
+  printPlan(plan, args.json)
+  return Exit.Ok
+}
+
+async function doctor(config: RootConfig, plugins: Map<string, GamePlugin>): Promise<number> {
+  let failed = false
+  for (const game of Object.keys(config.games)) {
+    const { plan, problems } = await resolvePlan({ game, profile: 'modless', root: config, plugins })
+    const all = [...problems, ...(await preflight(plan))]
+    if (all.length === 0) {
+      status(`${game}: ok`)
+      continue
+    }
+    failed = true
+    status(`${game}: ${all.length} problem(s)`)
+    for (const problem of all) {
+      process.stderr.write(`  ${problem.where}\n    ${problem.message}\n`)
+      if (problem.suggestion) process.stderr.write(`      try: ${problem.suggestion}\n`)
+    }
+  }
+  return failed ? Exit.Environment : Exit.Ok
+}
+
+async function logs(args: ParsedArgs, config: RootConfig): Promise<number> {
+  const game = requireGame(args, config)
+  const profile = args.profile ?? 'modless'
+  const runs = join(instanceDir(args, config, game, profile), 'logs', 'runs')
+
+  const latest = (await readdir(runs, { withFileTypes: true }).catch(() => []))
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .at(-1)
+  if (latest === undefined) {
+    throw new GamecrateError(`no runs recorded for ${game} ${profile}`, Exit.Usage, runs)
+  }
+
+  const dir = join(runs, latest)
+  const files = (await readdir(dir, { withFileTypes: true }))
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .sort()
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify({ run: latest, dir, files }, null, 2)}\n`)
+    return Exit.Ok
+  }
+
+  status(dir)
+  for (const name of files) {
+    const text = await readFile(join(dir, name), 'utf8').catch(() => '')
+    for (const line of text.split('\n')) {
+      if (line.length > 0) process.stdout.write(`${name}: ${line}\n`)
+    }
+  }
+  return Exit.Ok
+}
+
+interface DockerInspect {
+  State?: { Running?: boolean; StartedAt?: string }
+  Mounts?: { Source?: string; Destination?: string }[]
+}
+
+interface ContainerInfo {
+  running: boolean
+  startedAt: number
+  mounts: { source: string; destination: string }[]
+}
+
+async function inspectContainer(name: string): Promise<ContainerInfo | null> {
+  const { code, stdout: text } = await capture(['docker', 'inspect', name])
+  if (code !== 0) return null
+
+  let first: DockerInspect | undefined
+  try {
+    first = (JSON.parse(text) as DockerInspect[])[0]
+  } catch {
+    return null
+  }
+  if (first === undefined) return null
+
+  const startedAt = Date.parse(first.State?.StartedAt ?? '')
+  return {
+    running: first.State?.Running === true,
+    startedAt: Number.isNaN(startedAt) ? Date.now() : startedAt,
+    mounts: (first.Mounts ?? [])
+      .filter((m) => m.Source !== undefined && m.Destination !== undefined)
+      .map((m) => ({ source: m.Source!, destination: m.Destination! })),
+  }
+}
+
+interface BoundMod {
+  packageId: string
+  hostDir: string
+  branch: string | null
+  assembly: { path: string; mtimeMs: number } | null
+  hasSources: boolean
+  stale: boolean
+  report: StaleReport | null
+}
+
+function boundStatus(mod: BoundMod): string {
+  if (mod.report !== null) {
+    const files = mod.report.newerCount === 1 ? '1 source' : `${mod.report.newerCount} sources`
+    return `STALE - ${files} newer`
+  }
+  if (mod.assembly !== null) return 'OK'
+  return mod.hasSources ? 'STALE - never built' : '(xml only)'
+}
+
+/**
+ * What the container is running right now, read off its own mounts. A green build proves the
+ * compiler ran somewhere, not that it wrote into the directory this container bound.
+ */
+async function verify(args: ParsedArgs, config: RootConfig, plugins: Map<string, GamePlugin>): Promise<number> {
+  const game = requireGame(args, config)
+  const profile = args.profile ?? 'modless'
+  const { plan, problems } = await resolvePlan({ game, profile, root: config, plugins, args })
+  if (problems.length > 0) reportProblems(problems)
+
+  const name = containerName(plan)
+  const info = await inspectContainer(name)
+  if (info === null || !info.running) {
+    throw new GamecrateError(
+      `no container named ${name} is running`,
+      Exit.Environment,
+      'launch it first, or name the run with --instance or --worktree',
+    )
+  }
+
+  // Per-mod binds are one level under the mods dir; the staged tree itself is the parent.
+  const prefix = `${plan.gameConfig.modsDir.container}/`
+  const bound = info.mounts
+    .filter((m) => m.destination.startsWith(prefix))
+    .filter((m) => !m.destination.slice(prefix.length).includes('/'))
+    .sort((a, b) => (a.destination < b.destination ? -1 : 1))
+
+  const boundMods: BoundMod[] = await Promise.all(
+    bound.map(async (mount): Promise<BoundMod> => {
+      const times = await scanBuildTimes(mount.source)
+      const request = resolveWorktree(mount.source, 'ref', 0)
+      return {
+        packageId: mount.destination.slice(prefix.length),
+        hostDir: mount.source,
+        branch: 'root' in request ? request.branch : null,
+        assembly: times.newestAssembly ?? null,
+        hasSources: times.newestSource !== undefined,
+        stale: decideStale(times),
+        report: staleReport(times),
+      }
+    }),
+  )
+
+  const stale = boundMods.filter((mod) => mod.stale)
+  if (args.json) {
+    const payload = {
+      container: name,
+      running: true,
+      upSeconds: Math.round((Date.now() - info.startedAt) / 1000),
+      instance: plan.instance ?? plan.profile,
+      stale: stale.length,
+      mods: boundMods.map((mod) => ({
+        packageId: mod.packageId,
+        hostDir: mod.hostDir,
+        branch: mod.branch,
+        assembly: mod.assembly?.path ?? null,
+        assemblyMs: mod.assembly?.mtimeMs ?? null,
+        stale: mod.stale,
+        status: boundStatus(mod),
+        ...(mod.report === null ? {} : { report: mod.report }),
+      })),
+    }
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`)
+    return stale.length > 0 ? Exit.Stale : Exit.Ok
+  }
+
+  process.stdout.write(`${renderVerify(name, info, plan, boundMods)}\n`)
+  return stale.length > 0 ? Exit.Stale : Exit.Ok
+}
+
+function renderVerify(
+  name: string,
+  info: ContainerInfo,
+  plan: LaunchPlan,
+  boundMods: BoundMod[],
+): string {
+  const out = [
+    '',
+    `  container   ${name} (up ${duration(Date.now() - info.startedAt)})`,
+    `  instance    ${plan.instance ?? plan.profile}`,
+    '',
+  ]
+  if (boundMods.length === 0) {
+    out.push('  no boundMods are bind-mounted into this container')
+    return out.join('\n')
+  }
+
+  const paths = boundMods.map((mod) => shortenHome(mod.hostDir))
+  const idWidth = Math.max(...boundMods.map((mod) => mod.packageId.length))
+  const pathWidth = Math.max(...paths.map((p) => p.length))
+  const stamps = boundMods.map((mod) =>
+    mod.assembly === null ? 'no assemblies' : `${mod.assembly.path}  ${ago(mod.assembly.mtimeMs)}`,
+  )
+  const stampWidth = Math.max(...stamps.map((s) => s.length))
+
+  for (const [i, mod] of boundMods.entries()) {
+    const origin = mod.branch === null ? '' : `worktree ${mod.branch}`
+    out.push(`  ${mod.packageId.padEnd(idWidth)}  ${paths[i]!.padEnd(pathWidth)} ${origin}`.trimEnd())
+    out.push(`  ${' '.repeat(idWidth)}  ${stamps[i]!.padEnd(stampWidth)}   ${boundStatus(mod)}`)
+  }
+  return out.join('\n')
+}
+
+function shortenHome(path: string): string {
+  const home = homedir()
+  return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path
+}
+
+/** Tiered on purpose: the default tier can never reach a save. */
+async function clean(args: ParsedArgs, config: RootConfig): Promise<number> {
+  const game = requireGame(args, config)
+  const profile = args.profile
+  if (profile === undefined) throw new GamecrateError('clean needs a profile', Exit.Usage)
+
+  const dir = profileDataDir(config, game, profile)
+  const tier = args.cleanTier ?? 'staging'
+  const saveSuffixes = config.games[game]!.saveExtensions.map((ext) => `.${ext.replace(/^\./, '')}`.toLowerCase())
+
+  // The cheap tiers belong to one instance; --all takes the profile and every instance with it.
+  if (tier !== 'all') {
+    const target = join(instanceDir(args, config, game, profile), tier === 'logs' ? 'logs' : '.stage')
+    await rm(target, { recursive: true, force: true })
+    status(`removed ${target}`)
+    return Exit.Ok
+  }
+
+  const saves = await countSaves(dir, saveSuffixes)
+  if (!args.yes) {
+    throw new GamecrateError(
+      `clean --all would delete ${dir}, including ${saves} save file(s)`,
+      Exit.Usage,
+      'add --yes to confirm',
+    )
+  }
+  await rm(dir, { recursive: true, force: true })
+  status(`removed ${dir} (${saves} save file(s))`)
+  return Exit.Ok
+}
+
+async function countSaves(dir: string, suffixes: string[]): Promise<number> {
+  let count = 0
+  const queue = [dir]
+  while (queue.length > 0) {
+    const current = queue.shift()!
+    let entries
+    try {
+      entries = await readdir(current, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory()) queue.push(join(current, entry.name))
+      else if (suffixes.some((s) => entry.name.toLowerCase().endsWith(s))) count++
+    }
+  }
+  return count
+}
+
+/** `cp -a --reflink=auto`: on btrfs the precious tier copies in constant time. */
+async function clone(args: ParsedArgs, config: RootConfig): Promise<number> {
+  const game = requireGame(args, config)
+  const [src, dst] = args.rest
+  if (src === undefined || dst === undefined) {
+    throw new GamecrateError('clone needs a source and a destination profile', Exit.Usage)
+  }
+
+  const from = join(profileDataDir(config, game, src), 'game')
+  const to = join(profileDataDir(config, game, dst), 'game')
+  if (!existsSync(from)) throw new GamecrateError(`${from} does not exist`, Exit.Usage)
+  if (existsSync(to) && !args.yes) {
+    throw new GamecrateError(`${to} already exists`, Exit.Usage, 'add --yes to overwrite')
+  }
+
+  await mkdir(to, { recursive: true })
+  const code = await spawnStatus(['cp', '-a', '--reflink=auto', `${from}/.`, to])
+  if (code !== 0) throw new GamecrateError(`cp failed with exit ${code}`, Exit.Environment)
+  status(`cloned ${from} -> ${to}`)
+  return Exit.Ok
+}
+
+async function build(args: ParsedArgs, config: RootConfig): Promise<number> {
+  const game = requireGame(args, config)
+  await acquireImage(game, config.games[game]!, args.pull ?? 'always')
+  status(`${config.games[game]!.image.ref} is ready`)
+  return Exit.Ok
+}
+
+async function configEdit(args: ParsedArgs): Promise<number> {
+  if (args.rest[0] !== 'edit') throw new GamecrateError('config takes one word: edit', Exit.Usage)
+
+  const path = defaultConfigPath()
+  await mkdir(dirname(path), { recursive: true })
+  if (!existsSync(path)) await writeFile(path, '{\n  "games": {}\n}\n')
+
+  const editor = process.env.VISUAL ?? process.env.EDITOR
+  if (editor === undefined) throw new GamecrateError('no $EDITOR or $VISUAL set', Exit.Usage, path)
+  if ((await spawnStatus([...editor.split(' '), path], true)) !== 0) return Exit.Usage
+
+  await loadConfig(path)
+  status(`${path} is valid`)
+  return Exit.Ok
+}
+
+/** Never silently chowns: it reports what it found and only acts under --yes. */
+async function fixPerms(args: ParsedArgs, config: RootConfig): Promise<number> {
+  const game = requireGame(args, config)
+  const identity = resolveIdentity(false)
+  const found: string[] = []
+  for (const dir of await profileDirs(config, game, args.profile)) {
+    if (!existsSync(dir)) continue
+    found.push(...(await detectForeignOwnership(dir, identity.uid, 10_000)))
+  }
+
+  if (found.length === 0) {
+    status(`${game}: every path is owned by uid ${identity.uid}`)
+    return Exit.Ok
+  }
+  if (args.dryRun || !args.yes) {
+    for (const path of found) process.stdout.write(`would chown ${identity.uid}:${identity.gid} ${path}\n`)
+    status(`${found.length} foreign-owned path(s); re-run with --yes to chown them`)
+    return Exit.Environment
+  }
+  // chown of a foreign-owned path needs root either way, so an empty directory whose parent
+  // we own is recovered by removing it: the next launch recreates it as the caller.
+  let fixed = 0
+  const stuck: string[] = []
+  for (const path of found) {
+    const chowned = await chown(path, identity.uid, identity.gid).then(
+      () => true,
+      () => false,
+    )
+    if (chowned) {
+      fixed += 1
+      continue
+    }
+    if (await removeIfEmptyDir(path)) {
+      status(`removed empty ${path}; it will be recreated on the next run`)
+      fixed += 1
+      continue
+    }
+    stuck.push(path)
+  }
+
+  if (fixed > 0) status(`fixed ${fixed} path(s) for ${identity.uid}:${identity.gid}`)
+  if (stuck.length > 0) {
+    for (const path of stuck) warn(`cannot chown ${path}`)
+    throw new GamecrateError(
+      `${stuck.length} path(s) still not owned by uid ${identity.uid}`,
+      Exit.Environment,
+      `sudo chown -R ${identity.uid}:${identity.gid} ${stuck.join(' ')}`,
+    )
+  }
+  return Exit.Ok
+}
+
+/** Removing needs write on the parent, not ownership of the directory itself. */
+async function removeIfEmptyDir(path: string): Promise<boolean> {
+  const info = await stat(path).catch(() => null)
+  if (info === null || !info.isDirectory()) return false
+  const entries = await readdir(path).catch((): string[] | null => null)
+  if (entries === null || entries.length > 0) return false
+  // fs.rm on a directory needs recursive:true; rmdir is the one that removes an empty dir.
+  return rmdir(path).then(
+    () => true,
+    () => false,
+  )
+}
+
+async function spawnStatus(argv: string[], interactive = false): Promise<number> {
+  const proc = spawnArgv(argv, [interactive ? 'inherit' : 'ignore', 'inherit', 'inherit'])
+  return exited(proc)
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/** Prints a failure and returns its exit code. Shared, so --log and the bare path agree. */
+function reportFatal(error: unknown): number {
+  if (error instanceof GamecrateError) {
+    process.stderr.write(`gamecrate: ${error.message}\n`)
+    if (error.detail) process.stderr.write(`${error.detail}\n`)
+    return error.code
+  }
+  process.stderr.write(`gamecrate: ${describe(error)}\n`)
+  return Exit.GameFailed
+}
+
+try {
+  process.exit(await main(process.argv.slice(2)))
+} catch (error) {
+  // Only reachable for failures before dispatch: arg parsing and config loading.
+  process.exit(reportFatal(error))
+}