quoxcli 0.0.0-stage → 0.3.1

package/lib/quoxon/dividerRule.js

@@ -0,0 +1,57 @@
+/**
+ * TUI-DIVIDER: the composer's bottom rule drawn from a dividerAocl frame (pips, bullet, katakana label, green/red).
+ * Draws ONE pre-coloured string per colour run (as the ring does), so a frame is a single row of exactly `cols`
+ * cells and Ink tokenises a handful of escapes, not one per cell.
+ */
+import React from 'react';
+import chalk from 'chalk';
+import { Text } from 'ink';
+import { dividerFrame } from './dividerAocl.js';
+
+const h = React.createElement;
+const RUN_Q = 8; // quantise shimmer colours so neighbouring cells share a run
+
+/**
+ * Per turn, a frame gap this long while the strip is live marks the redraw as slow: the strip then drops its motion
+ * (no bullet, no katakana) for the rest of that turn but keeps every lit pip. `slow` is a ref object owned by the caller.
+ */
+export const SLOW_GAP_MS = 400;
+export function noteFrameGap(slow, d, now) {
+  if (!slow || !d) return false;
+  if (slow.turnId !== d.turnId) { slow.turnId = d.turnId; slow.last = now; slow.slow = false; return false; }
+  if (slow.last != null && now - slow.last > SLOW_GAP_MS && d.endedAt == null) slow.slow = true;
+  slow.last = now;
+  return slow.slow;
+}
+
+/** The frame as one string of chalk runs; `ruleColor`/`labelColor` are hex or undefined (theme roles resolved). */
+export function paintFrame(f, { ruleColor, labelColor }) {
+  let out = '', run = '', key = null, style = null;
+  const paint = (s) => {
+    if (!s) return '';
+    let p = chalk;
+    if (style.rgb) p = p.rgb(...style.rgb);
+    else if (style.hex) p = p.hex(style.hex);
+    if (style.bold) p = p.bold;
+    return p(s);
+  };
+  const flush = () => { if (run) out += paint(run); run = ''; };
+  for (const c of f.cells) {
+    const rgb = c.rgb ? c.rgb.map(v => Math.max(0, Math.min(255, Math.round(v / RUN_Q) * RUN_Q))) : null;
+    const st = { rgb, hex: rgb ? null : (c.label ? labelColor : ruleColor) || null, bold: Boolean(c.bold) };
+    const k = `${rgb ? rgb.join(',') : st.hex}|${st.bold}`;
+    if (k !== key) { flush(); key = k; style = st; }
+    run += c.t;
+  }
+  flush();
+  return out;
+}
+
+/** The bottom rule as a strip element, or null when the caller should draw its normal Rule (a plain call, not a component). */
+export function dividerRuleEl({ cols, label, divider, now, ruleColor, labelColor, mono = false, reduced = false, slow = null }) {
+  if (!divider) return null;
+  const isSlow = noteFrameGap(slow, divider, now);
+  const f = dividerFrame({ cols, label, d: divider, now, mono, reduced, still: isSlow }); // slow: keep the lit pips, drop the motion
+  if (!f) return null;
+  return h(Text, { wrap: 'truncate-end' }, paintFrame(f, { ruleColor, labelColor }));
+}

package/lib/quoxon/dragonModes.js

