@imenam/mcp-ssh-gate 0.0.0-stage → 1.0.1

package/dist/src/core/executor.js

@@ -0,0 +1,328 @@
+import { GateError } from "./errors.js";
+import { toPublic } from "./server-store.js";
+import { ShellSession } from "./ssh-session.js";
+/** Sortie conservée par commande ; au-delà, le début est écarté. */
+export const MAX_STORED_OUTPUT = 512 * 1024;
+const PERSIST_INTERVAL_MS = 400;
+function now() {
+    return new Date().toISOString();
+}
+function cleanNote(note) {
+    const text = typeof note === "string" ? note.trim() : "";
+    return text ? text : null;
+}
+function skipRemaining(draft, from) {
+    for (let i = from; i < draft.commands.length; i++) {
+        if (draft.commands[i].status === "pending")
+            draft.commands[i].status = "skipped";
+    }
+}
+/**
+ * Exécution des demandes validées. Une session SSH par serveur, ouverte à la
+ * première exécution, et une seule demande en cours par serveur.
+ */
+export class Executor {
+    servers;
+    requests;
+    log;
+    sessions = new Map();
+    running = new Map();
+    constructor(servers, requests, log) {
+        this.servers = servers;
+        this.requests = requests;
+        this.log = log;
+    }
+    /** Marque en échec les demandes restées « en cours » après l'arrêt du worker. */
+    recoverAbandoned() {
+        for (const request of this.requests.listOpen()) {
+            if (request.status !== "running")
+                continue;
+            this.requests.update(request.id, (draft) => {
+                for (const command of draft.commands) {
+                    if (command.status === "running") {
+                        command.status = "interrupted";
+                        command.endedAt = now();
+                    }
+                }
+                skipRemaining(draft, 0);
+                draft.status = "failed";
+                draft.error = "L'interface s'est arrêtée pendant l'exécution : le résultat des commandes en cours est inconnu.";
+                draft.finishedAt = now();
+            });
+        }
+    }
+    views() {
+        const open = this.requests.listOpen();
+        return this.servers.list().map((server) => this.view(server, open));
+    }
+    view(server, open = this.requests.listOpen()) {
+        const session = this.sessions.get(server.id);
+        return {
+            ...toPublic(server),
+            session: session && !session.closed ? "connected" : "closed",
+            cwd: session && !session.closed ? session.cwd : null,
+            pendingCount: open.filter((r) => r.serverId === server.id && r.status === "pending").length,
+            busy: this.running.has(server.id),
+        };
+    }
+    addServer(input) {
+        return this.view(this.servers.create(input));
+    }
+    updateServer(id, input) {
+        const before = this.servers.get(id);
+        const after = this.servers.update(before.id, input);
+        if (before.host !== after.host || before.port !== after.port || before.username !== after.username)
+            this.disconnect(after.id);
+        return this.view(after);
+    }
+    deleteServer(id) {
+        const server = this.servers.get(id);
+        if (this.running.has(server.id))
+            throw new GateError("Une exécution est en cours sur ce serveur : attends sa fin ou interromps-la.");
+        this.disconnect(server.id);
+        this.servers.delete(server.id);
+        this.requests.deleteServer(server.id);
+    }
+    /** Ouvre une nouvelle session ; enregistre l'empreinte de l'hôte au premier test. */
+    async testConnection(id) {
+        const server = this.servers.get(id);
+        if (this.running.has(server.id))
+            throw new GateError("Une exécution est en cours sur ce serveur.");
+        this.disconnect(server.id);
+        const session = await this.openSession(server);
+        if (!server.hostKeyFingerprint)
+            this.servers.setFingerprint(server.id, session.fingerprint);
+        return { server: this.view(this.servers.get(server.id)), fingerprint: session.fingerprint, cwd: session.cwd };
+    }
+    disconnect(serverId) {
+        const session = this.sessions.get(serverId);
+        this.sessions.delete(serverId);
+        session?.close();
+    }
+    approve(requestId, note) {
+        const request = this.requests.get(requestId);
+        this.assertIdle(request.serverId);
+        const updated = this.requests.update(requestId, (draft) => {
+            if (draft.status !== "pending")
+                throw new GateError(`Cette demande n'est plus en attente (${draft.status}).`);
+            draft.status = "running";
+            draft.note = cleanNote(note);
+            draft.decidedAt = now();
+        });
+        this.start(updated);
+        return updated;
+    }
+    refuse(requestId, note) {
+        return this.requests.update(requestId, (draft) => {
+            if (draft.status !== "pending")
+                throw new GateError(`Cette demande n'est plus en attente (${draft.status}).`);
+            draft.status = "refused";
+            draft.note = cleanNote(note);
+            draft.decidedAt = now();
+            draft.finishedAt = draft.decidedAt;
+            skipRemaining(draft, 0);
+        });
+    }
+    editCommand(requestId, index, command) {
+        const text = typeof command === "string" ? command.trim() : "";
+        if (!text)
+            throw new GateError("La commande ne peut pas être vide.");
+        return this.requests.update(requestId, (draft) => {
+            if (draft.status !== "pending")
+                throw new GateError(`Cette demande n'est plus en attente (${draft.status}).`);
+            const entry = draft.commands[index];
+            if (!entry)
+                throw new GateError(`Commande ${index + 1} introuvable.`);
+            const proposed = entry.original ?? entry.command;
+            entry.command = text;
+            entry.original = text === proposed ? null : proposed;
+        });
+    }
+    removeCommand(requestId, index) {
+        return this.requests.update(requestId, (draft) => {
+            if (draft.status !== "pending")
+                throw new GateError(`Cette demande n'est plus en attente (${draft.status}).`);
+            if (!draft.commands[index])
+                throw new GateError(`Commande ${index + 1} introuvable.`);
+            if (draft.commands.length === 1)
+                throw new GateError("Une demande garde au moins une commande : refuse-la plutôt.");
+            draft.commands.splice(index, 1);
+        });
+    }
+    /** Commande saisie par l'utilisateur : exécutée aussitôt, sans validation. */
+    runManual(serverId, command) {
+        const server = this.servers.get(serverId);
+        this.assertIdle(server.id);
+        const created = this.requests.create({ serverId: server.id, source: "user", explanation: "", commands: [String(command ?? "")] });
+        const updated = this.requests.update(created.id, (draft) => {
+            draft.status = "running";
+            draft.decidedAt = now();
+        });
+        this.start(updated);
+        return updated;
+    }
+    async interrupt(requestId) {
+        const request = this.requests.get(requestId);
+        const entry = this.running.get(request.serverId);
+        if (!entry || entry.requestId !== request.id)
+            throw new GateError("Cette demande n'est pas en cours d'exécution.");
+        const session = this.sessions.get(request.serverId);
+        if (!session || session.closed)
+            throw new GateError("Le shell de ce serveur est fermé.");
+        entry.interruptRequested = true;
+        try {
+            await session.interrupt();
+        }
+        catch (err) {
+            entry.interruptRequested = false;
+            throw err;
+        }
+    }
+    assertIdle(serverId) {
+        if (this.running.has(serverId))
+            throw new GateError("Une exécution est déjà en cours sur ce serveur.");
+    }
+    async openSession(server) {
+        const session = await ShellSession.open({
+            host: server.host,
+            port: server.port,
+            username: server.username,
+            privateKey: this.servers.privateKey(server.id),
+            expectedFingerprint: server.hostKeyFingerprint,
+        }, (reason) => {
+            if (this.sessions.get(server.id) === session)
+                this.sessions.delete(server.id);
+            this.log(`Session ${server.id} closed: ${reason}`);
+        });
+        this.sessions.set(server.id, session);
+        return session;
+    }
+    async sessionFor(serverId) {
+        const existing = this.sessions.get(serverId);
+        if (existing && !existing.closed)
+            return existing;
+        const server = this.servers.get(serverId);
+        if (!server.hostKeyFingerprint) {
+            throw new GateError("La connexion à ce serveur n'a jamais été testée : lance « Tester la connexion » dans l'interface.");
+        }
+        return this.openSession(server);
+    }
+    start(request) {
+        const entry = { requestId: request.id, interruptRequested: false };
+        this.running.set(request.serverId, entry);
+        this.execute(request, entry)
+            .catch((err) => this.log(`Execution of ${request.id} failed: ${err?.stack ?? err}`))
+            .finally(() => {
+            if (this.running.get(request.serverId) === entry)
+                this.running.delete(request.serverId);
+        });
+    }
+    finish(requestId, status, error, from) {
+        this.requests.update(requestId, (draft) => {
+            skipRemaining(draft, from);
+            draft.status = status;
+            draft.error = error;
+            draft.finishedAt = now();
+        });
+    }
+    async execute(request, entry) {
+        let session;
+        try {
+            session = await this.sessionFor(request.serverId);
+        }
+        catch (err) {
+            this.finish(request.id, "failed", err.message, 0);
+            return;
+        }
+        const total = this.requests.get(request.id).commands.length;
+        for (let index = 0; index < total; index++) {
+            if (entry.interruptRequested) {
+                this.finish(request.id, "interrupted", null, index);
+                return;
+            }
+            const command = this.requests.get(request.id).commands[index].command;
+            const stopped = await this.runOne(request.id, index, command, session, entry);
+            if (stopped) {
+                this.finish(request.id, stopped.status, stopped.error, index + 1);
+                return;
+            }
+        }
+        this.finish(request.id, "completed", null, total);
+    }
+    /** Exécute une commande ; renvoie de quoi clore la demande si l'exécution doit s'arrêter là. */
+    async runOne(requestId, index, command, session, entry) {
+        let syntaxError;
+        try {
+            syntaxError = await session.checkSyntax(command);
+        }
+        catch (err) {
+            this.requests.update(requestId, (draft) => {
+                draft.commands[index].status = "failed";
+                draft.commands[index].endedAt = now();
+            });
+            return { status: "failed", error: err.message };
+        }
+        if (syntaxError) {
+            this.requests.update(requestId, (draft) => {
+                const target = draft.commands[index];
+                target.status = "failed";
+                target.output = `Erreur de syntaxe, commande non exécutée :\n${syntaxError}`;
+                target.startedAt = now();
+                target.endedAt = target.startedAt;
+            });
+            return { status: "failed", error: null };
+        }
+        this.requests.update(requestId, (draft) => {
+            draft.commands[index].status = "running";
+            draft.commands[index].startedAt = now();
+        });
+        let output = "";
+        let truncated = false;
+        let dirty = false;
+        const flush = () => {
+            if (!dirty)
+                return;
+            dirty = false;
+            this.requests.update(requestId, (draft) => {
+                draft.commands[index].output = output;
+                draft.commands[index].outputTruncated = truncated;
+            });
+        };
+        const timer = setInterval(flush, PERSIST_INTERVAL_MS);
+        try {
+            const result = await session.run(command, (text) => {
+                output += text;
+                if (output.length > MAX_STORED_OUTPUT) {
+                    output = output.slice(-MAX_STORED_OUTPUT);
+                    truncated = true;
+                }
+                dirty = true;
+            });
+            clearInterval(timer);
+            const status = entry.interruptRequested ? "interrupted" : result.exitCode === 0 ? "succeeded" : "failed";
+            this.requests.update(requestId, (draft) => {
+                const target = draft.commands[index];
+                target.output = output;
+                target.outputTruncated = truncated;
+                target.exitCode = result.exitCode;
+                target.status = status;
+                target.endedAt = now();
+                draft.cwd = result.cwd;
+            });
+            if (status === "succeeded")
+                return null;
+            return { status: status === "interrupted" ? "interrupted" : "failed", error: null };
+        }
+        catch (err) {
+            clearInterval(timer);
+            this.requests.update(requestId, (draft) => {
+                const target = draft.commands[index];
+                target.output = output;
+                target.outputTruncated = truncated;
+                target.status = entry.interruptRequested ? "interrupted" : "failed";
+                target.endedAt = now();
+            });
+            return { status: entry.interruptRequested ? "interrupted" : "failed", error: err.message };
+        }
+    }
+}

