quoxcli 0.0.0-stage → 0.3.1

package/lib/server/skew.js

@@ -0,0 +1,56 @@
+/**
+ * C4: version skew between this CLI and the server it talks to. Warns at most once per day, and only when
+ * major or minor differ (a patch difference does not matter). Silent whenever either side is unknown.
+ *
+ * CLI side: the platform release the CLI was built from (the repo VERSION file beside cli/).
+ * Server side: the collector's public /version `release` (the image's /app/VERSION).
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSemver, cmpSemver } from './install.js';
+
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const DAY_MS = 86400000;
+
+export function cliRelease(root = CLI_ROOT) {
+  try { const v = readFileSync(join(root, '..', 'VERSION'), 'utf8').trim(); return parseSemver(v) ? v : null; } catch { return null; }
+}
+
+export function skewCachePath(env = process.env) {
+  return join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'quox', 'version-skew.json');
+}
+
+/** -> null | { cli, server, newer: 'cli'|'server', message } */
+export function skewOf(cli, server) {
+  const a = parseSemver(cli); const b = parseSemver(server);
+  if (!a || !b) return null;
+  if (a[0] === b[0] && a[1] === b[1]) return null;
+  const newer = cmpSemver(cli, server) > 0 ? 'cli' : 'server';
+  const message = newer === 'cli'
+    ? `this quox CLI is ${cli} but the server runs ${server}. Update the server: quox server update (on the server; quox server update --dry-run shows the plan first).`
+    : `this quox CLI is ${cli} but the server runs ${server}. Update the CLI to ${server} so its commands match the server.`;
+  return { cli, server, newer, message };
+}
+
+/**
+ * Once per day: read the server release, compare, return the warning (or null). Never throws.
+ * The cache is stamped BEFORE the network call, so a slow or failing server costs one try per day.
+ */
+export async function checkSkewOncePerDay({ collectorUrl, fetchImpl = globalThis.fetch, now = () => Date.now(), cachePath = skewCachePath(), cli = cliRelease(), timeoutMs = 1500 } = {}) {
+  try {
+    if (!cli || !collectorUrl) return null;
+    let cache = {};
+    try { cache = JSON.parse(readFileSync(cachePath, 'utf8')) || {}; } catch { /* first run */ }
+    if (cache.checkedAt && now() - cache.checkedAt < DAY_MS) return null;
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify({ ...cache, checkedAt: now() }) + '\n');
+    const r = await fetchImpl(`${collectorUrl.replace(/\/+$/, '')}/version`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!r.ok) return null;
+    const body = await r.json();
+    const sk = skewOf(cli, body?.release);
+    if (sk) writeFileSync(cachePath, JSON.stringify({ checkedAt: now(), warnedAt: now(), cli, server: body.release }) + '\n');
+    return sk;
+  } catch { return null; }
+}

package/lib/server/snapshot.js

