tledger 0.1.3 → 0.2.0

package/README.md

@@ -1,103 +1,157 @@
 # Token Ledger
 
-Token Ledger is a lightweight, local-only terminal dashboard for Codex token
-usage. It ranks projects, shows model and cache mix, and adds reset-cycle
-context without sending usage data anywhere. Codex Auto Review is shown
-separately with its token total, distinct-turn share, and cached-input share.
+Token Ledger is a small, local-only terminal dashboard for Codex usage. It
+shows ranked project bars, model mix, usage type, cache coverage, and reset
+cycle context without sending your data anywhere.
 
-Token Ledger reads Codex history stored on the computer where it runs. It does
-not sign in, fetch account-wide usage, or combine activity from other machines.
+## Install
 
-![Token Ledger running with synthetic demo data](https://raw.githubusercontent.com/jskoiz/token-ledger/main/docs/token-ledger-demo.svg)
+Requires Node.js 22.13 or newer.
 
-_The screenshot is generated from an intentionally synthetic fixture._
+Once published, install the CLI with:
 
-## Requirements
+```bash
+npm install -g tledger
+```
 
-Token Ledger requires Node.js 22.13 or newer and npm. Install a supported LTS
-release from [nodejs.org](https://nodejs.org/en/download) if either command is
-missing, then confirm the versions in a new terminal:
+For a one-time run without a permanent global install:
 
 ```bash
-node --version
-npm --version
+npx tledger week
 ```
 
-## Install
-
-Token Ledger has no runtime npm dependencies and runs no installation script.
+Until the package is published, install it from this repository:
 
 ```bash
-npm install --global tledger
-tledger --help
+git clone <repository-url>
+cd token-ledger
+npm install -g .
 ```
 
-## Use
+The package uses a small runtime image encoder for PNG report output, Node's
+built-in SQLite support, and reads Codex data directly from the local machine.
+
+## Run
+
+The shortest useful command is:
 
 ```bash
-tledger                 # current seven-day window
-tledger week            # same default, stated explicitly
-tledger day             # today
-tledger day yesterday
-tledger week 2026-08-05
+tledger week
 ```
 
-The local timezone and top 10 projects are selected automatically. The default
-view is interactive in a terminal; use arrow keys or `j`/`k` to move and `q` or
-Escape to exit. If the selected period is empty, Token Ledger reports the most
-recent local activity date and prints the exact command for opening it.
+It defaults to today's seven-day window, the computer's local timezone, the
+top 10 projects, and the local Codex data directory. The default terminal view
+is interactive; press `q` or `esc` to exit.
 
-Useful options:
+Other common views:
 
-```text
---tz <zone>          Use another IANA timezone
---top <1-100>        Change the project limit
---refresh            Force a fresh local scan
---no-refresh         Use the existing cache without a freshness check
---input <file>       Read an explicit privacy-reduced snapshot
---codex-home <dir>   Read another Codex data directory
---no-archived        Skip archived sessions during collection
---raw-projects       Keep singleton project labels separate
---static             Print once instead of opening the interactive view
---plain              Print once without ANSI color
---ascii              Use ASCII bars
---width <40-200>     Set the static layout width
---date <day>         Set today, yesterday, or YYYY-MM-DD
---help               Show complete CLI help
+```bash
+tledger day 2026-08-05
+tledger week --top 5
+tledger week --static
+tledger trend 7d --static
+tledger trend 7d --image --image-output artifacts/token-ledger-trend-7d.png
+tledger report 7d
 ```
 
-## Update or uninstall
+`tledger report [7d|14d|30d]` is the one-step report output: it writes the
+dashboard PNG (identical to `trend --image`) to
+`token-ledger-report-<period>.png` in the current directory. It accepts the
+same flags as the trend view (`--drain`, `--date`, `--tz`, `--image-output`,
+`--image-width`) and prints progress while rendering and encoding the image.
+
+The terminal trend view is a compact approximation of the image view. For the
+full chart grammar, use `--image`: it writes a PNG with two aligned panels
+sharing one time axis — the observed weekly meter as a line on its own 0–100%
+panel on top, and calendar-day columns of local token volume stacked by model
+below, each annotated with the observed drop ("−18.1%" means the meter fell
+18.1 points across that column's days). The drain numbers come straight from
+the meter — no pricing model involved — so token volume and actual limit
+consumption can be compared per day at a glance.
+
+Turns run in fast mode (service tier "priority") are drawn as a darker shade
+at the top of their model's segment, with each model's fast share in the
+legend; fast-mode turns are weighted 1.5× in the credit estimate because they
+debit the plan limit at a higher rate.
+
+Pass `--drain` to flip the columns into limit-drain units instead: each column
+becomes the weekly limit percentage the meter dropped, stacked by model using
+rate-card credit weights (an estimate — the official card is the best
+available proxy for per-model debit, but subscription limits are not billed
+per token), on the same percent scale as the meter line.
+
+Meter windows are keyed by their server-reported reset timestamp, so a fresh
+window that starts days early (a provider-initiated limit restart) is drawn as
+its own cycle and labeled `restart`, while a true weekly expiry is labeled
+`reset`.
+Stale readings from sessions still reporting a superseded window are dropped
+instead of being fused into the line as phantom drain. Drops observed after a
+sparse meter gap (over 36 hours) are spread across the covered days and marked
+with `≈`. When a range has no usable meter drain, columns fall back to raw
+local token counts and the chart says so.
+
+`--image` defaults to `token-ledger-trend-7d.png` in the current directory.
+Use `--image-output <file.png>` to choose the path and `--image-width <px>` to
+choose a width from 900 to 2400 pixels.
+
+Use `trend 14d` for daily columns across two weeks. At 30 days, the terminal
+uses readable multi-day bins: three-day bins at ordinary widths and two-day
+bins on wider terminals. The image view uses the same readable multi-day
+binning at 30 days. The image also reports the separate local rate-card credit
+estimate when token breakdowns are available; that estimate is an absolute
+credit count and never rescales the observed-drain columns.
+
+The CLI automatically checks the local Codex source files before rendering. If
+they are newer than the local cache, it rebuilds the privacy-reduced snapshot.
+The first refresh may scan historical rollout files; later runs use the cache
+for one hour before checking source freshness again. Use `--refresh` when you
+need to force an immediate rebuild.
+
+Useful overrides:
 
 ```bash
-npm install --global tledger@latest
-npm uninstall --global tledger
+# Use another timezone instead of the computer's local timezone
+tledger week --tz America/New_York
+
+# Force a complete local refresh
+tledger week --refresh
+
+# Skip the freshness check and use the existing cache
+tledger week --no-refresh
+
+# Read a specific privacy-reduced snapshot
+tledger week --input /path/to/token-ledger-snapshot.json
 ```
 
-Uninstalling the npm package leaves the privacy-reduced cache at
-`~/.token-ledger/token-ledger-snapshot.json`. Remove that directory separately
-only when you also want the next installation to perform a completely fresh
-scan.
+`--static` prints once for pipes, logs, or terminals without interactive input.
+`--plain` or `NO_COLOR=1` disables ANSI color. `--youplot` is an optional
+legacy renderer and is not required for the default dashboard.
 
 ## Local data and privacy
 
-By default, Token Ledger reads `CODEX_HOME` or `~/.codex` and keeps a
-privacy-reduced cache at `~/.token-ledger/token-ledger-snapshot.json`. It checks
-source freshness automatically. Fresh scans use a bounded pool of up to four
-workers; unchanged runs read the existing cache. Token Ledger makes no network
-requests and excludes
-message bodies, reasoning text, tool payloads, credentials, and full local
-paths from the cache. Project labels can still reveal local context, so keep
-snapshots private unless you have reviewed them. Reset-cycle burn
-is an estimate, not official quota or billing data.
+The CLI reads from `CODEX_HOME` when set, otherwise `~/.codex`. It uses local
+Codex rollout JSONL files, the session index, and local state metadata. It
+writes its privacy-reduced cache to:
+
+```text
+~/.token-ledger/token-ledger-snapshot.json
+```
+
+The collector does not export message bodies, reasoning text, tool arguments or
+results, credentials, file contents, or full local paths. Display titles may
+contain user-written text. The CLI makes no network requests.
 
-## Develop
+## Keyboard controls
+
+In the interactive dashboard:
+
+- `↑` / `↓` or `j` / `k` moves between projects.
+- `q` or `esc` exits.
+
+## Verify from source
 
 ```bash
 npm test
-npm run demo
+npm run lint
 npm pack --dry-run
 ```
-
-## License
-
-[MIT](LICENSE)

package/bin/token-ledger-rates.mjs

@@ -0,0 +1,62 @@
+// Pricing weights are used only for the separate attribution lens. They are
+// never used to scale or relabel the actual-token columns.
+export const RATE_CARD_AS_OF = "2026-08-17";
+
+// Fast mode (service tier "priority") debits the plan limit at a higher rate.
+export const FAST_MODE_MULTIPLIER = 1.5;
+
+export const RATE_CARD = {
+  "gpt-5.6-sol": { input: 125, cached: 12.5, output: 750 },
+  "gpt-5.6-terra": { input: 50, cached: 5, output: 300 },
+  "gpt-5.6-luna": { input: 5, cached: 0.5, output: 30 },
+  "gpt-5.5": { input: 125, cached: 12.5, output: 750 },
+  "gpt-5.5-cyber": { input: 500, cached: 50, output: 3_000 },
+  "gpt-5.4": { input: 62.5, cached: 6.25, output: 375 },
+  "gpt-5.4-mini": { input: 18.75, cached: 1.875, output: 113 },
+  "gpt-5.3-codex": { input: 43.75, cached: 4.375, output: 350 },
+  "gpt-5.2": { input: 43.75, cached: 4.375, output: 350 },
+};
+
+export function normalizeModel(model) {
+  const value = String(model || "unknown")
+    .trim()
+    .toLowerCase()
+    .replaceAll("_", "-");
+  if (RATE_CARD[value]) return value;
+  if (value.startsWith("gpt-5.6-sol")) return "gpt-5.6-sol";
+  if (value.startsWith("gpt-5.6-terra")) return "gpt-5.6-terra";
+  if (value.startsWith("gpt-5.6-luna")) return "gpt-5.6-luna";
+  if (value.startsWith("gpt-5.5-cyber")) return "gpt-5.5-cyber";
+  if (value.startsWith("gpt-5.5")) return "gpt-5.5";
+  if (value.startsWith("gpt-5.4-mini")) return "gpt-5.4-mini";
+  if (value.startsWith("gpt-5.4")) return "gpt-5.4";
+  if (value.startsWith("gpt-5.3-codex")) return "gpt-5.3-codex";
+  if (value.startsWith("gpt-5.2")) return "gpt-5.2";
+  return value || "unknown";
+}
+
+function hasDetailedBreakdown(usage) {
+  const totalTokens = Number(usage.totalTokens) || 0;
+  const inputTokens = Number(usage.inputTokens) || 0;
+  const outputTokens = Number(usage.outputTokens) || 0;
+  if (totalTokens === 0) return true;
+  return (
+    inputTokens + outputTokens === totalTokens &&
+    (inputTokens > 0 || outputTokens > 0)
+  );
+}
+
+export function creditsForUsage(model, usage) {
+  if (!hasDetailedBreakdown(usage)) return null;
+  const rate = RATE_CARD[normalizeModel(model)];
+  if (!rate) return null;
+  const inputTokens = Math.max(0, Number(usage.inputTokens) || 0);
+  const cachedInputTokens = Math.max(0, Number(usage.cachedInputTokens) || 0);
+  const outputTokens = Math.max(0, Number(usage.outputTokens) || 0);
+  const cached = Math.min(inputTokens, cachedInputTokens);
+  const uncached = Math.max(0, inputTokens - cached);
+  return (
+    (uncached * rate.input + cached * rate.cached + outputTokens * rate.output) /
+    1_000_000
+  );
+}