quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/onboarding/index.js

@@ -0,0 +1,94 @@
+/**
+ * Entry for Getting started (main.js calls this when no server is configured, or for --demo-onboarding).
+ * Runs the Ink view, then performs what it asked for: exit, or hand off to the existing `quox login` flow for
+ * `/connect server <url>`.
+ */
+import React from 'react';
+import { render } from 'ink';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { probeQuoxCore, probeMessage } from './probe.js';
+import { GettingStarted } from './view.js';
+import { inkStdout } from '../term.js';
+import { createCredentialBroker, createRequestCredential } from './credential.js';
+import { createDryRunRunner } from './runner.js';
+import { createInstallRunner, defaultInstallDir, probeAuthHealth } from './installRunner.js';
+import { createFinisher } from './finish.js';
+import { journeyPath as defaultJourneyPath, clearJourney, loadJourney } from './journey.js';
+import * as T from './copy.js';
+import { runDockerOffer } from './dockerOffer.js';
+
+const QUOX_BIN = fileURLToPath(new URL('../../../bin/quox.js', import.meta.url));
+
+/** The real install: get.quox.ai -> scripts/setup.sh, health = the new instance's auth service on loopback. */
+export async function realInstall({ env = process.env } = {}) {
+  // The CLI's own service resolution (honours the per-service overrides); with no server configured
+  // yet it derives auth on loopback 127.0.0.1:3101, where the new instance's auth service listens.
+  const { loadConfig } = await import('../../core/config.js');
+  const authUrl = loadConfig().getServiceUrl('auth');
+  const saved = loadJourney();
+  return {
+    runner: createInstallRunner({ env, installDir: saved?.installDir || defaultInstallDir(), probeHealth: () => probeAuthHealth(authUrl) }),
+    finisher: await createFinisher()
+  };
+}
+
+/** -> { action: 'exit' } | { action: 'connected', replay? } | { action: 'connect-failed' } */
+export async function runGettingStarted({ version, cwd, welcome = false, earlyInput = null, demo = false, stdout = process.stdout } = {}) {
+  const broker = createCredentialBroker();
+  const requestCredential = createRequestCredential(broker);
+  let result = { action: 'exit' };
+  const real = demo ? { runner: createDryRunRunner(), finisher: null } : await realInstall();
+  const props = {
+    version, cwd, welcome, earlyInput, broker, requestCredential,
+    dryRun: demo,
+    runner: real.runner,
+    finisher: real.finisher, // owner account, vault, one-time link (C2c); none in the dry run
+    journeyPath: demo ? null : defaultJourneyPath(), // the demo never leaves state behind
+    onExit: (r) => { result = r || result; app.unmount(); }
+  };
+  const app = render(React.createElement(GettingStarted, props), { exitOnCtrlC: false, stdout: inkStdout(stdout) });
+  await app.waitUntilExit();
+  broker.cancel();
+  if (result.action === 'connect') return connectServer(result.url, { demo });
+  if (result.action === 'docker' && !demo) return runDockerOffer(result.kind, { bin: QUOX_BIN }); // FIRSTRUN
+  return result;
+}
+
+/**
+ * /connect server <url>: check the URL is a real QuoxCORE (#1101), point the active profile at it and run the
+ * existing login. Any outcome but a completed sign-in (failure, Ctrl-C at Email or Password) puts the previous
+ * URL and the last-good config.json.bak back, so no half-saved profile is left behind.
+ */
+export async function connectServer(url, {
+  demo = false, spawn = spawnSync, out = (s) => process.stdout.write(s),
+  probe = probeQuoxCore, loadConfigImpl = null, bakFile = join(homedir(), '.config', 'quox', 'config.json.bak'),
+  localCertPath = join(defaultInstallDir(), 'quox', 'ssl', 'quox.crt') // the guided install's own certificate, if this is the server
+} = {}) {
+  if (demo) { out(`${T.connectHandoff(url)}\n(demo: not connecting)\n`); return { action: 'exit' }; }
+  const p = await probe(url);
+  if (!p?.ok) { out(`${probeMessage(url, p, { localCert: existsSync(localCertPath) ? localCertPath : null })}\n`); return { action: 'connect-failed' }; }
+  const load = loadConfigImpl || (await import('../../core/config.js')).loadConfig;
+  const config = load();
+  const prev = config.getActiveProfile()?.url || null;
+  let bak = null;
+  try { bak = readFileSync(bakFile); } catch { /* no backup yet */ }
+  config.setProfileConnection({ url });
+  out(`${T.connectHandoff(url)}\n`);
+  // Ctrl-C reaches the whole foreground group: the login child handles it, the parent must live to restore.
+  const hold = () => {};
+  process.on('SIGINT', hold);
+  let r;
+  try { r = spawn(process.execPath, [QUOX_BIN, 'login'], { stdio: 'inherit' }); } finally { process.removeListener('SIGINT', hold); }
+  if (r?.status === 0) { clearJourney(); out(`${T.CONNECT_DONE}\n`); return { action: 'connected' }; }
+  const cfg = load();
+  if (prev) cfg.setProfileConnection({ url: prev });
+  else { const prof = cfg.getActiveProfile(); if (prof) { delete prof.url; cfg.save(); } }
+  if (bak) { try { writeFileSync(bakFile, bak, { mode: 0o600 }); } catch { /* best effort */ } }
+  if (r?.status === 130 || r?.signal === 'SIGINT') { out(`\x1b[?25h${T.CONNECT_CANCELLED}\n`); return { action: 'connect-cancelled' }; }
+  out(`${T.connectFailed(url)}\n`);
+  return { action: 'connect-failed' };
+}

