refactor(onboard): extract entry option resolution by cv · Pull Request #5161 · NVIDIA/NemoClaw

cv · 2026-06-10T17:55:59Z

Summary

Extracts the first-pass onboarding option resolution from onboard() into a small helper. The helper now owns --resume/--fresh validation, --from and non-interactive env fallback handling, early sandbox-name validation, reserved-name checks, and the no-TTY --from name guard.

Related Issue

Refs #3802

Changes

Added resolveOnboardEntryOptions in src/lib/onboard/entry-options.ts.
Replaced the inline opening option-resolution block in onboard() with the new helper call.
Added unit coverage for mutually-exclusive flags, non-interactive env fallbacks, missing sandbox names for --from, resume deferral, reserved names, and validation guidance.
Extended test/e2e/test-onboard-negative-paths.sh with --from entry-option guard coverage, including the no-name guard and the env-provided sandbox-name path.
Addressed PR advisor feedback by keeping reserved-name rejection outside the validation-error catch, with assertions that the path does not print validation guidance or double-exit.
Refreshed the resume guard comment in onboard.ts so it references resolveOnboardEntryOptions instead of stale line numbers.

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

Targeted checks run:

npx @biomejs/biome format --write src/lib/onboard.ts src/lib/onboard/entry-options.ts src/lib/onboard/entry-options.test.ts
npx @biomejs/biome lint src/lib/onboard.ts src/lib/onboard/entry-options.ts src/lib/onboard/entry-options.test.ts
npm run build:cli
npm run typecheck:cli
npx vitest run src/lib/onboard/entry-options.test.ts test/onboard.test.ts test/cli/onboard-compatibility.test.ts (87 tests)
CI=true npx vitest run --project installer-integration test/install-preflight.test.ts (104 tests; rerun locally after the CI installer-integration timeout)
bash -n test/e2e/test-onboard-negative-paths.sh
Direct CLI probe: --from Dockerfile without --name/NEMOCLAW_SANDBOX_NAME exits 1 with the explicit missing-name guard and no stack trace.
Direct CLI probe: --from Dockerfile with NEMOCLAW_SANDBOX_NAME="bad name" exits 1 at sandbox-name validation and does not print the missing-name guard.
git diff --check

GitHub/remote validation:

Standard PR checks passed on 726a539b0416e0cd86274fac43290382c6edee22.
PR Review Advisor: 0 needs attention, 0 worth checking, 0 nice ideas.
CodeRabbit: skipped because this PR is draft.
Required nightly E2E onboard-negative-paths-e2e passed: https://github.com/NVIDIA/NemoClaw/actions/runs/27297021441
Required scenario E2E ubuntu-repo-cloud-openclaw passed: https://github.com/NVIDIA/NemoClaw/actions/runs/27297021291
GitHub mergeability: mergeable_state=clean.

Local broad-hook note:

Full npx prek run --all-files remains blocked locally by the unrelated test/release-latest-tag.test.ts fixture commit signing failure (/home/cvillela/.ssh/git-signing-key.pub missing private key). This PR does not touch that release test file.
shellcheck and shfmt are not installed in this local environment; the E2E script was syntax-checked with bash -n and covered by direct CLI probes. CI ShellCheck passed remotely.
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 entry option resolution across various CLI and environment configurations.
- Extended negative-path testing for entry option validation scenarios.
Refactor
- Consolidated onboarding entry point argument resolution into dedicated, testable logic.

copy-pr-bot · 2026-06-10T17:56:02Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

coderabbitai · 2026-06-10T17:56:05Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2e0210b5-1cdf-48f8-bfe0-a75de177a2bb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR extracts onboarding entry option resolution (CLI flag parsing, environment variable handling, validation, and early error gating) from inline code in onboard.ts into a dedicated, testable entry-options.ts module with dependency injection, comprehensive unit tests, and E2E validation.

Changes

Entry Options Module Refactoring

