feat: project runner commands can show their own detailed --help

[hatayama]

Summary

• Runner-owned native commands (await-pause-point, pause-point-status, list, sync, focus-window) now have their --help flag list defined and rendered from the project runner binary itself.

User Impact

• Today the dispatcher's --help output for these commands comes from a hardcoded options table that can drift out of sync with the pinned runner version, and requires a dispatcher code change (and release) whenever a runner-owned command gains a flag.
• This change is additive only: it adds the same help output inside the project runner, so a follow-up change can forward --help for these commands to the runner instead of the dispatcher's static table, keeping the flag list and its help text defined in one place.

Changes

• Added native_command_help.go in cli/project-runner: a per-command option table and formatter matching the dispatcher's existing help layout (Usage, description, Options, Global options).
• Wired RunProjectLocal's --help handling to print this command-specific help for runner-owned commands, falling back to the existing minimal runner usage otherwise.

Verification

• bash scripts/check-go-cli.sh passed (fmt/vet/lint/tests/binary rebuild), exit code 0.
• Added tests asserting expected flags appear in await-pause-point --help / pause-point-status --help, and that list/sync/focus-window --help show only the global --project-path option with no command-specific Options section.
• Confirmed the new tests actually exercise the assertions by temporarily breaking one expected flag string and observing the test fail, then restoring it and re-running to green.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a3fa5c7d-69e1-4717-8165-d93703798b2a

📥 Commits

Reviewing files that changed from the base of the PR and between 985d3fe and c511699.

📒 Files selected for processing (3)

• cli/project-runner/internal/projectrunner/native_command_help.go
• cli/project-runner/internal/projectrunner/native_command_help_test.go
• cli/project-runner/internal/projectrunner/run.go

---

📝 Walkthrough

Walkthrough

Adds native-command-specific help for projectrunner, including sorted command options and the global project path flag. RunProjectLocal now returns after printing native help, with tests covering option-bearing and global-only commands.

Changes

Native command help

Layer / File(s)	Summary
Implement native command help cli/project-runner/internal/projectrunner/native_command_help.go, cli/project-runner/internal/projectrunner/run.go	Defines runner-owned command options, renders deterministic usage and option sections, and routes recognized help requests through native help output.
Validate command help output cli/project-runner/internal/projectrunner/native_command_help_test.go	Tests expected flags for pause-point commands and confirms list, sync, and focus-window show only the global project-path option.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant RunProjectLocal
  participant NativeCommandHelp
  CLI->>RunProjectLocal: request command help
  RunProjectLocal->>NativeCommandHelp: tryPrintNativeCommandHelp
  NativeCommandHelp-->>CLI: print usage and options
  RunProjectLocal-->>CLI: return exit code 0

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: runner-owned commands now have detailed native --help output.
Description check	✅ Passed	The description matches the code changes and explains the new native help rendering, wiring, and tests.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/runner-native-command-help

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}