@smithers-orchestrator/accounts 0.16.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@smithers-orchestrator/accounts",
+  "version": "0.16.9",
+  "description": "Manage multiple Claude/Codex/Gemini/Kimi subscription and API-key accounts that Smithers agents can round-robin through.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@smithers-orchestrator/errors": "0.16.9"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/Account.ts

@@ -0,0 +1,29 @@
+import type { AccountProvider } from "./AccountProvider";
+
+/**
+ * A single registered account. Either `configDir` (subscription providers) or
+ * `apiKey` (API providers) is set, never both. The CLI enforces this at
+ * registration time.
+ */
+export type Account = {
+  /** Unique label, e.g. "claude-work". Lowercase, kebab/snake/camel-case OK. */
+  label: string;
+  /** Which CLI/API this account belongs to. */
+  provider: AccountProvider;
+  /**
+   * Absolute path to the per-account CLI config directory. Set for
+   * subscription providers (claude-code, codex, gemini, kimi).
+   */
+  configDir?: string;
+  /**
+   * Raw API key. Set for API providers (anthropic-api, openai-api,
+   * gemini-api). Stored in plaintext in `~/.smithers/accounts.json` (mode 600).
+   * For stricter handling, set this to the empty string and override at
+   * runtime via the matching env var.
+   */
+  apiKey?: string;
+  /** Optional default model to bake into the generated `agents.ts`. */
+  model?: string;
+  /** ISO timestamp of when this account was added. */
+  addedAt?: string;
+};

package/src/AccountProvider.ts

@@ -0,0 +1,13 @@
+/**
+ * The provider behind a registered account. Subscription providers are
+ * authenticated by a CLI config directory; API providers are authenticated by
+ * an API key.
+ */
+export type AccountProvider =
+  | "claude-code"
+  | "codex"
+  | "gemini"
+  | "kimi"
+  | "anthropic-api"
+  | "openai-api"
+  | "gemini-api";

package/src/AccountsFile.ts

@@ -0,0 +1,6 @@
+import type { Account } from "./Account";
+
+export type AccountsFile = {
+  version: 1;
+  accounts: Account[];
+};

package/src/accountToProviderEnv.js

@@ -0,0 +1,44 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+/**
+ * Maps an account to the environment variables that the spawned CLI honors.
+ * Used by the agent classes' `buildCommand` and by `smithers agent test` to
+ * exercise an account without involving an agent.
+ *
+ * @param {import("./Account.ts").Account} account
+ * @returns {Record<string, string>}
+ */
+export function accountToProviderEnv(account) {
+    switch (account.provider) {
+        case "claude-code":
+            if (!account.configDir) {
+                throw new SmithersError("ACCOUNT_INVALID", `claude-code account "${account.label}" missing configDir`);
+            }
+            return { CLAUDE_CONFIG_DIR: account.configDir };
+        case "codex":
+            if (!account.configDir) {
+                throw new SmithersError("ACCOUNT_INVALID", `codex account "${account.label}" missing configDir`);
+            }
+            return { CODEX_HOME: account.configDir };
+        case "gemini":
+            if (!account.configDir) {
+                throw new SmithersError("ACCOUNT_INVALID", `gemini account "${account.label}" missing configDir`);
+            }
+            return { GEMINI_DIR: account.configDir };
+        case "kimi":
+            if (!account.configDir) {
+                throw new SmithersError("ACCOUNT_INVALID", `kimi account "${account.label}" missing configDir`);
+            }
+            return { KIMI_SHARE_DIR: account.configDir };
+        case "anthropic-api":
+            return account.apiKey ? { ANTHROPIC_API_KEY: account.apiKey } : {};
+        case "openai-api":
+            return account.apiKey ? { OPENAI_API_KEY: account.apiKey } : {};
+        case "gemini-api":
+            return account.apiKey ? { GEMINI_API_KEY: account.apiKey } : {};
+        default: {
+            const exhaustive = /** @type {never} */ (account.provider);
+            throw new SmithersError("ACCOUNT_INVALID", `unknown provider: ${exhaustive}`);
+        }
+    }
+}

package/src/accountsFilePath.js

