@isothrum/editor 0.0.0-stage → 0.1.0

package/src/lib/tool/examples.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "vitest";
+import { exampleLab, vlanExample } from "./examples";
+import { canvasIssues } from "./issues";
+import { compile, issueText, sw1Networks } from "@/test/lab";
+
+const networksOf = (t: ReturnType<typeof compile>) => Object.fromEntries(Object.entries(t.nodes).map(([n, m]) => [n, m.networks]));
+
+describe("the starting lab", () => {
+  const t = compile(exampleLab().nodes, exampleLab().edges, exampleLab().name);
+
+  test("puts the workstation on the office LAN, the servers on theirs, and the router on both", () => {
+    expect(networksOf(t)).toEqual({ user: { office: null }, router: { office: null, servers: null }, web: { servers: null }, db: { servers: null } });
+  });
+
+  test("has the workstation as access machine and the servers' services", () => {
+    expect(t.nodes.user.access).toBe(true);
+    expect([t.nodes.web.services, t.nodes.db.services]).toEqual([[{ port: 80 }], [{ port: 5432 }]]);
+  });
+
+  test("has nothing to fix", () => {
+    expect(canvasIssues(exampleLab().nodes, issueText)).toEqual([]);
+  });
+});
+
+describe("the VLAN lab", () => {
+  const t = compile(vlanExample().nodes, vlanExample().edges);
+
+  test("puts the PCs on vlan10, the server on vlan20 and the router on the trunk", () => {
+    expect(networksOf(t)).toEqual({ router: { vlan10: null, vlan20: null }, pc1: { vlan10: null }, pc2: { vlan10: null }, srv: { vlan20: null } });
+  });
+
+  test("nests both VLANs under the switch", () => {
+    expect(t.networks).toEqual(sw1Networks);
+  });
+});

package/src/lib/tool/examples.ts

@@ -0,0 +1,71 @@
+import { twoVlans } from "./create";
+import { DEFAULT_OS } from "./os";
+import { LAN_BEHAVIOR, MACHINE_H, MACHINE_W, type CableEdge, type Draft, type LabNode, type LanData, type LanNode, type MachineData, type MachineNode } from "./model";
+
+/** The labs the menu loads: one to start from, and one with VLANs. */
+
+const base = { image: "", os: "", provision: "", ports: "", access: false };
+
+const machine = (id: string, position: { x: number; y: number }, data: MachineData): MachineNode => ({ id, type: "machine", position, data });
+
+const lan = (id: string, area: { x: number; y: number; w: number; h: number }, data: LanData): LanNode => ({
+  ...LAN_BEHAVIOR,
+  id,
+  type: "lan",
+  position: { x: area.x, y: area.y },
+  width: area.w,
+  height: area.h,
+  data,
+});
+
+/** A cable from `source` to `target`, its handles and port labels as [source's, target's]. */
+const cable = (id: string, [source, target]: [string, string], [sh, th]: [string, string], [aPort, bPort]: [string, string]): CableEdge => ({
+  id,
+  type: "cable",
+  source,
+  sourceHandle: sh,
+  target,
+  targetHandle: th,
+  data: { aPort, bPort },
+});
+
+/**
+ * A starting lab: an office LAN with a workstation, a servers LAN with a web server and a
+ * database, and a router cabled to both LANs.
+ */
+export function exampleLab(): Draft {
+  const nodes: LabNode[] = [
+    // LANs first, so they are drawn under the machines.
+    lan("l-office", { x: -40, y: 40, w: 280, h: 260 }, { name: "office", cidr: "10.10.1.0/24", internet: true }),
+    lan("l-servers", { x: 560, y: -80, w: 300, h: 500 }, { name: "servers", cidr: "10.10.2.0/24", internet: true }),
+    machine("m-user", { x: 40, y: 110 }, { ...base, name: "user", kind: "vm", icon: "laptop", os: DEFAULT_OS, access: true }),
+    // On the office LAN's right edge: a two-network appliance, office on one side, its port out.
+    machine("m-router", { x: 240 - MACHINE_W / 2, y: 170 - MACHINE_H / 2 }, { ...base, name: "router", kind: "router", icon: "router" }),
+    machine("m-web", { x: 650, y: 0 }, { ...base, name: "web", kind: "container", icon: "server", image: "nginx:1.27-alpine", ports: "80" }),
+    machine("m-db", { x: 650, y: 240 }, { ...base, name: "db", kind: "vm", icon: "monitor", os: DEFAULT_OS, provision: "provision/db.sh", ports: "5432" }),
+  ];
+  const edges = [cable("c-1", ["m-router", "l-servers"], ["port", "left"], ["eth1", ""])];
+  return { name: "office-lab", nodes, edges };
+}
+
+/**
+ * The VLAN example: a switch with vlan10 and vlan20, two PCs on vlan10, a server on vlan20, and a
+ * router on the trunk (router-on-a-stick: one address on each VLAN).
+ */
+export function vlanExample(): Draft {
+  const nodes: LabNode[] = [
+    { id: "s-sw1", type: "switch", position: { x: 40, y: 0 }, data: { ...twoVlans(), name: "sw1" } },
+    machine("m-router", { x: 180, y: -230 }, { ...base, name: "router", kind: "router", icon: "router" }),
+    machine("m-pc1", { x: -140, y: 220 }, { ...base, name: "pc1", kind: "vm", icon: "laptop", os: DEFAULT_OS, access: true }),
+    machine("m-pc2", { x: 40, y: 220 }, { ...base, name: "pc2", kind: "container", icon: "container", image: "alpine:3.20" }),
+    machine("m-srv", { x: 300, y: 220 }, { ...base, name: "srv", kind: "container", icon: "server", image: "nginx:1.27-alpine", ports: "80" }),
+  ];
+  const onSwitch = (id: string, m: string, mh: string, port: string, labels: [string, string]) => cable(id, [m, "s-sw1"], [mh, port], labels);
+  const edges = [
+    onSwitch("c-1", "m-router", "port", "trunk", ["eth0", "T"]),
+    onSwitch("c-2", "m-pc1", "top", "p1", ["eth0", "1"]),
+    onSwitch("c-3", "m-pc2", "top", "p2", ["eth0", "2"]),
+    onSwitch("c-4", "m-srv", "top", "p5", ["eth0", "5"]),
+  ];
+  return { name: "vlan-lab", nodes, edges };
+}

