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

package/skills/http-server/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: duplojs-http-server
+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
+
+## 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. 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.
+
+## 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.
+
+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`.
+
+## 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.
+
+## 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 attendus. Vérifier aussi qu'un refus arrête les étapes dépendantes.

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 { 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: ({ response }) => response.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/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/initialize.ts

@@ -0,0 +1,29 @@
+/**
+ * @title Assembler le Hub et le connecteur de l'environnement.
+ *
+ * Exécuter les déclarations de routes avant de consommer le store global.
+ */
+import "./minimal-route";
+import { createHub, routeStore } from "@duplojs/http";
+import { createHttpServer } from "@duplojs/http/node";
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// Une configuration invalide arrête l'initialisation avant l'écoute HTTP.
+const environment = await DSCommon.environmentVariableOrThrow({
+	ENVIRONMENT: DDataStructure.literal(["DEV", "PROD"]),
+	HOST: DDataStructure.literal(["localhost", "127.0.0.1", "0.0.0.0"]),
+	PORT: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.greaterThanOrEqual(1),
+		DDataStructure.lessThanOrEqual(65535),
+	]),
+});
+
+const hub = createHub({ environment: environment.ENVIRONMENT })
+	.register(routeStore.getAll());
+
+await createHttpServer(hub, {
+	host: environment.HOST,
+	port: environment.PORT,
+});

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

@@ -0,0 +1,17 @@
+/**
+ * @title Valider une entrée et répondre sans dépendance applicative.
+ *
+ * Cette route autonome sert au démarrage minimal du serveur.
+ */
+import { useRouteBuilder } from "@duplojs/http";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+export const helloRoute = useRouteBuilder("GET", "/hello")
+	.extract({
+		query: {
+			name: DDataStructure.string([DDataStructure.minCharacters(1)]),
+		},
+	})
+	.handler(
+		({ name }, { response }) => response.ok("hello.received", name),
+	);

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

@@ -0,0 +1,29 @@
+/**
+ * @title Consommer les garanties d'un processus d'authentification.
+ *
+ * Comparer son application commune par preflight et son exécution locale.
+ */
+import { useRouteBuilder } from "@duplojs/http";
+import type * as DCommon from "@duplojs/lang/common";
+import { authenticationProcess, useAuthenticatedRouteBuilder } from "./authentication";
+import { type User } from "./contracts";
+
+export const profileRoute = useAuthenticatedRouteBuilder("GET", "/profile")
+	.handler(
+		(floor, { response }) => {
+			type _CheckFloor = DCommon.ExpectType<
+				typeof floor,
+				{ user: User },
+				"strict"
+			>;
+
+			return response.ok("profile.read", floor.user);
+		},
+	);
+
+// Alternative lorsque le processus est propre à cette route.
+export const explicitAuthenticationRoute = useRouteBuilder("GET", "/session")
+	.exec(authenticationProcess, { imports: ["user"] })
+	.handler(
+		({ user }, { response }) => response.ok("session.read", user),
+	);

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

@@ -0,0 +1,52 @@
+/**
+ * @title Adapter les résultats d'un scénario applicatif.
+ *
+ * Un preset résout la ressource ; un cut traite l'issue propre à la modification.
+ */
+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, 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.
+declare function renameUser(user: User, body: RenameUserBody): Promise<
+	DEither.Right<"user-renamed", User> | DEither.Left<"rename-denied", undefined>
+>;
+
+export const renameUserRoute = useRouteBuilder("PATCH", "/users/{userId}")
+	.extract({
+		params: {
+			userId: DDataStructure.string([DDataStructure.uuid()]),
+		},
+		// Une structure sur la source conserve floor.body.
+		body: renameUserBody,
+	})
+	.presetCheck(iWantUserExist.indexing("user"), ({ userId }) => userId)
+	.cut(
+		async({ user, body }, { response, output }) => {
+			const result = await renameUser(user, body);
+
+			return DEither.matchInformation(result, {
+				"user-renamed": (updatedUser) => output({ updatedUser }),
+				"rename-denied": () => response.conflict("user.renameDenied"),
+			});
+		},
+	)
+	.handler(
+		(floor, { response }) => {
+			type _CheckFloor = DCommon.ExpectType<
+				typeof floor,
+				{
+					userId: User["id"];
+					body: RenameUserBody;
+					user: User;
+					updatedUser: User;
+				},
+				"strict"
+			>;
+
+			return response.ok("user.renamed", floor.updatedUser);
+		},
+	);

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

@@ -0,0 +1,26 @@
+/**
+ * @title Séparer une recherche réutilisable et son interprétation HTTP.
+ *
+ * Un preset fixe le résultat attendu et la réponse d'absence du checker.
+ */
+import { createPresetChecker, useCheckerBuilder } from "@duplojs/http";
+import * as DEither from "@duplojs/lang/either";
+import { type User } from "./contracts";
+
+// Capacité fournie par l'application ; son absence reste un résultat typé.
+declare function findUser(id: User["id"]): Promise<DEither.Maybe<User>>;
+
+export const userExist = useCheckerBuilder()
+	.handler(async(id: User["id"], { output }) => {
+		const result = await findUser(id);
+
+		return DEither.matchInformation(result, {
+			some: (user) => output("user.found", user),
+			none: () => output("user.notFound", null),
+		});
+	});
+
+export const iWantUserExist = createPresetChecker(userExist, {
+	result: "user.found",
+	otherwise: ({ response }) => response.notFound("user.notFound"),
+});

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

@@ -0,0 +1,45 @@
+/**
+ * @title Valider une entrée puis interpréter un checker dans une route.
+ *
+ * L'extraction et l'indexation du résultat enrichissent le floor du handler.
+ */
+import { useRouteBuilder } from "@duplojs/http";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import { type User } from "./contracts";
+import { userExist } from "./user-checker";
+
+export const userRoute = useRouteBuilder("GET", "/users/{userId}")
+	.extract({
+		params: {
+			userId: DDataStructure.string([DDataStructure.uuid()]),
+		},
+	})
+	.check(userExist, {
+		input: ({ userId }) => userId,
+		result: "user.found",
+		otherwise: ({ response, result }) => {
+			type _CheckRejectedResult = DCommon.ExpectType<
+				typeof result.information,
+				"user.notFound",
+				"strict"
+			>;
+
+			return response.notFound("user.notFound");
+		},
+		indexing: "user",
+	})
+	.handler(
+		(floor, { response }) => {
+			type _CheckFloor = DCommon.ExpectType<
+				typeof floor,
+				{
+					userId: User["id"];
+					user: User;
+				},
+				"strict"
+			>;
+
+			return response.ok("user.read", floor.user);
+		},
+	);

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

@@ -0,0 +1,33 @@
+# Initialiser et enregistrer les routes
+
+## Hub et connecteur
+
+Le `Hub` décrit l'application HTTP sans dépendre de son serveur natif. Il rassemble les routes et les capacités ajoutées par les plugins. `.plug(...)` ajoute un plugin ; `.register(...)` enregistre une route, un ensemble itérable ou un objet de routes.
+
+Le connecteur fournit l'exécution propre au runtime et lance le cycle de vie du Hub. Choisir celui adapté à l'environnement et vérifier son export public dans la documentation. L'[exemple d'initialisation sur Node](examples/initialize.ts) utilise `createHttpServer` depuis `@duplojs/http/node`.
+
+Il charge uniquement une [route autonome](examples/minimal-route.ts) : `GET /hello?name=Alice` valide le nom et le renvoie dans la réponse. Après configuration de l'environnement, cet exemple peut s'exécuter sans capacité applicative à implémenter. Ajouter ensuite les modules du projet selon le besoin.
+
+Conserver cette initialisation au point d'entrée. Les modules de routes déclarent les flux et les traitements ; ils ne démarrent pas chacun un serveur.
+
+## Charger la configuration d'environnement
+
+Récupérer et valider les variables d'environnement au démarrage avec `DSCommon.environmentVariableOrThrow`, depuis `@duplojs/server/common`. Décrire leur contrat avec les data structures, puis transmettre les valeurs typées au Hub et au connecteur.
+
+L'[exemple d'initialisation](examples/initialize.ts) utilise ainsi `ENVIRONMENT` pour configurer le Hub, puis `HOST` et `PORT` pour démarrer le serveur. Une variable absente ou invalide interrompt l'initialisation avant l'écoute HTTP : cette utilisation de `OrThrow` concerne la configuration au démarrage. Pour charger aussi des fichiers d'environnement, consulter les options de cette fonction dans la documentation conceptuelle.
+
+## Utiliser le route store
+
+Une déclaration achevée par `.handler(...)` construit une route et l'ajoute au store global. Importer les modules qui exécutent ces déclarations, puis enregistrer `routeStore.getAll()` sur le Hub.
+
+L'ordre est essentiel : `.register` consomme les routes présentes à ce moment-là. Le store ne parcourt aucun dossier et n'enregistre pas automatiquement les routes qui seraient déclarées plus tard dans le Hub déjà construit. Un import de type n'exécute pas le module.
+
+Un builder inachevé n'est pas une route enregistrée. Une route marquée `IgnoreByRouteStoreMetadata` est volontairement exclue de cette collecte ; elle peut être enregistrée explicitement si nécessaire.
+
+Le store est global : lorsqu'une application contient plusieurs Hubs qui doivent avoir des ensembles distincts de routes, préférer un enregistrement explicite de ces ensembles plutôt qu'une collecte globale indifférenciée.
+
+## 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`.
+
+Pour approfondir, rechercher l'initialisation HTTP dans le routeur conceptuel du package AgentKit.

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

