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

package/skills/server/references/examples/file-structure.ts

@@ -0,0 +1,26 @@
+/**
+ * @title Décoder un chemin en fichier existant de taille bornée.
+ *
+ * Le codec construit l'interface ; les contraintes consultent le disque.
+ */
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+import type * as DSFile from "@duplojs/server/file";
+import type * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+
+const inputFile = DSDataStructure.file([
+	DSDataStructure.fileExist(),
+	DSDataStructure.size({ max: "1mb" }),
+]);
+
+type _CheckValue = DCommon.ExpectType<
+	DDataStructure.StructureValue<typeof inputFile>,
+	DSFile.FileInterface,
+	"strict"
+>;
+
+export function decodeInputFile(value: unknown) {
+	// Retourne decode-success avec l'interface, ou decode-error.
+	// Une simple string n'est pas la valeur déjà décodée du contrat.
+	return inputFile.asyncDecode(DSDataStructure.codecsString, value);
+}

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

@@ -0,0 +1,52 @@
+/**
+ * @title Conserver les erreurs des opérations de fichiers.
+ *
+ * Tolérer uniquement l'absence attendue et séquencer une écriture dépendante.
+ */
+import * as DSFile from "@duplojs/server/file";
+import * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+import type * as DCommon from "@duplojs/lang/common";
+
+export async function readTextOrEmpty(path: string & DPath.Path) {
+	const result = await DSFile.readTextFile(path);
+
+	if (DEither.isRight(result)) {
+		const text = DEither.unwrapRight(result);
+
+		type _CheckText = DCommon.ExpectType<typeof text, string, "strict">;
+		return result;
+	}
+
+	const error = DEither.unwrapLeft(result);
+
+	type _CheckError = DCommon.ExpectType<typeof error, DSFile.ReadTextFileErrors, "strict">;
+
+	return DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			// L'absence est le seul cas pour lequel ce scénario choisit un défaut.
+			"file-system-read-text-file-not-found": () => DEither.right("file-system-read-text-file", ""),
+		},
+		() => result,
+	);
+}
+
+export async function writeReport(directory: string & DPath.Path, text: string) {
+	const target = DPath.resolveRelative([directory, DPath.declarePath("report.txt")]);
+	const result = await DEither.rightAsyncPipe(
+		DSFile.ensureDirectory(directory),
+		// Cette écriture ne s'exécute pas si la préparation du dossier échoue.
+		() => DSFile.writeTextFile(target, text),
+	);
+
+	type _CheckResult = DCommon.ExpectType<
+		typeof result,
+		| DSFile.WriteTextFileResult
+		| Extract<DSFile.EnsureDirectoryResult, DEither.Left>,
+		"strict"
+	>;
+
+	return result;
+}

package/skills/server/references/files.md

