@curia-sh/cli 0.4.1

package/src/purge.mjs

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+
+import { EXIT, Refusal, UsageError } from './exit.mjs'
+import { dockerRunner } from './compose.mjs'
+import { launcherPath } from './launcher.mjs'
+import { withLifecycleLock } from './lock.mjs'
+import { removeInstallationResources, removeReleaseImages } from './resources.mjs'
+import { openRoot, recordPath } from './root.mjs'
+import { namedSteps } from './steps.mjs'
+import { readTailscaleRecord, tailscaleRunner, withdrawServeRoutes } from './tailscale.mjs'
+import { externalChecklist, purgeCommand } from './uninstall.mjs'
+
+// `curia purge` (#887, implementing #855): the confirmed purge. It removes
+// every local trace of one installation after one explicit confirmation, as
+// six named steps.
+//
+//   preflight  the root boundary (`openRoot`, which must find an
+//              installation), then the warning: the exact root and what
+//              goes with it. Nothing changes.
+//   confirm    the one confirmation. On a terminal the operator types the
+//              exact installation root; without one, `--confirm <root>` on
+//              the command line says the same thing. Anything else stops the
+//              command with nothing changed. There is no second question, no
+//              scan for unpublished work, and no salvage.
+//   docker     under the lifecycle lock from here to the end: every
+//              container, network, and volume that carries this
+//              installation's label, the same teardown as uninstall.
+//   routes     the Tailscale Serve routes Curia created, the same as uninstall.
+//   images     the release images nothing on the host uses any more. Found
+//              by their exact repositories, never by a name prefix, and
+//              removed only when Docker lists no container over them and
+//              accepts the removal without force. An image another
+//              installation runs stays. The agent image the service built is
+//              not a release image and stays.
+//   root       the launcher when it names this root, then the installation
+//              root itself, last, with the installation record as the last
+//              file inside it, so a rerun over a half-removed root still
+//              finds the installation.
+//
+// The installation ID and the external identifiers are read before anything
+// is removed, because the files that hold them go with the root. Every step
+// reads before it removes, so a rerun over a partial purge finishes it. The
+// bootstrap's `--purge` runs this command from a temporary stage with
+// `CURIA_ROOT` only: no launcher, no stage, and possibly a root whose `run/`
+// is already gone, so the lock's directory is created when it is missing.
+
+export const PURGE_STEPS = Object.freeze(['preflight', 'confirm', 'docker', 'routes', 'images', 'root'])
+
+export const CONFIRM_OPTION = '--confirm'
+const PROMPT = 'Type the installation root to confirm, or anything else to stop: '
+
+// The command's seam. `context` is what `runCli` hands a command. `deps` are
+// the boundaries a test replaces: the Docker runner, the `tailscale` runner,
+// the question on the terminal, and whether there is a terminal to ask on.
+export async function runPurge(
+  { env, args = [], stdout, uid, root },
+  { docker = dockerRunner, tailscale = tailscaleRunner, prompt = askOnTerminal, isTerminal = () => Boolean(process.stdin.isTTY) } = {},
+) {
+  const confirmed = confirmationFromArgs(args)
+  const launcher = launcherPath(env)
+  const bootstrap = purgeCommand({ env, root })
+  const steps = namedSteps({
+    steps: PURGE_STEPS,
+    stdout,
+    rerun: (step) => (existsSync(launcher)
+      ? `Run '${launcher} purge' to run ${step} again; the completed steps are kept.`
+      : `Fix the cause, then run 'curia purge' again from the bootstrap (${bootstrap}); the completed steps are kept.`),
+  })
+  const say = (text) => stdout.write(`${text}\n`)
+
+  try {
+    // 1. preflight
+    steps.begin('preflight')
+    const opened = openRoot(root, { uid })
+    if (opened.status !== 'installed') {
+      throw new Refusal(`${root} holds no installation, so there is nothing to purge. Nothing changed.`)
+    }
+    const { installationId, activeVersion } = opened.record
+    const external = externalChecklist(root, { uid })
+    const recordedRoutes = readTailscaleRecord(join(root, 'state')).serve
+    say(`This purges the Curia installation at ${root} (installation ${installationId}, version ${activeVersion}).`)
+    say('It deletes, with no way back:')
+    say('  - your configuration (config/), credentials (secrets/), history (state/), and unfinished work (work/)')
+    say('  - the installed versions, caches, and runtime files (versions/, cache/, run/) and the launcher')
+    say("  - the installation's containers, networks, and volumes, and the release images nothing else uses")
+    say('  - the Tailscale Serve routes Curia created')
+    say('It does not delete the GitHub App, the Discord bot and channel, the Tailscale node, or any model-provider login; those stay yours to remove.')
+
+    // 2. confirm
+    steps.begin('confirm')
+    if (confirmed !== null) {
+      if (confirmed !== root) throw new Refusal(`${CONFIRM_OPTION} names ${confirmed}, not the installation root ${root}. Nothing changed.`)
+    } else if (!isTerminal()) {
+      throw new Refusal(`no terminal to confirm on. Run 'curia purge ${CONFIRM_OPTION} ${root}' to confirm without a prompt. Nothing changed.`)
+    } else if ((await prompt(PROMPT)) !== root) {
+      throw new Refusal('the answer did not match the installation root. Nothing changed.')
+    }
+    say(`confirmed: purging ${root}`)
+
+    // The lock lives under run/, which a partial purge or the bootstrap's
+    // stage case may find missing.
+    const runDir = join(root, 'run')
+    if (!existsSync(runDir)) mkdirSync(runDir, { mode: 0o700 })
+
+    return await withLifecycleLock(root, async () => {
+      // 3. docker
+      steps.begin('docker')
+      const removed = await removeInstallationResources(installationId, { docker, stdout })
+      const count = removed.containers.length + removed.networks.length + removed.volumes.length
+      say(count === 0
+        ? `no container, network, or volume carries the label of installation ${installationId}`
+        : `removed every container, network, and volume of installation ${installationId}`)
+
+      // 4. routes
+      steps.begin('routes')
+      const routes = await withdrawServeRoutes({ stateDir: join(root, 'state'), stdout }, { tailscale })
+      if (routes.recorded.length === 0) say('no Serve route is recorded for this installation')
+      else if (routes.withdrawn.length === 0 && routes.absent.length > 0 && !routes.unreachable) say('no recorded Serve route is standing; nothing to withdraw')
+
+      // 5. images
+      steps.begin('images')
+      const images = await removeReleaseImages({ docker, stdout })
+      if (images.found.length === 0) say('no release image is on this host')
+      else say(`release images: ${images.removed.length} removed, ${images.kept.length} kept`)
+
+      // 6. root
+      steps.begin('root')
+      const launcherFate = removeLauncher(launcher, root)
+      say(launcherFate === 'removed' ? `removed the launcher ${launcher}`
+        : launcherFate === 'foreign' ? `kept the launcher ${launcher}: it belongs to another installation root`
+          : `no launcher at ${launcher}`)
+      removeRoot(root)
+      say(`removed ${root}`)
+
+      say('')
+      say(`Curia is purged. The installation root ${root} is removed.`)
+      say(`  removed:   the root with config/, secrets/, state/, and work/, the launcher, the installation's containers, networks, and volumes, and ${images.removed.length === 1 ? '1 release image' : `${images.removed.length} release images`}`)
+      if (images.kept.length > 0) say(`  kept:      ${images.kept.length === 1 ? '1 release image' : `${images.kept.length} release images`} still in use on this host (listed under [5/6] images)`)
+      say(`  reinstall: a later install starts a new installation with a new ID; the removed one cannot come back`)
+      say('')
+      say('External resources Curia never deletes. Deleting the local secret files revokes nothing: each credential stays valid until you remove it where it was issued.')
+      for (const line of external) say(`  ${line}`)
+      for (const route of recordedRoutes) {
+        const withdrawn = routes.withdrawn.some((r) => r.https === route.https && r.target === route.target)
+        const absent = routes.absent.some((r) => r.https === route.https && r.target === route.target) && !routes.unreachable
+        say(`  Serve route https://:${route.https} -> ${route.target}: ${withdrawn ? 'withdrawn' : absent ? 'was not standing' : `still recorded when the root was removed; run 'tailscale serve --https=${route.https} off' on the node`}`)
+      }
+      say('  Model-provider logins (Anthropic, OpenAI): revoke them in each provider\'s account settings if you won\'t reinstall; only the local copies were deleted.')
+      return EXIT.ok
+    })
+  } catch (e) {
+    throw steps.wrap(e)
+  }
+}
+
+// `--confirm <root>` or `--confirm=<root>`; anything else on the line is a
+// usage error before the command runs.
+export function confirmationFromArgs(args) {
+  let value = null
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === CONFIRM_OPTION) {
+      if (i + 1 >= args.length || args[i + 1].startsWith('-')) throw new UsageError(`${CONFIRM_OPTION} needs the installation root as its value`)
+      value = args[++i]
+    } else if (arg.startsWith(`${CONFIRM_OPTION}=`)) {
+      value = arg.slice(CONFIRM_OPTION.length + 1)
+      if (value === '') throw new UsageError(`${CONFIRM_OPTION} needs the installation root as its value`)
+    } else if (arg.startsWith('-')) {
+      throw new UsageError(`unknown option: ${arg}`)
+    } else {
+      throw new UsageError(`unexpected argument: ${arg}`)
+    }
+  }
+  return value
+}
+
+// The question on the operator's terminal, answered once.
+function askOnTerminal(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout })
+    rl.question(question, (answer) => {
+      rl.close()
+      resolve(answer)
+    })
+  })
+}
+
+// Removes the launcher when it names this root. A launcher of another root
+// is another installation's and stays. The same rule as uninstall.
+function removeLauncher(launcher, root) {
+  let text
+  try {
+    text = readFileSync(launcher, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return 'absent'
+    throw e
+  }
+  if (!text.includes(`CURIA_ROOT='${root}'`)) return 'foreign'
+  unlinkSync(launcher)
+  return 'removed'
+}
+
+// Removes the root with the installation record last: everything beside
+// `state/` first, then everything in `state/` beside the record, then the
+// record with the rest. A failure anywhere before the end leaves a root that
+// `openRoot` still recognizes, so the rerun is a purge and not a refusal of
+// an unknown directory.
+function removeRoot(root) {
+  const record = recordPath(root)
+  const stateDir = join(root, 'state')
+  for (const entry of readdirSync(root)) {
+    if (entry === 'state') continue
+    rmSync(join(root, entry), { recursive: true, force: true })
+  }
+  if (existsSync(stateDir)) {
+    for (const entry of readdirSync(stateDir)) {
+      const file = join(stateDir, entry)
+      if (file === record) continue
+      rmSync(file, { recursive: true, force: true })
+    }
+  }
+  rmSync(root, { recursive: true, force: true })
+}
+
+// Used by the command table.
+export function purgeCommandRun(context, deps) {
+  return runPurge(context, deps)
+}

package/src/resources.mjs

@@ -0,0 +1,146 @@
+import { IMAGE_REGISTRY, INSTALLATION_LABEL, RELEASE_IMAGES } from './bundle.mjs'
+import { dockerRunner } from './compose.mjs'
+
+// The Docker resources of one installation, found by label and by nothing
+// else (#886 and #887, implementing #855).
+//
+// Every container, network, and volume Curia creates for an installation
+// carries `sh.curia.installation=<installation ID>`: the Compose bundle puts
+// it on the five services, the project network, and the tmux socket volume,
+// and the service puts it on every agent container and the agent cache
+// volumes it creates. So one filter names what belongs to an installation on
+// a host, whatever the Compose project's files are in, and a name prefix is
+// never read as ownership. A container of another installation, an
+// operator's own container, and a probe container without the label are
+// never listed and never touched.
+//
+// Uninstall stops and removes them; purge does the same and then removes
+// the release images. Both read what is there before they remove it, so a
+// rerun over a host where nothing is left lists nothing and removes nothing.
+
+export class DockerError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'DockerError'
+  }
+}
+
+const filter = (installationId) => ['--filter', `label=${INSTALLATION_LABEL}=${installationId}`]
+
+// The labelled resources: `{ containers: [{ id, name, running }], networks:
+// [{ id, name }], volumes: [{ name }] }`.
+export async function installationResources(installationId, { docker = dockerRunner } = {}) {
+  const containers = (await run(docker, ['ps', '--all', '--no-trunc', ...filter(installationId), '--format', '{{.ID}}\t{{.Names}}\t{{.State}}']))
+    .map((line) => {
+      const [id, name, state] = line.split('\t')
+      return { id, name, running: state === 'running' }
+    })
+  const networks = (await run(docker, ['network', 'ls', '--no-trunc', ...filter(installationId), '--format', '{{.ID}}\t{{.Name}}']))
+    .map((line) => {
+      const [id, name] = line.split('\t')
+      return { id, name }
+    })
+  const volumes = (await run(docker, ['volume', 'ls', ...filter(installationId), '--format', '{{.Name}}']))
+    .map((name) => ({ name }))
+  return { containers, networks, volumes }
+}
+
+// Stops every running labelled container, then removes every labelled
+// container, network, and volume, in that order, so the network and the
+// volumes are free when they are removed. Returns what was removed. A stop
+// gives each process its termination signal and the usual grace before the
+// kill, which is what lets the service close its journal; nothing waits for
+// a session to finish, and nothing drains one.
+export async function removeInstallationResources(installationId, { docker = dockerRunner, stdout } = {}) {
+  const found = await installationResources(installationId, { docker })
+  const running = found.containers.filter((c) => c.running)
+  if (running.length > 0) {
+    stdout?.write(`stopping ${describe(running.map((c) => c.name), 'container')}\n`)
+    await run(docker, ['stop', ...running.map((c) => c.id)])
+  }
+  if (found.containers.length > 0) {
+    stdout?.write(`removing ${describe(found.containers.map((c) => c.name), 'container')}\n`)
+    await run(docker, ['rm', '--force', '--volumes', ...found.containers.map((c) => c.id)])
+  }
+  if (found.networks.length > 0) {
+    stdout?.write(`removing ${describe(found.networks.map((n) => n.name), 'network')}\n`)
+    await run(docker, ['network', 'rm', ...found.networks.map((n) => n.id)])
+  }
+  if (found.volumes.length > 0) {
+    stdout?.write(`removing ${describe(found.volumes.map((v) => v.name), 'volume')}\n`)
+    await run(docker, ['volume', 'rm', '--force', ...found.volumes.map((v) => v.name)])
+  }
+  return found
+}
+
+// The release images on the host: every image under one of the four exact
+// repositories `RELEASE_IMAGES` names, whatever release it belongs to, as
+// `{ id, reference }` with the reference `<repository>@<digest>` (or
+// `<repository>:<tag>` for one pulled by tag). Images are not labelled with
+// an installation, because two installations on one host share a pulled
+// image, so the repository is the identity; a name that merely starts with
+// `curia-` is never read as a release image.
+export async function releaseImages({ docker = dockerRunner } = {}) {
+  const seen = new Map()
+  for (const name of Object.values(RELEASE_IMAGES)) {
+    const repository = `${IMAGE_REGISTRY}/${name}`
+    const rows = await run(docker, ['image', 'ls', '--no-trunc', '--digests', '--filter', `reference=${repository}`, '--format', '{{.ID}}\t{{.Repository}}\t{{.Tag}}\t{{.Digest}}'])
+    for (const line of rows) {
+      const [id, repo, tag, digest] = line.split('\t')
+      const reference = digest && digest !== '<none>' ? `${repo}@${digest}` : `${repo}:${tag}`
+      if (!seen.has(id)) seen.set(id, { id, reference })
+    }
+  }
+  return [...seen.values()]
+}
+
+// Removes every release image that Docker proves unused, and keeps the rest
+// with the reason. Unused means: `docker ps --all --filter ancestor=<id>`
+// lists no container, of this installation or any other, and Docker itself
+// accepts the removal without `--force`. An image Docker refuses (a container
+// created between the two calls, a dependent image) is kept and reported,
+// not a failure: images are shared host resources, and keeping one leaves
+// nothing of the installation behind. Returns `{ found, removed, kept }`
+// with `kept` as `[{ reference, reason }]`.
+export async function removeReleaseImages({ docker = dockerRunner, stdout } = {}) {
+  const found = await releaseImages({ docker })
+  const removed = []
+  const kept = []
+  for (const image of found) {
+    const users = (await run(docker, ['ps', '--all', '--no-trunc', '--filter', `ancestor=${image.id}`, '--format', '{{.ID}}\t{{.Names}}']))
+      .map((line) => line.split('\t')[1])
+    if (users.length > 0) {
+      const reason = `in use by ${describe(users, 'container')}`
+      stdout?.write(`kept the image ${image.reference}: ${reason}\n`)
+      kept.push({ reference: image.reference, reason })
+      continue
+    }
+    const result = await docker(['image', 'rm', image.id])
+    if (!result.ok) {
+      const reason = `docker refused: ${lastLines(result)}`
+      stdout?.write(`kept the image ${image.reference}: ${reason}\n`)
+      kept.push({ reference: image.reference, reason })
+      continue
+    }
+    stdout?.write(`removed the image ${image.reference}\n`)
+    removed.push(image)
+  }
+  return { found, removed, kept }
+}
+
+function describe(names, noun) {
+  return `${names.length} ${noun}${names.length === 1 ? '' : 's'}: ${names.join(', ')}`
+}
+
+// One `docker` invocation whose output is read line by line.
+async function run(docker, args) {
+  const result = await docker(args)
+  if (!result.ok) {
+    throw new DockerError(`docker ${args.join(' ')} failed:\n${lastLines(result)}`)
+  }
+  return String(result.stdout ?? '').split('\n').map((l) => l.trim()).filter((l) => l !== '')
+}
+
+function lastLines(result) {
+  return result.missing ? 'docker is not on the path' : (result.stderr || result.stdout || `exit ${result.code}`).trim().split('\n').slice(-5).join('\n')
+}

