@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/cli/secrets.ts

@@ -0,0 +1,258 @@
+// `circuit secrets`: a network's secrets file, each value encrypted. Alone, in a terminal, it opens the secrets to look through and change them; its commands list them, read one, set, delete, encrypt what was typed in plain text, and change the password.
+
+import { type SecretKind, OnePassword, SecretsFile } from "../core/secrets-file";
+import { Secrets } from "../core/secrets";
+import { ProjectError, readProject, secretsFileOf } from "../project/project";
+import { isAbsolute, normalize, relative, resolve, sep } from "node:path";
+import { ProjectCommands } from "./project-commands";
+import { Setup } from "./setup";
+import { SecretsPassword } from "./secrets-password";
+import { TextEditor } from "./text-editor";
+import { Ui } from "./ui";
+
+export class SecretCommands {
+    /** A name a secret can take: letters, digits and `_`, not starting with a digit. */
+    private static readonly NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+    private constructor(
+        readonly root: string,
+        private readonly file: SecretsFile,
+        /** The secrets the config names that live in this file. */
+        private readonly needed: readonly string[]
+    ) {}
+
+    /**
+     * The secrets file to work on: the one `--file` names, relative to where the command runs, or `.circuit/secrets`. A project whose
+     * networks keep their secrets elsewhere has to name the file. Reading the project says which secrets the config needs; a project
+     * that can't be read still works on the file named.
+     */
+    static async open(file: string | undefined): Promise<SecretCommands> {
+        const root = ProjectCommands.find() ?? Ui.fail("No Circuit project here: no circuit.ts in this folder or above it.");
+        Setup.prepare(root);
+        Secrets.useRoot(root);
+
+        const name = file === undefined ? SecretsFile.DEFAULT : SecretCommands.inProject(root, file);
+        const needed = new Set<string>();
+        try {
+            const read = await Ui.step("Reading the project", () => readProject(root));
+            const files = [...new Set(read.networks.map(secretsFileOf))].map(SecretCommands.normal);
+            const using = read.networks.filter((network) => SecretCommands.normal(secretsFileOf(network)) === SecretCommands.normal(name));
+
+            if (!using.length && files.length) {
+                if (file === undefined) Ui.fail(`This project keeps its secrets in ${files.join(", ")}. Name the file: --file ${files[0]}`);
+                Ui.warn(`No network uses ${name}. The project's secrets files: ${files.join(", ")}`);
+            }
+            for (const network of using)
+                for (const reference of Secrets.referencesIn([network.devices, network.settings.integrations])) needed.add(reference);
+        } catch (error) {
+            if (!(error instanceof ProjectError)) throw error;
+            Ui.warn("The project has errors, so this cannot say which secrets the config needs. Run circuit validate.");
+        }
+
+        Secrets.useFile(name);
+        return new SecretCommands(root, Secrets.file(), [...needed].filter((each) => !each.startsWith("file:")).sort());
+    }
+
+    /** A path as the project writes it: relative to its root, with forward slashes. */
+    private static normal(path: string): string {
+        return normalize(path).split(sep).join("/");
+    }
+
+    /** `--file`, given relative to where the command runs, as a path inside the project. */
+    private static inProject(root: string, file: string): string {
+        const path = relative(root, resolve(file));
+        if (!path || path.startsWith("..") || isAbsolute(path)) Ui.fail(`${file} is not inside the project, ${root}.`);
+        return SecretCommands.normal(path);
+    }
+
+    private static checkName(name: string): string {
+        if (!SecretCommands.NAME.test(name) || name === SecretsFile.PASSWORD)
+            Ui.fail(`${name} is not a name a secret can take: letters, digits and _, such as EDGE_01_PASSWORD.`);
+        return name;
+    }
+
+    private static describe(kind: SecretKind | "missing", value = ""): string {
+        if (kind === "encrypted") return Ui.green("encrypted");
+        if (kind === "1password") return `${Ui.green("1Password")}  ${Ui.dim(value)}`;
+        if (kind === "empty") return Ui.yellow("empty");
+        if (kind === "missing") return Ui.red("missing, the config needs it");
+        return Ui.red("NOT ENCRYPTED");
+    }
+
+    /** Every name, the ones the config needs but the file lacks too, each with how it is kept. */
+    private rows(): { name: string; kind: SecretKind | "missing"; value: string }[] {
+        const values = this.file.values();
+        const names = [...new Set([...this.file.names(), ...this.needed])].sort();
+        return names.map((name) => {
+            const value = values[name];
+            return value === undefined ? { name, kind: "missing", value: "" } : { name, kind: SecretsFile.kindOf(value), value };
+        });
+    }
+
+    private passwordLine(): string {
+        return `Password of ${this.file.name}: ${this.file.passwordLocation() ?? "typed when Circuit asks"}`;
+    }
+
+    /** Every secret, how it is kept, and the ones the config needs that the file lacks. Values are never shown. */
+    list(): void {
+        const rows = this.rows();
+
+        if (!rows.length) console.log(`No secrets yet. Add one with ${SecretsFile.command(this.file.name, "set NAME")}.`);
+        else
+            console.log(
+                Ui.table(
+                    [{ title: "Name" }, { title: "How it is kept" }],
+                    rows.map((row) => [
+                        row.name,
+                        process.env[row.name] ? Ui.dim("from the environment") : SecretCommands.describe(row.kind, row.value),
+                    ])
+                )
+            );
+
+        console.log(`\n${Ui.dim(this.passwordLine())}`);
+    }
+
+    /** Print one value, decrypted. */
+    async get(name: string | undefined): Promise<void> {
+        const chosen = name ?? Ui.fail("Name the secret, such as circuit secrets get EDGE_01_PASSWORD.");
+        if (!(chosen in this.file.values()) || chosen === SecretsFile.PASSWORD) Ui.fail(`${chosen} is not in ${this.file.name}.`);
+
+        if (SecretsFile.isEncrypted(this.file.values()[chosen]!)) await SecretsPassword.unlock(this.file);
+        try {
+            process.stdout.write(`${this.file.reveal(chosen)}\n`);
+        } catch (error) {
+            Ui.fail((error as Error).message);
+        }
+    }
+
+    /** Set a value, encrypted. A value not given is typed without showing it, so it stays out of the shell's history. */
+    async set(name: string | undefined, value: string | undefined): Promise<void> {
+        const chosen = SecretCommands.checkName(
+            name ?? (Ui.interactive ? await Ui.text("Name", { placeholder: "EDGE_01_PASSWORD" }) : Ui.fail("Name the secret."))
+        );
+        const given =
+            value ??
+            (Ui.interactive
+                ? await Ui.secret(`Value of ${chosen} (an op:// reference keeps it in 1Password)`)
+                : Ui.fail("Give the value."));
+
+        try {
+            if (!given.startsWith("op://")) await SecretsPassword.ready(this.file);
+            this.file.set(chosen, given);
+        } catch (error) {
+            Ui.fail((error as Error).message);
+        }
+
+        Ui.done(given.startsWith("op://") ? `${chosen} points at 1Password.` : `${chosen} is set, encrypted, in ${this.file.name}.`);
+    }
+
+    async delete(name: string | undefined, confirmed: boolean): Promise<void> {
+        const chosen = name ?? Ui.fail("Name the secret to delete.");
+        if (!(chosen in this.file.values()) || chosen === SecretsFile.PASSWORD) Ui.fail(`${chosen} is not in ${this.file.name}.`);
+
+        if (!confirmed) {
+            if (!Ui.interactive) Ui.fail("Not deleted. Without a person to answer, add --confirm.");
+            if (!(await Ui.confirm(`Delete ${chosen} from ${this.file.name}?`))) return;
+        }
+
+        this.file.remove(chosen);
+        Ui.done(`${chosen} is deleted.`);
+    }
+
+    /** Encrypt every value written in plain text, such as one typed into the file by hand. */
+    async encrypt(): Promise<void> {
+        if (!this.file.plaintext().length) {
+            Ui.done("Every value is already encrypted.");
+            return;
+        }
+
+        try {
+            await SecretsPassword.ready(this.file);
+            Ui.done(`Encrypted ${this.file.encryptAll().join(", ")}.`);
+        } catch (error) {
+            Ui.fail((error as Error).message);
+        }
+    }
+
+    /** Change the password, or say where Circuit reads it in 1Password, or stop reading it there. */
+    async password(flags: { onePassword?: string; forgetOnePassword?: boolean; confirm?: boolean }): Promise<void> {
+        if (flags.forgetOnePassword) {
+            this.file.setPasswordReference(undefined);
+            Ui.done(`Circuit no longer reads the password of ${this.file.name} from 1Password. It asks for it instead.`);
+            return;
+        }
+
+        if (flags.onePassword !== undefined) {
+            const reference = flags.onePassword;
+            if (!reference.startsWith("op://")) Ui.fail("Give a 1Password reference, op://vault/item/field.");
+
+            try {
+                const password = OnePassword.read(reference, "The password");
+                if (this.file.hasEncrypted()) this.file.unlock(password, reference);
+                this.file.setPasswordReference(reference);
+            } catch (error) {
+                Ui.fail((error as Error).message);
+            }
+            Ui.done(`Circuit reads the password of ${this.file.name} from ${reference}. Commit ${this.file.name}.`);
+            return;
+        }
+
+        if (!this.file.hasEncrypted()) {
+            await SecretsPassword.ready(this.file);
+            Ui.done(`${this.file.name} has its password. Add a secret with ${SecretsFile.command(this.file.name, "set NAME")}.`);
+            return;
+        }
+
+        if (!flags.confirm) {
+            if (!Ui.interactive) Ui.fail("Not changed. Without a person to answer, add --confirm.");
+            Ui.note(
+                "Every value is encrypted again with the new password, and the old one stops working.\nEveryone on the team needs the new one, unless it is kept in 1Password.\nThis changes no password on a device: to change one, set it with circuit secrets set, then apply.",
+                "Change the password"
+            );
+            if (!(await Ui.confirm("Change it now?"))) return;
+        }
+
+        await SecretsPassword.unlock(this.file);
+        const reference = this.file.values()[SecretsFile.PASSWORD];
+        const next = Ui.interactive
+            ? await SecretsPassword.choose(this.file, "the new password")
+            : process.env.CIRCUIT_SECRETS_NEW_PASSWORD;
+        if (!next) Ui.fail("Without a person to answer, give the new password in CIRCUIT_SECRETS_NEW_PASSWORD.");
+
+        try {
+            await Ui.step("Encrypting every value again", async () => this.file.changePassword(next));
+        } catch (error) {
+            Ui.fail((error as Error).message);
+        }
+
+        Ui.done(`Changed. Commit ${this.file.name}.`);
+        if (reference) Ui.warn(`Put the new password in 1Password at ${reference} now: it still holds the old one.`);
+    }
+
+    /** Every secret, decrypted, in a text editor on the whole screen: change, add or delete lines, Ctrl+S to save, each value encrypted again. Nothing is written to disk in plain text. */
+    async edit(): Promise<void> {
+        if (!Ui.interactive) Ui.fail(`The editor needs a terminal. Use ${SecretsFile.command(this.file.name, "set NAME")} instead.`);
+
+        try {
+            await SecretsPassword.ready(this.file);
+        } catch (error) {
+            Ui.fail((error as Error).message);
+        }
+
+        const missing = this.needed.filter((name) => !(name in this.file.values()));
+        await TextEditor.open({
+            title: `Secrets: ${this.file.name}`,
+            text: this.file.editable(),
+            ...(missing.length ? { note: `The config needs ${missing.join(", ")}: add a line NAME=value for each.` } : {}),
+            save: (edited) => {
+                try {
+                    return this.file.saveEditable(edited);
+                } catch (error) {
+                    return (error as Error).message;
+                }
+            },
+        });
+
+        Ui.done(`${this.file.name}: ${this.file.names().length} secret(s), each encrypted. Commit it.`);
+    }
+}

