@curia-sh/cli 0.4.1

package/src/exit.mjs

@@ -0,0 +1,32 @@
+// The four exit codes every lifecycle command and the launcher use.
+//
+//   ok       the command did what it said.
+//   failed   the command started the operation and the operation failed.
+//            The installation may have changed. The message says what to do next.
+//   usage    the command line was wrong. Nothing ran.
+//   refused  Curia refused to start the operation. Nothing changed. The message
+//            names the condition and one corrective action.
+//
+// A script can branch on these numbers. The launcher exits `refused` when the
+// active version is incomplete, so the same code means the same thing whether
+// the refusal came from the shell script or from the lifecycle interface.
+export const EXIT = Object.freeze({ ok: 0, failed: 1, usage: 2, refused: 3 })
+
+// A refusal a command raises before it changes anything. `runCli` turns it into
+// `EXIT.refused` and prints the message on stderr, so a command states the
+// condition once and never touches the exit code itself.
+export class Refusal extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'Refusal'
+  }
+}
+
+// A command line the command cannot act on. `runCli` turns it into
+// `EXIT.usage` and points at `curia help`; nothing ran.
+export class UsageError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'UsageError'
+  }
+}

package/src/install.mjs

@@ -0,0 +1,194 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+import { EXIT, Refusal } from './exit.mjs'
+import { BOOTSTRAP_COMMAND } from './acquire.mjs'
+import { writeAtomically } from './atomic.mjs'
+import { composeProject, dockerRunner, startProject, waitForHealth, writeComposeEnvironment } from './compose.mjs'
+import { initialOperatorConfig, operatorConfigPath, writeOperatorConfig } from './config.mjs'
+import { launcherPath, renderLauncher } from './launcher.mjs'
+import { serviceLayout } from './layout.mjs'
+import { withLifecycleLock } from './lock.mjs'
+import { releaseProbes } from './manifest.mjs'
+import { hostProbes, preflight } from './preflight.mjs'
+import { createInstallationRecord, ensureLayout, openRoot, versionPaths, writeInstallationRecord } from './root.mjs'
+import { isCompleteStage, placeVersion, stagedVersion, verifyRetained } from './stage.mjs'
+
+// `curia install` and `curia reinstall` (#873, implementing #851, #854, #857,
+// and #862): from a verified stage to a healthy packaged Curia and a reachable
+// app, as one linear sequence of six named steps.
+//
+//   preflight  the root boundary (`openRoot`) and the host preflight. Nothing
+//              on disk changes. A refusal here creates no root.
+//   root       the root and its seven boundaries exist, the lifecycle lock is
+//              held from here to the end, the installation record names the
+//              version, and a fresh root gets the initial operator
+//              configuration. A recognized root keeps its installation ID,
+//              config/, secrets/, state/, and work/: that is a reinstall.
+//   stage      the staged artifacts are verified against the release manifest
+//              and land under versions/<version>/ as one complete version,
+//              read-only, replacing that directory if it was there.
+//   activate   the record names the version and the launcher is written.
+//              Any other directory under versions/ is removed, so one release
+//              is installed.
+//   start      the Compose environment and the mount sources exist, the
+//              images are pulled by digest, and the project is up.
+//   health     every declared service reports healthy.
+//
+// Every step is idempotent by inspection, not by a persisted operation record:
+// a rerun repeats the cheap steps, finds the expensive ones done, and so lands
+// at the step that failed. A failure names the current step and the command
+// that reruns it. There is no operation engine, no repair mode, and no retry
+// loop beyond the health wait.
+//
+// The stage comes from the bootstrap as CURIA_STAGE, holding `node/`, `cli/`,
+// `cli.tgz`, `bundle.tar.gz`, and `bundle.tar.gz.sha256`. The bootstrap removes
+// it when this command returns, so the stage is copied, never moved. Without
+// CURIA_STAGE, which is how the installed launcher reruns the command, the
+// version already under versions/<version>/ is verified and reused.
+//
+// The version installed is always this interface's own version: the bootstrap
+// runs the staged package, and the launcher runs the installed one. Installing
+// another version is `curia update` (#883), which stages through the same
+// `placeVersion` in stage.mjs.
+
+export const INSTALL_STEPS = Object.freeze(['preflight', 'root', 'stage', 'activate', 'start', 'health'])
+
+// The Tailscale Serve port of the Curia app, `dashboard.serve_port` in
+// config/curia.yaml. daemon/test/preflightports.test.mjs keeps them equal.
+export const APP_SERVE_PORT = 8445
+
+export 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 plus `gid`
+// and `mode` (`install` or `reinstall`). `deps` are the boundaries a test
+// replaces: the host probes, the release probes, the Docker runner, and the
+// clock the health wait uses.
+export async function runInstall(
+  { env, stdout, uid, gid, root, mode = 'install' },
+  { hostProbes: host = hostProbes, releaseProbes: release = releaseProbes, docker = dockerRunner, sleep, now } = {},
+) {
+  const version = packageVersion
+  const launcher = launcherPath(env)
+  const steps = sequence({ stdout, launcher, mode })
+  const say = (text) => stdout.write(`${text}\n`)
+
+  try {
+    // 1. preflight
+    steps.begin('preflight')
+    const opened = openRoot(root, { uid })
+    const hostReport = await preflight({ uid, root, stdout }, host)
+    if (!hostReport.ok) throw hostReport.refusal
+    const dockerGid = hostReport.facts.docker.group.gid
+    const appHost = hostReport.facts.tailscale.certDomains[0]
+
+    // 2. root
+    steps.begin('root')
+    if (mode === 'reinstall' && opened.status !== 'installed') {
+      throw new Refusal(`${root} holds no installation, so there is nothing to reinstall. Run the bootstrap to install Curia there.`)
+    }
+    const reinstalling = opened.status === 'installed'
+    say(reinstalling ? `reinstalling ${version} over the installation at ${root} (installation ${opened.record.installationId})` : `creating the installation root at ${root}`)
+    ensureLayout(root, { uid })
+
+    return await withLifecycleLock(root, async () => {
+      const record = opened.record ?? createInstallationRecord(version)
+      if (!opened.record) writeInstallationRecord(root, record)
+      const configPath = operatorConfigPath(root)
+      if (!existsSync(configPath)) {
+        writeOperatorConfig(configPath, initialOperatorConfig())
+        say(`wrote the initial operator configuration to ${configPath}`)
+      } else {
+        say(`keeping ${configPath}`)
+      }
+
+      // 3. stage
+      steps.begin('stage')
+      const paths = versionPaths(root, version)
+      const stage = env.CURIA_STAGE
+      if (stage) {
+        if (!isCompleteStage(stage)) {
+          throw new Refusal(`the stage ${stage} is incomplete. Run the bootstrap again; it downloads a complete stage.`)
+        }
+        const staged = stagedVersion(stage)
+        if (staged !== version) {
+          throw new Refusal(`the stage holds @curia-sh/cli ${staged}, but this lifecycle interface is ${version}, and an installation is always its own version. Run the bootstrap again so it installs one version end to end.`)
+        }
+        await placeVersion({ root, version, stage, stdout }, release)
+      } else if (isCompleteStage(paths.dir)) {
+        say(`${version} is already installed under ${paths.dir}; verifying the retained artifacts`)
+        await verifyRetained({ version, dir: paths.dir, stdout }, release)
+      } else {
+        throw new Refusal(`no release to install: CURIA_STAGE is not set and ${paths.dir} holds no complete version. Run the bootstrap: ${BOOTSTRAP_COMMAND}`)
+      }
+
+      // 4. activate
+      steps.begin('activate')
+      writeInstallationRecord(root, { ...record, activeVersion: version })
+      mkdirSync(dirname(launcher), { recursive: true })
+      writeAtomically(launcher, renderLauncher({ root }), { mode: 0o755 })
+      for (const other of readdirSync(join(root, 'versions'))) {
+        if (other !== version) rmSync(join(root, 'versions', other), { recursive: true, force: true })
+      }
+      say(`${version} is the active version; the launcher is ${launcher}`)
+
+      // 5. start
+      steps.begin('start')
+      const project = composeProject({ root, version })
+      writeComposeEnvironment(project, { uid, gid, dockerGid, installationId: record.installationId })
+      const layout = serviceLayout(root)
+      for (const dir of [layout.home, layout.overseerRepos, layout.overseerTokens, layout.overseerConfigDir]) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 })
+        chmodSync(dir, 0o700)
+      }
+      await startProject(project, { docker, stdout })
+
+      // 6. health
+      steps.begin('health')
+      await waitForHealth(project, { docker, sleep, now, stdout })
+
+      const app = `https://${appHost}:${APP_SERVE_PORT}/`
+      say('')
+      say(`Curia ${version} is installed and running.`)
+      say(`  installation root: ${root}`)
+      say(`  launcher:          ${launcher}`)
+      say(`  Curia app:         ${app}`)
+      say('')
+      say(`Next: open the Curia app at ${app} from a device on your tailnet and start integration setup. It connects GitHub, Discord, Tailscale, and one model provider, then runs the Full loop.`)
+      return EXIT.ok
+    })
+  } catch (e) {
+    throw steps.wrap(e)
+  }
+}
+
+// The step sequence: prints each header, remembers the current step, and
+// turns an error into one that names the step and the command that reruns
+// it. Before the launcher exists the rerun is the bootstrap.
+function sequence({ stdout, launcher, mode }) {
+  let current = null
+  let index = 0
+  return {
+    begin(name) {
+      current = name
+      index = INSTALL_STEPS.indexOf(name) + 1
+      stdout.write(`[${index}/${INSTALL_STEPS.length}] ${name}\n`)
+    },
+    wrap(e) {
+      if (current === null) return e
+      if (e instanceof Refusal) return new Refusal(`${current}: ${e.message}`)
+      const rerun = existsSync(launcher)
+        ? `Run '${launcher} ${mode}' to run ${current} again; the completed steps are kept.`
+        : `Fix the cause and run the bootstrap again; it resumes at ${current}.`
+      const wrapped = new Error(`${current} failed: ${e.message}\n${rerun}`)
+      wrapped.cause = e
+      return wrapped
+    },
+  }
+}
+
+// Used by the command table: the two commands are one sequence with one
+// difference, whether a root that holds no installation is acceptable.
+export function installCommand(mode) {
+  return (context, deps) => runInstall({ ...context, mode }, deps)
+}

