AlexMaghen/wp-dev

wp-dev : travailler sur un site WordPress en direct localement

Exécutez wpsync comme ${CLAUDE_PLUGIN_ROOT}/bin/wpsync (ci-après : wpsync). Le développeur n'est généralement pas la personne qui a construit ce projet, alors expliquez chaque étape en termes simples et dites quand une action est nécessaire de sa part.

Lisez d'abord ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md. Ce fichier explique comment afficher la progression (une liste de contrôle des étapes de la phase), comment poser des questions (une boîte de dialogue pour chaque décision et chaque attente), et que faire lorsque l'application ne propose pas ces fonctionnalités. Les lignes Demander ci-dessous indiquent les dialogues à utiliser.

Principes : vérifiez tout avant de modifier quoi que ce soit, et signalez chaque problème immédiatement avec sa solution. Chaque étape peut être réexécutée en toute sécurité, donc après une interruption, le développeur dit « continuer mon projet wp-dev » et vous reprenez là où vous vous êtes arrêté.

Avant tout : wpsync peut-il s'exécuter ?

wpsync fonctionne sur Bun. Sur un Mac qui n'a pas encore Bun, chaque commande wpsync (y compris status, init et doctor) échoue avec le message « wpsync needs Bun » (code de sortie 127). Vérifiez cela d'abord, avant toute commande wpsync :

1. Exécutez ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version. S'il affiche un numéro de version, passez à « Où en sommes-nous ? ».
2. S'il indique que wpsync a besoin de Bun, trouvez Homebrew : command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew.
   • Homebrew trouvé → brew install oven-sh/bun/bun (en utilisant le chemin complet vers brew s'il n'est pas dans le PATH), puis exécutez à nouveau wpsync --version.
   • Pas de Homebrew → cela nécessite l'intervention du développeur (il demande son mot de passe Mac). Expliquez que wpsync et les autres outils sont installés avec Homebrew, ouvrez un onglet de terminal avec la commande d'installation de https://brew.sh prête (voir guiding.md), et attendez avec la boîte de dialogue « Fait, vérifiez ». Ensuite, rendez Homebrew utilisable (voir « Homebrew juste après son installation » à l'étape 2) et installez Bun comme ci-dessus.

Si wpsync s'exécute, ne dites rien et continuez. Si vous avez dû installer Bun, informez le développeur en une ligne que c'était la première condition préalable et que wpsync doctor --local vérifiera le reste à l'étape 2.

Où en sommes-nous ?

Exécutez wpsync status --json dans le dossier actuel et suivez la valeur de son champ phase :

