quoxcli 0.0.0-stage → 0.3.1

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/runner.js

@@ -0,0 +1,58 @@
+/**
+ * Install runner interface (C2a). The view only ever talks to this shape:
+ *
+ *   runner = {
+ *     kind: 'dry-run' | 'real',
+ *     stages: [{ id, label }],                       // fetch, configure, build, start, health
+ *     run({ onEvent, signal, request }) -> Promise<{ ok, dashboardUrl?, failedStage?, error? }>
+ *   }
+ *   events: { type: 'stage', id, status: 'running' | 'ok' | 'fail', at, ms? }
+ *           { type: 'log', line }                    // the real log tail (`v` shows it)
+ *
+ * The real runner (C2b) wraps get.quox.ai -> scripts/setup.sh and maps its "Step n/7" lines onto these stages.
+ * Only the dry run exists today: simulated, labelled, nothing downloaded, built or started.
+ */
+import { STAGES } from './copy.js';
+
+export const STAGE_IDS = ['fetch', 'configure', 'build', 'start', 'health'];
+export const stageList = () => STAGE_IDS.map(id => ({ id, label: STAGES[id] }));
+
+const DRY_LOG = {
+  fetch: ['[dry run] would clone quox, quoxflow and quoxmcp'],
+  configure: ['[dry run] would generate .env secrets and a self-signed certificate'],
+  build: ['[dry run] would run: docker compose build'],
+  start: ['[dry run] would run: docker compose up -d'],
+  health: ['[dry run] would wait for every service health check']
+};
+
+const wait = (ms, signal) => new Promise((res) => {
+  if (signal?.aborted) return res();
+  const t = setTimeout(done, ms);
+  function done() { clearTimeout(t); signal?.removeEventListener?.('abort', done); res(); }
+  signal?.addEventListener?.('abort', done, { once: true });
+});
+
+/** Dry run: walks the stages on a timer. `failAt` makes one stage fail (tests, demo of the failure path). */
+export function createDryRunRunner({ stepMs = 450, failAt = null, now = () => Date.now(), dashboardUrl = 'https://localhost:3000' } = {}) {
+  return {
+    kind: 'dry-run',
+    stages: stageList(),
+    async run({ onEvent = () => {}, signal } = {}) {
+      for (const id of STAGE_IDS) {
+        if (signal?.aborted) return { ok: false, interrupted: true };
+        const t0 = now();
+        onEvent({ type: 'stage', id, status: 'running', at: t0 });
+        for (const line of DRY_LOG[id]) onEvent({ type: 'log', line });
+        await wait(stepMs, signal);
+        if (signal?.aborted) return { ok: false, interrupted: true };
+        if (failAt === id) {
+          onEvent({ type: 'log', line: `[dry run] simulated failure at ${id}` });
+          onEvent({ type: 'stage', id, status: 'fail', at: now(), ms: now() - t0 });
+          return { ok: false, failedStage: id, error: 'simulated failure (dry run)' };
+        }
+        onEvent({ type: 'stage', id, status: 'ok', at: now(), ms: now() - t0 });
+      }
+      return { ok: true, dashboardUrl, dryRun: true };
+    }
+  };
+}