@smithers-orchestrator/accounts 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/accounts",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Manage multiple Claude/Antigravity/Codex/Gemini/Kimi subscription and API-key accounts that Smithers agents can round-robin through.",
   "type": "module",
   "sideEffects": false,
@@ -20,7 +20,7 @@
     "src/"
   ],
   "dependencies": {
-    "@smithers-orchestrator/errors": "0.24.0"
+    "@smithers-orchestrator/errors": "0.25.0"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/Account.ts

@@ -12,7 +12,7 @@ export type Account = {
   provider: AccountProvider;
   /**
    * Absolute path to the per-account CLI config directory. Set for
-   * subscription providers (claude-code, antigravity, codex, gemini, kimi).
+   * subscription providers (claude-code, antigravity, codex, kimi).
    */
   configDir?: string;
   /**

package/src/AccountProvider.ts

@@ -7,7 +7,6 @@ export type AccountProvider =
   | "claude-code"
   | "antigravity"
   | "codex"
-  | "gemini"
   | "kimi"
   | "anthropic-api"
   | "openai-api"

package/src/accountToProviderEnv.js

@@ -25,11 +25,6 @@ export function accountToProviderEnv(account) {
                 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`);

package/src/addAccount.js

@@ -1,6 +1,7 @@
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { readAccounts } from "./readAccounts.js";
 import { writeAccounts } from "./writeAccounts.js";
+import { withAccountsLock } from "./withAccountsLock.js";
 import { API_KEY_PROVIDERS, SUBSCRIPTION_PROVIDERS, VALID_PROVIDERS } from "./parseAccountsFile.js";
 
 /** @typedef {import("./Account.ts").Account} Account */
@@ -22,29 +23,38 @@ export function addAccount(account, options = {}) {
     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 (typeof account.configDir === "string" && typeof account.apiKey === "string") {
+        throw new SmithersError("ACCOUNT_INVALID", `${account.provider} account "${account.label}" must set configDir or apiKey, never both`);
+    }
     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;
+    // Read-modify-write must be serialized against concurrent mutations or a
+    // second writer's atomic rename clobbers this entry (lost update). The lock
+    // covers read → conflict-check → write so the base state we mutate is the
+    // same one we persist.
+    return withAccountsLock(env, () => {
+        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 ?? existing.accounts[conflict]?.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

@@ -1,5 +1,5 @@
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import { accountsRoot } from "./accountsRoot.js";
 
 /**
@@ -26,17 +26,5 @@ export function defaultConfigDir(label, env = process.env) {
         );
     }
     const root = accountsRoot(env);
-    const dir = join(root, "accounts", label);
-    // Defense-in-depth: a valid label can never escape, but assert the resolved
-    // path stays under the accounts root so a future regex change can't silently
-    // reintroduce traversal.
-    const base = resolve(root, "accounts");
-    const resolved = resolve(dir);
-    if (resolved !== join(base, label) && !resolved.startsWith(base + "/")) {
-        throw new SmithersError(
-            "ACCOUNT_INVALID",
-            `Invalid account label ${JSON.stringify(label)}: resolved path escapes the accounts directory.`,
-        );
-    }
-    return dir;
+    return join(root, "accounts", label);
 }

package/src/index.d.ts

@@ -3,7 +3,7 @@
  * authenticated by a CLI config directory; API providers are authenticated by
  * an API key.
  */
-type AccountProvider = "claude-code" | "antigravity" | "codex" | "gemini" | "kimi" | "anthropic-api" | "openai-api" | "gemini-api";
+type AccountProvider = "claude-code" | "antigravity" | "codex" | "kimi" | "anthropic-api" | "openai-api" | "gemini-api";
 
 /**
  * A single registered account. Either `configDir` (subscription providers) or
@@ -17,7 +17,7 @@ type Account$1 = {
     provider: AccountProvider;
     /**
      * Absolute path to the per-account CLI config directory. Set for
-     * subscription providers (claude-code, antigravity, codex, gemini, kimi).
+     * subscription providers (claude-code, antigravity, codex, kimi).
      */
     configDir?: string;
     /**

package/src/index.js

@@ -1,9 +1,16 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./Account.ts").Account} Account */
+/** @typedef {import("./AccountProvider.ts").AccountProvider} AccountProvider */
+/** @typedef {import("./AccountsFile.ts").AccountsFile} AccountsFile */
+// @smithers-type-exports-end
+
 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 { withAccountsLock } from "./withAccountsLock.js";
 export { listAccounts } from "./listAccounts.js";
 export { getAccount } from "./getAccount.js";
 export { addAccount } from "./addAccount.js";

package/src/parseAccountsFile.js

@@ -4,7 +4,6 @@ const VALID_PROVIDERS = new Set([
     "claude-code",
     "antigravity",
     "codex",
-    "gemini",
     "kimi",
     "anthropic-api",
     "openai-api",
@@ -15,7 +14,6 @@ const SUBSCRIPTION_PROVIDERS = new Set([
     "claude-code",
     "antigravity",
     "codex",
-    "gemini",
     "kimi",
 ]);
 
@@ -76,6 +74,9 @@ export function parseAccountsFile(raw) {
         seenLabels.add(e.label);
         const isSubscription = SUBSCRIPTION_PROVIDERS.has(e.provider);
         const isApiKey = API_KEY_PROVIDERS.has(e.provider);
+        if (typeof e.configDir === "string" && typeof e.apiKey === "string") {
+            throw new SmithersError("ACCOUNTS_FILE_INVALID", `accounts.json: ${e.label} (${e.provider}) must set configDir or apiKey, never both`);
+        }
         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`);
         }

package/src/removeAccount.js

@@ -1,6 +1,7 @@
 import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { readAccounts } from "./readAccounts.js";
 import { writeAccounts } from "./writeAccounts.js";
+import { withAccountsLock } from "./withAccountsLock.js";
 
 /**
  * Removes an account by label. Throws if no account exists with that label
@@ -12,12 +13,16 @@ import { writeAccounts } from "./writeAccounts.js";
  */
 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;
+    // Serialized read-modify-write so a concurrent addAccount cannot have its
+    // entry dropped by this remove's whole-file rewrite (lost update).
+    return withAccountsLock(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/withAccountsLock.js

@@ -0,0 +1,89 @@
+import { closeSync, mkdirSync, openSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { accountsFilePath } from "./accountsFilePath.js";
+
+/**
+ * Cross-process advisory lock around accounts.json read-modify-write. Smithers
+ * runs many agents/CLIs concurrently and both the wizard and the programmatic
+ * API can mutate ~/.smithers/accounts.json at the same time. Without a lock,
+ * two callers each readAccounts() the same base state and then writeAccounts()
+ * the whole file via atomic rename — the second rename clobbers the first
+ * writer's entry (lost update). This serializes those critical sections.
+ *
+ * The lock is an O_EXCL lock file next to accounts.json: only one process can
+ * create it. Others spin-wait briefly. A lock older than {@link STALE_LOCK_MS}
+ * is treated as orphaned (the holder crashed) and broken, so a killed process
+ * can never wedge the registry permanently — which matters because Smithers'
+ * whole premise is surviving kills/restarts.
+ *
+ * @template T
+ * @param {NodeJS.ProcessEnv} env
+ * @param {() => T} critical the read-modify-write to run while holding the lock
+ * @returns {T}
+ */
+export function withAccountsLock(env, critical) {
+    const lockPath = `${accountsFilePath(env)}.lock`;
+    mkdirSync(dirname(lockPath), { recursive: true });
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let fd = -1;
+    for (;;) {
+        try {
+            // wx === O_CREAT | O_EXCL | O_WRONLY: atomic create-or-fail.
+            fd = openSync(lockPath, "wx", 0o600);
+            break;
+        } catch (cause) {
+            if (cause?.code !== "EEXIST") throw cause;
+            if (Date.now() >= deadline) {
+                throw new Error(
+                    `Timed out acquiring accounts lock at ${lockPath} after ${LOCK_TIMEOUT_MS}ms; another process may be stuck holding it.`,
+                );
+            }
+            if (breakStaleLock(lockPath)) continue;
+            spin();
+        }
+    }
+    try {
+        writeFileSync(fd, `${process.pid}\n${Date.now()}\n`);
+        return critical();
+    } finally {
+        try { closeSync(fd); } catch {}
+        try { rmSync(lockPath, { force: true }); } catch {}
+    }
+}
+
+const LOCK_TIMEOUT_MS = 10_000;
+const STALE_LOCK_MS = 30_000;
+
+/**
+ * Removes the lock file if it is older than STALE_LOCK_MS (the holder almost
+ * certainly crashed). Returns true if the caller should retry acquiring.
+ *
+ * @param {string} lockPath
+ * @returns {boolean}
+ */
+function breakStaleLock(lockPath) {
+    try {
+        const stat = statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+            rmSync(lockPath, { force: true });
+            return true;
+        }
+    } catch {
+        // Lock vanished between EEXIST and stat: the holder released it. Retry.
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Busy-wait a few milliseconds before retrying. addAccount/removeAccount are
+ * fully synchronous, so the critical section never yields the event loop — a
+ * short spin is simpler and safer than introducing async, and the lock is held
+ * only for a single read-modify-write.
+ */
+function spin() {
+    const until = Date.now() + 5;
+    while (Date.now() < until) {
+        // intentional busy-wait
+    }
+}

package/src/writeAccounts.js

@@ -1,4 +1,5 @@
-import { chmodSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
 import { dirname } from "node:path";
 import { accountsFilePath } from "./accountsFilePath.js";
 
@@ -6,6 +7,11 @@ 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.
  *
+ * Writes to a temp file then renames over the target so a crash mid-write
+ * leaves the existing accounts.json byte-identical (atomicity). If the rename
+ * fails, the temp file — which contains plaintext API keys — is removed so it
+ * cannot linger world-readable or accumulate under ~/.smithers.
+ *
  * @param {import("./AccountsFile.ts").AccountsFile} contents
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {string} the file path that was written
@@ -13,11 +19,19 @@ import { accountsFilePath } from "./accountsFilePath.js";
 export function writeAccounts(contents, env = process.env) {
     const path = accountsFilePath(env);
     mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+    // pid + time + random so two same-millisecond writers never share a temp
+    // path and clobber each other's in-flight bytes.
+    const tmp = `${path}.tmp.${process.pid}.${Date.now()}.${randomBytes(6).toString("hex")}`;
     const serialized = `${JSON.stringify(contents, null, 2)}\n`;
     writeFileSync(tmp, serialized, { encoding: "utf8", mode: 0o600 });
     chmodSync(tmp, 0o600);
-    renameSync(tmp, path);
+    try {
+        renameSync(tmp, path);
+    } catch (cause) {
+        // Don't leave a plaintext-key temp file behind on a failed rename.
+        try { rmSync(tmp, { force: true }); } catch {}
+        throw cause;
+    }
     chmodSync(path, 0o600);
     return path;
 }