@takodotid/circuit 0.34.3 → 0.36.0

package/src/transport/path-check.ts

@@ -0,0 +1,91 @@
+// How good the path to a device is, measured before an apply sends anything. A path that drops packets is how a change loses the device halfway.
+
+import { spawn } from "node:child_process";
+import { isIPv6 } from "node:net";
+
+/** What the pings found: how many were sent, and the round trip of each that came back, in milliseconds. */
+export type PathMeasure = { sent: number; times: number[] };
+
+/** Whether an apply may go ahead over the path, and a line that says why. */
+export type PathVerdict = { refuse: boolean; summary: string };
+
+export class PathCheck {
+    /** Pings sent in all. With 20, one lost is 5%. */
+    static readonly PINGS = 20;
+
+    /** Ping programs run side by side, so the check takes about five seconds on every system: each sends one ping a second. */
+    private static readonly RUNS = 4;
+
+    /** The most loss allowed, in percent: one of 20 pings may be lost, two may not. */
+    static readonly MAX_LOSS_PERCENT = 5;
+
+    /** The highest average round trip allowed, in milliseconds. */
+    static readonly MAX_AVERAGE_MS = 300;
+
+    /** How long one ping program may run before it is stopped and what it printed is counted. */
+    private static readonly LIMIT_MS = 15_000;
+
+    /**
+     * The round trip of every reply in what `ping` printed, in milliseconds. A reply is the one line with a time after `=` or `<` and before `ms`, as in `time=12 ms` or `time<1ms`: the same in every language `ping` prints in. A summary line has several times, or none right before `ms`, and is not counted.
+     */
+    static parse(output: string): number[] {
+        const times: number[] = [];
+
+        for (const line of output.split(/\r?\n/)) {
+            const found = [...line.matchAll(/[=<]\s*(\d+(?:[.,]\d+)?)\s*ms\b/gi)];
+            if (found.length === 1) times.push(Number(found[0]![1]!.replace(",", ".")));
+        }
+
+        return times;
+    }
+
+    /** Whether the path is good enough to apply over. A device that answers no ping at all may only block it, so that alone is not refused. */
+    static verdict(host: string, measure: PathMeasure): PathVerdict {
+        const received = Math.min(measure.times.length, measure.sent);
+
+        if (!received) return { refuse: false, summary: `${host} answers no ping, so the path to it was not measured` };
+
+        const lost = measure.sent - received;
+        const lossPercent = Math.round((lost / measure.sent) * 100);
+        const average = Math.round(measure.times.reduce((sum, time) => sum + time, 0) / measure.times.length);
+        const summary = `${host}: ${lost} of ${measure.sent} pings lost (${lossPercent}%), ${average} ms on average`;
+
+        const refuse = lossPercent > PathCheck.MAX_LOSS_PERCENT || average > PathCheck.MAX_AVERAGE_MS;
+        return { refuse, summary };
+    }
+
+    /** Ping a host with the system's `ping`. Undefined when there is no `ping` to run. */
+    static async measure(host: string): Promise<PathMeasure | undefined> {
+        const count = PathCheck.PINGS / PathCheck.RUNS;
+        const outputs = await Promise.all(Array.from({ length: PathCheck.RUNS }, () => PathCheck.ping(host, count)));
+        if (outputs.some((output) => output === undefined)) return undefined;
+
+        // A duplicate reply is printed as a reply too; no run counts more replies than it sent.
+        const times = outputs.flatMap((output) => PathCheck.parse(output!).slice(0, count));
+        return { sent: PathCheck.PINGS, times };
+    }
+
+    /** What one run of `ping` printed. Windows takes `-n` and a wait per ping in milliseconds; Linux and macOS take `-c`, and macOS pings IPv6 with `ping6`. */
+    private static ping(host: string, count: number): Promise<string | undefined> {
+        const windows = process.platform === "win32";
+        const program = !windows && process.platform === "darwin" && isIPv6(host) ? "ping6" : "ping";
+        const args = windows ? ["-n", String(count), "-w", "1000", host] : ["-c", String(count), host];
+
+        return new Promise((done) => {
+            const child = spawn(program, args, { windowsHide: true });
+            let output = "";
+
+            const limit = setTimeout(() => child.kill(), PathCheck.LIMIT_MS);
+
+            child.stdout.on("data", (chunk: Buffer) => (output += chunk.toString("utf8")));
+            child.on("error", () => {
+                clearTimeout(limit);
+                done(undefined);
+            });
+            child.on("close", () => {
+                clearTimeout(limit);
+                done(output);
+            });
+        });
+    }
+}

