refactor(cli): normalize policy command ids

[cv]

Summary

Start normalizing sandbox-scoped internal command IDs by moving policy commands to topic-style IDs. Public CLI syntax stays unchanged (policy-add, policy-remove, policy-list).

Stack Navigation

• Position: 25 of 60
• Previous PR: #2917 — refactor(cli): rename oclif dispatch module
• Next PR: #2919 — test(cli): require oclif command metadata

Changes

• Renamed internal policy command IDs to sandbox:policy:add, sandbox:policy:remove, and sandbox:policy:list.
• Updated dispatch routing and oclif command registration for the new IDs.
• Updated dispatch tests for the normalized IDs.

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 sandbox:doctor CLI command

• Improvements

  • Updated sandbox policy command naming: sandbox:policy:add, sandbox:policy:list, sandbox:policy:remove
  • Enhanced sandbox:config get with JSON and YAML format options
  • Added CLI usage examples for sandbox status, policy list, channels list, and config commands

[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

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 902b503a-204a-40b9-bfd9-044d0eea7db3

📥 Commits

Reviewing files that changed from the base of the PR and between 9499ca6 and 944b9aa.

📒 Files selected for processing (3)

• src/lib/oclif-commands.ts
• src/lib/oclif-dispatch.test.ts
• src/lib/oclif-dispatch.ts

---

📝 Walkthrough

Walkthrough

This PR modernizes the CLI command registry and routing by adding a new sandbox:doctor command, renaming policy command keys from hyphenated to colon-delimited format, removing the legacy dispatch fallback mechanism, and enhancing command metadata with examples and usage strings for improved UX.

Changes

CLI Command Routing Modernization

Layer / File(s)	Summary
Command Registry src/lib/oclif-commands.ts	Added sandbox:doctor command. Renamed policy command keys from sandbox:policy-add|list|remove to sandbox:policy:add|list|remove while preserving handler references.
Routing Logic src/lib/oclif-dispatch.ts	Removed LegacyDispatch mechanism from DispatchResult union. Updated resolveSandboxOclifDispatch to route doctor, policy-add, skill, and snapshot directly through oclif adapters instead of legacy fallbacks. Expanded help and usage strings for logs, destroy, rebuild, and policy-add.
Command Metadata src/lib/policy-mutate-cli-commands.ts, src/lib/sandbox-inspection-cli-command.ts	Added static examples arrays to PolicyAddCommand, PolicyRemoveCommand, SandboxStatusCommand, SandboxPolicyListCommand, SandboxChannelsListCommand, and SandboxConfigGetCommand. Updated usage declarations and expanded SandboxConfigGetCommand.flags.format with explicit options: ["json", "yaml"] constraint.
Tests & Validation src/lib/oclif-dispatch.test.ts	Added test cases verifying status, doctor, recover, logs routing and help behavior; confirming policy-add --from-file, skill, and snapshot route through oclif with correct command IDs and forwarded arguments.

Sequence Diagram

sequenceDiagram
    participant User
    participant Dispatch as resolveSandboxOclifDispatch
    participant Handlers as Oclif Handlers
    
    User->>Dispatch: sandbox doctor [args]
    Dispatch->>Dispatch: Check action == "doctor"
    Dispatch->>Handlers: Route to sandbox:doctor command
    Handlers->>Handlers: Execute SandboxDoctorCliCommand
    Handlers-->>User: Result
    
    User->>Dispatch: sandbox policy-add --from-file file.yaml
    Dispatch->>Dispatch: Check action == "policy-add"
    Dispatch->>Handlers: Route to sandbox:policy:add command
    Handlers->>Handlers: Execute PolicyAddCommand
    Handlers-->>User: Result
    
    User->>Dispatch: sandbox doctor --help
    Dispatch->>Dispatch: Detect --help flag
    Dispatch-->>User: Return help usage (public, not routed)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~22 minutes

Poem

🐰 The doctor's in—no more legacy ways!
Commands now routed through modern displays,
With : delimiters, policies refined,
Examples and options beautifully aligned,
The sandbox shines bright in its freshly oclif'd days! 🌟

✨ 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-arch-normalize-policy-ids

---

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

[cjagwani]

Approved as part of stack from #2886 (auto-approve: CI green, no scope/behavior flags).