refactor(cli): model debug flags with oclif

src/lib/debug-cli-command.ts

@@ -3,18 +3,19 @@
 
 /* v8 ignore start -- thin oclif adapter covered through CLI integration tests. */
 
-import { Command } from "@oclif/core";
+import { Command, Flags } from "@oclif/core";
 
-import type { CaptureOpenshellResult } from "./openshell";
-import type { RunDebugCommandDeps } from "./debug-command";
 import { CLI_NAME } from "./branding";
 import { runDebug } from "./debug";
-import { runDebugCommand } from "./debug-command";
-import { OPENSHELL_PROBE_TIMEOUT_MS } from "./openshell-timeouts";
+import type { DebugOptions } from "./debug";
+import type { RunDebugCommandDeps } from "./debug-command";
+import { runDebugCommandWithOptions } from "./debug-command";
+import type { CaptureOpenshellResult } from "./openshell";
 import { captureOpenshellCommand } from "./openshell";
-import { parseLiveSandboxNames } from "./runtime-recovery";
+import { OPENSHELL_PROBE_TIMEOUT_MS } from "./openshell-timeouts";
 import * as registry from "./registry";
 import { resolveOpenshell } from "./resolve-openshell";
+import { parseLiveSandboxNames } from "./runtime-recovery";
 
 const useColor = !process.env.NO_COLOR && !!process.stderr.isTTY;
 const B = useColor ? "\x1b[1m" : "";
@@ -70,13 +71,28 @@ function buildDebugCommandDeps(rootDir: string): RunDebugCommandDeps {
 
 export default class DebugCliCommand extends Command {
   static id = "debug";
-  static strict = false;
+  static strict = true;
   static summary = "Collect diagnostics for bug reports";
   static description = "Collect NemoClaw diagnostic information.";
-  static usage = ["debug [--quick] [--output FILE] [--sandbox NAME]"];
+  static usage = ["debug [--quick|-q] [--output FILE|-o FILE] [--sandbox NAME]"];
+  static examples = [
+    "<%= config.bin %> debug --quick",
+    "<%= config.bin %> debug --sandbox alpha",
+    "<%= config.bin %> debug --output /tmp/nemoclaw-debug.tar.gz",
+  ];
+  static flags = {
+    help: Flags.help({ char: "h" }),
+    quick: Flags.boolean({ char: "q", description: "Only collect minimal diagnostics" }),
+    output: Flags.string({ char: "o", description: "Write a tarball to FILE" }),
+    sandbox: Flags.string({ description: "Target sandbox name" }),
+  };
 
   public async run(): Promise<void> {
-    this.parsed = true;
-    runDebugCommand(this.argv, buildDebugCommandDeps(this.config.root));
+    const { flags } = await this.parse(DebugCliCommand);
+    const options: DebugOptions = {};
+    if (flags.quick) options.quick = true;
+    if (flags.output) options.output = flags.output;
+    if (flags.sandbox) options.sandboxName = flags.sandbox;
+    runDebugCommandWithOptions(options, buildDebugCommandDeps(this.config.root));
   }
 }

src/lib/debug-command.test.ts

@@ -3,7 +3,12 @@
 
 import { describe, expect, it, vi } from "vitest";
 
-import { parseDebugArgs, printDebugHelp, runDebugCommand } from "../../dist/lib/debug-command";
+import {
+  parseDebugArgs,
+  printDebugHelp,
+  runDebugCommand,
+  runDebugCommandWithOptions,
+} from "../../dist/lib/debug-command";
 
 function exitWithCode(code: number): never {
   throw new Error(`exit:${code}`);
@@ -40,6 +45,22 @@ describe("debug command", () => {
     expect(runDebug).toHaveBeenCalledWith({ sandboxName: "beta" });
   });
 
+  it("runs parsed debug options and falls back to the default sandbox", () => {
+    const runDebug = vi.fn();
+    runDebugCommandWithOptions({ quick: true, output: "/tmp/out.tgz" }, {
+      getDefaultSandbox: () => "alpha",
+      runDebug,
+      log: () => {},
+      error: () => {},
+      exit: exitWithCode,
+    });
+    expect(runDebug).toHaveBeenCalledWith({
+      quick: true,
+      output: "/tmp/out.tgz",
+      sandboxName: "alpha",
+    });
+  });
+
   it("--sandbox overrides the default sandbox", () => {
     const runDebug = vi.fn();
     runDebugCommand(["--sandbox", "mybox"], {

src/lib/debug-command.ts

@@ -67,6 +67,14 @@ export function parseDebugArgs(
   return opts;
 }
 
+export function runDebugCommandWithOptions(options: DebugOptions, deps: RunDebugCommandDeps): void {
+  const opts = { ...options };
+  if (!opts.sandboxName) {
+    opts.sandboxName = deps.getDefaultSandbox();
+  }
+  deps.runDebug(opts);
+}
+
 export function runDebugCommand(args: string[], deps: RunDebugCommandDeps): void {
   const opts = parseDebugArgs(args, deps);
   deps.runDebug(opts);

test/cli.test.ts

@@ -1148,8 +1148,8 @@ describe("CLI dispatch", () => {
 
   it("debug exits 1 on unknown option", () => {
     const r = run("debug --quik");
-    expect(r.code).toBe(1);
-    expect(r.out.includes("Unknown option")).toBeTruthy();
+    expect(r.code).not.toBe(0);
+    expect(r.out).toContain("Nonexistent flag: --quik");
   });
 
   it("help mentions debug command", () => {
@@ -1172,6 +1172,7 @@ describe("CLI dispatch", () => {
   it("debug --sandbox without a name exits 1", () => {
     const r = run("debug --sandbox");
     expect(r.code).not.toBe(0);
+    expect(r.out).toContain("--sandbox");
   });
 
   it("debug warns when default sandbox is stale", testTimeoutOptions(), () => {