package/src/transport/ssh.ts

@@ -12,121 +12,125 @@ export type Login = {
     hostKeys?: string[];
 };
 
-/** The address SSH reaches a device at. A device without one is reached only through its console. */
-export function managementHost(device: Device): string {
-    if (!device.connection.host) throw new Error(`${device.name} has no management address; it is reached through its console`);
-    return device.connection.host;
-}
+export class Ssh {
+    /** The address SSH reaches a device at. A device without one is reached only through its console. */
+    static hostOf(device: Device): string {
+        if (!device.connection.host) throw new Error(`${device.name} has no management address; it is reached through its console`);
+        return device.connection.host;
+    }
+
+    /** Open a session. */
+    static connect(login: Login): Promise<Client> {
+        return new Promise((resolve, reject) => {
+            const client = new Client();
+
+            client
+                .on("ready", () => resolve(client))
+                .on("error", reject)
+                .connect({
+                    host: login.host,
+                    port: login.port ?? 22,
+                    username: login.user,
+                    password: login.password,
+                    readyTimeout: 30_000,
+                    ...(login.hostKeys ? { algorithms: { serverHostKey: login.hostKeys as never } } : {}),
+                });
+        });
+    }
 
-/** Open a session. */
-export function connect(login: Login): Promise<Client> {
-    return new Promise((resolve, reject) => {
-        const client = new Client();
-
-        client
-            .on("ready", () => resolve(client))
-            .on("error", reject)
-            .connect({
-                host: login.host,
-                port: login.port ?? 22,
-                username: login.user,
-                password: login.password,
-                readyTimeout: 30_000,
-                ...(login.hostKeys ? { algorithms: { serverHostKey: login.hostKeys as never } } : {}),
-            });
-    });
-}
+    /** Run one command and return what it printed, stderr included. */
+    static exec(client: Client, command: string, timeout = 120_000): Promise<string> {
+        return new Promise((resolve, reject) => {
+            client.exec(command, (error, stream) => {
+                if (error) return reject(error);
 
-/** Run one command and return what it printed, stderr included. */
-export function exec(client: Client, command: string, timeout = 120_000): Promise<string> {
-    return new Promise((resolve, reject) => {
-        client.exec(command, (error, stream) => {
-            if (error) return reject(error);
+                let output = "";
+                const append = (chunk: Buffer) => (output += chunk.toString("utf8"));
+                const timer = setTimeout(() => resolve(output.trim()), timeout);
 
-            let output = "";
-            const append = (chunk: Buffer) => (output += chunk.toString("utf8"));
-            const timer = setTimeout(() => resolve(output.trim()), timeout);
+                stream.on("data", append);
+                stream.stderr.on("data", append);
 
-            stream.on("data", append);
-            stream.stderr.on("data", append);
-
-            stream.on("close", () => {
-                clearTimeout(timer);
-                resolve(output.trim());
+                stream.on("close", () => {
+                    clearTimeout(timer);
+                    resolve(output.trim());
+                });
             });
         });
-    });
-}
+    }
 
-/** An interactive shell, for platforms that take configuration only there. */
-export function shell(client: Client, columns = 200, rows = 1000): Promise<ClientChannel> {
-    return new Promise((resolve, reject) => {
-        client.shell({ cols: columns, rows }, (error, channel) => (error ? reject(error) : resolve(channel)));
-    });
-}
+    /** An interactive shell, for platforms that take configuration only there. */
+    static shell(client: Client, columns = 200, rows = 1000): Promise<ClientChannel> {
+        return new Promise((resolve, reject) => {
+            client.shell({ cols: columns, rows }, (error, channel) => (error ? reject(error) : resolve(channel)));
+        });
+    }
 
-/** Collect output until `done` holds, then wait `settle` for stragglers, or give up at `timeout`. */
-export function readUntil(channel: ClientChannel, done: (output: string) => boolean, timeout: number, settle = 400): Promise<string> {
-    return new Promise((resolve) => {
-        let output = "";
-        let finished = false;
+    /** Collect output until `done` holds, then wait `settle` for stragglers, or give up at `timeout`. */
+    static readUntil(channel: ClientChannel, done: (output: string) => boolean, timeout: number, settle = 400): Promise<string> {
+        return new Promise((resolve) => {
+            let output = "";
+            let finished = false;
 
-        const finish = () => {
-            if (finished) return;
+            const finish = () => {
+                if (finished) return;
 
-            finished = true;
-            channel.removeListener("data", onData);
-            resolve(output);
-        };
+                finished = true;
+                channel.removeListener("data", onData);
+                resolve(output);
+            };
 
-        const onData = (chunk: Buffer) => {
-            output += chunk.toString("utf8");
-            if (done(output)) setTimeout(finish, settle);
-        };
+            const onData = (chunk: Buffer) => {
+                output += chunk.toString("utf8");
+                if (done(output)) setTimeout(finish, settle);
+            };
 
-        channel.on("data", onData);
-        setTimeout(finish, timeout);
-    });
-}
+            channel.on("data", onData);
+            setTimeout(finish, timeout);
+        });
+    }
 
-/** Send one line into an interactive shell and collect output until it goes quiet for `settle`. */
-export function send(channel: ClientChannel, line: string, timeout = 20_000, settle = 1500): Promise<string> {
-    channel.write(line + "\n");
+    /** Send one line into an interactive shell and collect output until it goes quiet for `settle`. */
+    static send(channel: ClientChannel, line: string, timeout = 20_000, settle = 1500): Promise<string> {
+        channel.write(line + "\n");
 
-    return new Promise((resolve) => {
-        let output = "";
-        let timer: ReturnType<typeof setTimeout>;
+        return new Promise((resolve) => {
+            let output = "";
+            let timer: ReturnType<typeof setTimeout>;
 
-        const finish = () => {
-            channel.removeListener("data", onData);
-            resolve(output);
-        };
+            const finish = () => {
+                channel.removeListener("data", onData);
+                resolve(output);
+            };
 
-        const onData = (chunk: Buffer) => {
-            output += chunk.toString("utf8");
-            clearTimeout(timer);
-            timer = setTimeout(finish, settle);
-        };
+            const onData = (chunk: Buffer) => {
+                output += chunk.toString("utf8");
+                clearTimeout(timer);
+                timer = setTimeout(finish, settle);
+            };
 
-        channel.on("data", onData);
-        timer = setTimeout(finish, timeout);
-    });
-}
+            channel.on("data", onData);
+            timer = setTimeout(finish, timeout);
+        });
+    }
 
-export const sleep = (milliseconds: number) => new Promise((done) => setTimeout(done, milliseconds));
+    static sleep(milliseconds: number): Promise<unknown> {
+        return new Promise((done) => setTimeout(done, milliseconds));
+    }
 
-/** Write a file to the device over SFTP. */
-export function upload(client: Client, path: string, content: string | Buffer): Promise<void> {
-    return new Promise((resolve, reject) => {
-        client.sftp((error, sftp) => {
-            if (error) return reject(error);
+    /** Write a file to the device over SFTP. */
+    static upload(client: Client, path: string, content: string | Buffer): Promise<void> {
+        return new Promise((resolve, reject) => {
+            client.sftp((error, sftp) => {
+                if (error) return reject(error);
 
-            sftp.writeFile(path, content, (writeError) => {
-                sftp.end();
+                sftp.writeFile(path, content, (writeError) => {
+                    sftp.end();
 
-                if (writeError) reject(writeError);
-                else resolve();
+                    if (writeError) reject(writeError);
+                    else resolve();
+                });
             });
         });
-    });
+    }
 }

package/templates/colocation/checks.ts

@@ -1,16 +1,19 @@
 // Rules of your own. `circuit validate` runs them beside Circuit's own, and an error stops `diff` and `apply`.
 
 import type { Check, Finding } from "@takodotid/circuit";
-import { contains } from "@takodotid/circuit";
-import { exportsEndInReject, trustBoundary } from "@takodotid/circuit/presets";
+import { Address } from "@takodotid/circuit";
+import { Checks } from "@takodotid/circuit/helpers";
 import { TENANTS } from "./tenants";
 
 export default [
     // Nothing leaves by accident: every export ends by rejecting what it did not accept.
-    exportsEndInReject,
+    Checks.exportsEndInReject,
 
     // Traffic from the transit and the exchange reaches the tenants only through the router, which filters it.
-    trustBoundary({ untrusted: ["transit", "ix"], routers: ["edge-01"] }),
+    Checks.trustBoundary({ untrusted: ["transit", "ix"], routers: ["edge-01"] }),
+
+    // A native VLAN stays on one trunk and nowhere else, or it joins every trunk it is native on.
+    Checks.nativeVlansAreDeadEnds,
 
     // Tenants never share a name, a number, an address or a port. A port given twice would go to the last tenant alone.
     () => {
@@ -23,7 +26,9 @@ export default [
                 if (other.number === t.number) error(`tenants ${t.name} and ${other.name} share number ${t.number}`);
 
                 for (const block of t.blocks) {
-                    const clash = other.blocks.find(({ prefix }) => contains(prefix, block.prefix) || contains(block.prefix, prefix));
+                    const clash = other.blocks.find(
+                        ({ prefix }) => Address.contains(prefix, block.prefix) || Address.contains(block.prefix, prefix)
+                    );
                     if (clash) error(`${block.prefix} of ${t.name} overlaps ${clash.prefix} of ${other.name}`);
                 }
             }
@@ -36,7 +41,7 @@ export default [
             }
 
             for (const { prefix, gateway } of t.blocks) {
-                if (!contains(prefix, gateway)) error(`the gateway ${gateway} of ${t.name} is outside ${prefix}`);
+                if (!Address.contains(prefix, gateway)) error(`the gateway ${gateway} of ${t.name} is outside ${prefix}`);
             }
         });
 

package/templates/colocation/edge-01.ts

@@ -3,8 +3,8 @@
 // Hurricane Electric and SGIX stand for your own transit and exchange. Addresses are from the documentation ranges; use the ones your providers give you.
 
 import type { Prefix } from "@takodotid/circuit";
-import { defineDevice, merge, secret } from "@takodotid/circuit";
-import { antiSpoofing, badTcpFlags, bgpSanity, MARTIANS, PRIVATE_RANGES } from "@takodotid/circuit/presets";
+import { defineDevice, secret, Utils } from "@takodotid/circuit";
+import { Bgp, Filters } from "@takodotid/circuit/helpers";
 import { ASN, communities } from "./routing";
 import { edgeRules, gateways, internetVlanNames, internetVlans } from "./tenancy";
 import { TENANTS } from "./tenants";
@@ -16,7 +16,7 @@ const OURS = ["198.51.100.0/24", "2001:db8:100::/48"] as const satisfies readonl
 const MANAGEMENT = "10.0.0.0/24" satisfies Prefix;
 
 /** Sources that never arrive from the internet: our own space, and addresses that are not on the internet at all. */
-const SPOOFED = [OURS[0], ...MARTIANS, ...PRIVATE_RANGES];
+const SPOOFED = [OURS[0], ...Filters.MARTIANS, ...Filters.PRIVATE_RANGES];
 
 export default defineDevice({
     name: "edge-01",
@@ -28,7 +28,7 @@ export default defineDevice({
     system: { timezone: "Asia/Jakarta", ntp: { servers: ["pool.ntp.org"] } },
     management: { allow: [MANAGEMENT], ssh: {} },
 
-    vlans: merge(
+    vlans: Utils.merge(
         {
             mgmt: { id: 99, description: "Management of the switches" },
             transit: { id: 300, description: "IP transit from Hurricane Electric, AS6939" },
@@ -49,7 +49,7 @@ export default defineDevice({
         },
     },
 
-    interfaces: merge(
+    interfaces: Utils.merge(
         {
             mgmt: { type: "vlan", vlan: "mgmt", addresses: ["10.0.99.1/24"] },
             transit: { type: "vlan", vlan: "transit", addresses: ["203.0.113.2/30"] },
@@ -95,7 +95,7 @@ export default defineDevice({
     },
 
     policies: {
-        SANITY: bgpSanity(),
+        SANITY: Bgp.sanity(),
         // A route from the exchange is preferred over the same route from the transit: higher local preference wins.
         "TRANSIT-IN": [{ call: "SANITY" }, communities.tag("transit", 6939), { set: { local_pref: 100 } }, { action: "accept" }],
         "IX-IN": [{ call: "SANITY" }, communities.tag("exchange", 55518), { set: { local_pref: 200 } }, { action: "accept" }],
@@ -117,15 +117,15 @@ export default defineDevice({
                     { description: "BGP", match: { protocol: "tcp", dst_port: 179, src_set: "bgp-neighbors" }, action: "accept" },
                 ],
             },
-            forward: { rules: [...badTcpFlags()] },
+            forward: { rules: [...Filters.badTcpFlags()] },
         },
     },
 
     // In the switch chip, before a packet reaches the router's CPU: spoofed sources first, then each tenant's own rules.
     acls: {
         edge: [
-            ...antiSpoofing("transit", SPOOFED),
-            ...antiSpoofing("ix", SPOOFED),
+            ...Filters.antiSpoofing("transit", SPOOFED),
+            ...Filters.antiSpoofing("ix", SPOOFED),
             ...edgeRules(TENANTS, "transit"),
             ...edgeRules(TENANTS, "ix"),
         ],

package/templates/colocation/routing.ts

@@ -1,12 +1,12 @@
 // What your network is on the internet: its AS number and its BGP communities.
 
-import { communityScheme } from "@takodotid/circuit/presets";
+import { Bgp } from "@takodotid/circuit/helpers";
 
 /** Your AS number. */
 export const ASN = 64500;
 
 /** What your BGP communities mean. The router tags each route it learns with them, and `circuit communities` publishes them. */
-export const communities = communityScheme({
+export const communities = Bgp.communityScheme({
     asn: ASN,
     learned_from: { function: 1, classes: { transit: 1, exchange: 2 } },
     learned_from_as: 3,

package/templates/colocation/tenancy.ts

@@ -1,7 +1,7 @@
 // What a tenant is, and what each device carries for it. A tenant's file says what is the tenant's own; its VLANs and names follow from its name and number.
 
 import type { AclRule, Interface, IP, Port, Prefix, Vlan } from "@takodotid/circuit";
-import { familyOf } from "@takodotid/circuit";
+import { Address } from "@takodotid/circuit";
 
 /** A tenant's networks. `internet` carries its servers' public addresses and reaches the router. `private` connects its own servers to each other and stays on the switches. */
 type TenantNetwork = "internet" | "private";
@@ -75,7 +75,7 @@ export function gateways<N extends string>(tenants: readonly Tenant<N>[]) {
             type: "vlan",
             vlan: internetVlan(t),
             description: `Tenant ${t.name}`,
-            addresses: t.blocks.map(({ prefix, gateway }) => `${gateway}/${prefix.split("/")[1]}`),
+            addresses: t.blocks.map(({ prefix, gateway }): Prefix => `${gateway}/${Address.split(prefix).len}`),
         };
     }
 
@@ -87,7 +87,7 @@ export const edgeRules = <V extends string>(tenants: readonly Tenant[], vlan: V)
     tenants.flatMap((t) =>
         (t.acl ?? []).flatMap((rule) =>
             t.blocks
-                .filter(({ prefix }) => familyOf(prefix) === "ipv4")
+                .filter(({ prefix }) => Address.family(prefix) === "ipv4")
                 .map(({ prefix }) => ({
                     ...rule,
                     ...(rule.description ? { description: `${vlan}: ${rule.description}` } : {}),

package/templates/colocation/tor-01.ts

@@ -1,6 +1,6 @@
 // The top-of-rack switch: the tenants' servers, and one uplink to the router.
 
-import { defineDevice, merge, secret } from "@takodotid/circuit";
+import { defineDevice, secret, Utils } from "@takodotid/circuit";
 import { internetVlanNames, internetVlans, portsOn, privateVlans } from "./tenancy";
 import { TENANTS } from "./tenants";
 
@@ -17,10 +17,10 @@ export default defineDevice({
     lldp: true,
     stp: {},
 
-    vlans: merge({ mgmt: { id: 99, description: "Management" } }, internetVlans(TENANTS), privateVlans(TENANTS, "tor-01")),
+    vlans: Utils.merge({ mgmt: { id: 99, description: "Management" } }, internetVlans(TENANTS), privateVlans(TENANTS, "tor-01")),
 
     // Every tenant's ports, from its file in tenants/, beside the switch's own.
-    ports: merge(portsOn(TENANTS, "tor-01"), {
+    ports: Utils.merge(portsOn(TENANTS, "tor-01"), {
         "40g-1": {
             description: "edge-01",
             trunk_vlans: ["mgmt", ...internetVlanNames(TENANTS)],

package/templates/edge-router/checks.ts

@@ -1,19 +1,19 @@
 // Rules of your own. `circuit validate` runs them beside Circuit's own, and an error stops `diff` and `apply`.
 
 import type { Check } from "@takodotid/circuit";
-import { exportsEndInReject, neighborPolicies, trustBoundary } from "@takodotid/circuit/presets";
+import { Bgp, Checks } from "@takodotid/circuit/helpers";
 
 export default [
     // Nothing leaves by accident: every export ends by rejecting what it did not accept.
-    exportsEndInReject,
+    Checks.exportsEndInReject,
 
     // Traffic from the transit and the exchange reaches the rest of the network only through the router.
-    trustBoundary({ untrusted: ["transit", "ix"], routers: ["edge-01"] }),
+    Checks.trustBoundary({ untrusted: ["transit", "ix"], routers: ["edge-01"] }),
 
     // Every BGP session filters what it takes in.
     (devices) =>
         devices.flatMap((device) =>
-            neighborPolicies(device)
+            Bgp.neighborPolicies(device)
                 .filter((neighbor) => !neighbor.import)
                 .map((neighbor) => ({ level: "error" as const, device: device.name, message: `${neighbor.name} has no import policy` }))
         ),

package/templates/edge-router/edge-01.ts

@@ -4,7 +4,7 @@
 
 import type { Prefix } from "@takodotid/circuit";
 import { defineDevice, secret } from "@takodotid/circuit";
-import { antiSpoofing, badTcpFlags, bgpSanity, MARTIANS, PRIVATE_RANGES } from "@takodotid/circuit/presets";
+import { Bgp, Filters } from "@takodotid/circuit/helpers";
 import { ASN, communities } from "./routing";
 
 /** The address space this router announces. */
@@ -14,7 +14,7 @@ const OURS = ["198.51.100.0/24", "2001:db8:100::/48"] as const satisfies readonl
 const MANAGEMENT = "10.0.0.0/24" satisfies Prefix;
 
 /** Sources that never arrive from the internet: our own space, and addresses that are not on the internet at all. */
-const SPOOFED = [OURS[0], ...MARTIANS, ...PRIVATE_RANGES];
+const SPOOFED = [OURS[0], ...Filters.MARTIANS, ...Filters.PRIVATE_RANGES];
 
 export default defineDevice({
     name: "edge-01",
@@ -79,7 +79,7 @@ export default defineDevice({
     },
 
     policies: {
-        SANITY: bgpSanity(),
+        SANITY: Bgp.sanity(),
         // A route from the exchange is preferred over the same route from the transit: higher local preference wins.
         "TRANSIT-IN": [{ call: "SANITY" }, communities.tag("transit", 6939), { set: { local_pref: 100 } }, { action: "accept" }],
         "IX-IN": [{ call: "SANITY" }, communities.tag("exchange", 55518), { set: { local_pref: 200 } }, { action: "accept" }],
@@ -101,10 +101,10 @@ export default defineDevice({
                     { description: "BGP", match: { protocol: "tcp", dst_port: 179, src_set: "bgp-neighbors" }, action: "accept" },
                 ],
             },
-            forward: { rules: [...badTcpFlags()] },
+            forward: { rules: [...Filters.badTcpFlags()] },
         },
     },
 
     // In the switch chip, before a packet reaches the router's CPU.
-    acls: { edge: [...antiSpoofing("transit", SPOOFED), ...antiSpoofing("ix", SPOOFED)] },
+    acls: { edge: [...Filters.antiSpoofing("transit", SPOOFED), ...Filters.antiSpoofing("ix", SPOOFED)] },
 });

package/templates/edge-router/routing.ts

@@ -1,12 +1,12 @@
 // What your network is on the internet: its AS number and its BGP communities.
 
-import { communityScheme } from "@takodotid/circuit/presets";
+import { Bgp } from "@takodotid/circuit/helpers";
 
 /** Your AS number. */
 export const ASN = 64500;
 
 /** What your BGP communities mean. The router tags each route it learns with them, and `circuit communities` publishes them. */
-export const communities = communityScheme({
+export const communities = Bgp.communityScheme({
     asn: ASN,
     learned_from: { function: 1, classes: { transit: 1, exchange: 2 } },
     learned_from_as: 3,

package/templates/project/AGENTS.md

@@ -22,6 +22,9 @@ What each field means is written as a comment on the field, in `node_modules/@ta
 | `npx circuit diff [device]`                   | Shows what would change, compared with the last snapshot                      | no               |
 | `npx circuit build <device>`                  | Prints the full configuration the device should run                           | no               |
 | `npx circuit snapshot [device]`               | Reads what each device runs now into `.circuit/state/`                        | no, only reads   |
+| `npx circuit show <device> '<command>'`       | Runs commands that only read on the device, secrets hidden                    | no, only reads   |
+| `npx circuit bgp [device] [name-regex]`       | Each BGP neighbor in the config next to its live session: up or down          | no, only reads   |
+| `npx circuit console <device> '<line>'`       | Sends lines to the device's serial console, unchecked                         | **can**          |
 | `npx circuit apply <device>`                  | Reads the device, then shows what would change on it                          | no               |
 | `npx circuit apply <device> --confirm`        | Sends the change to the device                                                | **yes**          |
 | `npx circuit secrets`                         | Lists every secret the config uses, and whether each one can be read          | no               |
@@ -41,7 +44,8 @@ What each field means is written as a comment on the field, in `node_modules/@ta
 
 ## Rules
 
-- Never run `apply --confirm`, `refresh --confirm` or `peeringdb --confirm` without the owner's explicit approval for that run.
+- Never run `apply --confirm`, `refresh --confirm` or `peeringdb --confirm`, or `console` with a line that changes something, without the owner's explicit approval for that run.
 - If a plan removes something you did not expect, stop and ask. It usually means the file is missing something the device needs.
 - Be careful with anything that carries your own access to the device: the management address, the management VLAN, the uplink, `management.allow`, and the login user. A mistake there locks everyone out.
+- A platform supports only the OS versions listed at https://circuit.tako.id/platforms/. Before the first apply to a device, check that it runs one of them.
 - When you are not sure what a field does, or what the owner wants, ask instead of guessing.

package/templates/single-site/checks.ts

@@ -1,7 +1,7 @@
 // Rules of your own. `circuit validate` runs them beside Circuit's own, and an error stops `diff` and `apply`.
 
 import type { Check } from "@takodotid/circuit";
-import { vlansOf } from "@takodotid/circuit/presets";
+import { Checks } from "@takodotid/circuit/helpers";
 
 export default [
     // A port without a description is hard to trace later. A warning, so it does not block anything.
@@ -16,7 +16,7 @@ export default [
     (devices) =>
         devices.flatMap((device) =>
             Object.entries(device.ports ?? {})
-                .filter(([, port]) => port?.access_vlan && vlansOf(port).includes("mgmt"))
+                .filter(([, port]) => port?.access_vlan && Checks.vlansOf(port).includes("mgmt"))
                 .map(([name]) => ({
                     level: "error" as const,
                     device: device.name,