@tsa-group/claude-usage 0.4.6 → 0.4.8

package/README.md

@@ -332,6 +332,21 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
 
 ---
 
+## 自動更新
+
+v0.4.7 起支援自我更新，但**由伺服器決定**，不是去問 npm：
+
+- 版本資訊搭 `/v1/report` 的回應回來，**零額外網路呼叫**（daemon 每 5 分鐘一次，
+  若各自去問 npm registry 會變成每台每天 288 次）
+- 伺服器指定**確切版本號**，不是 `@latest` —— 有人拿到 npm token 亂發版本也裝不進來
+- 只在**沒有採樣**的那一輪執行，不拖慢本業
+- 24 小時內同一個目標版本只試一次；**不跨 major**
+- npm 全域目錄不可寫（node 裝在系統目錄）時不嘗試，改在 `doctor` 提示人工升級
+
+想關掉：設環境變數 `CU_NO_AUTOUPDATE=1`。
+
+`status` 與 `doctor` 都會顯示是否有新版，用的是上次回報快取的結果，不另外打網路。
+
 ## 已知限制
 
 - **非官方 endpoint**：額度 % 來自 Claude Code 內部的 `/api/oauth/usage`，Anthropic 可能變更。
@@ -347,6 +362,9 @@ Client 對 server 只用兩個端點，皆為 `application/json`：
   （實測：2026-08-29 四台 Win11 因此全數斷線 10.7–18.1 小時，其中一台累計只跑過 7 次。）
 - **重疊的 tick 尚未互斥**：VBS 以非阻塞方式啟動 node，工作排程器認為任務瞬間完成，
   所以 `MultipleInstances` 擋不住重疊的 node 行程。極少數情況下會競寫 `health.json`。
+- **npm 11 起不跑 postinstall**：安裝時會印 `npm warn allow-scripts`，我們的安裝提示
+  因此不會顯示。同樣的檢查已搬進 `claude-usage install` 與 `doctor`，所以裝完務必
+  跑一次 `install`。
 - **PowerShell 執行原則**：預設 `Restricted` 會同時擋掉 `npm.ps1`（安裝時）與
   `claude-usage.ps1`（執行時）。處理方式見上面 **Windows → 第 0 步**。
 - **Linux 背景任務未實作**（systemd --user timer）。其餘指令可用。

package/dist/daemon.js

@@ -11,7 +11,8 @@ import { existsSync } from "node:fs";
 import { EXIT, loadToken } from "./creds.js";
 import { healthWarning, lastSnapshot, loadHealth, saveHealth, } from "./health.js";
 import { devicePath, projectsDir } from "./paths.js";
-import { enroll, report } from "./upload.js";
+import { agentChannel, enroll, report } from "./upload.js";
+import { maybeSelfUpdate, updateNotice } from "./selfupdate.js";
 import { sample } from "./usage.js";
 import { nowIso, parseIso } from "./util.js";
 // ── 自適應策略 ──
@@ -200,6 +201,19 @@ export async function tick(opts = {}) {
     }
     const upload = explain ? "(skipped)" : await flushUploads();
     h.last_upload_state = upload;
+    // ★ 只在**沒有採樣**的那一輪自我更新。採樣是本業，不能為了自我維護被 npm
+    //   拖上幾十秒。skip 的 tick 本來就閒著，那才是做這件事的位置。
+    //   也必須在 flushUploads 之後 —— 版本頻道是那次 report 的回應帶回來的。
+    let updateNote = "";
+    if (!explain && !should) {
+        try {
+            updateNote = maybeSelfUpdate(agentChannel());
+        }
+        catch (e) {
+            // 更新絕不能影響 tick。吞掉並記錄，不往上拋。
+            updateNote = `update: 例外 ${e?.message ?? e}`;
+        }
+    }
     const warn = healthWarning(h);
     h.unhealthy = Boolean(warn);
     h.warning = warn;