package/src/cli/setup.ts

@@ -0,0 +1,300 @@
+// A new project, started by the installer or from the menu: the folder, its files, git and its hook, and the editor's types. Also what Circuit keeps current in a project each time it runs in it.
+
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { SecretsFile } from "../core/secrets-file";
+import { EditorTypes } from "./editor-types";
+import { GitHooks } from "./git-hooks";
+import { Ui } from "./ui";
+import { Format } from "./format";
+import { VERSION } from "./version";
+import { Versions } from "./versions";
+
+export const GENERATED_README = `# Do not edit
+
+Circuit writes everything in this folder. Don't edit it by hand: change the project's own files, or use the command named below.
+
+- \`version\`: the Circuit version this project runs. \`circuit update\` changes it. (Not in a full install: \`package.json\` pins the version.)
+- \`secrets\`: the project's secrets, each value encrypted, so it is committed. Change them with \`circuit secrets\`.
+- \`types/\`: what your editor reads to complete and check the project's files. Written again on each update. (Not in a full install: the types come from the package in \`node_modules\`.)
+- \`hooks/\`: the git hook that checks each commit: every secret encrypted, and a project that validates.
+- \`cache/\`: temporary, ignored by git.
+`;
+
+/** The notice in `.circuit`. */
+export const NOTICE = "DO_NOT_EDIT.md";
+
+export const GITIGNORE = `node_modules/
+.circuit/cache/
+`;
+
+/** What a new project is set up with. */
+export type ProjectSetup = {
+    folder: string;
+    /** Simple: the binary alone. Full: Circuit as a package in the project, its version pinned in package.json. */
+    kind: "simple" | "full";
+    asn: number;
+    git: boolean;
+    openInEditor: boolean;
+};
+
+export class Setup {
+    /** The package a full install adds to the project. */
+    static readonly PACKAGE = "@takodotid/circuit";
+
+    private static installed(command: string): boolean {
+        return !spawnSync(command, ["--version"], { encoding: "utf8", shell: process.platform === "win32" }).error;
+    }
+
+    /** Circuit installed in the project as a package, by a full install: the file to run it from. */
+    static localCircuit(root: string): string | undefined {
+        const path = join(root, "node_modules", ...Setup.PACKAGE.split("/"), "src", "cli", "index.ts");
+        return existsSync(path) ? path : undefined;
+    }
+
+    /** What Circuit keeps current in a project, each time it runs in it: the editor's types, the git hook, and a warning for a secret in plain text. */
+    static prepare(root: string): void {
+        const full = Boolean(Setup.pinned(root));
+
+        // A full install's editor reads the types from the package in node_modules.
+        if (!full && !EditorTypes.current(root)) {
+            EditorTypes.write(root);
+            Ui.done(`Wrote the editor types for Circuit ${VERSION}.`);
+        }
+        Setup.writeNotice(root);
+
+        const hooks = GitHooks.install(root);
+        if (hooks) Ui.done(`${hooks[0]!.toUpperCase()}${hooks.slice(1)}.`);
+
+        if (!full && !Versions.pinned(root)) {
+            Versions.pin(root, VERSION);
+            Ui.done(`Pinned this project to Circuit ${VERSION} in ${Versions.FILE}. Commit it.`);
+        }
+
+        const plain = SecretsFile.at(root).plaintext();
+        if (plain.length)
+            Ui.warn(`${SecretsFile.DEFAULT} holds ${plain.join(", ")} in plain text. Run circuit secrets encrypt before you commit.`);
+    }
+
+    /** Ask how to set up a new project, then set it up. */
+    static async ask(folder?: string, chosen?: ProjectSetup["kind"]): Promise<ProjectSetup> {
+        Ui.intro("A new Circuit project");
+
+        const name =
+            folder ??
+            (await Ui.text("Project folder", {
+                // An empty folder takes the project itself; elsewhere, a new folder in it.
+                initial: readdirSync(process.cwd()).length ? "network" : ".",
+                check: (value) => {
+                    if (!value.trim()) return "Type a folder name.";
+                    const path = resolve(process.cwd(), value.trim());
+                    return existsSync(path) && readdirSync(path).length ? "That folder already holds files. Pick another." : undefined;
+                },
+            }));
+
+        const kind =
+            chosen ??
+            (await Ui.select<ProjectSetup["kind"]>("How should this project run Circuit?", [
+                { value: "simple", label: "Simple (recommended)", hint: "the circuit app, its version pinned in .circuit/version" },
+                { value: "full", label: "Full", hint: "Circuit as a package in the project, run with bun circuit" },
+            ]));
+
+        if (kind === "full") {
+            await Ui.select("Runtime", [
+                { value: "bun", label: "Bun (recommended)" },
+                { value: "node", label: "Node.js and npm", hint: "coming later", disabled: true },
+                { value: "deno", label: "Deno", hint: "coming later", disabled: true },
+            ]);
+            if (!Setup.installed("bun")) await Setup.offerBun();
+        }
+
+        const asn = Number(
+            await Ui.text("Your network's AS number", {
+                initial: "64500",
+                check: (value) => (/^\d+$/.test(value.trim()) ? undefined : "Type a number, such as 64500. Change it later in circuit.ts."),
+            })
+        );
+
+        let git = false;
+        if (GitHooks.gitInstalled()) git = await Ui.confirm("Start a git repository, so each change is kept and can be reviewed?", true);
+        else Ui.warn("git is not installed, so the project is not a git repository. Install git, then run git init in the folder.");
+
+        const openInEditor = Setup.installed("code") && (await Ui.confirm("Open the project in VS Code?", true));
+
+        return { folder: name.trim(), kind, asn, git, openInEditor };
+    }
+
+    /** Install Bun with its own installer, when the person agrees. */
+    private static async offerBun(): Promise<void> {
+        if (!(await Ui.confirm("Bun is not installed. Install it now, with Bun's own installer from bun.sh?", true))) {
+            Ui.fail("A full install needs Bun. Install it from https://bun.sh, or pick Simple.");
+        }
+
+        const windows = process.platform === "win32";
+        const result = windows
+            ? spawnSync("powershell", ["-NoProfile", "-Command", "irm bun.sh/install.ps1 | iex"], { stdio: "inherit" })
+            : spawnSync("sh", ["-c", "curl -fsSL https://bun.sh/install | bash"], { stdio: "inherit" });
+        if (result.status !== 0) Ui.fail("Bun's installer did not finish. Install Bun from https://bun.sh, then run this again.");
+    }
+
+    /** Write the project's files, then git, the package and the editor, as `setup` says. */
+    static async create(setup: ProjectSetup): Promise<string> {
+        const root = resolve(process.cwd(), setup.folder);
+
+        await Ui.step("Writing the project", async () => {
+            mkdirSync(join(root, "sites"), { recursive: true });
+            mkdirSync(join(root, "tenants"), { recursive: true });
+
+            writeFileSync(
+                join(root, "circuit.ts"),
+                `// The network: its AS, its sites, and the checks Circuit runs on it. Each device is a file under sites/<site>/.
+
+export const as${setup.asn} = circuit({
+    asn: ${setup.asn},
+    // Each site by its name, such as "jakarta-1": { description: "Jakarta, rack 12" }. Its devices go in sites/jakarta-1/.
+    sites: {},
+    checks: {
+        exports_end_in_reject: true,
+        imports_end_in_accept_or_reject: true,
+    },
+});
+`
+            );
+            writeFileSync(
+                join(root, "sites", "README.md"),
+                "One folder per site, named as in circuit.ts, with one file per device: sites/<site>/<device>.ts.\n"
+            );
+            writeFileSync(
+                join(root, "tenants", "README.md"),
+                "What tenants share with your devices, one file each, merged in `tenants/index.ts`.\n"
+            );
+            writeFileSync(join(root, ".gitignore"), GITIGNORE);
+            writeFileSync(join(root, "tsconfig.json"), setup.kind === "full" ? EditorTypes.TSCONFIG_FULL : EditorTypes.TSCONFIG);
+            Setup.writeEditor(root);
+            if (setup.kind === "simple") Versions.pin(root, VERSION);
+            if (setup.kind === "simple") EditorTypes.write(root);
+            Setup.writeNotice(root);
+
+            if (setup.kind === "full") {
+                writeFileSync(
+                    join(root, "package.json"),
+                    `${JSON.stringify({ name: setup.folder.toLowerCase().replace(/[^a-z0-9-]+/g, "-"), private: true, devDependencies: {} }, null, 4)}\n`
+                );
+            }
+        });
+
+        if (setup.kind === "full") {
+            await Ui.step(`Adding Circuit ${VERSION} to the project with Bun`, async () => {
+                const result = spawnSync("bun", ["add", "--dev", "--exact", `${Setup.PACKAGE}@${VERSION}`], {
+                    cwd: root,
+                    encoding: "utf8",
+                    shell: process.platform === "win32",
+                });
+                if (result.status !== 0) throw new Error(`bun add failed: ${(result.stderr || result.stdout).trim()}`);
+            });
+        }
+
+        if (setup.git) {
+            await Ui.step("Starting the git repository", async () => {
+                GitHooks.init(root);
+                GitHooks.install(root);
+            });
+        }
+
+        if (setup.openInEditor) spawn("code", [root], { detached: true, stdio: "ignore", shell: process.platform === "win32" }).unref();
+
+        return root;
+    }
+
+    /** The steps after a new project, for the person to follow. */
+    static nextSteps(root: string, setup: ProjectSetup): string {
+        const run = setup.kind === "full" ? "bun circuit" : "circuit";
+        return [
+            ...(setup.folder === "." ? [] : [`cd ${setup.folder}`]),
+            "Add a site in circuit.ts, then a device in sites/<site>/<device>.ts. Your editor completes each field.",
+            `${run} secrets          your secrets, such as a device password, each encrypted`,
+            `${run} validate         check the project`,
+            `${run} diff <device>    what would change on the device`,
+            `${run} apply <device>   make the device match`,
+            "",
+            `Read more at https://circuit.tako.id. Project: ${root}`,
+        ].join("\n");
+    }
+
+    /** The whole of a new project: ask, create, and say what is next. */
+    static async run(folder: string | undefined, options: { existing: "ready" | "refuse"; kind?: ProjectSetup["kind"] }): Promise<void> {
+        // In a project already, such as a fresh clone: set it up as it is, with no questions.
+        const here = resolve(process.cwd(), folder ?? ".");
+        if (existsSync(join(here, "circuit.ts"))) {
+            if (options.existing === "refuse") Ui.fail(`${here} holds a project already. Pick another folder.`);
+            await Setup.ready(here);
+            return;
+        }
+
+        if (!Ui.interactive) Ui.fail("Starting a project asks a few questions, so it needs a terminal.");
+
+        const setup = await Setup.ask(folder, options.kind);
+        const root = await Setup.create(setup);
+
+        Ui.note(Setup.nextSteps(root, setup), "Next");
+        Ui.outro("The project is ready.");
+    }
+
+    /** Get a project Circuit did not start here ready: its editor types, its git hook, and, in a full install, its packages. */
+    static async ready(root: string): Promise<void> {
+        Setup.prepare(root);
+
+        if (Setup.pinned(root)) {
+            await Ui.step("Installing the project's packages with Bun", async () => {
+                const result = spawnSync("bun", ["install"], { cwd: root, encoding: "utf8", shell: process.platform === "win32" });
+                if (result.status !== 0) throw new Error(`bun install failed: ${(result.stderr || result.stdout).trim()}`);
+            });
+        }
+
+        Ui.done(`${root} is ready. Run circuit in it.`);
+    }
+
+    /** `.circuit/DO_NOT_EDIT.md`, in place of the README an older Circuit wrote there. */
+    static writeNotice(root: string): void {
+        mkdirSync(join(root, ".circuit"), { recursive: true });
+        const path = join(root, ".circuit", NOTICE);
+        if (!existsSync(path) || readFileSync(path, "utf8") !== GENERATED_README) writeFileSync(path, GENERATED_README);
+        rmSync(join(root, ".circuit", "README.md"), { force: true });
+    }
+
+    /** The editor's settings: the style in `.editorconfig`, which the Prettier extension and `circuit fmt` both read, and format on save in VS Code. A file the project has already is kept. */
+    static writeEditor(root: string): void {
+        const json = (value: unknown) => `${JSON.stringify(value, null, 4)}\n`;
+        const files: Record<string, string> = {
+            ".editorconfig": Format.EDITORCONFIG,
+            ".vscode/settings.json": json({
+                "editor.formatOnSave": true,
+                "prettier.useEditorConfig": true,
+                "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+                "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" },
+                "files.eol": "\n",
+            }),
+            ".vscode/extensions.json": json({ recommendations: ["esbenp.prettier-vscode"] }),
+        };
+
+        for (const [file, text] of Object.entries(files)) {
+            const path = join(root, file);
+            if (existsSync(path)) continue;
+            mkdirSync(join(path, ".."), { recursive: true });
+            writeFileSync(path, text);
+        }
+    }
+
+    /** The version pinned in a full install's package.json, if the project has one. */
+    static pinned(root: string): string | undefined {
+        const path = join(root, "package.json");
+        if (!existsSync(path)) return undefined;
+
+        const manifest = JSON.parse(readFileSync(path, "utf8")) as {
+            devDependencies?: Record<string, string>;
+            dependencies?: Record<string, string>;
+        };
+        return manifest.devDependencies?.[Setup.PACKAGE] ?? manifest.dependencies?.[Setup.PACKAGE];
+    }
+}

