@curia-sh/cli 0.4.1

package/src/uninstall.mjs

@@ -0,0 +1,190 @@
+import { existsSync, readFileSync, readdirSync, rmSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { BOOTSTRAP_COMMAND } from './acquire.mjs'
+import { EXIT, Refusal } from './exit.mjs'
+import { dockerRunner } from './compose.mjs'
+import { launcherPath } from './launcher.mjs'
+import { lockPath, withLifecycleLock } from './lock.mjs'
+import { removeInstallationResources } from './resources.mjs'
+import { installationRoot, openRoot } from './root.mjs'
+import { readSecret } from './secrets.mjs'
+import { namedSteps } from './steps.mjs'
+import { tailscaleRunner, withdrawServeRoutes } from './tailscale.mjs'
+
+// `curia uninstall` (#886, implementing #855): the ordinary uninstall. It
+// removes Curia's runnable footprint from the host and keeps the
+// installation, as four named steps.
+//
+//   preflight  the root boundary (`openRoot`, which must find an
+//              installation). Nothing changes.
+//   docker     under the lifecycle lock from here to the end: every
+//              container, network, and volume that carries this
+//              installation's label is stopped and removed. That is the
+//              five services of the Compose project, its network and tmux
+//              socket volume, and every agent container and agent cache
+//              volume the service created. Nothing without the label is
+//              read or touched, and the release images stay for purge.
+//   routes     the Tailscale Serve routes Curia created, as
+//              `state/tailscale.json` records them, are turned off. No
+//              other route, and nothing else of the node.
+//   files      the contents of versions/, cache/, and run/ are removed, and
+//              then the launcher, when it is this installation's.
+//
+// What stays is the installation: `config/`, `secrets/`, `state/`, and
+// `work/`, with the installation record and its ID. Nothing here reads a
+// session, drains one, changes a claim, or judges what under `work/` is
+// worth keeping: the preserved directories are the recovery mechanism, and
+// the bootstrap's `curia install` over the root is the reinstall.
+//
+// Every step reads what is there before it removes it, so a rerun over a
+// partial cleanup does the rest and a rerun over a finished one does
+// nothing. There is no persisted operation record and no repair mode. A
+// failed step names itself and the command that reruns it.
+
+export const UNINSTALL_STEPS = Object.freeze(['preflight', 'docker', 'routes', 'files'])
+
+// The directories whose contents go, in the order they are removed. The
+// directories themselves stay, so the root keeps its seven boundaries and the
+// lock has a place to live on a rerun.
+export const REMOVED_BOUNDARIES = Object.freeze(['versions', 'cache', 'run'])
+export const PRESERVED_BOUNDARIES = Object.freeze(['config', 'secrets', 'state', 'work'])
+
+// The command's seam. `context` is what `runCli` hands a command. `deps` are
+// the boundaries a test replaces: the Docker runner and the `tailscale`
+// runner.
+export async function runUninstall(
+  { env, stdout, uid, root },
+  { docker = dockerRunner, tailscale = tailscaleRunner } = {},
+) {
+  const launcher = launcherPath(env)
+  const steps = namedSteps({
+    steps: UNINSTALL_STEPS,
+    stdout,
+    rerun: (step) => (existsSync(launcher)
+      ? `Run '${launcher} uninstall' to run ${step} again; the completed steps are kept.`
+      : `Fix the cause, then run 'curia uninstall' again from the bootstrap's reinstall (${reinstallCommand({ env, root })}), or remove the rest by hand: ${REMOVED_BOUNDARIES.map((b) => join(root, b)).join(', ')}.`),
+  })
+  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 uninstall. Nothing changed.`)
+    }
+    const { installationId, activeVersion } = opened.record
+    say(`uninstalling Curia ${activeVersion} from ${root} (installation ${installationId}); config/, secrets/, state/, and work/ are kept`)
+
+    return await withLifecycleLock(root, async () => {
+      // 2. 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}; the release images are kept for 'curia purge'`)
+
+      // 3. 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) say(`no recorded Serve route is standing; nothing to withdraw`)
+
+      // 4. files
+      steps.begin('files')
+      const lock = lockPath(root)
+      for (const name of REMOVED_BOUNDARIES) {
+        const dir = join(root, name)
+        if (!existsSync(dir)) continue
+        for (const entry of readdirSync(dir)) {
+          const file = join(dir, entry)
+          if (file === lock) continue
+          rmSync(file, { recursive: true, force: true })
+        }
+        say(`emptied ${dir}`)
+      }
+      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}`)
+
+      say('')
+      say(`Curia is uninstalled. The installation at ${root} is preserved.`)
+      say(`  kept:      ${PRESERVED_BOUNDARIES.map((b) => `${b}/`).join(', ')} (installation ${installationId}: configuration, secrets, history, and resumable work)`)
+      say(`  removed:   the launcher, ${REMOVED_BOUNDARIES.map((b) => `${b}/`).join(', ')}, and the installation's containers, networks, volumes, and Serve routes`)
+      say(`  images:    kept; 'curia purge' removes them`)
+      say(`  reinstall: ${reinstallCommand({ env, root })}`)
+      say(`  purge:     ${purgeCommand({ env, root })}`)
+      const external = externalChecklist(root, { uid })
+      if (external.length > 0) {
+        say('')
+        say("External resources Curia never deletes. Remove them yourself if you won't reinstall:")
+        for (const line of external) say(`  ${line}`)
+      }
+      return EXIT.ok
+    })
+  } catch (e) {
+    throw steps.wrap(e)
+  }
+}
+
+// The bootstrap installs over a preserved root and recognizes the record, so
+// the reinstall command is the install command, with the root named when it
+// is not the default one.
+export function reinstallCommand({ env, root }) {
+  return `${BOOTSTRAP_COMMAND}${rootOption({ env, root })}`
+}
+
+export function purgeCommand({ env, root }) {
+  return `${BOOTSTRAP_COMMAND} --purge${rootOption({ env, root })}`
+}
+
+function rootOption({ env, root }) {
+  const byDefault = installationRoot({ HOME: env.HOME, XDG_DATA_HOME: env.XDG_DATA_HOME })
+  return root === byDefault ? '' : ` --root ${root}`
+}
+
+// Removes the launcher when it names this root. A launcher of another root
+// is another installation's and stays.
+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'
+}
+
+// The external resources Curia knows the identifiers of, from the files it
+// keeps. Identifiers only, never a token or a key, and a file that cannot be
+// read contributes nothing: the checklist is a courtesy, not a check.
+export function externalChecklist(root, { uid }) {
+  const lines = []
+  const github = parse(() => readSecret(root, 'github-app.json', { uid }))
+  if (github?.id) lines.push(`GitHub App ${github.id} and its installations: https://github.com/settings/apps`)
+  const discord = parse(() => readFileSync(join(root, 'state', 'discord.json'), 'utf8'))
+  if (discord?.guild_id) lines.push(`Discord bot, server ${discord.guild_id}${discord.channel ? `, channel ${discord.channel}` : ''}: https://discord.com/developers/applications`)
+  const tailscale = parse(() => readFileSync(join(root, 'state', 'tailscale.json'), 'utf8'))
+  if (tailscale?.machine_name) lines.push(`Tailscale node ${tailscale.machine_name}: https://login.tailscale.com/admin/machines`)
+  return lines
+}
+
+function parse(read) {
+  try {
+    const text = read()
+    return text ? JSON.parse(text) : null
+  } catch {
+    return null
+  }
+}
+
+// Used by the command table.
+export function uninstallCommand(context, deps) {
+  return runUninstall(context, deps)
+}

