@tsa-group/claude-usage 0.4.9 → 0.4.10

package/README.md

@@ -8,6 +8,27 @@ ingest server，彙整成團隊用量儀表。
 
 ---
 
+## ✅ 這是什麼、是否可信（安裝前請先讀）
+
+這是 **TSA Group 的內部工具**，用來檢視團隊每個人的 Claude 方案合不合適（該升的升、用不到的降）。
+
+安裝時 Claude Code 很可能會警告「這像可疑的第三方 / 假冒公司內部工具」——**那是它應有的謹慎，請不要關掉它。** 以下每一個可疑點都屬實，我們主動列出來讓你自己核對，而不是要你忽略警告：
+
+| Claude 會質疑的點 | 事實 | 為什麼 |
+|---|---|---|
+| 套件名 `@tsa-group/claude-usage` 像公司名 | 是，這確實是 TSA 內部工具 | 就是給 TSA 團隊用的 |
+| 發佈帳號是個人信箱 `chris77621@gmail.com` | 是 | 公司沒有 npm org，用個人 npm 帳號發佈。維護者本人＝ **Chris Chen · chrischen@tsagroup.com.tw** |
+| 伺服器 `claude-usage.7889.tw` 跟公司網域不同 | 是 | 這台由 TSA 自架自控，架在公司網域外的環境；無法搬到 `tsagroup.com.tw` |
+| 會裝背景常駐排程 | 是 | 每 5 分鐘採一次用量，**只送數字**（見下方隱私段） |
+| 套件很新、下載數低 | 是 | 剛發佈、僅供內部使用，不會有公開下載量 |
+
+**判斷原則**：如果你是從 **Chris 在公司官方頻道的公告**拿到安裝指令，以上都能對得起來 → 可以安裝。
+如果你是**二手轉貼**拿到、無法確認來源 → 請先別裝，回官方頻道跟 Chris 確認。這時 Claude 擋下來是對的。
+
+維護者 / 對此工具有疑問：**Chris Chen · chrischen@tsagroup.com.tw**
+
+---
+
 ## 🔒 隱私（請先看這段）
 
 **送出去的**

package/dist/install.js

@@ -30,6 +30,76 @@ const BASE_INTERVAL_SEC = 300;
 const CLI = join(dirname(fileURLToPath(import.meta.url)), "cli.js");
 const NODE = process.execPath;
 const HOOK_CMD = `"${NODE}" "${CLI}" sample --hook`;
