Référence d'API — nodefony — cli

stable

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#

class EntityFieldError extends Error

Erreur de syntaxe dans la déclaration d’un champ — message actionnable.

LiveLine#

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#

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#

class ScaffoldDestinationError extends Error

Erreur de destination — message sûr, affichable tel quel (jamais un chemin serveur).

Spinner#

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#

function agentRoot(target: IAgentTarget, ctx: { projectRoot: string; home?: string; env?: Record<string, string>; }): string

Racine où vit la configuration d’une cible : le projet, ou son dossier maison.

agentsPresents#

function agentsPresents(ctx: { projectRoot: string; home?: string; env?: Record<string, string>; exists: (filePath: string) => boolean; }): IAgentTarget[]

Agents dont la présence est CONSTATÉE sur ce poste.

alreadyHasKey#

function alreadyHasKey(forme: IAgentTarget["forme"], content: string, key: string): boolean

anchorEventLoop#

function anchorEventLoop(): () => void

Retient l’event loop, et rend de quoi le relâcher.

argvMcpWiring#

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#

function askPasswordMasked(question: string): Promise<string>

Demande un secret sans jamais l’ÉCHOTER — mot de passe, phrase de passe.

buildCard#

function buildCard(input: ICardInput): ICard

Construit la carte de visite d’une application à partir de son état.

buildMcpUrl#

function buildMcpUrl(origin: string, endpointPath: string): string

Compose l’URL de l’endpoint MCP.

capAllows#

function capAllows(question: Pick<IScaffoldQuestion, "askIf">, caps: IScaffoldCaps): boolean

La question est-elle posée dans CET environnement ?

chargePrompts#

function chargePrompts(): Promise<IPrompts & Record<string, unknown>>

Charge les prompts — import DYNAMIQUE, et c’est délibéré.

contributionFingerprint#

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#

function createAppContributionContext(appRoot: string, options?: { appName?: string; dryRun?: boolean; update?: boolean; recorded?: Readonly<Record<string, string>>; }): { context: IAppContributionContext; written: string[]; kept: string[]; updated: string[]; outdated: string[]; modified: string[]; files: Record<string, string>; }

Construit le contexte d’UNE contribution, qui consigne ce qu’elle pose et ce qu’elle laisse.

diffLines#

function diffLines(before: string, after: string): IDiffLine[]

Diff ligne à ligne de deux contenus (plus longue sous-séquence commune).

escapeRoff#

function escapeRoff(text: string): string

Échappe une chaîne pour roff.

findProjectRoot#

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#

function fitToWidth(line: string, columns: number): string

Tronque une ligne à la largeur du terminal, séquences ANSI non comptées.

formatDuration#

function formatDuration(ms: number): string

Met en forme une durée pour un humain : 840ms, 12.3s, 4m 05s.

formatEntityField#

function formatEntityField(field: IEntityField): string

Écrit un champ dans la grammaire de la ligne de commande — l’inverse exact de parseEntityFields.

getScaffoldContext#

function getScaffoldContext(dir: string, writer?: ScaffoldWriter): IScaffoldContext | null

Lit le contexte du projet contenant dir.

getScaffoldSpec#

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#

function guessOrigin(cwd: string): string

Déduit l’origine du serveur de développement.

hydrateQuestion#

function hydrateQuestion(question: IScaffoldQuestion, context: IScaffoldContext | null): IScaffoldQuestion

Remplace les réponses possibles d’une question par celles du PROJET RÉEL.

installGitHooks#

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#

function isInsideRoot(root: string, child: string): boolean

child est-il À L’INTÉRIEUR de root ?

isSafeSubPath#

function isSafeSubPath(sub: string): boolean

Le sous-chemin proposé est-il navigable sans danger ?

isScaffoldStep#

function isScaffoldStep(value: unknown): value is TScaffoldStep

Une étape connue ? (garde des entrées venues du réseau).

listTargets#

function listTargets(projectRoot: string, writer?: ScaffoldWriter): [ IScaffoldTarget, ...IScaffoldTarget[] ]

lookupSymbol#

function lookupSymbol(graph: ISymbolsGraph, name: string): ISymbolEntry

Trouve un symbole par son nom exact.

mcpWiringPlan#

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#

function needsShell(command: string, plateforme?: NodeJS.Platform, grammar?: Pick<typeof path, "isAbsolute">): boolean