Layer / File(s)	Summary
Entry Options Module: Types, Implementation, and Unit Tests `src/lib/onboard/entry-options.ts`, `src/lib/onboard/entry-options.test.ts`	Defines `OnboardEntryOptionsInput`, `OnboardEntryOptionsDeps`, and `ResolvedOnboardEntryOptions` interfaces. Implements `resolveOnboardEntryOptions` to normalize `resume`/`fresh` flags, derive `requestedFromDockerfile` and `requestedSandboxName` from CLI args and environment with TTY-aware defaults, validate names (including guidance on errors), reject reserved sandbox names, enforce sandbox name presence for non-interactive `--from` usage, and gate on mutually exclusive flags. Comprehensive unit tests cover all validation paths, environment defaults, flag combinations, reserved names, and error reporting via dependency injection.
Integration into Onboarding Flow `src/lib/onboard.ts`	Imports the new entry-options module and replaces ~69 lines of inlined option parsing/validation with a single `resolveOnboardEntryOptions` call, wiring in TTY detection and callbacks. Returns normalized flags and request state to drive downstream onboarding control flow. Comment updated to clarify whitespace-only env values do not satisfy sandbox-name requirements.
E2E Validation Tests for Entry Options `test/e2e/test-onboard-negative-paths.sh`	Adds new Phase 3 (Entry option validation) that executes non-interactive `onboard --from` scenarios: missing sandbox name (asserts exit 1, missing-name guard message, no stack trace) and invalid `NEMOCLAW_SANDBOX_NAME` (asserts name validation is invoked rather than missing-name guard). Subsequent phases renumbered (Gateway port conflict becomes Phase 5, live non-interactive onboard becomes Phase 6, cleanup becomes Phase 7).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

NVIDIA/NemoClaw#5147: Adds E2E test for nemoclaw onboard --resume resume-from-session behavior, directly validating the resume flag handling refactored by this resolver.

Suggested reviewers

prekshivyas

Poem

🐰 A rabbit hops through tangled flags with glee,
Extracting logic clean, for all to see.
No whitespace ghosts will hide the truth,
The resolver speaks—validation proof! 🌿

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% 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 pull request title accurately describes the main change: extracting entry option resolution logic into a dedicated helper function in the onboarding module.
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 unit tests (beta)

Create PR with unit tests
Commit unit tests in branch codex/onboard-entry-options-flow

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

github-actions · 2026-06-10T17:58:29Z

E2E Advisor Recommendation

Required E2E: onboard-negative-paths-e2e
Optional E2E: onboard-resume-e2e, cloud-onboard-e2e

Dispatch hint: onboard-negative-paths-e2e

Auto-dispatched E2E: onboard-negative-paths-e2e via nightly-e2e.yaml at e72cebb6d010a91b1918f2a71b305ad35835a337 — nightly run

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/codex/onboard-messaging-preflight-flow
Head: HEAD
Confidence: high

Required E2E

onboard-negative-paths-e2e (medium-high; ubuntu-latest live onboarding with NVIDIA_API_KEY, Docker/OpenShell, timeout 75 minutes): Directly exercises the modified non-interactive onboarding entry validation, including the newly added --from Dockerfile missing-name guard and env-provided sandbox-name path, then continues through live non-interactive onboard to catch integration regressions in the refactor.

Optional E2E

onboard-resume-e2e (medium; ubuntu-latest live onboarding/resume flow, timeout 60 minutes): Entry-option resolution also feeds resume handling and the PR preserves special --resume behavior for missing sandbox names; this is useful adjacent confidence but less targeted than onboard-negative-paths because the main changed runtime behavior is fail-fast entry validation.
cloud-onboard-e2e (medium; ubuntu-latest live cloud onboard with NVIDIA_API_KEY, timeout inherited from reusable script): Provides a clean happy-path cloud onboard smoke after moving early option parsing into a new module; optional because onboard-negative-paths already includes a live non-interactive onboard phase.

