81 lines
3.6 KiB
Markdown
81 lines
3.6 KiB
Markdown
# 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.
|