@duplojs/agents-kit 0.1.0-beta.3 → 0.1.0-beta.7

package/instructions/coding-conventions.md

@@ -1,8 +1,8 @@
 ## Développement avec DuploJS
 
-- Réutiliser les fonctions DuploJS avant d’écrire un utilitaire ou d’utiliser une API native ou tierce équivalente.
+- Avant d’écrire un utilitaire ou d’utiliser une API native ou tierce, rechercher la fonction adaptée à la manipulation souhaitée dans le [routeur API]({{packagePath}}/docs/API.llms.md). Suivre les liens vers le domaine puis la référence pertinente, et utiliser l’équivalent DuploJS dès qu’il existe.
 - Pour une recherche de concept ou un problème de composition, de typage ou d’erreur, consulter le [routeur des concepts]({{packagePath}}/docs/concepts.llms.md), puis uniquement les pages et exemples pertinents.
 - Appliquer les contrats et patterns documentés, notamment pour les contraintes et les résultats `Either`. Ne pas inventer d’API ni contourner le typage pour résoudre un doute.
 - Utiliser les skills DuploJS installés pour les procédures spécialisées liées à la tâche.
 
-Le chemin du routeur est relatif au dossier de ce fichier ; résoudre ensuite chaque lien depuis le document qui le contient.
+Les chemins des routeurs sont relatifs au dossier de ce fichier ; résoudre ensuite chaque lien depuis le document qui le contient.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duplojs/agents-kit",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.7",
   "license": "MIT",
   "author": {
     "name": "DuploJS",
@@ -32,19 +32,19 @@
     "./docs/API/*/index.llms.md": "./docs/API/*/index.llms.md"
   },
   "dependencies": {
-    "@duplojs/lang": "0.1.0-beta.3",
-    "@duplojs/server": "0.1.0-beta.3"
+    "@duplojs/lang": "0.1.0-beta.7",
+    "@duplojs/server": "0.1.0-beta.7"
   },
   "peerDependencies": {
-    "@duplojs/code-config": "0.1.0-beta.3",
-    "@duplojs/eslint": "0.1.0-beta.3",
-    "@duplojs/form": "0.1.0-beta.3",
-    "@duplojs/http": "0.1.0-beta.3",
-    "@duplojs/json-web-token": "0.1.0-beta.3",
-    "@duplojs/lang": "0.1.0-beta.3",
-    "@duplojs/playwright": "0.1.0-beta.3",
-    "@duplojs/server": "0.1.0-beta.3",
-    "@duplojs/tools": "0.1.0-beta.3"
+    "@duplojs/code-config": "0.1.0-beta.7",
+    "@duplojs/eslint": "0.1.0-beta.7",
+    "@duplojs/form": "0.1.0-beta.7",
+    "@duplojs/http": "0.1.0-beta.7",
+    "@duplojs/json-web-token": "0.1.0-beta.7",
+    "@duplojs/lang": "0.1.0-beta.7",
+    "@duplojs/playwright": "0.1.0-beta.7",
+    "@duplojs/server": "0.1.0-beta.7",
+    "@duplojs/tools": "0.1.0-beta.7"
   },
   "peerDependenciesMeta": {
     "@duplojs/code-config": {
@@ -70,9 +70,12 @@
     }
   },
   "devDependencies": {
-    "@duplojs/code-config": "0.1.0-beta.3",
+    "@duplojs/code-config": "0.1.0-beta.7",
+    "@duplojs/eslint": "0.1.0-beta.7",
     "@types/node": "24.13.3",
-    "@types/web": "0.0.358"
+    "@types/web": "0.0.358",
+    "vue": "3.5.43",
+    "vue-tsc": "3.3.11"
   },
   "files": [
     "dist",

package/skills/http-client/SKILL.md

@@ -19,7 +19,7 @@ node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.l
 
 ## 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.
+Importer les symboles nommés depuis `@duplojs/http/client`. `createHttpClient<Routes>` utilise le type des routes pour vérifier les requêtes et les réponses attendues. Le client peut appeler une API DuploJS ou un serveur externe.
 
 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.
 

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

@@ -1,6 +1,8 @@
 # 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é.
+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.
+
+Pour une API DuploJS, utiliser `RouteDeclarationToContract` depuis `@duplojs/http` avec le type d'une route (`typeof route`) ou une union de types de routes. Il reprend leurs entrées et leurs réponses, y compris les refus des étapes de vérification. Importer les routes avec `import type` pour éviter de charger les modules serveur dans le client. Voir `docs/concepts/03-client/10-http/10-init.ts` depuis le 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.
 

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

@@ -3,24 +3,25 @@
  *
  * Les sélecteurs imposent un choix pour chaque cas du contrat de la requête.
  */
-import * as DHttpClient from "@duplojs/http/client";
+import { createHttpClient } 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 };
+	readonly method: "GET";
+	readonly path: "/profile";
+	readonly responses: {
+		readonly code: "200";
+		readonly information: "profile.found";
+		readonly body: { name: string };
 	} | {
-		code: "401";
-		information: "auth.required";
+		readonly code: "401";
+		readonly information: "auth.required";
+		readonly body: undefined;
 	};
 }
 
