@takodotid/circuit 0.6.0 → 0.8.0

package/README.md

@@ -1,195 +1,35 @@
 # 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.
+Write how each router and switch should be configured, in one TypeScript file per device. Circuit shows you what would change, then 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.
+> Circuit is in alpha. It runs a production network, but the way you write config, the commands and the supported devices can still change between releases. Install an exact version, and read the release notes before you upgrade.
 
-## Principles
+## Start
 
-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, or any file named with `--config <path>`:
-
-```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:
+You need [Bun](https://bun.sh). Then:
 
 ```bash
-cd circuit && bun link
-cd ../my-network && bun link @takodotid/circuit
+bunx @takodotid/circuit new
 ```
 
-`bun install` in the network's project returns it to the pinned release.
-
-## Adding a platform
+It asks which kind of network you have, creates a project with example devices, and installs Circuit. [Getting started](https://circuit.tako.id/guide/getting-started) walks through the first run.
 
-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.
+Circuit supports MikroTik RouterOS 7, Huawei VRP and Raisecom ROS. Releases are on the [releases page](https://github.com/takodotid/circuit/releases), on npm and on GitHub Packages.
 
-## 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
+## Working on Circuit
 
 ```bash
-bun run release patch | minor | major
-bun run release rc [patch | minor | major]
-bun run release stable
+bun install
+bun run typecheck
+bun run test        # every example and template validates, and plans nothing against its own render
+bun run docs:dev    # the documentation site, from docs/
 ```
 
-The script commits the version and pushes a tag; the tag publishes the package and a GitHub release.
+[Contributing](https://circuit.tako.id/contributing) explains the layout, how to add a platform, and how releases are cut. `AGENTS.md` has the rules for changing the code.
 
 ## 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.
+[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 from [legal@tako.id](mailto:legal@tako.id). Each version becomes Apache License 2.0 four years after it is published. See [License](https://circuit.tako.id/license).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.6.0",
+    "version": "0.8.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",
@@ -47,6 +47,7 @@
     },
     "files": [
         "src",
+        "templates",
         "LICENSE",
         "README.md"
     ],

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

@@ -874,12 +874,13 @@ export const RPKI_GROUP = "rpki";
 /** The chain a session without a policy uses, so that it learns or announces nothing. */
 export const REJECT_ALL = "REJECT-ALL";
 
+// RouterOS takes our own role. The config states the neighbor's, so each becomes its opposite: a neighbor that is our provider makes us its customer.
 const ROLES = {
-    provider: "ebgp-provider",
-    customer: "ebgp-customer",
+    provider: "ebgp-customer",
+    customer: "ebgp-provider",
     peer: "ebgp-peer",
-    rs: "ebgp-rs",
-    "rs-client": "ebgp-rs-client",
+    rs: "ebgp-rs-client",
+    "rs-client": "ebgp-rs",
 } as const;
 
 type AnyRule = PolicyRule<string, string>;
@@ -1097,7 +1098,7 @@ function bgpConnections(out: Output, ctx: Context): void {
         const addressFamily = familyOf(neighbor.address);
         const internal = settings.remote_as === bgp.asn;
         const originates = bgp.networks?.some((prefix) => familyOf(host(prefix)) === family);
-        const role = settings.local_role ? ROLES[settings.local_role] : internal ? "ibgp" : "ebgp";
+        const role = settings.role ? ROLES[settings.role] : internal ? "ibgp" : "ebgp";
 
         out.add(
             "/routing bgp connection",

package/src/adapters/registries/peeringdb.ts

@@ -56,8 +56,8 @@ function peersWithRouteServer(device: Device, iface: AnyInterface): boolean {
 
     return Object.values(bgp?.neighbors ?? {}).some((neighbor) => {
         const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
-        const role = neighbor.local_role ?? group?.local_role;
-        return role === "rs-client" && subnets.some((subnet) => contains(subnet, neighbor.address));
+        const role = neighbor.role ?? group?.role;
+        return role === "rs" && subnets.some((subnet) => contains(subnet, neighbor.address));
     });
 }
 

package/src/cli/index.ts

@@ -1,21 +1,22 @@
 #!/usr/bin/env bun
-// The command line. Loads `circuit.config.ts` from the working directory.
+// The command line. `new` starts a project; every other command loads the network from `circuit.config.ts` in the working directory, or the file `--config` names.
 
 import { createPrivateKey, createPublicKey } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import { adapters } from "../adapters/devices";
 import type { ApplyOptions, DeviceAdapter, Plan } from "../adapters/devices/types";
 import { registries } from "../adapters/registries";
 import { planPeeringDb, sendPeeringDb } from "../adapters/registries/peeringdb";
 import { network as prefixOf } from "../core/addr";
 import type { Network } from "../core/define";
-import { resolve as reveal } from "../core/secrets";
+import { isSecret, referenceOf, resolve as reveal, sourceOf, useRoot } from "../core/secrets";
 import { validate } from "../core/validate";
 import type { Device } from "../schema";
 
 const HELP = `usage: circuit <command> [device...] [options]
 
