Contribuer

Cette section s’adresse à celles et ceux qui modifient le code source de Mankomail : corriger un bogue, ajouter un nœud, brancher un nouveau service, améliorer l’interface ou la documentation. Elle décrit le dépôt tel qu’il est : les paquets, les outils, les commandes et les règles que l’outillage fait respecter.

Les autres pages de la section vont plus loin :

Page	Quand la lire
Écrire un nœud	Vous ajoutez ou modifiez un nœud du catalogue.
Écrire une intégration	Vous branchez un service tiers (clé d’API, webhooks, déclencheur par sondage).
Conventions	Avant votre première modification : TypeScript, frontières entre paquets, i18n, erreurs d’API, commits.
Tests	Vous écrivez ou lancez des tests, y compris ceux qui exigent PostgreSQL.

Organisation du dépôt

Le dépôt est un unique espace de travail pnpm piloté par Turborepo. Ses membres sont tous les dossiers de packages/ et d’apps/ (pnpm-workspace.yaml). Tous les paquets sont des modules ES purs écrits en TypeScript, publiés dans l’espace de travail sous la portée @manko/.

Dossier	Paquet	Rôle
packages/workflow	@manko/workflow	Le cœur isomorphe : graphe de workflow et validation, contrat de nœud (defineNode), déclaration des paramètres, moteur de templating {{ }}. Ne dépend d’aucun autre paquet du produit.
packages/api-types	@manko/api-types	Les schémas zod partagés entre le serveur (validation) et l’interface (types) : contenus de l’API, format d’erreur, catalogue des connexions, déclarations d’intégrations.
packages/credentials	@manko/credentials	Types de credentials, chiffrement d’instance, flux OAuth et renouvellement des jetons.
packages/connectors	@manko/connectors	Gmail, Microsoft Graph et IMAP/SMTP derrière un contrat commun.
packages/mirror	@manko/mirror	La synchronisation des boîtes : curseurs, rattrapage, push, et le modèle de message canonique.
packages/nodes	@manko/nodes	Le catalogue de nœuds : déclaration et fonction execute de chaque nœud, contrats des services consommés par les nœuds, doublures de test.
packages/engine	@manko/engine	Le moteur d’exécution : étapes persistées, file, planificateur, nouvelles tentatives, idempotence.
packages/tools	@manko/tools	La couche de tools interne : des capacités typées, nommées, à l’effet déclaré, utilisées par l’analyseur de boîte.
packages/server	@manko/server	Le point de composition : API HTTP et WebSocket, configuration typée, accès à la base et migrations SQL, intégrations.
packages/ui	@manko/ui	L’application Vue 3 : éditeur de workflows, webmail, administration. Construite, puis servie par le serveur.
apps/docs	@manko/docs	Cette documentation (VitePress). Les pages des nœuds et des intégrations sont générées depuis le catalogue réel.

Les dépendances entre paquets sont strictement descendantes, et ESLint le vérifie. Par exemple, @manko/nodes ne peut importer que @manko/workflow, et @manko/ui que @manko/workflow, @manko/api-types et @manko/nodes. Le tableau complet figure dans Conventions.

Prérequis

Outil	Version	Où elle est fixée
Node.js	24 ou ultérieure	engines dans le package.json racine ; la CI tourne sur Node 24.
pnpm	11.24.0	packageManager dans le package.json racine. Lancez corepack enable : Corepack fournit la version épinglée.
Docker	Docker Engine récent avec Compose	Fait tourner PostgreSQL 16 et MinIO pour la pile de développement et les tests d’intégration.

Il n’y a pas de fichier .nvmrc : le champ engines fait référence. TypeScript, Vitest, ESLint, Biome et Turborepo sont des dépendances de développement de l’espace de travail ; vous ne les installez pas globalement.

pnpm install n’exécute aucun script de cycle de vie des dépendances : la liste onlyBuiltDependencies de pnpm-workspace.yaml est vide à dessein, et la CI échoue si pnpm signale des scripts de build ignorés. Ajouter une dépendance qui exige un script de build est une exception à justifier dans ce fichier.

Mettre en place l’environnement de développement

1. Clonez le dépôt et installez les dépendances :

   corepack enable
   pnpm install

2. Copiez la configuration d’exemple. Chaque variable y est documentée, ainsi que dans Variables d’environnement.

   cp .env.example .env

