gespann 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias
+
+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,107 @@
-# Temporary Holding Version
+# Gespann
 
-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.
+Your coding agents keep making the same mistakes. Gespann finds them in your git history and agent transcripts, and turns each one into a check that stops it next time: a hook, a lint rule, a CI check. Prose rules only as a last resort. Then it measures whether the mistake comes back.
+
+Works across Claude Code, Codex and T3 Code. Everything stays in your repo.
+
+Status: MVP CLI with an interactive view. See `docs/SPEC.md`.
+
+## Use
+
+Needs Node 20 or newer and git.
+
+```sh
+bun install && bun run build
+node dist/cli.js                           # interactive view: browse, propose, apply, check
+node dist/cli.js scan --since 30d          # rank recurring mistakes
+node dist/cli.js propose cmd-gh-watch      # build and test a guardrail for one of them
+node dist/cli.js apply cmd-gh-watch        # install it (hook, lint rule or prose line)
+node dist/cli.js check                     # run every installed guardrail (CI or local)
+```
+
+`scan` reads:
+
+- git: fix commits, reverts, files that keep getting fixed.
+- Claude Code transcripts in `~/.claude/projects/` and Codex sessions in `~/.codex/sessions/` whose working directory is this repo or one of its worktrees.
+- "never `x`" rules in `AGENTS.md`, `CLAUDE.md` and `~/.claude/CLAUDE.md`, to spot commands the agents were told not to run.
+
+## Interactive view
+
+Run `gespann` without a command in a terminal. It opens on the last report, refreshes it in the background when it is older than six hours, and builds and tests fixes for the top mistakes on its own.
+
+- The headline says how much time agents lost and how much the ready fixes win back a month.
+- The bar shows where that time went: one block per fix, brass for time lost, green for fixes you approved.
+- Each row: time lost in the window, time the fix should win back a month, and what the fix does. The selected row opens to show the fix, its test result, the files it writes and how the estimate is made.
+- Press enter twice to approve. Approving writes nothing yet; the fix goes into the next pull request.
+- Press `p` to open that pull request. Gespann makes a new branch from the remote's default branch in a temporary worktree, installs the approved fixes there, commits, pushes and runs `gh pr create`. Your checkout, its branch and uncommitted changes stay as they are. Quitting with approved fixes asks once whether to open it.
+- Open it again later: each fix shows whether it is waiting in a pull request, held (blocked calls, time saved), came back, is too early to judge, or blocks nothing and can go.
+
+| Key | Does |
+|---|---|
+| `↑` `↓` / `j` `k` | choose a fix |
+| `enter` `enter` | approve it for the next pull request |
+| `p` | open the pull request with all approved fixes |
+| `x` | take a fix out of the pull request |
+| `m` | show all fixes, not just the top seven |
+| `e` | show examples from the sessions |
+| `r` | scan again |
+
+`gespann review` prints the same verdicts for scripts. `gespann pr [id ...]` opens the pull request without the view. It needs a remote named `origin` and the GitHub CLI. Pipes and CI keep the plain commands.
+
+### How time is counted
+
+- Agent mistakes: the measured time from the tool call to its result (a `sleep` poll that ran 20 minutes counts 20 minutes), at least a small estimate per kind.
+- Git: 15 minutes per fix commit, 30 per revert.
+- Wins back: a hook stops about 9 in 10 repeats, a lint rule 6 in 10, a line of advice 1 in 3, and advice on code that keeps breaking 1 in 10. These are estimates and the view says so.
+- Calls a gespann hook blocked are not counted as mistakes. They count for the fix that blocked them.
+
+## Harnesses
+
+Gespann tells which app drove each session:
+
+- T3 Code: Claude transcripts with `entrypoint: "t3-code"` or T3 tools, Codex sessions with `originator: "T3 Code"`.
+- Claude Code and Codex on their own.
+
+The report counts sessions per harness. Where a harness has a better fix, Gespann says so. In T3 Code, a hook against `sleep` polling or `gh pr checks --watch` points to `watch_pull_request`; in plain Claude Code it says to check once. One hook script serves all of them: it reads the harness at run time (`T3CODE_THREAD_ID`, `CLAUDE_CODE_ENTRYPOINT`, the Codex payload) and validation checks each message.
+
+Hooks go to Claude Code and, when the repo has Codex sessions, to Codex too (`.codex/hooks.json`, same script). Codex runs a project hook only after you trust it in `/hooks`.
+
+## Files
+
+`scan` writes `.gespann/report.json` and `.gespann/report.md`. Use `--out DIR` to write somewhere else. Secrets and tokens are redacted.
+
+`propose` writes `.gespann/guardrails/<id>/` and checks the guardrail against its own passing and failing fixtures. Nothing in your repo changes until you run `apply`.
+
+| Kind | Files | `apply` installs |
+|---|---|---|
+| hook | `hook.mjs`, `settings.snippet.json`, `codex-hooks.snippet.json`, `fixtures/{fail,pass}.json` | `.claude/hooks/gespann-<id>.mjs` and a `PreToolUse` entry in `.claude/settings.json` (and `.codex/hooks.json`) |
+| lint | `rule.yml` (ast-grep), `rule-test.yml`, `fixtures/{fail,pass}.<ext>` | `.gespann/rules/<id>.yml` and `ruleDirs` in `sgconfig.yml` |
+| prose | `rule.md`, `fixtures/{fail,pass}.md` | one line with source and expiry in `AGENTS.md` (and `CLAUDE.md` if it is a separate file) |
+
+## Gespann Cloud (optional)
+
+The CLI is complete on its own. [Gespann Cloud](https://gespann.app) keeps the history: is a mistake coming back, how often did each hook stop an agent, which repos miss a guardrail your team requires. Free for one repo.
+
+```sh
+gespann sync --dry-run   # print exactly what would be sent; works without an account
+gespann login            # paste a key from gespann.app/account
+gespann scan --no-llm && gespann sync
+```
+
+`sync` sends the last scan's metadata: ids, counts, dates, check results and how often each hook blocked, per day. Ids that come from your commit messages, file names or prompts are hashed with a key that belongs to your account, so outsiders cannot guess them back from a file name. The key is stored on our server too. The repo is sent as a keyed hash too. `--names` also sends readable ids and the repo name. Never code, file paths, commit messages or transcripts.
+
+Installed hooks count each block in `.gespann/local/blocks.jsonl` (guardrail id and time only). `apply` adds `local/` to `.gespann/.gitignore`.
+
+## LLM
+
+By default `scan` and `propose` ask `claude -p` (or `codex exec` with `--llm codex`) to name clusters and suggest a stronger guardrail. Answers must match a strict JSON schema. If the call fails or the guardrail fails its fixtures, Gespann falls back to its own heuristics. `--no-llm` never calls a model.
+
+## Develop
+
+```sh
+bun run typecheck && bun run lint && bun test
+```
+
+Tests build a temp git repo and sample transcripts. They never touch the network or your real `~/.claude` / `~/.codex`.
+
+License: MIT.

package/dist/actions.js

@@ -0,0 +1,141 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { applyGuardrail, checkAll, planApply } from './guardrails/apply.js';
+import { guardrailDir, readManifest, writeManifest } from './guardrails/files.js';
+import { proposeGuardrail } from './guardrails/propose.js';
+import { readReport, reportPaths, writeReport } from './report.js';
+import { scan } from './scan.js';
+import { shipFixes } from './ship.js';
+/** Install hooks for every agent that ran in this repo. Codex and Claude read the same script. */
+export function hookTargetsFor(report) {
+    return report.stats.codexSessions > 0 ? ['claude', 'codex'] : ['claude'];
+}
+export function makeActions(o) {
+    return {
+        repo: o.repo,
+        outDir: o.outDir,
+        llm: Boolean(o.adapter),
+        load() {
+            if (!existsSync(reportPaths(o.outDir).json))
+                return undefined;
+            try {
+                const r = readReport(o.outDir);
+                return r.repo === o.repo ? r : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        async scan(progress, warn) {
+            const report = await scan({
+                repo: o.repo,
+                since: o.since,
+                claudeDir: o.claudeDir,
+                codexDir: o.codexDir,
+                adapter: o.adapter,
+                minCount: o.minCount,
+                warn,
+                progress,
+            });
+            writeReport(o.outDir, report);
+            return report;
+        },
+        async propose(report, id, opts) {
+            const cluster = report.clusters.find((c) => c.id === id);
+            if (!cluster)
+                throw new Error(`No mistake "${id}" in the report.`);
+            const adapter = opts?.llm === false ? undefined : o.adapter;
+            return proposeGuardrail(cluster, o.outDir, adapter, new Date(), hookTargetsFor(report));
+        },
+        apply: (id) => applyGuardrail(o.repo, o.outDir, id),
+        check: () => checkAll(o.repo, o.outDir),
+        state(id) {
+            const m = manifestOf(o.outDir, id);
+            if (m === undefined)
+                return 'none';
+            if (m === null)
+                return 'invalid';
+            if (m.applied)
+                return 'applied';
+            return m.validation.ok ? 'proposed' : 'invalid';
+        },
+        plan(id) {
+            const m = manifestOf(o.outDir, id);
+            return m ? planApply(o.repo, m.spec) : [];
+        },
+        proposal(id) {
+            return manifestOf(o.outDir, id) ?? undefined;
+        },
+        applied: () => appliedGuardrails(o.repo, o.outDir),
+        approve(id) {
+            const m = manifestOf(o.outDir, id);
+            if (!m)
+                throw new Error(`No proposal for "${id}".`);
+            if (!m.validation.ok)
+                throw new Error(`"${id}" fails its own fixtures.`);
+            m.approved = { at: new Date().toISOString() };
+            writeManifest(guardrailDir(o.outDir, id), m);
+        },
+        unapprove(id) {
+            const m = manifestOf(o.outDir, id);
+            if (!m?.approved)
+                return;
+            m.approved = undefined;
+            writeManifest(guardrailDir(o.outDir, id), m);
+        },
+        approved() {
+            const root = join(o.outDir, 'guardrails');
+            if (!existsSync(root))
+                return [];
+            return readdirSync(root)
+                .map((id) => [id, manifestOf(o.outDir, id)])
+                .filter(([, m]) => m?.approved && !m.applied)
+                .sort((a, b) => (a[1]?.approved?.at ?? '').localeCompare(b[1]?.approved?.at ?? ''))
+                .map(([id]) => id);
+        },
+        ship: (ids, progress) => shipFixes({
+            repo: o.repo,
+            outDir: o.outDir,
+            ids,
+            progress,
+            openPullRequest: o.openPullRequest,
+            now: o.now,
+        }),
+    };
+}
+/** Applied guardrails from `outDir`, with the result of `gespann check` for each. */
+export async function appliedGuardrails(repo, outDir) {
+    const root = join(outDir, 'guardrails');
+    if (!existsSync(root))
+        return [];
+    const status = new Map((await checkAll(repo, outDir)).map((s) => [s.id, s]));
+    const out = [];
+    for (const id of readdirSync(root)) {
+        const m = manifestOf(outDir, id);
+        if (!m?.applied)
+            continue;
+        const st = status.get(id);
+        const failed = st?.checks.find((c) => !c.ok);
+        out.push({
+            id,
+            at: m.applied.at,
+            spec: m.applied.spec,
+            ok: st ? st.ok : undefined,
+            ...(failed ? { problem: `${failed.name}: ${failed.detail}` } : {}),
+            ...(m.applied.pr ? { pr: m.applied.pr } : {}),
+        });
+    }
+    return out.sort((a, b) => a.at.localeCompare(b.at));
+}
+/** `undefined`: no proposal. `null`: a proposal that cannot be read. */
+function manifestOf(outDir, id) {
+    const dir = guardrailDir(outDir, id);
+    if (!existsSync(join(dir, 'guardrail.json')))
+        return undefined;
+    try {
+        return readManifest(dir);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,374 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { appliedGuardrails, hookTargetsFor, makeActions } from './actions.js';
+import { buildPayload, CloudError, checkApiUrl, cloudRequest, DEFAULT_API, deleteCredentials, isApiKey, PREVIEW_KEY, readBlocks, readCredentials, repoIdentity, writeCredentials, } from './cloud.js';
+import { ApplyError, applyGuardrail, checkAll } from './guardrails/apply.js';
+import { proposeGuardrail } from './guardrails/propose.js';
+import { makeAdapter } from './llm.js';
+import { findCluster, readReport, renderSummary, renderTable, reportPaths, writeReport, } from './report.js';
+import { reviewGuardrail } from './review.js';
+import { scan } from './scan.js';
+import { ShipError } from './ship.js';
+import { repoRoot } from './sources/git.js';
+import { parseSince, UsageError } from './util.js';
+const HELP = `gespann: turn the mistakes your coding agents repeat into checks.
+
+Usage:
+  gespann [ui] [--since 30d] [--repo .] [--no-llm]   Interactive view (needs a terminal)
+  gespann scan [--since 30d] [--repo .] [--claude-dir PATH] [--codex-dir PATH] [--out DIR] [--no-llm]
+  gespann propose <id|rank> [--repo .] [--out DIR] [--no-llm]
+  gespann apply <id> [--repo .] [--out DIR]
+  gespann check [--repo .] [--out DIR]
+  gespann review [--repo .] [--out DIR]   Did applied guardrails hold? Uses the last scan.
+  gespann pr [id ...] [--repo .] [--out DIR]   Open a pull request with approved fixes (or these ids)
+
+Gespann Cloud (optional, https://gespann.app):
+  gespann login [--key KEY]   Save an API key from gespann.app/account. Reads stdin if no --key.
+  gespann sync [--dry-run] [--names]
+                              Send the last scan's metadata: hashed ids, counts, dates, check
+                              results, blocks per day. Never code, paths, messages or transcripts.
+  gespann logout              Delete the saved key.
+
+Options:
+  --since SPAN       How far back to look: 30d, 2w, 12h or a date. Default 30d.
+  --repo PATH        The git repo to scan. Default: current directory.
+  --out DIR          Where reports and proposals go. Default: <repo>/.gespann
+  --claude-dir PATH  Claude Code home. Default: ~/.claude
+  --codex-dir PATH   Codex home. Default: ~/.codex
+  --no-llm           Use only the built-in heuristics. No model is called.
+  --llm NAME         Model CLI to use: claude (default) or codex.
+  --limit N          Rows in the table. Default 10.
+  --min-count N      Incidents needed for a cluster. Default 2.
+  --dry-run          sync: print exactly what would be sent, send nothing.
+  --names            sync: also send readable ids and the repo name. Off by default.
+  -h, --help         Show this help.
+  -v, --version      Show the version.
+`;
+function version() {
+    try {
+        const pkg = join(fileURLToPath(new URL('.', import.meta.url)), '..', 'package.json');
+        return JSON.parse(readFileSync(pkg, 'utf8')).version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function printChecks(io, checks) {
+    for (const c of checks)
+        io.out(`  ${c.ok ? 'ok  ' : 'FAIL'} ${c.name}: ${c.detail}`);
+}
+export async function main(argv, io) {
+    let parsed;
+    try {
+        parsed = parse(argv);
+    }
+    catch (e) {
+        io.err(`${e.message}\n\n${HELP}`);
+        return 2;
+    }
+    const { values: v, positionals } = parsed;
+    if (v.version) {
+        io.out(version());
+        return 0;
+    }
+    const [given, ...rest] = positionals;
+    const cmd = given ?? (io.tty && !v.help ? 'ui' : undefined);
+    if (v.help || !cmd) {
+        io.out(HELP);
+        return given || v.help ? 0 : 2;
+    }
+    const env = io.env ?? process.env;
+    const doFetch = io.fetch ?? fetch;
+    try {
+        if (cmd === 'login' || cmd === 'logout') {
+            return await account(cmd, v.key, env, io.home ?? homedir(), doFetch, io);
+        }
+        const repo = repoRoot(resolve(v.repo ?? '.'));
+        const outDir = resolve(v.out ?? join(repo, '.gespann'));
+        const adapter = v['no-llm'] ? undefined : (io.adapter ?? makeAdapter(v.llm));
+        const home = io.home ?? homedir();
+        switch (cmd) {
+            case 'ui': {
+                if (!io.tty && !io.runTui) {
+                    throw new UsageError('The interactive view needs a terminal. Use `gespann scan` instead.');
+                }
+                const actions = makeActions({
+                    repo,
+                    outDir,
+                    since: parseSince(v.since ?? '30d'),
+                    claudeDir: v['claude-dir'] ?? join(home, '.claude'),
+                    codexDir: v['codex-dir'] ?? join(home, '.codex'),
+                    adapter,
+                    minCount: v['min-count'] ? Number(v['min-count']) : undefined,
+                });
+                const run = io.runTui ?? (await import('./tui/run.js')).runTui;
+                await run(actions);
+                return 0;
+            }
+            case 'scan': {
+                const report = await scan({
+                    repo,
+                    since: parseSince(v.since ?? '30d'),
+                    claudeDir: v['claude-dir'] ?? join(home, '.claude'),
+                    codexDir: v['codex-dir'] ?? join(home, '.codex'),
+                    adapter,
+                    minCount: v['min-count'] ? Number(v['min-count']) : undefined,
+                    warn: (m) => io.err(m),
+                });
+                const paths = writeReport(outDir, report);
+                io.out(renderSummary(report));
+                io.out('');
+                if (report.clusters.length === 0) {
+                    io.out('No recurring mistakes found.');
+                }
+                else {
+                    io.out('Top recurring mistakes');
+                    io.out(renderTable(report, v.limit ? Number(v.limit) : 10));
+                }
+                io.out('');
+                io.out(`Wrote ${display(repo, paths.json)} and ${display(repo, paths.md)}`);
+                if (report.clusters[0])
+                    io.out(`Next: gespann propose ${report.clusters[0].id}`);
+                return 0;
+            }
+            case 'propose': {
+                const ref = rest[0];
+                if (!ref)
+                    throw new UsageError('Say which mistake: gespann propose <id|rank>.');
+                if (!existsSync(reportPaths(outDir).json))
+                    throw new UsageError('No report yet. Run `gespann scan` first.');
+                const report = readReport(outDir);
+                const cluster = findCluster(report, ref);
+                if (!cluster)
+                    throw new UsageError(`No mistake "${ref}" in the last report.`);
+                const res = await proposeGuardrail(cluster, outDir, adapter, new Date(), hookTargetsFor(report));
+                const m = res.manifest;
+                if (res.fallback)
+                    io.err(`LLM proposal not used: ${res.fallback}. Used the built-in one.`);
+                io.out(`Proposed ${m.spec.kind} guardrail "${m.spec.id}": ${m.spec.title}`);
+                io.out(`Files in ${display(repo, res.dir)}: ${m.files.join(', ')}`);
+                io.out('Validation:');
+                printChecks(io, m.validation.checks);
+                if (!m.validation.ok) {
+                    io.err('The guardrail does not pass its own fixtures. It will not be applied.');
+                    return 1;
+                }
+                io.out(`Review it, then run: gespann apply ${m.spec.id}`);
+                return 0;
+            }
+            case 'apply': {
+                const id = rest[0];
+                if (!id)
+                    throw new UsageError('Say which guardrail: gespann apply <id>.');
+                const changed = await applyGuardrail(repo, outDir, id);
+                if (changed.length === 0)
+                    io.out(`"${id}" was already installed. Nothing changed.`);
+                else {
+                    io.out(`Applied "${id}". Changed:`);
+                    for (const f of changed)
+                        io.out(`  ${display(repo, f)}`);
+                    if (changed.some((f) => f.endsWith(join('.codex', 'hooks.json')))) {
+                        io.out('Codex runs a project hook only after you trust it: open /hooks in Codex once.');
+                    }
+                }
+                return 0;
+            }
+            case 'check': {
+                const results = await checkAll(repo, outDir);
+                if (results.length === 0) {
+                    io.out('No applied guardrails. Run `gespann propose` and `gespann apply` first.');
+                    return 0;
+                }
+                for (const r of results) {
+                    io.out(`${r.ok ? (r.warn ? 'warn' : 'ok  ') : 'FAIL'} ${r.id} (${r.kind})`);
+                    printChecks(io, r.checks);
+                }
+                const failed = results.filter((r) => !r.ok).length;
+                io.out(failed
+                    ? `${failed} of ${results.length} guardrails failed.`
+                    : `All ${results.length} guardrails pass.`);
+                return failed ? 1 : 0;
+            }
+            case 'pr': {
+                const actions = makeActions({ repo, outDir, since: new Date() });
+                const ids = rest.length ? rest : actions.approved();
+                if (ids.length === 0) {
+                    throw new UsageError('Nothing approved yet. Approve fixes in `gespann`, or name them: gespann pr <id>.');
+                }
+                for (const id of ids) {
+                    const state = actions.state(id);
+                    if (state === 'none')
+                        throw new UsageError(`No proposal for "${id}". Run gespann propose ${id}.`);
+                    if (state === 'invalid')
+                        throw new UsageError(`"${id}" fails its own fixtures.`);
+                }
+                const res = await actions.ship(ids, (step) => io.err(`${step}…`));
+                io.out(`Opened ${res.url}`);
+                io.out(`Branch ${res.branch} from ${res.base}, ${ids.length} ${ids.length === 1 ? 'fix' : 'fixes'}:`);
+                for (const f of res.files)
+                    io.out(`  ${f}`);
+                return 0;
+            }
+            case 'review': {
+                if (!existsSync(reportPaths(outDir).json))
+                    throw new UsageError('No report yet. Run `gespann scan` first.');
+                const report = readReport(outDir);
+                const applied = await appliedGuardrails(repo, outDir);
+                if (applied.length === 0) {
+                    io.out('No applied guardrails yet. Approve one in `gespann` or run `gespann apply`.');
+                    return 0;
+                }
+                io.out(`Based on the scan from ${report.generatedAt.slice(0, 10)}.`);
+                const reviews = applied.map((g) => reviewGuardrail(report, g));
+                for (const r of reviews)
+                    io.out(`${r.verdict.padEnd(10)} ${r.id}: ${r.text}`);
+                return reviews.some((r) => r.verdict === 'broken') ? 1 : 0;
+            }
+            case 'sync': {
+                if (!existsSync(reportPaths(outDir).json))
+                    throw new UsageError('No report yet. Run `gespann scan` first.');
+                const now = io.now?.() ?? new Date();
+                const creds = readCredentials(env, home);
+                if (!creds && !v['dry-run'])
+                    throw new UsageError('Not logged in. Run `gespann login` first.');
+                // The account's hash key makes hashed ids unguessable. A dry run without login uses a preview key.
+                const key = creds
+                    ? (await cloudRequest(doFetch, creds, 'GET', '/api/v1/me')).hash_key
+                    : PREVIEW_KEY;
+                const payload = buildPayload({
+                    report: readReport(outDir),
+                    checks: await checkAll(repo, outDir),
+                    blocks: readBlocks(repo, now),
+                    repo: repoIdentity(repo, key),
+                    version: version(),
+                    names: !!v.names,
+                    key,
+                    now,
+                });
+                if (v['dry-run'] || !creds) {
+                    io.out(JSON.stringify(payload, null, 2));
+                    io.err(creds
+                        ? 'Dry run: no scan data was sent (only your hash key was fetched).'
+                        : 'Dry run: nothing was sent. Hashes use a preview key until you log in.');
+                    return 0;
+                }
+                const res = await cloudRequest(doFetch, creds, 'POST', '/api/v1/sync', payload);
+                const blocked = payload.blocks.reduce((n, b) => n + b.count, 0);
+                io.out(`Synced ${payload.repo.name ?? 'this repo'}: ${payload.mistakes.length} mistakes, ${payload.guardrails.length} guardrails, ${blocked} blocks.`);
+                io.out(`Dashboard: ${res.dashboard_url}`);
+                if (res.policy?.missing.length)
+                    io.out(`Required by your team, missing here: ${res.policy.missing.join(', ')}`);
+                if (res.policy?.failing.length)
+                    io.out(`Required by your team, failing here: ${res.policy.failing.join(', ')}`);
+                return 0;
+            }
+            default:
+                throw new UsageError(`Unknown command "${cmd}".\n\n${HELP}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof CloudError) {
+            io.err(e.message);
+            return 1;
+        }
+        if (e instanceof ShipError) {
+            io.err(`Could not open the pull request: ${e.message}`);
+            return 1;
+        }
+        if (e instanceof UsageError || e instanceof ApplyError) {
+            io.err(e.message);
+            return 2;
+        }
+        io.err(`gespann failed: ${e.message}`);
+        return 1;
+    }
+}
+async function account(cmd, keyFlag, env, home, doFetch, io) {
+    if (cmd === 'logout') {
+        io.out(deleteCredentials(env, home)
+            ? 'Logged out. The key is deleted from this machine.'
+            : 'Not logged in.');
+        return 0;
+    }
+    let key = keyFlag?.trim();
+    if (!key) {
+        io.err('Paste your API key from https://gespann.app/account and press Enter:');
+        key = (await (io.readStdin ?? readLine)()).trim();
+    }
+    if (!isApiKey(key))
+        throw new UsageError('That is not a Gespann API key (gsp_live_... or gsp_test_...).');
+    const api = checkApiUrl(env.GESPANN_API_URL || DEFAULT_API);
+    const me = await cloudRequest(doFetch, { api, key }, 'GET', '/api/v1/me');
+    const path = writeCredentials(env, home, { api, key });
+    io.out(`Logged in as ${me.email} (${me.plan}). Key saved to ${path}.`);
+    io.out('Next: gespann scan, then gespann sync.');
+    return 0;
+}
+function readLine() {
+    return new Promise((done) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+            if (data.includes('\n')) {
+                process.stdin.pause();
+                done(data.split('\n')[0] ?? '');
+            }
+        });
+        process.stdin.on('end', () => done(data));
+    });
+}
+function parse(argv) {
+    return parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            since: { type: 'string' },
+            repo: { type: 'string' },
+            out: { type: 'string' },
+            'claude-dir': { type: 'string' },
+            'codex-dir': { type: 'string' },
+            'no-llm': { type: 'boolean' },
+            llm: { type: 'string' },
+            limit: { type: 'string' },
+            'min-count': { type: 'string' },
+            key: { type: 'string' },
+            'dry-run': { type: 'boolean' },
+            names: { type: 'boolean' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+}
+function display(repo, p) {
+    const rel = relative(repo, p);
+    return rel.startsWith('..') ? p : rel;
+}
+const isEntry = (() => {
+    try {
+        return (process.argv[1] !== undefined &&
+            realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)));
+    }
+    catch {
+        return false;
+    }
+})();
+if (isEntry) {
+    // `gespann scan | head` closes the pipe early; that is not an error.
+    process.stdout.on('error', (e) => {
+        if (e.code === 'EPIPE')
+            process.exit(0);
+        throw e;
+    });
+    main(process.argv.slice(2), {
+        out: (s) => process.stdout.write(`${s}\n`),
+        err: (s) => process.stderr.write(`${s}\n`),
+        tty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    }).then((code) => {
+        process.exitCode = code;
+    });
+}