bytesim 0.1.0__py3-none-any.whl

bytesim/tui/commands/addressing.py

@@ -0,0 +1,235 @@
+"""Addresses: keeping them in step with the cabling, DHCP, ad-hoc, static config."""
+from __future__ import annotations
+
+from rich.markup import escape
+
+
+from ...model import Device, Iface, NetError, fmt
+from ..inspector import mode_text
+from .base import CommandHost
+from .registry import command
+
+
+class AddressCommands(CommandHost):
+    @command("dhcp")
+    def cmd_dhcp(self, args: list[str], opts: dict[str, str]) -> None:
+        self._need_addr_mode("dhcp")
+        if not args:
+            raise NetError("usage: dhcp <id[:nic]|all> ...")
+        for nic in self._nics(args):
+            self._dhcp_exchange(nic)
+        self.refresh_sidebar()
+
+    @command("release")
+    def cmd_release(self, args: list[str], opts: dict[str, str]) -> None:
+        if not args:
+            raise NetError("usage: release <id[:nic]|all> ...")
+        self._need_addr_mode("release")
+        for nic in self._nics(args):
+            ifc = self.net.iface(*nic)
+            if ifc.addr:
+                self.log_msg(f"[gold1]DHCP[/] {self._ifname(nic)} RELEASE {fmt(ifc.addr)}")
+            ifc.mode = "none"
+            ifc.clear()
+        self.changed()
+
+    @command("adhoc")
+    def cmd_adhoc(self, args: list[str], opts: dict[str, str]) -> None:
+        if not args:
+            raise NetError("usage: adhoc <id[:nic]|all> ...")
+        self._need_addr_mode("adhoc")
+        for nic in self._nics(args):
+            ifc = self.net.iface(*nic)
+            ifc.mode = "adhoc"
+            ifc.clear()
+            self.net.adhoc(nic)
+            self.log_msg(f"{self._ifname(nic)} → {fmt(ifc.addr)} [yellow](ad-hoc: free host "
+                         f"on network {ifc.net}, no server)[/]")
+        self.changed()
+
+    @command("dhcpd")
+    def cmd_dhcpd(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if not args:
+            for d in net.sorted_devices():
+                if d.kind in "rg":
+                    self.log_msg(f"{d.id}: DHCP server {'[red]off[/]' if d.id in net.dhcp_off else '[green]on[/]'}")
+            return
+        did = net.get(self._ref(args[0])[0]).id
+        if not net.is_router(did):
+            raise NetError("only routers and gateways run a DHCP server")
+        if len(args) > 1:
+            if args[1].lower() not in ("on", "off"):
+                raise NetError("usage: dhcpd <router> [on|off]")
+            (net.dhcp_off.discard if args[1].lower() == "on" else net.dhcp_off.add)(did)
+        self.log_msg(f"{did}: DHCP server {'[red]off[/]' if did in net.dhcp_off else '[green]on[/]'}")
+        self.changed()
+
+    def reconcile(self, skip: frozenset[tuple[str, int]] = frozenset()) -> None:
+        """Bring STP and addresses in line with the cabling, and say what changed."""
+        for note in self.net.stp_update():
+            color = "green" if note.startswith("broadcast storm over") else "cyan"
+            self.log_msg(f"[{color}]{escape(note)}[/]")
+        if self.graph:
+            return
+        notes = self.net.reconcile(skip)       # STP is already current, so these are addresses
+        if len(notes) > 4:
+            self.log_msg(f"[dim]auto-config: {len(notes)} address changes (type [b]ip[/b] to list)[/]")
+        else:
+            for n in notes:
+                self.log_msg(f"[dim]{escape(n)}[/]")
+
+    def _need_addr_mode(self, what: str) -> None:
+        if self.graph:
+            raise NetError(f"{what} needs addressing: switch with `mode addr`")
+
+    def _nics(self, toks: list[str], kinds: str = "c") -> list[tuple[str, int]]:
+        """Expand c1 / c1:2 / all into cabled NICs."""
+        net = self.net
+        out: list[tuple[str, int]] = []
+        for t in toks:
+            if t.lower() in ("all", "*"):
+                devs = [d for d in net.sorted_devices() if d.kind in kinds]
+                out += [(d.id, p) for d in devs for p in range(1, d.nports + 1)
+                        if net.link_index(d.id, p) is not None]
+                continue
+            did, port = self._ref(t)
+            dev = net.get(did)
+            if dev.kind not in kinds:
+                raise NetError(f"{did} is a {dev.name}: this only applies to computers"
+                               + (" (routers serve DHCP: see dhcpd)" if dev.kind in "rg" else ""))
+            if port is not None:
+                if not 1 <= port <= dev.nports:
+                    raise NetError(f"{did} has no port {port}")
+                out.append((did, port))
+            else:
+                out += [(did, p) for p in range(1, dev.nports + 1)
+                        if net.link_index(did, p) is not None] or [(did, 1)]
+        return out
+
+    def _dhcp_exchange(self, nic: tuple[str, int]) -> None:
+        """Animated DISCOVER (broadcast) then OFFER/ACK (unicast), or ad-hoc fallback."""
+        net, c = self.net, self.canvas
+        name = self._ifname(nic)
+        ifc = net.iface(*nic)
+        if net.link_index(*nic) is None:
+            self.log_msg(f"[yellow]{name}: no cable, so no DHCP[/]")
+            return
+        ifc.mode = "dhcp"
+        mac = net.devices[nic[0]].mac(nic[1])
+        if net.storm_near(nic[0]):
+            self.log_msg(f"[b gold1]DHCP[/] {name} [red]DISCOVER lost: the links are saturated"
+                         f"{self.storm_hint(nic[0])}[/]")  # type: ignore[attr-defined]
+            return
+        fl = net.flood(nic)
+        if fl.storm:
+            self.log_msg(f"[b gold1]DHCP[/] {name} [dim]{mac}[/] DISCOVER → broadcast")
+            self.set_off_storm(fl, f"the DHCP DISCOVER from {name}")  # type: ignore[attr-defined]
+            self.log_msg("  [red]DHCP failed: the DISCOVER drowned in the storm it caused[/]")
+            return
+        kind, server = net.lease(nic)
+        net.learn_flood(fl)
+        reached = len(fl.delivered)
+        self.log_msg(f"[b gold1]DHCP[/] {name} [dim]{mac}[/] DISCOVER → broadcast "
+                     f"(reaches {reached} interface{'s' if reached != 1 else ''})")
+
+        def done(back: list[tuple[str, int]] | None) -> None:
+            if back:
+                c.cool([li for _, li in back[1:]])
+            c.flash_device(nic[0], "gold1" if server else "yellow")
+            if kind == "adhoc":
+                self.log_msg(f"  [yellow]no DHCP server answered: took free address "
+                             f"{fmt(ifc.addr)} on network {ifc.net} (ad-hoc)[/]")
+            else:
+                verb = "ACK (renewed)" if kind == "renew" else "OFFER → REQUEST → ACK"
+                self.log_msg(f"  [gold1]{verb}[/] from {server[0]} {fmt(net.addr_of(server))}: "
+                             f"network {ifc.net} → host {ifc.host}, gateway {ifc.gw}")
+            self.refresh_sidebar()
+            c.refresh()
+
+        def discovered() -> None:
+            if server is None:
+                done(None)
+                return
+            back = net.l2path(server, nic)
+            net.learn(server, back)
+            c.heat([li for _, li in back[1:]])
+            c.send_packet(self._cells(back), "green", lambda: done(back))
+
+        if not fl.generations:
+            done(None)
+        else:
+            self.animate_flood(fl, "gold1", discovered)  # type: ignore[attr-defined]
+
+    @command("ip")
+    def cmd_ip(self, args: list[str], opts: dict[str, str]) -> None:
+        self._need_addr_mode("ip")
+        net = self.net
+        if not args:
+            self.log_msg("[b]DEVICE    MAC     NET  HOST  MODE       GW[/]")
+            for d in net.sorted_devices():
+                for p in range(1, d.nports + 1):
+                    ifc = net.ifaces.get(f"{d.id}:{p}")
+                    if ifc and (ifc.addr or (d.kind == "c" and net.link_index(d.id, p) is not None)):
+                        self._log_iface(d, p, ifc)
+            if not net.ifaces:
+                self.log_msg("[dim]no addresses yet: cable a computer to a router or switch[/]")
+            return
+        did, port = self._ref(args[0])
+        dev = net.get(did)
+        if dev.kind == "s":
+            raise NetError(f"{did} is a switch: layer 2 only, no addresses (its MAC table is in the inspector)")
+        if len(args) == 1:
+            for p in ([port] if port else range(1, dev.nports + 1)):
+                self._log_iface(dev, p, net.iface(did, p))
+            return
+        if port is None:
+            if dev.nports != 1:
+                raise NetError(f"{did} has {dev.nports} ports: say which, e.g. {did}:1")
+            port = 1
+        nic, ifc = (did, port), net.iface(did, port)
+        what = args[1].lower()
+        if what == "dhcp" or (what == "auto" and dev.kind == "c"):
+            if dev.kind != "c":
+                raise NetError("only computers are DHCP clients")
+            self._dhcp_exchange(nic)
+        elif what == "adhoc" and dev.kind == "c":
+            ifc.mode = "adhoc"
+            ifc.clear()
+            net.adhoc(nic)
+            self.log_msg(f"{self._ifname(nic)} → {fmt(ifc.addr)} [yellow](ad-hoc)[/]")
+        elif what == "auto":
+            ifc.mode = "auto"
+            ifc.clear()
+            self.log_msg(f"{self._ifname(nic)} back to automatic addressing")
+        elif what in ("none", "clear", "off"):
+            ifc.mode = "none"
+            ifc.clear()
+            self.log_msg(f"{self._ifname(nic)} unconfigured")
+        else:
+            usage = "usage: ip <id:port> (net,host) [gateway-host] | dhcp | adhoc | none"
+            try:
+                addr = self._parse_addr(args[1])
+                gw = int(args[2]) if len(args) > 2 else None
+            except ValueError:
+                raise NetError(usage) from None
+            if addr is None:
+                raise NetError(usage)
+            owner = net.resolve(addr)
+            if owner and owner != nic:
+                raise NetError(f"{fmt(addr)} is already used by {self._ifname(owner)} (ARP conflict)")
+            ifc.mode, ifc.via = "static", "static"
+            ifc.net, ifc.host = addr
+            ifc.gw = gw if dev.kind == "c" else None
+            self.log_msg(f"{self._ifname(nic)} → {fmt(addr)}"
+                         + (f" gateway {fmt((addr[0], gw))}" if ifc.gw else "") + " [cyan](static)[/]")
+        self.changed()
+
+    def _log_iface(self, d: Device, p: int, ifc: Iface) -> None:
+        cabled = self.net.link_index(d.id, p) is not None
+        net = str(ifc.net) if ifc.addr else "—"
+        host = str(ifc.host) if ifc.addr else "—"
+        gw = str(ifc.gw) if ifc.gw is not None else ""
+        state = "" if cabled else " [dim](no cable)[/]"
+        self.log_msg(f"[{d.color}]{d.id + ':' + d.port_name(p):<9}[/] {d.mac(p):<7} {net:>3}  {host:>4}  "
+                     f"{mode_text(ifc):<10} {gw}{state}")

bytesim/tui/commands/base.py

@@ -0,0 +1,43 @@
+"""What every command mixin may rely on from the app."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ...constants import REF
+from ...model import NetError, Network
+
+if TYPE_CHECKING:
+    from ..canvas import NetCanvas
+
+
+class CommandHost:
+    """Attributes and helpers the app provides to the command mixins."""
+
+    net: Network
+    auto: bool
+    graph: bool
+    replaying: int = 0          # > 0 while a script runs (hosts may batch their side effects)
+
+    @property
+    def canvas(self) -> "NetCanvas":
+        raise NotImplementedError
+
+    def log_msg(self, msg: str) -> None:
+        raise NotImplementedError
+
+    def changed(self, skip: frozenset[tuple[str, int]] = frozenset()) -> None:
+        raise NotImplementedError
+
+    def refresh_sidebar(self) -> None:
+        raise NotImplementedError
+
+    def dispatch(self, toks: list[str]) -> None:
+        raise NotImplementedError
+
+    @staticmethod
+    def _ref(tok: str) -> tuple[str, int | None]:
+        """Parse a device token like ``r1`` or ``s2:5`` into (id, port)."""
+        m = REF.match(tok)
+        if not m:
+            raise NetError(f"not a device id: {tok!r} (expected something like r1 or s2:5)")
+        return f"{m[1].lower()}{int(m[2])}", int(m[3]) if m[3] else None

bytesim/tui/commands/groups.py

@@ -0,0 +1,215 @@
+"""Groups (nestable) and HA clusters."""
+from __future__ import annotations
+
+from ...constants import POLICIES, VIP_HOST
+from ...model import NetError, fmt
+from ..theme import HA_COLOR, group_color
+from .base import CommandHost
+from .registry import command
+
+
+def _call(tok: str) -> tuple[str, list[str] | None]:
+    """'link2(rfab2,rfab3)' → ('link2', ['rfab2', 'rfab3']); 'link(1)' stays an auto name."""
+    if not tok.endswith(")") or "(" not in tok:
+        return tok, None
+    at = tok.rindex("(")
+    name, inner = tok[:at], tok[at + 1:-1]
+    if inner.isdigit() and "(" not in name:          # fab(1): auto-numbering, not endpoints
+        return tok, None
+    ends = [e for e in inner.split(",") if e]
+    if not ends or not name:
+        raise NetError(f"{tok}: expected name(endpoint, …)")
+    return name, [e.lower() for e in ends]
+
+
+class GroupCommands(CommandHost):
+    @command("group")
+    def cmd_group(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if not args:
+            self.dispatch(["groups"])
+            return
+        name = args[0].lower()
+        if len(args) == 1:
+            if name not in net.groups:
+                raise NetError(f"no such group: {name} (create one with group {name} <ids...>)")
+            self.canvas.select_group(name)
+            self.canvas.focus()
+            return
+        name = net.resolve_group_name(name)          # fab(1) → the next free fabN
+        moved = net.group_add(name, self._members(args[1:]))
+        if moved:
+            self.log_msg(f"[dim]moved {' '.join(moved)} out of their old group[/]")
+        self.log_msg(f"[{group_color(name)}]▣ group {name}[/]: {self._group_text(name)}")
+        self.changed()
+
+    @command("clone", "copy", "dup")
+    def cmd_clone(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        usage = ("usage: clone <group> [new-name]  ·  clone <group>(old, …) <new-name>(new, …)\n"
+                 "  e.g. copy link1(rfab1, rfab2) link2(rfab2, rfab3) creates link2 cabled to rfab2 and rfab3 "
+                 "the way link1 is cabled to rfab1 and rfab2")
+        if not 1 <= len(args) <= 2:
+            raise NetError(usage)
+        name, old_ends = _call(args[0])
+        new_tok, new_ends = _call(args[1]) if len(args) == 2 else (None, None)
+        name = name.lower()
+        if name not in net.groups:
+            raise NetError(f"no such group: {name}\n{usage}")
+        if (old_ends is None) != (new_ends is None):
+            raise NetError("give the endpoints on both sides: group(old, …) new(new, …)")
+        if old_ends is not None and len(old_ends) != len(new_ends):
+            raise NetError(f"{len(old_ends)} old endpoints but {len(new_ends)} new ones: they're paired in order")
+        dx = 0
+        if not self.auto:                     # manual layout: put the copy just right of the original
+            x0, _, x1, _ = net.group_bounds(name)
+            dx = x1 - x0 + 3
+        new_name = net.resolve_group_name(new_tok) if new_tok else None
+        res = net.clone_group(name, new_name, dx=dx, rewire=list(zip(old_ends or [], new_ends or [])))
+        devs = " ".join(f"{o}→{n}" for o, n in res.devices.items())
+        subs = [f"{o}→{n}" for o, n in res.groups.items() if o != name]
+        self.log_msg(f"[{group_color(res.group)}]▣ cloned {name} → {res.group}[/]: {len(res.devices)} devices, "
+                     f"{res.cables} internal cable{'s' if res.cables != 1 else ''}"
+                     + (f", {res.rewired} rewired to {' '.join(new_ends or [])}" if res.rewired else "")
+                     + (f" [dim]({res.skipped} to the outside not copied)[/]" if res.skipped else ""))
+        if res.moved:
+            self.log_msg(f"  [dim]ports already taken, used the next free: {' '.join(res.moved)}[/]")
+        self.log_msg(f"  [dim]{devs}{'  ·  groups ' + ' '.join(subs) if subs else ''}[/]")
+        self.changed()
+        self.canvas.select_group(res.group)
+
+    def copy_cabling(self, args: list[str]) -> None:
+        """ports copy link1(rfab1, rfab2) link2(rfab2, rfab3)"""
+        net = self.net
+        usage = ("usage: ports copy <group>(old, …) <group>(new, …)\n"
+                 "  e.g. ports copy link1(rfab1, rfab2) link2(rfab2, rfab3): cable link2 to rfab2 and rfab3 "
+                 "the way link1 is cabled to rfab1 and rfab2")
+        if len(args) != 2:
+            raise NetError(usage)
+        (src, old_ends), (dst, new_ends) = _call(args[0]), _call(args[1])
+        if old_ends is None or new_ends is None:
+            raise NetError(f"give the endpoints on both sides\n{usage}")
+        if len(old_ends) != len(new_ends):
+            raise NetError(f"{len(old_ends)} old endpoints but {len(new_ends)} new ones: they're paired in order")
+        src, dst = src.lower(), dst.lower()
+        if dst not in net.groups and src in net.groups:
+            raise NetError(f"no group {dst}: `ports copy` only cables existing devices. To create {dst} "
+                           f"with this cabling: copy {args[0]} {args[1]}")
+        res = net.copy_cabling(src, dst, list(zip(old_ends, new_ends)))
+        pairs = ", ".join(f"{o}→{n}" for o, n in zip(old_ends, new_ends))
+        if res.made:
+            self.log_msg(f"[green]⇄[/] {dst} now cabled like {src} [dim]({pairs})[/]: "
+                         f"{res.made} cable{'s' if res.made != 1 else ''} made"
+                         + (f", {res.already} already there" if res.already else ""))
+        else:
+            self.log_msg(f"{dst} is already cabled like {src} ({pairs}): nothing to do")
+        if res.moved:
+            self.log_msg(f"  [dim]ports already taken, used the next free: {' '.join(res.moved)}[/]")
+        self.changed()
+
+    @command("ungroup")
+    def cmd_ungroup(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if not args:
+            raise NetError("usage: ungroup <group> [member ...]")
+        name = args[0].lower()
+        parent = net.parent_of(name)
+        n = net.ungroup(name, self._members(args[1:]) or None)
+        where = f"into {parent}" if parent else "to the top level"
+        if name not in net.groups:
+            self.log_msg(f"[yellow]▢[/] dissolved {name}: {n} member{'s' if n != 1 else ''} moved {where}")
+        else:
+            self.log_msg(f"[yellow]▢[/] took {n} out of {name}, {where}")
+        self.changed()
+
+    @command("groups")
+    def cmd_groups(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+
+        def tree(g: str, depth: int) -> None:
+            devs = [m for m in net.groups[g] if m not in net.groups]
+            tag = " [dim](HA cluster)[/]" if g in net.clusters else ""
+            self.log_msg(f"{'  ' * depth}[{group_color(g)}]▣ {g}[/]{tag} {' '.join(devs)}")
+            for sub in net.subgroups(g):
+                tree(sub, depth + 1)
+
+        for g in net.groups:
+            if net.parent_of(g) is None:
+                tree(g, 0)
+        if not net.groups:
+            self.log_msg("[dim]no groups — try: group fab1 s1 s2 s3[/]")
+
+    @command("uncluster")
+    def cmd_uncluster(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if not args or args[0].lower() not in net.clusters:
+            raise NetError("usage: uncluster <cluster>  (the routers stay grouped)")
+        del net.clusters[args[0].lower()]
+        self.log_msg(f"{args[0].lower()} is a plain group again")
+        self.changed()
+
+    @command("clusters")
+    def cmd_clusters(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        for c in net.clusters:
+            st = net.ha_state(c)
+            self.log_msg(f"[{HA_COLOR[st['level']]}]{c:<8}[/] {' '.join(st['members'])}  {st['text']}")
+        if not net.clusters:
+            self.log_msg("[dim]no clusters: try cluster rfab1 r1 r2[/]")
+
+    def _members(self, toks: list[str]) -> list[str]:
+        """Group-command tokens: existing group names stay names, the rest are device ids."""
+        return [t.lower() if t.lower() in self.net.groups else self._ref(t)[0] for t in toks]
+
+    def _group_text(self, g: str) -> str:
+        """Members, with subgroups shown as name[device count]."""
+        net = self.net
+        return " ".join(f"[{group_color(m)}]{m}[/]\\[{len(net.devices_in(m))}]" if m in net.groups else m
+                        for m in net.groups[g])
+
+    @command("cluster")
+    def cmd_cluster(self, args: list[str], opts: dict[str, str]) -> None:
+        net = self.net
+        if not args:
+            self.dispatch(["clusters"])
+            return
+        name = args[0].lower()
+        policy = opts.get("policy")
+        if policy is not None and policy not in POLICIES:
+            raise NetError(f"policy must be one of: {', '.join(POLICIES)}")
+        if len(args) > 1:
+            ids = [net.get(self._ref(t)[0]).id for t in args[1:]]
+            bad = [d for d in ids if not net.is_router(d)]
+            if bad:
+                raise NetError(f"only routers and gateways can be clustered: {' '.join(bad)}")
+            net.group_add(name, ids)
+            net.clusters[name] = policy or net.clusters.get(name, "none")
+            self.log_msg(f"[{group_color(name)}]▣ cluster {name}[/]: {' '.join(net.groups[name])} "
+                         f"[dim](policy {net.clusters[name]}; virtual gateway host {VIP_HOST} on each network)[/]")
+        elif name not in net.clusters:
+            raise NetError(f"no such cluster: {name} (create: cluster {name} r1 r2)")
+        elif policy:
+            net.clusters[name] = policy
+            self.log_msg(f"{name}: split policy → {policy}")
+        else:
+            st = net.ha_state(name)
+            self.log_msg(f"[{HA_COLOR[st['level']]}]{name}: {st['text']}[/]")
+            for netid, owners in sorted(st["owners"].items()):
+                self.log_msg(f"  {fmt((netid, VIP_HOST))} → {' and '.join(o[0] for o in owners)}")
+            return
+        self.changed()
+
+    def _ha_report(self) -> None:
+        """Log cluster state changes (failover, split-brain, recovery) as they happen."""
+        seen = getattr(self, "_ha_seen", {})
+        now = {}
+        for c in self.net.clusters:
+            st = self.net.ha_state(c)
+            owners = " ".join(f"{fmt((n, VIP_HOST))}→{'+'.join(o[0] for o in os)}"
+                              for n, os in sorted(st["owners"].items()))
+            now[c] = (st["level"], st["text"], owners)
+            if seen.get(c) != now[c]:
+                icon = {"ok": "✓", "degraded": "▲", "split": "⚡", "down": "✕"}[st["level"]]
+                self.log_msg(f"[{HA_COLOR[st['level']]}]{icon} {c}: {st['text']}[/]"
+                             + (f"\n  [dim]virtual gateways: {owners}[/]" if owners else ""))
+        self._ha_seen = now

bytesim/tui/commands/history.py

@@ -0,0 +1,134 @@
+"""Multi-level undo and redo.
+
+Every command that changes the network is one step: a whole ``run`` script,
+``clear`` and ``load`` included. A burst of moves (arrow keys, or one drag) is
+one step too. Read-only commands don't create steps, and neither does traffic
+that only teaches switches MAC addresses. A storm it sets off does count.
+"""
+from __future__ import annotations
+
+import copy
+import time
+from dataclasses import dataclass
+
+from rich.markup import escape
+
+from ...model import NetError, Network
+from .base import CommandHost
+from .registry import command
+
+UNDO_LIMIT = 100
+MOVE_BURST = 2.0          # seconds: moves closer together than this are one step
+NOT_RECORDED = {"undo", "redo", "history"}
+
+
+@dataclass
+class Step:
+    label: str
+    net: Network
+    auto: bool
+    selection: tuple[str | None, str | None]
+
+
+def fingerprint(net: Network) -> str:
+    """What counts as a change: everything saved, plus storms (not MAC tables)."""
+    return net.to_json() + "|" + ",".join(sorted(net.storming))
+
+
+class HistoryCommands(CommandHost):
+    @property
+    def undo_stack(self) -> list[Step]:
+        return self.__dict__.setdefault("_undo", [])
+
+    @property
+    def redo_stack(self) -> list[Step]:
+        return self.__dict__.setdefault("_redo", [])
+
+    def snapshot(self, label: str = "") -> Step:
+        c = self.canvas
+        return Step(label, copy.deepcopy(self.net), self.auto, (c.selected, c.selected_group))
+
+    def record(self, step: Step) -> None:
+        """Push a 'before' state; a new change makes the redo stack meaningless."""
+        self.undo_stack.append(step)
+        del self.undo_stack[:-UNDO_LIMIT]
+        self.redo_stack.clear()
+        self.__dict__["_last_move"] = None
+
+    def recorded(self, label: str, action) -> None:
+        """Run an action, keeping one undo step if it changed anything."""
+        words = label.split()
+        if not words or words[0].lower() in NOT_RECORDED:
+            action()
+            return
+        before, mark = self.snapshot(label), fingerprint(self.net)
+        try:
+            action()
+        finally:
+            if fingerprint(self.net) != mark:
+                self.record(before)
+
+    def before_move(self, what: str) -> None:
+        """Called just before devices move: one step per burst of moves of the same thing."""
+        last = self.__dict__.get("_last_move")
+        now = time.monotonic()
+        if last and last[0] == what and now - last[1] < MOVE_BURST:
+            self.__dict__["_last_move"] = (what, now)
+            return
+        self.record(self.snapshot(f"move {what}"))
+        self.__dict__["_last_move"] = (what, now)
+
+    def _restore(self, step: Step) -> None:
+        self.net = step.net
+        self.auto = step.auto
+        c = self.canvas
+        c.reset()
+        sel, group = step.selection
+        if sel in self.net.devices:
+            c.selected = sel
+        elif group in self.net.groups:
+            c.selected_group = group
+        self.__dict__["_last_move"] = None
+        self.changed()
+
+    def _travel(self, args: list[str], back: bool) -> None:
+        word = "undo" if back else "redo"
+        try:
+            n = int(args[0]) if args else 1
+        except ValueError:
+            raise NetError(f"usage: {word} [steps]") from None
+        source, target = (self.undo_stack, self.redo_stack) if back else (self.redo_stack, self.undo_stack)
+        if not source:
+            raise NetError(f"nothing to {word}")
+        labels = []
+        for _ in range(max(1, n)):
+            if not source:
+                break
+            step = source.pop()
+            target.append(self.snapshot(step.label))
+            labels.append(step.label)
+            self._restore(step)
+        arrow = "↶ undid" if back else "↷ redid"
+        self.log_msg(f"[cyan]{arrow}[/] " + " · ".join(escape(x) for x in labels)
+                     + f"  [dim]({len(self.undo_stack)} to undo, {len(self.redo_stack)} to redo)[/]")
+
+    @command("undo")
+    def cmd_undo(self, args: list[str], opts: dict[str, str]) -> None:
+        self._travel(args, back=True)
+
+    @command("redo")
+    def cmd_redo(self, args: list[str], opts: dict[str, str]) -> None:
+        self._travel(args, back=False)
+
+    @command("history")
+    def cmd_history(self, args: list[str], opts: dict[str, str]) -> None:
+        if not self.undo_stack and not self.redo_stack:
+            self.log_msg("[dim]nothing to undo yet[/]")
+            return
+        for i, step in enumerate(reversed(self.undo_stack[-15:]), 1):
+            self.log_msg(f"  {i:>2}  {escape(step.label)}" + ("   [dim]← undo goes back past this[/]" if i == 1 else ""))
+        if len(self.undo_stack) > 15:
+            self.log_msg(f"  [dim]… {len(self.undo_stack) - 15} older[/]")
+        if self.redo_stack:
+            self.log_msg(f"  [dim]{len(self.redo_stack)} undone step(s) can be redone: "
+                         f"{escape(self.redo_stack[-1].label)} next[/]")