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

package/skills/command/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: duplojs-command
+description: "Créer, modifier ou corriger une interface en ligne de commande avec @duplojs/server/command : arguments et options typés, sous-commandes, aide et point d'entrée exécutable."
+---
+
+# Commandes 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 forme de la commande
+
+Importer le domaine sous le namespace `DSCommand` depuis `@duplojs/server/command`, et les schémas sous `DDataStructure` depuis `@duplojs/lang/dataStructure`.
+
+| Besoin | Construction |
+| --- | --- |
+| Exécuter une commande racine avec ses entrées | `DSCommand.exec` lit les arguments du processus et appelle le callback après validation. |
+| Assembler plusieurs actions nommées | `DSCommand.create` définit les sous-commandes, placées dans les `subjects` du parent exécuté avec `exec`. |
+| Lire uniquement les options d'un script | `DSCommand.execOptions` retourne le résultat du parsing ; le script décide ensuite de lancer le traitement. |
+
+Identifier les entrées et leurs contraintes, déclarer leur contrat, puis écrire le callback avec les `args` et `options` inférés. Exécuter la racine une seule fois au point d'entrée. Pour une racine simple, lire la première déclaration de `docs/concepts/02-server/40-command/10-use.ts` ; pour un script sans arguments positionnels, suivre l'[exemple à options seules](references/examples/options-only.ts).
+
+## Déclarer les entrées
+
+Les entrées du terminal sont externes : les faire décoder et valider par les data structures intégrées aux déclarations. Décrire les contraintes utiles, comme un entier borné ou un choix de littéraux ; ne pas remplacer cette validation par un cast ou une conversion manuelle dans le callback.
+
+| Entrée | Déclaration et garantie |
+| --- | --- |
+| Valeur positionnelle | `createArgument` dans `subjects`, obligatoire par défaut. Placer les arguments `optional: true` après les obligatoires. |
+| Option à valeur | `createOption` dans `options`, facultative par défaut : absence en `undefined`. `required: true` la rend obligatoire ; une présence sans valeur reste invalide. |
+| Flag de présence | `createBooleanOption`, `false` si absent et `true` si présent ; ne reçoit pas de valeur. |
+| Liste | `createArrayOption`, facultative par défaut ; son schéma décrit un élément. Les bornes ne rendent pas la liste obligatoire. |
+
+Les noms doivent être uniques dans chaque ensemble d'options ou de sujets. Choisir aussi des alias sans collision et conserver `help` / `h` pour l'aide intégrée.
+
+Pour créer ou modifier une entrée, lire [Entrées et garanties](references/inputs.md) avant de choisir sa syntaxe et son schéma. L'[exemple complet](references/examples/preview-command.ts) combine arguments, options, flag et liste bornée ; reprendre les constructions nécessaires au contrat de la commande.
+
+## Assembler et exécuter
+
+Un même `subjects` contient soit des arguments, soit des sous-commandes. Le premier argument sélectionne la sous-commande ; le callback du parent ne s'exécute pas comme une étape préalable. Déclarer les options nécessaires sur chaque commande qui les consomme ; celles du parent ne sont pas héritées.
+
+Décrire les commandes et leurs entrées pour alimenter l'aide intégrée `--help` / `-h`. Choisir `displayName` sur la racine pour identifier le programme dans l'aide et les diagnostics.
+
+Si la tâche ajoute un arbre, modifie l'exécution ou expose un binaire, lire [Arbre, aide et résultat d'exécution](references/execution.md). L'[exemple avec sous-commande](references/examples/cli.ts) montre l'assemblage et le code de sortie sur erreur de validation.
+
+## Raccorder l'application et vérifier
+
+Le callback est un point d'entrée d'infrastructure : il adapte les données validées, appelle l'application et interprète ses résultats pour le terminal. Il retourne `void` ou une promesse de `void` ; lui retourner un `Either` métier ne propage pas cet échec à `exec`. Garder l'orchestration métier dans l'application et choisir le diagnostic et la conséquence finale dans le callback.
+
+Une erreur de validation empêche l'appel du callback ; `exec` retourne cette erreur après son affichage, sans fixer à lui seul un code de sortie d'échec. Avec `execOptions`, sélectionner l'information `success` avant de lancer le travail : l'aide est aussi un `Right`, sous `log-help`.
+
+Pour les opérations sur les fichiers, la configuration d'environnement et les capacités du processus appelées depuis une commande, consulter le skill `duplojs-server`.
+
+Vérifier le typage du projet, puis exercer l'aide, un appel valide, une entrée invalide et l'absence d'une entrée obligatoire. Pour un arbre, vérifier aussi le chemin complet vers la sous-commande. Utiliser des opérations sans effet ou des dépendances de test lorsque la commande agit sur l'environnement ; vérifier le code de sortie attendu en cas d'échec.

