nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/agentTargets.js

@@ -0,0 +1,461 @@
+import { MCP_CONFIG_FILE, MCP_SERVER_KEY, MCP_TOKEN_ENV } from "./aiMcpReport.js";
+import { homedir } from "node:os";
+import path from "node:path";
+//#region src/cli/agentTargets.ts
+/**
+* Les agents de développement, et ce que Nodefony sait faire pour eux.
+*
+* Deux gestes distincts vivent ici, et il ne faut pas les confondre :
+*
+*  1. **poser le SECRET** là où l'agent lit ses variables (`security:token`) ;
+*  2. **déclarer la PORTE** — l'URL du serveur MCP — dans sa configuration
+*     (`ai:mcp --agent`).
+*
+* La frontière est celle-ci : **Nodefony possède le jeton et l'URL, l'agent
+* possède le format de sa déclaration.** On n'écrit donc jamais le fichier de
+* configuration d'un outil tiers pour la déclaration : on appelle SA CLI, qui
+* est la seule à savoir ce qu'elle attend et à survivre à ses propres versions.
+* Le secret, lui, se pose bien dans un fichier — parce qu'aucune de ces CLI
+* n'offre de le faire, et parce que l'emplacement a été CONSTATÉ, agent par
+* agent.
+*
+* Ce fichier vit dans le CŒUR et non dans `@nodefony/security` : `ai:mcp` et
+* `create app` sont des commandes du cœur, et une table recopiée à deux
+* endroits diverge en silence.
+*/
+/**
+* Agents dont l'emplacement de secret a été CONSTATÉ — au comportement ou au
+* source, jamais sur la foi d'une page de blog.
+*
+* Deux stratégies pour le SECRET, et elles ne se ressemblent pas :
+*  - **Claude Code** prend la VALEUR : la clé `env` de `settings.local.json`
+*    alimente l'expansion `${VAR}` de `.mcp.json` (constaté — `claude mcp list`
+*    passe de l'en-tête non substitué à « ✔ Connected ») ;
+*  - **Vibe** prend le NOM d'une variable (`--api-key-env`) et la résout dans
+*    son environnement — mais il PEUPLE cet environnement au démarrage depuis
+*    `$VIBE_HOME/.env` (`load_dotenv_values`, `vibe/cli/cli.py`), une valeur du
+*    shell l'emportant sur le fichier. Écrire là revient donc bien à câbler ;
+*  - **Gemini CLI** de même, depuis un fichier qu'il CHERCHE en remontant
+*    l'arborescence (`findEnvFile`) : `<projet>/.gemini/.env` d'abord — quand
+*    l'espace est de confiance — puis `<projet>/.env`, puis les parents, puis
+*    `~/.gemini/.env`. Le PREMIER trouvé gagne, et lui seul est chargé : viser
+*    `.gemini/.env` évite qu'il lise à la place le `.env` de l'application.
+*
+*  - **Codex** de même, depuis `$CODEX_HOME/.env` (défaut `~/.codex/.env`), et
+*    de là SEULEMENT : le `.env` du projet n'est pas lu.
+*
+* ⚠️ Ce dernier point a d'abord été conclu à l'envers, en cherchant une chaîne
+* dans un binaire compilé et en prenant son absence pour une preuve. Une
+* ABSENCE de trace n'en est pas une : c'est l'expérience qui a tranché — une
+* sonde (`codex doctor` signale une variable de serveur MCP manquante) montrée
+* discriminante d'abord, témoin à 1 et variable exportée à 0, puis passée sur
+* chaque emplacement candidat.
+*
+* ## Pourquoi certains sont déclarés LOCALEMENT et d'autres non
+*
+* ⚠️ **Deux questions distinctes, et les confondre mène à la faute** : ce que
+* l'agent LIT, et ce que sa CLI ÉCRIT. Les quatre savent lire une configuration
+* de projet, et les quatre y écrivent — deux d'entre eux seulement à condition
+* qu'on déplace leur dossier.
+*
+* | agent  | lit le projet                            | comment sa CLI y écrit    |
+* | ------ | ---------------------------------------- | ------------------------- |
+* | claude | `.mcp.json`                              | on écrit le fichier       |
+* | gemini | `.gemini/settings.json`                  | `--scope project`         |
+* | codex  | `.codex/config.toml` **si de confiance** | `CODEX_HOME=<projet>/.codex` |
+* | vibe   | `.vibe/config.toml` **si de confiance**  | `VIBE_HOME=<projet>/.vibe`   |
+*
+* Pour Codex et Vibe, la portée projet EXISTE mais leur ligne de commande n'a
+* pas d'option pour la viser : `codex mcp add` répond « Added **global** MCP
+* server », et le source de Vibe subordonne l'écriture à la source « user »
+* (`persist_allowed`).
+*
+* ⭐ **La sortie n'est ni de renoncer, ni d'écrire leur TOML nous-mêmes** — ce
+* serait reprendre à notre compte le format d'un tiers, précisément ce que ce
+* fichier existe pour éviter. Les deux obéissent à une variable qui déplace
+* leur dossier (`VIBE_HOME`, `CODEX_HOME`) : pointée sur `<projet>/<marker>`,
+* c'est LEUR binaire qui écrit LEUR format, dans le PROJET. Vérifié au disque
+* pour les deux, ligne d'authentification comprise.
+*
+* Et il le fallait, parce que le global est FAUX ici, pas seulement intrusif :
+* l'URL d'une porte porte un PORT, et deux applications Nodefony n'écoutent pas
+* sur le même. Une déclaration dans le foyer ne peut donc en désigner qu'UNE —
+* la dernière câblée efface la précédente sans un mot. L'annoncer, comme on le
+* faisait, ne répare rien.
+*
+* Ce qui reste vrai, et que la commande DIT : ces fichiers ne sont lus que dans
+* un dossier que l'agent tient pour DE CONFIANCE — un geste de sécurité qui
+* appartient à l'utilisateur. Un fichier non lu est inerte ; une déclaration
+* globale qui pointe la mauvaise application est active. Entre échouer en
+* silence et réussir à côté, on choisit le premier. `--global` reste offert à
+* qui veut délibérément l'autre.
+*
+* ⚠️ Le premier état de ce commentaire affirmait que Codex « n'a aucune notion
+* de projet ». C'était FAUX, et la sonde qui l'avait « prouvé » ne l'était pas :
+* elle tournait dans un dépôt NON approuvé, donc elle mesurait la confiance, pas
+* la portée. Le binaire le dit lui-même — « Project `.codex/config.toml`:
+* settings for a trusted repository, including [...] MCP ». Une absence de trace
+* n'est pas une preuve, et une sonde doit être discriminante SUR LA BONNE
+* VARIABLE.
+*
+* Et pour la DÉCLARATION de la porte, le partage est net, lui aussi constaté :
+* **seul Claude Code lit le `.mcp.json` du projet**. Gemini a été mesuré
+* l'ignorant — `.mcp.json` déclarant `nodefony` sur le disque, `gemini mcp list`
+* répond « No MCP servers configured ». Les trois autres reçoivent donc leur
+* déclaration par leur propre CLI, dans la grammaire lue de leur `--help`.
+*/
+const AGENT_TARGETS = [
+	{
+		key: "claude",
+		name: "Claude Code",
+		scope: "projet",
+		marker: ".claude",
+		file: ".claude/settings.local.json",
+		forme: "json-env",
+		instructions: {
+			file: "CLAUDE.md",
+			natif: false,
+			proof: "mesure : CLAUDE.md chargé, AGENTS.md seul ignoré (2.1.240)"
+		},
+		declaration: "fichier-projet"
+	},
+	{
+		key: "gemini",
+		name: "Gemini CLI",
+		scope: "projet",
+		marker: ".gemini",
+		file: ".gemini/.env",
+		forme: "dotenv",
+		instructions: {
+			file: "GEMINI.md",
+			natif: false,
+			proof: "gemini-cli packages/core/src/tools/memoryTool.ts (DEFAULT_CONTEXT_FILENAME)"
+		},
+		declaration: "cli",
+		bin: "gemini",
+		argvAdd: (c) => [
+			"mcp",
+			"add",
+			c.name,
+			c.url,
+			"--transport",
+			"http",
+			"--scope",
+			"project",
+			"--header",
+			`Authorization: Bearer \${${c.tokenEnv}}`
+		],
+		argvRemove: () => [
+			"mcp",
+			"remove",
+			MCP_SERVER_KEY,
+			"--scope",
+			"project"
+		],
+		argvList: () => ["mcp", "list"],
+		noteAfter: "Gemini n'active un serveur que dans un dossier de CONFIANCE — sinon il reste « Disabled ». Accorde la confiance au premier lancement, ou `gemini --skip-trust` le temps d'une session."
+	},
+	{
+		key: "vibe",
+		name: "Vibe (Mistral)",
+		scope: "utilisateur",
+		marker: ".vibe",
+		file: ".env",
+		forme: "dotenv",
+		home: "VIBE_HOME",
+		instructions: {
+			file: "AGENTS.md",
+			natif: true,
+			proof: "mistral-vibe vibe/core/paths/conventions.py (AGENTS_MD_FILENAME)"
+		},
+		declaration: "cli",
+		bin: "vibe",
+		noteAfter: "Déclaration de PROJET (`.vibe/config.toml`), écrite par sa propre CLI via `VIBE_HOME`. Vibe ne la lira que dans un dossier qu'il tient pour de CONFIANCE : `vibe --trust` une fois, ici. `--global` la remet dans ton foyer, où elle vaudra pour tous tes projets — donc pour un seul, puisque l'URL porte un port.",
+		argvAdd: (c) => [
+			"mcp",
+			"add",
+			c.name,
+			"--transport",
+			"streamable-http",
+			"--url",
+			c.url,
+			"--api-key-env",
+			c.tokenEnv
+		],
+		argvRemove: () => [
+			"mcp",
+			"remove",
+			MCP_SERVER_KEY
+		]
+	},
+	{
+		key: "codex",
+		name: "Codex",
+		scope: "utilisateur",
+		marker: ".codex",
+		file: ".env",
+		forme: "dotenv",
+		home: "CODEX_HOME",
+		instructions: {
+			file: "AGENTS.md",
+			natif: true,
+			proof: "codex codex-rs/core/src/agents_md.rs (DEFAULT_AGENTS_MD_FILENAME)"
+		},
+		declaration: "cli",
+		bin: "codex",
+		noteAfter: "Déclaration de PROJET (`.codex/config.toml`), écrite par sa propre CLI via `CODEX_HOME` — il répond « Added global », mot qui parle de SON dossier, pas du tien. Codex ne la lira que dans un dépôt de CONFIANCE (`trust_level`). `--global` la remet dans ton foyer.",
+		argvAdd: (c) => [
+			"mcp",
+			"add",
+			c.name,
+			"--url",
+			c.url,
+			"--bearer-token-env-var",
+			c.tokenEnv
+		],
+		argvRemove: () => [
+			"mcp",
+			"remove",
+			MCP_SERVER_KEY
+		],
+		argvList: () => ["mcp", "list"]
+	}
+];
+/**
+* Compose la déclaration de la porte MCP chez un agent.
+*
+* @param target - l'agent visé
+* @param ctx - l'URL de la porte et le nom de la variable qui porte le jeton
+* @param remove - `true` pour retirer la déclaration au lieu de la poser
+* @returns le plan d'exécution, jamais `null` — un agent sans CLI est un agent
+*          dont la déclaration vit déjà dans un fichier du projet
+*/
+function planAgentDeclaration(target, ctx, remove = false) {
+	if (target.declaration === "fichier-projet" || !target.bin) return {
+		voie: "fichier-projet",
+		file: MCP_CONFIG_FILE
+	};
+	const argv = remove ? target.argvRemove?.() ?? [] : target.argvAdd?.({
+		...ctx,
+		name: "nodefony"
+	}) ?? [];
+	return {
+		voie: "cli",
+		bin: target.bin,
+		argv
+	};
+}
+/**
+* Rend le plan sous la forme qu'on peut recopier dans un terminal.
+*
+* C'est le repli quand la CLI est absente : dire ce qu'il aurait fallu lancer
+* vaut mieux que constater l'absence — la commande reste juste le jour où
+* l'agent sera installé.
+*
+* @param plan - un plan de voie `cli` (les autres n'ont rien à recopier)
+*/
+function renderPlanShell(plan) {
+	if (plan.voie !== "cli") return "";
+	return [plan.bin, ...plan.argv.map((a) => /[\s"$]/u.test(a) ? `"${a}"` : a)].join(" ");
+}
+/**
+* Racine où vit la configuration d'une cible : le projet, ou son dossier maison.
+*
+* PURE au sens qui compte : l'environnement et le dossier de l'utilisateur sont
+* INJECTÉS, jamais lus ici. C'est ce qui permet d'éprouver la résolution — y
+* compris la grammaire de chemins d'une autre plateforme — sans dépendre du
+* poste qui exécute le test.
+*
+* @param target - l'agent visé
+* @param ctx - racine du projet, dossier de l'utilisateur, environnement
+*/
+function agentRoot(target, ctx) {
+	if (target.scope === "projet") return ctx.projectRoot;
+	const surcharge = target.home ? (ctx.env ?? process.env)[target.home] : void 0;
+	return path.resolve(surcharge ?? path.join(ctx.home ?? homedir(), target.marker));
+}
+/**
+* Agents dont la présence est CONSTATÉE sur ce poste.
+*
+* On ne crée pas la configuration d'un outil que personne n'utilise ici : le
+* marqueur (`.claude`, `.codex`…) est la seule preuve qu'on ait, et il vaut
+* mieux qu'une déduction depuis le `PATH` — un binaire installé ne dit pas que
+* quelqu'un s'en sert dans CE projet.
+*
+* Le test d'existence est INJECTÉ : c'est ce qui permet d'éprouver la détection
+* sans dépendre du poste qui exécute le test, et de la rejouer pour une
+* arborescence qui n'existe nulle part.
+*
+* @param ctx - racine du projet, dossier de l'utilisateur, environnement, et le
+*              prédicat qui répond « ce chemin existe-t-il ? »
+*/
+function agentsPresents(ctx) {
+	return AGENT_TARGETS.filter((c) => {
+		const inProject = ctx.exists(path.resolve(ctx.projectRoot, c.marker));
+		const inUserHome = ctx.exists(agentRoot({
+			...c,
+			scope: "utilisateur"
+		}, ctx));
+		return inProject || inUserHome;
+	});
+}
+/**
+* Pose une variable dans le contenu d'un fichier de configuration d'agent.
+*
+* Fonction PURE — elle prend le contenu et rend le contenu. C'est ce qui permet
+* d'éprouver chaque grammaire sans écrire sur le disque de qui que ce soit, et
+* de garantir qu'un fichier existant n'est pas ÉCRASÉ mais complété : ces
+* fichiers portent les réglages de quelqu'un d'autre.
+*
+* @param forme - grammaire du fichier
+* @param actuel - contenu actuel, ou chaîne vide s'il n'existe pas
+* @param cle - nom de la variable
+* @param valeur - sa valeur
+* @returns le nouveau contenu, ou une `Error` si le fichier est illisible
+*/
+/**
+* La chaîne sans ses sauts de ligne FINAUX — sans expression régulière.
+*
+* `/\n*$/` a l'air anodin et coûte du temps quadratique : sur une queue de
+* sauts de ligne, le moteur réessaie depuis chaque position. Une boucle qui
+* recule dit la même chose en un seul passage, et se lit mieux.
+*
+* `trimEnd()` ne convient pas : il emporterait aussi espaces et tabulations,
+* alors qu'on ne veut normaliser QUE la fin de ligne avant d'ajouter la nôtre.
+*/
+function withoutTrailingNewlines(text) {
+	let fin = text.length;
+	while (fin > 0 && text.charCodeAt(fin - 1) === 10) fin -= 1;
+	return text.slice(0, fin);
+}
+function poseVariable(forme, current, key, value) {
+	if (forme === "dotenv") {
+		const line = `${key}=${value}`;
+		const pattern = new RegExp(`^\\s*${key}\\s*=.*$`, "m");
+		if (pattern.test(current)) return current.replace(pattern, line);
+		return current.length === 0 ? `${line}\n` : `${withoutTrailingNewlines(current)}\n${line}\n`;
+	}
+	let doc;
+	try {
+		doc = current.trim() === "" ? {} : JSON.parse(current);
+	} catch {
+		return /* @__PURE__ */ new Error("le fichier existe mais n'est pas du JSON valide");
+	}
+	const env = doc.env ?? {};
+	env[key] = value;
+	doc.env = env;
+	return `${JSON.stringify(doc, null, 2)}\n`;
+}
+/**
+* Ce fichier porte-t-il DÉJÀ cette variable ?
+*
+* ⭐ C'est ce qui rend la rotation simple : l'état de câblage n'a pas à être
+* mémorisé quelque part, il EST dans les fichiers des agents. Un agent qui
+* porte la clé a été câblé un jour — le relancer doit la METTRE À JOUR, sans
+* reposer la question. Un fichier d'état parallèle, lui, mentirait dès que
+* quelqu'un modifierait sa configuration à la main.
+*
+* @param forme - grammaire du fichier
+* @param contenu - son contenu, ou chaîne vide s'il n'existe pas
+* @param cle - nom de la variable
+*/
+/**
+* Valeur d'une variable dans le fichier de configuration d'un agent.
+*
+* Fonction PURE — elle prend le contenu, elle rend la valeur. Elle existe pour
+* qu'on puisse RENSEIGNER sur un jeton posé (son échéance, ce qu'il autorise)
+* sans jamais le divulguer : c'est l'appelant qui décide ce qu'il en montre, et
+* ce qu'il en montre n'est pas le jeton.
+*
+* @param forme - grammaire du fichier
+* @param content - contenu actuel, ou chaîne vide
+* @param key - nom de la variable
+* @returns la valeur, ou `null` si elle est absente ou vide
+*/
+function litVariable(forme, content, key) {
+	if (content.trim() === "") return null;
+	if (forme === "dotenv") {
+		const found = new RegExp(`^\\s*${key}\\s*=\\s*(.*)$`, "m").exec(content);
+		if (!found?.[1]) return null;
+		const brut = found[1].trim().replace(/^["']|["']$/gu, "");
+		return brut === "" ? null : brut;
+	}
+	try {
+		const value = JSON.parse(content).env?.[key];
+		return typeof value === "string" && value !== "" ? value : null;
+	} catch {
+		return null;
+	}
+}
+function alreadyHasKey(forme, content, key) {
+	if (content.trim() === "") return false;
+	if (forme === "dotenv") return new RegExp(`^\\s*${key}\\s*=`, "m").test(content);
+	try {
+		const doc = JSON.parse(content);
+		return typeof doc.env?.[key] === "string" && doc.env[key] !== "";
+	} catch {
+		return false;
+	}
+}
+/**
+* Traduit `--agent` en cibles, ou rend l'erreur à afficher.
+*
+* Trois formes : rien (les cibles détectées, décidé par l'appelant), `none`
+* (aucune écriture), ou une liste de clés. Une clé inconnue est REFUSÉE en
+* nommant celles qui existent — ignorée en silence, elle ferait croire à un
+* agent servi qui ne l'est pas, et c'est exactement ce genre de silence qui a
+* déjà coûté une heure de diagnostic ici.
+*
+* @param raw - la valeur telle que tapée, ou rien
+* @returns les cibles demandées, `undefined` si rien n'est demandé, une `Error` sinon
+*/
+function requestedAgents(raw) {
+	if (raw === void 0) return void 0;
+	const keys = raw.split(/[\s,]+/u).map((c) => c.trim().toLowerCase()).filter(Boolean);
+	if (keys.length === 1 && keys[0] === "none") return [];
+	if (keys.length === 1 && keys[0] === "all") return AGENT_TARGETS;
+	const known = AGENT_TARGETS.map((c) => c.key);
+	const unknown = keys.filter((c) => !known.includes(c));
+	if (unknown.length > 0) return /* @__PURE__ */ new Error(`--agent : « ${unknown.join(", ")} » inconnu — attendus : ${known.join(", ")}, all, none`);
+	return AGENT_TARGETS.filter((c) => keys.includes(c.key));
+}
+/**
+* Les fichiers-POINTEURS à poser pour qu'aucun agent ne travaille aveugle.
+*
+* PURE, dérivée de {@link AGENT_TARGETS} : un agent qui lit déjà `AGENTS.md`
+* n'a besoin de rien, les autres reçoivent un fichier à LEUR nom qui renvoie
+* au standard. Deux agents qui liraient le même nom sont regroupés — le
+* pointeur est écrit une fois et les nomme tous les deux.
+*
+* 🔴 **Le filtrage n'est pas un confort.** Sans `keys`, cette fonction rendait
+* TOUS les pointeurs, et une application créée en répondant « Claude » naissait
+* avec un `GEMINI.md` que personne n'avait demandé. Rapporté tel quel :
+* « j'ai demandé un agent claude, je me retrouve avec un GEMINI.md ». Poser
+* chez quelqu'un le fichier d'un outil qu'il n'utilise pas n'est pas une
+* prévenance : c'est du bruit dans SON dépôt, qu'il devra expliquer à son
+* équipe. L'agent qui arrive plus tard reçoit son pointeur au moment où on le
+* câble (`nodefony ai:mcp --agent <clé>`), c'est-à-dire quand il entre
+* réellement dans le projet.
+*
+* @param keys - clés d'agents retenues. **Obligatoire** : rendre tous les
+*   pointeurs par défaut est précisément le défaut corrigé. Une liste vide ne
+*   rend rien — coder seul est un choix.
+* @returns un couple `file` → agents concernés, trié par nom de fichier.
+*/
+function pointeursInstructions(keys) {
+	const kept = new Set(keys);
+	const par = /* @__PURE__ */ new Map();
+	for (const target of AGENT_TARGETS) {
+		if (target.instructions.natif) continue;
+		if (!kept.has(target.key)) continue;
+		const already = par.get(target.instructions.file);
+		if (already) already.push(target.name);
+		else par.set(target.instructions.file, [target.name]);
+	}
+	return [...par.entries()].map(([file, agents]) => ({
+		file,
+		agents
+	})).sort((a, b) => a.file.localeCompare(b.file));
+}
+//#endregion
+export { AGENT_TARGETS, MCP_TOKEN_ENV, agentRoot, agentsPresents, alreadyHasKey, litVariable, planAgentDeclaration, pointeursInstructions, poseVariable, renderPlanShell, requestedAgents };