palabre 0.9.1 → 0.10.0

package/dist/runOptions.js

@@ -1,10 +1,21 @@
+/** @file Résolution centralisée des flags et defaults en options runtime immuables. */
 import { getStringListFlag } from "./args.js";
 import { DEFAULT_TURNS, MAX_ASK_AGENTS, parseTurnsFlag } from "./limits.js";
 import { normalizeOllamaBaseUrl } from "./ollamaUrl.js";
 import { createSessionContext } from "./session.js";
 import { askAgentSeedsForMode } from "./tuiState.js";
 import { optionalString } from "./commands/shared.js";
-/** Resolves flags and defaults into complete orchestrator options. */
+/**
+ * Construit le contrat complet transmis à l'orchestrateur.
+ *
+ * La priorité est : flags explicites, preset, defaults de configuration, puis
+ * fallbacks propres au mode. La fonction ne modifie ni les flags ni la config.
+ *
+ * @param input - Configuration, flags, contexte et signal de la session.
+ * @param messages - Dictionnaire localisé utilisé pour les erreurs de validation.
+ * @returns Des options complètes, avec agent de synthèse déjà résolu.
+ * @throws {Error} Si le mode, les agents, le nombre de tours ou l'URL Ollama sont invalides.
+ */
 export function resolveRunOptions(input, messages) {
     const { flags, config, language, topic, files, preset, signal } = input;
     const mode = parseModeFlag(optionalString(flags.mode) ?? config.defaults?.mode, messages);
@@ -36,12 +47,14 @@ export function resolveRunOptions(input, messages) {
         signal
     };
 }
+/** Résout un agent selon la priorité flag > preset > default configuré. */
 function resolveAgentName(label, explicitValue, presetValue, defaultValue, messages) {
     const resolved = optionalString(explicitValue) ?? presetValue ?? defaultValue;
     if (!resolved)
         throw new Error(messages.common.noAgentDefined(label));
     return resolved;
 }
