palabre 0.6.0 → 0.6.3

package/README.md

@@ -50,6 +50,7 @@ palabre -s "Compare ces deux approches" -t 2
 palabre codex-claude "Relis cette architecture" --context src docs
 palabre claude-ollama "Critique ce fichier" --files README.md
 palabre codex-claude "Preview" --context src --show-prompt
+palabre context scan src docs --json
 ```
 
 ### Agents supportés
@@ -63,10 +64,22 @@ palabre codex-claude "Preview" --context src --show-prompt
 
 PALABRE ne liste pas les modèles : ils changent souvent et dépendent de chaque CLI ou compte utilisateur. `--model-a`, `--model-b` et `--summary-model` transmettent simplement la valeur brute à l'agent concerné.
 
+### Intégrations
+
+PALABRE expose des sorties JSON versionnées pour les clients externes :
+
+- `palabre presets --json` pour lire les paires d'agents disponibles ;
+- `palabre context scan --json` pour prévisualiser le contexte que `--context` retiendrait ;
+- `--renderer ndjson` ou `--json` pour suivre un débat événement par événement.
+
+Le flux NDJSON v1 est traité comme une API publique d'intégration. Les ajouts compatibles se font sans casser v1 ; les changements cassants doivent changer le champ `v`.
+
 ### Confidentialité
 
 PALABRE tourne localement et n'envoie aucune donnée à un serveur appartenant à PALABRE. Les données envoyées aux agents dépendent des outils que vous utilisez : vérifiez les politiques de confidentialité de Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, OpenCode, Ollama ou de tout autre agent configuré.
 
+Si un agent échoue pendant le débat ou la synthèse, PALABRE conserve l'export Markdown partiel avec une section d'interruption quand c'est possible.
+
 ### Développement local
 
 ```bash
@@ -80,7 +93,9 @@ palabre --version
 
 Commandes utiles : `pnpm check`, `pnpm test`, `pnpm build`.
 
-Roadmap publique : [docs/guide/fr/roadmap.md](./docs/guide/fr/roadmap.md). Guide agents/contributeurs : [AGENTS.md](./AGENTS.md).
+Avant une publication, `pnpm smoke:real-presets -- --keep-going` lance des débats réels sur les presets prioritaires disponibles afin de vérifier le flux complet agent → NDJSON → export. Ce smoke test appelle de vraies CLIs IA et peut consommer des quotas ; il n'est donc pas lancé par `pnpm test`.
+
+Roadmap publique : [docs/guide/fr/roadmap.md](./docs/guide/fr/roadmap.md). Changements : [CHANGELOG.md](./CHANGELOG.md). Guide agents/contributeurs : [AGENTS.md](./AGENTS.md).
 
 ### Licence
 
@@ -97,7 +112,7 @@ It does not replace your tools: it drives them. You keep your subscriptions, def
 - https://palab.re
 - https://palabre.netlify.app
 
