@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/README.md

@@ -1,62 +1,140 @@
-# Circuit
-
-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)
+<p align="center">
+    <a href="https://circuit.tako.id">
+        <picture>
+            <source media="(prefers-color-scheme: dark)" srcset="docs/public/logotype-dark.png">
+            <img src="docs/public/logotype.png" alt="Circuit" width="320">
+        </picture>
+    </a>
+</p>
+
+<p align="center"><b>Your network, written down.</b><br>One TypeScript file per device. Circuit shows what would change, then makes the device match.</p>
+
+<p align="center">
+    <a href="https://github.com/takodotid/circuit/actions/workflows/check.yml?query=branch%3Av1"><img src="https://github.com/takodotid/circuit/actions/workflows/check.yml/badge.svg?branch=v1" alt="check"></a>
+    <a href="https://github.com/takodotid/circuit/releases"><img src="https://img.shields.io/github/v/release/takodotid/circuit?include_prereleases&label=release&color=0a47b8" alt="release"></a>
+    <a href="https://www.npmjs.com/package/@takodotid/circuit"><img src="https://img.shields.io/npm/v/@takodotid/circuit?color=0a47b8" alt="npm"></a>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/license-BSL%201.1-0a47b8" alt="license"></a>
+    <a href="https://circuit.tako.id"><img src="https://img.shields.io/badge/docs-circuit.tako.id-f8e347" alt="docs"></a>
+</p>
+
+<p align="center">
+    <img src="https://img.shields.io/badge/MikroTik-RouterOS%207-0a1a36" alt="RouterOS 7">
+    <img src="https://img.shields.io/badge/Huawei-VRP-0a1a36" alt="VRP">
+    <img src="https://img.shields.io/badge/Raisecom-ROS-0a1a36" alt="Raisecom ROS">
+    <img src="https://img.shields.io/badge/Juniper-Junos-0a1a36" alt="Junos">
+    <img src="https://img.shields.io/badge/Fortinet-FortiOS-0a1a36" alt="FortiOS">
+</p>
+
+<p align="center">
+    <a href="https://circuit.tako.id/guide/install">Install</a> ·
+    <a href="https://circuit.tako.id/guide/introduction">Guide</a> ·
+    <a href="https://circuit.tako.id/academy/">Academy</a> ·
+    <a href="https://circuit.tako.id/studio/">Studio</a>
+</p>
 
 > [!WARNING]
-> 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.
+> Circuit v1 is not released yet. It is a rewrite of the config language, and every version is a release candidate, `1.0.0-rc.N`, until it is stable. The language, the model and the commands can still change between candidates. Circuit 0.x, the version in use today, is on the `main` branch.
 
 ## What it does
 
-- **One file per device.** VLANs, ports, addresses, routing, firewall, users and services in TypeScript. Your editor checks every name as you type.
+- **One file per device.** Ports, VLANs, addresses, routing, BGP, firewall, users and services, written as plain data. Your editor checks every name and every port as you type.
+- **Plain TypeScript, nothing to install.** A project imports nothing from Circuit. Circuit's functions are globals, and the editor reads its types from `.circuit/types`, which Circuit writes.
+- **One binary, nothing else to install.** `circuit` reads the project, checks what the editor can't, and talks to the devices.
 - **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.
+- **The file is the whole truth.** A port, user or service the file doesn't write is removed or turned off. Circuit fills in nothing you didn't write.
+- **See every change first.** `diff` and `apply` read the live device and show what would change; `apply` sends it only once you say yes.
+- **Secrets are encrypted.** Each value in `.circuit/secrets` is encrypted, so the file is committed; the one password that opens it stays out of git, in your password manager. A git hook stops a commit with a secret in plain text.
+
+## A device
+
+```ts
+// sites/site-a/switch-01.ts
+import { as64500 } from "../../circuit";
+import { site_a } from "./site";
+
+export default as64500.device({
+    name: "switch-01",
+    site: "site-a",
+    platform: "vrp",
+    model: "CE6855-48S6Q-HI",
+    connection: { host: "192.0.2.2", user: "netops" },
+    system: {
+        users: { netops: { role: "admin", password: secret("SWITCH_01_ADMIN_PASSWORD") } },
+    },
+    interfaces: {
+        ethernet: {
+            "10g-1": { description: "edge-01 sfp28-2", trunk_vlans: ["mgmt"], link: { device: "edge-01", port: "25g-2" } },
+        },
+        vlan_interface: {
+            mgmt: { vlan: "mgmt", addresses: [site_a.addresses.switch] },
+        },
+    },
+    switching: {
+        vlans: { mgmt: site_a.vlans.mgmt },
+    },
+});
+```
 
