nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/Tools.d.ts

@@ -0,0 +1,116 @@
+import Container from "./Container.js";
+/** Alias direct de `Array.isArray` — exporté pour usage cohérent dans les modules. */
+declare const isArray: (arg: any) => arg is any[];
+/**
+ * Type guard — `true` si `value` est une fonction (incluant arrow et classes).
+ *
+ * @param value - valeur inconnue à tester.
+ */
+declare const isFunction: (value: unknown) => value is (...args: unknown[]) => unknown;
+/**
+ * Type guard — `true` si `value` est une instance `RegExp`.
+ *
+ * @param value - valeur inconnue à tester.
+ */
+declare const isRegExp: (value: unknown) => value is RegExp;
+/**
+ * Vérifie qu'un objet est un "plain object" — `{}` ou `Object.create(null)`.
+ *
+ * Rejette les instances de classes, les `Array`, `Date`, `RegExp`, etc.
+ * Implémentation alignée sur jQuery.isPlainObject (compatible cross-realm).
+ *
+ * @param obj - valeur à tester.
+ * @returns `true` si l'objet vient directement de `Object` ou n'a pas de prototype.
+ */
+declare const isPlainObject: (obj: unknown) => boolean;
+/**
+ * Type guard — `true` si `value === undefined` (strict, jamais `null`).
+ *
+ * @param value - valeur à tester.
+ */
+declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Vérifie qu'un objet existe et ne contient aucune clé propre énumérable.
+ *
+ * @param obj - objet à inspecter (peut être `null`/`undefined`).
+ * @returns `true` si `obj` est défini ET `Object.keys(obj).length === 0`.
+ */
+declare const isEmptyObject: (obj: object | null | undefined) => boolean;
+/**
+ * Fusionne plusieurs objets dans une cible — API compatible `jQuery.extend`.
+ *
+ * Mode `shallow` (défaut) : copie les clés du dernier au premier source.
+ * Mode `deep` (1er arg `true`) : récurse dans les plain objects et arrays.
+ * Sécurité : ignore `__proto__`, `constructor`, `prototype` (anti prototype pollution).
+ *
+ * @param args - `[target, ...sources]` ou `[true, target, ...sources]` pour deep.
+ * @returns la cible mutée (ou objet vide si appel à un seul argument).
+ *
+ * @example
+ * ```ts
+ * extend({ a: 1 }, { b: 2 });               // { a: 1, b: 2 }
+ * extend(true, { a: { x: 1 } }, { a: { y: 2 } }); // { a: { x: 1, y: 2 } }
+ * ```
+ */
+declare const extend: (...args: any[]) => any;
+declare const typeOf: (value: any) => string | null;
+/**
+ * Type guard — `true` si la valeur est une instance de `Container` (DI).
+ *
+ * @param container - valeur à tester.
+ */
+declare const isContainer: (container: unknown) => container is Container;
+/**
+ * Vérifie qu'une valeur est une `Promise` ou un thenable (duck-typing `.then`).
+ *
+ * Accepte les promesses natives ET les bibliothèques tierces (Bluebird, etc.)
+ * qui implémentent le protocole Promises/A+.
+ *
+ * @param obj - valeur à tester.
+ * @returns `true` si `obj instanceof Promise` ou `typeof obj.then === "function"`.
+ */
+declare const isPromise: (obj: any) => boolean;
+/**
+ * Vérifie qu'une classe hérite (directement ou non) d'une autre.
+ *
+ * @param subclass - classe enfant supposée.
+ * @param superclass - classe parent attendue.
+ * @returns `true` si `subclass.prototype instanceof superclass`.
+ */
+declare const isSubclassOf: (subclass: any, superclass: any) => boolean;
+/**
+ * Retire les barres obliques finales d'une chaîne, sans expression régulière.
+ *
+ * **Pourquoi pas `value.replace(/\/+$/, "")`** — la forme évidente, et celle qui
+ * était recopiée à cinq endroits. Elle est QUADRATIQUE quand la reconnaissance
+ * ÉCHOUE : le moteur reprend l'essai à chaque position, consomme la suite des
+ * barres, puis bute sur l'ancre de fin. Mesuré sur des barres suivies d'un
+ * caractère quelconque — 1 000 → 1,4 ms, 4 000 → 21 ms, 16 000 → **309 ms** ;
+ * la même entrée passe ici en 0 ms. Le cas qui RÉUSSIT, lui, coûte 0,03 ms :
+ * c'est l'échec qui est cher, et c'est le cas qu'une entrée hostile provoque.
+ *
+ * Deux propriétés utiles en chemin chaud : la lecture est en O(n) sans retour
+ * arrière, et **rien n'est alloué** quand il n'y a rien à couper — la chaîne
+ * d'origine est rendue telle quelle, là où `replace` alloue à chaque appel.
+ *
+ * @param value - la chaîne à normaliser (typiquement un chemin ou une URL).
+ * @returns la chaîne sans ses barres obliques finales ; la chaîne elle-même si elle n'en avait pas.
+ */
+declare const stripTrailingSlashes: (value: string) => string;
+/**
+ * Neutralise les métacaractères d'une chaîne destinée à être insérée dans une
+ * expression régulière, pour qu'elle n'y vaille que pour elle-même.
+ *
+ * **Pourquoi c'est ici** — le même motif était recopié à sept endroits, dans
+ * cinq paquets. Une liste de caractères recopiée est une liste qui diverge : il
+ * suffit qu'une copie oublie `|` pour qu'un littéral cesse d'être un littéral.
+ * `|` est d'ailleurs le plus coûteux à omettre, parce qu'il ne fait pas
+ * qu'élargir la reconnaissance : il DÉSANCRE. `new RegExp("^/a|b$")` ne
+ * reconnaît pas « /a ou /b » — il reconnaît « commence par /a » **ou** « finit
+ * par b », donc `/n/importe/quoi/b`.
+ *
+ * @param value - la chaîne à traiter comme un littéral.
+ * @returns la même chaîne, chaque métacaractère précédé d'une barre inverse.
+ */
+declare const escapeRegExp: (value: string) => string;
+export { extend, isEmptyObject, isPlainObject, isUndefined, isRegExp, isContainer, typeOf, isFunction, isArray, isPromise, isSubclassOf, stripTrailingSlashes, escapeRegExp, };