3. Choisissez comment lancer l’application.

   La pile complète en conteneurs. compose.yaml démarre PostgreSQL 16, MinIO, une tâche qui crée le bucket, et l’application construite depuis le Dockerfile, sur le port 3000 :

   docker compose up -d
   curl localhost:3000/healthz   # le processus est vivant
   curl localhost:3000/readyz    # base joignable, migrations appliquées

   Le serveur et l’interface depuis les sources, ce qu’il vous faut pendant que vous modifiez le code. Démarrez seulement les dépendances de compose.yaml, puis les deux serveurs de développement :

   docker compose up -d postgres minio createbucket
   pnpm build
   pnpm --filter @manko/server dev    # node --watch, port 3000
   pnpm --filter @manko/ui dev        # serveur de développement Vite

   Ouvrez l’URL affichée par Vite. Le serveur de développement Vite relaie /api (WebSocket compris), /hooks, /healthz et /readyz vers http://localhost:3000, si bien que le cookie de session fonctionne sur une seule origine.

Configuration du serveur lancé depuis les sources

Le serveur lit sa configuration dans l’environnement du processus uniquement ; il ne charge pas .env de lui-même. Exportez les variables dans le shell qui le lance, par exemple avec set -a; . ./.env; set +a.

compose.yaml publie PostgreSQL sur 127.0.0.1:15432 et MinIO sur 127.0.0.1:19000, qui ne sont pas les ports écrits dans .env.example. Si vous lancez le serveur depuis les sources contre ces conteneurs, adaptez DATABASE_URL et STORAGE_ENDPOINT en conséquence. Les identifiants de ces conteneurs de développement figurent dans compose.yaml.

Au premier démarrage sur une base vide, le serveur crée le premier administrateur à partir de BOOTSTRAP_ADMIN_EMAIL et BOOTSTRAP_ADMIN_PASSWORD lorsqu’elles sont renseignées. Le réglage est ignoré dès qu’un membre existe.

Commandes principales

Lancez-les depuis la racine du dépôt.

Commande	Effet
pnpm build	Construit tous les paquets avec Turborepo (turbo run build), dépendances d’abord. Le paquet de documentation est construit aussi, ce qui lance son générateur.
pnpm typecheck	Vérifie les types de tous les paquets (turbo run typecheck).
pnpm lint	Lance ESLint (règles TypeScript, frontières entre paquets, imports interdits) puis biome check (formatage et ordre des imports).
pnpm lint:fix	Idem, en appliquant les corrections automatiques.
pnpm format	Reformate le code avec Biome.
pnpm test	Lance Vitest sur tous les projets (vitest run). Voir Tests.
pnpm test:watch	Vitest en mode surveillance.
pnpm dev	Lance le script dev de chaque paquet qui en a un (turbo run dev) : serveur, interface et documentation.
pnpm clean	Supprime les sorties de build et les caches.

Les commandes propres à un paquet passent par --filter, par exemple pnpm --filter @manko/docs dev pour servir cette documentation en local. Les commandes de la documentation sont détaillées dans Écrire un nœud.

Avant de rendre une modification, lancez au moins pnpm typecheck, pnpm lint et les tests des paquets touchés. La CI rejoue les mêmes vérifications à chaque push et à chaque pull request.

Ce que vérifie la CI

Le workflow de CI exécute un job à chaque push sur main et à chaque pull request :

1. pnpm install --frozen-lockfile, et une vérification qu’aucun script de build de dépendance n’a été ignoré ;
2. pnpm typecheck ;
3. pnpm lint ;
4. pnpm test contre un vrai PostgreSQL 16 et un vrai MinIO, suivi d’un garde-fou qui échoue si un test a été sauté ou si le nombre de tests passe sous un plancher ;
5. pnpm build ;
6. un test fumigatoire : docker compose up de la pile complète, puis /healthz et /readyz doivent répondre.

Un job planifié rejoue la suite complète trois fois de suite chaque nuit pour repérer les tests instables.

Licence

Avant de contribuer, consultez le champ license du package.json du paquet que vous modifiez. @manko/workflow et @manko/api-types déclarent Apache-2.0. Les autres paquets déclarent SEE LICENSE IN LICENSE.md, qui renvoie à un fichier de licence à la racine du dépôt ; c’est ce fichier qui fait foi pour eux.