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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: muxplex-deck
-Version: 0.5.0
+Version: 0.5.2
 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>

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

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

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

@@ -16,6 +16,7 @@ import argparse
 import contextlib
 import json
 import platform
+import shutil
 import subprocess
 import sys
 import time
@@ -323,7 +324,7 @@ def check_config_file(config_path: str | None = None) -> tuple[str, str]:
     resolved = config_mod._resolve_config_path(config_path)
     if resolved.exists():
         return "ok", f"Config: {resolved}"
-    return "warn", f"Config: {resolved} (not yet created -- see README.md)"
+    return "warn", f"Config: {resolved} (not yet created -- run: muxplex-deck init)"
 
 
 def check_federation_key(key_file: Path) -> tuple[str, str]:
@@ -496,9 +497,16 @@ def check_hid_openable() -> tuple[str, str]:
         return "ok", "HID: device in use by the muxplex-deck service (expected)"
 
     from . import hidhelp
+    from . import wsl as wsl_mod
 
     hint = ""
-    if sys.platform not in ("darwin", "win32") and not udev_rule_exists():
+    if wsl_mod.detect().is_wsl:
+        # The udev-rule hints below don't apply on WSL -- see
+        # hidhelp.udev_guidance()'s WSL gate. explain_environment()'s W7
+        # guidance (the proven per-attach chown), already surfaced above
+        # this line in `doctor()`, covers this instead.
+        pass
+    elif sys.platform not in ("darwin", "win32") and not udev_rule_exists():
         hint = hidhelp.HID_HINT_RUN_SERVICE_INSTALL
     elif sys.platform not in ("darwin", "win32"):
         hint = hidhelp.HID_HINT_RULE_EXISTS_BUT_STILL_FAILED
