@fkom13/mcp-sftp-orchestrator 6.0.0 → 11.8.0

package/README.md

@@ -1,102 +1,356 @@
-# 🚀 MCP SFTP/SSH Orchestrator
+# 🚀 MCP Orchestrator — Serveur d'orchestration SSH/SFTP
 
-Un serveur MCP (Model-Context-Protocol) puissant pour l'orchestration de tâches distantes. Il gère des connexions SSH et SFTP, une file d'attente de tâches persistante, et expose un ensemble riche d'outils pour la gestion de serveurs, le monitoring, et l'exécution de commandes via une interface `stdio` compatible avec les LLM.
+> **v11.8.0 Security Refresh** — Les 82 tools publient désormais les annotations MCP standard. `infra_overview` reste léger sans argument, mais `infra_overview { alias: "..." }` effectue une découverte live et corrèle Nginx/domaines, ports, Docker/Compose et services. Voir `CHANGELOG.md`.
 
-✨ **Fonctionnalités Principales**
 
-- **Gestion de Serveurs** : Ajoutez, listez et supprimez des configurations de serveurs SSH/SFTP.
-- **Exécution de Tâches SSH** : Simple, interactive, ou en séquence.
-- **Transferts de Fichiers SFTP** : Upload/Download de fichiers et dossiers, avec support des patterns `glob`.
-- **File d'Attente Intelligente** : Mode hybride (synchrone/asynchrone) et persistance des tâches.
-- **Pooling de Connexions** : Gère un pool de connexions SSH pour une exécution ultra-rapide.
-- **Outils de Monitoring** : Surveillez les ressources système, le statut des services (systemd, Docker, PM2) et Fail2Ban.
-- **Outils de Logs** : Récupérez les logs de PM2, Docker, ou suivez la fin d'un fichier (`tail`).
+**Version** : 11.8.0  
+**Tools** : 82  
+**License** : MIT  
+**Node** : >= 18.0.0  
+**Changelog** : [CHANGELOG.md](./CHANGELOG.md)
+
+Serveur MCP (Model Context Protocol, transport **stdio**) qui donne à un agent IA la capacité d’orchestrer un parc de serveurs : SSH, SFTP, édition de fichiers locale/remote (hash-safe), diffs cross-server, shell PTY, snapshots d’infra, notes de protocole, **projets**, **sessions de travail**, inventaire, trust SSH (pubkey), groupes d’alias et audit parc.
+
+---
+
+## ✨ Points forts (v11.6)
+
+| Domaine | Capacité |
+|---------|----------|
+| **Exécution** | `task_exec` multi-serveur / `group:oci` / dry-run destructif / force |
+| **Fichiers** | `file_read` / `file_edit` (chirurgical) / `file_write` + hash + dryRun + backup |
+| **Parc** | notes, `infra_audit`, `fleet_status`, `server_inventory` |
+| **Projets** | registre local↔remote + `project_diff` |
+| **Travail** | `work_start` → edits → `work_end` (note d’intervention auto) |
+| **Trust** | `ssh_authorize_key` (pubkey only, dry_run par défaut) |
+| **Sécu** | secrets masqués, RO global + **RO par alias**, blocklist, pool SSH robuste |
+
+---
 
 ## 📦 Installation
 
-Ce projet est conçu pour être utilisé comme un outil MCP dans un environnement compatible (comme la `gemini-cli`).
+```bash
+git clone https://github.com/fkom13/mcp-sftp-orchestrator.git
+cd sftp-mcp   # ou tools/sftp-mcp
+npm install
+cp .env.example .env
+# Éditer MCP_DATA_DIR et chemins de clés
+```
+
+Prérequis : **Node.js >= 18**
+
+---
 
