sidekick-shared 0.13.7 → 0.14.0

package/README.md

@@ -77,10 +77,22 @@ import { fetchQuota, readClaudeMaxCredentials } from 'sidekick-shared';
 const creds = readClaudeMaxCredentials();
 if (creds) {
   const quota = await fetchQuota(creds.accessToken);
-  console.log(`5-hour utilization: ${quota.fiveHour.percentUsed}%`);
+  if (quota.available) {
+    console.log(`5-hour utilization: ${quota.fiveHour.utilization}%`);
+  } else {
+    console.log(quota.failureKind, quota.httpStatus, quota.retryAfterMs);
+  }
 }
 ```
 
+Unavailable quota responses remain non-throwing and may include:
+
+- `failureKind`: `auth | network | rate_limit | server | unknown`
+- `httpStatus`: HTTP response status when available
+- `retryAfterMs`: retry delay in milliseconds for `429` responses when the API provides `Retry-After`
+
+For first-party style messaging, `describeQuotaFailure()` maps unavailable quota states to stable alert keys plus display-ready severity/title/message/detail fields for CLI and VS Code consumers.
+
 ## Building
 
 ```bash

package/dist/accounts.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Multi-account management for Claude Max subscriptions.
+ *
+ * Handles saving, listing, switching, and removing Claude accounts.
+ * Both the VS Code extension and CLI consume this module.
+ */
+export interface AccountEntry {
+    uuid: string;
+    email: string;
+    label?: string;
+    addedAt: string;
+}
+export interface AccountRegistry {
+    version: 1;
+    activeAccountUuid: string | null;
+    accounts: AccountEntry[];
+}
+export interface ActiveAccountInfo {
+    email: string;
+    uuid: string;
+}
+export interface AccountManagerResult {
+    success: boolean;
+    error?: string;
+}
+export declare function getAccountsDir(): string;
+export declare function readAccountRegistry(): AccountRegistry | null;
+export declare function writeAccountRegistry(registry: AccountRegistry): void;
+export declare function readActiveClaudeAccount(): ActiveAccountInfo | null;
+export declare function addCurrentAccount(label?: string): AccountManagerResult;
+export declare function switchToAccount(uuid: string): AccountManagerResult;
+export declare function removeAccount(uuid: string): AccountManagerResult;
+export declare function listAccounts(): AccountEntry[];
+export declare function getActiveAccount(): AccountEntry | null;
+export declare function isMultiAccountEnabled(): boolean;

package/dist/accounts.js