package/src/launcher.mjs

@@ -0,0 +1,53 @@
+import { join } from 'node:path'
+
+// The stable host launcher: `~/.local/bin/curia`.
+//
+// The bootstrap writes it once per installation and no update rewrites it. It
+// is one POSIX shell script with the installation root written into it, so a
+// nondefault root stays explicit without the operator typing it. On every run
+// it reads `state/installation.json`, picks the version the record names, and
+// execs that version's pinned Node runtime on that version's entry point with
+// CURIA_ROOT exported. It carries no other logic: the lifecycle interface under
+// the active version owns everything else, which is what lets an update change
+// the interface without touching the launcher.
+//
+// It exits `refused` (3) when the record is missing or the active version is
+// incomplete, and says which file is missing. That is the launcher's one
+// refusal, and it matches the lifecycle interface's own refused code.
+
+export function launcherPath(env) {
+  return join(env.HOME ?? '', '.local', 'bin', 'curia')
+}
+
+export function renderLauncher({ root }) {
+  if (root.includes("'")) throw new Error(`the installation root must not contain a single quote: ${root}`)
+  return `#!/bin/sh
+# Curia launcher. Written by the Curia bootstrap; an update never rewrites it.
+# It runs the lifecycle interface of the active installed version.
+CURIA_ROOT='${root}'
+export CURIA_ROOT
+
+record="$CURIA_ROOT/state/installation.json"
+if [ ! -r "$record" ]; then
+  echo "curia: no installation record at $record. Run the bootstrap again to reinstall, or delete the launcher if Curia was purged." >&2
+  exit 3
+fi
+
+version=$(sed -n 's/^[[:space:]]*"activeVersion"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*$/\\1/p' "$record" | head -n 1)
+if [ -z "$version" ]; then
+  echo "curia: $record names no active version. Run the bootstrap again to reinstall." >&2
+  exit 3
+fi
+
+node="$CURIA_ROOT/versions/$version/node/bin/node"
+entry="$CURIA_ROOT/versions/$version/cli/bin/curia.mjs"
+for required in "$node" "$entry"; do
+  if [ ! -f "$required" ]; then
+    echo "curia: the active version $version is incomplete: $required is missing. Run the bootstrap again to reinstall the active version." >&2
+    exit 3
+  fi
+done
+
+exec "$node" "$entry" "$@"
+`
+}

