ccus-cli 0.1.4 → 0.1.5

package/README.md

@@ -8,6 +8,7 @@
 - `ccus export`：默认导出当前周数据包，里面同时包含原始事件和按天维度的周汇总。
 - `ccus aggregate`：读取一个目录里的多人 export bundle json，输出明细、按天、按周三个 CSV。
 - `ccus aggregate serve`：同样以 bundle 目录为输入，启动本地多人 dashboard 页面，不落地任何文件。
+- `ccus update`：主动检查 npm 上是否有新版本，有则提示手动升级命令；`ccus --version` 查看当前版本。
 
 > **支持范围**：`ccus statusline emit` 依赖 Claude Code 的 statusLine 机制（从 `stdin` 读 JSON、向 `stdout` 回一行文本），**只在命令行版 Claude Code（CLI / 终端）里生效**。
 >
@@ -23,6 +24,27 @@ npm install -g ccus-cli
 
 要求 Node.js >= 20。
 
+## 更新检查
+
+ccus 通过 npm 全局安装，自带一个轻量的更新检查：
+
+- statusline 渲染时会**异步、节流（每天最多一次）**地向 npm registry 查询最新版本，结果缓存到数据目录下的 `update-check.json`。检查在 detached 后台进程里完成，**不阻塞 statusline、不污染单行输出**。
+- 一旦发现有更新，statusline 行尾会追加一个小标记，例如 `… | ⏱ 11:44 | ⬆ v0.1.5`。
+- 看到标记后手动升级即可：
+
+```bash
+npm i -g ccus-cli@latest
+```
+
+也可以随时主动检查：
+
+```bash
+ccus update        # 立即查 registry，有新版本则打印升级命令
+ccus --version     # 查看当前安装的版本
+```
+
+> 出于稳妥考虑，ccus **只提示、不自动替你执行全局安装**。如需走私服或镜像（如 npmmirror），设置环境变量 `CCUS_REGISTRY` 指向对应 registry 即可。
+
 ## 快速开始
 
 全局安装后，一条命令把 statusline 接进 Claude Code：

package/dist/cli.js

@@ -55,9 +55,11 @@ const payload_1 = require("./lib/payload");
 const paths_1 = require("./lib/paths");
 const storage_1 = require("./lib/storage");
 const time_1 = require("./lib/time");
+const update_check_1 = require("./lib/update-check");
+const version_1 = require("./lib/version");
 /** CLI 帮助信息保持简洁，方便直接挂到 README 或终端里查看。 */
 function printHelp() {
-    process.stdout.write(`ccus\n\nCommands:\n  ccus install [--settings PATH] [--command CMD] [--data-dir PATH]\n  ccus statusline emit [--data-dir PATH] [--input FILE] [--no-store]\n  ccus dashboard build [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard open [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard serve [--range today|this-week|last-week|5h] [--port 0] [--host 127.0.0.1] [--open] [--data-dir PATH]\n  ccus export [RANGE] [--out FILE] [--data-dir PATH]   (RANGE: this-week|tw, last-week|lw, today, 5h; e.g. ccus export lw)\n  ccus aggregate --input-dir DIR [--out-dir DIR]\n  ccus aggregate serve --input-dir DIR [--port 0] [--host 127.0.0.1]\n\nGlobal flags:\n  --verbose | --debug | -v   输出详细调试日志到 stderr（等价于设置 CCUS_DEBUG=1），方便排查问题\n`);
+    process.stdout.write(`ccus\n\nCommands:\n  ccus install [--settings PATH] [--command CMD] [--data-dir PATH]\n  ccus statusline emit [--data-dir PATH] [--input FILE] [--no-store]\n  ccus dashboard build [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard open [--range today|this-week|last-week|5h] [--out FILE] [--data-dir PATH]\n  ccus dashboard serve [--range today|this-week|last-week|5h] [--port 0] [--host 127.0.0.1] [--open] [--data-dir PATH]\n  ccus export [RANGE] [--out FILE] [--data-dir PATH]   (RANGE: this-week|tw, last-week|lw, today, 5h; e.g. ccus export lw)\n  ccus aggregate --input-dir DIR [--out-dir DIR]\n  ccus aggregate serve --input-dir DIR [--port 0] [--host 127.0.0.1]\n  ccus update [--data-dir PATH]\n  ccus --version\n\nGlobal flags:\n  --verbose | --debug | -v   输出详细调试日志到 stderr（等价于设置 CCUS_DEBUG=1），方便排查问题\n`);
 }
 /** 一个轻量的参数解析器，当前命令面不复杂，没必要引入额外依赖。 */
 function parseOptions(args) {
@@ -174,7 +176,12 @@ async function handleStatuslineEmit(options) {
             gitUserAccount: event.gitUserAccount,
             gitBranch,
         });