Faut-il passer par le shell pour lancer cette commande ?

nodefonyBin#

function nodefonyBin(since?: string): string

Le chemin du lanceur nodefony, tel que CETTE installation l’a reçu.

packageManagerCommandLines#

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#

function packageManagerExecArgs(name: PackageManagerName, bin: string, args?: readonly string[]): string[]

Arguments qui lancent un BINAIRE installé dans le projet (nodefony, vitest…).

packageManagerToolchain#

function packageManagerToolchain(name: PackageManagerName): IPackageManagerToolchain

Commandes d’installation, de cache et d’élagage d’un gestionnaire, pour la forge et pour l’image.

packageManagerUpdateInstallArgs#

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#

function parseEntityFields(input: string): IEntityField[]

Analyse la déclaration textuelle des champs.

planAgentDeclaration#

function planAgentDeclaration(target: IAgentTarget, ctx: Pick<IDeclarationContext, "url" | "tokenEnv">, remove?: boolean): IDeclarationPlan

Compose la déclaration de la porte MCP chez un agent.

planGitHooks#

function planGitHooks(existing: Record<string, string | null>, currentHooksPath: string | null, wantedHooksPath: string): IGitHooksPlan

Décide, pour chaque hook et pour core.hooksPath, le geste à faire.

planMcpConfig#

function planMcpConfig(existing: IMcpConfigDocument | null, url: string, options?: { auth?: boolean; grammar?: IMcpGrammar; }): IMcpConfigPlan

Décide ce qu’il faut écrire dans .mcp.json.

portableSpawn#

function portableSpawn(command: string, args: readonly string[], platform?: NodeJS.Platform, grammar?: Pick<typeof path, "isAbsolute">, comSpec?: string): IPortableSpawn

Compose la commande portable — voir IPortableSpawn.

poseVariable#

function poseVariable(forme: IAgentTarget["forme"], current: string, key: string, value: string): string | Error

readScaffoldLock#

function readScaffoldLock(appRoot: string): Record<string, IScaffoldLockPackage>

Lit le registre de provenance de l’application.

readSymbolsGraph#

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#

function renderBar(done: number, total: number, options?: IRenderBarOptions): string

Dessine une barre de progression, et rien d’autre.

renderCard#

function renderCard(card: ICard): string

Rend la carte pour un HUMAIN (ou un agent qui lit un terminal).

renderGitHook#

function renderGitHook(name: GitHookName): string

Le contenu d’un hook.

renderGitHooksPlan#

function renderGitHooksPlan(plan: IGitHooksPlan, applique: boolean): string

Rend le plan pour un humain.

renderManPage#

function renderManPage(manifest: ICliManifest, version: string): string

Rend la page de manuel complète, en roff.

renderMcpPlan#

function renderMcpPlan(plan: IMcpConfigPlan, file: string, dryRun: boolean): string

Rend le plan pour un lecteur humain.

renderPlanShell#

function renderPlanShell(plan: IDeclarationPlan): string

Rend le plan sous la forme qu’on peut recopier dans un terminal.

request#

function request<T>(interaction: () => Promise<T>): Promise<T>

Exécute une interaction utilisateur en retenant l’event loop.

requestedAgents#

function requestedAgents(raw: string): readonly IAgentTarget[] | Error

Traduit --agent en cibles, ou rend l’erreur à afficher.

resolveAnswers#

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#

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#

function resolveScaffoldDestination(roots: readonly IScaffoldRoot[], rootId: string, sub: string, name: string): string

Recompose la destination d’une nouvelle app, ou refuse.

resolveSymbolsFile#

function resolveSymbolsFile(from: string): string | null

Trouve le graphe symbolique utilisable depuis from.

runAiMcpCommand#

function runAiMcpCommand(argv: string[]): Promise<number>

Point d’entrée de la commande.

runAppContributions#

function runAppContributions(appRoot: string, dryRun?: boolean, update?: boolean): Promise<IAppContributionReport[]>

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#

function runGitHooksCommand(argv: string[]): number

Commande nodefony git:hooks — hooks git natifs (core.hooksPath), zéro dépendance.

runScaffold#

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#

function runSymbolsCli(argv: string[]): Promise<number>

Porte de la ligne de commande : --generate écrit le graphe de l’application, tout le reste le lit (runSymbolsCommand).

runSymbolsCommand#

function runSymbolsCommand(argv: string[]): number

