refactor(onboard): extract sandbox create plan

src/lib/onboard/entry-options.test.ts

@@ -0,0 +1,162 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  resolveOnboardEntryOptions,
+  type OnboardEntryOptionsDeps,
+} from "../../../dist/lib/onboard/entry-options";
+
+class ExitError extends Error {
+  constructor(readonly code: number) {
+    super(`exit ${code}`);
+  }
+}
+
+function createDeps(overrides: Partial<OnboardEntryOptionsDeps> = {}): OnboardEntryOptionsDeps {
+  return {
+    isNonInteractive: vi.fn(() => false),
+    validateName: vi.fn((name: string) => name.trim().toLowerCase()),
+    reservedSandboxNames: new Set(["status"]),
+    cliDisplayName: vi.fn(() => "NemoClaw"),
+    getNameValidationGuidance: vi.fn(() => ["Use lowercase letters, numbers, and hyphens."]),
+    error: vi.fn(),
+    exitProcess: vi.fn((code: number) => {
+      throw new ExitError(code);
+    }) as (code: number) => never,
+    ...overrides,
+  };
+}
+
+describe("resolveOnboardEntryOptions", () => {
+  it("rejects mutually exclusive resume and fresh flags", () => {
+    const deps = createDeps();
+
+    expect(() =>
+      resolveOnboardEntryOptions(
+        {
+          opts: { resume: true, fresh: true },
+          env: {},
+          stdinIsTty: true,
+          stdoutIsTty: true,
+        },
+        deps,
+      ),
+    ).toThrow(ExitError);
+    expect(deps.error).toHaveBeenCalledWith("  --resume and --fresh cannot both be set.");
+  });
+
+  it("uses non-interactive env defaults for Dockerfile and sandbox name", () => {
+    const deps = createDeps({
+      isNonInteractive: vi.fn(() => true),
+    });
+
+    const result = resolveOnboardEntryOptions(
+      {
+        opts: {},
+        env: {
+          NEMOCLAW_FROM_DOCKERFILE: "Dockerfile.custom",
+          NEMOCLAW_SANDBOX_NAME: "  Demo-Box  ",
+        },
+        stdinIsTty: false,
+        stdoutIsTty: false,
+      },
+      deps,
+    );
+
+    expect(result).toMatchObject({
+      resume: false,
+      fresh: false,
+      requestedFromDockerfile: "Dockerfile.custom",
+      requestedSandboxName: "demo-box",
+      cannotPrompt: true,
+    });
+    expect(deps.validateName).toHaveBeenCalledWith("Demo-Box", "sandbox name");
+  });
+
+  it("requires a sandbox name for --from when prompts are unavailable", () => {
+    const deps = createDeps();
+
+    expect(() =>
+      resolveOnboardEntryOptions(
+        {
+          opts: { fromDockerfile: "Dockerfile.custom" },
+          env: {},
+          stdinIsTty: false,
+          stdoutIsTty: true,
+        },
+        deps,
+      ),
+    ).toThrow(ExitError);
+    expect(deps.error).toHaveBeenCalledWith(
+      "  --from <Dockerfile> requires --name <sandbox> (or NEMOCLAW_SANDBOX_NAME) when running without a TTY or with --non-interactive.",
+    );
+    expect(deps.error).toHaveBeenCalledWith(
+      "  A sandbox name cannot be prompted for in this context.",
+    );
+  });
+
+  it("allows resume with --from and no recovered sandbox name so later resume guards can decide", () => {
+    const deps = createDeps();
+
+    const result = resolveOnboardEntryOptions(
+      {
+        opts: { resume: true, fromDockerfile: "Dockerfile.custom" },
+        env: {},
+        stdinIsTty: false,
+        stdoutIsTty: true,
+      },
+      deps,
+    );
+
+    expect(result.resume).toBe(true);
+    expect(result.requestedFromDockerfile).toBe("Dockerfile.custom");
+    expect(result.requestedSandboxName).toBeNull();
+  });
+
+  it("rejects reserved sandbox command names with the original request source", () => {
+    const deps = createDeps();
+
+    expect(() =>
+      resolveOnboardEntryOptions(
+        {
+          opts: { sandboxName: "Status" },
+          env: {},
+          stdinIsTty: true,
+          stdoutIsTty: true,
+        },
+        deps,
+      ),
+    ).toThrow(ExitError);
+    expect(deps.error).toHaveBeenCalledWith("  Reserved name: 'status' is a NemoClaw CLI command.");
+    expect(deps.error).toHaveBeenCalledWith(
+      "  Choose a different sandbox name (passed via --name) to avoid routing conflicts.",
+    );
+    expect(deps.error).not.toHaveBeenCalledWith("  Use lowercase letters, numbers, and hyphens.");
+    expect(deps.getNameValidationGuidance).not.toHaveBeenCalled();
+    expect(deps.exitProcess).toHaveBeenCalledTimes(1);
+  });
+
+  it("prints validation guidance for invalid sandbox names", () => {
+    const deps = createDeps({
+      validateName: vi.fn(() => {
+        throw new Error("Invalid sandbox name");
+      }),
+    });
+
+    expect(() =>
+      resolveOnboardEntryOptions(
+        {
+          opts: { sandboxName: "bad name" },
+          env: {},
+          stdinIsTty: true,
+          stdoutIsTty: true,
+        },
+        deps,
+      ),
+    ).toThrow(ExitError);
+    expect(deps.error).toHaveBeenCalledWith("  Invalid sandbox name");
+    expect(deps.error).toHaveBeenCalledWith("  Use lowercase letters, numbers, and hyphens.");
+  });
+});