package/skills/command/references/examples/cli.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import * as DSCommand from "@duplojs/server/command";
+import * as DSCommon from "@duplojs/server/common";
+import * as DEither from "@duplojs/lang/either";
+import { previewCommand } from "./preview-command";
+
+const result = await DSCommand.exec(
+	{
+		displayName: "my-cli",
+		description: "Preview application operations",
+		subjects: [previewCommand],
+	},
+	() => {
+		console.log("Use my-cli preview --help to inspect export parameters.");
+	},
+);
+
+// Les diagnostics de validation ont déjà été affichés par exec.
+if (DEither.isLeft(result)) {
+	DSCommon.exitProcess(1);
+}

package/skills/command/references/examples/options-only.ts

@@ -0,0 +1,27 @@
+import * as DSCommand from "@duplojs/server/command";
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const result = await DSCommand.execOptions([
+	DSCommand.createOption("format", DDataStructure.literal(["json", "text"])),
+	DSCommand.createBooleanOption("verbose"),
+]);
+
+if (DEither.isLeft(result)) {
+	DSCommon.exitProcess(1);
+} else if (DEither.hasInformation(result, "success")) {
+	const options = DEither.unwrapRight(result);
+	type _CheckOptions = DCommon.ExpectType<
+		typeof options,
+		{
+			readonly format: "json" | "text" | undefined;
+			readonly verbose: boolean;
+		},
+		"strict"
+	>;
+
+	console.log(options);
+}
+// La branche log-help ne déclenche aucun traitement après l'aide.

package/skills/command/references/examples/preview-command.ts

@@ -0,0 +1,57 @@
+import * as DSCommand from "@duplojs/server/command";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+
+export const previewCommand = DSCommand.create(
+	"preview",
+	{
+		description: "Preview export parameters without writing files",
+		subjects: [
+			DSCommand.createArgument("source", DDataStructure.string()),
+			DSCommand.createArgument("destination", DDataStructure.string(), { optional: true }),
+		],
+		options: [
+			DSCommand.createOption("format", DDataStructure.literal(["json", "text"]), {
+				required: true,
+				aliases: ["f"],
+				description: "Export format",
+			}),
+			DSCommand.createOption("limit", DDataStructure.number([
+				DDataStructure.integer(),
+				DDataStructure.greaterThanOrEqual(1),
+				DDataStructure.lessThanOrEqual(100),
+			]), { description: "Maximum number of entries" }),
+			DSCommand.createBooleanOption("overwrite", { description: "Allow replacement" }),
+			DSCommand.createArrayOption("include", DDataStructure.string(), {
+				required: true,
+				min: 1,
+				max: 5,
+				description: "Comma-separated entries to include",
+			}),
+		],
+	},
+	({ args, options }) => {
+		type _CheckArgs = DCommon.ExpectType<
+			typeof args,
+			{
+				readonly source: string;
+				readonly destination: string | undefined;
+			},
+			"strict"
+		>;
+		type _CheckFormat = DCommon.ExpectType<typeof options.format, "json" | "text", "strict">;
+		type _CheckFlag = DCommon.ExpectType<typeof options.overwrite, boolean, "strict">;
+
+		// La liste obligatoire et son minimum garantissent l'accès sans absence.
+		const firstEntry = DArray.first(options.include);
+		type _CheckFirstEntry = DCommon.ExpectType<typeof firstEntry, string, "strict">;
+
+		console.log({
+			...args,
+			...options,
+			limit: options.limit ?? 20,
+			firstEntry,
+		});
+	},
+);

package/skills/command/references/execution.md

