refactor(cli): improve sandbox diagnostic command metadata

[cv]

Summary

Improve the oclif metadata and parser-owned validation for read-only sandbox diagnostic commands. This keeps public sandbox-scoped help output stable while making doctor and config get validation stricter in the command adapter.

Stack Navigation

• Position: 14 of 60
• Previous PR: #2905 — refactor(cli): validate logs flags with oclif
• Next PR: #2907 — refactor(cli): tighten policy and channel parser validation

Changes

• Added examples for connect, sandbox-scoped status, doctor, config get, policy-list, and channels list adapters.
• Made sandbox:doctor a strict oclif command with a required sandbox arg and --json flag.
• Moved config get --format validation into oclif with json|yaml options and removed the adapter-level manual format check.
• Preserved public doctor --help output through legacy dispatch and expanded diagnostics validation coverage.
• Updated the hidden command registry metadata for config get flags.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• New Features

  • Added command usage examples to help documentation for configuration, status, policy, and channels commands.
  • Enhanced doctor command with explicit --json flag support.

• Improvements

  • Updated configuration command help text to clearly advertise available options (--key and --format json|yaml).
  • Restricted --format flag to json and yaml values with stricter validation.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 716c42fd-0b88-4ec4-aa97-8420fb0b0b43

📥 Commits

Reviewing files that changed from the base of the PR and between 12a3850 and 00cbd63.

📒 Files selected for processing (7)

• src/lib/command-registry.ts
• src/lib/connect-cli-command.ts
• src/lib/legacy-oclif-dispatch.test.ts
• src/lib/legacy-oclif-dispatch.ts
• src/lib/sandbox-doctor-cli-command.ts
• src/lib/sandbox-inspection-cli-command.ts
• test/cli.test.ts

---

📝 Walkthrough

Walkthrough

The PR removes legacy dispatch handling and migrates sandbox commands to oclif-based argument and flag parsing with constrained options. The LegacyDispatch type is eliminated, doctor and logs commands gain explicit help handling, and CLI commands now declare arguments and flags explicitly instead of processing argv manually.

Changes

Command Parsing Modernization & Legacy Dispatch Removal

Layer / File(s)	Summary
Type & Dispatch Updates src/lib/legacy-oclif-dispatch.ts	LegacyDispatch type removed; DispatchResult simplified to exclude legacy variants. doctor gains explicit help dispatch returning usage: "doctor [--json]"; logs help text expanded to document --follow, --tail, --since.
Command Parsing Implementation src/lib/sandbox-doctor-cli-command.ts, src/lib/sandbox-inspection-cli-command.ts	SandboxDoctorCliCommand migrates to oclif Args/Flags with strict parsing; SandboxConfigGetCommand --format flag constrained to ["json", "yaml"] via oclif options; runtime validation removed.
CLI Metadata src/lib/command-registry.ts, src/lib/connect-cli-command.ts	nemoclaw <name> config get command registry updated with flags metadata (`[--key ] [--format json
Command Examples & Metadata src/lib/sandbox-inspection-cli-command.ts	SandboxStatusCommand, SandboxPolicyListCommand, and SandboxChannelsListCommand gain static examples entries. SandboxConfigGetCommand examples expanded.
Test Coverage src/lib/legacy-oclif-dispatch.test.ts, test/cli.test.ts	New test validates doctor --help returns help dispatch. CLI test expectations updated for alpha doctor --help output; alpha config get --help now requires `--format json

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 The legacy chains now break and fade,
Each command stands in oclif's shade,
With flags that sparkle, constrained and bright,
We parse before we dispatch right!
No more wild argv, just structured delight. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately reflects the primary changes: adding examples and improving oclif metadata for sandbox diagnostic commands (doctor, config get, status, policy-list, channels list), while also refactoring dispatch logic and validation rules.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 refactor/oclif-ux-sandbox-diagnostics

---

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

[prekshivyas]

LGTM after rebase. 7 files / +61 / -9 — small, well-tested.

Two intentional validation tightenings (both declared in the PR description, both well-covered by tests):

• SandboxDoctorCliCommand: strict = false → strict = true with explicit Args.string for sandboxName and Flags.boolean for --json. Unknown flags like --bogus are now rejected at parse time instead of silently ignored. Test added.
• SandboxConfigGetCommand.--format: manual format check replaced with oclif's options: ["json", "yaml"]. Same non-zero exit, slightly different error message wording (still contains --format, json, yaml). Test added.

Plus examples added to connect/status/doctor/config get/policy-list/channels list and doctor --help now routes through legacy dispatch's help branch so user-facing help stays free of sandbox:doctor command-id leakage.

src/nemoclaw.ts untouched — cumulative ~16-orphan debt unchanged. CI: pr.yaml mostly green; pr-self-hosted builds and wsl-e2e/checks still in flight at review time. No failures.