@isothrum/editor 0.0.0-stage → 0.1.0

package/dist/types/lib/tool/gns3-parts.d.ts

@@ -0,0 +1,25 @@
+import type { NoteShape } from "./model";
+/** Pieces of a GNS3 import that read one thing: an OS from an image name, a note from a drawing. */
+/** The editor's words for what a GNS3 import can't carry over (see the editor's text). */
+export interface Gns3Text {
+    notGns3: string;
+    noTopology: string;
+    cisco: (node: string, kind: string) => string;
+    firewall: (node: string) => string;
+    noEquivalent: (node: string, type: string) => string;
+    noNodes: string;
+}
+export interface G3Drawing {
+    x?: number;
+    y?: number;
+    svg?: string;
+}
+/** The Isoloom OS a VM's image or name suggests (Debian 12 when nothing does). */
+export declare function guessOs(text: string): string;
+/** The text of an SVG drawing, and its shape and size (scaled by `scale`). */
+export declare function drawingNote(d: G3Drawing, scale: number): {
+    text: string;
+    shape: NoteShape;
+    w: number;
+    h: number;
+} | null;

package/dist/types/lib/tool/issues.d.ts

@@ -0,0 +1,12 @@
+import { type LabNode } from "./model";
+/** The editor's words for what the canvas finds wrong (see the editor's text). */
+export interface IssueText {
+    vlanBlocks: (vlan: string, block: string, other: string, sw: string) => string;
+    areaBlock: (lan: string, block: string, switches: string) => string;
+    noName: Record<"machine" | "lan" | "switch", string>;
+    sameName: Record<"machine" | "lan" | "switch", (name: string) => string>;
+    /** A ports field entry Isoloom couldn't take: the machine and the entry. */
+    badPort: (machine: string, entry: string) => string;
+}
+/** What the canvas can tell before the engine runs: names Isoloom would reject or merge, ports it couldn't take. */
+export declare function canvasIssues(nodes: LabNode[], text: IssueText): string[];

package/dist/types/lib/tool/layout.d.ts

@@ -0,0 +1,52 @@
+/**
+ * A lab given as the engine's topology (what an assistant writes through the MCP server), laid
+ * out on the canvas: LANs side by side with their machines in a grid inside, automatic routers
+ * under the LANs they join (cabled to each), the machines on no LAN in a row below, and the
+ * cables between machines. The inverse of `toTopology`, for labs nobody drew.
+ */
+import { type Tc } from "./conditions";
+import { type Service } from "./ports";
+import { type Draft } from "./model";
+type TopologyNode = {
+    kind: {
+        container?: {
+            image: string;
+            idle?: boolean;
+        };
+        vm?: {
+            os: string;
+            provision?: string[];
+        };
+        router?: object;
+    };
+    access?: boolean;
+    services?: Service[];
+    networks?: Record<string, number | null>;
+};
+export interface Topology {
+    name: string;
+    nodes: Record<string, TopologyNode>;
+    networks?: Record<string, {
+        cidr: string;
+        internet?: boolean;
+        tc?: Tc;
+    }>;
+    links?: {
+        a: {
+            node: string;
+            port: string;
+        };
+        b: {
+            node: string;
+            port: string;
+        };
+        tc?: Tc;
+    }[];
+}
+/** A topology laid out: the draft, and each value in the topology the drawing leaves out. */
+export interface LaidOut {
+    draft: Draft;
+    problems: string[];
+}
+export declare function draftFromTopology(topo: Topology): LaidOut;
+export {};

package/dist/types/lib/tool/live.d.ts

@@ -0,0 +1,21 @@
+import { type LabLive, type Status, type SuspendedLink } from "./desktop";
+import type { CableEdge, LabNode } from "./model";
+/**
+ * The running lab as the canvas shows it (desktop app; null: not running, or in a browser).
+ * Machines by name; ports by `machine/network` (up, down, or null: unknown); cables by edge id;
+ * LANs by name, with how many of their ports are up.
+ */
+export type CableStatus = "up" | "cut" | "down" | "unknown";
+export interface LiveView {
+    machines: Partial<Record<string, {
+        status: Status;
+        detail: string;
+    }>>;
+    ports: Partial<Record<string, boolean | null>>;
+    cables: Partial<Record<string, CableStatus>>;
+    lans: Partial<Record<string, {
+        up: number;
+        total: number;
+    }>>;
+}
+export declare function liveViewOf(live: LabLive, links: SuspendedLink[], nodes: LabNode[], edges: CableEdge[]): LiveView;

