Merge pull request #7 from digitaldrreamer/claude/cli-ux

feat(cli): AI-client summary report + sweep + interactive UX (v0.2.0)

Author: digitaldrreamer

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] — 2026-07-02
+
+### Added
+- `broom sweep` — redact in place, equivalent to `clean --apply` (both work).
+- Interactive menu when `broom` is run with no arguments on a terminal, and a
+  confirmation prompt before `sweep`/`clean --apply` (skipped with `--yes` and
+  in non-interactive/CI use). Built on `node:readline/promises` — still zero
+  runtime dependencies.
+- `--verbose` flag: the default report is now a compact summary; `--verbose`
+  lists every occurrence with rule and line number.
+- "Did you mean …?" suggestion for unknown commands.
+
+### Changed
+- Report redesigned. Instead of one line per finding (thousands of lines on a
+  busy history), the default groups by **AI client** and shows vulnerable chats
+  and the count of **distinct** secrets, deduped by value — the same credential
+  echoed many times counts once (the raw occurrence count is shown alongside).
+- Colour output now respects `NO_COLOR` / `FORCE_COLOR` and TTY detection.
+
 ## [0.1.1] — 2026-07-02
 
 ### Fixed
@@ -45,5 +64,6 @@ First public release.
 - Extended-thinking blocks are passed through the proxy unredacted to preserve
   their signatures — see the README Limitations section.
 
+[0.2.0]: https://github.com/digitaldrreamer/broomsticks/releases/tag/v0.2.0
 [0.1.1]: https://github.com/digitaldrreamer/broomsticks/releases/tag/v0.1.1
 [0.1.0]: https://github.com/digitaldrreamer/broomsticks/releases/tag/v0.1.0

README.md

@@ -14,11 +14,13 @@ broomsticks does two things: it **cleans** secrets already sitting in your local
 # scan every transcript for secrets (read-only)
 npx broomsticks scan
 
-# preview redactions, then apply them (each touched file is backed up first)
+# preview redactions, then sweep them away (each touched file is backed up first)
 npx broomsticks clean
-npx broomsticks clean --apply
+npx broomsticks sweep
 ```
 
+Run `broom` with no arguments in a terminal for an interactive menu.
+
 Prefer a global command? `npm install -g broomsticks` gives you `broom` (used throughout this README). Requires **Node ≥ 22.13** — it reads Cursor's SQLite store with the built-in `node:sqlite`, unflagged as of 22.13.0, so there are no native modules to build.
 
 ## What it does
@@ -41,15 +43,20 @@ broom scan                              # report secrets; exits 1 if any (CI-fri
 broom scan --source cursor              # limit to one source (repeatable)
 broom sources                           # list discovered transcript files
 broom clean                             # preview redactions (dry-run)
-broom clean --apply                     # redact in place, backing up first
+broom sweep                             # redact in place, backing up first (= clean --apply)
+broom scan --verbose                    # list every finding, not just per-file counts
 broom scan --json                       # machine-readable output
-broom clean --apply --extra ./leaked.txt   # also scrub your own known values
+broom sweep --extra ./leaked.txt        # also scrub your own known values
 ```
 
+By default the report is a compact summary — grouped by AI client, showing how many chats are affected and how many **distinct** secrets are exposed (the same key echoed many times across a transcript counts once; the total occurrence count is shown alongside). Add `--verbose` to list every occurrence with its rule and line. Colour is used on a terminal and disabled automatically when piped or when `NO_COLOR` is set. `sweep` (and `clean --apply`) asks for confirmation on a terminal; pass `--yes` to skip it, and in a pipe/CI it proceeds without prompting.
+
 | Flag | Meaning |
 | --- | --- |
 | `--source <id>` | Restrict to `claude-code`, `codex`, or `cursor` (repeatable; default: all) |
-| `--apply` | Perform redaction (`clean` only; otherwise dry-run) |
+| `--apply` | Perform redaction (`clean` only; `sweep` implies it) |
+| `--yes` | Skip the pre-redaction confirmation prompt |
+| `--verbose` | List every finding, not just per-file counts |
 | `--backup-dir <dir>` | Where backups go (default `~/.broom/backups/<timestamp>/`) |
 | `--no-backup` | Skip backups (discouraged) |
 | `--extra <file>` | Extra literal / `/regex/` secrets to redact, one per line |

bin/broom.mjs

@@ -17,6 +17,7 @@ import { discoverTargets as codexTargets }      from '../src/sources/codex.mjs'
 import { discoverTargets as cursorTargets }     from '../src/sources/cursor.mjs'
 import { runInstall, isInstalled }              from '../src/install.mjs'
 import { startProxy, installProxyEnv, uninstallProxyEnv, installDaemon, uninstallDaemon } from '../src/proxy.mjs'
+import { confirm, select, isInteractive, closest } from '../src/ui.mjs'
 
 // ── Package metadata ──────────────────────────────────────────────────────────
 const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
