@hk_net/pi-usage-bars 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## Unreleased
 
+## [0.5.0] - 2026-08-22
+
+### Added
+
+- Added a `--usage` extension flag that prints one JSON line for the active provider and exits, providing a non-interactive Pi loader, credential, and endpoint smoke test.
+
+### Changed
+
+- Raised the minimum supported Pi version from 0.81.1 to 0.84.2; older Pi releases are no longer claimed or tested as compatible.
+- Namespaced the footer status and inter-extension usage update event to avoid collisions with other Pi extensions. **Breaking for event consumers:** listeners using the previous undocumented `usage:update` event must switch to `@hk_net/pi-usage-bars:update`.
+- Bounded the `/usage` provider viewport, expanded only the selected provider, and added the configured page-up/page-down navigation bindings for smaller terminals.
+- Removed redundant active-model checks on every turn in favor of Pi's `session_start` and `model_select` lifecycle events.
+- Cancelled an obsolete in-flight provider request immediately when the selected model provider changes, allowing the new provider to refresh without waiting for the old request timeout.
+- Isolated and documented the current Pi OAuth source-label compatibility check. Pi 0.84.2 exposes `AuthResult.source` as a human-readable label but no public typed credential discriminator, so Claude subscription detection must currently recognize the `"OAuth"` label.
+
+### Tests
+
+- Added lifecycle coverage for shutdown and replacement-session cancellation, repeated-start interval cleanup, `/usage` closure cancellation, model changes during active polling, and model-selection event wiring.
+
 ## [0.4.5] - 2026-08-22
 
 ### Changed

package/README.md

@@ -35,7 +35,7 @@ Google Gemini CLI and Google Antigravity are not supported because Pi removed th
 
 ## Requirements
 
-- Pi 0.81.1 or newer (tested with the current Pi 0.84.2 release)
+- Pi 0.84.2 or newer
 - Node.js 22.19 or newer when using the npm-distributed Pi CLI
 
 Authenticate providers through Pi's `/login` command. The extension resolves credentials through Pi's provider API; it does not read or write `auth.json` itself.
@@ -74,9 +74,19 @@ Usage refresh runs in interactive TUI sessions every two minutes. It does not ru
 
 ### `/usage`
 
-Run `/usage` to open a searchable list of configured supported providers.
+Run `/usage` to open a searchable list of configured supported providers. The selected provider's details are expanded; use the configured selection and page-navigation keybindings to browse the bounded list.
 
