opencode-quotas 0.0.1

package/src/providers/github.ts

@@ -0,0 +1,161 @@
+import { readFile } from "node:fs/promises";
+import { AUTH_FILE, getConfigDirectory } from "../utils/paths";
+import { join } from "node:path";
+import { type IQuotaProvider, type QuotaData } from "../interfaces";
+
+const AUTH_PATH_LOCAL = AUTH_FILE();
+const AUTH_PATH_CONFIG = join(getConfigDirectory(), "auth.json");
+
+interface AuthInfo {
+    type: string;
+    access: string;
+    refresh?: string;
+    expires?: number;
+}
+
+type AuthFile = Record<string, AuthInfo>;
+
+async function readAuthFile(): Promise<AuthFile | null> {
+    for (const path of [AUTH_PATH_LOCAL, AUTH_PATH_CONFIG]) {
+        try {
+            const raw = await readFile(path, "utf8");
+            return JSON.parse(raw) as AuthFile;
+        } catch {
+            continue;
+        }
+    }
+
+    return null;
+}
+
+function parseTokenSku(token: string): string | null {
+    const parts = token.split(";");
+    for (const part of parts) {
+        if (part.startsWith("sku=")) {
+            return part.split("=")[1];
+        }
+    }
+    return null;
+}
+
+function getNextMonthStart(): Date {
+    const now = new Date();
+    const nextMonth = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0));
+    return nextMonth;
+}
+
+function formatTimeUntil(target: Date): string {
+    const diff = target.getTime() - Date.now();
+    if (diff <= 0) return "soon";
+    
+    const days = Math.floor(diff / (1000 * 60 * 60 * 24));
+    const hours = Math.floor((diff % (1000 * 60 * 60 * 24)) / (1000 * 60 * 60));
+    
+    if (days > 0) return `${days}d ${hours}h`;
+    return `${hours}h`;
+}
+
+export function parseGithubUsage(data: unknown, sku: string | null, apiWarning?: string | null): QuotaData[] {
+    // free_engaged_oss_quota is actually a "pro" equivalent for OSS maintainers
+    const isFreeLimited = sku?.includes("free") && !sku?.includes("oss");
+    
+    const now = new Date();
+    const resetTime = getNextMonthStart();
+    const resetStr = `resets in ${formatTimeUntil(resetTime)}`;
+
+    let usedSuggestions = 0;
+    let limit = isFreeLimited ? 2000 : null;
+    let unit = "suggestions";
+
+    if (Array.isArray(data) && data.length > 0) {
+        const currentMonthUsage = data.filter((day: unknown) => {
+            if (!day || typeof day !== "object") return false;
+            const dayRecord = day as Record<string, unknown>;
+            const dayValue = dayRecord["day"];
+            if (typeof dayValue !== "string") return false;
+
+            const dayDate = new Date(dayValue);
+            return dayDate.getUTCMonth() === now.getUTCMonth() && dayDate.getUTCFullYear() === now.getUTCFullYear();
+        });
+
+        usedSuggestions = currentMonthUsage.reduce((acc: number, day: unknown) => {
+            if (!day || typeof day !== "object") return acc;
+            const dayRecord = day as Record<string, unknown>;
+            const suggestions = typeof dayRecord["total_suggestions_count"] === "number" ? dayRecord["total_suggestions_count"] : 0;
+            const chat = typeof dayRecord["total_chat_count"] === "number" ? dayRecord["total_chat_count"] : 0;
+            return acc + suggestions + chat;
+        }, 0);
+    }
+
+    const infoParts: string[] = [];
+    if (isFreeLimited) infoParts.push("Free Plan");
+    else if (sku) infoParts.push("Pro Plan");
+
+    if (apiWarning) {
+        infoParts.push("Service Currently Unavailable (API Deprecated)");
+    }
+
+    return [
+        {
+            id: "github-copilot",
+            providerName: "GitHub Copilot",
+            used: usedSuggestions,
+            limit: limit,
+            unit: unit,
+            reset: resetStr,
+            window: "Monthly",
+            info: infoParts.join(" | "),
+        }
+    ];
+}
+
+export function createGithubProvider(): IQuotaProvider {
+    return {
+        id: "github-copilot",
+        async fetchQuota(): Promise<QuotaData[]> {
+            const auth = await readAuthFile();
+            if (!auth) {
+                throw new Error("Opencode auth.json not found");
+            }
+
+            const info = auth["github-copilot"] || auth["github"];
+            if (!info || !info.access) {
+                throw new Error("GitHub Copilot credentials missing");
+            }
+
+            const sku = parseTokenSku(info.access);
+
+            // Note: GitHub does not currently support a user-level Copilot usage
+            // endpoint for individual accounts. The legacy/beta endpoints were
+            // deprecated (and may return 404). We still attempt the call, but we
+            // surface failures as provider metadata so users can diagnose.
+            let data: unknown = null;
+            let apiWarning: string | null = null;
+
+            try {
+                const response = await fetch("https://api.github.com/user/copilot/usage", {
+                    headers: {
+                        Authorization: `Bearer ${info.access}`,
+                        "X-GitHub-Api-Version": "2022-11-28",
+                        Accept: "application/vnd.github+json",
+                    },
+                });
+
+                if (!response.ok) {
+                    if (response.status === 404) {
+                        apiWarning = "404";
+                    } else {
+                        const body = await response.text();
+                        apiWarning = `${response.status}: ${body.slice(0, 50)}`;
+                    }
+                } else {
+                    data = (await response.json()) as unknown;
+                }
+            } catch (error) {
+                apiWarning = "Request Failed";
+            }
+
+            return parseGithubUsage(data, sku, apiWarning);
+        },
+    };
+}

