driverclient 0.2.1__tar.gz → 0.2.3__tar.gz

{driverclient-0.2.1 → driverclient-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: driverclient
-Version: 0.2.1
+Version: 0.2.3
 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>

{driverclient-0.2.1 → driverclient-0.2.3}/pyproject.toml

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

{driverclient-0.2.1 → driverclient-0.2.3}/src/driverclient/__init__.py

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

{driverclient-0.2.1 → driverclient-0.2.3}/src/driverclient/ops/automate.py

@@ -17,7 +17,7 @@ from datetime import datetime, timezone
 
 from driverclient import events
 from driverclient.config import get
-from driverclient.ops.capture import CaptureResult, wu_update
+from driverclient.ops.capture import CaptureResult, classify_missing, wu_update
 from driverclient.ops.install import InstallResult, resolve_and_install
 from driverclient.ops.resolve import ResolveResult, resolve
 from driverclient.ops.scan import ScanResult, scan
@@ -116,22 +116,39 @@ def _summary(r: AutomateResult) -> None:
     inst   = r.install or InstallResult()
     wu     = r.wu      or CaptureResult()
 
+    # Bucket the repo-missing HWIDs so "not found" reads truthfully: inbox
+    # devices are covered by Windows itself, not missing from the repo.
+    buckets = None
+    if r.scan and r.resolve and r.resolve.not_found:
+        buckets = classify_missing(r.resolve.not_found, r.scan)
+
     events.done("done", "")
     events.done("done", "=" * 60)
     events.done("done", "  Summary")
     events.done("done", f"  Duration : {r.duration_s}s", duration_s=r.duration_s)
+    if r.resolve:
+        events.done("done",
+                    f"  Current  : {r.resolve.already_current} already current "
+                    f"(of {r.resolve.total_hwids} HWIDs)",
+                    already_current=r.resolve.already_current,
+                    total_hwids=r.resolve.total_hwids)
     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 buckets:
+        inbox = len(buckets["inbox"])
+        genuine = len(buckets["driverless"]) + len(buckets["unknown"])
+        if inbox:
+            events.done("done",
+                        f"  Inbox    : {inbox} HWID(s) — Windows inbox driver, not applicable",
+                        inbox=inbox)
+        events.done("done",
+                    f"  Missing  : {genuine} genuinely missing (WU candidates)",
+                    genuinely_missing=genuine)
     if r.wu and r.wu.wu_triggered:
         events.done("done",
                     f"  WU       : {wu.submitted} captured  {wu.still_missing} still missing",
                     wu_submitted=wu.submitted, wu_still_missing=wu.still_missing)
-    else:
-        missing = len(r.resolve.not_found) if r.resolve else 0
-        if missing:
-            events.done("done", f"  Missing  : {missing} HWID(s) not in repo (WU not run)",
-                        missing=missing)
     events.done("done", "=" * 60)

{driverclient-0.2.1 → driverclient-0.2.3}/src/driverclient/ops/capture.py

@@ -40,7 +40,7 @@ from driverclient.config import get
 from driverclient.core.hardware import compute_fingerprint, get_model_profile
 from driverclient.core.http import BadRequestError, http_post_retry, http_upload_package, pack_driver_archive
 from driverclient.ops.resolve import ResolveResult, resolve
-from driverclient.ops.scan import Device, ScanResult, scan
+from driverclient.ops.scan import Device, ScanResult, _looks_like_hwid, scan
 
 
 def _post_wu_session(cfg: dict, wu_start, hwids_tried: list, captured: int) -> None:
@@ -153,26 +153,35 @@ def capture_missing(force: bool = False) -> CaptureResult:
                     total=0)
         return CaptureResult()
 
