pi-tokenburn 0.3.0 → 0.4.0

package/README.md

@@ -10,7 +10,7 @@ Totals match the `tokenburn` CLI exactly.
 
 - **Status bar:** `🔥 1.20M ($52.79) [today]`, turns red with `OVER BUDGET` past your limit.
 - **Report chart:** `/tokenburn` shows the summary plus a vertical column chart (y-axis, budget line, current period marked, over-budget columns in red, peak/avg footer). Daily (14 days), weekly (8 weeks) or monthly (6 months).
-- **Views:** `/tokenburn day|week|month|year|all`. Status bar period: `/tokenburn status <window>` or `/tokenburn cycle`.
+- **Status line:** `/tokenburn day|week|month|year|all` (or `cycle`) changes the period shown at the bottom. Charts live under `/tokenburn chart <view>`.
 - **Window panel (optional):** Today / Week / Month / Total below the editor, with in/out tokens and cost.
 - **Budgets** per day, week and month, in tokens and/or dollars.
 - **Fast:** per-file cache keyed on mtime+size. First scan of ~400 MB of sessions takes under a second; refreshes after that take milliseconds. Refresh never blocks the agent loop.
@@ -27,22 +27,19 @@ pi install git:github.com/sorinirimies/pi-tokenburn
 
 | Command | What it does |
 |---|---|
-| `/tokenburn` · `day` · `today` | Report + **daily** chart (last 14 days) |
-| `/tokenburn week` | Report + **weekly** chart (last 8 weeks) |
-| `/tokenburn month` | Report + **monthly** chart (last 6 months) |
-| `/tokenburn year` | Report + **yearly** chart (last 5 years) |
-| `/tokenburn all` | Report + whole history (monthly columns up to 18 months, yearly beyond) |
-| `/tokenburn report <view>` · `chart <view>` | Same as above, explicit form |
-| `/tokenburn status <today\|week\|month\|year\|total>` | Set the status-bar period |
-| `/tokenburn cycle` | Rotate the status-bar period: today → week → month → year → total |
+| `/tokenburn day\|week\|month\|year\|all` | **Switch the bottom status line**: today, this week, this month, this year, or the all-time total |
+| `/tokenburn chart <view>` | Report + **chart**. Views: `day` (14 days), `week` (8 weeks), `month` (6 months), `year` (5 years), `all` (whole history; monthly columns up to 18 months, yearly beyond) |
+| `/tokenburn` | Report + daily chart (same as `/tokenburn chart day`) |
+| `/tokenburn cycle` | Rotate the status line: today → week → month → year → total |
+| `/tokenburn status <today\|week\|month\|year\|total>` | Explicit form of the first row |
 | `/tokenburn window` | Toggle the panel below the editor |
 | `/tokenburn budget <day\|week\|month> <tokens>` | Token budget, e.g. `budget day 5000000` |
 | `/tokenburn budget <day\|week\|month> $<cost>` | Dollar budget, e.g. `budget week $50` |
 | `/tokenburn cache` | Toggle counting cache read/write tokens |
 
-Tab-completion works for all of the above. Unknown input prints usage instead of failing.
+Tab-completion works for all of these. Unknown input prints usage instead of failing. `report <view>` is kept as an alias of `chart <view>`.
 
-Chart example (`/tokenburn`, with a 600M day budget):
+Chart example (`/tokenburn chart day`, with a 600M day budget):
 
 ```
 Daily tokens · last 14 days  ┄ budget 600.00M
@@ -81,14 +78,23 @@ Weeks start on Monday, in local time.
 
 Environment overrides for the session directory: `TOKENBURN_PI_SESSIONS`, `PI_CODING_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR`.
 
+## Security notes
+
+- **Local and read-only.** It reads pi's session logs and its own `tokenburn.json`. Nothing leaves your machine: no network, no telemetry, no shell commands, **zero runtime dependencies**.
+- **Never breaks pi.** Stats refreshes are fire-and-forget and swallow their own errors, so a failure here cannot interrupt a turn or a session start.
+- **Hand-edited config is sanitised.** Unknown or non-numeric budget values are dropped.
+
 ## Development
 
 ```bash
 bun install
 just check          # typecheck + tests + pack check + nushell tests (what CI runs)
