refactor(cli): add oclif examples for utility commands

[cv]

Summary

Add oclif examples to low-risk global and utility commands so generated help has concrete usage snippets. This starts the oclif UX pass without changing command behavior.

Stack Navigation

• Position: 12 of 60
• Previous PR: #2901 — refactor(cli): expose explicit main entrypoint
• Next PR: #2905 — refactor(cli): validate logs flags with oclif

Changes

• Added examples for list, global status, gateway-token, credentials, credentials list, and credentials reset.
• Added examples for backup-all, upgrade-sandboxes, and gc.
• Added examples for uninstall, tunnel start, tunnel stop, and deprecated start/stop aliases.
• Added a help flag declaration to the uninstall oclif adapter to align its metadata with other utility commands.

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

Release Notes

• New Features

  • Added sandbox doctor command for comprehensive health diagnostics across sandbox infrastructure, gateway, and services
  • Introduced automated sandbox process recovery and health probing capabilities
  • Enhanced sandbox lifecycle management with improved destroy, rebuild, and skill installation workflows

• Documentation

  • Expanded CLI usage examples across multiple commands for improved discoverability and guidance

[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

📝 Walkthrough

Walkthrough

This PR refactors sandbox operation logic from a centralized nemoclaw-runtime-bridge module into dedicated per-action modules, eliminates legacy dispatch routing, and adds CLI command examples. New standalone action files implement sandbox connect, destroy, doctor, gateway state, process recovery, rebuild, skill install, and status workflows. CLI dispatch is simplified by removing the LegacyDispatch type and converting legacy cases to oclif commands. A runtime hook system is introduced to support test injection. Terminal styling utilities are extracted into a new module.

Changes

Sandbox Runtime Actions Extraction

Layer / File(s)	Summary
Utility Modules src/lib/terminal-style.ts	New ANSI terminal color constants (G, B, D, R, RD, YW) with TTY/NO_COLOR detection and conditional output control.
Data & State Management src/lib/sandbox-gateway-state-action.ts	Defines SandboxGatewayState type and reconciliation logic for querying/validating sandbox presence in live gateway, handling ambiguous gateway states, and enforcing sandbox readiness with guidance output.
Core Sandbox Operations src/lib/sandbox-connect-action.ts, src/lib/sandbox-destroy-action.ts, src/lib/sandbox-rebuild-action.ts, src/lib/sandbox-skill-install-action.ts, src/lib/sandbox-status-action.ts, src/lib/sandbox-doctor-action.ts, src/lib/upgrade-sandboxes-action.ts	Extracted sandbox action implementations: connect (with probing/readiness wait), destroy (with cleanup/registry removal), rebuild (with backup/restore flow), skill install (with file validation), status (with health check/reconciliation), doctor (with health check suite), and upgrade-sandboxes (with version checking/batch rebuild).
Process Health & Recovery src/lib/sandbox-process-recovery-action.ts	Implements sandbox process probing and automated recovery via SSH/exec, gateway health detection, and polling utilities for recovery verification.
Legacy Bridge Removal & Delegation src/lib/nemoclaw-runtime-bridge.ts, src/lib/sandbox-runtime-actions.ts, src/lib/global-cli-actions.ts	Deletes nemoclaw-runtime-bridge.ts; updates sandbox-runtime-actions.ts to dynamically require dedicated action modules instead of bridge; adds runtime hook injection in global-cli-actions.ts for test support.
Test Integration test/credentials-cli-command.test.ts, test/image-cleanup.test.ts	Updates test harness to use setGlobalCliActionRuntimeHooksForTest() for runtime injection; refactors image cleanup tests to directly import and test sandbox-destroy-action helpers instead of regex-parsing source.

CLI Routing & Command Updates

Layer / File(s)	Summary
Dispatch Type Cleanup src/lib/legacy-oclif-dispatch.ts, src/lib/legacy-oclif-dispatch.test.ts	Removes LegacyDispatch type; converts sandbox doctor, policy-add (raw mode), skill, and snapshot routing from legacy dispatch to oclif command dispatch; adds test coverage for new routes.
Command Registry & Wiring src/lib/oclif-commands.ts, src/lib/policy-mutate-cli-commands.ts, src/lib/skill-install-cli-command.ts, src/lib/snapshot-cli-commands.ts, src/lib/sandbox-doctor-cli-command.ts	Registers new CLI commands: sandbox:doctor, sandbox:policy-add:raw (hidden, non-strict), sandbox:skill (base), and sandbox:snapshot; updates import/export wiring to include new command classes.
Dependency Refactoring src/lib/share-command-deps.ts	Removes internal runtime bridge abstraction; directly requires captureOpenshell and ensureLiveSandboxOrExit modules with local type casts; preserves public ShareCommandDeps interface.

CLI Examples & Metadata

Layer / File(s)	Summary
Command Examples src/lib/credentials-cli-command.ts, src/lib/gateway-token-cli-command.ts, src/lib/list-command.ts, src/lib/maintenance-cli-commands.ts, src/lib/status-command.ts, src/lib/tunnel-commands.ts, src/lib/uninstall-cli-command.ts	Adds static examples property to 13 CLI command classes with example invocation strings using <%= config.bin %> template.
Documentation Reference Update src/lib/skill-install.ts	Updates JSDoc reference from nemoclaw.ts to sandbox-process-recovery-action.ts for command execution helper.

Sequence Diagram(s)

sequenceDiagram
    actor User
    participant CLI as CLI Handler
    participant State as Gateway State
    participant Recovery as Process Recovery
    participant OpenShell as OpenShell Runtime

    User->>CLI: sandbox destroy <name>
    CLI->>State: ensureLiveSandboxOrExit(name)
    State->>OpenShell: sandbox list
    OpenShell-->>State: live sandbox data
    State-->>CLI: { present: true }
    
    CLI->>Recovery: checkAndRecoverSandboxProcesses(name)
    Recovery->>OpenShell: health probe
    OpenShell-->>Recovery: RUNNING
    Recovery-->>CLI: { checked, wasRunning, recovered }
    
    CLI->>OpenShell: sandbox delete <name>
    OpenShell-->>CLI: delete result
    CLI->>CLI: getSandboxDeleteOutcome(result)
    CLI->>CLI: removeSandboxRegistryEntry(name)
    CLI-->>User: ✓ Sandbox destroyed

Loading

sequenceDiagram
    actor User
    participant CLI as Rebuild CLI
    participant Backup as Backup System
    participant OpenShell as OpenShell Runtime
    participant Onboard as Onboard Engine

    User->>CLI: sandbox rebuild <name>
    CLI->>CLI: Load registry entry
    CLI->>CLI: Confirm with user
    
    CLI->>Backup: backupSandboxState(name)
    Backup-->>CLI: backup manifest
    
    CLI->>OpenShell: sandbox delete <name>
    OpenShell-->>CLI: delete result
    
    CLI->>Onboard: onboard({ resume: true, recreateSandbox: true })
    Onboard->>OpenShell: create sandbox
    OpenShell-->>Onboard: sandbox ready
    Onboard-->>CLI: recreation complete
    
    CLI->>Backup: restoreSandboxState(name, manifest)
    Backup-->>CLI: restore complete
    CLI->>CLI: applyPreset(...) for each policy
    CLI-->>User: ✓ Rebuild complete

Loading

sequenceDiagram
    participant Test as Test Suite
    participant Cache as require.cache
    participant GlobalActions as global-cli-actions
    participant Runtime as Mock Runtime

    Test->>Test: Create mock runtime
    Test->>GlobalActions: require(GLOBAL_ACTIONS_PATH)
    Test->>GlobalActions: setGlobalCliActionRuntimeHooksForTest(mockRuntime)
    GlobalActions->>GlobalActions: Store runtime in module state
    
    Test->>GlobalActions: recoverNamedGatewayRuntime()
    GlobalActions->>GlobalActions: Check if hook present
    GlobalActions->>Runtime: Use injected hook
    Runtime-->>GlobalActions: result
    GlobalActions-->>Test: return result
    
    Test->>Cache: delete require.cache[GLOBAL_ACTIONS_PATH]
    Cache-->>Test: cache cleared

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 Hop, hop, the bridge comes down,
Actions stand alone in town!
Doctor probes, connects with care,
Rebuild dreams float in the air!
Sandbox flows refactored bright,
Legacy dispatch takes flight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.75% 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 title clearly summarizes the main change: adding oclif examples to utility commands. It is concise, specific, and accurately reflects the primary purpose of the PR.
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-global-utility-commands

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch refactor/oclif-ux-global-utility-commands

---

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

[prekshivyas]

LGTM. Pure additive metadata change — static examples arrays added to oclif Command classes for list, status, gateway-token, credentials*, backup-all, upgrade-sandboxes, gc, uninstall, tunnel start/stop, and the deprecated start/stop aliases. No run() body, flag, or arg changes anywhere.

The one slightly-non-cosmetic change — adding Flags.help({ char: "h" }) to UninstallCliCommand — brings its metadata into parity with peer utility commands. Strictly a UX improvement (explicit -h/--help), not a regression.

Public CLI surface unchanged (examples only render in --help output). src/nemoclaw.ts untouched, so the cumulative ~16-orphan debt is unaffected.

CI: pr.yaml mostly green (commit-lint, dco-check, check-hash, legacy-path-guard, changes PASS; macos-e2e and checks still in progress at review time). For an examples-only change with zero behavioral surface, lightweight gates are adequate signal.