package/lib/quoxon/onboarding/installRunner.js

@@ -0,0 +1,284 @@
+/**
+ * C2b: the real install runner (the runner interface in ./runner.js).
+ *
+ * Wraps the existing installer, never a second one: get.quox.ai serves install.sh (quox-website
+ * public/install.sh), which clones quox, quoxflow and quoxmcp into $QUOX_DIR and runs
+ * scripts/setup.sh --yes (non-interactive). We download it to a private temp file, show its
+ * SHA256, run it with `sh`, and map its own step markers onto the five honest stages:
+ *
+ *   fetch      start .. "[setup] Step 2/7"     (install.sh clones; setup.sh step 1 preflight)
+ *   configure  Step 2/7 .. Step 6/7            (.env secrets, SSL cert, deps, stale cleanup)
+ *   build      Step 6/7 .. "Starting services" (docker compose build)
+ *   start      "Starting services" .. Step 7/7 (docker compose up -d)
+ *   health     Step 7/7 .. "full platform is ready" + our own probe of the auth service
+ *
+ * Re-running (setup.sh read, 2026-10-12): clone() pulls instead of re-cloning; an existing complete
+ * .env and ssl/quox.crt are kept (so the Postgres password still matches its volume); the image
+ * build is cached. Step 5 however REMOVES running quox-* containers (compose down, volumes kept)
+ * before rebuilding. So: interrupted before `start` completed -> run the whole installer again;
+ * `start` completed -> never re-run it, only check health.
+ *
+ * Never a fake percentage: elapsed time per stage, and the real log lines (`v` in the view).
+ */
+import { spawn as defaultSpawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, appendFileSync, openSync, readSync, fstatSync, closeSync } from 'node:fs';
+import { explainInstallFailure } from './failureCause.js';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { STAGE_IDS, stageList } from './runner.js';
+
+import { BUILD_LABELS } from './copy.js';
+export const INSTALLER_URL = 'https://get.quox.ai';
+export const defaultInstallDir = (home = homedir()) => join(home, 'quox-install');
+/** Where the full install log lives: the user's quox state dir, ~/.local/state/quox/install-logs. */
+export const defaultInstallLogDir = (home = homedir()) => join(home, '.local', 'state', 'quox', 'install-logs');
+
+const ANSI = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const RED = /^\x1b\[(0;)?31m/;
+const MARKS = [
+  [/^\[setup\] Step 2\/7\b/, 'configure'],
+  [/^\[setup\] Step 6\/7\b/, 'build'],
+  [/Starting services\.\.\./, 'start'],
+  [/^\[setup\] Step 7\/7\b/, 'health']
+];
+
+/**
+ * Line-by-line stage machine over the installer's output.
+ * push(rawLine) -> { line: cleaned text | null, moves: [[stageId, 'ok'|'running']] }
+ */
+export function createStageParser() {
+  const state = { current: 'fetch', buildMode: null, ready: false, degraded: false, dashboardUrl: null, lastError: null };
+  return {
+    state,
+    push(raw, { stderr = false } = {}) {
+      const text = String(raw ?? '').replace(ANSI, '').replace(/\s+$/, '');
+      const moves = [];
+      if (!text.trim()) return { line: null, moves };
+      const line = text.replace(/^\s+/, (m) => (m.length > 2 ? '  ' : m));
+      for (const [re, next] of MARKS) {
+        if (!re.test(line.trim())) continue;
+        const from = STAGE_IDS.indexOf(state.current); const to = STAGE_IDS.indexOf(next);
+        if (to <= from) break;
+        for (let i = from; i < to; i++) { moves.push([STAGE_IDS[i], 'ok']); if (i + 1 < to) moves.push([STAGE_IDS[i + 1], 'running']); }
+        moves.push([next, 'running']);
+        state.current = next;
+        break;
+      }
+      // Z2H-IMAGES: setup.sh either downloads prebuilt images or builds them; the build stage says which.
+      if (/Downloading prebuilt images/.test(line)) state.buildMode = 'download';
+      else if (/Building images/.test(line)) state.buildMode = 'build';
+      if (/QuoxCORE full platform is ready/.test(line)) state.ready = true;
+      if (/core shell is up, but platform features are degraded/.test(line)) state.degraded = true;
+      const open = /^\s*Open:\s+(https?:\/\/\S+)/.exec(line);
+      if (open) state.dashboardUrl = open[1];
+      if (stderr || RED.test(String(raw))) state.lastError = line.trim();
+      return { line: line.trim(), moves };
+    }
+  };
+}
+
+/** GET <authUrl>/health once. -> { ok, error? } */
+export async function probeAuthHealth(authUrl, { fetchImpl = globalThis.fetch, timeout = 3000 } = {}) {
+  try {
+    const r = await fetchImpl(`${authUrl.replace(/\/+$/, '')}/health`, { signal: AbortSignal.timeout(timeout) });
+    return r.ok ? { ok: true } : { ok: false, error: `auth /health answered HTTP ${r.status}` };
+  } catch (e) { return { ok: false, error: e?.cause?.code ? `${e.message} (${e.cause.code})` : (e?.message || 'no answer') }; }
+}
+
+const sleep = (ms, signal) => new Promise((res) => {
+  const t = setTimeout(res, ms);
+  signal?.addEventListener?.('abort', () => { clearTimeout(t); res(); }, { once: true });
+});
+
+export function createInstallRunner({
+  env = process.env,
+  url = env.QUOX_INSTALLER_URL || INSTALLER_URL,
+  installDir = defaultInstallDir(),
+  logDir = defaultInstallLogDir(),
+  fetchImpl = globalThis.fetch,
+  spawnImpl = defaultSpawn,
+  tmpRoot = tmpdir(),
+  probeHealth = async () => ({ ok: true }),
+  healthTries = 20,
+  healthIntervalMs = 3000,
+  resumeFrom = null,
+  resumeDashboardUrl = null,
+  onCheckpoint = () => {},
+  killGraceMs = 5000,
+  now = () => Date.now()
+} = {}) {
+  async function checkHealth(emit, signal) {
+    let last = null;
+    for (let i = 0; i < Math.max(1, healthTries); i++) {
+      if (signal?.aborted) return { ok: false, interrupted: true };
+      last = await probeHealth();
+      if (last?.ok) return { ok: true };
+      emit({ type: 'log', line: `waiting for the auth service: ${last?.error || 'not ready'}` });
+      if (i + 1 < healthTries) await sleep(healthIntervalMs, signal);
+    }
+    return { ok: false, error: last?.error || 'the auth service did not answer' };
+  }
+
+  return {
+    kind: 'real',
+    url,
+    installDir,
+    stages: stageList(),
+    /** Per-run overrides (the view passes the journey's checkpoint): resumeFrom, resumeDashboardUrl, onCheckpoint. */
+    /**
+     * Every run also writes the full stage log (each line the installer printed) to a file under the
+     * user's quox state dir; the result carries `logPath` so the UI can show it on failure and at the end.
+     */
+    async run(opts = {}) {
+      const { onEvent = () => {} } = opts;
+      let logPath = null;
+      try {
+        mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        logPath = join(logDir, `install-${new Date(now()).toISOString().replace(/[:.]/g, '-')}.log`);
+        writeFileSync(logPath, `# quox install log, started ${new Date(now()).toISOString()}\n`, { mode: 0o600 });
+      } catch { logPath = null; } // best effort: a log that cannot be written never fails the install
+      const recent = []; // FIRSTRUN: the last lines, so a failure can say its cause
+      const tee = (e) => {
+        if (e.type === 'log') { recent.push(e.line); if (recent.length > 400) recent.shift(); }
+        if (logPath) {
+          try {
+            if (e.type === 'log') appendFileSync(logPath, e.line + '\n');
+            else if (e.type === 'stage') appendFileSync(logPath, `-- stage ${e.id} ${e.status}\n`);
+          } catch { /* best effort */ }
+        }
+        onEvent(e);
+      };
+      const res = await runCore({ ...opts, onEvent: tee });
+      if (!res.ok && !res.interrupted) {
+        const named = recent.map(l => /Full build log:\s*(\S+)/.exec(l)?.[1]).filter(Boolean).pop();
+        const cause = explainInstallFailure(`${recent.join('\n')}\n${res.error || ''}\n${named ? tailOf(named) : ''}`);
+        if (cause) res.cause = cause;
+      }
+      if (!res.ok && !res.interrupted && logPath) {
+        // Z2H-R2: a failed run always says where the full log is and what to do next.
+        res.hint = `Full log: ${logPath}. It is safe to run the installer again; finished steps are kept and the build is cached.`;
+      }
+      if (logPath) { try { appendFileSync(logPath, `-- result ${res.ok ? 'ok' : `failed at ${res.failedStage || '?'}: ${res.error || ''}`}\n`); } catch { /* best effort */ } }
+      return logPath ? { ...res, logPath } : res;
+    }
+  };
+  async function runCore({ onEvent = () => {}, signal, resumeFrom: rf = resumeFrom, resumeDashboardUrl: rd = resumeDashboardUrl, onCheckpoint: oc = onCheckpoint } = {}) {
+      const resumeAfterStart = rf === 'start' || rf === 'health';
+      const started = {};
+      const stage = (id, status) => {
+        const at = now();
+        if (status === 'running') started[id] = at;
+        onEvent({ type: 'stage', id, status, at, ...(status !== 'running' ? { ms: started[id] != null ? at - started[id] : null } : {}) });
+      };
+      const emit = (e) => onEvent(e);
+
+      if (resumeAfterStart) {
+        for (const id of ['fetch', 'configure', 'build', 'start']) onEvent({ type: 'stage', id, status: 'ok', at: now(), ms: null, earlier: true });
+        emit({ type: 'log', line: 'the services were already started; checking their health' });
+        stage('health', 'running');
+        const h = await checkHealth(emit, signal);
+        if (h.interrupted) return { ok: false, interrupted: true };
+        if (!h.ok) { stage('health', 'fail'); return { ok: false, failedStage: 'health', error: h.error, dashboardUrl: rd }; }
+        stage('health', 'ok');
+        oc('health', { dashboardUrl: rd });
+        return { ok: true, dashboardUrl: rd, resumed: true };
+      }
+
+      // ---- fetch: download the installer, show what will run -------------------------------------
+      stage('fetch', 'running');
+      let body;
+      try {
+        const r = await fetchImpl(url, { signal });
+        if (!r.ok) { stage('fetch', 'fail'); return { ok: false, failedStage: 'fetch', error: `${url} answered HTTP ${r.status}` }; }
+        body = await r.text();
+      } catch (e) {
+        if (signal?.aborted) return { ok: false, interrupted: true };
+        stage('fetch', 'fail');
+        return { ok: false, failedStage: 'fetch', error: `could not download ${url}: ${e?.message || e}` };
+      }
+      if (!/^#!\s*\/bin\/(ba)?sh\b/.test(body)) { stage('fetch', 'fail'); return { ok: false, failedStage: 'fetch', error: `${url} did not return a shell script, so nothing was run` }; }
+      const sha256 = createHash('sha256').update(body).digest('hex');
+      emit({ type: 'script', url, sha256, bytes: Buffer.byteLength(body) });
+      emit({ type: 'log', line: `installer ${url} sha256 ${sha256}` });
+
+      const dir = mkdtempSync(join(tmpRoot, 'quox-installer-'));
+      const file = join(dir, 'install.sh');
+      writeFileSync(file, body, { mode: 0o600 });
+
+      const parser = createStageParser();
+      try {
+        const code = await new Promise((resolve) => {
+          const child = spawnImpl('sh', [file], {
+            cwd: homedir(),
+            env: { ...env, QUOX_DIR: installDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+            detached: true // own process group: abort stops docker compose too
+          });
+          let killTimer = null;
+          const onAbort = () => {
+            try { process.kill(-child.pid, 'SIGTERM'); } catch { /* already gone */ }
+            killTimer = setTimeout(() => { try { process.kill(-child.pid, 'SIGKILL'); } catch { /* gone */ } }, killGraceMs);
+          };
+          if (signal) { if (signal.aborted) onAbort(); else signal.addEventListener('abort', onAbort, { once: true }); }
+          const feed = (stderr) => {
+            let rest = '';
+            return (chunk) => {
+              const parts = (rest + chunk.toString('utf8')).split(/\r\n|\r|\n/);
+              rest = parts.pop();
+              for (const raw of parts) take(raw, stderr);
+            };
+          };
+          const take = (raw, stderr) => {
+            const modeBefore = parser.state.buildMode;
+            const { line, moves } = parser.push(raw, { stderr });
+            for (const [id, status] of moves) {
+              if (status === 'ok') { stage(id, 'ok'); if (id !== 'health') oc(id, {}); }
+              else stage(id, 'running');
+            }
+            if (parser.state.buildMode !== modeBefore) emit({ type: 'stage-label', id: 'build', label: BUILD_LABELS[parser.state.buildMode] });
+            if (line) emit({ type: 'log', line });
+          };
+          child.stdout.on('data', feed(false));
+          child.stderr.on('data', feed(true));
+          child.on('error', (e) => { parser.state.lastError = `could not run sh: ${e.message}`; resolve(127); });
+          child.on('close', (c, sig) => { clearTimeout(killTimer); signal?.removeEventListener?.('abort', onAbort); resolve(sig ? 128 : c); });
+        });
+
+        if (signal?.aborted) return { ok: false, interrupted: true };
+        const at = parser.state.current;
+        if (code !== 0) {
+          stage(at, 'fail');
+          return { ok: false, failedStage: at, error: parser.state.lastError || `the installer exited with code ${code}`, dashboardUrl: parser.state.dashboardUrl };
+        }
+        if (at !== 'health' || !parser.state.ready) {
+          if (at !== 'health') stage(at, 'fail'); else stage('health', 'fail');
+          return {
+            ok: false, failedStage: at === 'health' ? 'health' : at, degraded: parser.state.degraded, dashboardUrl: parser.state.dashboardUrl,
+            error: parser.state.degraded ? 'the core is up, but some services are not healthy yet' : 'the installer finished without saying the platform is ready'
+          };
+        }
+        const h = await checkHealth(emit, signal);
+        if (h.interrupted) return { ok: false, interrupted: true };
+        if (!h.ok) { stage('health', 'fail'); return { ok: false, failedStage: 'health', error: h.error, dashboardUrl: parser.state.dashboardUrl }; }
+        stage('health', 'ok');
+        oc('health', { dashboardUrl: parser.state.dashboardUrl });
+        return { ok: true, dashboardUrl: parser.state.dashboardUrl, sha256 };
+      } finally {
+        try { rmSync(dir, { recursive: true, force: true }); } catch { /* temp cleanup only */ }
+      }
+  }
+}
+
+/** The last `max` bytes of a file, '' when it cannot be read (a cause is best effort, never a new failure). */
+function tailOf(path, max = 256 * 1024) {
+  let fd = null;
+  try {
+    fd = openSync(path, 'r');
+    const size = fstatSync(fd).size;
+    const len = Math.min(size, max);
+    const buf = Buffer.alloc(len);
+    readSync(fd, buf, 0, len, size - len);
+    return buf.toString('utf8');
+  } catch { return ''; } finally { if (fd != null) try { closeSync(fd); } catch { /* closed */ } }
+}

package/lib/quoxon/onboarding/intent.js

@@ -0,0 +1,53 @@
+/**
+ * Local intent matcher for Getting started. No model, no network: a keyword table, so the answer is instant
+ * and predictable. Anything it does not recognise is "offscript" and gets an honest deferral.
+ */
+
+export const INTENTS = ['servers', 'automate', 'code', 'email', 'explore'];
+
+// Order matters: the first rule whose pattern matches wins ("connect" first, so "I already have a server"
+// is never read as "watch my servers").
+const RULES = [
+  ['connect', /\b(already (have|got|run)|have (a|my|an?) (own )?(server|quox|instance)|existing (server|quox|instance)|my (own )?quox(core)?|connect (to )?(a |my )?(server|quox))\b/i],
+  ['servers', /\b(servers?|hosts?|fleet|monitor(ing)?|watch(ing)?|uptime|infra(structure)?|machines?|homelab|proxmox|vms?|nodes?|cluster|disk space|logs?)\b/i],
+  ['email', /\b(e-?mails?|mail|inbox|gmail|outlook|newsletters?|replies)\b/i],
+  ['code', /\b(code|coding|coder|repos?|repository|github|gitlab|pull requests?|prs?|bugs?|refactor|programm(ing|er)|develop(er|ment)?|tests?)\b/i],
+  ['automate', /\b(automat(e|ion|ing)|workflows?|schedul(e|ed|ing)|cron|routines?|repetitive|every (day|morning|week|hour)|n8n|zapier|tasks?|jobs?)\b/i],
+  ['explore', /\b(look(ing)? around|explore|just looking|curious|show me|demo|tour|not sure|no idea|anything|surprise me|what can (you|it|quox) do|browse)\b/i]
+];
+
+/** -> { intent: one of INTENTS | 'connect' | 'offscript' | 'empty', text } */
+export function matchIntent(input) {
+  const text = String(input ?? '').trim();
+  if (!text) return { intent: 'empty', text };
+  const n = /^[1-5]$/.exec(text);
+  if (n) return { intent: INTENTS[Number(n[0]) - 1], text };
+  for (const [intent, re] of RULES) if (re.test(text)) return { intent, text };
+  return { intent: 'offscript', text };
+}
+
+/** Y/n answer: Enter alone means yes. -> true | false | null (not an answer) */
+export function yesNo(input) {
+  const t = String(input ?? '').trim().toLowerCase();
+  if (t === '' || /^(y|yes|yeah|yep|sure|ok|okay|go|do it|set it up|please)\b/.test(t)) return true;
+  if (/^(n|no|nope|not now|later|skip|cancel)\b/.test(t)) return false;
+  return null;
+}
+
+/** `/connect server <url>` -> { ok, url } | { ok: false, reason: 'usage' | 'url', value } | null (not /connect) */
+export function parseConnect(input) {
+  const t = String(input ?? '').trim();
+  if (!/^\/connect\b/i.test(t)) return null;
+  const m = /^\/connect\s+server(?:\s+(\S+))?\s*$/i.exec(t);
+  if (!m) return { ok: false, reason: 'usage' };
+  if (!m[1]) return { ok: false, reason: 'usage' };
+  let raw = m[1];
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw)) raw = `https://${raw}`;
+  try {
+    const u = new URL(raw);
+    if (!['http:', 'https:'].includes(u.protocol) || !u.hostname) return { ok: false, reason: 'url', value: m[1] };
+    return { ok: true, url: u.origin + (u.pathname === '/' ? '' : u.pathname.replace(/\/+$/, '')) };
+  } catch {
+    return { ok: false, reason: 'url', value: m[1] };
+  }
+}

package/lib/quoxon/onboarding/journey.js

@@ -0,0 +1,73 @@
+/**
+ * Journey state for Getting started: ~/.config/quox/onboarding.json, so an interrupted journey resumes.
+ * ALLOWLIST ONLY: the file holds exactly the fields named here (never a key, token or password), whatever the
+ * caller passes in.
+ */
+import { readFileSync, writeFileSync, mkdirSync, rmSync, renameSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+
+export const JOURNEY_VERSION = 1;
+export const STEPS = ['ask', 'offer', 'declined', 'preflight', 'credential', 'install', 'owner', 'finishing', 'finale'];
+// installStage = the last install stage that COMPLETED (installRunner.js decides what re-running means).
+const FIELDS = ['step', 'intent', 'request', 'provider', 'installStage', 'installDir', 'dashboardUrl', 'ownerEmail', 'ollamaUrl', 'startedAt', 'updatedAt'];
+const INSTALL_STAGES = ['fetch', 'configure', 'build', 'start', 'health'];
+const MAX = { request: 500, installDir: 300, dashboardUrl: 300, ownerEmail: 254, ollamaUrl: 200 };
+
+export const journeyPath = () => join(homedir(), '.config', 'quox', 'onboarding.json');
+
+export function sanitize(state) {
+  const out = { version: JOURNEY_VERSION };
+  for (const k of FIELDS) {
+    const v = state?.[k];
+    if (v === undefined || v === null) continue;
+    if (typeof v !== 'string') continue;
+    out[k] = v.slice(0, MAX[k] || 64);
+  }
+  if (out.installStage && !INSTALL_STAGES.includes(out.installStage)) delete out.installStage;
+  if (out.dashboardUrl && !/^https?:\/\/[^\s]+$/.test(out.dashboardUrl)) delete out.dashboardUrl;
+  if (out.installDir && !out.installDir.startsWith('/')) delete out.installDir;
+  if (out.step && !STEPS.includes(out.step)) delete out.step;
+  if (out.provider && !['chatgpt', 'openai', 'anthropic', 'ollama', 'skip'].includes(out.provider)) delete out.provider;
+  if (out.ollamaUrl !== undefined && (typeof out.ollamaUrl !== 'string' || !/^https?:\/\//.test(out.ollamaUrl))) delete out.ollamaUrl; // B3: a URL, never a secret
+  return out;
+}
+
+export function loadJourney(path = journeyPath()) {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!raw || raw.version !== JOURNEY_VERSION) return null;
+    const s = sanitize(raw);
+    return s.step ? s : null;
+  } catch { return null; }
+}
+
+export function saveJourney(state, path = journeyPath(), now = () => new Date().toISOString()) {
+  if (!path) return false;
+  try {
+    const prev = loadJourney(path);
+    const t = now();
+    const next = sanitize({ ...state, startedAt: prev?.startedAt || state.startedAt || t, updatedAt: t });
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+    return true;
+  } catch { return false; }
+}
+
+export function clearJourney(path = journeyPath()) {
+  if (!path) return;
+  try { rmSync(path, { force: true }); } catch { /* nothing to clear */ }
+}
+
+/**
+ * Where a resumed journey starts. The AI key only ever lived in memory, so anything past the credential
+ * step goes back through preflight (cheap, and the machine may have changed) and asks for the key again.
+ */
+export function resumeStep(saved) {
+  if (!saved?.step) return null;
+  if (saved.step === 'ask' || saved.step === 'finale') return null;
+  if (saved.step === 'offer' || saved.step === 'declined') return 'offer';
+  return 'preflight';
+}

package/lib/quoxon/onboarding/preflight.js

@@ -0,0 +1,156 @@
+/**
+ * Preflight for Getting started: real checks, each bounded by a timeout, never sudo, never a write.
+ * Thresholds and ports are the installer's own (read from the repo, keep in step):
+ *   scripts/preflight.sh  MIN_RAM_GB=4, MIN_DISK_GB=10
+ *   README (public mirror) "Plan for 8 GB of RAM and 30 GB of free disk"
+ *   scripts/setup.sh      needs docker (daemon reachable), docker compose v2, openssl; get.quox.ai needs git
+ *   docker-compose.yml    host ports below
+ */
+import { execFile } from 'node:child_process';
+import { statfs } from 'node:fs/promises';
+import { totalmem, homedir, userInfo } from 'node:os';
+import { createConnection } from 'node:net';
+import { CHECK } from './copy.js';
+
+export const MIN_DISK_GB = 10;
+export const REC_DISK_GB = 30;
+export const MIN_RAM_GB = 4;
+export const REC_RAM_GB = 8;
+/** Every host port docker-compose.yml publishes (80, 3000 and 9848 on all interfaces, the rest on loopback). */
+export const PORTS = [80, 3000, 9848, 3100, 3101, 3102, 3103, 3104, 3105, 3106, 3107, 3108, 3110, 3200, 5432, 6333, 9849];
+export const CHECK_IDS = ['docker', 'compose', 'tools', 'disk', 'ram', 'ports'];
+
+/** execFile with a hard timeout; never throws. -> { code, stdout, stderr, missing } */
+export function run(cmd, args, timeout = 6000) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = execFile(cmd, args, { timeout, killSignal: 'SIGKILL', windowsHide: true, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+        resolve({ code: err ? (typeof err.code === 'number' ? err.code : 1) : 0, stdout: String(stdout || ''), stderr: String(stderr || ''), missing: err?.code === 'ENOENT', timedOut: Boolean(err?.killed) });
+      });
+    } catch (e) { resolve({ code: 1, stdout: '', stderr: String(e?.message || e), missing: e?.code === 'ENOENT' }); }
+    child?.stdin?.end?.();
+  });
+}
+
+/** Is something listening on 127.0.0.1:port? A connect, not a bind: needs no privileges, works for port 80. */
+export function portInUse(port, timeout = 400) {
+  return new Promise((resolve) => {
+    const s = createConnection({ host: '127.0.0.1', port });
+    const done = (v) => { s.destroy(); resolve(v); };
+    s.setTimeout(timeout, () => done(false));
+    s.once('connect', () => done(true));
+    s.once('error', () => done(false));
+  });
+}
+
+export const defaultDeps = () => ({
+  run,
+  portInUse,
+  statfs: (p) => statfs(p),
+  totalmem,
+  home: homedir()
+});
+
+const gb = (bytes) => Math.floor(bytes / 1024 ** 3);
+const row = (id, status, body, extra = {}) => ({ id, name: CHECK[id].name, status, body, ...extra });
+
+const safeUser = () => { try { return userInfo().username; } catch { return ''; } };
+
+export async function checkDocker(d) {
+  const v = await d.run('docker', ['--version'], 5000);
+  const linux = (d.platform || process.platform) === 'linux'; // FIRSTRUN: the guide can fix these itself (dockerOffer.js)
+  const offer = (kind) => (linux ? { offer: kind } : {});
+  if (v.missing || v.code !== 0) return row('docker', 'fail', CHECK.docker.missing, { fix: CHECK.docker.missingFix, link: CHECK.docker.missingLink, ...offer('install') });
+  const ver = (/version\s+([0-9][\w.\-+]*)/i.exec(v.stdout) || [])[1] || '';
+  const info = await d.run('docker', ['info', '--format', '{{.ServerVersion}}'], 10000);
+  if (info.code === 0 && info.stdout.trim()) return row('docker', 'ok', CHECK.docker.ok(ver || info.stdout.trim()));
+  if (/permission denied/i.test(info.stderr)) {
+    // Z2H-R5 D: the group was added after this terminal started. `id -nG` shows the groups of THIS process,
+    // `id -nG <user>` the account database; in the second but not the first, "press r" can never pass.
+    const user = d.user || safeUser();
+    if (user) {
+      const [mine, db] = await Promise.all([d.run('id', ['-nG'], 3000), d.run('id', ['-nG', user], 3000)]);
+      const has = (r) => r.code === 0 && r.stdout.trim().split(/\s+/).includes('docker');
+      if (has(db) && !has(mine)) return row('docker', 'fail', CHECK.docker.permStale, { fix: CHECK.docker.permStaleFix, link: CHECK.docker.link, stale: true, ...offer('relaunch') });
+    }
+    return row('docker', 'fail', CHECK.docker.perm, { fix: CHECK.docker.permFix, link: CHECK.docker.link, ...offer('group') });
+  }
+  return row('docker', 'fail', CHECK.docker.down, { fix: CHECK.docker.downFix, link: CHECK.docker.link });
+}
+
+export async function checkCompose(d) {
+  const r = await d.run('docker', ['compose', 'version', '--short'], 6000);
+  const v = r.stdout.trim();
+  if (r.code !== 0 || !v) return row('compose', 'fail', CHECK.compose.missing, { fix: CHECK.compose.missingFix, link: CHECK.compose.link });
+  const major = Number((/^v?(\d+)/.exec(v) || [])[1]);
+  if (major < 2) return row('compose', 'fail', CHECK.compose.old(v), { fix: CHECK.compose.missingFix, link: CHECK.compose.link });
+  return row('compose', 'ok', CHECK.compose.ok(v));
+}
+
+export async function checkTools(d) {
+  const [git, ssl] = await Promise.all([d.run('git', ['--version'], 4000), d.run('openssl', ['version'], 4000)]);
+  const missing = [git.code === 0 ? null : 'git', ssl.code === 0 ? null : 'openssl'].filter(Boolean);
+  if (missing.length) return row('tools', 'fail', CHECK.tools.missing(missing), { fix: CHECK.tools.fix(missing), link: CHECK.tools.link });
+  return row('tools', 'ok', CHECK.tools.ok);
+}
+
+export async function checkDisk(d) {
+  try {
+    const s = await d.statfs(d.home);
+    const free = gb(Number(s.bavail) * Number(s.bsize));
+    if (free < MIN_DISK_GB) return row('disk', 'fail', CHECK.disk.fail(free, MIN_DISK_GB), { fix: CHECK.disk.fix(MIN_DISK_GB), link: CHECK.disk.link });
+    if (free < REC_DISK_GB) return row('disk', 'warn', CHECK.disk.low(free, REC_DISK_GB));
+    return row('disk', 'ok', CHECK.disk.ok(free));
+  } catch (e) {
+    return row('disk', 'warn', `could not measure free space (${e?.code || 'error'})`);
+  }
+}
+
+export async function checkRam(d) {
+  const total = Math.round(d.totalmem() / 1024 ** 3);
+  if (total < MIN_RAM_GB) return row('ram', 'fail', CHECK.ram.fail(total, MIN_RAM_GB), { fix: CHECK.ram.fix(MIN_RAM_GB), link: CHECK.ram.link });
+  if (total < REC_RAM_GB) return row('ram', 'warn', CHECK.ram.low(total, REC_RAM_GB));
+  return row('ram', 'ok', CHECK.ram.ok(total));
+}
+
+export async function checkPorts(d, ports = PORTS) {
+  const used = [];
+  await Promise.all(ports.map(async (p) => { if (await d.portInUse(p)) used.push(p); }));
+  used.sort((a, b) => a - b);
+  const quox = used.includes(3000) && used.includes(9848); // the dashboard and collector ports: most likely Quox itself
+  // Resuming an install this guide started: Quox's own ports being busy is expected, not a blocker.
+  if (used.length && quox && d.ownInstall) return row('ports', 'warn', CHECK.ports.ownInstall);
+  if (used.length) return row('ports', 'fail', CHECK.ports.busy(used), { fix: quox ? CHECK.ports.quoxFix : CHECK.ports.fix(used[0]), link: CHECK.ports.link });
+  return row('ports', 'ok', CHECK.ports.ok(ports.length));
+}
+
+const CHECKS = { docker: checkDocker, compose: checkCompose, tools: checkTools, disk: checkDisk, ram: checkRam, ports: checkPorts };
+
+/** Rows in their running state, before any result. */
+export const pendingRows = () => CHECK_IDS.map(id => row(id, 'running', CHECK.running));
+
+/** Run every check in parallel; onRow(row) fires as each finishes. -> rows in CHECK_IDS order. */
+export async function runPreflight(deps = defaultDeps(), onRow = () => {}) {
+  const rows = await Promise.all(CHECK_IDS.map(async (id) => {
+    let r;
+    try { r = await CHECKS[id](deps); } catch (e) { r = row(id, 'fail', `check failed: ${e?.message || e}`, { fix: 'Press r to check again.', link: 'https://quox.ai/docs/setup' }); }
+    onRow(r);
+    return r;
+  }));
+  return rows;
+}
+
+export const preflightPassed = (rows) => rows.length > 0 && rows.every(r => r.status === 'ok' || r.status === 'warn');
+
+/** Ollama on this machine? A 1 s GET of its model list; never throws. */
+export async function detectOllama({ fetchImpl = globalThis.fetch, timeout = 1000 } = {}) {
+  if (!fetchImpl) return false;
+  const ac = new AbortController();
+  let t;
+  const late = new Promise((res) => { t = setTimeout(() => { ac.abort(); res(null); }, timeout); });
+  try {
+    const r = await Promise.race([fetchImpl('http://127.0.0.1:11434/api/tags', { signal: ac.signal }), late]);
+    return Boolean(r?.ok);
+  } catch { return false; } finally { clearTimeout(t); }
+}