nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/aiMcp.js

@@ -0,0 +1,553 @@
+import "./sysexits.js";
+import { chargePrompts } from "./prompts.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { defaultDevPorts } from "../service/dev/devProcess.js";
+import { findProjectRoot } from "./projectRoot.js";
+import { ADMIN_SCOPE_READ, ADMIN_SCOPE_WRITE } from "../kernel/adminPlane/adminCaller.js";
+import { MCP_CONFIG_FILE, MCP_SERVER_KEY, MCP_TOKEN_ENV, buildMcpUrl, planMcpConfig, renderMcpPlan } from "./aiMcpReport.js";
+import { AGENT_TARGETS, agentRoot, agentsPresents, litVariable, planAgentDeclaration, renderPlanShell, requestedAgents } from "./agentTargets.js";
+import { writeAgentPointers } from "./scaffold/engine.js";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+//#region src/cli/aiMcp.ts
+/**
+* `nodefony ai:mcp` — déclare le serveur MCP de cette application à ton agent.
+*
+* ## Ce que cette commande fait, et ce qu'elle NE fait pas
+*
+* Elle **écrit un fichier de câblage** (`.mcp.json`) et rend la main. Elle ne
+* démarre aucun process : depuis la révision `2026-07-28` du transport, un
+* serveur MCP est un simple endpoint `POST` sans session — chez Nodefony,
+* c'est une **route de l'application** (`POST /nodefony/mcp`, module
+* `@nodefony/devkit`). Il n'y a donc rien à lancer en plus de l'application,
+* et rien à relancer quand le superviseur la recharge.
+*
+* ## Pourquoi standalone (aucun boot)
+*
+* Même raison que `card` et `ai:sync` : écrire un fichier de configuration ne
+* dépend d'aucun service, et la commande doit répondre dans un terminal qui n'a
+* pas posé `NODE_ENV` — le module qui sert la route est `policy: "dev"`, il
+* n'existerait pas ici.
+*
+* ## Le port n'est pas deviné
+*
+* Il est lu du fichier d'état que le runtime publie une fois ses serveurs en
+* écoute (`defaultDevPorts`), et retombe sur la convention `5151` seulement
+* quand rien n'a jamais tourné. C'est la même source que `nodefony status` :
+* deux lectures indépendantes finiraient par annoncer un port où personne
+* n'écoute.
+*/
+/** Chemin de la route MCP — dupliqué NULLE PART ailleurs dans le cœur. */
+const MCP_PATH = "/nodefony/mcp";
+/** La page d'aide — `nodefony ai:mcp --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony ai:mcp",
+	tagline: "déclare le serveur MCP de cette application à ton agent, et si tu veux chez les agents installés",
+	synopsis: ["nodefony ai:mcp [--auth|--no-auth] [--url <origine>] [options]", "nodefony ai:mcp --agent <liste> [--remove] [--global] [options]"],
+	sections: [{
+		title: "CE QU'ELLE ÉCRIT",
+		paragraph: `Le fichier ${MCP_CONFIG_FILE} du projet, et — si --agent est donné — la déclaration chez les agents nommés, par LEUR propre outil en ligne de commande. Elle ne DÉMARRE rien : le serveur MCP est une route de l'application, pas un process.`
+	}, {
+		title: "AGENTS RECONNUS",
+		lines: [`${AGENT_TARGETS.map((c) => c.key).join(" · ")} · all · none`],
+		paragraph: "« none » — ou aucune case cochée en mode interactif — ne touche à aucun agent : coder seul est un choix, pas un oubli."
+	}],
+	options: [
+		{
+			term: "-a, --auth",
+			text: `mode authentifié : l'en-tête porte \${${MCP_TOKEN_ENV}}, jamais le jeton lui-même. Sans option, le mode déjà en place est CONSERVÉ`
+		},
+		{
+			term: "--no-auth",
+			text: "retire l'en-tête d'autorisation"
+		},
+		{
+			term: "-u, --url <origine>",
+			text: "origine forcée (ex. https://localhost:5152)"
+		},
+		{
+			term: "--agent <liste>",
+			text: "déclare AUSSI la porte chez ces agents, via leur propre CLI"
+		},
+		{
+			term: "--remove",
+			text: "avec --agent : retire la déclaration au lieu de la poser"
+		},
+		{
+			term: "--global",
+			text: "avec --agent : déclare dans TON foyer au lieu du projet (une seule application servie)"
+		},
+		{
+			term: "-n, --dry-run",
+			text: "le plan, sans rien écrire"
+		},
+		{
+			term: "-j, --json",
+			text: "le même plan, exploitable par un script"
+		},
+		{
+			term: "--cwd <chemin>",
+			text: "point de départ (la racine de l'app est résolue en remontant)"
+		}
+	],
+	examples: [
+		{
+			term: "nodefony ai:mcp",
+			text: "déclare la porte dans le projet"
+		},
+		{
+			term: "nodefony ai:mcp --auth",
+			text: "en mode authentifié — le jeton s'obtient par `nodefony security:token --write`"
+		},
+		{
+			term: "nodefony ai:mcp --agent all",
+			text: "et chez tous les agents installés sur ce poste"
+		}
+	],
+	exitCodes: [{
+		term: "66",
+		text: "aucune application ici (EX_NOINPUT)"
+	}]
+};
+/**
+* Parse l'argv après le mot `ai:mcp`.
+*
+* @param argv - `process.argv` complet
+* @returns la demande, ou le motif du refus
+*/
+function parseAiMcpArgv(argv) {
+	const at = argv.indexOf("ai:mcp");
+	const rest = at === -1 ? [] : argv.slice(at + 1);
+	const req = {
+		url: null,
+		auth: null,
+		agent: void 0,
+		remove: false,
+		global: false,
+		dryRun: false,
+		json: false,
+		cwd: process.cwd(),
+		help: false
+	};
+	for (let i = 0; i < rest.length; i++) {
+		const word = rest[i];
+		if (word === "--help" || word === "-h") req.help = true;
+		else if (word === "--auth" || word === "-a") req.auth = true;
+		else if (word === "--no-auth") req.auth = false;
+		else if (word === "--dry-run" || word === "-n") req.dryRun = true;
+		else if (word === "--json" || word === "-j") req.json = true;
+		else if (word === "--agent") req.agent = rest[++i] ?? "";
+		else if (word === "--global") req.global = true;
+		else if (word === "--remove") req.remove = true;
+		else if (word === "--url" || word === "-u") req.url = rest[++i] ?? null;
+		else if (word === "--cwd") req.cwd = path.resolve(rest[++i] ?? "");
+		else return { error: `argument inconnu : ${word}` };
+	}
+	return req;
+}
+/**
+* Déduit l'origine du serveur de développement.
+*
+* ⚠️ **Le port en clair est préféré au port TLS**, et ce n'est pas une
+* négligence : en développement le certificat est auto-signé, et un client MCP
+* qui le refuse ne dit pas pourquoi — il rend « serveur injoignable ». L'appel
+* est purement local ; `--url` reste là pour qui veut le TLS.
+*
+* @param cwd - racine du projet
+*/
+function guessOrigin(cwd) {
+	return `http://localhost:${defaultDevPorts(cwd)[0] ?? 5151}`;
+}
+/**
+* Lit l'échéance et les scopes d'un JWT, sans le valider ni le divulguer.
+*
+* @param token - le jeton compact (`en-tête.charge.signature`).
+* @param nowSeconds - l'instant de référence, INJECTÉ pour que le banc
+*   n'ait pas à attendre le temps qui passe.
+* @returns l'état lisible, ou `null` si ce n'est pas un JWT exploitable.
+*/
+function tokenState(token, nowSeconds) {
+	const parts = token.split(".");
+	if (parts.length !== 3 || !parts[1]) return null;
+	try {
+		const charge = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+		const scope = typeof charge.scope === "string" ? charge.scope : "";
+		return {
+			remainingSeconds: typeof charge.exp === "number" ? charge.exp - nowSeconds : null,
+			scopes: scope.split(/\s+/u).filter((s) => s !== "")
+		};
+	} catch {
+		return null;
+	}
+}
+/**
+* Phrase d'état d'un jeton, pour un humain devant une question.
+*
+* @param state - ce que {@link tokenState} a lu, ou `null` s'il n'y en a pas.
+* @returns la ligne à afficher.
+*/
+function renderTokenState(state) {
+	if (state === null) return "aucun jeton lisible n'est posé chez tes agents";
+	const scopes = state.scopes.length > 0 ? state.scopes.join(" ") : "aucun scope déclaré";
+	if (state.remainingSeconds === null) return `jeton sans échéance (${scopes})`;
+	if (state.remainingSeconds <= 0) return `jeton EXPIRÉ depuis ${Math.round(-state.remainingSeconds / 60)} min (${scopes}) — c'est lui qui provoque les 401`;
+	const hours = state.remainingSeconds / 3600;
+	return `jeton valide encore ${hours >= 48 ? `${Math.round(hours / 24)} jours` : hours >= 2 ? `${Math.round(hours)} heures` : `${Math.round(state.remainingSeconds / 60)} min`} (${scopes})`;
+}
+/**
+* État du jeton posé chez CHAQUE agent détecté — l'échéance et la portée, pas
+* le secret.
+*
+* ⭐ Par agent, et non « le » jeton : rien ne garantit qu'ils portent le même.
+* Un agent servi il y a trois semaines a le sien, périmé, pendant qu'un autre
+* vient d'être rafraîchi — et c'est précisément l'écart qu'on ne voit jamais,
+* parce qu'il se manifeste par un `401` chez un seul outil.
+*
+* @param targets - agents détectés sur ce poste.
+* @param projectRoot - racine du projet, pour résoudre leurs fichiers.
+* @param nowSeconds - instant de référence, injecté pour le banc.
+* @returns pour chaque agent, sa phrase d'état.
+*/
+function agentTokenStates(targets, projectRoot, nowSeconds) {
+	const states = /* @__PURE__ */ new Map();
+	for (const target of targets) {
+		const file = path.resolve(agentRoot(target, { projectRoot }), target.file);
+		let content = "";
+		try {
+			content = readFileSync(file, "utf8");
+		} catch (e) {
+			if (e.code !== "ENOENT") {
+				states.set(target.key, "état du jeton illisible");
+				continue;
+			}
+		}
+		const token = litVariable(target.forme, content, MCP_TOKEN_ENV);
+		states.set(target.key, token === null ? "pas de jeton posé" : renderTokenState(tokenState(token, nowSeconds)));
+	}
+	return states;
+}
+function planTokenChaining(request, context) {
+	if (request.auth !== true) return null;
+	if (request.dryRun || request.json) return null;
+	if (!context.isTTY) return null;
+	const argv = ["security:token", "--write"];
+	if (context.ttlMinutes !== void 0) argv.push("--ttl", String(context.ttlMinutes));
+	if (context.scopes !== void 0 && context.scopes.trim() !== "") argv.push("--scope", context.scopes);
+	return {
+		argv,
+		env: {
+			...context.env ?? process.env,
+			NODE_ENV: "development"
+		},
+		cwd: context.projectRoot
+	};
+}
+/**
+* Déclare (ou retire) la porte MCP chez chaque agent, **par SA propre CLI**.
+*
+* ⭐ La règle qui gouverne cette fonction : **on n'écrit pas le fichier de
+* configuration d'un outil tiers.** Son format lui appartient, il change avec
+* ses versions, et une écriture faite « à la main » se découvre le jour où
+* l'agent ne voit plus rien — sans rien dire. Sa CLI, elle, connaît son format
+* et le suit.
+*
+* La sortie des CLI est CAPTURÉE plutôt qu'héritée, et n'est montrée qu'en cas
+* d'échec : l'une d'elles écrit des avertissements d'interpréteur sur la sortie
+* d'erreur à chaque appel, et les laisser passer ferait lire un succès comme
+* une panne.
+*
+* @param targets - agents à servir
+* @param ctx - l'URL de la porte, et le sens du geste
+* @returns un verdict par agent — jamais une exception : un agent qui refuse
+*          n'empêche pas de servir les suivants
+*/
+async function declareToAgents(targets, ctx) {
+	const { spawnSync } = await import("node:child_process");
+	const { mkdirSync } = await import("node:fs");
+	const results = [];
+	for (const target of targets) {
+		const plan = planAgentDeclaration(target, {
+			url: ctx.url,
+			tokenEnv: MCP_TOKEN_ENV
+		}, ctx.remove);
+		if (plan.voie !== "cli") {
+			results.push({
+				target,
+				state: "fichier-projet",
+				command: ""
+			});
+			continue;
+		}
+		const command = renderPlanShell(plan);
+		const projectRoot = target.home ? path.join(ctx.projectRoot, target.marker) : void 0;
+		const inProject = projectRoot !== void 0 && !ctx.global;
+		if (inProject && projectRoot) try {
+			mkdirSync(projectRoot, { recursive: true });
+		} catch {}
+		const envAgent = inProject && projectRoot && target.home ? {
+			...process.env,
+			[target.home]: projectRoot
+		} : process.env;
+		const argvListBefore = target.argvList?.();
+		let replacesOtherUrl = false;
+		if (argvListBefore && !ctx.remove) {
+			const before = spawnSync(plan.bin, argvListBefore, {
+				encoding: "utf8",
+				shell: false,
+				cwd: ctx.projectRoot,
+				env: envAgent
+			});
+			const vu = `${before.stdout ?? ""}${before.stderr ?? ""}`;
+			replacesOtherUrl = !before.error && before.status === 0 && vu.includes("nodefony") && !vu.includes(ctx.url);
+		}
+		const r = spawnSync(plan.bin, plan.argv, {
+			encoding: "utf8",
+			shell: false,
+			cwd: ctx.projectRoot,
+			env: envAgent
+		});
+		if (r.error && r.error.code === "ENOENT") {
+			results.push({
+				target,
+				state: "cli-absente",
+				command
+			});
+			continue;
+		}
+		if (r.status !== 0) {
+			results.push({
+				target,
+				state: "echec",
+				command,
+				detail: `${r.stderr ?? ""}${r.stdout ?? ""}`.trim().split("\n").slice(-6).join("\n")
+			});
+			continue;
+		}
+		const argvList = target.argvList?.();
+		if (argvList) {
+			const vue = spawnSync(plan.bin, argvList, {
+				encoding: "utf8",
+				shell: false,
+				cwd: ctx.projectRoot,
+				env: envAgent
+			});
+			const output = `${vue.stdout ?? ""}${vue.stderr ?? ""}`;
+			const lisible = !vue.error && vue.status === 0;
+			const present = output.includes(MCP_SERVER_KEY);
+			if (lisible && present === ctx.remove) {
+				results.push({
+					target,
+					state: "sans-effet",
+					command,
+					detail: output.trim().split("\n").slice(-4).join("\n")
+				});
+				continue;
+			}
+		}
+		results.push({
+			target,
+			inProject,
+			state: ctx.remove ? "retire" : "declare",
+			command,
+			...replacesOtherUrl ? { replacesOtherUrl: true } : {}
+		});
+	}
+	return results;
+}
+/**
+* Rend le compte rendu des déclarations.
+*
+* PURE : c'est le texte que l'utilisateur lit, et il doit pouvoir être éprouvé
+* sans lancer la moindre CLI.
+*
+* @param results - un verdict par agent
+* @param remove - le sens du geste, pour accorder les phrases
+*/
+function renderDeclarations(results, remove) {
+	if (results.length === 0) return "\n  Aucun agent : tu codes seul, c'est un choix.\n  Quand tu voudras : nodefony ai:mcp --agent all\n";
+	let out = "\n";
+	for (const r of results) if (r.state === "fichier-projet") out += `  • ${r.target.name} — rien à faire : il lit ${MCP_CONFIG_FILE}, ${remove ? "retiré par --no-auth ou à la main" : "déjà à jour"}.\n`;
+	else if (r.state === "declare") {
+		const scope = r.inProject || r.target.scope === "projet" ? "dans ce projet" : "GLOBALE — elle vaut pour tous tes projets";
+		out += `  ✓ ${r.target.name} — porte déclarée, ${scope}. RELANCE-le.\n`;
+		if (r.state === "declare" && r.replacesOtherUrl) out += `    ⚠ elle a REMPLACÉ une déclaration « ${MCP_SERVER_KEY} » qui visait ailleurs — une autre application ?\n`;
+		if (r.target.noteAfter) out += `    ⓘ ${r.target.noteAfter}\n`;
+	} else if (r.state === "retire") out += `  ✓ ${r.target.name} — déclaration retirée.\n`;
+	else if (r.state === "sans-effet") out += `  ⚠ ${r.target.name} — sa CLI a répondu « ok », mais la porte est ${remove ? "TOUJOURS déclarée" : "INTROUVABLE"} chez lui.\n    Ce qu'elle liste :\n${(r.detail ?? "").split("\n").map((l) => `      ${l}`).join("\n")}\n    La commande jouée : ${r.command}\n    Son outil ne l'a pas honorée — reprends depuis SA configuration.\n`;
+	else if (r.state === "cli-absente") out += `  ⚠ ${r.target.name} — sa commande « ${r.target.bin} » est introuvable ici.\n    Le jour où tu l'installes :\n      ${r.command}\n`;
+	else out += `  ⚠ ${r.target.name} — sa CLI a refusé :\n${(r.detail ?? "").split("\n").map((l) => `      ${l}`).join("\n")}\n    La commande jouée était :\n      ${r.command}\n`;
+	return out;
+}
+/** Lit le `.mcp.json` du projet, ou `null` s'il est absent ou illisible. */
+function readMcpConfig(file) {
+	if (!existsSync(file)) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		return typeof parsed === "object" && parsed !== null ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Point d'entrée de la commande.
+*
+* @param argv - `process.argv` complet
+* @returns code de sortie sémantique (`OK`, `USAGE`, `NOINPUT` hors projet,
+*          `CANTCREAT` si l'écriture échoue)
+*/
+async function runAiMcpCommand(argv) {
+	const parsed = parseAiMcpArgv(argv);
+	if ("error" in parsed) return printUsageError(PAGE, parsed.error);
+	if (parsed.help) return printUsage(PAGE);
+	const projectRoot = findProjectRoot(parsed.cwd);
+	if (projectRoot === null) {
+		process.stderr.write(`ai:mcp: aucun projet Nodefony ici (pas de nodefony.config.ts en remontant depuis ${parsed.cwd}).\n`);
+		return 66;
+	}
+	if (parsed.auth === null && !parsed.dryRun && !parsed.json && parsed.url === null && process.stdin.isTTY) {
+		const alreadyAuth = Boolean(readMcpConfig(path.join(projectRoot, MCP_CONFIG_FILE))?.mcpServers?.["nodefony"]?.headers?.Authorization);
+		const { confirm } = await chargePrompts();
+		parsed.auth = await confirm({
+			message: `Mode authentifié ? (en-tête \${${MCP_TOKEN_ENV}}${alreadyAuth ? " — répondre non le RETIRE" : ""})`,
+			default: alreadyAuth
+		});
+	}
+	const origin = parsed.url ?? guessOrigin(projectRoot);
+	const mcpUrl = buildMcpUrl(origin, MCP_PATH);
+	const file = path.join(projectRoot, MCP_CONFIG_FILE);
+	const plan = planMcpConfig(readMcpConfig(file), mcpUrl, parsed.auth === null ? {} : { auth: parsed.auth });
+	if (!parsed.dryRun && plan.action !== "inchange") try {
+		writeFileSync(file, `${JSON.stringify(plan.document, null, 2)}\n`);
+	} catch (error) {
+		process.stderr.write(`ai:mcp: écriture impossible (${error.message}).\n`);
+		return 73;
+	}
+	const requests = requestedAgents(parsed.agent);
+	if (requests instanceof Error) {
+		process.stderr.write(`ai:mcp: ${requests.message}\n`);
+		return 64;
+	}
+	let targets = requests ?? [];
+	if (requests === void 0 && !parsed.dryRun && !parsed.json) {
+		const detected = agentsPresents({
+			projectRoot,
+			exists: existsSync
+		});
+		const presents = detected.filter((c) => c.declaration === "cli");
+		const byFile = detected.filter((c) => c.declaration === "fichier-projet");
+		if (detected.length > 0 && process.stdin.isTTY) {
+			const { checkbox } = await chargePrompts();
+			const chosen = await checkbox({
+				message: `Déclarer la porte chez quels agents ? (espace pour cocher — ENTRÉE sans rien cocher : aucun, je code seul)`,
+				choices: [...byFile.map((c) => ({
+					name: `${c.name} — servi par le ${path.basename(file)} de ce projet`,
+					value: c.key,
+					checked: true,
+					disabled: "déjà à jour, rien à lancer"
+				})), ...presents.map((c) => ({
+					name: `${c.name} — ${c.bin} mcp ${parsed.remove ? "remove" : "add"}`,
+					value: c.key,
+					checked: false
+				}))]
+			});
+			targets = presents.filter((c) => chosen.includes(c.key));
+		}
+	}
+	if (parsed.json) {
+		process.stdout.write(`${JSON.stringify({
+			file,
+			...plan,
+			dryRun: parsed.dryRun,
+			agents: targets.map((c) => c.key)
+		}, null, 2)}\n`);
+		return 0;
+	}
+	process.stdout.write(renderMcpPlan(plan, file, parsed.dryRun));
+	if (parsed.dryRun) {
+		if (targets.length > 0) process.stdout.write(`\n  À lancer (non joué — --dry-run) :\n` + targets.map((c) => {
+			const p = planAgentDeclaration(c, {
+				url: mcpUrl,
+				tokenEnv: MCP_TOKEN_ENV
+			}, parsed.remove);
+			return p.voie === "cli" ? `      ${renderPlanShell(p)}\n` : `      (${c.name} : rien — il lit ${MCP_CONFIG_FILE})\n`;
+		}).join(""));
+	} else if (requests !== void 0 || targets.length > 0) {
+		process.stdout.write(renderDeclarations(await declareToAgents(targets, {
+			url: mcpUrl,
+			remove: parsed.remove,
+			projectRoot,
+			global: parsed.global
+		}), parsed.remove));
+		if (!parsed.remove) {
+			const poses = writeAgentPointers(projectRoot, targets.map((c) => c.key), path.basename(projectRoot));
+			if (poses.length > 0) process.stdout.write(`\n  instructions : ${poses.join(", ")} — pointeur(s) vers AGENTS.md\n`);
+		}
+	}
+	const chainage = planTokenChaining(parsed, {
+		projectRoot,
+		isTTY: Boolean(process.stdin.isTTY)
+	});
+	if (chainage) {
+		const { confirm, select } = await chargePrompts();
+		const detectedForToken = agentsPresents({
+			projectRoot,
+			exists: existsSync
+		});
+		const states = agentTokenStates(detectedForToken, projectRoot, Math.floor(Date.now() / 1e3));
+		for (const target of detectedForToken) process.stdout.write(`  ${target.name} : ${states.get(target.key)}\n`);
+		const perime = detectedForToken.length === 0 || [...states.values()].some((phrase) => phrase.includes("EXPIRÉ") || phrase.includes("pas de jeton"));
+		const now = await confirm({
+			message: `${perime ? "Obtenir" : "Réémettre"} un jeton maintenant (${MCP_TOKEN_ENV}) ?`,
+			default: perime
+		});
+		const bin = process.argv[1];
+		if (now && bin) {
+			const withDuration = planTokenChaining(parsed, {
+				projectRoot,
+				isTTY: true,
+				ttlMinutes: await select({
+					message: "Durée de validité du jeton",
+					default: 10080,
+					choices: [
+						{
+							name: "7 jours (recommandé pour un agent local)",
+							value: 10080
+						},
+						{
+							name: "30 jours (maximum)",
+							value: 43200
+						},
+						{
+							name: "12 heures",
+							value: 720
+						},
+						{
+							name: "15 minutes (le défaut de la configuration)",
+							value: 15
+						}
+					]
+				}),
+				scopes: await select({
+					message: "Ce que le jeton autorise",
+					default: ADMIN_SCOPE_READ,
+					choices: [{
+						name: `Lecture seule (${ADMIN_SCOPE_READ}) — recommandé`,
+						value: ADMIN_SCOPE_READ
+					}, {
+						name: `Lecture et mutations (${ADMIN_SCOPE_READ} ${ADMIN_SCOPE_WRITE})`,
+						value: `${ADMIN_SCOPE_READ} ${ADMIN_SCOPE_WRITE}`
+					}]
+				})
+			});
+			const { spawnSync } = await import("node:child_process");
+			spawnSync(process.execPath, [bin, ...(withDuration ?? chainage).argv], {
+				stdio: "inherit",
+				cwd: chainage.cwd,
+				env: chainage.env
+			});
+		}
+	}
+	return 0;
+}
+//#endregion
+export { agentTokenStates, declareToAgents, guessOrigin, parseAiMcpArgv, planTokenChaining, readMcpConfig, renderDeclarations, renderTokenState, runAiMcpCommand, tokenState };

package/dist/node/cli/aiMcpReport.js

@@ -0,0 +1,129 @@
+import { stripTrailingSlashes } from "../Tools.js";
+//#region src/cli/aiMcpReport.ts
+/**
+* Composition PURE de la configuration MCP d'un projet — `.mcp.json`.
+*
+* Séparée de l'écriture pour la même raison que `env`, `card` et `ai:sync` :
+* ce qui décide (que faut-il écrire ? est-ce déjà bon ?) s'éprouve sans toucher
+* au disque, donc se teste vraiment.
+*
+* ## Ce que ce fichier NE fait pas
+*
+* Il ne lance aucun serveur et n'en décrit aucun : le serveur MCP de Nodefony
+* est une **route** de l'application (`POST /nodefony/mcp`), servie par le
+* module `@nodefony/devkit`. Ce fichier ne produit que le **câblage** — le
+* papier qui dit à un agent où taper.
+*/
+/** Nom de la clé sous laquelle notre serveur est déclaré. */
+const MCP_SERVER_KEY = "nodefony";
+/** Fichier de configuration, à la racine du projet. */
+const MCP_CONFIG_FILE = ".mcp.json";
+/**
+* Nom de la variable d'environnement qui porte le jeton de la porte MCP.
+*
+* 🔴 C'est la VARIABLE qui s'écrit dans `.mcp.json`, jamais le jeton : ce
+* fichier est un fichier de projet, suivi par git. Les clients MCP développent
+* `${VAR}` à la lecture, donc le porteur reste dans l'environnement du poste et
+* ne peut pas partir dans un commit.
+*/
+const MCP_TOKEN_ENV = "NF_MCP_TOKEN";
+/**
+* Compose l'URL de l'endpoint MCP.
+*
+* @param origin - origine du serveur (`http://localhost:5151`)
+* @param endpointPath - chemin de l'endpoint, tel que le module le monte
+*/
+function buildMcpUrl(origin, endpointPath) {
+	return `${stripTrailingSlashes(origin)}${endpointPath}`;
+}
+/**
+* Décide ce qu'il faut écrire dans `.mcp.json`.
+*
+* ⭐ **Le document existant est PRÉSERVÉ**, et pas seulement par politesse :
+* un projet y déclare ses autres serveurs MCP, et une commande de câblage qui
+* les emporterait serait une commande qu'on n'ose plus lancer. Seule la clé
+* `nodefony` est posée ou mise à jour.
+*
+* L'idempotence est au sens FORT : une URL déjà correcte rend `inchange`, donc
+* l'appelant n'écrit pas — l'horodatage du fichier ne bouge pas, et l'arbre
+* reste propre.
+*
+* @param existing - document déjà présent, ou `null`
+* @param url - URL de l'endpoint à déclarer
+*/
+function planMcpConfig(existing, url, options = {}) {
+	const base = existing ? {
+		...existing,
+		mcpServers: { ...existing.mcpServers }
+	} : { mcpServers: {} };
+	const previous = base.mcpServers[MCP_SERVER_KEY];
+	const auth = options.auth === true ? true : options.auth === false ? false : Boolean(previous?.headers?.Authorization);
+	const entry = auth ? {
+		type: "http",
+		url,
+		headers: { Authorization: `Bearer \${${MCP_TOKEN_ENV}}` }
+	} : {
+		type: "http",
+		url
+	};
+	base.mcpServers[MCP_SERVER_KEY] = entry;
+	const authRemoved = Boolean(previous?.headers?.Authorization) && !entry.headers?.Authorization;
+	if (!previous) return {
+		action: "pose",
+		document: base,
+		url,
+		auth
+	};
+	const memeAuth = (previous.headers?.Authorization ?? null) === (entry.headers?.Authorization ?? null);
+	if (previous.url === url && previous.type === "http" && memeAuth) return {
+		action: "inchange",
+		document: base,
+		url,
+		auth
+	};
+	return {
+		action: "remplace",
+		document: base,
+		url,
+		auth,
+		previousUrl: previous.url,
+		...authRemoved ? { authRemoved: true } : {}
+	};
+}
+/**
+* URL des métadonnées de la porte protégée (RFC 9728) : le chemin bien connu
+* s'INSÈRE entre l'hôte et le chemin de la ressource, il ne s'y ajoute pas.
+*
+* @param url - URL de l'endpoint MCP
+* @returns l'URL du document de métadonnées
+*/
+function metadataUrlOf(url) {
+	try {
+		const u = new URL(url);
+		return `${u.origin}/.well-known/oauth-protected-resource${u.pathname}`;
+	} catch {
+		return `/.well-known/oauth-protected-resource`;
+	}
+}
+/**
+* Rend le plan pour un lecteur humain.
+*
+* Dit surtout **ce qui reste à faire** : écrire le fichier ne branche rien tant
+* que l'application ne tourne pas, et un agent déjà lancé ne relit pas sa
+* configuration. Taire ces deux conditions produirait le pire des retours — un
+* succès annoncé, suivi d'un outil introuvable.
+*/
+function renderMcpPlan(plan, file, dryRun) {
+	const verbe = plan.action === "pose" ? "posé" : plan.action === "remplace" ? "mis à jour" : "déjà à jour";
+	const lines = [dryRun ? `${file} — ${plan.action} (simulation, rien n'est écrit)` : `${file} — ${verbe}`, `  serveur « ${MCP_SERVER_KEY} » → ${plan.url}`];
+	if (plan.previousUrl && plan.previousUrl !== plan.url) lines.push(`  (remplaçait ${plan.previousUrl})`);
+	if (plan.authRemoved) lines.push(`  ⚠ l'en-tête Authorization a été RETIRÉ — la porte est redevenue anonyme.`, `    (le remettre : nodefony ai:mcp --auth)`);
+	lines.push("", "Pour que ça réponde :", "  1. l'application doit TOURNER (npm run dev) — le serveur MCP est une de ses routes ;", "  2. redémarre ton agent, il ne relit pas sa configuration en cours de route.");
+	if (plan.auth === true) {
+		const metadata = metadataUrlOf(plan.url);
+		lines.push("", `Mode AUTHENTIFIÉ — l'en-tête envoie \${${MCP_TOKEN_ENV}}, jamais un jeton écrit ici.`, `  1. la porte publie où prendre un jeton :  curl ${metadata}`, "     (champ `authorization_servers` — RFC 9728) ;", "  2. obtiens-en un, sans serveur ni mot de passe — l'application le SIGNE :", `       nodefony security:token --write     → pose NF_MCP_TOKEN chez tes agents`, "       nodefony security:token             (l'affiche, pour un export manuel)", "     Elle vise l'audience de la porte d'elle-même (RFC 8707) : un jeton", "     d'audience différente serait refusé, à juste titre ;", `  3. ou exporte-le à la main :             export ${MCP_TOKEN_ENV}=<access_token>`, "  4. un jeton d'accès EXPIRE — pose une durée qui tienne la journée :", "       nodefony security:token --write --ttl 10080   (7 jours)", "", "Sans jeton, la porte sert quand même ses outils publics — l'authentification", "ajoute les outils réservés, elle n'est pas un péage.");
+	}
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+export { MCP_CONFIG_FILE, MCP_SERVER_KEY, MCP_TOKEN_ENV, buildMcpUrl, metadataUrlOf, planMcpConfig, renderMcpPlan };