@@ -0,0 +1,31 @@
+# Arbre, aide et résultat d'exécution
+
+## Commandes nommées et racine
+
+Une commande créée par `DSCommand.create` est une valeur à exporter puis importer dans le module qui assemble le parent. La placer dans les `subjects` du parent ; il n'y a pas de découverte automatique des fichiers. L'[exemple CLI](examples/cli.ts) importe explicitement sa sous-commande.
+
+La sélection descend immédiatement vers la sous-commande lorsque le premier argument correspond à son nom. Le parent ne constitue donc ni un middleware ni une source d'options communes. Pour appeler `my-cli preview ...`, placer les options de `preview` après son nom et les déclarer sur cette commande. Mutualiser au besoin les déclarations d'options, puis les inclure dans les commandes concernées.
+
+Le callback du parent traite son invocation sans sous-commande. Lui donner un comportement utile selon le projet, par exemple indiquer les actions disponibles. L'aide intégrée répond à `my-cli --help` et `my-cli preview --help` sans exécuter les callbacks correspondants.
+
+## Résultats et erreurs
+
+`DSCommand.exec` lit les arguments du processus. Une erreur de décodage ou de validation est déjà affichée et revient dans un `DEither.Error<DSCommand.Error>` ; le callback de la commande sélectionnée ne s'exécute pas. Une exécution réussie, y compris l'affichage de l'aide, renvoie `DEither.Ok`.
+
+Ce résultat ne fixe pas à lui seul un code de sortie d'échec. À la frontière du programme, le discriminer avec `DEither.isLeft` et, si le contrat du binaire le demande, terminer avec `DSCommon.exitProcess(1)` depuis `@duplojs/server/common`, comme dans l'exemple CLI. Éviter d'afficher une seconde fois le même diagnostic.
+
+Les échecs métier restent à interpréter dans le callback qui consomme l'application : afficher le message adapté et choisir la conséquence pour le programme. Le callback attend une valeur `void` ou une promesse de `void` ; lui retourner un `Either` métier ne constitue pas un mécanisme de propagation. `exec` ne convertit pas les exceptions du callback en erreurs de validation.
+
+Pour adapter les messages des data structures, `exec` et `execOptions` acceptent `dataStructureErrorInterpreter`.
+
+## Script recevant uniquement des options
+
+`DSCommand.execOptions` renvoie un résultat à trois branches : `success` contient les options validées, `log-help` indique que l'aide a déjà été affichée, et un `Left` porte l'erreur déjà affichée. Discriminer le succès avec `DEither.hasInformation(result, "success")` avant de déballer et de lancer le travail ; une aide est aussi un `Right`.
+
+Lire l'[exemple de script](examples/options-only.ts). Réserver cette forme aux scripts sans arguments positionnels ni arbre de commandes : elle ne vérifie pas les arguments restants après extraction des options.
+
+## Exposer le binaire
+
+Réutiliser le mode d'exécution du projet. Pour un package compilé sous Node, placer un shebang `#!/usr/bin/env node` au début du point d'entrée généré et faire pointer le champ `bin` du `package.json` vers ce fichier exécutable. L'exemple `cli.ts` suppose une compilation qui conserve ce shebang. Si le projet exécute directement du TypeScript, utiliser son interpréteur et le shebang correspondants plutôt que pointer Node sur un TypeScript non pris en charge par sa configuration.
+
+Vérifier que le fichier déclaré dans `bin` est produit, inclus dans le package distribué et exécutable. Tester ensuite la commande depuis un projet consommateur ou une installation locale du package.

package/skills/command/references/inputs.md