@@ -44,11 +45,30 @@ function options(name) {
 
 // ── Top-level flags ───────────────────────────────────────────────────────────
 if (flag('--version') || flag('-v')) { console.log(pkg.version); process.exit(0) }
-if (flag('--help')    || flag('-h') || argv.length === 0) { printHelp(); process.exit(0) }
+if (flag('--help')    || flag('-h')) { printHelp(); process.exit(0) }
+
+const COMMANDS = ['scan', 'clean', 'sweep', 'sources', 'install', 'proxy']
+
+let command = argv[0]
+
+// No command: offer an interactive menu on a TTY, otherwise print help.
+if (!command) {
+  if (isInteractive()) {
+    command = await select('\n  What would you like to do?', [
+      { label: 'scan    — find secrets (read-only)',           value: 'scan'    },
+      { label: 'clean   — preview redactions (dry-run)',       value: 'clean'   },
+      { label: 'sweep   — redact secrets in place (backs up)', value: 'sweep'   },
+      { label: 'sources — list discovered transcript files',   value: 'sources' },
+    ])
+    if (!command) { console.log('\n  Nothing to do.\n'); process.exit(0) }
+  } else {
+    printHelp(); process.exit(0)
+  }
+}
 
-const command = argv[0]
-if (!['scan', 'clean', 'sources', 'install', 'proxy'].includes(command)) {
-  console.error(`broom: unknown command '${command}'. Try 'broom --help'.`)
+if (!COMMANDS.includes(command)) {
+  const hint = closest(command, COMMANDS)
+  console.error(`broom: unknown command '${command}'.${hint ? ` Did you mean '${hint}'?` : ''} Try 'broom --help'.`)
   process.exit(1)
 }
 
@@ -156,10 +176,11 @@ const extraFile    = option('--extra')
 const allowFile    = option('--allowlist')
 const jsonOut      = flag('--json')
 const noFail       = flag('--no-fail')
-const apply        = flag('--apply')
+const apply        = flag('--apply') || command === 'sweep'   // `sweep` = clean --apply
 const backupDir    = option('--backup-dir')
 const noBackup     = flag('--no-backup')
 const noAllowlist  = flag('--no-allowlist')
+const verbose      = flag('--verbose')
 
 // ── Load extra secrets from --extra file ──────────────────────────────────────
 let extras = []
@@ -207,7 +228,19 @@ if (targets.length === 0) {
   process.exit(noFail ? 0 : 1)
 }
 
-const isClean   = command === 'clean'
+const isClean   = command === 'clean' || command === 'sweep'
+
+// Confirm before writing, but only when interactive and not forced with --yes.
+// Non-interactive (pipes, CI) proceeds silently — running `sweep`/`--apply`
+// there is itself the consent.
+if (apply && !flag('--yes') && isInteractive()) {
+  const ok = await confirm(
+    `\n  Redact secrets in place across ${targets.length} discovered file(s)? Originals are backed up first.`,
+    false,
+  )
+  if (!ok) { console.log('\n  Aborted — nothing was written.\n'); process.exit(0) }
+}
+
 const backup    = (!noBackup && apply) ? new BackupSession(backupDir) : null
 
 const scanResults = []
@@ -251,7 +284,7 @@ if (backup) backup.writeManifest(scanResults)
 if (jsonOut) {
   printJsonReport(scanResults)
 } else {
-  printReport(scanResults, { clean: isClean, apply })
+  printReport(scanResults, { clean: isClean, apply, verbose })
 }
 
 const totalFindings = scanResults.reduce((n, r) => n + r.findings.length, 0)
@@ -279,8 +312,10 @@ function printHelp() {
 broomsticks v${pkg.version} — sweep secrets out of AI coding-assistant transcripts
 
 USAGE
+  broom                           interactive menu (on a terminal)
   broom scan   [options]          find secrets (read-only, exits 1 if found)
   broom clean  [options]          preview redactions (dry-run by default)
+  broom sweep  [options]          redact in place — backs up first (= clean --apply)
   broom clean  --apply [options]  redact in place — backs up first
   broom sources                   list discovered transcript files
   broom install                   install Claude Code skill + Stop hook
@@ -301,6 +336,7 @@ OPTIONS
   --allowlist <file>  Custom allowlist file (default: ~/.broom/allowlist.txt)
   --no-allowlist      Disable allowlist suppression (report all findings)
   --json              Machine-readable JSON output
+  --verbose           List every finding, not just per-file counts
   --no-fail           Exit 0 even when secrets are found (CI override)
   --port <n>          Proxy port (default: 7777)
   --verbose           Log redaction counts to stderr (proxy only)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "broomsticks",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Sweep leaked secrets out of your AI coding-assistant chat transcripts (Claude Code, Codex, Cursor). Dry-run by default, backups before every write, zero runtime dependencies.",
   "type": "module",
   "bin": {