nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,239 @@
+import { type IMcpConfigDocument } from "./aiMcpReport.js";
+import { type IAgentTarget } from "./agentTargets.js";
+/** Ce que la ligne de commande demande. */
+interface IAiMcpRequest {
+    /** `true` si l'on veut seulement la page d'aide. */
+    help: boolean;
+    /** Origine forcée (`https://localhost:5152`), ou `null` pour la déduire. */
+    url: string | null;
+    /**
+     * Mode authentifié. `null` = ne rien décider — on conserve ce que le fichier
+     * porte déjà, pour qu'un rafraîchissement d'URL ne désarme pas la porte.
+     */
+    auth: boolean | null;
+    /**
+     * Agents à déclarer, tels que tapés. `undefined` = rien de demandé — en
+     * terminal on PROPOSE, ailleurs on ne touche à la configuration de personne.
+     */
+    agent: string | undefined;
+    /** Retirer la déclaration au lieu de la poser. */
+    remove: boolean;
+    /**
+     * Déclarer dans le foyer de l'utilisateur au lieu du projet.
+     *
+     * Le défaut est le PROJET : l'URL d'une porte porte un port, et une
+     * déclaration globale ne peut désigner qu'une application. Ce drapeau
+     * existe pour qui veut délibérément une porte valable partout — un poste
+     * qui n'ouvre jamais qu'un seul projet Nodefony, typiquement.
+     */
+    global: boolean;
+    dryRun: boolean;
+    json: boolean;
+    cwd: string;
+}
+/**
+ * Parse l'argv après le mot `ai:mcp`.
+ *
+ * @param argv - `process.argv` complet
+ * @returns la demande, ou le motif du refus
+ */
+export declare function parseAiMcpArgv(argv: string[]): IAiMcpRequest | {
+    error: string;
+};
+/**
+ * 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
+ */
+export declare function guessOrigin(cwd: string): string;
+/** Ce qu'il faut lancer pour obtenir le jeton, ou `null` s'il n'y a rien à faire. */
+export interface IChainedToken {
+    /** Arguments passés au binaire, après `node <bin>`. */
+    argv: string[];
+    /** Environnement du sous-process — hérité, `NODE_ENV` posé. */
+    env: Record<string, string | undefined>;
+    /** Répertoire de travail : la racine du PROJET, pas celui de l'appelant. */
+    cwd: string;
+}
+/**
+ * Décide s'il faut enchaîner sur `security:token`, et avec quoi.
+ *
+ * PURE — le `spawn` est de la plomberie, la DÉCISION est ce qui peut être faux.
+ * Trois choses ne « suivent » pas toutes seules d'un process à l'autre, et
+ * chacune a sa raison d'être ici :
+ *
+ *  - **l'environnement** : un sous-process ne reçoit que ce qu'on lui donne.
+ *    `NODE_ENV=development` est POSÉ, parce que la porte MCP est servie par un
+ *    module de développement — sans lui, l'émission échoue sur une audience que
+ *    l'application ne sert pas, ce qui est exactement l'erreur qu'on veut
+ *    éviter à l'utilisateur ;
+ *  - **le répertoire** : le jeton s'écrit dans le `.env.local` du PROJET, pas
+ *    dans celui d'où la commande a été tapée ;
+ *  - **le terminal** : sans lui, l'enfant ne pourrait poser aucune question et
+ *    échouerait en « aucun terminal pour le demander » — d'où le refus
+ *    d'enchaîner hors TTY plutôt qu'un échec en cascade.
+ *
+ * @param demande - ce que la ligne de commande a demandé
+ * @param contexte - racine du projet, présence d'un terminal, environnement
+ * @returns le plan d'exécution, ou `null` si l'on n'enchaîne pas
+ */
+/**
+ * Ce qu'on peut dire d'un jeton DÉJÀ posé, sans jamais le montrer.
+ *
+ * ⚠️ Le jeton part dans un en-tête STATIQUE que rien ne rafraîchit : quand il
+ * expire, le symptôme est un `401` sur la porte MCP — un refus qui accuse la
+ * configuration, l'audience ou le serveur, jamais l'échéance. Constater
+ * l'échéance AVANT de proposer d'en émettre un nouveau transforme une enquête
+ * en une ligne de texte.
+ *
+ * Lecture PURE de la charge utile (elle n'est pas chiffrée, seulement signée) :
+ * on ne vérifie pas la signature ici — ce n'est pas une décision d'accès, c'est
+ * un renseignement. La porte, elle, vérifie tout.
+ */
+export interface ITokenState {
+    /** Secondes restantes ; négatif s'il est expiré, `null` si sans échéance. */
+    remainingSeconds: number | null;
+    /** Scopes que le jeton porte, tels qu'il les déclare. */
+    scopes: string[];
+}
+/**
+ * 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.
+ */
+export declare function tokenState(token: string, nowSeconds: number): ITokenState | 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.
+ */
+export declare function renderTokenState(state: ITokenState | null): string;
+/**
+ * É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.
+ */
+export declare function agentTokenStates(targets: readonly IAgentTarget[], projectRoot: string, nowSeconds: number): Map<string, string>;
+export declare function planTokenChaining(request: Pick<IAiMcpRequest, "auth" | "dryRun" | "json">, context: {
+    projectRoot: string;
+    isTTY: boolean;
+    env?: Record<string, string | undefined>;
+    /**
+     * Durée de validité demandée, en minutes. Omise, l'émetteur applique son
+     * défaut de configuration.
+     *
+     * ⭐ Elle existe ici parce que le jeton part dans un en-tête STATIQUE :
+     * `.mcp.json` porte une valeur que personne ne rafraîchit. Le défaut de
+     * l'émetteur (15 min) est taillé pour un client qui sait renouveler ; ici,
+     * il condamne l'utilisateur à réémettre toutes les quinze minutes, en
+     * lisant chaque fois un 401 qui accuse le jeton à tort.
+     */
+    ttlMinutes?: number;
+    /**
+     * Scopes demandés à l'émetteur. Omis, la commande d'émission applique son
+     * défaut — la lecture seule.
+     */
+    scopes?: string;
+}): IChainedToken | null;
+/** Ce qu'il est advenu de la déclaration chez un agent. */
+export interface IDeclarationResult {
+    /** L'agent visé. */
+    target: IAgentTarget;
+    /**
+     * La déclaration a-t-elle été écrite DANS le projet ?
+     *
+     * Ne se déduit pas de `target.scope` — qui dit où l'agent lit ses VARIABLES,
+     * pas où sa porte est déclarée. Pour Vibe et Codex, les deux diffèrent : le
+     * jeton reste au foyer (un `.env` de projet se commite par accident), la
+     * porte va dans le projet (son URL porte un port).
+     */
+    inProject?: boolean;
+    /**
+     * `declare`/`retire` : sa CLI a répondu OK, et le contrôle le CONFIRME quand
+     * il est possible. `sans-effet` : elle a répondu OK, mais la porte est encore
+     * là (ou toujours absente) — mesuré chez l'un d'eux, et invisible autrement.
+     * `fichier-projet` : il lit déjà le `.mcp.json`, il n'y avait rien à lancer.
+     * `cli-absente` : l'outil n'est pas installé — la commande est rendue pour le
+     * jour où il le sera. `echec` : sa CLI a refusé, et c'est ELLE qui dit pourquoi.
+     */
+    state: "declare" | "retire" | "fichier-projet" | "cli-absente" | "echec" | "sans-effet";
+    /** La commande, telle qu'on peut la recopier. Vide pour `fichier-projet`. */
+    command: string;
+    /** Ce que la CLI a écrit quand elle a refusé. */
+    detail?: string;
+    /**
+     * `true` quand une déclaration du même nom, visant une AUTRE porte, était
+     * déjà là — donc qu'on vient de l'écraser.
+     *
+     * Le cas n'a rien de théorique : deux applications Nodefony sur le même poste
+     * écoutent deux ports, et chez un agent de portée utilisateur elles se
+     * disputent le même nom de serveur. Sans cette ligne, la seconde efface la
+     * première en silence.
+     */
+    replacesOtherUrl?: boolean;
+}
+/**
+ * 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
+ */
+export declare function declareToAgents(targets: readonly IAgentTarget[], ctx: {
+    url: string;
+    remove: boolean;
+    projectRoot: string;
+    /** Écrire dans le foyer de l'utilisateur au lieu du projet. */
+    global?: boolean;
+}): Promise<IDeclarationResult[]>;
+/**
+ * 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
+ */
+export declare function renderDeclarations(results: readonly IDeclarationResult[], remove: boolean): string;
+/** Lit le `.mcp.json` du projet, ou `null` s'il est absent ou illisible. */
+export declare function readMcpConfig(file: string): IMcpConfigDocument | 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)
+ */
+export declare function runAiMcpCommand(argv: string[]): Promise<number>;
+export {};

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

