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

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,18 @@
+/**
+ * @title Valider une entrée et répondre sans dépendance applicative.
+ *
+ * Cette route autonome sert au démarrage minimal du serveur.
+ */
+import { ResponseContract, 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(
+		ResponseContract.ok("hello.received", DDataStructure.string()),
+		({ name }, { response }) => response("hello.received", name),
+	);

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * @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 { ResponseContract, 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 { 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(
+		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"),
+			});
+		},
+	)
+	.handler(
+		ResponseContract.ok("user.renamed", userStructure),
+		(floor, { response }) => {
+			type _CheckFloor = DCommon.ExpectType<
+				typeof floor,
+				{
+					userId: User["id"];
+					body: RenameUserBody;
+					user: User;
+					updatedUser: User;
+				},
+				"strict"
+			>;
+
+			return response("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, ResponseContract, 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: ResponseContract.notFound("user.notFound"),
+});

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

@@ -0,0 +1,38 @@
+/**
+ * @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 { ResponseContract, 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 { 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: ResponseContract.notFound("user.notFound"),
+		indexing: "user",
+	})
+	.handler(
+		ResponseContract.ok("user.read", userStructure),
+		(floor, { response }) => {
+			type _CheckFloor = DCommon.ExpectType<
+				typeof floor,
+				{
+					userId: User["id"];
+					user: User;
+				},
+				"strict"
+			>;
+
+			return response("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`. L'[exemple de génération](examples/generate-sdk.ts) montre `.plug(...)` et un plugin déclenché par le cycle de vie.
+
+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` : contrat de réponse si le résultat attendu n'est pas obtenu ;
+- `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.
+
+## 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.
+
+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,38 @@
+# 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 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.
+
+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.
+
+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.
+
+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.
+
+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é.
+
+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.

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`.

package/skills/modeling/references/orchestration.md

@@ -0,0 +1,36 @@
+# Des preuves aux points d'entrée
+
+Les chemins `docs/` ci-dessous se résolvent depuis la racine du package `@duplojs/agents-kit` installé, retrouvée selon le `SKILL.md`.
+
+## Obtenir le résultat attendu
+
+Pour chaque paramètre d'agrégat portant une évidence, retrouver la méthode de repository et la variante demandées par `GetEvidenceResult`. Appeler cette méthode, puis discriminer son résultat avant de poursuivre. Une méthode peut produire plusieurs évidences : seule la branche exigée satisfait la précondition. Traiter ou propager les autres branches sans appeler l'agrégat.
+
+Pour une preuve de provenance, lire `docs/concepts/01-fundamental/06-modeling/50-evidence.ts`. Pour préparer et composer les entrées d'un use case, lire `docs/concepts/05-type-driven-design/03-applications/10-use-case.md`, qui relie la fixture `createBook`. Les mécanismes de sélection et de regroupement des résultats y sont expliqués ; les appliquer aux branches exigées par le contrat du projet.
+
+Une évidence exprime une garantie de contrat, sans effectuer de contrôle runtime. L'implémentation doit réellement exécuter l'opération annoncée avant de produire sa preuve. `GetEvidenceResult` extrait les types du contrat de la méthode ; il ne crée pas une identité nominale propre à chaque méthode. Si deux provenances doivent être distinguées, employer des noms d'évidence distincts. Une `SignedFunction` identifie quant à elle l'opération fournie comme dépendance.
+
+## Propager les exigences vers l'appelant
+
+Choisir la frontière qui possède l'information et peut établir la preuve :
+
+| Entrée attendue | Préparation |
+| --- | --- |
+| Valeur métier | Réutiliser sa structure dans le schéma du point d'entrée. |
+| Entité existante | Appeler le repository qui l'hydrate ; gérer son absence. |
+| Entité portant un flag | Appeler sa qualification et sélectionner la branche requise. |
+| Valeur portant une évidence | Appeler l'opération prévue par le contrat et sélectionner son résultat. |
+
+Un use case peut recevoir directement une entité qualifiée, ou effectuer lui-même sa récupération et sa qualification selon son contrat. Conserver les exigences explicites dans sa signature lorsqu'elles incombent à l'appelant. La frontière externe transforme les entrées brutes avec les structures du domaine et traite les refus ; elle ne fabrique pas des flags ou des évidences pour satisfaire la signature.
+
+Pour raccorder un point d'entrée ou implémenter un port, lire `docs/concepts/05-type-driven-design/04-infrastructure/10-implementation.md`. Cette page relie les exemples HTTP et CLI consommant le même use case. Les lectures seules ne nécessitent pas un use case intermédiaire ; une règle ou un effet métier supplémentaire doit rejoindre le domaine et l'application concernés.
+
+## Fournir les dépendances et exécuter les effets
+
+Les repositories du domaine décrivent les capacités extérieures requises par le métier. Les ports applicatifs peuvent les compléter avec les besoins techniques du use case, par exemple `save`. Déclarer chaque port avec `DInvocation.createPort`, puis le use case avec `createReader`. L'infrastructure fournit `Port.createImplementation` et résout les Readers avec `Reader.run` ou `resolveReaders`.
+
+Reader injecte les dépendances ; Resolver exécute les effets déclarés par l'agrégat. Pour modifier leur assemblage, consulter dans les pages sélectionnées le nommage des dépendances injectées et les contrats de résolution. Pour changer le contrat métier des effets, lire aussi `docs/concepts/05-type-driven-design/02-domains/20-aggregates.md`.
+
+Fixer l'ordre des effets et de la persistance selon le contrat métier. Si un effet nécessaire échoue, interrompre les étapes qui supposent son succès. `runAndResolve` permet d'exécuter une étape avant les effets ; des sauvegardes parallèles ne fournissent pas d'atomicité. Si le domaine exige une transaction, une sauvegarde ou un contexte spécifique, l'exprimer par le contrat et les preuves appropriées, puis l'établir réellement dans l'implémentation du port.
+
+Un flag ou une évidence établis avant une écriture ne garantissent pas à eux seuls l'absence de concurrence entre temps. Lorsque cette garantie est requise, la prévoir dans l'orchestration et le mécanisme de persistance. Conserver les refus métier dans les résultats attendus ; traiter une incohérence de données ou une panne imprévue comme une erreur technique selon le contrat existant.

package/skills/server/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: duplojs-server
+description: "Lire ou modifier des fichiers, charger la configuration et agir sur le processus avec les abstractions portables de @duplojs/server. Utiliser ce skill pour les interactions système côté serveur."
+---
+
+# Interactions serveur 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")))'
+```
+
+## Choisir la capacité serveur
+
+Pour une opération sur le système de fichiers ou l'environnement d'exécution, rechercher en priorité la fonction correspondante dans `@duplojs/server`. Le package expose les interactions avec le runtime selon les paradigmes de l'écosystème : chemins typés, résultats `Either` et erreurs identifiables. Utiliser l'API publique adaptée avant de recourir directement aux API Node.js, Bun ou Deno ; conserver une API native seulement lorsque la capacité recherchée n'est pas couverte.
+
+| Besoin | Domaine à consulter |
+| --- | --- |
+| Lire, écrire, créer, parcourir, déplacer ou supprimer une ressource | `DSFile` depuis `@duplojs/server/file` |
+| Charger et valider la configuration, lire les arguments, agir sur le processus ou ses dossiers | `DSCommon` depuis `@duplojs/server/common` |
+| Valider une interface de fichier ou de dossier et ses contraintes | `DSDataStructure` depuis `@duplojs/server/dataStructure` |
+| Construire et valider un chemin sans accès au système de fichiers | `DPath` depuis `@duplojs/lang/path` |
+
+Les capacités serveur sélectionnent leur implémentation selon l'environnement détecté. Utiliser cette abstraction sans ajouter de branchement par runtime lorsqu'elle couvre le besoin ; elle permet aussi de remplacer les capacités dans les tests.
+
+La construction d'une CLI relève du skill `duplojs-command`. La création de routes et le démarrage d'un serveur HTTP relèvent de `duplojs-http-server`. Consulter ces skills lorsque la tâche atteint ces points d'entrée.
+
+## Manipuler les ressources et leurs erreurs
+
+Valider les chemins externes avec `DPath.create` ou la contrainte plus précise nécessaire, puis les composer avec les fonctions de chemin. Un chemin valide ne prouve ni l'existence ni la nature de la ressource. Choisir une opération directe pour une action précise, ou une `FileInterface` / `FolderInterface` pour transporter une référence avec ses opérations.
+
+Conserver les résultats `Either` des I/O dans les fonctions réutilisables. Sélectionner leur branche avec `DEither`, puis discriminer l'erreur contenue par son identifiant. Une permission refusée et une absence demandent des décisions différentes. Traiter le résultat de l'opération effective, même après une vérification d'existence ; propager ou adapter le refus sans ajouter de `throw`.
+
+Pour écrire ou modifier un traitement de fichiers, lire [Fichiers, chemins et erreurs](references/files.md). L'[exemple de lecture et d'écriture](references/examples/files.ts) montre une absence explicitement tolérée et l'arrêt des opérations dépendantes sur échec.
+
+## Contrôler l'environnement et le processus
+
+Déclarer le contrat des variables avec les data structures. Utiliser `DSCommon.environmentVariable` pour transmettre le résultat du chargement ; au démarrage, `environmentVariableOrThrow` convient lorsque le point d'entrée décide qu'une configuration invalide arrête le programme. Choisir les sources et leur priorité lorsque des fichiers d'environnement participent à la configuration.
+
+Distinguer le dossier de travail du processus, obtenu avec `getCurrentWorkDirectory`, du dossier du module, obtenu avec `getCurrentDirectoryName(import.meta)`. Utiliser les fonctions communes pour accéder aux arguments, changer de dossier ou terminer le processus, afin de conserver l'abstraction d'environnement.
+
+Si la tâche charge l'environnement ou agit sur les dossiers, les arguments ou la fin du processus, lire [Configuration et capacités du processus](references/environment.md). L'[exemple d'environnement](references/examples/environment.ts) distingue les origines des chemins et fixe la priorité des sources.
+
+## Valider les fichiers dans un contrat
+
+Les structures `file` et `folder` portent des `FileInterface` et `FolderInterface`, pas des fichiers JavaScript natifs ni de simples strings. Décoder les chemins textuels avec les codecs serveur. Ajouter les contraintes d'existence ou de taille lorsque le contrat les exige ; ces vérifications d'I/O demandent une validation asynchrone. Une validation du fichier ne valide pas automatiquement son contenu.
+
+Si un contrat reçoit un fichier, un dossier ou leur chemin, lire [Structures et contraintes de ressources](references/structures.md) pour choisir le décodage et les validations nécessaires. L'[exemple de structure de fichier](references/examples/file-structure.ts) applique des contraintes d'existence et de taille.

package/skills/server/references/environment.md

@@ -0,0 +1,30 @@
+# Configuration et capacités du processus
+
+## Charger une configuration typée
+
+`DSCommon.environmentVariable` reçoit une shape de data structures et retourne un résultat asynchrone : `decode-success` avec les valeurs typées, `decode-error` pour une configuration non conforme, ou une erreur de lecture d'un fichier d'environnement. Les strings du runtime sont décodées selon les structures ; ne pas les convertir avec des casts dans le code consommateur.
+
+`environmentVariableOrThrow` appelle la version sûre, puis fournit les valeurs validées ou lève `EnvironmentVariableError` si le chargement ou le décodage échoue. Au démarrage, cet usage exprime la décision du point d'entrée d'interrompre une initialisation invalide, comme dans l'exemple ; il ne requalifie pas un refus de validation en défaillance imprévue. Dans une fonction qui doit transmettre son échec, conserver le résultat d'`environmentVariable`.
+
+Choisir les options qui déterminent les effets du chargement :
+
+- `includedEnvironmentFiles` ajoute les fichiers aux variables déjà présentes. Une erreur de lecture d'un fichier indiqué est propagée ; ne pas considérer implicitement ces fichiers comme facultatifs.
+- `override: false` (défaut) donne la priorité aux sources précédentes, dont les variables du runtime ; `true` donne priorité aux suivantes. L'ordre des fichiers participe à cette priorité.
+- `justRead: true` renvoie les valeurs validées sans modifier les variables du processus. Par défaut, un chargement réussi répercute les valeurs sur l'environnement du runtime.
+- `codecs` choisit le décodage. Fournir explicitement `DSDataStructure.codecsString` pour des structures serveur telles que `file` ou `folder`, afin de ne pas dépendre des codecs par défaut de l'implémentation du runtime.
+
+Voir [configuration et chemins du module](examples/environment.ts). Pour les substitutions de variables et des exemples complémentaires, rechercher les variables d'environnement dans le routeur conceptuel du package installé.
+
+## Choisir l'origine d'un chemin
+
+`getCurrentWorkDirectory()` retourne un `Success` portant le chemin absolu du dossier de travail, ou un `Error`. Il dépend de l'endroit où le processus a été lancé et peut changer pendant l'exécution. Sa variante `getCurrentWorkDirectoryOrThrow()` fournit directement le chemin ou lève une erreur.
+
+`getCurrentDirectoryName(import.meta)` donne le chemin absolu du dossier du module dont on fournit les métadonnées. L'utiliser pour localiser une ressource distribuée à côté de ce module. L'appel passe par une capacité serveur remplaçable et apporte le typage du chemin ; il conserve cette indirection plutôt que de lire directement `import.meta.dirname` dans l'application. La fonction s'appuie sur les métadonnées disponibles dans l'environnement d'exécution ; elle ne reconstruit pas une arborescence source supprimée par un bundler.
+
+`setCurrentWorkingDirectory` reçoit un chemin absolu et renvoie `Ok` ou `Fail` ; `setCurrentWorkingDirectoryOrThrow` lève une erreur en cas d'échec. Changer de dossier affecte les opérations suivantes du processus utilisant des chemins relatifs. Pour simplement viser une ressource, résoudre son chemin depuis l'origine appropriée.
+
+## Arguments et fin du processus
+
+`getProcessArguments()` fournit les arguments utilisateur sans les entrées de lancement du runtime. Pour leur syntaxe, leur validation, les options ou les sous-commandes, utiliser le skill `duplojs-command`.
+
+`exitProcess(code)` délègue la terminaison à l'environnement courant. Décider du code de sortie au point d'entrée qui interprète le résultat global ; les fonctions réutilisables transmettent leurs échecs pour que l'appelant choisisse la suite. Toutes les fonctions communes ne retournent pas un `Either` : respecter la signature de chacune plutôt que d'appliquer un traitement uniforme.

package/skills/server/references/examples/environment.ts

@@ -0,0 +1,41 @@
+/**
+ * @title Charger une configuration et choisir l'origine des chemins.
+ *
+ * Le dossier du module et le dossier de travail ne sont pas interchangeables.
+ */
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Une configuration invalide interrompt l'initialisation du module.
+export const configuration = await DSCommon.environmentVariableOrThrow(
+	{
+		PORT: DDataStructure.number([
+			DDataStructure.integer(),
+			DDataStructure.greaterThanOrEqual(1),
+			DDataStructure.lessThanOrEqual(65535),
+		]),
+		MODE: DDataStructure.literal(["DEV", "PROD"]),
+	},
+	{
+		// Le fichier indiqué doit être lisible ; les variables du runtime priment.
+		includedEnvironmentFiles: [DPath.declarePath(".env")],
+		override: false,
+		justRead: true,
+	},
+);
+
+type _CheckMode = DCommon.ExpectType<typeof configuration.MODE, "DEV" | "PROD", "strict">;
+
+const directory = DSCommon.getCurrentDirectoryName(import.meta);
+
+type _CheckDirectory = DCommon.ExpectType<typeof directory, string & DPath.Absolute, "strict">;
+
+export const resourcePath = DPath.resolveRelative([directory, DPath.declarePath("resources/template.json")]);
+
+export const outputPath = DEither.rightPipe(
+	DSCommon.getCurrentWorkDirectory(),
+	(workingDirectory) => DPath.resolveRelative([workingDirectory, DPath.declarePath("output/report.txt")]),
+);