@takodotid/circuit 0.34.2 → 0.35.0

package/dist/types/schema/routing.d.ts

@@ -9,6 +9,8 @@ export type StaticRoute<I extends string, F extends string> = {
     interface?: I;
     /** Discard matching traffic. The usual way to originate an aggregate. */
     blackhole?: true;
+    /** Withdraw the route while BFD finds `via` dead, and put it back once `via` answers again. Needs `via`. */
+    bfd?: true;
     /** Preference against other routes to the same prefix. Lower wins. 1 when absent. */
     distance?: number;
     /** The VRF the route is in. The default table when absent. */
@@ -69,6 +71,13 @@ export type Bgp<P extends string, G extends string> = {
     /** Sessions keyed by name. */
     neighbors?: Record<string, Neighbor<P, G>>;
 };
+/** How fast BFD notices a dead neighbor: after `multiplier` packets in a row are missed, so in `interval` times `multiplier` milliseconds. */
+export type Bfd = {
+    /** Milliseconds between the packets this device sends, and the shortest gap it asks of the neighbor. */
+    interval: number;
+    /** How many packets in a row may be missed before the neighbor is declared down. */
+    multiplier: number;
+};
 /** A route origin validation server, RFC 8210. */
 export type RpkiServer = {
     /** Where the validator listens. */
@@ -89,12 +98,14 @@ export type OspfInterface = {
     /** Detect a dead neighbor in under a second with BFD. */
     bfd?: boolean;
 };
+/** An OSPF area ID, written as four numbers with dots between them, for example `0.0.0.0` for the backbone. */
+export type OspfAreaId = `${number}.${number}.${number}.${number}`;
 /** OSPF, version 2 for IPv4 and version 3 for IPv6. */
 export type Ospf<I extends string> = {
     /** Which versions run. IPv4 when absent. */
     families?: readonly Family[];
     /** Areas keyed by area ID, for example `0.0.0.0`, each with the interfaces in it. */
-    areas: Record<string, {
+    areas: Record<OspfAreaId, {
         interfaces: Partial<Record<I, OspfInterface>>;
     }>;
     /** Routes from other sources announced into OSPF. */
@@ -112,4 +123,6 @@ export type Routing<P extends string, G extends string, I extends string, F exte
     ospf?: Ospf<I>;
     /** Validators answering route origin validation. */
     rpki?: readonly RpkiServer[];
+    /** BFD timers for every BFD session on the device: BGP, OSPF and static routes. The platform's own when absent; Junos has none, so Circuit sends every 300 ms there. Both ends of a link should agree. */
+    bfd?: Bfd;
 };

package/dist/types/schema/system.d.ts

@@ -1,8 +1,13 @@
-import type { IP, Prefix, Secret, Severity } from "./common";
+import type { IP, MacAddress, Prefix, Secret, Severity } from "./common";
+import type { TimeZone } from "./time-zones";
+/** A software release track, as RouterOS names them. `long-term` changes least; `development` is the newest and least tested. */
+export type ReleaseChannel = "long-term" | "stable" | "testing" | "development";
+/** How bad an alarm is, most severe first, as ITU-T X.733 ranks them. */
+export type AlarmSeverity = "critical" | "major" | "minor" | "warning";
 /** Device-wide settings. */
 export type System = {
-    /** IANA zone, for example `Asia/Jakarta`. UTC when absent. */
-    timezone?: string;
+    /** IANA zone, for example `Asia/Jakarta`. The editor suggests every name. UTC when absent. */
+    timezone?: TimeZone;
     /** Shown at login. */
     banner?: string;
     /** Resolvers the device uses. */
@@ -39,8 +44,12 @@ export type System = {
             level: Severity;
         }[];
     };
-    /** Software release track the device updates from. */
-    release_channel?: string;
+    /** Software release track the device updates from. `stable` when absent. */
+    release_channel?: ReleaseChannel;
+    /** Alarms raised at another severity than the platform's own, keyed by the alarm's name as the platform spells it, such as `hwOpticalUnAuthorized` on VRP. */
+    alarms?: Record<string, {
+        severity: AlarmSeverity;
+    }>;
     /** Read optic temperature, power and voltage. */
     transceiver_monitoring?: boolean;
     /** Host behaviour of the IP stack. */
@@ -152,7 +161,8 @@ export type DhcpServer<I extends string> = {
     /** Addresses fixed to a MAC. */
     reservations?: readonly {
         address: IP;
-        mac: string;
+        /** The client's MAC address. */
+        mac: MacAddress;
         /** Whose address it is. */
         description?: string;
     }[];

package/dist/types/schema/time-zones.d.ts

@@ -0,0 +1,2 @@
+/** An IANA time zone name, such as `Asia/Jakarta`, or `UTC`. */
+export type TimeZone = "UTC" | "Africa/Abidjan" | "Africa/Accra" | "Africa/Addis_Ababa" | "Africa/Algiers" | "Africa/Asmara" | "Africa/Asmera" | "Africa/Bamako" | "Africa/Bangui" | "Africa/Banjul" | "Africa/Bissau" | "Africa/Blantyre" | "Africa/Brazzaville" | "Africa/Bujumbura" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Ceuta" | "Africa/Conakry" | "Africa/Dakar" | "Africa/Dar_es_Salaam" | "Africa/Djibouti" | "Africa/Douala" | "Africa/El_Aaiun" | "Africa/Freetown" | "Africa/Gaborone" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Juba" | "Africa/Kampala" | "Africa/Khartoum" | "Africa/Kigali" | "Africa/Kinshasa" | "Africa/Lagos" | "Africa/Libreville" | "Africa/Lome" | "Africa/Luanda" | "Africa/Lubumbashi" | "Africa/Lusaka" | "Africa/Malabo" | "Africa/Maputo" | "Africa/Maseru" | "Africa/Mbabane" | "Africa/Mogadishu" | "Africa/Monrovia" | "Africa/Nairobi" | "Africa/Ndjamena" | "Africa/Niamey" | "Africa/Nouakchott" | "Africa/Ouagadougou" | "Africa/Porto-Novo" | "Africa/Sao_Tome" | "Africa/Tripoli" | "Africa/Tunis" | "Africa/Windhoek" | "America/Adak" | "America/Anchorage" | "America/Anguilla" | "America/Antigua" | "America/Araguaina" | "America/Argentina/Buenos_Aires" | "America/Argentina/Catamarca" | "America/Argentina/Cordoba" | "America/Argentina/Jujuy" | "America/Argentina/La_Rioja" | "America/Argentina/Mendoza" | "America/Argentina/Rio_Gallegos" | "America/Argentina/Salta" | "America/Argentina/San_Juan" | "America/Argentina/San_Luis" | "America/Argentina/Tucuman" | "America/Argentina/Ushuaia" | "America/Aruba" | "America/Asuncion" | "America/Atikokan" | "America/Bahia" | "America/Bahia_Banderas" | "America/Barbados" | "America/Belem" | "America/Belize" | "America/Blanc-Sablon" | "America/Boa_Vista" | "America/Bogota" | "America/Boise" | "America/Buenos_Aires" | "America/Cambridge_Bay" | "America/Campo_Grande" | "America/Cancun" | "America/Caracas" | "America/Catamarca" | "America/Cayenne" | "America/Cayman" | "America/Chicago" | "America/Chihuahua" | "America/Ciudad_Juarez" | "America/Coral_Harbour" | "America/Cordoba" | "America/Costa_Rica" | "America/Creston" | "America/Cuiaba" | "America/Curacao" | "America/Danmarkshavn" | "America/Dawson" | "America/Dawson_Creek" | "America/Denver" | "America/Detroit" | "America/Dominica" | "America/Edmonton" | "America/Eirunepe" | "America/El_Salvador" | "America/Fort_Nelson" | "America/Fortaleza" | "America/Glace_Bay" | "America/Godthab" | "America/Goose_Bay" | "America/Grand_Turk" | "America/Grenada" | "America/Guadeloupe" | "America/Guatemala" | "America/Guayaquil" | "America/Guyana" | "America/Halifax" | "America/Havana" | "America/Hermosillo" | "America/Indiana/Indianapolis" | "America/Indiana/Knox" | "America/Indiana/Marengo" | "America/Indiana/Petersburg" | "America/Indiana/Tell_City" | "America/Indiana/Vevay" | "America/Indiana/Vincennes" | "America/Indiana/Winamac" | "America/Indianapolis" | "America/Inuvik" | "America/Iqaluit" | "America/Jamaica" | "America/Jujuy" | "America/Juneau" | "America/Kentucky/Louisville" | "America/Kentucky/Monticello" | "America/Kralendijk" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Louisville" | "America/Lower_Princes" | "America/Maceio" | "America/Managua" | "America/Manaus" | "America/Marigot" | "America/Martinique" | "America/Matamoros" | "America/Mazatlan" | "America/Mendoza" | "America/Menominee" | "America/Merida" | "America/Metlakatla" | "America/Mexico_City" | "America/Miquelon" | "America/Moncton" | "America/Monterrey" | "America/Montevideo" | "America/Montserrat" | "America/Nassau" | "America/New_York" | "America/Nipigon" | "America/Nome" | "America/Noronha" | "America/North_Dakota/Beulah" | "America/North_Dakota/Center" | "America/North_Dakota/New_Salem" | "America/Nuuk" | "America/Ojinaga" | "America/Panama" | "America/Pangnirtung" | "America/Paramaribo" | "America/Phoenix" | "America/Port-au-Prince" | "America/Port_of_Spain" | "America/Porto_Velho" | "America/Puerto_Rico" | "America/Punta_Arenas" | "America/Rainy_River" | "America/Rankin_Inlet" | "America/Recife" | "America/Regina" | "America/Resolute" | "America/Rio_Branco" | "America/Santa_Isabel" | "America/Santarem" | "America/Santiago" | "America/Santo_Domingo" | "America/Sao_Paulo" | "America/Scoresbysund" | "America/Sitka" | "America/St_Barthelemy" | "America/St_Johns" | "America/St_Kitts" | "America/St_Lucia" | "America/St_Thomas" | "America/St_Vincent" | "America/Swift_Current" | "America/Tegucigalpa" | "America/Thule" | "America/Thunder_Bay" | "America/Tijuana" | "America/Toronto" | "America/Tortola" | "America/Vancouver" | "America/Whitehorse" | "America/Winnipeg" | "America/Yakutat" | "America/Yellowknife" | "Antarctica/Casey" | "Antarctica/Davis" | "Antarctica/DumontDUrville" | "Antarctica/Macquarie" | "Antarctica/Mawson" | "Antarctica/McMurdo" | "Antarctica/Palmer" | "Antarctica/Rothera" | "Antarctica/Syowa" | "Antarctica/Troll" | "Antarctica/Vostok" | "Arctic/Longyearbyen" | "Asia/Aden" | "Asia/Almaty" | "Asia/Amman" | "Asia/Anadyr" | "Asia/Aqtau" | "Asia/Aqtobe" | "Asia/Ashgabat" | "Asia/Atyrau" | "Asia/Baghdad" | "Asia/Bahrain" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Barnaul" | "Asia/Beirut" | "Asia/Bishkek" | "Asia/Brunei" | "Asia/Calcutta" | "Asia/Chita" | "Asia/Choibalsan" | "Asia/Chongqing" | "Asia/Colombo" | "Asia/Damascus" | "Asia/Dhaka" | "Asia/Dili" | "Asia/Dubai" | "Asia/Dushanbe" | "Asia/Famagusta" | "Asia/Gaza" | "Asia/Hebron" | "Asia/Ho_Chi_Minh" | "Asia/Hong_Kong" | "Asia/Hovd" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jayapura" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Kathmandu" | "Asia/Katmandu" | "Asia/Khandyga" | "Asia/Kolkata" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuching" | "Asia/Kuwait" | "Asia/Macau" | "Asia/Magadan" | "Asia/Makassar" | "Asia/Manila" | "Asia/Muscat" | "Asia/Nicosia" | "Asia/Novokuznetsk" | "Asia/Novosibirsk" | "Asia/Omsk" | "Asia/Oral" | "Asia/Phnom_Penh" | "Asia/Pontianak" | "Asia/Pyongyang" | "Asia/Qatar" | "Asia/Qostanay" | "Asia/Qyzylorda" | "Asia/Rangoon" | "Asia/Riyadh" | "Asia/Saigon" | "Asia/Sakhalin" | "Asia/Samarkand" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Thimphu" | "Asia/Tokyo" | "Asia/Tomsk" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Ust-Nera" | "Asia/Vientiane" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yangon" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Bermuda" | "Atlantic/Canary" | "Atlantic/Cape_Verde" | "Atlantic/Faeroe" | "Atlantic/Faroe" | "Atlantic/Madeira" | "Atlantic/Reykjavik" | "Atlantic/South_Georgia" | "Atlantic/St_Helena" | "Atlantic/Stanley" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Broken_Hill" | "Australia/Canberra" | "Australia/Currie" | "Australia/Darwin" | "Australia/Eucla" | "Australia/Hobart" | "Australia/Lindeman" | "Australia/Lord_Howe" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Etc/GMT" | "Etc/GMT+1" | "Etc/GMT+10" | "Etc/GMT+11" | "Etc/GMT+12" | "Etc/GMT+2" | "Etc/GMT+3" | "Etc/GMT+4" | "Etc/GMT+5" | "Etc/GMT+6" | "Etc/GMT+7" | "Etc/GMT+8" | "Etc/GMT+9" | "Etc/GMT-1" | "Etc/GMT-10" | "Etc/GMT-11" | "Etc/GMT-12" | "Etc/GMT-13" | "Etc/GMT-14" | "Etc/GMT-2" | "Etc/GMT-3" | "Etc/GMT-4" | "Etc/GMT-5" | "Etc/GMT-6" | "Etc/GMT-7" | "Etc/GMT-8" | "Etc/GMT-9" | "Etc/UTC" | "Europe/Amsterdam" | "Europe/Andorra" | "Europe/Astrakhan" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Busingen" | "Europe/Chisinau" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Gibraltar" | "Europe/Guernsey" | "Europe/Helsinki" | "Europe/Isle_of_Man" | "Europe/Istanbul" | "Europe/Jersey" | "Europe/Kaliningrad" | "Europe/Kiev" | "Europe/Kirov" | "Europe/Kyiv" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Luxembourg" | "Europe/Madrid" | "Europe/Malta" | "Europe/Mariehamn" | "Europe/Minsk" | "Europe/Monaco" | "Europe/Moscow" | "Europe/Oslo" | "Europe/Paris" | "Europe/Podgorica" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/San_Marino" | "Europe/Sarajevo" | "Europe/Saratov" | "Europe/Simferopol" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Tirane" | "Europe/Ulyanovsk" | "Europe/Uzhgorod" | "Europe/Vaduz" | "Europe/Vatican" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zaporozhye" | "Europe/Zurich" | "Indian/Antananarivo" | "Indian/Chagos" | "Indian/Christmas" | "Indian/Cocos" | "Indian/Comoro" | "Indian/Kerguelen" | "Indian/Mahe" | "Indian/Maldives" | "Indian/Mauritius" | "Indian/Mayotte" | "Indian/Reunion" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Bougainville" | "Pacific/Chatham" | "Pacific/Chuuk" | "Pacific/Easter" | "Pacific/Efate" | "Pacific/Enderbury" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Funafuti" | "Pacific/Galapagos" | "Pacific/Gambier" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Johnston" | "Pacific/Kanton" | "Pacific/Kiritimati" | "Pacific/Kosrae" | "Pacific/Kwajalein" | "Pacific/Majuro" | "Pacific/Marquesas" | "Pacific/Midway" | "Pacific/Nauru" | "Pacific/Niue" | "Pacific/Norfolk" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Palau" | "Pacific/Pitcairn" | "Pacific/Pohnpei" | "Pacific/Ponape" | "Pacific/Port_Moresby" | "Pacific/Rarotonga" | "Pacific/Saipan" | "Pacific/Tahiti" | "Pacific/Tarawa" | "Pacific/Tongatapu" | "Pacific/Truk" | "Pacific/Wake" | "Pacific/Wallis";

package/dist/types/transport/console.d.ts

@@ -1,17 +1,9 @@
 import { type ClientChannel } from "ssh2";
 import type { Console, Device } from "../schema";
-/** An open console: the stream to the device's CLI, and how to let it go. */
+/** An open console: the stream to the device's CLI, and how to let it go. `close` waits for the console to go quiet, then lets the port go. */
 export type ConsoleSession = {
     channel: ClientChannel;
-    close: () => void;
-};
-/** Open a device's serial console, through its jump host or on this computer. Fails when another session holds the port. */
-export declare function openConsole(console: Console): Promise<ConsoleSession>;
-/** A device's console and its login, for `--console`. */
-export declare function consoleOf(device: Device): {
-    console: Console;
-    user: string;
-    password: string;
+    close: () => Promise<void>;
 };
 /** How a platform's console asks for a login and shows its prompt, and what moves it on from anywhere else. */
 export type ConsoleDialect = {
@@ -35,25 +27,89 @@ type Channel = Pick<ClientChannel, "write"> & {
     on(event: "data", listener: (chunk: Buffer) => void): unknown;
     removeListener(event: "data", listener: (chunk: Buffer) => void): unknown;
 };
-/** Write, then wait until what the console printed since ends with one of the patterns. Returns which, and what was printed. */
-export declare function expect(channel: Channel, write: string, patterns: readonly RegExp[], timeout?: number): Promise<{
-    index: number;
-    text: string;
-}>;
-/**
- * Log in on a console, whatever state the last session left it in: what `others` names is moved on, a session left open is logged out, so every session starts from a fresh login. Returns once the CLI's prompt shows. A console that asks only for a password (`passwordOnly`) is logged in at its password prompt, with no name typed.
- */
-export declare function consoleLogin(channel: Channel, dialect: ConsoleDialect, user: string, password: string, passwordOnly?: boolean): Promise<void>;
-/** The text after a command's echo. A terminal wraps a long echo where it likes, so the echo is matched character by character, line breaks it added skipped. */
-export declare function afterEcho(text: string, command: string): string;
-/** A CLI on a console that runs one command at a time and returns what it printed, as an SSH exec would: no echo, no prompt. */
+export declare class SerialConsole {
+    private static readonly RELAY_PATH;
+    /** A serial port the relay is started with: a path under /dev, which reaches a shell, or a Windows COM port. */
+    private static readonly PORT;
+    private static readonly WINDOWS_PORT;
+    /** Terminal escape sequences: cursor moves, screen clears, character sets and modes. */
+    private static readonly ESCAPES;
+    /** A session to a jump host, through `cloudflared access ssh` when it sits behind a Cloudflare Tunnel. */
+    private static connectJump;
+    /**
+     * Open a device's serial console, through its jump host or on this computer.
+     *
+     * A port another program holds is tried again every five seconds, `attempts` times in all, then fails with a message that starts with `busy:`.
+     */
+    static open(console: Console, attempts?: number): Promise<ConsoleSession>;
+    private static openOnJump;
+    /** The relay as a child process: Python on Linux and macOS, PowerShell on Windows. */
+    private static openHere;
+    /** Wait until the relay says it holds the port, or why it cannot. */
+    private static relayReady;
+    /** A terminal ends a line with a carriage return. Adapters write lines as they do over SSH, and the console gets what a keyboard would send. */
+    private static asTerminal;
+    /** A device's console and its login, for `--console`. */
+    static of(device: Device): {
+        console: Console;
+        user: string;
+        password: string;
+    };
+    /**
+     * Write, then wait until what the console printed since ends with one of the patterns. Returns which, and what was printed.
+     *
+     * With `settle`, a match counts only once nothing more arrives for that many milliseconds, so a line in the middle of the output that looks like a prompt does not end it.
+     */
+    static expect(channel: Channel, write: string, patterns: readonly RegExp[], timeout?: number, settle?: number): Promise<{
+        index: number;
+        text: string;
+    }>;
+    /**
+     * Log in on a console, whatever state the last session left it in: what `others` names is moved on, a session left open is logged out, so every session starts from a fresh login. Returns once the CLI's prompt shows. A console that asks only for a password (`passwordOnly`) is logged in at its password prompt, with no name typed.
+     */
+    static login(channel: Channel, dialect: ConsoleDialect, user: string, password: string, passwordOnly?: boolean): Promise<void>;
+    /** Wait until the console has printed nothing for `silence` milliseconds, dropping what it printed, at most five seconds. */
+    private static quiet;
+    /** Write, then collect what the console prints until it is quiet for `silence` milliseconds, or for `limit` in all. Carriage returns and escape sequences are dropped. */
+    static listen(channel: Channel, write: string, silence: number, limit?: number): Promise<string>;
+    /** The text after a command's echo. A terminal wraps a long echo where it likes, so the echo is matched character by character, line breaks it added skipped. */
+    static afterEcho(text: string, command: string): string;
+    /** Where the echo of a command that starts at `start` ends, or undefined when the text there is not its echo. */
+    private static echoEnd;
+}
+/** A CLI on a console or in an SSH shell that runs one command at a time and returns what it printed, as an SSH exec would: no echo, no prompt. */
 export declare class ConsoleShell {
     private readonly channel;
     private readonly dialect;
-    constructor(channel: Channel, dialect: ConsoleDialect);
+    /** Milliseconds of quiet after the prompt shows before a command counts as done. */
+    private readonly settle;
+    /** The quiet to wait for after the prompt when output can hold a line that looks like it, as `circuit show` prints whatever the device has. */
+    static readonly SETTLE = 1000;
+    constructor(channel: Channel, dialect: ConsoleDialect, 
+    /** Milliseconds of quiet after the prompt shows before a command counts as done. */
+    settle?: number);
     /** Run a command and wait for the prompt. A pager in `others` is answered as it shows. */
     run(command: string, timeout?: number): Promise<string>;
     /** Log out, so no session is left open on the console. */
     logout(): void;
 }
+/** One line for `circuit console`: what to send, the quiet that ends its answer, and the text the last answer must end with for the line to be sent. */
+export type ScriptLine = {
+    text: string;
+    quiet: number;
+    onlyAfter?: string;
+};
+/**
+ * Lines sent to a console one at a time, each answer read until the console goes quiet, as a person would type them.
+ *
+ * A line may start with `@if=TEXT=>`: it is sent only when the last answer ends with TEXT, for a prompt that may or may not come. Then, or alone, `@wait=N:` waits for N seconds of quiet instead of the usual 1.5, for a slow command.
+ */
+export declare class ConsoleScript {
+    /** The quiet that ends an answer, in milliseconds. */
+    static readonly QUIET = 1500;
+    /** A line as written, with `quiet` for a line that has no `@wait=`. */
+    static parse(line: string, quiet?: number): ScriptLine;
+    /** Send each line and hand each answer to `answered` as it comes. A line whose condition does not hold is skipped. */
+    static run(channel: Channel, lines: readonly string[], answered: (answer: string) => void, quiet?: number): Promise<void>;
+}
 export {};

package/dist/types/transport/path-check.d.ts

@@ -0,0 +1,32 @@
+/** 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 declare 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;
+    /** 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;
+    /**
+     * 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[];
+    /** 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;
+    /** Ping a host with the system's `ping`. Undefined when there is no `ping` to run. */
+    static measure(host: string): Promise<PathMeasure | undefined>;
+    /** 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;
+}

package/dist/types/transport/ssh.d.ts

@@ -8,18 +8,20 @@ export type Login = {
     /** Host key algorithms to accept, for a device that negotiates one it then signs wrongly. */
     hostKeys?: string[];
 };
-/** The address SSH reaches a device at. A device without one is reached only through its console. */
-export declare function managementHost(device: Device): string;
-/** Open a session. */
-export declare function connect(login: Login): Promise<Client>;
-/** Run one command and return what it printed, stderr included. */
-export declare function exec(client: Client, command: string, timeout?: number): Promise<string>;
-/** An interactive shell, for platforms that take configuration only there. */
-export declare function shell(client: Client, columns?: number, rows?: number): Promise<ClientChannel>;
-/** Collect output until `done` holds, then wait `settle` for stragglers, or give up at `timeout`. */
-export declare function readUntil(channel: ClientChannel, done: (output: string) => boolean, timeout: number, settle?: number): Promise<string>;
-/** Send one line into an interactive shell and collect output until it goes quiet for `settle`. */
-export declare function send(channel: ClientChannel, line: string, timeout?: number, settle?: number): Promise<string>;
-export declare const sleep: (milliseconds: number) => Promise<unknown>;
-/** Write a file to the device over SFTP. */
-export declare function upload(client: Client, path: string, content: string | Buffer): Promise<void>;
+export declare class Ssh {
+    /** The address SSH reaches a device at. A device without one is reached only through its console. */
+    static hostOf(device: Device): string;
+    /** Open a session. */
+    static connect(login: Login): Promise<Client>;
+    /** Run one command and return what it printed, stderr included. */
+    static exec(client: Client, command: string, timeout?: number): Promise<string>;
+    /** An interactive shell, for platforms that take configuration only there. */
+    static shell(client: Client, columns?: number, rows?: number): Promise<ClientChannel>;
+    /** 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?: number): Promise<string>;
+    /** Send one line into an interactive shell and collect output until it goes quiet for `settle`. */
+    static send(channel: ClientChannel, line: string, timeout?: number, settle?: number): Promise<string>;
+    static sleep(milliseconds: number): Promise<unknown>;
+    /** Write a file to the device over SFTP. */
+    static upload(client: Client, path: string, content: string | Buffer): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.34.2",
+    "version": "0.35.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",
@@ -54,10 +54,10 @@
             "bun": "./src/index.ts",
             "default": "./dist/index.js"
         },
-        "./presets": {
-            "types": "./dist/types/presets/index.d.ts",
-            "bun": "./src/presets/index.ts",
-            "default": "./dist/presets/index.js"
+        "./helpers": {
+            "types": "./dist/types/helpers/index.d.ts",
+            "bun": "./src/helpers/index.ts",
+            "default": "./dist/helpers/index.js"
         }
     },
     "bin": {
@@ -88,22 +88,28 @@
         "docs:preview": "vitepress preview docs",
         "release": "bun scripts/release.ts",
         "prepare": "husky || true",
-        "prepack": "bun run build"
+        "prepack": "bun run build",
+        "check": "bun run typecheck && bun run test && bun run format:check && bun run docs:build && bun run build && node dist/cli/index.js validate --config templates/single-site/circuit.config.ts && node dist/cli/index.js validate --config templates/edge-router/circuit.config.ts && node dist/cli/index.js validate --config templates/colocation/circuit.config.ts",
+        "agents:setup": "npx -y skills experimental_install"
     },
     "dependencies": {
+        "@clack/prompts": "^1.8.1",
+        "@commander-js/extra-typings": "~14.0.0",
         "@types/ssh2": "^1.15.6",
+        "commander": "~14.0.3",
         "jiti": "^2.7.0",
-        "ssh2": "^1.17.0"
+        "ssh2": "^1.17.0",
+        "yaml": "^2.9.1"
     },
     "devDependencies": {
-        "@commitlint/cli": "^19.8.1",
-        "@commitlint/config-conventional": "^19.8.1",
-        "@types/bun": "^1.4.2",
+        "@commitlint/cli": "^21.2.4",
+        "@commitlint/config-conventional": "^21.2.4",
+        "@types/bun": "^1.4.4",
         "@types/node": "^24.19.2",
         "husky": "^9.1.7",
         "prettier": "^3.9.10",
         "typescript": "^7.0.2",
         "vitepress": "^1.6.4"
     },
-    "packageManager": "bun@1.4.3"
+    "packageManager": "bun@1.4.4"
 }

package/src/cli/graph-format.ts

@@ -0,0 +1,91 @@
+// 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 { Topology, type Annotated, type GraphNode } from "../core/topology";
+
+export class GraphFormat {
+    /** `error` when validate found an error on the device, `warning` for a warning or a difference from its snapshot. */
+    static mark(graph: Annotated, node: GraphNode): "error" | "warning" | undefined {
+        if (node.kind !== "device") return undefined;
+
+        const findings = graph.findings.filter((finding) => finding.device && Topology.deviceId(finding.device) === node.id);
+        if (findings.some((finding) => finding.level === "error")) return "error";
+
+        const drift = graph.drift[node.label]?.status;
+        if (findings.length || drift === "differs" || drift === "cannot plan") return "warning";
+
+        return undefined;
+    }
+
+    /** Mermaid, which GitHub draws wherever Markdown is shown. */
+    static mermaid(graph: Annotated): string {
+        const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
+        // Lines of text, each escaped, as one quoted label.
+        const text = (...lines: string[]) =>
+            `"${lines.map((line) => line.replace(/"/g, "#quot;").replace(/</g, "#lt;").replace(/>/g, "#gt;")).join("<br/>")}"`;
+
+        const shapes: Record<GraphNode["kind"], (label: string) => string> = {
+            device: (label) => `[${label}]`,
+            segment: (label) => `([${label}])`,
+            outside: (label) => `{{${label}}}`,
+        };
+
+        const lines = ["graph LR"];
+
+        for (const node of graph.nodes) {
+            const label = node.kind === "device" ? text(node.label, node.detail[0] ?? "") : text(node.label);
+            lines.push(`    ${ids.get(node.id)}${shapes[node.kind](label)}`);
+        }
+
+        for (const edge of graph.edges) {
+            const arrow = edge.oneSided ? "-.-" : "---";
+            lines.push(`    ${ids.get(edge.from)} ${arrow}|${text(edge.label)}| ${ids.get(edge.to)}`);
+        }
+
+        lines.push(
+            "    classDef error stroke:#d1242f,stroke-width:3px",
+            "    classDef warning stroke:#bf8700,stroke-width:3px",
+            "    classDef outside stroke-dasharray:4 3"
+        );
+
+        for (const node of graph.nodes) {
+            const mark = GraphFormat.mark(graph, node) ?? (node.kind === "outside" ? "outside" : undefined);
+            if (mark) lines.push(`    class ${ids.get(node.id)} ${mark}`);
+        }
+
+        return lines.join("\n") + "\n";
+    }
+
+    /** DOT, which Graphviz turns into an image: `circuit graph --format=dot | dot -Tsvg > network.svg`. */
+    static dot(graph: Annotated): string {
+        const text = (value: string) => `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+        const colors = { error: "#d1242f", warning: "#bf8700" };
+
+        const shapes: Record<GraphNode["kind"], string> = {
+            device: "shape=box, style=rounded",
+            segment: "shape=ellipse",
+            outside: "shape=box, style=dashed",
+        };
+
+        const lines = [
+            "graph network {",
+            "    rankdir=LR;",
+            '    node [fontname="Helvetica"];',
+            '    edge [fontname="Helvetica", fontsize=10];',
+        ];
+
+        for (const node of graph.nodes) {
+            const label = node.kind === "device" ? `${node.label}\n${node.detail[0] ?? ""}` : node.label;
+            const mark = GraphFormat.mark(graph, node);
+            const color = mark ? `, color=${text(colors[mark])}, penwidth=2` : "";
+            lines.push(`    ${text(node.id)} [label=${text(label)}, ${shapes[node.kind]}${color}];`);
+        }
+
+        for (const edge of graph.edges) {
+            const style = edge.oneSided ? ", style=dashed" : "";
+            lines.push(`    ${text(edge.from)} -- ${text(edge.to)} [label=${text(edge.label)}${style}];`);
+        }
+
+        lines.push("}");
+        return lines.join("\n") + "\n";
+    }
+}