quoxcli 0.3.1 → 0.5.0

package/lib/server/installFlow.js

@@ -0,0 +1,168 @@
+/**
+ * `quox server install`: the existing guided installer behind a CLI verb (ONBOARD-P1).
+ *
+ * Not a second installer. Preflight (onboarding/preflight.js), the real runner (installRunner.js: get.quox.ai ->
+ * setup.sh) and the finisher (finish.js: owner account, sign-in, one-time link) are the same modules the Getting
+ * started screen uses; this file only sequences them and turns their events into stage events:
+ *
+ *   preflight  docker  download  compose-up  health  owner  vault  link
+ *
+ * The runner's own stages fold in as: fetch + configure + build -> download, start -> compose-up, health -> health.
+ * `vault` is skipped here (no AI key is taken on argv); the next step is printed.
+ * Nothing is claimed ok that did not answer: health is the runner's own 2xx probe of the auth service.
+ */
+import { resolve } from 'node:path';
+import { QuoxUserError } from '../core/errors.js';
+import { confirmInteractive } from '../core/confirm.js';
+import { runPreflight, preflightPassed, defaultDeps as preflightDeps } from '../quoxon/onboarding/preflight.js';
+import { defaultInstallDir } from '../quoxon/onboarding/installRunner.js';
+import { passwordProblem, emailOk } from '../quoxon/onboarding/finish.js';
+
+export const INSTALL_STAGES = ['preflight', 'docker', 'download', 'compose-up', 'health', 'owner', 'vault', 'link'];
+const FOLD = { fetch: 'download', configure: 'download', build: 'download', start: 'compose-up', health: 'health' };
+export const PLAN_STEPS = [
+  'check Docker, Compose, git, openssl, disk, RAM and ports (read-only)',
+  'download the installer from get.quox.ai and show its SHA256',
+  'clone the Quox source into the install directory',
+  'write secrets (.env) and a self-signed certificate',
+  'download the Quox images',
+  'start the services with docker compose up -d',
+  'wait until the auth service answers /health with a 2xx',
+  'create your owner account and sign in',
+  'print a one-time dashboard sign-in link (10 minutes)'
+];
+const AGAIN = 'quox server install';
+const LINK_HOW = 'quox -p <profile> dashboard (mints a fresh one-time sign-in link), or re-run with --print-login-link';
+
+/** The preflight copy is shared with the TUI ("press r"); the CLI/JSON path speaks CLI. */
+const cliWords = (t) => String(t == null ? t : t).replace(/,? then press r to check again\.?/gi, ` Then run: ${AGAIN}`).replace(/,? then press r( to try again)?\.?/gi, '.').replace(/\s+\./g, '.').replace(/\.\s*\./g, '.');
+/** This verb never installs Docker: the honest offer is a manual one with the doc link. */
+const cliRow = (r) => ({
+  ...r,
+  ...(r.fix ? { fix: cliWords(r.fix) } : {}),
+  ...(r.offer === 'install' ? { offer: 'manual' } : {})
+});
+
+/** First line of stdin, no trailing newline. */
+export async function readPasswordStdin(readStdin) {
+  const first = String(await readStdin()).split(/\r?\n/)[0];
+  if (!first) throw new QuoxUserError('--password-stdin got an empty first line. Pipe the password in, for example: printf %s "$PW" | quox server install --password-stdin', { exitCode: 2, code: 'empty_password' });
+  return first;
+}
+
+export async function defaultReadStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+async function defaultPrompt(message, type) {
+  const { default: inquirer } = await import('inquirer');
+  const a = await inquirer.prompt([{ type, name: 'v', message, ...(type === 'password' ? { mask: '*' } : {}) }]);
+  return a.v;
+}
+
+export async function defaultMakeInstall({ dir, env = process.env } = {}) {
+  const { realInstall } = await import('../quoxon/onboarding/index.js');
+  return realInstall({ env, installDir: dir });
+}
+
+/**
+ * -> { ok, ... }. Throws QuoxUserError (exit 2) for refusals made before anything changes.
+ * opts: { dir, dryRun, yes, email, passwordStdin }; deps: see defaults; emit(event).
+ */
+export async function runInstallFlow(opts = {}, deps = {}, emit = () => {}) {
+  const d = {
+    runChecks: runPreflight, makeInstall: defaultMakeInstall, confirm: confirmInteractive,
+    isTTY: () => Boolean(process.stdin.isTTY), readStdin: defaultReadStdin,
+    promptEmail: () => defaultPrompt('Owner email', 'input'), promptPassword: () => defaultPrompt('Owner password (hidden)', 'password'),
+    ...deps
+  };
+  const { dryRun = false, yes = false, passwordStdin = false } = opts;
+  const dir = resolve(opts.dir || defaultInstallDir());
+  const printLink = Boolean(opts.printLink);
+  const stage = (s, status, extra = {}) => emit({ type: 'stage', stage: s, status, ...extra });
+  const fail = (failedStage, error, next, extra = {}) => {
+    stage(failedStage, 'fail', { error, next });
+    const res = { ok: false, failedStage, error, next, ...extra };
+    emit({ type: 'result', ...res });
+    return res;
+  };
+
+  // ---- refusals first: nothing has been touched --------------------------------------------------------------
+  if (!dryRun) {
+    if (!yes && !d.isTTY()) throw new QuoxUserError('No terminal to answer y/N here. Read the plan with --dry-run, then re-run with --yes to install.', { exitCode: 2, code: 'no_terminal' });
+    if (!d.isTTY() && !passwordStdin) throw new QuoxUserError('No terminal for the owner password prompt. Pipe it in with --password-stdin (the password is never taken as an argument).', { exitCode: 2, code: 'no_terminal' });
+  }
+
+  // ---- preflight (read-only, also in a dry run) --------------------------------------------------------------
+  stage('preflight', 'running');
+  const rows = (await d.runChecks(preflightDeps(), () => {})).map(cliRow);
+  const dockerRows = rows.filter(r => r.id === 'docker' || r.id === 'compose');
+  const otherRows = rows.filter(r => r.id !== 'docker' && r.id !== 'compose');
+  const nextFor = (rs) => rs.filter(r => r.status === 'fail').map(r => `${r.fix || r.body}`).join(' ');
+  const bad = rows.filter(r => r.status === 'fail');
+  const otherBad = bad.filter(r => r.id !== 'docker' && r.id !== 'compose');
+  if (otherBad.length) return fail('preflight', bad.map(r => r.body).join('; '), `${nextFor(bad)} Then run: ${AGAIN}`, { checks: rows });
+  stage('preflight', 'ok', { detail: otherRows.map(r => r.body).join('; ') });
+  if (bad.length) return fail('docker', bad.map(r => r.body).join('; '), `${nextFor(bad)} Then run: ${AGAIN}`, { checks: rows });
+  stage('docker', 'ok', { detail: dockerRows.map(r => r.body).join('; ') });
+
+  if (dryRun) {
+    emit({ type: 'plan', dir, installerUrl: 'https://get.quox.ai', checks: rows.map(r => ({ id: r.id, status: r.status, body: r.body })), steps: PLAN_STEPS, changed: 'nothing' });
+    const res = { ok: true, dryRun: true };
+    emit({ type: 'result', ...res });
+    return res;
+  }
+
+  // ---- confirm, then collect the owner credentials BEFORE the long install -----------------------------------
+  if (!yes && !(await d.confirm(`Install Quox into ${dir} now?`, { flag: '--yes', purpose: 'install' }))) {
+    const res = { ok: false, declined: true, error: 'not confirmed', next: `Nothing was changed. Run ${AGAIN} --dry-run to see the plan.` };
+    emit({ type: 'result', ...res });
+    return res;
+  }
+  let email = opts.email ? String(opts.email).trim() : null;
+  if (!email && d.isTTY()) email = String(await d.promptEmail()).trim();
+  if (!emailOk(email)) throw new QuoxUserError('A valid owner email is needed: pass --email <address>.', { exitCode: 2, code: 'bad_email' });
+  const password = passwordStdin ? await readPasswordStdin(d.readStdin) : await d.promptPassword();
+  const weak = passwordProblem(password);
+  if (weak) throw new QuoxUserError(`The owner password is not accepted: ${weak}`, { exitCode: 2, code: 'weak_password' });
+
+  // ---- the install itself (the same runner Getting started uses) ----------------------------------------------
+  const { runner, finisher } = await d.makeInstall({ dir });
+  const open = {};
+  const res = await runner.run({
+    onEvent: (e) => {
+      if (e.type === 'log') { emit({ type: 'log', line: e.line }); return; }
+      if (e.type !== 'stage') return;
+      const s = FOLD[e.id]; if (!s) return;
+      if (e.status === 'running') { if (!open[s]) { open[s] = true; stage(s, 'running'); } return; }
+      if (e.status === 'ok' && (e.id === 'build' || e.id === 'start' || e.id === 'health')) { stage(s, 'ok', e.ms != null ? { ms: e.ms } : {}); open[s] = false; }
+    }
+  });
+  if (!res.ok) {
+    const failed = FOLD[res.failedStage] || res.failedStage || 'download';
+    if (res.interrupted) return fail(failed, 'interrupted', `Run ${AGAIN} again; finished steps are kept.`);
+    const next = [res.cause?.next || res.cause?.fix, res.hint || 'Finished steps are kept.', `Then run: ${AGAIN}`].filter(Boolean).join(' ');
+    return fail(failed, res.error || 'the installer failed', next, { logPath: res.logPath, ...(res.dashboardUrl ? { dashboardUrl: res.dashboardUrl } : {}) });
+  }
+
+  // ---- owner account, sign-in, vault, link ---------------------------------------------------------------------
+  stage('owner', 'running');
+  const made = await finisher.createOwner({ email, password });
+  if (!made.ok) {
+    return fail('owner', made.error || 'the owner account was not created',
+      made.existed ? 'An owner already exists on this server. Sign in with: quox login' : `The server is running. Create the owner with: quox setup`, { dashboardUrl: res.dashboardUrl, logPath: res.logPath });
+  }
+  const signed = await finisher.signIn({ email, password });
+  if (!signed.ok) return fail('owner', `owner created, but sign-in failed: ${signed.error}`, 'Sign in with: quox login', { dashboardUrl: res.dashboardUrl, logPath: res.logPath });
+  stage('owner', 'ok', { detail: email });
+  stage('vault', 'skip', { detail: 'no AI key was given here', next: 'Add one with: quox provider connect' });
+  const link = await finisher.loginLink(res.dashboardUrl);
+  if (!link.ok) return fail('link', link.error || 'could not create the sign-in link', `Open ${res.dashboardUrl || 'https://localhost:3000'} and sign in with ${email}.`, { dashboardUrl: res.dashboardUrl, logPath: res.logPath });
+  stage('link', 'ok', { ttlSeconds: link.ttlSeconds, linkIssued: true, ...(printLink ? {} : { linkHow: LINK_HOW }) });
+  const done = { ok: true, dashboardUrl: res.dashboardUrl, link: link.url, installDir: runner.installDir, logPath: res.logPath };
+  const { link: liveLink, ...safe } = done;
+  emit({ type: 'result', ...(printLink ? done : { ...safe, linkIssued: true, linkHow: LINK_HOW }) });
+  return done;
+}

