nodefony 7.0.2 → 10.0.0-alpha.2

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

@@ -0,0 +1,119 @@
+/**
+ * Une entrée telle que `npm outdated --json` la rend, pour UN couple paquet/dépendant.
+ *
+ * Le champ `current` est absent quand le paquet n'est pas installé du tout.
+ */
+export interface INpmOutdatedEntry {
+    current?: string;
+    wanted: string;
+    latest: string;
+    dependent?: string;
+    location?: string;
+    type?: string;
+}
+/**
+ * Le document rendu par `npm outdated --json`.
+ *
+ * Un paquet réclamé par plusieurs espaces de travail apparaît sous forme de TABLEAU —
+ * c'est la source de la duplication massive quand on se contente de réafficher le brut.
+ */
+export type NpmOutdatedReport = Record<string, INpmOutdatedEntry | INpmOutdatedEntry[]>;
+/** Nature du saut de version qui sépare la version installée de la dernière publiée. */
+export type OutdatedSeverity = "major" | "minor" | "patch" | "missing";
+/**
+ * Un paquet en retard, agrégé : une seule ligne quel que soit le nombre de dépendants.
+ */
+export interface IOutdatedPackage {
+    /** Nom npm du paquet. */
+    name: string;
+    /** Version installée, ou `null` si le paquet est absent de `node_modules`. */
+    current: string | null;
+    /** Version que la plage de versions déclarée autorise déjà. */
+    wanted: string;
+    /** Dernière version publiée au registre. */
+    latest: string;
+    /** Nature du saut `current` → `latest`. */
+    severity: OutdatedSeverity;
+    /**
+     * `true` quand la plage déclarée INTERDIT la montée (`wanted` === `current`) :
+     * un `npm update` ne fera rien, il faut décider de changer la plage.
+     */
+    pinned: boolean;
+    /** Espaces de travail qui réclament ce paquet, dédupliqués et triés. */
+    dependents: string[];
+    /** `dependencies` / `devDependencies` / `peerDependencies` si `npm` l'a rendu (`--long`). */
+    type?: string;
+}
+/**
+ * Résultat agrégé, prêt à afficher ou à sérialiser.
+ */
+export interface IOutdatedSummary {
+    /** Paquets réellement en retard, triés du saut le plus grave au plus bénin. */
+    packages: IOutdatedPackage[];
+    /**
+     * Paquets dont la version INSTALLÉE dépasse celle du registre — typiquement un
+     * espace de travail local pas encore publié. Ce n'est pas un retard, c'est l'inverse.
+     */
+    ahead: IOutdatedPackage[];
+    /** Comptes par catégorie, pour l'en-tête. */
+    counts: {
+        major: number;
+        minor: number;
+        patch: number;
+        missing: number;
+        ahead: number;
+        /** Nombre de couples paquet/dépendant que `npm` a rendus, avant agrégation. */
+        rawEntries: number;
+    };
+}
+/**
+ * Classe le saut qui sépare deux versions.
+ *
+ * Les variantes de préversion rendues par `semver.diff` (`premajor`, `preminor`…) sont
+ * ramenées à leur saut de rang, faute de quoi elles échapperaient à tout regroupement.
+ *
+ * @param current - version installée, ou `null` si le paquet est absent.
+ * @param latest - dernière version publiée.
+ * @returns la sévérité du saut ; `"patch"` quand les versions sont illisibles (on ne suppose pas le pire).
+ */
+export declare function classifySeverity(current: string | null, latest: string): OutdatedSeverity;
+/**
+ * Agrège le document de `npm outdated --json` en une ligne par paquet.
+ *
+ * Deux corrections que le brut n'apporte pas : les dépendants sont regroupés au lieu
+ * d'être répétés, et un paquet dont la version installée DÉPASSE celle du registre est
+ * mis à part — c'est le cas d'un espace de travail local non publié, que `npm` présente
+ * comme un retard alors que c'est une avance.
+ *
+ * @param report - le document rendu par `npm outdated --json` (objet vide si rien).
+ * @returns le résumé trié, avec les comptes par catégorie.
+ */
+export declare function aggregateOutdated(report: NpmOutdatedReport): IOutdatedSummary;
+/**
+ * Résume la liste des dépendants pour l'affichage.
+ *
+ * @param dependents - noms des espaces de travail qui réclament le paquet.
+ * @param all - `true` pour tous les nommer, `false` pour n'en garder que le compte au-delà de trois.
+ * @returns une chaîne courte, jamais une énumération de vingt lignes.
+ */
+export declare function formatDependents(dependents: string[], all: boolean): string;
+/**
+ * Compose les lignes du tableau des paquets en retard.
+ *
+ * Rendu PUR : aucune écriture, aucune couleur — l'appelant décide de la sortie.
+ *
+ * @param summary - le résumé produit par {@link aggregateOutdated}.
+ * @param all - `true` pour nommer tous les dépendants.
+ * @returns une ligne par paquet : nom, saut, actuel, souhaité, dernier, dépendants.
+ */
+export declare function toTableRows(summary: IOutdatedSummary, all?: boolean): string[][];
+/**
+ * Compose la phrase d'en-tête qui dit ce qui a été trouvé — et ce qui a été agrégé.
+ *
+ * Nommer le nombre d'entrées brutes n'est pas décoratif : c'est ce qui explique
+ * pourquoi la sortie tient en quelques lignes là où `npm` en rend des dizaines.
+ *
+ * @param summary - le résumé produit par {@link aggregateOutdated}.
+ * @returns la phrase à afficher au-dessus du tableau.
+ */
+export declare function formatHeadline(summary: IOutdatedSummary): string;

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

