Skip to content

refactor(onboard): add refined flow context guards#5559

Merged
cv merged 1 commit into
mainfrom
refactor/onboard-flow-context-assertions
Jun 20, 2026
Merged

refactor(onboard): add refined flow context guards#5559
cv merged 1 commit into
mainfrom
refactor/onboard-flow-context-assertions

Conversation

@cv

@cv cv commented Jun 20, 2026

Copy link
Copy Markdown
Collaborator

Summary

Add shared refined onboarding flow context types and assertion helpers for the first #5518 nullability cleanup. The core and final onboard phases now reuse those guards instead of carrying local ad hoc not-null checks.

Related Issue

Refs #5518

Changes

  • Add ProviderSelectedOnboardFlowContext, SandboxCreatedOnboardFlowContext, and FinalOnboardFlowContext aliases in src/lib/onboard/machine/flow-context.ts.
  • Add shared assertProviderSelectedContext and assertSandboxCreatedContext helpers to narrow phase context before dependent work runs.
  • Replace local context completeness checks in core and final flow phases with the shared assertions.
  • Add unit coverage for the new flow-context assertion helpers.

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

  • Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes
  • Targeted tests pass for changed behavior
  • Full npm test passes (broad runtime changes only)
  • 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

  • Chores

    • Refactored internal onboarding validation logic to improve consistency and maintainability through centralized assertion helpers.
  • Tests

    • Added comprehensive test coverage for onboarding milestone validations.

Signed-off-by: Carlos Villela <cvillela@nvidia.com>
@cv cv self-assigned this Jun 20, 2026
@coderabbitai

coderabbitai Bot commented Jun 20, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Introduces two typed context refinements (ProviderSelectedOnboardFlowContext, SandboxCreatedOnboardFlowContext) and two runtime assertion helpers (assertProviderSelectedContext, assertSandboxCreatedContext) in flow-context.ts. These replace an inline guard in the sandbox phase and a local requireFinalContext helper in final flow phases. Tests are added for both assertions.

Onboarding FSM context assertion refactor

Layer / File(s) Summary
Context type refinements and assertion helpers
src/lib/onboard/machine/flow-context.ts
Adds ProviderSelectedOnboardFlowContext, SandboxCreatedOnboardFlowContext, and FinalOnboardFlowContext type aliases. Introduces assertProviderSelectedContext (checks model, provider, sandboxGpuConfig) and assertSandboxCreatedContext (checks sandboxName, model, provider), both throwing a uniform error message and narrowing the context type via asserts. Relocates OnboardFlowPhaseResult to below the new types.
Flow phase guards replaced with shared assertions
src/lib/onboard/machine/core-flow-phases.ts, src/lib/onboard/machine/final-flow-phases.ts
Imports assertProviderSelectedContext in core-flow-phases.ts and replaces the inline completeness check in the sandbox phase. Imports assertSandboxCreatedContext in final-flow-phases.ts, removes the local requireFinalContext helper, and substitutes it in agent setup, policies, and finalization phase preconditions.
Tests for assertion helpers
src/lib/onboard/machine/flow-context.test.ts
Adds test cases that verify assertProviderSelectedContext and assertSandboxCreatedContext do not throw on valid contexts and throw with the expected message pattern when required fields are absent.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • NVIDIA/NemoClaw#4507: Touches final-flow-phases.ts orchestration and the same completeness-check pattern for policies and finalization phases that this PR centralizes into assertSandboxCreatedContext.

Suggested labels

refactor, area: onboarding, v0.0.64

Poem

🐇 Hopping through phases with guards so refined,
No scattered inline checks left behind!
assertProvider, assertSandbox — names crisp and true,
A single shared helper for every phase cue.
The FSM leaps forward, its context all tight,
This bunny approves — the types are just right! ✨

🚥 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 accurately summarizes the main change: introducing refined flow context types and assertion helpers to guard onboarding phases.
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 refactor/onboard-flow-context-assertions

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

@github-code-quality

github-code-quality Bot commented Jun 20, 2026

