BIGboss248/nextjs-wordpress

Compétence Universelle de Configuration et d'Environnement de Dépôt (setup-repository)

Cette compétence établit, configure et valide l'environnement de développement standard pour tout dépôt logiciel. Elle gère la découverte des métadonnées du projet, l'hygiène git, l'intelligence de code avec codebase-memory-mcp (configuré dans l'espace de travail et globalement pour Google Antigravity / AGY uniquement), la normalisation des commits avec Husky & Commitlint, la conteneurisation Docker de production, et le déploiement CI/CD automatisé Release Please & multi-arch GHCR.

---

Aperçu du Workflow

flowchart TD
    A["1. Découverte Automatisée & Analyse Sans Interruption"] --> B["2. Vérité Terrain des Métadonnées du Projet (docs/project.json)"]
    B --> C["3. Configuration du Codebase Memory MCP (Espace de travail & Global AGY)"]
    C --> D["4. Configuration des Hooks Git & Commitlint"]
    D --> E["5. Stacks Docker & Compose de Production"]
    E --> F["6. CI/CD Release Please & Multi-Arch GHCR"]
    F --> G["7. Vérification de Sanité de l'Environnement"]
    G --> H["8. Rapport d'Exécution Standardisé & Conseils Git"]

---

Étape 1 : Découverte Automatisée & Analyse du Dépôt (Règle de Zéro Interruption)

[!IMPORTANT] NE PAS DEMANDER À L'UTILISATEUR SI LES INFORMATIONS SONT DISPONIBLES DANS LES FICHIERS DU DÉPÔT. Analyser d'abord les fichiers du dépôt, les configurations et la documentation dans docs/. Déduire automatiquement le runtime, les outils et les conventions. Ne demander à l'humain que pour les éléments de configuration manquants ou ambigus.

1.1. Inspection Automatisée (Règle de Zéro Interruption)

1. Détecter le Framework & Runtime :
   • Inspecter les manifestes de paquets : package.json (Node/Bun), pyproject.toml / requirements.txt (Python), Cargo.toml (Rust), go.mod (Go), etc.
   • Détecter le gestionnaire de paquets à partir des fichiers de verrouillage :
     • pnpm-lock.yaml → pnpm
     • bun.lockb / bun.lock → bun
     • yarn.lock → yarn
     • package-lock.json → npm