package/src/layout.mjs

@@ -0,0 +1,95 @@
+import { isAbsolute, join } from 'node:path'
+
+// Where the service data of an installation lives, inside the seven boundaries
+// of the installation root (#867, implementing #851).
+//
+// One function answers the question for every process: the lifecycle interface
+// that writes the Compose project, the daemon that writes the paths, the
+// overseer that reads them, and the tests that inspect the Compose bundle. Each
+// path sits in the boundary whose lifecycle class it has, so the survival
+// contract of the root (`config/`, `secrets/`, `state/`, and `work/` preserved;
+// `versions/`, `cache/`, and `run/` replaceable) applies to it with no extra
+// rule.
+//
+//   state/                    the journal, attachments, results, backups, the
+//                             preview registry, and the daemon's own token stores
+//   work/                     worktrees, review checkouts, and the per-session
+//                             config directories, which the daemon calls its
+//                             workspace root
+//   work/cfg/curia-overseer   the overseer's config directory and native sessions
+//   cache/home                HOME in every service container: tool caches and
+//                             nothing Curia has to keep
+//   cache/overseer-repos      the overseer's mirrors of origin
+//   run/overseer-tokens       the overseer's renewable installation tokens, one
+//                             file per owner, rewritten by the daemon
+//
+// The secret files themselves are the catalogue in `secrets.mjs`.
+export function serviceLayout(root) {
+  if (typeof root !== 'string' || !isAbsolute(root)) {
+    throw new Error(`the installation root must be an absolute path, got ${root}`)
+  }
+  const at = (...parts) => join(root, ...parts)
+  return Object.freeze({
+    root,
+    config: at('config'),
+    secrets: at('secrets'),
+    state: at('state'),
+    work: at('work'),
+    cache: at('cache'),
+    run: at('run'),
+    versions: at('versions'),
+    overseerConfigDir: at('work', 'cfg', 'curia-overseer'),
+    home: at('cache', 'home'),
+    overseerRepos: at('cache', 'overseer-repos'),
+    overseerTokens: at('run', 'overseer-tokens'),
+  })
+}
+
+// The five long-running services of an installation, in Compose order.
+export const SERVICES = Object.freeze(['daemon', 'tmux', 'ttyd', 'dashboard', 'overseer'])
+
+// What each container may see of the installation root, as layout paths and
+// modes. This is the container-access contract of #851, and the Compose bundle
+// is inspected against it:
+//
+//   - the service reads `config/` and writes its `config.yaml` for the app's
+//     settings screen, owns every secret file, writes the narrow state,
+//     work, cache, and runtime paths it uses, and reads `versions/` so its
+//     daily update check (#883) verifies the stable-release index with the
+//     key the active version's package carries;
+//   - the tmux runtime holds the panes that run `docker run` against host
+//     paths, so it sees the work tree and the shared home and nothing else;
+//   - the attach surface sees nothing of the root, only the tmux socket;
+//   - the app sees nothing of the root and reaches configuration through the
+//     service;
+//   - the overseer sees its own config directory, its mirrors, and its
+//     renewable tokens read-only. Its model credential reaches it as a copy in
+//     its config directory, written by the service, so no secret file is
+//     mounted into the container that holds a shell.
+export const SERVICE_MOUNTS = Object.freeze({
+  daemon: Object.freeze([
+    Object.freeze({ path: 'config', mode: 'rw' }),
+    Object.freeze({ path: 'secrets', mode: 'rw' }),
+    Object.freeze({ path: 'state', mode: 'rw' }),
+    Object.freeze({ path: 'work', mode: 'rw' }),
+    Object.freeze({ path: 'cache', mode: 'rw' }),
+    Object.freeze({ path: 'run', mode: 'rw' }),
+    Object.freeze({ path: 'versions', mode: 'ro' }),
+  ]),
+  tmux: Object.freeze([
+    Object.freeze({ path: 'work', mode: 'rw' }),
+    Object.freeze({ path: 'home', mode: 'rw' }),
+  ]),
+  ttyd: Object.freeze([]),
+  dashboard: Object.freeze([]),
+  overseer: Object.freeze([
+    Object.freeze({ path: 'overseerConfigDir', mode: 'rw' }),
+    Object.freeze({ path: 'overseerRepos', mode: 'rw' }),
+    Object.freeze({ path: 'overseerTokens', mode: 'ro' }),
+  ]),
+})
+
+// The containers that may reach the Docker socket: the service, which runs
+// agent containers as siblings, and the tmux runtime, whose panes run
+// `docker run`. The app, the attach surface, and the overseer never do.
+export const DOCKER_SOCKET_SERVICES = Object.freeze(['daemon', 'tmux'])