package/src/lib/tool/export-targets.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "vitest";
+import { groupByTarget } from "./export-targets";
+
+const text = { containersAndVms: "containers and VMs", oneVmPerMachine: "one VM per machine", dockerOnOneVm: "Docker on one VM" };
+const file = (path: string) => ({ path, contents: "" });
+const target = (dir: string) => groupByTarget([file(`.isoloom/${dir}/main.tf`)], text)[0];
+
+describe("groupByTarget", () => {
+  test("groups files by target, subfolders with their target", () => {
+    const groups = groupByTarget([file(".isoloom/docker/compose.yml"), file(".isoloom/docker/checks/web.sh"), file(".isoloom/vagrant/Vagrantfile")], text);
+    expect(groups.map((g) => [g.dir, g.files.length])).toEqual([
+      ["docker", 2],
+      ["vagrant", 1],
+    ]);
+  });
+
+  test("names Docker Compose, with the command that starts it and the tool's own", () => {
+    expect(target("docker")).toMatchObject({ name: "Docker Compose", isoloom: "isoloom run docker", run: "docker compose -f .isoloom/docker/compose.yml up -d" });
+  });
+
+  test("names the Vagrant outputs by what they run", () => {
+    expect([target("vagrant").name, target("hybrid").name, target("docker-vm").name]).toEqual([
+      "Vagrant (one VM per machine)",
+      "Vagrant (containers and VMs)",
+      "Vagrant (Docker on one VM)",
+    ]);
+  });
+
+  test("a cloud output is one folder per cloud, run with Terraform", () => {
+    expect(target("cloud-docker/aws")).toMatchObject({ name: "AWS (Docker on one VM)", isoloom: "isoloom run cloud-docker --cloud aws" });
+    expect(target("cloud-vm/gcp")).toMatchObject({ name: "Google Cloud (one VM per machine)", run: "cd .isoloom/cloud-vm/gcp && terraform init && terraform apply" });
+  });
+
+  test("docker-vm's Proxmox module is its own output, with no Isoloom command", () => {
+    expect(target("docker-vm/proxmox")).toMatchObject({ name: "Proxmox (Docker on one VM)", isoloom: null });
+  });
+
+  test("Proxmox and Kubernetes have their commands", () => {
+    expect(target("proxmox")).toMatchObject({ name: "Proxmox (one VM per machine)", isoloom: "isoloom run proxmox" });
+    expect(target("kubernetes").isoloom).toBe("isoloom run kubernetes");
+  });
+
+  test("an unknown cloud keeps its folder's name, an unknown target its folder and no command", () => {
+    expect(target("cloud-vm/mars").name).toBe("mars (one VM per machine)");
+    expect(target("mystery")).toMatchObject({ name: "mystery", isoloom: null, run: "" });
+  });
+});

