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

package/docs/concepts/03-client/20-form/30-layout.ts

@@ -0,0 +1,155 @@
+/**
+ * @title Composer avec les layouts
+ *
+ * Composition de la structure des données et des comportements d’un formulaire.
+ */
+import type * as DCommon from "@duplojs/lang/common";
+import type * as DEither from "@duplojs/lang/either";
+import { createForm, type DetailsError, useCheckLayout, useDisabledLayout, useMultiLayout, useRepeatLayout, useSectionLayout, useSlotLayout, useStepLayout, useUnionLayout } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import type * as DString from "@duplojs/lang/string";
+import { ref } from "vue";
+
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(
+	gridTemplates.useTemplates(),
+);
+
+// Les layouts de structure modifient directement la forme de `currentValue`
+// et la forme de la valeur retournée par `check`.
+// Un layout reçoit un ou plusieurs champs et produit un nouveau `FormField`.
+// Ici, les inputs sont composés dans des layouts, eux-mêmes imbriqués dans
+// `useMultiLayout`, puis `useSectionLayout` fournit le champ racine à `useForm`.
+const { check: checkStructureForm, component: StructureForm, currentValue: currentStructureValue } = useForm(
+	useSectionLayout(
+		useMultiLayout({
+			identity: useMultiLayout({
+				firstName: useTextInput({ label: "First name" }),
+				lastName: useTextInput({ label: "Last name" }),
+			}),
+			contacts: useRepeatLayout(
+				useTextInput({ label: "Email" }),
+				{
+					min: 1,
+					max: 3,
+				},
+			),
+			preferredContact: useUnionLayout(
+				[
+					["email", useTextInput({ label: "Email" })],
+					["phone", useTextInput({ label: "Phone" })],
+				],
+				{ defaultKind: "email" },
+			),
+			message: useSlotLayout(
+				"customMessage",
+				useTextareaInput({ label: "Message" }),
+			),
+		}),
+		{ title: "Profile" },
+	),
+);
+
+type _CheckContacts = DCommon.ExpectType<typeof currentStructureValue.value.contacts, [string, ...string[]], "strict">;
+type _CheckPreferredContactKind = DCommon.ExpectType<
+	typeof currentStructureValue.value.preferredContact.kind,
+	"email" | "phone",
+	"strict"
+>;
+void currentStructureValue;
+
+const checkedStructureValue = await checkStructureForm();
+type _CheckCheckedStructureValueLine96 = DCommon.ExpectType<
+	typeof checkedStructureValue,
+	DEither.Error<DetailsError> | DEither.Success<{
+		identity: {
+			firstName: string;
+			lastName: string;
+		};
+		contacts: [string, ...string[]];
+		preferredContact: {
+			kind: "email";
+			value: string;
+		} | {
+			kind: "phone";
+			value: string;
+		};
+		message: string | undefined;
+	}>,
+	"strict"
+>;
+
+void checkedStructureValue;
+void StructureForm;
+
+const hasCompany = ref(false);
+
+// Les layouts de contrôle changent surtout le flux du formulaire.
+// `step` impose une progression, `check` ajoute une validation autour d'un
+// champ existant, et `disabled` retire temporairement un champ du rendu et
+// de la valeur validée.
+const { check: checkFlowForm, component: FlowForm, currentValue: currentFlowValue } = useForm(
+	useStepLayout(
+		[
+			useMultiLayout({
+				fullName: useTextInput({ label: "Full name" }),
+				email: useCheckLayout(
+					useTextInput({ label: "Email" }),
+					{
+						dataStructure: DDataStructure.string([DDataStructure.email()]),
+					},
+				),
+			}),
+			useMultiLayout({
+				company: useDisabledLayout(
+					useTextInput({ label: "Company" }),
+					{
+						isDisabled: () => !hasCompany.value,
+					},
+				),
+				notes: useTextareaInput({ label: "Notes" }),
+			}),
+		],
+		{
+			errorMessageNotAtLastStep: "Complete all steps before submitting.",
+		},
+	),
+);
+
+type _CheckCurrentStep = DCommon.ExpectType<typeof currentFlowValue.value.currentStep, 0 | 1, "strict">;
+void currentFlowValue;
+
+const checkedFlowValue = await checkFlowForm();
+type _CheckCheckedFlowValueLine160 = DCommon.ExpectType<
+	typeof checkedFlowValue,
+	DEither.Error<DetailsError> | DEither.Success<readonly [
+		{
+			fullName: string;
+			email: string & DString.Email;
+		},
+		{
+			company: string | undefined;
+			notes: string;
+		},
+	]>,
+	"strict"
+>;

