rp-discovery

Découvrir et documenter le schéma de la plateforme source pour le projet de migration actif.

Purpose

Utilisez cette skill pour inspecter le système source, identifier les entités, les relations, les champs, les identifiants, les médias, le contenu enrichi et les contraintes spécifiques à la plateforme. Les exemples incluent Shopify, WordPress, WooCommerce et les plateformes CMS personnalisées.

Cette skill possède le processus de découverte indépendant de la plateforme et son contrat de sortie (source-profile.md + source-schema.json). Les détails spécifiques à la plateforme — comment capturer une source donnée, son modèle d'authentification, les particularités REST — vivent dans une source adapter skill dédiée, pas ici. Pour WordPress / WooCommerce, cet adaptateur est rp-source-wordpress. Pour supporter une nouvelle plateforme, ajoutez un adaptateur frère (ex. rp-source-shopify) et laissez cette skill inchangée.

Inputs

Les entrées attendues peuvent inclure :

migrations/<project>/orchestration/run.json
migrations/<project>/orchestration/decisions.json
URL du site/app source
nom de la plateforme source quand il ne peut pas être déduit
mode d'acquisition source quand la plateforme offre plusieurs chemins de lecture
documentation API source
identifiants, tokens ou fichiers de dump locaux quand disponibles
fichiers d'export quand l'exécution est basée sur fichier plutôt que sur URL
projet actuel sous migrations/<project>/
config locale du projet sous migrations/<project>/config/

Config gate before capture

Avant de lancer la capture source, vérifiez les fichiers config locaux créés par replatform :

config/wix.env doit toujours exister avec les clés WIX_SITE_STRATEGY, WIX_SITE_ID et WIX_AUTH_TOKEN, même si la découverte elle-même n'utilise pas encore les credentials Wix.
config/source.<platform>.env doit exister une fois que la plateforme source est connue. Pour WordPress c'est config/source.wordpress.env.

Si une clé requise est manquante ou vide, demandez cette valeur à l'utilisateur et remplissez le fichier config pour lui avant de continuer. Posez une valeur à la fois. Ne réaffusez jamais les valeurs secrètes à l'utilisateur ; signalez uniquement présent/manquant.

