refactor(cli): split oclif commands by command tree

[cv]

Summary

Split the oclif command adapter layer out of the flat src/lib/ directory and mirror the command tree under src/lib/commands/**.

Stack Navigation

• Position: 53 of 60
• Previous PR: #2967 — refactor(cli): group oclif core modules
• Next PR: #2984 — refactor(cli): group pure domain helpers

Changes

• Moved the explicit oclif registry to src/lib/commands/index.ts and updated the oclif target in package.json.
• Split registered oclif command classes to one command per production file, grouped by command family and sandbox scope.
• Moved command adapter tests beside the new command tree and updated imports/mocks.
• Kept behavior unchanged; command IDs, public syntax, parser flags, and action calls are preserved.

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 --stage pre-push passes
• npm run clean:cli && npm run build:cli && npm run dist:sourcemaps:check
• npm run typecheck:cli
• Command adapter and metadata tests pass
• 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 [email protected]

Summary by CodeRabbit

• Refactor
  • Reorganized CLI command modules into a more modular structure with commands grouped by feature and functionality.

[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: 629e9ef7-1492-469e-9585-5e855ba54785

📥 Commits

Reviewing files that changed from the base of the PR and between 5b89381 and 231f912.

📒 Files selected for processing (86)

• package.json
• src/lib/channels-mutate-cli-commands.ts
• src/lib/cli/oclif-metadata.ts
• src/lib/command-display-metadata.test.ts
• src/lib/commands/credentials.test.ts
• src/lib/commands/credentials.ts
• src/lib/commands/credentials/common.ts
• src/lib/commands/credentials/list.ts
• src/lib/commands/credentials/reset.ts
• src/lib/commands/debug.ts
• src/lib/commands/deploy.ts
• src/lib/commands/deprecated/start.ts
• src/lib/commands/deprecated/stop.ts
• src/lib/commands/gateway-token.ts
• src/lib/commands/global-oclif-command-adapters.test.ts
• src/lib/commands/index.ts
• src/lib/commands/list.ts
• src/lib/commands/maintenance/backup-all.ts
• src/lib/commands/maintenance/gc.ts
• src/lib/commands/maintenance/upgrade-sandboxes.ts
• src/lib/commands/onboard.test.ts
• src/lib/commands/onboard.ts
• src/lib/commands/onboard/common.ts
• src/lib/commands/root/help.ts
• src/lib/commands/root/version.ts
• src/lib/commands/sandbox/channels/add.ts
• src/lib/commands/sandbox/channels/common.ts
• src/lib/commands/sandbox/channels/list.ts
• src/lib/commands/sandbox/channels/mutate.test.ts
• src/lib/commands/sandbox/channels/remove.ts
• src/lib/commands/sandbox/channels/start.ts
• src/lib/commands/sandbox/channels/stop.ts
• src/lib/commands/sandbox/common.ts
• src/lib/commands/sandbox/config/get.ts
• src/lib/commands/sandbox/connect.ts
• src/lib/commands/sandbox/destroy.ts
• src/lib/commands/sandbox/doctor.ts
• src/lib/commands/sandbox/logs.test.ts
• src/lib/commands/sandbox/logs.ts
• src/lib/commands/sandbox/oclif-command-adapters.test.ts
• src/lib/commands/sandbox/policy/add.ts
• src/lib/commands/sandbox/policy/common.ts
• src/lib/commands/sandbox/policy/list.ts
• src/lib/commands/sandbox/policy/mutate.test.ts
• src/lib/commands/sandbox/policy/remove.ts
• src/lib/commands/sandbox/rebuild.ts
• src/lib/commands/sandbox/share.test.ts
• src/lib/commands/sandbox/share.ts
• src/lib/commands/sandbox/share/mount.ts
• src/lib/commands/sandbox/share/status.ts
• src/lib/commands/sandbox/share/unmount.ts
• src/lib/commands/sandbox/shields/down.ts
• src/lib/commands/sandbox/shields/status.ts
• src/lib/commands/sandbox/shields/up.ts
• src/lib/commands/sandbox/skill.test.ts
• src/lib/commands/sandbox/skill.ts
• src/lib/commands/sandbox/skill/common.ts
• src/lib/commands/sandbox/skill/install.ts
• src/lib/commands/sandbox/snapshot.test.ts
• src/lib/commands/sandbox/snapshot.ts
• src/lib/commands/sandbox/snapshot/common.ts
• src/lib/commands/sandbox/snapshot/create.ts
• src/lib/commands/sandbox/snapshot/list.ts
• src/lib/commands/sandbox/snapshot/restore.ts
• src/lib/commands/sandbox/status.ts
• src/lib/commands/setup-spark.ts
• src/lib/commands/setup.ts
• src/lib/commands/simple-global-oclif-adapters.test.ts
• src/lib/commands/status.ts
• src/lib/commands/tunnel/common.ts
• src/lib/commands/tunnel/start.ts
• src/lib/commands/tunnel/stop.ts
• src/lib/commands/uninstall.ts
• src/lib/credentials-cli-command.ts
• src/lib/maintenance-cli-commands.ts
• src/lib/oclif-command-metadata.test.ts
• src/lib/oclif-commands.ts
• src/lib/policy-mutate-cli-commands.ts
• src/lib/sandbox-inspection-cli-command.ts
• src/lib/share-cli-commands.ts
• src/lib/shields-cli-commands.ts
• src/lib/skill-install-cli-command.ts
• src/lib/snapshot-cli-commands.ts
• src/lib/tunnel-commands.ts
• test/cli.test.ts
• test/credentials-cli-command.test.ts

---

📝 Walkthrough

Walkthrough

This PR restructures the CLI command architecture from consolidated barrel exports to a modular, per-file layout. Commands are migrated from monolithic *-cli-commands.ts modules into individual files under src/lib/commands/, with a new central registry at src/lib/commands/index.ts mapping command identifiers to implementations. The oclif target in package.json is updated to reference the new registry location.

Changes

CLI Command Modularization

Layer / File(s)	Summary
Registry Update package.json, src/lib/cli/oclif-metadata.ts	oclif target path changed from ./dist/lib/oclif-commands.js to ./dist/lib/commands/index.js; module resolution paths updated to load from new ../commands paths.
Core Command Modules Deleted src/lib/channels-mutate-cli-commands.ts, src/lib/credentials-cli-command.ts, src/lib/maintenance-cli-commands.ts, src/lib/policy-mutate-cli-commands.ts, src/lib/sandbox-inspection-cli-command.ts, src/lib/share-cli-commands.ts, src/lib/shields-cli-commands.ts, src/lib/skill-install-cli-command.ts, src/lib/snapshot-cli-commands.ts, src/lib/tunnel-commands.ts, src/lib/oclif-commands.ts	Consolidated barrel modules removed; commands migrated to per-file structure.
New Credentials Commands src/lib/commands/credentials.ts, src/lib/commands/credentials/list.ts, src/lib/commands/credentials/reset.ts, src/lib/commands/credentials/common.ts	Credentials management split into separate command files with shared utilities (bridge provider detection, gateway recovery, usage printing).
New Sandbox Channel Commands src/lib/commands/sandbox/channels/add.ts, src/lib/commands/sandbox/channels/remove.ts, src/lib/commands/sandbox/channels/start.ts, src/lib/commands/sandbox/channels/stop.ts, src/lib/commands/sandbox/channels/list.ts, src/lib/commands/sandbox/channels/common.ts	Channel mutation commands split from consolidated module; runtime bridge and argument builders centralized in common.ts.
New Sandbox Policy Commands src/lib/commands/sandbox/policy/add.ts, src/lib/commands/sandbox/policy/remove.ts, src/lib/commands/sandbox/policy/list.ts, src/lib/commands/sandbox/policy/common.ts	Policy commands extracted with shared runtime bridge and flag utilities in common.ts.
New Sandbox Share Commands src/lib/commands/sandbox/share.ts, src/lib/commands/sandbox/share/mount.ts, src/lib/commands/sandbox/share/status.ts, src/lib/commands/sandbox/share/unmount.ts	Share operations split into modular command files.
New Sandbox Shields Commands src/lib/commands/sandbox/shields/down.ts, src/lib/commands/sandbox/shields/status.ts, src/lib/commands/sandbox/shields/up.ts	Shields management split into per-action command files.
New Sandbox Config & Inspection src/lib/commands/sandbox/config/get.ts, src/lib/commands/sandbox/status.ts, src/lib/commands/sandbox/snapshot.ts, src/lib/commands/sandbox/snapshot/create.ts, src/lib/commands/sandbox/snapshot/list.ts, src/lib/commands/sandbox/snapshot/restore.ts, src/lib/commands/sandbox/snapshot/common.ts	Config, status, and snapshot commands split into individual files with test helper factories.
New Sandbox Skill Commands src/lib/commands/sandbox/skill.ts, src/lib/commands/sandbox/skill/install.ts, src/lib/commands/sandbox/skill/common.ts	Skill installation split with runtime bridge abstraction.
New Maintenance Commands src/lib/commands/maintenance/backup-all.ts, src/lib/commands/maintenance/gc.ts, src/lib/commands/maintenance/upgrade-sandboxes.ts	Backup, garbage collection, and upgrade commands separated.
New Tunnel Commands src/lib/commands/tunnel/start.ts, src/lib/commands/tunnel/stop.ts, src/lib/commands/tunnel/common.ts	Tunnel operations split with service dependency injection via serviceDeps().
New Root Commands src/lib/commands/root/help.ts, src/lib/commands/root/version.ts	Help and version commands split.
New Deprecated Aliases src/lib/commands/deprecated/start.ts, src/lib/commands/deprecated/stop.ts	Deprecated command aliases for start/stop in separate directory.
New Standalone Commands src/lib/commands/onboard.ts, src/lib/commands/onboard/common.ts, src/lib/commands/setup.ts, src/lib/commands/setup-spark.ts, src/lib/commands/gateway-token.ts, src/lib/commands/deploy.ts, src/lib/commands/debug.ts, src/lib/commands/list.ts, src/lib/commands/status.ts, src/lib/commands/uninstall.ts, src/lib/commands/sandbox/connect.ts, src/lib/commands/sandbox/destroy.ts, src/lib/commands/sandbox/rebuild.ts, src/lib/commands/sandbox/doctor.ts, src/lib/commands/sandbox/logs.ts, src/lib/commands/sandbox/common.ts	Individual command files and helper modules created; imports updated to reference parent directories (../) where applicable.
Central Registry src/lib/commands/index.ts	New consolidated default export mapping command identifiers (e.g., "credentials", "sandbox:channels:add", "tunnel:start") to their command implementations; replaces the deleted oclif-commands.ts.
Test Updates src/lib/commands/credentials.test.ts, src/lib/commands/sandbox/channels/mutate.test.ts, src/lib/commands/sandbox/policy/mutate.test.ts, src/lib/commands/sandbox/snapshot.test.ts, src/lib/commands/sandbox/skill.test.ts, src/lib/commands/sandbox/logs.test.ts, src/lib/commands/sandbox/oclif-command-adapters.test.ts, src/lib/commands/global-oclif-command-adapters.test.ts, src/lib/commands/simple-global-oclif-adapters.test.ts, src/lib/command-display-metadata.test.ts, src/lib/oclif-command-metadata.test.ts, test/credentials-cli-command.test.ts, test/cli.test.ts	Test imports updated to reference new per-file modules as default exports; mock paths adjusted to new directory structure; test harness for credentials refactored to load per-module instead of aggregated.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Poem

🐰 Whiskers twitching with glee,
Commands now bloom in trees—
Each file its own sweet home,
No barrel buckets to roam!
Modular magic, so fine,
The registry shines! ✨

✨ 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/layer-command-tree

[prekshivyas]

LGTM. Large but mechanical — 86 files / +1687 / -1442.

Eight aggregator files (oclif-commands.ts + 10 *-cli-commands.ts/-cli-command.ts files) deleted; their classes split one-per-file under src/lib/commands/<topic>/<command>.ts mirroring the oclif command tree. New commands/index.ts replaces the aggregator registry. package.json oclif target updated to point at it.

Verified the colon-separated command IDs (e.g. sandbox:policy:add, sandbox:gateway:token) match what the OLD registry already used — not a behavior change. User-facing <name> policy-add hyphenated usage strings preserved.

oclif-metadata.ts tiny path tweak (3+/3-) to find the new registry. Test files moved alongside their sources.

CI: pr.yaml fully green (lint/dco/check-hash/legacy-path-guard/macos-e2e/changes/checks/test-e2e-ollama-proxy PASS); pr-self-hosted builds + wsl-e2e still in flight at review time. Critical signals (typecheck, integration test, adapter+metadata Vitest) all green.