refactor(cli): start onboarding fsm migration

.pre-commit-config.yaml

@@ -183,7 +183,7 @@ repos:
     hooks:
       - id: hadolint
         name: hadolint
-        entry: hadolint
+        entry: scripts/run-hadolint.sh
         language: system
         files: (Dockerfile[^/]*|.*\.dockerfile)$
         types: [file]

CONTRIBUTING.md

@@ -1,3 +1,6 @@
+<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+
 # Contributing to NVIDIA NemoClaw
 
 Thank you for your interest in contributing to NVIDIA NemoClaw. This guide covers how to set up your development environment, run tests, and submit changes.
@@ -18,7 +21,7 @@ Install the following before you begin.
 - Python 3.11+ (for blueprint and documentation builds)
 - Docker (running)
 - [uv](https://docs.astral.sh/uv/) (for Python dependency management)
-- [hadolint](https://github.com/hadolint/hadolint) (Dockerfile linter — `brew install hadolint` on macOS)
+- [hadolint](https://github.com/hadolint/hadolint) (Dockerfile linter — either install it locally, e.g. `brew install hadolint` on macOS, or keep Docker available for the pinned container fallback)
 
 ## Getting Started
 
@@ -92,6 +95,8 @@ All git hooks are managed by [prek](https://prek.j178.dev/), a fast, single-bina
 
 For a full manual check: `npx prek run --all-files`. For scoped runs: `npx prek run --from-ref <base> --to-ref HEAD`.
 
+If `hadolint` is not on your `PATH`, the local `hadolint` hook falls back to the pinned `hadolint/hadolint:v2.14.0` Docker image automatically. Dockerfile linting is still required, so contributors must have either a local `hadolint` binary or a working Docker daemon.
+
 If you still have `core.hooksPath` set from an old Husky setup, Git will ignore `.git/hooks`. Run `git config --unset core.hooksPath` in this repo, then `npm install` so `prek install` (via `prepare`) can register the hooks.
 
 `make check` remains the primary documented linter entry point.

scripts/run-hadolint.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+set -euo pipefail
+
+readonly HADOLINT_IMAGE="${HADOLINT_IMAGE:-hadolint/hadolint:v2.14.0}"
+
+run_via_docker() {
+  if ! command -v docker >/dev/null 2>&1; then
+    printf '%s\n' "hadolint is not installed and Docker is unavailable." >&2
+    printf '%s\n' "Install hadolint locally or make Docker available, then rerun prek." >&2
+    return 127
+  fi
+
+  if ! docker info >/dev/null 2>&1; then
+    printf '%s\n' "hadolint is not installed and Docker is not ready." >&2
+    printf '%s\n' "Start Docker or install hadolint locally, then rerun prek." >&2
+    return 1
+  fi
+
+  printf '%s\n' "hadolint not found on PATH; linting Dockerfiles via Docker image ${HADOLINT_IMAGE}" >&2
+
+  exec docker run --rm \
+    -v "${PWD}:${PWD}" \
+    -w "${PWD}" \
+    "${HADOLINT_IMAGE}" \
+    hadolint "$@"
+}
+
+main() {
+  if command -v hadolint >/dev/null 2>&1; then
+    exec hadolint "$@"
+  fi
+
+  run_via_docker "$@"
+}
+
+main "$@"

src/lib/ansi-utils.ts

@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Strip ANSI escape sequences from terminal-oriented output.
+ * Covers CSI (color, erase, cursor), OSC, and C1 two-byte escapes per ECMA-48.
+ */
+export const ANSI_RE = /\x1B(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\)|[@-_])/g;
+
+export function stripAnsi(value: string): string {
+  return String(value || "").replace(ANSI_RE, "");
+}

src/lib/onboard-bootstrap.test.ts

@@ -0,0 +1,149 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+const require = createRequire(import.meta.url);
+const bootstrapDistPath = require.resolve("../../dist/lib/onboard-bootstrap");
+const persistentDriverDistPath = require.resolve("../../dist/lib/onboard-persistent-driver");
+const flowStateDistPath = require.resolve("../../dist/lib/onboard-flow-state");
+const sessionDistPath = require.resolve("../../dist/lib/onboard-session");
+const originalHome = process.env.HOME;
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "nemoclaw-bootstrap-"));
+  process.env.HOME = tmpDir;
+  delete require.cache[bootstrapDistPath];
+  delete require.cache[persistentDriverDistPath];
+  delete require.cache[flowStateDistPath];
+  delete require.cache[sessionDistPath];
+});
+
+afterEach(() => {
+  delete require.cache[bootstrapDistPath];
+  delete require.cache[persistentDriverDistPath];
+  delete require.cache[flowStateDistPath];
+  delete require.cache[sessionDistPath];
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+  if (originalHome === undefined) {
+    delete process.env.HOME;
+  } else {
+    process.env.HOME = originalHome;
+  }
+});
+
+describe("initializeOnboardRun", () => {
+  it("creates a fresh session and resolves --from paths", () => {
+    const { initializeOnboardRun } = require("../../dist/lib/onboard-bootstrap");
+
+    const result = initializeOnboardRun({
+      resume: false,
+      mode: "non-interactive",
+      requestedFromDockerfile: "./Dockerfile.custom",
+      requestedAgent: "hermes",
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      throw new Error("expected fresh onboarding initialization to succeed");
+    }
+    expect(result.value.session.mode).toBe("non-interactive");
+    expect(result.value.session.agent).toBe("hermes");
+    expect(result.value.fromDockerfile).toBe(path.resolve("./Dockerfile.custom"));
+    expect(result.value.driver.session?.metadata.fromDockerfile).toBe(
+      path.resolve("./Dockerfile.custom"),
+    );
+  });
+
+  it("returns a friendly error when no resumable session exists", () => {
+    const { initializeOnboardRun } = require("../../dist/lib/onboard-bootstrap");
+
+    const result = initializeOnboardRun({
+      resume: true,
+      mode: "interactive",
+      requestedFromDockerfile: null,
+      requestedAgent: null,
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      lines: ["  No resumable onboarding session was found.", "  Run: nemoclaw onboard"],
+    });
+  });
+
+  it("reports resume conflicts using the shared formatter", () => {
+    const onboardSession = require("../../dist/lib/onboard-session");
+    const { initializeOnboardRun } = require("../../dist/lib/onboard-bootstrap");
+
+    onboardSession.saveSession(
+      onboardSession.createSession({
+        sandboxName: "alpha",
+        provider: "nvidia-prod",
+        model: "meta/llama-3.3-70b-instruct",
+      }),
+    );
+
+    const result = initializeOnboardRun({
+      resume: true,
+      mode: "interactive",
+      requestedFromDockerfile: null,
+      requestedAgent: null,
+      getResumeConflicts: (session: { sandboxName: string | null; provider: string | null }) => [
+        { field: "sandbox", requested: "beta", recorded: session.sandboxName },
+        { field: "provider", requested: "openai-api", recorded: session.provider },
+      ],
+    });
+
+    expect(result).toEqual({
+      ok: false,
+      lines: [
+        "  Resumable state belongs to sandbox 'alpha', not 'beta'.",
+        "  Resumable state recorded provider 'nvidia-prod', not 'openai-api'.",
+        "  Run: nemoclaw onboard              # start a fresh onboarding session",
+        "  Or rerun with the original settings to continue that session.",
+      ],
+    });
+  });
+
+  it("loads a resumable session, reuses the recorded Dockerfile, and clears failure state", () => {
+    const onboardSession = require("../../dist/lib/onboard-session");
+    const { initializeOnboardRun } = require("../../dist/lib/onboard-bootstrap");
+
+    onboardSession.saveSession(
+      onboardSession.createSession({
+        mode: "interactive",
+        status: "failed",
+        sandboxName: "alpha",
+        metadata: { gatewayName: "nemoclaw", fromDockerfile: "/tmp/Recorded.Dockerfile" },
+        failure: {
+          step: "policies",
+          message: "policy apply failed",
+          recordedAt: "2026-04-17T00:00:00.000Z",
+        },
+      }),
+    );
+
+    const result = initializeOnboardRun({
+      resume: true,
+      mode: "non-interactive",
+      requestedFromDockerfile: null,
+      requestedAgent: null,
+      getResumeConflicts: () => [],
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      throw new Error("expected resume initialization to succeed");
+    }
+    expect(result.value.fromDockerfile).toBe("/tmp/Recorded.Dockerfile");
+    expect(result.value.session.mode).toBe("non-interactive");
+    expect(result.value.session.status).toBe("in_progress");
+    expect(result.value.session.failure).toBeNull();
+  });
+});

src/lib/onboard-bootstrap.ts

@@ -0,0 +1,100 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import path from "node:path";
+
+import { PersistentOnboardDriver } from "./onboard-persistent-driver";
+import { buildResumeConflictLines, type ResumeConfigConflict } from "./onboard-resume";
+import { createSession, type Session } from "./onboard-session";
+
+export interface InitializeOnboardRunOptions {
+  resume: boolean;
+  mode: Session["mode"];
+  requestedFromDockerfile: string | null;
+  requestedAgent: string | null;
+  getResumeConflicts?: (session: Session) => ResumeConfigConflict[];
+}
+
+export interface InitializedOnboardRun {
+  driver: PersistentOnboardDriver;
+  session: Session;
+  fromDockerfile: string | null;
+}
+
+export interface InitializeOnboardRunFailure {
+  ok: false;
+  lines: string[];
+}
+
+export interface InitializeOnboardRunSuccess {
+  ok: true;
+  value: InitializedOnboardRun;
+}
+
+export type InitializeOnboardRunResult =
+  | InitializeOnboardRunFailure
+  | InitializeOnboardRunSuccess;
+
+export function initializeOnboardRun(
+  options: InitializeOnboardRunOptions,
+): InitializeOnboardRunResult {
+  const driver = new PersistentOnboardDriver({ resume: options.resume });
+
+  if (options.resume) {
+    const session = driver.session;
+    if (!session || session.resumable === false) {
+      return {
+        ok: false,
+        lines: ["  No resumable onboarding session was found.", "  Run: nemoclaw onboard"],
+      };
+    }
+
+    const sessionFrom = session.metadata.fromDockerfile || null;
+    const fromDockerfile = options.requestedFromDockerfile
+      ? path.resolve(options.requestedFromDockerfile)
+      : sessionFrom
+        ? path.resolve(sessionFrom)
+        : null;
+    const resumeConflicts = options.getResumeConflicts?.(session) ?? [];
+    if (resumeConflicts.length > 0) {
+      return {
+        ok: false,
+        lines: buildResumeConflictLines(resumeConflicts),
+      };
+    }
+
+    const updatedSession = driver.update((current) => {
+      current.mode = options.mode;
+      current.failure = null;
+      current.status = "in_progress";
+      return current;
+    });
+    return {
+      ok: true,
+      value: {
+        driver,
+        session: updatedSession,
+        fromDockerfile,
+      },
+    };
+  }
+
+  const fromDockerfile = options.requestedFromDockerfile
+    ? path.resolve(options.requestedFromDockerfile)
+    : null;
+  const session = driver.replaceSession(
+    createSession({
+      mode: options.mode,
+      agent: options.requestedAgent,
+      metadata: { gatewayName: "nemoclaw", fromDockerfile: fromDockerfile || null },
+    }),
+  );
+  return {
+    ok: true,
+    value: {
+      driver,
+      session,
+      fromDockerfile,
+    },
+  };
+}