fix(cli): fail fast on unsupported onboarding hosts

[ChunkyMonkey11]

Summary

• Add explicit host OS support classification for onboarding preflight.
• Fail fast when host support status is error.
• Keep onboarding non-blocking for warning hosts while surfacing clear guidance.

Root Cause

Onboarding did not gate early on unsupported host OS/platform combinations, which could lead users into later-stage failures after expensive setup steps.

Changes

• Added src/lib/host-support.ts with Linux/macOS/platform classification helpers.
• Added CJS shim bin/lib/host-support.js.
• Wired checkHostSupport() into bin/lib/onboard.js preflight.
• Added unit coverage in src/lib/host-support.test.ts.
• Added onboarding regression test in test/onboard.test.js to verify fail-fast behavior before Docker checks.
• Simplified the pre-20 EOL condition in src/lib/host-support.ts from a redundant clause to major < 20.

Validation

• npm test -- src/lib/host-support.test.ts test/onboard.test.js
• Pre-commit and pre-push hooks passed during commit/push in this environment.

---

Signed-off-by: Revant Patel revant.h.patel@gmail.com

Summary by CodeRabbit

• New Features

  • Onboarding now checks host OS support up front (Linux/macOS/others), prints clear success/warning/error messages, and exits early if unsupported—preventing later steps (Docker, GPU/memory checks, etc.) from running.
  • Linux distro lifecycle (supported / near‑EOL / EOL) and macOS version detection provide clearer, actionable warnings.

• Tests

  • Added tests covering host support detection and onboarding exit behavior across platforms and error paths.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a host support detection library (Linux/macOS), a CommonJS shim, unit and integration tests, and integrates the host support check into onboarding preflight to log results and exit early on unsupported hosts.

Changes

Cohort / File(s)	Summary
Host Support Source src/lib/host-support.ts	New TypeScript module exporting types and checkHostSupport() with platform branching, /etc/os-release parsing, macOS detection via sw_vers, classification helpers, and injectable I/O for testing.
Host Support Shim bin/lib/host-support.js	New CommonJS shim that re-exports the compiled module at ../../dist/lib/host-support via module.exports = require(...).
Onboard Integration bin/lib/onboard.js	Calls checkHostSupport() at start of preflight(); prints ok/warning to stdout, prints errors to stderr and calls process.exit(1) on unsupported hosts; defers subsequent checks until host support is evaluated.
Unit Tests src/lib/host-support.test.ts	Adds Vitest tests for parseOsRelease, classifyLinuxHost, macOS handling, and checkHostSupport() using injected read/get implementations and error paths.
Integration Test test/onboard.test.js	Adds a test that spawns bin/lib/onboard.js, stubs bin/lib/host-support.js in the child to force an unsupported-host error, asserts the child exits with code 1 before any Docker invocation.

Sequence Diagram(s)

sequenceDiagram
  participant User as User
  participant Onboard as Onboard (preflight)
  participant HostSupport as HostSupport
  participant OS as OS/FileSystem
  participant Docker as DockerChecks

  User->>Onboard: run onboard (preflight)
  Onboard->>HostSupport: checkHostSupport(opts)
  HostSupport->>OS: read /etc/os-release or run sw_vers
  OS-->>HostSupport: return version info or error
  HostSupport-->>Onboard: HostSupportResult (ok|warning|error)
  alt status == "error"
    Onboard->>Onboard: log to stderr
    Onboard-->>User: exit(1)
  else status == "ok" or "warning"
    Onboard->>Onboard: log to stdout
    Onboard->>Docker: run docker & other checks
    Docker-->>Onboard: continue startup
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I sniff the OS with twitchy nose,
Lines of release where the breezy wind blows.
A shim, a test, a preflight stop —
I hop, I check, then tap the top.
Hooray — the checks decide to go or not!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

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

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(cli): fail fast on unsupported onboarding hosts' directly summarizes the main change—adding host OS support classification to fail early during onboarding when hosts are unsupported, which is the primary objective of this PR.

_{✏️ 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.}

[ChunkyMonkey11]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

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.

[ChunkyMonkey11]

@cv when you have a moment, could you please approve workflows for PR #1461 so checks can run? Thanks!

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/host-support.ts (1)

143-151: Consider simplifying the EOL condition.

The condition major < 20 || (major === 18 && minor <= 4) is logically redundant — major < 20 already covers all 18.x versions. The second clause (major === 18 && minor <= 4) is a subset of major < 20 and never evaluated independently.

If the intent is to mark all pre-20.x as EOL, major < 20 alone suffices. If only specific 18.x versions should be EOL, the condition needs restructuring.

Simplified condition (if all pre-20.x is intended as EOL)

-  if (major < 20 || (major === 18 && minor <= 4)) {
+  if (major < 20) {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/lib/host-support.ts` around lines 143 - 151, The EOL check uses a
redundant clause: simplify the if-condition to remove the never-reached subset
and make intent explicit; replace the current `if (major < 20 || (major === 18
&& minor <= 4))` logic with either a single `major < 20` when all pre-20.x
releases are EOL or, if only specific 18.x minors should be EOL, change it to a
focused check like `major === 18 && minor <= 4`; update the branch that returns
the object containing os, version (normalized), status, code, and message
accordingly so the condition accurately reflects the intended EOL policy for
variables major, minor, and normalized.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@src/lib/host-support.ts`:
- Around line 143-151: The EOL check uses a redundant clause: simplify the
if-condition to remove the never-reached subset and make intent explicit;
replace the current `if (major < 20 || (major === 18 && minor <= 4))` logic with
either a single `major < 20` when all pre-20.x releases are EOL or, if only
specific 18.x minors should be EOL, change it to a focused check like `major ===
18 && minor <= 4`; update the branch that returns the object containing os,
version (normalized), status, code, and message accordingly so the condition
accurately reflects the intended EOL policy for variables major, minor, and
normalized.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 98c1c43d-3aa0-418e-bfd0-40775b730070

📥 Commits

Reviewing files that changed from the base of the PR and between b1bb01c and 9c10484.

📒 Files selected for processing (5)

• bin/lib/host-support.js
• bin/lib/onboard.js
• src/lib/host-support.test.ts
• src/lib/host-support.ts
• test/onboard.test.js

[ChunkyMonkey11]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

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.

[wscurran]

✨ Thanks for submitting this pull request, which proposes a way to fail fast during onboarding when the host OS is unsupported, improving the setup experience.

[ChunkyMonkey11]

Hi @wscurran, quick update: I merged the latest upstream/main into this branch and resolved the onboarding preflight conflict. The branch is now up to date and ready for commit/review on your side.