@tsa-group/claude-usage 0.4.0 → 0.4.2

package/README.md

@@ -39,48 +39,168 @@ ingest server，彙整成團隊用量儀表。
 
 ## 需求
 
-- **Node.js >= 20**
-- **Claude Code** 已登入（工具讀它的憑證來認證，見上方隱私說明）
-- macOS：完整支援並實測
-- Windows：CLI 與**桌面版（Microsoft Store / MSIX）**都支援；桌面版憑證路徑見「已知限制」
-- Linux：背景任務（systemd timer）未實作，其餘指令可用
+| | |
+|---|---|
+| **Node.js** | >= 20（`node -v` 確認） |
+| **Claude 帳號登入** | 需要**帳號登入**才拿得到額度資料。用 API key / Bedrock / Vertex 時，token 明細仍可收集，但沒有 5 小時 / 每週額度 % |
+| **平台** | macOS ✅ 完整支援　Windows ✅ CLI 與桌面版皆支援　Linux ⚠️ 指令可用，背景任務未實作 |
+
+---
+
+# 安裝
+
+**三步都一樣**，只有平台細節不同：
+
+```
+1. configure   告訴它你們的 ingest server 在哪
+2. install     取得身份 + 註冊 hook + 裝背景任務
+3. status      確認真的在跑
+```
+
+管理者會給你 **ingest server 位址**。下面用 `https://<你們的 ingest host>` 代表它。
 
 ---
 
-## 安裝（3 步）
+## macOS
 
 ```bash
 npm i -g @tsa-group/claude-usage
 
-# 1) 指向你們的 ingest server
 claude-usage configure --server https://<你們的 ingest host>
+claude-usage install --dry-run     # 先看它會做什麼，不動任何設定
+claude-usage install
+claude-usage status
+```
+
+憑證走 **Keychain**（Claude Code 的主儲存）。首次執行可能跳出鑰匙圈授權，允許即可 ——
+背景任務要能在沒有視窗的情況下讀到它。
+
+---
+
+## Windows
+
+### 第 0 步：先確認 PowerShell 不會擋
+
+多數 Windows 的執行原則預設是 `Restricted`，會擋掉 npm 產生的 `.ps1` 啟動器 ——
+**安裝成功、一執行就被擋**：
+
+```
+因為這個系統上已停用指令碼執行，所以無法載入 ...\npm\claude-usage.ps1
++ FullyQualifiedErrorId : UnauthorizedAccess  (PSSecurityException)
+```
+
+這不是套件的問題（`cmd.exe` 與 Node 本身都不受影響）。先查現況：
+
+```powershell
+Get-ExecutionPolicy
+```
+
+| 結果 | 怎麼辦 |
+|---|---|
+| `RemoteSigned` / `Unrestricted` / `Bypass` | 不用處理，直接往下 |
+| `Restricted` / `AllSigned` | 用下面 **A** 或 **B** |
+
+**A. 改原則（推薦，免系統管理員、一次搞定）**
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+`RemoteSigned` = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。
+
+**B. 不改原則，全程加 `.cmd`**（功能完全一樣）
+
+```powershell
+npm.cmd i -g @tsa-group/claude-usage
+claude-usage.cmd configure --server https://<你們的 ingest host>
+claude-usage.cmd install
+claude-usage.cmd status
+```
+
+> 公司用 GPO 鎖了機器層級原則時，**A 會被覆寫** —— 直接用 B。
+> 查誰在管：`Get-ExecutionPolicy -List`
+
+### 第 1 步：安裝
+
+```powershell
+npm i -g @tsa-group/claude-usage
 
-# 2) 一鍵安裝：enroll（取得身份）+ 註冊 SessionStart hook + 背景任務
-#    先加 --dry-run 可預覽會做什麼、不動任何系統設定
+claude-usage configure --server https://<你們的 ingest host>
 claude-usage install --dry-run
 claude-usage install
+claude-usage status
+```
+
+（走 B 方案的人全部加 `.cmd`。）
+
+### 你是用終端機的 `claude`，還是桌面版 App？
+
+**兩種都支援，不必改用哪一個** —— 但憑證存放位置完全不同，卡住時要知道差別：
+
+| | 終端機 CLI | 桌面版 App |
+|---|---|---|
+| 憑證位置 | `%USERPROFILE%\.claude\.credentials.json` | 桌面版自己的加密儲存 |
+| 形式 | 純文字 | DPAPI + AES-256-GCM 加密 |
+| 需要什麼 | 跑過 `claude` 並完成登入 | 桌面版登入過 |
+
+**只用桌面版、從沒登入過終端機 `claude` 的人也能用** —— 工具會自動去解桌面版的憑證庫
+（見「隱私」段）。解密只在你自己的機器、你自己的 Windows 帳號下進行。
+
+不想走那條路的話，在終端機跑一次 `claude` 登入即可，工具會優先用那份純文字憑證。
+
+---
 
