@fkom13/mcp-sftp-orchestrator 6.0.0 → 11.8.0

package/toolMetadata.js

@@ -0,0 +1,76 @@
+/**
+ * Metadata MCP agentique centralisée.
+ *
+ * L'objectif n'est pas de remplacer les garde-fous serveur par des hints :
+ * les annotations MCP aident le client/modèle à choisir et confirmer le bon
+ * outil, tandis que les policies/guards restent l'autorité réelle.
+ */
+
+const READ_ONLY = new Set([
+  'system_diagnostics','server_list','server_group_list','fleet_status','infra_audit',
+  'project_list','project_get','project_resolve','project_diff','work_list','server_inventory',
+  'policy_blocklist_list','api_list','api_check','get_system_resources','get_services_status',
+  'check_api_health','get_fail2ban_status','task_queue','task_status','task_history','pool_stats',
+  'queue_stats','task_logs','get_pm2_logs','get_docker_logs','tail_file','help','task_wait',
+  'file_read','diff_files','diff_folders','compare_all_sources','shell_list','snapshot_list',
+  'snapshot_diff','server_note_get','server_note_list','infra_overview','tmux_read','tmux_list',
+  'tunnel_list','guide'
+]);
+
+const DESTRUCTIVE = new Set([
+  'server_remove','server_group_remove','project_remove','work_end','policy_blocklist_remove',
+  'api_remove','task_exec','task_transfer','task_transfer_multi','task_exec_interactive',
+  'task_exec_sequence','task_retry','task_retry_all','task_purge','file_write','file_edit',
+  'shell_exec','shell_close','snapshot_restore','snapshot_delete','server_note_remove',
+  'tmux_exec','tmux_kill','tunnel_close','tunnel_allowlist_remove'
+]);
+
+const IDEMPOTENT_MUTATIONS = new Set([
+  'server_group_set','project_set','server_note_set','policy_blocklist_add',
+  'tunnel_allowlist_add','tunnel_allowlist_remove'
+]);
+
+const CLOSED_WORLD = new Set([
+  'help','guide','policy_blocklist_list','project_list','project_get','project_resolve',
+  'server_group_list','server_note_get','server_note_list','task_queue','task_status',
+  'task_history','queue_stats','task_logs','snapshot_list','snapshot_diff'
+]);
+
+const DESCRIPTION_OVERRIDES = {
+  system_diagnostics: 'Diagnostique le processus MCP lui-même (queue, pool SSH, registres, erreurs). Pour l’état réel d’une machine utilisez server_inventory; pour la topologie domaines→ports→services utilisez infra_overview avec alias.',
+  infra_audit: 'Contexte de contrôle-plane en un appel: version Orchestrator, registres, groupes, projets, notes, jobs crashés et pool. N’interroge pas profondément les machines. Pour une machine live et ses routes réseau utilisez infra_overview avec alias.',
+  infra_overview: 'Cartographie d’infrastructure. Sans alias: vue légère de tout le parc depuis les registres/notes. Avec alias (ou group:/all): découverte live mise en cache des listeners, Docker/Compose, PM2, systemd et Nginx, puis corrélation domaine → proxy → port → conteneur/service.',
+  fleet_status: 'Teste en parallèle la joignabilité SSH et quelques ressources de plusieurs serveurs. Choisir cet outil pour “qui est online ?”. Pour le détail d’une machine utilisez server_inventory; pour ses domaines/services exposés utilisez infra_overview.',
+  server_inventory: 'Inventaire live léger d’une machine avec cache TTL: ressources, Docker, PM2, HOME et Tailscale. Ne reconstruit pas les routes reverse-proxy; utilisez infra_overview pour domaine → port → service.',
+  task_exec: 'Commande distante one-shot. Pour une commande longue utilisez timeout:0 puis task_wait/task_status. Pour conserver cd/export entre appels utilisez shell_create/shell_exec; pour une session terminal survivant au MCP utilisez tmux_*.',
+  task_exec_sequence: 'Exécute plusieurs commandes ordonnées sur le même serveur avec résultat par étape. Préférer à plusieurs task_exec lorsque les étapes sont déterministes mais n’ont pas besoin d’un shell persistant.',
+  task_exec_interactive: 'Commande distante avec gestion de prompts interactifs connus. Utiliser seulement si la commande attend réellement yes/no/password/choix; sinon préférer task_exec.',
+  task_transfer: 'Transfert fichier ou dossier. server_to_server copie directement source_alias → alias. force:false protège une destination existante. Pour une réplication bit-à-bit avec métadonnées/symlinks, vérifier les warnings du résultat.',
+  task_transfer_multi: 'Lot de transferts avec patterns glob. À préférer pour plusieurs fichiers indépendants; task_transfer est plus clair pour un fichier/dossier ou un transfert server_to_server.',
+  file_edit: 'Édition chirurgicale locale/remote avec protection expectedHash, dryRun et backup. Préférer à file_write pour modifier un fichier existant sans écraser involontairement des changements concurrents.',
+  file_write: 'Crée ou remplace un fichier local/remote. Pour un fichier existant, préférer file_edit + expectedHash quand une édition chirurgicale est possible.',
+  shell_create: 'Ouvre un shell SSH persistant: cwd et variables survivent entre shell_exec. Pour une tâche détachée survivant à une déconnexion du MCP, préférer tmux_create/tmux_exec.',
+  tmux_create: 'Crée une session tmux distante durable. Adapté aux agents/serveurs de dev et tâches longues que l’on doit reprendre après déconnexion.',
+  snapshot_create: 'Snapshot CAS dédupliqué de fichiers/dossiers local ou remote pour rollback infra. Ce n’est pas de la mémoire sémantique projet; GenCodeDoc reste la brique Project Intelligence.',
+  help: 'Référence compacte des tools et variables Orchestrator. Pour des workflows agentiques guidés, utiliser guide.',
+  guide: 'Playbooks agentiques Orchestrator (audit, déploiement, recovery, transferts). Utiliser help pour le schéma/description d’un tool précis.'
+};
+
+function annotationsFor(name) {
+  const readOnlyHint = READ_ONLY.has(name);
+  return {
+    readOnlyHint,
+    destructiveHint: readOnlyHint ? false : DESTRUCTIVE.has(name),
+    idempotentHint: readOnlyHint || IDEMPOTENT_MUTATIONS.has(name),
+    openWorldHint: !CLOSED_WORLD.has(name)
+  };
+}
+
+function enhanceToolConfig(name, config = {}) {
+  const annotations = { ...annotationsFor(name), ...(config.annotations || {}) };
+  const description = DESCRIPTION_OVERRIDES[name] || config.description;
+  return { ...config, description, annotations };
+}
+
+export { annotationsFor, enhanceToolConfig, DESCRIPTION_OVERRIDES };
+export default { annotationsFor, enhanceToolConfig, DESCRIPTION_OVERRIDES };

