@tsa-group/claude-usage 0.3.3 → 0.3.5

package/dist/cli.js

@@ -6,6 +6,7 @@
  * prompt / 回應內容**永遠不離開這台機器**。
  */
 import { printHealth, tick } from "./daemon.js";
+import { doctor } from "./doctor.js";
 import { install, status, uninstall } from "./install.js";
 import { DEFAULT_SERVER, configPath, setConfig } from "./paths.js";
 import { enroll, report } from "./upload.js";
@@ -27,6 +28,7 @@ const HELP = `claude-usage v${VERSION} — per-user Claude usage collector
   enroll [--enroll-secret <密語>]
   report [--full] [--dry-run]
   health                  背景任務心跳；不健康時 exit 1
+  doctor                  自我診斷：印出解析到的路徑與那裡實際有什麼
   uninstall               移除 hook 與背景任務
 
 隱私：Claude OAuth token 與 prompt/回應內容永不離開本機。只送數字與帳號 email/uuid。`;
@@ -78,6 +80,8 @@ async function main() {
             return 0;
         case "health":
             return printHealth();
+        case "doctor":
+            return await doctor();
         case "enroll":
             return await enroll(argv);
         case "report":

package/dist/daemon.js

@@ -8,10 +8,10 @@
 import { statSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
-import { EXIT } from "./creds.js";
+import { EXIT, loadToken } from "./creds.js";
 import { healthWarning, lastSnapshot, loadHealth, saveHealth, } from "./health.js";
 import { devicePath, projectsDir } from "./paths.js";
-import { report } from "./upload.js";
+import { enroll, report } from "./upload.js";
 import { sample } from "./usage.js";
 import { nowIso, parseIso } from "./util.js";
 // ── 自適應策略 ──
@@ -137,8 +137,26 @@ export function decide() {
  * 都只記錄不拋出 —— daemon 絕不能因為上傳失敗就整個死掉。
  */
 async function flushUploads() {
-    if (!existsSync(devicePath()))
-        return "not-enrolled";
+    if (!existsSync(devicePath())) {
+        // install 當下 enroll 失敗（幾乎都是憑證還沒好）時，由這裡負責補上。
+        // 否則 install 印的「下次會自動重試」就是一句空話 —— 而使用者會合理地以為
+        // 自己不用再做什麼。第一台 Windows 機器就是這樣卡住的：憑證修好之後仍然
+        // 不會有任何資料，因為沒有人再跑一次 enroll。
+        try {
+            loadToken();
+        }
+        catch {
+            // 憑證還是壞的 -> 這次 enroll 必定失敗，安靜跳過，不要每 5 分鐘去騷擾 server
+            return "not-enrolled";
+        }
+        try {
+            if ((await enroll([])) !== 0)
+                return "enroll-failed";
+        }
+        catch {
+            return "enroll-failed";
+        }
+    }
     try {
         return (await report([])) === 0 ? "uploaded" : "upload-failed";
     }

package/dist/doctor.js

@@ -0,0 +1,168 @@
+/**
+ * `claude-usage doctor` — 把「為什麼不動」變成工具自己能回答的問題。
+ *
+ * 存在的理由：第一台 Windows 機器卡在憑證讀取時，錯誤訊息只說「讀不到」，於是
+ * 診斷變成「管理者手寫一段指令 → 請對方貼回來 → 猜 → 再寫一段」。這個迴圈每多一位
+ * 同事就重演一次，而卡住的人通常不知道自己卡住了。
+ *
+ * 原則：**印出「我解析到什麼路徑」與「那裡實際有什麼」，而不是只印結論。**
+ * 路徑對不對是使用者一眼就能判斷的事（「那不是我的 Claude Code 裝的地方」），
+ * 但前提是我們得把路徑印出來。
+ */
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir, platform, release, userInfo } from "node:os";
+import { join } from "node:path";
+import { EXIT, loadToken } from "./creds.js";
+import { claudeDir, claudeSettingsPath, configPath, credsPath, devicePath, projectsDir, serverUrl, stateDir, } from "./paths.js";
+import { healthWarning, loadHealth } from "./health.js";
+import { readJson } from "./util.js";
+import { VERSION } from "./version.js";
+const ok = (s) => `  [ok]   ${s}`;
+const bad = (s) => `  [BAD]  ${s}`;
+const info = (s) => `  [info] ${s}`;
+/** 目錄裡的 .jsonl 檔數與最新修改時間 —— 用來判斷 Claude Code 是不是真的在這裡跑 */
+function jsonlSummary(dir) {
+    let files = 0;
+    let newest = null;
+    const walk = (d, depth) => {
+        if (depth > 3)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = join(d, e.name);
+            if (e.isDirectory())
+                walk(p, depth + 1);
+            else if (e.name.endsWith(".jsonl")) {
+                files++;
+                try {
+                    const m = statSync(p).mtime;
+                    if (!newest || m > newest)
+                        newest = m;
+                }
+                catch {
+                    /* 檔案在走訪途中被換掉是正常的 */
+                }
+            }
+        }
+    };
+    walk(dir, 0);
+    return { files, newest };
+}
+export async function doctor() {
+    const problems = [];
+    const out = [];
+    out.push(`claude-usage doctor  v${VERSION}`);
+    out.push("");
+    out.push("環境");
+    out.push(info(`平台        ${platform()} ${release()}  node ${process.version}`));
+    out.push(info(`使用者      ${userInfo().username}`));
+    out.push(info(`家目錄      ${homedir()}`));
+    // ── Claude Code 的設定目錄 ──
+    out.push("");
+    out.push("Claude Code 資料");
+    const fromEnv = Boolean(process.env["CLAUDE_CONFIG_DIR"]);
+    out.push(info(`設定目錄    ${claudeDir()}${fromEnv ? "   <- 來自 CLAUDE_CONFIG_DIR" : "   (預設)"}`));
+    if (!existsSync(claudeDir())) {
+        out.push(bad(`設定目錄不存在 —— Claude Code 沒有在這個使用者/這台機器上跑過`));
+        problems.push(`找不到 ${claudeDir()}。若你的 Claude Code 跑在 WSL 或別的使用者底下，` +
+            `本工具要裝在同一個環境裡才看得到資料`);
+    }
+    else {
+        out.push(ok(`設定目錄存在`));
+    }
+    // ── 憑證 ──
+    // ⚠️ 這裡的呈現順序很重要。mac 的**主儲存是 Keychain**，`.credentials.json` 只是
+    // 可能過時的副本 —— 所以「檔案不存在」在 mac 上不是問題，在 Windows/Linux 上才是。
+    // 先前把兩者都印成 [BAD]/[ok]，結果出現「憑證檔不存在」緊接著「憑證可讀」這種
+    // 自相矛盾的畫面。判定一律以 loadToken() 的結果為準，上面兩行只是事實陳述。
+    const cp = credsPath();
+    const isMac = platform() === "darwin";
+    out.push(info(`憑證主儲存  ${isMac ? "macOS Keychain（檔案只是副本，可能過時）" : "檔案"}`));
+    out.push(info(`憑證檔      ${cp}  ->  ${existsSync(cp) ? `存在 ${statSync(cp).size} bytes` : "不存在"}` +
+        (!existsSync(cp) && !isMac ? "   <- 這個平台只有檔案這條路，所以是問題" : "")));
+    let credOk = false;
+    try {
+        const t = loadToken();
+        credOk = true;
+        out.push(ok(`憑證可讀（來源 ${t.source}，tier=${t.tier ?? "?"}，方案=${t.subscription ?? "?"}）`));
+    }
+    catch (e) {
+        const err = e;
+        out.push(bad(`憑證讀取失敗`));
+        for (const line of err.message.split("\n"))
+            out.push(`         ${line.trim()}`);
+        problems.push(err.code === EXIT.TOKEN_EXPIRED
+            ? "token 過期 —— 在 Claude Code 裡跑 /login"
+            : "讀不到憑證（細節見上）。本工具需要**帳號登入**（/login）；用 API key / Bedrock / Vertex 時取不到額度資訊");
+    }
+    // ── session 資料 ──
+    const pd = projectsDir();
+    out.push(info(`session 目錄 ${pd}`));
+    const js = jsonlSummary(pd);
+    if (js.files > 0) {
+        out.push(ok(`找到 ${js.files} 個 .jsonl，最新 ${js.newest?.toLocaleString() ?? "?"}`));
+    }
+    else {
+        out.push(bad(`沒有任何 .jsonl —— 這個目錄裡沒有 Claude Code 的使用紀錄`));
+        problems.push(`${pd} 是空的。最常見原因是 Claude Code 實際跑在別的地方（WSL、另一個 Windows 帳號、` +
+            `或設了 CLAUDE_CONFIG_DIR），本工具看的目錄和它不是同一個`);
+    }
+    // hook
+    const sp = claudeSettingsPath();
+    const settings = readJson(sp);
+    out.push(settings
+        ? ok(`settings.json 可讀（SessionStart 群組 ${settings.hooks?.SessionStart?.length ?? 0} 個）`)
+        : info(`settings.json 不存在或無法解析：${sp}`));
+    // ── 本工具自己的狀態 ──
+    out.push("");
+    out.push("claude-usage 狀態");
+    out.push(info(`狀態目錄    ${stateDir()}`));
+    out.push(info(`設定檔      ${configPath()}`));
+    out.push(info(`server      ${serverUrl()}`));
+    const enrolled = existsSync(devicePath());
+    out.push(enrolled ? ok("已註冊（device.json 存在）") : bad("尚未註冊 —— 沒有 device.json"));
+    if (!enrolled && credOk) {
+        problems.push("憑證正常但尚未註冊 —— 跑 claude-usage install（或 claude-usage enroll）");
+    }
+    const h = loadHealth();
+    if (Object.keys(h).length) {
+        const warn = healthWarning(h);
+        out.push(warn
+            ? bad(`採集狀態 UNHEALTHY：${warn}`)
+            : ok(`採集狀態正常（上次成功 ${h.last_ok_at ?? "-"}）`));
+        if (h.last_error)
+            out.push(`         上次錯誤: ${h.last_error}`);
+    }
+    else {
+        out.push(info("尚無 health 紀錄（背景任務還沒跑過）"));
+    }
+    // ── server 連通性 ──
+    try {
+        const r = await fetch(serverUrl() + "/v1/health", { signal: AbortSignal.timeout(10_000) });
+        out.push(r.ok ? ok(`server 可連線（HTTP ${r.status}）`) : bad(`server 回應 HTTP ${r.status}`));
+        if (!r.ok)
+            problems.push(`server 回應 ${r.status} —— 確認 configure --server 的位址正確`);
+    }
+    catch (e) {
+        out.push(bad(`server 連不上：${e.message}`));
+        problems.push("連不到 ingest server —— 檢查網路/VPN 與 configure --server 的位址");
+    }
+    out.push("");
+    if (problems.length === 0) {
+        out.push("結論：沒有發現問題。");
+    }
+    else {
+        out.push(`結論：${problems.length} 個問題`);
+        problems.forEach((p, i) => out.push(`  ${i + 1}. ${p}`));
+        out.push("");
+        out.push("把以上整段貼給管理者，通常一眼就能看出是哪一種。");
+    }
+    console.log(out.join("\n"));
+    return problems.length ? 1 : 0;
+}

package/dist/install.js

@@ -230,7 +230,12 @@ async function enrollStep(argv) {
             throw new Error("enroll returned non-zero");
     }
     catch (e) {
-        console.error(`enroll: FAILED (${e.message}) — hook/背景任務仍會安裝，下次 report 會自動重試`);
+        // 這句話必須與 daemon.flushUploads 的實際行為一致。它曾經承諾「會自動重試」
+        // 而程式碼並不會，於是卡住的人以為自己不用再做什麼。
+        console.error(`enroll: FAILED — ${e.message}`);
+        console.error("         hook 與背景任務仍會安裝。憑證問題解決後，背景任務會在 5 分鐘內自動完成註冊，" +
+            "不需要重跑 install。\n" +
+            "         先跑 claude-usage doctor 看是哪一種問題。");
     }
 }
 export async function install(argv = []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
   "type": "module",
   "bin": {