pinai-7640/MercuryToolbox
1
0
Fork 0
forked from Crockan/MercuryToolbox
Code Pull Requests Activity
Files
main
MercuryToolbox/README.md
T

1029 lines
55 KiB
Markdown
Raw Permalink Blame History

# Mercury Toolbox / 水星工具箱
Mercury Toolbox is proprietary software. See [LICENSE](LICENSE).
Mercury Toolbox is a PowerShell-first Rust toolbox of small, focused CLI binaries for local inspection, shaping, and triage.
It is built for the kind of terminal work where you need one command to answer one concrete question quickly: what changed, what owns this port, what does this JSON look like, what symbols exist in this codebase, what imports does this PE pull in, what is inside this Unity asset, or what hash set should I emit for this release artifact.
Instead of hiding everything behind one giant control binary, Mercury keeps each capability as its own small command with a stable CLI contract, compact text output by default, and structured `--json` or `--toon` output when the next consumer is a script, another tool, or an AI model.
Quick reasons to use it:
- PowerShell-friendly by default, including stdin and pipeline behavior that stays predictable on Windows.
- AI-readable structured output through native `--json` and `--toon` modes.
- Narrow commands that are easier to remember, script, package, test, and reason about than one monolithic Swiss-army binary.
- Coverage across code reading, logs, Git/repo shape, config editing, ports/processes, .NET/Unity inspection, PE/LLVM triage, CSV/JSON/SQL shaping, and release hashing through `mhash`.
Fast starter commands:
```powershell
fileprobe <PATH>
reposhape . --json | ConvertFrom-Json
diagpick .\build.log
mhash --algorithm sha256,blake3-256 .\dist\MercuryToolbox.zip --json | ConvertFrom-Json
peimports .\target\release-fast\portping.exe --json | ConvertFrom-Json
```
Recommended first read:
- [Install](#install) if you want the toolbox on your machine now.
- [Which Tool First](#which-tool-first) if you want the shortest route to the right command.
- [Commands](#commands) if you want the full tool map.
- [docs/jade-discipline.md](docs/jade-discipline.md) if you are contributing code or changing shared contracts.
- [docs/maintainer-notes.md](docs/maintainer-notes.md) before changing shared output, JSON-family formats, codeindex-family tools, or Jade gates.
## Architecture
- `crates/common` carries the shared CLI contract, exit codes, JSON/text/TOON rendering rules, compact JSON-family format helpers, and stdin policy.
- Set `$env:MERCURY_OUTPUT='json'` or `$env:MERCURY_OUTPUT='toon'` when you want the whole toolbox to default to one structured format for an AI-heavy shell session.
- JSON-capable tools should use native `--toon` or `--format toon`; reserve the standalone `toon` binary for external JSON producers or explicit format conversion.
- `codeshape` and `defsnip` both ride on the shared `codeindex` AST engine, so their JSON now exposes `engine=codeindex`.
- Managed inspection stays split on purpose: `asmtype` finds candidate types, `asmmember` drills into members, `asmflow` handles IL and xrefs, and JSONL piping lets them hand off without copy-paste.
- Unity-focused inspection builds on shared layers instead of one-off scripts: `unityasset` covers offline assets, `unitydiag` covers logs, and `unityprobe` covers read-only runtime inspection through an explicit BepInEx bridge install.
## Modern CLI Pairing
- Mercury is meant to work with modern terminal companions, not replace them: `rg`, `fd`, `bat`, `jq`, `yq`, `sd`, `xh`, `tokei`, `eza`, `procs`, `dust`, `hyperfine`, `hexyl`, `zoxide`, `lazygit`, `delta`, `tealdeer`, and `ouch`.
- Prefer `rg` over recursive `grep` or `Select-String`, `fd` over `Get-ChildItem -Recurse`, `bat` or Mercury readers over raw `Get-Content`, `jq` or `yq` over manual JSON or YAML parsing, and `xh` over `curl` for quick HTTP checks.
- Prefer Mercury when the question is “what is the shape of this local thing?” and prefer the companion tool when the question is “which local thing should I open next?”
- `just` is the fast command hub for this repo, and `bacon` is the watch loop that keeps either workspace-wide or subsystem-scoped checks running while you keep editing.
## Which Tool First
Start from the job, not from the command name. The table below is the quick routing layer for a fresh shell or an AI agent that has not seen the artifact yet.
| Job | First command | Follow-up lane |
| --- | --- | --- |
| I have an unknown file | `fileprobe <PATH>` | `binmeta`, `stringscan`, `snip`, or `chunkcat` depending on the detected shape |
| I have a repo and need the map | `reposhape . --json` | `codeshape`, `gitshape`, `dotnetshape`, `sqlshape`, or `ctxpack` |
| I have source and need one symbol | `defsnip <SYMBOL> .` | `refs <SYMBOL> .`, then `hitsnip` or `ctxpack` for handoff |
| I have a log or build failure | `diagpick <LOG>` | `logshape`, `snip --match`, or `runprobe` for the repro command |
| I have a .NET or Unity DLL | `asmref diagnose <ASSEMBLY> --resolve-dir <DIR>` | `asmtype`, `asmmember`, `asmflow`, and `asmapi diff` |
| I have a Windows EXE or DLL | `peimports <PATH>` | `peexports`, `pecalls`, `pesig`, `pestrrefs`, `llvmreadobj`, or `llvmobjdump` |
| I have a Windows driver | `drvshape <SYS>` | `ioctlscan`, `peimports --category device_io`, `pecalls --category device_io`, and `pestrrefs` |
| I need an AI-readable handoff | Add `--json` for tooling or `--toon` for model input | Pipe external JSON through `toon` only when the producer is not already a Mercury command |
Safe starter commands are intentionally read-only:
```powershell
fileprobe <PATH>
reposhape . --json | ConvertFrom-Json
asmref diagnose <ASSEMBLY> --resolve-dir <DIR> --format toon
peimports <PATH> --json | ConvertFrom-Json
drvshape <SYS> --json | ConvertFrom-Json
```
Every command has guided triage notes in the generated AI prompt and Codex skill catalog: an answer shape, a trust basis, and likely next actions. PE deep-analysis commands additionally emit that guidance at runtime through an answer-first text header plus `report_quality` and `next_actions` in structured output. Use those fields as the first trust check before inventing an ad-hoc pipeline.
## Install
Recommended on Windows + PowerShell:
```powershell
pwsh -NoProfile -File .\scripts\install-toolbox.ps1
```
Default install behavior:
- builds all toolbox binaries in `ReleaseFast`
- stages versioned binaries under `$env:LOCALAPPDATA\MercuryToolbox\versions\...`
- updates the stable command directory at `$env:LOCALAPPDATA\MercuryToolbox\current\bin`
- refreshes the generated AI prompt and Codex skill assets
- copies docs and AI assets into `$env:LOCALAPPDATA\MercuryToolbox\share\mercury-toolbox`
- installs the generated `mercury-toolbox` Codex skill into `$env:CODEX_HOME\skills` when `CODEX_HOME` is set, otherwise into `$HOME\.codex\skills`
- adds that stable command directory to the user `PATH` when missing
- updates the installer process `PATH` and prints a reload snippet for shells launched via `pwsh -File`
- installs every toolbox command:
`cjson`, `ison`, `isonl`, `zon`, `tonl`, `jsonlgrep`, `jsonshape`, `mhash`, `recent`, `pathshadow`, `portping`, `portunlock`, `msudo`, `asmtype`, `asmmember`, `asmref`, `asmapi`, `asmflow`, `llvmobjdump`, `llvmreadobj`, `llvmnm`, `peexports`, `peimports`, `pecalls`, `pesig`, `pestrrefs`, `drvshape`, `ioctlscan`, `binmeta`, `fileprobe`, `outline`, `codeshape`, `refs`, `snip`, `defsnip`, `ctxpack`, `chunkcat`, `hitsnip`, `diagpick`, `logshape`, `stringscan`, `toon`, `csvshape`, `sqliteshape`, `sqlshape`, `unityasset`, `unityprobe`, `unitydiag`, `envdiff`, `proctree`, `sysshape`, `runprobe`, `await`, `argv`, `config`, `gitshape`, `reposhape`, `dotnetshape`, `unlock`
If you launch the installer as a child PowerShell process, reload the current shell afterward:
```powershell
$env:Path = [Environment]::GetEnvironmentVariable('Path','User') + ';' + [Environment]::GetEnvironmentVariable('Path','Machine')
```
Useful install variants:
```powershell
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -Configuration Debug
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -Configuration ReleaseSize
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -SkipSlimBinaryRebuild
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -InstallRoot C:\Tools\MercuryToolbox
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -CodexHome C:\Tools\CodexHome
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -NoCodexSkillInstall
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -NoPathUpdate
```
Remove the toolbox again with:
```powershell
pwsh -NoProfile -File .\scripts\uninstall-toolbox.ps1
```
If you installed into a custom root, pass the same root to uninstall:
```powershell
pwsh -NoProfile -File .\scripts\uninstall-toolbox.ps1 -InstallRoot C:\Tools\MercuryToolbox
```
Manual Rust-native fallback:
```powershell
cargo install --path .\crates\snip
```
## Portable Package
Build a portable release bundle with binaries, package install scripts, manifest, checksums, the combined AI prompt, and the generated Codex skill:
```powershell
pwsh -NoProfile -File .\scripts\package-toolbox.ps1
```
The first hosted package is documented in
[the v0.1.0 release notes](docs/releases/v0.1.0.md), and hosted archives live
on the [Gitea releases page](../../releases).
For an offline install, download
`MercuryToolbox-x86_64-pc-windows-msvc-ReleaseFast.zip`, extract it, then run
the package installer shown below.
Default package behavior:
- builds the full workspace in `ReleaseFast`
- refreshes `docs\ai\mercury-toolbox-ai-prompt.md`
- refreshes `skills\mercury-toolbox\`
- stages a portable directory under `.\dist\MercuryToolbox-<host-target>-ReleaseFast`
- writes `SHA256SUMS.txt` and `mercury-toolbox-package.json`
- creates a matching `.zip` archive you can copy to another machine
Useful package variants:
```powershell
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -Configuration ReleaseSize
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -SkipSlimBinaryRebuild
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -OutputRoot C:\Artifacts
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -PackageName MercuryToolbox-custom
```
Install directly from an extracted package without the Rust toolchain:
```powershell
pwsh -NoProfile -File .\dist\MercuryToolbox-<host-target>-ReleaseFast\scripts\install-package-toolbox.ps1
```
That package installer:
- stages packaged binaries under `$env:LOCALAPPDATA\MercuryToolbox\versions\...`
- updates the stable command directory at `$env:LOCALAPPDATA\MercuryToolbox\current\bin`
- copies the AI prompt, generated skill, manifest, and checksums into `$env:LOCALAPPDATA\MercuryToolbox\share\mercury-toolbox`
- installs the generated `mercury-toolbox` Codex skill into `$env:CODEX_HOME\skills` when `CODEX_HOME` is set, otherwise into `$HOME\.codex\skills`
- updates the user `PATH`, and prints the same reload snippet for shells launched via `pwsh -File`, unless `-NoPathUpdate` is used
Remove a package install again with:
```powershell
pwsh -NoProfile -File .\dist\MercuryToolbox-<host-target>-ReleaseFast\scripts\uninstall-package-toolbox.ps1
```
## Build Profiles And Size Tuning
`ReleaseFast` is the default installer and packager configuration. It uses `opt-level=3`, fat LTO, one codegen unit, `panic=abort`, stripped symbols, and no debug info for fast runtime in portable binaries. This is intentionally slower to compile than debug or plain release builds.
`ReleaseSize` uses the same fat LTO, single-codegen-unit, stripped, aborting baseline with `opt-level="z"` for the smallest binaries and packages. Use it when archive size matters more than throughput, then run the probe gate to compare actual sizes:
```powershell
pwsh -NoProfile -File .\scripts\probe-toolbox.ps1 -BuildProfile ReleaseSize -SkipBenchmarks
```
The install and package scripts perform a second "slim rebuild" pass for selected codeindex-heavy tools after the workspace build. Keep the default for release artifacts. Use `-SkipSlimBinaryRebuild` only for faster local iteration when you can accept potentially larger selected binaries.
Portable packages deliberately do not set `target-cpu=native`. For a local-only build on the current machine, opt in from the shell:
```powershell
$env:RUSTFLAGS = '-Ctarget-cpu=native'
cargo build --profile release-fast -p mercury-mhash --bin mhash
Remove-Item Env:\RUSTFLAGS
```
## Commands
`HIGH RISK:` `msudo` is the top-level high-risk toolbox command because it can cross the Windows privilege boundary. Start with safe discovery first: `msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated`, then inspect `msudo --help` or `msudo run --help` before any explicit `run` request.
### Tool Map
Every command supports `--help`, compact text by default, and structured output through `--json`, `--toon`, or `--format text|json|toon` unless a command-specific format flag is explicitly documented.
| Area | Tool | Primary use | Fast start |
| --- | --- | --- | --- |
| Data and config | `cjson` | Compact JSON or JSONL. | `cjson <PATH>` |
| Data and config | `ison` | Convert JSON and ISON. | `ison <PATH>` |
| Data and config | `isonl` | Convert JSONL and ISONL. | `isonl --from jsonl --to isonl <PATH>` |
| Data and config | `zon` | Convert JSON/JSONL and ZON. | `zon <PATH>` |
| Data and config | `tonl` | Query, validate, index, stream, and ETL TONL. | `tonl query --where active=true <PATH>` |
| Data and config | `mhash` | Hash, manifest, verify, and benchmark files. | `mhash --algorithm sha256 <PATH>` |
| Data and config | `jsonlgrep` | Filter and project JSONL or JSON arrays. | `jsonlgrep level=error <PATH>` |
| Data and config | `jsonshape` | Summarize or diff JSON shape. | `jsonshape <PATH>` |
| Data and config | `csvshape` | Summarize or diff CSV/TSV shape. | `csvshape <PATH>` |
| Data and config | `sqliteshape` | Inspect or diff SQLite schema/table shape. | `sqliteshape <PATH>` |
| Data and config | `sqlshape` | Inspect or diff normalized SQL schema across engines. | `sqlshape --engine sqlite --url <PATH>` |
| Data and config | `config` | Read or edit JSON/YAML/TOML/env/INI config. | `config get <PATH> /version` |
| Data and config | `toon` | Convert external/raw JSON and TOON. | `'{"ok":true}' \| toon` |
| Code and context | `recent` | List fresh files or directories. | `recent --root . --since 2h` |
| Code and context | `pathshadow` | Explain PATH winners and shadowed commands. | `pathshadow rg --summary` |
| Code and context | `fileprobe` | Classify files before opening them. | `fileprobe <PATH>` |
| Code and context | `outline` | List top-level source or config structure. | `outline <PATH>` |
| Code and context | `codeshape` | Map repo files and AST declarations. | `codeshape .` |
| Code and context | `refs` | Find symbol references or callers. | `refs helper .` |
| Code and context | `snip` | Extract exact lines, matches, or symbols. | `snip --lines 16:27 <PATH>` |
| Code and context | `defsnip` | Extract full AST-backed definitions. | `defsnip helper .` |
| Code and context | `ctxpack` | Pack files/snippets/hits/diagnostics for prompts. | `ctxpack <PATH>` |
| Code and context | `chunkcat` | Read large files in bounded chunks. | `chunkcat <PATH> --max-lines 40` |
| Code and context | `hitsnip` | Turn search hits into merged snippets. | `rg -nH "helper" . \| hitsnip --def` |
| Code and context | `diagpick` | Extract actionable diagnostics from logs. | `diagpick <PATH> --def` |
| Code and context | `gitshape` | Summarize Git status and diffs. | `gitshape status` |
| Code and context | `reposhape` | Detect repo ecosystems and entrypoints. | `reposhape .` |
| Code and context | `dotnetshape` | Inspect .NET project graphs and MSBuild config shape. | `dotnetshape .` |
| Logs and runtime | `logshape` | Group repetitive log lines. | `logshape <PATH>` |
| Logs and runtime | `stringscan` | Extract and classify strings from blobs. | `stringscan <PATH>` |
| Logs and runtime | `envdiff` | Snapshot, diff, or wrap environment changes. | `envdiff run --shell pwsh -- <COMMAND>` |
| Logs and runtime | `proctree` | Inspect system, rooted, or command process trees. | `proctree system` |
| Logs and runtime | `sysshape` | Capture machine, shell, env, and tool shape. | `sysshape --group shell` |
| Logs and runtime | `runprobe` | Run one command and capture a stable result object. | `runprobe --shell raw -- <COMMAND>` |
| Logs and runtime | `await` | Poll paths, ports, HTTP, or commands. | `await path <PATH> --state exists` |
| Logs and runtime | `argv` | Quote argv or inspect shell argument passing. | `argv quote --shell pwsh -- git status` |
| Network and locks | `portping` | Probe TCP/HTTP/HTTPS with timings. | `portping tcp://127.0.0.1:80` |
| Network and locks | `portunlock` | Show or free local port owners. | `portunlock who 3000` |
| Network and locks | `unlock` | Inspect file lockers and unlock-aware file actions. | `unlock who <PATH>` |
| Network and locks | `msudo` | Inspect elevation state before privileged launches. | `msudo status --json` |
| Managed, Unity, binary | `asmtype` | Find managed assembly types. | `asmtype <ASSEMBLY> --match SpaceCraft` |
| Managed, Unity, binary | `asmmember` | Inspect managed type members. | `asmmember --assembly <ASSEMBLY> <TYPE>` |
| Managed, Unity, binary | `asmref` | Inspect managed assembly references and dependency closure risks. | `asmref diagnose <ASSEMBLY> --resolve-dir <DIR>` |
| Managed, Unity, binary | `asmapi` | Diff managed public API surfaces. | `asmapi diff <OLD_DLL> <NEW_DLL>` |
| Managed, Unity, binary | `asmflow` | Inspect managed IL bodies and xrefs. | `asmflow find <ASSEMBLY> --match Start` |
| Managed, Unity, binary | `llvmobjdump` | Summarize LLVM objdump sections and disassembly. | `llvmobjdump <PATH> --json` |
| Managed, Unity, binary | `llvmreadobj` | Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM. | `llvmreadobj <PATH> --json` |
| Managed, Unity, binary | `llvmnm` | List and classify object symbols through LLVM nm output. | `llvmnm <PATH> --defined-only --json` |
| Managed, Unity, binary | `peexports` | Deeply inspect PE export tables. | `peexports <DLL> --json` |
| Managed, Unity, binary | `peimports` | Categorize PE import tables by API family. | `peimports <DLL> --category device_io --json` |
| Managed, Unity, binary | `pecalls` | Extract imported API callsites from LLVM disassembly. | `pecalls <DLL> --api WSAStartup --json` |
| Managed, Unity, binary | `pesig` | Infer PE function boundaries and calling convention hints. | `pesig <DLL> --min-confidence medium --json` |
| Managed, Unity, binary | `pestrrefs` | Find strings and direct cross-references in PE code. | `pestrrefs <DLL> --contains DeviceIoControl --json` |
| Managed, Unity, binary | `drvshape` | Summarize likely Windows driver traits and hints. | `drvshape <SYS> --json` |
| Managed, Unity, binary | `ioctlscan` | Scan PE bytes for probable Windows IOCTL constants. | `ioctlscan <SYS> --json` |
| Managed, Unity, binary | `binmeta` | Inspect file metadata, PE basics, version resources, and Windows signature identity. | `binmeta <PATH>` |
| Managed, Unity, binary | `unityasset` | Inspect offline Unity assets and bundles. | `unityasset index <GAME_DATA>` |
| Managed, Unity, binary | `unityprobe` | Query an explicit read-only BepInEx bridge. | `unityprobe status --game-root <GAME>` |
| Managed, Unity, binary | `unitydiag` | Summarize Unity and BepInEx logs. | `unitydiag --game-root <GAME> --latest` |
### `cjson`
Compact JSON or JSONL into single-line output, with an optional stable recursive key sort for diffing, caching, and AI-friendly ingestion.
```powershell
cjson .\fixtures\cjson\sample.json
bat --style=plain --paging=never .\fixtures\cjson\records.jsonl | cjson --input-format jsonl --sort-keys
cjson --sort-keys --json .\fixtures\cjson\sample.json | ConvertFrom-Json
```
### `ison` / `isonl` / `zon` / `tonl`
Work with the compressed JSON family without adding Node or TypeScript runtime dependencies. `ison`, `isonl`, and `zon` are format converters; `tonl` also includes query, validate, index, streaming query, and ETL commands. Use `--toon` or `--format toon` when the wrapper output itself is going to an AI/model.
```powershell
ison .\fixtures\json-family\ison\users.json
isonl --from isonl --to jsonl .\fixtures\json-family\ison\users.isonl
zon .\fixtures\json-family\zon\person.json --toon
tonl query --where active=true .\fixtures\json-family\tonl\records.tonl --format toon
```
### `jsonlgrep`
Filter JSONL, single-line JSON arrays, or line-oriented logs with field selectors, negation, nested paths, projections, and JSON output.
```powershell
jsonlgrep level=error .\fixtures\jsonl\events.jsonl --pick ts,msg
jsonlgrep event.user.name!=alice .\nested.jsonl --pick event.user.name,status
bat --style=plain --paging=never .\fixtures\jsonl\events.jsonl | jsonlgrep 'msg~=login' --count --json | ConvertFrom-Json
recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json
```
### `jsonshape`
Summarize JSON or JSONL structure into compact path statistics, or diff two shape reports when you want additions, removals, and changed kinds without opening the raw payloads.
```powershell
jsonshape .\fixtures\reading\config.json
jsonshape .\fixtures\jsonshape\events.jsonl --input-format jsonl --json | ConvertFrom-Json
jsonshape .\fixtures\toon\config.json --limit 8
jsonshape diff .\fixtures\reading\config.json .\fixtures\toon\config.json --json | ConvertFrom-Json
```
### `mhash`
Compute high-performance OpenHashTab-class file mhashs, write JSONL manifests, verify manifests, list the supported algorithm matrix, and benchmark hash throughput without leaving PowerShell-friendly CLI flows.
`mhash` defaults to SHA-256 text output for simple local checks. Use `--algorithm` for explicit multi-algorithm hashing, `--all` when you want the full OpenHashTab-class matrix, `--json` or `--format jsonl` for machine handoff, and `--manifest` when the hash run should produce a reusable verification file. `mhash verify` reads Mercury JSONL manifests and common checksum-style lines; pass exactly one `--algorithm` when verifying checksum-style text that does not name the algorithm.
```powershell
mhash .\README.md
mhash --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip
mhash list-algorithms
mhash list-algorithms --json | ConvertFrom-Json | Sort-Object family,name
fd -t f . .\dist | mhash --input-format lines --algorithm sha256,blake3-256 --format jsonl | jq -r '.algorithm + " " + .path'
mhash --recursive --ignore target --all --manifest .\checksums.jsonl .\dist --jsonl
mhash verify .\checksums.jsonl --json | ConvertFrom-Json
mhash bench --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip
hyperfine 'mhash --algorithm sha256 .\dist\MercuryToolbox.zip' 'mhash --algorithm blake3-256 .\dist\MercuryToolbox.zip'
```
### `recent`
List recently modified files or directories, respecting `.gitignore` by default and filtering by extension, kind, or basename regex.
```powershell
recent --root . --since 2h --ext rs --name '^(lib|main)$'
'.' | recent --kind dir --limit 10
'.' | recent --limit 5 --json | ConvertFrom-Json
```
### `pathshadow`
Inspect command resolution order across `PATH`, explain who wins, and find every duplicate command available to the shell. Use `--shell powershell` when AI work needs the actual PowerShell winner, including aliases and cmdlets, and `--high-signal --summary` when full duplicate scans are too noisy.
```powershell
pathshadow rg
pathshadow python npm --shell powershell
'cargo' | pathshadow --json | ConvertFrom-Json
pathshadow --all-duplicates --high-signal --summary --json | ConvertFrom-Json
```
### `portping`
Probe TCP, HTTP, and HTTPS targets and emit compact timing summaries or JSON records with method and status expectation support.
```powershell
portping tcp://127.0.0.1:80
portping https://example.com/health --method HEAD --expect-status 200
'https://example.com' | portping --json | ConvertFrom-Json
```
### `portunlock`
Inspect local TCP or UDP port owners on Windows and, when needed, free the port by terminating only the exact remaining owning processes.
```powershell
portunlock who 3000
portunlock free --force 5000
'5000' | portunlock who --json | ConvertFrom-Json
```
### `msudo`
Inspect the current Windows elevation relay status and, when you explicitly choose to cross that boundary, launch a one-shot elevated child process through the configured host.
Reliable today: one-shot `current-process`, `current-user`, `admin`, `system`, and `trustedinstaller` commands, foreground `--same-console` launches in the current terminal, active-session targeting for duplicated high-privilege tokens, and interactive `SYSTEM` / `TrustedInstaller` shells either in a new window or in the current console when `--same-console` is explicit. The CLI is intentionally native to Mercury rather than syntax-compatible with gsudo or NSudo; use explicit options such as `--user trustedinstaller --dangerous --privileges enable-all`. For high-risk flows, start with `msudo status --json` and keep the requested command explicit.
`HIGH RISK:` The global `msudo` rule above applies here too: inspect with `msudo status --json`, check `--help` before using new flags, and relay only the exact command you intend to run.
For `--user trustedinstaller`, verify the token with `whoami /groups`, not just `whoami /user`: the launch runs from the `TrustedInstaller` service token, so the user SID still reports `NT AUTHORITY\SYSTEM` while the token carries the `NT SERVICE\TrustedInstaller` service SID.
```powershell
msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated
msudo --help
msudo run --help
msudo --user trustedinstaller --dangerous --privileges enable-all --integrity system --wait -- cmd /d /c whoami /groups
msudo --same-console --user system --dangerous --shell powershell
```
### `asmtype`
List managed assembly types with compact filters for Unity and general .NET reverse-engineering flows. `--with-member-match` lets you keep only the types whose members look relevant, `--show-matched-members` explains why each type survived that pass while preferring user-facing hits over auto-property backing fields when both are present, `--pick` trims the output for pipelines, `--base` is the fast “derived from this base type” filter, and `--intent unity-spacecraft-workflow` bakes in a good first-pass keyword bundle.
```powershell
asmtype .\fixtures\managed\bin\GameAssembly.dll --match SpaceCraft
asmtype .\fixtures\managed\bin\GameAssembly.dll --with-member-match 'StartProject|QueueVehicle'
asmtype .\fixtures\managed\bin\GameAssembly.dll --with-member-match 'Build|Launch' --show-matched-members --json | ConvertFrom-Json
asmtype .\fixtures\managed\bin\GameAssembly.dll --base '^Game\.ObjectInfoDataScripts\.ProductionItem$' --pick full_name,base_type
asmtype .\fixtures\managed\bin\GameAssembly.dll --with-member-match 'k__BackingField' --user-code-only
'C:\game\Managed\Assembly-CSharp.dll' | asmtype --input-format lines --intent unity-spacecraft-workflow --json | ConvertFrom-Json
'C:\game\Managed\Assembly-CSharp.dll' | asmtype --input-format lines --match 'Rocket|Launch'
asmtype .\fixtures\managed\bin\GameAssembly.dll --namespace 'Game\.UI' --json | ConvertFrom-Json
```
### `asmmember`
List methods, fields, and properties from managed types without hand-written reflection scripts. It now accepts JSONL rows from `asmtype --json`, so AI flows can go from “find likely types” to “inspect their members” without copying names around. `--pick` trims multi-type pipelines down to the fields you actually want, `--user-code-only` hides compiler-generated backing fields and closure artifacts, and the Unity intent preset turns that on automatically.
```powershell
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Game.UI.Windows.Windows.SpaceCraftConstructionWindow
asmtype .\fixtures\managed\bin\GameAssembly.dll --intent unity-spacecraft-workflow --json | asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll --input-format jsonl --intent unity-spacecraft-workflow --json | ConvertFrom-Json
'Game.UI.Windows.Windows.SpaceCraftConstructionWindow' | asmmember --assembly C:\game\Managed\Assembly-CSharp.dll --input-format lines --match 'Build|Launch'
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Data.SpacecraftConstructData --pick kind,name,visibility,signature
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Data.SpacecraftConstructData --user-code-only
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Data.SpacecraftConstructData --binding public,nonpublic,instance,static --json | ConvertFrom-Json
```
### `asmref`
Inspect managed assembly references and see which dependencies resolve from nearby directories. Use `diagnose` for Unity/.NET/Rocket plugin dependency closure checks, including missing references, same-name candidate conflicts, winning DLLs, test-only leaks, and obvious MissingMethod/TypeLoad risks.
```powershell
asmref .\fixtures\managed\bin\GameAssembly.dll --resolve-dir .\fixtures\managed\bin
asmref diagnose .\fixtures\managed\bin\GameAssembly.dll --resolve-dir .\fixtures\managed\bin --format toon
asmref diagnose .\RootPlugin.dll --test-only-pattern Project.Tests --no-default-test-patterns --json | ConvertFrom-Json
'C:\game\Managed\Assembly-CSharp.dll' | asmref --input-format lines --resolve-dir C:\game\Managed --json | ConvertFrom-Json
asmref .\fixtures\managed\bin\GameAssembly.dll --json | ConvertFrom-Json
```
### `asmapi`
Diff two managed assemblies by normalized type and method API. Public API is the default; use `--visibility internal` or `--visibility all` when reverse-engineering non-public compatibility, and use `--include-special` when property/event accessor methods should be visible.
```powershell
asmapi diff old\0Harmony.dll new\0Harmony.dll
asmapi diff Rocket.API.old.dll Rocket.API.new.dll --json | ConvertFrom-Json
asmapi diff old.dll new.dll --visibility all
```
### `asmflow`
Inspect managed method bodies, decoded IL, callers, callees, field access, and string literals when type/member lists are not enough. Use `find` to locate candidate methods, `body` to inspect the IL window, and `xref` to understand call flow.
```powershell
asmflow find .\fixtures\managed\bin\GameAssembly.dll --match 'StartProject|QueueVehicle'
asmflow body --assembly .\fixtures\managed\bin\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject'
asmflow xref --assembly .\fixtures\managed\bin\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartLaunch' --direction both
asmflow xref --assembly .\fixtures\managed\bin\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartLaunch' --direction callers --virtual --json | ConvertFrom-Json
```
### `llvmobjdump`
Run `llvm-objdump` through Mercury's LLVM backend discovery and turn section tables, symbol labels, and disassembly rows into compact text, JSON, or TOON.
```powershell
llvmobjdump .\target\release-fast\binmeta.exe --json | ConvertFrom-Json
llvmobjdump .\target\release-fast\binmeta.exe --section .text --toon
```
### `llvmreadobj`
Run `llvm-readobj` through Mercury's LLVM backend discovery and summarize COFF/PE file headers, sections, imports, exports, debug directories, and CodeView/PDB hints.
```powershell
llvmreadobj .\target\release-fast\binmeta.exe --json | ConvertFrom-Json
llvmreadobj .\target\release-fast\binmeta.exe --debug-directory --toon
```
### `llvmnm`
Run `llvm-nm` through Mercury's LLVM backend discovery and parse POSIX-style symbol rows, including object prefixes and source-line hints when LLVM emits them.
```powershell
llvmnm .\target\release-fast\binmeta.exe --defined-only --json | ConvertFrom-Json
llvmnm .\target\release-fast\binmeta.exe --undefined-only --toon
```
### `peexports`
Inspect PE export tables with ordinals, RVAs, forwarders, and entrypoint hints.
```powershell
peexports C:\Windows\System32\kernel32.dll --json | ConvertFrom-Json
peexports C:\Windows\System32\kernel32.dll --forwarders-only --toon
```
### `peimports`
Inspect and categorize PE imports by API family so you can spot filesystem, registry, device I/O, NT, and network usage quickly.
```powershell
peimports .\target\release-fast\portping.exe --category device_io --json | ConvertFrom-Json
peimports .\target\release-fast\portping.exe --library kernel32.dll --toon
```
### `pecalls`
Extract imported API callsites from LLVM disassembly and keep unresolved rows separate from confirmed import hits.
```powershell
pecalls .\target\release-fast\portping.exe --api WSAStartup --json | ConvertFrom-Json
pecalls .\target\release-fast\binmeta.exe --category device_io --include-jumps --toon
```
### `pesig`
Infer function boundaries and calling-convention hints from PE code shape and symbol labels.
```powershell
pesig .\target\release-fast\portping.exe --min-confidence medium --json | ConvertFrom-Json
pesig .\fixtures\managed\bin\GameAssembly.dll --min-confidence medium --toon
```
### `pestrrefs`
Scan ASCII and UTF-16LE strings, then surface direct cross-references when LLVM disassembly can prove them.
```powershell
pestrrefs .\target\release-fast\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json
pestrrefs .\fixtures\managed\bin\GameAssembly.dll --encoding both --min-len 6 --toon
```
### `drvshape`
Summarize likely driver shape, including WDM, KMDF, NDIS, minifilter, and native driver hints.
```powershell
drvshape C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json
drvshape C:\Windows\System32\drivers\ndis.sys --toon
```
### `ioctlscan`
Scan PE bytes for probable Windows IOCTL constants and decode the `CTL_CODE` fields for quick triage.
```powershell
ioctlscan C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json
ioctlscan C:\Windows\System32\drivers\ndis.sys --toon
```
### `binmeta`
Inspect file metadata, Windows PE structure, version resources, and Authenticode/catalog signature identity with compact text output for humans and stable JSON for automation.
```powershell
binmeta .\fixtures\binmeta\plain.txt
binmeta .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json
binmeta C:\Windows\System32\notepad.exe --json | ConvertFrom-Json | Select-Object path,version,signature
fd -a '^jsonlgrep\.exe$' .\target | binmeta --input-format lines --json | ConvertFrom-Json
```
For PE files, `binmeta` adds nullable `version` and `signature` objects. Version output includes common resource strings such as company, product, file version, original filename, and fixed four-part versions; signature output includes embedded certificate table presence, WinTrust status, embedded-vs-catalog signature type, catalog path/member tag when available, signer subject, chain summaries, timestamp signer, and certificate expiry fields. Signature or trust failures are reported as data and do not make `binmeta` fail.
### `fileprobe`
Probe whether a file is source, config, text, or binary before opening it, and surface AI-friendly hints such as language, minified/generated status, encoding, BOM, and newline style.
```powershell
fileprobe .\fixtures\reading\sample.rs
fileprobe .\fixtures\reading\minified.js --json | ConvertFrom-Json
fd -a '^sample\.rs$' .\fixtures\reading | fileprobe --input-format lines --json | ConvertFrom-Json
```
### `outline`
Emit heuristic structure summaries for Rust, C#, JSON, TOML, and YAML so you can jump straight to the interesting part of a file.
```powershell
outline .\fixtures\reading\sample.rs
outline --depth 1 .\fixtures\reading\config.toml
'.\fixtures\reading\config.yaml' | outline --json | ConvertFrom-Json
```
### `codeshape`
Walk a code repository with tree-sitter-backed indexing and emit a compact project map of files, declarations, and signatures. The JSON report includes `engine=codeindex` so downstream consumers can see the shared AST source explicitly.
```powershell
codeshape .\fixtures\polyglot\repo
codeshape --max-depth 1 --limit-per-file 8 .\fixtures\polyglot\repo --json | ConvertFrom-Json
'.\fixtures\polyglot\repo' | codeshape --json | ConvertFrom-Json
```
### `refs`
Find exact symbol use-sites or caller summaries through the shared `codeindex` engine, with text fallback when AST lookup is unavailable.
```powershell
refs helper .\fixtures\polyglot\repo
refs --callers helper .\fixtures\polyglot\repo --json | ConvertFrom-Json
refs --at .\fixtures\polyglot\repo\src\lib.rs:25 .\fixtures\polyglot\repo
```
### `snip`
Extract precise ranges, regex neighborhoods, or heuristic symbol blocks from files or piped text with numbered output.
```powershell
snip --lines 16:27 .\fixtures\reading\sample.rs
snip --symbol run .\fixtures\reading\sample.rs --json | ConvertFrom-Json
snip --around helper --context 0 .\fixtures\reading\sample.rs
```
### `defsnip`
Extract full AST-backed definition blocks by exact symbol name so nearby line churn does not break your code slices. The JSON rows include `engine=codeindex` for the same reason as `codeshape`, and the text mode now warns when one symbol name resolves to multiple definitions.
```powershell
defsnip helper .\fixtures\polyglot\repo
defsnip build_report . --json | ConvertFrom-Json
defsnip --kind method --parents Build .\fixtures\polyglot\repo
'.\fixtures\polyglot\repo\web\app.ts' | defsnip helper --json | ConvertFrom-Json
```
### `ctxpack`
Pack files, line hits, diagnostics, snippets, and definition JSON into compact context blocks that are ready to hand to an AI agent or paste into a review note.
```powershell
ctxpack .\fixtures\polyglot\repo\src\lib.rs:26
refs helper .\fixtures\polyglot\repo --json | ctxpack --input-format auto
diagpick .\fixtures\diag\rust-errors.txt --def --json | ctxpack --input-format auto --json | ConvertFrom-Json
```
### `chunkcat`
Plan stable line chunks for large text files, then print only the chunk you need with optional JSON metadata for scripts and AI flows. `--tail` is the quick “show me the last window” mode for logs.
```powershell
chunkcat .\fixtures\reading\sample.rs --max-lines 8
chunkcat .\fixtures\reading\sample.rs --max-lines 8 --chunk 2 --json | ConvertFrom-Json
chunkcat .\BepInEx\LogOutput.log --max-lines 20 --tail
fd -a '^sample\.rs$' .\fixtures\reading | chunkcat --input-format lines --chunk 0
```
### `hitsnip`
Turn `rg -n` output or `path:line[:column]` hit streams into merged, numbered snippets. `--def` promotes those hits to the enclosing definition when `codeindex` supports the file, and `--allow-empty` keeps exploratory pipelines quiet when there were no hits.
```powershell
rg -nH "Mode::" .\fixtures\reading\sample.rs | hitsnip --context 1
rg -nH "helper" .\fixtures\polyglot\repo\src\lib.rs | hitsnip --def
rg -n "error|warning" .\fixtures\diag\rust-errors.txt | hitsnip --path .\fixtures\diag\rust-errors.txt --context 1
rg -nH "DefinitelyMissing" .\fixtures\reading\sample.rs | hitsnip --allow-empty --json | ConvertFrom-Json
bat --style=plain --paging=never .\fixtures\hits\rg-output.txt | hitsnip --json | ConvertFrom-Json
```
### `diagpick`
Extract actionable diagnostics from compiler and runtime logs, with optional snippets and enclosing definitions. Clean logs now say `0 actionable diagnostics` in text mode instead of failing silently.
```powershell
diagpick .\fixtures\diag\rust-errors.txt
diagpick .\fixtures\diag\unity-errors.txt --snip --json | ConvertFrom-Json
diagpick .\fixtures\diag\rust-errors.txt --def
diagpick .\BepInEx\LogOutput.log --severity warning
```
### `logshape`
Collapse repetitive logs into template groups before reading the raw stream.
```powershell
logshape .\fixtures\logs\repetitive.log
logshape .\fixtures\logs\repetitive.log --json | ConvertFrom-Json | Select-Object -ExpandProperty groups
```
### `stringscan`
Extract printable strings from binaries or opaque artifacts and classify the high-signal matches.
```powershell
stringscan .\fixtures\binaries\stringscan-sample.bin
stringscan .\fixtures\binaries\stringscan-sample.bin --details --kind bepinex
fd -a '^stringscan-sample\.bin$' .\fixtures\binaries | stringscan --input-format lines --json | ConvertFrom-Json
```
### `toon`
Convert between JSON and TOON text, including tabular arrays, safe key folding, safe dotted-path expansion, and JSONL-to-array ingestion.
```powershell
toon .\fixtures\toon\config.json
toon .\fixtures\toon\config.toon --json | ConvertFrom-Json
toon .\fixtures\toon\records.jsonl
```
### `csvshape`
Summarize huge CSV or TSV files into a bounded, AI-friendly schema view with detected delimiter, header presence, inferred column kinds, blank counts, short examples, and diff support.
```powershell
csvshape .\fixtures\csvshape\sample.csv
csvshape .\fixtures\csvshape\sample.tsv --delimiter tab --json | ConvertFrom-Json
csvshape .\fixtures\csvshape\sample.csv --limit-columns 8 --sample-rows 16
csvshape diff .\fixtures\csvshape\sample.csv .\fixtures\csvshape\sample.tsv --json | ConvertFrom-Json
```
### `sqliteshape`
Inspect SQLite databases read-only without dropping into an interactive shell, keeping the default view cheap and compact, and diff two database shapes when schemas move. Use `sqliteshape` for SQLite-only local inspection; use `sqlshape` when you need a normalized cross-database report or diff.
```powershell
sqliteshape .\fixtures\sqliteshape\sample.db
'C:\data\events.db' | sqliteshape --input-format lines --json | ConvertFrom-Json
sqliteshape .\fixtures\sqliteshape\sample.db --table users --include-indexes
sqliteshape diff .\before.db .\after.db --json | ConvertFrom-Json
```
### `sqlshape`
Inspect SQL schema shape read-only across PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, and DuckDB. It normalizes tables, views, columns, primary keys, foreign keys, indexes, and cheap row estimates into one model, and it redacts connection strings in reports and errors.
```powershell
sqlshape --engine sqlite --url .\fixtures\sqliteshape\sample.db --json | ConvertFrom-Json
sqlshape --engine duckdb --url .\data\warehouse.duckdb --toon
sqlshape --engine postgres --url "postgres://user:pass@host:5432/app" --schema public
sqlshape diff --before-engine sqlite --before-url .\before.db --after-engine duckdb --after-url .\after.duckdb --json | ConvertFrom-Json
```
### `unityasset`
Inspect offline Unity assets, AssetBundles, YAML scenes, and prefabs without opening the Unity editor. Start with `index`, then use object ids with `refs`, `dump`, or `extract`.
```powershell
unityasset index 'C:\game\Game_Data'
unityasset index 'C:\game\Game_Data' --class MonoBehaviour --script 'MarketOffer|LaunchVehicle'
unityasset index 'C:\game\Game_Data' --class '^VideoClip$' --summary
unityasset refs 'sharedassets0.assets#1234' 'C:\game\Game_Data' --json | ConvertFrom-Json
unityasset extract 'resources.assets#5678' 'C:\game\Game_Data' --output-dir .\out
```
### `unityprobe`
Query a running Mono Unity game through an explicit read-only BepInEx bridge. It does not inject implicitly: install the bridge first, check status, then query scenes, objects, instances, or static state.
```powershell
unityprobe install 'C:\game'
unityprobe status --game-root 'C:\game'
unityprobe --json scenes | ConvertFrom-Json
unityprobe --json find 'Game\.UI\.Windows' | ConvertFrom-Json
unityprobe inspect 10432
unityprobe static Manager.GameManager
```
### `unitydiag`
Extract high-signal incidents from Unity `Player.log` and BepInEx logs, with grouping, stack controls, severity filters, and game-root discovery.
```powershell
unitydiag 'C:\Users\example\AppData\LocalLow\Studio\Game\Player.log'
unitydiag --game-root 'C:\game' --latest
unitydiag 'C:\game\BepInEx\LogOutput.log' --include-info --top 10
unitydiag --game-root 'C:\game' --json | ConvertFrom-Json
```
### `envdiff`
Capture environment snapshots, compare them, or wrap a command so PATH pollution and variable mutations become obvious immediately.
```powershell
envdiff snapshot --output .\before.json
envdiff diff .\before.json .\after.json --json | ConvertFrom-Json
envdiff run --shell cmd -- .\scripts\set-env.cmd
envdiff run --shell pwsh -- .\scripts\set-env.ps1
```
### `proctree`
Show the live Windows process tree, a subtree rooted at a PID, or the descendants of a command you just ran.
```powershell
proctree system
proctree root 1234 --json | ConvertFrom-Json
proctree run -- pwsh -NoProfile -Command "npm test"
```
### `sysshape`
Capture a compact machine and tool inventory for AI-friendly triage without manually checking the shell, environment, and language toolchains one by one.
`--env safe` keeps curated non-secret variables while leaving raw path-like values out of `environment`; the segmented `path_like` view carries PATH-heavy details more compactly. JSON output now includes `system.default_shell`, `system.session_shell`, `path_like[].duplicate_segments`, and per-tool `probe_status` / `error`.
```powershell
sysshape --group shell
sysshape --json --env safe --group shell | ConvertFrom-Json
sysshape --json --env safe --group all | ConvertFrom-Json
sysshape --env none --group dev
```
### `runprobe`
Run one command and capture the stable result object you actually want in scripts or AI flows: exit code, duration, timeout status, and bounded stdout/stderr tails.
```powershell
runprobe --shell raw -- cmd /d /s /c "exit 0"
runprobe --shell pwsh --timeout 2s -- Write-Output done
runprobe --json --shell cmd --timeout 1s -- cmd /d /s /c "echo hello & echo boom 1>&2 & exit 5" | ConvertFrom-Json
```
### `await`
Wait for a path, TCP target, HTTP endpoint, or repeated command condition without hand-writing polling loops.
```powershell
await path .\target\ready.flag --state exists
await port tcp://127.0.0.1:5000 --interval 200ms
await http http://127.0.0.1:8080/health --status 204
await run --shell pwsh -- .\scripts\health.ps1
```
### `argv`
Quote argument vectors for `pwsh`/`cmd`/raw launches and inspect what a shell really passed to a native process.
```powershell
argv quote --shell pwsh -- git commit -m "two words"
'["tool.exe","two words"]' | argv quote --shell cmd
argv inspect --json --shell pwsh -- alpha "two words" | ConvertFrom-Json
```
### `config`
Read and edit common config formats with slash-pointer paths and explicit value typing.
```powershell
config get .\package.json /version
config set .\config.yaml /retries 3 --value-type number
config ls --format toml .\settings.toml --json | ConvertFrom-Json
```
### `gitshape`
Summarize Git status and diffs into compact AI-friendly counters, changed files, line deltas, and touched-symbol hints.
```powershell
gitshape status
gitshape status --repo C:\src\repo --json | ConvertFrom-Json
gitshape diff --staged --json | ConvertFrom-Json
```
### `reposhape`
Detect repository ecosystems, manifests, command entrypoints, and CI hints before you start opening files.
```powershell
reposhape .
reposhape . --json | ConvertFrom-Json
reposhape C:\src\repo --max-depth 4
```
### `dotnetshape`
Inspect .NET project graphs, inherited MSBuild properties, package references, and build-shape warnings without invoking MSBuild.
```powershell
dotnetshape .
dotnetshape . --json | ConvertFrom-Json
dotnetshape C:\src\repo --max-depth 4
```
### `unlock`
Inspect file lockers and perform unlock-aware delete, move, rename, copy, or free operations with staged escalation. `unlock who` now defaults to a fast Restart Manager pass for interactive triage, while `--deep` adds the slower global handle scan when you need exhaustive coverage.
```powershell
unlock who .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results
unlock who --deep .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results
unlock free --force .\locked.txt
unlock delete --force .\locked.txt
```
## AI Assets
Mercury ships both a compact English AI prompt and a real Codex skill. The prompt is the terse “tool card”; the skill is the route-oriented entrypoint plus the generated command catalog.
```powershell
pwsh -NoProfile -File .\scripts\generate-ai-prompt.ps1
pwsh -NoProfile -File .\scripts\check-ai-prompt.ps1
pwsh -NoProfile -File .\scripts\generate-ai-skill.ps1
pwsh -NoProfile -File .\scripts\check-ai-skill.ps1
```
The generated skill lives in `.\skills\mercury-toolbox\`. Installing into Codex happens when you run `install-toolbox.ps1` or install a packaged build, unless `-NoCodexSkillInstall` is used.
For the authoritative full command reference, prefer the generated assets over this README: `docs\ai\mercury-toolbox-ai-prompt.md` is the compact prompt view, and `skills\mercury-toolbox\references\command-catalog.md` is the full generated catalog that packaged installs carry forward too.
## Development
For the day-to-day loop, use the repo-level [justfile](./justfile) and [bacon.toml](./bacon.toml):
`just test` and the scoped `*-test` recipes use `cargo nextest`; treat nextest as the default test runner for this repository. Plain `cargo test` is only for tool-specific cases that explicitly require it.
Start new user-facing features from the [Jade feature template](docs/templates/jade-feature-template.md) so CLI contracts, tests, generated AI assets, and handoff notes stay synchronized. For daily low-risk cleanup, use the [daily maintenance template](docs/templates/daily-maintenance-template.md) with the durable backlog in `.codex-progress\quality-security-backlog.md`.
```powershell
just
just --summary
just periphery-check
just workspace-check
just check
just code-check
just data-test
just runtime-check
just windows-test
just msudo-verify
just managed-clippy
just mhash-check
just mhash-test
just mhash-clippy
just mhash-bench
just mhash-benchmark
just ai-check
just test
just install
just uninstall
just package
just install-package
just uninstall-package
just package-roundtrip
just jade-skip-coverage
bacon
bacon code
bacon code-test
bacon code-clippy
bacon data
bacon data-test
bacon data-clippy
bacon mhash
bacon mhash-test
bacon mhash-clippy
bacon runtime
bacon runtime-test
bacon runtime-clippy
bacon windows
bacon msudo-verify
bacon managed
bacon managed-test
bacon managed-clippy
bacon unity-test
bacon unity-clippy
bacon ai
bacon clippy
bacon test
```
`just periphery-check` is the lightweight lane for docs, PowerShell scripts, justfile recipes, templates, and generated AI asset hygiene: it prints the recipe summary, runs the PowerShell gate, and rechecks generated AI assets without a Rust rebuild.
`just workspace-check` is the fast lane for everyday repo-wide confidence: formatting, cargo check, a `release-fast` workspace build, AI asset checks, and the PowerShell gate without the heavier install/package roundtrips.
For documentation-only maintenance, start from `just --summary` and the [maintainer notes](docs/maintainer-notes.md). Add `just ai-check` when a change mentions generated prompt or skill assets, then use `just periphery-check` before handoff when the patch changes workflow instructions, templates, scripts, or just recipes. Do not claim generated AI assets were refreshed unless the generator or check command was actually run.
Use the fuller gates when the change reaches beyond that quick lane:
- `just ecosystem` exercises install, package, and portable install flows.
- `just jade` is the full mandatory Jade gate: fmt, check, coverage-backed tests, strict Clippy, root and fuzz dependency audits, Miri, fuzzing, sanitizer, no-panic, Loom, PowerShell, generated AI assets, ecosystem checks, and the selected verification build profile.
- `just jade-skip-coverage` is still a broad local gate, but skipping coverage means it is not the release-quality Jade proof.
- `just miri`, `just fuzz`, `just sanitizer`, `just no-panic`, and `just loom` are focused repair loops. They are not exemptions and not a separate optional safety tier.
Run the broader Jade verification gate:
```powershell
pwsh -NoProfile -File .\scripts\check-jade.ps1
```
If a hardening gate truly cannot run on a machine, pass the matching `-ExemptMiri`, `-ExemptFuzz`, `-ExemptSanitizers`, `-ExemptNoPanic`, or `-ExemptLoom` flag with a non-empty reviewed reason. Do not turn those exemptions into default workflow recipes.
Run the install/package ecosystem gate:
```powershell
pwsh -NoProfile -File .\scripts\check-ecosystem.ps1
```
The hosted Gitea repository now uses native `.gitea/workflows` automation:
- `.gitea/workflows/ci.yml` runs the everyday verification lane on pushes, pull requests, and manual dispatches.
- `.gitea/workflows/release.yml` is tag-driven. It requires a tag like `v0.1.0` that matches `[workspace.package].version`, runs `just jade`, builds the portable package, and publishes the release through `scripts\publish-gitea-release.ps1`.
- `scripts\setup-gitea-runner.ps1` provisions a Windows host runner for the current repo, registers it with the repo-level runner token API, writes a host-backend config, and installs a startup entry so `.gitea/workflows` can execute on this machine again after logon.
For runner or release maintenance, keep the toolchain snapshot and secret surfaces in the handoff: confirm `cargo nextest --version`, `cargo llvm-cov --version`, `just --version`, and `pwsh --version` are visible in CI logs, and treat `.runner`, `GITEA_TOKEN`, and `GITEA_API_TOKEN` as host-local secret material. The maintainer checklist for those flows lives in [docs/maintainer-notes.md](docs/maintainer-notes.md).
If Git for Windows crashes in `git-remote-https.exe` while credential-manager or schannel credentials are being resolved, do not embed tokens in `origin` or Git config. Use the repo helper, which disables credential-manager lookup for that one command and passes a transient Basic auth header:
```powershell
$env:GITEA_API_TOKEN = '<repo token for this shell only>'
pwsh -NoProfile -File .\scripts\invoke-gitea-git.ps1 ls-remote origin refs/heads/main
pwsh -NoProfile -File .\scripts\invoke-gitea-git.ps1 push origin main
```
The helper uses Git's OpenSSL backend by default and keeps TLS verification enabled. If the local Gitea test host is temporarily presenting a certificate chain that Git cannot validate, add `-InsecureSkipTlsVerify` only for that one command. See `docs\maintainer-notes.md` before changing machine-wide Git credential or TLS settings.
For a local one-shot release from a checked-out repo, the `just` recipes now line up with the hosted workflow:
```powershell
just package
just publish-release v0.1.0 .\docs\releases\v0.1.0.md
```
Measure binary size and representative latency with the probe gate:
```powershell
pwsh -NoProfile -File .\scripts\probe-toolbox.ps1
pwsh -NoProfile -File .\scripts\probe-toolbox.ps1 -BuildProfile ReleaseSize -SkipBenchmarks
pwsh -NoProfile -File .\scripts\probe-toolbox.ps1 -BuildProfile ReleaseFast -IncludeBloat
```
On Windows, `cargo flamegraph` will use DTrace when it is configured; otherwise it falls back to `blondie`, which requires an elevated shell. `probe-toolbox.ps1 -IncludeFlamegraph` writes a capability report first and skips impossible runs instead of repeatedly failing blindly.
`samply` is installed by the Jade tooling script, but Windows recording still requires `xperf.exe` from Windows Performance Toolkit.
`sccache` is also wired into `.cargo/config.toml` as the default `rustc-wrapper`. Check it with `sccache --show-stats`, and reset counters with `sccache --zero-stats` before a fresh probe run when you want clean measurements.
For a one-shot UAC relay on Windows, use the dedicated wrapper:
```powershell
pwsh -NoProfile -File .\scripts\cargo-flamegraph-windows.ps1 -Package refs -TargetArgumentJson '["helper",".\\fixtures\\polyglot\\repo","--limit","12"]'
```
If you add `-LogPath .\dist\probe\release-fast\flamegraphs\refs.log`, the wrapper now writes a compact relay log to `refs.log` and the full elevated-session transcript to `refs.log.transcript.txt`.
View Git Blame Copy Permalink