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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: muxplex-deck
-Version: 0.4.0
+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.0 → 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.0 → muxplex_deck-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "muxplex-deck"
-version = "0.4.0"
+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.0 → muxplex_deck-0.5.0}/src/muxplex_deck/cli.py

@@ -251,11 +251,14 @@ def _get_install_info() -> dict:
     return info
 
 
+_PYPI_PROJECT_URL = "https://pypi.org/pypi/muxplex-deck/json"
+
+
 def _check_for_update(info: dict) -> tuple[bool, str]:
     """Check if an update is available.
 
-    muxplex-deck is git-only (no PyPI release) -- only the git comparison
-    path applies. Editable installs are never flagged.
+    muxplex-deck 0.4.0+ is published to PyPI, so both the git and pypi
+    comparison paths apply now. Editable installs are never flagged.
     """
     if info["source"] == "editable":
         return False, "editable install -- manage updates manually"
@@ -283,6 +286,24 @@ def _check_for_update(info: dict) -> tuple[bool, str]:
         except Exception:  # noqa: BLE001 -- any git/network failure means "upgrade to be safe"
             return True, "check failed -- upgrading to be safe"
 
+    if info["source"] == "pypi":
+        try:
+            import httpx
+
+            response = httpx.get(
+                _PYPI_PROJECT_URL,
+                headers={"Accept": "application/json"},
+                timeout=10,
+            )
+            response.raise_for_status()
+            latest = response.json()["info"]["version"]
+            current = info["version"]
+            if latest == current:
+                return False, f"up to date (v{current})"
+            return True, f"update available (v{current} -> v{latest})"
+        except Exception:  # noqa: BLE001 -- any network/parse failure means "upgrade to be safe"
+            return True, "could not check PyPI -- upgrading to be safe"
+
     return True, "unknown install source -- could not check"
 
 
@@ -400,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"
 )
 
 
@@ -481,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}"
 
 
@@ -647,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())
 
@@ -681,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"
@@ -780,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", {})))
 
@@ -855,19 +891,54 @@ def _service_is_active() -> bool:
     return service_is_active()
 
 
-def update() -> None:
+def update(*, force: bool = False) -> None:
     """Update muxplex-deck to the latest version and restart the service (if installed).
 
-    Simplified relative to muxplex's own `upgrade()`: muxplex-deck has no
-    PyPI release, so there is no "already up to date, use --force" version
-    gate -- it always reinstalls from git HEAD (matching `uv tool install
-    --force`'s own semantics). Reporting style (plain `  ERROR: ...` on
-    stderr equivalent) matches muxplex's.
+    Respects how the tool was installed (see `_get_install_info`), mirroring
+    muxplex's own `upgrade()`: a `pypi` install upgrades from PyPI (package
+    name, so `uv tool install --force muxplex-deck` / `pip install --upgrade
+    muxplex-deck`); a `git` (or `unknown`) install keeps reinstalling from
+    git HEAD via `_REPO_URL`, exactly as before -- this honors an explicit
+    git install rather than migrating it. An `editable` install is left
+    alone entirely (dev checkout -- manage it via git yourself).
+
+    Now that a real PyPI release exists, the "already up to date" version
+    gate this module previously lacked (see AGENTS.md history) is real:
+    unless `force=True`, an install already at the latest version/commit
+    is reported and left untouched rather than reinstalled and restarted
+    for no code change. Reporting style (plain `  ERROR: ...` on stderr
+    equivalent) matches muxplex's.
     """
     from .service import service_install
 
     print("\nmuxplex-deck update\n")
 
+    info = _get_install_info()
+    commit_suffix = f" @ {info['commit'][:8]}" if info["commit"] else ""
+    print(
+        f"  Installed: muxplex-deck {info['version']} (via {info['source']}{commit_suffix})"
+    )
+
+    if info["source"] == "editable":
+        print(
+            "\n  Editable install detected -- manage updates via git yourself (no action taken).\n"
+        )
+        return
+
+    if force:
+        print("  Status: --force specified -- skipping version check")
+    else:
+        update_available, message = _check_for_update(info)
+        print(f"  Status: {message}")
+        if not update_available:
+            print(
+                "\n  Already up to date."
+                " Use 'muxplex-deck update --force' to reinstall anyway.\n"
+            )
+            return
+
+    install_target = "muxplex-deck" if info["source"] == "pypi" else f"git+{_REPO_URL}"
+
     was_active = _service_is_active()
     if was_active:
         print("  Stopping service...")
@@ -896,7 +967,7 @@ def update() -> None:
         uv_path = _find_uv()
         if uv_path:
             result = subprocess.run(
-                [uv_path, "tool", "install", "--force", f"git+{_REPO_URL}"],
+                [uv_path, "tool", "install", "--force", install_target],
                 capture_output=True,
                 text=True,
                 check=False,
@@ -910,7 +981,7 @@ def update() -> None:
             pip_path = _find_pip()
             if pip_path:
                 result = subprocess.run(
-                    [pip_path, "install", "--upgrade", f"git+{_REPO_URL}"],
+                    [pip_path, "install", "--upgrade", install_target],
                     capture_output=True,
                     text=True,
                     check=False,
@@ -960,6 +1031,122 @@ def update() -> 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
 # ---------------------------------------------------------------------------
@@ -989,11 +1176,16 @@ def main() -> None:
         "--json", action="store_true", help="Emit raw status as JSON"
     )
 
-    sub.add_parser(
+    update_parser = sub.add_parser(
         "update",
         aliases=["upgrade"],
         help="Update muxplex-deck to the latest version and restart the service",
     )
+    update_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Reinstall even if already at the latest version/commit",
+    )
 
     init_parser = sub.add_parser(
         "init",
@@ -1024,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"
     )
@@ -1057,7 +1256,7 @@ def main() -> None:
             status(getattr(args, "config", None), as_json=getattr(args, "json", False))
         )
     elif args.command in ("update", "upgrade"):
-        update()
+        update(force=getattr(args, "force", False))
     elif args.command == "init":
         from .init_wizard import run_init
 
@@ -1068,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)