nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/types/kernel/CliKernel.d.ts

@@ -0,0 +1,289 @@
+import { conditionsInterface } from "../syslog/Syslog.js";
+import Cli, { PackageManagerName } from "../Cli.js";
+import Kernel, { IRunProfile, TypeKernelOptions } from "./Kernel.js";
+import Command from "../command/Command.js";
+import { type ICliManifest } from "../cli/completion.js";
+import { DebugType, EnvironmentType } from "../types/globals.js";
+import Module from "./Module.js";
+import { HelpContext, Command as commanderCommand } from "commander";
+type ModuleWithDefault<T> = {
+    default?: T;
+};
+export type PackageManager = (argv: string[], cwd?: string, env?: EnvironmentType) => Promise<number | Error>;
+/**
+ * Kernel spécialisé pour les invocations CLI (`npx nodefony <command>`).
+ *
+ * **N'étend PAS {@link Kernel}** mais {@link Cli} (Commander wrapper). Le `Kernel` applicatif
+ * est instancié séparément par {@link start} et linké à `this.kernel`. Sa raison d'être :
+ * parser argv via Commander, sélectionner une commande, configurer l'environnement
+ * (`SERVER` vs `CONSOLE`), puis déléguer au `Kernel` pour le boot.
+ *
+ * **Piège lifecycle connu** : `environment` peut être `undefined` au constructor — les
+ * sous-commandes le set dans leur hook `onKernelStart()`. Ne jamais conditionner du code
+ * sur `this.environment` dans le constructor.
+ *
+ * @example
+ * ```ts
+ * // bin/nodefony.ts
+ * import { CliKernel } from "nodefony";
+ * const cli = new CliKernel();
+ * await cli.start();   // boote le Kernel + parse argv + exécute la command
+ * ```
+ */
+declare class CliKernel extends Cli {
+    runProfile: IRunProfile;
+    app: Module | null;
+    packageManager: PackageManager;
+    /**
+     * Boot SILENCIEUX : pour les commandes CLI utilitaires (help global, commandes
+     * de module type `frontend:status`) dont la sortie doit être propre — les logs
+     * de cycle de vie (NOTICE/INFO/DEBUG) sont coupés, seuls EMERGENCY..ERROR
+     * surfacent (cf {@link initSyslog}). Mis à `true` par {@link dispatchGlobalHelp}
+     * et {@link dispatchModuleCommand}. `-d/--debug` rétablit le détail.
+     */
+    quietBoot: boolean;
+    /**
+     * @param environment - environnement initial (`"development"` / `"production"` / `"test"`).
+     *   Peut être `undefined` — sera set par la sous-commande dans `onKernelStart()`.
+     */
+    constructor(environment?: EnvironmentType);
+    /**
+     * Sélectionne le package manager pour les commandes `install`/`outdated`.
+     *
+     * @param manager - `"npm"` / `"yarn"` / `"pnpm"`. Défaut = `this.options.packageManager` (pnpm).
+     * @returns la fonction package manager liée à `this`.
+     */
+    setPackageManager(manager?: PackageManagerName): PackageManager;
+    showHelp(quit: boolean, context: HelpContext | undefined): void | never;
+    /**
+     * Parse argv synchroniquement via Commander (cf {@link parseCommandAsync} pour async).
+     *
+     * @param argv - args (défaut `process.argv`).
+     * @returns instance Commander après parse.
+     */
+    parseCommand(argv?: string[]): commanderCommand;
+    /**
+     * Parse argv et exécute la commande matched (peut être async — `.action(async () => ...)`).
+     *
+     * @param argv - args (défaut `process.argv`).
+     * @returns Promise résolue avec l'instance Commander après exécution.
+     */
+    parseCommandAsync(argv?: string[]): Promise<commanderCommand>;
+    /**
+     * Boot complet : instancie le Kernel, enregistre les commandes built-in, parse argv,
+     * lance `kernel.start()`.
+     *
+     * Comportement Commander :
+     * - `--help` / `--version` → terminate(0) propre
+     * - Erreur Commander (option/commande inconnue) → terminate(1) + re-throw —
+     *   **JAMAIS de fallback serveur** (legacy supprimé : une erreur de parse ne doit
+     *   pas démarrer un runtime).
+     * - Exception kernel → terminate(1) puis re-throw
+     *
+     * @param options - options surchargées pour le `new Kernel(env, this, options)`.
+     * @returns le Kernel booté.
+     * @throws Si Commander absent OR si kernel.start() crash.
+     */
+    start(options?: TypeKernelOptions): Promise<Kernel>;
+    /**
+     * Enregistre les commandes built-in dans commander (idempotent : skip si déjà
+     * fait). Ordre = ordre des groupes dans le help (Commander rend les groupes dans
+     * l'ordre de 1ʳᵉ rencontre) : Serveur → Build → Projet → Console/jobs.
+     * Partagé entre `start()` et le fallback de complétion (built-ins sans boot).
+     */
+    registerBuiltinCommands(): void;
+    /**
+     * Écrit le manifest de complétion shell (cache par projet) depuis l'état COURANT
+     * de commander — appelé par le Kernel à `onPreRegister` en dev, une fois les
+     * commandes de module posées. Best-effort côté appelant (fire-and-forget).
+     */
+    writeCompletionManifest(cwd?: string): Promise<void>;
+    /**
+     * Manifest de complétion construit en MÉMOIRE depuis commander (sans cache) —
+     * fallback du fast-path `__complete` hors projet.
+     */
+    buildBuiltinManifest(): ICliManifest;
+    /**
+     * Nom de la commande demandée = premier token non-option de `process.argv`.
+     *
+     * `null` si aucun (invocation nue, `--help`, `--version`) → on retombe sur le
+     * flow built-in inchangé.
+     *
+     * @returns nom de commande demandé ou `null`.
+     */
+    private getRequestedCommandName;
+    /**
+     * `true` si l'invocation demande la **version globale** : `nodefony -v` ou
+     * `nodefony --version` (que des options, aucun positionnel).
+     *
+     * Un positionnel présent → la commande décide (`nodefony dev --version` n'est pas
+     * une demande de version du CLI) : on laisse commander trancher.
+     *
+     * @returns `true` si la version du CLI est demandée.
+     */
+    private isVersionRequested;
+    /**
+     * `true` si l'invocation demande le **help global** : `nodefony` nu,
+     * `nodefony --help` ou `nodefony -h` (que des options, aucun positionnel).
+     *
+     * Exclut volontairement `--version` (fast-path standalone, cf `isVersionRequested`)
+     * et `nodefony <cmd> --help` (help d'une sous-commande, laissé à commander / au
+     * dispatch de module — il y a un positionnel).
+     *
+     * @returns `true` si le help global est demandé.
+     */
+    private isGlobalHelpRequested;
+    /**
+     * Noms + alias des commandes built-in déjà enregistrées dans commander.
+     *
+     * Dérivé de commander (pas de liste en dur → suit l'ajout/retrait de built-ins).
+     * À appeler APRÈS `addCommand(...)` des built-ins et AVANT que les modules
+     * n'enregistrent les leurs.
+     *
+     * @returns set des noms et alias built-in.
+     */
+    getBuiltinCommandNames(): Set<string>;
+    /**
+     * Dispatch DIFFÉRÉ d'une commande de module.
+     *
+     * commander ignore la commande au boot (posée par le module à `onPreRegister`,
+     * chargé depuis `config.modules`). On parse donc argv depuis un listener
+     * `onPreRegister` lui-même posé via `onStart` : `loadApp()` (qui pose le listener
+     * `loadModulesFromManifest`) précède `onStart`, et `emitAsync` est séquentiel →
+     * notre listener tourne APRÈS le chargement des modules, donc quand toutes les
+     * commandes de module sont connues, mais
+     * AVANT les phases qu'elles ciblent (`onRegister`/`onReady`/…) → leur
+     * `kernel.once(kernelEvent)` fire normalement. Le kernel reste en mode CONSOLE
+     * (aucune commande serveur ne fixe `type=SERVER`) → 0 serveur démarré. Commande
+     * réellement introuvable (typo) → `terminate(1)`, jamais de fallback serveur.
+     *
+     * @param requested - nom de commande demandé (pour le message d'erreur).
+     * @returns le Kernel booté (terminé après exécution de la commande).
+     */
+    private dispatchModuleCommand;
+    /**
+     * Boote le kernel jusqu'à `onPreRegister` (modules instanciés → leurs commandes
+     * sont posées dans commander), affiche le help COMPLET puis `terminate(0)`.
+     *
+     * Même mécanique de timing que {@link dispatchModuleCommand} : le listener
+     * `onPreRegister` est posé depuis `onStart` pour passer APRÈS le chargement des modules
+     * (`emitAsync` séquentiel). Le kernel reste CONSOLE (aucune commande → 0 serveur)
+     * et `terminate(0)` stoppe le boot avant `onRegister` (process.exit au nextTick).
+     *
+     * Boot KO (hors d'une app, config invalide) → fallback : help built-in seul
+     * (déjà enregistré dans commander) + `terminate(0)`. L'utilisateur a toujours un help.
+     *
+     * @returns le Kernel (terminé après affichage du help).
+     */
+    private dispatchGlobalHelp;
+    /**
+     * L'aide des commandes INTÉGRÉES, sans démarrer quoi que ce soit.
+     *
+     * Le repli de {@link dispatchGlobalHelp} quand il n'y a pas d'application à
+     * interroger : hors de tout projet, ou dans une application qui n'est pas
+     * encore installée ni construite. Les commandes de module manqueront —
+     * personne ne peut les connaître sans charger les modules — et c'est dit.
+     *
+     * Sort en **0** : demander de l'aide n'est pas une erreur, et un code 1
+     * casse un `nodefony --help | less` autant qu'un script d'installation.
+     *
+     * @param kernel - le kernel, terminé après l'affichage.
+     * @returns le kernel.
+     */
+    private renderStandaloneHelp;
+    /**
+     * Les commandes qui répondent en JSON — la seule chose qu'un agent cherche
+     * d'abord, et que rien n'affichait.
+     *
+     * Écrite ici plutôt que dérivée d'un `--json` cherché dans les options : la
+     * moitié des commandes en portent un pour un usage local (un fragment, un
+     * fichier), et les lister toutes noierait celles qui rendent un DOCUMENT
+     * exploitable. La liste est courte et se relit d'un coup d'œil.
+     */
+    private static readonly JSON_COMMANDS;
+    /**
+     * Compose le modèle d'aide depuis commander, et l'écrit.
+     *
+     * 🔴 Le modèle se lit sur COMMANDER, jamais sur `cli.commands` : les
+     * commandes de module ne sont pas dans ce registre (elles s'enregistrent
+     * directement dans commander depuis `Module`), et c'est ce trou qui faisait
+     * déjà perdre des commandes au menu. Le groupe voyage donc avec la commande,
+     * posé par son constructeur (`OptionsCommandInterface.helpGroup`).
+     *
+     * @param extra - une note de situation, quand l'aide est rendue hors d'une
+     *   application ou dans une application non installée.
+     */
+    private writeHelp;
+    /**
+     * Définit le profil d'exécution du run (cf {@link IRunProfile}) — déclaré par les
+     * commandes serveur/daemon. Le Kernel le recopie depuis `cli.runProfile` à `onStart`.
+     *
+     * @param profile - profil à appliquer (`servers`/`lifetime`/`interactive`).
+     * @returns le profil appliqué.
+     */
+    setRunProfile(profile: IRunProfile): IRunProfile;
+    /**
+     * Point UNIQUE de résolution d'une commande matchée — appelé par le callback
+     * commander de {@link Command} (parse pur : le match ne fait que signaler) et par
+     * `StartCommand` (sélection interactive).
+     *
+     * Fait, dans l'ordre :
+     * 1. lie la commande au Kernel (`kernel.command` / `kernel.commandArgs`) ;
+     * 2. applique le **profil déclaré** (`command.runProfile`) s'il existe —
+     *    `setRunProfile` resynchronise AUSSI `kernel.runProfile`, donc une commande
+     *    résolue APRÈS `onStart` (commande de module, posée à `onPreRegister`) peut
+     *    être serveur : la décision de monter les serveurs se joue plus tard
+     *    (`onReady → initServers`) ;
+     * 3. câble les hooks lifecycle + l'exécution à `kernelEvent` (`setEvents`).
+     *
+     * @param command - commande matchée.
+     * @param args - arguments produits par le parse commander.
+     */
+    resolveCommand(command: Command, args: unknown[]): void;
+    /**
+     * Enregistre une commande CLI dans le registre du CliKernel + Commander.
+     *
+     * @param cliCommand - constructeur de la commande (signature `new (cli: CliKernel) => Command`).
+     * @returns instance de la commande créée.
+     */
+    addCommand(cliCommand: new (cli: CliKernel) => Command): Command;
+    /**
+     * Charge dynamiquement un module ES depuis le filesystem local.
+     *
+     * Résout les chemins relatifs par rapport à `cwd`. Capture les erreurs d'import et les log
+     * en ERROR avant de les re-throw.
+     *
+     * @param moduleName - chemin absolu OR relatif vers le module à importer.
+     * @param cwd - racine pour résoudre `moduleName` (défaut `process.cwd()`).
+     * @returns export default du module ou `null`.
+     * @throws L'erreur d'import est re-throw après log.
+     */
+    loadLocalModule<T>(moduleName: string, cwd?: string): Promise<ModuleWithDefault<T> | null>;
+    /**
+     * Configure le pipeline Syslog selon environnement et mode debug.
+     *
+     * Sans kernel attaché → délègue à {@link Cli.initSyslog} parent. Avec kernel :
+     * - Sévérités `[0..6]` (EMERGENCY..INFO) toujours
+     * - `+7` (DEBUG) si `debug === true` OR `this.debug`
+     * - `+4, +5` (WARNING, NOTICE) si type === SERVER et env === development
+     * - mode MACHINE (`--json`) ou {@link quietBoot} → `[0..3]` seulement, que
+     *   `Syslog.rawLog` dirige vers la sortie d'erreur : le flux de données reste
+     *   pur, et un échec reste lisible.
+     *
+     * Le `pid` est ajouté en préfixe de chaque ligne SAUF en dev mono-process.
+     *
+     * @param environment - environnement (override de `this.environment`).
+     * @param debug - active sévérité DEBUG (override de `this.debug`).
+     * @param options - conditions de filtrage Syslog custom.
+     */
+    initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): void | null;
+    /**
+     * Arrêt propre — délègue à `kernel.terminate()` si kernel présent, sinon `super.terminate()`.
+     *
+     * @param code - exit code Unix (0 = succès, 1+ = erreur). Défaut `0`.
+     * @param quiet - supprime les messages de terminaison si `true`.
+     */
+    terminate(code?: number, quiet?: boolean): Promise<void>;
+}
+export type CommandConstructor = new (cli: CliKernel) => Command;
+export default CliKernel;