Migrer vers Encore

Cette skill guide la migration de toute application backend existante vers Encore, une unité de migration à la fois. Elle supporte n'importe quel langage source ou framework et cible à la fois Encore.ts et Encore Go. Un fichier récapitulatif migration-plan.md et un répertoire migration-plan/ contenant des fichiers de détail par unité sont créés à la racine du projet Encore pour suivre la progression entre les sessions. Cette skill ne contient aucun exemple de code Encore — elle délègue toute implémentation spécifique à Encore aux skills appropriées spécifiques au langage.

Détection de Phase

Avant toute action, déterminez quelle phase intégrer :

• Aucun migration-plan.md n'existe dans le répertoire du projet Encore → Commencez à Phase 1 : DISCOVER
• migration-plan.md existe mais pas de répertoire migration-plan/ → Reprenez à Phase 2 : PLAN (découverte faite, fichiers de détail pas encore écrits)
• Le répertoire migration-plan/ existe avec des unités en attente (toute unité du résumé avec le statut pending ou in progress) → Reprenez à Phase 3 : MIGRATE
• Toutes les unités du résumé sont migrated, skipped, ou manual validation needed → Allez à Phase 4 : COMPLETE

Reprendre une Migration (Phase 3)

Quand migration-plan.md et migration-plan/ existent avec des unités en attente :

1. Lisez migration-plan.md (résumé uniquement — ne lisez PAS tous les fichiers de détail)
2. Signalez le statut actuel à l'utilisateur — par exemple : « 3 de 7 unités migrées, prochaine suggérée : billing (toutes ses dépendances sont migrées) »
3. Demandez à l'utilisateur ce qu'il souhaite faire ensuite, en proposant une suggestion basée sur l'ordre des dépendances du plan

Phase 1 — Discover

1. Recueillir les Informations

Demandez à l'utilisateur :

• Chemin du système source (la base de code existante en cours de migration)
• URL locale où s'exécute le système source (si applicable — nécessaire pour la validation par comparaison HTTP plus tard)
• Langage cible : Encore.ts ou Encore Go

2. Analyser la Base de Code Source

Lisez la base de code source et inventoriez toutes les entités :

3. Identifier le Code Frontend

Les repos full-stack et monorepos mélangent souvent le code backend et frontend. La migration cible uniquement le backend — le code frontend est hors de portée.

Détectez les répertoires frontend et marquez-les comme hors de portée. Indicateurs courants :

Signalez le code côté serveur du framework qui devrait être migré. Certains frameworks frontend intègrent la logique backend qui contient des points de terminaison API, des requêtes de base de données ou la logique métier côté serveur :

Quand le code côté serveur du framework est trouvé, demandez à l'utilisateur quoi faire. Tout le code côté serveur ne devrait pas bouger vers Encore — parfois une couche backend mince (BFF, auth proxy, SSR data fetching) devrait rester dans le framework frontend aux côtés d'un backend Encore.

Présentez à l'utilisateur ce qui a été trouvé et demandez :

« J'ai trouvé <N> routes côté serveur dans votre app <framework> (par ex., pages/api/users.ts, app/billing/route.ts). Elles contiennent une logique backend qui pourrait être migrée vers Encore, mais certaines équipes préfèrent garder une couche serveur mince dans leur framework frontend pour des choses comme SSR data fetching ou BFF proxying. Souhaiteriez-vous :

1. Migrer tout — routes côté serveur vers Encore
2. Migrer certaines — je vais les lister et vous choisirez lesquelles bouger
3. Garder tout dans <framework> — migrer uniquement le code backend autonome »

Selon le choix de l'utilisateur :

• Migrer tout : Extrayez la logique backend dans les unités de migration. Laissez le code de rendu frontend hors de portée. Notez dans le plan de migration quels fichiers source contiennent du code mixte frontend/backend.
• Migrer certaines : Présentez la liste des routes côté serveur et laissez l'utilisateur sélectionner. Incluez les routes sélectionnées dans les unités de migration, marquez le reste comme hors de portée.
• Garder tout : Marquez tout le code côté serveur du framework comme hors de portée aux côtés du frontend. Seul le code backend autonome (routes Express, serveurs API autonomes, etc.) entre dans les unités de migration.

