@oh-my-pi-zen/omp-stats 16.3.6-zen.1

package/src/embedded-client.ts

@@ -0,0 +1,26 @@
+/**
+ * Embedded stats dashboard archive handling.
+ *
+ * `embedded-client.generated.txt` holds the base64 of a gzipped tar of the
+ * built dashboard (`dist/client`). It is populated by
+ * `gen:stats` for compiled binaries and the
+ * prepacked npm bundle, and reset to an empty file afterwards so the dev tree
+ * keeps building the dashboard from source.
+ */
+
+/**
+ * Decode the generated archive text.
+ *
+ * Returns `null` when the content is blank or not a raw gzip archive encoded as
+ * base64 — notably the legacy placeholder that contained a TypeScript
+ * `export const … = "";` stub, which must be treated as "no archive embedded"
+ * rather than decoded into garbage bytes.
+ */
+export function decodeEmbeddedClientArchive(txt: string): Buffer | null {
+	const normalized = txt.replaceAll(/\s+/g, "");
+	if (!normalized) return null;
+	if (!/^[A-Za-z0-9+/]+={0,2}$/.test(normalized)) return null;
+	const archiveBytes = Buffer.from(normalized, "base64");
+	if (archiveBytes[0] !== 0x1f || archiveBytes[1] !== 0x8b) return null;
+	return archiveBytes;
+}

package/src/gain-aggregator.ts