package/dist/types/lib/tool/logos.d.ts

@@ -0,0 +1,7 @@
+import { type SimpleIcon } from "simple-icons";
+import { type MachineData } from "./model";
+export declare function logoFor(m: Pick<MachineData, "kind" | "image" | "os">): SimpleIcon | null;
+/** The fallback for a container whose image we don't know: Docker's whale. */
+export declare const dockerLogo: SimpleIcon;
+/** Brand colors too dark to read on a dark background (AlmaLinux and others use black). */
+export declare function isDark(hex: string): boolean;

package/dist/types/lib/tool/model.d.ts

@@ -0,0 +1,173 @@
+import type { Edge, Node, XYPosition } from "@xyflow/react";
+/**
+ * The lab as drawn on the canvas: machines, LANs, switches and notes are nodes, cables are edges
+ * between two ports. `toTopology` translates it into the topology JSON the engine reads
+ * (`isothrum_compiler::Topology`), which it compiles to Isoloom's isoloom.yml.
+ */
+export type IconId = "container" | "server" | "router" | "shield" | "monitor" | "laptop";
+/** The Cisco OSes a container node can be (Isoloom's `app.appliance`). */
+export type Appliance = "cisco-iol" | "cisco-iol-l2" | "cisco-vios" | "cisco-vios-l2" | "cisco-csr1000v" | "cisco-c8000v" | "cisco-dynamips";
+/** Each Cisco OS: its usual vrnetlab image (none for Dynamips: Isoloom builds the emulator). */
+export declare const APPLIANCES: {
+    id: Appliance;
+    label: string;
+    image: string;
+    switch?: boolean;
+    kvm?: boolean;
+}[];
+/** The OS's name for the `k`th data interface (from 1), as Isoloom numbers them. */
+export declare function applianceInterface(kind: Appliance, k: number): string;
+export type MachineData = {
+    name: string;
+    /** "router": an automatic router, not a machine (its networks reach each other). */
+    kind: "container" | "vm" | "router";
+    icon: IconId;
+    /** Container image (`kind: container`): Isoloom's `app.image`. */
+    image: string;
+    /** The OS, as Isoloom writes it (`debian@12`, see `OS_CHOICES`) (`kind: vm`): Isoloom's `os`. */
+    os: string;
+    /** Provisioning steps, one per line (`kind: vm`): Isoloom's `app.steps`. */
+    provision: string;
+    /** Service ports, comma-separated, each a port and what it speaks when it isn't TCP (`80, 53/udp`): see `readPorts`. */
+    ports: string;
+    /** The machine the user lands on. */
+    access: boolean;
+    /**
+     * A container with no service of its own (a stock Linux image), kept running idle as a
+     * machine to work from. Unset: guessed from the image (see `idleByDefault`).
+     */
+    idle?: boolean;
+    /** A network OS in its container, wired as its image expects (Cisco IOL, built with vrnetlab). */
+    appliance?: Appliance;
+    /** The appliance's own configuration (IOS commands), added to the one Isoloom generates. */
+    config?: string;
+    /** Addresses fixed by hand: LAN name -> last octet. Others take the next free one. */
+    pins?: Record<string, number>;
+};
+/** An image's name: its last path segment, without the tag, in lowercase. */
+export declare function imageName(image: string): string;
+export declare function idleByDefault(image: string): boolean;
+/** How a cable or a LAN behaves, as a slow or lossy link: one-way delay and its jitter (ms),
+ * loss (%), bandwidth (Mbit/s). Isoloom applies it with `tc netem` (its `tc`). */
+export type LinkConditions = {
+    delay?: number;
+    jitter?: number;
+    loss?: number;
+    rate?: number;
+};
+/** The two ends of a cable: `aPort` on the source machine, `bPort` on the target. */
+export type CableData = {
+    aPort: string;
+    bPort: string;
+    /** How the cable behaves (between two machines; a cable to a LAN takes the LAN's). */
+    tc?: LinkConditions;
+    /** Drawing only, worked out from what the cable is plugged into (never saved). */
+    color?: string;
+};
+/** A LAN (or VLAN) drawn as an area: machines inside it are on it. */
+export type LanData = {
+    name: string;
+    cidr: string;
+    internet: boolean;
+    /** How the LAN behaves (not on a switch's VLAN yet). */
+    tc?: LinkConditions;
+    /** Only its label is drawn: the LAN, its machines and their addresses are unchanged. */
+    hidden?: boolean;
+};
+/** A VLAN on a switch: `vlan<id>`, with its block. VLANs are lab-wide: `vlan10` is the same
+ * network on every switch, and a LAN area named `vlan10` is that VLAN too. */
+type Vlan = {
+    id: number;
+    cidr: string;
+};
+/** A switch port: a VLAN (access), "trunk" (every VLAN of the switch), or nothing. */
+export type PortMode = number | "trunk" | null;
+/**
+ * A switch: access ports, each in a VLAN (or none), and one trunk port that carries every VLAN
+ * of the switch. Not a machine: it is the network fabric, so it never appears in isoloom.yml;
+ * its VLANs do, as networks, and a machine cabled to a port joins the port's VLAN.
+ */
+type SwitchData = {
+    name: string;
+    vlans: Vlan[];
+    ports: PortMode[];
+};
+/** A note on the canvas: text, a box or an ellipse. Drawing only: never in isoloom.yml. */
+export type NoteShape = "text" | "rect" | "ellipse";
+export declare const NOTE_COLORS: readonly ["yellow", "red", "blue", "green", "violet"];
+type NoteData = {
+    text: string;
+    shape: NoteShape;
+    color: (typeof NOTE_COLORS)[number];
+};
+export type MachineNode = Node<MachineData, "machine">;
+export type LanNode = Node<LanData, "lan">;
+export type SwitchNode = Node<SwitchData, "switch">;
+export type NoteNode = Node<NoteData, "note">;
+export type LabNode = MachineNode | LanNode | SwitchNode | NoteNode;
+export type CableEdge = Edge<CableData, "cable">;
+export declare const isMachine: (n: LabNode) => n is MachineNode;
+/**
+ * A router you configure (FRR as a container, or a VM): drawn as a faceplate with interfaces,
+ * like a switch. The automatic router (kind "router") has no interfaces to show.
+ */
+export declare const isRealRouter: (n: LabNode) => n is MachineNode;
+export declare const ROUTER_PORTS = 4;
+export declare const ROUTER_W = 168;
+export declare const ROUTER_H = 74;
+export declare const routerPort: (i: number) => string;
+/** Routers and firewalls: one connection point, and they snap onto a LAN's edge. */
+export declare const isAppliance: (n: LabNode) => n is MachineNode;
+export declare const isLan: (n: LabNode) => n is LanNode;
+export declare const isSwitch: (n: LabNode) => n is SwitchNode;
+export declare const isNote: (n: LabNode) => n is NoteNode;
+/** A node's name as lists show it (a note has none). */
+export declare const nodeName: (n: LabNode) => string;
+export declare const SWITCH_PORTS = 8;
+/** A switch's faceplate on the canvas (see `SwitchNodeView`). */
+export declare const SWITCH_W = 306;
+export declare const SWITCH_H = 74;
+export declare const TRUNK = "trunk";
+/** A machine's box on the canvas (see `MachineNodeView`). */
+export declare const MACHINE_W = 120;
+export declare const MACHINE_H = 116;
+export declare const LAN_W = 420;
+export declare const LAN_H = 300;
+/** How big a node is drawn: what snapping and "is it inside the LAN" go by. */
+export declare function sizeOf(n: LabNode): {
+    w: number;
+    h: number;
+};
+/** A node's center on the canvas, by its drawn size (measured by React Flow, or `fallback`). */
+export declare function centerOf(n: LabNode, fallback?: {
+    w: number;
+    h: number;
+}): XYPosition;
+/**
+ * How a LAN behaves on the canvas, as an Excalidraw frame: it is moved and selected by its label
+ * only, so a click or a drag inside it reaches the canvas (placing a device, drawing a selection
+ * box). Not saved: applied to every LAN when it is created or loaded.
+ */
+export declare const LAN_BEHAVIOR: {
+    readonly dragHandle: ".lan-handle";
+    readonly className: "pointer-events-none";
+};
+/** Which side of a LAN an appliance sits on, when it is snapped onto one. */
+export type Side = "top" | "bottom" | "left" | "right";
+/** The canvas's look (see `DesignContext`): hand-drawn, or crisp for a report. */
+export type Design = "sketch" | "business";
+export declare const DESIGNS: Design[];
+export type Draft = {
+    name: string;
+    nodes: LabNode[];
+    edges: CableEdge[];
+    design?: Design;
+};
+/** Machine names are Isoloom keys: lowercase letters, digits and dashes. */
+export declare function cleanName(name: string): string;
+export declare function uid(prefix: string): string;
+/** The first `<prefix><n>` no machine or LAN uses yet. */
+export declare function freeName(prefix: string, nodes: LabNode[]): string;
+/** Every node unselected: what placing or pasting something does to the rest. */
+export declare function unselected<T extends LabNode | CableEdge>(items: T[]): T[];
+export {};

