@takodotid/circuit 0.9.0 → 0.10.0

package/README.md

@@ -9,10 +9,10 @@ Documentation: [circuit.tako.id](https://circuit.tako.id)
 
 ## Start
 
-You need [Bun](https://bun.sh). Then:
+You need [Node.js](https://nodejs.org) 20.12 or newer, or [Bun](https://bun.sh). Then:
 
 ```bash
-bunx @takodotid/circuit new
+npx @takodotid/circuit new        # or: pnpm dlx @takodotid/circuit new, bunx @takodotid/circuit new
 ```
 
 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.
@@ -25,6 +25,7 @@ Circuit supports MikroTik RouterOS 7, Huawei VRP and Raisecom ROS. Releases are
 bun install
 bun run typecheck
 bun run test        # every example and template validates, and plans nothing against its own render
+bun run build       # dist/, what Node, npm and pnpm run
 bun run docs:dev    # the documentation site, from docs/
 ```
 

package/dist/chunks/index-ex1wcst7.js

@@ -0,0 +1,109 @@
+// src/core/addr.ts
+var familyOf = (address) => address.includes(":") ? "ipv6" : "ipv4";
+var bitsOf = (family) => family === "ipv4" ? 32 : 128;
+function parse(address) {
+  if (!address.includes(":")) {
+    const octets = address.split(".");
+    const valid2 = octets.length === 4 && octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255);
+    if (!valid2)
+      return null;
+    return octets.reduce((value, octet) => value << 8n | BigInt(octet), 0n);
+  }
+  const [before, after, extra] = address.split("::");
+  if (extra !== undefined)
+    return null;
+  const groupsOf = (text) => text ? text.split(":") : [];
+  const leading = groupsOf(before);
+  const trailing = groupsOf(after);
+  const zeros = after === undefined ? 0 : 8 - leading.length - trailing.length;
+  const groups = [...leading, ...Array(zeros).fill("0"), ...trailing];
+  const valid = groups.length === 8 && groups.every((group) => /^[0-9a-fA-F]{1,4}$/.test(group));
+  if (!valid)
+    return null;
+  return groups.reduce((value, group) => value << 16n | BigInt(parseInt(group, 16)), 0n);
+}
+function split(cidr) {
+  const [address, lengthText] = cidr.split("/");
+  const family = familyOf(address);
+  const length = Number(lengthText);
+  const valid = parse(address) !== null && lengthText !== undefined && Number.isInteger(length) && length >= 0 && length <= bitsOf(family);
+  if (!valid)
+    throw new Error(`'${cidr}' is not an address with a length`);
+  return { addr: address, len: length, family };
+}
+var isAddress = (text) => parse(text) !== null;
+function isCidr(text) {
+  try {
+    split(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var mask = (length, family) => {
+  const all = (1n << BigInt(bitsOf(family))) - 1n;
+  const hostBits = (1n << BigInt(bitsOf(family) - length)) - 1n;
+  return all ^ hostBits;
+};
+function format(value, family) {
+  if (family === "ipv4") {
+    return [24n, 16n, 8n, 0n].map((shift) => String(value >> shift & 255n)).join(".");
+  }
+  const groups = Array.from({ length: 8 }, (_, index) => (value >> BigInt(112 - index * 16) & 0xffffn).toString(16));
+  let longestStart = -1;
+  let longestLength = 0;
+  for (let start = 0;start < 8; ) {
+    let end = start;
+    while (end < 8 && groups[end] === "0")
+      end++;
+    const runLength = end - start;
+    if (runLength > longestLength && runLength > 1) {
+      longestStart = start;
+      longestLength = runLength;
+    }
+    start = end === start ? start + 1 : end;
+  }
+  if (longestStart < 0)
+    return groups.join(":");
+  const head = groups.slice(0, longestStart).join(":");
+  const tail = groups.slice(longestStart + longestLength).join(":");
+  return `${head}::${tail}`;
+}
+function network(cidr) {
+  const { addr, len, family } = split(cidr);
+  return `${format(parse(addr) & mask(len, family), family)}/${len}`;
+}
+function contains(outer, inner) {
+  const outerParts = split(outer);
+  const [innerAddress, innerLengthText] = inner.split("/");
+  if (familyOf(innerAddress) !== outerParts.family)
+    return false;
+  const innerLength = innerLengthText === undefined ? bitsOf(outerParts.family) : Number(innerLengthText);
+  if (innerLength < outerParts.len)
+    return false;
+  const outerMask = mask(outerParts.len, outerParts.family);
+  return (parse(innerAddress) & outerMask) === (parse(outerParts.addr) & outerMask);
+}
+var netmask = (length) => format(mask(length, "ipv4"), "ipv4");
+var wildcard = (length) => format(mask(length, "ipv4") ^ 0xffffffffn, "ipv4");
+var host = (cidr) => cidr.split("/")[0];
+var NOT_GLOBAL_V4 = [
+  "0.0.0.0/8",
+  "10.0.0.0/8",
+  "100.64.0.0/10",
+  "127.0.0.0/8",
+  "169.254.0.0/16",
+  "172.16.0.0/12",
+  "192.0.2.0/24",
+  "192.168.0.0/16",
+  "198.18.0.0/15",
+  "198.51.100.0/24",
+  "203.0.113.0/24"
+];
+function isGlobal(address) {
+  if (familyOf(address) === "ipv6")
+    return contains("2000::/3", address) && !contains("2001:db8::/32", address);
+  return !NOT_GLOBAL_V4.some((prefix) => contains(prefix, address));
+}
+
+export { familyOf, split, isAddress, isCidr, network, contains, netmask, wildcard, host, isGlobal };

package/dist/chunks/index-fq57hya4.js

@@ -0,0 +1,20 @@
+import { createRequire } from "node:module";
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __toESM = (mod, isNodeMode, target) => {
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: () => mod[key],
+        enumerable: true
+      });
+  return to;
+};
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+export { __toESM, __require };

package/dist/chunks/new-7n8qvtjd.js

@@ -0,0 +1,168 @@
+import"./index-fq57hya4.js";
+
+// src/cli/new.ts
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+function packageRoot() {
+  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;
+}
+var ROOT = packageRoot();
+var TEMPLATES = join(ROOT, "templates");
+var circuit = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8"));
+var 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" }
+};
+function detectManager() {
+  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";
+}
+var 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
+  }
+};
+var EXAMPLE_ASN = "64500";
+var 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
+  --use <manager>    npm, pnpm or bun; the one that ran this by default
+  --no-install       do not install the dependencies`;
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+function option(args, name) {
+  const at = args.indexOf(`--${name}`);
+  if (at >= 0)
+    return args[at + 1];
+  return args.find((arg) => arg.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+function filesIn(directory) {
+  return readdirSync(directory, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)));
+}
+async function create(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(USAGE);
+    return;
+  }
+  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;
+  const terminal = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+  const ask = async (question, fallback) => {
+    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");
+  if (!pattern) {
+    const names = Object.keys(PATTERNS);
+    if (terminal) {
+      console.log(`
+Which is closest to your network?`);
+      names.forEach((name2, index) => console.log(`  ${index + 1}. ${PATTERNS[name2].title}: ${PATTERNS[name2].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 manager = option(args, "use") ?? detectManager();
+  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();
+  cpSync(join(TEMPLATES, pattern), target, { recursive: true });
+  cpSync(join(TEMPLATES, "project"), target, { recursive: true });
+  renameSync(join(target, "gitignore"), join(target, ".gitignore"));
+  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;
+  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 [, name2] of text.matchAll(/secret\("([A-Z0-9_]+)"\)/g))
+      secrets.add(name2);
+    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((name2) => onePassword ? `${name2}=op://Network/${name2}/password` : `${name2}=`),
+    ""
+  ];
+  writeFileSync(join(target, ".env"), env.join(`
+`));
+  const name = basename(target).toLowerCase().replace(/[^a-z0-9-]+/g, "-");
+  const packageJson = {
+    name,
+    private: true,
+    type: "module",
+    dependencies: { "@takodotid/circuit": circuit.version },
+    devDependencies: { [`@types/${types}`]: circuit.devDependencies[`@types/${types}`] }
+  };
+  writeFileSync(join(target, "package.json"), JSON.stringify(packageJson, null, 4) + `
+`);
+  if (!args.includes("--no-install")) {
+    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: ${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."] : [],
+    `${run} validate`,
+    `${run} snapshot, then ${run} diff, to see what would change on each device`
+  ];
+  console.log(`
+Created ${directory} from the pattern "${PATTERNS[pattern].title}".
+
+Next:`);
+  steps.forEach((step, index) => console.log(`  ${index + 1}. ${step}`));
+  console.log(`
+What each file does: https://circuit.tako.id/patterns/${pattern}`);
+}
+export {
+  create
+};