packet-tracer-skill 0.3.0 → 0.3.2

package/scripts/pkt_editor.py

@@ -5,6 +5,7 @@ import hashlib
 import json
 import re
 from collections import Counter
+from collections.abc import Callable
 from pathlib import Path
 import xml.etree.ElementTree as ET
 from functools import lru_cache
@@ -706,6 +707,10 @@ def _append_unique_config_lines(parent: ET.Element | None, lines: list[str]) ->
 _WORD_VALUED_SETTINGS = (
     "switchport port-security violation",
     "switchport mode",
+    # An interface has one description. Without this, `description Satis` and
+    # `description VLAN40 standby` read as different settings and both survive
+    # a merge, where the device keeps only the last.
+    "description",
     "duplex",
     "speed",
 )
@@ -880,6 +885,49 @@ def _find_link_by_devices(root: ET.Element, left_name: str, right_name: str) ->
     return None
 
 
+@lru_cache(maxsize=1)
+def _modern_link_prototype_xml() -> str | None:
+    """A cable copied from a lab the installed Packet Tracer wrote itself.
+
+    A new link is cloned from one the file already has. When the file has none,
+    the fallback was a cable from the bundled `FTP.pkt`, and that sample is old
+    enough to predate the fields a 9.x cable carries: it refers to its devices
+    by index rather than by `save-ref-id`, and has no `FUNCTIONAL`,
+    `GEO_VIEW_COLOR` or `IS_MANAGED_IN_RACK_VIEW` at all.
+
+    Measured: adding one link to `minimal`, which has cables to copy, takes it
+    from four links to five and it opens. Adding one link to `wireless_home`,
+    which has none, produces a file Packet Tracer refuses -- and that is why
+    both wireless labs ship uncabled. Same writer, same ports, same devices;
+    the only difference is which cable was cloned.
+
+    The compatibility donor is the right source because it is already the file
+    this skill trusts for the installed version, so its cables are the shape
+    this Packet Tracer writes.
+    """
+    from packet_tracer_env import get_packet_tracer_compatibility_donor
+
+    donor = get_packet_tracer_compatibility_donor()
+    if donor is None:
+        return None
+    try:
+        root = decode_pkt_to_root(donor)
+    except Exception:  # pragma: no cover - a donor that no longer decodes
+        return None
+    prototype = _first_link_prototype(root)
+    if prototype is None:
+        return None
+    return ET.tostring(prototype, encoding="unicode")
+
+
+def _fallback_link_prototype() -> ET.Element | None:
+    xml = _modern_link_prototype_xml()
+    if xml is not None:
+        return ET.fromstring(xml)
+    prototype_root = load_sample_root(resolve_sample_path(FTP_SAMPLE))
+    return prototype_root.find(".//LINKS/LINK")
+
+
 def _first_link_prototype(root: ET.Element) -> ET.Element | None:
     for link in root.findall(".//LINKS/LINK"):
         cable = link.find("./CABLE")
@@ -1356,8 +1404,16 @@ def _ensure_link(
     right_port: str,
     media: str,
     port_mem_map: dict[tuple[str, str], str] | None = None,
+    allow_parallel: bool = False,
 ) -> None:
-    existing = _find_link_by_devices(root, left_name, right_name)
+    # Every caller but one wants at most one cable between a pair of devices, so
+    # a second call re-points the first cable instead of adding one. An
+    # EtherChannel is the exception: it is only a bundle if two cables run
+    # between the same two switches, and asking for the second one used to move
+    # the first. The new-link branch below is what a parallel cable needs -- it
+    # is the branch that drops the saving session's memory pointers, which is
+    # what makes Packet Tracer accept a link it did not write itself.
+    existing = None if allow_parallel else _find_link_by_devices(root, left_name, right_name)
     devices = {device.findtext("./ENGINE/NAME", default=""): device for device in root.findall(".//DEVICES/DEVICE")}
     index_refs, save_refs = _device_refs(root)
     left_device = devices.get(left_name)
