refactor(cli): extract public argv normalizer

src/lib/cli-argv-normalizer.test.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it } from "vitest";
+
+import { normalizeArgv, suggestCommand } from "./cli-argv-normalizer";
+
+const globalCommands = new Set(["list", "status", "onboard", "--version"]);
+const isConnectFlag = (arg: string | undefined) => arg === "--probe-only" || arg === "--help";
+
+describe("normalizeArgv", () => {
+  it("normalizes root help aliases", () => {
+    expect(normalizeArgv([], { globalCommands, isSandboxConnectFlag: isConnectFlag })).toEqual({
+      kind: "rootHelp",
+    });
+    expect(normalizeArgv(["--help"], { globalCommands, isSandboxConnectFlag: isConnectFlag })).toEqual({
+      kind: "rootHelp",
+    });
+  });
+
+  it("normalizes internal dump commands", () => {
+    expect(
+      normalizeArgv(["--dump-commands"], { globalCommands, isSandboxConnectFlag: isConnectFlag }),
+    ).toEqual({ kind: "dumpCommands" });
+  });
+
+  it("normalizes global commands", () => {
+    expect(
+      normalizeArgv(["list", "--json"], { globalCommands, isSandboxConnectFlag: isConnectFlag }),
+    ).toEqual({ kind: "global", command: "list", args: ["--json"] });
+  });
+
+  it("normalizes explicit sandbox actions", () => {
+    expect(
+      normalizeArgv(["alpha", "status"], { globalCommands, isSandboxConnectFlag: isConnectFlag }),
+    ).toEqual({
+      kind: "sandbox",
+      sandboxName: "alpha",
+      action: "status",
+      actionArgs: [],
+      connectHelpRequested: false,
+    });
+  });
+
+  it("normalizes bare and implicit connect invocations", () => {
+    expect(
+      normalizeArgv(["alpha"], { globalCommands, isSandboxConnectFlag: isConnectFlag }),
+    ).toEqual({
+      kind: "sandbox",
+      sandboxName: "alpha",
+      action: "connect",
+      actionArgs: [],
+      connectHelpRequested: false,
+    });
+    expect(
+      normalizeArgv(["alpha", "--probe-only"], {
+        globalCommands,
+        isSandboxConnectFlag: isConnectFlag,
+      }),
+    ).toEqual({
+      kind: "sandbox",
+      sandboxName: "alpha",
+      action: "connect",
+      actionArgs: ["--probe-only"],
+      connectHelpRequested: false,
+    });
+  });
+
+  it("tracks connect help requests", () => {
+    expect(
+      normalizeArgv(["alpha", "connect", "--help"], {
+        globalCommands,
+        isSandboxConnectFlag: isConnectFlag,
+      }),
+    ).toMatchObject({
+      kind: "sandbox",
+      sandboxName: "alpha",
+      action: "connect",
+      actionArgs: ["--help"],
+      connectHelpRequested: true,
+    });
+  });
+});
+
+describe("suggestCommand", () => {
+  it("suggests close global command typos", () => {
+    expect(suggestCommand("liost", globalCommands)).toBe("list");
+  });
+
+  it("ignores flag-like commands", () => {
+    expect(suggestCommand("version", globalCommands)).toBeNull();
+  });
+});

src/lib/cli-argv-normalizer.ts

@@ -0,0 +1,88 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export type NormalizedRootHelpArgv = { kind: "rootHelp" };
+export type NormalizedDumpCommandsArgv = { kind: "dumpCommands" };
+export type NormalizedGlobalArgv = { kind: "global"; command: string; args: string[] };
+export type NormalizedSandboxArgv = {
+  kind: "sandbox";
+  sandboxName: string;
+  action: string;
+  actionArgs: string[];
+  connectHelpRequested: boolean;
+};
+
+export type NormalizedArgv =
+  | NormalizedRootHelpArgv
+  | NormalizedDumpCommandsArgv
+  | NormalizedGlobalArgv
+  | NormalizedSandboxArgv;
+
+export type NormalizeArgvOptions = {
+  globalCommands: ReadonlySet<string>;
+  isSandboxConnectFlag: (arg: string | undefined) => boolean;
+};
+
+export function normalizeArgv(argv: readonly string[], opts: NormalizeArgvOptions): NormalizedArgv {
+  const [cmd, ...args] = argv;
+
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    return { kind: "rootHelp" };
+  }
+
+  if (cmd === "--dump-commands") {
+    return { kind: "dumpCommands" };
+  }
+
+  if (opts.globalCommands.has(cmd)) {
+    return { kind: "global", command: cmd, args };
+  }
+
+  const firstSandboxArg = args[0];
+  const implicitConnectArg = opts.isSandboxConnectFlag(firstSandboxArg);
+  const action = !firstSandboxArg || implicitConnectArg ? "connect" : firstSandboxArg;
+  const actionArgs = !firstSandboxArg || implicitConnectArg ? args : args.slice(1);
+
+  return {
+    kind: "sandbox",
+    sandboxName: cmd,
+    action,
+    actionArgs,
+    connectHelpRequested:
+      action === "connect" && actionArgs.some((arg) => arg === "--help" || arg === "-h"),
+  };
+}
+
+function editDistance(left: string, right: string): number {
+  const rows = left.length + 1;
+  const cols = right.length + 1;
+  const matrix: number[][] = Array.from({ length: rows }, () => Array(cols).fill(0));
+  for (let i = 0; i < rows; i++) matrix[i][0] = i;
+  for (let j = 0; j < cols; j++) matrix[0][j] = j;
+  for (let i = 1; i < rows; i++) {
+    for (let j = 1; j < cols; j++) {
+      const cost = left[i - 1] === right[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost,
+      );
+    }
+  }
+  return matrix[left.length][right.length];
+}
+
+export function suggestCommand(token: string, commands: Iterable<string>): string | null {
+  let best: { command: string; distance: number } | null = null;
+  for (const command of commands) {
+    if (command.startsWith("-")) continue;
+    const distance = editDistance(token, command);
+    if (!best || distance < best.distance) {
+      best = { command, distance };
+    }
+  }
+  if (!best) return null;
+  if (best.distance <= 1) return best.command;
+  if (token.length >= 5 && best.distance <= 2) return best.command;
+  return null;
+}

