muxplex-deck 0.4.1__tar.gz → 0.5.0__tar.gz

{muxplex_deck-0.4.1 → muxplex_deck-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: muxplex-deck
-Version: 0.4.1
+Version: 0.5.0
 Summary: Hardware probe/diagnostic app for the Elgato Stream Deck+ (seed of the muxplex sidecar)
 Author: Amplifier
 Author-email: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
@@ -108,10 +108,14 @@ without a udev rule granting your user access to the device (vendor id
 prints a copy-pasteable remediation block (the same rule shown in
 "Permissions" under the hardware probe section above) instead of silently
 installing a service that won't work. It never writes to `/etc` itself --
-only detects and reports. Run the printed `sudo tee ... && sudo udevadm
+only detects and reports. This remediation is only ever printed when udev
+is actually running (`/run/udev/control` present) -- on WSL without
+systemd, or in a container, it never fires anyway, so `muxplex-deck`
+detects that and prints a different, WSL/container-appropriate fix instead
+(see `docs/WSL.md`). Run the printed `sudo tee ... && sudo udevadm
 control --reload-rules && sudo udevadm trigger` commands, then unplug and
-replug the deck (or re-`usbipd attach` under WSL) and `muxplex-deck service
-restart`.
+replug the deck (or `muxplex-deck wsl attach` under WSL) and `muxplex-deck
+service restart`.
 
 On Linux, `service install` also attempts `loginctl enable-linger
 <you>` (best-effort, non-fatal) so the service keeps running after you log
@@ -159,25 +163,20 @@ uv run deck-probe
 
 #### Windows + WSL
 
-USB devices are not visible inside WSL until attached from the Windows
-side. In an **admin PowerShell**:
-
-```powershell
-usbipd list                        # find the Stream Deck's BUSID (VID 0fd9)
-usbipd bind --busid <BUSID>        # first time only
-usbipd attach --wsl --busid <BUSID>
-```
-
-Then inside WSL, grant HID access via a udev rule (first time only):
+USB devices are invisible to WSL until Windows hands them over. Rather
+than driving `usbipd`/udev rules by hand for this PoC probe, install and
+use the actual product instead -- it handles this for you:
 
 ```sh
-sudo tee /etc/udev/rules.d/70-streamdeck.rules >/dev/null \
-  <<< 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0fd9", MODE="0666"'
-sudo udevadm control --reload-rules
-# then detach/re-attach the device (usbipd detach + attach)
-sudo apt install libhidapi-libusb0   # native HIDAPI, if not present
+uv tool install muxplex-deck
+muxplex-deck wsl attach     # finds the deck, attaches it, tells you what's left
+muxplex-deck doctor         # diagnoses every remaining step, with real values
 ```
 
+Neither needs the details -- but see `docs/WSL.md` if you want them (BUSID/
+device-node churn, the `usbipd` vs `usbipd.exe` trap, durable vs per-attach
+permission options).
+
 **Close the Elgato Stream Deck app on Windows first** -- it holds
 exclusive HID access. The probe prints this same guidance when it finds
 no device.

{muxplex_deck-0.4.1 → muxplex_deck-0.5.0}/README.md

@@ -95,10 +95,14 @@ without a udev rule granting your user access to the device (vendor id
 prints a copy-pasteable remediation block (the same rule shown in
 "Permissions" under the hardware probe section above) instead of silently
 installing a service that won't work. It never writes to `/etc` itself --
-only detects and reports. Run the printed `sudo tee ... && sudo udevadm
+only detects and reports. This remediation is only ever printed when udev
+is actually running (`/run/udev/control` present) -- on WSL without
+systemd, or in a container, it never fires anyway, so `muxplex-deck`
+detects that and prints a different, WSL/container-appropriate fix instead
+(see `docs/WSL.md`). Run the printed `sudo tee ... && sudo udevadm
 control --reload-rules && sudo udevadm trigger` commands, then unplug and
-replug the deck (or re-`usbipd attach` under WSL) and `muxplex-deck service
-restart`.
+replug the deck (or `muxplex-deck wsl attach` under WSL) and `muxplex-deck
+service restart`.
 
 On Linux, `service install` also attempts `loginctl enable-linger
 <you>` (best-effort, non-fatal) so the service keeps running after you log
@@ -146,25 +150,20 @@ uv run deck-probe
 
 #### Windows + WSL
 
-USB devices are not visible inside WSL until attached from the Windows
-side. In an **admin PowerShell**:
-
-```powershell
-usbipd list                        # find the Stream Deck's BUSID (VID 0fd9)
-usbipd bind --busid <BUSID>        # first time only
-usbipd attach --wsl --busid <BUSID>
-```
-
-Then inside WSL, grant HID access via a udev rule (first time only):
+USB devices are invisible to WSL until Windows hands them over. Rather
+than driving `usbipd`/udev rules by hand for this PoC probe, install and
+use the actual product instead -- it handles this for you:
 
 ```sh
-sudo tee /etc/udev/rules.d/70-streamdeck.rules >/dev/null \
-  <<< 'SUBSYSTEM=="hidraw", ATTRS{idVendor}=="0fd9", MODE="0666"'
-sudo udevadm control --reload-rules
-# then detach/re-attach the device (usbipd detach + attach)
-sudo apt install libhidapi-libusb0   # native HIDAPI, if not present
+uv tool install muxplex-deck
+muxplex-deck wsl attach     # finds the deck, attaches it, tells you what's left
+muxplex-deck doctor         # diagnoses every remaining step, with real values
 ```
 
+Neither needs the details -- but see `docs/WSL.md` if you want them (BUSID/
+device-node churn, the `usbipd` vs `usbipd.exe` trap, durable vs per-attach
+permission options).
+
 **Close the Elgato Stream Deck app on Windows first** -- it holds
 exclusive HID access. The probe prints this same guidance when it finds
 no device.

{muxplex_deck-0.4.1 → muxplex_deck-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "muxplex-deck"
-version = "0.4.1"
+version = "0.5.0"
 description = "Hardware probe/diagnostic app for the Elgato Stream Deck+ (seed of the muxplex sidecar)"
 readme = "README.md"
 authors = [

{muxplex_deck-0.4.1 → muxplex_deck-0.5.0}/src/muxplex_deck/cli.py

@@ -421,16 +421,9 @@ def probe_deck_status(manager: Any) -> dict:
 
 _NO_DEVICE_GUIDANCE = (
     "No Stream Deck found. Things to check:\n"
-    "    - All platforms: close the official Elgato Stream Deck app -- it holds\n"
-    "      exclusive HID access, so muxplex-deck cannot open the device while it runs.\n"
-    "    - Linux (incl. WSL): a udev rule must grant access to Elgato devices\n"
-    "      (vendor id 0x0fd9). Run 'muxplex-deck service install' for the exact\n"
-    "      remediation block, or see AGENTS.md.\n"
-    "    - WSL specifically: USB devices are not visible until attached from\n"
-    "      Windows via usbipd -- in an admin PowerShell:\n"
-    "        usbipd list                        (find the Stream Deck's BUSID)\n"
-    "        usbipd bind --busid <BUSID>        (first time only)\n"
-    "        usbipd attach --wsl --busid <BUSID>\n"
+    "    - Close the official Elgato Stream Deck app -- it holds exclusive HID access,\n"
+    "      so muxplex-deck cannot open the device while it is running.\n"
+    "    - Check the USB cable and try a different port.\n"
 )
 
 
@@ -502,11 +495,13 @@ def check_hid_openable() -> tuple[str, str]:
     if service_is_active():
         return "ok", "HID: device in use by the muxplex-deck service (expected)"
 
+    from . import hidhelp
+
     hint = ""
     if sys.platform not in ("darwin", "win32") and not udev_rule_exists():
-        hint = " Run: muxplex-deck service install (prints the udev remediation)."
+        hint = hidhelp.HID_HINT_RUN_SERVICE_INSTALL
     elif sys.platform not in ("darwin", "win32"):
-        hint = " A udev rule exists but the device still could not be opened."
+        hint = hidhelp.HID_HINT_RULE_EXISTS_BUT_STILL_FAILED
     return "warn", f"HID: could not open device ({status['error']}).{hint}"
 
 
@@ -668,6 +663,15 @@ def doctor(config_path: str | None = None) -> int:
         ca_file = config_mod._expand(raw["ca_file"])
     checks.append(check_ca_file(ca_file))
 
+    # Environment guidance (WSL/usbipd/udev-liveness) BEFORE the device
+    # checks -- it explains why the next line is about to warn. Returns []
+    # on a healthy platform (macOS, or native Linux with udev running), so
+    # this adds no output there -- see hidhelp.explain_environment().
+    from . import hidhelp
+
+    for guidance in hidhelp.explain_environment():
+        checks.append((guidance.status, guidance.message))
+
     checks.append(check_deck_detected(config_path))
     checks.append(check_hid_openable())
 
@@ -702,6 +706,9 @@ def _format_device_line(device: dict[str, Any]) -> tuple[str, str]:
     if not device.get("connected"):
         return "warn", "Device: not connected"
     caps = device.get("capabilities") or {}
+    hint = device.get("hint")
+    if not caps and hint:
+        return "warn", "Device: connected (capabilities unavailable)"
     if not caps:
         return "ok", "Device: connected (capabilities unavailable)"
     touchscreen = "yes" if caps.get("has_touchscreen") else "no"
@@ -801,7 +808,15 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
     else:
         print_check("ok", f"Status updated {age:.0f}s ago (pid {data.get('pid', '?')})")
 
-    print_check(*_format_device_line(data.get("device", {})))
+    device_data = data.get("device", {})
+    print_check(*_format_device_line(device_data))
+    hint = device_data.get("hint")
+    if hint and not device_data.get("connected"):
+        # Populated by the sidecar's open-failure branch (see main.py /
+        # hidhelp.explain_open_failure) -- this is what turns a stale
+        # status file into the primary teaching surface instead of a
+        # bare "not connected" with no explanation.
+        print_check("warn", hint)
     print_check(*_format_server_line(data.get("server", {})))
     print_check("ok", _format_state_line(data.get("state", {})))
 
@@ -1016,6 +1031,122 @@ def update(*, force: bool = False) -> None:
     doctor()
 
 
+# ---------------------------------------------------------------------------
+# wsl attach -- find, share-check, and attach the Stream Deck under WSL2.
+#
+# This is the ONLY command whose entire purpose is to mutate host state
+# (WSL_COLD_START_SPEC.md section 6.1): it's the sole caller of
+# `wsl.attach()`. Its deciding rationale isn't convenience -- it removes
+# the `usbipd` vs `usbipd.exe` trap from the recurring path entirely (a
+# user who never types either name cannot get the wrong binary; see
+# section 6.4). Never invokes `sudo` (P3) -- when a permission fix is
+# still needed after attaching, it prints the command, it doesn't run it.
+# ---------------------------------------------------------------------------
+
+
+def wsl_attach(*, vendor_id: str = "0fd9") -> int:
+    """`muxplex-deck wsl attach` -- attach the Stream Deck to this WSL2 distro.
+
+    Exit 0 on a successful attach (even if a follow-up permission fix is
+    still needed -- the attach itself succeeded). Exit 1 for every state
+    that stops short of attaching (not WSL, WSL1, usbipd.exe missing, not
+    found, not shared) so scripts can branch on it.
+    """
+    from . import hidhelp
+    from . import usbnode as usbnode_mod
+    from . import wsl as wsl_mod
+
+    print("\nmuxplex-deck wsl attach\n")
+
+    info = wsl_mod.detect()
+    if not info.is_wsl:
+        print_check(
+            "fail", "Not running under WSL -- this command only makes sense there."
+        )
+        print()
+        return 1
+    print_check("ok", f"WSL{info.version} detected ({info.kernel})")
+
+    if info.version == 1:
+        print_check("fail", hidhelp.W1_MESSAGE)
+        print()
+        return 1
+
+    paths = wsl_mod.find_usbipd()
+    if paths.linux_impostor is not None and paths.windows is not None:
+        print_check("warn", hidhelp.impostor_message(paths))
+
+    if paths.windows is None:
+        print_check("warn", hidhelp.W2_MESSAGE)
+        print()
+        return 1
+    print_check("ok", f"usbipd.exe: {paths.windows}")
+
+    devices = wsl_mod.list_devices(paths.windows, vendor_id=vendor_id)
+    if devices is None:
+        print_check("warn", hidhelp.W2_MESSAGE)
+        print()
+        return 1
+    if not devices:
+        print_check("warn", hidhelp.NO_MATCHING_WINDOWS_DEVICE_MESSAGE)
+        print()
+        return 1
+
+    device = devices[0]
+    print_check(
+        "ok",
+        f"Found on Windows: BUSID {device.busid}  {device.vid_pid}  {device.description}",
+    )
+
+    if device.state == "not_shared":
+        print_check("warn", hidhelp.w4_message(device))
+        print()
+        return 1
+
+    if device.state == "unknown":
+        print_check("warn", hidhelp.w3_unknown_state_message(device))
+        print()
+        return 1
+
+    if device.state == "shared":
+        print_check("ok", "Shared -- attaching...")
+        success, message = wsl_mod.attach(paths.windows, device.busid)
+        if not success:
+            print_check("fail", f"Attach failed: {message}")
+            print()
+            return 1
+        print_check("ok", "Attached")
+    else:
+        print_check("ok", f"Already attached (BUSID {device.busid})")
+
+    node = usbnode_mod.find_usb_node(vendor_id)
+    if node is None:
+        print_check("warn", hidhelp.w6_message(device))
+        print()
+        return 1
+    print_check("ok", f"Visible to Linux: {node.path}")
+
+    if not node.readable_writable:
+        print_check("warn", hidhelp.w7_message(node))
+        if not usbnode_mod.udev_is_live():
+            print_check(
+                "warn",
+                hidhelp.u_dead_wsl_message(wsl_mod.wsl_conf_systemd_state()),
+            )
+
+    print()
+    print("  Next:")
+    print("    muxplex-deck service restart")
+    print("    muxplex-deck status")
+    print()
+    print(
+        "  The device number changes on every attach -- re-run "
+        "`muxplex-deck wsl attach`\n  after any unplug or Windows reboot."
+    )
+    print()
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # main
 # ---------------------------------------------------------------------------
@@ -1085,6 +1216,13 @@ def main() -> None:
         "key", nargs="?", help="Config key (omit to reset all)"
     )
 
+    wsl_parser = sub.add_parser("wsl", help="WSL2 USB/IP helpers")
+    wsl_sub = wsl_parser.add_subparsers(dest="wsl_command")
+    wsl_sub.add_parser(
+        "attach",
+        help="Find, share-check, and attach the Stream Deck to this WSL2 distro",
+    )
+
     service_parser = sub.add_parser(
         "service", help="Manage the muxplex-deck background service"
     )
@@ -1129,6 +1267,12 @@ def main() -> None:
                 non_interactive=getattr(args, "non_interactive", False),
             )
         )
+    elif args.command == "wsl":
+        cmd = getattr(args, "wsl_command", None)
+        if cmd == "attach":
+            sys.exit(wsl_attach())
+        else:
+            wsl_parser.print_help()
     elif args.command == "config":
         config_path = getattr(args, "config", None)
         cmd = getattr(args, "config_command", None)