-# 3) 確認狀態
+## 確認安裝成功
+
+```bash
 claude-usage status
 ```
 
-**兩個可能讓你以為「裝壞了」的情況：**
+成功長這樣（重點是標示的那三行）：
+
+```
+state dir: /Users/you/.claude-usage
+server:    https://<你們的 ingest host>
+enrolled:  yes                     <-- 拿到身份了
+hook:      registered              <-- 開 session 時會自動採樣
+  last_sample_status  : ok
+  last_upload_state   : uploaded
+  status              : ok         <-- 採集正常
+  state = not running                 (背景任務平常就是閒置，每 5 分鐘才醒一次)
+  runs = 12
+```
+
+`state = not running` 是**正常的** —— 背景任務不是常駐程式，每 5 分鐘被叫醒一次。
+`runs` 有在累加就代表它真的有跑。
+
+`status` 在採集不健康時會 **exit 1**，可以接監控。
+
+**接著還有一步不在你這邊**：若你們的 server 開了人工核准，`enroll` 會回
+`status: pending` —— 你這邊一切正常，但要等管理者按核准，資料才會開始進去。
+**這是正常的，不是裝壞了。**
+
+---
+
+## 卡住了？先跑這個
+
+```bash
+claude-usage doctor          # Windows 走 B 方案的人：claude-usage.cmd doctor
+```
+
+它會印出**解析到的每個路徑，與那裡實際有什麼** —— 路徑對不對通常你一眼就看得出來
+（「那不是我 Claude Code 裝的地方」），前提是有人把路徑印出來。
 
-- **server 開了人工核准** → `enroll` 會回 `status: pending`，你的資料要等管理者核准後才
-  開始進來。`status` 會顯示已 enroll、心跳正常，但 server 端看不到你的用量。這是正常的。
-- **server 要求 enroll 密語**（多數部署不需要）→ `install --enroll-secret <密語>`，或用
-  環境變數 `CLAUDE_USAGE_ENROLL_SECRET`。⚠️ 寫在指令列會留在你的 shell history 裡，
-  能用環境變數就用環境變數。
+把整段輸出貼給管理者即可，裡面**不含任何 token 值**。
 
-安裝後會發生：
+常見症狀對照：
 