+/** Résout une seule fois l'agent de synthèse avant l'entrée dans l'orchestrateur. */
 function resolveSummaryAgent(explicitValue, defaults, mode, askAgents, agentB) {
     const explicit = optionalString(explicitValue);
     if (explicit)
@@ -50,13 +63,31 @@ function resolveSummaryAgent(explicitValue, defaults, mode, askAgents, agentB) {
         return defaults?.askSummaryAgent ?? defaults?.summaryAgent ?? askAgents?.at(-1) ?? agentB;
     return defaults?.summaryAgent ?? agentB;
 }
-function parseModeFlag(value, messages) {
+/**
+ * Valide le mode demandé (`--mode`, `config --mode`) et applique `debate` quand
+ * aucune valeur n'est fournie. Partagé entre `run` et la commande `config`.
+ * @throws {Error} Si `value` n'est ni `debate` ni `ask`.
+ */
+export function parseModeFlag(value, messages) {
     if (!value)
         return "debate";
     if (value === "debate" || value === "ask")
         return value;
     throw new Error(messages.common.unknownMode(value, "debate, ask"));
 }
+/**
+ * Valide l'interface demandée (`--interface`, `config --interface`) et applique `tui`
+ * quand aucune valeur n'est fournie.
+ * @throws {Error} Si `value` n'est ni `tui` ni `terminal`.
+ */
+export function parseInterfaceFlag(value, messages) {
+    if (!value)
+        return "tui";
+    if (value === "tui" || value === "terminal")
+        return value;
+    throw new Error(messages.common.unknownMode(value, "tui, terminal"));
+}
+/** Déduplique les agents Ask et applique la limite produit sans modifier les listes sources. */
 function resolveAskAgents(explicitAgents, defaultAgents, fallbackAgents, messages) {
     const selected = explicitAgents.length > 0 ? explicitAgents : defaultAgents && defaultAgents.length > 0 ? defaultAgents : fallbackAgents;
     const unique = selected.filter((agent, index) => agent.trim() && selected.indexOf(agent) === index);

package/dist/session.js

@@ -1,3 +1,4 @@
+/** @file Construit le contexte de session factuel (date, fuseau, dossier) injecté dans chaque prompt agent. */
 import path from "node:path";
 /**
  * Construit le contexte de session partagé par tous les agents pour la durée du débat.

package/dist/tuiController.js

@@ -1,10 +1,20 @@
-import { setOllamaBaseUrl, setOllamaModel, syncDetectedAgentsDetailed, syncOllamaModel, writeExampleConfig } from "./config.js";
+/** @file Contrôleur des interactions TUI qui lisent et persistent la configuration Palabre. */
+import { setOllamaBaseUrl, setOllamaModel, syncDetectedAgentsDetailed, syncOllamaModel, writeConfig } from "./config.js";
 import { discoverLocalToolsForConfig } from "./discovery.js";
 import { AdapterError, formatAdapterError } from "./errors.js";
 import { createTranslator, DEFAULT_LANGUAGE, parseLanguage } from "./i18n.js";
 import { MAX_ASK_AGENTS, validateTurns } from "./limits.js";
 import { DEFAULT_OLLAMA_BASE_URL, normalizeOllamaBaseUrl, OllamaUrlError, resolveOllamaBaseUrl } from "./ollamaUrl.js";
 import { promptTuiAgentsWizard, promptTuiConfigCommand, promptTuiRolesWizard, renderTuiConfig } from "./renderers/tui.js";
+/**
+ * Exécute la boucle `/config` jusqu'au retour à l'accueil ou à la fermeture.
+ *
+ * @param configPath - Fichier de configuration à persister après chaque changement.
+ * @param config - Configuration chargée et mutée en mémoire.
+ * @param messages - Dictionnaire actif, remplacé si la langue change.
+ * @param initialMode - Mode affiché à l'ouverture de la vue.
+ * @returns Le mode final et les indicateurs de sortie ou de defaults modifiés.
+ */
 export async function runTuiConfigLoop(configPath, config, messages, initialMode) {
     let mode = initialMode;
     let notice;
@@ -27,27 +37,27 @@ export async function runTuiConfigLoop(configPath, config, messages, initialMode
         if (input.kind === "mode") {
             mode = mode === "ask" ? "debate" : "ask";
             config.defaults = { ...(config.defaults ?? {}), mode };
-            await writeExampleConfig(configPath, config);
+            await writeConfig(configPath, config);
             changedRunDefaults = true;
             notice = mode === "ask" ? currentMessages.tui.askDefaultMode : currentMessages.tui.debateDefaultMode;
             continue;
         }
         if (input.kind === "default-mode") {
             config.defaults = { ...(config.defaults ?? {}), mode };
-            await writeExampleConfig(configPath, config);
+            await writeConfig(configPath, config);
             changedRunDefaults = true;
             notice = mode === "ask" ? currentMessages.tui.askDefaultMode : currentMessages.tui.debateDefaultMode;
             continue;
         }
         if (input.kind === "interface") {
             config.defaults = { ...(config.defaults ?? {}), interface: input.interfaceName };
-            await writeExampleConfig(configPath, config);
+            await writeConfig(configPath, config);
             notice = currentMessages.tui.interfaceDefault(input.interfaceName);
             continue;
         }
         if (input.kind === "language") {
             config.language = parseLanguage(input.language, "--language");
-            await writeExampleConfig(configPath, config);
+            await writeConfig(configPath, config);
             currentMessages = createTranslator(config.language ?? DEFAULT_LANGUAGE);
             notice = currentMessages.tui.languageUpdated(input.language);
             continue;
@@ -67,14 +77,14 @@ export async function runTuiConfigLoop(configPath, config, messages, initialMode
                 if (mode === "ask") {
                     const agents = normalizeTuiAskAgents(config, agentsInput.agents, currentMessages);
                     config.defaults = { ...(config.defaults ?? {}), askAgents: agents };
-                    await writeExampleConfig(configPath, config);
+                    await writeConfig(configPath, config);
                     changedRunDefaults = true;
                     notice = currentMessages.tui.askAgentsUpdated(agents.join(", "));
                 }
                 else {
                     const [agentA, agentB] = normalizeTuiDebateAgents(config, agentsInput.agents, currentMessages);
                     config.defaults = { ...(config.defaults ?? {}), agentA, agentB };
-                    await writeExampleConfig(configPath, config);
+                    await writeConfig(configPath, config);
                     changedRunDefaults = true;
                     notice = currentMessages.tui.debateAgentsUpdated(`${agentA} <-> ${agentB}`);
                 }
@@ -97,7 +107,7 @@ export async function runTuiConfigLoop(configPath, config, messages, initialMode
                     continue;
                 }
                 notice = applyTuiRoles(config, mode, rolesInput.roles, currentMessages);
-                await writeExampleConfig(configPath, config);
+                await writeConfig(configPath, config);
             }
             catch (error) {
                 notice = error instanceof Error ? error.message : String(error);
@@ -112,7 +122,7 @@ export async function runTuiConfigLoop(configPath, config, messages, initialMode
             try {
                 validateTurns(input.turns, "--turns", currentMessages);
                 config.defaults = { ...(config.defaults ?? {}), turns: input.turns };
-                await writeExampleConfig(configPath, config);
+                await writeConfig(configPath, config);
                 changedRunDefaults = true;
                 notice = currentMessages.tui.turnsUpdated(input.turns);
             }
@@ -146,7 +156,7 @@ export async function runTuiConfigLoop(configPath, config, messages, initialMode
                     notice = currentMessages.tui.debateSummaryAgent(input.agent);
                 }
                 config.defaults = nextDefaults;
-                await writeExampleConfig(configPath, config);
+                await writeConfig(configPath, config);
                 changedRunDefaults = true;
             }
             catch (error) {
@@ -195,6 +205,7 @@ export async function runTuiConfigLoop(configPath, config, messages, initialMode
         }
     }
 }
+/** Normalise et persiste l'URL de tous les agents Ollama configurés. */
 async function setTuiOllamaUrl(configPath, config, value, messages) {
     if (!Object.values(config.agents).some((agent) => agent.type === "ollama")) {
         throw new Error(messages.config.ollamaModelNoAgent);
@@ -204,12 +215,13 @@ async function setTuiOllamaUrl(configPath, config, value, messages) {
         : normalizeOllamaBaseUrl(value);
     const effective = resolveOllamaBaseUrl({ configUrl: normalized });
     setOllamaBaseUrl(config, normalized);
-    await writeExampleConfig(configPath, config);
+    await writeConfig(configPath, config);
     return messages.tui.ollamaUrlUpdated(normalized, effective);
 }
 function isDefaultOllamaUrl(value) {
     return ["default", "defaut", "défaut", "local", "localhost"].includes(value.trim().toLowerCase());
 }
+/** Interroge le serveur Ollama effectif et formate son état pour une notice TUI. */
 async function formatTuiOllamaInfo(config, messages) {
     const discovery = await discoverLocalToolsForConfig(config);
     const agent = config.agents["ollama-local"];
@@ -225,6 +237,7 @@ async function formatTuiOllamaInfo(config, messages) {
     const api = `${discovery.ollama.baseUrl}`;
     return messages.tui.ollamaInfo(agent.model, installed, api);
 }
+/** Valide un modèle Ollama installé avant de le persister. */
 async function setTuiOllamaModel(configPath, config, model, messages) {
     const trimmed = model.trim();
     if (!trimmed) {
@@ -239,11 +252,12 @@ async function setTuiOllamaModel(configPath, config, model, messages) {
         throw new Error(messages.config.ollamaModelUnavailable(trimmed));
     }
     const result = setOllamaModel(config, trimmed);
-    await writeExampleConfig(configPath, config);
+    await writeConfig(configPath, config);
     return result
         ? messages.config.ollamaModelUpdated(configPath, result.previousModel, result.nextModel)
         : messages.config.ollamaModelNoChange(configPath, agent.model);
 }
+/** Remplace le modèle Ollama absent par le fallback installé choisi par la config. */
 async function syncTuiOllamaModel(configPath, config, messages) {
     const discovery = await discoverLocalToolsForConfig(config);
     const agent = config.agents["ollama-local"];
@@ -257,14 +271,21 @@ async function syncTuiOllamaModel(configPath, config, messages) {
     if (!result) {
         return messages.config.ollamaModelNoChange(configPath, agent.model);
     }
-    await writeExampleConfig(configPath, config);
+    await writeConfig(configPath, config);
     return messages.config.ollamaModelUpdated(configPath, result.previousModel, result.nextModel);
 }
+/**
+ * Synchronise les agents connus détectés avant l'affichage de l'accueil TUI.
+ *
+ * @param configPath - Fichier à réécrire uniquement si la synchronisation change la config.
+ * @param config - Configuration chargée et mise à jour en mémoire.
+ * @returns Les noms des agents nouvellement ajoutés, utilisés pour la notice d'accueil.
+ */
 export async function syncInteractiveDetectedAgents(configPath, config) {
     const discovery = await discoverLocalToolsForConfig(config);
     const result = syncDetectedAgentsDetailed(config, discovery);
     if (result.changed) {
-        await writeExampleConfig(configPath, config);
+        await writeConfig(configPath, config);
     }
     return {
         addedAgents: result.addedAgents
@@ -290,6 +311,16 @@ function normalizeTuiAskAgents(config, agents, messages) {
     unique.forEach((agent) => assertKnownAgent(config, agent, "defaults.askAgents", messages));
     return unique;
 }
+/**
+ * Exécute le wizard d'agents ou applique directement les noms fournis.
+ *
+ * @param configPath - Fichier de configuration à persister.
+ * @param config - Configuration chargée et modifiée en mémoire.
+ * @param messages - Dictionnaire localisé de la vue.
+ * @param mode - Mode dont les agents actifs doivent être modifiés.
+ * @param inlineAgents - Noms fournis directement après la commande `/agents`.
+ * @returns Une notice utilisateur et les indicateurs de sortie/changement.
+ */
 export async function runTuiAgentsWizard(configPath, config, messages, mode, inlineAgents = []) {
     try {
         const agentsInput = inlineAgents.length > 0
@@ -302,13 +333,23 @@ export async function runTuiAgentsWizard(configPath, config, messages, mode, inl
             return { quit: false, changedRunDefaults: false };
         }
         const notice = applyTuiAgents(config, mode, agentsInput.agents, messages);
-        await writeExampleConfig(configPath, config);
+        await writeConfig(configPath, config);
         return { notice, quit: false, changedRunDefaults: true };
     }
     catch (error) {
         return { notice: messages.tui.agentsError(error instanceof Error ? error.message : String(error)), quit: false, changedRunDefaults: false };
     }
 }
+/**
+ * Exécute le wizard de rôles ou applique directement les rôles fournis.
+ *
+ * @param configPath - Fichier de configuration à persister.
+ * @param config - Configuration chargée et modifiée en mémoire.
+ * @param messages - Dictionnaire localisé de la vue.
+ * @param mode - Mode déterminant la liste d'agents concernés.
+ * @param inlineRoles - Rôles fournis directement après la commande `/roles`.
+ * @returns Une notice utilisateur et l'indicateur de fermeture de la TUI.
+ */
 export async function runTuiRolesWizard(configPath, config, messages, mode, inlineRoles = []) {
     try {
         const rolesInput = inlineRoles.length > 0
@@ -321,13 +362,14 @@ export async function runTuiRolesWizard(configPath, config, messages, mode, inli
             return { quit: false };
         }
         const notice = applyTuiRoles(config, mode, rolesInput.roles, messages);
-        await writeExampleConfig(configPath, config);
+        await writeConfig(configPath, config);
         return { notice, quit: false };
     }
     catch (error) {
         return { notice: messages.tui.rolesError(error instanceof Error ? error.message : String(error)), quit: false };
     }
 }
+/** Valide puis applique les agents actifs du mode courant. */
 function applyTuiAgents(config, mode, agentNames, messages) {
     if (mode === "ask") {
         const agents = normalizeTuiAskAgents(config, agentNames, messages);
@@ -338,6 +380,7 @@ function applyTuiAgents(config, mode, agentNames, messages) {
     config.defaults = { ...(config.defaults ?? {}), agentA, agentB };
     return messages.tui.debateAgentsUpdated(`${agentA} <-> ${agentB}`);
 }
+/** Associe les rôles saisis aux agents actifs du mode courant. */
 function applyTuiRoles(config, mode, roleNames, messages) {
     const agents = activeAgentsForMode(config, mode);
     if (agents.length === 0) {
@@ -361,6 +404,7 @@ function activeAgentsForMode(config, mode) {
     }
     return [defaults.agentA, defaults.agentB].filter((agent) => Boolean(agent && config.agents[agent]));
 }
+/** Valide les rôles connus et conserve exactement le nombre attendu. */
 function normalizeTuiRoles(roleNames, agents, mode, messages) {
     const roles = roleNames.map((role) => role.trim().toLowerCase()).filter(Boolean);
     const expectedCount = agents.length;
@@ -386,6 +430,7 @@ function assertKnownAgent(config, agentName, fieldName, messages) {
         throw new Error(messages.common.unknownAgentForField(fieldName, agentName, Object.keys(config.agents).join(", ")));
     }
 }
+/** Convertit les erreurs adapter et URL stables en message localisé pour la TUI. */
 function formatTuiRuntimeError(error, messages) {
     if (error instanceof AdapterError)
         return formatAdapterError(error, messages);

package/dist/tuiState.js

@@ -1,3 +1,5 @@
+/** @file État partagé entre le point d'entrée et la TUI pour réinitialiser les overrides de lancement entre deux sessions. */
+/** Flags de session ponctuels (par sujet) qui ne doivent pas persister entre deux lancements TUI successifs. */
 const TUI_RUN_OVERRIDE_FLAGS = [
     "preset",
     "agent-a",
@@ -19,11 +21,13 @@ const TUI_RUN_OVERRIDE_FLAGS = [
     "terminal",
     "json"
 ];
+/** Supprime les overrides de lancement d'une session TUI terminée, pour repartir des defaults au prochain sujet. */
 export function clearTuiRunOverrides(flags) {
     for (const flag of TUI_RUN_OVERRIDE_FLAGS) {
         delete flags[flag];
     }
 }
+/** Pré-remplit les agents `ask` proposés par le wizard : explicites, sinon defaults de config, sinon aucun en mode `debate`. */
 export function askAgentSeedsForMode(mode, explicitAskAgents, defaultAskAgents) {
     if (mode !== "ask") {
         return [];

package/dist/types.js

@@ -1 +1,2 @@
+/** @file Contrats partagés entre modules : agents, config, options de débat et résultats de session. */
 export {};

package/dist/update.js

@@ -1,3 +1,4 @@
+/** @file Détection du mode d'installation et application du workflow de mise à jour pour un checkout source. */
 import { spawn } from "node:child_process";
 import { access } from "node:fs/promises";
 import path from "node:path";

package/dist/version.js

@@ -1,3 +1,4 @@
+/** @file Version locale courante et dernière version publiée npm, pour `--version` et la notice de mise à jour TUI. */
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

package/package.json

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