tokenusage-cli 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,13 @@
3
3
  本包(`tokenusage-cli`)的用户可见变更记录。发版时在顶部新增一节,
4
4
  `## <版本号>` 行会被 release workflow 取作 GitHub Release 正文。
5
5
 
6
+ ## 0.2.1
7
+
8
+ 修复 0.2.0 的严重回归:运行上报的版本号读取用了错误的相对路径(`Cannot find
9
+ module '../package.json'`),导致每轮 `sync` 启动即崩溃——定时与手动采集全部
10
+ 中断。本地包实测通过后发布;并新增防回归测试,锁定嵌套模块的 package.json
11
+ require 深度,此类问题不再可能静默通过测试。
12
+
6
13
  ## 0.2.0
7
14
 
8
15
  采集控制与运行记录:采集器从此可暂停、可审计。
package/README.md CHANGED
@@ -7,7 +7,8 @@
7
7
  ## 快速开始(三步)
8
8
 
9
9
  ```bash
10
- # 1) 初始化本地扫描(配置扫描根、安装各工具的用量 hook)
10
+ # 1) 初始化:扫描根配置、各工具用量 hook、并注册每小时自动采集的计划任务
11
+ # (Windows 经 VBS 隐藏窗口运行,不弹黑框;--no-task 可跳过任务注册)
11
12
  tokenusage init
12
13
 
13
14
  # 2) 配对:输出一个 user_code,浏览器打开提示的链接批准
@@ -20,7 +21,8 @@ tokenusage sync # 手动一轮:解析 → 入队 → 上传
20
21
  tokenusage sync --drain # 首次/积压补传(更大的批处理预算)
21
22
  ```
22
23
 
23
- 完成。之后随时跑 `tokenusage sync`,或用 `--watch` 常驻自动上报(见下)。
24
+ 完成。init 注册的计划任务每小时自动采集一次;也可以随时手动 `tokenusage sync`,
25
+ 或用 `--watch` 常驻自动上报(见下)。不想自动采集就 `tokenusage pause`(见下)。
24
26
 
25
27
  **谁批准配对?** 批准者就是配对时登录站点的那个账号——设备与其全部数据绑定到该账号,账号之间数据完全隔离。自托管用户批准自己的设备即可;站点管理员不需要、也无法替别人审批。陌生人可以对公开站点发起配对码,但没有账号就批不了(注册邀请制 / `token_allowed_emails` 白名单),码 15 分钟自动过期。
26
28
 
@@ -28,17 +30,18 @@ tokenusage sync --drain # 首次/积压补传(更大的批处理预算)
28
30
 
29
31
  | 命令 | 说明 |
30
32
  |---|---|
31
- | `tokenusage init` | 本地初始化(扫描根配置、各工具 hook 安装)。不含配对 |
33
+ | `tokenusage init` | 本地初始化:扫描根配置、各工具 hook 安装、注册每小时计划任务(Windows 隐藏窗口;`--no-task` 跳过任务;`--run-report=off` 关闭运行记录上报)。不含配对 |
32
34
  | `tokenusage device-login` | 设备流配对:输出 `user_code`,在站点 `/device` 页批准后本机拿到设备令牌 |
33
35
  | `tokenusage sync` | 解析本地 AI 工具日志 → 上报小时桶 + 会话元数据 |
34
36
  | `tokenusage sync --watch` | 常驻模式,默认每 15 分钟增量一轮(`--interval <ms>` 可调,≥60000) |
35
37
  | `tokenusage sync --no-sessions` | 只上报小时桶,跳过会话元数据 |
36
38
  | `tokenusage sync --drain` | 补传模式:更大的批处理预算,适合首次接入/长期积压 |
37
- | `tokenusage status` | 本地状态:Base URL、令牌、队列积压、最近解析/上传时间 |
39
+ | `tokenusage pause` / `resume` | 暂停/恢复自动采集:定时任务、hook、`--watch` 全部静默停手,手动 `sync` 不受影响(Windows 上同步启停计划任务) |
40
+ | `tokenusage status` | 本地状态:Base URL、令牌、采集状态、运行上报开关、队列积压、最近解析/上传时间 |
38
41
  | `tokenusage doctor` | 体检(运行时 / 网络 / 各工具配置),`--json` 输出 |
39
42
  | `tokenusage diagnostics` | 诊断信息导出 |
40
43
  | `tokenusage sessions` | 本地导出会话分析(JSON/CSV,元数据级) |
41
- | `tokenusage uninstall [--purge]` | 移除 hook;`--purge` 连数据目录一起删 |
44
+ | `tokenusage uninstall [--purge]` | 移除 hook 与计划任务;`--purge` 连数据目录一起删 |
42
45
 
43
46
  配置优先级:CLI 参数 > `~/.tokenusage/.../config.json` > 环境变量(`TOKENUSAGE_BASE_URL` 等)> 内置默认(你的部署地址 + 其公开 publishable key)。
44
47
 
@@ -54,6 +57,31 @@ tokenusage sync --watch --interval 3600000 --no-sessions # 每小时,只传
54
57
  - **停止**:在运行的终端 Ctrl+C 即可;`--watch` 只是前台进程,不注册任何系统计划任务/守护。随时终止都安全——队列与水位都已落盘,下次 `sync` 从断点继续。
55
58
  - 每轮增量:首轮解析全部历史日志(可能较慢),之后只重扫有变化的文件;上报侧队列 offset + 会话水位双断点,多轮之间不重不漏。
