refactor(onboard): extract gateway bootstrap repair helpers

src/lib/onboard/dashboard-access.test.ts

@@ -0,0 +1,77 @@
+// 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 {
+  buildAuthenticatedDashboardUrl,
+  dashboardUrlForDisplay,
+  getDashboardAccessInfo,
+  getDashboardForwardPort,
+  getDashboardForwardStartCommand,
+  getDashboardForwardTarget,
+  getDashboardGuidanceLines,
+  getWslHostAddress,
+} from "./dashboard-access";
+
+describe("dashboard access helpers", () => {
+  it("derives forward port and target from chat UI URLs", () => {
+    expect(getDashboardForwardPort("http://127.0.0.1:18789", { isWsl: false })).toBe("18789");
+    expect(getDashboardForwardTarget("http://127.0.0.1:18789", { isWsl: false })).toBe("18789");
+    expect(getDashboardForwardTarget("http://10.0.0.25:18789", { isWsl: false })).toBe("0.0.0.0:18789");
+  });
+
+  it("builds the OpenShell forward start command with the resolved target", () => {
+    const openshellShellCommand = vi.fn((args: string[]) => `openshell ${args.join(" ")}`);
+
+    expect(
+      getDashboardForwardStartCommand("alpha", {
+        chatUiUrl: "http://10.0.0.25:18789",
+        openshellShellCommand,
+      }),
+    ).toBe("openshell forward start --background 0.0.0.0:18789 alpha");
+  });
+
+  it("redacts token fragments for display", () => {
+    expect(buildAuthenticatedDashboardUrl("http://127.0.0.1:18789/", "secret token")).toBe(
+      "http://127.0.0.1:18789/#token=secret%20token",
+    );
+    expect(dashboardUrlForDisplay("http://127.0.0.1:18789/#token=secret", (value) => value)).toBe(
+      "http://127.0.0.1:18789/",
+    );
+  });
+
+  it("detects a WSL host address only when WSL is active", () => {
+    const runCapture = vi.fn(() => "172.22.1.1 10.0.0.2\n");
+
+    expect(getWslHostAddress({ isWsl: true, runCapture })).toBe("172.22.1.1");
+    expect(getWslHostAddress({ isWsl: false, runCapture })).toBeNull();
+  });
+
+  it("builds dashboard access entries including a WSL URL", () => {
+    const access = getDashboardAccessInfo("alpha", {
+      token: "secret",
+      chatUiUrl: "http://127.0.0.1:18789",
+      isWsl: true,
+      wslHostAddress: "172.22.1.1",
+    });
+
+    expect(access).toContainEqual({
+      label: "Alt 1",
+      url: "http://172.22.1.1:18789/#token=secret",
+    });
+  });
+
+  it("builds dashboard guidance for WSL and empty access lists", () => {
+    expect(
+      getDashboardGuidanceLines([], {
+        chatUiUrl: "http://127.0.0.1:18789",
+        isWsl: true,
+      }),
+    ).toEqual([
+      "Port 18789 must be forwarded before opening these URLs.",
+      "WSL detected: if localhost fails in Windows, use the WSL host IP shown by `hostname -I`.",
+      "No dashboard URLs were generated.",
+    ]);
+  });
+});

src/lib/onboard/dashboard-access.ts

