chore(release): prepare public source release

2026-07-18 15:41:59 +08:00
commit e365e5df4d
508 changed files with 163373 additions and 0 deletions
@@ -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: