@duplojs/agents-kit 0.0.0-stage → 0.1.0-beta.3

package/skills/fundamental/references/results-and-errors.md

@@ -0,0 +1,59 @@
+# Résultats typés et exceptions
+
+## Choisir selon la place de l'échec dans le traitement
+
+Identifier les issues prévisibles que l'appelant doit pouvoir exploiter, puis les exprimer dans le contrat `Either`. Un refus peut concerner une règle métier, une vérification ou une manipulation technique. Une opération sur l'environnement ne justifie donc pas à elle seule une exception. Pour la distinction conceptuelle avec une défaillance de l'environnement, lire « Conversion des absences et exceptions en résultats » depuis le routeur du package installé.
+
+Lorsqu'une fonction renvoie un `Either` dans une branche, toutes ses branches renvoient un `Either` : `DEither.Right` pour la réussite et `DEither.Left` pour le refus. Envelopper aussi une réussite sans valeur avec `DEither.ok()`, plutôt que retourner `undefined` à côté d'un `Left`. L'information identifie le cas ; la valeur associée transporte les détails utiles. Voir [une fonction qui propage les échecs de lecture](examples/error-propagation.ts).
+
+Le `Left` de lecture reste visible dans le type de retour. Une autre fonction peut le propager, l'adapter ou tenter une récupération. Une absence de ressource exploitable par l'algorithme ne devient pas une panne d'environnement parce qu'elle provient d'une I/O. Ne pas la masquer par un `throw` ou un unwrap qui lève.
+
+`DEither.rightPipe` et `DEither.rightAsyncPipe` composent les étapes sur les valeurs de réussite et arrêtent au premier `Left`. `DEither.isRight` et `DEither.isLeft` permettent une discrimination explicite avant `unwrapRight` ou `unwrapLeft`.
+
+Pour une API qui lève sur un refus prévisible, adapter ses erreurs documentées en résultats. `DEither.safeCallback` et `DEither.asyncSafeCallback` capturent les exceptions ; examiner ensuite la cause pour distinguer le refus attendu d'une défaillance imprévue. Conserver une cause technique capturée dans le résultat jusqu'à sa consommation finale, sans la requalifier en refus métier ni la relancer depuis l'adaptation réutilisable. Préférer d'abord l'API DuploJS sûre si elle existe ; ne pas capturer systématiquement les exceptions des dépendances.
+
+## Le consommateur final décide de l'effet
+
+La frontière d'exécution consomme le résultat après le retour des fonctions appelées et décide de sa conséquence finale. C'est à ce stade que le code applicatif peut écrire un `throw` ou utiliser `OrThrow` pour interrompre l'exécution. Déclarer une fonction au niveau d'un module ou l'appeler depuis un point d'entrée ne lui donne pas cette responsabilité.
+
+Exemples : initialisation du programme, callback d'une commande ou handler d'une route.
+
+```text
+entrée externe
+  → validation par les schémas du module
+  → point d'entrée du traitement
+    → fonction applicative
+      → sous-fonction : renvoie les issues prévues en Right ou Left
+    ← résultat typé
+  ← résultat typé
+  → le point d'entrée décide de l'effet final
+```
+
+Les fonctions applicatives et leurs sous-fonctions renvoient les refus prévisibles dans leur contrat de retour, sans créer leurs propres `throw`. Les exceptions déjà émises par les dépendances ou le runtime remontent implicitement à travers ces appels ; cette propagation ne demande pas d'ajouter un `throw`.
+
+À cette frontière, interpréter le `Left` selon le contrat d'exécution : par exemple produire une réponse HTTP, un diagnostic de commande ou une exception adaptée. Le fait qu'un appelant ignore le retour d'une fonction ne suffit pas à autoriser cette fonction à lever une exception.
+
+## Choisir entre version sûre et `OrThrow`
+
+Préférer une déclaration sûre pour une valeur connue. Pour une opération qui peut échouer, examiner les branches que `OrThrow` convertirait en exceptions avant de choisir cette variante.
+
+| Situation | Choix |
+| --- | --- |
+| Constante dont la validité est prouvable | `cast`, `infer`, helper de déclaration ou surcharge littérale sûre |
+| Vérification d'une donnée externe ou valeur runtime sans preuve | Validation ou fabrique sûre, puis traitement du `Either` |
+| Refus prévisible d'une fonction réutilisable, métier ou technique | Renvoyer, propager ou adapter le `Left` |
+| Exception de défaillance imprévue émise par une dépendance ou le runtime | La laisser remonter implicitement ; propager le résultat si elle a été capturée |
+| Point d'entrée décidant de l'effet final d'un résultat | Interpréter le `Left`, puis produire la réponse, la fin d'exécution ou l'exception adaptée |
+| Test affirmant un résultat attendu | `OrThrow` permet de faire échouer le test si le résultat diffère |
+
+La commodité de l'extraction, la rareté supposée d'un refus ou la complexité de propagation ne changent pas sa nature. Une variante qui lève sur une absence exploitable ne convient pas à une fonction réutilisable qui doit transmettre ce cas.
+
+## Démarrage et tests : interpréter le résultat
+
+Au démarrage, l'initialisation peut décider qu'une configuration invalide empêche l'exécution. `environmentVariableOrThrow` valide d'abord par la version sûre, puis traduit son `Left` en exception. Cet usage exprime la décision finale du point d'entrée ; une fonction qui doit transmettre le refus utilise `environmentVariable`.
+
+Voir [la validation de l'environnement au démarrage](examples/environment-initialization.ts). Pour les entrées reçues pendant le fonctionnement du logiciel, conserver les résultats de validation jusqu'à leur interprétation par la frontière concernée.
+
+En tests, `OrThrow` peut extraire le résultat attendu ou préparer une fixture : une issue différente doit interrompre le test. Une déclaration sûre reste adaptée aux constantes connues, comme dans [les déclarations sûres](examples/safe-declarations.ts). Le code testé conserve ses résultats ; ces assertions ne justifient pas de le faire lever sur ses refus prévisibles.
+
+Pour approfondir, rechercher les `Either`, l'environnement ou le contexte d'exécution concerné dans `docs/concepts.llms.md`, depuis la racine AgentKit indiquée par les instructions du projet.

package/skills/http-client/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: duplojs-http-client
+description: "Appeler une API HTTP DuploJS ou externe avec le client typé de @duplojs/http/client : configurer son contrat, sélectionner les réponses, traiter les erreurs et consommer les flux."
+---
+
+# Client HTTP DuploJS
+
+## Trouver les concepts
+
+Appliquer la démarche du skill et lire les ressources indiquées lorsque leur condition est rencontrée. Pour rechercher un concept ou un mécanisme non couvert, consulter `docs/concepts.llms.md` du package `@duplojs/agents-kit`.
+
+Le setup indique ce chemin dans `AGENTS.md` ou `CLAUDE.md`, relativement à leur dossier. Les chemins `docs/` partent du package installé, même avec `--copy`. Les références du skill partent de son dossier ; les liens d'un document se résolvent depuis ce document.
+
+Si le chemin du routeur manque, le retrouver depuis le projet consommateur :
+
+```sh
+node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
+```
+
+## Retrouver le contrat et configurer le client
+
+Importer `@duplojs/http/client` sous le namespace `DHttpClient`. `createHttpClient<Routes>` reçoit le contrat des méthodes, chemins, entrées et réponses de l'API. Ce contrat peut être généré, écrit à la main ou composé ; le client fonctionne aussi avec un serveur externe à DuploJS.
+
+Retrouver les routes consommées et le client existant avant d'en créer un. Pour créer le client ou modifier son contrat et sa configuration, lire [Contrat et configuration](references/configuration.md). L'[exemple d'API externe](references/examples/external-client.ts) montre un contrat écrit à la main et la sélection par code.
+
+Le mode Predicted est actif par défaut : les attentes refusent une réponse sans header `predicted`, même si son code ou son information correspond. Pour un fournisseur sans ce marqueur, configurer **`disabledPredictedMode: true`**. Le contrat TypeScript et ce marqueur ne valident pas le body au runtime ; utiliser une data structure lorsque le traitement exige cette garantie.
+
+## Sélectionner la réponse et traiter le résultat
+
+Chaque appel produit une `PromiseRequest`, sur laquelle les réactions locales s'enregistrent avant la sélection. Une réponse **prévue** appartient au contrat de l'API ; la réponse **voulue** est celle que le traitement accepte à cet endroit. Un refus métier prévu peut donc être rejeté ici.
+
+1. Fournir les paramètres typés de l'appel et attacher les hooks ou intercepteurs locaux nécessaires.
+2. Sélectionner le cas voulu avec `iWantInformation`, ou `iWantCode` si l'API ne fournit pas d'information. Pour répartir explicitement toutes les variantes du contrat, utiliser un sélecteur exhaustif.
+3. Attendre le résultat sélectionné. Les attentes sûres renvoient un `Either` ; elles ne renvoient plus une `PromiseRequest` à configurer.
+4. Discriminer le résultat, puis utiliser la réponse voulue ou traiter et propager les autres branches. Une réponse rejetée porte `unexpect-response` ; une erreur de requête porte `request-error`.
+
+Pour écrire ou modifier une sélection, lire [Choisir et traiter les réponses](references/responses.md). L'[exemple de sélecteurs](references/examples/client-expectations.ts) distingue les résultats par information ou par code. Dans une fonction réutilisable qui transforme le résultat, conserver toutes les branches sous `Either`, y compris la nouvelle valeur de réussite.
+
+## Ajouter les comportements nécessaires
+
+| Condition rencontrée | Ressource à lire |
+| --- | --- |
+| Un comportement commun ou une réaction locale doit observer ou transformer l'échange | [Hooks et intercepteurs](references/hooks.md), avant de placer la réaction dans le cycle. |
+| La réponse contient des SSE ou des données à recevoir progressivement | [Consommation d'un flux](references/streams.md) et l'[exemple SSE et stream](references/examples/client-streams.ts), avant de lancer la lecture. |
+
+Enregistrer les callbacks d'un flux ne démarre pas sa consommation. Après sélection de la réponse, parcourir son itérateur asynchrone ou appeler la méthode de consommation adaptée ; prévoir sa fermeture selon le cycle attendu.
+
+## Vérifier l'intégration
+
+Exécuter le typage et les vérifications du projet. Vérifier la réponse voulue et les branches de refus ou d'erreur concernées par la modification, y compris l'absence de traitement dépendant après un échec. Contrôler les headers réels du fournisseur pour le mode Predicted et valider le body lorsque le contrat exige une garantie runtime. Pour un flux, vérifier aussi le démarrage de la consommation et sa fermeture.

package/skills/http-client/references/configuration.md

@@ -0,0 +1,9 @@
+# Contrat et configuration du client
+
+Le client HTTP est utilisable partout où une application effectue une requête HTTP, que l'API soit développée avec DuploJS ou avec une autre technologie. `createHttpClient<Routes>` accepte un type compatible avec `ServerRoute` : chaque route décrit sa méthode, son chemin, ses entrées et l'union de ses réponses. Les types peuvent être écrits à la main, importés ou composés. La génération depuis un serveur DuploJS est une façon de produire ce contrat ; elle ne génère pas un client et n'est pas un prérequis à son utilisation. Pour configurer cette génération, utiliser le skill `duplojs-http-server` ou rechercher le partage des contrats HTTP dans `docs/concepts.llms.md` du package installé.
+
+Décrire précisément les requêtes et les réponses connues, y compris les erreurs contractuelles. Éviter de perdre ces garanties avec un client non paramétré ou des assertions sur les résultats. Le typage décrit le contrat supposé de l'API ; il n'effectue pas de validation runtime du body. Utiliser une data structure lorsque cette validation est nécessaire.
+
+Créer un client par configuration d'API. Y placer l'URL de base, les options globales telles que `credentials` et `cache`, les headers par défaut et les hooks transversaux. Un header peut être calculé à chaque requête, par exemple pour récupérer le token courant. Les paramètres d'un appel peuvent préciser ses headers, ses options `initParams` et son `abortController`. Voir [un client pour une API externe](examples/external-client.ts), avec un contrat écrit à la main, sans header `information` ni `predicted`.
+
+Pour les exemples complémentaires de configuration et d’envoi de formulaires, rechercher le client HTTP dans `docs/concepts.llms.md` du package installé.

package/skills/http-client/references/examples/client-expectations.ts

@@ -0,0 +1,84 @@
+/**
+ * @title Choisir les réponses voulues depuis une PromiseRequest.
+ *
+ * Les sélecteurs imposent un choix pour chaque cas du contrat de la requête.
+ */
+import * as DHttpClient from "@duplojs/http/client";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+interface Routes {
+	method: "GET";
+	path: "/profile";
+	responses: {
+		code: "200";
+		information: "profile.found";
+		body: { name: string };
+	} | {
+		code: "401";
+		information: "auth.required";
+	};
+}
+
+const client = DHttpClient.createHttpClient<Routes>({
+	baseUrl: "https://duplo-api.example.com",
+	// Le mode Predicted reste actif pour cette API DuploJS.
+});
+
+export function requestProfile(onAuthenticationRequired: () => void) {
+	return client.get("/profile")
+		.addRequestInterceptor((params) => ({
+			...params,
+			headers: {
+				...params.headers,
+				"x-request-source": "profile-page",
+			},
+		}))
+		.whenInformation("auth.required", onAuthenticationRequired);
+}
+
+export async function selectProfile(onAuthenticationRequired: () => void) {
+	const result = await requestProfile(onAuthenticationRequired)
+		.toEitherByInformation({
+			"profile.found": true,
+			"auth.required": false,
+		});
+
+	if (DEither.hasInformation(result, "profile.found")) {
+		const response = DEither.unwrapRight(result);
+
+		type _CheckCode = DCommon.ExpectType<typeof response.code, "200", "strict">;
+		type _CheckBody = DCommon.ExpectType<typeof response.body, { name: string }, "strict">;
+
+		return DEither.success(response.body);
+	}
+
+	// Les autres branches portent unexpect-response ou request-error.
+	return result;
+}
+
+export async function classifyProfileByCode() {
+	const result = await client.get("/profile").toEitherByCode({
+		200: true,
+		401: true,
+	});
+
+	// Une erreur métier peut être un résultat voulu à cet endroit du programme.
+	if (DEither.hasInformation(result, "response-401")) {
+		const response = DEither.unwrapRight(result);
+
+		type _CheckInformation = DCommon.ExpectType<typeof response.information, "auth.required", "strict">;
+		void response;
+	}
+
+	return result;
+}
+
+// Illustration de compilation, sans créer de requête supplémentaire.
+export function checkSelectorContract(request: ReturnType<typeof client.get>) {
+	// @ts-expect-error Le sélecteur doit aussi décider du cas auth.required.
+	void request.toEitherByInformation({ "profile.found": true });
+
+	// @ts-expect-error Le sélecteur doit aussi décider du code 401.
+	void request.toEitherByCode({ 200: true });
+}

package/skills/http-client/references/examples/client-streams.ts

@@ -0,0 +1,74 @@
+/**
+ * @title Consommer des événements SSE et un stream typés.
+ *
+ * La sélection de la réponse précède la lecture progressive du flux.
+ */
+import * as DHttpClient from "@duplojs/http/client";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+type Routes = {
+	method: "GET";
+	path: "/events";
+	responses: {
+		code: "200";
+		information: "events.open";
+		events: {
+			progress: { percent: number };
+			finished: { id: string };
+		};
+	};
+} | {
+	method: "GET";
+	path: "/text-stream";
+	responses: {
+		code: "200";
+		information: "text.open";
+		flux: string;
+	};
+};
+
+const client = DHttpClient.createHttpClient<Routes>({
+	baseUrl: "https://duplo-api.example.com",
+});
+
+export async function consumeEvents(onProgress: (percent: number) => void) {
+	const result = await client.get("/events").iWantInformation("events.open");
+
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	const response = DEither.unwrapRight(result);
+	response.onReceiveEvent("progress", (event) => {
+		type _CheckData = DCommon.ExpectType<typeof event.data, { percent: number }, "strict">;
+
+		onProgress(event.data.percent);
+	});
+	response.onReceiveEvent("finished", (_event, stream) => {
+		stream.closeEventStream();
+	});
+
+	// Enregistrer les callbacks ne démarre pas la lecture.
+	await response.consumeEventStream();
+	return DEither.ok();
+}
+
+export async function consumeText(onChunk: (chunk: string) => void) {
+	// Cette réponse fournit predicted, x-duplojs-body-options: stream
+	// et un content-type text/plain, cohérents avec le contrat flux: string.
+	const result = await client.get("/text-stream").iWantInformation("text.open");
+
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	const response = DEither.unwrapRight(result);
+	for await (const chunk of response) {
+		type _CheckChunk = DCommon.ExpectType<typeof chunk, string, "strict">;
+
+		onChunk(chunk);
+	}
+
+	return DEither.ok();
+}

package/skills/http-client/references/examples/external-client.ts

@@ -0,0 +1,78 @@
+/**
+ * @title Typer une API externe sans génération DuploJS.
+ *
+ * Le contrat est écrit à la main ; les réponses n'ont aucun header DuploJS.
+ */
+import * as DHttpClient from "@duplojs/http/client";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+interface ExternalRoutes {
+	method: "GET";
+	path: "/users/{userId}";
+	params: {
+		userId: number;
+	};
+	responses: {
+		code: "200";
+		// Rendre l'absence explicite préserve l'inférence avec l'API actuelle.
+		information?: undefined;
+		body: {
+			id: number;
+			name: string;
+		};
+	} | {
+		code: "404";
+		information?: undefined;
+		body: {
+			message: string;
+		};
+	};
+}
+
+export const externalClient = DHttpClient.createHttpClient<ExternalRoutes>({
+	baseUrl: "https://api.example.com",
+	// L'API ne fournit pas le marqueur de réponses prévues.
+	disabledPredictedMode: true,
+});
+
+export function configureExternalClient(getToken: () => string) {
+	externalClient.addDefaultHeader("authorization", () => `Bearer ${getToken()}`);
+	// Transformer ici les options communes à tous les appels de cette API.
+	externalClient.addRequestHook((params) => ({
+		...params,
+		initParams: {
+			...params.initParams,
+			credentials: "omit",
+		},
+	}));
+}
+
+export async function readExternalUser(userId: number) {
+	const result = await externalClient
+		.get("/users/{userId}", { params: { userId } })
+		.whenCode("404", ({ body }) => {
+			type _CheckError = DCommon.ExpectType<typeof body, { message: string }, "strict">;
+			console.log(body.message);
+		})
+		.iWantCode("200");
+
+	if (DEither.isRight(result)) {
+		const response = DEither.unwrapRight(result);
+
+		type _CheckBody = DCommon.ExpectType<
+			typeof response.body,
+			{
+				id: number;
+				name: string;
+			},
+			"strict"
+		>;
+
+		return DEither.success(response.body);
+	}
+
+	// Le 404 et les autres réponses reçues restent accessibles via unexpect-response.
+	// Les erreurs de transport ou de traitement portent request-error.
+	return result;
+}

package/skills/http-client/references/hooks.md

@@ -0,0 +1,7 @@
+# Placer les hooks et intercepteurs
+
+Le client porte les comportements communs : `addRequestHook`, `addResponseHook`, `addErrorHook` et les hooks ciblant une information, un code ou une famille de réponses. Les hooks de requête et de réponse peuvent transformer leur entrée ; retourner la valeur destinée à la suite du cycle. Les réactions globales telles que les loaders ou la journalisation se placent à ce niveau.
+
+Chaque appel retourne une `PromiseRequest`, représentation de cet échange. Lui attacher immédiatement les traitements locaux avant `await` : les `when*` enregistrent des callbacks et renvoient la même `PromiseRequest`. Ils permettent de composer plusieurs réactions sans sélectionner ni extraire le résultat. `addRequestInterceptor` et `addResponseInterceptor` permettent les transformations locales. `whenError` traite une erreur de requête ; `whenNotPredictedResponse` observe une réponse sans marqueur lorsque le mode de réponses prévues est actif.
+
+Après les hooks locaux, choisir l’attente ou le sélecteur selon [le résultat voulu](responses.md). Pour ajouter un loader ou une instrumentation globale, lire `docs/concepts/03-client/10-http/30-hook.ts` depuis le package installé : cet exemple suit les effets communs pendant le cycle d'un échange.

package/skills/http-client/references/responses.md

@@ -0,0 +1,39 @@
+# Choisir et traiter les réponses
+
+## Attentes et sélecteurs
+
+Les méthodes d'attente transforment ensuite le résultat en une promesse de réponse ou d'`Either`. Choisir l'attente après les hooks locaux ; un appel à `iWant*` ne renvoie plus une `PromiseRequest`. Voir [les attentes et sélecteurs](examples/client-expectations.ts).
+
+| Besoin | Choix et résultat après `await` |
+| --- | --- |
+| Réagir à un cas sans modifier le résultat | `whenInformation`, `whenCode` ou une famille `when*` ; callback avec la réponse ciblée |
+| Exiger un cas précis | `iWantInformation` ou `iWantCode` ; `Right<"response", RéponseVoulue>` ou un `Left` |
+| À la consommation finale du résultat, obtenir la réponse ou interrompre l'exécution | Variante `OrThrow` ; réponse voulue ou exception. Dans une fonction réutilisable, conserver le `Either`. |
+| Répartir toutes les informations du contrat entre résultats voulus et non voulus | `iSelectExpectedResponseByInformation` ; sélecteur exhaustif `true` / `false`, résultat sous `Either` |
+| Discriminer les `Right` par l'information de la réponse | `toEitherByInformation` ; sélecteur exhaustif, `Right<Information, Réponse>` pour les entrées `true` |
+| Discriminer les `Right` par le code HTTP | `toEitherByCode` ; sélecteur exhaustif, `Right<"response-<code>", Réponse>` pour les entrées `true` |
+
+Les sélecteurs exigent une décision pour chaque information ou code déclaré dans les réponses de la requête. Une évolution du contrat impose ainsi de revoir ce choix. `false` conserve la réponse dans un `Left<"unexpect-response", ...>` ; les erreurs de requête restent des `Left<"request-error", ...>`. Les `Left` ne prennent pas le nom de l'information ou du code rejeté. Traiter ces branches avec les outils `Either` ; une réponse non voulue n'est pas supprimée silencieusement. Les variantes `OrThrow` lèvent une erreur pour ces branches, y compris les erreurs de requête.
+
+La famille `ExpectedResponse` sans sélecteur (`whenExpectedResponse`, `iWantExpectedResponse`) regroupe les codes `2xx` et `4xx`. Elle ne signifie pas « tous les codes déclarés dans le contrat » et ne remplace pas le choix des cas utiles à l'application. Pour un scénario précis, sélectionner l'information attendue, ou le code si l'API ne fournit pas d'information.
+
+## Réponses prévues et mode Predicted
+
+Une réponse **prévue** appartient aux réponses contractuelles de l'API. Elle peut être un succès ou une erreur métier, par exemple un `404` déclaré. Une réponse **voulue** est celle que le consommateur décide d'accepter à cet endroit du programme. Une réponse prévue peut donc être rejetée par un sélecteur.
+
+DuploJS marque ses réponses contractuelles : les réponses `PredictedResponse` et leurs équivalents SSE et stream conduisent le serveur à ajouter le header `predicted`. Cette classe marque la réponse ; elle n'ajoute pas de traitement métier. Une erreur de parsing du body ou une erreur interne hors contrat peut produire une réponse imprévue. Son code ou son information peut coïncider avec celui d'une réponse déclarée, sans garantir le même body.
+
+Par défaut, `disabledPredictedMode` vaut `false`. Le client vérifie la **présence** du header indiqué par `predictedHeaderKey` (`predicted` par défaut). Sans ce header, les hooks ciblés par information, code ou famille ne s'exécutent pas et les attentes et sélecteurs renvoient `Left<"unexpect-response", ...>`, même si le code ou l'information correspond. Cela évite d'utiliser sous un type contractuel le contenu d'une autre réponse. Les hooks généraux de réponse et le hook dédié aux réponses imprévues restent disponibles.
+
+Cette règle concerne les attentes : un `await` direct sur la `PromiseRequest`, sans sélection, conserve une réponse HTTP reçue dans un `Right<"response", ...>`, y compris sans marqueur. Utiliser une attente pour obtenir la réponse correspondant au besoin ; ne pas confondre réception d'une réponse et acceptation de son contrat.
+
+## Adapter le client au protocole du fournisseur
+
+Pour une API **sans ce marqueur**, créer son client avec `disabledPredictedMode: true`. Les attentes se fondent alors sur le code ou l'information sans imposer le header. Sans information de réponse, sélectionner par code. Si seuls les noms des headers diffèrent, configurer `predictedHeaderKey` et `informationHeaderKey` selon le protocole de l'API. Conserver le mode actif pour une API DuploJS qui fournit le marqueur.
+
+Le marqueur est une convention du protocole, pas une validation du contenu ni une preuve d'authenticité. Le body reste à valider lorsque le traitement exige une garantie runtime.
+
+## Particularité d'inférence d'un contrat sans information
+
+Avec l'API actuelle, un contrat de réponses sans header d'information doit déclarer explicitement `information?: undefined` dans chaque réponse pour conserver leur inférence. L'[exemple d'API externe](examples/external-client.ts) applique cette forme et sélectionne par code. Cette déclaration répond au typage de l'API cliente ; elle n'ajoute aucun header au protocole.
+

package/skills/http-client/references/streams.md

@@ -0,0 +1,10 @@
+# Consommer progressivement un flux
+
+Décrire les événements SSE avec `responses.events` et les données d'un stream avec `responses.flux`. Après sélection de la réponse, consommer l'itérateur asynchrone pour traiter les éléments au fur et à mesure, ou enregistrer les callbacks puis lancer la consommation. Voir [SSE et stream](examples/client-streams.ts).
+
+- **SSE** : `onReceiveEvent` cible un événement typé, `onStreamEvent` observe le cycle, `consumeEventStream` lance la lecture et `closeEventStream` ferme le flux. La réponse est reconnue par le content-type `text/event-stream`.
+- **Stream** : `onStream` observe notamment `receiveData`, `consumeStream` lance la lecture et `closeStream` ferme le flux. Cette couche est activée par le header `x-duplojs-body-options` contenant `stream` ; les chunks sont décodés en texte si le content-type contient `text`, sinon ils restent des `Uint8Array`. Les chunks ne sont pas nécessairement des messages applicatifs complets : gérer le découpage si le protocole l'exige.
+
+`whenReceiveServerEvent` et `whenReceiveDataStream` permettent aussi d'attacher les callbacks depuis la `PromiseRequest` ; ils ne lancent pas à eux seuls la consommation. Les hooks globaux du client peuvent instrumenter le démarrage, la réception, les erreurs et la fermeture. Le mode de réponses prévues s'applique également à ces réponses : le désactiver pour un fournisseur sans marqueur. Le typage seul ne transforme pas un flux arbitraire en SSE ou en stream reconnu par cette couche ; vérifier les headers et le format de l'API.
+
+Pour choisir la réponse avant sa consommation, consulter [les attentes et le mode Predicted](responses.md).

package/skills/http-server/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: duplojs-http-server
+description: "Créer ou modifier des routes et un serveur HTTP DuploJS : Hub, entrées validées, réponses contractuelles, traitements réutilisables et génération des contrats partagés."
+---
+
+# Serveur HTTP DuploJS
+
+## Trouver les concepts
+
+Appliquer la démarche du skill et lire les ressources indiquées lorsque leur condition est rencontrée. Pour rechercher un concept ou un mécanisme non couvert, consulter `docs/concepts.llms.md` du package `@duplojs/agents-kit`.
+
+Le setup indique ce chemin dans `AGENTS.md` ou `CLAUDE.md`, relativement à leur dossier. Les chemins `docs/` partent du package installé, même avec `--copy`. Les références du skill partent de son dossier ; les liens d'un document se résolvent depuis ce document.
+
+Si le chemin du routeur manque, le retrouver depuis le projet consommateur :
+
+```sh
+node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
+```
+
+## Construire le flux d'une route
+
+Partir de la route concernée, de ses entrées et de ses réponses attendues. Reprendre le builder de sa famille dans le projet : il peut déjà porter des préconditions communes. Pour une route sans politique commune, utiliser `useRouteBuilder`.
+
+Une route enchaîne des étapes qui enrichissent un contexte typé, le **floor**. Chaque étape reçoit les données garanties par les précédentes. Une réponse termine le flux ; dans un `cut`, `output(...)` enrichit le floor et permet de continuer.
+
+1. Déclarer les entrées avec `.extract` et les data structures du contrat. L'extraction les valide avant de poursuivre.
+2. Préparer les préconditions et traiter les refus dans les étapes précédant le handler. Un `.cut` convient à une adaptation propre au scénario courant ; reprendre les traitements réutilisables existants lorsqu'ils portent la même responsabilité.
+3. Déclarer chaque réponse avec un `ResponseContract` : statut, `information` discriminante et schéma du body éventuel.
+4. Terminer le chemin de réussite avec `.handler` et son outil `response`.
+
+Pour créer une route ou modifier ses extractions et étapes, lire [Routes et floor](references/routes-and-floor.md). La [route minimale](references/examples/minimal-route.ts) montre validation et réponse sans dépendance applicative ; la [route de modification](references/examples/rename-user-route.ts) adapte un résultat applicatif en amont du handler.
+
+## Raccorder l'application
+
+La route est un point d'entrée d'infrastructure : elle adapte les données validées aux capacités de l'application, appelle les traitements prévus et traduit leurs résultats vers HTTP. Elle peut établir une précondition avec une qualification du domaine. L'orchestration métier et les transitions restent dans leurs couches ; ne pas les réimplémenter dans les steps.
+
+Traiter les résultats attendus avec les outils `Either` et les réponses contractuelles. Les fonctions réutilisables conservent leurs échecs typés ; une réponse HTTP relève du flux HTTP qui les consomme.
+
+Si la tâche raccorde un domaine existant ou modifie une responsabilité métier, appliquer le skill `duplojs-modeling` lorsqu'il est installé, ou lire `docs/concepts/05-type-driven-design/01-architecture/10-boundaries.md`.
+
+## Réutiliser au niveau approprié
+
+| Ce qui doit être réutilisé | Mécanisme |
+| --- | --- |
+| Une opération avec plusieurs résultats, interprétés différemment selon la route | Checker créé par `useCheckerBuilder`, appelé avec `.check`. |
+| La sélection d'un résultat de checker et sa réponse HTTP d'échec | Preset créé par `createPresetChecker`, appelé avec `.presetCheck`. |
+| Une séquence d'étapes et les données qu'elle garantit | Process créé par `useProcessBuilder`, appelé avec `.exec`. |
+| Des processus appliqués avant chaque route d'une famille | `usePreflightBuilder`, puis sa fonction `useRouteBuilder`. |
+
+Quand l'un de ces besoins apparaît, lire [Checkers, processus et builders communs](references/reusable-flows.md) avant de l'assembler. Éviter de recopier des `cut` portant la même opération et la même réponse. L'[exemple de preflight](references/examples/authentication.ts) et la [route protégée](references/examples/protected-route.ts) montrent comment transmettre les garanties d'une séquence commune.
+
+## Assembler et démarrer le serveur
+
+Le `Hub` rassemble les routes, les plugins et leur cycle de vie indépendamment du runtime. Créer le Hub avec `createHub`, ajouter les plugins avec `.plug` et les routes avec `.register`, puis appeler le connecteur de l'environnement. Sur Node, utiliser `createHttpServer` depuis `@duplojs/http/node`.
+
+Au démarrage, valider la configuration avec `DSCommon.environmentVariableOrThrow` depuis `@duplojs/server/common`, puis fournir les valeurs au Hub et au connecteur. Pour les sources d'environnement et les interactions système, consulter `duplojs-server` ou les concepts serveur du routeur.
+
+Si la tâche touche le démarrage ou l'enregistrement des routes, lire [Initialisation et enregistrement](references/initialization.md) et l'[exemple minimal](references/examples/initialize.ts). Avec `routeStore.getAll()`, importer d'abord les modules de routes : le store collecte les déclarations finalisées par `.handler`, sans découvrir ni importer leurs fichiers.
+
+## Partager les contrats et les schémas
+
+Lorsque la tâche partage des types de routes ou des schémas, lire [Génération et consommation des contrats](references/code-generation.md) et l'[exemple de génération](references/examples/generate-sdk.ts). `codeGeneratorPlugin` produit ces ressources à partir des contrats du serveur ; il ne crée pas d'instance de client. Sa configuration seule ne lance pas la génération : celle-ci dépend du cycle de vie du Hub. Pour consommer l'API, utiliser le skill `duplojs-http-client` ou les concepts du client HTTP.
+
+## Vérifier le flux exposé
+
+Exécuter le typage et les vérifications du projet. Vérifier que la route est effectivement enregistrée, qu'une entrée invalide est refusée et que chaque issue concernée produit le statut, l'information et le body déclarés. Vérifier aussi qu'un refus arrête les étapes dépendantes. Si la tâche touche la génération, exécuter celle-ci en `BUILD` puis vérifier les fichiers produits et leur utilisation depuis le consommateur.

package/skills/http-server/references/code-generation.md

@@ -0,0 +1,31 @@
+# Générer et consommer les contrats
+
+## Une source de vérité dans les routes
+
+Le plugin `codeGeneratorPlugin`, importé depuis `@duplojs/http/codeGenerator`, produit le contrat TypeScript des routes enregistrées sur le Hub. Les entrées et les réponses déclarées dans les étapes alimentent ce contrat ; maintenir aussi les contrats des échecs prévus.
+
+`outputFile` choisit le fichier de types généré. `generateStructure.outputFolder` active aussi la génération de data structures réutilisables au runtime. Voir [la génération pour un SDK](examples/generate-sdk.ts).
+
+Les types permettent de construire un client déjà informé des méthodes, chemins, paramètres et réponses. Les structures permettent de partager les mêmes schémas de validation avec un consommateur, par exemple dans un SDK utilisé par une autre application.
+
+## Identifier les structures à partager
+
+Donner un identifiant stable aux structures exportables avec `.addIdentifier(...)`, qui retourne une copie nommée. Cette méthode est ajoutée par l'extension `@duplojs/tools/toTypescript` : importer explicitement cette extension dans le module qui appelle la méthode. Les [contrats ordinaires](examples/contracts.ts) restent utilisables sans cette extension ; le [point d'entrée de génération](examples/generate-sdk.ts) crée leurs copies nommées pour le SDK.
+
+L'exemple fournit ces copies avec `generateStructure.structures` et active `generateStructure.disabledFromRoute` pour limiter la génération à cette sélection. Pour une découverte depuis les routes, conserver cette option désactivée et employer les structures identifiées dans les contrats des routes ; le générateur parcourt aussi leurs sous-structures. Ne pas supposer qu'un schéma anonyme produira un export nommé. Vérifier les capacités de génération des structures et contraintes personnalisées dans la documentation des outils.
+
+Réserver le dossier de sortie aux fichiers générés : le plugin remplace ce dossier pendant la génération. Garder les sources écrites à la main ailleurs.
+
+## Déclencher la génération
+
+Importer les modules de routes, enregistrer les routes et brancher le plugin avant de démarrer le cycle avec le connecteur. Le plugin travaille sur le hook `beforeStartServer`, dans les environnements `DEV` et `BUILD` ; créer le Hub et le plugin sans appeler le connecteur ne suffit pas.
+
+Pour un script de génération, utiliser `BUILD`. L'[exemple Node](examples/generate-sdk.ts) appelle `createHttpServer` dans ce mode : le cycle et la génération s'exécutent sans ouvrir l'écoute HTTP. Le Hub doit contenir des routes pour que le plugin produise les fichiers attendus.
+
+Les routes de cet exemple déclarent certaines capacités avec `declare function` : elles démontrent leurs contrats sans fournir d'implémentation applicative. La génération n'exécute pas leurs handlers. Pour servir ces routes, raccorder les capacités réelles ; pour démarrer un exemple autonome, utiliser [l'initialisation minimale](examples/initialize.ts).
+
+## Distribuer et utiliser le résultat
+
+Publier les types et structures générés dans le package consommateur ou le SDK selon son organisation. Importer le type généré `Routes` pour paramétrer `createHttpClient` depuis `@duplojs/http/client`, et importer les structures générées lorsque le consommateur doit valider des données. Garder ces ressources issues de la génération, sans recopier à la main les contrats du serveur.
+
+Pour le raccordement concret du client, ses sélecteurs et les API sans contrats générés, utiliser le skill `duplojs-http-client` ou rechercher le client HTTP dans `docs/concepts.llms.md` du package installé. Pour les options de génération, rechercher le partage des contrats HTTP et les outils de transformation des data structures dans `docs/concepts.llms.md`.

package/skills/http-server/references/examples/authentication.ts

@@ -0,0 +1,42 @@
+/**
+ * @title Équiper une famille de routes d'un processus commun.
+ *
+ * Le preflight exporte une fonction qui crée des routes avec authentification.
+ */
+import { ResponseContract, useCheckerBuilder, usePreflightBuilder, useProcessBuilder } from "@duplojs/http";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import { type User } from "./contracts";
+
+// La politique de vérification est fournie par l'application.
+declare function authenticateToken(token: string): Promise<DEither.Success<User> | DEither.Fail>;
+
+const tokenChecker = useCheckerBuilder()
+	.handler(async(token: string, { output }) => {
+		const result = await authenticateToken(token);
+
+		return DEither.whenIsRightOtherwise(
+			result,
+			(user) => output("token.valid", user),
+			() => output("token.invalid", null),
+		);
+	});
+
+export const authenticationProcess = useProcessBuilder()
+	.extract({
+		headers: {
+			authorization: DDataStructure.string(),
+		},
+	})
+	.check(tokenChecker, {
+		input: ({ authorization }) => authorization,
+		result: "token.valid",
+		otherwise: ResponseContract.unauthorized("authentication.invalid"),
+		indexing: "user",
+	})
+	// authorization reste interne au process ; seul user est exposé.
+	.exports(["user"]);
+
+export const useAuthenticatedRouteBuilder = usePreflightBuilder()
+	.exec(authenticationProcess, { imports: ["user"] })
+	.useRouteBuilder;

package/skills/http-server/references/examples/contracts.ts

@@ -0,0 +1,19 @@
+/**
+ * @title Définir les contrats partagés des exemples HTTP.
+ *
+ * Les routes partagent leurs schémas sans dépendre d'une génération de SDK.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+export const userStructure = DDataStructure.object({
+	id: DDataStructure.string([DDataStructure.uuid()]),
+	name: DDataStructure.string([DDataStructure.minCharacters(3)]),
+});
+
+export type User = DDataStructure.StructureValue<typeof userStructure>;
+
+export const renameUserBody = DDataStructure.object({
+	name: DDataStructure.string([DDataStructure.minCharacters(3)]),
+});
+
+export type RenameUserBody = DDataStructure.StructureValue<typeof renameUserBody>;

package/skills/http-server/references/examples/generate-sdk.ts

@@ -0,0 +1,36 @@
+/**
+ * @title Générer les contrats et les schémas d'un SDK.
+ *
+ * Déclencher le cycle du Hub en BUILD pour générer sans écoute HTTP.
+ */
+import "@duplojs/tools/toTypescript";
+import "./user-route";
+import "./rename-user-route";
+import { createHub, routeStore } from "@duplojs/http";
+import { createHttpServer } from "@duplojs/http/node";
+import { codeGeneratorPlugin } from "@duplojs/http/codeGenerator";
+import * as DPath from "@duplojs/lang/path";
+import { renameUserBody, userStructure } from "./contracts";
+
+// Les dossiers parents de sortie sont préparés par le projet.
+const hub = createHub({ environment: "BUILD" })
+	.register(routeStore.getAll())
+	.plug(codeGeneratorPlugin({
+		outputFile: DPath.declarePath("sdk/routes.d.ts"),
+		generateStructure: {
+			// Ce dossier contient exclusivement les sources générées.
+			outputFolder: DPath.declarePath("sdk/dataStructures"),
+			// L'extension est chargée dans ce module, avant ces appels.
+			// Les copies nommées ne modifient pas les schémas des routes.
+			structures: [
+				userStructure.addIdentifier("User"),
+				renameUserBody.addIdentifier("RenameUserBody"),
+			],
+			disabledFromRoute: true,
+		},
+	}));
+
+await createHttpServer(hub, {
+	host: "localhost",
+	port: 1506,
+});