package/dist/src/core/files.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Sérialise un cycle lire-modifier-écrire entre processus : `wx` échoue si le
+ * verrou existe déjà. Un verrou plus vieux que LOCK_STALE_MS est cassé.
+ * Non réentrant.
+ */
+export declare function withFileLock<T>(lockPath: string, subject: string, fn: () => T): T;
+/** Écrit un JSON par renommage atomique : un lecteur voit l'ancien contenu ou le nouveau, jamais un fichier tronqué. */
+export declare function writeJsonAtomic(file: string, value: unknown, mode?: number): void;
+export declare function readJson<T>(file: string): T;

package/dist/src/core/files.js

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { GateError } from "./errors.js";
+const LOCK_STALE_MS = 10_000;
+const LOCK_RETRY_MS = 25;
+const LOCK_TIMEOUT_MS = 5_000;
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Sérialise un cycle lire-modifier-écrire entre processus : `wx` échoue si le
+ * verrou existe déjà. Un verrou plus vieux que LOCK_STALE_MS est cassé.
+ * Non réentrant.
+ */
+export function withFileLock(lockPath, subject, fn) {
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    let fd;
+    for (;;) {
+        try {
+            fd = fs.openSync(lockPath, "wx");
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            try {
+                if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                    fs.unlinkSync(lockPath);
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() > deadline) {
+                throw new GateError(`${subject} is being written by another process and did not free up in ${LOCK_TIMEOUT_MS} ms. Try again in a moment.`);
+            }
+            sleepSync(LOCK_RETRY_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.closeSync(fd);
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch {
+            // Verrou déjà cassé pour obsolescence par un autre processus.
+        }
+    }
+}
+/** Écrit un JSON par renommage atomique : un lecteur voit l'ancien contenu ou le nouveau, jamais un fichier tronqué. */
+export function writeJsonAtomic(file, value, mode) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", { encoding: "utf8", mode });
+    fs.renameSync(tmp, file);
+}
+export function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+}