package/src/lock.mjs

@@ -0,0 +1,74 @@
+import { closeSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { Refusal } from './exit.mjs'
+
+// The lifecycle-operation lock: `run/lifecycle.lock` inside the installation
+// root. One lifecycle operation runs at a time per installation. The lock file
+// is created exclusively and holds the owning process id, so a second `curia`
+// invocation refuses with that id instead of racing an install, update, or
+// uninstall that is half done.
+//
+// `run/` is restart-disposable, and a crash can leave the file behind. A lock
+// whose process no longer exists is taken over: the stale file is moved aside
+// first, so two takers cannot both unlink a fresh lock a third process just
+// created, and the exclusive create decides who wins.
+export function lockPath(root) {
+  return join(root, 'run', 'lifecycle.lock')
+}
+
+export async function withLifecycleLock(root, operation) {
+  const path = lockPath(root)
+  acquire(path)
+  try {
+    return await operation()
+  } finally {
+    try { unlinkSync(path) } catch {}
+  }
+}
+
+function acquire(path) {
+  for (let attempt = 0; attempt < 2; attempt++) {
+    let fd
+    try {
+      fd = openSync(path, 'wx', 0o600)
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e
+      const holder = holderOf(path)
+      if (holder !== null) {
+        throw new Refusal(`another lifecycle operation is running: process ${holder} holds ${path}. Wait for it to finish, then run the command again.`)
+      }
+      // Stale: no live process owns it. Move it aside, then try the create again.
+      try { renameSync(path, `${path}.stale.${process.pid}`) } catch {}
+      try { unlinkSync(`${path}.stale.${process.pid}`) } catch {}
+      continue
+    }
+    try {
+      writeSync(fd, `${process.pid}\n`)
+    } finally {
+      closeSync(fd)
+    }
+    return
+  }
+  throw new Refusal(`another lifecycle operation is running and holds ${path}. Wait for it to finish, then run the command again.`)
+}
+
+// The live process named in the lock file, or null when the file names none.
+function holderOf(path) {
+  let text
+  try {
+    text = readFileSync(path, 'utf8')
+  } catch (e) {
+    if (e.code === 'ENOENT') return null
+    throw e
+  }
+  const pid = Number.parseInt(text, 10)
+  if (!Number.isInteger(pid) || pid <= 0) return null
+  try {
+    process.kill(pid, 0)
+    return pid
+  } catch (e) {
+    // EPERM means the process exists and belongs to someone else: it's alive.
+    return e.code === 'EPERM' ? pid : null
+  }
+}