wp-dev: trabajo local con sitios WordPress en vivo

wp-dev: trabajo en un sitio WordPress en vivo localmente

Ejecuta wpsync como ${CLAUDE_PLUGIN_ROOT}/bin/wpsync (en adelante: wpsync). El desarrollador normalmente no es la persona que construyó esto, así que explica cada paso en palabras simples y di cuándo necesita algo de él.

Primero lee ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md. Allí se explica cómo mostrar progreso (una lista de verificación de los pasos de la fase), cómo preguntar (un diálogo de pregunta para cada decisión y cada espera), y qué hacer cuando la app no ofrece esos. Las líneas Ask abajo nombran los diálogos a usar.

Principios: verifica todo antes de cambiar nada, y reporta cada problema de una vez con su solución. Cada paso es seguro de re-ejecutar, así que después de cualquier interrupción el desarrollador dice "continue my wp-dev project" y tú retomas donde se detuvo.

Antes de nada: ¿puede wpsync ejecutarse?

wpsync se ejecuta en Bun, así que en un Mac que aún no tenga Bun, cualquier comando wpsync (incluyendo status, init y doctor) falla con "wpsync needs Bun" (código de salida 127). Verifica esto primero, antes de cualquier comando wpsync:

1. Ejecuta ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version. Si imprime una versión, continúa a "¿Dónde estamos?".
2. Si dice que wpsync necesita Bun, encuentra Homebrew: command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew.
   • Homebrew encontrado → brew install oven-sh/bun/bun (usando la ruta completa a brew si no está en PATH), luego ejecuta wpsync --version de nuevo.
   • Sin Homebrew → necesita al desarrollador (pide su contraseña de Mac). Explica que wpsync y las demás herramientas se instalan con Homebrew, abre una pestaña de Terminal con el comando de instalación desde https://brew.sh listo (ver guiding.md), y espera con el diálogo "Listo, verifícalo". Luego haz que Homebrew sea utilizable (ver "Homebrew justo después de instalarlo" en el paso 2) e instala Bun como se indicó arriba.

Si wpsync se ejecuta, no digas nada y continúa. Solo si tuviste que instalar Bun, dile al desarrollador en una línea que este fue el primer prerrequisito, y que wpsync doctor --local verificará el resto en el paso 2.

¿Dónde estamos?

Ejecuta wpsync status --json en la carpeta actual y guíate por su phase:

phase	Haz
no-project	Fase 1 desde el paso 1 (la puerta de inicio)
start-gate (carpeta creada en una sesión anterior)	Fase 1 desde el paso 2
connect, pull	Fase 1 desde el paso 2 (salta lo ya hecho)
work	Fase 2: el skill wp-work para cambios, wp-pull para actualizar, wp-publish para publicar
publish-pending	La última publicación espera finalización o reversión: ver wp-publish

Sea cual sea la fase: si status tiene un campo wordfence, el Wordfence de este sitio debe estar apagado mientras wpsync trabaja en él y encendido después. Sigue ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md.

En la fase 1, inicia (o, al reanudar, vuelve a mostrar) la Lista de verificación de configuración de guiding.md, con los pasos completados marcados, y comienza un capítulo "Configuración".

Fase 1: configurar la copia local

1. Puerta de inicio: la carpeta correcta, luego la dirección

La carpeta de una sesión se fija cuando comienza, así que el desarrollador inicia la sesión en la carpeta donde debe ir la copia local. Luego todo ocurre en esta misma sesión.

¿Está esta sesión en una carpeta utilizable? Mira la carpeta actual (ls -A):

• Vacía (o con solo .DS_Store o .claude): es la nueva carpeta del sitio. Continúa abajo.

• Cualquier otra cosa (Escritorio, carpeta personal, otro proyecto): no configures aquí. Envía esto, y detente:

  Para configurar un sitio, inicia una nueva sesión de Claude Code en la carpeta donde quieres su copia local: una carpeta nueva y vacía, por ejemplo ~/wp-sites/example.com.

  Inicia una nueva sesión, elige (o crea) esa carpeta, y establece el modo de permisos en Omitir permisos si prefieres no aprobar cada paso. (Publicar en el sitio en vivo siempre espera a que escribas su dominio en un diálogo). Luego di "new wp-dev project" allí.

En la nueva carpeta, pregunta una cosa, la dirección del sitio en vivo, en una línea corta:

¿Cuál es la dirección del sitio en vivo? Por ejemplo, https://ejemplo.com.

