Crockan/MercuryToolbox
1
0
Fork 1
Code Issues Pull Requests Releases 1 Wiki Activity
Files
e365e5df4d503dafa7019ef5e86cc1317b4b395f
MercuryToolbox/docs/superpowers/plans/2026-04-21-mercury-toolbox-v2-plan.md
T

7.2 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink