coding-usage-bar 0.4.1 → 0.5.0

package/README.md

@@ -17,7 +17,7 @@ Claude Code and Codex data stays local and is read from files those tools alread
 
 ## Live SwiftBar Menu
 
-The screenshot is captured from the live SwiftBar plugin. The animation reproduces opening and closing that menu without altering the captured usage data.
+The menu bar title and the dropdown panel are captured from the live SwiftBar plugin and placed on a plain backdrop. The animation reproduces opening and closing that menu without altering the captured usage data.
 
 <p align="center">
   <img src="docs/assets/demo.gif" alt="Opening the live Coding Usage Bar SwiftBar menu with Codex, Claude, GLM, DeepSeek, MiniMax, and Kimi usage" width="800">
@@ -33,6 +33,16 @@ coding-usage-bar status
 
 `install` creates a local runtime at `~/.coding-usage-bar/app`, a user-level CLI shim at `~/.local/bin/coding-usage-bar`, a launchd agent, a default config file, and a SwiftBar menu bar plugin. Make sure `~/.local/bin` is in your `PATH`.
 
+## Troubleshooting
+
+**Menu bar icon not showing after install?**
+
+1. Run `coding-usage-bar doctor --fix`. It relaunches SwiftBar, reinstalls the menu bar plugin if missing, re-adds SwiftBar to login items, and collects status data.
+2. macOS may fold menu bar icons away: check System Settings → Control Center → Menu Bar.
+3. If macOS showed an Automation permission prompt (System Events) and it was denied, SwiftBar cannot auto-start at login: allow it under System Settings → Privacy & Security → Automation, then run `coding-usage-bar install` again.
+
+`coding-usage-bar install` verifies at the end that the plugin actually renders and prints `Menu bar ready`; if that line is missing, the numbered steps it prints tell you exactly what to do.
+
 ## Commands
 
 | Command | Purpose |
@@ -40,6 +50,7 @@ coding-usage-bar status
 | `coding-usage-bar install` | Install runtime, launchd checker, SwiftBar host/plugin, and Claude ingest when safe |
 | `coding-usage-bar uninstall` | Remove Coding Usage Bar managed launchd/status line/plugin config |
 | `coding-usage-bar doctor` | Check local Codex/Claude/GLM usage sources and notification backend |
+| `coding-usage-bar doctor --fix` | Repair common issues: missing SwiftBar/plugin, SwiftBar not running, login item, status data |
 | `coding-usage-bar status` | Print the rolling windows reported by each account and their pacing state from `~/.coding-usage-bar/status.json` |
 | `coding-usage-bar status --json` | Print the same status snapshot written to `~/.coding-usage-bar/status.json` |
 | `coding-usage-bar status --refresh` | Re-collect local usage before printing status |

package/README.zh-CN.md

@@ -12,7 +12,7 @@ Claude Code 与 Codex 的数据直接读取它们在本机产生的文件，不
 
 ## 真实 SwiftBar 菜单
 
-以下截图来自正在运行的 SwiftBar 插件；动画复现菜单的展开与收起，不修改截图中的用量数据。
+菜单栏标题与下拉面板均截自正在运行的 SwiftBar 插件，仅叠加纯色桌面背景；动画复现菜单的展开与收起，不修改截图中的用量数据。
 
 <p align="center">
   <img src="docs/assets/demo.gif" alt="打开 Coding Usage Bar 的真实 SwiftBar 菜单，查看 Codex、Claude、GLM、DeepSeek、MiniMax 和 Kimi 用量" width="800">
@@ -33,6 +33,16 @@ coding-usage-bar status
 - 每 5 分钟采集一次用量的 launchd 任务
 - 写入 SwiftBar 当前插件目录的菜单栏插件
 
+安装结束时会自动验收菜单栏是否就绪，最后一行出现 `Menu bar ready` 即表示图标已出现在菜单栏右上角。
+
+## 常见问题
+
+**安装后菜单栏没有图标？**
+
+1. 执行 `coding-usage-bar doctor --fix`：自动重启 SwiftBar、补装菜单栏插件、补加 SwiftBar 登录项、补采 status 数据。
+2. macOS 可能把菜单栏图标折叠隐藏了：系统设置 → 控制中心 → 菜单栏，检查隐藏区。
+3. 如果 macOS 弹过 System Events 的"自动化"权限框且被拒绝，SwiftBar 将无法开机自启：在 系统设置 → 隐私与安全性 → 自动化 中放行，再执行一次 `coding-usage-bar install`。
+
 ## 核心特点
 
 - 一个菜单栏同时查看多个 AI 编程 Provider