@@ -0,0 +1,12 @@
+import { join } from "node:path";
+import { accountsRoot } from "./accountsRoot.js";
+
+/**
+ * Path to the JSON registry that lists all accounts.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function accountsFilePath(env = process.env) {
+    return join(accountsRoot(env), "accounts.json");
+}

package/src/accountsRoot.js

@@ -0,0 +1,16 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Returns the user-level Smithers root directory (~/.smithers by default).
+ * Honors `SMITHERS_HOME` for tests and CI.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function accountsRoot(env = process.env) {
+    if (env.SMITHERS_HOME) {
+        return env.SMITHERS_HOME;
+    }
+    return join(env.HOME ?? homedir(), ".smithers");
+}

package/src/addAccount.js

@@ -0,0 +1,50 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { readAccounts } from "./readAccounts.js";
+import { writeAccounts } from "./writeAccounts.js";
+import { API_KEY_PROVIDERS, SUBSCRIPTION_PROVIDERS, VALID_PROVIDERS } from "./parseAccountsFile.js";
+
+/** @typedef {import("./Account.ts").Account} Account */
+
+/**
+ * Adds (or replaces, if a same-label account exists) an account in the
+ * registry. Validates the entry before persisting so a malformed call cannot
+ * corrupt the file.
+ *
+ * @param {Account} account
+ * @param {{ replace?: boolean; env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Account}
+ */
+export function addAccount(account, options = {}) {
+    const env = options.env ?? process.env;
+    if (!account.label || !account.label.trim()) {
+        throw new SmithersError("ACCOUNT_INVALID", "account.label must be a non-empty string");
+    }
+    if (!VALID_PROVIDERS.has(account.provider)) {
+        throw new SmithersError("ACCOUNT_INVALID", `account.provider must be one of ${[...VALID_PROVIDERS].join(", ")}, got ${JSON.stringify(account.provider)}`);
+    }
+    if (SUBSCRIPTION_PROVIDERS.has(account.provider) && (!account.configDir || !account.configDir.trim())) {
+        throw new SmithersError("ACCOUNT_INVALID", `${account.provider} accounts require a non-empty configDir`);
+    }
+    if (API_KEY_PROVIDERS.has(account.provider) && typeof account.apiKey !== "string") {
+        throw new SmithersError("ACCOUNT_INVALID", `${account.provider} accounts require apiKey (may be empty string for env-var-only)`);
+    }
+    const existing = readAccounts(env);
+    const conflict = existing.accounts.findIndex((entry) => entry.label === account.label);
+    if (conflict >= 0 && !options.replace) {
+        throw new SmithersError("ACCOUNT_DUPLICATE_LABEL", `An account with label "${account.label}" already exists. Pass replace: true to overwrite, or use a different label.`);
+    }
+    /** @type {Account} */
+    const persisted = {
+        label: account.label,
+        provider: account.provider,
+        addedAt: account.addedAt ?? new Date().toISOString(),
+    };
+    if (account.configDir) persisted.configDir = account.configDir;
+    if (account.apiKey !== undefined) persisted.apiKey = account.apiKey;
+    if (account.model) persisted.model = account.model;
+    const next = conflict >= 0
+        ? existing.accounts.map((entry, i) => (i === conflict ? persisted : entry))
+        : [...existing.accounts, persisted];
+    writeAccounts({ version: 1, accounts: next }, env);
+    return persisted;
+}

package/src/defaultConfigDir.js

@@ -0,0 +1,14 @@
+import { join } from "node:path";
+import { accountsRoot } from "./accountsRoot.js";
+
+/**
+ * Default location for a per-account CLI config dir, e.g.
+ * `~/.smithers/accounts/claude-work`.
+ *
+ * @param {string} label
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function defaultConfigDir(label, env = process.env) {
+    return join(accountsRoot(env), "accounts", label);
+}

package/src/getAccount.js

@@ -0,0 +1,13 @@
+import { listAccounts } from "./listAccounts.js";
+
+/**
+ * Looks up an account by label. Returns undefined if not found (callers
+ * decide whether absence is an error).
+ *
+ * @param {string} label
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./Account.ts").Account | undefined}
+ */
+export function getAccount(label, env = process.env) {
+    return listAccounts(env).find((account) => account.label === label);
+}

