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

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

@@ -0,0 +1,160 @@
+/**
+ * @title Composer avec les layouts
+ *
+ * Composition de la structure des données et des comportements d’un formulaire.
+ */
+import { createForm, 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 { 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" },
+	),
+);
+
+// Ref<{
+//   identity: {
+//     firstName: string;
+//     lastName: string;
+//   };
+//   contacts: [string, ...string[]];
+//   preferredContact: {
+//     readonly kind: "email" | "phone";
+//     value: string;
+//     updateKind(kind: "email" | "phone", value?: string): void;
+//   };
+//   message: string;
+// }>
+void currentStructureValue;
+
+// DEither.Error<DetailsError> | DEither.Success<{
+//   identity: {
+//     firstName: string;
+//     lastName: string;
+//   };
+//   contacts: [string, ...string[]];
+//   preferredContact: {
+//     kind: "email" | "phone";
+//     value: string;
+//   };
+//   message: string | undefined;
+// }>
+const checkedStructureValue = await checkStructureForm();
+
+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.",
+		},
+	),
+);
+
+// Ref<{
+//   currentStep: 0 | 1;
+//   steps: [
+//     {
+//       fullName: string;
+//       email: string;
+//     },
+//     {
+//       company: string;
+//       notes: string;
+//     },
+//   ];
+// }>
+void currentFlowValue;
+
+// DEither.Error<DetailsError> | DEither.Success<[
+//   {
+//     fullName: string;
+//     email: string & Email;
+//   },
+//   {
+//     company: string | undefined;
+//     notes: string;
+//   },
+// ]>
+const checkedFlowValue = await checkFlowForm();

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

@@ -0,0 +1,89 @@
+/**
+ * @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";
+
+// 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.
+//
+// Ref<{
+//   title: string;
+//   subtitle: string;
+//   summary: string;
+// }>
+void currentValue;

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);
+	},
+});

package/docs/concepts/04-tests/02-e2e/20-architecture.ts

@@ -0,0 +1,76 @@
+/**
+ * @title Architecturer une suite E2E
+ *
+ * Organisation d’une suite E2E selon les pages et les composants du site testé.
+ */
+import { createComponent, createPage } from "@duplojs/playwright";
+
+// `Website` représente l’application et son contexte global, `Page` un écran
+// navigable et `Component` une zone réutilisable de l’interface.
+// Les locators sont déclarés dans ces objets ; les specs utilisent leurs
+// éléments et leurs méthodes sans répéter les sélecteurs.
+//
+// tests/
+//   website.ts
+//   pages/
+//      home.page.ts
+//      search.page.ts
+//  components/
+//      newsletter.component.ts
+//  specs/
+//      home.spec.ts
+
+// Un composant declare son element racine et les elements utiles au test.
+export const newsletterComponent = createComponent(
+	"newsletter",
+	{
+		getMainElement({ body }) {
+			return body.locator("[data-newsletter]");
+		},
+		getElements({ mainElement }) {
+			return {
+				emailInput: mainElement.locator("input[type='email']"),
+				submitButton: mainElement.locator("button[type='submit']"),
+				feedback: mainElement.locator("[data-feedback]"),
+			};
+		},
+	},
+);
+
+// Une page ajoute un path et les composants disponibles sur cet ecran.
+export const homePage = createPage(
+	"home",
+	{
+		makePath() {
+			return "/";
+		},
+		getMainElement({ body }) {
+			return body.locator("main[data-page='home']");
+		},
+		getElements({ mainElement }) {
+			return {
+				title: mainElement.locator("h1"),
+			};
+		},
+		components: [newsletterComponent],
+	},
+);
+
+// Les parametres d'URL restent avec la definition de l'ecran.
+export const articlePage = createPage(
+	"article",
+	{
+		makePath(params: { slug: string }) {
+			return `/articles/${params.slug}`;
+		},
+		getMainElement({ body }) {
+			return body.locator("article");
+		},
+		getElements({ mainElement }) {
+			return {
+				title: mainElement.locator("h1"),
+				content: mainElement.locator("[data-content]"),
+			};
+		},
+	},
+);

package/docs/concepts/04-tests/02-e2e/30-testing.ts

@@ -0,0 +1,90 @@
+/**
+ * @title Ecrire un parcours de test
+ *
+ * Scénarios utilisateur, interactions et vérifications avec les objets du site.
+ */
+import { Actions, Assertions, createComponent, createPage, type Website } from "@duplojs/playwright";
+
+interface TestFixtures {
+	website: Website;
+}
+
+declare const testClient: (title: string, body: (fixtures: TestFixtures) => Promise<void>) => void;
+
+const newsletterComponent = createComponent(
+	"newsletter",
+	{
+		getMainElement({ body }) {
+			return body.locator("[data-newsletter]");
+		},
+		getElements({ mainElement }) {
+			return {
+				emailInput: mainElement.locator("input[type='email']"),
+				submitButton: mainElement.locator("button[type='submit']"),
+				feedback: mainElement.locator("[data-feedback]"),
+			};
+		},
+		getMethods({ elements }) {
+			return {
+				async subscribe(email: string) {
+					await elements!.emailInput.fill(email);
+					await elements!.submitButton.click();
+				},
+			};
+		},
+	},
+);
+
+const homePage = createPage(
+	"home",
+	{
+		makePath() {
+			return "/";
+		},
+		getMainElement({ body }) {
+			return body.locator("main[data-page='home']");
+		},
+		getElements({ mainElement }) {
+			return {
+				title: mainElement.locator("h1"),
+			};
+		},
+		components: [newsletterComponent],
+	},
+);
+
+// Les actions parcourent l'interface, les assertions vérifient son état.
+// Les clés passées aux helpers viennent des éléments nommés dans `getElements`.
+// `Actions` et `Assertions` limitent ces clés aux éléments déclarés sur l’objet ciblé.
+// Le scénario navigue vers une page, récupère son composant, agit sur ses
+// éléments puis vérifie le résultat ; une méthode nommée peut regrouper les actions.
+testClient("visitor subscribes to the newsletter", async({ website }) => {
+	const home = await website.iNavigateTo(homePage);
+
+	await website.iExpectTitleIs(/Home/);
+	await Assertions.toHaveText(home, "title", "Welcome");
+
+	const newsletter = await home.iWantToSeeComponent("newsletter");
+
+	await Assertions.toHaveText(newsletter, "feedback", "No email submitted yet.");
+	await Actions.fill(newsletter, "emailInput", "jane@duplo.dev");
+	await Actions.click(newsletter, "submitButton");
+	await Assertions.toContainText(newsletter, "feedback", "jane@duplo.dev");
+	await Assertions.toHaveValue(newsletter, "emailInput", "jane@duplo.dev");
+});
+
+testClient("visitor cannot submit an empty newsletter form", async({ website }) => {
+	const home = await website.iNavigateTo(homePage);
+	const newsletter = await home.iWantToSeeComponent("newsletter");
+
+	await Actions.click(newsletter, "submitButton");
+	await Assertions.toHaveText(newsletter, "feedback", "Email is required.");
+});
+
+testClient("component methods can express repeated intentions", async({ website }) => {
+	const home = await website.iNavigateTo(homePage);
+	const newsletter = await home.iWantToSeeComponent("newsletter");
+
+	await newsletter.methods.subscribe("jane@duplo.dev");
+	await Assertions.toContainText(newsletter, "feedback", "jane@duplo.dev");
+});