package/dist/cli.js

@@ -5,7 +5,7 @@ import { saveUsage } from "./store.js";
 import { formatStatusRows, formatAnalysisDetail, formatIssues, formatProviderMeta } from "./format.js";
 import { loadDisplayStatusSnapshot, collectStatusSnapshot } from "./runtime.js";
 import { runDaemonOnce } from "./daemon.js";
-import { doctorHasFailures, formatDoctor, runDoctor } from "./doctor.js";
+import { doctorHasFailures, formatDoctor, runDoctor, runDoctorFix } from "./doctor.js";
 import { installMenuBar, renderMenuBar, uninstallMenuBar, toggleCompactMode } from "./menubar.js";
 import { buildPaths } from "./paths.js";
 import { bakeGlyphAtlases } from "./glyphs.js";
@@ -20,7 +20,7 @@ function printHelp() {
 Usage:
   coding-usage-bar install [--dry-run]
   coding-usage-bar uninstall [--dry-run]
-  coding-usage-bar doctor [--dry-run]
+  coding-usage-bar doctor [--dry-run] [--fix]
   coding-usage-bar status [--fixtures] [--json] [--refresh]
   coding-usage-bar menubar render
   coding-usage-bar menubar install [--dry-run]
@@ -57,9 +57,21 @@ async function main() {
             return;
         }
         if (command === "doctor") {
+            const fix = hasFlag(args, "--fix");
+            if (fix) {
+                const fixes = await runDoctorFix({ dryRun });
+                if (fixes.length > 0) {
+                    console.log(fixes.join("\n"));
+                    console.log("");
+                }
+            }
             const checks = runDoctor({ dryRun });
             console.log(formatDoctor(checks));
             if (doctorHasFailures(checks)) {
+                if (!fix) {
+                    console.log("");
+                    console.log("Run coding-usage-bar doctor --fix to repair common issues automatically.");
+                }
                 process.exitCode = 1;
             }
             return;

package/dist/doctor.d.ts

@@ -2,5 +2,25 @@ import { DoctorCheck } from "./types.js";
 export declare function runDoctor(options?: {
     dryRun?: boolean;
 }): DoctorCheck[];
+export interface DoctorFixProbes {
+    swiftBarInstalled?: () => boolean;
+    pluginPresent?: () => boolean;
+    swiftBarRunning?: () => boolean;
+    swiftBarInLoginItems?: () => boolean | null;
+    statusFilePresent?: () => boolean;
+}
+export interface DoctorFixEffects {
+    installSwiftBar?: () => string[];
+    installPlugin?: () => string[];
+    launchSwiftBar?: () => string[];
+    addLoginItem?: () => string[];
+    collectStatus?: () => Promise<string[]>;
+}
+export interface DoctorFixOptions {
+    dryRun?: boolean;
+    probes?: DoctorFixProbes;
+    effects?: DoctorFixEffects;
+}
+export declare function runDoctorFix(options?: DoctorFixOptions): Promise<string[]>;
 export declare function formatDoctor(checks: DoctorCheck[]): string;
 export declare function doctorHasFailures(checks: DoctorCheck[]): boolean;

package/dist/doctor.js

@@ -7,7 +7,8 @@ import { isDir, isFile } from "./fs-util.js";
 import { resolveKimiConfig } from "./kimi.js";
 import { buildPaths, providerLatestPath } from "./paths.js";
 import { notificationBackend } from "./notifier.js";
-import { isSwiftBarInstalled, isSwiftBarRunning, swiftBarPluginPath } from "./menubar.js";
+import { addSwiftBarToLoginItems, ensureSwiftBarInstalled, installMenuBar, isSwiftBarInstalled, isSwiftBarInLoginItems, isSwiftBarRunning, openSwiftBar, swiftBarPluginPath, } from "./menubar.js";
+import { runDaemonOnce } from "./daemon.js";
 function stableClaudeIngestHint() {
     const paths = buildPaths();
     return `printf "%s" "$input" | node "${paths.stateDir}/app/dist/cli.js" ingest claude-statusline >/dev/null`;
@@ -240,17 +241,96 @@ export function runDoctor(options = {}) {
     const swiftBarRunning = pluginPresent && isSwiftBarRunning();
     checks.push({
         name: "Menu bar",
-        ok: pluginPresent,
+        ok: pluginPresent && swiftBarRunning,
         message: swiftBarInstalled
             ? isFile(swiftBarPlugin.file)
                 ? swiftBarRunning
                     ? `SwiftBar plugin installed and SwiftBar running: ${swiftBarPlugin.file}`
-                    : `SwiftBar plugin installed but SwiftBar is not running (menu bar item hidden); run: open -a SwiftBar`
-                : `SwiftBar found; run coding-usage-bar menubar install`
-            : "SwiftBar not found; install SwiftBar, then run coding-usage-bar menubar install",
+                    : "SwiftBar plugin installed but SwiftBar is not running (menu bar item hidden); run: coding-usage-bar doctor --fix"
+                : "SwiftBar found; run: coding-usage-bar doctor --fix"
+            : "SwiftBar not found; run: coding-usage-bar doctor --fix (installs SwiftBar via Homebrew)",
+    });
+    if (process.platform === "darwin") {
+        if (options.dryRun) {
+            checks.push({
+                name: "SwiftBar login item",
+                ok: true,
+                message: "[dry-run] would check whether SwiftBar auto-starts at login",
+            });
+        }
+        else if (!swiftBarInstalled) {
+            checks.push({
+                name: "SwiftBar login item",
+                ok: true,
+                message: "skipped (SwiftBar not installed)",
+            });
+        }
+        else {
+            const inLoginItems = isSwiftBarInLoginItems();
+            checks.push({
+                name: "SwiftBar login item",
+                ok: inLoginItems !== false,
+                message: inLoginItems === null
+                    ? "could not verify (Automation permission denied?); if the icon disappears after reboot, check System Settings → General → Login Items"
+                    : inLoginItems
+                        ? "SwiftBar auto-starts at login"
+                        : "not in login items; the menu bar icon disappears after reboot. Run: coding-usage-bar doctor --fix",
+            });
+        }
+    }
+    checks.push({
+        name: "Status data",
+        ok: options.dryRun ? true : isFile(paths.statusFile),
+        message: options.dryRun
+            ? `[dry-run] would read ${paths.statusFile}`
+            : isFile(paths.statusFile)
+                ? `found ${paths.statusFile}`
+                : `missing ${paths.statusFile}; run coding-usage-bar doctor --fix or coding-usage-bar daemon --once`,
     });
     return checks;
 }
+// One-command self-healing for the common "installed but the menu bar icon is
+// gone" failures: missing SwiftBar, missing plugin, SwiftBar not running,
+// SwiftBar missing from login items, and missing status data.
+export async function runDoctorFix(options = {}) {
+    if (options.dryRun) {
+        return ["[dry-run] would repair SwiftBar, the menu bar plugin, login items, and status data automatically"];
+    }
+    const paths = buildPaths();
+    const probes = {
+        swiftBarInstalled: options.probes?.swiftBarInstalled ?? isSwiftBarInstalled,
+        pluginPresent: options.probes?.pluginPresent ?? (() => isFile(swiftBarPluginPath(paths).file)),
+        swiftBarRunning: options.probes?.swiftBarRunning ?? isSwiftBarRunning,
+        swiftBarInLoginItems: options.probes?.swiftBarInLoginItems ?? isSwiftBarInLoginItems,
+        statusFilePresent: options.probes?.statusFilePresent ?? (() => isFile(paths.statusFile)),
+    };
+    const effects = {
+        installSwiftBar: options.effects?.installSwiftBar ?? (() => ensureSwiftBarInstalled()),
+        installPlugin: options.effects?.installPlugin ?? (() => installMenuBar()),
+        launchSwiftBar: options.effects?.launchSwiftBar ?? (() => openSwiftBar()),
+        addLoginItem: options.effects?.addLoginItem ?? (() => addSwiftBarToLoginItems()),
+        collectStatus: options.effects?.collectStatus ?? (async () => runDaemonOnce()),
+    };
+    const messages = [];
+    let swiftBarInstalled = probes.swiftBarInstalled();
+    if (!swiftBarInstalled) {
+        messages.push(...effects.installSwiftBar());
+        swiftBarInstalled = probes.swiftBarInstalled();
+    }
+    if (!probes.pluginPresent()) {
+        messages.push(...effects.installPlugin());
+    }
+    if (swiftBarInstalled && !probes.swiftBarRunning()) {
+        messages.push(...effects.launchSwiftBar());
+    }
+    if (probes.swiftBarInLoginItems() === false) {
+        messages.push(...effects.addLoginItem());
+    }
+    if (!probes.statusFilePresent()) {
+        messages.push(...(await effects.collectStatus()));
+    }
+    return messages;
+}
 export function formatDoctor(checks) {
     return checks
         .map((check) => `${check.ok ? "OK" : "MISSING"}  ${check.name}: ${check.message}`)

package/dist/install.js

@@ -5,7 +5,7 @@ import { execFileSync } from "node:child_process";
 import { claudeStatusLineHasIngest, getClaudeStatusLineCommand, readClaudeSettings } from "./claude.js";
 import { ensureConfig, readConfig } from "./config.js";
 import { ensureDir, isFile, readJsonFile, writeJsonAtomic } from "./fs-util.js";
-import { addSwiftBarToLoginItems, ensureSwiftBarInstalled, installMenuBar, openSwiftBar, uninstallMenuBar } from "./menubar.js";
+import { addSwiftBarToLoginItems, ensureSwiftBarInstalled, installMenuBar, openSwiftBar, uninstallMenuBar, verifyMenuBarSetup } from "./menubar.js";
 import { bakeGlyphAtlases } from "./glyphs.js";
 import { buildPaths } from "./paths.js";
 import { stableNodeExecutable } from "./node-runtime.js";
@@ -376,11 +376,13 @@ export function install(options = {}) {
     if (dryRun) {
         messages.push(`[dry-run] would write launchd plist: ${paths.launchAgentFile}`);
         messages.push(`[dry-run] ProgramArguments: ${[...args, "daemon", "--once"].join(" ")}`);
+        messages.push(...verifyMenuBarSetup({ dryRun }));
         return messages;
     }
     fs.writeFileSync(paths.launchAgentFile, xml, "utf8");
     restartLaunchAgent(paths.launchAgentFile);
     messages.push(`Installed and restarted launchd agent: ${paths.launchAgentFile}`);
+    messages.push(...verifyMenuBarSetup());
     return messages;
 }
 export function uninstall(options = {}) {

package/dist/menubar.d.ts

@@ -12,9 +12,24 @@ export declare function ensureSwiftBarInstalled(options?: {
 }): string[];
 export declare function isSwiftBarRunning(): boolean;
 export declare function openSwiftBar(): string[];
+export declare function isSwiftBarInLoginItems(): boolean | null;
 export declare function addSwiftBarToLoginItems(options?: {
     dryRun?: boolean;
 }): string[];
+export interface PluginRunResult {
+    ok: boolean;
+    output: string;
+}
+export interface VerifyMenuBarOptions {
+    dryRun?: boolean;
+    runPlugin?: (file: string) => PluginRunResult;
+    loginItems?: () => boolean | null;
+    swiftBarInstalled?: () => boolean;
+    swiftBarRunning?: () => boolean;
+    repairPlugin?: () => string[];
+    launchSwiftBar?: () => string[];
+}
+export declare function verifyMenuBarSetup(options?: VerifyMenuBarOptions): string[];
 export declare function renderMenuBar(snapshot?: StatusSnapshot, paths?: RuntimePaths, now?: Date): string;
 export declare function swiftBarStatusItemVisibilityKeys(defaultsOutput: string): string[];
 export declare function installMenuBar(options?: {

package/dist/menubar.js

@@ -268,22 +268,27 @@ export function openSwiftBar() {
     }
     return messages;
 }
-export function addSwiftBarToLoginItems(options = {}) {
-    const dryRun = options.dryRun ?? false;
-    const appPath = swiftBarAppPath();
-    if (!appPath) {
-        return ["SwiftBar is not installed; skipping login item."];
-    }
+// Whether SwiftBar auto-starts at login. Returns null when the login item list
+// cannot be queried (Automation permission denied or non-interactive context).
+export function isSwiftBarInLoginItems() {
     try {
         const result = execFileSync("osascript", [
             "-e", 'tell application "System Events" to get the name of every login item',
         ], { encoding: "utf8" });
-        if (result.includes("SwiftBar")) {
-            return ["SwiftBar already in login items."];
-        }
+        return result.split(",").map((name) => name.trim()).includes("SwiftBar");
     }
     catch {
-        // Permission or access issue; try to add anyway.
+        return null;
+    }
+}
+export function addSwiftBarToLoginItems(options = {}) {
+    const dryRun = options.dryRun ?? false;
+    const appPath = swiftBarAppPath();
+    if (!appPath) {
+        return ["SwiftBar is not installed; skipping login item."];
+    }
+    if (isSwiftBarInLoginItems()) {
+        return ["SwiftBar already in login items."];
     }
     if (dryRun) {
         return [`[dry-run] would add SwiftBar to login items: ${appPath}`];
@@ -298,6 +303,69 @@ export function addSwiftBarToLoginItems(options = {}) {
         return [`Failed to add SwiftBar to login items: ${error instanceof Error ? error.message : String(error)}. Add manually in System Settings → General → Login Items.`];
     }
 }
+// Execute the installed plugin exactly the way SwiftBar would and check it
+// produces a real menu. The plugin prints "Usage ERR" with exit code 0 on
+// failure, so a non-error status alone proves nothing.
+function runPluginScript(file) {
+    try {
+        const stdout = execFileSync(file, { encoding: "utf8", timeout: 30000 });
+        const output = stdout.trim();
+        return { ok: output.length > 0 && !output.startsWith("Usage ERR"), output };
+    }
+    catch (error) {
+        return { ok: false, output: error instanceof Error ? error.message : String(error) };
+    }
+}
+const MENU_BAR_MANUAL_STEPS = [
+    "Menu bar is NOT ready yet. Fix it with these steps:",
+    "  1. If macOS is showing an Automation/Accessibility permission prompt, click Allow.",
+    "  2. Open SwiftBar: open -a SwiftBar",
+    "  3. If the icon is still missing, macOS may have folded it away: System Settings → Control Center → Menu Bar.",
+    "  4. Re-run: coding-usage-bar doctor --fix",
+];
+const LOGIN_ITEM_WARNING = [
+    "WARN SwiftBar is not in login items: the menu bar icon will disappear after a reboot.",
+    "     If macOS showed a System Events Automation prompt, allow it and re-run coding-usage-bar install,",
+    "     or add SwiftBar manually: System Settings → General → Login Items.",
+];
+// End-to-end acceptance at the end of install: the plugin exists, SwiftBar is
+// running, and the plugin actually renders a menu. Auto-repairs once, then
+// falls back to numbered manual steps instead of failing silently.
+export function verifyMenuBarSetup(options = {}) {
+    if (options.dryRun) {
+        return ["[dry-run] would verify the SwiftBar plugin renders and the menu bar item appears"];
+    }
+    const paths = buildPaths();
+    const plugin = swiftBarPluginPath(paths);
+    const isInstalled = options.swiftBarInstalled ?? isSwiftBarInstalled;
+    const isRunning = options.swiftBarRunning ?? isSwiftBarRunning;
+    const messages = [];
+    if (!isInstalled()) {
+        return [
+            ...MENU_BAR_MANUAL_STEPS,
+            `  (SwiftBar is not installed. Install it with: brew install --cask swiftbar, then re-run coding-usage-bar install.)`,
+        ];
+    }
+    if (!isFile(plugin.file)) {
+        messages.push(...(options.repairPlugin ?? installMenuBar)());
+    }
+    if (!isRunning()) {
+        messages.push(...(options.launchSwiftBar ?? openSwiftBar)());
+    }
+    if (!isFile(plugin.file)) {
+        return [...messages, ...MENU_BAR_MANUAL_STEPS, `  (Plugin file missing: ${plugin.file})`];
+    }
+    const run = (options.runPlugin ?? runPluginScript)(plugin.file);
+    if (!run.ok || !isRunning()) {
+        return [...messages, ...MENU_BAR_MANUAL_STEPS];
+    }
+    messages.push("");
+    messages.push("Menu bar ready — Coding Usage Bar should now appear at the top-right of your menu bar.");
+    if ((options.loginItems ?? isSwiftBarInLoginItems)() === false) {
+        messages.push(...LOGIN_ITEM_WARNING);
+    }
+    return messages;
+}
 function swiftBarEscape(value) {
     return value.replaceAll("|", "\\|");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coding-usage-bar",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "macOS menu bar usage monitor for Claude Code, Codex, GLM, DeepSeek, and MiniMax.",
   "author": "hanzhangzzz",
   "license": "MIT",
@@ -29,7 +29,7 @@
   ],
   "type": "module",
   "bin": {
-    "coding-usage-bar": "./dist/cli.js"
+    "coding-usage-bar": "dist/cli.js"
   },
   "files": [
     "assets",