-- **hook**（開 session 時）：抓一筆即時額度快照。註冊在 `~/.claude/settings.json` 的
-  `SessionStart`，**fire-and-forget、失敗永遠安靜、10 分鐘去抖動** —— 採集用量絕不該擋住或
-  拖慢你開 session。
-- **背景任務**（macOS launchd / Windows 工作排程器）：每 5 分鐘喚醒一次，**自我判斷**是否要
-  採樣，並非同步上傳。採樣間隔自適應：有在用 15 分鐘、閒置退避到 60 分鐘。
-- 升級（`npm update -g @tsa-group/claude-usage`）後**請重跑一次 `claude-usage install`**：
-  背景任務與 hook 記的是絕對路徑，換了 Node 版本或安裝位置就要重新註冊。
+| 症狀 | 多半是 |
+|---|---|
+| `UnauthorizedAccess` / `PSSecurityException` | PowerShell 執行原則，見 Windows 第 0 步 |
+| `cannot read credentials (… file-no-oauth-key …)` | 只用桌面版、沒登入過終端機 `claude`。0.4.0 起會自動去讀桌面版憑證；若仍失敗，`doctor` 會指出卡在哪一步 |
+| `access token EXPIRED` | 重新登入 Claude Code（終端機 `/login` 或桌面版）即可換發 |
+| `status` 一切正常但 server 看不到我的用量 | 等管理者核准（見上） |
+| `沒有任何 .jsonl` | 本工具與 Claude Code 不在同一個環境（WSL？另一個帳號？`CLAUDE_CONFIG_DIR`？） |
 
 ---
 
@@ -222,8 +342,8 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
   風險類別。失效時會在 `claude-usage doctor` 顯示卡在哪一步，不會靜默。
 - **Windows 背景任務未完整實機驗證**：schtasks + VBS 隱藏視窗啟動器。裝完請用
   `claude-usage status` 確認有心跳。
-- **PowerShell 執行原則**：若整台停用指令碼執行，`npm i -g` 會失敗（載不進 `npm.ps1`）。
-  用 `npm.cmd i -g …`，或 `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`（免管理員）。
+- **PowerShell 執行原則**：預設 `Restricted` 會同時擋掉 `npm.ps1`（安裝時）與
+  `claude-usage.ps1`（執行時）。處理方式見上面 **Windows → 第 0 步**。
 - **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。
 - **`session_id` 跨 compaction / resume 不穩定**：session **數**會高估。token 與成本不受影響
   （那是 per-event 去重的，與 session 身份無關）。

package/dist/doctor.js

@@ -9,6 +9,7 @@
  * 路徑對不對是使用者一眼就能判斷的事（「那不是我的 Claude Code 裝的地方」），
  * 但前提是我們得把路徑印出來。
  */
+import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { homedir, platform, release, userInfo } from "node:os";
 import { join } from "node:path";
