@takodotid/circuit 0.19.0 → 0.20.0

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   isCidr,
   isGlobal,
   network
-} from "./chunks/index-dczpxzzm.js";
+} from "./chunks/index-xm9nma2t.js";
 import"./chunks/index-fq57hya4.js";
 
 // src/core/define.ts

package/dist/presets/index.js

@@ -1,6 +1,6 @@
 import {
   contains
-} from "../chunks/index-dczpxzzm.js";
+} from "../chunks/index-xm9nma2t.js";
 import"../chunks/index-fq57hya4.js";
 
 // src/presets/index.ts

package/dist/types/adapters/devices/derive.d.ts

@@ -3,3 +3,5 @@ import type { Device } from "../../schema";
 export declare function lagIds(device: Device): Map<string, number>;
 /** The IPv4 networks of a port's or an interface's addresses. */
 export declare function ipv4Networks(device: Device, iface: string): string[];
+/** Fields neither switch platform, VRP nor Raisecom ROS, expresses: a service's own sources or port, a user's description or keys, the IP stack's host settings, a point-to-point address, and offload per interface. */
+export declare function switchUnsupported(device: Device): string[];

package/dist/types/core/across.d.ts

@@ -0,0 +1,4 @@
+import type { Device } from "../schema";
+import type { Finding } from "./define";
+/** Every rule across devices. */
+export declare function checkAcross(devices: readonly Device[]): Finding[];

package/dist/types/core/addr.d.ts

@@ -14,6 +14,16 @@ export declare function isCidr(text: string): boolean;
 export declare function network(cidr: string): string;
 /** Is the address or prefix `inner` inside `outer`? */
 export declare function contains(outer: string, inner: string): boolean;
+/** A number back to the address it stands for. */
+export declare const formatAddress: (value: bigint, family: Family) => string;
+/** The first and last address of a prefix, as numbers. */
+export declare function rangeOf(cidr: string): {
+    first: bigint;
+    last: bigint;
+    family: Family;
+};
+/** The fewest prefixes that cover every address from `first` to `last` and nothing else. */
+export declare function prefixesBetween(first: bigint, last: bigint, family: Family): string[];
 /** `/25` to `255.255.255.128`. */
 export declare const netmask: (length: number) => string;
 /** `/24` to `0.0.0.255`, the inverted mask some ACLs take. */

package/dist/types/core/addresses.d.ts

@@ -0,0 +1,46 @@
+import type { Device } from "../schema";
+/** One address or range in a segment, and what holds it. */
+export type Use = {
+    /** An address, or `first-last` for a range. */
+    address: string;
+    what: string;
+};
+/** A prefix our devices have addresses in. */
+export type Segment = {
+    prefix: string;
+    uses: Use[];
+    /** How many addresses no one uses, as a number written out, since an IPv6 count does not fit a JavaScript number. */
+    free: string;
+    /** The lowest free address, when there is one. */
+    next?: string;
+};
+/** A prefix in use without being a segment: a loopback's address, or a block routed elsewhere. */
+export type Block = {
+    prefix: string;
+    what: string;
+};
+/** Space the network owns: a prefix it originates in BGP, or one asked for. Everything in use inside it, and what is free. */
+export type Space = {
+    prefix: string;
+    /** Why it is listed, such as `originated by edge-01`. */
+    owner: string;
+    segments: Segment[];
+    blocks: Block[];
+    /** The fewest prefixes that cover what nothing uses. */
+    free: string[];
+};
+export type AddressReport = {
+    spaces: Space[];
+    /** What is in use outside every space. Left out when a prefix is asked for. */
+    elsewhere: {
+        segments: Segment[];
+        blocks: Block[];
+    };
+};
+/** Every address in use, by segment, under the space the network owns. With `within`, only what falls inside that prefix, as the one space. */
+export declare function addressesOf(devices: readonly Device[], within?: string): AddressReport;
+/** Free prefixes of one length inside the free space, up to `limit`, and how many there are in all. */
+export declare function freeOfLength(free: readonly string[], length: number, limit: number): {
+    prefixes: string[];
+    total: bigint;
+};

