quoxcli 0.2.0 → 0.3.1

package/lib/server/doctor.js

@@ -0,0 +1,71 @@
+/**
+ * C4: `quox server doctor` = the `quox doctor` checks (runDoctorChecks, extracted in f491a2394) plus the
+ * server-side checks only the box itself can answer. All read-only. Same row shape as runDoctorChecks:
+ * { name, status: 'pass'|'warn'|'fail'|'skip', detail }.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { envKeyNames, readInstalled } from './install.js';
+import { composeServices, diskFree, runningVersion } from './status.js';
+import { latestSnapshot } from './snapshot.js';
+
+export const REQUIRED_ENV = ['JWT_SECRET', 'POSTGRES_PASSWORD', 'INTERNAL_SERVICE_KEY'];
+
+export async function serverChecks({ install, sys, fetchImpl = globalThis.fetch, urls, backups, now = () => Date.now() }) {
+  const out = [];
+  const add = (name, status, detail) => out.push({ name, status, detail });
+
+  const dk = await sys.run('docker', ['info', '--format', '{{.ServerVersion}}']);
+  add('Docker engine', dk.code === 0 ? 'pass' : 'fail', dk.code === 0 ? `server ${dk.stdout.trim()}` : 'docker info failed (is the daemon running, is this user in the docker group?)');
+
+  const svc = await composeServices(install, sys);
+  if (!svc.ok) add('Compose services', 'fail', svc.error);
+  else {
+    const down = svc.services.filter((s) => s.state !== 'running');
+    const sick = svc.services.filter((s) => s.state === 'running' && s.health && s.health !== 'healthy');
+    add('Compose services', down.length ? 'fail' : sick.length ? 'warn' : 'pass',
+      `${svc.services.length - down.length} of ${svc.services.length} running${down.length ? `; not running: ${down.map((s) => s.service).join(', ')}` : ''}${sick.length ? `; unhealthy: ${sick.map((s) => `${s.service} (${s.health})`).join(', ')}` : ''}`);
+  }
+
+  const disk = await diskFree(install.root, sys);
+  add('Disk space', !disk.ok ? 'warn' : disk.freeGB < 2 ? 'fail' : disk.freeGB < 5 ? 'warn' : 'pass', disk.ok ? `${disk.freeGB} GB free at ${disk.path}` : disk.error);
+
+  const keys = envKeyNames(install.repoDir);
+  if (!keys) add('Config (.env)', 'fail', `no .env in ${install.repoDir}`);
+  else {
+    const missing = REQUIRED_ENV.filter((k) => !keys.includes(k));
+    add('Config (.env)', missing.length ? 'fail' : 'pass', missing.length ? `missing ${missing.join(', ')}` : `${keys.length} keys, required ones present (values not read)`);
+  }
+
+  const cert = join(install.repoDir, 'ssl', 'quox.crt');
+  if (!existsSync(cert)) add('TLS certificate', 'warn', `no ${cert}`);
+  else {
+    const r = await sys.run('openssl', ['x509', '-enddate', '-noout', '-in', cert]);
+    const end = r.code === 0 ? Date.parse(r.stdout.replace(/^notAfter=/, '').trim()) : NaN;
+    if (!Number.isFinite(end)) add('TLS certificate', 'warn', 'could not read its expiry (openssl)');
+    else {
+      const days = Math.floor((end - now()) / 86400000);
+      add('TLS certificate', days < 0 ? 'fail' : days < 14 ? 'warn' : 'pass', days < 0 ? `expired ${-days} days ago` : `expires in ${days} days`);
+    }
+  }
+
+  const installed = await readInstalled(install, sys);
+  add('Checkout', installed.dirty ? 'warn' : installed.dirty === null ? 'warn' : 'pass',
+    installed.dirty === null ? 'not a git checkout; quox server update cannot move it' : `${installed.release || '?'} at ${installed.commit}${installed.dirty ? ', with local changes (update will refuse without --force)' : ', clean'}`);
+
+  const rv = await runningVersion(urls.collector, fetchImpl);
+  if (!rv.ok) add('Running build', 'warn', `collector /version: ${rv.error}`);
+  else if (rv.stamped === false) add('Running build', 'warn', 'the collector build is unstamped (0.0.0); rebuild with QUOXCORE_VERSION set');
+  else {
+    const same = installed.commit && rv.commit && (String(rv.commit).startsWith(installed.commit) || String(installed.commit).startsWith(rv.commit));
+    add('Running build', same || !installed.commit ? 'pass' : 'warn', same ? `${rv.commit}, matches the checkout` : `running ${rv.commit}, checkout is ${installed.commit} (rebuilt since? quox server update rebuilds)`);
+  }
+
+  const snap = backups ? latestSnapshot(backups) : null;
+  if (!snap) add('Backups', 'warn', `no snapshot yet in ${backups}; quox server update takes one first`);
+  else {
+    const days = Math.floor((now() - Date.parse(snap.createdAt)) / 86400000);
+    add('Backups', days > 30 ? 'warn' : 'pass', `latest ${snap.createdAt} (${days} days ago, ${snap.release || snap.commit})`);
+  }
+  return out;
+}

package/lib/server/install.js

@@ -0,0 +1,149 @@
+/**
+ * C4 lifecycle: which install are we talking about, what version is it, what is available.
+ *
+ * Layout (get.quox.ai -> install.sh -> scripts/setup.sh): $QUOX_DIR/{quox,quoxflow,quoxmcp}; the quox
+ * checkout holds docker-compose.yml, VERSION, .env and ssl/. Compose project = the checkout's dir name
+ * (setup.sh runs `docker compose` there), unless the running containers say otherwise.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname, basename, resolve } from 'node:path';
+
+export const PUBLIC_REPO = 'quoxai/quoxcore';
+export const SIBLINGS = ['quoxflow', 'quoxmcp'];
+
+export function backupsRoot(env = process.env, home = homedir()) {
+  if (env.QUOX_SERVER_BACKUPS) return resolve(env.QUOX_SERVER_BACKUPS);
+  return join(env.XDG_DATA_HOME || join(home, '.local', 'share'), 'quox', 'server-backups');
+}
+
+function normalize(p) {
+  if (!p) return null;
+  const abs = resolve(p);
+  if (existsSync(join(abs, 'docker-compose.yml'))) return { repoDir: abs, root: dirname(abs) };
+  if (existsSync(join(abs, 'quox', 'docker-compose.yml'))) return { repoDir: join(abs, 'quox'), root: abs };
+  return null;
+}
+
+/** install.json that scripts/setup.sh writes: { dir } (the install root or the quox checkout). */
+export function installRecordPath(env = process.env, home = homedir()) {
+  return join(env.XDG_CONFIG_HOME || join(home, '.config'), 'quox', 'install.json');
+}
+function readRecordedDir(env, home) {
+  try { const d = JSON.parse(readFileSync(installRecordPath(env, home), 'utf8'))?.dir; return typeof d === 'string' && d.startsWith('/') ? d : null; } catch { return null; }
+}
+
+/**
+ * Where the install lives: --dir, then QUOX_INSTALL_DIR, then the Getting started journey
+ * (~/.config/quox/onboarding.json installDir), then ~/.config/quox/install.json (written by setup.sh), then
+ * the running containers' compose label, then the installer's default ~/quox-install.
+ * -> { repoDir, root, project, source } | { error }
+ */
+export async function resolveInstall({ dir, env = process.env, sys, journey = null, home = homedir() } = {}) {
+  if (dir) {
+    const n = normalize(dir);
+    if (!n) return { error: `${dir} is not a Quox install (no docker-compose.yml there or in ${join(dir, 'quox')})` };
+    return { ...n, project: await projectFor(n.repoDir, sys), source: '--dir' };
+  }
+  if (env.QUOX_INSTALL_DIR) {
+    const n = normalize(env.QUOX_INSTALL_DIR);
+    if (n) return { ...n, project: await projectFor(n.repoDir, sys), source: 'QUOX_INSTALL_DIR' };
+  }
+  let j = journey;
+  if (j === null) { try { const { loadJourney } = await import('../quoxon/onboarding/journey.js'); j = loadJourney(); } catch { j = null; } }
+  if (j?.installDir) {
+    const n = normalize(j.installDir);
+    if (n) return { ...n, project: await projectFor(n.repoDir, sys), source: 'Getting started' };
+  }
+  const rec = normalize(readRecordedDir(env, home));
+  if (rec) return { ...rec, project: await projectFor(rec.repoDir, sys), source: 'install.json' };
+  if (sys) {
+    const r = await sys.run('docker', ['inspect', 'quox-auth', '--format', '{{index .Config.Labels "com.docker.compose.project.working_dir"}}|{{index .Config.Labels "com.docker.compose.project"}}']);
+    if (r.code === 0) {
+      const [wd, project] = r.stdout.trim().split('|');
+      const n = normalize(wd);
+      if (n) return { ...n, project: project || basename(n.repoDir), source: 'running containers' };
+    }
+  }
+  const def = normalize(join(home, 'quox-install'));
+  if (def) return { ...def, project: await projectFor(def.repoDir, sys), source: 'default ~/quox-install' };
+  return { error: 'no Quox install found here. Pass --dir <path>, or set QUOX_INSTALL_DIR (setup.sh records it in ~/.config/quox/install.json).' };
+}
+
+async function projectFor(repoDir, sys) {
+  if (sys) {
+    const r = await sys.run('docker', ['inspect', 'quox-auth', '--format', '{{index .Config.Labels "com.docker.compose.project.working_dir"}}|{{index .Config.Labels "com.docker.compose.project"}}']);
+    if (r.code === 0) {
+      const [wd, project] = r.stdout.trim().split('|');
+      if (wd && resolve(wd) === repoDir && project) return project;
+    }
+  }
+  return basename(repoDir);
+}
+
+/** Read named keys from .env. ALLOWLIST: only the keys asked for come back; nothing else is parsed out. */
+export function readEnvKeys(repoDir, keys) {
+  const out = {};
+  let text = '';
+  try { text = readFileSync(join(repoDir, '.env'), 'utf8'); } catch { return out; }
+  for (const line of text.split('\n')) {
+    const m = /^([A-Z0-9_]+)=(.*)$/.exec(line.trim());
+    if (m && keys.includes(m[1])) out[m[1]] = m[2].replace(/^"(.*)"$/, '$1');
+  }
+  return out;
+}
+
+/** Names only (never values) of every key in .env. */
+export function envKeyNames(repoDir) {
+  try {
+    return readFileSync(join(repoDir, '.env'), 'utf8').split('\n').map((l) => /^([A-Z0-9_]+)=/.exec(l.trim())?.[1]).filter(Boolean);
+  } catch { return null; }
+}
+
+/** -> { release, commit, tag, dirty, siblings: { quoxflow: commit|null, ... } } (read-only git). */
+export async function readInstalled({ repoDir, root }, sys) {
+  let release = null;
+  try { release = readFileSync(join(repoDir, 'VERSION'), 'utf8').trim() || null; } catch { /* no VERSION */ }
+  const git = async (dir, args) => { const r = await sys.run('git', ['-C', dir, ...args]); return r.code === 0 ? r.stdout.trim() : null; };
+  const commit = await git(repoDir, ['rev-parse', '--short', 'HEAD']);
+  const tag = await git(repoDir, ['describe', '--tags', '--exact-match', 'HEAD']);
+  const porcelain = await git(repoDir, ['status', '--porcelain', '--untracked-files=no']);
+  const siblings = {};
+  for (const s of SIBLINGS) {
+    const d = join(root, s);
+    siblings[s] = existsSync(join(d, '.git')) ? await git(d, ['rev-parse', '--short', 'HEAD']) : null;
+  }
+  return { release, commit, tag, dirty: porcelain === null ? null : porcelain.length > 0, siblings };
+}
+
+export function parseSemver(v) {
+  const m = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(v || '').trim());
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+}
+export function cmpSemver(a, b) {
+  const x = parseSemver(a); const y = parseSemver(b);
+  if (!x || !y) return null;
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] < y[i] ? -1 : 1;
+  return 0;
+}
+
+/**
+ * Tags on the public repo (read-only, unauthenticated GitHub API). Status checked before parsing.
+ * -> { ok: true, latest, tags } | { ok: false, error }
+ */
+export async function fetchAvailable({ fetchImpl = globalThis.fetch, repo = PUBLIC_REPO, timeoutMs = 8000 } = {}) {
+  const url = `https://api.github.com/repos/${repo}/tags?per_page=100`;
+  let r;
+  try { r = await fetchImpl(url, { headers: { accept: 'application/vnd.github+json', 'user-agent': 'quox-cli' }, signal: AbortSignal.timeout(timeoutMs) }); } catch (e) { return { ok: false, error: `could not reach ${url}: ${e?.message || e}` }; }
+  if (!r.ok) return { ok: false, error: `${url} answered HTTP ${r.status}` };
+  let body;
+  try { body = await r.json(); } catch { return { ok: false, error: `${url} did not return JSON` }; }
+  if (!Array.isArray(body)) return { ok: false, error: `${url} returned an unexpected shape` };
+  const tags = body.map((t) => t?.name).filter((n) => parseSemver(n)).sort((a, b) => cmpSemver(b, a));
+  if (!tags.length) return { ok: false, error: `no release tags on ${repo}` };
+  return { ok: true, latest: tags[0], tags };
+}
+
+export const releaseNotesUrl = (tag, repo = PUBLIC_REPO) => `https://github.com/${repo}/releases/tag/${tag}`;
+export const compareUrl = (from, to, repo = PUBLIC_REPO) => `https://github.com/${repo}/compare/${from}...${to}`;
+export const vtag = (v) => (String(v).startsWith('v') ? String(v) : `v${v}`);

