# Runners Gitea Actions · ajouter Windows (et macOS)

Ce document explique comment activer le build **Windows** de l'app de bureau dans la CI. Il est écrit
pour être appliqué tel quel sur `git.lidge.fr` (Gitea 1.25).

## Pourquoi un runner Windows est obligatoire

Le cross-build Windows depuis Linux **ne peut pas fonctionner**, pour deux raisons vérifiées dans
`node_modules/@homebridge/node-pty-prebuilt-multiarch` :

1. `scripts/check-prebuild.js` sort en succès dès que le binaire de l'hôte existe, donc
   `prebuild-install` n'est jamais appelé et aucun binaire `win32` n'est téléchargé (le tarball publié
   ne contient que `prebuilds/linux-*`) ;
2. `scripts/post-install.js` ne copie `conpty.dll` et `OpenConsole.exe` **que si la plateforme de build
   est win32**. Sans eux, pas de ConPTY, donc **aucun terminal** dans l'app.

Un build produit sous Wine serait donc installable mais inutilisable. C'est pour cela que
`packages/desktop/README.md` ne propose plus cette voie.

## État actuel

| Plateforme | Runner | Build |
|---|---|---|
| Linux | `ubuntu-latest` (déjà en place) | automatique à chaque tag `desktop-v*` |
| Windows | **à enregistrer** | job **retiré** du workflow ; manuel (`npm run dist:win` sur Windows) |
| macOS | aucun | manuel (`npm run dist:mac` sur un Mac) |

Le job Windows a d'abord été gardé dans le workflow, conditionné par
`if: vars.ENABLE_WINDOWS_BUILD == 'true'`. Cela **n'a pas suffi** : sans runner labellisé
`windows-latest`, la release entière tombait en erreur au lieu de sauter le job. Il est donc
**retiré** de `.gitea/workflows/desktop-release.yml`. Son dernier état complet est dans l'historique
git (tag `desktop-v0.2.3`) : après avoir enregistré le runner ci-dessous, restaurer ce job, puis
remettre dans `latest-channel` le `download-artifact` de `desktop-windows` ainsi que
`dl/*.exe dl/latest.yml` dans la liste d'assets du canal flottant.

## 1. Préparer la machine Windows

Prérequis (Windows 10 1809+ ou Windows 11, x64) :

- **Git pour Windows** (fournit aussi `bash`, utilisé par les étapes `shell: bash` du workflow) ;
- **Node.js 22.21.1** (même version que `NODE_VERSION` dans le workflow) ;
- rien d'autre : `node-pty` s'installe via des binaires précompilés, aucun compilateur C++ n'est requis.

Vérification rapide dans PowerShell :

```powershell
node --version   # v22.21.1
git --version
bash --version   # fourni par Git for Windows
```

## 2. Enregistrer le runner

Récupérer un jeton d'enregistrement dans Gitea : **Site Administration → Actions → Runners → Create new
runner** (jeton d'instance), ou au niveau du dépôt : **Settings → Actions → Runners**.

Puis, dans PowerShell (répertoire dédié, par exemple `C:\actions-runner`) :

```powershell
mkdir C:\actions-runner; cd C:\actions-runner
# Binaire act_runner pour Windows (adapter la version à celle de votre Gitea)
Invoke-WebRequest -Uri "https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-windows-amd64.exe" -OutFile act_runner.exe

.\act_runner.exe register --no-interactive `
  --instance https://git.lidge.fr `
  --token <JETON_DENREGISTREMENT> `
  --name windows-builder `
  --labels windows-latest:host
```

Le label **`windows-latest:host`** est essentiel : `:host` signifie « exécuter directement sur la
machine », sans conteneur (il n'y a pas d'image Docker Windows utilisable ici), et `windows-latest` est
le nom attendu par `runs-on` dans le workflow.

Démarrage manuel pour un premier essai :

```powershell
.\act_runner.exe daemon
```

## 3. Exécuter le runner en service

Pour qu'il survive aux redémarrages, créer une tâche planifiée « à l'ouverture de session » (même
principe que `arboretum install` sur Windows) :

```powershell
schtasks /Create /TN "GiteaActRunner" /TR "C:\actions-runner\act_runner.exe daemon" `
  /SC ONLOGON /RL LIMITED /F
schtasks /Run /TN "GiteaActRunner"
```

Alternative : [NSSM](https://nssm.cc/) pour un vrai service Windows, si le runner doit tourner sans
session ouverte. Attention : un service hors session n'a pas accès au profil utilisateur.

## 4. Activer le job dans la CI

Dans Gitea, sur le dépôt `johanleroy/arboretum` : **Settings → Actions → Variables → Add Variable**

| Nom | Valeur |
|---|---|
| `ENABLE_WINDOWS_BUILD` | `true` |

## 5. Vérifier sans créer de tag

Le workflow accepte `workflow_dispatch` : **Actions → Desktop Release → Run workflow**. Dans ce mode, le
garde-fou « tag == version » est ignoré et rien n'est attaché à une release ; les installeurs sont
récupérables dans les artefacts du run (`desktop-windows`).

Contrôles à faire sur l'installeur produit :

1. l'installeur NSIS s'exécute et propose le répertoire d'installation ;
2. l'app démarre et affiche l'IDE **sans écran de connexion** (le token passe par le descripteur 3 ;
   c'est le point le plus susceptible de différer sur Windows, cf. `packages/desktop/src/main/daemon.ts`) ;
3. un terminal s'ouvre et répond (ConPTY présent) ;
4. le CLI `claude` est trouvé (sinon renseigner son chemin dans Réglages → Claude CLI) ;
5. « Démarrer le projet » lance bien les commandes sous PowerShell.

## 6. Signature de code

Aucun binaire n'est signé. SmartScreen affichera « éditeur inconnu » au premier lancement : choisir
« Informations complémentaires » puis « Exécuter quand même ». Pour signer plus tard, ajouter les
secrets `CSC_LINK` (certificat .pfx encodé en base64) et `CSC_KEY_PASSWORD` au dépôt : electron-builder
les utilise automatiquement, sans changement de workflow.

## Repli si aucun runner n'est possible

Sur une machine Windows, avec le dépôt cloné :

```powershell
npm ci
cd packages\desktop
npm ci
npm run dist:win
```

Puis attacher `packages\desktop\release\*.exe`, `latest.yml` et les `.blockmap` à la release
`desktop-vX.Y.Z` depuis l'interface Gitea. Le canal d'auto-update (`desktop-latest`) doit recevoir les
mêmes fichiers, sinon les utilisateurs Windows ne verront pas la mise à jour.