Copy link
Copy Markdown

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the branch is 96%. Coverage data for the branch is not yet available.

Show a code coverage summary of the most covered files.
File dfd7bf1 +/-
nemoclaw/src/se...cret-scanner.ts 100%
nemoclaw/src/commands/slash.ts 100%
nemoclaw/src/li...bprocess-env.ts 100%
nemoclaw/src/bl...eprint/state.ts 98%
nemoclaw/src/onboard/config.ts 98%
nemoclaw/src/bl...int/snapshot.ts 97%
nemoclaw/src/bl...print/runner.ts 95%
nemoclaw/src/co...ration-state.ts 94%
nemoclaw/src/bl...ate-networks.ts 94%
nemoclaw/src/index.ts 94%

TypeScript / code-coverage/cli

The overall coverage in the branch is 46%. Coverage data for the branch is not yet available.

Show a code coverage summary of the most covered files.
File dfd7bf1 +/-
src/lib/state/o...oard-session.ts 90%
src/lib/inference/local.ts 76%
src/lib/sandbox/config.ts 72%
src/lib/actions...dbox/rebuild.ts 67%
src/lib/onboard/preflight.ts 64%
src/lib/actions...licy-channel.ts 56%
src/lib/state/sandbox.ts 55%
src/lib/policy/index.ts 49%
src/lib/onboard...er-gpu-patch.ts 44%
src/lib/onboard.ts 18%

Updated June 20, 2026 16:06 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.

@github-actions

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: cloud-e2e, onboard-resume-e2e, onboard-repair-e2e
Optional E2E: cloud-onboard-e2e, network-policy-e2e

Dispatch hint: cloud-e2e,onboard-resume-e2e,onboard-repair-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • cloud-e2e (high): Runs the standard full OpenClaw install/onboard/sandbox/inference path and is the best merge-blocking coverage for changes in the onboarding phase machine from provider selection through final assistant readiness.
  • onboard-resume-e2e (medium): The changed phase guards sit on resume-compatible onboard slices; this job validates disrupted onboard recovery does not fail due to missing or incorrectly narrowed context across provider, sandbox, and final phases.
  • onboard-repair-e2e (medium): Validates repair/reconciliation behavior around already-created or partially-created onboarding state, which is directly adjacent to the shared assertions added before sandbox and final phase handlers.

Optional E2E

  • cloud-onboard-e2e (high): Useful extra confidence for the public installer plus cloud onboard path, sandbox health, security checks, and inference.local. It is adjacent but less targeted than the source full E2E and resume/repair jobs for this PR.
  • network-policy-e2e (medium): The final phases include the policies step, so this is a useful adjacent check if maintainers want extra confidence that reaching and applying policies still works after the shared final-context assertion change.

New E2E recommendations

  • None.

Dispatch hint

  • Workflow: .github/workflows/nightly-e2e.yaml
  • jobs input: cloud-e2e,onboard-resume-e2e,onboard-repair-e2e

@github-actions

Copy link
Copy Markdown
Contributor

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: ubuntu-repo-cloud-openclaw
Optional Vitest E2E scenarios: ubuntu-repo-docker-post-reboot-recovery

Dispatch required Vitest E2E scenarios:

  • gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Workflow run

Full Vitest E2E advisor summary

Vitest E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

  • ubuntu-repo-cloud-openclaw: The PR changes shared onboarding flow context assertions used before sandbox setup and final OpenClaw phases. The baseline live-supported OpenClaw scenario is the smallest typed Vitest scenario that exercises the affected provider-selected and sandbox-created context transitions end to end.
    • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional Vitest E2E scenarios

  • ubuntu-repo-docker-post-reboot-recovery: Optional adjacent coverage for the same OpenClaw onboarding flow with a supported lifecycle profile, useful if maintainers want extra confidence that the context assertion refactor does not affect recovery-oriented onboarding state.
    • Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-docker-post-reboot-recovery

Relevant changed files

  • src/lib/onboard/machine/core-flow-phases.ts
  • src/lib/onboard/machine/final-flow-phases.ts
  • src/lib/onboard/machine/flow-context.ts

