@imenam/mcp-organizer 0.0.0-stage → 1.0.2

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

@@ -0,0 +1,45 @@
+/**
+ * Dictée vocale : transcription d'un enregistrement par l'API Groq
+ * (compatible OpenAI), `POST <base>/audio/transcriptions` en multipart
+ * (`file`, `model`, `language=fr`, `response_format=json`). Sans clé ou sans
+ * modèle configuré, la transcription est désactivée et `disabledReason` dit
+ * quoi configurer.
+ */
+/** URL de base de l'API Groq. */
+export declare const GROQ_BASE_URL = "https://api.groq.com/openai/v1";
+/**
+ * Variable réservée aux tests : remplace l'URL de base de l'API Groq par celle
+ * d'un serveur simulé. Elle ne fait pas partie de la configuration d'une installation.
+ */
+export declare const TEST_BASE_URL_VARIABLE = "ORGANIZER_TEST_GROQ_BASE_URL";
+/** Délai maximal d'une transcription par Groq. */
+export declare const TRANSCRIPTION_TIMEOUT_MS = 90000;
+/** Échec d'une transcription, avec le code HTTP à renvoyer au navigateur (celui de Groq quand Groq refuse). */
+export declare class TranscriptionError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/** Enregistrement à transcrire. */
+export interface Recording {
+    content: Buffer;
+    filename: string;
+    mime: string;
+}
+export interface Transcriber {
+    readonly enabled: boolean;
+    readonly disabledReason: string | null;
+    /** Texte transcrit ; lève `TranscriptionError`. */
+    transcribe(recording: Recording): Promise<string>;
+}
+export interface TranscriptionConfig {
+    /** Clé de l'API Groq (`GROQ_API_KEY`). */
+    apiKey?: string;
+    /** Modèle de transcription (`ORGANIZER_TRANSCRIBE_MODEL`). */
+    model?: string;
+    /** URL de base de l'API ; celle de Groq par défaut. */
+    baseUrl?: string;
+    timeoutMs?: number;
+}
+export declare function createTranscriber(config: TranscriptionConfig): Transcriber;
+/** Transcription configurée par `GROQ_API_KEY` et `ORGANIZER_TRANSCRIBE_MODEL`. */
+export declare function transcriberFromEnv(env?: NodeJS.ProcessEnv): Transcriber;

package/dist/src/core/transcription.js

