catalyst-os 2.0.3 → 3.0.1

package/.catalyst/bin/install.js

@@ -86,6 +86,27 @@ function copyFile(src, dest) {
   return false;
 }
 
+/**
+ * Ensure the consuming project's .gitignore protects local secrets.
+ * If `.catalyst/` (or the secrets file) is already ignored, do nothing.
+ */
+function ensureGitignore(cwd) {
+  const guard = '.catalyst/secrets.local.yaml';
+  const gitignorePath = path.join(cwd, '.gitignore');
+  let content = '';
+  if (fs.existsSync(gitignorePath)) {
+    content = fs.readFileSync(gitignorePath, 'utf8');
+    const lines = content.split(/\r?\n/).map((l) => l.trim());
+    const covered = lines.some(
+      (l) => l === guard || l === '/.catalyst' || l === '.catalyst' || l === '.catalyst/'
+    );
+    if (covered) return;
+  }
+  const block = `${content && !content.endsWith('\n') ? '\n' : ''}\n# Catalyst OS local secrets (never commit)\n${guard}\n`;
+  fs.appendFileSync(gitignorePath, block);
+  console.log(`  ${green}✓${reset} Added ${guard} to .gitignore`);
+}
+
 /**
  * Install catalyst-os to current directory
  */
@@ -142,6 +163,14 @@ function install() {
     }
   }
 