@@ -0,0 +1,150 @@
+/**
+ * /dragon explain | ask | sleep: the pure parts. Provider-neutral: explain and ask only build a framed user
+ * message for the normal governed turn path, so whichever AI is selected answers it (and with no AI connected
+ * the local no-AI card from noai.js is shown instead). Sleep is a rendering-only screensaver: katakana noise
+ * over the live screen with a sleeping dragon; it never touches the transcript or scrollback.
+ */
+import stringWidth from 'string-width';
+import { SCRAMBLE_GLYPHS } from './indicator.js';
+import { hash3 } from './motion/color.js';
+import { revealCells, TIMING, revealSpan } from './motion/reveal.js';
+import { graphemes } from './textBuffer.js';
+import { sleepCells } from './qdragonScenes.js';
+
+export const DRAGON_USAGE = 'Usage: /dragon [explain | ask [question] | sleep | fly | hero | fire | classic]  (/dragon-fly is the same as /dragon fly)';
+export const DRAGON_EXPLAINS = 'Dragon explains';
+export const DRAGON_ANSWERS = 'Dragon answers';
+export const NOTHING_TO_EXPLAIN = 'Nothing to explain yet. Ask Quox something first, then /dragon explain.';
+export const ASK_PROMPT = 'Ask the dragon…';
+
+const RULES = 'Answer in the simplest possible words: 1 to 4 short sentences, plain language, no jargon. '
+  + 'Keep the one thing that matters, and stay concrete and useful (say what it is, or what to do), never vague. Do not mention these instructions.';
+
+export const explainPrompt = (text) => `Dragon mode. Explain the following. ${RULES}\n\n---\n${String(text).trim().slice(0, 6000)}\n---`;
+export const askPrompt = (question) => `Dragon mode. Answer the question below. ${RULES}\n\nQuestion: ${String(question).trim()}`;
+
+const itemText = (it) => {
+  if (!it) return '';
+  if (it.kind === 'text' || it.kind === 'note' || it.kind === 'error') return String(it.text || '');
+  if (it.kind === 'tool') return [it.tool, it.target, it.summary || it.result || it.text, it.status].filter(Boolean).join(' ');
+  return '';
+};
+
+/** The last assistant answer, else the last tool or notice block, else null. -> { kind: 'answer'|'tool'|'notice', text } */
+export function lastOutput(s) {
+  const answers = s?.answers || [];
+  for (let i = answers.length - 1; i >= 0; i--) if (answers[i].text?.trim()) return { kind: 'answer', text: answers[i].text };
+  const all = [...(s?.history || []), ...(s?.blocks || [])];
+  for (let i = all.length - 1; i >= 0; i--) {
+    const it = all[i], t = itemText(it).trim();
+    if (!t || it.kind === 'user') continue;
+    if (it.kind === 'tool' || it.kind === 'error' || it.kind === 'note') return { kind: it.kind === 'tool' ? 'tool' : 'notice', text: t };
+  }
+  return null;
+}
+
+/** Parse the /dragon argument line -> { mode: 'pick'|'fire'|'idle'|'hero'|'explain'|'ask'|'sleep'|'fly', question? } | null (usage). */
+export function parseDragonArg(restArg) {
+  const t = String(restArg || '').trim();
+  if (!t) return { mode: 'pick' };
+  const [w, ...rest] = t.split(/\s+/);
+  switch (w.toLowerCase()) {
+    case 'fire': return rest.length ? null : { mode: 'fire' };
+    case 'classic': return rest.length ? null : { mode: 'idle' };
+    case 'hero': return rest.length ? null : { mode: 'hero' };
+    // `/dragon explain <thing>` is a question about that thing (owner 2026-10-15: it used to print usage).
+    case 'explain': return rest.length ? { mode: 'ask', question: rest.join(' ').trim() } : { mode: 'explain' };
+    case 'sleep': return rest.length ? null : { mode: 'sleep' };
+    case 'fly': return rest.length ? null : { mode: 'fly' };
+    case 'ask': return { mode: 'ask', question: rest.join(' ').trim() };
+    // Anything else is a question for the dragon, never a usage error.
+    default: return { mode: 'ask', question: t };
+  }
+}
+
+// ---- sleep: katakana veil ---------------------------------------------------------------------------------
+export const VEIL_IN_MS = 700;           // text drops into katakana, left to right
+export const VEIL_STEP_MS = 700;         // the noise re-rolls this slowly (low frame rate; a shimmer, not a flicker)
+export const WAKE_MS = Math.round(revealSpan(TIMING.row) * 1000); // the existing decode reveal, run forward
+
+const isText = (ch) => /^[\p{L}\p{N}\p{P}\p{S}]+$/u.test(ch);
+const kana = (i, k, salt) => SCRAMBLE_GLYPHS[Math.floor(hash3(i, k, salt) * SCRAMBLE_GLYPHS.length)];
+
+/**
+ * One source line as veil cells at `ms` since sleep began (phase 'in' then 'asleep') or since wake began
+ * (phase 'wake'). Cells are { ch, kind: 'kana'|'plain'|'blank'|'glow', g }. Width of every column is preserved
+ * (a 2-wide char becomes two kana), so rows never change length. still: no re-rolling.
+ */
+export function veilRow(text, ms, { phase = 'asleep', still = false, salt = 1, row = 0 } = {}) {
+  if (phase === 'wake') return revealCells(text, ms / 1000, TIMING.row, { salt: salt + row }).map((c) => ({ ...c }));
+  const gs = graphemes(String(text ?? '')).map((g) => g.text);
+  const n = gs.length, bucket = still ? 0 : Math.floor(ms / VEIL_STEP_MS);
+  const edge = phase === 'in' && !still ? (ms / VEIL_IN_MS) * n : Infinity; // cells left of the edge are veiled
+  const out = [];
+  gs.forEach((ch, i) => {
+    const w = stringWidth(ch);
+    if (w === 0) return;
+    if (ch === ' ' || !isText(ch) || i > edge) { out.push({ ch, kind: 'plain', g: 0 }); return; }
+    for (let k = 0; k < w; k++) out.push({ ch: kana(i * 2 + k + row * 131, bucket, salt), kind: 'kana', g: hash3(i, bucket + 7, salt) });
+  });
+  return out;
+}
+
+export const veilText = (cells) => cells.map((c) => c.ch).join('');
+export const isVeiled = (cells) => cells.some((c) => c.kind === 'kana');
+
+/** The visible text the screen shows, as at most `rows` lines wrapped to `cols` (tail of the transcript). */
+export function sourceLines(s, cols, rows) {
+  const all = [...(s?.history || []), ...(s?.blocks || [])];
+  const lines = [];
+  for (let i = all.length - 1; i >= 0 && lines.length < rows; i--) {
+    const it = all[i];
+    const t = it.kind === 'user' ? `> ${it.text || ''}` : itemText(it);
+    if (!t.trim()) continue;
+    const wrapped = [];
+    for (const raw of t.split('\n')) {
+      let r = raw;
+      if (!r) { wrapped.push(''); continue; }
+      while (stringWidth(r) > cols) { let cut = cols; while (cut > 1 && stringWidth(r.slice(0, cut)) > cols) cut--; wrapped.push(r.slice(0, cut)); r = r.slice(cut); }
+      wrapped.push(r);
+    }
+    lines.unshift(...wrapped);
+  }
+  return lines.slice(-rows);
+}
+
+// ---- the sleep screen -----------------------------------------------------------------------------------------
+export const SLEEP_HINT = 'asleep · any key wakes · /back when you return';
+const VEIL_RGB = [129, 140, 248], HINT_RGB = [186, 230, 253];
+
+/**
+ * The whole sleep frame as rows of { ch, rgb } cells, `rows` tall and `cols` wide. ms = since sleep began, or
+ * since wake began when wake is true (text decodes back, the dragon is gone). Pure: no transcript access, the
+ * caller passes the source lines. still (reduced motion): a static veil and a still dragon. mono: no colour.
+ */
+export function composeSleep({ lines, cols, rows, ms = 0, wake = false, still = false, mono = false, theme = 'dark', size }) {
+  const phase = wake ? 'wake' : ms < VEIL_IN_MS && !still ? 'in' : 'asleep';
+  const col = (c) => (mono ? null : c);
+  const grid = Array.from({ length: rows }, () => Array.from({ length: cols }, () => ({ ch: ' ', rgb: null })));
+  const body = wake ? rows : rows - 1; // the last row holds the wake hint while asleep
+  const src = lines.slice(-body);
+  const top = body - src.length;
+  src.forEach((line, i) => {
+    veilRow(line, ms, { phase, still, row: i }).slice(0, cols).forEach((c, x) => {
+      grid[top + i][x] = { ch: c.ch, rgb: c.kind === 'kana' ? col(VEIL_RGB) : null, bold: c.kind === 'glow' && c.g > 0.5 };
+    });
+  });
+  if (!wake) {
+    const sz = size ?? (rows >= 32 && cols >= 64 ? undefined : 'mid');
+    const dcols = Math.min(cols, sz === 'mid' || cols < 64 ? 44 : 72);
+    const dc = sleepCells(ms, dcols, undefined, { theme, mono, still, size: sz });
+    const x0 = Math.max(0, Math.floor((cols - dcols) / 2)), y0 = Math.max(0, Math.floor((rows - 1 - dc.length) / 2));
+    dc.forEach((r, i) => {
+      if (y0 + i >= rows - 1) return;
+      r.forEach((c, x) => { if (x0 + x < cols) grid[y0 + i][x0 + x] = { ch: c.ch, rgb: mono ? null : c.rgb, bg: c.bg || undefined }; });
+    });
+    const hint = [...SLEEP_HINT], hx = Math.max(0, Math.floor((cols - hint.length) / 2));
+    hint.forEach((ch, i) => { if (hx + i < cols) grid[rows - 1][hx + i] = { ch, rgb: col(HINT_RGB) }; });
+  }
+  return grid;
+}

