trcc-linux 9.8.7__tar.gz → 9.8.9__tar.gz

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 9.8.7
+Version: 9.8.9
 Summary: Linux implementation of Thermalright LCD Control Center
 Project-URL: Homepage, https://github.com/Lexonight1/thermalright-trcc-linux
 Project-URL: Documentation, https://github.com/Lexonight1/thermalright-trcc-linux#readme
@@ -126,7 +126,7 @@ Description-Content-Type: text/markdown
 
 Native Linux port of the Thermalright LCD Control Center (Windows TRCC 2.1.2). Control and customize the LCD displays and LED segment displays on Thermalright CPU coolers, AIO pump heads, and fan hubs — entirely from Linux.
 
-> **This project wouldn't exist without our testers.** I only own one device. Every supported device in this list works because someone plugged it in, ran `trcc report`, and told me what broke. 32 testers helped us go from "SCSI only" to full C# feature parity with 6 USB protocols, 16 FBL resolutions, and 12 LED styles. Open source at its best — see [Contributors](#contributors) below.
+> **This project wouldn't exist without our testers.** I only own one device. Every supported device in this list works because someone plugged it in, ran `trcc report`, and told me what broke. 32 testers helped us go from "SCSI only" to full C# feature parity with 6 USB protocols, 16 FBL resolutions, and 13 LED styles. Open source at its best — see [Contributors](#contributors) below.
 
 > Unofficial community project, not affiliated with Thermalright. Built with [Claude](https://claude.ai) (AI) for protocol reverse engineering and code generation, guided by human architecture decisions and logical assessment.
 
@@ -306,7 +306,7 @@ Set the angle to **90°** (or 270°) in the GUI, then open **Cloud Themes** —
 | **Media** | Video/GIF playback on LCD, video trimmer, image cropper, screen cast (X11 + Wayland), mic audio visualization |
 | **Overlay Editor** | Text, sensors, date/time overlays — font picker, dynamic scaling, color picker |
 | **Hardware Sensors** | 77+ sensors — CPU/GPU temp, fan speed, power, usage — customizable dashboard |
-| **LED Control** | 12 LED styles, zone carousel, breathing/rainbow/static/wave modes, per-zone color |
+| **LED Control** | 13 LED styles, zone carousel, breathing/rainbow/static/wave modes, per-zone color |
 | **Display** | 16 resolutions (240x240 to 1920x462), 0/90/180/270 rotation, 3 brightness levels |
 | **Multi-device** | Per-device config, auto-detect, multi-device with device selection |
 | **Security** | udev rules, polkit policy, SELinux support, no root required after setup |
@@ -364,7 +364,7 @@ Run `lsusb` to find your USB ID (`xxxx:xxxx` after `ID`), then match it below.
 **HID LED devices** — RGB LED control:
 | USB ID | Devices |
 |--------|---------|
-| `0416:8001` | AX120 DIGITAL, PA120 DIGITAL, Peerless Assassin 120 DIGITAL ARGB White, Assassin X 120R Digital ARGB, Phantom Spirit 120 Digital EVO, HR10 2280 PRO Digital, and others (model auto-detected via handshake) |
+| `0416:8001` | AX120 DIGITAL, PA120 DIGITAL, Peerless Assassin 120 DIGITAL ARGB White, Assassin X 120R Digital ARGB, Phantom Spirit 120 Digital EVO, HR10 2280 PRO Digital, Magic Qube, and others (model auto-detected via handshake) |
 
 > See the [full device list with protocol details](doc/REFERENCE_DEVICES.md) and the [Device Testing Guide](doc/GUIDE_DEVICE_TESTING.md) if you have an untested device.
 
@@ -409,20 +409,21 @@ If a probe goes `BAD`, that's the bug — fix in `src/`, re-run, see `PASS`. Eve
 | HID Type 3 | pyusb interrupt | TARAN ARMS |
 | Bulk | pyusb bulk | GrandVision 360, Mjolnir Vision 360, Wonder Vision Pro 360, Frozen Warframe Pro |
 | LY | pyusb bulk (chunked) | Trofeo Vision 9.16 LCD |
-| LED | pyusb HID | All LED segment display devices (12 styles) |
+| LED | pyusb HID | All LED segment display devices (13 styles) |
 
 ## Code Contributors
 
 These folks didn't just report a problem — they opened the editor and sent a fix. On a solo project, a merged pull request is about the most generous thing you can do, and every one of these shipped to every user:
 
+- **[@jphilipb](https://github.com/jphilipb)** — [#215](https://github.com/Lexonight1/thermalright-trcc-linux/pull/215): reverse-engineered and hardware-validated the Thermalright Magic Qube (65-LED segment display) — a device that doesn't even exist in the Windows app — and wired up full support from scratch.
 - **[@Hythera](https://github.com/Hythera)** — [#209](https://github.com/Lexonight1/thermalright-trcc-linux/pull/209): had the flake read its version straight from `pyproject.toml`, killing an entire place I used to have to bump by hand every release.
 - **[@elsiedotcafe](https://github.com/elsiedotcafe)** — [#123](https://github.com/Lexonight1/thermalright-trcc-linux/pull/123): pinned the PySide6 package to a stable source so the build stops breaking.
 
-Thank you both — genuinely. PRs are always welcome, and you'll land right here.
+Thank you all — genuinely. PRs are always welcome, and you'll land right here.
 
 ## Contributors
 
-A huge thank you to every single person who filed an issue, pasted a `trcc report`, or just said "it doesn't work." You are the reason this project supports 6 USB protocols, 16 resolutions, and 12 LED styles from a single developer with one device. Every bug report, every test on hardware I don't own, every "hey this is broken" — that's open source at its best. You're not wasting your time. You're building something together.
+A huge thank you to every single person who filed an issue, pasted a `trcc report`, or just said "it doesn't work." You are the reason this project supports 6 USB protocols, 16 resolutions, and 13 LED styles from a single developer with one device. Every bug report, every test on hardware I don't own, every "hey this is broken" — that's open source at its best. You're not wasting your time. You're building something together.
 
 Special thanks to everyone who has contributed invaluable reports to this project:
 

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/README.md

@@ -53,7 +53,7 @@
 
 Native Linux port of the Thermalright LCD Control Center (Windows TRCC 2.1.2). Control and customize the LCD displays and LED segment displays on Thermalright CPU coolers, AIO pump heads, and fan hubs — entirely from Linux.
 
-> **This project wouldn't exist without our testers.** I only own one device. Every supported device in this list works because someone plugged it in, ran `trcc report`, and told me what broke. 32 testers helped us go from "SCSI only" to full C# feature parity with 6 USB protocols, 16 FBL resolutions, and 12 LED styles. Open source at its best — see [Contributors](#contributors) below.
+> **This project wouldn't exist without our testers.** I only own one device. Every supported device in this list works because someone plugged it in, ran `trcc report`, and told me what broke. 32 testers helped us go from "SCSI only" to full C# feature parity with 6 USB protocols, 16 FBL resolutions, and 13 LED styles. Open source at its best — see [Contributors](#contributors) below.
 
 > Unofficial community project, not affiliated with Thermalright. Built with [Claude](https://claude.ai) (AI) for protocol reverse engineering and code generation, guided by human architecture decisions and logical assessment.
 
@@ -233,7 +233,7 @@ Set the angle to **90°** (or 270°) in the GUI, then open **Cloud Themes** —
 | **Media** | Video/GIF playback on LCD, video trimmer, image cropper, screen cast (X11 + Wayland), mic audio visualization |
 | **Overlay Editor** | Text, sensors, date/time overlays — font picker, dynamic scaling, color picker |
 | **Hardware Sensors** | 77+ sensors — CPU/GPU temp, fan speed, power, usage — customizable dashboard |
-| **LED Control** | 12 LED styles, zone carousel, breathing/rainbow/static/wave modes, per-zone color |
+| **LED Control** | 13 LED styles, zone carousel, breathing/rainbow/static/wave modes, per-zone color |
 | **Display** | 16 resolutions (240x240 to 1920x462), 0/90/180/270 rotation, 3 brightness levels |
 | **Multi-device** | Per-device config, auto-detect, multi-device with device selection |
 | **Security** | udev rules, polkit policy, SELinux support, no root required after setup |
@@ -291,7 +291,7 @@ Run `lsusb` to find your USB ID (`xxxx:xxxx` after `ID`), then match it below.
 **HID LED devices** — RGB LED control:
 | USB ID | Devices |
 |--------|---------|
-| `0416:8001` | AX120 DIGITAL, PA120 DIGITAL, Peerless Assassin 120 DIGITAL ARGB White, Assassin X 120R Digital ARGB, Phantom Spirit 120 Digital EVO, HR10 2280 PRO Digital, and others (model auto-detected via handshake) |
+| `0416:8001` | AX120 DIGITAL, PA120 DIGITAL, Peerless Assassin 120 DIGITAL ARGB White, Assassin X 120R Digital ARGB, Phantom Spirit 120 Digital EVO, HR10 2280 PRO Digital, Magic Qube, and others (model auto-detected via handshake) |
 
 > See the [full device list with protocol details](doc/REFERENCE_DEVICES.md) and the [Device Testing Guide](doc/GUIDE_DEVICE_TESTING.md) if you have an untested device.
 
@@ -336,20 +336,21 @@ If a probe goes `BAD`, that's the bug — fix in `src/`, re-run, see `PASS`. Eve
 | HID Type 3 | pyusb interrupt | TARAN ARMS |
 | Bulk | pyusb bulk | GrandVision 360, Mjolnir Vision 360, Wonder Vision Pro 360, Frozen Warframe Pro |
 | LY | pyusb bulk (chunked) | Trofeo Vision 9.16 LCD |
-| LED | pyusb HID | All LED segment display devices (12 styles) |
+| LED | pyusb HID | All LED segment display devices (13 styles) |
 
 ## Code Contributors
 
 These folks didn't just report a problem — they opened the editor and sent a fix. On a solo project, a merged pull request is about the most generous thing you can do, and every one of these shipped to every user:
 
+- **[@jphilipb](https://github.com/jphilipb)** — [#215](https://github.com/Lexonight1/thermalright-trcc-linux/pull/215): reverse-engineered and hardware-validated the Thermalright Magic Qube (65-LED segment display) — a device that doesn't even exist in the Windows app — and wired up full support from scratch.
 - **[@Hythera](https://github.com/Hythera)** — [#209](https://github.com/Lexonight1/thermalright-trcc-linux/pull/209): had the flake read its version straight from `pyproject.toml`, killing an entire place I used to have to bump by hand every release.
 - **[@elsiedotcafe](https://github.com/elsiedotcafe)** — [#123](https://github.com/Lexonight1/thermalright-trcc-linux/pull/123): pinned the PySide6 package to a stable source so the build stops breaking.
 
-Thank you both — genuinely. PRs are always welcome, and you'll land right here.
+Thank you all — genuinely. PRs are always welcome, and you'll land right here.
 
 ## Contributors
 
-A huge thank you to every single person who filed an issue, pasted a `trcc report`, or just said "it doesn't work." You are the reason this project supports 6 USB protocols, 16 resolutions, and 12 LED styles from a single developer with one device. Every bug report, every test on hardware I don't own, every "hey this is broken" — that's open source at its best. You're not wasting your time. You're building something together.
+A huge thank you to every single person who filed an issue, pasted a `trcc report`, or just said "it doesn't work." You are the reason this project supports 6 USB protocols, 16 resolutions, and 13 LED styles from a single developer with one device. Every bug report, every test on hardware I don't own, every "hey this is broken" — that's open source at its best. You're not wasting your time. You're building something together.
 
 Special thanks to everyone who has contributed invaluable reports to this project:
 

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trcc-linux"
-version = "9.8.7"
+version = "9.8.9"
 description = "Linux implementation of Thermalright LCD Control Center"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/src/trcc/__version__.py

@@ -1,4 +1,4 @@
 """TRCC Linux version information. History in doc/CHANGELOG.md."""
 
-__version__ = "9.8.7"
+__version__ = "9.8.9"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/src/trcc/adapters/device/led.py

@@ -26,7 +26,13 @@ from ...core.errors import (
     UnsupportedOperationError,
 )
 from ...core.led_models import LedPayload
-from ...core.led_protocol import remap_led_colors, resolve_pm
+from ...core.led_protocol import (
+    is_fingerprint_header,
+    remap_led_colors,
+    resolve_handshake,
+    resolve_model_name,
+    resolve_pm,
+)
 from ...core.models import HandshakeResult, LedHandshakeResult, ProductInfo, Wire
 from ...core.ports import BulkTransport, Device
 from . import DeviceFactory
@@ -206,11 +212,15 @@ class Led(Device[BulkTransport]):
                     time.sleep(_HANDSHAKE_RETRY_DELAY_S)
                     continue
 
-                # Windows DeviceDataReceived1 doesn't validate magic/cmd —
-                # we warn on mismatch but accept.
-                if resp[0:4] != _MAGIC:
-                    log.warning("Led handshake: unexpected magic %s", resp[0:4].hex())
-                if len(resp) > 12 and resp[12] != 1:
+                # Windows DeviceDataReceived1 doesn't validate magic/cmd — we
+                # accept regardless.  A recognised fingerprint header (e.g. the
+                # Magic Qube's DC DD AA 01) is expected, so only warn on a truly
+                # unknown magic / cmd byte.
+                header = bytes(resp[0:4])
+                recognised = is_fingerprint_header(header)
+                if header != _MAGIC and not recognised:
+                    log.warning("Led handshake: unexpected magic %s", header.hex())
+                if len(resp) > 12 and resp[12] != 1 and not recognised:
                     log.warning("Led handshake: unexpected cmd byte %d", resp[12])
 
                 # PM and SUB extraction — matches Windows UCDevice.cs offsets:
@@ -218,10 +228,13 @@ class Led(Device[BulkTransport]):
                 self._pm = resp[5]
                 self._sub = resp[4]
 
-                # PM byte → device style + readable model name. Falls back to
-                # the registry's ``led_style`` / ``product`` when the firmware
-                # reports a PM not in PmRegistry (e.g. a new SKU).
-                entry = resolve_pm(self._pm, self._sub)
+                # Handshake → device style + readable model name.  The header
+                # fingerprint wins first (some SKUs reuse a PM byte but ship a
+                # distinct handshake header — e.g. the Magic Qube shares PM=208
+                # with CZ1 but answers with DC DD AA 01), then the PM registry.
+                # Falls back to the registry's ``led_style`` / ``product`` when
+                # the firmware reports a PM not in PmRegistry (e.g. a new SKU).
+                entry = resolve_handshake(header, self._pm, self._sub)
                 if entry is not None:
                     style = entry.style
                     model_name = entry.model_name
@@ -278,7 +291,10 @@ class Led(Device[BulkTransport]):
         cached = _probe_cache_load(self.info.vid, self.info.pid)
         if cached is not None:
             cpm, csub, cname = cached
-            entry = resolve_pm(cpm, csub)
+            # A fingerprint device (e.g. Magic Qube) shares its PM byte with
+            # another product, so recover it by cached model name first — the
+            # cache doesn't persist the handshake header — then by PM byte.
+            entry = resolve_model_name(cname) or resolve_pm(cpm, csub)
             log.warning(
                 "Led handshake: live failed after %d retries — using "
                 "disk cache (PM=%d SUB=%d model=%s, last_err=%s)",

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/src/trcc/adapters/diagnostics/debug_report.py

@@ -35,6 +35,7 @@ from ...core.registry import find_product
 from ..device import DeviceFactory
 from ..infra.logging import tail_log
 from .health import HealthReport, run_health_checks
+from .install import InstallInfo, collect_install_info
 
 log = logging.getLogger(__name__)
 
@@ -50,6 +51,7 @@ class DebugReport:
     timestamp: str
     platform_info: dict[str, str]
     paths: dict[str, str]
+    install: InstallInfo | None = None
     devices: list[dict[str, str]] = field(default_factory=list)
     devices_error: str = ""
     sensors: list[dict[str, str]] = field(default_factory=list)
@@ -66,6 +68,9 @@ class DebugReport:
         log.info("render_text: called")
         sections: list[str] = []
         sections.append(_header(self.timestamp))
+        # Install first: every other section is worthless if this is not the
+        # trcc the reporter thinks they are running.
+        sections.append(_render_install(self.install))
         sections.append(_render_kv("Platform", self.platform_info))
         sections.append(_render_kv("Paths", self.paths))
         sections.append(_render_devices(self.devices, self.devices_error))
@@ -96,6 +101,15 @@ def build_debug_report(
              log_tail_lines)
     timestamp = datetime.now(tz=timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
 
+    # Best-effort like every other collector: a report from a broken install is
+    # exactly when this matters, so it must degrade to "(unavailable)" rather
+    # than abort the report that would have explained the breakage.
+    try:
+        install = collect_install_info()
+    except Exception as e:
+        log.exception("build_debug_report: install info failed: %s", e)
+        install = None
+
     info = _collect_platform_info(platform)
     path_table = _collect_paths(platform)
     devices, devices_err = _collect_devices(platform)
@@ -113,6 +127,7 @@ def build_debug_report(
         timestamp=timestamp,
         platform_info=info,
         paths=path_table,
+        install=install,
         devices=devices,
         devices_error=devices_err,
         sensors=sensors,
@@ -141,11 +156,10 @@ def write_debug_report(report: DebugReport, output_path: Path) -> Path:
 
 def _collect_platform_info(platform: Platform) -> dict[str, str]:
     log.debug("_collect_platform_info: called")
+    # Version / path / installer live in the Install section, which owns the
+    # "which trcc is this?" question in one place — see _render_install.
     return {
         "distro": platform.distro_name(),
-        "install_method": platform.install_method(),
-        "python": f"{sys.version_info.major}.{sys.version_info.minor}."
-                  f"{sys.version_info.micro}",
         "python_impl": py_platform.python_implementation(),
         "machine": py_platform.machine(),
         "system": py_platform.system(),
@@ -375,6 +389,42 @@ def _render_kv(title: str, table: dict[str, str]) -> str:
     return f"## {title}\n{body}" if body else f"## {title}\n  (empty)"
 
 
+def _render_install(info: InstallInfo | None) -> str:
+    """Which trcc is running — and loud warnings when it isn't the expected one.
+
+    The warnings are spelled out in full because the reporter reading them is
+    the person who has to act, and neither of the two failures is guessable
+    from the outside: a stale cache and a duplicate binary both present as
+    "I upgraded and nothing changed".
+    """
+    if info is None:
+        return "## Install\n  (unavailable)"
+    rows = {
+        "version": info.version,
+        "installed_by": info.installer,
+        "module_path": str(info.module_path or "unknown"),
+        "interpreter": info.interpreter,
+        "python": info.python,
+    }
+    lines = [f"  {k:18}  {v}" for k, v in rows.items()]
+    for exe in info.executables:
+        lines.append(f"  {'on PATH':18}  {exe.path}  ->  {exe.interpreter}")
+    if info.bytecode_stale:
+        lines.append("")
+        lines.append(f"  !! STALE BYTECODE — running {info.version} but the source "
+                     f"says {info.source_version}.")
+        lines.append("  !! Python is serving a cached .pyc that no longer matches "
+                     "the code on disk.")
+        lines.append("  !! Fix: delete __pycache__ dirs, or reinstall.")
+    if info.duplicates:
+        lines.append("")
+        lines.append(f"  !! {len(info.executables)} trcc found on PATH — an upgrade "
+                     "may land on one")
+        lines.append("  !! while a different one keeps running. The first listed "
+                     "above is what runs.")
+    return "## Install\n" + "\n".join(lines)
+
+
 def _render_devices(rows: list[dict[str, str]], error: str) -> str:
     if error:
         return f"## Devices\n  Scan failed: {error}"

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/src/trcc/adapters/diagnostics/health.py

@@ -11,9 +11,9 @@ Severity ladder:
   * ``WARN`` — works on this machine but reporter should know.
   * ``FAIL`` — feature won't work until this is fixed.
 
-Adding a check: define a function returning ``HealthCheckResult`` and
-add it to ``ALL_CHECKS``.  The doctor + report bundlers iterate that
-tuple, so registration = inclusion.
+Adding a check: define a function returning ``HealthCheckResult`` and add
+it to the list in ``run_health_checks``.  The doctor + report bundlers both
+go through that function, so registration = inclusion.
 """
 from __future__ import annotations
 
@@ -26,6 +26,7 @@ from pathlib import Path
 from ...core.diagnostics import HealthCheckResult, HealthReport, Severity
 from ...core.ports import Paths, Platform
 from ..sensors.nvml import NVML_RELOAD_HINT, nvml_init_state
+from .install import collect_install_info
 
 log = logging.getLogger(__name__)
 
@@ -48,6 +49,57 @@ __all__ = [
 # =========================================================================
 
 
+def check_install_integrity() -> HealthCheckResult:
+    """Is the running trcc the one the user thinks they installed?
+
+    Two failures both present to the user as "I upgraded and nothing
+    changed", and neither is visible from the outside:
+
+    * stale bytecode — Python serves a cached .pyc whose recorded mtime+size
+      still match a since-edited source (FAIL: every other diagnostic, and
+      the version itself, is then untrustworthy);
+    * duplicate binaries on PATH — the upgrade landed on one, the other keeps
+      running (WARN: legitimate for venv/pipx users, so not fatal).
+    """
+    log.info("check_install_integrity: called")
+    try:
+        info = collect_install_info()
+    except Exception as e:
+        log.exception("check_install_integrity: collection failed: %s", e)
+        return HealthCheckResult(
+            name="install-integrity", severity="WARN",
+            message=f"Could not inspect the install: {e}",
+        )
+    if info.bytecode_stale:
+        return HealthCheckResult(
+            name="install-integrity", severity="FAIL",
+            message=(
+                f"Stale bytecode — running {info.version} but "
+                f"{info.module_path} says {info.source_version}"
+            ),
+            fix_hint=(
+                "Python is serving a cached .pyc that no longer matches the "
+                "source. Delete the __pycache__ directories under "
+                f"{info.module_path}, or reinstall trcc-linux."
+            ),
+        )
+    if info.duplicates:
+        found = ", ".join(str(e.path) for e in info.executables)
+        return HealthCheckResult(
+            name="install-integrity", severity="WARN",
+            message=f"{len(info.executables)} trcc on PATH: {found}",
+            fix_hint=(
+                f"'{info.executables[0].path}' is the one that runs. An "
+                "upgrade applied to the other will appear to do nothing. "
+                "Remove whichever you don't want."
+            ),
+        )
+    return HealthCheckResult(
+        name="install-integrity", severity="OK",
+        message=f"{info.version} via {info.installer} ({info.interpreter})",
+    )
+
+
 def check_python_version(platform: Platform) -> HealthCheckResult:
     """Python ≥ 3.11 is the project minimum (match-statement + slots)."""
     log.info("check_python_version: called")
@@ -301,6 +353,9 @@ def run_health_checks(platform: Platform) -> HealthReport:
     log.info("run_health_checks: starting")
     paths = platform.paths()
     checks: list[HealthCheckResult] = [
+        # First: if this isn't the trcc they think it is, nothing below means
+        # anything.
+        check_install_integrity(),
         check_python_version(platform),
         check_log_writable(paths),
         check_config_writable(paths),

trcc_linux-9.8.9/src/trcc/adapters/diagnostics/install.py

@@ -0,0 +1,206 @@
+"""Install integrity — which trcc is actually running, and is it the one
+the user thinks?
+
+Every field here exists because a real issue was unanswerable without it:
+
+* **version / source_version / bytecode_stale** — a stale ``.pyc`` served
+  ``9.9.9`` from a file that read ``9.8.8``.  Python's timestamp check
+  compares source mtime+size against the values baked into the ``.pyc``;
+  a rewrite that preserves both (same-length version strings do) leaves
+  the cache authoritative and wrong, silently, forever.
+* **executables / duplicates** — ``shutil.which`` returns the FIRST match.
+  Two ``trcc`` on PATH pointing at two interpreters is the commonest cause
+  of "I upgraded and nothing changed" (#175: six weeks on v9.7.0 while
+  installing 9.8.3 repeatedly; #220: three releases behind on "latest").
+* **installer** — the ``INSTALLER`` file pip writes is the only honest
+  answer.  The old per-OS heuristics guessed from PATH and were wrong for
+  rpm / deb / venv / source checkouts alike.
+
+Deliberately dependency-free (stdlib only) and side-effect-free: it is the
+first thing a broken install runs, so it must not need a working App.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# `__version__ = "9.8.8"` — matched against the SOURCE text, never exec'd.
+_VERSION_RE = re.compile(r"""^__version__\s*=\s*['"]([^'"]+)['"]""", re.MULTILINE)
+
+_UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class Executable:
+    """One ``trcc`` found on PATH, and the interpreter it runs under."""
+
+    path: Path
+    interpreter: str = _UNKNOWN
+
+
+@dataclass(frozen=True, slots=True)
+class InstallInfo:
+    """Everything needed to answer "which trcc is this?"."""
+
+    version: str
+    source_version: str
+    module_path: Path | None
+    interpreter: str
+    python: str
+    installer: str
+    executables: tuple[Executable, ...] = ()
+
+    @property
+    def bytecode_stale(self) -> bool:
+        """Imported version disagrees with its own source file.
+
+        Means Python is serving a cached ``.pyc`` that no longer matches
+        the code on disk — so every claim about "what version is this" is
+        untrustworthy until the cache is cleared.
+        """
+        return (
+            self.source_version != _UNKNOWN
+            and self.version != self.source_version
+        )
+
+    @property
+    def duplicates(self) -> bool:
+        """More than one ``trcc`` on PATH — an upgrade can land on either."""
+        return len(self.executables) > 1
+
+    @property
+    def healthy(self) -> bool:
+        return not self.bytecode_stale and not self.duplicates
+
+
+def _read_source_version(module_path: Path | None) -> str:
+    """Parse ``__version__`` out of the package's own ``__version__.py``.
+
+    Text-parsed rather than imported: importing would hit the very bytecode
+    cache we are trying to check, and would always agree with itself.
+    """
+    if module_path is None:
+        return _UNKNOWN
+    source = module_path / "__version__.py"
+    try:
+        text = source.read_text(encoding="utf-8")
+    except OSError as e:
+        log.debug("_read_source_version: cannot read %s: %s", source, e)
+        return _UNKNOWN
+    m = _VERSION_RE.search(text)
+    if m is None:
+        log.warning("_read_source_version: no __version__ assignment in %s", source)
+        return _UNKNOWN
+    log.debug("_read_source_version: %s → %s", source, m.group(1))
+    return m.group(1)
+
+
+def _shebang_interpreter(path: Path) -> str:
+    """The interpreter a console script runs under, from its shebang."""
+    try:
+        with path.open("rb") as fh:
+            first = fh.readline(256)
+    except OSError as e:
+        log.debug("_shebang_interpreter: cannot read %s: %s", path, e)
+        return _UNKNOWN
+    if not first.startswith(b"#!"):
+        return _UNKNOWN
+    return first[2:].decode("utf-8", "replace").strip()
+
+
+def _find_executables(name: str = "trcc") -> tuple[Executable, ...]:
+    """Every ``name`` on PATH — not just the first.
+
+    ``shutil.which`` stops at the first hit, which is precisely what hides a
+    duplicate install from the person trying to debug one.
+    """
+    exts = [""]
+    if os.name == "nt":
+        exts = [e.lower() for e in os.environ.get("PATHEXT", ".EXE").split(os.pathsep)]
+    found: list[Executable] = []
+    seen: set[Path] = set()
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if not entry:
+            continue
+        for ext in exts:
+            candidate = Path(entry) / f"{name}{ext}"
+            try:
+                resolved = candidate.resolve()
+                usable = candidate.is_file() and os.access(candidate, os.X_OK)
+            except OSError:
+                continue
+            if not usable or resolved in seen:
+                continue
+            seen.add(resolved)
+            found.append(Executable(candidate, _shebang_interpreter(candidate)))
+    log.debug("_find_executables: %d %r on PATH", len(found), name)
+    return tuple(found)
+
+
+def detect_installer() -> str:
+    """How this package got here — ``INSTALLER`` metadata over guesswork.
+
+    Supersedes the per-OS "is trcc on PATH? then pip" heuristics, which
+    answered "pip" for rpm, deb, venv and source checkouts alike.
+    """
+    if getattr(sys, "frozen", False):
+        return "pyinstaller"
+    if "pipx" in sys.prefix:
+        return "pipx"
+    try:
+        from importlib.metadata import PackageNotFoundError, distribution
+        try:
+            installer = (distribution("trcc-linux").read_text("INSTALLER") or "").strip()
+        except PackageNotFoundError:
+            log.debug("detect_installer: trcc-linux has no distribution metadata")
+            return "source"
+    except (OSError, ImportError) as e:
+        log.debug("detect_installer: metadata unavailable: %s", e)
+        return _UNKNOWN
+    if installer:
+        log.debug("detect_installer: INSTALLER=%s", installer)
+        return installer
+    # Installed as a distribution but nobody claimed it — a distro package
+    # manager (rpm/deb/pacman) drops the dist-info without an INSTALLER file.
+    return "package"
+
+
+def collect_install_info() -> InstallInfo:
+    """Gather the running install's identity.  Never raises."""
+    log.info("collect_install_info: called")
+    import trcc
+
+    module_file = getattr(trcc, "__file__", None)
+    module_path = Path(module_file).parent if module_file else None
+    info = InstallInfo(
+        version=trcc.__version__,
+        source_version=_read_source_version(module_path),
+        module_path=module_path,
+        interpreter=sys.executable,
+        python=f"{sys.version_info.major}.{sys.version_info.minor}."
+               f"{sys.version_info.micro}",
+        installer=detect_installer(),
+        executables=_find_executables(),
+    )
+    if info.bytecode_stale:
+        log.warning(
+            "collect_install_info: STALE BYTECODE — imported %s but %s says %s; "
+            "clear __pycache__",
+            info.version, module_path, info.source_version,
+        )
+    if info.duplicates:
+        log.warning(
+            "collect_install_info: %d trcc on PATH (%s) — an upgrade may land "
+            "on one and leave the other running",
+            len(info.executables),
+            ", ".join(str(e.path) for e in info.executables),
+        )
+    log.info("collect_install_info: %s via %s (%s)",
+             info.version, info.installer, info.interpreter)
+    return info

{trcc_linux-9.8.7 → trcc_linux-9.8.9}/src/trcc/adapters/system/bsd.py

@@ -179,11 +179,18 @@ class BSDPlatform(Platform):
         return "FreeBSD" if "freebsd" in sys.platform else "BSD"
 
     def install_method(self) -> str:
-        log.info("install_method: called")
-        import sys
-        if getattr(sys, "frozen", False):
-            return "pyinstaller"
-        return "source"
+        """How this package got here — delegated to the one honest detector.
+
+        Was a per-OS guess: this returned "source" for every pip install
+        (and Linux returned "pip" whenever `trcc` was merely on PATH, so
+        rpm/deb/venv/source checkouts all reported "pip"). The reading of
+        `INSTALLER` metadata is OS-agnostic, so there is nothing per-OS to
+        implement — see adapters/diagnostics/install.detect_installer.
+        """
+        from ..diagnostics.install import detect_installer
+        method = detect_installer()
+        log.info("install_method: %s", method)
+        return method
 
     # ── Per-OS diagnostic hints (pkg) ─────────────────────────────────