+  new [directory]       start a project from a pattern, asking what it needs
   validate              check the config, then every rule in checks
   build <device>        print the configuration the device should run, without contacting it
   diff [device...]      what apply would send, planned against the last snapshot, offline
@@ -28,6 +29,7 @@ const HELP = `usage: circuit <command> [device...] [options]
                         a client config for one peer, its private key left for the peer to fill
   communities           the network's BGP communities, one per line, for a looking glass or bgp.tools
   peeringdb             bring PeeringDB's exchange records in line with the config, with --confirm
+  secrets               every secret the config uses, and whether each can be read
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
 
@@ -35,6 +37,17 @@ const DEFAULT_CONFIG = "circuit.config.ts";
 
 const [command, ...args] = process.argv.slice(2);
 
+if (command === "new") {
+    const { create } = await import("./new");
+    await create(args);
+    process.exit(0);
+}
+
+if (!command || command === "help" || command === "--help" || command === "-h") {
+    console.log(HELP);
+    process.exit(0);
+}
+
 // `--config <path>` and `--config=<path>` both name the config file; neither is a device name.
 const configAt = args.indexOf("--config");
 const configArgument = configAt >= 0 ? args[configAt + 1] : args.find((arg) => arg.startsWith("--config="))?.slice("--config=".length);
@@ -49,8 +62,9 @@ if (!existsSync(configPath)) {
     process.exit(1);
 }
 
-/** The directory of the config file. The state directory is relative to it. */
+/** The directory of the config file. `.circuit/`, `.env` and secret files are found from here. */
 const root = dirname(configPath);
+useRoot(root);
 
 const network = (await import(configPath)).default as Network;
 
@@ -83,20 +97,22 @@ function one(): Device {
 }
 
 const adapterOf = (device: Device): DeviceAdapter => adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
-const stateDirectory = join(root, network.state);
+/** What Circuit writes, beside the config. */
+const generated = join(root, ".circuit");
+const stateDirectory = join(generated, "state");
 const statePath = (device: Device) => join(stateDirectory, device.name + adapterOf(device).extension);
 
-const STATE_README = `# Do not edit
+const GENERATED_README = `# Written by Circuit
 
-Written by \`circuit snapshot\` and \`circuit apply\`: what each device ran when it was last read, with secrets removed.
+Do not edit anything here: an edit changes nothing on a device, and Circuit overwrites it. Change the config instead.
 
-An edit here changes nothing on a device and is overwritten on the next read. Change the config instead.
+\`state/\` holds what each device ran when Circuit last read it, with secrets removed. \`circuit snapshot\` and \`circuit apply\` write it, and \`circuit diff\` plans against it. Commit it, so the history of this directory is the history of the network.
 `;
 
 /** Record what a device runs, beside a note that the directory is generated. */
 function writeState(device: Device, text: string): void {
     mkdirSync(stateDirectory, { recursive: true });
-    writeFileSync(join(stateDirectory, "README.md"), STATE_README);
+    writeFileSync(join(generated, "README.md"), GENERATED_README);
     writeFileSync(statePath(device), text);
 }
 
@@ -168,6 +184,17 @@ async function snapshotCommand(): Promise<void> {
         writeState(device, text);
         console.log(`${device.name}: ${text.split("\n").length} lines`);
     }
