tokenusage-cli 0.1.0 → 0.2.0

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.
Files changed (131) hide show
  1. package/CHANGELOG.md +39 -19
  2. package/LICENSE +22 -22
  3. package/README.md +94 -94
  4. package/THIRD_PARTY_NOTICES.md +140 -140
  5. package/bin/tokenusage.js +69 -69
  6. package/package.json +59 -59
  7. package/src/cli.js +146 -134
  8. package/src/commands/device-login.js +205 -205
  9. package/src/commands/diagnostics.js +38 -38
  10. package/src/commands/doctor.js +110 -110
  11. package/src/commands/init.js +2484 -2436
  12. package/src/commands/pause.js +77 -0
  13. package/src/commands/sessions.js +29 -29
  14. package/src/commands/status.js +1758 -1747
  15. package/src/commands/sync.js +8048 -7934
  16. package/src/commands/uninstall.js +322 -312
  17. package/src/lib/account-usage-dedup.js +267 -267
  18. package/src/lib/antigravity-paths.js +48 -48
  19. package/src/lib/ark-agent-plan-limits.js +438 -438
  20. package/src/lib/ark-coding-plan-limits.js +537 -537
  21. package/src/lib/async-queue-reader.js +138 -138
  22. package/src/lib/atomic-json.js +27 -27
  23. package/src/lib/bearer-token.js +11 -11
  24. package/src/lib/categorizer-utils.js +232 -232
  25. package/src/lib/claude-categorizer.js +1343 -1343
  26. package/src/lib/claude-config.js +279 -279
  27. package/src/lib/claude-user-identity.js +56 -56
  28. package/src/lib/cli-ui.js +179 -179
  29. package/src/lib/cloud-account.js +541 -541
  30. package/src/lib/cloud-device-token.js +141 -141
  31. package/src/lib/cloud-sync-prefs.js +14 -14
  32. package/src/lib/cloud-usage-reset.js +115 -115
  33. package/src/lib/codex-config.js +595 -595
  34. package/src/lib/codex-context-breakdown.js +806 -806
  35. package/src/lib/codex-model-attribution.js +128 -128
  36. package/src/lib/codex-rollout-parser.js +1471 -1471
  37. package/src/lib/codex-service-tier.js +49 -49
  38. package/src/lib/codex-token-refresh.js +140 -140
  39. package/src/lib/codex-token-usage.js +195 -195
  40. package/src/lib/codex-usage-record.js +195 -195
  41. package/src/lib/collection-pause.js +77 -0
  42. package/src/lib/command-runner.js +313 -313
  43. package/src/lib/commandcode-limits.js +317 -317
  44. package/src/lib/context-health.js +124 -124
  45. package/src/lib/cursor-config.js +605 -605
  46. package/src/lib/cursor-store.js +1918 -1918
  47. package/src/lib/debug-flags.js +7 -7
  48. package/src/lib/devin-limits.js +249 -249
  49. package/src/lib/devin-usage.js +212 -212
  50. package/src/lib/diagnostics.js +383 -383
  51. package/src/lib/doctor.js +385 -385
  52. package/src/lib/dumate.js +95 -95
  53. package/src/lib/fs.js +455 -455
  54. package/src/lib/function-url.js +14 -14
  55. package/src/lib/gemini-config.js +291 -291
  56. package/src/lib/git-outcomes.js +243 -243
  57. package/src/lib/grok-context-breakdown.js +890 -890
  58. package/src/lib/grok-hook.js +360 -360
  59. package/src/lib/grok-limits.js +865 -865
  60. package/src/lib/grok-usage.js +98 -98
  61. package/src/lib/heatmap-compact.js +114 -114
  62. package/src/lib/ingest-sanitize.js +41 -41
  63. package/src/lib/init-flow.js +42 -42
  64. package/src/lib/install-resolver.js +170 -170
  65. package/src/lib/jsonl-lines.js +134 -134
  66. package/src/lib/kimi-model-repair.js +173 -173
  67. package/src/lib/kimi-profile.js +61 -61
  68. package/src/lib/kimi-session.js +216 -216
  69. package/src/lib/local-api.js +3588 -3588
  70. package/src/lib/machine-id.js +238 -238
  71. package/src/lib/multi-install-parser.js +113 -113
  72. package/src/lib/notify-command.js +38 -38
  73. package/src/lib/omp-hook.js +589 -589
  74. package/src/lib/openclaw-cli.js +104 -104
  75. package/src/lib/openclaw-hook.js +375 -375
  76. package/src/lib/openclaw-session-plugin.js +560 -560
  77. package/src/lib/opencode-config.js +121 -121
  78. package/src/lib/opencode-go-limits.js +807 -807
  79. package/src/lib/outcomes-engine.js +253 -253
  80. package/src/lib/passive-mode.js +219 -219
  81. package/src/lib/pet-packages.js +722 -722
  82. package/src/lib/pricing/curated-overrides.json +822 -822
  83. package/src/lib/pricing/index.js +379 -379
  84. package/src/lib/pricing/litellm-fetcher.js +172 -172
  85. package/src/lib/pricing/matcher.js +456 -456
  86. package/src/lib/pricing/seed-snapshot.json +1 -1
  87. package/src/lib/progress.js +76 -76
  88. package/src/lib/project-usage-purge.js +117 -117
  89. package/src/lib/prompt.js +24 -24
  90. package/src/lib/provider-status.js +104 -104
  91. package/src/lib/proxy-env.js +489 -489
  92. package/src/lib/proxy-settings.js +163 -163
  93. package/src/lib/qoder-cn-cli-limits.js +119 -119
  94. package/src/lib/qoder-limits.js +880 -880
  95. package/src/lib/quiet-warnings.js +26 -26
  96. package/src/lib/rollout.js +26005 -25966
  97. package/src/lib/runtime-config.js +9 -4
  98. package/src/lib/scan-roots.js +277 -277
  99. package/src/lib/scheduled-task.js +145 -0
  100. package/src/lib/sentry.js +231 -231
  101. package/src/lib/session-analytics.js +2972 -2972
  102. package/src/lib/session-performance.js +237 -237
  103. package/src/lib/session-upload.js +379 -379
  104. package/src/lib/skill-usage.js +267 -267
  105. package/src/lib/skills-manager.js +1591 -1591
  106. package/src/lib/source-metadata.js +48 -48
  107. package/src/lib/sqlite-reader.js +215 -215
  108. package/src/lib/star-cta.js +73 -73
  109. package/src/lib/subscription-manager.js +293 -293
  110. package/src/lib/subscriptions.js +508 -508
  111. package/src/lib/sync-report.js +138 -0
  112. package/src/lib/telemetry.js +193 -193
  113. package/src/lib/tracker-paths.js +16 -16
  114. package/src/lib/trae-cn-config.js +548 -548
  115. package/src/lib/trae-db.js +127 -127
  116. package/src/lib/trae-snapshot.js +230 -230
  117. package/src/lib/trae-sqlite.js +143 -143
  118. package/src/lib/trae-usage.js +121 -121
  119. package/src/lib/upload-queue.js +134 -134
  120. package/src/lib/upload-throttle.js +171 -171
  121. package/src/lib/usage-limits.js +4552 -4552
  122. package/src/lib/wrapped-aggregator.js +236 -236
  123. package/src/lib/wsl-probe.js +281 -281
  124. package/src/lib/zcode-limits.js +1172 -1172
  125. package/src/lib/zcode-reset-credits.js +66 -66
  126. package/test/audit-fixes.test.js +200 -0
  127. package/test/cli-smoke.test.js +53 -53
  128. package/test/collection-controls.test.js +181 -0
  129. package/test/ingest-sanitize.test.js +162 -162
  130. package/test/quiet-warnings.test.js +53 -53
  131. package/test/session-upload.test.js +427 -427