@@ -0,0 +1,92 @@
+/**
+ * Dictée vocale : transcription d'un enregistrement par l'API Groq
+ * (compatible OpenAI), `POST <base>/audio/transcriptions` en multipart
+ * (`file`, `model`, `language=fr`, `response_format=json`). Sans clé ou sans
+ * modèle configuré, la transcription est désactivée et `disabledReason` dit
+ * quoi configurer.
+ */
+/** URL de base de l'API Groq. */
+export const GROQ_BASE_URL = "https://api.groq.com/openai/v1";
+/**
+ * Variable réservée aux tests : remplace l'URL de base de l'API Groq par celle
+ * d'un serveur simulé. Elle ne fait pas partie de la configuration d'une installation.
+ */
+export const TEST_BASE_URL_VARIABLE = "ORGANIZER_TEST_GROQ_BASE_URL";
+/** Délai maximal d'une transcription par Groq. */
+export const TRANSCRIPTION_TIMEOUT_MS = 90_000;
+/** Échec d'une transcription, avec le code HTTP à renvoyer au navigateur (celui de Groq quand Groq refuse). */
+export class TranscriptionError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "TranscriptionError";
+    }
+}
+function disabledTranscriber(reason) {
+    return {
+        enabled: false,
+        disabledReason: reason,
+        transcribe: async () => {
+            throw new TranscriptionError(503, reason);
+        },
+    };
+}
+/** Message d'erreur de Groq : `error.message` de son corps JSON, sinon le corps brut. */
+function groqMessage(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed.error?.message === "string")
+            return parsed.error.message;
+    }
+    catch {
+        // Corps non JSON : renvoyé tel quel.
+    }
+    return body.trim() || "réponse vide";
+}
+export function createTranscriber(config) {
+    const apiKey = config.apiKey?.trim();
+    const model = config.model?.trim();
+    if (!apiKey)
+        return disabledTranscriber("Dictée désactivée : GROQ_API_KEY n'est pas défini dans la configuration du site.");
+    if (!model)
+        return disabledTranscriber("Dictée désactivée : ORGANIZER_TRANSCRIBE_MODEL (modèle de transcription Groq) n'est pas défini dans la configuration du site.");
+    const endpoint = `${(config.baseUrl?.trim() || GROQ_BASE_URL).replace(/\/+$/, "")}/audio/transcriptions`;
+    const timeoutMs = config.timeoutMs ?? TRANSCRIPTION_TIMEOUT_MS;
+    return {
+        enabled: true,
+        disabledReason: null,
+        transcribe: async (recording) => {
+            const form = new FormData();
+            form.append("file", new Blob([new Uint8Array(recording.content)], { type: recording.mime }), recording.filename);
+            form.append("model", model);
+            form.append("language", "fr");
+            form.append("response_format", "json");
+            let response;
+            try {
+                response = await fetch(endpoint, { method: "POST", headers: { Authorization: `Bearer ${apiKey}` }, body: form, signal: AbortSignal.timeout(timeoutMs) });
+            }
+            catch (err) {
+                const reason = err?.name === "TimeoutError" ? `pas de réponse en ${Math.round(timeoutMs / 1000)} s` : (err?.cause?.message ?? err?.message ?? String(err));
+                throw new TranscriptionError(502, `L'API de transcription Groq est injoignable : ${reason}.`);
+            }
+            const body = await response.text();
+            if (!response.ok)
+                throw new TranscriptionError(response.status, `Groq a refusé la transcription (HTTP ${response.status}) : ${groqMessage(body)}`);
+            let text;
+            try {
+                text = JSON.parse(body).text;
+            }
+            catch {
+                text = undefined;
+            }
+            if (typeof text !== "string")
+                throw new TranscriptionError(502, `Réponse inattendue de l'API Groq : ${body.slice(0, 200)}`);
+            return text.trim();
+        },
+    };
+}
+/** Transcription configurée par `GROQ_API_KEY` et `ORGANIZER_TRANSCRIBE_MODEL`. */
+export function transcriberFromEnv(env = process.env) {
+    return createTranscriber({ apiKey: env.GROQ_API_KEY, model: env.ORGANIZER_TRANSCRIBE_MODEL, baseUrl: env[TEST_BASE_URL_VARIABLE] });
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Présence des veilleurs de notifications, par jeton d'agent.
+ *
+ * Un veilleur enchaîne des attentes longues sur `GET /api/agent/requests/wait`.
+ * Le registre rend sa présence observable : `enable_notifications` répond
+ * « déjà armé », la page Agent de la GUI affiche « à l'écoute ».
+ *
+ * État de connexion, donc volatile : il vit en mémoire du processus du site et
+ * disparaît avec lui.
+ */
+/**
+ * Délai de grâce entre deux attentes d'un même veilleur : le jeton reste
+ * « à l'écoute » pendant le court intervalle où aucune attente n'est ouverte.
+ */
+export declare const WATCHER_GRACE_MS: number;
+export interface WatcherStatus {
+    armed: boolean;
+    /** Début de la série d'attentes en cours, null sans veilleur. */
+    since: string | null;
+    /** Dernière activité connue d'un veilleur de ce jeton, null si aucune. */
+    lastSeen: string | null;
+}
+export declare class WatcherRegistry {
+    private readonly now;
+    private readonly presence;
+    constructor(now?: () => number);
+    /** Déclare une attente de veilleur du jeton `tokenId`. La fonction rendue la clôt ; elle doit toujours être appelée. */
+    begin(tokenId: string): () => void;
+    status(tokenId: string): WatcherStatus;
+}

package/dist/src/core/watchers.js

@@ -0,0 +1,50 @@
+/**
+ * Présence des veilleurs de notifications, par jeton d'agent.
+ *
+ * Un veilleur enchaîne des attentes longues sur `GET /api/agent/requests/wait`.
+ * Le registre rend sa présence observable : `enable_notifications` répond
+ * « déjà armé », la page Agent de la GUI affiche « à l'écoute ».
+ *
+ * État de connexion, donc volatile : il vit en mémoire du processus du site et
+ * disparaît avec lui.
+ */
+/**
+ * Délai de grâce entre deux attentes d'un même veilleur : le jeton reste
+ * « à l'écoute » pendant le court intervalle où aucune attente n'est ouverte.
+ */
+export const WATCHER_GRACE_MS = 2 * 60 * 1000;
+export class WatcherRegistry {
+    now;
+    presence = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Déclare une attente de veilleur du jeton `tokenId`. La fonction rendue la clôt ; elle doit toujours être appelée. */
+    begin(tokenId) {
+        const now = this.now();
+        const current = this.presence.get(tokenId);
+        const continuing = current !== undefined && (current.inflight > 0 || now - current.lastSeen <= WATCHER_GRACE_MS);
+        this.presence.set(tokenId, continuing ? { ...current, inflight: current.inflight + 1, lastSeen: now } : { inflight: 1, since: now, lastSeen: now });
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            const active = this.presence.get(tokenId);
+            if (!active)
+                return;
+            this.presence.set(tokenId, { ...active, inflight: Math.max(0, active.inflight - 1), lastSeen: this.now() });
+        };
+    }
+    status(tokenId) {
+        const entry = this.presence.get(tokenId);
+        if (!entry)
+            return { armed: false, since: null, lastSeen: null };
+        const armed = entry.inflight > 0 || this.now() - entry.lastSeen <= WATCHER_GRACE_MS;
+        if (!armed) {
+            this.presence.delete(tokenId);
+            return { armed: false, since: null, lastSeen: new Date(entry.lastSeen).toISOString() };
+        }
+        return { armed: true, since: new Date(entry.since).toISOString(), lastSeen: new Date(entry.lastSeen).toISOString() };
+    }
+}

