BIGboss248/nextjs-wordpress

Configuração de Desenvolvimento Next.js (nextjs-dev-setup)

Um runbook de orquestração estruturado e completo para descobrir, configurar e verificar o ambiente de desenvolvimento Next.js App Router, roteamento de proxy reverso (Traefik / Nginx) e fonte única de verdade em docs/project.json.

---

Pré-Condições e Descoberta

• Varredura sem Interrupção: Examine os arquivos do repositório existentes (package.json, lockfiles, folhas de estilo, docs/adr/*.md, docs/plan.md, CONTEXT.md) antes de fazer perguntas.
• Consulte project-json-schema.md para a estrutura de metadados e regras de dedução automatizada.

---

Fase 0: Entrevista de Configuração em Múltiplas Rodadas (Questionamento) e Geração de Plano

Conduza a entrevista interativa em rodadas progressivas e adaptativas (aguardando a resposta do usuário após cada rodada) para personalizar a configuração:

1. Rodada 1 (Escopo e Ferramentas): Investigue as suítes de teste alvo (Jest, Playwright, Storybook), servidores MCP e a aplicação de @shadcn/lint.
2. Rodada 2 (Proxy Reverso e Hospedagem de Produção): Investigue o nome de domínio, porta e estratégia de proxy reverso:
   • Traefik via Docker Compose: Descoberta automatizada de contêineres usando labels do Compose que leem variáveis de ambiente (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) com anti-buffering.
   • Nginx via Sistema Host: Configuração independente em /etc/nginx/sites-available/<dominio> usando certificados SSL Certbot.
3. Rodada 3 (CI/CD, Hooks Git e Registry): Investigue husky pre-push test suites, Commitlint e workflows GitHub Actions Release Please / GHCR.
4. Consulte setup-interview-rounds.md para conjuntos completos de perguntas e lógica de ramificação.
5. Plano e Execução: Gere e apresente um artefato implementation_plan.md detalhando todas as criações de arquivos, configurações e pacotes planejados antes de aplicar as alterações, e prossiga diretamente com a execução sem aguardar confirmação manual.

---

Fluxo de Execução Passo a Passo

Estágio 1: Metadados do Projeto e Ferramentas de Desenvolvimento (docs/project.json)

1. Inicialize docs/project.json usando project.template.json com base nas escolhas da entrevista do usuário.
2. Configure .vscode/launch.json usando vscode-launch.json.template.
3. Estruture app/providers.tsx com <ProgressBarProvider> usando providers.tsx.template e <Link> composto usando Link.tsx.template.
4. Estruture .env.example usando env.example.template para produção e .env.local usando env.local.template para desenvolvimento local.
5. Ícones do App, Ícone Apple e Manifest PWA: Implante manifest.ts.template em app/manifest.ts. Configure o favicon fornecido pelo usuário nos locais raiz app/favicon.ico, app/icon.png e app/apple-icon.png (ou ícone dinâmico ImageResponse). Consulte app-icons-and-pwa-guide.md.

Estágio 2: Suítes de Teste (Jest, Playwright e Navegação Instantânea)

[!IMPORTANT] Nenhum Arquivo de Teste Fictício (Regra 3): Não crie arquivos de teste placeholder/de exemplo no workspace. Configure apenas arquivos de framework e scripts. Padrões de exemplo estão disponíveis em sample-component.test.tsx, sample-navigation.spec.ts e sample-component.stories.tsx.

1. Teste Unitário Jest: Configure jest.config.ts.template e jest.setup.ts.template.
2. Playwright E2E e Navegação Instantânea: Instale @playwright/test e @next/playwright (pnpm add -D @playwright/test @next/playwright), configure playwright.config.ts.template e instale os navegadores.
3. Config Instantânea Next.js: Configure cacheComponents: true, partialPrefetching: true e insights instantâneos em next.config.ts.
4. Workshop Storybook: Configure .storybook/main.ts e .storybook/preview.tsx.
5. Revise as arquiteturas em testing-guide.md e storybook-guide.md.

Estágio 3: Configuração de Servidores MCP Duplos

[!IMPORTANT] Regra de Carregamento Global MCP Antigravity: O AG só carrega servidores MCP configurados globalmente no sistema host (~/.gemini/antigravity/mcp_config.json e ~/.gemini/config/mcp_config.json). O mcp.json do workspace é mantido para portabilidade. Ambos devem ser configurados.

1. Configure next-devtools, playwright, storybook e codebase-memory-mcp.
2. Prevenção de Gagueira: Defina auto_watch = false via codebase-memory-mcp config set auto_watch false e implante .cbmignore na raiz.
3. Revise as especificações completas em mcp-configuration-guide.md.

Estágio 4: Linting do Sistema de Design Agent-First (@shadcn/lint)

1. Instale @shadcn/lint e configure a config plana do ESLint usando eslint.config.mjs.template.
2. Revise a mecânica em styling-and-linting-guide.md.

Estágio 5: Docker de Produção Independente e Proxy Reverso (Traefik / Nginx)

1. Em next.config.ts: resolva o hash do commit Git (getGitCommitHash() com fallbacks de CI) e a versão do pacote, injete NEXT_PUBLIC_APP_VERSION e NEXT_PUBLIC_GIT_COMMIT_HASH em env, habilite output: "standalone", defina deploymentId para proteção contra distorção de versão (${pkg.version}-${gitHash}), configure headers com X-Accel-Buffering: no e defina experimental.serverActions.allowedOrigins.
2. Documente NEXT_SERVER_ACTIONS_ENCRYPTION_KEY em .env.example e passe para os ambientes de execução.
3. Implante Dockerfile.template (com STOPSIGNAL SIGTERM) e docker-compose.yml.template (com stop_grace_period: 30s).
4. Configuração de Proxy Reverso:
   • Traefik: Implante docker-compose.prod.yml.template com labels de variáveis de ambiente dinâmicas (${DOMAIN_NAME}, ${TRAEFIK_ENTRYPOINT}, ${TRAEFIK_CERTRESOLVER}) e middleware anti-buffering.
   • Nginx: Implante ou gere nginx-site.conf.template para /etc/nginx/sites-available/<dominio> com certificados SSL Certbot.
5. Revise a arquitetura e a observação de desvio de cache de vários contêineres em docker-containerization-guide.md.

Estágio 6: Hooks Git e CI/CD Otimizado para Créditos

1. Instale husky, @commitlint/cli, @commitlint/config-conventional.
2. Configure commitlint.config.mjs.template, .husky/commit-msg e .husky/pre-push (pnpm run test:all).
3. Implante .github/workflows/release-please.yml com cache de build .next/cache e publicação em matriz multi-arquitetura.
4. Revise o cache em cicd-and-release-automation-guide.md.

Estágio 7: Relatório de Execução Final e Verificação

1. Execute o script de verificação de configuração e garanta que todas as verificações sejam aprovadas.
2. Prepare todos os arquivos criados/modificados no git (git add .) conforme a Regra 36.
3. Saída Final Obrigatória: Renderize a tabela markdown completa e estruturada do Relatório de Execução da Configuração de Desenvolvimento Next.js resumindo todos os arquivos implementados, resultados das verificações e próximos passos de desenvolvimento.

---

Verificação e Sanity Check

• Execute o script de verificação de configuração:
  • Windows (PowerShell): powershell -ExecutionPolicy Bypass -File .agents/skills/nextjs-dev-setup/scripts/verify-project-config.ps1
  • Linux / macOS (Bash): bash .agents/skills/nextjs-dev-setup/scripts/verify-project-config.sh
• Corrija quaisquer erros relatados e verifique novamente até que todas as verificações sejam aprovadas.

---

Casos de Borda e Armadilhas Conhecidas de IA

• Comandos Encadeados: Nunca encadeie comandos com && ou ; em uma única linha na execução do terminal.
• Desabilitação de MCP: Nas configurações globais do AG, agy.exe ignora "disabled": true dentro de mcpServers. Mova servidores desabilitados para fora de mcpServers.
• Nomes de Imagens Docker: A nomenclatura OCI do Docker exige estritamente nomes de repositório em minúsculas (IMAGE_NAME=$(echo ... | tr '[:upper:]' '[:lower:]')).
• Contexto Intl Storybook: Sempre envolva stories do Storybook que renderizam Link ou useTranslations com NextIntlClientProvider.

---

Saída Final Obrigatória: Template do Relatório de Execução

Sempre gere este relatório ao concluir o fluxo de trabalho do skill:

## 🛠️ Relatório de Execução da Configuração de Desenvolvimento Next.js

| Etapa / Componente                 | Arquivo(s) Alvo / Recurso                                                                            | Status                          | Notas / Detalhes                                                              |
| :--------------------------------- | :--------------------------------------------------------------------------------------------------- | :------------------------------ | :---------------------------------------------------------------------------- |
| **1. Metadados do Projeto**        | `docs/project.json`                                                                                  | `[IMPLEMENTADO]` / `[INTOCADO]` | Gerenciador de pacotes configurado, diretórios, metadados de animação e i18n. |
| **2. Ícones do App e Manifest PWA**| `app/manifest.ts`, `app/favicon.ico`, `app/apple-icon.png`, `app/icon.png`                           | `[IMPLEMENTADO]` / `[INTOCADO]` | Favicon raiz configurado, ícone Apple touch e Manifest Web App usando o favicon do usuário. |
| **3. Dependências Principais**     | `package.json`, Lockfile                                                                             | `[IMPLEMENTADO]` / `[INTOCADO]` | Bibliotecas React, Next.js, estilização e movimento verificadas.              |
| **4. MCP Servidor Dev Next.js**    | `~/.gemini/antigravity/mcp_config.json`, `mcp.json`, `.agents/plugins/workspace-tools/mcp_config.json`| `[IMPLEMENTADO]` / `[INTOCADO]` | Servidor de Desenvolvimento Next.js configurado (`next-devtools`) globalmente para AG e no workspace. |
| **5. Playwright e Testes Instantâneos** | `playwright.config.ts`, `@next/playwright`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json` | `[IMPLEMENTADO]` / `[INTOCADO]` | Executor, navegadores, MCP Playwright e auxiliar de navegação instantânea `@next/playwright` verificados. |
| **6. Memória do Código e Correção de Gagueira** | `.cbmignore`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`, `auto_watch=false`               | `[IMPLEMENTADO]` / `[INTOCADO]` | MCP registrado, exclusões .cbmignore configuradas e observador da sessão desabilitado. |
| **7. Teste Unitário Jest**         | `jest.config.ts`, `jest.setup.ts`                                                                    | `[IMPLEMENTADO]` / `[INTOCADO]` | Transformer Jest do Next.js configurado, ambiente jsdom e test-dom.           |
| **8. Storybook e MCP Storybook**   | `.storybook/main.ts`, `.storybook/preview.tsx`, `mcp.json`, `~/.gemini/antigravity/mcp_config.json`   | `[IMPLEMENTADO]` / `[INTOCADO]` | Storybook Vite configurado, a11y, temas e MCP Storybook AI globalmente e no workspace. |
| **9. Linter Tailwind Agent-First** | `eslint.config.mjs`, `package.json`                                                                  | `[IMPLEMENTADO]` / `[INTOCADO]` | `@shadcn/lint` configurado para verificação de tokens de design e contratos pelo agente. |
| **10. Docker e Proxy Reverso**     | `Dockerfile`, `docker-compose.prod.yml`, `nginx-site.conf`, `.dockerignore`                          | `[IMPLEMENTADO]` / `[INTOCADO]` | Contêiner independente, labels Traefik / Nginx HTTPS com Certbot SSL.         |
| **11. Hooks Git Husky**            | `.husky/commit-msg`, `.husky/pre-push`                                                               | `[IMPLEMENTADO]` / `[INTOCADO]` | Aplica suíte dupla de testes pré-push (Jest + Playwright) e commitlint.       |
| **12. Config Commitlint**          | `commitlint.config.mjs`                                                                              | `[IMPLEMENTADO]` / `[INTOCADO]` | `@commitlint/config-conventional` configurado.                                |
| **13. Cache de Build e Release CI**| `.github/workflows/release-please.yml`                                                               | `[IMPLEMENTADO]` / `[INTOCADO]` | Cache de build Next.js (.next/cache), PRs de release SemVer e pacote multi-arquitetura GHCR. |
| **14. Verificação de Ambiente**    | `scripts/verify-project-config.ps1` / `.sh`                                                          | `[APROVADO]`                    | Verificação de funcionamento passou com zero erros.                           |

#### Definições de Status:
- **`[IMPLEMENTADO]`**: Recém-criado, instalado ou modificado durante esta execução de configuração.
- **`[INTOCADO]`**: Já configurado corretamente antes da execução do skill; preservado como está.
- **`[PULADO]`**: Omitido intencionalmente com base na preferência do usuário.