nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/startMenu.js

@@ -0,0 +1,496 @@
+import { MENU_GROUP_LABELS } from "./helpReport.js";
+//#region src/cli/startMenu.ts
+/**
+* Composition PURE du menu interactif `nodefony menu` — même patron que
+* `envReport`/`cardReport`/`aiSyncReport` : ce fichier reçoit l'état (contexte,
+* descriptions, commandes de module) et rend une structure neutre ; l'adaptateur
+* (`MenuCommand`) la traduit en prompts inquirer. Zéro I/O, zéro import lourd :
+* testable sans TTY et sans kernel.
+*
+* Deux règles tiennent ce menu :
+* - le RÉSUMÉ d'une entrée vient de `command.description()` (source unique,
+*   celle de `--help`) — jamais d'une copie locale qui divergerait ;
+* - le menu n'ajoute que ce qui n'existe nulle part ailleurs : le CONSEIL
+*   d'usage (`when`), affiché sous la liste pendant la navigation.
+*
+* Une commande absente de commander (retirée, renommée) sort du menu toute
+* seule : `describe()` rend `null` et l'entrée n'est pas émise.
+*/
+/**
+* Catalogue déclaratif du menu. L'ordre du tableau EST l'ordre d'affichage,
+* groupe par groupe. Ajouter une commande au menu = une entrée ici, rien
+* d'autre (le résumé et la disponibilité viennent de commander).
+*/
+/**
+* Le libellé de menu d'une intention — la MÊME taxonomie que l'aide.
+*
+* @param intention - un groupe de `HELP_GROUPS`.
+* @returns le libellé à afficher dans le menu.
+*/
+function menuGroup(intention) {
+	return MENU_GROUP_LABELS[intention];
+}
+const START_MENU_CATALOG = [
+	{
+		value: "development",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("LANCER"),
+			outside: null
+		},
+		when: "Pour coder : rechargement automatique à chaque sauvegarde, HMR côté front. Ctrl+C pour arrêter."
+	},
+	{
+		value: "production",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("LANCER"),
+			outside: null
+		},
+		when: "Le mode des conteneurs et des pods : premier plan, logs sur la sortie standard, arrêt gracieux sur SIGTERM."
+	},
+	{
+		value: "cluster",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("LANCER"),
+			outside: null
+		},
+		when: "Plusieurs workers isolés sur une même machine (bare-metal/VPS) — relance automatique d'un worker tombé."
+	},
+	{
+		value: "status",
+		contexts: ["project", "outside"],
+		group: {
+			project: menuGroup("LANCER"),
+			outside: "Machine"
+		},
+		when: "Qu'est-ce qui tourne ici ? Superviseur, serveurs, Vite, ports occupés — sans rien démarrer."
+	},
+	{
+		value: "stop",
+		contexts: ["project", "outside"],
+		group: {
+			project: menuGroup("LANCER"),
+			outside: "Machine"
+		},
+		when: "Arrête proprement tout runtime Nodefony de la machine (dev, prod, cluster) — remplace le pkill -9."
+	},
+	{
+		value: "doctor",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("COMPRENDRE"),
+			outside: null
+		},
+		when: "Diagnostic statique : marche même quand l'app ne démarre plus, et rapporte le bilan du dernier boot."
+	},
+	{
+		value: "inspect",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("COMPRENDRE"),
+			outside: null
+		},
+		when: "L'état RÉEL de l'app — ce qui est monté, pas ce que le code laisse croire. Sans ouvrir de port."
+	},
+	{
+		value: "env",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("COMPRENDRE"),
+			outside: null
+		},
+		when: "Chaque variable : sa valeur effective, le fichier .env qui l'a posée, et celles qui sont masquées ou inconnues."
+	},
+	{
+		value: "card",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("COMPRENDRE"),
+			outside: null
+		},
+		when: "La carte de visite : modules installés, où aller (docs, console d'admin), quoi lancer. Le point de départ."
+	},
+	{
+		value: "create",
+		contexts: ["project", "outside"],
+		group: {
+			project: menuGroup("GÉNÉRER ET CONSTRUIRE"),
+			outside: "Démarrer"
+		},
+		when: "Le wizard pose les questions puis génère un code conforme : ne rien écrire à la main qu'un générateur produit."
+	},
+	{
+		value: "build",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("GÉNÉRER ET CONSTRUIRE"),
+			outside: null
+		},
+		when: "Compile modules puis application. Le runtime charge dist/ : une route neuve n'existe qu'après ce geste."
+	},
+	{
+		value: "install",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("GÉNÉRER ET CONSTRUIRE"),
+			outside: null
+		},
+		when: "Installe les dépendances puis construit — le geste après un clone ou un changement de dépendances."
+	},
+	{
+		value: "outdated",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("GÉNÉRER ET CONSTRUIRE"),
+			outside: null
+		},
+		when: "Les dépendances en retard, agrégées par paquet — distingue une plage épinglée d'un simple npm update."
+	},
+	{
+		value: "git:hooks",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("AGENTS ET OUTILLAGE"),
+			outside: null
+		},
+		when: "Pose .githooks/ (pre-commit léger, pre-push verify) via git config natif — zéro dépendance, geste explicite."
+	},
+	{
+		value: "ai:sync",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("AGENTS ET OUTILLAGE"),
+			outside: null
+		},
+		when: "Pose les pointeurs vers les skills d'agent livrés par les paquets installés — à rejouer après un npm update."
+	},
+	{
+		value: "ai:mcp",
+		contexts: ["project"],
+		group: {
+			project: menuGroup("AGENTS ET OUTILLAGE"),
+			outside: null
+		},
+		when: "Déclare le serveur MCP de cette application à ton agent (.mcp.json) — --auth pour le mode authentifié."
+	},
+	{
+		value: "symbols",
+		contexts: ["project", "outside"],
+		group: {
+			project: menuGroup("COMPRENDRE"),
+			outside: "Comprendre"
+		},
+		when: "Cherche un symbole du framework : où il est défini, ce qu'il étend, ce que dit sa doc — sans ouvrir un fichier."
+	},
+	{
+		value: "man",
+		contexts: ["project", "outside"],
+		group: {
+			project: menuGroup("COMPRENDRE"),
+			outside: "Comprendre"
+		},
+		when: "Page de manuel du CLI, générée depuis les commandes réellement enregistrées."
+	},
+	{
+		value: "completion",
+		contexts: ["project", "outside"],
+		group: {
+			project: menuGroup("AGENTS ET OUTILLAGE"),
+			outside: "Machine"
+		},
+		when: "La complétion shell (bash, zsh, fish) : commandes, options et arguments au TAB."
+	}
+];
+/** Groupes, dans l'ordre d'affichage, par contexte. */
+const GROUP_ORDER = {
+	project: Object.values(MENU_GROUP_LABELS),
+	outside: ["Démarrer", "Machine"]
+};
+/**
+* Scripts npm que le menu sait proposer — les gestes qu'AUCUNE commande
+* nodefony ne porte (qualité, infra docker). Un script n'apparaît que s'il
+* existe dans le package.json du projet (`npmScripts`). La valeur émise est
+* préfixée `npm:` — l'adaptateur la déplie en `npm run <script>`.
+*/
+const NPM_SCRIPT_CATALOG = [
+	{
+		script: "verify",
+		summary: "typecheck + lint + tests + check",
+		group: "Qualité (npm run)",
+		when: "LA passe avant de dire « fait » : typecheck + lint + tests + check, dans cet ordre. Les tests seuls ne typecheckent rien."
+	},
+	{
+		script: "test",
+		summary: "tests unitaires (vitest)",
+		group: "Qualité (npm run)",
+		when: "Les tests unitaires du projet (vitest). Rapides — le boot réel vit dans test:e2e."
+	},
+	{
+		script: "test:integration",
+		summary: "tests d'intégration (serveur réel)",
+		group: "Qualité (npm run)",
+		when: "Les suites qui frappent un serveur RÉEL. Plus lentes que les unitaires, plus rapides que l'e2e complet — et elles voient ce qu'un mock ne verra jamais."
+	},
+	{
+		script: "test:e2e",
+		summary: "build + boot réel + HTTP/WS",
+		group: "Qualité (npm run)",
+		when: "Le gate LENT : build, boot réel, HTTP/WS de bout en bout. À jouer avant de livrer, pas à chaque sauvegarde."
+	},
+	{
+		script: "test:memory",
+		summary: "seuils de heap (fuites)",
+		group: "Qualité (npm run)",
+		when: "Le gate MÉMOIRE : 1000 requêtes, 100 crashs, 100 connexions WS, et les seuils de heap. À lancer avant tout commit qui touche le pipeline de requête — une fuite ne se voit dans aucun autre test."
+	},
+	{
+		script: "test:all",
+		summary: "docker + build + tout, et le rapport",
+		group: "Qualité (npm run)",
+		when: "TOUT, dans l'ordre, en démarrant l'infra manquante — et surtout : il DIT ce qu'il n'a PAS testé. Un « vert » qui cache des suites sautées est le piège le plus coûteux du dépôt."
+	},
+	{
+		script: "typecheck",
+		summary: "types seuls (tsgo --noEmit)",
+		group: "Qualité (npm run)",
+		when: "Les types SEULS, sans rien exécuter. Indispensable parce que des tests verts ne typecheckent RIEN : une suite peut passer sur du code qui ne compile pas chez celui qui l'installe."
+	},
+	{
+		script: "lint",
+		summary: "style et pièges (oxlint)",
+		group: "Qualité (npm run)",
+		when: "Style et pièges (oxlint) — ce que ni le compilateur ni les tests ne voient."
+	},
+	{
+		script: "format",
+		summary: "reformate tout (prettier)",
+		group: "Qualité (npm run)",
+		when: "Reformate tout le projet (prettier --write)."
+	},
+	{
+		script: "clean",
+		summary: "supprime dist/",
+		group: "Qualité (npm run)",
+		when: "Efface `dist/`. À faire après un merge ou un renommage d'export : le runtime charge le BUILD, et un dist périmé rend des 404 sur des routes qui existent — la cause perdue n°1."
+	},
+	{
+		script: "see",
+		summary: "regarde l'écran (et le MESURE)",
+		group: "Qualité (npm run)",
+		when: "Ouvre la page dans un navigateur piloté : contrastes CALCULÉS, arbre d'accessibilité, console, requêtes réelles. Pour CONSTATER un rendu au lieu de le supposer."
+	},
+	{
+		script: "audit:web",
+		summary: "audit Lighthouse + accessibilité",
+		group: "Qualité (npm run)",
+		when: "Audit complet d'une page servie : performance, accessibilité (axe), bonnes pratiques. Plus lourd que `see` — pour une revue, pas pour une boucle de dev."
+	},
+	{
+		script: "infra:up",
+		summary: "docker compose up -d",
+		group: "Infra (docker)",
+		when: "Démarre les conteneurs déclarés par le projet (base SQL, redis…) — à lancer AVANT le serveur s'ils sont requis."
+	},
+	{
+		script: "infra:down",
+		summary: "docker compose down",
+		group: "Infra (docker)",
+		when: "Arrête et retire les conteneurs du projet."
+	}
+];
+/** Préfixe des valeurs « script npm » émises par le menu. */
+const NPM_SCRIPT_PREFIX = "npm:";
+/** Titre du groupe des commandes de module (projet seulement). */
+const MODULE_COMMANDS_GROUP = "Commandes du projet";
+/**
+* Le plan d'exécution d'un choix de menu.
+*
+* ⚠️ **Une commande de MODULE ne peut pas s'exécuter dans le process du menu.**
+* Le menu s'ouvre à `onStart` pour rester instantané ; à cette phase, les
+* commandes de module ne sont pas encore posées dans commander (elles le sont à
+* `onPreRegister`, par le dispatch différé). Les exécuter par le re-parse
+* commander donnait donc `unknown command 'http:network'` + CRITIC + exit 1 —
+* un menu qui PROPOSE un geste puis le refuse. Elles se relancent dans un
+* process neuf, exactement comme le menu le fait déjà pour un script npm : le
+* boot complet a lieu, le dispatch différé fait son travail.
+*
+* La décision vit ici, PURE, parce qu'elle se teste : l'adaptateur ne fait plus
+* que `spawnSync` ou appeler commander, gestes qu'aucun test unitaire n'observe.
+*
+* @param response - la valeur choisie dans le menu.
+* @param isBuiltin - commander connaît-il cette commande à cet instant ?
+*/
+function planMenuAction(response, isBuiltin) {
+	if (response.startsWith("npm:")) return {
+		kind: "npm",
+		script: response.slice(4)
+	};
+	const argv = response.split(" ").filter(Boolean);
+	return isBuiltin(argv[0] ?? "") ? {
+		kind: "inline",
+		argv
+	} : {
+		kind: "respawn",
+		argv
+	};
+}
+function choice(value, summary, when) {
+	return {
+		kind: "choice",
+		label: value,
+		summary,
+		value,
+		description: when
+	};
+}
+/**
+* Construit le menu principal pour un contexte donné.
+*
+* @returns message d'accueil + items ordonnés (separators de groupe inclus).
+*/
+function buildStartMenu(input) {
+	const context = input.inProject ? "project" : "outside";
+	const items = [];
+	for (const groupTitle of GROUP_ORDER[context]) {
+		const entries = START_MENU_CATALOG.filter((e) => e.contexts.includes(context) && e.group[context] === groupTitle);
+		const rendered = [];
+		const vues = /* @__PURE__ */ new Set();
+		for (const entry of entries) {
+			const summary = input.describe(entry.value);
+			if (summary === null) continue;
+			vues.add(entry.value);
+			rendered.push(choice(entry.value, summary, entry.when));
+		}
+		if (context === "project") for (const cmd of input.builtinCommands ?? []) {
+			if (vues.has(cmd.name)) continue;
+			if ((cmd.requiredArgs ?? 0) > 0) continue;
+			if (!cmd.group || MENU_GROUP_LABELS[cmd.group] !== groupTitle) continue;
+			vues.add(cmd.name);
+			rendered.push(choice(cmd.name, cmd.description, "Commande intégrée du CLI — `nodefony <commande> --help` en dit plus."));
+		}
+		if (rendered.length > 0) {
+			items.push({
+				kind: "separator",
+				label: groupTitle
+			});
+			items.push(...rendered);
+		}
+	}
+	if (context === "project" && input.npmScripts?.length) {
+		const available = new Set(input.npmScripts);
+		const byGroup = /* @__PURE__ */ new Map();
+		for (const entry of NPM_SCRIPT_CATALOG) {
+			if (!available.has(entry.script)) continue;
+			const item = {
+				kind: "choice",
+				label: entry.script,
+				summary: entry.summary,
+				value: `${NPM_SCRIPT_PREFIX}${entry.script}`,
+				description: entry.when
+			};
+			const bucket = byGroup.get(entry.group);
+			if (bucket) bucket.push(item);
+			else byGroup.set(entry.group, [item]);
+		}
+		for (const [groupTitle, groupItems] of byGroup) {
+			items.push({
+				kind: "separator",
+				label: groupTitle
+			});
+			items.push(...groupItems);
+		}
+	}
+	if (context === "project") {
+		if (input.moduleCommands?.length) {
+			const byGroup = /* @__PURE__ */ new Map();
+			for (const mc of input.moduleCommands) {
+				const title = (mc.group && MENU_GROUP_LABELS[mc.group]) ?? "Commandes du projet";
+				const item = {
+					kind: "choice",
+					label: mc.name,
+					summary: mc.description,
+					value: mc.name,
+					description: "Commande apportée par un module de cette application (relue du dernier démarrage dev)."
+				};
+				const bucket = byGroup.get(title);
+				if (bucket) bucket.push(item);
+				else byGroup.set(title, [item]);
+			}
+			const order = [...Object.values(MENU_GROUP_LABELS), MODULE_COMMANDS_GROUP];
+			for (const title of order) {
+				const groupItems = byGroup.get(title);
+				if (!groupItems?.length) continue;
+				items.push({
+					kind: "separator",
+					label: title
+				});
+				items.push(...groupItems);
+			}
+		}
+	}
+	const missing = input.inProject && !input.moduleCommands?.length;
+	return {
+		message: input.inProject ? `${input.projectName ?? "Projet Nodefony"} — que veux-tu faire ?${missing ? " (commandes des modules non listées : l'app n'a pas encore démarré ici — `nodefony --help` les montre toutes)" : ""}` : "Aucun projet Nodefony ici — que veux-tu faire ?",
+		items
+	};
+}
+/**
+* Sous-menu des sujets d'`inspect`, dérivé de la table SOURCE
+* (`INSPECT_SUBJECTS`) : seuls les sujets SANS argument obligatoire sont
+* proposés (un sujet à paramètre exigerait une saisie de plus — il reste
+* accessible en ligne de commande, l'aide d'`inspect` les liste).
+*
+* @param subjects - la table `INSPECT_SUBJECTS` (injectée : ce fichier reste pur).
+*/
+function buildInspectMenu(subjects) {
+	const items = [];
+	for (const [name, subject] of Object.entries(subjects)) {
+		if (subject.param) continue;
+		items.push({
+			kind: "choice",
+			label: name,
+			summary: subject.summary,
+			value: name,
+			description: `nodefony inspect ${name} — même donnée que la console d'admin, redaction des secrets comprise.`
+		});
+	}
+	return {
+		message: "Inspecter quoi ?",
+		items
+	};
+}
+/**
+* Filtre le menu à la frappe (prompt `search`) — la logique est ICI, pure et
+* testée : normalisation (minuscules, accents retirés), chaque MOT du terme
+* doit se retrouver dans le label, le résumé, le conseil OU le titre du groupe
+* de l'entrée. Les titres de groupe suivent leurs entrées : un groupe dont
+* rien ne survit disparaît AVEC son titre.
+*/
+function filterStartMenu(items, term) {
+	const normalize = (text) => text.toLowerCase().normalize("NFD").replace(/\p{Diacritic}/gu, "");
+	const words = normalize(term).split(/\s+/).filter(Boolean);
+	if (words.length === 0) return items;
+	const kept = [];
+	let pendingGroup = null;
+	let currentGroupLabel = "";
+	for (const item of items) {
+		if (item.kind === "separator") {
+			pendingGroup = item;
+			currentGroupLabel = item.label;
+			continue;
+		}
+		const haystack = normalize(`${item.label} ${item.summary} ${item.description} ${currentGroupLabel}`);
+		if (words.every((w) => haystack.includes(w))) {
+			if (pendingGroup) {
+				kept.push(pendingGroup);
+				pendingGroup = null;
+			}
+			kept.push(item);
+		}
+	}
+	return kept;
+}
+//#endregion
+export { MODULE_COMMANDS_GROUP, NPM_SCRIPT_CATALOG, NPM_SCRIPT_PREFIX, START_MENU_CATALOG, buildInspectMenu, buildStartMenu, filterStartMenu, planMenuAction };