+  // Install voice runtime (zero-dependency local meeting daemon for /meet-spec)
+  const voiceSrc = path.join(src, '.catalyst', 'voice');
+  const voiceDest = path.join(catalystDir, 'voice');
+  if (fs.existsSync(voiceSrc)) {
+    copyDir(voiceSrc, voiceDest);
+    console.log(`  ${green}✓${reset} Installed .catalyst/voice/`);
+  }
+
   // Create specs directory if it doesn't exist
   const specsDir = path.join(catalystDir, 'specs');
   if (!fs.existsSync(specsDir)) {
@@ -149,6 +178,23 @@ function install() {
     console.log(`  ${green}✓${reset} Created .catalyst/specs/`);
   }
 
+  // Create a local secrets file (git-ignored) if it doesn't exist yet.
+  // Optional — only needed for voice meetings (/meet-spec).
+  const secretsPath = path.join(catalystDir, 'secrets.local.yaml');
+  if (!fs.existsSync(secretsPath)) {
+    fs.writeFileSync(
+      secretsPath,
+      '# Catalyst OS — Local Secrets (git-ignored, never commit)\n' +
+        '# Optional. Only needed for /meet-spec voice meetings.\n' +
+        '# Get a key at https://elevenlabs.io (you pay for your own usage).\n' +
+        'elevenlabs_api_key: ""\n'
+    );
+    console.log(`  ${green}✓${reset} Created .catalyst/secrets.local.yaml`);
+  }
+
+  // Safety belt: ensure the local secrets file can never be committed.
+  ensureGitignore(cwd);
+
   // Install AGENTS.md
   const agentsMdSrc = path.join(src, 'AGENTS.md');
   const agentsMdDest = path.join(cwd, 'AGENTS.md');

package/.catalyst/main/project-config.yaml

@@ -33,3 +33,19 @@ git:
     red_phase: "test({scope}): write failing tests for {spec}"
     green_phase: "feat({scope}): implement {spec}"
 
+# Voice meetings (/meet-spec) — optional.
+# See .catalyst/voice/README.md for setup.
+voice:
+  enabled: false            # set true to enable /meet-spec
+  language: "en"            # meeting/conversation language (e.g. "tr"); artifacts stay English
+
+  # mode: diy = browser speech + local `claude -p` brain. FREE, no API key, needs Chrome.
+  #       bundled = ElevenLabs Conversational AI. Nicer voice, per-minute cost (BYOK).
+  mode: diy
+
+  # --- bundled mode only (ignored in diy) ---
+  # The ElevenLabs API key does NOT go here — it lives in .catalyst/secrets.local.yaml.
+  provider: elevenlabs
+  voice_id: ""              # optional ElevenLabs voice id
+  agent_id: ""              # ElevenLabs Conversational AI agent id
+

package/.catalyst/spec-structure.yaml

@@ -46,7 +46,7 @@ files:
     owner: arbiter
     purpose: Test results, quality checks
     created: audit-spec
-    updated_by: [arbiter, enforcer, sentinel, inquisitor, watcher]
+    updated_by: [arbiter, enforcer, sentinel, inquisitor, watcher, curator]
 
   assets/:
     owner: any

package/.catalyst/voice/README.md

@@ -0,0 +1,78 @@
+# Catalyst Voice Runtime
+
+Local browser meeting room for `/meet-spec`. **Zero npm dependencies** — Node stdlib
+only. Requires **Node >= 18** and the `claude` CLI on your PATH.
+
+Two modes, set by `voice.mode` in `.catalyst/main/project-config.yaml`:
+
+| | **diy** (default) | **bundled** |
+|---|---|---|
+| Speech | Browser Web Speech API | ElevenLabs Conversational AI |
+| Brain | Local `claude -p` | ElevenLabs agent (Claude LLM) |
+| Voice quality | Robotic (browser TTS) | Natural |
+| Cost | **Free** (uses your Claude) | ~$0.10–$1/min (ElevenLabs, BYOK) |
+| Setup | None — just Chrome | API key + agent (see below) |
+
+Both modes give the agent full read access to the codebase, docs, and web search, and
+both write the same `meeting.md` artifact. **Artifacts are always in English**, whatever
+language the meeting is spoken in (set `voice.language`, e.g. `"tr"`).
+
+## DIY mode (default — nothing to set up)
+
+```yaml
+voice:
+  enabled: true
+  language: "tr"      # or "en", etc.
+  mode: diy
+```
+
+Open the room (via `/meet-spec`), click **Start meeting**, and talk. Chrome transcribes
+your speech, `claude -p` answers from the real repo, and the browser speaks the reply.
+You can also **type** in the text box at any time (great when speech is misheard). Needs
+Chrome/Chromium for speech; in other browsers, the text box still works.
+
+## Bundled mode (optional — nicer voice, paid)
+
+1. **Get an ElevenLabs API key** at https://elevenlabs.io. Conversational AI is billed
+   **per minute** (~1,000 credits/min on credit plans), so prefer a plan with included
+   agent-minutes. Paste the key into `.catalyst/secrets.local.yaml`:
+   ```yaml
+   elevenlabs_api_key: "your-key-here"
+   ```
+2. **Create a Conversational AI agent** (dashboard): LLM = Claude; a spec-shaping
+   interviewer system prompt; a **client tool** named exactly **`investigate_codebase`**
+   with one **string** parameter **`query`**. For non-English, enable the **language
+   override** (Security/Overrides → Language) and use a multilingual TTS model
+   (`eleven_flash_v2_5`).
+3. **Point Catalyst at it**:
+   ```yaml
+   voice:
+     enabled: true
+     language: "tr"
+     mode: bundled
+     agent_id: "your-agent-id"
+   ```
+   The key is read server-side by `meet-server.js` and never reaches the browser, argv,
+   or env. Signed URLs are minted server-side; client tools run in the browser so they
+   reach `localhost` — nothing is exposed to the internet.
+
+## How it works
+
+```
+diy:      Browser (Web Speech)  ──text──►  meet-server /turn  ──►  claude -p (repo)  ──►  reply ──► browser TTS
+bundled:  Browser (ElevenLabs SDK)  ◄─voice─►  ElevenLabs agent
+              └─ investigate_codebase ─► meet-server /tool ─► claude -p (repo)
+```
+
+Clicking **End meeting** sends the transcript to the daemon, which folds it into
+`.catalyst/meetings/YYYY-MM-DD-{slug}/meeting.md` via one `claude -p` pass, then shuts down.
+
+## Run it manually
+
+```bash
+PORT=4399 \
+MEETING_DIR=".catalyst/meetings/2026-01-01-test" \
+MEETING_TOPIC="Test meeting" \
+node .catalyst/voice/meet-server.js
+# then open http://localhost:4399
+```

package/.catalyst/voice/artifact.js

@@ -0,0 +1,61 @@
+/**
+ * Meeting artifact generation for /meet-spec.
+ * Writes meeting.md (canonical, for /catalyze-spec) and meeting.html (rendered, for humans).
+ */
+const fs = require('fs');
+const path = require('path');
+
+function esc(s) {
+  return String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
+}
+
+// One-pass transcript summarizer (bundled mode, or when no live notes were produced).
+const SUMMARY_PROMPT = (topic, transcript) =>
+  `You are summarizing a spec-shaping meeting. Convert the transcript below into clean ` +
+  `Markdown that another command (/catalyze-spec) will use as the feature request.\n\n` +
+  `Write the notes in ENGLISH regardless of the language spoken in the meeting.\n\n` +
+  `Output EXACTLY these sections, nothing before or after:\n\n` +
+  `# Meeting: ${topic}\n\n## Summary\n(one paragraph)\n\n## Decisions\n(bullet list of ` +
+  `decisions reached; "None recorded." if none)\n\n## Action Items\n(bullet list of ` +
+  `requirements / things to build)\n\n## Open Questions\n(bullet list of unresolved ` +
+  `questions)\n\n## Transcript\n(the full transcript, lightly cleaned)\n\n` +
+  `--- TRANSCRIPT ---\n${transcript}`;
+
+// notesHtml is the browser-rendered notes (DIY); falls back to <pre> if absent.
+function writeArtifacts({ projectRoot, meetingDir, topic, notesMd, notesHtml, transcriptText, findings }) {
+  const dir = path.join(projectRoot, meetingDir);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const research = findings && findings.length
+    ? '\n\n## Research Findings\n\n' + findings.map((f) => `### ${f.query}\n\n${f.result}`).join('\n\n')
+    : '';
+  const notesBody = notesMd.startsWith('#') ? notesMd : `# Meeting: ${topic}\n\n${notesMd}`;
+  const md = `${notesBody}\n\n## Transcript\n\n${transcriptText}\n${research}`;
+  fs.writeFileSync(path.join(dir, 'meeting.md'), md);
+
+  const notesSection = notesHtml || `<pre>${esc(notesMd)}</pre>`;
+  const transcriptHtml = transcriptText.split('\n').map((l) => `<p>${esc(l)}</p>`).join('\n');
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8" />
+<title>Meeting: ${esc(topic)}</title>
+<style>
+  body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;max-width:820px;
+    margin:40px auto;padding:0 20px;line-height:1.6;color:#1a1a24}
+  h1{font-size:24px} h2{font-size:18px;margin-top:28px;border-bottom:1px solid #eee;padding-bottom:4px}
+  .notes{background:#faf9ff;border:1px solid #ece8ff;border-radius:10px;padding:18px 22px}
+  .transcript p{margin:2px 0;color:#444;font-size:14px}
+  code{background:#f3f1fa;padding:2px 5px;border-radius:4px}
+</style></head>
+<body>
+<h1>Meeting: ${esc(topic)}</h1>
+<section class="notes">${notesSection}</section>
+<h2>Transcript</h2>
+<div class="transcript">${transcriptHtml}</div>
+</body></html>
+`;
+  fs.writeFileSync(path.join(dir, 'meeting.html'), html);
+
+  return { mdPath: path.join(meetingDir, 'meeting.md'), htmlPath: path.join(meetingDir, 'meeting.html') };
+}
+
+module.exports = { writeArtifacts, SUMMARY_PROMPT };

package/.catalyst/voice/meet-server.js

@@ -0,0 +1,293 @@
+#!/usr/bin/env node
+/**
+ * Local voice-meeting daemon for /meet-spec.
+ *
+ * Zero npm dependencies: Node stdlib + global fetch (Node >= 18) + child_process.
+ *
+ * Two modes (project-config voice.mode):
+ *   diy      — browser Web Speech (free) + local `claude -p` brain. No ElevenLabs, no cost.
+ *   bundled  — ElevenLabs Conversational AI (better voice, per-minute cost).
+ *
+ * Responsibilities:
+ *   GET  /              serve the meeting room page (diy or bundled)
+ *   GET  /config        non-secret config for the browser (mode, agentId, language, topic)
+ *   GET  /signed-url     bundled: mint an ElevenLabs signed URL (key stays server-side)
+ *   POST /turn          diy: one conversational turn via headless `claude -p`
+ *   POST /tool          bundled: live codebase investigation via headless `claude -p`
+ *   POST /end           fold transcript (+ findings) into meeting.md, then shut down
+ *
+ * The ElevenLabs API key (bundled only) is read from .catalyst/secrets.local.yaml and
+ * never leaves this process (not the browser, not argv, not the environment).
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const { writeArtifacts, SUMMARY_PROMPT } = require('./artifact');
+
+const PROJECT_ROOT = process.cwd();
+const PORT = parseInt(process.env.PORT || '4399', 10);
+const MEETING_DIR = process.env.MEETING_DIR || '.catalyst/meetings/untitled';
+const MEETING_TOPIC = process.env.MEETING_TOPIC || 'Untitled meeting';
+
+// Read-only tool whitelist for headless claude runs. Non-listed tools are
+// auto-denied in -p mode, so there are no interactive permission hangs.
+const CLAUDE_TOOLS = 'Read,Grep,Glob,Task,WebSearch,WebFetch';
+
+// --- Config / secrets (minimal YAML reads, no parser dependency) ---
+
+function readScalar(relPath, key) {
+  try {
+    const txt = fs.readFileSync(path.join(PROJECT_ROOT, relPath), 'utf8');
+    const m = txt.match(new RegExp('^\\s*' + key + ':\\s*["\']?([^"\'\\n]*)["\']?', 'm'));
+    return m ? m[1].trim() : '';
+  } catch {
+    return '';
+  }
+}
+
+const API_KEY = readScalar('.catalyst/secrets.local.yaml', 'elevenlabs_api_key');
+const AGENT_ID = readScalar('.catalyst/main/project-config.yaml', 'agent_id');
+const VOICE_ID = readScalar('.catalyst/main/project-config.yaml', 'voice_id');
+const LANGUAGE = readScalar('.catalyst/main/project-config.yaml', 'language') || 'en';
+// bundled = ElevenLabs Conversational AI; diy = browser speech + local claude -p (free).
+const MODE = readScalar('.catalyst/main/project-config.yaml', 'mode') || 'bundled';
+const HTML_PATH = path.join(__dirname, MODE === 'diy' ? 'meeting-diy.html' : 'meeting.html');
+
+// In DIY mode the "agent" is claude -p itself, driven turn by turn.
+const PERSONA =
+  `You are Catalyst, a spec-shaping interviewer for this software project. Hold a focused, ` +
+  `friendly spoken meeting that turns a rough idea into a clear feature specification. ` +
+  `Speak in ${LANGUAGE === 'tr' ? 'Turkish' : "the user's language"}. Ask ONE question at a ` +
+  `time and keep each spoken turn short (1-3 sentences). You have full read access to this ` +
+  `repository, its documentation, and web search — use them to ground your questions and ` +
+  `answers; never guess about the code. Drive toward: the problem, scope, concrete ` +
+  `requirements, key decisions, and action items. Be patient: if the user is brief or silent, ` +
+  `wait — never nag with "are you there?".\n\n` +
+  `OUTPUT FORMAT (strict, every turn): first your spoken words ONLY (no markdown). Then a ` +
+  `line containing exactly ===NOTES=== . Then the running meeting notes in Markdown, IN ` +
+  `ENGLISH, cumulative (carry forward everything so far and refine it), with these sections:\n` +
+  `## Summary\n## Decisions\n## Action Items\n## Open Questions\n` +
+  `The spoken part is for text-to-speech; the notes part is never spoken.`;
+
+const NOTES_DELIM = '===NOTES===';
+
+// Live investigation findings, folded into the artifact at the end.
+const findings = [];
+// DIY conversation session (claude -p --resume keeps context across turns).
+let sessionId = null;
+// Latest running notes (Markdown) maintained across DIY turns.
+let latestNotes = '';
+
+// --- Headless claude bridge ---
+
+function runClaude(prompt, timeoutMs) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('claude', ['-p', '--allowedTools', CLAUDE_TOOLS], {
+        cwd: PROJECT_ROOT,
+      });
+    } catch (e) {
+      return resolve(`(could not start claude: ${e.message})`);
+    }
+    let out = '';
+    let err = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      resolve(out.trim() || '(investigation timed out)');
+    }, timeoutMs);
+
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolve(`(claude not available: ${e.message})`);
+    });
+    child.on('close', () => {
+      clearTimeout(timer);
+      resolve(out.trim() || err.trim() || '(no output)');
+    });
+
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
+// One conversational turn for DIY mode. Uses --resume to keep context (and the
+// codebase warm) across turns; the persona is sent only on the first turn.
+function claudeTurn(userText) {
+  return new Promise((resolve) => {
+    const args = ['-p', '--output-format', 'json', '--allowedTools', CLAUDE_TOOLS];
+    if (sessionId) args.push('--resume', sessionId);
+    const prompt = sessionId
+      ? userText
+      : `${PERSONA}\n\nThe meeting topic is: ${MEETING_TOPIC}\n\nUser: ${userText}`;
+    let child;
+    try {
+      child = spawn('claude', args, { cwd: PROJECT_ROOT });
+    } catch (e) {
+      return resolve({ reply: `(claude unavailable: ${e.message})`, notes: latestNotes });
+    }
+    let out = '';
+    let err = '';
+    const timer = setTimeout(() => {
+      child.kill('SIGTERM');
+      resolve(splitTurn(out) || { reply: '(timed out)', notes: latestNotes });
+    }, 150000);
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (err += d));
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({ reply: `(claude unavailable: ${e.message})`, notes: latestNotes });
+    });
+    child.on('close', () => {
+      clearTimeout(timer);
+      let result = out.trim();
+      try {
+        const j = JSON.parse(out);
+        result = (j.result || '').trim();
+        if (j.session_id) sessionId = j.session_id;
+      } catch {
+        /* non-JSON output: fall back to raw text */
+      }
+      resolve(splitTurn(result) || { reply: err.trim() || '(no response)', notes: latestNotes });
+    });
+    child.stdin.write(prompt);
+    child.stdin.end();
+  });
+}
+
+// Split a turn's result into spoken reply + running notes. Updates latestNotes.
+// If the delimiter is missing, treat everything as the reply and keep prior notes.
+function splitTurn(result) {
+  if (!result) return null;
+  const i = result.indexOf(NOTES_DELIM);
+  if (i < 0) return { reply: result.trim(), notes: latestNotes };
+  const reply = result.slice(0, i).trim();
+  const notes = result.slice(i + NOTES_DELIM.length).trim();
+  if (notes) latestNotes = notes;
+  return { reply: reply || '(no response)', notes: latestNotes };
+}
+
+// --- HTTP helpers ---
+
+function sendJson(res, code, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(code, { 'Content-Type': 'application/json' });
+  res.end(body);
+}
+
+function readBody(req) {
+  return new Promise((resolve) => {
+    let data = '';
+    req.on('data', (c) => (data += c));
+    req.on('end', () => {
+      try {
+        resolve(data ? JSON.parse(data) : {});
+      } catch {
+        resolve({});
+      }
+    });
+  });
+}
+
+// --- Server ---
+
+const server = http.createServer(async (req, res) => {
+  const url = (req.url || '/').split('?')[0];
+
+  if (req.method === 'GET' && url === '/') {
+    fs.readFile(HTML_PATH, (e, buf) => {
+      if (e) {
+        res.writeHead(500);
+        res.end('meeting.html not found');
+      } else {
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(buf);
+      }
+    });
+    return;
+  }
+
+  if (req.method === 'GET' && url === '/config') {
+    return sendJson(res, 200, {
+      mode: MODE,
+      agentId: AGENT_ID,
+      voiceId: VOICE_ID,
+      topic: MEETING_TOPIC,
+      language: LANGUAGE,
+    });
+  }
+
+  if (req.method === 'GET' && url === '/signed-url') {
+    if (!API_KEY || !AGENT_ID) {
+      return sendJson(res, 200, { signedUrl: null });
+    }
+    try {
+      const r = await fetch(
+        `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${AGENT_ID}`,
+        { headers: { 'xi-api-key': API_KEY } }
+      );
+      const j = await r.json();
+      return sendJson(res, 200, { signedUrl: j.signed_url || null });
+    } catch (e) {
+      return sendJson(res, 200, { signedUrl: null, error: e.message });
+    }
+  }
+
+  if (req.method === 'POST' && url === '/tool') {
+    const { query } = await readBody(req);
+    if (!query) return sendJson(res, 400, { result: '(empty query)' });
+    const prompt =
+      `You are assisting a live spec meeting. Investigate this codebase and answer ` +
+      `concisely (max ~150 words), citing files where useful. Question: ${query}`;
+    const result = await runClaude(prompt, 120000);
+    findings.push({ query, result });
+    return sendJson(res, 200, { result });
+  }
+
+  if (req.method === 'POST' && url === '/turn') {
+    const { text } = await readBody(req);
+    if (!text) return sendJson(res, 400, { reply: '', notes: latestNotes });
+    const { reply, notes } = await claudeTurn(text);
+    return sendJson(res, 200, { reply, notes });
+  }
+
+  if (req.method === 'POST' && url === '/end') {
+    const { transcript, notesMd, notesHtml } = await readBody(req);
+    const text = (transcript || '').trim() || '(empty transcript)';
+    // Prefer the notes maintained live during the meeting; otherwise summarize the
+    // transcript in one pass (bundled mode, or if no notes were produced).
+    let notes = (notesMd || latestNotes || '').trim();
+    if (!notes) notes = await runClaude(SUMMARY_PROMPT(MEETING_TOPIC, text), 180000);
+    const { mdPath, htmlPath } = writeArtifacts({
+      projectRoot: PROJECT_ROOT,
+      meetingDir: MEETING_DIR,
+      topic: MEETING_TOPIC,
+      notesMd: notes,
+      notesHtml,
+      transcriptText: text,
+      findings,
+    });
+    sendJson(res, 200, { path: mdPath, htmlPath });
+    console.log(`\n  ✓ Meeting artifacts written:\n    ${mdPath}\n    ${htmlPath}`);
+    setTimeout(() => server.close(() => process.exit(0)), 500);
+    return;
+  }
+
+  res.writeHead(404);
+  res.end('not found');
+});
+
+server.listen(PORT, () => {
+  console.log(`\n  Catalyst meeting room: http://localhost:${PORT}`);
+  console.log(`  Topic: ${MEETING_TOPIC}  ·  Mode: ${MODE}  ·  Language: ${LANGUAGE}`);
+  if (MODE === 'diy') {
+    console.log('  DIY mode: browser speech + local claude -p (no ElevenLabs, no cost).');
+  } else {
+    if (!API_KEY) console.log('  ⚠ No elevenlabs_api_key in .catalyst/secrets.local.yaml');
+    if (!AGENT_ID) console.log('  ⚠ No voice.agent_id in project-config.yaml');
+  }
+});