-Enregistrez ce MCP auprès de votre client en utilisant la configuration suivante :
+## ⚙️ Configuration (`.env`)
+
+Toutes les variables sont optionnelles.
+
+| Variable | Défaut | Description |
+|----------|--------|-------------|
+| `MCP_DATA_DIR` | `~/.config/mcp-orchestrator` | Dossier data (JSON, snapshots, projets…) |
+| `MCP_SYNC_TIMEOUT_S` | `120` | Délai (s) avant passage d’une tâche en arrière-plan |
+| `MCP_DEFAULT_CMD_TIMEOUT_S` | `600` | Timeout SSH commande (s). `0` = infini |
+| `MCP_INTERACTIVE_CMD_TIMEOUT_S` | `300` | Timeout interactif (s). `0` = infini |
+| `MCP_MAX_WAIT_TIMEOUT_S` | `600` | Timeout max `task_wait` (s) |
+| `MAX_CONNECTIONS_PER_SERVER` | `5` | Pool SSH max / serveur |
+| `MIN_CONNECTIONS_PER_SERVER` | `1` | Pool SSH min / serveur |
+| `IDLE_TIMEOUT` | `300000` | Fermeture connexion inactive (ms) |
+| `KEEP_ALIVE_INTERVAL` | `30000` | Keepalive SSH (ms) |
+| `MAX_QUEUE_SIZE` | `1000` | Taille max queue jobs |
+| `SAVE_INTERVAL` | `5000` | Autosave queue (ms) |
+| `MCP_ALLOWED_ROOTS` | _(vide)_ | Racines autorisées pour paths locaux (CSV) |
+| `MCP_READONLY` | `false` | `1` = refuse écritures / exec mutantes (global) |
+| `MCP_COMPACT` | `false` | `1` = réponses tronquées (tokens agent) |
+| `MCP_DEBUG` | `false` | Logs détaillés stderr |
+
+### Fichiers sous `MCP_DATA_DIR`
+
+| Fichier | Contenu |
+|---------|---------|
+| `servers.json` | Alias SSH (`host`, `user`, `keyPath`/`password`, `port?`, `readonly?`) |
+| `apis.json` | Catalogue APIs (secrets masqués en lecture tools) |
+| `queue.json` / `queue.backup.json` | Jobs |
+| `history.json` | Historique tâches |
+| `server_notes.json` | Protocoles / notes par serveur |
+| `server_groups.json` | Groupes d’alias |
+| `projects.json` | Registre projets |
+| `work_sessions.json` | Sessions de travail |
+| `policies.json` | Blocklist commandes |
+| `tunnels.json` / `tunnel_allowlist.json` | Tunnels SSH |
+| `infra_snapshots/` | Snapshots content-addressable |
+
+---
+
+## 🔌 Connexion client MCP
+
+### Grok / config.toml
+
+```toml
+[mcp_servers.orchestrator]
+command = "node"
+args = ["/chemin/absolu/sftp-mcp/server.js"]
+# optionnel:
+# env = { MCP_DATA_DIR = "/chemin/absolu/sftp-mcp/data" }
+```
+
+### OpenCode / Claude Desktop (JSON)
 
 ```json
 {
   "mcpServers": {
-    "mcp-sftp-orchestrator": {
-      "command": "npx",
-      "args": [
-        "@fkom13/mcp-sftp-orchestrator"
-      ],
+    "orchestrator": {
+      "command": "node",
+      "args": ["/chemin/absolu/sftp-mcp/server.js"],
       "env": {
-        "MCP_DATA_DIR": "~/.config/mcp-orchestrator"
+        "MCP_DATA_DIR": "/chemin/absolu/sftp-mcp/data"
       }
     }
   }
 }
 ```
 
-Le client MCP lancera automatiquement le serveur via `npx` lors de son premier appel.
+Après modification du code : recharger le serveur MCP (`/mcps` → `r` ou restart session). Vérifier `system_diagnostics` → `version: "11.8.0"`.
 
-## 🛠️ Configuration
+---
 
-Le serveur est configurable via des variables d'environnement. Vous pouvez créer un fichier `.env` à la racine du projet si vous l'exécutez localement pour le développement.
+## 🧰 Référence des outils (82)
 