-    not_found_set = set(res_result.not_found)
-    events.progress("capture",
-                    f"[capture-missing] {len(not_found_set)} HWID(s) missing from repo",
-                    total=len(not_found_set))
-
-    to_export = _find_installed_packages_for_hwids(not_found_set, scan_result, cfg)
+    buckets = classify_missing(res_result.not_found, scan_result)
+    genuinely_missing = len(buckets["driverless"]) + len(buckets["unknown"])
+    events.progress(
+        "capture",
+        f"[capture-missing] {len(res_result.not_found)} HWID(s) not in repo — "
+        f"{len(buckets['inbox'])} inbox (not applicable)  "
+        f"{len(buckets['oem_local'])} with local OEM driver  "
+        f"{genuinely_missing} genuinely missing",
+        total=len(res_result.not_found), inbox=len(buckets["inbox"]),
+        oem_local=len(buckets["oem_local"]), genuinely_missing=genuinely_missing)
+
+    to_export = _find_installed_packages_for_hwids(set(buckets["oem_local"]), scan_result, cfg)
     if not to_export:
         events.done("capture",
-                    "[capture-missing] None of the missing HWIDs have locally-installed drivers",
-                    total=0, still_missing=len(not_found_set))
-        return CaptureResult(still_missing=len(not_found_set))
+                    f"[capture-missing] Nothing capturable — {len(buckets['inbox'])} inbox, "
+                    f"{genuinely_missing} genuinely missing (WU candidates)",
+                    total=0, still_missing=genuinely_missing)
+        return CaptureResult(still_missing=genuinely_missing)
 
     events.progress("capture",
                     f"[capture-missing] Exporting {len(to_export)} locally-installed package(s)…",
                     total=len(to_export))
     result = _export_and_submit(to_export, cfg)
-    result.still_missing = max(0, len(not_found_set) - result.submitted)
+    result.still_missing = genuinely_missing
     events.done("capture",
                 f"[capture-missing] Done — {result.submitted} submitted  "
-                f"{result.skipped} skipped  {result.failed} failed",
+                f"{result.skipped} skipped  {result.failed} failed  "
+                f"({len(buckets['inbox'])} inbox not applicable, "
+                f"{genuinely_missing} genuinely missing)",
                 total=len(to_export), submitted=result.submitted,
                 skipped=result.skipped, failed=result.failed,
                 still_missing=result.still_missing)
@@ -198,24 +207,21 @@ def wu_update(force: bool = False) -> CaptureResult:
                     total=0)
         return CaptureResult()
 
-    wu_hwids = _filter_wu_hwids(res_result.not_found, scan_result, cfg)
-    skipped  = len(res_result.not_found) - len(wu_hwids)
+    wu_hwids, skip_reasons = _filter_wu_hwids(res_result.not_found, scan_result, cfg)
+    skip_detail = (f"{skip_reasons['inbox']} inbox (not applicable)  "
+                   f"{skip_reasons['local_driver']} covered by local driver  "
+                   f"{skip_reasons['ignored_class']} ignored class")
 
     if not wu_hwids:
         events.done("windows_update",
-                    "[wu-update] All missing HWIDs have local drivers or are ignored — skipping WU",
-                    total=0, still_missing=len(res_result.not_found))
-        return CaptureResult(still_missing=len(res_result.not_found))
-
-    if skipped:
-        events.start("windows_update",
-                     f"[wu-update] {len(wu_hwids)} HWID(s) need WU  "
-                     f"({skipped} skipped — has local driver or ignored class)",
-                     total=len(wu_hwids), skipped=skipped)
-    else:
-        events.start("windows_update",
-                     f"[wu-update] {len(wu_hwids)} HWID(s) not in repo — triggering Windows Update…",
-                     total=len(wu_hwids))
+                    f"[wu-update] WU skipped — 0 genuinely missing ({skip_detail})",
+                    total=0, still_missing=0, **skip_reasons)
+        return CaptureResult(still_missing=0)
+
+    events.start("windows_update",
+                 f"[wu-update] {len(wu_hwids)} genuinely missing HWID(s) — "
+                 f"triggering Windows Update…  ({skip_detail})",
+                 total=len(wu_hwids), **skip_reasons)
 
     if not _trigger_wu():
         return CaptureResult(still_missing=len(wu_hwids))
@@ -257,41 +263,72 @@ def wu_full() -> CaptureResult:
     return total
 
 