New E2E recommendations

None.

Dispatch hint

Workflow: .github/workflows/nightly-e2e.yaml
jobs input: onboard-negative-paths-e2e

github-actions · 2026-06-10T17:58:30Z

Vitest E2E Scenario Recommendation

Required Vitest E2E scenarios: onboard-negative-paths-vitest, ubuntu-repo-cloud-openclaw
Optional Vitest E2E scenarios: None

Dispatch required Vitest E2E scenarios:

gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-negative-paths-vitest
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/codex/onboard-messaging-preflight-flow
Head: HEAD
Confidence: high

Required Vitest E2E scenarios

onboard-negative-paths-vitest: The PR changes onboard entry-option validation and the onboard negative-path contract. Run the discrete Vitest job for the live non-interactive onboard negative-path CLI boundary.
- Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field jobs=onboard-negative-paths-vitest
ubuntu-repo-cloud-openclaw: The refactor is in the main onboard entry path used before standard cloud OpenClaw onboarding; this live-supported typed scenario validates the normal Ubuntu repo Docker onboarding flow still succeeds.
- Dispatch: gh workflow run e2e-vitest-scenarios.yaml --ref <pr-head-ref> --field scenarios=ubuntu-repo-cloud-openclaw

Optional Vitest E2E scenarios

None.

Relevant changed files

src/lib/onboard.ts
src/lib/onboard/entry-options.ts
test/e2e/test-onboard-negative-paths.sh

github-actions · 2026-06-10T17:59:54Z

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** — onboard --non-interactive --from Dockerfile --name explicit with NEMOCLAW_SANDBOX_NAME=env-name uses the explicit sandbox name. The helper unit tests and E2E negative-path additions cover the key extracted logic. Because this logic gates real onboarding and Dockerfile-based sandbox creation in noninteractive and no-TTY modes, a few behavior-specific runtime checks would further reduce regression risk, but no blocker-worthy test gap was found.
**Runtime validation** — onboard --non-interactive --from Dockerfile with a valid NEMOCLAW_SANDBOX_NAME bypasses the missing-name guard and fails or succeeds only at the next controlled preflight/build-context boundary. The helper unit tests and E2E negative-path additions cover the key extracted logic. Because this logic gates real onboarding and Dockerfile-based sandbox creation in noninteractive and no-TTY modes, a few behavior-specific runtime checks would further reduce regression risk, but no blocker-worthy test gap was found.
**Runtime validation** — onboard with stdin/stdout TTY available, no --name, and NEMOCLAW_SANDBOX_NAME set does not treat the env value as the already-resolved entry option before prompt handling. The helper unit tests and E2E negative-path additions cover the key extracted logic. Because this logic gates real onboarding and Dockerfile-based sandbox creation in noninteractive and no-TTY modes, a few behavior-specific runtime checks would further reduce regression risk, but no blocker-worthy test gap was found.
**Runtime validation** — onboard --resume --from Dockerfile with a session lacking recorded sandboxName exits through the resume-specific missing-name guard before preflight side effects. The helper unit tests and E2E negative-path additions cover the key extracted logic. Because this logic gates real onboarding and Dockerfile-based sandbox creation in noninteractive and no-TTY modes, a few behavior-specific runtime checks would further reduce regression risk, but no blocker-worthy test gap was found.
**Runtime validation** — direct CLI onboard --non-interactive --name status exits through reserved-name rejection without printing validation guidance. The helper unit tests and E2E negative-path additions cover the key extracted logic. Because this logic gates real onboarding and Dockerfile-based sandbox creation in noninteractive and no-TTY modes, a few behavior-specific runtime checks would further reduce regression risk, but no blocker-worthy test gap was found.
**Acceptance clause:** Refs Umbrella: refactor onboarding into a serializable FSM #3802 — add test evidence or identify existing coverage. The deterministic linkedIssues list is empty and no trusted issue body or comments for Umbrella: refactor onboarding into a serializable FSM #3802 were provided. The diff does extract entry option resolution and adds tests for the changed guard behavior, but no literal Umbrella: refactor onboarding into a serializable FSM #3802 acceptance clauses were available to map.

