# Manuel de référence — Archicratie Web Edition (Site + Gitea + Runner)

Ce manuel explique comment utiliser et maintenir l’outil d’édition :
- Site Astro “Archicratie – Web Edition”
- Proposer (tickets Gitea pré-remplis)
- Apply-ticket (application semi-automatique dans le contenu)
- Contrat d’ancres (citabilité) + tests
- CI Gitea Actions + ds220-runner (DS220+)

> Objectif : une boucle éditoriale reproductible, opposable, sûre, et testée.

---

## 0) Glossaire minimal (anti-jargon)
- **PR** (Pull Request) : demande de fusion d’une branche vers `master`.
- **PAT** (Personal Access Token) : jeton d’accès Gitea utilisé comme “mot de passe” pour API/Git.
- **Anchor / Ancre** : identifiant stable d’un paragraphe (ex: `p-8-0e65838d`) utilisable dans une URL `#...`.
- **Churn** : variation des ancres d’une page entre deux builds (mesure de stabilité).
- **dist/** : sortie buildée (artefact), jamais la “source de vérité”.
- **CI** : automatisation (build + tests) à chaque push/PR.

---

## 1) Pré-requis (poste local)
### Outils
- Node.js + npm
- Git
- (Optionnel) Python3 pour scripts de debug ponctuels

### Accès
- Compte Gitea avec droits sur le repo
- Un **PAT** Gitea
- Accès au site local (dev) et/ou build (dist)

---

## 2) Vue d’ensemble : la boucle éditoriale (rituel)
### Boucle standard (la “cadence courte”)
1) Sur le site, cliquer **Proposer** sur un paragraphe.
2) Choisir Type (Correction / Fact-check), puis Category.
3) Gitea ouvre un ticket pré-rempli (Chemin/URL/Ancre + texte actuel).
4) Rédiger la **Proposition (remplacer par)** + Justification.
5) En local :
   - `node scripts/apply-ticket.mjs <num>` (d’abord `--dry-run`)
   - `npm run test:anchors`
   - `npm run build`
6) Commit + push + PR si nécessaire.

---

## 3) Le site “Proposer / Citer / ¶” (para-tools)
### Où ça vit ?
- `src/layouts/EditionLayout.astro` injecte un script qui :
  - ajoute “¶” (lien d’ancre), “Citer”, “Proposer”
  - construit l’URL de création d’issue Gitea
  - embarque si possible le **paragraphe exact** (sinon un extrait)

- `src/components/ProposeModal.astro` gère la modal 2 étapes :
  - Type (correction/fact-check)
  - Category (cat/style, cat/lexique, etc.)
  - ouvre ensuite l’issue en **nouvel onglet** sans quitter le site

### Invariants (non négociables)
- **Ancre + URL + Chemin** doivent toujours être présents.
- Le mode “texte exact” est *best effort* :
  - si trop long → fallback extrait + note
  - priorité absolue : rester robuste et cliquable.

### Limites / règles de taille
- **FULL_TEXT_SOFT_LIMIT** : taille max pour tenter d’embarquer “copie exacte”
- **URL_HARD_LIMIT** : si l’URL devient trop longue → repasse en extrait

> But : éviter des issues amputées + éviter des URLs trop longues / fragiles.

---

## 4) Format des tickets (machine-readable)
Le parsing des tickets est fait par `scripts/apply-ticket.mjs` + workflow auto-label.
Donc le contenu doit rester “parsable”.

Sections attendues (au minimum) :
- `Chemin: /.../`
- `Ancre: #p-...`
- `Texte actuel (...)` (idéalement “copie exacte”, sinon “extrait”)
- `Proposition (remplacer par): ...`
- `Justification: ...` (peut être vide, mais le champ doit exister si possible)

> Voir aussi : docs/CONTRAT_TICKETS.md

---

## 5) Appliquer un ticket en local : `apply-ticket`
### Commandes
- Dry run (recommandé) :
  - `node scripts/apply-ticket.mjs <N> --dry-run`

- Application réelle :
  - `node scripts/apply-ticket.mjs <N>`

### Comportements de sûreté (guardrails)
- `--dry-run` :
  - **aucun fichier écrit**
  - **aucun backup créé**
  - affiche BEFORE/AFTER (extrait)

- Mode écriture :
  - crée un backup `.bak.issue-<N>` uniquement si écriture
  - match “best effort” mais refuse si score insuffisant

### Après application
- `git diff -- <fichier>`
- `git add <fichier>`
- `git commit -m "edit: apply ticket #N (...)"`

---

## 6) Contrat de citabilité : ancres + churn test
### Pourquoi ?
Les ancres sont le “socle de citabilité”. On veut prévenir les liens morts.

### Scripts
- `npm run test:anchors`
  - compare les ancres de `dist/` avec une baseline
  - calcule le churn et signale les pages modifiées

- `npm run test:anchors:update`
  - met à jour la baseline (à faire seulement quand c’est volontaire)

> Important : `dist/` est un artefact ; la baseline sert à mesurer, pas à “éditer dist”.

---

## 7) Garde-fou JS inline : `check-inline-js`
Pourquoi : éviter qu’un JS inline cassé supprime les boutons et fasse disparaître “Proposer/Citer”.

- `node scripts/check-inline-js.mjs`
- intégré dans `npm test`

---

## 8) CI (Gitea Actions)
### Objectif
Sur chaque push/PR : vérifier automatiquement que :
- build OK
- ancres OK
- JS inline OK

### Workflow
- `.gitea/workflows/ci.yml`

### Commande “contrat”
- `npm test`
  - exécute : build + anchors + inline-js

---

## 9) ds220-runner (DS220+ / Gitea act-runner)
### Comportement normal
Le runner lance des jobs dans des conteneurs éphémères qui démarrent/stop.
DSM peut notifier “conteneur arrêté de manière inattendue” : c’est souvent un faux positif “bruyant”.

### À surveiller vraiment
- Jobs en échec côté Gitea Actions
- logs mentionnant :
  - auth API (401)
  - labels manquants
  - npm ci/build en échec

---

## 10) Dépannage (symptômes → causes fréquentes)
### “Proposer” ouvre deux onglets / remplace l’onglet courant
Cause : double handler click / manque de `stopPropagation` / mauvais fallback.
Fix : le flux doit ouvrir **nouvel onglet uniquement**, et sinon prompt.

### “Proposer/Citer/¶” disparaissent
Cause : JS inline cassé → exception ou erreur syntaxe.
Fix : `node scripts/check-inline-js.mjs` + vérifier `dist/.../index.html` console.

### apply-ticket : “Proposition introuvable”
Cause : ticket sans section “Proposition (remplacer par):”.
Fix : respecter le contrat de ticket.

### apply-ticket : “Match trop faible”
Cause : texte actuel absent / trop tronqué / mismatch.
Fix :
- privilégier “Texte actuel (copie exacte du paragraphe)”
- sinon le script récupère via `dist` (si possible).

---

## 11) Règles de contribution (discipline de repo)
- Toute modif éditoriale passe par ticket → apply-ticket → tests.
- Toute modif structurelle (layouts, rendu, MDX) doit être suivie de :
  - `npm test`
  - éventuellement `npm run test:anchors:update` si changement volontaire d’ancres.
- Ne jamais éditer `dist/` à la main.

---

## 12) Commandes utiles (raccourcis)
- Dev : `npm run dev`
- Build : `npm run build`
- Tests : `npm test`
- Anchors : `npm run test:anchors`
- Apply ticket : `node scripts/apply-ticket.mjs <N> --dry-run`