package/dist/types/core/files.d.ts

@@ -0,0 +1,6 @@
+/** Every TypeScript file of the project, relative to its root, in name order. */
+export declare function projectSources(root: string, directory?: string): string[];
+/** Whether a file's text declares the device: it calls defineDevice and gives it the name, written out whole. */
+export declare function declaresDevice(text: string, name: string): boolean;
+/** The project files that declare the device, relative to the root. */
+export declare function deviceFiles(root: string, name: string, sources?: string[]): string[];

package/dist/types/core/graph.d.ts

@@ -1,4 +1,5 @@
-import type { Device } from "../schema";
+import type { Device, Routed } from "../schema";
+import type { Finding } from "./define";
 /** One view of the network. Every edge belongs to one. */
 export type Layer = "l1" | "l2" | "l3" | "bgp" | "ospf" | "tunnels";
 export declare const LAYERS: readonly Layer[];
@@ -37,7 +38,36 @@ export type Graph = {
     nodes: GraphNode[];
     edges: GraphEdge[];
 };
+/** How a device compares with its last snapshot, found offline as `diff` finds it. */
+export type Drift = {
+    status: "matches" | "differs" | "no snapshot" | "cannot plan";
+    /** The plan `diff` would show, when it differs. */
+    lines: string[];
+};
+/** The graph with what `validate` found and how each device drawn compares with its snapshot. */
+export type Annotated = Graph & {
+    findings: Finding[];
+    /** By device name. */
+    drift: Record<string, Drift>;
+};
+/** An address one of the devices holds on a port or interface. */
+export type Holder = {
+    device: Device;
+    /** The port or interface. */
+    name: string;
+    /** With its length. */
+    address: string;
+    /** The far end of a point-to-point address. */
+    peer?: string;
+    vrrp: NonNullable<Routed<string>["vrrp"]>;
+};
 export declare const deviceId: (name: string) => string;
+/** An address as a key, so two spellings of one address compare equal. Undefined when it is not an address. */
+export declare function keyOf(address: string | undefined): string | undefined;
+/** Ports, then interfaces, that can hold an address. */
+export declare function routedOf(device: Device): [string, Routed<string>][];
+/** Every valid address the devices hold. An invalid one is left for `validate` to report. */
+export declare function holdersOf(devices: readonly Device[]): Holder[];
 /** The network as a graph. It reads the config only, never a device, and works on a config that does not validate. */
 export declare function graphOf(devices: readonly Device[]): Graph;
 /** Only the edges on these layers, and among those only the ones that touch these devices when any are named. Every device named stays. */

package/dist/types/core/schema-docs.d.ts

@@ -0,0 +1,16 @@
+/** The schema files in reading order, with the title each gets. */
+export declare const SCHEMA_FILES: readonly [readonly ["device.ts", "Device"], readonly ["interfaces.ts", "Ports and interfaces"], readonly ["routing.ts", "Routing"], readonly ["policy.ts", "Route policies"], readonly ["firewall.ts", "Firewall and ACLs"], readonly ["system.ts", "System and management"], readonly ["common.ts", "Common values"]];
+export type Field = {
+    path: string;
+    type: string;
+    description: string;
+};
+export type TypeDoc = {
+    name: string;
+    description: string;
+    definition?: string;
+    includes?: string[];
+    fields: Field[];
+};
+/** Every type in each schema file, in the order given. Every file is read first, so a type is known to take parameters wherever it is used. */
+export declare function schemaTypes(sources: readonly string[]): TypeDoc[][];

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.19.0",
+    "version": "0.20.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/adapters/devices/derive.ts

@@ -25,3 +25,35 @@ export function ipv4Networks(device: Device, iface: string): string[] {
 
     return addresses.filter((address) => familyOf(address) === "ipv4").map((address) => network(address));
 }
