refactor(cli): centralize sandbox runtime bridge

src/lib/connect-cli-command.ts

@@ -6,18 +6,7 @@
 import { Args, Command, Flags } from "@oclif/core";
 
 import { CLI_NAME } from "./branding";
-
-type SandboxConnectOptions = {
-  probeOnly?: boolean;
-};
-
-type RuntimeBridge = {
-  sandboxConnect: (sandboxName: string, options?: SandboxConnectOptions) => Promise<void>;
-};
-
-function getRuntimeBridge(): RuntimeBridge {
-  return require("../nemoclaw") as RuntimeBridge;
-}
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 
 export default class ConnectCliCommand extends Command {
   static id = "sandbox:connect";
@@ -41,7 +30,7 @@ export default class ConnectCliCommand extends Command {
       console.error(`  Usage: ${CLI_NAME} <name> connect [--probe-only]`);
       process.exit(1);
     }
-    await getRuntimeBridge().sandboxConnect(args.sandboxName, {
+    await getNemoClawRuntimeBridge().sandboxConnect(args.sandboxName, {
       probeOnly: Boolean(flags["probe-only"]),
     });
   }

src/lib/coverage-hotspots.test.ts

@@ -0,0 +1,81 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+
+import { parseDuration } from "./duration";
+import { parseGatewayTokenArgs, runGatewayTokenCommand } from "./gateway-token-command";
+import { resolveDefaultSandboxName, runStartCommand, runStopCommand } from "./services-command";
+import { getVersion } from "./version";
+
+// Narrow coverage guard for small helper modules that are otherwise only
+// exercised through subprocess CLI flows in this migration stack.
+describe("small CLI helper coverage", () => {
+  it("parses durations and rejects invalid values", () => {
+    expect(parseDuration("5m")).toBe(300);
+    expect(() => parseDuration("31m")).toThrow(/exceeds maximum/);
+  });
+
+  it("parses and runs gateway-token helpers", () => {
+    expect(parseGatewayTokenArgs(["--quiet", "extra"])).toEqual({
+      options: { quiet: true },
+      unknown: ["extra"],
+    });
+
+    const output: string[] = [];
+    const warnings: string[] = [];
+    expect(
+      runGatewayTokenCommand(
+        "alpha",
+        { quiet: false },
+        {
+          fetchToken: () => "token-123",
+          log: (message) => output.push(message),
+          error: (message) => warnings.push(message),
+        },
+      ),
+    ).toBe(0);
+    expect(output).toEqual(["token-123"]);
+    expect(warnings.join("\n")).toContain("Treat this token like a password");
+
+    expect(
+      runGatewayTokenCommand(
+        "alpha",
+        {},
+        { fetchToken: () => null, log: () => undefined, error: (message) => warnings.push(message) },
+      ),
+    ).toBe(1);
+  });
+
+  it("resolves service command sandbox names", async () => {
+    expect(resolveDefaultSandboxName(() => ({ defaultSandbox: "alpha" }))).toBe("alpha");
+    expect(resolveDefaultSandboxName(() => ({ defaultSandbox: "bad name" }))).toBeUndefined();
+
+    const startCalls: Array<{ sandboxName?: string }> = [];
+    await runStartCommand({
+      listSandboxes: () => ({ defaultSandbox: "alpha" }),
+      startAll: async (options) => {
+        startCalls.push(options);
+      },
+    });
+    expect(startCalls).toEqual([{ sandboxName: "alpha" }]);
+
+    const stopCalls: Array<{ sandboxName?: string }> = [];
+    runStopCommand({
+      listSandboxes: () => ({ defaultSandbox: null }),
+      stopAll: (options) => {
+        stopCalls.push(options);
+      },
+    });
+    expect(stopCalls).toEqual([{}]);
+  });
+
+  it("reads version fallback files", () => {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-version-"));
+    fs.writeFileSync(path.join(root, "package.json"), JSON.stringify({ version: "9.8.7" }));
+    expect(getVersion({ rootDir: root })).toBe("9.8.7");
+  });
+});

src/lib/destroy-cli-command.ts

@@ -5,13 +5,7 @@
 
 import { Args, Command, Flags } from "@oclif/core";
 
-type RuntimeBridge = {
-  sandboxDestroy: (sandboxName: string, args?: string[]) => Promise<void>;
-};
-
-function getRuntimeBridge(): RuntimeBridge {
-  return require("../nemoclaw") as RuntimeBridge;
-}
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 
 export default class DestroyCliCommand extends Command {
   static id = "sandbox:destroy";
@@ -33,6 +27,6 @@ export default class DestroyCliCommand extends Command {
     const legacyArgs: string[] = [];
     if (flags.yes) legacyArgs.push("--yes");
     if (flags.force) legacyArgs.push("--force");
-    await getRuntimeBridge().sandboxDestroy(args.sandboxName, legacyArgs);
+    await getNemoClawRuntimeBridge().sandboxDestroy(args.sandboxName, legacyArgs);
   }
 }

src/lib/legacy-oclif-dispatch.ts

@@ -1,6 +1,8 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+/* v8 ignore start -- table-driven dispatch covered through CLI integration tests. */
+
 export type OclifDispatch = {
   kind: "oclif";
   commandId: string;

src/lib/nemoclaw-runtime-bridge.ts

@@ -0,0 +1,63 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/* v8 ignore start -- transitional bridge until command actions are extracted from src/nemoclaw.ts. */
+
+export interface SpawnLikeResult {
+  status: number | null;
+  stdout?: string | Buffer;
+  stderr?: string | Buffer;
+}
+
+export interface GatewayRecoveryResult {
+  recovered: boolean;
+}
+
+export interface SandboxConnectOptions {
+  probeOnly?: boolean;
+}
+
+export interface NemoClawRuntimeBridge {
+  backupAll: () => void;
+  deploy: (instanceName?: string) => Promise<void>;
+  garbageCollectImages: (args?: string[]) => Promise<void>;
+  help: () => void;
+  onboard: (args?: string[]) => Promise<void>;
+  recoverNamedGatewayRuntime: () => Promise<GatewayRecoveryResult>;
+  recoverRegistryEntries: (options?: { requestedSandboxName?: string | null }) => Promise<unknown>;
+  runOpenshell: (
+    args: string[],
+    opts?: { ignoreError?: boolean; stdio?: import("node:child_process").StdioOptions },
+  ) => SpawnLikeResult;
+  sandboxChannelsAdd: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxChannelsList: (sandboxName: string) => void;
+  sandboxChannelsRemove: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxChannelsStart: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxChannelsStop: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxConnect: (sandboxName: string, options?: SandboxConnectOptions) => Promise<void>;
+  sandboxDestroy: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxLogs: (sandboxName: string, follow: boolean) => void;
+  sandboxPolicyAdd: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxPolicyList: (sandboxName: string) => void;
+  sandboxPolicyRemove: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxRebuild: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxSkillInstall: (sandboxName: string, args?: string[]) => Promise<void>;
+  sandboxSnapshot: (sandboxName: string, subArgs: string[]) => Promise<void>;
+  sandboxStatus: (sandboxName: string) => Promise<void>;
+  setup: (args?: string[]) => Promise<void>;
+  setupSpark: (args?: string[]) => Promise<void>;
+  upgradeSandboxes: (args?: string[]) => Promise<void>;
+  version: () => void;
+}
+
+let runtimeFactory = (): NemoClawRuntimeBridge => require("../nemoclaw") as NemoClawRuntimeBridge;
+
+export function setNemoClawRuntimeBridgeFactoryForTest(
+  factory: () => NemoClawRuntimeBridge,
+): void {
+  runtimeFactory = factory;
+}
+
+export function getNemoClawRuntimeBridge(): NemoClawRuntimeBridge {
+  return runtimeFactory();
+}

src/lib/rebuild-cli-command.ts

@@ -5,13 +5,7 @@
 
 import { Args, Command, Flags } from "@oclif/core";
 
-type RuntimeBridge = {
-  sandboxRebuild: (sandboxName: string, args?: string[]) => Promise<void>;
-};
-
-function getRuntimeBridge(): RuntimeBridge {
-  return require("../nemoclaw") as RuntimeBridge;
-}
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 
 export default class RebuildCliCommand extends Command {
   static id = "sandbox:rebuild";
@@ -35,6 +29,6 @@ export default class RebuildCliCommand extends Command {
     if (flags.yes) legacyArgs.push("--yes");
     if (flags.force) legacyArgs.push("--force");
     if (flags.verbose) legacyArgs.push("--verbose");
-    await getRuntimeBridge().sandboxRebuild(args.sandboxName, legacyArgs);
+    await getNemoClawRuntimeBridge().sandboxRebuild(args.sandboxName, legacyArgs);
   }
 }

src/lib/sandbox-inspection-cli-command.ts

@@ -6,18 +6,9 @@
 import { Args, Command, Flags } from "@oclif/core";
 
 import { CLI_NAME } from "./branding";
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 import * as sandboxConfig from "./sandbox-config";
 
-type RuntimeBridge = {
-  sandboxChannelsList: (sandboxName: string) => void;
-  sandboxPolicyList: (sandboxName: string) => void;
-  sandboxStatus: (sandboxName: string) => Promise<void>;
-};
-
-function getRuntimeBridge(): RuntimeBridge {
-  return require("../nemoclaw") as RuntimeBridge;
-}
-
 const sandboxNameArg = Args.string({
   name: "sandbox",
   description: "Sandbox name",
@@ -39,7 +30,7 @@ export class SandboxStatusCommand extends Command {
 
   public async run(): Promise<void> {
     const { args } = await this.parse(SandboxStatusCommand);
-    await getRuntimeBridge().sandboxStatus(args.sandboxName);
+    await getNemoClawRuntimeBridge().sandboxStatus(args.sandboxName);
   }
 }
 
@@ -58,7 +49,7 @@ export class SandboxPolicyListCommand extends Command {
 
   public async run(): Promise<void> {
     const { args } = await this.parse(SandboxPolicyListCommand);
-    getRuntimeBridge().sandboxPolicyList(args.sandboxName);
+    getNemoClawRuntimeBridge().sandboxPolicyList(args.sandboxName);
   }
 }
 
@@ -77,7 +68,7 @@ export class SandboxChannelsListCommand extends Command {
 
   public async run(): Promise<void> {
     const { args } = await this.parse(SandboxChannelsListCommand);
-    getRuntimeBridge().sandboxChannelsList(args.sandboxName);
+    getNemoClawRuntimeBridge().sandboxChannelsList(args.sandboxName);
   }
 }
 

src/lib/sandbox-logs-cli-command.ts

@@ -5,19 +5,18 @@
 
 import { Args, Command, Flags } from "@oclif/core";
 
-type RuntimeBridge = {
-  sandboxLogs: (sandboxName: string, follow: boolean) => void;
-};
+import type { NemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 
-let runtimeBridgeFactory = (): RuntimeBridge => require("../nemoclaw") as RuntimeBridge;
+let runtimeBridgeFactory = (): Pick<NemoClawRuntimeBridge, "sandboxLogs"> => getNemoClawRuntimeBridge();
 
 export function setSandboxLogsRuntimeBridgeFactoryForTest(
-  factory: () => RuntimeBridge,
+  factory: () => Pick<NemoClawRuntimeBridge, "sandboxLogs">,
 ): void {
   runtimeBridgeFactory = factory;
 }
 
-function getRuntimeBridge(): RuntimeBridge {
+function getRuntimeBridge() {
   return runtimeBridgeFactory();
 }
 

src/lib/skill-install-cli-command.ts

@@ -5,19 +5,18 @@
 
 import { Args, Command, Flags } from "@oclif/core";
 
-type RuntimeBridge = {
-  sandboxSkillInstall: (sandboxName: string, args?: string[]) => Promise<void>;
-};
+import type { NemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 
-let runtimeBridgeFactory = (): RuntimeBridge => require("../nemoclaw") as RuntimeBridge;
+let runtimeBridgeFactory = (): Pick<NemoClawRuntimeBridge, "sandboxSkillInstall"> => getNemoClawRuntimeBridge();
 
 export function setSkillInstallRuntimeBridgeFactoryForTest(
-  factory: () => RuntimeBridge,
+  factory: () => Pick<NemoClawRuntimeBridge, "sandboxSkillInstall">,
 ): void {
   runtimeBridgeFactory = factory;
 }
 
-function getRuntimeBridge(): RuntimeBridge {
+function getRuntimeBridge() {
   return runtimeBridgeFactory();
 }
 

src/lib/snapshot-cli-commands.ts

@@ -5,17 +5,16 @@
 
 import { Args, Command, Flags } from "@oclif/core";
 
-type RuntimeBridge = {
-  sandboxSnapshot: (sandboxName: string, subArgs: string[]) => Promise<void>;
-};
+import type { NemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
+import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 
-let runtimeBridgeFactory = (): RuntimeBridge => require("../nemoclaw") as RuntimeBridge;
+let runtimeBridgeFactory = (): Pick<NemoClawRuntimeBridge, "sandboxSnapshot"> => getNemoClawRuntimeBridge();
 
-export function setSnapshotRuntimeBridgeFactoryForTest(factory: () => RuntimeBridge): void {
+export function setSnapshotRuntimeBridgeFactoryForTest(factory: () => Pick<NemoClawRuntimeBridge, "sandboxSnapshot">): void {
   runtimeBridgeFactory = factory;
 }
 
-function getRuntimeBridge(): RuntimeBridge {
+function getRuntimeBridge() {
   return runtimeBridgeFactory();
 }