-just test           # bun test only
+just test           # bun test only (with coverage)
+just coverage       # tests + a coverage table
 ```
 
+**Coverage:** every `bun test` collects coverage (`bunfig.toml`) and **fails below 95% lines / 95% functions**. CI shows the table on the run page and uploads `lcov.info`.
+
 CI scripts are [nushell](https://www.nushell.sh) (`scripts/`), the same ones locally and in GitHub / Gitea Actions.
 `just --list` shows every task.
 

package/extensions/tokenburn.ts

@@ -78,18 +78,24 @@ const DEFAULT_CONFIG: TokenBurnConfig = {
 	budgets: {},
 };
 
-function getConfigDir(): string {
-	if (process.env.PI_CODING_AGENT_DIR) return process.env.PI_CODING_AGENT_DIR;
-	if (process.env.XDG_CONFIG_HOME) return join(process.env.XDG_CONFIG_HOME, "pi", "agent");
-	return join(homedir(), ".pi", "agent");
+/** Where pi keeps its config: PI_CODING_AGENT_DIR, then $XDG_CONFIG_HOME/pi/agent, then ~/.pi/agent. */
+export function resolveAgentDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.PI_CODING_AGENT_DIR) return env.PI_CODING_AGENT_DIR;
+	if (env.XDG_CONFIG_HOME) return join(env.XDG_CONFIG_HOME, "pi", "agent");
+	return join(home, ".pi", "agent");
 }
 
-function getSessionsDir(): string {
-	if (process.env.TOKENBURN_PI_SESSIONS) return process.env.TOKENBURN_PI_SESSIONS;
-	if (process.env.PI_CODING_AGENT_SESSION_DIR) return process.env.PI_CODING_AGENT_SESSION_DIR;
-	return join(getConfigDir(), "sessions");
+/** Pi session logs: TOKENBURN_PI_SESSIONS, PI_CODING_AGENT_SESSION_DIR, then <agent dir>/sessions. */
+export function resolveSessionsDir(env: Record<string, string | undefined>, home: string): string {
+	if (env.TOKENBURN_PI_SESSIONS) return env.TOKENBURN_PI_SESSIONS;
+	if (env.PI_CODING_AGENT_SESSION_DIR) return env.PI_CODING_AGENT_SESSION_DIR;
+	return join(resolveAgentDir(env, home), "sessions");
 }
 
+const getConfigDir = () => resolveAgentDir(process.env, homedir());
+
+const getSessionsDir = () => resolveSessionsDir(process.env, homedir());
+
 export async function loadConfig(): Promise<TokenBurnConfig> {
 	try {
 		const raw = await readFile(join(getConfigDir(), "tokenburn.json"), "utf8");
@@ -102,13 +108,26 @@ export async function loadConfig(): Promise<TokenBurnConfig> {
 			statusWindow: (STATUS_WINDOWS as readonly string[]).includes(parsed.statusWindow)
 				? parsed.statusWindow
 				: DEFAULT_CONFIG.statusWindow,
-			budgets: typeof parsed.budgets === "object" && parsed.budgets !== null ? { ...parsed.budgets } : {},
+			budgets: sanitizeBudgets(parsed.budgets),
 		};
 	} catch {
 		return freshConfig();
 	}
 }
 
+const BUDGET_KEYS = ["dayTokens", "weekTokens", "monthTokens", "dayCost", "weekCost", "monthCost"] as const;
+
+/** Keep only known budget keys holding positive, finite numbers (the file is hand-editable). */
+export function sanitizeBudgets(value: unknown): TokenBurnConfig["budgets"] {
+	const out: TokenBurnConfig["budgets"] = {};
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return out;
+	for (const key of BUDGET_KEYS) {
+		const n = (value as Record<string, unknown>)[key];
+		if (typeof n === "number" && Number.isFinite(n) && n > 0) out[key] = n;
+	}
+	return out;
+}
+
 /** A config that shares no mutable state with DEFAULT_CONFIG. */
 export function freshConfig(): TokenBurnConfig {
 	return { ...DEFAULT_CONFIG, budgets: {} };
@@ -172,6 +191,16 @@ async function parseFile(file: string): Promise<Turn[]> {
 	return turns;
 }
 
+/** Cache key for a file: mtime + size. `undefined` when it cannot be stat'ed. */
+export function fileSignature(file: string): string | undefined {
+	try {
+		const st = statSync(file);
+		return `${st.mtimeMs}:${st.size}`;
+	} catch {
+		return undefined;
+	}
+}
+
 function listSessionFiles(root: string): string[] {
 	const files: string[] = [];
 	const walk = (dir: string) => {
@@ -209,13 +238,8 @@ async function loadAll(sessionsRoot: string): Promise<Turn[][]> {
 
 	const out: Turn[][] = [];
 	for (const file of files) {
-		let sig: string;
-		try {
-			const st = statSync(file);
-			sig = `${st.mtimeMs}:${st.size}`;
-		} catch {
-			continue;
-		}
+		const sig = fileSignature(file);
+		if (sig === undefined) continue; // vanished between listing and stat
 		let entry = FILE_CACHE.get(file);
 		if (!entry || entry.sig !== sig) {
 			entry = { sig, turns: await parseFile(file) };
@@ -560,7 +584,8 @@ export default function tokenBurnExtension(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, ctx) => {
 		config = await loadConfig();
-		await updateUI(ctx);
+		// A failing refresh must never break session start.
+		await updateUI(ctx).catch(() => {});
 	});
 
 	// Fire-and-forget: never block the agent loop on a stats refresh.
@@ -569,7 +594,7 @@ export default function tokenBurnExtension(pi: ExtensionAPI) {
 	});
 
 	pi.registerCommand("tokenburn", {
-		description: "TokenBurn: /tokenburn [day|week|month|year|all] chart, status <window>, cycle, window, budget, cache",
+		description: "TokenBurn: /tokenburn [day|week|month|year|all] sets the status bar; /tokenburn chart <day|week|month|year|all> shows the chart",
 		getArgumentCompletions: (prefix: string) => completions(prefix),
 		handler: async (args, ctx) => {
 			const cmd = parseCommand(args);
@@ -655,7 +680,7 @@ export default function tokenBurnExtension(pi: ExtensionAPI) {
 							rule,
 							...chart,
 							rule,
-							"/tokenburn day|week|month|year|all · status <window> · cycle · window · budget · cache",
+							"/tokenburn chart <day|week|month|year|all> · /tokenburn <day|week|month|year|all> sets the status bar · cycle · window · budget · cache",
 						].join("\n"),
 						"info",
 					);
@@ -684,24 +709,37 @@ export type Command =
 	| { kind: "invalid"; message: string };
 
 export const USAGE =
-	"Usage: /tokenburn [day|week|month|year|all] · status <today|week|month|year|total> · cycle · window · budget <day|week|month> <tokens|$cost> · cache";
+	"Usage: /tokenburn [day|week|month|year|all] (status-bar period) · chart [day|week|month|year|all] · status <today|week|month|year|total> · cycle · window · budget <day|week|month> <tokens|$cost> · cache";
+
+/** Words that pick the status-bar period: `day` shows today, `all` shows the all-time total. */
+const WORD_TO_WINDOW: Record<string, Window> = {
+	day: "today",
+	today: "today",
+	week: "week",
+	month: "month",
+	year: "year",
+	all: "total",
+	total: "total",
+};
 
+/** Views the chart can show. */
 const asView = (w: string | undefined): ReportView | undefined =>
-	w === "today" ? "day" : (REPORT_VIEWS as readonly string[]).includes(w ?? "") ? (w as ReportView) : undefined;
+	w === "today" ? "day" : w === "total" ? "all" : (REPORT_VIEWS as readonly string[]).includes(w ?? "") ? (w as ReportView) : undefined;
 
 export function parseCommand(args: string | undefined): Command {
 	const [cmd, p1, p2] = (args ?? "").trim().toLowerCase().split(/\s+/).filter(Boolean);
 	if (!cmd) return { kind: "report", view: "day" };
 
-	const view = asView(cmd);
-	if (view) return { kind: "report", view };
+	// /tokenburn day|week|month|year|all → what the bottom status line shows
+	const window = WORD_TO_WINDOW[cmd];
+	if (window) return { kind: "status", window };
 
 	switch (cmd) {
-		case "report":
-		case "chart": {
+		case "chart":
+		case "report": {
 			if (p1 === undefined) return { kind: "report", view: "day" };
 			const v = asView(p1);
-			return v ? { kind: "report", view: v } : { kind: "invalid", message: `Unknown view "${p1}". ${USAGE}` };
+			return v ? { kind: "report", view: v } : { kind: "invalid", message: `Unknown chart "${p1}". ${USAGE}` };
 		}
 		case "status":
 			return (STATUS_WINDOWS as readonly string[]).includes(p1 ?? "")
@@ -734,13 +772,22 @@ export interface CompletionItem {
 	description?: string;
 }
 
+const CHART_SPAN: Record<ReportView, string> = {
+	day: "last 14 days",
+	week: "last 8 weeks",
+	month: "last 6 months",
+	year: "last 5 years",
+	all: "whole history",
+};
+
 const TOP_LEVEL: CompletionItem[] = [
-	{ value: "day", label: "day", description: "Report + daily chart (last 14 days)" },
-	{ value: "week", label: "week", description: "Report + weekly chart (last 8 weeks)" },
-	{ value: "month", label: "month", description: "Report + monthly chart (last 6 months)" },
-	{ value: "year", label: "year", description: "Report + yearly chart (last 5 years)" },
-	{ value: "all", label: "all", description: "Report + whole history" },
-	{ value: "status ", label: "status", description: "Set the status-bar period" },
+	{ value: "day", label: "day", description: "Status bar: today" },
+	{ value: "week", label: "week", description: "Status bar: this week" },
+	{ value: "month", label: "month", description: "Status bar: this month" },
+	{ value: "year", label: "year", description: "Status bar: this year" },
+	{ value: "all", label: "all", description: "Status bar: all-time total" },
+	{ value: "chart ", label: "chart", description: "Report + chart: day, week, month, year or all" },
+	{ value: "status ", label: "status", description: "Set the status-bar period explicitly" },
 	{ value: "cycle", label: "cycle", description: "Rotate the status-bar period" },
 	{ value: "window", label: "window", description: "Toggle the panel below the editor" },
 	{ value: "budget ", label: "budget", description: "Set a day/week/month budget" },
@@ -750,16 +797,17 @@ const TOP_LEVEL: CompletionItem[] = [
 /** `prefix` is the whole argument text typed so far (pi replaces it with `value`). */
 export function completions(prefix: string): CompletionItem[] | null {
 	const text = (prefix ?? "").toLowerCase().replace(/^\s+/, "");
-	const sub = (head: string, words: readonly string[], desc: (w: string) => string): CompletionItem[] =>
-		words.map((w) => ({ value: `${head} ${w}`, label: w, description: desc(w) }));
+	// `tail` = " " when the completed text still needs another word (a budget amount).
+	const sub = (head: string, words: readonly string[], desc: (w: string) => string, tail = ""): CompletionItem[] =>
+		words.map((w) => ({ value: `${head} ${w}${tail}`, label: w, description: desc(w) }));
 
 	let pool: CompletionItem[];
 	if (text.startsWith("status ")) pool = sub("status", STATUS_WINDOWS, (w) => `Show ${w} in the status bar`);
 	else if (text.startsWith("budget ") && !/^budget \S+ /.test(text))
-		pool = sub("budget", BUDGET_PERIODS, (w) => `Set the ${w} budget (tokens or $cost)`);
+		pool = sub("budget", BUDGET_PERIODS, (w) => `Set the ${w} budget (tokens or $cost)`, " ");
 	else if (/^(report|chart) /.test(text)) {
 		const head = text.split(" ")[0];
-		pool = sub(head, REPORT_VIEWS, (w) => `${head} for ${w}`);
+		pool = sub(head, REPORT_VIEWS, (w) => `Chart: ${CHART_SPAN[w as ReportView]}`);
 	} else pool = TOP_LEVEL;
 
 	const out = pool.filter((i) => i.value.startsWith(text));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-tokenburn",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pi extension for live token usage monitoring and budget tracking (Day / Week / Month / Total). 0 prompt tokens.",
   "keywords": ["pi-package", "pi-extension", "tokenburn", "tokens", "analytics", "budget", "stats"],
   "license": "MIT",