quoxcli 0.0.0-stage → 0.2.0

package/lib/quoxon/web/qface.js

@@ -0,0 +1,81 @@
+/**
+ * The Q face for the web (cli.quox.ai): the SAME pure frames the CLI draws (qart.js, qglyph.js, qhello.js),
+ * rendered into <pre> elements as coloured spans. Plays Orbit & Lock, then the Q says hello (the line
+ * decodes in from katakana), then idles: the mark breathes, the status Q breathes beside "Ready", and now
+ * and then the Dragon's Eye opens and blinks. prefers-reduced-motion: the settled frame only.
+ *
+ * Browser ESM, no dependencies, no build: import it next to ../qart.js, ../qglyph.js, ../qhello.js.
+ *   import { mountQFace } from './qface.js';
+ *   mountQFace(document.getElementById('face'), { hello: "Hi, I'm Quox!" });
+ */
+import { introPlan, restCellsAt, eyeCellsAt, INTRO_MS, EYE_MS } from '../qart.js';
+import { qGlyph } from '../qglyph.js';
+import { helloCells, helloGradient, helloMs } from '../qhello.js';
+
+const esc = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
+
+/** One row of cells -> HTML spans, merging runs of the same colour. */
+export function rowToHTML(row) {
+  let html = '', run = '', key = null;
+  const flush = () => { if (!run) return; html += key ? `<span style="${key}">${esc(run)}</span>` : esc(run); run = ''; };
+  for (const c of row) {
+    const k = c.rgb ? `color:rgb(${c.rgb.join(',')})${c.bold ? ';font-weight:700' : ''}` : (c.bold ? 'font-weight:700' : null);
+    if (k !== key) { flush(); key = k; }
+    run += c.ch;
+  }
+  flush();
+  return html;
+}
+// Blank cells in Braille art are drawn as U+2800 (the empty Braille pattern), not a space: a browser can
+// give a space and a Braille glyph different advances (font fallback), which shears the Q row by row.
+const BLANK = '\u2800';
+export const cellsToHTML = (rows) => rows.map((r) => rowToHTML(r.map((c) => (c.ch === ' ' ? { ...c, ch: BLANK } : c)))).join('\n');
+
+/** Which Q size fits a container of `px` CSS pixels at a monospace advance of `cw` px. */
+export function sizeForWidth(px, cw = 8.4) {
+  const cols = Math.floor(px / cw);
+  return cols >= 34 ? 'large' : cols >= 22 ? 'mid' : 'small';
+}
+
+/**
+ * Timeline state at t ms (pure): which picture, the hello progress, and whether the eye is open.
+ * eyeAt: list of start times (ms) for idle eye blinks.
+ */
+export function faceFrame(t, { size, hello, eyeAt = [], color = true }) {
+  const plan = introPlan(size, { color, quant: false });
+  const hT = t - INTRO_MS, settledAt = INTRO_MS + helloMs(hello);
+  let q;
+  const eye = eyeAt.find((s) => t >= s && t < s + EYE_MS + 400);
+  if (t < INTRO_MS) q = plan.at(t);
+  else if (eye != null) q = eyeCellsAt(size, t - eye, { color, quant: false });
+  else q = restCellsAt(size, Math.max(0, t - settledAt), { color, quant: false });
+  const line = helloCells(hello, hT, { fg: helloGradient(hello), mono: !color });
+  const glyph = qGlyph('resting', Math.max(0, t - settledAt), { mono: !color });
+  return { q, line, glyph, showStatus: t >= settledAt };
+}
+
+export function mountQFace(root, { hello = "Hi, I'm Quox!", status = 'Ready', seed = 7, reduced = null, eyeEveryMs = [9000, 16000] } = {}) {
+  const doc = root.ownerDocument, win = doc.defaultView;
+  root.classList.add('qface');
+  root.innerHTML = '<pre class="qface-q" aria-hidden="true"></pre><div class="qface-side"><pre class="qface-hello"></pre><pre class="qface-status"></pre></div>';
+  root.setAttribute('role', 'img');
+  root.setAttribute('aria-label', `The Quox Q says: ${hello}`);
+  const [qEl, hEl, sEl] = ['.qface-q', '.qface-hello', '.qface-status'].map((s) => root.querySelector(s));
+  const still = reduced ?? Boolean(win.matchMedia?.('(prefers-reduced-motion: reduce)').matches);
+  let r = seed; const rand = () => { r = (r * 16807) % 2147483647; return r / 2147483647; };
+  const eyeAt = [];
+  let next = INTRO_MS + helloMs(hello) + 2500; // the first blink comes soon after hello, then rarely
+  for (let i = 0; i < 40; i++) { eyeAt.push(next); next += EYE_MS + eyeEveryMs[0] + rand() * (eyeEveryMs[1] - eyeEveryMs[0]); }
+  const size = () => sizeForWidth(Math.min(root.clientWidth || 600, win.innerWidth || 600) * (root.clientWidth > 520 ? 0.55 : 1));
+  const draw = (t) => {
+    const f = faceFrame(t, { size: size(), hello, eyeAt });
+    qEl.innerHTML = cellsToHTML(f.q);
+    hEl.innerHTML = rowToHTML(f.line);
+    sEl.innerHTML = f.showStatus ? `${rowToHTML(f.glyph.cells)} <span class="qface-word">${esc(status)}</span>` : '&nbsp;';
+  };
+  if (still) { draw(INTRO_MS + helloMs(hello) + 10); return { stop() {} }; }
+  let raf = 0, t0 = null, stopped = false;
+  const tick = (now) => { if (stopped) return; t0 ??= now; draw(now - t0); raf = win.requestAnimationFrame(tick); };
+  raf = win.requestAnimationFrame(tick);
+  return { stop() { stopped = true; win.cancelAnimationFrame(raf); }, seek: draw };
+}