package/lib/server/pluginEnable.js

@@ -0,0 +1,161 @@
+/**
+ * PLUGIN-IMG #1012: `quox plugin enable <id>` starts a paid plugin from its
+ * prebuilt PRIVATE image on a self-hosted install.
+ *
+ * Order, and why:
+ *   1. Licence check FIRST. Not entitled: refuse with a clear message and
+ *      run nothing on the box (no login, no pull, no compose). The entitlement
+ *      read is the same resolved set auth's has-plugin uses (verified,
+ *      instance-bound, unexpired leases), via the user-facing
+ *      /api/setup/licensing/entitlements read.
+ *   2. Pull credential (TODO hook below): the licence server will issue a
+ *      short-lived, package-scoped GHCR credential to an instance whose lease
+ *      covers the plugin. Until that endpoint ships, the hook returns a clear
+ *      "pending" error and enable stops there, unless the image is already
+ *      present locally (for example a proving VM where it was loaded by hand),
+ *      in which case it starts with --pull never.
+ *   3. docker compose -f docker-compose.yml -f docker-compose.images.yml
+ *        -f docker-compose.plugins.yml --profile <profile> up -d <service>
+ *   4. Health: poll the container's healthcheck until healthy (or time out).
+ *
+ * Everything that touches the host goes through an injected `sys`
+ * (lib/server/sys.js), so tests prove what would run without running it.
+ */
+
+/** Plugins that ship as prebuilt images. QuoxPlan only for now. */
+export const PLUGIN_IMAGES = Object.freeze({
+  quoxplan: Object.freeze({
+    service: 'quoxplan',
+    profile: 'with-quoxplan',
+    container: 'quox-quoxplan',
+    image: 'ghcr.io/quoxai/quoxplan',
+    registry: 'ghcr.io',
+  }),
+});
+
+export const COMPOSE_FILES = Object.freeze(['docker-compose.yml', 'docker-compose.images.yml', 'docker-compose.plugins.yml']);
+
+/** The image tag: the install's release tag (QUOX_IMAGE_TAG in .env), else latest. */
+export function imageRef(spec, tag) {
+  return `${spec.image}:${tag || 'latest'}`;
+}
+
+/** The docker compose argv `enable` runs (after `docker`). */
+export function composeUpArgs({ project }, spec, { pullNever = false } = {}) {
+  return [
+    'compose',
+    ...(project ? ['-p', project] : []),
+    ...COMPOSE_FILES.flatMap((f) => ['-f', f]),
+    '--profile', spec.profile,
+    'up', '-d',
+    ...(pullNever ? ['--pull', 'never'] : []),
+    spec.service,
+  ];
+}
+
+/**
+ * TODO(PLUGIN-IMG #1012, owner-gated): fetch a short-lived, package-scoped
+ * pull credential from the licence server for this instance's lease. The
+ * endpoint does not exist yet (licence-server change, owner deploy word).
+ * Contract when it lands: -> { ok: true, registry, username, token, expires_at }
+ * and enable logs in with `docker login <registry> -u <username> --password-stdin`.
+ */
+export async function getPluginPullCredential(_pluginId, _ctx = {}) {
+  return {
+    ok: false,
+    pending: true,
+    error: 'pull credential pending licence-server endpoint: the licence server does not issue plugin image pull credentials yet (#1012)',
+  };
+}
+
+/**
+ * Same rule as `quox plugin licence`: a governed plugin is entitled when the
+ * resolved entitlements carry it (bare or banded) and, when it is banded,
+ * this org holds a seat.
+ */
+export function entitlementFrom(data, pluginId) {
+  const entitlements = Array.isArray(data?.entitlements) ? data.entitlements : [];
+  const governed = (Array.isArray(data?.governed) ? data.governed : []).includes(pluginId);
+  const match = entitlements.find((e) => e === pluginId || String(e).startsWith(`${pluginId}@`)) || null;
+  const band = (data?.org_bands && data.org_bands[pluginId]) || null;
+  if (!governed) return { entitled: true, governed: false };
+  if (!match) return { entitled: false, governed: true, reason: 'no_entitlement' };
+  if (band && band.org_licensed === false) return { entitled: false, governed: true, reason: 'org_not_in_band' };
+  return { entitled: true, governed: true };
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.pluginId
+ * @param {(pluginId: string) => Promise<{ entitled: boolean, reason?: string }>} o.checkEntitlement
+ * @param {{ repoDir: string, project?: string }} o.install
+ * @param {{ run: Function }} o.sys
+ * @param {string} [o.tag] image tag (QUOX_IMAGE_TAG)
+ * @param {Function} [o.getPullCredential]
+ * @param {(ms: number) => Promise<void>} [o.sleep]
+ * @param {number} [o.healthTries]
+ * @param {(line: string) => void} [o.log]
+ * @returns {Promise<{ ok: boolean, stage: string, message: string, ran: string[][] }>}
+ */
+export async function enablePlugin({
+  pluginId, checkEntitlement, install, sys, tag,
+  getPullCredential = getPluginPullCredential,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  healthTries = 30, healthIntervalMs = 2000,
+  log = () => {},
+}) {
+  const ran = [];
+  const run = async (cmd, args, opts) => { ran.push([cmd, ...args]); return sys.run(cmd, args, opts); };
+  const spec = PLUGIN_IMAGES[pluginId];
+  if (!spec) {
+    const known = Object.keys(PLUGIN_IMAGES).join(', ');
+    return { ok: false, stage: 'unknown', message: `${pluginId} does not ship as a prebuilt plugin image yet (available: ${known}).`, ran };
+  }
+
+  let ent;
+  try {
+    ent = await checkEntitlement(pluginId);
+  } catch (err) {
+    return { ok: false, stage: 'licence', message: `Could not check the ${pluginId} licence (${err.message}). Nothing was pulled or started.`, ran };
+  }
+  if (!ent || !ent.entitled) {
+    const why = ent?.reason === 'org_not_in_band' ? ' This organisation does not hold one of its seats.' : '';
+    return {
+      ok: false,
+      stage: 'licence',
+      message: `${pluginId} is not licensed on this install.${why} Nothing was pulled or started. Run \`quox plugin licence ${pluginId}\` to see the entitlement, then renew or buy the licence.`,
+      ran,
+    };
+  }
+
+  const ref = imageRef(spec, tag);
+  let pullNever = false;
+  const cred = await getPullCredential(pluginId, { install });
+  if (cred && cred.ok) {
+    const login = await run('docker', ['login', cred.registry || spec.registry, '-u', cred.username, '--password-stdin'], { stdinText: cred.token });
+    if (login.code !== 0) return { ok: false, stage: 'login', message: `docker login to ${cred.registry || spec.registry} failed: ${(login.stderr || '').trim().slice(0, 300)}`, ran };
+  } else {
+    const local = await run('docker', ['image', 'inspect', ref, '--format', '{{.Id}}']);
+    if (local.code !== 0) {
+      return { ok: false, stage: 'pull-credential', message: `${pluginId} is licensed, but its image ${ref} is private and ${cred?.error || 'no pull credential is available'}. Nothing was started.`, ran };
+    }
+    pullNever = true;
+    log(`${ref} is already present locally; starting it without a pull.`);
+  }
+
+  const up = await run('docker', composeUpArgs(install, spec, { pullNever }), { cwd: install.repoDir });
+  if (up.code !== 0) return { ok: false, stage: 'compose', message: `docker compose up for ${spec.service} failed: ${(up.stderr || '').trim().slice(-400)}`, ran };
+
+  for (let i = 0; i < healthTries; i += 1) {
+    const h = await run('docker', ['inspect', '--format', '{{if .State.Health}}{{.State.Health.Status}}{{else}}{{.State.Status}}{{end}}', spec.container]);
+    const status = (h.stdout || '').trim();
+    if (h.code === 0 && status === 'healthy') {
+      return { ok: true, stage: 'healthy', message: `${pluginId} is running (${ref}) and healthy.`, ran };
+    }
+    if (h.code === 0 && status === 'unhealthy') {
+      return { ok: false, stage: 'health', message: `${spec.container} started but reports unhealthy. Check \`docker logs ${spec.container}\`.`, ran };
+    }
+    await sleep(healthIntervalMs);
+  }
+  return { ok: false, stage: 'health', message: `${spec.container} did not report healthy in time. Check \`docker logs ${spec.container}\`.`, ran };
+}

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;
+}