MercuryToolbox/docs/superpowers/plans/2026-04-21-toolbox-v1-5-plan.md

Toolbox V1.5 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: Upgrade the existing four toolbox commands with better UX and capability, then add a production-grade binmeta binary metadata inspector.

Architecture: Keep the workspace shape flat and consistent: each command remains its own crate, shared behavior stays in common, and every new behavior is covered by command-local tests plus workspace verification. binmeta will follow the same input/output contract as the existing tools and keep format-specific parsing behind focused helpers.

Tech Stack: Rust stable, lexopt-style manual CLI parsing, shared common crate, targeted parsing crates for PE inspection, workspace tests via assert_cmd.

---

Task 1: Design And Manifest Wiring

Files:

• Create: docs/superpowers/specs/2026-04-21-toolbox-v1-5-design.md

• Create: docs/superpowers/plans/2026-04-21-toolbox-v1-5-plan.md

• Modify: Cargo.toml

• Modify: README.md

• Record the approved v1.5 scope in repo docs.

• Add any new workspace dependencies needed for binmeta.

• Register crates/binmeta in the workspace.

• Update README command inventory and usage examples.

Task 2: jsonlgrep Upgrade

Files:

• Modify: crates/jsonlgrep/src/lib.rs

• Modify: crates/jsonlgrep/tests/query_and_cli.rs

• Write failing tests for dotted field paths, !=, and !~= queries.

• Run targeted jsonlgrep tests and confirm the new cases fail for the right reason.

• Implement nested path resolution and negative predicate parsing/matching with minimal code changes.

• Add after_help examples and test representative help output.

• Re-run targeted jsonlgrep tests until green.

Task 3: recent Upgrade

Files:

• Modify: crates/recent/src/lib.rs

• Modify: crates/recent/tests/recent_cli.rs

• Write failing tests for --name regex filtering and help output examples.

• Run targeted recent tests and confirm failure.

• Implement basename regex filtering and help text polish.

• Re-run targeted recent tests until green.

Task 4: pathshadow Upgrade

Files:

• Modify: crates/pathshadow/src/lib.rs

• Modify: crates/pathshadow/tests/pathshadow_cli.rs

• Write failing tests for explanation/rank fields and help examples.

• Run targeted pathshadow tests and confirm failure.

• Implement richer JSON/text explanation output while preserving existing contract fields.

• Re-run targeted pathshadow tests until green.

Task 5: portping Upgrade

Files:

• Modify: crates/portping/src/lib.rs

• Modify: crates/portping/src/main.rs

• Modify: crates/portping/tests/portping_cli.rs

• Write failing tests for --method, --expect-status, and help examples.

• Run targeted portping tests and confirm failure.

• Implement request method selection and explicit status expectation handling.

• Re-run targeted portping tests until green.

Task 6: binmeta Command

Files:

• Create: crates/binmeta/Cargo.toml

• Create: crates/binmeta/src/lib.rs

• Create: crates/binmeta/src/main.rs

• Create: crates/binmeta/tests/binmeta_cli.rs

• Create: fixtures/binmeta/plain.txt

• Write failing tests for non-PE fallback, PE metadata extraction against a compiled workspace binary, JSON output, and help examples.

• Run targeted binmeta tests and confirm failure.

• Implement stdin/path loading, metadata hashing, PE parsing, heuristic hints, and text/JSON rendering.

• Re-run targeted binmeta tests until green.

Task 7: Full 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 all commands pass.