@@ -0,0 +1,113 @@
+/**
+ * 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é. */
+export declare const MCP_SERVER_KEY = "nodefony";
+/** Fichier de configuration, à la racine du projet. */
+export declare 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.
+ */
+export declare const MCP_TOKEN_ENV = "NF_MCP_TOKEN";
+/** Une entrée de serveur MCP en transport HTTP. */
+export interface IMcpServerEntry {
+    /** Transport — seul `http` est produit ici (cf `type` de la spec). */
+    type: "http";
+    /** URL absolue de l'endpoint. */
+    url: string;
+    /**
+     * En-têtes ajoutés à chaque requête. Posés uniquement en mode authentifié —
+     * la spécification MCP impose l'en-tête `Authorization` sur CHAQUE requête,
+     * pas seulement à la première.
+     */
+    headers?: Record<string, string>;
+}
+/** Le document `.mcp.json` dans son entier. */
+export interface IMcpConfigDocument {
+    mcpServers: Record<string, IMcpServerEntry>;
+    /** Tout ce que le projet y avait déjà mis est conservé tel quel. */
+    [key: string]: unknown;
+}
+/** Ce que la commande a décidé de faire. */
+export type McpConfigAction = "pose" | "remplace" | "inchange";
+/** Résultat de la composition — ce qu'on écrira, et pourquoi. */
+export interface IMcpConfigPlan {
+    action: McpConfigAction;
+    /** Document complet à écrire (identique à l'existant si `inchange`). */
+    document: IMcpConfigDocument;
+    /** URL retenue. */
+    url: string;
+    /** URL précédente, quand on remplace. */
+    previousUrl?: string;
+    /**
+     * `true` quand l'entrée précédente portait un en-tête d'autorisation que
+     * celle-ci n'a plus.
+     *
+     * 🔴 Sans cela, `nodefony ai:mcp` sans `--auth` RETIRAIT l'authentification
+     * configurée la veille en annonçant « remplaçait <la même URL> » — un
+     * remplacement qui ne remplace rien de visible, et une porte qui redevient
+     * anonyme sans que personne l'ait demandé. Une configuration qu'on enlève se
+     * NOMME.
+     */
+    authRemoved?: boolean;
+    /** `true` si l'entrée écrite porte l'en-tête d'autorisation. */
+    auth?: boolean;
+}
+/**
+ * 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
+ */
+export declare function buildMcpUrl(origin: string, endpointPath: string): string;
+/**
+ * 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
+ */
+export declare function planMcpConfig(existing: IMcpConfigDocument | null, url: string, options?: {
+    auth?: boolean;
+}): IMcpConfigPlan;
+/**
+ * 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
+ */
+export declare function metadataUrlOf(url: string): string;
+/**
+ * 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.
+ */
+export declare function renderMcpPlan(plan: IMcpConfigPlan, file: string, dryRun: boolean): string;

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

