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

package/docs/concepts.llms.md

@@ -0,0 +1,475 @@
+# Fondamentaux.
+
+## Contraintes de typage
+
+Garanties sur les valeurs : acquisition, composition, propagation, compatibilité statique et contraintes personnalisées.
+
+### Acquisition des contraintes.
+
+Vérification runtime et narrowing vers un type contraint.
+ 
+```ts
+import * as DNumber from "@duplojs/lang/number";
+
+// Une contrainte existe uniquement dans le typage : elle ne modifie ni ne valide la valeur.
+// L’intersection compose ici deux garanties établies par les predicates.
+type Age = number & DNumber.Integer & DNumber.Positive;
+
+// @ts-expect-error Le littéral seul ne porte pas les contraintes attendues.
+const age: Age = 12;
+
+// Chaque vérification réussie enrichit le type sans changer la valeur runtime.
+const maybeAge = 12;
+if (
+	DNumber.isInteger(maybeAge)
+	&& DNumber.isPositive(maybeAge)
+) {
+	const age: Age = maybeAge;
+}
+```
+
+### [Composition des contraintes fournies.](concepts/01-fundamental/01-constraint/10-built-in-constraint.ts)
+
+Réutilisation et composition des contraintes disponibles dans les domaines.
+ 
+### [Manipulation des valeurs contraintes.](concepts/01-fundamental/01-constraint/20-manipulation.ts)
+
+Exploitation des contraintes par les fonctions DuploJS pour simplifier la manipulation des valeurs.
+ 
+### [Compatibilité statique des contraintes.](concepts/01-fundamental/01-constraint/30-cast.ts)
+
+Cast par implication, valeurs littérales et inférence en contexte générique.
+ 
+### [Contraintes personnalisées.](concepts/01-fundamental/01-constraint/40-custom-constraint.ts)
+
+Déclaration, predicate de validation et extension des règles de cast.
+ 
+## Currification
+
+Composition des transformations de données avec les fonctions DuploJS : pipes, callbacks et traitements asynchrones.
+
+### Currification et composition avec pipe.
+
+Configurer les opérations avant de recevoir la donnée et enchaîner ses transformations.
+ 
+```ts
+import * as DCommon from "@duplojs/lang/common";
+import * as DArray from "@duplojs/lang/array";
+import * as DString from "@duplojs/lang/string";
+
+// La forme curifiée reçoit les paramètres, puis la donnée transmise par pipe.
+// Si la fonction retournée ne déclare pas ses propres génériques, ses types sont
+// fixés dès l'appel de configuration, même si la surcharge extérieure est générique.
+// Écrire alors l'appel curifié directement comme étape de pipe ou asyncPipe pour
+// fournir le contexte d'inférence attendu. Passer à un pipe une variable contenant
+// une fonction déjà préparée ne déplace pas sa configuration dans ce contexte.
+// Ne pas forcer cette préparation avec des génériques explicites, annotations ou casts.
+// Formater chaque pipe sur plusieurs lignes, un argument par ligne et la fermeture
+// sur sa propre ligne, même avec seulement une donnée et une étape.
+// Privilégier pipe dès qu’une donnée subit plusieurs transformations,
+// ou si le traitement est susceptible d’en accueillir d’autres.
+// Utiliser en priorité les fonctions fournies par l’écosystème.
+const normalizedTags = DCommon.pipe(
+	" TypeScript, DuploJS, Functional " as const,
+	// Configure le séparateur ; pipe fournit ensuite la chaîne.
+	DString.split(","),
+	// Configure la transformation ; pipe fournit le tableau.
+	DArray.map(DString.trim),
+	DArray.filter(DString.isNotEmpty),
+	DArray.map(DString.toLowerCase),
+);
+// Résultat : ["typescript", "duplojs", "functional"].
+// Chaque étape reçoit la sortie précédente ; les types suivent ces transformations.
+// On peut ajouter, retirer ou réordonner les étapes sans restructurer le traitement.
+```
+
+### [Réutilisation des fonctions de l’écosystème dans les pipes.](concepts/01-fundamental/02-currying/10-built-in-function.ts)
+
+Composer les opérations fournies, sous forme curifiée ou directement compatible avec pipe.
+ 
+### [Composition dans une callback.](concepts/01-fundamental/02-currying/20-inner-pipe.ts)
+
+Enchaîner des transformations lorsque la fonction appelante attend une fonction.
+ 
+### [Composition de traitements asynchrones.](concepts/01-fundamental/02-currying/30-async-pipe.ts)
+
+Enchaîner des étapes synchrones et asynchrones dans un pipe ou une callback.
+ 
+## Either
+
+Résultats et états contextualisés : représentation, discrimination, traitement exhaustif, propagation des échecs et adaptation des contrats.
+
+### Représentation des résultats avec Either.
+
+Statuts Right et Left, information contextuelle et valeur associée.
+ 
+```ts
+import * as DEither from "@duplojs/lang/either";
+
+// Un résultat porte un statut, une information qui identifie le cas et une valeur.
+const result = DEither.right("user-found", { name: "Alice" });
+const missing = DEither.left("user-not-found");
+
+// Les variantes fournies reposent sur Right (Success, Some, Result, Ok) ou Left
+// (Fail, Error, None).
+// Result décrit un état contextualisé sans décider s’il constitue un succès ou un échec.
+// Un contrat exprime les résultats possibles par une union, avec des informations
+// personnalisées ou des variantes fournies.
+// Dès qu'une branche d'une fonction renvoie un Right ou un Left, toutes ses
+// branches renvoient un Either. Envelopper les valeurs de réussite dans un Right,
+// y compris avec ok() pour une réussite sans valeur ; ne pas mélanger des Either
+// et des valeurs brutes dans le contrat de retour.
+type FindUserResult = DEither.Right<"user-found", { name: "Alice" }> | DEither.Left<"user-not-found", undefined>;
+```
+
+### [Discrimination et extraction des résultats.](concepts/01-fundamental/03-either/10-discrimination.ts)
+
+Choisir une branche par statut ou information, extraire sa valeur et traiter les autres cas.
+ 
+### [Décisions exhaustives sur les résultats.](concepts/01-fundamental/03-either/20-exhaustive-handling.ts)
+
+Sélection et traitement de chaque variante pour détecter les évolutions du contrat.
+ 
+### [Composition avec propagation des échecs.](concepts/01-fundamental/03-either/30-composition.ts)
+
+Enchaîner ou regrouper des opérations en arrêtant le traitement au premier Left.
+ 
+### [Adaptation des résultats au contexte.](concepts/01-fundamental/03-either/40-result-adaptation.ts)
+
+Reclasser les statuts et renommer les informations en conservant les valeurs.
+ 
+### [Conversion des absences et exceptions en résultats.](concepts/01-fundamental/03-either/50-external-results.ts)
+
+Distinguer les refus prévisibles des défaillances d'environnement et adapter les absences ou exceptions en résultats.
+ 
+### [États contextualisés avec Result.](concepts/01-fundamental/03-either/60-contextual-state.ts)
+
+Décrire et discriminer des états sans leur attribuer un sens de succès ou d’échec.
+ 
+## DataStructure
+
+Contrats de données partagés entre TypeScript et runtime : composition, validation, contraintes, représentations, récursivité et erreurs.
+
+### Contrats de données avec DataStructure.
+
+Décrire les données attendues et obtenir des valeurs typées après validation.
+ 
+```ts
+import * as DDataStructure from "@duplojs/lang/dataStructure";
+import * as DEither from "@duplojs/lang/either";
+
+// Une structure porte le même contrat dans TypeScript et au runtime.
+// L’utiliser aux frontières du logiciel pour vérifier les données encore inconnues.
+const userStructure = DDataStructure.object({
+	name: DDataStructure.string(),
+	email: DDataStructure.string([DDataStructure.email()]),
+});
+type User = DDataStructure.StructureValue<typeof userStructure>;
+
+declare const input: unknown;
+const result = userStructure.check(input);
+if (DEither.isRight(result)) {
+	const user: User = DEither.unwrapRight(result);
+}
+// Un Left conserve une erreur structurée lorsque la validation échoue.
+```
+
+### [Composition des contrats de données.](concepts/01-fundamental/04-data-structure/10-structure.ts)
+
+Construire et réutiliser des structures pour décrire des données simples ou composées.
+ 
+### [Contraintes de validation dans les structures.](concepts/01-fundamental/04-data-structure/20-constraint.ts)
+
+Ajouter et cumuler des contraintes compatibles, fournies ou personnalisées.
+ 
+### [Validation des données entrantes.](concepts/01-fundamental/04-data-structure/30-validation.ts)
+
+Vérification, conversion et narrowing aux frontières du logiciel, en synchrone ou asynchrone.
+ 
+### [Changement de représentation avec des codecs.](concepts/01-fundamental/04-data-structure/40-codecs.ts)
+
+Encoder et décoder les données avec un même contrat, selon leur type fondamental.
+ 
+### [Contrats de données récursifs.](concepts/01-fundamental/04-data-structure/50-recursive.ts)
+
+Références différées et cohérence entre un type déclaré et sa structure runtime.
+ 
+### [Interprétation des erreurs de validation et de conversion.](concepts/01-fundamental/04-data-structure/60-interpret-error.ts)
+
+Localiser les données invalides et adapter les messages au contexte ou à la langue.
+ 
+## Chrono
+
+Représentation des instants et durées : création, calculs, comparaison, sérialisation et fuseaux horaires.
+
+### Représentation des instants et des durées.
+
+TheDate et TheTime pour modéliser le temps avec des valeurs immuables.
+ 
+```ts
+import * as DChrono from "@duplojs/lang/chrono";
+
+// TheDate représente un instant absolu ; TheTime une durée ou une quantité de temps.
+// Privilégier ces types aux Date et number natifs dans le domaine pour rendre ce sens explicite.
+const instant = DChrono.createDate("2026-09-30");
+const duration = DChrono.createTime(2, "hour");
+
+// La transformation produit un nouvel instant ; la valeur initiale reste inchangée.
+const later = DChrono.addTime(instant, duration);
+```
+
+### [Création des instants et des durées.](concepts/01-fundamental/05-chrono/10-creation.ts)
+
+Valeurs connues statiquement ou reçues au runtime, et gestion des entrées invalides.
+ 
+### [Calculs et comparaisons temporels.](concepts/01-fundamental/05-chrono/20-manipulation.ts)
+
+Transformer, comparer et décomposer des instants ou durées avec les fonctions Chrono.
+ 
+### [Transport et reconstruction des valeurs temporelles.](concepts/01-fundamental/05-chrono/30-serialized.ts)
+
+Sérialiser, reconnaître et reconstruire les instants et durées en conservant leur valeur.
+ 
+### [Interprétation et affichage dans un fuseau horaire.](concepts/01-fundamental/05-chrono/40-timezone.ts)
+
+Interpréter une heure locale et lire ou présenter un instant dans le fuseau demandé.
+ 
+## Modélisation
+
+Identités métier, modèles de données, états et transitions, preuves de passage et identité des opérations dans les contrats.
+
+### [Identité et contraintes des types métier.](concepts/01-fundamental/06-modeling/10-new-type.ts)
+
+Distinguer des valeurs de même représentation par des NewType propres à leur rôle métier.
+ 
+### [Entités métier et hydratation.](concepts/01-fundamental/06-modeling/20-entity.ts)
+
+Déclarer les propriétés métier, hydrater les données externes et mettre à jour les valeurs typées.
+ 
+### [Objets taggés et unions discriminées.](concepts/01-fundamental/06-modeling/30-tagged-object.ts)
+
+Identité transportable, distinction des formes d’un objet et hydratation des données brutes.
+ 
+### [Cycle de vie des entités.](concepts/01-fundamental/06-modeling/40-entity-lifecycle.ts)
+
+États, préconditions et transitions métier représentés par des Flag et des Fact.
+ 
+### [Preuves de passage par une opération.](concepts/01-fundamental/06-modeling/50-evidence.ts)
+
+Exiger dans les types qu’une valeur soit passée par un traitement préalable.
+ 
+### [Identité des fonctions dans les dépendances.](concepts/01-fundamental/06-modeling/60-signed-function.ts)
+
+Exiger une fonction identifiée au-delà de sa seule signature TypeScript.
+ 
+## Discrimination
+
+Sélection et affinement des types dans les unions : identité, valeurs littérales, forme ou prédicats, traitement exhaustif ou partiel.
+
+### [Discrimination des entités par identité.](concepts/01-fundamental/07-discrimination/10-entity.ts)
+
+Sélection exhaustive ou partielle selon le nom métier, avec typage précis des branches.
+ 
+### [Discrimination selon le fait courant.](concepts/01-fundamental/07-discrimination/20-fact.ts)
+
+Choisir une branche selon la Fact portée par une valeur et accéder aux données du fait.
+ 
+### [Discrimination des objets par tag.](concepts/01-fundamental/07-discrimination/30-tagged-object.ts)
+
+Identifier la forme d’un objet par son tag et traiter tout ou partie de l’union.
+ 
+### [Discrimination des erreurs par identifiant.](concepts/01-fundamental/07-discrimination/40-error.ts)
+
+Sélection exhaustive ou partielle des erreurs DuploJS, avec typage précis des branches et des cas restants.
+ 
+### [Discrimination des valeurs littérales.](concepts/01-fundamental/07-discrimination/50-literal.ts)
+
+Traitement exhaustif ou partiel d’une union selon la valeur, avec branches typées.
+ 
+### [Discrimination par la forme des données.](concepts/01-fundamental/07-discrimination/60-shape.ts)
+
+Sélectionner les variantes sans identité explicite par des patterns, y compris imbriqués.
+ 
+### [Discrimination par prédicats et élimination.](concepts/01-fundamental/07-discrimination/70-predicate.ts)
+
+Affiner les branches et réduire les cas restants, avec sélection positive ou inverse.
+ 
+# Serveur
+
+## Manipuler des fichiers
+
+Accès cross-platform au système de fichiers : chemins typés avec `Path`, opérations sur fichiers/dossiers/liens et erreurs représentées par `Either`.
+
+### [Manipuler le système de fichiers](concepts/02-server/10-file/10-manipulation.ts)
+
+Lecture, écriture et opérations de système de fichiers avec chemins typés et résultats `Either`.
+ 
+### [Chemins typés](concepts/02-server/10-file/20-path.ts)
+
+Contraintes `Path`, `Absolute` et `Segment` pour valider, extraire et résoudre des chemins Unix.
+ 
+## HTTP
+
+Interfaces HTTP côté serveur : réception et validation des requêtes, orchestration des traitements et contrats de réponse typés partageables avec les clients.
+
+### [Créer une application HTTP](concepts/02-server/20-http/10-init.ts)
+
+Configuration d'un `Hub`, plugins et enregistrement des routes d'une application HTTP.
+ 
+### [Créer une route HTTP](concepts/02-server/20-http/20-route.ts)
+
+Construction du flux d’une route : entrées validées, contexte de traitement et réponses contextualisées.
+ 
+### [Faire une routine de vérification](concepts/02-server/20-http/30-routine.ts)
+
+Vérifications dans les flux HTTP, réutilisation des traitements et adaptation de leurs résultats au contexte.
+ 
+### [Définir une politique de gestion de tokens](concepts/02-server/20-http/40-jwt.ts)
+
+Déclaration d'une politique unique pour créer et vérifier une famille de tokens.
+ 
+### [Comment partager des ressources](concepts/02-server/20-http/50-codegen.ts)
+
+Génération du typage des routes et des `DataStructure` pour partager un contrat statique.
+ 
+## Environnement
+
+Exploitation des capacités de l’environnement serveur et adaptation aux API des différentes plateformes d’exécution.
+
+### [Capacités de plateforme](concepts/02-server/30-environment/10-platform.ts)
+
+Utilisation des abstractions communes et des connecteurs pour garder le code
+applicatif indépendant du runtime.
+ 
+### [Manipuler les variables d'environnement](concepts/02-server/30-environment/20-variable.ts)
+
+Chargement de sources d'environnement, validation par `DataStructure` et
+obtention d'une configuration typée.
+ 
+## Créer des commandes
+
+Création d’interfaces en ligne de commande (CLI) pour les applications serveur.
+
+### [Définir une commande](concepts/02-server/40-command/10-use.ts)
+
+Définition des entrées et du traitement d’une commande CLI.
+ 
+### [Créer des sous-commandes](concepts/02-server/40-command/20-sub-command.ts)
+
+Composition de commandes sous forme d'arbre pour router l'exécution vers
+une branche spécialisée.
+ 
+# Client
+
+## Client HTTP
+
+Communication typée avec des API HTTP.
+
+### [Initialiser un client HTTP](concepts/03-client/10-http/10-init.ts)
+
+Création d'un client à partir du contrat statique des routes, configuration
+globale et conservation du typage des requêtes et réponses exposées par le
+serveur.
+ 
+### [Effectuer une requête HTTP](concepts/03-client/10-http/20-request.ts)
+
+Envoi de données et traitement des réponses typées d’une API HTTP.
+ 
+### [Utiliser les hooks du client HTTP](concepts/03-client/10-http/30-hook.ts)
+
+Comportements transversaux et instrumentation du cycle des échanges HTTP.
+ 
+## Form
+
+Création et gestion de formulaires typés pour les interfaces utilisateur.
+
+### [Créer un formulaire](concepts/03-client/20-form/10-init.ts)
+
+Initialisation et cycle de vie d’un formulaire Vue typé.
+ 
+### [Inputs de formulaire réutilisables](concepts/03-client/20-form/20-input.ts)
+
+Création, intégration et validation des champs de saisie d’un formulaire Vue.
+ 
+### [Composer avec les layouts](concepts/03-client/20-form/30-layout.ts)
+
+Composition de la structure des données et des comportements d’un formulaire.
+ 
+### [Personnaliser les templates](concepts/03-client/20-form/40-template.ts)
+
+Personnalisation globale ou locale du rendu Vue des formulaires et de leurs champs.
+ 
+# Tests
+
+## Tests unitaires
+
+Vérification du comportement et du typage des unités de code.
+
+### [Tester un résultat Either](concepts/04-tests/01-unit/10-either.ts)
+
+Vérification des branches, des valeurs et du typage d’un contrat Either.
+ 
+### [Remplacer les implémentations serveur](concepts/04-tests/01-unit/20-server-mocking.ts)
+
+Contrôle de l'environnement et des fonctions serveur pour isoler les tests.
+ 
+## Tests E2E
+
+Vérification des parcours utilisateur dans une application web.
+
+### [Initialiser le client E2E](concepts/04-tests/02-e2e/10-init.ts)
+
+Configuration de l’environnement de test et intégration du site aux fixtures Playwright.
+ 
+### [Architecturer une suite E2E](concepts/04-tests/02-e2e/20-architecture.ts)
+
+Organisation d’une suite E2E selon les pages et les composants du site testé.
+ 
+### [Ecrire un parcours de test](concepts/04-tests/02-e2e/30-testing.ts)
+
+Scénarios utilisateur, interactions et vérifications avec les objets du site.
+ 
+# Type Driven Design
+
+Architecture en couches, modélisation du domaine et orchestration applicative pour faire vivre les cycles de vie métier.
+
+## Architecture
+
+Responsabilités des couches, sens des dépendances, opérations autorisées aux frontières et exposition des résultats aux consommateurs.
+
+### [Frontières entre domaine, application et infrastructure](concepts/05-type-driven-design/01-architecture/10-boundaries.md)
+
+Déterminer les dépendances autorisées, les opérations utilisables depuis chaque couche et le traitement des données et erreurs aux frontières du système.
+
+## Domaines
+
+Modélisation du métier et contrats de ses opérations : entités, invariants, transitions, agrégats et repositories.
+
+### [Conception des entités en Type-Driven Design](concepts/05-type-driven-design/02-domains/10-entities.md)
+
+Organisation des modèles métier, de leurs invariants, qualifications et transitions dans le domaine.
+
+### [Conception des agrégats en Type-Driven Design](concepts/05-type-driven-design/02-domains/20-aggregates.md)
+
+Contrats des transactions métier, préconditions et orchestration de faits réutilisables.
+
+### [Conception des repositories en Type-Driven Design](concepts/05-type-driven-design/02-domains/30-repositories.md)
+
+Contrats des opérations nécessaires au métier dont l'implémentation technique reste extérieure au domaine.
+
+## Applications
+
+Orchestration des agrégats, ports de capacités, injection des dépendances, effets et persistance.
+
+### [Conception des use cases en Type-Driven Design](concepts/05-type-driven-design/03-applications/10-use-case.md)
+
+Orchestration applicative des agrégats, sélection et propagation des résultats Either, ports et injection avec Reader, résolution des effets et persistance.
+
+## Infrastructure
+
+Assemblage concret de l'application : implémentation des ports, résolution des use cases et raccordement aux points d'entrée.
+
+### [Assembler l'application dans l'infrastructure](concepts/05-type-driven-design/04-infrastructure/10-implementation.md)
+
+Fournir les dépendances concrètes de l'application et raccorder ses capacités aux points d'entrée du système.
+