package/tunnels.js

@@ -0,0 +1,243 @@
+import { spawn } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+import config from './config.js';
+import queue from './queue.js';
+import history from './history.js';
+import ssh from './ssh.js';
+import utils from './utils.js';
+import jsonStore from './atomicJsonStore.js';
+
+
+const TUNNELS_PATH = path.join(config.dataDir, 'tunnels.json');
+const ALLOWLIST_PATH = path.join(config.dataDir, 'tunnel_allowlist.json');
+
+const DEFAULT_ALLOWLIST = [80, 443, 3000, 8080, 8443, 9090, 3002, 3100, 3102, 4520, 5002, 4001, 51821, 5678, 8081, 8083, 8090];
+
+const LOCAL_TUNNELS = new Map();
+
+async function loadJson(p, def) {
+    return jsonStore.readJson(p, def);
+}
+async function saveJson(p, data) {
+    await jsonStore.writeJsonAtomic(p, data);
+}
+
+async function loadAllowlist() {
+    return loadJson(ALLOWLIST_PATH, DEFAULT_ALLOWLIST);
+}
+async function saveAllowlist(list) {
+    await saveJson(ALLOWLIST_PATH, list);
+}
+
+async function loadRegistry() {
+    return loadJson(TUNNELS_PATH, {});
+}
+async function saveRegistry(reg) {
+    await saveJson(TUNNELS_PATH, reg);
+}
+
+const tunnelLocks = new Map();
+async function withTunnelLock(name, fn) {
+    const prev = tunnelLocks.get(name) || Promise.resolve();
+    let release;
+    const gate = new Promise(r => { release = r; });
+    const tail = prev.catch(() => {}).then(() => gate);
+    tunnelLocks.set(name, tail);
+    await prev.catch(() => {});
+    try { return await fn(); }
+    finally { release(); if (tunnelLocks.get(name) === tail) tunnelLocks.delete(name); }
+}
+
+async function getSshTarget(alias, serverManager) {
+    const cfg = await serverManager.getServer(alias);
+    return { host: cfg.host, port: cfg.port || 22, user: cfg.user, keyPath: cfg.keyPath };
+}
+
+function spawnLocalSsh(args, name, info) {
+    const proc = spawn('ssh', args, { stdio: 'ignore', detached: false });
+    LOCAL_TUNNELS.set(name, { process: proc, info });
+    proc.on('exit', (code) => {
+        LOCAL_TUNNELS.delete(name);
+    });
+    proc.on('error', () => LOCAL_TUNNELS.delete(name));
+    return proc.pid;
+}
+
+function buildArgs(type, listenPort, target, via, remoteKeyPath) {
+    const args = ['-N', '-o', 'ServerAliveInterval=30', '-o', 'StrictHostKeyChecking=no'];
+    if (type !== 'remote') args.push('-o', 'ExitOnForwardFailure=yes');
+    switch (type) {
+        case 'local': args.push('-L', `${listenPort}:${target}`); break;
+        case 'remote': args.push('-R', `${listenPort}:${target}`); break;
+        case 'socks': args.push('-D', `${listenPort}`); break;
+    }
+    args.push('-p', String(via.port), `${via.user}@${via.host}`);
+    const keyToUse = remoteKeyPath || via.keyPath;
+    if (keyToUse) args.push('-i', keyToUse);
+    return args;
+}
+
+export default {
+    async create(params, serverManager) {
+        return withTunnelLock(params.name, async () => {
+        const { name, type, listen_port, target, via, source, key_path } = params;
+        if (!name) throw new Error("Le paramètre 'name' est requis.");
+        if (!['local', 'remote', 'socks'].includes(type)) throw new Error("type doit être 'local', 'remote' ou 'socks'");
+        if (!listen_port || listen_port < 1 || listen_port > 65535) throw new Error("listen_port invalide");
+        if (type !== 'socks' && !target) throw new Error("target requis pour les tunnels local/remote");
+        if (listen_port < 1024) throw new Error("Les ports < 1024 nécessitent root. Utilisez un port > 1023.");
+
+        const allowlist = await loadAllowlist();
+        if (!allowlist.includes(listen_port)) {
+            throw new Error(`Port ${listen_port} non autorisé. Autorisez-le: tunnel_allowlist_add ${listen_port}. Ports autorisés: ${allowlist.join(', ')}`);
+        }
+
+        const registry = await loadRegistry();
+        if (registry[name]) throw new Error(`Un tunnel nommé '${name}' existe déjà. Fermez-le d'abord.`);
+
+        const viaTarget = await getSshTarget(via, serverManager);
+
+        // Pour les tunnels sur serveur distant, le key_path doit exister SUR ce serveur
+        const remoteKeyPath = source ? (key_path || null) : null;
+        const args = buildArgs(type, listen_port, target || '', viaTarget, source ? (key_path || null) : null);
+
+        if (!source) {
+            const pid = spawnLocalSsh(args, name, { type, listen_port, target, via, source: null });
+            registry[name] = { type, listen_port, target, via, source: null, pid, created_at: new Date().toISOString() };
+            await saveRegistry(registry);
+            const desc = type === 'socks'
+                ? `Proxy SOCKS5 sur 127.0.0.1:${listen_port} (via ${via})`
+                : `http://127.0.0.1:${listen_port} → ${via}:${target}`;
+            return `Tunnel '${name}' créé localement (PID ${pid}). ${desc}\n⚠️  Ne survit pas au redémarrage du MCP.`;
+        }
+
+        const sessionName = `tunnel-${name}`;
+        const sshCmd = ['ssh', ...args].map(utils.escapeShellArg).join(' ');
+        const createCmd = `tmux new-session -d -s ${utils.escapeShellArg(sessionName)} -- sh -lc ${utils.escapeShellArg(sshCmd)}`;
+
+        const job = queue.addJob({ type: 'ssh', alias: source, cmd: createCmd, pty: true, timeout: 20, skip_policy: true, status: 'pending' });
+        history.logTask(job);
+        ssh.executeCommand(job.id);
+
+        const result = await new Promise(resolve => {
+            const start = Date.now();
+            const poll = () => {
+                const j = queue.getJob(job.id);
+                if (!j || j.status === 'completed') resolve(j);
+                else if (j.status === 'failed') resolve(j);
+                else if (Date.now() - start > 30000) resolve({ status: 'failed', error: 'timeout 30s' });
+                else setTimeout(poll, 200);
+            };
+            poll();
+        });
+
+        if (!result || result.status === 'failed') {
+            const detail = result ? (result.stderr || result.output || result.error || '') : 'job introuvable';
+            throw new Error(`Échec création tunnel sur ${source}: ${detail.substring(0, 500)}`);
+        }
+
+        registry[name] = { type, listen_port, target, via, source, tmux_session: sessionName, key_path, created_at: new Date().toISOString() };
+        await saveRegistry(registry);
+
+        const desc = type === 'socks'
+            ? `Proxy SOCKS5 sur ${source}:${listen_port} (via ${via})`
+            : `${source}:${listen_port} → ${via}:${target}`;
+        return `Tunnel '${name}' créé sur ${source} (session tmux: ${sessionName}). ${desc}\n✅ Persistant (survit au redémarrage du MCP).`;
+        });
+    },
+
+    async get(name) {
+        const registry = await loadRegistry();
+        return registry[name] || null;
+    },
+
+    async list() {
+        const registry = await loadRegistry();
+        const alive = [];
+
+        for (const [name, info] of Object.entries(registry)) {
+            let status;
+            if (!info.source) {
+                const local = LOCAL_TUNNELS.get(name);
+                status = local && local.process && !local.process.killed ? 'actif' : 'mort (MCP relancé, relancez le tunnel)';
+            } else {
+                const ckJob = queue.addJob({ type: 'ssh', alias: info.source, cmd: `tmux has-session -t ${utils.escapeShellArg(info.tmux_session)} 2>/dev/null && echo actif || echo mort`, timeout: 10, skip_policy: true, streaming: false, status: 'pending' });
+                ssh.executeCommand(ckJob.id);
+                await new Promise(r => { const p = () => { const j = queue.getJob(ckJob.id); if (!j || j.status === 'completed' || j.status === 'failed') r(j); else setTimeout(p, 200); }; p(); });
+                const j = queue.getJob(ckJob.id);
+                status = j && j.output && j.output.trim() === 'actif' ? 'actif' : 'mort';
+            }
+            alive.push({ name, ...info, status });
+        }
+
+        const allowlist = await loadAllowlist();
+        return { tunnels: alive, allowlist };
+    },
+
+    async close(name, serverManager) {
+        return withTunnelLock(name, async () => {
+        const registry = await loadRegistry();
+        const info = registry[name];
+        if (!info) throw new Error(`Tunnel '${name}' introuvable.`);
+
+        if (!info.source) {
+            const local = LOCAL_TUNNELS.get(name);
+            if (local && local.process && !local.process.killed) {
+                local.process.kill('SIGTERM');
+                setTimeout(() => { if (!local.process.killed) local.process.kill('SIGKILL'); }, 2000);
+            }
+            LOCAL_TUNNELS.delete(name);
+        } else {
+            const killJob = queue.addJob({ type: 'ssh', alias: info.source, cmd: `tmux kill-session -t ${utils.escapeShellArg(info.tmux_session)} 2>/dev/null; echo OK`, timeout: 10, skip_policy: true, streaming: false, status: 'pending' });
+            ssh.executeCommand(killJob.id);
+        }
+
+        delete registry[name];
+        await saveRegistry(registry);
+        return `Tunnel '${name}' fermé.`;
+        });
+    },
+
+    async allowlistList() {
+        return await loadAllowlist();
+    },
+
+    async allowlistAdd(port) {
+        return jsonStore.updateJson(ALLOWLIST_PATH, DEFAULT_ALLOWLIST, list => {
+            if (!list.includes(port)) list.push(port);
+            return list;
+        });
+    },
+
+    async allowlistRemove(port) {
+        return jsonStore.updateJson(ALLOWLIST_PATH, DEFAULT_ALLOWLIST, list => list.filter(p => p !== port));
+    },
+
+    async restore(servers) {
+        const registry = await loadRegistry();
+        let restored = 0;
+        for (const [name, info] of Object.entries(registry)) {
+            if (!info.source) {
+                try {
+                    const viaTarget = await getSshTarget(info.via, servers);
+                    const args = buildArgs(info.type, info.listen_port, info.target || '', viaTarget, false);
+                    const pid = spawnLocalSsh(args, name, info);
+                    registry[name].pid = pid;
+                    restored++;
+                } catch { /* silencieux, tunnel perdu */ }
+            }
+        }
+        await saveRegistry(registry);
+        return restored;
+    },
+
+    shutdown() {
+        for (const [name, entry] of LOCAL_TUNNELS) {
+            if (entry.process && !entry.process.killed) {
+                entry.process.kill('SIGTERM');
+            }
+        }
+        LOCAL_TUNNELS.clear();
+    }
+};