package/dist/types/lib/tool/os.d.ts

@@ -0,0 +1,20 @@
+import type { Appliance } from "./model";
+/**
+ * The OSes a machine can be, as Isoloom writes them (`<family>@<version>`): exactly Isoloom's list,
+ * which its engine gives (`choices_json`, checked by the tests). A machine of one of them is its
+ * OS, set up by its provisioning steps; each target decides whether it runs as a VM or as a
+ * container built from the OS's image.
+ */
+export declare const OS_CHOICES: string[];
+/** The OS a new VM gets. */
+export declare const DEFAULT_OS = "debian@12";
+/**
+ * An OS as a lab stored before Isoloom's new format named it (its image-table name: `debian-12`,
+ * `almalinux-9`, `kali`, `windows-server-2022`), in today's spelling; any other value as it is.
+ */
+export declare function currentOs(os: string): string;
+/** A machine as a stored lab or device holds it, in today's spelling: its OS and its Cisco OS. */
+export declare function currentMachine<M extends {
+    os: string;
+    appliance?: Appliance;
+}>(m: M): M;

package/dist/types/lib/tool/pins.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Fixing a machine's address on a LAN by hand: same block, a new last number (typed alone, or
+ * as a whole address); clearing it goes back to the next free one. Null: not a valid address.
+ */
+export declare function pinned(pins: Record<string, number> | undefined, net: string, ip: string, typed: string): Record<string, number> | null;