@@ -0,0 +1,27 @@
+# Entrées et garanties
+
+Lire l'[exemple de prévisualisation](examples/preview-command.ts) pour combiner arguments, option obligatoire, option numérique facultative, flag et liste bornée. Les assertions `DCommon.ExpectType` y vérifient les garanties reçues dans le callback.
+
+## Valeurs du terminal
+
+`createArgument` reçoit le nom, la data structure et les paramètres éventuels. L'ordre dans `subjects` fixe l'ordre des valeurs positionnelles. Une déclaration facultative ajoute `undefined` à la valeur reçue ; la data structure décrit la valeur présente.
+
+`createOption` reçoit également un nom et une data structure. La syntaxe accepte `--format=json` et `--format json`, ainsi qu'un alias déclaré comme `-f json`. Déclarer les noms et les alias sans tirets. Le décodage depuis les chaînes est intégré, y compris vers un nombre : une data structure numérique peut donc valider un entier et ses bornes avant le callback.
+
+Ne pas confondre une option facultative avec une valeur par défaut : appliquer la valeur de repli au résultat validé, ou rendre l'option obligatoire selon le contrat attendu.
+
+## Flags et listes
+
+`createBooleanOption` modélise la présence : `--overwrite` active le flag. `--overwrite=false` est invalide ; ne pas le proposer comme syntaxe de désactivation.
+
+`createArrayOption` reçoit le schéma d'un **élément**, puis décode les éléments d'une valeur séparée par des virgules par défaut : `--include=src,tests`. Utiliser `separator` pour changer ce séparateur. Ne pas supposer qu'une répétition du flag accumule les valeurs.
+
+`min` et `max` contraignent la longueur d'une liste présente. Ils ne rendent pas l'option obligatoire : ajouter `required: true` si son absence doit échouer. Avec un `min` littéral de `1`, une liste obligatoire garantit un premier élément ; exploiter cette garantie sans assertion ni garde d'absence redondante.
+
+Exemple d'appel de la sous-commande exposée par [cli.ts](examples/cli.ts) :
+
+```sh
+my-cli preview ./src ./out --format=json --limit=20 --include=src,tests --overwrite
+```
+
+L'exemple affiche les paramètres d'une prévisualisation ; il n'écrit aucun fichier. L'argument `destination` et l'option `limit` peuvent être omis, tandis que `source`, `format` et `include` sont requis.