@@ -1387,8 +1443,7 @@ def _ensure_link(
         if prototype is None:
             prototype = _first_link_prototype(root)
         if prototype is None:
-            prototype_root = load_sample_root(resolve_sample_path(FTP_SAMPLE))
-            prototype = prototype_root.find(".//LINKS/LINK")
+            prototype = _fallback_link_prototype()
         link = copy.deepcopy(prototype)
         if link is None:
             return
@@ -1550,13 +1605,13 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ip dhcp snooping", f"ip dhcp snooping vlan {operation['vlan']}"])
             if operation.get("trust_port"):
-                _append_config_block(target, f"interface {operation['trust_port']}", [" ip dhcp snooping trust"])
+                _set_config_block(target, f"interface {operation['trust_port']}", [" ip dhcp snooping trust"])
         return
     elif operation["op"] == "set_dai":
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ip dhcp snooping", f"ip dhcp snooping vlan {operation['vlan']}", f"ip arp inspection vlan {operation['vlan']}"])
             if operation.get("trust_port"):
-                _append_config_block(target, f"interface {operation['trust_port']}", [" ip arp inspection trust", " ip dhcp snooping trust"])
+                _set_config_block(target, f"interface {operation['trust_port']}", [" ip arp inspection trust", " ip dhcp snooping trust"])
         return
     elif operation["op"] == "set_port_security":
         body = [" switchport mode access", " switchport port-security"]
@@ -1565,7 +1620,7 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
         if operation.get("violation"):
             body.append(f" switchport port-security violation {operation['violation']}")
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['port']}", body)
+            _set_config_block(target, f"interface {operation['port']}", body)
         return
     elif operation["op"] == "set_lldp":
         for target in _config_targets(device):
@@ -1573,7 +1628,7 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
         return
     elif operation["op"] == "set_rep":
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", [f" rep segment {operation['segment']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" rep segment {operation['segment']}"])
         return
     elif operation["op"] == "set_span":
         for target in _config_targets(device):
@@ -1592,7 +1647,7 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
         mode = str(operation.get("mode") or "auto")
         for target in _config_targets(device):
             _append_unique_config_lines(target, global_lines)