@@ -0,0 +1,281 @@
+/**
+ * Aggregates token-savings data for the Gain dashboard.
+ *
+ * Source:
+ *   1. Snapcompact: colocated with stats.db as snapcompact-savings.jsonl
+ *
+ * Missing files are treated as zero records — never an error.
+ */
+
+import * as path from "node:path";
+import { getStatsDbPath, isEnoent, logger } from "@oh-my-pi-zen/pi-utils";
+import { getTimeRangeConfig } from "./aggregator";
+import { initDb } from "./db";
+import type { GainDashboardStats, GainSourceTotals, GainTimeSeriesPoint } from "./shared-types";
+
+const BYTES_PER_TOKEN_ESTIMATE = 4;
+const SQLITE_VARIABLE_CHUNK_SIZE = 500;
+
+// Paths that carry no dashboard signal — temp/internal locations.
+const TEMP_PATH_RE = /(?:^|\/)(?:T|tmp|pi-bash-exec|omp-bash-exec|pi-bash-detach)(?:\/|$)|^\/var\/folders(?:\/|$)/;
+
+// ---------------------------------------------------------------------------
+// Project-match helper
+// ---------------------------------------------------------------------------
+
+function canonicalProjectPath(p: string): string {
+	const normalized = p.replaceAll("\\", "/").replace(/\/+$/u, "");
+	return normalized || "/";
+}
+
+/** True when `candidate` exactly equals `parent` or is a separator-bounded sub-path. */
+function isSameOrSubPath(candidate: string, parent: string): boolean {
+	const normalizedCandidate = canonicalProjectPath(candidate);
+	const normalizedParent = canonicalProjectPath(parent);
+	return normalizedCandidate === normalizedParent || normalizedCandidate.startsWith(`${normalizedParent}/`);
+}
+
+/**
+ * True when `cwd` (or its normalized project root) exactly equals `project`
+ * or is a direct sub-path of it.
+ *
+ * Normalization is applied so that a cwd of `/repo/.worktrees/lane/src`
+ * matches a project root of `/repo` — the selector shows normalized roots, so
+ * the filter must compare apples-to-apples.
+ */
+function matchesProject(cwd: string | undefined, project: string): boolean {
+	if (!cwd) return false;
+	const normalizedCwd = normalizeProjectPath(cwd) ?? canonicalProjectPath(cwd);
+	const normalizedProject = normalizeProjectPath(project) ?? canonicalProjectPath(project);
+	return isSameOrSubPath(normalizedCwd, normalizedProject) || isSameOrSubPath(cwd, normalizedProject);
+}
+
+// ---------------------------------------------------------------------------
+// Project normalization & deduplication
+// ---------------------------------------------------------------------------
+
+/**
+ * Collapse conventional worktree sub-paths to their logical project root.
+ *
+ * Rules are generic: omp internal wt paths are dropped; conventional worktree
+ * suffixes (`.wt/`, `-wt/`, `.worktrees/`, `-worktrees/`) are stripped. No
+ * author-specific IDE or tool paths are baked in.
+ *
+ * Returns null to drop temp/internal paths entirely.
+ */
+export function normalizeProjectPath(p: string): string | null {
+	const clean = canonicalProjectPath(p);
+	if (TEMP_PATH_RE.test(clean)) return null;
+	if (/\/\.omp\/wt\//u.test(clean)) return null;
+
+	const worktreePatterns = [
+		/^(.+)\/\.wt\/[^/]+(?:\/.*)?$/u,
+		/^(.+)\/\.worktrees\/[^/]+(?:\/.*)?$/u,
+		/^(.+)-wt\/[^/]+(?:\/.*)?$/u,
+		/^(.+)-worktrees\/[^/]+(?:\/.*)?$/u,
+		/^(.+)\.wt\/[^/]+(?:\/.*)?$/u,
+	];
+	for (const pattern of worktreePatterns) {
+		const match = clean.match(pattern);
+		if (match?.[1]) return canonicalProjectPath(match[1]);
+	}
+
+	return clean;
+}
+
+/**
+ * Given a raw set of paths, normalize worktree paths and remove sub-paths
+ * that are already covered by a shorter parent at depth ≥ 4.
+ * Returns a sorted, deduped list of meaningful project roots.
+ */
+export function dedupeProjects(rawPaths: Set<string>): string[] {
+	const normalized = new Set<string>();
+	for (const p of rawPaths) {
+		const n = normalizeProjectPath(p);
+		if (n) normalized.add(n);
+	}
+	const sorted = Array.from(normalized).sort();
+	return sorted.filter(p => {
+		return !sorted.some(
+			other =>
+				other !== p &&
+				other.length < p.length &&
+				isSameOrSubPath(p, other) &&
+				other.split("/").filter(Boolean).length >= 4,
+		);
+	});
+}
+
+// ---------------------------------------------------------------------------
+// Snapcompact record schema
+// ---------------------------------------------------------------------------
+
+interface SnapcompactRecord {
+	ts: number; // epoch ms
+	session: string;
+	provider: string;
+	model: string;
+	toolCallId: string;
+	savedTokens: number;
+}
+
+interface SnapcompactSets {
+	records: SnapcompactRecord[];
+	projects: Set<string>;
+}
+
+async function readProjectsBySession(sessions: readonly string[]): Promise<Map<string, Set<string>>> {
+	const uniqueSessions = Array.from(new Set(sessions.filter(Boolean)));
+	const projectsBySession = new Map<string, Set<string>>();
+	if (uniqueSessions.length === 0) return projectsBySession;
+
+	const database = await initDb();
+	for (let i = 0; i < uniqueSessions.length; i += SQLITE_VARIABLE_CHUNK_SIZE) {
+		const chunk = uniqueSessions.slice(i, i + SQLITE_VARIABLE_CHUNK_SIZE);
+		const placeholders = chunk.map(() => "?").join(",");
+		const rows = database
+			.prepare(`SELECT DISTINCT session_file, folder FROM messages WHERE session_file IN (${placeholders})`)
+			.all(...chunk) as Array<{ session_file: string; folder: string }>;
+		for (const row of rows) {
+			if (!row.folder) continue;
+			let projects = projectsBySession.get(row.session_file);
+			if (!projects) {
+				projects = new Set<string>();
+				projectsBySession.set(row.session_file, projects);
+			}
+			projects.add(row.folder);
+		}
+	}
+	return projectsBySession;
+}
+
+async function readSnapcompactRecords(cutoff: number | null, project: string | null): Promise<SnapcompactSets> {
+	const filePath = path.join(path.dirname(getStatsDbPath()), "snapcompact-savings.jsonl");
+	let text: string;
+	try {
+		text = await Bun.file(filePath).text();
+	} catch (err) {
+		if (isEnoent(err)) return { records: [], projects: new Set() };
+		logger.debug("gain-aggregator: failed to read snapcompact-savings.jsonl", { err: String(err) });
+		return { records: [], projects: new Set() };
+	}
+
+	const seen = new Set<string>();
+	const parsed: SnapcompactRecord[] = [];
+	for (const line of text.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const rec = JSON.parse(line) as SnapcompactRecord;
+			if (cutoff !== null && rec.ts < cutoff) continue;
+			const key = `${rec.session}:${rec.toolCallId}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			parsed.push(rec);
+		} catch {
+			/* skip malformed line */
+		}
+	}
+
+	const projectsBySession = await readProjectsBySession(parsed.map(rec => rec.session));
+	const projects = new Set<string>();
+	const records: SnapcompactRecord[] = [];
+	for (const rec of parsed) {
+		const sessionProjects = projectsBySession.get(rec.session);
+		if (sessionProjects) {
+			for (const sessionProject of sessionProjects) projects.add(sessionProject);
+		}
+		if (project !== null) {
+			if (
+				!sessionProjects ||
+				!Array.from(sessionProjects).some(sessionProject => matchesProject(sessionProject, project))
+			) {
+				continue;
+			}
+		}
+		records.push(rec);
+	}
+
+	return { records, projects };
+}
+
+// ---------------------------------------------------------------------------
+// Aggregation helpers
+// ---------------------------------------------------------------------------
+
+function emptyTotals(): GainSourceTotals {
+	return {
+		savedTokens: 0,
+		savedBytes: 0,
+		hits: 0,
+		outputBytes: 0,
+		originalBytes: 0,
+		reductionPercent: null,
+	};
+}
+
+/** ISO date string from epoch ms, bucketed to the day. */
+function toDateBucket(epochMs: number): string {
+	return new Date(epochMs).toISOString().slice(0, 10); // "YYYY-MM-DD"
+}
+
+// ---------------------------------------------------------------------------
+// Main aggregation function
+// ---------------------------------------------------------------------------
+
+export async function getGainDashboardStats(
+	range?: string | null,
+	project?: string | null,
+): Promise<GainDashboardStats> {
+	const { cutoff: effectiveCutoff } = getTimeRangeConfig(range);
+	const effectiveProject: string | null = project?.trim() || null;
+
+	const { records: snapcompactRecords, projects: snapcompactProjects } = await readSnapcompactRecords(
+		effectiveCutoff,
+		effectiveProject,
+	);
+
+	const snapcompactTotals = emptyTotals();
+	const timeMap = new Map<string, { snapcompact: number }>();
+
+	for (const rec of snapcompactRecords) {
+		snapcompactTotals.savedTokens += rec.savedTokens;
+		const approxBytes = rec.savedTokens * BYTES_PER_TOKEN_ESTIMATE;
+		snapcompactTotals.savedBytes += approxBytes;
+		snapcompactTotals.hits += 1;
+
+		const date = toDateBucket(rec.ts);
+		const bucket = timeMap.get(date) ?? { snapcompact: 0 };
+		bucket.snapcompact += rec.savedTokens;
+		timeMap.set(date, bucket);
+	}
+	// No originalBytes for snapcompact — reductionPercent stays null.
+
+	const overall: GainSourceTotals = {
+		savedTokens: snapcompactTotals.savedTokens,
+		savedBytes: snapcompactTotals.savedBytes,
+		hits: snapcompactTotals.hits,
+		outputBytes: 0,
+		originalBytes: 0,
+		reductionPercent: null,
+	};
+
+	const timeSeries: GainTimeSeriesPoint[] = Array.from(timeMap.entries())
+		.sort(([a], [b]) => a.localeCompare(b))
+		.map(([date, bucket]) => ({
+			date,
+			snapcompact: bucket.snapcompact,
+			total: bucket.snapcompact,
+		}));
+
+	const projects = dedupeProjects(snapcompactProjects);
+
+	return {
+		overall,
+		bySource: {
+			snapcompact: snapcompactTotals,
+		},
+		timeSeries,
+		project: effectiveProject,
+		projects,
+	};
+}

package/src/index.ts

@@ -0,0 +1,194 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from "node:util";
+import { formatDuration, formatNumber, formatPercent } from "@oh-my-pi-zen/pi-utils";
+import { getDashboardStats, getTotalMessageCount, syncAllSessions } from "./aggregator";
+import { closeDb } from "./db";
+import { startServer } from "./server";
+
+export {
+	getDashboardStats,
+	getToolDashboardStats,
+	getTotalMessageCount,
+	type SyncOptions,
+	type SyncProgress,
+	smokeTestSyncWorker,
+	syncAllSessions,
+} from "./aggregator";
+export { closeDb } from "./db";
+export { getGainDashboardStats } from "./gain-aggregator";
+export { startServer } from "./server";
+export type {
+	GainDashboardStats,
+	GainSource,
+	GainSourceTotals,
+	GainTimeSeriesPoint,
+} from "./shared-types";
+export type {
+	AggregatedStats,
+	DashboardStats,
+	FolderStats,
+	MessageStats,
+	ModelPerformancePoint,
+	ModelStats,
+	ModelTimeSeriesPoint,
+	TimeSeriesPoint,
+	ToolDashboardStats,
+	ToolModelStats,
+	ToolTimeSeriesPoint,
+	ToolUsageStats,
+} from "./types";
+
+/**
+ * Format cost in dollars.
+ */
+function formatCost(n: number): string {
+	if (n < 0.01) return `$${n.toFixed(4)}`;
+	if (n < 1) return `$${n.toFixed(3)}`;
+	return `$${n.toFixed(2)}`;
+}
+
+function normalizePremiumRequests(n: number): number {
+	return Math.round((n + Number.EPSILON) * 100) / 100;
+}
+
+/**
+ * Print stats summary to console.
+ */
+async function printStats(): Promise<void> {
+	const stats = await getDashboardStats();
+	const { overall, byModel, byFolder } = stats;
+
+	console.log("\n=== AI Usage Statistics ===\n");
+
+	console.log("Overall:");
+	console.log(`  Requests: ${formatNumber(overall.totalRequests)} (${formatNumber(overall.failedRequests)} errors)`);
+	console.log(`  Error Rate: ${formatPercent(overall.errorRate)}`);
+	console.log(`  Total Tokens: ${formatNumber(overall.totalInputTokens + overall.totalOutputTokens)}`);
+	console.log(`  Input Tokens: ${formatNumber(overall.totalInputTokens)}`);
+	console.log(`  Output Tokens: ${formatNumber(overall.totalOutputTokens)}`);
+	console.log(`  Cache Rate: ${formatPercent(overall.cacheRate)}`);
+	console.log(`  Total Cost: ${formatCost(overall.totalCost)}`);
+	console.log(`  Premium Requests: ${formatNumber(normalizePremiumRequests(overall.totalPremiumRequests ?? 0))}`);
+	console.log(`  Avg Duration: ${overall.avgDuration !== null ? formatDuration(overall.avgDuration) : "-"}`);
+	console.log(`  Avg TTFT: ${overall.avgTtft !== null ? formatDuration(overall.avgTtft) : "-"}`);
+	if (overall.avgTokensPerSecond !== null) {
+		console.log(`  Avg Tokens/s: ${overall.avgTokensPerSecond.toFixed(1)}`);
+	}
+
+	if (byModel.length > 0) {
+		console.log("\nBy Model:");
+		for (const m of byModel.slice(0, 10)) {
+			console.log(
+				`  ${m.model}: ${formatNumber(m.totalRequests)} reqs, ${formatCost(m.totalCost)}, ${formatPercent(m.cacheRate)} cache`,
+			);
+		}
+	}
+
+	if (byFolder.length > 0) {
+		console.log("\nBy Folder:");
+		for (const f of byFolder.slice(0, 10)) {
+			console.log(`  ${f.folder}: ${formatNumber(f.totalRequests)} reqs, ${formatCost(f.totalCost)}`);
+		}
+	}
+
+	console.log("");
+}
+
+/**
+ * Main CLI entry point.
+ */
+async function main(): Promise<void> {
+	const { values } = parseArgs({
+		options: {
+			port: { type: "string", short: "p", default: "3847" },
+			json: { type: "boolean", short: "j", default: false },
+			sync: { type: "boolean", short: "s", default: false },
+			help: { type: "boolean", short: "h", default: false },
+		},
+		allowPositionals: true,
+	});
+
+	if (values.help) {
+		console.log(`
+omp-stats - AI Usage Statistics Dashboard
+
+Usage:
+  omp-stats [options]
+
+Options:
+  -p, --port <port>  Port for the dashboard server (default: 3847)
+  -j, --json         Output stats as JSON and exit
+  -s, --sync         Sync session files and show summary
+  -h, --help         Show this help message
+
+Examples:
+  omp-stats              # Start dashboard server
+  omp-stats --json       # Print stats as JSON
+  omp-stats --port 8080  # Start on custom port
+  omp-stats --sync       # Sync and show summary
+`);
+		return;
+	}
+
+	try {
+		// Sync first
+		const tty = process.stderr.isTTY === true;
+		process.stderr.write("Syncing session files...\n");
+		let lastWidth = 0;
+		let lastRender = 0;
+		const { processed, files } = await syncAllSessions({
+			onProgress: event => {
+				if (!tty) return;
+				const now = Date.now();
+				if (event.current < event.total && now - lastRender < 33) return;
+				lastRender = now;
+				const marker = "/sessions/";
+				const idx = event.sessionFile.indexOf(marker);
+				const short = idx >= 0 ? event.sessionFile.slice(idx + marker.length) : event.sessionFile;
+				const pct = ((event.current / event.total) * 100).toFixed(0).padStart(3, " ");
+				const line = `[${event.current}/${event.total}] ${pct}%  ${short}`;
+				const columns = process.stderr.columns ?? 120;
+				const clipped = line.length > columns - 1 ? `${line.slice(0, columns - 2)}\u2026` : line;
+				process.stderr.write(`\r${clipped.padEnd(lastWidth)}`);
+				lastWidth = clipped.length;
+			},
+		});
+		if (tty && lastWidth > 0) process.stderr.write(`\r${" ".repeat(lastWidth)}\r`);
+		const total = await getTotalMessageCount();
+		console.log(`Synced ${processed} new entries from ${files} files (${total} total)\n`);
+
+		if (values.json) {
+			const stats = await getDashboardStats();
+			console.log(JSON.stringify(stats, null, 2));
+			return;
+		}
+
+		if (values.sync) {
+			await printStats();
+			return;
+		}
+
+		// Start server
+		const port = parseInt(values.port || "3847", 10);
+		const { port: actualPort } = await startServer(port);
+		console.log(`Dashboard available at: http://localhost:${actualPort}`);
+		console.log("Press Ctrl+C to stop\n");
+
+		// Keep process running
+		process.on("SIGINT", () => {
+			console.log("\nShutting down...");
+			closeDb();
+			process.exit(0);
+		});
+	} catch (error) {
+		console.error("Error:", error);
+		closeDb();
+		process.exit(1);
+	}
+}
+
+// Run if executed directly
+if (import.meta.main) {
+	main();
+}