whobrokeit 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Berkan Atik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# whobrokeit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Find the commit that broke it, and prove it.**
+
+English · [Türkçe](README.tr.md)
+
+Describe a bug in one sentence. An AI agent writes a test that shows it, whobrokeit walks your git history to the first commit where that test fails, and proves the result: the test fails at that commit and passes at its parent. Then it explains what went wrong and suggests a fix, which it shows only after the test passes with it.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="whobrokeit finds the commit that broke subtotal(), in 37 seconds" width="860">
+</p>
+
+```sh
+npx whobrokeit demo        # try it on a generated repo with a hidden bug (no AI needed)
+npx whobrokeit demo --ai   # the same, with an AI agent writing the test
+```
+
+## Use it
+
+Describe the bug, from anywhere inside your repo:
+
+```sh
+whobrokeit "Adding 3 mugs costs the same as 1 mug."
+```
+
+This needs [Claude Code](https://github.com/anthropics/claude-code) or [Codex](https://github.com/openai/codex) installed and logged in. whobrokeit uses whichever it finds.
+
+Or bring your own failing test, and no AI is involved:
+
+```sh
+whobrokeit --test "npm test -- cart.test.js"
+whobrokeit --test "pytest tests/test_cart.py -x"
+whobrokeit --test "node repro.mjs" --with repro.mjs   # a test you haven't committed yet
+```
+
+Any command works. Exit code 0 means it works, 125 means this commit can't be tested (skip it), anything else means broken. Add `--explain` to get the explanation and a fix in this mode too.
+
+## What it does
+
+1. **Reproduce.** The agent reads your code and writes a small script that prints a `WHOBROKEIT_BUG:` line when it sees the bug. whobrokeit runs it at `HEAD` and only goes on if it fails there for that reason. A crash without that line counts as "can't tell", so a test that calls a function older commits don't have never blames the wrong commit.
+2. **Find a commit where it still worked.** It walks back 1, 2, 4, 8… commits until the test passes. Or pass `--good <ref>`.
+3. **Bisect.** `git bisect` narrows it down to the first bad commit, skipping commits the test can't tell about.
+4. **Prove it.** It runs the test again at the culprit (fails) and at its parent (passes).
+5. **Explain and fix.** The agent says why the change broke things and proposes an edit. whobrokeit applies it, runs the test, and shows the fix only if the test passes. It saves it as a patch you can `git apply`.
+
+## Tested on real bugs
+
+I ran it on 12 closed regression issues from commander, semver, postcss, luxon, marked, express, markdown-it, fastify and yargs. It got only the issue text, exactly as the reporter wrote it. It proved the commit the maintainers had identified in **11 of 12** cases, in about 100 seconds each. The cases, the one miss and how to rerun everything are in [bench/](bench).
+
+## Safe to run on your repo
+
+- **Your working copy is never touched.** Every check runs in a temporary `git worktree`, which is removed at the end. Uncommitted changes, open files and your current branch stay as they are.
+- **The agent can only read.** Claude Code runs with the Read, Grep and Glob tools only, and with your hooks, plugins and MCP servers turned off. Codex runs in its read-only sandbox. whobrokeit runs the test the agent writes, so check it if you don't trust the repo.
+- **Nothing is taken on faith.** The test has to fail at `HEAD` for the reported reason, the culprit has to be proven against its parent, and a fix has to make the test pass.
+- **Dependencies are installed per commit** when `package.json` or a lockfile changes (npm, pnpm, yarn, bun). Use `--setup "<cmd>"` for anything else, or `--no-setup`.
+
+## Options
+
+| Option | |
+|---|---|
+| `-t, --test <cmd>` | A command that fails while the bug is present. |
+| `--agent <name>` | Who writes the test: `claude`, `codex`, or any command that reads a prompt on stdin and answers on stdout. Default: `claude`, else `codex`. |
+| `--model <name>` | Model for the agent, e.g. `sonnet`. |
+| `--explain` / `--no-explain` | Explain the culprit and test a fix. On by default when you describe a bug, off with `--test`. |
+| `-w, --with <file>` | Copy this file from your working copy into every commit tested. Repeatable. |
+| `-g, --good <ref>` | A commit where it still worked. Default: found automatically. |
+| `-b, --bad <ref>` | A commit where it is broken. Default: `HEAD`. |
+| `--setup <cmd>` / `--no-setup` | Install command, re-run when dependency files change. Default: auto. |
+| `--timeout <sec>` | Time limit for each test run. Default: 600, or 300 for agent-written tests. |
+| `--report <file>` | Also write a Markdown report, ready to paste into an issue or PR. |
+| `--json` | Print the result as JSON. |
+
+Exit codes: `0` found and proven · `1` error · `2` bug not reproduced · `3` no working commit found · `4` inconclusive.
+
+## Good to know
+
+- Requires Node.js 20+ and git. No other dependencies.
+- The test can be in any language your project uses. Automatic dependency install covers JavaScript package managers; for other stacks, use `--setup`.
+- With an agent, a run usually makes two requests: one to write the test, one to explain the culprit (each is retried once if its result doesn't hold up). On the demo repo the whole run takes 30 to 60 seconds.
+- If the project commits no lockfile, old commits get today's versions of their dependencies. A bug that depends on a dependency's version can then be traced to the wrong commit.
+- After a run, the agent's test and the fix are in `.git/whobrokeit/`, outside your working tree.
+
+## License
+
+[MIT](LICENSE)

package/README.tr.md

@@ -0,0 +1,85 @@
+# whobrokeit
+
+**Hatayı getiren commit'i bulur ve kanıtlar.**
+
+[English](README.md) · Türkçe
+
+Hatayı tek cümleyle anlatırsın. Bir yapay zekâ ajanı hatayı gösteren bir test yazar; whobrokeit git geçmişinde bu testin ilk başarısız olduğu commit'e kadar gider ve sonucu kanıtlar: test o commit'te başarısız, bir öncekinde başarılıdır. Ardından neyin bozulduğunu açıklar ve bir düzeltme önerir. Düzeltmeyi ancak test onunla geçtikten sonra gösterir.
+
+<p align="center">
+  <img src="assets/demo.gif" alt="whobrokeit, subtotal() fonksiyonunu bozan commit'i 37 saniyede buluyor" width="860">
+</p>
+
+```sh
+npx whobrokeit demo        # içine hata gizlenmiş örnek bir repoda dene (yapay zekâ gerekmez)
+npx whobrokeit demo --ai   # aynısı, testi yapay zekâ ajanı yazar
+```
+
+## Kullanım
+
+Reponun içindeyken hatayı anlat:
+
+```sh
+whobrokeit "Sepete 3 kupa ekleyince fiyat 1 kupa kadar çıkıyor."
+```
+
+Bunun için [Claude Code](https://github.com/anthropics/claude-code) ya da [Codex](https://github.com/openai/codex) kurulu ve giriş yapılmış olmalı. whobrokeit hangisini bulursa onu kullanır. Açıklama, hatayı hangi dilde yazdıysan o dilde gelir.
+
+Ya da başarısız olan testi kendin ver, o zaman yapay zekâ hiç devreye girmez:
+
+```sh
+whobrokeit --test "npm test -- cart.test.js"
+whobrokeit --test "pytest tests/test_cart.py -x"
+whobrokeit --test "node repro.mjs" --with repro.mjs   # henüz commit'lemediğin bir test
+```
+
+Her komut olur. Çıkış kodu 0 çalışıyor, 125 bu commit test edilemiyor (atla), diğer her şey bozuk demektir. Bu modda da açıklama ve düzeltme istersen `--explain` ekle.
+
+## Ne yapar
+
+1. **Hatayı yeniden üretir.** Ajan kodu okur ve hatayı görünce `WHOBROKEIT_BUG:` satırı basan küçük bir betik yazar. whobrokeit onu `HEAD`'de çalıştırır, yalnız bu sebeple başarısız olursa devam eder. Bu satır olmadan gelen bir çökme "belli değil" sayılır; eski commit'lerde olmayan bir fonksiyonu çağıran test yüzünden yanlış commit suçlanmaz.
+2. **Hâlâ çalıştığı bir commit bulur.** Test geçene kadar 1, 2, 4, 8… commit geri gider. İstersen `--good <ref>` ile kendin verirsin.
+3. **Bisect yapar.** `git bisect` ile ilk bozuk commit'e iner, testin karar veremediği commit'leri atlar.
+4. **Kanıtlar.** Testi suçlu commit'te (başarısız) ve bir öncekinde (başarılı) yeniden çalıştırır.
+5. **Açıklar ve düzeltir.** Ajan değişikliğin neyi bozduğunu anlatır ve bir düzenleme önerir. whobrokeit düzenlemeyi uygular, testi çalıştırır, yalnız test geçerse gösterir. `git apply` ile uygulanabilen bir patch olarak da kaydeder.
+
+## Gerçek hatalarda denendi
+
+commander, semver, postcss, luxon, marked, express, markdown-it, fastify ve yargs projelerinden kapanmış 12 regresyon issue'sunda çalıştırdım. Araca yalnız issue metni verildi, raporu yazan kişinin yazdığı haliyle. **12 vakanın 11'inde** proje sahiplerinin belirlediği commit'i kanıtladı; her biri yaklaşık 100 saniye sürdü. Vakalar, tutmayan tek vaka ve hepsini yeniden çalıştırma adımları [bench/](bench) klasöründe.
+
+## Reponda güvenle çalışır
+
+- **Çalışma kopyana dokunmaz.** Her kontrol geçici bir `git worktree` içinde yapılır ve sonunda silinir. Commit'lenmemiş değişikliklerin, açık dosyaların ve bulunduğun branch olduğu gibi kalır.
+- **Ajan yalnız okuyabilir.** Claude Code yalnız Read, Grep ve Glob araçlarıyla, hook'ların, eklentilerin ve MCP sunucuların kapalıyken çalışır. Codex kendi salt okunur sandbox'ında çalışır. Ajanın yazdığı testi whobrokeit çalıştırır; güvenmediğin bir repoda bu testi kontrol et.
+- **Hiçbir şey sözle kabul edilmez.** Test `HEAD`'de bildirilen sebeple başarısız olmalı, suçlu commit bir öncekiyle karşılaştırılarak kanıtlanmalı, düzeltme de testi geçirmeli.
+- **Bağımlılıklar commit başına kurulur:** `package.json` ya da lockfile değiştiğinde (npm, pnpm, yarn, bun). Başka bir şey için `--setup "<komut>"`, hiç kurmamak için `--no-setup`.
+
+## Seçenekler
+
+| Seçenek | |
+|---|---|
+| `-t, --test <cmd>` | Hata varken başarısız olan bir komut. |
+| `--agent <name>` | Testi kim yazar: `claude`, `codex` ya da stdin'den talimat alıp stdout'a cevap yazan herhangi bir komut. Varsayılan: `claude`, yoksa `codex`. |
+| `--model <name>` | Ajanın modeli, örn. `sonnet`. |
+| `--explain` / `--no-explain` | Suçlu commit'i açıkla ve düzeltme dene. Hatayı anlattığında açık, `--test` ile kapalı. |
+| `-w, --with <file>` | Bu dosyayı çalışma kopyandan test edilen her commit'e kopyala. Birden çok verilebilir. |
+| `-g, --good <ref>` | Hâlâ çalıştığı bir commit. Varsayılan: otomatik bulunur. |
+| `-b, --bad <ref>` | Bozuk olduğu bir commit. Varsayılan: `HEAD`. |
+| `--setup <cmd>` / `--no-setup` | Kurulum komutu, bağımlılık dosyaları değişince yeniden çalışır. Varsayılan: otomatik. |
+| `--timeout <sec>` | Her test çalıştırması için süre sınırı. Varsayılan: 600, ajanın yazdığı testlerde 300. |
+| `--report <file>` | Ayrıca issue ya da PR'a yapıştırmaya hazır bir Markdown rapor yaz. |
+| `--json` | Sonucu JSON olarak bas. |
+
+Çıkış kodları: `0` bulundu ve kanıtlandı · `1` hata · `2` hata yeniden üretilemedi · `3` çalışan commit bulunamadı · `4` sonuçsuz.
+
+## Bilmekte fayda var
+
+- Node.js 20+ ve git gerekir. Başka bağımlılık yok.
+- Test, projenin kullandığı herhangi bir dilde olabilir. Otomatik bağımlılık kurulumu JavaScript paket yöneticilerini kapsar; diğerleri için `--setup` kullan.
+- Ajanla bir çalıştırma genelde iki istek yapar: biri testi yazmak, biri suçlu commit'i açıklamak için (sonuç tutmazsa her biri bir kez daha denenir). Demo reposunda tüm süreç 30–60 saniye sürer.
+- Proje lockfile commit'lemiyorsa eski commit'ler bağımlılıklarının bugünkü sürümleriyle kurulur. Bir bağımlılığın sürümüne bağlı hatalarda yanlış commit bulunabilir.
+- İş bitince ajanın yazdığı test ve düzeltme `.git/whobrokeit/` içinde durur, çalışma klasörünün dışında.
+
+## Lisans
+
+[MIT](LICENSE)

package/dist/agent.js

@@ -0,0 +1,183 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, relative, sep } from 'node:path';
+import { UserError } from './errors.js';
+import { runCommand } from './exec.js';
+const PRESETS = ['claude', 'codex'];
+const LABELS = { claude: 'Claude Code', codex: 'Codex' };
+/**
+ * `undefined` picks the first installed preset. A preset name picks that one.
+ * Anything else is a custom command: it gets the prompt on stdin and answers on stdout.
+ */
+export async function pickAgent(choice, cwd, model) {
+    if (model !== undefined && !/^[\w.:/@[\]-]+$/.test(model))
+        throw new UserError(`--model ${model} is not a valid model name.`);
+    if (choice !== undefined && !PRESETS.includes(choice)) {
+        if (model !== undefined)
+            throw new UserError('--model only works with --agent claude or --agent codex.');
+        return customAgent(choice);
+    }
+    const candidates = choice ? [choice] : [...PRESETS];
+    for (const name of candidates) {
+        const probe = await runCommand(`${name} --version`, cwd, 30_000);
+        if (probe.code === 0)
+            return name === 'claude' ? claudeAgent(model) : codexAgent(model);
+    }
+    if (choice) {
+        throw new UserError(`${LABELS[choice]} (\`${choice}\`) is not installed or not on your PATH.`);
+    }
+    throw new UserError('Describing a bug in plain words needs Claude Code or Codex installed.', 'Install one of them, use --agent "<command>" for another tool, or pass your own test with --test "<command>".');
+}
+function claudeAgent(model) {
+    const label = LABELS.claude;
+    const command = [
+        'claude -p',
+        '--output-format stream-json --verbose',
+        // Read-only tools, no hooks, plugins or MCP servers, nothing left in the session list.
+        '--tools Read,Grep,Glob',
+        '--permission-prompts none',
+        '--safe-mode --strict-mcp-config',
+        '--no-session-persistence',
+        model ? `--model ${model}` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return {
+        label,
+        async ask(prompt, cwd, { timeoutMs, onActivity }) {
+            let result;
+            const lines = lineSplitter((line) => {
+                if (!line.startsWith('{'))
+                    return;
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                if (event.type === 'assistant') {
+                    for (const part of event.message?.content ?? []) {
+                        if (part.type === 'tool_use')
+                            onActivity?.(describeTool(part.name, part.input ?? {}, cwd));
+                    }
+                }
+                else if (event.type === 'result') {
+                    result = { text: event.result ?? '', isError: Boolean(event.is_error), subtype: event.subtype };
+                }
+            });
+            // The user's `language` setting survives --safe-mode and beats the prompt's "write in the bug
+            // report's language" rule, so a Turkish setting turned English reports into Turkish answers.
+            const dir = await mkdtemp(join(tmpdir(), 'whobrokeit-claude-'));
+            const settings = join(dir, 'settings.json');
+            let run;
+            try {
+                await writeFile(settings, JSON.stringify({ language: '' }));
+                run = await runCommand(`${command} --settings "${settings}"`, cwd, timeoutMs, { input: prompt, onStdout: lines.push });
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
+            }
+            lines.flush();
+            failIfBroken(label, run, timeoutMs, result === undefined);
+            if (result?.isError) {
+                throw new UserError(`${label} stopped with an error: ${result.text || result.subtype || 'unknown error'}`);
+            }
+            return result?.text ?? '';
+        },
+    };
+}
+function codexAgent(model) {
+    const label = LABELS.codex;
+    return {
+        label,
+        async ask(prompt, cwd, { timeoutMs }) {
+            const dir = await mkdtemp(join(tmpdir(), 'whobrokeit-codex-'));
+            const answerFile = join(dir, 'answer.txt');
+            try {
+                const command = [
+                    'codex exec',
+                    '--sandbox read-only --skip-git-repo-check --ephemeral --color never',
+                    model ? `-m ${model}` : '',
+                    `-o "${answerFile}"`,
+                    '-',
+                ]
+                    .filter(Boolean)
+                    .join(' ');
+                const run = await runCommand(command, cwd, timeoutMs, { input: prompt });
+                const answer = await readFile(answerFile, 'utf8').catch(() => null);
+                failIfBroken(label, run, timeoutMs, answer === null);
+                return answer ?? '';
+            }
+            finally {
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
+            }
+        },
+    };
+}
+function customAgent(command) {
+    return {
+        label: command,
+        async ask(prompt, cwd, { timeoutMs }) {
+            let stdout = '';
+            const run = await runCommand(command, cwd, timeoutMs, { input: prompt, onStdout: (text) => (stdout += text) });
+            failIfBroken(command, run, timeoutMs, false);
+            return stdout;
+        },
+    };
+}
+function failIfBroken(label, run, timeoutMs, noAnswer) {
+    if (run.timedOut) {
+        throw new UserError(`${label} did not answer within ${Math.round(timeoutMs / 60_000)} minutes.`);
+    }
+    if (run.code === 0 && !noAnswer)
+        return;
+    // Drop the JSON event stream; keep what a human would read.
+    const said = run.output
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith('{'))
+        .slice(-8)
+        .join('\n');
+    throw new UserError(`${label} failed (exit code ${run.code}).${said ? `\n${said}` : ''}`, 'Check that it works on its own in this terminal (is it logged in?), or pass your own test with --test.');
+}
+function describeTool(name, input, cwd) {
+    const str = (key) => (typeof input[key] === 'string' ? input[key] : '');
+    const where = (path) => {
+        if (!path)
+            return '';
+        const rel = isAbsolute(path) ? relative(cwd, path) : path;
+        if (!rel)
+            return '.';
+        return rel.startsWith('..') ? path : rel.split(sep).join('/');
+    };
+    switch (name) {
+        case 'Read':
+            return `reading ${where(str('file_path'))}`;
+        case 'Grep':
+            return `searching for "${str('pattern')}"${str('path') ? ` in ${where(str('path'))}` : ''}`;
+        case 'Glob':
+            return `looking for ${str('pattern')}${str('path') ? ` in ${where(str('path'))}` : ''}`;
+        default:
+            return `using ${name ?? 'a tool'}`;
+    }
+}
+/** Turns arbitrary stdout chunks into whole lines. */
+function lineSplitter(onLine) {
+    let buffer = '';
+    return {
+        push: (text) => {
+            buffer += text;
+            let newline;
+            while ((newline = buffer.indexOf('\n')) !== -1) {
+                onLine(buffer.slice(0, newline).trim());
+                buffer = buffer.slice(newline + 1);
+            }
+        },
+        flush: () => {
+            if (buffer.trim())
+                onLine(buffer.trim());
+            buffer = '';
+        },
+    };
+}

package/dist/cli.js

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { mkdir, mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pickAgent } from './agent.js';
+import { DEMO_BUG_REPORT, DEMO_REPRO, DEMO_TEST, createDemoRepo } from './demo.js';
+import { UserError, findCulprit } from './engine.js';
+import { killActiveCommands } from './exec.js';
+import { git } from './git.js';
+import { colorFor, liveReporter, renderOutcome, toMarkdown } from './report.js';
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+    .version;
+const HELP = `whobrokeit: find the commit that broke it, and prove it.
+
+Usage
+  whobrokeit "<what is broken>" [options]   an AI agent writes a test that shows the bug
+  whobrokeit --test "<command>" [options]   bring your own failing test
+  whobrokeit demo [dir] [--ai]              try it on a generated repo with a hidden bug
+
+Options
+  -t, --test <cmd>     A command that fails while the bug is present.
+                       Exit 0 = works, 125 = can't tell (skip), anything else = broken.
+      --agent <name>   Who writes the test: claude, codex, or any command that reads a
+                       prompt on stdin and answers on stdout. Default: claude, else codex.
+      --model <name>   Model for the agent, e.g. sonnet.
+      --explain        Also explain the culprit and test a fix when you use --test.
+      --no-explain     Skip the explanation and fix when you describe a bug.
+  -w, --with <file>    Copy this file from your working copy into every commit tested.
+                       Use it for a repro test you haven't committed. Repeatable.
+  -g, --good <ref>     A commit where it still worked. Default: found automatically.
+  -b, --bad <ref>      A commit where it is broken. Default: HEAD.
+      --setup <cmd>    Install command, re-run when dependency files change. Default: auto (npm/pnpm/yarn/bun).
+      --no-setup       Never install dependencies.
+      --timeout <sec>  Time limit for each test run. Default: 600, or 300 for agent-written tests.
+      --report <file>  Also write a Markdown report.
+      --json           Print the result as JSON.
+  -h, --help
+  -v, --version
+
+Your working copy is never touched: every check runs in a temporary git worktree.
+The agent can only read the code. whobrokeit runs the test it writes, and trusts it
+only after seeing it fail where the bug is. A suggested fix is shown only after the
+test passes with it.
+
+Exit codes
+  0 found and proven · 1 error · 2 bug not reproduced · 3 no working commit found · 4 inconclusive
+`;
+/**
+ * Keeps the agent-written test and the fix in .git/whobrokeit/, next to git's own state: out
+ * of the working copy, but easy to open, copy or `git apply`. Returns a path to show, or
+ * undefined if it could not be saved.
+ */
+async function saveFile(cwd, name, content) {
+    try {
+        const gitDir = resolve(cwd, await git(['rev-parse', '--git-common-dir'], cwd));
+        const target = join(gitDir, 'whobrokeit', basename(name));
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, content);
+        const shown = relative(process.cwd(), target);
+        return shown.startsWith('..') ? target : shown.split(sep).join('/');
+    }
+    catch {
+        return undefined;
+    }
+}
+function exitCode(outcome) {
+    switch (outcome.kind) {
+        case 'found':
+            return outcome.proven ? 0 : 4;
+        case 'not-reproduced':
+        case 'cannot-test':
+        case 'no-repro':
+            return 2;
+        case 'no-good-commit':
+        case 'good-fails':
+            return 3;
+        case 'ambiguous':
+            return 4;
+    }
+}
+async function main(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            test: { type: 'string', short: 't' },
+            with: { type: 'string', short: 'w', multiple: true },
+            good: { type: 'string', short: 'g' },
+            bad: { type: 'string', short: 'b' },
+            setup: { type: 'string' },
+            'no-setup': { type: 'boolean' },
+            agent: { type: 'string' },
+            model: { type: 'string' },
+            ai: { type: 'boolean' },
+            explain: { type: 'boolean' },
+            'no-explain': { type: 'boolean' },
+            timeout: { type: 'string' },
+            report: { type: 'string' },
+            json: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    if (values.help) {
+        process.stdout.write(HELP);
+        return 0;
+    }
+    if (values.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    const progress = colorFor(process.stderr);
+    let cwd = process.cwd();
+    let test = values.test;
+    let bug = positionals.join(' ').trim() || undefined;
+    let withFiles = values.with ?? [];
+    if (positionals[0] === 'demo') {
+        const dir = positionals[1] ? resolve(positionals[1]) : await mkdtemp(join(tmpdir(), 'whobrokeit-demo-'));
+        await createDemoRepo(dir);
+        process.stderr.write(`\n${progress.bold('Demo repo:')} ${dir}\n` +
+            `24 commits of a tiny shopping-cart library. A user reports: "${DEMO_BUG_REPORT}"\n`);
+        cwd = dir;
+        if (values.ai) {
+            bug = DEMO_BUG_REPORT;
+            test = undefined;
+        }
+        else {
+            process.stderr.write(progress.dim(`The repro test ${DEMO_REPRO} is not committed; --with brings it into every commit.\n` +
+                'Add --ai to have an AI agent write the test from the bug report instead.\n'));
+            bug = undefined;
+            test = DEMO_TEST;
+            withFiles = [DEMO_REPRO];
+        }
+    }
+    else if (values.ai) {
+        throw new UserError('--ai only works with `whobrokeit demo`. Elsewhere, just describe the bug in quotes.');
+    }
+    if (test && bug) {
+        throw new UserError('Give either a bug description or --test, not both.');
+    }
+    if (!test && !bug) {
+        process.stdout.write(HELP);
+        return 1;
+    }
+    let timeoutMs;
+    if (values.timeout !== undefined) {
+        const seconds = Number(values.timeout);
+        if (!Number.isFinite(seconds) || seconds <= 0)
+            throw new UserError('--timeout must be a positive number of seconds.');
+        timeoutMs = seconds * 1000;
+    }
+    const controller = new AbortController();
+    const onSigint = () => {
+        if (controller.signal.aborted)
+            process.exit(130);
+        process.stderr.write('\nStopping and cleaning up…\n');
+        controller.abort();
+        killActiveCommands();
+    };
+    process.on('SIGINT', onSigint);
+    if (values.explain && values['no-explain'])
+        throw new UserError('Give either --explain or --no-explain, not both.');
+    const wantsExplain = bug ? !values['no-explain'] : Boolean(values.explain);
+    try {
+        let describe;
+        let explain;
+        if (bug || wantsExplain) {
+            const agent = await pickAgent(values.agent, cwd, values.model);
+            if (bug)
+                describe = { bug, agent };
+            if (wantsExplain)
+                explain = { agent };
+        }
+        else if (values.agent || values.model) {
+            throw new UserError('--agent and --model need a bug description or --explain; with only --test, no agent is used.');
+        }
+        const outcome = await findCulprit({
+            cwd,
+            test,
+            describe,
+            explain,
+            withFiles,
+            good: values.good,
+            bad: values.bad,
+            setup: values['no-setup'] ? false : values.setup,
+            timeoutMs,
+            signal: controller.signal,
+            onEvent: values.json ? undefined : liveReporter(process.stderr, progress, test ? { test } : { bug: bug ?? '' }),
+        });
+        const fix = outcome.kind === 'found' ? outcome.explanation?.fix : undefined;
+        const saved = {
+            test: outcome.repro ? await saveFile(cwd, outcome.repro.path, outcome.repro.code) : undefined,
+            fix: fix?.verified ? await saveFile(cwd, 'fix.patch', fix.patch) : undefined,
+        };
+        if (values.report)
+            await writeFile(resolve(values.report), toMarkdown(outcome, test ?? ''));
+        if (values.json) {
+            process.stdout.write(`${JSON.stringify({ ...outcome, savedTest: saved.test, savedFix: saved.fix }, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(renderOutcome(outcome, colorFor(process.stdout), process.stdout.columns || 100, saved));
+        }
+        return exitCode(outcome);
+    }
+    catch (err) {
+        if (controller.signal.aborted)
+            return 130;
+        throw err;
+    }
+    finally {
+        process.off('SIGINT', onSigint);
+    }
+}
+main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    const c = colorFor(process.stderr);
+    if (err instanceof UserError) {
+        process.stderr.write(`${c.red('error:')} ${err.message}\n${err.hint ? `${c.dim(err.hint)}\n` : ''}`);
+    }
+    else if (err instanceof Error && 'code' in err && String(err.code).startsWith('ERR_PARSE_ARGS')) {
+        process.stderr.write(`${c.red('error:')} ${err.message}\n${c.dim('Run whobrokeit --help for usage.')}\n`);
+    }
+    else {
+        process.stderr.write(`${c.red('Unexpected error:')} ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    }
+    process.exitCode = 1;
+});