@takodotid/circuit 0.9.0 → 0.11.0

package/src/cli/index.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 // 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";
@@ -66,7 +66,15 @@ if (!existsSync(configPath)) {
 const root = dirname(configPath);
 useRoot(root);
 
-const network = (await import(configPath)).default as Network;
+/** The config, a TypeScript file. Bun imports it as it is; Node needs jiti, which also resolves imports written without an extension. */
+async function load(path: string): Promise<Network> {
+    if (process.versions.bun) return (await import(path)).default;
+
+    const { createJiti } = await import("jiti");
+    return createJiti(import.meta.url).import(path, { default: true });
+}
+
+const network = await load(configPath);
 
 const flags = rest.filter((arg) => arg.startsWith("--"));
 const names = rest.filter((arg) => !arg.startsWith("--"));

package/src/cli/new.ts

@@ -1,12 +1,44 @@
 // `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 { spawnSync } from "node:child_process";
 import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { basename, join, relative, resolve } from "node:path";
+import { basename, dirname, 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"));
+/** Circuit's own directory: this file runs from src/cli/ in Bun, and from dist/ once built. */
+function packageRoot(): string {
+    let directory = dirname(fileURLToPath(import.meta.url));
+
+    while (!existsSync(join(directory, "templates"))) {
+        const parent = dirname(directory);
+        if (parent === directory) throw new Error("Circuit's templates are missing from its package");
+        directory = parent;
+    }
+
+    return directory;
+}
+
+const ROOT = packageRoot();
+const TEMPLATES = join(ROOT, "templates");
+const circuit = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+
+/** How each package manager installs and runs. The templates are written for npm; the others are swapped in. */
+const MANAGERS = {
+    npm: { install: "npm install", run: "npx circuit", types: "node" },
+    pnpm: { install: "pnpm install", run: "pnpm circuit", types: "node" },
+    bun: { install: "bun install", run: "bun circuit", types: "bun" },
+} as const;
+
+type Manager = keyof typeof MANAGERS;
+
+/** The package manager that started this, from what it says about itself, such as `pnpm/9.1.0 npm/? node/v22`. */
+function detectManager(): Manager {
+    const agent = process.env.npm_config_user_agent ?? "";
+    if (agent.startsWith("pnpm/")) return "pnpm";
+    if (agent.startsWith("bun/") || process.versions.bun) return "bun";
+    return "npm";
+}
 
 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 },
@@ -28,7 +60,8 @@ 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`;
+  --use <manager>    npm, pnpm or bun; the one that ran this by default
+  --no-install       do not install the dependencies`;
 
 function fail(message: string): never {
     console.error(message);
@@ -55,7 +88,7 @@ export async function create(args: string[]): Promise<void> {
         return;
     }
 
-    const valued = new Set(["--pattern", "--asn"]);
+    const valued = new Set(["--pattern", "--asn", "--use"]);
     const positional = args.filter((arg, index) => !arg.startsWith("--") && !valued.has(args[index - 1] ?? ""));
 
     const interactive = process.stdin.isTTY === true;
@@ -89,6 +122,10 @@ export async function create(args: string[]): Promise<void> {
     }
     if (asn && !/^\d+$/.test(asn)) fail(`${asn} is not an AS number`);
 
+    const manager = (option(args, "use") ?? detectManager()) as Manager;
+    if (!(manager in MANAGERS)) fail(`no package manager ${manager}; there are ${Object.keys(MANAGERS).join(", ")}`);
+    const { install, run, types } = MANAGERS[manager];
+
     const onePassword =
         args.includes("--1password") || (await ask("Keep the secrets in 1Password? y or n", "n")).toLowerCase().startsWith("y");
     terminal?.close();
@@ -98,6 +135,16 @@ export async function create(args: string[]): Promise<void> {
     cpSync(join(TEMPLATES, "project"), target, { recursive: true });
     renameSync(join(target, "gitignore"), join(target, ".gitignore"));
 
+    // What the templates say about npm, said for the package manager in use.
+    for (const file of ["AGENTS.md", "README.md", "tsconfig.json"]) {
+        const path = join(target, file);
+        const text = readFileSync(path, "utf8")
+            .replaceAll("npx circuit", run)
+            .replaceAll("npm install", install)
+            .replaceAll('"types": ["node"]', `"types": ["${types}"]`);
+        writeFileSync(path, text);
+    }
+
     const sources = filesIn(target).filter((file) => file.endsWith(".ts"));
     const secrets = new Set<string>();
 
@@ -127,24 +174,25 @@ export async function create(args: string[]): Promise<void> {
         private: true,
         type: "module",
         dependencies: { "@takodotid/circuit": circuit.version },
-        devDependencies: { "@types/bun": circuit.devDependencies["@types/bun"] },
+        devDependencies: { [`@types/${types}`]: circuit.devDependencies[`@types/${types}`] },
     };
     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.");
+        // npm and pnpm are scripts on Windows, which only a shell runs.
+        const result = spawnSync(install, { cwd: target, stdio: "inherit", shell: true });
+        if (result.status !== 0) console.log(`${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",
+            ? `Point each line of .env at the item that holds it in 1Password, then run: ${run} secrets`
+            : `Fill in each password in .env, then run: ${run} 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",
+        `${run} validate`,
+        `${run} snapshot, then ${run} diff, to see what would change on each device`,
     ];
 
     console.log(`\nCreated ${directory} from the pattern "${PATTERNS[pattern].title}".\n\nNext:`);

package/src/core/secrets.ts

@@ -1,5 +1,6 @@
 // Secrets are references in the config and values only at the moment a command is sent. A reference names a variable, set in the environment or in `.env` beside the config, or a file kept out of the repository. A variable's value may itself be a 1Password reference, `op://vault/item/field`, read with the 1Password CLI.
 
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { Secret } from "../schema";
@@ -44,19 +45,16 @@ function readOnePassword(name: string, reference: string): string {
     const cached = fromOnePassword.get(reference);
     if (cached !== undefined) return cached;
 
-    let result: ReturnType<typeof Bun.spawnSync>;
-    try {
-        result = Bun.spawnSync(["op", "read", "--no-newline", reference], { stdout: "pipe", stderr: "pipe" });
-    } catch {
-        throw new Error(`secret ${name} is a 1Password reference, and the 1Password CLI, op, is not installed`);
-    }
+    const result = spawnSync("op", ["read", "--no-newline", reference], { encoding: "utf8" });
+
+    if (result.error) throw new Error(`secret ${name} is a 1Password reference, and the 1Password CLI, op, is not installed`);
 
-    if (result.exitCode !== 0) {
-        const reason = result.stderr?.toString().trim() || `op exited with ${result.exitCode}`;
+    if (result.status !== 0) {
+        const reason = result.stderr.trim() || `op exited with ${result.status}`;
         throw new Error(`secret ${name}: 1Password could not read ${reference}: ${reason}`);
     }
 
-    const value = result.stdout?.toString() ?? "";
+    const value = result.stdout;
     fromOnePassword.set(reference, value);
     return value;
 }

package/src/presets/index.ts

@@ -239,7 +239,7 @@ const article = (word: string) => (/^[aeiou]/i.test(word) ? `an ${word}` : `a ${
  * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
  *
  * - `tag(neighborClass, neighborAs, { site, keepActions })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. `site` is needed when the scheme has `learned_at`. With `keepActions`, for a customer, its action communities stay.
- * - `actions(neighborAs)`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept.
+ * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
  * - `blackhole(prefixSet)`: a rule for a customer's import policy, before anything that rejects long prefixes. It takes a route the customer asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
@@ -286,8 +286,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
-    const actions = (neighborAs: number): PolicyRule<never, never>[] => [
-        ...(scheme.blackhole !== undefined
+    const actions = (neighborAs: number, options: { blackhole?: string } = {}): PolicyRule<never, never>[] => [
+        ...(scheme.blackhole !== undefined && !options.blackhole
             ? [
                   {
                       description: "Blackholed here, never announced",
@@ -310,6 +310,20 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
                   },
               ]
             : []),
+        ...(scheme.blackhole !== undefined && options.blackhole
+            ? [
+                  {
+                      description: `Blackhole passed on to AS${neighborAs}`,
+                      match: { large_community: community(scheme.blackhole, 0) },
+                      set: {
+                          remove_communities: ours.standard,
+                          remove_large_communities: ours.large,
+                          add_communities: [options.blackhole],
+                      },
+                      action: "accept" as const,
+                  },
+              ]
+            : []),
         ...PREPENDS.flatMap(([name, times]) => {
             const fn = scheme.prepend?.[name];
             if (fn === undefined) return [];

package/templates/project/AGENTS.md

@@ -18,21 +18,21 @@ What each field means is written as a comment on the field, in `node_modules/@ta
 
 | Command                                | What it does                                                         | Changes a device |
 | -------------------------------------- | -------------------------------------------------------------------- | ---------------- |
-| `bun circuit validate`                 | Checks every file and every rule in the checks                       | no               |
-| `bun circuit diff [device]`            | Shows what would change, compared with the last snapshot             | no               |
-| `bun circuit build <device>`           | Prints the full configuration the device should run                  | no               |
-| `bun circuit snapshot [device]`        | Reads what each device runs now into `.circuit/state/`               | no, only reads   |
-| `bun circuit apply <device>`           | Reads the device, then shows what would change on it                 | no               |
-| `bun circuit apply <device> --confirm` | Sends the change to the device                                       | **yes**          |
-| `bun circuit secrets`                  | Lists every secret the config uses, and whether each one can be read | no               |
+| `npx circuit validate`                 | Checks every file and every rule in the checks                       | no               |
+| `npx circuit diff [device]`            | Shows what would change, compared with the last snapshot             | no               |
+| `npx circuit build <device>`           | Prints the full configuration the device should run                  | no               |
+| `npx circuit snapshot [device]`        | Reads what each device runs now into `.circuit/state/`               | no, only reads   |
+| `npx circuit apply <device>`           | Reads the device, then shows what would change on it                 | no               |
+| `npx circuit apply <device> --confirm` | Sends the change to the device                                       | **yes**          |
+| `npx circuit secrets`                  | Lists every secret the config uses, and whether each one can be read | no               |
 
 ## Making a change
 
 1. Edit the device's file.
-2. Run `bun circuit validate`. Fix every error.
-3. Run `bun circuit diff <device>` and read the result.
+2. Run `npx circuit validate`. Fix every error.
+3. Run `npx circuit diff <device>` and read the result.
 4. Show the owner what will change and why, in plain words.
-5. Run `bun circuit apply <device>` to see the plan against the live device.
+5. Run `npx circuit apply <device>` to see the plan against the live device.
 6. **Stop.** Only run `apply <device> --confirm` after the owner says yes to that exact plan. Never confirm on your own, even if you were told to finish the task.
 7. After the apply, commit the device file together with the updated `.circuit/state/`.
 

package/templates/project/README.md

@@ -3,13 +3,13 @@
 This repository describes the network with [Circuit](https://circuit.tako.id). Each device has a file; Circuit makes the device match it.
 
 ```bash
-bun install                     # once
-bun circuit secrets             # check every secret can be read
-bun circuit validate            # check the files
-bun circuit snapshot            # read what each device runs now
-bun circuit diff                # see what would change
-bun circuit apply <device>      # see the plan against the device
-bun circuit apply <device> --confirm
+npm install                     # once
+npx circuit secrets             # check every secret can be read
+npx circuit validate            # check the files
+npx circuit snapshot            # read what each device runs now
+npx circuit diff                # see what would change
+npx circuit apply <device>      # see the plan against the device
+npx circuit apply <device> --confirm
 ```
 
 Secrets go in `.env`, which is never committed. `.circuit/` is written by Circuit; commit it, but never edit it.

package/templates/project/tsconfig.json

@@ -4,7 +4,7 @@
         "target": "ESNext",
         "module": "ESNext",
         "moduleResolution": "bundler",
-        "types": ["bun"],
+        "types": ["node"],
         "strict": true,
         "noEmit": true,
         "skipLibCheck": true,