pi-zro-provider 1.0.0

package/status.ts

@@ -0,0 +1,298 @@
+/**
+ * Footer status presentation for the Zro extension.
+ *
+ * Pure functions + a width-aware widget component — no pi runtime imports.
+ * index.ts owns fetching, events, and config persistence; this module turns
+ * state snapshots into terminal strings.
+ *
+ * Layout (below-editor widget, neuralwatt style):
+ *
+ *   ⚡ $0.42 · 7 req              Pro ◆ $12.34 avail · $2.50 pack · 1.2k req/30d
+ *   └ left: session activity ─┘  └───────────── right: account / quota ─────────┘
+ *
+ * The left side is preserved at full fidelity. The right side is rendered
+ * from a tier list (most → least detailed); render() picks the first tier
+ * that fits the remaining width, and as a last resort truncates the minimal
+ * tier. Width math counts only terminal-visible columns (ANSI-aware, wide
+ * glyphs like ⚡ ⚠ measure 2 columns).
+ */
+
+export type DisplayMode = "widget" | "statusbar" | "off";
+
+export interface StatusConfig {
+	session: DisplayMode;
+	account: DisplayMode;
+	hideOnOtherProvider: boolean;
+	lowBalanceUsd: number | null;
+}
+
+export const DEFAULT_STATUS_CONFIG: StatusConfig = {
+	session: "widget",
+	account: "widget",
+	hideOnOtherProvider: true,
+	lowBalanceUsd: 10,
+};
+
+const VALID_MODES = new Set<string>(["widget", "statusbar", "off"]);
+
+function coerceMode(value: unknown, fallback: DisplayMode): DisplayMode {
+	return typeof value === "string" && VALID_MODES.has(value) ? (value as DisplayMode) : fallback;
+}
+
+export function coerceStatusConfig(raw: unknown): StatusConfig {
+	const d = DEFAULT_STATUS_CONFIG;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return { ...d };
+	const r = raw as Record<string, unknown>;
+	return {
+		session: coerceMode(r.session, d.session),
+		account: coerceMode(r.account, d.account),
+		hideOnOtherProvider: typeof r.hideOnOtherProvider === "boolean" ? r.hideOnOtherProvider : d.hideOnOtherProvider,
+		lowBalanceUsd:
+			typeof r.lowBalanceUsd === "number" && Number.isFinite(r.lowBalanceUsd) && r.lowBalanceUsd > 0
+				? r.lowBalanceUsd
+				: r.lowBalanceUsd === null || r.lowBalanceUsd === false
+					? null
+					: d.lowBalanceUsd,
+	};
+}
+
+// State snapshots
+export interface RateLimitState {
+	limit: number;
+	remaining: number;
+	capturedAt: number;
+}
+
+export interface AccountState {
+	availableUsd: number | null;
+	planName: string | null;
+	usagePackUsd: number | null;
+	activity30dRequests: number | null;
+	activity30dTokens: number | null;
+	rate: RateLimitState | null;
+	keyAlias: string | null;
+}
+
+export const EMPTY_ACCOUNT: AccountState = {
+	availableUsd: null,
+	planName: null,
+	usagePackUsd: null,
+	activity30dRequests: null,
+	activity30dTokens: null,
+	rate: null,
+	keyAlias: null,
+};
+
+export interface SessionStats {
+	requests: number;
+	tokens: number;
+	spend: number;
+}
+
+export const EMPTY_SESSION_STATS: SessionStats = { requests: 0, tokens: 0, spend: 0 };
+
+export function applyOptimisticSpend(acc: AccountState, spendUsd: number): void {
+	if (spendUsd > 0 && acc.availableUsd !== null) {
+		acc.availableUsd = Math.max(0, acc.availableUsd - spendUsd);
+	}
+}
+
+// Formatters
+function trimZeros(text: string): string {
+	return text.includes(".") ? text.replace(/0+$/, "").replace(/\.$/, "") : text;
+}
+
+export function formatUsd(n: number): string {
+	if (!Number.isFinite(n)) return "?";
+	if (n <= 0) return "$0";
+	if (n < 0.01) return "~$0.01";
+	const abs = Math.abs(n);
+	if (abs >= 1_000_000) return `$${trimZeros((n / 1_000_000).toFixed(2))}M`;
+	if (abs >= 10_000) return `$${trimZeros((n / 1_000).toFixed(1))}k`;
+	if (abs >= 100) return `$${Math.round(n)}`;
+	return `$${trimZeros(n.toFixed(2))}`;
+}
+
+export function formatTokens(n: number): string {
+	if (!Number.isFinite(n)) return "?";
+	if (n <= 0) return "0";
+	if (n < 1000) return String(Math.round(n));
+	if (n < 1_000_000) return `${trimZeros((n / 1000).toFixed(1))}k`;
+	return `${trimZeros((n / 1_000_000).toFixed(2))}M`;
+}
+
+export function formatCount(n: number): string {
+	if (!Number.isFinite(n)) return "?";
+	if (n >= 1_000_000) return `${trimZeros((n / 1_000_000).toFixed(2))}M`;
+	if (n >= 1000) return `${trimZeros((n / 1000).toFixed(1))}k`;
+	return String(Math.max(0, Math.round(n)));
+}
+
+// Line builders
+export function buildSessionLine(stats: SessionStats): string | undefined {
+	if (stats.requests <= 0 && stats.tokens <= 0 && stats.spend <= 0) return undefined;
+	const req = `${stats.requests} req`;
+	if (stats.spend > 0) return `⚡ ${formatUsd(stats.spend)} · ${req}`;
+	if (stats.tokens > 0) return `⚡ ${formatTokens(stats.tokens)} tok · ${req}`;
+	return `⚡ ${req}`;
+}
+
+export function accountHasData(acc: AccountState): boolean {
+	return (
+		acc.availableUsd !== null ||
+		acc.planName !== null ||
+		acc.usagePackUsd !== null ||
+		acc.activity30dRequests !== null ||
+		acc.activity30dTokens !== null ||
+		acc.rate !== null ||
+		acc.keyAlias !== null
+	);
+}
+
+export function buildAccountTiers(acc: AccountState, lowBalance: boolean): string[] {
+	const gem = lowBalance ? "⚠ ◆" : "◆";
+	const bal = acc.availableUsd !== null ? `${gem} ${formatUsd(acc.availableUsd)} avail` : undefined;
+	const plan = acc.planName?.trim() || undefined;
+	const pack = acc.usagePackUsd !== null && acc.usagePackUsd > 0 ? `${formatUsd(acc.usagePackUsd)} pack` : undefined;
+	const actTok = acc.activity30dTokens !== null && acc.activity30dTokens > 0 ? `${formatTokens(acc.activity30dTokens)} tok/30d` : undefined;
+	const actReq = acc.activity30dRequests !== null ? `${formatCount(acc.activity30dRequests)} req/30d` : undefined;
+	const rate = acc.rate !== null ? `${formatCount(acc.rate.remaining)}/${formatCount(acc.rate.limit)}` : undefined;
+	const head = [plan, bal].filter((p): p is string => !!p).join(" ") || undefined;
+	const numOnly = acc.availableUsd !== null ? formatUsd(acc.availableUsd) : undefined;
+
+	const join = (parts: (string | undefined)[]) => parts.filter((p): p is string => !!p).join(" · ");
+
+	const tiers: string[] = [
+		join([head, pack, actTok, actReq, rate]),
+		join([head, pack, actReq, rate]),
+		join([head, pack, actReq]),
+		join([head, actTok, actReq]),
+		join([head, actReq]),
+		join([head, rate]),
+		join([head]),
+		join([bal, actReq]),
+		join([bal]),
+		join([numOnly]),
+	];
+
+	// Dedupe adjacent identical tiers (happens when atoms are missing).
+	// Enforce monotonic non-increasing width so render() can trust ordering
+	// even on pathological data (a tier wider than its predecessor is dropped).
+	const out: string[] = [];
+	for (const t of tiers) {
+		if (!t || t === out[out.length - 1]) continue;
+		if (out.length > 0 && termVisWidth(t) > termVisWidth(out[out.length - 1])) continue;
+		out.push(t);
+	}
+	return out;
+}
+
+// Terminal width math (adapted from pi-neuralwatt-provider)
+const EMOJI_RE = /\p{Emoji_Presentation}/u;
+const AMBIGUOUS_WIDE = new Set(["■", "▲", "◉"]);
+
+export function termVisWidth(str: string): number {
+	let width = 0;
+	let i = 0;
+	while (i < str.length) {
+		const code = str.charCodeAt(i);
+		if (code === 0x1b && i + 1 < str.length) {
+			const next = str.charCodeAt(i + 1);
+			if (next === 0x5b) {
+				i += 2;
+				while (i < str.length && str.charCodeAt(i) >= 0x20 && str.charCodeAt(i) <= 0x3f) i++;
+				while (i < str.length && str.charCodeAt(i) >= 0x30 && str.charCodeAt(i) <= 0x3f) i++;
+				if (i < str.length) i++;
+				continue;
+			}
+		}
+		const cp = str.codePointAt(i)!;
+		const char = cp > 0xffff ? str.slice(i, i + 2) : str[i];
+		if (cp >= 0x1f1e6 && cp <= 0x1f1ff) {
+			width += 1;
+		} else if (EMOJI_RE.test(char)) {
+			width += 2;
+		} else if (AMBIGUOUS_WIDE.has(char)) {
+			width += 2;
+		} else {
+			width += 1;
+		}
+		i += cp > 0xffff ? 2 : 1;
+	}
+	return width;
+}
+
+export function truncateAnsi(str: string, maxCols: number): string {
+	if (maxCols <= 0) return "";
+	if (termVisWidth(str) <= maxCols) return str;
+	let result = "";
+	let visWidth = 0;
+	let i = 0;
+	const target = maxCols - 1;
+	while (i < str.length) {
+		const code = str.charCodeAt(i);
+		if (code === 0x1b && i + 1 < str.length && str.charCodeAt(i + 1) === 0x5b) {
+			const start = i;
+			i += 2;
+			while (i < str.length && str.charCodeAt(i) >= 0x20 && str.charCodeAt(i) <= 0x3f) i++;
+			while (i < str.length && str.charCodeAt(i) >= 0x30 && str.charCodeAt(i) <= 0x3f) i++;
+			if (i < str.length) i++;
+			result += str.slice(start, i);
+			continue;
+		}
+		const cp = str.codePointAt(i)!;
+		const char = cp > 0xffff ? str.slice(i, i + 2) : str[i];
+		let charWidth: number;
+		if (cp >= 0x1f1e6 && cp <= 0x1f1ff) charWidth = 1;
+		else if (EMOJI_RE.test(char)) charWidth = 2;
+		else if (AMBIGUOUS_WIDE.has(char)) charWidth = 2;
+		else charWidth = 1;
+		if (visWidth + charWidth > target) break;
+		result += char;
+		visWidth += charWidth;
+		i += cp > 0xffff ? 2 : 1;
+	}
+	return result + "…";
+}
+
+export interface LineTheme {
+	fg(color: string, text: string): string;
+}
+
+export class StatusLineWidget {
+	private theme: LineTheme;
+	private leftRaw: string;
+	private rightTiers: string[];
+	private rightWarn: boolean;
+
+	constructor(theme: LineTheme, leftRaw: string, rightTiers: string[] = [], rightWarn = false) {
+		this.theme = theme;
+		this.leftRaw = leftRaw;
+		this.rightTiers = rightTiers;
+		this.rightWarn = rightWarn;
+	}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const leftVis = termVisWidth(this.leftRaw);
+		if (leftVis > width) {
+			return [this.theme.fg("dim", truncateAnsi(this.leftRaw, width))];
+		}
+
+		const rightColor = this.rightWarn ? "warning" : "dim";
+		const themedLeft = this.theme.fg("dim", this.leftRaw);
+		const budget = width - leftVis - 1;
+
+		for (const tier of this.rightTiers) {
+			if (termVisWidth(tier) <= budget) {
+				const themedRight = this.theme.fg(rightColor, tier);
+				const pad = width - termVisWidth(themedLeft) - termVisWidth(themedRight);
+				return [themedLeft + " ".repeat(Math.max(1, pad)) + themedRight];
+			}
+		}
+
+		const pad = width - termVisWidth(themedLeft);
+		return [themedLeft + " ".repeat(Math.max(0, pad))];
+	}
+}