Workflow run details

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

github-actions · 2026-06-10T18:31:14Z

Selective E2E Results — ✅ All requested jobs passed

Run: 27297021441
Target ref: codex/onboard-entry-options-flow
Workflow ref: main
Requested jobs: onboard-negative-paths-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
onboard-negative-paths-e2e	✅ success

# Conflicts: # src/lib/onboard.ts

…into codex/pr-5159-update

github-actions · 2026-06-11T19:17:46Z

Selective E2E Results — ❌ Some jobs failed

Run: 27371459799
Target ref: edc16f71e4f3db21e4f1e2a7f21800f22c3dfbe0
Workflow ref: main
Requested jobs: onboard-negative-paths-e2e
Summary: 0 passed, 1 failed, 0 cancelled, 0 skipped

Job	Result
onboard-negative-paths-e2e	❌ failure

Failed jobs: onboard-negative-paths-e2e. Check run artifacts for logs.

github-actions · 2026-06-11T19:21:23Z

Selective E2E Results — ❌ Some jobs failed

Run: 27371582699
Target ref: edc16f71e8a0787956a64aa1ae80d45ae9bfa8a0
Workflow ref: main
Requested jobs: onboard-negative-paths-e2e
Summary: 0 passed, 1 failed, 0 cancelled, 0 skipped

Job	Result
onboard-negative-paths-e2e	❌ failure

Failed jobs: onboard-negative-paths-e2e. Check run artifacts for logs.

github-actions · 2026-06-11T19:25:50Z

Selective E2E Results — ❌ Some jobs failed

Run: 27371582699
Target ref: edc16f71e8a0787956a64aa1ae80d45ae9bfa8a0
Workflow ref: main
Requested jobs: onboard-negative-paths-e2e
Summary: 0 passed, 1 failed, 0 cancelled, 0 skipped

Job	Result
onboard-negative-paths-e2e	❌ failure

Failed jobs: onboard-negative-paths-e2e. Check run artifacts for logs.

github-actions · 2026-06-11T19:38:46Z

Selective E2E Results — ✅ All requested jobs passed

Run: 27371582699
Target ref: edc16f71e8a0787956a64aa1ae80d45ae9bfa8a0
Workflow ref: main
Requested jobs: onboard-negative-paths-e2e
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
onboard-negative-paths-e2e	✅ success

cv · 2026-06-11T19:40:47Z

@coderabbitai review

coderabbitai · 2026-06-11T19:43:51Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

github-actions · 2026-06-11T19:53:09Z

Selective E2E Results — ✅ All requested jobs passed

Run: 27372961345
Target ref: edc16f71e8a0787956a64aa1ae80d45ae9bfa8a0
Workflow ref: codex/onboard-messaging-preflight-flow
Requested jobs: onboard-negative-paths-e2e
Summary: 1 passed, 0 failed, 0 skipped

Job	Result
onboard-negative-paths-e2e	✅ success

…into codex/pr-5159-update # Conflicts: # src/lib/onboard.ts

…t-flow' into codex/pr-5161-update

github-actions · 2026-06-11T21:44:49Z

Selective E2E Results — ❌ Some jobs failed

Run: 27379313333
Target ref: e72cebb6d010a91b1918f2a71b305ad35835a337
Workflow ref: codex/onboard-messaging-preflight-flow
Requested jobs: onboard-negative-paths-e2e
Summary: 0 passed, 1 failed, 0 cancelled, 0 skipped

Job	Result
onboard-negative-paths-e2e	❌ failure

Failed jobs: onboard-negative-paths-e2e. Check run artifacts for logs.

github-actions · 2026-06-11T21:55:10Z

