quoxcli 0.2.0 → 0.4.0

package/lib/quoxon/onboarding/finish.js

@@ -107,6 +107,21 @@ export async function createFinisher({ profileUrl = LOCAL_PROFILE_URL, fetchImpl
       }
     },
 
+    /** QUOXON-Z2H lane R: the owner said yes at the credential step; record it as their own act. -> { ok } | { ok: false, error } */
+    async grantConsent(provider) {
+      try { await createApi({ client, config, auth }).grantConsent(provider); return { ok: true }; }
+      catch (e) { return { ok: false, error: apiError(e, 'consent not recorded') }; }
+    },
+
+    /** Z2H-R5 E: can this server serve its host installer? -> { ok, status } | null (unknown). Reads only. */
+    async hostInstaller() {
+      try {
+        const api = createApi({ client, config, auth });
+        const base = await api.hostsBaseUrl();
+        return await api.hostInstallCheck(base);
+      } catch { return null; }
+    },
+
     /** -> { ok: true, url, expiresAt, ttlSeconds } | { ok: false, error } */
     async loginLink(dashboardUrl) {
       try {

package/lib/quoxon/onboarding/index.js

@@ -7,6 +7,10 @@ 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';
@@ -15,6 +19,7 @@ import { createInstallRunner, defaultInstallDir, probeAuthHealth } from './insta
 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));
 