package/dist/src/deploy/env-render.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Écriture du fichier `.env` du site par `mcp-organizer --setup`.
+ *
+ * Un fichier existant est fusionné ligne à ligne : les commentaires et les
+ * variables que le setup ne gère pas restent tels quels, chaque variable gérée
+ * est réécrite à sa place, une variable gérée sans valeur est retirée, et les
+ * variables gérées absentes du fichier sont ajoutées à la fin.
+ */
+/** Variables écrites par le setup, dans l'ordre d'un fichier neuf. */
+export declare const MANAGED_ENV_KEYS: readonly ["ORGANIZER_PUBLIC_URL", "ORGANIZER_BASE_PATH", "PORT", "HOST", "ORGANIZER_TRUST_PROXY", "MCP_ORGANIZER_DATA_DIR", "GROQ_API_KEY", "ORGANIZER_TRANSCRIBE_MODEL", "SMTP_URL", "MAIL_FROM"];
+export type ManagedEnvKey = (typeof MANAGED_ENV_KEYS)[number];
+/**
+ * Variables d'amorçage du premier compte : le setup crée le compte en base et
+ * les retire du fichier, où le mot de passe resterait en clair.
+ */
+export declare const REMOVED_ENV_KEYS: readonly ["ORGANIZER_ADMIN_EMAIL", "ORGANIZER_ADMIN_NAME", "ORGANIZER_ADMIN_PASSWORD"];
+/** Valeur de chaque variable gérée ; `null` retire la variable du fichier. */
+export type ManagedEnvValues = Record<ManagedEnvKey, string | null>;
+/**
+ * Valeur écrite telle que `dotenv` la relit : brute si elle ne contient que
+ * des caractères sûrs, sinon entre guillemets simples (aucune interprétation),
+ * ou doubles si elle contient une apostrophe.
+ */
+export declare function formatEnvValue(key: string, value: string): string;
+/** Contenu du fichier `.env` : `existing` fusionné avec `values`, ou un fichier neuf. */
+export declare function renderEnvFile(existing: string | undefined, values: ManagedEnvValues): string;

package/dist/src/deploy/env-render.js