@@ -0,0 +1,40 @@
+# Checkers, processus et builders communs
+
+## Checker : réutiliser l'opération
+
+Un checker encapsule une opération avec un input et des résultats nommés. Le créer avec `useCheckerBuilder().handler(...)` et retourner les résultats avec `output(information, value)`. Il peut adapter les `Either` d'un repository ou d'une capacité applicative ; il ne choisit pas leur statut HTTP.
+
+Voir [le checker de recherche d'utilisateur](examples/user-checker.ts). Sa capacité de recherche est déclarée avec `declare function` et doit être raccordée à l'application avant exécution. Pour l'utiliser avec `.check(...)`, fournir :
+
+- `input` : calcul de l'argument depuis le floor courant ;
+- `result` : information du résultat permettant de continuer ;
+- `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 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. 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).
+
+Ne pas répéter des `cut` pour rechercher la même ressource et renvoyer la même réponse d'absence. Utiliser un checker pour l'opération et un preset pour cette politique commune.
+
+## Process : réutiliser une séquence
+
+Créer un process avec `useProcessBuilder()`, enchaîner ses étapes, puis le finaliser avec `.exports(...)`. Son floor est local : les données de la route appelante ne deviennent pas implicitement son contexte, et toutes ses données internes ne deviennent pas le floor de la route.
+
+Déclarer les clés exposées avec `.exports([ ... ])`. Au point d'appel, `.exec(process, { imports: [ ... ] })` récupère les clés nécessaires parmi ces exports. Utiliser les options du process si son comportement doit être paramétré ; consulter les signatures pour leur passage depuis le floor appelant.
+
+Voir [le process d'authentification](examples/authentication.ts) et son [exécution explicite dans une route](examples/protected-route.ts). La vérification du token est un contrat déclaré à implémenter selon la politique de sécurité du projet. Le process peut lui-même produire une réponse qui arrête le traitement. Son export décrit uniquement ce que la suite peut récupérer après réussite.
+
+## Preflight : préparer une famille de routes
+
+Pour appliquer systématiquement un ou plusieurs processus avant les étapes propres à chaque route, partir de `usePreflightBuilder()`. Ajouter les processus avec `.exec(...)`, en précisant les imports, puis exposer sa fonction `.useRouteBuilder` sous un nom reflétant la politique commune.
+
+L'[exemple d'authentification](examples/authentication.ts) expose `useAuthenticatedRouteBuilder`. Cette fonction crée une route équipée du preflight ; chaque route construite avec elle dispose de l'utilisateur garanti dans son floor. Les vérifications du process passent avant ses propres extractions et traitements.
+
+Utiliser ce builder pour toutes les routes de la famille concernée. Voir [une route protégée](examples/protected-route.ts). Une route qui appelle directement le builder de base ne reçoit pas automatiquement la politique du builder personnalisé.
+
+Pour approfondir, rechercher les routines HTTP dans `docs/concepts.llms.md`. Consulter les ressources de sécurité du projet pour l'implémentation de vérification des tokens ; le builder assemble cette vérification et ne définit pas lui-même sa politique cryptographique.

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

@@ -0,0 +1,46 @@
+# Construire une route et suivre son floor
+
+## Décrire les entrées
+
+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 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 :
+
+- Une source décrite directement par une structure conserve sa clé de source : une structure sur `body` produit `floor.body`.
+- Une source décrite par un objet de structures ajoute chaque propriété au floor : un objet sous `params` contenant `userId` produit `floor.userId`.
+
+Voir [la route autonome](examples/minimal-route.ts) pour une extraction par propriété. Les exemples de [récupération](examples/user-route.ts) et de [modification d'une ressource](examples/rename-user-route.ts) montrent ensuite le raccordement applicatif et un body conservé sous sa clé. Leurs capacités déclarées avec `declare function` sont des contrats à remplacer par les implémentations du projet avant exécution.
+
+## Enrichir le floor
+
+Chaque étape reçoit le floor courant en premier argument. Les vérifications réussies peuvent y ajouter leur résultat sous la clé `indexing` ; un `cut` ajoute ou remplace les clés fournies à `output`. Le typage de l'étape suivante reflète ces garanties. Choisir les clés intentionnellement pour éviter d'écraser une donnée encore nécessaire.
+
+Ne pas accéder manuellement à la requête brute pour récupérer une valeur que l'extraction ou une étape précédente garantit déjà. Ne pas ajouter de garde pour une absence exclue du type.
+
+## Adapter un scénario avec `cut`
+
+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.
+
+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).
+
+## Terminer avec le handler
+
+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.
+
+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/skills/modeling/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: duplojs-modeling
+description: "Comprendre, concevoir ou faire évoluer un système métier DuploJS en Type-Driven Design : domaine, cycles de vie, agrégats, preuves, use cases et raccordement à l'infrastructure. S'applique aussi à l'implémentation d'une couche autour d'un domaine existant."
+---
+
+# Modélisation métier 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")))'
+```
+
+## Délimiter l'intervention
+
+Ici, TDD signifie **Type-Driven Design**. Le domaine exprime le métier et impose ses garanties par ses types. Partir de l'opération concernée et choisir la lecture selon la responsabilité modifiée :
+
+| Intervention | Contrats à examiner et référence à lire |
+| --- | --- |
+| Concevoir ou modifier un modèle, une qualification ou une transition | Invariants, faits et agrégats concernés : [Modèles et transitions](references/domain.md). |
+| Modifier un use case | Préconditions de l'agrégat, ports, refus, effets et persistance : [Des preuves aux points d'entrée](references/orchestration.md). |
+| Raccorder un point d'entrée ou implémenter un port existant | Contrat consommé, préparation des entrées et garanties produites : [Des preuves aux points d'entrée](references/orchestration.md). |
+
+## Comprendre le contrat et les faits concernés
+
+Lire les entrées, garanties, sorties et refus du contrat actuel. Lorsqu'un agrégat intervient, lire son implémentation et les faits qu'il appelle : leurs préconditions, leurs cibles et leur ordre expliquent les transitions et l'intention de l'opération. Lire aussi les qualifications ou opérations qui établissent les garanties requises ; une signature seule ne prouve pas leur réalisation.
+
+Étendre la lecture si une précondition, une provenance, un effet ou une responsabilité nécessaire reste inexpliqué. Arrêter l'exploration lorsque les contrats et les faits concernés permettent de réaliser et vérifier la modification ; les autres parcours du domaine restent hors de cette lecture.
+
+Pour raccorder un domaine fourni, conserver ses contrats : une difficulté technique ne justifie pas de retirer une précondition ou de déplacer une règle. Si une décision métier nécessaire manque ou se contredit, isoler la question et avancer sur les parties indépendantes.
+
+## Respecter les couches
+
+| Couche | Dépendances et responsabilités |
+| --- | --- |
+| Domaine | N'importe ni application ni infrastructure. Définit les modèles, qualifications, faits, agrégats et contrats des repositories. Les agrégats restent purs. |
+| Application | Importe le domaine. Définit ses ports, appelle les repositories, prépare les preuves, appelle les agrégats, résout les effets et persiste les résultats. N'importe pas l'infrastructure. |
+| Infrastructure | Importe domaine et application. Implémente les ports, hydrate les données, résout les Readers et adapte les points d'entrée aux contrats. |
+
+L'entrée habituelle d'une opération métier dans le domaine est un **agrégat appelé par un use case**. Le domaine orchestre les règles et les faits ; l'application orchestre leurs besoins techniques. Un repository est un contrat de capacité extérieure au domaine, pas nécessairement un accès à une base de données.
+
+L'infrastructure peut appeler directement une opération de lecture de repository, comme `findById` ou `findMany`, et une qualification du domaine pour préparer une entrée. Ne pas imposer un use case de simple relais. Dès qu'il faut conduire une opération métier, ses transitions ou ses effets, passer par l'orchestration applicative. Ne pas appeler directement un fait ou un agrégat depuis un point d'entrée.
+
+Lorsqu'une tâche crée une couche ou modifie ses responsabilités, lire `docs/concepts/05-type-driven-design/01-architecture/10-boundaries.md`. Pour un raccordement existant, appliquer ces frontières aux contrats concernés.
+
+## Choisir les garanties du modèle
+
+| Besoin | Choix |
+| --- | --- |
+| Vérifier une donnée et ses contraintes au runtime | `DataStructure` ; réutiliser les structures du domaine aux frontières. |
+| Distinguer deux valeurs de même représentation mais de sens différent | `NewType`. |
+| Porter une identité et une shape métier stable | `Entity`. |
+| Faire varier la forme d'une propriété selon son cas | Union de `TaggedObject` dans la shape commune. |
+| Prouver une condition actuelle de l'entité | `Flag`, établi par une qualification ou par le fait qui produit cette condition. Plusieurs flags compatibles peuvent coexister. |
+| Créer une entité ou modifier ses propriétés métier | `Fact` ciblant une seule entité, même si le changement ne modifie pas son état nommé. |
+| Exiger un passage, un résultat ou une provenance | `Evidence` et `GetEvidenceResult` dans le contrat qui porte cette exigence. |
+| Exiger une opération identifiée, au-delà de sa signature d'appel | `SignedFunction`. |
+| Déclarer des effets à exécuter autour des résultats métier | `Resolver` retourné par l'agrégat, exécuté par l'application. |
+
+Si le contrat exige une `Evidence` ou `GetEvidenceResult`, lire `docs/concepts/01-fundamental/06-modeling/50-evidence.ts` avant de préparer l'entrée. S'il exige une `SignedFunction`, lire `docs/concepts/01-fundamental/06-modeling/60-signed-function.ts`. Ces mécanismes portent des exigences distinctes : conserver l'opération réelle qui établit la garantie.
+
+## Implémenter et vérifier l'opération
+
+Adapter les appelants du contrat modifié. Pour une opération métier, remonter les exigences de l'agrégat vers le use case et son point d'entrée ; pour une lecture ou une qualification isolée, partir directement de son contrat. Décider qui reçoit les valeurs déjà qualifiées et qui les obtient par ses ports. Conserver les types métier jusque dans la validation externe ; un cast ne produit aucune garantie.
+
+Si la tâche assemble des ports ou des Readers, lire `docs/concepts/05-type-driven-design/03-applications/10-use-case.md` pour leur déclaration et leur résolution. Reader injecte les dépendances du use case ; Resolver exécute les effets déclarés par l'agrégat. Lire le contenu des ressources sélectionnées, pas seulement leurs titres.
+
+Vérifier que chaque preuve est établie par une opération réelle, que seules les branches autorisées atteignent l'agrégat et que l'enchaînement utilise les nouvelles entités retournées. Vérifier aussi le sens des imports et l'ordre entre effets et persistance. Un `Left` attendu doit empêcher les étapes qui nécessitent le résultat positif.
+
+Exécuter le typage et les vérifications du projet. Pour les garanties ajoutées, vérifier les entrées acceptées et refusées par les types ; pour le comportement, couvrir les transitions et les branches de refus concernées, ainsi que l'absence d'effets après un refus. Ne pas transformer un échec de typage en cast ni apposer une preuve à la place de l'opération requise.