+# ══ Missing-HWID classification ═══════════════════════════════════════════════
+
+def classify_missing(not_found: list[str], scan_result: ScanResult) -> dict[str, list[str]]:
+    """Bucket repo-missing HWIDs by what the machine says about their device:
+    inbox (Windows ships the driver — not applicable), oem_local (OEM driver
+    installed locally — capturable), driverless (genuinely missing — WU
+    candidate), unknown (HWID not in scan)."""
+    hwid_to_device: dict[str, Device] = {}
+    for dev in scan_result.devices:
+        for h in dev.hwids:
+            hwid_to_device[_norm_hwid(h)] = dev
+
+    buckets: dict[str, list[str]] = {
+        "inbox": [], "oem_local": [], "driverless": [], "unknown": [],
+    }
+    for hwid in not_found:
+        dev = hwid_to_device.get(_norm_hwid(hwid))
+        if dev is None:
+            buckets["unknown"].append(hwid)
+        elif not dev.has_driver:
+            buckets["driverless"].append(hwid)
+        elif dev.is_inbox:
+            buckets["inbox"].append(hwid)
+        else:
+            buckets["oem_local"].append(hwid)
+    return buckets
+
+
 # ══ WU HWID filtering ═════════════════════════════════════════════════════════
 
 def _filter_wu_hwids(
     not_found: list[str],
     scan_result: ScanResult,
     cfg: dict,
-) -> list[str]:
+) -> tuple[list[str], dict[str, int]]:
     """
-    Return only the not_found HWIDs that genuinely need Windows Update:
-      - Device has no driver installed locally (has_driver=False)
-      - Device class is not in wu_ignore_classes config
-      - If HWID is not in scan at all → include (unknown device, safer to try)
+    Return (wu_hwids, skipped_reasons) — only genuinely driverless, non-inbox,
+    non-ignored devices go to Windows Update:
+      - inbox driver bound        → skip (Windows covers it — not applicable)
+      - local OEM driver bound    → skip (capture_missing handles repo upload)
+      - class in wu_ignore_classes → skip
+      - not in scan at all        → include (unknown device — safer to attempt)
     """
     ignore_classes: set[str] = {
         c.lower() for c in cfg.get("wu_ignore_classes", [])
     }
+    buckets = classify_missing(not_found, scan_result)
 
+    result: list[str] = list(buckets["unknown"])
+    skipped = {
+        "inbox": len(buckets["inbox"]),
+        "local_driver": len(buckets["oem_local"]),
+        "ignored_class": 0,
+    }
     hwid_to_device: dict[str, Device] = {}
     for dev in scan_result.devices:
-        for hwid in dev.hwids:
-            hwid_to_device[hwid.upper()] = dev
-
-    result = []
-    for hwid in not_found:
-        dev = hwid_to_device.get(hwid.upper())
-        if dev is None:
+        for h in dev.hwids:
+            hwid_to_device[_norm_hwid(h)] = dev
+    for hwid in buckets["driverless"]:
+        dev = hwid_to_device.get(_norm_hwid(hwid))
+        if dev and ignore_classes and dev.class_name.lower() in ignore_classes:
+            skipped["ignored_class"] += 1
+        else:
             result.append(hwid)
-            continue
-        if dev.has_driver:
-            continue
-        if ignore_classes and dev.class_name.lower() in ignore_classes:
-            continue
-        result.append(hwid)
 
-    return result
+    return result, skipped
 
 
 # ══ Package enumeration ════════════════════════════════════════════════════════
@@ -345,15 +382,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 +453,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"]     = []
@@ -411,7 +470,7 @@ def _parse_hwid_line(line: str, stripped: str, state: dict) -> None:
         state["in_hwids"]  = False
     elif low.startswith(("hardware ids", "compatible ids")):
         state["in_hwids"] = True
-    elif state["in_hwids"] and "\\" in stripped and not stripped.endswith(":"):
+    elif state["in_hwids"] and _looks_like_hwid(stripped):
         state["hwids"].append(stripped.upper())
     elif ":" in stripped and not line.startswith(" "):
         state["in_hwids"] = False

{driverclient-0.2.1 → driverclient-0.2.3}/src/driverclient/ops/install.py