Selective E2E Results — ✅ All requested jobs passed

Run: 27379313333
Target ref: e72cebb6d010a91b1918f2a71b305ad35835a337
Workflow ref: codex/onboard-messaging-preflight-flow
Requested jobs: onboard-negative-paths-e2e
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
onboard-negative-paths-e2e	✅ success

cv added 2 commits June 10, 2026 10:22

refactor(onboard): extract sandbox messaging preflight

0c5db46

refactor(onboard): extract entry option resolution

0d87a4d

cv self-assigned this Jun 10, 2026

cv mentioned this pull request Jun 10, 2026

Umbrella: refactor onboarding into a serializable FSM #3802

Closed

cv added 3 commits June 10, 2026 11:07

test(onboard): cover from entry option guards

13031f9

fix(onboard): keep entry reserved-name exits clean

2c5eb66

chore(onboard): refresh entry option resume comment

726a539

cv added the v0.0.64 Release target label Jun 10, 2026

cv added 3 commits June 11, 2026 00:17

Merge branch 'codex/tmp-create-plan-merge' into HEAD

5d0b22e

# Conflicts: # src/lib/onboard.ts

Merge branch 'codex/tmp-create-plan-merge-v2' into HEAD

c4548ef

Merge branch 'codex/tmp-messaging-preflight-merge-v2' into HEAD

9557fbb

cv added refactor PR restructures code without intended behavior change area: onboarding Onboarding FSM, provider setup, sandbox launch, or first-run flow labels Jun 11, 2026

cv added 4 commits June 11, 2026 10:54

Merge remote-tracking branch 'origin/codex/onboard-create-plan-flow' …

e36fba1

…into codex/pr-5159-update

fix(onboard): preserve messaging gateway conflicts

24f6819

test(onboard): assert messaging preflight return channels

225c01e

merge: refresh entry option flow stack base

edc16f7

cv marked this pull request as ready for review June 11, 2026 19:40

cv added 2 commits June 11, 2026 14:03

Merge remote-tracking branch 'origin/codex/onboard-create-plan-flow' …

80077d8

…into codex/pr-5159-update # Conflicts: # src/lib/onboard.ts

Merge remote-tracking branch 'origin/codex/onboard-messaging-prefligh…

e72cebb

…t-flow' into codex/pr-5161-update

Base automatically changed from codex/onboard-messaging-preflight-flow to codex/onboard-create-plan-flow June 11, 2026 23:59

cv merged commit 2de593c into codex/onboard-create-plan-flow Jun 12, 2026
241 of 247 checks passed

cv deleted the codex/onboard-entry-options-flow branch June 12, 2026 00:01

This was referenced Jun 12, 2026

refactor(onboard): extract sandbox create plan #5158

Merged

refactor(onboard): extract session bootstrap flow #5164

Merged

fix(onboard): auto-detect resume from an in_progress session #5487

Open

Conversation

cv commented Jun 10, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Type of Change

Verification

Summary by CodeRabbit

Uh oh!

copy-pr-bot Bot commented Jun 10, 2026

Uh oh!

coderabbitai Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

❌ Failed checks (1 warning)

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Dispatch hint

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vitest E2E Scenario Recommendation

Vitest E2E Scenario Advisor

Required Vitest E2E scenarios

Optional Vitest E2E scenarios

Relevant changed files

Uh oh!

github-actions Bot commented Jun 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor

Uh oh!

github-actions Bot commented Jun 10, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ❌ Some jobs failed

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ❌ Some jobs failed

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ❌ Some jobs failed

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

cv commented Jun 11, 2026

Uh oh!

coderabbitai Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ❌ Some jobs failed

Uh oh!

github-actions Bot commented Jun 11, 2026

Selective E2E Results — ✅ All requested jobs passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

cv commented Jun 10, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

github-actions Bot commented Jun 10, 2026 •

edited

Loading

coderabbitai Bot commented Jun 11, 2026 •

edited

Loading