muxplex-deck 0.6.1__tar.gz → 0.7.0__tar.gz

{muxplex_deck-0.6.1 → muxplex_deck-0.7.0}/PKG-INFO

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

{muxplex_deck-0.6.1 → muxplex_deck-0.7.0}/pyproject.toml

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

{muxplex_deck-0.6.1 → muxplex_deck-0.7.0}/src/muxplex_deck/cli.py

@@ -812,15 +812,118 @@ def print_check(status: str, message: str) -> None:
         print(f"{prefix}{line}")
 
 
-def doctor(config_path: str | None = None) -> int:
+def _status_glyph(status: str) -> str:
+    """Map a check helper's ("ok"|"warn"|"fail") status to a report glyph.
+
+    "ok" -> fine. "fail" (a definitive rejection) and "warn" (almost always
+    paired with a "run: ..." remediation already in the message) both ->
+    act-now. Checks that are genuinely blocked on an upstream item (e.g.
+    server/service before config exists) are never routed through this
+    mapper -- callers construct those `Check`s directly with
+    `report.BLOCKED` instead.
+    """
+    from . import report
+
+    return report.FINE if status == "ok" else report.ACT
+
+
+def _hid_tail(hid_message: str) -> str:
+    """Short phrase summarizing a successful HID-open, for the merged device line."""
+    text = hid_message
+    text = text.removeprefix("HID: ")
+    if text.startswith("device opened successfully"):
+        return "HID opens"
+    if text.startswith("device in use by the muxplex-deck service"):
+        return "HID in use by service"
+    return text if text.startswith("HID") else f"HID: {text}"
+
+
+def _device_hid_checks(
+    deck_status: str, deck_message: str, hid_status: str, hid_message: str
+) -> list[Any]:
+    """Merge device-detection + HID-open into one line when they agree.
+
+    When both share a glyph there's nothing to hide by combining them --
+    one readable "device" line beats two boring ones. When they diverge
+    (e.g. the device is visible on Windows but WSL can't open it yet),
+    collapsing to a single worst-member line would silently drop whichever
+    fact ACTION needs to reference (like a busid) -- so they render as two
+    independent, dependency-ordered lines instead: "device" (is it
+    physically present) then "hid" (can this process open it).
+    """
+    from . import report
+
+    deck_glyph = _status_glyph(deck_status)
+    hid_glyph = _status_glyph(hid_status)
+    if deck_glyph == hid_glyph:
+        tail = _hid_tail(hid_message)
+        value = f"{deck_message}, {tail}" if tail else deck_message
+        return [report.Check("device", deck_glyph, value)]
+    return [
+        report.Check("device", deck_glyph, deck_message),
+        report.Check("hid", hid_glyph, hid_message),
+    ]
+
+
+def _doctor_decision(check: Any) -> Any:
+    """Build the ACTION decision for the first act-now check, in dependency order."""
+    from . import report
+
+    if check.subject == "config":
+        return report.Decision(
+            commands=["muxplex-deck init"],
+            prose=(
+                "Creates the config, fetches and fingerprints the server CA, "
+                "stores the federation key, and offers to install the service."
+            ),
+        )
+    command = report.extract_run_command(check.value)
+    if command:
+        return report.Decision(commands=[command])
+    return report.Decision(commands=[], prose=check.value)
+
+
+def _build_doctor_action(collapsed: list[Any]) -> list[str] | None:
+    """The ACTION band: the first act-now item's decision, plus an overflow
+
+    note when more than one independent act-now item exists (see
+    report.Action.overflow_note) -- never dump every fix at once.
+    """
+    from . import report
+
+    act_items = [c for c in collapsed if c.glyph == report.ACT]
+    if not act_items:
+        return None
+    overflow = None
+    if len(act_items) > 1:
+        overflow = f"{len(act_items) - 1} more after this -- rerun doctor."
+    action = report.Action(
+        decision=_doctor_decision(act_items[0]), overflow_note=overflow
+    )
+    return report.render_action(action)
+
+
+def doctor(config_path: str | None = None, *, show_all: bool = False) -> int:
     """Run diagnostic checks and report system status. Always returns 0 (informational)."""
-    print("\nmuxplex-deck doctor\n")
+    from . import hidhelp, report
+
+    utf8 = report.utf8_capable()
 
-    checks: list[tuple[str, str]] = []
-    checks.append(check_python_version())
-    checks.append(check_install_and_update())
-    checks.append(check_config_file(config_path))
+    py_status, py_message = check_python_version()
+    inst_status, inst_message = check_install_and_update()
+    env_members = [
+        report.Check("python", _status_glyph(py_status), py_message),
+        report.Check("install", _status_glyph(inst_status), inst_message),
+    ]
+    hidapi_check = check_hidapi_dll()  # Windows-only; None everywhere else.
+    if hidapi_check is not None:
+        hidapi_status, hidapi_message = hidapi_check
+        env_members.append(
+            report.Check("hidapi", _status_glyph(hidapi_status), hidapi_message)
+        )
+    environment_group = report.Group("environment", env_members)
 
+    cfg_status, cfg_message = check_config_file(config_path)
     try:
         cfg = config_mod.load_config(config_path)
     except ConfigError:
@@ -828,29 +931,44 @@ def doctor(config_path: str | None = None) -> int:
 
     raw = config_mod.load_raw_config(config_path)
     key_file = config_mod._expand(raw.get("key_file", config_mod.DEFAULT_KEY_FILE))
