usage-panel-opencode 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# usage-panel-opencode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Plugin para OpenCode v2 que muestra el consumo de las ventanas de cuota de una suscripción ChatGPT. Requiere Bun ≥ 1.2 y OpenCode v2; una cuenta con suscripción conectada mediante `/connect` → OpenAI → **Sign in with ChatGPT**.
+
+## Instalación y carga
+
+Instala las dependencias (`bun install`). Para una instalación publicada, añade el paquete y sus opciones a `opencode.jsonc` del proyecto o a la configuración de usuario:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": [
+    {
+      "package": "usage-panel-opencode",
+      "options": {
+        "enabled": true,
+        "intervalSeconds": 60,
+        "visible": true
+      }
+    }
+  ]
+}
+```
+
+Para desarrollo en este repositorio, usa `"plugins": ["./"]`. El paquete incluye piezas separadas de servidor y TUI.
+
+## Preferencias
+
+- `enabled` (`true`): desactiva consultas, eventos e indicador al establecerlo en `false`.
+- `intervalSeconds` (`60`): intervalo de sondeo; los valores menores se normalizan a 60 segundos.
+- `visible` (`true`): oculta el indicador sin desactivar las lecturas.
+
+Las preferencias se guardan en el almacenamiento del plugin. El consumo no se persiste. El RPC `openai-usage` ofrece `snapshot`, `refresh`, `setPreferences`, `start` y `stop`; `start`, `stop`, `snapshot` y `refresh` reciben el identificador de la instancia TUI. El indicador abre el detalle; la paleta ofrece detalle y actualización, con comandos `/usage-detail` (alias `/openai-usage-detail`) y `/usage-refresh` (alias `/openai-usage-refresh`).
+
+Las opciones del bloque `options` son valores iniciales; una preferencia guardada por `setPreferences` tiene precedencia y sobrevive al reinicio. No hay un comando de ajustes integrado en la paleta. Para cambiar preferencias en ejecución, un plugin TUI auxiliar puede invocar el RPC compartido:
+
+```ts
+import { Usage } from 'usage-panel-opencode/rpc'
+
+const usage = context.client.rpc(Usage)
+const location = context.location ?? context.data.location.default()
+const rpcOptions = { location }
+
+// Cambiar intervalo y ocultar el indicador; las consultas siguen activas.
+await usage.setPreferences({ intervalSeconds: 180, visible: false }, rpcOptions)
+
+// Reactivarlo después, incluso si la preferencia enabled quedó en false.
+await usage.setPreferences({ enabled: true, visible: true }, rpcOptions)
+```
+
+Después de la llamada, el servidor devuelve y emite el estado actualizado. Para verificar la instalación, reinicia OpenCode, confirma que `/usage-detail` aparece en la paleta, abre el detalle y revisa que las preferencias indicadas se reflejen en el estado RPC. Si se cambia la configuración estática, elimina o actualiza primero las preferencias guardadas desde el RPC; estas prevalecen deliberadamente sobre `options`.
+
+## Privacidad y fuentes
+
+El servidor consulta únicamente `https://chatgpt.com/backend-api/wham/usage` con el OAuth activo, o utiliza porcentajes de cabeceras `x-codex-*` de respuestas OpenAI solo cuando puede correlacionarlas con la misma petición y cuenta activa. Si no puede demostrar esa asociación, las descarta. No lee la cabecera Authorization, no registra credenciales y enmascara identificadores. No se recopilan conversaciones, créditos ni límites por modelo. No se hacen peticiones de sondeo cuando el plugin está desactivado.
+
+El alcance de los porcentajes (entre clientes o personal frente a organizativo) no está verificado para cada fuente y cuenta; el detalle lo declara como desconocido. Las cabeceras no proporcionan hora de reinicio, por lo que se muestra «no disponible». El servicio puede informar resets, pero su formato y disponibilidad dependen del proveedor. La respuesta del endpoint es un contrato observado, no una API pública garantizada.
+
+## Resolución de problemas
+
+- **Sin datos / conexión de API key:** se muestran cuotas de suscripción solo para OAuth de ChatGPT; una API key no equivale a una suscripción.
+- **Requiere autenticación:** vuelve a conectar OpenAI desde `/connect`.
+- **Error temporal o límite 429:** se conserva la última lectura si existe y se aplica espera; los intentos respetan un mínimo de 60 segundos.
+- **Datos parciales:** comprueba el origen en detalle. La fuente de cabeceras puede carecer de plan, alguna ventana o reset.
+- **Desactivar:** establece `enabled: false` o quita el plugin de la configuración.
+
+El slot público de la barra lateral no informa de sus dimensiones. Para evitar expandirlo o desplazar contenido, el indicador usa un presupuesto conservador de hasta 28 columnas y reserva espacio para el contenido existente. Se oculta si no cabe el bloque completo: el estado normal requiere al menos 12 filas y un fallo inicial con acción y reintento puede requerir hasta 18; el ancho mínimo efectivo es 78 columnas. La vista compacta solo muestra 5 h y semanal; otras ventanas siguen disponibles en el detalle.
+
+## Desarrollo y dependencias
+
+Ejecuta `bun test`, `bunx tsc --noEmit`, `bunx biome check .` y `bun audit`. `bunfig.toml` carga el transform Solid de OpenTUI tanto en ejecución como en pruebas; la suite de aceptación renderiza el componente real con el renderer de prueba de OpenTUI. Actualiza dependencias deliberadamente: revisa cambios mayores, ejecuta todas las verificaciones y confirma compatibilidad con OpenCode v2 antes de integrar.

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "usage-panel-opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "OpenCode v2 plugin for viewing ChatGPT subscription usage.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./server": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./tui": {
+      "types": "./src/tui.tsx",
+      "import": "./src/tui.tsx"
+    },
+    "./rpc": {
+      "types": "./src/rpc.ts",
+      "import": "./src/rpc.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check ."
+  },
+  "dependencies": {
+    "@opencode/plugin": "^2.2.5"
+  },
+  "overrides": {
+    "glob": "^14.0.2",
+    "minimatch": "^11.0.1"
+  },
+  "peerDependencies": {
+    "@opencode/theme": "*",
+    "@opentui/core": ">=0.8.0",
+    "@opentui/solid": ">=0.8.0",
+    "solid-js": ">=1.9.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@opencode/theme": "*",
+    "@opentui/core": "^0.8.0",
+    "@opentui/solid": "^0.8.0",
+    "@types/bun": "^1.2.0",
+    "solid-js": "^1.9.0",
+    "typescript": "^5.0.0"
+  }
+}

