nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/env.js

@@ -0,0 +1,332 @@
+import "./sysexits.js";
+import { printUsage, printUsageError } from "./usageReport.js";
+import { findProjectRoot } from "./projectRoot.js";
+import { envFileOrder } from "../runtime/loadEnv.js";
+import { renderEnvExample } from "../config/envExample.js";
+import { getEnvCatalog } from "../config/defineEnv.js";
+import { stripGlobalCliFlags } from "./globalFlags.js";
+import { buildEnvReport } from "./envReport.js";
+import { parseEnv } from "node:util";
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+//#region src/cli/env.ts
+/** Parse l'argv après le mot `env`. */
+function parseEnvArgv(argv) {
+	const at = argv.indexOf("env");
+	const rest = stripGlobalCliFlags(at === -1 ? [] : argv.slice(at + 1));
+	let json = false;
+	let example = false;
+	let check = false;
+	let cwd = process.cwd();
+	let targetEnv = null;
+	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 === "--example") example = true;
+		else if (word === "--check") check = true;
+		else if (word === "--cwd") cwd = path.resolve(rest[++i] ?? "");
+		else if (word === "--env") {
+			const value = rest[++i];
+			if (value === void 0 || value.startsWith("-")) return { error: "--env attend un environnement (ex. --env production)" };
+			targetEnv = value;
+		} else return { error: `option inconnue : ${word}` };
+	}
+	if (check && !example && !help) return { error: "--check n'a de sens qu'avec --example" };
+	return {
+		json,
+		example,
+		check,
+		cwd,
+		targetEnv,
+		help
+	};
+}
+/** La page d'aide — `nodefony env --help`, et le rappel après un refus. */
+const PAGE = {
+	command: "nodefony env",
+	tagline: "la cascade des fichiers .env, la valeur effective de chaque variable, et d'où elle vient",
+	synopsis: ["nodefony env [--json] [--env <e>] [--cwd <chemin>]", "nodefony env --example [--check] [--cwd <chemin>]"],
+	sections: [{
+		title: "CE QU'ELLE MONTRE",
+		paragraph: "L'ordre dans lequel les fichiers .env sont lus, les variables que l'application DÉCLARE, la valeur retenue pour chacune et SA PROVENANCE — puis ce qui est présent dans l'environnement et que personne ne lit. Elle ne démarre pas l'application : on cherche une variable précisément quand celle-ci ne démarre PAS, et la faire booter la rendrait muette au seul moment où elle sert."
+	}],
+	options: [
+		{
+			term: "-j, --json",
+			text: "la même réponse, exploitable par un script"
+		},
+		{
+			term: "--env <e>",
+			text: "évalue les exigences sous CET environnement (ex. production) depuis ce poste — les valeurs restent celles d'ici"
+		},
+		{
+			term: "--example",
+			text: "dérive .env.example du catalogue déclaré dans env.ts"
+		},
+		{
+			term: "--check",
+			text: "avec --example : vérifie sans écrire, et sort en erreur si le fichier diverge (pre-commit, intégration continue)"
+		},
+		{
+			term: "--cwd <chemin>",
+			text: "point de départ (la racine de l'app est résolue en remontant)"
+		}
+	],
+	examples: [
+		{
+			term: "nodefony env",
+			text: "l'environnement d'ici, en entier"
+		},
+		{
+			term: "nodefony env --env production",
+			text: "ce qui manquera là-bas, sans y aller"
+		},
+		{
+			term: "nodefony env --example --check",
+			text: "le .env.example est-il encore à jour ?"
+		}
+	],
+	exitCodes: [{
+		term: "66",
+		text: "aucune application ici (EX_NOINPUT)"
+	}, {
+		term: "78",
+		text: "une variable requise manque, ou .env.example diverge sous --check (EX_CONFIG)"
+	}]
+};
+/**
+* Lit les niveaux de fichiers de la cascade — l'ORDRE vient de `envFileOrder`,
+* jamais d'une copie locale : afficher un ordre qui différerait de celui
+* réellement appliqué tromperait sur le seul point qu'on vient vérifier.
+*/
+function readLevels(cwd, runtimeEnv, appEnv) {
+	return envFileOrder({
+		runtimeEnv,
+		...appEnv ? { appEnv } : {}
+	}).map((source) => {
+		try {
+			return {
+				source,
+				vars: parseEnv(readFileSync(path.join(cwd, source), "utf8"))
+			};
+		} catch {
+			return {
+				source,
+				vars: null
+			};
+		}
+	});
+}
+/**
+* Catalogue des variables déclarées par l'application.
+*
+* Il vit dans `env.ts`, réexporté par l'`index.ts` de l'app — donc lisible en
+* important son build. Pas de build, pas d'export `env` : on rend `null` plutôt
+* que d'échouer, et le rapport le DIT. Une commande de diagnostic qui refuse de
+* répondre quand le projet va mal est une commande inutile.
+*/
+async function readCatalog(projectRoot) {
+	for (const candidate of [path.join(projectRoot, "env.ts"), path.join(projectRoot, "dist", "index.js")]) try {
+		const mod = await import(pathToFileURL(candidate).href);
+		if (mod.env === void 0) continue;
+		const catalog = getEnvCatalog(mod.env);
+		if (catalog.length > 0) return catalog;
+	} catch {}
+	return null;
+}
+/** Colonne alignée, sans dépendance de mise en forme. */
+const pad = (s, n) => s.length >= n ? s : s + " ".repeat(n - s.length);
+/** Rend une variable : valeur, provenance, et ce qui la rend suspecte. */
+function renderVar(v) {
+	const value = v.value === null ? "(absente)" : v.value;
+	const origin = v.origin === null ? "" : `← ${v.origin}`;
+	const flags = [];
+	if (v.missing) flags.push("REQUISE ET ABSENTE");
+	if (v.requiredIn?.length) flags.push(`requise en ${v.requiredIn.join("/")}`);
+	if (v.value === null && v.default !== void 0) flags.push(`défaut ${JSON.stringify(v.default)}`);
+	if (v.secret) flags.push("secret");
+	if (v.values) flags.push(v.values.join("|"));
+	for (const s of v.shadowed) flags.push(`ignoré dans ${s.source}`);
+	return (`  ${pad(v.name, 24)} ${pad(v.kind, 8)} ${pad(value, 24)} ${pad(origin, 22)}` + (flags.length ? `  ${flags.join(" · ")}` : "")).trimEnd();
+}
+/** Rendu humain — l'ordre des sections suit l'ordre des questions qu'on se pose. */
+function render(report, projectRoot) {
+	const out = [];
+	out.push(`\nEnvironnement — mode ${report.runtimeEnv}` + (report.appEnv ? ` · déploiement ${report.appEnv}` : "") + (report.targetEnv ? ` · exigences évaluées pour ${report.targetEnv}` : "") + (projectRoot ? `\n${projectRoot}` : ""));
+	out.push(`\nCascade — du plus FORT au plus faible (le premier posé gagne)`);
+	for (const l of report.levels) {
+		const state = !l.exists ? "absent" : `${l.count} variable${l.count > 1 ? "s" : ""}`;
+		out.push((`  ${l.rank}. ${pad(l.source, 28)} ${pad(state, 16)}` + (l.rank === 1 ? "  ← shell / orchestrateur : gagne TOUJOURS" : "") + (l.skipped ? `  (${l.skipped})` : "")).trimEnd());
+	}
+	if (report.vars.length > 0) {
+		out.push(`\nVariables déclarées par l'application (env.ts)`);
+		for (const v of report.vars) out.push(renderVar(v));
+	}
+	if (report.overrides.length > 0) {
+		out.push("\nSurcharges de configuration (NF__<MODULE>__<CHEMIN>) — visent une clé de module,\nsans passer par env.ts");
+		for (const o of report.overrides) out.push(`  ${pad(o.envKey, 34)} → ${o.module}.${o.path.join(".")} = ${o.value}` + (o.origin ? `  ← ${o.origin}` : ""));
+	}
+	if (report.unknown.length > 0) {
+		out.push("\nVariables NF_ présentes mais NON déclarées — sans effet (une faute de frappe\nsur une variable ne se voit jamais : le défaut s'applique en silence)");
+		for (const u of report.unknown) out.push(`  ${pad(u.name, 34)}${u.origin ? `← ${pad(u.origin, 20)}` : ""}` + (u.suggestion ? `  vouliez-vous dire ${u.suggestion} ?` : ""));
+	}
+	if (report.reserved.length > 0) {
+		out.push(`\nVariables posées par le FRAMEWORK — ni à déclarer, ni à écrire soi-même`);
+		for (const r of report.reserved) out.push(`  ${pad(r.name, 34)}${r.role}`);
+	}
+	const missing = report.vars.filter((v) => v.missing);
+	if (missing.length > 0) out.push(`\n⚠ ${missing.length} variable(s) REQUISE(S) manquante(s) — l'application ne démarrera pas :\n  ${missing.map((v) => v.name).join(", ")}`);
+	for (const note of report.notes) out.push(`\n⚠ ${note}`);
+	out.push("");
+	return out.join("\n");
+}
+/**
+* Commande `nodefony env` — orchestre : résout le projet, lit la cascade et le
+* catalogue, délègue le calcul au module pur, rend.
+*
+* @returns exit code sémantique (`OK`, `USAGE`, `CONFIG` si une requise manque)
+*/
+/**
+* Compose le rapport d'environnement d'un projet — la MÊME donnée pour tous ses
+* lecteurs.
+*
+* Extraite de {@link runEnvCommand} pour que `nodefony doctor` puisse dire « il
+* manque une variable REQUISE » sans réimplémenter la cascade : deux définitions
+* de « quelle valeur est effective » divergeraient, et chacune passerait ses
+* propres tests. Le second lecteur ne rend d'ailleurs pas le rapport, il n'en
+* lit que les manquantes — raison de plus pour qu'il ne le RECALCULE pas.
+*
+* @param projectRoot - racine de l'application, ou `null` hors projet (le
+*   catalogue des variables déclarées est alors inconnu : il se lit dans le
+*   `dist/` de l'application).
+* @param cwd - dossier de départ, utilisé comme racine hors projet.
+* @returns le rapport complet (fichiers lus, variables, provenance, notes).
+*/
+async function buildProjectEnvReport(projectRoot, cwd, targetEnv = null) {
+	const runtimeEnv = process.env.NODE_ENV ?? "development";
+	const rawAppEnv = process.env.APP_ENV ?? process.env.NF_ENV ?? null;
+	const appEnv = rawAppEnv && rawAppEnv !== runtimeEnv ? rawAppEnv : null;
+	const root = projectRoot ?? cwd;
+	return buildEnvReport({
+		runtimeEnv,
+		appEnv,
+		targetEnv,
+		processEnv: process.env,
+		files: readLevels(root, runtimeEnv, appEnv),
+		catalog: projectRoot ? await readCatalog(projectRoot) : null
+	});
+}
+/**
+* En-tête GÉNÉRIQUE du `.env.example` d'une application — la version curée du
+* dépôt self-hosted vit, elle, dans son script (`scripts/gen-env-example.ts`) :
+* même `renderEnvExample` en dessous, seuls le préambule et le chemin diffèrent.
+*/
+const EXAMPLE_HEADER = `# .env.example — MODÈLE d'onboarding (committé, 0 secret réel).
+#
+# ⚙️  GÉNÉRÉ depuis env.ts (catalogue defineEnv) — NE PAS éditer à la main.
+#     Régénérer : npx nodefony env --example
+#     Vérifier  : npx nodefony env --example --check   (pre-commit, CI)
+#
+# Toutes les variables sont COMMENTÉES (le framework a des défauts) : décommenter
+# celles que ton déploiement surcharge, dans .env.local (secrets/machine,
+# gitignoré) ou .env / .env.<env> (défauts non-secrets). Précédence, du plus
+# fort au plus faible :
+#   process.env > .env.<appEnv>.local > .env.<env>.local > .env.local
+#               > .env.<appEnv> > .env.<env> > .env
+#
+# Override GÉNÉRIQUE de config (hors catalogue) : NF__<MODULE|APP>__<CHEMIN>=valeur
+#   ex. NF__APP__SERVERS__HTTP__PORT=8080
+# Secret monté en conteneur : toute variable accepte aussi <NOM>_FILE (Docker/K8s).`;
+/**
+* Compose le contenu de `.env.example` d'une application — PUR.
+*
+* @param catalog - catalogue des variables (via `getEnvCatalog`).
+* @returns le texte complet du fichier.
+*/
+function composeEnvExample(catalog, customHeader = null) {
+	return renderEnvExample(catalog, { header: customHeader ?? EXAMPLE_HEADER });
+}
+/**
+* L'en-tête curé du projet, s'il en a un — convention `.env.example.head` à la
+* racine (versionné). Il PRIME sur l'en-tête générique : un projet qui a écrit
+* son onboarding le garde, le corps reste dérivé du catalogue dans tous les
+* cas. C'est ce qui a permis au dépôt self-hosted de MIGRER de son script
+* `gen-env-example.ts` vers cette commande sans perdre sa prose.
+*
+* @param projectRoot - racine de l'application.
+* @returns le contenu du fichier, ou `null` s'il n'existe pas.
+*/
+function readExampleHeader(projectRoot) {
+	try {
+		return readFileSync(path.join(projectRoot, ".env.example.head"), "utf8").trimEnd();
+	} catch {
+		return null;
+	}
+}
+/**
+* Applique (ou vérifie) le contenu sur le `.env.example` du projet — I/O seul,
+* la composition appartient à {@link composeEnvExample}.
+*
+* Idempotence FORTE : un fichier déjà identique n'est pas réécrit — même
+* doctrine qu'`ai:sync`, un outil qui salit l'horodatage est un outil qu'on
+* hésite à lancer.
+*
+* @param projectRoot - racine de l'application.
+* @param content - contenu attendu, composé en amont.
+* @param check - `true` : ne rien écrire, seulement comparer.
+* @returns `synced` : le fichier correspond (déjà, ou après écriture) ;
+*   `wrote` : une écriture a eu lieu.
+*/
+function applyEnvExample(projectRoot, content, check) {
+	const target = path.join(projectRoot, ".env.example");
+	let current = null;
+	try {
+		current = readFileSync(target, "utf8");
+	} catch {}
+	if (current === content) return {
+		synced: true,
+		wrote: false
+	};
+	if (check) return {
+		synced: false,
+		wrote: false
+	};
+	writeFileSync(target, content, "utf8");
+	return {
+		synced: true,
+		wrote: true
+	};
+}
+async function runEnvCommand(argv) {
+	const parsed = parseEnvArgv(argv);
+	if ("error" in parsed) return printUsageError(PAGE, parsed.error);
+	if (parsed.help) return printUsage(PAGE);
+	const projectRoot = findProjectRoot(parsed.cwd);
+	if (parsed.example) {
+		if (projectRoot === null) {
+			process.stderr.write(`env: aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant).\n`);
+			return 66;
+		}
+		const catalog = await readCatalog(projectRoot);
+		if (catalog === null) {
+			process.stderr.write("env: catalogue introuvable — l'app n'est pas construite, ou son index\nn'exporte pas `env` (env.ts). Lancer d'abord : npm run build\n");
+			return 69;
+		}
+		const { synced, wrote } = applyEnvExample(projectRoot, composeEnvExample(catalog, readExampleHeader(projectRoot)), parsed.check);
+		if (!synced) {
+			process.stderr.write(`❌ .env.example désynchronisé de env.ts — lancer : npx nodefony env --example\n`);
+			return 78;
+		}
+		process.stdout.write(`✅ .env.example ${wrote ? "régénéré depuis" : "synchronisé avec"} env.ts (${catalog.length} variable(s))\n`);
+		return 0;
+	}
+	const report = await buildProjectEnvReport(projectRoot, parsed.cwd, parsed.targetEnv);
+	if (projectRoot === null) report.notes.push("aucun projet Nodefony ici (nodefony.config.ts introuvable en remontant) — seul l'environnement du shell est décrit");
+	process.stdout.write(parsed.json ? `${JSON.stringify(report, null, 2)}\n` : render(report, projectRoot));
+	return report.vars.some((v) => v.missing) ? 78 : 0;
+}
+//#endregion
+export { applyEnvExample, buildProjectEnvReport, composeEnvExample, parseEnvArgv, readExampleHeader, runEnvCommand };