+
+    // With every device read, a snapshot of a device the config no longer has, such as one renamed, is removed.
+    if (names.length || !existsSync(stateDirectory)) return;
+
+    const current = new Set(network.devices.map((device) => basename(statePath(device))));
+    for (const file of readdirSync(stateDirectory)) {
+        if (current.has(file)) continue;
+
+        rmSync(join(stateDirectory, file));
+        console.log(`${file}: removed, no such device in the config`);
+    }
 }
 
 async function applyCommand(): Promise<void> {
@@ -290,6 +317,36 @@ async function peeringdbCommand(): Promise<void> {
     await sendPeeringDb(network, plan.changes);
 }
 
+/** Every secret reference in a value, however deep. */
+function secretsIn(value: unknown, found = new Set<string>()): Set<string> {
+    if (isSecret(value)) found.add(referenceOf(value));
+    else if (Array.isArray(value)) for (const item of value) secretsIn(item, found);
+    else if (typeof value === "object" && value !== null) for (const item of Object.values(value)) secretsIn(item, found);
+
+    return found;
+}
+
+function secretsCommand(): void {
+    const references = [...secretsIn([network.devices, network.peeringdb])].sort();
+    let missing = 0;
+
+    for (const reference of references) {
+        const name = reference.replace(/^file:/, "");
+
+        try {
+            reveal(reference);
+            console.log(`  ok       ${name}, from ${sourceOf(reference)}`);
+        } catch (error) {
+            missing++;
+            console.log(`  missing  ${name}: ${(error as Error).message}`);
+        }
+    }
+
+    console.log(`
+${references.length} secret(s), ${missing} missing.`);
+    process.exit(missing ? 1 : 0);
+}
+
 const commands: Record<string, () => void | Promise<void>> = {
     validate: validateCommand,
     build: buildCommand,
@@ -300,8 +357,12 @@ const commands: Record<string, () => void | Promise<void>> = {
     wireguard: wireguardCommand,
     communities: communitiesCommand,
     peeringdb: peeringdbCommand,
+    secrets: secretsCommand,
 };
 
-const run = commands[command ?? ""];
+const run = commands[command];
 if (run) await run();
-else console.log(HELP);
+else
+    fail(`no command ${command}
+
+${HELP}`);

package/src/cli/new.ts

@@ -0,0 +1,153 @@
+// `circuit new`: start a project from one of the patterns in templates/. In a terminal it asks what it needs; the same answers can be given as options, for a script or an AI agent.
+
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATES = fileURLToPath(new URL("../../templates", import.meta.url));
+const circuit = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+
+const PATTERNS = {
+    "single-site": { title: "A single site", fits: "a home, an office or an internal network: a router and a switch, no BGP", asn: false },
+    "edge-router": { title: "An edge router", fits: "your own AS number, with an IP transit and an internet exchange", asn: true },
+    colocation: {
+        title: "Colocation with tenants",
+        fits: "a provider whose customers each get their own VLANs, addresses and ports",
+        asn: true,
+    },
+} as const;
+
+type Pattern = keyof typeof PATTERNS;
+
+/** The AS number the templates use, reserved for documentation by RFC 5398. */
+const EXAMPLE_ASN = "64500";
+
+const USAGE = `usage: circuit new [directory] [options]
+
+  --pattern <name>   single-site, edge-router or colocation
+  --asn <number>     your AS number, for edge-router and colocation
+  --1password        write .env with 1Password references instead of empty values
+  --no-install       do not run bun install`;
+
+function fail(message: string): never {
+    console.error(message);
+    process.exit(1);
+}
+
+/** The value of `--name value` or `--name=value`. */
+function option(args: string[], name: string): string | undefined {
+    const at = args.indexOf(`--${name}`);
+    if (at >= 0) return args[at + 1];
+    return args.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+
+/** Every file under a directory, relative to it. */
+function filesIn(directory: string): string[] {
+    return readdirSync(directory, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => relative(directory, join(entry.parentPath, entry.name)));
+}
+
+export async function create(args: string[]): Promise<void> {
+    if (args.includes("--help") || args.includes("-h")) {
+        console.log(USAGE);
+        return;
+    }
+
+    const valued = new Set(["--pattern", "--asn"]);
+    const positional = args.filter((arg, index) => !arg.startsWith("--") && !valued.has(args[index - 1] ?? ""));
+
+    const interactive = process.stdin.isTTY === true;
+    const terminal = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+
+    // The answer typed, or the fallback when nothing is typed or nobody is there to type.
+    const ask = async (question: string, fallback: string) => {
+        if (!terminal) return fallback;
+        const answer = (await terminal.question(`${question} (${fallback}): `)).trim();
+        return answer || fallback;
+    };
+
+    const directory = positional[0] ?? (await ask("Directory for the project", "my-network"));
+    const target = resolve(process.cwd(), directory);
+    if (existsSync(target) && readdirSync(target).length) fail(`${target} is not empty`);
+
+    let pattern = option(args, "pattern") as Pattern | undefined;
+    if (!pattern) {
+        const names = Object.keys(PATTERNS) as Pattern[];
+        if (terminal) {
+            console.log("\nWhich is closest to your network?");
+            names.forEach((name, index) => console.log(`  ${index + 1}. ${PATTERNS[name].title}: ${PATTERNS[name].fits}`));
+        }
+        pattern = names[Number(await ask("Number", "1")) - 1];
+    }
+    if (!pattern || !(pattern in PATTERNS)) fail(`no pattern ${pattern}; there are ${Object.keys(PATTERNS).join(", ")}`);
+
+    let asn = option(args, "asn");
+    if (!asn && PATTERNS[pattern].asn) {
+        asn = await ask("Your AS number, or press enter to keep the documentation example", EXAMPLE_ASN);
+    }
+    if (asn && !/^\d+$/.test(asn)) fail(`${asn} is not an AS number`);
+
+    const onePassword =
+        args.includes("--1password") || (await ask("Keep the secrets in 1Password? y or n", "n")).toLowerCase().startsWith("y");
+    terminal?.close();
+
+    // The pattern's files, then what every project has. npm leaves out a file named .gitignore, so it travels without the dot.
+    cpSync(join(TEMPLATES, pattern), target, { recursive: true });
+    cpSync(join(TEMPLATES, "project"), target, { recursive: true });
+    renameSync(join(target, "gitignore"), join(target, ".gitignore"));
+
+    const sources = filesIn(target).filter((file) => file.endsWith(".ts"));
+    const secrets = new Set<string>();
+
+    for (const file of sources) {
+        const path = join(target, file);
+        let text = readFileSync(path, "utf8");
+
+        if (asn && asn !== EXAMPLE_ASN) text = text.replaceAll(new RegExp(`\\b${EXAMPLE_ASN}\\b`, "g"), asn);
+        for (const [, name] of text.matchAll(/secret\("([A-Z0-9_]+)"\)/g)) secrets.add(name!);
+
+        writeFileSync(path, text);
+    }
+
+    const env = [
+        "# Secrets for Circuit. Never commit this file.",
+        "# A value is the secret itself, or a 1Password reference, op://vault/item/field, read with the 1Password CLI.",
+        ...[...secrets].sort().map((name) => (onePassword ? `${name}=op://Network/${name}/password` : `${name}=`)),
+        "",
+    ];
+    writeFileSync(join(target, ".env"), env.join("\n"));
+
+    const name = basename(target)
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-");
+    const packageJson = {
+        name,
+        private: true,
+        type: "module",
+        dependencies: { "@takodotid/circuit": circuit.version },
+        devDependencies: { "@types/bun": circuit.devDependencies["@types/bun"] },
+    };
+    writeFileSync(join(target, "package.json"), JSON.stringify(packageJson, null, 4) + "\n");
+
+    if (!args.includes("--no-install")) {
+        const install = Bun.spawnSync(["bun", "install"], { cwd: target, stdout: "inherit", stderr: "inherit" });
+        if (install.exitCode !== 0) console.log("bun install failed; run it again in the project.");
+    }
+
+    const steps = [
+        `cd ${directory}`,
+        onePassword
+            ? "Point each line of .env at the item that holds it in 1Password, then run: bun circuit secrets"
+            : "Fill in each password in .env, then run: bun circuit secrets",
+        "Change the names, addresses and ports in the device files to your own.",
+        ...(PATTERNS[pattern].asn && (!asn || asn === EXAMPLE_ASN) ? ["Put your own AS number in routing.ts."] : []),
+        "bun circuit validate",
+        "bun circuit snapshot, then bun circuit diff, to see what would change on each device",
+    ];
+
+    console.log(`\nCreated ${directory} from the pattern "${PATTERNS[pattern].title}".\n\nNext:`);
+    steps.forEach((step, index) => console.log(`  ${index + 1}. ${step}`));
+    console.log(`\nWhat each file does: https://circuit.tako.id/patterns/${pattern}`);
+}

package/src/core/define.ts

@@ -1,10 +1,10 @@
 import type { ModelName, PlatformName, PortName } from "../adapters/devices/catalog";
 import type { Device, Secret } from "../schema";
 
-/** A value resolved by name when a device is applied, from the environment or `.env.local`. Never the value itself. */
+/** A value resolved by name when a device is applied, from the environment or `.env` beside the config, and through 1Password when that value is an `op://` reference. Never the value itself. */
 export const secret = (name: string): Secret => ({ secret: name });
 
-/** A value read from a file when a device is applied, such as a private key in PEM. The path is relative to the project root; keep the file out of git. */
+/** A value read from a file when a device is applied, such as a private key in PEM. The path is relative to the config file; keep the file out of git. */
 export const secretFile = (path: string): Secret => {
     if (!/^[A-Za-z0-9_./-]+$/.test(path)) throw new Error(`secret file path ${path} may hold only letters, digits, _ . / and -`);
     return { secret_file: path };
@@ -77,8 +77,6 @@ export type Network = {
     devices: readonly Device[];
     /** Rules of your own design. */
     checks?: readonly Check[];
-    /** Where snapshots of what each device runs are kept, relative to the config file. */
-    state: string;
     /** The AS the network operates, for what is published about it. */
     asn?: number;
     /** The BGP communities the network defines, printed by `circuit communities` for a looking glass or bgp.tools. */