-![/usage command](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
+![/usage command]
+
+### `--usage`
+
+Pass `--usage` to print one JSON line for the active model provider and exit without opening the usage UI. This is also useful as a loader and credential smoke test:
+
+```powershell
+pi --no-extensions -e C:\hk\code\pi-usage-bars\extensions\usage-bars\index.ts --usage
+```
+
+The result has `status` set to `ok`, `unconfigured`, `unsupported`, or `error`. No credential is included in the output.(https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/usage-command.png)
 
 ## Endpoint configuration
 

package/docs/releasing.md

@@ -22,6 +22,14 @@ cd /path/to/pi-usage-bars
 scripts/release.sh X.Y.Z
 ```
 
+From Windows PowerShell, run the Bash workflow through WSL (replace the WSL path with your checkout):
+
+```powershell
+wsl bash -lc 'cd /mnt/c/path/to/pi-usage-bars && ./scripts/release.sh X.Y.Z'
+```
+
+The repository's `.gitattributes` keeps shell scripts on LF endings so they remain executable in WSL even when Git for Windows uses `core.autocrlf=true`.
+
 This **default command only prepares the release**. It deliberately stops before npm login or publication, so the pushed release commit can be reviewed first. The launcher first executes an immutable temporary copy of itself, so editing the script while a release is running cannot corrupt that run.
 
 Preparation:
@@ -39,6 +47,12 @@ After reviewing the prepared commit, stage it for browser approval:
 scripts/release.sh X.Y.Z stage
 ```
 
+From Windows PowerShell:
+
+```powershell
+wsl bash -lc 'cd /mnt/c/path/to/pi-usage-bars && ./scripts/release.sh X.Y.Z stage'
+```
+
 `stage` submits the package to npm's staged-publishing queue. It **does not publish live**, does not open a browser, and does not tag Git. If npm authentication is needed, run `npm login --auth-type=web` manually first; this only authenticates the CLI.
 
 In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the staged tarball, and click **Approve**. npm prompts for 2FA during approval. After npm shows the version as live, finalize the release:
@@ -47,6 +61,12 @@ In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the stag
 scripts/release.sh X.Y.Z finalize
 ```
 
+From Windows PowerShell:
+
+```powershell
+wsl bash -lc 'cd /mnt/c/path/to/pi-usage-bars && ./scripts/release.sh X.Y.Z finalize'
+```
+
 `finalize` refuses to run until the exact version is live in the npm registry. It then verifies registry metadata and creates/pushes the annotated Git tag. It never stages or publishes a package.
 
 Use `--yes` only for attended preparation:

package/extensions/usage-bars/index.ts

@@ -39,7 +39,9 @@ import {
 } from "./core";
 
 const POLL_INTERVAL_MS = 2 * 60 * 1000;
-const STATUS_KEY = "usage-bars";
+const EXTENSION_ID = "@hk_net/pi-usage-bars";
+const STATUS_KEY = EXTENSION_ID;
+const USAGE_UPDATE_EVENT = `${EXTENSION_ID}:update`;
 const PROVIDERS: readonly ProviderKey[] = [
   "codex",
   "claude",
@@ -123,6 +125,7 @@ class UsageSelectorComponent extends Container implements Focusable {
   private allItems: SubscriptionItem[] = [];
   private filteredItems: SubscriptionItem[] = [];
   private selectedIndex = 0;
+  private viewportStart = 0;
   private loading = true;
   private hint: "loading" | "ready" | "error" = "loading";
   private disposed = false;
@@ -215,6 +218,7 @@ class UsageSelectorComponent extends Container implements Focusable {
     });
     this.filteredItems = this.allItems;
     this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, this.filteredItems.length - 1));
+    this.ensureSelectedVisible();
   }
 
   private filterItems(query: string): void {
@@ -224,6 +228,34 @@ class UsageSelectorComponent extends Container implements Focusable {
           item.name.toLowerCase().includes(normalized) || item.provider.includes(normalized))
       : this.allItems;
     this.selectedIndex = Math.min(this.selectedIndex, Math.max(0, this.filteredItems.length - 1));
+    this.viewportStart = 0;
+    this.ensureSelectedVisible();
+  }
+
+  private viewportSize(): number {
+    // Leave room for the frame, search input, hints, and expanded details for
+    // the selected provider. Keeping the provider list bounded avoids pushing
+    // the custom UI beyond short terminal viewports.
+    return Math.max(1, Math.min(8, this.tui.terminal.rows - 14));
+  }
+
+  private ensureSelectedVisible(): void {
+    const size = this.viewportSize();
+    if (this.selectedIndex < this.viewportStart) this.viewportStart = this.selectedIndex;
+    if (this.selectedIndex >= this.viewportStart + size) {
+      this.viewportStart = this.selectedIndex - size + 1;
+    }
+    this.viewportStart = Math.max(0, Math.min(
+      this.viewportStart,
+      Math.max(0, this.filteredItems.length - size),
+    ));
+  }
+
+  private moveSelection(delta: number): void {
+    if (this.filteredItems.length === 0) return;
+    this.selectedIndex = Math.max(0, Math.min(this.filteredItems.length - 1, this.selectedIndex + delta));
+    this.ensureSelectedVisible();
+    this.refresh();
   }
 
   private renderBar(percent: number, width = 16): string {
@@ -239,6 +271,7 @@ class UsageSelectorComponent extends Container implements Focusable {
     const activeBadge = item.isActive ? theme.fg("success", " ✓") : "";
     const name = selected ? theme.fg("accent", theme.bold(item.name)) : item.name;
     this.listContainer.addChild(new Text(`${pointer}${name}${activeBadge}`, 0, 0));
+    if (!selected) return;
 
     const indent = "    ";
     if (item.data.error) {
@@ -323,7 +356,22 @@ class UsageSelectorComponent extends Container implements Focusable {
       this.listContainer.addChild(new Text(this.theme.fg("muted", "  No matching configured providers"), 0, 0));
       return;
     }
-    this.filteredItems.forEach((item, index) => this.renderItem(item, index === this.selectedIndex));
+    this.ensureSelectedVisible();
+    const size = this.viewportSize();
+    const end = Math.min(this.filteredItems.length, this.viewportStart + size);
+    if (this.viewportStart > 0) {
+      this.listContainer.addChild(new Text(this.theme.fg("dim", `  ↑ ${this.viewportStart} more`), 0, 0));
+    }
+    for (let index = this.viewportStart; index < end; index += 1) {
+      this.renderItem(this.filteredItems[index]!, index === this.selectedIndex);
+    }
+    if (end < this.filteredItems.length) {
+      this.listContainer.addChild(new Text(
+        this.theme.fg("dim", `  ↓ ${this.filteredItems.length - end} more`),
+        0,
+        0,
+      ));
+    }
   }
 
   private refresh(): void {
@@ -337,6 +385,7 @@ class UsageSelectorComponent extends Container implements Focusable {
         this.selectedIndex = this.selectedIndex === 0
           ? this.filteredItems.length - 1
           : this.selectedIndex - 1;
+        this.ensureSelectedVisible();
         this.refresh();
       }
       return;
@@ -346,10 +395,19 @@ class UsageSelectorComponent extends Container implements Focusable {
         this.selectedIndex = this.selectedIndex === this.filteredItems.length - 1
           ? 0
           : this.selectedIndex + 1;
+        this.ensureSelectedVisible();
         this.refresh();
       }
       return;
     }
+    if (this.keybindings.matches(keyData, "tui.select.pageUp")) {
+      this.moveSelection(-this.viewportSize());
+      return;
+    }
+    if (this.keybindings.matches(keyData, "tui.select.pageDown")) {
+      this.moveSelection(this.viewportSize());
+      return;
+    }
     if (
       this.keybindings.matches(keyData, "tui.select.cancel") ||
       this.keybindings.matches(keyData, "tui.select.confirm")
@@ -381,6 +439,12 @@ interface UsageState extends UsageByProvider {
 }
 
 export default function (pi: ExtensionAPI): void {
+  pi.registerFlag("usage", {
+    description: "Print one-line usage for the active provider and exit",
+    type: "boolean",
+    default: false,
+  });
+
   const endpoints = resolveUsageEndpoints();
   const state: UsageState = {
     codex: null,
@@ -403,6 +467,7 @@ export default function (pi: ExtensionAPI): void {
   let pollQueued = false;
   let currentContext: ExtensionContext | undefined;
   let sessionController: AbortController | undefined;
+  let providerPollController: AbortController | undefined;
 
   const renderPercent = (theme: Theme, value: number) => {
     const percent = clampPercent(value);
@@ -490,12 +555,20 @@ export default function (pi: ExtensionAPI): void {
     const previous = state.activeProvider;
     state.activeProvider = detectProvider(model);
     if (previous !== state.activeProvider) {
+      providerPollController?.abort();
       updateStatus();
       return true;
     }
     return false;
   }
 
+  function isClaudeSubscriptionAuth(source: string | undefined): boolean {
+    // Pi 0.84 exposes AuthResult.source as a human-readable label rather than a
+    // credential-type discriminator. Keep the compatibility assumption in one
+    // place until ModelRegistry exposes the resolved credential type directly.
+    return source === "OAuth";
+  }
+
   async function resolveCredential(ctx: ExtensionContext, provider: ProviderKey): Promise<CredentialResolution> {
     const providerId = providerToPiProviderId(provider);
     if (!ctx.modelRegistry.getProvider(providerId)) return {};
@@ -504,7 +577,7 @@ export default function (pi: ExtensionAPI): void {
 
     try {
       const resolved = await ctx.modelRegistry.getProviderAuth(providerId);
-      if (provider === "claude" && resolved?.source !== "OAuth") return {};
+      if (provider === "claude" && !isClaudeSubscriptionAuth(resolved?.source)) return {};
       const token = resolved?.auth.apiKey;
       if (token) return { token };
       // Some OAuth flows (e.g. kimi-coding) expose the token only as a Bearer
@@ -563,18 +636,25 @@ export default function (pi: ExtensionAPI): void {
 
   async function runPoll(): Promise<void> {
     const ctx = currentContext;
-    const signal = sessionController?.signal;
+    const sessionSignal = sessionController?.signal;
     const provider = state.activeProvider;
-    if (!ctx || !signal || signal.aborted || ctx.mode !== "tui" || !provider) {
+    if (!ctx || !sessionSignal || sessionSignal.aborted || ctx.mode !== "tui" || !provider) {
       updateStatus();
       return;
     }
 
-    await fetchProvider(ctx, provider, signal);
-    if (signal.aborted) return;
-    const data = state[provider];
-    if (data && !data.error) pi.events.emit("usage:update", { provider, ...data });
-    updateStatus();
+    const controller = new AbortController();
+    providerPollController = controller;
+    const signal = AbortSignal.any([sessionSignal, controller.signal]);
+    try {
+      await fetchProvider(ctx, provider, signal);
+      if (signal.aborted) return;
+      const data = state[provider];
+      if (data && !data.error) pi.events.emit(USAGE_UPDATE_EVENT, { provider, ...data });
+      updateStatus();
+    } finally {
+      if (providerPollController === controller) providerPollController = undefined;
+    }
   }
 
   async function poll(): Promise<void> {
@@ -611,7 +691,7 @@ export default function (pi: ExtensionAPI): void {
     return results;
   }
 
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
     currentContext = ctx;
     sessionController?.abort();
     sessionController = new AbortController();
@@ -619,6 +699,25 @@ export default function (pi: ExtensionAPI): void {
 
     if (pollTimer) clearInterval(pollTimer);
     pollTimer = undefined;
+
+    if (pi.getFlag("usage") === true) {
+      const provider = state.activeProvider;
+      if (!provider) {
+        console.log(JSON.stringify({ extension: EXTENSION_ID, status: "unsupported", provider: ctx.model?.provider }));
+      } else {
+        await fetchProvider(ctx, provider, sessionController.signal);
+        const data = state[provider];
+        console.log(JSON.stringify({
+          extension: EXTENSION_ID,
+          provider,
+          status: !data ? "unconfigured" : data.error ? "error" : "ok",
+          ...(data ?? {}),
+        }));
+      }
+      ctx.shutdown();
+      return;
+    }
+
     if (ctx.mode !== "tui") return;
 
     updateStatus();
@@ -627,6 +726,8 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("session_shutdown", (_event, ctx) => {
+    providerPollController?.abort();
+    providerPollController = undefined;
     sessionController?.abort();
     sessionController = undefined;
     pollQueued = false;
@@ -636,11 +737,6 @@ export default function (pi: ExtensionAPI): void {
     currentContext = undefined;
   });
 
-  pi.on("turn_start", (_event, ctx) => {
-    currentContext = ctx;
-    if (updateProviderFrom(ctx.model)) void poll();
-  });
-
   pi.on("model_select", (event, ctx) => {
     currentContext = ctx;
     updateProviderFrom(event.model);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hk_net/pi-usage-bars",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Quota, balance, and spend indicators for current Pi providers",
   "keywords": [
     "pi-package",