-Useful pages: [Installation](https://palab.re/fr/get-started/installation), [Configuration](https://palab.re/fr/get-started/configuration), [First debate](https://palab.re/fr/get-started/first-debate), [CLI reference](https://palab.re/fr/reference/cli), [Troubleshooting](https://palab.re/fr/troubleshooting), [Roadmap](https://palab.re/fr/roadmap).
+Useful pages: [Installation](https://palab.re/en/get-started/installation), [Configuration](https://palab.re/en/get-started/configuration), [First debate](https://palab.re/en/get-started/first-debate), [CLI reference](https://palab.re/en/reference/cli), [Troubleshooting](https://palab.re/en/troubleshooting), [Roadmap](https://palab.re/en/roadmap).
 
 ### Installation
 
@@ -125,6 +140,7 @@ palabre -s "Compare these two approaches" -t 2
 palabre codex-claude "Review this architecture" --context src docs
 palabre claude-ollama "Review this file" --files README.md
 palabre codex-claude "Preview" --context src --show-prompt
+palabre context scan src docs --json
 ```
 
 ### Supported Agents
@@ -138,10 +154,22 @@ palabre codex-claude "Preview" --context src --show-prompt
 
 PALABRE does not list models: they change often and depend on each CLI or user account. `--model-a`, `--model-b`, and `--summary-model` simply pass the raw value to the selected agent.
 
+### Integrations
+
+PALABRE exposes versioned JSON outputs for external clients:
+
+- `palabre presets --json` to read available agent pairs;
+- `palabre context scan --json` to preview the context `--context` would retain;
+- `--renderer ndjson` or `--json` to follow a debate event by event.
+
+The NDJSON v1 stream is treated as a public integration API. Compatible additions do not break v1; breaking changes must change the `v` field.
+
 ### Privacy
 
 PALABRE runs locally and does not send data to a PALABRE-owned server. Data sent to agents depends on the tools you use: check the privacy policies of Claude Code, Codex CLI, Gemini CLI, Antigravity CLI, OpenCode, Ollama, or any custom agent you configure.
 
+If an agent fails during the debate or final summary, PALABRE keeps the partial Markdown export with an interruption section whenever possible.
+
 ### Local Development
 
 ```bash
@@ -155,7 +183,9 @@ palabre --version
 
 Useful commands: `pnpm check`, `pnpm test`, `pnpm build`.
 
-Public roadmap: [docs/guide/fr/roadmap.md](./docs/guide/fr/roadmap.md). Agent/contributor guide: [AGENTS.md](./AGENTS.md).
+Before publishing, `pnpm smoke:real-presets -- --keep-going` runs real debates for the available priority presets to validate the full agent → NDJSON → export flow. This smoke test calls real AI CLIs and may consume quota, so it is not part of `pnpm test`.
+
+Public roadmap: [docs/guide/fr/roadmap.md](./docs/guide/fr/roadmap.md). Changes: [CHANGELOG.md](./CHANGELOG.md). Agent/contributor guide: [AGENTS.md](./AGENTS.md).
 
 ### License
 

package/dist/adapters/cli-pty.js

@@ -1,8 +1,9 @@
-import { spawn as spawnPty } from "node-pty";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { AdapterError } from "../errors.js";
+import { executableExtensions } from "../exec.js";
 import { formatAgentPrompt } from "../prompt.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS, withModelArgs } from "./cli-shared.js";
 import { cleanTerminalOutput } from "./terminal.js";
 /**
  * Adapter pour les CLIs qui exigent un vrai terminal.
@@ -43,13 +44,16 @@ export class CliPtyAdapter {
         const args = promptMode === "argument"
             ? [...baseArgs, renderedPrompt]
             : baseArgs;
+        const { spawn: spawnPty } = await import("node-pty");
         return new Promise((resolve, reject) => {
             let output = "";
+            let outputBytes = 0;
             let settled = false;
             let hardTimer;
             let term;
             let dataSubscription;
             let exitSubscription;
+            const maxOutputBytes = this.config.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
             const finish = (error, exitCode, kill = true) => {
                 if (settled)
                     return;
@@ -104,11 +108,19 @@ export class CliPtyAdapter {
                 return;
             }
             hardTimer = setTimeout(() => {
-                finish(new AdapterError("timeout", this.name, `${this.name} timed out after ${this.config.timeoutMs ?? 180_000}ms`, {
-                    timeoutMs: this.config.timeoutMs ?? 180_000
+                finish(new AdapterError("timeout", this.name, `${this.name} timed out after ${this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`, {
+                    timeoutMs: this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS
                 }));
-            }, this.config.timeoutMs ?? 180_000);
+            }, this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
             dataSubscription = term.onData((chunk) => {
+                outputBytes += Buffer.byteLength(chunk, "utf8");
+                if (outputBytes > maxOutputBytes) {
+                    finish(new AdapterError("output-too-large", this.name, `${this.name} produced more than ${maxOutputBytes} bytes of PTY output`, {
+                        maxOutputBytes,
+                        outputBytes
+                    }));
+                    return;
+                }
                 output += chunk;
             });
             exitSubscription = term.onExit(({ exitCode }) => {
@@ -147,30 +159,6 @@ function cleanupPty(term) {
         // Best-effort cleanup for Windows ConPTY internals.
     }
 }
-function executableExtensions(command) {
-    if (path.extname(command) || process.platform !== "win32") {
-        return [""];
-    }
-    return (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
-        .split(";")
-        .map((extension) => extension.toLowerCase())
-        .concat(".ps1", "");
-}
-function withModelArgs(args, model, modelArg) {
-    if (!model) {
-        return [...args];
-    }
-    const promptStdinIndex = args.lastIndexOf("-");
-    if (promptStdinIndex === args.length - 1) {
-        return [
-            ...args.slice(0, promptStdinIndex),
-            modelArg,
-            model,
-            ...args.slice(promptStdinIndex)
-        ];
-    }
-    return [...args, modelArg, model];
-}
 function createPtyExitError(adapterName, exitCode, raw) {
     return new AdapterError("non-zero-exit", adapterName, `${adapterName} exited with code ${exitCode}: ${summarizePtyOutput(raw)}`, {
         exitCode,

package/dist/adapters/cli-shared.js

@@ -0,0 +1,24 @@
+/** Limite de sortie par défaut des adapters CLI/PTY : 50 Mio avant `output-too-large`. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 50 * 1024 * 1024;
+/** Timeout dur par défaut d'un appel d'agent CLI/PTY (3 minutes). */
+export const DEFAULT_TIMEOUT_MS = 180_000;
+/**
+ * Insère `modelArg model` dans la liste d'arguments d'une commande CLI.
+ * Si le dernier argument est `-` (marqueur stdin), insère avant lui pour
+ * préserver l'ordre attendu par les CLIs qui lisent le prompt sur stdin.
+ */
+export function withModelArgs(args, model, modelArg) {
+    if (!model) {
+        return [...args];
+    }
+    const promptStdinIndex = args.lastIndexOf("-");
+    if (promptStdinIndex === args.length - 1) {
+        return [
+            ...args.slice(0, promptStdinIndex),
+            modelArg,
+            model,
+            ...args.slice(promptStdinIndex)
+        ];
+    }
+    return [...args, modelArg, model];
+}

package/dist/adapters/cli.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { AdapterError } from "../errors.js";
 import { formatAgentPrompt } from "../prompt.js";
+import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS, withModelArgs } from "./cli-shared.js";
 import { cleanTerminalOutput } from "./terminal.js";
 /**
  * Adapter pour les CLIs batch (Codex, Claude, Gemini…).
@@ -50,8 +51,10 @@ export class CliAdapter {
             let stdout = "";
             let stderr = "";
             let settled = false;
+            let outputBytes = 0;
             let hardTimer;
             let idleTimer;
+            const maxOutputBytes = this.config.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
             const finish = (error) => {
                 if (settled)
                     return;
@@ -78,10 +81,10 @@ export class CliAdapter {
             };
             hardTimer = setTimeout(() => {
                 child.kill();
-                finish(new AdapterError("timeout", this.name, `${this.name} timed out after ${this.config.timeoutMs ?? 180_000}ms`, {
-                    timeoutMs: this.config.timeoutMs ?? 180_000
+                finish(new AdapterError("timeout", this.name, `${this.name} timed out after ${this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms`, {
+                    timeoutMs: this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS
                 }));
-            }, this.config.timeoutMs ?? 180_000);
+            }, this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS);
             const bumpIdleTimer = () => {
                 if (!this.config.idleTimeoutMs)
                     return;
@@ -94,10 +97,28 @@ export class CliAdapter {
             };
             bumpIdleTimer();
             child.stdout.on("data", (chunk) => {
+                outputBytes += chunk.length;
+                if (outputBytes > maxOutputBytes) {
+                    child.kill();
+                    finish(new AdapterError("output-too-large", this.name, `${this.name} produced more than ${maxOutputBytes} bytes of output`, {
+                        maxOutputBytes,
+                        outputBytes
+                    }));
+                    return;
+                }
                 stdout += chunk.toString("utf8");
                 bumpIdleTimer();
             });
             child.stderr.on("data", (chunk) => {
+                outputBytes += chunk.length;
+                if (outputBytes > maxOutputBytes) {
+                    child.kill();
+                    finish(new AdapterError("output-too-large", this.name, `${this.name} produced more than ${maxOutputBytes} bytes of output`, {
+                        maxOutputBytes,
+                        outputBytes
+                    }));
+                    return;
+                }
                 stderr += chunk.toString("utf8");
                 bumpIdleTimer();
             });
@@ -123,28 +144,45 @@ export class CliAdapter {
         });
     }
 }
-/**
- * Insère `modelArg model` dans la liste d'arguments.
- * Si le dernier argument est `-` (stdin marker), insère avant lui pour préserver l'ordre attendu par les CLIs.
- */
-function withModelArgs(args, model, modelArg) {
-    if (!model) {
-        return [...args];
-    }
-    const promptStdinIndex = args.lastIndexOf("-");
-    if (promptStdinIndex === args.length - 1) {
-        return [
-            ...args.slice(0, promptStdinIndex),
-            modelArg,
-            model,
-            ...args.slice(promptStdinIndex)
-        ];
-    }
-    return [...args, modelArg, model];
-}
 /** Retire les séquences ANSI et les espaces en tête/fin. */
 function cleanCliOutput(output) {
-    return cleanTerminalOutput(output);
+    return stripWindowsTaskkillNoise(cleanTerminalOutput(output));
+}
+function stripWindowsTaskkillNoise(output) {
+    const lines = output.split("\n");
+    const kept = [];
+    let skipNextFrenchContinuation = false;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const normalized = normalizeForWindowsStatus(trimmed);
+        if (skipNextFrenchContinuation && /^arr.*t.*\.$/i.test(normalized)) {
+            skipNextFrenchContinuation = false;
+            continue;
+        }
+        skipNextFrenchContinuation = false;
+        if (isWindowsTaskkillStatusLine(trimmed)) {
+            skipNextFrenchContinuation = true;
+            continue;
+        }
+        kept.push(line);
+    }
+    return kept.join("\n").trim();
+}
+function isWindowsTaskkillStatusLine(line) {
+    const normalized = normalizeForWindowsStatus(line);
+    const lower = line.toLowerCase();
+    return (/^SUCCESS:\s+The process with PID \d+ .* has been terminated\.$/i.test(line) ||
+        /^operation reussie.*processus de pid \d+ .* a ete$/.test(normalized) ||
+        (lower.startsWith("op") &&
+            lower.includes("processus de pid ") &&
+            lower.includes("processus enfant de pid") &&
+            lower.includes(" a ")));
+}
+function normalizeForWindowsStatus(line) {
+    return line
+        .normalize("NFD")
+        .replace(/\p{Diacritic}/gu, "")
+        .toLowerCase();
 }
 /**
  * Construit une `AdapterError` typée depuis un exit code non nul.

package/dist/adapters/ollama.js

@@ -1,4 +1,5 @@
 import { AdapterError } from "../errors.js";
+import { createTranslator } from "../i18n.js";
 import { formatAgentPrompt } from "../prompt.js";
 /**
  * Adapter pour Ollama via l'API HTTP locale (`POST /api/chat`).
@@ -57,7 +58,7 @@ export class OllamaAdapter {
                         {
                             role: "system",
                             content: this.config.systemPrompt ??
-                                "Tu participes a un debat technique orchestre. Reste precis, utile et honnete sur tes limites."
+                                createTranslator(prompt.language ?? "fr").prompt.ollamaSystemPrompt
                         },
                         {
                             role: "user",

package/dist/agentRegistry.js

@@ -0,0 +1,76 @@
+/**
+ * Agents CLI connus, dans l'ordre d'affichage canonique.
+ * `ollama-local` n'est pas listé ici : ce n'est pas une commande CLI, il est
+ * géré séparément via `discovery.ollama`.
+ */
+const KNOWN_CLI_AGENTS = [
+    { configKey: "codex", commandAliases: ["codex"], discoveryKey: "codex" },
+    { configKey: "claude", commandAliases: ["claude"], discoveryKey: "claude" },
+    { configKey: "gemini", commandAliases: ["gemini"], discoveryKey: "gemini" },
+    { configKey: "antigravity", commandAliases: ["agy", "antigravity"], discoveryKey: "antigravity" },
+    { configKey: "opencode", commandAliases: ["opencode"], discoveryKey: "opencode" }
+];
+/** Clé de config de l'agent Ollama local par défaut. */
+export const OLLAMA_AGENT_KEY = "ollama-local";
+/**
+ * Extrait le nom de base d'une commande en supprimant le chemin et l'extension
+ * exécutable Windows éventuelle (ex. `C:\bin\claude.cmd` → `claude`).
+ */
+export function normalizeCommandName(command) {
+    return command
+        .split(/[\\/]/)
+        .pop()
+        ?.toLowerCase()
+        .replace(/\.(exe|cmd|bat|ps1)$/i, "") ?? command.toLowerCase();
+}
+/**
+ * Résout l'entrée de découverte d'une commande d'agent CLI connue.
+ * Retourne `undefined` pour une commande custom non reconnue : Palabre ne peut
+ * pas connaître sa sémantique sans la lancer, donc l'appelant la considère
+ * généralement comme disponible.
+ */
+export function detectionForCommand(command, discovery) {
+    const normalized = normalizeCommandName(command);
+    const known = KNOWN_CLI_AGENTS.find((agent) => agent.commandAliases.includes(normalized));
+    return known ? discovery[known.discoveryKey] : undefined;
+}
+/**
+ * Liste les clés d'agents connus effectivement détectés localement, dans
+ * l'ordre canonique (`codex`, `claude`, `gemini`, `antigravity`, `opencode`,
+ * puis `ollama-local`).
+ */
+export function detectedAgentNames(discovery) {
+    const names = KNOWN_CLI_AGENTS
+        .filter((agent) => discovery[agent.discoveryKey].available)
+        .map((agent) => agent.configKey);
+    if (discovery.ollama.available) {
+        names.push(OLLAMA_AGENT_KEY);
+    }
+    return names;
+}
+/**
+ * Applique les chemins de commande résolus localement aux agents CLI connus
+ * d'une config. Mute `config` : l'appelant est responsable de la cloner au besoin.
+ * Sans détection disponible, l'agent garde la commande déjà déclarée.
+ */
+export function applyDetectedCommands(config, discovery) {
+    for (const agent of KNOWN_CLI_AGENTS) {
+        const detection = discovery[agent.discoveryKey];
+        const cfg = config.agents[agent.configKey];
+        if (detection.available && cfg && (cfg.type === "cli" || cfg.type === "cli-pty")) {
+            cfg.command = detection.command;
+        }
+    }
+}
+/**
+ * Indique si un agent de config est détecté localement.
+ * Pour Ollama, reflète l'accessibilité du serveur ; pour les CLIs connues, l'état
+ * de découverte ; pour une CLI custom inconnue, retourne `true` (faute de pouvoir vérifier).
+ */
+export function isAgentDetected(name, config, discovery) {
+    if (config.type === "ollama") {
+        return discovery.ollama.available;
+    }
+    const detection = detectionForCommand(config.command || name, discovery);
+    return detection ? detection.available : true;
+}

