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

package/docs/API/20-server/20-common/10-environmentVariableOrThrow.ts

@@ -0,0 +1,21 @@
+/**
+ * @title DSCommon.environmentVariableOrThrow
+ *
+ * Charger une configuration typée ou lever une erreur.
+ */
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSCommon from "@duplojs/server/common";
+
+// Adapté au démarrage lorsque la configuration est indispensable.
+const configuration = await DSCommon.environmentVariableOrThrow(
+	{
+		PORT: DDataStructure.number(),
+		HOST: DDataStructure.string(),
+	},
+	{ justRead: true },
+);
+
+// Une lecture ou un décodage en échec lève EnvironmentVariableError.
+
+// Voir 10-environmentVariable.ts pour les sources, la priorité, les codecs
+// et les effets de justRead ; cette variante applique les mêmes paramètres.

package/docs/API/20-server/20-common/10-exitProcess.ts

@@ -0,0 +1,9 @@
+/**
+ * @title DSCommon.exitProcess
+ *
+ * Terminer le processus avec un code de sortie.
+ */
+import * as DSCommon from "@duplojs/server/common";
+
+// À réserver à une frontière qui a décidé de terminer le programme.
+DSCommon.exitProcess(1);

package/docs/API/20-server/20-common/10-getCurrentDirectoryName.ts

@@ -0,0 +1,10 @@
+/**
+ * @title DSCommon.getCurrentDirectoryName
+ *
+ * Obtenir le dossier absolu du module fourni.
+ */
+import * as DSCommon from "@duplojs/server/common";
+
+const moduleDirectory = DSCommon.getCurrentDirectoryName(import.meta);
+
+// Ce chemin dépend du module, pas du répertoire de lancement.

package/docs/API/20-server/20-common/10-getCurrentWorkDirectory.ts

@@ -0,0 +1,10 @@
+/**
+ * @title DSCommon.getCurrentWorkDirectory
+ *
+ * Obtenir le répertoire de travail courant sous forme de résultat.
+ */
+import * as DSCommon from "@duplojs/server/common";
+
+const result = DSCommon.getCurrentWorkDirectory();
+
+// Le Right porte un chemin absolu ; le Left signale un échec du runtime.

package/docs/API/20-server/20-common/10-getCurrentWorkDirectoryOrThrow.ts

@@ -0,0 +1,10 @@
+/**
+ * @title DSCommon.getCurrentWorkDirectoryOrThrow
+ *
+ * Obtenir le répertoire de travail courant ou lever une erreur.
+ */
+import * as DSCommon from "@duplojs/server/common";
+
+const directory = DSCommon.getCurrentWorkDirectoryOrThrow();
+
+// Le chemin absolu dépend du dossier courant du processus.

package/docs/API/20-server/20-common/10-getProcessArguments.ts

@@ -0,0 +1,10 @@
+/**
+ * @title DSCommon.getProcessArguments
+ *
+ * Lire les arguments utilisateur du processus.
+ */
+import * as DSCommon from "@duplojs/server/common";
+
+const argumentsFromTerminal = DSCommon.getProcessArguments();
+
+// Les entrées de lancement du runtime ne figurent pas dans ce tableau.

package/docs/API/20-server/20-common/10-setCurrentWorkingDirectory.ts

@@ -0,0 +1,14 @@
+/**
+ * @title DSCommon.setCurrentWorkingDirectory
+ *
+ * Changer le répertoire de travail et retourner un résultat.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSCommon from "@duplojs/server/common";
+
+declare const directory: string & DPath.Absolute;
+
+const result = DSCommon.setCurrentWorkingDirectory(directory);
+
+// Un Left indique que le changement a échoué ; les chemins relatifs suivants
+// sont résolus depuis le nouveau dossier uniquement en cas de succès.

package/docs/API/20-server/20-common/10-setCurrentWorkingDirectoryOrThrow.ts

@@ -0,0 +1,12 @@
+/**
+ * @title DSCommon.setCurrentWorkingDirectoryOrThrow
+ *
+ * Changer le répertoire de travail ou lever une erreur.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSCommon from "@duplojs/server/common";
+
+declare const directory: string & DPath.Absolute;
+
+// Lève SetCurrentWorkingDirectoryError si le changement échoue.
+DSCommon.setCurrentWorkingDirectoryOrThrow(directory);

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

@@ -0,0 +1,40 @@
+## Common
+
+Accéder à la configuration, aux arguments et aux capacités du processus.
+
+### [DSCommon.environmentVariable](10-environmentVariable.ts)
+
+Charger et décoder une configuration issue de l’environnement.
+ 
+### [DSCommon.environmentVariableOrThrow](10-environmentVariableOrThrow.ts)
+
+Charger une configuration typée ou lever une erreur.
+ 
+### [DSCommon.exitProcess](10-exitProcess.ts)
+
+Terminer le processus avec un code de sortie.
+ 
+### [DSCommon.getCurrentDirectoryName](10-getCurrentDirectoryName.ts)
+
+Obtenir le dossier absolu du module fourni.
+ 
+### [DSCommon.getCurrentWorkDirectory](10-getCurrentWorkDirectory.ts)
+
+Obtenir le répertoire de travail courant sous forme de résultat.
+ 
+### [DSCommon.getCurrentWorkDirectoryOrThrow](10-getCurrentWorkDirectoryOrThrow.ts)
+
+Obtenir le répertoire de travail courant ou lever une erreur.
+ 
+### [DSCommon.getProcessArguments](10-getProcessArguments.ts)
+
+Lire les arguments utilisateur du processus.
+ 
+### [DSCommon.setCurrentWorkingDirectory](10-setCurrentWorkingDirectory.ts)
+
+Changer le répertoire de travail et retourner un résultat.
+ 
+### [DSCommon.setCurrentWorkingDirectoryOrThrow](10-setCurrentWorkingDirectoryOrThrow.ts)
+
+Changer le répertoire de travail ou lever une erreur.
+ 

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

@@ -0,0 +1,3 @@
+## Common
+
+Accéder à la configuration, aux arguments et aux capacités du processus.

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.