Signalez à l'utilisateur : Listez tous les répertoires frontend détectés et la décision prise concernant le code côté serveur du framework. Exemple : « J'ai trouvé un frontend Next.js dans app/ — les composants React sont hors de portée. Vous avez choisi de migrer 8 des 12 routes API de pages/api/ vers Encore et de garder 4 routes proxy minces dans Next.js. »

4. Grouper les Entités dans des Unités de Migration

Regroupez les entités découvertes dans des unités de migration en utilisant ces heuristiques par ordre de priorité :

1. Limites de service existantes — Si l'app source a déjà des services, modules ou packages, utilisez-les comme point de départ pour les chunks
2. Préfixes de chemin URL — Regroupez les points de terminaison partageant un préfixe de chemin (ex., /users/*, /billing/*)
3. Tables de base de données partagées — Les points de terminaison qui lisent/écrivent aux mêmes tables appartiennent ensemble
4. Types/modèles partagés — Les points de terminaison qui partagent les types requête/réponse ou les modèles de domaine

Dimensionnement des chunks : Visez 5-15 points de terminaison par unité de migration. Si un groupe dépasse ~15 points de terminaison, suggérez de le scinder davantage (ex., users-crud et users-admin). Si un groupe a moins de 3 points de terminaison, envisagez de le fusionner avec un chunk connexe.

Les préoccupations transversales reçoivent leurs propres unités de migration : auth, secrets et infrastructure autonome (pub/sub topics, cron jobs non fortement couplés à un service) sont des unités séparées car elles suivent différents niveaux de dépendance.

Pour les monolithes sans limites claires : Retombez sur le regroupement par préfixe de chemin URL, puis demandez : « Ces regroupements sont basés sur les chemins URL — souhaiteriez-vous les réorganiser par domaine ? »

5. Présenter les Unités de Migration

Présentez les unités de migration à l'utilisateur sous forme d'un tableau récapitulatif :

Incluez les totaux (ex., « 7 unités de migration couvrant 42 points de terminaison, 3 bases de données »). Pour chaque unité, évaluez la complexité globale de la migration :

• Low — les équivalents Encore directs existent, mappage simple
• Medium — nécessite une restructuration ou a des équivalents Encore partiels
• High — pas d'équivalent direct, nécessite une refonte ou une solution personnalisée

Proposez de montrer le détail de toute unité si l'utilisateur souhaite inspecter ce qui se trouve à l'intérieur avant de confirmer.

6. Afficher des Aperçus de Code

Pour 2-3 entités représentatives (choisissez un mélange de simples et complexes provenant de différentes unités), montrez un court aperçu « avant et après » de ce que le code source ressemble maintenant et ce que la version Encore ressemblera. Utilisez la skill appropriée spécifique au langage pour informer l'aperçu. Gardez les aperçus brefs — un point de terminaison, une requête ou une déclaration de topic est suffisant par aperçu.

7. Confirmer avec l'Utilisateur

Demandez à l'utilisateur de confirmer que les unités de migration sont correctes. Demandez spécifiquement :

• « Y a-t-il des services, points de terminaison ou autres entités que j'ai manqués ? »
• « Souhaiteriez-vous scinder, fusionner ou renommer l'une de ces unités de migration ? »
• « Y a-t-il quelque chose que vous voulez exclure de la migration ? »

8. Itérer si Nécessaire

Si l'utilisateur identifie des entités manquantes ou souhaite ajuster les limites des chunks, mettez à jour les unités et re-présentez le tableau récapitulatif. Répétez jusqu'à ce que l'utilisateur confirme que les unités de migration sont exactes.

Phase 2 — Plan

1. Vérifier l'Existence du Projet Encore

Vérifiez si un projet Encore existe déjà au chemin cible (recherchez le fichier encore.app). Si oui, confirmez auprès de l'utilisateur que c'est le bon projet. Si non, aidez à en créer un en invoquant la skill encore-getting-started (ou encore-go-getting-started pour Go).

2. Recueillir les Informations Cibles

Demandez à l'utilisateur :

• Chemin du projet Encore (où vivra le code migré)
• URL locale où s'exécutera l'app Encore (défaut : http://localhost:4000)

3. Déterminer l'Ordre des Dépendances

Ordonnez les unités de migration en fonction des dépendances. Suivez cet ordre de tier :

1. Secrets / config — aucune dépendance, nécessaires pour tout
2. Bases de données — schéma et migrations doivent exister avant que les services puissent les utiliser
3. Auth — les gestionnaires d'auth sont nécessaires avant les points de terminaison protégés
4. Unités feuille — unités sans dépendances inter-services
5. Unités dépendantes — unités qui dépendent d'unités déjà migrées
6. Topics Pub/Sub et abonnements — dépendent souvent de la présence de services
7. Tâches Cron — dépendent généralement des points de terminaison de service

Au sein de chaque tier, suggérez l'unité la plus simple en premier (le moins de points de terminaison, le plus petit schéma, le moins de complexité).

4. Écrire migration-plan.md (Résumé)

Écrivez le fichier résumé migration-plan.md à la racine du projet Encore en utilisant le modèle dans la section « Format migration-plan.md » ci-dessous. Remplissez toutes les unités de migration avec le statut pending.

5. Écrire les Fichiers de Détail

Créez un répertoire migration-plan/ à la racine du projet Encore. Écrivez un fichier de détail par unité de migration en utilisant le modèle dans la section « Format Fichier de Détail » ci-dessous. Chaque fichier est nommé migration-plan/<unit-name>.md.

6. Proposer la Première Unité

Proposez la première unité de migration, en expliquant pourquoi elle devrait venir en premier en fonction de l'ordre des dépendances. Attendez l'approbation de l'utilisateur avant de procéder à la Phase 3.

Phase 3 — Migrate (Boucle)

1. Identifier l'Unité Suivante

Lisez migration-plan.md (résumé uniquement) et identifiez l'unité de migration en attente suivante en fonction de l'ordre des dépendances.

2. Suggérer et Confirmer

Suggérez l'unité suivante à migrer et expliquez pourquoi celle-ci vient ensuite (ex., « Cette unité n'a aucune dépendance sur les unités non migrées » ou « La base de données doit exister avant que nous puissions migrer le service qui l'utilise »). Demandez à l'utilisateur s'il souhaite procéder avec cette unité ou en choisir une autre.

3. Charger le Détail de l'Unité

Lisez le fichier de détail pour l'unité choisie (migration-plan/<unit-name>.md). Ne lisez PAS les fichiers de détail pour les autres unités.

4. Migrer Chaque Entité

Pour chaque entité dans l'unité :

a. Implémenter

Invoquez la skill appropriée spécifique au langage en fonction du type d'entité et du langage cible :

b. Migrer les Tests

Si l'entité source a des tests associés, migrez-les en utilisant la skill de test appropriée (encore-testing ou encore-go-testing). Adaptez les assertions de test pour correspondre aux motifs API Encore. Si l'entité source n'a pas de tests, notez-le dans le fichier de détail.

c. Valider

Trois couches de validation sont appliquées à chaque entité avant qu'elle puisse être marquée comme migrated. Chaque entité doit passer par toutes les couches applicables.

Couche 1 : Migration de Tests (Primaire)

• Lors de la migration d'une entité, migrez également ses tests associés
• Utilisez la skill encore-testing (ou encore-go-testing pour Go) pour implémenter les tests
• Exécutez les tests — ils doivent réussir avant que l'entité puisse être marquée comme migrated
• Si l'entité source n'avait pas de tests, notez « no source tests » dans le plan et appuyez-vous sur les autres couches

Couche 2 : Comparaison HTTP (Points de Terminaison Uniquement, Meilleur Effort)

Quand les deux systèmes s'exécutent localement, appelez le même point de terminaison sur le système source et l'app Encore, puis comparez :

• Code de statut HTTP — doit correspondre
• Structure du corps de réponse — les clés et la forme doivent correspondre (les valeurs peuvent différer pour les données dynamiques comme les timestamps ou les ID)

Ignorez cette couche quand :

• Le point de terminaison nécessite des identifiants d'authentification que l'agent ne peut pas obtenir (demandez à l'utilisateur — autorisez l'omission)

Si une requête à l'un ou l'autre système échoue à se connecter, demandez à l'utilisateur de démarrer l'app avant de réessayer. N'omettez pas silencieusement — l'utilisateur a peut-être simplement oublié de la démarrer.

Demandez toujours à l'utilisateur avant de faire tout appel HTTP qui pourrait avoir des effets secondaires.

Couche 3 : Portail de Vérification-Avant-Complétion

Avant de marquer UNE QUELCONQUE entité comme migrated, l'agent DOIT avoir des preuves récentes de la session actuelle :

• Sortie de commande de test montrant le nombre de réussite et le code de sortie, OU
• Résultats de comparaison HTTP montrant une correspondance, OU
• Approbation explicite de l'utilisateur pour ignorer la validation

Règles :

• Pas de « should work », « looks correct » ou « seems fine » — uniquement des prétentions soutenues par des preuves
• L'agent doit énoncer exactement ce qu'il a vérifié et quelle a été la sortie
• Si la preuve est insuffisante, marquez l'entité comme manual validation needed, pas migrated
• Les preuves obsolètes d'une session précédente ne comptent pas — réexécutez la validation en cas de reprise

d. Mettre à Jour le Fichier de Détail

Mettez à jour le statut de l'entité dans le fichier de détail de l'unité (migration-plan/<unit-name>.md) et enregistrez la preuve de validation dans le tableau Validation Log de ce fichier.

e. Mettre à Jour le Résumé

Quand toutes les entités d'une unité sont terminées, mettez à jour le statut de l'unité dans migration-plan.md à migrated. Si certaines entités sont en attente, définissez le statut de l'unité à in progress.

5. Continuer ou Pausar

Après avoir complété une unité, demandez « Qu'aimeriez-vous migrer ensuite ? » et suggérez l'unité suivante en fonction de l'ordre des dépendances.

6. Regroupement

Le défaut est une unité à la fois. Si l'utilisateur dit « continue », « fais-les tous » ou similaire, regroupez plusieurs unités mais validez toujours chaque entité individuellement avant de la marquer comme migrée.

Phase 4 — Complete

Quand toutes les unités dans migration-plan.md sont migrated, skipped, ou manual validation needed :

1. Présentez un résumé final provenant de migration-plan.md :
   • Unités migrées au total
   • Unités marquées comme manual validation needed — lisez ces fichiers de détail spécifiques et listez les entités qui nécessitent une attention avec les raisons
   • Unités ignorées (listez-les avec les raisons)
2. Suggérez d'exécuter la suite de tests complète une dernière fois pour détecter tout problème d'intégration
3. Notez tout élément de validation manuel qui nécessite encore une attention humaine
4. Si le système source avait du code frontend, suggérez d'utiliser la skill encore-frontend pour reconnecter le frontend au nouveau backend Encore (générer un client API typé, configurer CORS, mettre à jour les URLs de base)
5. Suggérez de supprimer migration-plan.md et migration-plan/ du projet une fois que l'utilisateur est satisfait de la migration

Poser des Questions

Demandez à l'utilisateur avant d'agir quand :

• Les limites de service ne sont pas claires — ex., « Ces fichiers de routes pourraient être 1 service ou 3 — comment souhaiteriez-vous les scinder ? »
• Aucun équivalent Encore propre n'existe — ex., couche de cache Redis, chaînes de middleware personnalisées, gestionnaires WebSocket
• Plusieurs stratégies de migration valides existent — présentez les options avec les compromis
• Avant tout appel HTTP qui pourrait avoir des effets secondaires — toujours demander d'abord
• Le code source est ambigu — quand l'agent n'est pas confiant sur ce que fait le code, demandez plutôt que de deviner
• Le système source semble avoir changé — si des fichiers référencés dans un fichier de détail n'existent plus ou ont changé significativement

Protection du Système Source

Le système source ne doit jamais être modifié lors de la migration. Suivez ces règles :

• Ne jamais modifier les fichiers source — lisez-les, ne les éditez pas
• Ne jamais supprimer les fichiers source — même après la migration
• Ne jamais écrire dans le répertoire source — toute sortie va vers le projet Encore
• Ne jamais exécuter de commandes destructrices contre le système source (drop tables, delete queues, etc.)
• Demandez avant tout appel HTTP qui mute l'état du système source (POST, PUT, DELETE)

Si l'utilisateur vous demande de « nettoyer » ou « supprimer » l'ancien système, confirmez explicitement avant de prendre toute action. Le système source peut encore servir le trafic de production.

Cas Limites

Déplacer des Points de Terminaison Entre les Unités

Si l'utilisateur réalise qu'un point de terminaison appartient à une unité de migration différente :

1. Supprimez la ligne du point de terminaison du fichier de détail de l'unité source
2. Ajoutez-la au fichier de détail de l'unité cible
3. Mettez à jour les nombres de points de terminaison dans migration-plan.md

Scinder une Unité en Cours de Migration

Si une unité s'avère être trop grande pendant que vous travaillez dessus :

1. Créez un nouveau fichier de détail pour la portion scindée (migration-plan/<new-unit>.md)
2. Déplacez les entités en attente vers le nouveau fichier (les entités déjà migrées restent dans l'original)
3. Ajoutez la nouvelle unité au tableau résumé migration-plan.md
4. Insérez-la dans l'ordre des dépendances (même tier, après l'original)

Monolithe vers Plusieurs Services Encore

Une seule unité de migration peut mapper à plusieurs services Encore. Le fichier de détail suit le regroupement source, mais la colonne « Notes » peut indiquer le service Encore cible. Demandez lors de la migration si l'unité mappe à un service ou doit être scindée entre les services Encore.

Code Source Changé Depuis la Découverte

Si des fichiers référencés dans un fichier de détail n'existent plus ou ont changé significativement depuis la découverte :

1. Signalez la discordance à l'utilisateur
2. Demandez si mettre à jour le fichier de détail avec le nouvel état ou ignorer les entités affectées
3. Si mise à jour, ré-évaluez la complexité et ajustez le plan en conséquence

Dépannage

Les problèmes courants lors de la migration et comment les résoudre :

Format migration-plan.md

Utilisez ce modèle exact pour le fichier de plan résumé. Remplissez les valeurs depuis la phase de découverte.

# Migration Plan

## Source System
- **Path:** <source system path>
- **URL:** <source system local URL>
- **Framework:** <detected framework>
- **Language:** <detected language>

## Frontend (Out of Scope)
- **Detected:** <Yes/No>
- **Directories:** <list of frontend directories, or "None">
- **Framework:** <frontend framework if detected, or "N/A">
- **Note:** <any framework server-side code that WAS included in migration units>

## Target System
- **Path:** <encore project path>
- **URL:** <encore local URL>
- **Type:** Encore.ts | Encore Go

## Migration Units

| Unit | Endpoints | DB Tables | Other | Complexity | Status |
|------|-----------|-----------|-------|------------|--------|

## Dependency Order
1. <ordered list of migration units>

Valeurs de statut : pending, in progress, migrated, skipped, manual validation needed

Valeurs de complexité : Low (équivalent direct), Medium (nécessite une restructuration), High (nécessite une refonte)

Format Fichier de Détail

Créez un fichier par unité de migration à migration-plan/<unit-name>.md. Utilisez ce modèle exact :

# Migration Unit: <unit-name>

## Source
- **Files:** <list of source files in this unit>
- **Depends on:** <other migration units, with their current status>

## Endpoints
| Endpoint | Method | Path | Status | Notes |
|----------|--------|------|--------|-------|

## Database
| Table | Complexity | Status | Notes |
|-------|------------|--------|-------|

## Tests
- **Source tests:** <test files and count>
- **Migrated:** <count of migrated tests>

## Validation Log
| Entity | Tests | HTTP Match | Evidence | Status |
|--------|-------|------------|----------|--------|

Toutes les sections ne sont pas obligatoires — omettez les sections qui ne s'appliquent pas à une unité donnée (ex., une unité de secrets n'aura pas de sections Endpoints ou Database).