flatbread-cli 0.1.0 → 0.3.0

package/README.md

@@ -10,8 +10,7 @@ npm install -g flatbread-cli          # installs the `flatbread` command (Node 2
 npx -y flatbread-cli --help           # or run it without installing
 ```
 
-**Not on npm until the owner runs the first `npm publish`** - until then, `npm pack` (below) and
-`npm install -g ./flatbread-cli-<version>.tgz`. **The npm package is `flatbread-cli`, not `flatbread`.** `flatbread` on npm is an unrelated
+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
@@ -123,8 +122,12 @@ Visibility is `private` unless a human raises it - in the review UI, or from the
 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 `packages/cli/.tmp/last-parse.json`.
-`share` writes `packages/cli/.tmp/last-share.json` and refreshes `last-parse.json`.
+`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**
@@ -136,9 +139,49 @@ capsule quotes trace text verbatim and inherits whatever the source still contai
 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 also registers the MCP server at Claude Code's user scope (`mcpServers.flatbread` in
+`~/.claude.json`, or `$CLAUDE_CONFIG_DIR/.claude.json`), so every project has it and none asks you
+to approve a `.mcp.json`. Only that one entry is touched: a file that is not JSON is refused, a
+server named `flatbread` that runs something else is left alone, the file's BOM, line endings and
+mode are kept, and the first write leaves `~/.claude.json.flatbread.bak`. Restart Claude Code (or
+reload the VS Code window) afterwards. `--no-mcp` skips it.
+
+`setup --dry-run` writes nothing. `setup --uninstall` removes the handlers, the MCP entry 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`.
+a private run's share link (`?t=`) is sent as a header, never in a URL. `pull <id>` reads a run
+this machine shared or captured from disk, so it works offline; anything else comes from the site.
+Without `setup`, add the MCP server by hand: `claude mcp add --scope user flatbread -- flatbread mcp`.
+
+`share` writes the reviewed draft to `last-share.json`, which the next share replaces. The run is
+not lost with it: every share is also kept under its own ID, which `search --local` lists and
+`pull <id>` prints. The review page listens on 127.0.0.1, on 4321-4325, or a port the OS picks
+when all five are busy.
 
 ### Building the package
 

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,31 @@
+# Third-party notices
+
+## deja-vu
+
+`src/adapters/antigravity.ts` reads conversations the way deja-vu reads Windsurf trajectories
+(`internal/sources/windsurf.go`), and `test/fixtures/antigravity/*.pb` are its fixtures
+(`fixtures/registry/windsurf/cascade/`).
+
+```
+MIT License
+
+Copyright (c) 2026 Vladislav Shulcz
+
+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.
+```