package/lib/quoxon/welcome.js

@@ -0,0 +1,52 @@
+/**
+ * First-run notice for bare `quox`: who we are, legal, docs. Pure model + a tiny "seen" marker kept in the
+ * CLI's existing config dir (~/.config/quox, same place as config.json). Links live ONLY here.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DOCS_URL = 'https://github.com/quoxai/quoxcore'; // will become https://cli.quox.ai
+export const TERMS_URL = 'https://quox.ai/terms';
+export const PRIVACY_URL = 'https://quox.ai/privacy';
+export const LICENCE = 'Quox Community Source Licence 1.0 (source-available)';
+export const WELCOME_VERSION = 1;
+
+export function packageVersion() {
+  try { return JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version || '0.1.0'; } catch { return '0.1.0'; }
+}
+
+/** [{ kind: 'title'|'sub'|'rule'|'field'|'para'|'gap'|'hint', ... }] */
+export function welcomeModel(version = packageVersion()) {
+  return [
+    { kind: 'title', text: 'Welcome to Quox' },
+    { kind: 'sub', text: `Quox CLI ${version}` },
+    { kind: 'para', text: 'The main front door to Quox, your self-hosted control plane for AI agents.' },
+    { kind: 'rule' },
+    { kind: 'field', label: 'Docs', value: DOCS_URL, link: true },
+    { kind: 'field', label: 'Terms', value: TERMS_URL, link: true },
+    { kind: 'field', label: 'Privacy', value: PRIVACY_URL, link: true },
+    { kind: 'field', label: 'Licence', value: LICENCE },
+    { kind: 'rule' },
+    { kind: 'para', text: 'Your prompts go to your own QuoxCORE server and to the AI provider you connect to it.' },
+    { kind: 'para', text: 'Risky actions ask you first, and the actions Quox takes leave receipts you can verify.' },
+    { kind: 'para', text: 'This CLI sends no telemetry to Quox.' },
+    { kind: 'para', text: 'By using Quox CLI you agree to the Terms.' },
+    { kind: 'hint', text: 'Enter to continue · /about to see this again' }
+  ];
+}
+
+export const welcomeStatePath = () => join(homedir(), '.config', 'quox', 'welcome.json');
+
+export function welcomeSeen(path = welcomeStatePath()) {
+  try { return (JSON.parse(readFileSync(path, 'utf8')).version || 0) >= WELCOME_VERSION; } catch { return false; }
+}
+export function markWelcomeSeen(path = welcomeStatePath()) {
+  try { mkdirSync(join(path, '..'), { recursive: true }); writeFileSync(path, JSON.stringify({ version: WELCOME_VERSION, seenAt: new Date().toISOString() }) + '\n'); return true; } catch { return false; }
+}
+
+/** First interactive launch only: a TTY, not suppressed, not seen at this notice version. */
+export function shouldShowWelcome({ env = process.env, isTTY = process.stdout.isTTY && process.stdin.isTTY, print = false, path } = {}) {
+  if (print || !isTTY || env.QUOX_NO_WELCOME === '1') return false;
+  return !welcomeSeen(path);
+}