@@ -0,0 +1,68 @@
+import type { IAiSyncPlan, IDiscoveredSkill } from "./aiSyncReport.js";
+/**
+ * La première phrase de la `description` d'un `SKILL.md`.
+ *
+ * Volontairement écrit à la main plutôt que par un analyseur YAML : le cœur ne
+ * dépend d'aucune bibliothèque pour lire deux champs, et un `SKILL.md` non
+ * conforme doit être IGNORÉ, pas faire échouer la commande — la synchronisation
+ * ne juge pas la qualité des skills des autres.
+ *
+ * @param src - contenu complet du fichier.
+ * @returns `{ name, summary }`, ou `null` si le frontmatter est inexploitable.
+ */
+export declare function readSkillHeader(src: string): {
+    name: string;
+    summary: string;
+} | null;
+/**
+ * Découvre les skills livrés par les paquets installés.
+ *
+ * Un skill est un DOSSIER portant un `SKILL.md` — c'est la spécification, et
+ * c'est le seul critère retenu : ni le nom du paquet, ni un champ maison.
+ *
+ * @param projectRoot - racine de l'application.
+ * @returns les skills trouvés, dans l'ordre de découverte.
+ */
+export declare function discoverSkills(projectRoot: string): IDiscoveredSkill[];
+/**
+ * Ce que le dossier de découverte porte déjà : nom du skill → contenu.
+ *
+ * @param projectRoot - racine de l'application.
+ * @returns la table, vide si le dossier n'existe pas encore.
+ */
+export declare function readExistingPointers(projectRoot: string): Record<string, string>;
+/**
+ * Analyse les arguments de `ai:sync`.
+ *
+ * @param argv - `process.argv` complet.
+ * @returns les options, ou une erreur d'usage.
+ */
+export declare function parseAiSyncArgv(argv: string[]): {
+    cwd: string;
+    json: boolean;
+    dryRun: boolean;
+    help: boolean;
+} | {
+    error: string;
+};
+export declare function syncSkillPointers(projectRoot: string, dryRun?: boolean): IAiSyncPlan;
+/**
+ * Commande `nodefony ai:sync` — pose dans le projet les pointeurs vers les
+ * skills livrés par les paquets installés.
+ *
+ * Standalone (0 boot), et il le FAUT : la commande doit répondre dans un
+ * terminal qui n'a pas posé `NODE_ENV`. Portée par un module `policy: "dev"`,
+ * elle n'aurait tout simplement pas existé là — c'est exactement le défaut qui a
+ * fait remonter `card` dans le cœur, et il n'y a aucune raison de le repayer.
+ *
+ * ⚠️ Aucun `postinstall` ne l'appelle, volontairement : `--ignore-scripts` est
+ * courant (intégration continue, politiques d'entreprise), les scripts
+ * d'installation sont un vecteur d'attaque connu de l'écosystème npm, et écrire
+ * dans un dossier VERSIONNÉ à chaque installation produirait des différences
+ * surprises. Le scaffold pose les pointeurs à la création ; cette commande les
+ * remet à jour quand on le demande.
+ *
+ * @param argv - `process.argv` complet.
+ * @returns exit code sémantique (`OK`, `USAGE`, `NOINPUT` hors projet).
+ */
+export declare function runAiSyncCommand(argv: string[]): number;

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