package/dist/src/core/heartbeat.d.ts

@@ -0,0 +1,5 @@
+export declare const HEARTBEAT_INTERVAL_MS = 2000;
+/** Écrit le battement du worker : son URL publique et l'heure courante. */
+export declare function writeHeartbeat(dataDir: string, url: string): void;
+/** URL du worker vivant qui sert l'interface, ou null s'il n'y en a pas. */
+export declare function liveGuiUrl(dataDir: string): string | null;

package/dist/src/core/heartbeat.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readJson, writeJsonAtomic } from "./files.js";
+/** Au-delà de ce délai sans battement, le worker de l'interface est réputé arrêté. */
+const STALE_MS = 10_000;
+export const HEARTBEAT_INTERVAL_MS = 2_000;
+function fileOf(dataDir) {
+    return path.join(dataDir, "gui.json");
+}
+/** Écrit le battement du worker : son URL publique et l'heure courante. */
+export function writeHeartbeat(dataDir, url) {
+    writeJsonAtomic(fileOf(dataDir), { pid: process.pid, url, updatedAt: Date.now() });
+}
+/** URL du worker vivant qui sert l'interface, ou null s'il n'y en a pas. */
+export function liveGuiUrl(dataDir) {
+    const file = fileOf(dataDir);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const beat = readJson(file);
+        return Date.now() - beat.updatedAt < STALE_MS ? beat.url : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/core/request-store.d.ts

@@ -0,0 +1,26 @@
+import { type GateRequest, type RequestSource } from "../../shared/model.js";
+export interface NewRequest {
+    serverId: string;
+    source: RequestSource;
+    explanation: string;
+    commands: string[];
+}
+/**
+ * Demandes d'exécution : un fichier JSON par demande dans
+ * `<DATA_DIR>/requests/<serveur>/`. Les processus MCP créent les demandes,
+ * le worker de l'interface les fait avancer.
+ */
+export declare class RequestStore {
+    private readonly root;
+    constructor(dataDir: string);
+    create(input: NewRequest): GateRequest;
+    get(id: string): GateRequest;
+    /** Demandes d'un serveur, les plus anciennes d'abord ; `limit` garde les plus récentes. */
+    listForServer(serverId: string, limit?: number): GateRequest[];
+    /** Demandes non terminées de tous les serveurs. */
+    listOpen(): GateRequest[];
+    update(id: string, fn: (draft: GateRequest) => void): GateRequest;
+    deleteServer(serverId: string): void;
+    private fileOf;
+    private locate;
+}

package/dist/src/core/request-store.js

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { MAX_COMMANDS_PER_REQUEST } from "../../shared/model.js";
+import { GateError } from "./errors.js";
+import { readJson, withFileLock, writeJsonAtomic } from "./files.js";
+const ID_PATTERN = /^[0-9a-z]{9}-[0-9a-f]{6}$/;
+/** Identifiant triable par date de création : horodatage base 36 sur 9 caractères, puis 6 caractères aléatoires. */
+function newId() {
+    return `${Date.now().toString(36).padStart(9, "0")}-${randomBytes(3).toString("hex")}`;
+}
+function normalizeCommands(commands) {
+    if (!Array.isArray(commands) || commands.length === 0)
+        throw new GateError("At least one command is required.");
+    if (commands.length > MAX_COMMANDS_PER_REQUEST) {
+        throw new GateError(`A request holds at most ${MAX_COMMANDS_PER_REQUEST} commands; split the work into several requests.`);
+    }
+    return commands.map((raw, index) => {
+        const command = String(raw ?? "").trim();
+        if (!command)
+            throw new GateError(`Command ${index + 1} is empty.`);
+        return command;
+    });
+}
+/**
+ * Demandes d'exécution : un fichier JSON par demande dans
+ * `<DATA_DIR>/requests/<serveur>/`. Les processus MCP créent les demandes,
+ * le worker de l'interface les fait avancer.
+ */
+export class RequestStore {
+    root;
+    constructor(dataDir) {
+        this.root = path.join(dataDir, "requests");
+        fs.mkdirSync(this.root, { recursive: true });
+    }
+    create(input) {
+        const commands = normalizeCommands(input.commands);
+        const request = {
+            id: newId(),
+            serverId: input.serverId,
+            source: input.source,
+            explanation: String(input.explanation ?? "").trim(),
+            createdAt: new Date().toISOString(),
+            status: "pending",
+            note: null,
+            decidedAt: null,
+            finishedAt: null,
+            error: null,
+            cwd: null,
+            commands: commands.map((command) => ({
+                command,
+                original: null,
+                status: "pending",
+                exitCode: null,
+                output: "",
+                outputTruncated: false,
+                startedAt: null,
+                endedAt: null,
+            })),
+        };
+        writeJsonAtomic(this.fileOf(request.serverId, request.id), request);
+        return request;
+    }
+    get(id) {
+        return readJson(this.locate(id));
+    }
+    /** Demandes d'un serveur, les plus anciennes d'abord ; `limit` garde les plus récentes. */
+    listForServer(serverId, limit) {
+        const dir = path.join(this.root, serverId);
+        if (!fs.existsSync(dir))
+            return [];
+        let names = fs
+            .readdirSync(dir)
+            .filter((name) => name.endsWith(".json"))
+            .sort();
+        if (limit !== undefined)
+            names = names.slice(-limit);
+        return names.map((name) => readJson(path.join(dir, name)));
+    }
+    /** Demandes non terminées de tous les serveurs. */
+    listOpen() {
+        if (!fs.existsSync(this.root))
+            return [];
+        return fs
+            .readdirSync(this.root)
+            .flatMap((serverId) => this.listForServer(serverId))
+            .filter((request) => request.status === "pending" || request.status === "running");
+    }
+    update(id, fn) {
+        const file = this.locate(id);
+        return withFileLock(`${file}.lock`, `Request ${id}`, () => {
+            const draft = readJson(file);
+            fn(draft);
+            writeJsonAtomic(file, draft);
+            return draft;
+        });
+    }
+    deleteServer(serverId) {
+        fs.rmSync(path.join(this.root, serverId), { recursive: true, force: true });
+    }
+    fileOf(serverId, id) {
+        return path.join(this.root, serverId, `${id}.json`);
+    }
+    locate(id) {
+        const value = String(id ?? "").trim();
+        if (!ID_PATTERN.test(value))
+            throw new GateError(`Invalid request id "${id}".`);
+        for (const serverId of fs.readdirSync(this.root)) {
+            const file = this.fileOf(serverId, value);
+            if (fs.existsSync(file))
+                return file;
+        }
+        throw new GateError(`Unknown request "${id}".`);
+    }
+}

package/dist/src/core/server-store.d.ts

@@ -0,0 +1,42 @@
+import { type NotesAuthor, type ServerPublic } from "../../shared/model.js";
+export interface StoredServer extends ServerPublic {
+    /** Clé privée OpenSSH chiffrée avec VAULT_KEY. */
+    privateKeyEncrypted: string;
+}
+export interface ServerInput {
+    name: string;
+    host: string;
+    port: number;
+    username: string;
+}
+/** Contrôle et normalise les champs saisis pour un serveur. */
+export declare function validateServerInput(input: ServerInput): ServerInput;
+export declare function toPublic(server: StoredServer): ServerPublic;
+/**
+ * Serveurs SSH : `<DATA_DIR>/servers.json`. La paire de clés est générée à la
+ * création ; seule la clé publique est lisible, la clé privée est chiffrée.
+ */
+export declare class ServerStore {
+    private readonly vaultKey;
+    private readonly file;
+    private readonly lockFile;
+    constructor(dataDir: string, vaultKey: Buffer);
+    list(): StoredServer[];
+    /** Retrouve un serveur par identifiant ou par nom (sans tenir compte de la casse). */
+    get(idOrName: string): StoredServer;
+    create(input: ServerInput): StoredServer;
+    /** Modifie les champs saisis. Un changement d'hôte ou de port oublie l'empreinte : c'est une autre machine. */
+    update(id: string, input: ServerInput): StoredServer;
+    setFingerprint(id: string, fingerprint: string): StoredServer;
+    /**
+     * Remplace les notes. Avec `expectedUpdatedAt`, l'écriture est refusée si les
+     * notes ont changé depuis cette date : une saisie ne doit pas écraser une
+     * mise à jour faite entre-temps par l'agent ou par un autre onglet.
+     */
+    setNotes(id: string, text: string, by: NotesAuthor, expectedUpdatedAt?: string | null): StoredServer;
+    delete(id: string): void;
+    privateKey(id: string): string;
+    /** Vérifie que VAULT_KEY déchiffre toutes les clés enregistrées. */
+    verifyVault(): void;
+    private mutate;
+}