-        process.stdout.write(`${event.statusLine}\n`);
+        // 更新检查必须对 statusline 完全无侵入：同步读旧缓存决定是否在行尾追加小标记，
+        // 把网络请求甩给 detached 后台进程，主进程不等待、失败静默。
+        (0, update_check_1.maybeSpawnBackgroundCheck)(dataDir);
+        const notice = (0, update_check_1.computeUpdateNotice)(dataDir);
+        const statusLine = notice ? `${event.statusLine} | ${notice}` : event.statusLine;
+        process.stdout.write(`${statusLine}\n`);
     }
     catch (error) {
         // 正常路径不能因为采样失败把 statusline 弄挂，所以这里仍然降级输出兜底文本；
@@ -518,6 +525,43 @@ function resolveExportOptions(action, args, rest) {
     }
     return options;
 }
+/**
+ * `ccus update`：用户主动检查更新（绕过 24h 节流）。
+ *
+ * 根据当前的产品选择，这里只做「检查 + 提示」，不替用户执行全局安装。
+ * 有新版本时打印应当手动运行的 `npm i -g` 命令。
+ */
+async function handleUpdate(options) {
+    const dataDir = getDataDir(options);
+    const current = (0, version_1.getCurrentVersion)();
+    let latest;
+    try {
+        latest = await (0, update_check_1.fetchLatestVersion)();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stdout.write(`无法检查更新：${message}\n当前版本 v${current}\n`);
+        return;
+    }
+    // 顺手刷新缓存，让 statusline 标记和这次检查结果保持一致。
+    await (0, update_check_1.performUpdateCheck)(dataDir);
+    if ((0, version_1.isNewerVersion)(latest, current)) {
+        process.stdout.write(`发现新版本：v${current} -> v${latest}\n运行以下命令升级：\n  npm i -g ccus-cli@latest\n`);
+    }
+    else {
+        process.stdout.write(`已是最新版本 v${current}\n`);
+    }
+}
+/**
+ * 隐藏命令 `__check-update`：由 statusline 路径以 detached 后台进程触发。
+ *
+ * 只做一件事：查 registry 并写缓存。不输出任何东西到 stdout（它不是被人看的），
+ * 失败也静默，绝不影响触发它的 statusline 主进程。
+ */
+async function handleBackgroundCheckUpdate(options) {
+    const dataDir = getDataDir(options);
+    await (0, update_check_1.performUpdateCheck)(dataDir);
+}
 /** 顶层命令分发入口。 */
 async function main(args = process.argv.slice(2)) {
     (0, debug_1.setDebugEnabled)((0, debug_1.resolveDebugEnabled)(args));
@@ -528,6 +572,18 @@ async function main(args = process.argv.slice(2)) {
         printHelp();
         return;
     }
+    if (group === "--version" || group === "-V" || group === "version") {
+        process.stdout.write(`${(0, version_1.getCurrentVersion)()}\n`);
+        return;
+    }
+    if (group === "update") {
+        await handleUpdate(parseOptions(args.slice(1)));
+        return;
+    }
+    if (group === "__check-update") {
+        await handleBackgroundCheckUpdate(parseOptions(args.slice(1)));
+        return;
+    }
     if (group === "install") {
         await handleInstall(parseOptions(args.slice(1)));
         return;

package/dist/lib/paths.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDefaultDataDir = getDefaultDataDir;
 exports.getEventsDir = getEventsDir;
 exports.getDashboardDir = getDashboardDir;
+exports.getUpdateCachePath = getUpdateCachePath;
 exports.getClaudeDataDir = getClaudeDataDir;
 exports.getClaudeSettingsPath = getClaudeSettingsPath;
 const node_os_1 = __importDefault(require("node:os"));
@@ -41,6 +42,10 @@ function getEventsDir(dataDir) {
 function getDashboardDir(dataDir) {
     return node_path_1.default.join(dataDir, "dashboard");
 }
+/** 版本更新检查的本地缓存文件，记录上次检查时间与拿到的最新版本。 */
+function getUpdateCachePath(dataDir) {
+    return node_path_1.default.join(dataDir, "update-check.json");
+}
 /** Claude Code 默认本地数据目录。 */
 function getClaudeDataDir() {
     const configured = process.env.CCUS_CLAUDE_DATA_DIR;

package/dist/lib/update-check.js

@@ -0,0 +1,180 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUpdateCacheSync = readUpdateCacheSync;
+exports.fetchLatestVersion = fetchLatestVersion;
+exports.performUpdateCheck = performUpdateCheck;
+exports.maybeSpawnBackgroundCheck = maybeSpawnBackgroundCheck;
+exports.computeUpdateNotice = computeUpdateNotice;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_https_1 = __importDefault(require("node:https"));
+const debug_1 = require("./debug");
+const paths_1 = require("./paths");
+const version_1 = require("./version");
+/** npm 包名，更新检查向 registry 查询它的最新版本。 */
+const PACKAGE_NAME = "ccus-cli";
+/** 后台检查节流窗口：同一数据目录每天最多向 registry 查一次。 */
+const CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+/** 网络请求超时，避免后台进程长时间挂着；statusline 主进程本身不等它。 */
+const FETCH_TIMEOUT_MS = 4000;
+/**
+ * 同步读取更新缓存。
+ *
+ * statusline 是高频短命进程，这里只读一个很小的 JSON，用同步 IO 换取最简单、最快的路径；
+ * 任何异常都静默返回 null，绝不影响状态行输出。
+ */
+function readUpdateCacheSync(dataDir) {
+    try {
+        const raw = node_fs_1.default.readFileSync((0, paths_1.getUpdateCachePath)(dataDir), "utf8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.lastCheckedAt !== "string") {
+            return null;
+        }
+        return {
+            lastCheckedAt: parsed.lastCheckedAt,
+            latestVersion: typeof parsed.latestVersion === "string" ? parsed.latestVersion : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** 写入更新缓存；目录可能尚未创建，所以先 mkdir。失败静默。 */
+async function writeUpdateCache(dataDir, cache) {
+    try {
+        await promises_1.default.mkdir(dataDir, { recursive: true });
+        await promises_1.default.writeFile((0, paths_1.getUpdateCachePath)(dataDir), `${JSON.stringify(cache, null, 2)}\n`, "utf8");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("update", "failed to write cache", error instanceof Error ? error.message : String(error));
+    }
+}
+/** registry 基地址，允许用 CCUS_REGISTRY 指向私服或镜像（如 npmmirror）。 */
+function getRegistryBase(env = process.env) {
+    const configured = (env.CCUS_REGISTRY ?? "").trim();
+    const base = configured || "https://registry.npmjs.org";
+    return base.replace(/\/+$/, "");
+}
+/**
+ * 向 npm registry 查询最新发布版本。
+ *
+ * 走 `/<pkg>/latest` 这个轻量端点，只取 `version` 字段；超时或任何错误都 reject，
+ * 由调用方决定是否静默。
+ */
+function fetchLatestVersion(env = process.env) {
+    const url = `${getRegistryBase(env)}/${PACKAGE_NAME}/latest`;
+    return new Promise((resolve, reject) => {
+        const request = node_https_1.default.get(url, { headers: { accept: "application/json" } }, (response) => {
+            const status = response.statusCode ?? 0;
+            if (status < 200 || status >= 300) {
+                response.resume();
+                reject(new Error(`registry responded ${status}`));
+                return;
+            }
+            let body = "";
+            response.setEncoding("utf8");
+            response.on("data", (chunk) => {
+                body += chunk;
+            });
+            response.on("end", () => {
+                try {
+                    const parsed = JSON.parse(body);
+                    if (typeof parsed.version === "string") {
+                        resolve(parsed.version);
+                    }
+                    else {
+                        reject(new Error("registry payload missing version"));
+                    }
+                }
+                catch (error) {
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                }
+            });
+        });
+        request.setTimeout(FETCH_TIMEOUT_MS, () => {
+            request.destroy(new Error("registry request timed out"));
+        });
+        request.on("error", reject);
+    });
+}
+/**
+ * 真正执行一次检查并把结果写进缓存。
+ *
+ * 供隐藏命令 `__check-update`（statusline 后台触发）和 `ccus update`（用户主动）复用。
+ * 即使 registry 失败也会更新 lastCheckedAt，避免反复重试打爆 registry。
+ */
+async function performUpdateCheck(dataDir) {
+    let latestVersion = null;
+    try {
+        latestVersion = await fetchLatestVersion();
+        (0, debug_1.debugLog)("update", "fetched latest version", latestVersion);
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("update", "fetch failed", error instanceof Error ? error.message : String(error));
+    }
+    const cache = {
+        lastCheckedAt: new Date().toISOString(),
+        latestVersion,
+    };
+    await writeUpdateCache(dataDir, cache);
+    return cache;
+}
+/** 缓存是否已过 TTL（或根本不存在），需要重新向 registry 查询。 */
+function isCacheStale(cache, now) {
+    if (!cache) {
+        return true;
+    }
+    const last = Date.parse(cache.lastCheckedAt);
+    if (!Number.isFinite(last)) {
+        return true;
+    }
+    return now.getTime() - last >= CHECK_TTL_MS;
+}
+/**
+ * 如缓存过期，spawn 一个 detached 后台进程刷新它，主进程不等待。
+ *
+ * 这是 statusline 路径能用的唯一安全方式：主进程同步读旧缓存决定是否提示，
+ * 把网络请求甩给后台子进程，自己立刻输出单行状态文本并退出，绝不阻塞。
+ */
+function maybeSpawnBackgroundCheck(dataDir, now = new Date()) {
+    try {
+        if (!isCacheStale(readUpdateCacheSync(dataDir), now)) {
+            return;
+        }
+        const scriptPath = process.argv[1];
+        if (!scriptPath) {
+            return;
+        }
+        const child = (0, node_child_process_1.spawn)(process.execPath, [scriptPath, "__check-update", "--data-dir", dataDir], {
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+        (0, debug_1.debugLog)("update", "spawned background check");
+    }
+    catch (error) {
+        (0, debug_1.debugLog)("update", "failed to spawn background check", error instanceof Error ? error.message : String(error));
+    }
+}
+/**
+ * 根据缓存计算 statusline 末尾要追加的更新标记。
+ *
+ * 有严格新于当前版本的发布时返回形如 `⬆ v0.1.5` 的短标记，否则返回 null。
+ */
+function computeUpdateNotice(dataDir, currentVersion = (0, version_1.getCurrentVersion)()) {
+    const cache = readUpdateCacheSync(dataDir);
+    if (!cache || !cache.latestVersion) {
+        return null;
+    }
+    if (!(0, version_1.isNewerVersion)(cache.latestVersion, currentVersion)) {
+        return null;
+    }
+    return `⬆ v${cache.latestVersion}`;
+}
+//# sourceMappingURL=update-check.js.map

package/dist/lib/version.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentVersion = getCurrentVersion;
+exports.isNewerVersion = isNewerVersion;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 读取 ccus 自身的版本号（package.json 的 version）。
+ *
+ * dist/lib/version.js 与 src/lib/version.ts 距离包根都是 `../..`，
+ * 所以编译产物和 tsx 直跑源码时都能定位到同一个 package.json。
+ * 读不到时回退 "0.0.0"，让上层逻辑（更新检查）安全降级而不是抛错。
+ */
+let cachedVersion = null;
+function getCurrentVersion() {
+    if (cachedVersion !== null) {
+        return cachedVersion;
+    }
+    try {
+        const packageJsonPath = node_path_1.default.join(__dirname, "..", "..", "package.json");
+        const raw = node_fs_1.default.readFileSync(packageJsonPath, "utf8");
+        const parsed = JSON.parse(raw);
+        cachedVersion = typeof parsed.version === "string" ? parsed.version : "0.0.0";
+    }
+    catch {
+        cachedVersion = "0.0.0";
+    }
+    return cachedVersion;
+}
+/**
+ * 语义化版本比较：判断 latest 是否严格新于 current。
+ *
+ * 只比较 `major.minor.patch` 三段数字，忽略预发布/构建元数据，
+ * 对当前发布节奏足够；任意一段解析失败按 0 处理，避免误报更新。
+ */
+function isNewerVersion(latest, current) {
+    const parse = (value) => value
+        .trim()
+        .replace(/^v/, "")
+        .split("-", 1)[0]
+        .split(".")
+        .map((part) => Number.parseInt(part, 10))
+        .map((part) => (Number.isFinite(part) ? part : 0));
+    const a = parse(latest);
+    const b = parse(current);
+    const length = Math.max(a.length, b.length);
+    for (let index = 0; index < length; index += 1) {
+        const left = a[index] ?? 0;
+        const right = b[index] ?? 0;
+        if (left > right) {
+            return true;
+        }
+        if (left < right) {
+            return false;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccus-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Claude Code statusline usage logger and dashboard CLI",
   "type": "commonjs",
   "bin": {
@@ -15,7 +15,7 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "test": "node --test dist/test",
-    "test:src": "node --import tsx --test src/test/payload.test.ts src/test/dashboard.test.ts src/test/export.test.ts src/test/storage.test.ts src/test/claude.test.ts src/test/aggregate.test.ts src/test/aggregate-dashboard.test.ts src/test/install.test.ts src/test/debug.test.ts src/test/time.test.ts"
+    "test:src": "node --import tsx --test src/test/payload.test.ts src/test/dashboard.test.ts src/test/export.test.ts src/test/storage.test.ts src/test/claude.test.ts src/test/aggregate.test.ts src/test/aggregate-dashboard.test.ts src/test/install.test.ts src/test/debug.test.ts src/test/time.test.ts src/test/update-check.test.ts"
   },
   "keywords": [
     "claude-code",