Fix Windows CLI startup when tunnel imports fail

[lmmontoya-ai]

What changed

• Stop re-exporting Tunnel eagerly from prime_tunnel.__init__.
• Lazy-load Tunnel only when prime tunnel start executes, so unrelated commands do not import prime_tunnel.tunnel at CLI startup.
• Guard the fcntl import in prime_tunnel.tunnel so the module can be imported on non-POSIX platforms.
• Add regression tests covering both the missing-fcntl path and the requirement that prime --help not import prime_tunnel.tunnel.
• This patch is scoped to import-time compatibility and CLI startup behavior, not full tunnel support on Windows.

Why

• On Windows, any invocation of prime could fail with ModuleNotFoundError: No module named 'fcntl' before command dispatch.
• The CLI imported the tunnel command eagerly in prime_cli.main, which imported prime_tunnel, which imported Unix-only fcntl at module import time.
• That prevented Windows users from using unrelated commands such as pods, availability, or even --help.

Impact

• Windows users can now use the CLI for non-tunnel commands.
• Tunnel code is only imported when prime tunnel start is invoked, instead of breaking the entire CLI at startup.
• This does not add or guarantee native Windows support for tunnel functionality itself. A fuller Windows-compatible tunnel design and implementation would still be needed.

Validation

• uv run pytest packages/prime/tests/test_windows_cli.py packages/prime-tunnel/tests/test_tunnel.py -q

---

Note

Low Risk
Low risk import-time compatibility change; main risk is accidentally breaking Tunnel exports or tunnel startup due to the new lazy-import path.

Overview
Fixes Windows CLI startup by removing eager tunnel imports: prime_tunnel.Tunnel is now lazy-exported via __getattr__, and the prime tunnel start command imports Tunnel only when invoked.

Makes prime_tunnel.tunnel importable on non-POSIX platforms by guarding the fcntl import, and adds regression tests ensuring prime --help works when fcntl is unavailable and that CLI help does not import prime_tunnel.tunnel.

^{Reviewed by Cursor Bugbot for commit 958e7d8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7fa3d62924

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[chatgpt-codex-connector]

Defer all tunnel package imports until command execution

Moving Tunnel into run_tunnel() does not actually stop startup-time tunnel imports, because this module still imports prime_tunnel at import time (TunnelClient and tunnel exceptions at the top), and importing prime_tunnel.core.client executes prime_tunnel/__init__.py, which in turn imports prime_tunnel.tunnel (packages/prime-tunnel/src/prime_tunnel/__init__.py:15). That means prime --help can still fail before dispatch whenever tunnel package import fails, so the Windows startup fix remains incomplete for the failure mode this patch is trying to isolate.

Useful? React with 👍 / 👎.

[lmmontoya-ai]

The initial patch fixed the concrete Windows failure we reproduced (ModuleNotFoundError: No module named 'fcntl'), but it did not fully defer tunnel-module imports at CLI startup.

What the initial patch did:

• guarded the fcntl import in prime_tunnel.tunnel so the package no longer crashed on Windows for that specific import-time failure
• moved Tunnel usage inside prime tunnel start
• added a Windows startup regression test around the missing-fcntl path

What was still incomplete:

• prime_cli.commands.tunnel still imported prime_tunnel.core.client
• importing prime_tunnel.core.client still loaded the parent package
• prime_tunnel.__init__ still eagerly imported prime_tunnel.tunnel
• so CLI startup was still coupled to importing the tunnel module

What I changed after the codex review:

• removed the eager from prime_tunnel.tunnel import Tunnel from prime_tunnel.__init__
• lazy-load Tunnel via prime_tunnel.__getattr__ instead
• added a stronger regression test that fails if prime_tunnel.tunnel is imported during prime --help

So the branch now covers both:

1. the original Windows fcntl failure mode, and
2. the broader startup-import coupling codex pointed out

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 7fa3d62. Configure here.}