@tmustier/pi-usage-extension 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.7.1] - 2026-07-17
+
+### Added
+- Descriptive loading messages with a live file counter while `/usage` opens: “Building your usage history for the first time…” on a fresh install, “Rebuilding your usage history — the cache format changed…” after an upgrade that bumps the cache version, and “Updating your usage history since \<date>…” for routine incremental refreshes. Warm opens with nothing to parse keep the plain spinner.
+- `collectUsageData` accepts an `onProgress` callback reporting mode (`first-run` / `rebuild` / `update`), files to parse, files parsed, and the newest already-ingested session activity timestamp.
+
 ## [0.7.0] - 2026-07-17
 
 ### Changed

package/README.md

@@ -159,7 +159,7 @@ On narrow terminals, `/usage` automatically switches to a compact table instead
 - **On-disk cache.** Per-file extraction results are cached in `<agentDir>/usage-extension-cache.json` (respects `PI_CODING_AGENT_DIR`), keyed by file size + mtime. Warm opens only re-parse session files that changed since the last run — on a 5.2 GB / 3,310-file corpus that takes the open from ~17 s to ~0.3 s.
 - **First open** after install (or after deleting the cache) does a one-off full build, showing the usual cancellable loader. Cancelling saves partial progress, so the next open resumes where it left off.
 - The cache is safe to delete at any time; it is rebuilt automatically. Corrupt or version-mismatched caches are ignored and rebuilt rather than trusted.
-- **0.7.0 bumps the cache format to v3** (adds session working directory and compaction markers; 0.6.0's v2 added thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild, then warm opens are fast again.
+- **0.7.0 bumps the cache format to v3** (adds session working directory and compaction markers; 0.6.0's v2 added thinking level and reasoning tokens). The first open after upgrading does a one-off full rebuild (with a progress message and live file counter), then warm opens are fast again.
 
 ## Provider Notes
 

package/data.ts

@@ -619,6 +619,7 @@ function getPeriodsForTimestamp(
 }
 
 const DAY_MS = 24 * HOUR_MS;
+const PROGRESS_REPORT_EVERY = 100;
 
 function addMessagesToUsageData(
 	data: UsageData,
@@ -727,8 +728,21 @@ const STAT_CONCURRENCY = 16;
 const DEFAULT_PARSE_CONCURRENCY = 4;
 const AGGREGATE_YIELD_EVERY_FILES = 200;
 
+export interface CollectProgress {
+	/** Why this pass needs to parse files. */
+	mode: "first-run" | "rebuild" | "update";
+	/** Session files that need parsing this pass (0 = fully warm). */
+	filesToParse: number;
+	/** Files parsed so far; reported in coarse increments. */
+	filesParsed: number;
+	/** Newest session activity already ingested (ms since epoch); null when starting fresh. */
+	sinceMs: number | null;
+}
+
 export interface CollectUsageOptions {
 	signal?: AbortSignal;
+	/** Called once before parsing begins and periodically while files are parsed. */
+	onProgress?: (progress: CollectProgress) => void;
 	/** Defaults to `<agentDir>/sessions`. */
 	sessionsDir?: string;
 	/** Defaults to `<agentDir>/usage-extension-cache.json`. Pass `null` to disable the on-disk cache. */
@@ -794,6 +808,15 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 	if (signal?.aborted) return null;
 
 	// 3. Load the cache and decide which files actually need parsing.
+	let cacheFileExists = false;
+	if (cachePath) {
+		try {
+			await stat(cachePath);
+			cacheFileExists = true;
+		} catch {
+			// No cache file yet — first run.
+		}
+	}
 	const previous = cachePath ? await loadUsageCache(cachePath) : new Map<string, CachedFileState>();
 	if (signal?.aborted) return null;
 	const current = new Map<string, CachedFileState>();
@@ -818,6 +841,22 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 		}
 	}
 
+	// Progress reporting: distinguish a true first run from a format-change
+	// rebuild (cache file present but unusable) and a routine incremental update.
+	const progressMode: CollectProgress["mode"] =
+		previous.size > 0 ? "update" : cacheFileExists ? "rebuild" : "first-run";
+	let sinceMs: number | null = null;
+	if (progressMode === "update") {
+		for (const state of previous.values()) {
+			if (state.mtimeMs > (sinceMs ?? 0)) sinceMs = state.mtimeMs;
+		}
+	}
+	let filesParsed = 0;
+	const reportProgress = (): void => {
+		options.onProgress?.({ mode: progressMode, filesToParse: toParse.length, filesParsed, sinceMs });
+	};
+	reportProgress();
+
 	// 4. Parse new/changed files with bounded concurrency.
 	{
 		let next = 0;
@@ -831,11 +870,16 @@ export async function collectUsageData(options: CollectUsageOptions = {}): Promi
 					try {
 						buffer = await readFile(filePath);
 					} catch {
+						filesParsed++;
 						continue; // File vanished — skip it.
 					}
 					const parsed = await parseSessionBuffer(buffer, signal);
 					if (signal?.aborted) return; // Never cache a partial parse.
 					current.set(filePath, { size: st.size, mtimeMs: st.mtimeMs, parsed });
+					filesParsed++;
+					if (filesParsed % PROGRESS_REPORT_EVERY === 0 || filesParsed === toParse.length) {
+						reportProgress();
+					}
 				}
 			})
 		);

package/index.ts

@@ -14,6 +14,7 @@ import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import { CancellableLoader, Container, Spacer, matchesKey, visibleWidth, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
 
 import { collectUsageData, TAB_ORDER } from "./data";
+import type { CollectProgress } from "./data";
 import type { BaseStats, TabName, UsageData } from "./data";
 import {
 	buildGraphModel,
@@ -175,6 +176,18 @@ function seriesColor(index: number): string {
 	return SERIES_COLORS[index % SERIES_COLORS.length]!;
 }
 
+/** "14:32" if the timestamp is today, otherwise "16 Jul" (with year if not this year). */
+function formatSinceDate(ms: number): string {
+	const d = new Date(ms);
+	const now = new Date();
+	if (d.toDateString() === now.toDateString()) {
+		return d.toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+	}
+	const opts: Intl.DateTimeFormatOptions = { day: "numeric", month: "short" };
+	if (d.getFullYear() !== now.getFullYear()) opts.year = "numeric";
+	return d.toLocaleDateString(undefined, opts);
+}
+
 function padLeft(s: string, len: number): string {
 	const vis = visibleWidth(s);
 	if (vis >= len) return s;
@@ -722,7 +735,20 @@ export default function (pi: ExtensionAPI) {
 
 				loader.onAbort = () => finish(null);
 
-				collectUsageData({ signal: loader.signal })
+				const onProgress = (p: CollectProgress): void => {
+					if (finished || p.filesToParse === 0) return;
+					const files = `${p.filesParsed.toLocaleString()}/${p.filesToParse.toLocaleString()} files`;
+					if (p.mode === "update") {
+						const since = p.sinceMs !== null ? ` since ${formatSinceDate(p.sinceMs)}` : "";
+						loader.setMessage(`Updating your usage history${since}… (${files})`);
+					} else if (p.mode === "rebuild") {
+						loader.setMessage(`Rebuilding your usage history — the cache format changed… (${files})`);
+					} else {
+						loader.setMessage(`Building your usage history for the first time… (${files})`);
+					}
+				};
+
+				collectUsageData({ signal: loader.signal, onProgress })
 					.then(finish)
 					.catch(() => finish(null));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmustier/pi-usage-extension",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Usage statistics dashboard for Pi sessions.",
   "license": "MIT",
   "author": "Thomas Mustier",