quoxcli 0.0.0-stage → 0.3.1

package/lib/core/lazyCommands.js

@@ -0,0 +1,122 @@
+/**
+ * Lazy command-group registration (CORTEX-BENCH, CLI startup latency).
+ *
+ * Importing every command module cost ~1s on every `quox` invocation. Here a
+ * cached map (top-level command name -> registrar indexes) lets a normal
+ * invocation import only the module(s) that define or extend its command (a
+ * group can be extended by several modules, e.g. `agent` by agent.js and
+ * agentAttach.js). Correctness rules:
+ *   - no map, stale map, unknown command, help/completion/bare invocation,
+ *     or ANY error in the lazy path  ->  full load (the old behaviour);
+ *   - after a lazy load, the command must actually exist, else full load;
+ *   - every full load rebuilds the map, so it self-heals.
+ * A wrong map can therefore only make a call slower, never break it.
+ */
+import { readFileSync, writeFileSync, mkdirSync, statSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const MAP_VERSION = 1;
+// Global options that consume the next argv token (so it is not the command).
+const VALUE_OPTS = new Set(['-o', '--output', '--org', '-p', '--profile']);
+const FULL_LOAD_TOKENS = new Set(['help', 'completion', 'tui']);
+
+/** First argv token that names a command, or null (help/bare/unknown shape). */
+export function commandToken(argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--') return null;
+    if (a === '-h' || a === '--help' || a === '-V' || a === '--version') return null;
+    if (a.startsWith('-')) {
+      if (VALUE_OPTS.has(a)) i++;
+      continue;
+    }
+    return a;
+  }
+  return null;
+}
+
+function mapPath() {
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'quox', 'cli-command-map.json');
+}
+
+/** Cache key: the command modules' file set and mtimes, plus the registrar list. */
+export function mapKey(registrars, commandsDir) {
+  let sig = registrars.map(([p, n]) => `${p}#${n}`).join('|');
+  try {
+    for (const f of readdirSync(commandsDir).sort()) {
+      if (!f.endsWith('.js')) continue;
+      sig += `|${f}:${statSync(join(commandsDir, f)).mtimeMs}`;
+    }
+  } catch { return null; }
+  let h = 5381;
+  for (let i = 0; i < sig.length; i++) h = ((h << 5) + h + sig.charCodeAt(i)) | 0;
+  return `v${MAP_VERSION}:${h}`;
+}
+
+// Size of a command subtree (every nested command and option), so a module
+// that only extends a DEEP subcommand of an existing group is still recorded
+// as touching that top-level group.
+function subtreeSize(cmd) {
+  return 1 + cmd.options.length + cmd.commands.reduce((n, c) => n + subtreeSize(c), 0);
+}
+function topLevelSnapshot(program) {
+  return new Map(program.commands.map((c) => [c.name(), subtreeSize(c)]));
+}
+
+async function fullLoad(program, ctx, registrars, baseUrl, key) {
+  const map = {};
+  for (let i = 0; i < registrars.length; i++) {
+    const [path, name] = registrars[i];
+    const before = topLevelSnapshot(program);
+    const mod = await import(new URL(path, baseUrl).href);
+    mod[name](program, ctx);
+    for (const [cmd, size] of topLevelSnapshot(program)) {
+      if (before.get(cmd) !== size) (map[cmd] ||= []).push(i);
+    }
+  }
+  if (key) {
+    try {
+      const file = mapPath();
+      mkdirSync(dirname(file), { recursive: true });
+      writeFileSync(file, JSON.stringify({ key, map }));
+    } catch { /* the cache is an optimisation only */ }
+  }
+}
+
+/**
+ * Register command groups lazily when safe, fully otherwise.
+ * @param {import('commander').Command} program
+ * @param {object} ctx
+ * @param {Array<[string, string]>} registrars [modulePath relative to baseUrl, export name], in registration order
+ * @param {string[]} argv process.argv.slice(2)
+ * @param {string} baseUrl import.meta.url of the caller
+ */
+export async function registerCommandGroups(program, ctx, registrars, argv, baseUrl) {
+  // The directory the registrar modules live in, resolved from the registrar paths
+  // themselves (the list moved to lib/core/commandRegistrars.js, so baseUrl is no
+  // longer bin/quox.js and a fixed '../lib/commands' would miss).
+  const commandsDir = registrars.length ? dirname(fileURLToPath(new URL(registrars[0][0], baseUrl))) : join(dirname(fileURLToPath(baseUrl)), '..', 'lib', 'commands');
+  const key = process.env.QUOX_CLI_EAGER === '1' ? null : mapKey(registrars, commandsDir);
+  const token = commandToken(argv);
+  if (key && token && !FULL_LOAD_TOKENS.has(token)) {
+    try {
+      const cached = JSON.parse(readFileSync(mapPath(), 'utf-8'));
+      const idx = cached && cached.key === key ? cached.map[token] : null;
+      if (Array.isArray(idx) && idx.length > 0) {
+        for (const i of idx) {
+          const [path, name] = registrars[i];
+          const mod = await import(new URL(path, baseUrl).href);
+          mod[name](program, ctx);
+        }
+        if (program.commands.some((c) => c.name() === token || c.aliases().includes(token))) return 'lazy';
+      }
+    } catch { /* fall through to a full load */ }
+    // Partial registration (if any) must not double-register: start clean.
+    program.commands.splice(0, program.commands.length);
+  }
+  await fullLoad(program, ctx, registrars, baseUrl, key);
+  return 'full';
+}