package/src/cli/signing.ts

@@ -0,0 +1,23 @@
+// Signed releases. The release workflow signs each release's SHA256SUMS with Circuit's release key (Ed25519), kept as the repository secret RELEASE_SIGNING_KEY, and attaches the signature, SHA256SUMS.sig. Circuit downloads a binary only when SHA256SUMS carries a signature by one of the keys below and the binary matches it, so a release changed by anyone without the key is refused. A new key is added here, beside the old one, before releases are signed with it.
+
+import { createPublicKey, verify } from "node:crypto";
+
+export class Signing {
+    /** The public keys a release may be signed with. */
+    static readonly KEYS: readonly string[] = [
+        // Made 2026-11-03.
+        "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAEVi8tuMkrBMhyI241mBUtTQO7ndoVRjG7LBMQbnOyEw=\n-----END PUBLIC KEY-----\n",
+    ];
+
+    /** Whether `signature`, base64, is one of the release keys' over `data`. */
+    static verify(data: Buffer, signature: string, keys: readonly string[] = Signing.KEYS): boolean {
+        const bytes = Buffer.from(signature.trim(), "base64");
+        return keys.some((key) => {
+            try {
+                return verify(null, data, createPublicKey(key), bytes);
+            } catch {
+                return false;
+            }
+        });
+    }
+}