package/src/quota-cache.ts

@@ -0,0 +1,157 @@
+import { type IQuotaProvider, type QuotaData, type IHistoryService } from "./interfaces";
+import { validateQuotaData } from "./utils/validation";
+
+import { logger } from "./logger";
+
+type CachedQuotas = {
+    data: QuotaData[];
+    fetchedAt: Date | null;
+    lastError: unknown;
+};
+
+type QuotaCacheOptions = {
+    refreshIntervalMs: number;
+    historyService?: IHistoryService;
+    debug?: boolean;
+};
+
+const DEFAULT_OPTIONS: QuotaCacheOptions = {
+    refreshIntervalMs: 60_000,
+};
+
+export class QuotaCache {
+    private readonly providers: IQuotaProvider[];
+    private readonly options: QuotaCacheOptions;
+    private state: CachedQuotas;
+    private timer: ReturnType<typeof setInterval> | null;
+    private inFlight: Promise<void> | null;
+
+    public constructor(providers: IQuotaProvider[], options?: Partial<QuotaCacheOptions>) {
+        this.providers = providers;
+        this.options = { ...DEFAULT_OPTIONS, ...(options ?? {}) };
+        this.state = { data: [], fetchedAt: null, lastError: null };
+        this.timer = null;
+        this.inFlight = null;
+    }
+
+    public start(): void {
+        if (this.timer) return;
+
+        // Kick off an initial refresh without blocking startup.
+        void this.refresh();
+
+        this.timer = setInterval(() => {
+            void this.refresh();
+        }, this.options.refreshIntervalMs);
+
+        // Avoid keeping the process alive just for quota polling.
+        this.timer.unref?.();
+    }
+
+    public stop(): void {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+
+    public getSnapshot(): CachedQuotas {
+        return this.state;
+    }
+
+    public async refresh(): Promise<void> {
+        logger.debug(
+            "cache:refresh_start",
+            {
+                providerCount: this.providers.length,
+                refreshIntervalMs: this.options.refreshIntervalMs,
+                inFlight: !!this.inFlight,
+            },
+        );
+        if (this.inFlight) {
+            logger.debug("cache:refresh_coalesced", { inFlight: true });
+            return this.inFlight;
+        }
+
+        const refreshPromise = this.doRefresh();
+        this.inFlight = refreshPromise;
+
+        return refreshPromise;
+    }
+
+
+    private async doRefresh(): Promise<void> {
+        try {
+            const results = await Promise.all(
+                this.providers.map(async (p: IQuotaProvider) => {
+                    const startedAt = Date.now();
+                    try {
+                        logger.debug(
+                            "cache:provider_fetch_start",
+                            { id: p.id },
+                        );
+                        const result = await p.fetchQuota();
+                        logger.debug(
+                            "cache:provider_fetch_ok",
+                            {
+                                id: p.id,
+                                count: result.length,
+                                durationMs: Date.now() - startedAt,
+                            },
+                        );
+                        return result;
+                    } catch (e) {
+                        logger.error(
+                            "cache:provider_fetch_error",
+                            {
+                                id: p.id,
+                                durationMs: Date.now() - startedAt,
+                                error: e,
+                            },
+                        );
+                        return [];
+                    }
+                }),
+            );
+
+            // Validate and normalize provider responses before storing
+            const flattened = results.flat();
+            const validatedData = flattened
+                .map(d => validateQuotaData(d))
+                .filter((v): v is QuotaData => v !== null);
+
+            this.state = {
+                data: validatedData,
+                fetchedAt: new Date(),
+                lastError: null,
+            };
+
+            logger.debug(
+                "cache:refresh_ok",
+                {
+                    totalCount: this.state.data.length,
+                    fetchedAt: this.state.fetchedAt?.toISOString(),
+                },
+            );
+
+            if (this.options.historyService) {
+                void this.options.historyService.append(this.state.data);
+            }
+        } catch (e) {
+            this.state = {
+                ...this.state,
+                lastError: e,
+            };
+            logger.error(
+                "cache:refresh_error",
+                { error: e },
+            );
+        } finally {
+            logger.debug(
+                "cache:refresh_end",
+                { inFlightCleared: true },
+            );
+            this.inFlight = null;
+        }
+    }
+}

package/src/registry.ts

@@ -0,0 +1,30 @@
+import { type IQuotaRegistry, type IQuotaProvider } from "./interfaces";
+
+const REGISTRY_KEY = "__OPENCODE_QUOTA_REGISTRY__";
+
+type RegistryGlobal = {
+  [REGISTRY_KEY]?: IQuotaRegistry;
+};
+
+function createRegistry(): IQuotaRegistry {
+  const providers: IQuotaProvider[] = [];
+  return {
+    register(provider: IQuotaProvider) {
+      if (providers.some((p) => p.id === provider.id)) {
+        return;
+      }
+      providers.push(provider);
+    },
+    getAll() {
+      return [...providers];
+    },
+  };
+}
+
+export function getQuotaRegistry(): IQuotaRegistry {
+  const globalRef = globalThis as RegistryGlobal;
+  if (!globalRef[REGISTRY_KEY]) {
+    globalRef[REGISTRY_KEY] = createRegistry();
+  }
+  return globalRef[REGISTRY_KEY] as IQuotaRegistry;
+}

package/src/services/aggregation-service.ts

@@ -0,0 +1,116 @@
+import { 
+    type QuotaData, 
+    type IPredictionEngine, 
+    type IAggregationService 
+} from "../interfaces";
+import { formatDurationMs } from "../utils/time";
+
+/**
+ * Service for aggregating multiple quota sources into a single representative quota.
+ * 
+ * Supports multiple aggregation strategies:
+ * - most_critical: Selects the quota with shortest predicted time-to-limit
+ * - max: Selects the quota with highest usage ratio
+ * - min: Selects the quota with lowest usage ratio
+ * - mean: Creates a synthetic quota with average usage ratio
+ * - median: Creates a synthetic quota with median usage ratio
+ */
+export class AggregationService implements IAggregationService {
+    private readonly predictionEngine: IPredictionEngine;
+
+    constructor(predictionEngine: IPredictionEngine) {
+        this.predictionEngine = predictionEngine;
+    }
+
+    /**
+     * Aggregates quotas using the most critical (shortest time-to-limit) strategy.
+     * Falls back to max usage ratio if no predictions are available.
+     */
+    aggregateMostCritical(
+        quotas: QuotaData[], 
+        windowMinutes: number = 60, 
+        shortWindowMinutes?: number
+    ): QuotaData | null {
+        if (quotas.length === 0) return null;
+
+        let minTime = Infinity;
+        let representative: QuotaData | null = null;
+
+        for (const q of quotas) {
+            const time = this.predictionEngine.predictTimeToLimit(
+                q.id, 
+                windowMinutes, 
+                shortWindowMinutes
+            );
+            if (time < minTime) {
+                minTime = time;
+                representative = q;
+            }
+        }
+
+        // Fallback to max usage if no prediction is possible
+        if (!representative) {
+            return this.aggregateMax(quotas);
+        } 
+        
+        if (minTime !== Infinity) {
+            return {
+                ...representative,
+                predictedReset: `in ${formatDurationMs(minTime)} (predicted)`
+            };
+        }
+        return representative;
+    }
+
+    /**
+     * Aggregates quotas by selecting the one with highest usage ratio.
+     */
+    aggregateMax(quotas: QuotaData[]): QuotaData {
+        return quotas.reduce((a, b) => {
+            const aRatio = a.limit ? a.used / a.limit : 0;
+            const bRatio = b.limit ? b.used / b.limit : 0;
+            return aRatio > bRatio ? a : b;
+        });
+    }
+
+    /**
+     * Aggregates quotas by selecting the one with lowest usage ratio.
+     */
+    aggregateMin(quotas: QuotaData[]): QuotaData {
+        return quotas.reduce((a, b) => {
+            const aRatio = a.limit ? a.used / a.limit : 0;
+            const bRatio = b.limit ? b.used / b.limit : 0;
+            return aRatio < bRatio ? a : b;
+        });
+    }
+
+    /**
+     * Aggregates quotas by averaging their usage ratios.
+     * Creates a synthetic quota with percentage-based representation.
+     */
+    aggregateAverage(
+        quotas: QuotaData[], 
+        name: string, 
+        id: string, 
+        strategy: "mean" | "median"
+    ): QuotaData {
+        const ratios = quotas.map(q => q.limit ? q.used / q.limit : 0);
+        let avgRatio = 0;
+
+        if (strategy === "mean") {
+            avgRatio = ratios.reduce((a, b) => a + b, 0) / ratios.length;
+        } else {
+            ratios.sort((a, b) => a - b);
+            avgRatio = ratios[Math.floor(ratios.length / 2)];
+        }
+        
+        return {
+            id: id,
+            providerName: name,
+            used: Math.round(avgRatio * 100),
+            limit: 100,
+            unit: "%",
+            info: "Aggregated"
+        };
+    }
+}

package/src/services/config-loader.ts

@@ -0,0 +1,124 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_CONFIG } from "../defaults";
+import { type QuotaConfig } from "../interfaces";
+import { logger } from "../logger";
+
+import { validatePollingInterval } from "../utils/validation";
+
+/**
+ * Configuration loading and merging service.
+ * Handles reading config from disk and merging with defaults.
+ */
+export class ConfigLoader {
+    /**
+     * Creates a new configuration by merging defaults with initial config.
+     */
+    static createConfig(initialConfig?: Partial<QuotaConfig>): QuotaConfig {
+        const config: QuotaConfig = { ...DEFAULT_CONFIG, ...initialConfig };
+        
+        // Deep clone specific nested objects to avoid mutation of the constant
+        if (DEFAULT_CONFIG.progressBar) {
+            config.progressBar = { ...DEFAULT_CONFIG.progressBar, ...initialConfig?.progressBar };
+        }
+        if (DEFAULT_CONFIG.aggregatedGroups) {
+            config.aggregatedGroups = [
+                ...DEFAULT_CONFIG.aggregatedGroups, 
+                ...(initialConfig?.aggregatedGroups || [])
+            ];
+        }
+        
+        return config;
+    }
+
+    /**
+     * Loads and merges user configuration from disk into the provided config.
+     * Returns the updated config.
+     */
+    static async loadFromDisk(
+        directory: string, 
+        config: QuotaConfig
+    ): Promise<QuotaConfig> {
+        const result = { ...config };
+        
+        try {
+            const envConfigPath = process.env.OPENCODE_QUOTAS_CONFIG_PATH;
+            const configPath = envConfigPath || join(directory, ".opencode", "quotas.json");
+            const rawConfig = await readFile(configPath, "utf-8");
+            const userConfig = JSON.parse(rawConfig);
+            
+            ConfigLoader.mergeUserConfig(result, userConfig);
+            
+            logger.debug(
+                "init:config_loaded",
+                { configPath, debug: result.debug },
+            );
+
+        } catch (e) {
+            // Ignore missing config or parse errors
+            logger.error(
+                "init:config_load_failed",
+                { error: e },
+            );
+        }
+
+        // Validate and normalize config values
+        await ConfigLoader.validateConfig(result);
+        
+        return result;
+    }
+
+    /**
+     * Merges user configuration into the target config.
+     */
+    private static mergeUserConfig(target: QuotaConfig, userConfig: Partial<QuotaConfig>): void {
+        if (userConfig.debug !== undefined) {
+            target.debug = userConfig.debug;
+            logger.setDebug(!!target.debug);
+        }
+        if (userConfig.footer !== undefined) {
+            target.footer = userConfig.footer;
+        }
+        if (userConfig.progressBar) {
+            target.progressBar = { ...target.progressBar, ...userConfig.progressBar };
+        }
+        if (userConfig.table) {
+            target.table = { ...target.table, ...userConfig.table };
+        }
+        if (userConfig.disabled) {
+            target.disabled = userConfig.disabled;
+        }
+        if (userConfig.filterByCurrentModel !== undefined) {
+            target.filterByCurrentModel = userConfig.filterByCurrentModel;
+        }
+        if (userConfig.aggregatedGroups) {
+            target.aggregatedGroups = userConfig.aggregatedGroups;
+        }
+        if (userConfig.historyMaxAgeHours !== undefined) {
+            target.historyMaxAgeHours = userConfig.historyMaxAgeHours;
+        }
+        if (userConfig.predictionShortWindowMinutes !== undefined) {
+            target.predictionShortWindowMinutes = userConfig.predictionShortWindowMinutes;
+        }
+        if (userConfig.pollingInterval !== undefined) {
+            target.pollingInterval = userConfig.pollingInterval;
+        }
+    }
+
+    /**
+     * Validates and normalizes configuration values.
+     */
+    private static async validateConfig(config: QuotaConfig): Promise<void> {
+        // Handle pollingInterval from user config
+        const validated = validatePollingInterval(config.pollingInterval as unknown);
+        if (validated === null) {
+            console.warn('[QuotaService] pollingInterval is invalid, using default');
+            config.pollingInterval = DEFAULT_CONFIG.pollingInterval;
+        } else if (validated < 10_000) {
+            console.warn('[QuotaService] pollingInterval below 10s is not recommended');
+            config.pollingInterval = Math.max(validated, 1_000);
+        } else {
+            config.pollingInterval = validated;
+        }
+    }
+}

