@tsa-group/claude-usage 0.3.0 → 0.3.2

package/README.md

@@ -45,12 +45,20 @@ claude-usage configure --server https://<你們的 ingest host>
 # 2) 一鍵安裝：enroll（取得身份）+ 註冊 SessionStart hook + 背景任務
 #    先加 --dry-run 可預覽會做什麼、不動任何系統設定
 claude-usage install --dry-run
-claude-usage install --enroll-secret <管理者給你的密語>
+claude-usage install
 
 # 3) 確認狀態
 claude-usage status
 ```
 
+**兩個可能讓你以為「裝壞了」的情況：**
+
+- **server 開了人工核准** → `enroll` 會回 `status: pending`，你的資料要等管理者核准後才
+  開始進來。`status` 會顯示已 enroll、心跳正常，但 server 端看不到你的用量。這是正常的。
+- **server 要求 enroll 密語**（多數部署不需要）→ `install --enroll-secret <密語>`，或用
+  環境變數 `CLAUDE_USAGE_ENROLL_SECRET`。⚠️ 寫在指令列會留在你的 shell history 裡，
+  能用環境變數就用環境變數。
+
 安裝後會發生：
 
 - **hook**（開 session 時）：抓一筆即時額度快照。註冊在 `~/.claude/settings.json` 的
@@ -107,19 +115,20 @@ npm rm -g @tsa-group/claude-usage
 | 指令 | 用途 |
 |---|---|
 | `configure --server <url>` | 設定 ingest server 位址 |
-| `install [--enroll-secret <s>] [--dry-run]` | enroll + hook + 背景任務 |
+| `install [--dry-run]` | enroll + hook + 背景任務 |
 | `status` | 裝好了嗎？**採樣真的有在動嗎？** |
 | `uninstall` | 移除 hook 與背景任務 |
 | `show [--history]` | 看自己的額度水位 / 時間序 |
 | `sessions [--json]` | session 與 token 明細 |
 | `sample [--hook]` | 手動抓一筆額度快照 |
 | `daemon-tick [--explain]` | 背景排程器呼叫的單元；`--explain` 只印決策不採樣 |
-| `enroll [--enroll-secret <s>]` | 手動與 server 溝通取得身份 |
+| `enroll` | 手動與 server 溝通取得身份 |
 | `report [--full] [--dry-run]` | 手動上報。`--full` 忽略游標整包重送（重送是安全的） |
 | `health` | 背景任務心跳；不健康時 **exit 1**（可接監控） |
 
-`--enroll-secret` **刻意不寫進設定檔**：enroll 是一次性動作，把密語落地在每台機器上只是
-多開一個洩漏面。也可用環境變數 `CLAUDE_USAGE_ENROLL_SECRET`。
+`install` / `enroll` 都接受 `--enroll-secret <s>`，但**只有在 server 要求時才需要**。
+它不會被寫進設定檔；若要避免留在 shell history，改用環境變數
+`CLAUDE_USAGE_ENROLL_SECRET`。
 
 ---
 
@@ -199,8 +208,9 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
 - **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。
 - **`session_id` 跨 compaction / resume 不穩定**：session **數**會高估。token 與成本不受影響
   （那是 per-event 去重的，與 session 身份無關）。
-- **enroll 是 client 自報身份**：可偽造 email / org，共享密語擋得住路過的人，擋不住內部人。
-  要真正的身份保證需要 server 端接 SSO 或人工核准流程。
+- **enroll 是 client 自報身份**：profile 由 client 自己打 Anthropic 取得後轉送，理論上可
+  偽造 email / org。共享密語**不解決這件事**（知道密語的人一樣能冒充別人），它只擋路過的
+  流量。要真正的身份保證需要 server 端接 SSO / OIDC，或用人工核准流程把關。
 
 ---
 

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/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() {
@@ -216,8 +227,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,18 +1,30 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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": { "claude-usage": "dist/cli.js" },
-  "files": ["dist", "README.md"],
-  "engines": { "node": ">=20" },
+  "bin": {
+    "claude-usage": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.ts",
     "prepublishOnly": "npm run build && npm test",
     "check": "tsc -p tsconfig.json --noEmit"
   },
-  "keywords": ["claude", "usage", "telemetry", "cli"],
+  "keywords": [
+    "claude",
+    "usage",
+    "telemetry",
+    "cli"
+  ],
   "license": "UNLICENSED",
   "private": false,
   "devDependencies": {