new: [opencode-greenpt-usage] add GreenPT credit balance plugin

Show the remaining GreenPT API credit balance in the OpenCode TUI
sidebar. The key is resolved from the ``apiKey`` option, the
``GREENPT_API_KEY`` environment variable, or the active OpenCode
``auth.json`` (provider ``greenpt``); the section is hidden when no key
is present, so the plugin stays portable across machines and profiles.

The balance is read from the ``x-credits-remaining`` header returned by
a free ``HEAD /v1/chat/completions`` probe (HTTP 400 before any credit
is consumed), which avoids a billable call per refresh. Tests cover the
credential resolution, the header parsing and the live API.

Distribute via git clone; there is no npm publish.

README.md

@@ -0,0 +1,104 @@
+# opencode-greenpt-usage
+
+Plugin TUI [OpenCode](https://opencode.ai) qui affiche dans la barre latérale
+le **solde de crédits API GreenPT** restant.
+
+```
+▼ GreenPT
+Solde              5.31 €   maj 21:35
+```
+
+## Fonctionnement
+
+- La clé API est résolue dans cet ordre :
+  1. l'option `apiKey` du plugin ;
+  2. la variable d'environnement `GREENPT_API_KEY` ;
+  3. le store d'authentification **actif** d'OpenCode (`auth.json`,
+     provider `greenpt`, entrée `type: "api"`), c'est-à-dire ce que produit
+     un simple `opencode auth login`.
+- Le solde est lu via une sonde **gratuite** `HEAD /v1/chat/completions` :
+  l'API répond `400 Bad Request` avant toute facturation, mais la réponse
+  porte quand même l'en-tête `x-credits-remaining`. Aucun crédit n'est
+  consommé et aucune génération n'est lancée.
+- La section est **masquée tant qu'aucune clé GreenPT n'est détectée**.
+- Rafraîchissement : au démarrage, à la fin d'une session, à la
+  reconnexion du serveur, par minuteur (300 s par défaut) et à la demande
+  via la commande `greenpt.refresh`.
+
+Aucune dépendance à un profil ou à une commande locale : le plugin se base
+uniquement sur la présence d'une clé.
+
+## Prérequis
+
+- OpenCode `>= 1.18.0` (système de plugins TUI).
+- Un compte GreenPT et une clé API.
+
+## Installation
+
+1. **Cloner ce dépôt** à l'emplacement de votre choix.
+
+2. **Connecter GreenPT à OpenCode** :
+
+   ```bash
+   opencode auth login
+   ```
+
+   Choisir **GreenPT** dans la liste, puis coller la clé API.
+
+   (Alternative : exporter `GREENPT_API_KEY` dans votre environnement.)
+
+3. **Enregistrer le plugin** dans `~/.config/opencode/tui.json`, en
+   renseignant le **chemin absolu vers votre clone** :
+
+   ```jsonc
+   {
+     "$schema": "https://opencode.ai/tui.json",
+     "plugin": [
+       ["file:///CHEMIN/ABSOLU/VERS/opencode-greenpt-usage/src/index.tsx", { "order": 700 }]
+     ]
+   }
+   ```
+
+   > Utiliser une URL `file://` pointant vers le fichier source
+   > `src/index.tsx` (OpenCode compile le TSX lui-même). Ne pas pointer vers
+   > un bundle : cela embarquerait une seconde copie de `solid-js` et la
+   > section resterait vide.
+
+4. **Quitter complètement OpenCode et le relancer** (les plugins ne sont pas
+   rechargés à chaud).
+
+## Configuration
+
+Toutes les options sont facultatives et se placent dans l'entrée du plugin
+de `tui.json` :
+
+| Option               | Type    | Défaut                      | Description                                              |
+| -------------------- | ------- | --------------------------- | -------------------------------------------------------- |
+| `apiKey`             | string  | résolu automatiquement      | Clé GreenPT explicite.                                   |
+| `baseUrl`            | string  | `https://api.greenpt.ai/v1` | URL de base de l'API GreenPT.                            |
+| `refreshInterval`    | number  | `300`                       | Intervalle de rafraîchissement en secondes (`0` = aucun).|
+| `order`              | number  | `700`                       | Position de la section dans la barre latérale.           |
+| `showWhenUnavailable`| boolean | `false`                     | Afficher un indice quand aucune clé GreenPT n'existe.    |
+| `unit`               | string  | `€`                         | Unité affichée après le montant.                         |
+
+## Dépannage
+
+- **La section n'apparaît pas** : vérifier que `opencode auth login` a bien
+  enregistré une clé `greenpt` (ou que `GREENPT_API_KEY` est définie), et que
+  l'URL `file://` de `tui.json` pointe vers le bon chemin.
+- **« clé GreenPT invalide »** : la clé API a été refusée (HTTP 401).
+- **« solde indisponible »** : GreenPT n'a pas renvoyé l'en-tête de solde ;
+  réessayer plus tard.
+
+## Développement
+
+```bash
+npm install
+npm test                 # tests unitaires
+npm run typecheck        # vérification de types
+GREENPT_API_KEY=... npm run test:integration   # test contre l'API réelle
+```
+
+## Licence
+
+AGPL-3.0-or-later. Voir [LICENSE](LICENSE).