package/dist/args.js

@@ -0,0 +1,265 @@
+import { listPresetNames } from "./presets.js";
+/**
+ * Table centrale décrivant l'arité de chaque flag long canonique.
+ *
+ * C'est la source de vérité du parser : un flag `boolean` ne consomme jamais le
+ * token suivant (évite que `--plain codex-claude "x"` avale le preset), un flag
+ * `single` exige une valeur, un flag `multi` collecte plusieurs valeurs.
+ *
+ * Les noms sont les noms canoniques après `normalizeFlagName` (ex. `subject`
+ * est normalisé en `topic` avant la recherche dans cette table).
+ */
+const FLAG_SPECS = {
+    // Booléens : présence = vrai, aucune valeur consommée.
+    help: { arity: "boolean" },
+    version: { arity: "boolean" },
+    plain: { arity: "boolean" },
+    json: { arity: "boolean" },
+    "no-summary": { arity: "boolean" },
+    "no-early-stop": { arity: "boolean" },
+    "show-prompt": { arity: "boolean" },
+    "pull-models": { arity: "boolean" },
+    local: { arity: "boolean" },
+    apply: { arity: "boolean" },
+    "clear-defaults": { arity: "boolean" },
+    "sync-agents": { arity: "boolean" },
+    // Valeur unique.
+    "agent-a": { arity: "single" },
+    "agent-b": { arity: "single" },
+    config: { arity: "single" },
+    language: { arity: "single" },
+    "model-a": { arity: "single" },
+    "model-b": { arity: "single" },
+    preset: { arity: "single" },
+    "summary-agent": { arity: "single" },
+    "summary-model": { arity: "single" },
+    topic: { arity: "single" },
+    turns: { arity: "single" },
+    renderer: { arity: "single" },
+    // Valeurs multiples.
+    "set-defaults": { arity: "multi", max: 2 },
+    files: { arity: "multi" },
+    context: { arity: "multi" }
+};
+/** Commandes acceptées comme premier argument positionnel. */
+const COMMANDS = new Set([
+    "run",
+    "new",
+    "init",
+    "setup",
+    "help",
+    "version",
+    "update",
+    "doctor",
+    "config",
+    "agent",
+    "agents",
+    "preset",
+    "presets",
+    "context"
+]);
+/**
+ * Parse `process.argv` en une structure typée `ParsedArgs`.
+ * Gère les flags courts (-h, -v, -s, -t, -a), les flags longs pilotés par
+ * `FLAG_SPECS`, les flags multi-valeurs (--files, --context, --set-defaults) et
+ * les positionnels.
+ * @param args - Tableau d'arguments (généralement `process.argv.slice(2)`).
+ * @returns Commande détectée, indicateur d'explicitation et map de flags.
+ */
+export function parseArgs(args, messages) {
+    const flags = {};
+    let command = "run";
+    let commandExplicit = false;
+    const positionals = [];
+    const presets = new Set(listPresetNames());
+    for (let index = 0; index < args.length; index += 1) {
+        const value = args[index];
+        if (!value.startsWith("-") && !commandExplicit && positionals.length === 0 && COMMANDS.has(value)) {
+            command = value;
+            commandExplicit = true;
+            continue;
+        }
+        if (!value.startsWith("-") && index === 0) {
+            if (COMMANDS.has(value)) {
+                command = value;
+                commandExplicit = true;
+            }
+            else if (isLikelyCommandTypo(value, COMMANDS)) {
+                throw new Error(messages.common.unknownCommand(value, Array.from(COMMANDS).join(", ")));
+            }
+            else {
+                positionals.push(value);
+            }
+            continue;
+        }
+        if (!value.startsWith("-")) {
+            positionals.push(value);
+            continue;
+        }
+        if (value === "-h") {
+            flags.help = true;
+            continue;
+        }
+        if (value === "-v") {
+            flags.version = true;
+            continue;
+        }
+        if (value === "-a") {
+            command = "agents";
+            commandExplicit = true;
+            continue;
+        }
+        if (value === "-s") {
+            const next = args[index + 1];
+            if (!next || next.startsWith("-")) {
+                throw new Error(messages.common.optionRequiresValue("-s"));
+            }
+            flags.topic = next;
+            index += 1;
+            continue;
+        }
+        if (value === "-t") {
+            const next = args[index + 1];
+            if (!next || next.startsWith("-")) {
+                throw new Error(messages.common.optionRequiresValue("-t"));
+            }
+            flags.turns = next;
+            index += 1;
+            continue;
+        }
+        if (value.startsWith("--")) {
+            const rawKey = value.slice(2);
+            const key = normalizeFlagName(rawKey);
+            const spec = FLAG_SPECS[key];
+            if (spec?.arity === "multi") {
+                const values = [];
+                while (args[index + 1] && !args[index + 1].startsWith("-") && (spec.max === undefined || values.length < spec.max)) {
+                    values.push(args[index + 1]);
+                    index += 1;
+                }
+                if (key === "set-defaults" && values.length !== 2) {
+                    throw new Error(messages.common.setDefaultsRequiresTwo);
+                }
+                flags[key] = key === "set-defaults"
+                    ? values
+                    : [...getStringListFlag(flags[key]), ...values];
+                continue;
+            }
+            if (spec?.arity === "boolean") {
+                flags[key] = true;
+                continue;
+            }
+            const next = args[index + 1];
+            const wantsValue = spec?.arity === "single";
+            if (!next || next.startsWith("-")) {
+                if (wantsValue) {
+                    throw new Error(messages.common.optionRequiresValue(`--${rawKey}`));
+                }
+                flags[key] = true;
+            }
+            else if (wantsValue) {
+                flags[key] = next;
+                index += 1;
+            }
+            else {
+                // Flag inconnu : traité comme booléen pour ne jamais avaler un positionnel.
+                flags[key] = true;
+            }
+        }
+    }
+    if (command === "run") {
+        applyRunPositionals(positionals, flags, presets, commandExplicit, COMMANDS, messages);
+    }
+    return { command, commandExplicit, positionals, flags };
+}
+/**
+ * Détecte si une valeur ressemble à une faute de frappe d'une commande connue
+ * (même première lettre et distance de Levenshtein ≤ 2).
+ * @param value - Token saisi par l'utilisateur.
+ * @param commands - Ensemble des commandes valides.
+ */
+export function isLikelyCommandTypo(value, commands) {
+    const normalized = value.toLowerCase();
+    for (const command of commands) {
+        if (normalized[0] === command[0] && levenshteinDistance(normalized, command) <= 2) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Calcule la distance de Levenshtein entre deux chaînes (insertions, suppressions, substitutions).
+ * @param left - Première chaîne.
+ * @param right - Deuxième chaîne.
+ * @returns Distance entière ≥ 0.
+ */
+function levenshteinDistance(left, right) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let leftIndex = 0; leftIndex < left.length; leftIndex += 1) {
+        let diagonal = previous[0];
+        previous[0] = leftIndex + 1;
+        for (let rightIndex = 0; rightIndex < right.length; rightIndex += 1) {
+            const insertCost = previous[rightIndex + 1] + 1;
+            const deleteCost = previous[rightIndex] + 1;
+            const replaceCost = diagonal + (left[leftIndex] === right[rightIndex] ? 0 : 1);
+            diagonal = previous[rightIndex + 1];
+            previous[rightIndex + 1] = Math.min(insertCost, deleteCost, replaceCost);
+        }
+    }
+    return previous[right.length] ?? 0;
+}
+/**
+ * Interprète les arguments positionnels pour la commande `run` :
+ * premier positionnel = preset si connu, sinon sujet complet concaténé.
+ * @param positionals - Arguments positionnels extraits du parseur.
+ * @param flags - Map de flags à muter si un preset ou un sujet est détecté.
+ * @param presets - Ensemble des noms de presets valides.
+ * @param commandExplicit - `true` si l'utilisateur a tapé `palabre run` explicitement.
+ */
+function applyRunPositionals(positionals, flags, presets, commandExplicit, commands, messages) {
+    if (positionals.length === 0) {
+        return;
+    }
+    const [first, ...rest] = positionals;
+    if (presets.has(first)) {
+        flags.preset ??= first;
+        if (rest.length > 0) {
+            flags.topic ??= rest.join(" ");
+        }
+        return;
+    }
+    if (!commandExplicit && positionals.length === 1 && !positionals[0]?.includes(" ")) {
+        if (isLikelyCommandTypo(positionals[0], commands)) {
+            throw new Error(messages.common.unknownCommand(positionals[0], Array.from(commands).join(", ")));
+        }
+        throw new Error(messages.common.ambiguousSubject(positionals[0]));
+    }
+    flags.topic ??= positionals.join(" ");
+}
+/**
+ * Normalise un nom de flag long en son alias canonique (ex. `subject` → `topic`).
+ * @param value - Nom brut extrait après `--`.
+ */
+export function normalizeFlagName(value) {
+    const aliases = {
+        lang: "language",
+        s: "topic",
+        subject: "topic",
+        t: "turns"
+    };
+    return aliases[value] ?? value;
+}
+/**
+ * Normalise une valeur de flag multi-valeur en tableau de chaînes.
+ * @param value - Valeur brute (tableau, chaîne unique ou absent).
+ * @returns Tableau de chaînes, vide si la valeur n'est pas applicable.
+ */
+export function getStringListFlag(value) {
+    if (Array.isArray(value)) {
+        return value;
+    }
+    if (typeof value === "string") {
+        return [value];
+    }
+    return [];
+}