package/src/config.ts

@@ -0,0 +1,62 @@
+export interface PanelPreferences {
+  enabled: boolean;
+  intervalSeconds: number;
+  visible: boolean;
+}
+
+export const DEFAULT_PREFERENCES: Readonly<PanelPreferences> = Object.freeze({
+  enabled: true,
+  intervalSeconds: 60,
+  visible: true,
+});
+
+const PREFERENCE_KEYS = ['enabled', 'intervalSeconds', 'visible'] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function normalizeIntervalSeconds(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value))
+    return DEFAULT_PREFERENCES.intervalSeconds;
+  return Math.max(60, value);
+}
+
+function readStaticOptions(options: unknown): PanelPreferences {
+  const values = isRecord(options) ? options : {};
+
+  return {
+    enabled: typeof values.enabled === 'boolean' ? values.enabled : DEFAULT_PREFERENCES.enabled,
+    intervalSeconds: normalizeIntervalSeconds(values.intervalSeconds),
+    visible: typeof values.visible === 'boolean' ? values.visible : DEFAULT_PREFERENCES.visible,
+  };
+}
+
+function isSavedPreferences(value: unknown): value is PanelPreferences {
+  if (!isRecord(value)) return false;
+  if (
+    Object.keys(value).some(
+      (key) => !PREFERENCE_KEYS.includes(key as (typeof PREFERENCE_KEYS)[number]),
+    )
+  ) {
+    return false;
+  }
+
+  return (
+    PREFERENCE_KEYS.every((key) => Object.hasOwn(value, key)) &&
+    typeof value.enabled === 'boolean' &&
+    typeof value.intervalSeconds === 'number' &&
+    Number.isInteger(value.intervalSeconds) &&
+    value.intervalSeconds >= 60 &&
+    typeof value.visible === 'boolean'
+  );
+}
+
+/** Resolves startup settings. Valid stored preferences override static options. */
+export function resolvePreferences(options?: unknown, stored?: unknown): PanelPreferences {
+  if (stored === undefined) return readStaticOptions(options);
+  if (isSavedPreferences(stored)) return { ...stored };
+
+  // Corrupt persisted values are discarded as a whole, as specified by the storage contract.
+  return { ...DEFAULT_PREFERENCES };
+}