package/skills/fundamental/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: duplojs-fundamental
+description: "Appliquer les API et la philosophie fonctionnelle DuploJS pour toute tâche impliquant du code TypeScript, quel que soit le contexte d'exécution."
+---
+
+# Fondamentaux 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")))'
+```
+
+## Utiliser les API DuploJS
+
+Utiliser obligatoirement l'équivalent DuploJS avant une API native, tierce ou un nouvel utilitaire, y compris dans les tests. Chercher dans `lang` pour les primitives indépendantes de la plateforme, dans `server` pour les interactions avec l'environnement, puis dans les packages spécialisés.
+
+Importer le sous-export du domaine avec son namespace long, comme dans les exemples des références.
+
+## Modifier à l'endroit responsable
+
+Lire les contrats, définitions et appelants concernés ; intégrer le besoin dans la fonction, le modèle ou le module responsable. Limiter le remaniement au besoin, adapter les usages et vérifier les garanties conservées.
+
+Privilégier fonctions pures, immutabilité et transformations explicites ; isoler les interactions avec l'environnement.
+
+## Laisser les types s'inférer
+
+Laisser TypeScript inférer les valeurs et les retours des implémentations. Annoter un retour uniquement pour résoudre une récursivité ; les signatures d'interfaces et les déclarations de fonctions décrivent des contrats, pas cette annotation dans l'implémentation.
+
+## Composer les transformations
+
+Si la fonction retournée par une forme curifiée ne déclare pas ses propres génériques, écrire l'appel de configuration directement dans l'étape de `DCommon.pipe` ou `asyncPipe` : son contexte permet l'inférence. Ne pas préparer cette étape dans une variable ni forcer son typage par génériques, annotations ou casts. Lire [Composition](references/composition.md) lors de l'emploi d'une forme curifiée pour distinguer les deux niveaux de génériques.
+
+Écrire chaque argument du pipe sur sa propre ligne, avec virgule finale et fermeture séparée, même pour une donnée et une seule étape. Un appel simple peut rester direct ; préparer séparément les données de sources indépendantes avant de les combiner.
+
+Choisir `DCommon.asyncPipe` pour attendre les étapes, ou `DEither.rightPipe` / `rightAsyncPipe` pour transmettre les valeurs des `Right` et arrêter au premier `Left`. À toute étape produisant des états à sélectionner, composer production et sélection dans un pipe interne à sa callback, avant le déballage par le pipe extérieur. Lire [Composition](references/composition.md) pour ces enchaînements de résultats.
+
+## Remplacer les boucles impératives
+
+Ne pas écrire de `for`, de `while` ni leurs variantes. Utiliser :
+
+- `DArray.reduce` pour parcourir un tableau avec un accumulateur ; `DGenerator.reduce` pour un autre itérable.
+- `DGenerator.asyncReduce` pour un parcours asynchrone, y compris sur un tableau.
+- `DCommon.loop` pour une répétition conditionnelle ; `DCommon.asyncLoop` en asynchrone.
+- `DCommon.loopAccumulator` et `DCommon.asyncLoopAccumulator` pour transporter un accumulateur entre les tours d’une répétition conditionnelle.
+- `DGenerator.loop` et `DGenerator.asyncLoop` pour produire une séquence ; leurs variantes `loopAccumulator` transportent aussi un accumulateur.
+
+Dans les variantes `loopAccumulator`, transmettre l'état avec `next(nouvelAccumulateur)` ; `DGenerator.loop` et `DGenerator.asyncLoop` utilisent `next` pour émettre des valeurs. Dans `DCommon.loop` et `DCommon.asyncLoop`, `next` poursuit la boucle sans transmettre son argument au tour suivant. Terminer avec `exit`. Avant de créer ou remplacer une boucle, lire [Itérations](references/iterations.md) pour les contrats de ces callbacks. Pour une simple transformation ou sélection, utiliser directement `DArray.map` ou `DArray.filter`.
+
+## Valider les entrées et conserver les garanties
+
+Valider les données externes avec une `DDataStructure`, via l'intégration du module récepteur lorsqu'elle existe. Décrire les contraintes utiles : bornes, entier, format ou longueur. Une contrainte déclarée ne valide rien au runtime ; dans les traitements internes, réutiliser les garanties établies.
+
+Choisir selon la preuve disponible :
+
+- **Littéral ou garantie compatible** : déclaration sûre ou `DCommon.cast` ; `DCommon.infer` pour conserver aussi le littéral. Ces fonctions calculent une compatibilité statique, sans validation runtime.
+- **Valeur runtime sans preuve** : validation ou fabrique sûre, puis traitement du `Either`.
+- **Refus du compilateur** : vérifier l'inférence et l'origine de la garantie ; ne pas la fabriquer avec `as`, `!` ou un helper sans preuve.
+
+Lire [Contraintes et validation](references/constraints-and-validation.md) pour construire un contrat, une valeur contrainte ou résoudre un refus de compatibilité. Après chaque transformation, suivre les garanties restantes et exploiter les accès garantis sans garde redondante.
+
+## Représenter les résultats et propager les erreurs
+
+Utiliser `DEither.result` lorsqu'une fonction doit établir des états sans décider de leur caractère favorable ou défavorable. L'information distingue les états ; la valeur porte leur contexte. Tous ces `Result` sont des `Right` : `isRight` ne choisit pas un état particulier.
+
+Lorsque la fonction décide d'une réussite ou d'un refus prévisible, les exprimer en `Right` ou `Left`, y compris pour les absences et refus techniques. Si une branche renvoie un `Either`, toutes en renvoient un ; utiliser `DEither.ok()` pour une réussite sans valeur.
+
+Chez le consommateur, sélectionner les issues qui autorisent la suite avec `keepAsRightByInformation` ; les autres deviennent des `Left` en conservant information et valeur. Utiliser un sélecteur exhaustif comme `keepAsRightSelection` ou `matchInformation` lorsqu'une nouvelle variante doit obliger à réexaminer la décision.
+
+`unwrapRight` extrait les valeurs des `Right` et conserve les `Left` : le pattern sélection → `unwrapRight` → garde `isLeft` permet un retour anticipé sûr. Propager ou adapter les refus dans les fonctions réutilisables. Lire [Résultats et erreurs](references/results-and-errors.md) pour choisir la sélection et l'extraction.
+
+Les exceptions imprévues des dépendances ou du runtime remontent implicitement. Réserver les `throw` explicites et `OrThrow` à la consommation finale du résultat par la frontière d'exécution. Une fonction réutilisable n'ajoute pas de `throw`, même appelée depuis cette frontière. La rareté du refus ou son coût de propagation ne changent pas cette règle.
+
+Avant d'adapter une API qui lève sur un refus prévisible ou d'introduire `OrThrow`, lire [Résultats et erreurs](references/results-and-errors.md). Préférer les déclarations sûres pour les constantes connues.

package/skills/fundamental/references/composition.md

@@ -0,0 +1,19 @@
+# Composition
+
+## Configurer dans le contexte du pipe
+
+La forme directe reçoit donnée et paramètres ; la forme curifiée configure les paramètres puis reçoit la donnée. Une fonction déjà unaire peut être passée directement.
+
+Si la fonction retournée ne déclare pas ses propres génériques, ses types sont fixés à la configuration. Écrire cet appel dans l'étape du pipe apporte le contexte d'inférence ; passer ensuite une variable déjà configurée à un pipe ne le rétablit pas. Ne pas forcer cette préparation par génériques, annotations ou casts.
+
+Pour réutiliser le traitement, écrire une fonction recevant la donnée et construisant son pipe, ou utiliser la forme directe. L'[exemple de composition](examples/composition.ts) montre les deux formes, le format multiligne et une préparation à éviter.
+
+Préparer les données de sources indépendantes avant de les combiner ; les configurations curifiées restent dans leur pipe. Voir [deux sources indépendantes](examples/independent-inputs.ts).
+
+## Asynchronisme et résultats
+
+`DCommon.asyncPipe` attend chaque étape ; un seul `await` final suffit. Voir l'[exemple asynchrone](examples/async-composition.ts).
+
+`DEither.rightPipe` et `rightAsyncPipe` transmettent les valeurs des `Right` et arrêtent au premier `Left`. Un pipe ordinaire ne s'arrête pas automatiquement sur un `Left`. Pour sélectionner un état produit par une étape, composer production et sélection dans un `innerPipe` ou `asyncInnerPipe`, avant de rendre le résultat au pipe extérieur. Une callback construisant un `pipe` ou `asyncPipe` convient aussi.
+
+Ce montage s'applique à toute étape ou callback imbriquée. À l'étape extérieure suivante, le `Right` serait déjà déballé, sans son information. Voir la [sélection intermédiaire](examples/result-selection.ts).

package/skills/fundamental/references/constraints-and-validation.md

@@ -0,0 +1,24 @@
+# Contraintes et validation
+
+## Établir la garantie
+
+Une contrainte exprime une propriété dans les types : borne, longueur ou format. Les intersections cumulent ces garanties ; leur déclaration seule ne valide ni ne transforme une valeur.
+
+Aux frontières, décrire le contrat complet avec une `DDataStructure` et les contraintes du besoin. Fournir cette structure au module récepteur lorsqu'il propose une intégration ; sinon, valider explicitement et traiter le `Either`. Réutiliser ensuite les garanties établies. Voir [le contrat d'entrée](examples/input-validation.ts).
+
+## Choisir la construction
+
+- **Valeur connue statiquement ou garantie compatible** : `DCommon.cast` calcule les implications statiques que TypeScript ne déduit pas seul. La cible vient du type attendu ; aucune validation runtime n'est effectuée. Voir [les conversions](examples/cast.ts).
+- **Littéral à conserver** : `DCommon.infer` conserve aussi le type littéral et exige une entrée littérale. Voir [une propriété littérale](examples/infer.ts).
+- **Valeur runtime sans preuve** : validation par une structure, un prédicat ou une fabrique sûre. Une simple `string` ou un simple `number` ne prouve pas de contrainte.
+- **Constante spécialisée** : chercher une déclaration sûre du domaine avant `OrThrow`. Vérifier la surcharge : selon l'argument, elle peut retourner une valeur ou un `Either`. Voir [les chemins et Chrono](examples/safe-declarations.ts).
+
+Un refus de `cast` indique une compatibilité non établie : vérifier l'inférence ou le support du calcul pour une contrainte personnalisée, puis choisir une validation si nécessaire. Ne pas fabriquer la preuve avec une assertion ou un helper.
+
+Si un paramètre générique direct ne fournit pas la cible de `cast` ou `infer`, l'expliciter avec `satisfies` après l'appel. Ce contexte ne valide rien et n'est pas nécessaire partout : comparer [le paramètre générique](examples/generic-inference.ts) et [la propriété littérale](examples/infer.ts).
+
+## Exploiter les garanties restantes
+
+Suivre ce que chaque transformation préserve ou perd. Une longueur minimale garantit certains accès ; l'exploiter sans garde redondante. Elle ne garantit pas les indices au-delà du minimum, et n'enlève pas `undefined` du type propre aux éléments. Un filtre peut perdre cette garantie de longueur.
+
+Voir [les accès garantis](examples/guaranteed-array-access.ts) pour distinguer présence prouvée et accès incertain.

package/skills/fundamental/references/examples/async-composition.ts

@@ -0,0 +1,15 @@
+/**
+ * @title Composer des étapes asynchrones.
+ *
+ * Attendre le résultat final avec asyncPipe.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DString from "@duplojs/lang/string";
+
+declare function loadName(): Promise<string>;
+
+const name = await DCommon.asyncPipe(
+	loadName(),
+	DString.trim,
+	DString.toLowerCase,
+);

package/skills/fundamental/references/examples/cast.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Établir la compatibilité des contraintes.
+ *
+ * Convertir une garantie existante ou déclarer une valeur littérale.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DNumber from "@duplojs/lang/number";
+import type * as DPath from "@duplojs/lang/path";
+
+declare const belowTen: number & DNumber.LessThan<10>;
+const belowTwentyFive: number & DNumber.LessThan<25> = DCommon.cast(belowTen);
+
+const age: number & DNumber.GreaterThanOrEqual<18> = DCommon.cast(20);
+const path: string & DPath.Path = DCommon.cast("resources/config.json");
+
+// Une valeur incompatible ne peut pas acquérir la contrainte par cast.
+// @ts-expect-error 10 ne respecte pas la borne minimale de 18.
+const invalidAge: number & DNumber.GreaterThanOrEqual<18> = DCommon.cast(10);

package/skills/fundamental/references/examples/composition.ts

@@ -0,0 +1,40 @@
+/**
+ * @title Composer une transformation.
+ *
+ * Appels curifiés dans un pipe multiligne, avec inférence depuis la donnée.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DCommon from "@duplojs/lang/common";
+
+declare const users: readonly {
+	enabled: boolean;
+	name: string;
+}[];
+
+const enabledUsers = DArray.filter(users, (user) => user.enabled);
+
+// Même avec deux arguments, le pipe place la donnée et l'étape sur deux lignes.
+// L'appel curifié est écrit ici, dans le contexte fourni par le pipe.
+const names = DCommon.pipe(
+	users,
+	DArray.map((user) => user.name),
+);
+
+type _CheckNames = DCommon.ExpectType<typeof names, readonly string[], "strict">;
+
+// Plusieurs transformations s'enchaînent avec leurs appels curifiés à leur place.
+const enabledNames = DCommon.pipe(
+	users,
+	DArray.filter((user) => user.enabled),
+	DArray.map((user) => user.name),
+);
+
+type _CheckEnabledNames = DCommon.ExpectType<typeof enabledNames, readonly string[], "strict">;
+
+// À éviter : les génériques explicites rendent la préparation typable, mais le
+// pipe ajouté ensuite ne déplace pas l'appel de configuration dans son contexte.
+const preparedNames = DArray.map<typeof users, string>((user) => user.name);
+const namesFromPreparedStep = DCommon.pipe(
+	users,
+	preparedNames,
+);

package/skills/fundamental/references/examples/environment-initialization.ts

@@ -0,0 +1,19 @@
+/**
+ * @title Valider la configuration au démarrage.
+ *
+ * Utiliser une exception au point d’initialisation du programme.
+ */
+import * as DSCommon from "@duplojs/server/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+
+// Initialisation du programme, avant de commencer les traitements.
+const environment = await DSCommon.environmentVariableOrThrow({
+	PORT: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.greaterThanOrEqual(1),
+		DDataStructure.lessThanOrEqual(65535),
+	]),
+});
+
+// Ici, l'initialisation exige un dossier de travail accessible pour démarrer.
+const currentDirectory = DSCommon.getCurrentWorkDirectoryOrThrow();

package/skills/fundamental/references/examples/error-propagation.ts

@@ -0,0 +1,24 @@
+/**
+ * @title Propager les échecs dans le contrat de retour.
+ *
+ * Conserver les Left d’une opération dans une fonction réutilisable.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DSFile from "@duplojs/server/file";
+import type * as DPath from "@duplojs/lang/path";
+
+async function loadText(path: string & DPath.Path) {
+	const result = await DSFile.readTextFile(path);
+	if (DEither.isLeft(result)) {
+		return result;
+	}
+
+	return DEither.right("text-loaded", DEither.unwrapRight(result));
+}
+
+type _CheckResult = DCommon.ExpectType<
+	Awaited<ReturnType<typeof loadText>>,
+	Exclude<DSFile.ReadTextFileResult, DEither.Right> | DEither.Right<"text-loaded", string>,
+	"strict"
+>;

package/skills/fundamental/references/examples/generic-inference.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Fournir une cible de calcul en contexte générique.
+ *
+ * Utiliser satisfies avec cast et infer sur un paramètre générique direct.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare function defineName<GenericName extends string & DString.MinCharacters<3>>(
+	name: GenericName,
+): GenericName;
+
+const name = defineName(
+	DCommon.cast("Alice") satisfies string & DString.MinCharacters<3>,
+);
+
+const literalName = defineName(
+	DCommon.infer("Alice") satisfies string & DString.MinCharacters<3>,
+);
+
+type _CheckName = DCommon.ExpectType<
+	typeof name,
+	string & DString.MinCharacters<3>,
+	"strict"
+>;
+
+type _CheckLiteralName = DCommon.ExpectType<
+	typeof literalName,
+	"Alice" & DString.MinCharacters<3>,
+	"strict"
+>;

package/skills/fundamental/references/examples/guaranteed-array-access.ts

@@ -0,0 +1,31 @@
+/**
+ * @title Exploiter une taille minimale de tableau.
+ *
+ * Distinguer les indices garantis et les accès potentiellement absents.
+ */
+import * as DArray from "@duplojs/lang/array";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+const namesStructure = DDataStructure.array(
+	DDataStructure.string(),
+	[DDataStructure.minElements(2)],
+);
+
+declare const input: unknown;
+const result = namesStructure.check(input);
+if (DEither.isRight(result)) {
+	const names = DEither.unwrapRight(result);
+	const first = DArray.first(names);
+	const last = DArray.last(names);
+	const atZero = DArray.at(names, 0);
+	const atOne = DArray.at(names, 1);
+	const atTwo = DArray.at(names, 2);
+
+	type _CheckAccess = DCommon.ExpectType<
+		[typeof first, typeof last, typeof atZero, typeof atOne, typeof atTwo],
+		[string, string, string, string, string | undefined],
+		"strict"
+	>;
+}

package/skills/fundamental/references/examples/independent-inputs.ts

@@ -0,0 +1,18 @@
+/**
+ * @title Combiner des sources indépendantes.
+ *
+ * Préparer les arguments séparément avant leur combinaison.
+ */
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+declare const users: readonly {
+	enabled: boolean;
+	name: string;
+}[];
+declare const rawSearch: string;
+declare function searchUsers(names: readonly string[], search: string): readonly string[];
+
+const names = DArray.map(users, (user) => user.name);
+const search = DString.trim(rawSearch);
+const matches = searchUsers(names, search);

package/skills/fundamental/references/examples/infer.ts

@@ -0,0 +1,21 @@
+/**
+ * @title Conserver une valeur littérale contrainte.
+ *
+ * Garder le littéral lors de la déclaration d’une propriété.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DString from "@duplojs/lang/string";
+
+declare function defineSettings<GenericSettings extends {
+	name: string & DString.MinCharacters<3>;
+}>(settings: GenericSettings): GenericSettings;
+
+const settings = defineSettings({
+	name: DCommon.infer("Alice"),
+});
+
+type _CheckName = DCommon.ExpectType<
+	typeof settings.name,
+	"Alice" & DString.MinCharacters<3>,
+	"strict"
+>;

package/skills/fundamental/references/examples/input-validation.ts

@@ -0,0 +1,37 @@
+/**
+ * @title Valider un contrat de données.
+ *
+ * Décrire les contraintes puis discriminer le résultat de validation.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+
+const requestStructure = DDataStructure.object({
+	name: DDataStructure.string([
+		DDataStructure.minCharacters(3),
+		DDataStructure.maxCharacters(40),
+	]),
+	age: DDataStructure.number([
+		DDataStructure.integer(),
+		DDataStructure.greaterThanOrEqual(18),
+	]),
+	tags: DDataStructure.array(
+		DDataStructure.string(),
+		[DDataStructure.minElements(2)],
+	),
+});
+
+type Request = DDataStructure.StructureValue<typeof requestStructure>;
+
+function validateRequest(input: unknown) {
+	return requestStructure.check(input);
+}
+
+declare const input: unknown;
+const result = validateRequest(input);
+if (DEither.isRight(result)) {
+	const request = DEither.unwrapRight(result);
+
+	type _CheckRequest = DCommon.ExpectType<typeof request, Request, "strict">;
+}