tokenmaxxing 1.10.0 → 1.11.0

package/src/cli/switch.ts

@@ -7,15 +7,24 @@ import { currentWins, effectiveBars, pickBest, pickEarliestReset, weeklyExpiry,
 import { InvalidGrantError } from "../lib/oauth.ts";
 import { gatedFamilies } from "../lib/usage.ts";
 import { findAccount } from "./rename.ts";
-import { c, fmtReset } from "./render.ts";
+import { c, emitError, emitJson, fmtReset } from "./render.ts";
 import type { Account } from "../lib/types.ts";
 
-export async function cmdSwitch(selector?: string): Promise<number> {
-  const idx0 = loadAccounts();
-  if (idx0.accounts.length < 2) {
-    console.error(c.yellow("need at least 2 accounts to switch - add one with `tokenmaxxing add`"));
+export async function cmdSwitch(selector?: string, json = false): Promise<number> {
+  const deadGrants: string[] = [];
+  const withDeadGrants = (report: Record<string, unknown>) => (deadGrants.length > 0 ? { ...report, deadGrants } : report);
+  const emit = (text: string, report: Record<string, unknown>): void => {
+    if (json) emitJson({ ok: true, ...withDeadGrants(report) });
+    else console.log(text);
+  };
+  const fail = (message: string, opts: { paint?: (s: string) => string; extra?: Record<string, unknown> } = {}): number => {
+    emitError({ json, message, paint: opts.paint, extra: withDeadGrants(opts.extra ?? {}) });
     return 1;
-  }
+  };
+  const deadGrantMessage = (a: Account) => `${a.label}'s refresh token is dead - run \`tokenmaxxing auth ${a.label}\``;
+
+  const idx0 = loadAccounts();
+  if (idx0.accounts.length < 2) return fail("need at least 2 accounts to switch - add one with `tokenmaxxing add`", { paint: c.yellow });
   const cfg = loadConfig();
   const now = Date.now();
 
@@ -26,23 +35,29 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     const claimedOrg = liveClaim?.organizationUuid ?? null;
     const drifted = claimed != null && claimed !== idx.activeAccountUuid;
 
-    const swapTo = async (target: Account): Promise<number> => {
+    const swapTo = async (target: Account, reason: string, extra: Record<string, unknown> = {}): Promise<number> => {
       try {
         await performSwap(target);
       } catch (e) {
-        if (e instanceof InvalidGrantError) { console.error(c.red(`${target.label}'s refresh token is dead - run \`tokenmaxxing auth ${target.label}\``)); return 1; }
+        if (e instanceof InvalidGrantError) {
+          deadGrants.push(target.label);
+          return fail(deadGrantMessage(target));
+        }
         throw e;
       }
-      console.log(`${c.green("↻")} switched to ${c.bold(target.label)}`);
+      emit(`${c.green("↻")} switched to ${c.bold(target.label)}`, { switched: true, account: target.label, reason, ...extra });
       return 0;
     };
 
     if (selector) {
       const target = findAccount(idx.accounts, selector);
-      if (!target) { console.error(c.red(`no account matches "${selector}"`)); return 1; }
-      if (target.accountUuid === idx.activeAccountUuid && !drifted) { console.log(`already on ${c.bold(target.label)}`); return 0; }
-      if (target.needsReauth) { console.error(c.red(`${target.label} needs re-auth - run \`tokenmaxxing auth ${target.label}\``)); return 1; }
-      return swapTo(target);
+      if (!target) return fail(`no account matches "${selector}"`);
+      if (target.accountUuid === idx.activeAccountUuid && !drifted) {
+        emit(`already on ${c.bold(target.label)}`, { switched: false, account: target.label, reason: "already-on" });
+        return 0;
+      }
+      if (target.needsReauth) return fail(`${target.label} needs re-auth - run \`tokenmaxxing auth ${target.label}\``);
+      return swapTo(target, "selected");
     }
 
     const switchFamilies = gatedFamilies(loadUsage()?.model ?? null, cfg.policy.switchModels);
@@ -60,10 +75,15 @@ export async function cmdSwitch(selector?: string): Promise<number> {
         cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ??
         null;
       if (active != null && currentWins(active, cur.accounts, everyone)) {
-        if (drifted) return swapTo(active);
+        if (drifted) return swapTo(active, "drift-reconciled");
         const expiry = weeklyExpiry(active, now);
         const why = Number.isFinite(expiry) ? ` (weekly ${fmtReset(expiry, now)})` : "";
-        console.log(`already on the best account: ${c.bold(active.label)}${why}`);
+        emit(`already on the best account: ${c.bold(active.label)}${why}`, {
+          switched: false,
+          account: active.label,
+          reason: "current-wins",
+          weeklyResetsAt: Number.isFinite(expiry) ? expiry : null,
+        });
         return 0;
       }
       const best = pickBest(cur.accounts, { ...everyone, currentAccountUuid: active?.accountUuid ?? null });
@@ -72,37 +92,53 @@ export async function cmdSwitch(selector?: string): Promise<number> {
         await performSwap(best);
       } catch (e) {
         if (e instanceof InvalidGrantError) {
-          console.error(c.red(`${best.label}'s refresh token is dead - run \`tokenmaxxing auth ${best.label}\``));
+          deadGrants.push(best.label);
+          if (!json) console.error(c.red(deadGrantMessage(best)));
           continue;
         }
         throw e;
       }
-      console.log(`${c.green("↻")} switched to ${c.bold(best.label)}`);
+      emit(`${c.green("↻")} switched to ${c.bold(best.label)}`, { switched: true, account: best.label, reason: "best" });
       return 0;
     }
 
     const fresh = loadAccounts();
     const earliest = pickEarliestReset(fresh.accounts, everyoneIn(fresh.accounts));
+    const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
     if (!earliest) {
-      const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
-      if (reauth.length > 0) { console.error(c.yellow(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`)); return 1; }
+      if (reauth.length > 0) {
+        return fail(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`, {
+          paint: c.yellow,
+          extra: { reauthNeeded: reauth },
+        });
+      }
       const freshActive = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid) ?? null;
-      if (drifted && freshActive) return swapTo(freshActive);
-      console.log(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"));
+      if (drifted && freshActive) return swapTo(freshActive, "drift-reconciled");
+      emit(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"), {
+        switched: false,
+        account: freshActive?.label ?? null,
+        reason: "unknown-resets",
+      });
       return 0;
     }
-    const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
     const reauthNote = reauth.length ? ` - re-auth needed: ${reauth.join(", ")}` : "";
+    const availableAt = earliest.availableAt > now ? earliest.availableAt : null;
     if (earliest.account.accountUuid === fresh.activeAccountUuid && !drifted) {
-      const msg = earliest.availableAt <= now
+      const msg = availableAt == null
         ? `staying on ${c.bold(earliest.account.label)} - no usable switch target${reauthNote}`
-        : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(earliest.availableAt, now)})${reauthNote}`;
-      console.log(c.yellow(msg));
+        : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(availableAt, now)})${reauthNote}`;
+      emit(c.yellow(msg), {
+        switched: false,
+        account: earliest.account.label,
+        reason: availableAt == null ? "no-target" : "all-at-limit",
+        availableAt,
+        reauthNeeded: reauth,
+      });
       return 0;
     }
-    const code = await swapTo(earliest.account);
-    if (code === 0 && earliest.availableAt > now) {
-      console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(earliest.availableAt, now)})${reauthNote}`));
+    const code = await swapTo(earliest.account, "earliest-reset", { availableAt, reauthNeeded: reauth });
+    if (code === 0 && availableAt != null && !json) {
+      console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(availableAt, now)})${reauthNote}`));
     }
     return code;
   });

