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

package/docs/API/20-server/30-dataStructure/10-file.ts

@@ -0,0 +1,14 @@
+/**
+ * @title DSDataStructure.file
+ *
+ * Décrire une interface de fichier serveur.
+ */
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+
+declare const input: unknown;
+
+const structure = DSDataStructure.file([DSDataStructure.fileExist()]);
+const result = await structure.asyncDecode(DSDataStructure.codecsString, input);
+
+// Le codec construit une interface ; la contrainte inspecte le disque.
+// Le résultat distingue le décodage réussi de l’échec de validation.

package/docs/API/20-server/30-dataStructure/10-fileExist.ts

@@ -0,0 +1,27 @@
+/**
+ * @title DSDataStructure.fileExist
+ *
+ * Exiger que l’interface représente un fichier existant.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+import * as DSFile from "@duplojs/server/file";
+
+declare const input: unknown;
+
+const structure = DSDataStructure.file([DSDataStructure.fileExist()]);
+
+// Le codec transforme le chemin textuel en FileInterface. La contrainte
+// interroge ensuite le système de fichiers : utiliser asyncDecode.
+const result = await structure.asyncDecode(DSDataStructure.codecsString, input);
+
+if (DEither.isRight(result)) {
+	const file = DEither.unwrapRight(result);
+
+	// La validation a constaté l'existence au moment du contrôle ; le fichier
+	// peut avoir changé ou disparu avant cette lecture, qui peut encore échouer.
+	const readResult = await DSFile.readTextFile(file.path);
+} else {
+	// Le décodage du chemin ou le contrôle de la ressource a échoué.
+	const validationError = DEither.unwrapLeft(result);
+}

package/docs/API/20-server/30-dataStructure/10-folder.ts

@@ -0,0 +1,14 @@
+/**
+ * @title DSDataStructure.folder
+ *
+ * Décrire une interface de dossier serveur.
+ */
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+
+declare const input: unknown;
+
+const structure = DSDataStructure.folder([DSDataStructure.folderExist()]);
+const result = await structure.asyncDecode(DSDataStructure.codecsString, input);
+
+// Le codec construit une interface ; la contrainte inspecte le disque.
+// Le résultat distingue le décodage réussi de l’échec de validation.

package/docs/API/20-server/30-dataStructure/10-folderExist.ts

@@ -0,0 +1,14 @@
+/**
+ * @title DSDataStructure.folderExist
+ *
+ * Exiger que l’interface représente un dossier existant.
+ */
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+
+declare const input: unknown;
+
+const structure = DSDataStructure.folder([DSDataStructure.folderExist()]);
+const result = await structure.asyncDecode(DSDataStructure.codecsString, input);
+
+// La vérification asynchrone constate l’état du disque au moment du décodage.
+// Le résultat distingue le décodage réussi de l’échec de validation.

package/docs/API/20-server/30-dataStructure/10-mimeType.ts

@@ -0,0 +1,14 @@
+/**
+ * @title DSDataStructure.mimeType
+ *
+ * Contraindre le type MIME déduit de l’extension du fichier.
+ */
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+
+declare const input: unknown;
+
+const structure = DSDataStructure.file([DSDataStructure.mimeType("image/png")]);
+const result = await structure.asyncDecode(DSDataStructure.codecsString, input);
+
+// Le type MIME est déduit de l’extension, pas du contenu.
+// Le résultat distingue le décodage réussi de l’échec de validation.

package/docs/API/20-server/30-dataStructure/10-size.ts

@@ -0,0 +1,32 @@
+/**
+ * @title DSDataStructure.size
+ *
+ * Contraindre la taille en octets d’un fichier.
+ */
+import * as DEither from "@duplojs/lang/either";
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+import type * as DSFile from "@duplojs/server/file";
+
+declare const file: DSFile.FileInterface;
+
+const structure = DSDataStructure.file([
+	DSDataStructure.fileExist(),
+	DSDataStructure.size({
+		min: 1,
+		max: "1mb",
+	}),
+]);
+
+// La taille est lue dans les métadonnées : asyncCheck est nécessaire même
+// lorsque l'entrée est déjà une interface et ne nécessite pas de codec.
+const result = await structure.asyncCheck(file);
+
+if (DEither.isRight(result)) {
+	const checkedFile = DEither.unwrapRight(result);
+
+	// Les bornes sont vérifiées au moment du contrôle ; elles ne réservent pas
+	// le fichier et ne valident pas le contenu de ses octets.
+	const path = checkedFile.path;
+} else {
+	const validationError = DEither.unwrapLeft(result);
+}

package/docs/API/20-server/30-dataStructure/index.llms.md

@@ -0,0 +1,28 @@
+## DataStructure
+
+Décoder et valider les interfaces de fichiers et dossiers avec les contraintes serveur.
+
+### [DSDataStructure.file](10-file.ts)
+
+Décrire une interface de fichier serveur.
+ 
+### [DSDataStructure.fileExist](10-fileExist.ts)
+
+Exiger que l’interface représente un fichier existant.
+ 
+### [DSDataStructure.folder](10-folder.ts)
+
+Décrire une interface de dossier serveur.
+ 
+### [DSDataStructure.folderExist](10-folderExist.ts)
+
+Exiger que l’interface représente un dossier existant.
+ 
+### [DSDataStructure.mimeType](10-mimeType.ts)
+
+Contraindre le type MIME déduit de l’extension du fichier.
+ 
+### [DSDataStructure.size](10-size.ts)
+
+Contraindre la taille en octets d’un fichier.
+ 

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

