330 lines
10 KiB
Markdown
330 lines
10 KiB
Markdown
# Mercury Toolbox V2 Design
|
|
|
|
## Goal
|
|
|
|
Promote the repository from a generic AI-friendly CLI toolbox into the formally named `Mercury Toolbox` / `水星工具箱`, add four new high-leverage commands for search-to-context, diagnostics, log reduction, and binary string triage, and ship a first-class Windows + PowerShell installation path that automatically places the toolbox on the user PATH.
|
|
|
|
## Scope
|
|
|
|
- Rename the toolbox brand in repository-level docs, workspace metadata, install-facing text, and user help from the generic placeholder wording to `Mercury Toolbox` / `水星工具箱`.
|
|
- Add four new commands:
|
|
- `hitsnip`
|
|
- `diagpick`
|
|
- `logshape`
|
|
- `stringscan`
|
|
- Keep natural binary names such as `snip`, `outline`, `hitsnip`, and `diagpick`; do not introduce a global binary prefix.
|
|
- Add a user-facing PowerShell installer that:
|
|
- builds the workspace release binaries
|
|
- installs all toolbox binaries into `$env:LOCALAPPDATA\MercuryToolbox\bin`
|
|
- automatically adds that directory to the user PATH if missing
|
|
- reports what changed and how to verify the install
|
|
- Add a complementary uninstall path and installation documentation.
|
|
- Preserve the shared CLI contract:
|
|
- compact ASCII text output by default
|
|
- `--json` for machine consumption
|
|
- PowerShell-friendly stdin behavior
|
|
- stable exit code mapping
|
|
|
|
## Non-Goals
|
|
|
|
- No GUI, TUI, or long-running background service.
|
|
- No package publishing, Scoop bucket, installer EXE, or code signing in this iteration.
|
|
- No heavyweight parser stack such as tree-sitter, Roslyn, or full symbol servers.
|
|
- No single “master” control binary; the toolbox remains a workspace of small independent commands.
|
|
|
|
## Product Direction
|
|
|
|
The existing toolbox already covers “find a file”, “probe the environment”, and “read a known target”. The new batch fills the remaining gaps that are especially painful for AI-assisted terminal workflows:
|
|
|
|
- `hitsnip` answers “I already have search hits; now give me the smallest useful context.”
|
|
- `diagpick` answers “this compiler or runtime log is noisy; show me the actionable diagnostics.”
|
|
- `logshape` answers “this log is too repetitive; summarize the patterns before I read it.”
|
|
- `stringscan` answers “this binary or generated blob is opaque; show me the strings that reveal identity, runtime, and ecosystem.”
|
|
|
|
The installation work is part of the feature set, not a side quest. A toolbox that is annoying to install has near-zero real-world value even if the commands are good.
|
|
|
|
## Branding And Naming
|
|
|
|
### Repository Name
|
|
|
|
- Primary English name: `Mercury Toolbox`
|
|
- Primary Chinese name: `水星工具箱`
|
|
- Documentation should treat these as the formal product name, not as aliases for the old placeholder wording.
|
|
|
|
### Binary Names
|
|
|
|
- Keep natural command names:
|
|
- `jsonlgrep`
|
|
- `recent`
|
|
- `pathshadow`
|
|
- `portping`
|
|
- `binmeta`
|
|
- `fileprobe`
|
|
- `outline`
|
|
- `snip`
|
|
- `chunkcat`
|
|
- `hitsnip`
|
|
- `diagpick`
|
|
- `logshape`
|
|
- `stringscan`
|
|
- Do not add `mercury-` prefixes.
|
|
- The installer owns product-level grouping; the binaries stay small and task-specific.
|
|
|
|
## Installation Design
|
|
|
|
### Main Installation Path
|
|
|
|
- Add `scripts/install-toolbox.ps1`
|
|
- Default behavior:
|
|
- verify `cargo` exists
|
|
- run `cargo build --release --workspace`
|
|
- collect all known toolbox executables from `target\release`
|
|
- create `$env:LOCALAPPDATA\MercuryToolbox\bin` if needed
|
|
- copy all toolbox executables into that directory
|
|
- inspect the user PATH
|
|
- append the install directory if missing
|
|
- print a compact summary of installed commands and PATH status
|
|
|
|
### PATH Policy
|
|
|
|
- PATH updates target the user-level environment variable, not machine-wide PATH.
|
|
- The script should avoid duplicate path entries by normalizing path comparison.
|
|
- Current-session PATH may also be patched so the commands are usable immediately after install without opening a new shell.
|
|
|
|
### Safety And UX
|
|
|
|
- Support `-NoPathUpdate` for explicit opt-out.
|
|
- Support `-InstallRoot <PATH>` for advanced/manual installs, while defaulting to `$env:LOCALAPPDATA\MercuryToolbox`.
|
|
- Support `-Configuration Debug|Release`, defaulting to `Release`.
|
|
- Text output should clearly distinguish:
|
|
- install root
|
|
- bin directory
|
|
- copied binaries
|
|
- whether PATH was already configured, updated, or skipped
|
|
|
|
### Uninstall Path
|
|
|
|
- Add `scripts/uninstall-toolbox.ps1`
|
|
- Default behavior:
|
|
- remove installed binaries from the Mercury Toolbox bin directory
|
|
- remove the Mercury Toolbox bin directory from the user PATH when present
|
|
- leave unrelated files untouched
|
|
|
|
### Fallback Installation Path
|
|
|
|
- README also documents manual per-command install via `cargo install --path crates/<command>`.
|
|
- This is a fallback path for Rust-native users, not the primary recommendation.
|
|
|
|
## Command Designs
|
|
|
|
### `hitsnip`
|
|
|
|
#### Purpose
|
|
|
|
Convert search hits into deduplicated, compact context windows so neither humans nor AI have to manually reopen each hit.
|
|
|
|
#### Inputs
|
|
|
|
- Explicit files plus line references in one of these forms:
|
|
- `path:line`
|
|
- `path:line:column`
|
|
- stdin text from tools such as `rg -n`
|
|
- JSONL hit records with at least `path` and `line`
|
|
|
|
#### Output
|
|
|
|
- Text mode:
|
|
- one header per merged snippet
|
|
- numbered lines under each snippet
|
|
- compact reason metadata such as hit count and merged line span
|
|
- JSON mode:
|
|
- one JSON array of snippet objects
|
|
- fields:
|
|
- `path`
|
|
- `start_line`
|
|
- `end_line`
|
|
- `hit_lines`
|
|
- `hit_count`
|
|
- `lines`
|
|
|
|
#### Behavior
|
|
|
|
- Merge nearby hits in the same file when the distance between hit windows is at most `--max-gap`.
|
|
- Expand each hit by `--context` lines.
|
|
- Deduplicate repeated identical hit lines.
|
|
- Ignore malformed lines with clear usage/runtime errors rather than panicking.
|
|
|
|
#### Key Flags
|
|
|
|
- `--context <N>`
|
|
- `--max-gap <N>`
|
|
- `--limit <N>`
|
|
- `--input-format auto|lines|jsonl`
|
|
- shared `--json`
|
|
|
|
### `diagpick`
|
|
|
|
#### Purpose
|
|
|
|
Extract actionable diagnostics from compiler, build, and runtime logs and optionally attach source context.
|
|
|
|
#### Inputs
|
|
|
|
- Plain text logs from stdin or files
|
|
- JSONL records with fields such as `path`, `line`, `column`, `severity`, `message`
|
|
|
|
#### Recognized Text Patterns
|
|
|
|
- Rust diagnostics:
|
|
- `error[E0425]: ...`
|
|
- `--> path:line:column`
|
|
- MSVC/C#/Unity-style:
|
|
- `path(line,column): error CSxxxx: ...`
|
|
- `path:line:column: error: ...`
|
|
- Generic runtime stack/log references where a path and line are present
|
|
|
|
#### Output
|
|
|
|
- Text mode:
|
|
- one compact record per diagnostic
|
|
- optional source snippet below when `--with-source` is enabled
|
|
- JSON mode:
|
|
- array of diagnostics with stable fields:
|
|
- `path`
|
|
- `line`
|
|
- `column`
|
|
- `severity`
|
|
- `code`
|
|
- `message`
|
|
- `source`
|
|
- `tool_hint`
|
|
|
|
#### Key Flags
|
|
|
|
- `--with-source`
|
|
- `--context <N>`
|
|
- `--limit <N>`
|
|
- `--severity error|warning|note|all`
|
|
|
|
### `logshape`
|
|
|
|
#### Purpose
|
|
|
|
Collapse repetitive logs into pattern groups before anyone spends tokens reading the raw stream.
|
|
|
|
#### Inputs
|
|
|
|
- Plain log lines from stdin or files
|
|
|
|
#### Heuristic Normalization
|
|
|
|
- Replace volatile fragments with placeholders:
|
|
- timestamps
|
|
- decimal and hex numbers
|
|
- UUID-like tokens
|
|
- long paths and addresses
|
|
- Preserve level-like prefixes such as `INFO`, `WARN`, `ERROR` when possible
|
|
|
|
#### Output
|
|
|
|
- Text mode:
|
|
- one compact line per template
|
|
- includes count and a representative sample
|
|
- JSON mode:
|
|
- array of groups with fields:
|
|
- `pattern`
|
|
- `count`
|
|
- `first_line`
|
|
- `last_line`
|
|
- `sample`
|
|
|
|
#### Key Flags
|
|
|
|
- `--top <N>`
|
|
- `--min-count <N>`
|
|
- `--show-samples`
|
|
- `--keep-level`
|
|
|
|
### `stringscan`
|
|
|
|
#### Purpose
|
|
|
|
Expose the high-signal strings inside binaries, generated files, and opaque artifacts for reverse engineering and quick triage.
|
|
|
|
#### Inputs
|
|
|
|
- One or more file paths from argv or stdin
|
|
|
|
#### Output
|
|
|
|
- Text mode:
|
|
- one compact summary line per file in summary mode
|
|
- optional per-string output when filtering by category
|
|
- JSON mode:
|
|
- per-file reports with:
|
|
- `path`
|
|
- `is_binary`
|
|
- `string_count`
|
|
- `categories`
|
|
- `matches`
|
|
|
|
#### Heuristic Categories
|
|
|
|
- `url`
|
|
- `path`
|
|
- `dll`
|
|
- `namespace`
|
|
- `unity`
|
|
- `dotnet`
|
|
- `il2cpp`
|
|
- `bepinex`
|
|
- `generic`
|
|
|
|
#### Key Flags
|
|
|
|
- `--min-len <N>`
|
|
- `--kind all|url|path|dll|namespace|unity|dotnet|il2cpp|bepinex|generic`
|
|
- `--unique`
|
|
- `--limit <N>`
|
|
- `--details`
|
|
|
|
## Shared Fixtures
|
|
|
|
Add fixtures that support these commands without introducing heavyweight dependencies:
|
|
|
|
- `fixtures/hits/rg-output.txt`
|
|
- `fixtures/diag/rust-errors.txt`
|
|
- `fixtures/diag/unity-errors.txt`
|
|
- `fixtures/logs/repetitive.log`
|
|
- `fixtures/binaries/stringscan-sample.bin`
|
|
|
|
The binary fixture should embed obvious markers such as URLs, DLL names, Unity namespace fragments, and BepInEx-like strings so category detection can be tested reliably.
|
|
|
|
## Testing Strategy
|
|
|
|
- Unit tests:
|
|
- hit parsing and merge planning for `hitsnip`
|
|
- diagnostic parsing helpers for `diagpick`
|
|
- normalization and grouping for `logshape`
|
|
- string extraction and category heuristics for `stringscan`
|
|
- installer path normalization and PATH edit helpers
|
|
- Integration tests:
|
|
- `--help` examples for all new binaries
|
|
- PowerShell pipeline flows
|
|
- JSON output shape
|
|
- install/uninstall script dry-run or temp-root behavior
|
|
- Verification gates stay under the existing Jade standard, including `check-jade.ps1`.
|
|
|
|
## Risks
|
|
|
|
- Search-hit parsing can get messy when input mixes drive-letter paths and colon-separated line syntax.
|
|
- Prefer a path-aware parser that handles Windows drive prefixes before splitting on the final line/column segments.
|
|
- Diagnostic parsers can drift when tools change exact wording.
|
|
- Keep the patterns heuristic and additive rather than pretending to be a full parser for each toolchain.
|
|
- Over-normalizing logs can merge meaningfully different failures.
|
|
- Keep the normalization rule set conservative in v1.
|
|
- Binary string scanning can explode in output volume.
|
|
- Default to concise summaries and require explicit detail flags for large per-string dumps.
|
|
- PATH editing is user-hostile if it duplicates entries or stomps unrelated content.
|
|
- Use minimal, append-only edits with idempotent detection.
|