AlexMaghen/wp-dev

wp-dev: trabalhar em um site WordPress ativo localmente

Execute o wpsync como ${CLAUDE_PLUGIN_ROOT}/bin/wpsync (abaixo: wpsync). O desenvolvedor geralmente não é a pessoa que construiu isso, então explique cada etapa em palavras simples e diga quando algo precisa dele.

Primeiro leia ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/guiding.md. Ele diz como mostrar o progresso (uma lista de verificação das etapas da fase), como perguntar (um diálogo de perguntas para cada decisão e cada espera) e o que fazer quando o aplicativo não oferece essas opções. As linhas Perguntar abaixo nomeiam os diálogos a usar.

Princípios: verifique tudo antes de alterar qualquer coisa e relate cada problema de uma vez com sua correção. Cada etapa é segura para ser reexecutada, portanto, após qualquer interrupção, o desenvolvedor diz "continue my wp-dev project" e você continua de onde parou.

Antes de tudo: o wpsync pode ser executado?

O wpsync é executado no Bun, então em um Mac que ainda não tem Bun, todo comando wpsync (incluindo status, init e doctor) falha com "wpsync needs Bun" (código de saída 127). Verifique isso primeiro, antes de qualquer comando wpsync:

1. Execute ${CLAUDE_PLUGIN_ROOT}/bin/wpsync --version. Se imprimir uma versão, vá para "Onde estamos?".
2. Se disser que wpsync precisa de Bun, encontre o Homebrew: command -v brew || ls /opt/homebrew/bin/brew /usr/local/bin/brew.
   • Homebrew encontrado → brew install oven-sh/bun/bun (usando o caminho completo para brew se não estiver no PATH), depois execute wpsync --version novamente.
   • Sem Homebrew → precisa do desenvolvedor (pede a senha do Mac dele). Explique que o wpsync e as outras ferramentas são instalados com o Homebrew, abra uma aba do Terminal com o comando do instalador de https://brew.sh pronto (veja guiding.md) e aguarde com o diálogo "Done, check it". Em seguida, torne o Homebrew utilizável (veja "Homebrew logo após instalá-lo" no passo 2) e instale o Bun como acima.

Se o wpsync for executado, não diga nada sobre isso e prossiga. Somente se você teve que instalar o Bun, diga ao desenvolvedor em uma linha que este foi o primeiro pré-requisito e que wpsync doctor --local verificará o restante no passo 2.

Onde estamos?

Execute wpsync status --json na pasta atual e siga de acordo com sua phase:

phase	Faça
no-project	Fase 1 a partir do passo 1 (o portão inicial)
start-gate (pasta criada em uma sessão anterior)	Fase 1 a partir do passo 2
connect, pull	Fase 1 a partir do passo 2 (pula o que já foi feito)
work	Fase 2: a skill wp-work para alterações, wp-pull para atualizar, wp-publish para publicar
publish-pending	A última publicação está aguardando finalização ou reversão: veja wp-publish

Qualquer que seja a fase: se status tiver um campo wordfence, o Wordfence deste site deve ser desligado enquanto o wpsync trabalha nele e religado depois. Siga ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md.

Na fase 1, inicie (ou, ao retomar, mostre novamente) a lista de verificação de Configuração de guiding.md, com as etapas concluídas marcadas, e inicie um capítulo "Configuração".

Fase 1: configurar a cópia local

1. Portão inicial: a pasta certa, depois o endereço

A pasta de uma sessão é fixa quando ela começa, então o desenvolvedor inicia a sessão na pasta onde a cópia local deve ficar. Então tudo acontece nesta única sessão.

Esta sessão está em uma pasta utilizável? Veja a pasta atual (ls -A):

• Vazia (ou contendo apenas .DS_Store ou .claude): é a nova pasta do site. Vá abaixo.

• Qualquer outra coisa (Área de Trabalho, a pasta pessoal, outro projeto): não configure aqui. Envie isto e pare:

  Para configurar um site, inicie uma nova sessão do Claude Code na pasta onde você quer sua cópia local: uma pasta nova e vazia, por exemplo ~/wp-sites/example.com.

  Inicie uma nova sessão, escolha (ou crie) essa pasta e defina o modo de permissão como Bypass permissions se preferir não aprovar cada etapa. (Publicar no site ativo sempre aguarda você digitar o domínio dele em um diálogo.) Depois, diga "new wp-dev project" lá.