package/lib/core/liveSessionsReport.js

@@ -0,0 +1,112 @@
+/**
+ * DEVSUITE phase 19: gather this host's tmux sessions into the payload for
+ * POST /api/v1/live-sessions/report. Pure parse/map functions take injected
+ * tmux output and held-slots JSON so they unit-test without tmux.
+ */
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+export const TMUX_FORMAT = '#{session_name}\t#{session_created}\t#{session_attached}\t#{pane_current_command}\t#{pane_pid}\t#{session_activity}';
+
+const AGENT_PROGRAMS = new Set(['claude', 'codex', 'gemini']);
+
+/** Parse `tmux list-panes -a -F TMUX_FORMAT` output; one entry per session (first pane wins). */
+export function parseTmuxPanes(out) {
+  const seen = new Map();
+  for (const line of String(out || '').split('\n')) {
+    const c = line.split('\t');
+    if (c.length < 5 || !c[0]) continue;
+    if (seen.has(c[0])) continue;
+    const created = Number(c[1]);
+    const pid = Number.parseInt(c[4], 10);
+    const activity = Number(c[5]);
+    seen.set(c[0], {
+      name: c[0],
+      tmux: true,
+      attached: Number(c[2]) > 0,
+      program: c[3] || null,
+      pid: Number.isInteger(pid) ? pid : null,
+      started_at: Number.isFinite(created) && created > 0 ? new Date(created * 1000).toISOString() : null,
+      last_active: Number.isFinite(activity) && activity > 0 ? new Date(activity * 1000).toISOString() : null,
+    });
+  }
+  return [...seen.values()];
+}
+
+/** held-slots.json is { slotName: { session, pid, ... } }; return { holderSession: { slot, pid } }. */
+export function slotsBySession(held) {
+  const map = {};
+  if (!held || typeof held !== 'object') return map;
+  for (const [slot, e] of Object.entries(held)) {
+    if (e && typeof e.session === 'string' && e.session && !(e.session in map)) {
+      map[e.session] = { slot, pid: Number.isInteger(e.pid) ? e.pid : null };
+    }
+  }
+  return map;
+}
+
+/**
+ * Attach kits live at ~/.quox/attach/sessions/claude-<pid>/<agentId>/, where
+ * <pid> is the claude process the slot entry records. Read ONLY the agent dir
+ * name and the plain `splinter` label file (e.g. "S2 1"); never the token.
+ */
+export function readAttachSafe(pid, base = join(homedir(), '.quox', 'attach', 'sessions')) {
+  if (!Number.isInteger(pid)) return null;
+  try {
+    const dir = join(base, `claude-${pid}`);
+    if (!existsSync(dir)) return null;
+    const agent = readdirSync(dir).find((d) => /^[a-z0-9_-]{1,40}$/.test(d));
+    if (!agent) return null;
+    let splinter = null;
+    const sp = join(dir, agent, 'splinter');
+    if (existsSync(sp)) {
+      const m = /^(S\d{1,3})\b/.exec(readFileSync(sp, 'utf-8').trim());
+      if (m) splinter = m[1];
+    }
+    return { agent, splinter };
+  } catch {
+    return null;
+  }
+}
+
+export function buildReport({ tmuxOut, held, env = {}, host, attachLookup = readAttachSafe }) {
+  const bySession = slotsBySession(held);
+  const sessions = parseTmuxPanes(tmuxOut).slice(0, 50).map((s) => {
+    // `quox claude --resume NAME` runs NAME in tmux session quox-NAME, while
+    // the slot entry records the bare NAME.
+    const bare = s.name.replace(/^quox-/, '');
+    const hit = bySession[s.name] || bySession[bare] || null;
+    const { last_active: lastActive, ...rest } = s;
+    const out = { ...rest, slot: hit ? hit.slot : null };
+    const att = hit ? attachLookup(hit.pid) : null;
+    if (att) {
+      out.agent = att.agent;
+      if (att.splinter) out.splinter = att.splinter;
+    }
+    // No stream from env: QUOX_STREAM goes stale in inherited shells (house
+    // rule, and it mislabelled VULCAN as QUOX-SECURITY on the first live run).
+    // The column stays for a reliable source later (slot or attach metadata).
+    // last_active (tmux session_activity) feeds the J1 index's working/resting state.
+    out.meta = { agent_program: AGENT_PROGRAMS.has(s.program), ...(lastActive ? { last_active: lastActive } : {}) };
+    return out;
+  });
+  return { host: host || hostname(), sessions };
+}
+
+export function readHeldSlotsSafe(path = join(homedir(), '.quox', 'held-slots.json')) {
+  try {
+    if (!existsSync(path)) return {};
+    return JSON.parse(readFileSync(path, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/** Live gather. Returns null when tmux is missing; an empty server yields an empty list. */
+export function gatherReport({ spawn = spawnSync, env = process.env, held = readHeldSlotsSafe() } = {}) {
+  const r = spawn('tmux', ['list-panes', '-a', '-F', TMUX_FORMAT], { encoding: 'utf8' });
+  if (r.error) return null;
+  return buildReport({ tmuxOut: r.status === 0 ? r.stdout : '', held, env });
+}