package/dist/types/lib/tool/placement.d.ts

@@ -0,0 +1,21 @@
+import type { NodeChange, XYPosition } from "@xyflow/react";
+import { type LabNode, type LanNode } from "./model";
+import type { Preset } from "./presets";
+/** Placing devices: where they land, and what comes with them. */
+/** A device placed from the palette (no point given): in the middle of the view, staggered so machines added in a row don't stack exactly. */
+export declare function paletteSpot(viewCenter: XYPosition, nodes: LabNode[]): XYPosition;
+/**
+ * The nodes after placing a router or firewall at `position`: near a LAN's border it lands on
+ * it, as when dragged; away from any LAN it comes with its own LAN under it (it is that LAN's
+ * gateway). `dropped`: placed at a point (a click, a drop), centered there like a machine.
+ */
+export declare function placeAppliance(preset: Preset, position: XYPosition, dropped: boolean, nodes: LabNode[], lans: LanNode[]): LabNode[];
+/** The nodes after placing a machine at `position`, selected. */
+export declare function placeMachine(preset: Preset, position: XYPosition, nodes: LabNode[]): LabNode[];
+/**
+ * The nodes after placing a switch at `at`: on a LAN's edge when near one; away from any LAN it
+ * comes with its LAN, its first VLAN, hanging under it.
+ */
+export declare function placeSwitch(at: XYPosition, nodes: LabNode[], lans: LanNode[]): LabNode[];
+/** Routers, firewalls and switches are magnetic: dragged near a LAN's border, they land on it. */
+export declare function snapMoves(changes: NodeChange<LabNode>[], nodes: LabNode[], lans: LanNode[]): NodeChange<LabNode>[];