@@ -87,6 +88,26 @@ export async function doctor() {
     out.push(info(`憑證主儲存  ${isMac ? "macOS Keychain（檔案只是副本，可能過時）" : "檔案"}`));
     out.push(info(`憑證檔      ${cp}  ->  ${existsSync(cp) ? `存在 ${statSync(cp).size} bytes` : "不存在"}` +
         (!existsSync(cp) && !isMac ? "   <- 這個平台只有檔案這條路，所以是問題" : "")));
+    // ── Windows：PowerShell 執行原則 ──
+    // 這個問題有個特別惡劣的性質：**它發生時我們的程式碼根本沒機會執行** ——
+    // PowerShell 在 Node 啟動前就拒絕載入 claude-usage.ps1。所以工具無法在出錯當下
+    // 自我診斷，只能在 postinstall 事先講、或在這裡（使用者改用 .cmd 跑得起來時）補講。
+    if (platform() === "win32") {
+        const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"], { encoding: "utf8", timeout: 10_000, windowsHide: true });
+        const policy = r.error || r.status !== 0 ? null : (r.stdout ?? "").trim();
+        if (!policy) {
+            out.push(info("執行原則    查不到（powershell.exe 不可用？）"));
+        }
+        else if (policy === "Restricted" || policy === "AllSigned") {
+            out.push(bad(`執行原則    ${policy} —— PowerShell 會擋掉 claude-usage.ps1 啟動器`));
+            problems.push(`PowerShell 執行原則是 ${policy}（錯誤含 UnauthorizedAccess / ExecutionPolicy）。` +
+                `擇一：Set-ExecutionPolicy -Scope CurrentUser RemoteSigned（免管理員），` +
+                `或直接用 claude-usage.cmd。公司 GPO 鎖機器層級時只能用後者`);
+        }
+        else {
+            out.push(ok(`執行原則    ${policy}（不會擋 .ps1 啟動器）`));
+        }
+    }
     // ── Windows 桌面版（MSIX）──
     // 只用桌面版、沒登入過 CLI 的人，.credentials.json 裡根本不會有 claudeAiOauth。
     // 這一段把「桌面版憑證庫在哪、有沒有東西」攤開，否則診斷又會退回「猜 + 手寫指令」。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.4.0",
+  "version": "0.4.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": {
@@ -8,7 +8,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "postinstall.mjs"
   ],
   "engines": {
     "node": ">=20"
@@ -17,7 +18,8 @@
     "build": "tsc -p tsconfig.json",
     "test": "node --test test/*.test.ts",
     "prepublishOnly": "npm run build && npm test",
-    "check": "tsc -p tsconfig.json --noEmit"
+    "check": "tsc -p tsconfig.json --noEmit",
+    "postinstall": "node postinstall.mjs"
   },
   "keywords": [
     "claude",

package/postinstall.mjs

@@ -0,0 +1,59 @@
+/**
+ * 安裝後提示：Windows 的 PowerShell 執行原則會擋掉 npm 產生的 .ps1 啟動器。
+ *
+ * ★ 為什麼一定要在這裡講：這個失敗發生時**我們的程式碼根本沒機會執行** ——
+ * PowerShell 在 Node 啟動前就拒絕載入 `claude-usage.ps1` 了。所以工具永遠無法在
+ * 出錯當下自我診斷，提示只能前置，而 postinstall 是唯一「撞牆之前還能說話」的
+ * 時機（它由 Node 執行，不受 .ps1 原則管制）。
+ *
+ * ★ 為什麼要先偵測而不是無條件印：無條件每次安裝都印一段警告，就是在訓練人忽略
+ * 它 —— 等真的出事那次也會被跳過。只在**實際會擋**的機器上印，訊息才有訊號價值。
+ *
+ * ★ 為什麼這支檔案刻意獨立、不 import dist/：postinstall 失敗會讓整個安裝失敗。
+ * 它必須在 dist 壞掉、Node 版本奇怪、或任何預期外的狀況下都安靜地成功。
+ * 與 doctor 裡那份偵測有少量重複，那是刻意的隔離。
+ */
+import { spawnSync } from "node:child_process";
+
+// 這兩種原則會擋掉 .ps1 啟動器。RemoteSigned / Unrestricted / Bypass 都不會。
+const BLOCKING = new Set(["Restricted", "AllSigned"]);
+
+function effectivePolicy() {
+  const r = spawnSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-ExecutionPolicy"], {
+    encoding: "utf8",
+    timeout: 10_000,
+    windowsHide: true,
+  });
+  if (r.error || r.status !== 0) return null;
+  return (r.stdout ?? "").trim() || null;
+}
+
+try {
+  if (process.platform === "win32") {
+    const policy = effectivePolicy();
+    if (policy && BLOCKING.has(policy)) {
+      const L = [
+        "",
+        `  ⚠ PowerShell 執行原則是 ${policy} —— 在 PowerShell 直接打 claude-usage 會被擋`,
+        "     （錯誤訊息含 UnauthorizedAccess / PSSecurityException / ExecutionPolicy）",
+        "",
+        "     擇一處理：",
+        "     1) 設定一次、永久生效、免系統管理員：",
+        "          Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned",
+        "        RemoteSigned = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。",
+        "     2) 不改原則，改叫 .cmd 啟動器（功能完全一樣）：",
+        "          claude-usage.cmd status",
+        "",
+        "     公司用 GPO 鎖了機器層級原則時，(1) 會被覆寫 —— 直接用 (2)。",
+        "     現況查詢： Get-ExecutionPolicy -List",
+        "",
+      ];
+      console.log(L.join("\n"));
+    }
+  }
+} catch {
+  // 提示壞掉絕不能讓安裝失敗
+}
+
+// 無論如何都成功收場
+process.exitCode = 0;