package/src/index.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The provider behind a registered account. Subscription providers are
+ * authenticated by a CLI config directory; API providers are authenticated by
+ * an API key.
+ */
+type AccountProvider = "claude-code" | "codex" | "gemini" | "kimi" | "anthropic-api" | "openai-api" | "gemini-api";
+
+/**
+ * A single registered account. Either `configDir` (subscription providers) or
+ * `apiKey` (API providers) is set, never both. The CLI enforces this at
+ * registration time.
+ */
+type Account$1 = {
+    /** Unique label, e.g. "claude-work". Lowercase, kebab/snake/camel-case OK. */
+    label: string;
+    /** Which CLI/API this account belongs to. */
+    provider: AccountProvider;
+    /**
+     * Absolute path to the per-account CLI config directory. Set for
+     * subscription providers (claude-code, codex, gemini, kimi).
+     */
+    configDir?: string;
+    /**
+     * Raw API key. Set for API providers (anthropic-api, openai-api,
+     * gemini-api). Stored in plaintext in `~/.smithers/accounts.json` (mode 600).
+     * For stricter handling, set this to the empty string and override at
+     * runtime via the matching env var.
+     */
+    apiKey?: string;
+    /** Optional default model to bake into the generated `agents.ts`. */
+    model?: string;
+    /** ISO timestamp of when this account was added. */
+    addedAt?: string;
+};
+
+type AccountsFile = {
+    version: 1;
+    accounts: Account$1[];
+};
+
+/**
+ * Returns the user-level Smithers root directory (~/.smithers by default).
+ * Honors `SMITHERS_HOME` for tests and CI.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+declare function accountsRoot(env?: NodeJS.ProcessEnv): string;
+
+/**
+ * Path to the JSON registry that lists all accounts.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+declare function accountsFilePath(env?: NodeJS.ProcessEnv): string;
+
+/**
+ * Default location for a per-account CLI config dir, e.g.
+ * `~/.smithers/accounts/claude-work`.
+ *
+ * @param {string} label
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+declare function defaultConfigDir(label: string, env?: NodeJS.ProcessEnv): string;
+
+/**
+ * Parses a raw JSON string into a validated AccountsFile. Throws SmithersError
+ * with code `ACCOUNTS_FILE_INVALID` if the shape is wrong. Tolerates missing
+ * accounts.json (caller passes an empty string for that).
+ *
+ * @param {string} raw
+ * @returns {import("./AccountsFile.ts").AccountsFile}
+ */
+declare function parseAccountsFile(raw: string): AccountsFile;
+declare const SUBSCRIPTION_PROVIDERS: Set<string>;
+declare const API_KEY_PROVIDERS: Set<string>;
+declare const VALID_PROVIDERS: Set<string>;
+
+/**
+ * Reads ~/.smithers/accounts.json. Returns an empty registry if the file does
+ * not exist (a fresh install with no accounts is the normal startup state, not
+ * an error).
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./AccountsFile.ts").AccountsFile}
+ */
+declare function readAccounts(env?: NodeJS.ProcessEnv): AccountsFile;
+
+/**
+ * Atomically writes the accounts registry to ~/.smithers/accounts.json. The
+ * file is mode 0600 because it may contain raw API keys.
+ *
+ * @param {import("./AccountsFile.ts").AccountsFile} contents
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} the file path that was written
+ */
+declare function writeAccounts(contents: AccountsFile, env?: NodeJS.ProcessEnv): string;
+
+/**
+ * Returns the array of registered accounts, in registration order.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./Account.ts").Account[]}
+ */
+declare function listAccounts(env?: NodeJS.ProcessEnv): Account$1[];
+
+/**
+ * Looks up an account by label. Returns undefined if not found (callers
+ * decide whether absence is an error).
+ *
+ * @param {string} label
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./Account.ts").Account | undefined}
+ */
+declare function getAccount(label: string, env?: NodeJS.ProcessEnv): Account$1 | undefined;
+
+/** @typedef {import("./Account.ts").Account} Account */
+/**
+ * Adds (or replaces, if a same-label account exists) an account in the
+ * registry. Validates the entry before persisting so a malformed call cannot
+ * corrupt the file.
+ *
+ * @param {Account} account
+ * @param {{ replace?: boolean; env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Account}
+ */
+declare function addAccount(account: Account, options?: {
+    replace?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): Account;
+type Account = Account$1;
+
+/**
+ * Removes an account by label. Throws if no account exists with that label
+ * unless `silent: true`.
+ *
+ * @param {string} label
+ * @param {{ silent?: boolean; env?: NodeJS.ProcessEnv }} [options]
+ * @returns {boolean} true if an entry was removed
+ */
+declare function removeAccount(label: string, options?: {
+    silent?: boolean;
+    env?: NodeJS.ProcessEnv;
+}): boolean;
+
+/**
+ * Maps an account to the environment variables that the spawned CLI honors.
+ * Used by the agent classes' `buildCommand` and by `smithers agent test` to
+ * exercise an account without involving an agent.
+ *
+ * @param {import("./Account.ts").Account} account
+ * @returns {Record<string, string>}
+ */
+declare function accountToProviderEnv(account: Account$1): Record<string, string>;
+
+export { API_KEY_PROVIDERS, type Account$1 as Account, type AccountProvider, type AccountsFile, SUBSCRIPTION_PROVIDERS, VALID_PROVIDERS, accountToProviderEnv, accountsFilePath, accountsRoot, addAccount, defaultConfigDir, getAccount, listAccounts, parseAccountsFile, readAccounts, removeAccount, writeAccounts };

package/src/index.js

@@ -0,0 +1,11 @@
+export { accountsRoot } from "./accountsRoot.js";
+export { accountsFilePath } from "./accountsFilePath.js";
+export { defaultConfigDir } from "./defaultConfigDir.js";
+export { parseAccountsFile, SUBSCRIPTION_PROVIDERS, API_KEY_PROVIDERS, VALID_PROVIDERS } from "./parseAccountsFile.js";
+export { readAccounts } from "./readAccounts.js";
+export { writeAccounts } from "./writeAccounts.js";
+export { listAccounts } from "./listAccounts.js";
+export { getAccount } from "./getAccount.js";
+export { addAccount } from "./addAccount.js";
+export { removeAccount } from "./removeAccount.js";
+export { accountToProviderEnv } from "./accountToProviderEnv.js";

package/src/listAccounts.js

@@ -0,0 +1,11 @@
+import { readAccounts } from "./readAccounts.js";
+
+/**
+ * Returns the array of registered accounts, in registration order.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./Account.ts").Account[]}
+ */
+export function listAccounts(env = process.env) {
+    return readAccounts(env).accounts;
+}

package/src/parseAccountsFile.js

@@ -0,0 +1,95 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+
+const VALID_PROVIDERS = new Set([
+    "claude-code",
+    "codex",
+    "gemini",
+    "kimi",
+    "anthropic-api",
+    "openai-api",
+    "gemini-api",
+]);
+
+const SUBSCRIPTION_PROVIDERS = new Set([
+    "claude-code",
+    "codex",
+    "gemini",
+    "kimi",
+]);
+
+const API_KEY_PROVIDERS = new Set([
+    "anthropic-api",
+    "openai-api",
+    "gemini-api",
+]);
+
+/**
+ * Parses a raw JSON string into a validated AccountsFile. Throws SmithersError
+ * with code `ACCOUNTS_FILE_INVALID` if the shape is wrong. Tolerates missing
+ * accounts.json (caller passes an empty string for that).
+ *
+ * @param {string} raw
+ * @returns {import("./AccountsFile.ts").AccountsFile}
+ */
+export function parseAccountsFile(raw) {
+    if (!raw.trim()) {
+        return { version: 1, accounts: [] };
+    }
+    /** @type {unknown} */
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json is not valid JSON: ${cause?.message ?? String(cause)}`);
+    }
+    if (!parsed || typeof parsed !== "object") {
+        throw new SmithersError("ACCOUNTS_FILE_INVALID", "accounts.json must be a JSON object");
+    }
+    const obj = /** @type {Record<string, unknown>} */ (parsed);
+    if (obj.version !== 1) {
+        throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: unsupported version ${JSON.stringify(obj.version)} (expected 1)`);
+    }
+    if (!Array.isArray(obj.accounts)) {
+        throw new SmithersError("ACCOUNTS_FILE_INVALID", "accounts.json: `accounts` must be an array");
+    }
+    const seenLabels = new Set();
+    /** @type {import("./Account.ts").Account[]} */
+    const accounts = [];
+    for (let i = 0; i < obj.accounts.length; i++) {
+        const entry = obj.accounts[i];
+        if (!entry || typeof entry !== "object") {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: accounts[${i}] must be an object`);
+        }
+        const e = /** @type {Record<string, unknown>} */ (entry);
+        if (typeof e.label !== "string" || !e.label.trim()) {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: accounts[${i}].label must be a non-empty string`);
+        }
+        if (typeof e.provider !== "string" || !VALID_PROVIDERS.has(e.provider)) {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: accounts[${i}].provider must be one of ${[...VALID_PROVIDERS].join(", ")}, got ${JSON.stringify(e.provider)}`);
+        }
+        if (seenLabels.has(e.label)) {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: duplicate label ${JSON.stringify(e.label)}`);
+        }
+        seenLabels.add(e.label);
+        const isSubscription = SUBSCRIPTION_PROVIDERS.has(e.provider);
+        const isApiKey = API_KEY_PROVIDERS.has(e.provider);
+        if (isSubscription && (typeof e.configDir !== "string" || !e.configDir.trim())) {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: ${e.label} (${e.provider}) requires a non-empty configDir`);
+        }
+        if (isApiKey && typeof e.apiKey !== "string") {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: ${e.label} (${e.provider}) requires apiKey (may be empty string for env-var-only)`);
+        }
+        accounts.push({
+            label: e.label,
+            provider: e.provider,
+            configDir: typeof e.configDir === "string" ? e.configDir : undefined,
+            apiKey: typeof e.apiKey === "string" ? e.apiKey : undefined,
+            model: typeof e.model === "string" ? e.model : undefined,
+            addedAt: typeof e.addedAt === "string" ? e.addedAt : undefined,
+        });
+    }
+    return { version: 1, accounts };
+}
+
+export { SUBSCRIPTION_PROVIDERS, API_KEY_PROVIDERS, VALID_PROVIDERS };