-- `MCP_DATA_DIR`: Le dossier où seront stockées les données (configurations des serveurs, historique, etc.). Par défaut : `~/.config/mcp-orchestrator`.
-- `MCP_SYNC_TIMEOUT_S`: Le délai en secondes avant qu'une tâche longue ne passe en arrière-plan. Par défaut : `30`.
+### Diagnostic & audit
+| Outil | Description |
+|-------|-------------|
+| `help` | Guide outils + .env + astuces |
+| `guide` | Manuel IA (workflows, cheatsheet, pitfalls, audit, security) |
+| `system_diagnostics` | Queue, pool, serveurs/APIs **masqués**, version, readOnly |
+| `infra_audit` | Synthèse parc + projets + notes + crashed |
+| `infra_overview` | Serveurs + notes (vue légère) |
+| `fleet_status` | Ping SSH parallèle (latence, load, disk) |
+| `server_inventory` | Inventaire léger (pm2/docker/disk/home, cache 10 min) |
 
-## 🧰 Référence des Outils (API)
+### Serveurs & groupes
+| Outil | Description |
+|-------|-------------|
+| `server_add` | CRUD alias (`keyPath` ou `password`, `port`, **`readonly`**) |
+| `server_list` | Liste (passwords masqués) |
+| `server_remove` | Supprime un alias |
+| `server_group_list/set/remove` | Groupes (`oci`, `contabo`…). Usage : `group:oci` ou nom de groupe |
 
-Voici la liste complète des outils exposés par ce serveur MCP.
+### Projets (v11.6)
+| Outil | Description |
+|-------|-------------|
+| `project_list` / `project_get` / `project_set` / `project_remove` | Registre |
+| `project_resolve` | → `{ local, remote, ignore, runtime }` |
+| `project_diff` | Diff local↔remote du projet |
 
-### Gestion des Serveurs
+Exemple `project_set` :
+
+```json
+{
+  "name": "p-image",
+  "local": { "path": "/home/.../dev-serveur/p-image" },
+  "servers": {
+    "prod": {
+      "alias": "fkomprodmini2_prod",
+      "path": "/home/ubuntu/p-image",
+      "runtime": { "pm2": "p-image", "port": 5002 },
+      "url": "https://pruna.esprit-artificiel.com"
+    }
+  },
+  "ignore": ["node_modules", ".git", "data"]
+}
+```
+
+### Sessions de travail (v11.6)
+| Outil | Description |
+|-------|-------------|
+| `work_start` | Ouvre un journal (`alias`, `project`, `tag`, snapshot optionnel) |
+| `work_log` | Event (`file_edit`, `task_exec`, …) |
+| `work_list` | Sessions actives (+ historique) |
+| `work_end` | Clôture + `server_note` `last_intervention` |
+
+### Trust SSH (v11.6)
+| Outil | Description |
+|-------|-------------|
+| `ssh_authorize_key` | Ajoute une **pubkey** dans `authorized_keys` distant. `dry_run` défaut. Sources : `string` \| `local_path` \| `alias` |
+
+```json
+{
+  "target_alias": "fkomprodmini1_prod",
+  "source": { "type": "alias", "alias": "vps_contabo" },
+  "comment": "fleet-from-contabo",
+  "dry_run": true
+}
+```
 
-- `server_add`: Enregistre ou met à jour les informations de connexion d'un serveur.
-- `server_list`: Affiche la liste de tous les alias de serveurs configurés.
-- `server_remove`: Supprime un alias de serveur de la configuration.
+### Policies
+| Outil | Description |
+|-------|-------------|
+| `policy_blocklist_list/add/remove` | Blocklist commandes (aussi appliquée à shell + sequences) |
 
-### Exécution de Tâches
+### Catalogue API
+| Outil | Description |
+|-------|-------------|
+| `api_add` / `api_list` / `api_remove` / `api_check` | Monitoring (clés masquées en list) |
 