package/src/services/history-service.ts

@@ -0,0 +1,116 @@
+import { writeFile, readFile } from "node:fs/promises";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { HISTORY_FILE } from "../utils/paths";
+import { type IHistoryService, type HistoryPoint, type QuotaData } from "../interfaces";
+import { logger } from "../logger";
+
+export class HistoryService implements IHistoryService {
+    private historyPath: string;
+    private data: Record<string, HistoryPoint[]> = {};
+    private maxWindowMs: number = 24 * 60 * 60 * 1000; // Keep 24 hours of history
+    private saveTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    constructor(customPath?: string) {
+        this.historyPath = customPath || HISTORY_FILE();
+    }
+
+    async init(): Promise<void> {
+        try {
+            const dir = join(this.historyPath, "..");
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+
+            if (existsSync(this.historyPath)) {
+                const raw = await readFile(this.historyPath, "utf-8");
+                this.data = JSON.parse(raw);
+            }
+        } catch (e) {
+            logger.error("history-service:init_failed", { path: this.historyPath, error: e });
+            this.data = {};
+        }
+    }
+
+    async append(snapshot: QuotaData[]): Promise<void> {
+        const timestamp = Date.now();
+        let changed = false;
+        
+        for (const quota of snapshot) {
+            if (!this.data[quota.id]) {
+                this.data[quota.id] = [];
+            }
+            
+            this.data[quota.id].push({
+                timestamp,
+                used: quota.used,
+                limit: quota.limit
+            });
+
+            // Prune old data for this quota
+            const cutoff = timestamp - this.maxWindowMs;
+            const originalLength = this.data[quota.id].length;
+            this.data[quota.id] = this.data[quota.id].filter(p => p.timestamp >= cutoff);
+            
+            if (this.data[quota.id].length !== originalLength || originalLength > 0) {
+                changed = true;
+            }
+        }
+
+        if (changed || snapshot.length > 0) {
+            this.save();
+        }
+    }
+
+    getHistory(quotaId: string, windowMs: number): HistoryPoint[] {
+        const now = Date.now();
+        const cutoff = now - windowMs;
+        const history = this.data[quotaId] || [];
+        return history.filter(p => p.timestamp >= cutoff);
+    }
+
+    setMaxAge(hours: number): void {
+        this.maxWindowMs = hours * 60 * 60 * 1000;
+    }
+
+    async pruneAll(): Promise<void> {
+        const now = Date.now();
+        const cutoff = now - this.maxWindowMs;
+        let changed = false;
+
+        for (const id in this.data) {
+            const originalLen = this.data[id].length;
+            this.data[id] = this.data[id].filter(p => p.timestamp >= cutoff);
+            
+            if (this.data[id].length !== originalLen) {
+                changed = true;
+            }
+
+            // Remove key if empty to free memory
+            if (this.data[id].length === 0) {
+                delete this.data[id];
+                changed = true;
+            }
+        }
+
+        if (changed) {
+            this.save();
+        }
+    }
+
+    private save(): void {
+        if (this.saveTimeout) {
+            clearTimeout(this.saveTimeout);
+        }
+
+        this.saveTimeout = setTimeout(async () => {
+            try {
+                await writeFile(this.historyPath, JSON.stringify(this.data, null, 2), "utf-8");
+                logger.debug("history-service:save_success", { path: this.historyPath });
+            } catch (e) {
+                logger.error("history-service:save_failed", { path: this.historyPath, error: e });
+            }
+            this.saveTimeout = null;
+        }, 5000);
+    }
+}