package/dist/node/cli/envReport.js

@@ -0,0 +1,159 @@
+import { isEnvVarRequired, resolveEnvStages } from "../config/defineEnv.js";
+import { closestMatch, parseNfEnvOverrides, pathLooksSecret } from "../config/envOverride.js";
+import { isReservedEnv, reservedEnvRole } from "../config/reservedEnv.js";
+//#region src/cli/envReport.ts
+/** Masque une valeur sensible sans mentir sur sa présence. */
+function mask(value) {
+	return value === "" ? "(vide)" : `${"•".repeat(8)} (${value.length} car.)`;
+}
+/**
+* Variables présentes dans l'env mais qu'aucune déclaration n'explique.
+*
+* Restreint au préfixe `NF_` : le reste de `process.env` appartient au système
+* (PATH, HOME, les mille variables d'un shell) et le lister noierait le signal.
+* Une variable `NF_` inconnue, elle, est presque toujours une faute de frappe —
+* et une faute de frappe sur une variable d'environnement ne se voit JAMAIS :
+* la valeur est simplement ignorée, et le défaut s'applique en silence.
+*/
+function collectUnknown(processEnv, declared, originOf) {
+	const known = [...declared];
+	const out = [];
+	for (const name of Object.keys(processEnv)) {
+		if (!name.startsWith("NF_") || name.startsWith("NF__")) continue;
+		if (declared.has(name)) continue;
+		if (isReservedEnv(name)) continue;
+		if (name.endsWith("_FILE") && declared.has(name.slice(0, -5))) continue;
+		const suggestion = closestMatch(name, known);
+		out.push({
+			name,
+			origin: originOf(name),
+			...suggestion ? { suggestion } : {}
+		});
+	}
+	return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* Les variables que le FRAMEWORK a posées lui-même dans l'environnement.
+*
+* Elles sont RENDUES, pas tues : une variable présente que le rapport passe
+* sous silence est le même défaut vu de l'autre côté — l'utilisateur cherche
+* alors pourquoi son environnement ne ressemble pas à ce qu'on lui montre.
+*/
+function collectReserved(processEnv, originOf) {
+	const out = [];
+	for (const name of Object.keys(processEnv)) {
+		const role = reservedEnvRole(name);
+		if (role === null) continue;
+		out.push({
+			name,
+			origin: originOf(name),
+			role
+		});
+	}
+	return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+* Construit le rapport d'environnement.
+*
+* @param input.runtimeEnv - mode runtime (`NODE_ENV`).
+* @param input.appEnv - environnement de déploiement, s'il diffère du mode.
+* @param input.processEnv - l'environnement effectif, cascade déjà appliquée.
+* @param input.files - les niveaux de fichiers, du PLUS fort au PLUS faible.
+* @param input.catalog - les variables déclarées par l'app, ou `null` si illisible.
+* @returns le rapport, sérialisable tel quel.
+*/
+function buildEnvReport(input) {
+	const { runtimeEnv, processEnv, files, catalog } = input;
+	const appEnv = input.appEnv ?? null;
+	const targetEnv = input.targetEnv ?? null;
+	const stages = targetEnv ? [targetEnv] : resolveEnvStages({
+		NODE_ENV: runtimeEnv,
+		...appEnv ? { NF_ENV: appEnv } : {}
+	});
+	/**
+	* Origine d'une clé : le premier fichier de la cascade qui la définit AVEC la
+	* valeur effective. Aucun ne correspond → le shell l'a posée (ou l'a écrasée,
+	* puisqu'il gagne toujours).
+	*/
+	const originOf = (name) => {
+		const effective = processEnv[name];
+		if (effective === void 0) return null;
+		for (const level of files) if (level.vars && level.vars[name] === effective) return level.source;
+		return "process.env";
+	};
+	/** Niveaux qui définissent la clé sans être son origine — donc ignorés. */
+	const shadowsOf = (name, winner) => {
+		const out = [];
+		let passedWinner = winner === "process.env";
+		for (const level of files) {
+			if (!level.vars || level.vars[name] === void 0) continue;
+			if (!passedWinner && level.source === winner) {
+				passedWinner = true;
+				continue;
+			}
+			if (passedWinner) out.push({
+				source: level.source,
+				value: level.vars[name]
+			});
+		}
+		return out;
+	};
+	const levels = [{
+		rank: 1,
+		source: "process.env",
+		exists: true,
+		count: Object.keys(processEnv).length
+	}, ...files.map((f, i) => ({
+		rank: i + 2,
+		source: f.source,
+		exists: f.vars !== null,
+		count: f.vars ? Object.keys(f.vars).length : 0,
+		...f.skipped ? { skipped: f.skipped } : {}
+	}))];
+	const declared = new Set((catalog ?? []).map((v) => v.name));
+	const vars = (catalog ?? []).map((meta) => {
+		const raw = processEnv[meta.name];
+		const secret = pathLooksSecret([meta.name]);
+		const origin = originOf(meta.name);
+		const required = isEnvVarRequired(meta, stages);
+		return {
+			name: meta.name,
+			kind: meta.kind,
+			declared: true,
+			required,
+			...meta.requiredIn ? { requiredIn: meta.requiredIn } : {},
+			secret,
+			...meta.description ? { description: meta.description } : {},
+			value: raw === void 0 ? null : secret ? mask(raw) : raw,
+			origin,
+			...meta.default !== void 0 ? { default: meta.default } : {},
+			...meta.values ? { values: meta.values } : {},
+			missing: required && (raw === void 0 || raw === ""),
+			shadowed: shadowsOf(meta.name, origin)
+		};
+	});
+	const overrides = parseNfEnvOverrides(processEnv).map((o) => ({
+		envKey: o.envKey,
+		module: o.moduleSeg,
+		path: o.path,
+		value: pathLooksSecret(o.path) ? mask(String(processEnv[o.envKey] ?? "")) : String(processEnv[o.envKey] ?? ""),
+		origin: originOf(o.envKey)
+	}));
+	const notes = [];
+	if (catalog === null) notes.push("catalogue des variables illisible — l'application n'est pas construite (`npm run build`) ou n'exporte pas `env` : la cascade ci-dessus reste exacte, la liste des variables déclarées manque");
+	return {
+		runtimeEnv,
+		appEnv,
+		targetEnv,
+		stages,
+		levels,
+		vars,
+		overrides,
+		unknown: collectUnknown(processEnv, declared, originOf),
+		reserved: collectReserved(processEnv, originOf),
+		catalogAvailable: catalog !== null,
+		notes
+	};
+}
+//#endregion
+export { buildEnvReport };

package/dist/node/cli/execPortable.js

@@ -0,0 +1,60 @@
+import path from "node:path";
+//#region src/cli/execPortable.ts
+/**
+* Lancer un exécutable de l'écosystème npm, sur les trois systèmes.
+*
+* ## Le défaut, et pourquoi il ne se voit jamais sur un poste de développement
+*
+* Sous Windows, `npm`, `npx`, `prettier` et compagnie ne sont pas des exécutables :
+* ce sont des scripts `.cmd`. Depuis le correctif de CVE-2024-27980, Node REFUSE
+* d'exécuter un `.cmd` sans `shell: true` — et il ne le dit pas en ces termes : il
+* rend `spawnSync npm ENOENT`, qui se lit « npm n'est pas installé ». Sur une
+* machine où npm vient de tourner, c'est un message qui envoie chercher très loin
+* de la cause.
+*
+* Ce que cela coûtait EN PRODUIT, et pas seulement en outillage : `nodefony create
+* module` installe le workspace npm qu'il vient d'écrire — c'est ce `npm install`
+* qui crée le lien sans lequel le Kernel ne peut pas importer le module par son
+* nom. Sous Windows il ne s'exécutait pas ; le module était écrit, construit,
+* déclaré au manifeste — et introuvable au boot. L'application démarrait sans lui
+* (fail-soft) et TOUTES ses routes rendaient 404.
+*
+* ## Une seule implémentation, dans le FRAMEWORK
+*
+* La règle a d'abord été écrite dans le banc qui mesure le framework, jamais dans
+* le framework lui-même — si bien que l'outil de mesure était portable et que le
+* produit ne l'était pas. C'est l'utilisateur qui subit la règle : c'est donc ici
+* qu'elle vit, et le banc l'importe.
+*/
+/**
+* Faut-il passer par le shell pour lancer cette commande ?
+*
+* Vrai sous Windows dans DEUX cas, et une première version n'en voyait qu'un :
+*
+*  1. la commande est cherchée dans le `PATH` (`npm`, `npx`) — elle s'y résout en
+*     `.cmd` ;
+*  2. la commande est un chemin ABSOLU qui désigne un script batch
+*     (`…\node_modules\.bin\oxlint.cmd`).
+*
+* « Absolu donc exécutable réel » est une inférence, pas un constat : ce qui empêche
+* Node de lancer la chose n'est pas l'endroit où elle est, c'est ce qu'elle EST.
+*
+* Ailleurs que sous Windows, `shell: true` est à éviter : il rouvre l'interprétation
+* des métacaractères sur des arguments qui viennent parfois d'un décor.
+*
+* La plateforme et la grammaire de chemins sont INJECTÉES, et ce n'est pas de la
+* coquetterie : une fonction qui lit `process.platform` ne peut être éprouvée que
+* sur la plateforme qu'elle décrit — c'est-à-dire jamais, sur les postes de ce
+* projet. Injectées, les deux branches se vérifient partout.
+*
+* @param command - ce qu'on s'apprête à lancer.
+* @param plateforme - le système, injectable pour l'épreuve.
+* @param grammar - `path.win32` ou `path.posix`, idem.
+* @returns la valeur à donner à l'option `shell` de `spawn`/`spawnSync`.
+*/
+function needsShell(command, plateforme = process.platform, grammar = path) {
+	if (plateforme !== "win32") return false;
+	return !grammar.isAbsolute(command) || /\.(cmd|bat)$/iu.test(command);
+}
+//#endregion
+export { needsShell };