@@ -0,0 +1,149 @@
+/**
+ * Composition PURE de la synchronisation des skills d'agent.
+ *
+ * Reçoit un état déjà lu (les skills découverts, ce que le projet porte déjà) et
+ * conclut : que poser, que remplacer, que laisser. Aucune lecture de disque,
+ * aucune écriture — c'est ce qui la rend éprouvable sans projet ni paquet
+ * installé, et ce qui garantit qu'elle ne peut rien inventer.
+ *
+ * La lecture et l'écriture vivent dans `aiSync.ts` ; la même séparation que
+ * `cardReport.ts` / `card.ts` et `envReport.ts` / `env.ts`.
+ */
+/**
+ * Un skill découvert dans un paquet installé.
+ */
+export interface IDiscoveredSkill {
+    /** Nom du skill — identique au dossier qui le contient (contrainte de la spec). */
+    name: string;
+    /** Paquet qui le livre, tel qu'il s'écrit dans un `import` (`@nodefony/devkit`). */
+    packageName: string;
+    /** Première phrase de sa `description`, pour l'afficher sans charger le corps. */
+    summary: string;
+    /**
+     * Chemin du `SKILL.md` source, RELATIF à la racine du projet et écrit en `/`.
+     *
+     * Il VOYAGE (il est écrit dans un fichier que d'autres outils liront) : il
+     * s'écrit donc en séparateurs POSIX, jamais avec ceux de la plateforme.
+     */
+    source: string;
+}
+/** Ce qu'il faut faire d'un skill, une fois comparé à ce que le projet porte. */
+export type SkillAction = "pose" | "remplace" | "inchange";
+/**
+ * Le geste décidé pour un skill, prêt à être exécuté ou affiché.
+ */
+export interface IPlannedSkill {
+    name: string;
+    packageName: string;
+    action: SkillAction;
+    /** Chemin du pointeur à écrire, relatif au projet, en `/`. */
+    target: string;
+    /**
+     * Chemin du MIROIR Claude Code (`CLAUDE_SKILLS_DIR`), même contenu.
+     *
+     * L'idempotence du miroir se juge sur SON fichier au moment d'écrire (pas
+     * sur `action`, qui ne parle que de la racine canonique) : un miroir absent
+     * sous un canonique inchangé doit quand même être posé.
+     */
+    mirrorTarget: string;
+    /** Contenu exact du pointeur — c'est lui qu'on écrit, tel quel. */
+    content: string;
+}
+/**
+ * Le plan complet, tel qu'il s'affiche et tel qu'il s'exécute.
+ */
+export interface IAiSyncPlan {
+    /** Dossier de découverte visé, relatif au projet, en `/`. */
+    directory: string;
+    skills: IPlannedSkill[];
+    /** Pointeurs présents dans le dossier que plus aucun paquet ne livre. */
+    orphelins: string[];
+    /**
+     * Fichiers que la synchronisation a REFUSÉ d'écraser — un `SKILL.md` déjà
+     * présent qui n'est pas un pointeur, donc écrit par quelqu'un.
+     *
+     * 🔴 Ils sont rendus pour être DITS. Un fichier préservé en silence laisse
+     * croire que le skill a été synchronisé alors qu'il ne l'est pas ; et
+     * l'écraser sans le dire détruit du travail — vécu : 385 lignes remplacées
+     * par un renvoi de neuf lignes, sans un mot.
+     */
+    preserves: string[];
+}
+/**
+ * Le dossier de découverte INTEROPÉRABLE.
+ *
+ * La spécification Agent Skills ne mandate AUCUN emplacement — elle ne définit
+ * que ce qu'un skill contient. La convention qui a émergé pour le partage entre
+ * clients est `.agents/skills/` : c'est la racine CANONIQUE, celle où vivent
+ * aussi la détection d'orphelins et l'inventaire.
+ *
+ * ⭐ **« La convention qui a émergé » n'est pas un pari : deux clients la
+ * lisent, et l'un des deux la PRÉFÈRE à son propre dossier.** Une convention
+ * qu'on affirme sans nommer qui l'honore est une croyance ; celle-ci est
+ * constatée au source de chaque client :
+ *
+ * | client | lit `.agents/skills` | preuve                                          |
+ * | ------ | -------------------- | ----------------------------------------------- |
+ * | vibe   | oui                  | `vibe/core/paths/_local_config_files.py` (`_AGENTS_SKILLS_SUBDIR`) |
+ * | gemini | oui, **en priorité** | `@google/gemini-cli` `bundle/docs/cli/skills.md` |
+ * | claude | non                  | mesuré — d'où {@link CLAUDE_SKILLS_DIR}         |
+ * | codex  | pas de skills        | rien dans son paquet (0.149.0)                  |
+ *
+ * Gemini est explicite sur la préférence : à niveau égal, « the `.agents/skills/`
+ * alias takes precedence over the `.gemini/skills/` directory ». Poser en plus
+ * un `skill_paths` dans la configuration d'un agent serait donc une SECONDE
+ * source pour la même règle — la racine canonique suffit, et c'est tout
+ * l'intérêt d'une convention.
+ */
+export declare const SKILLS_DIR = ".agents/skills";
+/**
+ * Le MIROIR pour Claude Code — parce que le pari « c'est aux clients d'ajouter
+ * `.agents/skills/` » a été MESURÉ perdu.
+ *
+ * Constaté sur une application générée (claude-code 2.1.238, mode headless) :
+ * les cinq pointeurs étaient posés dans `.agents/skills/`, et le champ `skills`
+ * de la session n'en listait AUCUN ; les mêmes fichiers recopiés dans
+ * `.claude/skills/` y apparaissaient tous. Un skill que le client dominant ne
+ * charge jamais n'existe pas — même motif que la porte MCP câblée sans
+ * `--mcp-config`. Le contenu reste rendu par `renderPointer`, en un seul
+ * exemplaire : deux racines, un écrivain, aucune divergence possible.
+ *
+ * ⚠️ Cette racine appartient d'abord à l'UTILISATEUR (ses propres skills y
+ * vivent) : la synchronisation n'y écrit QUE les pointeurs qu'elle livre, n'y
+ * détecte aucun orphelin et n'y supprime jamais rien.
+ */
+export declare const CLAUDE_SKILLS_DIR = ".claude/skills";
+/**
+ * Le pointeur écrit dans le projet.
+ *
+ * Il ne COPIE pas le skill : il le désigne. C'est ce qui fait que le contenu se
+ * met à jour par `npm update` sans qu'aucun fichier du projet ne soit réécrit —
+ * une copie, elle, mentirait six mois plus tard. Le corps reste court à dessein :
+ * l'agent charge d'abord les métadonnées de tous les skills, et seulement
+ * ensuite le corps de celui qu'il active.
+ *
+ * @param skill - le skill découvert.
+ * @returns le contenu complet du `SKILL.md` pointeur.
+ */
+export declare function renderPointer(skill: IDiscoveredSkill): string;
+/**
+ * Décide, pour chaque skill découvert, s'il faut poser, remplacer ou ne rien
+ * faire — et relève les pointeurs devenus orphelins.
+ *
+ * Un pointeur déjà identique n'est PAS réécrit : sans cette comparaison, chaque
+ * passage salirait l'arbre git de l'utilisateur avec des fichiers au contenu
+ * inchangé, et `ai:sync` deviendrait une commande qu'on hésite à lancer.
+ *
+ * @param decouverts - les skills livrés par les paquets installés.
+ * @param existing - ce que le dossier de découverte porte déjà : nom → contenu.
+ * @returns le plan, trié par nom pour que deux exécutions se comparent.
+ */
+export declare function planSync(decouverts: IDiscoveredSkill[], existing: Record<string, string>): IAiSyncPlan;
+/**
+ * Rend le plan pour un humain.
+ *
+ * @param plan - le plan calculé.
+ * @param applique - `false` quand rien n'a été écrit (`--dry-run`).
+ * @returns le texte à écrire sur la sortie standard.
+ */
+export declare function renderPlan(plan: IAiSyncPlan, applique: boolean): string;

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

