flatbread-cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,400 @@
-# Temporary Holding Version
-
-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.
+# flatbread-cli
+
+Reads a completed agent session off local disk, normalizes it into a
+`FlatbreadTrace`, and sanitizes it for sharing. Nothing is uploaded unless you pass `--publish`
+(or set `FLATBREAD_API_URL` and `FLATBREAD_API_TOKEN` yourself), and then only after the review is
+confirmed. The commands still to come (`setup`, `blame`) are in `PLAN.md` §8.
+
+```bash
+npm install -g flatbread-cli          # installs the `flatbread` command (Node 20 or newer)
+npx -y flatbread-cli --help           # or run it without installing
+```
+
+On npm since 2026-10-18 (0.1.0). **The npm package is `flatbread-cli`, not `flatbread`.** `flatbread` on npm is an unrelated
+project, so `npx flatbread` runs somebody else's code. The command it installs is `flatbread`.
+
+## Commands
+
+```bash
+flatbread parse --file <path.jsonl>   # parse one session log
+flatbread parse --latest              # newest primary session under the projects dir
+
+flatbread share                       # newest session: parse, scan, review, write a draft
+flatbread share --file <path.jsonl>   # a specific session
+flatbread share --no-review           # redact everything, no browser (non-interactive)
+flatbread share --no-open             # start the review server but do not launch a browser
+
+flatbread share --publish             # after review, upload to the signed-in site
+
+flatbread login | logout | whoami     # sign the CLI in to a site (device flow)
+
+flatbread share --pr <url>            # link the pull request this run belongs to (https)
+
+flatbread view                        # write the Execution Brief and CAPSULE.md beside the newest artifact
+
+flatbread pull <id-or-url>            # print a published run's Context Capsule
+flatbread pull <id-or-url> --out <f>  # or write it to a file
+flatbread mcp                         # stdio MCP server: flatbread_search_traces, flatbread_get_capsule
+
+flatbread hook install                # offer the share at the end of a Claude Code turn
+flatbread hook status                 # where it is installed, and what it has seen
+flatbread hook uninstall              # remove only the flatbread handlers
+```
+
+## The Claude Code hook
+
+`flatbread hook install` merges two handlers into `~/.claude/settings.json`
+(`CLAUDE_CONFIG_DIR` moves it; `--settings <path>` picks any file; `--dry-run` prints the
+merged block and writes nothing). Other tools' hooks in that file are left alone, a second
+install changes nothing, and a settings file that does not parse is **refused** - the block
+to paste is printed instead.
+
+What the two handlers do is decided by what the harness allows, not by taste:
+
+| Event | What it does | Why not more |
+|---|---|---|
+| `Stop` | prints ONE line offering the share, once per session, after two finished turns | it is the only event whose `systemMessage` reaches the human |
+| `SessionEnd` | records that the session ended, and its reason | Claude Code **discards** a SessionEnd hook's output, so it cannot speak |
+
+- The hook **never blocks and never continues a turn**: `decision: "block"` and
+  `additionalContext` would put the agent back to work, and exit 2 blocks a `Stop`, so
+  `hook notify` exits 0 on every path including its own internal errors. Diagnostics go to
+  stderr, which is the debug log (`claude --debug`), and they name every reason it stayed
+  quiet.
+- `SessionEnd` asks for **no timeout**, because a per-hook timeout raises the shared
+  1.5-second SessionEnd budget for every other hook in that file.
+- The offer **claims nothing**. It does not say the run is unshared - the hook never reads
+  the store - and it cannot ask for a visibility, because a hook has no terminal. It names
+  the command, and the choice stays in the local review page.
+- **An offer it cannot remember making is not made.** The "offered" record is written before
+  the line is printed; if that write fails the hook stays quiet rather than nag every turn.
+- Turn it off with `FLATBREAD_HOOK_DISABLED=1`, or change when it speaks with
+  `FLATBREAD_HOOK_OFFER_AFTER=<turns>`. State lives in `~/.flatbread/hook-state.json`
+  (`FLATBREAD_HOME` moves it) and is capped at 50 sessions. Nothing is ever written into
+  your repository.
+
+Two things the harness's own changelog says can break an install silently, both handled:
+
+- **Exec form (`args`) landed in Claude Code 2.1.139.** An older version ignores `args` and
+  would run the interpreter with no arguments: a hook that never answers, costing every turn
+  the full Stop timeout. `hook install` reads `claude --version` and **refuses** on a version
+  it knows is too old; a version it could not read is reported as `NOT RETRIEVED`, never as
+  "fine".
+- **`transcript_path` pointed at the wrong directory for resumed sessions before 2.1.72**, so
+  the offer requires the transcript to EXIST before it names it. A wrong path shows up as
+  silence with a reason, never as a command that fails when you paste it.
+
+`hook install` also **probes before it writes**: it runs the exact command it is about to
+install, with a synthetic event, and refuses to write one that does not exit 0 silently. That
+closes the worst failure available — a hook that is installed, broken, and only visible under
+`claude --debug`. `--no-probe` skips it for a machine where spawning is blocked.
+
+One caveat worth knowing: Claude Code writes the transcript asynchronously, so the last
+message of a turn may not be in the file yet. The offer names a command you run later, and the
+trace is parsed then, so this only matters if you share within a second of the answer.
+
+**It has never run under a real Claude Code**: this machine has none. Everything above is
+proven by unit tests against recorded event payloads and by driving `hook notify` with the
+event JSON on stdin. `HUMAN-TESTS.md` **A7** is the test a person has to run.
+
+## Persistence and publishing
+
+After the review gate, `share` mints a slug and writes a `TraceRecord` into the local
+store (`packages/cli/.tmp/store/<slug>.json`), then prints:
+
+- the **slug** and its `/r/<slug>` URL
+- a **manage token**, shown once. Only its sha256 hash is stored, so there is no
+  recovery path; a `private` record is unreachable without it.
+
+`FLATBREAD_STORE_DIR` overrides the store location outright; `FLATBREAD_TMP_DIR`
+moves the whole scratch directory (the store becomes `<tmp>/store`).
+
+**Nothing is uploaded** unless you pass `--publish` with a login stored by
+`flatbread login`, or set BOTH `FLATBREAD_API_URL` and `FLATBREAD_API_TOKEN`. The URL
+and the token resolve independently, each falling back to the stored login, and a
+STORED token is never offered to a site that did not issue it. Being signed in is not
+permission to upload: that is what `--publish` is for. `packages/cli/src/publish.ts` is the only file in this repository
+permitted to make an outbound request, the verify suite enforces that by name across
+all four packages, and it refuses to send a token over plain `http` to anything but
+loopback. A publish failure never invalidates the local record; it is reported.
+
+Visibility is `private` unless a human raises it - in the review UI, or from the owner
+panel on the site while signed in as the run's owner. There is no `--visibility` flag
+and no API field for it: `--no-review` is non-interactive and must never publish.
+
+`parse` writes nothing: it prints the run's summary and brief. `parse --save` writes the raw
+(unredacted) trace to `packages/cli/.tmp/last-parse.json`, and `parse --out <file>` writes it there instead.
+`share` writes `packages/cli/.tmp/last-share.json`. `--title <text>` sets the run's title (the review
+page opens with it and can still change it; every secret in a typed title is redacted), and
+`--commit [sha]` binds the run to a commit (bare = HEAD) and records whether the working tree was
+clean against it.
+`view` reads the newest artifact (share draft preferred over raw parse), builds the
+deterministic Execution Brief with `buildExecutionBrief`, writes `last-brief.json` and
+`CAPSULE.md`, and prints `open http://127.0.0.1:3000/r/local`. It does **not**
+start Next: a hung dev server is worse than one honest instruction line. If the source
+is a raw parse, or a share draft that kept flagged originals, it prints a NOTE - the
+capsule quotes trace text verbatim and inherits whatever the source still contains.
+
+`parse` and `share` record the git branch, HEAD commit and uncommitted file names when the
+session's working directory is a git repository. Nothing else is read from git, the index is
+never written, and a log that names a different branch than the checkout gets no commit.
+
+### Auto-capture: `flatbread setup`
+
+`flatbread setup` turns on capture for this machine. It installs the Claude Code hook (as `hook
+install` does) with one difference - the SessionEnd handler also starts `flatbread capture` for the
+session that just ended - and, inside a git repository, a chained `post-commit` that records each
+commit against the newest session of that repository (if that session moved in the last two hours).
+
+Every capture goes to `~/.flatbread/bucket` (`FLATBREAD_HOME/bucket`): one record per session, with
+EVERY redaction match redacted, visibility `private`, never uploaded. A capture is not a share; to
+publish one, run `share --file` on its session, which opens the review. `capture.log` in the bucket
+has one line per capture, including the ones that skipped or were refused.
+
+The post-commit hook never replaces yours: an existing `post-commit` is kept as
+`post-commit.pre-flatbread`, runs first with git's arguments, and its exit status is the hook's.
+It runs after the commit exists, so no SHA changes. When the repository sets `core.hooksPath`
+(husky, lefthook) nothing is written and the line to add is printed. When `core.hooksPath` is
+set machine-wide (system or global config), the hook goes in the repository's own hooks
+directory and setup says it fires only if that machine-wide hook runs it.
+
+`setup --dry-run` writes nothing. `setup --uninstall` removes the handlers and the hook, and puts
+a chained hook back byte for byte. `FLATBREAD_HOOK_DISABLED=1` stops every capture.
+
+`flatbread search <words>` answers from this machine's shared runs, its captured runs, then the
+site - the same text the MCP tool returns. Words are matched as typed, and by stem ("retry" finds
+"retries" and "retrying"). `--local` leaves the site out; a site that did not answer is said, and
+exits 1.
+
+`pull` and `mcp` only read. A token from `flatbread login` goes only to the site that issued it;
+a private run's share link (`?t=`) is sent as a header, never in a URL. Add the MCP server to
+Claude Code with `claude mcp add flatbread -- flatbread mcp`.
+
+### Building the package
+
+```bash
+npm run build -w flatbread-cli        # bundles schema, store and zod into dist/flatbread.mjs
+cd packages/cli && npm pack           # flatbread-cli-<version>.tgz, the file npm publish uploads
+```
+
+## Verify
+
+From the repo root:
+
+```bash
+npm install
+npx tsx packages/cli/src/index.ts parse --file packages/cli/test/fixtures/claude-code-sample.jsonl
+npm run verify        # every suite, no framework, no network
+npm run typecheck
+```
+
+`parse --latest` on a machine with no `~/.claude/projects` prints
+`no sessions found in <dir>` and exits 0. To prove it without deleting anything:
+
+```bash
+# macOS / Linux
+CLAUDE_CONFIG_DIR=$(mktemp -d) npx tsx packages/cli/src/index.ts parse --latest
+# PowerShell
+$env:CLAUDE_CONFIG_DIR="$env:TEMP\no-claude-here"; npx tsx packages/cli/src/index.ts parse --latest
+```
+
+Requires Node 20+. Nothing is compiled: `tsx` runs the TypeScript directly, and
+`@flatbread/schema` is consumed as source through the workspace symlink.
+
+## Where sessions live
+
+```
+<projects-dir>/<encoded-cwd>/<session-uuid>.jsonl
+```
+
+- Projects dir is `$CLAUDE_CONFIG_DIR/projects` when that variable is set,
+  otherwise `path.join(os.homedir(), ".claude", "projects")`.
+- Encoded cwd replaces every non-alphanumeric character with `-`. The encoding is
+  lossy, so it is only ever used in the encode direction, never decoded back.
+- `agent-*.jsonl` and anything under a `subagents/` directory is a subagent
+  transcript and is never treated as a primary session.
+
+## Reading rules
+
+The reader streams the file with `readline` and parses one line at a time. A
+whole session is never handed to `JSON.parse`, so one corrupt byte cannot cost
+the entire trace.
+
+Three separate skip counters are reported, because they mean different things:
+
+| counter | meaning |
+| --- | --- |
+| `malformed` | not JSON, not an object, or no string `type`. Corruption. |
+| `known ignored type` | a type we know and deliberately drop (`system`, `progress`, `file-history-snapshot`, `queue-operation`, `pr-link`, …). |
+| `unknown type` | a `type` this parser has never seen. **Watch this number** - it is how we find out the format moved. |
+
+Blank lines are counted separately and are not treated as corruption.
+
+Only `user` and `assistant` records produce steps. Only these fields are read:
+
+- any record: `type`, `uuid`, `parentUuid`, `timestamp`, `sessionId`, `cwd`,
+  `gitBranch`, `version`, `isSidechain`
+- `user`: `message.content` as a string, or as blocks of `text` / `tool_result`
+  (`tool_use_id`, `is_error`, `content`)
+- `assistant`: `message.model`, `message.content[]` of `text` / `thinking` /
+  `tool_use` (`id`, `name`, `input`), `message.usage.{input_tokens,
+  output_tokens, cache_creation_input_tokens, cache_read_input_tokens}`
+
+## Normalization rules
+
+- **Order.** File order is the base truth. Steps are re-sorted by `timestamp`
+  only when every step has a parseable one, and that sort is stable, so several
+  blocks inside one message keep their block order.
+- **`user_prompt`.** A user message that is *not* only `tool_result` blocks. A
+  turn carrying both a prompt and tool results yields both kinds of step, with
+  the prompt placed at its first text block.
+- **`tool_call`.** One step per `tool_use`. `content` is a one-line label built
+  only from input fields that are present (`command`, `file_path`, `pattern`,
+  `url`, `description`, `prompt`, `query`); the full input is on `tool.input`.
+- **`tool_result`.** Matched to its `tool_use` by `tool_use_id`. The match sets
+  `tool.output` and `tool.isError` on the earlier `tool_call` step **and** emits
+  its own step. Unmatched results are counted and reported.
+- **`error_recovery`.** A `tool_result` with `is_error: true` becomes exactly one
+  `error_recovery` step; it is *not* also emitted as `tool_result`, or every
+  failure would appear twice. Errors are never inferred from prose.
+- **`filesChanged`.** Unique `file_path` (or `notebook_path`) values from
+  `Write` / `Edit` / `MultiEdit` / `NotebookEdit` / `Update` inputs, excluding
+  calls whose result came back `is_error: true` - a `Write` that raised `EACCES`
+  changed nothing. No path in the log means no file recorded; none is invented.
+  Unknown tool names contribute nothing here, because "did this write a file"
+  cannot be guessed from a name.
+- **`diff`.** Only when the log actually carries one: an explicit `patch`
+  string, `old_string`/`new_string`, or the first entry of MultiEdit `edits`.
+  A `Write` has no old side, so it gets no diff.
+- **Truncation.** Step `content` at 4000 chars, every string inside `tool.input`
+  at 2000 chars, both with `…[truncated]` appended. Limits live in
+  `@flatbread/schema` (`LIMITS`) so the web renderer agrees with the CLI.
+- **`title`.** First real `user_prompt`, whitespace collapsed, max 120 chars.
+  Otherwise `"Untitled session"`.
+- **`model`.** First `assistant.message.model`, otherwise `"unknown"`.
+- **`visibility`.** Always `"private"` out of the parser.
+
+## Deliberate non-goals in this pass
+
+No upload, no localhost review UI, no Next.js. Flatbread does not replay a trace onto
+another codebase, and no copy should ever suggest it does.
+
+---
+
+# Sharing: `flatbread share`
+
+The command exists to put a human gate in front of the data. It never uploads
+anything, and it cannot: there is no outbound request anywhere in this package,
+and a test greps the sources to keep it that way.
+
+```
+parse the session  ->  scan every string  ->  review in the browser  ->  write a sanitized draft
+                                              (you decide, per match)
+```
+
+1. Parse with the same code `parse` uses. Sharing changes nothing about parsing.
+2. Scan `title`, `summary`, `source.cwd`, `source.sourcePath`, every
+   `step.content`, every string inside `tool.input` (recursively), `tool.output`,
+   `diff.filePath` and `diff.patch`.
+3. Serve one page on `http://127.0.0.1:4321` (then 4322-4325 if busy).
+4. You tick any match to KEEP its original text; everything else is redacted.
+5. You pick visibility: `private` (default), `unlisted`, `public`.
+6. Confirm writes `packages/cli/.tmp/last-share.json`. Cancel writes nothing.
+
+## The redaction engine
+
+Deterministic, local, no model. The same trace and the same choices always give a
+byte-identical result, which is what makes the review meaningful: the artifact is
+exactly what you approved.
+
+Matched spans are replaced with a stable token such as `«REDACTED:aws_access_key»`.
+
+| # | rule id | what it matches | note |
+| --- | --- | --- | --- |
+| 1 | `aws_access_key` | `AKIA[0-9A-Z]{16}` | |
+| 2 | `private_key` | `-----BEGIN … PRIVATE KEY-----` … `-----END … PRIVATE KEY-----` | the whole block is one match |
+| 3 | `github_token` | `gh[pousr]_[A-Za-z0-9_]{20,}` | |
+| 4 | `anthropic_key` | `sk-ant-[A-Za-z0-9\-_]+` | before rule 5, so it cannot double-fire |
+| 5 | `openai_key` | `sk-[A-Za-z0-9]{20,}` | |
+| 6 | `slack_token` | `xox[baprs]-[A-Za-z0-9-]+` | |
+| 7 | `jwt` | `eyJ….….…` | before rule 8 |
+| 8 | `bearer_token` | `Bearer <value>` | keeps `Bearer `, redacts the value |
+| 9 | `home_path` | `C:\Users\<name>`, `/Users/<name>`, `/home/<name>` | keeps the path shape, redacts the username; case-insensitive |
+| 10 | `assigned_secret` | `(api_key\|apikey\|api-key\|secret\|password\|token\|passwd)\s*[:=]\s*\S+` | keeps the left-hand name, redacts the value; case-insensitive, because real config says `API_KEY=` |
+| 11 | `secret_field_name` | any string whose FIELD NAME is a credential name | **evaluated first**, see below |
+
+**Evaluation order is significant.** An earlier rule wins an overlap, so specific
+patterns come before general ones and no span is ever rewritten twice. The order is
+`secret_field_name` first, then rules 1-10 in the order above — the table is
+numbered to match the spec, not the evaluation sequence.
+
+Rule 11 going first is deliberate: a field literally named `password` or
+`authorization` holds a credential in its entirety, so redacting the whole value
+beats redacting the one recognisable substring inside it. The only cost is
+reporting granularity — a Slack token in a field named `token` is reported once as
+`secret_field_name` rather than as `slack_token`.
+
+**Rule 11 is an addition beyond the ten text patterns**, and the only rule that
+looks at where a string lives rather than at the string itself. An
+`Authorization: Opaque a7f3c9e1d5b28046` value, or a nested
+`env: { API_KEY: "9c8b7a…" }`, has no recognisable shape — an opaque credential
+looks like nothing — so no text pattern can catch it. Field names that trigger it
+are listed in `SECRET_FIELD_NAMES` in `src/redact.ts`; delete that set and the
+rule id to remove the behaviour.
+
+**`bearer_token` matches capital-B `Bearer` only**, as specified. RFC 7235 says the
+scheme is case-insensitive, so a lowercase `bearer <opaque-value>` would be missed
+by this rule; a JWT after it is still caught by rule 7, which runs earlier.
+
+**The word "token" in prose is not a secret.** Rule 10 requires a `:` or `=` after
+the name, so "Token usage is high" is untouched. There is a test for exactly that.
+
+### What the report does NOT contain
+
+`last-share.json` holds the sanitized trace plus a `redaction` report. For every
+match it records the id, rule, field path, offsets, replacement, whether it was
+redacted, and the original's LENGTH — but **not the original text**. A report that
+recorded every original would hand back every secret in the same file that just
+removed them. A short `keptPreview` survives only for matches you chose to keep,
+where the text is in the trace anyway.
+
+## The review page
+
+One HTML document. Inline CSS, ~25 lines of inline JS, no CDN, no fonts, no
+`<link>`, no `<iframe>`, served with `Content-Security-Policy: default-src 'none'`.
+An offline machine can run the whole review.
+
+- **Top:** title, model, step / tool-call / file / error counts, duration, and the
+  number of matches.
+- **Main:** a `trace` block (title, summary, cwd, sourcePath) then every step, with
+  each matched span marked. The mark shows the replacement token by default and
+  the original when you tick KEEP.
+- **Side:** every match with a rule label, a preview of the original capped at 24
+  characters, and the field path. `redact all` / `keep all` buttons, the visibility
+  radio, and Confirm / Cancel.
+
+The page shows unredacted secrets when you tick KEEP, by design — you cannot
+review what you cannot see. That is why it binds `127.0.0.1` only and is never
+written to disk.
+
+**The submitted checkbox means KEEP, not redact.** HTML only submits ticked boxes,
+so a value lost in the browser has to mean "redact it". The sidebar still reads
+"redact, on by default" via CSS, but the transport fails closed.
+
+## Verify the share path
+
+```bash
+npm run verify   # includes the redaction / review / share suites
+
+# non-interactive, writes a draft with everything redacted
+npx tsx packages/cli/src/index.ts share --file packages/cli/test/fixtures/secrets-sample.jsonl --no-review
+
+# the real thing
+npx tsx packages/cli/src/index.ts share --file packages/cli/test/fixtures/secrets-sample.jsonl
+```
+
+`test/fixtures/secrets-sample.jsonl` carries one of every class: an AWS key id, an
+Anthropic key, a GitHub token, a Slack token, a JWT in a Bearer header, a PEM
+private key, `password=` on one line, Windows and Linux home paths, opaque values
+in credential-named fields, and the prose "Token usage is high" that must survive.
+It contains no real secret.