--- title: "Référence d'API — nodefony — kernel" source: docs/api/core/kernel.md url: https://nodefony.github.io/nodefony-core/docs/api/core/kernel/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › kernel > Générée depuis les déclarations de types publiées de `nodefony` **10.0.0-beta.5** : exactement ce que reçoit une application qui l'installe. Cette page n'existe dans aucun dépôt — pour la corriger, on corrige le TSDoc du code. ## `nodefony` `import { … } from "nodefony"` — 42 symboles. ### Classes (4) #### `BootConfigurationError` ```ts class BootConfigurationError extends Error ``` Erreur de **configuration** détectée pendant le boot — TOUJOURS fatale, dans TOUS les environnements et pour TOUT module, là où un échec de boot ordinaire n'est fatal qu'en production pour un module critique (fail-soft ailleurs). - `name: string` - `exitCode: number` — Code de sortie du process — `EX_CONFIG` (78), pas le `EX_SOFTWARE` (70) par défaut. - `static is(error: unknown): boolean` — Type guard TOLÉRANT aux copies multiples du package (dual-package / bundles) : reconnaît l'instance OU toute `Error` portant le `name` de la classe — un `instanceof` seul raterait une erreur construit … #### `CliKernel` ```ts class CliKernel extends Cli ``` Kernel spécialisé pour les invocations CLI (`npx nodefony `). - `runProfile: IRunProfile` - `app: Module | null` - `packageManager: PackageManager` - `quietBoot: boolean` — 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é … - `constructor(environment?: EnvironmentType)` - `setPackageManager(manager?: PackageManagerName, dir?: string): PackageManager` — Sélectionne le lanceur du gestionnaire de paquets (`nodefony install`). - `showHelp(quit: boolean, context: HelpContext): void | never` - `parseCommand(argv?: string[]): commanderCommand` — Parse argv synchroniquement via Commander (cf `parseCommandAsync` pour async). - `parseCommandAsync(argv?: string[]): Promise` — Parse argv et exécute la commande matched (peut être async — `.action(async () => ...)`). - `start(options?: TypeKernelOptions): Promise` — Boot complet : instancie le Kernel, enregistre les commandes built-in, parse argv, lance `kernel.start()`. - `registerBuiltinCommands(): void` — Enregistre les commandes built-in dans commander (idempotent : skip si déjà fait). - `writeCompletionManifest(cwd?: string): Promise` — É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. - `buildBuiltinManifest(): ICliManifest` — Manifest de complétion construit en MÉMOIRE depuis commander (sans cache) — fallback du fast-path `__complete` hors projet. - `getBuiltinCommandNames(): Set` — Noms + alias des commandes built-in déjà enregistrées dans commander. - `setRunProfile(profile: IRunProfile): IRunProfile` — Définit le profil d'exécution du run (cf `IRunProfile`) — déclaré par les commandes serveur/daemon. - `resolveCommand(command: Command, args: unknown[]): void` — Point UNIQUE de résolution d'une commande matchée — appelé par le callback commander de `Command` (parse pur : le match ne fait que signaler) et par `StartCommand` (sélection interactive). - `addCommand(cliCommand: new (cli: CliKernel) => Command): Command` — Enregistre une commande CLI dans le registre du CliKernel + Commander. - `loadLocalModule(moduleName: string, cwd?: string): Promise | null>` — Charge dynamiquement un module ES depuis le filesystem local. - `initSyslog(environment?: EnvironmentType, debug?: DebugType, options?: conditionsInterface): void | null` — Configure le pipeline Syslog selon environnement et mode debug. - `terminate(code?: number, quiet?: boolean): Promise` — Arrêt propre — délègue à `kernel.terminate()` si kernel présent, sinon `super.terminate()`. #### `Kernel` ```ts class Kernel extends Service implements IKernel ``` Orchestrateur central de Nodefony — gère le boot, les modules, le DI Container racine, et expose les events lifecycle auxquels services/modules se branchent. - `options: TypeKernelOptions` — Options du kernel — le type précis du champ hérité de `Service`. - `Events: Readonly` - `runProfile: IRunProfile` - `version: string` - `started: boolean` - `booted: boolean` - `ready: boolean` - `postReady: boolean` - `get suppressBootBanners(): boolean` — Supprime les bannières serveurs sous l'écran de boot animé — détenu par `SupervisorLink`, lu et écrit ici comme un champ. - `set suppressBootBanners(value: boolean)` — Supprime les bannières serveurs sous l'écran de boot animé — détenu par `SupervisorLink`, lu et écrit ici comme un champ. - `trunk: trunkType` - `appName: string` — Nom du paquet de l'application, lu par `resolveAppEntry` dans la même lecture de `package.json` — connu dès `loadApp`, avant que le module app ne charge le sien (`onPreBoot`). - `core: boolean` - `command: Command | null` - `commandArgs: CommandArgs` - `preRegistered: boolean` - `registered: boolean` - `app: Module | null` - `cli: CliKernel | null` - `environment: EnvironmentType` — Mode MOTEUR par défaut, quand RIEN ne le dit. - `debug: DebugType` - `appEnvironment: AppEnvironmentType` - `path: string` - `get typeCluster(): ClusterType` — Rôle dans la topologie — détenu par `KernelCluster`, lu et écrit ici comme un champ. - `set typeCluster(value: ClusterType)` — Rôle dans la topologie — détenu par `KernelCluster`, lu et écrit ici comme un champ. - `get pid(): number` — PID de ce processus — détenu par `KernelCluster`. - `set pid(value: number)` — PID de ce processus — détenu par `KernelCluster`. - `get workerId(): number` — Identifiant du worker (`undefined` dans le primaire) — détenu par `KernelCluster`. - `set workerId(value: number)` — Identifiant du worker (`undefined` dans le primaire) — détenu par `KernelCluster`. - `get worker(): Worker` — Le worker courant (`undefined` dans le primaire) — détenu par `KernelCluster`. - `set worker(value: Worker)` — Le worker courant (`undefined` dans le primaire) — détenu par `KernelCluster`. - `console: boolean` - `isTTY: boolean` — Vrai terminal disponible ? - `node_start: NodefonyStartType` - `platform: NodeJS.Platform` - `projectName: string` - `uptime: number` - `numberCpu: number` - `modules: Record` - `tmpDir?: FileClass` — Répertoire temporaire du projet (`/tmp`), initialisé au boot. - `varDir?: FileClass` — Répertoire des données runtime **persistées** (`/var`) — base commune des stores fichier (passkeys, TOTP, sessions) et bases SQLite. - `get interfaces(): NetworkInterface` — Instantané des interfaces réseau de la machine — détenu par `KernelNetwork`, lu et écrit ici comme un champ. - `set interfaces(interfaces: NetworkInterface)` — Instantané des interfaces réseau de la machine — détenu par `KernelNetwork`, lu et écrit ici comme un champ. - `domain: string` - `progress: number` - `injector: Injector` - `isDev: boolean` - `isProd: boolean` - `get reporterOwnsHeader(): boolean` — Le BootReporter possède l'en-tête de boot (dev) — détenu par `SupervisorLink`, lu et écrit ici comme un champ. - `set reporterOwnsHeader(value: boolean)` — Le BootReporter possède l'en-tête de boot (dev) — détenu par `SupervisorLink`, lu et écrit ici comme un champ. - `get devHeaderDeferred(): boolean` — Bandeau de démarrage différé au BootReporter (dev) — détenu par `SupervisorLink`, lu et écrit ici comme un champ. - `set devHeaderDeferred(value: boolean)` — Bandeau de démarrage différé au BootReporter (dev) — détenu par `SupervisorLink`, lu et écrit ici comme un champ. - `constructor(environment: EnvironmentType, cli?: CliKernel | null, options?: TypeKernelOptions)` - `start(): Promise` — Point d'entrée du boot — et POINT DE PASSAGE UNIQUE de l'échec de démarrage. - `preRegister(): Promise` — Phase pré-registration — fire `"onPreRegister"` puis `"onRegister"`. - `boot(): Promise` — Phase boot — fire `"onPreBoot"` puis `"onBoot"`. - `onReady(): Promise` — Phase ready — fire `"onReady"`, démarre les serveurs HTTP/WS via `initServers()`, log memoryUsage, puis fire `"onPostReady"`. - `initServers(): Promise` — Démarre les serveurs HTTP/HTTPS/HTTP2/WS/WSS via le `HttpKernel` (@nodefony/http). - `park(opts?: { keepAlive?: boolean; }): Promise` — Parke le flow : retourne une Promise qui ne se résout JAMAIS (met en pause le pipeline async appelant). - `clean(): void` — Libère les ressources — retire les listeners trackés du bus partagé pour éviter les fuites mémoire, puis détache container/kernel/syslog/nc. - `setCommand(command: Command): void` - `setDomain(): string` - `readConfig(config?: TypeKernelOptions): TypeKernelOptions` - `addService(service: ServiceConstructor, module: Module, ...args: unknown[]): Promise` - `addKernelService(service: ServiceConstructor, ...args: unknown[]): Promise` — Instancie un service au niveau kernel (vs niveau module via `Module.addService`). - `loadService(service: string, module?: Module | null, ...args: unknown[]): Promise` - `loadModule(moduleName: string): Promise` — Charge un module du manifeste. - `getModuleConfigEntry(packageName: string): IModuleConfigEntry` — Configuration figée d'un module et sa liste blanche de surcharge, par nom de paquet (`"@nodefony/http"`). - `replaceModuleOptions(mod: Module, options: Record): void` — Remplace la configuration FIGÉE d'un module par une nouvelle, déjà gelée — la seule façon de la changer après `onReady` (édition à chaud en développement). - `addModule(Mod: ModuleConstructor, ...args: unknown[]): Promise` — Instancie un module et l'enregistre dans `kernel.modules[name]`. - `getModule(name: string): Module` — Module enregistré sous ce nom. - `getModules(): Record` - `get infra(): IInfra` — Infra déclarée (`database`/`cache`/`logs`) résolue depuis `process.env` (modèle « infra déclarée »). - `get storeResolutions(): IStoreResolution[]` — Résolutions EFFECTIVES des stores de persistance capturées au boot — la vérité vécue (replis annoncés inclus). - `registerStoreResolution(resolution: Omit): void` — Enregistre la résolution effective d'une brique (idempotent par `brick`). - `resolveAppEntry(): string | null` — Résout le point d'entrée de l'application depuis SON `package.json` (champ `main` — la source de vérité Node), fallback legacy `dist/index.js` puis `index.js`. - `isTrunk(): Promise` - `mainWorktreeRoot(): string | null` — Racine du dépôt PRINCIPAL quand ce dossier est un worktree git — sinon `null`. - `diagnoseUnbootableProject(): string | null` - `isCore(): Promise` - `isModule(subclass: unknown): boolean` - `getEventName(event: number): string` - `setCommandComplete(progress: number): boolean` - `isCommandComplete(progress: number): boolean` - `initializeLog(): void | null` — Monte le journal du noyau : sink, drivers du Log Backplane, transports d'écriture, seuils de sévérité, puis démarre la sortie console du Syslog. - `setCli(cli?: CliKernel | null): CliKernel | null` - `isConsole(): boolean` - `setNodeEnv(environment: EnvironmentType): void` - `resolveRuntimeEnv(fromCommand?: EnvironmentType): "development" | "production"` — Résout le **mode runtime** (dev/prod) : `NODE_ENV` (ambient, posé par l'orchestrateur en cloud) PRIME sur l'intention de la commande locale, qui prime sur la valeur courante. - `setEnv(environment?: EnvironmentType): void` - `startupOutputMode(): StartupOutputMode` — Rendu du démarrage demandé (`--output`, `NF_OUTPUT`, sinon le terminal) — délégué à `SupervisorLink.startupOutputMode`. - `frameworkVersion(): string` — Version du paquet `nodefony` qui tourne, jamais celle de l'application — délégué à `SupervisorLink.frameworkVersion`. - `devHeader(): string` — Bannière de développement, rendue pour la largeur actuelle du terminal — délégué à `SupervisorLink.devHeader`. - `printDevHeader(): void` — Imprime la bannière de développement (`devHeader`) en tête du boot. - `logEnv(): string` — Bannière `SERVER` (profil, rôle cluster, environnements, debug) — délégué à `KernelCluster.logEnv`. - `clusterIsMaster(): boolean` — `true` dans le processus primaire du cluster — délégué à `KernelCluster.clusterIsMaster`. - `initCluster(): void` — Entrée dans le cluster, à `preRegister` : pid, bannière `SERVER`, `MODULE ADD` différés (SOUS la bannière), `onCluster`, puis — worker — écoute des messages de contrôle du primaire. - `fire(event: KernelEventsType, ...args: unknown[]): boolean` — Alias `emit` — émet l'événement de manière synchrone. - `emit(event: KernelEventsType, ...args: unknown[]): boolean` — Émet l'événement (API EventEmitter standard). - `emitAsync(event: KernelEventsType, ...args: unknown[]): Promise` — Émet et attend les listeners async — équivalent de `fireAsync`. - `fireAsync(event: KernelEventsType, ...args: unknown[]): Promise` — Émet l'événement et attend que tous les listeners async résolvent. - `getBootReport(): IBootReport` — Verdict agrégé du dernier boot (vérité unique, recalculable à la demande pour l'introspection Studio/IA). - `get readinessBlocked(): number` — Nombre de composants qui retiennent la mise en service — `0` = disponible. - `get servable(): boolean` — Ce processus a-t-il le droit de recevoir du trafic ? - `setReadiness(name: string, ready: boolean, reason?: string, blocking?: boolean, action?: string): void` — Pose le verdict de disponibilité d'un composant nommé — un schéma de base en retard, un cache froid, un service tiers muet. - `clearReadiness(name: string): void` — Retire un contributeur du registre — sa voix ne compte plus. - `readinessReport(): IReadinessContributor[]` — Restitue l'état de chaque contributeur — pour un diagnostic (journal, `status`, console d'administration), jamais pour la sonde. - `reportBootLine(phase: string, line: string): void` — Déclare une ligne de détail à afficher SOUS une phase de boot (canal NEUTRE dev-only : le `BootReporter` la rend ; le core ne connaît pas son contenu). - `reportBootNotice(notice: IBootNotice): void` — Déclare un point d'attention du démarrage — ce qui manque ou s'est dégradé, dit par le module qui le CONSTATE, avec le geste qui le corrige. - `reportBootLink(link: IBootLinkDeclaration): void` — Déclare une adresse à ouvrir, par son CHEMIN : le noyau la résout contre l'origine de l'application (hôte et port viennent de la configuration, que le module n'a pas à connaître). - `setBootLines(phase: string, lines: string[]): void` — REMPLACE les lignes de détail d'une phase (vs `reportBootLine` qui AJOUTE). - `getBootLines(phase: string): string[]` — Lignes de détail déclarées pour une phase de boot (vide si aucune). - `fireLifecycle(event: KernelEventsType, ...args: unknown[]): Promise` — Émet une phase de **lifecycle de boot** de façon GARDÉE (cf `Event.emitAsyncGuarded`) : chaque hook de module est isolé par try/catch + timeout ; un module qui throw ou se fige ne gèle/ne tue plus tou … - `guardServiceInitialize(serviceInit: ServiceWithInit, owner: Module | Kernel, critical: boolean): Promise` — Initialise un service **sous garde de boot** (timeout + politique de criticité via `guardInitialize`) si le service expose le hook `init`. - `serviceBootErrorFatal(error: unknown, serviceName: string, critical: boolean): boolean` — Applique la politique de criticité du boot à l'échec d'un service déclaré via `@services([...])` — **construction (`new`) comprise**, pas seulement `init`. - `checkPath(myPath: string): string | null` - `sendMessage(message: unknown, handle?: SendHandle, options?: { swallowErrors?: boolean; keepOpen?: boolean; }, callback?: (error: Error | null) => void): boolean` — Enveloppe IPC héritée (`type: "process:msg"`) vers le processus parent — délégué à `KernelCluster.sendMessage` (hors du canal `nf-dev`). - `memoryUsage(message?: string, severity?: Severity): void` - `stats(): Stats` - `interfacesFilter(filters?: FilterInterface): NetworkInterface` — Filtre l'instantané des interfaces — délégué à `KernelNetwork.interfacesFilter` (contrat et piège d'origine inclus). - `getNetworkInterfaces(): { [name: string]: os.NetworkInterfaceInfo[]; }` - `getNetwork(): import("nodefony").KernelNetworkResult` - `getFirstExternalInterface(family?: FamilyType): os.NetworkInterfaceInfo` - `terminate(code?: number, quiet?: boolean): Promise` — Shutdown propre du kernel — fire `"onTerminate"` puis `CliKernel.quit(code)` sur next tick. #### `Module` ```ts class Module> extends Service implements IModule ``` Unité fonctionnelle de Nodefony — successeur direct du concept "Bundle" (Symfony / Nodefony JS). - `commands: Record` - `static controllers: Partial>>` - `static critical: boolean` — Criticité du module pour la **résilience de boot** (Phase 3). - `package?: PackageJson` - `path: string` - `isApp: boolean` - `appOptions: DefaultOptionsService | null` — Ce que l'APPLICATION a posé sur ce module par `use(name, config)` — et rien d'autre. - `onKernelRegister?(): Promise` - `onKernelBoot?(): Promise` - `onKernelReady?(): Promise` - `init?(kernel?: IKernel): Promise` - `getMcpTools?(): IMcpTool[]` — Outils que ce module ajoute à la porte MCP de l'application — cf `IModule.getMcpTools`. - `overlaySchema: ZodType | null` — Liste blanche des clés de configuration qu'une requête peut surcharger (`overlayConfig`) : un schéma Zod STRICT, en général `configSchema.pick({...}).partial()`. - `constructor(name: string, kernel: Kernel, path: string, options: DefaultOptionsService)` - `configSchema(): unknown` — Schéma JSON (`z.toJSONSchema`) de la configuration du module, ou `null` si le module n'est pas (encore) migré vers une validation Zod. - `get config(): TConfig` — Config **validée + gelée** du module — point d'accès UNIFORME et typé. - `setPath(myPath: string): string` — Résout le chemin source du module (`module.path`) — normalise URL `file://`, remonte au-dessus de `dist/` si nécessaire. - `gePath(name?: string): string` - `static getModulePath(name: string): string` — Résout le chemin d'installation d'un module npm via `require.resolve`. - `setEvents(): void` — Câble les hooks lifecycle (`onKernelRegister/Boot/Ready`) sur le kernel parent. - `hookKernel(event: string, listener: (...args: never[]) => unknown): this` — Pose un hook de cycle de vie du kernel **au nom de ce module** — donc avec sa politique de boot (propriétaire + criticité), comme les hooks de classe. - `applyAppConfig(config: DefaultOptionsService): DefaultOptionsService` — Applique la configuration colocalisée de l'application (`use(name, config)`) sous les défauts du module, AVANT sa validation Zod — et la RETIENT. - `readOverrideModuleConfig(deep?: boolean): DefaultOptionsService` - `registerService(service: ServiceConstructor, name: string): ServiceConstructor` - `addService(service: ServiceConstructor, ...args: unknown[]): Promise` — Instancie un service via l'`Injector` et l'enregistre dans le container du module. - `handleServiceBootError(error: unknown, service: string | ServiceConstructor): void` — Politique d'échec d'un service déclaré via `@services([...])` : la MÊME que pour le reste du boot — fatal en production (ou sur une erreur de configuration), fail-soft **ANNONCÉ** ailleurs (agrégé au … - `getServiceNames(): string[]` — Noms des services enregistrés par ce module (ordre d'ajout). - `loadService(service: string, ...args: unknown[]): Promise` — Charge dynamiquement un service depuis un chemin (`import()`) puis l'enregistre via `addService`. - `getPackageJson(cwd?: string): Promise` - `getController(name: string): TypeController` — Récupère un controller enregistré **dans ce module**. - `getControllers(): Record>` — Retourne les controllers enregistrés **pour ce module** (clés = nom de classe nu, préfixe module retiré). - `getDependencies(): string[]` — Liste les dépendances + peerDependencies du module (depuis son `package.json`). - `static getPackageDependencies(mypackage: PackageJson | null): string[]` — Variante static — extrait les deps depuis un `package.json` arbitraire. - `getModuleName(): string` - `getModuleVersion(): string` - `addCommand(cliCommand: new (cli: CliKernel) => Command): Command | void` — Enregistre une commande CLI custom rattachée à ce module. - `install(force?: boolean): Promise` — Exécute `npm install` (ou yarn/pnpm) dans le dossier du module. - `outdated(): Promise` — Exécute `npm outdated` dans le dossier du module. - `loadJson(url: string, cwd?: string): Promise` — Lit un fichier JSON dont la racine doit être un objet. - `log(pci: any, severity?: Severity, msgid?: Msgid, msg?: Message): Pdu` — Surcharge `Service.log` — `msgid` défaut = `"MODULE "` pour identifier les logs de ce module dans le pipeline Syslog. ### Fonctions (11) #### `connectorMigrationsDir` ```ts function connectorMigrationsDir(appDir: string, connector: string): string ``` Dossier des migrations PROPRES à un connecteur — la seule règle qui dit où elles vivent. #### `connectorVersionsMigrations` ```ts function connectorVersionsMigrations(connector: string, appDir: string, list?: IListMigrationsDir): boolean ``` Des migrations versionnées CONCERNENT-elles ce connecteur ? #### `isReservedConnectorName` ```ts function isReservedConnectorName(connector: string): boolean ``` Le nom de ce connecteur collisionne-t-il avec un dossier de dialecte ? #### `overlayField` ```ts function overlayField(field: T): ZodType, output> ``` Retire le défaut d'un champ de schéma, pour le réutiliser dans une LISTE BLANCHE de surcharge (`Module.overlaySchema`). #### `ownsSharedMigrations` ```ts function ownsSharedMigrations(connector: string): boolean ``` Ce connecteur possède-t-il les migrations du framework et de l'application ? #### `parseModuleConfig` ```ts function parseModuleConfig(schema: ZodType, input: unknown, packageName: string): T ``` Valide la configuration d'un module contre son schéma Zod, et transforme un refus en `BootConfigurationError` nommant le module et la clé fautive. #### `parseStoreManifest` ```ts function parseStoreManifest(raw: unknown): IStoreManifest | null ``` Lit la déclaration `nodefony` d'un `package.json` déjà analysé. #### `runNeedsExternalServices` ```ts function runNeedsExternalServices(kernel: { runProfile?: IRunProfile | null; } | null): boolean ``` Ce run a-t-il DÉCLARÉ avoir besoin de l'infrastructure de l'application ? #### `runWorksOnSchema` ```ts function runWorksOnSchema(kernel: { runProfile?: IRunProfile | null; } | null): boolean ``` Ce run travaille-t-il le schéma de la base ? Point d'appel UNIQUE de la question. #### `storeConnectivity` ```ts function storeConnectivity(kernel: { runProfile?: IRunProfile | null; } | null): IStoreConnectivity ``` Les briques du framework peuvent-elles, dans ce run, résoudre leur store `auto` vers un backend CONNECTÉ (base, cache) — et sinon, pourquoi ? #### `versionsMigrations` ```ts function versionsMigrations(dir: string, list?: IListMigrationsDir): boolean ``` Ce dossier versionne-t-il au moins une migration ? ### Constantes (5) #### `CONSOLE_DATA_RUN_PROFILE` ```ts const CONSOLE_DATA_RUN_PROFILE: Readonly ``` Profil d'une commande console qui a besoin de l'infrastructure — `orm:migrate`, `security:user:add`, tout ce qui LIT ou ÉCRIT des données. #### `CONSOLE_RUN_PROFILE` ```ts const CONSOLE_RUN_PROFILE: Readonly ``` Profil par défaut — équivaut à l'ancien `type = "CONSOLE"` (one-shot, sans serveur). #### `CONSOLE_SCHEMA_RUN_PROFILE` ```ts const CONSOLE_SCHEMA_RUN_PROFILE: Readonly ``` Profil d'une commande qui TRAVAILLE le schéma (`orm:generate`, `orm:migrate`…) : connectée, mais sans schéma dérivé au démarrage ni store durable `auto`. Cf `IRunProfile.schemaWork`. #### `FRAMEWORK_SQL_CONNECTOR` ```ts const FRAMEWORK_SQL_CONNECTOR = "default" ``` Connecteur SQL conventionnel qui héberge le schéma du framework et des entités de l'application (`"default"` pour Drizzle ; Mongoose a le sien). #### `RESERVED_MIGRATION_DIRS` ```ts const RESERVED_MIGRATION_DIRS: readonly string[] ``` Noms qui ne peuvent PAS désigner le dossier d'un connecteur secondaire : ce sont ceux des dossiers de dialecte (et du journal) que le connecteur du framework range déjà sous `migrations/`. Un connecteur `postgres` y lirait les migrations de `default` comme les siennes. ### Interfaces (17) #### `FilterInterface` ```ts interface FilterInterface ``` - `type?: "local" | "external"` - `family?: FamilyType` - `condition?: "&&" | "||" | "=="` #### `IBootFailure` ```ts interface IBootFailure ``` Un module ignoré ou en échec **non fatal** pendant le boot (fail-soft). Agrégé par le Kernel pour expliquer, en une ligne par module, pourquoi le boot est dégradé — au lieu de N WARNING enterrés dans le JSONL. - `module: string` — Nom du module/service en échec (tag `owner`, ou nom d'entrée du manifeste). - `reason: string` — Message d'erreur condensé (1ʳᵉ ligne). - `phase: "load" | "lifecycle" | "init"` — Étape du boot où l'échec s'est produit : - `load` — `import()` du module (manifeste) a throw (ex. - `timedOut?: boolean` — `true` si l'échec est un dépassement du timeout de boot. #### `IBootLink` ```ts interface IBootLink ``` Une adresse à OUVRIR — ce que le développeur tape dans son navigateur. - `id: string` — Clé stable en anglais (`app`, `studio`) — lue par la machine. - `label: string` — Libellé affiché (`Application`, `Studio`). - `url: string` — URL complète. #### `IBootLinkDeclaration` ```ts interface IBootLinkDeclaration ``` Déclaration d'un lien par un module : un CHEMIN, que le noyau résout contre l'origine de l'application. Le module ne connaît ni le port ni l'hôte — et ne doit pas les connaître : ils changent avec la configuration. - `id: string` — Clé stable en anglais. - `label: string` — Libellé affiché. - `path: string` — Chemin absolu sur l'application (`/nodefony`). #### `IBootModuleGated` ```ts interface IBootModuleGated ``` Un module du manifeste **volontairement NON chargé** par le gating `policy`/`when` de `config.modules`. Ce n'est PAS un échec (cf `IBootFailure`) — mais un gating silencieux se lit comme un module perdu : le bilan de boot l'affiche AVEC sa raison pour que le dev sache pourquoi son module manque. - `module: string` — Nom d'entrée du manifeste (`config.modules`). - `reason: string` — Raison lisible du non-chargement (ex. #### `IBootNotice` ```ts interface IBootNotice ``` Un point d'attention du démarrage — CE QUI MANQUE OU S'EST DÉGRADÉ, dit par le module qui le constate, avec le geste qui le corrige. - `code: string` — Identifiant stable, en majuscules (`FIREWALL_PUBLIC_ROUTES`). - `level: BootNoticeLevel` — Gravité — décide du symbole et de l'ordre d'affichage. - `message: string` — Le constat, en une phrase. - `fix?: string` — Le geste qui corrige, prêt à coller (commande ou config) — absent s'il n'y en a pas. #### `IBootReport` ```ts interface IBootReport ``` Verdict agrégé du dernier boot. `healthy=false` ⇒ le boot est raté ou dégradé de façon bloquante (typiquement : profil serveur attendu mais 0 serveur en écoute). - `durationMs: number` — Durée approximative du boot (ms). - `modulesLoaded: string[]` — Modules effectivement chargés et enregistrés. - `manifestEntries: number` — Nombre d'entrées DÉCLARÉES au manifeste `config.modules`, avant tout gating. - `modulesSkipped: IBootFailure[]` — Modules ignorés/échoués en fail-soft (avec la raison). - `modulesGated: IBootModuleGated[]` — Modules volontairement non chargés (gating `policy`/`when`) — pas des échecs. - `warnings: number` — Logs `WARNING` émis pendant le boot (comptés dans le ring buffer syslog ; figés à `onPostReady`, comptage à la volée tant que le boot est en cours). - `errors: number` — Logs `ERROR` et pire (`CRITIC`/`ALERT`/`EMERGENCY`) émis pendant le boot. - `criticals: string[] | null` — Les PREMIERS de ces messages, condensés — `null` quand il n'y en a aucun. - `serversExpected: boolean` — `true` si le profil d'exécution attendait des serveurs réseau. - `serversListening: IBootServerInfo[]` — Serveurs réellement en écoute. - `healthy: boolean` — Verdict global : `false` si un profil serveur a fini sans aucun serveur en écoute (garde-fou 0-serveur). - `remediation?: string` — Action corrective suggérée d'après les raisons d'échec (ex. - `open: IBootLink[]` — Adresses à OUVRIR (application, puis les liens déclarés par les modules) — vide sans serveur web. - `notices: IBootNotice[]` — Points d'attention, triés du plus urgent au détail — constatés par le noyau (`collectBootNotices`) ou déclarés par les modules. #### `IBootServerInfo` ```ts interface IBootServerInfo ``` Un serveur réseau réellement en écoute à la fin du boot. - `type: string` — Identité du serveur — son schéma d'URI (`http` | `https` | `ws` | `wss`). - `scheme: string` — Scheme d'URL court et conventionnel (`http` | `https` | `ws` | `wss`). - `port: number` — Port d'écoute effectif. - `address?: string` — Adresse de bind (`127.0.0.1`, `0.0.0.0`…), si connue. - `url: string` — URL complète d'accès (`scheme://host:port`) — cliquable au terminal. #### `IMigrationsDirEntry` ```ts interface IMigrationsDirEntry ``` Une entrée de dossier, telle que la rend `IListMigrationsDir`. - `readonly name: string` - `readonly isDirectory: boolean` #### `IReadinessContributor` ```ts interface IReadinessContributor ``` Un contributeur et son verdict, tels qu'un diagnostic les restitue. - `readonly name: string` — Nom du contributeur — celui qui apparaît au journal et au diagnostic. - `readonly ready: boolean` — Verdict déjà calculé : `false` retient la mise en service. - `readonly reason?: string` — Ce qui retient, en clair — absent quand le contributeur est prêt. - `readonly blocking?: boolean` — Ce verdict retient-il le trafic ? - `readonly action?: string` — Le geste qui lèverait ce verdict, prêt à taper (`"nodefony orm:migrate"`). #### `IRunProfile` ```ts interface IRunProfile ``` Profil d'exécution d'un run — remplace l'ancien binaire `KernelType` (SERVER/CONSOLE) qui écrasait 3 axes orthogonaux en un seul drapeau. Déclaré par chaque commande. - `servers: boolean` - `lifetime: RunLifetime` - `interactive: boolean` - `externalServices: boolean` — Ce run a-t-il besoin de l'infrastructure de l'application ? - `schemaWork?: boolean` — Ce run TRAVAILLE le schéma de la base — écrire, appliquer, lire l'état des migrations (`orm:*`) ? #### `IStoreManifest` ```ts interface IStoreManifest ``` Ce qu'un module DÉCLARE, dans son `package.json`, de son rapport aux magasins du framework (sessions, jetons, passkeys, audit, 2FA, idempotence). - `provides: boolean` — Le module FOURNIT des magasins (la clé `nodefony.stores` est déclarée). - `storeKind: "durable" | "cache"` — Nature des magasins fournis. - `stores: string[]` — Briques couvertes — `session`, `user`, `tokens`, `audit`, `totp`… - `consumesStores: boolean` — Le module CONSOMME les magasins des autres à son propre démarrage — il doit donc être déclaré APRÈS eux dans le manifeste `modules`. #### `KernelNetworkResult` ```ts interface KernelNetworkResult ``` Résultat de `Kernel.getNetwork()` — définition UNIQUE, ré-exportée par `types/IKernel.ts` (ce module feuille n'importe rien du noyau : aucun cycle). - `external: Record` - `local: Record` - `ipv4: Record` - `ipv6: Record` - `interfaces: Record` #### `NetworkInterface` ```ts interface NetworkInterface ``` - `[name: string]: os.NetworkInterfaceInfo[]` #### `ServiceConstructor` ```ts interface ServiceConstructor ``` - `new (...args: any[]): ServiceWithInit` - `_inject?: { [key: number]: string; }` #### `ServiceWithInit` ```ts interface ServiceWithInit extends Service ``` Interface-marqueur du **hook de cycle de vie async de boot** (pattern NestJS `OnModuleInit`). Un service qui implémente `init` est initialisé une fois au démarrage — par `Kernel.addKernelService` (service kernel) ou `Module.addService` (service de module) — sous garde de boot (`Kernel.guardInitialize` : timeout + politique de criticité). - `init?(owner?: Module | Kernel): Promise` #### `TypeKernelOptions` ```ts interface TypeKernelOptions extends DefaultOptionsService ``` - `node_start?: NodefonyStartType` - `domain?: string` — Domaine public du kernel ; `"selectAuto"` = première interface externe. - `packageManager?: PackageManagerName` — Gestionnaire de paquets des commandes d'installation. - `modules?: IModuleManifest` — Manifeste déclaratif des modules de l'app (liste ordonnée, gatable par `policy`/`when`/environnement). - `shutdownDeadline?: number` — Deadline GLOBALE du shutdown (ms) — cf `AppConfigInput.shutdownDeadline` (config/types.ts). - `log?: { active?: boolean; dir?: string; debug?: DebugType; buffered?: boolean | "auto"; driver?: "stdout" | "file" | "null"; format?: "text" | "json"; file?: { path?: string; sync?: boolean; }; queryD …` ### Types (5) #### `BootNoticeLevel` ```ts type BootNoticeLevel = "error" | "warning" | "info" ``` Gravité d'un point d'attention du démarrage, de la plus urgente à la moins urgente : `error` bloque (✗), `warning` est à corriger (⚠), `info` renseigne (ℹ). #### `FamilyType` ```ts type FamilyType = "IPv4" | "IPv6" ``` #### `IListMigrationsDir` ```ts type IListMigrationsDir = (dir: string) => readonly IMigrationsDirEntry[] ``` Lit les entrées d'un dossier — injectable : le démarrage lit le disque, le générateur lit sa transaction (fichiers en attente compris). #### `KernelEventsType` ```ts type KernelEventsType = keyof EventsType ``` #### `RunLifetime` ```ts type RunLifetime = "oneshot" | "longrunning" ``` Durée de vie d'un run : `"oneshot"` = fait sa tâche puis le process sort (build, install, help) ; `"longrunning"` = reste vivant jusqu'à un signal (serveur, daemon, REPL) — maintenu soit par un socket en écoute, soit par un park explicite. --- [← Toutes les références d'API](../../)