packet-tracer-skill 0.2.2 → 0.3.0

package/scripts/remote_search.py

@@ -14,6 +14,16 @@ import zipfile
 from intent_parser import IntentPlan
 
 GITHUB_SEARCH_API = "https://api.github.com/search/repositories"
+PERMISSIVE_LICENSES = {
+    "APACHE-2.0",
+    "BSD-2-CLAUSE",
+    "BSD-3-CLAUSE",
+    "CC0-1.0",
+    "ISC",
+    "MIT",
+    "UNLICENSE",
+}
+REMOTE_AUDIT_FILENAME = "remote-sample-audit.json"
 
 
 @dataclass
@@ -26,6 +36,25 @@ class RemoteSearchCandidate:
     import_status: str
     default_branch: str | None = None
     archive_url: str | None = None
+    candidate_promotion_status: str = "reference_only"
+    imported_file_count: int = 0
+    pkt_file_count: int = 0
+    pka_file_count: int = 0
+    readme_file_count: int = 0
+    license_file_count: int = 0
+
+
+def is_permissive_license(license_or_permission: str | None) -> bool:
+    value = (license_or_permission or "").strip().upper()
+    return value in PERMISSIVE_LICENSES
+
+
+def candidate_promotion_status(license_or_permission: str | None) -> str:
+    return "validated_curated" if is_permissive_license(license_or_permission) else "reference_only"
+
+
+def candidate_is_curated_eligible(candidate: RemoteSearchCandidate) -> bool:
+    return candidate.candidate_promotion_status == "validated_curated"
 
 
 def build_remote_search_queries(plan: IntentPlan) -> list[str]:
@@ -91,6 +120,9 @@ def search_remote_candidates(
                     import_status="discovered",
                     default_branch=item.get("default_branch"),
                     archive_url=item.get("archive_url"),
+                    candidate_promotion_status=candidate_promotion_status(
+                        str((item.get("license") or {}).get("spdx_id") or "unknown")
+                    ),
                 )
             )
             if len(candidates) >= max_results:
