# Mercury Toolbox V2 Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Rebrand the repository as Mercury Toolbox, add four new high-leverage CLI commands, and ship a first-class Windows installer that puts the full toolbox on PATH.

**Architecture:** Keep the toolbox as a Rust workspace of independent binaries with a shared CLI contract in `crates/common`. Add the new commands as focused crates with heuristic parsers and stable JSON payloads, and implement installation through PowerShell scripts that build and copy the binaries into a dedicated Mercury Toolbox bin directory.

**Tech Stack:** Rust stable, `lexopt`-style manual CLI parsing, shared `common` crate, `regex`, `serde_json`, PowerShell install scripts, `assert_cmd`, `predicates`, `tempfile`, and the existing Jade verification scripts.

---

### Task 1: Branding And Install Surface

**Files:**
- Create: `docs/superpowers/specs/2026-04-21-mercury-toolbox-v2-design.md`
- Create: `docs/superpowers/plans/2026-04-21-mercury-toolbox-v2-plan.md`
- Modify: `Cargo.toml`
- Modify: `README.md`
- Modify: `docs/jade-discipline.md`
- Create: `scripts/install-toolbox.ps1`
- Create: `scripts/uninstall-toolbox.ps1`

- [ ] Record the Mercury Toolbox design and plan docs in the repo.
- [ ] Rename top-level product-facing descriptions and README text from generic toolbox wording to `Mercury Toolbox` / `水星工具箱`.
- [ ] Add an install section to the README covering:
  - `pwsh .\scripts\install-toolbox.ps1`
  - install root
  - PATH behavior
  - uninstall path
  - manual `cargo install --path` fallback
- [ ] Write `scripts/install-toolbox.ps1` with idempotent bin copy and user PATH update behavior.
- [ ] Write `scripts/uninstall-toolbox.ps1` with idempotent uninstall and PATH removal behavior.
- [ ] Add focused script tests or temp-root verification coverage where practical.

### Task 2: Workspace Wiring For New Commands

**Files:**
- Modify: `Cargo.toml`
- Modify: `README.md`
- Create: `fixtures/hits/rg-output.txt`
- Create: `fixtures/diag/rust-errors.txt`
- Create: `fixtures/diag/unity-errors.txt`
- Create: `fixtures/logs/repetitive.log`
- Create: `fixtures/binaries/stringscan-sample.bin`
- Create: `crates/hitsnip/Cargo.toml`
- Create: `crates/hitsnip/src/main.rs`
- Create: `crates/hitsnip/src/lib.rs`
- Create: `crates/diagpick/Cargo.toml`
- Create: `crates/diagpick/src/main.rs`
- Create: `crates/diagpick/src/lib.rs`
- Create: `crates/logshape/Cargo.toml`
- Create: `crates/logshape/src/main.rs`
- Create: `crates/logshape/src/lib.rs`
- Create: `crates/stringscan/Cargo.toml`
- Create: `crates/stringscan/src/main.rs`
- Create: `crates/stringscan/src/lib.rs`

- [ ] Register the four new crates in the workspace member list.
- [ ] Add any workspace dependencies required by the new crates.
- [ ] Add fixture files with stable, portable sample content for all four commands.
- [ ] Add README command inventory entries for `hitsnip`, `diagpick`, `logshape`, and `stringscan`.

### Task 3: `hitsnip`

**Files:**
- Create: `crates/hitsnip/Cargo.toml`
- Create: `crates/hitsnip/src/lib.rs`
- Create: `crates/hitsnip/src/main.rs`
- Create: `crates/hitsnip/tests/hitsnip_cli.rs`
- Use: `fixtures/hits/rg-output.txt`
- Use: `fixtures/reading/sample.rs`

- [ ] Write failing tests for:
  - `rg -n` line parsing
  - merged context windows
  - JSON output shape
  - PowerShell pipeline usage
  - `--help`