@@ -0,0 +1,349 @@
+/**
+ * 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.
+ */
+export declare const BRAILLE_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** Tourniquet ASCII — le repli quand la police ne porte pas le braille. */
+export declare const LINE_FRAMES: readonly ["-", "\\", "|", "/"];
+/** Arcs tournants — plus discret que le braille, même encombrement. */
+export declare const ARC_FRAMES: readonly ["◜", "◠", "◝", "◞", "◡", "◟"];
+/** Barres montantes — suggère une activité qui « pompe ». */
+export declare const BLOCK_FRAMES: readonly ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "▆", "▅", "▄", "▃", "▂"];
+/** Points qui s'ajoutent — le plus sobre, et le seul purement ASCII. */
+export declare const DOT_FRAMES: readonly ["   ", ".  ", ".. ", "..."];
+/** Paire de caractères d'une barre : ce qui est fait, ce qui reste. */
+export interface IBarStyle {
+    readonly filled: string;
+    readonly empty: string;
+}
+/** Styles de barre prêts à l'emploi. */
+export declare const BAR_STYLES: {
+    /** `▰▰▰▱▱` — le défaut, lisible et compact. */
+    readonly blocks: {
+        readonly filled: "▰";
+        readonly empty: "▱";
+    };
+    /** `███░░` — dense, bon contraste sur fond sombre. */
+    readonly solid: {
+        readonly filled: "█";
+        readonly empty: "░";
+    };
+    /** `===--` — purement ASCII, pour un terminal pauvre ou un journal. */
+    readonly ascii: {
+        readonly filled: "=";
+        readonly empty: "-";
+    };
+    /** `●●●○○` — pour un petit nombre d'unités qu'on veut compter à l'œil. */
+    readonly dots: {
+        readonly filled: "●";
+        readonly 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).
+ */
+export declare function supportsUnicode(env?: NodeJS.ProcessEnv, platform?: string): boolean;
+/**
+ * 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.
+ */
+export declare function shouldAnimate(stream: NodeJS.WriteStream, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * 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.
+ */
+export declare function fitToWidth(line: string, columns: number | undefined): string;
+/** Réglages de {@link renderBar}. */
+export interface IRenderBarOptions {
+    /** Largeur en cellules. Défaut : 20. */
+    readonly width?: number;
+    /** Caractères plein/vide. Défaut : {@link BAR_STYLES.blocks}. */
+    readonly style?: IBarStyle;
+}
+/**
+ * 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 }); // "==--"
+ * ```
+ */
+export declare function renderBar(done: number, total: number, options?: IRenderBarOptions): string;
+/**
+ * Met en forme une durée pour un humain : `840ms`, `12.3s`, `4m 05s`.
+ *
+ * @param ms - durée en millisecondes
+ */
+export declare function formatDuration(ms: number): string;
+/** Réglages communs à toutes les formes. */
+export interface ILiveLineOptions {
+    /** Flux de sortie. Défaut : `process.stdout`. */
+    readonly stream?: NodeJS.WriteStream;
+    /**
+     * Forcer ou interdire l'animation, court-circuitant {@link shouldAnimate}.
+     *
+     * À ne poser que pour éprouver le comportement : en usage normal, c'est
+     * l'environnement qui décide, et lui seul sait s'il est une forge.
+     */
+    readonly animate?: boolean;
+    /** Environnement à interroger. Défaut : `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+}
+/**
+ * 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}.
+ */
+export declare abstract class LiveLine {
+    protected readonly stream: NodeJS.WriteStream;
+    /** Vrai entre `start()` et `stop()`, même hors terminal. */
+    protected active: boolean;
+    /** Résultat de {@link shouldAnimate}, résolu UNE fois à la construction. */
+    protected readonly interactive: boolean;
+    constructor(options?: ILiveLineOptions);
+    /** Vrai si l'on peut dessiner en place — terminal, hors forge, `TERM` utile. */
+    get isInteractive(): boolean;
+    /** Vrai entre `start()` et `stop()`. */
+    get running(): boolean;
+    /**
+     * 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?: string): void;
+    /** Masque le curseur au premier indicateur qui anime, et le compte. */
+    protected claimCursor(): void;
+    /** Arrête la mécanique propre à la forme (minuteur, compteurs). */
+    protected abstract halt(): void;
+    /** Efface la ligne courante puis écrit la nouvelle. Muet hors terminal. */
+    protected paint(text: string): void;
+    /** Ramène le curseur en début de ligne et efface ce qui s'y trouvait. */
+    protected erase(): void;
+}
+/**
+ * Rendu d'une ligne animée : c'est le CONSOMMATEUR qui décide du contenu.
+ *
+ * @param frame - l'image courante du tourniquet
+ * @param label - le libellé courant
+ * @returns la ligne complète, SANS retour à la ligne
+ */
+export type SpinnerRenderer = (frame: string, label: string) => string;
+/** Réglages d'un {@link Spinner}. */
+export interface ISpinnerOptions extends ILiveLineOptions {
+    /** Cadence de l'animation en millisecondes. Défaut : 80. */
+    readonly intervalMs?: number;
+    /** Images du tourniquet. Défaut : {@link BRAILLE_FRAMES}. */
+    readonly frames?: readonly string[];
+    /** Rendu de la ligne. Défaut : `"  <image> <libellé>…"`. */
+    readonly render?: SpinnerRenderer;
+}
+/**
+ * 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)})`);
+ * ```
+ */
+export declare class Spinner extends LiveLine {
+    #private;
+    constructor(options?: ISpinnerOptions);
+    /** Vrai si l'animation tourne RÉELLEMENT (donc sur un terminal). */
+    get animating(): boolean;
+    /**
+     * 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: string): void;
+    /**
+     * Change le libellé sans interrompre l'animation.
+     *
+     * @param label - le nouveau libellé
+     */
+    setLabel(label: string): void;
+    /** Redessine tout de suite, sans attendre la prochaine image. */
+    refresh(): void;
+    protected halt(): void;
+}
+/** Ce qu'un rendu de barre reçoit pour composer sa ligne. */
+export interface IProgressState {
+    /** Unités faites. */
+    readonly done: number;
+    /** Unités attendues. */
+    readonly total: number;
+    /** Rapport `done/total`, borné à `[0, 1]` ; `0` si le total est nul. */
+    readonly ratio: number;
+    /** La barre déjà dessinée par {@link renderBar}. */
+    readonly bar: string;
+    /** Libellé courant. */
+    readonly label: string;
+    /** Image du tourniquet, ou `""` si `spin` est faux. */
+    readonly frame: string;
+    /** Millisecondes écoulées depuis {@link ProgressBar.start}. */
+    readonly elapsedMs: number;
+}
+/** Rendu d'une ligne de progression. */
+export type ProgressRenderer = (state: IProgressState) => string;
+/** Réglages d'une {@link ProgressBar}. */
+export interface IProgressBarOptions extends ILiveLineOptions {
+    /** Largeur de la barre. Défaut : 20. */
+    readonly width?: number;
+    /** Caractères plein/vide. Défaut : {@link BAR_STYLES.blocks}. */
+    readonly style?: IBarStyle;
+    /**
+     * Ajoute un tourniquet en tête, animé indépendamment de l'avancement.
+     *
+     * À poser quand l'avancement peut rester longtemps immobile : la barre dit
+     * OÙ l'on en est, le tourniquet dit que ça VIT encore. Sans lui, une étape
+     * lente est indiscernable d'un blocage.
+     */
+    readonly spin?: boolean;
+    /** Cadence du tourniquet, en millisecondes. Défaut : 80. */
+    readonly intervalMs?: number;
+    /** Images du tourniquet. Défaut : {@link BRAILLE_FRAMES}. */
+    readonly frames?: readonly string[];
+    /** Rendu de la ligne. Défaut : `"  <barre> <faits>/<total> <libellé>"`. */
+    readonly render?: ProgressRenderer;
+}
+/**
+ * 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`);
+ * ```
+ */
+export declare class ProgressBar extends LiveLine {
+    #private;
+    constructor(options?: IProgressBarOptions);
+    /** Unités faites. */
+    get done(): number;
+    /** Unités attendues. */
+    get total(): number;
+    /** Vrai si le tourniquet tourne réellement. */
+    get animating(): boolean;
+    /**
+     * Démarre la progression.
+     *
+     * @param total - unités attendues
+     * @param label - libellé facultatif
+     */
+    start(total: number, label?: string): void;
+    /**
+     * Pose l'avancement à une valeur absolue.
+     *
+     * @param done - unités faites
+     * @param label - nouveau libellé, facultatif
+     */
+    update(done: number, label?: string): void;
+    /**
+     * Avance de `step` unités.
+     *
+     * @param step - pas d'avancement. Défaut : 1.
+     */
+    increment(step?: number): void;
+    /** Change le total en cours de route (une découverte, un lot qui grossit). */
+    setTotal(total: number): void;
+    /** Change le libellé sans toucher à l'avancement. */
+    setLabel(label: string): void;
+    protected halt(): void;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export declare function findProjectRoot(from: string): string | null;

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

@@ -0,0 +1,22 @@
+/**
+ * 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
+ */
+export declare function askPasswordMasked(question: string): Promise<string>;

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

@@ -0,0 +1,102 @@
+/**
+ * La porte UNIQUE par laquelle une commande pose une question.
+ *
+ * ⭐ Elle existe pour une raison qu'aucune commande ne peut résoudre seule :
+ * **attendre une réponse humaine ne retient pas Node.**
+ *
+ * Une question est une promesse en attente. Node ne compte pas les promesses —
+ * il compte les HANDLES actifs (sockets, timers, serveurs). Une commande qui
+ * boote une application en a des dizaines, si bien que la question tient sans
+ * que personne n'y pense. Une commande « standalone » — celles que le CLI sert
+ * sans démarrer quoi que ce soit, précisément pour être rapides — n'en a
+ * AUCUN : l'attente d'une frappe est alors la seule chose qui reste, et Node
+ * conclut qu'il n'a plus rien à faire. Le process s'arrête **au milieu de la
+ * question**, sans erreur, avec un code de sortie nul, en laissant tout au plus
+ * un `Detected unsettled top-level await`.
+ *
+ * Le symptôme se lit « la commande meurt toute seule » et se diagnostique comme
+ * un délai d'attente qui n'existe pas. Il ne se manifeste que là où l'on a
+ * travaillé à ne rien démarrer, donc il frappe les commandes les plus soignées,
+ * et jamais celles qui bootent — ce qui achève de brouiller la piste.
+ *
+ * D'où cette porte : elle pose un handle le temps de la question, et le retire
+ * ensuite. Une commande n'a pas à y penser ; elle n'a même pas à savoir que le
+ * problème existe. La règle vit ici, une fois — l'écrire dans chaque commande
+ * garantirait qu'elle manque un jour dans la dernière écrite.
+ *
+ * ⚠️ Ne JAMAIS importer `@inquirer/prompts` directement dans une commande.
+ * C'est ce qui recrée le défaut, en silence, dans un endroit qu'on ne relira
+ * pas.
+ */
+/**
+ * Retient l'event loop, et rend de quoi le relâcher.
+ *
+ * Un intervalle **non `unref()`** est le handle le plus léger qui fasse
+ * l'affaire : il ne consomme rien (son échéance est hors de portée), il ne
+ * réveille jamais le process, et il compte comme travail en cours pour Node.
+ * L'intervalle est volontairement énorme — ce n'est pas un timer, c'est une
+ * ancre.
+ *
+ * @returns la fonction qui relâche l'ancre ; l'appeler deux fois est sans effet.
+ */
+export declare function anchorEventLoop(): () => void;
+/**
+ * Exécute une interaction utilisateur en retenant l'event loop.
+ *
+ * ⚠️ L'ancre se relâche dans un `finally` : une question interrompue (Ctrl+C,
+ * flux fermé, refus) doit rendre la main comme une question aboutie, sinon on
+ * troque une commande qui meurt trop tôt contre une commande qui ne rend jamais
+ * la main — le défaut symétrique, et plus pénible encore.
+ *
+ * @param interaction - ce qui pose la ou les questions.
+ * @returns ce que l'interaction rend.
+ */
+export declare function request<T>(interaction: () => Promise<T>): Promise<T>;
+/** Les questions servies par cette porte — le sous-ensemble réellement utilisé. */
+export interface IPrompts {
+    confirm: (config: {
+        message: string;
+        default?: boolean;
+    }) => Promise<boolean>;
+    select: <T>(config: {
+        message: string;
+        choices: readonly unknown[];
+        default?: T;
+    }) => Promise<T>;
+    checkbox: (config: {
+        message: string;
+        choices: readonly unknown[];
+    }) => Promise<unknown[]>;
+    input: (config: {
+        message: string;
+        default?: string;
+    }) => Promise<string>;
+}
+/**
+ * Charge les prompts — import DYNAMIQUE, et c'est délibéré.
+ *
+ * Le paquet pèse ; une commande non interactive (`--json`, un script de forge)
+ * ne doit pas le payer. Le chargement est idempotent : Node met le module en
+ * cache, les appels suivants ne coûtent rien.
+ *
+ * @returns les questions disponibles.
+ */
+export declare function chargePrompts(): Promise<IPrompts & Record<string, unknown>>;
+/**
+ * Interface `readline` ANCRÉE — même garantie, pour le front natif du scaffold.
+ *
+ * Le scaffold de `create app` ne passe pas par `@inquirer/prompts` : il pose ses
+ * questions en `node:readline/promises`, sans aucune dépendance. Le besoin est
+ * pourtant identique, et l'exposition la même — `create app` est servi sans rien
+ * démarrer. Fournir la fabrique ICI évite d'écrire l'ancre à la main là-bas :
+ * une règle qu'on doit se rappeler d'appliquer est une règle qui manquera un
+ * jour.
+ *
+ * @param input - flux d'entrée (injectable pour les bancs).
+ * @param output - flux de sortie.
+ * @returns l'interface, et la fermeture qui relâche AUSSI l'ancre.
+ */
+export declare function ouvreReadline(input: NodeJS.ReadableStream, output: NodeJS.WritableStream): Promise<{
+    rl: import("node:readline/promises").Interface;
+    close: () => void;
+}>;

package/dist/types/cli/scaffold/destination.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Où une NOUVELLE application a le droit de naître, quand la création est pilotée par
+ * une interface web (Studio) plutôt que par une ligne de commande.
+ *
+ * ## Le problème
+ *
+ * En CLI, la destination est le `cwd` de l'utilisateur : il est chez lui, il assume. Sur
+ * le web, la destination arrive par le réseau — et un endpoint qui écrit au chemin qu'on
+ * lui donne écrit aussi dans `/etc`, `~/.ssh` ou `node_modules`. Un champ « chemin
+ * absolu » serait une porte ouverte, quel que soit le rôle exigé derrière.
+ *
+ * ## La règle
+ *
+ * Le client ne transmet JAMAIS un chemin. Il choisit :
+ *  - une **racine autorisée**, par identifiant (le serveur seul connaît son chemin réel) ;
+ *  - un **sous-dossier** relatif, dont chaque segment est validé ;
+ *  - un **nom d'app**, validé par la même expression que le moteur.
+ *
+ * Le serveur RECOMPOSE la destination et vérifie qu'elle reste **sous la racine**. Tout
+ * le reste est refusé — `..`, chemin absolu, segment vide, caractère exotique.
+ *
+ * Ces fonctions sont **pures** (aucun accès disque) : la protection contre les liens
+ * symboliques se fait chez l'appelant, en résolvant les chemins réels AVANT de les passer
+ * ici (cf {@link isInsideRoot}).
+ */
+/** Nom d'application — même expression que la spec du scaffold (`spec.ts`). */
+export declare const APP_NAME_RE: RegExp;
+/** Racine autorisée : un espace de travail où l'on a le droit de créer une app. */
+export interface IScaffoldRoot {
+    /** Identifiant opaque manipulé par le client (jamais un chemin). */
+    id: string;
+    /** Libellé affiché. */
+    label: string;
+    /** Chemin réel côté serveur — ne sort JAMAIS tel quel vers un client non admin. */
+    path: string;
+}
+/**
+ * Le sous-chemin proposé est-il navigable sans danger ?
+ *
+ * @param sub - chemin relatif (`""` = la racine elle-même), séparé par `/`.
+ * @returns `true` si chaque segment est acceptable et qu'aucun ne remonte.
+ */
+export declare function isSafeSubPath(sub: string): boolean;
+/**
+ * `child` est-il À L'INTÉRIEUR de `root` ?
+ *
+ * Comparaison sur les chemins **normalisés**, avec le séparateur final : sans lui,
+ * `/home/user/app-secrets` passerait pour un enfant de `/home/user/app`. La racine
+ * elle-même n'est pas « à l'intérieur » (on ne crée pas une app SUR sa racine).
+ *
+ * ⚠️ Passer ici des chemins RÉELS (`realpathSync`) quand ils existent : sinon un lien
+ * symbolique placé dans la racine ferait sortir l'écriture de l'espace autorisé sans que
+ * cette comparaison n'y voie rien.
+ */
+export declare function isInsideRoot(root: string, child: string): boolean;
+/** Erreur de destination — message sûr, affichable tel quel (jamais un chemin serveur). */
+export declare class ScaffoldDestinationError extends Error {
+}
+/**
+ * Recompose la destination d'une nouvelle app, ou refuse.
+ *
+ * @param roots - racines autorisées (côté serveur).
+ * @param rootId - identifiant de racine choisi par le client.
+ * @param sub - sous-dossier relatif choisi (`""` = la racine).
+ * @param name - nom de l'app.
+ * @returns le chemin absolu où l'app doit naître.
+ * @throws {ScaffoldDestinationError} racine inconnue, sous-chemin ou nom refusé, ou
+ *   destination hors de la racine.
+ */
+export declare function resolveScaffoldDestination(roots: readonly IScaffoldRoot[], rootId: string, sub: string, name: string): string;