package/src/core/account.ts

@@ -0,0 +1,74 @@
+import type { CredentialKind, SubscriptionAccount } from '../rpc';
+import { readAccountClaims } from './claims';
+import { maskAccountId, redactText, sanitizeText } from './redact';
+
+export interface ResolvedAccount {
+  account: SubscriptionAccount;
+  /** Ephemeral OAuth access token used only by the request client. */
+  accessToken: string | null;
+  /** Raw identifier is kept out of the public account entity and used only for the request header. */
+  usageAccountId: string | null;
+  /** Non-secret key used to discard data when the active account changes. */
+  identity: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function planOrganization(planHint: string | null): boolean | null {
+  if (!planHint) return null;
+  const plan = planHint.toLowerCase();
+  if (['business', 'team', 'enterprise', 'edu'].includes(plan)) return true;
+  if (['plus', 'pro', 'prolite', 'free'].includes(plan)) return false;
+  return null;
+}
+
+function credentialKind(credential: Record<string, unknown> | null): CredentialKind {
+  if (credential?.type === 'oauth') return 'oauth';
+  if (credential?.type === 'key') return 'key';
+  return 'none';
+}
+
+/** Resolves a connection and credential without putting secrets on the public account entity. */
+export function resolveAccount(
+  connectionValue: unknown,
+  credentialValue: unknown,
+): ResolvedAccount {
+  const connection = isRecord(connectionValue) ? connectionValue : null;
+  const credential = isRecord(credentialValue) ? credentialValue : null;
+  const kind = credentialKind(credential);
+  const accessToken = kind === 'oauth' ? getString(credential?.access) : null;
+  const claims = readAccountClaims(accessToken);
+  const labelValue = getString(connection?.label) ?? getString(connection?.name);
+  const label = labelValue
+    ? sanitizeText(
+        redactText(labelValue, { secrets: [accessToken], accountIds: [claims.accountId] }),
+        100,
+      )
+    : null;
+  const expiresValue = kind === 'oauth' ? credential?.expires : null;
+  const expiresAt =
+    typeof expiresValue === 'number' && Number.isFinite(expiresValue) ? expiresValue : null;
+  const connectionId = getString(connection?.id) ?? getString(connection?.connectionID);
+  const identity = `${kind}:${connectionId ?? 'connection'}:${claims.accountId ?? label ?? 'unknown'}`;
+
+  return {
+    account: {
+      credentialKind: kind,
+      ...(label ? { label } : {}),
+      ...(claims.accountId ? { accountId: maskAccountId(claims.accountId) } : {}),
+      ...(claims.planHint
+        ? { planHint: claims.planHint, organization: planOrganization(claims.planHint) }
+        : {}),
+      ...(kind === 'oauth' ? { expiresAt } : {}),
+    },
+    accessToken,
+    usageAccountId: claims.accountId,
+    identity,
+  };
+}

package/src/core/backoff.ts

@@ -0,0 +1,32 @@
+import type { UsageClientErrorKind } from './usage-client';
+
+const MIN_ATTEMPT_INTERVAL_MS = 60_000;
+const FIRST_RETRY_DELAY_MS = 60_000;
+const MAX_RETRY_DELAY_MS = 15 * 60_000;
+
+export function canAttempt(lastAttemptAt: number | null | undefined, now: number): boolean {
+  return (
+    lastAttemptAt === null ||
+    lastAttemptAt === undefined ||
+    now - lastAttemptAt >= MIN_ATTEMPT_INTERVAL_MS
+  );
+}
+
+/** Returns a retry delay, or null when the failure must wait for a credential change. */
+export function nextRetryDelay(
+  failureCount: number,
+  kind: UsageClientErrorKind,
+  retryAfterMs?: number,
+): number | null {
+  if (kind === 'unauthorized' || kind === 'forbidden') return null;
+  const attempt = Number.isFinite(failureCount) ? Math.max(0, Math.floor(failureCount)) : 0;
+  const exponential = Math.min(
+    MAX_RETRY_DELAY_MS,
+    FIRST_RETRY_DELAY_MS * 2 ** Math.min(attempt, 20),
+  );
+  const retryAfter =
+    typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs)
+      ? Math.max(0, retryAfterMs)
+      : 0;
+  return Math.max(MIN_ATTEMPT_INTERVAL_MS, exponential, retryAfter);
+}

