fix(onboard): explain Docker Desktop WSL integration gaps (Fixes #4301)

[deepujain]

Summary

Fixes #4301.

On Windows/WSL, a fresh Ubuntu handoff can leave Docker Desktop WSL integration disabled for that distro. The installer/onboard preflight then printed generic Linux Docker advice, which sent users toward Docker Engine instead of the Docker Desktop toggle that actually fixes the failure.

Changes

• Add a WSL-specific remediation when Docker is missing inside WSL.
• Add a WSL-specific remediation when Docker exists but the WSL distro cannot reach the daemon.
• Cover both paths in src/lib/onboard/preflight.test.ts.

Testing

• npm run build:cli
• npm run typecheck:cli
• npx vitest run src/lib/onboard/preflight.test.ts -t 'planHostRemediation'
• npx vitest run src/lib/onboard/preflight.test.ts
• npx vitest run test/install-preflight.test.ts -t 'skips onboarding when shared host preflight detects Docker is missing'

Signed-off-by: Deepak Jain deepujain@gmail.com

Summary by CodeRabbit

• Improvements

  • Enhanced Docker troubleshooting for WSL: adds clear guidance to enable Docker Desktop WSL integration when Docker is not present or cannot be reached from the distro, and surfaces WSL-focused remediation steps (including suggested commands and UI steps).

• Tests

  • Added test coverage covering Docker/WSL integration scenarios for missing or unreachable Docker.

[copy-pr-bot]

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]

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: 5b9f43e2-cb05-4d62-a4b4-0569d2b5e737

📥 Commits

Reviewing files that changed from the base of the PR and between 1d5c2d0 and bef2c9b.

📒 Files selected for processing (2)

• src/lib/onboard/preflight.test.ts
• src/lib/onboard/preflight.ts

💤 Files with no reviewable changes (2)

• src/lib/onboard/preflight.test.ts
• src/lib/onboard/preflight.ts

---

📝 Walkthrough

Walkthrough

planHostRemediation() now detects when Docker is missing or unreachable on WSL hosts and returns early with a blocking enable_docker_desktop_wsl_integration remediation action. Two new tests with a shared baseAssessment helper validate the missing and unreachable WSL scenarios and their command sequences.

Changes

WSL Docker Desktop Integration

Layer / File(s)	Summary
WSL Docker Desktop remediation logic src/lib/onboard/preflight.ts	When running on WSL with Docker not installed, planHostRemediation returns early with a blocking enable_docker_desktop_wsl_integration action instructing the user to enable Docker Desktop WSL integration. When Docker is installed but unreachable, a similar WSL-first branch emits the same remediation action and skips the subsequent docker-group / start_docker remediation paths.
WSL Docker Desktop remediation test validation src/lib/onboard/preflight.test.ts	Adds a baseAssessment helper to standardize test assessments and two Vitest cases that assert enable_docker_desktop_wsl_integration is emitted (blocking) for Docker-missing and Docker-unreachable WSL scenarios; tests check action id/title/reason and the presence of command strings (wsl --shutdown, docker info) and the absence of sudo systemctl start docker in the unreachable case.

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly Related PRs

• NVIDIA/NemoClaw#4298: Modifies planHostRemediation WSL Docker Desktop remediation behavior (related file and feature).
• NVIDIA/NemoClaw#4346: Adds WSL-specific Docker Desktop integration remediation guidance in the onboarding flow (same area of code).

Suggested Labels

bug

Suggested Reviewers

• ericksoa
• cjagwani

Poem

🐰 In WSL meadows I softly tread,
Where Docker sleeps and things must mend,
A toggle, shutdown, then a check,
Tests hop in to guard the deck,
Now onboarding finds its friend.

🚥 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 describes the main change: adding WSL-specific Docker Desktop integration remediation steps to address preflight onboarding failures.
Linked Issues check	✅ Passed	The PR implements the desired outcome (b) from issue #4301: detecting Docker Desktop WSL integration gaps and providing actionable guidance via new remediation actions in preflight checks.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing issue #4301: WSL-specific Docker remediation logic and corresponding test coverage with no unrelated modifications.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@src/lib/onboard/preflight.ts`:
- Around line 701-715: After pushing the WSL-specific blocking remediation
object (when assessment.isWsl) — the action with id
"enable_docker_desktop_wsl_integration" — add an early return so execution stops
and no further actions (e.g., those added under likelyGroupIssue) are appended;
locate the conditional that checks assessment.isWsl in the onboard preflight
flow and return (or break out) immediately after pushing that action to keep the
WSL daemon-unreachable path isolated.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 48724679-0135-4474-a9f1-ba699998ff52

📥 Commits

Reviewing files that changed from the base of the PR and between e139dbc and 1d5c2d0.

📒 Files selected for processing (2)

• src/lib/onboard/preflight.test.ts
• src/lib/onboard/preflight.ts

[wscurran]

✨ Thanks for submitting this detailed PR that explains Docker Desktop WSL integration gaps and proposes a fix for the issue reported in #4301. This PR adds WSL-specific remediations for Docker integration and updates the onboard preflight checks to handle these cases.

---

Related open issues:

• #4301 [WSL2 ARM][Install] Docker Desktop WSL integration not auto-enabled for fresh Ubuntu-24.04 after bootstrap-windows.ps1; nemoclaw onboard fails "Docker is not reachable"

[deepujain]

Rebased on current main and kept the WSL Docker Desktop remediation isolated with an early return. The preflight suite passes.

[prekshivyas]

The new WSL branch in the unreachable case already includes return actions; (preflight.ts ~line 719 in the latest commit), so CodeRabbit's "execution continues" concern looks already addressed. Could you either mark that thread resolved, or reply on it if it's pointing somewhere I'm not seeing? Will approve once it's cleared.

[prekshivyas]

LGTM — WSL-specific remediation branches with explicit return actions; early returns, tests cover both new WSL paths. CodeRabbit thread resolved (the early-return suggestion is already in the code at both call sites).

Substantive CI verified on the actual code commit bef2c9b: CodeQL (js/ts + python), cli-parity, macos-e2e all passed. The checks cancellations on subsequent merge SHAs are concurrency replays from my "Update branch" pushes — no code change between 99d64b1 and 8a05145 beyond doc files from main.