@@ -207,6 +221,9 @@ export async function tick(opts = {}) {
         saveHealth(h);
     console.log(`[${ts}] activity=${actS} cadence=${interval}m -> ${action.padEnd(22)} ` +
         `upload=${upload}  . ${reason}`);
+    // 只在真的做了什麼時才印，否則每 5 分鐘一行 "skip" 會把 log 洗掉。
+    if (updateNote && !updateNote.startsWith("update: skip"))
+        console.log(`  ${updateNote}`);
     if (warn) {
         // 前綴固定，方便 grep daemon.log 或讓 status 指令抓
         console.error(`[${ts}] UNHEALTHY: ${warn}`);
@@ -235,5 +252,9 @@ export function printHealth() {
     if (h.last_error)
         row("last_error", h.last_error);
     row("status", warn ? `UNHEALTHY - ${warn}` : "ok");
+    // 版本提示用上次 report 快取下來的結果，不為了顯示這一行去打網路。
+    const note = updateNotice();
+    if (note)
+        console.log(`  ${"update".padEnd(20)}: ${note}`);
     return warn ? 1 : 0;
 }

package/dist/doctor.js

@@ -19,6 +19,7 @@ import { claudeDir, claudeSettingsPath, configPath, credsPath, devicePath, proje
 import { healthWarning, loadHealth } from "./health.js";
 import { readJson } from "./util.js";
 import { VERSION } from "./version.js";
+import { updateNotice } from "./selfupdate.js";
 const ok = (s) => `  [ok]   ${s}`;
 const bad = (s) => `  [BAD]  ${s}`;
 const info = (s) => `  [info] ${s}`;
@@ -60,6 +61,10 @@ export async function doctor() {
     const problems = [];
     const out = [];
     out.push(`claude-usage doctor  v${VERSION}`);
+    // 舊版是很多疑難雜症的根因，所以擺在最上面而不是埋在結論裡。
+    const upd = updateNotice();
+    if (upd)
+        out.push(`  ! ${upd}`);
     out.push("");
     out.push("環境");
     out.push(info(`平台        ${platform()} ${release()}  node ${process.version}`));

package/dist/install.js

@@ -141,7 +141,32 @@ function winHardenTask() {
         "-AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable)");
     return false;
 }
+/**
+ * 安裝時檢查 PowerShell 執行原則。
+ *
+ * ★ 為什麼這段從 postinstall.mjs 搬到這裡：npm 11 起預設**不執行**未核准的
+ *   postinstall 腳本（安裝時只印 `npm warn allow-scripts`），所以那支檔案在新版 npm
+ *   上根本不會跑 —— 它原本的唯一價值（在使用者撞牆前先講）已經失效。
+ *   `install` 是 `npm i -g` 之後緊接著要跑的指令，把提示放這裡才真的看得到。
+ *
+ * ★ 為什麼仍然要提示而不是自動修：改動使用者機器的安全設定，該由他自己決定。
+ */
+function warnExecutionPolicy() {
+    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 !== "Restricted" && policy !== "AllSigned")
+        return;
+    console.log(`\n! PowerShell 執行原則是 ${policy} —— 直接打 claude-usage 會被擋\n` +
+        "  （錯誤含 UnauthorizedAccess / PSSecurityException / ExecutionPolicy）\n" +
+        "  擇一處理：\n" +
+        "    1) Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned\n" +
+        "       設定一次、永久生效、免系統管理員。\n" +
+        "    2) 不改原則，改叫 claude-usage.cmd（功能完全一樣）\n" +
+        "  公司用 GPO 鎖了機器層級原則時 (1) 會被覆寫 —— 直接用 (2)。\n");
+}
 function winInstall() {
+    warnExecutionPolicy(); // 先講，因為接下來每一步都可能因為它而失敗
     const vbs = `Set s = CreateObject("Wscript.Shell")\r\n` +
         `s.Run """${NODE}"" ""${CLI}"" daemon-tick", 0, False\r\n`;
     writeFileSync(VBS_PATH(), vbs, "utf8");

package/dist/paths.js

@@ -31,6 +31,8 @@ export const configPath = () => join(stateDir(), "config.json");
 export const healthPath = () => join(stateDir(), "health.json");
 /** 上報游標：每個 JSONL 檔讀到第幾個 byte */
 export const cursorPath = () => join(stateDir(), "cursor.json");
+/** 自我更新的節流狀態。**必須落地**：daemon 每次 tick 都是新行程，記憶體留不住。 */
+export const updatePath = () => join(stateDir(), "update.json");
 /** daemon 的 stdout/stderr（背景任務寫的） */
 export const logPath = () => join(stateDir(), "daemon.log");
 /**

package/dist/selfupdate.js

@@ -0,0 +1,185 @@
+/**
+ * 自我更新 —— 由 server 指定版本，client 執行。
+ *
+ * ★ 為什麼版本由 server 給，而不是 client 去問 npm：
+ *   1. **安全**：`npm i -g pkg@latest` 等於「誰能發布 npm，誰就決定同事機器上跑什麼」。
+ *      由 server 指定確切版本號，權威在我們手上 —— 有人拿到 npm token 發了新版，
+ *      只要 server 沒說要，沒有任何一台會裝。
+ *   2. **煞車**：發現壞版本時改一個環境變數就全隊停住，比 npm deprecate 快得多。
+ *   3. **成本**：版本資訊搭 /v1/report 的回應，零額外網路呼叫。daemon 每 5 分鐘跑一次，
+ *      去問 npm registry 會變成每台每天 288 次。
+ *   4. **可達性**：公司網路擋 npmjs 時仍然運作（我們的 server 本來就通）。
+ *
+ * ⚠️ 這個檔案讓「能發布 npm 套件」變成「能在同事機器上執行程式碼」。所有護欄都是
+ *    為了這件事存在的，刪任何一條之前先想清楚。
+ */
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { join } from "node:path";
+import { updatePath } from "./paths.js";
+import { readJson, writeJsonAtomic, nowIso } from "./util.js";
+import { VERSION } from "./version.js";
+/** 兩次自我更新嘗試的最小間隔。壞版本會讓它每 5 分鐘重裝一次，把機器打爛。 */
+export const RETRY_COOLDOWN_HOURS = 24;
+export const loadUpdateState = () => readJson(updatePath()) ?? {};
+export const saveUpdateState = (s) => writeJsonAtomic(updatePath(), s);
+/**
+ * 語意化版本比較。回 -1 / 0 / 1。
+ * 只比對 major.minor.patch 的數字部分；預發行標籤（-beta.1）一律當成比正式版小。
+ */
+export function cmpVersion(a, b) {
+    const parse = (v) => {
+        const [core = "", pre = ""] = v.split("-", 2);
+        const nums = core.split(".").map((x) => Number.parseInt(x, 10) || 0);
+        return { nums, pre };
+    };
+    const A = parse(a), B = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const d = (A.nums[i] ?? 0) - (B.nums[i] ?? 0);
+        if (d !== 0)
+            return d > 0 ? 1 : -1;
+    }
+    if (A.pre === B.pre)
+        return 0;
+    if (!A.pre)
+        return 1; // 正式版 > 預發行
+    if (!B.pre)
+        return -1;
+    return A.pre > B.pre ? 1 : -1;
+}
+/** npm 全域安裝目錄。拿不到就回 null（代表我們無從判斷可不可寫）。 */
+function globalPrefix() {
+    const r = spawnSync("npm", ["prefix", "-g"], {
+        encoding: "utf8", timeout: 20_000, windowsHide: true, shell: process.platform === "win32",
+    });
+    if (r.error || r.status !== 0)
+        return null;
+    return (r.stdout ?? "").trim() || null;
+}
+/**
+ * 全域目錄可不可寫。
+ *
+ * ★ 為什麼一定要先檢查：node 裝在 /usr/local 或 Program Files 時，`npm i -g` 需要
+ *   sudo/系統管理員。從 daemon 跑必定失敗，而且是每 24 小時失敗一次、永遠不會好。
+ *   偵測得出來就不該去撞牆 —— 改成在 status/doctor 提示人工升級。
+ */
+export function prefixWritable() {
+    const p = globalPrefix();
+    if (!p)
+        return null;
+    try {
+        accessSync(p, constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 要不要更新。**純函式，不做 I/O**，所以護欄邏輯測得到 —— 這是整個功能最需要被測的部分。
+ */
+export function decideUpdate(ch, st, now, opts = {}) {
+    const cur = opts.current ?? VERSION;
+    if (opts.disabled)
+        return { act: false, reason: "CU_NO_AUTOUPDATE=1（本機關閉）" };
+    if (!ch?.latest)
+        return { act: false, reason: "server 未啟用版本頻道" };
+    if (ch.autoupdate !== true)
+        return { act: false, reason: "server 只告知、未授權自動更新" };
+    const c = cmpVersion(ch.latest, cur);
+    if (c <= 0)
+        return { act: false, reason: `已是最新（本機 ${cur}）` };
+    // ★ 不跨 major：major 依定義有破壞性變更，該由人決定何時承受。
+    const majFrom = Number.parseInt(cur.split(".")[0] ?? "0", 10) || 0;
+    const majTo = Number.parseInt(ch.latest.split(".")[0] ?? "0", 10) || 0;
+    if (majTo !== majFrom) {
+        return { act: false, reason: `跨 major（${cur} → ${ch.latest}）需人工升級` };
+    }
+    // ★ 節流。目標版本換了就重置 —— 否則發了修正版還要再等滿 24 小時才會裝。
+    if (st.last_attempt_at && st.last_attempt_version === ch.latest) {
+        const hrs = (now.getTime() - Date.parse(st.last_attempt_at)) / 3_600_000;
+        if (Number.isFinite(hrs) && hrs < RETRY_COOLDOWN_HOURS) {
+            return { act: false, reason: `${RETRY_COOLDOWN_HOURS}h 內已試過 ${ch.latest}（${hrs.toFixed(1)}h 前）` };
+        }
+    }
+    return { act: true, from: cur, to: ch.latest };
+}
+/** 實際執行 npm 安裝。**釘死版本號**，不用 @latest —— 見檔頭。 */
+function runInstall(version) {
+    const pkg = `@tsa-group/claude-usage@${version}`;
+    const r = spawnSync("npm", ["install", "-g", pkg, "--no-fund", "--no-audit"], {
+        encoding: "utf8", timeout: 300_000, windowsHide: true,
+        shell: process.platform === "win32", // Windows 上 npm 是 .cmd，需要 shell 才找得到
+    });
+    if (r.error)
+        return { ok: false, detail: `spawn 失敗: ${r.error.message}` };
+    if (r.status !== 0) {
+        const tail = ((r.stderr ?? "") + (r.stdout ?? "")).trim().split("\n").slice(-3).join(" / ");
+        return { ok: false, detail: `npm rc=${r.status}: ${tail.slice(0, 300)}` };
+    }
+    return { ok: true, detail: `installed ${version}` };
+}
+/**
+ * 檢查並（在允許時）自我更新。回一句給 daemon.log 的話。
+ *
+ * ★ 絕不拋例外：daemon 的本業是採樣，不是自我維護。更新壞掉不能影響 tick。
+ */
+export function maybeSelfUpdate(ch) {
+    let st;
+    try {
+        st = loadUpdateState();
+    }
+    catch {
+        st = {};
+    }
+    // 不論要不要更新，都把 server 說的最新版存起來 —— status/doctor 靠它顯示提示，
+    // 而它們不該為了知道版本而自己去打網路。
+    if (ch?.latest && st.latest !== ch.latest) {
+        st.latest = ch.latest;
+        try {
+            saveUpdateState(st);
+        }
+        catch { /* 存不了就算了，下次還會再存 */ }
+    }
+    const d = decideUpdate(ch, st, new Date(), {
+        disabled: process.env["CU_NO_AUTOUPDATE"] === "1",
+    });
+    if (!d.act)
+        return `update: skip (${d.reason})`;
+    const w = prefixWritable();
+    if (w === false) {
+        return "update: skip (npm 全域目錄不可寫 —— 需要人工升級，見 doctor)";
+    }
+    st.last_attempt_at = nowIso();
+    st.last_attempt_version = d.to;
+    const res = runInstall(d.to);
+    st.last_result = res.ok ? "ok" : res.detail.slice(0, 200);
+    try {
+        saveUpdateState(st);
+    }
+    catch { /* 同上 */ }
+    return res.ok
+        // 不重啟自己：排程指向絕對路徑，npm 就地換檔，下一個 tick 自然用新版。
+        ? `update: ${d.from} → ${d.to} 成功（下次 tick 起生效）`
+        : `update: ${d.from} → ${d.to} 失敗 — ${res.detail}`;
+}
+/** 給 status / doctor 用的一行提示。沒有新版就回 null。 */
+export function updateNotice() {
+    let st;
+    try {
+        st = loadUpdateState();
+    }
+    catch {
+        return null;
+    }
+    if (!st.latest || cmpVersion(st.latest, VERSION) <= 0)
+        return null;
+    const how = prefixWritable() === false
+        ? "npm 全域目錄需要權限，請用系統管理員身分執行"
+        : "npm i -g @tsa-group/claude-usage@latest";
+    const failed = st.last_result && st.last_result !== "ok"
+        ? `  (自動更新上次失敗: ${st.last_result})` : "";
+    return `有新版 ${st.latest}（本機 ${VERSION}）—— ${how}${failed}`;
+}
+/** 供測試覆寫用的路徑組裝（正式路徑在 paths.ts） */
+export const _updateFileName = (dir) => join(dir, "update.json");

package/dist/upload.js

@@ -25,6 +25,9 @@ import * as events from "./events.js";
 import { devicePath, serverUrl } from "./paths.js";
 import { readJson, writeJsonAtomic } from "./util.js";
 import { VERSION } from "./version.js";
+/** 最近一次 report 回應帶回來的版本頻道。null = server 未啟用或尚未回報過。 */
+let lastAgentChannel = null;
+export const agentChannel = () => lastAgentChannel;
 async function post(path, obj, bearer) {
     const headers = { "Content-Type": "application/json" };
     if (bearer)
@@ -172,6 +175,9 @@ export async function report(argv = []) {
     }
     payload.device_id = dev.device_id;
     const { status, body } = await post("/v1/report", payload, dev.device_key);
+    // server 會在回應帶版本頻道（沒啟用時整個欄位不存在）。存起來給 daemon 決策用 ——
+    // 這是**唯一**的版本來源，client 永遠不自己去問 npm registry。見 selfupdate.ts 檔頭。
+    lastAgentChannel = body?.agent ?? null;
     const kind = anyRows ? "report" : "heartbeat";
     console.log(`${kind} -> ${status}: ${JSON.stringify(body)}`);
     console.log(`  sent: ${n.limit_snapshots} snapshots, ${n.sessions} sessions, ` +

package/package.json

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

package/postinstall.mjs

@@ -1,6 +1,11 @@
 /**
  * 安裝後提示：Windows 的 PowerShell 執行原則會擋掉 npm 產生的 .ps1 啟動器。
  *
+ * ⚠️ npm 11 起預設**不執行**未核准的 postinstall（只印 `npm warn allow-scripts`），
+ *    所以這支檔案在新版 npm 上不會跑。同樣的檢查已於 v0.4.8 搬進 `install`
+ *    與 `doctor`（見 src/install.ts warnExecutionPolicy）。這裡保留是因為在
+ *    舊版 npm 上它仍然是唯一能「撞牆之前先說話」的時機。
+ *
  * ★ 為什麼一定要在這裡講：這個失敗發生時**我們的程式碼根本沒機會執行** ——
  * PowerShell 在 Node 啟動前就拒絕載入 `claude-usage.ps1` 了。所以工具永遠無法在
  * 出錯當下自我診斷，提示只能前置，而 postinstall 是唯一「撞牆之前還能說話」的