@tsa-group/claude-usage 0.3.1 → 0.3.3

package/dist/creds.js

@@ -11,8 +11,8 @@
  */
 import { spawnSync } from "node:child_process";
 import { userInfo } from "node:os";
-import { credsPath } from "./paths.js";
-import { readJson } from "./util.js";
+import { readFileSync } from "node:fs";
+import { claudeDir, credsPath } from "./paths.js";
 /** 可區分的結束碼 —— daemon 靠這個把「token 過期」和「網路壞掉」分開記錄。
  *  過去兩者都是 exit 1，daemon 只能寫 sample-failed，於是 2026-08-22 那次
  *  token 過期靜默死了 17.6 小時沒人發現。 */
@@ -24,11 +24,15 @@ export const EXIT = {
     NETWORK: 5,
 };
 export class CuError extends Error {
+    // ★ 刻意不用 constructor parameter property（`constructor(msg, readonly code)`）：
+    // tsc 吃得下，但 Node 的 strip-only 型別剝除**不支援**，於是 `node --test` 永遠
+    // 載不進這個模組 —— 這正是憑證這條路徑一路裸奔到第一台 Windows 機器才爆掉的原因。
+    // 出貨的是 dist/（tsc 編過），所以問題不會在生產顯現，只會讓它「無法被測試」。
     code;
     constructor(message, code) {
         super(message);
-        this.code = code;
         this.name = "CuError";
+        this.code = code;
     }
 }
 const KEYCHAIN_SERVICE = "Claude Code-credentials";
@@ -57,11 +61,40 @@ function fromKeychain() {
         return [null, "keychain-not-json"];
     }
 }
