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

package/docs/API/20-server/10-file/index.llms.md

@@ -0,0 +1,144 @@
+## File
+
+Lire et modifier les ressources du système de fichiers, leurs chemins et leurs métadonnées.
+
+### [DSFile.appendFile](10-appendFile.ts)
+
+Ajouter des octets à un fichier.
+ 
+### [DSFile.appendTextFile](10-appendTextFile.ts)
+
+Ajouter du texte à un fichier.
+ 
+### [DSFile.copy](10-copy.ts)
+
+Copier une ressource, récursivement pour un dossier.
+ 
+### [DSFile.createEntryInterface](10-createEntryInterface.ts)
+
+Inspecter une entrée et construire son interface adaptée.
+ 
+### [DSFile.createFileInterface](10-createFileInterface.ts)
+
+Construire une référence de fichier sans accès au disque.
+ 
+### [DSFile.createFolderInterface](10-createFolderInterface.ts)
+
+Construire une référence de dossier sans accès au disque.
+ 
+### [DSFile.createUnknownEntryInterface](10-createUnknownEntryInterface.ts)
+
+Construire une référence d’entrée de type inconnu sans accès au disque.
+ 
+### [DSFile.ensureDirectory](10-ensureDirectory.ts)
+
+Créer un dossier et ses parents si nécessaire.
+ 
+### [DSFile.ensureFile](10-ensureFile.ts)
+
+Créer un fichier absent sans tronquer un fichier existant.
+ 
+### [DSFile.exists](10-exists.ts)
+
+Vérifier l’accès à une entrée du système de fichiers.
+ 
+### [DSFile.link](10-link.ts)
+
+Créer un lien physique vers une entrée existante.
+ 
+### [DSFile.linkStat](10-linkStat.ts)
+
+Lire les métadonnées d’un lien lui-même.
+ 
+### [DSFile.makeDirectory](10-makeDirectory.ts)
+
+Créer un dossier, éventuellement avec ses parents.
+ 
+### [DSFile.makeTemporaryDirectory](10-makeTemporaryDirectory.ts)
+
+Créer un dossier temporaire avec un préfixe.
+ 
+### [DSFile.makeTemporaryFile](10-makeTemporaryFile.ts)
+
+Créer un fichier temporaire avec préfixe et suffixe.
+ 
+### [DSFile.move](10-move.ts)
+
+Déplacer une ressource vers un chemin de destination.
+ 
+### [DSFile.readDirectory](10-readDirectory.ts)
+
+Lister les chemins d’un dossier avec récursivité et résolution absolue optionnelles.
+ 
+### [DSFile.readFile](10-readFile.ts)
+
+Lire les octets d’un fichier.
+ 
+### [DSFile.readJsonFile](10-readJsonFile.ts)
+
+Lire et analyser un fichier JSON.
+ 
+### [DSFile.readLink](10-readLink.ts)
+
+Lire la cible d’un lien symbolique.
+ 
+### [DSFile.readTextFile](10-readTextFile.ts)
+
+Lire le contenu UTF-8 d'un fichier et distinguer les erreurs d'accès.
+ 
+### [DSFile.realPath](10-realPath.ts)
+
+Résoudre le chemin réel d’une entrée.
+ 
+### [DSFile.relocate](10-relocate.ts)
+
+Déplacer une entrée dans un autre dossier en conservant son nom.
+ 
+### [DSFile.remove](10-remove.ts)
+
+Supprimer une entrée, éventuellement récursivement.
+ 
+### [DSFile.rename](10-rename.ts)
+
+Renommer une entrée dans son dossier parent.
+ 
+### [DSFile.setMode](10-setMode.ts)
+
+Modifier les permissions d’une entrée.
+ 
+### [DSFile.setOwner](10-setOwner.ts)
+
+Modifier le propriétaire et le groupe d’une entrée.
+ 
+### [DSFile.setTime](10-setTime.ts)
+
+Modifier les dates d’accès et de modification d’une entrée.
+ 
+### [DSFile.stat](10-stat.ts)
+
+Lire les métadonnées d’une entrée.
+ 
+### [DSFile.symlink](10-symlink.ts)
+
+Créer un lien symbolique vers une cible.
+ 
+### [DSFile.truncate](10-truncate.ts)
+
+Tronquer ou étendre un fichier à une taille en octets.
+ 
+### [DSFile.walkDirectory](10-walkDirectory.ts)
+
+Parcourir les entrées d’un dossier sous forme d’interfaces.
+ 
+### [DSFile.writeFile](10-writeFile.ts)
+
+Écrire des octets dans un fichier.
+ 
+### [DSFile.writeJsonFile](10-writeJsonFile.ts)
+
+Sérialiser une valeur en JSON et l’écrire dans un fichier.
+ 
+### [DSFile.writeTextFile](10-writeTextFile.ts)
+
+Écrire du texte dans un fichier.
+ 

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

@@ -0,0 +1,3 @@
+## File
+
+Lire et modifier les ressources du système de fichiers, leurs chemins et leurs métadonnées.

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

@@ -0,0 +1,57 @@
+/**
+ * @title DSCommon.environmentVariable
+ *
+ * Charger et décoder une configuration issue de l’environnement.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import * as DSCommon from "@duplojs/server/common";
+import * as DSDataStructure from "@duplojs/server/dataStructure";
+
+const result = await DSCommon.environmentVariable(
+	{
+		PORT: DDataStructure.number(),
+		HOST: DDataStructure.string(),
+		INPUT: DSDataStructure.file(),
+	},
+	{
+		// Les fichiers sont lus dans cet ordre. Une erreur de lecture est renvoyée.
+		includedEnvironmentFiles: [
+			DPath.declarePath(".env"),
+			DPath.declarePath(".env.local"),
+		],
+		// false : la première source gagne, en commençant par le runtime.
+		// true : les sources suivantes remplacent les précédentes.
+		override: false,
+		// true : ne pas répercuter les valeurs chargées sur l'environnement.
+		// Par défaut, l'environnement est mis à jour après validation réussie.
+		justRead: true,
+		// Les codecs serveur décodent aussi INPUT en interface de fichier.
+		codecs: DSDataStructure.codecsString,
+	},
+);
+
+if (DEither.isRight(result)) {
+	const configuration = DEither.unwrapRight(result);
+
+	type _CheckPort = DCommon.ExpectType<
+		typeof configuration.PORT,
+		number,
+		"strict"
+	>;
+
+	// INPUT est une interface ; le codec seul ne vérifie pas l'existence.
+	const inputPath = configuration.INPUT.path;
+} else if (DEither.hasInformation(result, "decode-error")) {
+	// Une variable absente ou invalide échoue au décodage de la shape.
+	const validationError = DEither.unwrapLeft(result);
+} else {
+	// Un fichier d'environnement demandé n'a pas pu être lu : l'erreur
+	// conserve les catégories de readTextFile (absence, permission, etc.).
+	const readError = DEither.unwrapLeft(result);
+}
+
+// Les références comme ${HOST} sont développées après fusion des sources,
+// avant le décodage. La valeur finale dépend de l'environnement courant.

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.