@tsa-group/claude-usage 0.4.0 → 0.4.1

package/README.md

@@ -64,6 +64,34 @@ claude-usage install
 claude-usage status
 ```
 
+### Windows / PowerShell 首次執行
+
+多數 Windows 的 PowerShell 執行原則預設是 `Restricted`，會擋掉 npm 產生的 `.ps1`
+啟動器 —— **安裝成功、一執行就被擋**：
+
+```
+因為這個系統上已停用指令碼執行，所以無法載入 ...\npm\claude-usage.ps1
++ FullyQualifiedErrorId : UnauthorizedAccess  (PSSecurityException)
+```
+
+這**不是套件的問題**，`cmd.exe` 與 Node 本身都不受影響。擇一處理：
+
+```powershell
+# 1) 設定一次、永久生效、免系統管理員（推薦）
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+
+# 2) 不改原則，改叫 .cmd 啟動器（功能完全一樣）
+claude-usage.cmd status
+```
+
+`RemoteSigned` = 本機與 npm 的腳本可跑，只擋網路下載的未簽章腳本。
+公司用 GPO 鎖了機器層級原則時 (1) 會被覆寫 —— 直接用 (2)。
+現況查詢：`Get-ExecutionPolicy -List`
+
+> 安裝時若偵測到會擋的原則，`postinstall` 會主動提醒；事後也可用
+> `claude-usage.cmd doctor` 檢查。**但工具無法在被擋的當下自己說話** ——
+> PowerShell 在 Node 啟動前就拒絕了，所以這段提示只能寫在這裡。
+
 **兩個可能讓你以為「裝壞了」的情況：**
 
 - **server 開了人工核准** → `enroll` 會回 `status: pending`，你的資料要等管理者核准後才
@@ -222,8 +250,9 @@ 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`（執行時）。安裝用 `npm.cmd i -g …`；其餘見上面
+  「Windows / PowerShell 首次執行」。
 - **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.1",
   "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;