quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/windowOrg.js

@@ -0,0 +1,123 @@
+/**
+ * Window-scoped org (#1034 root cause). `/org switch` in the TUI used to write the new org and token into the SHARED
+ * profile (config.json) and move the shared server session's org, so every other window, script and proof run on the
+ * same profile (`-p moo`) silently ran in the switched org. Now the org-scoped token lives in THIS window's memory only:
+ *
+ *   - the switch asks the server for a token without moving the session (`scope: 'window'`); an older server that
+ *     moves it anyway gets the session put straight back on the profile's org;
+ *   - the profile, the file and every other process keep the profile's org and token;
+ *   - when the window token expires it is re-minted for the window's org, never the profile's.
+ *
+ * `quox org switch` from the shell is still the explicit way to change a profile's default org.
+ */
+import { resolveEndpoint } from '../api/endpoints.js';
+import { RESTART_ORG_ENV } from './slash/restart.js';
+
+export { RESTART_ORG_ENV };
+
+const expiryOf = (token) => {
+  try { const p = JSON.parse(Buffer.from(String(token).split('.')[1], 'base64url').toString('utf8')); return p?.exp ? p.exp * 1000 : null; }
+  catch { return null; }
+};
+
+/**
+ * @param {object} args
+ * @param {object} args.auth        the profile auth (createAuth(config))
+ * @param {object} args.baseClient  a client on the PROFILE identity (createClient(config, auth)), used only to mint
+ * @returns {{ auth, switchTo(orgId), current(), _expireForTest() }}
+ */
+export function createWindowOrg({ auth, baseClient, now = () => Date.now() }) {
+  let overlay = null; // { id, name, slug, role, access_token, expires_at } for this window only
+  const ep = resolveEndpoint('auth.switch-org');
+  const profileOrgId = () => { try { return auth.getOrgId(); } catch { return null; } };
+
+  async function mint(orgId) {
+    const data = await baseClient.post(ep.path, { service: ep.service, body: { org_id: orgId, scope: 'window' } });
+    if (!data?.org?.id || !data?.access_token) { const e = new Error('The server did not return a token for that org.'); e.code = 'switch_failed'; throw e; }
+    if (data.scope !== 'window') {
+      // An older server moved the shared session's org (the #1034 leak). Put it back on the profile's org so the other
+      // users of this profile do not refresh into the window's org. The token that call returns is discarded.
+      const home = profileOrgId();
+      if (home && home !== data.org.id) { try { await baseClient.post(ep.path, { service: ep.service, body: { org_id: home } }); } catch { /* best effort */ } }
+    }
+    return {
+      id: data.org.id, name: data.org.name || data.org.slug || data.org.id, slug: data.org.slug || null, role: data.role || null,
+      access_token: data.access_token, expires_at: expiryOf(data.access_token) ?? now() + 50 * 60 * 1000,
+    };
+  }
+
+  const over = {
+    getTokens() {
+      const t = auth.getTokens();
+      if (!overlay) return t;
+      return { ...(t || {}), access_token: overlay.access_token, expires_at: overlay.expires_at, org_id: overlay.id, org_name: overlay.name, org_slug: overlay.slug, org_role: overlay.role };
+    },
+    isExpired() { return overlay ? now() > overlay.expires_at : auth.isExpired(); },
+    getOrgId(o) { if (o) return o; return overlay ? overlay.id : auth.getOrgId(); },
+    async refresh(baseUrl) {
+      if (!overlay) return auth.refresh(baseUrl);
+      if (auth.isExpired()) await auth.refresh(baseUrl); // the profile's own token, in the profile's org
+      overlay = await mint(overlay.id);
+      return { access_token: overlay.access_token };
+    },
+    // A new sign-in or sign-out in this window starts from the profile again.
+    async login(...a) { overlay = null; return auth.login(...a); },
+    async logout(...a) { overlay = null; return auth.logout(...a); },
+  };
+  const wrapped = new Proxy(auth, {
+    get(t, k) {
+      if (Object.prototype.hasOwnProperty.call(over, k)) return over[k];
+      const v = t[k];
+      return typeof v === 'function' ? v.bind(t) : v;
+    },
+  });
+
+  return {
+    auth: wrapped,
+    /** Move THIS window to orgId. Back to the profile's own org just drops the window token. -> { id, name } */
+    async switchTo(orgId) {
+      if (orgId && orgId === profileOrgId()) {
+        overlay = null;
+        const a = auth.getTokens() || {};
+        return { id: orgId, name: a.org_name || a.org_slug || orgId };
+      }
+      const m = await mint(orgId);
+      overlay = m;
+      return { id: m.id, name: m.name };
+    },
+    /** The window's own org when it differs from the profile's, else null. */
+    current() { return overlay ? { id: overlay.id, name: overlay.name } : null; },
+    _expireForTest() { if (overlay) overlay.expires_at = now() - 1; },
+  };
+}
+
+/**
+ * The client a TUI window should use: requests carry the window's org token when one is set.
+ * -> { client, auth, windowOrg } ready for createApi({ ...this, config }).
+ */
+export function createWindowClient({ config, auth, createClient }) {
+  const windowOrg = createWindowOrg({ auth, baseClient: createClient(config, auth) });
+  // A client on the SAME user's token for another org, without moving this window (cached; each has its own overlay).
+  const scoped = new Map();
+  const clientForOrg = async (orgId) => {
+    if (scoped.has(orgId)) return scoped.get(orgId);
+    let cl;
+    if (orgId === (() => { try { return auth.getOrgId(); } catch { return null; } })()) cl = createClient(config, auth);
+    else { const sub = createWindowOrg({ auth, baseClient: createClient(config, auth) }); await sub.switchTo(orgId); cl = createClient(config, sub.auth); }
+    scoped.set(orgId, cl);
+    return cl;
+  };
+  return { client: createClient(config, windowOrg.auth), auth: windowOrg.auth, windowOrg, clientForOrg };
+}
+
+/**
+ * /restart hand-over: the predecessor's window org arrives in RESTART_ORG_ENV. Re-enter it in this window, once.
+ * -> null (nothing carried) | { id, name } | { error, id }
+ */
+export async function carryOrg(api, env = process.env) {
+  const id = env[RESTART_ORG_ENV] || null;
+  delete env[RESTART_ORG_ENV];
+  if (!id || !api?.switchOrg) return null;
+  try { return await api.switchOrg(id); }
+  catch (e) { return { error: e?.message || 'refused', id }; }
+}