Na nova pasta, pergunte uma coisa, o endereço do site ativo, em uma linha curta:

Qual é o endereço do site ativo? Por exemplo, https://example.com.

Se o nome da pasta contiver um domínio (por exemplo, example.com-local), ofereça-o: "Qual é o endereço do site ativo? Pelo nome da pasta, eu diria https://example.com."

Depois, crie o projeto aqui: wpsync init <url-do-site> --dir .. Ele escreve o CLAUDE.md da pasta, .claude/settings.json (pré-aprova ddev, git, brew e os comandos wpsync somente leitura; publicar ainda pergunta) e .wpsync.json marcado como pendente. Não contacta nada. Vá direto para o passo 2. Essas configurações entram em vigor a partir da próxima sessão nesta pasta; se você não estiver no modo Bypass permissions, esta sessão pode pedir um pouco mais frequentemente. Você não pode detectar o modo de permissão e não precisa.

2. Verificar este Mac

wpsync doctor --local lista tudo de uma vez. Mostre como a tabela de resultados em guiding.md. Instale o que estiver faltando, nesta ordem:

• Você pode fazer: brew install ddev/ddev/ddev, brew install oven-sh/bun/bun e Docker. Se nenhum aplicativo Docker estiver instalado, pergunte "Qual aplicativo Docker devo instalar neste Mac?": OrbStack (Recomendado: mais leve e rápido em um Mac, gratuito para uso pessoal) ou Docker Desktop (o padrão; gratuito para uso pessoal e pequenas empresas). Depois brew install --cask orbstack ou brew install --cask docker. Docker instalado, mas "não em execução": inicie você mesmo (open -a OrbStack ou open -a Docker) e aguarde até um minuto para que docker info seja bem-sucedido. Apenas a primeira execução (termos, senha) precisa do desenvolvedor; se docker info ainda falhar após um minuto, um diálogo de primeira execução está aguardando por ele.
• Precisa do desenvolvedor (uma senha ou um clique, que você nunca faz por ele): as ferramentas de linha de comando do Xcode (xcode-select --install), Homebrew (de https://brew.sh), a primeira execução do OrbStack ou Docker Desktop e mkcert -install. Abra uma aba do Terminal com o comando pronto (veja guiding.md) e aguarde com o diálogo "Done, check it". Quando vários estiverem faltando, liste todos em uma mensagem e aguarde uma vez, não uma vez por item.

mkcert é obrigatório (doctor relata como FIX até ser configurado). O endereço da cópia local é https://…ddev.site. Sem mkcert -install, o Chrome recusa esse endereço e, em http simples, a página carrega sem estilos ou imagens (o WordPress os vincula via https). Isso parece uma cópia quebrada no passo 7. Portanto, faça isso aqui, antes do primeiro pull: diga que pedirá a senha do Mac, execute mkcert -install em uma aba do Terminal e aguarde. Se for instalado apenas depois que o DDEV foi iniciado (retomando uma configuração mais antiga), o DDEV ainda está usando seu certificado não confiável: execute ddev poweroff && ddev start na pasta do site, depois peça para recarregar a página.

Execute wpsync doctor --local novamente até que nada diga FIX. Observações podem esperar, mas diga o que significam.

Homebrew logo após instalá-lo: em Macs Apple Silicon, o Homebrew vai para /opt/homebrew, que não está no PATH até que as linhas "Next steps" do instalador sejam executadas. doctor relata isso como "installed at /opt/homebrew/bin/brew, but not on the PATH yet", com a linha para adicionar a ~/.zprofile; nunca o envie para reinstalar. Seu próprio shell não pega ~/.zprofile, portanto, nesta sessão, prefixe os comandos com eval "$(/opt/homebrew/bin/brew shellenv)" &&.

3. Verificar o site

wpsync doctor <url-do-site> (somente leitura). Antes de conectar, verifica se o site é WordPress com sua REST API e se as Senhas de Aplicativo estão ativas. (Se o host passa o cabeçalho Authorization só pode ser testado com uma chave real, portanto isso é verificado quando o wpsync se conectar.) Mostre a tabela de resultados. Corrija ou explique cada FIX antes de prosseguir; a maioria são configurações de hospedagem ou plugin de segurança que o desenvolvedor precisa perguntar a alguém: use o diálogo "When a check needs someone else" em guiding.md.

Wordfence: se ele relatar Senhas de Aplicativo "desligadas, provavelmente pelo Wordfence", siga ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md ("Before"): o desenvolvedor desliga uma configuração no wp-admin e você aguarda com o diálogo "Done, check it" até que doctor confirme. Você lembrará de religá-la no passo 8.

4. Conectar

A skill wp-connect. Depois execute wpsync doctor <url-do-site> novamente: agora também verifica o cabeçalho Authorization, multisite, permissões de arquivo, versões e espaço em disco neste Mac e no servidor.

(wpsync new <url-do-site> executa os passos 2 a 7 de uma só vez e para na primeira coisa que precisa do desenvolvedor; é útil para retomar. Passo a passo, como aqui, explica mais ao longo do caminho.)

5. Baixar

A skill wp-pull (primeiro pull: wpsync pull <url-do-site> --dir .). Ela cria o projeto DDEV em https://<projeto>.ddev.site, que não precisa de alteração no arquivo hosts. Sites grandes levam um tempo: execute como um job longo (guiding.md).

6. Tornar a cópia segura para execução

A cópia tem o banco de dados do site ativo: e-mails reais de clientes, talvez chaves de pagamento ou API ativas, jobs agendados. O DDEV captura todos os e-mails de saída (veja com ddev mailpit) e o wpsync define WP_ENVIRONMENT_TYPE=local. Veja os plugins ativos em CLAUDE.md. Se algum for um plugin de pagamento, envio, CRM, newsletter ou webhook, liste-os e pergunte "Estes plugins na cópia local de <domínio> ainda podem falar com serviços reais. O que devemos fazer?": Me oriente no modo de teste (Recomendado: você os guia para a configuração de teste ou sandbox de cada plugin no wp-admin local) ou Deixar como estão (eles aceitam que a cópia local pode acessar esses serviços).

Se nenhum dos plugins ativos for desse tipo, não pergunte: diga em uma linha (nomeando qualquer um que só envie e-mail, que o DDEV captura) e prossiga.

7. Verificar

wpsync verify verifica páginas, wp-admin, permalinks, endereços do site ativo restantes, imagens e se os plugins e o tema correspondem ao site ativo. Mostre a tabela de resultados.

Antes de investigar uma falha na verificação de página, verifique você mesmo a página uma vez: curl -s -o /dev/null -w '%{http_code}' <urlLocal>. Se responder 200, a verificação provavelmente foi executada enquanto o DDEV ainda estava iniciando (responde 502 por um momento após ddev start): execute wpsync verify mais uma vez antes de investigar logs.

Depois, veja você mesmo: abra o site ativo e a cópia local lado a lado no Chrome (Claude no Chrome), página inicial e algumas páginas internas, e compare. Não julgue a cópia no painel de navegador embutido do app: ele bloqueia estilos, scripts e imagens de uma página *.ddev.site (ERR_BLOCKED_BY_CLIENT), então mesmo uma cópia perfeita parece quebrada lá. Se o Chrome não estiver disponível, verifique a página com curl e peça ao desenvolvedor para verificar. Se algo diferir que você não consegue explicar, descreva e pergunte: Corrigir agora (Recomendado) ou Está bem, prossiga.

Login local: a cópia tem os usuários do site ativo, então o desenvolvedor faz login no wp-admin local com sua senha do site ativo.

8. Entregar

Leia o CLAUDE.md do site agora, para que suas regras se apliquem daqui em diante.

Primeiro, se este site usa Wordfence (wpsync status --json mostra "wordfence": "switched-off"): a configuração não precisa mais do site ativo, então siga ${CLAUDE_PLUGIN_ROOT}/skills/wp-dev/wordfence.md ("When wpsync is done") para que o desenvolvedor religue a proteção do Wordfence, aguarde e confirme com wpsync status. Faça isso antes da linha de entrega, para que a última etapa do desenvolvedor seja começar a trabalhar, em vez de outra tarefa.

Depois, abra o site local no Chrome e finalize a lista de verificação. Termine a configuração exatamente com isto, em negrito, em sua própria linha, como a última coisa em sua mensagem (nada depois; quaisquer outras notas, como fazer login, vão antes):

A cópia local do site está pronta em https://{domínio do site local}. Verifique e depois me diga quais alterações gostaria de começar a fazer.

com https://{domínio do site local} substituído por localUrl de .wpsync.json. Pouco antes, uma linha sobre fazer login: o wp-admin local aceita o nome de usuário e senha do site ativo.