usage-panel-opencode 0.0.0-stage → 0.1.1

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, ejecuta `bun run build` y usa `"plugins": ["./"]`; vuelve a ejecutar el build tras cambiar el TUI. El paquete incluye piezas separadas de servidor y TUI. `prepack` compila el TUI con el transform de Solid antes de publicar, sin depender del `bunfig.toml` de la aplicación consumidora.
+
+## 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.