package/src/core/claims.ts

@@ -0,0 +1,49 @@
+import { redactText } from './redact';
+
+const ACCOUNT_ID_CLAIM = 'https://api.openai.com/auth.chatgpt_account_id';
+const PLAN_TYPE_CLAIM = 'https://api.openai.com/auth.chatgpt_plan_type';
+const AUTH_CLAIM = 'https://api.openai.com/auth';
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9_-]{4,64}$/;
+
+export interface AccountClaims {
+  accountId: string | null;
+  planHint: string | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function decodePayload(token: unknown): Record<string, unknown> | null {
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length < 2 || !parts[1]) return null;
+
+  try {
+    const normalized = parts[1].replaceAll('-', '+').replaceAll('_', '/');
+    const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    const payload: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    return isRecord(payload) ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Reads optional display/routing hints from a JWT-shaped token; it does not authenticate the token. */
+export function readAccountClaims(token: unknown): AccountClaims {
+  const payload = decodePayload(token);
+  if (!payload) return { accountId: null, planHint: null };
+
+  const nestedAuth = payload[AUTH_CLAIM];
+  const auth = isRecord(nestedAuth) ? nestedAuth : {};
+  const rawAccountId = payload[ACCOUNT_ID_CLAIM] ?? auth.chatgpt_account_id;
+  const rawPlanHint = payload[PLAN_TYPE_CLAIM] ?? auth.chatgpt_plan_type;
+  const accountId =
+    typeof rawAccountId === 'string' && ACCOUNT_ID_PATTERN.test(rawAccountId) ? rawAccountId : null;
+  const planText =
+    typeof rawPlanHint === 'string' ? redactText(rawPlanHint, { maxLength: 80 }) : '';
+
+  return { accountId, planHint: planText.length > 0 ? planText : null };
+}

package/src/core/redact.ts

@@ -0,0 +1,151 @@
+export interface RedactionOptions {
+  accountIds?: readonly (string | null | undefined)[];
+  secrets?: readonly (string | null | undefined)[];
+  maxLength?: number;
+}
+
+const DEFAULT_MAX_LENGTH = 240;
+const TOKEN_ASSIGNMENT =
+  /\b((?:access|refresh|id)[_-]?token|api[_-]?key|token)\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)/gi;
+const AUTHORIZATION_HEADER =
+  /\b(authorization\s*[:=]\s*)(?:bearer\s+)?(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)/gi;
+const ACCOUNT_ID_FIELD =
+  /(\b(?:chatgpt[-_]?account[-_]?id|account[-_]?id)\s*[:=]\s*["']?)([A-Za-z0-9_-]{4,64})/gi;
+
+function safeString(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function validLimit(value: number | undefined): number {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_MAX_LENGTH;
+}
+
+function stripTerminalSequences(text: string): string {
+  let result = '';
+
+  for (let index = 0; index < text.length; index += 1) {
+    if (text.charCodeAt(index) !== 27) {
+      result += text[index];
+      continue;
+    }
+
+    const next = text.charCodeAt(index + 1);
+    if (next === 91) {
+      index += 2;
+      while (
+        index < text.length &&
+        !(text.charCodeAt(index) >= 64 && text.charCodeAt(index) <= 126)
+      ) {
+        index += 1;
+      }
+    } else if (next === 93) {
+      index += 2;
+      while (index < text.length) {
+        const code = text.charCodeAt(index);
+        if (code === 7) break;
+        if (code === 27 && text.charCodeAt(index + 1) === 92) {
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+    } else {
+      index += 1;
+    }
+  }
+
+  return result;
+}
+
+function stripUnsafeCharacters(text: string): string {
+  return Array.from(text, (character) => {
+    const codePoint = character.codePointAt(0) ?? 0;
+    if (codePoint === 9) return ' ';
+    if (
+      codePoint <= 31 ||
+      (codePoint >= 127 && codePoint <= 159) ||
+      (codePoint >= 0x202a && codePoint <= 0x202e) ||
+      (codePoint >= 0x2066 && codePoint <= 0x2069)
+    ) {
+      return '';
+    }
+    return character;
+  }).join('');
+}
+
+function replaceExactValues(text: string, values: RedactionOptions['secrets']): string {
+  let result = text;
+  for (const value of values ?? []) {
+    if (typeof value === 'string' && value.length > 0)
+      result = result.split(value).join('[redacted]');
+  }
+  return result;
+}
+
+function maskIdentifier(value: string): string {
+  return maskAccountId(value) ?? '[redacted]';
+}
+
+/** Returns a display-safe account suffix. Very short identifiers are omitted rather than exposed. */
+export function maskAccountId(value: unknown): string | null {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{4,64}$/.test(value) || value.length <= 4) {
+    return null;
+  }
+  return `…${value.slice(-4)}`;
+}
+
+/** Removes terminal control sequences, line breaks, and bidirectional control characters. */
+export function sanitizeText(value: unknown, maxLength = DEFAULT_MAX_LENGTH): string {
+  const limit = validLimit(maxLength);
+  const text = stripUnsafeCharacters(
+    stripTerminalSequences(safeString(value)).replace(/\r\n?|\n/g, ' '),
+  )
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit - 1)}…`;
+}
+
+/** Redacts known secrets and common credential formats, then returns safe single-line text. */
+export function redactText(value: unknown, options: RedactionOptions = {}): string {
+  let text = safeString(value);
+
+  text = replaceExactValues(text, options.secrets);
+  for (const accountId of options.accountIds ?? []) {
+    if (typeof accountId === 'string' && accountId.length > 0) {
+      text = text.split(accountId).join(maskIdentifier(accountId));
+    }
+  }
+
+  text = text
+    .replace(AUTHORIZATION_HEADER, '$1[redacted]')
+    .replace(/\bbearer\s+[^\s,;}\]]+/gi, 'Bearer [redacted]')
+    .replace(TOKEN_ASSIGNMENT, '$1=[redacted]')
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}/gi, '[redacted]')
+    .replace(/\beyJ[A-Za-z0-9_-]{10,}(?:\.[A-Za-z0-9_-]+){1,2}\b/g, '[redacted]')
+    .replace(ACCOUNT_ID_FIELD, (_match, prefix: string, accountId: string) => {
+      return `${prefix}${maskIdentifier(accountId)}`;
+    });
+
+  return sanitizeText(text, options.maxLength);
+}
+
+/** Extracts only an error message; stack traces and attached response bodies are never returned. */
+export function redactError(error: unknown, options: RedactionOptions = {}): string {
+  let message: string;
+  if (error instanceof Error) {
+    message = error.message;
+  } else if (typeof error === 'string') {
+    message = error;
+  } else if (typeof error === 'object' && error !== null && 'message' in error) {
+    const candidate = error.message;
+    message = typeof candidate === 'string' ? candidate : 'Unknown error';
+  } else {
+    message = 'Unknown error';
+  }
+
+  return redactText(message, options);
+}