pi-cost 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.2.0
+
+### Breaking changes
+
+- The server listens on `127.0.0.1` only. To reach it from another machine, start it with `--host 0.0.0.0 --allowed-hosts=<hostname>`.
+- The Projects tab is gone. The Overview lists the projects, and a click opens a project's sessions. `1` and `2` switch between Overview and Insights.
+
+### Features
+
+- **Date ranges.** Pick a range with the date picker or a brush on the charts. The cost-by-model charts show hourly or daily series.
+- **Insights, sessions and agents.** New pages and APIs: `/api/insights`, `/api/sessions`, and `/api/agents`.
+- **Command line.** `pi-cost overview|insights|projects|sessions|agents|session` prints the same numbers in the terminal, or as JSON with `--json`.
+- **Color themes.** 18 theme families in a theme menu, in light and dark.
+- **pi-kanban pane.** `GET /api/companion` and the embed theme handshake let the pi-kanban board show pi-cost in a pane, in the board's colors.
+- Keyboard help, loading skeletons, and fonts served locally.
+- Follows pi's directory settings: `PI_CODING_AGENT_DIR`, `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, and `sessionDir` in `settings.json`.
+- Uses the cost that pi records for each message.
+
+### Security
+
+- The server refuses requests with a non-local `Host` header and cross-site requests that change data.
+- A content security policy lets only local pages frame pi-cost.
+
+### Other
+
+- Express 5 and current dependencies.
+- A `node:test` suite for the parsers and routes.

package/README.md

@@ -1,5 +1,8 @@
 # pi-cost
 