-- `task_exec`: Exécute une commande SSH (hybride synchrone/asynchrone).
-- `task_transfer`: Transfère un fichier ou dossier via SFTP (hybride synchrone/asynchrone).
-- `task_exec_interactive`: Exécute une commande SSH interactive (gère les prompts `yes/no`, etc.).
-- `task_exec_sequence`: Exécute plusieurs commandes SSH en séquence sur le même serveur.
-- `task_transfer_multi`: Transfère plusieurs fichiers/dossiers avec support de patterns `glob`.
+### Exécution de tâches
+| Outil | Description |
+|-------|-------------|
+| `task_exec` | SSH ; alias \| tableau \| `all` \| `group:x` ; dry_run/force destructif |
+| `task_exec_interactive` | Prompts yes/no, menus |
+| `task_exec_sequence` | Séquence sur un serveur (policy par étape) |
+| `task_transfer` | SFTP upload/download/`server_to_server` |
+| `task_transfer_multi` | Multi + globs |
 
-### Monitoring & Diagnostics
+### Files / Diff / Shell / Snapshots
+| Famille | Outils |
+|---------|--------|
+| Files | `file_read`, `file_write`, `file_edit` |
+| Diff | `diff_files`, `diff_folders`, `compare_all_sources` |
+| Shell | `shell_create`, `shell_exec` (+ `skip_policy`), `shell_list`, `shell_close` |
+| Snapshots | `snapshot_create/list/diff/restore/delete` |
 
-- `get_system_resources`: Récupère les métriques système vitales (CPU, RAM, Disque).
-- `get_services_status`: Récupère le statut des services (systemd, Docker, PM2).
-- `get_fail2ban_status`: Récupère les informations du service Fail2Ban.
+**Édition safe** : `file_read` → hash → `file_edit` + `expectedHash` (+ `dryRun` / `backup`).
 
-### Récupération de Logs
+### Notes serveur
+| Outil | Description |
+|-------|-------------|
+| `server_note_set/get/list/remove` | Protocole (description, services, warnings, intervention) |
 
-- `get_pm2_logs`: Raccourci pour récupérer les logs PM2.
-- `get_docker_logs`: Raccourci pour récupérer les logs d'un container Docker.
-- `tail_file`: Affiche les dernières lignes d'un fichier distant.
+### Monitoring & logs
+| Outil | Description |
+|-------|-------------|
+| `get_system_resources` | CPU / RAM / disque |
+| `get_services_status` | systemd / Docker / PM2 |
+| `get_fail2ban_status` | Fail2Ban |
+| `check_api_health` | HTTP via SSH+curl |
+| `get_pm2_logs` / `get_docker_logs` / `tail_file` | Logs |
 
-### Gestion de la File d'Attente (Queue)
+### Queue
+| Outil | Description |
+|-------|-------------|
+| `task_queue` / `task_status` / `task_history` / `task_wait` / `task_logs` | Suivi |
+| `task_retry` / `task_retry_all` | Relance |
+| `task_purge` | Purge (dry_run défaut) |
+| `queue_stats` / `pool_stats` | Stats |
 