@github-actions

Copy link
Copy Markdown
Contributor

PR Review Advisor

Findings: 0 needs attention, 0 worth checking, 0 nice ideas

Consider writing more tests for
  • **Runtime validation** — `createCoreOnboardFlowPhases` sandbox phase rejects missing `model`, `provider`, or `sandboxGpuConfig` before invoking sandbox setup dependencies.. The changed code sits on onboarding runtime/sandbox phase boundaries. Existing helper-level unit tests cover the new assertions and the refactor appears behavior-preserving, but phase-level tests would provide extra confidence that handlers are not invoked with incomplete context.
  • **Runtime validation** — `createFinalOnboardFlowPhases` agent setup, policies, and finalization phases reject missing `sandboxName`, `model`, or `provider` before invoking their handlers.. The changed code sits on onboarding runtime/sandbox phase boundaries. Existing helper-level unit tests cover the new assertions and the refactor appears behavior-preserving, but phase-level tests would provide extra confidence that handlers are not invoked with incomplete context.
  • **Runtime validation** — Complete provider-selected and sandbox-created contexts still reach the corresponding phase handlers with the same required fields after the shared guard refactor.. The changed code sits on onboarding runtime/sandbox phase boundaries. Existing helper-level unit tests cover the new assertions and the refactor appears behavior-preserving, but phase-level tests would provide extra confidence that handlers are not invoked with incomplete context.

Workflow run details

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
src/lib/onboard/machine/flow-context.test.ts (1)

76-80: ⚡ Quick win

Add an isolated failure test for missing sandboxGpuConfig in provider-selected context.

This test currently fails because multiple required fields are missing, so it won’t catch regressions where only the sandboxGpuConfig check is removed.

Proposed test addition
   it("rejects missing provider-selected context fields", () => {
     expect(() => assertProviderSelectedContext(baseContext(), "sandbox setup")).toThrow(
       /Onboarding state is incomplete before sandbox setup\./,
     );
   });
+
+  it("rejects missing sandboxGpuConfig before sandbox setup", () => {
+    const context = mergeOnboardFlowContext(baseContext(), {
+      provider: "nvidia-prod",
+      model: "model",
+      sandboxGpuConfig: null,
+    });
+
+    expect(() => assertProviderSelectedContext(context, "sandbox setup")).toThrow(
+      /Onboarding state is incomplete before sandbox setup\./,
+    );
+  });
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/onboard/machine/flow-context.test.ts` around lines 76 - 80, The
current test "rejects missing provider-selected context fields" fails due to
multiple missing fields, which won't catch regressions if only the
sandboxGpuConfig validation is removed. Add a new isolated test case that calls
assertProviderSelectedContext with a baseContext that provides all other
required provider-selected context fields but specifically omits only the
sandboxGpuConfig field, ensuring the test validates sandboxGpuConfig validation
in isolation and will catch if that specific check is accidentally removed.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/onboard/machine/flow-context.test.ts`:
- Around line 76-80: The current test "rejects missing provider-selected context
fields" fails due to multiple missing fields, which won't catch regressions if
only the sandboxGpuConfig validation is removed. Add a new isolated test case
that calls assertProviderSelectedContext with a baseContext that provides all
other required provider-selected context fields but specifically omits only the
sandboxGpuConfig field, ensuring the test validates sandboxGpuConfig validation
in isolation and will catch if that specific check is accidentally removed.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7d77c7b9-c47f-4c3f-a53b-5ead91e09820

📥 Commits

Reviewing files that changed from the base of the PR and between df54922 and dfd7bf1.

📒 Files selected for processing (4)
  • src/lib/onboard/machine/core-flow-phases.ts
  • src/lib/onboard/machine/final-flow-phases.ts
  • src/lib/onboard/machine/flow-context.test.ts
  • src/lib/onboard/machine/flow-context.ts

@cv cv merged commit ca229cb into main Jun 20, 2026
46 checks passed
@cv cv deleted the refactor/onboard-flow-context-assertions branch June 20, 2026 16:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant