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