package/lib/server/devServers.js

@@ -0,0 +1,137 @@
+// DEVFLEET: the dev-server list behind `quox server list|go|mark` and the TUI /server picker.
+// A dev server is a Bastion host (`quox fleet hosts`) that has a local entry in dev-servers.json
+// (purpose, and optionally project, repo, workdir, ci, user, jump). Bastion supplies address + state;
+// the entry supplies what the server is FOR. Pure functions here; the file read/write is the only IO.
+import { readFileSync, writeFileSync, mkdirSync, renameSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join, dirname } from 'node:path';
+import { matchServer, localIps } from '../quoxon/serverChip.js';
+import { resolveEndpoint } from '../api/endpoints.js';
+
+const FIELDS = ['purpose', 'project', 'repo', 'workdir', 'ci', 'user', 'jump', 'lastDeploy'];
+const SAFE = /^[A-Za-z0-9._@:\/~+-]+$/;
+
+export function registryPath(env = process.env) {
+  return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'quox', 'dev-servers.json');
+}
+
+/** -> { servers: { [name]: entry } }; a missing file is empty, a corrupt one throws (never clobbered). */
+export function readRegistry(path = registryPath()) {
+  let raw;
+  try { raw = readFileSync(path, 'utf8'); } catch (e) { if (e.code === 'ENOENT') return { servers: {} }; throw e; }
+  const j = JSON.parse(raw);
+  return { servers: j && typeof j.servers === 'object' && j.servers ? j.servers : {}, defaults: j && typeof j.defaults === 'object' && j.defaults ? j.defaults : {} };
+}
+
+/** Additive upsert of one server's entry; unspecified fields are kept. Atomic write. */
+export function markServer(name, fields, path = registryPath()) {
+  if (!name || !SAFE.test(name)) throw new Error(`invalid server name: ${name}`);
+  const reg = readRegistry(path);
+  const next = { ...(reg.servers[name] || {}) };
+  for (const k of FIELDS) if (fields[k] != null && fields[k] !== '') next[k] = String(fields[k]);
+  reg.servers[name] = next;
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(reg, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+  return next;
+}
+
+function writeCache(reg, path) {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(reg, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+const pickFields = (e) => Object.fromEntries(FIELDS.filter(k => e && e[k] != null && e[k] !== '').map(k => [k, String(e[k])]));
+
+/**
+ * The registry lives SERVER-SIDE (org-scoped, collector); the local file is an offline cache only.
+ * -> { servers, source: 'server' | 'cache', migrated }. A good server read refreshes the cache. If the server
+ * has no entries and the cache has some, they are uploaded once (migration). Unreachable or a non-registry
+ * answer -> the cache (a corrupt cache throws, never clobbered).
+ */
+export async function loadRegistry({ client, path = registryPath() } = {}) {
+  let remote = null;
+  let defaults = {}; // local-only preferences (e.g. defaults.jump, the ssh ProxyJump alias): never uploaded, kept across cache refreshes
+  try { defaults = readRegistry(path).defaults; } catch { /* corrupt cache: no local defaults */ }
+  try {
+    const ep = resolveEndpoint('devServerRegistry.list');
+    const d = await client.get(ep.path, { service: ep.service, retries: 0, timeout: 5000 });
+    if (d && typeof d.servers === 'object' && d.servers && !Array.isArray(d.servers)) remote = d.servers;
+  } catch { /* offline: fall back to the cache */ }
+  if (!remote) return { servers: readRegistry(path).servers, defaults, source: 'cache', migrated: 0 };
+  let migrated = 0;
+  let intact = true;
+  if (!Object.keys(remote).length) {
+    let local = {};
+    try { local = readRegistry(path).servers; } catch { /* unreadable cache: nothing to migrate */ }
+    for (const [name, e] of Object.entries(local)) {
+      try {
+        const ep = resolveEndpoint('devServerRegistry.put', { name });
+        await client.put(ep.path, { service: ep.service, body: pickFields(e) });
+        remote[name] = pickFields(e); migrated++;
+      } catch { intact = false; break; /* the cache keeps what did not upload; the next read retries */ }
+    }
+    // A failed upload must never be followed by a cache overwrite: the cache is then the only copy.
+    if (!intact) return { servers: { ...local, ...remote }, defaults, source: 'cache', migrated };
+  }
+  try { writeCache({ servers: remote, defaults }, path); } catch { /* cache is best effort */ }
+  return { servers: remote, defaults, source: 'server', migrated };
+}
+
+/** Upsert one entry on the server (additive), then refresh the cache. Offline -> throws, nothing written. */
+export async function saveServer({ client, name, fields, path = registryPath() }) {
+  if (!name || !SAFE.test(name)) throw new Error(`invalid server name: ${name}`);
+  const ep = resolveEndpoint('devServerRegistry.put', { name });
+  let r;
+  try { r = await client.put(ep.path, { service: ep.service, body: pickFields(fields) }); }
+  catch (e) { throw new Error(`could not save to the Quox server (${e?.message || 'failed'}); nothing was recorded`); }
+  let entry = r && r.entry && typeof r.entry === 'object' ? pickFields(r.entry) : null;
+  if (!entry) { try { entry = markServer(name, fields, path); } catch { entry = pickFields(fields); } }
+  else { try { const reg = readRegistry(path); reg.servers[name] = entry; writeCache(reg, path); } catch { /* cache is best effort */ } }
+  return entry;
+}
+
+/** Bastion host list + registry -> rows for each registered server. `here` = { hostname, ips }. */
+export function buildRows(hosts, registry, here = {}) {
+  const list = Array.isArray(hosts) ? hosts : [];
+  const me = matchServer(list, here);
+  return Object.entries(registry?.servers || {}).map(([name, e]) => {
+    const h = list.find(x => x && x.id === name) || null;
+    return {
+      name, purpose: e.purpose || null, project: e.project || null, repo: e.repo || null, workdir: e.workdir || null,
+      ci: e.ci || null, lastDeploy: e.lastDeploy || null,
+      ip: h?.ip || null,
+      registered: Boolean(h),
+      reachable: h ? (h.status?.state ?? h.state) === 'active' : false,
+      current: Boolean(me && me.name === name),
+      user: e.user || null, jump: e.jump || null, defaultJump: registry?.defaults?.jump || null
+    };
+  });
+}
+
+const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+/**
+ * What `go` will run. -> { error } | { local: true, cmd, args, cwd, text } | { cmd:'ssh', args, text }.
+ * Remote: the user's own ssh config/keys via the jump host alias; nothing is copied anywhere.
+ */
+export function planGo(row) {
+  if (!row) return { error: 'unknown server' };
+  if (!row.registered) return { error: `${row.name} is not in the Bastion host registry (quox fleet hosts), so go cannot reach it` };
+  if (!row.reachable) return { error: `${row.name} is not reachable according to the Bastion registry; try: quox fleet ping ${row.name}` };
+  if (row.current) {
+    const cwd = row.workdir || process.cwd();
+    return { local: true, cmd: 'quox', args: [], cwd, text: `cd ${cwd} && quox   (this is ${row.name}; local)` };
+  }
+  if (!row.ip) return { error: `${row.name} has no address in the Bastion registry` };
+  const target = `${row.user || 'control'}@${row.ip}`;
+  const remote = `${row.workdir ? `cd ${shq(row.workdir)} && ` : ''}exec quox`;
+  const jump = row.jump || row.defaultJump || null; // a per-server --jump, else the registry's defaults.jump, else a direct ssh
+  const args = ['-t', ...(jump ? ['-o', `ProxyJump=${jump}`] : []), target, remote];
+  return { cmd: 'ssh', args, text: `ssh ${args.slice(0, 4).join(' ')} ${shq(remote)}` };
+}
+
+export const hereIdentity = () => ({ hostname: hostname(), ips: localIps() });

package/lib/server/diag.js

@@ -0,0 +1,129 @@
+/**
+ * C4: `quox server diag` = a redacted support bundle, written locally, never uploaded.
+ *
+ * Redaction is ALLOWLIST-only, never a denylist (a denylist only knows the secret shapes its author
+ * thought of; 2026-08-09 a nested access_token slipped one):
+ *  - JSON log lines keep only the fields named in LOG_FIELDS; everything else is dropped.
+ *  - Free-text log lines keep a token only if it has an allowed SHAPE (a plain word, a small number,
+ *    a timestamp, a URL path with no query and no id-like segment, an HTTP method/status); a key=value
+ *    keeps its value only when the key is in VALUE_KEYS. Every other token becomes [redacted].
+ *  - .env: key names only, plus the values of ENV_VALUE_KEYS (non-secret by construction).
+ */
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { envKeyNames, readEnvKeys } from './install.js';
+
+export const LOG_FIELDS = ['time', 'timestamp', 'ts', 'level', 'severity', 'service', 'component', 'module', 'msg', 'message', 'event', 'type',
+  'status', 'statusCode', 'code', 'method', 'route', 'path', 'duration_ms', 'durationMs', 'latency_ms', 'attempt', 'phase', 'errorName', 'err_name'];
+export const VALUE_KEYS = ['status', 'code', 'method', 'level', 'service', 'port', 'attempt', 'duration', 'ms', 'count', 'exit', 'signal', 'version', 'route', 'path', 'phase', 'state'];
+export const ENV_VALUE_KEYS = ['NODE_ENV', 'LOG_LEVEL', 'QUOXCORE_VERSION', 'COMPOSE_PROJECT_NAME', 'TZ'];
+const R = '[redacted]';
+const TEXT_FIELDS = new Set(['msg', 'message']);
+
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const SHAPES = [
+  /^[A-Za-z][A-Za-z'’-]{0,24}$/, // a plain word
+  /^-?\d{1,6}(\.\d{1,3})?(ms|s|m|h|%|kb|mb|gb|KB|MB|GB)?$/, // a small number or duration
+  /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?(Z|[+-]\d{2}:?\d{2})?)?$/, // a date / ISO timestamp
+  /^\d{2}:\d{2}(:\d{2}(\.\d{1,6})?)?$/, // a clock time
+  /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/,
+  /^[[\](){}<>:;,.!?=|/*#&+-]{1,4}$/ // punctuation runs
+];
+const PUNCT_EDGE = /^([("'`[{<]*)(.*?)([)"'`\]}>:;,.!?]*)$/s;
+
+/** A URL path with no query; any id-like segment (digits+letters, 12+ chars, hex 8+) is masked. */
+function safePath(p) {
+  if (!/^\/[A-Za-z0-9/_.:-]{0,200}$/.test(p)) return null;
+  return p.split('/').map((seg) => (seg === '' || SHAPES[0].test(seg) || /^v\d{1,2}$/.test(seg) || /^\d{1,6}$/.test(seg) ? seg : ':id')).join('/');
+}
+
+function scrubToken(tok) {
+  const m = PUNCT_EDGE.exec(tok); const [, pre, core, post] = m || ['', '', tok, ''];
+  if (!core) return tok;
+  const kv = /^([A-Za-z_][\w.-]{0,40})([=:])(.*)$/.exec(core);
+  if (kv && !/^\/\//.test(kv[3])) {
+    const key = kv[1].toLowerCase().replace(/^.*[._-]/, '');
+    const val = kv[3].replace(/^["']|["']$/g, '');
+    const keep = VALUE_KEYS.includes(kv[1].toLowerCase()) || VALUE_KEYS.includes(key);
+    if (val === '') return `${pre}${kv[1]}${kv[2]}${post}`;
+    return `${pre}${kv[1]}${kv[2]}${keep && SHAPES.some((s) => s.test(val)) ? val : keep && safePath(val) ? safePath(val) : R}${post}`;
+  }
+  if (SHAPES.some((s) => s.test(core))) return `${pre}${core}${post}`;
+  if (core.startsWith('/')) { const sp = safePath(core); if (sp) return `${pre}${sp}${post}`; }
+  return `${pre}${R}${post}`;
+}
+
+/** Free text -> only allowed token shapes survive. */
+export function scrubText(line) {
+  return String(line || '').replace(ANSI, '').split(/(\s+)/).map((t) => (/^\s+$/.test(t) || t === '' ? t : scrubToken(t))).join('');
+}
+
+/** One log line -> its redacted form. JSON lines keep allowlisted fields only. */
+export function redactLine(line) {
+  const raw = String(line || '').replace(ANSI, '');
+  // docker compose prefixes "service-1  | "
+  const pm = /^(\S+\s+\|\s?)(.*)$/.exec(raw);
+  const prefix = pm ? pm[1] : ''; const body = pm ? pm[2] : raw;
+  const t = body.trim();
+  if (t.startsWith('{')) {
+    try {
+      const o = JSON.parse(t);
+      const kept = {};
+      for (const k of LOG_FIELDS) {
+        const v = o[k];
+        if (v === undefined || v === null || typeof v === 'object') continue;
+        if (typeof v === 'string') {
+          if (k === 'path' || k === 'route') kept[k] = safePath(v.split('?')[0]) || R;
+          else kept[k] = TEXT_FIELDS.has(k) ? scrubText(v) : (SHAPES.some((s) => s.test(v)) ? v : R);
+        } else kept[k] = v;
+      }
+      return prefix + JSON.stringify(kept);
+    } catch { /* not JSON after all */ }
+  }
+  return prefix + scrubText(body);
+}
+
+const INTERESTING = /\b(error|err|fail(ed|ure)?|fatal|exception|panic|warn(ing)?|refused|timeout|unhealthy|denied)\b/i;
+
+/** Recent error/warning lines only, newest last, at most `max`. */
+export function recentErrors(text, max = 200) {
+  return String(text || '').split('\n').filter((l) => INTERESTING.test(l)).slice(-max).map(redactLine);
+}
+
+/**
+ * Write the bundle. data = { versions, status rows, doctor rows }. Logs come from `docker compose logs`.
+ * -> { ok, file, files } ; the directory is tarred into <out>/quox-diag-<stamp>.tar.gz and removed.
+ */
+export async function writeDiagBundle({ install, sys, out, data, now = () => new Date(), services = null, tail = 2000 }) {
+  const stamp = now().toISOString().replace(/[:.]/g, '-').replace(/-\d{3}Z$/, 'Z');
+  const name = `quox-diag-${stamp}`;
+  const dir = join(out, name);
+  mkdirSync(join(dir, 'logs'), { recursive: true, mode: 0o700 });
+  const files = [];
+  const put = (rel, body) => { writeFileSync(join(dir, rel), typeof body === 'string' ? body : JSON.stringify(body, null, 2) + '\n', { mode: 0o600 }); files.push(rel); };
+
+  put('README.txt', [
+    'Quox support bundle (quox server diag). Written on this machine; nothing was uploaded.',
+    'Redaction is allowlist-only: JSON log lines keep only named fields; free-text lines keep only plain',
+    'words, small numbers, timestamps and id-free URL paths; everything else reads [redacted].',
+    '.env: key names only, plus the values of NODE_ENV, LOG_LEVEL, QUOXCORE_VERSION, COMPOSE_PROJECT_NAME, TZ.',
+    'Look through it before you share it.', ''
+  ].join('\n'));
+  put('versions.json', data.versions || {});
+  put('status.json', data.status || {});
+  put('doctor.json', data.doctor || []);
+  put('env.json', { keys: envKeyNames(install.repoDir) || [], values: readEnvKeys(install.repoDir, ENV_VALUE_KEYS) });
+
+  const names = services || (data.status?.services?.ok ? data.status.services.services.map((s) => s.service) : []);
+  for (const s of names) {
+    if (!/^[\w.-]+$/.test(s)) continue;
+    const r = await sys.run('docker', ['compose', '-p', install.project, 'logs', '--no-color', '--tail', String(tail), s], { cwd: install.repoDir });
+    const lines = r.code === 0 ? recentErrors(`${r.stdout}\n${r.stderr}`) : [`could not read logs (exit ${r.code})`];
+    put(join('logs', `${s}.log`), lines.join('\n') + '\n');
+  }
+  const file = join(out, `${name}.tar.gz`);
+  const t = await sys.run('tar', ['czf', file, '-C', out, name]);
+  if (t.code !== 0) return { ok: true, file: dir, files, tarred: false };
+  rmSync(dir, { recursive: true, force: true });
+  return { ok: true, file, files, tarred: true };
+}

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}`);