@@ -0,0 +1,3 @@
+## DataStructure
+
+Décoder et valider les interfaces de fichiers et dossiers avec les contraintes serveur.

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

@@ -0,0 +1,39 @@
+/**
+ * @title DSCommand.create
+ *
+ * Construire une commande nommée à placer dans un arbre de commandes.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSCommand from "@duplojs/server/command";
+
+declare function inspect(source: string): Promise<void>;
+
+const inspectCommand = DSCommand.create(
+	"inspect",
+	{
+		description: "Inspect a resource",
+		subjects: [
+			DSCommand.createArgument(
+				"source",
+				DDataStructure.string(),
+			),
+		],
+	},
+	async({ args }) => {
+		await inspect(args.source);
+	},
+);
+
+const result = await DSCommand.exec(
+	{ subjects: [inspectCommand] },
+	() => {},
+);
+
+// La sous-commande sélectionnée exécute son callback sans exécuter celui du parent.
+
+// Exemple avec un fichier cli.ts exécuté par tsx :
+// tsx cli.ts inspect ./resources
+// « inspect » sélectionne la sous-commande, puis source reçoit ./resources.
+// Un tableau subjects contient des arguments OU des sous-commandes : ces
+// deux catégories ne peuvent pas être mélangées dans une même commande.
+// Les options du parent ne sont pas héritées par les sous-commandes.

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

@@ -0,0 +1,39 @@
+/**
+ * @title DSCommand.createArgument
+ *
+ * Déclarer un argument positionnel validé et transmis à une commande.
+ */
+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",
+	{
+		subjects: [
+			DSCommand.createArgument(
+				"source",
+				DDataStructure.string(),
+			),
+			DSCommand.createArgument(
+				"destination",
+				DDataStructure.string(),
+				{ optional: true },
+			),
+		],
+	},
+	({ args }) => {
+		// Les arguments facultatifs suivent les arguments obligatoires.
+		type _CheckArgs = DCommon.ExpectType<
+			typeof args,
+			{
+				readonly source: string;
+				readonly destination: string | undefined;
+			},
+			"strict"
+		>;
+	},
+);
+
+// Dans subjects, les arguments facultatifs suivent les obligatoires.
+// Le même tableau ne peut pas mélanger arguments et sous-commandes.

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

@@ -0,0 +1,36 @@
+/**
+ * @title DSCommand.createArrayOption
+ *
+ * Déclarer une option contenant plusieurs valeurs décodées.
+ */
+import * as DArray from "@duplojs/lang/array";
+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(
+	"inspect",
+	{
+		options: [
+			DSCommand.createArrayOption(
+				"include",
+				DDataStructure.string(),
+				{
+					required: true,
+					min: 1,
+				},
+			),
+		],
+	},
+	({ options }) => {
+		// La liste obligatoire et sa borne minimale garantissent un premier élément.
+		const first = DArray.first(options.include);
+		type _CheckFirst = DCommon.ExpectType<
+			typeof first,
+			string,
+			"strict"
+		>;
+	},
+);
+
+// Par défaut les éléments d'une valeur sont séparés par des virgules.

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

@@ -0,0 +1,28 @@
+/**
+ * @title DSCommand.createBooleanOption
+ *
+ * Déclarer un flag représentant la présence d’une option.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DSCommand from "@duplojs/server/command";
+
+const command = DSCommand.create(
+	"inspect",
+	{
+		options: [
+			DSCommand.createBooleanOption(
+				"verbose",
+				{ aliases: ["v"] },
+			),
+		],
+	},
+	({ options }) => {
+		type _CheckVerbose = DCommon.ExpectType<
+			typeof options.verbose,
+			boolean,
+			"strict"
+		>;
+	},
+);
+
+// Le flag vaut false si absent, true si présent ; il n'accepte pas de valeur.

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.7",
+  "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.7",
-    "@duplojs/server": "0.1.0-beta.7"
+    "@duplojs/lang": "0.1.0-beta.9",
+    "@duplojs/server": "0.1.0-beta.9"
   },
   "peerDependencies": {
-    "@duplojs/code-config": "0.1.0-beta.7",
-    "@duplojs/eslint": "0.1.0-beta.7",
-    "@duplojs/form": "0.1.0-beta.7",
-    "@duplojs/http": "0.1.0-beta.7",
-    "@duplojs/json-web-token": "0.1.0-beta.7",
-    "@duplojs/lang": "0.1.0-beta.7",
-    "@duplojs/playwright": "0.1.0-beta.7",
-    "@duplojs/server": "0.1.0-beta.7",
-    "@duplojs/tools": "0.1.0-beta.7"
+    "@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.7",
-    "@duplojs/eslint": "0.1.0-beta.7",
+    "@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",