package/dist/types/lib/tool/ports.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A machine's ports field (`80, 443/https, 53/udp`): each entry a port, 1 to 65535, and what it
+ * speaks when it isn't plain TCP: Isoloom's port `protocol`. An entry Isoloom couldn't take is
+ * kept out of the topology and reported (see `canvasIssues`), never guessed.
+ */
+/** What a port speaks: TCP (the default), UDP, or TCP that speaks HTTP, HTTPS or TLS. */
+export declare const PORT_PROTOCOLS: readonly ["tcp", "udp", "http", "https", "tls"];
+type PortProtocol = (typeof PORT_PROTOCOLS)[number];
+/** A port as the engine's topology takes it (`protocol` left out for TCP). */
+export interface Service {
+    port: number;
+    protocol?: PortProtocol;
+}
+/** The ports field read: its ports, and each entry it couldn't read. */
+export declare function readPorts(text: string): {
+    services: Service[];
+    bad: string[];
+};
+/** Ports as the field writes them: `80, 53/udp`. */
+export declare function portsText(services: readonly Service[]): string;
+export {};

package/dist/types/lib/tool/presets.d.ts

@@ -0,0 +1,21 @@
+import { type MachineData } from "./model";
+/** The devices the toolbar places, and the ones saved from the canvas. */
+export interface Preset {
+    id: string;
+    /** Toolbar groups: network appliances first, then containers, then VMs, then saved devices. */
+    group: "network" | "container" | "vm" | "mine";
+    /** A saved device's name. The built-in devices are named in the editor's text, by their id. */
+    label?: string;
+    /** Prefix of the generated machine name (`router1`, `router2`...). */
+    prefix: string;
+    data: Omit<MachineData, "name">;
+}
+export declare const PRESETS: Preset[];
+/** Keys 1–9 then 0 pick the devices, in toolbar order. */
+export declare function shortcutOf(presetId: string): string | null;
+/** The device a number key picks: 1–9 the first nine, 0 the tenth. */
+export declare function presetForKey(key: string): Preset | undefined;
+/** A device from a machine on the canvas: everything but its name and fixed addresses. */
+export declare function deviceFrom(m: MachineData): Preset;
+/** What changes when a machine is set to run as `kind`: a VM keeps its OS (Debian 12 by default), a container its image (FRR for a router, Alpine otherwise). */
+export declare function runAs(m: MachineData, kind: string): Partial<MachineData> | null;

package/dist/types/lib/tool/projects-api.d.ts

@@ -0,0 +1,37 @@
+import type { Draft } from "./model";
+/**
+ * The site's project store (`/api/projects`), for a signed-in user: their projects, each with
+ * its earlier versions. Errors carry the server's message, or the HTTP status.
+ */
+export interface ProjectSummary {
+    id: string;
+    name: string;
+    updatedAt: string;
+}
+export interface ProjectVersion {
+    id: number;
+    savedAt: string;
+}
+export declare const listProjects: () => Promise<ProjectSummary[]>;
+export declare const getProject: (id: string) => Promise<{
+    id: string;
+    name: string;
+    draft: Draft;
+}>;
+export declare const deleteProject: (id: string) => Promise<unknown>;
+export declare const listVersions: (id: string) => Promise<ProjectVersion[]>;
+export declare const getVersion: (id: string, version: number) => Promise<{
+    draft: Draft;
+}>;
+/** Saves the lab as a new project (POST), or as the next version of `id` (PUT). */
+export declare function saveProject(id: string | null, body: {
+    name?: string;
+    draft: Draft;
+    isoloomYml: string | null;
+}): Promise<ProjectSummary>;
+/** A project by the id in a link (#project=…), or null when it can't be read. */
+export declare function projectFromLink(id: string): Promise<{
+    id: string;
+    name: string;
+    draft: unknown;
+} | null>;

package/dist/types/lib/tool/router-ports.d.ts

@@ -0,0 +1,22 @@
+import { type CableEdge, type LabNode, type LanNode } from "./model";
+/**
+ * A real router's interfaces: each port's color (striped when it is a trunk), and the list of
+ * interfaces with the network and address on each; a trunk port has one sub-interface per VLAN
+ * (eth0.10, eth0.20), as router-on-a-stick.
+ */
+export interface RouterPorts {
+    colors: Partial<Record<string, string>>;
+    interfaces: {
+        name: string;
+        network: string;
+        ip?: string;
+        color: string;
+    }[];
+}
+/** Each machine's addresses (from the engine), by machine name: [network, IPv4][]. */
+export type Addresses = Partial<Record<string, [string, string][]>>;
+/**
+ * Each real router's interfaces, by node id: the network on each port, its address there, and a
+ * color. On a LAN's edge, the LAN is on eth0 (or the first port no cable uses).
+ */
+export declare function routerPortsOf(nodes: LabNode[], edges: CableEdge[], lans: LanNode[], addresses: Addresses): Record<string, RouterPorts>;

