packet-tracer-skill 0.2.0 → 0.2.2

package/scripts/runtime_doctor.py

@@ -43,23 +43,62 @@ def runtime_env_examples(host_os: str) -> list[str]:
         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="$env:USERPROFILE\.codex\skills\pkt\scripts\vendor\_twofish.cp314-win_amd64.pyd"',
+            r'$env:PKT_TWOFISH_LIBRARY="C:\path\to\_twofish.cp314-win_amd64.pyd"',
+            r'$env:PKT_TWOFISH_SEARCH_ROOTS="C:\path\to\bridge-folder"',
         ]
     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/.codex/skills/pkt/scripts/vendor:$HOME/pkt-bridges\"",
+            "export PKT_TWOFISH_SEARCH_ROOTS=\"$HOME/path/to/bridge-folder:$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/.codex/skills/pkt/scripts/vendor:$HOME/pkt-bridges\"",
+            "export PKT_TWOFISH_SEARCH_ROOTS=\"$HOME/path/to/bridge-folder:$HOME/pkt-bridges\"",
         ]
     return []
 
 
+def _format_operation_list(operations: list[str]) -> str:
+    return ", ".join(operations) if operations else "none"
+
+
+def _best_next_fix(runtime_blockers: list[str], recommended_next_steps: list[str]) -> str:
+    blocker_map = {
+        "missing_or_incompatible_donor": "Fix the donor path first so inventory/edit/generate can use a compatible 9.0 donor.",
+        "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.",
+    }
+    for blocker in runtime_blockers:
+        if blocker in blocker_map:
+            return blocker_map[blocker]
+    return recommended_next_steps[0] if recommended_next_steps else "No immediate fix is required."
+
+
+def _why_it_is_blocked(runtime_blockers: list[str], bridge_resolution: str) -> str:
+    if not runtime_blockers:
+        return "No runtime blocker is currently active."
+    reasons: list[str] = []
+    if "missing_or_incompatible_donor" in runtime_blockers:
+        reasons.append("no compatible donor is resolved")
+    if "missing_twofish_bridge" in runtime_blockers:
+        reasons.append("no local Twofish bridge is resolved")
+    if "missing_packet_tracer_root" in runtime_blockers:
+        reasons.append("Packet Tracer root is not resolved")
+    if "missing_packet_tracer_executable" in runtime_blockers:
+        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":
+        reasons.append("strict runtime currently relies on an external bridge override")
+    return "; ".join(reasons) + "."
+
+
 def build_recommended_next_steps(
     *,
     host_os: str,
@@ -205,13 +244,43 @@ def collect_runtime_doctor() -> dict[str, object]:
     else:
         runtime_grade = "ready"
     if runtime_grade == "ready":
-        doctor_summary = "Runtime looks ready for decode, edit, generate, and validate-open."
+        doctor_summary = (
+            "Runtime is ready. "
+            f"Ready operations: {_format_operation_list(ready_operations)}."
+        )
+    elif bridge_resolution == "external_env" and not blocked_operations:
+        doctor_summary = (
+            "Runtime operations are ready, but packaged runtime remains partially ready because the bridge "
+            "comes from an external environment instead of the repo-local vendor path. "
+            f"Ready operations: {_format_operation_list(ready_operations)}."
+        )
     elif runtime_grade == "partially_ready":
-        doctor_summary = "Runtime is partially ready: some operations work, but strict .pkt generation is still blocked."
+        doctor_summary = (
+            "Runtime is partially ready. "
+            f"Ready operations: {_format_operation_list(ready_operations)}. "
+            f"Blocked operations: {_format_operation_list(blocked_operations)}."
+        )
     else:
-        doctor_summary = "Runtime is blocked: required donor, bridge, or Packet Tracer runtime pieces are missing."
-    if bridge_resolution == "external_env":
+        doctor_summary = (
+            "Runtime is blocked. "
+            f"Blocked operations: {_format_operation_list(blocked_operations)}."
+        )
+    if bridge_resolution == "external_env" and blocked_operations:
         doctor_summary = f"{doctor_summary} External bridge is being used instead of a repo-local vendor bridge."
+    elif bridge_resolution == "missing" and runtime_grade != "ready":
+        doctor_summary = f"{doctor_summary} Strict decode/edit/generate remain blocked until a local bridge is resolved."
+    what_currently_works = (
+        f"Currently working operations: {_format_operation_list(ready_operations)}."
+        if ready_operations
+        else "No strict runtime operations are currently working."
+    )
+    what_is_blocked = (
+        f"Blocked operations: {_format_operation_list(blocked_operations)}."
+        if blocked_operations
+        else "No runtime operations are currently blocked."
+    )
+    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"
@@ -220,11 +289,11 @@ def collect_runtime_doctor() -> dict[str, object]:
         else "Repo-local bridge is resolved."
     )
     runtime_contract_notes = (
-        "Repo-local bridge and donor are present."
+        "Repo-local bridge and donor are present, so this checkout can run strict decode/edit/generate locally."
         if bridge_resolution == "repo_local"
-        else "External bridge resolves decode/edit, but repo-local runtime packaging is still incomplete."
+        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 "Bridge resolution is missing, so strict runtime remains blocked."
+        else "No bridge is resolved. validate_open may still work when Packet Tracer is installed, but strict decode/edit/generate remain blocked."
     )
 
     return {
@@ -270,6 +339,10 @@ def collect_runtime_doctor() -> dict[str, object]:
         "runtime_blockers": runtime_blockers,
         "ready_operations": ready_operations,
         "blocked_operations": blocked_operations,
+        "what_currently_works": what_currently_works,
+        "what_is_blocked": what_is_blocked,
+        "why_it_is_blocked": why_it_is_blocked,
+        "best_next_fix": best_next_fix,
         "doctor_summary": doctor_summary,
         "runtime_grade": runtime_grade,
         "recommended_next_steps": recommended_next_steps,

package/scripts/sample_catalog.py

@@ -24,20 +24,82 @@ CAPABILITY_KEYWORDS = {
     "dhcp_pool": ["dhcp", "reservation", "apipa"],
     "router_dhcp": ["dhcp", "reservation", "apipa"],
     "server_dhcp": ["dhcp", "reservation", "apipa"],
+    "dhcpv6_stateful": ["dhcpv6", "stateful_dhcpv6"],
+    "dhcpv6_stateless": ["stateless_dhcpv6"],
+    "ipv6_slaac": ["slaac"],
+    "ipv6_prefix_delegation": ["prefix_delegation"],
+    "ipv6_dns_aaaa": ["aaaa"],
+    "ipv6_tunneling": ["ipv6ip", "ipv6 tunneling"],
+    "isatap": ["isatap"],
     "dhcp_snooping": ["dhcp snooping", "option_82", "trusted_untrusted"],
     "ospf": ["ospf"],
+    "ospfv3": ["ospfv3", "ipv6_ospf"],
     "eigrp": ["eigrp"],
+    "eigrp_ipv6": ["ipv6_eigrp"],
     "rip": ["rip"],
+    "ripng": ["ripng", "ipv6 rip"],
+    "hsrp": ["hsrp"],
     "nat": ["nat"],
     "acl": ["acl", "access-list"],
+    "dai": ["dai", "dynamic arp inspection"],
+    "dot1x": ["dot1x", "802.1x", "port-based nac"],
+    "lldp": ["lldp"],
+    "rep": ["rep_"],
+    "snmp": ["snmp"],
+    "netflow": ["netflow"],
+    "span": ["span", "rspan"],
+    "qos": ["qos"],
+    "port_security": ["port security", "port-security"],
     "vpn": ["vpn", "ipsec", "gre"],
     "ipsec": ["ipsec", "ike"],
     "gre": ["gre"],
     "ppp": ["ppp", "chap", "pap"],
+    "wan": ["wan", "cloud", "serial", "pppoe", "ppp"],
+    "security_edge": ["asa", "firewall", "security appliance"],
+    "asa_acl_nat": ["asa_acl_nat"],
+    "asa_service_policy": ["asa_service_policy", "service policy"],
+    "clientless_vpn": ["clientless_vpn"],
+    "cbac": ["cbac"],
+    "zfw": ["zfw", "zone based firewall"],
+    "sniffer": ["sniffer"],
     "multilayer_switching": ["multilayer", "layer 3", "3560", "svi"],
     "wireless": ["wireless", "wlan", "wlc", "wifi", "ssid", "wpa", "wep", "5g", "bluetooth", "cellular"],
     "wireless_ap": ["wireless", "wlan", "wlc", "wifi", "ssid", "wpa", "wep"],
     "wireless_client": ["wireless", "wifi", "tablet", "smartphone", "laptop"],
+    "wlc": ["wlc", "wireless lan controller"],
+    "wpa_enterprise": ["wpa_radius", "wpa2_enterprise"],
+    "wep": ["wep"],
+    "guest_wifi": ["guest"],
+    "beamforming": ["beamforming"],
+    "meraki": ["meraki"],
+    "cellular_5g": ["5g", "cellular", "cell tower"],
+    "bluetooth": ["bluetooth"],
+    "network_controller": ["network controller", "netcon"],
+    "python_programming": ["python"],
+    "javascript_programming": ["javascript"],
+    "blockly_programming": ["blockly"],
+    "tcp_udp_app": ["tcp_test_app", "udp_test_app"],
+    "vm_iox": ["iox", "uploading_and_running_vm"],
+    "voip": ["voip"],
+    "ip_phone": ["ip phone", "phone"],
+    "call_manager": ["call manager", "telephony", "voip"],
+    "linksys_voice": ["voip linksys"],
+    "mqtt": ["mqtt"],
+    "real_http": ["real-http", "real http"],
+    "real_websocket": ["real-websocket", "real websocket"],
+    "visual_scripting": ["visual-scripting", "visual scripting"],
+    "ptp": ["ptp"],
+    "profinet": ["profinet"],
+    "l2nat": ["l2nat"],
+    "cyberobserver": ["cyberobserver"],
+    "industrial_firewall": ["isa3000", "industrial cybersecurity"],
+    "coaxial": ["coaxial"],
+    "cable_dsl": ["cable modem", "dsl modem"],
+    "central_office": ["centraloffice", "central office"],
+    "cell_tower": ["cell tower"],
+    "power_distribution": ["power distribution"],
+    "hot_swappable": ["hotswappable", "hot swappable"],
+    "ios_license": ["ios_15", "license"],
     "ntp": ["ntp"],
     "dns": ["dns"],
     "server_dns": ["dns"],
@@ -54,6 +116,70 @@ CAPABILITY_KEYWORDS = {
     "printer": ["printer"],
 }
 
+REPORT_ONLY_CAPABILITIES = {
+    "ipv6_slaac",
+    "dhcpv6_stateful",
+    "dhcpv6_stateless",
+    "ipv6_prefix_delegation",
+    "ipv6_dns_aaaa",
+    "ipv6_tunneling",
+    "isatap",
+    "ospfv3",
+    "eigrp_ipv6",
+    "ripng",
+    "hsrp",
+    "dhcp_snooping",
+    "dai",
+    "dot1x",
+    "lldp",
+    "rep",
+    "snmp",
+    "netflow",
+    "span",
+    "qos",
+    "port_security",
+    "asa_acl_nat",
+    "asa_service_policy",
+    "clientless_vpn",
+    "cbac",
+    "zfw",
+    "sniffer",
+    "wlc",
+    "wpa_enterprise",
+    "wep",
+    "guest_wifi",
+    "beamforming",
+    "meraki",
+    "cellular_5g",
+    "bluetooth",
+    "network_controller",
+    "python_programming",
+    "javascript_programming",
+    "blockly_programming",
+    "tcp_udp_app",
+    "vm_iox",
+    "voip",
+    "ip_phone",
+    "call_manager",
+    "linksys_voice",
+    "mqtt",
+    "real_http",
+    "real_websocket",
+    "visual_scripting",
+    "ptp",
+    "profinet",
+    "l2nat",
+    "cyberobserver",
+    "industrial_firewall",
+    "coaxial",
+    "cable_dsl",
+    "central_office",
+    "cell_tower",
+    "power_distribution",
+    "hot_swappable",
+    "ios_license",
+}
+
 TYPE_NORMALIZATION = {
     "pc": "PC",
     "pc-pt": "PC",
@@ -76,6 +202,9 @@ TYPE_NORMALIZATION = {
     "printer": "Printer",
     "smartphone": "Smartphone",
     "mcucomponent": "IoT",
+    "networkcontroller": "NetworkController",
+    "centralofficeserver": "CentralOfficeServer",
+    "celltower": "CellTower",
 }
 
 LICENSE_FILENAMES = [
@@ -215,6 +344,7 @@ def infer_capability_tags(item: dict[str, Any]) -> list[str]:
     rel = item.get("relative_path", "").lower().replace("\\", "/")
     rel_flat = rel.replace("/", " ")
     devices = item.get("devices", [])
+    raw_types = {str(device.get("type", "")).strip() for device in devices if str(device.get("type", "")).strip()}
     normalized_types = [normalize_device_type(device.get("type", "")) for device in devices]
     router_count = normalized_types.count("Router")
     switch_count = normalized_types.count("Switch")
@@ -232,6 +362,15 @@ def infer_capability_tags(item: dict[str, Any]) -> list[str]:
     if any(dtype in {"WirelessRouter", "LightWeightAccessPoint"} for dtype in normalized_types):
         tags.add("wireless")
         tags.add("wireless_ap")
+    if "HomeGateway" in raw_types or any(dtype == "IoT" for dtype in normalized_types):
+        tags.add("iot")
+    if any(dtype in {"ASA", "Security Appliance"} for dtype in normalized_types) or raw_types & {"ASA", "Security Appliance"}:
+        tags.add("security_edge")
+        tags.add("acl")
+    if any(dtype in {"Cloud", "Cable Modem", "Dsl Modem"} for dtype in normalized_types):
+        tags.add("wan")
+    if any(dtype == "MultiLayerSwitch" for dtype in normalized_types):
+        tags.add("multilayer_switching")
     if any(dtype in {"Tablet", "Laptop", "Smartphone"} for dtype in normalized_types):
         tags.add("wireless_client")
     if any(dtype == "Tablet" for dtype in normalized_types):
@@ -314,6 +453,23 @@ def infer_wireless_mode_tags(item: dict[str, Any]) -> list[str]:
     return sorted(tags)
 
 
+def infer_iot_roles(item: dict[str, Any]) -> list[str]:
+    roles = {str(role).strip() for role in item.get("iot_roles", []) if str(role).strip()}
+    raw_types = {str(device.get("type", "")).strip() for device in item.get("devices", []) if str(device.get("type", "")).strip()}
+    normalized_types = {normalize_device_type(device.get("type", "")) for device in item.get("devices", []) if device.get("type")}
+    families = set(item.get("device_families", []) or infer_device_families(item))
+    has_thing = bool(raw_types & {"MCUComponent", "Board", "Sensor", "Actuator"}) or "iot devices" in families
+    has_gateway = "HomeGateway" in raw_types or ("home/wireless routers" in families and has_thing)
+    has_server = "Server" in normalized_types or "servers" in families
+    if has_thing:
+        roles.add("thing")
+    if has_gateway:
+        roles.add("gateway")
+    if has_server:
+        roles.add("server")
+    return sorted(roles)
+
+
 def infer_device_families(item: dict[str, Any]) -> list[str]:
     family_map = {
         "Router": "routers",
@@ -336,6 +492,9 @@ def infer_device_families(item: dict[str, Any]) -> list[str]:
         "Dsl Modem": "wan/cloud/dsl/cable devices",
         "Security Appliance": "security devices",
         "ASA": "security devices",
+        "NetworkController": "network controllers",
+        "CentralOfficeServer": "wan/cloud/dsl/cable devices",
+        "CellTower": "wan/cloud/dsl/cable devices",
         "IoT": "iot devices",
         "Sensor": "iot devices",
         "Actuator": "iot devices",
@@ -397,12 +556,24 @@ def infer_service_support(item: dict[str, Any]) -> list[str]:
 
 def infer_runtime_features(item: dict[str, Any]) -> list[str]:
     features: set[str] = set()
+    tags = set(item.get("capability_tags", []))
+    families = set(item.get("device_families", []) or infer_device_families(item))
     if item.get("wireless_mode_tags"):
         features.add("wireless_runtime")
     if item.get("service_support"):
         features.add("service_runtime")
-    if item.get("iot_roles"):
+    if infer_iot_roles(item):
         features.add("iot_runtime")
+    if families & {"wan/cloud/dsl/cable devices"} or tags & {"wan", "ppp"}:
+        features.add("wan_runtime")
+    if families & {"security devices"} or tags & {"security_edge", "acl", "nat"}:
+        features.add("security_runtime")
+    if tags & {"vpn", "ipsec", "gre"}:
+        features.add("tunnel_runtime")
+    if tags & {"ipv6_slaac", "dhcpv6_stateful", "dhcpv6_stateless", "ospfv3", "eigrp_ipv6", "ripng", "hsrp"}:
+        features.add("ipv6_runtime")
+    if families & {"multilayer switches"} or tags & {"multilayer_switching"}:
+        features.add("multilayer_runtime")
     if item.get("workspace_validation"):
         features.add("workspace_validated")
     if any(str(link.get("from", "")) and str(link.get("to", "")) for link in item.get("links", [])):
@@ -416,7 +587,7 @@ def infer_archetype_tags(item: dict[str, Any]) -> list[str]:
     families = set(item.get("device_families", []))
     services = set(item.get("service_support", []))
     wireless_modes = set(item.get("wireless_mode_tags", []))
-    iot_roles = set(item.get("iot_roles", []))
+    iot_roles = set(infer_iot_roles(item))
 
     if topology & {"chain", "core_access", "department_lan", "router_on_a_stick"} or (
         families & {"routers", "switches", "multilayer switches"}
@@ -431,10 +602,29 @@ def infer_archetype_tags(item: dict[str, Any]) -> list[str]:
         tags.add("IoT/home gateway")
     if families & {"wan/cloud/dsl/cable devices", "security devices"} or set(item.get("capability_tags", [])) & {
         "vpn",
+        "ipsec",
+        "gre",
+        "ppp",
+        "wan",
+        "security_edge",
+        "multilayer_switching",
         "nat",
         "acl",
     }:
         tags.add("WAN/security edge")
+    capability_tags = set(item.get("capability_tags", []))
+    if capability_tags & {"ipv6_slaac", "dhcpv6_stateful", "dhcpv6_stateless", "ipv6_prefix_delegation", "ipv6_dns_aaaa", "ipv6_tunneling", "isatap", "ospfv3", "eigrp_ipv6", "ripng", "hsrp"}:
+        tags.add("IPv6/routing")
+    if capability_tags & {"dhcp_snooping", "dai", "dot1x", "lldp", "rep", "snmp", "netflow", "span", "qos", "port_security"}:
+        tags.add("L2 security/monitoring")
+    if capability_tags & {"wlc", "wpa_enterprise", "wep", "guest_wifi", "beamforming", "meraki", "cellular_5g", "bluetooth"}:
+        tags.add("advanced wireless")
+    if capability_tags & {"network_controller", "python_programming", "javascript_programming", "blockly_programming", "tcp_udp_app", "vm_iox"} or "network controllers" in families:
+        tags.add("automation/controller")
+    if capability_tags & {"voip", "ip_phone", "call_manager", "linksys_voice"}:
+        tags.add("voice/collaboration")
+    if capability_tags & {"mqtt", "real_http", "real_websocket", "visual_scripting", "ptp", "profinet", "l2nat", "cyberobserver", "industrial_firewall"}:
+        tags.add("industrial IoT")
     return sorted(tags)
 
 
@@ -467,6 +657,8 @@ def infer_apply_safety_level(item: dict[str, Any]) -> str:
 
 def infer_validated_edit_capabilities(item: dict[str, Any]) -> list[str]:
     capabilities: set[str] = {str(tag) for tag in item.get("capability_tags", []) if str(tag).strip()}
+    inferred_iot_roles = set(infer_iot_roles(item))
+    families = set(item.get("device_families", []) or infer_device_families(item))
     service_capability_map = {
         "dhcp": "server_dhcp",
         "dns": "server_dns",
@@ -487,12 +679,24 @@ def infer_validated_edit_capabilities(item: dict[str, Any]) -> list[str]:
         capabilities.add("wireless_mutation")
     if any(device_family == "end devices" for device_family in item.get("device_families", [])):
         capabilities.add("end_device_mutation")
-    if item.get("iot_roles"):
+    if inferred_iot_roles:
+        capabilities.add("iot")
         capabilities.add("iot_registration")
-        if "server" in {str(role) for role in item.get("iot_roles", [])}:
+        if {"server", "gateway"} & inferred_iot_roles:
             capabilities.add("iot_control")
+    if capabilities & {"vpn", "ipsec", "gre"}:
+        capabilities.update({"vpn", "ipsec", "gre"})
+    if capabilities & {"ppp", "wan"} or families & {"wan/cloud/dsl/cable devices"}:
+        capabilities.add("wan")
+        if "ppp" in capabilities:
+            capabilities.add("ppp")
+    if capabilities & {"acl", "nat", "security_edge"} or families & {"security devices"}:
+        capabilities.add("security_edge")
+    if "multilayer switches" in families or "multilayer_switching" in capabilities:
+        capabilities.add("multilayer_switching")
     if item.get("apply_safety_level") == "inventory-supported":
         return []
+    capabilities -= REPORT_ONLY_CAPABILITIES
     return sorted(capabilities)
 
 
@@ -731,7 +935,8 @@ def enrich_catalog_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
         new_item.setdefault("model_families", infer_model_families(new_item))
         new_item.setdefault("port_media_types", infer_port_media_types(new_item))
         new_item.setdefault("service_support", infer_service_support(new_item))
-        new_item.setdefault("runtime_features", infer_runtime_features(new_item))
+        new_item.setdefault("iot_roles", infer_iot_roles(new_item))
+        new_item["runtime_features"] = sorted(set(new_item.get("runtime_features", [])) | set(infer_runtime_features(new_item)))
         new_item.setdefault("donor_graph_fingerprint", infer_donor_graph_fingerprint(new_item))
         new_item.setdefault("apply_safety_level", infer_apply_safety_level(new_item))
         new_item.setdefault("archetype_tags", infer_archetype_tags(new_item))

package/docs/screenshots/.gitkeep

@@ -1 +0,0 @@
-