codehere 0.6.1 → 0.7.0

package/dist/index.js

@@ -39,6 +39,10 @@ import { executeNarratorCommand } from './presentation/cli/commands/narrator-com
 import { executeTrustCommand } from './presentation/cli/commands/trust-command.js';
 import { executeReportCommand } from './presentation/cli/commands/report-command.js';
 import { executeScanToolCommand } from './presentation/cli/commands/scan-tool-command.js';
+import { executeVerifyCommand } from './presentation/cli/commands/verify-command.js';
+import { executeAuditCommand } from './presentation/cli/commands/audit-command.js';
+import { executeContextSourceCommand } from './presentation/cli/commands/context-source-command.js';
+import { executeThreadCommand } from './presentation/cli/commands/thread-command.js';
 import { displayError } from './presentation/cli/error-display.js';
 import { performHealthCheck, formatHealthStatus, getMetrics } from './monitoring.js';
 import { colors, createBanner, createTable, createWelcomeMessage, success, error, info, sectionHeader, formatNumber, newline, isMinimalStyle, printMinimalHeader, } from './ui.js';
@@ -58,7 +62,7 @@ import { checkTypo, looksLikeUnknownCommand } from './utils/typo-guard.js';
 const program = new Command();
 program
     .name('codehere')
-    .description('A PM for your AI coding agents. Delegate a task, watch it run, get a plain-English report with a trust score on every file.')
+    .description('A PM for your AI coding agents. Delegate a task, watch it run, and get a plain-English report with a trust score on every file it changed.')
     .version(getVersion())
     .configureHelp({ helpWidth: 80, sortSubcommands: true })
     // rc.18: many users hit `codehere --help` first and get Commander's flat
@@ -77,7 +81,7 @@ program
     // typo guard miss the unknown-command shape. See typo-guard.ts.
     .argument('[query...]', 'Optional initial task to delegate (otherwise enter interactive REPL)')
     .action(async (queryParts) => {
-    const joined = (queryParts && queryParts.length > 0) ? queryParts.join(' ') : '';
+    const joined = queryParts && queryParts.length > 0 ? queryParts.join(' ') : '';
     // One-shot delegate: `codehere "review src/auth.ts"` runs that task and exits.
     // Useful for scripting or quick one-offs without entering the REPL.
     if (joined && joined.trim()) {
@@ -118,6 +122,10 @@ program
     }
     if (!process.stdin.isTTY) {
         console.log(createWelcomeMessage());
+        // Non-interactive (piped / scripted): the REPL can't run, so leave the
+        // user with ONE clear next step instead of a dead-end welcome screen.
+        console.log(colors.dim('  Next: ') + colors.cyan('codehere start') + colors.dim('   open the dashboard'));
+        console.log(colors.dim('  New here? ') + colors.cyan('codehere setup') + colors.dim('   one-time setup\n'));
         return;
     }
     const { runInteractiveRepl } = await import('./presentation/cli/repl.js');
@@ -354,6 +362,140 @@ Examples:
         process.exit(1);
     }
 });
