WSL2 support: bring-up script + comprehensive documentation (#9, #4)

[Liohtml]

Description

WSL2 support: one-command bring-up script and comprehensive documentation.

Changes

• feature: one-command WSL2 bring-up helper script (attach + bridge + serial_bridge) #9 — WSL2 bring-up script (scripts/wsl-cyd-up.sh). One-command setup for running the bridge under WSL2:

  • Checks for usbipd, attaches CYD via hardware-id (1a86:7523).
  • Verifies /dev/ttyUSB0 permissions (dialout group).
  • Starts vibe-bridge if not already running.
  • Execs serial_bridge --port /dev/ttyUSB0.
  • Handles missing device, permission errors, already-running bridge.
  • Added just wsl-up recipe to Justfile for easy invocation.

• WSL2 support (umbrella): usbipd-win passthrough — bridge in WSL, COM ports invisible #4 — Comprehensive WSL2 documentation in README:

  • Prerequisites on Windows (usbipd-win install, bind the CYD).
  • Quick start (just wsl-up).
  • Auto-reconnect behavior on replug (usbipd re-attach + serial_bridge auto-reconnect).
  • Troubleshooting (permissions, replug, bridge startup).

The script treats existing serial_bridge auto-reconnect behavior as the foundation and documents it. Users can optionally upgrade to systemd services or supervised bring-up for production deployments.

Type of Change

• New feature (shell script + Justfile recipe)
• Documentation update (WSL2 section + troubleshooting)

Component

• Bridge (HTTP server, session collection)
• Serial Bridge (USB transport binary)
• CI/build system (Justfile)

Testing

• Script tested on Windows 11 + WSL2 with CH340 CYD.
• Documentation reviewed against verified working recipe.

Closes #4
Closes #9

🤖 Generated with Claude Code

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added a one-command WSL2 workflow to bring up the CYD USB-serial connection, verify access, and start the bridge services.
  • Introduced a convenient just wsl-up command for Windows + WSL users.

• Documentation

  • Expanded the setup guide with WSL2 installation steps, replug behavior, and troubleshooting tips for common USB and permission issues.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4202026f-3a99-4f6c-857a-9b0f79d7ace3

📥 Commits

Reviewing files that changed from the base of the PR and between 33d0beb and 26ae3f2.

📒 Files selected for processing (3)

• Justfile
• README.md
• scripts/wsl-cyd-up.sh

---

📝 Walkthrough

Walkthrough

Adds a WSL2 bring-up helper script (scripts/wsl-cyd-up.sh) that detects, binds, and attaches a USB-serial device into WSL, validates permissions, starts a bridge server, and launches serial_bridge. Adds a just wsl-up recipe and README documentation covering setup, replug behavior, and troubleshooting.

Changes

WSL2 Bring-up Script and Documentation

Layer / File(s)	Summary
Device detection, bind, and attach scripts/wsl-cyd-up.sh	Script initializes device/tty/port variables, checks for usbipd.exe, exits quietly if the target device isn't connected, binds it if unshared, and attaches it to WSL while polling for /dev/ttyUSB0.
Permission check, bridge startup, serial_bridge launch scripts/wsl-cyd-up.sh	Validates read/write access to the tty device (with dialout guidance and chmod 666 fallback), starts vibe-bridge on port 5151 if not already running, then execs serial_bridge against the tty device.
just recipe and README docs Justfile, README.md	Adds a wsl-up recipe invoking the script, and a README "WSL2 Setup" section documenting usbipd prerequisites, quick start via just wsl-up, replug/auto-attach behavior, and troubleshooting steps.

Estimated code review effort: 2 (Simple) | ~15 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Just as Justfile (wsl-up)
  participant Script as wsl-cyd-up.sh
  participant Windows as usbipd.exe
  participant Bridge as vibe-bridge/serial_bridge

  User->>Just: just wsl-up
  Just->>Script: bash scripts/wsl-cyd-up.sh
  Script->>Windows: check device present, bind/attach --wsl
  Windows-->>Script: /dev/ttyUSB0 available
  Script->>Script: verify read/write permissions
  Script->>Bridge: start vibe-bridge on :5151 (if not running)
  Script->>Bridge: exec serial_bridge --port /dev/ttyUSB0

Loading

Possibly related issues

• WSL2: replug must auto-recover — CYD should resume exactly as before without manual steps #10: This PR's bring-up script provides re-run/manual-attach recovery guidance for replug scenarios, addressing part of the auto-recover objective though not the full persistent auto-attach behavior.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/wsl2-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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