@@ -0,0 +1,38 @@
+# Fichiers, chemins et erreurs
+
+## Choisir l'opération
+
+Choisir l'opération selon le résultat nécessaire et vérifier sa signature publique. Pour une capacité absente de cette sélection, rechercher le mécanisme dans `docs/concepts.llms.md` :
+
+| Besoin | API à considérer |
+| --- | --- |
+| Lire ou écrire du texte, du binaire ou du JSON | `readTextFile` / `writeTextFile`, `readFile` / `writeFile`, `readJsonFile` / `writeJsonFile` |
+| Ajouter du contenu sans remplacer le précédent | `appendTextFile`, `appendFile` |
+| Créer un dossier et ses parents si nécessaire | `ensureDirectory` |
+| Créer un fichier absent sans tronquer un fichier existant | `ensureFile` ; préparer le dossier parent séparément |
+| Créer une ressource temporaire | `makeTemporaryFile`, `makeTemporaryDirectory` |
+| Lister des chemins ou obtenir des interfaces d'entrées | `readDirectory`, `walkDirectory` |
+| Obtenir les métadonnées de la ressource ou du lien lui-même | `stat`, `linkStat` |
+| Copier, déplacer, renommer ou supprimer | `copy`, `move`, `rename`, `relocate`, `remove` selon leur contrat et leurs options |
+
+`readDirectory` renvoie des chemins relatifs au dossier lu par défaut ; demander `absolute: true` pour des chemins absolus, et `recursive: true` pour descendre dans les sous-dossiers. `walkDirectory` renvoie un générateur d'interfaces de fichiers, dossiers ou entrées inconnues ; choisir explicitement la récursivité et discriminer les interfaces avant d'employer leurs opérations spécifiques.
+
+`exists` retourne un `Either`, pas un booléen. Pour distinguer un fichier d'un dossier et conserver les diagnostics d'échec, utiliser `stat` ou `createEntryInterface`. Les raccourcis `isFile()` / `isFolder()` des interfaces renvoient `false` lorsqu'ils ne peuvent pas confirmer la nature de la ressource ; ils ne permettent pas de récupérer tous les diagnostics.
+
+## Séparer chemin, référence et état du disque
+
+Une string dynamique doit être validée par `DPath.create`, `createAbsolute` ou `createSegment` selon son usage. Utiliser les fonctions de résolution de `DPath` pour assembler les chemins. La validité du chemin reste une garantie sur sa représentation ; elle ne prouve pas l'accès au système de fichiers.
+
+`createFileInterface` et `createFolderInterface` construisent une référence sans créer ni inspecter la ressource. `createEntryInterface` effectue une inspection pour choisir l'interface appropriée. Les méthodes des interfaces délèguent aux opérations du domaine ; lire ou écrire le contenu passe par les fonctions qui prennent leur `.path`. Les opérations de déplacement ou de renommage renvoient la nouvelle interface dans leur résultat de réussite : utiliser ce résultat pour les opérations suivantes.
+
+Une vérification préalable d'existence ne garantit pas la réussite de la lecture ou de l'écriture suivante. Traiter le résultat de l'opération effective, même après validation d'une précondition.
+
+## Préserver les diagnostics et arrêter sur échec
+
+Pour une opération telle que `readTextFile`, le résultat porte `file-system-read-text-file` en réussite ou `file-system-read-text-file-error` en échec. La valeur du `Left` est une union de `DuploJSError` portant les identifiants précis, tels que `file-system-read-text-file-not-found` et `file-system-read-text-file-permission-denied`. Ces identifiants précis ne sont pas les informations du `Left` extérieur.
+
+Après sélection du `Left` avec `DEither`, utiliser `DPattern.matchWithError` pour couvrir toutes les erreurs déclarées, ou `matchWithErrorOtherwise` pour traiter un cas et conserver les autres. Ne pas dépendre du message d'erreur ni des codes natifs du runtime. Voir [lecture avec absence explicitement tolérée et écriture séquencée](examples/files.ts).
+
+Pour plusieurs opérations dépendantes, composer avec `DEither.rightAsyncPipe` : la première erreur est conservée et les étapes suivantes ne s'exécutent pas. Chaque étape reçoit la valeur déballée du `Right` précédent. Consulter les concepts `Either` pour les règles de composition et d'adaptation des résultats.
+
+`readJsonFile` parse le JSON et en retourne une valeur `DCommon.Json` ; il ne prouve pas le contrat de l'application. Faire ensuite vérifier cette valeur par une data structure, en conservant la différence entre échec de lecture et contenu invalide.

package/skills/server/references/structures.md

@@ -0,0 +1,15 @@
+# Structures et contraintes de ressources
+
+`DSDataStructure.file()` et `folder()` étendent les data structures de `@duplojs/lang/dataStructure` avec des valeurs `DSFile.FileInterface` et `FolderInterface`. Employer les structures fondamentales de `lang` pour les objets et les valeurs ordinaires, puis les structures serveur pour les ressources du système de fichiers.
+
+Choisir la validation d'après la représentation reçue :
+
+- Une interface déjà construite se vérifie avec `asyncCheck` lorsque des contraintes asynchrones sont présentes. Un objet ordinaire portant seulement une propriété `path` n'est pas une interface de fichier DuploJS.
+- Un chemin textuel se décode avec `asyncDecode(DSDataStructure.codecsString, valeur)`. Le codec normalise le chemin et construit une interface ; sans contrainte supplémentaire, il ne consulte pas la ressource sur le disque.
+- Pour le transport sous forme JSON, les codecs serveur `codecsJson` représentent aussi les interfaces par leur chemin.
+
+Ajouter `fileExist()` pour exiger un fichier existant ou `folderExist()` pour exiger un dossier existant. Ces contraintes inspectent les métadonnées et distinguent fichier et dossier. `size({ min, max })` vérifie la taille d'un fichier en octets ; les bornes acceptent des nombres ou les unités textuelles reconnues par l'écosystème. Ces contraintes nécessitent l'exécution asynchrone de la structure. Voir [décodage d'un chemin avec contraintes de fichier](examples/file-structure.ts).
+
+La validation d'une ressource porte sur son état au moment de la vérification. Elle ne réserve pas le fichier et ne dispense pas de traiter le résultat des I/O suivantes. Une structure de fichier ne valide pas non plus ses données internes : lire le texte ou le JSON avec `DSFile`, puis appliquer la structure du contenu attendu.
+
+Le type MIME fourni par une `FileInterface` est déduit de l'extension ; il ne constitue pas une inspection du contenu. Ne pas en déduire une preuve sur les octets du fichier.

