coding-usage-bar 0.1.0

package/dist/star.js

@@ -0,0 +1,117 @@
+import { execFileSync } from "node:child_process";
+import { readJsonFile, writeJsonAtomic } from "./fs-util.js";
+const REPO = "hanzhangzzz/coding-usage-bar";
+const PROMPT = "[coding-usage-bar] Enjoying Coding Usage Bar? Star it on GitHub? [y/N] ";
+function defaultIsInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+export function isStarConsent(answer) {
+    const normalized = answer.trim().toLowerCase();
+    return normalized === "y" || normalized === "yes";
+}
+function defaultConfirmStar(prompt) {
+    if (!defaultIsInteractive()) {
+        return false;
+    }
+    try {
+        const answer = execFileSync("/bin/sh", [
+            "-c",
+            'printf "%s" "$1" > /dev/tty; IFS= read -r answer < /dev/tty; printf "%s" "$answer"',
+            "coding-usage-bar-star-prompt",
+            prompt,
+        ], { encoding: "utf8" });
+        return isStarConsent(answer);
+    }
+    catch {
+        return false;
+    }
+}
+export function ghStarArgs(repo) {
+    return [
+        "api",
+        "--method",
+        "PUT",
+        `/user/starred/${repo}`,
+        "--silent",
+    ];
+}
+export function ghAuthStatusArgs() {
+    return ["auth", "status", "-h", "github.com"];
+}
+function commandErrorMessage(error) {
+    if (error && typeof error === "object") {
+        const stderr = error.stderr;
+        if (Buffer.isBuffer(stderr)) {
+            const message = stderr.toString("utf8").trim();
+            if (message) {
+                return message;
+            }
+        }
+        if (typeof stderr === "string" && stderr.trim()) {
+            return stderr.trim();
+        }
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function defaultStarRepo(repo) {
+    execFileSync("gh", ghStarArgs(repo), { stdio: "pipe" });
+}
+function defaultCanStarWithGh() {
+    try {
+        execFileSync("gh", ghAuthStatusArgs(), { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function canStarWithGh(options) {
+    if (typeof options.canStarWithGh === "boolean") {
+        return options.canStarWithGh;
+    }
+    if (typeof options.canStarWithGh === "function") {
+        return options.canStarWithGh();
+    }
+    return defaultCanStarWithGh();
+}
+function hasPromptState(paths) {
+    const state = readJsonFile(paths.starPromptFile);
+    return state?.repo === REPO && (state.outcome === "starred" || state.outcome === "skipped");
+}
+export function maybePromptForStar(paths, options) {
+    const env = options.env ?? process.env;
+    if (options.dryRun || env.CI || options.isInteractive === false || hasPromptState(paths)) {
+        return [];
+    }
+    if (options.isInteractive === undefined && !defaultIsInteractive()) {
+        return [];
+    }
+    if (!canStarWithGh(options)) {
+        return [];
+    }
+    const confirmStar = options.confirmStar ?? defaultConfirmStar;
+    const starRepo = options.starRepo ?? defaultStarRepo;
+    const now = options.now ?? (() => new Date());
+    const accepted = confirmStar(PROMPT);
+    const state = {
+        repo: REPO,
+        promptedAt: now().toISOString(),
+        response: accepted ? "accepted" : "declined",
+        outcome: accepted ? "starred" : "skipped",
+    };
+    if (!accepted) {
+        writeJsonAtomic(paths.starPromptFile, state);
+        return ["Skipped GitHub star prompt."];
+    }
+    try {
+        starRepo(REPO);
+        writeJsonAtomic(paths.starPromptFile, state);
+        return ["Starred Coding Usage Bar on GitHub."];
+    }
+    catch (error) {
+        state.outcome = "failed";
+        state.error = commandErrorMessage(error);
+        writeJsonAtomic(paths.starPromptFile, state);
+        return [`Could not star Coding Usage Bar with gh: ${state.error}`];
+    }
+}

package/dist/status.d.ts

@@ -0,0 +1,14 @@
+import { BurnProfile, ProviderUsage, RuntimePaths, StatusIssue, StatusSnapshot } from "./types.js";
+export declare function createStatusSnapshot(usages: ProviderUsage[], profile: BurnProfile, options?: {
+    paths?: RuntimePaths;
+    generatedAt?: Date;
+    fixtureSamples?: Map<string, ProviderUsage[]>;
+    issues?: StatusIssue[];
+    staleAfterSeconds?: number;
+}): StatusSnapshot;
+export declare function refreshStatusSnapshotFreshness(snapshot: StatusSnapshot, options?: {
+    now?: Date;
+    staleAfterSeconds?: number;
+}): StatusSnapshot;
+export declare function saveStatusSnapshot(snapshot: StatusSnapshot, paths?: RuntimePaths): void;
+export declare function loadStatusSnapshot(paths?: RuntimePaths): StatusSnapshot | null;

package/dist/status.js

@@ -0,0 +1,65 @@
+import { analyzeUsage } from "./burn.js";
+import { readJsonFile, writeJsonAtomic } from "./fs-util.js";
+import { buildPaths } from "./paths.js";
+import { loadSamples } from "./store.js";
+const DEFAULT_STALE_AFTER_SECONDS = 10 * 60;
+function buildProviderMeta(usage, generatedAt, staleAfterSeconds) {
+    const ageSeconds = Math.max(0, Math.round((generatedAt.getTime() - Date.parse(usage.observedAt)) / 1000));
+    return {
+        source: usage.source,
+        observedAt: usage.observedAt,
+        ageSeconds,
+        stale: ageSeconds > staleAfterSeconds,
+    };
+}
+function staleIssuesFor(providers) {
+    return providers
+        .filter((provider) => provider.meta.stale)
+        .map((provider) => ({
+        provider: provider.usage.provider,
+        severity: "warning",
+        code: "USAGE_STALE",
+        message: `${provider.usage.provider} usage is stale; latest observation is ${provider.meta.ageSeconds}s old.`,
+    }));
+}
+export function createStatusSnapshot(usages, profile, options = {}) {
+    const paths = options.paths ?? buildPaths();
+    const generatedAt = options.generatedAt ?? new Date();
+    const staleAfterSeconds = options.staleAfterSeconds ?? DEFAULT_STALE_AFTER_SECONDS;
+    const providers = usages.map((usage) => {
+        const fixtureSamples = options.fixtureSamples?.get(usage.provider);
+        const samples = fixtureSamples ?? loadSamples(usage.provider, paths);
+        return {
+            usage,
+            analysis: analyzeUsage(usage, samples.length > 0 ? samples : usages.filter((item) => item.provider === usage.provider), profile, generatedAt),
+            meta: buildProviderMeta(usage, generatedAt, staleAfterSeconds),
+        };
+    });
+    const staleIssues = staleIssuesFor(providers);
+    return {
+        generatedAt: generatedAt.toISOString(),
+        profile,
+        providers,
+        issues: [...(options.issues ?? []), ...staleIssues],
+    };
+}
+export function refreshStatusSnapshotFreshness(snapshot, options = {}) {
+    const now = options.now ?? new Date();
+    const staleAfterSeconds = options.staleAfterSeconds ?? DEFAULT_STALE_AFTER_SECONDS;
+    const providers = snapshot.providers.map((provider) => ({
+        ...provider,
+        meta: buildProviderMeta(provider.usage, now, staleAfterSeconds),
+    }));
+    const nonStaleIssues = snapshot.issues.filter((issue) => issue.code !== "USAGE_STALE");
+    return {
+        ...snapshot,
+        providers,
+        issues: [...nonStaleIssues, ...staleIssuesFor(providers)],
+    };
+}
+export function saveStatusSnapshot(snapshot, paths = buildPaths()) {
+    writeJsonAtomic(paths.statusFile, snapshot);
+}
+export function loadStatusSnapshot(paths = buildPaths()) {
+    return readJsonFile(paths.statusFile);
+}

package/dist/store.d.ts

@@ -0,0 +1,4 @@
+import { ProviderId, ProviderUsage, RuntimePaths } from "./types.js";
+export declare function saveUsage(usage: ProviderUsage, paths?: RuntimePaths): void;
+export declare function loadLatestUsage(provider: ProviderId, paths?: RuntimePaths): ProviderUsage | null;
+export declare function loadSamples(provider: ProviderId, paths?: RuntimePaths): ProviderUsage[];

package/dist/store.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import { appendJsonLine, readJsonFile, writeJsonAtomic } from "./fs-util.js";
+import { buildPaths, providerLatestPath, providerSamplesPath } from "./paths.js";
+export function saveUsage(usage, paths = buildPaths()) {
+    writeJsonAtomic(providerLatestPath(paths, usage.provider), usage);
+    appendJsonLine(providerSamplesPath(paths, usage.provider), usage);
+}
+export function loadLatestUsage(provider, paths = buildPaths()) {
+    return readJsonFile(providerLatestPath(paths, provider));
+}
+export function loadSamples(provider, paths = buildPaths()) {
+    const file = providerSamplesPath(paths, provider);
+    if (!fs.existsSync(file)) {
+        return [];
+    }
+    return fs
+        .readFileSync(file, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((item) => item !== null);
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+export type ProviderId = "claude" | "codex" | "glm" | "deepseek" | "minimax";
+export type WindowName = "five_hour" | "seven_day";
+export type BurnProfile = "low" | "high";
+export type BurnState = "RAW" | "UNDER_BURN" | "ON_TRACK" | "OVER_BURN" | "LIMIT_RISK";
+export interface UsageWindow {
+    name: WindowName;
+    windowMinutes: number;
+    usedPercent: number;
+    resetsAt: string;
+}
+export interface ProviderUsage {
+    provider: ProviderId;
+    source: string;
+    observedAt: string;
+    planType?: string | null;
+    windows: UsageWindow[];
+    balance?: {
+        total: string;
+        currency: string;
+        isAvailable: boolean;
+    };
+}
+export interface BurnAnalysis {
+    provider: ProviderId;
+    state: BurnState;
+    profile: BurnProfile;
+    observedAt: string;
+    fiveHour?: UsageWindow;
+    sevenDay?: UsageWindow;
+    target?: {
+        minPercent: number;
+        maxPercent: number;
+        recommendedPercent: number;
+        conversionRate: number;
+    };
+    message: string;
+}
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    message: string;
+}
+export interface GlmConfig {
+    baseUrl?: string;
+    apiKey?: string;
+}
+export interface DeepseekConfig {
+    apiKey?: string;
+}
+export interface MinimaxConfig {
+    region?: "cn" | "global";
+    apiKey?: string;
+}
+export interface RuntimePaths {
+    homeDir: string;
+    stateDir: string;
+    configFile: string;
+    claudeDir: string;
+    codexDir: string;
+    glmDir: string;
+    deepseekDir: string;
+    minimaxDir: string;
+    notificationStateFile: string;
+    statusFile: string;
+    starPromptFile: string;
+    cliBinDir: string;
+    cliBinFile: string;
+    swiftBarPluginDir: string;
+    swiftBarPluginFile: string;
+    launchAgentFile: string;
+    claudeSettingsFile: string;
+    claudeStatusLineScript: string;
+}
+export interface ProviderStatus {
+    usage: ProviderUsage;
+    analysis: BurnAnalysis;
+    meta: {
+        source: string;
+        observedAt: string;
+        ageSeconds: number;
+        stale: boolean;
+    };
+}
+export interface StatusIssue {
+    provider?: ProviderId;
+    severity: "warning" | "error";
+    code: string;
+    message: string;
+}
+export interface StatusSnapshot {
+    generatedAt: string;
+    profile: BurnProfile;
+    providers: ProviderStatus[];
+    issues: StatusIssue[];
+}
+export interface BurnConfig {
+    providers: ProviderId[];
+    glm?: GlmConfig;
+    deepseek?: DeepseekConfig;
+    minimax?: MinimaxConfig;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/usage.d.ts

@@ -0,0 +1,12 @@
+import { ProviderId, ProviderUsage, UsageWindow, WindowName } from "./types.js";
+export declare function normalizeWindow(name: WindowName, raw: unknown, fallbackMinutes: number): UsageWindow | null;
+export declare function findWindow(usage: ProviderUsage, name: WindowName): UsageWindow | undefined;
+export declare function validateProviderUsage(usage: ProviderUsage): void;
+export declare function makeProviderUsage(input: {
+    provider: ProviderId;
+    source: string;
+    observedAt?: string;
+    planType?: string | null;
+    fiveHour: UsageWindow;
+    sevenDay: UsageWindow;
+}): ProviderUsage;

package/dist/usage.js

@@ -0,0 +1,56 @@
+function asNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : null;
+    }
+    return null;
+}
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+export function normalizeWindow(name, raw, fallbackMinutes) {
+    if (raw === null || typeof raw !== "object") {
+        return null;
+    }
+    const record = raw;
+    const usedPercent = asNumber(record.used_percent ?? record.used_percentage);
+    const windowMinutes = asNumber(record.window_minutes ?? record.windowMinutes) ?? fallbackMinutes;
+    const resetsAtRaw = record.resets_at ?? record.resetsAt;
+    const resetsAt = typeof resetsAtRaw === "number"
+        ? new Date(resetsAtRaw * 1000).toISOString()
+        : asString(resetsAtRaw);
+    if (usedPercent === null || resetsAt === null) {
+        return null;
+    }
+    return {
+        name,
+        windowMinutes,
+        usedPercent,
+        resetsAt,
+    };
+}
+export function findWindow(usage, name) {
+    return usage.windows.find((window) => window.name === name);
+}
+export function validateProviderUsage(usage) {
+    const fiveHour = findWindow(usage, "five_hour");
+    const sevenDay = findWindow(usage, "seven_day");
+    if (!fiveHour || fiveHour.windowMinutes !== 300) {
+        throw new Error(`${usage.provider}: missing 5h usage window`);
+    }
+    if (!sevenDay || sevenDay.windowMinutes !== 10080) {
+        throw new Error(`${usage.provider}: missing 7d usage window`);
+    }
+}
+export function makeProviderUsage(input) {
+    return {
+        provider: input.provider,
+        source: input.source,
+        observedAt: input.observedAt ?? new Date().toISOString(),
+        planType: input.planType ?? null,
+        windows: [input.fiveHour, input.sevenDay],
+    };
+}

package/fixtures/claude/latest.json

@@ -0,0 +1,20 @@
+{
+  "provider": "claude",
+  "source": "fixture",
+  "observedAt": "2026-05-08T00:00:00.000Z",
+  "planType": null,
+  "windows": [
+    {
+      "name": "five_hour",
+      "windowMinutes": 300,
+      "usedPercent": 25,
+      "resetsAt": "2026-05-08T02:00:00.000Z"
+    },
+    {
+      "name": "seven_day",
+      "windowMinutes": 10080,
+      "usedPercent": 35,
+      "resetsAt": "2026-05-12T00:00:00.000Z"
+    }
+  ]
+}

package/fixtures/claude/samples.jsonl

@@ -0,0 +1,3 @@
+{"provider":"claude","source":"fixture","observedAt":"2026-05-07T22:00:00.000Z","planType":null,"windows":[{"name":"five_hour","windowMinutes":300,"usedPercent":5,"resetsAt":"2026-05-08T02:00:00.000Z"},{"name":"seven_day","windowMinutes":10080,"usedPercent":33,"resetsAt":"2026-05-12T00:00:00.000Z"}]}
+{"provider":"claude","source":"fixture","observedAt":"2026-05-07T23:00:00.000Z","planType":null,"windows":[{"name":"five_hour","windowMinutes":300,"usedPercent":15,"resetsAt":"2026-05-08T02:00:00.000Z"},{"name":"seven_day","windowMinutes":10080,"usedPercent":34,"resetsAt":"2026-05-12T00:00:00.000Z"}]}
+{"provider":"claude","source":"fixture","observedAt":"2026-05-08T00:00:00.000Z","planType":null,"windows":[{"name":"five_hour","windowMinutes":300,"usedPercent":25,"resetsAt":"2026-05-08T02:00:00.000Z"},{"name":"seven_day","windowMinutes":10080,"usedPercent":35,"resetsAt":"2026-05-12T00:00:00.000Z"}]}

package/fixtures/codex/latest.json

@@ -0,0 +1,20 @@
+{
+  "provider": "codex",
+  "source": "fixture",
+  "observedAt": "2026-05-08T00:00:00.000Z",
+  "planType": "pro",
+  "windows": [
+    {
+      "name": "five_hour",
+      "windowMinutes": 300,
+      "usedPercent": 92,
+      "resetsAt": "2026-05-08T00:45:00.000Z"
+    },
+    {
+      "name": "seven_day",
+      "windowMinutes": 10080,
+      "usedPercent": 41,
+      "resetsAt": "2026-05-13T00:00:00.000Z"
+    }
+  ]
+}

package/fixtures/codex/samples.jsonl

@@ -0,0 +1,3 @@
+{"provider":"codex","source":"fixture","observedAt":"2026-05-07T22:00:00.000Z","planType":"pro","windows":[{"name":"five_hour","windowMinutes":300,"usedPercent":20,"resetsAt":"2026-05-08T00:45:00.000Z"},{"name":"seven_day","windowMinutes":10080,"usedPercent":37,"resetsAt":"2026-05-13T00:00:00.000Z"}]}
+{"provider":"codex","source":"fixture","observedAt":"2026-05-07T23:00:00.000Z","planType":"pro","windows":[{"name":"five_hour","windowMinutes":300,"usedPercent":55,"resetsAt":"2026-05-08T00:45:00.000Z"},{"name":"seven_day","windowMinutes":10080,"usedPercent":39,"resetsAt":"2026-05-13T00:00:00.000Z"}]}
+{"provider":"codex","source":"fixture","observedAt":"2026-05-08T00:00:00.000Z","planType":"pro","windows":[{"name":"five_hour","windowMinutes":300,"usedPercent":92,"resetsAt":"2026-05-08T00:45:00.000Z"},{"name":"seven_day","windowMinutes":10080,"usedPercent":41,"resetsAt":"2026-05-13T00:00:00.000Z"}]}

package/fixtures/deepseek/latest.json

@@ -0,0 +1,12 @@
+{
+  "provider": "deepseek",
+  "source": "https://api.deepseek.com/user/balance",
+  "observedAt": "2026-05-19T12:00:00.000Z",
+  "planType": null,
+  "windows": [],
+  "balance": {
+    "total": "37.87",
+    "currency": "CNY",
+    "isAvailable": true
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "coding-usage-bar",
+  "version": "0.1.0",
+  "description": "macOS menu bar usage monitor for Claude Code, Codex, GLM, DeepSeek, and MiniMax.",
+  "author": "hanzhangzzz",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanzhangzzz/coding-usage-bar.git"
+  },
+  "homepage": "https://github.com/hanzhangzzz/coding-usage-bar#readme",
+  "bugs": {
+    "url": "https://github.com/hanzhangzzz/coding-usage-bar/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "openai",
+    "anthropic",
+    "macos",
+    "menu-bar",
+    "ai-coding",
+    "coding-plan",
+    "usage-monitor",
+    "quota-monitor",
+    "rate-limit",
+    "swiftbar",
+    "burn-rate"
+  ],
+  "type": "module",
+  "bin": {
+    "coding-usage-bar": "./dist/cli.js"
+  },
+  "files": [
+    "assets",
+    "docs/assets/hero.png",
+    "dist",
+    "fixtures",
+    "README.md",
+    "README.zh-CN.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli.js",
+    "test": "npm run build && node --test tests/*.test.js",
+    "clean": "rm -rf dist",
+    "prepack": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "darwin"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.9.3"
+  }
+}