@@ -98,19 +130,66 @@ def search_remote_candidates(
     return candidates
 
 
+def _allowed_archive_member(filename: str) -> bool:
+    lower_name = filename.lower()
+    return (
+        lower_name.endswith(".pkt")
+        or lower_name.endswith(".pka")
+        or lower_name.endswith("readme.md")
+        or lower_name.endswith("license")
+        or lower_name.endswith("license.md")
+        or lower_name.endswith("license.txt")
+    )
+
+
+def _increment_file_counters(candidate: RemoteSearchCandidate, target: Path) -> None:
+    lower_name = target.name.lower()
+    candidate.imported_file_count += 1
+    if lower_name.endswith(".pkt"):
+        candidate.pkt_file_count += 1
+    elif lower_name.endswith(".pka"):
+        candidate.pka_file_count += 1
+    elif lower_name == "readme.md":
+        candidate.readme_file_count += 1
+    elif lower_name in {"license", "license.md", "license.txt"}:
+        candidate.license_file_count += 1
+
+
+def _clear_import_destination(dest_root: Path) -> None:
+    if not dest_root.exists():
+        return
+    for child in dest_root.iterdir():
+        if child.is_dir():
+            for nested in child.rglob("*"):
+                if nested.is_file():
+                    nested.unlink()
+            for nested_dir in sorted([item for item in child.rglob("*") if item.is_dir()], reverse=True):
+                nested_dir.rmdir()
+            child.rmdir()
+        else:
+            child.unlink()
+
+
 def auto_import_remote_candidates(
     candidates: list[RemoteSearchCandidate],
     import_cache_root: Path,
     *,
     max_results: int = 3,
+    dry_run: bool = False,
 ) -> list[RemoteSearchCandidate]:
     imported: list[RemoteSearchCandidate] = []
-    import_cache_root.mkdir(parents=True, exist_ok=True)
+    if not dry_run:
+        import_cache_root.mkdir(parents=True, exist_ok=True)
     for candidate in candidates[:max_results]:
+        candidate.candidate_promotion_status = candidate_promotion_status(candidate.license_or_permission)
         repo_name = candidate.repo_url.rstrip("/").split("/")[-1]
         owner_name = candidate.repo_url.rstrip("/").split("/")[-2] if "/" in candidate.repo_url.rstrip("/") else "repo"
         dest_root = import_cache_root / f"{owner_name}_{repo_name}"
         archive_url = candidate.archive_url
+        if dry_run:
+            candidate.import_status = "dry_run"
+            imported.append(candidate)
+            continue
         if not archive_url:
             imported.append(candidate)
             continue
@@ -124,39 +203,26 @@ def auto_import_remote_candidates(
             continue
         try:
             with zipfile.ZipFile(io.BytesIO(archive_bytes)) as archive:
-                if dest_root.exists():
-                    for child in dest_root.iterdir():
-                        if child.is_dir():
-                            for nested in child.rglob("*"):
-                                if nested.is_file():
-                                    nested.unlink()
-                            for nested_dir in sorted([item for item in child.rglob("*") if item.is_dir()], reverse=True):
-                                nested_dir.rmdir()
-                            child.rmdir()
-                        else:
-                            child.unlink()
+                _clear_import_destination(dest_root)
                 dest_root.mkdir(parents=True, exist_ok=True)
                 for member in archive.infolist():
-                    lower_name = member.filename.lower()
-                    if not (
-                        lower_name.endswith(".pkt")
-                        or lower_name.endswith(".pka")
-                        or lower_name.endswith("readme.md")
-                        or lower_name.endswith("license")
-                        or lower_name.endswith("license.md")
-                        or lower_name.endswith("license.txt")
-                    ):
+                    if not _allowed_archive_member(member.filename):
                         continue
                     cleaned = re.sub(r"^[^/]+/", "", member.filename).strip("/")
                     if not cleaned:
                         continue
                     target = dest_root / cleaned
+                    try:
+                        target.resolve().relative_to(dest_root.resolve())
+                    except ValueError:
+                        continue
                     target.parent.mkdir(parents=True, exist_ok=True)
                     if member.is_dir():
                         target.mkdir(parents=True, exist_ok=True)
                         continue
                     with archive.open(member) as source, target.open("wb") as sink:
                         sink.write(source.read())
+                    _increment_file_counters(candidate, target)
                 candidate.path = str(dest_root)
                 candidate.import_status = "imported"
         except zipfile.BadZipFile:
@@ -165,5 +231,115 @@ def auto_import_remote_candidates(
     return imported
 
 
+def _decode_audit_for_root(root: Path, license_or_permission: str) -> dict[str, object]:
+    pkt_paths = sorted(root.rglob("*.pkt")) if root.exists() else []
+    decode_success_count = 0
+    decode_failure_count = 0
+    detected_features: set[str] = set()
+    detected_families: set[str] = set()
+    for pkt_path in pkt_paths:
+        try:
+            from sample_catalog import summarize_pkt_descriptor
+
+            descriptor = summarize_pkt_descriptor(
+                pkt_path,
+                str(pkt_path.relative_to(root)),
+                origin="external-reference",
+                prototype_eligible=False,
+                trust_level="reference-only",
+                role="reference",
+                license_or_permission=license_or_permission,
+                promotion_status="reference_only",
+                donor_eligible=False,
+            )
+        except Exception:
+            decode_failure_count += 1
+            continue
+        decode_success_count += 1
+        detected_features.update(descriptor.capability_tags)
+        detected_features.update(descriptor.validated_edit_capabilities)
+        detected_families.update(descriptor.archetype_tags)
+        detected_families.update(descriptor.device_families)
+        detected_families.update(descriptor.topology_tags)
+    return {
+        "decode_status": "not_run" if not pkt_paths else ("ok" if decode_failure_count == 0 else "partial_or_failed"),
+        "decode_success_count": decode_success_count,
+        "decode_failure_count": decode_failure_count,
+        "detected_feature_tags": sorted(detected_features),
+        "detected_feature_families": sorted(detected_families),
+    }
+
+
+def build_remote_sample_audit(
+    candidates: list[RemoteSearchCandidate],
+    import_cache_root: Path,
+) -> dict[str, object]:
+    entries: list[dict[str, object]] = []
+    license_counts: dict[str, int] = {}
+    for candidate in candidates:
+        license_value = candidate.license_or_permission or "unknown"
+        license_counts[license_value] = license_counts.get(license_value, 0) + 1
+        entry = asdict(candidate)
+        if candidate.path:
+            entry.update(_decode_audit_for_root(Path(candidate.path), candidate.license_or_permission))
+        else:
+            entry.update(
+                {
+                    "decode_status": "not_run",
+                    "decode_success_count": 0,
+                    "decode_failure_count": 0,
+                    "detected_feature_tags": [],
+                    "detected_feature_families": [],
+                }
+            )
+        if candidate.candidate_promotion_status == "validated_curated" and int(entry.get("decode_success_count", 0)) > 0:
+            entry["validation_promotion_status"] = "validated_curated"
+        else:
+            entry["validation_promotion_status"] = "reference_only"
+        entries.append(entry)
+    return {
+        "audit_version": "1.0",
+        "cache_root": str(import_cache_root),
+        "raw_pkt_policy": "remote Packet Tracer files stay local/cache-only and are not committed or packed",
+        "candidate_count": len(candidates),
+        "imported_repo_count": sum(1 for candidate in candidates if candidate.import_status == "imported"),
+        "dry_run_repo_count": sum(1 for candidate in candidates if candidate.import_status == "dry_run"),
+        "pkt_file_count": sum(candidate.pkt_file_count for candidate in candidates),
+        "pka_file_count": sum(candidate.pka_file_count for candidate in candidates),
+        "decode_success_count": sum(int(entry.get("decode_success_count", 0)) for entry in entries),
+        "decode_failure_count": sum(int(entry.get("decode_failure_count", 0)) for entry in entries),
+        "license_counts": license_counts,
+        "promotion_status_counts": {
+            status: sum(1 for candidate in candidates if candidate.candidate_promotion_status == status)
+            for status in sorted({candidate.candidate_promotion_status for candidate in candidates})
+        },
+        "validation_promotion_status_counts": {
+            status: sum(1 for entry in entries if entry.get("validation_promotion_status") == status)
+            for status in sorted({str(entry.get("validation_promotion_status")) for entry in entries})
+        },
+        "top_gaps_filled_by_imported_samples": sorted(
+            {
+                feature
+                for entry in entries
+                for feature in entry.get("detected_feature_tags", [])
+                if isinstance(feature, str)
+            }
+        )[:25],
+        "candidates": entries,
+    }
+
+
+def write_remote_sample_audit(
+    candidates: list[RemoteSearchCandidate],
+    import_cache_root: Path,
+    audit_path: Path | None = None,
+) -> dict[str, object]:
+    payload = build_remote_sample_audit(candidates, import_cache_root)
+    target = audit_path or (import_cache_root / REMOTE_AUDIT_FILENAME)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    return payload
+
+
 def asdict_list(candidates: list[RemoteSearchCandidate]) -> list[dict[str, object]]:
     return [asdict(candidate) for candidate in candidates]

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,