refactor(cli): model debug flags with oclif

[cv]

Summary

Move debug flag parsing into its oclif adapter so unknown flags and missing flag values fail through the parser before diagnostic collection. The debug action helpers remain available for existing unit tests and now also accept already-parsed options.

Stack Navigation

• Position: 20 of 60
• Previous PR: #2911 — refactor(cli): split share into oclif subcommands
• Next PR: #2913 — refactor(cli): model onboard flags with oclif

Changes

• Modeled --quick/-q, --output/-o, and --sandbox as oclif flags.
• Added debug command examples.
• Added runDebugCommandWithOptions for adapters that already have parsed options.
• Updated CLI and unit tests for oclif-owned parse errors and parsed-option execution.

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

  • Debug command accepts shorthand flags (-q, -o) and explicit output/sandbox options.
  • Debug command can be invoked with pre-parsed options so sandbox defaults are applied when not provided.

• Improvements

  • Stronger CLI parsing and clearer error messages for unknown flags and missing flag values.

• Tests

  • CLI tests tightened to assert specific error messages for invalid flag usage.

[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: 714c6655-a71f-424b-8d8d-c12d10840f69

📥 Commits

Reviewing files that changed from the base of the PR and between 928219c and 52eb5a1.

📒 Files selected for processing (1)

• test/cli.test.ts

---

📝 Walkthrough

Walkthrough

The debug CLI was refactored to parse oclif flags strictly and build a DebugOptions object; a new runDebugCommandWithOptions helper centralizes defaulting of sandboxName (via getDefaultSandbox) before calling runDebug. Tests and CLI error assertions updated accordingly.

Changes

Debug Command Refactoring

Layer / File(s)	Summary
Data Shape / Types src/lib/debug-command.ts	Introduces/uses DebugOptions as the options shape passed to the runtime helper.
Core Helper src/lib/debug-command.ts	Adds exported runDebugCommandWithOptions(options, deps) which clones options, fills sandboxName from deps.getDefaultSandbox() when missing, and calls deps.runDebug(opts). Keeps runDebugCommand(args, deps) as entry that parses args.
CLI Flag Definitions src/lib/debug-cli-command.ts	Adds static flags (including `--quick
CLI Integration src/lib/debug-cli-command.ts	Replaces run() to use await this.parse(DebugCliCommand), map parsed flags into DebugOptions, and call runDebugCommandWithOptions(options, buildDebugCommandDeps(this.config.root)).
Tests / Assertions src/lib/debug-command.test.ts, test/cli.test.ts	Adds a test verifying runDebugCommandWithOptions falls back to default sandbox when none provided; tightens CLI error assertions to check for Nonexistent flag: --quik and presence of --sandbox in missing-name error output.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant CLI as "Debug CLI"
    participant Parser as "oclif parser"
    participant CmdHelper as "runDebugCommandWithOptions"
    participant Deps as "Deps (getDefaultSandbox, runDebug)"
    CLI->>Parser: parse flags (quick, output, sandbox)
    Parser-->>CLI: parsed flags
    CLI->>CmdHelper: call with DebugOptions (from flags)
    CmdHelper->>Deps: getDefaultSandbox() if sandbox missing
    Deps-->>CmdHelper: sandboxName (e.g., "alpha")
    CmdHelper->>Deps: runDebug(options with sandboxName)
    Deps-->>CmdHelper: runDebug result
    CmdHelper-->>CLI: complete

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🐰 I nibbled flags and stitched them tight,
Short hops of -q and -o in sight,
Defaults fetched when the sandbox hides,
Clean options now take joyful strides. 🥕✨

✨ 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-debug-flags

---

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