@nodefony/drizzle 10.0.0-alpha.1

package/dist/nodefony/src/migrator/sources.js

@@ -0,0 +1,419 @@
+import { FORMAT_MARKER, MigrationVerdictError, STATEMENT_BREAKPOINT } from "./types.js";
+import { frameworkMigrationsDir } from "./paths.js";
+import { migrationHash, normalizeSql } from "./hash.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+//#region nodefony/src/migrator/sources.ts
+/**
+* Version du journal drizzle-kit que cet applicateur sait lire.
+*
+* On adopte le format d'un outil tiers : le lire « au mieux » reviendrait à
+* découvrir un défaut de découpe APRÈS publication, quand le corriger
+* changerait le sens de fichiers déjà livrés chez des utilisateurs.
+*/
+const SUPPORTED_JOURNAL_VERSIONS = ["7"];
+/**
+* Ordonne un registre de sources : rang croissant, nom en départage.
+*
+* `framework` porte le rang 0 (les entités d'application peuvent référencer ses
+* tables), `app` le rang le plus élevé. Entre les deux, les modules à leur
+* ordre de chargement. Le nom départage à rang égal pour que l'ordre soit
+* **déterministe** : deux pods qui liraient le même registre dans deux ordres
+* différents appliqueraient deux plans différents.
+*
+* @param sources - registre, dans n'importe quel ordre.
+* @returns le même registre, trié.
+*/
+function orderSources(sources) {
+	return [...sources].sort((a, b) => a.rank - b.rank || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+/**
+* Charge toutes les sources d'un registre pour un dialecte donné.
+*
+* @param sources - registre de sources (espace de noms ouvert).
+* @param dialect - dialecte du connecteur ; sélectionne le sous-dossier.
+* @returns les fichiers ordonnés et les sources absentes, nommées.
+* @throws MigrationVerdictError si un fichier ne porte pas le format attendu.
+*/
+async function loadSources(sources, dialect) {
+	const files = [];
+	const absent = [];
+	for (const source of orderSources(sources)) {
+		const dir = path.join(source.dir, dialect);
+		const journal = await readJournal(dir, source.name);
+		if (journal === null) {
+			absent.push(source.name);
+			continue;
+		}
+		for (const entry of [...journal.entries].sort((a, b) => a.idx - b.idx)) files.push(await readMigrationFile(dir, source.name, entry, dialect));
+	}
+	return {
+		files,
+		absent
+	};
+}
+/**
+* Lit le journal d'une source, ou `null` si la source n'est pas installée.
+*
+* @param dir - dossier `<source>/<dialecte>`.
+* @param source - nom logique de la source, pour nommer un refus.
+* @returns le journal validé, ou `null` si le dossier n'existe pas.
+* @throws MigrationVerdictError si la version du journal n'est pas reconnue.
+*/
+async function readJournal(dir, source) {
+	const file = path.join(dir, "meta", "_journal.json");
+	let raw;
+	try {
+		raw = await fs.readFile(file, "utf8");
+	} catch (e) {
+		if (e.code === "ENOENT") return null;
+		throw e;
+	}
+	let journal;
+	try {
+		journal = JSON.parse(raw);
+	} catch (e) {
+		throw new MigrationVerdictError({
+			code: "NF_MIGRATE_UNKNOWN_FORMAT",
+			connector: "",
+			source,
+			facts: {
+				file,
+				cause: e instanceof Error ? e.message : String(e)
+			},
+			nextActions: []
+		}, `Le journal des migrations « ${file} » n'est pas lisible : ${e instanceof Error ? e.message : String(e)}. La cause la plus fréquente est un conflit de fusion non résolu — deux branches ayant généré chacune une migration. Ouvrir le fichier, résoudre le conflit, et vérifier que chaque migration du dossier y figure une fois. La base n'est pour rien dans cette erreur.`);
+	}
+	if (!Array.isArray(journal.entries)) throw new MigrationVerdictError({
+		code: "NF_MIGRATE_UNKNOWN_FORMAT",
+		connector: "",
+		source,
+		facts: { file },
+		nextActions: []
+	}, `Le journal des migrations « ${file} » ne porte pas de liste « entries » : ce n'est pas un journal que ce format sait lire.`);
+	if (!SUPPORTED_JOURNAL_VERSIONS.includes(String(journal.version))) throw new MigrationVerdictError({
+		code: "NF_MIGRATE_UNKNOWN_FORMAT",
+		connector: "",
+		source,
+		facts: {
+			file,
+			journalVersion: String(journal.version),
+			supported: SUPPORTED_JOURNAL_VERSIONS
+		},
+		nextActions: [{
+			command: "npm update @nodefony/drizzle",
+			args: ["update", "@nodefony/drizzle"]
+		}]
+	}, `Le journal de migrations de la source « ${source} » est en version ${String(journal.version)}, que cette version du framework ne sait pas lire (reconnue : ${SUPPORTED_JOURNAL_VERSIONS.join(", ")}).`);
+	return journal;
+}
+/**
+* Lit un fichier de migration, valide son format et découpe ses statements.
+*
+* @param dir - dossier `<source>/<dialecte>`.
+* @param source - nom logique de la source.
+* @param entry - entrée du journal.
+* @param dialect - dialecte du connecteur ; choisit la grammaire de découpe.
+* @returns le fichier chargé, empreinte comprise.
+* @throws MigrationVerdictError si le marqueur de format est absent ou autre.
+*/
+async function readMigrationFile(dir, source, entry, dialect) {
+	const file = path.join(dir, `${entry.tag}.sql`);
+	let content;
+	try {
+		content = await fs.readFile(file, "utf8");
+	} catch (cause) {
+		throw new MigrationVerdictError({
+			code: "NF_MIGRATE_JOURNAL_MISMATCH",
+			connector: "",
+			source,
+			tag: entry.tag,
+			facts: {
+				file,
+				reason: cause instanceof Error ? cause.message : String(cause)
+			},
+			nextActions: [{
+				command: "nodefony orm:migrate:status --json",
+				args: ["orm:migrate:status", "--json"]
+			}]
+		}, `Le journal de la source « ${source} » annonce la migration « ${entry.tag} », mais son fichier « ${file} » est introuvable. Cette source est incohérente avec elle-même : rien n'a été appliqué, et l'applicateur ne devine jamais le contenu d'un fichier absent. Deux issues, et le statut ci-dessus dit laquelle : si « ${entry.tag} » figure dans l'historique, la migration a DÉJÀ été appliquée et c'est le fichier qu'il faut rendre (contrôle de version) ; si elle n'y figure pas, retirer son entrée de « ${path.join(dir, "meta", "_journal.json")} ». Ne PAS refaire la base : elle porte des données, et rien ici ne les concerne.`);
+	}
+	const normalized = normalizeSql(content);
+	const marker = normalized.split("\n", 1)[0]?.trim() ?? "";
+	if (marker !== "-- nodefony:migration format=1") throw new MigrationVerdictError({
+		code: "NF_MIGRATE_UNKNOWN_FORMAT",
+		connector: "",
+		source,
+		tag: entry.tag,
+		facts: {
+			file,
+			found: marker,
+			expected: FORMAT_MARKER
+		},
+		nextActions: [{
+			command: `nodefony orm:generate --custom --name ${entry.tag}`,
+			args: [
+				"orm:generate",
+				"--custom",
+				"--name",
+				entry.tag
+			]
+		}]
+	}, `Le fichier « ${file} » ne porte pas le format de migration attendu (« ${FORMAT_MARKER} » ; lu : « ${marker} »). Il n'a PAS été appliqué. Un fichier de migration ne s'écrit pas à la main : « --custom » dépose le gabarit, son marqueur et son entrée de journal, et c'est dedans que le SQL libre se met. Sinon, poser « ${FORMAT_MARKER} » en première ligne du fichier.`);
+	return {
+		source,
+		tag: entry.tag,
+		idx: entry.idx,
+		hash: migrationHash(content),
+		statements: splitStatements(normalized, dialect),
+		path: file
+	};
+}
+/**
+* Découpe un fichier de migration en statements exécutables.
+*
+* ## Le séparateur EST un commentaire SQL — et c'est tout le problème
+*
+* `--> statement-breakpoint` commence par deux tirets : pour le moteur, c'est
+* un commentaire, et rien ne le distingue d'un autre à l'œil nu. Deux ordres
+* naïfs échouent donc, chacun pour sa raison, et les deux ont été constatés :
+*
+* - **découper puis retirer les commentaires** fait d'un séparateur écrit DANS
+*   un commentaire un vrai séparateur. La ligne est coupée en deux, et le
+*   fragment de droite — qui ne commence plus par deux tirets — part au pilote
+*   comme une instruction. Le produit se le faisait à lui-même : le gabarit
+*   qu'écrit `orm:generate --custom` porte la phrase qui NOMME le séparateur,
+*   si bien que toute migration libre écrite en suivant son aide échouait sur
+*   une erreur de syntaxe, en laissant dans l'historique une migration `failed`
+*   — c'est-à-dire une base bloquée, à réparer à la main ;
+* - **retirer les commentaires puis découper** emporte les séparateurs
+*   eux-mêmes, et fond toutes les instructions du fichier en une seule.
+*
+* Il n'y a donc pas d'ordre à trouver : les deux décisions se prennent au MÊME
+* moment, ligne par ligne, en sachant si l'on est dans une chaîne littérale.
+* Un commentaire ne peut pas ouvrir un commentaire : dès que la ligne commence
+* par deux tirets sans être le séparateur, tout ce qu'elle porte est du texte.
+*
+* Le séparateur n'est pas reconnu « ligne entière » pour autant : drizzle-kit
+* le colle en fin d'instruction (`CREATE INDEX …;--> statement-breakpoint`), et
+* l'exiger seul sur sa ligne ferait fusionner toutes les instructions d'une
+* migration du framework.
+*
+* ## La grammaire de chaîne est celle du MOTEUR, pas une moyenne des trois
+*
+* Savoir si l'on est dans une chaîne n'a pas la même réponse partout : MySQL
+* échappe l'apostrophe par une contre-oblique, PostgreSQL délimite les corps
+* par `$tag$`. Une grammaire fausse ne lève AUCUNE erreur — le scanner croit
+* sortir d'une chaîne où il est encore, la ligne suivante commençant par deux
+* tirets est retirée comme un commentaire alors qu'elle est de la DONNÉE, ou
+* un séparateur porté par un texte coupe l'instruction en deux. La migration
+* s'inscrit ensuite en succès avec l'empreinte du fichier entier : plus aucun
+* verdict ne peut le voir. Le dialecte est donc un paramètre REQUIS, jamais un
+* défaut — le fichier vit déjà sous `<source>/<dialecte>/`, l'appelant l'a.
+*
+* @param normalized - contenu normalisé (fins de ligne en LF).
+* @param dialect - dialecte du connecteur ; choisit la grammaire de chaîne.
+* @returns les statements non vides, dans l'ordre du fichier.
+*/
+function splitStatements(normalized, dialect) {
+	const grammar = STRING_GRAMMARS[dialect];
+	const statements = [];
+	let current = [];
+	const curseur = {
+		open: "",
+		coupe: -1
+	};
+	/** Clôt le statement en cours — vide, il ne compte pas. */
+	const clore = () => {
+		const statement = current.join("\n").trim();
+		if (statement.length > 0) statements.push(statement);
+		current = [];
+		curseur.open = "";
+	};
+	for (const line of normalized.split("\n")) {
+		if (curseur.open === "") {
+			const tete = line.trimStart();
+			if (tete.startsWith("--> statement-breakpoint")) {
+				clore();
+				continue;
+			}
+			if (tete.startsWith("--")) continue;
+			scanLine(line, STATEMENT_BREAKPOINT, grammar, curseur);
+			const coupe = curseur.coupe;
+			if (coupe >= 0) {
+				current.push(line.slice(0, coupe));
+				clore();
+				const remainder = line.slice(coupe + STATEMENT_BREAKPOINT.length);
+				if (remainder.trim() !== "") {
+					current.push(remainder);
+					scanLine(remainder, "", grammar, curseur);
+				}
+				continue;
+			}
+			current.push(line);
+			continue;
+		}
+		current.push(line);
+		scanLine(line, "", grammar, curseur);
+	}
+	clore();
+	return statements;
+}
+/**
+* La grammaire de chaîne de chaque moteur supporté.
+*
+* SQLite suit le standard et rien de plus : une contre-oblique y est un
+* caractère ordinaire, et `$$` n'est pas un délimiteur. Lui appliquer la
+* grammaire de MySQL serait aussi faux que l'inverse — c'est pourquoi le
+* routage se fait dans les DEUX sens, et pas seulement pour ajouter des cas.
+*/
+const STRING_GRAMMARS = {
+	sqlite: {
+		backslashInSingleQuote: false,
+		apostropheEchappeePrefixee: false,
+		dollarQuote: false
+	},
+	postgres: {
+		backslashInSingleQuote: false,
+		apostropheEchappeePrefixee: true,
+		dollarQuote: true
+	},
+	mysql: {
+		backslashInSingleQuote: true,
+		apostropheEchappeePrefixee: false,
+		dollarQuote: false
+	}
+};
+/** Vrai si `c` peut faire partie d'un identifiant SQL non quoté. */
+function isIdentifierChar(c) {
+	return c !== void 0 && /[A-Za-z0-9_$]/.test(c);
+}
+/**
+* Balaye une ligne : met à jour l'état de chaîne, et repère le motif.
+*
+* UNE seule implémentation pour les deux questions que pose la découpe — « où
+* couper ? » et « la ligne suivante peut-elle porter un commentaire ? ». Elles
+* se répondaient auparavant dans deux fonctions jumelles, chacune avec sa copie
+* de la grammaire : deux copies divergent, et chacune reste verte dans son
+* propre test.
+*
+* Le balayage s'ARRÊTE sur le motif : l'appelant repart alors du reste de la
+* ligne, avec une chaîne close par construction (un statement neuf commence).
+* Passer un motif vide balaye donc la ligne entière.
+*
+* @param line - ligne à balayer.
+* @param needle - texte cherché hors chaîne ; vide pour ne rien chercher.
+* @param grammar - grammaire de chaîne du moteur visé.
+* @param curseur - état lu ET écrit : chaîne ouverte, indice du motif.
+*/
+function scanLine(line, needle, grammar, curseur) {
+	curseur.coupe = -1;
+	let open = curseur.open;
+	for (let i = 0; i < line.length; i += 1) {
+		const c = line[i];
+		if (open.startsWith("$")) {
+			if (line.startsWith(open, i)) {
+				i += open.length - 1;
+				open = "";
+			}
+			continue;
+		}
+		if (open !== "") {
+			if (c === "\\" && (grammar.backslashInSingleQuote || open === "e'")) {
+				i += 1;
+				continue;
+			}
+			if (c === "'") {
+				if (line[i + 1] === "'") {
+					i += 1;
+					continue;
+				}
+				open = "";
+			}
+			continue;
+		}
+		if (c === "'") {
+			open = "'";
+			continue;
+		}
+		if (grammar.apostropheEchappeePrefixee && (c === "E" || c === "e") && line[i + 1] === "'" && !isIdentifierChar(line[i - 1])) {
+			open = "e'";
+			i += 1;
+			continue;
+		}
+		if (grammar.dollarQuote && c === "$") {
+			const tag = delimiteurDollar(line, i);
+			if (tag !== null) {
+				open = tag;
+				i += tag.length - 1;
+				continue;
+			}
+		}
+		if (needle !== "" && line.startsWith(needle, i)) {
+			curseur.coupe = i;
+			curseur.open = open;
+			return;
+		}
+	}
+	curseur.open = open;
+}
+/**
+* Le délimiteur `$tag$` qui commence à `debut`, ou `null`.
+*
+* Le tag est optionnel (`$$`) et suit les règles d'un identifiant : ce qui
+* exclut `$1`, un paramètre de requête, qu'il ne faut surtout pas lire comme
+* l'ouverture d'une chaîne.
+*
+* @param line - ligne balayée.
+* @param debut - indice du `$` candidat.
+* @returns le délimiteur complet, ou `null` si ce n'en est pas un.
+*/
+function delimiteurDollar(line, debut) {
+	let i = debut + 1;
+	while (i < line.length && /[A-Za-z0-9_]/.test(line[i])) {
+		if (i === debut + 1 && /[0-9]/.test(line[i])) return null;
+		i += 1;
+	}
+	return line[i] === "$" ? line.slice(debut, i + 1) : null;
+}
+/**
+* Noms des tables qu'un lot de migrations CRÉE.
+*
+* Sert la garde d'adoption : un historique vide alors que ces tables existent
+* déjà signale une base antérieure aux migrations, pas une base neuve. La
+* liste est DÉRIVÉE des fichiers — une liste codée en dur mentirait dès la
+* première migration livrée par un module tiers.
+*
+* @param files - fichiers de migration chargés.
+* @returns les noms de tables, sans doublon.
+*/
+function createdTables(files) {
+	const found = /* @__PURE__ */ new Set();
+	const pattern = /CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[`"']?([A-Za-z0-9_$]+)[`"']?/gi;
+	for (const file of files) for (const statement of file.statements) for (const match of statement.matchAll(pattern)) found.add(match[1]);
+	return [...found];
+}
+/**
+* Tables que le FRAMEWORK construit — dérivées de ses fichiers de migration.
+*
+* Dérivées, jamais listées à la main : une liste codée en dur mentirait dès la
+* première migration livrée par une version suivante.
+*
+* Une seule implémentation, parce que deux appelants en dépendent pour la même
+* décision — le générateur les exclut de ce qu'il écrit, l'adoption les exclut
+* de ce qu'elle lit. Deux copies divergeraient en silence, chacune verte dans
+* son propre test.
+*
+* @param dialect - dialecte du connecteur visé.
+* @returns les noms de tables du framework.
+*/
+async function frameworkTables(dialect) {
+	const { files } = await loadSources([{
+		name: "framework",
+		dir: await frameworkMigrationsDir(),
+		rank: 0
+	}], dialect);
+	return createdTables(files);
+}
+//#endregion
+export { SUPPORTED_JOURNAL_VERSIONS, createdTables, frameworkTables, loadSources, orderSources, splitStatements };

package/dist/nodefony/src/migrator/status.js

@@ -0,0 +1,231 @@
+import { MigrationVerdictError } from "./types.js";
+import { action, buildReport } from "./explain.js";
+import { buildMigrator, readMigrationEnv, resetAllowed, resolveConnector } from "./resolve.js";
+import { describeResolutionRefusal, moduleAbsent } from "./refusals.js";
+import { describeDivergence } from "./divergence.js";
+import { describeTargetSafely } from "../safeTarget.js";
+//#region nodefony/src/migrator/status.ts
+/**
+* Habille un refus en charge utile publiée — la MÊME que celle de `--json`.
+*
+* @param connector - connecteur demandé.
+* @param refusal - ce qu'il y a à en dire.
+* @returns la charge utile d'arrêt.
+*/
+function failureFrom(connector, refusal) {
+	return {
+		formatVersion: 1,
+		connector,
+		exitCode: refusal.exitCode,
+		error: {
+			code: refusal.code,
+			summary: refusal.summary,
+			meaning: refusal.meaning,
+			nextActions: refusal.nextActions
+		}
+	};
+}
+/**
+* Compose la charge utile d'un état — le SEUL endroit où le contexte du rendu
+* est assemblé.
+*
+* Les quatre commandes de migration ET le plan d'administration publient le
+* même objet ; recopier son assemblage les faisait déjà diverger d'un champ à
+* l'autre, et le prochain consommateur à naître aurait oublié celui du jour.
+* La troisième source ne se paie qu'ici, une fois : `describeDivergence`
+* s'abstient toute seule quand le verdict est déjà décidé.
+*
+* @param plan - plan calculé par l'applicateur, en lecture seule.
+* @param resolution - connecteur prêt (porte le mode de schéma effectif).
+* @param config - configuration validée du module.
+* @param kernel - kernel courant, pour constater l'environnement.
+* @returns la charge utile, prête pour `--json` comme pour l'écran.
+*/
+async function composeReport(plan, resolution, config, kernel) {
+	const mode = config.migrations.divergence;
+	return buildReport(plan, {
+		ddl: resolution.ddl,
+		divergence: mode === "off" ? null : await describeDivergence(plan),
+		divergenceMode: mode,
+		canReset: resetAllowed(readMigrationEnv(kernel)),
+		target: describeTargetSafely(resolution.target),
+		fromMigrateUrl: resolution.fromMigrateUrl
+	});
+}
+/**
+* Résout le connecteur pour les trois verbes — ou rend le refus.
+*
+* Les trois posent la même question dans le même ordre : le module est-il
+* chargé, le connecteur existe-t-il, est-il migrable. Trois copies auraient
+* fini par répondre trois choses différentes au même cas.
+*
+* @param wanted - connecteur demandé.
+* @param config - configuration validée, `null` si le module n'est pas chargé.
+* @param kernel - kernel courant.
+* @returns le connecteur prêt et sa configuration, ou le refus.
+*/
+function prepare(wanted, config, kernel) {
+	if (!config) return {
+		ok: false,
+		failure: failureFrom(wanted, moduleAbsent())
+	};
+	const resolution = resolveConnector(wanted, config, readMigrationEnv(kernel), kernel, { allowMigrateUrl: false });
+	if (resolution.kind !== "ready") return {
+		ok: false,
+		failure: failureFrom(wanted, describeResolutionRefusal(wanted, resolution, config))
+	};
+	return {
+		ok: true,
+		resolution,
+		config
+	};
+}
+/**
+* Traduit n'importe quel échec d'exécution en charge utile publiée.
+*
+* Un refus de l'applicateur porte DÉJÀ son verdict et ses gestes : on les rend
+* tels quels. Tout le reste — base injoignable, droits manquants, verrou
+* impossible — est une panne, et l'écran doit la MONTRER : un tableau vide qui
+* ressemble à « tout va bien » est pire qu'une erreur.
+*
+* @param connector - connecteur concerné.
+* @param e - ce qui a été levé.
+* @returns la charge utile d'arrêt.
+*/
+function failure(connector, e) {
+	if (e instanceof MigrationVerdictError) return {
+		formatVersion: 1,
+		connector,
+		exitCode: e.verdict.code === "NF_MIGRATE_LOCK_TIMEOUT" ? 2 : 1,
+		error: {
+			code: e.verdict.code,
+			summary: e.message,
+			meaning: "",
+			nextActions: [...e.verdict.nextActions]
+		}
+	};
+	return {
+		formatVersion: 1,
+		connector,
+		exitCode: 2,
+		error: {
+			code: "NF_MIGRATE_UNAVAILABLE",
+			summary: `Le connecteur « ${connector} » n'a pas pu être lu : ${e instanceof Error ? e.message : String(e)}`,
+			meaning: "Toucher une base échoue quand celle-ci est injoignable, quand le compte n'a pas le droit de lire l'historique, ou quand le verrou est tenu par un autre travail.",
+			nextActions: [action(`nodefony orm:migrate:status --connector ${connector}`)]
+		}
+	};
+}
+/**
+* Lit l'état des migrations d'un connecteur, sans rien appliquer.
+*
+* @param wanted - connecteur demandé (`default` quand rien n'est précisé).
+* @param config - configuration validée du module, `null` s'il n'est pas chargé.
+* @param kernel - kernel courant.
+* @returns l'état, ou le refus qui explique pourquoi il n'y en a pas.
+*/
+async function migrationStatusFor(wanted, config, kernel) {
+	const prepared = prepare(wanted, config, kernel);
+	if (!prepared.ok) return prepared;
+	try {
+		return {
+			ok: true,
+			report: await composeReport(await (await buildMigrator(prepared.resolution, prepared.config, kernel)).status(), prepared.resolution, prepared.config, kernel)
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			failure: failure(prepared.resolution.connector, e)
+		};
+	}
+}
+/**
+* Ce qui S'APPLIQUERAIT, avec son SQL — lecture seule.
+*
+* Sert la confirmation d'un geste d'application : une modification de schéma
+* ne se confirme pas sur une promesse, elle se confirme sur les instructions
+* qui vont être exécutées.
+*
+* @param wanted - connecteur demandé.
+* @param config - configuration validée du module, `null` s'il n'est pas chargé.
+* @param kernel - kernel courant.
+* @returns le plan, ou le refus.
+*/
+async function migrationPlanFor(wanted, config, kernel) {
+	const prepared = prepare(wanted, config, kernel);
+	if (!prepared.ok) return prepared;
+	try {
+		const plan = await (await buildMigrator(prepared.resolution, prepared.config, kernel)).status();
+		return {
+			ok: true,
+			plan: {
+				formatVersion: 1,
+				connector: plan.connector,
+				pending: plan.pending.map((f) => ({
+					source: f.source,
+					tag: f.tag,
+					statements: [...f.statements]
+				}))
+			}
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			failure: failure(prepared.resolution.connector, e)
+		};
+	}
+}
+/**
+* Applique les migrations en attente — **DÉVELOPPEMENT seulement**.
+*
+* 🔴 Le refus hors développement n'est pas une précaution d'interface, c'est la
+* doctrine : en production, les migrations s'appliquent dans un travail
+* d'orchestrateur qui se termine AVANT que le premier nouvel exemplaire ne
+* démarre. Les appliquer au clic de quelqu'un qui regarde une console pendant
+* que le trafic passe, c'est modifier un schéma sous les pieds des exemplaires
+* en service. La garde vit ICI, dans le produit — jamais dans l'écran, qui ne
+* protège que celui qui le regarde.
+*
+* @param wanted - connecteur demandé.
+* @param config - configuration validée du module, `null` s'il n'est pas chargé.
+* @param kernel - kernel courant.
+* @returns ce qui a été appliqué, ou le refus.
+*/
+async function applyMigrationsFor(wanted, config, kernel) {
+	const env = readMigrationEnv(kernel);
+	if (!resetAllowed(env)) return {
+		ok: false,
+		failure: failureFrom(wanted, {
+			code: "NF_MIGRATE_NOT_DEVELOPMENT",
+			summary: "Appliquer les migrations depuis la console d'administration est réservé au développement. Rien n'a été appliqué.",
+			meaning: "En production, les migrations s'appliquent dans un travail dédié qui se termine AVANT que le premier nouvel exemplaire ne démarre — le fichier `deploy/migrate-job.yaml` d'une application générée en est la recette. Les appliquer depuis un serveur qui sert le trafic reviendrait à changer le schéma sous les pieds des exemplaires en service.",
+			nextActions: [action(`nodefony orm:migrate --connector ${wanted}`), action(`nodefony orm:migrate:status --connector ${wanted}`)],
+			exitCode: 1
+		})
+	};
+	const prepared = prepare(wanted, config, kernel);
+	if (!prepared.ok) return prepared;
+	try {
+		const run = await (await buildMigrator(prepared.resolution, prepared.config, kernel)).migrate();
+		return {
+			ok: true,
+			run: {
+				formatVersion: 1,
+				connector: prepared.resolution.connector,
+				runId: run.runId,
+				applied: run.applied.map((a) => ({
+					source: a.source,
+					tag: a.tag,
+					executionMs: a.executionMs
+				}))
+			}
+		};
+	} catch (e) {
+		return {
+			ok: false,
+			failure: failure(prepared.resolution.connector, e)
+		};
+	}
+}
+//#endregion
+export { applyMigrationsFor, composeReport, failureFrom, migrationPlanFor, migrationStatusFor };