package/dist/node/cli/symbols.js

@@ -0,0 +1,205 @@
+import "./sysexits.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { findProjectRoot } from "./projectRoot.js";
+import { stripGlobalCliFlags } from "./globalFlags.js";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+//#region src/cli/symbols.ts
+/**
+* Le GRAPHE SYMBOLIQUE du framework — où le trouver, et comment l'interroger.
+*
+* `.ai/symbols.json` répond en O(1) à « que fait ce symbole, où est-il défini,
+* qui l'étend » — sans ouvrir un `.d.ts` ni parcourir des sources. C'est l'outil
+* qui évite à un agent de deviner ; encore faut-il qu'il EXISTE là où il
+* travaille.
+*
+* ## Le trou que ce fichier ferme
+*
+* Le graphe était produit à la racine du dépôt et lu là uniquement. Dans une
+* application installée depuis npm, ce fichier n'existe pas : la lecture rendait
+* une liste vide, sans rien dire. Le graphe est désormais **publié par le
+* paquet `nodefony`** — une application qui l'installe reçoit celui de tout le
+* framework, quelle que soit la combinaison de paquets qu'elle a choisie.
+*
+* La résolution essaie donc, dans l'ordre : le graphe du PROJET (cas du dépôt de
+* développement, où il est plus frais que tout), puis celui du framework
+* INSTALLÉ. Jamais un chemin en dur : c'est ce qui l'avait cassé.
+*/
+/** Emplacement conventionnel, relatif à une racine. */
+const GRAPH_RELATIVE = path.join(".ai", "symbols.json");
+/**
+* Trouve le graphe symbolique utilisable depuis `from`.
+*
+* @param from - dossier de départ (typiquement le cwd).
+* @returns le chemin du fichier, ou `null` si aucun graphe n'est atteignable.
+*/
+function resolveSymbolsFile(from) {
+	const root = findProjectRoot(from) ?? from;
+	const local = path.join(root, GRAPH_RELATIVE);
+	if (existsSync(local)) return local;
+	const shipped = path.join(root, "node_modules", "nodefony", GRAPH_RELATIVE);
+	if (existsSync(shipped)) return shipped;
+	return null;
+}
+/**
+* Lit le graphe, ou `null` s'il est absent ou illisible.
+*
+* Ne lève jamais : un outil de découverte qui tombe sur un fichier corrompu doit
+* le DIRE à son appelant, pas interrompre ce qu'il diagnostiquait.
+*
+* @param from - dossier de départ de la résolution.
+*/
+function readSymbolsGraph(from) {
+	const file = resolveSymbolsFile(from);
+	if (file === null) return null;
+	try {
+		const parsed = JSON.parse(readFileSync(file, "utf8"));
+		return parsed.symbols ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Trouve un symbole par son nom exact.
+*
+* Le graphe indexe par nom, sauf pour les **homonymes** qu'il range sous
+* `Module:Nom` — d'où le second passage, qui les rattrape. Extrait ici parce
+* que la commande n'est plus le seul lecteur : le serveur MCP interroge le même
+* graphe, et deux résolutions d'homonymes finiraient par différer.
+*
+* @param graph - le graphe déjà lu
+* @param name - nom exact recherché
+* @returns l'entrée, ou `undefined`
+*/
+function lookupSymbol(graph, name) {
+	return graph.symbols[name] ?? Object.values(graph.symbols).find((s) => s.name === name);
+}
+/** La page d'aide — `nodefony symbols --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony symbols",
+	tagline: "interroge le graphe symbolique : où un symbole est défini, ce qu'il fait, et de qui il hérite",
+	synopsis: ["nodefony symbols [<Symbole>] [options]"],
+	sections: [{
+		title: "CE QU'ELLE LIT",
+		paragraph: "Un fichier JSON — le graphe engendré par le dépôt — et rien d'autre. Sans nom de symbole, elle rend un résumé du graphe. Elle ne DÉMARRE pas l'application : elle répond donc quand celle-ci ne démarre plus, le moment où l'on cherche justement ce que fait une classe."
+	}],
+	options: [
+		{
+			term: "-j, --json",
+			text: "la même réponse, exploitable par un script"
+		},
+		{
+			term: "-m, --module <nom>",
+			text: "n'afficher qu'un paquet"
+		},
+		{
+			term: "--cwd <chemin>",
+			text: "point de départ (la racine de l'app est résolue en remontant)"
+		}
+	],
+	examples: [
+		{
+			term: "nodefony symbols",
+			text: "ce que contient le graphe"
+		},
+		{
+			term: "nodefony symbols Kernel",
+			text: "où Kernel est défini, et sa parenté"
+		},
+		{
+			term: "nodefony symbols -m @nodefony/http",
+			text: "les symboles d'un seul paquet"
+		}
+	],
+	exitCodes: [{
+		term: "66",
+		text: "aucun graphe ici — le dépôt ne l'a pas engendré (EX_NOINPUT)"
+	}]
+};
+/**
+* Parse l'argv après le mot `symbols`.
+*
+* @param argv - `process.argv` complet.
+* @returns la demande, ou le motif du refus.
+*/
+function parseSymbolsArgv(argv) {
+	const at = argv.indexOf("symbols");
+	const rest = stripGlobalCliFlags(at === -1 ? [] : argv.slice(at + 1));
+	const req = {
+		name: null,
+		json: false,
+		module: null,
+		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 === "--json" || word === "-j") req.json = true;
+		else if (word === "--module" || word === "-m") req.module = rest[++i] ?? null;
+		else if (word === "--cwd") req.cwd = path.resolve(rest[++i] ?? "");
+		else if (word.startsWith("-")) return { error: `option inconnue : ${word}` };
+		else if (req.name === null) req.name = word;
+		else return { error: `argument en trop : ${word}` };
+	}
+	return req;
+}
+/** Rend un symbole pour un lecteur humain — une ligne d'identité, puis la parenté. */
+function renderSymbol(sym) {
+	const lines = [`${sym.name} — ${sym.kind} (${sym.module})`, `  ${sym.file}${sym.line ? `:${sym.line}` : ""}`];
+	if (sym.description) lines.push(`  ${sym.description}`);
+	if (sym.extends) lines.push(`  étend      : ${sym.extends}`);
+	if (sym.implements?.length) lines.push(`  implémente : ${sym.implements.join(", ")}`);
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Commande `nodefony symbols` — le graphe, sans boot et sans dépôt.
+*
+* Trois usages, du plus fréquent au plus rare : un nom (« qu'est-ce que
+* `AbstractCrudService` ? »), un paquet (`--module @nodefony/http` : sa surface
+* exportée), rien (le résumé — d'où vient le graphe, ce qu'il couvre).
+*
+* @param argv - `process.argv` complet.
+* @returns exit code sémantique (`OK`, `USAGE`, `NOINPUT` si aucun graphe,
+*   `DATAERR` si le symbole demandé est introuvable).
+*/
+function runSymbolsCommand(argv) {
+	const parsed = parseSymbolsArgv(argv);
+	if ("error" in parsed) return printUsageError(PAGE, parsed.error);
+	if (parsed.help) return printUsage(PAGE);
+	const file = resolveSymbolsFile(parsed.cwd);
+	const graph = readSymbolsGraph(parsed.cwd);
+	if (graph === null) {
+		process.stderr.write("symbols: aucun graphe symbolique atteignable.\n  Il est publié par le paquet nodefony (node_modules/nodefony/.ai/symbols.json)\n  et régénérable dans ce dépôt par : npm run generate-symbols\n");
+		return 66;
+	}
+	if (parsed.name !== null) {
+		const sym = lookupSymbol(graph, parsed.name);
+		if (!sym) {
+			process.stderr.write(`symbols: « ${parsed.name} » est introuvable dans le graphe (${Object.keys(graph.symbols).length} symboles).\n`);
+			return 65;
+		}
+		process.stdout.write(parsed.json ? `${JSON.stringify(sym, null, 2)}\n` : renderSymbol(sym));
+		return 0;
+	}
+	const entries = Object.values(graph.symbols).filter((s) => parsed.module === null || s.module === parsed.module);
+	if (parsed.json) {
+		process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`);
+		return 0;
+	}
+	if (parsed.module !== null) {
+		for (const sym of entries.sort((a, b) => a.name.localeCompare(b.name))) process.stdout.write(`  ${sym.name.padEnd(34)} ${sym.kind}${sym.description ? ` — ${sym.description}` : ""}\n`);
+		process.stdout.write(`\n${entries.length} symbole(s) — ${parsed.module}\n`);
+		return 0;
+	}
+	const byPackage = /* @__PURE__ */ new Map();
+	for (const sym of entries) byPackage.set(sym.module, (byPackage.get(sym.module) ?? 0) + 1);
+	process.stdout.write(`graphe : ${file}\n`);
+	if (graph.generated) process.stdout.write(`généré : ${graph.generated}\n`);
+	process.stdout.write(`${entries.length} symboles exportés\n\n`);
+	for (const [mod, n] of [...byPackage].sort((a, b) => b[1] - a[1])) process.stdout.write(`  ${String(n).padStart(5)}  ${mod}\n`);
+	process.stdout.write("\nUn symbole : nodefony symbols AbstractCrudService\nUn paquet  : nodefony symbols --module @nodefony/http\n");
+	return 0;
+}
+//#endregion
+export { lookupSymbol, parseSymbolsArgv, readSymbolsGraph, resolveSymbolsFile, runSymbolsCommand };