- [ ] Run `cargo nextest run -p hitsnip` and confirm the new tests fail for the expected missing behavior.
- [ ] Implement hit parsing that correctly handles Windows drive prefixes and `path:line[:column]` shapes.
- [ ] Implement per-file hit grouping, context expansion, max-gap merging, and compact numbered rendering.
- [ ] Re-run `cargo nextest run -p hitsnip` until green.

### Task 4: `diagpick`

**Files:**
- Create: `crates/diagpick/Cargo.toml`
- Create: `crates/diagpick/src/lib.rs`
- Create: `crates/diagpick/src/main.rs`
- Create: `crates/diagpick/tests/diagpick_cli.rs`
- Use: `fixtures/diag/rust-errors.txt`
- Use: `fixtures/diag/unity-errors.txt`
- Use: `fixtures/reading/sample.rs`
- Use: `fixtures/reading/sample.cs`

- [ ] Write failing tests for:
  - Rust diagnostic extraction
  - Unity/C# diagnostic extraction
  - severity filtering
  - `--with-source`
  - JSON output shape
  - `--help`
- [ ] Run `cargo nextest run -p diagpick` and confirm failure.
- [ ] Implement heuristic text parsers for the supported diagnostic families plus JSONL input support.
- [ ] Implement optional source loading with context lines and safe missing-file handling.
- [ ] Re-run `cargo nextest run -p diagpick` until green.

### Task 5: `logshape`

**Files:**
- Create: `crates/logshape/Cargo.toml`
- Create: `crates/logshape/src/lib.rs`
- Create: `crates/logshape/src/main.rs`
- Create: `crates/logshape/tests/logshape_cli.rs`
- Use: `fixtures/logs/repetitive.log`

- [ ] Write failing tests for:
  - normalization of volatile fields
  - grouping repeated templates
  - `--top` and `--min-count`
  - JSON output shape
  - PowerShell pipeline usage
  - `--help`
- [ ] Run `cargo nextest run -p logshape` and confirm failure.
- [ ] Implement conservative normalization and frequency grouping logic.
- [ ] Implement compact text summaries plus JSON records with count and sample metadata.
- [ ] Re-run `cargo nextest run -p logshape` until green.

### Task 6: `stringscan`

**Files:**
- Create: `crates/stringscan/Cargo.toml`
- Create: `crates/stringscan/src/lib.rs`
- Create: `crates/stringscan/src/main.rs`
- Create: `crates/stringscan/tests/stringscan_cli.rs`
- Use: `fixtures/binaries/stringscan-sample.bin`

- [ ] Write failing tests for:
  - printable string extraction
  - category detection for URL, DLL, namespace, Unity, IL2CPP, and BepInEx-like strings
  - summary mode vs detail mode
  - JSON output shape
  - PowerShell path pipeline
  - `--help`
- [ ] Run `cargo nextest run -p stringscan` and confirm failure.
- [ ] Implement printable-string scanning and category classification helpers.
- [ ] Implement summary output, filtered detail output, and JSON payloads.
- [ ] Re-run `cargo nextest run -p stringscan` until green.

### Task 7: Full Documentation And Install Verification

**Files:**
- Modify: `README.md`
- Modify: command `after_help` sections in the four new crates
- Modify: install/uninstall scripts as needed by verification

- [ ] Ensure every new command has PowerShell examples in README and `--help`.
- [ ] Verify the install script copies all toolbox commands, not just the new ones.
- [ ] Verify PATH update behavior against an isolated temp install root when possible.
- [ ] Verify uninstall removes the Mercury Toolbox bin path entry without touching unrelated PATH content.

### Task 8: Final Verification

**Files:**
- Modify only as required by verification failures

- [ ] Run `cargo fmt --all`.
- [ ] Run `cargo nextest run --all-targets --all-features`.
- [ ] Run `cargo clippy --all-targets --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery`.
- [ ] Run `pwsh -NoProfile -File .\scripts\check-jade.ps1`.
- [ ] Fix any regressions and repeat until the full workspace passes.