package/dist/types/bin/resolveLocalCli.d.ts

@@ -0,0 +1,49 @@
+/** Variable de garde : le CLI délégué ne délègue pas à son tour (anti-boucle). */
+export declare const DELEGATED_ENV: string;
+/** Trace la décision du lanceur sur stderr quand la variable vaut `1`. */
+export declare const DEBUG_ENV: string;
+/** Décision du lanceur : exécuter soi-même, ou passer la main au CLI de l'app. */
+export type TLocalCliDecision = {
+    /** Exécuter le CLI courant (celui qui tourne). */
+    delegate: null;
+    reason: "already-delegated" | "no-project" | "no-local-cli" | "same-package";
+    detail?: string;
+} | {
+    /** Chemin ABSOLU du binaire du projet à exécuter à la place. */
+    delegate: string;
+    reason: "local-cli";
+    projectRoot: string;
+    selfVersion: string | null;
+    localVersion: string | null;
+} | {
+    /** Le projet a un `nodefony` installé, mais son CLI est inutilisable. */
+    delegate: null;
+    reason: "local-cli-broken";
+    projectRoot: string;
+    detail: string;
+};
+/**
+ * Décide quel CLI Nodefony doit réellement s'exécuter : **celui de l'application**
+ * dès qu'on se trouve dans un projet, sinon celui qu'on a lancé.
+ *
+ * Pourquoi cette règle : le binaire installé en global (`npm i -g nodefony`) est
+ * la porte d'entrée du framework (c'est lui qui fait `create app`), mais sa version
+ * dérive de celle des applications déjà générées. Exécuter le CLI global **dans**
+ * une app reviendrait à piloter cette app avec un autre framework que celui de ses
+ * `node_modules` : configs, scaffolds et commandes de module peuvent diverger.
+ * La version qui fait autorité est donc toujours celle de l'application — comme le
+ * wrapper d'un projet (`gradlew`, `mvnw`) prime sur l'outil de la machine.
+ *
+ * Fonction PURE (aucun effet de bord, aucun `process`) : les entrées sont passées
+ * explicitement pour que la décision soit testable sans lancer de binaire.
+ *
+ * @param input.cwd - dossier courant, point de départ de la recherche du projet.
+ * @param input.selfDir - racine du paquet `nodefony` en train de s'exécuter.
+ * @param input.env - environnement (lu pour la garde anti-boucle).
+ * @returns la décision : `delegate` = chemin du binaire à charger, ou `null` pour soi.
+ */
+export declare function resolveLocalCli(input: {
+    cwd: string;
+    selfDir: string;
+    env?: Record<string, string | undefined>;
+}): TLocalCliDecision;

package/dist/types/bundler/index.d.ts

