packet-tracer-skill 0.2.3 → 0.3.0

package/scripts/runtime_doctor.py

@@ -39,24 +39,25 @@ def _packet_tracer_os_name(host_os: str) -> str:
 
 
 def runtime_env_examples(host_os: str) -> list[str]:
+    # PKT_TWOFISH_* is optional: it selects the compiled accelerator. The
+    # vendored pure-Python engine is used automatically when it is absent.
     if host_os == "Windows":
         return [
             r"$env:PACKET_TRACER_ROOT='C:\Program Files\Cisco Packet Tracer 9.0.0'",
             r"$env:PACKET_TRACER_COMPAT_DONOR='C:\path\to\your-working-9.0-donor.pkt'",
-            r'$env:PKT_TWOFISH_LIBRARY="C:\path\to\_twofish.cp314-win_amd64.pyd"',
-            r'$env:PKT_TWOFISH_SEARCH_ROOTS="C:\path\to\bridge-folder"',
+            r'# optional speed-up: $env:PKT_TWOFISH_LIBRARY="C:\path\to\_twofish.cp314-win_amd64.pyd"',
         ]
     if host_os == "macOS":
         return [
             "export PACKET_TRACER_ROOT='/Applications/Cisco Packet Tracer.app/Contents/Resources'",
             "export PACKET_TRACER_COMPAT_DONOR=\"$HOME/path/to/your-working-9.0-donor.pkt\"",
-            "export PKT_TWOFISH_SEARCH_ROOTS=\"$HOME/path/to/bridge-folder:$HOME/pkt-bridges\"",
+            "# optional speed-up: export PKT_TWOFISH_SEARCH_ROOTS=\"$HOME/pkt-bridges\"",
         ]
     if host_os == "Linux":
         return [
             "export PACKET_TRACER_ROOT='/opt/pt/bin'",
             "export PACKET_TRACER_COMPAT_DONOR=\"$HOME/path/to/your-working-9.0-donor.pkt\"",
-            "export PKT_TWOFISH_SEARCH_ROOTS=\"$HOME/path/to/bridge-folder:$HOME/pkt-bridges\"",
+            "# optional speed-up: export PKT_TWOFISH_SEARCH_ROOTS=\"$HOME/pkt-bridges\"",
         ]
     return []
 