@@ -0,0 +1,49 @@
+import { type ICardInput } from "./cardReport.js";
+/** Ce que la ligne de commande demande. */
+interface ICardRequest {
+    json: boolean;
+    /** Racine de recherche (défaut : le cwd). */
+    cwd: string;
+    /** `true` si l'on veut seulement la page d'aide. */
+    help: boolean;
+}
+/**
+ * Parse l'argv après le mot `card` (ou son alias).
+ *
+ * @param argv - `process.argv` complet.
+ * @returns la demande, ou le motif du refus.
+ */
+export declare function parseCardArgv(argv: string[]): ICardRequest | {
+    error: string;
+};
+/**
+ * Compose l'état de la carte à FROID : ce que des fichiers suffisent à établir.
+ *
+ * Que des lectures, aucune exécution : le `package.json` de l'application (nom,
+ * version, briques déclarées), celui du framework installé (sa version), puis le
+ * DISQUE — `node_modules/@nodefony/*` et `modules/*`, réunis aux déclarations.
+ *
+ * Ce sont des FAITS, là où lire les `use()` de `nodefony.config.ts` à
+ * l'expression régulière produirait une liste fausse dès qu'un appel est
+ * conditionnel, sans le dire. Ils restent des modules INSTALLÉS : ce qui sera
+ * réellement chargé dépend du gating `policy`/`when`, qui n'a pas encore eu lieu
+ * — d'où `source: "static"`, que le rendu annonce.
+ *
+ * @param projectRoot - racine de l'application (cf `findProjectRoot`).
+ * @param fallbackVersion - version du framework à afficher si l'application ne
+ *   l'a pas encore installé (celle du CLI qui répond).
+ * @returns l'état à passer à `buildCard`, ou `null` si le `package.json` de
+ *   l'application est illisible.
+ */
+export declare function readColdCardInput(projectRoot: string, fallbackVersion: string): ICardInput | null;
+/**
+ * Commande `nodefony card` — orchestre : résout le projet, lit l'état statique,
+ * délègue la composition au module pur, rend.
+ *
+ * @param argv - `process.argv` complet.
+ * @param fallbackVersion - version du CLI courant, affichée si l'application n'a
+ *   pas (encore) `nodefony` dans ses `node_modules`.
+ * @returns exit code sémantique (`OK`, `USAGE`, `NOINPUT` hors projet).
+ */
+export declare function runCardCommand(argv: string[], fallbackVersion: string): number;
+export {};