package/utils.js

@@ -0,0 +1,215 @@
+/**
+ * Utilitaires partagés (échappement shell, masquage secrets, timeouts, statuts).
+ * Extrait pour tests unitaires sans charger le serveur MCP.
+ */
+
+const SENSITIVE_KEYS = new Set([
+    'password',
+    'pass',
+    'api_key',
+    'apikey',
+    'apiKey',
+    'htpasswd_pass',
+    'htpasswdPass',
+    'secret',
+    'token',
+    'access_token',
+    'privateKey',
+    'private_key',
+    'authorization'
+]);
+
+function escapeShellArg(arg) {
+    if (typeof arg !== 'string') return String(arg);
+    return "'" + arg.replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * Masque un secret : garde les `visible` derniers caractères.
+ * null/undefined/non-string → inchangé.
+ */
+function maskSecret(value, visible = 4) {
+    if (value == null) return value;
+    const s = String(value);
+    if (s.length === 0) return s;
+    if (s.length <= visible) return '***';
+    return '***' + s.slice(-visible);
+}
+
+/**
+ * Clone profond léger et masque les champs sensibles (récursif).
+ * Ne mute pas l'objet d'origine.
+ */
+function redactSensitiveObject(obj, options = {}) {
+    const visible = options.visible ?? 4;
+    const extraKeys = options.extraKeys || [];
+    const keys = new Set([...SENSITIVE_KEYS, ...extraKeys.map(k => k.toLowerCase())]);
+
+    function walk(value, keyName) {
+        if (value == null) return value;
+        if (Array.isArray(value)) return value.map(v => walk(v, null));
+        if (typeof value === 'object') {
+            const out = {};
+            for (const [k, v] of Object.entries(value)) {
+                const lower = k.toLowerCase();
+                if (keys.has(lower) || keys.has(k)) {
+                    out[k] = typeof v === 'string' || typeof v === 'number'
+                        ? maskSecret(v, visible)
+                        : (v == null ? v : '***');
+                } else {
+                    out[k] = walk(v, k);
+                }
+            }
+            return out;
+        }
+        return value;
+    }
+
+    return walk(obj, null);
+}
+
+/**
+ * Convertit un timeout "secondes utilisateur" en ms pour waitForJobCompletion.
+ * - undefined/null → fallbackMs (déjà en ms, ex: config.syncTimeout)
+ * - 0 → 0 (attente infinie côté wait)
+ * - n > 0 → n * 1000
+ */
+function toWaitTimeoutMs(timeoutSeconds, fallbackMs) {
+    if (timeoutSeconds === 0) return 0;
+    if (timeoutSeconds == null || timeoutSeconds === undefined || timeoutSeconds === '') {
+        return fallbackMs;
+    }
+    const n = Number(timeoutSeconds);
+    if (!Number.isFinite(n) || n < 0) return fallbackMs;
+    return n * 1000;
+}
+
+/** Statuts pour lesquels un job n'évoluera plus (fin d'attente hybride). */
+function isTerminalJobStatus(status) {
+    return status === 'completed'
+        || status === 'failed'
+        || status === 'partial'
+        || status === 'crashed';
+}
+
+/**
+ * Résout le port SSH depuis une config serveur.
+ */
+function resolveSshPort(serverConfig) {
+    if (!serverConfig) return 22;
+    const p = serverConfig.port;
+    if (p == null || p === '') return 22;
+    const n = Number(p);
+    return Number.isFinite(n) && n > 0 && n <= 65535 ? n : 22;
+}
+
+/** Patterns heuristiques de commandes destructives (avertissement / dry-run). */
+const DESTRUCTIVE_PATTERNS = [
+    /\brm\s+(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r)\b/i,
+    /\brm\s+-rf\b/i,
+    /\bmkfs\b/i,
+    /\bdd\s+if=/i,
+    /\bdrop\s+(database|table)\b/i,
+    /\btruncate\s+table\b/i,
+    /\bshutdown\b/i,
+    /\breboot\b/i,
+    /\buserdel\b/i,
+    /\bpasswd\b/i,
+    /\bchmod\s+-R\s+000\b/i,
+    /\b>\s*\/dev\/sd/i,
+    /\biptables\s+-F\b/i,
+    /\bsystemctl\s+(stop|disable|mask)\b/i,
+    /\bdocker\s+(system\s+prune|rmi|rm\s+-f)\b/i,
+    /\bpm2\s+(delete|del|kill)\b/i
+];
+
+function isDestructiveCommand(cmd) {
+    if (!cmd || typeof cmd !== 'string') return false;
+    return DESTRUCTIVE_PATTERNS.some(re => re.test(cmd));
+}
+
+/**
+ * Refuse l'opération si MCP_READONLY=true.
+ * @throws Error
+ */
+function assertWritable(actionLabel = 'cette opération') {
+    // Lazy import-free: caller passes config.readOnly or we read env
+    const ro = process.env.MCP_READONLY === 'true' || process.env.MCP_READONLY === '1';
+    if (ro) {
+        throw new Error(
+            `Mode lecture seule (MCP_READONLY=1) : ${actionLabel} est refusé. ` +
+            `Relancez le MCP sans MCP_READONLY pour écrire.`
+        );
+    }
+}
+
+/**
+ * Compacte un objet pour l'agent (tronque gros champs).
+ * options = { maxString=500, maxArray=30, dropKeys=[] }
+ */
+function compactResult(obj, options = {}) {
+    const maxString = options.maxString ?? 500;
+    const maxArray = options.maxArray ?? 30;
+    const dropKeys = new Set(options.dropKeys || ['diff', 'raw_output', 'content']);
+
+    function walk(v, key) {
+        if (v == null) return v;
+        if (typeof v === 'string') {
+            if (dropKeys.has(key)) return v.length > 80 ? `[omitted ${v.length} chars]` : v;
+            return v.length > maxString ? v.slice(0, maxString) + `…[+${v.length - maxString}]` : v;
+        }
+        if (Array.isArray(v)) {
+            const sliced = v.slice(0, maxArray).map((item) => walk(item, null));
+            if (v.length > maxArray) sliced.push(`…+${v.length - maxArray} items`);
+            return sliced;
+        }
+        if (typeof v === 'object') {
+            const out = {};
+            for (const [k, val] of Object.entries(v)) {
+                if (dropKeys.has(k) && typeof val === 'string' && val.length > 100) {
+                    out[k] = `[omitted ${val.length} chars]`;
+                } else {
+                    out[k] = walk(val, k);
+                }
+            }
+            return out;
+        }
+        return v;
+    }
+
+    return walk(obj, null);
+}
+
+function wantsCompact(params = {}) {
+    if (params && params.compact === true) return true;
+    if (params && params.compact === false) return false;
+    return process.env.MCP_COMPACT === 'true' || process.env.MCP_COMPACT === '1';
+}
+
+export {
+    escapeShellArg,
+    maskSecret,
+    redactSensitiveObject,
+    toWaitTimeoutMs,
+    isTerminalJobStatus,
+    resolveSshPort,
+    isDestructiveCommand,
+    assertWritable,
+    compactResult,
+    wantsCompact,
+    DESTRUCTIVE_PATTERNS,
+    SENSITIVE_KEYS
+};
+
+export default {
+    escapeShellArg,
+    maskSecret,
+    redactSensitiveObject,
+    toWaitTimeoutMs,
+    isTerminalJobStatus,
+    resolveSshPort,
+    isDestructiveCommand,
+    assertWritable,
+    compactResult,
+    wantsCompact
+};

package/workSession.js

@@ -0,0 +1,139 @@
+/**
+ * workSession.js — Sessions de travail (journal d'intervention).
+ * Stockage atomique: <dataDir>/work_sessions.json
+ */
+import path from 'path';
+import crypto from 'crypto';
+import config from './config.js';
+import notes from './notes.js';
+import snapshotManager from './snapshotManager.js';
+import jsonStore from './atomicJsonStore.js';
+
+const SESSIONS_PATH = path.join(config.dataDir, 'work_sessions.json');
+const EMPTY = { active: {}, history: [] };
+
+const load = () => jsonStore.readJson(SESSIONS_PATH, EMPTY);
+
+function trimHistory(data) {
+    data.active ||= {};
+    data.history ||= [];
+    if (data.history.length > 100) data.history = data.history.slice(-100);
+    return data;
+}
+
+export default {
+    async start({ alias = null, project = null, tag = null, message = null, snapshot = false, paths = [] } = {}) {
+        const id = `ws_${Date.now()}_${crypto.randomBytes(3).toString('hex')}`;
+        const session = {
+            id,
+            alias,
+            project,
+            tag: tag || `work-${new Date().toISOString().slice(0, 10)}`,
+            message: message || null,
+            startedAt: new Date().toISOString(),
+            events: [],
+            snapshotId: null,
+            status: 'active'
+        };
+
+        // Effet externe avant publication de la session. S'il échoue, on garde
+        // l'information dans les events mais on ne laisse aucun état partiel.
+        if (snapshot && alias && paths.length) {
+            try {
+                const snap = await snapshotManager.createSnapshot(
+                    { type: 'remote', alias }, paths,
+                    { tag: session.tag, message: message || `work_start ${id}` }
+                );
+                session.snapshotId = snap.snapshotId;
+            } catch (e) {
+                session.events.push({ at: new Date().toISOString(), type: 'snapshot_error', detail: e.message });
+            }
+        }
+
+        await jsonStore.updateJson(SESSIONS_PATH, EMPTY, data => {
+            trimHistory(data);
+            data.active[id] = session;
+            return data;
+        });
+        return session;
+    },
+
+    async log(id, event) {
+        let count = 0;
+        await jsonStore.updateJson(SESSIONS_PATH, EMPTY, data => {
+            trimHistory(data);
+            const session = data.active[id];
+            if (!session) throw new Error(`Session '${id}' introuvable ou déjà fermée.`);
+            session.events.push({ at: new Date().toISOString(), ...event });
+            count = session.events.length;
+            return data;
+        });
+        return { id, events: count };
+    },
+
+    async get(id) {
+        const data = trimHistory(await load());
+        if (data.active[id]) return data.active[id];
+        const hist = data.history.find(s => s.id === id);
+        if (hist) return hist;
+        throw new Error(`Session '${id}' introuvable.`);
+    },
+
+    async list({ includeHistory = false } = {}) {
+        const data = trimHistory(await load());
+        const active = Object.values(data.active);
+        if (!includeHistory) return { active, historyCount: data.history.length };
+        return { active, history: data.history };
+    },
+
+    async end(id, { summary = null, note = true } = {}) {
+        let closed;
+        // Commit principal d'abord : une panne de notes ne doit jamais laisser
+        // la session active alors que l'appel end a été accepté.
+        await jsonStore.updateJson(SESSIONS_PATH, EMPTY, data => {
+            trimHistory(data);
+            const session = data.active[id];
+            if (!session) throw new Error(`Session '${id}' introuvable ou déjà fermée.`);
+
+            session.status = 'closed';
+            session.endedAt = new Date().toISOString();
+            session.summary = summary || session.message || `Session ${id} fermée`;
+            session.events.push({ at: session.endedAt, type: 'end', detail: session.summary });
+            if (note && session.alias) session.noteUpdated = null; // pending
+
+            delete data.active[id];
+            data.history.push(session);
+            trimHistory(data);
+            closed = structuredClone(session);
+            return data;
+        });
+
+        if (note && closed.alias) {
+            let noteUpdated = true;
+            let noteError = null;
+            try {
+                await notes.set(closed.alias, {
+                    intervention: `[${closed.tag}] ${closed.summary} (${closed.events.length} events)`
+                });
+            } catch (e) {
+                noteUpdated = false;
+                noteError = e.message;
+            }
+
+            // Compensation: enrichit l'historique sans rouvrir la session.
+            await jsonStore.updateJson(SESSIONS_PATH, EMPTY, data => {
+                trimHistory(data);
+                const hist = data.history.find(s => s.id === id);
+                if (hist) {
+                    hist.noteUpdated = noteUpdated;
+                    if (noteError) hist.noteError = noteError;
+                    else delete hist.noteError;
+                    closed = structuredClone(hist);
+                }
+                return data;
+            });
+        }
+
+        return closed;
+    }
+};