opencode-usage-report 0.1.0

package/src/tui-format.ts

@@ -0,0 +1,201 @@
+/**
+ * Pure formatting helpers for the TUI sidebar usage panel. No JSX, no Solid
+ * imports (the only module dependency is the shared `DEFAULT_OPTIONS`).
+ */
+import { DEFAULT_OPTIONS } from "./report.js";
+
+export type ToneName = "success" | "warning" | "error" | "textMuted";
+
+export const BAR_MIN_WIDTH = 4;
+export const BAR_MAX_WIDTH = 40;
+export const DEFAULT_BAR_WIDTH = 14;
+export const MIN_REFRESH_INTERVAL_SECONDS = 5;
+export const MAX_REFRESH_INTERVAL_SECONDS = 3600;
+export const DEFAULT_REFRESH_INTERVAL_SECONDS = 60;
+
+/**
+ * Renders a fixed-width progress bar. `percent` is clamped to 0-100 and rounded
+ * to the nearest filled cell; `null` (or any non-finite value) renders an empty
+ * bar. Width is floored and clamped to 4..40 cells so it can never throw or
+ * allocate an unbounded string.
+ */
+export function bar(percent: number | null, width = DEFAULT_BAR_WIDTH): string {
+  const requested = Number.isFinite(width) ? Math.floor(width) : DEFAULT_BAR_WIDTH;
+  const w = Math.min(BAR_MAX_WIDTH, Math.max(BAR_MIN_WIDTH, requested));
+  if (percent === null || !Number.isFinite(percent)) return "░".repeat(w);
+  const clamped = Math.min(100, Math.max(0, percent));
+  const filled = Math.round((clamped / 100) * w);
+  return "█".repeat(filled) + "░".repeat(w - filled);
+}
+
+/**
+ * Maps a window's usage to a theme color name. Rate-limited/frozen windows are
+ * always an error, unknown percentages are muted, and the remaining bands are
+ * 80%+ (error), 50%+ (warning) and everything below (success).
+ */
+export function toneFor(
+  percent: number | null,
+  status: "ok" | "rate-limited" | "frozen" | "unknown",
+): ToneName {
+  if (status === "rate-limited" || status === "frozen") return "error";
+  if (percent === null || !Number.isFinite(percent)) return "textMuted";
+  if (percent >= 80) return "error";
+  if (percent >= 50) return "warning";
+  return "success";
+}
+
+/**
+ * Compact countdown to an ISO reset time. Returns `null` for missing/invalid
+ * input, `"now"` when less than a minute remains, and otherwise the largest
+ * non-zero day/hour/minute units (e.g. `"4d 9h 33m"`, `"3h 33m"`, `"12m"`).
+ */
+export function countdown(resetsAt: string | null, now: Date): string | null {
+  if (resetsAt === null) return null;
+  const target = Date.parse(resetsAt);
+  if (!Number.isFinite(target)) return null;
+  const deltaMs = target - now.getTime();
+  if (!Number.isFinite(deltaMs) || deltaMs < 60_000) return "now";
+
+  const totalMinutes = Math.floor(deltaMs / 60_000);
+  const totalHours = Math.floor(totalMinutes / 60);
+  const totalDays = Math.floor(totalHours / 24);
+  const days = totalDays;
+  const hours = totalHours % 24;
+  const minutes = totalMinutes % 60;
+
+  const parts: string[] = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  return parts.length > 0 ? parts.join(" ") : "now";
+}
+
+/** Human label for a window kind, falling back to the provider-supplied label. */
+export function windowLabel(
+  kind: "5h" | "daily" | "weekly" | "monthly" | "other",
+  fallback: string,
+): string {
+  switch (kind) {
+    case "5h":
+      return "5h limit";
+    case "daily":
+      return "Daily limit";
+    case "weekly":
+      return "Weekly limit";
+    case "monthly":
+      return "Monthly limit";
+    default:
+      return fallback;
+  }
+}
+
+/**
+ * Prefers a percentage, then used/limit, then a lone used count, then a dash.
+ * Fields are treated as unknown so `undefined` (or non-number junk) never
+ * reaches `toLocaleString()`.
+ */
+export function percentText(w: {
+  usedPercent?: number | null;
+  used?: number | null;
+  limit?: number | null;
+  source?: string;
+}): string {
+  const usedPercent = w.usedPercent;
+  if (typeof usedPercent === "number" && Number.isFinite(usedPercent)) {
+    return `${Math.round(usedPercent)}%`;
+  }
+  const used = w.used;
+  const limit = w.limit;
+  const usedIsNumber = typeof used === "number" && Number.isFinite(used);
+  const limitIsNumber = typeof limit === "number" && Number.isFinite(limit);
+  if (usedIsNumber && limitIsNumber) {
+    return `${used.toLocaleString()}/${limit.toLocaleString()}`;
+  }
+  if (usedIsNumber) {
+    return `~${used.toLocaleString()}`;
+  }
+  return "—";
+}
+
+/**
+ * Compact age of an ISO timestamp relative to `now` (e.g. `"14m"`, `"2h"`,
+ * `"3d"`). `null`/invalid input yields `null`; future timestamps floor to `"0s"`.
+ */
+export function formatAge(iso: string | null, now: Date): string | null {
+  if (iso === null) return null;
+  const then = Date.parse(iso);
+  if (!Number.isFinite(then)) return null;
+  const ageMs = Math.max(0, now.getTime() - then);
+
+  const seconds = Math.floor(ageMs / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+export interface ResolvedTuiOptions {
+  providers?: string[];
+  cacheTtlSeconds: number;
+  thresholdPercent: number;
+  refreshIntervalSeconds: number;
+  barWidth: number;
+}
+
+/** Coerces a loosely-typed value into a finite number, or null. */
+function toFiniteNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+/**
+ * Defensive option coercion; malformed values fall back to defaults.
+ * `barWidth` is floored and clamped to 4..40; `refreshIntervalSeconds` is
+ * rounded and clamped to 5..3600 so the timer can never hot-loop or overflow.
+ */
+export function coerceTuiOptions(
+  raw: Record<string, unknown> | undefined,
+): ResolvedTuiOptions {
+  const opts: ResolvedTuiOptions = {
+    cacheTtlSeconds: DEFAULT_OPTIONS.cacheTtlSeconds,
+    thresholdPercent: DEFAULT_OPTIONS.thresholdPercent,
+    refreshIntervalSeconds: DEFAULT_REFRESH_INTERVAL_SECONDS,
+    barWidth: DEFAULT_BAR_WIDTH,
+  };
+  if (raw === undefined) return opts;
+
+  if (Array.isArray(raw.providers)) {
+    const ids = raw.providers.filter((id): id is string => typeof id === "string");
+    if (ids.length > 0) opts.providers = ids;
+  } else if (raw.providers === null) {
+    opts.providers = undefined;
+  }
+
+  const ttl = toFiniteNumber(raw.cacheTtlSeconds);
+  if (ttl !== null && ttl >= 0) opts.cacheTtlSeconds = ttl;
+
+  const threshold = toFiniteNumber(raw.thresholdPercent);
+  if (threshold !== null) opts.thresholdPercent = threshold;
+
+  const interval = toFiniteNumber(raw.refreshIntervalSeconds);
+  if (interval !== null) {
+    opts.refreshIntervalSeconds = Math.min(
+      MAX_REFRESH_INTERVAL_SECONDS,
+      Math.max(MIN_REFRESH_INTERVAL_SECONDS, Math.round(interval)),
+    );
+  }
+
+  const width = toFiniteNumber(raw.barWidth);
+  if (width !== null) {
+    opts.barWidth = Math.min(BAR_MAX_WIDTH, Math.max(BAR_MIN_WIDTH, Math.floor(width)));
+  }
+
+  return opts;
+}

package/src/tui.tsx

@@ -0,0 +1,244 @@
+/** @jsxImportSource @opentui/solid */
+import type {
+  TuiPlugin,
+  TuiPluginApi,
+  TuiPluginModule,
+  TuiSlotPlugin,
+} from "@opencode-ai/plugin/tui";
+import { For, createSignal } from "solid-js";
+import { DEFAULT_OPTIONS, collectReports } from "./report.js";
+import {
+  bar,
+  coerceTuiOptions,
+  countdown,
+  percentText,
+  toneFor,
+  windowLabel,
+} from "./tui-format.js";
+import type { ProviderReport, WindowKind } from "./types.js";
+
+type Theme = TuiPluginApi["theme"]["current"];
+type ThemeColor = Theme["text"];
+
+interface Segment {
+  text: string;
+  fg: ThemeColor;
+  bold?: boolean;
+}
+
+interface Line {
+  segments: Segment[];
+}
+
+const NAMED_WIDTH = 14;
+const EXTRAS_MAX_LENGTH = 80;
+
+/** Order windows for display; unknown kinds sort last. */
+const WINDOW_ORDER: Record<WindowKind, number> = {
+  "5h": 0,
+  weekly: 1,
+  monthly: 2,
+  daily: 3,
+  other: 4,
+};
+
+function windowRank(kind: WindowKind): number {
+  return WINDOW_ORDER[kind] ?? WINDOW_ORDER.other;
+}
+
+/** Collapses whitespace and truncates to a single-line label. */
+function clip(value: string, max = 60): string {
+  const single = value.replace(/\s+/g, " ").trim();
+  if (single.length <= max) return single;
+  return single.slice(0, Math.max(0, max - 1)) + "…";
+}
+
+/** Pads a label to a fixed width, truncating (with a trailing space) when long. */
+function alignLabel(label: string): string {
+  const text =
+    label.length > NAMED_WIDTH ? label.slice(0, NAMED_WIDTH - 1) + " " : label;
+  return text.padEnd(NAMED_WIDTH);
+}
+
+/** Flattens the current signal state into plain, pre-colored text lines. */
+function buildLines(
+  theme: Theme,
+  reports: ProviderReport[],
+  busy: boolean,
+  error: string | null,
+  now: Date,
+  barWidth: number,
+): Line[] {
+  const lines: Line[] = [];
+
+  if (error !== null) {
+    lines.push({
+      segments: [{ text: `api error: ${clip(error)}`, fg: theme.error }],
+    });
+  }
+
+  if (reports.length === 0 && busy) {
+    lines.push({
+      segments: [{ text: "loading…", fg: theme.textMuted }],
+    });
+  }
+
+  for (const report of reports) {
+    const nameColor = report.source === "error" ? theme.textMuted : theme.accent;
+    const segments: Segment[] = [{ text: report.displayName, fg: nameColor, bold: true }];
+    if (report.stale) segments.push({ text: " (stale)", fg: theme.textMuted });
+    if (report.source === "local-estimate") {
+      segments.push({ text: " (est)", fg: theme.textMuted });
+    }
+    lines.push({ segments });
+
+    if (report.source === "error") {
+      lines.push({
+        segments: [
+          { text: clip(report.error ?? "unknown error"), fg: theme.error },
+        ],
+      });
+      continue;
+    }
+
+    const windows = [...report.windows].sort(
+      (a, b) => windowRank(a.kind) - windowRank(b.kind),
+    );
+    for (const w of windows) {
+      const tone = toneFor(w.usedPercent, w.status);
+      const row: Segment[] = [
+        { text: alignLabel(windowLabel(w.kind, w.label)), fg: theme.textMuted },
+        { text: bar(w.usedPercent, barWidth), fg: theme[tone] },
+        { text: " ", fg: theme.text },
+        { text: percentText(w), fg: theme.text },
+      ];
+      const reset = countdown(w.resetsAt, now);
+      if (reset !== null) {
+        row.push({ text: ` resets in ${reset}`, fg: theme.textMuted });
+      }
+      lines.push({ segments: row });
+    }
+
+    for (const [key, value] of Object.entries(report.extras)) {
+      lines.push({
+        segments: [
+          { text: clip(`${key}: ${value}`, EXTRAS_MAX_LENGTH), fg: theme.textMuted },
+        ],
+      });
+    }
+  }
+
+  return lines;
+}
+
+export const tui: TuiPlugin = async (api, rawOptions) => {
+  const options = coerceTuiOptions(rawOptions);
+
+  const [reports, setReports] = createSignal<ProviderReport[]>([]);
+  const [inFlight, setInFlight] = createSignal(0);
+  const [error, setError] = createSignal<string | null>(null);
+  const [tick, setTick] = createSignal(Date.now());
+
+  const busy = (): boolean => inFlight() > 0;
+
+  let disposed = false;
+
+  const load = async (refresh = false): Promise<void> => {
+    if (disposed) return;
+    setInFlight((n) => n + 1);
+    try {
+      const result = await collectReports({
+        providers: options.providers,
+        refresh,
+        options: {
+          ...DEFAULT_OPTIONS,
+          cacheTtlSeconds: options.cacheTtlSeconds,
+          thresholdPercent: options.thresholdPercent,
+        },
+      });
+      if (disposed) return;
+      setReports(result);
+      setError(null);
+    } catch (err) {
+      if (disposed) return;
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setInFlight((n) => Math.max(0, n - 1));
+    }
+  };
+
+  // Single timer: refreshes data and advances countdowns.
+  const intervalMs = Math.max(1, Math.floor(options.refreshIntervalSeconds)) * 1000;
+  const timer = setInterval(() => {
+    setTick(Date.now());
+    void load();
+  }, intervalMs);
+
+  api.lifecycle.onDispose(() => {
+    disposed = true;
+    clearInterval(timer);
+  });
+
+  const offIdle = api.event.on("session.idle", () => {
+    setTick(Date.now());
+    void load();
+  });
+  api.lifecycle.onDispose(offIdle);
+
+  api.lifecycle.onDispose(
+    api.keymap.registerLayer({
+      commands: [
+        {
+          name: "usage.refresh",
+          title: "Usage: refresh now",
+          category: "Plugin",
+          namespace: "palette",
+          run: () => {
+            void load(true);
+          },
+        },
+      ],
+      bindings: [
+        { key: "ctrl+shift+u", cmd: "usage.refresh", desc: "Refresh usage panel" },
+      ],
+    }),
+  );
+
+  const slot: TuiSlotPlugin = {
+    order: 150,
+    slots: {
+      sidebar_content(ctx) {
+        const theme = ctx.theme.current;
+        return (
+          <box flexDirection="column">
+            <text fg={theme.text}>
+              <b>Usage</b>
+            </text>
+            <For
+              each={buildLines(theme, reports(), busy(), error(), new Date(tick()), options.barWidth)}
+            >
+              {(line) => (
+                <text>
+                  {line.segments.map((seg) =>
+                    seg.bold ? (
+                      <b style={{ fg: seg.fg }}>{seg.text}</b>
+                    ) : (
+                      <span style={{ fg: seg.fg }}>{seg.text}</span>
+                    ),
+                  )}
+                </text>
+              )}
+            </For>
+          </box>
+        );
+      },
+    },
+  };
+
+  api.slots.register(slot);
+
+  void load();
+};
+
+const plugin: TuiPluginModule & { id: string } = { id: "usage-report", tui };
+export default plugin;

package/src/types.ts

@@ -0,0 +1,57 @@
+export type WindowKind = "5h" | "daily" | "weekly" | "monthly" | "other";
+export type WindowStatus = "ok" | "rate-limited" | "frozen" | "unknown";
+
+export interface UsageWindow {
+  kind: WindowKind;
+  label: string; // "5-hour", "Weekly", "Monthly"
+  usedPercent: number | null; // 0-100
+  used: number | null;
+  limit: number | null;
+  remaining: number | null;
+  resetsAt: string | null; // ISO-8601
+  status: WindowStatus;
+}
+
+export type ReportSource = "api" | "cache" | "local-estimate" | "error";
+
+export interface ProviderReport {
+  provider: string;
+  displayName: string;
+  fetchedAt: string;
+  source: ReportSource;
+  stale: boolean;
+  windows: UsageWindow[];
+  extras: Record<string, string>;
+  error: string | null;
+}
+
+export interface Credential {
+  type: "api" | "oauth";
+  key: string;
+}
+export interface AdapterResult {
+  windows: UsageWindow[];
+  extras?: Record<string, string>;
+}
+export interface FetchOptions {
+  timeoutMs: number;
+}
+export interface ProviderAdapter {
+  id: string;
+  displayName: string;
+  fetch(cred: Credential, opts: FetchOptions): Promise<AdapterResult>;
+}
+export interface PluginOptions {
+  thresholdPercent: number; // default 80
+  cacheTtlSeconds: number; // default 120
+  providers: string[] | null; // null = all discovered
+  fallback: boolean; // default true
+}
+
+export type AdapterErrorKind = "auth" | "no-plan" | "rate-limited" | "network" | "bad-response";
+export class AdapterError extends Error {
+  constructor(public kind: AdapterErrorKind, message: string) {
+    super(message);
+    this.name = "AdapterError";
+  }
+}

package/src/warn.ts

@@ -0,0 +1,97 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ProviderReport, UsageWindow } from "./types.js";
+import { pluginStateDir } from "./paths.js";
+import { formatReset } from "./render.js";
+
+export interface WarnHit {
+  provider: string;
+  displayName: string;
+  window: UsageWindow;
+  message: string;
+}
+
+interface WarnEntry {
+  firedAtReset: string | null;
+}
+type WarnState = Record<string, WarnEntry>;
+
+const HITS_WINDOW_STATUSES = new Set<UsageWindow["status"]>(["rate-limited", "frozen"]);
+const REARM_HYSTERESIS = 10;
+
+function buildMessage(displayName: string, w: UsageWindow, now: Date): string {
+  const base = `${displayName} ${w.label} window`;
+  if (HITS_WINDOW_STATUSES.has(w.status)) {
+    return `${base} is ${w.status === "rate-limited" ? "rate-limited" : "frozen"}`;
+  }
+  let message = `${base} at ${w.usedPercent}%`;
+  if (w.resetsAt !== null) {
+    const reset = formatReset(w.resetsAt, now);
+    if (reset !== null) message += ` (resets ${reset})`;
+  }
+  return message;
+}
+
+function readState(file: string): WarnState {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(file, "utf8"));
+    if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed as WarnState;
+    }
+  } catch {
+    // Missing or corrupt state file: start from empty.
+  }
+  return {};
+}
+
+/** Atomic: write a temp file next to the target, then rename it into place. */
+function writeState(file: string, dir: string, state: WarnState): void {
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${Math.random().toString(36).slice(2)}`;
+  writeFileSync(tmp, JSON.stringify(state, null, 2));
+  renameSync(tmp, file);
+}
+
+/**
+ * Checks reports for windows that crossed the warning threshold or are
+ * rate-limited/frozen. Fires at most once per (provider, window-kind) until the
+ * window resets; re-arms once usage drops below threshold - 10.
+ */
+export async function checkWarnings(
+  reports: ProviderReport[],
+  thresholdPercent: number,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<WarnHit[]> {
+  const now = new Date();
+  const dir = pluginStateDir(env);
+  const file = join(dir, "warn-state.json");
+  const state = readState(file);
+  const hits: WarnHit[] = [];
+
+  for (const report of reports) {
+    for (const w of report.windows) {
+      const key = `${report.provider}/${w.kind}`;
+      const crossed =
+        (w.usedPercent !== null && w.usedPercent >= thresholdPercent) || HITS_WINDOW_STATUSES.has(w.status);
+
+      if (crossed) {
+        const prev = state[key];
+        const alreadyFired = prev !== undefined && prev.firedAtReset === w.resetsAt;
+        if (!alreadyFired) {
+          state[key] = { firedAtReset: w.resetsAt };
+          hits.push({
+            provider: report.provider,
+            displayName: report.displayName,
+            window: w,
+            message: buildMessage(report.displayName, w, now),
+          });
+        }
+      } else if (w.usedPercent !== null && w.usedPercent < thresholdPercent - REARM_HYSTERESIS) {
+        delete state[key];
+      }
+    }
+  }
+
+  writeState(file, dir, state);
+  return hits;
+}