MercuryToolbox/docs/superpowers/specs/2026-04-21-toolbox-v1-5-design.md

Toolbox V1.5 Design

Goal

Promote the existing four commands from "usable prototypes" to daily-driver tools by pairing feature upgrades with first-class help and documentation, and add a production-grade binmeta command for fast binary triage in AI-heavy terminal workflows.

Scope

• Upgrade jsonlgrep with nested field paths and negative field predicates.
• Upgrade recent with regex-based name filtering.
• Upgrade pathshadow with clearer shadowing explanations in text and JSON output.
• Upgrade portping with selectable HTTP method and expected status checks.
• Add concrete examples to --help output for all commands.
• Update README.md with scenario-driven examples and PowerShell pipeline usage.
• Add binmeta as a new CLI command for binary metadata inspection on Windows PE files, with graceful handling for non-PE files.

Non-Goals

• No GUI or TUI work.
• No installer, release automation, or Scoop packaging in this iteration.
• No multi-format binary analysis beyond production-grade PE support plus safe fallback summaries for unknown formats.

Command Changes

jsonlgrep

• Extend query syntax to support field!=value and field!~=regex.
• Resolve dotted field paths such as event.user.name.
• Treat scalar JSON values consistently so exact matches and text projections also work for numbers, booleans, and null.
• Improve --help with copy-pasteable file and pipeline examples.

recent

• Add --name <REGEX> to filter by file or directory basename.
• Preserve .gitignore-aware traversal and current sorting behavior.
• Improve --help with examples for recent Rust work, recent directories, and JSON pipeline usage.

pathshadow

• Append stable explanation fields to JSON output so scripts and AI can tell why an entry won or lost.
• Include PATH rank and winner path context where applicable.
• Keep text output compact but clearer about origin and shadowing reason.
• Improve --help with explicit PATH diagnosis examples.

portping

• Add --method GET|HEAD for HTTP(S) requests.
• Add --expect-status to turn mismatched HTTP status codes into probe failure while keeping actual status visible.
• Preserve TCP behavior unchanged.
• Improve --help with health-check and HEAD examples.

binmeta

• Input: one or more file paths from argv or stdin lines.
• Text output: one concise summary line per file for human scanning.
• JSON output: one object per file with stable fields for automation and AI use.
• PE analysis:
  • file kind, machine/architecture, subsystem, executable vs DLL hint, PE timestamp
  • section summaries
  • imported DLLs and imported symbol count summary
  • exported symbol count summary when available
  • SHA-256, file size, modified time
  • heuristic hints for .NET, Unity, IL2CPP, Mono, and BepInEx-related artifacts
• Non-PE fallback:
  • still emit hash, size, modified time, file extension, and "not_pe" kind without failing the whole command

Testing Strategy

• Add focused unit tests for new parsing helpers and negative query logic.
• Expand integration tests to cover help examples and new CLI flags.
• Add binmeta integration tests against:
  • a known text fixture for non-PE fallback
  • compiled workspace binaries for PE parsing
• Keep the existing Jade verification gate unchanged.

Risks

• PE parsing APIs can be noisy; the implementation should wrap parser details behind small helpers.
• binmeta hints must remain heuristic and clearly labeled as hints, not definitive claims.
• Help text examples must stay in sync with actual behavior, so tests should assert representative help fragments.