@@ -586,38 +594,35 @@ def check_server_reachable(server_url: str, ca_file: Path | None) -> tuple[str,
 
 
 def check_service_status() -> tuple[str, str]:
-    """Best-effort service-installed/running check (systemd or launchd)."""
+    """Service-state check: not installed / installed but not running / running.
+
+    Three distinct states, not two -- `service_is_installed()` (unit/plist
+    file exists) and `service_is_active()` (currently running) are checked
+    independently, so an installed-but-crash-looping service is reported
+    honestly instead of as "not installed" (which used to tell the user to
+    re-run `service install` for a service that was already installed and
+    failing -- see AGENTS.md for the incident this fixes).
+    """
+    from .service import service_is_active, service_is_installed
+
     if sys.platform == "darwin":
-        import os as _os
+        manager, tool = "launchd", "launchctl"
+    else:
+        manager, tool = "systemd", "systemctl"
 
-        uid = _os.getuid()
-        try:
-            result = subprocess.run(
-                ["launchctl", "print", f"gui/{uid}/com.muxplex-deck"],
-                capture_output=True,
-                text=True,
-                timeout=5,
-                check=False,
-            )
-        except FileNotFoundError:
-            return "warn", "Service: launchctl not found"
-        if result.returncode == 0:
-            return "ok", "Service: installed (launchd)"
+    if shutil.which(tool) is None:
+        return "warn", f"Service: {tool} not found -- run muxplex-deck directly"
+
+    if not service_is_installed():
         return "warn", "Service: not installed -- run: muxplex-deck service install"
 
-    try:
-        result = subprocess.run(
-            ["systemctl", "--user", "is-active", "muxplex-deck"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-            check=False,
-        )
-    except FileNotFoundError:
-        return "warn", "Service: systemctl not found -- run muxplex-deck directly"
-    if result.returncode == 0:
-        return "ok", f"Service: {result.stdout.strip()} (systemd)"
-    return "warn", "Service: not installed -- run: muxplex-deck service install"
+    if service_is_active():
+        return "ok", f"Service: installed and running ({manager})"
+
+    return "warn", (
+        f"Service: installed ({manager}) but not running -- check: "
+        "muxplex-deck service logs"
+    )
 
 
 _CHECK_MARKS: dict[str, str] = {
@@ -669,11 +674,40 @@ def doctor(config_path: str | None = None) -> int:
     # this adds no output there -- see hidhelp.explain_environment().
     from . import hidhelp
 
-    for guidance in hidhelp.explain_environment():
+    env_guidances = hidhelp.explain_environment()
+    for guidance in env_guidances:
         checks.append((guidance.status, guidance.message))
-
-    checks.append(check_deck_detected(config_path))
-    checks.append(check_hid_openable())
+    env_states = {g.state for g in env_guidances}
+
+    if "W7" in env_states:
+        # The W7 guidance just appended above already says the device is
+        # attached but can't be opened, plus the proven per-attach `chown`
+        # fix -- check_deck_detected()/check_hid_openable() would only
+        # restate the same fact across two more (partly contradictory)
+        # lines. See the WSL cold-start bug report: "3 lines describe one
+        # problem". Skip both; nothing more to add.
+        pass
+    else:
+        deck_status, deck_message = check_deck_detected(config_path)
+        if deck_message == _NO_DEVICE_GUIDANCE and env_states & {
+            "W1",
+            "W2",
+            "W3",
+            "W4",
+            "W5",
+            "W6",
+        }:
+            # A WSL-specific state above already explains exactly where
+            # the device is (or precisely why it isn't visible to this OS
+            # yet) -- the generic "check the cable" guidance would
+            # flatly contradict it (see bug report: located @ BUSID 1-4,
+            # immediately followed by "check your cable").
+            deck_message = (
+                "Stream Deck: not detected on this OS yet -- see the WSL "
+                "guidance above."
+            )
+        checks.append((deck_status, deck_message))
+        checks.append(check_hid_openable())
 
     server_url = cfg.server_url if cfg is not None else raw.get("server_url", "")
     checks.append(check_server_reachable(server_url, ca_file))
@@ -1044,6 +1078,34 @@ def update(*, force: bool = False) -> None:
 # ---------------------------------------------------------------------------
 
 
+# A settled-enough bound for sysfs to enumerate a just-attached device --
+# generous enough to absorb the usbip attach -> udev/sysfs lag that
+# produced a false W6 ("not visible yet") immediately followed by a
+# `doctor` run that found the device fine, but tight enough that a
+# genuinely-stuck attach still fails promptly.
+_ATTACH_SETTLE_ATTEMPTS = 5
+_ATTACH_SETTLE_DELAY_SECONDS = 0.2
+
+
+def _find_usb_node_with_settle(usbnode_mod: Any, vendor_id: str) -> Any:
+    """Poll for the USB node with a bounded settle window after an attach.
+
+    A successful `wsl.attach()` can return before sysfs has finished
+    enumerating the device on this side -- checking `find_usb_node` only
+    once produced a false negative (W6: "attached but Linux doesn't see it
+    yet") moments before the very next `doctor` run found the device
+    working. Retries a few times with a short delay instead of declaring
+    failure on the very first miss.
+    """
+    node = usbnode_mod.find_usb_node(vendor_id)
+    for _ in range(_ATTACH_SETTLE_ATTEMPTS - 1):
+        if node is not None:
+            return node
+        time.sleep(_ATTACH_SETTLE_DELAY_SECONDS)
+        node = usbnode_mod.find_usb_node(vendor_id)
+    return node
+
+
 def wsl_attach(*, vendor_id: str = "0fd9") -> int:
     """`muxplex-deck wsl attach` -- attach the Stream Deck to this WSL2 distro.
 
@@ -1119,7 +1181,7 @@ def wsl_attach(*, vendor_id: str = "0fd9") -> int:
     else:
         print_check("ok", f"Already attached (BUSID {device.busid})")
 
-    node = usbnode_mod.find_usb_node(vendor_id)
+    node = _find_usb_node_with_settle(usbnode_mod, vendor_id)
     if node is None:
         print_check("warn", hidhelp.w6_message(device))
         print()

{muxplex_deck-0.5.0 → muxplex_deck-0.5.2}/src/muxplex_deck/config.py

@@ -145,9 +145,9 @@ def load_config(config_path: str | None = None) -> Config:
     if not path.exists():
         raise ConfigError(
             f"Config file not found: {path}\n"
-            "Create it with at least a 'server_url' field, e.g.:\n"
-            '  {"server_url": "https://<your-server>:8088"}\n'
-            "See README.md for the full example."
+            "Run: muxplex-deck init\n"
+            "(or create it by hand with at least a 'server_url' field, e.g.:\n"
+            '  {"server_url": "https://<your-server>:8088"})'
         )
 
     try:

{muxplex_deck-0.5.0 → muxplex_deck-0.5.2}/src/muxplex_deck/hidhelp.py

@@ -52,7 +52,10 @@ HID_HINT_RULE_EXISTS_BUT_STILL_FAILED = (
     " A udev rule exists but the device still could not be opened."
 )
 
-_UDEV_RULE_CONTENT = 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", MODE="0660", GROUP="plugdev", TAG+="uaccess"\n'
+_UDEV_RULE_CONTENT = (
+    'SUBSYSTEM=="usb", ATTRS{idVendor}=="0fd9", MODE="0660", '
+    'GROUP="plugdev", TAG+="uaccess"'
+)
 
 
 @dataclass(frozen=True)
@@ -369,8 +372,24 @@ def udev_guidance() -> Guidance | None:
 
     Returns `None` when udev is not live (P4: never print a command we
     know will fail here) -- `explain_environment()`'s U-DEAD guidance
-    takes its place in that case instead.
+    takes its place in that case instead. Also returns `None` on WSL:
+    `udevadm control --reload-rules` can report success there while the
+    rule still never fires for a usbip-attached device (see AGENTS.md
+    "U7" -- a real WSL user followed this exact block and lost ~40
+    minutes to a rule that never took effect). On WSL the only proven
+    remediation is the per-attach `sudo chown` in `w7_message()`, already
+    surfaced by `explain_environment()` -- callers show that instead (see
+    `service._warn_if_no_udev_rule`).
+
+    The install command is a single `echo | sudo tee` line rather than a
+    `<<'EOF' ... EOF` heredoc: this text gets copy-pasted into a terminal,
+    and a heredoc terminator that isn't at column 0 (as it wasn't here,
+    once the surrounding block got indented for display) is silently
+    swallowed by the shell, leaving the user stuck at a `>` continuation
+    prompt. A single line has no terminator to misplace.
     """
+    if wsl.detect().is_wsl:
+        return None
     if not usbnode.udev_is_live():
         return None
     return Guidance(
@@ -379,8 +398,8 @@ def udev_guidance() -> Guidance | None:
             f"No udev rule found for the Stream Deck (vendor id {_ELGATO_VENDOR_ID}).\n"
             "Without it, the service (running as your user, not root) will fail to\n"
             "open the device. Install a rule once:\n\n"
-            "      sudo tee /etc/udev/rules.d/70-streamdeck.rules >/dev/null <<'EOF'\n"
-            f"{_UDEV_RULE_CONTENT}EOF\n"
+            f"      echo '{_UDEV_RULE_CONTENT}' | sudo tee "
+            "/etc/udev/rules.d/70-streamdeck.rules >/dev/null\n"
             "      sudo udevadm control --reload-rules && sudo udevadm trigger\n\n"
             "Then unplug and replug the Stream Deck (or re-run `muxplex-deck wsl attach`\n"
             "under WSL), and make sure you're in the `plugdev` group:\n"

{muxplex_deck-0.5.0 → muxplex_deck-0.5.2}/src/muxplex_deck/service.py

@@ -44,6 +44,8 @@ import sys
 import time
 from pathlib import Path
 
+from . import config as config_mod
+
 # ---------------------------------------------------------------------------
 # Constants
 # ---------------------------------------------------------------------------
@@ -232,20 +234,28 @@ def _warn_if_no_udev_rule() -> None:
 
     Delegates the actual guidance text to `hidhelp.udev_guidance()` -- the
     single home for this string (see WSL_COLD_START_SPEC.md P6). That
-    function returns `None` when udev isn't actually running (P4: never
-    print a command known to fail here); in that case this prints
-    nothing, and the U-DEAD guidance from `hidhelp.explain_environment()`
-    (surfaced separately by `_print_environment_guidance()` below) takes
-    its place instead.
+    function now returns `None` both when udev isn't actually running
+    (P4: never print a command known to fail here) and when this is WSL
+    (the reload can report success there while the rule still never
+    fires for a usbip-attached device -- see AGENTS.md "U7"; a real WSL
+    user followed this exact block and lost ~40 minutes). On a healthy
+    non-WSL platform this prints nothing, exactly as before. On WSL,
+    show the environment-appropriate guidance instead (the proven
+    per-attach `chown`) rather than leaving the user with nothing.
     """
     if udev_rule_exists():
         return
     from . import hidhelp
 
     guidance = hidhelp.udev_guidance()
-    if guidance is None:
+    if guidance is not None:
+        _print_guidance_block(guidance.message)
         return
-    _print_guidance_block(guidance.message)
+
+    from . import wsl as wsl_mod
+
+    if wsl_mod.detect().is_wsl:
+        _print_environment_guidance()
 
 
 def _print_environment_guidance() -> None:
@@ -299,6 +309,22 @@ def service_is_active() -> bool:
     return result.returncode == 0
 
 
+def service_is_installed() -> bool:
+    """Is the muxplex-deck unit/plist file present on disk?
+
+    Independent of `service_is_active()` -- a service that is installed but
+    crash-looping (or simply stopped) is still installed. `doctor`'s
+    `check_service_status` used to conflate "not active" with "not
+    installed" and recommend `service install` for a service that was
+    already installed and failing; this is the file-existence half of the
+    fix (see AGENTS.md for the incident: 1113 restarts, then told to
+    "install" a service that was already there).
+    """
+    if _is_darwin():
+        return _LAUNCHD_PLIST_PATH.exists()
+    return _SYSTEMD_UNIT_PATH.exists()
+
+
 def _enable_linger() -> None:
     """Best-effort `loginctl enable-linger` so the service survives logout.
 
@@ -338,6 +364,37 @@ def _print_next_steps() -> None:
     print()
 
 
+def _config_ready() -> tuple[bool, str | None]:
+    """Return (True, None) if config is loadable, else (False, ConfigError message).
+
+    Calls the exact same `config.load_config()` the installed unit's own
+    `ExecStart` (`... run`, no `--config` flag) will call at startup, so
+    "ready to install" and "ready to run" can never diverge. A config that
+    fails this check would make the service crash immediately once
+    started, and `Restart=always` (`KeepAlive` on launchd) would then
+    restart it every few seconds forever -- see the `service install`
+    crash-loop incident in AGENTS.md (1113 restarts on a fresh machine
+    with no config yet).
+    """
+    try:
+        config_mod.load_config(None)
+    except config_mod.ConfigError as exc:
+        return False, str(exc)
+    return True, None
+
+
+def _print_config_not_ready(config_error: str | None) -> None:
+    """Explain why install is stopping short of enabling/starting the service."""
+    _print_guidance_block(
+        "Not enabling or starting yet -- configuration is incomplete:\n"
+        + (config_error or "unknown configuration error")
+    )
+    print()
+    print("  Run muxplex-deck init to create it, then run this command again:")
+    print("    muxplex-deck service install")
+    print()
+
+
 def _systemd_install() -> None:
     print("\nmuxplex-deck service install (systemd --user)\n")
 
@@ -354,6 +411,15 @@ def _systemd_install() -> None:
     subprocess.run(["systemctl", "--user", "daemon-reload"], check=True)
     _step_ok("Reloaded the systemd user daemon")
 
+    # Never enable/start a unit whose config we already know will make it
+    # crash on launch -- see `_config_ready()`. The unit file above is
+    # harmless to have on disk either way; only the "make it run" steps are
+    # gated.
+    config_ready, config_error = _config_ready()
+    if not config_ready:
+        _print_config_not_ready(config_error)
+        return
+
     subprocess.run(
         ["systemctl", "--user", "enable", "--now", "muxplex-deck"], check=True
     )
@@ -559,6 +625,15 @@ def _launchd_install() -> None:
     _LAUNCHD_PLIST_PATH.write_text(plist_content)
     _step_ok(f"Wrote plist: {_LAUNCHD_PLIST_PATH}")
 
+    # Never bootstrap (load + start) a job whose config we already know will
+    # make it crash on launch -- see `_config_ready()`. `KeepAlive` would
+    # then have launchd relaunch it forever. The plist above is harmless to
+    # have on disk either way; only the "make it run" step is gated.
+    config_ready, config_error = _config_ready()
+    if not config_ready:
+        _print_config_not_ready(config_error)
+        return
+
     result = _launchd_bootstrap()
     if result.returncode == 0:
         _step_ok("Loaded + started the service (launchctl bootstrap)")