brainblast 0.4.0 → 0.4.2

package/README.md

@@ -11,10 +11,70 @@ parses your code statically and runs offline.
 npx brainblast .            # scan the repo, write .agent-research/report.json
 npx brainblast . --ci       # exit 1 if a confirmed FAIL remains
 npx brainblast . --ci --strict   # also fail on CANT_TELL (can't statically prove)
+npx brainblast . --since origin/main   # diff-aware: only audit what changed
+npx brainblast fix .                   # dry run: list mechanical fixes
+npx brainblast fix . --apply           # write fixes, re-audit RED -> GREEN
 ```
 
 Exit codes: **0** clean · **1** a confirmed FAIL · CANT_TELL is a warning by
-default (a red build always means a real, confirmed problem).
+default (a red build always means a real, confirmed problem). `2` means
+`--since <ref>` could not run `git diff` (bad ref, or not a git work tree).
+
+### Diff-aware scanning (`--since <ref>`)
+
+`--since <ref>` audits only what's changed relative to `<ref>` (any git
+revision: a branch, `HEAD~1`, a commit SHA): TS/Rust functions whose line
+range overlaps `git diff <ref>`, and config/env files that changed at all.
+This makes brainblast fast enough to run on every commit or PR instead of a
+full-repo scan:
+
+```sh
+npx brainblast . --since origin/main   # CI: only the PR's diff
+npx brainblast . --since HEAD          # pre-commit/save hook: working tree changes
+```
+
+Living-memory precedents (see below) are still looked up and shown in
+`--since` mode, but the memory snapshot itself is only written on full
+(non-`--since`) runs — a partial diff-scan never overwrites the full picture.
+
+### Watch mode (`brainblast watch`)
+
+```sh
+npx brainblast watch .
+```
+
+Runs as a daemon: every time a file is saved, brainblast re-scans only the
+working-tree changes (uncommitted edits vs `HEAD`, plus untracked files —
+the "what did I just save?" view) and emits one **NDJSON event per line** on
+stdout:
+
+```json
+{"type":"watch_started","targetDir":"."}
+{"type":"finding","ruleId":"stripe-webhook-raw-body-verification","severity":"critical","result":"fail","file":"src/webhook.ts","line":3,"detail":"...","fix":{...}}
+{"type":"scan_complete","filesChanged":1,"findings":1,"durationMs":62}
+```
+
+Event types: `watch_started`, `finding` (one per FAIL/CANT_TELL), `scan_complete`
+(per debounced save, even if nothing changed), and `scan_error` (e.g. not a
+git work tree). This is the integration point for an agent daemon — tail
+stdout for structured findings instead of polling `.agent-research/report.json`.
+Exit with Ctrl-C / SIGTERM.
+
+### Auto-fix (`brainblast fix`)
+
+```sh
+npx brainblast fix .            # dry run: list available mechanical fixes
+npx brainblast fix . --apply    # write each fix.diff to disk, then re-audit
+npx brainblast fix . --apply --branch   # also commit to brainblast/auto-fix-<ts>
+```
+
+Every confirmed FAIL that ships a mechanical `fix.diff` (e.g. Stripe raw-body,
+Privy `audience`/`issuer`) can be applied directly. `--apply` writes each diff,
+then re-runs the audit to confirm the finding now passes (RED -> GREEN) — any
+fix that doesn't take is reported, not silently dropped. Findings with only a
+`suggestion` (structural fixes brainblast won't auto-synthesize) are listed as
+guidance, not applied. `--branch` additionally creates a new branch and commits
+the applied changes.
 
 ## What it catches
 
@@ -34,6 +94,13 @@ default (a red build always means a real, confirmed problem).
 | `metaplex-metadata-immutable` | `createV1` / `createNft` omits `isMutable: false` | Metadata defaults to mutable; any update authority can change the token's name, image, or attributes after launch |
 | `anchor-init-if-needed-guarded` | Anchor instruction uses `init_if_needed` without a re-initialization guard | Any user can reinitialize another user's account, overwriting its state |
 
+### Config / env
+
+| Rule | What's wrong | Consequence |
+|------|--------------|-------------|
+| `env-secrets-committed` | A `.env*` file (not `.env.example`/`.sample`/`.template`) is tracked by git and contains a secret-shaped key (`SECRET`, `*_PRIVATE_KEY`, `*_API_KEY`, `*_TOKEN`, `*_PASSWORD`, etc.) with a real-looking (non-placeholder) value | Anyone with read access to the repo — including forks of a public repo — can read the live credential |
+| `env-secret-leaked-to-sink` | A secret-shaped `process.env.X` value (directly, via a local variable, or one hop through a same-file helper) is passed to `console.log`/`res.json`/`res.send`/etc. | Credentials end up in logs, error trackers, or API responses — readable by anyone with log/response access |
+
 Each finding lands in `.agent-research/report.json` (stable `schemaVersion: "1.0"`)
 with a `checks[]` array a CI gate can read. Each confirmed FAIL ships a
 generated behavioral test (RED on vulnerable, GREEN on fixed).
@@ -116,7 +183,7 @@ All types are exported: `Rule`, `CheckResult`, `CostReport`, `AccountFlow`,
 
 ```sh
 npm install
-npm test         # unit suite (135 tests)
+npm test         # unit suite (173 tests)
 npm run prove    # end-to-end: generated tests RED on vulnerable, GREEN on fixed
 npm run build    # produce dist/ (the published artifact)
 ```