@takodotid/circuit 0.34.3 → 0.35.0

package/dist/chunks/index-n7w3tg5y.js

@@ -0,0 +1,149 @@
+// src/core/address.ts
+class Address2 {
+  static 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"
+  ];
+  static family(address) {
+    return address.includes(":") ? "ipv6" : "ipv4";
+  }
+  static bits(family) {
+    return family === "ipv4" ? 32 : 128;
+  }
+  static toNumber(address) {
+    if (!address.includes(":")) {
+      const octets = address.split(".");
+      const valid = octets.length === 4 && octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255);
+      if (!valid)
+        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);
+  }
+  static split(cidr) {
+    const [address, lengthText] = cidr.split("/");
+    const family = Address2.family(address);
+    const length = Number(lengthText);
+    const valid = Address2.toNumber(address) !== null && lengthText !== undefined && Number.isInteger(length) && length >= 0 && length <= Address2.bits(family);
+    if (!valid)
+      throw new Error(`'${cidr}' is not an address with a length`);
+    return { addr: address, len: length, family };
+  }
+  static isValid(text) {
+    return Address2.toNumber(text) !== null;
+  }
+  static isCidr(text) {
+    try {
+      Address2.split(text);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  static mask(length, family) {
+    const all = (1n << BigInt(Address2.bits(family))) - 1n;
+    const hostBits = (1n << BigInt(Address2.bits(family) - length)) - 1n;
+    return all ^ hostBits;
+  }
+  static fromNumber(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}`;
+  }
+  static canonical(text) {
+    const [address, length] = text.split("/");
+    const value = Address2.toNumber(address);
+    if (value === null)
+      return text;
+    const spelled = Address2.fromNumber(value, Address2.family(address));
+    return length === undefined ? spelled : `${spelled}/${length}`;
+  }
+  static prefixOf(cidr) {
+    const { addr, len, family } = Address2.split(cidr);
+    return `${Address2.fromNumber(Address2.toNumber(addr) & Address2.mask(len, family), family)}/${len}`;
+  }
+  static contains(outer, inner) {
+    const outerParts = Address2.split(outer);
+    const [innerAddress, innerLengthText] = inner.split("/");
+    if (Address2.family(innerAddress) !== outerParts.family)
+      return false;
+    const innerLength = innerLengthText === undefined ? Address2.bits(outerParts.family) : Number(innerLengthText);
+    if (innerLength < outerParts.len)
+      return false;
+    const outerMask = Address2.mask(outerParts.len, outerParts.family);
+    return (Address2.toNumber(innerAddress) & outerMask) === (Address2.toNumber(outerParts.addr) & outerMask);
+  }
+  static range(cidr) {
+    const { addr, len, family } = Address2.split(cidr);
+    const hostBits = Address2.mask(len, family) ^ (1n << BigInt(Address2.bits(family))) - 1n;
+    const first = Address2.toNumber(addr) & Address2.mask(len, family);
+    return { first, last: first | hostBits, family };
+  }
+  static prefixesBetween(first, last, family) {
+    const bits = Address2.bits(family);
+    const prefixes = [];
+    for (let start = first;start <= last; ) {
+      let size = 0;
+      while (size < bits && start % (1n << BigInt(size + 1)) === 0n && start + (1n << BigInt(size + 1)) - 1n <= last)
+        size++;
+      prefixes.push(`${Address2.fromNumber(start, family)}/${bits - size}`);
+      start += 1n << BigInt(size);
+    }
+    return prefixes;
+  }
+  static netmask(length) {
+    return Address2.fromNumber(Address2.mask(length, "ipv4"), "ipv4");
+  }
+  static wildcard(length) {
+    return Address2.fromNumber(Address2.mask(length, "ipv4") ^ 0xffffffffn, "ipv4");
+  }
+  static host(cidr) {
+    return cidr.split("/")[0];
+  }
+  static isGlobal(address) {
+    if (Address2.family(address) === "ipv6")
+      return Address2.contains("2000::/3", address) && !Address2.contains("2001:db8::/32", address);
+    return !Address2.NOT_GLOBAL_V4.some((prefix) => Address2.contains(prefix, address));
+  }
+}
+
+export { Address2 };

package/dist/chunks/new-w3zys5y4.js

@@ -0,0 +1,172 @@
+// 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 { fileURLToPath } from "node:url";
+import * as prompts from "@clack/prompts";
+
+class Scaffold {
+  static ROOT = Scaffold.packageRoot();
+  static TEMPLATES = join(Scaffold.ROOT, "templates");
+  static CIRCUIT = JSON.parse(readFileSync(join(Scaffold.ROOT, "package.json"), "utf8"));
+  static 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" }
+  };
+  static 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
+    }
+  };
+  static EXAMPLE_ASN = "64500";
+  static 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;
+  }
+  static 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";
+  }
+  static fail(message) {
+    console.error(message);
+    process.exit(1);
+  }
+  static filesIn(directory) {
+    return readdirSync(directory, { recursive: true, withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)));
+  }
+  static notEmpty(directory) {
+    const target = resolve(process.cwd(), directory);
+    return existsSync(target) && readdirSync(target).length ? `${target} is not empty` : undefined;
+  }
+  static async ask(question, fallback) {
+    if (process.stdin.isTTY !== true)
+      return fallback;
+    const answer = await question();
+    if (prompts.isCancel(answer)) {
+      prompts.cancel("Nothing created.");
+      process.exit(1);
+    }
+    return answer;
+  }
+  static async create(directoryArgument, options) {
+    const directory = directoryArgument ?? await Scaffold.ask(() => prompts.text({
+      message: "Directory for the project",
+      placeholder: "my-network",
+      defaultValue: "my-network",
+      validate: (value) => Scaffold.notEmpty(value || "my-network")
+    }), "my-network");
+    const notEmpty = Scaffold.notEmpty(directory);
+    if (notEmpty)
+      Scaffold.fail(notEmpty);
+    const target = resolve(process.cwd(), directory);
+    const names = Object.keys(Scaffold.PATTERNS);
+    const pattern = options.pattern ?? await Scaffold.ask(() => prompts.select({
+      message: "Which is closest to your network?",
+      options: names.map((name) => ({
+        value: name,
+        label: Scaffold.PATTERNS[name].title,
+        hint: Scaffold.PATTERNS[name].fits
+      }))
+    }), names[0]);
+    if (!Object.hasOwn(Scaffold.PATTERNS, pattern))
+      Scaffold.fail(`no pattern ${pattern}; there are ${names.join(", ")}`);
+    const chosen = Scaffold.PATTERNS[pattern];
+    let asn = options.asn;
+    if (!asn && chosen.asn) {
+      asn = await Scaffold.ask(() => prompts.text({
+        message: "Your AS number, or press enter to keep the documentation example",
+        placeholder: Scaffold.EXAMPLE_ASN,
+        defaultValue: Scaffold.EXAMPLE_ASN,
+        validate: (value) => !value || /^\d+$/.test(value) ? undefined : `${value} is not an AS number`
+      }), Scaffold.EXAMPLE_ASN);
+    }
+    if (asn && !/^\d+$/.test(asn))
+      Scaffold.fail(`${asn} is not an AS number`);
+    const manager = options.use ?? Scaffold.detectManager();
+    if (!Object.hasOwn(Scaffold.MANAGERS, manager)) {
+      Scaffold.fail(`no package manager ${manager}; there are ${Object.keys(Scaffold.MANAGERS).join(", ")}`);
+    }
+    const { install, run, types } = Scaffold.MANAGERS[manager];
+    const onePassword = options.onePassword || await Scaffold.ask(() => prompts.confirm({ message: "Keep the secrets in 1Password?", initialValue: false }), false);
+    cpSync(join(Scaffold.TEMPLATES, pattern), target, { recursive: true });
+    cpSync(join(Scaffold.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 = Scaffold.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 !== Scaffold.EXAMPLE_ASN)
+        text = text.replaceAll(new RegExp(`\\b${Scaffold.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.",
+      "# Put quotes around a value that has a # in it: without them, # starts a comment.",
+      ...[...secrets].sort().map((name) => onePassword ? `${name}=op://Network/${name}/password` : `${name}=`),
+      ""
+    ];
+    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": Scaffold.CIRCUIT.version },
+      devDependencies: { [`@types/${types}`]: Scaffold.CIRCUIT.devDependencies[`@types/${types}`] }
+    };
+    writeFileSync(join(target, "package.json"), JSON.stringify(packageJson, null, 4) + `
+`);
+    if (options.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.",
+      ...chosen.asn && (!asn || asn === Scaffold.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 "${chosen.title}".
+
+Next:`);
+    steps.forEach((step, index) => console.log(`  ${index + 1}. ${step}`));
+    console.log(`
+What each file does: https://circuit.tako.id/patterns/${pattern}`);
+  }
+}
+export {
+  Scaffold
+};

package/dist/chunks/server-gzsf5me5.js

@@ -0,0 +1,259 @@
+import {
+  StudioModel
+} from "./index-2r4bbhac.js";
+
+// src/studio/server.ts
+import { execFile as execFile2, spawn } from "node:child_process";
+import { existsSync, readFileSync, watch } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join as join2 } from "node:path";
+
+// src/studio/git.ts
+import { execFile } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+class Git {
+  static FORMAT = "--format=%H%x1f%h%x1f%an%x1f%aI%x1f%s";
+  static environment() {
+    return Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith("GIT_")));
+  }
+  static run(cwd, args) {
+    return new Promise((done, fail) => {
+      execFile("git", args, { cwd, env: Git.environment(), maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error)
+          fail(new Error((stderr || error.message).trim()));
+        else
+          done(stdout);
+      });
+    });
+  }
+  static commitsOf(text) {
+    return text.split(`
+`).filter(Boolean).map((line) => {
+      const [commit = "", short = "", author = "", date = "", subject = ""] = line.split("\x1F");
+      return { commit, short, author, date, subject };
+    });
+  }
+  static async top(directory) {
+    try {
+      return (await Git.run(directory, ["rev-parse", "--show-toplevel"])).trim();
+    } catch {
+      return;
+    }
+  }
+  static async history(directory, files, limit = 50) {
+    if (!files.length)
+      return [];
+    return Git.commitsOf(await Git.run(directory, ["log", `-n${limit}`, Git.FORMAT, "--", ...files]));
+  }
+  static async references(directory) {
+    const names = (await Git.run(directory, [
+      "for-each-ref",
+      "--count=100",
+      "--sort=-committerdate",
+      "--format=%(refname:short)",
+      "refs/heads",
+      "refs/remotes",
+      "refs/tags"
+    ])).split(`
+`).filter((name) => name && !name.endsWith("/HEAD"));
+    return { names, commits: Git.commitsOf(await Git.run(directory, ["log", "-n30", Git.FORMAT])) };
+  }
+  static async commitOf(directory, name) {
+    if (!/^[A-Za-z0-9][\w./@^~-]*$/.test(name))
+      return;
+    try {
+      const [commit] = Git.commitsOf(await Git.run(directory, ["log", "-n1", Git.FORMAT, `${name}^{commit}`, "--"]));
+      return commit;
+    } catch {
+      return;
+    }
+  }
+  static async networkAt(configDirectory, configPath, commit, gather) {
+    const top = await Git.top(configDirectory);
+    if (!top)
+      throw new Error("the config is not in a git repository");
+    const cache = join(configDirectory, ".circuit", "cache");
+    mkdirSync(cache, { recursive: true });
+    writeFileSync(join(cache, ".gitignore"), `# Written by Circuit Studio: checkouts of other commits, removed once read.
+*
+`);
+    await Git.run(top, ["worktree", "prune"]);
+    const checkout = join(cache, commit.slice(0, 12));
+    await Git.run(top, ["-c", "core.longpaths=true", "worktree", "add", "--detach", "--force", checkout, commit]);
+    try {
+      const prefix = (await Git.run(configDirectory, ["rev-parse", "--show-prefix"])).trim();
+      return await gather(join(checkout, prefix, basename(configPath)));
+    } finally {
+      await Git.run(top, ["-c", "core.longpaths=true", "worktree", "remove", "--force", checkout]).catch(() => {});
+    }
+  }
+}
+
+// src/studio/server.ts
+class StudioServer {
+  static IGNORED = /(^|[\\/])(node_modules|\.git|\.circuit[\\/]cache)([\\/]|$)/;
+  static CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".woff2": "font/woff2"
+  };
+  static isLoopback(host) {
+    return host === "localhost" || host === "::1" || /^127\.\d+\.\d+\.\d+$/.test(host);
+  }
+  static hostAllowed(header, port, allowHosts) {
+    if (!header)
+      return false;
+    if (header === `127.0.0.1:${port}` || header === `localhost:${port}` || header === `[::1]:${port}`)
+      return true;
+    const name = header.replace(/:\d+$/, "").toLowerCase();
+    return allowHosts.some((allowed) => {
+      const wanted = allowed.toLowerCase();
+      return wanted === header.toLowerCase() || wanted === name;
+    });
+  }
+  static gather(configPath) {
+    const cli = process.argv[1];
+    const args = [...process.execArgv, cli, "studio", "--json", `--config=${configPath}`];
+    return new Promise((done) => {
+      execFile2(process.execPath, args, { maxBuffer: 256 * 1024 * 1024 }, (error, stdout, stderr) => {
+        if (!error)
+          return done(stdout);
+        const message = (stderr || error.message).trim();
+        done(JSON.stringify({ error: message }));
+      });
+    });
+  }
+  static openBrowser(url) {
+    const [command, args] = process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  }
+  static async start(options) {
+    const { configPath, root, port } = options;
+    const installed = StudioModel.packageRoot();
+    if (!installed)
+      throw new Error("cannot find where Circuit is installed, so Studio has no page to serve");
+    const pages = join2(installed, "src", "studio", "public");
+    let data = await StudioServer.gather(configPath);
+    const past = new Map;
+    const answer = async (response, work) => {
+      let body;
+      try {
+        const result = await work();
+        body = typeof result === "string" ? result : JSON.stringify(result);
+      } catch (error) {
+        body = JSON.stringify({ error: error.message });
+      }
+      response.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" }).end(body);
+    };
+    const listeners = new Set;
+    const tell = (message) => {
+      for (const listener of listeners)
+        listener.write(`data: ${message}
+
+`);
+    };
+    const server = createServer((request, response) => {
+      response.setHeader("x-robots-tag", "noindex, nofollow, noarchive");
+      if (!StudioServer.hostAllowed(request.headers.host, port, options.allowHosts)) {
+        response.writeHead(403).end();
+        return;
+      }
+      const url = new URL(request.url ?? "/", "http://studio");
+      const path = url.pathname;
+      if (path === "/history") {
+        answer(response, async () => {
+          const name = url.searchParams.get("device") ?? "";
+          const files = JSON.parse(data).files?.[name];
+          if (!files)
+            throw new Error(`no device ${name}`);
+          return Git.history(root, [files.source, files.snapshot].filter((file) => Boolean(file)));
+        });
+        return;
+      }
+      if (path === "/refs") {
+        answer(response, () => Git.references(root));
+        return;
+      }
+      if (path === "/compare") {
+        answer(response, async () => {
+          const asked = url.searchParams.get("ref") ?? "";
+          const commit = await Git.commitOf(root, asked);
+          if (!commit)
+            throw new Error(`${asked} names no commit here`);
+          if (!past.has(commit.commit))
+            past.set(commit.commit, Git.networkAt(root, configPath, commit.commit, StudioServer.gather));
+          const network = await past.get(commit.commit);
+          if (network.startsWith('{"error"'))
+            past.delete(commit.commit);
+          return `{"commit":${JSON.stringify(commit)},"network":${network}}`;
+        });
+        return;
+      }
+      if (path === "/robots.txt") {
+        response.writeHead(200, { "content-type": "text/plain; charset=utf-8" }).end(`User-agent: *
+Disallow: /
+`);
+        return;
+      }
+      if (path === "/data") {
+        response.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" }).end(data);
+        return;
+      }
+      if (path === "/events") {
+        response.writeHead(200, {
+          "content-type": "text/event-stream",
+          "cache-control": "no-store",
+          connection: "keep-alive",
+          "x-accel-buffering": "no"
+        });
+        response.write(`: connected
+
+`);
+        listeners.add(response);
+        request.on("close", () => listeners.delete(response));
+        return;
+      }
+      const name = path === "/" ? "index.html" : path.slice(1);
+      const type = StudioServer.CONTENT_TYPES[extname(name)];
+      const file = join2(pages, name);
+      if (!/^[a-z-]+\.[a-z0-9]+$/.test(name) || !type || !existsSync(file)) {
+        response.writeHead(404).end();
+        return;
+      }
+      response.writeHead(200, { "content-type": type, "cache-control": "no-store" }).end(readFileSync(file));
+    });
+    let timer;
+    watch(root, { recursive: true }, (_event, filename) => {
+      if (filename && StudioServer.IGNORED.test(filename))
+        return;
+      clearTimeout(timer);
+      timer = setTimeout(async () => {
+        data = await StudioServer.gather(configPath);
+        tell("changed");
+        console.log(`${new Date().toLocaleTimeString()}  ${filename ?? "a file"} changed, read again`);
+      }, 300);
+    });
+    watch(pages, () => tell("page"));
+    server.on("error", (error) => {
+      const message = error.code === "EADDRINUSE" ? `port ${port} is in use; choose another with --port=N` : error.message;
+      console.error(message);
+      process.exit(1);
+    });
+    server.listen(port, options.host, () => {
+      const local = StudioServer.isLoopback(options.host);
+      const url = local ? `http://127.0.0.1:${port}` : `http://${options.allowHosts[0] ?? options.host}`;
+      console.log(`Circuit Studio at ${url}, listening on ${options.host}:${port}, watching ${root}. Stop it with Ctrl+C.`);
+      if (options.open && local)
+        StudioServer.openBrowser(url);
+    });
+  }
+}
+export {
+  StudioServer
+};