package/instructions/coding-conventions.md

@@ -0,0 +1,8 @@
+## Développement avec DuploJS
+
+- Réutiliser les fonctions DuploJS avant d’écrire un utilitaire ou d’utiliser une API native ou tierce équivalente.
+- Pour une recherche de concept ou un problème de composition, de typage ou d’erreur, consulter le [routeur des concepts]({{packagePath}}/docs/concepts.llms.md), puis uniquement les pages et exemples pertinents.
+- Appliquer les contrats et patterns documentés, notamment pour les contraintes et les résultats `Either`. Ne pas inventer d’API ni contourner le typage pour résoudre un doute.
+- Utiliser les skills DuploJS installés pour les procédures spécialisées liées à la tâche.
+
+Le chemin du routeur est relatif au dossier de ce fichier ; résoudre ensuite chaque lien depuis le document qui le contient.

package/package.json

@@ -1,6 +1,99 @@
 {
   "name": "@duplojs/agents-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-beta.3",
+  "license": "MIT",
+  "author": {
+    "name": "DuploJS",
+    "url": "https://github.com/duplojs"
+  },
+  "description": "Shared skills and configuration for DuploJS packages.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/duplojs/ecosystem.git",
+    "directory": "packages/agents-kit"
+  },
+  "bugs": {
+    "url": "https://github.com/duplojs/ecosystem/issues"
+  },
+  "bin": {
+    "duplojs-agents-kit": "./dist/bin/index.mjs"
+  },
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./docs/concepts.llms.md": "./docs/concepts.llms.md",
+    "./docs/API.llms.md": "./docs/API.llms.md",
+    "./docs/API/*/index.llms.md": "./docs/API/*/index.llms.md"
+  },
+  "dependencies": {
+    "@duplojs/lang": "0.1.0-beta.3",
+    "@duplojs/server": "0.1.0-beta.3"
+  },
+  "peerDependencies": {
+    "@duplojs/code-config": "0.1.0-beta.3",
+    "@duplojs/eslint": "0.1.0-beta.3",
+    "@duplojs/form": "0.1.0-beta.3",
+    "@duplojs/http": "0.1.0-beta.3",
+    "@duplojs/json-web-token": "0.1.0-beta.3",
+    "@duplojs/lang": "0.1.0-beta.3",
+    "@duplojs/playwright": "0.1.0-beta.3",
+    "@duplojs/server": "0.1.0-beta.3",
+    "@duplojs/tools": "0.1.0-beta.3"
+  },
+  "peerDependenciesMeta": {
+    "@duplojs/code-config": {
+      "optional": true
+    },
+    "@duplojs/eslint": {
+      "optional": true
+    },
+    "@duplojs/form": {
+      "optional": true
+    },
+    "@duplojs/http": {
+      "optional": true
+    },
+    "@duplojs/json-web-token": {
+      "optional": true
+    },
+    "@duplojs/playwright": {
+      "optional": true
+    },
+    "@duplojs/tools": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@duplojs/code-config": "0.1.0-beta.3",
+    "@types/node": "24.13.3",
+    "@types/web": "0.0.358"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "skills",
+    "instructions",
+    "README.md"
+  ],
+  "keywords": [
+    "duplojs",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=24.18.0"
+  },
+  "scripts": {
+    "build": "./.commands/build.sh",
+    "llms": "tsx bin/index.ts",
+    "test:types": "./.commands/test-types.sh",
+    "test:types:target": "./.commands/test-types-target.sh",
+    "test:lint": "./.commands/test-lint.sh",
+    "test:lint:fix": "./.commands/test-lint.sh --fix"
+  }
 }