package/lib/quoxon/dragonView.js

@@ -0,0 +1,41 @@
+/** Ink views for /dragon explain|ask (the talking dragon) and /dragon sleep (the screensaver). Frames come from dragonModes.js. */
+import React from 'react';
+import { Box, Text } from 'ink';
+import { cellNodes } from './qmotion.js';
+import { composeSleep } from './dragonModes.js';
+import { pickCells } from './qdragonScenes.js';
+import { flyFrame, flyCols } from './qdragonFly.js';
+import { mono, isLight, clip } from './theme.js';
+import { useFrame } from './motion/frame.js';
+
+const h = React.createElement;
+
+/** The sleep screen: the whole live region while asleep (and for the decode on wake). Reads the clock itself. */
+export function SleepScreen({ lines, cols, rows, startedAt, wakeAt = null, still = false }) {
+  useFrame();
+  const now = Date.now();
+  const wake = wakeAt != null;
+  const ms = wake ? now - wakeAt : now - startedAt;
+  const grid = composeSleep({ lines, cols, rows, ms, wake, still, mono: mono(), theme: isLight() ? 'light' : 'dark' });
+  return h(Box, { flexDirection: 'column' }, ...grid.map((r, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(r, `s${k}-`))));
+}
+
+/** The compact dragon beside an explain/ask answer: the mouth works while text streams, then it rests with idle eyes. */
+export function DragonTalk({ cols, label, talking, since, still = false }) {
+  useFrame();
+  const dcols = Math.min(cols, 44);
+  const t = Date.now() - since;
+  const cells = pickCells(t, dcols, undefined, { theme: isLight() ? 'light' : 'dark', mono: mono(), still: still || !talking, talk: talking && !still, size: 'mid', mouthSide: 'right' });
+  return h(Box, { flexDirection: 'column', marginTop: 1 },
+    ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `t${k}-`))),
+    h(Text, null, clip(label, Math.max(10, cols - 2))));
+}
+
+/** /dragon-fly: one pass of the dragon in flight across the live region (qdragonFly.js). `still`: a single frame, no motion. */
+export function FlyLive({ cols, rows, startedAt, still = false }) {
+  useFrame();
+  const c = flyCols(cols);
+  const cells = flyFrame(Date.now() - startedAt, c, { still, mono: mono(), theme: isLight() ? 'light' : 'dark', termRows: rows });
+  return h(Box, { flexDirection: 'column', marginTop: 1 },
+    ...cells.map((row, k) => h(Text, { key: k, wrap: 'truncate' }, ...cellNodes(row, `f${k}-`))));
+}