+
+/** Services the switch platforms run. Each takes its sources from `management.allow`, on the protocol's own port. */
+const SWITCH_SERVICES = ["ssh", "telnet", "snmp"] as const;
+
+/** Fields neither switch platform, VRP nor Raisecom ROS, expresses: a service's own sources or port, a user's description or keys, the IP stack's host settings, a point-to-point address, and offload per interface. */
+export function switchUnsupported(device: Device): string[] {
+    const found: string[] = [];
+
+    for (const service of SWITCH_SERVICES) {
+        const settings = device.management?.[service];
+        if (settings?.allow) found.push(`management.${service}.allow, every service takes management.allow`);
+        if (settings?.port) found.push(`management.${service}.port`);
+    }
+
+    for (const [name, user] of Object.entries(device.users ?? {})) {
+        if (user.description) found.push(`users.${name}.description`);
+        if (user.ssh_keys?.length) found.push(`users.${name}.ssh_keys`);
+    }
+
+    if (device.system?.ip) found.push("system.ip");
+
+    for (const [name, port] of Object.entries(device.ports ?? {})) {
+        if (port?.hardware_offload !== undefined) found.push(`ports.${name}.hardware_offload`);
+    }
+
+    for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
+        if (iface.addresses?.some((entry) => typeof entry !== "string")) found.push(`interfaces.${name}.addresses with a peer`);
+        if (iface.hardware_offload !== undefined) found.push(`interfaces.${name}.hardware_offload`);
+    }
+
+    return found;
+}

package/src/adapters/devices/raisecom-ros/index.ts

@@ -9,7 +9,7 @@ import { offset } from "../../../core/time";
 import type { Device, Port, SnmpUser, Switched, Vrrp } from "../../../schema";
 import { connect, readUntil, send, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
-import { ipv4Networks, lagIds } from "../derive";
+import { ipv4Networks, lagIds, switchUnsupported } from "../derive";
 import { compare, type Dialect, entries, type Group, scrub, steps, vlanListChange } from "../lines";
 import type { DeviceAdapter, Plan, Step } from "../types";
 
@@ -387,7 +387,14 @@ export function unsupported(device: Device): string[] {
             continue;
         }
 
-        if (iface.vrf) found.push(`interfaces.${name}.vrf`);
+        for (const field of ["vrf", "description", "mtu", "ipv6_ra"] as const) {
+            if (iface[field] !== undefined) found.push(`interfaces.${name}.${field}`);
+        }
+
+        for (const entry of iface.addresses ?? []) {
+            const address = typeof entry === "string" ? entry : entry.address;
+            if (familyOf(address) === "ipv6") found.push(`interfaces.${name}.addresses ${address}, only IPv4 here`);
+        }
 
         for (const group of iface.vrrp ?? []) {
             if (familyOf(group.address) === "ipv6") found.push(`interfaces.${name}.vrrp for IPv6`);
@@ -412,7 +419,15 @@ export function unsupported(device: Device): string[] {
     }
 
     for (const route of routing?.static ?? []) {
-        if (!route.via || route.vrf) found.push(`routing.static ${route.prefix}, only an IPv4 next hop in the default table`);
+        if (!route.via || route.vrf || familyOf(route.prefix) === "ipv6") {
+            found.push(`routing.static ${route.prefix}, only an IPv4 next hop in the default table`);
+        }
+
+        if (route.description || route.distance) found.push(`routing.static ${route.prefix} description and distance`);
+    }
+
+    for (const [name, vlan] of Object.entries(device.vlans ?? {})) {
+        if (vlan.description) found.push(`vlans.${name}.description`);
     }
 
     const UNSUPPORTED_SECTIONS = [
@@ -443,6 +458,9 @@ export function unsupported(device: Device): string[] {
             found.push(`management.snmp.users.${name}.auth ${user.auth}, the platform authenticates with SHA1 or MD5`);
     }
 
+    if (management.snmp?.contact || management.snmp?.location) found.push("management.snmp.contact and location");
+    if (management.ssh?.weak_crypto) found.push("management.ssh.weak_crypto");
+
     if (device.lldp && device.lldp !== true) found.push("lldp.interfaces, LLDP is per device");
     if (device.stp?.mode && device.stp.mode !== "mstp") found.push("stp.mode other than mstp");
 
@@ -456,6 +474,8 @@ export function unsupported(device: Device): string[] {
         found.push("system.dns, logging, release_channel, banner and ntp.serve");
     }
 
+    found.push(...switchUnsupported(device));
+
     return found;
 }
 

package/src/adapters/devices/routeros/index.ts

@@ -99,6 +99,14 @@ export function unsupported(device: Device): string[] {
         }
     }
 
+    for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
+        if (iface.type !== "lag") continue;
+
+        for (const field of ["storm_control", "stp"] as const) {
+            if (iface[field] !== undefined) found.push(`interfaces.${name}.${field}, on a LAG`);
+        }
+    }
+
     const bgp = device.routing?.bgp;
 
     for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