package/src/cli/watch.ts

@@ -1,7 +1,8 @@
 import { clamp, delay } from "es-toolkit";
 import { loadAccounts } from "../lib/state.ts";
+import { loadCodexAccounts } from "../lib/codexstate.ts";
 import { cmdStatus } from "./status.ts";
-import { c } from "./render.ts";
+import { c, emitError, emitJson } from "./render.ts";
 
 const DEFAULT_INTERVAL_S = 120;
 const MIN_INTERVAL_S = 30;
@@ -16,13 +17,13 @@ export function resolveWatchInterval(arg?: string): number | null {
 
 const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
 
-export async function cmdWatch(intervalArg?: string): Promise<number> {
+export async function cmdWatch(intervalArg?: string, json = false): Promise<number> {
   const intervalS = resolveWatchInterval(intervalArg);
   if (intervalS === null) {
-    console.error(c.red(`watch interval must be a positive number of seconds, got: ${intervalArg}`));
+    emitError({ json, message: `watch interval must be a positive number of seconds, got: ${intervalArg}` });
     return 2;
   }
-  if (loadAccounts().accounts.length === 0) return cmdStatus();
+  if (loadAccounts().accounts.length === 0 && loadCodexAccounts().accounts.length === 0) return cmdStatus({ json });
 
   const paintHeader = () => {
     process.stdout.write(process.stdout.isTTY ? CLEAR : "\n");
@@ -30,10 +31,15 @@ export async function cmdWatch(intervalArg?: string): Promise<number> {
   };
   while (true) {
     try {
-      await cmdStatus(false, paintHeader);
+      await cmdStatus(json ? { json } : { preRender: paintHeader });
     } catch (e) {
-      paintHeader();
-      console.error(c.red(`status failed this tick: ${e instanceof Error ? e.message : String(e)}`));
+      const message = `status failed this tick: ${e instanceof Error ? e.message : String(e)}`;
+      if (json) {
+        emitJson({ ok: false, error: message });
+      } else {
+        paintHeader();
+        console.error(c.red(message));
+      }
     }
     await delay(intervalS * 1000);
   }

package/src/entries/mcp.ts

@@ -151,7 +151,7 @@ export function createTokenmaxxingMcpServer(): McpServer {
       inputSchema: {},
     },
     async () => {
-      const cap = await captureCli(() => cmdStatus(false));
+      const cap = await captureCli(() => cmdStatus());
       return textResult({ text: formatCapture(cap), isError: cap.code !== 0 });
     },
   );

package/src/main.ts

@@ -26,7 +26,10 @@ import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
 import { timerDeactivationHint, uninstallSupervisor } from "./lib/install.ts";
-import { c } from "./cli/render.ts";
+import { c, emitError, emitJson } from "./cli/render.ts";
+
+const JSON_FLAG = "--json";
+const INTERACTIVE_COMMANDS = new Set(["init", "add", "auth"]);
 
 function printHelp(): void {
   console.log(`${c.bold("tokenmaxxing")} - automatic Claude Code account switching
@@ -50,30 +53,45 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing rm")} [--codex] <sel>
   ${c.cyan("tokenmaxxing uninstall")}  remove supervisor + settings entries
 
+  ${c.cyan("--json")}                  print one JSON document on stdout instead of text (status, ls, config, doctor, check, switch, rename, rm, uninstall; one per tick for watch); every document carries ${c.bold("ok")}, failures add ${c.bold("error")}
+
   ${c.dim("(aliased as")} ${c.cyan("xx")}${c.dim(")")} - then just run ${c.bold("claude")} as always; it switches accounts near quota automatically.`);
 }
 
+let jsonMode = false;
+
 async function main(): Promise<number> {
   if (process.platform !== "darwin" && process.platform !== "linux") {
     console.error(`tokenmaxxing supports macOS and Linux only (this is ${process.platform})`);
     return 1;
   }
-  const args = process.argv.slice(2);
+  const argv = process.argv.slice(2);
   const argv0 = basename(process.argv0 || process.argv[0] || "");
-  const sub = args[0];
 
-  if (argv0 === "claude" || sub === "__supervise") {
-    return runSupervisor(sub === "__supervise" ? args.slice(1) : args);
+  if (argv0 === "claude" || argv[0] === "__supervise") {
+    return runSupervisor(argv[0] === "__supervise" ? argv.slice(1) : argv);
   }
-  if (argv0 === "codex" || sub === "__supervise-codex") {
-    return runCodexSupervisor({ argv: sub === "__supervise-codex" ? args.slice(1) : args });
+  if (argv0 === "codex" || argv[0] === "__supervise-codex") {
+    return runCodexSupervisor({ argv: argv[0] === "__supervise-codex" ? argv.slice(1) : argv });
   }
 
+  jsonMode = argv.includes(JSON_FLAG);
+  const json = jsonMode;
+  const args = argv.filter((a) => a !== JSON_FLAG);
+  const sub = args[0];
+
+  if (json && sub != null && INTERACTIVE_COMMANDS.has(sub)) {
+    emitError({ json, message: `${sub} is interactive (it runs a login flow) and has no --json form` });
+    return 2;
+  }
   if (!(sub != null && sub.startsWith("__")) && !process.env.TOKENMAXXING_PROBE) {
     const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
     const ambient = nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
     if (ambient != null) {
-      console.error(c.red(`CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR is set (${ambient}): claude uses a namespaced credential store there that tokenmaxxing does not manage - unset it (or run from a clean shell) and retry.`));
+      emitError({
+        json,
+        message: `CLAUDE_CONFIG_DIR / CLAUDE_SECURESTORAGE_CONFIG_DIR is set (${ambient}): claude uses a namespaced credential store there that tokenmaxxing does not manage - unset it (or run from a clean shell) and retry.`,
+      });
       return 1;
     }
   }
@@ -85,26 +103,26 @@ async function main(): Promise<number> {
     case "__stop-failure-hook": return runStopFailureHook();
     case "__session-start": return runSessionStart();
     case "__codex-stop-hook": return runCodexStopHook();
-    case undefined: return cmdStatus();
-    case "--force": return cmdStatus(true);
+    case undefined: return cmdStatus({ json });
+    case "--force": return cmdStatus({ force: true, json });
     case "switch": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
-      return args.includes("--codex") ? cmdCodexSwitch(rest[0]) : cmdSwitch(rest[0]);
+      return args.includes("--codex") ? cmdCodexSwitch(rest[0], json) : cmdSwitch(rest[0], json);
     }
-    case "check": return cmdCheck(args.slice(1));
-    case "config": return cmdConfig(args.slice(1));
+    case "check": return cmdCheck(args.slice(1), json);
+    case "config": return cmdConfig(args.slice(1), json);
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "auth": return cmdAuth(args.slice(1));
-    case "ls": return cmdLs();
-    case "status": return cmdStatus(args.includes("--force"));
-    case "watch": return cmdWatch(args[1]);
-    case "doctor": return cmdDoctor();
+    case "ls": return cmdLs(json);
+    case "status": return cmdStatus({ force: args.includes("--force"), json });
+    case "watch": return cmdWatch(args[1], json);
+    case "doctor": return cmdDoctor(json);
     case "rm": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
-      return args.includes("--codex") ? cmdCodexRm(rest[0]) : cmdRm(rest[0]);
+      return args.includes("--codex") ? cmdCodexRm(rest[0], json) : cmdRm(rest[0], json);
     }
-    case "rename": return cmdRename(args.slice(1));
+    case "rename": return cmdRename(args.slice(1), json);
     case "uninstall": {
       const out = uninstallSupervisor();
       const removed = [
@@ -113,6 +131,10 @@ async function main(): Promise<number> {
         ...(out.timerDeactivated ? ["check timer"] : []),
         ...(out.pathLineRemoved ? ["rc PATH line"] : []),
       ];
+      if (json) {
+        emitJson({ ok: true, removed, timerDeactivated: out.timerDeactivated, pathLineRemoved: out.pathLineRemoved });
+        return 0;
+      }
       console.log(`removed ${removed.join(", ")}`);
       if (!out.timerDeactivated) console.log(c.yellow(`⚠ the check job may still be loaded - run: ${timerDeactivationHint()}`));
       if (!out.pathLineRemoved) console.log(c.dim("(no tokenmaxxing PATH line found in the shell rc)"));
@@ -125,8 +147,8 @@ async function main(): Promise<number> {
       printHelp();
       return 0;
     default:
-      console.error(c.red(`unknown command: ${sub}`));
-      printHelp();
+      emitError({ json, message: `unknown command: ${sub}` });
+      if (!json) printHelp();
       return 2;
   }
 }
@@ -134,6 +156,6 @@ async function main(): Promise<number> {
 try {
   process.exit(await main());
 } catch (e) {
-  console.error(c.red(e instanceof Error ? e.message : String(e)));
+  emitError({ json: jsonMode, message: e instanceof Error ? e.message : String(e) });
   process.exit(1);
 }