ccdeck 3.81.3 → 3.81.4

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.
@@ -24,7 +24,10 @@
24
24
  // and that day's date — numbers, never their names (see usage-day.mjs) —
25
25
  // and which of the deck's features were used that day, as fixed names
26
26
  // ("usage-history", "account-switch") and nothing about what was done
27
- // with them (feature-use.mjs), and how the deck held up and who runs it:
27
+ // with them (feature-use.mjs) — among them where the deck was looked at
28
+ // from that day: the desktop app's window ("desktop-window"), a browser
29
+ // tab ("browser-tab") or `ccdeck tui` ("tui"), a window or tab counted on
30
+ // every day it stayed open — and how the deck held up and who runs it:
28
31
  // how long this run took to start, that day's peak memory and how many
29
32
  // events it took in, each as a bucket ("2s", "512m", "1k"), the Claude and
30
33
  // Codex plan as its category ("max-20x", "plus") and nothing else from the
@@ -48,14 +51,22 @@
48
51
  // names, the host of every web address, every IP address and the machine
49
52
  // name a network error carries, email addresses and key-shaped strings
50
53
  // scrubbed out before they leave (see scrub),
51
- // - a "ping" heartbeat, every ten minutes or so while the deck runs, which
52
- // moves the install's "last seen" so the admin can show who is online now,
53
- // and is counted per day, which is how long the deck stays open.
54
+ // - a "ping" heartbeat, a minute or two after the deck starts and every ten
55
+ // minutes or so after that while it runs, which moves the install's "last
56
+ // seen" so the admin can show who is online now, and is counted per day,
57
+ // which is how long the deck stays open.
54
58
  // It writes no event and carries the install id alone — no facts, no
55
59
  // fingerprint.
56
60
  //
57
61
  // Each event carries the install id, the version, the OS and CPU architecture,
58
62
  // the channel (the desktop app, npm, or a source checkout) and the runtime, plus
63
+ // which release of the OS it is: on macOS and Windows the release as a token
64
+ // (`osVersion`, "macos-15", "windows-11", translated from the kernel version as
65
+ // os-version.mjs does for a paired deck's card), on Linux the distribution
66
+ // (`distro`, os-release's ID and VERSION_ID, "ubuntu-24.04" or "arch", or
67
+ // "omarchy" when Omarchy's folder is there — never os-release's free-text
68
+ // names) and `wsl: true` under WSL (each left out where it does not apply, and
69
+ // never on the ping, errors or feedback), and
59
70
  // a coarse sketch of the environment: the logical CPU count, the RAM in MB, the
60
71
  // locale, the language chosen in the deck's own page (`uiLanguage`, "ro" or
61
72
  // "pt-BR": the page tells the server, which keeps it in prefs.json and omits it
@@ -96,8 +107,11 @@
96
107
  // be refused the same way. A 4xx the edge in front of it answers with is tried again.
97
108
 
98
109
  import { createHash, randomUUID } from "node:crypto";
110
+ import { readFileSync, statSync } from "node:fs";
99
111
  import { chmod, mkdir, readFile, unlink } from "node:fs/promises";
100
- import { arch as osArch, cpus as osCpus, homedir, hostname, platform as osPlatform, totalmem } from "node:os";
112
+ import {
113
+ arch as osArch, cpus as osCpus, homedir, hostname, platform as osPlatform, release as osKernelRelease, totalmem,
114
+ } from "node:os";
101
115
  import { basename, dirname, join, resolve } from "node:path";
102
116
  import { fileURLToPath, pathToFileURL } from "node:url";
103
117
  import { inApp } from "./app-host.mjs";
@@ -111,6 +125,8 @@ import { RUNNING_VERSION } from "./running-version.mjs";
111
125
  import { FEATURES, usageDay, utcDay } from "./usage-day.mjs";
112
126
  import { setupFacts, sinceInstallBucket, whenSetupKnown } from "./activation.mjs";
113
127
  import { notedRef, refSlug } from "./install-ref.mjs";
128
+ import { isWsl } from "./open-url.mjs";
129
+ import { osReleaseFields, osVersionOf } from "./os-version.mjs";
114
130
  import { UI_LANGUAGE_MAX, uiLanguageCode } from "./ui-language.mjs";
