forked from Crockan/MercuryToolbox
chore(release): prepare public source release
This commit is contained in:
MercuryToolbox Release
@@ -0,0 +1,172 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Toolbox Reading 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:** Add four new reading-oriented CLI commands that let PowerShell and AI workflows inspect files precisely without dumping whole files.
|
||||
|
||||
**Architecture:** Keep each command as its own crate in the workspace and keep language or file-type heuristics inside focused helpers rather than shared heavyweight parsers. Reuse the existing common CLI contract for stdin behavior, JSON output, and exit codes, while letting each command define small, stable domain-specific JSON payloads.
|
||||
|
||||
**Tech Stack:** Rust stable, `lexopt`-style manual CLI parsing, shared `common` crate, `regex`, `serde_json`, `toml`, `assert_cmd`, and existing workspace verification scripts.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Manifest And Documentation Wiring
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/superpowers/specs/2026-04-21-toolbox-reading-v2-design.md`
|
||||
- Create: `docs/superpowers/plans/2026-04-21-toolbox-reading-v2-plan.md`
|
||||
- Modify: `Cargo.toml`
|
||||
- Modify: `README.md`
|
||||
|
||||
- [ ] Record the reading-tool batch scope in repo docs.
|
||||
- [ ] Register `crates/snip`, `crates/outline`, `crates/fileprobe`, and `crates/chunkcat` in the workspace.
|
||||
- [ ] Add any workspace dependencies needed by the four crates.
|
||||
- [ ] Update README command inventory and usage examples.
|
||||
|
||||
### Task 2: `snip`
|
||||
|
||||
**Files:**
|
||||
- Create: `crates/snip/Cargo.toml`
|
||||
- Create: `crates/snip/src/lib.rs`
|
||||
- Create: `crates/snip/src/main.rs`
|
||||
- Create: `crates/snip/tests/snip_cli.rs`
|
||||
- Create: `fixtures/reading/sample.rs`
|
||||
- Create: `fixtures/reading/sample.cs`
|
||||
|
||||
- [ ] Write failing tests for `--lines`, `--around`, `--symbol`, and `--help`.
|
||||
- [ ] Run targeted `snip` tests and confirm failure for the new behavior.
|
||||
- [ ] Implement snippet selection, numbered text rendering, and JSON output.
|
||||
- [ ] Add heuristic symbol extraction for Rust and C# plus safe fallback behavior.
|
||||
- [ ] Re-run targeted `snip` tests until green.
|
||||
|
||||
### Task 3: `outline`
|
||||
|
||||
**Files:**
|
||||
- Create: `crates/outline/Cargo.toml`
|
||||
- Create: `crates/outline/src/lib.rs`
|
||||
- Create: `crates/outline/src/main.rs`
|
||||
- Create: `crates/outline/tests/outline_cli.rs`
|
||||
- Create: `fixtures/reading/config.json`
|
||||
- Create: `fixtures/reading/config.toml`
|
||||
- Create: `fixtures/reading/config.yaml`
|
||||
|
||||
- [ ] Write failing tests for Rust/C#/config outline extraction, JSON shape, and `--help`.
|
||||
- [ ] Run targeted `outline` tests and confirm failure.
|
||||
- [ ] Implement heuristic outline extraction and depth limiting.
|
||||
- [ ] Re-run targeted `outline` tests until green.
|
||||
|
||||
### Task 4: `fileprobe`
|
||||
|
||||
**Files:**
|
||||
- Create: `crates/fileprobe/Cargo.toml`
|
||||
- Create: `crates/fileprobe/src/lib.rs`
|
||||
- Create: `crates/fileprobe/src/main.rs`
|
||||
- Create: `crates/fileprobe/tests/fileprobe_cli.rs`
|
||||
- Create: `fixtures/reading/minified.js`
|
||||
- Create: `fixtures/reading/generated.lock`
|
||||
- Create: `fixtures/reading/binary.bin`
|
||||
|
||||
- [ ] Write failing tests for text/binary detection, heuristic flags, JSON output, and `--help`.
|
||||
- [ ] Run targeted `fileprobe` tests and confirm failure.
|
||||
- [ ] Implement lightweight probing, line stats, and file family heuristics.
|
||||
- [ ] Re-run targeted `fileprobe` tests until green.
|
||||
|
||||
### Task 5: `chunkcat`
|
||||
|
||||
**Files:**
|
||||
- Create: `crates/chunkcat/Cargo.toml`
|
||||
- Create: `crates/chunkcat/src/lib.rs`
|
||||
- Create: `crates/chunkcat/src/main.rs`
|
||||
- Create: `crates/chunkcat/tests/chunkcat_cli.rs`
|
||||
|
||||
- [ ] Write failing tests for chunk inventory, selected chunk rendering, JSON output, and `--help`.
|
||||
- [ ] Run targeted `chunkcat` tests and confirm failure.
|
||||
- [ ] Implement deterministic chunk planning and selected chunk extraction.
|
||||
- [ ] Re-run targeted `chunkcat` tests until green.
|
||||
|
||||
### Task 6: 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.
|
||||
@@ -0,0 +1,95 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user