diff --git a/README.md b/README.md index 87b813a..8657b90 100644 --- a/README.md +++ b/README.md @@ -41,3 +41,27 @@ All commands are run from the root of the project, from a terminal: ## 👀 Want to learn more? Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat). + +# Archicratie — Web Edition (Atelier éditorial) + +Ce repo contient le site Astro “Archicratie – Web Edition” et sa machine éditoriale : +- Proposer (tickets Gitea pré-remplis depuis les paragraphes) +- Apply-ticket (application sûre des corrections) +- Contrat d’ancres (citabilité) + churn test +- CI Gitea Actions + runner DS220+ + +## Démarrage rapide +- `npm install` +- `npm run dev` + +## Documentation (référence) +- **Quickstart (10 min)** : `docs/QUICKSTART.md` +- **Manuel de référence** : `docs/MANUEL_REFERENCE.md` +- **Contrat de tickets** : `docs/CONTRAT_TICKETS.md` + +## Commandes clés +- Tests complets : `npm test` +- Test ancres : `npm run test:anchors` +- Appliquer un ticket : + - `node scripts/apply-ticket.mjs --dry-run` + - `node scripts/apply-ticket.mjs ` diff --git a/docs/CONTRAT_TICKETS.md b/docs/CONTRAT_TICKETS.md new file mode 100644 index 0000000..7a251c5 --- /dev/null +++ b/docs/CONTRAT_TICKETS.md @@ -0,0 +1,29 @@ +# Contrat de ticket — Proposer / Apply-ticket / Auto-label + +Ce document fixe le format minimal et les invariants des tickets d’édition. +Objectif : parsing fiable par scripts + workflows. + +## Invariants (non négociables) +Doivent toujours exister dans le body du ticket : + +- `Chemin: /.../` +- `URL locale: ...#...` (utile pour audit humain) +- `Ancre: #p-...` +- `Type: type/...` +- `State: state/...` +- `Proposition (remplacer par):` + +## Texte actuel : best effort +Priorité : +1) `Texte actuel (copie exacte du paragraphe):` +2) sinon `Texte actuel (extrait):` + note de troncature + +> Même si le texte actuel est un extrait, l’ancre + chemin rendent le ticket opposable. + +## Catégorie (optionnelle) +- `Category: cat/...` (ou vide) + +## Pourquoi ce contrat ? +- `apply-ticket.mjs` dépend de repères textuels stables +- `auto-label-issues` dépend de `Type/State/Category` +- on veut éviter des tickets “illisibles machine” qui cassent l’industrialisation diff --git a/docs/MANUEL_REFERENCE.md b/docs/MANUEL_REFERENCE.md new file mode 100644 index 0000000..71a6f73 --- /dev/null +++ b/docs/MANUEL_REFERENCE.md @@ -0,0 +1,206 @@ +# 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 ` (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 --dry-run` + +- Application réelle : + - `node scripts/apply-ticket.mjs ` + +### 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-` uniquement si écriture + - match “best effort” mais refuse si score insuffisant + +### Après application +- `git diff -- ` +- `git add ` +- `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 --dry-run` diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md new file mode 100644 index 0000000..fa6a458 --- /dev/null +++ b/docs/QUICKSTART.md @@ -0,0 +1,80 @@ +# Quickstart — 10 minutes (Proposer → Ticket → Apply → Tests) + +## 1) Pré-requis +- Node.js + npm +- Accès Gitea (compte) + PAT si usage API (apply-ticket) + +## 2) Lancer le site +en bash : +npm install +npm run dev + +Dans le navigateur, url : http://localhost:4321 + +## 3) Proposer une correction + +Ouvre une page (ex: Prologue). + +Sur un paragraphe : clique Proposer. + +Choisis : + +Type : Correction / Fact-check + +Category (optionnel) + +Un nouvel onglet Gitea s’ouvre sur une issue pré-remplie. + +Rédige : + +Proposition (remplacer par): + +Justification: + +## 4) Appliquer le ticket en local ( = numéro du ticket non pas id-paragraphe) + +En bash : + +# dry-run (recommandé) +node scripts/apply-ticket.mjs --dry-run + +# appliquer +node scripts/apply-ticket.mjs +git diff +git add +git commit -m "edit: apply ticket # (...)" + +## 5) Vérifier avant push + +npm test + +## 6) Règle d’or + +Ne jamais éditer dist/ à la main. + +Toujours garder Chemin + Ancre + Proposition dans le ticket. + +Déplacer/ajouter les deux docs que je t’ai donnés +- `docs/MANUEL_REFERENCE.md` +- `docs/CONTRAT_TICKETS.md` + +*(Tu peux reprendre mes versions telles quelles.)* + +--- + +## Commandes terminal P0 (copier-coller) +En bash +mkdir -p docs + +# crée/édite les fichiers avec ton éditeur habituel +# README.md +# docs/QUICKSTART.md +# docs/MANUEL_REFERENCE.md +# docs/CONTRAT_TICKETS.md + +git status -sb +npm test +git add docs/QUICKSTART.md docs/MANUEL_REFERENCE.md docs/CONTRAT_TICKETS.md +git commit -m "docs: add quickstart + reference manual + ticket contract" +git push +