--- title: "Référence d'API — nodefony — cli" source: docs/api/core/cli.md url: https://nodefony.github.io/nodefony-core/docs/api/core/cli/ --- [Documentation](../../../) › [Référence d'API](../../) › [`nodefony`](../) › cli > 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"` — 150 symboles. ### Classes (5) #### `EntityFieldError` ```ts class EntityFieldError extends Error ``` Erreur de syntaxe dans la déclaration d'un champ — message actionnable. #### `LiveLine` ```ts abstract class LiveLine ``` Une ligne de terminal qu'on réécrit en place. - `protected readonly stream: NodeJS.WriteStream` - `protected active: boolean` — Vrai entre `start()` et `stop()`, même hors terminal. - `protected readonly interactive: boolean` — Résultat de `shouldAnimate`, résolu UNE fois à la construction. - `constructor(options?: ILiveLineOptions)` - `get isInteractive(): boolean` — Vrai si l'on peut dessiner en place — terminal, hors forge, `TERM` utile. - `get running(): boolean` — Vrai entre `start()` et `stop()`. - `stop(finalLine?: string): void` — Arrête et fige éventuellement une ligne à la place de celle qui vivait. - `protected claimCursor(): void` — Masque le curseur au premier indicateur qui anime, et le compte. - `protected abstract halt(): void` — Arrête la mécanique propre à la forme (minuteur, compteurs). - `protected paint(text: string): void` — Efface la ligne courante puis écrit la nouvelle. - `protected erase(): void` — Ramène le curseur en début de ligne et efface ce qui s'y trouvait. #### `ProgressBar` ```ts class ProgressBar extends LiveLine ``` Progression **déterminée** : on connaît le total, on montre où l'on en est. - `constructor(options?: IProgressBarOptions)` - `get done(): number` — Unités faites. - `get total(): number` — Unités attendues. - `get animating(): boolean` — Vrai si le tourniquet tourne réellement. - `start(total: number, label?: string): void` — Démarre la progression. - `update(done: number, label?: string): void` — Pose l'avancement à une valeur absolue. - `increment(step?: number): void` — Avance de `step` unités. - `setTotal(total: number): void` — Change le total en cours de route (une découverte, un lot qui grossit). - `setLabel(label: string): void` — Change le libellé sans toucher à l'avancement. - `protected halt(): void` — Arrête la mécanique propre à la forme (minuteur, compteurs). #### `ScaffoldDestinationError` ```ts class ScaffoldDestinationError extends Error ``` Erreur de destination — message sûr, affichable tel quel (jamais un chemin serveur). #### `Spinner` ```ts class Spinner extends LiveLine ``` Attente **indéterminée** : on montre que ça vit, sans promettre de fin. - `constructor(options?: ISpinnerOptions)` - `get animating(): boolean` — Vrai si l'animation tourne RÉELLEMENT (donc sur un terminal). - `start(label: string): void` — Démarre l'attente sous un libellé. - `setLabel(label: string): void` — Change le libellé sans interrompre l'animation. - `refresh(): void` — Redessine tout de suite, sans attendre la prochaine image. - `protected halt(): void` — Arrête la mécanique propre à la forme (minuteur, compteurs). ### Fonctions (65) #### `agentRoot` ```ts function agentRoot(target: IAgentTarget, ctx: { projectRoot: string; home?: string; env?: Record; }): string ``` Racine où vit la configuration d'une cible : le projet, ou son dossier maison. #### `agentsPresents` ```ts function agentsPresents(ctx: { projectRoot: string; home?: string; env?: Record; exists: (filePath: string) => boolean; }): IAgentTarget[] ``` Agents dont la présence est CONSTATÉE sur ce poste. #### `alreadyHasKey` ```ts function alreadyHasKey(forme: IAgentTarget["forme"], content: string, key: string): boolean ``` #### `anchorEventLoop` ```ts function anchorEventLoop(): () => void ``` Retient l'event loop, et rend de quoi le relâcher. #### `argvMcpWiring` ```ts function argvMcpWiring(chosen: readonly string[], detected: readonly IAgentTarget[], dest: string, opts?: { token?: boolean; }): string[] | null ``` Traduit le choix d'agents de développement en appel `ai:mcp` — PURE. #### `askPasswordMasked` ```ts function askPasswordMasked(question: string): Promise ``` Demande un secret sans jamais l'ÉCHOTER — mot de passe, phrase de passe. #### `buildCard` ```ts function buildCard(input: ICardInput): ICard ``` Construit la carte de visite d'une application à partir de son état. #### `buildMcpUrl` ```ts function buildMcpUrl(origin: string, endpointPath: string): string ``` Compose l'URL de l'endpoint MCP. #### `capAllows` ```ts function capAllows(question: Pick, caps: IScaffoldCaps): boolean ``` La question est-elle posée dans CET environnement ? #### `chargePrompts` ```ts function chargePrompts(): Promise> ``` Charge les prompts — import DYNAMIQUE, et c'est délibéré. #### `contributionFingerprint` ```ts function contributionFingerprint(content: string | Uint8Array): string ``` L'empreinte d'un fichier livré : sha256 de ses octets, fins de ligne ramenées à `\n` pour un TEXTE (aucun octet nul). Sans cette normalisation, un dépôt extrait sous Windows avec `core.autocrlf` ferait passer chaque fichier intact pour retouché — donc jamais rafraîchi. #### `createAppContributionContext` ```ts function createAppContributionContext(appRoot: string, options?: { appName?: string; dryRun?: boolean; update?: boolean; recorded?: Readonly>; }): { context: IAppContributionContext; written: string[]; kept: string[]; updated: string[]; outdated: string[]; modified: string[]; files: Record; } ``` Construit le contexte d'UNE contribution, qui consigne ce qu'elle pose et ce qu'elle laisse. #### `diffLines` ```ts function diffLines(before: string, after: string): IDiffLine[] ``` Diff ligne à ligne de deux contenus (plus longue sous-séquence commune). #### `escapeRoff` ```ts function escapeRoff(text: string): string ``` Échappe une chaîne pour roff. #### `findProjectRoot` ```ts function findProjectRoot(from: string): string | null ``` 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`. #### `fitToWidth` ```ts function fitToWidth(line: string, columns: number): string ``` Tronque une ligne à la largeur du terminal, séquences ANSI non comptées. #### `formatDuration` ```ts function formatDuration(ms: number): string ``` Met en forme une durée pour un humain : `840ms`, `12.3s`, `4m 05s`. #### `formatEntityField` ```ts function formatEntityField(field: IEntityField): string ``` Écrit un champ dans la grammaire de la ligne de commande — l'inverse exact de `parseEntityFields`. #### `getScaffoldContext` ```ts function getScaffoldContext(dir: string, writer?: ScaffoldWriter): IScaffoldContext | null ``` Lit le contexte du projet contenant `dir`. #### `getScaffoldSpec` ```ts function getScaffoldSpec(type?: string): IScaffoldTypeSpec[] ``` La spec complète du scaffold — contrat des trois fronts (CLI rapide, CLI interactif, Studio). Structure 100 % sérialisable en JSON. #### `guessOrigin` ```ts function guessOrigin(cwd: string): string ``` Déduit l'origine du serveur de développement. #### `hydrateQuestion` ```ts function hydrateQuestion(question: IScaffoldQuestion, context: IScaffoldContext | null): IScaffoldQuestion ``` Remplace les réponses possibles d'une question par celles du PROJET RÉEL. #### `installGitHooks` ```ts function installGitHooks(projectRoot: string, dryRun?: boolean): IGitHooksPlan | null ``` Pose les hooks natifs dans un projet, et rend le plan de ce qui a été fait. #### `isInsideRoot` ```ts function isInsideRoot(root: string, child: string): boolean ``` `child` est-il À L'INTÉRIEUR de `root` ? #### `isSafeSubPath` ```ts function isSafeSubPath(sub: string): boolean ``` Le sous-chemin proposé est-il navigable sans danger ? #### `isScaffoldStep` ```ts function isScaffoldStep(value: unknown): value is TScaffoldStep ``` Une étape connue ? (garde des entrées venues du réseau). #### `listTargets` ```ts function listTargets(projectRoot: string, writer?: ScaffoldWriter): [ IScaffoldTarget, ...IScaffoldTarget[] ] ``` #### `lookupSymbol` ```ts function lookupSymbol(graph: ISymbolsGraph, name: string): ISymbolEntry ``` Trouve un symbole par son nom exact. #### `mcpWiringPlan` ```ts function mcpWiringPlan(ctx: { chosen: number; installed: boolean; built: boolean; databaseUnreachable?: boolean; manager?: PackageManagerName; }): { propose: true; token: boolean; pattern?: string; } | { propose: false; pattern: string; } ``` Décide si `create app` CÂBLE la porte MCP chez les agents choisis. PURE. #### `needsShell` ```ts function needsShell(command: string, plateforme?: NodeJS.Platform, grammar?: Pick): boolean ``` Faut-il passer par le shell pour lancer cette commande ? #### `nodefonyBin` ```ts function nodefonyBin(since?: string): string ``` Le chemin du lanceur `nodefony`, tel que CETTE installation l'a reçu. #### `packageManagerCommandLines` ```ts function packageManagerCommandLines(name: PackageManagerName): { install: string; add: (pkg: string) => string; run: (script: string) => string; exec: (bin: string) => string; audit: string; } ``` Lignes de commande à AFFICHER pour un gestionnaire — ce qu'on conseille à l'utilisateur doit être ce que son outil accepte, et sortir de la même règle que ce qu'on exécute (`packageManagerExecArgs`). #### `packageManagerExecArgs` ```ts function packageManagerExecArgs(name: PackageManagerName, bin: string, args?: readonly string[]): string[] ``` Arguments qui lancent un BINAIRE installé dans le projet (`nodefony`, `vitest`…). #### `packageManagerToolchain` ```ts function packageManagerToolchain(name: PackageManagerName): IPackageManagerToolchain ``` Commandes d'installation, de cache et d'élagage d'un gestionnaire, pour la forge et pour l'image. #### `packageManagerUpdateInstallArgs` ```ts function packageManagerUpdateInstallArgs(name: PackageManagerName): string[] ``` Arguments d'une installation qui SUIT une modification du manifeste (`create app`, `create module`, une dépendance ajoutée). #### `parseEntityFields` ```ts function parseEntityFields(input: string): IEntityField[] ``` Analyse la déclaration textuelle des champs. #### `planAgentDeclaration` ```ts function planAgentDeclaration(target: IAgentTarget, ctx: Pick, remove?: boolean): IDeclarationPlan ``` Compose la déclaration de la porte MCP chez un agent. #### `planGitHooks` ```ts function planGitHooks(existing: Record, currentHooksPath: string | null, wantedHooksPath: string): IGitHooksPlan ``` Décide, pour chaque hook et pour `core.hooksPath`, le geste à faire. #### `planMcpConfig` ```ts function planMcpConfig(existing: IMcpConfigDocument | null, url: string, options?: { auth?: boolean; grammar?: IMcpGrammar; }): IMcpConfigPlan ``` Décide ce qu'il faut écrire dans `.mcp.json`. #### `portableSpawn` ```ts function portableSpawn(command: string, args: readonly string[], platform?: NodeJS.Platform, grammar?: Pick, comSpec?: string): IPortableSpawn ``` Compose la commande portable — voir `IPortableSpawn`. #### `poseVariable` ```ts function poseVariable(forme: IAgentTarget["forme"], current: string, key: string, value: string): string | Error ``` #### `readScaffoldLock` ```ts function readScaffoldLock(appRoot: string): Record ``` Lit le registre de provenance de l'application. #### `readSymbolsGraph` ```ts function readSymbolsGraph(from: string): ISymbolsGraph | null ``` Lit le graphe atteignable depuis `from` — celui du PROJET fusionné avec celui du framework INSTALLÉ —, ou `null` si aucun n'est lisible. #### `renderBar` ```ts function renderBar(done: number, total: number, options?: IRenderBarOptions): string ``` Dessine une barre de progression, et rien d'autre. #### `renderCard` ```ts function renderCard(card: ICard): string ``` Rend la carte pour un HUMAIN (ou un agent qui lit un terminal). #### `renderGitHook` ```ts function renderGitHook(name: GitHookName): string ``` Le contenu d'un hook. #### `renderGitHooksPlan` ```ts function renderGitHooksPlan(plan: IGitHooksPlan, applique: boolean): string ``` Rend le plan pour un humain. #### `renderManPage` ```ts function renderManPage(manifest: ICliManifest, version: string): string ``` Rend la page de manuel complète, en roff. #### `renderMcpPlan` ```ts function renderMcpPlan(plan: IMcpConfigPlan, file: string, dryRun: boolean): string ``` Rend le plan pour un lecteur humain. #### `renderPlanShell` ```ts function renderPlanShell(plan: IDeclarationPlan): string ``` Rend le plan sous la forme qu'on peut recopier dans un terminal. #### `request` ```ts function request(interaction: () => Promise): Promise ``` Exécute une interaction utilisateur en retenant l'event loop. #### `requestedAgents` ```ts function requestedAgents(raw: string): readonly IAgentTarget[] | Error ``` Traduit `--agent` en cibles, ou rend l'erreur à afficher. #### `resolveAnswers` ```ts function resolveAnswers(spec: IScaffoldTypeSpec, partial: TScaffoldAnswers, caps: IScaffoldCaps): TScaffoldAnswers ``` Complète et VALIDE des réponses partielles contre la spec d'un type : défauts appliqués, patterns vérifiés, choix contraints à leur liste. Le contexte des templates est donc complet PAR CONSTRUCTION (eta ne rend jamais un `undefined` silencieux). Les questions `askIf` non satisfaites sont forcées à `false` ; celles dont l'`askWhen` n'est pas satisfait retombent à leur DÉFAUT — une réponse qui porte sur ce qui ne sera pas généré n'a rien à décider. #### `resolvePackageManager` ```ts function resolvePackageManager(input?: { readonly configured?: PackageManagerName; readonly dir?: string; readonly userAgent?: string; readonly exists?: (file: string) => boolean; }): IPackageManagerResolution ``` Désigne le gestionnaire de paquets d'un projet (cf l'ordre des sources en tête de fichier). #### `resolveScaffoldDestination` ```ts function resolveScaffoldDestination(roots: readonly IScaffoldRoot[], rootId: string, sub: string, name: string): string ``` Recompose la destination d'une nouvelle app, ou refuse. #### `resolveSymbolsFile` ```ts function resolveSymbolsFile(from: string): string | null ``` Trouve le graphe symbolique utilisable depuis `from`. #### `runAiMcpCommand` ```ts function runAiMcpCommand(argv: string[]): Promise ``` Point d'entrée de la commande. #### `runAppContributions` ```ts function runAppContributions(appRoot: string, dryRun?: boolean, update?: boolean): Promise ``` Exécute les contributions des paquets installés dans une application : chaque paquet qui déclare `nodefony.contribute` dans son `package.json` y pose ses fichiers, sans jamais remplacer un fichier présent. #### `runGitHooksCommand` ```ts function runGitHooksCommand(argv: string[]): number ``` Commande `nodefony git:hooks` — hooks git natifs (`core.hooksPath`), zéro dépendance. #### `runScaffold` ```ts function runScaffold(request: IScaffoldRequest, version: string, options?: IScaffoldRunOptions): IScaffoldResult ``` Exécute un scaffold — point d'entrée UNIQUE des trois fronts (CLI rapide, CLI interactif, Studio), dispatché par type : - `app` : projet NEUF dans `request.dir` (layers base/preset/frontend) ; - `controller` : IN-PROJECT — `request.dir` est le point de départ de la détection de racine (cwd de l'appelant), la cible réelle vient de `answers.module` (vide = app racine). #### `runSymbolsCli` ```ts function runSymbolsCli(argv: string[]): Promise ``` Porte de la ligne de commande : `--generate` écrit le graphe de l'application, tout le reste le lit (`runSymbolsCommand`). #### `runSymbolsCommand` ```ts function runSymbolsCommand(argv: string[]): number ``` Commande `nodefony symbols` — le graphe, sans boot et sans dépôt. #### `scaffoldCaps` ```ts function scaffoldCaps(dir?: string): IScaffoldCaps ``` Capacités de l'environnement, telles que le MOTEUR les voit. #### `shouldAnimate` ```ts function shouldAnimate(stream: NodeJS.WriteStream, env?: NodeJS.ProcessEnv): boolean ``` Faut-il animer du tout ? #### `supportsUnicode` ```ts function supportsUnicode(env?: NodeJS.ProcessEnv, platform?: string): boolean ``` Le terminal sait-il dessiner du braille et des blocs ? ### Constantes (22) #### `AGENT_TARGETS` ```ts const AGENT_TARGETS: readonly IAgentTarget[] ``` Agents dont l'emplacement de secret a été CONSTATÉ — au comportement ou au source, jamais sur la foi d'une page de blog. #### `APP_NAME_RE` ```ts const APP_NAME_RE: RegExp ``` Nom d'application — même expression que la spec du scaffold (`spec.ts`). #### `ARC_FRAMES` ```ts const ARC_FRAMES: readonly [ "◜", "◠", "◝", "◞", "◡", "◟" ] ``` Arcs tournants — plus discret que le braille, même encombrement. #### `BAR_STYLES` ```ts const BAR_STYLES: { readonly blocks: { readonly filled: "▰"; readonly empty: "▱"; }; readonly solid: { readonly filled: "█"; readonly empty: "░"; }; readonly ascii: { readonly filled: "="; readonly empty: "-"; }; readonly dots: { readonly filled: "●"; readonly empty: "○"; }; } ``` Styles de barre prêts à l'emploi. #### `BLOCK_FRAMES` ```ts const BLOCK_FRAMES: readonly [ "▁", "▂", "▃", "▄", "▅", "▆", "▇", "▆", "▅", "▄", "▃", "▂" ] ``` Barres montantes — suggère une activité qui « pompe ». #### `BRAILLE_FRAMES` ```ts const BRAILLE_FRAMES: readonly [ "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" ] ``` Tourniquet braille — dix images, rotation fluide. Le défaut. #### `DOT_FRAMES` ```ts const DOT_FRAMES: readonly [ " ", ". ", ".. ", "..." ] ``` Points qui s'ajoutent — le plus sobre, et le seul purement ASCII. #### `ENTITY_FIELD_TYPES` ```ts const ENTITY_FIELD_TYPES: readonly [ "string", "text", "int", "float", "bool", "json", "date", "uuid", "enum", "char", "decimal" ] ``` Types de champ du vocabulaire Nodefony (jamais le vocabulaire Drizzle). #### `FRONTEND_CHOICES` ```ts const FRONTEND_CHOICES: readonly [ "none", "react", "vue", "angular", "svelte" ] ``` Frameworks front supportés par `@nodefony/frontend` (builder Vite multi-framework). #### `GIT_HOOKS_DIR` ```ts const GIT_HOOKS_DIR = ".githooks" ``` Dossier des hooks, relatif à la racine de l'application, écrit en `/`. #### `GIT_HOOKS_MARKER` ```ts const GIT_HOOKS_MARKER = "pos\u00E9 par `nodefony git:hooks`" ``` Marqueur d'APPARTENANCE, présent dans chaque hook généré. #### `GIT_HOOK_NAMES` ```ts const GIT_HOOK_NAMES: readonly [ "pre-commit", "pre-push" ] ``` Les hooks que la commande sait poser, dans l'ordre d'affichage. #### `LINE_FRAMES` ```ts const LINE_FRAMES: readonly [ "-", "\\", "|", "/" ] ``` Tourniquet ASCII — le repli quand la police ne porte pas le braille. #### `MAN_PAGE_NAME` ```ts const MAN_PAGE_NAME = "nodefony.1" ``` Nom de la page, section 1 (commandes utilisateur). #### `MCP_CONFIG_FILE` ```ts const MCP_CONFIG_FILE = ".mcp.json" ``` Fichier de configuration, à la racine du projet. #### `MCP_ENDPOINT_PATH` ```ts const MCP_ENDPOINT_PATH = "/nodefony/mcp" ``` Chemin de l'endpoint MCP. #### `MCP_SERVER_KEY` ```ts const MCP_SERVER_KEY = "nodefony" ``` Nom de la clé sous laquelle notre serveur est déclaré. #### `MCP_TOKEN_ENV` ```ts const MCP_TOKEN_ENV = "NF_MCP_TOKEN" ``` Nom de la variable d'environnement qui porte le jeton de la porte MCP. #### `SCAFFOLD_LOCK_FILE` ```ts const SCAFFOLD_LOCK_FILE = "scaffold.lock.json" ``` Le nom du registre de provenance, à la racine de l'application. #### `SCAFFOLD_STEPS` ```ts const SCAFFOLD_STEPS: readonly [ "install", "build", "typecheck" ] ``` Étapes possibles, dans leur ordre d'exécution naturel. #### `SCAFFOLD_STEP_COMMANDS` ```ts const SCAFFOLD_STEP_COMMANDS: Record ``` Arguments passés à `npm` pour chaque étape. #### `SCAFFOLD_STEP_LABELS` ```ts const SCAFFOLD_STEP_LABELS: Record ``` Ce que chaque étape apporte — affiché avant de la lancer. ### Interfaces (42) #### `IAgentTarget` ```ts interface IAgentTarget ``` Un agent de développement, et l'endroit où il lit ses variables. - `key: string` — Clé courte — ce que `--agent` accepte, et ce qu'une question propose. - `name: string` — Nom affiché. - `scope: "projet" | "utilisateur"` — Où vit sa configuration : dans le PROJET, ou dans le dossier de l'utilisateur. - `marker: string` — Ce dont la présence prouve que l'agent est utilisé — résolu selon `scope`. - `file: string` — Fichier à écrire — relatif au projet, ou au dossier de l'agent. - `forme: "json-env" | "dotenv"` — Grammaire du fichier. - `home?: string` — Variable qui déplace le dossier de l'agent — `VIBE_HOME`, `CODEX_HOME`. - `declaration: DeclarationChannel` — Par quelle voie sa configuration apprend l'existence de la porte MCP. - `mcpFile?: IAgentMcpFile` — Présent si et seulement si `declaration === "fichier-agent"`. - `bin?: string` — Exécutable de sa CLI — présent si et seulement si `declaration === "cli"`. - `argvAdd?: (ctx: IDeclarationContext) => string[]` — Arguments qui DÉCLARENT la porte, hors nom de l'exécutable. - `argvRemove?: () => string[]` — Arguments qui RETIRENT la déclaration. - `argvList?: () => string[]` — Arguments qui LISTENT les serveurs déclarés, quand la CLI sait le faire. - `noteAfter?: string` — Ce qu'il reste à faire APRÈS une déclaration réussie, quand l'agent pose une condition de son cru. - `instructions: { file: string; natif: boolean; proof: string; }` — Le fichier d'instructions que cet agent lit **d'office**, et s'il s'agit d'`AGENTS.md` lui-même. #### `IAppContributionContext` ```ts interface IAppContributionContext ``` Ce qu'une contribution reçoit : la racine de l'application et des gestes d'écriture qui ne REMPLACENT jamais un fichier existant. - `readonly appRoot: string` — Racine de l'application (chemin natif absolu). - `readonly appName: string` — Nom de l'application — le `name` de son `package.json`. - `readonly dryRun: boolean` — `true` : rien n'est écrit, le rapport dit ce qui le serait. - `readonly update: boolean` — `true` (`scaffold:sync --update`) : un fichier SUIVI resté intact est remplacé par la version du paquet. - `exists(relative: string): boolean` — Le fichier existe-t-il dans l'application ? - `read(relative: string): string | null` — Lit un fichier texte de l'application. - `write(relative: string, content: string | Uint8Array, options?: IContributionWriteOptions): boolean` — Pose un fichier — seulement s'il est ABSENT : un fichier présent est à l'application, qui a pu le retoucher. - `copyTree(sourceDir: string, relative: string): void` — Recopie un dossier du paquet, fichier par fichier. #### `IAppContributionReport` ```ts interface IAppContributionReport ``` Ce qu'une contribution a fait — une entrée par paquet contributeur. - `readonly packageName: string` — Le paquet (ou module local) qui contribue. - `readonly written: readonly string[]` — Fichiers posés (ou qui le seraient), relatifs, en `/`. - `readonly kept: readonly string[]` — Fichiers déjà présents, laissés tels quels (quelle qu'en soit la raison). - `readonly updated: readonly string[]` — Fichiers suivis remplacés par la version du paquet (`--update`). - `readonly outdated: readonly string[]` — Fichiers suivis INTACTS mais en retard sur le paquet — `--update` les rafraîchirait. - `readonly modified: readonly string[]` — Fichiers suivis qui DIFFÈRENT de la version du paquet sans preuve d'être intacts : retouchés par l'application, ou posés avant le registre. - `readonly error: string | null` — Raison de l'échec, ou `null`. #### `IBarStyle` ```ts interface IBarStyle ``` Paire de caractères d'une barre : ce qui est fait, ce qui reste. - `readonly filled: string` - `readonly empty: string` #### `ICard` ```ts interface ICard ``` La carte de visite complète de l'application. - `app: ICardAppInfo` - `nodefony: { version: string; }` — Version du framework qui sert cette application. - `modules: string[]` — Modules, triés — chargés ou installés selon `ICard.source`. - `source: CardSource` — Ce que `modules` décrit réellement. - `doors: ICardDoor[]` — Où aller, par valeur décroissante. - `verbs: ICardVerb[]` — Quoi lancer, par valeur décroissante. #### `ICardAppInfo` ```ts interface ICardAppInfo ``` Identité de l'application qui répond. - `name: string` — Nom de l'application. - `version: string` — Version déclarée par son `package.json`. - `environment: string` — Environnement de run (`development`, `production`, `staging`…). #### `ICardDoor` ```ts interface ICardDoor ``` Une PORTE : un endroit où aller chercher la suite. - `title: string` — Ce que la porte ouvre, en quelques mots. - `where: string` — URL servie, ou chemin de fichier relatif à la racine de l'application. - `why: string` — Pourquoi y aller — la raison, pas la description. #### `ICardInput` ```ts interface ICardInput ``` État minimal dont `ICard` se dérive. - `appName: string` - `appVersion: string` - `nodefonyVersion: string` - `environment: string` - `modules: string[]` — Noms courts des modules (la clé du conteneur, pas le nom npm). - `source?: CardSource` — Ce que `modules` décrit — défaut `runtime` (l'appel historique). #### `ICardVerb` ```ts interface ICardVerb ``` Un VERBE : une commande à lancer. - `command: string` — Commande complète, prête à coller dans un terminal. - `why: string` — Ce qu'elle répond. #### `IContributionWriteOptions` ```ts interface IContributionWriteOptions ``` Options d'écriture d'une contribution. - `readonly tracked?: boolean` — `true` : le fichier est une copie du paquet, inscrite au registre de provenance et rafraîchie par `scaffold:sync --update` tant qu'elle est intacte. #### `IDeclarationContext` ```ts interface IDeclarationContext ``` Ce qu'il faut savoir pour composer la déclaration chez un agent. - `url: string` — URL absolue de la porte MCP (`http://localhost:5151/nodefony/mcp`). - `name: string` — Nom sous lequel le serveur est déclaré. - `tokenEnv: string` — Nom de la variable qui porte le jeton — jamais le jeton lui-même. #### `IDiffLine` ```ts interface IDiffLine ``` Une ligne d'un diff, telle que `diffLines` la classe. - `kind: "keep" | "add" | "remove"` — `keep` = inchangée, `add` = ajoutée, `remove` = retirée. - `text: string` #### `IGitHooksPlan` ```ts interface IGitHooksPlan ``` Le plan complet — hooks ET configuration, jugés ensemble. - `directory: string` - `hooks: IPlannedGitHook[]` - `hooksPath: { current: string | null; wanted: string; action: HooksPathAction; }` - `refused: boolean` — `true` dès qu'un refus interdit d'appliquer quoi que ce soit. #### `ILiveLineOptions` ```ts interface ILiveLineOptions ``` Réglages communs à toutes les formes. - `readonly stream?: NodeJS.WriteStream` — Flux de sortie. - `readonly animate?: boolean` — Forcer ou interdire l'animation, court-circuitant `shouldAnimate`. - `readonly env?: NodeJS.ProcessEnv` — Environnement à interroger. #### `IMcpConfigDocument` ```ts interface IMcpConfigDocument ``` Un fichier de configuration MCP dans son entier — `.mcp.json` ou celui d'un agent qui tient le sien. - `mcpServers?: Record` — Racine de `.mcp.json` et de Cursor. - `servers?: Record` — Racine de VS Code. - `[key: string]: unknown` #### `IMcpConfigPlan` ```ts interface IMcpConfigPlan ``` Résultat de la composition — ce qu'on écrira, et pourquoi. - `action: McpConfigAction` - `document: IMcpConfigDocument` — Document complet à écrire (identique à l'existant si `inchange`). - `url: string` — URL retenue. - `previousUrl?: string` — URL précédente, quand on remplace. - `authRemoved?: boolean` — `true` quand l'entrée précédente portait un en-tête d'autorisation que celle-ci n'a plus. - `auth?: boolean` — `true` si l'entrée écrite porte l'en-tête d'autorisation. #### `IMcpServerEntry` ```ts interface IMcpServerEntry ``` Une entrée de serveur MCP en transport HTTP. - `type: "http"` — Transport — seul `http` est produit ici (cf `type` de la spec). - `url: string` — URL absolue de l'endpoint. - `headers?: Partial>` — En-têtes ajoutés à chaque requête. #### `IPackageManagerGithubSetup` ```ts interface IPackageManagerGithubSetup ``` Action GitHub qui pose l'outil sur l'exécuteur, avant `setup-node`. - `uses: string` — Référence ÉPINGLÉE par SHA de commit, suivie de sa version en commentaire YAML (`owner/action@ # vX.Y.Z`) : un tag se déplace, un SHA non — et le commentaire est ce que Dependabot relit pour prop … - `versionInput: string` — Nom de l'entrée qui porte la version (`version`, `bun-version`). - `version: string` #### `IPackageManagerResolution` ```ts interface IPackageManagerResolution ``` Gestionnaire retenu, et la source qui l'a désigné. - `name: PackageManagerName` - `source: PackageManagerSource` - `lockfile?: string` — Fichier de verrou qui a tranché, quand `source === "lockfile"`. #### `IPackageManagerToolchain` ```ts interface IPackageManagerToolchain ``` Ce qu'une chaîne d'INTÉGRATION (forge, image de conteneur) doit écrire pour un gestionnaire — UNE règle, lue par les gabarits CI et le `Dockerfile`. - `lockfile: string` — Verrou que le gestionnaire écrit, et que la chaîne exige. - `frozenInstall: string` — Installation stricte : refuse un verrou désaccordé du `package.json`. - `setupNodeCache: "npm" | "pnpm" | "yarn" | null` — Valeur `cache:` de `actions/setup-node`, `null` s'il ne connaît pas l'outil. - `githubSetup: IPackageManagerGithubSetup | null` — Action qui installe l'outil sur l'exécuteur GitHub, `null` s'il y est déjà. - `bootstrap: string | null` — Commande qui installe l'outil dans une image `node:*`, `null` s'il y est déjà. - `imageCacheDir: string` — Dossier de cache dans l'image (montage BuildKit). - `projectCacheDir: string` — Dossier de cache RELATIF au projet (GitLab ne garde que l'arbre du job). - `projectCachedInstall: string` — Installation stricte qui écrit son cache dans `projectCacheDir`. - `imageInstall: string` — Installation de l'image, sans scripts, verrou présent. - `imageInstallUnlocked: string` — Même chose sans verrou (application fraîche, jamais installée). - `prune: string` — Retire les dépendances de développement d'un arbre installé. #### `IPlannedGitHook` ```ts interface IPlannedGitHook ``` Le geste décidé pour un hook. - `name: GitHookName` - `action: GitHookAction` - `target: string` — Chemin du hook, relatif à la racine de l'application, en `/`. - `content: string` — Contenu à écrire — celui de `renderGitHook`, tel quel. #### `IPortableSpawn` ```ts interface IPortableSpawn ``` Ce qu'il faut donner à `spawn`/`spawnSync` pour lancer `command args…` sur ce système — SANS jamais confier des arguments à un shell. - `file: string` — Le programme à lancer : la commande, ou `cmd.exe` quand elle est un script batch. - `args: string[]` — Ses arguments, prêts pour `spawn` — jamais à retoucher. - `windowsVerbatimArguments: boolean` — À recopier dans les options de `spawn` : `cmd.exe` reçoit sa ligne verbatim. #### `IProgressBarOptions` ```ts interface IProgressBarOptions extends ILiveLineOptions ``` Réglages d'une `ProgressBar`. - `readonly width?: number` — Largeur de la barre. - `readonly style?: IBarStyle` — Caractères plein/vide. - `readonly spin?: boolean` — Ajoute un tourniquet en tête, animé indépendamment de l'avancement. - `readonly intervalMs?: number` — Cadence du tourniquet, en millisecondes. - `readonly frames?: readonly string[]` — Images du tourniquet. - `readonly render?: ProgressRenderer` — Rendu de la ligne. #### `IProgressState` ```ts interface IProgressState ``` Ce qu'un rendu de barre reçoit pour composer sa ligne. - `readonly done: number` — Unités faites. - `readonly total: number` — Unités attendues. - `readonly ratio: number` — Rapport `done/total`, borné à `[0, 1]` ; `0` si le total est nul. - `readonly bar: string` — La barre déjà dessinée par `renderBar`. - `readonly label: string` — Libellé courant. - `readonly frame: string` — Image du tourniquet, ou `""` si `spin` est faux. - `readonly elapsedMs: number` — Millisecondes écoulées depuis `ProgressBar.start`. #### `IPrompts` ```ts interface IPrompts ``` Les questions servies par cette porte — le sous-ensemble réellement utilisé. - `confirm: (config: { message: string; default?: boolean; }) => Promise` - `select: (config: { message: string; choices: readonly unknown[]; default?: T; }) => Promise` - `checkbox: (config: { message: string; choices: readonly unknown[]; }) => Promise` - `input: (config: { message: string; default?: string; }) => Promise` #### `IRenderBarOptions` ```ts interface IRenderBarOptions ``` Réglages de `renderBar`. - `readonly width?: number` — Largeur en cellules. - `readonly style?: IBarStyle` — Caractères plein/vide. #### `IScaffoldCaps` ```ts interface IScaffoldCaps ``` Capacités de l'environnement, telles que le MOTEUR les voit — ce qu'un front ne peut pas deviner (cf `IScaffoldQuestion.askIf`). - `hasCheckout: boolean` — Un checkout du framework est résolvable (mode `--link`). - `hasSqlOrm?: boolean` — Le projet courant persiste en SQL (Drizzle). #### `IScaffoldChange` ```ts interface IScaffoldChange ``` Écriture prévue par un scaffold, telle qu'un dry-run la restitue. - `path: string` — Chemin absolu du fichier. - `kind: "create" | "overwrite"` — Le fichier n'existait pas (`create`) ou sera réécrit (`overwrite`). - `content: string` — Contenu qui sera écrit — en base64 quand `encoding` vaut `"base64"`. - `previous?: string` — Contenu actuel sur disque — seulement si `kind === "overwrite"`. - `encoding?: "base64"` — `"base64"` pour un fichier BINAIRE (image) : `content` et `previous` sont alors encodés, et ne se comparent pas ligne à ligne. #### `IScaffoldConnector` ```ts interface IScaffoldConnector ``` - `name: string` — Nom sous lequel les entités le désignent (`default`, `analytics`…). - `dialect: TEntityDialect | "mongodb"` — Moteur visé — décide des types générés. - `ddl?: string` — Qui fabrique le schéma de ce connecteur, quand l'application l'ÉCRIT. #### `IScaffoldContext` ```ts interface IScaffoldContext ``` Ce que le PROJET RÉEL offre comme choix à un scaffold, sans démarrer le noyau. - `targets: IScaffoldTarget[]` — Cibles possibles : l'application racine et ses modules locaux. - `connectors: IScaffoldConnector[]` — Connecteurs déclarés, avec le moteur de chacun (`mongodb` pour Mongoose). - `columnTypes: Array<{ type: string; byDialect: Record; }>` — Types de champ disponibles, et ce qu'ils deviennent dans CHAQUE moteur. - `entities: Record` — Entités existantes par cible — ce que `ref:` peut viser. - `idKinds: readonly string[]` — Stratégies de clé primaire proposées. #### `IScaffoldLock` ```ts interface IScaffoldLock ``` Le registre de provenance — `scaffold.lock.json` à la racine de l'application, VERSIONNÉ avec elle : l'empreinte de chaque fichier suivi tel que le paquet l'a livré. C'est lui qui distingue un fichier intact (donc rafraîchissable) d'un fichier retouché (donc à l'application). - `readonly description: string` — Une phrase pour qui ouvre le fichier. - `readonly packages: Readonly>` — Par paquet : sa version à la dernière synchronisation, et ses fichiers. #### `IScaffoldLockPackage` ```ts interface IScaffoldLockPackage ``` L'entrée d'un paquet au registre de provenance. - `readonly version: string | null` — Version du paquet à la dernière synchronisation, ou `null`. - `readonly files: Readonly>` — Chemin relatif (en `/`) → empreinte sha256 de la version livrée. #### `IScaffoldQuestion` ```ts interface IScaffoldQuestion ``` - `key: string` - `label: string` — Libellé montré tel quel par le CLI interactif et Studio. - `type: "string" | "boolean" | "choice" | "list"` — `"list"` = plusieurs valeurs indépendantes, chacune conservée entière. - `choices?: { value: string; label: string; hint?: string; }[]` — Choix ordonnés (type "choice") — le premier N'est PAS forcément le défaut. - `default: string | boolean | string[]` - `note?: string` — Ce que l'outil DIT au moment où il pose la question — jamais dans une page annexe. - `pattern?: string` — Regex source (sans flags) que la valeur string doit satisfaire. - `patternHint?: string` — Message d'aide affiché si la validation échoue. - `askIf?: TScaffoldCap` — Condition d'affichage par CAPACITÉ d'environnement (JSON-able — pas de fonction) : la question n'est posée que si le front la déclare vraie. - `askWhen?: { key: string; equals: string; }` — Condition d'affichage par RÉPONSE PRÉCÉDENTE (JSON-able) : la question n'est posée que si `key` a déjà pour valeur `equals`. - `optionsFrom?: "connectors" | "entities"` — Source des choix RÉELS de cette question, dans le projet courant (JSON-able, même esprit qu'`askIf`). - `compose?: "entityFields"` — La réponse se COMPOSE en plusieurs questions au lieu de s'écrire d'un bloc. - `advanced?: boolean` — Réglage **avancé** : jamais posé en dialogue (son défaut est sûr), mais piloté par une option de la ligne de commande — et proposé par Studio dans un repli. - `flag?: string` — Nom du drapeau de ligne de commande, quand il ne se DÉDUIT pas de la clé. #### `IScaffoldRequest` ```ts interface IScaffoldRequest ``` - `type: string` - `answers: TScaffoldAnswers` - `dir: string` — Dossier cible complet (défaut : `./` relatif au cwd de l'appelant). - `force: boolean` #### `IScaffoldResult` ```ts interface IScaffoldResult ``` - `dest: string` - `files: string[]` — Chemins relatifs écrits (triés). - `linked: string[]` — Paquets nodefony câblés en `file:` (mode link). - `notes?: string[]` — Points d'entrée utiles du scaffold (routes, canaux…) — affichés tels quels. - `depsAdded?: string[]` — Dépendances AJOUTÉES au `package.json` du projet par cette génération. - `migration?: { table: string; connector: string; advice: { command: string; pending: string; }; }` — La migration que cette génération RÉCLAME — une table NEUVE sur un connecteur qui versionne ses migrations, où le démarrage ne la crée pas. - `changes?: IScaffoldChange[]` — Écritures PRÉVUES, avec l'ancien contenu quand il y en a un — présent uniquement en dry-run (rien n'a touché le disque). - `unformatted?: number` — Fichiers formatables laissés SANS mise en forme, faute de prettier dans le projet (cas courant : `--no-install`). #### `IScaffoldRoot` ```ts interface IScaffoldRoot ``` Racine autorisée : un espace de travail où l'on a le droit de créer une app. - `id: string` — Identifiant opaque manipulé par le client (jamais un chemin). - `label: string` — Libellé affiché. - `path: string` — Chemin réel côté serveur — ne sort JAMAIS tel quel vers un client non admin. #### `IScaffoldRunOptions` ```ts interface IScaffoldRunOptions ``` Options d'exécution d'un scaffold (cf `runScaffold`). - `dryRun?: boolean` — Ne rien écrire : le scaffold se déroule entièrement (gardes comprises) et rend son plan dans `result.changes`. - `writer?: ScaffoldWriter` — Transaction déjà ouverte par un scaffold APPELANT (`create module` délègue à `controller`/`front`). #### `IScaffoldTarget` ```ts interface IScaffoldTarget ``` Cible d'un scaffold in-project : l'app racine ou un module du projet. - `kind: "app" | "module"` - `name: string` — Nom affichable (package.json `name`). - `dir: string` — Dossier du code (contient `index.ts` + `nodefony/`). #### `IScaffoldTypeSpec` ```ts interface IScaffoldTypeSpec ``` Spec d'un type de scaffold (`app` aujourd'hui ; `module`/`controller`/`entity` suivent). - `type: string` - `description: string` - `questions: IScaffoldQuestion[]` #### `ISpinnerOptions` ```ts interface ISpinnerOptions extends ILiveLineOptions ``` Réglages d'un `Spinner`. - `readonly intervalMs?: number` — Cadence de l'animation en millisecondes. - `readonly frames?: readonly string[]` — Images du tourniquet. - `readonly render?: SpinnerRenderer` — Rendu de la ligne. #### `ISymbolEntry` ```ts interface ISymbolEntry ``` Un symbole tel que le graphe le décrit (surface utile, pas le fichier entier). - `name: string` - `kind: string` - `module: string` — Nom npm du paquet qui le porte (`@nodefony/http`, `@nodefony/core`). - `file: string` — Chemin du source, relatif à la racine du dépôt qui l'a produit. - `line?: number` - `exported?: boolean` - `description?: string` — Première phrase du TSDoc — auto-suffisante par convention. - `extends?: string` - `implements?: string[]` - `decorators?: string[]` — Décorateurs appliqués (`injectable`, `Route`…). #### `ISymbolsGraph` ```ts interface ISymbolsGraph ``` Ce que le graphe contient, réduit à ce que ses lecteurs utilisent. - `generated?: string` - `version?: string` - `symbols: Record` - `relations?: Record>` ### Types (15) #### `CardSource` ```ts type CardSource = "runtime" | "static" ``` D'où vient la liste de modules — et donc ce que la carte a le droit d'affirmer. #### `DeclarationChannel` ```ts type DeclarationChannel = "fichier-projet" | "fichier-agent" | "cli" ``` Comment la porte MCP se déclare chez un agent. #### `GitHookAction` ```ts type GitHookAction = "pose" | "remplace" | "inchange" | "refus-etranger" ``` Ce qu'il faut faire d'un hook, une fois comparé à l'existant. #### `GitHookName` ```ts type GitHookName = (typeof GIT_HOOK_NAMES)[number] ``` #### `HooksPathAction` ```ts type HooksPathAction = "pose" | "inchange" | "refus-autre" ``` Ce qu'il faut faire de `core.hooksPath`. #### `IDeclarationPlan` ```ts type IDeclarationPlan = { channel: "fichier-projet"; file: string; } | { channel: "fichier-agent"; file: string; mcpFile: IAgentMcpFile; } | { channel: "cli"; bin: string; argv: string[]; } ``` Ce qu'il faut lancer — ou ne pas lancer — pour qu'un agent connaisse la porte. #### `McpConfigAction` ```ts type McpConfigAction = "pose" | "remplace" | "inchange" ``` Ce que la commande a décidé de faire. #### `ProgressRenderer` ```ts type ProgressRenderer = (state: IProgressState) => string ``` Rendu d'une ligne de progression. #### `SpinnerRenderer` ```ts type SpinnerRenderer = (frame: string, label: string) => string ``` Rendu d'une ligne animée : c'est le CONSOMMATEUR qui décide du contenu. #### `TAppContributor` ```ts type TAppContributor = (context: IAppContributionContext) => void | Promise ``` La fonction qu'un paquet exporte sous le nom `contribute` pour poser ses fichiers dans une application. #### `TFrontendChoice` ```ts type TFrontendChoice = (typeof FRONTEND_CHOICES)[number] ``` #### `TPresetChoice` ```ts type TPresetChoice = (typeof PRESET_CHOICES)[number] ``` #### `TScaffoldAnswers` ```ts type TScaffoldAnswers = Partial> ``` Réponses d'un scaffold, complétées et validées contre la spec. #### `TScaffoldCap` ```ts type TScaffoldCap = keyof IScaffoldCaps ``` Nom d'une capacité d'environnement (`IScaffoldCaps`). #### `TScaffoldStep` ```ts type TScaffoldStep = (typeof SCAFFOLD_STEPS)[number] ``` ### Énumérations (1) #### `SysExit` ```ts enum SysExit { OK = 0, USAGE = 64, DATAERR = 65, NOINPUT = 66, UNAVAILABLE = 69, CANTCREAT = 73, SOFTWARE = 70, NOPERM = 77, CONFIG = 78 } ``` Codes de sortie standardisés — convention BSD `sysexits.h` (FreeBSD `sysexits(3)`). Ce n'est PAS un RFC, mais le standard de facto Unix pour des exit codes porteurs de sens, au-delà du binaire POSIX `0`/non-zéro. Permet à un script appelant de distinguer un « mauvais usage » d'une « erreur interne » ou d'une « config invalide ». --- [← Toutes les références d'API](../../)