refactor(cli): table-drive sandbox dispatch

[cv]

Summary

Replace switch-heavy sandbox command dispatch with route tables. Public CLI behavior is preserved while making the mapping between public sandbox syntax and internal oclif command IDs easier to review and extend.

Stack Navigation

• Position: 30 of 60
• Previous PR: #2922 — refactor(cli): use oclif summaries in root help
• Next PR: #2924 — refactor(cli): normalize gateway token command id

Changes

• Added flat sandbox route metadata for single-action commands.
• Added nested sandbox route metadata for skill, share, snapshot, shields, channels, and config.
• Kept public help and compatibility routing behavior stable.

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

• Refactor
  • Restructured CLI command routing system
  • Modified help behavior for nested commands (channels, config, shields)

[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 two independent systems: (1) the oclif command dispatcher moves from large switch statements to data-driven route tables with dedicated resolvers for flat and nested sandbox commands, and (2) the Docker info parser is split from a monolithic function into focused helpers for extracting CPU, memory, storage driver, and snapshotter detection.

Changes

oclif Dispatch Refactoring

Layer / File(s)	Summary
Route Type Definitions src/lib/oclif-dispatch.ts (lines 40–53)	Introduces FlatSandboxRoute and NestedSandboxRoute types to describe command mappings with optional help usage and nested subcommand structures.
Route Lookup Tables src/lib/oclif-dispatch.ts (lines 54–106)	Defines GLOBAL_ROUTES, FLAT_SANDBOX_ROUTES, and NESTED_SANDBOX_ROUTES to replace switch-statement dispatch logic with data-driven route configurations.
Resolution Helpers src/lib/oclif-dispatch.ts (lines 239–293)	Adds resolveFlatSandboxRoute and resolveNestedSandboxRoute to map actions to oclif commands; handles --help by returning help output only when route defines helpUsage, otherwise falls back to parent oclif dispatch for unknown subcommands.
Global Dispatch Update src/lib/oclif-dispatch.ts (lines 207–237)	Refactors resolveGlobalOclifDispatch to use GLOBAL_ROUTES lookup while preserving special cases for tunnel and credentials handling.
Sandbox Dispatch Integration src/lib/oclif-dispatch.ts (lines 295–311)	Updates resolveSandboxOclifDispatch to route actions through flat/nested resolvers and return unknownAction for unmapped actions.

Docker Info Parsing Refactoring

Layer / File(s)	Summary
New Parsing Helpers src/lib/preflight.ts (lines 179–257)	Adds dedicated exportable parsers: parseDockerCgroupVersion(), parseDockerStorageDriver(), parseDockerUsesContainerdSnapshotter(), parseDockerInfoCpus(), parseDockerInfoMemTotalBytes(), and parseDockerInfoSummary(); replaces monolithic parseDockerInfo() and DockerInfo interface.
Assessment Integration src/lib/preflight.ts (lines 373–385, 437, 460–462)	Updates assessHost to invoke new dedicated parsers instead of parseDockerInfo() and removes note logic that depended on plain-text fallback detection.
Test Restructuring src/lib/preflight.test.ts (lines 14–20, 458–500, 960–996)	Removes monolithic parseDockerInfo test coverage; adds targeted test blocks for each new parser validating JSON extraction, plain-text fallback parsing, and boundary conditions (zero/negative rejection, empty input handling).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

A rabbit hops through routes and routes again,
Swapping switch for tables—sleek and clean.
Docker's data parsed with care and zen,
Five helpers shine where one once reigned supreme.
🐰 ✨

🚥 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 title references 'table-drive sandbox dispatch', which is a core refactoring described in the PR objectives, but the actual changeset spans three files with significant changes to oclif dispatch, docker info parsing, and test coverage.
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-arch-table-dispatch

---

_{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).