@duplojs/agents-kit 0.1.0-beta.8 → 0.1.0-beta.9

package/docs/API/20-server/40-command/10-createOption.ts

@@ -0,0 +1,46 @@
+/**
+ * @title DSCommand.createOption
+ *
+ * Déclarer une option à valeur décodée par une data structure.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSCommand from "@duplojs/server/command";
+
+const command = DSCommand.create(
+	"generate",
+	{
+		options: [
+			DSCommand.createOption(
+				"format",
+				DDataStructure.literal(["json", "text"]),
+				{
+					required: true,
+					aliases: ["f"],
+				},
+			),
+			DSCommand.createOption(
+				"output",
+				DDataStructure.string(),
+			),
+		],
+	},
+	({ options }) => {
+		type _CheckFormat = DCommon.ExpectType<
+			typeof options.format,
+			"json" | "text",
+			"strict"
+		>;
+		type _CheckOutput = DCommon.ExpectType<
+			typeof options.output,
+			string | undefined,
+			"strict"
+		>;
+	},
+);
+
+// Une option présente sans valeur est invalide, même lorsqu'elle est facultative.
+
+// Les noms et alias doivent éviter les collisions dans la commande ;
+// help et h sont réservés à l’aide intégrée.
+// Les formes --format=json, --format json et -f json sont acceptées.

package/docs/API/20-server/40-command/10-exec.ts

@@ -0,0 +1,51 @@
+/**
+ * @title DSCommand.exec
+ *
+ * Lire les arguments du processus, valider une commande racine et exécuter son traitement.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import * as DSCommand from "@duplojs/server/command";
+
+declare function generate(source: string, format: "json" | "text"): Promise<void>;
+
+const result = await DSCommand.exec(
+	{
+		displayName: "generator",
+		subjects: [
+			DSCommand.createArgument(
+				"source",
+				DDataStructure.string(),
+			),
+		],
+		options: [
+			DSCommand.createOption(
+				"format",
+				DDataStructure.literal(["json", "text"]),
+				{ required: true },
+			),
+		],
+	},
+	async({ args, options }) => {
+		type _CheckFormat = DCommon.ExpectType<
+			typeof options.format,
+			"json" | "text",
+			"strict"
+		>;
+
+		await generate(args.source, options.format);
+	},
+);
+
+if (DEither.isLeft(result)) {
+	// Le parsing invalide empêche le callback ; exec affiche le diagnostic.
+	const error = DEither.unwrapLeft(result);
+}
+
+// Pour un fichier cli.ts exécuté avec tsx :
+// tsx cli.ts ./source --format=json
+// Ici exec définit directement la commande racine : aucun nom de
+// sous-commande ne précède l'argument source.
+// Les noms d'options doivent être uniques dans la commande. subjects
+// contient soit des arguments positionnels, soit des sous-commandes.

package/docs/API/20-server/40-command/10-execOptions.ts

@@ -0,0 +1,30 @@
+/**
+ * @title DSCommand.execOptions
+ *
+ * Décoder les options du processus sans déclarer de commande positionnelle.
+ */
+import * as DEither from "@duplojs/lang/either";
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSCommand from "@duplojs/server/command";
+
+const result = await DSCommand.execOptions([
+	DSCommand.createOption(
+		"format",
+		DDataStructure.literal(["json", "text"]),
+	),
+	DSCommand.createBooleanOption("verbose"),
+]);
+
+if (DEither.hasInformation(result, "success")) {
+	const options = DEither.unwrapRight(result);
+
+	type _CheckFormat = DCommon.ExpectType<
+		typeof options.format,
+		"json" | "text" | undefined,
+		"strict"
+	>;
+}
+
+// L'aide est également un Right, identifié par log-help ; une erreur est
+// affichée puis renvoyée dans un Left.

package/docs/API/20-server/40-command/index.llms.md