@@ -0,0 +1,131 @@
+/**
+ * C4: snapshots = DB + config, taken before every update, restored by rollback.
+ *
+ * <backups>/<stamp>-<release>-<commit>/
+ *   manifest.json     written LAST with complete:true; a dir without it is not a snapshot
+ *   postgres.sql      pg_dumpall from the running postgres service
+ *   volumes/<v>.tgz   every other compose volume (the SQLite stores), tarred with the stack stopped
+ *   config/.env, config/ssl/, config/docker-compose.override.yml (mode 0600 / as found)
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, cpSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { readEnvKeys } from './install.js';
+import { compose } from './status.js';
+
+export const HELPER_IMAGE = 'alpine:3.20';
+const CONFIG_ITEMS = ['.env', 'ssl', 'docker-compose.override.yml'];
+
+export function listSnapshots(backups) {
+  let names = [];
+  try { names = readdirSync(backups); } catch { return []; }
+  return names.map((n) => {
+    const dir = join(backups, n);
+    try { const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8')); return m?.complete ? { ...m, dir } : null; } catch { return null; }
+  }).filter(Boolean).sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)));
+}
+export const latestSnapshot = (backups) => listSnapshots(backups)[0] || null;
+
+const stampOf = (d) => d.toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z');
+
+/**
+ * The stack's volumes, from the containers' own mounts (compose volumes carry fixed `name:`s whose project
+ * label depends on who created them first, so a label filter misses some, postgres included, on real boxes).
+ * -> { volumes: [names], pgVolume: name|null }
+ */
+export async function stackVolumes(install, run) {
+  const ids = await run('docker', compose(install, ['ps', '-a', '-q']), { cwd: install.repoDir });
+  const list = ids.code === 0 ? ids.stdout.split('\n').map((s) => s.trim()).filter(Boolean) : [];
+  if (!list.length) return { volumes: [], pgVolume: null };
+  const r = await run('docker', ['inspect', '--format', '{{range .Mounts}}{{if eq .Type "volume"}}{{.Name}}>{{.Destination}};{{end}}{{end}}', ...list]);
+  if (r.code !== 0) return { volumes: [], pgVolume: null };
+  const seen = new Map();
+  for (const part of r.stdout.split(/[;\n]/).map((s) => s.trim()).filter(Boolean)) {
+    const [name, dest] = part.split('>');
+    if (name && !seen.has(name)) seen.set(name, dest || '');
+  }
+  const volumes = [...seen.keys()].sort();
+  return { volumes, pgVolume: volumes.find((v) => seen.get(v) === '/var/lib/postgresql/data') || null };
+}
+
+/**
+ * -> { ok, dir, manifest } | { ok:false, error }. g = gate(sys, { dryRun }).
+ * Order: dump postgres live, stop the stack, tar the other volumes, start the stack again.
+ */
+export async function createSnapshot({ install, installed, backups, g, reason = 'manual', now = () => new Date(), log = () => {} }) {
+  const createdAt = now();
+  const dir = join(backups, `${stampOf(createdAt)}-${installed.release || 'unknown'}-${installed.commit || 'nocommit'}`);
+  const pgUser = readEnvKeys(install.repoDir, ['POSTGRES_USER']).POSTGRES_USER || 'quoxflow';
+  const { volumes, pgVolume } = await stackVolumes(install, g.ro);
+  const tarVolumes = volumes.filter((v) => v !== pgVolume);
+  const cfg = CONFIG_ITEMS.filter((f) => existsSync(join(install.repoDir, f)));
+
+  await g.fx(`create ${dir}`, () => mkdirSync(join(dir, 'volumes'), { recursive: true, mode: 0o700 }));
+  await g.fx(`copy config (${cfg.join(', ') || 'nothing found'}) to ${join(dir, 'config')}`, () => {
+    mkdirSync(join(dir, 'config'), { recursive: true, mode: 0o700 });
+    for (const f of cfg) cpSync(join(install.repoDir, f), join(dir, 'config', f), { recursive: true, preserveTimestamps: true });
+  });
+  let postgres = null;
+  if (pgVolume) {
+    const r = await g.mut('docker', compose(install, ['exec', '-T', 'postgres', 'pg_dumpall', '-U', pgUser]), { cwd: install.repoDir, stdoutFile: join(dir, 'postgres.sql') });
+    if (r.code !== 0) return { ok: false, error: `pg_dumpall failed (exit ${r.code}): ${(r.stderr || '').trim().split('\n').pop()}` };
+    postgres = 'postgres.sql';
+  }
+  if (tarVolumes.length) {
+    const s = await g.mut('docker', compose(install, ['stop']), { cwd: install.repoDir });
+    if (s.code !== 0) return { ok: false, error: `docker compose stop failed (exit ${s.code})` };
+    try {
+      for (const v of tarVolumes) {
+        const r = await g.mut('docker', ['run', '--rm', '-v', `${v}:/v:ro`, '-v', `${join(dir, 'volumes')}:/b`, HELPER_IMAGE, 'tar', 'czf', `/b/${v}.tgz`, '-C', '/v', '.']);
+        if (r.code !== 0) return { ok: false, error: `could not archive volume ${v} (exit ${r.code})` };
+      }
+    } finally {
+      await g.mut('docker', compose(install, ['start']), { cwd: install.repoDir });
+    }
+  }
+  const manifest = {
+    version: 1, complete: true, createdAt: createdAt.toISOString(), reason,
+    release: installed.release, commit: installed.commit, tag: installed.tag || null, siblings: installed.siblings || {},
+    project: install.project, repoDir: install.repoDir, root: install.root,
+    config: cfg, postgres, postgresUser: pgUser, pgVolume, volumes: tarVolumes
+  };
+  await g.fx(`write ${join(dir, 'manifest.json')} (marks the snapshot complete)`, () => writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n', { mode: 0o600 }));
+  return { ok: true, dir, manifest };
+}
+
+/** Restore data + config from a snapshot into the install. Caller has already checked out the code and built. */
+export async function restoreSnapshot({ install, snap, g, pgReadyTries = 30, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) }) {
+  const dc = (args, opts = {}) => g.mut('docker', compose(install, args), { cwd: install.repoDir, ...opts });
+  await g.fx(`restore config (${(snap.config || []).join(', ') || 'none'}) from ${snap.dir}`, () => {
+    for (const f of snap.config || []) cpSync(join(snap.dir, 'config', f), join(install.repoDir, f), { recursive: true, force: true, preserveTimestamps: true });
+  });
+  let r = await dc(['down', '--remove-orphans']);
+  if (r.code !== 0) return { ok: false, error: `docker compose down failed (exit ${r.code})` };
+  for (const v of snap.volumes || []) {
+    r = await g.mut('docker', ['run', '--rm', '-v', `${v}:/v`, '-v', `${join(snap.dir, 'volumes')}:/b:ro`, HELPER_IMAGE, 'sh', '-c', `find /v -mindepth 1 -delete && tar xzf /b/${basename(v)}.tgz -C /v`]);
+    if (r.code !== 0) return { ok: false, error: `could not restore volume ${v} (exit ${r.code})` };
+  }
+  if (snap.postgres && snap.pgVolume) {
+    r = await g.mut('docker', ['volume', 'rm', snap.pgVolume]);
+    if (r.code !== 0) return { ok: false, error: `could not reset ${snap.pgVolume} (exit ${r.code})` };
+    r = await dc(['up', '-d', 'postgres']);
+    if (r.code !== 0) return { ok: false, error: `could not start postgres (exit ${r.code})` };
+    if (!g.dryRun) {
+      let ready = false;
+      for (let i = 0; i < pgReadyTries && !ready; i++) {
+        const p = await g.ro('docker', compose(install, ['exec', '-T', 'postgres', 'pg_isready', '-U', snap.postgresUser || 'quoxflow']), { cwd: install.repoDir });
+        ready = p.code === 0; if (!ready) await sleep(2000);
+      }
+      if (!ready) return { ok: false, error: 'postgres did not become ready to restore into' };
+    }
+    r = await dc(['exec', '-T', 'postgres', 'psql', '-q', '-U', snap.postgresUser || 'quoxflow', '-d', 'postgres'], { stdinFile: join(snap.dir, snap.postgres) });
+    if (r.code !== 0) return { ok: false, error: `psql restore failed (exit ${r.code})` };
+  }
+  return { ok: true };
+}
+
+export function snapshotSize(dir) {
+  let n = 0;
+  const walk = (d) => { for (const f of readdirSync(d)) { const p = join(d, f); const s = statSync(p); if (s.isDirectory()) walk(p); else n += s.size; } };
+  try { walk(dir); } catch { /* best effort */ }
+  return n;
+}