package/skills/modeling/references/domain.md

@@ -0,0 +1,33 @@
+# Modèles et transitions
+
+Les chemins `docs/` ci-dessous se résolvent depuis la racine du package `@duplojs/agents-kit` installé, retrouvée selon le `SKILL.md`.
+
+## Dessiner le cycle de vie utile
+
+Pour une nouvelle opération, identifier les invariants permanents, les conditions d'entrée, les changements et les garanties de sortie. Une petite entité peut suffire : ajouter des états ou des preuves lorsqu'ils expriment une distinction métier requise, sans inventer un cycle de vie plus détaillé que le besoin.
+
+Regrouper le modèle dans le namespace de l'entité : NewType, structures, définition commune, variantes de propriétés, flags et union des faits. La shape principale reste stable ; si certaines propriétés n'existent que dans un cas, les placer dans une variante de TaggedObject plutôt que rendre toutes les propriétés facultatives.
+
+Un état nommé n'épuise pas les conditions possibles. Une entité peut être disponible, éligible à une action et liée à une autre entité selon plusieurs qualifications compatibles. Ne pas transformer chaque combinaison de flags en un nouvel état exclusif. Une qualification lit l'entité, vérifie sa condition et retourne un résultat qui porte le flag associé ; elle ne change aucune propriété métier.
+
+Pour modifier cette organisation, lire `docs/concepts/05-type-driven-design/02-domains/10-entities.md`. Consulter ensuite les exemples de `docs/concepts/01-fundamental/06-modeling/` correspondant aux primitives utilisées : `10-new-type.ts`, `20-entity.ts`, `30-tagged-object.ts` ou `40-entity-lifecycle.ts`. La page sur les entités relie les fixtures de qualification et de transition.
+
+## Donner une cible à chaque fait
+
+Chaque création ou modification métier passe par un fait. Un fait peut lire plusieurs entités, mais il n'en modifie qu'une. Pour deux cibles, définir deux faits et les coordonner dans l'agrégat. Pour plusieurs changements successifs d'une même cible, transmettre la valeur retournée par le fait précédent.
+
+`Entity.update` appartient aux faits ; `Flag.append` appartient aux qualifications et aux faits qui établissent réellement la condition. Une hydratation avec `map` ou `decodeMap` reconstitue une donnée existante et ne remplace pas un événement de création.
+
+Après une mise à jour, repartir de la nouvelle entité, reconstruire les flags dont les conditions sont établies et appliquer le nouveau fait. Les anciens flags et l'ancien fait courant ne sont pas conservés par `Entity.update`. Ne pas réintroduire les preuves d'une valeur antérieure par un spread ou un cast. Le fait courant porté par l'entité ne constitue pas un historique persistant.
+
+Les valeurs passées à `update` doivent déjà satisfaire leurs structures : `update` ne les valide pas. Vérifier les préconditions, la payload et les preuves de sortie dans les faits du projet avant d'ajouter une transition.
+
+## Placer l'exigence à la bonne granularité
+
+Une contrainte commune à toutes les exécutions d'une transition appartient au fait. Une exigence propre à un parcours métier appartient à son agrégat ou à l'étape qui en est responsable.
+
+Comparer les parcours qui consomment le fait : conserver ses préconditions communes et placer les exigences supplémentaires dans le contrat du parcours qui les impose. Si le métier distingue les événements eux-mêmes, créer des faits distincts. Ne pas déplacer systématiquement toutes les évidences sur les faits, ni sur les seuls agrégats.
+
+L'agrégat n'appelle pas le repository pour obtenir la preuve : il l'exige en entrée. Il n'exécute pas non plus une callback impure reçue de l'extérieur. S'il demande un effet, il déclare la dépendance dans un Resolver ; sans effet à déclarer, il peut retourner directement sa valeur ou son Either.
+
+Pour un contrat d'agrégat, lire `docs/concepts/05-type-driven-design/02-domains/20-aggregates.md` ; son exemple `createBook` illustre les exigences propres à une transaction. Pour une capacité extérieure, lire `docs/concepts/05-type-driven-design/02-domains/30-repositories.md`. Si le contrat exige une provenance, consulter `docs/concepts/01-fundamental/06-modeling/50-evidence.ts` ; si c'est l'identité d'une dépendance qui compte, consulter `docs/concepts/01-fundamental/06-modeling/60-signed-function.ts`.