2. Analyser la Documentation Existante :
   • Lire CONTEXT.md, docs/plan.md, docs/adr/*.md, et README.md pour extraire les standards architecturaux, les suites de test et les conventions linguistiques.
3. Vérifier l'Arbre de Travail Git :
   • Vérifier le statut git et la branche. Toutes les étapes d'inspection et de commande doivent être exécutées comme des opérations uniques discrètes sans enchaînement.

1.2. Clarification Interactive (Échafaudage Assisté par IA)

Si des paramètres critiques sont manquants, ambigus ou indéterminés à partir des fichiers existants, poser à l'utilisateur des questions ciblées avec des options claires :

### 📋 Configuration du Dépôt et CI/CD

Pour configurer le workflow CI/CD standard pour ce dépôt, veuillez confirmer ou spécifier :

1. **Langage & Runtime Principal** : (ex : Node.js / TypeScript, Python, Go, Rust, Java, C++)
2. **Commande de Test** : (ex : `pnpm test`, `pytest`, `cargo test`, `go test ./...`)
3. **Commande de Build** : (ex : `pnpm run build`, `cargo build --release`, `go build`, `aucune`)
4. **Cible de Publication** :
   - [ ] Image de Conteneur Docker (GHCR / Docker Hub)
   - [ ] Registre de Paquets (npm, PyPI, Crates.io, Maven)
   - [ ] Actifs de Version Binaire (GitHub Releases)
   - [ ] Site Statique / Documentation (GitHub Pages)
   - [ ] Aucune (Tests CI & Tags Git SemVer uniquement)

---

Étape 2 : Vérité Terrain des Métadonnées du Projet (docs/project.json)

Maintenir un fichier de configuration central lisible par machine à docs/project.json afin que tous les agents AI et compétences spécialisées partagent un contexte identique.

Modèle Standard docs/project.json :

{
  "project_context_and_metadata": {
    "project_name": "my-project",
    "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. S'assurer que le répertoire docs/ existe.
2. Écrire ou mettre à jour docs/project.json avec les valeurs de configuration découvertes ou confirmées.

---

Étape 3 : Configuration du Serveur d'Intelligence de Code codebase-memory-mcp

Équiper le dépôt du serveur de graphe de connaissances persistant codebase-memory-mcp (162 langages, AST Tree-sitter, résolution sémantique hybride LSP, et recherche vectorielle 100% locale).

3.1. Installation du Binaire

Choisir la méthode pour la plateforme :

• 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
  

• Alternative Globale via Paquet npm :

  npm install -g codebase-memory-mcp@latest
  

3.2. Enregistrement du Serveur MCP (Espace de Travail & Global AGY Uniquement)

[!IMPORTANT] L'enregistrement global MCP est pour Antigravity (AGY) UNIQUEMENT. Antigravity découvre et charge les serveurs MCP configurés globalement sur le système hôte. Ne jamais configurer ou enregistrer des serveurs MCP globalement pour d'autres agents de codage (par exemple, Claude Desktop, Cursor, VS Code, Cline). Enregistrer le serveur MCP dans les emplacements suivants :

1. Racine de l'Espace de Travail mcp.json :

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

2. Configuration de l'Agent de l'Espace de Travail (.agents/mcp_config.json) (si le dépôt utilise .agents/) :

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

3. Configuration Globale de l'Hôte (Google Antigravity / AGY Uniquement) : Ajouter codebase-memory strictement aux configurations hôte AGY :
   • ~/.gemini/antigravity/mcp_config.json
   • ~/.gemini/config/mcp_config.json (Ne PAS enregistrer dans Claude Desktop, Cursor ou d'autres agents de codage) :

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

3.3. Hygiène Git & Persistance

3.3. Configurer les Exclusions .cbmignore (Prévenir le Bégaiement de l'Éditeur & le Churn de Découverte)

• Local-Uniquement (Par défaut) : Ajouter .codebase-memory/ à .gitignore.

[!IMPORTANT] Prévention du Bégaiement & Exclusions à Fort Changement (.cbmignore) : codebase-memory-mcp lit un fichier .cbmignore situé strictement à la racine du dépôt (<repo>/.cbmignore) en utilisant la syntaxe .gitignore. Sans .cbmignore, les fichiers non-code (comme les documents de planification, la mémoire d'agent, les artefacts de test et les caches de build) déclenchent une découverte AST, une résolution de type et des écritures disque continues à chaque édition. Toujours générer <repo>/.cbmignore à la racine du dépôt :

# Règles d'ignorance pour codebase-memory-mcp (.cbmignore)
# Empêche les fichiers non-code et à fort changement de déclencher l'indexation du graphe ou de gonfler le graphe AST.

# Logs d'agent, métadonnées et documents de planification (fort changement pendant les sessions actives)
.agents/
docs/
*.md

# Artefacts de build & caches de compilation
dist/
build/
out/
.next/
.swc/

# Tests, rapports et couverture
coverage/
test-results/
playwright-report/
blob-report/
.playwright-mcp/
storybook-static/
*storybook.log

# Artefacts locaux de Codebase Memory (empêcher les boucles d'auto-déclenchement)
.codebase-memory/

# Système et logs
*.log
*.tsbuildinfo
.DS_Store

# Actifs statiques et médias (symboles de code zéro)
public/
assets/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.ico
*.webp
*.mp4
*.mp3
*.pdf

# Environnement & fichiers de verrouillage
.env*
*.pem
*.lock
pnpm-lock.yaml
package-lock.json
yarn.lock
bun.lockb

3.4. Désactiver la Surveillance Automatique de Fichiers de Session (auto_watch = false)

[!CAUTION] Prévention du Bégaiement Système : Par défaut, codebase-memory-mcp enregistre automatiquement les projets connectés avec son watcher git en arrière-plan (auto_watch = true). Sur Windows et les systèmes multitâches, le watcher détecte les sauvegardes de fichiers, génère un processus worker index.supervisor et compresse .codebase-memory/graph.db.zst via zstd à chaque frappe/sauvegarde, entraînant de sévères micro-bégaiements de l'UI de l'éditeur et du gestionnaire de fenêtres. Toujours désactiver la surveillance automatique de session globalement :

codebase-memory-mcp config set auto_watch false

Lorsqu'elle est désactivée, les sessions ne s'enregistrent pas avec le watcher en arrière-plan, éliminant complètement les blocages de l'éditeur. Le graphe est interrogé via les outils MCP et rafraîchi explicitement à la demande.

3.5. Hygiène Git & Persistance

• Local-Uniquement (Par défaut) : Ajouter .codebase-memory/ à .gitignore. Ne jamais valider l'artefact binaire à chaque sauvegarde.
• Partage d'Instantané en Équipe : Si la validation de l'instantané du graphe pré-indexé pour l'équipe, suivre .codebase-memory/graph.db.zst avec Git LFS dans le .gitattributes racine :

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

3.4. Indexation Initiale & Script de Cadence

3.6. Indexation Initiale à la Demande & Script de Cadence

1. Exécuter l'indexation initiale :
2. Exécuter l'indexation initiale à la demande (en utilisant le mode moderate ou fast pour ignorer les calculs d'embedding sémantique lourds) :

   codebase-memory-mcp cli index_repository --repo-path "<canonical-repo-path>"
   codebase-memory-mcp cli index_repository --repo-path "<canonical-repo-path>" --mode moderate
   

3. Ajouter un script de cadence à package.json pour rafraîchir l'index sur les jalons :
4. Ajouter un script de cadence à package.json pour rafraîchir l'index sur les jalons/commits majeurs :

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

---

Étape 4 : Configuration des Hooks Git avec Husky & Commitlint

Imposer les commits conventionnels et garantir que les suites de tests s'exécutent avant que le code puisse être poussé vers les branches distantes.

1. Installer les Dépendances de Développement :

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

2. Configurer commitlint.config.mjs :

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

3. Initialiser Husky :

   pnpm exec husky init
   

4. Configurer le Hook commit-msg :

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

5. Configurer le Hook pre-push : Imposer l'exécution de la suite de tests avant d'autoriser tout git push :

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

   [!NOTE] S'assurer que les scripts de test dans package.json incluent des indicateurs gracieux (par exemple --passWithNoTests) afin que les dépôts sans fichiers de test sortent avec le code 0 plutôt que de casser les pushs. Ne jamais créer de fichiers de test échantillons/placeholders dans l'espace de travail.

---

Étape 5 : Configuration de la Conteneurisation Docker Multi-Étapes de Production

Configurer la conteneurisation strictement pour les builds et déploiements de production autonomes. Le développement local s'exécute sur la machine hôte en utilisant le gestionnaire de paquets natif du projet.

5.1. Configurer .dockerignore

Exclure les artefacts locaux, l'historique git et les secrets :

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

5.2. Dockerfile Multi-Étapes

Créer un build multi-étapes en 3 étapes (dependencies → builder → runner) s'exécutant sous un utilisateur non-root sécurisé :

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. Stacks 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. Stack Pré-construite de Production (docker-compose.prod.yml) : Tire les images multi-arch pré-construites directement depuis GHCR sans code source :

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

---

Étape 6 : Configuration du CI/CD Optimisé pour le Crédit & Automatisation Release Please

Automatiser les versions sémantiques, les changelogs et la publication multi-architecture (AMD64 & ARM64) sur le GitHub Container Registry via .github/workflows/release-please.yml :

Règles de Conception DevOps Cœur :

1. Porte de Test Automatisée : Exécute les tests du projet sur les pull requests et les commits vers main.
2. Automatisation Release Please : Automatise les incrémentations de version, les changelogs et les PR de version.
3. concurrency.cancel-in-progress: false : Ne jamais annuler les workflows de version ou les déploiements en cours sur la branche principale.
4. Constructeur Matriciel Multi-Arch en Deux Étapes : Construire AMD64 et ARM64 sur des machines runner natives (ubuntu-latest et ubuntu-24.04-arm) sans émulation QEMU. Pousser les images par digest.
5. Fusion du Manifeste de Digest : Un job merge-manifest aval fusionne les digests AMD64 et ARM64 en une balise multi-arch unifiée.
6. Nom de Dépôt en Minuscules : Toujours transformer github.repository en minuscules via toLower et filtrer tout préfixe de chemin.

...

[La suite du contenu du fichier original a été tronquée, mais le markdown ci-dessus a été traduit intégralement.]

---

Documentation de compétence traduite et localisée.