+/**
+ * 讀檔案版憑證。**每種失敗都有自己的名字。**
+ *
+ * 舊版一律回 `file-error:unreadable`，把「檔案不存在」「沒權限」「JSON 壞掉」
+ * 「有檔但沒 token」混成同一句話 —— 而這四種的處置完全不同（跑 /login vs 修權限
+ * vs 檔案損毀 vs 用的是 API key 而非 OAuth）。第一台 Windows 機器卡住時，那句話
+ * 讓人完全看不出該做什麼。
+ */
 function fromFile() {
-    const o = readJson(credsPath());
-    if (!o)
-        return [null, "file-error:unreadable"];
-    return [(o.claudeAiOauth ?? {}), "file"];
+    const path = credsPath();
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT")
+            return [null, "file-not-found"];
+        if (code === "EACCES" || code === "EPERM")
+            return [null, "file-no-permission"];
+        return [null, `file-error:${code ?? "unknown"}`];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [null, "file-bad-json"];
+    }
+    if (!parsed?.claudeAiOauth)
+        return [null, "file-no-oauth-key"];
+    if (!parsed.claudeAiOauth.accessToken)
+        return [null, "file-no-token"];
+    return [parsed.claudeAiOauth, "file"];
 }
 /**
  * 讀 access token。**刻意不做 refresh**：refresh token 若是一次性輪替，我們換完之後
@@ -74,12 +107,21 @@ export function loadToken() {
         const kcWhy = source;
         [o, source] = fromFile();
         if (!o?.accessToken) {
-            const hint = kcWhy === "keychain-locked"
-                ? " -> 解鎖 login keychain（不是重新登入）"
-                : kcWhy === "keychain-no-item"
-                    ? " -> 在 Claude Code 跑 /login"
-                    : "";
-            throw new CuError(`cannot read credentials (keychain: ${kcWhy}; file: ${source})${hint}`, EXIT.NO_TOKEN);
+            const hints = {
+                "keychain-locked": "解鎖 login keychain（不是重新登入）",
+                "keychain-no-item": "在 Claude Code 裡跑 /login",
+                "file-not-found": `找不到 ${credsPath()} —— 在 Claude Code 裡跑 /login；` +
+                    `若你用的是 API key / Bedrock / Vertex 而非帳號登入，本工具無法取得額度資訊`,
+                "file-no-permission": `沒有權限讀 ${credsPath()}`,
+                "file-bad-json": `${credsPath()} 不是合法 JSON（檔案損毀？）`,
+                "file-no-oauth-key": `${credsPath()} 裡沒有 claudeAiOauth —— 多半是用 API key 登入的`,
+                "file-no-token": `${credsPath()} 裡沒有 accessToken —— 在 Claude Code 裡跑 /login`,
+            };
+            const hint = hints[source] ?? hints[kcWhy] ?? "";
+            throw new CuError(`cannot read credentials (keychain: ${kcWhy}; file: ${source})` +
+                (hint ? `\n  -> ${hint}` : "") +
+                `\n  設定目錄: ${claudeDir()}` +
+                (process.env["CLAUDE_CONFIG_DIR"] ? "  (來自 CLAUDE_CONFIG_DIR)" : ""), EXIT.NO_TOKEN);
         }
     }
     if (o.expiresAt && Date.now() >= o.expiresAt) {

package/dist/daemon.js

@@ -207,7 +207,11 @@ export function printHealth() {
     row("last_tick_at", h.last_tick_at);
     row("last_sample_at", h.last_sample_at);
     row("last_sample_status", h.last_sample_status);
-    row("last_ok_at", h.last_ok_at + (h.last_ok_at_backfilled ? "  (從既有快照回填，非真的成功紀錄)" : ""));
+    // 不能先字串相加再交給 row()：h.last_ok_at 是 undefined 時 `undefined + ""` 會變成
+    // 字串 "undefined"，把 row() 的 `?? "-"` 完全繞過去（Sandy 那台就印出 undefined）。
+    row("last_ok_at", h.last_ok_at
+        ? h.last_ok_at + (h.last_ok_at_backfilled ? "  (從既有快照回填，非真的成功紀錄)" : "")
+        : "從未成功採樣過");
     row("consecutive_failures", h.consecutive_failures ?? 0);
     row("last_upload_state", h.last_upload_state);
     if (h.last_error)

package/dist/install.js

@@ -13,7 +13,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { claudeSettingsPath, devicePath, logPath, serverUrl, stateDir } from "./paths.js";
 import { printHealth } from "./daemon.js";
-import { enroll, enrollSecret } from "./upload.js";
+import { enroll } from "./upload.js";
 import { readJson, writeJsonAtomic } from "./util.js";
 const LABEL = "com.tsa.claude-usage";
 const WIN_TASK = "ClaudeUsage";
@@ -104,11 +104,22 @@ function winInstall() {
         "/TR", tr,
         "/RL", "LIMITED", "/F",
     ];
-    const r = spawnSync("schtasks", args, { encoding: "utf8" });
+    // 不設 encoding：Windows 主控台是本地碼頁（繁中是 CP950），用 utf8 解碼會變亂碼，
+    // 而亂碼會把「真正的錯誤訊息」也一起藏掉。rc 才是可靠的訊號。
+    const r = spawnSync("schtasks", args);
     console.log(`wrote ${VBS_PATH()}`);
-    console.log(`schtasks /Create: rc=${r.status} ${(r.stdout ?? r.stderr ?? "").trim()}`);
+    if (r.status === 0) {
+        console.log(`schtasks: 已建立工作 "${WIN_TASK}"，每 ${Math.max(1, Math.floor(BASE_INTERVAL_SEC / 60))} 分鐘執行一次`);
+    }
+    else {
+        // 失敗才印原始輸出。用 latin1 至少保證位元組不失真，並告訴使用者怎麼看到真訊息。
+        const raw = Buffer.concat([r.stdout ?? Buffer.alloc(0), r.stderr ?? Buffer.alloc(0)])
+            .toString("latin1").trim();
+        console.error(`schtasks 失敗 rc=${r.status}${raw ? ` (原始輸出可能因碼頁而亂碼: ${raw})` : ""}`);
+        console.error(`  手動執行這行可看到正確訊息: schtasks ${args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ")}`);
+    }
     console.log(`uninstall: schtasks /Delete /TN ${WIN_TASK} /F`);
-    console.log("! Windows 路徑尚未在真機驗證過 —— 裝完請跑 claude-usage status 確認有心跳");
+    console.log("! Windows 路徑尚未在真機完整驗證 —— 裝完請跑 claude-usage status 確認有心跳");
     return r.status ?? 1;
 }
 function winUninstall() {
@@ -118,9 +129,19 @@ function winUninstall() {
     return 0;
 }
 function winStatus() {
-    const r = spawnSync("schtasks", ["/Query", "/TN", WIN_TASK], { encoding: "utf8" });
-    console.log(r.status === 0 ? (r.stdout ?? "").trim() : "bg-task:   NOT installed (schtasks)");
-    return r.status ?? 1;
+    // 同 winInstall：不設 encoding。Windows 主控台是本地碼頁（繁中 CP950），用 utf8
+    // 解碼會把整段表格變成亂碼，而使用者要看的只是「這個工作在不在、下次何時跑」。
+    const r = spawnSync("schtasks", ["/Query", "/TN", WIN_TASK]);
+    if (r.status !== 0) {
+        console.log("bg-task:   NOT installed (schtasks)");
+        return r.status ?? 1;
+    }
+    // 只挑出下次執行時間那一段數字/日期，避開會亂碼的本地化欄位標題
+    const raw = (r.stdout ?? Buffer.alloc(0)).toString("latin1");
+    const when = raw.match(/\d{4}[/-]\d{1,2}[/-]\d{1,2}[^\r\n]*/)?.[0]?.trim();
+    console.log(`bg-task:   已註冊 "${WIN_TASK}"${when ? `，下次執行 ${when}` : ""}`);
+    console.log(`           完整資訊: schtasks /Query /TN ${WIN_TASK} /V /FO LIST`);
+    return 0;
 }
 const sessionStartGroups = (s) => s.hooks?.SessionStart ?? [];
 /**
@@ -216,8 +237,9 @@ export async function install(argv = []) {
     const os = platform();
     console.log(`claude-usage install (${os})${isDry(argv) ? " [DRY-RUN]" : ""}`);
     console.log(`  server = ${serverUrl()}   state = ${stateDir()}`);
-    if (!enrollSecret(argv) && !existsSync(devicePath())) {
-        console.log("  ! server 若有設 enroll 密語，請加 --enroll-secret <密語>");
+    if (!existsSync(devicePath())) {
+        // 註冊需要管理者核准，同事看到「裝好了但沒資料」時第一個要想到的就是這件事。
+        console.log("  ! 首次註冊後需管理者核准，核准前你的資料不會進來（這是正常的）");
     }
     await enrollStep(argv);
     registerHook(argv);

package/dist/paths.js

@@ -33,12 +33,21 @@ export const healthPath = () => join(stateDir(), "health.json");
 export const cursorPath = () => join(stateDir(), "cursor.json");
 /** daemon 的 stdout/stderr（背景任務寫的） */
 export const logPath = () => join(stateDir(), "daemon.log");