package/lib/server/status.js

@@ -0,0 +1,128 @@
+/**
+ * C4: `quox server status` and /server. Read-only: version, health per service, disk, ports, last update.
+ * Anything that could not be read is said as such, never filled in.
+ */
+import { readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { readInstalled } from './install.js';
+
+const STATE_FILE = 'lifecycle-state.json';
+const HISTORY_FILE = 'history.jsonl';
+
+export function readState(root) { try { return JSON.parse(readFileSync(join(root, STATE_FILE), 'utf8')); } catch { return null; } }
+export function writeState(root, state) {
+  mkdirSync(root, { recursive: true });
+  const p = join(root, STATE_FILE); const tmp = `${p}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, p);
+}
+export function appendHistory(root, event) {
+  mkdirSync(root, { recursive: true });
+  appendFileSync(join(root, HISTORY_FILE), JSON.stringify(event) + '\n', { mode: 0o600 });
+}
+export function readHistory(root) {
+  try { return readFileSync(join(root, HISTORY_FILE), 'utf8').split('\n').filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean); } catch { return []; }
+}
+
+/** `docker compose ps --format json` is a JSON array on some versions and NDJSON on others. */
+export function parseComposePs(text) {
+  const t = String(text || '').trim();
+  if (!t) return [];
+  try { const j = JSON.parse(t); return Array.isArray(j) ? j : [j]; } catch { /* NDJSON */ }
+  return t.split('\n').map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+}
+
+export const compose = (install, args) => ['compose', '-p', install.project, ...args];
+
+export async function composeServices(install, sys) {
+  const r = await sys.run('docker', compose(install, ['ps', '-a', '--format', 'json']), { cwd: install.repoDir });
+  if (r.code !== 0) return { ok: false, error: (r.stderr || '').trim().split('\n').pop() || `docker compose ps exited ${r.code}` };
+  return {
+    ok: true,
+    services: parseComposePs(r.stdout).map((s) => ({
+      service: s.Service || s.Name,
+      name: s.Name,
+      state: s.State || '?',
+      health: s.Health || null,
+      ports: [...new Set((s.Publishers || []).filter((p) => p.PublishedPort).map((p) => `${p.URL && p.URL !== '0.0.0.0' && p.URL !== '::' ? p.URL + ':' : ''}${p.PublishedPort}->${p.TargetPort}`))]
+    })).sort((a, b) => String(a.service).localeCompare(String(b.service)))
+  };
+}
+
+export async function diskFree(path, sys) {
+  const r = await sys.run('df', ['-Pk', path]);
+  if (r.code !== 0) return { ok: false, error: `df exited ${r.code}` };
+  const line = r.stdout.trim().split('\n').pop().split(/\s+/);
+  const availKb = Number(line[3]); const sizeKb = Number(line[1]);
+  if (!Number.isFinite(availKb)) return { ok: false, error: 'could not read df output' };
+  return { ok: true, path, freeGB: +(availKb / 1048576).toFixed(1), sizeGB: +(sizeKb / 1048576).toFixed(1), usedPct: line[4] };
+}
+
+async function getJson(url, fetchImpl, timeout = 3000) {
+  try {
+    const r = await fetchImpl(url, { signal: AbortSignal.timeout(timeout) });
+    if (!r.ok) return { ok: false, status: r.status, error: `HTTP ${r.status}` };
+    let body = null; try { body = await r.json(); } catch { /* health may be text */ }
+    return { ok: true, status: r.status, body };
+  } catch (e) { return { ok: false, error: e?.cause?.code || e?.message || 'no answer' }; }
+}
+
+/** The running build, from the collector's public /version. */
+export async function runningVersion(collectorUrl, fetchImpl = globalThis.fetch) {
+  const r = await getJson(`${collectorUrl.replace(/\/+$/, '')}/version`, fetchImpl);
+  if (!r.ok) return { ok: false, error: r.error };
+  return { ok: true, commit: r.body?.version || null, release: r.body?.release || null, stamped: r.body?.stamped ?? null };
+}
+
+export async function probeHttp(urls, fetchImpl = globalThis.fetch) {
+  return Promise.all(Object.entries(urls).map(async ([name, base]) => {
+    const t0 = Date.now();
+    const r = await getJson(`${base.replace(/\/+$/, '')}/health`, fetchImpl);
+    return { name, url: base, ok: r.ok, detail: r.ok ? `HTTP ${r.status}` : r.error, ms: Date.now() - t0 };
+  }));
+}
+
+export function defaultUrls(config) {
+  const get = (s, fb) => { try { return config?.getServiceUrl?.(s) || fb; } catch { return fb; } };
+  return { auth: get('auth', 'http://127.0.0.1:3101'), collector: get('collector', 'http://127.0.0.1:9848') };
+}
+
+/** -> the full status object. Never throws for a missing piece. */
+export async function gatherStatus({ install, sys, fetchImpl = globalThis.fetch, urls, backups }) {
+  const [installed, running, svc, disk, http] = await Promise.all([
+    readInstalled(install, sys),
+    runningVersion(urls.collector, fetchImpl),
+    composeServices(install, sys),
+    diskFree(install.root, sys),
+    probeHttp(urls, fetchImpl)
+  ]);
+  const hist = backups ? readHistory(backups) : [];
+  const lastUpdate = [...hist].reverse().find((e) => e.op === 'update' || e.op === 'rollback') || null;
+  const state = backups ? readState(backups) : null;
+  return { install, installed, running, services: svc, disk, http, lastUpdate, inFlight: state && state.status === 'running' ? state : null };
+}
+
+const svcIcon = (s) => (s.state === 'running' ? (s.health && s.health !== 'healthy' ? '⚠' : '✔') : '✖');
+
+/** Rows for the terminal and for /server (kind/key/text like the other panels). */
+export function statusRows(st) {
+  const row = (key, text) => ({ kind: 'row', key, text: String(text) });
+  const out = [{ kind: 'head', text: 'Server' }];
+  out.push(row('Install', `${st.install.repoDir} (found via ${st.install.source}, project ${st.install.project})`));
+  const i = st.installed;
+  out.push(row('Version', `${i.release || '? no VERSION file'}${i.tag ? ` (${i.tag})` : ''} · checkout ${i.commit || '?'}${i.dirty ? ' · local changes' : ''}`));
+  const rv = st.running;
+  out.push(row('Running', rv.ok ? `${rv.commit || '?'}${rv.stamped === false ? ' (unstamped build)' : ''}${rv.commit && i.commit && !String(rv.commit).startsWith(i.commit) && !String(i.commit).startsWith(rv.commit) ? ' · differs from the checkout' : ''}` : `? ${rv.error}`));
+  for (const h of st.http) out.push(row(`${h.ok ? '✔' : '✖'} ${h.name}`, `${h.url} · ${h.detail} · ${h.ms}ms`));
+  if (!st.services.ok) out.push(row('✖ Services', `? ${st.services.error}`));
+  else {
+    const up = st.services.services.filter((s) => s.state === 'running').length;
+    out.push(row('Services', `${up} of ${st.services.services.length} running`));
+    for (const s of st.services.services) out.push({ kind: s.state === 'running' && (!s.health || s.health === 'healthy') ? 'dim' : 'row', key: `  ${svcIcon(s)} ${s.service}`, text: [s.state + (s.health ? ` (${s.health})` : ''), s.ports.join(' ')].filter(Boolean).join(' · ') });
+  }
+  out.push(row('Disk', st.disk.ok ? `${st.disk.freeGB} GB free of ${st.disk.sizeGB} GB (${st.disk.usedPct} used) at ${st.disk.path}` : `? ${st.disk.error}`));
+  const lu = st.lastUpdate;
+  out.push(row('Last update', lu ? `${lu.op} ${lu.status} ${lu.at}${lu.from ? ` · ${lu.from} -> ${lu.to || '?'}` : ''}` : 'none recorded by quox server update'));
+  if (st.inFlight) out.push(row('⚠ In flight', `an update to ${st.inFlight.target} stopped after ${st.inFlight.done?.slice(-1)[0] || 'preflight'}; quox server update resumes it`));
+  return out;
+}

package/lib/server/sys.js

@@ -0,0 +1,65 @@
+/**
+ * C4 lifecycle: the one place that runs host commands (docker, docker compose, git, df, tar, openssl).
+ *
+ * Every lifecycle module takes a `sys` and never spawns on its own, so tests pass a stub and a dry run
+ * can prove it never reached a mutating command. A call marked { ro: true } is read-only and still runs
+ * in a dry run (it is how the plan learns what is there); anything else is recorded, never run, when
+ * dry. That rule lives here, once, in `gate()`.
+ */
+import { spawn as defaultSpawn } from 'node:child_process';
+import { createWriteStream, createReadStream } from 'node:fs';
+
+/** -> { run(cmd, args, opts) -> Promise<{ code, stdout, stderr }> } */
+export function createSys({ spawnImpl = defaultSpawn } = {}) {
+  return {
+    kind: 'real',
+    run(cmd, args = [], { cwd, env, stdoutFile, stdinFile, stdinText, timeoutMs = 0 } = {}) {
+      return new Promise((resolve) => {
+        let child;
+        try {
+          child = spawnImpl(cmd, args, { cwd, env: env ? { ...process.env, ...env } : process.env, stdio: [stdinFile || typeof stdinText === 'string' ? 'pipe' : 'ignore', 'pipe', 'pipe'] });
+        } catch (e) { resolve({ code: 127, stdout: '', stderr: e.message }); return; }
+        let stdout = ''; let stderr = '';
+        const sink = stdoutFile ? createWriteStream(stdoutFile, { mode: 0o600 }) : null;
+        if (sink) child.stdout.pipe(sink); else child.stdout.on('data', (d) => { if (stdout.length < 4e6) stdout += d; });
+        child.stderr.on('data', (d) => { if (stderr.length < 1e6) stderr += d; });
+        if (stdinFile) createReadStream(stdinFile).pipe(child.stdin);
+        else if (typeof stdinText === 'string') child.stdin.end(stdinText); // secrets via stdin, never argv
+        const timer = timeoutMs ? setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, timeoutMs) : null;
+        child.on('error', (e) => { clearTimeout(timer); resolve({ code: 127, stdout, stderr: stderr || e.message }); });
+        child.on('close', (code, sig) => {
+          clearTimeout(timer);
+          const done = () => resolve({ code: sig ? 128 : code, stdout, stderr });
+          if (sink) sink.end(done); else done();
+        });
+      });
+    }
+  };
+}
+
+export const show = (cmd, args = []) => [cmd, ...args].map((a) => (/^[\w./:=@%+,-]+$/.test(a) ? a : `'${String(a).replace(/'/g, `'\\''`)}'`)).join(' ');
+
+/**
+ * A step runner over sys: ro calls always run; mutating calls run only when !dryRun, else they are
+ * recorded in `planned` and answered { code: 0, dry: true }. log(line) receives every command shown.
+ */
+export function gate(sys, { dryRun = false, log = () => {} } = {}) {
+  const planned = [];
+  return {
+    dryRun,
+    planned,
+    async ro(cmd, args, opts) { return sys.run(cmd, args, opts); },
+    async mut(cmd, args, opts = {}) {
+      const line = show(cmd, args) + (opts.stdoutFile ? ` > ${opts.stdoutFile}` : '') + (opts.stdinFile ? ` < ${opts.stdinFile}` : '');
+      if (dryRun) { planned.push(line); log(`[dry run] ${line}`); return { code: 0, stdout: '', stderr: '', dry: true }; }
+      log(`$ ${line}`);
+      return sys.run(cmd, args, opts);
+    },
+    /** A filesystem change (or any non-command effect): described, and only performed when !dryRun. */
+    async fx(desc, fn) {
+      if (dryRun) { planned.push(desc); log(`[dry run] ${desc}`); return undefined; }
+      log(desc);
+      return fn();
+    }
+  };
+}