package/lib/tui/app.jsx

@@ -0,0 +1,289 @@
+/**
+ * QuoxCLI TUI — Root Application Component
+ *
+ * Manages the view state machine:
+ *   intro -> menu -> specific view (fleet, agents, tools, etc.)
+ *
+ * Provides TuiContext to all descendants with navigation helpers,
+ * the CLI context (config, auth, client), and the app exit function.
+ *
+ * ── Input-mode registry ────────────────────────────────────────────────
+ * `inputMode` on the context tells the global keybinding handler whether
+ * it's safe to steal single-character keys like `?` (help) and `q` (quit):
+ *   'nav'     - default; global shortcuts are active
+ *   'input'   - a text field (chat box, search box) has focus; global
+ *               single-char shortcuts are suppressed so typing works
+ *   'overlay' - the help overlay or command palette is open; it owns its
+ *               own close handler and (for the palette) all keystrokes
+ * Escape/back always works regardless of mode (text inputs intentionally
+ * ignore Escape so navigation can still happen).
+ *
+ * ── Command palette + global jump keys ─────────────────────────────────
+ * Ctrl+K or ':' (nav mode only) opens the palette (components/Palette.jsx)
+ * over the current screen, content-swapped like the help overlay. It's a
+ * fuzzy search over lib/tui/registry.js's SCREEN_REGISTRY. Separately,
+ * whenever inputMode is 'nav' and a sub-view is active (screen !== 'menu'),
+ * pressing a screen's hotkey (1-0 / o i v g h — same as MainMenu's number
+ * keys) jumps straight there without returning to the menu first
+ * (k9s-style). Both are gated on inputMode === 'nav' so they never steal
+ * keystrokes from a focused chat/search box.
+ *
+ * ── Keep-alive views ───────────────────────────────────────────────────
+ * A screen is mounted the first time it's visited and then stays mounted
+ * (hidden via `display: none`) so its state — chat history, filters,
+ * selections — survives navigating away and back. Views only fetch data
+ * on their first activation (see each view's data hook), so this does
+ * NOT boot-fetch all screens at startup.
+ */
+
+import React, { useState, useCallback, createContext, useContext } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { matchKey } from './keys.js';
+import { colors } from './theme.js';
+import { MainMenu } from './views/MainMenu.jsx';
+import { FleetView } from './views/FleetView.jsx';
+import { AgentView } from './views/AgentView.jsx';
+import { ToolView } from './views/ToolView.jsx';
+import { OrgView } from './views/OrgView.jsx';
+import { MemoryView } from './views/MemoryView.jsx';
+import { BrainView } from './views/BrainView.jsx';
+import { WorkflowView } from './views/WorkflowView.jsx';
+import { ChatView } from './views/ChatView.jsx';
+import { AdminView } from './views/AdminView.jsx';
+import { FilesView } from './views/FilesView.jsx';
+import { BackupView } from './views/BackupView.jsx';
+import { ObjectivesView } from './views/ObjectivesView.jsx';
+import { InboxView } from './views/InboxView.jsx';
+import { VaultView } from './views/VaultView.jsx';
+import { GovernanceView } from './views/GovernanceView.jsx';
+import { HealthView } from './views/HealthView.jsx';
+import { StatusBar } from './components/StatusBar.jsx';
+import { HelpOverlay } from './components/HelpOverlay.jsx';
+import { Palette } from './components/Palette.jsx';
+import { Toast } from './components/Toast.jsx';
+import { SCREEN_BY_HOTKEY } from './registry.js';
+
+// ── TUI Context ───────────────────────────────────────────────────────
+export const TuiContext = createContext(null);
+
+/**
+ * Hook to access TUI context from any descendant component.
+ * @returns {{ config, auth, client, navigate, goBack, screen, history, exit, inputMode, setInputMode, orgVersion, onOrgChange }}
+ */
+export const useTui = () => useContext(TuiContext);
+
+// ── Screen registry ───────────────────────────────────────────────────
+const SCREENS = [
+  'menu',
+  'fleet', 'agents', 'tools', 'orgs',
+  'memory', 'brain', 'workflows', 'chat',
+  'admin', 'files', 'backups',
+  'objectives', 'inbox', 'vault', 'governance', 'health',
+];
+
+// Sub-views rendered (keep-alive) alongside the menu. Keyed by screen id.
+const VIEW_COMPONENTS = {
+  fleet: FleetView,
+  agents: AgentView,
+  tools: ToolView,
+  orgs: OrgView,
+  memory: MemoryView,
+  brain: BrainView,
+  workflows: WorkflowView,
+  chat: ChatView,
+  admin: AdminView,
+  files: FilesView,
+  backups: BackupView,
+  objectives: ObjectivesView,
+  inbox: InboxView,
+  vault: VaultView,
+  governance: GovernanceView,
+  health: HealthView,
+};
+
+// ── Root component ────────────────────────────────────────────────────
+export function App({ ctx, initialScreen = null }) {
+  const { exit } = useApp();
+  // Deep-link: `quox tui <screen>` (or the web QuoxCLIView ?screen= param) can
+  // open directly on a view instead of the menu. Guard against unknown names.
+  const startScreen =
+    initialScreen && initialScreen !== 'menu' && SCREENS.includes(initialScreen)
+      ? initialScreen
+      : 'menu';
+  const [screen, setScreen] = useState(startScreen);
+  const [history, setHistory] = useState([]);
+  const [showHelp, setShowHelp] = useState(false);
+  const [showPalette, setShowPalette] = useState(false);
+  const [toast, setToast] = useState(null);
+  const [inputMode, setInputMode] = useState('nav');
+  const [orgVersion, setOrgVersion] = useState(0);
+
+  // Screens that have been visited at least once — kept mounted (hidden
+  // via display:none when not current) so their state survives navigation.
+  const [visited, setVisited] = useState(() =>
+    startScreen === 'menu' ? new Set(['menu']) : new Set(['menu', startScreen])
+  );
+
+  // Navigation helpers
+  const navigate = (target) => {
+    if (!SCREENS.includes(target)) return;
+    setHistory((prev) => [...prev, screen]);
+    setVisited((prev) => (prev.has(target) ? prev : new Set(prev).add(target)));
+    setScreen(target);
+  };
+
+  const goBack = () => {
+    if (history.length > 0) {
+      const prev = history[history.length - 1];
+      setHistory((h) => h.slice(0, -1));
+      setScreen(prev);
+    }
+  };
+
+  // Toast helper
+  const showToast = useCallback((message, type = 'info') => {
+    setToast({ message, type });
+  }, []);
+
+  const dismissToast = useCallback(() => {
+    setToast(null);
+  }, []);
+
+  // Called by OrgView after switching the active org — bumps a version
+  // counter that org-scoped views include in their fetch deps so they
+  // refetch automatically.
+  const onOrgChange = useCallback(() => {
+    setOrgVersion((v) => v + 1);
+  }, []);
+
+  const closeHelp = useCallback(() => {
+    setShowHelp(false);
+    setInputMode('nav');
+  }, []);
+
+  const closePalette = useCallback(() => {
+    setShowPalette(false);
+    setInputMode('nav');
+  }, []);
+
+  // Build context value
+  const tuiCtx = {
+    ...(ctx || {}),
+    navigate,
+    goBack,
+    screen,
+    history,
+    exit,
+    showToast,
+    inputMode,
+    setInputMode,
+    orgVersion,
+    onOrgChange,
+  };
+
+  // ── Global keybindings ──────────────────────────────────────────────
+  useInput((input, key) => {
+    // While the help overlay is open, it owns ? and Esc via its own listener.
+    if (showHelp) return;
+
+    // While the command palette is open, it owns all keystrokes (typing,
+    // arrows, Enter, Esc) via its own useInput listener.
+    if (showPalette) return;
+
+    // Single-character global shortcuts (help, quit, palette) and the
+    // global jump keys only fire in 'nav' mode — otherwise typing into a
+    // chat/search box would be hijacked.
+    if (inputMode === 'nav') {
+      if (matchKey('help', input, key)) {
+        setShowHelp(true);
+        setInputMode('overlay');
+        return;
+      }
+
+      // Command palette: Ctrl+K (can't be expressed via matchKey's plain
+      // string comparison) or ':' (a normal KEYS binding).
+      if ((key.ctrl && input === 'k') || matchKey('palette', input, key)) {
+        setShowPalette(true);
+        setInputMode('overlay');
+        return;
+      }
+
+      if (screen === 'menu' && matchKey('quit', input, key)) {
+        exit();
+        return;
+      }
+
+      // Global jump keys (k9s-style): from any non-menu screen, a screen's
+      // hotkey (1-0 / o i v g h — see SCREEN_BY_HOTKEY) jumps straight
+      // there, mirroring MainMenu's own number-key shortcuts.
+      if (screen !== 'menu') {
+        const target = SCREEN_BY_HOTKEY[input];
+        if (target) {
+          navigate(target);
+          return;
+        }
+      }
+    }
+
+    // Escape goes back from any sub-view — works regardless of input mode
+    // (text inputs deliberately ignore Escape so this can still fire).
+    if (screen !== 'menu' && matchKey('back', input, key)) {
+      goBack();
+    }
+  });
+
+  // ── Render ──────────────────────────────────────────────────────────
+  return (
+    <TuiContext.Provider value={tuiCtx}>
+      <Box flexDirection="column" width="100%" height="100%">
+        {/* Toast notification */}
+        {toast && (
+          <Toast
+            message={toast.message}
+            type={toast.type}
+            duration={3000}
+            onDismiss={dismissToast}
+          />
+        )}
+
+        {/* Main content area — the palette and help overlay swap in place
+            of the screens (no layout shift) rather than pushing them down
+            as a sibling. Palette takes priority if somehow both are open. */}
+        <Box flexGrow={1}>
+          {showPalette ? (
+            <Palette
+              onSelect={(id) => {
+                navigate(id);
+                closePalette();
+              }}
+              onClose={closePalette}
+            />
+          ) : showHelp ? (
+            <HelpOverlay visible={showHelp} onClose={closeHelp} />
+          ) : (
+            <>
+              <Box display={screen === 'menu' ? 'flex' : 'none'} width="100%" height="100%">
+                <MainMenu />
+              </Box>
+              {Object.entries(VIEW_COMPONENTS).map(([name, ViewComponent]) => (
+                visited.has(name) && (
+                  <Box
+                    key={name}
+                    display={screen === name ? 'flex' : 'none'}
+                    width="100%"
+                    height="100%"
+                  >
+                    <ViewComponent />
+                  </Box>
+                )
+              ))}
+            </>
+          )}
+        </Box>
+
+        {/* Status bar */}
+        <StatusBar />
+      </Box>
+    </TuiContext.Provider>
+  );
+}

