@nodefony/devkit 10.0.0-beta.3 → 10.0.0-beta.5

package/dist/nodefony/mcp/profileRoute.js

@@ -0,0 +1,521 @@
+import { renderProfileReport } from "./profileReport.js";
+import { watchToolStop } from "./shutdown.js";
+import { NOT_SERVING_MESSAGE } from "./observe.js";
+import { SHOT_REQUEST_TIMEOUT_MS, createShotClient } from "./shotClient.js";
+import { PROFILE_SESSION_PATH } from "../src/profileSession.js";
+import { ADMIN_SCOPE_WRITE, EVENT_LOOP_RESOLUTION_MS, ProcessProbe } from "nodefony";
+import { MCP_RESERVED_PREFIX, SESSION_TICKET_HEADER, mcpText, readTicketSessionVerdict } from "@nodefony/ai";
+import { setTimeout } from "node:timers/promises";
+import { N_PLUS_ONE_MIN_REPEATS, aggregateProfiles, isFailedProfile } from "@nodefony/http";
+import { randomBytes } from "node:crypto";
+// nodefony/mcp/profileRoute.ts
+/** Requêtes mesurées par défaut. */
+const PROFILE_ROUTE_DEFAULT_COUNT = 50;
+/**
+* Requêtes mesurées au plus. Avec la chauffe, sous les 500 profils que garde le
+* profileur : au-delà, les premiers seraient évincés avant d'être lus.
+*/
+const PROFILE_ROUTE_MAX_COUNT = 200;
+/** Requêtes simultanées par défaut. */
+const PROFILE_ROUTE_DEFAULT_CONCURRENCY = 4;
+/** Requêtes simultanées au plus : mesurer une route, pas saturer le process. */
+const PROFILE_ROUTE_MAX_CONCURRENCY = 8;
+/** Requêtes de chauffe par défaut, tirées AVANT et hors des mesures. */
+const PROFILE_ROUTE_DEFAULT_WARMUP = 3;
+/** Requêtes de chauffe au plus. */
+const PROFILE_ROUTE_MAX_WARMUP = 20;
+/**
+* Budget de temps d'un tir, en ms. Sous les 60 s qu'un client MCP attend par
+* défaut : au-delà, l'agent couperait l'appel juste avant le rapport.
+*/
+const PROFILE_ROUTE_BUDGET_MS = 45e3;
+/**
+* Attente maximale, en ms, d'un profil après la réponse : le profileur le
+* collecte au `close` de la réponse, émis en différé — rien ne garantit qu'il
+* précède la fin de lecture côté client, dans le même process.
+*/
+const PROFILE_COLLECT_WAIT_MS = 500;
+/**
+* Périodes d'échantillonnage de la boucle d'événements en deçà desquelles la
+* sonde n'a rien mesuré de fiable : un tir plus court rend « non mesurée »,
+* jamais un 0 qui passerait pour une boucle libre.
+*/
+const EVENT_LOOP_MIN_PERIODS = 5;
+/** Longueur maximale d'un chemin profilé. */
+const PROFILE_PATH_MAX = 2048;
+/** Instantanés de progression par tir, au plus. */
+const PROGRESS_STEPS = 10;
+const LOOPBACK_BASE = "http://127.0.0.1";
+/**
+* Le contrat de l'outil tel que l'agent le lit dans `tools/list`. Les bornes
+* citées sont les constantes du code. Composée une fois, au chargement.
+*/
+const PROFILE_ROUTE_DESCRIPTION = `Mesure UNE route de l'application Nodefony qui tourne : l'outil lui envoie lui-même N requêtes, retrouve leurs profils par l'identifiant qu'il pose (x-request-id) et rend le même rapport que nodefony_observe — p50/p95, requêtes SQL par requête, N+1, où part le temps (action.self, SQL, render, firewall), erreurs. Ferme la boucle « je modifie → je mesure » en un appel.
+
+QUAND : après avoir modifié le contrôleur, le service ou la requête d'une page ; pour comparer avant/après ; face à « cette page est lente » ou « trop de requêtes SQL ». Pour observer un trafic que l'on génère soi-même (tests, navigation), prendre nodefony_observe.
+
+COMMENT :
+1. path = un CHEMIN de l'application avec sa requête (\`/orders?page=2\`), jamais une URL : hôte, schéma et \`//\` sont refusés.
+2. count (défaut 50, max 200), concurrency (défaut 4, max 8), warmup (défaut 3, max 20 : requêtes tirées avant, hors mesures — le premier appel compile et se connecte), method GET (défaut) ou HEAD.
+3. IDENTITÉ — une page protégée vue sans compte ne rend que des refus. Par défaut l'outil joue le PROPRIÉTAIRE du jeton MCP si ce jeton porte le scope ${ADMIN_SCOPE_WRITE} : il ouvre une session à son nom (tous ses rôles), tire avec, puis la détruit. \`as: "<identifiant>"\` joue un autre compte (scope ${ADMIN_SCOPE_WRITE}, et ses rôles doivent être inclus dans ceux du propriétaire). \`anonymous: true\` force l'anonyme. Sans ce scope : anonyme, et le rapport dit comment obtenir le jeton.
+4. Corriger la cause nommée, rappeler l'outil avec les mêmes arguments et comparer le bloc « Données (JSON) ».
+Ne modifier AUCUN fichier pendant le tir : le serveur redémarre et le rapport rendu est partiel (il le dit).
+
+LE RAPPORT : en tête, ce qui invalide la mesure — requêtes REFUSÉES (401/403), REDIRIGÉES (page de connexion), sans réponse, profils non retrouvés ; puis le tir (identité jouée, chauffe, statuts reçus), les anomalies (« N+1 » : même requête SQL ≥ ${N_PLUS_ONE_MIN_REPEATS} fois par requête ; « Lente » : p95 ≥ 500 ms ; « Erreurs » 5xx avec leur journal), le tableau par route et les requêtes SQL les plus coûteuses (valeurs masquées).
+
+LIMITES : développement seulement ; GET et HEAD seulement ; HTTP en clair de l'application elle-même. Les zones à jeton (jwt, external-jwt) ne sont pas jouées : leurs requêtes rendent 401, et le rapport le dit. Tir borné à ${PROFILE_ROUTE_BUDGET_MS / 1e3} s, ${SHOT_REQUEST_TIMEOUT_MS / 1e3} s par requête. Un instantané de progression par lot.`;
+/**
+* Contrôle le chemin à profiler : un CHEMIN de l'application, jamais une URL —
+* l'outil ne doit pouvoir viser qu'elle.
+*
+* @param raw - l'argument `path`, non fiable.
+* @returns le chemin normalisé (fragment retiré), ou la raison du refus.
+*/
+function checkProfilePath(raw) {
+	if (typeof raw !== "string" || raw.length === 0) return {
+		ok: false,
+		reason: "path est requis : un chemin de l'application, ex. /orders?page=2"
+	};
+	if (raw.length > PROFILE_PATH_MAX) return {
+		ok: false,
+		reason: `path dépasse ${PROFILE_PATH_MAX} caractères`
+	};
+	if (!raw.startsWith("/") || raw.startsWith("//") || /[\\\s\u0000-\u001f\u007f]/u.test(raw)) return {
+		ok: false,
+		reason: "path doit être un CHEMIN commençant par un seul « / », sans antislash, espace ni caractère de contrôle — jamais une URL ni un hôte : l'outil ne vise que l'application"
+	};
+	const url = new URL(raw, LOOPBACK_BASE);
+	if (url.origin !== LOOPBACK_BASE) return {
+		ok: false,
+		reason: "path sort de l'application"
+	};
+	return {
+		ok: true,
+		path: url.pathname + url.search
+	};
+}
+/** Entier borné — et la remarque à faire s'il a été corrigé. */
+function readBounded(raw, name, fallback, min, max) {
+	if (raw === void 0) return {
+		value: fallback,
+		note: null
+	};
+	if (typeof raw !== "number" || !Number.isFinite(raw)) return {
+		value: fallback,
+		note: `${name} illisible, ${fallback} retenu`
+	};
+	const value = Math.min(Math.max(Math.round(raw), min), max);
+	return {
+		value,
+		note: value === raw ? null : `${name} ramené à ${value} (bornes ${min}–${max})`
+	};
+}
+/** L'identité à jouer, ou le refus à rendre à l'agent. */
+async function resolveIdentity(args, caller, deps) {
+	if (args.anonymous === true) return {
+		ok: true,
+		identity: {
+			kind: "anonymous",
+			why: null
+		},
+		account: null
+	};
+	const owner = caller.authenticated && typeof caller.subject === "string" && caller.subject.length > 0 && caller.scopes.includes(ADMIN_SCOPE_WRITE) ? caller.subject : null;
+	const as = typeof args.as === "string" && args.as.length > 0 ? args.as : null;
+	if (as !== null) {
+		if (owner === null) return {
+			ok: false,
+			message: `\`as\` exige un jeton MCP portant le scope ${ADMIN_SCOPE_WRITE} : jouer un compte, c'est agir en son nom. Jeton : \`npx nodefony security:mcp:token --scope "admin:read admin:write" --write\`.`
+		};
+		if (as !== owner) {
+			const verdict = deps.rolesWithin === void 0 ? {
+				ok: false,
+				reason: "comparaison des rôles indisponible"
+			} : await deps.rolesWithin(owner, as);
+			if (!verdict.ok) return {
+				ok: false,
+				message: `\`as: "${as}"\` refusé — ${verdict.reason}. Jouer un autre compte ne doit jamais monter en droits : ses rôles doivent être inclus dans ceux du propriétaire du jeton (\`${owner}\`).`
+			};
+		}
+		return {
+			ok: true,
+			identity: {
+				kind: "anonymous",
+				why: null
+			},
+			account: as
+		};
+	}
+	if (owner !== null) return {
+		ok: true,
+		identity: {
+			kind: "anonymous",
+			why: null
+		},
+		account: owner
+	};
+	return {
+		ok: true,
+		account: null,
+		identity: {
+			kind: "anonymous",
+			why: caller.authenticated ? `le jeton MCP n'a pas le scope ${ADMIN_SCOPE_WRITE}` : "appel sans jeton MCP"
+		}
+	};
+}
+/** Ouvre la session du tir par la route de connexion du profilage. */
+async function openShotSession(client, issueTicket, account, signal) {
+	let ticket;
+	try {
+		ticket = issueTicket(account);
+	} catch (error) {
+		return {
+			ok: false,
+			message: error instanceof Error ? error.message : String(error)
+		};
+	}
+	const res = await client.send({
+		method: "POST",
+		path: PROFILE_SESSION_PATH,
+		headers: { [SESSION_TICKET_HEADER]: ticket },
+		readBody: true
+	}, signal);
+	const read = readTicketSessionVerdict(res.body);
+	if (res.status !== 200 || "message" in read) {
+		const why = "message" in read ? read.message : `statut ${res.status}`;
+		return {
+			ok: false,
+			message: `session de profilage non ouverte pour \`${account}\` (${res.status} — ${why}). ` + (res.status === 403 ? "Compte inconnu, inactif ou verrouillé ?" : res.status === 503 ? "" : "La route de connexion du profilage répond-elle ?")
+		};
+	}
+	const cookie = res.setCookie.map((c) => c.split(";", 1)[0] ?? "").filter((c) => c.length > 0).join("; ");
+	if (cookie.length === 0) return {
+		ok: false,
+		message: `session ouverte pour \`${account}\`, mais aucun cookie reçu`
+	};
+	return {
+		ok: true,
+		session: {
+			cookie,
+			ref: read.ref,
+			identifier: read.identifier,
+			roles: read.roles
+		}
+	};
+}
+/** Comptes du client, mis à jour réponse par réponse. */
+function emptyClientStatus() {
+	return {
+		ok: 0,
+		redirected: 0,
+		unauthorized: 0,
+		forbidden: 0,
+		clientError: 0,
+		serverError: 0,
+		failed: 0,
+		location: null,
+		failure: null
+	};
+}
+function countStatus(c, status, location) {
+	if (status === 401) c.unauthorized += 1;
+	else if (status === 403) c.forbidden += 1;
+	else if (status >= 500) c.serverError += 1;
+	else if (status >= 400) c.clientError += 1;
+	else if (status >= 300) {
+		c.redirected += 1;
+		c.location ??= location;
+	} else c.ok += 1;
+}
+/** Le tir proprement dit : un groupe de requêtes, `concurrency` à la fois. */
+async function fire(client, ids, opts) {
+	const outcomes = [];
+	let next = 0;
+	let truncated = false;
+	const worker = async () => {
+		for (;;) {
+			if (opts.signal.aborted) return;
+			if (performance.now() >= opts.deadline) {
+				truncated = next < ids.length;
+				return;
+			}
+			const index = next;
+			next += 1;
+			const requestId = ids[index];
+			if (requestId === void 0) return;
+			try {
+				const res = await client.send({
+					method: opts.method,
+					path: opts.path,
+					headers: {
+						...opts.headers,
+						"x-request-id": requestId
+					}
+				}, opts.signal);
+				outcomes.push({
+					requestId,
+					status: res.status
+				});
+				if (opts.status !== null) countStatus(opts.status, res.status, res.location);
+			} catch (error) {
+				if (error instanceof Error && error.name === "AbortError") return;
+				outcomes.push({
+					requestId,
+					status: null
+				});
+				if (opts.status !== null) {
+					opts.status.failed += 1;
+					opts.status.failure ??= error instanceof Error ? error.message : String(error);
+				}
+			}
+			opts.onDone?.(outcomes.length);
+		}
+	};
+	await Promise.all(Array.from({ length: opts.concurrency }, worker));
+	return {
+		outcomes,
+		truncated
+	};
+}
+/**
+* Retrouve les profils des requêtes tirées, par leur identifiant. Un profil
+* peut arriver APRÈS la réponse : attente bornée, puis le reste est compté.
+*/
+async function collectProfiles(profiler, outcomes, waitMs) {
+	const entries = [];
+	let pending = [];
+	for (const o of outcomes) {
+		if (o.status === null) continue;
+		const entry = profiler.get(o.requestId);
+		if (entry === void 0) pending.push(o.requestId);
+		else entries.push(entry);
+	}
+	const deadline = performance.now() + waitMs;
+	while (pending.length > 0 && performance.now() < deadline) {
+		await setTimeout(10);
+		pending = pending.filter((id) => {
+			const entry = profiler.get(id);
+			if (entry === void 0) return true;
+			entries.push(entry);
+			return false;
+		});
+	}
+	return {
+		entries,
+		missing: pending.length
+	};
+}
+/**
+* L'outil `nodefony_profile_route` : envoie lui-même N requêtes à une route de
+* l'application, au nom d'un compte s'il le faut, et rend leur profil agrégé.
+*
+* Rien n'est armé hors d'un appel : le client du tir (ses connexions), la
+* session de profilage et l'écoute de l'arrêt du serveur naissent avec l'appel
+* et sont libérés à sa sortie, quelle qu'elle soit.
+*
+* @param deps - profileur, adresse d'écoute, ouverture de session, journal.
+*/
+function profileRouteTool(deps) {
+	return {
+		name: `${MCP_RESERVED_PREFIX}profile_route`,
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: true,
+			openWorldHint: false
+		},
+		description: PROFILE_ROUTE_DESCRIPTION,
+		inputSchema: {
+			type: "object",
+			required: ["path"],
+			properties: {
+				path: {
+					type: "string",
+					description: "CHEMIN de l'application, requête comprise (`/orders?page=2`) — jamais une URL"
+				},
+				count: {
+					type: "integer",
+					minimum: 1,
+					maximum: 200,
+					description: `Requêtes mesurées (défaut 50, max 200)`
+				},
+				concurrency: {
+					type: "integer",
+					minimum: 1,
+					maximum: 8,
+					description: `Requêtes simultanées (défaut 4, max 8)`
+				},
+				warmup: {
+					type: "integer",
+					minimum: 0,
+					maximum: 20,
+					description: `Requêtes de chauffe, hors mesures (défaut 3, max 20)`
+				},
+				method: {
+					type: "string",
+					enum: ["GET", "HEAD"],
+					description: "Méthode (défaut GET)"
+				},
+				as: {
+					type: "string",
+					description: `Identifiant du compte à jouer (scope ${ADMIN_SCOPE_WRITE} ; rôles inclus dans ceux du propriétaire du jeton)`
+				},
+				anonymous: {
+					type: "boolean",
+					description: "Jouer en anonyme, même avec un jeton qui permettrait un compte"
+				}
+			}
+		},
+		scopesFor: (args) => args.anonymous !== true && typeof args.as === "string" && args.as !== "" ? [ADMIN_SCOPE_WRITE] : [],
+		handler: async (args, caller, run) => {
+			if (deps.servesTraffic?.() === false) return mcpText(NOT_SERVING_MESSAGE, true);
+			const profiler = deps.getProfiler();
+			if (profiler === void 0) return mcpText("Aucun profileur dans cette application : il n'existe qu'en développement, et seulement si `@nodefony/http` est chargé.", true);
+			const path = checkProfilePath(args.path);
+			if (!path.ok) return mcpText(`Refusé : ${path.reason}.`, true);
+			if (args.method !== void 0 && args.method !== "GET" && args.method !== "HEAD") return mcpText("Refusé : method vaut GET ou HEAD — les seules méthodes sûres et idempotentes (RFC 9110) ; l'outil ne déclenche aucune écriture.", true);
+			const target = deps.getTarget();
+			if (target === null) return mcpText("Aucun serveur HTTP en clair prêt dans cette application : rien à viser.", true);
+			const identity = await resolveIdentity(args, caller, deps);
+			if (!identity.ok) return mcpText(identity.message, true);
+			const count = readBounded(args.count, "count", 50, 1, 200);
+			const concurrency = readBounded(args.concurrency, "concurrency", 4, 1, 8);
+			const warmup = readBounded(args.warmup, "warmup", 3, 0, 20);
+			const notes = [
+				count.note,
+				concurrency.note,
+				warmup.note
+			].filter((n) => n !== null);
+			return profileRoute(profiler, target, deps, {
+				method: args.method === "HEAD" ? "HEAD" : "GET",
+				path: path.path,
+				count: count.value,
+				concurrency: concurrency.value,
+				warmup: warmup.value,
+				identity: identity.identity,
+				account: identity.account,
+				caller,
+				run,
+				notes
+			});
+		}
+	};
+}
+async function profileRoute(profiler, target, deps, opts) {
+	const stop = watchToolStop(opts.run, deps.onShutdown);
+	const client = (deps.createClient ?? createShotClient)(target, opts.concurrency);
+	const probe = (deps.createProbe ?? (() => new ProcessProbe()))();
+	const budgetMs = deps.budgetMs ?? 45e3;
+	const started = performance.now();
+	const deadline = started + budgetMs;
+	const runId = randomBytes(4).toString("hex");
+	const ids = (prefix, n) => Array.from({ length: n }, (_, i) => `nf-prof-${runId}-${prefix}${i + 1}`);
+	let session = null;
+	let identity = opts.identity;
+	try {
+		const headers = { "user-agent": "nodefony-profile-route" };
+		if (opts.account !== null) {
+			if (deps.issueTicket === void 0) return mcpText("Profilage authentifié indisponible : aucun émetteur de ticket.", true);
+			const opened = await openShotSession(client, deps.issueTicket, opts.account, stop.signal);
+			if (!opened.ok) return mcpText(opened.message, true);
+			session = opened.session;
+			headers.cookie = session.cookie;
+			identity = {
+				kind: "account",
+				identifier: session.identifier,
+				roles: session.roles,
+				impersonated: opts.caller.subject !== opts.account
+			};
+		}
+		probe.read();
+		const probeStart = performance.now();
+		const shared = {
+			method: opts.method,
+			path: opts.path,
+			headers,
+			concurrency: opts.concurrency,
+			signal: stop.signal,
+			deadline
+		};
+		const warm = await fire(client, ids("w", opts.warmup), {
+			...shared,
+			status: null
+		});
+		const status = emptyClientStatus();
+		const step = Math.max(1, Math.ceil(opts.count / PROGRESS_STEPS));
+		let ticks = 0;
+		opts.run?.progress(0, opts.count, `tir de ${opts.count} requête(s) ${opts.method} ${opts.path}`);
+		const shot = await fire(client, ids("", opts.count), {
+			...shared,
+			status,
+			onDone: (done) => {
+				if (done % step !== 0 && done !== opts.count) return;
+				ticks += 1;
+				opts.run?.progress(done, opts.count, `${done}/${opts.count} · 2xx ${status.ok} · refus ${status.unauthorized + status.forbidden} · 5xx ${status.serverError}`);
+			}
+		});
+		const health = probe.read();
+		const probedMs = performance.now() - probeStart;
+		const waitMs = deps.collectWaitMs ?? 500;
+		const warmed = await collectProfiles(profiler, warm.outcomes, waitMs);
+		const measured = await collectProfiles(profiler, shot.outcomes, waitMs);
+		const warmRoute = aggregateProfiles(warmed.entries, { includeTooling: true }).routes[0];
+		const report = aggregateProfiles(measured.entries, { includeTooling: true });
+		let errorLogs = null;
+		const read = deps.readRequestLogs;
+		if (read !== void 0) {
+			errorLogs = /* @__PURE__ */ new Map();
+			for (const entry of measured.entries) {
+				if (errorLogs.size >= 10) break;
+				if (!isFailedProfile(entry)) continue;
+				errorLogs.set(entry.requestId, await read(entry.requestId, opts.caller).catch(() => ({
+					kind: "unavailable",
+					reason: "la lecture du journal a échoué"
+				})));
+			}
+		}
+		const elapsedMs = performance.now() - started;
+		const text = renderProfileReport(report, {
+			windowMs: elapsedMs,
+			elapsedMs,
+			ticks,
+			lost: 0,
+			cancelled: stop.signal.aborted && !stop.interrupted,
+			interrupted: stop.interrupted,
+			errorLogs,
+			route: null,
+			filteredRoute: 0,
+			pid: process.pid,
+			uptimeSec: process.uptime(),
+			eventLoop: probedMs < EVENT_LOOP_RESOLUTION_MS * EVENT_LOOP_MIN_PERIODS ? null : {
+				meanMs: health.eventLoopMs,
+				maxMs: health.eventLoopMaxMs
+			},
+			heapDeltaBytes: null,
+			shot: {
+				method: opts.method,
+				path: opts.path,
+				requested: opts.count,
+				sent: shot.outcomes.length,
+				concurrency: opts.concurrency,
+				identity,
+				warmup: {
+					count: warm.outcomes.length,
+					p50Ms: warmRoute?.p50Ms ?? null,
+					maxMs: warmRoute?.maxMs ?? null
+				},
+				client: status,
+				missing: measured.missing,
+				truncated: shot.truncated || warm.truncated,
+				budgetMs
+			}
+		});
+		return mcpText(opts.notes.length === 0 ? text : `ℹ️ ${opts.notes.join(" · ")}.\n${text}`);
+	} finally {
+		client.close();
+		probe.dispose();
+		if (session !== null && deps.closeSession !== void 0) await deps.closeSession(session.ref).catch(() => void 0);
+		stop.release();
+	}
+}
+export { PROFILE_COLLECT_WAIT_MS, PROFILE_ROUTE_BUDGET_MS, PROFILE_ROUTE_DEFAULT_CONCURRENCY, PROFILE_ROUTE_DEFAULT_COUNT, PROFILE_ROUTE_DEFAULT_WARMUP, PROFILE_ROUTE_MAX_CONCURRENCY, PROFILE_ROUTE_MAX_COUNT, PROFILE_ROUTE_MAX_WARMUP, checkProfilePath, profileRouteTool };