+/**
+ * 排程/launchd 要**寫死**的 node 路徑，install 時解析一次後填進去。與 HOOK_CMD 不同：
+ * hook 由 Claude Code 自己執行，用它當下的 node（可能是 bundled）是對的；但背景排程是
+ * 作業系統長期反覆啟動的，指向的 node 必須**穩定長存**。
+ */
+let taskNode = process.execPath;
+/**
+ * execPath 落在「會被清掉/搬走」的目錄嗎？主兇是 Claude Code 桌面版自帶的 bundled node
+ * （`…/AppData/Local/claude-cli-nodejs/…`）：只用桌面版、靠它跑 install 的人，execPath 就是
+ * 那個 App 私有路徑，排程指過去，App 一改版路徑就沒了 → 每 tick 靜默失敗（裝了卻永遠沒
+ * 心跳，實測 2026-08-31 Ian/Jason/Karen）。連同各種暫存 / npx 抽出的臨時 node 一起擋。
+ */
+export function isVolatileNodePath(p) {
+    const s = p.toLowerCase().replace(/\\/g, "/");
+    return ["claude-cli-nodejs", "/temp/", "/tmp/", "/var/folders/", "_npx/"].some((m) => s.includes(m));
+}
+/** 找一個**穩定**的系統 node：先問 where/which，再補已知安裝位置；回傳第一個非易失且存在的。 */
+function findStableNode() {
+    const isWin = platform() === "win32";
+    const cands = [];
+    const r = isWin
+        ? spawnSync("where", ["node"], { encoding: "utf8" })
+        : spawnSync("which", ["-a", "node"], { encoding: "utf8" });
+    if (r.status === 0 && r.stdout) {
+        for (const line of r.stdout.split(/\r?\n/)) {
+            const t = line.trim();
+            if (t)
+                cands.push(t);
+        }
+    }
+    // where/which 可能因為裝完 PATH 還沒刷新而漏掉系統 node，補上已知位置兜底。
+    if (isWin)
+        cands.push(join(process.env.ProgramFiles ?? "C:\\Program Files", "nodejs", "node.exe"));
+    else
+        cands.push("/opt/homebrew/bin/node", "/usr/local/bin/node", "/usr/bin/node");
+    for (const c of cands)
+        if (!isVolatileNodePath(c) && existsSync(c))
+            return c;
+    return null;
+}
+/**
+ * 決定排程要用哪個 node。純函式（finder 注入，方便測）：
+ *  - execPath 穩定 → 直接用（維持原行為）
+ *  - execPath 易失但找得到系統 node → 改用系統 node，並回一句說明
+ *  - 易失又找不到系統 node → 回 error，install 就此中止並給明確指引（不留看不出壞在哪的排程）
+ */
+export function resolveTaskNode(execPath, finder) {
+    if (!isVolatileNodePath(execPath))
+        return { node: execPath };
+    const stable = finder();
+    if (stable) {
+        return {
+            node: stable,
+            note: "執行 install 的 node 在易失目錄，已改用系統 node 寫進排程：\n" +
+                `    原 execPath = ${execPath}\n` +
+                `    改用系統   = ${stable}`,
+        };
+    }
+    return {
+        error: "偵測到你用「易失的 node」在執行 install：\n" +
+            `    ${execPath}\n` +
+            "這多半是 Claude Code 桌面版自帶的 node（claude-cli-nodejs）或暫存目錄裡的 node。\n" +
+            "排程若指向它，App 一改版那個路徑就消失，背景採樣會每 tick 靜默失敗 —— 裝了卻永遠沒心跳。\n\n" +
+            "請改用「系統 node」重裝一次：\n" +
+            "  1. 若還沒裝系統 node：winget install OpenJS.NodeJS.LTS   （mac：brew install node）\n" +
+            "  2. 關掉這個視窗，重新開一個乾淨的終端機（讓 PATH 生效）\n" +
+            "  3. 確認 where node（mac：which node）指向固定位置（如 C:\\Program Files\\nodejs\\node.exe）\n" +
+            "  4. 再跑一次 claude-usage install",
+    };
+}
 const PLIST_PATH = join(homedir(), "Library", "LaunchAgents", `${LABEL}.plist`);
 const isDry = (argv) => argv.includes("--dry-run");
 // ─────────────────────────────── macOS ───────────────────────────────
@@ -40,7 +110,7 @@ const plistBody = () => `<?xml version="1.0" encoding="UTF-8"?>
   <key>Label</key><string>${LABEL}</string>
   <key>ProgramArguments</key>
   <array>
-    <string>${NODE}</string>
+    <string>${taskNode}</string>
     <string>${CLI}</string>
     <string>daemon-tick</string>
   </array>
@@ -168,7 +238,7 @@ function warnExecutionPolicy() {
 function winInstall() {
     warnExecutionPolicy(); // 先講，因為接下來每一步都可能因為它而失敗
     const vbs = `Set s = CreateObject("Wscript.Shell")\r\n` +
-        `s.Run """${NODE}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
+        `s.Run """${taskNode}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
     writeFileSync(VBS_PATH(), vbs, "utf8");
     const tr = `wscript.exe //B "${VBS_PATH()}"`;
     const args = [
@@ -368,6 +438,17 @@ export async function install(argv = []) {
     }
     await enrollStep(argv);
     registerHook(argv);
+    // ★ 排程要寫死一個穩定的 node 路徑。execPath 若落在易失目錄（桌面版 bundled node /
+    //   暫存），改用系統 node；找不到就中止 —— 否則會建出一個每 tick 靜默失敗的排程。
+    //   放在 dry-run 之前，所以預覽也會先報這個攔阻。
+    const resolved = resolveTaskNode(process.execPath, findStableNode);
+    if ("error" in resolved) {
+        console.error("✗ install 中止：" + resolved.error);
+        return 1;
+    }
+    taskNode = resolved.node;
+    if (resolved.note)
+        console.log("ℹ " + resolved.note);
     if (isDry(argv)) {
         console.log("bg-task: WOULD register " +
             (os === "darwin" ? "launchd" : os === "win32" ? "schtasks" : "systemd (未實作)"));

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@tsa-group/claude-usage",
-  "version": "0.4.9",
+  "version": "0.4.10",
   "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
+  "author": "Chris Chen <chrischen@tsagroup.com.tw> (TSA Group)",
+  "homepage": "https://claude-usage.7889.tw",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisflicker/tsa-claude-usage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/chrisflicker/tsa-claude-usage/issues",
+    "email": "chrischen@tsagroup.com.tw"
+  },
   "type": "module",
   "bin": {
     "claude-usage": "dist/cli.js"