-- `task_queue`: Affiche le statut de toutes les tâches dans la file d'attente.
-- `task_status`: Récupère les détails d'une tâche par son ID.
-- `task_history`: Affiche l'historique des dernières tâches lancées.
-- `task_retry`: Relance une tâche qui a échoué ou crashé.
-- `queue_stats`: Affiche les statistiques de la queue de tâches.
+### Tmux & tunnels
+| Outil | Description |
+|-------|-------------|
+| `tmux_create/exec/read/list/kill` | Sessions tmux distantes |
+| `tunnel_create/list/close` | Tunnels SSH local/remote/socks |
+| `tunnel_allowlist_add/remove` | Ports autorisés pour tunnels |
+
+---
+
+## 📖 Workflows agent recommandés
+
+### Début de session
+```
+infra_audit  (ou infra_overview)
+fleet_status
+project_list / project_resolve
+```
+
+### Chantier sur un projet
+```
+work_start { project: "p-image", alias: "fkomprodmini2_prod", tag: "fix-x", message: "…" }
+file_read → file_edit (expectedHash, dryRun puis apply)
+work_log { type: "file_edit", path: "…" }
+work_end { summary: "…" }   → note serveur mise à jour
+project_diff { name: "p-image" }
+```
+
+### Commandes longues
+```
+task_exec { timeout: 0, … }  → si > syncTimeout → task_wait { id }
+```
+
+### Cibles multi-serveurs
+```
+task_exec { alias: "group:oci", cmd: "hostname" }
+task_exec { alias: "all", cmd: "uptime" }
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+Client MCP (stdio)
+    │
+server.js ─── 82 tools
+    │
+    ├── queue.js          File d’attente persistante + purge/retry
+    ├── ssh.js / sshPool  Exécution + pool (retry safe, port configurable)
+    ├── sftp.js           Transferts (server_to_server via sourceAdapter/pool)
+    ├── sourceAdapter.js  Local fs | remote SFTP pool
+    ├── fileOps.js        Read/write/edit + hash + dryRun + backup
+    ├── diffEngine.js / compareEngine.js / diffFormatter.js
+    ├── shellSessions.js  PTY persistants + policy
+    ├── snapshotManager.js
+    ├── projects.js / workSession.js / inventory.js / groups.js / fleet.js
+    ├── sshTrust.js       authorized_keys (pubkey only)
+    ├── servers.js / apis.js / notes.js / policies.js / tunnels.js
+    ├── history.js / guide.js / config.js / utils.js
+```
+
+### Cycle de vie d’un job
+
+```
+pending → running → completed | failed | partial
+                      ↓ (redémarrage MCP pendant running)
+                    crashed → task_retry → pending
+```
+
+---
+
+## 🔒 Sécurité
+
+| Mécanisme | Détail |
+|-----------|--------|
+| Secrets | Masqués en `api_list` / diagnostics (`***` + 4 derniers car.) |
+| Shell escape | `escapeShellArg` sur curl, logs, chemins |
+| Blocklist | `policies.json` ; shell + sequence inclus ; `skip_policy` pour forcer |
+| RO global | `MCP_READONLY=1` |
+| RO alias | `"readonly": true` dans `servers.json` |
+| Destructif | `task_exec` dry-run si pattern dangereux sans `force:true` |
+| Trust | Pubkey only ; dry_run par défaut |
+| Clés | Préférer `keyPath` SSH ; Vaultwarden pour secrets API |
+
+---
+
+## 🧪 Tests
+
+```bash
+npm test:unit    # p0 + p1 + p16 (43 tests)
+npm test         # unit + smoke MCP + features
+node diagnose.js # diagnostic local optionnel
+```
 
-### Gestion des APIs (Monitoring Externe)
+| Fichier | Couverture |
+|---------|------------|
+| `test_p0_unit.js` | utils, policies, redact, timeouts, version |
+| `test_p1_unit.js` | groups, purge, destructive, RO env |
+| `test_p16_unit.js` | projects, work session, compact, sshTrust |
+| `test_mcp.js` | smoke SDK |
+| `test_features.js` | queue / pool / globs / prompts |
 
-- `api_add`: Ajoute une API au catalogue de monitoring.
-- `api_list`: Affiche toutes les APIs configurées.
-- `api_remove`: Supprime une API du catalogue.
-- `api_check`: Lance un test de santé sur une API.
+---
 
-### Administration du Serveur MCP
+## 🛣️ Versions récentes
 
-- `task_logs`: Affiche les logs du système MCP lui-même.
-- `pool_stats`: Affiche les statistiques du pool de connexions SSH.
+| Version | Contenu | Snapshot gencodedoc |
+|---------|---------|---------------------|
+| **11.6.1** | Hardening multi-agent: RO transversal, server-to-server dossiers/force, allowed roots anti-symlink, quoting shell/tmux, queue + JSON stores atomiques | — |
+| **11.6.0** | Projets, work sessions, inventory, ssh_authorize_key, RO alias, compact | **#23** (final docs) |
+| 11.4.0 | fleet, infra_audit, groups, retry_all, purge, pool rewrite | #21 |
+| 11.3.0 | Secrets mask, policy shell/seq, port SSH, wait partial | #20 |
+| 10.4–10.0 | file ops, diff, shell, snapshots, notes, guide | #17–19 |
+| 9.x / 8.x | SFTP force, timeouts, interactif, sécu de base | — |
 