src/nemoclaw.ts

@@ -83,6 +83,7 @@ const {
   globalCommandTokens,
   sandboxActionTokens,
 } = require("./lib/command-registry");
+import { normalizeArgv, suggestCommand } from "./lib/cli-argv-normalizer";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./lib/openshell-timeouts";
 import {
   resolveGlobalOclifDispatch,
@@ -148,38 +149,8 @@ function printSandboxActionUsage(action: string): void {
 
 // ── Dispatch helpers ─────────────────────────────────────────────
 
-function editDistance(left: string, right: string): number {
-  const rows = left.length + 1;
-  const cols = right.length + 1;
-  const matrix: number[][] = Array.from({ length: rows }, () => Array(cols).fill(0));
-  for (let i = 0; i < rows; i++) matrix[i][0] = i;
-  for (let j = 0; j < cols; j++) matrix[0][j] = j;
-  for (let i = 1; i < rows; i++) {
-    for (let j = 1; j < cols; j++) {
-      const cost = left[i - 1] === right[j - 1] ? 0 : 1;
-      matrix[i][j] = Math.min(
-        matrix[i - 1][j] + 1,
-        matrix[i][j - 1] + 1,
-        matrix[i - 1][j - 1] + cost,
-      );
-    }
-  }
-  return matrix[left.length][right.length];
-}
-
 function suggestGlobalCommand(token: string): string | null {
-  let best: { command: string; distance: number } | null = null;
-  for (const command of GLOBAL_COMMANDS) {
-    if (command.startsWith("-")) continue;
-    const distance = editDistance(token, command);
-    if (!best || distance < best.distance) {
-      best = { command, distance };
-    }
-  }
-  if (!best) return null;
-  if (best.distance <= 1) return best.command;
-  if (token.length >= 5 && best.distance <= 2) return best.command;
-  return null;
+  return suggestCommand(token, GLOBAL_COMMANDS);
 }
 
 function findRegisteredSandboxName(tokens: string[]): string | null {
@@ -256,36 +227,31 @@ async function runDispatchResult(
 
 // eslint-disable-next-line complexity
 async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
-  const [cmd, ...args] = argv;
+  const normalized = normalizeArgv(argv, {
+    globalCommands: GLOBAL_COMMANDS,
+    isSandboxConnectFlag,
+  });
 
-  // No command → help
-  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+  if (normalized.kind === "rootHelp") {
     await runOclif("root:help", []);
     return;
   }
 
-  // Internal developer flag — dump canonical command list for check-docs.sh parity checks
-  if (cmd === "--dump-commands") {
+  if (normalized.kind === "dumpCommands") {
     canonicalUsageList().forEach((c: string) => console.log(c));
     return;
   }
 
-  // Global commands
-  if (GLOBAL_COMMANDS.has(cmd)) {
-    await runDispatchResult(resolveGlobalOclifDispatch(cmd, args));
+  if (normalized.kind === "global") {
+    await runDispatchResult(resolveGlobalOclifDispatch(normalized.command, normalized.args));
     return;
   }
 
-  // Sandbox-scoped commands: nemoclaw <name> <action>
-  const firstSandboxArg = args[0];
-  const implicitConnectArg = isSandboxConnectFlag(firstSandboxArg);
-  const requestedSandboxAction =
-    !firstSandboxArg || implicitConnectArg ? "connect" : firstSandboxArg;
-  const requestedSandboxActionArgs = !firstSandboxArg || implicitConnectArg ? args : args.slice(1);
-  if (
-    requestedSandboxAction === "connect" &&
-    requestedSandboxActionArgs.some((arg) => arg === "--help" || arg === "-h")
-  ) {
+  const cmd = normalized.sandboxName;
+  const args = argv.slice(1);
+  const requestedSandboxAction = normalized.action;
+  const requestedSandboxActionArgs = normalized.actionArgs;
+  if (normalized.connectHelpRequested) {
     validateName(cmd, "sandbox name");
     printSandboxConnectHelp(cmd);
     return;