phase	Action
no-project	Phase 1 à partir de l'étape 1 (la porte de départ)
start-gate (dossier créé lors d'une session précédente)	Phase 1 à partir de l'étape 2
connect, pull	Phase 1 à partir de l'étape 2 (elle ignore ce qui est déjà fait)
work	Phase 2 : la compétence wp-work pour les modifications, wp-pull pour actualiser, wp-publish pour mettre en ligne
publish-pending	La dernière publication attend une finalisation ou un retour en arrière : voir wp-publish

Quelle que soit la phase : si status contient un champ wordfence, ce site doit désactiver Wordfence pendant que wpsync travaille dessus, puis le réactiver. Suivez ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md.

En phase 1, commencez (ou, lors de la reprise, réaffichez) la liste de vérification de configuration de guiding.md, avec les étapes terminées cochées, et démarrez un chapitre « Configuration ».

Phase 1 : configurer la copie locale

1. Porte de départ : le bon dossier, puis l'adresse

Le dossier d'une session est fixé au démarrage, donc le développeur démarre la session dans le dossier où doit se trouver la copie locale. Ensuite, tout se passe dans cette session unique.

Cette session est-elle dans un dossier utilisable ? Regardez le dossier actuel (ls -A) :

• Vide (ou contenant uniquement .DS_Store ou .claude) : c'est le nouveau dossier du site. Continuez ci-dessous.

• Autre chose (Bureau, dossier personnel, autre projet) : ne configurez pas ici. Envoyez ce message, puis arrêtez :

  Pour configurer un site, démarrez une nouvelle session Claude Code dans le dossier où vous souhaitez sa copie locale : un nouveau dossier vide, par exemple ~/wp-sites/example.com.

  Démarrez une nouvelle session, choisissez (ou créez) ce dossier et définissez le mode d'autorisation sur Contourner les autorisations si vous préférez ne pas approuver chaque étape. (La publication sur le site en direct attend toujours que vous tapiez son domaine dans une boîte de dialogue.) Ensuite, dites « nouveau projet wp-dev » dans ce dossier.

Dans le nouveau dossier, demandez une chose, l'adresse du site en direct, en une courte ligne :

Quelle est l'adresse du site en direct ? Par exemple, https://example.com.

Si le nom du dossier contient un domaine (par exemple example.com-local), proposez-le à la place : « Quelle est l'adresse du site en direct ? D'après le nom du dossier, je dirais https://example.com. »

Ensuite, créez le projet ici : wpsync init <site-url> --dir .. Cela écrit le fichier CLAUDE.md du dossier, .claude/settings.json (pré-approuve ddev, git, brew et les commandes wpsync en lecture seule ; la publication demande toujours) et .wpsync.json marqué comme en attente. Cela ne contacte rien. Passez directement à l'étape 2. Ces paramètres prennent effet à partir de la prochaine session dans ce dossier ; si vous n'êtes pas en mode Contourner les autorisations, cette session peut demander un peu plus souvent entre-temps. Vous ne pouvez pas détecter le mode d'autorisation et ce n'est pas nécessaire.

2. Vérifier ce Mac

wpsync doctor --local liste tout à la fois. Affichez-le sous forme de tableau de résultats dans guiding.md. Installez ce qui manque, dans cet ordre :

• Vous pouvez faire : brew install ddev/ddev/ddev, brew install oven-sh/bun/bun et Docker. Si aucune application Docker n'est installée, demandez « Quelle application Docker dois-je installer sur ce Mac ? » : OrbStack (Recommandé : plus léger et plus rapide sur un Mac, gratuit pour un usage personnel) ou Docker Desktop (le standard ; gratuit pour un usage personnel et les petites entreprises). Ensuite, brew install --cask orbstack ou brew install --cask docker. Docker installé mais « ne tourne pas » : démarrez-le vous-même (open -a OrbStack ou open -a Docker) et attendez jusqu'à une minute que docker info réussisse. Seul un premier lancement (conditions, mot de passe) nécessite le développeur ; si docker info échoue encore après une minute, une boîte de dialogue de premier lancement l'attend.
• Nécessite le développeur (un mot de passe ou un clic, que vous n'effectuez jamais à sa place) : les outils de ligne de commande Xcode (xcode-select --install), Homebrew (depuis https://brew.sh), le premier lancement d'OrbStack ou Docker Desktop, et mkcert -install. Ouvrez un onglet de terminal avec la commande prête (voir guiding.md) et attendez avec la boîte de dialogue « Fait, vérifiez ». Lorsque plusieurs éléments manquent, listez-les tous dans un seul message et attendez une seule fois, pas une fois par élément.

mkcert est requis (doctor le signale comme FIX jusqu'à ce qu'il soit configuré). L'adresse de la copie locale est https://…ddev.site. Sans mkcert -install, Chrome refuse cette adresse, et en http simple, la page se charge sans ses styles ni images (WordPress les lie en https). Cela ressemble à une copie cassée à l'étape 7. Faites-le donc ici, avant la première récupération : dites que cela demandera le mot de passe Mac du développeur, exécutez mkcert -install dans un onglet de terminal et attendez. S'il est installé seulement après que DDEV a démarré (reprise d'une configuration plus ancienne), DDEV utilise toujours son certificat non fiable : exécutez ddev poweroff && ddev start dans le dossier du site, puis demandez au développeur de recharger la page.

Exécutez wpsync doctor --local à nouveau jusqu'à ce que rien ne mentionne FIX. Les notes peuvent attendre, mais dites ce qu'elles signifient.

Homebrew juste après son installation : sur les Mac Apple Silicon, Homebrew s'installe dans /opt/homebrew, qui n'est pas dans le PATH tant que les lignes « Next steps » de l'installateur ne sont pas exécutées. doctor signale ceci comme « installé dans /opt/homebrew/bin/brew, mais pas encore dans le PATH », avec la ligne à ajouter à ~/.zprofile ; n'envoyez jamais le développeur le réinstaller. Votre propre shell ne lit pas ~/.zprofile, donc dans cette session, préfixez les commandes avec eval "$(/opt/homebrew/bin/brew shellenv)" &&.

3. Vérifier le site

wpsync doctor <site-url> (lecture seule). Avant de se connecter, il vérifie que le site est WordPress avec son API REST et que les mots de passe d'application sont activés. (Le fait que l'hôte transmette l'en-tête Authorization ne peut être testé qu'avec une vraie clé, donc cela est vérifié une fois que wpsync se connecte.) Affichez le tableau des résultats. Corrigez ou expliquez chaque FIX avant de continuer ; la plupart sont des paramètres d'hébergement ou de plugin de sécurité que le développeur doit demander à quelqu'un : utilisez la boîte de dialogue « Quand une vérification nécessite quelqu'un d'autre » dans guiding.md.

