@f5xc-salesdemos/xcsh-stats 14.0.3

package/README.md

@@ -0,0 +1,82 @@
+# @f5xc-salesdemos/xcsh-stats
+
+Local observability dashboard for AI usage statistics.
+
+## Features
+
+- **Session log parsing**: Reads JSONL session logs from `~/.xcsh/agent/sessions/`
+- **SQLite aggregation**: Efficient stats storage and querying using `bun:sqlite`
+- **Web dashboard**: Real-time metrics visualization with Chart.js
+- **Incremental sync**: Only processes new/modified log entries
+
+## Metrics Tracked
+
+| Metric | Calculation |
+|--------|-------------|
+| Tokens/s | `output_tokens / (duration / 1000)` |
+| Cache Rate | `cache_read / (input + cache_read) * 100` |
+| Error Rate | `count(stopReason=error) / total_calls * 100` |
+| Total Cost | Sum of `usage.cost.total` |
+| Avg Latency | Mean of `duration` |
+| TTFT | Mean of `ttft` (time to first token) |
+
+## Usage
+
+### Via CLI
+
+```bash
+# Start dashboard server (default: http://localhost:3847)
+xcsh stats
+
+# Custom port
+xcsh stats --port 8080
+
+# Print summary to console
+xcsh stats --summary
+
+# Output as JSON (for scripting)
+xcsh stats --json
+```
+
+### Programmatic
+
+```typescript
+import { getDashboardStats, syncAllSessions } from "@f5xc-salesdemos/xcsh-stats";
+
+// Sync session logs to database
+const { processed, files } = await syncAllSessions();
+
+// Get aggregated stats
+const stats = await getDashboardStats();
+console.log(stats.overall.totalCost);
+console.log(stats.byModel[0].avgTokensPerSecond);
+```
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /api/stats` | Overall stats with all breakdowns |
+| `GET /api/stats/models` | Per-model statistics |
+| `GET /api/stats/folders` | Per-folder/project statistics |
+| `GET /api/stats/timeseries` | Hourly time series data |
+| `GET /api/sync` | Trigger sync and return counts |
+
+## Data Storage
+
+- **Session logs**: `~/.xcsh/agent/sessions/` (JSONL files)
+- **Stats database**: `~/.xcsh/stats.db` (SQLite)
+
+## Dashboard
+
+The web dashboard provides:
+
+- Overall metrics cards (requests, cost, cache rate, error rate, duration, tokens/s)
+- Time series chart showing requests and errors over time
+- Per-model breakdown table
+- Per-folder breakdown table
+- Auto-refresh every 30 seconds
+
+## License
+
+MIT

package/build.ts

@@ -0,0 +1,84 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { compile } from "@tailwindcss/node";
+
+/**
+ * Extract Tailwind class names from source files by scanning for className attributes.
+ */
+async function extractTailwindClasses(dir: string): Promise<Set<string>> {
+	const classes = new Set<string>();
+	const classPattern = /className\s*=\s*["'`]([^"'`]+)["'`]/g;
+
+	async function scanDir(currentDir: string): Promise<void> {
+		const entries = await fs.readdir(currentDir, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = path.join(currentDir, entry.name);
+			if (entry.isDirectory()) {
+				await scanDir(fullPath);
+			} else if (entry.isFile() && /\.(tsx|ts|jsx|js)$/.test(entry.name)) {
+				const content = await Bun.file(fullPath).text();
+				const matches = content.matchAll(classPattern);
+				for (const match of matches) {
+					for (const cls of match[1].split(/\s+/)) {
+						if (cls) classes.add(cls);
+					}
+				}
+			}
+		}
+	}
+
+	await scanDir(dir);
+	return classes;
+}
+
+// Clean dist
+await fs.rm("./dist/client", { recursive: true, force: true });
+
+// Build Tailwind CSS
+console.log("Building Tailwind CSS...");
+const sourceCss = await Bun.file("./src/client/styles.css").text();
+const candidates = await extractTailwindClasses("./src/client");
+const baseDir = path.resolve("./src/client");
+
+const compiler = await compile(sourceCss, {
+	base: baseDir,
+	onDependency: () => {},
+});
+const tailwindOutput = compiler.build([...candidates]);
+await Bun.write("./dist/client/styles.css", tailwindOutput);
+
+// Build React app
+console.log("Building React app...");
+const result = await Bun.build({
+	entrypoints: ["./src/client/index.tsx"],
+	outdir: "./dist/client",
+	minify: true,
+	naming: "[dir]/[name].[ext]",
+});
+
+if (!result.success) {
+	console.error("Build failed");
+	for (const message of result.logs) {
+		console.error(message);
+	}
+	process.exit(1);
+}
+
+// Create index.html
+const indexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>AI Usage Statistics</title>
+    <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+    <div id="root"></div>
+    <script src="index.js" type="module"></script>
+</body>
+</html>`;
+
+await Bun.write("./dist/client/index.html", indexHtml);
+
+console.log("Build complete");

package/package.json

@@ -0,0 +1,89 @@
+{
+	"type": "module",
+	"name": "@f5xc-salesdemos/xcsh-stats",
+	"version": "14.0.3",
+	"description": "Local observability dashboard for pi AI usage statistics",
+	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
+	"author": "Can Boluk",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/f5xc-salesdemos/xcsh.git",
+		"directory": "packages/stats"
+	},
+	"bugs": {
+		"url": "https://github.com/f5xc-salesdemos/xcsh/issues"
+	},
+	"keywords": [
+		"ai",
+		"observability",
+		"metrics",
+		"dashboard",
+		"llm",
+		"statistics"
+	],
+	"main": "./src/index.ts",
+	"types": "./src/index.ts",
+	"bin": {
+		"xcsh-stats": "./src/index.ts"
+	},
+	"scripts": {
+		"build": "bun run build.ts",
+		"dev": "bun run src/index.ts",
+		"check": "biome check . && bun run check:types",
+		"check:types": "tsgo -p tsconfig.json --noEmit && tsgo -p tsconfig.client.json --noEmit",
+		"lint": "biome lint .",
+		"fix": "biome check --write --unsafe .",
+		"fmt": "biome format --write ."
+	},
+	"dependencies": {
+		"@f5xc-salesdemos/pi-ai": "14.0.1",
+		"@f5xc-salesdemos/pi-utils": "14.0.1",
+		"@tailwindcss/node": "^4.2",
+		"chart.js": "^4.5",
+		"date-fns": "^4.1",
+		"lucide-react": "^0.576",
+		"react": "^19.2",
+		"react-chartjs-2": "^5.3",
+		"react-dom": "^19.2"
+	},
+	"devDependencies": {
+		"@types/bun": "^1.3",
+		"@types/react": "^19.2",
+		"@types/react-dom": "^19.2",
+		"postcss": "^8.5",
+		"tailwindcss": "^4.2"
+	},
+	"engines": {
+		"bun": ">=1.3.7"
+	},
+	"files": [
+		"src",
+		"build.ts",
+		"tailwind.config.js",
+		"README.md"
+	],
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		},
+		"./*": {
+			"types": "./src/*.ts",
+			"import": "./src/*.ts"
+		},
+		"./client": {
+			"types": "./src/client/index.tsx",
+			"import": "./src/client/index.tsx"
+		},
+		"./client/*": {
+			"types": "./src/client/*.ts",
+			"import": "./src/client/*.ts"
+		},
+		"./client/components/*": {
+			"types": "./src/client/components/*.ts",
+			"import": "./src/client/components/*.ts"
+		},
+		"./*.js": "./src/*.ts"
+	}
+}

package/src/aggregator.ts

@@ -0,0 +1,129 @@
+import * as fs from "node:fs";
+import {
+	getRecentErrors as dbGetRecentErrors,
+	getRecentRequests as dbGetRecentRequests,
+	getFileOffset,
+	getMessageById,
+	getMessageCount,
+	getModelPerformanceSeries,
+	getModelTimeSeries,
+	getOverallStats,
+	getStatsByFolder,
+	getStatsByModel,
+	getTimeSeries,
+	initDb,
+	insertMessageStats,
+	setFileOffset,
+} from "./db";
+import { getSessionEntry, listAllSessionFiles, parseSessionFile } from "./parser";
+import type { DashboardStats, MessageStats, RequestDetails } from "./types";
+
+/**
+ * Sync a single session file to the database.
+ * Only processes new entries since the last sync.
+ */
+async function syncSessionFile(sessionFile: string): Promise<number> {
+	// Get file stats
+	let fileStats: fs.Stats;
+	try {
+		fileStats = await fs.promises.stat(sessionFile);
+	} catch {
+		return 0;
+	}
+
+	const lastModified = fileStats.mtimeMs;
+
+	// Check if file has changed since last sync
+	const stored = getFileOffset(sessionFile);
+	if (stored && stored.lastModified >= lastModified) {
+		return 0; // File hasn't changed
+	}
+
+	// Parse file from last offset
+	const fromOffset = stored?.offset ?? 0;
+	const { stats, newOffset } = await parseSessionFile(sessionFile, fromOffset);
+
+	if (stats.length > 0) {
+		insertMessageStats(stats);
+	}
+
+	// Update offset tracker
+	setFileOffset(sessionFile, newOffset, lastModified);
+
+	return stats.length;
+}
+
+/**
+ * Sync all session files to the database.
+ * Returns the number of new entries processed.
+ */
+export async function syncAllSessions(): Promise<{ processed: number; files: number }> {
+	await initDb();
+
+	const files = await listAllSessionFiles();
+	let totalProcessed = 0;
+	let filesProcessed = 0;
+
+	for (const file of files) {
+		const count = await syncSessionFile(file);
+		if (count > 0) {
+			totalProcessed += count;
+			filesProcessed++;
+		}
+	}
+
+	return { processed: totalProcessed, files: filesProcessed };
+}
+
+/**
+ * Get all dashboard stats.
+ */
+export async function getDashboardStats(): Promise<DashboardStats> {
+	await initDb();
+
+	return {
+		overall: getOverallStats(),
+		byModel: getStatsByModel(),
+		byFolder: getStatsByFolder(),
+		timeSeries: getTimeSeries(24),
+		modelSeries: getModelTimeSeries(14),
+		modelPerformanceSeries: getModelPerformanceSeries(14),
+	};
+}
+
+export async function getRecentRequests(limit?: number): Promise<MessageStats[]> {
+	await initDb();
+	return dbGetRecentRequests(limit);
+}
+
+export async function getRecentErrors(limit?: number): Promise<MessageStats[]> {
+	await initDb();
+	return dbGetRecentErrors(limit);
+}
+
+export async function getRequestDetails(id: number): Promise<RequestDetails | null> {
+	await initDb();
+	const msg = getMessageById(id);
+	if (!msg) return null;
+
+	const entry = await getSessionEntry(msg.sessionFile, msg.entryId);
+	if (!entry || entry.type !== "message") return null;
+
+	// TODO: Get parent/context messages?
+	// For now we return the single entry which contains the assistant response.
+	// The user prompt is likely the parent.
+
+	return {
+		...msg,
+		messages: [entry],
+		output: (entry as any).message,
+	};
+}
+
+/**
+ * Get the current message count in the database.
+ */
+export async function getTotalMessageCount(): Promise<number> {
+	await initDb();
+	return getMessageCount();
+}

package/src/client/App.tsx

@@ -0,0 +1,116 @@
+import { useCallback, useEffect, useState } from "react";
+import { getRecentErrors, getRecentRequests, getStats, sync } from "./api";
+import { ChartsContainer } from "./components/ChartsContainer";
+import { Header } from "./components/Header";
+import { ModelsTable } from "./components/ModelsTable";
+import { RequestDetail } from "./components/RequestDetail";
+import { RequestList } from "./components/RequestList";
+import { StatsGrid } from "./components/StatsGrid";
+import type { DashboardStats, MessageStats } from "./types";
+
+type Tab = "overview" | "requests" | "errors" | "models";
+
+export default function App() {
+	const [stats, setStats] = useState<DashboardStats | null>(null);
+	const [recentRequests, setRecentRequests] = useState<MessageStats[]>([]);
+	const [recentErrors, setRecentErrors] = useState<MessageStats[]>([]);
+	const [selectedRequest, setSelectedRequest] = useState<number | null>(null);
+	const [syncing, setSyncing] = useState(false);
+	const [activeTab, setActiveTab] = useState<Tab>("overview");
+
+	const loadData = useCallback(async () => {
+		try {
+			const [s, r, e] = await Promise.all([getStats(), getRecentRequests(50), getRecentErrors(50)]);
+			setStats(s);
+			setRecentRequests(r);
+			setRecentErrors(e);
+		} catch (err) {
+			console.error(err);
+		}
+	}, []);
+
+	const handleSync = async () => {
+		setSyncing(true);
+		try {
+			await sync();
+			await loadData();
+		} finally {
+			setSyncing(false);
+		}
+	};
+
+	useEffect(() => {
+		loadData();
+		const interval = setInterval(loadData, 30000);
+		return () => clearInterval(interval);
+	}, [loadData]);
+
+	if (!stats) {
+		return (
+			<div className="min-h-screen flex items-center justify-center">
+				<div className="flex items-center gap-3 text-[var(--text-muted)]">
+					<div className="w-5 h-5 border-2 border-[var(--border-default)] border-t-[var(--accent-cyan)] rounded-full spin" />
+					<span className="text-sm">Loading analytics...</span>
+				</div>
+			</div>
+		);
+	}
+
+	return (
+		<div className="min-h-screen">
+			<div className="max-w-[1600px] mx-auto px-6 py-6">
+				<Header activeTab={activeTab} onTabChange={setActiveTab} onSync={handleSync} syncing={syncing} />
+
+				{activeTab === "overview" && (
+					<div className="space-y-6 animate-fade-in">
+						<StatsGrid stats={stats.overall} />
+
+						<div className="grid lg:grid-cols-2 gap-6">
+							<RequestList
+								title="Recent Requests"
+								requests={recentRequests.slice(0, 10)}
+								onSelect={r => r.id && setSelectedRequest(r.id)}
+							/>
+							<RequestList
+								title="Recent Errors"
+								requests={recentErrors.slice(0, 10)}
+								onSelect={r => r.id && setSelectedRequest(r.id)}
+							/>
+						</div>
+					</div>
+				)}
+
+				{activeTab === "requests" && (
+					<div className="h-[calc(100vh-140px)] animate-fade-in">
+						<RequestList
+							title="All Recent Requests"
+							requests={recentRequests}
+							onSelect={r => r.id && setSelectedRequest(r.id)}
+						/>
+					</div>
+				)}
+
+				{activeTab === "errors" && (
+					<div className="h-[calc(100vh-140px)] animate-fade-in">
+						<RequestList
+							title="Failed Requests"
+							requests={recentErrors}
+							onSelect={r => r.id && setSelectedRequest(r.id)}
+						/>
+					</div>
+				)}
+
+				{activeTab === "models" && (
+					<div className="space-y-6 animate-fade-in">
+						<ChartsContainer modelSeries={stats.modelSeries} />
+						<ModelsTable models={stats.byModel} performanceSeries={stats.modelPerformanceSeries} />
+					</div>
+				)}
+
+				{selectedRequest !== null && (
+					<RequestDetail id={selectedRequest} onClose={() => setSelectedRequest(null)} />
+				)}
+			</div>
+		</div>
+	);
+}

package/src/client/api.ts

@@ -0,0 +1,33 @@
+import type { DashboardStats, MessageStats, RequestDetails } from "./types";
+
+const API_BASE = "/api";
+
+export async function getStats(): Promise<DashboardStats> {
+	const res = await fetch(`${API_BASE}/stats`);
+	if (!res.ok) throw new Error("Failed to fetch stats");
+	return res.json() as Promise<DashboardStats>;
+}
+
+export async function getRecentRequests(limit = 50): Promise<MessageStats[]> {
+	const res = await fetch(`${API_BASE}/stats/recent?limit=${limit}`);
+	if (!res.ok) throw new Error("Failed to fetch recent requests");
+	return res.json() as Promise<MessageStats[]>;
+}
+
+export async function getRecentErrors(limit = 50): Promise<MessageStats[]> {
+	const res = await fetch(`${API_BASE}/stats/errors?limit=${limit}`);
+	if (!res.ok) throw new Error("Failed to fetch recent errors");
+	return res.json() as Promise<MessageStats[]>;
+}
+
+export async function getRequestDetails(id: number): Promise<RequestDetails> {
+	const res = await fetch(`${API_BASE}/request/${id}`);
+	if (!res.ok) throw new Error("Failed to fetch request details");
+	return res.json() as Promise<RequestDetails>;
+}
+
+export async function sync(): Promise<any> {
+	const res = await fetch(`${API_BASE}/sync`);
+	if (!res.ok) throw new Error("Failed to sync");
+	return res.json();
+}