-            _append_config_block(
+            _set_config_block(
                 target,
                 f"interface {operation['interface']}",
                 [f" authentication port-control {mode}", " dot1x pae authenticator"],
@@ -1612,7 +1667,7 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
                 f"policy-map {operation['policy_map']}",
                 [f" class {operation['class_map']}", f"  {action}"],
             )
-            _append_config_block(
+            _set_config_block(
                 target,
                 f"interface {operation['interface']}",
                 [f" service-policy {operation['direction']} {operation['policy_map']}"],
@@ -1631,8 +1686,8 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
         interfaces = [str(interface) for interface in operation.get("interfaces", []) if str(interface).strip()]
         for target in _config_targets(device):
             for interface_name in interfaces:
-                _append_config_block(target, f"interface {interface_name}", [f" channel-group {channel} mode {mode}"])
-            _append_config_block(target, f"interface Port-channel{channel}", [" no shutdown"])
+                _set_config_block(target, f"interface {interface_name}", [f" channel-group {channel} mode {mode}"])
+            _set_config_block(target, f"interface Port-channel{channel}", [" no shutdown"])
         return
     elif operation["op"] == "set_vtp":
         lines = [f"vtp domain {operation['domain']}", f"vtp mode {operation['mode']}"]
@@ -1643,7 +1698,7 @@ def _apply_switch_op(device: ET.Element, operation: dict[str, object]) -> None:
         return
     elif operation["op"] == "set_dtp":
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", [f" switchport mode {operation['mode']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" switchport mode {operation['mode']}"])
         return
     else:
         return
@@ -1668,7 +1723,7 @@ def _apply_router_op(device: ET.Element, operation: dict[str, object]) -> None:
 def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) -> None:
     if operation["op"] == "set_subinterface":
         for target in _config_targets(device):
-            _append_config_block(
+            _set_config_block(
                 target,
                 f"interface {operation['subinterface']}",
                 [
@@ -1699,7 +1754,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
         return
     elif operation["op"] == "apply_acl":
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", [f" ip access-group {operation['acl_name']} {operation['direction']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ip access-group {operation['acl_name']} {operation['direction']}"])
         return
     elif operation["op"] == "enable_ipv6_unicast_routing":
         for target in _config_targets(device):
@@ -1708,7 +1763,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
     elif operation["op"] == "set_ipv6_address":
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing"])
-            _append_config_block(
+            _set_config_block(
                 target,
                 f"interface {operation['interface']}",
                 [f" ipv6 address {operation['address']}/{operation['prefix']}", " no shutdown"],
@@ -1720,7 +1775,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
             body.insert(1, f" ipv6 nd prefix {operation['prefix']}/{operation['prefix_len']}")
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing"])
-            _append_config_block(target, f"interface {operation['interface']}", body)
+            _set_config_block(target, f"interface {operation['interface']}", body)
         return
     elif operation["op"] == "set_dhcpv6_pool":
         pool_body = [f" address prefix {operation['prefix']}/{operation['prefix_len']}"]
@@ -1732,26 +1787,26 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing"])
             _append_config_block(target, f"ipv6 dhcp pool {operation['name']}", pool_body)
-            _append_config_block(target, f"interface {operation['interface']}", interface_body)
+            _set_config_block(target, f"interface {operation['interface']}", interface_body)
         return
     elif operation["op"] == "set_ospfv3_interface":
         process_id = operation["process_id"]
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing"])
-            _append_config_block(target, f"interface {operation['interface']}", [f" ipv6 ospf {process_id} area {operation['area']}", " no shutdown"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ipv6 ospf {process_id} area {operation['area']}", " no shutdown"])
             _append_config_block(target, f"ipv6 router ospf {process_id}", [])
         return
     elif operation["op"] == "set_eigrp_ipv6_interface":
         asn = operation["asn"]
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing", "no ipv6 cef"])
-            _append_config_block(target, f"interface {operation['interface']}", [f" ipv6 eigrp {asn}", " no shutdown"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ipv6 eigrp {asn}", " no shutdown"])
             _append_config_block(target, f"ipv6 router eigrp {asn}", [" no shutdown"])
         return
     elif operation["op"] == "set_ripng_interface":
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing"])
-            _append_config_block(target, f"interface {operation['interface']}", [f" ipv6 rip {operation['process_name']} enable", " no shutdown"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ipv6 rip {operation['process_name']} enable", " no shutdown"])
         return
     elif operation["op"] == "set_hsrp_ipv6":
         # A standby group with no virtual address configures nothing, and the
@@ -1767,7 +1822,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
             body.append(f" standby {operation['group']} preempt")
         for target in _config_targets(device):
             _append_unique_config_lines(target, ["ipv6 unicast-routing"])
-            _append_config_block(target, f"interface {operation['interface']}", body)
+            _set_config_block(target, f"interface {operation['interface']}", body)
         return
     elif operation["op"] == "set_ospfv2_network":
         for target in _config_targets(device):
@@ -1797,11 +1852,11 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
         return
     elif operation["op"] == "set_dhcp_relay":
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", [f" ip helper-address {operation['helper']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ip helper-address {operation['helper']}"])
         return
     elif operation["op"] == "set_nat_interface":
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", [f" ip nat {operation['role']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ip nat {operation['role']}"])
         return
     elif operation["op"] == "set_nat_static":
         for target in _config_targets(device):
@@ -1849,7 +1904,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
         for target in _config_targets(device):
             _append_unique_config_lines(target, global_lines)
             if operation.get("interface") and operation.get("direction"):
-                _append_config_block(target, f"interface {operation['interface']}", [f" ip flow {operation['direction']}"])
+                _set_config_block(target, f"interface {operation['interface']}", [f" ip flow {operation['direction']}"])
         return
     elif operation["op"] == "set_gre_tunnel":
         body = []
@@ -1864,7 +1919,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
             ]
         )
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", body)
+            _set_config_block(target, f"interface {operation['interface']}", body)
         return
     elif operation["op"] == "set_ppp_interface":
         body = [" encapsulation ppp"]
@@ -1872,7 +1927,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
             body.append(f" ppp authentication {operation['authentication']}")
         body.append(" no shutdown")
         for target in _config_targets(device):
-            _append_config_block(target, f"interface {operation['interface']}", body)
+            _set_config_block(target, f"interface {operation['interface']}", body)
         return
     elif operation["op"] == "set_ipsec_transform_set":
         for target in _config_targets(device):
@@ -1893,17 +1948,17 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
                 ],
             )
             if operation.get("interface"):
-                _append_config_block(target, f"interface {operation['interface']}", [f" crypto map {operation['map_name']}"])
+                _set_config_block(target, f"interface {operation['interface']}", [f" crypto map {operation['map_name']}"])
         return
     elif operation["op"] == "set_cbac_inspect":
         for target in _config_targets(device):
             _append_unique_config_lines(target, [f"ip inspect name {operation['name']} {operation['protocol']}"])
-            _append_config_block(target, f"interface {operation['interface']}", [f" ip inspect {operation['name']} {operation['direction']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" ip inspect {operation['name']} {operation['direction']}"])
         return
     elif operation["op"] == "set_zfw_zone_interface":
         for target in _config_targets(device):
             _append_config_block(target, f"zone security {operation['zone']}", [])
-            _append_config_block(target, f"interface {operation['interface']}", [f" zone-member security {operation['zone']}"])
+            _set_config_block(target, f"interface {operation['interface']}", [f" zone-member security {operation['zone']}"])
         return
     elif operation["op"] == "set_zfw_zone_pair":
         for target in _config_targets(device):
@@ -1968,7 +2023,7 @@ def _apply_router_op_inner(device: ET.Element, operation: dict[str, object]) ->
 def _apply_management_op(device: ET.Element, operation: dict[str, object]) -> None:
     if operation["op"] == "set_management_vlan":
         for target in _config_targets(device):
-            _append_config_block(
+            _set_config_block(
                 target,
                 f"interface Vlan{operation['vlan']}",
                 [f" ip address {operation['ip']} {_prefix_to_mask(int(operation['prefix']))}", " no shutdown"],
@@ -2135,10 +2190,23 @@ def _apply_wireless_op(device: ET.Element, operation: dict[str, object]) -> None
             if node.find("CHANNEL") is not None:
                 _ensure_text(node, "CHANNEL", str(operation["channel"]))
             if operation.get("passphrase"):
-                if node.find("WEP_KEY") is not None:
-                    _ensure_text(node, "WEP_KEY", str(operation["passphrase"]))
-                if node.find("WPA_PASSPHRASE") is not None:
-                    _ensure_text(node, "WPA_PASSPHRASE", str(operation["passphrase"]))
+                # The key goes in `WEP_PROCESS`, whatever the security is.
+                #
+                # Those field names are legacy: a working WPA2 home router
+                # keeps `WEP_PROCESS/KEY` with `WEP_PROCESS/ENCRYPTION` set to
+                # the encryption type, and carries no `WPA_PASSPHRASE` at all.
+                # Measured on `hr-guest`, which associates and pings; the same
+                # shape the client side already used. Choosing the field by
+                # authentication type -- `WEP_KEY` for WEP, `WPA_PASSPHRASE`
+                # otherwise -- put the passphrase somewhere Packet Tracer does
+                # not read, so the access point ran WPA2 with no key while its
+                # clients had one, and nothing associated. The lab opened and
+                # every field looked right on both sides.
+                process = node.find("WEP_PROCESS")
+                if process is None:
+                    process = ET.SubElement(node, "WEP_PROCESS")
+                _ensure_text(process, "KEY", str(operation["passphrase"]))
+                _ensure_text(process, "ENCRYPTION", str(operation["encrypt_type"]))
         for profile in _profile_nodes(engine):
             _ensure_text(profile, "NAME", str(operation["ssid"]))
             _ensure_text(profile, "SSID", str(operation["ssid"]))
@@ -2391,9 +2459,23 @@ def apply_edit_operations(root: ET.Element, plan: IntentPlan) -> ET.Element:
     return apply_plan_operations(root, plan)
 
 
-def edit_pkt_file(pkt_path: str | Path, plan: IntentPlan, output_path: str | Path, xml_out_path: str | Path | None = None) -> Path:
+def edit_pkt_file(
+    pkt_path: str | Path,
+    plan: IntentPlan,
+    output_path: str | Path,
+    xml_out_path: str | Path | None = None,
+    repair: Callable[[ET.Element], object] | None = None,
+) -> Path:
     root = decode_pkt_to_root(pkt_path)
     updated = apply_plan_operations(root, plan)
+    # An edit names ports the way a plan does -- from the request, not from the
+    # file -- so it can write the same configuration that took SW2 off the
+    # network: a channel-group on a port whose peer does not bundle. The
+    # generation pipelines repair that after the fact and the edit path had no
+    # such step. The caller passes the repair in; importing it here would close
+    # a loop, since the module that owns it already imports this one.
+    if repair is not None:
+        repair(updated)
     xml_bytes = serialize_pkt_xml(updated)
     output_path = Path(output_path)
     output_path.parent.mkdir(parents=True, exist_ok=True)

package/scripts/pkt_transformer.py

@@ -718,6 +718,82 @@ UNSLOTTED_MULTIPORT_TYPES = {
     "MerakiServer",
 }
 
+# A home router numbers its LAN ports from one and gives the WAN socket a name
+# of its own. Counting the sockets and numbering them all is how a cable landed
+# on `GigabitEthernet 5` of a router with four LAN ports: five copper gigabit
+# PORT nodes, and the fifth is `Internet`. Packet Tracer refused the file, and
+# every check before it passed -- the device lists no interfaces in its
+# configuration, so nothing else could contradict the count.
+WIRELESS_ROUTER_TYPES = {"WirelessRouter", "WirelessRouterNewGeneration"}
+
+
+def wireless_router_port_names(device: ET.Element) -> list[str]:
+    """The interface names a home router really answers to, LAN ports first.
+
+    A home router writes no interfaces into its configuration, so
+    `donor_interface_names` comes back empty and every shape check abstains --
+    which left the port index as the only thing anyone checked. That accepted
+    `FastEthernet0/1` on a device whose sockets are `Ethernet 1` .. `4`: right
+    index, wrong name, and Packet Tracer refuses a lab that names an interface
+    a device does not have.
+
+    The names are positional and set by the model. Measured over every home
+    router in the labs on this machine -- sixteen cables in all, and not one on
+    any other name:
+
+        WirelessRouter                 `Ethernet 1` .. `4`,        `Internet`
+        WirelessRouterNewGeneration    `GigabitEthernet 1` .. `4`, `Internet`
+
+    Both carry five copper ports and the fifth is the uplink, which is why
+    counting sockets and numbering them all put a cable on a port that is not
+    there. Note the older model's ports report `eCopperFastEthernet` and are
+    still named plain `Ethernet`, so the family cannot be read off the socket:
+    the device type is the discriminator.
+
+    Confirmed against the live devices rather than the files alone. Dropped into
+    an empty Packet Tracer and read back:
+
+        Linksys-WRT300N   Vlan1, Internet, Ethernet 1 .. 4, Wireless
+        HomeRouter-PT-AC  Vlan1, Internet, GigabitEthernet 1 .. 4,
+                          Wireless 1 .. 6, Wireless0/0
+
+    Worth doing: the builder's own device table gives `Ethernet 1` .. `4` for
+    the AC model, which the device itself contradicts. `pt_inspect_ports` is no
+    help either -- it answers at the IOS layer, where the LAN sockets are
+    bridged into `Vlan1` and do not appear at all.
+
+    The wireless sockets follow from the same PORT list: the access-point
+    radios are `Wireless 1` .. `N`, or bare `Wireless` when there is only one,
+    and a host radio is `Wireless0/0`. They are listed so a wireless link is
+    never mistaken for a cable on a port that is not there.
+
+    `Internet` comes after the LAN ports so a repair prefers a LAN port and
+    only reaches for the uplink when the LAN ports are taken.
+    """
+    raw_type = (device.findtext("./ENGINE/TYPE") or "").strip()
+    if normalize_device_type(raw_type) not in WIRELESS_ROUTER_TYPES:
+        return []
+    prefix = "GigabitEthernet" if raw_type == "WirelessRouterNewGeneration" else "Ethernet"
+    copper = access_radios = host_radios = 0
+    for node in device.findall(".//PORT"):
+        port_type = (node.findtext("TYPE") or "").strip()
+        if PORT_TYPE_FAMILIES.get(port_type) in {"FastEthernet", "GigabitEthernet"}:
+            copper += 1
+        elif port_type.startswith("eAccessPointWireless"):
+            access_radios += 1
+        elif port_type.startswith("eHostWireless"):
+            host_radios += 1
+    # One of the copper sockets is the uplink, which is why counting them and
+    # numbering them all put a cable on a port that is not there.
+    names = [f"{prefix} {index}" for index in range(1, max(copper - 1, 0) + 1)]
+    names.append("Internet")
+    if access_radios == 1:
+        names.append("Wireless")
+    else:
+        names += [f"Wireless {index}" for index in range(1, access_radios + 1)]
+    names += ["Wireless0/0"] * min(host_radios, 1)
+    return names
+
 
 def donor_interface_names(device: ET.Element) -> list[str]:
     """The interfaces a donor device really has, in the order it lists them.
@@ -779,7 +855,7 @@ def _name_contradicts_device_shape(device: ET.Element, canonical: str, kind: str
       `1/1`, ... `9/1`. Both have one slash, so depth cannot tell them apart,
       and the generator's `FastEthernet0/{index}` asked such a switch for
       `FastEthernet0/2`. Measured: that single link is why a lab built from
-      `Senan_Haciyev_tapsiriq.pkt` was refused; the same file with the uplink on
+      the saved serial-WAN lab was refused; the same file with the uplink on
       `FastEthernet2/1` opens.
 
     Two names are required before concluding anything about the second axis, so
@@ -827,6 +903,16 @@ def port_exists(device: ET.Element, port_name: str) -> bool:
     if "channel" in lowered or lowered.startswith("vlan") or "." in canonical:
         return False
 
+    # A home router's sockets are named positionally and are the same on every
+    # unit of a model, so they can be answered exactly rather than guessed at.
+    # This has to come before the branches below: `Ethernet 1` matches neither
+    # modelled prefix and used to fall through to the permissive branch, where a
+    # device with no configured interfaces is given the benefit of the doubt --
+    # so `Ethernet 99` passed too.
+    if device_type in WIRELESS_ROUTER_TYPES:
+        known = wireless_router_port_names(device)
+        return canonical in known if known else True
+
     # Serial is modelled now, so it gets a real answer: a router with no serial
     # card cannot carry `Serial0/0/0`, and letting that through produced a WAN
     # lab whose PPP configuration sat on an interface that was never cabled.
@@ -845,7 +931,19 @@ def port_exists(device: ET.Element, port_name: str) -> bool:
     # point, `RS 232` on a laptop, the `Switch` pass-through on an IP phone.
     # Reporting those as missing made real links look invalid, which is the
     # damaging direction: a legitimate link gets dropped.
+    #
+    # Permissive, but not blind. A device that lists its own interfaces has told
+    # us what it has, and a name absent from that list is not one of them. An
+    # ASA 5506-X whose interfaces are `GigabitEthernet1/1` .. `1/8` answered yes
+    # to `Ethernet0/0` -- the name fits neither modelled prefix, so it fell
+    # straight through to this branch, the port repair saw nothing to fix, and
+    # Packet Tracer refused the lab. Devices with no interfaces in their
+    # configuration keep the benefit of the doubt, which is what leaves access
+    # points, phones and laptops working.
     if not canonical.startswith(("FastEthernet", "GigabitEthernet")):
+        named = donor_interface_names(device)
+        if named and canonical not in named:
+            return False
         return True
 
     for kind, count in port_capacity(device).items():

package/scripts/sample_catalog.py

@@ -21,6 +21,11 @@ SCRIPT_DIR = Path(__file__).resolve().parent
 SKILL_ROOT = SCRIPT_DIR.parent
 DEFAULT_CATALOG_JSON = SKILL_ROOT / "references" / "packettracer-sample-catalog.json"
 DEFAULT_CATALOG_MD = SKILL_ROOT / "references" / "packettracer-sample-catalog.md"
+# Labs the user happens to have on disk are catalogued for donor ranking but
+# never written to the two files above: those are committed, and a lab from
+# `C:/Users/<name>/Downloads` carries that person's name in its path, its
+# filename and its device labels. Kept beside them, and git-ignored.
+LOCAL_CATALOG_JSON = SKILL_ROOT / "references" / "local-donor-catalog.json"
 DEFAULT_CURATED_DONOR_REGISTRY = SKILL_ROOT / "references" / "curated-donor-registry.json"
 
 CAPABILITY_KEYWORDS = {
@@ -1112,25 +1117,51 @@ def enrich_catalog_items(items: list[dict[str, Any]]) -> list[dict[str, Any]]:
     return enriched
 
 
+def _catalog_item_path(item: dict, saves_root: Path | None) -> str:
+    """Where a catalogued lab actually lives.
+
+    Entries from the Packet Tracer installation are stored relative to its
+    saves root and joined back to it here. A lab the user saved somewhere else
+    carries its own absolute path, and joining that to the saves root produced
+    a path no file was at -- so a donor built for this skill could be
+    catalogued and still never be read.
+
+    The committed catalogue drops `path` on purpose, to stay independent of
+    whose machine wrote it. `source_path` survives instead, and only entries
+    outside the installation carry one: those are machine-specific by nature.
+    """
+    for key in ("path", "source_path"):
+        own_path = str(item.get(key) or "")
+        if own_path and Path(own_path).is_absolute():
+            return own_path
+    relative_path = item["relative_path"]
+    if saves_root is None:
+        return own_path or relative_path
+    return str(saves_root / relative_path)
+
+
 @lru_cache(maxsize=8)
 def _load_catalog_cached(path_str: str) -> tuple[SampleDescriptor, ...]:
     raw_items = json.loads(Path(path_str).read_text(encoding="utf-8"))
     items = enrich_catalog_items(raw_items)
     saves_root = get_packet_tracer_saves_root()
     return tuple(
-        _descriptor_from_item(
-            {
-                **item,
-                "path": str((saves_root / item["relative_path"]) if saves_root is not None else item.get("path", item["relative_path"])),
-            }
-        )
+        _descriptor_from_item({**item, "path": _catalog_item_path(item, saves_root)})
         for item in items
         if "error" not in item
     )
 
 
 def load_catalog(path: Path | None = None) -> list[SampleDescriptor]:
-    return list(_load_catalog_cached(str(path or DEFAULT_CATALOG_JSON)))
+    """Both catalogues, so splitting the file did not shrink donor choice.
+
+    The installed samples are committed; the labs found on this machine are
+    not. Ranking has always seen one list and still does.
+    """
+    catalog = list(_load_catalog_cached(str(path or DEFAULT_CATALOG_JSON)))
+    if path is None and LOCAL_CATALOG_JSON.is_file():
+        catalog.extend(_load_catalog_cached(str(LOCAL_CATALOG_JSON)))
+    return catalog
 
 
 def _summarize_pkt(path: Path, relative_path: str, origin: str, prototype_eligible: bool) -> dict[str, Any]:
@@ -1348,17 +1379,39 @@ def extract_reference_patterns(samples: list[SampleDescriptor]) -> list[Referenc
     return patterns
 
 
-def write_catalog_outputs(items: list[dict[str, Any]], json_path: Path | None = None, md_path: Path | None = None) -> None:
+def write_catalog_outputs(
+    items: list[dict[str, Any]],
+    json_path: Path | None = None,
+    md_path: Path | None = None,
+    local_json_path: Path | None = None,
+) -> None:
+    """Write the installed-sample catalogue, and the local one beside it.
+
+    `_local_donor_items` strips `path` from its entries so the committed
+    catalogue would not depend on whose machine built it -- but that intent
+    lived only there, and this writer, which is what actually persists the
+    file, did not share it. So a rebuild on a machine with saved labs staged
+    350 entries naming the user and their classmates, each with an absolute
+    path under their home directory, into a file bound for a public
+    repository. Provenance is already on every entry; the split reads it
+    rather than trusting the caller to have filtered first.
+    """
     enriched = enrich_catalog_items(items)
-    compact_items: list[dict[str, Any]] = []
+    installed: list[dict[str, Any]] = []
+    local: list[dict[str, Any]] = []
     for item in enriched:
         saved = dict(item)
         saved.pop("path", None)
-        compact_items.append(saved)
-    (json_path or DEFAULT_CATALOG_JSON).write_text(json.dumps(compact_items, indent=2, ensure_ascii=False), encoding="utf-8")
+        (installed if saved.get("origin") == "cisco-local" else local).append(saved)
+    (json_path or DEFAULT_CATALOG_JSON).write_text(json.dumps(installed, indent=2, ensure_ascii=False), encoding="utf-8")
+    local_path = local_json_path or LOCAL_CATALOG_JSON
+    if local:
+        local_path.write_text(json.dumps(local, indent=2, ensure_ascii=False), encoding="utf-8")
+    elif local_path.exists():
+        local_path.unlink()
     root_label = "<PACKET_TRACER_SAVES_ROOT>"
     lines = ["# Packet Tracer Installed Sample Catalog", "", f"Source root: `{root_label}`", ""]
-    for item in enriched:
+    for item in installed:
         if "error" in item:
             lines.append(f"- `{item['relative_path']}`")
             lines.append(f"  decode error: `{item['error']}`")