@@ -0,0 +1,32 @@
+## Command
+
+Déclarer et exécuter des commandes CLI et leurs entrées typées.
+
+### [DSCommand.create](10-create.ts)
+
+Construire une commande nommée à placer dans un arbre de commandes.
+ 
+### [DSCommand.createArgument](10-createArgument.ts)
+
+Déclarer un argument positionnel validé et transmis à une commande.
+ 
+### [DSCommand.createArrayOption](10-createArrayOption.ts)
+
+Déclarer une option contenant plusieurs valeurs décodées.
+ 
+### [DSCommand.createBooleanOption](10-createBooleanOption.ts)
+
+Déclarer un flag représentant la présence d’une option.
+ 
+### [DSCommand.createOption](10-createOption.ts)
+
+Déclarer une option à valeur décodée par une data structure.
+ 
+### [DSCommand.exec](10-exec.ts)
+
+Lire les arguments du processus, valider une commande racine et exécuter son traitement.
+ 
+### [DSCommand.execOptions](10-execOptions.ts)
+
+Décoder les options du processus sans déclarer de commande positionnelle.
+ 

package/docs/API/20-server/40-command/index.md

@@ -0,0 +1,3 @@
+## Command
+
+Déclarer et exécuter des commandes CLI et leurs entrées typées.

package/docs/API/20-server/index.md

@@ -0,0 +1,3 @@
+# @duplojs/server
+
+Capacités portables de fichiers, environnement, validation de ressources et commandes CLI.

package/docs/API.llms.md

@@ -58,6 +58,26 @@ Fonctions de manipulation, recherche, validation et transformation des chaînes
 
 Manipulation et typage des tuples : convertir les garanties de cardinalité en positions typées, puis transformer leurs éléments en conservant leur forme.
 
+# @duplojs/server
+
+Capacités portables de fichiers, environnement, validation de ressources et commandes CLI.
+
+## [File](API/20-server/10-file/index.llms.md)
+
+Lire et modifier les ressources du système de fichiers, leurs chemins et leurs métadonnées.
+
+## [Common](API/20-server/20-common/index.llms.md)
+
+Accéder à la configuration, aux arguments et aux capacités du processus.
+
+## [DataStructure](API/20-server/30-dataStructure/index.llms.md)
+
+Décoder et valider les interfaces de fichiers et dossiers avec les contraintes serveur.
+
+## [Command](API/20-server/40-command/index.llms.md)
+
+Déclarer et exécuter des commandes CLI et leurs entrées typées.
+
 # @duplojs/json-web-token
 
 Politiques JWT réutilisables, signature, chiffrement facultatif et primitives cryptographiques.

package/package.json

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

package/skills/fundamental/SKILL.md

@@ -48,8 +48,10 @@ 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.
 
-Transmettre l'état sans mutation externe avec `next`, 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`.
+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
 

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