@@ -0,0 +1,66 @@
+import type { RolldownOptions, RolldownPluginOption } from "rolldown";
+export interface INodefonyRolldownOptions {
+    /** Liste `external` du package (deps runtime non bundlées). Le nom propre du paquet est ajouté d'office. */
+    external?: string[];
+    /**
+     * Externalise automatiquement toutes les `dependencies` + `peerDependencies` du
+     * `package.json` courant (défaut `false`). Mode recommandé pour une APPLICATION :
+     * son runtime vient de `node_modules`, rien à bundler. Les packages du framework
+     * gardent leur liste `external` explicite (auditée par `nodefony-check-externals`).
+     */
+    externalDeps?: boolean;
+    /** Entrées explicites — remplace le glob par défaut (`index.ts` + `nodefony/**∕*.ts`). */
+    input?: Record<string, string>;
+    /** Patterns glob des sources à préserver en modules (défaut `["nodefony/**∕*.ts"]`). */
+    globPatterns?: string[];
+    /** Sourcemaps de sortie (défaut `false`). */
+    sourcemap?: boolean;
+    /** Plugins additionnels (ex : `browserShim` du core). */
+    plugins?: RolldownPluginOption[];
+    /** Cible de résolution des builtins (défaut `"node"`). */
+    platform?: "node" | "browser" | "neutral";
+    /** Racine `preserveModulesRoot` (défaut `"."` — chemins relatifs au package). */
+    preserveModulesRoot?: string;
+    /** Dossier de sortie (défaut `"dist"`). */
+    outDir?: string;
+}
+/**
+ * Matcher `external` des packages Nodefony : exact-match ou préfixe `<nom>/`,
+ * SAUF pour `nodefony` (exact-match seulement — cf invariant en tête de fichier).
+ */
+export declare function nodefonyExternalMatcher(external: string[]): (id: string) => boolean;
+/**
+ * Treeshake commun : les externes sont sans effet de bord (équivalent
+ * `no-external`) SAUF `reflect-metadata`, dont le side-effect doit survivre.
+ */
+export declare const nodefonyTreeshake: {
+    moduleSideEffects: (id: string, isExternal: boolean) => boolean;
+};
+/**
+ * Construit la map d'entrées d'un package Nodefony : `index.ts` + toutes les sources
+ * `nodefony/**` (hors tests et `.d.ts`), nommées par chemin relatif — la sortie
+ * `preserveModules` reproduit l'arborescence source dans `dist/`.
+ *
+ * @remarks Les chemins sont ramenés à la grammaire POSIX **avant tout le reste**, car
+ *   `globSync` rend le séparateur NATIF. Deux conséquences sous Windows, sinon : la
+ *   clé devient un nom de sortie que personne ne reconnaît (`input["nodefony/src/x"]`
+ *   vaut `undefined`, le `dist/` d'un build Windows cesse de ressembler aux autres) ;
+ *   et surtout l'exclusion `(^|/)tests/` ne mord plus sur `nodefony\tests\…` — les
+ *   fichiers de test entrent alors dans le paquet publié, sans un mot. Une clé
+ *   d'entrée est un identifiant qui VOYAGE — vers rolldown, vers `dist/`, vers les
+ *   `exports` du `package.json` — pas un chemin qu'on ouvre.
+ */
+export declare function nodefonyInput(globPatterns?: string[], deps?: {
+    /** Expansion des motifs (défaut `globSync`). */
+    readonly glob?: (pattern: string) => string[];
+    /** Séparateur de la plateforme — injecté pour éprouver Windows d'ailleurs. */
+    readonly sep?: string;
+}): Record<string, string>;
+/**
+ * Config rolldown partagée d'un package ou d'une application Nodefony
+ * (bundle node ESM, `preserveModules`).
+ *
+ * @param opts - écarts par rapport au défaut (external, entrées, plugins)
+ * @returns la config rolldown complète, prête pour `export default`
+ */
+export declare function defineNodefonyRolldownConfig(opts?: INodefonyRolldownOptions): RolldownOptions;

package/dist/types/cli/agentTargets.d.ts

