bdo-toolkit 1.0.4__tar.gz → 1.0.5__tar.gz

{bdo_toolkit-1.0.4/src/bdo_toolkit.egg-info → bdo_toolkit-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.4
+Version: 1.0.5
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -37,16 +37,27 @@ Dynamic: license-file
 Passive, read-only Python tooling that turns live or recorded Black Desert
 traffic into structured, application-ready data.
 
-[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
-[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
-[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
-[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
+[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
+[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
+[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
 [Report an issue](https://github.com/ychwu/bdo-toolkit/issues)
 
 > **Passive, read-only boundary.** bdo-toolkit observes local traffic or saved
 > captures. It does not send or modify packets, replay traffic to the game,
 > automate gameplay, inspect process memory, or bypass anti-cheat software.
 
+## Live-capture limitations
+
+Live capture depends heavily on your network setup and on whether the capture
+backend can see BDO traffic. VPNs and routing services such as ExitLag may require
+manual interface, local IP, and port settings; automatic detection may select the
+wrong connection. Traffic visible only as an encrypted tunnel cannot be decoded.
+Follow [Diagnose capture when automatic selection fails](https://ychwu.github.io/bdo-toolkit/#capture-foundation/diagnose-network)
+to inspect connections on Windows, select grouped capture settings, and verify
+them with game activity. The guide covers VPNs, local proxies, and cases where
+no usable adapter is found. Discovery does not apply settings or verify decoding.
+
 ## Capabilities
 
 bdo-toolkit exposes three passive workflows. Each can observe live traffic or
@@ -104,7 +115,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
-| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.5}/README.md

@@ -10,16 +10,27 @@
 Passive, read-only Python tooling that turns live or recorded Black Desert
 traffic into structured, application-ready data.
 
-[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
-[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
-[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
-[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
+[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
+[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
+[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
 [Report an issue](https://github.com/ychwu/bdo-toolkit/issues)
 
 > **Passive, read-only boundary.** bdo-toolkit observes local traffic or saved
 > captures. It does not send or modify packets, replay traffic to the game,
 > automate gameplay, inspect process memory, or bypass anti-cheat software.
 
+## Live-capture limitations
+
+Live capture depends heavily on your network setup and on whether the capture
+backend can see BDO traffic. VPNs and routing services such as ExitLag may require
+manual interface, local IP, and port settings; automatic detection may select the
+wrong connection. Traffic visible only as an encrypted tunnel cannot be decoded.
+Follow [Diagnose capture when automatic selection fails](https://ychwu.github.io/bdo-toolkit/#capture-foundation/diagnose-network)
+to inspect connections on Windows, select grouped capture settings, and verify
+them with game activity. The guide covers VPNs, local proxies, and cases where
+no usable adapter is found. Discovery does not apply settings or verify decoding.
+
 ## Capabilities
 
 bdo-toolkit exposes three passive workflows. Each can observe live traffic or
@@ -77,7 +88,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
-| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.5}/src/bdo_toolkit/__init__.py

@@ -3,6 +3,7 @@
 from ._async_sessions import AsyncCalibrationSession, AsyncLiveCaptureSession
 from ._capture_options import LiveCaptureOptions, PacketCaptureOptions
 from ._capture_runtime import CaptureEndpoint
+from .capture_diagnosis import CaptureCandidate, CaptureDiagnosis, CaptureSettingsProposal, diagnose_capture
 from .capture import (
     CaptureIntegrityError,
     LiveCaptureHealth,
@@ -48,6 +49,10 @@ __all__ = [
     "AsyncLiveCaptureSession",
     "BDOEvent",
     "CaptureEndpoint",
+    "CaptureCandidate",
+    "CaptureDiagnosis",
+    "CaptureSettingsProposal",
+    "diagnose_capture",
     "CaptureIntegrityError",
     "ConsoleEventWriter",
     "DecoderDiagnostic",

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.5}/src/bdo_toolkit/_version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the BDO Toolkit release version."""
 
-__version__ = "1.0.4"
+__version__ = "1.0.5"

bdo_toolkit-1.0.5/src/bdo_toolkit/capture_diagnosis.py

@@ -0,0 +1,246 @@
+"""Read-only Windows connection discovery; candidates are not capture validation."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+import ipaddress
+import json
+import math
+import subprocess
+import sys
+from typing import Any, Literal
+
+from ._capture_options import LiveCaptureOptions
+from ._protocol import DEFAULT_SERVER_PORTS
+
+
+@dataclass(frozen=True)
+class CaptureCandidate:
+    """One observed game connection mapped to a capture adapter, if available."""
+
+    process_id: int
+    local_ip: str
+    local_port: int
+    remote_ip: str
+    remote_port: int
+    interface: str | None
+    peer_process: str | None
+    kind: Literal["local_proxy", "game_port", "other_tcp"]
+    explanation: str
+
+    def to_live_options(self) -> LiveCaptureOptions:
+        """Build explicit options; reject candidates without a matching adapter."""
+        if self.interface is None:
+            raise ValueError("No matching capture adapter; manual investigation required")
+        return LiveCaptureOptions(
+            interface=self.interface, local_ip=self.local_ip,
+            ports=(self.remote_port,),
+        )
+
+
+@dataclass(frozen=True)
+class CaptureSettingsProposal:
+    """Compatible connections grouped for one explicit capture configuration."""
+
+    process_id: int
+    interface: str | None
+    local_ip: str
+    kind: Literal["local_proxy", "game_port", "other_tcp"]
+    ports: tuple[int, ...]
+    candidates: tuple[CaptureCandidate, ...]
+
+    def to_live_options(self) -> LiveCaptureOptions:
+        """Build settings with every observed port; never starts capture."""
+        if self.interface is None:
+            raise ValueError("No matching capture adapter; manual investigation required")
+        return LiveCaptureOptions(
+            interface=self.interface, local_ip=self.local_ip, ports=self.ports,
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return JSON-compatible settings and underlying connection evidence."""
+        return {
+            "process_id": self.process_id, "interface": self.interface,
+            "local_ip": self.local_ip, "kind": self.kind,
+            "ports": list(self.ports),
+            "candidates": [asdict(candidate) for candidate in self.candidates],
+        }
+
+
+@dataclass(frozen=True)
+class CaptureDiagnosis:
+    """Snapshot of candidates and limitations; never automatically applied."""
+
+    status: Literal["candidates", "no_game", "no_connections", "unavailable"]
+    candidates: tuple[CaptureCandidate, ...] = ()
+    messages: tuple[str, ...] = ()
+
+    @property
+    def proposals(self) -> tuple[CaptureSettingsProposal, ...]:
+        """Group by process, adapter, local address, and kind in evidence order.
+
+        Local proxies additionally match peer address and process name. When
+        ownership is unknown, different peer ports remain separate. Candidates
+        without matching adapters remain visible but cannot produce options.
+        """
+        groups: dict[tuple[object, ...], list[CaptureCandidate]] = {}
+        for candidate in self.candidates:
+            key: tuple[object, ...] = (
+                candidate.process_id, candidate.interface,
+                candidate.local_ip, candidate.kind,
+            )
+            if candidate.kind == "local_proxy":
+                key += (candidate.remote_ip, candidate.peer_process)
+                if candidate.peer_process is None:
+                    key += (candidate.remote_port,)
+            groups.setdefault(key, []).append(candidate)
+        return tuple(
+            CaptureSettingsProposal(
+                process_id=group[0].process_id, interface=group[0].interface,
+                local_ip=group[0].local_ip, kind=group[0].kind,
+                ports=tuple(sorted({candidate.remote_port for candidate in group})),
+                candidates=tuple(group),
+            )
+            for group in groups.values()
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return JSON-compatible diagnostic data, including local endpoints."""
+        return {
+            "status": self.status,
+            "candidates": [asdict(candidate) for candidate in self.candidates],
+            "messages": list(self.messages),
+            "proposals": [proposal.to_dict() for proposal in self.proposals],
+        }
+
+
+# Fixed script: no user text is interpolated into PowerShell. Read the connection
+# table once, and correlate local proxies by the exact reversed TCP four-tuple.
+_WINDOWS_SNAPSHOT = r"""
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$processes = @(Get-Process)
+$games = @($processes | Where-Object { $_.ProcessName -in @('BlackDesert64', 'BlackDesert') })
+$connections = @(Get-NetTCPConnection)
+$rows = @($connections | Where-Object { $_.State -eq 'Established' -and $_.OwningProcess -in $games.Id } | ForEach-Object {
+    $connection = $_
+    $peer = $connections | Where-Object {
+        $_.LocalAddress -eq $connection.RemoteAddress -and $_.LocalPort -eq $connection.RemotePort -and
+        $_.RemoteAddress -eq $connection.LocalAddress -and $_.RemotePort -eq $connection.LocalPort
+    } | Select-Object -First 1
+    $peerName = $null
+    if ($null -ne $peer) { $peerName = ($processes | Where-Object { $_.Id -eq $peer.OwningProcess } | Select-Object -First 1).ProcessName }
+    @{ process_id = [int]$connection.OwningProcess; local_ip = $connection.LocalAddress;
+       local_port = [int]$connection.LocalPort; remote_ip = $connection.RemoteAddress;
+       remote_port = [int]$connection.RemotePort; peer_process = $peerName }
+})
+@{ game_count = $games.Count; connections = $rows } | ConvertTo-Json -Depth 4 -Compress
+"""
+
+
+def _windows_snapshot(timeout: float) -> dict[str, Any]:
+    result = subprocess.run(
+        ["powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-Command", _WINDOWS_SNAPSHOT],
+        capture_output=True, encoding="utf-8", errors="replace", timeout=timeout,
+        # subprocess exposes this constant only on Windows. Discovery already
+        # gates this helper by platform; getattr also permits non-Windows typing.
+        creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+    )
+    if result.returncode:
+        raise RuntimeError("Windows connection inspection failed; check permissions and NetTCPIP availability")
+    value = json.loads(result.stdout.lstrip("\ufeff"))
+    if not isinstance(value, dict) or not isinstance(value.get("connections"), list):
+        raise ValueError("Unexpected Windows connection snapshot")
+    if type(value.get("game_count")) is not int or value["game_count"] < 0:
+        raise ValueError("Unexpected Windows process count")
+    for row in value["connections"]:
+        if not isinstance(row, dict):
+            raise ValueError("Unexpected Windows connection row")
+        for name in ("local_ip", "remote_ip"):
+            if not isinstance(row.get(name), str):
+                raise ValueError("Missing Windows connection address")
+            ipaddress.ip_address(row[name])
+        for name, maximum in (("process_id", 0xFFFFFFFF), ("local_port", 65535), ("remote_port", 65535)):
+            if type(row.get(name)) is not int or not 1 <= row[name] <= maximum:
+                raise ValueError("Invalid Windows connection identifier or port")
+        if "peer_process" not in row or not isinstance(row["peer_process"], (str, type(None))):
+            raise ValueError("Invalid Windows peer process name")
+    return value
+
+
+def _capture_adapters() -> list[tuple[str, tuple[str, ...]]]:
+    from scapy.all import conf  # type: ignore
+
+    conf.ifaces.reload()
+    return [
+        (str(adapter.network_name), tuple(str(ip) for ip in adapter.ips.get(4, [])))
+        for adapter in conf.ifaces.values()
+    ]
+
+
+def diagnose_capture(*, timeout: float = 15.0) -> CaptureDiagnosis:
+    """Inspect Windows BDO TCP connections and capture interfaces.
+
+    ``timeout`` bounds the Windows subprocess, not Scapy adapter enumeration.
+    Call from a worker in GUI applications. No packets are captured, no profile
+    is needed, and no settings are applied. IPv6 connections are reported as a
+    limitation. Other platforms return ``unavailable``. Operational inspection
+    failures are returned in messages; invalid timeout values raise ValueError.
+    Proxy ports and process IDs are valid only for the observed session.
+    """
+    if isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError("timeout must be finite and greater than zero")
+    if sys.platform != "win32":
+        return CaptureDiagnosis("unavailable", messages=("Connection discovery currently supports Windows only.",))
+    try:
+        snapshot = _windows_snapshot(timeout)
+    except subprocess.TimeoutExpired:
+        return CaptureDiagnosis("unavailable", messages=(
+            f"Windows connection inspection timed out after {timeout:g} seconds; retry or increase timeout.",
+        ))
+    except (OSError, RuntimeError, ValueError) as exc:
+        return CaptureDiagnosis("unavailable", messages=(f"Could not inspect BDO connections: {exc}",))
+    if not snapshot["game_count"]:
+        return CaptureDiagnosis("no_game", messages=("Start Black Desert, enter the game, and retry.",))
+    messages = ["Candidates are unverified: test with known in-game activity. No settings were changed."]
+    try:
+        adapters = _capture_adapters()
+    except Exception as exc:
+        adapters = []
+        messages.append(f"Could not enumerate capture adapters: {exc}")
+    candidates: list[CaptureCandidate] = []
+    for row in snapshot["connections"]:
+        local = ipaddress.ip_address(row["local_ip"])
+        remote = ipaddress.ip_address(row["remote_ip"])
+        if local.version != 4 or remote.version != 4:
+            messages.append("An established BDO IPv6 connection was skipped: capture decoding supports IPv4 only.")
+            continue
+        interfaces = sorted({
+            name for name, ips in adapters
+            if str(local) in ips or (local.is_loopback and name == r"\Device\NPF_Loopback")
+        })
+        kind: Literal["local_proxy", "game_port", "other_tcp"]
+        if local.is_loopback and remote.is_loopback:
+            kind = "local_proxy"
+            explanation = "BDO connects through a local TCP peer; capture loopback using the peer port. Recheck after reconnecting."
+        elif row["remote_port"] in DEFAULT_SERVER_PORTS:
+            kind = "game_port"
+            explanation = "Connection uses a default BDO game port; verify traffic is visible on this adapter."
+        else:
+            kind = "other_tcp"
+            explanation = "Nonstandard TCP peer; may be web, authentication, or other traffic rather than gameplay."
+        if not interfaces:
+            explanation += " No capture adapter matches the local IPv4 address."
+        if len(interfaces) > 1:
+            explanation += " Multiple adapters match; test each candidate explicitly."
+        matches: list[str | None] = list(interfaces) if interfaces else [None]
+        for interface in matches:
+            candidates.append(CaptureCandidate(
+                process_id=row["process_id"], local_ip=str(local), local_port=row["local_port"],
+                remote_ip=str(remote), remote_port=row["remote_port"], interface=interface,
+                peer_process=row["peer_process"], kind=kind, explanation=explanation,
+            ))
+    candidates.sort(key=lambda c: ({"local_proxy": 0, "game_port": 1, "other_tcp": 2}[c.kind], c.process_id, c.local_port, c.interface or ""))
+    if not candidates:
+        messages.append("No established IPv4 TCP candidates found. Enter a game server and retry.")
+    return CaptureDiagnosis("candidates" if candidates else "no_connections", tuple(candidates), tuple(dict.fromkeys(messages)))

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.5}/src/bdo_toolkit/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import math
 import sys
 from pathlib import Path
@@ -11,6 +12,7 @@ from typing import Optional
 from . import __version__
 from ._capture_options import LiveCaptureOptions, PacketCaptureOptions
 from .capture import capture_live, replay_pcap
+from .capture_diagnosis import diagnose_capture
 from .diagnostics import DecoderDiagnostic
 from ._protocol import DEFAULT_SERVER_PORTS
 from .calibration import (
@@ -544,6 +546,27 @@ def _run_origin_promote(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_diagnose_capture(args: argparse.Namespace) -> int:
+    result = diagnose_capture(timeout=args.timeout)
+    if args.json:
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print(f"Capture discovery: {result.status}")
+        for message in result.messages:
+            print(message)
+        for number, proposal in enumerate(result.proposals, 1):
+            print(f"\n{number}. {proposal.kind} (BDO PID {proposal.process_id})")
+            print(f"   Interface: {proposal.interface or '(no matching adapter)'}")
+            print(f"   Local IP: {proposal.local_ip}; ports: {','.join(map(str, proposal.ports))}")
+            for explanation in dict.fromkeys(c.explanation for c in proposal.candidates):
+                print(f"   {explanation}")
+            print(f"   Connections: {len(proposal.candidates)}")
+            for candidate in proposal.candidates:
+                peer = f" ({candidate.peer_process})" if candidate.peer_process else ""
+                print(f"     {candidate.local_ip}:{candidate.local_port} -> {candidate.remote_ip}:{candidate.remote_port}{peer}")
+    return 2 if result.status == "unavailable" else 0
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="bdo-toolkit",
@@ -557,6 +580,12 @@ def build_parser() -> argparse.ArgumentParser:
         "--version", action="version", version=f"%(prog)s {__version__}"
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
+    diagnose = subparsers.add_parser(
+        "diagnose-capture", help="inspect Windows BDO connections and suggest capture settings",
+    )
+    diagnose.add_argument("--json", action="store_true", help="print structured JSON")
+    diagnose.add_argument("--timeout", type=_positive_float, default=15.0, help="Windows inspection timeout in seconds (default: 15)")
+    diagnose.set_defaults(func=_run_diagnose_capture)
 
     profile = subparsers.add_parser(
         "profile",

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.5/src/bdo_toolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bdo-toolkit
-Version: 1.0.4
+Version: 1.0.5
 Summary: Passive, read-only BDO packet parsing toolkit for app developers.
 Author: bdo-toolkit contributors
 License-Expression: MIT
@@ -37,16 +37,27 @@ Dynamic: license-file
 Passive, read-only Python tooling that turns live or recorded Black Desert
 traffic into structured, application-ready data.
 
-[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
-[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
-[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
-[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
+[Documentation](https://ychwu.github.io/bdo-toolkit/) ·
+[Quickstart](https://ychwu.github.io/bdo-toolkit/#quickstart) ·
+[Examples](https://ychwu.github.io/bdo-toolkit/#item-examples) ·
+[API index](https://ychwu.github.io/bdo-toolkit/#api-index) ·
 [Report an issue](https://github.com/ychwu/bdo-toolkit/issues)
 
 > **Passive, read-only boundary.** bdo-toolkit observes local traffic or saved
 > captures. It does not send or modify packets, replay traffic to the game,
 > automate gameplay, inspect process memory, or bypass anti-cheat software.
 
+## Live-capture limitations
+
+Live capture depends heavily on your network setup and on whether the capture
+backend can see BDO traffic. VPNs and routing services such as ExitLag may require
+manual interface, local IP, and port settings; automatic detection may select the
+wrong connection. Traffic visible only as an encrypted tunnel cannot be decoded.
+Follow [Diagnose capture when automatic selection fails](https://ychwu.github.io/bdo-toolkit/#capture-foundation/diagnose-network)
+to inspect connections on Windows, select grouped capture settings, and verify
+them with game activity. The guide covers VPNs, local proxies, and cases where
+no usable adapter is found. Discovery does not apply settings or verify decoding.
+
 ## Capabilities
 
 bdo-toolkit exposes three passive workflows. Each can observe live traffic or
@@ -104,7 +115,7 @@ installed with the Python wheel.
 | Observe live item activity | [`examples/live_transfer_log.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_transfer_log.py) |
 | Capture inventory and town storage on character load | [`examples/live_character_load_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_character_load_snapshot.py) |
 | Rebuild an item profile after a patch | [`examples/live_calibrate_profile.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibrate_profile.py) |
-| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
+| Observe calibration progress and stop on completion | [`examples/live_calibration_progress.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/live_calibration_progress.py) · [async](https://github.com/ychwu/bdo-toolkit/blob/main/examples/async_calibration_progress.py) |
 | Capture an Arena of Solare leaderboard load | [`examples/solare_live_snapshot.py`](https://github.com/ychwu/bdo-toolkit/blob/main/examples/solare_live_snapshot.py) |
 
 See the [Examples index](https://ychwu.github.io/bdo-toolkit/#item-examples)

{bdo_toolkit-1.0.4 → bdo_toolkit-1.0.5}/src/bdo_toolkit.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ src/bdo_toolkit/_storage_hydration.py
 src/bdo_toolkit/_version.py
 src/bdo_toolkit/calibration.py
 src/bdo_toolkit/capture.py
+src/bdo_toolkit/capture_diagnosis.py
 src/bdo_toolkit/character_state.py
 src/bdo_toolkit/cli.py
 src/bdo_toolkit/diagnostics.py
@@ -88,6 +89,7 @@ tests/test_calibration_persistence.py
 tests/test_calibration_progress.py
 tests/test_calibration_retention.py
 tests/test_capture_backend.py
+tests/test_capture_diagnosis.py
 tests/test_capture_replay.py
 tests/test_capture_runtime.py
 tests/test_character_state.py

bdo_toolkit-1.0.5/tests/test_capture_diagnosis.py

@@ -0,0 +1,215 @@
+"""Synthetic network discovery: no game, capture driver, or network required."""
+
+import json
+import subprocess
+
+import pytest
+
+from bdo_toolkit import CaptureDiagnosis, diagnose_capture, cli
+from bdo_toolkit import capture_diagnosis as diagnosis
+
+
+def connection(**changes):
+    row = dict(process_id=12, local_ip="192.0.2.2", local_port=50000,
+               remote_ip="198.51.100.1", remote_port=8889, peer_process=None)
+    row.update(changes)
+    return row
+
+
+@pytest.fixture
+def snapshot(monkeypatch):
+    data = {"game_count": 1, "connections": [connection()]}
+    monkeypatch.setattr(diagnosis.sys, "platform", "win32")
+    monkeypatch.setattr(diagnosis, "_windows_snapshot", lambda timeout: data)
+    monkeypatch.setattr(diagnosis, "_capture_adapters", lambda: [
+        ("ethernet", ("192.0.2.2",)), (r"\Device\NPF_Loopback", ("127.0.0.1",)),
+    ])
+    return data
+
+
+def test_direct_and_web_connections_are_distinguished(snapshot):
+    snapshot["connections"].append(connection(remote_port=443, local_port=50001))
+    result = diagnose_capture()
+    assert result.status == "candidates"
+    assert [c.kind for c in result.candidates] == ["game_port", "other_tcp"]
+    options = result.candidates[0].to_live_options()
+    assert (options.interface, options.local_ip, options.ports) == ("ethernet", "192.0.2.2", (8889,))
+    assert json.loads(json.dumps(result.to_dict()))["status"] == "candidates"
+
+
+def test_proxy_uses_current_peer_port_and_loopback(snapshot):
+    snapshot["connections"] = [connection(local_ip="127.0.0.2", remote_ip="127.0.0.1",
+                                          remote_port=53123, peer_process="ExitLag")]
+    candidate, = diagnose_capture().candidates
+    assert candidate.kind == "local_proxy"
+    assert candidate.peer_process == "ExitLag"
+    options = candidate.to_live_options()
+    assert options.interface == r"\Device\NPF_Loopback"
+    assert options.ports == (53123,)
+    assert options.local_ip == "127.0.0.2"
+
+
+def test_unidentified_proxy_still_has_evidence(snapshot):
+    snapshot["connections"] = [connection(local_ip="127.0.0.1", remote_ip="127.0.0.1", remote_port=53000)]
+    candidate, = diagnose_capture().candidates
+    assert candidate.peer_process is None
+    assert candidate.kind == "local_proxy"
+
+
+def test_missing_adapter_does_not_fall_back_to_default(snapshot, monkeypatch):
+    monkeypatch.setattr(diagnosis, "_capture_adapters", lambda: [])
+    candidate, = diagnose_capture().candidates
+    assert candidate.interface is None
+    with pytest.raises(ValueError, match="No matching"):
+        candidate.to_live_options()
+
+
+def test_ambiguous_adapters_are_all_returned(snapshot, monkeypatch):
+    monkeypatch.setattr(diagnosis, "_capture_adapters", lambda: [("a", ("192.0.2.2",)), ("b", ("192.0.2.2",))])
+    result = diagnose_capture()
+    assert [c.interface for c in result.candidates] == ["a", "b"]
+    assert all("Multiple adapters" in c.explanation for c in result.candidates)
+
+
+def test_ipv6_is_not_suggested(snapshot):
+    snapshot["connections"] = [connection(local_ip="::1", remote_ip="::1")]
+    result = diagnose_capture()
+    assert result.status == "no_connections"
+    assert not result.candidates
+    assert any("IPv6" in m for m in result.messages)
+
+
+def test_no_game_and_no_connections(snapshot):
+    snapshot["game_count"] = 0
+    assert diagnose_capture().status == "no_game"
+    snapshot.update(game_count=1, connections=[])
+    assert diagnose_capture().status == "no_connections"
+
+
+@pytest.mark.parametrize("error", [OSError("denied"), subprocess.TimeoutExpired("powershell", 1), ValueError("bad JSON")])
+def test_inspection_failure_is_structured(snapshot, monkeypatch, error):
+    def fail(timeout):
+        raise error
+    monkeypatch.setattr(diagnosis, "_windows_snapshot", fail)
+    result = diagnose_capture()
+    assert result.status == "unavailable"
+    assert result.messages
+
+
+def test_adapter_failure_preserves_connection_evidence(snapshot, monkeypatch):
+    def fail():
+        raise RuntimeError("Npcap unavailable")
+    monkeypatch.setattr(diagnosis, "_capture_adapters", fail)
+    result = diagnose_capture()
+    assert result.candidates[0].interface is None
+    assert any("Npcap unavailable" in m for m in result.messages)
+
+
+def test_other_platform_does_not_run_powershell(monkeypatch):
+    monkeypatch.setattr(diagnosis.sys, "platform", "linux")
+    assert diagnose_capture().status == "unavailable"
+
+
+@pytest.mark.parametrize("timeout", [0, -1, float("inf"), float("nan"), True])
+def test_invalid_timeout(timeout):
+    with pytest.raises(ValueError):
+        diagnose_capture(timeout=timeout)
+
+
+def test_cli_json_and_text(snapshot, capsys):
+    assert cli.main(["diagnose-capture", "--json"]) == 0
+    assert json.loads(capsys.readouterr().out)["candidates"][0]["remote_port"] == 8889
+    assert cli.main(["diagnose-capture"]) == 0
+    output = capsys.readouterr().out
+    assert "Interface: ethernet" in output
+    assert "unverified" in output
+
+
+def test_cli_unavailable_and_timeout_validation(monkeypatch, capsys):
+    monkeypatch.setattr(cli, "diagnose_capture", lambda **kw: CaptureDiagnosis("unavailable"))
+    assert cli.main(["diagnose-capture", "--json"]) == 2
+    assert json.loads(capsys.readouterr().out)["status"] == "unavailable"
+    with pytest.raises(SystemExit):
+        cli.main(["diagnose-capture", "--timeout", "0"])
+
+
+def test_windows_collector_uses_fixed_script_timeout_and_hidden_window(monkeypatch):
+    monkeypatch.setattr(subprocess, "CREATE_NO_WINDOW", 0x08000000, raising=False)
+    def run(argv, **kwargs):
+        assert argv[-1] == diagnosis._WINDOWS_SNAPSHOT
+        assert kwargs["timeout"] == 3.0
+        assert kwargs["creationflags"] == 0x08000000
+        assert "shell" not in kwargs
+        return subprocess.CompletedProcess(argv, 0, '\ufeff' + json.dumps({"game_count": 1, "connections": [connection()]}))
+    monkeypatch.setattr(subprocess, "run", run)
+    assert diagnosis._windows_snapshot(3.0)["connections"][0]["remote_port"] == 8889
+
+
+@pytest.mark.parametrize("payload", ["invalid", "[]", '{"connections":[]}',
+    json.dumps({"game_count": 1, "connections": [connection(remote_port=0)]}),
+    json.dumps({"game_count": 1, "connections": [connection(local_ip="bad")]}),
+])
+def test_windows_collector_rejects_malformed_snapshot(monkeypatch, payload):
+    monkeypatch.setattr(subprocess, "CREATE_NO_WINDOW", 0x08000000, raising=False)
+    monkeypatch.setattr(subprocess, "run", lambda *a, **kw: subprocess.CompletedProcess(a, 0, payload))
+    with pytest.raises(ValueError):
+        diagnosis._windows_snapshot(1)
+
+
+def test_windows_collector_failure_does_not_leak_command_output(monkeypatch):
+    monkeypatch.setattr(subprocess, "CREATE_NO_WINDOW", 0x08000000, raising=False)
+    monkeypatch.setattr(subprocess, "run", lambda *a, **kw: subprocess.CompletedProcess(a, 1, "", "private command output"))
+    with pytest.raises(RuntimeError, match="inspection failed") as error:
+        diagnosis._windows_snapshot(1)
+    assert "private" not in str(error.value)
+
+
+def test_settings_proposals_merge_game_ports_but_not_web(snapshot):
+    snapshot["connections"] = [connection(remote_port=p, local_port=50000+i)
+                               for i, p in enumerate([8889, 8885, 8884, 443, 443])]
+    result = diagnose_capture()
+    game, web = result.proposals
+    assert game.ports == (8884, 8885, 8889)
+    assert game.to_live_options().ports == game.ports
+    assert web.kind == "other_tcp" and web.ports == (443,)
+    assert len(game.candidates) == 3 and len(web.candidates) == 2
+    assert len(result.candidates) == 5
+    assert result.to_dict()["proposals"][0]["ports"] == [8884, 8885, 8889]
+
+
+@pytest.mark.parametrize("change", [dict(process_id=13), dict(local_ip="192.0.2.3"),
+                                    dict(interface="another"), dict(kind="other_tcp")])
+def test_proposal_group_boundaries(change):
+    from dataclasses import replace
+    from bdo_toolkit import CaptureCandidate
+    first = CaptureCandidate(**connection(), interface="ethernet", kind="game_port", explanation="test")
+    second = replace(first, **change)
+    assert len(CaptureDiagnosis("candidates", (first, second)).proposals) == 2
+
+
+def test_proxy_grouping_preserves_unknown_ownership_boundaries():
+    from dataclasses import replace
+    from bdo_toolkit import CaptureCandidate
+    first = CaptureCandidate(**connection(local_ip="127.0.0.1", remote_ip="127.0.0.1", peer_process="ExitLag"),
+                             interface="loopback", kind="local_proxy", explanation="test")
+    second = replace(first, remote_port=53000)
+    assert len(CaptureDiagnosis("candidates", (first, second)).proposals) == 1
+    for other in [replace(second, peer_process="Other"), replace(second, remote_ip="127.0.0.2")]:
+        assert len(CaptureDiagnosis("candidates", (first, other)).proposals) == 2
+    unknown = (replace(first, peer_process=None), replace(second, peer_process=None))
+    assert len(CaptureDiagnosis("candidates", unknown).proposals) == 2
+
+
+def test_proposals_empty_and_missing_adapter(snapshot, monkeypatch):
+    assert CaptureDiagnosis("no_game").proposals == ()
+    monkeypatch.setattr(diagnosis, "_capture_adapters", lambda: [])
+    with pytest.raises(ValueError, match="No matching"):
+        diagnose_capture().proposals[0].to_live_options()
+
+
+def test_cli_consolidates_ports(snapshot, capsys):
+    snapshot["connections"] = [connection(remote_port=port) for port in (8889, 8885, 8884)]
+    assert cli.main(["diagnose-capture"]) == 0
+    output = capsys.readouterr().out
+    assert output.count("Interface:") == 1
+    assert "ports: 8884,8885,8889" in output