quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/windowOrg.js

@@ -0,0 +1,113 @@
+/**
+ * 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) });
+  return { client: createClient(config, windowOrg.auth), auth: windowOrg.auth, windowOrg };
+}
+
+/**
+ * /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/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}`);

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