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

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "muxplex-deck"
-version = "0.4.0"
+version = "0.4.1"
 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.4.1}/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"
 
 
@@ -855,19 +876,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 +952,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 +966,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,
@@ -989,11 +1045,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",
@@ -1057,7 +1118,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
 

{muxplex_deck-0.4.0 → muxplex_deck-0.4.1}/src/muxplex_deck/main.py

@@ -54,7 +54,6 @@ import threading
 import time
 from urllib.parse import urlparse
 
-from . import attention, focus, interaction, layout, rendering, views
 from muxplex_client import (
     AuthError,
     MuxplexClient,
@@ -64,6 +63,8 @@ from muxplex_client import (
     Settings,
     UnreachableError,
 )
+
+from . import attention, focus, interaction, layout, rendering, views
 from .config import Config
 from .device import (
     DeckDevice,

{muxplex_deck-0.4.0 → muxplex_deck-0.4.1}/src/muxplex_deck/service.py

@@ -17,6 +17,21 @@ Ported near 1:1 from muxplex's own `service.py` (see that repo's
 (unit/plist path, enable/start, resulting status) using the same ✓/!
 2-space-indent style as `cli.doctor()` -- a silent success path left a real
 user unsure whether `service install` had done anything at all.
+
+`launchctl bootstrap` idempotency: unlike `systemctl start` (idempotent --
+starting an already-active unit just succeeds), `launchctl bootstrap` exits
+5 ("Input/output error") when the job label is ALREADY loaded. A real user
+hit this running `service start` against a service that was already
+healthy and running: the code used ``check=True``, so launchd's expected
+"already loaded" refusal surfaced as an unhandled `CalledProcessError`
+traceback instead of the benign no-op it actually is. `_launchd_bootstrap()`
+is the shared, non-raising (`check=False`) helper both `_launchd_install()`
+and `_launchd_start()` use; both treat exit 5 as success, and any other
+nonzero exit as a genuine failure reported via launchctl's own stderr
+(never swallowed) rather than a raw traceback. `_launchd_restart()` also
+waits for `bootout` to actually finish (it returns before the job is fully
+torn down) so the follow-up `bootstrap` doesn't race it into the same
+exit-5 rejection for the wrong reason.
 """
 
 from __future__ import annotations
@@ -26,6 +41,7 @@ import os
 import shutil
 import subprocess
 import sys
+import time
 from pathlib import Path
 
 # ---------------------------------------------------------------------------
@@ -39,6 +55,21 @@ _LAUNCHD_PLIST_DIR: Path = Path.home() / "Library" / "LaunchAgents"
 _LAUNCHD_PLIST_PATH: Path = _LAUNCHD_PLIST_DIR / "com.muxplex-deck.plist"
 _LAUNCHD_LABEL: str = "com.muxplex-deck"
 
+# `launchctl bootstrap` exit code when the job label is already loaded. This
+# is launchd's way of saying "already running" -- not a failure -- so it is
+# handled as a benign no-op everywhere `_launchd_bootstrap()` is used, never
+# swallowed silently for any OTHER exit code.
+_LAUNCHD_ALREADY_LOADED_EXIT = 5
+
+# `launchctl bootout` returns before the job has necessarily finished
+# tearing down, so a `restart` (stop then start) can race it: bootstrap
+# fires while the old job is still unloading and gets rejected with the
+# same exit-5 "already loaded" the still-loading old job produces. Poll
+# `service_is_active()` until the job is actually gone (bounded so a stuck
+# teardown can't hang `restart` forever).
+_LAUNCHD_BOOTOUT_POLL_INTERVAL_SECONDS = 0.2
+_LAUNCHD_BOOTOUT_TIMEOUT_SECONDS = 5.0
+
 # Elgato Stream Deck USB vendor id -- used to detect an existing udev rule.
 _ELGATO_VENDOR_ID = "0fd9"
 _UDEV_RULE_DIRS: tuple[Path, ...] = (
@@ -342,8 +373,36 @@ def _systemd_uninstall() -> None:
     print()
 
 
+def _report_systemctl_failure(
+    action: str, result: subprocess.CompletedProcess[str]
+) -> None:
+    """Print systemctl's own diagnostics for a genuine (non-idempotent) failure.
+
+    The most common ordinary-user trigger here is running `start`/`restart`
+    before `install` (unit not found) -- a real failure, but one that should
+    surface as a clear message, not a raw `CalledProcessError` traceback.
+    """
+    stderr = (result.stderr or "").strip()
+    print(
+        f"  ERROR: systemctl {action} failed (exit {result.returncode})",
+        file=sys.stderr,
+    )
+    if stderr:
+        print(f"    {stderr}", file=sys.stderr)
+
+
 def _systemd_start() -> None:
-    subprocess.run(["systemctl", "--user", "start", "muxplex-deck"], check=True)
+    result = subprocess.run(
+        ["systemctl", "--user", "start", "muxplex-deck"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode == 0:
+        _step_ok("Started the service")
+    else:
+        _report_systemctl_failure("start", result)
+        sys.exit(1)
 
 
 def _systemd_stop() -> None:
@@ -351,7 +410,21 @@ def _systemd_stop() -> None:
 
 
 def _systemd_restart() -> None:
-    subprocess.run(["systemctl", "--user", "restart", "muxplex-deck"], check=True)
+    # `systemctl restart` is a single atomic transaction (unlike launchd's
+    # separate bootout + bootstrap), so it needs no unload-race handling --
+    # and it is idempotent whether or not the unit was already running. The
+    # ordinary failure mode is the unit not being installed yet.
+    result = subprocess.run(
+        ["systemctl", "--user", "restart", "muxplex-deck"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode == 0:
+        _step_ok("Restarted the service")
+    else:
+        _report_systemctl_failure("restart", result)
+        sys.exit(1)
 
 
 def _systemd_status() -> None:
@@ -374,6 +447,71 @@ def _systemd_logs() -> None:
 # ---------------------------------------------------------------------------
 
 
+def _launchd_bootstrap() -> subprocess.CompletedProcess[str]:
+    """Run `launchctl bootstrap` for the muxplex-deck plist, never raising.
+
+    `check=False` deliberately: `bootstrap` exits
+    `_LAUNCHD_ALREADY_LOADED_EXIT` (5, "Input/output error") when the job
+    label is already loaded -- launchd's way of saying "already running",
+    not a failure. Callers must inspect `returncode` themselves and decide
+    what that means for them; this helper only runs the command and hands
+    back the raw result.
+    """
+    uid = os.getuid()
+    return subprocess.run(
+        ["launchctl", "bootstrap", f"gui/{uid}", str(_LAUNCHD_PLIST_PATH)],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+
+def _report_launchctl_failure(
+    action: str, result: subprocess.CompletedProcess[str]
+) -> None:
+    """Print launchctl's own diagnostics for a genuine (non-idempotent) failure.
+
+    Only the well-known "already loaded" exit code is treated as benign by
+    callers; every other nonzero exit prints launchctl's own stderr (which
+    already includes its "re-run as root for richer errors" hint) so the
+    real failure is still visible -- just as a clear message instead of an
+    unhandled `CalledProcessError` traceback.
+    """
+    stderr = (result.stderr or "").strip()
+    print(
+        f"  ERROR: launchctl {action} failed (exit {result.returncode})",
+        file=sys.stderr,
+    )
+    if stderr:
+        print(f"    {stderr}", file=sys.stderr)
+
+
+def _wait_for_launchd_unload(timeout: float | None = None) -> bool:
+    """Poll until the launchd job is no longer loaded, or `timeout` elapses.
+
+    `launchctl bootout` returns before the job has necessarily finished
+    tearing down -- immediately re-bootstrapping afterward can race it and
+    get rejected with the same "already loaded" exit code a genuinely
+    still-running job would produce. Returns True once `service_is_active()`
+    reports the job gone; returns False if it was still present when the
+    timeout elapsed (the caller decides how to proceed -- see
+    `_launchd_restart`).
+
+    `timeout` defaults to `_LAUNCHD_BOOTOUT_TIMEOUT_SECONDS` read at CALL time
+    (not as a bound default argument) so tests can monkeypatch the module
+    constant and have it take effect.
+    """
+    if timeout is None:
+        timeout = _LAUNCHD_BOOTOUT_TIMEOUT_SECONDS
+    deadline = time.monotonic() + timeout
+    while True:
+        if not service_is_active():
+            return True
+        if time.monotonic() >= deadline:
+            return False
+        time.sleep(_LAUNCHD_BOOTOUT_POLL_INTERVAL_SECONDS)
+
+
 def _launchd_install() -> None:
     print("\nmuxplex-deck service install (launchd)\n")
 
@@ -394,11 +532,16 @@ def _launchd_install() -> None:
     _LAUNCHD_PLIST_PATH.write_text(plist_content)
     _step_ok(f"Wrote plist: {_LAUNCHD_PLIST_PATH}")
 
-    uid = os.getuid()
-    subprocess.run(
-        ["launchctl", "bootstrap", f"gui/{uid}", str(_LAUNCHD_PLIST_PATH)], check=True
-    )
-    _step_ok("Loaded + started the service (launchctl bootstrap)")
+    result = _launchd_bootstrap()
+    if result.returncode == 0:
+        _step_ok("Loaded + started the service (launchctl bootstrap)")
+    elif result.returncode == _LAUNCHD_ALREADY_LOADED_EXIT:
+        _step_ok(
+            "Service was already loaded -- plist rewritten; run "
+            "`muxplex-deck service restart` to apply changes"
+        )
+    else:
+        _report_launchctl_failure("bootstrap", result)
 
     if service_is_active():
         _step_ok("Service is running")
@@ -434,10 +577,14 @@ def _launchd_uninstall() -> None:
 
 
 def _launchd_start() -> None:
-    uid = os.getuid()
-    subprocess.run(
-        ["launchctl", "bootstrap", f"gui/{uid}", str(_LAUNCHD_PLIST_PATH)], check=True
-    )
+    result = _launchd_bootstrap()
+    if result.returncode == 0:
+        _step_ok("Started the service (launchctl bootstrap)")
+    elif result.returncode == _LAUNCHD_ALREADY_LOADED_EXIT:
+        _step_ok("Service was already running (nothing to start)")
+    else:
+        _report_launchctl_failure("bootstrap", result)
+        sys.exit(1)
 
 
 def _launchd_stop() -> None:
@@ -447,7 +594,20 @@ def _launchd_stop() -> None:
 
 def _launchd_restart() -> None:
     _launchd_stop()
-    _launchd_start()
+    if not _wait_for_launchd_unload():
+        _step_warn(
+            f"Service did not fully unload within "
+            f"{_LAUNCHD_BOOTOUT_TIMEOUT_SECONDS:.0f}s -- attempting restart anyway"
+        )
+
+    result = _launchd_bootstrap()
+    if result.returncode == 0:
+        _step_ok("Restarted the service (launchctl bootstrap)")
+    elif result.returncode == _LAUNCHD_ALREADY_LOADED_EXIT:
+        _step_ok("Service is running")
+    else:
+        _report_launchctl_failure("bootstrap", result)
+        sys.exit(1)
 
 
 def _launchd_status() -> None:

{muxplex_deck-0.4.0 → muxplex_deck-0.4.1}/src/muxplex_deck/rendering.py

@@ -37,11 +37,11 @@ from __future__ import annotations
 import re
 from typing import cast
 
+from muxplex_client import Session
 from PIL import Image, ImageDraw, ImageFont
 from StreamDeck.Devices.StreamDeck import StreamDeck
 from StreamDeck.ImageHelpers import PILHelper
 
-from muxplex_client import Session
 from .device import DeckDevice
 
 _KEY_LABEL_FONT_SIZE = 16