-## 🤝 Contribution
+Détail : **[CHANGELOG.md](./CHANGELOG.md)** · plans historiques : `ROADMAP.md`, `ROADMAP_EXTENDED.md`.
 
-Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une *Issue* pour signaler un bug ou proposer une fonctionnalité, ou une *Pull Request* pour soumettre des modifications.
+---
 
 ## 📄 Licence
 
-Ce projet est sous licence MIT.
+MIT — Copyright (c) 2025-2026 Franck (fkom13)

package/apis.js

@@ -1,88 +1,44 @@
-import fs from 'fs/promises';
 import path from 'path';
 import config from './config.js';
+import jsonStore from './atomicJsonStore.js';
 
 const APIS_FILE = path.join(config.dataDir, 'apis.json');
+const EMPTY = {};
 
-let apis = {};
-
-let isInitialized = false;
-let initPromise = null;
-
-// Charger les APIs au démarrage
 async function loadApis() {
-    try {
-        const data = await fs.readFile(APIS_FILE, 'utf-8');
-        apis = JSON.parse(data);
-    } catch (err) {
-        if (err.code === 'ENOENT') {
-            // Le fichier n'existe pas encore, c'est normal
-            apis = {};
-        } else {
-            console.error("Erreur lors du chargement de apis.json:", err);
-        }
-    }
-}
-
-async function ensureInitialized() {
-    if (isInitialized) return;
-    if (!initPromise) {
-        initPromise = loadApis().then(() => { isInitialized = true; });
-    }
-    return initPromise;
+    return jsonStore.readJson(APIS_FILE, EMPTY);
 }
 
-// Sauvegarder les APIs
-async function saveApis() {
-    await ensureInitialized();
-    try {
-        await fs.writeFile(APIS_FILE, JSON.stringify(apis, null, 2));
-    } catch (err) {
-        console.error("Erreur lors de la sauvegarde de apis.json:", err);
-    }
-}
-
-// Ajouter ou mettre à jour une API
 async function addApi(alias, apiConfig) {
-    await ensureInitialized();
-    apis[alias] = apiConfig;
-    await saveApis();
+    if (!alias || typeof alias !== 'string') throw new Error("L'alias doit être une chaîne non vide.");
+    if (!apiConfig.url) throw new Error("L'URL de l'API est obligatoire.");
+    try { new URL(apiConfig.url); } catch { throw new Error(`URL invalide: ${apiConfig.url}`); }
+
+    await jsonStore.updateJson(APIS_FILE, EMPTY, (apis) => {
+        apis[alias] = apiConfig;
+        return apis;
+    });
     return { success: true, message: `API '${alias}' ajoutée/mise à jour avec succès.` };
 }
 
-// Lister toutes les APIs
 async function listApis() {
-    await ensureInitialized();
-    return apis;
+    return loadApis();
 }
 
-// Obtenir une API par son alias
 async function getApi(alias) {
-    await ensureInitialized();
+    const apis = await loadApis();
     const apiConfig = apis[alias];
-    if (!apiConfig) {
-        throw new Error(`L'alias d'API '${alias}' est inconnu.`);
-    }
+    if (!apiConfig) throw new Error(`L'alias d'API '${alias}' est inconnu.`);
     return apiConfig;
 }
 
-// Supprimer une API
 async function removeApi(alias) {
-    await ensureInitialized();
-    if (!apis[alias]) {
-        throw new Error(`L'alias d'API '${alias}' est inconnu.`);
-    }
-    delete apis[alias];
-    await saveApis();
+    await jsonStore.updateJson(APIS_FILE, EMPTY, (apis) => {
+        if (!apis[alias]) throw new Error(`L'alias d'API '${alias}' est inconnu.`);
+        delete apis[alias];
+        return apis;
+    });
     return { success: true, message: `API '${alias}' supprimée avec succès.` };
 }
 
