refactor(onboard): extract preflight and gateway FSM phases

[cv]

Summary

Add reusable FSM phase wrappers for preflight and gateway. These wrappers map existing handler outputs into OnboardFlowContext updates plus explicit FSM results.

Changes

• Add createPreflightPhase() and createGatewayPhase() under onboard machine flow phases.
• Map preflight outputs such as GPU, sandbox GPU config, passthrough, and session into the flow context.
• Add tests for phase state names, context updates, and returned FSM results.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Verification

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

• Tests

  • Added comprehensive test suite for preflight and gateway onboarding flow phases, covering handler execution, context mapping, and state transitions.

• Improvements

  • Introduced factory functions for preflight and gateway onboarding flow phases with enhanced session management and GPU configuration handling.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 1ae2f61a-a57d-48a5-bfab-076fb8fba80b

📥 Commits

Reviewing files that changed from the base of the PR and between 3db6971 and c123223.

📒 Files selected for processing (2)

• src/lib/onboard/machine/flow-phases/preflight-gateway.test.ts
• src/lib/onboard/machine/flow-phases/preflight-gateway.ts

---

📝 Walkthrough

Walkthrough

Adds two factory functions (createPreflightPhase and createGatewayPhase) that create onboarding flow sequence phases, with comprehensive test coverage. The factories accept handler functions, await their results, merge selected output fields into the flow context, and return phase objects that transition the FSM to the next state.

Changes

Onboarding Preflight and Gateway Phase Factories

Layer / File(s)	Summary
Factory implementation for preflight and gateway phases src/lib/onboard/machine/flow-phases/preflight-gateway.ts	Exports createPreflightPhase and createGatewayPhase factories that build OnboardSequencePhase objects with state identifiers "preflight" and "gateway". Each factory's async run method awaits a caller-provided handler, merges specific handler output fields into the flow context using mergeOnboardFlowContext, and returns a structured phase result via onboardFlowPhaseResult. Preflight merges session, gpu, sandboxGpuConfig, and gpuPassthrough; gateway merges session only.
Tests for phase factory behavior src/lib/onboard/machine/flow-phases/preflight-gateway.test.ts	Defines a context() helper factory that initializes OnboardFlowContext with default values. First test validates that createPreflightPhase invokes its handler once, correctly merges GPU and passthrough data, and transitions FSM state to "gateway". Second test validates that createGatewayPhase merges the handler's session and transitions FSM state to "provider_selection".

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4481: Introduces the OnboardFlowContext, mergeOnboardFlowContext, and onboardFlowPhaseResult helpers that are directly used by this PR's factory functions.
• NVIDIA/NemoClaw#4446: Updates the preflight→gateway→provider_selection flow alignment; this PR's factories and tests assert the mapping of handler outputs into flow context and FSM transitions.
• NVIDIA/NemoClaw#4475: This PR's OnboardSequencePhase objects are designed to be executed by the sequence-runner adapter.

Suggested labels

onboarding

Suggested reviewers

• prekshivyas
• cjagwani
• jyaunches

Poem

🐰 Two phases hop along the flow,
Preflight checks and gateways show,
Handlers merge with context bright,
FSM transitions take their flight! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor(onboard): extract preflight and gateway FSM phases' directly and specifically summarizes the main change—extracting two reusable FSM phase wrappers for the onboarding machine, which aligns with the additions of createPreflightPhase() and createGatewayPhase() functions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/onboard-fsm-preflight-gateway-phases

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

E2E Advisor Recommendation

Required E2E: ubuntu-repo-cloud-openclaw, ubuntu-no-docker-preflight-negative, ubuntu-gateway-port-conflict-negative
Optional E2E: gpu-repo-local-ollama-openclaw, ubuntu-repo-cloud-openclaw-resume

Dispatch hint: ubuntu-repo-cloud-openclaw,ubuntu-no-docker-preflight-negative,ubuntu-gateway-port-conflict-negative

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• ubuntu-repo-cloud-openclaw (medium): Canonical live Ubuntu onboarding path exercises preflight, gateway startup, provider selection, sandbox creation, credentials, and inference smoke after the touched FSM handoff points.
• ubuntu-no-docker-preflight-negative (low): Validates the preflight failure boundary: when preflight cannot pass, onboarding must stop cleanly without starting the gateway or creating a sandbox.
• ubuntu-gateway-port-conflict-negative (low): Validates the gateway failure boundary and forbidden side effects around gateway startup, which is directly adjacent to the new gateway phase adapter.

Optional E2E