package/dist/nodefony/mcp/shotClient.js

@@ -0,0 +1,84 @@
+import http from "node:http";
+// nodefony/mcp/shotClient.ts
+/** Délai d'une requête du tir, en ms : au-delà, elle compte « sans réponse ». */
+const SHOT_REQUEST_TIMEOUT_MS = 15e3;
+/**
+* Client `node:http` d'un tir : connexions gardées ouvertes entre deux requêtes,
+* comme un navigateur, au plus `concurrency` à la fois, toutes fermées par
+* `close()`. Un `fetch` passerait par un pool global, qui survivrait à l'appel.
+*
+* @param target - l'adresse d'écoute de l'application.
+* @param concurrency - connexions simultanées au plus.
+* @returns le client, à fermer en fin de tir.
+*/
+function createShotClient(target, concurrency) {
+	const agent = new http.Agent({
+		keepAlive: true,
+		maxSockets: concurrency
+	});
+	return {
+		send(request, signal) {
+			return new Promise((resolve, reject) => {
+				const req = http.request({
+					host: target.host,
+					port: target.port,
+					method: request.method,
+					path: request.path,
+					agent,
+					signal,
+					timeout: SHOT_REQUEST_TIMEOUT_MS,
+					headers: {
+						...request.headers,
+						host: target.hostHeader
+					}
+				});
+				req.once("timeout", () => {
+					req.destroy(/* @__PURE__ */ new Error("délai de réponse dépassé"));
+				});
+				req.once("error", reject);
+				req.once("response", (res) => {
+					const chunks = request.readBody ? [] : null;
+					if (chunks === null) res.resume();
+					else res.on("data", (chunk) => chunks.push(chunk));
+					res.once("error", reject);
+					res.once("end", () => {
+						const location = res.headers.location;
+						resolve({
+							status: res.statusCode ?? 0,
+							location: typeof location === "string" ? location : null,
+							setCookie: res.headers["set-cookie"] ?? [],
+							body: chunks === null ? null : Buffer.concat(chunks).toString("utf8")
+						});
+					});
+				});
+				req.end();
+			});
+		},
+		close() {
+			agent.destroy();
+		}
+	};
+}
+/**
+* Lit l'adresse d'écoute du serveur HTTP en clair de l'application (service
+* `server-http`), telle qu'il l'a réellement obtenue — port de repli compris.
+*
+* Une écoute sur toutes les interfaces (`0.0.0.0`, `::`) se joint par la boucle
+* locale : c'est aussi ce qui rend l'appel LOCAL pour la route de connexion du
+* profilage.
+*
+* @param server - ce que le conteneur rend pour `server-http`.
+* @returns la cible, ou `null` si aucun serveur n'est prêt.
+*/
+function readShotTarget(server) {
+	if (typeof server !== "object" || server === null || !("ready" in server) || server.ready !== true || !("port" in server) || typeof server.port !== "number" || server.port <= 0) return null;
+	const address = "address" in server && typeof server.address === "string" ? server.address : "";
+	const host = address === "" || address === "0.0.0.0" ? "127.0.0.1" : address === "::" ? "::1" : address;
+	const domain = "domain" in server && typeof server.domain === "string" && server.domain !== "" ? server.domain : host.includes(":") ? `[${host}]` : host;
+	return {
+		host,
+		port: server.port,
+		hostHeader: `${domain}:${server.port}`
+	};
+}
+export { SHOT_REQUEST_TIMEOUT_MS, createShotClient, readShotTarget };