115
131
  import {
116
132
  CLAUDE_PLANS, CODEX_PLANS, cappedCount, deckDepth, eventsBucket, installMarkFile, installVia, launchBucket,
@@ -131,6 +147,13 @@ const CHECK_IN_EVERY_MS = 6 * 60 * 60 * 1000;
131
147
  * not all beat on the same tick. */
132
148
  const PING_EVERY_MS = 10 * 60 * 1000;
133
149
  const PING_JITTER_MS = 2 * 60 * 1000;
150
+ /** One ping of its own soon after a start, one to two minutes in, ahead of the
151
+ * first beat. A restart on a day and a version already reported sends nothing
152
+ * at its check-in, so until the first beat the admin showed a restarted deck
153
+ * offline for ten minutes or more. Not at once: the boot check-in goes first,
154
+ * and a fleet started together still spreads out. The beats keep their pace. */
155
+ const FIRST_PING_MS = 60 * 1000;
156
+ const FIRST_PING_JITTER_MS = 60 * 1000;
134
157
  /** The longest a 429's or a 503's Retry-After is waited for: a header that asks
135
158
  * for a week does not silence a deck for one. */
136
159
  const RETRY_AFTER_MAX_MS = 24 * 60 * 60 * 1000;
@@ -175,7 +198,10 @@ export function reportsOn(prefs, env = process.env) {
175
198
  // The keys the API caps, so a value that would be rejected for length is not
176
199
  // sent: it is trimmed to the cap here instead. Only ever tokens the shape of a
177
200
  // terminal name, a shell name, a locale or a version — never anything free.
178
- const TOKEN_CAPS = { locale: 16, shell: 16, term: 32, claudeVersion: 32, codexVersion: 32, deviceId: 64, uiLanguage: UI_LANGUAGE_MAX };
201
+ const TOKEN_CAPS = {
202
+ locale: 16, shell: 16, term: 32, claudeVersion: 32, codexVersion: 32, deviceId: 64, uiLanguage: UI_LANGUAGE_MAX,
203
+ osVersion: 24, distro: 32,
204
+ };
179
205
 
180
206
  /** A value reduced to the API's token shape `^[0-9A-Za-z.+_-]+$`: spaces become
181
207
  * "_" (so "Apple Terminal" rides as "Apple_Terminal"), every other disallowed
@@ -315,6 +341,99 @@ function baseName(p) {
315
341
  return String(p).split(/[\\/]/).pop().replace(/\.exe$/i, "");
316
342
  }
317
343
 
344
+ /** The API's token shape. A distribution's own words leave only when they are
345
+ * already in it: nothing is reshaped into one, as `token` does for a terminal. */
346
+ const TOKEN_SHAPE = /^[0-9A-Za-z.+_-]+$/;
347
+
348
+ /** `value` when it is already a token no longer than `max`, else nothing. */
349
+ function shaped(value, max) {
350
+ return typeof value === "string" && TOKEN_SHAPE.test(value) && value.length <= max ? value : undefined;
351
+ }
352
+
353
+ /** The OS release as a token, on macOS and Windows only — "macos-15",
354
+ * "macos-26", "windows-10", "windows-11" — by the translation a paired deck's
355
+ * card uses (os-version.mjs). Nothing on Linux, which says its distribution
356
+ * instead (distroToken), and nothing for a release that cannot be told. */
357
+ export function osVersionToken({ platform = process.platform, release = "" } = {}) {
358
+ const v = osVersionOf({ platform, release });
359
+ return v ? shaped(`${v.family}-${v.major}`, TOKEN_CAPS.osVersion) : undefined;
360
+ }
361
+
362
+ /**
363
+ * The Linux distribution as a token: os-release's `ID`, lowercased, with its
364
+ * `VERSION_ID` after a dash when it has one — "ubuntu-24.04", "fedora-41",
365
+ * "debian-12", and "arch", which has none. Omarchy sits on Arch and leaves
366
+ * Arch's os-release in place, so it is told by the folder it installs into
367
+ * (`omarchy`, read by the caller) or by an os-release that names it, and is
368
+ * sent as "omarchy".
369
+ *
370
+ * Only what is already token-shaped leaves: an ID that is not, or is longer
371
+ * than the cap, is nothing at all; a version that is not, or that would take
372
+ * the token past the cap, leaves the ID alone. The free-text fields — NAME,
373
+ * PRETTY_NAME — are only ever looked through for "omarchy", never sent.
374
+ * Never throws.
375
+ */
376
+ export function distroToken({ osRelease = "", omarchy = false } = {}) {
377
+ try {
378
+ const f = osReleaseFields(osRelease);
379
+ if (omarchy === true || [f.ID, f.VARIANT_ID, f.NAME, f.PRETTY_NAME].some(v => /omarchy/i.test(v ?? ""))) return "omarchy";
380
+ const id = shaped(String(f.ID ?? "").trim().toLowerCase(), TOKEN_CAPS.distro);
381
+ if (!id) return undefined;
382
+ const version = String(f.VERSION_ID ?? "").trim().toLowerCase();
383
+ return (version && shaped(`${id}-${version}`, TOKEN_CAPS.distro)) || id;
384
+ } catch {
385
+ return undefined;
386
+ }
387
+ }
388
+
389
+ /**
390
+ * This Linux's distribution as distroToken words it: os-release from where the
391
+ * spec puts it, `/etc/os-release` and then `/usr/lib/os-release`, and Omarchy's
392
+ * folder under the home folder, which only ever answers yes or no. The reads
393
+ * are parameters so a test can stand up any machine. Never throws.
394
+ */
395
+ export function readDistro({ read = readFileSync, isDir = isDirectory, home = homedir() } = {}) {
396
+ let osRelease = "";
397
+ for (const file of ["/etc/os-release", "/usr/lib/os-release"]) {
398
+ try {
399
+ osRelease = String(read(file, "utf8"));
400
+ break;
401
+ } catch { /* not this one */ }
402
+ }
403
+ let omarchy = false;
404
+ try {
405
+ omarchy = isDir(join(home, ".local", "share", "omarchy")) === true;
406
+ } catch { /* no home, no Omarchy */ }
407
+ return distroToken({ osRelease, omarchy });
408
+ }
409
+
410
+ function isDirectory(path) {
411
+ try { return statSync(path).isDirectory(); } catch { return false; }
412
+ }
413
+
414
+ /** This machine's distribution, read the first time it is asked and kept:
415
+ * nothing it is read from changes under a running deck. */
416
+ let distroKept = null;
417
+ function machineDistro() {
418
+ if (!distroKept) {
419
+ let value;
420
+ try { value = readDistro(); } catch { value = undefined; }
421
+ distroKept = { value };
422
+ }
423
+ return distroKept.value;
424
+ }
425
+
426
+ /** The kernel's release, or "" when it will not say. */
427
+ function kernelRelease() {
428
+ try { return osKernelRelease(); } catch { return ""; }
429
+ }
430
+
431
+ /** Whether this Linux is WSL (open-url.mjs, which opens the browser on the
432
+ * Windows side for it). Never throws. */
433
+ function underWsl(platform, env) {
434
+ try { return isWsl(platform, env ?? {}) === true; } catch { return false; }
435
+ }
436
+
318
437
  function addIf(target, key, value) {
319
438
  if (value !== undefined) target[key] = value;
320
439
  }
@@ -324,13 +443,18 @@ function addIf(target, key, value) {
324
443
  * counts the API records as optional. `claudeVersion`/`codexVersion` are
325
444
  * supplied by the reporter once its background probe has them (cli-versions.mjs)
326
445
  * and omitted until then; everything else is read here from the OS and the
327
- * environment. */
446
+ * environment. The OS release, the distribution and WSL are read off this
447
+ * machine only when `platform` is this machine's, so a test that names
448
+ * another platform is never handed this one's. */
328
449
  export function installFacts({
329
450
  version = RUNNING_VERSION,
330
451
  platform = process.platform,
331
452
  arch = process.arch,
332
453
  versions = process.versions,
333
454
  env = process.env,
455
+ release = platform === process.platform ? kernelRelease() : "",
456
+ distro = platform === "linux" && platform === process.platform ? machineDistro() : undefined,
457
+ wsl = platform === "linux" && platform === process.platform ? underWsl(platform, env) : false,
334
458
  checkout = isGitCheckout(PKG_ROOT),
335
459
  cpus = cpuCount(),
336
460
  memMb = totalMemMb(),
@@ -351,6 +475,12 @@ export function installFacts({
351
475
  channel: inApp(env) ? "desktop" : checkout ? "checkout" : "npm",
352
476
  runtime: versions.electron ? `electron-${versions.electron}` : `node-${versions.node}`,
353
477
  };
478
+ // Which release of the system: "macos-26", "windows-11" on those two, and on
479
+ // Linux the distribution ("ubuntu-24.04", "arch", "omarchy") and, under WSL,
480
+ // `wsl: true`. Fixed tokens and one yes, never a name the machine was given.
481
+ addIf(facts, "osVersion", osVersionToken({ platform, release }));
482
+ addIf(facts, "distro", platform === "linux" ? shaped(distro, TOKEN_CAPS.distro) : undefined);
483
+ addIf(facts, "wsl", platform === "linux" && wsl === true ? true : undefined);
354
484
  addIf(facts, "cpus", count(cpus));
355
485
  addIf(facts, "memMb", count(memMb));
356
486
  addIf(facts, "locale", token(locale, TOKEN_CAPS.locale));
@@ -592,6 +722,8 @@ export function createReporter({
592
722
  const lastSentAt = new Map();
593
723
  let timer = null;
594
724
  let pingTimer = null;
725
+ /** The one ping a start sends ahead of the first beat (FIRST_PING_MS). */
726
+ let firstPingTimer = null;
595
727
  /** How long this run took to start, read when start() runs; null before. */
596
728
  let launchMs = null;
597
729
 
@@ -1295,8 +1427,13 @@ export function createReporter({
1295
1427
  lastSentAt.set(key, at);
1296
1428
  const stack = typeof error?.stack === "string" ? scrub(error.stack, home, root).slice(0, STACK_MAX) : undefined;
1297
1429
  // Less the runtime, and less the deviceId — an error is not one of the events
1298
- // the fingerprint rides on, so the personal field never leaves on one.
1299
- const { runtime: _runtime, deviceId: _deviceId, uiLanguage: _uiLanguage, ...fields } = factsNow();
1430
+ // the fingerprint rides on, so the personal field never leaves on one. The
1431
+ // page's language and the OS release, distribution and WSL ride on the
1432
+ // events alone, as their contract with the API says.
1433
+ const {
1434
+ runtime: _runtime, deviceId: _deviceId, uiLanguage: _uiLanguage,
1435
+ osVersion: _osVersion, distro: _distro, wsl: _wsl, ...fields
1436
+ } = factsNow();
1300
1437
  return (await call("POST", "/v1/app/errors", { installId: p.report.installId, ...fields, where, message, stack })) === "sent";
1301
1438
  }
1302
1439
 
@@ -1328,9 +1465,13 @@ export function createReporter({
1328
1465
 
1329
1466
  /** Check in once the prefs are read, and every few hours after; and beat a
1330
1467
  * heartbeat on its own, lighter timer, which also sends whatever a check-in
1331
- * still owes (beat). Both timers never hold the process open. The first
1332
- * check-in already puts a freshly launched deck online, so the first ping is
1333
- * a full interval out — nothing pings at boot. */
1468
+ * still owes (beat). Both timers never hold the process open. Ahead of the
1469
+ * first beat, one ping alone, one to two minutes after the start
1470
+ * (FIRST_PING_MS), so a restarted deck — whose check-in has nothing new to
1471
+ * send on a day already reported — is online again within two minutes. It
1472
+ * is the heartbeat's ping and nothing more: the same body, under the same
1473
+ * rules (reports on, an install id, no Retry-After running), and nothing
1474
+ * pings at the boot itself. */
1334
1475
  function start() {
1335
1476
  // start() runs as the deck starts listening (index.mjs), so this is the
1336
1477
  // launch: process start to ready. A second start() keeps the first answer.
@@ -1357,7 +1498,14 @@ export function createReporter({
1357
1498
  timer = setInterval(() => { if (retryDue()) void checkIn(); }, CHECK_IN_EVERY_MS);
1358
1499
  timer.unref?.();
1359
1500
  }
1360
- if (!pingTimer) scheduleNextPing();
1501
+ if (!pingTimer) {
1502
+ scheduleNextPing();
1503
+ firstPingTimer = setTimeout(() => {
1504
+ firstPingTimer = null;
1505
+ void ping();
1506
+ }, FIRST_PING_MS + Math.floor(Math.random() * FIRST_PING_JITTER_MS));
1507
+ firstPingTimer.unref?.();
1508
+ }
1361
1509
  }
1362
1510
 
1363
1511
  function stop() {
@@ -1365,6 +1513,8 @@ export function createReporter({
1365
1513
  timer = null;
1366
1514
  if (pingTimer) clearTimeout(pingTimer);
1367
1515
  pingTimer = null;
1516
+ if (firstPingTimer) clearTimeout(firstPingTimer);
1517
+ firstPingTimer = null;
1368
1518
  }
1369
1519
 
1370
1520
  return {
@@ -53,6 +53,10 @@ export const FEATURES = Object.freeze([
53
53
  "jira", "github", "gitlab",
54
54
  // Which CLI the day's sessions came from.
55
55
  "claude-sessions", "codex-sessions",
56
+ // Where somebody looked at the deck that day: the desktop app's window, a
57
+ // browser tab, `ccdeck tui` (feature-use.mjs). One left open across midnight
58
+ // counts for the day after too (holdFeature).
59
+ "desktop-window", "browser-tab", "tui",
56
60
  ]);
57
61
  const FEATURE_SET = new Set(FEATURES);
58
62
 
@@ -130,6 +134,9 @@ export function createUsageDay({ now = () => new Date() } = {}) {
130
134
  /** The first use this run heard, `{ at, provider }`, for activation.mjs. */
131
135
  let first = null;
132
136
  const firstListeners = [];
137
+ /** Features in use right now, for as long as they last — a page connected —
138
+ * with how many hold each: every new day starts with them used. */
139
+ const held = new Map();
133
140
 
134
141
  function fresh(day, floor = null) {
135
142
  return {
@@ -164,6 +171,9 @@ export function createUsageDay({ now = () => new Date() } = {}) {
164
171
  if (current?.day === day) return current;
165
172
  if (current && current.day < day) done = totals(current);
166
173
  current = fresh(day);
174
+ // What is still in use as the day turns was used on this day too: a window
175
+ // left open overnight is a window open today.
176
+ for (const name of held.keys()) current.features.add(name);
167
177
  changes++;
168
178
  return current;
169
179
  }
@@ -217,6 +227,29 @@ export function createUsageDay({ now = () => new Date() } = {}) {
217
227
  return true;
218
228
  }
219
229
 
230
+ /**
231
+ * A feature in use for as long as something lasts — a page connected to the
232
+ * deck — rather than at one moment: used today, and on every later day it is
233
+ * still in use when that day starts. Returns the release, to call once when
234
+ * it ends, which notes it on the day it ends as well: an end the day's first
235
+ * reading comes after would otherwise leave that day without it. A name off
236
+ * FEATURES holds nothing and its release does nothing.
237
+ */
238
+ function holdFeature(name) {
239
+ if (!FEATURE_SET.has(name)) return () => {};
240
+ noteFeature(name);
241
+ held.set(name, (held.get(name) ?? 0) + 1);
242
+ let released = false;
243
+ return () => {
244
+ if (released) return;
245
+ released = true;
246
+ noteFeature(name);
247
+ const left = (held.get(name) ?? 1) - 1;
248
+ if (left > 0) held.set(name, left);
249
+ else held.delete(name);
250
+ };
251
+ }
252
+
220
253
  /** A Codex session's working directory, which is its project. */
221
254
  function noteFolder(dir) {
222
255
  if (!dir || typeof dir !== "string") return;
@@ -308,8 +341,8 @@ export function createUsageDay({ now = () => new Date() } = {}) {
308
341
  }
309
342
 
310
343
  return {
311
- noteUse, noteProject, noteFolder, noteFeature, notePeak, firstUse, onFirstUse, finished, markSent, saved, restore, version,
312
- daysUsed,
344
+ noteUse, noteProject, noteFolder, noteFeature, holdFeature, notePeak, firstUse, onFirstUse, finished, markSent, saved,
345
+ restore, version, daysUsed,
313
346
  };
314
347
  }
315
348