@@ -49,19 +54,41 @@ export async function runGettingStarted({ version, cwd, welcome = false, earlyIn
   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>: point the active profile at it and run the existing login. Restores the URL on failure. */
-export async function connectServer(url, { demo = false, spawn = spawnSync, out = (s) => process.stdout.write(s) } = {}) {
+/**
+ * /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 { loadConfig } = await import('../../core/config.js');
-  const config = loadConfig();
+  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 });
-  const r = spawn(process.execPath, [QUOX_BIN, 'login'], { stdio: 'inherit' });
-  if (r.status === 0) { clearJourney(); out(`${T.CONNECT_DONE}\n`); return { action: 'connected' }; }
-  if (prev) loadConfig().setProfileConnection({ url: prev });
+  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

@@ -22,13 +22,17 @@
  */
 import { spawn as defaultSpawn } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+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/;
@@ -44,7 +48,7 @@ const MARKS = [
  * push(rawLine) -> { line: cleaned text | null, moves: [[stageId, 'ok'|'running']] }
  */
 export function createStageParser() {
-  const state = { current: 'fetch', ready: false, degraded: false, dashboardUrl: null, lastError: null };
+  const state = { current: 'fetch', buildMode: null, ready: false, degraded: false, dashboardUrl: null, lastError: null };
   return {
     state,
     push(raw, { stderr = false } = {}) {
@@ -61,6 +65,9 @@ export function createStageParser() {
         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);
@@ -88,6 +95,7 @@ export function createInstallRunner({
   env = process.env,
   url = env.QUOX_INSTALLER_URL || INSTALLER_URL,
   installDir = defaultInstallDir(),
+  logDir = defaultInstallLogDir(),
   fetchImpl = globalThis.fetch,
   spawnImpl = defaultSpawn,
   tmpRoot = tmpdir(),
@@ -118,7 +126,44 @@ export function createInstallRunner({
     installDir,
     stages: stageList(),
     /** Per-run overrides (the view passes the journey's checkpoint): resumeFrom, resumeDashboardUrl, onCheckpoint. */
-    async run({ onEvent = () => {}, signal, resumeFrom: rf = resumeFrom, resumeDashboardUrl: rd = resumeDashboardUrl, onCheckpoint: oc = 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) => {
@@ -185,11 +230,13 @@ export function createInstallRunner({
             };
           };
           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));
@@ -220,6 +267,18 @@ export function createInstallRunner({
       } 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/preflight.js

@@ -8,7 +8,7 @@
  */
 import { execFile } from 'node:child_process';
 import { statfs } from 'node:fs/promises';
-import { totalmem, homedir } from 'node:os';
+import { totalmem, homedir, userInfo } from 'node:os';
 import { createConnection } from 'node:net';
 import { CHECK } from './copy.js';
 
@@ -55,13 +55,27 @@ export const defaultDeps = () => ({
 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);
-  if (v.missing || v.code !== 0) return row('docker', 'fail', CHECK.docker.missing, { fix: CHECK.docker.missingFix, link: CHECK.docker.missingLink });
+  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)) return row('docker', 'fail', CHECK.docker.perm, { fix: CHECK.docker.permFix, link: CHECK.docker.link });
+  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 });
 }
 

package/lib/quoxon/onboarding/probe.js

@@ -0,0 +1,65 @@
+/**
+ * #1101: is this URL a real QuoxCORE? One cheap unauthenticated GET of the edge's /health (nginx.conf answers
+ * {"status":"ok","service":"dashboard"} on both the HTTP and HTTPS servers), run BEFORE /connect server asks for
+ * an email and password. An error body is not data: only a 2xx JSON answer of that exact shape passes.
+ *
+ * -> { ok: true } | { ok: false, kind: 'url'|'unreachable'|'tls'|'not-quoxcore', code?, status?, detail? }
+ */
+const TLS_CODES = /^(SELF_SIGNED_CERT_IN_CHAIN|DEPTH_ZERO_SELF_SIGNED_CERT|UNABLE_TO_VERIFY_LEAF_SIGNATURE|UNABLE_TO_GET_ISSUER_CERT(_LOCALLY)?|CERT_HAS_EXPIRED|CERT_NOT_YET_VALID|ERR_TLS_.*|ERR_SSL_.*|EPROTO)$/;
+const PLAINTEXT_CODES = new Set(['ERR_SSL_WRONG_VERSION_NUMBER', 'EPROTO']);
+
+export async function probeQuoxCore(url, { fetchImpl = globalThis.fetch, timeout = 5000 } = {}) {
+  let base;
+  try {
+    base = new URL(String(url || ''));
+    if (base.protocol !== 'http:' && base.protocol !== 'https:') return { ok: false, kind: 'url', detail: 'the address must start with https:// or http://' };
+  } catch { return { ok: false, kind: 'url', detail: 'the address must start with https:// or http://' }; }
+  const target = `${base.href.replace(/\/+$/, '')}/health`;
+  let res;
+  try {
+    res = await fetchImpl(target, { signal: AbortSignal.timeout(timeout), headers: { accept: 'application/json' } });
+  } catch (e) {
+    const code = e?.cause?.code || e?.code || null;
+    if (code && TLS_CODES.test(code)) return { ok: false, kind: 'tls', code };
+    if (e?.name === 'TimeoutError' || e?.name === 'AbortError') return { ok: false, kind: 'unreachable', code: 'TIMEOUT', detail: `no answer within ${Math.round(timeout / 1000)} s` };
+    return { ok: false, kind: 'unreachable', code, detail: e?.message || 'no answer' };
+  }
+  if (res?.status === 400 && base.protocol === 'http:') {
+    let t = ''; try { t = await res.text(); } catch { /* no body */ }
+    if (/plain HTTP request was sent to HTTPS port/i.test(t)) return { ok: false, kind: 'tls', code: 'HTTP_TO_HTTPS_PORT' };
+  }
+  if (!res || !(res.status >= 200 && res.status < 300)) return { ok: false, kind: 'not-quoxcore', status: res?.status, detail: `HTTP ${res?.status} from /health` };
+  let body;
+  try { body = JSON.parse(await res.text()); } catch { return { ok: false, kind: 'not-quoxcore', status: res.status, detail: '/health did not answer JSON' }; }
+  if (!body || body.status !== 'ok' || body.service !== 'dashboard') return { ok: false, kind: 'not-quoxcore', status: res.status, detail: '/health answered, but not as QuoxCORE does' };
+  return { ok: true };
+}
+
+// A new QuoxCORE serves its own self-signed certificate (setup.sh writes ssl/quox.crt, CA:TRUE, SAN = localhost +
+// the LAN IP). Trusting exactly that file is the sanctioned fix; these are the codes it fixes. An expired or
+// wrong-name certificate is a different problem: trusting a file would not cure it, so it is not suggested.
+const SELF_SIGNED_CODES = new Set(['DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN', 'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY']);
+export const SERVER_CERT_DEFAULT = '~/quox-install/quox/ssl/quox.crt';
+
+/**
+ * One plain message per failure kind, naming the address and the next step.
+ * opts.localCert: the absolute path of a QuoxCORE certificate on THIS machine (the server is here), if any.
+ */
+export function probeMessage(url, r, { localCert = null } = {}) {
+  const again = 'Check the address, then try /connect server <url> again.';
+  switch (r?.kind) {
+    case 'url': return `"${url}" is not a server address (${r.detail}). Example: /connect server https://quox.example.com`;
+    case 'unreachable': return `No answer from ${url}${r.code ? ` (${r.code})` : ''}. Nothing was saved and no password was asked for. ${again}`;
+    case 'tls':
+      if (r.code === 'HTTP_TO_HTTPS_PORT') return `${url} is an HTTPS port spoken to in plain HTTP. Did you mean ${String(url).replace(/^http:/i, 'https:')} ? Nothing was saved.`;
+      if (PLAINTEXT_CODES.has(r.code)) return `${url} answered plain HTTP to an https:// request (${r.code}). Did you mean ${String(url).replace(/^https:/i, 'http:')} ? Nothing was saved.`;
+      if (SELF_SIGNED_CODES.has(r.code)) {
+        const lead = `${url} answered with its own self-signed certificate (${r.code}), which is normal for a new QuoxCORE. Trust that server's certificate, then start quox again.`;
+        const tail = 'Never turn TLS checks off. Nothing was saved.';
+        if (localCert) return `${lead} It is on this machine, so run: NODE_EXTRA_CA_CERTS=${localCert} quox   ${tail}`;
+        return `${lead} Copy it from the server (by default ${SERVER_CERT_DEFAULT}) to this machine, then run: NODE_EXTRA_CA_CERTS=~/quox.crt quox   ${tail}`;
+      }
+      return `${url} answered, but its TLS certificate is not trusted (${r.code}). For a self-signed edge, trust its CA with NODE_EXTRA_CA_CERTS=<ca.pem> and try again; never turn TLS checks off. Nothing was saved.`;
+    default: return `${url} answered, but it is not a QuoxCORE server (${r?.detail || 'unexpected answer'}). Nothing was saved and no password was asked for. ${again}`;
+  }
+}

package/lib/quoxon/onboarding/shortcutOffer.js

@@ -0,0 +1,28 @@
+/**
+ * QUOXON-Q: after first-run onboarding succeeds, ONE offer (y/N, default No, asked once) to make `q` run quox.
+ * The answer is remembered in the CLI config (shortcutOffer = 'yes' | 'no'). A yes runs the same code as
+ * `quox shortcut add`. Nothing is offered when q already resolves to something (ours or not): never shadow.
+ */
+import { askText } from '../ask.js';
+import { addShortcut, whichOnPath, DEFAULT_NAME } from '../../core/shortcut.js';
+
+export const SHORTCUT_QUESTION = 'Want a shorter command? Type `q` instead of `quox`.';
+export const shortcutOfferLine = () => askText(SHORTCUT_QUESTION, { keys: 'y/N', who: 'Quox', action: `make \`${DEFAULT_NAME}\` a link to quox in a folder you own (no sudo, no shell edits); undo with: quox shortcut remove` });
+
+/** -> true when the offer should be shown now. */
+export function shouldOfferShortcut({ config, env = process.env, which = whichOnPath } = {}) {
+  if (config?.get?.('shortcutOffer')) return false; // asked once
+  return !which(DEFAULT_NAME, env);
+}
+
+/** Runs the offer. ask(line) -> string answer. -> { offered, accepted, result? } */
+export async function offerShortcut({ config, ask, out = (s) => process.stdout.write(s), env = process.env, add = addShortcut, which = whichOnPath } = {}) {
+  if (!shouldOfferShortcut({ config, env, which })) return { offered: false };
+  const answer = String(await ask(shortcutOfferLine()) ?? '').trim();
+  const accepted = /^y(es)?$/i.test(answer);
+  config.set('shortcutOffer', accepted ? 'yes' : 'no');
+  if (!accepted) return { offered: true, accepted: false };
+  const result = add({ name: DEFAULT_NAME, env });
+  out(`${result.ok ? '✔' : '✖'} ${result.message}\n`);
+  return { offered: true, accepted: true, result };
+}