+/**
+ * Claude Code 的設定目錄。
+ *
+ * ★ 必須看 `CLAUDE_CONFIG_DIR`：那是 Claude Code 官方支援的搬家方式（Linux/Windows），
+ * 設了之後 `.credentials.json`、`projects/`、`settings.json` 全都在那底下。寫死
+ * `~/.claude` 的後果是「憑證讀不到」而且**錯誤訊息會指向一個根本不該去看的路徑** ——
+ * 2026-08-25 第一台 Windows 機器就是卡在憑證讀取，這是必須先排除的可能。
+ */
+export const claudeDir = () => process.env["CLAUDE_CONFIG_DIR"] || join(homedir(), ".claude");
 /** Claude Code 的 OAuth 憑證檔。**唯讀、永不上傳**（且在 mac 上只是過時副本，見 creds.ts） */
-export const credsPath = () => join(homedir(), ".claude", ".credentials.json");
+export const credsPath = () => join(claudeDir(), ".credentials.json");
 /** Claude Code 的 session JSONL 根目錄。唯讀 */
-export const projectsDir = () => join(homedir(), ".claude", "projects");
+export const projectsDir = () => join(claudeDir(), "projects");
 /** Claude Code 設定（SessionStart hook 註冊在這） */
-export const claudeSettingsPath = () => join(homedir(), ".claude", "settings.json");
+export const claudeSettingsPath = () => join(claudeDir(), "settings.json");
 export const DEFAULT_SERVER = "http://127.0.0.1:8787";
 export function config() {
     return readJson(configPath()) ?? {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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": {