@@ -0,0 +1,378 @@
+/**
+ * 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.
+ */
+import { MCP_TOKEN_ENV } from "./aiMcpReport.js";
+/**
+ * Comment la porte MCP se déclare chez un agent.
+ *
+ * `fichier-projet` : l'agent lit lui-même le `.mcp.json` que `ai:mcp` écrit —
+ * il n'y a rien de plus à faire, et le refaire par sa CLI créerait une SECONDE
+ * déclaration, dans une autre portée, que plus rien ne tiendrait à jour.
+ *
+ * `cli` : l'agent ignore `.mcp.json` (constaté) et tient sa propre
+ * configuration — on lui parle par sa ligne de commande.
+ */
+export type VoieDeclaration = "fichier-projet" | "cli";
+/**
+ * Un agent de développement, et l'endroit où il lit ses variables.
+ *
+ * ⭐ **Cette table existe parce qu'aucun agent ne lit `.env.local`.** Ce fichier
+ * est celui de l'APPLICATION ; le client MCP, lui, résout ses variables dans son
+ * propre environnement ou dans SA configuration — et quand il n'y trouve rien,
+ * il envoie l'en-tête non substitué et reçoit un 401 qui accuse le jeton. Une
+ * heure de diagnostic pour une chaîne cohérente en apparence.
+ *
+ * Ajouter un agent = ajouter une ligne. Ce qui n'y est PAS reste dit en clair
+ * plutôt que deviné : poser un secret dans un fichier dont on n'a pas vérifié le
+ * comportement serait un pari, et c'est le porteur qui le paierait.
+ */
+export interface IAgentTarget {
+    /** Clé courte — ce que `--agent` accepte, et ce qu'une question propose. */
+    key: string;
+    /** Nom affiché. */
+    name: string;
+    /**
+     * Où vit sa configuration : dans le PROJET, ou dans le dossier de
+     * l'utilisateur. La distinction commande la garde appliquée — un fichier de
+     * projet peut se retrouver commité, celui de l'utilisateur non.
+     */
+    scope: "projet" | "utilisateur";
+    /** Ce dont la présence prouve que l'agent est utilisé — résolu selon `scope`. */
+    marker: string;
+    /** Fichier à écrire — relatif au projet, ou au dossier de l'agent. */
+    file: string;
+    /** Grammaire du fichier. */
+    forme: "json-env" | "dotenv";
+    /**
+     * Variable qui déplace le dossier de l'agent — `VIBE_HOME`, `CODEX_HOME`.
+     *
+     * Elle sert DEUX fois. À la lecture, elle dit où l'agent tient ses variables
+     * quand l'utilisateur l'a déplacé. À l'écriture, elle est ce qui donne une
+     * portée PROJET à une CLI qui n'en offre pas : pointée sur
+     * `<projet>/<marker>`, la commande de l'agent écrit son propre format dans
+     * le projet au lieu du foyer. Sa présence vaut donc capacité — un agent qui
+     * la porte peut être déclaré par projet ; les autres ne le peuvent pas.
+     */
+    home?: string;
+    /** Par quelle voie sa configuration apprend l'existence de la porte MCP. */
+    declaration: VoieDeclaration;
+    /** Exécutable de sa CLI — présent si et seulement si `declaration === "cli"`. */
+    bin?: string;
+    /**
+     * Arguments qui DÉCLARENT la porte, hors nom de l'exécutable.
+     *
+     * Rendus par une fonction plutôt que par un gabarit à trous : les quatre
+     * grammaires ne se ressemblent pas (positionnel chez l'un, `--url` chez
+     * l'autre, valeur de l'en-tête ici, NOM de la variable là), et un gabarit
+     * commun les aurait déformées toutes les quatre.
+     */
+    argvAdd?: (ctx: IDeclarationContext) => string[];
+    /** Arguments qui RETIRENT la déclaration. */
+    argvRemove?: () => string[];
+    /**
+     * Arguments qui LISTENT les serveurs déclarés, quand la CLI sait le faire.
+     *
+     * 🔴 Elle existe parce qu'un code de sortie ne prouve rien. Mesuré ici :
+     * `gemini mcp remove nodefony` répond « not found in project settings »,
+     * **sort en 0**, et laisse l'entrée que `gemini mcp add` venait d'écrire.
+     * Sans ce second regard, notre commande annonçait « déclaration retirée »
+     * sur une déclaration toujours en place — un mensonge qu'on ne découvre
+     * qu'en cherchant ailleurs.
+     *
+     * Absente chez un agent qui n'offre pas de lecture : on ne prétend alors
+     * rien, plutôt que de deviner.
+     */
+    argvList?: () => string[];
+    /**
+     * Ce qu'il reste à faire APRÈS une déclaration réussie, quand l'agent pose
+     * une condition de son cru.
+     *
+     * ⭐ Elle existe pour un cas CONSTATÉ : Gemini accepte la déclaration, la
+     * liste — et l'affiche `Disabled`, parce que le dossier n'est pas « de
+     * confiance » chez lui. Sans cette phrase, on obtient un succès annoncé suivi
+     * d'un outil qui n'apparaît nulle part : le pire retour possible, et une
+     * heure passée à soupçonner le jeton.
+     */
+    noteAfter?: string;
+    /**
+     * Le fichier d'instructions que cet agent lit **d'office**, et s'il s'agit
+     * d'`AGENTS.md` lui-même.
+     *
+     * ⭐ **Pourquoi cette colonne existe** : `AGENTS.md` est le standard — porté
+     * par l'**Agentic AI Foundation** (Linux Foundation), règle de précédence
+     * « le plus proche gagne ». Mais tous les agents ne le lisent pas : deux
+     * d'entre eux ouvrent un fichier À LEUR NOM et ne verront JAMAIS l'`AGENTS.md`
+     * d'une application, si bien qu'ils travaillent sans aucune instruction sans
+     * que rien ne le signale. Un POINTEUR à leur nom ferme le trou sans dupliquer
+     * la matière : un fichier à NOUS, dans notre projet — on ne touche pas à la
+     * configuration d'un outil tiers (même règle que la déclaration MCP, qui
+     * passe par SA CLI).
+     *
+     * `proof` ancre le fait dans le SOURCE de l'agent, pas dans sa
+     * documentation : c'est elle qui se re-vérifie le jour où l'un d'eux change
+     * d'avis, et la doc de l'un d'eux dit déjà autre chose que son code.
+     */
+    instructions: {
+        /** Nom du fichier lu d'office (relatif à la racine du projet). */
+        file: string;
+        /** `true` quand ce fichier EST `AGENTS.md` — rien à poser. */
+        natif: boolean;
+        /** Où le constater dans le source de l'agent (ou la mesure qui l'a établi). */
+        proof: string;
+    };
+}
+/** Ce qu'il faut savoir pour composer la déclaration chez un agent. */
+export interface IDeclarationContext {
+    /** URL absolue de la porte MCP (`http://localhost:5151/nodefony/mcp`). */
+    url: string;
+    /** Nom sous lequel le serveur est déclaré. */
+    name: string;
+    /** Nom de la variable qui porte le jeton — jamais le jeton lui-même. */
+    tokenEnv: string;
+}
+/**
+ * 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`.
+ */
+export declare const AGENT_TARGETS: readonly IAgentTarget[];
+/**
+ * Ce qu'il faut lancer — ou ne pas lancer — pour qu'un agent connaisse la porte.
+ *
+ * PURE : c'est la DÉCISION, le `spawn` n'est que de la plomberie. Rendre un plan
+ * plutôt que d'exécuter permet de l'afficher tel quel quand la CLI manque, et
+ * c'est ce qui fait du repli une vraie sortie et non un message d'excuse.
+ */
+export type IDeclarationPlan = {
+    voie: "fichier-projet";
+    /** Le fichier qui porte DÉJÀ la déclaration — rien à lancer. */
+    file: string;
+} | {
+    voie: "cli";
+    /** Exécutable à chercher dans le `PATH`. */
+    bin: string;
+    /** Ses arguments. */
+    argv: string[];
+};
+/**
+ * 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
+ */
+export declare function planAgentDeclaration(target: IAgentTarget, ctx: Pick<IDeclarationContext, "url" | "tokenEnv">, remove?: boolean): IDeclarationPlan;
+/**
+ * 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)
+ */
+export declare function renderPlanShell(plan: IDeclarationPlan): string;
+/**
+ * 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
+ */
+export declare function agentRoot(target: IAgentTarget, ctx: {
+    projectRoot: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+}): string;
+/**
+ * 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 ? »
+ */
+export declare function agentsPresents(ctx: {
+    projectRoot: string;
+    home?: string;
+    env?: Record<string, string | undefined>;
+    exists: (filePath: string) => boolean;
+}): IAgentTarget[];
+export declare function poseVariable(forme: IAgentTarget["forme"], current: string, key: string, value: string): string | Error;
+/**
+ * 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
+ */
+export declare function litVariable(forme: IAgentTarget["forme"], content: string, key: string): string | null;
+export declare function alreadyHasKey(forme: IAgentTarget["forme"], content: string, key: string): boolean;
+/**
+ * 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
+ */
+export declare function requestedAgents(raw: string | undefined): readonly IAgentTarget[] | undefined | Error;
+/**
+ * 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.
+ */
+export declare function pointeursInstructions(keys: readonly string[]): readonly {
+    file: string;
+    agents: readonly string[];
+}[];
+/** Ré-export de commodité — la table et la variable vont toujours ensemble. */
+export { MCP_TOKEN_ENV };