palabre 0.1.7 → 0.3.0

package/README.md

@@ -7,6 +7,8 @@
   <a href="https://palab.re"><img src="https://img.shields.io/badge/docs-palab.re-18181B?logo=netlify&logoColor=7C3AED" alt="Documentation"></a>
 </p>
 
+![PALABRE](docs/assets/palabre-logo-text-og.png)
+
 [Français](#français) | [English](#english)
 
 ## Français
@@ -20,7 +22,7 @@ Il ne remplace pas vos outils : il les pilote. Vous gardez vos abonnements, vos
 - https://palab.re
 - https://palabre.netlify.app
 
-Pages utiles : [Installation](https://palab.re/get-started/installation), [Configuration](https://palab.re/get-started/configuration), [Premier débat](https://palab.re/get-started/first-debate), [Référence CLI](https://palab.re/reference/cli), [Dépannage](https://palab.re/troubleshooting), [Roadmap](https://palab.re/roadmap).
+Pages utiles : [Installation](https://palab.re/fr/get-started/installation), [Configuration](https://palab.re/fr/get-started/configuration), [Premier débat](https://palab.re/fr/get-started/first-debate), [Référence CLI](https://palab.re/fr/reference/cli), [Dépannage](https://palab.re/fr/troubleshooting), [Roadmap](https://palab.re/fr/roadmap).
 
 ### Installation
 
@@ -77,7 +79,7 @@ palabre --version
 
 Commandes utiles : `pnpm check`, `pnpm test`, `pnpm build`.
 
-Roadmap projet : [docs/roadmap.md](./docs/roadmap.md). Guide agents/contributeurs : [AGENTS.md](./AGENTS.md).
+Roadmap publique : [docs/guide/fr/roadmap.md](./docs/guide/fr/roadmap.md). Guide agents/contributeurs : [AGENTS.md](./AGENTS.md).
 
 ### Licence
 
@@ -94,7 +96,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/get-started/installation), [Configuration](https://palab.re/get-started/configuration), [First debate](https://palab.re/get-started/first-debate), [CLI reference](https://palab.re/reference/cli), [Troubleshooting](https://palab.re/troubleshooting), [Roadmap](https://palab.re/roadmap).
+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).
 
 ### Installation
 
@@ -151,7 +153,7 @@ palabre --version
 
 Useful commands: `pnpm check`, `pnpm test`, `pnpm build`.
 
-Project roadmap: [docs/roadmap.md](./docs/roadmap.md). Agent/contributor guide: [AGENTS.md](./AGENTS.md).
+Public roadmap: [docs/guide/fr/roadmap.md](./docs/guide/fr/roadmap.md). Agent/contributor guide: [AGENTS.md](./AGENTS.md).
 
 ### License
 

package/dist/index.js

@@ -13,10 +13,12 @@ import { formatAgentPrompt } from "./prompt.js";
 import { runNewWizard } from "./new.js";
 import { listPresetNames, resolvePreset } from "./presets.js";
 import { createConsoleRenderer } from "./renderers/console.js";
+import { createNdjsonRenderer } from "./renderers/ndjson.js";
 import { runDebate } from "./orchestrator.js";
 import { writeDebateMarkdown } from "./output.js";
 import { applySourceUpdate, formatUpdateInstructions, getUpdateInfo } from "./update.js";
 import { createSessionContext } from "./session.js";
+/** Point d'entrée principal du CLI Palabre. Dispatche vers la commande appropriée selon les arguments. */
 async function main() {
     const parsed = parseArgs(process.argv.slice(2));
     if (parsed.command === "version" || parsed.flags.version) {
@@ -41,6 +43,10 @@ async function main() {
         await runAgentsCommand(parsed.flags);
         return;
     }
+    if (parsed.command === "presets" || parsed.command === "preset") {
+        runPresetsCommand(parsed.flags);
+        return;
+    }
     if (parsed.command === "update") {
         const info = await getUpdateInfo(await getPackageVersion());
         if (parsed.flags.apply) {
@@ -129,12 +135,16 @@ async function main() {
         printPromptPreview(config, options);
         return;
     }
-    const renderer = createConsoleRenderer(options.plainOutput);
+    const renderer = createRendererFromFlags(parsed.flags, options.plainOutput);
     context.warnings.forEach((warning) => renderer.warning(warning));
     const result = await runDebate(config, options, renderer);
     const outputPath = await writeDebateMarkdown(config.outputDir ?? ".", result.options, result.messages, result.summary, result.stopReason);
     renderer.done(outputPath);
 }
+/**
+ * Exécute la commande `agents` : charge la config et affiche les agents déclarés avec leur état de détection.
+ * @param flags - Flags parsés depuis la ligne de commande.
+ */
 async function runAgentsCommand(flags) {
     const configPath = optionalString(flags.config) ?? await resolveDefaultConfigPath();
     if (!(await configExists(configPath))) {
@@ -144,6 +154,10 @@ async function runAgentsCommand(flags) {
     const discovery = await discoverLocalTools();
     printAgents(configPath, config, discovery);
 }
+/**
+ * Exécute la commande `config` : wizard interactif ou mise à jour directe des paramètres par défaut.
+ * @param flags - Flags parsés depuis la ligne de commande.
+ */
 async function runConfigCommand(flags) {
     const configPath = optionalString(flags.config) ?? await resolveDefaultConfigPath();
     if (!(await configExists(configPath))) {
@@ -203,9 +217,18 @@ async function runConfigCommand(flags) {
     }
     await runConfigWizard(configPath, config);
 }
+/**
+ * Renvoie `true` si la valeur représente une désactivation explicite (ex. "none", "0", "disabled").
+ * @param value - Chaîne saisie par l'utilisateur.
+ */
 function isNoneValue(value) {
     return ["0", "none", "aucun", "disabled", "désactivé", "desactive"].includes(value.trim().toLowerCase());
 }
+/**
+ * Formate les paramètres par défaut en une ligne lisible pour les messages console.
+ * @param defaults - Objet `defaults` de la config Palabre.
+ * @returns Chaîne résumant la paire d'agents, le nombre de réponses et l'agent de synthèse.
+ */
 function formatDefaultsForMessage(defaults) {
     const pair = defaults.agentA && defaults.agentB
         ? `agents: ${defaults.agentA} <-> ${defaults.agentB}`
@@ -213,11 +236,26 @@ function formatDefaultsForMessage(defaults) {
     const summary = defaults.summaryAgent ? `synthèse: ${defaults.summaryAgent}` : "synthèse: agent B";
     return `${pair}, réponses: ${turnsOrDefault(defaults.turns)}, ${summary}`;
 }
+/**
+ * Lève une erreur si `agentName` n'est pas déclaré dans la config.
+ * @param config - Config chargée.
+ * @param agentName - Nom de l'agent à vérifier.
+ * @param fieldName - Nom du champ (utilisé dans le message d'erreur).
+ */
 function assertKnownAgent(config, agentName, fieldName) {
     if (!config.agents[agentName]) {
         throw new Error(`Agent inconnu pour ${fieldName}: ${agentName}. Agents disponibles: ${Object.keys(config.agents).join(", ")}.`);
     }
 }
+/**
+ * Résout le nom d'un agent selon la priorité : flag CLI > preset > défaut config.
+ * Lève une erreur si aucune source ne fournit de valeur.
+ * @param label - Libellé humain utilisé dans le message d'erreur (ex. "agent A").
+ * @param explicitValue - Valeur passée via flag CLI.
+ * @param presetValue - Valeur issue du preset sélectionné.
+ * @param defaultValue - Valeur issue des défauts de la config.
+ * @returns Nom de l'agent résolu.
+ */
 function resolveAgentName(label, explicitValue, presetValue, defaultValue) {
     const resolved = optionalString(explicitValue) ?? presetValue ?? defaultValue;
     if (!resolved) {
@@ -225,6 +263,11 @@ function resolveAgentName(label, explicitValue, presetValue, defaultValue) {
     }
     return resolved;
 }
+/**
+ * Affiche un aperçu du prompt du premier tour sans appeler aucun agent (flag `--show-prompt`).
+ * @param config - Config chargée.
+ * @param options - Options du débat résolues.
+ */
 function printPromptPreview(config, options) {
     const agentConfig = config.agents[options.agentA];
     if (!agentConfig) {
@@ -250,15 +293,89 @@ function printPromptPreview(config, options) {
     console.log("");
     console.log("Note: seuls les prompts du premier tour sont exacts sans exécuter les agents. Les tours suivants incluent le transcript réel.");
 }
+/**
+ * Extrait une chaîne non vide depuis une valeur de flag, ou renvoie `undefined`.
+ * @param value - Valeur brute issue du parseur de flags.
+ */
 function optionalString(value) {
     return typeof value === "string" && value.trim() ? value : undefined;
 }
+/** Liste des kinds de renderer acceptés par `--renderer`. */
+const SUPPORTED_RENDERERS = ["auto", "pretty", "plain", "ndjson"];
+/**
+ * Instancie le renderer en fonction des flags CLI.
+ *
+ * Précédence :
+ *  1. `--renderer <kind>` (canonique).
+ *  2. `--json` (alias pour `--renderer ndjson`).
+ *  3. `--plain` (rétro-compatible, équivalent `--renderer plain`).
+ *  4. par défaut : `auto` (pretty si TTY, plain sinon, hérité de `createConsoleRenderer`).
+ *
+ * Lève si la valeur de `--renderer` n'est pas dans `SUPPORTED_RENDERERS`.
+ */
+function createRendererFromFlags(flags, plainOutputFallback) {
+    const explicit = optionalString(flags.renderer);
+    if (explicit) {
+        if (!SUPPORTED_RENDERERS.includes(explicit)) {
+            throw new Error(`Renderer inconnu: ${explicit}. Valeurs supportées: ${SUPPORTED_RENDERERS.join(", ")}.`);
+        }
+        const kind = explicit;
+        switch (kind) {
+            case "ndjson":
+                return createNdjsonRenderer();
+            case "plain":
+                return createConsoleRenderer(true);
+            case "pretty":
+                return createConsoleRenderer(false);
+            case "auto":
+                return createConsoleRenderer(plainOutputFallback);
+        }
+    }
+    if (flags.json) {
+        return createNdjsonRenderer();
+    }
+    return createConsoleRenderer(plainOutputFallback);
+}
+/**
+ * Exécute la commande `palabre presets`.
+ *
+ * Sortie humaine par défaut (liste alignée), ou JSON avec `--json` pour les
+ * intégrations (extension VS Code, scripts shell). Le schéma JSON est versionné
+ * via le champ `v` au cas où on enrichirait plus tard (ex : description par
+ * preset, tags premium/local).
+ *
+ * @param flags - Flags parsés depuis la ligne de commande.
+ */
+function runPresetsCommand(flags) {
+    const presets = listPresetNames().map((name) => {
+        const pair = resolvePreset(name);
+        return { name, agentA: pair.agentA, agentB: pair.agentB };
+    });
+    if (flags.json) {
+        process.stdout.write(JSON.stringify({ v: 1, presets }) + "\n");
+        return;
+    }
+    console.log("Presets disponibles:");
+    console.log("");
+    for (const preset of presets) {
+        console.log(`  ${preset.name.padEnd(20)} ${preset.agentA} <-> ${preset.agentB}`);
+    }
+    console.log("");
+    console.log(`Total : ${presets.length} preset(s). Utilise --json pour une sortie machine-readable.`);
+}
+/**
+ * Parse `process.argv` en une structure typée `ParsedArgs`.
+ * Gère les flags courts (-h, -v, -s, -t, -a), les flags longs (--topic, --agent-a…),
+ * 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.
+ */
 function parseArgs(args) {
     const flags = {};
     let command = "run";
     let commandExplicit = false;
     const positionals = [];
-    const commands = new Set(["run", "new", "init", "setup", "help", "version", "update", "doctor", "config", "agent", "agents"]);
+    const commands = new Set(["run", "new", "init", "setup", "help", "version", "update", "doctor", "config", "agent", "agents", "preset", "presets"]);
     const presets = new Set(listPresetNames());
     for (let index = 0; index < args.length; index += 1) {
         const value = args[index];
@@ -352,6 +469,12 @@ function parseArgs(args) {
     }
     return { command, commandExplicit, 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.
+ */
 function isLikelyCommandTypo(value, commands) {
     const normalized = value.toLowerCase();
     for (const command of commands) {
@@ -361,6 +484,12 @@ function isLikelyCommandTypo(value, commands) {
     }
     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) {
@@ -376,6 +505,14 @@ function levenshteinDistance(left, right) {
     }
     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) {
     if (positionals.length === 0) {
         return;
@@ -393,6 +530,10 @@ function applyRunPositionals(positionals, flags, presets, commandExplicit) {
     }
     flags.topic ??= positionals.join(" ");
 }
+/**
+ * Normalise un nom de flag long en son alias canonique (ex. `subject` → `topic`).
+ * @param value - Nom brut extrait après `--`.
+ */
 function normalizeFlagName(value) {
     const aliases = {
         s: "topic",
@@ -401,6 +542,10 @@ function normalizeFlagName(value) {
     };
     return aliases[value] ?? value;
 }
+/**
+ * Indique si un flag long nécessite une valeur suivante (lève une erreur si absente).
+ * @param value - Nom canonique du flag (sans `--`).
+ */
 function requiresFlagValue(value) {
     return new Set([
         "agent-a",
@@ -416,12 +561,18 @@ function requiresFlagValue(value) {
         "turns"
     ]).has(value);
 }
+/** Lit la version depuis `package.json` adjacent au bundle compilé. */
 async function getPackageVersion() {
     const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
     const raw = await readFile(packageJsonPath, "utf8");
     const packageJson = JSON.parse(raw);
     return packageJson.version ?? "0.0.0";
 }
+/**
+ * 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.
+ */
 function getStringListFlag(value) {
     if (Array.isArray(value)) {
         return value;
@@ -431,11 +582,22 @@ function getStringListFlag(value) {
     }
     return [];
 }
+/**
+ * Écrit les avertissements de contexte sur `stderr`.
+ * @param warnings - Messages d'avertissement issus du chargement des fichiers de contexte.
+ */
 function printContextWarnings(warnings) {
     for (const warning of warnings) {
         process.stderr.write(`Warning: ${warning}\n`);
     }
 }
+/**
+ * Ajoute dans `config.agents` les agents détectés localement mais absents de la config.
+ * Mute `config` directement ; l'appelant est responsable de persister la config.
+ * @param config - Config Palabre à compléter.
+ * @param discovery - Résultat de la découverte locale des outils.
+ * @returns Noms des agents nouvellement ajoutés.
+ */
 function syncDetectedAgents(config, discovery) {
     const discoveredConfig = createConfigFromDiscovery(discovery);
     const missingAgents = findDetectedMissingAgents(config, discovery);
@@ -444,6 +606,11 @@ function syncDetectedAgents(config, discovery) {
     }
     return missingAgents;
 }
+/**
+ * Renvoie les noms des agents détectés localement qui ne sont pas encore dans `config.agents`.
+ * @param config - Config Palabre existante.
+ * @param discovery - Résultat de la découverte locale des outils.
+ */
 function findDetectedMissingAgents(config, discovery) {
     const detectedAgents = [
         discovery.codex.available ? "codex" : undefined,
@@ -454,6 +621,12 @@ function findDetectedMissingAgents(config, discovery) {
     ].filter((agent) => Boolean(agent));
     return detectedAgents.filter((agentName) => !config.agents[agentName]);
 }
+/**
+ * Affiche la liste des agents déclarés avec leur type, rôle, état de détection et défauts.
+ * @param configPath - Chemin du fichier de config (affiché en en-tête).
+ * @param config - Config Palabre chargée.
+ * @param discovery - Résultat de la découverte locale des outils.
+ */
 function printAgents(configPath, config, discovery) {
     const entries = Object.entries(config.agents).sort(([left], [right]) => left.localeCompare(right));
     console.log(`Config: ${configPath}`);
@@ -472,6 +645,11 @@ function printAgents(configPath, config, discovery) {
     console.log("");
     console.log(`Défauts: ${config.defaults?.agentA ?? "aucun"} <-> ${config.defaults?.agentB ?? "aucun"}, réponses: ${turnsOrDefault(config.defaults?.turns)}, synthèse: ${config.defaults?.summaryAgent ?? "agent B"}`);
 }
+/**
+ * Renvoie un libellé indiquant si l'agent est agent A, agent B ou agent de synthèse par défaut.
+ * @param name - Nom de l'agent.
+ * @param config - Config Palabre contenant les défauts.
+ */
 function formatAgentDefaults(name, config) {
     const labels = [];
     if (config.defaults?.agentA === name)
@@ -482,12 +660,23 @@ function formatAgentDefaults(name, config) {
         labels.push("synthèse par défaut");
     return labels.join(", ");
 }
+/**
+ * Renvoie une ligne de détails pour un agent : commande CLI ou modèle Ollama.
+ * @param agentConfig - Configuration de l'agent.
+ */
 function formatAgentDetails(agentConfig) {
     if (agentConfig.type === "ollama") {
         return `modèle: ${agentConfig.model}`;
     }
     return `commande: ${agentConfig.command}${agentConfig.model ? ` | modèle: ${agentConfig.model}` : ""}`;
 }
+/**
+ * Renvoie le statut de détection d'un agent sous forme de chaîne lisible.
+ * Pour Ollama, vérifie la disponibilité du serveur et la présence du modèle.
+ * @param name - Nom de l'agent dans la config.
+ * @param agentConfig - Configuration de l'agent.
+ * @param discovery - Résultat de la découverte locale des outils.
+ */
 function formatAgentDetection(name, agentConfig, discovery) {
     if (agentConfig.type === "ollama") {
         if (!discovery.ollama.available) {
@@ -500,6 +689,13 @@ function formatAgentDetection(name, agentConfig, discovery) {
     const detection = cliDetectionForAgent(name, agentConfig, discovery);
     return detection.available ? `détecté (${detection.command})` : "non détecté";
 }
+/**
+ * Résout l'entrée de détection correspondant à un agent CLI dans le résultat de découverte.
+ * Renvoie un objet `{ available: true }` pour les agents CLI non reconnus (considérés disponibles).
+ * @param name - Nom de l'agent dans la config.
+ * @param agentConfig - Configuration de l'agent.
+ * @param discovery - Résultat de la découverte locale des outils.
+ */
 function cliDetectionForAgent(name, agentConfig, discovery) {
     const command = normalizeCommandName(agentConfig.type === "cli" ? agentConfig.command : name);
     if (command === "codex")
@@ -512,9 +708,18 @@ function cliDetectionForAgent(name, agentConfig, discovery) {
         return discovery.opencode;
     return { available: true, command: agentConfig.type === "cli" ? agentConfig.command : name };
 }
+/**
+ * Extrait le nom de base d'une commande en supprimant le chemin et l'extension Windows éventuelle.
+ * @param command - Chemin ou nom de commande brut (ex. `C:\bin\claude.cmd`).
+ */
 function normalizeCommandName(command) {
     return path.basename(command).replace(/\.(cmd|exe|ps1|bat)$/i, "").toLowerCase();
 }
+/**
+ * Affiche le récapitulatif de détection locale après `palabre init`.
+ * @param discovery - Résultat de la découverte locale des outils.
+ * @param config - Config générée à partir de la découverte.
+ */
 function printInitDiscovery(discovery, config) {
     console.log("");
     console.log("Détection locale:");
@@ -526,11 +731,19 @@ function printInitDiscovery(discovery, config) {
     console.log("");
     console.log(`Défauts: ${config.defaults?.agentA ?? "codex"} <-> ${config.defaults?.agentB ?? "ollama-local"}`);
 }
+/**
+ * Formate le statut de détection d'un outil CLI (disponible ou non).
+ * @param detection - Résultat de détection d'un outil CLI.
+ */
 function formatCommandDetection(detection) {
     return detection.available
         ? `détecté (${detection.command})`
         : "non détecté";
 }
+/**
+ * Formate le statut de détection d'Ollama : commande absente, serveur injoignable ou modèles disponibles.
+ * @param detection - Résultat de détection d'Ollama.
+ */
 function formatOllamaDetection(detection) {
     if (!detection.available) {
         return detection.commandAvailable
@@ -540,54 +753,94 @@ function formatOllamaDetection(detection) {
     const modelCount = detection.models.length;
     return `détectée (${modelCount} modèle${modelCount > 1 ? "s" : ""})`;
 }
+/** Affiche le texte d'aide complet sur `stdout`. */
 function printHelp() {
     console.log(`
 PALABRE
+_____________________________________________
 
 Usage rapide:
+
+  palabre init 
+      Crée une config globale et détecte les agents AI disponibles sur la machine.
+
+  palabre agents
+      Affiche les agents déclarés dans la config.
+
+  palabre config
+      Assistant pour définir ou supprimer les paramètres par défaut.
+
   palabre new
       Assistant interactif pour choisir les agents, le sujet et les options.
-  palabre run -s "Sujet"
-      Lance avec les agents par défaut de la config.
+
   palabre claude-gemini "Sujet" -t 4
       Lance avec un preset et un sujet positionnel.
 
+  palabre "Sujet"
+      Lance le débat avec paramètres par défaut de la config.
+
+_____________________________________________
+
+
 Commandes:
+
   palabre init [--local]
-      Crée une config et détecte Codex, Claude, Gemini, OpenCode et Ollama.
+      Crée une config locale et détecte Codex, Claude, Gemini, OpenCode et Ollama.
+
   palabre agents [--config <path>]
       Liste les agents déclarés dans la config et leur détection locale.
+
+  palabre presets [--json]
+      Liste les presets de paires d'agents. \`--json\` émet la liste structurée
+      pour les intégrations (extension VS Code, scripts).
+
   palabre config
       Assistant pour définir ou supprimer les paramètres par défaut.
+
   palabre config --set-defaults <agentA> <agentB> [-t <n>] [--summary-agent <name>]
       Définit les agents par défaut, et optionnellement les réponses et la synthèse.
+
   palabre config -t <n>
       Définit seulement le nombre de réponses par défaut.
+
   palabre config --summary-agent <name|none>
       Définit ou retire seulement l'agent de synthèse par défaut.
+
   palabre config --clear-defaults
       Supprime les paramètres par défaut.
+
   palabre doctor [--config <path>]
       Vérifie la config et les outils locaux.
+
   palabre update [--apply]
       Affiche ou exécute les étapes de mise à jour d'un checkout git.
+
   palabre help
       Affiche cette aide. Identique à -h ou --help.
+      
   palabre version
       Affiche la version. Identique à -v ou --version.
 
+_____________________________________________
+
+
 Notation:
+
   [option] signifie facultatif. Ne tape pas les crochets.
   <valeur> signifie qu'il faut remplacer ce texte par ta valeur.
 
 Options générales:
+
   -h, --help              Affiche cette aide
   -v, --version           Affiche la version
-  -a                      Liste les agents. Identique à palabre agents
+  -a, --agents            Liste les agents. Identique à palabre agents
   --config <path>         Chemin vers un fichier de config explicite
   --plain                 Utilise le rendu console simple sans habillage TUI
+  --json                  Émet un événement NDJSON par ligne sur stdout (alias de --renderer ndjson)
+  --renderer <kind>       Force le renderer : auto | pretty | plain | ndjson
 
 Sujet et lancement:
+
   -s, --subject <text>    Sujet du débat, option recommandée
   --topic <text>          Alias compatible de --subject
   --agent-a <name>        Premier agent
@@ -597,21 +850,25 @@ Sujet et lancement:
   --no-early-stop         Désactive l'arrêt anticipé si les agents sont clairement d'accord
 
 Modèles:
+
   --model-a <model>       Modèle brut transmis à l'agent A
   --model-b <model>       Modèle brut transmis à l'agent B
   --pull-models           Autorise Ollama à télécharger un modèle manquant
 
 Synthèse:
+
   --summary-agent <name>  Agent utilisé pour produire la synthèse finale
   --summary-model <model> Modèle brut transmis à l'agent de synthèse
   --no-summary            Désactive la synthèse finale
 
 Contexte:
+
   --files <paths...>      Fichiers texte à injecter explicitement dans le contexte
   --context <paths...>    Scanne fichiers/dossiers texte en respectant les limites de contexte
   --show-prompt           Affiche le prompt du premier tour sans appeler d'agent
 
 Configuration:
+
   --local                 Avec init/setup, crée ./palabre.config.json
   --set-defaults <a b>    Avec config, définit les agents par défaut
   --summary-agent <name>  Avec config, définit l'agent de synthèse par défaut
@@ -620,10 +877,18 @@ Configuration:
   --sync-agents           Avec config, ajoute les agents détectés manquants
 
 Mise à jour:
+
   --apply                 Avec update, exécute les étapes de mise à jour
 
+_____________________________________________
+
+
 Presets disponibles:
+
   ${listPresetNames().join(", ")}
+
+_____________________________________________
+
 `);
 }
 main().catch((error) => {

package/dist/renderers/console.js

@@ -4,6 +4,10 @@ const supportsInteractiveOutput = Boolean(process.stdout.isTTY);
 export function createConsoleRenderer(plain) {
     return plain ? new PlainConsoleRenderer() : new PrettyConsoleRenderer(supportsColor, supportsInteractiveOutput);
 }
+/**
+ * Renderer interactif avec spinner, couleurs ANSI et encadrés de section.
+ * Utilisé quand `stdout` est un TTY et que `--plain` n'est pas passé.
+ */
 class PrettyConsoleRenderer {
     color;
     interactive;
@@ -11,10 +15,15 @@ class PrettyConsoleRenderer {
     spinnerFrame = 0;
     renderingSummary = false;
     frames = ["-", "\\", "|", "/"];
+    /**
+     * @param color - Active les codes couleur ANSI.
+     * @param interactive - Active le spinner en place (mode TTY interactif).
+     */
     constructor(color, interactive) {
         this.color = color;
         this.interactive = interactive;
     }
+    /** Affiche l'en-tête du débat (sujet, agents, options). */
     start(options, agents = []) {
         const title = "PALABRE";
         process.stdout.write([
@@ -29,21 +38,25 @@ class PrettyConsoleRenderer {
             ""
         ].join("\n"));
     }
+    /** Écrit un avertissement sur `stderr` en jaune. */
     warning(message) {
         process.stderr.write(`${this.c("yellow", "Warning:")} ${message}\n`);
     }
+    /** Écrit une notice informative sur `stdout` en vert. */
     notice(message) {
         process.stdout.write(`${this.c("green", "Info:")} ${message}\n`);
     }
+    /** Affiche l'en-tête d'un nouveau tour (agent, rôle, progression). */
     turnStart(turn, totalTurns, agent, role) {
         this.renderingSummary = false;
         process.stdout.write([
             "",
-            this.c("blue", `◆ ${agent}`) + this.dim(` · ${role} · tour ${turn}/${totalTurns}`),
+            this.c("orange", `◆ ${agent}`) + this.dim(` · ${role} · tour ${turn}/${totalTurns}`),
             this.dim("─".repeat(60)),
             ""
         ].join("\n"));
     }
+    /** Démarre le spinner de réflexion (ou affiche une ligne fixe si non interactif). */
     thinkingStart(agent, role) {
         this.thinkingEnd();
         const text = `${agent} (${role}) reflechit`;
@@ -59,6 +72,7 @@ class PrettyConsoleRenderer {
         render();
         this.spinner = setInterval(render, 120);
     }
+    /** Arrête le spinner et efface la ligne de réflexion en mode interactif. */
     thinkingEnd() {
         if (this.spinner) {
             clearInterval(this.spinner);
@@ -68,22 +82,29 @@ class PrettyConsoleRenderer {
             process.stdout.write("\r\u001b[2K");
         }
     }
+    /** Écrit le contenu d'un message agent, avec formatage de synthèse si applicable. */
     message(content) {
         const trimmed = content.trim();
         process.stdout.write(`${this.renderingSummary ? this.formatSummaryMessage(trimmed) : trimmed}\n`);
     }
+    /** Affiche l'en-tête de section synthèse et active le mode formatage de résumé. */
     summaryStart(agent, role) {
         this.renderingSummary = true;
         process.stdout.write([
             "",
-            this.c("magenta", `◆ Synthese`) + this.dim(` · ${agent} · ${role}`),
+            this.c("pink", `◆ Synthese`) + this.dim(` · ${agent} · ${role}`),
             this.dim("─".repeat(60)),
             ""
         ].join("\n"));
     }
+    /** Affiche le chemin du fichier de sortie en vert à la fin du débat. */
     done(outputPath) {
-        process.stdout.write(`\n${this.c("green", "Debat exporte:")} ${outputPath}\n`);
+        process.stdout.write(`\n\n${this.c("green", "Debat exporte:")} ${outputPath}\n\n`);
     }
+    /**
+     * Convertit les titres Markdown `### Heading` en titres colorés avec séparateur.
+     * @param content - Contenu texte de la synthèse.
+     */
     formatSummaryMessage(content) {
         return content
             .split(/\r?\n/)
@@ -93,66 +114,99 @@ class PrettyConsoleRenderer {
                 return line;
             return [
                 "",
-                this.c("magenta", heading[1] ?? line),
+                this.c("pink", heading[1] ?? line),
                 this.dim("─".repeat(40))
             ].join("\n");
         })
             .join("\n")
             .trimStart();
     }
+    /** Entoure `value` avec le code couleur ANSI si les couleurs sont activées. */
     c(color, value) {
         if (!this.color)
             return value;
         return `${codes[color]}${value}${codes.reset}`;
     }
+    /** Applique le style dim (atténué) si les couleurs sont activées. */
     dim(value) {
         if (!this.color)
             return value;
         return `${codes.dim}${value}${codes.reset}`;
     }
 }
+/**
+ * Renderer minimaliste sans couleurs ni spinner.
+ * Utilisé avec `--plain` ou quand `stdout` n'est pas un TTY.
+ */
 class PlainConsoleRenderer {
+    /** Affiche les informations de démarrage du débat en texte brut. */
     start(options, agents = []) {
         process.stdout.write(`Sujet: ${options.topic}` + "\n");
         process.stdout.write(`Agents: ${formatAgentPair(options, agents)}` + "\n");
         process.stdout.write(`Réponses: ${options.turns} | Synthèse: ${formatSummary(options)} | Contexte: ${formatContext(options)}` + "\n");
     }
+    /** Écrit un avertissement sur `stderr`. */
     warning(message) {
         process.stderr.write(`Warning: ${message}\n`);
     }
+    /** Écrit une notice informative sur `stdout`. */
     notice(message) {
         process.stdout.write(`Info: ${message}\n`);
     }
+    /** Affiche la progression du tour en texte brut. */
     turnStart(turn, totalTurns, agent, role) {
         process.stdout.write(`\n[${turn}/${totalTurns}] ${agent} (${role})...\n`);
     }
+    /** No-op : pas de spinner en mode plain. */
     thinkingStart(_agent, _role) { }
+    /** No-op : pas de spinner à arrêter en mode plain. */
     thinkingEnd() { }
+    /** Écrit le contenu du message agent trimé. */
     message(content) {
         process.stdout.write(`${content.trim()}\n`);
     }
+    /** Affiche l'en-tête de la section synthèse en texte brut. */
     summaryStart(agent, role) {
         process.stdout.write(`\n[Synthese] ${agent} (${role})...\n`);
     }
+    /** Affiche le chemin du fichier de sortie à la fin du débat. */
     done(outputPath) {
         process.stdout.write(`\nDebat exporte: ${outputPath}\n`);
     }
 }
+/**
+ * Formate la paire d'agents pour l'en-tête : utilise les infos enrichies si disponibles,
+ * sinon les noms bruts des options.
+ * @param options - Options du débat.
+ * @param agents - Infos de démarrage des agents (type, rôle, nom).
+ */
 function formatAgentPair(options, agents) {
     if (agents.length >= 2) {
         return `${formatAgentLabel(agents[0])} <-> ${formatAgentLabel(agents[1])}`;
     }
     return `${options.agentA} <-> ${options.agentB}`;
 }
+/**
+ * Formate un agent en `nom (rôle, type)` ou `"?"` si absent.
+ * @param agent - Info de démarrage de l'agent, ou `undefined`.
+ */
 function formatAgentLabel(agent) {
     if (!agent) {
         return "?";
     }
     return `${agent.name} (${agent.role}, ${agent.type})`;
 }
+/**
+ * Renvoie le nom de l'agent de synthèse ou `"désactivée"` si la synthèse est désactivée.
+ * @param options - Options du débat.
+ */
 function formatSummary(options) {
     return options.summaryEnabled ? options.summaryAgent ?? options.agentB : "désactivée";
 }
+/**
+ * Renvoie un résumé du contexte injecté (nombre de fichiers ou mention d'absence).
+ * @param options - Options du débat.
+ */
 function formatContext(options) {
     const count = options.files.length;
     if (count === 0) {
@@ -160,6 +214,7 @@ function formatContext(options) {
     }
     return `${count} fichier${count > 1 ? "s" : ""} injecté${count > 1 ? "s" : ""}`;
 }
+/** Codes d'échappement ANSI utilisés par `PrettyConsoleRenderer`. */
 const codes = {
     reset: "\u001b[0m",
     dim: "\u001b[2m",
@@ -167,5 +222,7 @@ const codes = {
     cyan: "\u001b[36m",
     green: "\u001b[32m",
     magenta: "\u001b[35m",
-    yellow: "\u001b[33m"
+    yellow: "\u001b[33m",
+    orange: "\u001b[38;5;208m",
+    pink: "\u001b[38;5;205m"
 };

package/dist/renderers/ndjson.js

@@ -0,0 +1,116 @@
+/**
+ * Renderer NDJSON : émet une ligne JSON par événement DebateRenderer.
+ *
+ * Cible : intégrations qui pilotent Palabre en out-of-process (extension
+ * VS Code, plugin Obsidian, scripts shell). Le rendu humain reste
+ * `PrettyConsoleRenderer` ou `PlainConsoleRenderer`.
+ *
+ * Contrat :
+ * - une ligne = un événement JSON valide, terminé par `\n` ;
+ * - tous les événements portent un champ `v` (entier) pour le versioning ;
+ * - toute évolution cassante du schéma doit incrémenter `v` et documenter
+ *   la migration dans AGENTS.md (section "Renderer NDJSON").
+ *
+ * Sortie : stdout uniquement. stderr reste libre pour les messages bas
+ * niveau (Node, shell) que les consommateurs peuvent agréger comme ils
+ * veulent.
+ */
+export class NdjsonRenderer {
+    schemaVersion = 1;
+    currentSection = "debate";
+    currentTurn = 0;
+    currentAgent = null;
+    currentRole = null;
+    /** Émet `start` avec le sujet, les agents, les options principales et le contexte de session. */
+    start(options, agents = []) {
+        this.emit({
+            type: "start",
+            topic: options.topic,
+            turns: options.turns,
+            agents: agents.map((a) => ({ name: a.name, role: a.role, type: a.type })),
+            summaryEnabled: options.summaryEnabled,
+            summaryAgent: options.summaryEnabled
+                ? options.summaryAgent ?? options.agentB
+                : null,
+            earlyStop: options.earlyStopOnAgreement,
+            filesCount: options.files.length,
+            session: {
+                startedAt: options.session.startedAt,
+                localDate: options.session.localDate,
+                timeZone: options.session.timeZone,
+                cwd: options.session.cwd,
+            },
+        });
+    }
+    /** Émet un événement informatif. */
+    notice(message) {
+        this.emit({ type: "notice", message });
+    }
+    /** Émet un avertissement. Reste sur stdout pour conserver l'ordre des événements. */
+    warning(message) {
+        this.emit({ type: "warning", message });
+    }
+    /** Émet `turn-start` et bascule la section courante en débat. */
+    turnStart(turn, totalTurns, agent, role) {
+        this.currentSection = "debate";
+        this.currentTurn = turn;
+        this.currentAgent = agent;
+        this.currentRole = role;
+        this.emit({ type: "turn-start", turn, totalTurns, agent, role });
+    }
+    /**
+     * Émet `thinking-start`. Les consommateurs UI peuvent l'utiliser pour un
+     * indicateur "agent en cours" ; les consommateurs purement data peuvent
+     * l'ignorer sans perte d'information sémantique.
+     */
+    thinkingStart(agent, role) {
+        this.emit({ type: "thinking-start", agent, role });
+    }
+    /** Émet `thinking-end`. */
+    thinkingEnd() {
+        this.emit({ type: "thinking-end" });
+    }
+    /**
+     * Émet `message` (section débat) ou `summary-message` (section synthèse)
+     * selon l'état courant. La discrimination par type permet aux
+     * consommateurs de router sans maintenir d'état eux-mêmes.
+     */
+    message(content) {
+        if (this.currentSection === "summary") {
+            this.emit({
+                type: "summary-message",
+                agent: this.currentAgent,
+                role: this.currentRole,
+                content,
+            });
+        }
+        else {
+            this.emit({
+                type: "message",
+                turn: this.currentTurn,
+                agent: this.currentAgent,
+                role: this.currentRole,
+                content,
+            });
+        }
+    }
+    /** Émet `summary-start` et bascule la section courante en synthèse. */
+    summaryStart(agent, role) {
+        this.currentSection = "summary";
+        this.currentAgent = agent;
+        this.currentRole = role;
+        this.emit({ type: "summary-start", agent, role });
+    }
+    /** Émet `done` avec le chemin du `.debate.md` écrit. */
+    done(outputPath) {
+        this.emit({ type: "done", outputPath });
+    }
+    /** Sérialise un événement et l'écrit sur stdout, terminé par `\n`. */
+    emit(event) {
+        process.stdout.write(JSON.stringify({ v: this.schemaVersion, ...event }) + "\n");
+    }
+}
+/** Factory pratique pour conserver la symétrie avec `createConsoleRenderer`. */
+export function createNdjsonRenderer() {
+    return new NdjsonRenderer();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "palabre",
-  "version": "0.1.7",
+  "version": "0.3.0",
   "description": "Orchestrateur de debat entre agents IA locaux, CLIs et Ollama.",
   "license": "MIT",
   "type": "module",