• gpu-repo-local-ollama-openclaw (high): Useful additional confidence because the new preflight adapter propagates gpu, sandboxGpuConfig, and gpuPassthrough into flow context; this scenario validates the GPU/local Ollama onboarding path on a GPU runner.
• ubuntu-repo-cloud-openclaw-resume (medium): Optional coverage for resume behavior near cached preflight/gateway state if the new phase adapters are used by the resumable onboarding sequence.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/e2e-scenarios.yaml
• jobs input: ubuntu-repo-cloud-openclaw,ubuntu-no-docker-preflight-negative,ubuntu-gateway-port-conflict-negative

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: ubuntu-repo-cloud-openclaw, ubuntu-no-docker-preflight-negative, ubuntu-gateway-port-conflict-negative
Optional scenario E2E: gpu-repo-local-ollama-openclaw, wsl-repo-cloud-openclaw

Dispatch required scenario E2E:

• gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
• gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-no-docker-preflight-negative
• gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-gateway-port-conflict-negative

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• ubuntu-repo-cloud-openclaw: Core onboarding preflight/gateway flow phase code changed. This baseline Ubuntu repo scenario exercises the normal preflight-passed path, gateway startup, sandbox creation, and baseline onboarding checks.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw
• ubuntu-no-docker-preflight-negative: Preflight phase result/context handling changed; this negative scenario is the targeted coverage for expected preflight failure before gateway or sandbox side effects.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-no-docker-preflight-negative
• ubuntu-gateway-port-conflict-negative: Gateway phase result/session handling changed; this scenario specifically exercises expected gateway startup failure handling via a port conflict.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-gateway-port-conflict-negative

Optional scenario E2E

• gpu-repo-local-ollama-openclaw: Optional special-runner coverage because the changed preflight phase propagates GPU-related context fields; this is the scenario that exercises GPU/CDI local Ollama onboarding.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=gpu-repo-local-ollama-openclaw
• wsl-repo-cloud-openclaw: Optional adjacent platform coverage for the same cloud OpenClaw preflight/gateway onboarding path on WSL; special-runner/platform scenario, so not primary required coverage.
  • Dispatch: gh workflow run e2e-scenarios.yaml --ref <pr-head-ref> --field scenarios=wsl-repo-cloud-openclaw

Relevant changed files

• src/lib/onboard/machine/flow-phases/preflight-gateway.test.ts
• src/lib/onboard/machine/flow-phases/preflight-gateway.ts

[github-actions]

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 0 still apply, 0 new items found

Consider writing more tests for

• **Runtime validation** — Preflight-to-gateway sequence propagation — run runOnboardSequenceWithRunner with createPreflightPhase() and createGatewayPhase() and assert the gateway handler receives preflight's updated session, gpu, sandboxGpuConfig, and gpuPassthrough, then advances to provider_selection.. The direct unit tests are sufficient for the isolated adapter logic in this additive patch. Because these factories are intended for the onboarding FSM sequence path, targeted runtime-style validation would improve confidence before or during future wiring.
• **Runtime validation** — Handler input identity and unrelated-field preservation — assert each wrapped handler receives the exact input context object and fields outside the merge patch, such as provider, model, and hermesToolGateways, survive unchanged.. The direct unit tests are sufficient for the isolated adapter logic in this additive patch. Because these factories are intended for the onboarding FSM sequence path, targeted runtime-style validation would improve confidence before or during future wiring.
• **Runtime validation** — Handler rejection propagation — assert rejecting runPreflight and rejecting runGateway reject phase.run() rather than producing a successful FSM result.. The direct unit tests are sufficient for the isolated adapter logic in this additive patch. Because these factories are intended for the onboarding FSM sequence path, targeted runtime-style validation would improve confidence before or during future wiring.
• **Runtime validation** — Existing-handler adapter compatibility — when wiring to handlePreflightState and handleGatewayState, assert their stateResult output is translated or renamed into the phase handler result contract.. The direct unit tests are sufficient for the isolated adapter logic in this additive patch. Because these factories are intended for the onboarding FSM sequence path, targeted runtime-style validation would improve confidence before or during future wiring.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[github-actions]

Selective E2E Results — ✅ All requested jobs passed

Run: 27227316169
Target ref: adbbdfa95cfdc71d5992f8cf3130421c6ef2c2b2
Workflow ref: stack/onboard-fsm-flow-context
Requested jobs: cloud-onboard-e2e,onboard-negative-paths-e2e
Summary: 2 passed, 0 failed, 0 skipped

Job	Result
cloud-onboard-e2e	✅ success
onboard-negative-paths-e2e	✅ success