package/src/rollback.mjs

@@ -0,0 +1,131 @@
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { EXIT, Refusal } from './exit.mjs'
+import { dockerRunner } from './compose.mjs'
+import { operatorConfigPath } from './config.mjs'
+import { launcherPath } from './launcher.mjs'
+import { withLifecycleLock } from './lock.mjs'
+import { hostProbes, preflight } from './preflight.mjs'
+import { openRoot, versionPaths } from './root.mjs'
+import { IncompatibleRelease, isCompleteStage, validateWithRelease } from './stage.mjs'
+import { namedSteps } from './steps.mjs'
+import { switchRelease } from './switch.mjs'
+
+// `curia rollback` (#885, implementing #854): the switch of `curia update`
+// with the versions swapped, from the active release to the one rollback
+// release, as four named steps.
+//
+//   preflight  the root boundary (`openRoot`, which must find an
+//              installation) and the host preflight. Nothing changes.
+//   select     under the lifecycle lock from here to the end: the rollback
+//              release is the one complete release under versions/ that is
+//              not the active one. Curia keeps exactly one after a
+//              successful switch, so none means there was no update to roll
+//              back, and two means a failed update left its staged target
+//              beside the rollback release, and the operator says which one
+//              goes. Both are refusals; nothing is guessed.
+//   validate   the rollback release validates the current operator
+//              configuration with its own reader (`validateWithRelease`,
+//              the door `curia update` validates through). A configuration
+//              the rollback release refuses is the blocking incompatibility
+//              the contract names: the rollback is refused, exit `refused`,
+//              and the running release is not touched.
+//   switch     `switchRelease`, the same door as the update's `switch`
+//              step: the core services are recreated from the rollback
+//              release's bundle while tmux, ttyd, and the agent containers
+//              keep running, every service must be healthy, the service and
+//              the app must report the rollback release, and every live
+//              session must be adopted back; then the record names the
+//              rollback release and the release that was active is kept as
+//              the new rollback release. A failure switches back once to
+//              the release that was running and leaves the record alone.
+//
+// `config/`, `secrets/`, `state/`, and `work/` are never read for writing
+// here: the record is the one file the rollback changes, and the switch
+// changes it only after acceptance.
+
+export const ROLLBACK_STEPS = Object.freeze(['preflight', 'select', 'validate', 'switch'])
+
+// The command's seam. `context` is what `runCli` hands a command. `deps` are
+// the boundaries a test replaces: the host probes, the rollback release's
+// configuration validator, the Docker runner, the loopback `fetch`, and the
+// clock the waits use.
+export async function runRollback(
+  { env, args = [], stdout, uid, gid, root },
+  { hostProbes: host = hostProbes, validateTarget = validateWithRelease, docker = dockerRunner, fetch: fetchImpl = globalThis.fetch, sleep, now } = {},
+) {
+  const command = [launcherPath(env), 'rollback', ...args].join(' ')
+  const steps = namedSteps({ steps: ROLLBACK_STEPS, stdout, rerun: (step) => `Run '${command}' to run ${step} again; the completed steps are kept.` })
+  const say = (text) => stdout.write(`${text}\n`)
+
+  try {
+    // 1. preflight
+    steps.begin('preflight')
+    const opened = openRoot(root, { uid })
+    if (opened.status !== 'installed') {
+      throw new Refusal(`${root} holds no installation, so there is nothing to roll back. Run the bootstrap to install Curia there.`)
+    }
+    const record = opened.record
+    const active = record.activeVersion
+    const hostReport = await preflight({ uid, root, stdout }, host)
+    if (!hostReport.ok) throw hostReport.refusal
+    const dockerGid = hostReport.facts.docker.group.gid
+
+    return await withLifecycleLock(root, async () => {
+      // 2. select
+      steps.begin('select')
+      const { version: previous, candidates } = rollbackRelease(root, active)
+      if (previous === null) {
+        if (candidates.length === 0) {
+          throw new Refusal(`versions/ holds no release beside the active one, ${active}, so there is nothing to roll back to. Curia keeps the release you updated from after a successful 'curia update', and only that one.`)
+        }
+        throw new Refusal(`versions/ holds ${candidates.length === 2 ? 'two' : candidates.length} releases beside the active one, ${active}: ${candidates.join(' and ')}. One of them is the release you updated from and the other is the staged target of an update that did not switch. Finish the update with 'curia update', or remove the staged release you don't want from ${join(root, 'versions')}, then run 'curia rollback' again.`)
+      }
+      say(`rolling back from ${active} to ${previous}`)
+
+      // 3. validate
+      steps.begin('validate')
+      try {
+        await validateTarget({ root, version: previous, dir: versionPaths(root, previous).dir })
+      } catch (e) {
+        if (!(e instanceof IncompatibleRelease)) throw e
+        const action = e.reason === 'configuration'
+          ? `Fix the file so that both releases accept it, or stay on ${active}.`
+          : `${previous} is older than the operator configuration contract, so Curia cannot prove it reads this installation.`
+        throw new Refusal(`${e.message} ${action} The active version is unchanged.`)
+      }
+      say(`${previous} accepts the current operator configuration at ${operatorConfigPath(root)}`)
+
+      // 4. switch
+      steps.begin('switch')
+      await switchRelease(
+        { root, from: active, to: previous, record, environment: { uid, gid, dockerGid, installationId: record.installationId }, stdout },
+        { docker, fetch: fetchImpl, sleep, now },
+      )
+      say('')
+      say(`Curia ${previous} is running. Open the Curia app as before; nothing in integration setup has to be repeated.`)
+      say(`${active} is now the rollback release: 'curia rollback' switches forward to it, and 'curia update' replaces it.`)
+      return EXIT.ok
+    })
+  } catch (e) {
+    throw steps.wrap(e)
+  }
+}
+
+// The rollback release under `root`: the one complete release under
+// versions/ that is not `active`. Returns `{ version, candidates }`, with
+// `version` null when there is none or more than one. A dot directory is a
+// staging leftover and never a candidate; an incomplete directory is not one
+// either (the switch removes both).
+export function rollbackRelease(root, active, { complete = isCompleteStage } = {}) {
+  const candidates = readdirSync(join(root, 'versions'))
+    .filter((name) => !name.startsWith('.') && name !== active && complete(join(root, 'versions', name)))
+    .sort()
+  return { version: candidates.length === 1 ? candidates[0] : null, candidates }
+}
+
+// Used by the command table.
+export function rollbackCommand(context, deps) {
+  return runRollback(context, deps)
+}