@takodotid/circuit 0.4.3

package/LICENSE

@@ -0,0 +1,106 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             PT Hobimu Jadi Cuan
+Licensed Work:        Circuit. The Licensed Work is (c) 2026 PT Hobimu Jadi Cuan.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      that the Total Finances of you and your Affiliates do not
+                      exceed US$100,000 in the most recent twelve-month period.
+
+                      "Total Finances" means the larger of (a) the aggregate gross
+                      revenue and (b) the aggregate funds raised, including debt
+                      and equity, of you and your Affiliates.
+
+                      "Affiliates" means every entity that controls, is
+                      controlled by, or is under common control with you, where
+                      control means ownership of more than fifty percent of the
+                      voting interests.
+
+                      Production use beyond this grant needs a commercial license
+                      from the Licensor: legal@tako.id.
+Change Date:          Four years from the date the Licensed Work is published.
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact legal@tako.id.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Business Source License 1.1
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -0,0 +1,195 @@
+# Circuit
+
+Declarative, vendor-neutral network configuration. Describe each device in TypeScript, and Circuit renders it for the platform, compares it with what the device runs, and makes the device match.
+
+Documentation: [circuit.tako.id](https://circuit.tako.id)
+
+> [!WARNING]
+> Circuit is in alpha. It runs a production network, but it is not yet stable: the schema, the CLI and the adapters can still change in breaking ways between releases. Pin an exact version and read the release notes before upgrading.
+
+## Principles
+
+1. **The config is the whole truth.** Whatever a device runs that its config does not say is removed, or returned to its default. There are no exceptions and nothing is left alone.
+2. **Absent means off.** A field is written when it has a value. An undeclared port is shut down, an undeclared service is disabled, an undeclared feature is not running. There is no `enabled: false` and no placeholder.
+3. **Neutral words only.** The schema says `access_vlan`, `https`, `hardware_offload`. Each adapter translates, and a field a platform cannot express fails validation instead of being skipped.
+4. **Names are checked.** A device declares its VLANs, interfaces, policies and the rest; every reference to one is type-checked, so a typo does not compile and the editor suggests the names that exist. Port names come from the hardware model.
+5. **Secrets are references.** `secret("NAME")` is resolved from the environment or `.env.local`, and `secretFile("path")` from a file kept out of git, only when a command is sent. Rendered config, plans and snapshots never hold a secret.
+
+## Install
+
+Circuit runs on [Bun](https://bun.sh) and ships as TypeScript source, on npm and GitHub Packages.
+
+```bash
+bun add --exact @takodotid/circuit
+```
+
+Add `"net": "circuit"` to the project's `scripts` to run it as `bun net`. Every release is on the [releases page](https://github.com/takodotid/circuit/releases); release candidates are tagged `-rc.N` and published under the `rc` dist-tag.
+
+## A device
+
+```ts
+import { defineDevice, secret } from "@takodotid/circuit";
+
+export default defineDevice({
+    name: "sw1",
+    platform: "vrp",
+    model: "CE6855-48S6Q-HI",
+    connection: { host: "10.0.0.2", user: "operator" },
+    users: { operator: { role: "admin", password: secret("SW1_PASSWORD") } },
+    management: { allow: ["10.0.0.0/24"], ssh: {} },
+    vlans: { mgmt: { id: 99 }, servers: { id: 100 } },
+    ports: {
+        "10g-1": { description: "server-1", access_vlan: "servers" },
+        "40g-1": { description: "uplink", trunk_vlans: ["mgmt", "servers"] },
+    },
+    interfaces: { mgmt: { type: "vlan", vlan: "mgmt", addresses: ["10.0.0.2/24"] } },
+    routing: { static: [{ prefix: "0.0.0.0/0", via: "10.0.0.1" }] },
+});
+```
+
+Ports are named `<speed>-<position>`: `10g-1` is the first 10G cage. The model decides which exist; the adapter knows what the platform calls each one. Everything a device can hold is in `src/schema/`, with a comment on every field.
+
+A network is a list of devices in `circuit.config.ts` at the root of the project:
+
+```ts
+import { defineNetwork } from "@takodotid/circuit";
+
+export default defineNetwork({ devices: [sw1, r1], checks, state: "state" });
+```
+
+`checks` are rules of your own design, run by `validate` beside Circuit's. `state` is where device snapshots are kept, committed, so history shows what each device ran. The CLI writes a `README.md` there saying the directory is generated.
+
+Config is plain data. Shared values are ordinary imports, and anything repetitive can be a function; the result is still plain data.
+
+## Commands
+
+| Command                          | What it does                                                             | Touches a device       |
+| -------------------------------- | ------------------------------------------------------------------------ | ---------------------- |
+| `validate`                       | Checks the config and every rule in `checks`                             | no                     |
+| `build <device>`                 | Prints the whole configuration the device should run                     | no                     |
+| `diff [device...]`               | The plan against the last snapshot                                       | no                     |
+| `snapshot [device...]`           | Reads what each device runs into the state directory                     | reads                  |
+| `apply <device>`                 | Reads the device live and prints the plan; `--confirm` sends it          | yes, with `--confirm`  |
+| `refresh <device>`               | Fills prefix sets fetched from a registry; `--confirm` sends             | yes, with `--confirm`  |
+| `wireguard <device> <if> <peer>` | A client config for one peer, its private key left for the peer to fill  | no                     |
+| `communities`                    | The network's BGP communities, for a looking glass or bgp.tools          | no                     |
+| `peeringdb`                      | Brings PeeringDB's exchange records in line with the config; `--confirm` | PeeringDB, `--confirm` |
+
+`apply` also takes `--secrets`, to send every secret when rotating one, and `--rollback=N`, the minutes before a device that can restore itself does, 10 by default. Secrets cannot be read back, so without `--secrets` they are sent only when the object holding them is new.
+
+A change goes:
+
+1. Edit the device's file.
+2. `validate`, then `diff <device>` to see the change against the last snapshot.
+3. `apply <device>` and read every line of the plan. A `~ set` on a settings menu may turn something off.
+4. `apply <device> --confirm`.
+5. Commit the config with the snapshot `apply` wrote.
+
+## Publishing the network
+
+Some of the config describes the network to others rather than configuring a device. Devices ignore it.
+
+```ts
+interfaces: {
+    "ix-lan": {
+        type: "vlan",
+        vlan: "ix",
+        addresses: ["192.0.2.10/24", "2001:db8:1::10/64"],
+        exchange: { name: "Example IX", speed: 10_000, peeringdb_ixlan: 1234 },
+    },
+},
+```
+
+```ts
+export default defineNetwork({
+    devices,
+    state: "state",
+    asn: 64500,
+    communities: [{ community: "64500:0:nnn", description: "Do not announce to AS$0" }],
+    peeringdb: { api_key: secret("PEERINGDB_API_KEY") },
+});
+```
+
+`peeringdb` compares every interface with a `peeringdb_ixlan` against PeeringDB's records for `asn`: speed, the interface's globally reachable addresses, and whether a BGP neighbor on it is a route server. A record PeeringDB holds that the config does not is reported, never deleted.
+
+`communities` prints one per line, `community,description`, in the format the NLNOG Ring looking glass defines and bgp.tools reads: `nnn` is any number, `x` one digit, `a-b` a range, and `$0`, `$1` in the description are what each wildcard matched.
+
+## How a device is converged
+
+Each adapter guards the apply its platform allows:
+
+| Platform       | Commit                     | If it goes wrong                                                          |
+| -------------- | -------------------------- | ------------------------------------------------------------------------- |
+| `routeros`     | each command as sent       | backup saved, a scheduler restores it unless a fresh login disarms it     |
+| `vrp`          | `commit`, then `save`      | nothing applies until commit; save only after a fresh login proves access |
+| `raisecom-ros` | each command, then `write` | write only after a fresh login proves access                              |
+
+Plans run in two phases: additions and changes in dependency order, then removals in reverse, so nothing is removed while something still uses it. An ordered list such as a firewall chain is replaced whole, the old rules deciding until the new ones are in place.
+
+## Platforms
+
+`src/adapters/devices/<platform>/` holds the model catalog, the renderer, the reader and the apply. `TRAPS.md` beside each lists the platform behaviour it works around.
+
+Not every platform can express every field. What one cannot is reported by `validate`, never skipped:
+
+| Feature                                   | routeros              | vrp                   | raisecom-ros            |
+| ----------------------------------------- | --------------------- | --------------------- | ----------------------- |
+| VLANs, access and trunk ports, links      | yes                   | yes                   | yes                     |
+| Per-port STP, storm control, LLDP         | yes, storm in percent | yes, storm in percent | off only, broadcast pps |
+| LAGs                                      | yes                   | yes                   | yes                     |
+| Routed ports, loopbacks, tunnels          | yes                   | VLAN interfaces only  | VLAN interfaces only    |
+| VRRP, VRFs, DHCP relay                    | yes                   | IPv4                  | VRRP, IPv4              |
+| Static routes                             | yes                   | yes                   | IPv4 next hop           |
+| OSPF and BFD                              | yes                   | IPv4                  | OSPF, IPv4              |
+| BGP, policies, prefix sets, RPKI          | yes                   | no                    | no                      |
+| Firewall, NAT, hardware ACLs, DHCP server | yes                   | no                    | no                      |
+| Flow export                               | NetFlow 9, IPFIX      | sFlow                 | no                      |
+| SNMP                                      | v2c, v3 with SHA1     | v2c, v3               | v2c, v3 with SHA1       |
+| Certificates, web and API                 | yes                   | no                    | no                      |
+
+`examples/` holds a device per platform using every field its adapter supports. `bun run test` validates them and checks each plans nothing against its own render. Their commands were compiled on real devices without being run.
+
+## Versions
+
+An adapter renders for one major version of its platform and refuses another when it connects. `routeros` is RouterOS 7; RouterOS 6 has a different BGP and filter language and would be an adapter of its own. Within a major version, a property the device does not know is caught before anything is sent: RouterOS compiles every command first, and VRP stages them in a candidate that is cleared on the first refusal. A behaviour that differs between minor versions belongs in the adapter, with a note in its `TRAPS.md`.
+
+Circuit follows semantic versioning. A release is a git tag, `v<major>.<minor>.<patch>`.
+
+## Developing Circuit beside a network
+
+Link the working copy into the network's project, so a change here is live there without a release:
+
+```bash
+cd circuit && bun link
+cd ../my-network && bun link @takodotid/circuit
+```
+
+`bun install` in the network's project returns it to the pinned release.
+
+## Adding a platform
+
+1. `src/adapters/devices/<platform>/models.ts`: each model's ports per speed class and the platform's spelling.
+2. An adapter implementing `DeviceAdapter` in `src/adapters/devices/types.ts`. `lines.ts` converges block-structured configurations; `routeros/` shows a command-structured one.
+3. Register it in `src/adapters/devices/index.ts` and the catalog in `src/adapters/devices/catalog.ts`.
+4. `unsupported()` lists every field it cannot express. Silence is not an option.
+5. An example in `examples/` using every field it supports.
+
+## Documentation site
+
+`docs/` is the site at [circuit.tako.id](https://circuit.tako.id), built with VitePress: `bun run docs:dev` serves it locally. It is not part of the package.
+
+## Releases
+
+```bash
+bun run release patch | minor | major
+bun run release rc [patch | minor | major]
+bun run release stable
+```
+
+The script commits the version and pushes a tag; the tag publishes the package and a GitHub release.
+
+## License
+
+[Business Source License 1.1](LICENSE). Free in production for an organization whose yearly revenue and funding, with its affiliates, are each under US$100,000; above that, production use needs a commercial license: [legal@tako.id](mailto:legal@tako.id). Each version becomes Apache License 2.0 four years after it is published.
+
+Maintained by the Tako Network Engineering Team. Copyright 2026 PT Hobimu Jadi Cuan.

package/package.json

@@ -0,0 +1,83 @@
+{
+    "name": "@takodotid/circuit",
+    "version": "0.4.3",
+    "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
+    "keywords": [
+        "network",
+        "network-automation",
+        "infrastructure-as-code",
+        "declarative",
+        "netops",
+        "bgp",
+        "routeros",
+        "mikrotik",
+        "vrp",
+        "huawei",
+        "raisecom"
+    ],
+    "homepage": "https://circuit.tako.id",
+    "bugs": {
+        "url": "https://github.com/takodotid/circuit/issues",
+        "email": "noc@tako.id"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/takodotid/circuit.git"
+    },
+    "license": "BUSL-1.1",
+    "author": {
+        "name": "Tako Network Engineering Team",
+        "email": "noc@tako.id",
+        "url": "https://tako.id"
+    },
+    "contributors": [
+        {
+            "name": "Rafly Maulana",
+            "email": "rafly@tako.id",
+            "url": "https://raflymaulana.com"
+        }
+    ],
+    "type": "module",
+    "exports": {
+        ".": "./src/index.ts"
+    },
+    "bin": {
+        "circuit": "./src/cli/index.ts"
+    },
+    "files": [
+        "src",
+        "LICENSE",
+        "README.md"
+    ],
+    "engines": {
+        "bun": ">=1.3.5"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "typecheck": "bunx tsc --noEmit",
+        "test": "bun test",
+        "format": "bunx prettier --write .",
+        "format:check": "bunx prettier --check .",
+        "docs:dev": "bun scripts/schema-reference.ts && vitepress dev docs",
+        "docs:build": "bun scripts/schema-reference.ts && vitepress build docs",
+        "docs:preview": "vitepress preview docs",
+        "release": "bun scripts/release.ts",
+        "prepare": "husky || true"
+    },
+    "dependencies": {
+        "@types/ssh2": "^1.15.6",
+        "ssh2": "^1.17.0"
+    },
+    "devDependencies": {
+        "@commitlint/cli": "^19.5.0",
+        "@commitlint/config-conventional": "^19.5.0",
+        "@types/bun": "^1.4.2",
+        "husky": "^9.1.6",
+        "prettier": "^3.9.9",
+        "typescript": "^7.0.2",
+        "vitepress": "^1.6.4"
+    },
+    "packageManager": "bun@1.3.5"
+}

package/src/adapters/devices/catalog.ts

@@ -0,0 +1,38 @@
+// Every model each platform supports. Types read from here, so a model or port name that does not exist fails to compile.
+
+import { models as raisecom } from "./raisecom-ros/models";
+import { models as routeros } from "./routeros/models";
+import { models as vrp } from "./vrp/models";
+
+export const catalog = { routeros, vrp, "raisecom-ros": raisecom } as const;
+
+export type Catalog = typeof catalog;
+export type PlatformName = keyof Catalog;
+export type ModelName<Pl extends PlatformName> = keyof Catalog[Pl] & string;
+
+type Upto<N extends number, A extends unknown[] = [], R = never> = A["length"] extends N
+    ? R
+    : Upto<N, [...A, 0], R | `${[...A, 0]["length"]}`>;
+type PortsOf<Pl extends PlatformName, M extends ModelName<Pl>> = Catalog[Pl][M] extends { ports: infer P } ? P : never;
+
+/** `10g-1` to `10g-48` on a model with 48 10G ports. */
+export type PortName<Pl extends PlatformName, M extends ModelName<Pl>> = {
+    [S in keyof PortsOf<Pl, M>]: `${S & string}-${Upto<PortsOf<Pl, M>[S] & number>}`;
+}[keyof PortsOf<Pl, M>];
+
+/** Every port a model has, in order. */
+export function portsOf(platform: string, model: string): string[] {
+    const spec = (catalog as Record<string, Record<string, { ports: Record<string, number> }>>)[platform]?.[model];
+    if (!spec) throw new Error(`${platform} has no model ${model}`);
+    return Object.entries(spec.ports).flatMap(([speed, count]) => Array.from({ length: count }, (_, i) => `${speed}-${i + 1}`));
+}
+
+/** The platform's own name for a port. */
+export function spell(platform: string, model: string, port: string): string {
+    const spec = (catalog as Record<string, Record<string, { spelling: Record<string, string> }>>)[platform]?.[model];
+    const parts = /^(\d+[gm])-(\d+)$/.exec(port);
+    const template = parts && spec?.spelling[parts[1]!];
+    if (!template) throw new Error(`${model} has no port ${port}`);
+
+    return template.replace("{n}", parts[2]!);
+}

package/src/adapters/devices/derive.ts

@@ -0,0 +1,27 @@
+// Values more than one adapter derives from a device in the same way.
+
+import { familyOf, network } from "../../core/addr";
+import type { Device } from "../../schema";
+
+/** Each LAG's number: its own `id`, or its position among the device's LAGs. */
+export function lagIds(device: Device): Map<string, number> {
+    const numbers = new Map<string, number>();
+    let position = 0;
+
+    for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
+        if (iface.type !== "lag") continue;
+
+        position++;
+        numbers.set(name, iface.id ?? position);
+    }
+
+    return numbers;
+}
+
+/** The IPv4 networks of a port's or an interface's addresses. */
+export function ipv4Networks(device: Device, iface: string): string[] {
+    const settings = device.interfaces?.[iface] ?? device.ports?.[iface as keyof typeof device.ports];
+    const addresses = (settings?.addresses ?? []).map((entry) => (typeof entry === "string" ? entry : entry.address));
+
+    return addresses.filter((address) => familyOf(address) === "ipv4").map((address) => network(address));
+}

package/src/adapters/devices/index.ts

@@ -0,0 +1,7 @@
+import { raisecom } from "./raisecom-ros";
+import { routeros } from "./routeros";
+import type { DeviceAdapter } from "./types";
+import { vrp } from "./vrp";
+
+/** Every platform the framework can render and apply, by name. */
+export const adapters: Record<string, DeviceAdapter> = { routeros, vrp, "raisecom-ros": raisecom };

package/src/adapters/devices/lines.ts

@@ -0,0 +1,212 @@
+// Convergence for platforms whose configuration is a list of lines in nested blocks, such as `interface X` holding its settings. A line the render does not hold is undone, so the device ends up holding exactly the render.
+
+import type { Plan, Step } from "./types";
+
+export type Dialect = {
+    /** A line at the margin that opens a block, for platforms that do not indent a block's lines. */
+    block: RegExp;
+    /** Whether a block's lines are indented under it. When they are, any line followed by deeper lines opens a block. */
+    indented: boolean;
+    /** A line at the margin that closes every open block. */
+    terminator: string;
+    /** Lines that describe the device rather than configure it, or that the platform prints whatever is set. */
+    ignore: (line: string) => boolean;
+    /** The command that removes a line. */
+    undo: (line: string) => string;
+    /** Leaves one level of block. */
+    leave: string;
+    /** Lines sent before the undos of their block, because the platform refuses an undo until they are in place. */
+    first?: RegExp;
+    /** A line in the form both sides compare in, for example a secret the device prints as a cipher. */
+    canon?: (line: string) => string;
+    /** Where a block is sent among the others, lowest first, so that nothing is referenced before it exists. In the order they differ when absent. */
+    order?: (path: string[]) => number;
+};
+
+/** One line, with the blocks it sits in, outermost first. */
+export type Entry = { path: string[]; line: string };
+
+/** How deep a line is indented. */
+const indentOf = (raw: string) => raw.length - raw.trimStart().length;
+
+export function entries(text: string, dialect: Dialect): Entry[] {
+    const lines = text
+        .replace(/\r/g, "")
+        .split("\n")
+        .filter((raw) => raw.trim() !== "");
+    const result: Entry[] = [];
+    const open: { indent: number; header: string }[] = [];
+
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i]!;
+        const indent = indentOf(raw);
+        const line = raw.trim().replace(/\s+/g, " ");
+
+        if (line === dialect.terminator) {
+            if (indent === 0) open.length = 0;
+            continue;
+        }
+
+        if (dialect.ignore(line)) continue;
+
+        if (dialect.indented) {
+            while (open.length && open.at(-1)!.indent >= indent) open.pop();
+        } else if (indent === 0 && dialect.block.test(line)) {
+            open.length = 0;
+        }
+
+        result.push({ path: open.map((block) => block.header), line });
+
+        const isContent = (candidate: string) => candidate.trim() !== dialect.terminator && !dialect.ignore(candidate.trim());
+        const nextLine = lines.slice(i + 1).find(isContent);
+
+        const opensBlock = dialect.indented
+            ? nextLine !== undefined && indentOf(nextLine) > indent
+            : indent === 0 && dialect.block.test(line);
+
+        if (opensBlock) open.push({ indent, header: line });
+    }
+
+    return result;
+}
+
+/** The part of a line that names what it sets: `rule 5`, a free-text keyword, or the line up to its value. Two lines with one head are one setting with two values. */
+export function head(line: string): string {
+    const rule = /^rule \d+/.exec(line);
+    if (rule) return rule[0];
+
+    if (/^(description|name) /.test(line)) return line.split(" ")[0]!;
+
+    const words = line.split(" ");
+    return words.slice(0, Math.max(1, words.length - 1)).join(" ");
+}
+
+/** What changes inside one block. */
+export type Group = { path: string[]; remove: string[]; add: string[] };
+
+/**
+ * What differs, by block.
+ *
+ * A device line replaced by a desired line with the same head is not undone; sending the new one is enough. A block the render does not hold goes with its header, and its lines with it.
+ */
+export function compare(desired: string, current: string, dialect: Dialect): Group[] {
+    const canon = dialect.canon ?? ((line: string) => line);
+    const keyOf = (entry: Entry) => [...entry.path, canon(entry.line)].join("\u0000");
+    const pathKey = (path: string[]) => path.join("\u0000");
+
+    const wanted = entries(desired, dialect);
+    const existing = entries(current, dialect);
+    const wantedKeys = new Set(wanted.map(keyOf));
+    const existingKeys = new Set(existing.map(keyOf));
+    const wantedBlocks = new Set(wanted.map((entry) => pathKey([...entry.path, entry.line])));
+
+    const groups = new Map<string, Group>();
+    const groupFor = (path: string[]) => {
+        const key = pathKey(path);
+        if (!groups.has(key)) groups.set(key, { path, remove: [], add: [] });
+        return groups.get(key)!;
+    };
+
+    for (const entry of wanted) {
+        if (existingKeys.has(keyOf(entry))) continue;
+
+        // A header goes with its block's own step, never on its own.
+        const ownBlock = pathKey([...entry.path, entry.line]);
+        const opensBlock = wanted.some((other) => {
+            const deeper = other.path.length > entry.path.length;
+            return deeper && pathKey(other.path.slice(0, entry.path.length + 1)) === ownBlock;
+        });
+        if (opensBlock) continue;
+
+        groupFor(entry.path).add.push(entry.line);
+    }
+
+    // Undone in reverse order, so a line is undone before the line it depends on.
+    for (const entry of [...existing].reverse()) {
+        if (wantedKeys.has(keyOf(entry))) continue;
+
+        // Inside a block the render does not hold: undoing the header removes it.
+        const insideRemovedBlock = entry.path.some((_, depth) => {
+            const enclosing = pathKey(entry.path.slice(0, depth + 1));
+            return !wantedBlocks.has(enclosing);
+        });
+        if (insideRemovedBlock) continue;
+
+        const replaced = wanted.some((other) => {
+            const sameBlock = pathKey(other.path) === pathKey(entry.path);
+            const isNew = !existingKeys.has(keyOf(other));
+            return sameBlock && isNew && head(other.line) === head(entry.line);
+        });
+        if (!replaced) groupFor(entry.path).remove.push(entry.line);
+    }
+
+    return [...groups.values()].filter((group) => group.add.length || group.remove.length);
+}
+
+/**
+ * Replace a changed VLAN list line with only what changed.
+ *
+ * A platform keeps its VLANs as one line, such as `vlan batch 10 20 to 30`. Undoing the old line would delete VLANs still in use, so the plan adds the new IDs and removes the gone ones instead.
+ */
+export function vlanListChange(
+    groups: Group[],
+    prefix: string,
+    parse: (line: string) => number[],
+    format: (ids: number[]) => string[],
+    removal: (ids: number[]) => string[]
+): void {
+    const top = groups.find((group) => group.path.length === 0);
+    if (!top) return;
+
+    const old = top.remove.find((line) => line.startsWith(prefix));
+    const fresh = top.add.find((line) => line.startsWith(prefix));
+    if (!old && !fresh) return;
+
+    const before = old ? parse(old) : [];
+    const after = fresh ? parse(fresh) : [];
+
+    top.remove = top.remove.filter((line) => line !== old);
+    top.add = top.add.filter((line) => line !== fresh);
+
+    const added = after.filter((id) => !before.includes(id));
+    const removed = before.filter((id) => !after.includes(id));
+
+    // New VLANs exist before anything uses them; gone ones go after.
+    if (added.length) top.add.unshift(...format(added));
+    if (removed.length) top.remove.push(...removal(removed));
+}
+
+/** Commands a platform needs around one group, such as releasing a binding before a change and restoring it after. */
+export type Around = (group: Group) => { before: string[]; after: string[] };
+
+const nothingAround: Around = () => ({ before: [], after: [] });
+
+/** The steps for the groups: enter each block of the path, undo, add, then leave each level. */
+export function steps(groups: Group[], dialect: Dialect, around: Around = nothingAround): Plan["steps"] {
+    const rank = dialect.order ?? (() => 0);
+    const ordered = [...groups].sort((a, b) => rank(a.path) - rank(b.path));
+
+    return ordered.map((group): Step => {
+        const { before, after } = around(group);
+
+        const early = group.add.filter((line) => dialect.first?.test(line));
+        const late = group.add.filter((line) => !early.includes(line));
+
+        // A block header sent on its own, such as an empty `bfd`, enters its view; it is left at once so the next line is not sent into it.
+        const added = late.flatMap((line) => (dialect.block.test(line) ? [line, dialect.leave] : [line]));
+
+        const inner = [...early, ...group.remove.map(dialect.undo), ...added];
+        const leave = group.path.map(() => dialect.leave);
+
+        return {
+            title: group.path.join(" > ") || "(top level)",
+            show: [...group.remove.map((line) => `- ${line}`), ...group.add.map((line) => `+ ${line}`)],
+            send: [...before, ...group.path, ...inner, ...leave, ...after],
+        };
+    });
+}
+
+const STORED_CREDENTIAL = /(password (?:irreversible-)?cipher|community read cipher|^snmp-server community)( +)\S+/gm;
+
+/** A device prints stored credentials as ciphers. They never leave the read. */
+export const scrub = (text: string) => text.replace(STORED_CREDENTIAL, "$1$2<redacted>");