@@ -113,6 +121,8 @@ export function unsupported(device: Device): string[] {
     if (management?.console) found.push("management.console, the console uses the device's users");
     if (management?.privilege_password) found.push("management.privilege_password, the platform has no privileged mode");
 
+    if (management?.snmp?.port) found.push("management.snmp.port");
+
     if (management?.ssh?.auth_timeout || management?.ssh?.auth_retries) {
         found.push("management.ssh.auth_timeout and auth_retries");
     }

package/src/adapters/devices/vrp/index.ts

@@ -9,7 +9,7 @@ import { offset } from "../../../core/time";
 import type { Device, Interface, Port, Vrrp } from "../../../schema";
 import { connect, readUntil, send, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
-import { ipv4Networks, lagIds } from "../derive";
+import { ipv4Networks, lagIds, switchUnsupported } from "../derive";
 import { compare, type Dialect, scrub, steps, vlanListChange } from "../lines";
 import type { DeviceAdapter, Plan } from "../types";
 
@@ -608,9 +608,14 @@ export function unsupported(device: Device): string[] {
     for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
         if (iface.type !== "vlan" && iface.type !== "lag") found.push(`interfaces.${name}, a ${iface.type}`);
         if (iface.type === "lag" && iface.addresses?.length) found.push(`interfaces.${name}.addresses, LAGs are switched`);
+        if (iface.mtu !== undefined) found.push(`interfaces.${name}.mtu`);
         for (const group of iface.vrrp ?? []) if (familyOf(group.address) === "ipv6") found.push(`interfaces.${name}.vrrp for IPv6`);
     }
 
+    for (const [name, vrf] of Object.entries(device.vrfs ?? {})) {
+        if (vrf.description) found.push(`vrfs.${name}.description`);
+    }
+
     const routing = device.routing;
     if (routing?.bgp) found.push("routing.bgp");
     if (routing?.rpki) found.push("routing.rpki");
@@ -644,6 +649,10 @@ export function unsupported(device: Device): string[] {
         found.push("system.dns, logging, release_channel and banner");
     }
 
+    if (system.transceiver_monitoring !== undefined) found.push("system.transceiver_monitoring");
+
+    found.push(...switchUnsupported(device));
+
     const flow = device.flow_export;
     if (flow && flow.protocol !== "sflow") found.push(`flow_export.protocol ${flow.protocol}, the platform exports sFlow`);
     const sampling = flow?.protocol === "sflow" ? flow.sampling : undefined;

package/src/cli/graph.ts

@@ -1,20 +1,6 @@
 // What `circuit graph` prints: the graph of the network with what `validate` found and how each device compares with its last snapshot, as Mermaid, DOT or JSON.
 
-import type { Finding } from "../core/define";
-import { deviceId, type Graph, type GraphNode } from "../core/graph";
-
-/** How a device compares with its last snapshot, found offline as `diff` finds it. */
-export type Drift = {
-    status: "matches" | "differs" | "no snapshot" | "cannot plan";
-    /** The plan `diff` would show, when it differs. */
-    lines: string[];
-};
-
-export type Annotated = Graph & {
-    findings: Finding[];
-    /** By device name. */
-    drift: Record<string, Drift>;
-};
+import { type Annotated, deviceId, type GraphNode } from "../core/graph";
 
 /** `error` when validate found an error on the device, `warning` for a warning or a difference from its snapshot. */
 export function markOf(graph: Annotated, node: GraphNode): "error" | "warning" | undefined {

package/src/cli/index.ts

@@ -3,20 +3,24 @@
 
 import { createPrivateKey, createPublicKey } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { adapters } from "../adapters/devices";
 import type { ApplyOptions, DeviceAdapter, Plan } from "../adapters/devices/types";
 import { registries } from "../adapters/registries";
 import { planLibreNms, sendLibreNms } from "../adapters/registries/librenms";
 import { planPeeringDb, sendPeeringDb } from "../adapters/registries/peeringdb";
 import { prometheusTargets, snmpExporterAuths } from "../adapters/registries/prometheus";
-import { network as prefixOf } from "../core/addr";
+import { isCidr, network as prefixOf } from "../core/addr";
+import { addressesOf, freeOfLength, type Segment } from "../core/addresses";
 import type { Network } from "../core/define";
-import { graphOf, LAYERS, only, type Layer } from "../core/graph";
+import { type Annotated, type Drift, graphOf, LAYERS, only, type Layer } from "../core/graph";
 import { isSecret, referenceOf, resolve as reveal, sourceOf, useRoot } from "../core/secrets";
 import { validate } from "../core/validate";
 import type { Device } from "../schema";
-import { type Annotated, dot, type Drift, mermaid } from "./graph";
+import { dot, mermaid } from "./graph";
+import { applyRename, planRename, type RenamePlan } from "./rename";
+import { deviceFiles, projectSources } from "../core/files";
+import { studioData } from "../studio/data";
 
 const HELP = `usage: circuit <command> [device...] [options]
 
@@ -37,12 +41,22 @@ const HELP = `usage: circuit <command> [device...] [options]
   prometheus            every device with SNMP, as Prometheus targets for snmp_exporter
                           --auths        snmp_exporter's auths for them instead, with secrets as \${NAME}
   secrets               every secret the config uses, and whether each can be read
+  rename <device> <new-name>
+                        give a device a new name in every file that names it, with --confirm
+                          --file         also rename the file that declares it, to <new-name>.ts
+  addresses [prefix]    every address the config uses, by prefix, and what is still free
+                          --length=N     free prefixes of this length, instead of the fewest that cover the free space
+                          --format=json  as JSON
   graph [device...]     the network as a graph, from the config alone, without contacting a device
                           --layer=l1     l1, l2, l3, bgp, ospf or tunnels, several with commas, or all
                           --format=mermaid  mermaid, dot or json
-  studio                the graph in the browser, drawn again whenever the config changes
-                          --port=4600    the port it listens on, on this machine only
+  studio                Circuit Studio: the network in the browser, drawn again whenever the config changes
+                          --port=4600    the port it listens on
                           --no-open      do not open the browser
+                          --host=0.0.0.0 listen on a server's address instead, with --allow-host
+                          --allow-host=studio.example.com
+                                         the names it is reached by, several with commas
+                          --json         print what Studio shows, as JSON, instead
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
 
@@ -426,6 +440,20 @@ function driftOf(device: Device): Drift {
     }
 }
 
+/** The graph on these layers, around these devices when any are named, with what validate found and how each device drawn compares with its snapshot. */
+function annotatedGraph(layers: readonly Layer[], deviceNames: readonly string[]): Annotated {
+    const graph = only(graphOf(network.devices), layers, deviceNames);
+    const shown = new Set(graph.nodes.map((node) => node.label));
+
+    return {
+        ...graph,
+        findings: validate(network).filter((finding) => !finding.device || shown.has(finding.device)),
+        drift: Object.fromEntries(
+            network.devices.filter((device) => shown.has(device.name)).map((device) => [device.name, driftOf(device)])
+        ),
+    };
+}
+
 function graphCommand(): void {
     const requested = (flagValue("layer") ?? "l1").split(",");
     const layers = requested.includes("all") ? [...LAYERS] : (requested as Layer[]);
@@ -435,18 +463,7 @@ function graphCommand(): void {
 
     const format = flagValue("format") ?? "mermaid";
     const devices = selected(true);
-
-    const graph = only(graphOf(network.devices), layers, names.length ? devices.map((device) => device.name) : []);
-    const shown = new Set(graph.nodes.map((node) => node.label));
-
-    // Each device drawn is compared with its snapshot; findings are kept for those, and for the network as a whole.
-    const annotated: Annotated = {
-        ...graph,
-        findings: validate(network).filter((finding) => !finding.device || shown.has(finding.device)),
-        drift: Object.fromEntries(
-            network.devices.filter((device) => shown.has(device.name)).map((device) => [device.name, driftOf(device)])
-        ),
-    };
+    const annotated = annotatedGraph(layers, names.length ? devices.map((device) => device.name) : []);
 
     if (format === "mermaid") process.stdout.write(mermaid(annotated));
     else if (format === "dot") process.stdout.write(dot(annotated));
@@ -454,12 +471,127 @@ function graphCommand(): void {
     else fail(`no format ${format}; known: mermaid, dot, json`);
 }
 
+/** One segment and what uses each address in it. */
+function printSegment(segment: Segment, indent: string): void {
+    const next = segment.next ? `, next ${segment.next}` : "";
+    console.log(`${indent}${segment.prefix}, ${segment.free} free${next}`);
+
+    const width = Math.max(...segment.uses.map((use) => use.address.length)) + 2;
+    for (const use of segment.uses) console.log(`${indent}    ${use.address.padEnd(width)}${use.what}`);
+}
+
+function addressesCommand(): void {
+    const [within] = names;
+    if (within && !isCidr(within)) fail(`${within} is not a prefix, such as 10.0.0.0/16`);
+
+    const lengthText = flagValue("length");
+    const length = lengthText === undefined ? undefined : Number(lengthText);
+    if (length !== undefined && !(Number.isInteger(length) && length >= 0 && length <= 128))
+        fail("--length takes a prefix length, such as 24");
+
+    const report = addressesOf(network.devices, within);
+
+    if (flagValue("format") === "json") {
+        console.log(JSON.stringify(report, null, 4));
+        return;
+    }
+
+    for (const space of report.spaces) {
+        console.log(`${space.prefix}, ${space.owner}`);
+        for (const segment of space.segments) printSegment(segment, "  ");
+        for (const block of space.blocks) console.log(`  ${block.prefix}  ${block.what}`);
+
+        if (length === undefined) {
+            console.log(`  free: ${space.free.join(", ") || "none"}`);
+        } else {
+            const { prefixes, total } = freeOfLength(space.free, length, 16);
+            const more = total > BigInt(prefixes.length) ? `, and ${total - BigInt(prefixes.length)} more` : "";
+            console.log(`  free /${length}: ${prefixes.join(", ") || "none"}${more}`);
+        }
+
+        console.log("");
+    }
+
+    const { segments, blocks } = report.elsewhere;
+    if (segments.length || blocks.length) {
+        console.log("Outside the space the network originates");
+        for (const segment of segments) printSegment(segment, "  ");
+        for (const block of blocks) console.log(`  ${block.prefix}  ${block.what}`);
+    }
+
+    if (!report.spaces.length && !segments.length && !blocks.length) console.log("The config holds no addresses.");
+}
+
+function renameCommand(): void {
+    const [from, to] = names;
+    if (!from || !to) fail("usage: circuit rename <device> <new-name> [--file] [--confirm]");
+
+    const device = network.devices.find((candidate) => candidate.name === from);
+    if (!device) fail(`no device ${from}; known: ${network.devices.map((candidate) => candidate.name).join(", ")}`);
+    if (network.devices.some((candidate) => candidate.name === to)) fail(`${to} is already a device`);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(to)) fail(`${to} is not a hostname: letters, digits, dots, dashes and underscores`);
+
+    const snapshot = statePath(device);
+    const snapshots = existsSync(snapshot) ? [relative(root, snapshot)] : [];
+
+    let plan: RenamePlan;
+    try {
+        plan = planRename(root, from, to, { file: flags.includes("--file"), snapshots });
+    } catch (error) {
+        fail((error as Error).message);
+    }
+
+    for (const change of plan.changes) {
+        console.log(`${change.file}:${change.line}`);
+        console.log(`  - ${change.before.trim()}`);
+        console.log(`  + ${change.after.trim()}`);
+    }
+
+    for (const move of plan.moves) console.log(`move ${move.from} to ${move.to}`);
+
+    if (plan.mentions.length) {
+        console.log(`\nStill naming ${from}, left as they are: change them by hand if they mean the device.`);
+        for (const mention of plan.mentions) console.log(`  ${mention.file}:${mention.line}  ${mention.text.slice(0, 160)}`);
+    }
+
+    if (!confirmed) {
+        console.log("\nNothing written. Re-run with --confirm.");
+        return;
+    }
+
+    applyRename(root, plan);
+    console.log(`\nRenamed. Run circuit validate, then circuit apply ${to}: the device keeps its old hostname until then.`);
+}
+
 async function studioCommand(): Promise<void> {
+    if (flags.includes("--json")) {
+        const sources = projectSources(root);
+        const data = studioData(network.devices, annotatedGraph(LAYERS, []), {
+            render: (device) => adapterOf(device).render(device),
+            snapshot: (device) => (existsSync(statePath(device)) ? readFileSync(statePath(device), "utf8") : undefined),
+            files: (device) => ({
+                // Written with forward slashes on every system, as git and the page take them.
+                source: deviceFiles(root, device.name, sources)[0]?.split(sep).join("/"),
+                snapshot: existsSync(statePath(device)) ? relative(root, statePath(device)).split(sep).join("/") : undefined,
+            }),
+        });
+        console.log(JSON.stringify(data));
+        return;
+    }
+
     const port = Number(flagValue("port") ?? 4600);
     if (!Number.isInteger(port) || port < 1 || port > 65535) fail("--port takes a number from 1 to 65535");
 
-    const { studio } = await import("./studio");
-    await studio({ configPath, root, port, open: !flags.includes("--no-open") });
+    const { isLoopback, studio } = await import("../studio/server");
+    const host = flagValue("host") ?? "127.0.0.1";
+    const allowHosts = (flagValue("allow-host") ?? "").split(",").filter(Boolean);
+
+    // Off this machine, Studio must be told the names it is reached by: every other name is refused.
+    if (!isLoopback(host) && !allowHosts.length) {
+        fail(`Studio on ${host} needs --allow-host=<name>, the name people reach it by, such as studio.example.com`);
+    }
+
+    await studio({ configPath, root, port, open: !flags.includes("--no-open"), host, allowHosts });
 }
 
 const commands: Record<string, () => void | Promise<void>> = {
@@ -475,6 +607,8 @@ const commands: Record<string, () => void | Promise<void>> = {
     librenms: librenmsCommand,
     prometheus: prometheusCommand,
     secrets: secretsCommand,
+    rename: renameCommand,
+    addresses: addressesCommand,
     graph: graphCommand,
     studio: studioCommand,
 };