package/lib/server/uninstall.js

@@ -0,0 +1,63 @@
+/**
+ * C4: `quox server uninstall`. Lists exactly what goes first; two-step confirmation (the command layer);
+ * keeps backups unless --purge, and takes a final snapshot first unless --no-backup or --purge.
+ */
+import { existsSync, readdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { SIBLINGS } from './install.js';
+import { compose, composeServices } from './status.js';
+import { createSnapshot, listSnapshots, stackVolumes } from './snapshot.js';
+import { readInstalled } from './install.js';
+import { gate } from './sys.js';
+
+const DANGEROUS = (p, home) => {
+  const r = resolve(p);
+  return r === '/' || r === resolve(home) || r.split('/').filter(Boolean).length < 2;
+};
+
+/** Everything that will be removed and kept. Read-only. */
+export async function planUninstall({ install, sys, backups, purge = false, journeyFile = join(homedir(), '.config', 'quox', 'onboarding.json'), home = homedir() }) {
+  const svc = await composeServices(install, sys);
+  const vols = await stackVolumes(install, (c, a, o) => sys.run(c, a, o));
+  const imgs = await sys.run('docker', compose(install, ['config', '--images']), { cwd: install.repoDir });
+  const dirs = [install.repoDir, ...SIBLINGS.map((s) => join(install.root, s)).filter((d) => existsSync(d))];
+  const refused = dirs.filter((d) => DANGEROUS(d, home));
+  let rootToo = false;
+  try { rootToo = !DANGEROUS(install.root, home) && readdirSync(install.root).every((f) => dirs.includes(join(install.root, f))); } catch { /* unreadable */ }
+  const snaps = listSnapshots(backups);
+  const backupsInside = dirs.some((d) => resolve(backups).startsWith(resolve(d) + '/')) || (rootToo && resolve(backups).startsWith(resolve(install.root) + '/'));
+  return {
+    backupsInside,
+    containers: svc.ok ? svc.services.map((s) => s.name) : [],
+    containersError: svc.ok ? null : svc.error,
+    volumes: vols.volumes,
+    images: imgs.code === 0 ? [...new Set(imgs.stdout.split('\n').map((s) => s.trim()).filter(Boolean))] : [],
+    networks: `the ${install.project} compose networks`,
+    dirs: dirs.filter((d) => !refused.includes(d)),
+    root: rootToo ? install.root : null,
+    refused,
+    journeyFile: existsSync(journeyFile) ? journeyFile : null,
+    backups: { dir: backups, count: snaps.length, removed: purge }
+  };
+}
+
+/** Executes the plan. Confirmation is the caller's job and must have happened already. */
+export async function runUninstall({ install, sys, backups, purge = false, noBackup = false, dryRun = false, log = () => {}, plan, now }) {
+  const g = gate(sys, { dryRun, log });
+  if (plan.backupsInside && !purge) return { ok: false, step: 'plan', error: `the backups directory ${backups} sits inside the install, so removing the install would delete them. Set QUOX_SERVER_BACKUPS to a path outside it, or pass --purge.` };
+  let finalSnapshot = null;
+  if (!noBackup && !purge) {
+    const installed = await readInstalled(install, sys);
+    const snap = await createSnapshot({ install, installed, backups, g, reason: 'before uninstall', now, log });
+    if (!snap.ok) return { ok: false, step: 'backup', error: `${snap.error}. Nothing was removed; pass --no-backup to uninstall without a final snapshot.` };
+    finalSnapshot = snap.dir;
+  }
+  const r = await g.mut('docker', compose(install, ['down', '--volumes', '--rmi', 'local', '--remove-orphans']), { cwd: install.repoDir });
+  if (r.code !== 0) return { ok: false, step: 'down', error: `docker compose down failed (exit ${r.code}); the install directory was left in place` };
+  for (const d of plan.dirs) await g.fx(`remove ${d}`, () => rmSync(d, { recursive: true, force: true }));
+  if (plan.root) await g.fx(`remove ${plan.root} (now empty)`, () => rmSync(plan.root, { recursive: true, force: true }));
+  if (plan.journeyFile) await g.fx(`remove ${plan.journeyFile}`, () => rmSync(plan.journeyFile, { force: true }));
+  if (purge) await g.fx(`remove every backup in ${backups}`, () => rmSync(backups, { recursive: true, force: true }));
+  return { ok: true, dryRun, finalSnapshot, planned: g.planned };
+}