@idl3/claude-control 0.1.20 → 0.1.22

package/README.md

@@ -20,6 +20,16 @@ npm install -g @idl3/claude-control     # or run once: npx @idl3/claude-control
 
 **Prerequisites:** Node ≥20 and **tmux** on your `PATH` (`brew install tmux` · `sudo apt install tmux`). Optional: **ttyd** for the in-browser raw terminal (`brew install ttyd` · `sudo apt install ttyd`) — set `CLAUDE_CONTROL_TTYD` to override its path. The web UI ships prebuilt — no build step on install.
 
+**Optional local AI (no API key):**
+
+- **Voice → text** — `brew install ffmpeg whisper-cpp` and drop a model at `~/.claude-control/models/ggml-base.en.bin`. The mic in the composer records audio and transcribes it locally.
+- **Prompt enhancer (✨)** — defaults to a **local MLX model** on Apple Silicon. One-time setup:
+  ```bash
+  python3 -m venv ~/.claude-control/mlx-venv
+  ~/.claude-control/mlx-venv/bin/pip install mlx-lm
+  ```
+  claude-control lazily starts `mlx_lm.server` on first use, keeps it warm, and shuts it down when idle. The model (default `mlx-community/Llama-3.2-3B-Instruct-4bit`, ~1.8 GB) auto-downloads on first run. Pick the backend + model in **Settings** (`mlx` → `claude -p` → rules fallback). Without the venv (or on non-Apple hardware) the enhancer falls back to `claude -p`, then a deterministic rules optimiser. Env overrides: `CLAUDE_CONTROL_MLX_PYTHON`, `CLAUDE_CONTROL_MLX_PORT`.
+
 ```bash
 claude-control                    # start the server (prints the URL)
 claude-control --help             # config + subcommands

package/lib/answer.js

@@ -4,7 +4,8 @@
 //   footer: "Enter to select · ↑/↓ to navigate · n to add notes · Tab to switch
 //            questions · Esc to cancel"
 //   spec:   single-select = ['Down'*index, 'Enter'];
-//           multi-select  = navigate Down to each chosen index, press Space, then Enter.
+//           multi-select  = Space-toggle each chosen index, then Down to the
+//                           per-question action row ("Next"/"Submit") + Enter.
 //
 //   - Each question lists its options vertically; a cursor starts on the FIRST
 //     option (index 0) and moves with Up/Down. There are NO number shortcuts —
@@ -12,11 +13,15 @@
 //     this UI (the cause of "answer sent but nothing happened").
 //   - SINGLE-select: navigate Down to the chosen option, then press Enter. Enter
 //     commits the answer and advances to the next question (or submits on the last).
-//   - MULTI-select: navigate Down to each chosen option (top-to-bottom, so a
-//     monotonic run of Downs) pressing Space to toggle it, then press Enter to
-//     confirm the question and advance/submit.
-//   - There is no separate "Submit" step: the final question's Enter submits the
-//     whole picker. (The old `Right`-to-Submit-tab + `'1'` model was stale.)
+//   - MULTI-select: Space toggles a checkbox; Enter on a checkbox ONLY toggles it
+//     (footer reads "Enter to select") and does NOT advance. So: Space-toggle each
+//     chosen option, then navigate Down to the action row — "Next" (non-final) or
+//     "Submit" (final) — at navigable index options.length + 1 (after the real
+//     options and the always-present "Type something" free-text row), then Enter.
+//     Enter on "Next" advances to the next question (cursor resets to 0); Enter on
+//     "Submit" submits the whole picker. (Pressing Enter on the last toggled
+//     option — the old model — left the second question unanswered + never
+//     submitted: the exact reported bug.)
 //
 // We deliberately avoid the `n` (add notes) key: it opens a free-text input that
 // would swallow every subsequent keystroke. Navigation is arrows + Space/Enter only.
@@ -24,6 +29,309 @@
 // Keys are sent one at a time with a delay (see tmux.sendRawKeysSequenced) so the
 // picker's re-render settles between keys and none are dropped.
 
+// ---------------------------------------------------------------------------
+// Picker capture parser — capture-driven answerer
+// ---------------------------------------------------------------------------
+//
+// Empirical picker model (reverse-engineered from live renders):
+//
+//   Navigable rows in order:
+//     1. Each real option:  "N. [ ]Label" or "N. [x]Label" or "N. [✓]Label"
+//        Below each option there may be DIMMED DESCRIPTION lines — these are
+//        NOT navigable and Up/Down skip them.
+//     2. "Type something"  — always present free-text row.
+//     3. Action row        — literal "Next" (non-final) or "Submit" (final).
+//     4. "Chat about this" — always present last row.
+//
+//   Cursor:   row is marked at line start with "›" or "❯" (possibly with
+//             leading whitespace / ANSI stripped text before it).
+//
+//   Review screen (multi-question only, appears after final Submit):
+//     "Review your answers … Ready to submit your answers?"
+//     "› 1. Submit answers"
+//     "2. Cancel"
+//
+// The parser strips ANSI escape sequences before analysis so it works on both
+// plain and escape-laden captures.
+
+/**
+ * @typedef {{
+ *   kind: 'option'|'type-something'|'action'|'chat'|'review-submit'|'review-cancel',
+ *   label: string,
+ *   checked?: boolean,
+ *   cursor: boolean
+ * }} PickerRow
+ *
+ * @typedef {{
+ *   rows: PickerRow[],
+ *   actionLabel: 'Next'|'Submit'|null,
+ *   isReview: boolean,
+ *   confidence: 'ok'|'low'
+ * }} ParsedPicker
+ */
+
+// Strip ANSI escape sequences from a string.
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return str.replace(/\x1b\[[0-9;]*[A-Za-z]/g, '').replace(/\x1b\][^\x07]*\x07/g, '');
+}
+
+// Detect cursor marker at the start of a (stripped, trimmed) line.
+function hasCursor(line) {
+  return /^[›❯]/.test(line.trim());
+}
+
+// Remove the cursor marker from a line and trim.
+function removeCursor(line) {
+  return line.trim().replace(/^[›❯]\s*/, '');
+}
+
+// Detect an option line: "N. [ ] Label" / "N. [x] Label" / "N. [✓] Label"
+// Also handles "N. [✓]Label" without space after bracket.
+const OPTION_RE = /^\d+\.\s+\[([✓x✗ ])\]\s*(.*)/;
+
+/**
+ * Parse the visible content of a tmux pane into a structured picker model.
+ *
+ * Returns a low-confidence result (confidence:'low', rows:[]) rather than
+ * throwing when the capture doesn't look like a picker at all.
+ *
+ * @param {string} capture  Raw text from tmux capture-pane.
+ * @returns {ParsedPicker}
+ */
+export function parsePicker(capture) {
+  const EMPTY = { rows: [], actionLabel: null, isReview: false, confidence: 'low' };
+
+  if (!capture || typeof capture !== 'string') return EMPTY;
+
+  const raw = stripAnsi(capture);
+  const lines = raw.split('\n');
+
+  // Detect review screen first — it's structurally different.
+  const hasReviewHeader = lines.some((l) => /Review your answers/i.test(l));
+  const hasReadyLine = lines.some((l) => /Ready to submit your answers/i.test(l));
+
+  if (hasReviewHeader && hasReadyLine) {
+    // Parse the two review options.
+    const rows = [];
+    for (const rawLine of lines) {
+      const stripped = stripAnsi(rawLine);
+      const cursor = hasCursor(stripped);
+      const line = removeCursor(stripped);
+      if (/1\.\s+Submit answers/i.test(line)) {
+        rows.push({ kind: 'review-submit', label: 'Submit answers', cursor });
+      } else if (/2\.\s+Cancel/i.test(line)) {
+        rows.push({ kind: 'review-cancel', label: 'Cancel', cursor });
+      }
+    }
+    if (rows.length === 0) return EMPTY;
+    return { rows, actionLabel: null, isReview: true, confidence: 'ok' };
+  }
+
+  // Normal question screen.
+  // Strategy: scan lines, classify each as option / description / special.
+  // Description lines follow an option and do NOT match the option pattern,
+  // are not cursor-marked, and don't match any other special marker.
+
+  /** @type {PickerRow[]} */
+  const rows = [];
+  /** @type {'Next'|'Submit'|null} */
+  let actionLabel = null;
+
+  // Track whether we've seen at least one option (to know if we're past options).
+  let seenOption = false;
+  // Track whether the most-recently-seen navigable row was an option, so the
+  // next plain text line can be classified as a description.
+  let lastNavWasOption = false;
+
+  for (const rawLine of lines) {
+    const stripped = stripAnsi(rawLine);
+    const cursor = hasCursor(stripped);
+    const line = removeCursor(stripped);
+    const trimmed = line.trim();
+
+    if (!trimmed) continue;
+
+    // Option line: "N. [x] Label" — match first, then check if it's a special
+    // known row (Type something, Chat about this) that happens to be numbered.
+    const optMatch = trimmed.match(OPTION_RE);
+    if (optMatch) {
+      const checkChar = optMatch[1]; // ' ', 'x', '✓', '✗'
+      const label = optMatch[2].trim();
+
+      // "Type something" can appear as a numbered checkbox row.
+      if (/^Type something$/i.test(label)) {
+        rows.push({ kind: 'type-something', label: 'Type something', cursor });
+        lastNavWasOption = false;
+        continue;
+      }
+
+      // "Chat about this" can appear as a numbered checkbox row.
+      if (/^Chat about this$/i.test(label)) {
+        rows.push({ kind: 'chat', label: 'Chat about this', cursor });
+        lastNavWasOption = false;
+        continue;
+      }
+
+      const checked = checkChar !== ' ';
+      rows.push({ kind: 'option', label, checked, cursor });
+      seenOption = true;
+      lastNavWasOption = true;
+      continue;
+    }
+
+    // "Type something" row — the free-text row when not in option format.
+    if (/^Type something/i.test(trimmed)) {
+      rows.push({ kind: 'type-something', label: 'Type something', cursor });
+      lastNavWasOption = false;
+      continue;
+    }
+
+    // Action row — "Next" or "Submit" (bare word on its own line, appears AFTER
+    // "Type something"). Must appear at start of line content (after cursor strip).
+    if (/^Next$/i.test(trimmed)) {
+      rows.push({ kind: 'action', label: 'Next', cursor });
+      actionLabel = 'Next';
+      lastNavWasOption = false;
+      continue;
+    }
+    if (/^Submit$/i.test(trimmed)) {
+      rows.push({ kind: 'action', label: 'Submit', cursor });
+      actionLabel = 'Submit';
+      lastNavWasOption = false;
+      continue;
+    }
+
+    // "Chat about this" row — may appear bare or as a numbered line "N. Chat about this".
+    {
+      const bareLabel = trimmed.replace(/^\d+\.\s+/, '');
+      if (/^Chat about this/i.test(bareLabel) || /^Chat about this/i.test(trimmed)) {
+        rows.push({ kind: 'chat', label: 'Chat about this', cursor });
+        lastNavWasOption = false;
+        continue;
+      }
+    }
+
+    // Footer line — skip (keyboard hint at the bottom).
+    if (/Enter to select|↑.↓ to navigate|Esc to cancel/i.test(trimmed)) continue;
+
+    // Tab-bar line (e.g. "←  ⊠ Fruits   □ Colors   ✔ Submit   →") — skip.
+    if (/←.*→/.test(trimmed)) continue;
+
+    // Question text / header — skip if we haven't seen any option yet.
+    if (!seenOption) continue;
+
+    // Otherwise: if the previous navigable row was an option, this is a
+    // description line below it — skip (not navigable).
+    if (lastNavWasOption) continue;
+
+    // Anything else after options: skip (question text bleed, etc.).
+  }
+
+  // Need at least one option or "Type something" to call it a picker.
+  if (rows.filter((r) => r.kind === 'option' || r.kind === 'type-something').length === 0) {
+    return EMPTY;
+  }
+
+  return { rows, actionLabel, isReview: false, confidence: 'ok' };
+}
+
+/**
+ * Given a parsed picker for ONE question and the desired selections, compute
+ * the keystroke sequence to toggle the right options and press the action row.
+ *
+ * Returns null when confidence is insufficient (unknown option label, no action
+ * row found, etc.) — caller must fall back to the static model.
+ *
+ * @param {ParsedPicker} parsed
+ * @param {{ multiSelect?: boolean, options: {label:string}[] }} question
+ * @param {string[]} selectedLabels
+ * @returns {string[]|null}
+ */
+export function planStep(parsed, question, selectedLabels) {
+  if (!parsed || parsed.confidence !== 'ok' || parsed.isReview) return null;
+
+  const { rows, actionLabel } = parsed;
+
+  // Navigable rows are everything EXCEPT descriptions (which we already excluded
+  // in parsePicker). All rows in the list are navigable.
+  const navRows = rows;
+
+  if (navRows.length === 0) return null;
+
+  if (!question.multiSelect) {
+    // Single-select: find the target option by label, Down to it, Enter.
+    if (!selectedLabels || selectedLabels.length === 0) return null;
+    const targetLabel = selectedLabels[0];
+    const targetIdx = navRows.findIndex(
+      (r) => r.kind === 'option' && r.label === targetLabel,
+    );
+    if (targetIdx < 0) return null;
+
+    // Cursor position from the parsed state.
+    const cursorIdx = navRows.findIndex((r) => r.cursor);
+    const fromIdx = cursorIdx >= 0 ? cursorIdx : 0;
+
+    const keys = [];
+    const delta = targetIdx - fromIdx;
+    if (delta > 0) {
+      for (let i = 0; i < delta; i += 1) keys.push('Down');
+    } else if (delta < 0) {
+      for (let i = 0; i < -delta; i += 1) keys.push('Up');
+    }
+    keys.push('Enter');
+    return keys;
+  }
+
+  // Multi-select: for each label, verify it exists, then compute toggle plan.
+  if (!selectedLabels || selectedLabels.length === 0) return null;
+
+  // Resolve label → navigable index for all targets.
+  const targetIndices = selectedLabels.map((label) =>
+    navRows.findIndex((r) => r.kind === 'option' && r.label === label),
+  );
+  if (targetIndices.some((i) => i < 0)) return null; // unknown label — bail
+
+  // Sort ascending for top-to-bottom navigation.
+  targetIndices.sort((a, b) => a - b);
+
+  // Find action row index.
+  const actionIdx = navRows.findIndex((r) => r.kind === 'action');
+  if (actionIdx < 0) return null; // no action row visible — bail
+
+  const cursorIdx = navRows.findIndex((r) => r.cursor);
+  let cursor = cursorIdx >= 0 ? cursorIdx : 0;
+
+  const keys = [];
+
+  for (const target of targetIndices) {
+    // Navigate to the target option.
+    const delta = target - cursor;
+    if (delta > 0) {
+      for (let i = 0; i < delta; i += 1) keys.push('Down');
+    } else if (delta < 0) {
+      for (let i = 0; i < -delta; i += 1) keys.push('Up');
+    }
+    // Toggle: only Space if the current checked state ≠ desired (checked).
+    // The picker starts with all unchecked; we always want to check the targets.
+    // If it's already checked (pre-ticked), Space would UN-check — skip it.
+    const row = navRows[target];
+    if (!row.checked) keys.push('Space');
+    cursor = target;
+  }
+
+  // Navigate to the action row and Enter.
+  const actionDelta = actionIdx - cursor;
+  if (actionDelta > 0) {
+    for (let i = 0; i < actionDelta; i += 1) keys.push('Down');
+  } else if (actionDelta < 0) {
+    for (let i = 0; i < -actionDelta; i += 1) keys.push('Up');
+  }
+  keys.push('Enter');
+
+  return keys;
+}
+
 /**
  * Resolve the selected labels to option indices, in top-to-bottom order.
  * @param {{options: {label:string}[]}} question
@@ -62,15 +370,26 @@ export function buildAnswerKeys(question, selectedLabels) {
     return keys;
   }
 
-  // Multi-select: walk down through the chosen options in order, toggling each
-  // with Space; the cursor starts at option 0, so move only the delta between
-  // successive targets. A trailing Enter confirms the question.
+  // Multi-select: toggle each chosen option with Space (cursor starts at option
+  // 0; move only the delta between successive targets). Then navigate DOWN to the
+  // per-question action row — "Next" on a non-final question, "Submit" on the
+  // final one — and press Enter to activate it.
+  //
+  // CRITICAL (verified empirically against the live picker): the footer is
+  // "Enter to select", so Enter on a CHECKBOX only toggles it — it does NOT
+  // advance/submit. The action row sits at navigable index options.length + 1:
+  // the real options [0..N-1], then the always-present "Type something" free-text
+  // row [N], then "Next"/"Submit" [N+1] (then "Chat about this" [N+2]). The OLD
+  // model pressed Enter while still on the last option, so it never advanced —
+  // the second question went unanswered and the picker never submitted.
   let cursor = 0;
   for (const target of indices) {
     for (let i = cursor; i < target; i += 1) keys.push('Down');
     keys.push('Space');
     cursor = target;
   }
+  const actionRow = (question.options?.length ?? 0) + 1;
+  for (let i = cursor; i < actionRow; i += 1) keys.push('Down');
   keys.push('Enter');
   return keys;
 }
@@ -91,5 +410,12 @@ export function buildAnswerProgram(pending, selections) {
   for (let i = 0; i < questions.length; i += 1) {
     program.push(...buildAnswerKeys(questions[i], selections?.[i] || []));
   }
+  // Multi-question pickers carry a final "Submit" tab: after the last question's
+  // action-row Enter, the picker lands on a "Review your answers · Submit answers /
+  // Cancel" screen with "Submit answers" highlighted. One more Enter confirms +
+  // closes it. (Verified live: without this, every question was answered correctly
+  // but the picker sat on the review screen, unsubmitted.) Single-question pickers
+  // have no review step — the question's own Enter submits.
+  if (questions.length > 1) program.push('Enter');
   return program;
 }

package/lib/claude-cli.js

@@ -0,0 +1,170 @@
+/**
+ * lib/claude-cli.js — LLM backend that spawns the host Claude CLI.
+ *
+ * No API key required. Uses the same `claude` binary that the operator already
+ * has installed. Lean flags cut cost ~28x by disabling MCP and tools.
+ *
+ * Exports:
+ *  - resolveClaudeBin()  → string | null   (abs path or null; re-reads config each call)
+ *  - parseResult(stdout) → string          (pure; throws on bad envelope)
+ *  - complete(prompt, { model }) → Promise<string>
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execFileSync, spawn } from 'node:child_process';
+
+import { readConfig } from './config.js';
+
+// ---------------------------------------------------------------------------
+// Empty MCP config: written once at module init to a stable temp path so the
+// --mcp-config flag always points at a valid (empty) file.
+// ---------------------------------------------------------------------------
+const EMPTY_MCP_PATH = path.join(os.tmpdir(), 'claude-control-empty-mcp.json');
+
+function ensureEmptyMcpConfig() {
+  if (!fs.existsSync(EMPTY_MCP_PATH)) {
+    fs.writeFileSync(EMPTY_MCP_PATH, '{"mcpServers":{}}', { mode: 0o600 });
+  }
+}
+
+try {
+  ensureEmptyMcpConfig();
+} catch {
+  // Non-fatal: complete() will fail if the path is missing, which is fine.
+}
+
+// ---------------------------------------------------------------------------
+// Binary resolution — re-reads config each call so tests can control it via
+// writeConfig({ claudeBin: ... }) without module-level memoization.
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the absolute path of the claude CLI binary.
+ * Resolution order:
+ *  1. config.claudeBin if set and exists
+ *  2. `which claude` result if exists
+ *  3. Common installation paths, first that exists
+ *
+ * Re-reads config each call (cheap; avoids memoization that breaks tests).
+ *
+ * @returns {string | null}
+ */
+export function resolveClaudeBin() {
+  const config = readConfig();
+
+  // 1. Explicit config override
+  if (config.claudeBin && typeof config.claudeBin === 'string' && config.claudeBin.trim()) {
+    const p = config.claudeBin.trim();
+    if (fs.existsSync(p)) return p;
+  }
+
+  // 2. `which claude`
+  try {
+    const found = execFileSync('which', ['claude'], { encoding: 'utf8' }).trim();
+    if (found && fs.existsSync(found)) return found;
+  } catch {
+    // not on PATH
+  }
+
+  // 3. Common paths
+  const candidates = [
+    path.join(os.homedir(), '.local', 'bin', 'claude'),
+    '/opt/homebrew/bin/claude',
+    '/usr/local/bin/claude',
+    '/usr/bin/claude',
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Envelope parser — pure, no I/O, fully testable without spawning.
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the JSON stdout envelope from `claude -p ... --output-format json`.
+ * Throws on malformed JSON, is_error:true, or missing .result.
+ *
+ * Expected envelope:
+ *   { type: 'result', subtype: 'success', is_error: false, result: string, ... }
+ *
+ * @param {string} stdout
+ * @returns {string}
+ */
+export function parseResult(stdout) {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(`claude CLI: invalid JSON in stdout: ${err.message}`);
+  }
+  if (parsed && parsed.is_error === true) {
+    throw new Error(`claude CLI: is_error=true: ${parsed.result ?? '(no message)'}`);
+  }
+  if (!parsed || typeof parsed.result !== 'string') {
+    throw new Error('claude CLI: missing .result in envelope');
+  }
+  return parsed.result;
+}
+
+// ---------------------------------------------------------------------------
+// complete — spawn the CLI and return the result string.
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a prompt through the Claude CLI and return the text result.
+ *
+ * @param {string} prompt
+ * @param {{ model?: string }} [opts]
+ * @returns {Promise<string>}
+ */
+export function complete(prompt, { model } = {}) {
+  return new Promise((resolve, reject) => {
+    const bin = resolveClaudeBin();
+    if (!bin) {
+      return reject(new Error('claude CLI not found'));
+    }
+
+    ensureEmptyMcpConfig();
+
+    const resolvedModel = model ?? readConfig().optimizeModel ?? 'claude-haiku-4-5';
+
+    // Lean flags: -p (print mode), --output-format json, no tools, empty MCP.
+    // Prompt is passed as a direct argv element — never shell-interpolated.
+    const args = [
+      '-p', prompt,
+      '--model', resolvedModel,
+      '--output-format', 'json',
+      '--strict-mcp-config',
+      '--mcp-config', EMPTY_MCP_PATH,
+      '--allowed-tools', '',
+    ];
+
+    const child = spawn(bin, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+
+    child.stdout.on('data', (chunk) => stdoutChunks.push(chunk));
+    child.stderr.on('data', (chunk) => stderrChunks.push(chunk));
+
+    child.on('close', (code) => {
+      if (code !== 0) {
+        const stderrText = Buffer.concat(stderrChunks).toString('utf8').slice(0, 300);
+        return reject(new Error(`claude CLI exited ${code}: ${stderrText}`));
+      }
+      const stdout = Buffer.concat(stdoutChunks).toString('utf8');
+      try {
+        resolve(parseResult(stdout));
+      } catch (err) {
+        reject(err);
+      }
+    });
+
+    child.on('error', (err) => reject(err));
+  });
+}