axusage 2.1.0 → 3.0.0

package/dist/commands/run-auth-setup.js

@@ -1,5 +1,7 @@
-import chalk from "chalk";
 import { BrowserAuthManager } from "../services/browser-auth-manager.js";
+import { resolveAuthCliDependencyOrReport } from "../utils/check-cli-dependency.js";
+import { chalk } from "../utils/color.js";
+import { resolvePromptCapability } from "../utils/resolve-prompt-capability.js";
 /** Timeout for authentication setup (5 minutes) */
 const AUTH_SETUP_TIMEOUT_MS = 300_000;
 /**
@@ -46,31 +48,46 @@ export function isAuthFailure(result) {
 export async function runAuthSetup(service) {
     // CLI-based auth cannot use browser auth flow
     if (service === "gemini") {
+        const cliPath = resolveAuthCliDependencyOrReport("gemini");
+        if (!cliPath)
+            return false;
         console.error(chalk.yellow("\nGemini uses CLI-based authentication managed by the Gemini CLI."));
         console.error(chalk.gray("\nTo re-authenticate, run:"));
-        console.error(chalk.cyan("  gemini"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nThe Gemini CLI will guide you through the OAuth login process.\n"));
         return false;
     }
     if (service === "claude") {
+        const cliPath = resolveAuthCliDependencyOrReport("claude");
+        if (!cliPath)
+            return false;
         console.error(chalk.yellow("\nClaude uses CLI-based authentication managed by Claude Code."));
         console.error(chalk.gray("\nTo re-authenticate, run:"));
-        console.error(chalk.cyan("  claude"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nClaude Code will guide you through authentication.\n"));
         return false;
     }
     if (service === "chatgpt") {
+        const cliPath = resolveAuthCliDependencyOrReport("chatgpt");
+        if (!cliPath)
+            return false;
         console.error(chalk.yellow("\nChatGPT uses CLI-based authentication managed by Codex."));
         console.error(chalk.gray("\nTo re-authenticate, run:"));
-        console.error(chalk.cyan("  codex"));
+        console.error(chalk.cyan(`  ${cliPath}`));
         console.error(chalk.gray("\nCodex will guide you through authentication.\n"));
         return false;
     }
+    if (!resolvePromptCapability()) {
+        console.error(chalk.red("Error: Interactive authentication requires a TTY terminal."));
+        console.error(chalk.gray("Re-run in a TTY terminal (avoid piping stdin/stdout) with --interactive to complete authentication."));
+        return false;
+    }
     const manager = new BrowserAuthManager({ headless: false });
+    let setupPromise;
     let timeoutId;
     try {
         console.error(chalk.blue(`\nOpening browser for ${service} authentication...\n`));
-        const setupPromise = manager.setupAuth(service);
+        setupPromise = manager.setupAuth(service);
         const timeoutPromise = new Promise((_, reject) => {
             timeoutId = setTimeout(() => {
                 reject(new Error("Authentication setup timed out after 5 minutes"));
@@ -86,6 +103,10 @@ export async function runAuthSetup(service) {
     }
     finally {
         clearTimeout(timeoutId);
+        if (setupPromise) {
+            // Avoid unhandled rejections if the timeout wins the race.
+            void setupPromise.catch(() => { });
+        }
         await manager.close();
     }
 }

package/dist/commands/usage-command.js

@@ -1,9 +1,9 @@
-import chalk from "chalk";
 import { formatServiceUsageData, formatServiceUsageDataAsJson, formatServiceUsageAsTsv, toJsonObject, } from "../utils/format-service-usage.js";
 import { formatPrometheusMetrics } from "../utils/format-prometheus-metrics.js";
 import { fetchServiceUsage, selectServicesToQuery, } from "./fetch-service-usage.js";
 import { fetchServiceUsageWithAutoReauth } from "./fetch-service-usage-with-reauth.js";
 import { isAuthFailure } from "./run-auth-setup.js";
+import { chalk } from "../utils/color.js";
 /**
  * Fetches usage for services using hybrid strategy:
  * 1. Try all services in parallel first (fast path for valid credentials)
@@ -79,7 +79,9 @@ export async function usageCommand(options) {
     }
     if (!interactive && authFailureServices.size > 0) {
         const list = [...authFailureServices].join(", ");
-        console.error(chalk.gray(`Authentication required for: ${list}. Run 'axusage auth setup <service>' or re-run with '--interactive' to re-authenticate during fetch.`));
+        console.error(chalk.gray(`Authentication required for: ${list}. ` +
+            "For GitHub Copilot, run 'axusage --auth-setup github-copilot --interactive'. " +
+            "For CLI-auth services, run the provider CLI (claude/codex/gemini), or re-run with '--interactive' to re-authenticate during fetch."));
         if (successes.length > 0) {
             console.error();
         }
@@ -141,6 +143,6 @@ export async function usageCommand(options) {
         }
     }
     if (hasPartialFailures) {
-        process.exitCode = 2;
+        process.exitCode = 1;
     }
 }

package/dist/config/credential-sources.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Configuration for credential sources per service.
+ *
+ * Supports three modes:
+ * - "local": Use local credentials from axauth (default behavior)
+ * - "vault": Fetch credentials from axvault server
+ * - "auto": Try vault first if configured and credential name provided, fallback to local
+ */
+import { z } from "zod";
+/** Credential source type */
+declare const CredentialSourceType: z.ZodEnum<{
+    auto: "auto";
+    local: "local";
+    vault: "vault";
+}>;
+type CredentialSourceType = z.infer<typeof CredentialSourceType>;
+/** Resolved source config with normalized fields */
+interface ResolvedSourceConfig {
+    source: CredentialSourceType;
+    name: string | undefined;
+}
+/** Service IDs that support vault credentials (API-based services) */
+type VaultSupportedServiceId = "claude" | "chatgpt" | "gemini";
+/**
+ * All service IDs.
+ * Note: github-copilot uses GitHub token auth, not vault credentials,
+ * so it's excluded from VaultSupportedServiceId.
+ */
+type ServiceId = VaultSupportedServiceId | "github-copilot";
+/**
+ * Get the resolved source config for a specific service.
+ *
+ * @param service - Service ID (e.g., "claude", "chatgpt", "gemini")
+ * @returns Resolved config with source type and optional credential name
+ */
+declare function getServiceSourceConfig(service: ServiceId): ResolvedSourceConfig;
+export type { ServiceId, VaultSupportedServiceId };
+export { getServiceSourceConfig };

