driverclient 0.2.0__tar.gz → 0.2.2__tar.gz

{driverclient-0.2.0 → driverclient-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: driverclient
-Version: 0.2.0
+Version: 0.2.2
 Summary: Driver Server client with an embeddable connector for config injection at runtime.
 Project-URL: Homepage, https://example.com/driverclient
 Author-email: Raja Sanaullah <sanaullah@99technologies.com>
@@ -110,6 +110,32 @@ Each `ClientEvent` (frozen dataclass, `ev.to_dict()` for transport) has:
 `phase` and `status` are a fixed, documented vocabulary — this is the interface
 a GUI binds to; treat changes to it as an API change.
 
+#### Reboots (the client does not reboot — the caller decides)
+
+The client is **stateless and single-shot**: it installs/captures in one pass and
+returns. It never reboots and keeps no state across reboots. When a driver
+installs but needs a reboot to take effect (installer exit code `3010`/`1641`),
+that is reported as **success with a reboot flag**, not a failure:
+
+- `InstallResult.reboot_required` / `AutomateResult.reboot_required` → `bool`
+- the per-driver `install` event carries `data["reboot_required"]`
+
+The embedding app owns the reboot + resume loop. Typical convergence:
+
+```python
+result = client.run("automate", on_event=cb)
+if result.reboot_required:
+    persist_state(); schedule_resume(); reboot()      # then run "automate" again
+elif not result.made_progress:
+    proceed_to_next_step()                             # nothing new + no reboot = converged
+```
+
+`AutomateResult.made_progress` is `True` when the pass installed or captured
+anything, so `not made_progress and not reboot_required` means the machine has
+converged. Drivers for devices that only appear *after* a reboot are picked up on
+the next pass; run a `capture-missing` / `wu-full` pass post-reboot to catch
+packages Windows Update only stages during the reboot.
+
 > Events are emitted on whatever thread the op is running on — and the parallel
 > download/export/upload pools mean some events arrive on **worker threads**. The
 > Qt pattern below (queued cross-thread signals) is safe regardless.

{driverclient-0.2.0 → driverclient-0.2.2}/README.md

@@ -94,6 +94,32 @@ Each `ClientEvent` (frozen dataclass, `ev.to_dict()` for transport) has:
 `phase` and `status` are a fixed, documented vocabulary — this is the interface
 a GUI binds to; treat changes to it as an API change.
 
+#### Reboots (the client does not reboot — the caller decides)
+
+The client is **stateless and single-shot**: it installs/captures in one pass and
+returns. It never reboots and keeps no state across reboots. When a driver
+installs but needs a reboot to take effect (installer exit code `3010`/`1641`),
+that is reported as **success with a reboot flag**, not a failure:
+
+- `InstallResult.reboot_required` / `AutomateResult.reboot_required` → `bool`
+- the per-driver `install` event carries `data["reboot_required"]`
+
+The embedding app owns the reboot + resume loop. Typical convergence:
+
+```python
+result = client.run("automate", on_event=cb)
+if result.reboot_required:
+    persist_state(); schedule_resume(); reboot()      # then run "automate" again
+elif not result.made_progress:
+    proceed_to_next_step()                             # nothing new + no reboot = converged
+```
+
+`AutomateResult.made_progress` is `True` when the pass installed or captured
+anything, so `not made_progress and not reboot_required` means the machine has
+converged. Drivers for devices that only appear *after* a reboot are picked up on
+the next pass; run a `capture-missing` / `wu-full` pass post-reboot to catch
+packages Windows Update only stages during the reboot.
+
 > Events are emitted on whatever thread the op is running on — and the parallel
 > download/export/upload pools mean some events arrive on **worker threads**. The
 > Qt pattern below (queued cross-thread signals) is safe regardless.

{driverclient-0.2.0 → driverclient-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "driverclient"
-version = "0.2.0"
+version = "0.2.2"
 description = "Driver Server client with an embeddable connector for config injection at runtime."
 readme = "README.md"
 requires-python = ">=3.10"

{driverclient-0.2.0 → driverclient-0.2.2}/src/driverclient/__init__.py

@@ -25,7 +25,7 @@ from driverclient.main import run as _run
 
 __all__ = ["DriverClient", "ClientEvent"]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 
 class DriverClient:

{driverclient-0.2.0 → driverclient-0.2.2}/src/driverclient/ops/automate.py

@@ -32,6 +32,22 @@ class AutomateResult:
     wu:              CaptureResult | None = None
     duration_s:      int           = 0
 
+    @property
+    def reboot_required(self) -> bool:
+        """True if this pass installed a driver that needs a reboot to take effect."""
+        return bool(self.install and self.install.reboot_required)
+
+    @property
+    def made_progress(self) -> bool:
+        """
+        True if this pass installed and/or captured anything. When this is
+        False and reboot_required is False, the machine has converged — the
+        caller can stop looping and move to the next step.
+        """
+        installed = self.install.ok_count if self.install else 0
+        captured  = self.wu.submitted if self.wu else 0
+        return bool(installed or captured)
+
 
 def run_automation() -> AutomateResult:
     cfg    = get()
@@ -106,6 +122,9 @@ def _summary(r: AutomateResult) -> None:
     events.done("done", f"  Duration : {r.duration_s}s", duration_s=r.duration_s)
     events.done("done", f"  Installed: {inst.ok_count} ok  {inst.fail_count} failed",
                 installed_ok=inst.ok_count, installed_failed=inst.fail_count)
+    if inst.reboot_required:
+        events.done("done", "  Reboot   : REQUIRED (a driver needs a reboot to take effect)",
+                    reboot_required=True)
     if r.wu and r.wu.wu_triggered:
         events.done("done",
                     f"  WU       : {wu.submitted} captured  {wu.still_missing} still missing",

{driverclient-0.2.0 → driverclient-0.2.2}/src/driverclient/ops/capture.py

@@ -345,15 +345,36 @@ def _enumerate_packages_since(cutoff: datetime, cfg: dict) -> list[dict]:
     return result
 
 
+def _norm_hwid(hwid: str) -> str:
+    """Normalize an HWID for comparison: uppercase and strip the &REV_* tail.
+
+    The repo's `not_found` list carries the stripped HWID variants
+    (e.g. PCI\\VEN_8086&DEV_9D15&SUBSYS_222C17AA) while the IDs reported by the
+    live machine — both `installed_versions` keys and pnputil /enum-devices —
+    carry a &REV_xx suffix. Comparing the two forms verbatim never matches, so
+    both sides are normalized to the same REV-less, uppercase form.
+    """
+    up  = hwid.upper()
+    idx = up.find("&REV_")
+    return up[:idx] if idx != -1 else up
+
+
 def _find_installed_packages_for_hwids(
     not_found_hwids: set[str],
     scan_result: ScanResult,
     cfg: dict,
 ) -> list[dict]:
-    locally_installed = {
-        hwid for hwid in not_found_hwids
-        if hwid in scan_result.installed_versions
-    }
+    # A missing HWID is capturable when it belongs to a scanned device that
+    # already has a driver bound. Match on the device's own HWID list (which
+    # includes every variant) using normalized HWIDs, rather than exact
+    # membership in installed_versions whose keys are the full &REV_xx form.
+    not_found_norm = {_norm_hwid(h) for h in not_found_hwids}
+    locally_installed: set[str] = set()
+    for dev in scan_result.devices:
+        if not dev.has_driver:
+            continue
+        if any(_norm_hwid(h) in not_found_norm for h in dev.hwids):
+            locally_installed.update(h.upper() for h in dev.hwids)
     if not locally_installed:
         return []
 
@@ -395,8 +416,9 @@ def _map_hwids_to_published(hwids: set[str], cfg: dict) -> dict[str, str]:
 def _commit_hwid_block(state: dict, hwids: set[str], mapping: dict) -> None:
     """Flush accumulated HWIDs for the current device into mapping."""
     if state["published"]:
+        targets = {_norm_hwid(h) for h in hwids}
         for h in state["hwids"]:
-            if h in hwids:
+            if _norm_hwid(h) in targets:
                 mapping[h] = state["published"]
     state["published"] = ""
     state["hwids"]     = []

{driverclient-0.2.0 → driverclient-0.2.2}/src/driverclient/ops/install.py

@@ -33,13 +33,24 @@ _CATEGORY_ORDER: dict[str, int] = {
     "network": 3, "display": 5, "audio": 6, "other": 10,
 }
 
+# Installer exit codes that mean "succeeded, but a reboot is required".
+#   3010 = ERROR_SUCCESS_REBOOT_REQUIRED (pnputil / MSI / most installers)
+#   1641 = ERROR_SUCCESS_REBOOT_INITIATED
+_REBOOT_CODES: frozenset[int] = frozenset({3010, 1641})
+
+# Installer exit codes that mean "succeeded, nothing to do" (NOT a failure).
+#   259 = ERROR_NO_MORE_ITEMS — pnputil added the package but no device needed
+#         updating (driver already present / "Already exists in the system").
+_SUCCESS_NO_CHANGE_CODES: frozenset[int] = frozenset({259})
+
 
 @dataclass
 class DriverResult:
-    binding_id:  str
-    success:     bool
-    error:       str = ""
-    duration_ms: int = 0
+    binding_id:      str
+    success:         bool
+    error:           str  = ""
+    duration_ms:     int  = 0
+    reboot_required: bool = False   # installed OK but needs a reboot (pnputil 3010)
 
 
 @dataclass
@@ -53,6 +64,11 @@ class InstallResult:
     @property
     def fail_count(self) -> int: return len(self.install_failed)
 
+    @property
+    def reboot_required(self) -> bool:
+        """True if any successfully-installed driver reported reboot-required."""
+        return any(r.reboot_required for r in self.installed_ok)
+
 
 def resolve_and_install(force: bool = False) -> InstallResult:
     """
@@ -83,9 +99,12 @@ def resolve_and_install(force: bool = False) -> InstallResult:
 
     _confirm(result.trace_id, installed_ok, install_failed, cfg)
 
+    reboot_required = any(r.reboot_required for r in installed_ok)
+    reboot_tag = "  — reboot required" if reboot_required else ""
     events.done("install",
-                f"[install] Done — {len(installed_ok)} ok  {len(install_failed)} failed",
-                total=len(all_results), ok=len(installed_ok), failed=len(install_failed))
+                f"[install] Done — {len(installed_ok)} ok  {len(install_failed)} failed{reboot_tag}",
+                total=len(all_results), ok=len(installed_ok), failed=len(install_failed),
+                reboot_required=reboot_required)
     for r in install_failed:
         events.error("install", f"  ✗ {r.binding_id}: {r.error}",
                      binding_id=r.binding_id, error=r.error)
@@ -173,12 +192,15 @@ def _process_completed(
         return DriverResult(binding_id=bid, success=False, error="download_failed")
 
     t0 = time.monotonic()
-    ok, err = _install_driver(driver, dest, cfg)
+    ok, err, reboot = _install_driver(driver, dest, cfg)
     dur = int((time.monotonic() - t0) * 1000)
-    line = f"  {'✓' if ok else '✗'} [{cat}] {bid}  ({dur}ms)"
+    tag = " (reboot required)" if reboot else ""
+    line = f"  {'✓' if ok else '✗'} [{cat}] {bid}  ({dur}ms){tag}"
     emit = events.ok if ok else events.error
-    emit("install", line, binding_id=bid, category=cat, duration_ms=dur, error=err)
-    return DriverResult(binding_id=bid, success=ok, error=err, duration_ms=dur)
+    emit("install", line, binding_id=bid, category=cat, duration_ms=dur,
+         error=err, reboot_required=reboot)
+    return DriverResult(binding_id=bid, success=ok, error=err,
+                        duration_ms=dur, reboot_required=reboot)
 
 
 def _download_driver(driver: dict, base: Path, repo_url: str,
@@ -208,50 +230,66 @@ def _level_label(level: int) -> str:
 
 # ── Driver installation ─────────────────────────────────────────────────────────
 
-def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, str]:
+def _classify(returncode: int, err_text: str = "") -> tuple[bool, str, bool]:
+    """
+    Map an installer exit code to (success, error, reboot_required).
+
+    0                  -> success, no reboot
+    259                -> success, no reboot (package already present / no change)
+    3010 / 1641        -> success, reboot required (NOT a failure)
+    anything else      -> failure, carry err_text
+    """
+    if returncode == 0 or returncode in _SUCCESS_NO_CHANGE_CODES:
+        return True, "", False
+    if returncode in _REBOOT_CODES:
+        return True, "", True
+    return False, err_text, False
+
+
+def _install_driver(driver: dict, driver_dir: Path, cfg: dict) -> tuple[bool, str, bool]:
     install_type = driver.get("install_type", "inf_silent")
 
     try:
         if install_type == "inf_silent":
             inf_files = list(driver_dir.glob("*.inf"))
             if not inf_files:
-                return False, "No INF file found"
+                return False, "No INF file found", False
             r = subprocess.run(
                 ["pnputil", "/add-driver", str(inf_files[0]), "/install", "/subdirs"],
                 capture_output=True, text=True,
                 timeout=cfg["timeout_long"],
             )
-            return r.returncode == 0, r.stdout[:200] if r.returncode != 0 else ""
+            return _classify(r.returncode, r.stdout[:200])
 
         if install_type == "exe_silent":
             exe_files = list(driver_dir.glob("*.exe"))
             if not exe_files:
-                return False, "No EXE file found"
+                return False, "No EXE file found", False
             flags = driver.get("install_flags", "/S")
             r = subprocess.run(
                 [str(exe_files[0])] + flags.split(),
                 capture_output=True,
                 timeout=cfg["timeout_install"],
             )
-            return r.returncode == 0, ""
+            return _classify(r.returncode)
 
         if install_type == "firmware_flash":
             inf_files = list(driver_dir.glob("*.inf"))
             if not inf_files:
-                return False, "No firmware INF"
+                return False, "No firmware INF", False
             r = subprocess.run(
                 ["pnputil", "/add-driver", str(inf_files[0]), "/install"],
                 capture_output=True, text=True,
                 timeout=cfg["timeout_long"],
             )
-            return r.returncode == 0, ""
+            return _classify(r.returncode)
 
     except subprocess.TimeoutExpired:
-        return False, "Install timed out"
+        return False, "Install timed out", False
     except Exception as e:
-        return False, str(e)
+        return False, str(e), False
 
-    return False, f"Unknown install_type: {install_type}"
+    return False, f"Unknown install_type: {install_type}", False
 
 
 # ── Confirm ─────────────────────────────────────────────────────────────────────

{driverclient-0.2.0 → driverclient-0.2.2}/src/driverclient/ops/scan.py

@@ -9,6 +9,7 @@ Public API:
     scan(force=False) -> ScanResult
 """
 import json
+import re
 import subprocess
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import asdict, dataclass, field
@@ -62,6 +63,54 @@ class ScanResult:
         return [d for d in self.devices if d.has_driver]
 
 
+_ACPI_VENDEV = re.compile(r"^ACPI\\VEN_([^&]+)&DEV_(.+)$")
+
+
+def _canon_hwid(hwid: str) -> str:
+    """Fold the two HWID forms Windows reports for one device into one key.
+
+    `installed_versions` comes from Win32_PnPSignedDriver.HardWareID — the
+    canonical VEN_/DEV_ form with a &REV_xx tail, and ACPI IDs written as
+    ACPI\\VEN_INT&DEV_3394.  The HWIDs sent to /resolve come from pnputil
+    /enum-devices — raw form, no &REV, ACPI as ACPI\\INT3394.  Both collapse to
+    one comparable key: uppercase, &REV_* dropped, ACPI VEN_/DEV_ concatenated.
+    """
+    up  = hwid.upper()
+    idx = up.find("&REV_")
+    if idx != -1:
+        up = up[:idx]
+    m = _ACPI_VENDEV.match(up)
+    if m:
+        up = f"ACPI\\{m.group(1)}{m.group(2)}"
+    return up
+
+
+def _installed_prefix_index(installed_versions: dict[str, str]) -> dict[str, str]:
+    """Expand each canonical installed HWID into its &-boundary prefixes.
+
+    The installed key is the most-specific device ID
+    (PCI\\VEN_8086&DEV_9D15&SUBSYS_222C17AA&REV_F1) while /resolve frequently
+    matches on a shorter variant (PCI\\VEN_8086&DEV_9D15).  Emitting every
+    prefix that still contains &DEV_ lets the shorter form find the version.
+    The bare bus/vendor root (PCI\\VEN_8086) is skipped so an over-generic ID
+    can't be mislabelled as already-current.
+    """
+    idx: dict[str, str] = {}
+    for key, ver in installed_versions.items():
+        canon = _canon_hwid(key)
+        parts = canon.split("&")
+        acc   = parts[0]
+        prefixes = [acc]
+        for p in parts[1:]:
+            acc = f"{acc}&{p}"
+            prefixes.append(acc)
+        for pref in prefixes:
+            if "&" in canon and "&DEV_" not in pref:
+                continue  # skip bare bus/vendor root
+            idx.setdefault(pref, ver)
+    return idx
+
+
 def scan(force: bool = False) -> ScanResult:
     """
     Run a full hardware scan.  Loads from ds_scan.json cache if fresh
@@ -91,6 +140,19 @@ def scan(force: bool = False) -> ScanResult:
                         total=len(all_hwids))
         installed_versions = get_installed_versions(all_hwids)
 
+    # Re-key installed_versions onto the raw HWID strings the client sends to
+    # /resolve.  Win32_PnPSignedDriver reports the canonical VEN_/DEV_+REV form,
+    # which never matches the raw pnputil HWIDs verbatim — so without this the
+    # server's already-current check (and Device.installed_version below) miss
+    # every time and every repo-covered driver shows up as "to install".
+    if installed_versions:
+        prefix_idx = _installed_prefix_index(installed_versions)
+        for h in all_hwids:
+            if h not in installed_versions:
+                ver = prefix_idx.get(_canon_hwid(h))
+                if ver:
+                    installed_versions[h] = ver
+
     for dev in devices:
         ver = next(
             (installed_versions[h] for h in dev.hwids if h in installed_versions),