package/src/lib/fs.js CHANGED
@@ -1,455 +1,455 @@
1
- const fs = require("node:fs/promises");
2
- const crypto = require("node:crypto");
3
- const path = require("node:path");
4
-
5
- async function ensureDir(p) {
6
- await fs.mkdir(p, { recursive: true });
7
- }
8
-
9
- async function writeFileAtomic(filePath, content, { mode } = {}) {
10
- const dir = path.dirname(filePath);
11
- await ensureDir(dir);
12
- // Include a UUID so two writes in the same millisecond do not share a tmp
13
- // path (Date.now() alone collides under concurrent writers).
14
- const tmp = `${filePath}.tmp.${Date.now()}.${crypto.randomUUID()}`;
15
- // mode only applies to newly created files; passing it keeps the tmp file
16
- // private from creation instead of relying on a later chmod that a crash
17
- // between write and chmod would skip.
18
- try {
19
- await fs.writeFile(
20
- tmp,
21
- content,
22
- mode == null ? { encoding: "utf8" } : { encoding: "utf8", mode },
23
- );
24
- await fs.rename(tmp, filePath);
25
- } catch (err) {
26
- try {
27
- await fs.unlink(tmp);
28
- } catch {
29
- /* tmp may not exist if writeFile failed before creating it */
30
- }
31
- throw err;
32
- }
33
- }
34
-
35
- async function readJson(filePath) {
36
- try {
37
- const raw = await fs.readFile(filePath, "utf8");
38
- return JSON.parse(raw);
39
- } catch (_e) {
40
- return null;
41
- }
42
- }
43
-
44
- async function readJsonStrict(filePath) {
45
- try {
46
- const raw = await fs.readFile(filePath, "utf8");
47
- return { status: "ok", value: JSON.parse(raw), error: null };
48
- } catch (err) {
49
- if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
50
- return { status: "missing", value: null, error: err };
51
- }
52
- if (err && err.name === "SyntaxError") {
53
- return { status: "invalid", value: null, error: err };
54
- }
55
- return { status: "error", value: null, error: err };
56
- }
57
- }
58
-
59
- async function writeJson(filePath, obj) {
60
- await writeFileAtomic(filePath, JSON.stringify(obj, null, 2) + "\n");
61
- }
62
-
63
- async function chmod600IfPossible(filePath) {
64
- try {
65
- await fs.chmod(filePath, 0o600);
66
- } catch (_e) {}
67
- }
68
-
69
- const LOCK_STALE_MS = 5 * 60 * 1000; // 5 minutes
70
- const LOCK_HEARTBEAT_MS = 30 * 1000;
71
- const MAX_RECLAIM_DEPTH = 4;
72
- const MAX_RECLAIM_SWEEP_DEPTH = 64;
73
- const TRANSITION_GUARD_RETRY_MS = 5;
74
- const TRANSITION_GUARD_ATTEMPTS = 1000;
75
-
76
- function parseLockOwner(raw) {
77
- try {
78
- const parsed = JSON.parse(raw);
79
- const pid = Number(parsed?.pid);
80
- const token = typeof parsed?.token === "string" ? parsed.token : null;
81
- if (!Number.isSafeInteger(pid) || pid <= 0 || !token) return null;
82
- return { pid, token };
83
- } catch (_e) {
84
- return null;
85
- }
86
- }
87
-
88
- function heartbeatPathFor(lockPath, token) {
89
- const tokenDigest = crypto.createHash("sha256").update(token, "utf8").digest("hex");
90
- return `${lockPath}.heartbeat.${tokenDigest}`;
91
- }
92
-
93
- function isProcessAlive(pid) {
94
- try {
95
- process.kill(pid, 0);
96
- return true;
97
- } catch (e) {
98
- if (e?.code === "ESRCH") return false;
99
- // EPERM means the process exists but belongs to another user. Unknown
100
- // errors are treated conservatively so a live lock is never reclaimed.
101
- return true;
102
- }
103
- }
104
-
105
- async function existingLockCanBeReclaimed(lockPath) {
106
- let lockHandle = null;
107
- try {
108
- // Inspect one opened inode instead of stat-ing a path and then reading
109
- // that path. The latter is a TOCTOU window and is also unsafe if a
110
- // concurrent reclaimer replaces the lock between the two operations.
111
- lockHandle = await fs.open(lockPath, "r");
112
- const [stat, raw] = await Promise.all([
113
- lockHandle.stat(),
114
- lockHandle.readFile({ encoding: "utf8" }),
115
- ]);
116
- const owner = parseLockOwner(raw);
117
- if (owner) {
118
- if (!isProcessAlive(owner.pid)) return true;
119
-
120
- // New leases keep a token-specific heartbeat separate from the owner
121
- // file. This lets a PID that has since been reused be recognized as an
122
- // abandoned lease without reclaiming a live, long-running sync whose
123
- // heartbeat is still fresh. Locks from before heartbeat support retain
124
- // the conservative live-PID behavior.
125
- let heartbeatHandle = null;
126
- try {
127
- heartbeatHandle = await fs.open(heartbeatPathFor(lockPath, owner.token), "r");
128
- const heartbeat = await heartbeatHandle.stat();
129
- return Date.now() - heartbeat.mtimeMs > LOCK_STALE_MS;
130
- } catch (_e) {
131
- return false;
132
- } finally {
133
- await heartbeatHandle?.close().catch(() => {});
134
- }
135
- }
136
- return Date.now() - stat.mtimeMs > LOCK_STALE_MS;
137
- } catch (e) {
138
- // The lock disappeared between open and inspection, so retry acquisition.
139
- if (e?.code === "ENOENT") return true;
140
- return false;
141
- } finally {
142
- await lockHandle?.close().catch(() => {});
143
- }
144
- }
145
-
146
- async function inspectLock(lockPath) {
147
- let raw = null;
148
- try {
149
- raw = await fs.readFile(lockPath, "utf8");
150
- } catch (e) {
151
- if (e?.code === "ENOENT") return { exists: false, pid: null, alive: false };
152
- return { exists: true, pid: null, alive: true };
153
- }
154
- const owner = parseLockOwner(raw);
155
- if (!owner) return { exists: true, pid: null, alive: true };
156
- return { exists: true, pid: owner.pid, alive: isProcessAlive(owner.pid) };
157
- }
158
-
159
- // Drop an abandoned lock file. The rename makes the removal atomic, so two
160
- // sweepers racing on the same debris cannot delete a lease installed in
161
- // between: only the winner of the rename removes anything.
162
- async function removeAbandonedLockFile(lockPath) {
163
- if (!(await existingLockCanBeReclaimed(lockPath))) return false;
164
- const quarantinePath = `${lockPath}.stale.${process.pid}.${crypto.randomUUID()}`;
165
- try {
166
- await fs.rename(lockPath, quarantinePath);
167
- } catch (_e) {
168
- return false;
169
- }
170
- const owner = parseLockOwner(await fs.readFile(quarantinePath, "utf8").catch(() => ""));
171
- if (owner) {
172
- await fs.unlink(heartbeatPathFor(lockPath, owner.token)).catch(() => {});
173
- }
174
- await fs.unlink(quarantinePath).catch(() => {});
175
- return true;
176
- }
177
-
178
- // A sync killed while it held a transition guard leaves `${lockPath}.reclaim`
179
- // behind, and the next reclaimer then nests its own guard on top of that
180
- // orphan. Four nested levels exhaust MAX_RECLAIM_DEPTH, after which every
181
- // acquisition gives up forever instead of healing (issue #431). Recursion
182
- // cannot clean the chain — each level needs a guard one level deeper — so sweep
183
- // it iteratively. Only levels whose owner is dead or whose heartbeat expired are
184
- // removed, deepest first: dropping a shallow guard while a deeper orphan
185
- // survives would just rebuild the same clogged chain on the next attempt.
186
- async function sweepAbandonedReclaimGuards(lockPath) {
187
- const chain = [];
188
- let guardPath = lockPath;
189
- for (let depth = 0; depth < MAX_RECLAIM_SWEEP_DEPTH; depth += 1) {
190
- guardPath = `${guardPath}.reclaim`;
191
- try {
192
- await fs.access(guardPath);
193
- } catch (_e) {
194
- break;
195
- }
196
- chain.push(guardPath);
197
- }
198
-
199
- let removed = 0;
200
- for (let index = chain.length - 1; index >= 0; index -= 1) {
201
- if (await removeAbandonedLockFile(chain[index])) removed += 1;
202
- }
203
- return removed > 0;
204
- }
205
-
206
- function startLockHeartbeat(handle, heartbeatHandle) {
207
- const beat = async () => {
208
- try {
209
- const now = new Date();
210
- await Promise.all([
211
- handle.utimes(now, now),
212
- heartbeatHandle.utimes(now, now),
213
- ]);
214
- } catch (_e) {
215
- // A failed heartbeat makes the lease eligible for bounded stale
216
- // reclamation. The owning sync will still finish or release normally.
217
- }
218
- };
219
- const timer = setInterval(() => {
220
- void beat();
221
- }, LOCK_HEARTBEAT_MS);
222
- timer.unref?.();
223
- return timer;
224
- }
225
-
226
- async function releaseOwnedLock(
227
- lockPath,
228
- handle,
229
- heartbeatHandle,
230
- heartbeatTimer,
231
- token,
232
- {
233
- beforeReleaseUnlink = null,
234
- reclaimDepth = 0,
235
- serializeRelease = true,
236
- } = {},
237
- ) {
238
- let transitionGuard = null;
239
- if (serializeRelease) {
240
- // Reclaimers use the same guard while moving a stale lease aside. Holding
241
- // it across token validation and unlink makes that ownership transition
242
- // indivisible: an old owner cannot delete a replacement installed by a
243
- // concurrent stale-lock reclaimer.
244
- for (let attempt = 0; attempt < TRANSITION_GUARD_ATTEMPTS; attempt += 1) {
245
- transitionGuard = await openLock(`${lockPath}.reclaim`, {
246
- quietIfLocked: true,
247
- reclaimDepth: reclaimDepth + 1,
248
- // This short-lived internal guard is the serialization primitive; its
249
- // own release must not recursively acquire another transition guard.
250
- serializeRelease: false,
251
- });
252
- if (transitionGuard) break;
253
- await new Promise((resolve) => setTimeout(resolve, TRANSITION_GUARD_RETRY_MS));
254
- }
255
- if (!transitionGuard) {
256
- clearInterval(heartbeatTimer);
257
- await handle.close().catch(() => {});
258
- await heartbeatHandle?.close().catch(() => {});
259
- await fs.unlink(heartbeatPathFor(lockPath, token)).catch(() => {});
260
- throw new Error(`Timed out serializing lock release: ${lockPath}`);
261
- }
262
- }
263
-
264
- try {
265
- clearInterval(heartbeatTimer);
266
- await handle.close().catch(() => {});
267
- await heartbeatHandle?.close().catch(() => {});
268
- const owner = parseLockOwner(await fs.readFile(lockPath, "utf8"));
269
- if (owner?.token === token) {
270
- if (typeof beforeReleaseUnlink === "function") {
271
- await beforeReleaseUnlink({ lockPath });
272
- }
273
- await fs.unlink(lockPath).catch(() => {});
274
- await fs.unlink(heartbeatPathFor(lockPath, token)).catch(() => {});
275
- }
276
- } catch (_e) {
277
- // Missing or replaced owner paths are already released from this token's
278
- // perspective. Other failures retain the conservative no-delete outcome.
279
- } finally {
280
- await transitionGuard?.release();
281
- }
282
- }
283
-
284
- async function openLock(
285
- lockPath,
286
- {
287
- quietIfLocked = false,
288
- beforeReclaim = null,
289
- beforeReleaseUnlink = null,
290
- reclaimDepth = 0,
291
- serializeRelease = true,
292
- sweptReclaimGuards = false,
293
- } = {},
294
- ) {
295
- try {
296
- const handle = await fs.open(lockPath, "wx");
297
- const token = crypto.randomUUID();
298
- const heartbeatPath = heartbeatPathFor(lockPath, token);
299
- let heartbeatHandle = null;
300
- try {
301
- await handle.writeFile(
302
- JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() }) + "\n",
303
- "utf8",
304
- );
305
- heartbeatHandle = await fs.open(heartbeatPath, "wx");
306
- await heartbeatHandle.writeFile(`${token}\n`, "utf8");
307
- const heartbeatTimer = startLockHeartbeat(handle, heartbeatHandle);
308
- return {
309
- async release() {
310
- await releaseOwnedLock(
311
- lockPath,
312
- handle,
313
- heartbeatHandle,
314
- heartbeatTimer,
315
- token,
316
- {
317
- beforeReleaseUnlink,
318
- reclaimDepth,
319
- serializeRelease,
320
- },
321
- );
322
- },
323
- };
324
- } catch (e) {
325
- await heartbeatHandle?.close().catch(() => {});
326
- await fs.unlink(heartbeatPath).catch(() => {});
327
- await handle.close().catch(() => {});
328
- await fs.unlink(lockPath).catch(() => {});
329
- throw e;
330
- }
331
- } catch (e) {
332
- if (e && e.code === "EEXIST") {
333
- if (await existingLockCanBeReclaimed(lockPath)) {
334
- if (typeof beforeReclaim === "function") {
335
- await beforeReclaim({ lockPath });
336
- }
337
- if (reclaimDepth >= MAX_RECLAIM_DEPTH) return null;
338
-
339
- // Serialize all reclaimers before re-checking the target. A stale
340
- // check can be shared by many contenders; only the holder of this
341
- // atomic guard may move the old lease out of the way.
342
- const reclaimGuard = await openLock(`${lockPath}.reclaim`, {
343
- quietIfLocked: true,
344
- reclaimDepth: reclaimDepth + 1,
345
- serializeRelease: false,
346
- });
347
- if (!reclaimGuard) {
348
- // Either a live reclaimer holds the guard (nothing to do) or the guard
349
- // chain is clogged with abandoned guards. Sweeping the latter is the
350
- // only escape, and it is attempted once per acquisition. beforeReclaim
351
- // already ran, so the retry must not invoke it a second time.
352
- if (!sweptReclaimGuards && (await sweepAbandonedReclaimGuards(lockPath))) {
353
- return openLock(lockPath, {
354
- quietIfLocked,
355
- beforeReleaseUnlink,
356
- reclaimDepth,
357
- serializeRelease,
358
- sweptReclaimGuards: true,
359
- });
360
- }
361
- return null;
362
- }
363
-
364
- let quarantinePath = null;
365
- try {
366
- // Re-check while holding the guard. A competing reclaimer may have
367
- // already replaced the target since our initial stale inspection.
368
- if (!(await existingLockCanBeReclaimed(lockPath))) return null;
369
-
370
- quarantinePath = `${lockPath}.stale.${process.pid}.${crypto.randomUUID()}`;
371
- try {
372
- await fs.rename(lockPath, quarantinePath);
373
- } catch (renameError) {
374
- if (renameError?.code === "ENOENT") {
375
- return openLock(lockPath, {
376
- quietIfLocked,
377
- beforeReleaseUnlink,
378
- reclaimDepth,
379
- serializeRelease,
380
- });
381
- }
382
- if (!quietIfLocked) {
383
- process.stdout.write("Another sync is already running.\n");
384
- }
385
- return null;
386
- }
387
-
388
- const staleOwner = parseLockOwner(
389
- await fs.readFile(quarantinePath, "utf8").catch(() => ""),
390
- );
391
- if (staleOwner) {
392
- // The heartbeat name contains the old token, so it cannot belong
393
- // to a replacement lease created after the atomic rename.
394
- await fs.unlink(heartbeatPathFor(lockPath, staleOwner.token)).catch(() => {});
395
- }
396
- return await openLock(lockPath, {
397
- quietIfLocked,
398
- beforeReleaseUnlink,
399
- reclaimDepth,
400
- serializeRelease,
401
- });
402
- } finally {
403
- if (quarantinePath) await fs.unlink(quarantinePath).catch(() => {});
404
- await reclaimGuard.release();
405
- }
406
- }
407
- if (!quietIfLocked) {
408
- process.stdout.write("Another sync is already running.\n");
409
- }
410
- return null;
411
- }
412
- throw e;
413
- }
414
- }
415
-
416
- async function updateJsonLocked(
417
- filePath,
418
- update,
419
- { timeoutMs = 30_000, retryMs = 10 } = {},
420
- ) {
421
- const lockPath = `${filePath}.lock`;
422
- const deadline = Date.now() + timeoutMs;
423
- let lock = null;
424
- while (!lock) {
425
- lock = await openLock(lockPath, { quietIfLocked: true });
426
- if (lock) break;
427
- if (Date.now() >= deadline) {
428
- throw new Error(`Timed out waiting to update JSON file: ${filePath}`);
429
- }
430
- await new Promise((resolve) => setTimeout(resolve, retryMs));
431
- }
432
-
433
- try {
434
- const current = (await readJson(filePath)) || {};
435
- const next = await update(current);
436
- if (next == null) return current;
437
- await writeJson(filePath, next);
438
- await chmod600IfPossible(filePath);
439
- return next;
440
- } finally {
441
- await lock.release();
442
- }
443
- }
444
-
445
- module.exports = {
446
- ensureDir,
447
- writeFileAtomic,
448
- readJson,
449
- readJsonStrict,
450
- writeJson,
451
- chmod600IfPossible,
452
- openLock,
453
- inspectLock,
454
- updateJsonLocked,
455
- };
1
+ const fs = require("node:fs/promises");
2
+ const crypto = require("node:crypto");
3
+ const path = require("node:path");
4
+
5
+ async function ensureDir(p) {
6
+ await fs.mkdir(p, { recursive: true });
7
+ }
8
+
9
+ async function writeFileAtomic(filePath, content, { mode } = {}) {
10
+ const dir = path.dirname(filePath);
11
+ await ensureDir(dir);
12
+ // Include a UUID so two writes in the same millisecond do not share a tmp
13
+ // path (Date.now() alone collides under concurrent writers).
14
+ const tmp = `${filePath}.tmp.${Date.now()}.${crypto.randomUUID()}`;
15
+ // mode only applies to newly created files; passing it keeps the tmp file
16
+ // private from creation instead of relying on a later chmod that a crash
17
+ // between write and chmod would skip.
18
+ try {
19
+ await fs.writeFile(
20
+ tmp,
21
+ content,
22
+ mode == null ? { encoding: "utf8" } : { encoding: "utf8", mode },
23
+ );
24
+ await fs.rename(tmp, filePath);
25
+ } catch (err) {
26
+ try {
27
+ await fs.unlink(tmp);
28
+ } catch {
29
+ /* tmp may not exist if writeFile failed before creating it */
30
+ }
31
+ throw err;
32
+ }
33
+ }
34
+
35
+ async function readJson(filePath) {
36
+ try {
37
+ const raw = await fs.readFile(filePath, "utf8");
38
+ return JSON.parse(raw);
39
+ } catch (_e) {
40
+ return null;
41
+ }
42
+ }
43
+
44
+ async function readJsonStrict(filePath) {
45
+ try {
46
+ const raw = await fs.readFile(filePath, "utf8");
47
+ return { status: "ok", value: JSON.parse(raw), error: null };
48
+ } catch (err) {
49
+ if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) {
50
+ return { status: "missing", value: null, error: err };
51
+ }
52
+ if (err && err.name === "SyntaxError") {
53
+ return { status: "invalid", value: null, error: err };
54
+ }
55
+ return { status: "error", value: null, error: err };
56
+ }
57
+ }
58
+
59
+ async function writeJson(filePath, obj) {
60
+ await writeFileAtomic(filePath, JSON.stringify(obj, null, 2) + "\n");
61
+ }
62
+
63
+ async function chmod600IfPossible(filePath) {
64
+ try {
65
+ await fs.chmod(filePath, 0o600);
66
+ } catch (_e) {}
67
+ }
68
+
69
+ const LOCK_STALE_MS = 5 * 60 * 1000; // 5 minutes
70
+ const LOCK_HEARTBEAT_MS = 30 * 1000;
71
+ const MAX_RECLAIM_DEPTH = 4;
72
+ const MAX_RECLAIM_SWEEP_DEPTH = 64;
73
+ const TRANSITION_GUARD_RETRY_MS = 5;
74
+ const TRANSITION_GUARD_ATTEMPTS = 1000;
75
+
76
+ function parseLockOwner(raw) {
77
+ try {
78
+ const parsed = JSON.parse(raw);
79
+ const pid = Number(parsed?.pid);
80
+ const token = typeof parsed?.token === "string" ? parsed.token : null;
81
+ if (!Number.isSafeInteger(pid) || pid <= 0 || !token) return null;
82
+ return { pid, token };
83
+ } catch (_e) {
84
+ return null;
85
+ }
86
+ }
87
+
88
+ function heartbeatPathFor(lockPath, token) {
89
+ const tokenDigest = crypto.createHash("sha256").update(token, "utf8").digest("hex");
90
+ return `${lockPath}.heartbeat.${tokenDigest}`;
91
+ }
92
+
93
+ function isProcessAlive(pid) {
94
+ try {
95
+ process.kill(pid, 0);
96
+ return true;
97
+ } catch (e) {
98
+ if (e?.code === "ESRCH") return false;
99
+ // EPERM means the process exists but belongs to another user. Unknown
100
+ // errors are treated conservatively so a live lock is never reclaimed.
101
+ return true;
102
+ }
103
+ }
104
+
105
+ async function existingLockCanBeReclaimed(lockPath) {
106
+ let lockHandle = null;
107
+ try {
108
+ // Inspect one opened inode instead of stat-ing a path and then reading
109
+ // that path. The latter is a TOCTOU window and is also unsafe if a
110
+ // concurrent reclaimer replaces the lock between the two operations.
111
+ lockHandle = await fs.open(lockPath, "r");
112
+ const [stat, raw] = await Promise.all([
113
+ lockHandle.stat(),
114
+ lockHandle.readFile({ encoding: "utf8" }),
115
+ ]);
116
+ const owner = parseLockOwner(raw);
117
+ if (owner) {
118
+ if (!isProcessAlive(owner.pid)) return true;
119
+
120
+ // New leases keep a token-specific heartbeat separate from the owner
121
+ // file. This lets a PID that has since been reused be recognized as an
122
+ // abandoned lease without reclaiming a live, long-running sync whose
123
+ // heartbeat is still fresh. Locks from before heartbeat support retain
124
+ // the conservative live-PID behavior.
125
+ let heartbeatHandle = null;
126
+ try {
127
+ heartbeatHandle = await fs.open(heartbeatPathFor(lockPath, owner.token), "r");
128
+ const heartbeat = await heartbeatHandle.stat();
129
+ return Date.now() - heartbeat.mtimeMs > LOCK_STALE_MS;
130
+ } catch (_e) {
131
+ return false;
132
+ } finally {
133
+ await heartbeatHandle?.close().catch(() => {});
134
+ }
135
+ }
136
+ return Date.now() - stat.mtimeMs > LOCK_STALE_MS;
137
+ } catch (e) {
138
+ // The lock disappeared between open and inspection, so retry acquisition.
139
+ if (e?.code === "ENOENT") return true;
140
+ return false;
141
+ } finally {
142
+ await lockHandle?.close().catch(() => {});
143
+ }
144
+ }
145
+
146
+ async function inspectLock(lockPath) {
147
+ let raw = null;
148
+ try {
149
+ raw = await fs.readFile(lockPath, "utf8");
150
+ } catch (e) {
151
+ if (e?.code === "ENOENT") return { exists: false, pid: null, alive: false };
152
+ return { exists: true, pid: null, alive: true };
153
+ }
154
+ const owner = parseLockOwner(raw);
155
+ if (!owner) return { exists: true, pid: null, alive: true };
156
+ return { exists: true, pid: owner.pid, alive: isProcessAlive(owner.pid) };
157
+ }
158
+
159
+ // Drop an abandoned lock file. The rename makes the removal atomic, so two
160
+ // sweepers racing on the same debris cannot delete a lease installed in
161
+ // between: only the winner of the rename removes anything.
162
+ async function removeAbandonedLockFile(lockPath) {
163
+ if (!(await existingLockCanBeReclaimed(lockPath))) return false;
164
+ const quarantinePath = `${lockPath}.stale.${process.pid}.${crypto.randomUUID()}`;
165
+ try {
166
+ await fs.rename(lockPath, quarantinePath);
167
+ } catch (_e) {
168
+ return false;
169
+ }
170
+ const owner = parseLockOwner(await fs.readFile(quarantinePath, "utf8").catch(() => ""));
171
+ if (owner) {
172
+ await fs.unlink(heartbeatPathFor(lockPath, owner.token)).catch(() => {});
173
+ }
174
+ await fs.unlink(quarantinePath).catch(() => {});
175
+ return true;
176
+ }
177
+
178
+ // A sync killed while it held a transition guard leaves `${lockPath}.reclaim`
179
+ // behind, and the next reclaimer then nests its own guard on top of that
180
+ // orphan. Four nested levels exhaust MAX_RECLAIM_DEPTH, after which every
181
+ // acquisition gives up forever instead of healing (issue #431). Recursion
182
+ // cannot clean the chain — each level needs a guard one level deeper — so sweep
183
+ // it iteratively. Only levels whose owner is dead or whose heartbeat expired are
184
+ // removed, deepest first: dropping a shallow guard while a deeper orphan
185
+ // survives would just rebuild the same clogged chain on the next attempt.
186
+ async function sweepAbandonedReclaimGuards(lockPath) {
187
+ const chain = [];
188
+ let guardPath = lockPath;
189
+ for (let depth = 0; depth < MAX_RECLAIM_SWEEP_DEPTH; depth += 1) {
190
+ guardPath = `${guardPath}.reclaim`;
191
+ try {
192
+ await fs.access(guardPath);
193
+ } catch (_e) {
194
+ break;
195
+ }
196
+ chain.push(guardPath);
197
+ }
198
+
199
+ let removed = 0;
200
+ for (let index = chain.length - 1; index >= 0; index -= 1) {
201
+ if (await removeAbandonedLockFile(chain[index])) removed += 1;
202
+ }
203
+ return removed > 0;
204
+ }
205
+
206
+ function startLockHeartbeat(handle, heartbeatHandle) {
207
+ const beat = async () => {
208
+ try {
209
+ const now = new Date();
210
+ await Promise.all([
211
+ handle.utimes(now, now),
212
+ heartbeatHandle.utimes(now, now),
213
+ ]);
214
+ } catch (_e) {
215
+ // A failed heartbeat makes the lease eligible for bounded stale
216
+ // reclamation. The owning sync will still finish or release normally.
217
+ }
218
+ };
219
+ const timer = setInterval(() => {
220
+ void beat();
221
+ }, LOCK_HEARTBEAT_MS);
222
+ timer.unref?.();
223
+ return timer;
224
+ }
225
+
226
+ async function releaseOwnedLock(
227
+ lockPath,
228
+ handle,
229
+ heartbeatHandle,
230
+ heartbeatTimer,
231
+ token,
232
+ {
233
+ beforeReleaseUnlink = null,
234
+ reclaimDepth = 0,
235
+ serializeRelease = true,
236
+ } = {},
237
+ ) {
238
+ let transitionGuard = null;
239
+ if (serializeRelease) {
240
+ // Reclaimers use the same guard while moving a stale lease aside. Holding
241
+ // it across token validation and unlink makes that ownership transition
242
+ // indivisible: an old owner cannot delete a replacement installed by a
243
+ // concurrent stale-lock reclaimer.
244
+ for (let attempt = 0; attempt < TRANSITION_GUARD_ATTEMPTS; attempt += 1) {
245
+ transitionGuard = await openLock(`${lockPath}.reclaim`, {
246
+ quietIfLocked: true,
247
+ reclaimDepth: reclaimDepth + 1,
248
+ // This short-lived internal guard is the serialization primitive; its
249
+ // own release must not recursively acquire another transition guard.
250
+ serializeRelease: false,
251
+ });
252
+ if (transitionGuard) break;
253
+ await new Promise((resolve) => setTimeout(resolve, TRANSITION_GUARD_RETRY_MS));
254
+ }
255
+ if (!transitionGuard) {
256
+ clearInterval(heartbeatTimer);
257
+ await handle.close().catch(() => {});
258
+ await heartbeatHandle?.close().catch(() => {});
259
+ await fs.unlink(heartbeatPathFor(lockPath, token)).catch(() => {});
260
+ throw new Error(`Timed out serializing lock release: ${lockPath}`);
261
+ }
262
+ }
263
+
264
+ try {
265
+ clearInterval(heartbeatTimer);
266
+ await handle.close().catch(() => {});
267
+ await heartbeatHandle?.close().catch(() => {});
268
+ const owner = parseLockOwner(await fs.readFile(lockPath, "utf8"));
269
+ if (owner?.token === token) {
270
+ if (typeof beforeReleaseUnlink === "function") {
271
+ await beforeReleaseUnlink({ lockPath });
272
+ }
273
+ await fs.unlink(lockPath).catch(() => {});
274
+ await fs.unlink(heartbeatPathFor(lockPath, token)).catch(() => {});
275
+ }
276
+ } catch (_e) {
277
+ // Missing or replaced owner paths are already released from this token's
278
+ // perspective. Other failures retain the conservative no-delete outcome.
279
+ } finally {
280
+ await transitionGuard?.release();
281
+ }
282
+ }
283
+
284
+ async function openLock(
285
+ lockPath,
286
+ {
287
+ quietIfLocked = false,
288
+ beforeReclaim = null,
289
+ beforeReleaseUnlink = null,
290
+ reclaimDepth = 0,
291
+ serializeRelease = true,
292
+ sweptReclaimGuards = false,
293
+ } = {},
294
+ ) {
295
+ try {
296
+ const handle = await fs.open(lockPath, "wx");
297
+ const token = crypto.randomUUID();
298
+ const heartbeatPath = heartbeatPathFor(lockPath, token);
299
+ let heartbeatHandle = null;
300
+ try {
301
+ await handle.writeFile(
302
+ JSON.stringify({ pid: process.pid, token, createdAt: new Date().toISOString() }) + "\n",
303
+ "utf8",
304
+ );
305
+ heartbeatHandle = await fs.open(heartbeatPath, "wx");
306
+ await heartbeatHandle.writeFile(`${token}\n`, "utf8");
307
+ const heartbeatTimer = startLockHeartbeat(handle, heartbeatHandle);
308
+ return {
309
+ async release() {
310
+ await releaseOwnedLock(
311
+ lockPath,
312
+ handle,
313
+ heartbeatHandle,
314
+ heartbeatTimer,
315
+ token,
316
+ {
317
+ beforeReleaseUnlink,
318
+ reclaimDepth,
319
+ serializeRelease,
320
+ },
321
+ );
322
+ },
323
+ };
324
+ } catch (e) {
325
+ await heartbeatHandle?.close().catch(() => {});
326
+ await fs.unlink(heartbeatPath).catch(() => {});
327
+ await handle.close().catch(() => {});
328
+ await fs.unlink(lockPath).catch(() => {});
329
+ throw e;
330
+ }
331
+ } catch (e) {
332
+ if (e && e.code === "EEXIST") {
333
+ if (await existingLockCanBeReclaimed(lockPath)) {
334
+ if (typeof beforeReclaim === "function") {
335
+ await beforeReclaim({ lockPath });
336
+ }
337
+ if (reclaimDepth >= MAX_RECLAIM_DEPTH) return null;
338
+
339
+ // Serialize all reclaimers before re-checking the target. A stale
340
+ // check can be shared by many contenders; only the holder of this
341
+ // atomic guard may move the old lease out of the way.
342
+ const reclaimGuard = await openLock(`${lockPath}.reclaim`, {
343
+ quietIfLocked: true,
344
+ reclaimDepth: reclaimDepth + 1,
345
+ serializeRelease: false,
346
+ });
347
+ if (!reclaimGuard) {
348
+ // Either a live reclaimer holds the guard (nothing to do) or the guard
349
+ // chain is clogged with abandoned guards. Sweeping the latter is the
350
+ // only escape, and it is attempted once per acquisition. beforeReclaim
351
+ // already ran, so the retry must not invoke it a second time.
352
+ if (!sweptReclaimGuards && (await sweepAbandonedReclaimGuards(lockPath))) {
353
+ return openLock(lockPath, {
354
+ quietIfLocked,
355
+ beforeReleaseUnlink,
356
+ reclaimDepth,
357
+ serializeRelease,
358
+ sweptReclaimGuards: true,
359
+ });
360
+ }
361
+ return null;
362
+ }
363
+
364
+ let quarantinePath = null;
365
+ try {
366
+ // Re-check while holding the guard. A competing reclaimer may have
367
+ // already replaced the target since our initial stale inspection.
368
+ if (!(await existingLockCanBeReclaimed(lockPath))) return null;
369
+
370
+ quarantinePath = `${lockPath}.stale.${process.pid}.${crypto.randomUUID()}`;
371
+ try {
372
+ await fs.rename(lockPath, quarantinePath);
373
+ } catch (renameError) {
374
+ if (renameError?.code === "ENOENT") {
375
+ return openLock(lockPath, {
376
+ quietIfLocked,
377
+ beforeReleaseUnlink,
378
+ reclaimDepth,
379
+ serializeRelease,
380
+ });
381
+ }
382
+ if (!quietIfLocked) {
383
+ process.stdout.write("Another sync is already running.\n");
384
+ }
385
+ return null;
386
+ }
387
+
388
+ const staleOwner = parseLockOwner(
389
+ await fs.readFile(quarantinePath, "utf8").catch(() => ""),
390
+ );
391
+ if (staleOwner) {
392
+ // The heartbeat name contains the old token, so it cannot belong
393
+ // to a replacement lease created after the atomic rename.
394
+ await fs.unlink(heartbeatPathFor(lockPath, staleOwner.token)).catch(() => {});
395
+ }
396
+ return await openLock(lockPath, {
397
+ quietIfLocked,
398
+ beforeReleaseUnlink,
399
+ reclaimDepth,
400
+ serializeRelease,
401
+ });
402
+ } finally {
403
+ if (quarantinePath) await fs.unlink(quarantinePath).catch(() => {});
404
+ await reclaimGuard.release();
405
+ }
406
+ }
407
+ if (!quietIfLocked) {
408
+ process.stdout.write("Another sync is already running.\n");
409
+ }
410
+ return null;
411
+ }
412
+ throw e;
413
+ }
414
+ }
415
+
416
+ async function updateJsonLocked(
417
+ filePath,
418
+ update,
419
+ { timeoutMs = 30_000, retryMs = 10 } = {},
420
+ ) {
421
+ const lockPath = `${filePath}.lock`;
422
+ const deadline = Date.now() + timeoutMs;
423
+ let lock = null;
424
+ while (!lock) {
425
+ lock = await openLock(lockPath, { quietIfLocked: true });
426
+ if (lock) break;
427
+ if (Date.now() >= deadline) {
428
+ throw new Error(`Timed out waiting to update JSON file: ${filePath}`);
429
+ }
430
+ await new Promise((resolve) => setTimeout(resolve, retryMs));
431
+ }
432
+
433
+ try {
434
+ const current = (await readJson(filePath)) || {};
435
+ const next = await update(current);
436
+ if (next == null) return current;
437
+ await writeJson(filePath, next);
438
+ await chmod600IfPossible(filePath);
439
+ return next;
440
+ } finally {
441
+ await lock.release();
442
+ }
443
+ }
444
+
445
+ module.exports = {
446
+ ensureDir,
447
+ writeFileAtomic,
448
+ readJson,
449
+ readJsonStrict,
450
+ writeJson,
451
+ chmod600IfPossible,
452
+ openLock,
453
+ inspectLock,
454
+ updateJsonLocked,
455
+ };