package/dist/config/credential-sources.js

@@ -0,0 +1,117 @@
+/**
+ * Configuration for credential sources per service.
+ *
+ * Supports three modes:
+ * - "local": Use local credentials from axauth (default behavior)
+ * - "vault": Fetch credentials from axvault server
+ * - "auto": Try vault first if configured and credential name provided, fallback to local
+ */
+import Conf from "conf";
+import { z } from "zod";
+/** Credential source type */
+const CredentialSourceType = z.enum(["auto", "local", "vault"]);
+/** Service source config - either a string shorthand or object with name */
+const ServiceSourceConfig = z.union([
+    CredentialSourceType,
+    z.object({
+        source: CredentialSourceType,
+        name: z.string().optional(),
+    }),
+]);
+/** Full sources config - map of service ID to source config */
+const SourcesConfig = z.record(z.string(), ServiceSourceConfig);
+// Lazy-initialized config instance
+let configInstance;
+function getConfig() {
+    if (!configInstance) {
+        configInstance = new Conf({
+            projectName: "axusage",
+            projectSuffix: "",
+            schema: {
+                sources: {
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        });
+        // Migration runs once per process when the config is first initialized.
+        migrateLegacySources(configInstance);
+    }
+    return configInstance;
+}
+function migrateLegacySources(config) {
+    // Respect explicit new config values; never overwrite them with legacy data.
+    if (config.get("sources") !== undefined)
+        return;
+    // Conf defaults to the legacy "-nodejs" suffix, which matches older configs.
+    const legacyConfig = new Conf({
+        projectName: "axusage",
+    });
+    const legacySources = legacyConfig.get("sources");
+    if (!legacySources)
+        return;
+    const parsed = SourcesConfig.safeParse(legacySources);
+    if (!parsed.success) {
+        console.error("Warning: Legacy axusage config contains invalid sources; skipping migration. Check your legacy config and migrate manually if needed.");
+        return;
+    }
+    config.set("sources", parsed.data);
+    console.error("Migrated credential source configuration from legacy axusage-nodejs config path.");
+}
+/**
+ * Get the full credential source configuration.
+ *
+ * Priority:
+ * 1. AXUSAGE_SOURCES environment variable (flat JSON)
+ * 2. Config file sources key
+ * 3. Empty object (defaults apply per-service)
+ */
+function getCredentialSourceConfig() {
+    // Priority 1: Environment variable
+    const environmentVariable = process.env.AXUSAGE_SOURCES;
+    if (environmentVariable) {
+        try {
+            const parsed = SourcesConfig.parse(JSON.parse(environmentVariable));
+            return parsed;
+        }
+        catch (error) {
+            const reason = error instanceof SyntaxError
+                ? "invalid JSON syntax"
+                : "schema validation failed";
+            console.error(`Warning: AXUSAGE_SOURCES ${reason}, falling back to config file`);
+        }
+    }
+    // Priority 2: Config file
+    const config = getConfig();
+    const fileConfig = config.get("sources");
+    if (fileConfig) {
+        const parsed = SourcesConfig.safeParse(fileConfig);
+        if (parsed.success) {
+            return parsed.data;
+        }
+        console.error("Warning: Config file contains invalid sources, using defaults");
+    }
+    // Priority 3: Empty (defaults apply)
+    return {};
+}
+/**
+ * Get the resolved source config for a specific service.
+ *
+ * @param service - Service ID (e.g., "claude", "chatgpt", "gemini")
+ * @returns Resolved config with source type and optional credential name
+ */
+function getServiceSourceConfig(service) {
+    const config = getCredentialSourceConfig();
+    const serviceConfig = config[service];
+    // Default: auto mode with no credential name
+    if (serviceConfig === undefined) {
+        return { source: "auto", name: undefined };
+    }
+    // String shorthand: just the source type
+    if (typeof serviceConfig === "string") {
+        return { source: serviceConfig, name: undefined };
+    }
+    // Object: source and name
+    return { source: serviceConfig.source, name: serviceConfig.name };
+}
+export { getServiceSourceConfig };

package/dist/services/create-auth-context.js

@@ -27,7 +27,8 @@ export async function loadStoredUserAgent(dataDirectory, service) {
 export async function createAuthContext(browser, dataDirectory, service) {
     const storageStatePath = getStorageStatePathFor(dataDirectory, service);
     if (!existsSync(storageStatePath)) {
-        throw new Error(`No saved authentication for ${service}. Run 'axusage auth setup ${service}' first.`);
+        throw new Error(`No saved authentication for ${service}. ` +
+            `Run 'axusage --auth-setup ${service} --interactive' first.`);
     }
     const userAgent = await loadStoredUserAgent(dataDirectory, service);
     return browser.newContext({ storageState: storageStatePath, userAgent });

package/dist/services/do-setup-auth.js

@@ -1,7 +1,7 @@
 import { setupAuthInContext } from "./setup-auth-flow.js";
-import { writeFile, chmod } from "node:fs/promises";
 import path from "node:path";
 import { getAuthMetaPathFor } from "./auth-storage-path.js";
+import { writeAtomicJson } from "../utils/write-atomic-json.js";
 export async function doSetupAuth(service, context, storagePath, instructions) {
     console.error(`\n${instructions}`);
     console.error("Waiting for login to complete (or press Enter to continue)\n");
@@ -9,13 +9,7 @@ export async function doSetupAuth(service, context, storagePath, instructions) {
     try {
         if (userAgent) {
             const metaPath = getAuthMetaPathFor(path.dirname(storagePath), service);
-            await writeFile(metaPath, JSON.stringify({ userAgent }), "utf8");
-            try {
-                await chmod(metaPath, 0o600);
-            }
-            catch {
-                // best effort
-            }
+            await writeAtomicJson(metaPath, { userAgent }, 0o600);
         }
     }
     catch {

package/dist/services/get-service-access-token.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Unified credential fetcher for services.
+ *
+ * Fetches access tokens based on per-service configuration:
+ * - "local": From local axauth credential store
+ * - "vault": From axvault server
+ * - "auto": Try vault first if configured, fallback to local
+ */
+import { type VaultSupportedServiceId } from "../config/credential-sources.js";
+/**
+ * Get access token for a service.
+ *
+ * Uses the configured credential source for the service:
+ * - "local": Fetch from local axauth credential store
+ * - "vault": Fetch from axvault server (requires credential name)
+ * - "auto": Try vault if configured and name provided, fallback to local
+ *
+ * @param service - Service ID (e.g., "claude", "chatgpt", "gemini")
+ * @returns Access token string or undefined if not available
+ *
+ * @example
+ * const token = await getServiceAccessToken("claude");
+ * if (!token) {
+ *   console.error("No credentials found for Claude");
+ * }
+ */
+declare function getServiceAccessToken(service: VaultSupportedServiceId): Promise<string | undefined>;
+export { getServiceAccessToken };

package/dist/services/get-service-access-token.js

@@ -0,0 +1,146 @@
+/**
+ * Unified credential fetcher for services.
+ *
+ * Fetches access tokens based on per-service configuration:
+ * - "local": From local axauth credential store
+ * - "vault": From axvault server
+ * - "auto": Try vault first if configured, fallback to local
+ */
+import { fetchVaultCredentials, getAgentAccessToken, isVaultConfigured, } from "axauth";
+import { getServiceSourceConfig, } from "../config/credential-sources.js";
+/** Map service IDs to agent IDs for axauth/vault */
+const SERVICE_TO_AGENT = {
+    claude: "claude",
+    chatgpt: "codex", // ChatGPT and Codex both use OpenAI API credentials
+    gemini: "gemini",
+};
+/**
+ * Extract access token from vault credentials.
+ *
+ * Different credential types store tokens differently:
+ * - oauth-credentials: access_token (Gemini style) or tokens.access_token (Codex/OpenAI style)
+ * - oauth-token: accessToken field (Claude style)
+ * - api-key: apiKey field
+ */
+function extractAccessToken(credentials) {
+    if (!credentials)
+        return undefined;
+    const { data } = credentials;
+    // Try accessToken first (Claude oauth-token style, camelCase)
+    if (typeof data.accessToken === "string") {
+        return data.accessToken;
+    }
+    // Try access_token at top level (Gemini oauth-credentials style, snake_case)
+    if (typeof data.access_token === "string") {
+        return data.access_token;
+    }
+    // Try tokens.access_token (Codex/OpenAI oauth-credentials style)
+    if (data.tokens &&
+        typeof data.tokens === "object" &&
+        "access_token" in data.tokens &&
+        typeof data.tokens.access_token === "string") {
+        return data.tokens.access_token;
+    }
+    // Try apiKey as fallback (api-key type)
+    if (typeof data.apiKey === "string") {
+        return data.apiKey;
+    }
+    return undefined;
+}
+/**
+ * Fetch access token from vault.
+ *
+ * @returns Access token string or undefined if not available
+ */
+async function fetchFromVault(agentId, credentialName) {
+    try {
+        const result = await fetchVaultCredentials({
+            agentId,
+            name: credentialName,
+        });
+        if (!result.ok) {
+            // Log warning for debugging, but don't fail hard
+            if (result.reason !== "not-configured" && result.reason !== "not-found") {
+                console.error(`[axusage] Vault fetch failed for ${agentId}/${credentialName}: ${result.reason}`);
+            }
+            return undefined;
+        }
+        const token = extractAccessToken(result.credentials);
+        if (!token) {
+            console.error(`[axusage] Vault credentials for ${agentId}/${credentialName} missing access token. ` +
+                `Credential type: ${result.credentials.type}`);
+        }
+        return token;
+    }
+    catch (error) {
+        console.error(`[axusage] Vault fetch error for ${agentId}/${credentialName}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Fetch access token from local credential store.
+ *
+ * @returns Access token string or undefined if not available
+ */
+async function fetchFromLocal(agentId) {
+    try {
+        return await getAgentAccessToken(agentId);
+    }
+    catch (error) {
+        console.error(`[axusage] Local credential fetch error for ${agentId}: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/**
+ * Get access token for a service.
+ *
+ * Uses the configured credential source for the service:
+ * - "local": Fetch from local axauth credential store
+ * - "vault": Fetch from axvault server (requires credential name)
+ * - "auto": Try vault if configured and name provided, fallback to local
+ *
+ * @param service - Service ID (e.g., "claude", "chatgpt", "gemini")
+ * @returns Access token string or undefined if not available
+ *
+ * @example
+ * const token = await getServiceAccessToken("claude");
+ * if (!token) {
+ *   console.error("No credentials found for Claude");
+ * }
+ */
+async function getServiceAccessToken(service) {
+    const config = getServiceSourceConfig(service);
+    const agentId = SERVICE_TO_AGENT[service];
+    switch (config.source) {
+        case "local": {
+            return fetchFromLocal(agentId);
+        }
+        case "vault": {
+            if (!config.name) {
+                console.error(`[axusage] Vault source requires credential name for ${service}. ` +
+                    `Set {"${service}": {"source": "vault", "name": "your-name"}} in config.`);
+                return undefined;
+            }
+            const token = await fetchFromVault(agentId, config.name);
+            if (!token) {
+                // User explicitly selected vault but it failed - provide clear feedback
+                console.error(`[axusage] Vault credential fetch failed for ${service}. ` +
+                    `Check that vault is configured (AXVAULT env) and credential "${config.name}" exists.`);
+            }
+            return token;
+        }
+        case "auto": {
+            // Auto mode: try vault first if configured and name provided
+            if (config.name && isVaultConfigured()) {
+                const vaultToken = await fetchFromVault(agentId, config.name);
+                if (vaultToken) {
+                    return vaultToken;
+                }
+                // Fallback to local if vault failed
+            }
+            // No credential name or vault not configured: use local only
+            return fetchFromLocal(agentId);
+        }
+    }
+}
+export { getServiceAccessToken };

package/dist/services/persist-storage-state.d.ts

@@ -1,6 +1,6 @@
 import type { BrowserContext } from "playwright";
 /**
  * Persist context storage state to disk with secure permissions (0o600).
- * Errors are silently ignored to avoid blocking the main operation.
+ * Errors are logged as warnings to avoid blocking the main operation.
  */
 export declare function persistStorageState(context: BrowserContext, storagePath: string): Promise<void>;

package/dist/services/persist-storage-state.js

@@ -1,16 +1,16 @@
-import { chmod } from "node:fs/promises";
+import { writeAtomicJson } from "../utils/write-atomic-json.js";
+import { chalk } from "../utils/color.js";
 /**
  * Persist context storage state to disk with secure permissions (0o600).
- * Errors are silently ignored to avoid blocking the main operation.
+ * Errors are logged as warnings to avoid blocking the main operation.
  */
 export async function persistStorageState(context, storagePath) {
     try {
-        await context.storageState({ path: storagePath });
-        await chmod(storagePath, 0o600).catch(() => {
-            // best effort: permissions may already be correct or OS may ignore
-        });
+        const state = await context.storageState();
+        await writeAtomicJson(storagePath, state, 0o600);
     }
-    catch {
-        // ignore persistence errors; do not block request completion
+    catch (error) {
+        const details = error instanceof Error ? error.message : String(error);
+        console.error(chalk.yellow(`Warning: Failed to persist auth state to ${storagePath} (${details}).`));
     }
 }

package/dist/services/setup-auth-flow.js

@@ -1,7 +1,29 @@
 import { getServiceAuthConfig } from "./service-auth-configs.js";
 import { waitForLogin } from "./wait-for-login.js";
 import { verifySessionByFetching } from "./verify-session.js";
-import { chmod } from "node:fs/promises";
+import { writeAtomicJson } from "../utils/write-atomic-json.js";
+function describeLoginOutcome(outcome) {
+    switch (outcome) {
+        case "manual": {
+            return "after manual continuation";
+        }
+        case "timeout": {
+            return "after login timeout";
+        }
+        case "closed": {
+            return "after the browser window closed";
+        }
+        case "aborted": {
+            return "after prompt cancellation";
+        }
+        case "selector": {
+            return "after detecting a login signal";
+        }
+        case "skipped": {
+            return "without waiting for a login signal";
+        }
+    }
+}
 export async function setupAuthInContext(service, context, storagePath) {
     const page = await context.newPage();
     try {
@@ -9,24 +31,27 @@ export async function setupAuthInContext(service, context, storagePath) {
         await page.goto(config.url);
         const selectors = config.waitForSelectors ??
             (config.waitForSelector ? [config.waitForSelector] : []);
-        await waitForLoginForService(page, selectors);
+        const loginOutcome = await waitForLoginForService(page, selectors);
+        const outcomeLabel = describeLoginOutcome(loginOutcome);
+        if (loginOutcome === "aborted") {
+            throw new Error("Authentication was canceled. Authentication was not saved.");
+        }
         if (config.verifyUrl) {
             const ok = config.verifyFunction
                 ? await config.verifyFunction(context, config.verifyUrl)
                 : await verifySessionByFetching(context, config.verifyUrl);
             if (!ok) {
-                console.warn(`\n⚠ Unable to verify session via ${config.verifyUrl}. Saving state anyway...`);
+                throw new Error(`Unable to verify session via ${config.verifyUrl} ${outcomeLabel}. Authentication was not saved. Ensure login completed successfully and retry.`);
             }
         }
+        else if (selectors.length > 0 && loginOutcome !== "selector") {
+            // Without a verification URL, we only persist when a login selector confirms success.
+            throw new Error(`Login was not confirmed ${outcomeLabel}. Authentication was not saved.`);
+        }
         // Capture user agent for future headless contexts
         const userAgent = await page.evaluate(() => navigator.userAgent);
-        await context.storageState({ path: storagePath });
-        try {
-            await chmod(storagePath, 0o600);
-        }
-        catch {
-            // best effort to restrict sensitive storage state
-        }
+        const state = await context.storageState();
+        await writeAtomicJson(storagePath, state, 0o600);
         return userAgent;
     }
     finally {
@@ -35,6 +60,8 @@ export async function setupAuthInContext(service, context, storagePath) {
 }
 async function waitForLoginForService(page, selectors) {
     if (selectors.length > 0) {
-        await waitForLogin(page, selectors);
+        return waitForLogin(page, selectors);
     }
+    // When no selectors are configured, skip waiting and rely on verification if available.
+    return "skipped";
 }

package/dist/services/supported-service.js

@@ -6,11 +6,13 @@ export const SUPPORTED_SERVICES = [
 ];
 export function validateService(service) {
     if (!service) {
-        throw new Error(`Service is required. Supported services: ${SUPPORTED_SERVICES.join(", ")}`);
+        throw new Error(`Service is required. Supported services: ${SUPPORTED_SERVICES.join(", ")}. ` +
+            "Run 'axusage --help' for usage.");
     }
     const normalizedService = service.toLowerCase();
     if (!SUPPORTED_SERVICES.includes(normalizedService)) {
-        throw new Error(`Unsupported service: ${service}. Supported services: ${SUPPORTED_SERVICES.join(", ")}`);
+        throw new Error(`Unsupported service: ${service}. Supported services: ${SUPPORTED_SERVICES.join(", ")}. ` +
+            "Run 'axusage --help' for usage.");
     }
     return normalizedService;
 }

package/dist/services/wait-for-login.d.ts

@@ -1,5 +1,6 @@
-import type { Page } from "playwright";
+import { type Page } from "playwright";
 /**
  * Waits until one of the selectors appears on the page, or the user presses Enter to continue.
  */
-export declare function waitForLogin(page: Page, selectors: readonly string[]): Promise<void>;
+export type LoginWaitOutcome = "selector" | "manual" | "timeout" | "closed" | "aborted" | "skipped";
+export declare function waitForLogin(page: Page, selectors: readonly string[]): Promise<LoginWaitOutcome>;