Traitez migrations/<project>/config/*.env comme contenant des secrets une fois qu'ils peuvent contenir des valeurs réelles. Ne les inspectez pas avec des lectures de fichier complet qui répercutent le contenu dans la sortie d'outil. Utilisez uniquement des vérifications sécurisées : existence, noms de clés requises, et statut present / blank / missing.

Site creation precedence

Si cette skill rencontre des directives Wix conflictuelles sur la façon de créer une destination new site + headless, le contrat de migration de replatform gagne.

Routez la création de destination headless vers le Wix CLI headless scaffold défini dans replatform → "Headless site creation" (npm create @wix/new@latest headless). C'est la façon vérifiée d'obtenir un vrai site headless ; l'API Projects au niveau du compte est dépréciée pour ce workflow (elle produisait des sites non-headless).
La découverte est côté source et ne crée pas le site elle-même — déférez simplement à cette section.

Workflow

Confirmez le projet actif sous migrations/<project>/.
Commencez par l'URL source quand disponible et essayez d'identifier vous-même la plateforme source avant de demander à l'utilisateur. Utilisez des signaux légers tels qu'un index REST, des headers, des marqueurs HTML/application ou des patterns de route spécifiques à la plateforme. Posez la question à l'utilisateur seulement si la détection reste inconclusive.
Une fois la plateforme déduite, résolvez le mode d'acquisition avant de demander les credentials source quand la plateforme a des chemins de lecture matériellement différents.
- Pour les migrations Shopify basées sur URL, demandez si utiliser l'Admin API ou seulement les données storefront publiquement disponibles.
- Pour les migrations WordPress / WooCommerce basées sur URL, demandez si importer le contenu public uniquement ou aussi inclure les données privées/authentifiées.
- Seule la branche aussi inclure les données privées/authentifiées de WordPress / WooCommerce doit déclencher une demande de credentials. La branche contenu public uniquement proceed sans credentials et doit être décrite comme limitée aux données publiques. Pour WooCommerce, cette branche doit tout de même explorer les routes publiques Store API comme /wc/store/v1/products et /wc/store/v1/products/categories avant de déclarer le commerce hors de portée. Traitez l'ingestion fichier/export comme un flux séparé qui commence par des fichiers fournis par l'utilisateur au lieu d'une sonde URL ; n'offrez pas les exports comme une troisième option dans la question mode d'acquisition basée sur URL.
Sélectionnez ensuite la skill source adapter correspondante (ex. rp-source-wordpress pour WordPress / WooCommerce, rp-source-csv quand l'exécution est basée fichier). Si aucun adaptateur n'existe pour la plateforme, capturez les entités manuellement en suivant le même contrat de sortie.
- Les exécutions basées fichier (sourceMode=files_only, sourcePlatform=csv) utilisent rp-source-csv indépendamment du système qui a produit les fichiers ; cet adaptateur identifie le vendeur d'origine à partir de la ligne d'en-tête. Il n'y a pas de question mode d'acquisition et pas de demande de credentials pour ce chemin.
Exécutez l'étape capture de l'adaptateur pour produire un dump brut capturé par machine sous <migrations-root>/<project>/data/<source>-discovery/. Pour WordPress, le script de capture vit dans rp-source-wordpress/scripts/ — exécutez-le depuis le répertoire de cette skill (voir rp-source-wordpress section Capture et CONVENTIONS.md). L'adaptateur possède la mécanique de capture, le modèle d'authentification et les particularités de plateforme ; cette skill consomme sa sortie. Pour les longues exécutions, passez --progress-log <path> et consultez-le selon CONVENTIONS.md#progress-log-polling.
- Distinguez les entités supportées (annoncées par la source) des entités utilisées (celles avec recordCount > 0). Les entités annoncées mais vides doivent être signalées, pas mappées comme si elles contenaient des données.
- Une capture faite sans credentials est généralement incomplète (entités gatées, champs privés, PII retournent 401/403). Ne traitez pas une capture non-authentifiée comme autoritaire — l'adaptateur documente l'authentification qu'une exécution complète requiert.
- Pour les captures WordPress / WooCommerce, lisez data/wp-discovery/skipped-routes.json quand présent. Traitez-le comme l'audit trail de scope route canonical : les routes ignorées sont des preuves, pas des entités source, sauf si elles ont été explicitement force-incluses par une override auditée.
- Pour les captures CSV, le script de capture vit dans rp-source-csv/scripts/csv-discovery.js et prend l'ensemble de fichiers entier en une seule exécution (--file est répétable) pour que les rôles et fichiers divisés se résolvent ensemble. Lisez data/csv-discovery/fileset.json — c'est la capture machine canonical, et source-schema.json en est synthétisé :
  - portez sourceFiles[] (avec role, vendor, partOf), vendor, dialect, drift, mappingHints et csvInputRoot dans sourceMeta, en gardant les chemins de fichier relatifs à csvInputRoot pour que le projet reste mobile ;
  - donnez à chaque entité une origin (file-rows | row-group | column-values) avec les paramètres que cette origine requiert, et réglez hierarchical: true sur les entités dérivées imbriquées pour que la règle faithfulness-ledger du mapper se déclenche ;
  - surfacez drift.unmappedColumns comme unknowns pour que le mapper les gère explicitement ;
  - honorez halt: true. Une disposition ambiguë, un rôle de fichier inconnu, des headers de fichier divisé en conflit ou une détection de vendeur presque-manquée est une question pour l'utilisateur, pas quelque chose à résoudre en choisissant le candidat le plus bien noté. Le texte d'avertissement nomme la décision à porter devant eux.
Capturez les détails de schéma au niveau du champ, incluant type, cardinalité, requiredness et valeurs d'exemple.
Quand la connaissance Wix groupée reconnaît une route source ou une entité source, annotez l'entité découverte avec sourceMeta.candidateTargetRefs[] comme ["stores/product"]. La découverte doit toujours enregistrer seulement les faits source ; ces refs sont des hints mapper, pas des décisions cible.
Notez les contraintes opérationnelles telles que la pagination, les rate limits, le modèle d'authentification et les options de sync incrémentale. Si l'URL base source ou les URLs média/fichier découvertes utilisent localhost, 127.0.0.1 ou un autre hôte privé uniquement, enregistrez une note de reachabilité média dans source-profile.md. Localhost est ok pour la découverte et les lectures source locales, mais l'import Wix Media est basé sur URL et les serveurs Wix ne peuvent pas récupérer le localhost de l'utilisateur. C'est une étape de préparation optionnelle et, autant que nous le savons aujourd'hui, ne concerne que l'import média. Énoncez les deux choix acceptables :
- exposez la source avec un tunnel HTTPS public comme ngrok avant l'import média en direct
- sautez/déférez l'import média en continuant les entités non-média
Incluez des instructions de setup concises ngrok quand pertinent :
```
brew install ngrok
ngrok config add-authtoken "<YOUR_AUTHTOKEN>"
ngrok http 8090
export WP_BASE_URL=https://<id>.ngrok-free.app
```
Synthétisez la capture brute dans les artefacts normalisés ci-dessous.

Artifacts to create or update

migrations/<project>/discovery/run.json
migrations/<project>/discovery/entities/
migrations/<project>/discovery/warnings.json
migrations/<project>/discovery/llm-handoff.json
migrations/<project>/orchestration/checkpoints.json
migrations/<project>/data/<source>-discovery/ : sortie brute capturée par machine de la source adapter skill. Traitée comme preuve, pas un artefact de hand-off — les skills en aval y font référence pour la traçabilité mais ne la lisent pas en masse.
migrations/<project>/source-profile.md : plateforme source, méthode d'accès, limites, authentification et notes opérationnelles. Synthétisée à partir de la capture brute. Capturez les faits opérationnels que l'adaptateur documente (modèle d'authentification, pagination, rate limits) pour que rp-import-codegen les ait sans les re-dériver.
migrations/<project>/source-schema.json : schéma lisible par machine pour entités et champs. Synthétisé à partir de la capture brute — ceci et source-profile.md sont le hand-off canonical vers rp-mapper. Incluez des pointeurs de traçabilité pour que le mapper puisse approfondir le fichier brut d'une entité spécifique quand nécessaire :
- top-level rawDiscovery : chemin relatif au répertoire de capture brute, ex. data/wp-discovery/.
- per-entity rawFile : nom de fichier dans ce répertoire, ex. wp-v2--posts.md.
- per-entity recordCount et inUse pour que les consommateurs puissent distinguer entités supportées vs. réellement utilisées.
- per-entity relations dérivées des relations déclarées par la source dans la capture brute, pour que les relations soient soutenues par preuve plutôt que devinées. Chaque relation doit porter un pointeur evidence vers le signal source dont il provient.
- Pour WordPress / WooCommerce, synthétisez les entités seulement à partir des artefacts de route backend_data et backend_metadata acceptés échantillonnés. Ne synthétisez pas d'entités à partir des routes listées dans skipped-routes.json sauf si l'enregistrement skipped-route a includedByOverride: true ; dans ce cas, incluez originalDiscoveryCategory, includedByOverride: true et overrideReason quand présents dans l'entité sourceMeta.
- Suivez le source-schema.example.json de l'adaptateur pour la forme (ex. rp-source-wordpress/source-schema.example.json). C'est un template à suivre, pas un schéma strict à valider contre — gardez le noyau agnostique de plateforme stable et poussez les particularités de plateforme dans le blob sourceMeta ouvert de chaque entité.
Notes de support optionnelles sous migrations/<project>/research/ si nécessaire.

Output quality rules

Séparez les faits confirmés des hypothèses.
Enregistrez le volume par entité (compte d'enregistrements) pour que les skills en aval sachent ce que le site utilise réellement, pas seulement ce qu'il supporte.
Préservez exactement les identifiants spécifiques à la source.
Incluez assez de détail pour le mapping en aval et la génération de code.
Signalez les inconnues explicitement au lieu d'inventer la structure.