Si el nombre de la carpeta contiene un dominio (por ejemplo ejemplo.com-local), ofrécelo en su lugar: "¿Cuál es la dirección del sitio en vivo? Por el nombre de la carpeta supongo https://ejemplo.com."

Luego crea el proyecto aquí: wpsync init <site-url> --dir .. Escribe el CLAUDE.md de la carpeta, .claude/settings.json (pre-aprueba ddev, git, brew y los comandos de solo lectura de wpsync; publicar aún pregunta) y .wpsync.json marcado como pendiente. No contacta nada. Continúa directamente al paso 2. Esa configuración surte efecto desde la siguiente sesión en esta carpeta; si no estás en Omitir permisos, esta sesión puede preguntar un poco más seguido mientras tanto. No puedes detectar el modo de permisos, y no necesitas hacerlo.

2. Verificar este Mac

wpsync doctor --local lista todo de una vez. Muéstralo como la tabla de resultados en guiding.md. Instala lo que falte, en este orden:

• Tú puedes hacer: brew install ddev/ddev/ddev, brew install oven-sh/bun/bun, y Docker. Si ninguna aplicación Docker está instalada, pregunta "¿Qué aplicación Docker debo instalar en este Mac?": OrbStack (Recomendado: más ligero y rápido en un Mac, gratuito para uso personal) o Docker Desktop (el estándar; gratuito para uso personal y pequeñas empresas). Luego brew install --cask orbstack o brew install --cask docker. Docker instalado pero "no ejecutándose": inícialo tú mismo (open -a OrbStack o open -a Docker) y espera hasta un minuto a que docker info tenga éxito. Solo un primer lanzamiento (términos, contraseña) necesita al desarrollador; si docker info aún falla después de un minuto, un diálogo de primer lanzamiento está esperándolo.
• Necesita al desarrollador (una contraseña o un clic, que nunca haces por él): las herramientas de línea de comandos de Xcode (xcode-select --install), Homebrew (desde https://brew.sh), el primer lanzamiento de OrbStack o Docker Desktop, y mkcert -install. Abre una pestaña de Terminal con el comando listo (ver guiding.md), y espera con el diálogo "Listo, verifícalo". Cuando falten varios, enuméralos todos en un mensaje y espera una vez, no una vez por elemento.

mkcert es necesario (doctor lo reporta como FIX hasta que esté configurado). La dirección de la copia local es https://…ddev.site. Sin mkcert -install, Chrome rechaza esa dirección, y a través de http simple la página se carga sin sus estilos o imágenes (WordPress los enlaza por https). Eso parece una copia rota en el paso 7. Así que hazlo aquí, antes de la primera descarga: di que pedirá la contraseña del Mac, ejecuta mkcert -install en una pestaña de Terminal, y espera. Si se instala solo después de que DDEV haya iniciado (reanudando una configuración anterior), DDEV aún está usando su certificado no confiable: ejecuta ddev poweroff && ddev start en la carpeta del sitio, luego pídeles que recarguen la página.

Ejecuta wpsync doctor --local de nuevo hasta que nada diga FIX. Las notas pueden esperar, pero di lo que significan.

Homebrew justo después de instalarlo: en Macs Apple Silicon Homebrew se instala en /opt/homebrew, que no está en PATH hasta que se ejecuten las líneas de "Próximos pasos" del instalador. doctor reporta esto como "instalado en /opt/homebrew/bin/brew, pero aún no en PATH", con la línea para agregar a ~/.zprofile; nunca le digas que lo reinstale. Tu propio shell no recoge ~/.zprofile, así que en esta sesión prefija los comandos con eval "$(/opt/homebrew/bin/brew shellenv)" &&.

3. Verificar el sitio

wpsync doctor <site-url> (solo lectura). Antes de conectar, verifica que el sitio es WordPress con su API REST y que las Contraseñas de Aplicación están activadas. (Si el anfitrión pasa el encabezado Authorization solo se puede probar con una clave real, así que eso se verifica una vez que wpsync conecta). Muestra la tabla de resultados. Corrige o explica cada FIX antes de continuar; la mayoría son configuraciones del hosting o plugins de seguridad que el desarrollador debe preguntar a alguien: usa el diálogo "Cuando una verificación necesita a alguien más" en guiding.md.

Wordfence: si reporta Contraseñas de Aplicación "desactivadas, probablemente por Wordfence", sigue ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md ("Antes"): el desarrollador cambia una opción en wp-admin, y tú esperas con el diálogo "Listo, verifícalo" hasta que doctor lo confirme. Le recordarás que la active de nuevo en el paso 8.

4. Conectar

El skill wp-connect. Después ejecuta wpsync doctor <site-url> de nuevo: ahora también verifica el encabezado Authorization, multisitio, permisos de archivos, versiones y espacio en disco en este Mac y el servidor.

(wpsync new <site-url> ejecuta los pasos 2 a 7 de una vez y se detiene en lo primero que necesita al desarrollador; es útil para reanudar. Paso a paso, como aquí, explica más en el camino).

5. Descargar

El skill wp-pull (primera descarga: wpsync pull <site-url> --dir .). Crea el proyecto DDEV en https://<project>.ddev.site, que no necesita cambiar el archivo hosts. Los sitios grandes toman tiempo: ejecútalo como un trabajo largo (guiding.md).

6. Hacer que la copia sea segura para ejecutar

La copia tiene la base de datos del sitio en vivo: correos reales de clientes, tal vez claves de pago o API en vivo, tareas programadas. DDEV atrapa todo el correo saliente (míralo con ddev mailpit) y wpsync establece WP_ENVIRONMENT_TYPE=local. Mira los plugins activos en CLAUDE.md. Si alguno es un plugin de pago, envío, CRM, newsletter o webhook, enuméralos y pregunta "Estos plugins en la copia local de pueden seguir hablando con servicios reales. ¿Qué debemos hacer?": Guíame por el modo de prueba (Recomendado: tú los guías a la configuración de prueba o sandbox de cada plugin en el wp-admin local), o Déjalos como están (aceptan que la copia local puede alcanzar esos servicios).

Si ninguno de los plugins activos es así, no preguntes: dilo en una línea (nombrando cualquiera que solo envíe correo, que DDEV atrapa) y continúa.

7. Verificar

wpsync verify verifica páginas, wp-admin, enlaces permanentes, direcciones en vivo sobrantes, imágenes, y que los plugins y el tema coincidan con el sitio en vivo. Muestra la tabla de resultados.

Antes de investigar una verificación de página fallida, pregunta la página tú mismo una vez: curl -s -o /dev/null -w '%{http_code}' <localUrl>/. Si responde 200, la verificación probablemente se ejecutó mientras DDEV aún estaba iniciando (responde 502 por un momento después de ddev start): ejecuta wpsync verify una vez más antes de indagar en los registros.

Luego mira tú mismo: abre el sitio en vivo y la copia local lado a lado en Chrome (Claude en Chrome), la página de inicio y un par de páginas interiores, y compara. No juzgues la copia en el panel del navegador integrado de la app: bloquea los estilos, scripts e imágenes de una página *.ddev.site (ERR_BLOCKED_BY_CLIENT), por lo que incluso una copia perfecta se ve rota allí. Si Chrome no está disponible, verifica la página con curl y pídele al desarrollador que mire. Si algo difiere que no puedes explicar, descríbelo y pregunta: Arrégialo ahora (Recomendado), o Está bien, continúa.

Inicio de sesión local: la copia tiene los usuarios del sitio en vivo, así que el desarrollador inicia sesión en el wp-admin local con su contraseña del sitio en vivo.

8. Entregar

Lee el CLAUDE.md del sitio ahora, para que sus reglas se apliquen de aquí en adelante.

Primero, si este sitio usa Wordfence (wpsync status --json muestra "wordfence": "switched-off"): la configuración ya no necesita el sitio en vivo, así que sigue ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md ("Cuando wpsync haya terminado") para que el desarrollador active de nuevo la protección de Wordfence, espera, y confirma con wpsync status. Haz esto antes de la línea de entrega, para que el último paso del desarrollador sea comenzar a trabajar en lugar de otra tarea.

Luego abre el sitio local en Chrome y finaliza la lista de verificación. Termina la configuración exactamente con esto, en negrita, en su propia línea, como lo último en tu mensaje (nada después; cualquier otra nota, como iniciar sesión, va antes):

La copia local del sitio está lista en https://{dominio del sitio local}. Revísala y luego dime cambios que te gustaría comenzar a hacer.

con https://{dominio del sitio local} reemplazado por el localUrl de .wpsync.json. Justo antes, una línea sobre iniciar sesión: el wp-admin local acepta su nombre de usuario y contraseña del sitio en vivo.