codex-token-tracker 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to `codex-token-tracker`. This project follows [Semantic Versioning](https://semver.org/).
 
+## 0.2.2 — 2026-09-02
+
+Installs on machines that cannot download Electron.
+
+### Fixed
+
+- **`npm install -g` no longer runs Electron's install script.** `electron` was an optional dependency, and
+  `menubar` declared it as a hard peer dependency, so every install ran Electron's `install.js` — a ~100 MB
+  download from GitHub. When that download failed (firewalled build servers, no proxy) npm aborted the
+  **entire** install instead of skipping the optional package — Node 16's npm 8 does so outright, npm 11 does
+  the same once the script runs — and the retry died with
+  `Cannot find module …/node_modules/electron/install.js`, leaving the machine unable to install the tracker
+  even for headless use. Neither package is a dependency any more: `menubar` is bundled into `dist/main.js`,
+  and the CLI downloads the Electron runtime itself on first GUI launch into
+  `~/.codex-tracker/electron/<version>/` — the same downloader 0.1.1 added for package managers that skip
+  install scripts — honouring `ELECTRON_MIRROR` and `HTTPS_PROXY`. A globally installed `electron` is still
+  preferred when present. Headless machines never download Electron at all, and a plain install is ~40
+  packages instead of ~75.
+
+### Changed
+
+- The *Electron download failed* message now points at `ELECTRON_MIRROR` / `HTTPS_PROXY` and
+  `codex-tracker menubar` rather than `npm rebuild electron`.
+
+## 0.2.1 — 2026-09-01
+
+A manual **Sync** button that recalibrates this device's numbers on the dashboard.
+
+### Added
+
+- **Full sync.** The popover header gets a **⟳** button (also *Sync now* in the Account card and the tray
+  menu, and `codex-token-tracker sync` on the CLI). Unlike the background upload — which every 60 s pushes
+  only the hour buckets and sessions that changed — a full sync throws away every cache on the way:
+  1. re-reads the config, so agents enabled since start-up are picked up;
+  2. re-discovers every session directory and re-parses every transcript from scratch — Codex plus the
+     coding agents running on your Codex subscription (pi, OpenCode, Cline / Roo / Kilo, Hermes) and any
+     configured `extraSessionDirs` — instead of skipping files whose size and mtime are unchanged;
+  3. recomputes the aggregates with the current pricing table;
+  4. re-uploads **everything**, so the dashboard's totals for this device are replaced by the freshly
+     computed ones;
+  5. pulls the other devices' rows and the live rate limits back down.
+
+  Use it when a machine's numbers look wrong, after installing a new agent, or after an update that
+  changes the pricing table. It is manual only — never on a timer — because it re-sends the whole history.
+- A banner in the popover reports the phase while a sync runs (*Rescanning every agent's transcripts…*,
+  *Re-uploading this device's history…*) and then the result, e.g. `Synced codex, pi · 75 files ·
+  75 sessions · 70 hours re-uploaded`. Signed out, the rescan still runs and nothing leaves the machine.
+- `codex-token-tracker sync` prints the same summary and exits non-zero if the sync failed.
+
+- **Dev builds target the dev environment.** A build now carries its channel, stamped by
+  `scripts/build.mjs`: only `--release` (what `prepack` runs) produces a production build, so every
+  published tarball is prod and every local `pnpm build` / `pnpm dev` is dev. A dev build
+  - defaults to the local dashboard `http://localhost:3000` instead of `https://codex.chenli.dev`, and
+    therefore uploads to whatever Convex deployment that dashboard advertises — the dev one;
+  - keeps its config, device token and upload state in `~/.codex-tracker-dev`, so a local run can
+    never overwrite the production token or the record of what was already pushed to production;
+  - defaults `checkUpdates` to `false` and refuses `codex-token-tracker update`, which would otherwise
+    install the published package over the checkout;
+  - runs as `Codex Tracker (dev)` with its own Electron userData directory and macOS LaunchAgent, so it
+    can run **beside** an installed copy instead of fighting it for the single-instance lock;
+  - shows an orange **DEV** badge in the popover header and names its dashboard and config directory in
+    `--version`, `status` and `paths`.
+
+  `--dashboard <url>`, `config set dashboardUrl` and `CODEX_TRACKER_HOME` still override all of it.
+
+### Changed
+
+- `Uploader.pushAll()` takes a `{ full }` option that clears the pushed-buckets/pushed-sessions record
+  before building the payload, and waits for an in-flight incremental push instead of skipping the call.
+- `SessionStore.reset()` drops the parsed-file index so a following deep refresh re-reads everything.
+- Packaging scripts: `build:release` builds with the prod channel; `prepack` runs it (so `npm pack` and
+  `npm publish` always ship a prod build) and `postpack` restores the dev build in `dist/`.
+  `prepublishOnly` now only typechecks.
+- `app.setName()` moved ahead of `requestSingleInstanceLock()` — the lock is keyed on the userData
+  directory, which is derived from the name.
+
 ## 0.2.0 — 2026-09-01
 
 Pricing accuracy, an honest tokens/s number, and self-update.

package/README.md

@@ -27,9 +27,11 @@ This installs two equivalent commands on your PATH: **`codex-token-tracker`** an
 Already installed? `codex-token-tracker update` fetches the newest published version and installs it
 with whichever package manager you used (npm / pnpm / yarn / bun).
 
-> **npm 11+ / pnpm 10+ block Electron's install script by default.** That's fine: the first `codex-tracker` run downloads the Electron runtime itself (~100 MB, once). To do it during install instead: `npm install -g codex-token-tracker --allow-scripts=electron`.
+> **Electron is downloaded on first launch, not during install.** `npm install -g` never runs Electron's install script, so the install succeeds on locked-down servers and headless machines download nothing. The first `codex-tracker` run on a desktop fetches the runtime (~100 MB, once) into `~/.codex-tracker/electron/<version>/`, honouring `ELECTRON_MIRROR` (e.g. `https://npmmirror.com/mirrors/electron/`) and `HTTPS_PROXY`. A globally installed `electron` (`npm i -g electron`) is used instead when present.
 
-Node.js 20+ is required. Electron is an *optional* dependency: if its binary cannot be downloaded (locked-down servers, WSL without a desktop), the package still installs and runs in agent mode.
+Node.js 20+ is required. Electron is not an npm dependency: if the runtime cannot be downloaded (locked-down servers, WSL without a desktop), the package still installs and runs in agent mode.
+
+> **Stuck on Node 16?** Install [`codex-token-tracker-nodejs16`](https://www.npmjs.com/package/codex-token-tracker-nodejs16) instead — the same app, same features, same version number, built from these same sources for Node 16.8+. Use one or the other on a machine, not both, since they install the same commands.
 
 ## Quick start
 
@@ -61,6 +63,7 @@ The tracker discovers the Convex deployment through `<dashboard>/api/config`.
 | `codex-tracker login [--dashboard <url>]` | Device-code login |
 | `codex-tracker logout` | Forget the device token (local data stays) |
 | `codex-tracker status [--json]` | Today / 7d / 30d usage, live session, rate limits, models |
+| `codex-tracker sync` | Full sync: rescan every agent and re-upload this device's whole history |
 | `codex-tracker paths` | Detected Codex session directories |
 | `codex-tracker config get [key]` / `config set <key> <value>` | Settings (see below) |
 | `codex-tracker lang <en\|zh\|auto>` | Display language |
@@ -71,10 +74,35 @@ The tracker discovers the Convex deployment through `<dashboard>/api/config`.
 
 - Tray title shows today's tokens (`12.4k`) — `config set trayTitle tokens|cost|none`
 - Click: popover with Today, Live session (tokens/s, context window, rate limits), Activity heatmap, Models, Account
-- Right-click: Open dashboard, Sign in/out, Language, Launch at login, Refresh, Check for updates, Quit
+- Right-click: Open dashboard, Sign in/out, Language, Launch at login, Refresh, **Sync now**, Check for updates, Quit
 - A banner appears at the top of the popover when a newer version is published; **Update** installs it and the app asks you to restart
 - Launch at login uses a LaunchAgent on macOS and the registry run key on Windows
 
+## Sync
+
+The tracker uploads continuously in the background: every 60 s it sends the hour buckets and sessions
+that *changed* since the last push. **Sync** does the full version instead — use it when the dashboard's
+numbers for this machine look wrong, after you install a new agent, or after an update that changes the
+pricing table.
+
+Press the **⟳** button in the popover header (or *Sync now* in the Account card and the tray menu, or run
+`codex-tracker sync`). It:
+
+1. re-reads the config, so agents enabled since the app started are picked up;
+2. re-discovers **every** session directory and re-parses **every** transcript from scratch — Codex plus
+   the coding agents running on your Codex subscription (pi, OpenCode, Cline / Roo / Kilo, Hermes) and any
+   `extraSessionDirs` you configured — instead of skipping files whose size and mtime are unchanged;
+3. recomputes all aggregates with the current pricing table;
+4. re-uploads **everything**, not just what changed, so the dashboard's totals for this device are
+   replaced by the freshly computed ones — this is the calibration step;
+5. pulls the other devices' rows and the live rate limits back down.
+
+A banner reports the phase while it runs and then what it found (`Synced codex, pi · 75 files ·
+75 sessions · 70 hours re-uploaded`). Signed out, steps 1-3 still run and nothing leaves the machine.
+
+A full sync re-sends your whole history, so it costs more bandwidth than a normal push — it is a manual
+action, never on a timer.
+
 ## Windows and WSL2
 
 **Native Windows**: `npm i -g codex-token-tracker` in PowerShell, then `codex-tracker`. The tray app also scans every WSL distro (`\\wsl$\<distro>\home\*\.codex\sessions`) so sessions run inside WSL are counted.
@@ -199,7 +227,42 @@ CODEX_TRACKER_DEVTOOLS=1 ...                                                # op
 pnpm --filter codex-token-tracker build:icons                               # regenerate tray icons
 ```
 
-Publishing (from the repo root): `pnpm release:menubar` — `prepublishOnly` rebuilds and typechecks first.
+### Dev builds vs published builds
+
+A build knows which environment it belongs to, so a local test run can never write into production.
+`scripts/build.mjs` stamps the channel at bundle time: **only `--release` produces a prod build**, which
+is what `prepack` runs — so every tarball and every `npm publish` is prod, and every `pnpm build`,
+`pnpm dev` and watch-mode rebuild is dev.
+
+| | dev build (`pnpm build`) | published build (`npm i -g codex-token-tracker`) |
+| --- | --- | --- |
+| Dashboard default | `http://localhost:3000` | `https://codex.chenli.dev` |
+| Convex deployment | whatever the local dashboard's `/api/config` advertises — the **dev** one | production |
+| Config, device token, upload state | `~/.codex-tracker-dev` | `~/.codex-tracker` |
+| `checkUpdates` default | `false` (`update` refuses to run) | `true` |
+| App name / Electron userData | `Codex Tracker (dev)` | `Codex Tracker` |
+| macOS LaunchAgent | `dev.codex-tracker.menubar.dev` | `dev.codex-tracker.menubar` |
+| Popover | orange **DEV** badge in the header | — |
+
+Because the two differ in app name and config directory, **a dev build and an installed one can run at
+the same time**, each with its own tray icon, device token and upload state.
+
+To test against a dev environment, start the dashboard and Convex, then run the local build:
+
+```bash
+cd apps/dashboard && npx convex dev            # terminal 1
+pnpm dev                                        # terminal 2 — http://localhost:3000
+pnpm --filter codex-token-tracker build         # terminal 3
+node packages/menubar/bin/codex-tracker.js login   # → localhost:3000, no --dashboard needed
+node packages/menubar/bin/codex-tracker.js menubar
+```
+
+Both defaults are only *defaults*: `--dashboard <url>` and `config set dashboardUrl <url>` still point
+either build anywhere, and `CODEX_TRACKER_HOME` still overrides the config directory.
+
+Publishing (from the repo root): `pnpm release:menubar` — `prepublishOnly` typechecks and `prepack`
+makes the release build, so a published tarball is never accidentally a dev build. `postpack` restores
+the dev build in `dist/` afterwards, so your working copy keeps pointing at localhost.
 
 ## License
 
@@ -207,6 +270,6 @@ MIT
 
 ## Troubleshooting
 
-- **"Electron is not installed" / tray app does not start** – the Electron binary is downloaded by an install script. If your package manager skipped or cached it incompletely, run `npm rebuild electron` (or `node "$(npm root -g)/codex-token-tracker/node_modules/electron/install.js"`). With pnpm, allow the build script (`pnpm approve-builds`). The headless `codex-tracker agent` and `codex-tracker status` work without Electron.
+- **"Electron download failed" / tray app does not start** – the CLI downloads the Electron runtime on first launch from GitHub releases into `~/.codex-tracker/electron/<version>/`. Behind a firewall set `ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/` (or `HTTPS_PROXY`) and run `codex-tracker menubar` again; a half-finished download can be cleared by deleting that directory. A manually installed `npm i -g electron` is also picked up. The headless `codex-tracker agent` and `codex-tracker status` work without Electron.
 - **Nothing is tracked** – run `codex-tracker paths`; Codex must have written rollouts under `~/.codex/sessions` (or set `CODEX_HOME`). Add other locations with `codex-tracker config set extraSessionDirs '["/path/to/sessions"]'`.
 - **Uploads fail with BAD_TOKEN** – the device was revoked in the dashboard; run `codex-tracker login` again.