nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/aiSync.js

@@ -0,0 +1,323 @@
+import "./sysexits.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { findProjectRoot } from "./projectRoot.js";
+import { stripGlobalCliFlags } from "./globalFlags.js";
+import { SKILLS_DIR, planSync, renderPlan } from "./aiSyncReport.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+//#region src/cli/aiSync.ts
+/** La page d'aide — `nodefony ai:sync --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony ai:sync",
+	tagline: "installe dans ce projet les pointeurs vers les skills d'agent que livrent les paquets présents",
+	sections: [{
+		title: "CE QU'ELLE ÉCRIT",
+		paragraph: "Des POINTEURS, jamais une copie : le contenu des skills reste dans les paquets, où npm le met à jour. Elle écrit `.agents/skills/` et son miroir `.claude/skills/`, et n'y touche qu'aux entrées qu'elle a posées. Elle ne DÉMARRE pas l'application — elle répond donc dans un terminal qui n'a pas posé NODE_ENV."
+	}],
+	options: [
+		{
+			term: "--dry-run",
+			text: "le plan, sans rien écrire"
+		},
+		{
+			term: "--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:sync",
+		text: "pose les pointeurs manquants"
+	}, {
+		term: "nodefony ai:sync --dry-run",
+		text: "ce qu'elle ferait, avant de la laisser faire"
+	}],
+	exitCodes: [{
+		term: "66",
+		text: "aucune application ici (EX_NOINPUT)"
+	}]
+};
+/**
+* Les paquets d'où proviennent des skills.
+*
+* On scanne `node_modules/@nodefony/*` ET les modules LOCAUX de l'application
+* (`modules/<nom>`), pas seulement le devkit : rien dans la mécanique n'est
+* propre à un paquet, et un module tiers qui livre ses propres skills doit être
+* servi par la même commande. Coder `@nodefony/devkit` en dur aurait fait de
+* cette généralité un cas particulier, et obligé à toucher au cœur le jour où
+* quelqu'un d'autre en livre.
+*/
+/**
+* Les paquets que CE projet produit lui-même — ses espaces de travail.
+*
+* ⚠️ Ce n'est PAS « le paquet est un lien symbolique ». Une application créée
+* avec `--link` pointe elle aussi vers un checkout du framework, et elle, elle
+* VEUT ses pointeurs : elle consomme le framework sans le produire. Le
+* discriminant est la propriété — un paquet déclaré comme espace de travail
+* appartient à ce dépôt, sa source y est versionnée et éditable, et lui poser un
+* pointeur vers `node_modules` reviendrait à s'envoyer chercher le double de ce
+* qu'on a sous la main.
+*
+* Lecture volontairement tolérante : un `package.json` illisible ou sans
+* `workspaces` rend un ensemble vide — c'est le cas d'une application ordinaire,
+* et le comportement doit alors être exactement celui d'avant.
+*
+* @param projectRoot - racine du projet.
+* @returns les noms de paquets produits ici.
+*/
+function packagesBuiltByThisProject(projectRoot) {
+	const produced = /* @__PURE__ */ new Set();
+	let patterns;
+	try {
+		patterns = JSON.parse(readFileSync(path.join(projectRoot, "package.json"), "utf8")).workspaces;
+	} catch {
+		return produced;
+	}
+	const list = Array.isArray(patterns) ? patterns : Array.isArray(patterns?.packages) ? patterns.packages : [];
+	for (const pattern of list) {
+		if (typeof pattern !== "string") continue;
+		const etoile = pattern.endsWith("/*");
+		const base = path.join(projectRoot, etoile ? pattern.slice(0, -2) : pattern);
+		for (const folder of etoile ? listDir(base) : [""]) {
+			const dir = etoile ? path.join(base, folder) : base;
+			try {
+				const name = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8")).name;
+				if (typeof name === "string") produced.add(name);
+			} catch {}
+		}
+	}
+	return produced;
+}
+function packageRoots(projectRoot) {
+	const roots = [];
+	const scope = path.join(projectRoot, "node_modules", "@nodefony");
+	const producedHere = packagesBuiltByThisProject(projectRoot);
+	for (const name of listDir(scope)) {
+		if (name.startsWith(".")) continue;
+		if (producedHere.has(`@nodefony/${name}`)) continue;
+		roots.push({
+			dir: path.join(scope, name),
+			name: `@nodefony/${name}`
+		});
+	}
+	const locaux = path.join(projectRoot, "modules");
+	for (const name of listDir(locaux)) {
+		if (name.startsWith(".")) continue;
+		roots.push({
+			dir: path.join(locaux, name),
+			name
+		});
+	}
+	return roots;
+}
+/**
+* Le contenu d'un dossier, ou rien s'il n'existe pas.
+*
+* @param dir - chemin absolu.
+* @returns les entrées, ou `[]` — un dossier absent est un cas NORMAL ici.
+*/
+function listDir(dir) {
+	try {
+		return readdirSync(dir);
+	} catch {
+		return [];
+	}
+}
+/**
+* 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.
+*/
+function readSkillHeader(src) {
+	const block = /^---\r?\n([\s\S]*?)\r?\n---/u.exec(src);
+	if (block === null) return null;
+	const fm = block[1] ?? "";
+	const name = /^name:[ \t]*(\S.*)$/mu.exec(fm)?.[1]?.trim();
+	if (name === void 0 || name === "") return null;
+	let desc = /^description:[ \t]*(\S.*)$/mu.exec(fm)?.[1]?.trim() ?? "";
+	if (desc === "" || desc === ">" || desc === "|") desc = (/^description:[ \t]*[>|][^\n]*\n((?:[ \t]+\S[^\n]*\n?)+)/mu.exec(fm)?.[1] ?? "").split("\n").map((l) => l.trim()).filter(Boolean).join(" ");
+	return {
+		name,
+		summary: (/^(.*?[.!?])(\s|$)/u.exec(desc)?.[1] ?? desc).trim()
+	};
+}
+/**
+* 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.
+*/
+function discoverSkills(projectRoot) {
+	const out = [];
+	for (const pkg of packageRoots(projectRoot)) {
+		const skillsDir = path.join(pkg.dir, "skills");
+		for (const entry of listDir(skillsDir)) {
+			const md = path.join(skillsDir, entry, "SKILL.md");
+			if (!existsSync(md)) continue;
+			let header = null;
+			try {
+				header = readSkillHeader(readFileSync(md, "utf8"));
+			} catch {
+				continue;
+			}
+			if (header === null || header.name !== entry) continue;
+			out.push({
+				name: header.name,
+				packageName: pkg.name,
+				summary: header.summary,
+				source: path.relative(projectRoot, md).split(path.sep).join("/")
+			});
+		}
+	}
+	return out;
+}
+/**
+* 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.
+*/
+function readExistingPointers(projectRoot) {
+	const dir = path.join(projectRoot, ...SKILLS_DIR.split("/"));
+	const out = Object.create(null);
+	for (const entry of listDir(dir)) {
+		const md = path.join(dir, entry, "SKILL.md");
+		try {
+			out[entry] = readFileSync(md, "utf8");
+		} catch {}
+	}
+	return out;
+}
+/**
+* Analyse les arguments de `ai:sync`.
+*
+* @param argv - `process.argv` complet.
+* @returns les options, ou une erreur d'usage.
+*/
+function parseAiSyncArgv(argv) {
+	const args = stripGlobalCliFlags(argv.slice(2).filter((a) => a !== "ai:sync"));
+	let cwd = process.cwd();
+	let json = false;
+	let dryRun = false;
+	let help = false;
+	for (let i = 0; i < args.length; i += 1) {
+		const a = args[i];
+		if (a === "--help" || a === "-h") help = true;
+		else if (a === "--json") json = true;
+		else if (a === "--dry-run") dryRun = true;
+		else if (a === "--cwd") {
+			const v = args[i + 1];
+			if (v === void 0) return { error: "--cwd attend un chemin" };
+			cwd = path.resolve(v);
+			i += 1;
+		} else return { error: `option inconnue : ${a}` };
+	}
+	return {
+		cwd,
+		json,
+		dryRun,
+		help
+	};
+}
+/**
+* Pose dans un projet les pointeurs vers les skills livrés par les paquets
+* installés, et rend le plan de ce qui a été fait.
+*
+* C'est le geste ENTIER — découvrir, comparer, écrire — tel que l'exécutent ses
+* DEUX appelants : la commande `ai:sync` et le scaffold `create app`. Il vit ici
+* en un seul exemplaire : recopier la boucle d'écriture dans le scaffold aurait
+* produit deux gestes divergeant au premier réglage (format du pointeur, dossier
+* visé, condition de réécriture), et chacun aurait passé ses propres tests.
+*
+* @param projectRoot - racine de l'application, DÉJÀ résolue (la remontée par
+*   `findProjectRoot` appartient à l'appelant : le scaffold connaît sa cible,
+*   la commande doit la chercher).
+* @param dryRun - `true` pour calculer sans rien écrire.
+* @returns le plan, qu'il ait été appliqué ou non.
+*/
+/**
+* Ce fichier est-il un pointeur que cette commande a posé ?
+*
+* Le marqueur est celui que `renderPointer` écrit dans le frontmatter
+* (`nodefony-source-package`) : il DIT l'appartenance, là où une heuristique de
+* taille ou de contenu se tromperait un jour. Tout le reste — un skill écrit à
+* la main, un skill du dépôt lui-même — n'appartient pas à cette commande, et
+* ne se remplace pas.
+*
+* @param content - le fichier tel qu'il est sur le disque.
+* @returns `true` si la synchronisation peut le remplacer.
+*/
+function estUnPointeur(content) {
+	return content.includes("nodefony-source-package:");
+}
+function syncSkillPointers(projectRoot, dryRun = false) {
+	const plan = planSync(discoverSkills(projectRoot), readExistingPointers(projectRoot));
+	if (dryRun) return plan;
+	for (const skill of plan.skills) {
+		if (skill.action !== "inchange") {
+			const dest = path.join(projectRoot, ...skill.target.split("/"));
+			mkdirSync(path.dirname(dest), { recursive: true });
+			writeFileSync(dest, skill.content, "utf8");
+		}
+		const mirror = path.join(projectRoot, ...skill.mirrorTarget.split("/"));
+		let current = null;
+		try {
+			current = readFileSync(mirror, "utf8");
+		} catch {}
+		if (current !== null && !estUnPointeur(current)) {
+			plan.preserves.push(skill.mirrorTarget);
+			continue;
+		}
+		if (current !== skill.content) {
+			mkdirSync(path.dirname(mirror), { recursive: true });
+			writeFileSync(mirror, skill.content, "utf8");
+		}
+	}
+	return plan;
+}
+/**
+* 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).
+*/
+function runAiSyncCommand(argv) {
+	const parsed = parseAiSyncArgv(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:sync: aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant).\nPour en créer un :\n  npx nodefony create app mon-app\n");
+		return 66;
+	}
+	const plan = syncSkillPointers(projectRoot, parsed.dryRun);
+	process.stdout.write(parsed.json ? `${JSON.stringify(plan, null, 2)}\n` : renderPlan(plan, !parsed.dryRun));
+	return 0;
+}
+//#endregion
+export { discoverSkills, parseAiSyncArgv, readExistingPointers, readSkillHeader, runAiSyncCommand, syncSkillPointers };