package/lib/server/status.js

@@ -4,6 +4,7 @@
  */
 import { readFileSync, writeFileSync, mkdirSync, appendFileSync, renameSync } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { X509Certificate } from 'node:crypto';
 import { readInstalled } from './install.js';
 
 const STATE_FILE = 'lifecycle-state.json';
@@ -67,6 +68,18 @@ async function getJson(url, fetchImpl, timeout = 3000) {
   } catch (e) { return { ok: false, error: e?.cause?.code || e?.message || 'no answer' }; }
 }
 
+/**
+ * H3: the SHA256 fingerprint of the certificate the edge serves (ssl/quox.crt in the checkout), in the same format
+ * as the `quox connect` card, so the two can be compared by eye or by script. Never throws.
+ */
+export function certFingerprint(repoDir, { read = readFileSync } = {}) {
+  const file = join(repoDir || '', 'ssl', 'quox.crt');
+  try {
+    const c = new X509Certificate(read(file));
+    return { ok: true, file, fingerprint256: c.fingerprint256, validTo: c.validTo };
+  } catch (e) { return { ok: false, file, error: e?.code === 'ENOENT' ? 'no certificate file' : 'could not read the certificate' }; }
+}
+
 /** The running build, from the collector's public /version. */
 export async function runningVersion(collectorUrl, fetchImpl = globalThis.fetch) {
   const r = await getJson(`${collectorUrl.replace(/\/+$/, '')}/version`, fetchImpl);
@@ -99,7 +112,7 @@ export async function gatherStatus({ install, sys, fetchImpl = globalThis.fetch,
   const hist = backups ? readHistory(backups) : [];
   const lastUpdate = [...hist].reverse().find((e) => e.op === 'update' || e.op === 'rollback') || null;
   const state = backups ? readState(backups) : null;
-  return { install, installed, running, services: svc, disk, http, lastUpdate, inFlight: state && state.status === 'running' ? state : null };
+  return { install, installed, running, services: svc, disk, http, cert: certFingerprint(install.repoDir), lastUpdate, inFlight: state && state.status === 'running' ? state : null };
 }
 
 const svcIcon = (s) => (s.state === 'running' ? (s.health && s.health !== 'healthy' ? '⚠' : '✔') : '✖');
@@ -113,6 +126,7 @@ export function statusRows(st) {
   out.push(row('Version', `${i.release || '? no VERSION file'}${i.tag ? ` (${i.tag})` : ''} · checkout ${i.commit || '?'}${i.dirty ? ' · local changes' : ''}`));
   const rv = st.running;
   out.push(row('Running', rv.ok ? `${rv.commit || '?'}${rv.stamped === false ? ' (unstamped build)' : ''}${rv.commit && i.commit && !String(rv.commit).startsWith(i.commit) && !String(i.commit).startsWith(rv.commit) ? ' · differs from the checkout' : ''}` : `? ${rv.error}`));
+  if (st.cert) out.push(row('Certificate', st.cert.ok ? `SHA256 ${st.cert.fingerprint256} · valid to ${st.cert.validTo} (compare with the card \`quox connect\` shows)` : `? ${st.cert.error} (${st.cert.file})`));
   for (const h of st.http) out.push(row(`${h.ok ? '✔' : '✖'} ${h.name}`, `${h.url} · ${h.detail} · ${h.ms}ms`));
   if (!st.services.ok) out.push(row('✖ Services', `? ${st.services.error}`));
   else {

package/lib/toolOutputShape.js

@@ -270,6 +270,59 @@ function smallTopFields(body, found) {
   return Object.keys(out).length ? out : null;
 }
 
+
+/**
+ * OVERSIZED-IDS: the oversized summary used to carry only a sample of whole rows, which a big row (logs, blobs)
+ * pushes out entirely, so the model lost every id/name and answered from another tool (keeper_backup_list,
+ * bob_log_tail). id_index keeps the first ID_INDEX_ROWS rows of every list (top level, or under a top key) reduced
+ * to identifier/status fields, inside ID_INDEX_BUDGET chars in total, and says how many rows were left out.
+ */
+export const ID_INDEX_ROWS = 20;
+export const ID_INDEX_BUDGET = 6000;
+const ID_FIELD_RE = /^(id|name|title|status|state|created_at|started_at|key|host|host_id|hostname|slug|label|kind|type)$|_id$/i;
+const ID_VALUE_MAX = 80;
+
+function idRow(row) {
+  if (!isObj(row)) return (row === null || typeof row === 'object') ? null : (typeof row === 'string' ? row.slice(0, ID_VALUE_MAX) : row);
+  const r = {};
+  for (const [k, v] of Object.entries(row)) {
+    if (BLOCKED.has(k) || !ID_FIELD_RE.test(k)) continue;
+    if (v === null || typeof v === 'object') continue;
+    r[k] = typeof v === 'string' && v.length > ID_VALUE_MAX ? `${v.slice(0, ID_VALUE_MAX)}...` : v;
+  }
+  return r;
+}
+
+function idIndex(body, found) {
+  const lists = [];
+  if (Array.isArray(body)) lists.push(['(root)', body]);
+  else if (isObj(body)) {
+    for (const [k, v] of Object.entries(body)) if (!BLOCKED.has(k) && Array.isArray(v) && v.length) lists.push([k, v]);
+    if (!lists.length && found && found.path) lists.push([found.path, found.list]);
+  }
+  if (!lists.length) return null;
+  // the main list first, then the rest by size
+  const mainPath = found && found.path;
+  lists.sort((a, b) => ((b[0] === mainPath) - (a[0] === mainPath)) || b[1].length - a[1].length);
+  const out = {};
+  let used = 0;
+  for (const [path, list] of lists.slice(0, 8)) {
+    const rows = [];
+    for (const it of list.slice(0, ID_INDEX_ROWS)) {
+      const r = idRow(it);
+      if (r === null || (isObj(r) && !Object.keys(r).length)) continue;
+      const n = jsonLen(r) + 2;
+      if (used + n + 120 > ID_INDEX_BUDGET) break;
+      rows.push(r);
+      used += n;
+    }
+    if (!rows.length) continue;
+    used += 120;
+    out[path] = { total: list.length, shown: rows.length, omitted: list.length - rows.length, rows };
+  }
+  return Object.keys(out).length ? out : null;
+}
+
 export function capInline(value, { maxChars = INLINE_MAX_CHARS } = {}) {
   const size = jsonLen(value);
   if (size <= maxChars) return { value, capped: false };
@@ -299,6 +352,8 @@ export function capInline(value, { maxChars = INLINE_MAX_CHARS } = {}) {
     : `--select '${lp ? `${lp}[field=value].name` : '[0]'}', --select 'count(${lp || ''})' or --select '${lp ? `${lp}[*].field` : '[*].field'}'`;
   const next = `Result is ${fullKb} KB, too large to show whole, so this is the --summary view. For the exact part you need, run the same quox tool exec again with ${example} (or --summary --limit N for a bigger sample)${via ? `; the list is inside ${via}` : ''}. Never read or post-process a saved output with a shell.`;
   const head = { oversized: true, full_size_kb: fullKb, next, top_keys: isObj(body) ? Object.keys(body).slice(0, 40) : undefined };
+  const idx = idIndex(body, found);
+  if (idx) head.id_index = idx;
   const extra = smallTopFields(body, found);
   for (const limit of [DEFAULT_SAMPLE, 5, 3, 1, 0]) {
     const s = summarize(body, { limit });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quoxcli",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Quox: the conversational front door to your self-hosted AI agent control plane",
   "type": "module",
   "bin": {
@@ -53,6 +53,7 @@
   "files": [
     "bin/",
     "lib/",
+    "vendor/",
     "!lib/**/*.test.js",
     "!lib/**/*.test.jsx",
     "!lib/**/__tests__/",
@@ -60,6 +61,7 @@
     "!lib/core/websiteSession.js",
     "!lib/quoxon/whatsnew.md",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "repository": {
@@ -67,7 +69,7 @@
     "url": "git+https://github.com/quoxai/quoxcore.git",
     "directory": "cli"
   },
-  "homepage": "https://cli.quox.ai",
+  "homepage": "https://quox.ai/cli",
   "bugs": {
     "url": "https://github.com/quoxai/quoxcore/issues"
   },

package/vendor/dragonlab/SOURCE

@@ -0,0 +1,4 @@
+repo: quoxai/dragonlab
+commit: a4dda5ef12c417689768664022b8de1245794c56
+branch: integration/companions-vulcan-quoxperticus
+files: 66

package/vendor/dragonlab/design/cipher/v1/cipher-master.svg

@@ -0,0 +1,46 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 480">
+<title>Cipher — network operations, electric-blue listening dragon</title>
+<g id="wings">
+<path id="far-sail" fill="#185a9b" d="M 352 288 Q 363 205 445 105 L 430 222 L 484 181 L 451 285 Z"/>
+<path id="near-sail" fill="#297cc4" d="M 398 302 Q 450 189 564 144 L 531 227 L 579 209 L 537 272 L 572 272 L 483 329 Z"/>
+<path id="sail-ribs" fill="none" stroke="#81ddff" stroke-width="8" d="M 398 302 L 564 144 L 481 272 L 537 272 M 352 288 L 445 105 L 398 246"/>
+</g>
+<g id="tail">
+<path id="tail-ribbon" fill="#2988da" d="M 475 305 C 538 278 625 287 658 327 C 696 378 630 409 589 387 C 547 366 564 328 613 313 C 673 294 711 263 695 218 Q 683 189 654 197 Q 691 201 677 234 C 663 262 600 266 559 295 C 502 337 525 398 576 419 C 644 446 731 395 696 332 C 663 266 548 253 469 275 Z"/>
+<path id="tail-edge" fill="none" stroke="#9aefff" stroke-width="7" d="M 491 294 C 554 274 641 289 665 335 C 686 374 637 404 594 384 M 613 313 C 673 294 711 263 695 218"/>
+<path id="tail-fin" fill="#76dbfb" d="M 688 226 L 641 221 L 658 202 L 635 180 Q 688 178 699 215 Z"/>
+</g>
+<g id="body">
+<path id="torso" fill="#287fc3" d="M 288 246 C 328 225 374 246 402 266 C 445 267 494 287 510 317 Q 524 356 476 367 L 331 354 Q 282 335 278 291 Z"/>
+<path id="silver-belly" fill="#bddceb" d="M 291 265 Q 346 301 426 308 L 480 340 Q 405 365 336 337 Q 295 319 291 265 Z"/>
+<path id="belly-plates" fill="none" stroke="#477b9d" stroke-width="5" d="M 320 295 L 315 325 M 348 306 L 344 339 M 379 311 L 376 345 M 410 315 L 408 348"/>
+<path id="rear-legs" fill="#2367a8" d="M 455 314 Q 496 299 505 338 L 495 386 L 526 399 L 525 412 L 468 412 L 469 362 L 443 347 Z M 388 329 L 405 376 L 435 391 L 429 405 L 382 402 L 366 345 Z"/>
+<path id="front-legs" fill="#409bde" d="M 298 290 Q 323 283 332 307 L 322 378 L 349 400 L 345 416 L 293 415 Q 283 409 290 390 L 291 330 Z M 265 288 L 281 312 L 265 378 L 280 393 L 270 408 L 231 405 L 243 371 Z"/>
+<path id="talons" fill="#e8f7ff" d="M 296 403 L 289 417 L 305 412 L 313 401 L 311 417 L 327 412 L 335 404 L 337 417 L 350 411 M 474 400 L 466 413 L 483 410 L 490 399 L 490 414 L 507 410 L 515 400 L 519 413 L 531 408 M 235 393 L 230 406 L 247 402 L 255 392 L 255 408 L 272 401"/>
+<path id="dorsal-fins" fill="#7ae6ff" d="M 330 249 L 341 224 L 356 258 L 374 238 L 386 269 L 409 251 L 421 276 L 445 260 L 457 289"/>
+</g>
+<g id="neck">
+<path id="neck-mass" fill="#358bd1" d="M 230 180 Q 281 156 310 193 Q 316 231 349 273 Q 305 315 263 281 Q 271 239 230 180 Z"/>
+<path id="neck-silver" fill="#d1e8f4" d="M 237 201 Q 259 214 274 233 Q 281 259 274 282 Q 295 297 314 284 Q 294 249 288 221 Z"/>
+</g>
+<g id="head">
+<path id="antenna-far" fill="none" stroke="#9eeeff" stroke-width="9" d="M 233 127 Q 225 82 263 46 L 283 22"/>
+<path id="antenna-near" fill="none" stroke="#d5f5ff" stroke-width="10" d="M 278 130 Q 286 74 332 55 L 366 33"/>
+<path id="ear-far" fill="#5dc8f5" d="M 216 146 L 166 106 L 185 161 L 165 172 L 218 179 Z"/>
+<path id="head-mass" fill="#469ee0" d="M 203 143 Q 217 112 263 116 Q 301 117 312 152 Q 324 189 295 217 Q 255 245 216 218 L 192 188 Z"/>
+<path id="ear-near" fill="#70d8fa" d="M 291 153 L 354 113 L 332 157 L 362 150 L 334 185 L 347 189 L 302 205 Z"/>
+<path id="ear-cut" fill="none" stroke="#2978bb" stroke-width="5" d="M 305 169 L 337 139 M 309 182 L 336 168"/>
+<path id="muzzle" fill="#9bd7ed" d="M 208 181 Q 187 177 178 190 Q 166 208 191 220 Q 229 238 266 218 L 270 204 Q 237 215 208 181 Z"/>
+<path id="nose" fill="#080d19" d="M 185 194 Q 195 186 202 194 Q 197 202 185 199 Z"/>
+<path id="smile" fill="none" stroke="#164668" stroke-width="5" d="M 185 211 Q 218 231 255 214"/>
+<path id="brow" fill="none" stroke="#a6edff" stroke-width="6" d="M 213 143 Q 230 130 245 143 M 259 140 Q 280 125 295 141"/>
+</g>
+<g id="eyes">
+<path id="far-eye-socket" fill="#080d19" d="M 210 154 Q 223 138 240 149 Q 253 164 243 184 Q 222 197 211 177 Z"/>
+<path id="far-eye-white" fill="#ffffff" d="M 216 156 Q 227 145 237 155 Q 246 166 238 179 Q 224 188 216 174 Z"/>
+<path id="far-pupil" fill="#080d19" d="M 225 166 C 225 157 234 157 234 166 C 234 175 225 175 225 166 Z"/>
+<path id="near-eye-socket" fill="#080d19" d="M 253 153 Q 272 134 293 149 Q 310 168 295 190 Q 271 204 254 183 Z"/>
+<path id="near-eye-white" fill="#ffffff" d="M 260 155 Q 275 142 289 154 Q 301 169 290 184 Q 274 194 261 179 Z"/>
+<path id="near-pupil" fill="#080d19" d="M 272 168 C 272 157 283 157 283 168 C 283 179 272 179 272 168 Z"/>
+</g>
+</svg>

package/vendor/dragonlab/design/cipher/v2/character.mjs

@@ -0,0 +1,49 @@
+import {renderSvgRig} from '../../../factory/svg-rig.mjs';
+const pulse=(t,a,b)=>t<=a||t>=b?0:Math.sin(Math.PI*(t-a)/(b-a))**2;
+const ease=x=>{x=Math.max(0,Math.min(1,x));return x*x*(3-2*x);};
+export const CIPHER_CLIPS=[{id:'idle',title:'Listening',duration:12000},{id:'attach',title:'Link Up',duration:3200},{id:'inspect',title:'Following Traffic',duration:3600},{id:'trace',title:'Trace Route',duration:4800},{id:'delay',title:'Delayed Hop',duration:4800},{id:'broken',title:'Broken Link',duration:4800},{id:'restored',title:'Route Restored',duration:4800}];
+export const STORY=[['attach',3200],['idle',1600],['inspect',3600],['trace',4800],['delay',4800],['broken',4800],['restored',4800],['idle',2400]];
+export const STORY_DURATION=STORY.reduce((s,b)=>s+b[1],0);
+export function poseRig(rig,t,scene){
+ const cycle=t%12000,arrival=scene==='attach'&&t<3200;
+ const attention=arrival?pulse(t,0,2800):pulse(cycle,600,3400);
+ const fin=arrival?pulse(t,500,2900):pulse(cycle,2600,4300);
+ const tail=arrival?pulse(t,1000,3200):pulse(cycle,6200,10500);
+ const paths=rig.paths.map(p=>({...p,polygons:p.polygons.map(poly=>poly.map(([x,y])=>{
+  if(p.id.endsWith('-pupil'))x+=(scene==='inspect'?Math.sin(t/700):attention)*2;
+  if(p.group==='head'||p.group==='eyes'){x+=attention*3;y-=attention*3;if(p.id.startsWith('ear-'))y-=fin*4*ease((x-290)/65);if(p.id.startsWith('antenna-'))x+=fin*4*ease((130-y)/100);}
+  if(p.group==='neck'){const w=ease((290-y)/100);x+=attention*3*w;y-=attention*3*w;}
+  if(p.group==='wings'){const w=ease((300-y)/170);x-=fin*3*w;y+=fin*3*w;}
+  if(p.group==='tail'){const w=ease((x-490)/150);x-=tail*4*w;y+=tail*4*w*Math.sin((x-490)/70);}
+  return [x,y];
+ }))}));
+ const byId=new Map(paths.map(p=>[p.id,p]));
+ return {...rig,paths,bounds:{left:rig.bounds.left-7,top:rig.bounds.top-7,right:rig.bounds.right+7,bottom:rig.bounds.bottom+7},eyes:rig.eyes.map(e=>({...e,socket:byId.get(e.socket.id),white:byId.get(e.white.id),pupil:byId.get(e.pupil.id)}))};
+}
+function route(frame,t,scene,mono){
+ const cols=frame[0].length,rows=frame.length,y=1;
+ const nodes=[.53,.69,.85].map(f=>Math.round(f*(cols-1)));
+ let effectCells=0;
+ const put=(x,ch,rgb)=>{if(x<1||x>=cols-1||y>=rows-1||frame[y][x].ch!==' ')return;frame[y][x]={ch,rgb:mono?null:rgb,bg:null};effectCells++;};
+ const cyan=[103,226,255],amber=[255,194,76],red=[255,100,103];
+ const p=Math.min(1,t/4000),blocked=scene==='broken',delayed=scene==='delay';
+ nodes.forEach((x,i)=>put(x,'⠿',(i===1&&(blocked||delayed))?(blocked?red:amber):cyan));
+ for(let x=nodes[0];x<=nodes[2];x++){if(blocked&&x>nodes[1]&&x<nodes[1]+3)continue;put(x,'⠒',cyan);}
+ // Replace our route cells only; never overwrite original art.
+ const set=(x,ch,rgb)=>{if(x>=nodes[0]&&x<=nodes[2]&&['⠒','⠿'].includes(frame[y][x].ch))frame[y][x]={ch,rgb:mono?null:rgb,bg:null};};
+ let progress=p;if(delayed)progress=p<.3?p/.6:p<.7?.5:.5+(p-.7)/.6;if(blocked)progress=Math.min(.5,p);
+ const x=Math.round(nodes[0]+(nodes[2]-nodes[0])*Math.min(1,progress));
+ set(x,'⣿',blocked?red:delayed&&progress===.5?amber:[255,255,255]);
+ return effectCells;
+}
+export function renderCipher(rig,scene='idle',ms=0,options={}){
+ const clip=CIPHER_CLIPS.find(c=>c.id===scene);if(!clip)return {ok:false,code:'UNKNOWN_CLIP'};
+ if(!Number.isFinite(ms)||ms<0)return {ok:false,code:'INVALID_TIME'};
+ const t=options.still?0:ms;
+ const idleT=scene==='attach'&&t>=3200?t-3200:t;
+ const posed=poseRig(rig,options.still?0:(options.motionTime??idleT),scene==='attach'&&t>=3200?'idle':scene);
+ const r=renderSvgRig(posed,options),power=['trace','delay','broken','restored'].includes(scene);
+ const effectCells=power?route(r.frame,options.still?2400:t,scene,options.mono):0;
+ return {...r,scene,clip:clip.title,caption:power?clip.title+' · simulated network state':'Listening to the network.',effectCells};
+}
+export function renderStory(rig,ms,options={}){let t=options.still?0:Math.min(ms,STORY_DURATION-1);for(const [scene,duration]of STORY){if(t<duration)return renderCipher(rig,scene,t,{...options});t-=duration;}}

package/vendor/dragonlab/design/cipher/v2/review.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import {parseSvgRig} from '../../../factory/svg-rig.mjs';
+import {renderCipher,CIPHER_CLIPS} from './character.mjs';
+import {artSlot,composeMessage} from '../../lucid/recovery/layout.mjs';
+import {cellsToAnsi} from '../../../vendor/quox-dragon/qart.js';
+const args=process.argv.slice(2),values=new Set(['--cols','--rows','--terminal-cols','--terminal-rows','--message','--scene','--at']);
+for(let i=0;i<args.length;i++){
+ if(values.has(args[i])){if(!args[i+1]||args[i+1].startsWith('--'))throw Error('Missing option value');i++;}
+ else if(!['--large','--mono','--help','--watch','--attach','--intro','--still','--list'].includes(args[i]))throw Error('Unknown option: '+args[i]);
+}
+const value=(name,fallback)=>args.includes(name)?args[args.indexOf(name)+1]:fallback;
+if(args.includes('--help')){console.log('Cipher V2 acting studio. --watch --attach --intro --still --scene ID --at MS --list --large --mono --message TEXT --cols N --rows N --terminal-cols N --terminal-rows N');process.exit(0);}
+if(args.includes('--list')){console.log(CIPHER_CLIPS.map(c=>c.id+' · '+c.title).join('\n'));process.exit(0);}
+const w=Number(value('--terminal-cols',process.stdout.columns||80)),h=Number(value('--terminal-rows',process.stdout.rows||24));
+if(!Number.isSafeInteger(w)||!Number.isSafeInteger(h)||w<1||h<1)throw Error('Invalid terminal size');
+const slot=artSlot(w,h),large=args.includes('--large')||args.includes('--intro'),explicit=large||args.includes('--cols')||args.includes('--rows');
+const cols=Number(value('--cols',large?Math.min(120,w-4):Math.min(39,slot.cols))),rows=Number(value('--rows',large?Math.min(36,h-4):Math.min(11,slot.rows)));
+const message=value('--message','CIPHER\nOn guard.');
+if(!slot.showArt&&!explicit){console.log(composeMessage(null,message,{terminalCols:w}).join('\n'));}
+else{
+ if(cols>w-4||rows>h-2)throw Error('Requested art exceeds terminal margins');
+ const rig=parseSvgRig(await fs.readFile(new URL('../v1/cipher-master.svg',import.meta.url),'utf8'));
+ const opts={cols,rows,mono:args.includes('--mono'),still:args.includes('--still'),deck:large};
+ const scene=value('--scene',args.includes('--attach')?'attach':'idle');
+ const r=renderCipher(rig,scene,Number(value('--at',0)),opts);
+ if(!r.ok)throw Error(r.code);
+ if(args.includes('--watch')||args.includes('--attach')||args.includes('--intro')){
+  const {watch}=await import('./watch.mjs');
+  await watch(rig,opts,{terminalCols:w,terminalRows:h,large,scene:args.includes('--scene')||args.includes('--attach')?scene:null,arrival:args.includes('--attach'),message:args.includes('--message')?message:null});
+ }else
+ console.log((large?[...cellsToAnsi(r.frame),...composeMessage(null,message,{terminalCols:w})]:composeMessage(r.frame,message,{terminalCols:w})).join('\n'));
+}

package/vendor/dragonlab/design/cipher/v2/watch.mjs

@@ -0,0 +1,56 @@
+import {performance} from 'node:perf_hooks';
+import {CIPHER_CLIPS,renderCipher,renderStory,STORY_DURATION} from './character.mjs';
+import {composeMessage} from '../../lucid/recovery/layout.mjs';
+import {cellsToAnsi} from '../../../vendor/quox-dragon/qart.js';
+
+/** One bounded performance. No alternate screen or full-screen clearing. */
+export async function watch(paths,options,config){
+  if(!process.stdout.isTTY||!process.stdin.isTTY)throw new Error('--watch/--intro needs an interactive terminal. Use --scene and --at for snapshots.');
+  const {terminalCols,terminalRows,scene,large,message}=config;
+  const clip=scene?CIPHER_CLIPS.find(c=>c.id===scene):null;
+  const duration=(config.arrival&&options.deck?3200:clip?.duration??STORY_DURATION)+(config.arrival?6000:0);
+  const realCols=process.stdout.columns,realRows=process.stdout.rows;
+  const start=performance.now();
+  const render=t=>{
+    const r=scene?renderCipher(paths,scene,t,options):renderStory(paths,t,options);
+    if(!r?.ok)throw new Error(r?.code??'Invalid story frame');
+    const caption=message??'CIPHER · '+r.clip+'\n'+r.caption;
+    return large?[...cellsToAnsi(r.frame),...caption.split('\n')]:composeMessage(r.frame,caption,{terminalCols});
+  };
+  // Reserve enough lines for captions too; keep within the real terminal.
+  const height=options.rows+3;
+  if(height>=terminalRows)throw new Error('Animation needs room for its caption; reduce --rows.');
+  let ended=false,drawn=false,timer,resolveDone,rejectDone;
+  const wasRaw=Boolean(process.stdin.isRaw);
+  const done=new Promise((resolve,reject)=>{resolveDone=resolve;rejectDone=reject;});
+  const cleanup=(error)=>{
+    if(ended)return;ended=true;clearInterval(timer);
+    process.stdin.off('data',key);process.stdout.off('resize',resized);
+    process.off('SIGINT',sigint);process.off('SIGTERM',sigterm);
+    process.stdin.setRawMode(wasRaw);process.stdin.pause();
+    if(drawn)process.stdout.write(`\x1b[${height}B\r`);
+    process.stdout.write('\x1b[0m\x1b[?25h');
+    error?rejectDone(error):resolveDone();
+  };
+  const key=data=>{if(data.includes(3)||data.toString().includes('q'))cleanup();};
+  const sigint=()=>cleanup(),sigterm=()=>cleanup();
+  const resized=()=>cleanup(new Error('Terminal resized; rerun for the new art slot.'));
+  try{
+    process.stdin.setRawMode(true);process.stdin.resume();process.stdin.on('data',key);
+    process.stdout.on('resize',resized);process.on('SIGINT',sigint);process.on('SIGTERM',sigterm);
+    process.stdout.write('\x1b[?25l');
+    // Allocate the block once; each frame replaces only these lines.
+    process.stdout.write('\n'.repeat(height)+`\x1b[${height}A`);drawn=true;
+    const tick=()=>{
+      try{
+        if(process.stdout.columns!==realCols||process.stdout.rows!==realRows)return resized();
+        const t=Math.min(performance.now()-start,duration-1),lines=render(t);
+        if(lines.length>height)throw new Error('Message exceeds the animation block; use a shorter message or a static preview.');
+        process.stdout.write(Array.from({length:height},(_,i)=>'\r\x1b[2K'+(lines[i]??'')+'\n').join('')+`\x1b[${height}A`);
+        if(performance.now()-start>=duration)cleanup();
+      }catch(e){cleanup(e);}
+    };
+    tick();if(!ended)timer=setInterval(tick,1000/6);
+    await done;
+  }catch(e){cleanup(e);await done;}
+}

package/vendor/dragonlab/design/drago/v1/character.mjs

@@ -0,0 +1,19 @@
+import {renderSvgRig} from '../../../factory/svg-rig.mjs';
+import {flattenPath} from '../../stage3/svg-coverage.js';
+export const DRAGO_CLIPS=Object.freeze(['idle','active']);
+const glare={
+ 'far-eye-white':'M 325 113 L 358 128 L 357 141 Q 336 138 325 124 Z',
+ 'near-eye-white':'M 382 128 L 424 111 L 422 126 Q 405 139 383 141 Z',
+ 'far-pupil':'M 341 128 C 341 122 348 122 348 128 C 348 134 341 134 341 128 Z',
+ 'near-pupil':'M 398 128 C 398 122 405 122 405 128 C 405 134 398 134 398 128 Z'
+};
+export function poseDrago(rig,scene='idle'){
+ if(!DRAGO_CLIPS.includes(scene))throw RangeError('Unknown Drago scene: '+scene);
+ const paths=rig.paths.map(p=>scene==='active'&&glare[p.id]?{...p,polygons:flattenPath(glare[p.id])}:p);
+ const byId=new Map(paths.map(p=>[p.id,p]));
+ return {...rig,paths,eyes:rig.eyes.map(e=>({...e,socket:byId.get(e.socket.id),white:byId.get(e.white.id),pupil:byId.get(e.pupil.id)}))};
+}
+export function renderDrago(rig,scene='idle',ms=0,options={}){
+ if(!Number.isFinite(ms)||ms<0)throw RangeError('Invalid time');
+ return {...renderSvgRig(poseDrago(rig,scene),options),scene,staticStudy:true,caption:'DRAGO\n'+(scene==='active'?'Active glare study.':'On guard.')};
+}

package/vendor/dragonlab/design/drago/v1/drago-master.svg

@@ -0,0 +1,56 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 480">
+<title>Drago — crimson engagement guardian, shield-bearing terminal master</title>
+<g id="wings">
+<path id="left-wing" fill="#922837" d="M 349 289 C 286 246 246 199 224 146 Q 208 115 183 103 C 197 184 158 282 109 365 Q 156 334 181 348 Q 218 308 246 340 Q 275 308 302 350 Z"/>
+<path id="left-wing-ribs" fill="none" stroke="#ef5350" stroke-width="8" d="M 349 289 Q 240 207 183 103 M 183 103 Q 201 242 109 365 M 204 178 Q 235 272 181 348 M 232 217 L 246 340"/>
+<path id="right-wing" fill="#6d2433" d="M 445 266 Q 520 206 566 108 Q 585 80 605 83 C 585 165 628 273 687 361 Q 647 333 623 349 Q 589 305 563 332 Q 529 301 501 347 Z"/>
+<path id="right-wing-ribs" fill="none" stroke="#d34243" stroke-width="9" d="M 445 266 Q 546 167 605 83 M 605 83 Q 583 203 687 361 M 584 153 Q 554 234 623 349 M 556 194 L 563 332"/>
+<path id="wing-claws" fill="#ffc28e" d="M 180 121 Q 162 93 192 86 L 183 103 Z M 593 100 Q 600 69 621 74 L 605 91 Z"/>
+</g>
+<g id="body">
+<path id="haunches" fill="#b53b43" d="M 346 250 C 293 266 267 326 278 380 Q 291 422 342 420 L 476 420 Q 536 416 543 372 C 544 311 493 259 450 242 Z"/>
+<path id="neck" fill="#c34143" d="M 348 146 C 335 205 327 243 310 294 Q 382 324 473 285 C 438 245 442 195 432 146 Z"/>
+<path id="throat" fill="#e9ac8a" d="M 361 166 Q 358 233 339 280 Q 388 307 435 278 Q 414 224 410 166 Z"/>
+<path id="throat-plates" fill="none" stroke="#79303b" stroke-width="6" d="M 359 199 Q 386 211 415 197 M 356 221 Q 387 235 420 221 M 350 245 Q 387 258 426 245 M 344 267 Q 388 281 433 267"/>
+<path id="spine" fill="#ff6048" d="M 433 156 L 473 160 L 447 180 L 485 197 L 448 206 L 481 230 L 451 232 L 491 262 L 464 260 L 510 287 L 481 288 Z"/>
+<path id="feet" fill="#bd4249" d="M 301 357 Q 278 379 244 398 Q 230 420 262 428 L 329 428 L 344 383 Z M 481 362 Q 518 375 548 407 Q 552 428 523 429 L 463 429 L 450 384 Z"/>
+<path id="foot-talons" fill="#f5c59d" d="M 251 410 L 243 430 L 267 422 L 278 409 L 274 431 L 295 421 L 306 409 L 307 430 L 326 421 M 477 410 L 467 431 L 489 423 L 500 411 L 500 433 L 520 423 L 531 414 L 535 431 L 548 424"/>
+</g>
+<g id="head">
+<path id="far-horn" fill="#f5b47f" d="M 343 107 C 309 93 296 63 290 27 Q 320 65 365 70 Z"/>
+<path id="near-horn" fill="#ffc18b" d="M 410 91 C 459 81 482 50 502 18 C 499 64 462 104 430 121 Z"/>
+<path id="skull" fill="#d84a49" d="M 323 112 Q 320 79 362 75 Q 412 65 437 101 L 444 145 Q 425 184 380 188 Q 329 183 312 149 Z"/>
+<path id="brow-armour" fill="#f06956" d="M 324 104 L 349 78 L 366 86 L 386 62 L 401 84 L 426 79 L 438 106 L 395 121 L 365 118 Z"/>
+<path id="cheek-blades" fill="#ff7458" d="M 434 119 L 478 100 L 453 132 L 480 134 L 447 152 L 461 168 L 425 169 Z M 321 119 L 294 105 L 303 132 L 288 137 L 315 153 Z"/>
+<path id="muzzle" fill="#e0715b" d="M 328 145 Q 357 135 379 150 Q 401 142 422 151 L 414 174 Q 379 196 332 178 L 313 164 Z"/>
+<path id="nose" fill="#080d19" d="M 329 153 L 341 151 L 336 158 Z M 400 153 L 411 151 L 404 159 Z"/>
+<path id="mouth" fill="none" stroke="#080d19" stroke-width="5" d="M 327 172 Q 370 184 414 168"/>
+<path id="fangs" fill="#fff0d4" d="M 337 176 L 346 193 L 350 179 Z M 398 176 L 402 188 L 409 172 Z"/>
+</g>
+<g id="shield">
+<path id="shield-outer" fill="#ff7058" d="M 386 260 Q 430 289 492 294 L 486 350 Q 471 401 390 440 Q 312 401 296 350 L 290 294 Q 347 290 386 260 Z"/>
+<path id="shield-dark" fill="#080d19" d="M 386 273 Q 435 301 478 303 L 473 348 Q 456 391 390 425 Q 327 391 309 348 L 304 303 Q 352 298 386 273 Z"/>
+<path id="shield-left" fill="#bd3841" d="M 385 285 L 385 411 Q 333 381 321 346 L 317 314 Q 355 307 385 285 Z"/>
+<path id="shield-right" fill="#842d3d" d="M 394 286 Q 431 309 466 314 L 461 345 Q 448 382 394 411 Z"/>
+<path id="shield-rune" fill="none" stroke="#ffc999" stroke-width="8" d="M 360 334 L 389 354 L 418 334 M 389 354 L 389 386"/>
+</g>
+<g id="hands">
+<path id="left-arm" fill="#d74b4a" d="M 315 264 Q 279 270 283 298 L 317 321 L 337 304 L 312 288 Z"/>
+<path id="right-arm" fill="#ba3c43" d="M 454 260 Q 501 265 501 296 L 464 320 L 442 305 L 475 286 Z"/>
+<path id="gripping-talons" fill="#ffe0b2" d="M 311 297 Q 322 286 333 301 L 330 321 L 323 305 L 318 323 Z M 329 297 Q 342 291 348 306 L 343 323 L 338 307 Z M 445 297 Q 457 290 462 303 L 456 324 L 451 308 Z M 464 297 Q 478 288 482 302 L 473 322 L 471 305 Z"/>
+</g>
+<g id="tail">
+<path id="tail-coil" fill="#aa3541" d="M 501 350 C 554 351 608 371 605 405 C 601 440 507 464 392 460 C 271 458 190 439 180 406 Q 169 376 199 359 Q 178 392 232 407 C 326 438 473 431 535 411 Q 564 393 502 384 Z"/>
+<path id="tail-rim" fill="none" stroke="#ed5a50" stroke-width="9" d="M 199 359 Q 178 392 232 407 C 326 438 473 431 535 411"/>
+<path id="tail-tip" fill="#ff815e" d="M 201 359 L 169 346 L 180 379 L 162 390 L 195 395 Q 181 376 201 359 Z"/>
+<path id="tail-scutes" fill="none" stroke="#752939" stroke-width="6" d="M 226 410 L 218 434 M 264 420 L 257 444 M 305 428 L 302 453 M 351 434 L 350 458 M 400 435 L 402 459 M 451 432 L 459 457 M 500 425 L 514 449 M 543 410 L 563 432"/>
+</g>
+<g id="eyes">
+<path id="far-eye-socket" fill="#080d19" d="M 321 111 Q 340 100 362 114 L 363 145 Q 336 154 320 134 Z"/>
+<path id="far-eye-white" fill="#ffffff" d="M 326 115 Q 342 109 357 118 L 357 139 Q 338 147 326 131 Z"/>
+<path id="far-pupil" fill="#080d19" d="M 338 127 C 338 117 348 117 348 127 C 348 137 338 137 338 127 Z"/>
+<path id="near-eye-socket" fill="#080d19" d="M 377 115 Q 405 99 429 109 L 429 135 Q 410 153 379 144 Z"/>
+<path id="near-eye-white" fill="#ffffff" d="M 383 119 Q 405 108 423 113 L 423 132 Q 407 146 383 139 Z"/>
+<path id="near-pupil" fill="#080d19" d="M 397 127 C 397 116 408 116 408 127 C 408 138 397 138 397 127 Z"/>
+</g>
+</svg>