package/skills/command/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: duplojs-command
+description: "Créer, modifier ou corriger une interface en ligne de commande avec @duplojs/server/command : arguments et options typés, sous-commandes, aide et point d'entrée exécutable."
+---
+
+# Commandes DuploJS
+
+## Trouver les concepts
+
+Appliquer la démarche du skill et lire les ressources indiquées lorsque leur condition est rencontrée. Pour rechercher un concept ou un mécanisme non couvert, consulter `docs/concepts.llms.md` du package `@duplojs/agents-kit`.
+
+Le setup indique ce chemin dans `AGENTS.md` ou `CLAUDE.md`, relativement à leur dossier. Les chemins `docs/` partent du package installé, même avec `--copy`. Les références du skill partent de son dossier ; les liens d'un document se résolvent depuis ce document.
+
+Si le chemin du routeur manque, le retrouver depuis le projet consommateur :
+
+```sh
+node --input-type=module -e 'import { fileURLToPath } from "node:url"; console.log(fileURLToPath(import.meta.resolve("@duplojs/agents-kit/docs/concepts.llms.md")))'
+```
+
+## Choisir la forme de la commande
+
+Importer le domaine sous le namespace `DSCommand` depuis `@duplojs/server/command`, et les schémas sous `DDataStructure` depuis `@duplojs/lang/dataStructure`.
+
+| Besoin | Construction |
+| --- | --- |
+| Exécuter une commande racine avec ses entrées | `DSCommand.exec` lit les arguments du processus et appelle le callback après validation. |
+| Assembler plusieurs actions nommées | `DSCommand.create` définit les sous-commandes, placées dans les `subjects` du parent exécuté avec `exec`. |
+| Lire uniquement les options d'un script | `DSCommand.execOptions` retourne le résultat du parsing ; le script décide ensuite de lancer le traitement. |
+
+Identifier les entrées et leurs contraintes, déclarer leur contrat, puis écrire le callback avec les `args` et `options` inférés. Exécuter la racine une seule fois au point d'entrée. Pour une racine simple, lire la première déclaration de `docs/concepts/02-server/40-command/10-use.ts` ; pour un script sans arguments positionnels, suivre l'[exemple à options seules](references/examples/options-only.ts).
+
+## Déclarer les entrées
+
+Les entrées du terminal sont externes : les faire décoder et valider par les data structures intégrées aux déclarations. Décrire les contraintes utiles, comme un entier borné ou un choix de littéraux ; ne pas remplacer cette validation par un cast ou une conversion manuelle dans le callback.
+
+| Entrée | Déclaration et garantie |
+| --- | --- |
+| Valeur positionnelle | `createArgument` dans `subjects`, obligatoire par défaut. Placer les arguments `optional: true` après les obligatoires. |
+| Option à valeur | `createOption` dans `options`, facultative par défaut : absence en `undefined`. `required: true` la rend obligatoire ; une présence sans valeur reste invalide. |
+| Flag de présence | `createBooleanOption`, `false` si absent et `true` si présent ; ne reçoit pas de valeur. |
+| Liste | `createArrayOption`, facultative par défaut ; son schéma décrit un élément. Les bornes ne rendent pas la liste obligatoire. |
+
+Les noms doivent être uniques dans chaque ensemble d'options ou de sujets. Choisir aussi des alias sans collision et conserver `help` / `h` pour l'aide intégrée.
+
+Pour créer ou modifier une entrée, lire [Entrées et garanties](references/inputs.md) avant de choisir sa syntaxe et son schéma. L'[exemple complet](references/examples/preview-command.ts) combine arguments, options, flag et liste bornée ; reprendre les constructions nécessaires au contrat de la commande.
+
+## Assembler et exécuter
+
+Un même `subjects` contient soit des arguments, soit des sous-commandes. Le premier argument sélectionne la sous-commande ; le callback du parent ne s'exécute pas comme une étape préalable. Déclarer les options nécessaires sur chaque commande qui les consomme ; celles du parent ne sont pas héritées.
+
+Décrire les commandes et leurs entrées pour alimenter l'aide intégrée `--help` / `-h`. Choisir `displayName` sur la racine pour identifier le programme dans l'aide et les diagnostics.
+
+Si la tâche ajoute un arbre, modifie l'exécution ou expose un binaire, lire [Arbre, aide et résultat d'exécution](references/execution.md). L'[exemple avec sous-commande](references/examples/cli.ts) montre l'assemblage et le code de sortie sur erreur de validation.
+
+## Raccorder l'application et vérifier
+
+Le callback est un point d'entrée d'infrastructure : il adapte les données validées, appelle l'application et interprète ses résultats pour le terminal. Il retourne `void` ou une promesse de `void` ; lui retourner un `Either` métier ne propage pas cet échec à `exec`. Garder l'orchestration métier dans l'application et choisir le diagnostic et la conséquence finale dans le callback.
+
+Une erreur de validation empêche l'appel du callback ; `exec` retourne cette erreur après son affichage, sans fixer à lui seul un code de sortie d'échec. Avec `execOptions`, sélectionner l'information `success` avant de lancer le travail : l'aide est aussi un `Right`, sous `log-help`.
+
+Pour les opérations sur les fichiers, la configuration d'environnement et les capacités du processus appelées depuis une commande, consulter le skill `duplojs-server`.
+
+Vérifier le typage du projet, puis exercer l'aide, un appel valide, une entrée invalide et l'absence d'une entrée obligatoire. Pour un arbre, vérifier aussi le chemin complet vers la sous-commande. Utiliser des opérations sans effet ou des dépendances de test lorsque la commande agit sur l'environnement ; vérifier le code de sortie attendu en cas d'échec.

package/skills/command/references/examples/cli.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+
+import * as DSCommand from "@duplojs/server/command";
+import * as DSCommon from "@duplojs/server/common";
+import * as DEither from "@duplojs/lang/either";
+import { previewCommand } from "./preview-command";
+
+const result = await DSCommand.exec(
+	{
+		displayName: "my-cli",
+		description: "Preview application operations",
+		subjects: [previewCommand],
+	},
+	() => {
+		console.log("Use my-cli preview --help to inspect export parameters.");
+	},
+);
+
+// Les diagnostics de validation ont déjà été affichés par exec.
+if (DEither.isLeft(result)) {
+	DSCommon.exitProcess(1);
+}