-    checks.append(check_federation_key(key_file))
+    key_status, key_message = check_federation_key(key_file)
 
     ca_file = cfg.ca_file if cfg is not None else None
     if cfg is None and raw.get("ca_file"):
         ca_file = config_mod._expand(raw["ca_file"])
-    checks.append(check_ca_file(ca_file))
+    ca_status, ca_message = check_ca_file(ca_file)
+
+    config_group = report.Group(
+        "config",
+        [
+            report.Check("file", _status_glyph(cfg_status), cfg_message),
+            report.Check("key", _status_glyph(key_status), key_message),
+            report.Check("ca", _status_glyph(ca_status), ca_message),
+        ],
+    )
+    config_created = cfg_status == "ok"
 
-    # Windows-only; None (skipped, not appended) on every other platform.
-    hidapi_check = check_hidapi_dll()
-    if hidapi_check is not None:
-        checks.append(hidapi_check)
+    items: list[Any] = [environment_group, config_group]
 
     # 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
-
     env_guidances = hidhelp.explain_environment()
     for guidance in env_guidances:
-        checks.append((guidance.status, guidance.message))
+        items.append(
+            report.Check("device", _status_glyph(guidance.status), guidance.message)
+        )
     env_states = {g.state for g in env_guidances}
 
+    if not config_created:
+        # Server/service structurally need server_url/config -- blocked,
+        # not independently evaluated. Device/HID don't depend on config
+        # at all (a bare USB probe works with no config file), so they are
+        # still evaluated for real below.
+        items.append(report.Check("server", report.BLOCKED, "waiting on config"))
+        items.append(report.Check("service", report.BLOCKED, "waiting on config"))
+
     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`
@@ -874,22 +992,27 @@ def doctor(config_path: str | None = None) -> int:
             # 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())
+            deck_message = "not detected on this OS yet -- see the WSL guidance above."
+        hid_status, hid_message = check_hid_openable()
+        items.extend(
+            _device_hid_checks(deck_status, deck_message, hid_status, hid_message)
+        )
 
-    server_url = cfg.server_url if cfg is not None else raw.get("server_url", "")
-    checks.append(check_server_reachable(server_url, ca_file))
+    if config_created:
+        server_url = cfg.server_url if cfg is not None else raw.get("server_url", "")
+        srv_status, srv_message = check_server_reachable(server_url, ca_file)
+        items.append(report.Check("server", _status_glyph(srv_status), srv_message))
 
-    checks.append(check_service_status())
+        svc_status, svc_message = check_service_status()
+        items.append(report.Check("service", _status_glyph(svc_status), svc_message))
 
-    for status, message in checks:
-        print_check(status, message)
+    collapsed = report.collapsed_checks(items)
+    action_count = report.count_actions([c.glyph for c in collapsed])
+    verdict = report.verdict_readiness(action_count)
+    state_lines = report.render_items(items, show_all=show_all, utf8=utf8)
+    action_lines = _build_doctor_action(collapsed)
 
-    print()
+    sys.stdout.write(report.render(verdict, state_lines, action_lines))
     return 0
 
 
@@ -908,48 +1031,62 @@ def doctor(config_path: str | None = None) -> int:
 _STATUS_STALE_THRESHOLD_SECONDS = 15.0
 
 
-def _format_device_line(device: dict[str, Any]) -> tuple[str, str]:
+def _status_device_item(device: dict[str, Any]) -> Any:
+    """Build the "device" Check from the sidecar's published status snapshot.
+
+    "-" is the correct rendering for "I could not determine this" -- during
+    a restart race the caller returns before this is ever called (see the
+    pid-freshness guard in `status()`), so this function only ever runs
+    when the snapshot is genuinely current.
+    """
+    from . import report
+
     if not device.get("connected"):
-        return "warn", "Device: not connected"
+        return report.Check("device", report.ACT, "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)"
+        glyph = report.ACT if hint else report.FINE
+        return report.Check("device", glyph, "connected (capabilities unavailable)")
     touchscreen = "yes" if caps.get("has_touchscreen") else "no"
-    return "ok", (
-        f"Device: {caps.get('model', '?')} -- {caps.get('key_count', '?')} keys "
+    value = (
+        f"{caps.get('model', '?')} -- {caps.get('key_count', '?')} keys "
         f"({caps.get('key_rows', '?')}x{caps.get('key_cols', '?')}), "
         f"{caps.get('dial_count', '?')} dials, touchscreen={touchscreen}"
     )
+    return report.Check("device", report.FINE, value)
 
 
-def _format_server_line(server: dict[str, Any]) -> tuple[str, str]:
+def _status_server_item(server: dict[str, Any]) -> Any:
+    from . import report
+
     url = server.get("url") or "(not configured)"
     if server.get("connected"):
-        return "ok", f"Server: {url} (reachable)"
+        return report.Check("server", report.FINE, f"{url} (reachable)")
     err = server.get("last_error")
-    message = f"Server: {url} (unreachable)"
+    value = f"{url} (unreachable)"
     if err:
-        message += f" -- {err}"
-    return "warn", message
+        value += f" -- {err}"
+    return report.Check("server", report.ACT, value)
 
 
-def _format_state_line(state: dict[str, Any]) -> str:
-    session = state.get("active_session") or "none"
-    view = state.get("active_view") or "all"
+def _status_view_value(state: dict[str, Any]) -> str:
+    view_name = state.get("active_view") or "all"
     page = state.get("page")
-    page_text = str(page) if page is not None else "-"
-    return f"Active session: {session} | view: {view} | page: {page_text}"
+    return f"{view_name} (page {page})" if page is not None else view_name
 
 
-def _print_direct_probe(config_path: str | None) -> None:
+def _direct_probe_item(config_path: str | None) -> Any:
     """Fallback when the service isn't running -- nothing holds the device."""
-    print_check(*check_deck_detected(config_path))
+    from . import report
+
+    deck_status, deck_message = check_deck_detected(config_path)
+    return report.Check("device", _status_glyph(deck_status), deck_message)
 
 
-def status(config_path: str | None = None, *, as_json: bool = False) -> int:
+def status(
+    config_path: str | None = None, *, as_json: bool = False, show_all: bool = False
+) -> int:
     """Print the sidecar's hardware + connection status.
 
     Reads the status file the running sidecar publishes (see
@@ -961,6 +1098,7 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
     fall back to a direct probe -- this keeps `status` useful even before
     the service has ever been installed.
     """
+    from . import report
     from .service import service_is_active, service_main_pid
     from .statusfile import read_status
 
@@ -972,36 +1110,45 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
         print(json.dumps(payload, indent=2))
         return 0 if data is not None else 1
 
-    print("\nmuxplex-deck status\n")
-    print_check(
-        "ok" if running else "warn",
-        f"Service: {'running' if running else 'not running'}",
-    )
+    utf8 = report.utf8_capable()
 
     if not running:
-        if data is None:
-            print_check(
-                "warn",
-                "No status file found -- probing the device directly instead "
-                "(safe: nothing holds it while the service is stopped).",
-            )
-        else:
-            print_check(
-                "warn",
-                "Service not running -- probing the device directly instead "
-                "of trusting the (possibly stale) status file.",
-            )
-        _print_direct_probe(config_path)
-        print()
+        probe_note = (
+            "no status file -- probing the device directly instead (safe: "
+            "nothing holds it while the service is stopped)"
+            if data is None
+            else "not trusting the (possibly stale) status file -- probing "
+            "the device directly instead"
+        )
+        items: list[Any] = [
+            report.Check("service", report.BLOCKED, "not running"),
+            report.Check("probe", report.BLOCKED, probe_note),
+            _direct_probe_item(config_path),
+        ]
+        collapsed = report.collapsed_checks(items)
+        action_count = report.count_actions([c.glyph for c in collapsed])
+        verdict = (
+            "Not connected -- service not running."
+            if action_count == 0
+            else report.verdict_readiness(action_count)
+        )
+        state_lines = report.render_items(items, show_all=show_all, utf8=utf8)
+        sys.stdout.write(report.render(verdict, state_lines, None))
         return 0
 
     if data is None:
-        print_check(
-            "unknown",
-            "No status file found even though the service is running -- it "
-            "may have just started. Try: muxplex-deck service logs",
+        items = [
+            report.Check(
+                "status",
+                report.BLOCKED,
+                "no status file yet -- the sidecar may have just started. "
+                "Try: muxplex-deck service logs",
+            )
+        ]
+        state_lines = report.render_items(items, show_all=show_all, utf8=utf8)
+        sys.stdout.write(
+            report.render("Not connected -- starting up.", state_lines, None)
         )
-        print()
         return 0
 
     # Is this snapshot from the process running RIGHT NOW, or from a
@@ -1024,40 +1171,94 @@ def status(config_path: str | None = None, *, as_json: bool = False) -> int:
         ) <= _STATUS_STALE_THRESHOLD_SECONDS
 
     if not is_current:
-        print_check(
-            "unknown",
-            f"Status not yet available for the running process (pid "
-            f"{current_pid if current_pid is not None else '?'}) -- the "
-            f"published status is from a previous run (pid {recorded_pid}). "
-            "This is expected right after (re)starting; try again in a "
-            "moment, or: muxplex-deck service logs",
+        # "-" (BLOCKED), never "!" (act-now): we did not actually observe
+        # this instant, so nothing here has earned a verdict yet -- see the
+        # restart-race incident this guards against (AGENTS.md).
+        items = [
+            report.Check(
+                "status",
+                report.BLOCKED,
+                f"not yet available for the running process (pid "
+                f"{current_pid if current_pid is not None else '?'}) -- the "
+                f"published status is from a previous run (pid {recorded_pid}). "
+                "This is expected right after (re)starting; try again in a "
+                "moment, or: muxplex-deck service logs",
+            )
+        ]
+        state_lines = report.render_items(items, show_all=show_all, utf8=utf8)
+        sys.stdout.write(
+            report.render("Not connected -- previous run's data.", state_lines, None)
         )
-        print()
         return 0
 
     age = time.time() - data.get("updated_at", 0)
-    if age > _STATUS_STALE_THRESHOLD_SECONDS:
-        print_check(
-            "warn",
-            f"Status file is stale (last updated {age:.0f}s ago) -- the "
-            "sidecar may be stuck. Try: muxplex-deck service logs",
-        )
-    else:
-        print_check("ok", f"Status updated {age:.0f}s ago (pid {data.get('pid', '?')})")
+    stale = age > _STATUS_STALE_THRESHOLD_SECONDS
+    device_item = _status_device_item(data.get("device", {}))
+    server_item = _status_server_item(data.get("server", {}))
+    state = data.get("state", {})
+
+    session_readout = report.Readout("session", state.get("active_session") or "none")
+    view_readout = report.Readout("view", _status_view_value(state))
+    pid_readout = report.Readout(
+        "pid", f"{data.get('pid', '?')} (updated {age:.0f}s ago)"
+    )
 
-    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"):
+    all_fine = (
+        not stale
+        and device_item.glyph == report.FINE
+        and server_item.glyph == report.FINE
+    )
+
+    if all_fine:
+        readouts = [
+            session_readout,
+            view_readout,
+            report.Readout("device", device_item.value),
+            report.Readout("server", server_item.value),
+            pid_readout,
+        ]
+        state_lines = report.render_readouts(readouts)
+        sys.stdout.write(report.render("Running.", state_lines, None))
+        return 0
+
+    lines: list[str] = [
+        report.format_readout_line(session_readout.name, session_readout.value),
+        report.format_readout_line(view_readout.name, view_readout.value),
+        report.format_check_line(
+            device_item.glyph, device_item.subject, device_item.value, utf8=utf8
+        ),
+    ]
+    hint = data.get("device", {}).get("hint")
+    if hint and device_item.glyph != report.FINE:
         # 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", {})))
-
-    print()
+        lines.append(report.format_check_line(report.ACT, "hint", hint, utf8=utf8))
+    lines.append(
+        report.format_check_line(
+            server_item.glyph, server_item.subject, server_item.value, utf8=utf8
+        )
+    )
+    if stale:
+        lines.append(
+            report.format_check_line(
+                report.ACT,
+                "status",
+                f"stale (last updated {age:.0f}s ago) -- the sidecar may be "
+                "stuck. Try: muxplex-deck service logs",
+                utf8=utf8,
+            )
+        )
+    lines.append(report.format_readout_line(pid_readout.name, pid_readout.value))
+
+    glyphs = [device_item.glyph, server_item.glyph]
+    if hint and device_item.glyph != report.FINE:
+        glyphs.append(report.ACT)
+    if stale:
+        glyphs.append(report.ACT)
+    verdict = report.verdict_readiness(report.count_actions(glyphs))
+    sys.stdout.write(report.render(verdict, lines, None))
     return 0
 
 
@@ -1428,7 +1629,17 @@ def main() -> None:
 
     sub.add_parser("version", help="Show the muxplex-deck version")
 
-    sub.add_parser("doctor", help="Check dependencies and system status")
+    doctor_parser = sub.add_parser(
+        "doctor", help="Check dependencies and system status"
+    )
+    doctor_parser.add_argument(
+        "--all",
+        "--verbose",
+        dest="show_all",
+        action="store_true",
+        help="Show every underlying check (VID:PID, full paths, etc.) instead "
+        "of the collapsed summary -- a strict superset, never a different answer",
+    )
 
     status_parser = sub.add_parser(
         "status", help="Show connected hardware + connection state"
@@ -1436,6 +1647,13 @@ def main() -> None:
     status_parser.add_argument(
         "--json", action="store_true", help="Emit raw status as JSON"
     )
+    status_parser.add_argument(
+        "--all",
+        "--verbose",
+        dest="show_all",
+        action="store_true",
+        help="Show every underlying check instead of the collapsed summary",
+    )
 
     update_parser = sub.add_parser(
         "update",
@@ -1511,10 +1729,14 @@ def main() -> None:
     if args.command == "version":
         print_version()
     elif args.command == "doctor":
-        doctor(getattr(args, "config", None))
+        doctor(getattr(args, "config", None), show_all=getattr(args, "show_all", False))
     elif args.command == "status":
         sys.exit(
-            status(getattr(args, "config", None), as_json=getattr(args, "json", False))
+            status(
+                getattr(args, "config", None),
+                as_json=getattr(args, "json", False),
+                show_all=getattr(args, "show_all", False),
+            )
         )
     elif args.command in ("update", "upgrade"):
         update(force=getattr(args, "force", False))

{muxplex_deck-0.6.1 → muxplex_deck-0.7.0}/src/muxplex_deck/layout.py

@@ -13,18 +13,34 @@ Two layout modes:
   Deck+). Every LCD key is a session tile; dial 0 cycles views, dial 1
   pages, and the touch strip carries the server/view/status headline.
   This is the pre-existing Stream Deck+ behavior, unchanged.
-- REDUCED -- everything else (Original/MK2 3x5, XL 4x8, Mini 2x3, ...).
+- REDUCED -- everything else (Original/MK2 3x5, XL 4x8, Mini 3x2, ...).
   With no dials or strip to lean on, three keys are reserved *by grid
   position* (computed from `key_layout` rows x cols, never hardcoded)
-  for the roles the dials/strip played:
-    * VIEW  = top-left     (index 0): shows the current view name +
-      server label (what the strip showed); a tap opens a paged view
-      picker on the session-slot keys (dial-0's picker role) -- VIEW
-      becomes BACK, PREV/NEXT page the list, tapping a view selects it.
-    * PREV  = bottom-left  (index (rows-1)*cols): previous page.
-    * NEXT  = bottom-right (index rows*cols-1): next page (dial-1's role).
-  Every remaining key is a session tile in reading order, so
-  sessions_per_page = key_count - 3 (12 on a 15-key deck).
+  for the roles the dials/strip played. Which three positions depends on
+  grid shape alone (see `_reserved_control_keys`), never on model name:
+
+    * Exactly 3 columns, 2+ rows (e.g. the Stream Deck Mini, 3 cols x 2
+      rows): 3 columns is exactly enough to dedicate the *entire bottom
+      row* to controls, reading left to right as PREV, VIEW, NEXT --
+      every row above it is entirely session tiles. This was chosen over
+      reusing the corner layout below because on a 3-wide grid the
+      corner scheme leaves session tiles awkwardly split around a lone
+      reserved key in the bottom row (e.g. keys 1, 2, 4 on a 3x2 grid --
+      a gap where key 3 (PREV) sits), whereas a full control row leaves
+      every session tile contiguous on the row(s) above.
+    * Everything else (any other column count): reserve the three
+      corners -- VIEW top-left (index 0), PREV bottom-left
+      (index (rows-1)*cols), NEXT bottom-right (index rows*cols-1) --
+      the original REDUCED geometry, ported from dial-0/dial-1's roles
+      on the Stream Deck+. Unchanged for the 15-key Original (3x5) and
+      XL (4x8).
+
+  In both cases VIEW shows the current view name + server label (what
+  the strip showed); a tap opens a paged view picker on the session-slot
+  keys (dial-0's picker role) -- VIEW becomes BACK, PREV/NEXT page the
+  list, tapping a view selects it. Every remaining key is a session tile
+  in reading order, so sessions_per_page = key_count - 3 (12 on a 15-key
+  deck, 3 on a 6-key Mini).
 
 Edge cases (degrade gracefully, never crash):
 
@@ -33,10 +49,10 @@ Edge cases (degrade gracefully, never crash):
 - Touchscreen but fewer than two dials: REDUCED for the keys, but the
   strip is still used for the status headline (`use_strip` stays True) --
   free extra signal, no behavior depends on it.
-- Fewer than 4 keys, or a grid so degenerate the three reserved corners
-  collide (e.g. a single row, where top-left == bottom-left): every key
-  becomes a session tile with no view/page controls -- a plain session
-  switcher beats three controls with no sessions.
+- Fewer than 4 keys, or a grid so degenerate the three reserved control
+  keys collide (e.g. a single row, where top-left == bottom-left): every
+  key becomes a session tile with no view/page controls -- a plain
+  session switcher beats three controls with no sessions.
 
 Everything here is pure (no device I/O, no threads), so both layout modes
 are unit-testable with fake capability dicts.
@@ -102,6 +118,27 @@ class LayoutPlan:
     use_strip: bool  # paint the touch strip (status headline)?
 
 
+def _reserved_control_keys(rows: int, cols: int) -> tuple[int, int, int]:
+    """Compute `(view_key, prev_key, next_key)` physical key indices.
+
+    Chosen by grid shape alone (`key_rows` x `key_cols`) -- never by model
+    name. Two geometries:
+
+    - Exactly 3 columns, 2+ rows: the bottom row exactly fits all three
+      controls, reading left to right as PREV, VIEW, NEXT. Every row above
+      it is entirely session tiles. A 3-wide grid is the one shape where a
+      full control row is both possible (no leftover) and better than the
+      corner scheme below, which would otherwise strand session tiles
+      around a lone reserved key mid-row.
+    - Everything else: reserve the three corners -- VIEW top-left, PREV
+      bottom-left, NEXT bottom-right -- the original REDUCED geometry.
+    """
+    if cols == 3 and rows >= 2:
+        bottom_row_start = (rows - 1) * cols
+        return bottom_row_start + 1, bottom_row_start, bottom_row_start + 2
+    return 0, (rows - 1) * cols, rows * cols - 1
+
+
 def plan_layout(caps: Mapping[str, Any]) -> LayoutPlan:
     """Choose the layout mode and key assignments for a deck's capabilities.
 
@@ -131,9 +168,7 @@ def plan_layout(caps: Mapping[str, Any]) -> LayoutPlan:
             use_strip=True,
         )
 
-    view_key = 0
-    prev_key = (rows - 1) * cols
-    next_key = rows * cols - 1
+    view_key, prev_key, next_key = _reserved_control_keys(rows, cols)
     reserved = (view_key, prev_key, next_key)
     degenerate = (
         key_count < _REDUCED_MIN_KEYS

muxplex_deck-0.7.0/src/muxplex_deck/report.py

@@ -0,0 +1,416 @@
+"""Terminal-output rendering for `doctor` / `status` / `service` -- pure text.
+
+Three bands, always this order, separated by exactly ONE blank line, with
+leading/trailing blank lines as the only frame::
+
+    VERDICT     one line, column 0
+    STATE       the checks or readouts, indented
+    ACTION      "Do this:" + exactly one decision (omitted when nothing to do)
+
+No ANSI color, no box drawing, no tree connectors -- the acid test is the
+paste: the user's primary act is selecting this output and pasting it as
+plain text, so every emphasis device must survive that. Output is
+byte-identical whether printed to a TTY or piped to a file; the only thing
+that varies with environment is the `+` (fine) glyph, which becomes a
+Unicode checkmark when the environment is UTF-8-capable (see
+`utf8_capable`). This module does no I/O itself -- callers decide what to
+check and how to phrase it; this module only lays it out.
+
+Column ladder (exact, see the layout-architect review this implements)::
+
+    check line     2sp + glyph + 2sp + subject padded to 14 + value (col 19)
+    continuation    19sp + text (hangs under the value column)
+    readout line     5sp + name padded to 14 + value -- gutter left empty
+    group label     column 0, lowercase, blank line above (--all only)
+    command to run  indented +4 from its governing text
+    prose in ACTION column 2, max 2 lines
+
+Only VERDICT, "Do this:", and `--all` group labels ever touch column 0.
+Below 60 columns, subject padding drops to a single space (no other
+reflow); above 80, nothing changes -- fields are never stretched to fill
+a wide terminal, and wrapping always happens at column 78.
+
+The gutter law: the gutter is empty if and only if there is nothing to do.
+A fully healthy report has no glyphs at all -- see `Readout` -- and `+`
+appears only for contrast alongside a failure in the same report, or under
+`--all`.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import textwrap
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------------------
+# Glyphs -- exactly three, ASCII by design (see module docstring on UTF-8).
+# ---------------------------------------------------------------------------
+
+ACT = "!"  # act now -- the root cause; a command exists
+FINE = "+"  # nothing to do
+BLOCKED = "-"  # cannot be done or evaluated until an upstream item resolves
+
+# Rollup severity for grouped checks: "!" > "-" > "+" (higher = worse).
+_SEVERITY = {ACT: 2, BLOCKED: 1, FINE: 0}
+
+# ---------------------------------------------------------------------------
+# Column geometry
+# ---------------------------------------------------------------------------
+
+_GUTTER_WIDTH = 5  # "  " + glyph/space + "  "
+_SUBJECT_WIDTH = 14
+_NARROW_SUBJECT_WIDTH = 1  # below _NARROW_THRESHOLD, drop padding to 1 space
+_NARROW_THRESHOLD = 60
+_DEFAULT_WIDTH = 78
+_ACTION_PROSE_COLUMN = 2
+_ACTION_COMMAND_INDENT = 4  # "+4 from its governing text"
+
+
+def _subject_field(subject: str, width: int) -> str:
+    """The subject column's text, including its trailing separator.
+
+    At normal widths this is `subject` left-justified to 14 columns. Below
+    `_NARROW_THRESHOLD` columns, padding drops to a single separating space
+    instead (the spec's "drop subject padding to a single space") -- the
+    column ladder is no longer aligned at that width, which is expected.
+    """
+    if width < _NARROW_THRESHOLD:
+        return f"{subject} "
+    return subject.ljust(_SUBJECT_WIDTH)
+
+
+# ---------------------------------------------------------------------------
+# UTF-8 glyph substitution -- "+"/"✓" only. "!" and "-" never change: a
+# diagnostic tool must not emit output that can be corrupted by the very
+# environment it is diagnosing, so the ASCII forms are always valid; the
+# checkmark is a cosmetic upgrade applied only when it is safe.
+# ---------------------------------------------------------------------------
+
+
+def utf8_capable(env: dict[str, str] | None = None) -> bool:
+    """Best-effort: can this environment render a UTF-8 checkmark safely?
+
+    Checks LC_ALL, LC_CTYPE, LANG in that order (the standard POSIX locale
+    precedence) for a "UTF-8"/"utf8" marker. Defaults to `os.environ`;
+    callers (and tests) may pass an explicit mapping instead.
+    """
+    source = os.environ if env is None else env
+    for key in ("LC_ALL", "LC_CTYPE", "LANG"):
+        value = source.get(key)
+        if not value:
+            continue
+        normalized = value.lower()
+        if "utf-8" in normalized or "utf8" in normalized:
+            return True
+    return False
+
+
+def _glyph_char(glyph: str, *, utf8: bool) -> str:
+    if glyph == FINE and utf8:
+        return "\u2713"
+    return glyph
+
+
+# ---------------------------------------------------------------------------
+# Data model
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Check:
+    """One line of STATE: a glyph, a subject, and a value."""
+
+    subject: str
+    glyph: str
+    value: str
+
+
+@dataclass
+class Group:
+    """A named cluster of `Check`s that collapses to one line by default.
+
+    Default mode renders `rollup()` (glyph = worst member, value = that
+    member's value). `--all` renders every member instead, under a
+    column-0 group label -- a strict superset, never a different answer.
+    """
+
+    subject: str
+    members: list[Check]
+
+    def rollup(self) -> Check:
+        worst = max(self.members, key=lambda c: _SEVERITY[c.glyph])
+        return Check(subject=self.subject, glyph=worst.glyph, value=worst.value)
+
+
+@dataclass
+class Readout:
+    """One line of STATE with no glyph at all -- the all-fine gutter-empty form."""
+
+    name: str
+    value: str
+
+
+Item = Check | Group
+
+# ---------------------------------------------------------------------------
+# Wrapping -- hard-wrap at column 78 (or the given width), never soft-wrap.
+# Lines that already fit are left byte-for-byte alone (so hand-formatted
+# multi-line guidance blocks with their own bullet indentation survive);
+# only a line that genuinely overflows gets reflowed, and only that line.
+# ---------------------------------------------------------------------------
+
+
+def _wrap_logical_line(line: str, avail: int) -> list[str]:
+    avail = max(10, avail)
+    if len(line) <= avail:
+        return [line]
+    wrapped = textwrap.wrap(
+        line, width=avail, break_long_words=False, break_on_hyphens=False
+    )
+    return wrapped or [""]
+
+
+def _render_value_block(
+    prefix: str, value: str, *, value_column: int, width: int
+) -> str:
+    """Render `prefix` + `value`, wrapping/hanging continuations at `value_column`."""
+    avail = max(10, width - value_column)
+    logical_lines = value.splitlines() or [""]
+    out: list[str] = []
+    first = True
+    for logical in logical_lines:
+        for fragment in _wrap_logical_line(logical, avail):
+            if first:
+                out.append(prefix + fragment)
+                first = False
+            else:
+                out.append(" " * value_column + fragment)
+    return "\n".join(out)
+
+
+def format_check_line(
+    glyph: str, subject: str, value: str, *, utf8: bool, width: int = _DEFAULT_WIDTH
+) -> str:
+    """Render one STATE check line: `  <glyph>  <subject><value>` (+ wraps)."""
+    display_glyph = _glyph_char(glyph, utf8=utf8)
+    prefix = f"  {display_glyph}  {_subject_field(subject, width)}"
+    return _render_value_block(prefix, value, value_column=len(prefix), width=width)
+
+
+def format_readout_line(name: str, value: str, *, width: int = _DEFAULT_WIDTH) -> str:
+    """Render one STATE readout line: gutter left empty (the all-fine form)."""
+    prefix = " " * _GUTTER_WIDTH + _subject_field(name, width)
+    return _render_value_block(prefix, value, value_column=len(prefix), width=width)
+
+
+def group_label(subject: str) -> str:
+    """The `--all`-only column-0 group heading (lowercase, blank line above it)."""
+    return subject.lower()
+
+
+# ---------------------------------------------------------------------------
+# Rendering a list of Check/Group items into STATE lines
+# ---------------------------------------------------------------------------
+
+
+def collapsed_checks(items: list[Item]) -> list[Check]:
+    """Flatten groups to their rollup -- the representation the VERDICT/ACTION
+
+    bands are always computed from, so both bands stay identical between
+    default and `--all` mode (the superset property: only the middle
+    expands).
+    """
+    return [item.rollup() if isinstance(item, Group) else item for item in items]
+
+
+def render_items(
+    items: list[Item], *, show_all: bool, utf8: bool, width: int = _DEFAULT_WIDTH
+) -> list[str]:
+    """Render STATE lines for a list of Check/Group items.
+
+    Default mode: each Group renders as its single rolled-up line. `--all`:
+    each Group expands into a column-0 lowercase label followed by every
+    member as its own check line; ungrouped Checks render identically in
+    both modes (nothing to expand).
+    """
+    lines: list[str] = []
+    need_blank_before_next_group = False
+    for item in items:
+        if isinstance(item, Group):
+            if show_all:
+                if need_blank_before_next_group:
+                    lines.append("")
+                lines.append(group_label(item.subject))
+                for member in item.members:
+                    lines.append(
+                        format_check_line(
+                            member.glyph,
+                            member.subject,
+                            member.value,
+                            utf8=utf8,
+                            width=width,
+                        )
+                    )
+                need_blank_before_next_group = True
+                continue
+            rolled = item.rollup()
+            lines.append(
+                format_check_line(
+                    rolled.glyph, rolled.subject, rolled.value, utf8=utf8, width=width
+                )
+            )
+        else:
+            lines.append(
+                format_check_line(
+                    item.glyph, item.subject, item.value, utf8=utf8, width=width
+                )
+            )
+        need_blank_before_next_group = False
+    return lines
+
+
+def render_readouts(
+    readouts: list[Readout], *, width: int = _DEFAULT_WIDTH
+) -> list[str]:
+    return [format_readout_line(r.name, r.value, width=width) for r in readouts]
+
+
+# ---------------------------------------------------------------------------
+# VERDICT -- counts ACTIONS, not problems.
+# ---------------------------------------------------------------------------
+
+
+def count_actions(glyphs: list[str]) -> int:
+    return sum(1 for g in glyphs if g == ACT)
+
+
+def verdict_readiness(action_count: int, *, note: str | None = None) -> str:
+    """ "Ready."/"Not ready -- N thing(s) to do[, note]." -- the doctor-style verdict."""
+    if action_count <= 0:
+        return "Ready."
+    word = "thing" if action_count == 1 else "things"
+    base = f"Not ready -- {action_count} {word} to do"
+    if note:
+        base = f"{base}, {note}"
+    return base + "."
+
+
+# ---------------------------------------------------------------------------
+# ACTION band
+# ---------------------------------------------------------------------------
+
+
+def prose_lines(text: str, *, width: int = _DEFAULT_WIDTH) -> list[str]:
+    """Prose in ACTION: column 2, wrapped at `width`."""
+    avail = max(10, width - _ACTION_PROSE_COLUMN)
+    out: list[str] = []
+    for logical in text.splitlines() or [text]:
+        out.extend(_wrap_logical_line(logical, avail))
+    return [" " * _ACTION_PROSE_COLUMN + line for line in out]
+
+
+@dataclass
+class Decision:
+    """A single ACTION decision: a contiguous command sequence, plus prose."""
+
+    commands: list[str]
+    prose: str | None = None  # max 2 lines
+
+
+@dataclass
+class Step:
+    """One numbered step of a multi-step, cross-machine ACTION."""
+
+    number: int
+    intro: str  # step body text, e.g. "On Windows, in an Administrator PowerShell:"
+    commands: list[str] = field(default_factory=list)
+    note: str | None = None  # continuation prose specific to this step
+
+
+@dataclass
+class Action:
+    decision: Decision | None = None
+    steps: list[Step] = field(default_factory=list)
+    overflow_note: str | None = None  # e.g. "2 more after this -- rerun doctor."
+
+
+def _render_decision(decision: Decision, *, width: int) -> list[str]:
+    lines: list[str] = []
+    if decision.commands:
+        lines.append("")
+        for cmd in decision.commands:
+            lines.append(" " * _ACTION_COMMAND_INDENT + cmd)
+    if decision.prose:
+        lines.append("")
+        lines.extend(prose_lines(decision.prose, width=width))
+    return lines
+
+
+def _render_step(step: Step, *, width: int) -> list[str]:
+    marker = f"{step.number}. "
+    body_column = _ACTION_PROSE_COLUMN + len(marker)
+    command_column = body_column + _ACTION_COMMAND_INDENT
+    lines = [" " * _ACTION_PROSE_COLUMN + marker + step.intro]
+    if step.commands:
+        lines.append("")
+        for cmd in step.commands:
+            lines.append(" " * command_column + cmd)
+    if step.note:
+        lines.append("")
+        for logical in step.note.splitlines() or [step.note]:
+            lines.append(" " * body_column + logical)
+    return lines
+
+
+def render_action(action: Action, *, width: int = _DEFAULT_WIDTH) -> list[str]:
+    """Render the full ACTION band, including its "Do this:" header line."""
+    lines: list[str] = ["Do this:"]
+    if action.decision is not None:
+        lines.extend(_render_decision(action.decision, width=width))
+    else:
+        for index, step in enumerate(action.steps):
+            if index > 0:
+                lines.append("")
+            lines.extend(_render_step(step, width=width))
+    if action.overflow_note:
+        lines.append("")
+        lines.extend(prose_lines(action.overflow_note, width=width))
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# Top-level assembly
+# ---------------------------------------------------------------------------
+
+
+def render(
+    verdict: str, state_lines: list[str], action_lines: list[str] | None = None
+) -> str:
+    """Assemble VERDICT / STATE / ACTION with exactly one blank-line separator
+
+    between bands and a leading/trailing blank line as the only frame.
+    Returns the full text -- callers should write it verbatim (e.g.
+    `sys.stdout.write(...)`), not `print()` it (which would add a second
+    trailing newline).
+    """
+    lines: list[str] = ["", verdict, "", *state_lines]
+    if action_lines:
+        lines += ["", *action_lines]
+    return "\n".join(lines) + "\n\n"
+
+
+# ---------------------------------------------------------------------------
+# Helper for callers extracting an embedded "run: <command>" suggestion out
+# of an existing check message -- lets ACTION reuse guidance text that
+# already exists in check functions instead of duplicating it.
+# ---------------------------------------------------------------------------
+
+_RUN_COMMAND_RE = re.compile(r"run:\s*(muxplex-deck[^\n.]*)")
+
+
+def extract_run_command(message: str) -> str | None:
+    match = _RUN_COMMAND_RE.search(message)
+    if not match:
+        return None
+    return match.group(1).strip()

{muxplex_deck-0.6.1 → muxplex_deck-0.7.0}/src/muxplex_deck/service.py

@@ -139,19 +139,29 @@ _LAUNCHD_PLIST_TEMPLATE = """\
 </plist>
 """
 
-# Same ✓/! 2-space-indent style as `cli.doctor()`'s `print_check` -- kept as
-# a small local duplicate (rather than importing from `cli.py`) to avoid a
-# circular import: `cli.py` already imports from this module at call time.
-_MARK_OK = "\033[32m\u2713\033[0m"
-_MARK_WARN = "\033[33m!\033[0m"
+
+# Same glyph vocabulary as `report.py` (see that module's docstring): "+"
+# for fine, becoming a UTF-8 checkmark only when the environment can render
+# one. This install/uninstall narration is step-by-step progress output,
+# not a VERDICT/STATE/ACTION report -- it intentionally keeps its own
+# simple 2-space-indent style rather than adopting the full column ladder,
+# but shares the same glyph-substitution rule so the visual language is
+# consistent across `doctor`/`status`/`service`. No ANSI color: plain text
+# only, so this stays byte-identical whether printed to a TTY or piped.
+def _mark_ok() -> str:
+    from . import report
+
+    return report._glyph_char(report.FINE, utf8=report.utf8_capable())
 
 
 def _step_ok(message: str) -> None:
-    print(f"  {_MARK_OK} {message}")
+    print(f"  {_mark_ok()}  {message}")
 
 
 def _step_warn(message: str) -> None:
-    print(f"  {_MARK_WARN} {message}")
+    from . import report
+
+    print(f"  {report.ACT}  {message}")
 
 
 # ---------------------------------------------------------------------------
@@ -256,8 +266,10 @@ def _print_guidance_block(message: str) -> None:
     uses (kept as a small local duplicate here to avoid a circular import
     with `cli.py`).
     """
+    from . import report
+
     for i, line in enumerate(message.splitlines()):
-        prefix = f"  {_MARK_WARN} " if i == 0 else "    "
+        prefix = f"  {report.ACT} " if i == 0 else "    "
         print(f"{prefix}{line}")
 
 

{muxplex_deck-0.6.1 → muxplex_deck-0.7.0}/src/muxplex_deck/statusfile.py

@@ -122,7 +122,7 @@ def build_status(
     `hidhelp.explain_open_failure`), published so `muxplex-deck status`
     can show it instead of a stale/misleading status. Older readers that
     don't know this field simply don't see it (`.get()` is used to read
-    it back -- see `cli._format_device_line`).
+    it back -- see `cli._status_device_item`).
     """
     device: dict[str, Any] = {"connected": device_connected}
     if device_connected and device_caps is not None: