codex-account-orchestrator 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-01-27
+
+### Added
+
+- Global npm install instructions and expanded debug options in README
+
+### Changed
+
+- Hardened registry and gateway config loading with automatic corruption backups
+- Improved gateway config path resolution via `os.homedir()`
+- Made codex shim resolution more robust when `codex` is missing from PATH
+
 ## [1.0.0] - 2025-01-27
 
 ### Added

package/README.md

@@ -2,6 +2,19 @@
 
 Codex OAuth account fallback orchestrator. It keeps **separate `CODEX_HOME` directories per account** and automatically falls back to the next account when quota is exhausted.
 
+## Requirements
+
+- Node.js 18+
+- Codex CLI installed and available on `PATH`
+
+## Install (npm)
+
+```bash
+npm install -g codex-account-orchestrator
+```
+
+The CLI is available as `cao` (alias) or `codex-account-orchestrator`.
+
 ## Install (local dev)
 
 ```bash
@@ -134,6 +147,12 @@ cao gateway status
 
 Set `CAO_DEBUG_HEADERS=1` to log sanitized request/response headers in the gateway process. To capture the last request body for inspection, also set `CAO_CAPTURE_BODY=1` (saved to `/tmp/cao-last-body.json` by default).
 
+Additional debug flags:
+
+- `CAO_DEBUG_BODY=1` to log a sanitized body snippet.
+- `CAO_CAPTURE_BODY_PATH=/path/to/file.json` to override the capture path.
+- `CAO_FORCE_QUOTA_ACCOUNTS=accountA,accountB` to simulate quota failures for specific accounts.
+
 ## Notes
 
 - Fallback requires capturing output; this may make Codex detect a non-TTY stdout. If you want a pure TTY session, use `--no-fallback`.

package/dist/gateway/account_pool.js

@@ -95,7 +95,14 @@ function loadTokens(accountDir) {
         return undefined;
     }
     const raw = fs_1.default.readFileSync(authPath, "utf8");
-    const data = JSON.parse(raw);
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch (error) {
+        process.stderr.write(`Warning: auth.json for ${accountDir} is invalid and will be skipped.\n`);
+        return undefined;
+    }
     const tokens = data.tokens ?? {};
     if (!tokens.access_token || !tokens.refresh_token) {
         return undefined;

package/dist/gateway/codex_shim.js

@@ -53,11 +53,21 @@ function disableGatewayShim() {
 }
 function resolveCodexPath() {
     const shimPath = path_1.default.join(resolveShimDir(), "codex");
-    const whichOutput = (0, child_process_1.execSync)("which -a codex", { encoding: "utf8" })
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean);
-    for (const line of whichOutput) {
+    const candidates = [];
+    const whichOutput = tryExec("which -a codex");
+    if (whichOutput) {
+        candidates.push(...whichOutput
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean));
+    }
+    if (candidates.length === 0) {
+        const fallback = tryExec("command -v codex");
+        if (fallback) {
+            candidates.push(fallback.trim());
+        }
+    }
+    for (const line of candidates) {
         if (line.includes("aliased to")) {
             continue;
         }
@@ -68,11 +78,7 @@ function resolveCodexPath() {
             return line;
         }
     }
-    const fallback = (0, child_process_1.execSync)("command -v codex", { encoding: "utf8" }).trim();
-    if (!fallback || fallback === shimPath) {
-        throw new Error("codex binary not found in PATH (or only the CAO shim is present). Disable the shim first.");
-    }
-    return fallback;
+    throw new Error("codex binary not found in PATH (or only the CAO shim is present). Disable the shim first.");
 }
 function resolveShimDir() {
     return path_1.default.join(os_1.default.homedir(), ".local", "bin");
@@ -81,3 +87,11 @@ function isDirInPath(dir) {
     const envPath = process.env.PATH ?? "";
     return envPath.split(":").includes(dir);
 }
+function tryExec(command) {
+    try {
+        return (0, child_process_1.execSync)(command, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/gateway/gateway_config.js

@@ -8,6 +8,7 @@ exports.getGatewayConfigPath = getGatewayConfigPath;
 exports.loadGatewayConfig = loadGatewayConfig;
 exports.saveGatewayConfig = saveGatewayConfig;
 const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const DEFAULT_CONFIG = {
     bindAddress: "127.0.0.1",
@@ -26,7 +27,7 @@ function resolveGatewayConfig(overrides) {
     };
 }
 function getGatewayConfigPath() {
-    return path_1.default.join(process.env.HOME ?? "", ".codex-account-orchestrator", "gateway.json");
+    return path_1.default.join(os_1.default.homedir(), ".codex-account-orchestrator", "gateway.json");
 }
 function loadGatewayConfig() {
     const configPath = getGatewayConfigPath();
@@ -34,7 +35,15 @@ function loadGatewayConfig() {
         return {};
     }
     const raw = fs_1.default.readFileSync(configPath, "utf8");
-    return JSON.parse(raw);
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const backupPath = `${configPath}.corrupt-${Date.now()}`;
+        fs_1.default.writeFileSync(backupPath, raw, "utf8");
+        process.stderr.write(`Warning: gateway.json was invalid and has been backed up to ${backupPath}.\n`);
+        return {};
+    }
 }
 function saveGatewayConfig(config) {
     const configPath = getGatewayConfigPath();

package/dist/paths.js

@@ -11,7 +11,7 @@ const path_1 = __importDefault(require("path"));
 const constants_1 = require("./constants");
 function getBaseDir(dataDir) {
     if (dataDir && dataDir.trim().length > 0) {
-        return dataDir;
+        return path_1.default.resolve(dataDir);
     }
     return path_1.default.join(os_1.default.homedir(), ".codex-account-orchestrator");
 }

package/dist/registry_store.js

@@ -7,16 +7,34 @@ exports.loadRegistry = loadRegistry;
 exports.saveRegistry = saveRegistry;
 const fs_1 = __importDefault(require("fs"));
 const paths_1 = require("./paths");
+const EMPTY_REGISTRY = {
+    default_account: null,
+    accounts: []
+};
 function loadRegistry(baseDir) {
     const registryPath = (0, paths_1.getRegistryPath)(baseDir);
     if (!fs_1.default.existsSync(registryPath)) {
-        return { default_account: null, accounts: [] };
+        return { ...EMPTY_REGISTRY };
     }
     const raw = fs_1.default.readFileSync(registryPath, "utf8");
-    const parsed = JSON.parse(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const backupPath = `${registryPath}.corrupt-${Date.now()}`;
+        fs_1.default.writeFileSync(backupPath, raw, "utf8");
+        process.stderr.write(`Warning: registry.json was invalid and has been backed up to ${backupPath}.\n`);
+        return { ...EMPTY_REGISTRY };
+    }
+    const accounts = normalizeAccounts(parsed.accounts);
+    const defaultAccount = typeof parsed.default_account === "string" ? parsed.default_account.trim() : null;
+    const normalizedDefault = defaultAccount && accounts.includes(defaultAccount)
+        ? defaultAccount
+        : accounts[0] ?? null;
     return {
-        default_account: parsed.default_account ?? null,
-        accounts: Array.isArray(parsed.accounts) ? parsed.accounts : []
+        default_account: normalizedDefault,
+        accounts
     };
 }
 function saveRegistry(baseDir, registry) {
@@ -24,3 +42,28 @@ function saveRegistry(baseDir, registry) {
     const payload = JSON.stringify(registry, null, 2) + "\n";
     fs_1.default.writeFileSync(registryPath, payload, "utf8");
 }
+function normalizeAccounts(accounts) {
+    if (!Array.isArray(accounts)) {
+        return [];
+    }
+    const seen = new Set();
+    const normalized = [];
+    for (const entry of accounts) {
+        if (typeof entry !== "string") {
+            continue;
+        }
+        const trimmed = entry.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        if (!/^[a-zA-Z0-9_-]+$/.test(trimmed)) {
+            continue;
+        }
+        if (seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        normalized.push(trimmed);
+    }
+    return normalized;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-account-orchestrator",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Codex OAuth account fallback orchestrator with seamless gateway mode",
   "main": "dist/cli_main.js",
   "types": "dist/cli_main.d.ts",