@takodotid/circuit 0.18.5 → 0.20.0

package/src/cli/index.ts

@@ -3,18 +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 { 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 { 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]
 
@@ -35,6 +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                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`;
 
@@ -395,6 +417,183 @@ ${references.length} secret(s), ${missing} missing.`);
     process.exit(missing ? 1 : 0);
 }
 
+/** The value of `--name=value`, or undefined when it is not given. */
+const flagValue = (name: string) => flags.find((flag) => flag.startsWith(`--${name}=`))?.slice(name.length + 3);
+
+/** How a device compares with its last snapshot, offline, as `diff` plans it. */
+function driftOf(device: Device): Drift {
+    const path = statePath(device);
+    if (!existsSync(path)) return { status: "no snapshot", lines: [] };
+
+    try {
+        const adapter = adapterOf(device);
+        const plan = adapter.plan(adapter.render(device), readFileSync(path, "utf8"), options);
+
+        const lines = [
+            ...plan.steps.flatMap((step) => [step.title, ...step.show.map((line) => `  ${line}`)]),
+            ...plan.problems.map((problem) => `PROBLEM ${problem}`),
+        ];
+
+        return { status: lines.length ? "differs" : "matches", lines };
+    } catch (error) {
+        return { status: "cannot plan", lines: [(error as Error).message] };
+    }
+}
+
+/** 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[]);
+
+    const unknown = layers.filter((layer) => !LAYERS.includes(layer));
+    if (unknown.length) fail(`no layer ${unknown.join(", ")}; known: ${LAYERS.join(", ")}, all`);
+
+    const format = flagValue("format") ?? "mermaid";
+    const devices = selected(true);
+    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));
+    else if (format === "json") console.log(JSON.stringify(annotated, null, 4));
+    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 { 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>> = {
     validate: validateCommand,
     build: buildCommand,
@@ -408,6 +607,10 @@ const commands: Record<string, () => void | Promise<void>> = {
     librenms: librenmsCommand,
     prometheus: prometheusCommand,
     secrets: secretsCommand,
+    rename: renameCommand,
+    addresses: addressesCommand,
+    graph: graphCommand,
+    studio: studioCommand,
 };
 
 const run = commands[command];

package/src/cli/rename.ts

@@ -0,0 +1,129 @@
+// `circuit rename`: a device's new name everywhere the project's files name it, its snapshot renamed to match, and with `--file` its file too. It plans first and writes only with --confirm.
+
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { declaresDevice, projectSources } from "../core/files";
+
+/** One line that changes. */
+export type LineChange = { file: string; line: number; before: string; after: string };
+
+export type RenamePlan = {
+    changes: LineChange[];
+    /** Files that move, from and to, relative to the project. */
+    moves: { from: string; to: string }[];
+    /** Lines that still name the device inside a longer text, such as a description or a comment, which the rename leaves alone. */
+    mentions: { file: string; line: number; text: string }[];
+};
+
+const escape = (text: string) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/**
+ * Plan renaming a device from `from` to `to` in the project at `root`.
+ *
+ * A string that is exactly the old name becomes the new name: `name: "edge-01"`, `link: { device: "edge-01", ... }`, a check's list of routers, and a key such as a tenant's ports by device, which would otherwise no longer be found. A BGP neighbor named after the device is renamed too, which renames its session on the device: `circuit diff` shows it.
+ */
+export function planRename(root: string, from: string, to: string, options: { file: boolean; snapshots: string[] }): RenamePlan {
+    const changes: LineChange[] = [];
+    const moves: RenamePlan["moves"] = [];
+
+    const exact = new RegExp(`(["'\`])${escape(from)}\\1`, "g");
+    const anywhere = new RegExp(`(^|[^A-Za-z0-9_.-])${escape(from)}(?![A-Za-z0-9_-])`);
+
+    const sources = projectSources(root);
+    const declaring = new Set<string>();
+
+    for (const file of sources) {
+        const text = readFileSync(join(root, file), "utf8");
+        const lines = text.split("\n");
+
+        // The device's own file calls defineDevice and gives it the name.
+        if (declaresDevice(text, from)) declaring.add(file);
+
+        for (const [index, before] of lines.entries()) {
+            const after = before.replace(exact, (_match, quote: string) => `${quote}${to}${quote}`);
+            if (after !== before) changes.push({ file, line: index + 1, before, after });
+        }
+    }
+
+    if (!declaring.size) {
+        throw new Error(
+            `no file declares name: "${from}"; the name may be built from parts, such as a template string, so rename it by hand`
+        );
+    }
+
+    for (const snapshot of options.snapshots) {
+        moves.push({ from: snapshot, to: join(dirname(snapshot), `${to}${extname(snapshot)}`) });
+    }
+
+    if (options.file) {
+        if (declaring.size > 1) throw new Error(`${[...declaring].join(" and ")} both declare name: "${from}"; rename the file by hand`);
+
+        const [file] = [...declaring] as [string];
+        const target = join(dirname(file), `${to}${extname(file)}`);
+        if (existsSync(join(root, target))) throw new Error(`${target} already exists`);
+
+        moves.push({ from: file, to: target });
+        changes.push(...importChanges(root, sources, file, target, changes));
+    }
+
+    // What still names the device once every change is made.
+    const mentions = sources.flatMap((file) =>
+        readFileSync(join(root, file), "utf8")
+            .split("\n")
+            .flatMap((original, index) => {
+                const text = changes.find((change) => change.file === file && change.line === index + 1)?.after ?? original;
+                return anywhere.test(text) ? [{ file, line: index + 1, text: text.trim() }] : [];
+            })
+    );
+
+    return { changes, moves, mentions };
+}
+
+/** Imports of a file that moves, pointed at its new name. Lines already changed are changed further. */
+function importChanges(root: string, sources: string[], file: string, target: string, earlier: LineChange[]): LineChange[] {
+    const result: LineChange[] = [];
+    const withoutExtension = (path: string) => path.replace(/\.(ts|mts|cts|js|mjs|cjs)$/, "");
+    const moved = withoutExtension(resolve(root, file));
+
+    for (const source of sources) {
+        const lines = readFileSync(join(root, source), "utf8").split("\n");
+
+        for (const [index, original] of lines.entries()) {
+            const line = index + 1;
+            const changed = earlier.find((change) => change.file === source && change.line === line);
+            const before = changed?.after ?? original;
+
+            // A relative specifier that resolves to the moved file keeps its own form, extension or not.
+            const after = before.replace(
+                /(\bfrom\s+|\bimport\s*\(\s*)(["'])(\.{1,2}\/[^"']+)\2/g,
+                (match, lead: string, quote: string, specifier: string) => {
+                    if (withoutExtension(resolve(root, dirname(source), specifier)) !== moved) return match;
+
+                    const extension = specifier.match(/\.(ts|mts|cts|js|mjs|cjs)$/)?.[0] ?? "";
+                    const renamed = `${dirname(specifier)}/${basename(withoutExtension(target))}${extension}`;
+                    return `${lead}${quote}${renamed}${quote}`;
+                }
+            );
+
+            if (after === before) continue;
+
+            if (changed) changed.after = after;
+            else result.push({ file: source, line, before: original, after });
+        }
+    }
+
+    return result;
+}
+
+/** Write the plan: each changed line, then each move. */
+export function applyRename(root: string, plan: RenamePlan): void {
+    const files = new Set(plan.changes.map((change) => change.file));
+
+    for (const file of files) {
+        const lines = readFileSync(join(root, file), "utf8").split("\n");
+        for (const change of plan.changes.filter((each) => each.file === file)) lines[change.line - 1] = change.after;
+        writeFileSync(join(root, file), lines.join("\n"));
+    }
+
+    for (const move of plan.moves) renameSync(join(root, move.from), join(root, move.to));
+}