package/dist/nodefony/mcp/shutdown.js

@@ -0,0 +1,44 @@
+import { setTimeout } from "node:timers/promises";
+// nodefony/mcp/shutdown.ts
+/**
+* Délai maximal, en ms, pendant lequel l'arrêt du serveur attend que le
+* rapport parte : le superviseur de développement tue le process 4 s après
+* le lui avoir demandé.
+*/
+const SHUTDOWN_REPORT_MAX_MS = 1e3;
+/** Marge, en ms, laissée à la porte pour écrire le rapport une fois rendu. */
+const SHUTDOWN_REPORT_FLUSH_MS = 100;
+/**
+* Arme l'arrêt d'un outil long : l'agent qui abandonne, ou le serveur qui
+* s'arrête (rechargement après une modification de fichier). Dans le second
+* cas, l'arrêt attend — borné — que le rapport partiel soit parti.
+*
+* @param run - l'appel en cours, porteur du signal d'abandon de l'agent.
+* @param onShutdown - abonnement à l'arrêt du serveur ; absent hors application.
+* @returns le signal combiné, la cause, et la libération.
+*/
+function watchToolStop(run, onShutdown) {
+	const stop = new AbortController();
+	const signal = run === void 0 ? stop.signal : AbortSignal.any([run.signal, stop.signal]);
+	const delivered = Promise.withResolvers();
+	let interrupted = false;
+	const unsubscribe = onShutdown?.(async () => {
+		interrupted = true;
+		stop.abort();
+		await Promise.race([delivered.promise.then(() => setTimeout(SHUTDOWN_REPORT_FLUSH_MS, void 0, { ref: false })), setTimeout(SHUTDOWN_REPORT_MAX_MS, void 0, { ref: false })]);
+	}) ?? null;
+	let released = false;
+	return {
+		signal,
+		get interrupted() {
+			return interrupted;
+		},
+		release() {
+			if (released) return;
+			released = true;
+			delivered.resolve();
+			unsubscribe?.();
+		}
+	};
+}
+export { watchToolStop };