@@ -0,0 +1,144 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { WslDetectionOptions } from "../platform";
+import { isWsl } from "../platform";
+import { DASHBOARD_PORT } from "../core/ports";
+import { buildChain, buildControlUiUrls } from "../dashboard/contract";
+
+type RunCapture = (args: string[], options: { ignoreError: true }) => string;
+type OpenshellShellCommand = (args: string[], options?: { openshellBinary?: string }) => string;
+
+export type DashboardAccessOptions = WslDetectionOptions & {
+  chatUiUrl?: string;
+  token?: string | null;
+  wslHostAddress?: string | null;
+  runCapture?: RunCapture;
+  openshellBinary?: string;
+  openshellShellCommand?: OpenshellShellCommand;
+  fetchGatewayAuthToken?: (sandboxName: string) => string | null;
+  env?: NodeJS.ProcessEnv;
+};
+
+export type DashboardAccessEntry = {
+  label: string;
+  url: string;
+};
+
+const CONTROL_UI_PORT = DASHBOARD_PORT;
+
+function defaultChatUiUrl(options: DashboardAccessOptions = {}): string {
+  return options.chatUiUrl || options.env?.CHAT_UI_URL || process.env.CHAT_UI_URL || `http://127.0.0.1:${CONTROL_UI_PORT}`;
+}
+
+export function getWslHostAddress(options: DashboardAccessOptions = {}): string | null {
+  if (options.wslHostAddress) {
+    return options.wslHostAddress;
+  }
+  if (!isWsl(options)) {
+    return null;
+  }
+  const runCaptureFn = options.runCapture;
+  if (!runCaptureFn) return null;
+  const output = runCaptureFn(["hostname", "-I"], { ignoreError: true });
+  return (
+    String(output || "")
+      .trim()
+      .split(/\s+/)
+      .filter(Boolean)[0] || null
+  );
+}
+
+export function buildDashboardChain(
+  chatUiUrl = defaultChatUiUrl(),
+  options: DashboardAccessOptions = {},
+) {
+  return buildChain({
+    chatUiUrl,
+    isWsl: isWsl(options),
+    wslHostAddress: getWslHostAddress(options),
+  });
+}
+
+export function getDashboardForwardPort(
+  chatUiUrl = defaultChatUiUrl(),
+  options: DashboardAccessOptions = {},
+): string {
+  return String(buildDashboardChain(chatUiUrl, options).port);
+}
+
+export function getDashboardForwardTarget(
+  chatUiUrl = defaultChatUiUrl(),
+  options: DashboardAccessOptions = {},
+): string {
+  return buildDashboardChain(chatUiUrl, options).forwardTarget;
+}
+
+export function getDashboardForwardStartCommand(
+  sandboxName: string,
+  options: DashboardAccessOptions = {},
+): string {
+  if (!options.openshellShellCommand) {
+    throw new Error("getDashboardForwardStartCommand requires openshellShellCommand");
+  }
+  const chatUiUrl = defaultChatUiUrl(options);
+  const forwardTarget = getDashboardForwardTarget(chatUiUrl, options);
+  return `${options.openshellShellCommand(
+    ["forward", "start", "--background", forwardTarget, sandboxName],
+    options,
+  )}`;
+}
+
+export function buildAuthenticatedDashboardUrl(baseUrl: string, token: string | null = null): string {
+  if (!token) return baseUrl;
+  return `${baseUrl}#token=${encodeURIComponent(token)}`;
+}
+
+export function dashboardUrlForDisplay(url: string, redact: (value: string) => string = (value) => value): string {
+  return redact(url.replace(/#token=[^\s'"]*$/i, ""));
+}
+
+export function getDashboardAccessInfo(
+  sandboxName: string,
+  options: DashboardAccessOptions = {},
+): DashboardAccessEntry[] {
+  const token = Object.prototype.hasOwnProperty.call(options, "token")
+    ? options.token
+    : options.fetchGatewayAuthToken?.(sandboxName) ?? null;
+  const chatUiUrl = defaultChatUiUrl(options);
+  const chain = buildDashboardChain(chatUiUrl, options);
+  const dashboardAccess = buildControlUiUrls(token ?? null, chain.port, chain.accessUrl).map(
+    (url, index) => ({
+      label: index === 0 ? "Dashboard" : `Alt ${index}`,
+      url: buildAuthenticatedDashboardUrl(url, null),
+    }),
+  );
+
+  const wslHostAddress = getWslHostAddress(options);
+  if (wslHostAddress) {
+    const wslUrl = buildAuthenticatedDashboardUrl(`http://${wslHostAddress}:${chain.port}/`, token ?? null);
+    if (!dashboardAccess.some((access) => access.url === wslUrl)) {
+      dashboardAccess.push({ label: "VS Code/WSL", url: wslUrl });
+    }
+  }
+
+  return dashboardAccess;
+}
+
+export function getDashboardGuidanceLines(
+  dashboardAccess: DashboardAccessEntry[] = [],
+  options: DashboardAccessOptions = {},
+): string[] {
+  const chatUiUrl = defaultChatUiUrl(options);
+  const chain = buildDashboardChain(chatUiUrl, options);
+  const guidance = [`Port ${String(chain.port)} must be forwarded before opening these URLs.`];
+  if (isWsl(options)) {
+    guidance.push(
+      "WSL detected: if localhost fails in Windows, use the WSL host IP shown by `hostname -I`.",
+    );
+  }
+  if (dashboardAccess.length === 0) {
+    guidance.push("No dashboard URLs were generated.");
+  }
+  return guidance;
+}

src/lib/onboard/gateway-bootstrap.test.ts

@@ -0,0 +1,86 @@
+// 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 {
+  buildGatewayBootstrapSecretsScript,
+  createGatewayBootstrapRepairHelpers,
+  getGatewayBootstrapRepairPlan,
+} from "./gateway-bootstrap";
+
+describe("gateway bootstrap helpers", () => {
+  it("normalizes missing secrets into a repair plan", () => {
+    expect(
+      getGatewayBootstrapRepairPlan([
+        "openshell-client-tls",
+        "noise",
+        " openshell-server-tls ",
+        "",
+      ]),
+    ).toEqual({
+      missingSecrets: ["openshell-client-tls", "openshell-server-tls"],
+      needsRepair: true,
+      needsServerTls: true,
+      needsClientBundle: true,
+      needsHandshake: false,
+    });
+  });
+
+  it("builds a no-op script when nothing is missing", () => {
+    expect(buildGatewayBootstrapSecretsScript([]).trim()).toBe("exit 0");
+  });
+
+  it("builds a repair script only for requested secret classes", () => {
+    const script = buildGatewayBootstrapSecretsScript([
+      "openshell-server-tls",
+      "openshell-ssh-handshake",
+    ]);
+
+    expect(script).toContain("openshell-server-tls");
+    expect(script).toContain("openshell-ssh-handshake");
+    expect(script).toContain("if true; then");
+    expect(script).toContain("if false; then");
+  });
+
+  it("lists missing secrets through the gateway cluster executor", () => {
+    const buildGatewayClusterExecArgv = vi.fn((script: string) => ["docker", "exec", script]);
+    const runCapture = vi.fn(() => "openshell-client-tls\n\nopenshell-server-tls\n");
+    const helpers = createGatewayBootstrapRepairHelpers({
+      buildGatewayClusterExecArgv,
+      run: vi.fn(() => ({ status: 0 })),
+      runCapture,
+    });
+
+    expect(helpers.listMissingGatewayBootstrapSecrets()).toEqual([
+      "openshell-client-tls",
+      "openshell-server-tls",
+    ]);
+    expect(runCapture).toHaveBeenCalledWith(
+      expect.arrayContaining([expect.stringContaining("kubectl -n openshell get secret")]),
+      { ignoreError: true },
+    );
+  });
+
+  it("repairs missing secrets and reports success when the second probe is clean", () => {
+    const log = vi.fn();
+    const runCapture = vi
+      .fn()
+      .mockReturnValueOnce("openshell-client-tls\n")
+      .mockReturnValueOnce("");
+    const run = vi.fn(() => ({ status: 0 }));
+    const helpers = createGatewayBootstrapRepairHelpers({
+      buildGatewayClusterExecArgv: (script) => ["docker", "exec", script],
+      run,
+      runCapture,
+      log,
+    });
+
+    expect(helpers.repairGatewayBootstrapSecrets()).toEqual({ repaired: true, missingSecrets: [] });
+    expect(run).toHaveBeenCalledWith(expect.any(Array), {
+      ignoreError: true,
+      suppressOutput: true,
+    });
+    expect(log).toHaveBeenCalledWith("  ✓ OpenShell bootstrap secrets created");
+  });
+});