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

package/docs/API/20-server/10-file/10-setMode.ts

@@ -0,0 +1,37 @@
+/**
+ * @title DSFile.setMode
+ *
+ * Modifier les permissions d’une entrée.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.setMode(path, 0o640);
+
+// Le résultat peut notamment signaler un refus d’accès.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-set-mode-not-found": () => "missing",
+			"file-system-set-mode-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-set-mode-not-found
+// file-system-set-mode-permission-denied
+// file-system-set-mode-not-directory
+// file-system-set-mode-read-only
+// file-system-set-mode-invalid-argument
+// file-system-set-mode-error

package/docs/API/20-server/10-file/10-setOwner.ts

@@ -0,0 +1,38 @@
+/**
+ * @title DSFile.setOwner
+ *
+ * Modifier le propriétaire et le groupe d’une entrée.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+declare const owner: DSFile.SetOwnerParams;
+
+const result = await DSFile.setOwner(path, owner);
+
+// La disponibilité et les permissions dépendent de l’environnement.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-set-owner-not-found": () => "missing",
+			"file-system-set-owner-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-set-owner-not-found
+// file-system-set-owner-permission-denied
+// file-system-set-owner-not-directory
+// file-system-set-owner-read-only
+// file-system-set-owner-invalid-argument
+// file-system-set-owner-error

package/docs/API/20-server/10-file/10-setTime.ts

@@ -0,0 +1,42 @@
+/**
+ * @title DSFile.setTime
+ *
+ * Modifier les dates d’accès et de modification d’une entrée.
+ */
+import type * as DChrono from "@duplojs/lang/chrono";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+declare const date: DChrono.TheDate;
+
+const result = await DSFile.setTime(path, {
+	accessTime: date,
+	modifiedTime: date,
+});
+
+// Le résultat indique si les métadonnées ont été modifiées.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-set-time-not-found": () => "missing",
+			"file-system-set-time-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-set-time-not-found
+// file-system-set-time-permission-denied
+// file-system-set-time-not-directory
+// file-system-set-time-read-only
+// file-system-set-time-invalid-argument
+// file-system-set-time-error

package/docs/API/20-server/10-file/10-stat.ts