+[![npm version](https://img.shields.io/npm/v/pi-cost.svg)](https://www.npmjs.com/package/pi-cost)
+[![npm downloads](https://img.shields.io/npm/dm/pi-cost.svg)](https://www.npmjs.com/package/pi-cost)
+
 Cost dashboard for the [pi coding agent](https://pi.dev) — overview → project → session → message, with actual and estimated spend.
 
 [![pi-cost demo](./assets/session-light.png)](https://github.com/user-attachments/assets/f9383f3f-4379-4ca6-b920-badb35f5eea8)
@@ -24,7 +27,15 @@ Or run standalone:
 npx pi-cost
 ```
 
-Open `http://localhost:5461` — `npm run dev` auto-opens the browser.
+Open `http://localhost:5461` — `npm run dev` auto-opens the browser. pi-cost reads the agent dir in `PI_CODING_AGENT_DIR` (default `~/.pi/agent`).
+
+The same numbers from the command line:
+
+```sh
+npx pi-cost overview --range 30d
+npx pi-cost sessions --match refactor --json
+npx pi-cost help
+```
 
 ### From source
 
@@ -33,6 +44,7 @@ git clone https://github.com/NikiforovAll/pi-cost
 cd pi-cost
 npm install
 npm start              # http://localhost:5461
+npm test               # node:test suite on synthetic sessions
 pi --add ./extensions  # register as a pi extension
 ```
 

package/extensions/cost.ts

@@ -1,47 +1,25 @@
 import { spawn, spawnSync, type ChildProcess } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import { createConnection } from "node:net";
-import { homedir } from "node:os";
-import { join as joinPath, resolve as resolvePath } from "node:path";
+import { resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const extDir = fileURLToPath(new URL('.', import.meta.url));
+const requireLib = createRequire(import.meta.url);
+const parsers = requireLib("../lib/pi-parsers-cost.js");
+const { readServerRecord, isAlive } = requireLib("../lib/cost-dir.js");
 
 let child: ChildProcess | null = null;
 let lastStderr = "";
-const port = 5461;
-
-const COST_DIR = joinPath(homedir(), ".pi", "agent", "cost");
-const SETTINGS_PATH = joinPath(COST_DIR, "settings.json");
-const DEFAULT_THEME_DIR = joinPath(COST_DIR, "themes");
-
-type CostSettings = {
-	themes?: { light?: string; dark?: string; dir?: string };
-};
-
-function readSettings(): CostSettings {
-	try {
-		return JSON.parse(readFileSync(SETTINGS_PATH, "utf8")) as CostSettings;
-	} catch (e: any) {
-		if (e?.code !== "ENOENT") console.warn(`pi-cost: cannot read ${SETTINGS_PATH}: ${e.message}`);
-		return {};
-	}
-}
+const PREFERRED_PORT = 5461;
 
-function buildServerEnv(): NodeJS.ProcessEnv {
-	const settings = readSettings();
-	const t = settings.themes ?? {};
-	const env: NodeJS.ProcessEnv = { ...process.env, PORT: String(port) };
-	env.COST_THEME_DIR = process.env.COST_THEME_DIR ?? t.dir ?? DEFAULT_THEME_DIR;
-	if (process.env.COST_LIGHT_THEME ?? t.light) {
-		env.COST_LIGHT_THEME = process.env.COST_LIGHT_THEME ?? t.light;
-	}
-	if (process.env.COST_DARK_THEME ?? t.dark) {
-		env.COST_DARK_THEME = process.env.COST_DARK_THEME ?? t.dark;
-	}
-	return env;
-}
+// The server follows the same agent dir as this pi (PI_CODING_AGENT_DIR, else ~/.pi/agent), so a
+// dev pi and the main pi each get their own dashboard. The server reads theme settings itself.
+const AGENT_DIR: string = parsers.getAgentDir();
+const COST_DIR: string = parsers.getCostDir();
+
+type ServerRecord = { pid: number; port: number };
 
 const SUBCOMMANDS = ["start", "stop", "restart", "status", "open"] as const;
 type Sub = (typeof SUBCOMMANDS)[number];
@@ -57,35 +35,25 @@ function probePort(p: number, timeoutMs = 250): Promise<boolean> {
 	});
 }
 
-async function waitForPort(p: number, totalMs = 5000): Promise<boolean> {
+async function runningServer(): Promise<ServerRecord | null> {
+	const rec: ServerRecord | null = readServerRecord(COST_DIR);
+	return rec && (await probePort(rec.port)) ? rec : null;
+}
+
+async function waitForServer(pid: number, totalMs = 8000): Promise<ServerRecord | null> {
 	const start = Date.now();
 	while (Date.now() - start < totalMs) {
-		if (await probePort(p)) return true;
+		const rec = await runningServer();
+		if (rec && rec.pid === pid) return rec;
 		await new Promise((r) => setTimeout(r, 150));
 	}
-	return false;
+	return null;
 }
 
 function splitArgs(args: string): string[] {
 	return args.trim().split(/\s+/).filter(Boolean);
 }
 
-function findPidsOnPort(p: number): number[] {
-	if (process.platform === "win32") {
-		const r = spawnSync("netstat", ["-ano", "-p", "tcp"], { encoding: "utf8" });
-		if (r.status !== 0) return [];
-		const pids = new Set<number>();
-		for (const line of r.stdout.split(/\r?\n/)) {
-			const m = line.match(/^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)/i);
-			if (m && Number(m[1]) === p) pids.add(Number(m[2]));
-		}
-		return [...pids];
-	}
-	const r = spawnSync("lsof", ["-tiTCP:" + p, "-sTCP:LISTEN"], { encoding: "utf8" });
-	if (r.status !== 0) return [];
-	return r.stdout.split(/\s+/).map((s) => Number(s)).filter((n) => Number.isFinite(n) && n > 0);
-}
-
 function killPid(pid: number): void {
 	if (process.platform === "win32") {
 		spawnSync("taskkill", ["/F", "/PID", String(pid)], { stdio: "ignore" });
@@ -96,18 +64,20 @@ function killPid(pid: number): void {
 
 export default function costExtension(pi: ExtensionAPI) {
 	const serverPath = resolvePath(extDir, "..", "server.js");
-	const url = `http://localhost:${port}`;
+	const urlOf = (rec: ServerRecord) => `http://localhost:${rec.port}`;
 
 	type Notify = (m: string, l?: "info" | "error") => void;
 
-	async function startServer(notify: Notify, opts: { silentSuccess?: boolean } = {}): Promise<boolean> {
-		if (await probePort(port)) {
-			notify(`pi-cost already listening on ${url} — run /cost open to launch it`);
-			return true;
+	async function startServer(notify: Notify, opts: { silentSuccess?: boolean } = {}): Promise<ServerRecord | null> {
+		const existing = await runningServer();
+		if (existing) {
+			if (!opts.silentSuccess) notify(`pi-cost already listening on ${urlOf(existing)} — run /cost open to launch it`);
+			return existing;
 		}
 		lastStderr = "";
-		child = spawn(process.execPath, [serverPath], {
-			env: buildServerEnv(),
+		// No --port: the server takes PORT, and a random port when that one is in use.
+		child = spawn(process.execPath, [serverPath, "--no-open"], {
+			env: { ...process.env, PI_CODING_AGENT_DIR: AGENT_DIR, PORT: String(PREFERRED_PORT) },
 			stdio: ["ignore", "ignore", "pipe"],
 			detached: true,
 			windowsHide: true,
@@ -115,35 +85,34 @@ export default function costExtension(pi: ExtensionAPI) {
 		child.stderr?.on("data", (b) => { lastStderr += b.toString(); });
 		child.on("exit", () => { child = null; });
 
-		if (!(await waitForPort(port))) {
+		const rec = child.pid ? await waitForServer(child.pid) : null;
+		if (!rec || !child) {
 			notify(`pi-cost failed to start.\n${lastStderr.slice(-500) || "(no stderr)"}`, "error");
-			return false;
+			return null;
 		}
 		child.stderr?.removeAllListeners("data");
 		child.stderr?.resume();
 		child.unref();
-		if (!opts.silentSuccess) notify(`pi-cost started → ${url} — run /cost open to launch it`);
-		return true;
+		if (!opts.silentSuccess) notify(`pi-cost started → ${urlOf(rec)} — run /cost open to launch it`);
+		return rec;
 	}
 
 	async function stopServer(notify: Notify, opts: { silentSuccess?: boolean } = {}): Promise<boolean> {
+		const rec = await runningServer();
 		if (child) child.kill("SIGINT");
 		child = null;
-
-		if (await probePort(port)) {
-			const pids = findPidsOnPort(port);
-			for (const pid of pids) killPid(pid);
-			await new Promise((r) => setTimeout(r, 300));
-			if (await probePort(port)) {
-				notify(`port ${port} still in use after killing pids ${pids.join(",") || "?"}`, "error");
-				return false;
-			}
-			if (!opts.silentSuccess) {
-				notify(`pi-cost stopped (killed orphan pid${pids.length > 1 ? "s" : ""} ${pids.join(",")})`);
-			}
+		if (!rec) {
+			if (!opts.silentSuccess) notify("pi-cost stopped");
 			return true;
 		}
-		if (!opts.silentSuccess) notify("pi-cost stopped");
+		await new Promise((r) => setTimeout(r, 300));
+		if (isAlive(rec.pid)) killPid(rec.pid);
+		await new Promise((r) => setTimeout(r, 300));
+		if (await probePort(rec.port)) {
+			notify(`port ${rec.port} still in use after killing pid ${rec.pid}`, "error");
+			return false;
+		}
+		if (!opts.silentSuccess) notify(`pi-cost stopped (pid ${rec.pid})`);
 		return true;
 	}
 
@@ -160,19 +129,20 @@ export default function costExtension(pi: ExtensionAPI) {
 			if (sub === "stop") { await stopServer(notify); return; }
 			if (sub === "restart") {
 				if (!(await stopServer(notify, { silentSuccess: true }))) return;
-				if (!(await startServer(notify, { silentSuccess: true }))) return;
-				notify(`pi-cost restarted → ${url}`);
+				const rec = await startServer(notify, { silentSuccess: true });
+				if (rec) notify(`pi-cost restarted → ${urlOf(rec)}`);
 				return;
 			}
 			if (sub === "status") {
-				const up = await probePort(port);
-				const owned = child ? ` (pid ${child.pid})` : " (external)";
-				notify(up ? `running on ${url}${owned}` : "not running");
+				const rec = await runningServer();
+				notify(rec ? `running on ${urlOf(rec)} (pid ${rec.pid}, agent dir ${AGENT_DIR})` : "not running");
 				return;
 			}
 			if (sub === "open") {
+				const rec = (await runningServer()) ?? (await startServer(notify, { silentSuccess: true }));
+				if (!rec) return;
 				const { default: open } = await import("open");
-				await open(url);
+				await open(urlOf(rec));
 				return;
 			}
 			notify(`Usage: /cost ${SUBCOMMANDS.join("|")}`, "error");

package/lib/app.js

@@ -0,0 +1,113 @@
+'use strict';
+
+const express = require('express');
+const path = require('node:path');
+const parsers = require('./pi-parsers-cost');
+const pricing = require('./pi-pricing');
+const costs = require('./costs');
+
+const VERSION = require('../package.json').version;
+// Served from node_modules, not a CDN: the page must work offline inside the pi-kanban board.
+const CHART_JS = path.join(path.dirname(require.resolve('chart.js')), 'chart.umd.min.js');
+
+/**
+ * @param {{net: ReturnType<import('./net-guard').createNetGuard>, themes: ReturnType<import('./themes').createThemeStore>}} deps
+ */
+function createApp({ net, themes }) {
+  const app = express();
+
+  // Before express.json() so a rejected request never buffers a body.
+  app.use(net.hostGuard);
+  app.use(net.frameGuard);
+  app.use(net.originGuard);
+  app.use(express.json());
+  app.use(express.static(path.join(__dirname, '..', 'public')));
+  app.get('/vendor/chart.umd.min.js', (_req, res) => res.sendFile(CHART_JS));
+
+  // A custom from/to wins over `range`. null is the all-time range, so malformed input is rejected
+  // here rather than passed on as a sentinel.
+  const withRange = (fallback = null) => (req, res, next) => {
+    const custom = costs.parseCustomRange(req.query);
+    if (custom === null) return res.status(400).json({ error: 'Invalid date range' });
+    req.range = custom || costs.parseRange(req.query.range, fallback);
+    next();
+  };
+
+  const withProject = (req, res, next) => {
+    const project = costs.parseProject(req.query.project);
+    if (project === null) return res.status(400).json({ error: 'Invalid project' });
+    req.project = project;
+    next();
+  };
+
+  const handle = (label, fn) => async (req, res) => {
+    try {
+      const data = await fn(req);
+      if (data == null) return res.status(404).json({ error: `${label} not found` });
+      res.json(data);
+    } catch (err) {
+      console.error(`[api] ${label}:`, err);
+      res.status(500).json({ error: `Failed to load ${label}` });
+    }
+  };
+
+  app.get('/api/themes', async (_req, res) => {
+    await themes.ready;
+    res.json({
+      light: themes.active('light'),
+      dark: themes.active('dark'),
+      families: themes.families(),
+      config: { lightId: themes.config.lightId, darkId: themes.config.darkId, themeDir: themes.config.dir },
+    });
+  });
+
+  // pi-kanban probes this before it frames the page; `session` is the deep-link template.
+  app.get('/api/companion', (_req, res) => {
+    res.json({ name: 'pi-cost', version: VERSION, session: '/?session={id}' });
+  });
+
+  app.get('/pi-config', (req, res) => {
+    res.json({
+      agentDir: parsers.getAgentDir(),
+      sessionsDir: parsers.getSessionsDir(),
+      sessionRoots: parsers.getSessionRoots(),
+      port: req.socket.localPort,
+    });
+  });
+
+  app.get('/api/overview', withRange(30), withProject, handle('overview', (req) => costs.getOverviewData(req.range, req.project)));
+  app.get('/api/insights', withRange(30), withProject, handle('insights', (req) => costs.getInsightsData(req.range, req.project)));
+  app.get('/api/projects', withRange(), handle('projects', (req) => costs.getProjectsData(req.range)));
+  app.get('/api/projects/:encoded/sessions', withRange(), handle('project sessions', (req) => costs.getProjectSessionsData(req.params.encoded, req.range)));
+  app.get('/api/sessions', withRange(), withProject, handle('sessions', (req) => costs.getAllSessionsData(req.range, req.project)));
+  app.get('/api/agents', withRange(30), withProject, handle('agents', (req) => costs.getAgentsData(req.range, req.project)));
+  app.get('/api/sessions/:id', withRange(), handle('session', async (req) => {
+    const base = await costs.getSessionDetailData(req.params.id);
+    return base && costs.withSessionSlices(base, req.range);
+  }));
+
+  app.get('/api/pricing', handle('pricing', async () => {
+    const map = await pricing.fetchPricing();
+    const models = [];
+    for (const [key, info] of map) {
+      models.push({
+        key,
+        input: info.input_cost_per_token,
+        output: info.output_cost_per_token,
+        cacheRead: info.cache_read_input_token_cost,
+        cacheWrite: info.cache_creation_input_token_cost,
+      });
+    }
+    return { models, ...pricing.getMeta() };
+  }));
+
+  app.post('/api/refresh', (_req, res) => {
+    costs.invalidateAllCache();
+    pricing.refresh();
+    res.json({ ok: true });
+  });
+
+  return app;
+}
+
+module.exports = { createApp, VERSION };

package/lib/args.js

@@ -0,0 +1,17 @@
+'use strict';
+
+// `--name value` or `--name=value`. A following flag is not taken as the value.
+function getArg(name, argv = process.argv) {
+  const idx = argv.findIndex((a) => a === `--${name}` || a.startsWith(`--${name}=`));
+  if (idx === -1) return null;
+  const arg = argv[idx];
+  if (arg.includes('=')) return arg.slice(arg.indexOf('=') + 1);
+  const next = argv[idx + 1];
+  return next !== undefined && !next.startsWith('--') ? next : null;
+}
+
+function hasFlag(name, argv = process.argv) {
+  return argv.includes(`--${name}`);
+}
+
+module.exports = { getArg, hasFlag };