@hank-warren/pi-statusline 0.7.2 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-statusline",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Compact Pi footer statusline with Git/worktree context, token usage, and neon celebrations for exceptional prompt-cache hits.",
   "type": "module",
   "keywords": [
@@ -23,7 +23,7 @@
   },
   "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-statusline#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.19.0"
   },
   "pi": {
     "extensions": [
@@ -35,6 +35,8 @@
     "cache-celebration.ts",
     "celebration-preview.ts",
     "celebration-styles.ts",
+    "custom.ts",
+    "custom-setup.ts",
     "redraw.ts",
     "settings.ts",
     "settings-menu.ts",

package/redraw.ts

@@ -33,7 +33,7 @@ export interface RedrawTarget {
 	requestRender(force?: boolean): void;
 }
 
-export interface FullRedrawSchedulerOptions {
+interface FullRedrawSchedulerOptions {
 	minGapMs?: number;
 	rowRefreshIntervalMs?: number;
 	idleIntervalMs?: number;

package/settings-menu.ts

@@ -10,6 +10,7 @@ import {
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
 import { type BooleanSettingKey, collapseHome, resolveWorktreeRoot, type StatuslineSettings } from "./settings.ts";
+import type { CustomItemState } from "./custom.ts";
 import { CELEBRATION_STYLE_NAMES, isCelebrationStyleName } from "./celebration-styles.ts";
 import { isThemeName, THEME_NAMES } from "./themes.ts";
 
@@ -17,13 +18,15 @@ export const THEME_ID = "theme";
 export const CACHE_CELEBRATION_ID = "showCacheCelebration";
 export const WORKTREE_ROOT_ID = "worktreeRoot";
 export const REPO_ALIASES_ID = "repoAliases";
+export const CUSTOM_ITEMS_ID = "customItems";
 export const ADD_ALIAS_VALUE = "\u0000add";
+export const ADD_CUSTOM_ITEM_VALUE = "\u0000add-item";
 
 export const ON = "on";
 export const OFF = "off";
 const TOGGLE_VALUES = [ON, OFF];
 
-export interface BooleanRow {
+interface BooleanRow {
 	id: BooleanSettingKey;
 	label: string;
 	description: string;
@@ -36,6 +39,7 @@ export const BOOLEAN_ROWS: readonly BooleanRow[] = [
 	{ id: "showDirectory", label: "Directory & git", description: "Show the working directory and its git branch." },
 	{ id: "showContext", label: "Context", description: "Show context tokens used against the window." },
 	{ id: "showUsage", label: "Subscription usage", description: "Show Claude/Codex remaining-headroom meters." },
+	{ id: "showCustomItems", label: "Custom items", description: "Run your configured commands and show their output." },
 	{ id: "showWorktrees", label: "Worktree line", description: "Show touched worktrees and their pull requests." },
 	{ id: "showSessionId", label: "Session ID line", description: "Show the full Pi session id on its own line." },
 ];
@@ -57,9 +61,67 @@ export function aliasSummary(settings: StatuslineSettings): string {
 	return `${count} alias${count === 1 ? "" : "es"}`;
 }
 
+/** Row value for the custom-items submenu: how many items are switched on. */
+export function customItemsSummary(settings: StatuslineSettings): string {
+	const total = settings.customItems.length;
+	if (total === 0) return "none configured";
+	return `${settings.customItems.filter((item) => item.enabled).length}/${total} on`;
+}
+
+/**
+ * Rows in the custom-items submenu: each item, what it shows and why, then the
+ * one action that creates an item. Adding hands the job to the agent rather
+ * than opening a form: a statusline command is a script plus a JSON entry plus
+ * a test run, which is a conversation, not a field.
+ */
+export function customItemRows(
+	settings: StatuslineSettings,
+	states: readonly CustomItemState[] = [],
+): SelectItem[] {
+	return [
+		...customItemStateRows(settings, states),
+		{
+			value: ADD_CUSTOM_ITEM_VALUE,
+			label: "Add custom item…",
+			description: "Ask the agent to write one; it gets the contract and the settings path.",
+		},
+	];
+}
+
+function customItemStateRows(settings: StatuslineSettings, states: readonly CustomItemState[]): SelectItem[] {
+	const byId = new Map(states.map((state) => [state.id, state]));
+	return settings.customItems.map((item) => {
+		const state = byId.get(item.id);
+		// Configuration errors outrank run errors: an item that cannot be parsed
+		// never ran, so a stale run error from a previous config would mislead.
+		const error = item.error ?? state?.error;
+		// A broken entry reads as "disabled" unless its reason wins here: it is off
+		// *because* it cannot run, and "disabled" would suggest the user chose that.
+		const detail = item.error !== undefined
+			? item.error
+			: !item.enabled
+				? "disabled"
+				: error !== undefined
+				? error
+				: state?.running === true && state.value === undefined
+					? "running…"
+					: state?.value !== undefined && state.value.length > 0
+						? state.value
+						: state?.value !== undefined
+							? "empty output"
+							: "no value yet";
+		return {
+			value: item.id,
+			label: `${item.enabled ? toggleValue(true) : toggleValue(false)}  ${item.id}`,
+			description: detail,
+		};
+	});
+}
+
 export interface SettingSubmenus {
 	worktreeRoot?: SettingItem["submenu"];
 	repoAliases?: SettingItem["submenu"];
+	customItems?: SettingItem["submenu"];
 }
 
 /** Build the `/statusline` rows for a settings snapshot. */
@@ -81,6 +143,10 @@ export function buildSettingItems(
 	// Rows follow the order their elements render in, so the celebration sits
 	// after the usage meters it is appended to on line 1.
 	for (const row of BOOLEAN_ROWS) {
+		// A toggle for a segment with nothing in it is a row that does nothing;
+		// the list row below is where an item gets created, and the toggle
+		// appears once there is something to switch off.
+		if (row.id === "showCustomItems" && settings.customItems.length === 0) continue;
 		items.push({
 			id: row.id,
 			label: row.label,
@@ -113,6 +179,13 @@ export function buildSettingItems(
 		currentValue: aliasSummary(settings),
 		...(submenus.repoAliases ? { submenu: submenus.repoAliases } : {}),
 	});
+	items.push({
+		id: CUSTOM_ITEMS_ID,
+		label: "Custom item list",
+		description: "Enable or disable configured items; edit commands in statusline-settings.json.",
+		currentValue: customItemsSummary(settings),
+		...(submenus.customItems ? { submenu: submenus.customItems } : {}),
+	});
 
 	return items;
 }
@@ -183,6 +256,13 @@ export function aliasItems(settings: StatuslineSettings): SelectItem[] {
 export interface SubmenuHost {
 	/** Read the live settings; the menu edits a single shared snapshot. */
 	getSettings(): StatuslineSettings;
+	/** Live per-item run state, for the custom-items submenu. */
+	customItemStates?(): CustomItemState[];
+	/**
+	 * Hand "add an item" to the agent with the user's one-line description of
+	 * what it should show. Closes the menu; absent when no agent can be reached.
+	 */
+	requestCustomItem?(request: string): void;
 	/** Commit an edit: persists, applies live, and repaints. */
 	commit(settings: StatuslineSettings): void;
 	notify(message: string): void;
@@ -348,3 +428,99 @@ class AliasSubmenu implements Component {
 export function createAliasSubmenu(host: SubmenuHost): NonNullable<SettingItem["submenu"]> {
 	return (_currentValue, done) => new AliasSubmenu(host, done);
 }
+
+/**
+ * Custom item list: enable/disable each item and read why it is not showing.
+ *
+ * Commands are edited in the settings file, not here. A statusline command is a
+ * shell line with quoting and pipes in it, which a single-line TUI prompt edits
+ * badly, and keeping the field out of the menu means a toggle writes only the
+ * `enabled` flag over whatever the file currently holds.
+ */
+class CustomItemsSubmenu implements Component {
+	private list: SelectList;
+	private prompt: PromptComponent | undefined;
+
+	constructor(
+		private readonly host: SubmenuHost,
+		private readonly done: (value?: string) => void,
+	) {
+		this.list = this.buildList();
+	}
+
+	private buildList(selectedIndex = 0): SelectList {
+		const rows = customItemRows(this.host.getSettings(), this.host.customItemStates?.() ?? []);
+		const list = new SelectList(rows, 10, this.host.selectTheme);
+		list.setSelectedIndex(selectedIndex);
+		list.onCancel = () => this.done(customItemsSummary(this.host.getSettings()));
+		list.onSelect = (item) => (item.value === ADD_CUSTOM_ITEM_VALUE ? this.add() : this.toggle(item.value));
+		return list;
+	}
+
+	private add(): void {
+		if (!this.host.requestCustomItem) {
+			this.host.notify("Add items to statusline-settings.json; see the pi-statusline README");
+			return;
+		}
+		this.prompt = new PromptComponent(
+			"What should the item show? (Enter for the agent to ask)",
+			"",
+			this.host.settingsTheme.hint,
+			(value) => {
+				this.prompt = undefined;
+				// Close the whole menu before the message lands: the agent's reply
+				// renders in the transcript, which the menu is drawn over.
+				this.done(customItemsSummary(this.host.getSettings()));
+				this.host.requestCustomItem?.(value);
+			},
+			() => {
+				this.prompt = undefined;
+				this.host.requestRender();
+			},
+		);
+		this.host.requestRender();
+	}
+
+	private toggle(id: string): void {
+		if (id.startsWith("\u0000")) return;
+		const settings = this.host.getSettings();
+		const index = settings.customItems.findIndex((item) => item.id === id);
+		const target = settings.customItems[index];
+		if (!target) return;
+		if (target.error !== undefined && !target.enabled) {
+			// Enabling an unparseable entry would only fail again on the next tick.
+			this.host.notify(`${id} cannot run: ${target.error}`);
+			return;
+		}
+		const customItems = [...settings.customItems];
+		customItems[index] = { ...target, enabled: !target.enabled };
+		this.host.commit({ ...settings, customItems });
+		this.list = this.buildList(index);
+		this.host.requestRender();
+	}
+
+	invalidate(): void {
+		this.prompt?.invalidate();
+		this.list.invalidate();
+	}
+
+	render(width: number): string[] {
+		if (this.prompt) return this.prompt.render(width);
+		return [
+			truncateToWidth(this.host.settingsTheme.hint("  Custom items"), width),
+			"",
+			...this.list.render(width),
+			"",
+			truncateToWidth(this.host.settingsTheme.hint("  Enter to enable/disable or add · Esc to go back"), width),
+		];
+	}
+
+	handleInput(data: string): void {
+		if (this.prompt) this.prompt.handleInput(data);
+		else this.list.handleInput(data);
+	}
+}
+
+export function createCustomItemsSubmenu(host: SubmenuHost): NonNullable<SettingItem["submenu"]> {
+	return (_currentValue, done) => new CustomItemsSubmenu(host, done);
+}

package/settings.ts

@@ -2,11 +2,18 @@ import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import { pid } from "node:process";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import {
 	type CelebrationStyleName,
 	DEFAULT_CELEBRATION_STYLE,
 	isCelebrationStyleName,
 } from "./celebration-styles.ts";
+import {
+	type CustomItem,
+	normalizeCustomItems,
+	sameCustomItems,
+	serializeCustomItems,
+} from "./custom.ts";
 import { DEFAULT_THEME, isThemeName, type StatuslineThemeName } from "./themes.ts";
 
 /** Toggle keys, in the order the `/statusline` menu lists them. */
@@ -16,6 +23,7 @@ export const BOOLEAN_SETTING_KEYS = [
 	"showDirectory",
 	"showContext",
 	"showUsage",
+	"showCustomItems",
 	"showWorktrees",
 	"showSessionId",
 	"showCacheCelebration",
@@ -32,9 +40,11 @@ export interface StatuslineSettings extends Record<BooleanSettingKey, boolean> {
 	worktreeRoot: string;
 	/** `repository name -> display alias` overrides for the worktree line. */
 	repoAliases: Record<string, string>;
+	/** User-defined command segments rendered after the usage meters. */
+	customItems: CustomItem[];
 }
 
-export function defaultWorktreeRoot(home: string = homedir()): string {
+function defaultWorktreeRoot(home: string = homedir()): string {
 	return join(home || homedir(), "repos", "worktrees");
 }
 
@@ -46,6 +56,9 @@ export function defaultSettings(home: string = homedir()): StatuslineSettings {
 		showDirectory: true,
 		showContext: true,
 		showUsage: true,
+		// On by default and free until the user configures an item: with an empty
+		// list nothing renders, nothing is spawned, and no timer runs.
+		showCustomItems: true,
 		showWorktrees: true,
 		showSessionId: true,
 		showCacheCelebration: true,
@@ -53,11 +66,21 @@ export function defaultSettings(home: string = homedir()): StatuslineSettings {
 		cacheCelebrationStyle: DEFAULT_CELEBRATION_STYLE,
 		worktreeRoot: defaultWorktreeRoot(home),
 		repoAliases: {},
+		customItems: [],
 	};
 }
 
-export function defaultSettingsPath(home: string = homedir()): string {
-	return join(home || homedir(), ".pi", "agent", "statusline-settings.json");
+/**
+ * Where the settings live when the caller names no path.
+ *
+ * The agent dir, not the home dir: pi honours `PI_CODING_AGENT_DIR`, so a
+ * session running against a scratch agent dir must save its statusline settings
+ * there rather than into the host's real `~/.pi/agent`. `home` still shapes the
+ * settings' *content* (the worktree root default, `~` collapsing) — that is a
+ * different thing and keeps its own parameter.
+ */
+export function defaultSettingsPath(): string {
+	return join(getAgentDir(), "statusline-settings.json");
 }
 
 /** Expand a leading `~` (and `$HOME`) against `home`; other paths are returned as-is. */
@@ -78,7 +101,7 @@ export function collapseHome(path: string, home: string = homedir()): string {
 	return path.startsWith(`${base}/`) ? `~/${path.slice(base.length + 1)}` : path;
 }
 
-export interface WorktreeRootResult {
+interface WorktreeRootResult {
 	path?: string;
 	error?: string;
 }
@@ -109,7 +132,7 @@ function normalizeAliases(value: unknown): Record<string, string> | undefined {
 	return aliases;
 }
 
-export interface NormalizedSettings {
+interface NormalizedSettings {
 	settings: StatuslineSettings;
 	/** Top-level keys this version does not know about, preserved on write. */
 	extra: Record<string, unknown>;
@@ -130,6 +153,7 @@ export function normalizeSettings(value: unknown, home: string = homedir()): Nor
 		"cacheCelebrationStyle",
 		"worktreeRoot",
 		"repoAliases",
+		"customItems",
 	]);
 	for (const [key, raw] of Object.entries(value)) {
 		if (!known.has(key)) {
@@ -148,6 +172,12 @@ export function normalizeSettings(value: unknown, home: string = homedir()): Nor
 			if (aliases) settings.repoAliases = aliases;
 			continue;
 		}
+		if (key === "customItems") {
+			// Unusable entries come back as items carrying their parse error rather
+			// than being dropped, so a write cannot delete what it failed to read.
+			settings.customItems = normalizeCustomItems(raw);
+			continue;
+		}
 		if (key === "theme") {
 			if (isThemeName(raw)) settings.theme = raw;
 			continue;
@@ -175,6 +205,7 @@ export const SETTING_KEYS = [
 	"cacheCelebrationStyle",
 	"worktreeRoot",
 	"repoAliases",
+	"customItems",
 ] as const satisfies readonly (keyof StatuslineSettings)[];
 
 export type SettingKey = (typeof SETTING_KEYS)[number];
@@ -195,11 +226,11 @@ export function changedSettingKeys(
 	previous: StatuslineSettings,
 	next: StatuslineSettings,
 ): SettingKey[] {
-	return SETTING_KEYS.filter((key) =>
-		key === "repoAliases"
-			? !sameAliases(previous.repoAliases, next.repoAliases)
-			: previous[key] !== next[key],
-	);
+	return SETTING_KEYS.filter((key) => {
+		if (key === "repoAliases") return !sameAliases(previous.repoAliases, next.repoAliases);
+		if (key === "customItems") return !sameCustomItems(previous.customItems, next.customItems);
+		return previous[key] !== next[key];
+	});
 }
 
 /**
@@ -222,10 +253,13 @@ export function serializeSettings(
 	}
 	if (settings.worktreeRoot !== defaults.worktreeRoot) out.worktreeRoot = settings.worktreeRoot;
 	if (!sameAliases(settings.repoAliases, defaults.repoAliases)) out.repoAliases = { ...settings.repoAliases };
+	// An empty list is the default and stays out of the file; a configured one is
+	// written back from each entry's original source object.
+	if (settings.customItems.length > 0) out.customItems = serializeCustomItems(settings.customItems);
 	return out;
 }
 
-export interface SettingsStoreOptions {
+interface SettingsStoreOptions {
 	path?: string;
 	home?: string;
 }
@@ -242,7 +276,7 @@ export class SettingsStore {
 
 	constructor(options: SettingsStoreOptions = {}) {
 		this.home = options.home ?? homedir();
-		this.path = options.path ?? defaultSettingsPath(this.home);
+		this.path = options.path ?? defaultSettingsPath();
 		this.current = defaultSettings(this.home);
 	}
 

package/usage.ts

@@ -1,8 +1,8 @@
 import { createHash } from "node:crypto";
 import { readFile, rename, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { pid } from "node:process";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 /**
  * Remaining (not used) integer percents per provider window.
@@ -84,7 +84,7 @@ export const USAGE_RATE_LIMIT_BACKOFF_MS = 15 * 60_000;
  * process's fresh values appear within one tick instead of at the next turn.
  * Request volume is unchanged: both throttles still gate every fetch.
  */
-export const USAGE_TICK_INTERVAL_MS = 10_000;
+const USAGE_TICK_INTERVAL_MS = 10_000;
 const FETCH_TIMEOUT_MS = 10_000;
 const ONE_DAY_SECONDS = 86_400;
 
@@ -283,7 +283,7 @@ type ProviderKey = "claude" | "codex";
 const PROVIDER_KEYS = ["claude", "codex"] as const;
 
 /** Provider ids whose additional logins (`${base}-${suffix}`) share a meter. */
-export const USAGE_BASE_PROVIDERS: Record<ProviderKey, string> = {
+const USAGE_BASE_PROVIDERS: Record<ProviderKey, string> = {
 	claude: "anthropic",
 	codex: "openai-codex",
 };
@@ -295,7 +295,7 @@ const PROVIDER_REFRESH_INTERVAL_MS: Record<ProviderKey, number> = {
 };
 
 /** Credential id polled for each family. */
-export type UsageAccounts = Record<ProviderKey, string>;
+type UsageAccounts = Record<ProviderKey, string>;
 
 /** A freshly fetched value together with the boundary it is valid until. */
 interface FetchedUsage<K extends ProviderKey> {
@@ -477,8 +477,11 @@ export class UsageTracker {
 	private tickHandle: unknown;
 
 	constructor(options: UsageTrackerOptions = {}) {
-		this.authPath = options.authPath ?? join(homedir(), ".pi", "agent", "auth.json");
-		this.cachePath = options.cachePath ?? join(homedir(), ".pi", "agent", "statusline-usage.json");
+		// getAgentDir(), not ~/.pi/agent: pi honours PI_CODING_AGENT_DIR, and a
+		// hardcoded home path made a session pointed at another agent dir read the
+		// wrong credentials and write its usage cache into the host's real one.
+		this.authPath = options.authPath ?? join(getAgentDir(), "auth.json");
+		this.cachePath = options.cachePath ?? join(getAgentDir(), "statusline-usage.json");
 		this.fetchFn = options.fetchFn ?? ((url, init) => fetch(url, init));
 		this.onChange = options.onChange;
 		this.now = options.now ?? Date.now;

package/worktrees.ts

@@ -29,7 +29,7 @@ interface WorktreeMetadata {
 	branch: string;
 }
 
-export interface WorktreeTrackerHost {
+interface WorktreeTrackerHost {
 	exec(
 		command: string,
 		args: string[],