phewsh 0.15.7 → 0.15.10

package/commands/clarify.js

@@ -37,7 +37,7 @@ async function askForInput() {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
   return new Promise((resolve) => {
     console.log('\n  Describe what you\'re building. Be as messy as you want.\n');
-    console.log('  (You\'re the David Rose. PHEWSH is the business registration clerk.)\n');
+    console.log('  (You bring the messy idea. PHEWSH compiles it into a clear, structured spec.)\n');
     process.stdout.write('  > ');
     let input = '';
     rl.on('line', (line) => { input += (input ? ' ' : '') + line.trim(); });

package/commands/session.js

@@ -244,6 +244,13 @@ async function streamChat(apiKey, messages, systemPrompt, modelId, opts = {}) {
   let completionTokens = null;
   let firstToken = true;
 
+  // Line-buffered markdown render at a TTY; raw passthrough otherwise. The
+  // spinner stops on first rendered output, not first raw token.
+  const stopSpin = () => { if (firstToken) { spin.stop(); firstToken = false; } };
+  const render = process.stdout.isTTY
+    ? require('../lib/md').streamRenderer((out) => { stopSpin(); process.stdout.write(out); })
+    : null;
+
   for await (const chunk of response.body) {
     const text = Buffer.from(chunk).toString('utf-8');
     const lines = text.split('\n').filter(l => l.startsWith('data: '));
@@ -253,11 +260,8 @@ async function streamChat(apiKey, messages, systemPrompt, modelId, opts = {}) {
       try {
         const parsed = JSON.parse(data);
         if (parsed.type === 'content_block_delta' && parsed.delta?.text) {
-          if (firstToken) {
-            spin.stop();
-            firstToken = false;
-          }
-          process.stdout.write(parsed.delta.text);
+          if (render) render.push(parsed.delta.text);
+          else { stopSpin(); process.stdout.write(parsed.delta.text); }
           fullResponse += parsed.delta.text;
         }
         if (parsed.type === 'message_start' && parsed.message?.usage) {
@@ -270,6 +274,7 @@ async function streamChat(apiKey, messages, systemPrompt, modelId, opts = {}) {
     }
   }
 
+  if (render) render.flush();
   if (firstToken) spin.stop();
   process.stdout.write('\n');
 
@@ -331,9 +336,12 @@ async function main() {
   await ui.brandReveal();
 
   if (config?.apiKey && !config.apiKey.startsWith('sk-')) {
-    console.log(`  ${ember('!')} ${sage('Stored API key looks invalid — ignoring it.')} ${slate('/key to replace')}`);
+    // Persist the cleanup so this never nags again — an unusable key
+    // (not sk-…) helps nobody, and harness routes need no key at all.
+    console.log(`  ${ember('!')} ${sage('Cleared an unusable stored API key.')} ${slate('harness routes need none — /key to add one')}`);
     console.log('');
     config.apiKey = null;
+    try { saveConfig(config); } catch { /* read-only home — in-memory clear still holds */ }
     route = resolveRoute(config, harnesses);
   }
 

package/lib/harnesses.js

@@ -20,7 +20,7 @@ const { execSync, spawn } = require('child_process');
 // list of its own, so it can never go stale. Harnesses without a known
 // model flag ignore the preference and use their own config.
 const HARNESSES = {
-  'claude-code': { bin: 'claude',       label: 'Claude Code',  role: 'writes code',          auth: 'Claude subscription / Console', models: true, modelHints: ['sonnet', 'opus', 'haiku', 'fable'], args: (p, m) => ['-p', p, '--output-format', 'text', ...(m ? ['--model', m] : [])] },
+  'claude-code': { bin: 'claude',       label: 'Claude Code',  role: 'writes code',          auth: 'Claude subscription / Console', models: true, modelHints: ['sonnet', 'opus', 'haiku'], streamFormat: 'claude-json', args: (p, m) => ['-p', p, '--output-format', 'stream-json', '--include-partial-messages', '--verbose', ...(m ? ['--model', m] : [])] },
   'codex':       { bin: 'codex',        label: 'Codex CLI',    role: 'reasons & reviews',    auth: 'ChatGPT plan',                  models: true, args: (p, m) => ['exec', '--skip-git-repo-check', ...(m ? ['-m', m] : []), p] },
   'gemini':      { bin: 'gemini',       label: 'Gemini CLI',   role: "another model's take", auth: 'Google login',                  models: true, args: (p, m) => ['-p', p, ...(m ? ['-m', m] : [])] },
   'cursor':      { bin: 'cursor-agent', label: 'Cursor Agent', role: 'edits files',          auth: 'Cursor account',                models: true, args: (p, m) => ['-p', p, '--output-format', 'text', ...(m ? ['--model', m] : [])] },
@@ -87,6 +87,17 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
   const prompt = systemPrompt ? `${systemPrompt}\n\n---\n\n${userPrompt}` : userPrompt;
   const model = h.models ? opts.model : undefined;
 
+  // Spinner during the wait, and live token streaming where the harness
+  // supports it — no path is ever a dead blank screen. quiet (council) parses
+  // silently so parallel runs don't interleave into soup.
+  // Output is written whenever this isn't a quiet (council) run. The spinner
+  // additionally needs a TTY — piped/test contexts get the text, no spinner.
+  const show = !opts.quiet;
+  let spin = null;
+  if (show && process.stdout.isTTY) {
+    try { spin = require('./ui').spinner('thinking'); } catch { spin = null; }
+  }
+
   return new Promise((resolve, reject) => {
     const child = spawn(h.bin, h.args(prompt, model), { stdio: ['pipe', 'pipe', 'pipe'] });
     ACTIVE_CHILDREN.add(child);
@@ -94,20 +105,85 @@ function runViaHarness(id, systemPrompt, userPrompt, opts = {}) {
     // Some harnesses (codex exec, gemini) wait for stdin EOF before running.
     child.stdin.end();
 
-    let stdout = '';
     let stderr = '';
-    // quiet: collect without streaming — parallel runs (council) would
-    // interleave live output into soup.
-    if (!opts.quiet) process.stdout.write('\n');
-    child.stdout.on('data', (d) => { if (!opts.quiet) process.stdout.write(d); stdout += d.toString(); });
+    let assembled = '';        // raw text — returned + kept in history (never ANSI)
+    let resultFallback = '';   // claude's final `result` field — never-blank guard
+    let jsonBuf = '';
+    let firstByte = false;
+
+    // Spinner stop + leading newline fire on first *displayed* output, so the
+    // line-buffered renderer never leaves a spinner-stopped-but-blank gap.
+    function onFirstShow() {
+      if (firstByte) return;
+      firstByte = true;
+      if (spin) { spin.stop(); spin = null; }
+      if (show) process.stdout.write('\n');
+    }
+    // Render markdown only at a real TTY; pipes/quiet get raw passthrough so
+    // council parsing and scripted use stay clean (no stray ANSI).
+    const render = (show && process.stdout.isTTY)
+      ? require('./md').streamRenderer((out) => { onFirstShow(); process.stdout.write(out); })
+      : null;
+
+    function emit(text) {
+      if (!text) return;
+      assembled += text; // always raw
+      if (render) render.push(text);
+      else if (show) { onFirstShow(); process.stdout.write(text); }
+    }
+
+    child.stdout.on('data', (d) => {
+      if (h.streamFormat === 'claude-json') {
+        // Newline-delimited JSON: each line is one event. text_delta events
+        // carry the live tokens; the final `result` is the fallback.
+        jsonBuf += d.toString();
+        let nl;
+        while ((nl = jsonBuf.indexOf('\n')) !== -1) {
+          const line = jsonBuf.slice(0, nl).trim();
+          jsonBuf = jsonBuf.slice(nl + 1);
+          if (!line) continue;
+          let obj;
+          // A complete line that isn't JSON is real output (plain-text error,
+          // or a non-streaming stub) — show it rather than swallow it.
+          try { obj = JSON.parse(line); } catch { emit(line + '\n'); continue; }
+          if (obj.type === 'stream_event'
+              && obj.event?.type === 'content_block_delta'
+              && obj.event.delta?.type === 'text_delta') {
+            emit(obj.event.delta.text);
+          } else if (obj.type === 'result' && typeof obj.result === 'string') {
+            resultFallback = obj.result;
+          }
+        }
+      } else {
+        emit(d.toString());
+      }
+    });
     child.stderr.on('data', (d) => { stderr += d.toString(); });
     child.on('close', (code) => {
-      if (!opts.quiet) process.stdout.write('\n');
+      if (spin) { spin.stop(); spin = null; }
+      if (h.streamFormat === 'claude-json' && jsonBuf.trim()) {
+        try {
+          const obj = JSON.parse(jsonBuf.trim());
+          if (obj.type === 'result' && typeof obj.result === 'string') resultFallback = obj.result;
+        } catch { /* partial trailing line */ }
+      }
+      if (render) render.flush(); // render any trailing partial line
+      // Streaming produced nothing but the result has text → show it. Never blank.
+      let finalText = assembled;
+      if (!assembled.trim() && resultFallback) {
+        finalText = resultFallback;
+        if (render) { render.push(resultFallback); render.flush(); }
+        else if (show) { onFirstShow(); process.stdout.write(resultFallback); }
+      }
+      if (show) process.stdout.write('\n');
       if (child._phewshCancelled) return reject(new Error(`${h.label} cancelled`));
-      if (code === 0) resolve(stdout);
+      if (code === 0) resolve(finalText);
       else reject(new Error(`${h.label} exited ${code}${stderr ? `\n  ${stderr.trim().split('\n').slice(-3).join('\n  ')}` : ''}`));
     });
-    child.on('error', (e) => reject(new Error(`Could not run ${h.bin}: ${e.message}`)));
+    child.on('error', (e) => {
+      if (spin) { spin.stop(); spin = null; }
+      reject(new Error(`Could not run ${h.bin}: ${e.message}`));
+    });
   });
 }
 

package/lib/md.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// Terminal markdown rendering, safe for line-buffered streaming.
+//
+// Each completed line is rendered on its own — no cursor movement, no
+// in-place rewrites. That is deliberate: mid-stream cursor tricks under line
+// wrapping are the exact Apple Terminal hazard that has bitten this project
+// before. We hold tokens until a newline, render that finished line, and print
+// it. The only block-level state carried across lines is the code-fence flag,
+// so fenced code renders literally instead of as inline markdown.
+
+const A = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  ital: '\x1b[3m', italOff: '\x1b[23m',
+  uline: '\x1b[4m',
+  cream: '\x1b[38;5;230m',  // bold emphasis
+  teal: '\x1b[38;5;79m',    // code, links, headers
+  sage: '\x1b[38;5;151m',   // list items
+  slate: '\x1b[38;5;247m',  // dividers, quotes, link urls
+};
+
+// Inline spans: bold, italic, code, links. `base` is the SGR sequence to
+// restore the line's colour after each span's reset, so the rest of the line
+// keeps its block colour. Pass '' for default-foreground body text.
+function inlineMd(t, base = '') {
+  return t
+    .replace(/\*\*([^*]+)\*\*/g, (_, x) => `${A.bold}${A.cream}${x}${A.reset}${base}`)
+    .replace(/(^|\W)\*([^*\n]+)\*(?=\W|$)/g, (_, p, x) => `${p}${A.ital}${x}${A.italOff}${base}`)
+    .replace(/`([^`]+)`/g, (_, x) => `${A.teal}${x}${A.reset}${base}`)
+    .replace(/\[([^\]]+)\]\(([^)]+)\)/g,
+      (_, x, u) => `${A.uline}${A.teal}${x}${A.reset}${base} ${A.dim}${A.slate}(${u})${A.reset}${base}`);
+}
+
+// Render one complete line, mutating `state` for block-level context.
+// Body text keeps the default terminal foreground (bright) — only structural
+// elements get colour, so a reply reads as a reply, not as dimmed UI chrome.
+function renderLine(line, state = {}) {
+  const fence = line.match(/^\s*```+\s*\w*\s*$/);
+  if (fence) {
+    state.inFence = !state.inFence;
+    return `  ${A.slate}${A.dim}┄┄┄${A.reset}`;
+  }
+  if (state.inFence) {
+    return `  ${A.teal}${line}${A.reset}`; // literal code, no inline md
+  }
+  if (/^#{1,2}\s/.test(line)) return `\n${A.bold}${A.teal}${inlineMd(line.replace(/^#+\s*/, ''), A.teal)}${A.reset}`;
+  if (/^#{3,}\s/.test(line)) return `${A.cream}${inlineMd(line.replace(/^#+\s*/, ''), A.cream)}${A.reset}`;
+  if (/^\s*[-*]\s/.test(line)) return `  ${A.teal}·${A.reset} ${A.sage}${inlineMd(line.replace(/^\s*[-*]\s*/, ''), A.sage)}${A.reset}`;
+  if (/^\s*\d+\.\s/.test(line)) return `  ${A.sage}${inlineMd(line.trim(), A.sage)}${A.reset}`;
+  if (/^\s*>\s?/.test(line)) return `  ${A.slate}${A.ital}${inlineMd(line.replace(/^\s*>\s?/, ''), A.slate)}${A.italOff}${A.reset}`;
+  if (/^---+\s*$/.test(line)) return `  ${A.slate}${'─'.repeat(40)}${A.reset}`;
+  if (line.trim() === '') return '';
+  return inlineMd(line, ''); // body: default foreground, inline styling only
+}
+
+// Line-buffered streaming renderer. Feed raw token text via push(); each time a
+// newline completes a line, the rendered line (with its trailing '\n') is handed
+// to write(). flush() renders any trailing partial line at stream end. The
+// caller's write() is where first-output side effects (stop the spinner, print a
+// leading newline) belong, so they fire on first *rendered* output, not on the
+// first raw token — no spinner-stopped-but-blank gap.
+function streamRenderer(write) {
+  let buf = '';
+  const state = { inFence: false };
+  return {
+    push(text) {
+      buf += text;
+      let nl;
+      while ((nl = buf.indexOf('\n')) !== -1) {
+        const line = buf.slice(0, nl);
+        buf = buf.slice(nl + 1);
+        write(renderLine(line, state) + '\n');
+      }
+    },
+    flush() {
+      if (buf.length) {
+        write(renderLine(buf, state) + '\n');
+        buf = '';
+      }
+    },
+  };
+}
+
+module.exports = { inlineMd, renderLine, streamRenderer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phewsh",
-  "version": "0.15.7",
+  "version": "0.15.10",
   "description": "Turn intent into action. Structure your thinking, execute your next step.",
   "bin": {
     "phewsh": "bin/phewsh.js"