package/lib/quoxon/earlyInput.js

@@ -0,0 +1,40 @@
+/**
+ * Keys typed before the app is ready (R3 audit D4). bin/quox.js calls this before it loads React, Ink or any
+ * command module, so the tty is raw (no cooked echo) and every key is kept for the composer. main() calls it
+ * again and gets the same capture. Tiny on purpose: it must not import anything heavy.
+ *
+ * A line typed while the tty was still cooked reaches us when raw mode turns on, with the kernel's ICRNL
+ * having turned its Enter into LF; that first read is mapped back to CR so the Enter submits as typed.
+ */
+import { PASTE_ON, PASTE_OFF } from './keys.js';
+
+const COOKED_MS = 50; // the read that drains the cooked line buffer arrives right after raw mode turns on
+let shared = null;
+
+export function captureEarlyInput(stdin = process.stdin, stdout = process.stdout) {
+  const own = stdin === process.stdin;
+  if (own && shared) return shared;
+  if (!stdin?.isTTY) return null;
+  const chunks = [];
+  const t0 = Date.now();
+  const fn = (d) => {
+    const s = typeof d === 'string' ? d : d.toString('utf8');
+    chunks.push(Date.now() - t0 < COOKED_MS ? s.replace(/\n/g, '\r') : s);
+  };
+  try { stdin.setRawMode?.(true); stdin.resume?.(); } catch { /* not a tty after all */ }
+  stdin.on('data', fn);
+  if (stdout?.isTTY) stdout.write(PASTE_ON);
+  const cap = {
+    chunks,
+    detach: () => stdin.off('data', fn),
+    /** Nothing will take the terminal over (help, a flag error): give it back as it was. */
+    release: () => {
+      stdin.off('data', fn);
+      try { stdin.setRawMode?.(false); stdin.pause?.(); } catch { /* ignore */ }
+      if (stdout?.isTTY) stdout.write(PASTE_OFF);
+      if (own) shared = null;
+    }
+  };
+  if (own) shared = cap;
+  return cap;
+}