package/src/readAccounts.js

@@ -0,0 +1,20 @@
+import { existsSync, readFileSync } from "node:fs";
+import { accountsFilePath } from "./accountsFilePath.js";
+import { parseAccountsFile } from "./parseAccountsFile.js";
+
+/**
+ * Reads ~/.smithers/accounts.json. Returns an empty registry if the file does
+ * not exist (a fresh install with no accounts is the normal startup state, not
+ * an error).
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {import("./AccountsFile.ts").AccountsFile}
+ */
+export function readAccounts(env = process.env) {
+    const path = accountsFilePath(env);
+    if (!existsSync(path)) {
+        return { version: 1, accounts: [] };
+    }
+    const raw = readFileSync(path, "utf8");
+    return parseAccountsFile(raw);
+}

package/src/removeAccount.js

@@ -0,0 +1,23 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { readAccounts } from "./readAccounts.js";
+import { writeAccounts } from "./writeAccounts.js";
+
+/**
+ * Removes an account by label. Throws if no account exists with that label
+ * unless `silent: true`.
+ *
+ * @param {string} label
+ * @param {{ silent?: boolean; env?: NodeJS.ProcessEnv }} [options]
+ * @returns {boolean} true if an entry was removed
+ */
+export function removeAccount(label, options = {}) {
+    const env = options.env ?? process.env;
+    const existing = readAccounts(env);
+    const next = existing.accounts.filter((entry) => entry.label !== label);
+    if (next.length === existing.accounts.length) {
+        if (options.silent) return false;
+        throw new SmithersError("ACCOUNT_NOT_FOUND", `No account with label "${label}" is registered.`);
+    }
+    writeAccounts({ version: 1, accounts: next }, env);
+    return true;
+}

package/src/writeAccounts.js

@@ -0,0 +1,23 @@
+import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { accountsFilePath } from "./accountsFilePath.js";
+
+/**
+ * Atomically writes the accounts registry to ~/.smithers/accounts.json. The
+ * file is mode 0600 because it may contain raw API keys.
+ *
+ * @param {import("./AccountsFile.ts").AccountsFile} contents
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} the file path that was written
+ */
+export function writeAccounts(contents, env = process.env) {
+    const path = accountsFilePath(env);
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    const serialized = `${JSON.stringify(contents, null, 2)}\n`;
+    writeFileSync(tmp, serialized, { encoding: "utf8", mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+    chmodSync(path, 0o600);
+    return path;
+}