@@ -0,0 +1,98 @@
+/**
+ * Écriture du fichier `.env` du site par `mcp-organizer --setup`.
+ *
+ * Un fichier existant est fusionné ligne à ligne : les commentaires et les
+ * variables que le setup ne gère pas restent tels quels, chaque variable gérée
+ * est réécrite à sa place, une variable gérée sans valeur est retirée, et les
+ * variables gérées absentes du fichier sont ajoutées à la fin.
+ */
+/** Variables écrites par le setup, dans l'ordre d'un fichier neuf. */
+export const MANAGED_ENV_KEYS = [
+    "ORGANIZER_PUBLIC_URL",
+    "ORGANIZER_BASE_PATH",
+    "PORT",
+    "HOST",
+    "ORGANIZER_TRUST_PROXY",
+    "MCP_ORGANIZER_DATA_DIR",
+    "GROQ_API_KEY",
+    "ORGANIZER_TRANSCRIBE_MODEL",
+    "SMTP_URL",
+    "MAIL_FROM",
+];
+/**
+ * Variables d'amorçage du premier compte : le setup crée le compte en base et
+ * les retire du fichier, où le mot de passe resterait en clair.
+ */
+export const REMOVED_ENV_KEYS = ["ORGANIZER_ADMIN_EMAIL", "ORGANIZER_ADMIN_NAME", "ORGANIZER_ADMIN_PASSWORD"];
+const KEY_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+const PLAIN_VALUE = /^[A-Za-z0-9_\-.:/@+,=%~]*$/;
+/**
+ * Valeur écrite telle que `dotenv` la relit : brute si elle ne contient que
+ * des caractères sûrs, sinon entre guillemets simples (aucune interprétation),
+ * ou doubles si elle contient une apostrophe.
+ */
+export function formatEnvValue(key, value) {
+    if (/[\r\n]/.test(value))
+        throw new Error(`${key} : une valeur sur plusieurs lignes n'est pas admise.`);
+    if (PLAIN_VALUE.test(value))
+        return value;
+    if (!value.includes("'"))
+        return `'${value}'`;
+    if (!value.includes('"') && !value.includes("\\"))
+        return `"${value}"`;
+    throw new Error(`${key} : la valeur contient à la fois une apostrophe et un guillemet ou une barre oblique inverse ; elle ne peut pas s'écrire dans un fichier .env.`);
+}
+const HEADER = [
+    "# Configuration du site mcp-organizer, écrite par « mcp-organizer --setup ».",
+    "# Relancer le setup réécrit les variables qu'il gère et conserve les autres.",
+    "# Ce fichier contient des secrets : il n'est lisible que par son propriétaire.",
+];
+const COMMENTS = {
+    ORGANIZER_PUBLIC_URL: "# URL ouverte par les utilisateurs, derrière nginx.",
+    PORT: "# Écoute du site ; nginx le joint à cette adresse.",
+    MCP_ORGANIZER_DATA_DIR: "# Base SQLite, pièces jointes et journaux.",
+    GROQ_API_KEY: "# Dictée vocale (Groq).",
+    SMTP_URL: "# Envoi des e-mails (invitations, notifications).",
+};
+function managedLines(keys, values) {
+    const lines = [];
+    for (const key of keys) {
+        const value = values[key];
+        if (value === null)
+            continue;
+        const comment = COMMENTS[key];
+        if (comment)
+            lines.push("", comment);
+        lines.push(`${key}=${formatEnvValue(key, value)}`);
+    }
+    return lines;
+}
+/** Contenu du fichier `.env` : `existing` fusionné avec `values`, ou un fichier neuf. */
+export function renderEnvFile(existing, values) {
+    if (existing === undefined || existing.trim() === "") {
+        return [...HEADER, ...managedLines(MANAGED_ENV_KEYS, values), ""].join("\n");
+    }
+    const managed = new Set(MANAGED_ENV_KEYS);
+    const removed = new Set(REMOVED_ENV_KEYS);
+    const written = new Set();
+    const lines = [];
+    for (const line of existing.replace(/\r\n/g, "\n").replace(/\n+$/, "").split("\n")) {
+        const key = KEY_LINE.exec(line)?.[1];
+        if (key === undefined || (!managed.has(key) && !removed.has(key))) {
+            lines.push(line);
+            continue;
+        }
+        if (removed.has(key) || written.has(key))
+            continue;
+        const value = values[key];
+        written.add(key);
+        if (value !== null)
+            lines.push(`${key}=${formatEnvValue(key, value)}`);
+    }
+    const missing = MANAGED_ENV_KEYS.filter((key) => !written.has(key) && values[key] !== null);
+    if (missing.length > 0) {
+        lines.push("", "# Ajouté par « mcp-organizer --setup ».", ...managedLines(missing, values).filter((line) => line !== "" && !line.startsWith("#")));
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/src/deploy/templates.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Fichiers de déploiement produits par `mcp-organizer --setup`, remplis avec
+ * les réponses : l'unité systemd du site et son bloc nginx.
+ */
+export interface DeploymentAnswers {
+    /** URL publique sans barre oblique finale. */
+    publicUrl: string;
+    /** Chemin de base, `/` ou `/organizer`. */
+    basePath: string;
+    host: string;
+    port: number;
+    /** Répertoire de données, absolu. */
+    dataDir: string;
+}
+export interface DeploymentContext {
+    /** Racine du dépôt cloné, où se trouve `dist/src/index.js`. */
+    installDir: string;
+    /** Fichier `.env` passé au site par `--dotenv`. */
+    envFilePath: string;
+    /** Compte système qui exécute le site. */
+    serviceUser: string;
+    /** Exécutable Node.js. */
+    nodePath: string;
+}
+/** Nom de l'unité systemd et du site nginx. */
+export declare const SERVICE_NAME = "mcp-organizer";
+/** `client_max_body_size` de nginx : la plus grosse requête admise par le site, arrondie au Mo supérieur. */
+export declare function nginxBodyLimit(): string;
+/** Adresse par laquelle nginx joint le site : la boucle locale quand le site écoute sur toutes les interfaces. */
+export declare function upstreamAddress(host: string, port: number): string;
+/** Unité systemd du site : `mcp-organizer --server`, compte dédié, redémarrage, durcissement. */
+export declare function renderSystemdUnit(answers: DeploymentAnswers, context: DeploymentContext): string;
+/**
+ * Bloc nginx : HTTPS (redirection du port 80), proxy vers `HOST:PORT` avec les
+ * en-têtes `X-Forwarded-*`, taille des corps alignée sur le site, API jamais
+ * mise en cache. Publié sous un chemin, le préfixe est retiré avant le site.
+ */
+export declare function renderNginx(answers: DeploymentAnswers): string;

package/dist/src/deploy/templates.js

@@ -0,0 +1,130 @@
+import net from "node:net";
+import { MAX_BODY_BYTES } from "../server/limits.js";
+/** Nom de l'unité systemd et du site nginx. */
+export const SERVICE_NAME = "mcp-organizer";
+/** `client_max_body_size` de nginx : la plus grosse requête admise par le site, arrondie au Mo supérieur. */
+export function nginxBodyLimit() {
+    return `${Math.ceil(MAX_BODY_BYTES / (1024 * 1024))}m`;
+}
+/** Adresse par laquelle nginx joint le site : la boucle locale quand le site écoute sur toutes les interfaces. */
+export function upstreamAddress(host, port) {
+    if (host === "0.0.0.0")
+        return `127.0.0.1:${port}`;
+    if (host === "::")
+        return `[::1]:${port}`;
+    return net.isIPv6(host) ? `[${host}]:${port}` : `${host}:${port}`;
+}
+/** Argument d'une directive systemd, entre guillemets s'il contient un blanc. */
+function systemdArg(value) {
+    if (/[\r\n]/.test(value))
+        throw new Error(`Chemin sur plusieurs lignes refusé dans l'unité systemd : ${JSON.stringify(value)}.`);
+    return /[\s"'\\]/.test(value) ? `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : value;
+}
+function entryPoint(installDir) {
+    return `${installDir.replace(/[\\/]+$/, "")}/dist/src/index.js`;
+}
+/** Unité systemd du site : `mcp-organizer --server`, compte dédié, redémarrage, durcissement. */
+export function renderSystemdUnit(answers, context) {
+    const privilegedPort = answers.port < 1024;
+    const capabilities = privilegedPort
+        ? ["# Port inférieur à 1024 : seule la capacité de s'y lier est accordée.", "AmbientCapabilities=CAP_NET_BIND_SERVICE", "CapabilityBoundingSet=CAP_NET_BIND_SERVICE"]
+        : ["CapabilityBoundingSet="];
+    return [
+        "# Unité systemd du site mcp-organizer, écrite par « mcp-organizer --setup ».",
+        `# Installation : cp ${SERVICE_NAME}.service /etc/systemd/system/ && systemctl daemon-reload && systemctl enable --now ${SERVICE_NAME}`,
+        "",
+        "[Unit]",
+        "Description=mcp-organizer (site web : interface, API, base)",
+        `Documentation=file:${context.installDir.replace(/[\\/]+$/, "")}/README.md`,
+        "After=network-online.target",
+        "Wants=network-online.target",
+        "",
+        "[Service]",
+        "Type=simple",
+        `User=${context.serviceUser}`,
+        `Group=${context.serviceUser}`,
+        `WorkingDirectory=${context.installDir}`,
+        "Environment=NODE_ENV=production",
+        "# La configuration est lue dans le fichier .env, à chaque démarrage.",
+        `ExecStart=${systemdArg(context.nodePath)} ${systemdArg(entryPoint(context.installDir))} --server ${systemdArg(`--dotenv=${context.envFilePath}`)}`,
+        "Restart=on-failure",
+        "RestartSec=5",
+        "TimeoutStopSec=30",
+        "UMask=0077",
+        "",
+        "# Durcissement : le site n'écrit que dans son répertoire de données.",
+        "NoNewPrivileges=true",
+        "PrivateTmp=true",
+        "PrivateDevices=true",
+        "ProtectSystem=strict",
+        "ProtectHome=read-only",
+        `ReadWritePaths=${systemdArg(answers.dataDir)}`,
+        "ProtectKernelTunables=true",
+        "ProtectKernelModules=true",
+        "ProtectKernelLogs=true",
+        "ProtectControlGroups=true",
+        "ProtectClock=true",
+        "ProtectHostname=true",
+        "RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX",
+        "RestrictNamespaces=true",
+        "RestrictRealtime=true",
+        "RestrictSUIDSGID=true",
+        "LockPersonality=true",
+        "SystemCallArchitectures=native",
+        ...capabilities,
+        "",
+        "StandardOutput=journal",
+        "StandardError=journal",
+        `SyslogIdentifier=${SERVICE_NAME}`,
+        "",
+        "[Install]",
+        "WantedBy=multi-user.target",
+        "",
+    ].join("\n");
+}
+/** Bloc `location` de l'API : jamais mis en cache, ni par nginx ni par le navigateur. */
+function apiLocation(prefix, upstream, hsts) {
+    return [
+        `    location ${prefix}api/ {`,
+        `        proxy_pass ${upstream};`,
+        "        proxy_cache off;",
+        "        proxy_hide_header Cache-Control;",
+        '        add_header Cache-Control "no-store" always;',
+        ...(hsts ? ['        add_header Strict-Transport-Security "max-age=31536000" always;'] : []),
+        "    }",
+    ];
+}
+/**
+ * Bloc nginx : HTTPS (redirection du port 80), proxy vers `HOST:PORT` avec les
+ * en-têtes `X-Forwarded-*`, taille des corps alignée sur le site, API jamais
+ * mise en cache. Publié sous un chemin, le préfixe est retiré avant le site.
+ */
+export function renderNginx(answers) {
+    const url = new URL(answers.publicUrl);
+    const https = url.protocol === "https:";
+    const serverName = url.hostname.replace(/^\[|\]$/g, "");
+    const upstreamHost = `http://${upstreamAddress(answers.host, answers.port)}`;
+    const prefix = answers.basePath === "/" ? "/" : `${answers.basePath}/`;
+    // proxy_pass avec un chemin retire le préfixe publié ; sans chemin, l'URI est transmise telle quelle.
+    const upstream = answers.basePath === "/" ? upstreamHost : `${upstreamHost}/`;
+    const apiUpstream = answers.basePath === "/" ? upstreamHost : `${upstreamHost}/api/`;
+    const lines = [
+        `# Bloc nginx du site mcp-organizer (${answers.publicUrl}), écrit par « mcp-organizer --setup ».`,
+        `# Le site écoute sur ${upstreamAddress(answers.host, answers.port)} ; nginx seul est exposé.`,
+        ...(answers.basePath === "/" ? [] : ["# Les blocs location peuvent aussi être placés dans le server existant de ce nom d'hôte."]),
+        "",
+    ];
+    if (https) {
+        lines.push("server {", "    listen 80;", "    listen [::]:80;", `    server_name ${serverName};`, "    return 301 https://$host$request_uri;", "}", "", "server {", 
+        // « listen … http2 » est accepté depuis nginx 1.9.5 (avec un avertissement à partir de 1.25.1) ; « http2 on; » exige 1.25.1.
+        "    listen 443 ssl http2;", "    listen [::]:443 ssl http2;", `    server_name ${serverName};`, "", "    # Certificat Let's Encrypt (certbot certonly --nginx -d " + serverName + ").", `    ssl_certificate     /etc/letsencrypt/live/${serverName}/fullchain.pem;`, `    ssl_certificate_key /etc/letsencrypt/live/${serverName}/privkey.pem;`, '    add_header Strict-Transport-Security "max-age=31536000" always;');
+    }
+    else {
+        lines.push("# URL publique en http : réservé à un essai local, sans TLS.", "server {", "    listen 80;", `    server_name ${serverName};`);
+    }
+    lines.push("", "    # Pièces jointes (20 Mo) et dictée (25 Mo), enveloppe du formulaire comprise.", `    client_max_body_size ${nginxBodyLimit()};`, "", "    proxy_http_version 1.1;", "    proxy_set_header Host              $host;", "    proxy_set_header X-Real-IP         $remote_addr;", "    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;", "    proxy_set_header X-Forwarded-Proto $scheme;", "    proxy_set_header X-Forwarded-Host  $host;", "    # La dictée attend la réponse de Groq.", "    proxy_read_timeout 120s;", "");
+    if (answers.basePath !== "/")
+        lines.push(`    location = ${answers.basePath} {`, `        return 301 ${prefix};`, "    }", "");
+    lines.push(...apiLocation(prefix, apiUpstream, https), "", `    location ${prefix} {`, `        proxy_pass ${upstream};`, "    }", "}", "");
+    return lines.join("\n");
+}

package/dist/src/gui-api.d.ts

@@ -0,0 +1,37 @@
+import { type ApiRequestData, type ApiResponseData, type ApiErrorKind } from "../shared/schemas/gui-api.schema.js";
+import type { AttachmentStorage } from "./core/attachments.js";
+import type { Mailer } from "./core/mail.js";
+import type { Store } from "./core/store.js";
+import { type Transcriber } from "./core/transcription.js";
+/** Erreur d'une requête de la GUI, avec la nature qui fixe son code HTTP. */
+export declare class ApiError extends Error {
+    readonly kind: ApiErrorKind;
+    /** Code HTTP imposé à la réponse, à la place de celui de `kind`. */
+    readonly status?: number | undefined;
+    constructor(kind: ApiErrorKind, message: string, 
+    /** Code HTTP imposé à la réponse, à la place de celui de `kind`. */
+    status?: number | undefined);
+}
+/** Nature d'une erreur levée en traitant une requête de la GUI. */
+export declare function errorKindOf(err: unknown): ApiErrorKind;
+/** Code HTTP imposé par une erreur : celui que Groq a renvoyé pour une transcription refusée. */
+export declare function errorStatusOf(err: unknown): number | undefined;
+export interface GuiApiContext {
+    store: Store;
+    version: string;
+    mailer: Mailer;
+    /** URL publique de la GUI (`ORGANIZER_PUBLIC_URL`), base des liens envoyés par e-mail. */
+    publicUrl: string | undefined;
+    /** Fichiers des pièces jointes. */
+    attachments: AttachmentStorage;
+    /** Dictée vocale (API Groq). */
+    transcriber: Transcriber;
+    /** Horloge, imposée par les tests. */
+    now?: () => Date;
+}
+/**
+ * Traite une requête `/api/*` de la GUI. Hors des routes
+ * publiques (santé, connexion, déconnexion, liens d'accès), une session valide
+ * est exigée ; une session prolongée renvoie son nouveau cookie.
+ */
+export declare function handleApiRequest(ctx: GuiApiContext, request: ApiRequestData): Promise<ApiResponseData>;