tledger 0.1.2 → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jskoiz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,17 +5,31 @@ 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 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.
+
 ![Token Ledger running with synthetic demo data](https://raw.githubusercontent.com/jskoiz/token-ledger/main/docs/token-ledger-demo.svg)
 
 _The screenshot is generated from an intentionally synthetic fixture._
 
+## Requirements
+
+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:
+
+```bash
+node --version
+npm --version
+```
+
 ## Install
 
-Token Ledger requires Node.js 22.13 or newer and has no runtime npm
-dependencies.
+Token Ledger has no runtime npm dependencies and runs no installation script.
 
 ```bash
 npm install --global tledger
+tledger --help
 ```
 
 ## Use
@@ -30,7 +44,8 @@ tledger week 2026-08-05
 
 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.
+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.
 
 Useful options:
 
@@ -51,6 +66,20 @@ Useful options:
 --help               Show complete CLI help
 ```
 
+## Update or uninstall
+
+```bash
+npm install --global tledger@latest
+npm uninstall --global tledger
+```
+
+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.
+
+## 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
@@ -68,3 +97,7 @@ npm test
 npm run demo
 npm pack --dry-run
 ```
+
+## License
+
+[MIT](LICENSE)

package/bin/token-ledger.mjs

@@ -382,6 +382,48 @@ function sourceLabel(snapshotPath, snapshot) {
   return `${cleanLabel(basename(snapshotPath), "snapshot")} · captured ${generated}`;
 }
 
+function latestActivityDateString(snapshot, timeZone) {
+  let latestTimestamp = Number.NEGATIVE_INFINITY;
+  for (const event of snapshot.events ?? []) {
+    const timestamp = new Date(event.timestamp).getTime();
+    if (Number.isFinite(timestamp) && timestamp > latestTimestamp) {
+      latestTimestamp = timestamp;
+    }
+  }
+  if (!Number.isFinite(latestTimestamp)) return null;
+  return dateStringFromParts(numericDateParts({
+    value: new Date(latestTimestamp),
+    timeZone,
+  }));
+}
+
+function displayCalendarDate(dateString) {
+  const [year, month, day] = dateString.split("-").map(Number);
+  return new Intl.DateTimeFormat("en-US", {
+    month: "long",
+    day: "numeric",
+    year: "numeric",
+    timeZone: "UTC",
+  }).format(new Date(Date.UTC(year, month - 1, day)));
+}
+
+function emptyState(options, snapshot, bounds) {
+  const rangeDescription = options.range === "week"
+    ? `${bounds.startDateString} through ${bounds.endDateString}`
+    : bounds.dateString;
+  const lines = [
+    `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
+    "Token Ledger reads only Codex history stored on this computer.",
+  ];
+  const latestDate = latestActivityDateString(snapshot, bounds.timeZone);
+  if (latestDate) {
+    lines.push(`Latest local activity: ${displayCalendarDate(latestDate)}.`);
+    lines.push(`Try: tledger ${options.range} ${latestDate}`);
+  }
+  lines.push(`Source: ${sourceLabel(options.input, snapshot)}`);
+  return lines.join("\n");
+}
+
 async function readSnapshot(snapshotPath) {
   let parsed;
   try {
@@ -489,13 +531,7 @@ export async function run(options) {
   const snapshot = await loadSnapshot(options);
   const events = filterDayEvents(snapshot, bounds);
   if (events.length === 0) {
-    const rangeDescription = options.range === "week"
-      ? `${bounds.startDateString} through ${bounds.endDateString}`
-      : bounds.dateString;
-    return [
-      `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
-      `Source: ${sourceLabel(options.input, snapshot)}`,
-    ].join("\n");
+    return emptyState(options, snapshot, bounds);
   }
   const allRows = aggregateProjects(snapshot, events, options);
   const rows = allRows.slice(0, options.top);
@@ -519,14 +555,7 @@ async function runInteractive(options) {
   const snapshot = await loadSnapshot(options);
   const events = filterDayEvents(snapshot, bounds);
   if (events.length === 0) {
-    const rangeDescription = options.range === "week"
-      ? `${bounds.startDateString} through ${bounds.endDateString}`
-      : bounds.dateString;
-    process.stdout.write([
-      `No model-call events found for ${rangeDescription} (${bounds.timeZone}).`,
-      `Source: ${sourceLabel(options.input, snapshot)}`,
-      "",
-    ].join("\n"));
+    process.stdout.write(`${emptyState(options, snapshot, bounds)}\n`);
     return;
   }
   const allRows = aggregateProjects(snapshot, events, options);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "tledger",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A local-only terminal dashboard for Codex token usage",
+  "license": "MIT",
   "keywords": [
     "codex",
     "cli",
@@ -24,6 +25,7 @@
   "files": [
     "bin/",
     "lib/",
+    "LICENSE",
     "README.md"
   ],
   "bin": {