56
59
 
60
+ ## 采集控制:pause / resume 与计划任务
61
+
62
+ ```bash
63
+ tokenusage pause # 暂停自动采集(定时任务 / hook / --watch 全部静默停手)
64
+ tokenusage resume # 恢复
65
+ tokenusage status # 查看当前采集状态
66
+ ```
67
+
68
+ - 暂停是持久标志:`sync --auto`、hook/notify 触发、`--watch`、计划任务都会静默
69
+ 退出(不报错、不上报、不留运行记录);**手动 `tokenusage sync` 永远可用**。
70
+ - Windows 上 init 会注册每小时计划任务 `TokenUsageSync`(隐藏窗口,无黑框),
71
+ pause/resume 顺势 disable/enable 它;`uninstall` 一并删除任务与脚本。
72
+ - 自动采集的日志落在 `~/.tokenusage/tracker/logs/sync.log`(1 MiB 滚动一代),
73
+ 不依赖终端重定向。
74
+
75
+ ## 运行记录上报
76
+
77
+ 每轮 sync 结束后(**空跑也算**),CLI 向服务端上报一条聚合运行记录:时间、触发
78
+ 方式(定时/手动/常驻/通知)、结果、耗时、解析文件数与上报量。仪表盘的
79
+ "采集记录"页用它展示采集器健康度——空跑记录就是"活着"的心跳。
80
+
81
+ - 内容只有聚合计数与版本字符串,无任何路径/标题/正文。
82
+ - 上报尽力而为:失败只记本地日志,绝不影响用量数据采集。
83
+ - 不想上报:`tokenusage init --run-report=off`(重跑 init 修改,配对不受影响)。
84
+
57
85
  ## 未配对时会发生什么
58
86
 
59
87
  CLI 未配对也能正常用,只是**降级为“只采集、不上报”**:
@@ -76,7 +104,7 @@ CLI 未配对也能正常用,只是**降级为“只采集、不上报”**:
76
104
 
77
105
  ## 数据目录
78
106
 
79
- `~/.tokenusage/`(`0700` 目录 + `0600` 文件):上传队列(`queue.jsonl` + offset)、会话分析 sidecar、`session-upload-watermarks.json`(增量水位)。与旧版 tokentracker CLI 的 `~/.tokentracker/` 互不干扰,迁移期两套 CLI 可在同一台机器共存。
107
+ `~/.tokenusage/`(`0700` 目录 + `0600` 文件):`tracker/config.json`(配对与运行配置)、上传队列(`queue.jsonl` + offset)、会话分析 sidecar、`session-upload-watermarks.json`(增量水位)、`tracker/logs/sync.log`(自动采集滚动日志)、暂停标志。与旧版 tokentracker CLI 的 `~/.tokentracker/` 互不干扰,迁移期两套 CLI 可在同一台机器共存。
80
108
 
81
109
  ## provider 支持面
82
110
 
@@ -91,4 +119,5 @@ pnpm install # 仓库根
91
119
  pnpm --filter tokenusage-cli test
92
120
  ```
93
121
 
94
- 发布(npm)是操作者动作,本包 `private: true`。
122
+ 发布走仓库的 `cli-v*` tag 触发的 GitHub Actions(Trusted Publishing,见
123
+ `docs/cli-release.md`)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tokenusage-cli",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Self-hosted AI coding token usage collector for token-usage (forked from TokenTracker, MIT).",
5
5
  "keywords": [
6
6
  "token-usage",
@@ -603,7 +603,7 @@ async function cmdSync(argv, context = {}) {
603
603
  const syncRun = isRunReportEnabled(trackerDir)
604
604
  ? createSyncRunTelemetry({
605
605
  trigger: resolveSyncTrigger(opts, context),
606
- cliVersion: require("../package.json").version,
606
+ cliVersion: require("../../package.json").version,
607
607
  })
608
608
  : null;
609
609
  // Manual CLI sync is a one-time upload request, without changing the toggle.
@@ -179,3 +179,32 @@ test("hidden-runner VBS quotes paths individually and propagates the exit code",
179
179
  // The task name stays stable — pause/resume and uninstall toggle by name.
180
180
  assert.equal(TASK_NAME, "TokenUsageSync");
181
181
  });
182
+
183
+ // Runtime-require depth guard: a `require("../package.json")` inside src/commands
184
+ // or src/lib resolves to a nonexistent src/package.json and only explodes when
185
+ // the lazy call site runs (0.2.0 shipped exactly this in sync.js's report tail —
186
+ // the smoke tests never execute it). Only src/cli.js sits at the depth where the
187
+ // one-level form is valid; everything nested deeper must use ../../.
188
+ test("no nested module resolves package.json at the wrong depth", () => {
189
+ const srcDir = path.join(__dirname, "..", "src");
190
+ const offenders = [];
191
+
192
+ const walk = (dir) => {
193
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
194
+ const full = path.join(dir, entry.name);
195
+ if (entry.isDirectory()) {
196
+ walk(full);
197
+ } else if (entry.name.endsWith(".js")) {
198
+ const source = fs.readFileSync(full, "utf8");
199
+ if (source.includes('require("../package.json")')) {
200
+ const relative = path.relative(srcDir, full).split(path.sep).join("/");
201
+
202
+ if (relative !== "cli.js") offenders.push(relative);
203
+ }
204
+ }
205
+ }
206
+ };
207
+
208
+ walk(srcDir);
209
+ assert.deepEqual(offenders, []);
210
+ });