-const client = DHttpClient.createHttpClient<Routes>({
+const client = createHttpClient<Routes>({
 	baseUrl: "https://duplo-api.example.com",
 	// Le mode Predicted reste actif pour cette API DuploJS.
 });

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

@@ -3,7 +3,7 @@
  *
  * La sélection de la réponse précède la lecture progressive du flux.
  */
-import * as DHttpClient from "@duplojs/http/client";
+import { createHttpClient } from "@duplojs/http/client";
 import * as DEither from "@duplojs/lang/either";
 import type * as DCommon from "@duplojs/lang/common";
 
@@ -28,7 +28,7 @@ type Routes = {
 	};
 };
 
-const client = DHttpClient.createHttpClient<Routes>({
+const client = createHttpClient<Routes>({
 	baseUrl: "https://duplo-api.example.com",
 });
 

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

@@ -3,7 +3,7 @@
  *
  * Le contrat est écrit à la main ; les réponses n'ont aucun header DuploJS.
  */
-import * as DHttpClient from "@duplojs/http/client";
+import { createHttpClient } from "@duplojs/http/client";
 import * as DEither from "@duplojs/lang/either";
 import type * as DCommon from "@duplojs/lang/common";
 
@@ -30,7 +30,7 @@ interface ExternalRoutes {
 	};
 }
 
-export const externalClient = DHttpClient.createHttpClient<ExternalRoutes>({
+export const externalClient = createHttpClient<ExternalRoutes>({
 	baseUrl: "https://api.example.com",
 	// L'API ne fournit pas le marqueur de réponses prévues.
 	disabledPredictedMode: true,

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

@@ -21,7 +21,7 @@ La famille `ExpectedResponse` sans sélecteur (`whenExpectedResponse`, `iWantExp
 
 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.
+Le serveur DuploJS ajoute le header `predicted` aux `PredictedResponse` et à leurs équivalents SSE et stream. Ce marqueur permet au client de reconnaître les réponses prévues par l'API. Une erreur de parsing du body ou une erreur interne peut produire une réponse imprévue. Son code ou son information peut coïncider avec celui d'une réponse prévue, 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.
 

package/skills/http-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+description: "Créer ou modifier une API HTTP DuploJS : routes, validation des requêtes, vérifications réutilisables et configuration du serveur."
 ---
 
 # Serveur HTTP DuploJS
@@ -25,8 +25,7 @@ Une route enchaîne des étapes qui enrichissent un contexte typé, le **floor**
 
 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`.
+3. Terminer avec `.handler`. Son callback retourne la réponse HTTP avec l'outil `response` disponible dans son second argument.
 
 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.
 
@@ -34,7 +33,7 @@ Pour créer une route ou modifier ses extractions et étapes, lire [Routes et fl
 
 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.
+Traduire les résultats attendus en réponses HTTP avec les outils `Either`. Les fonctions réutilisables conservent leurs échecs typés ; la route choisit la réponse à envoyer au client.
 
 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`.
 
@@ -57,10 +56,6 @@ Au démarrage, valider la configuration avec `DSCommon.environmentVariableOrThro
 
 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.
+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 attendus. Vérifier aussi qu'un refus arrête les étapes dépendantes.

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

@@ -3,7 +3,7 @@
  *
  * Le preflight exporte une fonction qui crée des routes avec authentification.
  */
-import { ResponseContract, useCheckerBuilder, usePreflightBuilder, useProcessBuilder } from "@duplojs/http";
+import { 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";
@@ -31,7 +31,7 @@ export const authenticationProcess = useProcessBuilder()
 	.check(tokenChecker, {
 		input: ({ authorization }) => authorization,
 		result: "token.valid",
-		otherwise: ResponseContract.unauthorized("authentication.invalid"),
+		otherwise: ({ response }) => response.unauthorized("authentication.invalid"),
 		indexing: "user",
 	})
 	// authorization reste interne au process ; seul user est exposé.

package/skills/http-server/references/examples/inferred-client.ts

@@ -0,0 +1,54 @@
+/**
+ * @title Partager les types d'une route avec un client HTTP.
+ *
+ * Créer un client dont les requêtes et les réponses suivent la définition des routes serveur.
+ */
+import { type RouteDeclarationToContract } from "@duplojs/http";
+import { createHttpClient } from "@duplojs/http/client";
+import type * as DCommon from "@duplojs/lang/common";
+import { type renameUserRoute } from "./rename-user-route";
+import { type RenameUserBody, type User } from "./contracts";
+
+// Ces imports de type n'exécutent pas les modules du serveur.
+type Routes = RouteDeclarationToContract<typeof renameUserRoute>;
+
+type _CheckResponses = DCommon.ExpectType<
+	Routes["responses"],
+	| {
+		readonly code: "422";
+		readonly information: "extract-error";
+		readonly body: string;
+	}
+	| {
+		readonly code: "404";
+		readonly information: "user.notFound";
+		readonly body: undefined;
+	}
+	| {
+		readonly code: "409";
+		readonly information: "user.renameDenied";
+		readonly body: undefined;
+	}
+	| {
+		readonly code: "200";
+		readonly information: "user.renamed";
+		readonly body: User;
+	},
+	"strict"
+>;
+
+const client = createHttpClient<Routes>({
+	baseUrl: "https://duplo-api.example.com",
+});
+
+export function renameUserRemotely(userId: User["id"], body: RenameUserBody) {
+	return client.patch("/users/{userId}", {
+		params: { userId },
+		body,
+	}).toEitherByInformation({
+		"extract-error": false,
+		"user.notFound": false,
+		"user.renameDenied": false,
+		"user.renamed": true,
+	});
+}

package/skills/http-server/references/examples/minimal-route.ts

@@ -3,7 +3,7 @@
  *
  * Cette route autonome sert au démarrage minimal du serveur.
  */
-import { ResponseContract, useRouteBuilder } from "@duplojs/http";
+import { useRouteBuilder } from "@duplojs/http";
 import * as DDataStructure from "@duplojs/lang/dataStructure";
 
 export const helloRoute = useRouteBuilder("GET", "/hello")
@@ -13,6 +13,5 @@ export const helloRoute = useRouteBuilder("GET", "/hello")
 		},
 	})
 	.handler(
-		ResponseContract.ok("hello.received", DDataStructure.string()),
-		({ name }, { response }) => response("hello.received", name),
+		({ name }, { response }) => response.ok("hello.received", name),
 	);

package/skills/http-server/references/examples/protected-route.ts

@@ -3,14 +3,13 @@
  *
  * Comparer son application commune par preflight et son exécution locale.
  */
-import { ResponseContract, useRouteBuilder } from "@duplojs/http";
+import { useRouteBuilder } from "@duplojs/http";
 import type * as DCommon from "@duplojs/lang/common";
 import { authenticationProcess, useAuthenticatedRouteBuilder } from "./authentication";
-import { userStructure, type User } from "./contracts";
+import { type User } from "./contracts";
 
 export const profileRoute = useAuthenticatedRouteBuilder("GET", "/profile")
 	.handler(
-		ResponseContract.ok("profile.read", userStructure),
 		(floor, { response }) => {
 			type _CheckFloor = DCommon.ExpectType<
 				typeof floor,
@@ -18,7 +17,7 @@ export const profileRoute = useAuthenticatedRouteBuilder("GET", "/profile")
 				"strict"
 			>;
 
-			return response("profile.read", floor.user);
+			return response.ok("profile.read", floor.user);
 		},
 	);
 
@@ -26,6 +25,5 @@ export const profileRoute = useAuthenticatedRouteBuilder("GET", "/profile")
 export const explicitAuthenticationRoute = useRouteBuilder("GET", "/session")
 	.exec(authenticationProcess, { imports: ["user"] })
 	.handler(
-		ResponseContract.ok("session.read", userStructure),
-		({ user }, { response }) => response("session.read", user),
+		({ user }, { response }) => response.ok("session.read", user),
 	);

package/skills/http-server/references/examples/rename-user-route.ts

@@ -3,11 +3,11 @@
  *
  * Un preset résout la ressource ; un cut traite l'issue propre à la modification.
  */
-import { ResponseContract, useRouteBuilder } from "@duplojs/http";
+import { useRouteBuilder } from "@duplojs/http";
 import * as DDataStructure from "@duplojs/lang/dataStructure";
 import * as DEither from "@duplojs/lang/either";
 import type * as DCommon from "@duplojs/lang/common";
-import { renameUserBody, userStructure, type RenameUserBody, type User } from "./contracts";
+import { renameUserBody, type RenameUserBody, type User } from "./contracts";
 import { iWantUserExist } from "./user-checker";
 
 // Use case résolu dans l'infrastructure ; il porte la règle de modification.
@@ -25,18 +25,16 @@ export const renameUserRoute = useRouteBuilder("PATCH", "/users/{userId}")
 	})
 	.presetCheck(iWantUserExist.indexing("user"), ({ userId }) => userId)
 	.cut(
-		ResponseContract.conflict("user.renameDenied"),
 		async({ user, body }, { response, output }) => {
 			const result = await renameUser(user, body);
 
 			return DEither.matchInformation(result, {
 				"user-renamed": (updatedUser) => output({ updatedUser }),
-				"rename-denied": () => response("user.renameDenied"),
+				"rename-denied": () => response.conflict("user.renameDenied"),
 			});
 		},
 	)
 	.handler(
-		ResponseContract.ok("user.renamed", userStructure),
 		(floor, { response }) => {
 			type _CheckFloor = DCommon.ExpectType<
 				typeof floor,
@@ -49,6 +47,6 @@ export const renameUserRoute = useRouteBuilder("PATCH", "/users/{userId}")
 				"strict"
 			>;
 
-			return response("user.renamed", floor.updatedUser);
+			return response.ok("user.renamed", floor.updatedUser);
 		},
 	);

package/skills/http-server/references/examples/user-checker.ts

@@ -3,7 +3,7 @@
  *
  * Un preset fixe le résultat attendu et la réponse d'absence du checker.
  */
-import { createPresetChecker, ResponseContract, useCheckerBuilder } from "@duplojs/http";
+import { createPresetChecker, useCheckerBuilder } from "@duplojs/http";
 import * as DEither from "@duplojs/lang/either";
 import { type User } from "./contracts";
 
@@ -22,5 +22,5 @@ export const userExist = useCheckerBuilder()
 
 export const iWantUserExist = createPresetChecker(userExist, {
 	result: "user.found",
-	otherwise: ResponseContract.notFound("user.notFound"),
+	otherwise: ({ response }) => response.notFound("user.notFound"),
 });

package/skills/http-server/references/examples/user-route.ts

@@ -3,10 +3,10 @@
  *
  * L'extraction et l'indexation du résultat enrichissent le floor du handler.
  */
-import { ResponseContract, useRouteBuilder } from "@duplojs/http";
+import { useRouteBuilder } from "@duplojs/http";
 import * as DDataStructure from "@duplojs/lang/dataStructure";
 import type * as DCommon from "@duplojs/lang/common";
-import { userStructure, type User } from "./contracts";
+import { type User } from "./contracts";
 import { userExist } from "./user-checker";
 
 export const userRoute = useRouteBuilder("GET", "/users/{userId}")
@@ -18,11 +18,18 @@ export const userRoute = useRouteBuilder("GET", "/users/{userId}")
 	.check(userExist, {
 		input: ({ userId }) => userId,
 		result: "user.found",
-		otherwise: ResponseContract.notFound("user.notFound"),
+		otherwise: ({ response, result }) => {
+			type _CheckRejectedResult = DCommon.ExpectType<
+				typeof result.information,
+				"user.notFound",
+				"strict"
+			>;
+
+			return response.notFound("user.notFound");
+		},
 		indexing: "user",
 	})
 	.handler(
-		ResponseContract.ok("user.read", userStructure),
 		(floor, { response }) => {
 			type _CheckFloor = DCommon.ExpectType<
 				typeof floor,
@@ -33,6 +40,6 @@ export const userRoute = useRouteBuilder("GET", "/users/{userId}")
 				"strict"
 			>;
 
-			return response("user.read", floor.user);
+			return response.ok("user.read", floor.user);
 		},
 	);

package/skills/http-server/references/initialization.md

@@ -28,6 +28,6 @@ Le store est global : lorsqu'une application contient plusieurs Hubs qui doivent
 
 ## Ajouter un plugin
 
-Brancher le plugin sur le Hub avant d'appeler le connecteur. Les paramètres et les effets relèvent du plugin choisi ; les rechercher depuis `docs/concepts.llms.md`. L'[exemple de génération](examples/generate-sdk.ts) montre `.plug(...)` et un plugin déclenché par le cycle de vie.
+Brancher le plugin sur le Hub avant d'appeler le connecteur. Les paramètres et les effets relèvent du plugin choisi ; les rechercher depuis `docs/concepts.llms.md`.
 
 Pour approfondir, rechercher l'initialisation HTTP dans le routeur conceptuel du package AgentKit.

package/skills/http-server/references/reusable-flows.md

@@ -8,14 +8,14 @@ Voir [le checker de recherche d'utilisateur](examples/user-checker.ts). Sa capac
 
 - `input` : calcul de l'argument depuis le floor courant ;
 - `result` : information du résultat permettant de continuer ;
-- `otherwise` : contrat de réponse si le résultat attendu n'est pas obtenu ;
+- `otherwise` : callback retournant la réponse si le résultat attendu n'est pas obtenu ; il reçoit `response`, le `floor` courant et le `result` excluant les issues sélectionnées ;
 - `indexing` : clé sous laquelle ajouter la valeur retenue au floor, si elle doit être réutilisée.
 
-L'[exemple de lecture](examples/user-route.ts) interprète ainsi un checker pour une route. Le résultat sélectionné est garanti aux étapes suivantes ; l'autre résultat termine le flux avec la réponse déclarée.
+L'[exemple de lecture](examples/user-route.ts) interprète ainsi un checker pour une route. Le résultat sélectionné est garanti aux étapes suivantes ; l'autre résultat termine le flux avec la réponse retournée par `otherwise`.
 
 ## Preset : réutiliser l'interprétation HTTP
 
-Quand une opération attend toujours le même résultat et produit la même réponse sinon, nommer cette politique avec `createPresetChecker`. Le checker reste réutilisable avec d'autres interprétations ; le preset fixe son usage récurrent.
+Quand une opération attend toujours le même résultat et produit la même réponse sinon, nommer cette politique avec `createPresetChecker`. Le checker reste réutilisable avec d'autres interprétations ; le preset fixe son usage récurrent. Son callback `otherwise` reçoit `response` et le `result` non retenu, sans floor appelant.
 
 Appliquer ensuite `.presetCheck(...)`, fournir l'input depuis le floor et choisir une indexation locale avec `.indexing(...)`. L'[exemple de modification](examples/rename-user-route.ts) réutilise le preset défini dans [le module du checker](examples/user-checker.ts).
 

package/skills/http-server/references/routes-and-floor.md

@@ -4,7 +4,7 @@
 
 Commencer avec le builder de la famille de routes concernée. Pour une route sans préfixe commun, utiliser `useRouteBuilder`. `.extract(...)` décrit les sources attendues avec les data structures et leurs contraintes. Réutiliser les structures partagées du projet lorsqu'elles portent le même contrat.
 
-L'extraction vérifie la donnée avant de poursuivre. Une entrée invalide produit la réponse d'extraction prévue par la configuration ; ne pas ajouter de parsing manuel ou de variante `OrThrow` dans les étapes suivantes.
+L'extraction vérifie la donnée avant de poursuivre. Une entrée invalide appelle le callback d'échec du Hub, qui retourne par défaut `422 / extract-error` avec l'erreur en body. Pour adapter ce refus à une étape, passer un callback en second argument de `.extract` : il reçoit `response`, le `floor` courant et `dataStructureError`. Ne pas ajouter de parsing manuel ou de variante `OrThrow` dans les étapes suivantes.
 
 Le placement dans le floor dépend de la forme déclarée :
 
@@ -23,7 +23,7 @@ Ne pas accéder manuellement à la requête brute pour récupérer une valeur qu
 
 Utiliser `cut` pour une opération spécifique au flux courant : qualification métier nécessaire à ce scénario, appel applicatif avec adaptation de ses résultats ou préparation particulière.
 
-Déclarer les réponses possibles dans le premier argument. Dans le callback, retourner `response(...)` pour terminer ou `output(...)` pour transmettre les données et continuer. Ne pas retourner une valeur brute en espérant enrichir le floor.
+Le callback de `.cut` reçoit le floor et les outils `response` et `output`. Retourner une réponse, par exemple `response.conflict(information)`, pour arrêter la route, ou `output(...)` pour enrichir le floor et poursuivre. Ne pas retourner une valeur brute en espérant enrichir le floor.
 
 L'[exemple de modification](examples/rename-user-route.ts) adapte un résultat applicatif : l'échec attendu devient une réponse de conflit ; la réussite fournit la donnée à la suite. Les règles de modification restent dans le traitement applicatif. Si la même vérification et son interprétation se répètent, utiliser un checker et son preset comme décrit dans [les flux réutilisables](reusable-flows.md).
 
@@ -31,8 +31,16 @@ L'[exemple de modification](examples/rename-user-route.ts) adapte un résultat a
 
 Le handler termine la route et retourne la réponse positive lorsque les étapes précédentes ont réussi. Préparer les préconditions et traiter les échecs attendus en amont. Il peut appeler le traitement applicatif à cet endroit si ses préconditions garantissent le résultat attendu.
 
-Un `ResponseContract` associe le statut HTTP, une `information` précise et le schéma du body éventuel. L'information distingue les issues de l'API, y compris celles qui ont le même statut. Retourner la réponse avec l'outil `response` fourni au callback et respecter le contrat déclaré.
+Le callback de `.handler` reçoit le floor et l'outil `response`. Retourner `response.ok(information, body)` pour envoyer le résultat, ou `response.noContent(information)` pour une réussite sans body. Choisir l'information pour identifier le résultat de l'opération : elle distingue les issues de l'API, y compris lorsqu'elles partagent le même statut HTTP.
+
+Le type de chaque réponse est déduit de son statut, de son information et de son body. Les helpers ne valident ni ne filtrent le body au runtime ; préparer les données à exposer avant de les leur transmettre. Le handler dispose de tous les helpers de réponse. Dans les `cut` et les callbacks `otherwise`, seuls les helpers de refus sont disponibles : `4xx` et `internalServerError`.
 
 Ne pas transformer le handler en orchestrateur métier. Dans une application organisée en couches, consommer les use cases résolus et les qualifications prévues par le domaine. Pour comprendre ces responsabilités, rechercher les frontières du Type-Driven Design et les fixtures d'infrastructure dans `docs/concepts.llms.md`.
 
 Pour une représentation de body particulière, un flux ou un autre besoin HTTP, rechercher le mécanisme adapté dans le routeur conceptuel avant de modifier la réception ou l'envoi natifs.
+
+## Partager les types avec un client
+
+Pour créer un client à partir des routes du serveur, utiliser `RouteDeclarationToContract<typeof route>`. Ce type reprend les entrées et toutes les réponses de la route, y compris les refus des extractions et des vérifications exécutées dans les processus ou le preflight. Une union de types de routes permet de couvrir plusieurs endpoints. L'[exemple de client](examples/inferred-client.ts) montre comment partager ces types et sélectionner la réponse attendue, sans charger les modules serveur au runtime.
+
+Pour générer une documentation OpenAPI, consulter `docs/concepts/02-server/20-http/50-open-api.ts` depuis le package installé. Cette ressource explique comment fournir les schémas de réponse au générateur.

package/dist/bin/install/index.d.ts

@@ -1,2 +0,0 @@
-import * as DSCommand from "@duplojs/server/command";
-export declare const installCommand: DSCommand.Command<"install">;

package/docs/concepts/02-server/20-http/50-codegen.ts

@@ -1,29 +0,0 @@
-/**
- * @title Comment partager des ressources
- *
- * Génération du typage des routes et des `DataStructure` pour partager un contrat statique.
- */
-import { createHub, routeStore } from "@duplojs/http";
-import { codeGeneratorPlugin } from "@duplojs/http/codeGenerator";
-import * as DCommon from "@duplojs/lang/common";
-
-const hub = createHub({ environment: "BUILD" })
-	.register(routeStore.getAll())
-	.plug(
-		codeGeneratorPlugin({
-			// Génère le typage des routes.
-			outputFile: DCommon.infer("types.d.ts"),
-
-			// Génère les `DataStructure` utilisées par les routes.
-			generateStructure: {
-				outputFolder: DCommon.infer("dataStructures"),
-			},
-		}),
-	);
-
-// La génération produit des fichiers autonomes à distribuer aux consommateurs.
-// Les `DataStructure` peuvent être générées depuis les routes ou sélectionnées explicitement.
-
-// `codeGeneratorPlugin` exécute sa génération sur le hook `beforeStartServer`.
-// Le `Hub` doit donc disposer d'un connecteur HTTP.
-// En environnement `BUILD`, le cycle s'exécute sans démarrer le serveur HTTP.

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

@@ -1,31 +0,0 @@
-# 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/generate-sdk.ts

@@ -1,36 +0,0 @@
-/**
- * @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,
-});