package/src/update.mjs

@@ -0,0 +1,174 @@
+import { mkdirSync, readFileSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { EXIT, Refusal, UsageError } from './exit.mjs'
+import { acquireProbes, acquireRelease } from './acquire.mjs'
+import { operatorConfigPath } from './config.mjs'
+import { launcherPath } from './launcher.mjs'
+import { withLifecycleLock } from './lock.mjs'
+import { releaseProbes } from './manifest.mjs'
+import { hostProbes, preflight } from './preflight.mjs'
+import { openRoot, versionPaths } from './root.mjs'
+import { StableIndexError, fetchStableIndex, pinnedPublicKey, releaseNotesUrl, renderSelection, selectRelease, selectionFromArgs, stableProbes } from './stable.mjs'
+import { IncompatibleRelease, isCompleteStage, placeVersion, validateWithRelease, verifyRetained } from './stage.mjs'
+import { namedSteps } from './steps.mjs'
+import { switchRelease } from './switch.mjs'
+import { dockerRunner } from './compose.mjs'
+
+// `curia update` (#883, implementing #854): from the signed stable-release
+// index to a verified, validated target release staged beside the active
+// one, as one linear sequence of named steps.
+//
+//   preflight  the root boundary (`openRoot`, which must find an installation)
+//              and the host preflight. Nothing on disk changes.
+//   select     the stable-release index is downloaded and proven against the
+//              pinned key, and one version is selected from it: the stable
+//              release by default, an exact version when asked, an exact
+//              prerelease only with `--prerelease`. A withdrawn version is
+//              never selected. When the selected version is the active one,
+//              there is nothing to do and the command stops here, ok.
+//   acquire    under the lifecycle lock from here to the end: every artifact
+//              of the target (package, pinned runtime, bundle, checksum,
+//              manifest) is downloaded into cache/update/ and proven, the
+//              bootstrap's own steps in this package's code (acquire.mjs). A
+//              target already complete under versions/<target>/ is verified
+//              and reused instead, so a rerun downloads nothing.
+//   stage      the target passes the release door (`verifyStagedRelease`)
+//              and lands read-only as versions/<target>/ through one rename,
+//              beside the active version, which does not change.
+//   validate   the target release validates the current operator
+//              configuration with its own reader (`readOperatorConfig` of
+//              the staged package), so a configuration the target refuses
+//              stops the update before anything switches.
+//   switch     the core services (service, app, overseer) are recreated
+//              from the target's bundle while tmux, ttyd, and the live agent
+//              containers keep running; every service reports healthy, the
+//              service and the app report the target version, and the live
+//              sessions are re-adopted; then the record names the target
+//              and the release that was active is kept as the one rollback
+//              release, every other version removed. A failure switches
+//              the core services back once and leaves the record alone.
+//              The sequence is `switchRelease` in switch.mjs, which `curia
+//              rollback` shares.
+//
+// Discovery is the same `fetchStableIndex` and `selectRelease` the service's
+// daily check and the Curia app use. A failed discovery refuses before the
+// lock, so it never touches the running installation. The command never
+// rewrites the launcher: it reads the record, and the record is what the
+// switch writes.
+
+export const UPDATE_STEPS = Object.freeze(['preflight', 'select', 'acquire', 'stage', 'validate', 'switch'])
+
+const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+
+// The command's seam. `context` is what `runCli` hands a command. `deps` are
+// the boundaries a test replaces: the host probes, the stable-index probe
+// and the pinned key, the acquisition probes, the release probes, the
+// target's configuration validator, the Docker runner, the loopback `fetch`,
+// and the clock the waits use.
+export async function runUpdate(
+  { env, args = [], stdout, uid, gid, root },
+  { hostProbes: host = hostProbes, stableProbes: stable = stableProbes, publicKey = pinnedPublicKey(), acquireProbes: acquire = acquireProbes, releaseProbes: release = releaseProbes, validateTarget = validateWithRelease, docker = dockerRunner, fetch: fetchImpl = globalThis.fetch, sleep, now } = {},
+) {
+  let selection
+  try {
+    selection = selectionFromArgs(args)
+  } catch (e) {
+    if (e instanceof StableIndexError) throw new UsageError(e.message)
+    throw e
+  }
+  const command = [launcherPath(env), 'update', ...args].join(' ')
+  const steps = namedSteps({ steps: UPDATE_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 update. 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
+
+    // 2. select
+    steps.begin('select')
+    const fetched = await fetchStableIndex({ stdout, publicKey }, stable)
+    if (!fetched.ok) throw new Refusal(`${fetched.error} The running installation is not affected.`)
+    const { index } = fetched
+    if (index.withdrawn.includes(active)) {
+      say(`warning: the active version ${active} is withdrawn. The release notes at ${releaseNotesUrl(active)} say why.`)
+    }
+    const { version: target, selection: how } = selectRelease(index, selection)
+    stdout.write(renderSelection({ version: target, selection: how }))
+    if (target === active) {
+      say(`${active} is the active version. Nothing to update.`)
+      return EXIT.ok
+    }
+    say(`updating ${active} to ${target} (release notes: ${releaseNotesUrl(target)})`)
+
+    return await withLifecycleLock(root, async () => {
+      // 3. acquire
+      steps.begin('acquire')
+      const paths = versionPaths(root, target)
+      let stage = null
+      if (isCompleteStage(paths.dir)) {
+        say(`${target} is already staged under ${paths.dir}; verifying the retained artifacts`)
+        await verifyRetained({ version: target, dir: paths.dir, stdout }, release)
+      } else {
+        stage = join(root, 'cache', 'update', `${target}.${process.pid}`)
+        rmSync(stage, { recursive: true, force: true })
+        mkdirSync(stage, { recursive: true, mode: 0o700 })
+        try {
+          await acquireRelease({ version: target, stage, stdout }, acquire)
+        } catch (e) {
+          rmSync(stage, { recursive: true, force: true })
+          throw e
+        }
+      }
+
+      // 4. stage
+      steps.begin('stage')
+      if (stage) {
+        try {
+          await placeVersion({ root, version: target, stage, stdout }, release)
+        } finally {
+          rmSync(stage, { recursive: true, force: true })
+        }
+      } else {
+        say(`${target} is staged under ${paths.dir}`)
+      }
+
+      // 5. validate
+      steps.begin('validate')
+      try {
+        await validateTarget({ root, version: target, dir: paths.dir })
+      } catch (e) {
+        if (!(e instanceof IncompatibleRelease)) throw e
+        throw new Error(e.reason === 'configuration' ? `${e.message} Fix the file, or choose another version. The active version is unchanged.` : `${e.message} Choose a version that does.`)
+      }
+      say(`${target} accepts the current operator configuration at ${operatorConfigPath(root)}`)
+
+      // 6. switch
+      steps.begin('switch')
+      await switchRelease(
+        { root, from: active, to: target, record, environment: { uid, gid, dockerGid, installationId: record.installationId }, stdout },
+        { docker, fetch: fetchImpl, sleep, now },
+      )
+      say('')
+      say(`Curia ${target} is running. Open the Curia app as before; nothing in integration setup has to be repeated.`)
+      say(`If ${target} misbehaves, 'curia rollback' switches back to ${active}.`)
+      return EXIT.ok
+    })
+  } catch (e) {
+    throw steps.wrap(e)
+  }
+}
+
+// Used by the command table.
+export function updateCommand(context, deps) {
+  return runUpdate(context, deps)
+}

package/stable-index.pub

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAxCKSmZVadSpZM0t24JceAmtafXwAOgRV0eNbwkyOzrY=
+-----END PUBLIC KEY-----