test(preflight): skip real-bind tests in restricted environments (#544)

[ColinM-sys]

Summary

Harden the four real-net probe tests in `src/lib/preflight.test.ts` against environments that deny localhost `bind()` (seccomp, gVisor, some container runtimes).

Fixes #544.

Background

The production code (`probePortAvailability`) already handles `EPERM`/`EACCES` correctly — it returns `{ ok: true, warning: ... }` rather than a false port conflict (see `src/lib/preflight.ts:469-475`). The gap was in the tests: the real-bind cases assumed localhost bind permission was always available, which is flaky in restricted CI / sandbox environments.

Change

Added a memoised `canBindLocalhost()` helper that probes port-0 once. The four real-bind tests now:

1. If bind is permitted → exercise the real probe as before
2. If bind is denied → assert the probe returns `ok: true` with an `inconclusive` / `skipped` warning (the documented graceful-degradation behavior) and skip the conflict-manufacture step

Mocked-probe tests (via `probeImpl` injection) are unchanged — they already cover the happy / `EADDRINUSE` / `EPERM` paths independent of environment.

Test plan

• `npx vitest run src/lib/preflight.test.ts` — 36/36 pass locally
• Production code unchanged (no behavior risk)
• CI will validate the graceful-skip branch runs green on restricted runners

🤖 Generated with Claude Code

Summary by CodeRabbit

• Tests
  • Improved test reliability in restricted CI/sandbox environments by adding environment detection for localhost binding constraints.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d3323be-b3fb-437e-a967-4069f9933d1c

📥 Commits

Reviewing files that changed from the base of the PR and between 002ae01 and 92cc755.

📒 Files selected for processing (1)

• src/lib/preflight.test.ts

---

📝 Walkthrough

Walkthrough

Added a cached canBindLocalhost() helper function to test code that checks if the environment permits localhost socket binds. Updated probePortAvailability and checkPortAvailable tests to conditionally skip or assert inconclusive results when the helper returns false, preventing false port-conflict failures in restricted CI/sandbox environments where bind operations are denied.

Changes

Cohort / File(s)	Summary
Test Preflight Robustness src/lib/preflight.test.ts	Added canBindLocalhost() cached helper to detect environment socket-bind constraints. Updated real net-probe tests to gate execution: when bind is unavailable, tests assert inconclusive/skipped warnings instead of false failures, improving resilience in sandboxed CI environments.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 Hop-hop, the tests now understand,
Not all sandboxes have an open land.
When bind is blocked, we skip with grace,
No false alarms in restricted space! ✨

🚥 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 'test(preflight): skip real-bind tests in restricted environments' accurately and specifically describes the main change—adding test skips for environments where localhost binds are denied.
Linked Issues check	✅ Passed	The PR directly addresses issue #544 by adding a canBindLocalhost() helper that gates real-bind tests, preventing false port-conflict failures in restricted environments where bind permissions are denied.
Out of Scope Changes check	✅ Passed	All changes are scoped to test-local helpers and test control flow in preflight.test.ts; no production code changes or unrelated modifications are present.

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