package/docs/concepts/03-client/20-form/40-template.ts

@@ -0,0 +1,94 @@
+/**
+ * @title Personnaliser les templates
+ *
+ * Personnalisation globale ou locale du rendu Vue des formulaires et de leurs champs.
+ */
+import { createForm, createTemplate, useMultiLayout, type InputTemplateProperties, type VueComponent } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import type * as DCommon from "@duplojs/lang/common";
+
+// Un template transforme les props système et les slots en interface Vue.
+// Il reste générique : la connaissance métier appartient au formulaire.
+// Remplacer le template change le rendu ; la structure des champs, leurs
+// validations et leurs valeurs restent définies par les inputs et les layouts.
+interface HeroInputTemplateProperties {
+	props: (
+		& InputTemplateProperties["props"]
+		& {
+			tone?: "default" | "accent";
+		}
+	);
+	slots: InputTemplateProperties["slots"];
+}
+
+declare const HeroInputTemplate: VueComponent<HeroInputTemplateProperties>;
+
+// La clé `"input"` indique quelle partie du rendu est remplacée.
+const useHeroInputTemplate = createTemplate(
+	"input",
+	HeroInputTemplate,
+	{
+		props: {
+			tone: "default",
+		},
+	},
+);
+
+// Les templates grid fournissent une base visuelle remplaçable globalement
+// ou localement.
+const gridTemplates = createGridTemplates({
+	repeat: {
+		addLabel: "Add another item",
+		removeLabel: "Remove this item",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		resetButton: templateFormResetButton,
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+// La surcharge globale s'applique à tous les champs concernés par ce formulaire.
+const useForm = createForm({
+	...gridTemplates.useTemplates(),
+	input: useHeroInputTemplate({ tone: "accent" }),
+});
+
+const { component: TheForm, currentValue } = useForm(
+	useMultiLayout({
+		title: useTextInput({
+			label: "Title",
+		}),
+		subtitle: useTextInput({
+			label: "Subtitle",
+			template: useHeroInputTemplate({ tone: "default" }),
+		}),
+		summary: useTextareaInput({
+			label: "Summary",
+			template: gridTemplates.useInputTemplate({
+				columns: 12,
+			}),
+		}),
+	}),
+);
+
+// `title` utilise le template global, `subtitle` le surcharge localement,
+// `summary` revient au template grid.
+//
+type _CheckCurrentValue = DCommon.ExpectType<
+	typeof currentValue.value,
+	{
+		title: string;
+		subtitle: string;
+		summary: string;
+	},
+	"strict"
+>;
+void currentValue;

package/docs/concepts/03-client/20-form/50-integration.md

@@ -0,0 +1,11 @@
+## Intégrer un formulaire dans une page Vue
+
+Séparer la logique d'un formulaire de son rendu dans une page Vue.
+
+---
+
+Une séparation recommandée consiste à construire le formulaire et à regrouper ses opérations dans un composable. La page consomme son interface et reste centrée sur la présentation ; Form n'impose pas cette organisation.
+
+Dans [usePostModeration.ts](./examples/postModeration/usePostModeration.ts), le composable configure les champs, choisit la variante, valide la soumission et libère le formulaire à la fin du scope Vue. Il expose le composant `ModerationForm` et les seuls états et actions utiles à la page. En cas de validation réussie, il utilise la valeur validée ; les erreurs restent affichées par les templates du formulaire.
+
+[ThePage.vue](./examples/postModeration/ThePage.vue) monte ce composant, place le bouton de soumission dans son slot par défaut et relie son événement `submit` à l'opération du composable. Les boutons de décision illustrent le changement de variante depuis l'interface.

package/docs/concepts/03-client/20-form/examples/postModeration/ThePage.vue

@@ -0,0 +1,32 @@
+<script setup lang="ts">
+import { PrimaryButton, OutlineButton, DestructiveButton } from "@duplojs/form/vueDesignSystem";
+import { usePostModeration } from "./usePostModeration";
+
+const { ModerationForm, selectedDecision, submitted, selectApproval, selectRejection, submit } = usePostModeration();
+</script>
+
+<template>
+	<section>
+		<h1>Moderate post</h1>
+
+		<OutlineButton @click="selectApproval">
+			Approve
+		</OutlineButton>
+
+		<DestructiveButton @click="selectRejection">
+			Reject
+		</DestructiveButton>
+
+		<p>Selected decision: {{ selectedDecision }}</p>
+
+		<ModerationForm @submit="submit">
+			<PrimaryButton type="submit">
+				Submit decision
+			</PrimaryButton>
+		</ModerationForm>
+
+		<p v-if="submitted">
+			{{ submitted }}
+		</p>
+	</section>
+</template>

package/docs/concepts/03-client/20-form/examples/postModeration/usePostModeration.ts

@@ -0,0 +1,80 @@
+import { createForm, useMultiLayout, useUnionLayout } from "@duplojs/form/vue";
+import { templateFormAddButton, templateFormNextButton, templateFormPreviousButton, templateFormRemoveButton, templateFormResetButton, templateFormSelect, useTextareaInput, useTextInput } from "@duplojs/form/vueDesignSystem";
+import { createGridTemplates } from "@duplojs/form/vueGrid";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+import { computed, onScopeDispose, ref } from "vue";
+
+const templates = createGridTemplates({
+	repeat: {
+		addLabel: "Add",
+		removeLabel: "Remove",
+		addButton: templateFormAddButton,
+		removeButton: templateFormRemoveButton,
+		resetButton: templateFormResetButton,
+	},
+	step: {
+		nextLabel: "Continue",
+		previousLabel: "Back",
+		nextButton: templateFormNextButton,
+		previousButton: templateFormPreviousButton,
+		resetButton: templateFormResetButton,
+	},
+	union: { selectInputKind: templateFormSelect },
+});
+
+const useForm = createForm(templates.useTemplates());
+
+export function usePostModeration() {
+	const { component: ModerationForm, currentValue, check, dispose } = useForm(
+		useUnionLayout(
+			[
+				["approve", useTextInput({ label: "Public note" })],
+				[
+					"reject",
+					useMultiLayout({
+						reason: useTextareaInput({
+							label: "Reason for rejection",
+							dataStructure: DDataStructure.string([DDataStructure.minCharacters(1)]),
+						}),
+					}),
+				],
+			],
+			{ defaultKind: "approve" },
+		),
+	);
+	const selectedDecision = computed(() => currentValue.value.kind);
+	const submitted = ref("");
+
+	function selectApproval() {
+		currentValue.value.updateKind("approve");
+	}
+
+	function selectRejection() {
+		currentValue.value.updateKind("reject");
+	}
+
+	async function submit() {
+		submitted.value = "";
+		const result = await check();
+
+		if (DEither.isRight(result)) {
+			const decision = DEither.unwrapRight(result);
+
+			submitted.value = decision.kind === "approve"
+				? `Approved: ${decision.value}`
+				: `Rejected: ${decision.value.reason}`;
+		}
+	}
+
+	onScopeDispose(dispose);
+
+	return {
+		ModerationForm,
+		selectedDecision,
+		submitted,
+		selectApproval,
+		selectRejection,
+		submit,
+	};
+}

package/docs/concepts/03-client/20-form/index.md

@@ -0,0 +1,3 @@
+## Form
+
+Création et gestion de formulaires typés pour les interfaces utilisateur.

package/docs/concepts/03-client/index.md

@@ -0,0 +1 @@
+# Client

package/docs/concepts/04-tests/01-unit/10-either.ts

@@ -0,0 +1,136 @@
+/**
+ * @title Tester un résultat Either
+ *
+ * Vérification des branches, des valeurs et du typage d’un contrat Either.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DEither from "@duplojs/lang/either";
+
+// Dans les tests du monorepo, Vitest expose ces globals directement.
+// Ces déclarations rendent uniquement l'exemple typable dans la documentation d'AgentKit.
+declare const describe: (title: string, body: () => void) => void;
+declare const it: (title: string, body: () => void | Promise<void>) => void;
+declare const expect: (value: unknown) => {
+	toBe(expected: unknown): void;
+	toStrictEqual(expected: unknown): void;
+};
+
+interface User {
+	id: number;
+	email: string;
+}
+
+declare function findUserByEmail(
+	email: string,
+): (
+	| DEither.Result<"user.found", User>
+	| DEither.Left<"user.notfound", string>
+	| DEither.Error<Error>
+);
+
+// L'unwrap exprime la branche attendue avant l'assertion sur la donnée.
+// `unwrapByInformationOrThrow` sélectionne l’information visée et extrait sa
+// valeur. Une information différente provoque une exception et fait échouer le test.
+// L’assertion vérifie ensuite la donnée ; `ExpectType` vérifie son type à la compilation.
+describe("findUserByEmail", () => {
+	it("returns the found user", () => {
+		const result = findUserByEmail("jane@duplo.dev");
+
+		const user = DEither.unwrapByInformationOrThrow(
+			result,
+			"user.found",
+		);
+
+		expect(user).toStrictEqual({
+			id: 1,
+			email: "jane@duplo.dev",
+		});
+
+		type _CheckUser = DCommon.ExpectType<
+			typeof user,
+			User,
+			"strict"
+		>;
+	});
+
+	it("returns the not found email", () => {
+		const result = findUserByEmail("missing@duplo.dev");
+
+		const email = DEither.unwrapByInformationOrThrow(
+			result,
+			"user.notfound",
+		);
+
+		expect(email).toBe("missing@duplo.dev");
+	});
+});
+
+// La sélection rend explicites les branches acceptées par ce test.
+// `unwrapSelectionOrThrow` lève aussi une exception si le résultat appartient
+// à une branche exclue, ici `error`.
+describe("findUserByEmail selection", () => {
+	it("accepts only the business results handled by this test", () => {
+		const result = findUserByEmail("jane@duplo.dev");
+
+		const value = DEither.unwrapSelectionOrThrow(
+			result,
+			{
+				"user.found": true,
+				"user.notfound": true,
+				error: false,
+			},
+		);
+
+		type _CheckValue = DCommon.ExpectType<
+			typeof value,
+			User | string,
+			"strict"
+		>;
+
+		if (typeof value === "string") {
+			expect(value).toBe("jane@duplo.dev");
+		} else {
+			expect(value).toStrictEqual({
+				id: 1,
+				email: "jane@duplo.dev",
+			});
+		}
+	});
+});
+
+// `DEither.expect` matérialise dans le type qu'une valeur est déjà un `Either`.
+describe("DEither.expect", () => {
+	it("keeps the exact either type", () => {
+		const input = DEither.success(42);
+		const result = DEither.expect(input);
+
+		expect(result).toBe(input);
+
+		type _CheckResult = DCommon.ExpectType<
+			typeof result,
+			DEither.Success<42>,
+			"strict"
+		>;
+
+		// @ts-expect-error input must be an Either
+		DEither.expect("plain value");
+	});
+});
+
+// Tester une API curifiée dans son contexte réel conserve l'inférence utile.
+describe("curried Either helpers", () => {
+	it("preserves inference in a pipe", () => {
+		const result = DCommon.pipe(
+			findUserByEmail("jane@duplo.dev"),
+			DEither.unwrapByInformationOrThrow("user.found"),
+		);
+
+		expect(result.email).toBe("jane@duplo.dev");
+
+		type _CheckResult = DCommon.ExpectType<
+			typeof result,
+			User,
+			"strict"
+		>;
+	});
+});

package/docs/concepts/04-tests/01-unit/20-server-mocking.ts

@@ -0,0 +1,53 @@
+/**
+ * @title Remplacer les implémentations serveur
+ *
+ * Contrôle de l'environnement et des fonctions serveur pour isoler les tests.
+ */
+import * as DEither from "@duplojs/lang/either";
+// Ces deux outils sont des exports directs du package, sans sous-export dédié.
+import { TESTImplementation, setEnvironment } from "@duplojs/server";
+import * as DSCommand from "@duplojs/server/command";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// Pour les fonctions serveur exposées via `implementFunction`, privilégier
+// ce mécanisme aux mocks de modules ou d'imports et aux spies sur les exports.
+// `setEnvironment("TEST")` sélectionne les implémentations enregistrées avec
+// `TESTImplementation.set` ; leur signature est vérifiée par TypeScript.
+// Chaque fonction serveur effectivement appelée, même indirectement, doit être
+// enregistrée : une implémentation absente lève une erreur, sans repli natif.
+describe("command with controlled server dependencies", () => {
+	afterEach(() => {
+		// Le registre et l'environnement sont partagés. Nettoyer même si le test
+		// échoue ; ne pas exécuter ces tests concurremment.
+		TESTImplementation.clear();
+		// Cette suite Vitest tourne sous Node. Adapter l'environnement rétabli
+		// à celui attendu par la suite lorsqu'elle utilise Bun ou Deno.
+		setEnvironment("NODE");
+	});
+
+	it("reads the injected process arguments", async() => {
+		setEnvironment("TEST");
+
+		// `vi.fn` reste utile pour observer les appels de l'implémentation injectée.
+		const getProcessArgumentsSpy = vi.fn(() => ["--verbose"]);
+		TESTImplementation.set("getProcessArguments", getProcessArgumentsSpy);
+		const executeSpy = vi.fn(() => undefined);
+
+		const result = await DSCommand.exec(
+			{
+				displayName: "tool",
+				options: [DSCommand.createBooleanOption("verbose")],
+			},
+			executeSpy,
+		);
+
+		DEither.unwrapByInformationOrThrow(result, "ok");
+		expect(getProcessArgumentsSpy).toHaveBeenCalledTimes(1);
+		expect(executeSpy).toHaveBeenCalledWith({
+			options: { verbose: true },
+		});
+	});
+});
+
+// Les autres dépendances sans ce mécanisme peuvent toujours être observées
+// ou remplacées avec les outils de mock habituels du runner de tests.

package/docs/concepts/04-tests/01-unit/index.md

@@ -0,0 +1,3 @@
+## Tests unitaires
+
+Vérification du comportement et du typage des unités de code.

package/docs/concepts/04-tests/02-e2e/10-init.ts

@@ -0,0 +1,80 @@
+/**
+ * @title Initialiser le client E2E
+ *
+ * Configuration de l’environnement de test et intégration du site aux fixtures Playwright.
+ */
+import * as DCommon from "@duplojs/lang/common";
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DSCommon from "@duplojs/server/common";
+import { createWebsite, type Website } from "@duplojs/playwright";
+import test, { defineConfig, devices } from "playwright/test";
+
+const envs = await DSCommon.environmentVariableOrThrow(
+	{
+		BASE_URL: DDataStructure.string([DDataStructure.url()]),
+		CI: DDataStructure.boolean(),
+		RETRIES: DDataStructure.number([DDataStructure.integer()]),
+		WORKERS: DDataStructure.number([DDataStructure.integer()]),
+	},
+	{
+		justRead: true,
+		includedEnvironmentFiles: [DCommon.infer(".env")],
+	},
+);
+
+// La configuration reste une configuration Playwright normale.
+export default defineConfig({
+	testDir: "./tests",
+	fullyParallel: true,
+	forbidOnly: envs.CI,
+	retries: envs.RETRIES,
+	workers: envs.WORKERS,
+	reporter: [
+		[
+			"html",
+			{
+				open: "never",
+				outputFolder: "playwright-report",
+			},
+		],
+		["list"],
+	],
+	use: {
+		headless: true,
+		trace: "retain-on-failure",
+		screenshot: "only-on-failure",
+	},
+	projects: [
+		{
+			name: "chromium",
+			use: { ...devices["Desktop Chrome"] },
+		},
+	],
+});
+
+interface TestFixtures {
+	website: Website;
+}
+
+// La fixture ajoute `website` aux tests et centralise le contexte du site.
+// Elle crée un `Website` par test à partir de la `page` et du `BrowserContext`
+// fournis par Playwright. `baseUrl` fixe l’adresse du site ; le hook attend la
+// fin du chargement réseau après chaque navigation.
+export const testClient = test.extend<TestFixtures>({
+	async website({ page, context }, use) {
+		const website = createWebsite({
+			playwrightPage: page,
+			playwrightBrowserContext: context,
+			envConfig: {
+				baseUrl: envs.BASE_URL,
+			},
+			hooks: {
+				async afterNavigateOnPage() {
+					await page.waitForLoadState("networkidle");
+				},
+			},
+		});
+
+		await use(website);
+	},
+});