-<picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/public/screenshots/studio-dark.png">
-    <img src="docs/public/screenshots/studio-light.png" alt="Studio's VLAN graph with devices that differ from their snapshots marked by orange dashed borders, beside the layer details and legend.">
-</picture>
+In the editor, `"10g-49"` is an error, `10g-49 is not a port of CE6855-48S6Q-HI`, and so is `trunk_vlans: ["mgnt"]`: the device has no VLAN of that name. `circuit validate` says the same, with the file and line, and `Did you mean mgmt?`. [How to write a project](docs/guide/project.md) has the whole project: this switch in full, a router and a tenant.
 
-## Circuit Academy
+## Circuit Studio
 
-New to networking? [Circuit Academy](https://circuit.tako.id/academy/) teaches it from the very start, in lessons you try in the browser rather than only read: packets, addresses, switches and routers first, then VLANs, DHCP, NAT and firewalls written down in Circuit, BGP and an edge router of your own, and on to running a provider network. A certification is coming.
+`circuit studio` draws the network and lists everything in the project, in your browser.
 
 <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/public/screenshots/academy-dark.png">
-    <img src="docs/public/screenshots/academy-light.png" alt="A Circuit Academy lesson on switches: a frame from a laptop to a printer has just been flooded out of every port, and the switch has learned which port the laptop is behind.">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/public/screenshots/studio-dark.png">
+    <img src="docs/public/screenshots/studio-light.png" alt="Circuit Studio's graph of an example network, beside the layer's details.">
 </picture>
 
 ## Start
 
-You need [Node.js](https://nodejs.org) 22.12 or newer, or [Bun](https://bun.sh). Then:
-
-```bash
-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.
-
-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.
+1. Install Circuit. Circuit v1 is a release candidate, so its installers come from its GitHub release until circuit.tako.id serves v1:
+    - Linux and macOS: `curl -fsSL https://github.com/takodotid/circuit/releases/download/v1.0.0-rc.2/install | sh`
+    - Windows, in PowerShell: `irm https://github.com/takodotid/circuit/releases/download/v1.0.0-rc.2/install.ps1 | iex`
+2. Start a project: `circuit new network`. Open its folder in VS Code. Add a site in `circuit.ts`, then write each device in `sites/<site>/<device>.ts`.
+3. Run `circuit`. It opens a menu, or runs a command straight away, such as `circuit validate`.
+
+Each project runs the Circuit version in its `.circuit/version`. `circuit update` lists the newer versions, newest first, and moves the project to the one you pick. Circuit itself updates on its own, and a project on a version with a security problem has to move before anything runs.
+
+## Commands
+
+Each reads the project in the working directory or the nearest folder above it. Leave out the device and Circuit lists them to pick from.
+
+| Command                             | What it does                                                                                           |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `validate`                          | Reads the project and checks it, then runs every check in `circuit.ts`.                                |
+| `diff [device]`                     | Reads the device and shows what `apply` would change.                                                  |
+| `apply [device]`                    | Reads the device, shows what would change, and sends it once you say yes (`--confirm`).                |
+| `exec [device] [command...]`        | Runs commands that only read on the device, and prints the answer, secrets hidden.                     |
+| `bgp [device]`                      | Each BGP neighbor next to its live session: up or down, prefixes, uptime.                              |
+| `access-console [device] [line...]` | Opens the device's serial console, logged in, or sends it lines.                                       |
+| `studio`                            | Opens the project in your browser: the graph, every table, tools, compare and secrets.                 |
+| `rename [device] [new-name]`        | Gives a device a new name everywhere the project writes it, and its file too.                          |
+| `secrets`                           | Every secret in a text editor, saved encrypted; `list`, `get`, `set`, `delete`, `encrypt`, `password`. |
+| `fmt [file...]`                     | Tidies spacing and line breaks, as VS Code does on save. Nothing else changes.                         |
+| `new [folder]`                      | Starts a project.                                                                                      |
+| `update`                            | Pick a newer version for the project, newest first. Outside a project: Circuit's own.                  |
+| `uninstall`                         | Removes Circuit. Your projects stay.                                                                   |
+
+## Docs
+
+- [The documentation site](https://circuit.tako.id), whose pages are in `docs/`: install, writing a project, the `circuit` command, secrets, Studio, and Circuit Academy.
+- [How to write a project](docs/guide/project.md), then [rules](docs/guide/rules.md), [parts and merge](docs/guide/parts.md), [communities](docs/guide/communities.md) and [checks](docs/guide/checks.md).
+- [The model](docs/reference/model.md): what one device holds, and what Circuit resolves before a platform reads it.
+- [Decisions](design/decisions.md): what shaped v1, and why.
+- `src/config/`: every field, with its doc comment, which your editor shows on hover.
 
 ## Working on Circuit
 
 ```bash
 bun install
-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 docs:dev    # the documentation site, from docs/
+bun run check       # typecheck, tests, and the binary
+bun run build       # dist/circuit, or dist/circuit.exe on Windows
+cd <project> && bun <circuit>/src/cli/index.ts validate   # run Circuit from the sources
 ```
 
-[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.
+`AGENTS.md` has the rules for changing the code, for people and AI agents alike.
 
 ## 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 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).
+[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.

package/package.json

@@ -1,25 +1,7 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.43.1",
-    "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
-    "keywords": [
-        "network",
-        "network-automation",
-        "infrastructure-as-code",
-        "declarative",
-        "netops",
-        "bgp",
-        "routeros",
-        "mikrotik",
-        "vrp",
-        "huawei",
-        "raisecom",
-        "junos",
-        "juniper",
-        "fortios",
-        "fortinet",
-        "fortigate"
-    ],
+    "version": "1.0.0-rc.2",
+    "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. One binary, nothing to install.",
     "homepage": "https://circuit.tako.id",
     "bugs": {
         "url": "https://github.com/takodotid/circuit/issues",
@@ -48,68 +30,49 @@
         }
     ],
     "type": "module",
-    "exports": {
-        ".": {
-            "types": "./dist/types/index.d.ts",
-            "bun": "./src/index.ts",
-            "default": "./dist/index.js"
-        },
-        "./helpers": {
-            "types": "./dist/types/helpers/index.d.ts",
-            "bun": "./src/helpers/index.ts",
-            "default": "./dist/helpers/index.js"
-        }
-    },
     "bin": {
-        "circuit": "dist/cli/index.js"
+        "circuit": "src/cli/index.ts"
     },
     "files": [
         "src",
-        "dist",
-        "templates",
         "LICENSE",
         "README.md"
     ],
-    "engines": {
-        "node": ">=22.12",
-        "bun": ">=1.3.5"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
     "scripts": {
-        "typecheck": "bunx tsc --noEmit",
+        "typecheck": "bunx tsc --noEmit && bunx tsc --noEmit -p src/studio/app",
         "test": "bun test",
         "build": "bun scripts/build.ts",
+        "studio": "bun scripts/studio.ts",
         "format": "bunx prettier --write .",
         "format:check": "bunx prettier --check .",
-        "docs:dev": "bun scripts/schema-reference.ts && vitepress dev docs",
-        "docs:build": "bun scripts/schema-reference.ts && vitepress build docs",
-        "docs:preview": "vitepress preview docs",
-        "release": "bun scripts/release.ts",
-        "prepare": "husky || true",
-        "prepack": "bun run build",
-        "check": "bun run typecheck && bun run test && bun run format:check && bun run docs:build && bun run build && bunx tsc -p test/package && node dist/cli/index.js validate --config templates/single-site/circuit.config.ts && node dist/cli/index.js validate --config templates/edge-router/circuit.config.ts && node dist/cli/index.js validate --config templates/colocation/circuit.config.ts",
-        "agents:setup": "npx -y skills experimental_install"
+        "docs:dev": "bun install --cwd docs && bun run --cwd docs dev",
+        "docs:build": "bun install --cwd docs --frozen-lockfile && bun run --cwd docs build",
+        "docs:preview": "bun run --cwd docs preview",
+        "check": "bun run studio && bun run typecheck && bun run test && bun run format:check && bun run build",
+        "prepare": "bun run studio; husky || true"
     },
     "dependencies": {
-        "@clack/prompts": "^1.8.1",
+        "@clack/prompts": "1.8.1",
         "@commander-js/extra-typings": "~15.0.0",
-        "@types/ssh2": "^1.15.6",
         "commander": "~15.0.0",
-        "jiti": "^2.7.0",
-        "ssh2": "^1.17.0",
-        "yaml": "^2.9.1"
+        "prettier": "3.9.10",
+        "ssh2": "^1.17.0"
     },
     "devDependencies": {
         "@commitlint/cli": "^21.2.4",
         "@commitlint/config-conventional": "^21.2.4",
+        "@noble/ciphers": "1.3.0",
+        "@noble/hashes": "1.8.0",
         "@types/bun": "^1.4.4",
         "@types/node": "^24.19.2",
+        "@types/ssh2": "^1.15.6",
+        "@vitejs/plugin-vue": "6.0.10",
+        "cytoscape": "3.34.4",
         "husky": "^9.1.7",
-        "prettier": "^3.9.10",
         "typescript": "^7.0.2",
-        "vitepress": "^1.6.4"
+        "typescript-6": "npm:typescript@6.0.3",
+        "vite": "8.3.5",
+        "vue": "3.5.44"
     },
     "packageManager": "bun@1.4.4"
 }