package/skills/test/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: duplojs-test
+description: "Écrire ou corriger des tests DuploJS : vérifier les résultats Either et le typage, isoler les capacités serveur ou organiser un parcours E2E avec @duplojs/playwright."
+---
+
+# Tester avec 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")))'
+```
+
+## Partir du contrat testé
+
+Lire la signature et les résultats possibles de la fonction avant d'écrire ses assertions. Préparer les données avec les outils DuploJS et conserver le type de retour complet jusqu'à la sélection du résultat attendu. Utiliser les imports publics des domaines avec leur namespace long.
+
+Les outils du runner gardent leur rôle pour les assertions et les spies ; les exemples utilisent Vitest. Ce skill apporte les pratiques propres à DuploJS, à adapter au runner et à l'organisation du projet consommateur.
+
+| Garantie à vérifier | Démarche et ressource à lire |
+| --- | --- |
+| Une branche de résultat et sa valeur à l'exécution | Sélectionner le résultat puis écrire l'assertion : [Résultats, sélecteurs et typage](references/results.md) et l'[exemple autonome](references/examples/results.ts). |
+| L'inférence, le narrowing ou l'évolution d'un contrat | Ajouter les vérifications de type adaptées et exécuter le contrôle TypeScript des tests. Pour les formes curifiées et les assertions de type, lire `docs/concepts/04-tests/01-unit/10-either.ts`. |
+| Un traitement utilisant une capacité serveur à isoler | Injecter l'implémentation de test : [Remplacer les fonctions serveur](references/server.md) et l'[exemple de lecture](references/examples/server.ts). |
+| Un parcours dans le navigateur | Suivre la démarche E2E ci-dessous ; ses objets de pages et composants portent les interactions du scénario. |
+
+## Sélectionner le résultat attendu et vérifier sa valeur
+
+Un résultat `Either` porte une information et une valeur. Dans un test, `DEither.unwrapByInformationOrThrow` permet de sélectionner l'information attendue, de faire échouer immédiatement le test si une autre information est obtenue, puis de récupérer la valeur avec son type précis. Utiliser ce mécanisme aussi pour un échec attendu : sélectionner son information, puis vérifier l'erreur ou la donnée qu'il contient.
+
+Choisir l'outil selon l'intention :
+
+| Intention du test | Outil |
+| --- | --- |
+| Attendre une information précise | `DEither.unwrapByInformationOrThrow` |
+| Accepter ou rejeter explicitement chaque information possible | `DEither.unwrapSelectionOrThrow` |
+| Vérifier seulement le côté du résultat, sans information précise | `DEither.unwrapRightOrThrow` ou `DEither.unwrapLeftOrThrow` |
+| Vérifier dans le typage qu'une valeur est déjà un `Either`, sans l'extraire | `DEither.expect` |
+
+Les variantes qui lèvent sont utiles dans les tests : une branche inattendue doit les interrompre. Après l'extraction, écrire une assertion sur le contenu ; la sélection ne prouve pas que la valeur est correcte. Éviter un simple unwrap qui perdrait l'information attendue ou une assertion placée uniquement dans un `if` qui pourrait ne jamais s'exécuter. Cette pratique de test ne justifie pas de remplacer les résultats sûrs du code applicatif par des exceptions.
+
+## Surveiller l'évolution des résultats
+
+Utiliser `DEither.unwrapSelectionOrThrow` lorsqu'un test doit imposer une décision à chaque ajout d'information au contrat. Lui transmettre le résultat complet et décider explicitement des cas acceptés ou rejetés. Une sélection par information précise suffit lorsque le scénario n'a pas cette responsabilité de surveillance.
+
+Pour un point de surveillance exhaustif, lire la section correspondante de la référence sur les résultats avant de construire le sélecteur : le contrôle doit recevoir l'union complète. Exécuter le contrôle TypeScript des tests ; le runner seul ne garantit pas cette surveillance.
+
+## Isoler les dépendances serveur
+
+Pour les capacités de `@duplojs/server` exposées via son mécanisme d'implémentation, préférer `setEnvironment("TEST")` et `TESTImplementation.set` aux mocks de modules ou aux spies sur leurs exports. Enregistrer chaque fonction effectivement appelée, y compris indirectement : une implémentation absente lève une erreur, sans repli vers le runtime natif.
+
+Nettoyer le registre et rétablir l'environnement après chaque test, même en échec ; éviter les tests concurrents qui modifient ce même état. La référence serveur détaille ce cycle et les retours typés à injecter. Les autres dépendances peuvent utiliser les mocks habituels du runner.
+
+## Vérifier les garanties de typage
+
+Quand l'inférence ou le narrowing fait partie du contrat testé, ajouter `DCommon.ExpectType` avec `"strict"` à côté des assertions runtime. Vérifier une API curifiée dans `DCommon.pipe` ou `DCommon.asyncPipe` ; pour un predicate, vérifier le narrowing dans un `if`, ou dans `DCommon.when` pour la forme curifiée. Réserver `@ts-expect-error` aux usages que le contrat doit refuser, avec une explication.
+
+Une vérification de type et une assertion runtime contrôlent des garanties différentes. Préparer les arguments indépendants avant le pipe, récupérer son résultat dans une variable puis écrire l'assertion séparément. Exécuter le contrôle TypeScript lorsque des garanties de type sont vérifiées, puis les tests runtime concernés.
+
+## Organiser un parcours E2E
+
+Avec `@duplojs/playwright`, construire le contexte avec `Website`, les écrans avec `createPage` et leurs zones réutilisables avec `createComponent`. Garder les locators dans ces objets, puis exprimer les scénarios par leurs éléments, méthodes nommées et helpers `Actions` / `Assertions`.
+
+Les concepts sous `docs/concepts/04-tests/02-e2e/` se lisent selon l'intervention : `10-init.ts` pour initialiser le client, `20-architecture.ts` pour créer ou modifier pages et composants, `30-testing.ts` pour écrire le parcours et ses assertions. Reprendre les objets existants lorsque le scénario les utilise déjà.

package/skills/test/references/examples/results.ts

@@ -0,0 +1,95 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+import { describe, expect, it } from "vitest";
+
+interface User {
+	id: number;
+	email: string;
+}
+
+// Les résultats possibles sont inférés à partir des branches de la fonction.
+function findUserByEmail(email: string) {
+	if (email === "") {
+		return DEither.error(new Error("Email is required"));
+	}
+	const user = {
+		id: 1,
+		email: "jane@duplo.dev",
+	};
+	if (email === user.email) {
+		return DEither.result("user.found", user);
+	}
+	return DEither.left("user.notfound", email);
+}
+
+describe("findUserByEmail", () => {
+	it("selects the expected information and checks its value", () => {
+		const result = findUserByEmail("jane@duplo.dev");
+		const user = DEither.unwrapByInformationOrThrow(result, "user.found");
+
+		expect(user).toStrictEqual({
+			id: 1,
+			email: "jane@duplo.dev",
+		});
+
+		type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+	});
+
+	it("extracts an expected business failure", () => {
+		const result = findUserByEmail("missing@duplo.dev");
+		const email = DEither.unwrapByInformationOrThrow(result, "user.notfound");
+
+		expect(email).toBe("missing@duplo.dev");
+
+		type _CheckEmail = DCommon.ExpectType<typeof email, string, "strict">;
+	});
+
+	it("checks an expected error payload", () => {
+		const result = findUserByEmail("");
+		const error = DEither.unwrapByInformationOrThrow(result, "error");
+
+		expect(error).toBeInstanceOf(Error);
+		expect(error.message).toBe("Email is required");
+	});
+
+	it("monitors all possible information before extracting the user", () => {
+		const result = findUserByEmail("jane@duplo.dev");
+		// Une nouvelle information dans les résultats inférés de la fonction
+		// impose de revoir les cas acceptés ou rejetés à cet endroit.
+		const user = DEither.unwrapSelectionOrThrow(result, {
+			"user.found": true,
+			"user.notfound": false,
+			error: false,
+		});
+
+		expect(user).toStrictEqual({
+			id: 1,
+			email: "jane@duplo.dev",
+		});
+
+		type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+	});
+
+	it("fails when an excluded information is returned", () => {
+		const result = findUserByEmail("missing@duplo.dev");
+
+		expect(
+			() => DEither.unwrapSelectionOrThrow(result, {
+				"user.found": true,
+				"user.notfound": false,
+				error: false,
+			}),
+		).toThrow(DEither.HasNotSelectedInformationError);
+	});
+
+	it("preserves inference when selecting in a pipe", () => {
+		const user = DCommon.pipe(
+			findUserByEmail("jane@duplo.dev"),
+			DEither.unwrapByInformationOrThrow("user.found"),
+		);
+
+		expect(user.email).toBe("jane@duplo.dev");
+
+		type _CheckUser = DCommon.ExpectType<typeof user, User, "strict">;
+	});
+});

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

@@ -0,0 +1,59 @@
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+import * as DPath from "@duplojs/lang/path";
+import { TESTImplementation, setEnvironment } from "@duplojs/server";
+import * as DSFile from "@duplojs/server/file";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// Le traitement utilise l'API publique ; les tests remplacent seulement l'I/O.
+function loadGreeting(path: string & DPath.Path) {
+	return DEither.rightAsyncPipe(
+		DSFile.readTextFile(path),
+		(name) => DEither.result("greeting.loaded", `Hello ${name}`),
+	);
+}
+
+const inputPath = DPath.declarePath("fixtures/name.txt");
+
+describe("loadGreeting", () => {
+	beforeEach(() => {
+		setEnvironment("TEST");
+	});
+
+	afterEach(() => {
+		TESTImplementation.clear();
+		// Cette suite cible Node ; rétablir BUN ou DENO dans une suite adaptée.
+		setEnvironment("NODE");
+	});
+
+	it("uses the injected server implementation", async() => {
+		const readTextFile = vi.fn(() => Promise.resolve(DEither.right("file-system-read-text-file", "Jane")));
+		TESTImplementation.set("readTextFile", readTextFile);
+
+		const result = await loadGreeting(inputPath);
+		const greeting = DEither.unwrapByInformationOrThrow(result, "greeting.loaded");
+
+		expect(greeting).toBe("Hello Jane");
+		expect(readTextFile).toHaveBeenCalledExactlyOnceWith(inputPath);
+
+		type _CheckGreeting = DCommon.ExpectType<typeof greeting, `Hello ${string}`, "strict">;
+	});
+
+	it("preserves the I/O failure", async() => {
+		// Reconstituer une erreur publique par son identifiant, sans cast ni
+		// import de classe privée. Sa compatibilité est vérifiée à l'injection.
+		class PermissionDenied extends DCommon.DuploJSError.parentClass("file-system-read-text-file-permission-denied", Error) {}
+		const cause = new Error("Read denied");
+		const failure = new PermissionDenied(cause);
+		const readTextFile = vi.fn(() => Promise.resolve(DEither.left("file-system-read-text-file-error", failure)));
+		TESTImplementation.set("readTextFile", readTextFile);
+
+		const result = await loadGreeting(inputPath);
+		const error = DEither.unwrapByInformationOrThrow(result, "file-system-read-text-file-error");
+
+		expect(error).toBe(failure);
+		expect(DCommon.DuploJSError.hasIdentifier(error, "file-system-read-text-file-permission-denied")).toBe(true);
+		expect(error.cause).toBe(cause);
+		expect(readTextFile).toHaveBeenCalledExactlyOnceWith(inputPath);
+	});
+});

package/skills/test/references/results.md

@@ -0,0 +1,21 @@
+# Résultats, sélecteurs et typage
+
+Consulter [l'exemple exécutable de résultats](examples/results.ts) pour sélectionner une réussite, un échec attendu et vérifier l'extraction typée. La fonction de recherche y sert uniquement de petit contrat autonome à adapter à la fonction réellement testée.
+
+## Une information attendue
+
+`unwrapByInformationOrThrow` vérifie que l'information du résultat fait partie de la sélection demandée et extrait sa valeur. Sélectionner l'information précise plutôt que le seul côté `Right` ou `Left` lorsque plusieurs issues partagent ce côté. Pour un résultat asynchrone, attendre le résultat avant de l'extraire, ou utiliser la forme curifiée dans `DCommon.asyncPipe`.
+
+Après l'extraction, vérifier la valeur avec le runner : propriétés d'un objet, contenu d'une collection, erreur ou cause attendue. Pour une erreur DuploJS, son identifiant peut être vérifié avec `DCommon.DuploJSError.hasIdentifier` ; l'information du `Left` et l'identifiant de l'erreur qu'il contient sont deux contrats distincts.
+
+`DEither.expect` conserve exactement un type déjà contraint à un `Either` ; il ne valide pas une donnée inconnue au runtime.
+
+## Un point de surveillance exhaustif
+
+Le sélecteur de `unwrapSelectionOrThrow` doit contenir toutes les informations de l'union reçue, avec des booléens littéraux : `true` extrait la valeur et `false` fait échouer le test si cette information apparaît. Les clés étrangères à l'union sont refusées. Accepter plusieurs informations n'a de sens que si le même scénario tolère réellement leurs résultats ; la valeur extraite prend alors l'union des valeurs acceptées.
+
+L'ajout d'une information au type de retour rend le sélecteur incomplet et provoque une erreur de typage. Il ne se met pas à jour automatiquement : décider si le scénario accepte ou rejette la nouvelle information, généralement avec une seule entrée à `true`. L'exemple vérifie cette surveillance à partir des résultats inférés de la fonction.
+
+Ne pas réécrire manuellement une union réduite aux résultats déjà connus et ne pas filtrer le résultat avant de l'envoyer au sélecteur : le contrôle porte sur le type reçu à cet endroit. Les sélecteurs surveillent les informations ; une évolution de valeur ou de sous-type d'erreur nécessite les vérifications adaptées sur le contenu et son type.
+
+La compilation vérifie la complétude du sélecteur et `DCommon.ExpectType` vérifie les types obtenus. Le runner vérifie les valeurs et l'échec sur les informations exclues. Lancer ces deux validations dans le projet consommateur.

package/skills/test/references/server.md

@@ -0,0 +1,17 @@
+# Remplacer les fonctions serveur
+
+Lire [l'exemple de fonction utilisant une lecture serveur](examples/server.ts) pour tester un traitement applicatif sans accès réel au système de fichiers. Rechercher aussi « Remplacer les implémentations serveur » dans le routeur conceptuel pour un exemple de commande avec des arguments de processus contrôlés.
+
+## Injecter la capacité utilisée
+
+`setEnvironment` et `TESTImplementation` sont des exports directs de `@duplojs/server`, sans sous-export dédié. Importer les domaines tels que `DSFile` depuis leurs sous-exports habituels.
+
+Activer l'environnement `TEST`, puis enregistrer les implémentations avec `TESTImplementation.set`. Les noms et signatures autorisés sont typés à partir des fonctions serveur disponibles. Fournir leurs résultats `Either` attendus, y compris dans les scénarios d'échec. Enregistrer aussi les capacités appelées indirectement par le traitement ; seules les fonctions qui passent par le mécanisme d'implémentation serveur sont remplaçables ainsi.
+
+Utiliser un spy du runner comme implémentation injectée pour vérifier les arguments et le nombre d'appels. Le traitement testé continue d'appeler l'API serveur publique. Pour tester la propagation d'un échec, injecter cet échec, sélectionner son information dans le résultat applicatif et vérifier la valeur ou la cause propagée.
+
+## Rétablir l'état partagé
+
+Le registre et l'environnement sont partagés. Dans `afterEach`, appeler `TESTImplementation.clear()` et rétablir l'environnement attendu par la suite même après une assertion en échec. L'exemple rétablit `NODE` parce qu'il vise une suite Vitest exécutée sous Node ; adapter ce choix pour Bun ou Deno. Ne pas exécuter concurremment des tests qui modifient ce même état.
+
+Une implémentation absente en environnement `TEST` provoque une exception. Corriger l'enregistrement manquant si cet appel fait partie du scénario. Un test d'intégration qui doit vérifier les I/O réelles conserve son environnement natif et utilise des ressources temporaires adaptées.