@pi-vault/pi-status 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/%40pi-vault%2Fpi-status)](https://www.npmjs.com/package/@pi-vault/pi-status)
 [![Quality](https://github.com/pi-vault/pi-status/actions/workflows/quality.yml/badge.svg?branch=master)](https://github.com/pi-vault/pi-status/actions/workflows/quality.yml)
-[![Node >= 22.12](https://img.shields.io/badge/node-%3E%3D22.12-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![Node >= 22.19](https://img.shields.io/badge/node-%3E%3D22.19-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 
 Replace Pi's default footer with a cleaner Codex-style status line that stays out of the way but keeps the useful bits visible.
@@ -11,20 +11,36 @@ Default status line:
 
 `model-with-reasoning · current-dir`
 
-> **Status:** Early-adopter release (`v0.1.0`). It is ready to use, but the available segments and configuration details may still change before `v1.0`.
-
 ## Install
 
+Install `pi-status`:
+
 ```bash
 pi install npm:@pi-vault/pi-status
 ```
 
+Optional: install `pi-usage` if you want `/usage` plus the usage-backed footer segments:
+
+```bash
+pi install npm:@pi-vault/pi-usage
+```
+
 Then reload Pi:
 
 ```bash
 /reload
 ```
 
+## Screenshots
+
+Default status line rendering:
+
+![Status line UI](docs/assets/statusline-ui.png)
+
+Interactive configuration editor (`/statusline`):
+
+![Status line configuration](docs/assets/statusline-configuration.png)
+
 ## Use
 
 Once installed, the footer updates automatically.
@@ -59,7 +75,7 @@ You can build your footer from these items:
 - `weekly-limit`
 - `extension-statuses`
 
-`five-hour-limit` and `weekly-limit` come from [`@pi-vault/pi-usage`](https://www.npmjs.com/package/@pi-vault/pi-usage) and only appear when that usage data is available.
+`five-hour-limit` and `weekly-limit` require standalone [`@pi-vault/pi-usage`](https://www.npmjs.com/package/@pi-vault/pi-usage). When `pi-usage` is not installed or has not responded yet, those items are hidden from `/statusline` and omitted from the footer.
 
 ## Common Setups
 
@@ -77,7 +93,7 @@ model · run-state · git-branch · context-used · context-remaining · session
 
 ## Compatibility
 
-- Node.js `>=22.12`
+- Node.js `>=22.19`
 - Pi host environment with `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui`
 - Tested in this repo against `@earendil-works/pi-coding-agent@0.78.x` and `@earendil-works/pi-tui@0.78.x`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-vault/pi-status",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Pi extension that replaces the default status with a Codex-like status",
   "author": "Lanh Hoang <lanhhoang@users.noreply.github.com>",
@@ -29,19 +29,19 @@
   },
   "pi": {
     "extensions": [
-      "./src/index.ts",
-      "node_modules/@pi-vault/pi-usage/src/index.ts"
+      "./src/index.ts"
     ]
   },
   "engines": {
-    "node": ">=22.12"
+    "node": ">=22.19"
   },
   "files": [
     "src",
+    "docs/assets",
     "README.md"
   ],
   "dependencies": {
-    "@pi-vault/pi-usage": "^0.1.1"
+    "@pi-vault/pi-usage": "^0.2.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/{config.ts → core/config.ts}

@@ -11,14 +11,11 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import {
   DEFAULT_SEGMENTS,
+  isKnownSegment,
+  type PiStatusConfig,
   type StatusFilter,
   type StatusLineSegmentId,
-} from "./render.ts";
-
-export type PiStatusConfig = {
-  segments: StatusLineSegmentId[];
-  filter: StatusFilter;
-};
+} from "../shared/types.ts";
 
 export type ConfigLoadResult = {
   config: PiStatusConfig;
@@ -30,25 +27,6 @@ export const DEFAULT_CONFIG: PiStatusConfig = {
   filter: { mode: "all", hidden: [] },
 };
 
-const KNOWN_SEGMENTS = new Set<StatusLineSegmentId>([
-  "model",
-  "model-with-reasoning",
-  "project-name",
-  "current-dir",
-  "git-branch",
-  "run-state",
-  "context-remaining",
-  "context-used",
-  "context-window-size",
-  "used-tokens",
-  "total-input-tokens",
-  "total-output-tokens",
-  "session-id",
-  "five-hour-limit",
-  "weekly-limit",
-  "extension-statuses",
-]);
-
 function cloneDefaultConfig(): PiStatusConfig {
   return {
     segments: [...DEFAULT_CONFIG.segments],
@@ -76,11 +54,10 @@ export function normalizeSegments(input: unknown): StatusLineSegmentId[] {
 
   for (const value of input) {
     if (typeof value !== "string") continue;
-    if (!KNOWN_SEGMENTS.has(value as StatusLineSegmentId)) continue;
-    const id = value as StatusLineSegmentId;
-    if (seen.has(id)) continue;
-    seen.add(id);
-    out.push(id);
+    if (!isKnownSegment(value)) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    out.push(value);
   }
 
   return out;
@@ -103,8 +80,9 @@ function normalizeFilterValues(input: unknown): string[] {
 }
 
 export function normalizeStatusFilter(input: unknown): StatusFilter {
-  if (!input || typeof input !== "object" || Array.isArray(input))
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
     return { mode: "all", hidden: [] };
+  }
   const mode = (input as { mode?: unknown }).mode;
 
   if (mode === "all") {
@@ -127,8 +105,9 @@ export function normalizeStatusFilter(input: unknown): StatusFilter {
 function readJsonObject(path: string): Record<string, unknown> | null {
   try {
     const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
       return null;
+    }
     return parsed as Record<string, unknown>;
   } catch {
     return null;
@@ -141,24 +120,17 @@ type SettingsFileState =
   | { exists: true; malformed: true };
 
 function readSettingsFileState(path: string): SettingsFileState {
-  if (!existsSync(path)) {
-    return { exists: false, value: {} };
-  }
-
+  if (!existsSync(path)) return { exists: false, value: {} };
   const parsed = readJsonObject(path);
-  if (parsed) {
-    return { exists: true, value: parsed };
-  }
-
+  if (parsed) return { exists: true, value: parsed };
   return { exists: true, malformed: true };
 }
 
 function normalizePiStatus(input: unknown): PiStatusConfig {
-  if (!input || typeof input !== "object" || Array.isArray(input))
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
     return cloneDefaultConfig();
-  const segments = normalizeSegments(
-    (input as { segments?: unknown }).segments,
-  );
+  }
+  const segments = normalizeSegments((input as { segments?: unknown }).segments);
   const filter = normalizeStatusFilter((input as { filter?: unknown }).filter);
   return {
     segments: segments.length > 0 ? segments : [...DEFAULT_SEGMENTS],
@@ -167,18 +139,12 @@ function normalizePiStatus(input: unknown): PiStatusConfig {
 }
 
 function mergePiStatus(globalValue: unknown, projectValue: unknown): unknown {
-  if (
-    !globalValue ||
-    typeof globalValue !== "object" ||
-    Array.isArray(globalValue)
-  )
+  if (!globalValue || typeof globalValue !== "object" || Array.isArray(globalValue)) {
     return projectValue ?? globalValue;
-  if (
-    !projectValue ||
-    typeof projectValue !== "object" ||
-    Array.isArray(projectValue)
-  )
+  }
+  if (!projectValue || typeof projectValue !== "object" || Array.isArray(projectValue)) {
     return globalValue;
+  }
   const g = globalValue as Record<string, unknown>;
   const p = projectValue as Record<string, unknown>;
   const merged: Record<string, unknown> = { ...g, ...p };
@@ -186,12 +152,8 @@ function mergePiStatus(globalValue: unknown, projectValue: unknown): unknown {
   const gFilter = g.filter;
   const pFilter = p.filter;
   if (
-    gFilter &&
-    typeof gFilter === "object" &&
-    !Array.isArray(gFilter) &&
-    pFilter &&
-    typeof pFilter === "object" &&
-    !Array.isArray(pFilter)
+    gFilter && typeof gFilter === "object" && !Array.isArray(gFilter) &&
+    pFilter && typeof pFilter === "object" && !Array.isArray(pFilter)
   ) {
     merged.filter = {
       ...(gFilter as Record<string, unknown>),
@@ -240,9 +202,7 @@ export function saveConfigToSettings(
 
   const targetState = readSettingsFileState(path);
   if ("malformed" in targetState) {
-    throw new Error(
-      `Refusing to write malformed or non-object settings file: ${path}`,
-    );
+    throw new Error(`Refusing to write malformed or non-object settings file: ${path}`);
   }
 
   const base = targetState.value;

package/src/core/usage-runtime.ts

@@ -0,0 +1,62 @@
+import {
+  USAGE_CORE_READY_EVENT,
+  USAGE_CORE_REQUEST_EVENT,
+  USAGE_CORE_UPDATE_CURRENT_EVENT,
+} from "@pi-vault/pi-usage/events";
+import type { UsageCoreState } from "@pi-vault/pi-usage/types";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+function isUsageCoreState(value: unknown): value is UsageCoreState {
+  return Boolean(value && typeof value === "object");
+}
+
+export function createUsageRuntime(pi: ExtensionAPI) {
+  let available = false;
+  let state: UsageCoreState | undefined;
+  let onChange: (() => void) | undefined;
+
+  const acceptPayload = (payload: unknown): void => {
+    if (!payload || typeof payload !== "object") return;
+    const maybe = payload as { state?: unknown };
+    const next = maybe.state ?? payload;
+    if (!isUsageCoreState(next)) return;
+    state = next;
+    available = true;
+    onChange?.();
+  };
+
+  const requestCurrent = (): void => {
+    pi.events.emit(USAGE_CORE_REQUEST_EVENT, {
+      type: "current",
+      reply(payload: unknown) {
+        acceptPayload(payload);
+      },
+    });
+  };
+
+  const unsubscribeReady = pi.events.on(USAGE_CORE_READY_EVENT, acceptPayload);
+  const unsubscribeUpdate = pi.events.on(
+    USAGE_CORE_UPDATE_CURRENT_EVENT,
+    acceptPayload,
+  );
+
+  requestCurrent();
+
+  return {
+    getAvailable(): boolean {
+      return available;
+    },
+    getState(): UsageCoreState | undefined {
+      return state;
+    },
+    setOnChange(listener: (() => void) | undefined): void {
+      onChange = listener;
+    },
+    requestCurrent,
+    dispose(): void {
+      onChange = undefined;
+      unsubscribeReady();
+      unsubscribeUpdate();
+    },
+  };
+}

package/src/index.ts

@@ -2,20 +2,15 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import {
-  USAGE_CORE_READY_EVENT,
-  USAGE_CORE_REQUEST_EVENT,
-  USAGE_CORE_UPDATE_CURRENT_EVENT,
-} from "@pi-vault/pi-usage/events";
-import type { UsageCoreState } from "@pi-vault/pi-usage/types";
 import {
   loadConfig,
   saveConfigToSettings,
-  type PiStatusConfig,
-} from "./config.ts";
-import { buildFooterLine } from "./render.ts";
-import { createStatuslineEditor } from "./ui/statusline-editor.ts";
-import { fromPiTheme, noTheme, type StatuslineMenuTheme } from "./ui/statusline-theme.ts";
+} from "./core/config.ts";
+import { createUsageRuntime } from "./core/usage-runtime.ts";
+import type { PiStatusConfig } from "./shared/types.ts";
+import { createStatusLineEditor } from "./tui/editor.ts";
+import { buildFooterLine } from "./tui/render.ts";
+import { fromPiTheme, noTheme, type StatusLineTheme } from "./tui/theme.ts";
 
 type FooterComponent = {
   render: (width: number) => string[];
@@ -35,21 +30,14 @@ type FooterFactory = (
   footerData: FooterDataLike,
 ) => FooterComponent;
 
-// Used only to suppress the live footer while a custom UI (e.g. /statusline)
-// is open. Renders no lines and is a no-op otherwise.
 const EMPTY_FOOTER_FACTORY: FooterFactory = () => ({
-  render(_width: number): string[] {
+  render(): string[] {
     return [];
   },
   invalidate(): void {},
   dispose(): void {},
 });
 
-// `ctx.ui.custom(...)` is expected to hand us a live Pi theme, but the
-// runtime contract is loose and the theme may be missing in some test or
-// boot contexts. We only adapt it when both `fg` and `bold` are callable so
-// the editor always gets a well-formed `StatuslineMenuTheme` and never has
-// to defend against partial themes at render time.
 function isLiveTheme(value: unknown): boolean {
   if (!value || typeof value !== "object") return false;
   const candidate = value as { fg?: unknown; bold?: unknown };
@@ -66,8 +54,7 @@ function aggregateBranchTotals(ctx: ExtensionContext): {
 
   for (const entry of branch ?? []) {
     if (!entry || typeof entry !== "object") continue;
-    const type = (entry as { type?: unknown }).type;
-    if (type !== "message") continue;
+    if ((entry as { type?: unknown }).type !== "message") continue;
     const message = (
       entry as {
         message?: {
@@ -81,8 +68,7 @@ function aggregateBranchTotals(ctx: ExtensionContext): {
     if (!usage) continue;
     if (typeof usage.input === "number") totals.input += usage.input;
     if (typeof usage.output === "number") totals.output += usage.output;
-    if (typeof usage.totalTokens === "number")
-      totals.totalTokens += usage.totalTokens;
+    if (typeof usage.totalTokens === "number") totals.totalTokens += usage.totalTokens;
   }
 
   return totals;
@@ -92,38 +78,28 @@ export default function createExtension(pi: ExtensionAPI): void {
   let runtimeConfig: PiStatusConfig = loadConfig().config;
   let currentCtx: ExtensionContext | undefined;
   let requestRender: (() => void) | undefined;
-  let usageState: UsageCoreState | undefined;
   let lastGitBranch: string | null = null;
   let lastExtensionStatuses = new Map<string, string>();
 
+  const usageRuntime = createUsageRuntime(pi);
+
   function refreshRuntimeConfig(cwd?: string): void {
     runtimeConfig = loadConfig(cwd ? { cwd } : undefined).config;
   }
 
-  function acceptUsageState(payload: unknown): void {
-    if (!payload || typeof payload !== "object") return;
-    const maybe = payload as { state?: unknown };
-    const next =
-      maybe.state && typeof maybe.state === "object" ? maybe.state : payload;
-    usageState = next as UsageCoreState;
-    requestRender?.();
-  }
-
   function installFooter(ctx: ExtensionContext): void {
     if (!ctx.hasUI) return;
 
     const factory: FooterFactory = (tui, theme, footerData) => {
       requestRender = () => tui.requestRender?.();
-      const unsubscribe = footerData.onBranchChange?.(() =>
-        tui.requestRender?.(),
-      );
+      usageRuntime.setOnChange(requestRender);
+      const unsubscribe = footerData.onBranchChange?.(() => tui.requestRender?.());
 
       return {
         dispose() {
           unsubscribe?.();
-          if (requestRender === tui.requestRender) {
-            requestRender = undefined;
-          }
+          if (requestRender === tui.requestRender) requestRender = undefined;
+          usageRuntime.setOnChange(requestRender);
         },
         invalidate() {
           requestRender?.();
@@ -131,9 +107,7 @@ export default function createExtension(pi: ExtensionAPI): void {
         render(width: number) {
           const activeCtx = currentCtx ?? ctx;
           lastGitBranch = footerData.getGitBranch();
-          lastExtensionStatuses = new Map(
-            footerData.getExtensionStatuses().entries(),
-          );
+          lastExtensionStatuses = new Map(footerData.getExtensionStatuses().entries());
           const line = buildFooterLine(
             {
               model: activeCtx.model,
@@ -148,7 +122,7 @@ export default function createExtension(pi: ExtensionAPI): void {
               contextUsage: activeCtx.getContextUsage(),
               branchTotals: aggregateBranchTotals(activeCtx),
               sessionId: activeCtx.sessionManager.getSessionId(),
-              usageState,
+              usageState: usageRuntime.getState(),
               extensionStatuses: lastExtensionStatuses,
               filter: runtimeConfig.filter,
               segments: runtimeConfig.segments,
@@ -156,7 +130,6 @@ export default function createExtension(pi: ExtensionAPI): void {
             theme,
             width,
           );
-
           return [line];
         },
       };
@@ -166,8 +139,7 @@ export default function createExtension(pi: ExtensionAPI): void {
   }
 
   function installEmptyFooter(ctx: ExtensionContext): void {
-    if (!ctx.hasUI) return;
-    ctx.ui.setFooter(EMPTY_FOOTER_FACTORY as never);
+    if (ctx.hasUI) ctx.ui.setFooter(EMPTY_FOOTER_FACTORY as never);
   }
 
   function refresh(ctx: ExtensionContext): void {
@@ -176,27 +148,6 @@ export default function createExtension(pi: ExtensionAPI): void {
     requestRender?.();
   }
 
-  const unsubscribeUsageReady = pi.events.on(
-    USAGE_CORE_READY_EVENT,
-    (payload: unknown) => {
-      acceptUsageState(payload);
-    },
-  );
-
-  const unsubscribeUsageUpdate = pi.events.on(
-    USAGE_CORE_UPDATE_CURRENT_EVENT,
-    (payload: unknown) => {
-      acceptUsageState(payload);
-    },
-  );
-
-  pi.events.emit(USAGE_CORE_REQUEST_EVENT, {
-    type: "current",
-    reply(payload: unknown) {
-      acceptUsageState(payload);
-    },
-  });
-
   pi.registerCommand("statusline", {
     description: "Configure statusline segments and extension-status filters",
     handler: async (_args, ctx) => {
@@ -205,44 +156,39 @@ export default function createExtension(pi: ExtensionAPI): void {
         return;
       }
 
-      const discovered = [...lastExtensionStatuses.keys()].sort((a, b) =>
-        a.localeCompare(b),
-      );
+      const discovered = [...lastExtensionStatuses.keys()].sort((a, b) => a.localeCompare(b));
 
       let result: PiStatusConfig | null = null;
       try {
         installEmptyFooter(ctx);
-        result = await ctx.ui.custom<PiStatusConfig | null>(
-          (tui, theme, _keys, done) => {
-            const activeCtx = currentCtx ?? ctx;
-            const menuTheme: StatuslineMenuTheme = isLiveTheme(theme)
-              ? fromPiTheme(theme)
-              : noTheme;
-            return createStatuslineEditor({
-              config: runtimeConfig,
-              discoveredStatuses: discovered,
-              previewInput: {
-                model: activeCtx.model,
-                cwd: activeCtx.cwd,
-                thinkingLevel: String(pi.getThinkingLevel()),
-                gitBranch: lastGitBranch,
-                runState: !activeCtx.isIdle()
-                  ? "busy"
-                  : activeCtx.hasPendingMessages()
-                    ? "queued"
-                    : "idle",
-                contextUsage: activeCtx.getContextUsage(),
-                branchTotals: aggregateBranchTotals(activeCtx),
-                sessionId: activeCtx.sessionManager.getSessionId(),
-                usageState,
-                extensionStatuses: lastExtensionStatuses,
-              },
-              theme: menuTheme,
-              done,
-              requestRender: () => tui.requestRender?.(),
-            });
-          },
-        );
+        result = await ctx.ui.custom<PiStatusConfig | null>((tui, theme, _keys, done) => {
+          const activeCtx = currentCtx ?? ctx;
+          const menuTheme: StatusLineTheme = isLiveTheme(theme) ? fromPiTheme(theme) : noTheme;
+          return createStatusLineEditor({
+            config: runtimeConfig,
+            discoveredStatuses: discovered,
+            previewInput: {
+              model: activeCtx.model,
+              cwd: activeCtx.cwd,
+              thinkingLevel: String(pi.getThinkingLevel()),
+              gitBranch: lastGitBranch,
+              runState: !activeCtx.isIdle()
+                ? "busy"
+                : activeCtx.hasPendingMessages()
+                  ? "queued"
+                  : "idle",
+              contextUsage: activeCtx.getContextUsage(),
+              branchTotals: aggregateBranchTotals(activeCtx),
+              sessionId: activeCtx.sessionManager.getSessionId(),
+              usageState: usageRuntime.getState(),
+              extensionStatuses: lastExtensionStatuses,
+            },
+            theme: menuTheme,
+            done,
+            requestRender: () => tui.requestRender?.(),
+            usageAvailable: usageRuntime.getAvailable(),
+          });
+        });
       } finally {
         installFooter(ctx);
       }
@@ -254,16 +200,14 @@ export default function createExtension(pi: ExtensionAPI): void {
         runtimeConfig = result;
         requestRender?.();
       } catch (error) {
-        const message =
-          error instanceof Error
-            ? error.message
-            : "Failed to save statusline settings";
+        const message = error instanceof Error ? error.message : "Failed to save statusline settings";
         ctx.ui.notify(message, "warning");
       }
     },
   });
 
   pi.on("session_start", (_event, ctx) => {
+    usageRuntime.requestCurrent();
     refreshRuntimeConfig(ctx.cwd);
     currentCtx = ctx;
     installFooter(ctx);
@@ -286,8 +230,7 @@ export default function createExtension(pi: ExtensionAPI): void {
   pi.on("session_shutdown", (_event, ctx) => {
     currentCtx = undefined;
     requestRender = undefined;
-    unsubscribeUsageReady();
-    unsubscribeUsageUpdate();
+    usageRuntime.setOnChange(undefined);
     if (ctx.hasUI) ctx.ui.setFooter(undefined);
   });
 }

package/src/shared/types.ts

@@ -0,0 +1,63 @@
+export type StatusLineSegmentId =
+  | "model"
+  | "model-with-reasoning"
+  | "project-name"
+  | "current-dir"
+  | "git-branch"
+  | "run-state"
+  | "context-remaining"
+  | "context-used"
+  | "context-window-size"
+  | "used-tokens"
+  | "total-input-tokens"
+  | "total-output-tokens"
+  | "session-id"
+  | "five-hour-limit"
+  | "weekly-limit"
+  | "extension-statuses";
+
+export type StatusFilter =
+  | { mode: "all"; hidden: string[] }
+  | { mode: "only"; shown: string[] };
+
+export type PiStatusConfig = {
+  segments: StatusLineSegmentId[];
+  filter: StatusFilter;
+};
+
+export const KNOWN_SEGMENTS: readonly StatusLineSegmentId[] = [
+  "model",
+  "model-with-reasoning",
+  "project-name",
+  "current-dir",
+  "git-branch",
+  "run-state",
+  "context-remaining",
+  "context-used",
+  "context-window-size",
+  "used-tokens",
+  "total-input-tokens",
+  "total-output-tokens",
+  "session-id",
+  "five-hour-limit",
+  "weekly-limit",
+  "extension-statuses",
+] as const;
+
+export const DEFAULT_SEGMENTS: readonly StatusLineSegmentId[] = [
+  "model-with-reasoning",
+  "current-dir",
+] as const;
+
+export const USAGE_SEGMENTS = new Set<StatusLineSegmentId>([
+  "five-hour-limit",
+  "weekly-limit",
+]);
+
+export function isKnownSegment(value: string): value is StatusLineSegmentId {
+  return (KNOWN_SEGMENTS as readonly string[]).includes(value);
+}
+
+export function isUsageSegment(id: StatusLineSegmentId): boolean {
+  return USAGE_SEGMENTS.has(id);
+}