nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/cli/progress.js

@@ -0,0 +1,555 @@
+import readline from "node:readline";
+//#region src/cli/progress.ts
+/**
+* Indicateurs d'attente et de progression pour un terminal — la seule
+* implémentation du framework.
+*
+* Ils existent parce qu'une commande qui annonce une étape puis se tait pendant
+* quarante secondes est indiscernable d'une commande plantée : l'utilisateur ne
+* peut pas savoir s'il doit attendre ou interrompre. Un point fixe n'est pas
+* une progression.
+*
+* ## Ce qu'il faut choisir
+*
+* | On sait…                                    | La forme      |
+* | ------------------------------------------- | ------------- |
+* | seulement que ça travaille                  | {@link Spinner} |
+* | combien d'unités sur combien                | {@link ProgressBar} |
+* | les deux (des lots en parallèle, par ex.)   | `ProgressBar` avec `spin: true` |
+*
+* ## 🔴 Rien de tout cela ne passe par le Syslog, et c'est structurel
+*
+* Une animation réécrit la même ligne dix fois par seconde. La faire passer par
+* le journal en ferait dix entrées allouées, poussées au tampon circulaire, aux
+* transports et au backplane — du décor d'affichage expédié à un collecteur de
+* logs. Ces objets écrivent DIRECTEMENT sur leur flux, et le journal les ignore.
+*
+* ## Hors terminal
+*
+* Quand le flux n'est pas un terminal (redirection, tube, forge d'intégration),
+* `\r` ne ramène nulle part et l'animation deviendrait une avalanche de lignes.
+* Rien n'est alors dessiné : seule la ligne finale de `stop()` est émise. C'est
+* ce qui rend ces objets posables sans condition dans du code qui tourne aussi
+* bien en local qu'en forge.
+*/
+/**
+* Tourniquet braille — dix images, rotation fluide. Le défaut.
+*
+* Le braille est préféré aux `|/-\` : il occupe une seule cellule quelle que
+* soit l'image, donc la ligne ne « respire » pas au fil de l'animation.
+*/
+const BRAILLE_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** Tourniquet ASCII — le repli quand la police ne porte pas le braille. */
+const LINE_FRAMES = [
+	"-",
+	"\\",
+	"|",
+	"/"
+];
+/** Arcs tournants — plus discret que le braille, même encombrement. */
+const ARC_FRAMES = [
+	"◜",
+	"◠",
+	"◝",
+	"◞",
+	"◡",
+	"◟"
+];
+/** Barres montantes — suggère une activité qui « pompe ». */
+const BLOCK_FRAMES = [
+	"▁",
+	"▂",
+	"▃",
+	"▄",
+	"▅",
+	"▆",
+	"▇",
+	"▆",
+	"▅",
+	"▄",
+	"▃",
+	"▂"
+];
+/** Points qui s'ajoutent — le plus sobre, et le seul purement ASCII. */
+const DOT_FRAMES = [
+	"   ",
+	".  ",
+	".. ",
+	"..."
+];
+/** Styles de barre prêts à l'emploi. */
+const BAR_STYLES = {
+	/** `▰▰▰▱▱` — le défaut, lisible et compact. */
+	blocks: {
+		filled: "▰",
+		empty: "▱"
+	},
+	/** `███░░` — dense, bon contraste sur fond sombre. */
+	solid: {
+		filled: "█",
+		empty: "░"
+	},
+	/** `===--` — purement ASCII, pour un terminal pauvre ou un journal. */
+	ascii: {
+		filled: "=",
+		empty: "-"
+	},
+	/** `●●●○○` — pour un petit nombre d'unités qu'on veut compter à l'œil. */
+	dots: {
+		filled: "●",
+		empty: "○"
+	}
+};
+/**
+* Le terminal sait-il dessiner du braille et des blocs ?
+*
+* 🔴 Windows est un impératif produit ici, et `cmd.exe` rend `⠋` en carré vide
+* ou en point d'interrogation : une animation illisible est pire qu'aucune.
+* La capacité se CONSTATE sur l'environnement plutôt que de se déduire de
+* `process.platform` — Windows Terminal, VS Code et les consoles modernes
+* affichent parfaitement le braille, et les punir serait aussi faux que de
+* supposer que toutes y arrivent.
+*
+* Même méthode que `is-unicode-supported`, sans la dépendance.
+*
+* @param env - l'environnement à interroger (injecté : une fonction qui lit
+*   `process.env` en dur ne s'éprouve pas).
+*/
+function supportsUnicode(env = process.env, platform = process.platform) {
+	if (platform !== "win32") {
+		if (env["TERM"] === "linux") return false;
+		const locale = env["LC_ALL"] ?? env["LC_CTYPE"] ?? env["LANG"] ?? "";
+		return /UTF-?8$/i.test(locale) || locale === "";
+	}
+	return Boolean(env["WT_SESSION"] || env["TERMINUS_SUBLIME"] || env["ConEmuTask"] === "{cmd::Cmder}" || env["TERM_PROGRAM"] === "vscode" || env["TERM"] === "xterm-256color" || env["TERM"] === "alacritty");
+}
+/**
+* Faut-il animer du tout ?
+*
+* Un terminal ne suffit pas : une forge d'intégration peut en fournir un
+* (`CI=true` avec un pseudo-terminal), et y déverser dix images par seconde
+* remplit un journal que personne ne pourra relire. `TERM=dumb` est la
+* déclaration explicite d'un terminal qui ne sait rien réécrire.
+*/
+function shouldAnimate(stream, env = process.env) {
+	if (!stream.isTTY) return false;
+	if (env["TERM"] === "dumb") return false;
+	if (env["CI"]) return false;
+	if (env["NF_NO_PROGRESS"]) return false;
+	return true;
+}
+/** Nombre d'indicateurs qui animent en ce moment — le curseur suit ce compte. */
+let animatingCount = 0;
+/** Le flux sur lequel le curseur a été masqué, `null` s'il ne l'est pas. */
+let cursorHiddenOn = null;
+/** Retrait des gardes de sortie — `null` tant qu'elles ne sont pas posées. */
+let releaseGuards = null;
+function showCursor() {
+	if (cursorHiddenOn === null) return;
+	cursorHiddenOn.write("\x1B[?25h");
+	cursorHiddenOn = null;
+	releaseGuards?.();
+	releaseGuards = null;
+}
+function hideCursor(stream) {
+	if (cursorHiddenOn !== null) return;
+	stream.write("\x1B[?25l");
+	cursorHiddenOn = stream;
+	const onExit = () => showCursor();
+	const onSignal = (signal) => {
+		if (process.listenerCount(signal) > 1) {
+			showCursor();
+			return;
+		}
+		showCursor();
+		process.kill(process.pid, signal);
+	};
+	process.once("exit", onExit);
+	process.on("SIGINT", onSignal);
+	process.on("SIGTERM", onSignal);
+	releaseGuards = () => {
+		process.removeListener("exit", onExit);
+		process.removeListener("SIGINT", onSignal);
+		process.removeListener("SIGTERM", onSignal);
+	};
+}
+/**
+* Tronque une ligne à la largeur du terminal, séquences ANSI non comptées.
+*
+* 🔴 Sans cela, une ligne trop longue passe à la ligne — et `clearLine` n'en
+* efface qu'UNE : la queue reste à l'écran, l'animation laisse une traînée. Le
+* dépôt a déjà payé ce défaut ailleurs (`inspect routes` sortait à 900
+* colonnes). Deux colonnes sont laissées libres : certains terminaux passent à
+* la ligne dès la dernière atteinte.
+*/
+function fitToWidth(line, columns) {
+	const width = columns && columns > 8 ? columns - 2 : 78;
+	const ansi = /\u001B\[[0-9;]*m/g;
+	let visible = 0;
+	let out = "";
+	let index = 0;
+	for (const match of line.matchAll(ansi)) {
+		const text = line.slice(index, match.index);
+		for (const ch of text) {
+			if (visible >= width) return out;
+			out += ch;
+			visible++;
+		}
+		out += match[0];
+		index = match.index + match[0].length;
+	}
+	for (const ch of line.slice(index)) {
+		if (visible >= width) return out;
+		out += ch;
+		visible++;
+	}
+	return out;
+}
+const SYNC_END = "\x1B[?2026l";
+/** Cadence par défaut, en millisecondes — au-delà l'animation saccade. */
+const DEFAULT_INTERVAL_MS = 80;
+/** Largeur par défaut d'une barre, en cellules. */
+const DEFAULT_BAR_WIDTH = 20;
+/**
+* Ramène une valeur à un compte utilisable : entier, positif, FINI.
+*
+* 🔴 `NaN` est le piège : il traverse `Math.min`, `Math.max` et `Math.round`
+* sans jamais lever, puis `"▰".repeat(NaN)` rend la chaîne VIDE. Une barre
+* censée faire vingt cellules disparaissait donc en silence — le pire mode de
+* panne pour un indicateur, qui n'affiche rien là où il devrait alerter.
+*/
+function safeCount(value) {
+	return Number.isFinite(value) ? Math.max(0, Math.trunc(value)) : 0;
+}
+/** Rapport `done/total` borné à `[0, 1]` ; `0` si le total est nul ou absurde. */
+function ratioOf(done, total) {
+	const t = safeCount(total);
+	if (t === 0) return 0;
+	return Math.min(1, Math.max(0, safeCount(done) / t));
+}
+/**
+* Dessine une barre de progression, et rien d'autre.
+*
+* Fonction PURE : elle n'écrit nulle part, ne connaît aucun terminal et se
+* teste par simple comparaison de chaînes. C'est ce qui permet de la réutiliser
+* dans un rendu sur mesure — un rapport, un journal, une page — sans traîner
+* derrière soi la machinerie d'affichage.
+*
+* Les bornes sont tenues : un `done` négatif, supérieur au total, ou un total
+* nul ne produisent jamais une barre plus longue ou plus courte que `width`.
+* Un total nul rend une barre vide plutôt que de diviser par zéro.
+*
+* @param done - unités faites
+* @param total - unités attendues
+* @param options - largeur et style
+* @returns la barre, sans couleur ni texte autour
+*
+* @example
+* ```ts
+* renderBar(3, 10, { width: 10 });        // "▰▰▰▱▱▱▱▱▱▱"
+* renderBar(1, 2, { style: BAR_STYLES.ascii, width: 4 }); // "==--"
+* ```
+*/
+function renderBar(done, total, options = {}) {
+	const width = safeCount(options.width ?? DEFAULT_BAR_WIDTH);
+	const { filled, empty } = options.style ?? BAR_STYLES.blocks;
+	const full = Math.min(width, Math.round(ratioOf(done, total) * width));
+	return filled.repeat(full) + empty.repeat(width - full);
+}
+/**
+* Met en forme une durée pour un humain : `840ms`, `12.3s`, `4m 05s`.
+*
+* @param ms - durée en millisecondes
+*/
+function formatDuration(ms) {
+	if (ms < 1e3) return `${Math.round(ms)}ms`;
+	if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
+	const minutes = Math.floor(ms / 6e4);
+	const seconds = Math.round(ms % 6e4 / 1e3);
+	return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+}
+/**
+* Une ligne de terminal qu'on réécrit en place.
+*
+* Porte ce que toutes les formes répètent sinon : le choix du flux, la
+* détection du terminal, l'effacement AVANT écriture (sans quoi un texte court
+* laisse derrière lui la queue d'un texte plus long), et le fait de ne rien
+* dessiner hors terminal.
+*
+* Classe de base : on instancie {@link Spinner} ou {@link ProgressBar}.
+*/
+var LiveLine = class {
+	stream;
+	/** Vrai entre `start()` et `stop()`, même hors terminal. */
+	active = false;
+	/** Résultat de {@link shouldAnimate}, résolu UNE fois à la construction. */
+	interactive;
+	constructor(options = {}) {
+		this.stream = options.stream ?? process.stdout;
+		this.interactive = options.animate ?? shouldAnimate(this.stream, options.env);
+	}
+	/** Vrai si l'on peut dessiner en place — terminal, hors forge, `TERM` utile. */
+	get isInteractive() {
+		return this.interactive;
+	}
+	/** Vrai entre `start()` et `stop()`. */
+	get running() {
+		return this.active;
+	}
+	/**
+	* Arrête et fige éventuellement une ligne à la place de celle qui vivait.
+	*
+	* Sans terminal, la ligne finale est écrite telle quelle — c'est la seule
+	* trace du passage, et c'est ce qui rend les journaux de forge lisibles.
+	*
+	* @param finalLine - la ligne à laisser ; omise, la ligne vivante disparaît.
+	*/
+	stop(finalLine) {
+		this.halt();
+		this.erase();
+		if (this.active && this.isInteractive) {
+			animatingCount = Math.max(0, animatingCount - 1);
+			if (animatingCount === 0) showCursor();
+		}
+		this.active = false;
+		if (finalLine !== void 0) this.stream.write(`${finalLine}\n`);
+	}
+	/** Masque le curseur au premier indicateur qui anime, et le compte. */
+	claimCursor() {
+		animatingCount++;
+		hideCursor(this.stream);
+	}
+	/** Efface la ligne courante puis écrit la nouvelle. Muet hors terminal. */
+	paint(text) {
+		if (!this.isInteractive) return;
+		this.stream.write("\x1B[?2026h\x1B[2K\x1B[1G" + fitToWidth(text, this.stream.columns) + SYNC_END);
+	}
+	/** Ramène le curseur en début de ligne et efface ce qui s'y trouvait. */
+	erase() {
+		if (!this.active || !this.isInteractive) return;
+		readline.clearLine(this.stream, 0);
+		readline.cursorTo(this.stream, 0);
+	}
+};
+/**
+* Attente **indéterminée** : on montre que ça vit, sans promettre de fin.
+*
+* Le minuteur est `unref()` — il n'empêche jamais le processus de se terminer —
+* et {@link LiveLine.stop} l'arrête explicitement. Un `Spinner` arrêté est
+* réutilisable : un nouveau {@link start} repart proprement.
+*
+* @example
+* ```ts
+* const spinner = new Spinner();
+* spinner.start("Compilation");
+* await build();
+* spinner.stop(`✓ Compilation (${formatDuration(elapsed)})`);
+* ```
+*/
+var Spinner = class extends LiveLine {
+	#intervalMs;
+	#frames;
+	#render;
+	/** Minuteur d'animation — `null` tant que rien ne tourne. */
+	#timer = null;
+	#frame = 0;
+	#label = "";
+	constructor(options = {}) {
+		super(options);
+		this.#intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+		this.#frames = options.frames ?? (supportsUnicode(options.env) ? BRAILLE_FRAMES : LINE_FRAMES);
+		this.#render = options.render ?? ((frame, label) => `  ${frame} ${label}…`);
+	}
+	/** Vrai si l'animation tourne RÉELLEMENT (donc sur un terminal). */
+	get animating() {
+		return this.#timer !== null;
+	}
+	/**
+	* Démarre l'attente sous un libellé.
+	*
+	* Un `start()` sur un tourniquet déjà lancé change simplement le libellé : il
+	* ne crée jamais un second minuteur.
+	*
+	* @param label - ce qu'on est en train d'attendre
+	*/
+	start(label) {
+		this.#label = label;
+		if (this.active) {
+			this.#draw();
+			return;
+		}
+		this.active = true;
+		if (!this.isInteractive) return;
+		this.claimCursor();
+		this.#frame = 0;
+		this.#draw();
+		this.#timer = setInterval(() => {
+			this.#frame = (this.#frame + 1) % this.#frames.length;
+			this.#draw();
+		}, this.#intervalMs);
+		this.#timer.unref?.();
+	}
+	/**
+	* Change le libellé sans interrompre l'animation.
+	*
+	* @param label - le nouveau libellé
+	*/
+	setLabel(label) {
+		this.#label = label;
+		if (this.#timer !== null) this.#draw();
+	}
+	/** Redessine tout de suite, sans attendre la prochaine image. */
+	refresh() {
+		if (this.#timer !== null) this.#draw();
+	}
+	halt() {
+		if (this.#timer === null) return;
+		clearInterval(this.#timer);
+		this.#timer = null;
+	}
+	#draw() {
+		this.paint(this.#render(this.#frames[this.#frame], this.#label));
+	}
+};
+/**
+* Progression **déterminée** : on connaît le total, on montre où l'on en est.
+*
+* Redessine à chaque {@link update}. Avec `spin: true`, un minuteur anime en
+* plus un tourniquet en tête — utile quand l'avancement peut rester immobile un
+* long moment, ce qu'une barre seule ne distingue pas d'un blocage.
+*
+* @example
+* ```ts
+* const bar = new ProgressBar({ spin: true });
+* bar.start(files.length, "Compilation");
+* for (const file of files) {
+*   await compile(file);
+*   bar.increment();
+* }
+* bar.stop(`✓ ${files.length} fichiers`);
+* ```
+*/
+var ProgressBar = class extends LiveLine {
+	#width;
+	#style;
+	#spin;
+	#intervalMs;
+	#frames;
+	#render;
+	#timer = null;
+	#frame = 0;
+	#done = 0;
+	#total = 0;
+	#label = "";
+	#startedAt = 0;
+	constructor(options = {}) {
+		super(options);
+		this.#width = options.width ?? DEFAULT_BAR_WIDTH;
+		this.#style = options.style ?? (supportsUnicode(options.env) ? BAR_STYLES.blocks : BAR_STYLES.ascii);
+		this.#spin = options.spin ?? false;
+		this.#intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+		this.#frames = options.frames ?? (supportsUnicode(options.env) ? BRAILLE_FRAMES : LINE_FRAMES);
+		this.#render = options.render ?? (({ bar, done, total, label, frame }) => `  ${frame ? `${frame} ` : ""}${bar} ${done}/${total}${label ? ` ${label}` : ""}`);
+	}
+	/** Unités faites. */
+	get done() {
+		return this.#done;
+	}
+	/** Unités attendues. */
+	get total() {
+		return this.#total;
+	}
+	/** Vrai si le tourniquet tourne réellement. */
+	get animating() {
+		return this.#timer !== null;
+	}
+	/**
+	* Démarre la progression.
+	*
+	* @param total - unités attendues
+	* @param label - libellé facultatif
+	*/
+	start(total, label = "") {
+		this.#total = safeCount(total);
+		this.#label = label;
+		this.#done = 0;
+		this.#startedAt = Date.now();
+		if (this.active) {
+			this.#draw();
+			return;
+		}
+		this.active = true;
+		if (!this.isInteractive) return;
+		this.claimCursor();
+		this.#draw();
+		if (!this.#spin) return;
+		this.#timer = setInterval(() => {
+			this.#frame = (this.#frame + 1) % this.#frames.length;
+			this.#draw();
+		}, this.#intervalMs);
+		this.#timer.unref?.();
+	}
+	/**
+	* Pose l'avancement à une valeur absolue.
+	*
+	* @param done - unités faites
+	* @param label - nouveau libellé, facultatif
+	*/
+	update(done, label) {
+		this.#done = safeCount(done);
+		if (label !== void 0) this.#label = label;
+		this.#draw();
+	}
+	/**
+	* Avance de `step` unités.
+	*
+	* @param step - pas d'avancement. Défaut : 1.
+	*/
+	increment(step = 1) {
+		this.update(this.#done + step);
+	}
+	/** Change le total en cours de route (une découverte, un lot qui grossit). */
+	setTotal(total) {
+		this.#total = safeCount(total);
+		this.#draw();
+	}
+	/** Change le libellé sans toucher à l'avancement. */
+	setLabel(label) {
+		this.#label = label;
+		this.#draw();
+	}
+	halt() {
+		if (this.#timer === null) return;
+		clearInterval(this.#timer);
+		this.#timer = null;
+	}
+	#draw() {
+		if (!this.active) return;
+		const ratio = ratioOf(this.#done, this.#total);
+		this.paint(this.#render({
+			done: this.#done,
+			total: this.#total,
+			ratio,
+			bar: renderBar(this.#done, this.#total, {
+				width: this.#width,
+				style: this.#style
+			}),
+			label: this.#label,
+			frame: this.#spin ? this.#frames[this.#frame] : "",
+			elapsedMs: this.#startedAt === 0 ? 0 : Date.now() - this.#startedAt
+		}));
+	}
+};
+//#endregion
+export { ARC_FRAMES, BAR_STYLES, BLOCK_FRAMES, BRAILLE_FRAMES, DOT_FRAMES, LINE_FRAMES, LiveLine, ProgressBar, Spinner, fitToWidth, formatDuration, renderBar, shouldAnimate, supportsUnicode };

package/dist/node/cli/projectRoot.js

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+//#region src/cli/projectRoot.ts
+/**
+* Racine du PROJET Nodefony courant (app générée / app utilisateur) : remonte
+* depuis `from` jusqu'au premier dossier portant `nodefony.config.ts` +
+* `package.json`.
+*
+* Deux consommateurs, une seule définition de « où commence l'app » :
+* - les scaffolds IN-PROJECT (`create controller|module|entity`) — par
+*   opposition à `create app` qui crée un dossier neuf ;
+* - le **lanceur** (`bin/nodefony`), qui délègue au CLI de l'app quand il en
+*   trouve un (cf `../bin/resolveLocalCli`).
+*
+* Vit ici (module sans dépendance, `node:fs`/`node:path` seuls) et pas dans
+* `scaffold/engine.ts` : le bundle du binaire importerait alors `eta` et tout le
+* moteur de templates, payés à CHAQUE invocation du CLI.
+*
+* @param from - dossier de départ (typiquement `process.cwd()`).
+* @returns racine absolue, ou `null` hors projet.
+*/
+function findProjectRoot(from) {
+	let dir = path.resolve(from);
+	for (;;) {
+		if (existsSync(path.join(dir, "nodefony.config.ts")) && existsSync(path.join(dir, "package.json"))) return dir;
+		const parent = path.dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+//#endregion
+export { findProjectRoot };

package/dist/node/cli/promptPassword.js

@@ -0,0 +1,44 @@
+import readline from "node:readline/promises";
+import { Writable } from "node:stream";
+//#region src/cli/promptPassword.ts
+/**
+* Demande un secret sans jamais l'ÉCHOTER — mot de passe, phrase de passe.
+*
+* La frappe passe par un `readline` dont la sortie est un flux MUET : la
+* question s'écrit directement sur la sortie standard, les caractères tapés ne
+* s'affichent nulle part et ne peuvent donc pas se retrouver dans une capture
+* d'écran, un partage de terminal ou un journal de session.
+*
+* Vit au cœur, et pas dans la commande qui en avait besoin la première : deux
+* copies d'un prompt de secret finissent par différer sur ce qui compte — l'une
+* oublie de couper l'écho, l'autre de refermer l'interface, et le terminal reste
+* muet après coup.
+*
+* ⚠️ **Sans terminal, cette fonction n'a pas de sens** : un pipeline resterait
+* suspendu sur une question que personne ne lit. L'appelant doit constater le
+* TTY avant (cf `Command.askArgument`) et proposer une option de ligne de
+* commande pour les scripts.
+*
+* @param question - invite écrite telle quelle (ajouter les deux points et l'espace)
+* @returns ce qui a été tapé, sans le retour à la ligne
+*/
+async function askPasswordMasked(question) {
+	const muted = new Writable({ write(_chunk, _enc, cb) {
+		cb();
+	} });
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: muted,
+		terminal: true
+	});
+	process.stdout.write(question);
+	try {
+		const answer = await rl.question("");
+		process.stdout.write("\n");
+		return answer;
+	} finally {
+		rl.close();
+	}
+}
+//#endregion
+export { askPasswordMasked };