package/tests/status.smoke.ts

@@ -0,0 +1,164 @@
+/**
+ * Dependency-free smoke test for the footer-status presentation module.
+ * Run: node tests/status.smoke.ts (Node ≥ 23 strips types natively).
+ * Exercises tier building, width math, widget layout, and config coercion —
+ * the pieces where a regression would silently corrupt the footer line.
+ */
+import assert from "node:assert/strict";
+import {
+	EMPTY_ACCOUNT,
+	StatusLineWidget,
+	accountHasData,
+	applyOptimisticSpend,
+	buildAccountTiers,
+	buildSessionLine,
+	coerceStatusConfig,
+	formatCount,
+	formatTokens,
+	formatUsd,
+	termVisWidth,
+	truncateAnsi,
+	type AccountState,
+} from "../status.ts";
+
+const stripAnsi = (s: string) => s.replace(/\x1b\[[0-9;]*m/g, "");
+const fakeTheme = { fg: (_c: string, t: string) => `\x1b[2m${t}\x1b[39m` };
+
+// ── formatters ──
+assert.equal(formatUsd(0), "$0");
+assert.equal(formatUsd(12.34), "$12.34");
+assert.equal(formatUsd(0.5), "$0.5");
+assert.equal(formatUsd(249), "$249");
+assert.equal(formatUsd(12345), "$12.3k");
+assert.equal(formatUsd(1_250_000), "$1.25M");
+assert.equal(formatUsd(0.0004), "~$0.01");
+assert.equal(formatTokens(0), "0");
+assert.equal(formatTokens(850), "850");
+assert.equal(formatTokens(48200), "48.2k");
+assert.equal(formatTokens(1_048_576), "1.05M");
+assert.equal(formatCount(7), "7");
+assert.equal(formatCount(1200), "1.2k");
+assert.equal(formatCount(12_000), "12k");
+
+// ── session line ──
+assert.equal(buildSessionLine({ requests: 0, tokens: 0, spend: 0 }), undefined);
+assert.equal(buildSessionLine({ requests: 7, tokens: 48200, spend: 0 }), "⚡ 48.2k tok · 7 req");
+assert.equal(buildSessionLine({ requests: 7, tokens: 0, spend: 0.42 }), "⚡ $0.42 · 7 req");
+assert.equal(buildSessionLine({ requests: 1, tokens: 0, spend: 0 }), "⚡ 1 req");
+
+// ── account tiers ──
+const acc = (over: Partial<AccountState>): AccountState => ({ ...EMPTY_ACCOUNT, ...over });
+const rate = { limit: 1000, remaining: 996, capturedAt: 0 };
+
+assert.equal(accountHasData(acc({})), false);
+assert.equal(accountHasData(acc({ availableUsd: 0 })), true);
+
+const full = acc({ availableUsd: 12.34, planName: "Pro", usagePackUsd: 2.5, activity30dRequests: 1200, activity30dTokens: 850000, rate });
+const tiers = buildAccountTiers(full, false);
+assert.equal(tiers[0], "Pro ◆ $12.34 avail · $2.5 pack · 850k tok/30d · 1.2k req/30d · 996/1k");
+assert.ok(tiers.includes("Pro ◆ $12.34 avail"));
+assert.ok(tiers.includes("◆ $12.34 avail"));
+assert.ok(tiers.includes("$12.34"));
+// tiers must be strictly non-increasing in width
+for (let i = 1; i < tiers.length; i++) {
+	assert.ok(termVisWidth(tiers[i]) <= termVisWidth(tiers[i - 1]), `tier ${i} wider than previous`);
+}
+// dedupe of adjacent identical tiers when atoms are missing
+assert.deepEqual(buildAccountTiers(acc({ planName: "Pro" }), false), ["Pro"]);
+const balOnly = buildAccountTiers(acc({ availableUsd: 5 }), true);
+assert.equal(balOnly[0], "⚠ ◆ $5 avail");
+assert.ok(balOnly.includes("$5"));
+
+// optimistic spend deduction
+{
+	const opt = acc({ availableUsd: 12.34 });
+	applyOptimisticSpend(opt, 0.5);
+	assert.equal(opt.availableUsd, 11.84);
+	applyOptimisticSpend(opt, 0); // zero spend is a no-op
+	assert.equal(opt.availableUsd, 11.84);
+	applyOptimisticSpend(opt, 300); // clamps at 0, never negative
+	assert.equal(opt.availableUsd, 0);
+	const unknown = acc({ availableUsd: null });
+	applyOptimisticSpend(unknown, 1); // unknown balance stays unknown
+	assert.equal(unknown.availableUsd, null);
+}
+
+// ── width math ──
+assert.equal(termVisWidth("abc"), 3);
+assert.equal(termVisWidth(""), 0);
+assert.equal(termVisWidth(fakeTheme.fg("dim", "abc")), 3, "ANSI is zero-width");
+assert.equal(termVisWidth("◆"), 1, "◆ counts as narrow in this terminal");
+assert.equal(termVisWidth("⚡"), 2);
+assert.equal(truncateAnsi("hello world", 8), "hello w…");
+assert.equal(termVisWidth(truncateAnsi(fakeTheme.fg("x", "hello world"), 8)), 8);
+assert.equal(truncateAnsi("abc", 5), "abc");
+assert.equal(truncateAnsi("abc", 0), "");
+
+// ── widget render ──
+const left = buildSessionLine({ requests: 7, tokens: 0, spend: 0.42 })!;
+const widget = new StatusLineWidget(fakeTheme, left, tiers, false);
+
+// Wide: full tier, left-right justified, exactly width columns
+const wide = widget.render(80);
+assert.equal(wide.length, 1);
+assert.equal(termVisWidth(wide[0]), 80);
+assert.ok(stripAnsi(wide[0]).startsWith("⚡ $0.42"));
+assert.ok(stripAnsi(wide[0]).endsWith("996/1k"));
+
+// Medium: drops to a compressed tier, still exactly width
+const med = widget.render(52);
+assert.equal(termVisWidth(med[0]), 52);
+assert.ok(!stripAnsi(med[0]).includes("tok/30d"), "compressed tiers drop tokens activity first");
+
+// Narrow: no tier fits → left only, padded
+const narrow = widget.render(termVisWidth(left) + 3);
+assert.equal(termVisWidth(narrow[0]), termVisWidth(left) + 3);
+assert.ok(stripAnsi(narrow[0]).startsWith("⚡"));
+assert.ok(!stripAnsi(narrow[0]).includes("◆"));
+
+// Narrower than left itself: truncation never overflows (crash guard)
+const tiny = widget.render(10);
+assert.equal(termVisWidth(tiny[0]), 10);
+
+// Left empty (session gated) → right-aligned account line
+const rightOnly = new StatusLineWidget(fakeTheme, "", tiers, false);
+const ro = rightOnly.render(70);
+assert.equal(termVisWidth(ro[0]), 70);
+assert.ok(stripAnsi(ro[0]).endsWith("996/1k"));
+
+// No data at all
+assert.deepEqual(new StatusLineWidget(fakeTheme, "", [], false).render(40), [fakeTheme.fg("dim", "") + " ".repeat(40)]);
+
+// Warning color wired through
+const warn = new StatusLineWidget(fakeTheme, "", buildAccountTiers(acc({ availableUsd: 5 }), true), true);
+const warnLine = warn.render(60)[0];
+assert.ok(stripAnsi(warnLine).includes("⚠ ◆ $5 avail"));
+assert.ok(warnLine.includes("warning") || true); // fakeTheme ignores color names
+const markTheme = { fg: (c: string, t: string) => `<${c}>${t}</>` };
+assert.ok(new StatusLineWidget(markTheme, "", buildAccountTiers(acc({ availableUsd: 5 }), true), true).render(60)[0].includes("<warning>"));
+assert.ok(new StatusLineWidget(markTheme, "", buildAccountTiers(acc({ availableUsd: 5 }), true), false).render(60)[0].includes("<dim>"));
+
+// ── config coercion ──
+assert.deepEqual(coerceStatusConfig(undefined), {
+	session: "widget",
+	account: "widget",
+	hideOnOtherProvider: true,
+	lowBalanceUsd: 10,
+});
+assert.deepEqual(coerceStatusConfig({ session: "bogus", lowBalanceUsd: -3 }), {
+	session: "widget",
+	account: "widget",
+	hideOnOtherProvider: true,
+	lowBalanceUsd: 10,
+});
+assert.deepEqual(coerceStatusConfig({ session: "statusbar", account: "off", hideOnOtherProvider: false, lowBalanceUsd: null }), {
+	session: "statusbar",
+	account: "off",
+	hideOnOtherProvider: false,
+	lowBalanceUsd: null,
+});
+assert.equal(coerceStatusConfig({ lowBalanceUsd: 42 }).lowBalanceUsd, 42);
+assert.equal(coerceStatusConfig({ lowBalanceUsd: false }).lowBalanceUsd, null);
+assert.deepEqual(coerceStatusConfig(null).session, "widget");
+
+console.log("status.smoke: all assertions passed");

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "esModuleInterop": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "resolveJsonModule": true
+  },
+  "include": ["./*.ts"],
+  "exclude": ["node_modules", "tests"]
+}