package/src/lib/tool/export-targets.ts

@@ -0,0 +1,84 @@
+import type { GeneratedFile } from "./engine";
+
+/**
+ * The Isoloom outputs in a lab's zip, as the Export window lists them: how each is named for
+ * people, the one Isoloom command that starts it (from the unzipped folder), and the same thing
+ * with the tool itself.
+ */
+
+/** The words the names take (the editor's text). */
+export interface TargetText {
+  containersAndVms: string;
+  oneVmPerMachine: string;
+  dockerOnOneVm: string;
+}
+
+export interface Target {
+  dir: string;
+  files: GeneratedFile[];
+  name: string;
+  isoloom: string | null;
+  run: string;
+}
+
+const CLOUDS: Partial<Record<string, string>> = {
+  aws: "AWS",
+  azure: "Azure",
+  gcp: "Google Cloud",
+  digitalocean: "DigitalOcean",
+  linode: "Linode",
+  oci: "Oracle Cloud",
+};
+
+type Described = Pick<Target, "name" | "isoloom" | "run">;
+
+/** A cloud output (one folder per cloud): Docker on one VM, or one VM per machine. */
+function cloudTarget(target: string, cloud: string | undefined, terraform: string, t: TargetText): Described {
+  const where = CLOUDS[cloud ?? ""] ?? String(cloud);
+  if (target === "cloud-docker") return { name: `${where} (${t.dockerOnOneVm})`, isoloom: `isoloom run cloud-docker --cloud ${String(cloud)}`, run: terraform };
+  return { name: `${where} (${t.oneVmPerMachine})`, isoloom: `isoloom run cloud-vm --cloud ${String(cloud)}`, run: terraform };
+}
+
+function describe(dir: string, t: TargetText): Described {
+  const [target, cloud] = dir.split("/") as [string, string | undefined];
+  const terraform = `cd .isoloom/${dir} && terraform init && terraform apply`;
+  switch (target) {
+    case "docker":
+      return { name: "Docker Compose", isoloom: "isoloom run docker", run: "docker compose -f .isoloom/docker/compose.yml up -d" };
+    case "hybrid":
+      return { name: `Vagrant (${t.containersAndVms})`, isoloom: "isoloom run hybrid", run: "cd .isoloom/hybrid && vagrant up" };
+    case "vagrant":
+      return { name: `Vagrant (${t.oneVmPerMachine})`, isoloom: "isoloom run vagrant", run: "cd .isoloom/vagrant && vagrant up" };
+    case "docker-vm":
+      return cloud === "proxmox"
+        ? { name: `Proxmox (${t.dockerOnOneVm})`, isoloom: null, run: terraform }
+        : { name: `Vagrant (${t.dockerOnOneVm})`, isoloom: "isoloom run docker-vm", run: "cd .isoloom/docker-vm && vagrant up" };
+    case "proxmox":
+      return { name: `Proxmox (${t.oneVmPerMachine})`, isoloom: "isoloom run proxmox", run: terraform };
+    case "kubernetes":
+      return { name: "Kubernetes", isoloom: "isoloom run kubernetes", run: "kubectl kustomize --load-restrictor LoadRestrictionsNone .isoloom/kubernetes | kubectl apply -f -" };
+    case "cloud-docker":
+    case "cloud-vm":
+      return cloudTarget(target, cloud, terraform, t);
+    default:
+      return { name: dir, isoloom: null, run: "" };
+  }
+}
+
+/** The folder a generated file belongs to: `<target>`, or `<target>/<cloud>` for a cloud output and docker-vm's Proxmox module. */
+function folderOf(path: string): string {
+  const parts = path.replace(/^\.isoloom\//, "").split("/");
+  // Every other subfolder (checks/, …) belongs to its target.
+  const deeper = parts.length > 2 && (parts[0] === "cloud-docker" || parts[0] === "cloud-vm" || (parts[0] === "docker-vm" && parts[1] === "proxmox"));
+  return deeper ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+
+/** Generated files grouped by where they run: `.isoloom/<target>[/<cloud>]/…`. */
+export function groupByTarget(files: GeneratedFile[], t: TargetText): Target[] {
+  const groups = new Map<string, GeneratedFile[]>();
+  for (const f of files) {
+    const dir = folderOf(f.path);
+    groups.set(dir, [...(groups.get(dir) ?? []), f]);
+  }
+  return [...groups.entries()].map(([dir, fs]) => ({ dir, files: fs, ...describe(dir, t) }));
+}

package/src/lib/tool/facing.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "vitest";
+import { facingSides, shownCables } from "./facing";
+import { autoRouter, cable, lan, machine, switchNode } from "@/test/lab";
+
+const office = lan("office");
+const vlanArea = lan("v20", { name: "vlan20" }, { x: 2000 });
+/** On the office LAN's right border. */
+const r = autoRouter("r", { x: 340, y: 92 });
+const web = machine("web", {}, { x: 140, y: 92 });
+const dmz = machine("dmz", {}, { x: 600, y: 92 });
+const cli = machine("cli", {}, { x: 140, y: 500 });
+const sw = switchNode("sw", {}, { x: 0, y: 500 });
+const pc = machine("pc", {}, { x: 0, y: 300 });
+const nodes = [office, vlanArea, r, web, dmz, cli, sw, pc];
+const lans = [office, vlanArea];
+const edges = [
+  cable("toInside", "r", "web", { sourceHandle: "port" }),
+  cable("toOutside", "r", "dmz", { sourceHandle: "port" }),
+  cable("onSwitch", "pc", "sw", { sourceHandle: "top", targetHandle: "p1" }),
+  cable("toLan", "cli", "office", { sourceHandle: "top", targetHandle: "left" }),
+  cable("toVlanArea", "cli", "v20"),
+];
+const shown = (id: string) => shownCables(nodes, edges, lans).find((e) => e.id === id);
+
+describe("facingSides", () => {
+  test("an appliance on a LAN's border faces out of it", () => {
+    expect(facingSides(nodes, edges, lans).r).toBe("right");
+  });
+
+  test("an appliance elsewhere faces down when most of its cables lead below it", () => {
+    const fw = machine("fw", { icon: "shield" }, { x: 1000, y: 0 });
+    const below = [machine("b1", {}, { x: 900, y: 200 }), machine("b2", {}, { x: 1100, y: 200 })];
+    const sides = facingSides([fw, ...below], [cable("c1", "fw", "b1"), cable("c2", "b2", "fw")], []);
+    expect(sides.fw).toBe("bottom");
+  });
+
+  test("an appliance with its cables above keeps its default side", () => {
+    const fw = machine("fw", { icon: "shield" }, { x: 1000, y: 500 });
+    expect(facingSides([fw, pc], [cable("c", "fw", "pc")], []).fw).toBeUndefined();
+  });
+
+  test("a switch's port faces up when the device on it is above the switch", () => {
+    expect(facingSides(nodes, edges, lans)["sw:p1"]).toBe("top");
+  });
+});
+
+describe("shownCables", () => {
+  test("an appliance on a LAN's border shows its inside port toward that LAN's machines, its outside port otherwise", () => {
+    expect([shown("toInside")?.sourceHandle, shown("toOutside")?.sourceHandle]).toEqual(["lan", "port"]);
+  });
+
+  test("a machine's end leaves from its top or bottom, whichever faces the other end", () => {
+    expect([shown("onSwitch")?.sourceHandle, shown("toLan")?.sourceHandle]).toEqual(["bottom", "top"]);
+  });
+
+  test("a switch keeps the port the cable is plugged into", () => {
+    expect(shown("onSwitch")?.targetHandle).toBe("p1");
+  });
+
+  test("a LAN's end is on its side facing the other end", () => {
+    expect(shown("toLan")?.targetHandle).toBe("bottom");
+  });
+
+  test("a cable on a VLAN takes the VLAN's color; one on a plain LAN none", () => {
+    expect([shown("onSwitch")?.data?.color, shown("toVlanArea")?.data?.color, shown("toLan")?.data?.color]).toEqual(["#2f9e44", "#1971c2", undefined]);
+  });
+
+  test("a cable to a node that is gone is shown as it is", () => {
+    const loose = cable("loose", "gone", "web");
+    expect(shownCables(nodes, [loose], lans)[0]).toBe(loose);
+  });
+});

package/src/lib/tool/facing.ts

@@ -0,0 +1,100 @@
+import { networkOfCable } from "./cables";
+import { insideLan, lanUnder, sideOnLan } from "./geometry";
+import { centerOf, isAppliance, isMachine, isRealRouter, isSwitch, type CableEdge, type LabNode, type LanNode, type Side } from "./model";
+import { vlanColor, vlanOf } from "./vlans";
+
+/** Which way ports face and where cables attach: worked out from where things are on the canvas. */
+
+/** A node's vertical middle, by its measured height (its top when it hasn't been measured). */
+const middleY = (n: LabNode) => n.position.y + (n.height ?? n.measured?.height ?? 0) / 2;
+
+/** The nodes at the other end of `n`'s cables. */
+function peersOf(n: LabNode, nodes: LabNode[], edges: CableEdge[]): LabNode[] {
+  return edges
+    .filter((e) => e.source === n.id || e.target === n.id)
+    .flatMap((e) => nodes.find((x) => x.id === (e.source === n.id ? e.target : e.source)) ?? []);
+}
+
+/**
+ * Which way each appliance's single port faces, by node id. On a LAN's edge: out of the LAN.
+ * Elsewhere: toward its cables (down when they mostly lead below it), so they don't cross the box.
+ */
+function applianceSides(nodes: LabNode[], edges: CableEdge[], lans: LanNode[], out: Record<string, Side>): void {
+  for (const n of nodes) {
+    if (!isAppliance(n)) continue;
+    const side = sideOnLan(n, lans);
+    if (side) {
+      out[n.id] = side;
+      continue;
+    }
+    const peers = peersOf(n, nodes, edges);
+    const below = peers.filter((x) => middleY(x) > n.position.y + 58).length;
+    if (peers.length && below > peers.length / 2) out[n.id] = "bottom";
+  }
+}
+
+/** A switch's (or a real router's) port faces up, `<id>:<port>`, when the device on it is above. */
+function portSides(nodes: LabNode[], edges: CableEdge[], out: Record<string, Side>): void {
+  for (const e of edges) {
+    for (const [end, handle, other] of [
+      [e.source, e.sourceHandle, e.target],
+      [e.target, e.targetHandle, e.source],
+    ] as const) {
+      const sw = nodes.find((x) => x.id === end);
+      const peer = nodes.find((x) => x.id === other);
+      if (sw && peer && (isSwitch(sw) || isRealRouter(sw)) && handle && middleY(peer) < sw.position.y) out[`${sw.id}:${handle}`] = "top";
+    }
+  }
+}
+
+/** The sides ports face: an appliance's by its id, a switch's or router's ports by `<id>:<port>`. */
+export function facingSides(nodes: LabNode[], edges: CableEdge[], lans: LanNode[]): Record<string, Side> {
+  const out: Record<string, Side> = {};
+  applianceSides(nodes, edges, lans, out);
+  portSides(nodes, edges, out);
+  return out;
+}
+
+/** The side of a LAN another node lies toward, relative to the LAN's own proportions. */
+function lanSideToward(lan: LabNode, other: LabNode): Side {
+  const a = centerOf(lan);
+  const b = centerOf(other);
+  const dx = (b.x - a.x) / (lan.width ?? lan.measured?.width ?? 1);
+  const dy = (b.y - a.y) / (lan.height ?? lan.measured?.height ?? 1);
+  if (Math.abs(dx) > Math.abs(dy)) return dx > 0 ? "right" : "left";
+  return dy > 0 ? "bottom" : "top";
+}
+
+/**
+ * Where a cable attaches to `n`, going to `other`. A switch keeps the port the cable is plugged
+ * into, and a real router its port. An appliance on a LAN's edge: its inside port toward machines
+ * in that LAN, the outside one otherwise. A machine: its top or bottom, whichever faces the
+ * other end. A LAN: its side facing the other end.
+ */
+function handleFor(n: LabNode, handle: string | null | undefined, other: LabNode, lans: LanNode[]): string | null | undefined {
+  if (isSwitch(n) || isRealRouter(n)) return handle;
+  if (isAppliance(n)) {
+    const under = lanUnder(n, lans);
+    return under && insideLan(centerOf(other), under.lan) ? "lan" : "port";
+  }
+  if (isMachine(n)) return centerOf(other).y < centerOf(n).y ? "top" : "bottom";
+  return lanSideToward(n, other);
+}
+
+/**
+ * The cables as drawn: each end attached where things are now (not where the cable was first
+ * drawn), and a cable on a VLAN (a switch access port, a VLAN area, a router port on it) in its
+ * color.
+ */
+export function shownCables(nodes: LabNode[], edges: CableEdge[], lans: LanNode[]): CableEdge[] {
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  return edges.map((e) => {
+    const a = byId.get(e.source);
+    const b = byId.get(e.target);
+    if (!a || !b) return e;
+    const net = networkOfCable(e.id, nodes, edges);
+    const vlan = net ? vlanOf(net) : null;
+    const data = e.data && vlan !== null ? { ...e.data, color: vlanColor(vlan) } : e.data;
+    return { ...e, data, sourceHandle: handleFor(a, e.sourceHandle, b, lans), targetHandle: handleFor(b, e.targetHandle, a, lans) };
+  });
+}

package/src/lib/tool/geometry.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "vitest";
+import { insideLan, lanRect, lanUnder, lansAround, sideOnLan, snapToLanEdge, within } from "./geometry";
+import { MACHINE_H, MACHINE_W } from "./model";
+import { autoRouter, lan, machine } from "@/test/lab";
+
+/** The 400 by 300 LAN at the origin. */
+const office = lan("office");
+/** The position that centers a machine's box on `p`. */
+const centeredOn = (p: { x: number; y: number }) => ({ x: p.x - MACHINE_W / 2, y: p.y - MACHINE_H / 2 });
+
+describe("areas", () => {
+  test("a LAN covers its position and size", () => {
+    expect(lanRect(lan("l", {}, { x: 5, y: 6, w: 10, h: 20 }))).toEqual({ x: 5, y: 6, w: 10, h: 20 });
+  });
+
+  test("within includes the borders, and the slack around them", () => {
+    const r = { x: 0, y: 0, w: 10, h: 10 };
+    expect([within(r, { x: 10, y: 0 }), within(r, { x: 12, y: 5 }), within(r, { x: 12, y: 5 }, 2)]).toEqual([true, false, true]);
+  });
+
+  test("insideLan excludes the border", () => {
+    expect(insideLan({ x: 200, y: 150 }, office)).toBe(true);
+    expect(insideLan({ x: 0, y: 150 }, office)).toBe(false);
+  });
+});
+
+describe("snapToLanEdge", () => {
+  test("centers an appliance on the nearest border within reach", () => {
+    expect(snapToLanEdge(centeredOn({ x: 10, y: 150 }), [office])).toEqual(centeredOn({ x: 0, y: 150 }));
+    expect(snapToLanEdge(centeredOn({ x: 200, y: 290 }), [office])).toEqual(centeredOn({ x: 200, y: 300 }));
+  });
+
+  test("snaps to the closer of two LANs", () => {
+    const servers = lan("servers", {}, { x: 500, w: 400 });
+    expect(snapToLanEdge(centeredOn({ x: 470, y: 100 }), [office, servers])).toEqual(centeredOn({ x: 500, y: 100 }));
+  });
+
+  test("leaves an appliance where it is when no border is within 36", () => {
+    const far = centeredOn({ x: -37, y: 150 });
+    expect(snapToLanEdge(far, [office])).toBe(far);
+  });
+
+  test("goes by the size it is given", () => {
+    expect(snapToLanEdge({ x: -100, y: 100 }, [office], { w: 180, h: 100 })).toEqual({ x: -90, y: 100 });
+  });
+});
+
+describe("appliances on a LAN's border", () => {
+  test("sideOnLan names the border the appliance's center is on", () => {
+    expect(sideOnLan(autoRouter("r", centeredOn({ x: 400, y: 100 })), [office])).toBe("right");
+    expect(sideOnLan(autoRouter("r", centeredOn({ x: 100, y: 0 })), [office])).toBe("top");
+    expect(sideOnLan(autoRouter("r", centeredOn({ x: 100, y: 100 })), [office])).toBeNull();
+  });
+
+  test("lanUnder gives the LAN and the side", () => {
+    const servers = lan("servers", {}, { x: 600 });
+    const under = lanUnder(autoRouter("r", centeredOn({ x: 600, y: 100 })), [office, servers]);
+    expect(under?.lan.id).toBe("servers");
+    expect(under?.side).toBe("left");
+  });
+});
+
+describe("lansAround", () => {
+  test("a machine is on every LAN its center lies in", () => {
+    const inner = lan("inner", {}, { x: 100, y: 100, w: 100, h: 100 });
+    const m = machine("m", {}, centeredOn({ x: 150, y: 150 }));
+    expect(lansAround(m, [office, inner, m]).map((l) => l.id)).toEqual(["office", "inner"]);
+  });
+
+  test("a hidden LAN takes no machine by position", () => {
+    const m = machine("m", {}, centeredOn({ x: 150, y: 150 }));
+    expect(lansAround(m, [{ ...office, data: { ...office.data, hidden: true } }, m])).toEqual([]);
+  });
+
+  test("a hidden LAN still takes the appliance on its edge", () => {
+    const hidden = { ...office, data: { ...office.data, hidden: true } };
+    const r = autoRouter("r", centeredOn({ x: 400, y: 100 }));
+    expect(lansAround(r, [hidden, r]).map((l) => l.id)).toEqual(["office"]);
+  });
+});

package/src/lib/tool/geometry.ts

@@ -0,0 +1,109 @@
+import type { XYPosition } from "@xyflow/react";
+import { LAN_H, LAN_W, MACHINE_H, MACHINE_W, isAppliance, isLan, sizeOf, type LabNode, type LanNode, type MachineNode, type Side } from "./model";
+
+/** Where things sit on the canvas: LAN areas, their borders, and what snaps onto them. */
+
+/** How close (canvas units) an appliance's center must come to a LAN's border to snap onto it. */
+const SNAP = 36;
+/** Exactly on the border, give or take rounding. */
+const ON = 0.5;
+
+interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** The area a LAN covers on the canvas. */
+export function lanRect(l: LanNode): Rect {
+  return { x: l.position.x, y: l.position.y, w: l.width ?? LAN_W, h: l.height ?? LAN_H };
+}
+
+/** Whether `p` lies within `r`, borders included, give or take `slack`. */
+export function within(r: Rect, p: XYPosition, slack = 0): boolean {
+  return p.x >= r.x - slack && p.x <= r.x + r.w + slack && p.y >= r.y - slack && p.y <= r.y + r.h + slack;
+}
+
+/** A point on one of a rectangle's borders, and how far `p` is from it. */
+interface BorderPoint {
+  d: number;
+  x: number;
+  y: number;
+}
+
+/** The points of `r`'s borders facing `p` (top, bottom, left, right), where `p` is level with them. */
+function borderPoints(r: Rect, p: XYPosition): BorderPoint[] {
+  const alongX = p.x >= r.x && p.x <= r.x + r.w;
+  const alongY = p.y >= r.y && p.y <= r.y + r.h;
+  const out: BorderPoint[] = [];
+  if (alongX) out.push({ d: Math.abs(p.y - r.y), x: p.x, y: r.y }, { d: Math.abs(p.y - (r.y + r.h)), x: p.x, y: r.y + r.h });
+  if (alongY) out.push({ d: Math.abs(p.x - r.x), x: r.x, y: p.y }, { d: Math.abs(p.x - (r.x + r.w)), x: r.x + r.w, y: p.y });
+  return out;
+}
+
+/**
+ * Where an appliance at `position` should go: centered on the nearest LAN border within reach
+ * (half inside, half outside), or where it is when no border is near.
+ */
+export function snapToLanEdge(position: XYPosition, lans: LanNode[], size: { w: number; h: number } = { w: MACHINE_W, h: MACHINE_H }): XYPosition {
+  const center = { x: position.x + size.w / 2, y: position.y + size.h / 2 };
+  let best: BorderPoint | null = null;
+  for (const l of lans) {
+    for (const c of borderPoints(lanRect(l), center)) if (c.d <= SNAP && (!best || c.d < best.d)) best = c;
+  }
+  return best ? { x: best.x - size.w / 2, y: best.y - size.h / 2 } : position;
+}
+
+/** The side of `r` that `p` lies on, if any (top, bottom, left, right, in that order). */
+function sideOf(r: Rect, p: XYPosition): Side | null {
+  const alongX = p.x >= r.x && p.x <= r.x + r.w;
+  const alongY = p.y >= r.y && p.y <= r.y + r.h;
+  if (alongX && Math.abs(p.y - r.y) < ON) return "top";
+  if (alongX && Math.abs(p.y - (r.y + r.h)) < ON) return "bottom";
+  if (alongY && Math.abs(p.x - r.x) < ON) return "left";
+  if (alongY && Math.abs(p.x - (r.x + r.w)) < ON) return "right";
+  return null;
+}
+
+/** A node's center, by the size it is drawn at (see `sizeOf`). */
+function drawnCenter(m: LabNode): XYPosition {
+  const { w, h } = sizeOf(m);
+  return { x: m.position.x + w / 2, y: m.position.y + h / 2 };
+}
+
+/** The LAN border an appliance sits on, if any: the side of the LAN, so its port faces out. */
+export function sideOnLan(m: MachineNode, lans: LanNode[]): Side | null {
+  const c = drawnCenter(m);
+  for (const l of lans) {
+    const side = sideOf(lanRect(l), c);
+    if (side) return side;
+  }
+  return null;
+}
+
+/** The LAN an appliance sits on the border of, and which border: its inside and outside. */
+export function lanUnder(m: MachineNode, lans: LanNode[]): { lan: LanNode; side: Side } | null {
+  for (const l of lans) {
+    const side = sideOnLan(m, [l]);
+    if (side) return { lan: l, side };
+  }
+  return null;
+}
+
+/** Whether a point is inside a LAN's area (not on its border). */
+export function insideLan(p: XYPosition, l: LanNode): boolean {
+  const r = lanRect(l);
+  return p.x > r.x + ON && p.x < r.x + r.w - ON && p.y > r.y + ON && p.y < r.y + r.h - ON;
+}
+
+/**
+ * The LANs a machine sits in: its center is inside the area (or on its border). A hidden LAN's
+ * area isn't drawn, so it doesn't take machines by position, except routers and firewalls on
+ * its edge; machines join it through its switch's ports or a cable.
+ */
+export function lansAround(m: MachineNode, nodes: LabNode[]): LanNode[] {
+  const c = drawnCenter(m);
+  const onEdge = isAppliance(m) ? lanUnder(m, nodes.filter(isLan))?.lan.id : undefined;
+  return nodes.filter(isLan).filter((l) => (!l.data.hidden || l.id === onEdge) && within(lanRect(l), c));
+}

package/src/lib/tool/gns3-cables.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "vitest";
+import { type Gns3Wiring, gns3Cables } from "./gns3-cables";
+import { autoRouter, lan, machine } from "@/test/lab";
+
+/** A GNS3 LAN where its switch was: 260 by 160 at the origin. */
+const office = lan("office", {}, { w: 260, h: 160 });
+const above = machine("above", {}, { x: 100, y: -300 });
+const left = machine("left", {}, { x: -600, y: 0 });
+const router = autoRouter("router", { x: 600, y: 600 });
+/** The wiring of `links` (GNS3 ids: s1 the switch, the machines by their own ids). */
+const wiring = (links: [string, string][]): Gns3Wiring => ({
+  links,
+  machines: new Map([above, left, router].map((m) => [m.id, m])),
+  lanOf: new Map([["s1", office]]),
+  nodes: [office, above, left, router],
+  lanSize: { w: 260, h: 160 },
+});
+const ends = (links: [string, string][]) => gns3Cables(wiring(links)).map((e) => [e.source, e.sourceHandle, e.target, e.targetHandle]);
+
+describe("gns3Cables", () => {
+  test("cables a machine to its switch's LAN, on the sides that face each other", () => {
+    expect(ends([["above", "s1"], ["s1", "left"]])).toEqual([
+      ["above", "bottom", "office", "top"],
+      ["left", "bottom", "office", "left"],
+    ]);
+  });
+
+  test("cables a router from its single port", () => {
+    expect(ends([["router", "s1"]])[0][1]).toBe("port");
+  });
+
+  test("cables two machines to each other, each end on its next free port", () => {
+    const [c] = gns3Cables(wiring([["above", "left"]]));
+    expect(c).toMatchObject({ source: "above", target: "left", data: { aPort: "eth0", bPort: "eth0" } });
+  });
+
+  test("cables a machine to a LAN once, however many links join them", () => {
+    expect(ends([["above", "s1"], ["s1", "above"]])).toHaveLength(1);
+  });
+
+  test("hides a LAN drawn over a machine it isn't cabled to", () => {
+    const covered = machine("covered", {}, { x: 50, y: 20 });
+    const w = { ...wiring([]), machines: new Map([["covered", covered]]), nodes: [{ ...office, data: { ...office.data } }, covered] };
+    gns3Cables(w);
+    expect(w.nodes[0].type === "lan" && w.nodes[0].data.hidden).toBe(true);
+  });
+});