living-ai-documentation 3.18.0 → 3.23.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 +138 -134
- package/README.md +4 -0
- package/dist/frontend-svelte/assets/index-B7a9qTDi.js +163 -0
- package/dist/frontend-svelte/assets/index-DxdcDsGV.css +1 -0
- package/dist/frontend-svelte/assets/{main-CCDIOfs_.js → main-wMSA95JC.js} +1 -1
- package/dist/frontend-svelte/i18n/en.json +15 -0
- package/dist/frontend-svelte/i18n/fr.json +15 -0
- package/dist/frontend-svelte/index.html +2 -2
- package/dist/src/lib/documentLanguage.d.ts +6 -0
- package/dist/src/lib/documentLanguage.d.ts.map +1 -0
- package/dist/src/lib/documentLanguage.js +56 -0
- package/dist/src/lib/documentLanguage.js.map +1 -0
- package/dist/src/lib/tts/adapters/kokoro.d.ts +21 -0
- package/dist/src/lib/tts/adapters/kokoro.d.ts.map +1 -0
- package/dist/src/lib/tts/adapters/kokoro.js +93 -0
- package/dist/src/lib/tts/adapters/kokoro.js.map +1 -0
- package/dist/src/lib/tts/index.d.ts +6 -0
- package/dist/src/lib/tts/index.d.ts.map +1 -0
- package/dist/src/lib/tts/index.js +29 -0
- package/dist/src/lib/tts/index.js.map +1 -0
- package/dist/src/lib/tts/types.d.ts +29 -0
- package/dist/src/lib/tts/types.d.ts.map +1 -0
- package/dist/src/lib/tts/types.js +17 -0
- package/dist/src/lib/tts/types.js.map +1 -0
- package/dist/src/routes/tts.d.ts +3 -0
- package/dist/src/routes/tts.d.ts.map +1 -0
- package/dist/src/routes/tts.js +86 -0
- package/dist/src/routes/tts.js.map +1 -0
- package/dist/src/server.d.ts.map +1 -1
- package/dist/src/server.js +2 -0
- package/dist/src/server.js.map +1 -1
- package/package.json +5 -1
- package/dist/frontend-svelte/assets/index--Wi2c37G.css +0 -1
- package/dist/frontend-svelte/assets/index-COhoX4kH.js +0 -162
package/README.fr.md
CHANGED
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
**language:** fr
|
|
3
|
+
---
|
|
4
|
+
|
|
1
5
|
# Living Documentation
|
|
2
6
|
|
|
3
7
|
[🇬🇧 Read in English](./README.md)
|
|
@@ -17,27 +21,27 @@ npx living-ai-documentation@latest ./docs # servir un dossier existant
|
|
|
17
21
|
|
|
18
22
|
---
|
|
19
23
|
|
|
20
|
-
## Deux
|
|
24
|
+
## Deux façons de l'utiliser
|
|
21
25
|
|
|
22
|
-
### 1. Avec un agent IA , la fonctionnalité phare
|
|
26
|
+
### 1. Avec un agent de code IA , la fonctionnalité phare
|
|
23
27
|
|
|
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.
|
|
28
|
+
Living Documentation embarque un **serveur MCP** sur `POST /mcp`. N'importe quel agent compatible MCP peut lire, créer et auditer la documentation de votre projet de façon autonome.
|
|
25
29
|
|
|
26
|
-
|
|
|
27
|
-
| ------------------------------------------------------------ | ----------------------------- |
|
|
28
|
-
| _« feature
|
|
29
|
-
| _«
|
|
30
|
-
| _« vérifie la pertinence de cet ADR »_
|
|
31
|
-
| _«
|
|
32
|
-
| _«
|
|
30
|
+
| Vous dites… | L'agent déclenche… | Ce qui se passe |
|
|
31
|
+
| ------------------------------------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| _« feature done »_ / _« feature terminée »_ | `create-adr` | Cherche les ADR existants, supplante l'ADR obsolète s'il y en a un, écrit un nouvel ADR en `To be validated`, attache les fichiers source via les métadonnées. |
|
|
33
|
+
| _« audit the ADRs »_ / _« vérifie la fiabilité des ADR »_ | `audit-adrs-drift` | Liste chaque ADR sous 80 % de fiabilité et remet chacun en cohérence , re-baseline ou supersession après votre confirmation. |
|
|
34
|
+
| _« review this ADR »_ / _« vérifie la pertinence de cet ADR »_ | `review-adr-relevance` | Examine un seul ADR à la lumière des fichiers source liés ; rafraîchit les hashes ou propose la supersession. |
|
|
35
|
+
| _« backfill ADRs from git »_ / _« retrodocumente depuis 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 qui n'ont jamais été documentées. |
|
|
36
|
+
| _« give me the big picture »_ | `generate-context-diagram` | Crée un diagramme C4 de contexte **dérivé des documents**, jamais inventé. |
|
|
33
37
|
|
|
34
38
|
**Tous les nouveaux ADR atterrissent en `To be validated`.** _Vous_ les promouvez. L'agent ne promeut jamais à votre place.
|
|
35
39
|
|
|
36
|
-
### 2.
|
|
40
|
+
### 2. En solo, sans IA
|
|
37
41
|
|
|
38
|
-
Un hub
|
|
42
|
+
Un hub de documentation personnel : ADR, notes de réunion, journaux de développement, plans de fonctionnalités, esquisses d'architecture , tout reste en Markdown sur disque, git-friendly, zéro vendor lock-in. Édition inline, snippets, collage d'image, pièces jointes, éditeur de diagrammes, recherche plein-texte, export PDF/HTML/Notion/Confluence.
|
|
39
43
|
|
|
40
|
-
Les deux modes se mélangent :
|
|
44
|
+
Les deux modes se mélangent librement : prenez des notes en solo toute la semaine, puis laissez votre agent enregistrer l'ADR quand la fonctionnalité est effectivement livrée.
|
|
41
45
|
|
|
42
46
|
---
|
|
43
47
|
|
|
@@ -45,7 +49,7 @@ Les deux modes se mélangent : prendre des notes en solo toute la semaine, puis
|
|
|
45
49
|
|
|
46
50
|
```bash
|
|
47
51
|
# 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
|
|
52
|
+
# AGENTS.md / CLAUDE.md / memory/MEMORY.md à la racine du projet et crée des symlinks
|
|
49
53
|
# dans <docs>/AI/ pour que les agents IA les trouvent.
|
|
50
54
|
npx living-ai-documentation@latest
|
|
51
55
|
|
|
@@ -54,22 +58,22 @@ npx living-ai-documentation@latest ./docs
|
|
|
54
58
|
npx living-ai-documentation@latest ./docs --port 4000 --open
|
|
55
59
|
```
|
|
56
60
|
|
|
57
|
-
|
|
61
|
+
Ensuite ouvrez [http://localhost:4321](http://localhost:4321) (viewer) et [http://localhost:4321/admin](http://localhost:4321/admin) (config).
|
|
58
62
|
|
|
59
|
-
>
|
|
63
|
+
> L'argument du dossier doit être un **chemin relatif** (`./docs`, `../shared/docs`…). Les chemins absolus et `~` sont rejetés pour que le fichier `.living-doc.json` généré reste portable et puisse être commité.
|
|
60
64
|
|
|
61
65
|
### Installation
|
|
62
66
|
|
|
63
67
|
Nécessite **Node.js 20.19 ou plus récent** (Vite 8 et Commander 14 ne prennent plus en charge Node.js 18).
|
|
64
68
|
|
|
65
69
|
```bash
|
|
66
|
-
npx living-ai-documentation@latest #
|
|
70
|
+
npx living-ai-documentation@latest # zéro installation
|
|
67
71
|
npm install -g living-ai-documentation # global
|
|
68
72
|
```
|
|
69
73
|
|
|
70
74
|
---
|
|
71
75
|
|
|
72
|
-
##
|
|
76
|
+
## Connectez votre agent IA
|
|
73
77
|
|
|
74
78
|
### Claude Code
|
|
75
79
|
|
|
@@ -92,7 +96,7 @@ Ou manuellement dans `.claude/settings.json` :
|
|
|
92
96
|
|
|
93
97
|
### Claude Desktop
|
|
94
98
|
|
|
95
|
-
Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), puis
|
|
99
|
+
Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS), puis redémarrez :
|
|
96
100
|
|
|
97
101
|
```json
|
|
98
102
|
{
|
|
@@ -107,21 +111,21 @@ Dans `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS),
|
|
|
107
111
|
|
|
108
112
|
### Cursor, Continue, tout client MCP
|
|
109
113
|
|
|
110
|
-
|
|
114
|
+
Utilisez le même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sans état).
|
|
111
115
|
|
|
112
|
-
> Le serveur Living Documentation doit
|
|
116
|
+
> Le serveur Living Documentation doit être lancé en premier (`npx living-ai-documentation@latest ./docs`) avant que l'agent ne se connecte.
|
|
113
117
|
|
|
114
118
|
---
|
|
115
119
|
|
|
116
|
-
## Concepts
|
|
120
|
+
## Concepts clés
|
|
117
121
|
|
|
118
122
|
- **Markdown sur disque** , chaque document est un fichier `.md`. La configuration vit dans `.living-doc.json` à côté. Les deux sont git-friendly.
|
|
119
|
-
- **Pattern de nom de fichier** , par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`.
|
|
120
|
-
- **Dossiers → catégories → docs** dans
|
|
121
|
-
- **Les ADR** sont
|
|
122
|
-
- **`sourceRoot`**
|
|
123
|
-
- **Métadonnées source + jauge de fiabilité** ,
|
|
124
|
-
- **Les diagrammes sont des vues dérivées** , ils citent les documents
|
|
123
|
+
- **Pattern de nom de fichier** , par défaut `YYYY_MM_DD_HH_mm_[Category]_title.md`. Le pattern est configurable ; la date, la catégorie et le titre sont extraits. Les fichiers qui ne correspondent pas apparaissent sous **General**.
|
|
124
|
+
- **Dossiers → catégories → docs** dans la barre latérale. Les noms de dossiers deviennent les libellés ; les préfixes numériques (`1_TUTORIAL`, `2_REFERENCE`) contrôlent l'ordre sans s'afficher dans l'UI.
|
|
125
|
+
- **Les ADR** sont l'enregistrement 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 peut promouvoir.
|
|
126
|
+
- **`sourceRoot`** pointe vers 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. Valeur par défaut : le parent du dossier de documentation.
|
|
127
|
+
- **Métadonnées de fichiers source + jauge de fiabilité** , liez un document aux fichiers source qu'il décrit. Chaque liaison stocke un SHA-256. La jauge dans l'en-tête du document (`🔴 → 🟡 → 🟢`) reflète le ratio `unchanged / total`. Dès qu'un fichier lié est modifié ou supprimé, la dérive est visible. Les **god files** (`package.json`, lock files, manifests, barrels) sont exclus par convention.
|
|
128
|
+
- **Les diagrammes sont des vues dérivées** , ils citent les documents sur lesquels ils s'appuient (`evidence`). Ils ne peuvent pas introduire des concepts absents de la documentation.
|
|
125
129
|
|
|
126
130
|
---
|
|
127
131
|
|
|
@@ -131,56 +135,56 @@ Même endpoint HTTP : `http://localhost:4321/mcp` (transport Streamable HTTP, sa
|
|
|
131
135
|
|
|
132
136
|
| Groupe | Tool | Description |
|
|
133
137
|
| ---------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
-
| Onboarding | `get_server_guide` | Retourne le guide du serveur : workflow, conventions, règles
|
|
138
|
+
| Onboarding | `get_server_guide` | Retourne le guide du serveur : workflow, conventions, règles de diagrammes. |
|
|
135
139
|
| Documents | `list_documents` | Inventaire : `id`, `title`, `category`, `folder`, `linkHref`. |
|
|
136
140
|
| | `read_document` | Contenu Markdown brut d'un document. |
|
|
137
|
-
| | `create_document` | Crée un nouveau `.md` (nom de fichier dérivé du pattern
|
|
141
|
+
| | `create_document` | Crée un nouveau fichier `.md` (nom de fichier dérivé du pattern configuré, paramètre `date` optionnel pour la rétrodocumentation). |
|
|
138
142
|
| | `update_document` | Écrase un document existant (correction de dérive, supersession). |
|
|
139
143
|
| Diagrammes | `list_diagrams` | Liste les diagrammes sauvegardés. |
|
|
140
144
|
| | `read_diagram` | Lit les nœuds + arêtes d'un diagramme. |
|
|
141
|
-
| | `create_diagram` | Crée / écrase un diagramme (garde-fous serveur
|
|
145
|
+
| | `create_diagram` | Crée / écrase un diagramme (garde-fous côté serveur appliquent la progression C4 et les labels d'arêtes). |
|
|
142
146
|
| Code source (fallback) | `list_source_files` | Liste les fichiers sous `sourceRoot` (ignore : `node_modules`, `dist`, `.git`…). |
|
|
143
147
|
| | `read_source_file` | Lit un fichier sous `sourceRoot`. |
|
|
144
|
-
| | `search_source` | Recherche grep
|
|
145
|
-
| Métadonnées | `list_metadata` |
|
|
148
|
+
| | `search_source` | Recherche texte de type grep sous `sourceRoot`. |
|
|
149
|
+
| Métadonnées | `list_metadata` | Liaisons de fichiers source d'un document. |
|
|
146
150
|
| | `get_accuracy` | Statut par entrée (`unchanged` / `modified` / `missing`) + accuracy pondérée ∈ [0, 1]. |
|
|
147
|
-
| | `add_metadata` |
|
|
148
|
-
| | `remove_metadata` | Détache
|
|
149
|
-
| | `refresh_metadata` | Re-hashe chaque
|
|
150
|
-
| Audit ADR | `list_adrs_below_accuracy` | Jusqu'à 10 ADR dont l'accuracy < 80 %, triés du plus dégradé. Exclut `SuperSeeded` et non-ADR.
|
|
151
|
-
| | `review_adr_relevance` | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state`
|
|
152
|
-
| Rétrodocumentation | `retrodocument_adrs_from_git` | Jusqu'à 200 commits git (du plus ancien)
|
|
151
|
+
| | `add_metadata` | Lie un fichier source (chemin sous `sourceRoot`), enregistre le SHA-256. **Ignore les god files.** |
|
|
152
|
+
| | `remove_metadata` | Détache une liaison (idempotent , pour les renommages/suppressions). |
|
|
153
|
+
| | `refresh_metadata` | Re-hashe chaque liaison (re-baseline après une mise à jour). |
|
|
154
|
+
| Audit ADR | `list_adrs_below_accuracy` | Jusqu'à 10 ADR dont l'accuracy < 80 %, triés du plus dégradé au moins dégradé. Exclut `SuperSeeded` et les non-ADR. |
|
|
155
|
+
| | `review_adr_relevance` | Rapport factuel sur un ADR + fichiers en dérive à relire. Retourne un `state` qui pilote l'arbre de décision du LLM. |
|
|
156
|
+
| Rétrodocumentation | `retrodocument_adrs_from_git` | Jusqu'à 200 commits git (du plus ancien) classés `candidate` / `trivial` / `merge`, avec flags god-file. Pour backfiller les ADR manquants. |
|
|
153
157
|
|
|
154
158
|
### Prompts (10)
|
|
155
159
|
|
|
156
|
-
| Groupe | Prompt | Quand
|
|
157
|
-
| ---------------- | ----------------------------- |
|
|
158
|
-
| Cycle de vie ADR | `create-adr` | Une
|
|
159
|
-
| | `audit-adrs-drift` | Audit
|
|
160
|
-
| | `review-adr-relevance` |
|
|
161
|
-
| | `retrodocument-adrs-from-git` | Backfill d'ADR depuis l'historique git quand le projet en manque.
|
|
162
|
-
| Diagrammes | `generate-context-diagram` | DÉFAUT. Diagramme C4 de contexte, gardé serveur.
|
|
163
|
-
| | `generate-container-diagram` | Sur demande explicite. Diagramme C4 conteneur d'un système.
|
|
164
|
-
| | `generate-uml-diagram` | Sur demande explicite. UML classe/séquence/état/activité/cas d'
|
|
165
|
-
| | `generate-screen-guide` | Sur demande explicite. Capture annotée avec post-it
|
|
166
|
-
| | `update-diagram-from-docs` | Relit les documents source pour mettre à jour les diagrammes existants.
|
|
167
|
-
| | `flow`, `erd` | Diagrammes
|
|
168
|
-
|
|
169
|
-
Un `GET http://localhost:4321/mcp` retourne les schémas live des tools
|
|
160
|
+
| Groupe | Prompt | Quand |
|
|
161
|
+
| ---------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
162
|
+
| Cycle de vie ADR | `create-adr` | Une fonctionnalité vient d'être implémentée ou modifiée. Enregistre la décision, supplante un ADR antérieur le cas échéant. |
|
|
163
|
+
| | `audit-adrs-drift` | Audit par lot : ramener chaque ADR en dérive à un état clair (re-baseline ou supersession confirmée par l'utilisateur). |
|
|
164
|
+
| | `review-adr-relevance` | Examen d'un seul ADR à la lumière des fichiers source liés. |
|
|
165
|
+
| | `retrodocument-adrs-from-git` | Backfill d'ADR depuis l'historique git quand le projet en manque. |
|
|
166
|
+
| Diagrammes | `generate-context-diagram` | DÉFAUT. Diagramme C4 de contexte, gardé côté serveur. |
|
|
167
|
+
| | `generate-container-diagram` | Sur demande explicite uniquement. Diagramme C4 de conteneur d'un système. |
|
|
168
|
+
| | `generate-uml-diagram` | Sur demande explicite uniquement. UML classe/séquence/état/activité/cas d'utilisation. |
|
|
169
|
+
| | `generate-screen-guide` | Sur demande explicite uniquement. Capture d'écran annotée avec callouts post-it. |
|
|
170
|
+
| | `update-diagram-from-docs` | Relit les documents source pour mettre à jour les diagrammes existants. |
|
|
171
|
+
| | `flow`, `erd` | Diagrammes de flux linéaire / entité-relation. |
|
|
172
|
+
|
|
173
|
+
Un `GET http://localhost:4321/mcp` retourne les schémas live des tools + prompts pour inspection.
|
|
170
174
|
|
|
171
175
|
---
|
|
172
176
|
|
|
173
177
|
## Fonctionnalités d'édition
|
|
174
178
|
|
|
175
|
-
- **Éditeur inline** ,
|
|
176
|
-
- **Panneau Snippets** (`🧩 Snippets`) , constructions Markdown
|
|
177
|
-
- **
|
|
178
|
-
- **Pièces jointes** ,
|
|
179
|
-
- **Recherche plein-texte** , filtre
|
|
180
|
-
- **Préfixe de recherche `metadata://<nomdefichier>`** , recherche
|
|
179
|
+
- **Éditeur inline** , éditez n'importe quel document dans le navigateur, sauvegarde instantanée sur disque.
|
|
180
|
+
- **Panneau Snippets** (`🧩 Snippets`) , constructions Markdown préfabriquées au curseur : blocs repliables, liens (intra-doc, inter-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 → arbre ASCII avec `├──` / `└──`). Sélectionner un snippet existant **détecte son type** et pré-remplit le formulaire pour édition.
|
|
181
|
+
- **Collage d'image** , collez depuis le presse-papier pendant l'édition, auto-upload vers `<docs>/images/`, inséré en Markdown.
|
|
182
|
+
- **Pièces jointes** , glissez, déposez, collez ou choisissez tout fichier non-image (PDF, archive, document bureautique). Uploadé sous `<docs>/files/`, inséré comme un pill trombone. Extensions bloquées et limites de taille configurables dans l'Admin.
|
|
183
|
+
- **Recherche plein-texte** , filtre instantané par nom de fichier + recherche serveur dans le contenu ; pour chaque fichier, liste chaque occurrence, les surligne et permet de naviguer vers elles.
|
|
184
|
+
- **Préfixe de recherche `metadata://<nomdefichier>`** , recherche inversée : quels documents référencent cette pièce jointe ?
|
|
181
185
|
- **Annotations** , marqueurs de surlignage persistants par document (jaune / rose / vert / bleu).
|
|
182
|
-
- **Navigation par ancre** , `[label](#heading-slug)` scrolle correctement après
|
|
183
|
-
- **Mode sombre** , suit la préférence système, basculable manuellement. Coloration syntaxique toujours sombre.
|
|
186
|
+
- **Navigation par ancre** , `[label](#heading-slug)` scrolle correctement après rendu asynchrone ; IDs auto-générés.
|
|
187
|
+
- **Mode sombre** , suit la préférence système, basculable manuellement. Coloration syntaxique toujours en mode sombre.
|
|
184
188
|
|
|
185
189
|
|
|
186
190
|
|
|
@@ -192,11 +196,11 @@ Un `GET http://localhost:4321/mcp` retourne les schémas live des tools et promp
|
|
|
192
196
|
|
|
193
197
|
Éditeur de diagrammes canvas intégré (vis-network), accessible via `/diagram?id=...`.
|
|
194
198
|
|
|
195
|
-
- **Progression C4 imposée** , contexte d'abord (défaut), conteneur/composant
|
|
196
|
-
- **`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
|
|
197
|
-
- **Provenance documentaire (`evidence`)** , chaque nœud
|
|
198
|
-
- **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.
|
|
199
|
-
- **Ports** pour arêtes ancrées, **guides d'alignement**, **undo/redo**, **snap-to-grid**, **
|
|
199
|
+
- **Progression C4 imposée** , contexte d'abord (défaut), conteneur/composant uniquement sur demande explicite. UML sur demande explicite.
|
|
200
|
+
- **`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 valeurs par défaut pertinentes pour chaque `kind`.
|
|
201
|
+
- **Provenance documentaire (`evidence`)** , chaque nœud/arête architectural peut citer le document et la section qui le justifient. L'éditeur signale les warnings d'evidence manquante.
|
|
202
|
+
- **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 dans tous les diagrammes.
|
|
203
|
+
- **Ports** pour arêtes ancrées, **guides d'alignement**, **undo/redo**, **snap-to-grid**, **collage d'images**, **export PNG**, **deep-link** vers un diagramme par id.
|
|
200
204
|
|
|
201
205
|
---
|
|
202
206
|
|
|
@@ -213,18 +217,18 @@ docs/
|
|
|
213
217
|
└── api.md → dossier : Reference / catégorie : General
|
|
214
218
|
```
|
|
215
219
|
|
|
216
|
-
- Le tag `[Category]` est extrait du
|
|
220
|
+
- Le tag `[Category]` est extrait du nom de fichier quel que soit le dossier.
|
|
217
221
|
- Les fichiers sans `[Category]` tombent sous **General**. **General** est toujours rendu en premier.
|
|
218
|
-
- Les dossiers sont triés alphabétiquement ,
|
|
219
|
-
- L'imbrication de sous-dossiers est
|
|
222
|
+
- Les dossiers sont triés alphabétiquement , préfixez par `1_`, `2_`… pour forcer un ordre ; le préfixe est caché dans l'UI mais visible au survol.
|
|
223
|
+
- L'imbrication de sous-dossiers est supportée récursivement.
|
|
220
224
|
|
|
221
|
-
|
|
222
226
|
|
|
223
227
|
---
|
|
224
228
|
|
|
225
229
|
## Configuration (`.living-doc.json`)
|
|
226
230
|
|
|
227
|
-
Créé automatiquement dans votre dossier de
|
|
231
|
+
Créé automatiquement dans votre dossier de documentation au premier lancement. Modifiable depuis l'Admin ou à la main.
|
|
228
232
|
|
|
229
233
|
```json
|
|
230
234
|
{
|
|
@@ -238,12 +242,12 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
|
|
|
238
242
|
}
|
|
239
243
|
```
|
|
240
244
|
|
|
241
|
-
| Champ | Rôle
|
|
242
|
-
| ----------------------- |
|
|
243
|
-
| `filenamePattern` | Convention de nom de fichier utilisée pour extraire date / catégorie / titre. Le token `[Category]` est obligatoire, exactement une fois.
|
|
244
|
-
| `extraFiles` | Fichiers Markdown ordonnés **hors** du dossier docs (ex. `README.md`, `CLAUDE.md`). Affichés en premier dans General.
|
|
245
|
-
| `sourceRoot` | Où vit votre code (relatif au dossier docs). Défaut : `..`. Utilisé par les tools MCP source + métadonnées.
|
|
246
|
-
| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable
|
|
245
|
+
| Champ | Rôle |
|
|
246
|
+
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
247
|
+
| `filenamePattern` | Convention de nom de fichier utilisée pour extraire date / catégorie / titre. Le token `[Category]` est obligatoire, exactement une fois. |
|
|
248
|
+
| `extraFiles` | Fichiers Markdown ordonnés **hors** du dossier docs (ex. `README.md`, `CLAUDE.md`). Affichés en premier dans General. |
|
|
249
|
+
| `sourceRoot` | Où vit votre code (relatif au dossier docs). Défaut : `..`. Utilisé par les tools MCP source + métadonnées. |
|
|
250
|
+
| `blockedFileExtensions` | Liste de sécurité des extensions de pièces jointes, éditable depuis l'Admin. |
|
|
247
251
|
|
|
248
252
|
**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.
|
|
249
253
|
|
|
@@ -253,24 +257,24 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
|
|
|
253
257
|
|
|
254
258
|
## Export
|
|
255
259
|
|
|
256
|
-
| Format
|
|
257
|
-
|
|
|
258
|
-
| PDF (par
|
|
259
|
-
| HTML , mode Notion
|
|
260
|
-
| HTML , mode Confluence
|
|
261
|
-
| Bundle Markdown
|
|
260
|
+
| Format | Endpoint | Notes |
|
|
261
|
+
| ----------------------- | --------------------------- | ------------------------------------------------------------------ |
|
|
262
|
+
| PDF (par document) | `POST /api/export/html` | Boîte de dialogue d'impression du navigateur depuis le HTML rendu. |
|
|
263
|
+
| HTML , mode Notion | `POST /api/export/html` | Bundle HTML unique adapté à l'import Notion. |
|
|
264
|
+
| HTML , mode Confluence | `POST /api/export/html` | Bundle HTML zippé adapté à l'import Confluence. |
|
|
265
|
+
| Bundle Markdown | `POST /api/export/markdown` | Zip de tous les documents avec liens normalisés. |
|
|
262
266
|
|
|
263
267
|
---
|
|
264
268
|
|
|
265
|
-
## Surfaces UI
|
|
269
|
+
## Surfaces de l'UI
|
|
266
270
|
|
|
267
|
-
| URL | Page
|
|
268
|
-
| --------------- |
|
|
269
|
-
| `/` | Viewer , sidebar, rendu document, édition inline, snippets, recherche, pièces jointes.
|
|
270
|
-
| `/admin` | Config , titre, thème, pattern de
|
|
271
|
-
| `/diagram?id=` | Éditeur de diagrammes (vis-network) avec conventions C4, ports, guides d'alignement, undo/redo.
|
|
272
|
-
| `/shape-editor` | Éditeur de bibliothèques de formes personnalisées , icônes SVG, couleurs par défaut, ports.
|
|
273
|
-
| `/context` | Page de contexte IA , instructions, règles, mémoire, **explorateur MCP** (
|
|
271
|
+
| URL | Page |
|
|
272
|
+
| --------------- | --------------------------------------------------------------------------------------------------------- |
|
|
273
|
+
| `/` | Viewer , sidebar, rendu de document, édition inline, snippets, recherche, pièces jointes. |
|
|
274
|
+
| `/admin` | Config , titre, thème, pattern de nom de fichier, extra files, source root, liste de sécurité des fichiers. |
|
|
275
|
+
| `/diagram?id=` | Éditeur de diagrammes (vis-network) avec conventions C4, ports, guides d'alignement, undo/redo. |
|
|
276
|
+
| `/shape-editor` | Éditeur de bibliothèques de formes personnalisées , icônes SVG, couleurs par défaut, ports. |
|
|
277
|
+
| `/context` | Page de contexte IA , instructions, règles, mémoire, **explorateur MCP** (testez les tools en live dans le navigateur). |
|
|
274
278
|
|
|
275
279
|
---
|
|
276
280
|
|
|
@@ -279,42 +283,42 @@ Créé automatiquement dans votre dossier de doc au premier lancement. Modifiabl
|
|
|
279
283
|
<details>
|
|
280
284
|
<summary>API HTTP complète (cliquer pour déplier)</summary>
|
|
281
285
|
|
|
282
|
-
| Méthode | Endpoint | Description
|
|
283
|
-
| -------- | ------------------------------ |
|
|
284
|
-
| `GET` | `/api/documents` | Liste les documents avec métadonnées (inclut extra files).
|
|
285
|
-
| `GET` | `/api/documents/:id` | Contenu du document + HTML rendu.
|
|
286
|
-
| `POST` | `/api/documents` | Crée
|
|
287
|
-
| `PUT` | `/api/documents/:id` | Sauvegarde
|
|
288
|
-
| `DELETE` | `/api/documents/:id` | Supprime un document.
|
|
289
|
-
| `GET` | `/api/documents/search?q=` | Recherche plein-texte.
|
|
290
|
-
| `GET` | `/api/config` | Lit la
|
|
291
|
-
| `PUT` | `/api/config` | Met à jour la
|
|
292
|
-
| `GET` | `/api/browse?path=` | Liste les dossiers et `.md` à un chemin
|
|
293
|
-
| `POST` | `/api/browse/mkdir` | Crée un dossier sous la racine docs.
|
|
294
|
-
| `POST` | `/api/images/upload` | Upload d'image base64 → `<docs>/images/`.
|
|
295
|
-
| `POST` | `/api/files/upload` | Upload
|
|
296
|
-
| `GET` | `/api/files` | Liste toutes les pièces jointes (chronologique). |
|
|
297
|
-
| `PUT` | `/api/files/:filename` | Remplace une pièce jointe.
|
|
298
|
-
| `DELETE` | `/api/files/:filename` | Supprime une pièce jointe.
|
|
299
|
-
| `GET` | `/api/metadata/:docId` | Rapport de fiabilité
|
|
300
|
-
| `POST` | `/api/metadata/:docId` | Ajoute ou remplace
|
|
301
|
-
| `DELETE` | `/api/metadata/:docId` | Retire
|
|
302
|
-
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline les hashes.
|
|
303
|
-
| `GET` | `/api/browse-source?path=` | Navigue l'arbre source ancré sur `sourceRoot`.
|
|
304
|
-
| `GET` | `/api/diagrams` | Liste les diagrammes sauvegardés.
|
|
305
|
-
| `GET` | `/api/diagrams/:id` | Lit un diagramme (nœuds + arêtes).
|
|
306
|
-
| `PUT` | `/api/diagrams/:id` | Crée ou met à jour un diagramme.
|
|
307
|
-
| `DELETE` | `/api/diagrams/:id` | Supprime un diagramme.
|
|
308
|
-
| `GET` | `/api/shape-libraries` | Liste les bibliothèques de formes personnalisées.
|
|
309
|
-
| `PUT` | `/api/shape-libraries/:id` | Sauvegarde une bibliothèque de formes.
|
|
310
|
-
| `GET` | `/api/annotations[/:docId]` | Liste les annotations (tous docs / un doc).
|
|
311
|
-
| `POST` | `/api/annotations/:docId` | Ajoute une annotation.
|
|
312
|
-
| `DELETE` | `/api/annotations/:docId/:id` | Supprime une annotation.
|
|
313
|
-
| `POST` | `/api/export/html` | Export HTML , modes Notion / Confluence.
|
|
314
|
-
| `POST` | `/api/export/markdown` | Export bundle Markdown.
|
|
315
|
-
| `GET` | `/api/wordcloud?path=&ext=` | Concatène récursivement les fichiers source
|
|
316
|
-
| `POST` | `/mcp` | Endpoint Model Context Protocol (Streamable HTTP).
|
|
317
|
-
| `GET` | `/mcp` | Résumé live des schémas tools + prompts.
|
|
286
|
+
| Méthode | Endpoint | Description |
|
|
287
|
+
| -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
|
|
288
|
+
| `GET` | `/api/documents` | Liste les documents avec métadonnées (inclut les extra files). |
|
|
289
|
+
| `GET` | `/api/documents/:id` | Contenu du document + HTML rendu. |
|
|
290
|
+
| `POST` | `/api/documents` | Crée à partir de `{ title, category, folder?, content?, date? }`. |
|
|
291
|
+
| `PUT` | `/api/documents/:id` | Sauvegarde le contenu sur disque. |
|
|
292
|
+
| `DELETE` | `/api/documents/:id` | Supprime un document. |
|
|
293
|
+
| `GET` | `/api/documents/search?q=` | Recherche plein-texte. |
|
|
294
|
+
| `GET` | `/api/config` | Lit la configuration. |
|
|
295
|
+
| `PUT` | `/api/config` | Met à jour la configuration (`title`, `theme`, `filenamePattern`, `extraFiles`, `sourceRoot`, `blockedFileExtensions`…). |
|
|
296
|
+
| `GET` | `/api/browse?path=` | Liste les dossiers et fichiers `.md` à un chemin donné. |
|
|
297
|
+
| `POST` | `/api/browse/mkdir` | Crée un dossier sous la racine docs. |
|
|
298
|
+
| `POST` | `/api/images/upload` | Upload d'une image base64 → `<docs>/images/`. |
|
|
299
|
+
| `POST` | `/api/files/upload` | Upload d'une pièce jointe base64 → `<docs>/files/`. |
|
|
300
|
+
| `GET` | `/api/files` | Liste toutes les pièces jointes (ordre chronologique). |
|
|
301
|
+
| `PUT` | `/api/files/:filename` | Remplace une pièce jointe. |
|
|
302
|
+
| `DELETE` | `/api/files/:filename` | Supprime une pièce jointe. |
|
|
303
|
+
| `GET` | `/api/metadata/:docId` | Rapport de fiabilité pour un document. |
|
|
304
|
+
| `POST` | `/api/metadata/:docId` | Ajoute ou remplace une liaison. |
|
|
305
|
+
| `DELETE` | `/api/metadata/:docId` | Retire une liaison. |
|
|
306
|
+
| `POST` | `/api/metadata/:docId/refresh` | Re-baseline les hashes. |
|
|
307
|
+
| `GET` | `/api/browse-source?path=` | Navigue dans l'arbre source ancré sur `sourceRoot`. |
|
|
308
|
+
| `GET` | `/api/diagrams` | Liste les diagrammes sauvegardés. |
|
|
309
|
+
| `GET` | `/api/diagrams/:id` | Lit un diagramme (nœuds + arêtes). |
|
|
310
|
+
| `PUT` | `/api/diagrams/:id` | Crée ou met à jour un diagramme. |
|
|
311
|
+
| `DELETE` | `/api/diagrams/:id` | Supprime un diagramme. |
|
|
312
|
+
| `GET` | `/api/shape-libraries` | Liste les bibliothèques de formes personnalisées. |
|
|
313
|
+
| `PUT` | `/api/shape-libraries/:id` | Sauvegarde une bibliothèque de formes. |
|
|
314
|
+
| `GET` | `/api/annotations[/:docId]` | Liste les annotations (tous les docs / un doc). |
|
|
315
|
+
| `POST` | `/api/annotations/:docId` | Ajoute une annotation. |
|
|
316
|
+
| `DELETE` | `/api/annotations/:docId/:id` | Supprime une annotation. |
|
|
317
|
+
| `POST` | `/api/export/html` | Export HTML , modes Notion / Confluence. |
|
|
318
|
+
| `POST` | `/api/export/markdown` | Export bundle Markdown. |
|
|
319
|
+
| `GET` | `/api/wordcloud?path=&ext=` | Concatène récursivement les fichiers source correspondants en texte brut. |
|
|
320
|
+
| `POST` | `/mcp` | Endpoint Model Context Protocol (Streamable HTTP). |
|
|
321
|
+
| `GET` | `/mcp` | Résumé live des schémas tools + prompts. |
|
|
318
322
|
|
|
319
323
|
</details>
|
|
320
324
|
|
|
@@ -333,16 +337,16 @@ npm run test:e2e # Playwright end-to-end (~3 s, ~30 spec
|
|
|
333
337
|
npm run test:coverage # couverture c8 V8-natif
|
|
334
338
|
```
|
|
335
339
|
|
|
336
|
-
En **dev**, ouvrez l'UI sur **http://localhost:5174** (Vite sert l'app Svelte avec HMR et
|
|
340
|
+
En **dev**, ouvrez l'UI sur **http://localhost:5174** (Vite sert l'app Svelte avec HMR et proxifie `/api`, `/mcp`, `/images`, `/files` vers le backend Express sur `:4321`).
|
|
337
341
|
|
|
338
|
-
Les tests end-to-end utilisent **Playwright**. Chaque test lance un vrai
|
|
342
|
+
Les tests end-to-end utilisent **Playwright**. Chaque test lance un vrai processus CLI enfant sur un fixture frais sur un port aléatoire , pas de fuite d'état, exécution en parallèle. Couverture côté serveur via **c8** (V8 natif, ~72 % de référence globale, 83 % sur `src/routes` et `src/lib`).
|
|
339
343
|
|
|
340
344
|
### Tester le package publié en local
|
|
341
345
|
|
|
342
|
-
Pas besoin de publier une version. Le CLI démarre un **
|
|
346
|
+
Pas besoin de publier une version. Le CLI démarre un **serveur Express unique** qui sert l'UI Svelte pré-buildée **et** l'API/MCP sur un seul port , Vite (`:5174`) est uniquement pour le développement et n'existe pas pour les utilisateurs finaux.
|
|
343
347
|
|
|
344
348
|
```bash
|
|
345
|
-
#
|
|
349
|
+
# Lancer l'artefact de production exact, puis ouvrir http://localhost:4321
|
|
346
350
|
npm run build
|
|
347
351
|
node dist/bin/cli.js ./documentation
|
|
348
352
|
|
|
@@ -350,17 +354,17 @@ node dist/bin/cli.js ./documentation
|
|
|
350
354
|
npm pack # → living-ai-documentation-<version>.tgz
|
|
351
355
|
npx ./living-ai-documentation-*.tgz ./documentation
|
|
352
356
|
|
|
353
|
-
npm pack --dry-run # inspecter exactement
|
|
357
|
+
npm pack --dry-run # inspecter exactement quels fichiers seraient publiés
|
|
354
358
|
```
|
|
355
359
|
|
|
356
360
|
> En production, il n'y a pas de `:5174`. L'endpoint MCP auquel les clients se connectent est **`http://localhost:4321/mcp`** (Express, port par défaut).
|
|
357
361
|
|
|
358
362
|
### Contribuer
|
|
359
363
|
|
|
360
|
-
Ce dépôt embarque un hook `pre-commit` (dans `.githooks/`) qui impose le contrat
|
|
364
|
+
Ce dépôt embarque un hook `pre-commit` (dans `.githooks/`) qui impose le contrat de README bilingue : 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. La même vérification s'exécute en CI sur chaque PR (voir `.github/workflows/readme-sync.yml`), donc la règle est appliquée même si un contributeur oublie la configuration locale.
|
|
361
365
|
|
|
362
366
|
---
|
|
363
367
|
|
|
364
368
|
## Licence
|
|
365
369
|
|
|
366
|
-
[AGPL-3.0](./LICENSE) , © Youssef MEDAGHRI-ALAOUI.
|
|
370
|
+
[AGPL-3.0](./LICENSE) , © Youssef MEDAGHRI-ALAOUI.
|