-// Initialiser le module
-ensureInitialized();
-
-export default {
-    addApi,
-    listApis,
-    getApi,
-    removeApi
-};
+export default { addApi, listApis, getApi, removeApi };

package/atomicJsonStore.js

@@ -0,0 +1,117 @@
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * AtomicJsonStore — primitive commune pour les petits registres JSON du MCP.
+ *
+ * Garanties intra-processus :
+ * - update(file) sérialise read -> mutate -> write par fichier ;
+ * - écriture via temp unique + fsync + rename atomique ;
+ * - backup .bak du dernier fichier valide avant remplacement ;
+ * - permissions du temp forcées à 0600 (les registres peuvent contenir des secrets) ;
+ * - un JSON corrompu n'est plus silencieusement remplacé par {} : tentative .bak,
+ *   puis erreur explicite si aucune copie valide n'existe.
+ *
+ * Ce verrou protège les appels concurrents du même process MCP. Pour le SaaS
+ * multi-instance, la persistance devra migrer vers DB/transaction ou un lock distribué.
+ */
+
+const tails = new Map();
+
+function clone(value) {
+    return value === undefined ? undefined : structuredClone(value);
+}
+
+async function withLock(file, fn) {
+    const key = path.resolve(file);
+    const prev = tails.get(key) || Promise.resolve();
+    let release;
+    const gate = new Promise(resolve => { release = resolve; });
+    const tail = prev.catch(() => {}).then(() => gate);
+    tails.set(key, tail);
+
+    await prev.catch(() => {});
+    try {
+        return await fn();
+    } finally {
+        release();
+        if (tails.get(key) === tail) tails.delete(key);
+    }
+}
+
+async function parseFile(file) {
+    const text = await fs.readFile(file, 'utf8');
+    return JSON.parse(text);
+}
+
+async function readJson(file, fallback, { createIfMissing = false } = {}) {
+    try {
+        return await parseFile(file);
+    } catch (err) {
+        if (err?.code === 'ENOENT') {
+            const value = clone(fallback);
+            if (createIfMissing) await writeJsonAtomic(file, value, { backup: false });
+            return value;
+        }
+
+        // Parse/I/O error : récupérer la dernière copie saine si possible.
+        try {
+            return await parseFile(`${file}.bak`);
+        } catch {
+            const wrapped = new Error(`JSON store illisible: ${file} (${err.message})`);
+            wrapped.code = 'JSON_STORE_CORRUPT';
+            wrapped.cause = err;
+            throw wrapped;
+        }
+    }
+}
+
+async function writeJsonAtomic(file, value, { backup = true } = {}) {
+    await fs.mkdir(path.dirname(file), { recursive: true });
+
+    if (backup) {
+        try { await fs.copyFile(file, `${file}.bak`); } catch (e) {
+            if (e?.code !== 'ENOENT') throw e;
+        }
+    }
+
+    const tmp = `${file}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    let handle = null;
+    try {
+        handle = await fs.open(tmp, 'w', 0o600);
+        await handle.writeFile(JSON.stringify(value, null, 2));
+        await handle.sync();
+        await handle.close();
+        handle = null;
+        await fs.rename(tmp, file);
+    } catch (err) {
+        if (handle) await handle.close().catch(() => {});
+        await fs.rm(tmp, { force: true }).catch(() => {});
+        throw err;
+    }
+}
+
+async function ensureJson(file, fallback) {
+    return withLock(file, async () => readJson(file, fallback, { createIfMissing: true }));
+}
+
+async function updateJson(file, fallback, mutator, options = {}) {
+    return withLock(file, async () => {
+        const current = await readJson(file, fallback, { createIfMissing: false });
+        const next = await mutator(current);
+        const value = next === undefined ? current : next;
+        await writeJsonAtomic(file, value, options);
+        return value;
+    });
+}
+
+export default {
+    withLock,
+    readJson,
+    writeJsonAtomic,
+    ensureJson,
+    updateJson
+};
+
+export { withLock, readJson, writeJsonAtomic, ensureJson, updateJson };