@@ -71,8 +72,8 @@ def _best_next_fix(runtime_blockers: list[str], recommended_next_steps: list[str
         "missing_twofish_bridge": "Fix the Twofish bridge next so strict decode/edit/generate can run locally.",
         "missing_packet_tracer_root": "Fix PACKET_TRACER_ROOT so the doctor can resolve the install layout deterministically.",
         "missing_packet_tracer_executable": "Fix the Packet Tracer install root or executable path before relying on validate_open.",
-        "windows_first_runtime": "Do not assume non-Windows strict runtime support without a custom native bridge and explicit Packet Tracer paths.",
-        "using_external_bridge_only": "Move the external bridge into the repo-local vendor path if you need a self-contained runtime claim.",
+        "windows_first_runtime": "Set PACKET_TRACER_ROOT so the Packet Tracer executable resolves on this host.",
+        "using_external_bridge_only": "Verify the vendored pure-Python Twofish engine; the external compiled bridge is only an accelerator.",
     }
     for blocker in runtime_blockers:
         if blocker in blocker_map:
@@ -94,7 +95,7 @@ def _why_it_is_blocked(runtime_blockers: list[str], bridge_resolution: str) -> s
         reasons.append("Packet Tracer executable is not resolved")
     if "windows_first_runtime" in runtime_blockers:
         reasons.append("strict bundled validation is still Windows-first")
-    if bridge_resolution == "external_env":
+    if bridge_resolution == "external_env" and "using_external_bridge_only" in runtime_blockers:
         reasons.append("strict runtime currently relies on an external bridge override")
     return "; ".join(reasons) + "."
 
@@ -116,9 +117,9 @@ def build_recommended_next_steps(
 ) -> list[str]:
     guidance: list[str] = []
     if not runtime_supported:
-        guidance.append(f"Real runtime is still Windows-first: {runtime_message}")
+        guidance.append(runtime_message)
     if python_support_status != "ok":
-        guidance.append("Use Python 3.14.x for Packet Tracer 9.0 encode/decode.")
+        guidance.append("Use Python 3.10 or newer.")
     if packet_tracer_root is None and recommended_root:
         guidance.append(f"Set PACKET_TRACER_ROOT to {recommended_root}.")
     if donor_status != "ok":
@@ -147,7 +148,7 @@ def build_recommended_next_steps(
         message.append("or set PKT_TWOFISH_LIBRARY / PKT_TWOFISH_SEARCH_ROOTS.")
         guidance.append(" ".join(message))
     if host_os in {"macOS", "Linux"} and not runtime_supported:
-        guidance.append("For non-Windows hosts, install a native Twofish bridge before expecting real .pkt runtime support.")
+        guidance.append("On non-Windows hosts set PACKET_TRACER_ROOT explicitly; the codec itself needs no extra setup.")
     return guidance
 
 
@@ -176,14 +177,27 @@ def collect_runtime_doctor() -> dict[str, object]:
             bridge_resolution = "external_env"
     else:
         bridge_resolution = "missing"
+    twofish_backend = str(twofish.get("twofish_backend") or "")
 
-    runtime_supported = host_os == "Windows"
-    if runtime_supported:
-        runtime_message = "validated Windows Packet Tracer 9.0 runtime path"
-    elif twofish.get("resolved_twofish_path"):
-        runtime_message = "custom native runtime may work, but bundled validation is still Windows-first"
+    # The Windows-only restriction existed because the codec needed a compiled
+    # Twofish bridge that was only ever built for Windows. The vendored
+    # pure-Python engine removed that dependency, and `packet_tracer_env` already
+    # resolves install layouts for macOS and Linux, so any host with Packet Tracer
+    # installed is supported. What differs by platform is how much has been
+    # exercised in practice, which is a confidence note, not a blocker.
+    runtime_supported = packet_tracer_exe is not None
+    if runtime_supported and host_os == "Windows":
+        runtime_message = f"resolved Windows Packet Tracer runtime at {packet_tracer_exe}"
+    elif runtime_supported:
+        runtime_message = (
+            f"resolved {host_os} Packet Tracer runtime at {packet_tracer_exe}. "
+            "Non-Windows hosts are supported but less exercised; verify a generated file opens."
+        )
     else:
-        runtime_message = "needs custom Packet Tracer paths and a non-Windows native Twofish bridge"
+        runtime_message = (
+            "no Packet Tracer executable was resolved. Decode, inventory and edit still work; "
+            "set PACKET_TRACER_ROOT to enable validate_open."
+        )
 
     blocking_reasons: list[str] = []
     if twofish.get("python_support_status") != "ok":
@@ -201,7 +215,7 @@ def collect_runtime_doctor() -> dict[str, object]:
     if packet_tracer_root is None:
         blocking_reasons.append("packet_tracer_root:not_set")
     if not runtime_supported:
-        blocking_reasons.append(f"runtime_os:{host_os}")
+        blocking_reasons.append("packet_tracer_executable:not_resolved")
 
     recommended_next_steps = build_recommended_next_steps(
         host_os=host_os,
@@ -235,9 +249,18 @@ def collect_runtime_doctor() -> dict[str, object]:
         runtime_blockers.append("missing_packet_tracer_root")
     if packet_tracer_exe is None:
         runtime_blockers.append("missing_packet_tracer_executable")
-    if not runtime_supported:
-        runtime_blockers.append("windows_first_runtime")
-    if bridge_resolution == "external_env" and "using_external_bridge_only" not in runtime_blockers:
+    # `windows_first_runtime` is no longer raised: a missing Packet Tracer
+    # executable is already reported as `missing_packet_tracer_executable`, and
+    # the host OS by itself no longer blocks anything.
+    # An externally-resolved compiled bridge is no longer a runtime blocker: it is
+    # an optional accelerator over the vendored pure-Python engine, which is always
+    # repo-local. Only flag it when the pure engine itself could not be verified.
+    if (
+        bridge_resolution == "external_env"
+        and twofish_backend != "pure_python"
+        and str(twofish.get("twofish_load_status")) != "ok"
+        and "using_external_bridge_only" not in runtime_blockers
+    ):
         runtime_blockers.append("using_external_bridge_only")
     if runtime_blockers:
         runtime_grade = "blocked" if len(ready_operations) == 0 else "partially_ready"
@@ -281,20 +304,43 @@ def collect_runtime_doctor() -> dict[str, object]:
     )
     why_it_is_blocked = _why_it_is_blocked(runtime_blockers, bridge_resolution)
     best_next_fix = _best_next_fix(runtime_blockers, recommended_next_steps)
-    bridge_recommendation = (
-        "Use or install a repo-local vendor bridge for fully self-contained runtime readiness."
-        if bridge_resolution == "external_env"
-        else "Provide PKT_TWOFISH_LIBRARY or PKT_TWOFISH_SEARCH_ROOTS to resolve a local bridge."
-        if bridge_resolution == "missing"
-        else "Repo-local bridge is resolved."
-    )
+    if twofish_backend == "pure_python":
+        bridge_recommendation = (
+            "Vendored pure-Python Twofish is in use; no bridge is required. "
+            "A compiled bridge is optional and only speeds up large labs (~12x)."
+        )
+    elif bridge_resolution == "external_env":
+        bridge_recommendation = (
+            "A compiled accelerator is being used from an external path. "
+            "This is optional; the vendored pure-Python engine is the supported baseline."
+        )
+    elif bridge_resolution == "missing":
+        bridge_recommendation = "Provide PKT_TWOFISH_LIBRARY or PKT_TWOFISH_SEARCH_ROOTS to resolve a local bridge."
+    else:
+        bridge_recommendation = "Repo-local bridge is resolved."
     runtime_contract_notes = (
-        "Repo-local bridge and donor are present, so this checkout can run strict decode/edit/generate locally."
+        "The vendored pure-Python Twofish engine is repo-local, so this checkout can run strict "
+        "decode/edit/generate with no binaries and no environment variables."
+        if twofish_backend == "pure_python"
+        else "Repo-local bridge and donor are present, so this checkout can run strict decode/edit/generate locally."
         if bridge_resolution == "repo_local"
         else "Strict decode/edit/generate currently rely on an external bridge path. Repo-local runtime packaging is still incomplete."
         if bridge_resolution == "external_env"
         else "No bridge is resolved. validate_open may still work when Packet Tracer is installed, but strict decode/edit/generate remain blocked."
     )
+    strict_gate_ready = twofish.get("twofish_load_status") == "ok"
+    runtime_gate_status = {
+        "default_gate": "unit/doc surface can pass; requires_twofish tests skip when the bridge is missing",
+        "strict_gate": "requires PKT_REQUIRE_TWOFISH_TESTS=1 plus PKT_TWOFISH_LIBRARY or PKT_TWOFISH_SEARCH_ROOTS",
+        "strict_gate_ready": strict_gate_ready,
+        "strict_gate_command": "PKT_REQUIRE_TWOFISH_TESTS=1 python -m pytest tests -q",
+    }
+    user_summary = {
+        "status": runtime_grade,
+        "message": doctor_summary,
+        "next_best_action": best_next_fix,
+        "runtime_gate_status": runtime_gate_status,
+    }
 
     return {
         "host_os": host_os,
@@ -303,7 +349,7 @@ def collect_runtime_doctor() -> dict[str, object]:
             "message": "supported" if installer_supported else "unknown host platform",
         },
         "real_pkt_runtime_support": {
-            "status": "validated" if runtime_supported else "windows_first",
+            "status": "validated" if runtime_supported else "packet_tracer_not_resolved",
             "message": runtime_message,
         },
         "env_examples": runtime_env_examples(host_os),
@@ -320,6 +366,7 @@ def collect_runtime_doctor() -> dict[str, object]:
         "twofish_search_roots": resolved_search_roots,
         "resolved_twofish_path": resolved_twofish_path,
         "twofish_source": twofish.get("twofish_source", ""),
+        "twofish_backend": twofish.get("twofish_backend", ""),
         "twofish_load_status": twofish.get("twofish_load_status", "unknown"),
         "twofish_message": twofish.get("twofish_message", "unknown"),
         "twofish_sha256": twofish.get("twofish_sha256", ""),
@@ -330,6 +377,8 @@ def collect_runtime_doctor() -> dict[str, object]:
         "target_version": donor.get("target_version", ""),
         "resolved_donor_path": donor.get("resolved_donor_path", ""),
         "donor_version": donor.get("donor_version", ""),
+        "donor_policy": donor.get("donor_policy", ""),
+        "donor_compatibility_tier": donor.get("compatibility_tier", ""),
         "donor_source": donor.get("donor_source", ""),
         "donor_status": donor.get("status", "unknown"),
         "donor_message": donor.get("message", "unknown"),
@@ -343,6 +392,8 @@ def collect_runtime_doctor() -> dict[str, object]:
         "what_is_blocked": what_is_blocked,
         "why_it_is_blocked": why_it_is_blocked,
         "best_next_fix": best_next_fix,
+        "user_summary": user_summary,
+        "runtime_gate_status": runtime_gate_status,
         "doctor_summary": doctor_summary,
         "runtime_grade": runtime_grade,
         "recommended_next_steps": recommended_next_steps,