codehere 0.3.0-rc.9 → 0.3.2

package/README.md

@@ -4,55 +4,63 @@
 
 [![npm](https://img.shields.io/npm/v/codehere)](https://www.npmjs.com/package/codehere)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](../LICENSE)
-[![Tests](https://img.shields.io/badge/tests-216%2F216-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-362%2F362-brightgreen)]()
 [![Vulnerabilities](https://img.shields.io/badge/vulnerabilities-0-brightgreen)]()
 
-codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, or OpenCode), wraps every action in the safety hook, audits everything, and hands you a plain-English report with a **trust score on every file changed**.
+codehere is **a PM for your AI coding agents.** Delegate a task. codehere picks the right specialist (Claude Code, Codex, Aider, or OpenCode), spawns it, streams its work back to you, and hands you a plain-English Final Report with a **trust score on every file changed**. Today, Claude Code gets full pre-execution safety-hook enforcement on every tool call; other adapters are session-traced and reported, with per-tool hook parity planned for v0.4.
 
-One manager, many specialists, everything traceable.
+One manager, many specialists, every action recorded.
 
-## Install
+---
 
-```bash
-npm install -g codehere
-```
+## Recipe — setup to first audit in 30 minutes
 
-Requires Node.js 20+. Open-source MIT.
+> One folder convention, one prompt formula, four ready-to-use prompts.
+> Full version: **[docs/RECIPE.md](../docs/RECIPE.md)**.
 
-## Quick start
+### Setup (once)
 
-### Delegate a task to an AI agent
+| | | |
+|---|---|---|
+| 1 | **Install** | `npm install -g codehere` (Node 20+) |
+| 2 | **Detect environment** | `codehere setup` — checks API key, finds your repo |
+| 3 | **Install the safety hook** | `codehere hook install` — every Claude Code tool call now audited |
+| 4 | **Install at least one specialist** | Claude Code: `npm i -g @anthropic-ai/claude-code` (Codex / Aider / OpenCode also supported) |
+| 5 | **Scaffold this repo** | `cd /your/repo && codehere init` — creates `.codehere/CONTEXT.md`, `HANDOVER.md`, `PROMPTS.md` |
+| 6 | **Fill in CONTEXT.md** | 5 minutes. The agent will follow what's written there. |
 
-Make sure at least one of the four supported agents is installed:
+You're done. `codehere start` opens the web UI at `:3773`; you delegate from there.
 
-| Agent | Install |
-|---|---|
-| Claude Code | `npm install -g @anthropic-ai/claude-code` |
-| Codex CLI | `npm install -g @openai/codex` |
-| Aider | `brew install aider` |
-| OpenCode | `curl -fsSL https://opencode.ai/install \| bash` |
+### The prompt formula
 
-Then:
-
-```bash
-codehere start          # opens http://127.0.0.1:3773 in your browser
 ```
+Context  +  End State  +  Constraints
+```
+
+- **Context** — *"Read .codehere/CONTEXT.md"* + any specific files
+- **End State** — the user-visible change, the test that passes, the file that exists
+- **Constraints** — files not to touch, dependencies not to add, patterns not to use
+
+### Folder convention (what `codehere init` writes)
+
+| File | Purpose | Committed? |
+|---|---|---|
+| `.codehere/CONTEXT.md` | What this repo is. Conventions. Style. Constraints. | yes |
+| `.codehere/HANDOVER.md` | Cross-session continuity (until F3 memory ships in v0.5). | **no** |
+| `.codehere/PROMPTS.md` | Your library of recurring task prompts. | yes |
 
-You'll see:
+---
 
-- **Today's activity** · "47 AI actions · 3 blocked · avg trust 91 · 4 agents"
-- **A task intake** with three starter prompts you can click
-- **A cwd field** pre-filled with where you ran `codehere start`
-- **An agent dropdown** showing which of the four are installed (and a one-click Install button for the others)
+## What you see when you delegate a task
 
-Pick an agent, type a task, hit **Assign**. codehere:
+`codehere start` opens `http://127.0.0.1:3773`. Pick an agent, type a task, hit **Assign**. codehere:
 
 1. Spawns the agent with the right headless flags
 2. Streams the steps back as readable progress · *"Read src/auth.ts · Edit src/auth.ts · Run npm test"*
-3. Runs every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live
+3. For Claude Code tasks: routes every tool call through the codehere safety hook — you see *"🛡 5 safe · 0 blocked"* grow live. For Codex / Aider / OpenCode tasks: emits the agent's native event stream (no per-tool blocking yet)
 4. On completion, hands you a **Final report**: files changed with `+/-` lines, trust score per file, test pass/fail, token usage
 
-Everything is logged to `~/.codehere/audit/`. One feed, every agent, every action.
+Claude Code tool calls are logged to `~/.codehere/audit/hook-events.jsonl`; spawned-task lifecycle (any adapter) is logged to `~/.codehere/sessions.jsonl`. Open-source MIT. Node 20+.
 
 ### Just the safety hook (no agents required)
 
@@ -65,7 +73,7 @@ codehere report         # generates a shareable markdown audit report
 codehere status         # quick dashboard · sessions, blocks, trust trends
 ```
 
-The hook intercepts every `Bash`, `Edit`, `Write`, `MultiEdit`, and `NotebookEdit` call from any Claude Code session running on your machine, runs it through the trust-scorer pattern bank in under 5 ms, blocks anything matching the destructive / credential / injection patterns, and appends every decision to a tamper-evident JSONL audit log.
+The hook intercepts every `Bash`, `Edit`, `Write`, `MultiEdit`, and `NotebookEdit` call from any Claude Code session running on your machine, runs it through the trust-scorer pattern bank in under 5 ms, blocks anything matching the destructive / credential / injection patterns, and appends every decision to an append-only JSONL audit log at `~/.codehere/audit/`. (Hook coverage today is Claude Code-only — Codex / Aider / OpenCode adapters spawn through their native CLIs and emit to `~/.codehere/sessions.jsonl`; full hook parity across all adapters is v0.4 work.)
 
 ## Commands
 
@@ -90,14 +98,14 @@ codehere scan-tool          · internal · used by the hook system, not by users
 
 ## What it catches
 
-The trust scorer + safety hook detect 60+ patterns across:
+The trust scorer + safety hook detect ~36 patterns across:
 
-- SQL injection · XSS · command injection · path traversal · SSRF
-- Hardcoded secrets · weak crypto · JWT bypass · open redirects
+- SQL injection · XSS · command injection · path traversal
+- Hardcoded secrets · API keys · weak crypto · JWT bypass
 - Eval injection · prompt injection · credential theft
-- Destructive operations · supply-chain patterns
+- Destructive shell operations · supply-chain patterns
 
-Every blocked call is logged with the reason; every allowed call is logged with the trust score.
+Every blocked call is logged with the reason; every allowed call is logged with the trust score. Pattern bank lives in `agent/src/infrastructure/security/trust-scorer.ts`.
 
 ## MCP server
 

package/dist/domain/services/codebase-detector.js

@@ -9,7 +9,7 @@ import { join, dirname, resolve } from 'path';
  */
 export function findCodebaseRoot(startPath = process.cwd()) {
     const resolvedStart = resolve(startPath);
-    let currentDir = resolvedStart;
+    const currentDir = resolvedStart;
     // Try to find git root first
     const gitRoot = findGitRoot(currentDir);
     if (gitRoot) {

package/dist/index.js

@@ -15,6 +15,7 @@ import { config } from 'dotenv';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { executeSetupCommand } from './presentation/cli/commands/setup-command.js';
+import { executeInitCommand } from './presentation/cli/commands/init-command.js';
 import { executeConfigCommand } from './presentation/cli/commands/config-command.js';
 import { executeHelpCommand } from './presentation/cli/commands/help-command.js';
 import { executeStatusCommand } from './presentation/cli/commands/status-command.js';
@@ -37,12 +38,19 @@ catch {
 }
 config();
 import { getVersion } from './utils/version.js';
+import { checkTypo } 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.')
     .version(getVersion())
-    .configureHelp({ helpWidth: 80, sortSubcommands: true });
+    .configureHelp({ helpWidth: 80, sortSubcommands: true })
+    // rc.18: many users hit `codehere --help` first and get Commander's flat
+    // list. The grouped `codehere help` is more useful for discovery. Surface
+    // it inline so muscle-memory `--help` users find the better page.
+    // (Pin: no raw ANSI in --help output — existing commands.test.ts asserts
+    // this, see test/cli/commands.test.ts "no raw ANSI escape codes in --help".)
+    .addHelpText('after', '\nTip: `codehere help` shows commands grouped by use case (Delegate · Safety & Trust · Configuration).');
 // Default action · show welcome, then drop into the interactive REPL on TTY.
 // codehere offers TWO surfaces, both first-class: the CLI REPL (here) and the
 // web UI (`codehere start`). Users pick whichever fits their workflow.
@@ -52,8 +60,23 @@ program
     // 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 (query && query.trim()) {
+        const trimmed = query.trim();
+        // Typo guard — see src/utils/typo-guard.ts for heuristics.
+        // Returns suggestions when input looks like a typo; null falls through.
+        const known = program.commands.map((c) => c.name());
+        const suggestions = checkTypo(trimmed, known);
+        if (suggestions) {
+            console.error(`codehere: unknown command '${trimmed}'.`);
+            console.error('');
+            console.error('  Did you mean:');
+            for (const s of suggestions)
+                console.error(`    codehere ${s}`);
+            console.error('');
+            console.error(`  If you meant to ask a question, quote it: codehere "${trimmed}"`);
+            process.exit(1);
+        }
         const { runOneShot } = await import('./presentation/cli/repl.js');
-        await runOneShot(query.trim());
+        await runOneShot(trimmed);
         return;
     }
     if (!process.stdin.isTTY) {
@@ -71,6 +94,15 @@ program
     .action(async (options) => {
     await executeSetupCommand(options.force || false);
 });
+// ── init ─────────────────────────────────────────────────────────────────────
+program
+    .command('init')
+    .description('Scaffold .codehere/ in this repo · CONTEXT, HANDOVER, PROMPTS')
+    .option('-f, --force', 'Overwrite existing files in .codehere/')
+    .option('--no-gitignore', 'Skip updating .gitignore')
+    .action((options) => {
+    executeInitCommand({ force: options.force, noGitignore: !options.gitignore });
+});
 // ── config ───────────────────────────────────────────────────────────────────
 program
     .command('config')
@@ -103,8 +135,23 @@ program
     .command('health')
     .description('Check system health and metrics')
     .option('-m, --metrics', 'Show detailed metrics')
+    .option('--json', 'Machine-readable JSON (for monitoring/CI)')
     .action((options) => {
     const health = performHealthCheck();
+    if (options.json) {
+        // Machine-readable: status + checks (+ metrics when --metrics).
+        // Stdout is the contract — never mix with the human banner.
+        // Use process.exitCode (not process.exit) so a piped consumer sees the
+        // full JSON before the process tears down (rc.16: Codex flagged the old
+        // process.exit call as a truncation hazard under stdout redirection).
+        const payload = { status: health.status, checks: health.checks };
+        if (options.metrics)
+            payload.metrics = getMetrics();
+        console.log(JSON.stringify(payload, null, 2));
+        if (health.status === 'unhealthy')
+            process.exitCode = 1;
+        return;
+    }
     if (isMinimalStyle()) {
         printMinimalHeader('health', '');
     }
@@ -202,9 +249,9 @@ program
     .command('report')
     .description('Generate a shareable security audit report — narrative, not just a score')
     .argument('[target]', 'File or directory to audit (default: current directory)')
-    .option('--out <file>', 'Write report to a specific file (default: codehere-audit.md)')
-    .option('--stdout', 'Print the report to stdout instead of writing a file')
-    .option('--json', 'Output machine-readable JSON instead of markdown')
+    .option('--out <file>', 'Write report to a specific file (default: codehere-audit.md for markdown)')
+    .option('--stdout', 'Print the report to stdout (already the default for --json)')
+    .option('--json', 'Output machine-readable JSON to stdout (pipe to jq, etc.)')
     .option('--simple', 'Plain English output — no jargon, for non-technical stakeholders')
     .addHelpText('after', `
 Examples:

package/dist/infrastructure/hooks/session-analyzer.js

@@ -76,17 +76,26 @@ export function detectAmplificationAlerts(sessions) {
             continue;
         let message = '';
         const risk = session.amplificationRisk;
-        if (session.blockedCalls > 0 && session.totalCalls > 20) {
-            message = `${session.totalCalls} tool calls with ${session.blockedCalls} blocked — possible injection in multi-agent chain`;
+        // rc.17 framing: don't accuse "injection" by default — that wording scares
+        // users on perfectly normal long attended sessions. Reserve the strong
+        // language for cases where the *blocked-call ratio* is high (real signal
+        // of prompts trying things they shouldn't), not just call volume.
+        // UX_OBSERVATIONS.md P1.
+        const blockRatio = session.totalCalls > 0 ? session.blockedCalls / session.totalCalls : 0;
+        if (session.blockedCalls > 0 && session.totalCalls > 20 && blockRatio > 0.05) {
+            message = `${session.totalCalls} tool calls, ${session.blockedCalls} blocked (${(blockRatio * 100).toFixed(0)}%) — high block ratio, review for injection`;
+        }
+        else if (session.blockedCalls > 0 && session.totalCalls > 20) {
+            message = `${session.totalCalls} tool calls, ${session.blockedCalls} blocked — long session, review if unattended`;
         }
         else if (session.totalCalls > 50) {
-            message = `${session.totalCalls} tool calls in one session — check for amplification`;
+            message = `${session.totalCalls} tool calls in one session — high density, review if unattended`;
         }
         else if ((session.toolMix['Bash'] ?? 0) > 10) {
-            message = `${session.toolMix['Bash']} Bash calls in one session — elevated risk`;
+            message = `${session.toolMix['Bash']} Bash calls in one session — elevated tool-mix`;
         }
         else {
-            message = `${session.totalCalls} calls, ${session.blockedCalls} blocked — worth reviewing`;
+            message = `${session.totalCalls} calls, ${session.blockedCalls} blocked — worth a glance`;
         }
         alerts.push({
             sessionId: session.sessionId,

package/dist/infrastructure/orchestration/conductor-adapter.js

@@ -91,7 +91,12 @@ function tokenize(prompt) {
     //   "add tests"  "add-tests"  "add_tests"  "add/tests"  "add:tests"  "add.tests"
     // Note: must NOT collapse the leading/trailing spaces — they're load-bearing
     // for the boundary check below (`.includes(' ' + t + ' ')`).
-    const normalized = ' ' + prompt.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim() + ' ';
+    const normalized = ' ' +
+        prompt
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, ' ')
+            .trim() +
+        ' ';
     return { tokens, normalized };
 }
 /**
@@ -240,7 +245,6 @@ function spawnConductor(prompt, options, lookup) {
             },
         };
         buffer.push(errEvent);
-        queueMicrotask(() => emitter.emit('event', errEvent));
         return synthesizeSession({ sessionId, startedAt, prompt, statusValue, emitter, buffer });
     }
     // Emit the routing-decision event FIRST so the audit log records WHY this
@@ -255,8 +259,11 @@ function spawnConductor(prompt, options, lookup) {
             promptExcerpt: prompt.slice(0, 200),
         },
     };
+    // Buffer replay on subscribe() handles delivery to the first subscriber. Do
+    // NOT also queueMicrotask(emit) — the microtask fires AFTER subscribe attaches
+    // its handler, so the handler would receive routingEvent twice (rc.13 bug:
+    // duplicate "routing → ..." line in the REPL).
     buffer.push(routingEvent);
-    queueMicrotask(() => emitter.emit('event', routingEvent));
     // Find the chosen specialist adapter and spawn against it.
     const specialist = lookup().find((a) => a.id === decision.agentId);
     if (!specialist) {
@@ -269,7 +276,6 @@ function spawnConductor(prompt, options, lookup) {
             data: { message: `Conductor picked '${decision.agentId}' but no adapter with that ID is registered.` },
         };
         buffer.push(errEvent);
-        queueMicrotask(() => emitter.emit('event', errEvent));
         return synthesizeSession({ sessionId, startedAt, prompt, statusValue, emitter, buffer });
     }
     // Spawn the specialist session and proxy every event through.
@@ -284,7 +290,12 @@ function spawnConductor(prompt, options, lookup) {
             stepsSnapshot = specialistSession.steps;
         if (specialistSession.artifacts)
             artifactsSnapshot = specialistSession.artifacts;
-        if (evt.type === 'codehere:complete' || evt.type === 'codehere:error') {
+        // Specialist adapters terminate with an 'exit' event — never emit
+        // 'codehere:complete' / 'codehere:error'. Without mirroring on 'exit',
+        // session.status stayed 'running' forever and the REPL printed
+        // "✗ └─ running" (rc.13 bug). Also keep the legacy types for safety in
+        // case a future adapter emits them.
+        if (evt.type === 'exit' || evt.type === 'codehere:complete' || evt.type === 'codehere:error') {
             statusValue = specialistSession.status;
         }
     });

package/dist/infrastructure/orchestration/generic-cli-adapter.js

@@ -478,7 +478,6 @@ export function compileSafePattern(source, fallback, agentId) {
     // Layer 1 · static shape check — this is the only fully reliable defense.
     const danger = detectRedosShape(source);
     if (danger) {
-        // eslint-disable-next-line no-console
         console.warn(`[codehere] Regex for "${agentId}" rejected (${danger}) — using fallback`);
         return fallback;
     }
@@ -487,7 +486,6 @@ export function compileSafePattern(source, fallback, agentId) {
         candidate = new RegExp(source);
     }
     catch {
-        // eslint-disable-next-line no-console
         console.warn(`[codehere] Invalid regex in agents.yaml for "${agentId}" — using fallback`);
         return fallback;
     }
@@ -496,7 +494,6 @@ export function compileSafePattern(source, fallback, agentId) {
         const start = Date.now();
         candidate.test('a'.repeat(1000));
         if (Date.now() - start > 100) {
-            // eslint-disable-next-line no-console
             console.warn(`[codehere] Regex for "${agentId}" too slow (likely ReDoS) — using fallback`);
             return fallback;
         }

package/dist/infrastructure/protocols/mcp-server-impl.js

@@ -20,7 +20,8 @@
  */
 import http from 'http';
 import { readFileSync, existsSync, statSync, watchFile, unwatchFile } from 'fs';
-import { join, relative } from 'path';
+import { join, relative, dirname } from 'path';
+import { fileURLToPath } from 'url';
 import { collectFilesForMCP, scoreFileForMCP } from './mcp-helpers.js';
 import { scanPayload, calculateRiskScore, AUDIT_FILE } from '../hooks/claude-sdk-hook.js';
 import { getVersion } from '../../utils/version.js';
@@ -589,8 +590,14 @@ export function startMCPServer(options = {}) {
             res.end(JSON.stringify({ error: 'Method not allowed for this path' }));
             return;
         }
-        // MCP endpoint
-        if (req.method === 'POST' && req.url === '/mcp') {
+        // MCP endpoint — POST jsonrpc; reject other verbs with 405 + Allow header
+        // (rc.17: was 404, which is wrong HTTP semantic — UX_OBSERVATIONS P3).
+        if (req.url === '/mcp') {
+            if (req.method !== 'POST') {
+                res.writeHead(405, { 'Content-Type': 'application/json', Allow: 'POST' });
+                res.end(JSON.stringify({ error: 'MCP endpoint accepts POST only', method: req.method }));
+                return;
+            }
             let body = '';
             req.on('data', (chunk) => {
                 body += chunk;
@@ -612,6 +619,29 @@ export function startMCPServer(options = {}) {
             });
             return;
         }
+        // /api/version — small completeness item for ops monitoring (rc.17).
+        // ESM-friendly: resolve package.json relative to the compiled module's
+        // own URL via fileURLToPath. Works in both src/ (during dev) and dist/
+        // because the relative path up to package.json is the same in both.
+        if (req.url === '/api/version' && req.method === 'GET') {
+            try {
+                const moduleDir = dirname(fileURLToPath(import.meta.url));
+                const pkgPath = join(moduleDir, '..', '..', '..', 'package.json');
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ version: pkg.version, name: pkg.name }));
+            }
+            catch (e) {
+                // rc.19: don't leak fs paths to the public HTTP surface.
+                // rc.20: but DO log the actual error context for the operator (Codex
+                // rc.19 review caught: previous version dropped `e` and logged only a
+                // static string, costing diagnosability).
+                console.error('[/api/version] failed to read package metadata:', e);
+                res.writeHead(500, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Failed to read package metadata' }));
+            }
+            return;
+        }
         // 404
         res.writeHead(404);
         res.end();

package/dist/infrastructure/security/file-collection.js

@@ -62,6 +62,9 @@ export const IGNORE_DIRS = new Set([
     '.cache',
     '.codehere',
     '.codehere-cache',
+    // Cloned reference repos used for dogfooding / comparison — not the user's code.
+    // Codehere convention; mirrors how `.git` is hidden tooling-data, not source.
+    '.oss-repos',
     // Test fixtures / mocks (intentionally-vulnerable code used as scanner inputs)
     'fixtures',
     'test-fixtures',