@@ -63,37 +63,50 @@ const loadedTotal = await DCommon.asyncPipe(
 // Chaque chargement est attendu avant le suivant ; la source peut aussi être un AsyncIterable.
 type _CheckLoadedTotal = DCommon.ExpectType<typeof loadedTotal, number, "strict">;
 
-const reachedValue = DCommon.loop<number, number>(({ previousOutput, next, exit }) => {
-	const current = previousOutput ?? 0;
-
+const reachedValue = DCommon.loopAccumulator(0, ({ accumulator, next, exit }) => {
 	// La condition est vérifiée avant le traitement, comme dans un while.
-	if (current >= 3) {
-		return exit(current);
+	if (accumulator >= 3) {
+		return exit(accumulator);
 	}
 
-	return next(DNumber.sum([current, 1]));
+	return next(DNumber.sum([accumulator, 1]));
 });
 
-// Résultat : 3. L'état circule dans next sans compteur externe mutable.
+// Résultat : 3. L'état circule dans l'accumulateur de la boucle.
 type _CheckReachedValue = DCommon.ExpectType<typeof reachedValue, number, "strict">;
 
 declare function readBatchSize(index: number): Promise<number>;
 
-const processedTotal = await DCommon.asyncLoop<number, number>(async({
+const processedTotal = await DCommon.asyncLoopAccumulator(0, async({
 	count,
-	previousOutput,
+	accumulator,
 	next,
 	exit,
 }) => {
-	const current = previousOutput ?? 0;
 	const size = await readBatchSize(count);
 
-	// La première taille nulle termine la lecture ; le dernier total devient le résultat.
+	// La première taille nulle termine la lecture ; exit retourne le total accumulé.
 	if (size === 0) {
-		return exit(current);
+		return exit(accumulator);
 	}
 
-	return next(DNumber.sum([current, size]));
+	return next(DNumber.sum([accumulator, size]));
 });
 
 type _CheckProcessedTotal = DCommon.ExpectType<typeof processedTotal, number, "strict">;
+
+const emitted = DArray.from(DGenerator.loop(({ count, next, exit }) => count === 3
+	? exit("done")
+	: next(count)));
+
+// DGenerator.loop émet les sorties de next puis celles de exit.
+type _CheckEmitted = DCommon.ExpectType<typeof emitted, readonly (number | "done")[], "strict">;
+
+const emittedWithAccumulator = DArray.from(
+	DGenerator.loopAccumulator(0, ({ accumulator, count, next, exit }) => count === 3
+		? exit(accumulator)
+		: next(accumulator + 1, accumulator)),
+);
+
+// Chaque sortie peut être produite au même moment que le nouvel accumulateur est choisi.
+type _CheckEmittedWithAccumulator = DCommon.ExpectType<typeof emittedWithAccumulator, readonly number[], "strict">;

package/skills/fundamental/references/iterations.md

@@ -13,7 +13,11 @@ Pour un autre itérable, utiliser `DGenerator.reduce`. `DGenerator.asyncReduce`
 
 ## Répéter jusqu'à une condition
 
-`DCommon.loop` fournit `count` depuis zéro et `previousOutput`, initialement `undefined`, puis égal au dernier `next`. Initialiser l'état au premier appel ; `exit` donne le résultat final. Les génériques décrivent sortie puis état intermédiaire. `DCommon.asyncLoop` attend les étapes asynchrones.
+`DCommon.loop` fournit `count` depuis zéro. `next()` continue et `exit(valeur)` retourne le résultat final. La donnée optionnelle de `next` n'est pas transmise au tour suivant ; utiliser `DCommon.loopAccumulator(initial, callback)` lorsque les tours doivent partager un état. Sa callback reçoit `accumulator`, `count`, `next(nouvelAccumulateur)` et `exit(résultat)`. `DCommon.asyncLoop` et `DCommon.asyncLoopAccumulator` offrent les mêmes comportements en attendant la callback asynchrone.
+
+`DGenerator.loop(callback)` produit une séquence : chaque `next(...valeurs)` émet les valeurs définies et poursuit la boucle ; `exit(...valeurs)` émet sa dernière séquence puis termine. La callback reçoit `count`, pas la valeur du tour précédent. `DGenerator.asyncLoop` attend les callbacks et résout les valeurs promises avant de les émettre.
+
+Les variantes `DGenerator.loopAccumulator(initial, callback)` et `DGenerator.asyncLoopAccumulator(initial, callback)` font circuler un accumulateur avec `next(nouvelAccumulateur, ...valeursÀÉmettre)`. `exit(...valeursÀÉmettre)` termine en émettant les dernières valeurs. Utiliser `DGenerator.loopAccumulatorFrom<Type>(valeur)` pour préserver un type d'accumulateur structuré ou une union.
 
 Conserver la condition avant le traitement d'un `while`, après celui d'un `do...while`. Pour une répétition par compteur, utiliser aussi `loop`, sans fabriquer un tableau.