Commande nodefony symbols — le graphe, sans boot et sans dépôt.

scaffoldCaps#

function scaffoldCaps(dir?: string): IScaffoldCaps

Capacités de l’environnement, telles que le MOTEUR les voit.

shouldAnimate#

function shouldAnimate(stream: NodeJS.WriteStream, env?: NodeJS.ProcessEnv): boolean

Faut-il animer du tout ?

supportsUnicode#

function supportsUnicode(env?: NodeJS.ProcessEnv, platform?: string): boolean

Le terminal sait-il dessiner du braille et des blocs ?

Constantes (22)#

AGENT_TARGETS#

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#

const APP_NAME_RE: RegExp

Nom d’application — même expression que la spec du scaffold (spec.ts).

ARC_FRAMES#

const ARC_FRAMES: readonly [ "◜", "◠", "◝", "◞", "◡", "◟" ]

Arcs tournants — plus discret que le braille, même encombrement.

BAR_STYLES#

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#

const BLOCK_FRAMES: readonly [ "▁", "▂", "▃", "▄", "▅", "▆", "▇", "▆", "▅", "▄", "▃", "▂" ]

Barres montantes — suggère une activité qui « pompe ».

BRAILLE_FRAMES#

const BRAILLE_FRAMES: readonly [ "⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏" ]

Tourniquet braille — dix images, rotation fluide. Le défaut.

DOT_FRAMES#

const DOT_FRAMES: readonly [ " ", ". ", ".. ", "..." ]

Points qui s’ajoutent — le plus sobre, et le seul purement ASCII.

ENTITY_FIELD_TYPES#

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#

const FRONTEND_CHOICES: readonly [ "none", "react", "vue", "angular", "svelte" ]

Frameworks front supportés par @nodefony/frontend (builder Vite multi-framework).

GIT_HOOKS_DIR#

const GIT_HOOKS_DIR = ".githooks"

Dossier des hooks, relatif à la racine de l’application, écrit en /.

GIT_HOOKS_MARKER#

const GIT_HOOKS_MARKER = "pos\u00E9 par `nodefony git:hooks`"

Marqueur d’APPARTENANCE, présent dans chaque hook généré.

GIT_HOOK_NAMES#

const GIT_HOOK_NAMES: readonly [ "pre-commit", "pre-push" ]

Les hooks que la commande sait poser, dans l’ordre d’affichage.

LINE_FRAMES#

const LINE_FRAMES: readonly [ "-", "\\", "|", "/" ]

Tourniquet ASCII — le repli quand la police ne porte pas le braille.

MAN_PAGE_NAME#

const MAN_PAGE_NAME = "nodefony.1"

Nom de la page, section 1 (commandes utilisateur).

MCP_CONFIG_FILE#

const MCP_CONFIG_FILE = ".mcp.json"

Fichier de configuration, à la racine du projet.

MCP_ENDPOINT_PATH#

const MCP_ENDPOINT_PATH = "/nodefony/mcp"

Chemin de l’endpoint MCP.

MCP_SERVER_KEY#

const MCP_SERVER_KEY = "nodefony"

Nom de la clé sous laquelle notre serveur est déclaré.

MCP_TOKEN_ENV#

const MCP_TOKEN_ENV = "NF_MCP_TOKEN"

Nom de la variable d’environnement qui porte le jeton de la porte MCP.

SCAFFOLD_LOCK_FILE#

const SCAFFOLD_LOCK_FILE = "scaffold.lock.json"

Le nom du registre de provenance, à la racine de l’application.

SCAFFOLD_STEPS#

const SCAFFOLD_STEPS: readonly [ "install", "build", "typecheck" ]

Étapes possibles, dans leur ordre d’exécution naturel.

SCAFFOLD_STEP_COMMANDS#

const SCAFFOLD_STEP_COMMANDS: Record<TScaffoldStep, readonly string[]>

Arguments passés à npm pour chaque étape.

SCAFFOLD_STEP_LABELS#

const SCAFFOLD_STEP_LABELS: Record<TScaffoldStep, string>

Ce que chaque étape apporte — affiché avant de la lancer.

Interfaces (42)#

IAgentTarget#

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#

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#

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#

interface IBarStyle

Paire de caractères d’une barre : ce qui est fait, ce qui reste.

• readonly filled: string
• readonly empty: string

