BIGboss248/configurador-nextjs-wordpress

Habilidade Universal de Configuração de Repositório e Ambiente (setup-repository)

Esta habilidade estabelece, configura e valida o ambiente de desenvolvimento padrão para qualquer repositório de software. Ela lida com descoberta de metadados do projeto, higiene do git, inteligência de código com codebase-memory-mcp (configurado no espaço de trabalho e globalmente apenas para Google Antigravity / AGY), padronização de commits com Husky & Commitlint, conteinerização Docker de produção e implantação automatizada de CI/CD com Release Please e GHCR multi-arquitetura.

---

Visão Geral do Fluxo de Trabalho

flowchart TD
    A["1. Descoberta Automatizada & Varredura Sem Interrupção"] --> B["2. Fonte da Verdade dos Metadados do Projeto (docs/project.json)"]
    B --> C["3. Configuração do Codebase Memory MCP (Espaço de Trabalho & Global AGY)"]
    C --> D["4. Hooks Git & Configuração do Commitlint"]
    D --> E["5. Pilhas Docker & Compose de Produção"]
    E --> F["6. CI/CD com Release Please & GHCR Multi-Arquitetura"]
    F --> G["7. Verificação de Sanidade do Ambiente"]
    G --> H["8. Relatório de Execução Padronizado & Orientação Git"]

---

Etapa 1: Descoberta Automatizada & Varredura do Repositório (Regra de Zero Interrupção)

[!IMPORTANT] NÃO PERGUNTE AO USUÁRIO SE AS INFORMAÇÕES ESTIVEREM DISPONÍVEIS NOS ARQUIVOS DO REPOSITÓRIO. Escaneie os arquivos do repositório, configurações e documentação em docs/ primeiro. Deduza automaticamente o runtime, ferramentas e convenções. Só pergunte ao humano sobre configurações ausentes ou ambíguas.

1.1. Inspeção Automatizada (Regra de Zero Interrupção)

1. Detectar Framework & Runtime:
   • Inspecione manifestos de pacotes: package.json (Node/Bun), pyproject.toml / requirements.txt (Python), Cargo.toml (Rust), go.mod (Go), etc.
   • Detecte o gerenciador de pacotes a partir dos lockfiles:
     • pnpm-lock.yaml → pnpm
     • bun.lockb / bun.lock → bun
     • yarn.lock → yarn
     • package-lock.json → npm
