living-documentation 8.10.0 → 8.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.fr.md +340 -0
- package/README.md +7 -0
- package/package.json +3 -1
package/README.fr.md
ADDED
|
@@ -0,0 +1,340 @@
|
|
|
1
|
+
# Living Documentation
|
|
2
|
+
|
|
3
|
+
[🇬🇧 Read in English](./README.md)
|
|
4
|
+
|
|
5
|
+
> **Hub local de documentation Markdown avec serveur MCP intégré — vos agents de code créent les ADR, dessinent les diagrammes et détectent la dérive pendant que vous codez.**
|
|
6
|
+
|
|
7
|
+
Du Markdown sur disque, pas de cloud, pas de base de données, pas d'étape de build. Pointez l'outil vers un dossier, ouvrez `http://localhost:4321`. Branchez n'importe quel agent IA compatible MCP (Claude Code, Claude Desktop, Cursor…) et votre documentation se maintient à mesure que le code évolue.
|
|
8
|
+
|
|
9
|
+
    
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx living-documentation # assistant interactif (EN/FR)
|
|
13
|
+
npx living-documentation ./docs # servir un dossier existant
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Deux usages
|
|
21
|
+
|
|
22
|
+
### 1. Avec un agent IA — la fonctionnalité phare
|
|
23
|
+
|
|
24
|
+
Living Documentation embarque un **serveur MCP** sur `POST /mcp`. N'importe quel agent compatible MCP peut lire, créer et auditer la documentation projet de façon autonome.
|
|
25
|
+
|
|
26
|
+
| Ce que vous dites… | Ce que l'agent déclenche… | Ce qui se passe |
|
|
27
|
+
| ----------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| *« feature terminée »* / *"feature done"* | `create-adr` | Cherche les ADR existants, supplante l'ADR obsolète s'il y en a, écrit un nouvel ADR en `To be validated`, relie les fichiers source via les métadonnées. |
|
|
29
|
+
| *« audite les ADR »* / *"audit the ADRs"* | `audit-adrs-drift` | Liste chaque ADR sous 80 % de fiabilité et remet chacun en cohérence — soit re-baseliner les hashes, soit supplanter après confirmation. |
|
|
30
|
+
| *« vérifie la pertinence de cet ADR »* / *"review this ADR"* | `review-adr-relevance` | Revue d'un ADR précis contre les fichiers source liés ; rafraîchit les hashes ou propose la supersession. |
|
|
31
|
+
| *« retrodocumente depuis git »* / *"backfill ADRs from git"* | `retrodocument-adrs-from-git` | Parcourt l'historique git du plus ancien au plus récent et crée des ADR pour les décisions durables jamais documentées. |
|
|
32
|
+
| *« donne-moi la big picture »* | `generate-context-diagram` | Crée un diagramme C4 de contexte **dérivé des documents**, jamais inventé. |
|
|
33
|
+
|
|
34
|
+
**Tous les nouveaux ADR atterrissent en `To be validated`.** *Vous* les promouvez. L'agent ne promeut jamais à votre place.
|
|
35
|
+
|
|
36
|
+
### 2. Sans IA, en solo
|
|
37
|
+
|
|
38
|
+
Un hub doc personnel : ADR, notes de réunion, journal de dev, plans de features, esquisses d'architecture — tout reste en Markdown sur disque, git-friendly, zéro lock-in. Édition inline, snippets, paste d'image, pièces jointes, éditeur de diagrammes, recherche plein-texte, export PDF/HTML/Notion/Confluence.
|
|
39
|
+
|
|
40
|
+
Les deux modes se mélangent : prendre des notes en solo toute la semaine, puis laisser l'agent enregistrer l'ADR quand la feature est livrée.
|
|
41
|
+
|
|
42
|
+
---
|
|
43
|
+
|
|
44
|
+
## Démarrage rapide
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
# Assistant interactif — crée un dossier de doc de démarrage (EN ou FR), scaffold
|
|
48
|
+
# AGENTS.md / CLAUDE.md / memory/MEMORY.md à la racine du projet et fait des symlinks
|
|
49
|
+
# dans <docs>/AI/ pour que les agents IA les trouvent.
|
|
50
|
+
npx living-documentation
|
|
51
|
+
|
|
52
|
+
# Ou servir un dossier existant
|
|
53
|
+
npx living-documentation ./docs
|
|
54
|
+
npx living-documentation ./docs --port 4000 --open
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Puis ouvrez [http://localhost:4321](http://localhost:4321) (viewer) et [http://localhost:4321/admin](http://localhost:4321/admin) (config).
|
|
58
|
+
|
|
59
|
+
> Le chemin du dossier doit être **relatif** (`./docs`, `../shared/docs`…). Les chemins absolus et `~` sont rejetés pour que `.living-doc.json` reste portable et soit committable.
|
|
60
|
+
|
|
61
|
+
### Installation
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
npx living-documentation # sans installation
|
|
65
|
+
npm install -g living-documentation # global
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## Connecter votre agent IA
|
|
71
|
+
|
|
72
|
+
### Claude Code
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
claude mcp add --transport http living-documentation http://localhost:4321/mcp
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Ou manuellement dans `.claude/settings.json` :
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"living-documentation": { "type": "http", "url": "http://localhost:4321/mcp" }
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### Claude Desktop
|
|
89
|
+
|
|
90
|
+
Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), puis redémarrer :
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"mcpServers": {
|
|
95
|
+
"living-documentation": { "type": "http", "url": "http://localhost:4321/mcp" }
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Cursor, Continue, tout client MCP
|
|
101
|
+
|
|
102
|
+
Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sans état).
|
|
103
|
+
|
|
104
|
+
> Le serveur Living Documentation doit tourner (`npx living-documentation ./docs`) avant que l'agent ne s'y connecte.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## Concepts centraux
|
|
109
|
+
|
|
110
|
+
- **Markdown sur disque** — chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
|
|
111
|
+
- **Pattern de nom de fichier** — par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`. Configurable ; date, catégorie et titre sont extraits. Les fichiers hors pattern apparaissent sous **General**.
|
|
112
|
+
- **Dossiers → catégories → docs** dans le sidebar. Les noms de dossiers deviennent les libellés ; un préfixe numérique (`1_TUTORIAL`, `2_REFERENCE`) contrôle l'ordre sans s'afficher dans l'UI.
|
|
113
|
+
- **Les ADR** sont le journal canonique des décisions. Le serveur MCP impose un frontmatter normalisé (`**date:**`, `**status:**`, `**description:**`, `**tags:**`) et un statut initial `To be validated` que seul un humain promeut.
|
|
114
|
+
- **`sourceRoot`** désigne le code du projet. Les tools MCP source (`list_source_files`, `read_source_file`, `search_source`) et l'attache de métadonnées en dépendent. Défaut : parent du dossier de doc.
|
|
115
|
+
- **Métadonnées source + jauge de fiabilité** — lier un document à ses fichiers source. Chaque lien stocke un SHA-256. La jauge dans le header (`🔴 → 🟡 → 🟢`) reflète `unchanged / total`. Dès qu'un fichier change ou disparaît, la dérive est visible. Les **god files** (`package.json`, lock files, manifests, barrels) sont exclus par convention.
|
|
116
|
+
- **Les diagrammes sont des vues dérivées** — ils citent les documents qui les justifient (`evidence`). Ils ne peuvent pas introduire un concept absent de la documentation.
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Référence MCP
|
|
121
|
+
|
|
122
|
+
### Tools (19)
|
|
123
|
+
|
|
124
|
+
| Groupe | Tool | Description |
|
|
125
|
+
| --------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
126
|
+
| Onboarding | `get_server_guide` | Retourne le guide du serveur : workflow, conventions, règles des diagrammes. |
|
|
127
|
+
| Documents | `list_documents` | Inventaire : `id`, `title`, `category`, `folder`, `linkHref`. |
|
|
128
|
+
| | `read_document` | Contenu Markdown brut d'un document. |
|
|
129
|
+
| | `create_document` | Crée un nouveau `.md` (nom de fichier dérivé du pattern, paramètre `date` optionnel pour la rétro-doc). |
|
|
130
|
+
| | `update_document` | Écrase un document existant (correction de dérive, supersession). |
|
|
131
|
+
| Diagrammes | `list_diagrams` | Liste les diagrammes sauvegardés. |
|
|
132
|
+
| | `read_diagram` | Lit les nœuds + arêtes d'un diagramme. |
|
|
133
|
+
| | `create_diagram` | Crée / écrase un diagramme (garde-fous serveur : progression C4 et labels d'arêtes). |
|
|
134
|
+
| Code source (fallback) | `list_source_files` | Liste les fichiers sous `sourceRoot` (ignore : `node_modules`, `dist`, `.git`…). |
|
|
135
|
+
| | `read_source_file` | Lit un fichier sous `sourceRoot`. |
|
|
136
|
+
| | `search_source` | Recherche grep-like sous `sourceRoot`. |
|
|
137
|
+
| Métadonnées | `list_metadata` | Fichiers source liés à un document. |
|
|
138
|
+
| | `get_accuracy` | Statut par entrée (`unchanged` / `modified` / `missing`) + accuracy pondérée ∈ [0, 1]. |
|
|
139
|
+
| | `add_metadata` | Attache un fichier source (chemin sous `sourceRoot`), enregistre SHA-256. **Saute les god files.** |
|
|
140
|
+
| | `remove_metadata` | Détache un lien (idempotent — pour renames/deletes). |
|
|
141
|
+
| | `refresh_metadata` | Re-hashe chaque lien (re-baseline après une mise à jour). |
|
|
142
|
+
| Audit ADR | `list_adrs_below_accuracy` | Jusqu'à 10 ADR dont l'accuracy < 80 %, triés du plus dégradé. Exclut `SuperSeeded` et non-ADR. |
|
|
143
|
+
| | `review_adr_relevance` | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state` pour piloter le LLM. |
|
|
144
|
+
| Rétrodocumentation | `retrodocument_adrs_from_git` | Jusqu'à 200 commits git (du plus ancien), classés `candidate` / `trivial` / `merge`, avec flags god-files. Pour backfiller les ADR manquants. |
|
|
145
|
+
|
|
146
|
+
### Prompts (10)
|
|
147
|
+
|
|
148
|
+
| Groupe | Prompt | Quand l'invoquer |
|
|
149
|
+
| -------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
|
150
|
+
| Cycle de vie ADR | `create-adr` | Une feature vient d'être implémentée ou modifiée. Enregistre la décision, supersede l'ADR antérieur si pertinent. |
|
|
151
|
+
| | `audit-adrs-drift` | Audit batch : ramener chaque ADR en dérive à un état clair (re-baseline ou supersession confirmée). |
|
|
152
|
+
| | `review-adr-relevance` | Revue d'un ADR précis contre ses fichiers source liés. |
|
|
153
|
+
| | `retrodocument-adrs-from-git` | Backfill d'ADR depuis l'historique git quand le projet en manque. |
|
|
154
|
+
| Diagrammes | `generate-context-diagram` | DÉFAUT. Diagramme C4 de contexte, gardé serveur. |
|
|
155
|
+
| | `generate-container-diagram` | Sur demande explicite. Diagramme C4 conteneur d'un système. |
|
|
156
|
+
| | `generate-uml-diagram` | Sur demande explicite. UML classe/séquence/état/activité/cas d'usage. |
|
|
157
|
+
| | `generate-screen-guide` | Sur demande explicite. Capture annotée avec post-it callouts. |
|
|
158
|
+
| | `update-diagram-from-docs` | Relit les documents source pour mettre à jour les diagrammes existants. |
|
|
159
|
+
| | `flow`, `erd` | Diagrammes flow linéaires / entité-relation. |
|
|
160
|
+
|
|
161
|
+
Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et prompts pour inspection.
|
|
162
|
+
|
|
163
|
+
---
|
|
164
|
+
|
|
165
|
+
## Fonctionnalités d'édition
|
|
166
|
+
|
|
167
|
+
- **Éditeur inline** — édition de n'importe quel document dans le navigateur, sauvegarde disque instantanée.
|
|
168
|
+
- **Panneau Snippets** (`🧩 Snippets`) — constructions Markdown pré-fabriquées au curseur : blocs repliables, liens (in-doc, cross-doc, ancre), listes, blocs de code, blockquotes, séparateurs, images. Plus un **éditeur de tableaux** (grille dynamique → tableau Markdown aligné) et un **éditeur d'arborescence** (indentation → ASCII tree avec `├──` / `└──`). Sélectionner un snippet existant **détecte son type** et pré-remplit le formulaire pour édition.
|
|
169
|
+
- **Paste d'image** — colle depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, insertion en Markdown.
|
|
170
|
+
- **Pièces jointes** — glisser, déposer, coller ou choisir n'importe quel fichier non-image (PDF, archive, doc bureautique). Upload sous `<docs>/files/`, insertion en pill trombone. Extensions bloquées et limites configurables en Admin.
|
|
171
|
+
- **Recherche plein-texte** — filtre filename instantané + recherche serveur de contenu ; pour chaque fichier liste chaque occurrence, surlignée, navigable.
|
|
172
|
+
- **Préfixe de recherche `metadata://<nomdefichier>`** — recherche inverse : quels documents référencent cette pièce jointe ?
|
|
173
|
+
- **Annotations** — marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
|
|
174
|
+
- **Navigation par ancre** — `[label](#heading-slug)` scrolle correctement après le rendu async ; IDs auto-générés.
|
|
175
|
+
- **Mode sombre** — suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
|
|
176
|
+
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## Éditeur de diagrammes
|
|
184
|
+
|
|
185
|
+
Éditeur de diagrammes canvas intégré (vis-network), accessible via `/diagram?id=...`.
|
|
186
|
+
|
|
187
|
+
- **Progression C4 imposée** — contexte d'abord (défaut), conteneur/composant seulement sur demande explicite. UML sur demande explicite.
|
|
188
|
+
- **`kind` architectural vs `renderAs` visuel** — sépare le concept (`software_system`, `database`, `queue`, `api`, `cloud_service`…) de la forme (`box`, `ellipse`, `database`, `actor`, `post-it`…). Le MCP choisit des défauts sensés pour chaque `kind`.
|
|
189
|
+
- **Provenance documentaire (`evidence`)** — chaque nœud / arête architectural peut citer le document et la section qui le justifient. L'éditeur lève des warnings si l'evidence manque.
|
|
190
|
+
- **Bibliothèques de formes personnalisées** sur `/shape-editor` — définissez vos propres formes (icônes SVG, ports, couleurs par défaut) et réutilisez-les.
|
|
191
|
+
- **Ports** pour arêtes ancrées, **guides d'alignement**, **undo/redo**, **snap-to-grid**, **paste d'image**, **export PNG**, **deep-link** vers un diagramme par id.
|
|
192
|
+
|
|
193
|
+
---
|
|
194
|
+
|
|
195
|
+
## Organisation des fichiers
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
docs/
|
|
199
|
+
├── 2024_01_15_09_30_[DevOps]_deploy.md → catégorie : DevOps
|
|
200
|
+
├── 1_tutorial/ → dossier : Tutorial (préfixe caché dans l'UI)
|
|
201
|
+
│ └── 2024_03_01_10_00_[Onboarding]_setup.md → dossier : Tutorial / catégorie : Onboarding
|
|
202
|
+
├── adrs/
|
|
203
|
+
│ └── 2024_04_01_10_15_[Architecture]_event_sourcing.md
|
|
204
|
+
└── 2_reference/
|
|
205
|
+
└── api.md → dossier : Reference / catégorie : General
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
- Le tag `[Category]` est extrait du filename quel que soit le dossier.
|
|
209
|
+
- Les fichiers sans `[Category]` tombent sous **General**. **General** est toujours rendu en premier.
|
|
210
|
+
- Les dossiers sont triés alphabétiquement — préfixer par `1_`, `2_`… pour forcer un ordre ; le préfixe est caché dans l'UI mais visible au survol.
|
|
211
|
+
- L'imbrication de sous-dossiers est récursive.
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Configuration (`.living-doc.json`)
|
|
218
|
+
|
|
219
|
+
Créé automatiquement dans votre dossier de doc au premier lancement. Modifiable depuis l'Admin ou à la main.
|
|
220
|
+
|
|
221
|
+
```json
|
|
222
|
+
{
|
|
223
|
+
"filenamePattern": "YYYY_MM_DD_HH_mm_[Category]_title",
|
|
224
|
+
"title": "Living Documentation",
|
|
225
|
+
"theme": "system",
|
|
226
|
+
"port": 4321,
|
|
227
|
+
"extraFiles": ["../README.md", "../CLAUDE.md"],
|
|
228
|
+
"sourceRoot": "../src",
|
|
229
|
+
"blockedFileExtensions": [".exe", ".bin"]
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
| Champ | Rôle |
|
|
234
|
+
| ---------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
235
|
+
| `filenamePattern` | Convention de nom de fichier utilisée pour extraire date / catégorie / titre. Le token `[Category]` est obligatoire, exactement une fois. |
|
|
236
|
+
| `extraFiles` | Fichiers Markdown ordonnés **hors** du dossier docs (ex. `README.md`, `CLAUDE.md`). Affichés en premier dans General. |
|
|
237
|
+
| `sourceRoot` | Où vit votre code (relatif au dossier docs). Défaut : `..`. Utilisé par les tools MCP source + métadonnées. |
|
|
238
|
+
| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable en Admin. |
|
|
239
|
+
|
|
240
|
+
**Tous les chemins sont relatifs POSIX** pour que `.living-doc.json` reste portable. Les chemins absolus legacy sont migrés silencieusement à la première lecture.
|
|
241
|
+
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
---
|
|
245
|
+
|
|
246
|
+
## Export
|
|
247
|
+
|
|
248
|
+
| Format | Endpoint | Notes |
|
|
249
|
+
| ------------------------ | ----------------------- | ------------------------------------------------------------------ |
|
|
250
|
+
| PDF (par doc) | `POST /api/export/html` | Boîte de dialogue d'impression du navigateur depuis le HTML rendu. |
|
|
251
|
+
| HTML — mode Notion | `POST /api/export/html` | Bundle HTML unique adapté à l'import Notion. |
|
|
252
|
+
| HTML — mode Confluence | `POST /api/export/html` | Bundle HTML zippé adapté à l'import Confluence. |
|
|
253
|
+
| Bundle Markdown | `POST /api/export/markdown` | Zip de tous les documents avec liens normalisés. |
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Surfaces UI
|
|
258
|
+
|
|
259
|
+
| URL | Page |
|
|
260
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------- |
|
|
261
|
+
| `/` | Viewer — sidebar, rendu document, édition inline, snippets, recherche, pièces jointes. |
|
|
262
|
+
| `/admin` | Config — titre, thème, pattern de filename, extra files, source root, liste de sécurité fichiers. |
|
|
263
|
+
| `/diagram?id=` | Éditeur de diagrammes (vis-network) avec conventions C4, ports, guides d'alignement, undo/redo. |
|
|
264
|
+
| `/shape-editor` | Éditeur de bibliothèques de formes personnalisées — icônes SVG, couleurs par défaut, ports. |
|
|
265
|
+
| `/context` | Page de contexte IA — instructions, règles, mémoire, **explorateur MCP** (tester les tools en live). |
|
|
266
|
+
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## API REST
|
|
272
|
+
|
|
273
|
+
<details>
|
|
274
|
+
<summary>API HTTP complète (cliquer pour déplier)</summary>
|
|
275
|
+
|
|
276
|
+
| Méthode | Endpoint | Description |
|
|
277
|
+
| -------- | ------------------------------ | ------------------------------------------------------------------ |
|
|
278
|
+
| `GET` | `/api/documents` | Liste les documents avec métadonnées (inclut extra files). |
|
|
279
|
+
| `GET` | `/api/documents/:id` | Contenu du document + HTML rendu. |
|
|
280
|
+
| `POST` | `/api/documents` | Crée depuis `{ title, category, folder?, content?, date? }`. |
|
|
281
|
+
| `PUT` | `/api/documents/:id` | Sauvegarde du contenu sur disque. |
|
|
282
|
+
| `DELETE` | `/api/documents/:id` | Supprime un document. |
|
|
283
|
+
| `GET` | `/api/documents/search?q=` | Recherche plein-texte. |
|
|
284
|
+
| `GET` | `/api/config` | Lit la config. |
|
|
285
|
+
| `PUT` | `/api/config` | Met à jour la config (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`, …). |
|
|
286
|
+
| `GET` | `/api/browse?path=` | Liste les dossiers et `.md` à un chemin. |
|
|
287
|
+
| `POST` | `/api/browse/mkdir` | Crée un dossier sous la racine docs. |
|
|
288
|
+
| `POST` | `/api/images/upload` | Upload d'image base64 → `<docs>/images/`. |
|
|
289
|
+
| `POST` | `/api/files/upload` | Upload de pièce jointe base64 → `<docs>/files/`. |
|
|
290
|
+
| `GET` | `/api/files` | Liste toutes les pièces jointes (chronologique). |
|
|
291
|
+
| `PUT` | `/api/files/:filename` | Remplace une pièce jointe. |
|
|
292
|
+
| `DELETE` | `/api/files/:filename` | Supprime une pièce jointe. |
|
|
293
|
+
| `GET` | `/api/metadata/:docId` | Rapport de fiabilité d'un doc. |
|
|
294
|
+
| `POST` | `/api/metadata/:docId` | Ajoute ou remplace un lien. |
|
|
295
|
+
| `DELETE` | `/api/metadata/:docId` | Retire un lien. |
|
|
296
|
+
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline les hashes. |
|
|
297
|
+
| `GET` | `/api/browse-source?path=` | Navigue l'arbre source ancré sur `sourceRoot`. |
|
|
298
|
+
| `GET` | `/api/diagrams` | Liste les diagrammes sauvegardés. |
|
|
299
|
+
| `GET` | `/api/diagrams/:id` | Lit un diagramme (nœuds + arêtes). |
|
|
300
|
+
| `PUT` | `/api/diagrams/:id` | Crée ou met à jour un diagramme. |
|
|
301
|
+
| `DELETE` | `/api/diagrams/:id` | Supprime un diagramme. |
|
|
302
|
+
| `GET` | `/api/shape-libraries` | Liste les bibliothèques de formes personnalisées. |
|
|
303
|
+
| `PUT` | `/api/shape-libraries/:id` | Sauvegarde une bibliothèque de formes. |
|
|
304
|
+
| `GET` | `/api/annotations[/:docId]` | Liste les annotations (tous docs / un doc). |
|
|
305
|
+
| `POST` | `/api/annotations/:docId` | Ajoute une annotation. |
|
|
306
|
+
| `DELETE` | `/api/annotations/:docId/:id` | Supprime une annotation. |
|
|
307
|
+
| `POST` | `/api/export/html` | Export HTML — modes Notion / Confluence. |
|
|
308
|
+
| `POST` | `/api/export/markdown` | Export bundle Markdown. |
|
|
309
|
+
| `GET` | `/api/wordcloud?path=&ext=` | Concatène récursivement les fichiers source filtrés en texte brut. |
|
|
310
|
+
| `POST` | `/mcp` | Endpoint Model Context Protocol (Streamable HTTP). |
|
|
311
|
+
| `GET` | `/mcp` | Résumé live des schémas tools + prompts. |
|
|
312
|
+
|
|
313
|
+
</details>
|
|
314
|
+
|
|
315
|
+
---
|
|
316
|
+
|
|
317
|
+
## Build et test
|
|
318
|
+
|
|
319
|
+
```bash
|
|
320
|
+
git clone https://github.com/craftskillz/living-documentation.git
|
|
321
|
+
cd living-documentation
|
|
322
|
+
npm install
|
|
323
|
+
npm run setup-hooks # une fois : active .githooks/ comme core.hooksPath
|
|
324
|
+
npm run dev -- ./documentation # nodemon + ts-node, watch src + bin
|
|
325
|
+
npm run build # tsc → dist/ + copie des assets frontend
|
|
326
|
+
npm run test:e2e # Playwright end-to-end (~3 s, ~30 specs MCP)
|
|
327
|
+
npm run test:coverage # couverture c8 V8-natif
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
Les tests end-to-end utilisent **Playwright**. Chaque test lance un vrai process CLI enfant sur un fixture frais sur un port aléatoire — pas de fuite d'état, parallélisable. Couverture serveur via **c8** (V8 natif, ~72 % global, 83 % sur `src/routes` et `src/lib`).
|
|
331
|
+
|
|
332
|
+
### Contribuer
|
|
333
|
+
|
|
334
|
+
Ce dépôt embarque un hook `pre-commit` (dans `.githooks/`) qui impose le contrat bilingue des README : si vous touchez `README.md`, vous devez aussi toucher `README.fr.md`, et inversement. Lancez `npm run setup-hooks` une fois après le clone pour l'activer. Le même check tourne en CI sur chaque PR (`.github/workflows/readme-sync.yml`), donc la règle est imposée même si un contributeur oublie le setup local.
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
## Licence
|
|
339
|
+
|
|
340
|
+
[AGPL-3.0](./LICENSE) — © Youssef MEDAGHRI-ALAOUI.
|
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# Living Documentation
|
|
2
2
|
|
|
3
|
+
[🇫🇷 Lire en français](./README.fr.md)
|
|
4
|
+
|
|
3
5
|
> **Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams, and detect drift while you code.**
|
|
4
6
|
|
|
5
7
|
Markdown on disk, no cloud, no database, no build step. Point it at a folder, open `http://localhost:4321`. Plug any MCP-aware AI agent into it (Claude Code, Claude Desktop, Cursor…) and your documentation maintains itself as your code evolves.
|
|
@@ -318,6 +320,7 @@ Created automatically in your docs folder on first run. Edit in the Admin panel
|
|
|
318
320
|
git clone https://github.com/craftskillz/living-documentation.git
|
|
319
321
|
cd living-documentation
|
|
320
322
|
npm install
|
|
323
|
+
npm run setup-hooks # one-time: enable .githooks/ as core.hooksPath
|
|
321
324
|
npm run dev -- ./documentation # nodemon + ts-node, watches src + bin
|
|
322
325
|
npm run build # tsc → dist/ + copy frontend assets
|
|
323
326
|
npm run test:e2e # Playwright end-to-end (~3 s, ~30 MCP specs)
|
|
@@ -326,6 +329,10 @@ npm run test:coverage # c8 V8-native coverage
|
|
|
326
329
|
|
|
327
330
|
End-to-end tests use **Playwright**. Each test spawns a real CLI child process against a fresh fixture on a random port — no leaking state, runs in parallel. Server-side coverage via **c8** (V8 native, ~72% baseline overall, 83% on `src/routes` and `src/lib`).
|
|
328
331
|
|
|
332
|
+
### Contributing
|
|
333
|
+
|
|
334
|
+
This repository ships with a `pre-commit` hook (under `.githooks/`) that enforces the bilingual README contract: if you touch `README.md` you must also touch `README.fr.md`, and vice-versa. Run `npm run setup-hooks` once after cloning to activate it. The same check runs in CI on every PR (see `.github/workflows/readme-sync.yml`), so the rule is enforced even if a contributor forgets the local setup.
|
|
335
|
+
|
|
329
336
|
---
|
|
330
337
|
|
|
331
338
|
## License
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "living-documentation",
|
|
3
|
-
"version": "8.
|
|
3
|
+
"version": "8.11.0",
|
|
4
4
|
"description": "Local Markdown documentation hub with a built-in MCP server — coding agents create ADRs, draw diagrams and detect drift while you code.",
|
|
5
5
|
"main": "dist/src/server.js",
|
|
6
6
|
"bin": {
|
|
@@ -20,6 +20,8 @@
|
|
|
20
20
|
"test:e2e": "npm run build && playwright test",
|
|
21
21
|
"test:e2e:ui": "playwright test --ui",
|
|
22
22
|
"test:coverage": "rm -rf coverage && npm run build && mkdir -p coverage/tmp && COVERAGE=1 NODE_V8_COVERAGE=coverage/tmp playwright test && c8 report",
|
|
23
|
+
"setup-hooks": "git config core.hooksPath .githooks && echo '✓ Git hooks active (.githooks/pre-commit)'",
|
|
24
|
+
"check:readme-sync": "./scripts/check-readme-sync.sh",
|
|
23
25
|
"prepublishOnly": "npm run build"
|
|
24
26
|
},
|
|
25
27
|
"keywords": [
|