@@ -0,0 +1,325 @@
+"use strict";
+/**
+ * Multi-account management for Claude Max subscriptions.
+ *
+ * Handles saving, listing, switching, and removing Claude accounts.
+ * Both the VS Code extension and CLI consume this module.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAccountsDir = getAccountsDir;
+exports.readAccountRegistry = readAccountRegistry;
+exports.writeAccountRegistry = writeAccountRegistry;
+exports.readActiveClaudeAccount = readActiveClaudeAccount;
+exports.addCurrentAccount = addCurrentAccount;
+exports.switchToAccount = switchToAccount;
+exports.removeAccount = removeAccount;
+exports.listAccounts = listAccounts;
+exports.getActiveAccount = getActiveAccount;
+exports.isMultiAccountEnabled = isMultiAccountEnabled;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const paths_1 = require("./paths");
+const credentialIO_1 = require("./credentialIO");
+// ── Paths ────────────────────────────────────────────────────────────────
+function getClaudeDir() {
+    return path.join(os.homedir(), '.claude');
+}
+function getClaudeConfigPath() {
+    // Primary: ~/.claude/.claude.json
+    const primary = path.join(getClaudeDir(), '.claude.json');
+    try {
+        const data = JSON.parse(fs.readFileSync(primary, 'utf8'));
+        if (data?.oauthAccount)
+            return primary;
+    }
+    catch { /* fall through */ }
+    // Fallback: ~/.claude.json (some Claude Code versions store config here)
+    return path.join(os.homedir(), '.claude.json');
+}
+function getAccountsDir() {
+    return path.join((0, paths_1.getConfigDir)(), 'accounts');
+}
+function getCredentialsDir() {
+    return path.join(getAccountsDir(), 'credentials');
+}
+function getConfigsDir() {
+    return path.join(getAccountsDir(), 'configs');
+}
+function getRegistryPath() {
+    return path.join(getAccountsDir(), 'accounts.json');
+}
+// ── Directory bootstrap ──────────────────────────────────────────────────
+function ensureDirs() {
+    for (const dir of [getAccountsDir(), getCredentialsDir(), getConfigsDir()]) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
+// ── Atomic file write ────────────────────────────────────────────────────
+function atomicWriteJson(filePath, data, mode = 0o600) {
+    const tmp = filePath + '.tmp';
+    const json = JSON.stringify(data, null, 2);
+    // Validate we can re-parse before writing
+    JSON.parse(json);
+    fs.writeFileSync(tmp, json, { encoding: 'utf8', mode });
+    fs.renameSync(tmp, filePath);
+}
+// ── Registry operations ──────────────────────────────────────────────────
+function readAccountRegistry() {
+    try {
+        const content = fs.readFileSync(getRegistryPath(), 'utf8');
+        const parsed = JSON.parse(content);
+        if (parsed?.version !== 1 || !Array.isArray(parsed.accounts))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function writeAccountRegistry(registry) {
+    ensureDirs();
+    atomicWriteJson(getRegistryPath(), registry);
+}
+// ── Read active Claude account ───────────────────────────────────────────
+function readActiveClaudeAccount() {
+    try {
+        const content = fs.readFileSync(getClaudeConfigPath(), 'utf8');
+        const parsed = JSON.parse(content);
+        const email = parsed?.oauthAccount?.emailAddress;
+        const uuid = parsed?.oauthAccount?.accountUuid;
+        if (!email || !uuid)
+            return null;
+        return { email, uuid };
+    }
+    catch {
+        return null;
+    }
+}
+// ── Add current account ──────────────────────────────────────────────────
+function addCurrentAccount(label) {
+    // 1. Read current Claude identity
+    const active = readActiveClaudeAccount();
+    if (!active) {
+        return { success: false, error: 'No active Claude account found. Sign in with `claude` first.' };
+    }
+    // 2. Read current credentials (platform-aware: Keychain on macOS, file on Linux)
+    const credBlob = (0, credentialIO_1.readActiveCredentials)();
+    if (!credBlob) {
+        return { success: false, error: 'Could not read Claude credentials.' };
+    }
+    // 3. Read oauthAccount section from .claude.json
+    let configBlob;
+    try {
+        const raw = JSON.parse(fs.readFileSync(getClaudeConfigPath(), 'utf8'));
+        configBlob = raw.oauthAccount;
+    }
+    catch {
+        return { success: false, error: 'Could not read Claude config file.' };
+    }
+    ensureDirs();
+    // 4. Load or create registry
+    const registry = readAccountRegistry() ?? {
+        version: 1,
+        activeAccountUuid: null,
+        accounts: [],
+    };
+    // 5. Check if account already exists — update credentials + label
+    const existing = registry.accounts.find(a => a.uuid === active.uuid);
+    if (existing) {
+        if (label !== undefined)
+            existing.label = label;
+        atomicWriteJson(path.join(getCredentialsDir(), `${active.uuid}.credentials.json`), credBlob);
+        atomicWriteJson(path.join(getConfigsDir(), `${active.uuid}.config.json`), configBlob);
+        registry.activeAccountUuid = active.uuid;
+        writeAccountRegistry(registry);
+        return { success: true };
+    }
+    // 6. New account — back up credentials
+    atomicWriteJson(path.join(getCredentialsDir(), `${active.uuid}.credentials.json`), credBlob);
+    atomicWriteJson(path.join(getConfigsDir(), `${active.uuid}.config.json`), configBlob);
+    // 7. Add entry
+    registry.accounts.push({
+        uuid: active.uuid,
+        email: active.email,
+        label,
+        addedAt: new Date().toISOString(),
+    });
+    registry.activeAccountUuid = active.uuid;
+    writeAccountRegistry(registry);
+    return { success: true };
+}
+// ── Switch to account ────────────────────────────────────────────────────
+function switchToAccount(uuid) {
+    const registry = readAccountRegistry();
+    if (!registry) {
+        return { success: false, error: 'No account registry found. Save an account first.' };
+    }
+    const target = registry.accounts.find(a => a.uuid === uuid);
+    if (!target) {
+        return { success: false, error: `Account ${uuid} not found in registry.` };
+    }
+    if (registry.activeAccountUuid === uuid) {
+        return { success: true }; // Already active
+    }
+    // 1. Back up current credentials + config (for the currently-active account)
+    let originalCreds = null;
+    let originalConfig = null;
+    originalCreds = (0, credentialIO_1.readActiveCredentials)();
+    try {
+        originalConfig = fs.readFileSync(getClaudeConfigPath(), 'utf8');
+    }
+    catch { /* no existing config to back up */ }
+    // Save current account's backup if we know who's active
+    const currentActive = readActiveClaudeAccount();
+    if (currentActive) {
+        if (originalCreds) {
+            try {
+                atomicWriteJson(path.join(getCredentialsDir(), `${currentActive.uuid}.credentials.json`), originalCreds);
+            }
+            catch { /* best effort */ }
+        }
+        if (originalConfig) {
+            try {
+                const parsed = JSON.parse(originalConfig);
+                if (parsed.oauthAccount) {
+                    atomicWriteJson(path.join(getConfigsDir(), `${currentActive.uuid}.config.json`), parsed.oauthAccount);
+                }
+            }
+            catch { /* best effort */ }
+        }
+    }
+    // 2. Read target account's backed-up credentials + config
+    let targetCreds;
+    let targetOauthAccount;
+    try {
+        targetCreds = JSON.parse(fs.readFileSync(path.join(getCredentialsDir(), `${uuid}.credentials.json`), 'utf8'));
+    }
+    catch {
+        return { success: false, error: `Backed-up credentials for ${target.email} not found.` };
+    }
+    try {
+        targetOauthAccount = JSON.parse(fs.readFileSync(path.join(getConfigsDir(), `${uuid}.config.json`), 'utf8'));
+    }
+    catch {
+        return { success: false, error: `Backed-up config for ${target.email} not found.` };
+    }
+    // 3. Write target credentials (platform-aware: Keychain on macOS, file on Linux)
+    try {
+        (0, credentialIO_1.writeActiveCredentials)(targetCreds);
+    }
+    catch (err) {
+        // Rollback: restore original credentials
+        if (originalCreds) {
+            try {
+                (0, credentialIO_1.writeActiveCredentials)(originalCreds);
+            }
+            catch { /* rollback failed */ }
+        }
+        return { success: false, error: `Failed to write credentials: ${err}` };
+    }
+    // 4. Merge target oauthAccount into current .claude.json
+    try {
+        let configObj = {};
+        try {
+            configObj = JSON.parse(fs.readFileSync(getClaudeConfigPath(), 'utf8'));
+        }
+        catch { /* file may not exist yet */ }
+        configObj.oauthAccount = targetOauthAccount;
+        atomicWriteJson(getClaudeConfigPath(), configObj);
+    }
+    catch (err) {
+        // Rollback: restore original credentials and config
+        if (originalCreds) {
+            try {
+                (0, credentialIO_1.writeActiveCredentials)(originalCreds);
+            }
+            catch { /* rollback failed */ }
+        }
+        if (originalConfig) {
+            try {
+                fs.writeFileSync(getClaudeConfigPath(), originalConfig);
+            }
+            catch { /* rollback failed */ }
+        }
+        return { success: false, error: `Failed to write config: ${err}` };
+    }
+    // 5. Update registry
+    registry.activeAccountUuid = uuid;
+    writeAccountRegistry(registry);
+    return { success: true };
+}
+// ── Remove account ───────────────────────────────────────────────────────
+function removeAccount(uuid) {
+    const registry = readAccountRegistry();
+    if (!registry) {
+        return { success: false, error: 'No account registry found.' };
+    }
+    const idx = registry.accounts.findIndex(a => a.uuid === uuid);
+    if (idx === -1) {
+        return { success: false, error: `Account ${uuid} not found.` };
+    }
+    // Remove backed-up files
+    try {
+        fs.unlinkSync(path.join(getCredentialsDir(), `${uuid}.credentials.json`));
+    }
+    catch { /* ok */ }
+    try {
+        fs.unlinkSync(path.join(getConfigsDir(), `${uuid}.config.json`));
+    }
+    catch { /* ok */ }
+    // Remove from registry
+    registry.accounts.splice(idx, 1);
+    if (registry.activeAccountUuid === uuid) {
+        registry.activeAccountUuid = registry.accounts[0]?.uuid ?? null;
+    }
+    writeAccountRegistry(registry);
+    return { success: true };
+}
+// ── Query helpers ────────────────────────────────────────────────────────
+function listAccounts() {
+    return readAccountRegistry()?.accounts ?? [];
+}
+function getActiveAccount() {
+    const registry = readAccountRegistry();
+    if (!registry?.activeAccountUuid)
+        return null;
+    return registry.accounts.find(a => a.uuid === registry.activeAccountUuid) ?? null;
+}
+function isMultiAccountEnabled() {
+    const registry = readAccountRegistry();
+    return (registry?.accounts.length ?? 0) >= 1;
+}

package/dist/credentialIO.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Platform-aware credential I/O for Claude Code.
+ *
+ * On macOS, Claude Code stores OAuth credentials in the system Keychain
+ * (service "Claude Code-credentials"). On Linux/WSL/Windows, credentials
+ * live in ~/.claude/.credentials.json.
+ *
+ * Both accounts.ts and credentials.ts consume this module so that all
+ * credential access is platform-correct in one place.
+ */
+/**
+ * Read the active Claude Code credentials as a parsed object.
+ *
+ * - macOS: reads from system Keychain via the `security` CLI
+ * - Linux / WSL / Windows: reads `~/.claude/.credentials.json`
+ *
+ * Returns `null` when credentials are absent or unreadable.
+ */
+export declare function readActiveCredentials(): unknown;
+/**
+ * Write credentials to the active Claude Code credential store.
+ *
+ * - macOS: writes to system Keychain via the `security` CLI
+ * - Linux / WSL / Windows: atomic-writes `~/.claude/.credentials.json`
+ *
+ * Throws on failure.
+ */
+export declare function writeActiveCredentials(credentials: unknown): void;

package/dist/credentialIO.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Platform-aware credential I/O for Claude Code.
+ *
+ * On macOS, Claude Code stores OAuth credentials in the system Keychain
+ * (service "Claude Code-credentials"). On Linux/WSL/Windows, credentials
+ * live in ~/.claude/.credentials.json.
+ *
+ * Both accounts.ts and credentials.ts consume this module so that all
+ * credential access is platform-correct in one place.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readActiveCredentials = readActiveCredentials;
+exports.writeActiveCredentials = writeActiveCredentials;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const child_process_1 = require("child_process");
+const KEYCHAIN_SERVICE = 'Claude Code-credentials';
+function getCredentialsFilePath() {
+    return path.join(os.homedir(), '.claude', '.credentials.json');
+}
+/**
+ * Read the active Claude Code credentials as a parsed object.
+ *
+ * - macOS: reads from system Keychain via the `security` CLI
+ * - Linux / WSL / Windows: reads `~/.claude/.credentials.json`
+ *
+ * Returns `null` when credentials are absent or unreadable.
+ */
+function readActiveCredentials() {
+    if (process.platform === 'darwin') {
+        try {
+            const raw = (0, child_process_1.execFileSync)('security', [
+                'find-generic-password', '-s', KEYCHAIN_SERVICE, '-w',
+            ], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+            return JSON.parse(raw.trim());
+        }
+        catch {
+            return null;
+        }
+    }
+    // Linux / WSL / Windows — file-based
+    try {
+        return JSON.parse(fs.readFileSync(getCredentialsFilePath(), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write credentials to the active Claude Code credential store.
+ *
+ * - macOS: writes to system Keychain via the `security` CLI
+ * - Linux / WSL / Windows: atomic-writes `~/.claude/.credentials.json`
+ *
+ * Throws on failure.
+ */
+function writeActiveCredentials(credentials) {
+    const json = JSON.stringify(credentials);
+    JSON.parse(json); // validate round-trip
+    if (process.platform === 'darwin') {
+        (0, child_process_1.execFileSync)('security', [
+            'add-generic-password', '-U',
+            '-s', KEYCHAIN_SERVICE,
+            '-a', process.env.USER || 'user',
+            '-w', json,
+        ], { stdio: ['pipe', 'pipe', 'pipe'] });
+        return;
+    }
+    // Linux / WSL / Windows — file-based
+    const credPath = getCredentialsFilePath();
+    const tmp = credPath + '.tmp';
+    fs.writeFileSync(tmp, json, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmp, credPath);
+}

package/dist/credentials.d.ts

@@ -11,10 +11,11 @@ export interface ClaudeMaxCredentials {
     subscriptionType?: string;
 }
 /**
- * Reads Claude Max OAuth credentials from `~/.claude/.credentials.json`.
+ * Reads Claude Max OAuth credentials.
  *
- * Returns `null` if the file does not exist, the token is missing, or the
- * token is expired. Never throws.
+ * On macOS reads from system Keychain; on Linux/Windows reads from
+ * `~/.claude/.credentials.json`. Returns `null` if credentials are
+ * absent, the token is missing, or the token is expired. Never throws.
  */
 export declare function readClaudeMaxCredentials(): Promise<ClaudeMaxCredentials | null>;
 /**

package/dist/credentials.js

@@ -4,59 +4,23 @@
  *
  * Shared by sidekick-cli, sidekick-vscode, and any external consumer.
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readClaudeMaxCredentials = readClaudeMaxCredentials;
 exports.readClaudeMaxAccessTokenSync = readClaudeMaxAccessTokenSync;
-const fs = __importStar(require("fs"));
-const path = __importStar(require("path"));
-const os = __importStar(require("os"));
+const credentialIO_1 = require("./credentialIO");
 /**
- * Reads Claude Max OAuth credentials from `~/.claude/.credentials.json`.
+ * Reads Claude Max OAuth credentials.
  *
- * Returns `null` if the file does not exist, the token is missing, or the
- * token is expired. Never throws.
+ * On macOS reads from system Keychain; on Linux/Windows reads from
+ * `~/.claude/.credentials.json`. Returns `null` if credentials are
+ * absent, the token is missing, or the token is expired. Never throws.
  */
 async function readClaudeMaxCredentials() {
-    const credPath = path.join(os.homedir(), '.claude', '.credentials.json');
     try {
-        if (!fs.existsSync(credPath))
+        const raw = (0, credentialIO_1.readActiveCredentials)();
+        if (!raw)
             return null;
-        const content = await fs.promises.readFile(credPath, 'utf8');
-        const parsed = JSON.parse(content);
-        const oauth = parsed?.claudeAiOauth;
+        const oauth = raw.claudeAiOauth;
         if (!oauth?.accessToken)
             return null;
         if (oauth.expiresAt && Date.now() > oauth.expiresAt)
@@ -77,13 +41,11 @@ async function readClaudeMaxCredentials() {
  * Synchronous convenience — returns just the access token or `null`.
  */
 function readClaudeMaxAccessTokenSync() {
-    const credPath = path.join(os.homedir(), '.claude', '.credentials.json');
     try {
-        if (!fs.existsSync(credPath))
+        const raw = (0, credentialIO_1.readActiveCredentials)();
+        if (!raw)
             return null;
-        const content = fs.readFileSync(credPath, 'utf8');
-        const parsed = JSON.parse(content);
-        const oauth = parsed?.claudeAiOauth;
+        const oauth = raw.claudeAiOauth;
         if (!oauth?.accessToken)
             return null;
         if (oauth.expiresAt && Date.now() > oauth.expiresAt)

package/dist/index.d.ts

@@ -79,9 +79,14 @@ export { PatternExtractor } from './aggregation/PatternExtractor';
 export type { PatternCluster, SerializedPatternState } from './aggregation/PatternExtractor';
 export { generateHtmlReport, parseTranscript, openInBrowser } from './report';
 export type { TranscriptContentBlock, TranscriptEntry, HtmlReportOptions } from './report';
+export { readActiveCredentials, writeActiveCredentials } from './credentialIO';
 export { readClaudeMaxCredentials, readClaudeMaxAccessTokenSync } from './credentials';
 export type { ClaudeMaxCredentials } from './credentials';
+export { getAccountsDir, readAccountRegistry, writeAccountRegistry, readActiveClaudeAccount, addCurrentAccount, switchToAccount, removeAccount, listAccounts, getActiveAccount, isMultiAccountEnabled, } from './accounts';
+export type { AccountEntry, AccountRegistry, ActiveAccountInfo, AccountManagerResult } from './accounts';
 export { fetchQuota } from './quota';
 export type { QuotaWindow, QuotaState } from './quota';
+export { describeQuotaFailure } from './quotaPresentation';
+export type { QuotaFailureDescriptor } from './quotaPresentation';
 export { fetchProviderStatus } from './providerStatus';
 export type { ProviderStatusState } from './providerStatus';

package/dist/index.js

@@ -5,7 +5,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.findActiveClaudeSession = exports.discoverSessionDirectory = exports.getClaudeSessionDirectory = exports.encodeClaudeWorkspacePath = exports.detectSessionActivity = exports.extractTaskInfo = exports.scanSubagentDir = exports.normalizeCodexToolInput = exports.normalizeCodexToolName = exports.extractPatchFilePaths = exports.CodexRolloutParser = exports.parseDbPartData = exports.parseDbMessageData = exports.convertOpenCodeMessage = exports.detectPlanModeFromText = exports.normalizeToolInput = exports.normalizeToolName = exports.TRUNCATION_PATTERNS = exports.JsonlParser = exports.CodexProvider = exports.OpenCodeProvider = exports.ClaudeCodeProvider = exports.getAllDetectedProviders = exports.detectProvider = exports.readClaudeCodePlanFiles = exports.getPlanAnalytics = exports.writePlans = exports.getLatestPlan = exports.readPlans = exports.readLatestHandoff = exports.readHistory = exports.readNotes = exports.readDecisions = exports.readTasks = exports.getProjectSlugRaw = exports.getProjectSlug = exports.encodeWorkspacePath = exports.getGlobalDataPath = exports.getProjectDataPath = exports.getConfigDir = exports.MAX_PLANS_PER_PROJECT = exports.PLAN_SCHEMA_VERSION = exports.createEmptyTokenTotals = exports.HISTORICAL_DATA_SCHEMA_VERSION = exports.STALENESS_THRESHOLDS = exports.IMPORTANCE_DECAY_FACTORS = exports.KNOWLEDGE_NOTE_SCHEMA_VERSION = exports.DECISION_LOG_SCHEMA_VERSION = exports.normalizeTaskStatus = exports.TASK_PERSISTENCE_SCHEMA_VERSION = void 0;
 exports.HeatmapTracker = exports.FrequencyTracker = exports.getSnapshotPath = exports.isSnapshotValid = exports.deleteSnapshot = exports.loadSnapshot = exports.saveSnapshot = exports.parseTodoDependencies = exports.EventAggregator = exports.getRandomPhrase = exports.ALL_PHRASES = exports.HIGHLIGHT_CSS = exports.clearHighlightCache = exports.highlightEvent = exports.formatSessionJson = exports.formatSessionMarkdown = exports.formatSessionText = exports.classifyNoise = exports.shouldMergeWithPrevious = exports.classifyFollowEvent = exports.classifyMessage = exports.getSoftNoiseReason = exports.isHardNoiseFollowEvent = exports.isHardNoise = exports.formatToolSummary = exports.toFollowEvents = exports.createWatcher = exports.parseChangelog = exports.extractProposedPlanShared = exports.parsePlanMarkdownShared = exports.PlanExtractor = exports.composeContext = exports.FilterEngine = exports.searchSessions = exports.CodexDatabase = exports.OpenCodeDatabase = exports.discoverDebugLogs = exports.collapseDuplicates = exports.filterByLevel = exports.parseDebugLog = exports.scanSubagentTraces = exports.findAllSessionsWithWorktrees = exports.discoverWorktreeSiblings = exports.resolveWorktreeMainRepo = exports.getAllClaudeProjectFolders = exports.decodeEncodedPath = exports.getMostRecentlyActiveSessionDir = exports.findSubdirectorySessionDirs = exports.findSessionsInDirectory = exports.findAllClaudeSessions = void 0;
-exports.fetchProviderStatus = exports.fetchQuota = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = void 0;
+exports.fetchProviderStatus = exports.describeQuotaFailure = exports.fetchQuota = exports.isMultiAccountEnabled = exports.getActiveAccount = exports.listAccounts = exports.removeAccount = exports.switchToAccount = exports.addCurrentAccount = exports.readActiveClaudeAccount = exports.writeAccountRegistry = exports.readAccountRegistry = exports.getAccountsDir = exports.readClaudeMaxAccessTokenSync = exports.readClaudeMaxCredentials = exports.writeActiveCredentials = exports.readActiveCredentials = exports.openInBrowser = exports.parseTranscript = exports.generateHtmlReport = exports.PatternExtractor = void 0;
 var taskPersistence_1 = require("./types/taskPersistence");
 Object.defineProperty(exports, "TASK_PERSISTENCE_SCHEMA_VERSION", { enumerable: true, get: function () { return taskPersistence_1.TASK_PERSISTENCE_SCHEMA_VERSION; } });
 Object.defineProperty(exports, "normalizeTaskStatus", { enumerable: true, get: function () { return taskPersistence_1.normalizeTaskStatus; } });
@@ -174,13 +174,31 @@ var report_1 = require("./report");
 Object.defineProperty(exports, "generateHtmlReport", { enumerable: true, get: function () { return report_1.generateHtmlReport; } });
 Object.defineProperty(exports, "parseTranscript", { enumerable: true, get: function () { return report_1.parseTranscript; } });
 Object.defineProperty(exports, "openInBrowser", { enumerable: true, get: function () { return report_1.openInBrowser; } });
+// Credential I/O (platform-aware: Keychain on macOS, file on Linux/Windows)
+var credentialIO_1 = require("./credentialIO");
+Object.defineProperty(exports, "readActiveCredentials", { enumerable: true, get: function () { return credentialIO_1.readActiveCredentials; } });
+Object.defineProperty(exports, "writeActiveCredentials", { enumerable: true, get: function () { return credentialIO_1.writeActiveCredentials; } });
 // Credentials
 var credentials_1 = require("./credentials");
 Object.defineProperty(exports, "readClaudeMaxCredentials", { enumerable: true, get: function () { return credentials_1.readClaudeMaxCredentials; } });
 Object.defineProperty(exports, "readClaudeMaxAccessTokenSync", { enumerable: true, get: function () { return credentials_1.readClaudeMaxAccessTokenSync; } });
+// Accounts
+var accounts_1 = require("./accounts");
+Object.defineProperty(exports, "getAccountsDir", { enumerable: true, get: function () { return accounts_1.getAccountsDir; } });
+Object.defineProperty(exports, "readAccountRegistry", { enumerable: true, get: function () { return accounts_1.readAccountRegistry; } });
+Object.defineProperty(exports, "writeAccountRegistry", { enumerable: true, get: function () { return accounts_1.writeAccountRegistry; } });
+Object.defineProperty(exports, "readActiveClaudeAccount", { enumerable: true, get: function () { return accounts_1.readActiveClaudeAccount; } });
+Object.defineProperty(exports, "addCurrentAccount", { enumerable: true, get: function () { return accounts_1.addCurrentAccount; } });
+Object.defineProperty(exports, "switchToAccount", { enumerable: true, get: function () { return accounts_1.switchToAccount; } });
+Object.defineProperty(exports, "removeAccount", { enumerable: true, get: function () { return accounts_1.removeAccount; } });
+Object.defineProperty(exports, "listAccounts", { enumerable: true, get: function () { return accounts_1.listAccounts; } });
+Object.defineProperty(exports, "getActiveAccount", { enumerable: true, get: function () { return accounts_1.getActiveAccount; } });
+Object.defineProperty(exports, "isMultiAccountEnabled", { enumerable: true, get: function () { return accounts_1.isMultiAccountEnabled; } });
 // Quota
 var quota_1 = require("./quota");
 Object.defineProperty(exports, "fetchQuota", { enumerable: true, get: function () { return quota_1.fetchQuota; } });
+var quotaPresentation_1 = require("./quotaPresentation");
+Object.defineProperty(exports, "describeQuotaFailure", { enumerable: true, get: function () { return quotaPresentation_1.describeQuotaFailure; } });
 // Provider Status
 var providerStatus_1 = require("./providerStatus");
 Object.defineProperty(exports, "fetchProviderStatus", { enumerable: true, get: function () { return providerStatus_1.fetchProviderStatus; } });

package/dist/quota.d.ts

@@ -17,6 +17,12 @@ export interface QuotaState {
     available: boolean;
     /** Human-readable error if not available */
     error?: string;
+    /** Machine-readable failure classification for unavailable states */
+    failureKind?: 'auth' | 'network' | 'rate_limit' | 'server' | 'unknown';
+    /** HTTP status code for unavailable API responses */
+    httpStatus?: number;
+    /** Retry delay in milliseconds when rate-limited */
+    retryAfterMs?: number;
     /** Projected 5-hour utilization at reset (percentage, capped at 200) */
     projectedFiveHour?: number;
     /** Projected 7-day utilization at reset (percentage, capped at 200) */

package/dist/quota.js

@@ -29,14 +29,27 @@ function projectFromElapsed(utilization, resetsAt, windowMs) {
 /**
  * Helper to build an unavailable QuotaState.
  */
-function unavailableState(error) {
+function unavailableState(error, meta = {}) {
     return {
         fiveHour: { utilization: 0, resetsAt: '' },
         sevenDay: { utilization: 0, resetsAt: '' },
         available: false,
         error,
+        ...meta,
     };
 }
+function parseRetryAfterMs(retryAfter) {
+    if (!retryAfter)
+        return undefined;
+    const seconds = Number(retryAfter);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+        return Math.round(seconds * 1000);
+    }
+    const retryAt = Date.parse(retryAfter);
+    if (Number.isNaN(retryAt))
+        return undefined;
+    return Math.max(retryAt - Date.now(), 0);
+}
 /**
  * Fetch current quota utilization from the Anthropic OAuth usage API.
  *
@@ -57,9 +70,29 @@ async function fetchQuota(accessToken) {
             },
         });
         if (!res.ok) {
-            if (res.status === 401)
-                return unavailableState('Sign in to Claude Code to view quota');
-            return unavailableState(`API error: ${res.status}`);
+            if (res.status === 401) {
+                return unavailableState('Sign in to Claude Code to view quota', {
+                    failureKind: 'auth',
+                    httpStatus: res.status,
+                });
+            }
+            if (res.status === 429) {
+                return unavailableState(`API error: ${res.status}`, {
+                    failureKind: 'rate_limit',
+                    httpStatus: res.status,
+                    retryAfterMs: parseRetryAfterMs(res.headers.get('retry-after')),
+                });
+            }
+            if (res.status >= 500 && res.status <= 599) {
+                return unavailableState(`API error: ${res.status}`, {
+                    failureKind: 'server',
+                    httpStatus: res.status,
+                });
+            }
+            return unavailableState(`API error: ${res.status}`, {
+                failureKind: 'unknown',
+                httpStatus: res.status,
+            });
         }
         const data = await res.json();
         const fiveUtil = data.five_hour?.utilization ?? 0;
@@ -75,6 +108,6 @@ async function fetchQuota(accessToken) {
         };
     }
     catch {
-        return unavailableState('Network error');
+        return unavailableState('Network error', { failureKind: 'network' });
     }
 }

package/dist/quotaPresentation.d.ts

@@ -0,0 +1,10 @@
+import type { QuotaState } from './quota';
+export interface QuotaFailureDescriptor {
+    severity: 'info' | 'warning' | 'error';
+    title: string;
+    message: string;
+    detail?: string;
+    alertKey: string;
+    isRetryable: boolean;
+}
+export declare function describeQuotaFailure(quota: QuotaState | null | undefined): QuotaFailureDescriptor | null;

package/dist/quotaPresentation.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeQuotaFailure = describeQuotaFailure;
+function formatRetryAfter(ms) {
+    if (ms <= 0)
+        return 'now';
+    const totalSeconds = Math.ceil(ms / 1000);
+    const days = Math.floor(totalSeconds / 86_400);
+    const hours = Math.floor((totalSeconds % 86_400) / 3_600);
+    const minutes = Math.floor((totalSeconds % 3_600) / 60);
+    const seconds = totalSeconds % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0 && days === 0)
+        parts.push(`${minutes}m`);
+    if (parts.length === 0)
+        parts.push(`${seconds}s`);
+    return parts.join(' ');
+}
+function describeQuotaFailure(quota) {
+    if (!quota || quota.available || !quota.failureKind)
+        return null;
+    switch (quota.failureKind) {
+        case 'auth':
+            if (quota.error === 'No OAuth token available') {
+                return {
+                    severity: 'error',
+                    title: 'Sign in required',
+                    message: 'No Claude Code credentials are available in this environment.',
+                    detail: 'Run `claude` to sign in, then retry quota refresh.',
+                    alertKey: 'auth:no-credentials',
+                    isRetryable: false,
+                };
+            }
+            return {
+                severity: 'error',
+                title: 'Claude Code sign-in expired',
+                message: 'The current Claude Code OAuth session was rejected.',
+                detail: 'Sign in again to refresh subscription quota.',
+                alertKey: `auth:${quota.httpStatus ?? 'unknown'}`,
+                isRetryable: false,
+            };
+        case 'network':
+            return {
+                severity: 'warning',
+                title: 'Quota API unreachable',
+                message: 'Could not reach Anthropic from the current environment.',
+                detail: 'Check connectivity, proxy, or firewall settings, then retry.',
+                alertKey: 'network',
+                isRetryable: true,
+            };
+        case 'rate_limit':
+            return {
+                severity: 'warning',
+                title: 'Quota API rate limited',
+                message: quota.retryAfterMs != null
+                    ? `Retry in ${formatRetryAfter(quota.retryAfterMs)}.`
+                    : 'Retry shortly.',
+                detail: quota.httpStatus != null ? `Anthropic returned HTTP ${quota.httpStatus}.` : undefined,
+                alertKey: `rate_limit:${quota.httpStatus ?? 429}`,
+                isRetryable: true,
+            };
+        case 'server':
+            return {
+                severity: 'warning',
+                title: 'Quota API unavailable',
+                message: quota.httpStatus != null
+                    ? `Anthropic returned HTTP ${quota.httpStatus}. Try again shortly.`
+                    : 'Anthropic quota data is temporarily unavailable.',
+                alertKey: `server:${quota.httpStatus ?? 'unknown'}`,
+                isRetryable: true,
+            };
+        case 'unknown':
+            return {
+                severity: 'error',
+                title: 'Unexpected quota response',
+                message: quota.httpStatus != null
+                    ? `Anthropic returned HTTP ${quota.httpStatus}.`
+                    : (quota.error ?? 'Quota data could not be retrieved.'),
+                detail: 'This failure is not classified as retryable.',
+                alertKey: `unknown:${quota.httpStatus ?? 'none'}`,
+                isRetryable: false,
+            };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.13.7",
+  "version": "0.14.0",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",