driverclient 0.2.19__tar.gz → 0.2.21__tar.gz

{driverclient-0.2.19 → driverclient-0.2.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: driverclient
-Version: 0.2.19
+Version: 0.2.21
 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.19 → driverclient-0.2.21}/pyproject.toml

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

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/__init__.py

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

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/config.json

@@ -1,13 +1,20 @@
 {
+  "_comment_mode": "mode = 'live' (default): SA/first-boot install+reboot+WU+capture. mode = 'offline': WinPE download-only to offline_driver_dir, then win11.bat.j2 DISM-injects. See examples/config.json for the full prod-deploy note.",
+  "mode": "live",
   "local_repo_url": "http://localhost:8000",
   "node_key": "REPLACE_WITH_YOUR_NODE_KEY",
 
   "default_command": "automate",
 
+  "_comment_compression": "zstd downloads decompressed on-the-fly; keep true, set false only if zstd fails in WinPE.",
+  "compression": true,
   "parallel_downloads": 6,
   "parallel_uploads": 8,
   "parallel_exports": 4,
 
+  "_comment_offline_driver_dir": "offline mode writes files here (WinPE); DISM injects into the applied image W:\\. Ignored in live mode.",
+  "offline_driver_dir": "W:\\drivers",
+
   "driver_root": "C:\\DriverServer",
   "cache_dir":   "C:\\DriverServer\\client",
   "work_dir":    "C:\\DriverServer\\client\\staging",

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/config.py

@@ -13,6 +13,26 @@ DEFAULTS: dict = {
     "local_repo_url":    "http://localhost:8000",
     "node_key":          "",
 
+    # ── Mode ──────────────────────────────────────────────────────────────
+    # "live"    = SA / first-boot: batched pnputil install + reboot loop + WU +
+    #             capture (today's behaviour; handles the post-boot device tail).
+    # "offline" = pre-boot / WinPE: scan → resolve → DOWNLOAD ONLY to
+    #             offline_driver_dir. No install, no reboot, no WU, no capture —
+    #             win11.bat.j2's DISM step injects the files into the image.
+    "mode": "live",
+
+    # ── Offline (pre-boot / WinPE) ────────────────────────────────────────
+    # Where offline mode writes the decompressed driver files. DISM
+    # (win11.bat.j2) injects them into the applied image at W:\ afterward — the
+    # client only downloads; it never runs DISM itself.
+    "offline_driver_dir": "W:\\drivers",
+
+    # Request zstd-compressed downloads (decompressed on-the-fly in core/http.py):
+    # GPU ≈ 450 MB instead of 1.3 GB. True everywhere by default; set False only
+    # as a WinPE fallback if zstd ever fails to load there. Gates the
+    # Accept-Encoding: zstd request header sent by http_download.
+    "compression": True,
+
     # ── Command ───────────────────────────────────────────────────────────
     "default_command":   "automate",
 

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/core/http.py

@@ -194,7 +194,12 @@ def http_download(url: str, dest: Path, sha256_expected: str,
     """
     cfg = get()
     t = timeout or cfg["timeout_long"]
-    headers = {**_headers(), "Accept-Encoding": "zstd"}
+    # Only advertise zstd when compression is enabled. Offline/WinPE keeps it on
+    # (GPU ≈ 450 MB vs 1.3 GB); set compression=false as a fallback if zstd ever
+    # fails to load in WinPE, and the server serves the file uncompressed.
+    headers = dict(_headers())
+    if cfg.get("compression", True):
+        headers["Accept-Encoding"] = "zstd"
 
     req = urllib.request.Request(url, headers=headers)
     dest.parent.mkdir(parents=True, exist_ok=True)

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/main.py

@@ -28,6 +28,7 @@ from driverclient.ops.capture import (
 )
 from driverclient.ops.diagnose import run_diagnostics
 from driverclient.ops.install import resolve_and_install
+from driverclient.ops.offline import resolve_and_download
 from driverclient.ops.resolve import resolve
 from driverclient.ops.scan import scan
 
@@ -35,6 +36,7 @@ _OPERATIONS: dict[str, callable] = {
     "scan":                scan,
     "resolve":             resolve,
     "resolve-and-install": resolve_and_install,
+    "offline":             resolve_and_download,
     "capture-all":         capture_all,
     "capture-missing":     capture_missing,
     "capture-delta":       capture_delta,

driverclient-0.2.21/src/driverclient/ops/download.py

@@ -0,0 +1,63 @@
+"""
+client/ops/download.py — Shared driver-file download primitives.
+
+Both the LIVE install path (ops/install.py) and the OFFLINE / pre-boot path
+(ops/offline.py) fetch the same package files from the repo:
+
+    GET {repo_url}/files/{package_id}/{filename}   (streamed, zstd on-the-fly,
+                                                     sha256-verified — see core/http.py)
+
+Factored out here so the two modes share one download implementation:
+  • download_driver()  — fetch every file for ONE driver into base/<binding_id>/
+  • download_drivers() — fan the above out across a driver list in parallel
+"""
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from driverclient.core.http import http_download_retry
+
+
+def download_driver(driver: dict, base: Path, repo_url: str,
+                    cfg: dict) -> tuple[Path, bool]:
+    """Download all files for one driver into base/<binding_id>/.
+    Returns (dest_dir, success). success is False if ANY file failed."""
+    bid    = driver.get("binding_id") or driver.get("package_id", "")
+    pkg_id = driver["package_id"]
+    dest   = base / bid
+    dest.mkdir(parents=True, exist_ok=True)
+
+    ok = True
+    for f in driver.get("files", []):
+        url  = f"{repo_url}/files/{pkg_id}/{f['filename']}"
+        path = dest / f["filename"]
+        if not http_download_retry(url, path, f["sha256"],
+                                   timeout=cfg["timeout_long"]):
+            ok = False
+
+    return dest, ok
+
+
+def download_drivers(drivers: list[dict], base: Path,
+                     cfg: dict) -> list[tuple[dict, Path | None, bool]]:
+    """Download a list of drivers into `base` in parallel.
+
+    Returns a list of (driver, dest_dir | None, success) in completion order.
+    A driver that raised during download yields (driver, None, False) rather
+    than propagating — the caller decides how to report failures.
+    """
+    repo_url = cfg["local_repo_url"]
+    parallel = cfg.get("parallel_downloads", 6)
+
+    results: list[tuple[dict, Path | None, bool]] = []
+    with ThreadPoolExecutor(max_workers=parallel) as executor:
+        fut_map = {executor.submit(download_driver, d, base, repo_url, cfg): d
+                   for d in drivers}
+        for fut in as_completed(fut_map):
+            driver = fut_map[fut]
+            try:
+                dest, ok = fut.result()
+            except Exception:
+                results.append((driver, None, False))
+                continue
+            results.append((driver, dest, ok))
+    return results

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/ops/install.py

@@ -19,14 +19,15 @@ import subprocess
 import time
 import uuid
 from collections import defaultdict
-from concurrent.futures import Future, ThreadPoolExecutor, as_completed
+from concurrent.futures import ThreadPoolExecutor, as_completed
 from dataclasses import dataclass, field
 from pathlib import Path
 
 from driverclient import events
 from driverclient.config import get
 from driverclient.core import proc
-from driverclient.core.http import http_download_retry, http_post_retry
+from driverclient.core.http import http_post_retry
+from driverclient.ops.download import download_driver
 from driverclient.ops.resolve import ResolveResult, resolve
 
 # Install order: lower number first (hardware dependency)
@@ -155,12 +156,13 @@ def resolve_and_install(force: bool = False) -> InstallResult:
     # at the same-or-newer version — so a still-current big driver (graphics) is not
     # re-downloaded, while missing/extension drivers still install. Toggle off with
     # skip_installed_drivers=false to force-reinstall everything.
-    # Live driver-store index: INF name -> highest installed version. Built once,
-    # then UPDATED as each driver installs this pass (see _record_installed) so a
-    # later package of the same driver family (same INF) at an equal-or-older
-    # version is skipped — the driver store already has it. This is skip-if-present
-    # (idempotency), NOT deduplication: no repo package is removed; a newer repo
-    # version still installs over an older store version (store_ver >= repo_ver skips).
+    # Driver-store index (INF name -> highest installed version), built once to
+    # FILTER the download list: skip any package the store already has at the
+    # same-or-newer version. This is skip-if-present (idempotency), NOT dedup —
+    # no repo package is removed; a newer repo version still installs over an
+    # older store version (store_ver >= repo_ver skips). Duplicate versions that
+    # survive the filter are resolved at install time by a single batched pnputil
+    # pass, where Windows picks the best driver per device.
     skip_installed = cfg.get("skip_installed_drivers", True)
     idx: dict = _installed_inf_index() if skip_installed else {}
 
@@ -188,7 +190,7 @@ def resolve_and_install(force: bool = False) -> InstallResult:
     events.start("install",
                  f"[install] {len(drivers)} driver(s) — starting parallel downloads…",
                  total=len(drivers))
-    all_results = _stream_install(drivers, work_dir, cfg, idx, skip_installed)
+    all_results = _stream_install(drivers, work_dir, cfg)
 
     shutil.rmtree(work_dir, ignore_errors=True)
 
@@ -219,34 +221,59 @@ def resolve_and_install(force: bool = False) -> InstallResult:
 
 # ── Streaming pipeline ──────────────────────────────────────────────────────────
 
-def _stream_install(drivers: list[dict], base: Path, cfg: dict,
-                    idx: dict, skip_installed: bool) -> list[DriverResult]:
+def _stream_install(drivers: list[dict], base: Path, cfg: dict) -> list[DriverResult]:
     """
-    Submit ALL downloads (all levels) simultaneously, then install level-by-level.
-    Each driver installs the moment its own download Future completes.
-
-    `idx` is the live driver-store index (INF -> installed version); it is read to
-    skip a driver the store already has and updated after each successful install
-    so same-family duplicates later in the pass are skipped too. Installs run one
-    at a time here (main thread), so mutating `idx` needs no lock.
+    Download every driver in parallel, then install in the fewest passes possible:
+
+      • all INF drivers  -> ONE `pnputil /add-driver <base>\\*.inf /subdirs /install`
+        pass. Windows stages every package and installs the best/newest driver per
+        device in a single PnP reconciliation — far faster than one pnputil call
+        per driver, and it resolves duplicate versions itself (so "no dedup" is
+        handled at install time here, not by dropping packages).
+      • EXE-installer drivers -> run their silent installer individually (EXEs
+        cannot be batched).
+
+    Downloads stay fully parallel; only the install strategy changed from one
+    pnputil call per driver to a single batched call.
     """
     repo_url = cfg["local_repo_url"]
     parallel = cfg.get("parallel_downloads", 6)
 
-    by_level                 = _dedup_and_group(drivers)
-    executor                 = ThreadPoolExecutor(max_workers=parallel)
-    future_info, level_futs  = _submit_all_downloads(by_level, base, repo_url, cfg, executor)
-
-    all_results: list[DriverResult] = []
-    for level in sorted(by_level):
-        events.progress("install",
-                        f"[install] {_level_label(level)} ({len(level_futs[level])} driver(s))…",
-                        category=_level_label(level), count=len(level_futs[level]))
-        for fut in as_completed(level_futs[level]):
-            all_results.append(_process_completed(fut, future_info, cfg, idx, skip_installed))
-
-    executor.shutdown(wait=False)
-    return all_results
+    by_level = _dedup_and_group(drivers)
+    ordered  = [d for level in sorted(by_level) for d in by_level[level]]
+
+    events.progress("install",
+                    f"[install] Downloading {len(ordered)} driver(s) in parallel…",
+                    total=len(ordered))
+
+    results:    list[DriverResult]      = []
+    downloaded: list[tuple[dict, Path]] = []
+    with ThreadPoolExecutor(max_workers=parallel) as executor:
+        fut_map = {executor.submit(download_driver, d, base, repo_url, cfg): d
+                   for d in ordered}
+        for fut in as_completed(fut_map):
+            driver = fut_map[fut]
+            bid    = driver.get("binding_id") or driver.get("package_id", "")
+            try:
+                dest, dl_ok = fut.result()
+            except Exception as e:
+                results.append(DriverResult(binding_id=bid, success=False, error=str(e)))
+                continue
+            if dl_ok:
+                downloaded.append((driver, dest))
+            else:
+                results.append(DriverResult(binding_id=bid, success=False,
+                                            error="download_failed"))
+
+    inf_drivers = [(d, p) for d, p in downloaded
+                   if d.get("install_type", "inf_silent") != "exe_silent"]
+    exe_drivers = [(d, p) for d, p in downloaded
+                   if d.get("install_type", "inf_silent") == "exe_silent"]
+
+    results += _batch_install_infs(inf_drivers, base, cfg)
+    for driver, dest in exe_drivers:
+        results.append(_install_one_exe(driver, dest, cfg))
+    return results
 
 
 def _dedup_and_group(drivers: list[dict]) -> dict[int, list[dict]]:
@@ -262,104 +289,84 @@ def _dedup_and_group(drivers: list[dict]) -> dict[int, list[dict]]:
     return by_level
 
 
-def _submit_all_downloads(
-    by_level: dict[int, list[dict]],
-    base: Path,
-    repo_url: str,
-    cfg: dict,
-    executor: ThreadPoolExecutor,
-) -> tuple[dict[Future, tuple[int, dict]], dict[int, list[Future]]]:
-    """Submit every driver download to the pool at once. Returns lookup maps."""
-    future_info:  dict[Future, tuple[int, dict]] = {}
-    level_futs:   dict[int, list[Future]]        = defaultdict(list)
-    for level in sorted(by_level):
-        for driver in by_level[level]:
-            fut = executor.submit(_download_driver, driver, base, repo_url, cfg)
-            future_info[fut] = (level, driver)
-            level_futs[level].append(fut)
-    return future_info, level_futs
-
-
-def _process_completed(
-    fut: Future,
-    future_info: dict[Future, tuple[int, dict]],
-    cfg: dict,
-    idx: dict,
-    skip_installed: bool,
-) -> DriverResult:
-    """Handle one completed download Future: install if ok, return DriverResult."""
-    _, driver = future_info[fut]
-    bid = driver.get("binding_id", "")
-    cat = driver.get("category", "other")
-
-    # A driver installed earlier THIS pass may have added the same INF (another
-    # package of the same driver family), so a package that was missing at
-    # pass-start can now already be in the store at an equal-or-newer version.
-    # Re-check against the live index and skip the redundant re-install.
-    if skip_installed and _already_in_store(driver, idx):
-        events.ok("install", f"  ⭑ [{cat}] {bid}  already in driver store — skipped",
-                  binding_id=bid, category=cat, skipped=True)
-        return DriverResult(binding_id=bid, success=True, skipped=True)
-
+def _batch_install_infs(inf_drivers: list[tuple[dict, Path]], base: Path,
+                        cfg: dict) -> list[DriverResult]:
+    """Install every downloaded INF driver in ONE pnputil pass.
+
+    `pnputil /add-driver <base>\\*.inf /subdirs /install` recurses the staging tree
+    (each driver lives in its own subdir), adds every package to the driver store
+    and installs the best match onto each device in a single PnP reconciliation —
+    the fast path the old driverserver used (launcher.bat). pnputil does not report
+    a clean per-package status, so the batch's outcome is attributed to each driver
+    and pnputil's own output lines are surfaced so nothing is hidden by batching."""
+    if not inf_drivers:
+        return []
+
+    n = len(inf_drivers)
+    events.progress("install",
+                    f"[install] Installing {n} INF driver(s) in one batched pnputil pass…",
+                    total=n)
+    t0     = time.monotonic()
+    stdout = ""
     try:
-        dest, dl_ok = fut.result()
+        r = proc.run(
+            ["pnputil", "/add-driver", str(base / "*.inf"), "/subdirs", "/install"],
+            capture_output=True, text=True,
+            timeout=cfg.get("timeout_install", 600),
+        )
+        stdout = r.stdout or ""
+        ok, err, reboot = _classify(r.returncode, r.stdout, r.stderr)
+    except subprocess.TimeoutExpired:
+        ok, err, reboot = False, "Batch install timed out", False
     except Exception as e:
-        return DriverResult(binding_id=bid, success=False, error=str(e))
+        ok, err, reboot = False, str(e), False
+    dur = int((time.monotonic() - t0) * 1000)
 
-    if not dl_ok:
-        return DriverResult(binding_id=bid, success=False, error="download_failed")
+    for line in stdout.splitlines():
+        s = line.strip()
+        if s:
+            events.progress("install", f"    {s}")
 
-    t0 = time.monotonic()
-    ok, err, reboot = _install_driver(driver, dest, cfg)
-    dur = int((time.monotonic() - t0) * 1000)
-    if ok:
-        _record_installed(driver, idx)   # update live index so same-family dupes skip
     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, reboot_required=reboot)
+    (events.ok if ok else events.error)(
+        "install",
+        f"  {'✓' if ok else '✗'} batch-installed {n} INF driver(s) ({dur}ms){tag}",
+        count=n, duration_ms=dur, reboot_required=reboot, error=err)
+
+    return [
+        DriverResult(binding_id=(d.get("binding_id") or d.get("package_id", "")),
+                     success=ok, error="" if ok else err,
+                     duration_ms=dur, reboot_required=reboot)
+        for d, _ in inf_drivers
+    ]
+
+
+def _install_one_exe(driver: dict, driver_dir: Path, cfg: dict) -> DriverResult:
+    """Run one EXE-installer driver's silent setup (EXEs cannot be batched)."""
+    bid = driver.get("binding_id") or driver.get("package_id", "")
+    t0  = time.monotonic()
+    try:
+        exe_files = list(driver_dir.glob("*.exe"))
+        if not exe_files:
+            return DriverResult(binding_id=bid, success=False, error="No EXE file found")
+        flags = driver.get("install_flags", "/S")
+        r = proc.run([str(exe_files[0])] + flags.split(),
+                     capture_output=True, timeout=cfg["timeout_install"])
+        ok, err, reboot = _classify(r.returncode)
+    except subprocess.TimeoutExpired:
+        ok, err, reboot = False, "Install timed out", False
+    except Exception as e:
+        ok, err, reboot = False, str(e), False
+    dur = int((time.monotonic() - t0) * 1000)
+    (events.ok if ok else events.error)(
+        "install", f"  {'✓' if ok else '✗'} [exe] {bid} ({dur}ms)",
+        binding_id=bid, duration_ms=dur, error=err, reboot_required=reboot)
     return DriverResult(binding_id=bid, success=ok, error=err,
                         duration_ms=dur, reboot_required=reboot)
 
 
-def _record_installed(driver: dict, idx: dict) -> None:
-    """Fold a just-installed driver's INF(s)+version into the live store index, so a
-    later package of the same driver family at an equal-or-older version is skipped
-    this pass — mirrors what `pnputil /enum-drivers` will report on the next scan."""
-    ver = _parse_ver(driver.get("version_label", ""))
-    if not ver:
-        return
-    for f in driver.get("files", []):
-        name = f.get("filename", "").lower()
-        if f.get("file_role") == "inf" or name.endswith(".inf"):
-            if idx.get(name) is None or ver > idx[name]:
-                idx[name] = ver
-
-
-def _download_driver(driver: dict, base: Path, repo_url: str,
-                     cfg: dict) -> tuple[Path, bool]:
-    """Download all files for one driver. Returns (dest_dir, success)."""
-    bid    = driver.get("binding_id") or driver.get("package_id", "")
-    pkg_id = driver["package_id"]
-    dest   = base / bid
-    dest.mkdir(parents=True, exist_ok=True)
-
-    ok = True
-    for f in driver.get("files", []):
-        url  = f"{repo_url}/files/{pkg_id}/{f['filename']}"
-        path = dest / f["filename"]
-        if not http_download_retry(url, path, f["sha256"],
-                                   timeout=cfg["timeout_long"]):
-            ok = False
-
-    return dest, ok
-
-
-def _level_label(level: int) -> str:
-    labels = {0: "chipset", 1: "firmware", 2: "storage",
-              3: "network", 5: "display", 6: "audio", 10: "other"}
-    return labels.get(level, f"level-{level}")
+# Driver-file download lives in ops/download.py (download_driver), shared with
+# the offline / pre-boot path.
 
 
 # ── Driver installation ─────────────────────────────────────────────────────────
@@ -397,52 +404,6 @@ def _classify(returncode: int, stdout: str = "", stderr: str = "") -> tuple[bool
     return False, (stderr.strip() or stdout.strip() or f"exit {returncode}")[:200], 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", False
-            r = proc.run(
-                ["pnputil", "/add-driver", str(inf_files[0]), "/install", "/subdirs"],
-                capture_output=True, text=True,
-                timeout=cfg["timeout_long"],
-            )
-            return _classify(r.returncode, r.stdout, r.stderr)
-
-        if install_type == "exe_silent":
-            exe_files = list(driver_dir.glob("*.exe"))
-            if not exe_files:
-                return False, "No EXE file found", False
-            flags = driver.get("install_flags", "/S")
-            r = proc.run(
-                [str(exe_files[0])] + flags.split(),
-                capture_output=True,
-                timeout=cfg["timeout_install"],
-            )
-            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", False
-            r = proc.run(
-                ["pnputil", "/add-driver", str(inf_files[0]), "/install"],
-                capture_output=True, text=True,
-                timeout=cfg["timeout_long"],
-            )
-            return _classify(r.returncode, r.stdout, r.stderr)
-
-    except subprocess.TimeoutExpired:
-        return False, "Install timed out", False
-    except Exception as e:
-        return False, str(e), False
-
-    return False, f"Unknown install_type: {install_type}", False
-
-
 # ── Confirm ─────────────────────────────────────────────────────────────────────
 
 def _confirm(trace_id: str, ok: list[DriverResult], fail: list[DriverResult],

driverclient-0.2.21/src/driverclient/ops/offline.py

@@ -0,0 +1,101 @@
+"""
+client/ops/offline.py — Offline / pre-boot (WinPE) driver staging.
+
+The FAST path, matching the old system: run inside WinPE against a freshly
+applied Windows image, enumerate the machine's real HWIDs, resolve them against
+the driverserver, and DOWNLOAD the matched driver files to offline_driver_dir
+(default W:\\drivers). That's ALL this op does — it never installs.
+
+win11.bat.j2 runs the injection afterward:
+
+    X:\\tools\\driverclient\\driverclient.exe          (this op, mode=offline)
+    dism /image:W:\\ /add-driver /driver:W:\\drivers /recurse /forceunsigned
+
+So there is NO live install, NO reboot loop, NO Windows Update, NO capture here —
+everything is injected offline into the image and is present instantly at first
+boot. The small post-boot device tail that WinPE can't see is handled later by
+the LIVE mode (SA finalization).
+
+Layout: each driver's files land in offline_driver_dir/<binding_id>/, so
+duplicate INF filenames across packages never collide and DISM /recurse picks
+them all up.
+
+Public API:
+    resolve_and_download() -> OfflineResult
+"""
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from driverclient import events
+from driverclient.config import get
+from driverclient.ops.download import download_drivers
+from driverclient.ops.resolve import resolve
+
+
+@dataclass
+class OfflineResult:
+    downloaded_ok:   list[str] = field(default_factory=list)
+    download_failed: list[str] = field(default_factory=list)
+    not_found:       list[str] = field(default_factory=list)
+    trace_id:        str       = ""
+    target_dir:      str       = ""
+
+    @property
+    def ok_count(self)   -> int: return len(self.downloaded_ok)
+    @property
+    def fail_count(self) -> int: return len(self.download_failed)
+
+
+def resolve_and_download() -> OfflineResult:
+    """
+    Scan → resolve (empty installed_versions → full matched set) → download every
+    matched driver's files to offline_driver_dir. No install. Returns OfflineResult.
+    """
+    cfg    = get()
+    target = Path(cfg.get("offline_driver_dir", "W:\\drivers"))
+
+    # force=True: fresh WinPE session, no meaningful cache to reuse — always scan
+    # the real hardware. offline=True: send empty installed_versions.
+    result = resolve(force=True, offline=True)
+
+    if not result.has_drivers:
+        events.done("offline",
+                    "[offline] Nothing to download — no matched drivers",
+                    total=0, not_found=len(result.not_found))
+        return OfflineResult(trace_id=result.trace_id,
+                             not_found=result.not_found,
+                             target_dir=str(target))
+
+    target.mkdir(parents=True, exist_ok=True)
+
+    drivers = result.drivers
+    events.start("offline",
+                 f"[offline] {len(drivers)} driver(s) → downloading to {target} …",
+                 total=len(drivers))
+
+    downloaded = download_drivers(drivers, target, cfg)
+
+    ok:     list[str] = []
+    failed: list[str] = []
+    for driver, _dest, success in downloaded:
+        bid = driver.get("binding_id") or driver.get("package_id", "")
+        (ok if success else failed).append(bid)
+
+    for bid in failed:
+        events.error("offline", f"  ✗ {bid}: download_failed", binding_id=bid)
+
+    events.done(
+        "offline",
+        f"[offline] Done — {len(ok)} downloaded  {len(failed)} failed  "
+        f"→ {target}  (DISM injects offline next)",
+        total=len(downloaded), ok=len(ok), failed=len(failed),
+        target_dir=str(target),
+    )
+
+    return OfflineResult(
+        downloaded_ok=ok,
+        download_failed=failed,
+        not_found=result.not_found,
+        trace_id=result.trace_id,
+        target_dir=str(target),
+    )

{driverclient-0.2.19 → driverclient-0.2.21}/src/driverclient/ops/resolve.py

@@ -54,11 +54,17 @@ class ResolveResult:
         return bool(self.not_found or self.stale)
 
 
-def resolve(force: bool = False) -> ResolveResult:
+def resolve(force: bool = False, offline: bool = False) -> ResolveResult:
     """
     Load (or run) a hardware scan, then POST to /resolve.
     Returns ResolveResult with drivers[] and not_found[].
     Saves result to ds_resolve.json.
+
+    offline: pre-boot / WinPE mode. The scan runs against WinPE, not the applied
+    image, so any "installed" versions it sees are irrelevant to the target. Send
+    installed_versions empty (and no inbox hints) so the server offers the FULL
+    matched set — every physically-present device's driver, GPU included — to be
+    DISM-injected into the fresh image. See ops/offline.py.
     """
     cfg = get()
 
@@ -69,10 +75,11 @@ def resolve(force: bool = False) -> ResolveResult:
             return cached
 
     scan_result: ScanResult = scan(force=force)
-    return _query_repo(scan_result, cfg, force)
+    return _query_repo(scan_result, cfg, force, offline)
 
 
-def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResult:
+def _query_repo(scan_result: ScanResult, cfg: dict, force: bool,
+                offline: bool = False) -> ResolveResult:
     repo_url   = cfg["local_repo_url"]
     session_id = str(uuid.uuid4())
 
@@ -112,8 +119,11 @@ def _query_repo(scan_result: ScanResult, cfg: dict, force: bool) -> ResolveResul
         "firmware_version":   scan_result.firmware_version,
         "hwids":              scan_result.all_hwids,
         "hwid_groups":        hwid_groups,
-        "inbox_hwids":        inbox_ids,
-        "installed_versions": {**scan_result.installed_versions, **canon_versions},
+        # Offline: no inbox hints and empty installed_versions → server offers the
+        # full matched set for the fresh image (nothing counts as already-current).
+        "inbox_hwids":        [] if offline else inbox_ids,
+        "installed_versions": {} if offline
+                              else {**scan_result.installed_versions, **canon_versions},
         "force":              force or cfg.get("force_resolve", False),
     }