package/dist/node/cli/aiSyncReport.js

@@ -0,0 +1,142 @@
+//#region src/cli/aiSyncReport.ts
+/**
+* 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.
+*/
+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.
+*/
+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.
+*/
+function renderPointer(skill) {
+	return `---
+name: ${skill.name}
+description: >
+  ${skill.summary}
+metadata:
+  nodefony-source-package: "${skill.packageName}"
+---
+
+# ${skill.name}
+
+> Ce fichier est un **pointeur**, posé par \`nodefony ai:sync\`. Le contenu vit
+> dans le paquet \`${skill.packageName}\` et se met à jour par \`npm update\` —
+> ne l'édite pas ici, l'édition serait écrasée et ne profiterait à personne.
+
+**Lis maintenant \`${skill.source}\`** : c'est la version qui correspond à la
+version du framework installée dans ce projet.
+`;
+}
+/**
+* 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.
+*/
+function planSync(decouverts, existing) {
+	const skills = [];
+	const delivered = /* @__PURE__ */ new Set();
+	for (const skill of [...decouverts].sort((a, b) => a.name.localeCompare(b.name))) {
+		delivered.add(skill.name);
+		const content = renderPointer(skill);
+		const current = existing[skill.name];
+		skills.push({
+			name: skill.name,
+			packageName: skill.packageName,
+			action: current === void 0 ? "pose" : current === content ? "inchange" : "remplace",
+			target: `${SKILLS_DIR}/${skill.name}/SKILL.md`,
+			mirrorTarget: `${CLAUDE_SKILLS_DIR}/${skill.name}/SKILL.md`,
+			content
+		});
+	}
+	const orphelins = Object.keys(existing).filter((name) => !delivered.has(name)).sort();
+	return {
+		directory: SKILLS_DIR,
+		skills,
+		orphelins,
+		preserves: []
+	};
+}
+/**
+* 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.
+*/
+function renderPlan(plan, applique) {
+	const lines = [];
+	const poses = plan.skills.filter((s) => s.action === "pose");
+	const replaced = plan.skills.filter((s) => s.action === "remplace");
+	const inchanges = plan.skills.filter((s) => s.action === "inchange");
+	lines.push(`\n  Skills d'agent — ${plan.directory} (miroir Claude Code : ${CLAUDE_SKILLS_DIR})\n`);
+	if (plan.skills.length === 0) {
+		lines.push("  Aucun skill trouvé dans les paquets installés.\n\n  Les skills sont livrés par les paquets Nodefony (dossier skills/).\n  Si tu attendais ceux du devkit :\n    npm install --save-dev @nodefony/devkit\n");
+		return lines.join("");
+	}
+	for (const s of plan.skills) {
+		const marque = s.action === "pose" ? "+" : s.action === "remplace" ? "~" : "=";
+		lines.push(`  ${marque} ${s.name.padEnd(24)} ${s.packageName}\n`);
+	}
+	for (const name of plan.orphelins) lines.push(`  ? ${name.padEnd(24)} plus livré par aucun paquet — à supprimer à la main\n`);
+	for (const target of plan.preserves) lines.push(`  ! ${target} existe déjà et n'est PAS un pointeur — conservé tel quel\n`);
+	lines.push(`\n  ${poses.length} posé(s) · ${replaced.length} mis à jour · ${inchanges.length} inchangé(s)` + (plan.orphelins.length > 0 ? ` · ${plan.orphelins.length} orphelin(s)` : "") + (plan.preserves.length > 0 ? ` · ${plan.preserves.length} conservé(s)` : "") + `\n`);
+	if (!applique) lines.push(`\n  Rien n'a été écrit (--dry-run).\n`);
+	else if (poses.length > 0 || replaced.length > 0) lines.push("\n  Ces fichiers sont faits pour être COMMITÉS : ton équipe et ton\n  intégration continue disposeront des mêmes skills.\n");
+	return lines.join("");
+}
+//#endregion
+export { CLAUDE_SKILLS_DIR, SKILLS_DIR, planSync, renderPlan, renderPointer };