@@ -0,0 +1,37 @@
+/**
+ * @title DSFile.stat
+ *
+ * Lire les métadonnées d’une entrée.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.stat(path);
+
+// Le Right décrit notamment la nature, la taille et les dates de l’entrée.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-stat-not-found": () => "missing",
+			"file-system-stat-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-stat-not-found
+// file-system-stat-permission-denied
+// file-system-stat-not-directory
+// file-system-stat-too-many-open-files
+// file-system-stat-busy
+// file-system-stat-error

package/docs/API/20-server/10-file/10-symlink.ts

@@ -0,0 +1,49 @@
+/**
+ * @title DSFile.symlink
+ *
+ * Créer un lien symbolique vers une cible.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const source: string & DPath.Path;
+declare const destination: string & DPath.Path;
+
+// Appel direct
+const result = await DSFile.symlink(source, destination);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	source,
+	DSFile.symlink(destination),
+);
+
+// Les résultats dépendent de l'état du système de fichiers et peuvent échouer.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-symlink-not-found": () => "missing",
+			"file-system-symlink-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-symlink-not-found
+// file-system-symlink-permission-denied
+// file-system-symlink-already-exists
+// file-system-symlink-not-directory
+// file-system-symlink-read-only
+// file-system-symlink-invalid-argument
+// file-system-symlink-too-many-open-files
+// file-system-symlink-busy
+// file-system-symlink-error

package/docs/API/20-server/10-file/10-truncate.ts

@@ -0,0 +1,41 @@
+/**
+ * @title DSFile.truncate
+ *
+ * Tronquer ou étendre un fichier à une taille en octets.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.truncate(path, 128);
+
+// Le résultat indique si la modification a réussi.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-truncate-not-found": () => "missing",
+			"file-system-truncate-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-truncate-not-found
+// file-system-truncate-permission-denied
+// file-system-truncate-is-directory
+// file-system-truncate-not-directory
+// file-system-truncate-no-space
+// file-system-truncate-read-only
+// file-system-truncate-invalid-argument
+// file-system-truncate-too-many-open-files
+// file-system-truncate-busy
+// file-system-truncate-error

package/docs/API/20-server/10-file/10-walkDirectory.ts

@@ -0,0 +1,75 @@
+/**
+ * @title DSFile.walkDirectory
+ *
+ * Parcourir les entrées d’un dossier sous forme d’interfaces.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DGenerator from "@duplojs/lang/generator";
+import type * as DPath from "@duplojs/lang/path";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+import * as DSFile from "@duplojs/server/file";
+
+declare const directory: string & DPath.Path;
+
+const result = await DSFile.walkDirectory(
+	directory,
+	{ recursive: true },
+);
+
+if (DEither.isRight(result)) {
+	const entries = DEither.unwrapRight(result);
+
+	// Le générateur produit des interfaces munies d'un chemin absolu.
+	// Le test du kind permet d'utiliser les opérations propres aux fichiers.
+	const descriptions = DArray.from(
+		DGenerator.map(
+			entries,
+			(entry) => {
+				type _CheckPath = DCommon.ExpectType<
+					typeof entry.path,
+					string & DPath.Path & DPath.Absolute,
+					"strict"
+				>;
+
+				if (DSFile.isFileInterface(entry)) {
+					return {
+						path: entry.path,
+						mimeType: entry.getMimeType(),
+					};
+				}
+
+				if (DSFile.isFolderInterface(entry)) {
+					return {
+						path: entry.path,
+						name: entry.getName(),
+					};
+				}
+
+				// Une entrée inconnue conserve notamment path et stat().
+				return { path: entry.path };
+			},
+		),
+	);
+} else {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-walk-directory-not-found": () => "missing-directory",
+			"file-system-walk-directory-permission-denied": () => "access-denied",
+			"file-system-walk-directory-not-directory": () => "not-a-directory",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-walk-directory-not-found
+// file-system-walk-directory-permission-denied
+// file-system-walk-directory-not-directory
+// file-system-walk-directory-too-many-open-files
+// file-system-walk-directory-busy
+// file-system-walk-directory-error

package/docs/API/20-server/10-file/10-writeFile.ts

@@ -0,0 +1,50 @@
+/**
+ * @title DSFile.writeFile
+ *
+ * Écrire des octets dans un fichier.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+declare const bytes: Uint8Array;
+
+// Appel direct
+const result = await DSFile.writeFile(path, bytes);
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	path,
+	DSFile.writeFile(bytes),
+);
+
+// Chaque résultat indique la réussite ou l'échec de l'écriture.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-write-file-not-found": () => "missing",
+			"file-system-write-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-write-file-not-found
+// file-system-write-file-permission-denied
+// file-system-write-file-is-directory
+// file-system-write-file-not-directory
+// file-system-write-file-no-space
+// file-system-write-file-read-only
+// file-system-write-file-invalid-argument
+// file-system-write-file-too-many-open-files
+// file-system-write-file-busy
+// file-system-write-file-error

package/docs/API/20-server/10-file/10-writeJsonFile.ts

@@ -0,0 +1,41 @@
+/**
+ * @title DSFile.writeJsonFile
+ *
+ * Sérialiser une valeur en JSON et l’écrire dans un fichier.
+ */
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+const result = await DSFile.writeJsonFile(path, { enabled: true });
+
+// Le résultat peut signaler une erreur de sérialisation ou d’écriture.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-write-json-file-not-found": () => "missing",
+			"file-system-write-json-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-write-json-file-not-found
+// file-system-write-json-file-permission-denied
+// file-system-write-json-file-is-directory
+// file-system-write-json-file-not-directory
+// file-system-write-json-file-no-space
+// file-system-write-json-file-read-only
+// file-system-write-json-file-invalid-argument
+// file-system-write-json-file-too-many-open-files
+// file-system-write-json-file-busy
+// file-system-write-json-file-error

package/docs/API/20-server/10-file/10-writeTextFile.ts

@@ -0,0 +1,49 @@
+/**
+ * @title DSFile.writeTextFile
+ *
+ * Écrire du texte dans un fichier.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import type * as DPath from "@duplojs/lang/path";
+import * as DSFile from "@duplojs/server/file";
+import * as DEither from "@duplojs/lang/either";
+import * as DPattern from "@duplojs/lang/pattern";
+
+declare const path: string & DPath.Path;
+
+// Appel direct
+const result = await DSFile.writeTextFile(path, "configuration");
+
+// Forme curifiée
+const pipedResult = await DCommon.pipe(
+	path,
+	DSFile.writeTextFile("configuration"),
+);
+
+// Chaque résultat indique la réussite ou l'échec de l'écriture.
+
+// L’information du Left identifie l’opération ; sa valeur précise la cause.
+if (DEither.isLeft(result)) {
+	const error = DEither.unwrapLeft(result);
+
+	const diagnosis = DPattern.matchWithErrorOtherwise(
+		error,
+		{
+			"file-system-write-text-file-not-found": () => "missing",
+			"file-system-write-text-file-permission-denied": () => "access-denied",
+		},
+		(otherError) => otherError,
+	);
+}
+
+// Identifiants d’erreur déclarés pour cette opération :
+// file-system-write-text-file-not-found
+// file-system-write-text-file-permission-denied
+// file-system-write-text-file-is-directory
+// file-system-write-text-file-not-directory
+// file-system-write-text-file-no-space
+// file-system-write-text-file-read-only
+// file-system-write-text-file-invalid-argument
+// file-system-write-text-file-too-many-open-files
+// file-system-write-text-file-busy
+// file-system-write-text-file-error

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.