src/lib/onboard/entry-options.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export interface OnboardEntryOptionsInput {
+  opts: {
+    resume?: boolean;
+    fresh?: boolean;
+    fromDockerfile?: string | null;
+    sandboxName?: string | null;
+  };
+  env: NodeJS.ProcessEnv | Record<string, string | undefined>;
+  stdinIsTty: boolean;
+  stdoutIsTty: boolean;
+}
+
+export interface OnboardEntryOptionsDeps {
+  isNonInteractive(): boolean;
+  validateName(name: string, kind: string): string;
+  reservedSandboxNames: ReadonlySet<string>;
+  cliDisplayName(): string;
+  getNameValidationGuidance(
+    kind: string,
+    value: string | null | undefined,
+    options?: { includeAllowedFormat?: boolean },
+  ): string[];
+  error(message: string): void;
+  exitProcess(code: number): never;
+}
+
+export interface ResolvedOnboardEntryOptions {
+  resume: boolean;
+  fresh: boolean;
+  requestedFromDockerfile: string | null;
+  requestedSandboxName: string | null;
+  cannotPrompt: boolean;
+}
+
+export function resolveOnboardEntryOptions(
+  input: OnboardEntryOptionsInput,
+  deps: OnboardEntryOptionsDeps,
+): ResolvedOnboardEntryOptions {
+  const resume = input.opts.resume === true;
+  const fresh = input.opts.fresh === true;
+  if (resume && fresh) {
+    deps.error("  --resume and --fresh cannot both be set.");
+    deps.exitProcess(1);
+  }
+
+  const requestedFromDockerfile =
+    input.opts.fromDockerfile ||
+    (deps.isNonInteractive() ? input.env.NEMOCLAW_FROM_DOCKERFILE || null : null);
+  const cannotPrompt = deps.isNonInteractive() || !input.stdinIsTty || !input.stdoutIsTty;
+  let requestedSandboxName: string | null =
+    typeof input.opts.sandboxName === "string" && input.opts.sandboxName.length > 0
+      ? input.opts.sandboxName
+      : null;
+  let requestedSandboxSource: "--name" | "NEMOCLAW_SANDBOX_NAME" | null = requestedSandboxName
+    ? "--name"
+    : null;
+  if (!requestedSandboxName && cannotPrompt) {
+    const envName = input.env.NEMOCLAW_SANDBOX_NAME;
+    if (typeof envName === "string" && envName.trim().length > 0) {
+      requestedSandboxName = envName.trim();
+      requestedSandboxSource = "NEMOCLAW_SANDBOX_NAME";
+    }
+  }
+  if (requestedSandboxName) {
+    let validated: string;
+    try {
+      validated = deps.validateName(requestedSandboxName, "sandbox name");
+    } catch (error) {
+      deps.error(`  ${error instanceof Error ? error.message : String(error)}`);
+      for (const line of deps.getNameValidationGuidance("sandbox name", requestedSandboxName, {
+        includeAllowedFormat: false,
+      })) {
+        deps.error(`  ${line}`);
+      }
+      deps.exitProcess(1);
+    }
+    if (deps.reservedSandboxNames.has(validated)) {
+      deps.error(`  Reserved name: '${validated}' is a ${deps.cliDisplayName()} CLI command.`);
+      deps.error(
+        `  Choose a different sandbox name (passed via ${requestedSandboxSource}) to avoid routing conflicts.`,
+      );
+      deps.exitProcess(1);
+    }
+    requestedSandboxName = validated;
+  }
+  if (cannotPrompt && !resume && requestedFromDockerfile && !requestedSandboxName) {
+    deps.error(
+      "  --from <Dockerfile> requires --name <sandbox> (or NEMOCLAW_SANDBOX_NAME) when running without a TTY or with --non-interactive.",
+    );
+    deps.error("  A sandbox name cannot be prompted for in this context.");
+    deps.exitProcess(1);
+  }
+
+  return {
+    resume,
+    fresh,
+    requestedFromDockerfile,
+    requestedSandboxName,
+    cannotPrompt,
+  };
+}