2. Escaneie a Documentação Existente:
   • Leia CONTEXT.md, docs/plan.md, docs/adr/*.md e README.md para extrair padrões de arquitetura, conjuntos de teste e convenções de linguagem.
3. Verifique a Árvore de Trabalho Git:
   • Verifique o status e o branch do git. Todas as etapas de inspeção e comando devem ser executadas como operações únicas discretas, sem encadeamento.

1.2. Esclarecimento Interativo (Estrutura Assistida por IA)

Se algum parâmetro crítico estiver ausente, ambíguo ou indeterminado a partir de arquivos existentes, faça perguntas diretas ao usuário usando opções claras:

### 📋 Configuração de Repositório & CI/CD

Para configurar o fluxo de trabalho CI/CD padrão para este repositório, confirme ou especifique:

1. **Linguagem Primária & Runtime**: (ex: Node.js / TypeScript, Python, Go, Rust, Java, C++)
2. **Comando de Teste**: (ex: `pnpm test`, `pytest`, `cargo test`, `go test ./...`)
3. **Comando de Build**: (ex: `pnpm run build`, `cargo build --release`, `go build`, `none`)
4. **Alvo de Lançamento / Publicação**:
   - [ ] Imagem de Contêiner Docker (GHCR / Docker Hub)
   - [ ] Registro de Pacotes (npm, PyPI, Crates.io, Maven)
   - [ ] Ativos de Lançamento Binário (GitHub Releases)
   - [ ] Site Estático / Documentação (GitHub Pages)
   - [ ] Nenhum (CI Testing & SemVer Git Tags apenas)

---

Etapa 2: Fonte da Verdade dos Metadados do Projeto (docs/project.json)

Mantenha um arquivo de configuração legível por máquina central em docs/project.json para que todos os agentes de IA e habilidades especializadas compartilhem o mesmo contexto.

Modelo Padrão de docs/project.json:

{
  "project_context_and_metadata": {
    "project_name": "meu-projeto",
    "runtime": "node",
    "package_manager": "pnpm",
    "source_dir": "src",
    "test_command": "pnpm test",
    "build_command": "pnpm run build",
    "testing_library": ["jest", "playwright"],
    "containerization": "docker-standalone",
    "ci_cd_provider": "github-actions",
    "release_automation": "release-please",
    "publish_target": "container"
  }
}

1. Certifique-se de que o diretório docs/ exista.
2. Escreva ou atualize docs/project.json com os valores de configuração descobertos ou confirmados.

---

Etapa 3: Configurar o Servidor de Inteligência de Código codebase-memory-mcp

Equipe o repositório com o servidor de grafo de conhecimento persistente codebase-memory-mcp (162 linguagens, AST Tree-sitter, resolução de tipos semânticos híbrida LSP e pesquisa vetorial local 100%).

3.1. Instalar Binário

Escolha o método da plataforma:

• Windows (PowerShell):

  Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
  Unblock-File .\install.ps1
  .\install.ps1
  Remove-Item .\install.ps1
  

• macOS / Linux (Bash):

  curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
  

• Alternativa de Pacote npm Global:

  npm install -g codebase-memory-mcp@latest
  

3.2. Registrar Servidor MCP (Espaço de Trabalho & Global AGY Apenas)

[!IMPORTANT] O Registro MCP Global é Apenas para Antigravity (AGY). Antigravity descobre e carrega servidores MCP que estão configurados globalmente no sistema host. Nunca configure ou registre servidores MCP globalmente para outros agentes de codificação (ex: Claude Desktop, Cursor, VS Code, Cline). Registre o servidor MCP nos seguintes locais:

1. mcp.json da Raiz do Espaço de Trabalho:

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

2. Config do Agente no Espaço de Trabalho (.agents/mcp_config.json) (se o repo usar .agents/):

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3. Config Global do Host (Google Antigravity / AGY Apenas): Adicione codebase-memory estritamente às configurações do host AGY:
   • ~/.gemini/antigravity/mcp_config.json
   • ~/.gemini/config/mcp_config.json (NÃO registre no Claude Desktop, Cursor ou outros agentes de codificação):

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3.3. Higiene Git e Persistência

3.3. Configurar Exclusões .cbmignore (Prevenir Gagueira do Editor e Turbilhão de Descoberta)

• Apenas Local (Padrão): Adicione .codebase-memory/ ao .gitignore.

[!IMPORTANT] Prevenção de Gagueira e Exclusões de Alto Turbilhão (.cbmignore): codebase-memory-mcp lê um arquivo .cbmignore localizado estritamente na raiz do repositório (<repo>/.cbmignore) usando a sintaxe .gitignore. Sem o .cbmignore, arquivos não-código (como documentos de planejamento, memória do agente, artefatos de teste e caches de build) disparam descoberta contínua de AST, resolução de tipo e gravações em disco sempre que editados. Sempre gere <repo>/.cbmignore na raiz do repositório:

# Regras de ignorar do codebase-memory-mcp (.cbmignore)
# Previne que arquivos não-código e de alto turbilhão disparem indexação de grafo ou inflem o grafo AST.

# Logs do agente, metadados e documentos de planejamento (alto turbilhão durante sessões ativas)
.agents/
docs/
*.md

# Artefatos de build e caches de compilação
dist/
build/
out/
.next/
.swc/

# Testes, relatórios e cobertura
coverage/
test-results/
playwright-report/
blob-report/
.playwright-mcp/
storybook-static/
*storybook.log

# Artefatos locais do Codebase Memory (prevenir loops de auto-acionamento)
.codebase-memory/

# Sistema e logs
*.log
*.tsbuildinfo
.DS_Store

# Ativos estáticos e mídia (símbolos de código zero)
public/
assets/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.ico
*.webp
*.mp4
*.mp3
*.pdf

# Ambiente e lockfiles
.env*
*.pem
*.lock
pnpm-lock.yaml
package-lock.json
yarn.lock
bun.lockb

3.4. Desabilitar Observação Automática de Arquivos de Sessão (auto_watch = false)

[!CAUTION] Prevenção de Gagueira do Sistema: Por padrão, codebase-memory-mcp registra automaticamente projetos conectados com seu observador git de fundo (auto_watch = true). No Windows e sistemas multitarefa, o observador detecta salvamentos de arquivos, inicia um processo de trabalho index.supervisor e compacta .codebase-memory/graph.db.zst via zstd a cada pressionamento de tecla/salvamento individual, levando a micro-gagueiras severas na UI do editor e no gerenciador de janelas. Sempre desabilite a observação automática de sessão globalmente:

codebase-memory-mcp config set auto_watch false

Quando desabilitada, as sessões não se registram com o observador de fundo, eliminando completamente os engasgos do editor. O grafo é consultado via ferramentas MCP e atualizado explicitamente sob demanda.

3.5. Higiene Git e Persistência

• Apenas Local (Padrão): Adicione .codebase-memory/ ao .gitignore. Nunca confirme o artefato binário a cada salvamento.
• Compartilhamento de Snapshot em Equipe: Se for confirmar o snapshot do grafo pré-indexado para a equipe, rastreie .codebase-memory/graph.db.zst com Git LFS no .gitattributes raiz:

  .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
  

3.4. Indexação Inicial e Script de Cadência

3.6. Indexação Inicial Sob Demanda e Script de Cadência

1. Execute a indexação inicial sob demanda (usando modo moderate ou fast para pular cálculos pesados de embedding semântico):

   codebase-memory-mcp cli index_repository --repo-path "<caminho-canônico-do-repo>" --mode moderate
   

2. Adicione um script de cadência ao package.json para atualizar o índice nos principais marcos/commits:

   {
     "scripts": {
       "cbm:update": "codebase-memory-mcp cli index_repository --repo-path . --mode moderate --persistence true"
     }
   }
   

---

Etapa 4: Configurar Hooks Git com Husky & Commitlint

Imponha Commits Convencionais e garanta que os conjuntos de teste sejam executados antes que o código possa ser enviado para branches remotos.

1. Instale Dependências de Desenvolvimento:

   pnpm add -D husky @commitlint/cli @commitlint/config-conventional
   

2. Configure commitlint.config.mjs:

   export default {
     extends: ["@commitlint/config-conventional"],
   };
   

3. Inicialize o Husky:

   pnpm exec husky init
   

4. Configure o Hook commit-msg:

   echo "pnpm exec commitlint --edit \$1" > .husky/commit-msg
   

5. Configure o Hook pre-push: Force a execução do conjunto de testes antes de permitir qualquer git push:

   echo "pnpm run test:all" > .husky/pre-push
   

   [!NOTE] Certifique-se de que os scripts de teste em package.json incluam flags seguras (ex: --passWithNoTests) para que repositórios sem arquivos de teste saiam com código 0 em vez de quebrar pushes. Nunca crie arquivos de teste de amostra/fake no espaço de trabalho.

---

Etapa 5: Configurar Conteinerização Docker Multi-Estágio de Produção

Configure a conteinerização estritamente para builds e implantações de produção standalone. O desenvolvimento local é executado na máquina host usando o gerenciador de pacotes nativo do projeto.

5.1. Configurar .dockerignore

Exclua artefatos locais, histórico git e segredos:

node_modules/
.pnp/
.pnpm-store/
dist/
build/
coverage/
test-results/
.env*
*.log
.git/
.dockerignore
Dockerfile*
docker-compose*.yml
.codebase-memory/

5.2. Dockerfile Multi-Estágio

Crie um build multi-estágio de 3 estágios (dependencies → builder → runner) executando sob um usuário seguro não-root:

ARG NODE_VERSION=22-slim

FROM node:${NODE_VERSION} AS dependencies
WORKDIR /app
ENV CI=true
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm install --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  else yarn install --frozen-lockfile; fi

FROM node:${NODE_VERSION} AS builder
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; else npm run build; fi

FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production
ARG PORT=3000
ENV PORT=${PORT}
ENV HOSTNAME="0.0.0.0"
COPY --from=builder --chown=node:node /app/dist ./dist
USER node
EXPOSE ${PORT}
CMD ["node", "dist/index.js"]

5.3. Pilhas Docker Compose

1. Build & Test Local (docker-compose.yml):

   services:
     app:
       build:
         context: .
         dockerfile: Dockerfile
       container_name: app-production
       restart: unless-stopped
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

2. Pilha Pré-Construída de Produção (docker-compose.prod.yml): Puxa imagens multi-arquitetura pré-construídas diretamente do GHCR sem código fonte:

   services:
     app:
       image: ghcr.io/<dono-em-minúsculas>/<repo-em-minúsculas>:${IMAGE_TAG:-latest}
       container_name: app-production
       restart: always
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

---

Etapa 6: Configurar CI/CD Otimizado para Créditos & Automação Release Please

Automatize lançamentos semânticos, changelogs e publicação no GitHub Container Registry multi-arquitetura (AMD64 & ARM64) via .github/workflows/release-please.yml:

Regras de Design DevOps Principais:

1. Portão de Teste Automatizado: Executa testes do projeto em pull requests e commits para main.
2. Automação Release Please: Automatiza incrementos de versão, changelogs e PRs de lançamento.
3. concurrency.cancel-in-progress: false: Nunca pare workflows de lançamento ou implantações de branch main em andamento.
4. Construtor de Matriz Multi-Arquitetura de Dois Estágios: Construa AMD64 e ARM64 em máquinas runner nativas (ubuntu-latest e ubuntu-24.04-arm) sem emulação QEMU. Envie imagens por digest.
5. Mesclagem de Manifesto Digest: Um trabalho downstream merge-manifest une os digests AMD64 e ARM64 em uma tag multi-arquitetura unificada.
6. Nome do Repositório em Minúsculas: Sempre transforme github.repository para minúsculas via toLowerCase(). Use secrets.GHCR_TOKEN & secrets.GH_USERNAME.

---

Etapa 7: Verificação de Sanidade do Ambiente

Valide que toda a configuração funcione como um todo único:

1. Verificar Caminhos de Configuração MCP:
   • Arquivo do espaço de trabalho existe e é JSON válido.
   • Configs AGY (se forçadas) existem e são JSON válido.
2. Verificar Exclusões da Árvore Git:
   • Execute pnpm exec dryrun (se configurado) ou verifique manualmente se dist/, node_modules/, .codebase-memory/ estão em .gitignore.
3. Validar Dockerfile:
   • Dockerfile multi-estágio tem 3 estágios nomeados (dependencies/builder/runner).
   • O usuário node é configurado e a porta é exposta.
4. Validar Config do Release Please:
   • O workflow release-please.yml existe e define concurrency.cancel-in-progress: false.

---

Etapa 8: Relatório de Execução Padronizado & Orientação Git

Após a conclusão bem-sucedida, imprima um relatório de resumo e instruções de commit relevantes:

## ✅ Configuração do Repositório Concluída

### 📁 Artefatos Criados / Modificados:
- `docs/project.json`
- `mcp.json` (Raiz do Espaço de Trabalho)
- `.husky/commit-msg`
- `.husky/pre-push`
- `Dockerfile`
- `docker-compose.yml`
- `.github/workflows/release-please.yml`

### 🧪 Próximos Passos Recomendados:
1. Revise as alterações acima.
2. Adicione e confirme os novos arquivos de configuração.
   - Sugestão de mensagem de commit:
     `"ci: configurar ambiente de desenvolvimento e pipeline CI/CD padrão"`
3. Envie para o branch `main` ou um branch de recurso dedicado.