# 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.