@takodotid/circuit 0.34.3 → 0.35.0

package/README.md

@@ -9,16 +9,16 @@ Documentation: [circuit.tako.id](https://circuit.tako.id)
 
 ## What it does
 
-- **One file per device.** VLANs, ports, addresses, routing, firewall, users and services, written in TypeScript. Your editor checks every name you refer to as you type.
-- **The same words for every vendor.** MikroTik RouterOS 7, Huawei VRP, Raisecom ROS, Juniper Junos and Fortinet FortiOS each get their own commands. What a device cannot do is an error before anything is sent.
-- **The file is the whole truth.** A port, user or service the file does not mention is removed or turned off, so nothing set by hand stays behind.
-- **See every change first.** `diff` shows it offline, `apply` plans it against the live device, and nothing is sent without `--confirm`. On RouterOS, Junos and FortiOS, a change undoes itself if Circuit cannot log in again afterwards.
-- **History in git.** Each device's last snapshot is kept in `.circuit/state/`, so the repository's history is the network's history.
-- **Rules of your own.** Checks run on every change, and presets give ready-made filters, BGP policies and checks.
-- **Secrets stay out of the repository.** They come from `.env` or 1Password, and never appear in a plan or a snapshot.
-- **See the network.** Circuit Studio, started with `circuit studio`, draws the cables, VLANs, addresses, BGP sessions, OSPF neighbors and tunnels in your browser, and marks what is broken or differs from the device. Its tables list everything each device has, for anyone who does not read TypeScript, and it can run on a server for the whole team. `circuit graph` prints the drawing as Mermaid, DOT or JSON.
-- **Keeps the rest up to date.** Prefix lists fetched from a registry, your PeeringDB record, devices in LibreNMS, targets for Prometheus, WireGuard client configs, and your BGP communities for a looking glass.
-- **Safe with AI agents.** Every project gets an `AGENTS.md` that tells an agent what it may run, and the last step stays yours.
+- **One file per device.** VLANs, ports, addresses, routing, firewall, users and services in TypeScript. Your editor checks every name as you type.
+- **Same words for every vendor.** MikroTik RouterOS 7, Huawei VRP, Raisecom ROS, Juniper Junos and Fortinet FortiOS each get their own commands. Anything a device can't do is an error before anything is sent.
+- **The file is the whole truth.** A port, user or service the file doesn't mention is removed or turned off, so nothing set by hand stays behind.
+- **See every change first.** `diff` shows it offline, `apply` plans it against the live device, and nothing is sent without `--confirm`. On RouterOS, Junos and FortiOS a change undoes itself if Circuit can't log in again afterwards.
+- **History in git.** Each device's last snapshot lives in `.circuit/state/`, so the repo's history is the network's history.
+- **Your own rules.** Checks run on every change; helpers give ready-made filters, BGP policies and checks.
+- **Secrets stay out of the repo.** They come from `.env` or 1Password and never show up in a plan or a snapshot.
+- **See the network.** `circuit studio` draws cables, VLANs, addresses, BGP, OSPF and tunnels in your browser, marks what's broken or differs from the device, and lists everything in tables for people who don't read TypeScript. It can run on a server for the whole team. `circuit graph` prints the drawing as Mermaid, DOT or JSON.
+- **Keeps the rest in step.** Prefix lists from a registry, your PeeringDB record, LibreNMS, NetBox, Prometheus targets, WireGuard client configs, and your BGP communities for a looking glass.
+- **Safe with AI agents.** Every project gets an `AGENTS.md` that says what an agent may run; the last step stays yours.
 
 <picture>
     <source media="(prefers-color-scheme: dark)" srcset="docs/public/screenshots/studio-dark.png">
@@ -44,19 +44,18 @@ npx @takodotid/circuit new        # or: pnpm dlx @takodotid/circuit new, bunx @t
 
 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.
 
-Circuit supports MikroTik RouterOS 7, Huawei VRP, Raisecom ROS, Juniper Junos and Fortinet FortiOS. Releases are on the [releases page](https://github.com/takodotid/circuit/releases), on npm and on GitHub Packages.
+Circuit supports MikroTik RouterOS 7, Huawei VRP V200R005, Raisecom ROS 6.5, Juniper Junos 21 and Fortinet FortiOS 6.2, at the versions on the [platforms page](https://circuit.tako.id/platforms/). Releases are on the [releases page](https://github.com/takodotid/circuit/releases), on npm and on GitHub Packages.
 
 ## Working on Circuit
 
 ```bash
 bun install
-bun run typecheck
+bun run check       # everything CI runs: typecheck, tests, format, docs build, Node build
 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/
 ```
 
-[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.
+[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, for people and AI agents alike; `.claude/skills/` has the step-by-step guides an agent loads, such as adding a device.
 
 ## License
 

package/dist/chunks/index-20kcjxjg.js

@@ -0,0 +1,174 @@
+// src/core/utils.ts
+class Utils2 {
+  static merge(...records) {
+    const result = {};
+    for (const record of records) {
+      for (const [key, value] of Object.entries(record)) {
+        if (key in result)
+          throw new Error(`Utils.merge: ${key} is declared twice`);
+        result[key] = value;
+      }
+    }
+    return result;
+  }
+  static timeZoneOffset(zone) {
+    const name = new Intl.DateTimeFormat("en-US", {
+      timeZone: zone,
+      timeZoneName: "longOffset"
+    }).formatToParts(new Date).find((entry) => entry.type === "timeZoneName").value;
+    const found = /GMT([+-])(\d{2}):(\d{2})/.exec(name);
+    if (!found)
+      return 0;
+    const [, sign, hours, minutes] = found;
+    const sizeInMinutes = Number(hours) * 60 + Number(minutes);
+    return sign === "-" ? -sizeInMinutes : sizeInMinutes;
+  }
+}
+
+// src/core/secrets.ts
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseEnv } from "node:util";
+
+class Secrets2 {
+  static root = process.cwd();
+  static envFile;
+  static fromOnePassword = new Map;
+  static revealed = new Set;
+  static REDACTED = "<redacted>";
+  static SHORTEST_DOTENV_VALUE = 6;
+  static MARKER = /<secret:([A-Za-z0-9_./:-]+)>/g;
+  static useRoot(directory) {
+    Secrets2.root = directory;
+    Secrets2.envFile = undefined;
+  }
+  static dotenv() {
+    if (Secrets2.envFile)
+      return Secrets2.envFile;
+    const path = join(Secrets2.root, ".env");
+    const text = existsSync(path) ? readFileSync(path, "utf8") : "";
+    Secrets2.refuseCutValues(text);
+    Secrets2.envFile = parseEnv(text);
+    return Secrets2.envFile;
+  }
+  static refuseCutValues(text) {
+    for (const line of text.split(/\r?\n/)) {
+      const [, name, value] = /^\s*(?:export\s+)?([\w.-]+)\s*=\s*(.*)$/.exec(line) ?? [];
+      if (!name || !value || /^['"`]/.test(value) || !/\S#/.test(value))
+        continue;
+      throw new Error(`.env: the value of ${name} has a # in it, which starts a comment there; put the value in quotes`);
+    }
+  }
+  static readOnePassword(name, reference) {
+    const cached = Secrets2.fromOnePassword.get(reference);
+    if (cached !== undefined)
+      return cached;
+    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.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;
+    Secrets2.fromOnePassword.set(reference, value);
+    return value;
+  }
+  static isSecret(value) {
+    return typeof value === "object" && value !== null && (("secret" in value) || ("secret_file" in value));
+  }
+  static referenceOf(secret) {
+    return "secret" in secret ? secret.secret : `file:${secret.secret_file}`;
+  }
+  static sourceOf(reference) {
+    if (reference.startsWith("file:"))
+      return existsSync(join(Secrets2.root, reference.slice("file:".length))) ? "a file" : undefined;
+    const fromFile = Secrets2.dotenv()[reference];
+    const value = process.env[reference] || fromFile;
+    if (!value)
+      return;
+    const where = process.env[reference] && process.env[reference] !== fromFile ? "the environment" : ".env";
+    return value.startsWith("op://") ? `1Password, through ${where}` : where;
+  }
+  static valueOf(reference) {
+    if (reference.startsWith("file:")) {
+      const path = reference.slice("file:".length);
+      const fullPath = join(Secrets2.root, path);
+      if (!existsSync(fullPath))
+        throw new Error(`secret file ${path} does not exist`);
+      const value = readFileSync(fullPath, "utf8").trimEnd();
+      if (!value)
+        throw new Error(`secret file ${path} is empty`);
+      Secrets2.revealed.add(value);
+      return value;
+    }
+    const fromFile = Secrets2.dotenv()[reference];
+    const value = process.env[reference] || fromFile;
+    if (!value)
+      throw new Error(`secret ${reference} is not set in the environment or in .env`);
+    const revealed = value.startsWith("op://") ? Secrets2.readOnePassword(reference, value) : value;
+    Secrets2.revealed.add(revealed);
+    return revealed;
+  }
+  static reveal(secret) {
+    return Secrets2.valueOf(typeof secret === "string" ? secret : Secrets2.referenceOf(secret));
+  }
+  static referencesIn(value, found = new Set) {
+    if (Secrets2.isSecret(value))
+      found.add(Secrets2.referenceOf(value));
+    else if (Array.isArray(value))
+      for (const item of value)
+        Secrets2.referencesIn(item, found);
+    else if (typeof value === "object" && value !== null)
+      for (const item of Object.values(value))
+        Secrets2.referencesIn(item, found);
+    return found;
+  }
+  static scrub(text, options = {}) {
+    const values = new Set(options.extra ?? []);
+    for (const value of Object.values(Secrets2.dotenv())) {
+      if (value.length >= Secrets2.SHORTEST_DOTENV_VALUE && !value.startsWith("op://"))
+        values.add(value);
+    }
+    for (const value of Secrets2.revealed)
+      values.add(value);
+    for (const reference of Secrets2.referencesIn(options.network)) {
+      const value = Secrets2.storedValueOf(reference);
+      if (value)
+        values.add(value);
+    }
+    const ordered = [...values].filter(Boolean).sort((a, b) => b.length - a.length);
+    return ordered.reduce((out, value) => out.split(value).join(Secrets2.REDACTED), text);
+  }
+  static storedValueOf(reference) {
+    if (reference.startsWith("file:")) {
+      const path = join(Secrets2.root, reference.slice("file:".length));
+      return existsSync(path) ? readFileSync(path, "utf8").trimEnd() : undefined;
+    }
+    const value = process.env[reference] || Secrets2.dotenv()[reference];
+    if (!value?.startsWith("op://"))
+      return value;
+    return Secrets2.fromOnePassword.get(value);
+  }
+  static loginOf(device) {
+    const user = device.users?.[device.connection.user];
+    if (!user)
+      throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
+    return {
+      ...device.connection.host ? { host: device.connection.host } : {},
+      port: device.connection.port ?? 22,
+      user: device.connection.user,
+      password: Secrets2.reveal(user.password),
+      ...device.connection.console ? { console: device.connection.console } : {}
+    };
+  }
+  static marker(secret) {
+    return `<secret:${Secrets2.referenceOf(secret)}>`;
+  }
+  static substitute(text) {
+    return text.replace(Secrets2.MARKER, (_, reference) => Secrets2.valueOf(reference));
+  }
+}
+
+export { Utils2, Secrets2 };