chore(release): prepare public source release
This commit is contained in:
MercuryToolbox Release
@@ -0,0 +1,62 @@
|
||||
# Mercury Toolbox AI Prompt
|
||||
Available tools: cjson, ison, isonl, zon, tonl, mhash, jsonlgrep, jsonshape, 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
|
||||
Rules: Prefer Mercury first when the task is local inspection, shaping, or triage. Prefer compact text. Use `--json` when the next step parses output, and use `--toon` or `--format toon` when structured output is meant for an AI/model to read. Pipe external JSON into `toon` only when the producer is not a Mercury tool; TOON auto-detects JSON and emits denser TOON by default. Set `$env:MERCURY_OUTPUT='json'` or `$env:MERCURY_OUTPUT='toon'` when most commands in the session should default to that structured format. Prefer stdin and pipelines over re-reading large files. Prefer `fileprobe`, `outline`, `snip`, `chunkcat`, `hitsnip`, `defsnip`, `codeshape`, `refs`, and `ctxpack` over raw `Get-Content`, `cat`, or whole-file dumps. Every tool has guided triage metadata in the generated prompt and skill catalog; PE deep-analysis tools also emit runtime `answer=`, `trust`, `report_quality`, and `next_actions` fields. For every command, read the generated `guided_triage` answer, trust basis, and next actions before inventing a new path. When you are unsure which command to run next, prefer the emitted `next_actions` before inventing an ad-hoc pipeline. Use these tools with modern CLI companions such as `rg`, `fd`, `jq`, `yq`, `bat`, `sd`, `xh`, `tokei`, `eza`, `procs`, `dust`, `hyperfine`, `hexyl`, `zoxide`, `lazygit`, `delta`, and PowerShell. Prefer `mhash` for local hashing, OpenHashTab-class algorithm discovery, JSONL manifest generation and verification, and quick hash throughput benches; pair its JSON/JSONL output with `jq` and compare external command timing with `hyperfine` when needed. Prefer `rg` over recursive `grep` or `Select-String`, `fd` over recursive `Get-ChildItem`, `bat` over raw `Get-Content`, `jq` or `yq` over manual JSON or YAML parsing, and `xh` over `curl` for quick HTTP checks.
|
||||
cjson: Compact JSON or JSONL before piping, diffing, or model input. Better than: pretty multi-line JSON when you need compact stable output and optional key sorting. Usage: `cjson [OPTIONS] [PATH]` Example: `cjson <PATH>` Guided: answer=Answer whether JSON/JSONL can be compacted cleanly and deterministically. trust=Trust the JSON parser result and document count; invalid JSON is reported before compaction. next=Run jsonshape on the compacted payload when you need schema shape. | Pipe to jq or toon for projection/model handoff.
|
||||
ison: Convert between JSON and ISON records for compact structured handoff. Better than: verbose JSON when a deterministic compact ISON representation is easier to scan or diff. Usage: `ison [OPTIONS] [PATH]` Example: `ison <PATH>` Guided: answer=Answer whether JSON can round-trip through compact ISON for handoff. trust=Trust successful parser/encoder output; use JSON mode when a tool must consume it next. next=Use isonl for line-oriented streams. | Use toon when the next consumer is an AI model.
|
||||
isonl: Convert between JSONL and ISONL line records. Better than: manual JSONL splitting when line-oriented ISON records are better for streaming or model input. Usage: `isonl [OPTIONS] [PATH]` Example: `isonl --from jsonl --to isonl <PATH>` Guided: answer=Answer whether JSONL/ISONL records can be converted as a stream. trust=Trust per-line parser diagnostics and document counts; malformed lines stop the conversion. next=Pipe into jsonlgrep for filtering. | Use cjson or toon for downstream compact handoff.
|
||||
zon: Convert JSON or JSONL to Zero Overhead Notation and back. Better than: hand-written compact table encodings when you need Zero Overhead Notation interop without Node tooling. Usage: `zon [OPTIONS] [PATH]` Example: `zon <PATH>` Guided: answer=Answer whether JSON/JSONL can convert to or from Zero Overhead Notation. trust=Trust parser diagnostics and wrapper metadata for document count and target format. next=Use jsonshape after decoding to validate shape. | Use toon for model-facing structured summaries.
|
||||
tonl: Encode, decode, query, validate, index, stream-query, and ETL JSON-backed TONL data. Better than: one-off scripts for compact JSON ETL, validation, query, indexing, or streaming filters. Usage: `tonl <COMMAND> [OPTIONS] [PATH] | tonl index <build|query> [OPTIONS] | tonl stream query [OPTIONS] [PATH]` Example: `tonl query --where active=true <PATH>` Guided: answer=Answer filtered TONL records, validation status, indexes, or ETL conversion results. trust=Trust explicit validation/query diagnostics; streaming mode reports record-level failures. next=Use jsonlgrep for simple JSONL filtering before TONL conversion. | Use cjson or toon for compact handoff.
|
||||
mhash: Compute local file hashes across the OpenHashTab-class matrix, list algorithms, hash with `--all` or explicit multi-algorithm sets, produce JSONL manifests, verify manifests, or benchmark hash throughput. Better than: PowerShell Get-FileHash loops, GUI hash tabs, ad-hoc checksum scripts, or manual benchmark harnesses when you need OpenHashTab-class algorithm coverage, manifests, verification, JSON/JSONL, and throughput telemetry in one local CLI. Usage: `mhash [OPTIONS] [PATH...] | mhash verify [OPTIONS] <MANIFEST> | mhash list-algorithms [--json] | mhash bench [OPTIONS] [PATH...]` Example: `mhash --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip --json | ConvertFrom-Json` Guided: answer=Answer file identity, checksum, manifest verification, or hash throughput questions. trust=Trust algorithm labels, manifest verification status, and per-file error rows. next=Use fileprobe first when the file type is unknown. | Use jsonlgrep or jq to filter manifest rows.
|
||||
jsonlgrep: Filter JSONL logs, single-line JSON arrays, or structured event streams by field. Better than: ad-hoc `jq` for simple field filters, projections, counts, and regex matches. Usage: `jsonlgrep [OPTIONS] <QUERY> [PATH...]` Example: `recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json` Guided: answer=Answer which JSONL records match field, regex, or projection filters. trust=Trust parsed JSON records and explicit malformed-line diagnostics. next=Use jsonshape on matched records to inspect structure. | Use toon or cjson for compact AI handoff.
|
||||
jsonshape: Summarize JSON or JSONL into path/type stats, or diff two shape reports. Better than: opening raw payloads when you first need the shape, key paths, or a schema diff. Usage: `jsonshape [OPTIONS] [PATH...] | jsonshape [OPTIONS] diff <BEFORE> <AFTER>` Example: `jsonshape diff before.json after.json --json | ConvertFrom-Json` Guided: answer=Answer the key paths, types, counts, and shape differences in JSON/JSONL. trust=Trust reported path/type counts when parsing succeeds; review diff diagnostics for drift. next=Use jsonlgrep to isolate records before reshaping. | Use cjson to normalize payloads before comparing.
|
||||
recent: List recently changed files or directories. Better than: manual directory scans when you just need the freshest files and `.gitignore` awareness. Usage: `recent [OPTIONS]` Example: `recent --root . --since 2h --ext rs --name '^(lib|main)$'` Guided: answer=Answer which files or directories changed recently. trust=Trust timestamp filters and gitignore-aware discovery within the selected root. next=Pipe paths into fileprobe or outline. | Use hitsnip or ctxpack after narrowing files.
|
||||
pathshadow: Show which executable wins and which ones are shadowed. Better than: guessing PATH order when the wrong executable is being picked. Usage: `pathshadow [OPTIONS] [COMMAND...]` Example: `pathshadow python npm --shell powershell --summary --json | ConvertFrom-Json` Guided: answer=Answer which executable wins on PATH and which candidates are shadowed. trust=Trust resolved filesystem candidates and shell-aware summary rows. next=Use sysshape --group shell for broader environment context. | Use argv quote when command invocation quoting is suspicious.
|
||||
portping: Probe ports or health endpoints with timings. Better than: jumping between multiple network tools for quick TCP and HTTP reachability checks. Usage: `portping [OPTIONS] [TARGET...]` Example: `portping tcp://127.0.0.1:80` Guided: answer=Answer whether a TCP/HTTP/HTTPS endpoint is reachable and how long it took. trust=Trust direct connection/status timing; failures distinguish DNS, connect, and HTTP states. next=Use portunlock when a local port is unexpectedly occupied. | Use await port/http to wait for readiness.
|
||||
portunlock: Show and free local TCP or UDP port owners on Windows. Better than: guessing which process owns a port or hand-writing `netstat` and kill loops when a local listener refuses to go away. Usage: `portunlock [OPTIONS] who <PORT...> | portunlock [OPTIONS] free <PORT...>` Example: `portunlock who --json --protocol any 3000 8080 | ConvertFrom-Json` Guided: answer=Answer which process owns a local TCP/UDP port and optionally free it. trust=Trust OS port snapshots and post-action verification rows. next=Use proctree on the owning PID before freeing. | Use portping after freeing or restarting a listener.
|
||||
msudo: Top-level high-risk command: inspect Windows elevation relay status, token state, active session state, and host availability before any privileged launch. Better than: guessing whether Windows elevation relay support is available, or hand-writing `Start-Process -Verb RunAs` wrappers when you first need the current privilege status. Usage: `msudo [OPTIONS] [--] <COMMAND...> | msudo run [OPTIONS] [--] <COMMAND...> | msudo status [OPTIONS] | msudo [OPTIONS] --shell <PRESET>` Example: `msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated` Guided: answer=Answer Windows elevation, token, relay, and launch-shape questions. trust=Trust status discovery before launch; treat run actions as high risk and explicit. next=Start with msudo status --json. | Use argv quote before privileged shell wrapping.
|
||||
asmtype: List managed assembly types and filter them by name, namespace, base type, interface, or matching members, with optional user-code-only screening. Better than: manual reflection or ad-hoc PowerShell when you first need the type map from a managed assembly. Usage: `asmtype [OPTIONS] [ASSEMBLY...]` Example: `asmtype <PATH> --with-member-match 'Build|Launch' --show-matched-members --pick full_name,base_type,matched_members --json | ConvertFrom-Json` Guided: answer=Answer which managed types match name, inheritance, interface, or member intent. trust=Trust metadata enumeration from the target assembly; broaden filters when no matches return. next=Pipe JSONL into asmmember. | Use asmflow find/xref when behavior matters.
|
||||
asmmember: Inspect managed type members with binding filters and compact signatures, including JSONL handoff from `asmtype` and user-code-only filtering. Better than: long reflection scripts when you need methods, fields, and properties from a known managed type. Usage: `asmmember [OPTIONS] <TYPE...>` Example: `asmtype <PATH> --intent unity-spacecraft-workflow --json | asmmember --assembly <PATH> --input-format jsonl --intent unity-spacecraft-workflow --pick type_name,name,visibility,signature --json | ConvertFrom-Json` Guided: answer=Answer which methods, fields, and properties exist on selected managed types. trust=Trust assembly metadata and binding filters; use non-public filters intentionally. next=Use asmflow body for IL details. | Use asmapi diff when comparing versions.
|
||||
asmref: Inspect managed assembly references, check whether they resolve from local directories, or run `diagnose` to report closure risks such as missing references, same-name version/token conflicts, winning DLLs, test-only leaks, and obvious MissingMethod/TypeLoad hazards. Better than: guessing missing managed dependencies when you need a fast reference, resolution, or Unity/Rocket plugin closure diagnosis pass. Usage: `asmref [OPTIONS] [ASSEMBLY...] | asmref diagnose [OPTIONS] [ASSEMBLY...]` Example: `asmref diagnose <PATH> --resolve-dir <PATH> --format toon` Guided: answer=Answer managed references, resolution status, and dependency closure risks. trust=Trust resolved candidates and risk tiers; explicit resolve dirs define the runtime universe. next=Run asmref diagnose for closure risks. | Use asmapi diff on risky version changes.
|
||||
asmapi: Compare two managed assemblies for added or removed public types, removed methods, signature changes, and MissingMethodException risks, with optional internal/all visibility. Better than: manual reflection diffs or brittle spreadsheet comparisons when you need to know what managed API changed between two DLL versions. Usage: `asmapi [OPTIONS] <SUBCOMMAND> [ARGS...]` Example: `asmapi diff .\old\0Harmony.dll .\new\0Harmony.dll --json | ConvertFrom-Json` Guided: answer=Answer public API differences between managed assemblies. trust=Trust metadata comparison under the chosen visibility scope. next=Use asmref diagnose to connect API drift to dependency closure. | Use asmmember on removed or changed types.
|
||||
asmflow: Inspect managed method bodies, IL summaries, and cross-references for Unity and general .NET reverse-engineering flows. Better than: ad-hoc IL dump scripts or manual dnSpy browsing when you need callers, callees, field access, or string literals from a managed method quickly. Usage: `asmflow [OPTIONS] <SUBCOMMAND> [ARGS...]` Example: `asmflow xref --assembly <PATH> 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject' --json | ConvertFrom-Json` Guided: answer=Answer managed IL bodies, callers, callees, field access, and string references. trust=Trust method-body metadata when the target method resolves; unknown bodies are reported. next=Use asmtype/asmmember to find exact targets. | Use ctxpack to hand off IL evidence.
|
||||
llvmobjdump: Inspect object sections, symbol labels, and disassembly through LLVM backend discovery. Better than: raw llvm-objdump text when you need compact section, symbol, and disassembly shape for COFF/PE or object files. Usage: `llvmobjdump [OPTIONS] [PATH...]` Example: `llvmobjdump .\target\release-fast\binmeta.exe --json | ConvertFrom-Json` Guided: answer=Answer object sections, symbols, and disassembly shape through LLVM. trust=Trust LLVM backend output plus parser warnings/raw blocks for unsupported regions. next=Use llvmreadobj for headers/imports/debug hints. | Use pecalls or pesig for PE-focused call/function triage.
|
||||
llvmreadobj: Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM backend discovery. Better than: heavy binary viewers or raw llvm-readobj output when you need a bounded COFF/PE header, import/export, and debug/PDB summary. Usage: `llvmreadobj [OPTIONS] [PATH...]` Example: `llvmreadobj .\target\release-fast\binmeta.exe --json | ConvertFrom-Json` Guided: answer=Answer COFF/PE headers, sections, imports, exports, and debug hints through LLVM. trust=Trust LLVM backend exit status and parsed blocks; raw blocks preserve unparsed details. next=Use peimports/peexports for PE-focused grouping. | Use llvmobjdump when code layout or disassembly is needed.
|
||||
llvmnm: List and classify object symbols through LLVM nm output. Better than: raw symbol-table dumps when you need stable symbol rows with kind, address, size, object/archive prefix, and source-line hints. Usage: `llvmnm [OPTIONS] [PATH...]` Example: `llvmnm .\target\release-fast\binmeta.exe --defined-only --json | ConvertFrom-Json` Guided: answer=Answer defined/undefined symbols with stable LLVM nm rows. trust=Trust POSIX-format symbol parsing and backend stderr tails. next=Use llvmobjdump for disassembly around symbols. | Use llvmreadobj for object headers and debug hints.
|
||||
peexports: Inspect export surfaces, spot forwarded symbols, filter by name or ordinal, and use `report_quality`/`next_actions` to decide the next PE pass. Better than: manual PE export-table browsing when you want names, ordinals, RVA/VA, forwarders, and guided follow-up commands without opening a heavy PE debugger. Usage: `peexports [OPTIONS] [PATH...]` Example: `peexports C:\Windows\System32\kernel32.dll --forwarders-only --json | ConvertFrom-Json` Guided: answer=Answer PE export names, ordinals, RVAs/VAs, forwarders, and entrypoint hints. trust=Trust PE export table parsing plus report_quality evidence and limitations. next=Use peimports to inspect dependencies. | Use llvmreadobj --exports to cross-check LLVM output.
|
||||
peimports: Inspect imports by library, name, or category, quickly separate filesystem, registry, device I/O, NT, and network APIs, then follow emitted `next_actions`. Better than: ad-hoc import-table triage when you need API families grouped into human-friendly categories with immediate callsite and role follow-ups. Usage: `peimports [OPTIONS] [PATH...]` Example: `peimports .\target\release-fast\portping.exe --category device_io --json | ConvertFrom-Json` Guided: answer=Answer imported APIs grouped by library and API category. trust=Trust PE import table parsing plus report_quality evidence and limitations. next=Use pecalls on interesting categories. | Use drvshape for driver-like/native profiles.
|
||||
pecalls: Extract callsites for one or more imported APIs or API categories from LLVM objdump text and inspect `report_quality.limitations` before treating it as exhaustive. Better than: guessing import callsites from raw disassembly when you want direct IAT matches plus trust metadata around best-effort disassembly parsing. Usage: `pecalls [OPTIONS] [PATH...]` Example: `pecalls .\target\release-fast\portping.exe --api WSAStartup --json | ConvertFrom-Json` Guided: answer=Answer direct imported API callsites found through LLVM disassembly. trust=Trust direct IAT-target matches; report_quality limitations mark disassembly truncation or gaps. next=Use peimports to choose categories. | Use pesig to place callsites inside functions.
|
||||
pesig: Infer function boundaries, source hints, and calling conventions from PE text and metadata, then pivot to imports, callsites, or raw objdump via `next_actions`. Better than: manual function-boundary and calling-convention inference when you need a quick v1 signal with explicit confidence and next-step context. Usage: `pesig [OPTIONS] [PATH...]` Example: `pesig .\target\release-fast\portping.exe --min-confidence medium --json | ConvertFrom-Json` Guided: answer=Answer likely PE function boundaries and calling-convention hints. trust=Trust confidence/evidence per function and report_quality for parse completeness. next=Use pecalls to connect functions to APIs. | Use llvmobjdump for raw disassembly context.
|
||||
pestrrefs: Scan ASCII or UTF-16LE strings, report direct references from LLVM disassembly, and use `next_actions` to connect strings to imports, callsites, or IOCTL constants. Better than: opening a disassembler and a string viewer separately when you need string hits with direct xrefs and a clear next triage command. Usage: `pestrrefs [OPTIONS] [PATH...]` Example: `pestrrefs .\target\release-fast\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json` Guided: answer=Answer strings and direct code references in PE files. trust=Trust direct VA/range xrefs; unresolved counts are not guessed. next=Use peimports to connect strings to APIs. | Use ioctlscan for device-control constants.
|
||||
drvshape: Summarize likely WDM, KMDF, NDIS, minifilter, or native driver traits, surface heuristic driver hints, and treat `report_quality` as the trust boundary. Better than: guessing the driver role from imports and exports when you want a compact Windows driver profile with IOCTL/import/callsite follow-ups already suggested. Usage: `drvshape [OPTIONS] [PATH...]` Example: `drvshape C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json` Guided: answer=Answer likely Windows driver role, subsystem, imports, exports, and heuristic hints. trust=Trust role hints as heuristics, not vulnerability conclusions; report_quality shows evidence. next=Use ioctlscan to decode CTL_CODE candidates. | Use pecalls --category device_io for dispatch/callsite evidence.
|
||||
ioctlscan: Scan PE bytes and disassembly-adjacent data for likely IOCTL constants, decode their fields, and use `report_quality` to separate strong hits from heuristic candidates. Better than: searching for Windows IOCTL constants by hand when you want decoded CTL_CODE fields, code locations, and suggested role/callsite/string follow-ups. Usage: `ioctlscan [OPTIONS] [PATH...]` Example: `ioctlscan C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json` Guided: answer=Answer probable IOCTL constants and decoded CTL_CODE fields. trust=Trust confidence/evidence per candidate; raw byte hits are heuristic until tied to code context. next=Use drvshape to confirm driver role. | Use pestrrefs or pecalls for surrounding evidence.
|
||||
binmeta: Inspect file metadata, Windows PE basics, version/company/product identity, embedded Authenticode certificate tables, WinTrust status, catalog signing, signer certificate subjects, chains, timestamps, and expiry hints. Better than: opening heavy PE tooling or shelling out to signature utilities when you first need binary identity, PE basics, version resources, and Windows signing status. Usage: `binmeta [OPTIONS] [PATH...]` Example: `binmeta .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json` Guided: answer=Answer file identity, PE basics, version resource fields, company/product names, signature status, embedded-vs-catalog signing, signer subject, certificate chain, timestamp, and expiry fields before deeper binary analysis. trust=Trust goblin PE/resource parsing for local structure and Windows WinTrust/catalog status on Windows; signature failures are reported as metadata, not command failures. On non-Windows, trust only embedded certificate table presence and treat WinTrust fields as unsupported. next=Use peimports or llvmreadobj for deeper PE detail after identity is known. | Use drvshape or ioctlscan for signed drivers and native/system binaries. | Use stringscan or pestrrefs when identity/version metadata is missing or suspicious.
|
||||
fileprobe: Classify files as text, binary, generated, minified, test, vendor, and more, including encoding, BOM, and newline diagnostics. Better than: blindly opening files when you need a fast read-worthiness, encoding, or newline check first. Usage: `fileprobe [OPTIONS] [PATH...]` Example: `fileprobe .\src\main.rs` Guided: answer=Answer whether a path is text, binary, generated, minified, vendor, or worth opening. trust=Trust bounded sniffing, encoding, newline, and classification diagnostics. next=Use outline or chunkcat for readable text. | Use binmeta or stringscan for binary files.
|
||||
outline: List top-level code or config structure. Better than: scrolling whole files when you only need the structure. Usage: `outline [OPTIONS] <PATH...>` Example: `outline <PATH>` Guided: answer=Answer top-level structure of source or config files. trust=Trust parser-supported outlines and explicit unsupported-file diagnostics. next=Use defsnip for exact definitions. | Use refs or codeshape for broader symbol maps.
|
||||
codeshape: Map a codebase into files plus AST-backed declarations and signatures from the shared `codeindex` engine. Better than: plain `tree` output when you need internal declarations and signatures without dumping full source files. Usage: `codeshape [OPTIONS] [PATH...]` Example: `codeshape --max-depth 1 --limit-per-file 8 . --json | ConvertFrom-Json` Guided: answer=Answer repository file/declaration shape with AST-backed summaries. trust=Trust codeindex parser results and skipped-file diagnostics. next=Use defsnip to extract definitions. | Use refs to find use sites.
|
||||
refs: Find exact symbol references or caller definitions through the shared `codeindex` engine with text fallback. Better than: falling back to raw `rg` when you need exact use-sites or caller summaries for a known symbol. Usage: `refs [OPTIONS] <SYMBOL> [PATH...] | refs [OPTIONS] --at <PATH:LINE[:COL]> [PATH...]` Example: `refs helper <PATH>` Guided: answer=Answer symbol references or callers across source files. trust=Trust codeindex hits and caller grouping under the selected roots. next=Use hitsnip to expand hit context. | Use defsnip for definition bodies.
|
||||
snip: Extract precise snippets from files or stdin. Better than: dumping whole files when you only need exact lines, matches, or symbols. Usage: `snip [OPTIONS] [PATH...]` Example: `snip --lines 16:27 <PATH>` Guided: answer=Answer exact bounded source/text snippets by line, match, or symbol. trust=Trust line numbers and bounded extraction; binary or missing paths are rejected. next=Use hitsnip after rg for multiple hits. | Use ctxpack to bundle snippets.
|
||||
defsnip: Extract full AST-backed definitions by exact symbol name through the shared `codeindex` engine. Better than: line-number snippets when you need the full function, class, or method body even after nearby edits move the lines. Usage: `defsnip [OPTIONS] <SYMBOL> [PATH...]` Example: `defsnip build_report . --json | ConvertFrom-Json` Guided: answer=Answer full AST-backed definition blocks for symbols. trust=Trust codeindex definitions and language support; no match means broaden symbol/root. next=Use refs for callers/use sites. | Use ctxpack to package the definition with nearby context.
|
||||
ctxpack: Pack files, snippets, hits, diagnostics, or definition JSON into compact context blocks. Better than: hand-assembling ad-hoc prompt context from files, hits, diagnostics, and definitions. Usage: `ctxpack [OPTIONS] [INPUT...]` Example: `ctxpack <PATH>` Guided: answer=Answer compact prompt-ready context from files, snippets, hits, and diagnostics. trust=Trust included path and byte/line caps; review omitted/truncated sections for scope. next=Use fileprobe/codeshape before packing broad roots. | Use diagpick or hitsnip to feed focused evidence.
|
||||
chunkcat: Read large text files in bounded chunks, including quick tail-style log windows. Better than: huge file dumps when you need deterministic windows. Usage: `chunkcat [OPTIONS] [PATH...]` Example: `chunkcat .\BepInEx\LogOutput.log --max-lines 20 --tail` Guided: answer=Answer a bounded chunk or inventory of a large text file. trust=Trust chunk indices, line ranges, and binary detection. next=Use snip when you know the exact line range. | Use hitsnip to expand search hits into chunks.
|
||||
hitsnip: Turn search hits into compact snippets or promote them to enclosing definitions. Better than: raw `rg` hit lists when you need merged readable context or the enclosing definition instead of a tiny window. Usage: `hitsnip [OPTIONS] [HIT...]` Example: `rg -nH "helper" <PATH> | hitsnip --def` Guided: answer=Answer merged snippets around rg-style search hits. trust=Trust hit parsing and merge ranges; malformed hit lines are reported. next=Use rg -nH to feed hits. | Use defsnip when the hit is inside a known symbol.
|
||||
diagpick: Extract compiler or runtime diagnostics from noisy logs, with optional snippets and enclosing definitions. Better than: reading full logs when you need the actionable errors first and want direct source or definition context. Usage: `diagpick [OPTIONS] [PATH...]` Example: `diagpick <PATH> --def` Guided: answer=Answer actionable diagnostics extracted from compiler/build/log text. trust=Trust recognized diagnostic formats and preserved source context. next=Use snip on referenced files/lines. | Use runprobe to capture the failing command reproducibly.
|
||||
logshape: Group recurring log lines into templates. Better than: reading repetitive logs line by line when you need the dominant patterns. Usage: `logshape [OPTIONS] [PATH...]` Example: `logshape <PATH>` Guided: answer=Answer repeated log templates, incidents, and message clusters. trust=Trust grouping counts and examples; rare lines may stay as individual templates. next=Use diagpick for actionable errors. | Use jsonlgrep when logs are structured JSONL.
|
||||
stringscan: Extract and classify high-signal strings from binaries or blobs. Better than: a full reverse-engineering pass when you first need identity clues from strings. Usage: `stringscan [OPTIONS] [PATH...]` Example: `stringscan <PATH>` Guided: answer=Answer strings and classified hints from arbitrary blobs. trust=Trust extracted string offsets and classification labels; encoding limits are explicit. next=Use binmeta first for binary identity. | Use pestrrefs for PE strings with xrefs.
|
||||
toon: Convert between JSON and TOON. Better than: verbose JSON when you want a denser structured text form. Usage: `toon [OPTIONS] [PATH]` Example: `'{"ok":true}' | toon` Guided: answer=Answer compact model-readable TOON from JSON/JSONL or decode TOON back. trust=Trust parser/encoder diagnostics and document wrapper metadata. next=Use native --toon on Mercury producers when available. | Use cjson/jsonshape before converting questionable JSON.
|
||||
csvshape: Summarize large CSV or TSV files into compact schema/bounded stats, or diff two CSV shapes. Better than: opening huge CSV or TSV files when you first need the columns, rough types, blanks, example values, or a shape diff. Usage: `csvshape [OPTIONS] [PATH...] | csvshape [OPTIONS] diff <BEFORE> <AFTER>` Example: `csvshape diff before.csv after.csv --json | ConvertFrom-Json` Guided: answer=Answer CSV/TSV delimiter, columns, row counts, and schema differences. trust=Trust parsed rows under the detected or requested delimiter. next=Use jsonshape after converting CSV to JSON externally. | Use config or sqlshape when CSV describes configuration/data imports.
|
||||
sqliteshape: Inspect SQLite databases read-only with compact schema/table summaries, or diff two SQLite shapes. Better than: dropping into an interactive SQLite shell when you only need schema, sample rows, light table stats, or a shape diff. Usage: `sqliteshape [OPTIONS] [PATH...] | sqliteshape [OPTIONS] diff <BEFORE> <AFTER>` Example: `'C:\data\events.db' | sqliteshape --input-format lines --json | ConvertFrom-Json` Guided: answer=Answer SQLite tables, columns, indexes, triggers, and schema diffs. trust=Trust SQLite catalog queries against the selected database file. next=Use sqlshape for normalized cross-engine reports. | Use jsonshape/csvshape on exported data samples.
|
||||
sqlshape: Inspect PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, or DuckDB schemas read-only with redacted connection sources and normalized cross-engine diffs. Better than: hand-writing per-engine catalog queries or exposing raw connection strings when you need a normalized cross-database schema report or diff. Usage: `sqlshape [OPTIONS] --url <CONNECTION> | sqlshape [OPTIONS] diff --before-url <CONNECTION> --after-url <CONNECTION>` Example: `sqlshape --engine sqlite --url <PATH> --json | ConvertFrom-Json` Guided: answer=Answer normalized SQL schema across SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, or DuckDB. trust=Trust engine-specific introspection and redacted connection reporting. next=Use sqliteshape for SQLite-specific detail. | Use config to inspect connection/config files safely.
|
||||
unityasset: Inspect Unity serialized assets, bundles, and YAML objects, then trace refs, dump fields, or extract payloads such as TextAsset, MonoScript, AudioClip, and VideoClip. Better than: opening a heavy Unity GUI tool when you first need an index, object refs, field dump, or a quick extraction path for assets, scripts, audio, or video. Usage: `unityasset [OPTIONS] index [PATH...] | unityasset [OPTIONS] refs <OBJECT_ID> [PATH...] | unityasset [OPTIONS] dump <OBJECT_ID> [PATH...] | unityasset [OPTIONS] extract <OBJECT_ID> [PATH...] [--output-dir <DIR>]` Example: `unityasset index 'C:\game\Game_Data'` Guided: answer=Answer Unity asset indexes, object dumps, references, and extraction writes. trust=Trust parsed serialized files/bundles and explicit unresolved reference rows. next=Use unitydiag for runtime/log symptoms. | Use asmtype/asmflow for managed script assemblies.
|
||||
unityprobe: Install and query a read-only BepInEx bridge for live scenes, objects, and static state in a running Mono Unity game on Windows. Better than: hand-writing BepInEx reflection plugins or one-off named-pipe helpers when you only need a read-only runtime snapshot from a Mono Unity game. Usage: `unityprobe [OPTIONS] <SUBCOMMAND> [ARGS...]` Example: `unityprobe install 'C:\game'` Guided: answer=Answer read-only Unity runtime bridge status, object search, and inspection. trust=Trust explicit bridge install/status and Windows named-pipe reachability. next=Use unitydiag when runtime logs explain bridge issues. | Use unityasset for offline assets.
|
||||
unitydiag: Summarize Unity Player.log and BepInEx logs into grouped incidents, normalized messages, and domain-aware failure summaries. Better than: reading raw Player.log and BepInEx logs end to end when you need the repeated incidents, top frames, and mod-vs-framework blame split first. Usage: `unitydiag [OPTIONS] [PATH...]` Example: `unitydiag 'C:\Users\example\AppData\LocalLow\Studio\Game\Player.log'` Guided: answer=Answer Unity/BepInEx log incidents, grouped frames, and mod/runtime warnings. trust=Trust discovered log paths, grouping counts, and preserved stack snippets. next=Use asmref diagnose for plugin dependency issues. | Use unityprobe when live object state is needed.
|
||||
envdiff: Snapshot, diff, or run commands while reporting environment-variable changes. Better than: hand-comparing environment variables before and after a script, especially around PATH pollution and batch wrappers. Usage: `envdiff [OPTIONS] run --shell cmd|pwsh|raw -- <COMMAND...>` Example: `envdiff run --shell cmd -- .\scripts\set-env.cmd` Guided: answer=Answer environment variable changes before/after a command or between snapshots. trust=Trust captured before/after maps and PATH segment deltas. next=Use pathshadow after PATH changes. | Use sysshape for broader shell/tool inventory.
|
||||
proctree: Inspect whole-system, rooted, matched, or command-run Windows process trees in AI-friendly form; use --match to filter by image name or command line. Better than: flat process lists when you need parent-child context, short command lines, and lingering orphan hints. Usage: `proctree [OPTIONS] system|root <PID>|run -- <COMMAND...>` Example: `proctree system --match 'pwsh|Mercury' --include-cmdline` Guided: answer=Answer process trees, rooted processes, and command ancestry. trust=Trust OS process snapshots at capture time; short-lived processes may disappear. next=Use portunlock for port owners. | Use runprobe to capture command execution shape.
|
||||
sysshape: Capture a compact local system and tool inventory for AI-friendly triage, including shell hints, path-like duplication, and probe status. Better than: asking users ad-hoc setup questions or checking versions one tool at a time when you need a compact local machine inventory first. Usage: `sysshape [OPTIONS]` Example: `sysshape --json --env safe --group shell | ConvertFrom-Json` Guided: answer=Answer machine, shell, environment, and tool inventory shape. trust=Trust detected command paths/versions and grouped environment metadata. next=Use pathshadow for a specific executable winner. | Use envdiff around commands that mutate the environment.
|
||||
runprobe: Run one command and capture exit code, duration, timeout status, and bounded output tails. Better than: reading fragile shell text when what you really need is the stable result object for one command run. Usage: `runprobe [OPTIONS] -- <COMMAND...>` Example: `runprobe --shell raw -- cmd /d /s /c "exit 0"` Guided: answer=Answer command exit code, duration, stdout/stderr tails, and timeout behavior. trust=Trust captured process result and bounded output tails. next=Use diagpick on captured stderr/stdout. | Use envdiff run when environment mutation matters.
|
||||
await: Wait for a path, TCP target, HTTP endpoint, or command condition with bounded polling. Better than: writing ad-hoc polling loops for files, ports, HTTP endpoints, or repeat-until-success commands. Usage: `await [OPTIONS] path <PATH> [--state exists|missing] | await [OPTIONS] port <TARGET> | await [OPTIONS] http <URL> [--status <CODE>] | await [OPTIONS] run [--shell <MODE>] [--cwd <PATH>] [--exit-code <CODE>] [--tail-bytes <COUNT>] -- <COMMAND...>` Example: `await path .\target\ready.flag` Guided: answer=Answer whether a path, port, HTTP endpoint, or command became ready before timeout. trust=Trust polling attempts, final state, and timeout status. next=Use portping for one-shot endpoint detail. | Use runprobe for command readiness probes.
|
||||
argv: Quote argv for `pwsh` or `cmd`, or inspect what a shell actually passed to a native process. Better than: guessing how PowerShell or cmd really passed arguments to a native process. Usage: `argv quote --shell <pwsh|cmd|raw> [VALUE...] | argv inspect [--json] --shell <pwsh|cmd|raw> [VALUE...]` Example: `argv quote --shell pwsh -- git commit -m "two words"` Guided: answer=Answer how arguments should be quoted or how a shell actually passes them. trust=Trust helper round-trips for the selected shell/platform. next=Use runprobe to execute the quoted command. | Use msudo status before privileged shell wrapping.
|
||||
config: Read, inspect, list, set, or delete config values in JSON, YAML, TOML, env, and INI files. Better than: fighting `jq` or hand-editing config files when you need safe slash-pointer reads or edits across common formats. Usage: `config [OPTIONS] [PATH] | config [OPTIONS] <get|inspect|ls|set|delete> <PATH> [POINTER] [VALUE]` Example: `config get .\package.json /version` Guided: answer=Answer get/set/delete operations over JSON/YAML/TOML/env/INI config paths. trust=Trust parser-specific diagnostics and structured edit reports. next=Use fileprobe before editing unknown config files. | Use jsonshape after JSON config changes.
|
||||
gitshape: Summarize Git status or diff shape into concise AI-friendly file, line, and touched-symbol reports. Better than: reading raw `git status` and diff noise when you first need compact status counters or changed-file summaries. Usage: `gitshape [OPTIONS] [PATH] | gitshape [OPTIONS] status [PATH] | gitshape [OPTIONS] diff [REVISION_A] [REVISION_B]` Example: `gitshape .` Guided: answer=Answer git status, branch, diff, and repository change shape. trust=Trust git command output and explicit revision/path filters. next=Use reposhape to connect git changes to ecosystems. | Use ctxpack or hitsnip for changed-file handoff.
|
||||
reposhape: Detect repository ecosystems, manifests, command entrypoints, and CI hints in one pass. Better than: manually browsing an unfamiliar repo when you first need the ecosystems, manifests, commands, and CI entrypoints. Usage: `reposhape [OPTIONS] [PATH]` Example: `reposhape .` Guided: answer=Answer repository ecosystems, manifests, entrypoints, and project layout. trust=Trust manifest detection under depth/hidden filters and parse diagnostics. next=Use codeshape for source declarations. | Use dotnetshape/sqlshape/gitshape for ecosystem-specific detail.
|
||||
dotnetshape: Inspect .csproj, Directory.Build.props/targets, Directory.Packages.props, project references, package versions, and .NET-specific project graph diagnostics. Better than: opening a .NET repo one file at a time when you first need project graph shape, shared MSBuild inheritance, package references, and build-shape warnings. Usage: `dotnetshape [OPTIONS] [PATH]` Example: `dotnetshape .` Guided: answer=Answer .NET project graph, inherited MSBuild properties, package references, and diagnostics. trust=Trust static XML parsing without invoking MSBuild; generated/effective values are labeled. next=Use asmref diagnose on built assemblies. | Use config to inspect Directory.Build or props files directly.
|
||||
unlock: Identify file lockers and perform unlock-aware file actions on Windows. Better than: ad-hoc PowerShell probing when a file is busy, locked, or refuses delete, move, rename, or copy. Usage: `unlock [OPTIONS] who <PATH...> | unlock [OPTIONS] free <PATH...> | unlock [OPTIONS] move <PATH> <DEST> | unlock [OPTIONS] rename <PATH> <NEW_NAME> | unlock [OPTIONS] delete <PATH...> | unlock [OPTIONS] copy <PATH> <DEST>` Example: `unlock who .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results` Guided: answer=Answer which processes lock files and perform unlock-aware copy/move/delete actions. trust=Trust restart-manager/handle-scan evidence and post-action filesystem checks. next=Use proctree on blocker PIDs. | Use recent after cleanup to confirm generated artifacts.
|
||||
@@ -0,0 +1,777 @@
|
||||
{
|
||||
"title": "Mercury Toolbox AI Prompt",
|
||||
"overview": [
|
||||
"Mercury Toolbox is a set of small, focused Windows and PowerShell-friendly CLI tools for fast local inspection, transformation, and triage.",
|
||||
"The toolbox is optimized for AI-assisted terminal work: compact text by default, stable machine-readable output through `--json`, native model-readable TOON through `--toon`, and easy piping between commands.",
|
||||
"Prefer these tools when you need a narrow binary that explains a local situation quickly without opening a heavy UI or dumping unnecessary text."
|
||||
],
|
||||
"selection_rules": [
|
||||
"Prefer Mercury first when the task is local inspection, shaping, or triage.",
|
||||
"Prefer compact text. Use `--json` when the next step parses output, and use `--toon` or `--format toon` when structured output is meant for an AI/model to read.",
|
||||
"Pipe external JSON into `toon` only when the producer is not a Mercury tool; TOON auto-detects JSON and emits denser TOON by default.",
|
||||
"Set `$env:MERCURY_OUTPUT='json'` or `$env:MERCURY_OUTPUT='toon'` when most commands in the session should default to that structured format.",
|
||||
"Prefer stdin and pipelines over re-reading large files.",
|
||||
"Prefer `fileprobe`, `outline`, `snip`, `chunkcat`, `hitsnip`, `defsnip`, `codeshape`, `refs`, and `ctxpack` over raw `Get-Content`, `cat`, or whole-file dumps.",
|
||||
"Every tool has guided triage metadata in the generated prompt and skill catalog; PE deep-analysis tools also emit runtime `answer=`, `trust`, `report_quality`, and `next_actions` fields.",
|
||||
"For every command, read the generated `guided_triage` answer, trust basis, and next actions before inventing a new path.",
|
||||
"When you are unsure which command to run next, prefer the emitted `next_actions` before inventing an ad-hoc pipeline.",
|
||||
"Use these tools with modern CLI companions such as `rg`, `fd`, `jq`, `yq`, `bat`, `sd`, `xh`, `tokei`, `eza`, `procs`, `dust`, `hyperfine`, `hexyl`, `zoxide`, `lazygit`, `delta`, and PowerShell.",
|
||||
"Prefer `mhash` for local hashing, OpenHashTab-class algorithm discovery, JSONL manifest generation and verification, and quick hash throughput benches; pair its JSON/JSONL output with `jq` and compare external command timing with `hyperfine` when needed.",
|
||||
"Prefer `rg` over recursive `grep` or `Select-String`, `fd` over recursive `Get-ChildItem`, `bat` over raw `Get-Content`, `jq` or `yq` over manual JSON or YAML parsing, and `xh` over `curl` for quick HTTP checks."
|
||||
],
|
||||
"tools": {
|
||||
"cjson": {
|
||||
"why": "pretty multi-line JSON when you need compact stable output and optional key sorting.",
|
||||
"use_when": "Compact JSON or JSONL before piping, diffing, or model input.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether JSON/JSONL can be compacted cleanly and deterministically.",
|
||||
"trust": "Trust the JSON parser result and document count; invalid JSON is reported before compaction.",
|
||||
"next_actions": [
|
||||
"Run jsonshape on the compacted payload when you need schema shape.",
|
||||
"Pipe to jq or toon for projection/model handoff."
|
||||
]
|
||||
}
|
||||
},
|
||||
"ison": {
|
||||
"why": "verbose JSON when a deterministic compact ISON representation is easier to scan or diff.",
|
||||
"use_when": "Convert between JSON and ISON records for compact structured handoff.",
|
||||
"prompt_example": "ison .\\fixtures\\json-family\\ison\\users.json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether JSON can round-trip through compact ISON for handoff.",
|
||||
"trust": "Trust successful parser/encoder output; use JSON mode when a tool must consume it next.",
|
||||
"next_actions": [
|
||||
"Use isonl for line-oriented streams.",
|
||||
"Use toon when the next consumer is an AI model."
|
||||
]
|
||||
}
|
||||
},
|
||||
"isonl": {
|
||||
"why": "manual JSONL splitting when line-oriented ISON records are better for streaming or model input.",
|
||||
"use_when": "Convert between JSONL and ISONL line records.",
|
||||
"prompt_example": "isonl --from jsonl --to isonl .\\fixtures\\json-family\\ison\\users.isonl",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether JSONL/ISONL records can be converted as a stream.",
|
||||
"trust": "Trust per-line parser diagnostics and document counts; malformed lines stop the conversion.",
|
||||
"next_actions": [
|
||||
"Pipe into jsonlgrep for filtering.",
|
||||
"Use cjson or toon for downstream compact handoff."
|
||||
]
|
||||
}
|
||||
},
|
||||
"zon": {
|
||||
"why": "hand-written compact table encodings when you need Zero Overhead Notation interop without Node tooling.",
|
||||
"use_when": "Convert JSON or JSONL to Zero Overhead Notation and back.",
|
||||
"prompt_example": "zon .\\fixtures\\json-family\\zon\\person.json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether JSON/JSONL can convert to or from Zero Overhead Notation.",
|
||||
"trust": "Trust parser diagnostics and wrapper metadata for document count and target format.",
|
||||
"next_actions": [
|
||||
"Use jsonshape after decoding to validate shape.",
|
||||
"Use toon for model-facing structured summaries."
|
||||
]
|
||||
}
|
||||
},
|
||||
"tonl": {
|
||||
"why": "one-off scripts for compact JSON ETL, validation, query, indexing, or streaming filters.",
|
||||
"use_when": "Encode, decode, query, validate, index, stream-query, and ETL JSON-backed TONL data.",
|
||||
"prompt_example": "tonl query --where active=true .\\fixtures\\json-family\\tonl\\records.tonl",
|
||||
"guided_triage": {
|
||||
"answer": "Answer filtered TONL records, validation status, indexes, or ETL conversion results.",
|
||||
"trust": "Trust explicit validation/query diagnostics; streaming mode reports record-level failures.",
|
||||
"next_actions": [
|
||||
"Use jsonlgrep for simple JSONL filtering before TONL conversion.",
|
||||
"Use cjson or toon for compact handoff."
|
||||
]
|
||||
}
|
||||
},
|
||||
"jsonlgrep": {
|
||||
"why": "ad-hoc `jq` for simple field filters, projections, counts, and regex matches.",
|
||||
"use_when": "Filter JSONL logs, single-line JSON arrays, or structured event streams by field.",
|
||||
"prompt_example": "recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which JSONL records match field, regex, or projection filters.",
|
||||
"trust": "Trust parsed JSON records and explicit malformed-line diagnostics.",
|
||||
"next_actions": [
|
||||
"Use jsonshape on matched records to inspect structure.",
|
||||
"Use toon or cjson for compact AI handoff."
|
||||
]
|
||||
}
|
||||
},
|
||||
"mhash": {
|
||||
"why": "PowerShell Get-FileHash loops, GUI hash tabs, ad-hoc checksum scripts, or manual benchmark harnesses when you need OpenHashTab-class algorithm coverage, manifests, verification, JSON/JSONL, and throughput telemetry in one local CLI.",
|
||||
"use_when": "Compute local file hashes across the OpenHashTab-class matrix, list algorithms, hash with `--all` or explicit multi-algorithm sets, produce JSONL manifests, verify manifests, or benchmark hash throughput.",
|
||||
"prompt_example": "mhash --algorithm sha256,blake3-256,xxh3-128 .\\dist\\MercuryToolbox.zip --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer file identity, checksum, manifest verification, or hash throughput questions.",
|
||||
"trust": "Trust algorithm labels, manifest verification status, and per-file error rows.",
|
||||
"next_actions": [
|
||||
"Use fileprobe first when the file type is unknown.",
|
||||
"Use jsonlgrep or jq to filter manifest rows."
|
||||
]
|
||||
}
|
||||
},
|
||||
"jsonshape": {
|
||||
"why": "opening raw payloads when you first need the shape, key paths, or a schema diff.",
|
||||
"use_when": "Summarize JSON or JSONL into path/type stats, or diff two shape reports.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer the key paths, types, counts, and shape differences in JSON/JSONL.",
|
||||
"trust": "Trust reported path/type counts when parsing succeeds; review diff diagnostics for drift.",
|
||||
"next_actions": [
|
||||
"Use jsonlgrep to isolate records before reshaping.",
|
||||
"Use cjson to normalize payloads before comparing."
|
||||
]
|
||||
}
|
||||
},
|
||||
"recent": {
|
||||
"why": "manual directory scans when you just need the freshest files and `.gitignore` awareness.",
|
||||
"use_when": "List recently changed files or directories.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which files or directories changed recently.",
|
||||
"trust": "Trust timestamp filters and gitignore-aware discovery within the selected root.",
|
||||
"next_actions": [
|
||||
"Pipe paths into fileprobe or outline.",
|
||||
"Use hitsnip or ctxpack after narrowing files."
|
||||
]
|
||||
}
|
||||
},
|
||||
"pathshadow": {
|
||||
"why": "guessing PATH order when the wrong executable is being picked.",
|
||||
"use_when": "Show which executable wins and which ones are shadowed.",
|
||||
"prompt_example": "pathshadow python npm --shell powershell --summary --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which executable wins on PATH and which candidates are shadowed.",
|
||||
"trust": "Trust resolved filesystem candidates and shell-aware summary rows.",
|
||||
"next_actions": [
|
||||
"Use sysshape --group shell for broader environment context.",
|
||||
"Use argv quote when command invocation quoting is suspicious."
|
||||
]
|
||||
}
|
||||
},
|
||||
"portping": {
|
||||
"why": "jumping between multiple network tools for quick TCP and HTTP reachability checks.",
|
||||
"use_when": "Probe ports or health endpoints with timings.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether a TCP/HTTP/HTTPS endpoint is reachable and how long it took.",
|
||||
"trust": "Trust direct connection/status timing; failures distinguish DNS, connect, and HTTP states.",
|
||||
"next_actions": [
|
||||
"Use portunlock when a local port is unexpectedly occupied.",
|
||||
"Use await port/http to wait for readiness."
|
||||
]
|
||||
}
|
||||
},
|
||||
"portunlock": {
|
||||
"why": "guessing which process owns a port or hand-writing `netstat` and kill loops when a local listener refuses to go away.",
|
||||
"use_when": "Show and free local TCP or UDP port owners on Windows.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which process owns a local TCP/UDP port and optionally free it.",
|
||||
"trust": "Trust OS port snapshots and post-action verification rows.",
|
||||
"next_actions": [
|
||||
"Use proctree on the owning PID before freeing.",
|
||||
"Use portping after freeing or restarting a listener."
|
||||
]
|
||||
}
|
||||
},
|
||||
"msudo": {
|
||||
"why": "guessing whether Windows elevation relay support is available, or hand-writing `Start-Process -Verb RunAs` wrappers when you first need the current privilege status.",
|
||||
"use_when": "Top-level high-risk command: inspect Windows elevation relay status, token state, active session state, and host availability before any privileged launch.",
|
||||
"prompt_example": "msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated",
|
||||
"guided_triage": {
|
||||
"answer": "Answer Windows elevation, token, relay, and launch-shape questions.",
|
||||
"trust": "Trust status discovery before launch; treat run actions as high risk and explicit.",
|
||||
"next_actions": [
|
||||
"Start with msudo status --json.",
|
||||
"Use argv quote before privileged shell wrapping."
|
||||
]
|
||||
}
|
||||
},
|
||||
"asmtype": {
|
||||
"why": "manual reflection or ad-hoc PowerShell when you first need the type map from a managed assembly.",
|
||||
"use_when": "List managed assembly types and filter them by name, namespace, base type, interface, or matching members, with optional user-code-only screening.",
|
||||
"prompt_example": "asmtype .\\fixtures\\managed\\bin\\GameAssembly.dll --with-member-match 'Build|Launch' --show-matched-members --pick full_name,base_type,matched_members --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which managed types match name, inheritance, interface, or member intent.",
|
||||
"trust": "Trust metadata enumeration from the target assembly; broaden filters when no matches return.",
|
||||
"next_actions": [
|
||||
"Pipe JSONL into asmmember.",
|
||||
"Use asmflow find/xref when behavior matters."
|
||||
]
|
||||
}
|
||||
},
|
||||
"asmmember": {
|
||||
"why": "long reflection scripts when you need methods, fields, and properties from a known managed type.",
|
||||
"use_when": "Inspect managed type members with binding filters and compact signatures, including JSONL handoff from `asmtype` and user-code-only filtering.",
|
||||
"prompt_example": "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 --pick type_name,name,visibility,signature --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which methods, fields, and properties exist on selected managed types.",
|
||||
"trust": "Trust assembly metadata and binding filters; use non-public filters intentionally.",
|
||||
"next_actions": [
|
||||
"Use asmflow body for IL details.",
|
||||
"Use asmapi diff when comparing versions."
|
||||
]
|
||||
}
|
||||
},
|
||||
"asmref": {
|
||||
"why": "guessing missing managed dependencies when you need a fast reference, resolution, or Unity/Rocket plugin closure diagnosis pass.",
|
||||
"use_when": "Inspect managed assembly references, check whether they resolve from local directories, or run `diagnose` to report closure risks such as missing references, same-name version/token conflicts, winning DLLs, test-only leaks, and obvious MissingMethod/TypeLoad hazards.",
|
||||
"prompt_example": "asmref diagnose .\\fixtures\\managed\\bin\\GameAssembly.dll --resolve-dir .\\fixtures\\managed\\bin --format toon",
|
||||
"guided_triage": {
|
||||
"answer": "Answer managed references, resolution status, and dependency closure risks.",
|
||||
"trust": "Trust resolved candidates and risk tiers; explicit resolve dirs define the runtime universe.",
|
||||
"next_actions": [
|
||||
"Run asmref diagnose for closure risks.",
|
||||
"Use asmapi diff on risky version changes."
|
||||
]
|
||||
}
|
||||
},
|
||||
"asmapi": {
|
||||
"why": "manual reflection diffs or brittle spreadsheet comparisons when you need to know what managed API changed between two DLL versions.",
|
||||
"use_when": "Compare two managed assemblies for added or removed public types, removed methods, signature changes, and MissingMethodException risks, with optional internal/all visibility.",
|
||||
"prompt_example": "asmapi diff .\\old\\0Harmony.dll .\\new\\0Harmony.dll --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer public API differences between managed assemblies.",
|
||||
"trust": "Trust metadata comparison under the chosen visibility scope.",
|
||||
"next_actions": [
|
||||
"Use asmref diagnose to connect API drift to dependency closure.",
|
||||
"Use asmmember on removed or changed types."
|
||||
]
|
||||
}
|
||||
},
|
||||
"asmflow": {
|
||||
"why": "ad-hoc IL dump scripts or manual dnSpy browsing when you need callers, callees, field access, or string literals from a managed method quickly.",
|
||||
"use_when": "Inspect managed method bodies, IL summaries, and cross-references for Unity and general .NET reverse-engineering flows.",
|
||||
"prompt_example": "asmflow xref --assembly .\\fixtures\\managed\\bin\\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject' --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer managed IL bodies, callers, callees, field access, and string references.",
|
||||
"trust": "Trust method-body metadata when the target method resolves; unknown bodies are reported.",
|
||||
"next_actions": [
|
||||
"Use asmtype/asmmember to find exact targets.",
|
||||
"Use ctxpack to hand off IL evidence."
|
||||
]
|
||||
}
|
||||
},
|
||||
"llvmobjdump": {
|
||||
"why": "raw llvm-objdump text when you need compact section, symbol, and disassembly shape for COFF/PE or object files.",
|
||||
"use_when": "Inspect object sections, symbol labels, and disassembly through LLVM backend discovery.",
|
||||
"prompt_usage": "llvmobjdump [OPTIONS] [PATH...]",
|
||||
"prompt_example": "llvmobjdump .\\target\\release-fast\\binmeta.exe --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer object sections, symbols, and disassembly shape through LLVM.",
|
||||
"trust": "Trust LLVM backend output plus parser warnings/raw blocks for unsupported regions.",
|
||||
"next_actions": [
|
||||
"Use llvmreadobj for headers/imports/debug hints.",
|
||||
"Use pecalls or pesig for PE-focused call/function triage."
|
||||
]
|
||||
}
|
||||
},
|
||||
"llvmreadobj": {
|
||||
"why": "heavy binary viewers or raw llvm-readobj output when you need a bounded COFF/PE header, import/export, and debug/PDB summary.",
|
||||
"use_when": "Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM backend discovery.",
|
||||
"prompt_usage": "llvmreadobj [OPTIONS] [PATH...]",
|
||||
"prompt_example": "llvmreadobj .\\target\\release-fast\\binmeta.exe --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer COFF/PE headers, sections, imports, exports, and debug hints through LLVM.",
|
||||
"trust": "Trust LLVM backend exit status and parsed blocks; raw blocks preserve unparsed details.",
|
||||
"next_actions": [
|
||||
"Use peimports/peexports for PE-focused grouping.",
|
||||
"Use llvmobjdump when code layout or disassembly is needed."
|
||||
]
|
||||
}
|
||||
},
|
||||
"llvmnm": {
|
||||
"why": "raw symbol-table dumps when you need stable symbol rows with kind, address, size, object/archive prefix, and source-line hints.",
|
||||
"use_when": "List and classify object symbols through LLVM nm output.",
|
||||
"prompt_usage": "llvmnm [OPTIONS] [PATH...]",
|
||||
"prompt_example": "llvmnm .\\target\\release-fast\\binmeta.exe --defined-only --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer defined/undefined symbols with stable LLVM nm rows.",
|
||||
"trust": "Trust POSIX-format symbol parsing and backend stderr tails.",
|
||||
"next_actions": [
|
||||
"Use llvmobjdump for disassembly around symbols.",
|
||||
"Use llvmreadobj for object headers and debug hints."
|
||||
]
|
||||
}
|
||||
},
|
||||
"peexports": {
|
||||
"why": "manual PE export-table browsing when you want names, ordinals, RVA/VA, forwarders, and guided follow-up commands without opening a heavy PE debugger.",
|
||||
"use_when": "Inspect export surfaces, spot forwarded symbols, filter by name or ordinal, and use `report_quality`/`next_actions` to decide the next PE pass.",
|
||||
"prompt_usage": "peexports [OPTIONS] [PATH...]",
|
||||
"prompt_example": "peexports C:\\Windows\\System32\\kernel32.dll --forwarders-only --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer PE export names, ordinals, RVAs/VAs, forwarders, and entrypoint hints.",
|
||||
"trust": "Trust PE export table parsing plus report_quality evidence and limitations.",
|
||||
"next_actions": [
|
||||
"Use peimports to inspect dependencies.",
|
||||
"Use llvmreadobj --exports to cross-check LLVM output."
|
||||
]
|
||||
}
|
||||
},
|
||||
"peimports": {
|
||||
"why": "ad-hoc import-table triage when you need API families grouped into human-friendly categories with immediate callsite and role follow-ups.",
|
||||
"use_when": "Inspect imports by library, name, or category, quickly separate filesystem, registry, device I/O, NT, and network APIs, then follow emitted `next_actions`.",
|
||||
"prompt_usage": "peimports [OPTIONS] [PATH...]",
|
||||
"prompt_example": "peimports .\\target\\release-fast\\portping.exe --category device_io --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer imported APIs grouped by library and API category.",
|
||||
"trust": "Trust PE import table parsing plus report_quality evidence and limitations.",
|
||||
"next_actions": [
|
||||
"Use pecalls on interesting categories.",
|
||||
"Use drvshape for driver-like/native profiles."
|
||||
]
|
||||
}
|
||||
},
|
||||
"pecalls": {
|
||||
"why": "guessing import callsites from raw disassembly when you want direct IAT matches plus trust metadata around best-effort disassembly parsing.",
|
||||
"use_when": "Extract callsites for one or more imported APIs or API categories from LLVM objdump text and inspect `report_quality.limitations` before treating it as exhaustive.",
|
||||
"prompt_usage": "pecalls [OPTIONS] [PATH...]",
|
||||
"prompt_example": "pecalls .\\target\\release-fast\\portping.exe --api WSAStartup --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer direct imported API callsites found through LLVM disassembly.",
|
||||
"trust": "Trust direct IAT-target matches; report_quality limitations mark disassembly truncation or gaps.",
|
||||
"next_actions": [
|
||||
"Use peimports to choose categories.",
|
||||
"Use pesig to place callsites inside functions."
|
||||
]
|
||||
}
|
||||
},
|
||||
"pesig": {
|
||||
"why": "manual function-boundary and calling-convention inference when you need a quick v1 signal with explicit confidence and next-step context.",
|
||||
"use_when": "Infer function boundaries, source hints, and calling conventions from PE text and metadata, then pivot to imports, callsites, or raw objdump via `next_actions`.",
|
||||
"prompt_usage": "pesig [OPTIONS] [PATH...]",
|
||||
"prompt_example": "pesig .\\target\\release-fast\\portping.exe --min-confidence medium --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer likely PE function boundaries and calling-convention hints.",
|
||||
"trust": "Trust confidence/evidence per function and report_quality for parse completeness.",
|
||||
"next_actions": [
|
||||
"Use pecalls to connect functions to APIs.",
|
||||
"Use llvmobjdump for raw disassembly context."
|
||||
]
|
||||
}
|
||||
},
|
||||
"pestrrefs": {
|
||||
"why": "opening a disassembler and a string viewer separately when you need string hits with direct xrefs and a clear next triage command.",
|
||||
"use_when": "Scan ASCII or UTF-16LE strings, report direct references from LLVM disassembly, and use `next_actions` to connect strings to imports, callsites, or IOCTL constants.",
|
||||
"prompt_usage": "pestrrefs [OPTIONS] [PATH...]",
|
||||
"prompt_example": "pestrrefs .\\target\\release-fast\\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer strings and direct code references in PE files.",
|
||||
"trust": "Trust direct VA/range xrefs; unresolved counts are not guessed.",
|
||||
"next_actions": [
|
||||
"Use peimports to connect strings to APIs.",
|
||||
"Use ioctlscan for device-control constants."
|
||||
]
|
||||
}
|
||||
},
|
||||
"drvshape": {
|
||||
"why": "guessing the driver role from imports and exports when you want a compact Windows driver profile with IOCTL/import/callsite follow-ups already suggested.",
|
||||
"use_when": "Summarize likely WDM, KMDF, NDIS, minifilter, or native driver traits, surface heuristic driver hints, and treat `report_quality` as the trust boundary.",
|
||||
"prompt_usage": "drvshape [OPTIONS] [PATH...]",
|
||||
"prompt_example": "drvshape C:\\Windows\\System32\\drivers\\ndis.sys --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer likely Windows driver role, subsystem, imports, exports, and heuristic hints.",
|
||||
"trust": "Trust role hints as heuristics, not vulnerability conclusions; report_quality shows evidence.",
|
||||
"next_actions": [
|
||||
"Use ioctlscan to decode CTL_CODE candidates.",
|
||||
"Use pecalls --category device_io for dispatch/callsite evidence."
|
||||
]
|
||||
}
|
||||
},
|
||||
"ioctlscan": {
|
||||
"why": "searching for Windows IOCTL constants by hand when you want decoded CTL_CODE fields, code locations, and suggested role/callsite/string follow-ups.",
|
||||
"use_when": "Scan PE bytes and disassembly-adjacent data for likely IOCTL constants, decode their fields, and use `report_quality` to separate strong hits from heuristic candidates.",
|
||||
"prompt_usage": "ioctlscan [OPTIONS] [PATH...]",
|
||||
"prompt_example": "ioctlscan C:\\Windows\\System32\\drivers\\ndis.sys --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer probable IOCTL constants and decoded CTL_CODE fields.",
|
||||
"trust": "Trust confidence/evidence per candidate; raw byte hits are heuristic until tied to code context.",
|
||||
"next_actions": [
|
||||
"Use drvshape to confirm driver role.",
|
||||
"Use pestrrefs or pecalls for surrounding evidence."
|
||||
]
|
||||
}
|
||||
},
|
||||
"binmeta": {
|
||||
"why": "opening heavy PE tooling or shelling out to signature utilities when you first need binary identity, PE basics, version resources, and Windows signing status.",
|
||||
"use_when": "Inspect file metadata, Windows PE basics, version/company/product identity, embedded Authenticode certificate tables, WinTrust status, catalog signing, signer certificate subjects, chains, timestamps, and expiry hints.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer file identity, PE basics, version resource fields, company/product names, signature status, embedded-vs-catalog signing, signer subject, certificate chain, timestamp, and expiry fields before deeper binary analysis.",
|
||||
"trust": "Trust goblin PE/resource parsing for local structure and Windows WinTrust/catalog status on Windows; signature failures are reported as metadata, not command failures. On non-Windows, trust only embedded certificate table presence and treat WinTrust fields as unsupported.",
|
||||
"next_actions": [
|
||||
"Use peimports or llvmreadobj for deeper PE detail after identity is known.",
|
||||
"Use drvshape or ioctlscan for signed drivers and native/system binaries.",
|
||||
"Use stringscan or pestrrefs when identity/version metadata is missing or suspicious."
|
||||
]
|
||||
}
|
||||
},
|
||||
"fileprobe": {
|
||||
"why": "blindly opening files when you need a fast read-worthiness, encoding, or newline check first.",
|
||||
"use_when": "Classify files as text, binary, generated, minified, test, vendor, and more, including encoding, BOM, and newline diagnostics.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether a path is text, binary, generated, minified, vendor, or worth opening.",
|
||||
"trust": "Trust bounded sniffing, encoding, newline, and classification diagnostics.",
|
||||
"next_actions": [
|
||||
"Use outline or chunkcat for readable text.",
|
||||
"Use binmeta or stringscan for binary files."
|
||||
]
|
||||
}
|
||||
},
|
||||
"outline": {
|
||||
"why": "scrolling whole files when you only need the structure.",
|
||||
"use_when": "List top-level code or config structure.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer top-level structure of source or config files.",
|
||||
"trust": "Trust parser-supported outlines and explicit unsupported-file diagnostics.",
|
||||
"next_actions": [
|
||||
"Use defsnip for exact definitions.",
|
||||
"Use refs or codeshape for broader symbol maps."
|
||||
]
|
||||
}
|
||||
},
|
||||
"codeshape": {
|
||||
"why": "plain `tree` output when you need internal declarations and signatures without dumping full source files.",
|
||||
"use_when": "Map a codebase into files plus AST-backed declarations and signatures from the shared `codeindex` engine.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer repository file/declaration shape with AST-backed summaries.",
|
||||
"trust": "Trust codeindex parser results and skipped-file diagnostics.",
|
||||
"next_actions": [
|
||||
"Use defsnip to extract definitions.",
|
||||
"Use refs to find use sites."
|
||||
]
|
||||
}
|
||||
},
|
||||
"refs": {
|
||||
"why": "falling back to raw `rg` when you need exact use-sites or caller summaries for a known symbol.",
|
||||
"use_when": "Find exact symbol references or caller definitions through the shared `codeindex` engine with text fallback.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer symbol references or callers across source files.",
|
||||
"trust": "Trust codeindex hits and caller grouping under the selected roots.",
|
||||
"next_actions": [
|
||||
"Use hitsnip to expand hit context.",
|
||||
"Use defsnip for definition bodies."
|
||||
]
|
||||
}
|
||||
},
|
||||
"snip": {
|
||||
"why": "dumping whole files when you only need exact lines, matches, or symbols.",
|
||||
"use_when": "Extract precise snippets from files or stdin.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer exact bounded source/text snippets by line, match, or symbol.",
|
||||
"trust": "Trust line numbers and bounded extraction; binary or missing paths are rejected.",
|
||||
"next_actions": [
|
||||
"Use hitsnip after rg for multiple hits.",
|
||||
"Use ctxpack to bundle snippets."
|
||||
]
|
||||
}
|
||||
},
|
||||
"defsnip": {
|
||||
"why": "line-number snippets when you need the full function, class, or method body even after nearby edits move the lines.",
|
||||
"use_when": "Extract full AST-backed definitions by exact symbol name through the shared `codeindex` engine.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer full AST-backed definition blocks for symbols.",
|
||||
"trust": "Trust codeindex definitions and language support; no match means broaden symbol/root.",
|
||||
"next_actions": [
|
||||
"Use refs for callers/use sites.",
|
||||
"Use ctxpack to package the definition with nearby context."
|
||||
]
|
||||
}
|
||||
},
|
||||
"ctxpack": {
|
||||
"why": "hand-assembling ad-hoc prompt context from files, hits, diagnostics, and definitions.",
|
||||
"use_when": "Pack files, snippets, hits, diagnostics, or definition JSON into compact context blocks.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer compact prompt-ready context from files, snippets, hits, and diagnostics.",
|
||||
"trust": "Trust included path and byte/line caps; review omitted/truncated sections for scope.",
|
||||
"next_actions": [
|
||||
"Use fileprobe/codeshape before packing broad roots.",
|
||||
"Use diagpick or hitsnip to feed focused evidence."
|
||||
]
|
||||
}
|
||||
},
|
||||
"chunkcat": {
|
||||
"why": "huge file dumps when you need deterministic windows.",
|
||||
"use_when": "Read large text files in bounded chunks, including quick tail-style log windows.",
|
||||
"prompt_example": "chunkcat .\\BepInEx\\LogOutput.log --max-lines 20 --tail",
|
||||
"guided_triage": {
|
||||
"answer": "Answer a bounded chunk or inventory of a large text file.",
|
||||
"trust": "Trust chunk indices, line ranges, and binary detection.",
|
||||
"next_actions": [
|
||||
"Use snip when you know the exact line range.",
|
||||
"Use hitsnip to expand search hits into chunks."
|
||||
]
|
||||
}
|
||||
},
|
||||
"hitsnip": {
|
||||
"why": "raw `rg` hit lists when you need merged readable context or the enclosing definition instead of a tiny window.",
|
||||
"use_when": "Turn search hits into compact snippets or promote them to enclosing definitions.",
|
||||
"prompt_example": "rg -nH \"helper\" .\\fixtures\\polyglot\\repo\\src\\lib.rs | hitsnip --def",
|
||||
"guided_triage": {
|
||||
"answer": "Answer merged snippets around rg-style search hits.",
|
||||
"trust": "Trust hit parsing and merge ranges; malformed hit lines are reported.",
|
||||
"next_actions": [
|
||||
"Use rg -nH to feed hits.",
|
||||
"Use defsnip when the hit is inside a known symbol."
|
||||
]
|
||||
}
|
||||
},
|
||||
"diagpick": {
|
||||
"why": "reading full logs when you need the actionable errors first and want direct source or definition context.",
|
||||
"use_when": "Extract compiler or runtime diagnostics from noisy logs, with optional snippets and enclosing definitions.",
|
||||
"prompt_example": "diagpick .\\fixtures\\diag\\rust-errors.txt --def",
|
||||
"guided_triage": {
|
||||
"answer": "Answer actionable diagnostics extracted from compiler/build/log text.",
|
||||
"trust": "Trust recognized diagnostic formats and preserved source context.",
|
||||
"next_actions": [
|
||||
"Use snip on referenced files/lines.",
|
||||
"Use runprobe to capture the failing command reproducibly."
|
||||
]
|
||||
}
|
||||
},
|
||||
"logshape": {
|
||||
"why": "reading repetitive logs line by line when you need the dominant patterns.",
|
||||
"use_when": "Group recurring log lines into templates.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer repeated log templates, incidents, and message clusters.",
|
||||
"trust": "Trust grouping counts and examples; rare lines may stay as individual templates.",
|
||||
"next_actions": [
|
||||
"Use diagpick for actionable errors.",
|
||||
"Use jsonlgrep when logs are structured JSONL."
|
||||
]
|
||||
}
|
||||
},
|
||||
"stringscan": {
|
||||
"why": "a full reverse-engineering pass when you first need identity clues from strings.",
|
||||
"use_when": "Extract and classify high-signal strings from binaries or blobs.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer strings and classified hints from arbitrary blobs.",
|
||||
"trust": "Trust extracted string offsets and classification labels; encoding limits are explicit.",
|
||||
"next_actions": [
|
||||
"Use binmeta first for binary identity.",
|
||||
"Use pestrrefs for PE strings with xrefs."
|
||||
]
|
||||
}
|
||||
},
|
||||
"toon": {
|
||||
"why": "verbose JSON when you want a denser structured text form.",
|
||||
"use_when": "Convert between JSON and TOON.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer compact model-readable TOON from JSON/JSONL or decode TOON back.",
|
||||
"trust": "Trust parser/encoder diagnostics and document wrapper metadata.",
|
||||
"next_actions": [
|
||||
"Use native --toon on Mercury producers when available.",
|
||||
"Use cjson/jsonshape before converting questionable JSON."
|
||||
]
|
||||
}
|
||||
},
|
||||
"csvshape": {
|
||||
"why": "opening huge CSV or TSV files when you first need the columns, rough types, blanks, example values, or a shape diff.",
|
||||
"use_when": "Summarize large CSV or TSV files into compact schema/bounded stats, or diff two CSV shapes.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer CSV/TSV delimiter, columns, row counts, and schema differences.",
|
||||
"trust": "Trust parsed rows under the detected or requested delimiter.",
|
||||
"next_actions": [
|
||||
"Use jsonshape after converting CSV to JSON externally.",
|
||||
"Use config or sqlshape when CSV describes configuration/data imports."
|
||||
]
|
||||
}
|
||||
},
|
||||
"sqliteshape": {
|
||||
"why": "dropping into an interactive SQLite shell when you only need schema, sample rows, light table stats, or a shape diff.",
|
||||
"use_when": "Inspect SQLite databases read-only with compact schema/table summaries, or diff two SQLite shapes.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer SQLite tables, columns, indexes, triggers, and schema diffs.",
|
||||
"trust": "Trust SQLite catalog queries against the selected database file.",
|
||||
"next_actions": [
|
||||
"Use sqlshape for normalized cross-engine reports.",
|
||||
"Use jsonshape/csvshape on exported data samples."
|
||||
]
|
||||
}
|
||||
},
|
||||
"sqlshape": {
|
||||
"why": "hand-writing per-engine catalog queries or exposing raw connection strings when you need a normalized cross-database schema report or diff.",
|
||||
"use_when": "Inspect PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, or DuckDB schemas read-only with redacted connection sources and normalized cross-engine diffs.",
|
||||
"prompt_example": "sqlshape --engine sqlite --url .\\fixtures\\sqliteshape\\sample.db --json | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer normalized SQL schema across SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, or DuckDB.",
|
||||
"trust": "Trust engine-specific introspection and redacted connection reporting.",
|
||||
"next_actions": [
|
||||
"Use sqliteshape for SQLite-specific detail.",
|
||||
"Use config to inspect connection/config files safely."
|
||||
]
|
||||
}
|
||||
},
|
||||
"unityasset": {
|
||||
"why": "opening a heavy Unity GUI tool when you first need an index, object refs, field dump, or a quick extraction path for assets, scripts, audio, or video.",
|
||||
"use_when": "Inspect Unity serialized assets, bundles, and YAML objects, then trace refs, dump fields, or extract payloads such as TextAsset, MonoScript, AudioClip, and VideoClip.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer Unity asset indexes, object dumps, references, and extraction writes.",
|
||||
"trust": "Trust parsed serialized files/bundles and explicit unresolved reference rows.",
|
||||
"next_actions": [
|
||||
"Use unitydiag for runtime/log symptoms.",
|
||||
"Use asmtype/asmflow for managed script assemblies."
|
||||
]
|
||||
}
|
||||
},
|
||||
"unityprobe": {
|
||||
"why": "hand-writing BepInEx reflection plugins or one-off named-pipe helpers when you only need a read-only runtime snapshot from a Mono Unity game.",
|
||||
"use_when": "Install and query a read-only BepInEx bridge for live scenes, objects, and static state in a running Mono Unity game on Windows.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer read-only Unity runtime bridge status, object search, and inspection.",
|
||||
"trust": "Trust explicit bridge install/status and Windows named-pipe reachability.",
|
||||
"next_actions": [
|
||||
"Use unitydiag when runtime logs explain bridge issues.",
|
||||
"Use unityasset for offline assets."
|
||||
]
|
||||
}
|
||||
},
|
||||
"unitydiag": {
|
||||
"why": "reading raw Player.log and BepInEx logs end to end when you need the repeated incidents, top frames, and mod-vs-framework blame split first.",
|
||||
"use_when": "Summarize Unity Player.log and BepInEx logs into grouped incidents, normalized messages, and domain-aware failure summaries.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer Unity/BepInEx log incidents, grouped frames, and mod/runtime warnings.",
|
||||
"trust": "Trust discovered log paths, grouping counts, and preserved stack snippets.",
|
||||
"next_actions": [
|
||||
"Use asmref diagnose for plugin dependency issues.",
|
||||
"Use unityprobe when live object state is needed."
|
||||
]
|
||||
}
|
||||
},
|
||||
"envdiff": {
|
||||
"why": "hand-comparing environment variables before and after a script, especially around PATH pollution and batch wrappers.",
|
||||
"use_when": "Snapshot, diff, or run commands while reporting environment-variable changes.",
|
||||
"prompt_usage": "envdiff [OPTIONS] run --shell cmd|pwsh|raw -- <COMMAND...>",
|
||||
"prompt_example": "envdiff run --shell cmd -- .\\scripts\\set-env.cmd",
|
||||
"guided_triage": {
|
||||
"answer": "Answer environment variable changes before/after a command or between snapshots.",
|
||||
"trust": "Trust captured before/after maps and PATH segment deltas.",
|
||||
"next_actions": [
|
||||
"Use pathshadow after PATH changes.",
|
||||
"Use sysshape for broader shell/tool inventory."
|
||||
]
|
||||
}
|
||||
},
|
||||
"proctree": {
|
||||
"why": "flat process lists when you need parent-child context, short command lines, and lingering orphan hints.",
|
||||
"use_when": "Inspect whole-system, rooted, matched, or command-run Windows process trees in AI-friendly form; use --match to filter by image name or command line.",
|
||||
"prompt_usage": "proctree [OPTIONS] system|root <PID>|run -- <COMMAND...>",
|
||||
"prompt_example": "proctree system --match 'pwsh|Mercury' --include-cmdline",
|
||||
"guided_triage": {
|
||||
"answer": "Answer process trees, rooted processes, and command ancestry.",
|
||||
"trust": "Trust OS process snapshots at capture time; short-lived processes may disappear.",
|
||||
"next_actions": [
|
||||
"Use portunlock for port owners.",
|
||||
"Use runprobe to capture command execution shape."
|
||||
]
|
||||
}
|
||||
},
|
||||
"sysshape": {
|
||||
"why": "asking users ad-hoc setup questions or checking versions one tool at a time when you need a compact local machine inventory first.",
|
||||
"use_when": "Capture a compact local system and tool inventory for AI-friendly triage, including shell hints, path-like duplication, and probe status.",
|
||||
"prompt_example": "sysshape --json --env safe --group shell | ConvertFrom-Json",
|
||||
"guided_triage": {
|
||||
"answer": "Answer machine, shell, environment, and tool inventory shape.",
|
||||
"trust": "Trust detected command paths/versions and grouped environment metadata.",
|
||||
"next_actions": [
|
||||
"Use pathshadow for a specific executable winner.",
|
||||
"Use envdiff around commands that mutate the environment."
|
||||
]
|
||||
}
|
||||
},
|
||||
"runprobe": {
|
||||
"why": "reading fragile shell text when what you really need is the stable result object for one command run.",
|
||||
"use_when": "Run one command and capture exit code, duration, timeout status, and bounded output tails.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer command exit code, duration, stdout/stderr tails, and timeout behavior.",
|
||||
"trust": "Trust captured process result and bounded output tails.",
|
||||
"next_actions": [
|
||||
"Use diagpick on captured stderr/stdout.",
|
||||
"Use envdiff run when environment mutation matters."
|
||||
]
|
||||
}
|
||||
},
|
||||
"await": {
|
||||
"why": "writing ad-hoc polling loops for files, ports, HTTP endpoints, or repeat-until-success commands.",
|
||||
"use_when": "Wait for a path, TCP target, HTTP endpoint, or command condition with bounded polling.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer whether a path, port, HTTP endpoint, or command became ready before timeout.",
|
||||
"trust": "Trust polling attempts, final state, and timeout status.",
|
||||
"next_actions": [
|
||||
"Use portping for one-shot endpoint detail.",
|
||||
"Use runprobe for command readiness probes."
|
||||
]
|
||||
}
|
||||
},
|
||||
"argv": {
|
||||
"why": "guessing how PowerShell or cmd really passed arguments to a native process.",
|
||||
"use_when": "Quote argv for `pwsh` or `cmd`, or inspect what a shell actually passed to a native process.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer how arguments should be quoted or how a shell actually passes them.",
|
||||
"trust": "Trust helper round-trips for the selected shell/platform.",
|
||||
"next_actions": [
|
||||
"Use runprobe to execute the quoted command.",
|
||||
"Use msudo status before privileged shell wrapping."
|
||||
]
|
||||
}
|
||||
},
|
||||
"config": {
|
||||
"why": "fighting `jq` or hand-editing config files when you need safe slash-pointer reads or edits across common formats.",
|
||||
"use_when": "Read, inspect, list, set, or delete config values in JSON, YAML, TOML, env, and INI files.",
|
||||
"prompt_usage": "config [OPTIONS] [PATH] | config [OPTIONS] <get|inspect|ls|set|delete> <PATH> [POINTER] [VALUE]",
|
||||
"prompt_example": "config get .\\package.json /version",
|
||||
"guided_triage": {
|
||||
"answer": "Answer get/set/delete operations over JSON/YAML/TOML/env/INI config paths.",
|
||||
"trust": "Trust parser-specific diagnostics and structured edit reports.",
|
||||
"next_actions": [
|
||||
"Use fileprobe before editing unknown config files.",
|
||||
"Use jsonshape after JSON config changes."
|
||||
]
|
||||
}
|
||||
},
|
||||
"gitshape": {
|
||||
"why": "reading raw `git status` and diff noise when you first need compact status counters or changed-file summaries.",
|
||||
"use_when": "Summarize Git status or diff shape into concise AI-friendly file, line, and touched-symbol reports.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer git status, branch, diff, and repository change shape.",
|
||||
"trust": "Trust git command output and explicit revision/path filters.",
|
||||
"next_actions": [
|
||||
"Use reposhape to connect git changes to ecosystems.",
|
||||
"Use ctxpack or hitsnip for changed-file handoff."
|
||||
]
|
||||
}
|
||||
},
|
||||
"reposhape": {
|
||||
"why": "manually browsing an unfamiliar repo when you first need the ecosystems, manifests, commands, and CI entrypoints.",
|
||||
"use_when": "Detect repository ecosystems, manifests, command entrypoints, and CI hints in one pass.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer repository ecosystems, manifests, entrypoints, and project layout.",
|
||||
"trust": "Trust manifest detection under depth/hidden filters and parse diagnostics.",
|
||||
"next_actions": [
|
||||
"Use codeshape for source declarations.",
|
||||
"Use dotnetshape/sqlshape/gitshape for ecosystem-specific detail."
|
||||
]
|
||||
}
|
||||
},
|
||||
"dotnetshape": {
|
||||
"why": "opening a .NET repo one file at a time when you first need project graph shape, shared MSBuild inheritance, package references, and build-shape warnings.",
|
||||
"use_when": "Inspect .csproj, Directory.Build.props/targets, Directory.Packages.props, project references, package versions, and .NET-specific project graph diagnostics.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer .NET project graph, inherited MSBuild properties, package references, and diagnostics.",
|
||||
"trust": "Trust static XML parsing without invoking MSBuild; generated/effective values are labeled.",
|
||||
"next_actions": [
|
||||
"Use asmref diagnose on built assemblies.",
|
||||
"Use config to inspect Directory.Build or props files directly."
|
||||
]
|
||||
}
|
||||
},
|
||||
"unlock": {
|
||||
"why": "ad-hoc PowerShell probing when a file is busy, locked, or refuses delete, move, rename, or copy.",
|
||||
"use_when": "Identify file lockers and perform unlock-aware file actions on Windows.",
|
||||
"guided_triage": {
|
||||
"answer": "Answer which processes lock files and perform unlock-aware copy/move/delete actions.",
|
||||
"trust": "Trust restart-manager/handle-scan evidence and post-action filesystem checks.",
|
||||
"next_actions": [
|
||||
"Use proctree on blocker PIDs.",
|
||||
"Use recent after cleanup to confirm generated artifacts."
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,90 @@
|
||||
# Benchmark Harness Usage
|
||||
|
||||
This directory stores reproducible benchmark notes and reports for Mercury tools.
|
||||
The mhash harness lives at `scripts/benchmark-mhash.ps1` and writes generated
|
||||
artifacts under `target\mhash-benchmark\results` by default.
|
||||
|
||||
## Default Digest Benchmark
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash.ps1
|
||||
```
|
||||
|
||||
The default matrix keeps runtime reasonable: 1MiB, 64MiB, and 256MiB inputs;
|
||||
MD5, SHA-1, SHA-256, and SHA-512; 1 warmup and 3 measured runs. It compares
|
||||
Mercury `mhash` auto/read modes against available non-admin external tools.
|
||||
|
||||
## Fast Smoke Check
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash-smoke.ps1 -SkipBuild
|
||||
```
|
||||
|
||||
The smoke check runs a 1KiB SHA-256 Mercury-only matrix, validates required
|
||||
telemetry fields, checks JSONL export counts, and verifies `-SizeOnly` emits
|
||||
artifact telemetry without process records.
|
||||
|
||||
## Useful Modes
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash.ps1 -SizeOnly -SkipBuild
|
||||
```
|
||||
|
||||
Use `-SizeOnly` when you only need binary artifact telemetry. It skips fixture
|
||||
creation and process benchmarks, but still writes raw JSON, artifact JSON/CSV,
|
||||
empty summary files, and a Markdown report.
|
||||
|
||||
To inspect a prebuilt size-focused binary, point the harness at it:
|
||||
|
||||
```powershell
|
||||
cargo build --profile release-size -p mercury-mhash --bin mhash
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash.ps1 -SizeOnly -SkipBuild -DigestPath .\target\release-size\mhash.exe
|
||||
```
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash.ps1 -Extended -Hyperfine
|
||||
```
|
||||
|
||||
Use `-Extended` for a deeper matrix. Unless explicitly overridden, it raises
|
||||
the run count to 5, warmups to 2, adds a 1GiB fixture, and benchmarks Mercury
|
||||
`sum`, `jsonl`, and `json` output formats. Use `-Hyperfine` to add optional
|
||||
`hyperfine` timing exports when `hyperfine` is available on `PATH`.
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash.ps1 -Sizes 1KiB -Algorithms sha256 -DigestFormats sum,jsonl -Repeat 1 -Warmup 0 -NoExternal -SkipBuild
|
||||
```
|
||||
|
||||
Use explicit small matrices for local harness checks or quick regression
|
||||
triage.
|
||||
|
||||
## Emitted Telemetry
|
||||
|
||||
Each run now records wall time, CPU time, CPU as percent of one core and of the
|
||||
machine, peak working set, mhash output format, binary path, binary size, and a
|
||||
short stdout/stderr sample. Summaries include mean wall time, min wall time,
|
||||
mean CPU milliseconds, throughput, peak working set, CPU percent of one core,
|
||||
and binary size.
|
||||
|
||||
The raw report includes reproducibility metadata: invocation, script path,
|
||||
workspace root, OS and process architecture, PowerShell version, logical
|
||||
processor count, git branch/commit/status entries, fixture SHA-256 hashes,
|
||||
tool paths/versions, artifact sizes, artifact SHA-256 hashes, and optional
|
||||
hyperfine suites.
|
||||
|
||||
Generated files include:
|
||||
|
||||
- `*.raw.json`: full environment, records, summary, artifact, and hyperfine data.
|
||||
- `*.records.jsonl`: one process measurement per line.
|
||||
- `*.summary.json` and `*.summary.jsonl`: grouped summary rows.
|
||||
- `*.summary.csv`: spreadsheet-friendly grouped summary rows.
|
||||
- `*.artifacts.json` and `*.artifacts.csv`: binary size and identity metadata.
|
||||
- `*.hyperfine.json` and `*.hyperfine.csv`: aggregate optional hyperfine output.
|
||||
- `*.md`: human-readable report.
|
||||
|
||||
## Measurement Caveats
|
||||
|
||||
Windows does not expose a safe non-admin cache-drop primitive, so results are
|
||||
warm-cache CLI timings. Very small fixtures mostly measure process startup and
|
||||
output overhead. Peak working set comes from process telemetry and can miss very
|
||||
short-lived allocation spikes. Hyperfine is opt-in and complements the built-in
|
||||
wall/CPU/memory telemetry; it does not replace the harness process metrics.
|
||||
@@ -0,0 +1,77 @@
|
||||
# Digest Benchmark - 2026-04-25
|
||||
|
||||
This benchmark compares Mercury `mhash` against common Windows and CLI hash tools on the same machine.
|
||||
|
||||
## Method
|
||||
|
||||
- Harness: `scripts/benchmark-mhash.ps1`
|
||||
- Scenario: warm-cache CLI hashing; Windows does not provide a safe non-admin cache-drop primitive, so cold-cache disk results are intentionally excluded.
|
||||
- Inputs: deterministic 1MiB, 64MiB, and 256MiB files under `target\mhash-benchmark\data`.
|
||||
- Algorithms: `md5`, `sha1`, `sha256`, `sha512`.
|
||||
- Repeats: 1 warmup plus 3 measured runs per tool/algorithm/size.
|
||||
- Metrics: wall-clock time, throughput, process CPU time as percent of one core, and peak working set.
|
||||
- Machine: `DESKTOP-EKBHO4B`, Windows `10.0.26200`, 32 logical processors.
|
||||
|
||||
## Tools
|
||||
|
||||
- Mercury `mhash 0.1.0`
|
||||
- PowerShell `Get-FileHash` via PowerShell `7.6.1`
|
||||
- Windows `certutil`
|
||||
- uutils coreutils `0.8.0` commands: `md5sum`, `sha1sum`, `sha256sum`, `sha512sum`
|
||||
- OpenSSL `3.6.1`
|
||||
|
||||
## Key Finding
|
||||
|
||||
The original Mercury `mhash` default `auto` mode memory-mapped large ordinary hash jobs. On this machine that increased peak working set to roughly the file size and was slower than streaming reads. The default was changed so streaming-friendly hash sets use one-pass buffered reads, while whole-file paths remain available for explicit `--io mmap` and for algorithms that benefit from whole-file/internal parallel processing.
|
||||
|
||||
## 256MiB Before/After
|
||||
|
||||
| Algorithm | Before auto ms | After auto ms | Speedup | Before peak MiB | After peak MiB | Peak drop MiB |
|
||||
|---|---:|---:|---:|---:|---:|---:|
|
||||
| md5 | 427.06 | 362.24 | 1.18x | 261.54 | 10.30 | 251.24 |
|
||||
| sha1 | 201.81 | 163.24 | 1.24x | 255.72 | 10.55 | 245.17 |
|
||||
| sha256 | 226.63 | 156.31 | 1.45x | 261.05 | 10.29 | 250.76 |
|
||||
| sha512 | 341.78 | 273.64 | 1.25x | 264.60 | 10.57 | 254.03 |
|
||||
|
||||
## 256MiB Post-Optimization Comparison
|
||||
|
||||
| Algorithm | Tool | Mean ms | MiB/s | Peak WS MiB | CPU % of one core |
|
||||
|---|---|---:|---:|---:|---:|
|
||||
| md5 | openssl:dgst | 353.02 | 725.17 | 12.17 | 100.5 |
|
||||
| md5 | mercury-mhash:auto | 362.24 | 706.71 | 10.30 | 94.9 |
|
||||
| md5 | mercury-mhash:read | 364.38 | 702.57 | 10.30 | 95.8 |
|
||||
| md5 | coreutils:md5sum | 377.49 | 678.17 | 9.44 | 96.6 |
|
||||
| md5 | windows:certutil | 521.46 | 490.93 | 14.71 | 91.9 |
|
||||
| md5 | powershell:Get-FileHash | 742.67 | 344.70 | 65.20 | 113.7 |
|
||||
| sha1 | mercury-mhash:read | 155.19 | 1649.56 | 10.54 | 90.6 |
|
||||
| sha1 | coreutils:sha1sum | 160.77 | 1592.36 | 9.45 | 90.7 |
|
||||
| sha1 | mercury-mhash:auto | 163.24 | 1568.23 | 10.55 | 98.9 |
|
||||
| sha1 | openssl:dgst | 196.64 | 1301.90 | 10.98 | 98.0 |
|
||||
| sha1 | windows:certutil | 398.24 | 642.82 | 14.73 | 99.4 |
|
||||
| sha1 | powershell:Get-FileHash | 641.07 | 399.33 | 66.26 | 114.5 |
|
||||
| sha256 | mercury-mhash:read | 155.78 | 1643.35 | 10.29 | 93.6 |
|
||||
| sha256 | mercury-mhash:auto | 156.31 | 1637.75 | 10.29 | 90.0 |
|
||||
| sha256 | coreutils:sha256sum | 170.32 | 1503.08 | 10.36 | 97.9 |
|
||||
| sha256 | openssl:dgst | 206.06 | 1242.36 | 10.99 | 91.0 |
|
||||
| sha256 | windows:certutil | 270.40 | 946.74 | 14.75 | 92.5 |
|
||||
| sha256 | powershell:Get-FileHash | 519.56 | 492.72 | 65.04 | 122.3 |
|
||||
| sha512 | mercury-mhash:auto | 273.64 | 935.52 | 10.57 | 99.0 |
|
||||
| sha512 | mercury-mhash:read | 273.88 | 934.70 | 10.31 | 93.2 |
|
||||
| sha512 | openssl:dgst | 277.36 | 922.98 | 10.99 | 99.5 |
|
||||
| sha512 | coreutils:sha512sum | 299.48 | 854.80 | 9.45 | 93.9 |
|
||||
| sha512 | windows:certutil | 910.10 | 281.29 | 14.73 | 99.6 |
|
||||
| sha512 | powershell:Get-FileHash | 1168.26 | 219.13 | 65.48 | 106.6 |
|
||||
|
||||
## Reproduce
|
||||
|
||||
```powershell
|
||||
just mhash-benchmark
|
||||
```
|
||||
|
||||
or:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -ExecutionPolicy Bypass -File .\scripts\benchmark-mhash.ps1
|
||||
```
|
||||
|
||||
The harness writes raw JSON, summary JSON, CSV, and Markdown reports under `target\mhash-benchmark\results`.
|
||||
@@ -0,0 +1,103 @@
|
||||
# Jade Discipline
|
||||
|
||||
Jade Discipline is the repository-wide Rust standard for Mercury Toolbox / 水星工具箱.
|
||||
|
||||
## Goals
|
||||
|
||||
- Default strictness: rules are either `deny` or `allow`; `warn` is not part of the policy surface.
|
||||
- Default observability: every command must remain easy to inspect from plain CLI output and machine-readable JSON.
|
||||
- Default auditability: lint gates, toolchain choices, and verification commands are written down and reproducible.
|
||||
- Default optimizability: development and release profiles are explicit instead of ad hoc.
|
||||
- Default narrow exemptions: repository-wide `allow` is treated as hazardous; when a lint must be suppressed, prefer the smallest code-local scope that still explains the exception.
|
||||
- Default hardening: Miri, fuzzing, sanitizer, no-panic, and Loom checks are Jade gates, not optional tiers.
|
||||
|
||||
## Repository Interpretation
|
||||
|
||||
- The workspace applies the Jade lint baseline through root `Cargo.toml` plus per-crate `[lints] workspace = true`.
|
||||
- The required hard gate is `cargo clippy --all-targets --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery`.
|
||||
- PowerShell scripts under `scripts/` are part of the same discipline surface. Executable `.ps1` files must opt into `Set-StrictMode -Version Latest`, set `$ErrorActionPreference = 'Stop'`, avoid automatic-variable reassignment, and stay free of `Invoke-Expression`.
|
||||
- Root `Cargo.toml` should not carry broad `allow` exemptions for design, API, or optimization lints. If a lint is not globally denied, that is not the same thing as globally allowing it.
|
||||
- Global `allow` is reserved for two cases only: a rule that is provably irrelevant to the repository with no realistic future exception, or a naming-only rule that would conflict with the project naming constitution. If a narrower suppression is possible, the narrower suppression wins.
|
||||
- Local suppressions should start at the smallest reasonable scope: item before impl block, impl block before module, module before crate. When `const`, borrowing, or `#[must_use]` can be added instead of suppressing, code changes are preferred over lint waivers.
|
||||
- `cargo_common_metadata = "deny"` is kept, and every crate is explicitly marked `publish = false` because Mercury Toolbox is a local toolbox rather than a published crate set.
|
||||
- Tokio-specific guidance is intentionally not applied because the current project has no async runtime, no Tokio dependencies, and no task scheduler to observe.
|
||||
- `tracing`, `tracing-subscriber`, `criterion`, `proptest`, `insta`, `rstest`, `anyhow`, and `miette` are approved workspace dependencies for future expansion. They are pinned now, but only crates with a concrete use case should inherit them to avoid dependency drift and `udeps` noise.
|
||||
- Workspace line coverage is enforced on logic-bearing source files. Thin binary entrypoints in `src/main.rs` and repetitive CLI argument shims in `src/cli.rs` are excluded from the line-rate denominator because they are covered instead by command-specific integration tests plus the PowerShell ecosystem gate.
|
||||
- Auto-generated lookup tables such as [`managed/src/flow_opcode_table.rs`](../crates/managed/src/flow_opcode_table.rs) are also excluded from the line-rate denominator. They are generated data snapshots rather than authored control flow, and they are verified indirectly through decoder tests that exercise the consuming logic in [`managed/src/flow.rs`](../crates/managed/src/flow.rs).
|
||||
- Because Mercury Toolbox is a workspace of many tiny binaries rather than one deep library crate, the repository coverage floor is `80%` line coverage after those wrapper exclusions, paired with a mandatory end-to-end `pwsh` ecosystem run.
|
||||
- Hardening checks are introduced into the main Jade gate. If a machine cannot run one, the run must use the matching `-ExemptMiri`, `-ExemptFuzz`, `-ExemptSanitizers`, `-ExemptNoPanic`, or `-ExemptLoom` flag plus a non-empty reason. Missing tools, missing harnesses, or platform discomfort are failures by default, not quiet skips.
|
||||
- Exemptions follow the same narrowness rule as lint suppressions: exempt one gate for one reviewed reason, fix the root cause as soon as the underlying toolchain supports it, and never convert the exemption into a broad permanent policy.
|
||||
|
||||
## Hard Gates
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\check-jade.ps1 -VerificationConfiguration ReleaseFast
|
||||
```
|
||||
|
||||
The script is the authoritative entry point. Expanded, it runs `cargo fmt --all --check`, `cargo check --all-targets --all-features`, coverage-backed `cargo llvm-cov --jobs 1 nextest --all-features --summary-only`, strict Clippy, root and fuzz-workspace `cargo +nightly udeps`, root and fuzz-workspace `cargo deny`, the mandatory hardening gates, generated AI asset drift checks, PowerShell analysis, the ecosystem probe, and the selected verification build profile.
|
||||
|
||||
The hardening sub-gate is `scripts/check-jade-hardening.ps1`. Its default `-Only All` path runs the no-panic source scan, Miri JSON-family tests, Loom runtime capture model, JSON-family fuzz target, and address sanitizer tests. The `-Only` switch exists only for focused local repair loops; it is not a Jade tier and it does not prove the repository is clean.
|
||||
|
||||
The `fuzz/` workspace is intentionally separate from the root Cargo workspace. Jade still audits it by running locked metadata generation, `cargo +nightly udeps`, and `cargo deny` against the fuzz manifest. Keep `fuzz/Cargo.lock` committed so fuzz dependency resolution is reproducible.
|
||||
|
||||
## Hardening Exemptions
|
||||
|
||||
Hardening exemptions are explicit audit records, not convenience switches.
|
||||
|
||||
- Use the exact gate flag, such as `-ExemptFuzz`, and include the matching non-empty reason parameter.
|
||||
- Prefer fixing missing tooling with `just jade-tools` or `pwsh -NoProfile -File .\scripts\install-jade-tooling.ps1` before considering an exemption.
|
||||
- Do not bake exemptions into `just` recipes, CI defaults, docs, or agent prompts.
|
||||
- Keep exemption reasons narrow enough to identify one machine, one platform issue, or one temporary toolchain gap.
|
||||
- Remove the exemption as soon as the underlying issue is fixed.
|
||||
|
||||
The no-panic source gate has its own local escape hatch for rare invariants. The only accepted form is an adjacent Rust comment: `// jade: allow-panic because: <reason>`. Prefer `Result`, `Option` handling, `ok_or_else`, and `?` over adding that comment.
|
||||
|
||||
## Install
|
||||
|
||||
Install or refresh the toolchain and cargo subcommands used by the standard.
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\install-jade-tooling.ps1
|
||||
```
|
||||
|
||||
The tooling script installs `cargo-udeps` and `cargo-llvm-cov`, so they stay in the active toolchain set as required Jade commands.
|
||||
`install-jade-tooling.ps1` also ensures `PSScriptAnalyzer` is available for the PowerShell gate.
|
||||
The hardening baseline also installs nightly `miri`, nightly `rust-src`, and `cargo-fuzz`. The repository no-panic gate is an audited source scan that denies `panic!`, `.unwrap()`, and `.expect()` in JSON-family production paths unless a narrow `// jade: allow-panic because: <reason>` comment is placed directly beside the call site.
|
||||
`just` and `bacon` are part of the local Jade tooling baseline now: `just` is the thin task runner over the repo scripts, and `bacon` is the continuous Rust feedback loop for the edit-compile-test idle gap.
|
||||
Generated AI assets are part of the repository surface too: the compact prompt under `docs\ai\` and the generated Codex skill under `skills\mercury-toolbox\` should both stay reproducible from their scripts instead of being hand-edited drift.
|
||||
On Windows, profiler helpers have extra OS prerequisites that Cargo cannot install for you: `cargo flamegraph` falls back to `blondie` unless DTrace is configured, and that `blondie` path requires an elevated shell; `samply` additionally requires `xperf.exe` from Windows Performance Toolkit.
|
||||
For local one-shot profiling runs, use `scripts/cargo-flamegraph-windows.ps1` to relay through UAC instead of trying to teach the full Jade gate to self-elevate.
|
||||
When you pass `-LogPath`, that wrapper writes a compact relay log to the requested path and the full elevated-session transcript to a sibling `*.transcript.txt` file so PowerShell-side failures stay auditable.
|
||||
`sccache` is part of the local Jade tooling baseline now and is configured as the default Cargo `rustc-wrapper`; use `sccache --show-stats` when verifying cache behavior after `cargo clean`.
|
||||
|
||||
## Profiles And Cargo Config
|
||||
|
||||
- `dev` is optimized for local debugging without dropping compile throughput.
|
||||
- `release` is the day-to-day shipping profile.
|
||||
- `release-fast` and `release-size` are reserved for speed-first and size-first builds.
|
||||
- `.cargo/config.toml` owns warning-to-error promotion, future incompatibility reports, and PowerShell-friendly network behavior.
|
||||
|
||||
## PowerShell Gate
|
||||
|
||||
- `scripts/check-powershell.ps1` is the Jade gate for repository PowerShell.
|
||||
- The gate runs `Invoke-ScriptAnalyzer` with [PSScriptAnalyzerSettings.psd1](../PSScriptAnalyzerSettings.psd1) and treats any reported diagnostic as a hard failure.
|
||||
- Naming-only analyzer rules such as approved verbs or singular nouns are intentionally left out of the hard gate because Jade reserves hard failures for completion and safety issues, not broad stylistic noise.
|
||||
- `scripts/toolbox-commands.ps1` is treated as a dot-sourced helper inventory rather than an executable script, so the strict-mode header requirement applies to the executable entry scripts instead.
|
||||
|
||||
## AI Asset Gate
|
||||
|
||||
- `scripts/generate-ai-prompt.ps1` and `scripts/generate-ai-skill.ps1` are the only supported writers for the generated AI prompt and Codex skill.
|
||||
- `scripts/check-ai-prompt.ps1` and `scripts/check-ai-skill.ps1` self-heal generated asset drift by regenerating once, then fail only if the regenerated files still do not match.
|
||||
- The generated skill exists partly to stop dumb whole-file reads in agent workflows: it explicitly routes AI toward `fileprobe`, `outline`, `snip`, `chunkcat`, `hitsnip`, `defsnip`, `codeshape`, `refs`, and `ctxpack` before falling back to raw dumps.
|
||||
|
||||
## Local Workflow
|
||||
|
||||
1. Install or update the required cargo tooling with `scripts/install-jade-tooling.ps1`; the local loop expects `cargo-nextest`, `cargo-llvm-cov`, `cargo-deny`, `cargo-udeps`, `just`, and `bacon`.
|
||||
2. Start new user-facing features from [the Jade feature template](templates/jade-feature-template.md) so behavior, tests, generated assets, and handoff notes stay aligned from the first commit. For daily low-risk maintenance, start from [the daily maintenance template](templates/daily-maintenance-template.md) and `.codex-progress\quality-security-backlog.md`.
|
||||
3. Keep public APIs fully documented, including `# Errors` and `# Panics` where applicable.
|
||||
4. Use `just check`, `just test`, `just clippy`, and `just jade-skip-coverage` for the broad local loop, then switch to subsystem loops such as `just code-check`, `just data-test`, `just runtime-check`, `just windows-test`, `just managed-clippy`, or `just ai-check` when the edit is narrower. Keep `just test` as the fast normal path; use `just stable-test` for warning-free incremental cleanup plus ignored slow Windows integrations.
|
||||
5. Use `just miri`, `just fuzz`, `just sanitizer`, `just no-panic`, and `just loom` only as focused edit loops for a specific failing gate. They are not exemptions and not an optional Jade tier: `just jade` runs the complete hardening gate set through `scripts/check-jade.ps1`.
|
||||
6. Use `bacon` when you want background compile or test feedback while you keep editing, and prefer the matching scoped jobs such as `bacon code`, `bacon runtime`, `bacon windows`, `bacon managed-test`, or `bacon ai` before falling back to the whole-workspace jobs.
|
||||
7. Run `pwsh -NoProfile -File .\scripts\check-jade.ps1` before claiming the repository is clean. If a hardening gate truly cannot run, pass the specific `-Exempt*` flag and reason so the missing coverage is visible in logs.
|
||||
8. Treat any new lint, warning, panic surface, UB finding, fuzz crash, sanitizer report, or Loom interleaving failure as a repository bug, not as backlog.
|
||||
9. If a lint or hardening check forces an exception, document it in code or command-line reason at the narrowest scope instead of adding a new workspace-wide `allow`.
|
||||
@@ -0,0 +1,73 @@
|
||||
# Maintainer Notes
|
||||
|
||||
This document captures the project decisions that are easy to lose between implementation rounds. Treat it as the quick orientation page for future workers before changing Mercury Toolbox internals.
|
||||
|
||||
## Project Direction
|
||||
|
||||
- Mercury Toolbox is not trying to replace every Unix utility. It adds a high-signal layer for local inspection, structure extraction, diagnostics, and AI/model handoff.
|
||||
- Default text output should stay compact and human-scannable. Use structured output only when the next consumer benefits from it.
|
||||
- The priority order for JSON-family and code-reading work is capability first, then speed, then memory/CPU footprint, then binary size. All four matter, but do not shrink a tool by removing useful behavior.
|
||||
- Windows PowerShell UX is a first-class target. Prefer stdin, path streams, clear examples, and failure messages that tell the user what to try next.
|
||||
|
||||
## Code Shape Family
|
||||
|
||||
- `codeindex` is the shared AST/indexing engine. `outline`, `codeshape`, `defsnip`, and `refs` should reuse it instead of growing separate parsers.
|
||||
- Tree-sitter support exists to make language coverage better, not just faster. When improving outline-like behavior, prefer AST-backed extraction over regex-only expansion.
|
||||
- If a language has weak output, add tests that demonstrate the missing constructs before tuning presentation. Java feedback was the first strong signal, but the goal is broad polyglot usefulness.
|
||||
- Keep `outline` short and readable by default. Use `codeshape`, `defsnip`, `refs`, `snip`, and `ctxpack` for deeper or wider context.
|
||||
|
||||
## JSON-Family Tools
|
||||
|
||||
- `common::formats::{toon, ison, zon, tonl}` is the shared home for compact JSON-family logic. Binaries should be thin CLIs around shared Rust implementations.
|
||||
- Do not introduce Node, npm, TypeScript, Python, or Go runtime dependencies for these formats. Official repositories/specs/fixtures are comparison sources only.
|
||||
- Every JSON-capable Mercury tool should route structured output through the shared renderer and support `--json`, `--toon`, and `--format text|json|toon`.
|
||||
- `--json` stays for compatibility. `--toon` is the AI-friendly shortcut. `MERCURY_OUTPUT=json|toon|text` is the session-wide default when no explicit format flag is provided.
|
||||
- The standalone `toon` binary remains useful for external JSON producers. For Mercury tools, prefer native `--toon`; for path streams, prefer simple pipelines such as `fd ... | fileprobe --input-format lines --toon`.
|
||||
- `toon` auto-detects JSON input and emits TOON by default. Avoid documenting long forms like `--json | toon --from json --to toon` unless a specific conversion direction truly needs to be explicit.
|
||||
- Shared TOON decoding must preserve quoted literal keys, reject strict dotted-path conflicts, and round-trip what the shared encoder emits, including root arrays and root primitives.
|
||||
- `tonl` is more than a converter. Preserve query, validate, index, streaming query, and ETL behavior when refactoring.
|
||||
|
||||
## Jade Is Mandatory
|
||||
|
||||
- Jade has no optional safety tier. Miri, fuzzing, sanitizers, no-panic scanning, and Loom are part of the main gate.
|
||||
- `scripts/check-jade.ps1` is the authoritative full gate. If a worker only runs a focused loop such as `just fuzz` or `just loom`, they have not run Jade.
|
||||
- Exemptions are allowed only through explicit `-Exempt*` flags with non-empty reviewed reasons. Missing tools, awkward platforms, or slow checks are failures by default.
|
||||
- The independent `fuzz/` workspace is intentional. Keep its `Cargo.lock` committed, keep `fuzz/.gitignore` preventing corpus/artifact leaks, and keep root Jade auditing fuzz dependencies with `udeps`, locked metadata, and `cargo deny`.
|
||||
- The no-panic gate scans JSON-family production paths for `panic!`, `.unwrap()`, and `.expect()`. Prefer fallible propagation. If a panic surface is truly unavoidable, use the strict adjacent comment form `// jade: allow-panic because: <reason>`.
|
||||
- Sanitizer setup is platform-sensitive. Windows needs ASan runtime discovery; non-Windows must not fail because a Windows DLL is absent.
|
||||
- Loom tests should model production-like concurrency patterns, not unrelated toy examples. Keep the runtime capture model tied to join/publish behavior.
|
||||
|
||||
## Documentation And Generated Assets
|
||||
|
||||
- `README.md` is the user-facing map. `docs/jade-discipline.md` is the safety/verification contract. This file is maintainer orientation.
|
||||
- Generated AI prompt and skill assets must be changed through `scripts/generate-ai-prompt.ps1` and `scripts/generate-ai-skill.ps1`; do not hand-edit generated output unless the generator changes in the same patch.
|
||||
- For docs, script, justfile, template, or generated-check hygiene, `just periphery-check` is the focused local proof. It is not a substitute for `just jade` when Rust behavior or release readiness is in scope.
|
||||
- For docs-only maintenance, prefer a small proof ladder: `just --summary`, `just ai-check` when generated asset references are touched, and `just periphery-check` before handoff if PowerShell scripts, just recipes, or generated-check expectations are mentioned.
|
||||
- When a pass receives a numeric candidate quota, record the reviewed count and the skipped classes in `.codex-progress\quality-security-backlog.md`; do not create low-value edits just to hit the number.
|
||||
- Help examples should teach the happy path and the AI-friendly path. Favor examples like `--toon` or `--json | toon` only when they shorten the real user workflow.
|
||||
- If a tool accepts path input, keep PowerShell wildcard behavior in mind. Native glob expansion is not guaranteed, so either support globs deliberately or give `fd ... | tool --input-format lines` guidance.
|
||||
- The vendored `tree-sitter` crate is intentionally pinned through `[patch.crates-io]`; follow `vendor/tree-sitter/README.md` before updating or re-vendoring it.
|
||||
|
||||
## CI And Runner Handoff
|
||||
|
||||
- The hosted Gitea CI lane uses the dedicated `windows` runner label, records a toolchain snapshot, runs `just workspace-check`, then performs explicit `cargo nextest`, strict Clippy, and `just ecosystem-fast` steps.
|
||||
- Treat the toolchain snapshot as runner drift evidence. If `cargo nextest --version`, `cargo llvm-cov --version`, `just --version`, or `pwsh --version` is missing or surprising, fix the runner/tooling before changing repository gates.
|
||||
- The release workflow is tag-driven and expects the tag to match `[workspace.package].version`; do not document a release as published until the package exists and the Gitea release upload has actually succeeded.
|
||||
- `scripts\setup-gitea-runner.ps1` creates local runner state and `.runner` credentials on the host. Treat those files and any `GITEA_TOKEN` / `GITEA_API_TOKEN` values as secret material that must stay out of docs, screenshots, package archives, and commits.
|
||||
- Before and after authenticated Gitea work, use secret-residue checks such as `git remote -v`, `.git\config`, and targeted `rg` scans for `Authorization`, `GITEA_TOKEN`, and token-bearing URLs. Report only the fact that the check passed, not token values.
|
||||
- When CI behavior changes, update the README workflow overview, this maintainer note, and the daily backlog together so future workers know whether a failing step is expected duplication, runner drift, or a new regression.
|
||||
|
||||
## Moving Or Relocating The Repo
|
||||
|
||||
- Scripts should be path-independent and derive the workspace root from `$PSScriptRoot` where possible.
|
||||
- Do not hardcode local worktree paths in documentation or scripts.
|
||||
- This repository may be moved between drives. After moving a Git worktree layout manually, verify both the main worktree and linked worktrees with `git status --short`.
|
||||
|
||||
## Gitea HTTPS Credential Fallback
|
||||
|
||||
- Symptom: Git for Windows can show a `git-remote-https.exe` application error while a push, fetch, or ls-remote operation is resolving HTTPS credentials. In the observed failure, direct authenticated API checks still worked, and a one-shot Git command with a Basic auth header worked, so the failure belonged to the local Git HTTPS credential path rather than repository contents.
|
||||
- First repair the machine when possible: update Git for Windows, update Git Credential Manager, and check whether the host certificate chain is trusted by the active Git TLS backend. Those changes belong on the affected machine, not in this repository.
|
||||
- Repo-safe fallback: use `scripts\invoke-gitea-git.ps1` for Gitea Git commands that need authentication. It sets `credential.helper=` for that invocation, uses `http.sslBackend=openssl`, injects an `http.extraHeader` Basic auth header, disables terminal prompts, clears Git curl tracing while the header is in scope, and filters libcurl trace lines from captured Git stderr.
|
||||
- Pass a token with `-ApiToken` or set `GITEA_API_TOKEN`/`GITEA_TOKEN` only in the current shell. The helper deliberately does not fall back to Git Credential Manager; if no token is provided, it fails closed instead of re-entering the crash path.
|
||||
- Keep TLS verification on by default. Use `-InsecureSkipTlsVerify` only as a temporary test-host workaround, then remove it once the certificate chain is fixed.
|
||||
- After any emergency authenticated push, verify that `git remote -v` and `.git\config` contain no token, no `Authorization` header, and no credential-bearing URL.
|
||||
@@ -0,0 +1,46 @@
|
||||
# Mercury Toolbox v0.1.0
|
||||
|
||||
Mercury Toolbox v0.1.0 is the first hosted release for the Gitea-backed repository. It packages the current PowerShell-first Rust toolbox, ships the renamed `mhash` hashing command, carries the generated Codex skill and AI prompt assets, and aligns the portable install path with the current package bundle.
|
||||
|
||||
## Highlights
|
||||
|
||||
- `mhash:` the former `digest` command surface is now published under the permanent `mhash` name across binaries, docs, scripts, packaged assets, and installed skills.
|
||||
- `Guided triage:` the generated AI prompt, skill catalog, and PE tooling guidance are bundled into the portable package so the hosted release matches the current local install surface.
|
||||
- `Portable packaging:` the release archive includes install and uninstall scripts, `SHA256SUMS.txt`, `mercury-toolbox-package.json`, and the packaged command catalog for offline inspection.
|
||||
- `Gitea automation:` this release adds native `.gitea/workflows` CI and tag-driven release publishing for the hosted repo.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
- `digest -> mhash`
|
||||
- Any automation or muscle memory that still invokes `digest` should switch to `mhash`.
|
||||
|
||||
## Install Or Upgrade
|
||||
|
||||
Fresh install from source checkout:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\install-toolbox.ps1
|
||||
```
|
||||
|
||||
Portable package install from the release assets:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\MercuryToolbox-x86_64-pc-windows-msvc-ReleaseFast\scripts\install-package-toolbox.ps1
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
- Release gate: `just jade`
|
||||
- Package build: `just package`
|
||||
- Release publish: `pwsh -NoProfile -File .\scripts\publish-gitea-release.ps1 -Tag v0.1.0 -NotesPath .\docs\releases\v0.1.0.md`
|
||||
|
||||
## Assets
|
||||
|
||||
- `MercuryToolbox-x86_64-pc-windows-msvc-ReleaseFast.zip`
|
||||
- `SHA256SUMS.txt`
|
||||
- `mercury-toolbox-package.json`
|
||||
|
||||
## Notes For Upgraders
|
||||
|
||||
- Open a new PowerShell after install so the updated PATH picks up the current toolbox binaries.
|
||||
- Codex skill installs are refreshed by the package installer; a new Codex session is the cleanest way to pick up the latest packaged skill copy.
|
||||
@@ -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.
|
||||
@@ -0,0 +1,329 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Toolbox Reading V2 Design
|
||||
|
||||
## Goal
|
||||
|
||||
Add four new PowerShell-friendly, AI-friendly reading commands to the toolbox so the workflow can move from "find a file" to "read the right part" without falling back to `Get-Content` or wasting tokens on full-file dumps.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add `snip` for precise snippet extraction from files or stdin.
|
||||
- Add `outline` for heuristic structure summaries of common source and config files.
|
||||
- Add `fileprobe` for fast file-type and usefulness heuristics before opening a file.
|
||||
- Add `chunkcat` for deterministic chunk listing and chunk extraction from large text files.
|
||||
- Add help examples and README usage for all four commands.
|
||||
- Reuse the existing workspace CLI contract: shared `--json`, `--input-format`, exit codes, and PowerShell pipe support.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No TUI, pager, fuzzy picker, or interactive mode.
|
||||
- No tree-sitter, Roslyn, or heavyweight language parser in this iteration.
|
||||
- No write or patch workflow in this batch.
|
||||
- No token estimation command, preview patch command, or replacement engine in this batch.
|
||||
|
||||
## Design Direction
|
||||
|
||||
- Prefer heuristic parsing over heavyweight parsing.
|
||||
- This keeps the binaries small, predictable, and fast enough for ad hoc shell use.
|
||||
- False positives are acceptable when they are clearly labeled as heuristic output.
|
||||
- Prefer compact text output that is useful to both humans and AI.
|
||||
- Text mode should avoid banners and avoid dumping redundant metadata.
|
||||
- JSON mode should expose stable machine fields so scripts can select the next action.
|
||||
- Treat these commands as a chain rather than isolated tools.
|
||||
- `fileprobe` answers "what is this file and should I read it?"
|
||||
- `outline` answers "where is the interesting structure?"
|
||||
- `snip` answers "show me the exact region."
|
||||
- `chunkcat` answers "how do I traverse this large file safely?"
|
||||
|
||||
## Command Designs
|
||||
|
||||
### `snip`
|
||||
|
||||
- Input:
|
||||
- one or more file paths from argv
|
||||
- or stdin content when piped
|
||||
- Selectors:
|
||||
- `--lines <START[:END]>`
|
||||
- `--around <REGEX>`
|
||||
- `--symbol <NAME>`
|
||||
- exactly one selector must be present
|
||||
- Supporting flags:
|
||||
- `--context <N>` for `--around` and `--symbol`
|
||||
- `--max-matches <N>` for `--around`
|
||||
- Output:
|
||||
- text mode emits `path:start-end reason=...` followed by numbered lines
|
||||
- JSON mode emits an array of snippets with `path`, `start_line`, `end_line`, `reason`, and `lines`
|
||||
- Heuristic behavior:
|
||||
- `--symbol` uses language-aware regexes for Rust and C# plus generic fallbacks for other text files
|
||||
- when possible, symbol extraction expands to a balanced block instead of a single line
|
||||
|
||||
### `outline`
|
||||
|
||||
- Input:
|
||||
- one or more file paths from argv
|
||||
- stdin paths in line mode
|
||||
- Supported heuristic families:
|
||||
- Rust: `mod`, `struct`, `enum`, `trait`, `impl`, `fn`, `const`, `static`, `type`
|
||||
- C#: `namespace`, `class`, `struct`, `enum`, `interface`, `record`, method-like members
|
||||
- JSON: object keys traversed by depth
|
||||
- TOML: tables and keys
|
||||
- YAML: indentation-based key outline
|
||||
- Flags:
|
||||
- `--depth <N>` to cap nested output
|
||||
- `--kind all|code|config`
|
||||
- Output:
|
||||
- text mode emits one compact line per item: `line depth kind name`
|
||||
- JSON mode emits per-file objects with stable `items`
|
||||
- Heuristic behavior:
|
||||
- items are marked by file-relative line number and depth, not claimed as exact AST nodes
|
||||
|
||||
### `fileprobe`
|
||||
|
||||
- Input:
|
||||
- one or more file paths from argv or stdin
|
||||
- Output fields:
|
||||
- path, extension, size, modified time
|
||||
- `exists`, `is_dir`, `is_binary`, `encoding_hint`
|
||||
- `family` such as `source`, `config`, `data`, `binary`, `archive`, `unknown`
|
||||
- `language_hint`
|
||||
- `line_count`, `blank_lines`, `longest_line`
|
||||
- heuristic flags such as `likely_generated`, `likely_minified`, `likely_test`, `likely_lockfile`, `likely_vendor`
|
||||
- optional `container_hint` such as `pe`, `zip`, `sqlite`, `pdf`
|
||||
- Heuristic behavior:
|
||||
- detect binary vs text from bytes and UTF-8 validity
|
||||
- infer family and language from extension plus lightweight content checks
|
||||
- do not parse PE deeply here; `binmeta` remains the dedicated PE inspector
|
||||
|
||||
### `chunkcat`
|
||||
|
||||
- Input:
|
||||
- one text file path at a time in v1
|
||||
- Flags:
|
||||
- `--max-lines <N>` defaulting to a budget-friendly size
|
||||
- `--overlap <N>` for deterministic overlap between chunks
|
||||
- `--chunk <INDEX>` to emit a specific chunk
|
||||
- Output:
|
||||
- without `--chunk`, emit chunk inventory only
|
||||
- with `--chunk`, emit the selected chunk with numbered lines
|
||||
- JSON mode emits chunk metadata, and chunk content only when `--chunk` is set
|
||||
- Behavior:
|
||||
- chunking is line-based and deterministic
|
||||
- line ranges are stable for the same file contents and options
|
||||
- overlapping chunks use a fixed stride of `max_lines - overlap`
|
||||
|
||||
## Shared Testing Strategy
|
||||
|
||||
- Add unit tests for:
|
||||
- selector parsing
|
||||
- heuristic file classification
|
||||
- chunk calculation
|
||||
- outline extraction helpers
|
||||
- Add integration tests for:
|
||||
- `--help` examples
|
||||
- PowerShell pipeline scenarios
|
||||
- JSON output shape for automation
|
||||
- Add fixtures for:
|
||||
- Rust source with multiple symbols
|
||||
- C# source with Unity-style class structure
|
||||
- JSON, TOML, and YAML config files
|
||||
- minified/generated-ish text and simple binary-like samples
|
||||
|
||||
## Risks
|
||||
|
||||
- Heuristic structure detection can misclassify edge-case syntax.
|
||||
- This is acceptable if outputs are useful and clearly heuristic.
|
||||
- `snip --symbol` block expansion can drift on malformed files.
|
||||
- Prefer a safe fallback to line-only snippets over panics or empty output.
|
||||
- `chunkcat` can become noisy if default chunk size is too small.
|
||||
- Pick a conservative default tuned for AI reading, not log streaming.
|
||||
@@ -0,0 +1,80 @@
|
||||
# Toolbox V1.5 Design
|
||||
|
||||
## Goal
|
||||
|
||||
Promote the existing four commands from "usable prototypes" to daily-driver tools by pairing feature upgrades with first-class help and documentation, and add a production-grade `binmeta` command for fast binary triage in AI-heavy terminal workflows.
|
||||
|
||||
## Scope
|
||||
|
||||
- Upgrade `jsonlgrep` with nested field paths and negative field predicates.
|
||||
- Upgrade `recent` with regex-based name filtering.
|
||||
- Upgrade `pathshadow` with clearer shadowing explanations in text and JSON output.
|
||||
- Upgrade `portping` with selectable HTTP method and expected status checks.
|
||||
- Add concrete examples to `--help` output for all commands.
|
||||
- Update `README.md` with scenario-driven examples and PowerShell pipeline usage.
|
||||
- Add `binmeta` as a new CLI command for binary metadata inspection on Windows PE files, with graceful handling for non-PE files.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- No GUI or TUI work.
|
||||
- No installer, release automation, or Scoop packaging in this iteration.
|
||||
- No multi-format binary analysis beyond production-grade PE support plus safe fallback summaries for unknown formats.
|
||||
|
||||
## Command Changes
|
||||
|
||||
### `jsonlgrep`
|
||||
|
||||
- Extend query syntax to support `field!=value` and `field!~=regex`.
|
||||
- Resolve dotted field paths such as `event.user.name`.
|
||||
- Treat scalar JSON values consistently so exact matches and text projections also work for numbers, booleans, and null.
|
||||
- Improve `--help` with copy-pasteable file and pipeline examples.
|
||||
|
||||
### `recent`
|
||||
|
||||
- Add `--name <REGEX>` to filter by file or directory basename.
|
||||
- Preserve `.gitignore`-aware traversal and current sorting behavior.
|
||||
- Improve `--help` with examples for recent Rust work, recent directories, and JSON pipeline usage.
|
||||
|
||||
### `pathshadow`
|
||||
|
||||
- Append stable explanation fields to JSON output so scripts and AI can tell why an entry won or lost.
|
||||
- Include PATH rank and winner path context where applicable.
|
||||
- Keep text output compact but clearer about origin and shadowing reason.
|
||||
- Improve `--help` with explicit PATH diagnosis examples.
|
||||
|
||||
### `portping`
|
||||
|
||||
- Add `--method GET|HEAD` for HTTP(S) requests.
|
||||
- Add `--expect-status` to turn mismatched HTTP status codes into probe failure while keeping actual status visible.
|
||||
- Preserve TCP behavior unchanged.
|
||||
- Improve `--help` with health-check and HEAD examples.
|
||||
|
||||
### `binmeta`
|
||||
|
||||
- Input: one or more file paths from argv or stdin lines.
|
||||
- Text output: one concise summary line per file for human scanning.
|
||||
- JSON output: one object per file with stable fields for automation and AI use.
|
||||
- PE analysis:
|
||||
- file kind, machine/architecture, subsystem, executable vs DLL hint, PE timestamp
|
||||
- section summaries
|
||||
- imported DLLs and imported symbol count summary
|
||||
- exported symbol count summary when available
|
||||
- SHA-256, file size, modified time
|
||||
- heuristic hints for `.NET`, Unity, IL2CPP, Mono, and BepInEx-related artifacts
|
||||
- Non-PE fallback:
|
||||
- still emit hash, size, modified time, file extension, and "not_pe" kind without failing the whole command
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- Add focused unit tests for new parsing helpers and negative query logic.
|
||||
- Expand integration tests to cover help examples and new CLI flags.
|
||||
- Add `binmeta` integration tests against:
|
||||
- a known text fixture for non-PE fallback
|
||||
- compiled workspace binaries for PE parsing
|
||||
- Keep the existing Jade verification gate unchanged.
|
||||
|
||||
## Risks
|
||||
|
||||
- PE parsing APIs can be noisy; the implementation should wrap parser details behind small helpers.
|
||||
- `binmeta` hints must remain heuristic and clearly labeled as hints, not definitive claims.
|
||||
- Help text examples must stay in sync with actual behavior, so tests should assert representative help fragments.
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
# Mercury Toolbox Daily Maintenance Template
|
||||
|
||||
Use this template for small, behavior-preserving maintenance passes. Start from the durable backlog, choose a narrow scope, and stop with evidence instead of broad cleanup drift.
|
||||
|
||||
## Header
|
||||
|
||||
- Date:
|
||||
- Worker or scope:
|
||||
- Starting branch:
|
||||
- Initial worktree status:
|
||||
- Backlog source: `.codex-progress\quality-security-backlog.md`
|
||||
- Candidate review quota:
|
||||
- Actual candidate slots reviewed:
|
||||
- Existing unrelated changes to avoid:
|
||||
|
||||
## Scope
|
||||
|
||||
- Owned files or surfaces:
|
||||
- Explicitly out of scope:
|
||||
- Other workers expected nearby:
|
||||
- Conflict-avoidance note:
|
||||
|
||||
## Candidate Scan
|
||||
|
||||
List only concrete, evidence-backed candidates. Prefer stale references, duplicated docs snippets, recipe naming consistency, metadata drift, and tiny verification hygiene.
|
||||
|
||||
| # | Candidate | Evidence | Risk | Decision |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | | | low \| medium \| high | land \| skip |
|
||||
|
||||
When a worker receives a numbered quota, keep this table countable even if most entries are skipped. Use one row per backlog item or directly evidenced follow-up.
|
||||
Group obvious no-edit candidates by range only when the reason is identical, for example generated assets that must be regenerated by script or code-owner items outside the worker's surface.
|
||||
|
||||
## Landed Changes
|
||||
|
||||
- [ ] Tiny change:
|
||||
- [ ] Tiny change:
|
||||
- [ ] Tiny change:
|
||||
|
||||
## Skipped Candidates
|
||||
|
||||
- Candidate:
|
||||
Reason:
|
||||
- Candidate:
|
||||
Reason:
|
||||
|
||||
## CI And Runner Notes
|
||||
|
||||
- Runner or CI files inspected:
|
||||
- Toolchain snapshot expectations changed: yes | no
|
||||
- Release or publish path touched: yes | no
|
||||
- Runner credential or token surfaces checked: yes | no | not applicable
|
||||
- Secret-residue checks:
|
||||
- `git remote -v`:
|
||||
- `.git\config`:
|
||||
- Targeted `rg` scan:
|
||||
|
||||
## Verification
|
||||
|
||||
Choose the smallest proof that covers the touched surface.
|
||||
|
||||
```powershell
|
||||
just --summary
|
||||
just ai-check
|
||||
just periphery-check
|
||||
cargo fmt --all --check
|
||||
just --fmt --check
|
||||
pwsh -NoProfile -File .\scripts\check-powershell.ps1
|
||||
pwsh -NoProfile -File .\scripts\check-ai-prompt.ps1 -Configuration ReleaseFast -SkipBuild
|
||||
pwsh -NoProfile -File .\scripts\check-ai-skill.ps1 -Configuration ReleaseFast -SkipBuild
|
||||
```
|
||||
|
||||
- Commands run:
|
||||
- Outcomes:
|
||||
- Commands intentionally not run:
|
||||
|
||||
## Handoff
|
||||
|
||||
- Changed files:
|
||||
- Micro-optimizations landed:
|
||||
- Follow-up backlog items:
|
||||
- Commit:
|
||||
- Push: not run unless explicitly requested
|
||||
+133
@@ -0,0 +1,133 @@
|
||||
# Jade Feature Template
|
||||
|
||||
Use this template for any new Mercury Toolbox feature, command, subcommand, output mode, parser path, generated asset, or cross-tool behavior change. Keep the filled copy close to the work item, then remove sections that truly do not apply before merging.
|
||||
|
||||
## Header
|
||||
|
||||
- Feature:
|
||||
- Owner:
|
||||
- Date:
|
||||
- Status: draft | implementing | verifying | ready
|
||||
- Tracking issue or branch:
|
||||
- Affected crates, scripts, and docs:
|
||||
|
||||
## Intent
|
||||
|
||||
- User problem:
|
||||
- Primary workflow:
|
||||
- Non-goals:
|
||||
- Compatibility promise:
|
||||
- Rollback or fallback plan:
|
||||
|
||||
## User-Facing Contract
|
||||
|
||||
Write the exact CLI shape before coding.
|
||||
|
||||
```powershell
|
||||
<command> --help
|
||||
<command> <subcommand> --help
|
||||
<command> --json <example-input>
|
||||
<command> --toon <example-input>
|
||||
```
|
||||
|
||||
- Text output:
|
||||
- JSON schema or fields:
|
||||
- TOON shape:
|
||||
- Exit codes:
|
||||
- Stdin behavior:
|
||||
- Path, glob, and missing-root behavior:
|
||||
- Windows-specific behavior:
|
||||
- Cross-platform behavior:
|
||||
|
||||
## Codebase Fit
|
||||
|
||||
- Existing command or helper to mirror:
|
||||
- Shared helper APIs to reuse:
|
||||
- New dependencies: none | list with reason
|
||||
- Feature flags or platform cfgs:
|
||||
- Generated files that must be regenerated:
|
||||
- Packaging or install changes:
|
||||
|
||||
## Test Plan First
|
||||
|
||||
Write the first failing test before implementation.
|
||||
|
||||
- Red test command:
|
||||
|
||||
```powershell
|
||||
cargo nextest run -p <crate> --test <test-name> <filter>
|
||||
```
|
||||
|
||||
- Expected failing assertion:
|
||||
- Green command after implementation:
|
||||
- Regression cases:
|
||||
- Parser/help contract cases:
|
||||
- Error-path cases:
|
||||
- Platform-specific cases:
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Add or update failing tests first.
|
||||
- [ ] Reuse `common` helpers for shared CLI, path, stdin, format, color, and error behavior.
|
||||
- [ ] Keep public Rust APIs documented, including `# Errors` and `# Panics` where applicable.
|
||||
- [ ] Avoid `.unwrap()`, `.expect()`, and `panic!` in production paths unless a narrow `// jade: allow-panic because: <reason>` comment is justified beside the call site.
|
||||
- [ ] Keep subcommand `--help` aligned with parser-supported flags.
|
||||
- [ ] Preserve literal paths unless a documented glob mode is explicitly requested.
|
||||
- [ ] Keep `--json`, `--toon`, and `--format text|json|toon` behavior consistent with the toolbox contract.
|
||||
- [ ] Update README or command docs when user-facing behavior changes.
|
||||
- [ ] Update `docs/ai/toolbox-ai-prompt-notes.json` when AI routing, examples, caveats, or command coverage changes.
|
||||
- [ ] Regenerate generated AI assets instead of hand-editing them.
|
||||
- [ ] Update package/install scripts only when the shipped artifact surface changes.
|
||||
|
||||
## Jade Verification
|
||||
|
||||
Focused loop:
|
||||
|
||||
```powershell
|
||||
cargo fmt --all --check
|
||||
cargo nextest run -p <crate> --all-targets --all-features
|
||||
cargo clippy -p <crate> --all-targets --all-features -- -D warnings -W clippy::pedantic -W clippy::nursery
|
||||
```
|
||||
|
||||
Docs or generated AI asset loop:
|
||||
|
||||
```powershell
|
||||
just --summary
|
||||
pwsh -NoProfile -File .\scripts\check-powershell.ps1
|
||||
pwsh -NoProfile -File .\scripts\check-ai-prompt.ps1 -Configuration ReleaseFast -SkipBuild
|
||||
pwsh -NoProfile -File .\scripts\check-ai-skill.ps1 -Configuration ReleaseFast -SkipBuild
|
||||
```
|
||||
|
||||
Shared behavior or broad refactor loop:
|
||||
|
||||
```powershell
|
||||
$env:CARGO_INCREMENTAL = '0'
|
||||
cargo nextest run --workspace --all-targets --all-features --no-fail-fast
|
||||
Remove-Item Env:\CARGO_INCREMENTAL
|
||||
```
|
||||
|
||||
Full Jade gate before claiming repository-clean status:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\check-jade.ps1
|
||||
```
|
||||
|
||||
If a hardening gate cannot run on the current machine, use only the specific `-Exempt*` flag with a non-empty reason. Do not add a CI skip, broad allow, or permanent template bypass.
|
||||
|
||||
## Review Checklist
|
||||
|
||||
- [ ] The diff is scoped to the feature and does not include unrelated cleanup.
|
||||
- [ ] Existing behavior is either preserved or deliberately documented as changed.
|
||||
- [ ] Help text, parser support, README/docs, generated AI prompt, and skill catalog agree.
|
||||
- [ ] Tests cover success, failure, and format-specific output where relevant.
|
||||
- [ ] `cargo nextest` is the test signal; plain `cargo test` is not used as the main proof.
|
||||
- [ ] Verification commands and outcomes are recorded in the final handoff.
|
||||
- [ ] Worktree is clean after commit or intentionally lists follow-up files.
|
||||
|
||||
## Handoff Notes
|
||||
|
||||
- What changed:
|
||||
- Tradeoffs:
|
||||
- Verification run:
|
||||
- Known follow-ups:
|
||||
- Commit:
|
||||
+71
@@ -0,0 +1,71 @@
|
||||
# Mercury Toolbox Release Notes Template
|
||||
|
||||
Use this template when publishing a release on Gitea. Keep it short, concrete, and oriented around what changed for someone installing or upgrading the toolbox.
|
||||
|
||||
## Title
|
||||
|
||||
`Mercury Toolbox vX.Y.Z`
|
||||
|
||||
## Summary
|
||||
|
||||
One short paragraph:
|
||||
|
||||
- What kind of release this is.
|
||||
- Who should care.
|
||||
- Whether there are any rename, install, or compatibility notes.
|
||||
|
||||
Example:
|
||||
|
||||
> Mercury Toolbox vX.Y.Z focuses on local inspection and packaging polish. This release updates the hashing command surface to `mhash`, refreshes the packaged Codex skill and AI prompt assets, and keeps the Windows + PowerShell install path aligned with the current release bundle.
|
||||
|
||||
## Highlights
|
||||
|
||||
- `Command / feature:` what changed and why it matters.
|
||||
- `Command / feature:` what changed and why it matters.
|
||||
- `Packaging / docs / skills:` what changed and why it matters.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
- `Old name or behavior -> new name or behavior`
|
||||
- `Migration note`
|
||||
|
||||
If none:
|
||||
|
||||
- None.
|
||||
|
||||
## Install Or Upgrade
|
||||
|
||||
Fresh install:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\scripts\install-toolbox.ps1
|
||||
```
|
||||
|
||||
Portable package install:
|
||||
|
||||
```powershell
|
||||
pwsh -NoProfile -File .\dist\MercuryToolbox-<host-target>-ReleaseFast\scripts\install-package-toolbox.ps1
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
- Built with: `ReleaseFast | ReleaseSize | Debug`
|
||||
- Key verification commands:
|
||||
- `cargo nextest run -p <crate> --all-features`
|
||||
- `pwsh -NoProfile -File .\scripts\check-powershell.ps1`
|
||||
- `pwsh -NoProfile -File .\scripts\generate-ai-prompt.ps1`
|
||||
- `pwsh -NoProfile -File .\scripts\generate-ai-skill.ps1`
|
||||
- `pwsh -NoProfile -File .\scripts\check-ai-prompt.ps1 -Configuration ReleaseFast -SkipBuild`
|
||||
- `pwsh -NoProfile -File .\scripts\check-ai-skill.ps1 -Configuration ReleaseFast -SkipBuild`
|
||||
- `pwsh -NoProfile -File .\scripts\package-toolbox.ps1`
|
||||
|
||||
## Assets
|
||||
|
||||
- `MercuryToolbox-<host-target>-ReleaseFast.zip`
|
||||
- Optional extra artifacts
|
||||
|
||||
## Notes For Upgraders
|
||||
|
||||
- PATH reload or shell restart note if relevant.
|
||||
- Config, skill, or naming migration note if relevant.
|
||||
- Any intentionally removed compatibility surface.
|
||||
Reference in New Issue
Block a user