ICard#

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#

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#

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#

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#

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#

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#

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#

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#

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#

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#

interface IMcpConfigDocument

Un fichier de configuration MCP dans son entier — .mcp.json ou celui d’un agent qui tient le sien.

• mcpServers?: Record<string, IMcpServerEntry> — Racine de .mcp.json et de Cursor.
• servers?: Record<string, IMcpServerEntry> — Racine de VS Code.
• [key: string]: unknown

IMcpConfigPlan#

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#

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<Record<string, string>> — En-têtes ajoutés à chaque requête.

IPackageManagerGithubSetup#

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@<sha> # 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#

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#

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#

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#

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#

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#

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#

interface IPrompts

Les questions servies par cette porte — le sous-ensemble réellement utilisé.

• 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>

IRenderBarOptions#

interface IRenderBarOptions

Réglages de renderBar.

• readonly width?: number — Largeur en cellules.
• readonly style?: IBarStyle — Caractères plein/vide.

IScaffoldCaps#

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#

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#

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#

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<string, string>; }> — Types de champ disponibles, et ce qu’ils deviennent dans CHAQUE moteur.
• entities: Record<string, string[]> — Entités existantes par cible — ce que ref: peut viser.
• idKinds: readonly string[] — Stratégies de clé primaire proposées.

IScaffoldLock#

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<Record<string, IScaffoldLockPackage>> — Par paquet : sa version à la dernière synchronisation, et ses fichiers.

IScaffoldLockPackage#

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<Record<string, string>> — Chemin relatif (en /) → empreinte sha256 de la version livrée.

IScaffoldQuestion#

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#

interface IScaffoldRequest

• type: string
• answers: TScaffoldAnswers
• dir: string — Dossier cible complet (défaut : ./<name> relatif au cwd de l’appelant).
• force: boolean

IScaffoldResult#

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#

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#

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#

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#

interface IScaffoldTypeSpec

Spec d’un type de scaffold (app aujourd’hui ; module/controller/entity suivent).

• type: string
• description: string
• questions: IScaffoldQuestion[]

ISpinnerOptions#

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#

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#

interface ISymbolsGraph

Ce que le graphe contient, réduit à ce que ses lecteurs utilisent.

• generated?: string
• version?: string
• symbols: Record<string, ISymbolEntry>
• relations?: Record<string, Record<string, string[]>>

Types (15)#

CardSource#

type CardSource = "runtime" | "static"

D’où vient la liste de modules — et donc ce que la carte a le droit d’affirmer.

DeclarationChannel#

type DeclarationChannel = "fichier-projet" | "fichier-agent" | "cli"

Comment la porte MCP se déclare chez un agent.

GitHookAction#

type GitHookAction = "pose" | "remplace" | "inchange" | "refus-etranger"

Ce qu’il faut faire d’un hook, une fois comparé à l’existant.

GitHookName#

type GitHookName = (typeof GIT_HOOK_NAMES)[number]

HooksPathAction#

type HooksPathAction = "pose" | "inchange" | "refus-autre"

Ce qu’il faut faire de core.hooksPath.

IDeclarationPlan#

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#

type McpConfigAction = "pose" | "remplace" | "inchange"

Ce que la commande a décidé de faire.

ProgressRenderer#

type ProgressRenderer = (state: IProgressState) => string

Rendu d’une ligne de progression.

SpinnerRenderer#

type SpinnerRenderer = (frame: string, label: string) => string

Rendu d’une ligne animée : c’est le CONSOMMATEUR qui décide du contenu.

TAppContributor#

type TAppContributor = (context: IAppContributionContext) => void | Promise<void>

La fonction qu’un paquet exporte sous le nom contribute pour poser ses fichiers dans une application.

TFrontendChoice#

type TFrontendChoice = (typeof FRONTEND_CHOICES)[number]

TPresetChoice#

type TPresetChoice = (typeof PRESET_CHOICES)[number]

TScaffoldAnswers#

type TScaffoldAnswers = Partial<Record<string, string | boolean | string[]>>

Réponses d’un scaffold, complétées et validées contre la spec.

TScaffoldCap#

type TScaffoldCap = keyof IScaffoldCaps

Nom d’une capacité d’environnement (IScaffoldCaps).

TScaffoldStep#

type TScaffoldStep = (typeof SCAFFOLD_STEPS)[number]

Énumérations (1)#

SysExit#

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