package/dist/node/cli/card.js

@@ -0,0 +1,186 @@
+import "./sysexits.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { findProjectRoot } from "./projectRoot.js";
+import { stripGlobalCliFlags } from "./globalFlags.js";
+import { buildCard, renderCard } from "./cardReport.js";
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+//#region src/cli/card.ts
+/**
+* `nodefony card [--json]` — qui répond, et où aller ensuite.
+*
+* La PREMIÈRE commande qu'un agent (ou un humain) lance en arrivant dans une
+* application qu'il ne connaît pas. C'est ce qui décide de son placement :
+* standalone, comme `check` et `env`, elle ne lit que des fichiers.
+*
+* Ce qu'elle répare, mesuré sur le terrain, deux portes fermées au moment exact
+* où elle sert :
+*
+* 1. **Application NON CONSTRUITE** — le cas d'une app fraîchement générée, donc
+*    précisément celle où l'on cherche par où commencer. Faire booter la carte
+*    la rendait muette (`diagnoseUnbootableProject` répond « lance npm run
+*    build » à toute commande qui exige un Kernel).
+* 2. **`NODE_ENV` non posé** — la carte était portée par une commande du module
+*    `@nodefony/devkit`, `policy: "dev"`. Hors développement le module n'est pas
+*    chargé : la commande n'EXISTAIT pas, et le CLI répondait `unknown command`,
+*    sans piste. Une porte d'accueil qui disparaît selon l'environnement n'est
+*    pas une porte d'accueil.
+*
+* La contrepartie est ÉNONCÉE, jamais masquée : sans boot, on ne connaît que les
+* modules INSTALLÉS, pas les modules CHARGÉS (cf `renderCard`). La vérité
+* runtime reste à `npx nodefony inspect modules`, que la carte cite.
+*
+* La composition (`buildCard`) et le rendu (`renderCard`) vivent dans
+* `cli/cardReport.ts` : le module `@nodefony/devkit` les réutilise pour sa porte
+* HTTP, où le Kernel tourne et où la liste est celle des modules chargés. Une
+* source, deux portes.
+*/
+/** La page d'aide — `nodefony card --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony card",
+	tagline: "la carte de visite de cette application : où l'on est, ce qu'elle embarque, et quoi taper ensuite",
+	aliases: ["nodefony devkit:card"],
+	sections: [{
+		title: "CE QU'ELLE LIT",
+		paragraph: "Des fichiers, et rien d'autre : elle ne DÉMARRE pas l'application. Elle répond donc dans une application pas encore construite, et dans un terminal qui n'a pas posé NODE_ENV — les deux situations où l'on cherche précisément par où commencer. La contrepartie est écrite dans la carte : elle connaît les modules INSTALLÉS, pas les modules CHARGÉS. Pour ceux-là, `nodefony inspect modules`."
+	}],
+	options: [{
+		term: "-j, --json",
+		text: "la même carte, 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 card",
+		text: "la carte de l'application d'ici"
+	}, {
+		term: "nodefony card --json | jq .",
+		text: "la même, pour un script ou un agent"
+	}],
+	exitCodes: [{
+		term: "66",
+		text: "aucune application ici (EX_NOINPUT)"
+	}]
+};
+/**
+* Parse l'argv après le mot `card` (ou son alias).
+*
+* @param argv - `process.argv` complet.
+* @returns la demande, ou le motif du refus.
+*/
+function parseCardArgv(argv) {
+	const at = argv.findIndex((a) => a === "card" || a === "devkit:card");
+	const rest = stripGlobalCliFlags(at === -1 ? [] : argv.slice(at + 1));
+	let json = false;
+	let cwd = process.cwd();
+	let help = false;
+	for (let i = 0; i < rest.length; i++) {
+		const word = rest[i];
+		if (word === "--help" || word === "-h") help = true;
+		else if (word === "--json" || word === "-j") json = true;
+		else if (word === "--cwd") cwd = path.resolve(rest[++i] ?? "");
+		else return { error: `option inconnue : ${word}` };
+	}
+	return {
+		json,
+		cwd,
+		help
+	};
+}
+/** Lit un `package.json` sans jamais lever — absent ou illisible → `null`. */
+function readPackage(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+/** Liste les entrées d'un dossier sans jamais lever — absent → `[]`. */
+function listDir(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory() || e.isSymbolicLink()).map((e) => e.name);
+	} catch {
+		return [];
+	}
+}
+/**
+* Nom COURT d'un module à partir de son nom npm : `@nodefony/studio` → `studio`.
+*
+* C'est la clé du conteneur — celle que le Kernel expose dans `kernel.modules`,
+* et donc la seule qui permette à la carte froide et à la carte chaude de dire
+* la même chose du même module.
+*/
+function shortName(pkgName) {
+	const at = pkgName.lastIndexOf("/");
+	return at === -1 ? pkgName : pkgName.slice(at + 1);
+}
+/**
+* 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.
+*/
+function readColdCardInput(projectRoot, fallbackVersion) {
+	const appPkg = readPackage(path.join(projectRoot, "package.json"));
+	if (appPkg === null) return null;
+	const deps = {
+		...appPkg.dependencies,
+		...appPkg.devDependencies
+	};
+	const modules = new Set(Object.keys(deps).filter((name) => name.startsWith("@nodefony/")).map(shortName));
+	for (const name of listDir(path.join(projectRoot, "node_modules", "@nodefony"))) if (!name.startsWith(".")) modules.add(name);
+	for (const name of listDir(path.join(projectRoot, "modules"))) if (!name.startsWith(".")) modules.add(name);
+	const corePkg = readPackage(path.join(projectRoot, "node_modules", "nodefony", "package.json"));
+	const nodefonyVersion = typeof corePkg?.version === "string" ? corePkg.version : fallbackVersion;
+	return {
+		appName: typeof appPkg.name === "string" ? appPkg.name : "application",
+		appVersion: typeof appPkg.version === "string" ? appPkg.version : "0.0.0",
+		nodefonyVersion,
+		environment: process.env.NODE_ENV ?? "development",
+		modules: [...modules],
+		source: "static"
+	};
+}
+/**
+* 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).
+*/
+function runCardCommand(argv, fallbackVersion) {
+	const parsed = parseCardArgv(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("card: aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant).\nPour en créer un :\n  npx nodefony create app mon-app\n");
+		return 66;
+	}
+	const input = readColdCardInput(projectRoot, fallbackVersion);
+	if (input === null) {
+		process.stderr.write(`card: package.json illisible dans ${projectRoot}\n`);
+		return 66;
+	}
+	const card = buildCard(input);
+	process.stdout.write(parsed.json ? `${JSON.stringify(card, null, 2)}\n` : renderCard(card));
+	return 0;
+}
+//#endregion
+export { parseCardArgv, readColdCardInput, runCardCommand };