+// ── verify ───────────────────────────────────────────────────────────────────
+// v0.7 verifier-agent (F-03). Catches the easy lies a Final Report makes
+// against the structured artifacts recorded during the session.
+program
+    .command('verify')
+    .description("Verify a session's Final Report against the recorded reality (catches optimistic claims)")
+    .argument('[session-id]', 'Session id (or short prefix) to verify. Omit to list recent sessions.')
+    .option('--json', 'Output machine-readable JSON instead of formatted findings')
+    .addHelpText('after', `
+Examples:
+  $ codehere verify                     # list recent sessions to pick from
+  $ codehere verify a1b2c3d4            # verify by short id prefix
+  $ codehere verify a1b2c3d4 --json     # machine-readable verdict for CI
+
+Exit codes:
+  0 = verified, partial (warnings only), or no Final Report to verify
+  1 = broken (a claim contradicts recorded reality)
+  2 = session not found
+  `)
+    .action(async (sessionId, options) => {
+    try {
+        // Per codex Round 2: set exitCode instead of calling process.exit so a
+        // piped --json consumer sees the full payload before Node tears down.
+        // The picker mode can write ~15 sessions worth of JSON · enough to
+        // exceed pipe buffer + race the process exit. exitCode preserves the
+        // intent (CI uses the exit code) without forcing an immediate teardown.
+        process.exitCode = await executeVerifyCommand(sessionId, { json: options.json });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
+// ── audit ────────────────────────────────────────────────────────────────────
+// F-05 of the demo v12 backlog · expose the hash-chain verifier as a CLI.
+program
+    .command('audit')
+    .description('Inspect the hash-chained audit log · verify the chain or show one entry')
+    .argument('[subcommand]', 'verify | show', 'verify')
+    .argument('[arg]', 'For `show`: the sequence number to print.')
+    .option('--json', 'Output machine-readable JSON instead of formatted text')
+    .addHelpText('after', `
+Examples:
+  $ codehere audit                  # equivalent to: codehere audit verify
+  $ codehere audit verify           # walk the chain, report intact/tampered
+  $ codehere audit verify --json    # machine-readable verdict for CI
+  $ codehere audit show 42          # print entry with seq=42
+  $ codehere audit show 42 --json
+
+Exit codes:
+  0 = chain intact OR entry found
+  1 = chain BROKEN (one or more break points detected)
+  2 = invalid input / no entry found
+  `)
+    .action((sub, arg, options) => {
+    try {
+        process.exitCode = executeAuditCommand(sub, arg, { json: options.json });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
+// ── context-source ───────────────────────────────────────────────────────────
+// v0.8 S2.5 · OAuth click-to-connect for Linear, Figma, etc.
+program
+    .command('context-source')
+    .alias('cs')
+    .description('Manage context sources (Linear, Figma) · connect via OAuth, list status, disconnect')
+    .argument('[subcommand]', 'list | connect | disconnect', 'list')
+    .argument('[provider]', 'For connect/disconnect: linear | figma | ...')
+    .option('--json', 'Machine-readable output')
+    .option('--no-open', 'For connect: skip auto-opening the browser (just print the URL)')
+    .addHelpText('after', `
+Examples:
+  $ codehere context-source                    # equivalent to: list
+  $ codehere context-source list
+  $ codehere context-source connect linear
+  $ codehere context-source connect figma --no-open
+  $ codehere context-source disconnect linear
+
+  Tokens persist at ~/.codehere/context-sources.json (0600 mode).
+  Requires the daemon running: codehere start
+  Provider client IDs come from env: CODEHERE_LINEAR_CLIENT_ID, CODEHERE_FIGMA_CLIENT_ID
+  `)
+    .action(async (sub, provider, options) => {
+    try {
+        process.exitCode = await executeContextSourceCommand(sub, provider, {
+            json: options.json,
+            open: options.open,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
+// ── thread ───────────────────────────────────────────────────────────────────
+// v0.8 S4 · signed-payload "GitHub for agent sessions" · share/import threads
+program
+    .command('thread')
+    .description('Share or import a session · Ed25519-signed bundle · local-first')
+    .argument('<subcommand>', 'export | import | keys | trust | untrust')
+    .argument('[arg]', 'For export: session-id · For import/trust/untrust: file path or pubkey')
+    .argument('[label]', 'For trust: an optional human label for the key')
+    .option('--out <file>', 'For export: write the signed bundle to a file (default: stdout)')
+    .option('--trust', 'For import: trust the signer key automatically if unknown')
+    .option('--json', 'Machine-readable output')
+    .addHelpText('after', `
+Examples:
+  $ codehere thread export a1b2c3d4 --out demo-thread.json
+  $ codehere thread import ./shared.json --trust
+  $ codehere thread keys
+  $ codehere thread trust <pubkey-base64> "Daniel"
+  $ codehere thread untrust <pubkey-base64>
+
+  Bundles include: spawned · steps · artifacts · finalReport · signature.
+  No source code · only the synthesized record.
+  Recipient must trust the signer key (or pass --trust) before replay.
+  `)
+    .action((sub, arg, label, options) => {
+    try {
+        process.exitCode = executeThreadCommand(sub, arg, label, {
+            out: options.out,
+            trust: options.trust,
+            label,
+            json: options.json,
+        });
+    }
+    catch (err) {
+        console.error(error('Error:'), err instanceof Error ? err.message : String(err));
+        process.exitCode = 1;
+    }
+});
 // ── hook ─────────────────────────────────────────────────────────────────────
 program
     .command('hook')
@@ -581,13 +723,17 @@ program
                 const { SessionManager } = require('./infrastructure/orchestration/session-manager.js');
                 SessionManager.getInstance().shutdown();
             }
-            catch { /* graceful degradation — daemon may not have started fully */ }
+            catch {
+                /* graceful degradation — daemon may not have started fully */
+            }
             if (cloud) {
                 try {
                     const { stopCloudSync } = require('./infrastructure/protocols/cloud-sync.js');
                     stopCloudSync();
                 }
-                catch { /* cloud sync may not be loaded */ }
+                catch {
+                    /* cloud sync may not be loaded */
+                }
             }
             server.close();
         };
@@ -634,10 +780,18 @@ program
 // ── task (spawn an agent session via CLI) ────────────────────────────────────
 program
     .command('task <prompt...>')
-    .description('Assign a task — spawns the default agent under codehere. Requires `codehere start` running.')
+    .description('Assign a task — spawns an agent under codehere. Requires `codehere start` running.')
     .option('-p, --port <number>', 'Daemon port', '3773')
     .option('--host <host>', 'Daemon host', '127.0.0.1')
-    .option('--watch', 'Stream events to the terminal (default: just returns the session id)')
+    .option('--agent <id>', 'Which agent to run (claude-code, codex, aider, gemini, opencode). Default: auto.')
+    .option('--watch', 'Watch it work and print the report when it finishes')
+    .addHelpText('after', `
+Examples:
+  $ codehere task "fix the totalValue bug in inventory.js"          # assign, get a session id
+  $ codehere task "add a health check route" --watch               # watch it work + see the report
+  $ codehere task "summarize recent changes" --agent codex --watch # pick the agent
+
+Needs a running daemon: start one with \`codehere start\` (or \`codehere serve\`).`)
     .action(async (promptParts, options) => {
     const prompt = promptParts.join(' ').trim();
     if (!prompt) {
@@ -648,8 +802,9 @@ program
     const host = options?.host ?? '127.0.0.1';
     const base = `http://${host}:${port}`;
     const http = await import('http');
+    const { waitForDeliverable, formatDeliverable } = await import('./presentation/cli/task-deliverable.js');
     const spawnResult = await new Promise((resolve) => {
-        const body = JSON.stringify({ prompt });
+        const body = JSON.stringify({ prompt, ...(options?.agent ? { agent: options.agent } : {}) });
         const r = http.request(`${base}/api/task`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
@@ -672,16 +827,26 @@ program
         r.end();
     });
     if (!spawnResult || !spawnResult.sessionId) {
-        console.error(error(`Could not reach daemon at ${base}. Start it with: codehere start`));
+        if (spawnResult?.error)
+            console.error(error(spawnResult.error));
+        else
+            console.error(error(`Could not reach the daemon at ${base}. Start it with: codehere start`));
         process.exit(1);
     }
-    console.log(success(`Task assigned · session ${spawnResult.sessionId}`));
-    console.log(colors.dim(`  Watch: ${base}/  ·  Kill: codehere kill ${spawnResult.sessionId}`));
-    if (!options?.watch)
+    const sid = spawnResult.sessionId;
+    console.log(success(`Task assigned · session ${sid.slice(0, 8)}`));
+    if (!options?.watch) {
+        console.log(colors.dim(`  Watch in the browser: ${base}/`));
+        console.log(colors.dim(`  Or in the terminal:   codehere task "${prompt}" --watch`));
+        console.log(colors.dim(`  Stop it:              codehere kill ${sid.slice(0, 8)}`));
         return;
-    const streamUrl = `${base}/api/task/${spawnResult.sessionId}/events`;
+    }
+    // --watch · render the agent's actual steps as they complete, then print
+    // the deliverable (report + files + trust + verifier) when it's done.
+    console.log(colors.dim(`  Watching… (Ctrl-C to stop watching; the agent keeps running)`));
+    const printed = new Set();
     await new Promise((resolve) => {
-        const r = http.get(streamUrl, (res) => {
+        const r = http.get(`${base}/api/task/${sid}/events`, (res) => {
             let buf = '';
             res.on('data', (c) => {
                 buf += c.toString();
@@ -691,20 +856,37 @@ program
                     buf = buf.slice(i + 2);
                     if (!frame.startsWith('data:'))
                         continue;
-                    const payload = frame.slice(5).trim();
                     try {
-                        const event = JSON.parse(payload);
+                        const event = JSON.parse(frame.slice(5).trim());
                         const type = String(event.type || 'message');
-                        if (type === 'exit') {
-                            console.log(colors.dim(`  [exit] ${String(event.data?.status ?? '?')}`));
+                        if (type === 'codehere:steps') {
+                            const steps = (event.data?.steps ?? []);
+                            for (const s of steps) {
+                                if (s.state !== 'done' && s.state !== 'failed')
+                                    continue;
+                                if (printed.has(s.label))
+                                    continue; // one line per step, on first settle
+                                printed.add(s.label);
+                                const mark = s.state === 'failed' ? colors.error('✗') : colors.success('✓');
+                                const text = s.kind === 'say' ? colors.dim(s.label) : s.label;
+                                console.log(`  ${mark} ${text}`);
+                            }
+                        }
+                        else if (type === 'codehere:error') {
+                            const d = event.data;
+                            if (d?.message)
+                                console.log(`  ${colors.error('!')} ${d.message}`);
+                            if (d?.recovery)
+                                console.log(colors.dim(`    ${d.recovery}`));
+                        }
+                        else if (type === 'exit') {
                             res.destroy();
                             resolve();
                             return;
                         }
-                        console.log(colors.dim(`  [${type}]`));
                     }
                     catch {
-                        /* skip */
+                        /* skip malformed frame */
                     }
                 }
             });
@@ -712,6 +894,23 @@ program
         });
         r.on('error', () => resolve());
     });
+    // The Final Report is generated after exit — poll for it, then print.
+    // Real agents take ~30-60s to write it, so tell the user we're waiting.
+    process.stdout.write(colors.dim('  Writing the report…'));
+    const result = await waitForDeliverable(base, sid);
+    process.stdout.write('\r' + ' '.repeat(24) + '\r'); // clear the waiting line
+    if (result && (result.finalReport || result.failedReport || result.status !== 'completed')) {
+        console.log(formatDeliverable(result));
+    }
+    else if (result) {
+        // Completed, but the report is still generating past our wait window.
+        console.log(formatDeliverable(result));
+        console.log(colors.dim('  (the written report is still being generated — run the command below in a moment)'));
+    }
+    else {
+        console.log(colors.dim('\n  Task finished, but the report could not be fetched from the daemon.'));
+    }
+    console.log(colors.dim(`Next: codehere verify ${sid.slice(0, 8)}   (see this report + the fact-check anytime)`));
 });
 // ── kill (stop a running task) ───────────────────────────────────────────────
 program

package/dist/infrastructure/completion/bash-completion.js

@@ -13,9 +13,9 @@ _complete_codehere() {
   opts="ask plan orchestrate fix suggest run review status help version"
 
   if [[ \${cur} == -* ]]; then
-    COMPREPLY=(\$(compgen -W "--help --version" -- \${cur}))
+    COMPREPLY=($(compgen -W "--help --version" -- \${cur}))
   else
-    COMPREPLY=(\$(compgen -W "\${opts}" -- \${cur}))
+    COMPREPLY=($(compgen -W "\${opts}" -- \${cur}))
   fi
 }
 

package/dist/infrastructure/config/config-manager.js

@@ -103,7 +103,7 @@ export class ConfigManager {
             writeFileSync(this.configPath, JSON.stringify(this.config, null, 2), 'utf-8');
         }
         catch (error) {
-            throw new Error(`Failed to save config to ${this.configPath}: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Failed to save config to ${this.configPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
     }
     /**

package/dist/infrastructure/context/adapters/drawio-source.js

@@ -0,0 +1,157 @@
+/**
+ * draw.io context-source adapter (v0.8 S5 · third reference adapter).
+ *
+ * URL shapes accepted (we route both via the same scheme to keep the
+ * agent prompt forgiving):
+ *   - `drawio://<gist-or-raw-url-base64>`   · base64url-encoded source URL
+ *   - `drawio://gh/<owner>/<repo>/<path>`   · raw GitHub-hosted .drawio XML
+ *   - `drawio://url/<urlencoded-https-url>` · arbitrary HTTPS-hosted .drawio
+ *
+ * No OAuth · draw.io is a client-side editor, the file itself is the
+ * payload. We fetch the raw XML, summarize node + edge counts, and emit
+ * the first ~3KB of the XML so the agent can read structure without us
+ * doing graphviz-style parsing here. Bigger diagrams get a `...truncated`
+ * suffix; agents can ask the human for a screenshot if they need pixels.
+ *
+ * Local-first: no codehere endpoint is contacted. Network call goes
+ * directly to GitHub-raw / the supplied HTTPS host. Audit chain records
+ * fetch + byte count, never content.
+ */
+import { ContextSourceError, estimateTokens, } from '../context-source.js';
+const MAX_XML_CHARS = 3000;
+const MAX_RESPONSE_BYTES = 1_500_000; // 1.5MB · refuse anything bigger to protect prompt budget
+/** Turn the codehere drawio:// URL into a concrete HTTPS fetch target. */
+function resolveTarget(url) {
+    const raw = url.toString();
+    const after = raw.slice('drawio://'.length).replace(/^\/+/, '');
+    if (!after) {
+        throw new ContextSourceError('drawio', 'invalid_url', 'drawio URL missing path');
+    }
+    // gh/<owner>/<repo>/<path...>
+    if (after.startsWith('gh/')) {
+        const parts = after.slice('gh/'.length).split('/');
+        if (parts.length < 3) {
+            throw new ContextSourceError('drawio', 'invalid_url', 'gh/ path needs <owner>/<repo>/<path>');
+        }
+        const [owner, repo, ...rest] = parts;
+        const path = rest.join('/');
+        if (!/^[A-Za-z0-9._-]+$/.test(owner) || !/^[A-Za-z0-9._-]+$/.test(repo)) {
+            throw new ContextSourceError('drawio', 'invalid_url', 'gh/ owner/repo must be alphanumeric');
+        }
+        return {
+            fetchUrl: `https://raw.githubusercontent.com/${owner}/${repo}/HEAD/${path}`,
+            label: `github.com/${owner}/${repo}/${path}`,
+        };
+    }
+    // url/<urlencoded-https-url>
+    if (after.startsWith('url/')) {
+        const encoded = after.slice('url/'.length);
+        const decoded = safeDecode(encoded);
+        if (!/^https:\/\//.test(decoded)) {
+            throw new ContextSourceError('drawio', 'invalid_url', 'url/ target must be https://');
+        }
+        return { fetchUrl: decoded, label: decoded };
+    }
+    // base64url-encoded full URL
+    const decoded = safeBase64UrlDecode(after);
+    if (decoded && /^https:\/\//.test(decoded)) {
+        return { fetchUrl: decoded, label: decoded };
+    }
+    throw new ContextSourceError('drawio', 'invalid_url', 'use drawio://gh/<owner>/<repo>/<path> · drawio://url/<urlencoded-https> · or drawio://<base64url-https>');
+}
+function safeDecode(s) {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return '';
+    }
+}
+function safeBase64UrlDecode(s) {
+    try {
+        const pad = '='.repeat((4 - (s.length % 4)) % 4);
+        return Buffer.from(s.replace(/-/g, '+').replace(/_/g, '/') + pad, 'base64').toString('utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+export const drawioSource = {
+    id: 'drawio',
+    label: 'draw.io',
+    scheme: 'drawio',
+    description: 'Fetch a draw.io / diagrams.net diagram XML (architecture, flowchart, etc.)',
+    isConfigured() {
+        // Public-by-URL · no auth needed. Always available.
+        return true;
+    },
+    async fetch(url, ctx) {
+        const target = resolveTarget(url);
+        const res = await ctx.httpGet(target.fetchUrl, { 'User-Agent': 'codehere/0.8' });
+        if (res.status === 404) {
+            throw new ContextSourceError('drawio', 'not_found', `diagram not found at ${target.label}`);
+        }
+        if (res.status === 429) {
+            throw new ContextSourceError('drawio', 'rate_limit', `host returned 429 for ${target.label}`);
+        }
+        if (res.status !== 200) {
+            throw new ContextSourceError('drawio', 'network', `host returned ${res.status} for ${target.label}: ${res.body.slice(0, 200)}`);
+        }
+        if (res.body.length > MAX_RESPONSE_BYTES) {
+            throw new ContextSourceError('drawio', 'parse', `diagram too big (${res.body.length} bytes · limit ${MAX_RESPONSE_BYTES})`);
+        }
+        if (!looksLikeDrawio(res.body)) {
+            throw new ContextSourceError('drawio', 'parse', 'response does not look like a draw.io XML or SVG file');
+        }
+        const stats = quickStats(res.body);
+        const text = renderDiagramAsPlainText(target, res.body, stats);
+        return {
+            url: url.toString(),
+            source: 'drawio',
+            fetchedAt: new Date(ctx.now ? ctx.now() : Date.now()).toISOString(),
+            text,
+            estimatedTokens: estimateTokens(text),
+            metadata: {
+                label: target.label,
+                bytes: res.body.length,
+                cellCount: stats.cellCount,
+                edgeCount: stats.edgeCount,
+                pageCount: stats.pageCount,
+            },
+        };
+    },
+};
+/** Does this payload look like a draw.io diagram (XML) or SVG export?
+ *  Accept any prolog (whitespace, BOM, `<?xml ...?>`) before the first
+ *  meaningful tag · `<mxfile`, `<mxGraphModel`, or `<svg`. */
+function looksLikeDrawio(body) {
+    const trimmed = body.replace(/^\uFEFF/, '').trimStart();
+    const stripped = trimmed.startsWith('<?') ? trimmed.slice(trimmed.indexOf('?>') + 2).trimStart() : trimmed;
+    return /^<(mxfile|mxGraphModel|svg)\b/i.test(stripped);
+}
+/** Cheap regex stats · we don't ship a real XML parser. */
+function quickStats(xml) {
+    const cellMatches = xml.match(/<mxCell\b/g);
+    const edgeMatches = xml.match(/<mxCell\b[^>]*\bedge="1"/g);
+    const pageMatches = xml.match(/<diagram\b/g);
+    return {
+        cellCount: cellMatches ? cellMatches.length : 0,
+        edgeCount: edgeMatches ? edgeMatches.length : 0,
+        pageCount: pageMatches ? pageMatches.length : 1,
+    };
+}
+function renderDiagramAsPlainText(target, xml, stats) {
+    const lines = [];
+    lines.push(`draw.io diagram · ${target.label}`);
+    lines.push('');
+    lines.push(`structure: ${stats.cellCount} cells · ${stats.edgeCount} edges · ${stats.pageCount} page${stats.pageCount === 1 ? '' : 's'}`);
+    lines.push(`bytes: ${xml.length}`);
+    lines.push('');
+    lines.push('--- raw xml (truncated) ---');
+    lines.push(xml.slice(0, MAX_XML_CHARS));
+    if (xml.length > MAX_XML_CHARS) {
+        lines.push(`...[truncated · diagram is ${xml.length} chars · ask the human for a screenshot if structure isn't clear]`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=drawio-source.js.map