@@ -38,6 +38,11 @@ _CATEGORY_ORDER: dict[str, int] = {
 #   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:
@@ -230,10 +235,11 @@ 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:
+    if returncode == 0 or returncode in _SUCCESS_NO_CHANGE_CODES:
         return True, "", False
     if returncode in _REBOOT_CODES:
         return True, "", True

{driverclient-0.2.1 → driverclient-0.2.3}/src/driverclient/ops/resolve.py

@@ -30,6 +30,8 @@ class ResolveResult:
     trace_id:   str         = ""
     machine_id: str         = ""
     timestamp:  str         = ""
+    total_hwids:     int    = 0
+    already_current: int    = 0
 
     @property
     def has_drivers(self) -> bool:
@@ -89,10 +91,12 @@ def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResul
         trace_id=resp.get("trace_id", ""),
         machine_id=scan_result.machine_id,
         timestamp=datetime.now(timezone.utc).isoformat(),
+        total_hwids=resp.get("total_hwids", len(scan_result.all_hwids)),
+        already_current=resp.get("already_current", 0),
     )
 
-    total_hwids     = resp.get("total_hwids", len(scan_result.all_hwids))
-    already_current = resp.get("already_current", 0)
+    total_hwids     = result.total_hwids
+    already_current = result.already_current
 
     events.done(
         "resolve",

{driverclient-0.2.1 → driverclient-0.2.3}/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
@@ -32,6 +33,13 @@ class Device:
     has_driver:        bool
     installed_version: str = ""
     class_name:        str = ""   # e.g. "System", "Net", "Display adapters"
+    driver_name:       str = ""   # published INF name, e.g. "oem42.inf" or "machine.inf"
+
+    @property
+    def is_inbox(self) -> bool:
+        """Driver ships with Windows (published name is not oem*.inf) — the repo
+        never needs to cover it, so it's 'not applicable' rather than 'missing'."""
+        return self.has_driver and not self.driver_name.lower().startswith("oem")
 
 
 @dataclass
@@ -62,6 +70,65 @@ class ScanResult:
         return [d for d in self.devices if d.has_driver]
 
 
+_ACPI_VENDEV = re.compile(r"^ACPI\\VEN_([^&]+)&DEV_(.+)$")
+
+
+def _looks_like_hwid(stripped: str) -> bool:
+    """A pnputil ID line: enumerator form (BUS\\...), star compatible ID
+    (*PNP0A0A), bare GUID, or a bare token (WireGuard software devices) —
+    never a 'Key:' header line. IDs never contain whitespace."""
+    if stripped.endswith(":"):
+        return False
+    if "\\" in stripped or stripped.startswith(("*", "{")):
+        return True
+    return len(stripped) >= 3 and not any(c.isspace() for c in stripped)
+
+
+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 +158,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),
@@ -245,7 +325,7 @@ def _apply_hwid_line(line: str, stripped: str, current: dict, in_hwids: bool) ->
     if low.startswith(("hardware ids", "compatible ids")):
         current.setdefault("hwids", [])
         return True
-    if in_hwids and "\\" in stripped and not stripped.endswith(":"):
+    if in_hwids and _looks_like_hwid(stripped):
         current.setdefault("hwids", []).append(stripped.upper())
         return True
     if ":" in stripped and not line.startswith(" "):
@@ -260,6 +340,7 @@ def _flush_device(current: dict, devices: list[Device]) -> None:
             device_name=current.get("name", ""),
             hwids=list(dict.fromkeys(current.get("hwids", []))),
             has_driver=bool(current.get("driver_name")),
+            driver_name=current.get("driver_name", ""),
         ))
 
 
@@ -310,7 +391,17 @@ def _print_summary(r: ScanResult) -> None:
     if r.missing_driver:
         events.progress("scan", "[scan] Missing drivers:")
         for d in r.missing_driver:
-            name  = d.device_name or (d.hwids[0] if d.hwids else d.instance_id)
-            cls   = f"  [{d.class_name}]" if d.class_name else ""
-            events.progress("scan", f"  ✗  {name}{cls}",
+            name = _device_label(d)
+            events.progress("scan", f"  ✗  {name}",
                             device_name=name, class_name=d.class_name)
+
+
+def _device_label(d: Device) -> str:
+    """Human line for a device — 'Unknown [Unknown]' tells the operator nothing,
+    so fall back to instance ID + first HWID."""
+    name = d.device_name
+    if not name or name.lower() == "unknown":
+        first_hwid = d.hwids[0] if d.hwids else ""
+        name = f"{d.instance_id}  {first_hwid}".strip()
+    cls = d.class_name if d.class_name.lower() not in ("", "unknown") else ""
+    return f"{name}  [{cls}]" if cls else name