[PR #1418] [CLOSED] fix(cli): describe native command options accurately in help #2872

New issue

Closed

opened 2026-10-17 21:11:16 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-17 21:11:16 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1418
Author: @Fazmin
Created: 10/10/2026
Status: ❌ Closed

Base: main ← Head: fix/cli-native-help-text

📝 Commits (1)

52ce382 fix(cli): describe native command options accurately in help

📊 Changes

3 files changed (+15 additions, -2 deletions)

View changed files

📝 src/cli/coreNativeCommands.ts (+1 -1)
📝 src/cli/utilityCommands.ts (+1 -1)
📝 tests/boundary/cli/cliOptionAliases.test.ts (+13 -0)

📄 Description

Summary

Two native CLI help entries were wrong:

rea inspect-native-data-type --help shows --address with no description at all.
rea inspect-plist --help states a default that doesn't apply to iOS-style bundles and doesn't mention absolute paths.

This PR corrects both and adds a help test that fails if any advertised command option has a blank description. No issue is linked because this is a small, self-contained fix.

Problem and expected behavior

Blank --address: src/cli/coreNativeCommands.ts declared z.string().describe("Exact native address").optional(). Calling .optional() after .describe() drops the description from incur's human-readable help, so the help printed --address <string> followed by nothing. --schema still carried the description, and the sibling --type option, which uses .optional().describe(…), rendered correctly. This was the only blank option across all primary commands.
--relative-path default: the help said (default: Contents/Info.plist). resolvePlistPath in NativeMacOSProvider.ts actually uses the Info.plist the bundle target recorded (the root Info.plist of an iOS-style bundle), falling back to Contents/Info.plist. It also accepts absolute paths. The MCP inspect_plist contract already describes this: "Parse Info.plist from the active artifact by default, or pass any local plist path."

Change and scope

--address: use .optional().describe(…).
--relative-path: reword to "Plist path relative to the app root, or an absolute path (default: the bundle's Info.plist)".
tests/boundary/cli/cliOptionAliases.test.ts: add a check that walks every primary command's --help and rejects option lines with no description. It reuses that file's existing per-command help walk.

No parsing or runtime behavior changes.

Contract and boundary impact

Semantic owner and earliest changed stage: CLI option descriptions
CLI and MCP/tool-catalog contract: CLI help text only; option names, types and parsing are unchanged; MCP is unchanged
Provider, bridge, target-format, or platform compatibility: none
Evidence, artifact, provenance, or reconstruction contract: none
Process execution, authorization, cleanup, or containment impact: none
Generated metadata, package, or installation impact: the generated catalog picks up the corrected descriptions; npm run docs:check passes

Evidence and regression coverage

Tests added or updated: CLI option aliases › describe every advertised command option.
Base reproduction: on the base revision the new test fails with ["inspect-native-data-type --address <string>"], and passes with this change.

User-visible output (rebuilt CLI):

$ rea inspect-native-data-type --help
  --address <string>       Exact native address
$ rea inspect-plist --help
  --relative-path <string>  Plist path relative to the app root, or an absolute path (default: the bundle's Info.plist)

Remaining proof gaps: none known. This changes help text only.

Validation performed

All commands ran on macOS (arm64) with Node 24.18.0 and npm 11.16.0:

npm run test:focused -- tests/boundary/cli/cliOptionAliases.test.ts: 3 passed. The new case fails on the base revision.
npm run check: passed.
npm run docs:check: passed.
npm run build:cached, then rea <command> --help for both commands: output shown above.

Compatibility, safety, and release

Breaking changes or migration steps: none
Real Hopper/Ghidra, browser, or OS coverage: not applicable (help text only)
Package or release metadata impact: none
Security, privacy, process, or containment review: none

Review checklist

This PR addresses a concrete problem or an agreed enhancement.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/1418 **Author:** [@Fazmin](https://github.com/Fazmin) **Created:** 10/10/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/cli-native-help-text` --- ### 📝 Commits (1) - [`52ce382`](https://github.com/morluto/rea/commit/52ce3821edb8bbe75735e691f0a28c65ebaa63fa) fix(cli): describe native command options accurately in help ### 📊 Changes **3 files changed** (+15 additions, -2 deletions) <details> <summary>View changed files</summary> 📝 `src/cli/coreNativeCommands.ts` (+1 -1) 📝 `src/cli/utilityCommands.ts` (+1 -1) 📝 `tests/boundary/cli/cliOptionAliases.test.ts` (+13 -0) </details> ### 📄 Description ## Summary Two native CLI help entries were wrong: - `rea inspect-native-data-type --help` shows `--address` with no description at all. - `rea inspect-plist --help` states a default that doesn't apply to iOS-style bundles and doesn't mention absolute paths. This PR corrects both and adds a help test that fails if any advertised command option has a blank description. No issue is linked because this is a small, self-contained fix. ## Problem and expected behavior - **Blank `--address`:** `src/cli/coreNativeCommands.ts` declared `z.string().describe("Exact native address").optional()`. Calling `.optional()` after `.describe()` drops the description from incur's human-readable help, so the help printed `--address <string>` followed by nothing. `--schema` still carried the description, and the sibling `--type` option, which uses `.optional().describe(…)`, rendered correctly. This was the only blank option across all primary commands. - **`--relative-path` default:** the help said `(default: Contents/Info.plist)`. `resolvePlistPath` in `NativeMacOSProvider.ts` actually uses the Info.plist the bundle target recorded (the root `Info.plist` of an iOS-style bundle), falling back to `Contents/Info.plist`. It also accepts absolute paths. The MCP `inspect_plist` contract already describes this: "Parse Info.plist from the active artifact by default, or pass any local plist path." ## Change and scope - `--address`: use `.optional().describe(…)`. - `--relative-path`: reword to "Plist path relative to the app root, or an absolute path (default: the bundle's Info.plist)". - `tests/boundary/cli/cliOptionAliases.test.ts`: add a check that walks every primary command's `--help` and rejects option lines with no description. It reuses that file's existing per-command help walk. No parsing or runtime behavior changes. ## Contract and boundary impact - Semantic owner and earliest changed stage: CLI option descriptions - CLI and MCP/tool-catalog contract: CLI help text only; option names, types and parsing are unchanged; MCP is unchanged - Provider, bridge, target-format, or platform compatibility: none - Evidence, artifact, provenance, or reconstruction contract: none - Process execution, authorization, cleanup, or containment impact: none - Generated metadata, package, or installation impact: the generated catalog picks up the corrected descriptions; `npm run docs:check` passes ## Evidence and regression coverage - **Tests added or updated:** `CLI option aliases › describe every advertised command option`. - **Base reproduction:** on the base revision the new test fails with `["inspect-native-data-type --address <string>"]`, and passes with this change. - **User-visible output (rebuilt CLI):** ``` $ rea inspect-native-data-type --help --address <string> Exact native address $ rea inspect-plist --help --relative-path <string> Plist path relative to the app root, or an absolute path (default: the bundle's Info.plist) ``` - **Remaining proof gaps:** none known. This changes help text only. ## Validation performed All commands ran on macOS (arm64) with Node 24.18.0 and npm 11.16.0: - `npm run test:focused -- tests/boundary/cli/cliOptionAliases.test.ts`: 3 passed. The new case fails on the base revision. - `npm run check`: passed. - `npm run docs:check`: passed. - `npm run build:cached`, then `rea <command> --help` for both commands: output shown above. ## Compatibility, safety, and release - Breaking changes or migration steps: none - Real Hopper/Ghidra, browser, or OS coverage: not applicable (help text only) - Package or release metadata impact: none - Security, privacy, process, or containment review: none ## Review checklist - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-17 21:11:16 +00:00