package/dist/types/lib/tool/selection.d.ts

@@ -0,0 +1,19 @@
+import { type IssueText } from "./issues";
+import type { Plan } from "./engine";
+import { type CableEdge, type LabNode } from "./model";
+/** What is selected: one thing opens its window; several open the "selection" window instead. */
+export declare function selectionOf(nodes: LabNode[], edges: CableEdge[]): {
+    selectedNodes: LabNode[];
+    selectedEdges: CableEdge[];
+    count: number;
+    machine: import("./model").MachineNode | undefined;
+    lan: import("./model").LanNode | undefined;
+    edge: CableEdge | undefined;
+};
+/**
+ * What to fix before the lab runs: the canvas's own findings, then the engine's. An empty canvas
+ * isn't a lab with problems yet: nothing until there is something to check.
+ */
+export declare function labIssues(nodes: LabNode[], plan: Plan | null, text: IssueText): string[];
+/** A node's name by its id, as the windows show it ("?" for one that is gone). */
+export declare function nameById(nodes: LabNode[], id: string): string;

package/dist/types/lib/tool/storage.d.ts

@@ -0,0 +1,25 @@
+import type { Design, Draft } from "./model";
+import type { Preset } from "./presets";
+/** The last lab drawn in this browser; none (a blank canvas) when what is kept hasn't a lab's shape. */
+export declare function loadDraft(): Draft | null;
+/** Keeps the lab, without its UI state (selection is not part of the lab). */
+export declare function saveDraft(draft: Draft): void;
+/** Devices saved from the canvas (GNS3's appliances), placed from the toolbar like the built-in ones. */
+export declare function loadDevices(): Preset[];
+export declare function saveDevices(list: Preset[]): void;
+/** The canvas's look picked in this browser, if any. */
+export declare function loadDesign(): Design | null;
+export declare function saveDesign(design: Design): void;
+/** The kind each toolbar block places, by block id, as picked last. */
+export declare function loadBlockChoices(): Record<string, string> | null;
+export declare function saveBlockChoices(choices: Record<string, string>): void;
+/** Whether `lab` starts when the app opens on it. */
+export declare function autoStarts(lab: string): boolean;
+export declare function setAutoStarts(lab: string, on: boolean): void;
+/** The saved project the editor is attached to. */
+export interface ProjectRef {
+    id: string;
+    name: string;
+}
+export declare function loadProject(): ProjectRef | null;
+export declare function saveProject(p: ProjectRef | null): void;

package/dist/types/lib/tool/switch-edit.d.ts

@@ -0,0 +1,17 @@
+import { type SwitchNode } from "./model";
+/** Editing a switch on the canvas: each change returns the switch's fields that change. */
+type SwitchData = SwitchNode["data"];
+/** A click steps a port through each VLAN, then trunk, then unassigned. */
+export declare function cyclePort(data: SwitchData, i: number): Pick<SwitchData, "ports">;
+/** A VLAN's number or block changed; a new number moves its ports along. */
+export declare function changeVlan(data: SwitchData, old: number, patch: {
+    id?: number;
+    cidr?: string;
+}): Pick<SwitchData, "vlans" | "ports">;
+/** A VLAN removed: its ports are left unassigned. */
+export declare function removeVlan(data: SwitchData, vid: number): Pick<SwitchData, "vlans" | "ports">;
+/** A new VLAN, numbered 10 after the highest, with its own block. */
+export declare function addVlan(data: SwitchData): Pick<SwitchData, "vlans">;
+/** A typed VLAN number, if it can be one: 1–4094, and not one the switch has already. */
+export declare function vlanNumber(data: SwitchData, typed: string): number | null;
+export {};

package/dist/types/lib/tool/text/de.d.ts

@@ -0,0 +1,2 @@
+import type { EditorText } from "./en";
+export declare const de: EditorText;