package/lib/quoxon/echo.js

@@ -0,0 +1,15 @@
+// Echo of a command the human typed, shown in the scrollback like a prompt line (wrapped in full, secrets masked).
+// Owner 2026-10-15: "why truncated": the echo wraps like any prompt; only a runaway paste is capped.
+import { redactSecrets } from './slotChat.js';
+import { clip } from './theme.js';
+
+const PIN_CMD = /^\/(authenticate|authorise|authorize)(\s|$)/i;
+
+/** -> { shown, full }: `shown` is the whole command on one logical line (the view wraps it; capped at ECHO_CAP), `full` is the masked text the transcript records. */
+export const ECHO_CAP = 2000;
+export function echoLine(text, { cols = 100 } = {}) {
+  let t = String(text ?? '').trim();
+  if (PIN_CMD.test(t)) t = t.split(/\s+/)[0]; // a stray argument may be a PIN: never shown
+  const full = redactSecrets(t).text;
+  return { shown: clip(full.replace(/\s*\n\s*/g, ' '), ECHO_CAP), full };
+}

package/lib/quoxon/egg.js

@@ -0,0 +1,36 @@
+/**
+ * The launch Easter egg (CLI-QUOX). On launch the v8 dragon greets you (googly eyes open, blink, smile), rarely:
+ * 1 in EGG_ODDS launches, never twice in a row, never in --print, under reduced motion or off a TTY.
+ * /dragon plays it on demand, and the cinematic motion level always may.
+ *
+ * pickLaunchEgg is pure; launchEgg adds the one bit of persistence (did the last launch show the eye?) in
+ * ~/.config/quox/motion.json. QUOX_EGG=eye forces it (demos, captures); QUOX_EGG=off disables it.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+export const EGG_ODDS = 20;
+
+/** Pure decision. */
+export function pickLaunchEgg({ rand = Math.random, lastWasEye = false, print = false, reduced = false, tty = true, force = null } = {}) {
+  if (print || reduced || !tty) return false;
+  if (force === 'off') return false;
+  if (force === 'eye') return true;
+  if (lastWasEye) return false;
+  return rand() < 1 / EGG_ODDS;
+}
+
+export const eggStatePath = (env = process.env) => join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'quox', 'motion.json');
+
+/** Decide once for this launch and remember the outcome. Never throws: an unreadable file means "no eye last time". */
+export function launchEgg({ env = process.env, tty = Boolean(process.stdout?.isTTY), print = false, rand = Math.random, path = eggStatePath(env) } = {}) {
+  let last = false;
+  try { last = Boolean(JSON.parse(readFileSync(path, 'utf8')).lastEye); } catch { /* first launch */ }
+  const reduced = env.QUOX_REDUCED_MOTION === '1' || Boolean(env.QUOX_TUI_LITE);
+  const eye = pickLaunchEgg({ rand, lastWasEye: last, print, reduced, tty, force: env.QUOX_EGG || null });
+  if (!print && tty) {
+    try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, JSON.stringify({ lastEye: eye }) + '\n'); } catch { /* read-only home: fine */ }
+  }
+  return eye;
+}