package/lib/tui/components/Breadcrumb.jsx

@@ -0,0 +1,42 @@
+/**
+ * Breadcrumb — Navigation trail showing current position
+ *
+ * Renders a breadcrumb path like: Main > Fleet > Agent Details
+ * where the last segment is highlighted in the primary color
+ * and preceding segments are dimmed.
+ *
+ * Props:
+ *   path - array of strings, e.g. ['Main', 'Fleet', 'Agent Details']
+ */
+
+import React from 'react';
+import { Box, Text } from 'ink';
+import { colors } from '../theme.js';
+
+export function Breadcrumb({ path = [] }) {
+  if (path.length === 0) return null;
+
+  return (
+    <Box>
+      {path.map((segment, i) => {
+        const isLast = i === path.length - 1;
+        return (
+          <React.Fragment key={i}>
+            {/* Separator */}
+            {i > 0 && (
+              <Text color={colors.dim}> {'>'} </Text>
+            )}
+
+            {/* Segment */}
+            <Text
+              color={isLast ? colors.primary : colors.dim}
+              bold={isLast}
+            >
+              {segment}
+            </Text>
+          </React.Fragment>
+        );
+      })}
+    </Box>
+  );
+}

package/lib/tui/components/ChatInput.jsx

@@ -0,0 +1,68 @@
+/**
+ * ChatInput — Presentational input line + agent picker overlay for ChatView
+ *
+ * Pure rendering component: ChatView owns all input state (draft text,
+ * cursor position, history, agent selection) and passes it down as props.
+ * Kept separate so the caret-rendering and agent-picker markup don't
+ * clutter ChatView's streaming/keyboard logic.
+ *
+ * Props:
+ *   input       - current draft text
+ *   cursor      - caret index into `input` (0..input.length)
+ *   disabled    - true while a response is streaming (dims the border)
+ *   agents      - array of agent objects/strings for the picker list
+ *   pickerOpen  - whether the agent picker overlay is visible
+ *   pickerIndex - highlighted row in the picker
+ */
+
+import React from 'react';
+import { Box, Text } from 'ink';
+import { colors } from '../theme.js';
+
+function agentLabel(a) {
+  if (typeof a === 'string') return a;
+  return a?.name || a?.display_name || a?.id || String(a);
+}
+
+export function ChatInput({
+  input = '',
+  cursor = 0,
+  disabled = false,
+  agents = [],
+  pickerOpen = false,
+  pickerIndex = 0,
+}) {
+  const safeCursor = Math.max(0, Math.min(cursor, input.length));
+  const pre = input.slice(0, safeCursor);
+  const rest = input.slice(safeCursor);
+
+  return (
+    <Box flexDirection="column">
+      <Box borderStyle="single" borderColor={disabled ? colors.subtle : colors.primary} paddingX={1}>
+        <Text color={colors.cyberBlue}>{'> '}</Text>
+        <Text>{pre}</Text>
+        <Text color={colors.dim}>{'█'}</Text>
+        <Text>{rest}</Text>
+      </Box>
+
+      {pickerOpen && (
+        <Box flexDirection="column" borderStyle="round" borderColor={colors.accent} paddingX={1}>
+          <Text color={colors.accent} bold>Select agent — Tab/↑↓ move, Enter confirm</Text>
+          {agents.length === 0 ? (
+            <Text color={colors.dim}>No agents found</Text>
+          ) : (
+            agents.map((a, i) => (
+              <Text
+                key={`${agentLabel(a)}-${i}`}
+                color={i === pickerIndex ? colors.cyberBlue : colors.textMuted}
+                bold={i === pickerIndex}
+              >
+                {i === pickerIndex ? '➤ ' : '  '}{agentLabel(a)}
+              </Text>
+            ))
+          )}
+        </Box>
+      )}
+    </Box>
+  );
+}

package/lib/tui/components/Confirm.jsx

@@ -0,0 +1,32 @@
+/**
+ * Confirm — Confirmation dialog component
+ *
+ * Shows an inline confirmation prompt with y/n keybindings.
+ *
+ * Props:
+ *   message   - question text (e.g. "Delete backup XYZ?")
+ *   onConfirm - called when user presses y
+ *   onCancel  - called when user presses n or Esc
+ *   active    - whether dialog is shown/active (default true)
+ */
+
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import { colors } from '../theme.js';
+
+export function Confirm({ message, onConfirm, onCancel, active = true }) {
+  useInput((input, key) => {
+    if (!active) return;
+    if (input === 'y' || input === 'Y') { onConfirm?.(); return; }
+    if (input === 'n' || input === 'N' || key.escape) { onCancel?.(); return; }
+  }, { isActive: active });
+
+  if (!active) return null;
+
+  return (
+    <Box borderStyle="single" borderColor={colors.warning} paddingX={2} paddingY={1}>
+      <Text color={colors.warning}>{message} </Text>
+      <Text color={colors.dim}>(y/n)</Text>
+    </Box>
+  );
+}