Wordfence : s'il signale que les mots de passe d'application sont « désactivés, probablement par Wordfence », suivez ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md (« Avant ») : le développeur désactive un paramètre dans wp-admin, et vous attendez avec la boîte de dialogue « Fait, vérifiez » jusqu'à ce que doctor confirme. Vous lui rappellerez de le réactiver à l'étape 8.

4. Connexion

La compétence wp-connect. Ensuite, exécutez wpsync doctor <site-url> à nouveau : il vérifie maintenant aussi l'en-tête Authorization, le multisite, les permissions des fichiers, les versions et l'espace disque sur ce Mac et le serveur.

(wpsync new <site-url> exécute les étapes 2 à 7 en une seule fois et s'arrête au premier élément nécessitant le développeur ; c'est pratique pour reprendre. Étape par étape, comme ici, explique plus en cours de route.)

5. Récupération

La compétence wp-pull (première récupération : wpsync pull <site-url> --dir .). Elle crée le projet DDEV à https://<project>.ddev.site, ce qui ne nécessite aucune modification du fichier hosts. Les grands sites prennent du temps : exécutez-la comme une tâche longue (guiding.md).

6. Rendre la copie sécurisée pour l'exécution

La copie contient la base de données du site en direct : de vrais e-mails de clients, peut-être des clés API ou de paiement en direct, des tâches planifiées. DDEV intercepte tous les e-mails sortants (consultez-les avec ddev mailpit) et wpsync définit WP_ENVIRONMENT_TYPE=local. Examinez les plugins actifs dans CLAUDE.md. Si l'un d'eux est un plugin de paiement, d'expédition, CRM, newsletter ou webhook, listez-les et demandez « Ces plugins sur la copie locale de peuvent encore communiquer avec des services réels. Que devons-nous faire ? » : Expliquez-moi le mode test (Recommandé : vous guidez le développeur vers le paramètre de test ou de bac à sable de chaque plugin dans le wp-admin local), ou Laissez-les tels quels (ils acceptent que la copie locale puisse atteindre ces services).

Si aucun des plugins actifs n'est de ce type, ne demandez pas : dites-le en une ligne (en nommant ceux qui envoient seulement des e-mails, que DDEV intercepte) et continuez.

7. Vérification

wpsync verify vérifie les pages, wp-admin, les permaliens, les adresses en direct résiduelles, les images, et que les plugins et le thème correspondent au site en direct. Affichez le tableau des résultats.

Avant d'investiguer un échec de vérification de page, testez la page vous-même une fois : curl -s -o /dev/null -w '%{http_code}' <localUrl>/. Si elle répond 200, la vérification a probablement été exécutée pendant que DDEV était encore en cours de démarrage (il répond 502 pendant un moment après ddev start) : exécutez wpsync verify une fois de plus avant de fouiller les journaux.

Ensuite, regardez vous-même : ouvrez le site en direct et la copie locale côte à côte dans Chrome (Claude dans Chrome), la page d'accueil et quelques pages internes, et comparez. Ne jugez pas la copie dans le panneau de navigation intégré de l'application : il bloque les styles, scripts et images d'une page *.ddev.site (ERR_BLOCKED_BY_CLIENT), donc même une copie parfaite y apparaît cassée. Si Chrome n'est pas disponible, vérifiez la page avec curl et demandez au développeur de regarder. Si quelque chose diffère que vous ne pouvez pas expliquer, décrivez-le et demandez : Corriger maintenant (Recommandé), ou C'est bon, continuez.

Connexion locale : la copie contient les utilisateurs du site en direct, donc le développeur se connecte au wp-admin local avec son mot de passe en direct.

8. Remise

Lisez maintenant le fichier CLAUDE.md du site, afin que ses règles s'appliquent à partir de maintenant.

D'abord, si ce site utilise Wordfence (wpsync status --json affiche "wordfence": "switched-off") : la configuration n'a plus besoin du site en direct, donc suivez ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md (« Quand wpsync a terminé ») pour que le développeur réactive la protection Wordfence, attendez, et confirmez avec wpsync status. Faites cela avant la ligne de remise, afin que la dernière étape du développeur soit de commencer le travail plutôt qu'une autre corvée.

Ensuite, ouvrez le site local dans Chrome et terminez la liste de contrôle. Terminez la configuration exactement par ceci, en gras, sur sa propre ligne, comme dernière chose dans votre message (rien après ; toutes les autres notes, comme la connexion, vont avant) :

La copie locale du site est prête à l'adresse https://{domaine du site local}. Vérifiez-la, puis dites-moi les modifications que vous souhaitez commencer à apporter.

en remplaçant https://{domaine du site local} par le localUrl de .wpsync.json. Juste avant, une ligne sur la connexion : le wp-admin local accepte le nom d'utilisateur et le mot de passe du site en direct.