AGENTS.md

ℹ️ ATTENZIONE: Tutte le procedure tecniche dettagliate, policy CI/CD, workflow Vercel/Next.js/OpenAI, fix errori, troubleshooting e script sono documentati nella guida guida-vercel.md nella root. Consultare SEMPRE quella guida prima di modificare script, policy o proporre fix automatici.

🚀 Build, Test, Lint, Deploy

• Install dependencies:
  • Se usi pnpm: pnpm install
  • Se usi npm: npm install
• Build:
  • pnpm build --filter <project_name>
  • Oppure: npm run build
• Test:
  • pnpm turbo run test --filter <project_name>
  • Oppure: npm test
  • Esegui solo uno specifico: pnpm vitest run -t "<test name>"
• Lint:
  • pnpm lint --filter <project_name>
  • Oppure: npm run lint
• Start dev:
  • pnpm dev --filter <project_name>
  • Oppure: npm run dev
• Deploy:
  • vercel --prod (se necessario)
• Watcher AI/Debug Vercel:
  • Avvia node ai-deploy-watcher.js per monitoraggio errori deploy/CI con analisi automatica AI (vedi sezione sotto).

🧠 AI, Codex, e Script Watcher

• Script di monitoraggio errori deploy:
  • Lo script ai-deploy-watcher.js controlla gli errori di deploy Vercel, legge i log e li invia ad OpenAI per ricevere una spiegazione e un fix AI.
  • Viene lanciato automaticamente dallo “Script di configurazione” del workspace.
  • Tutti gli errori di deploy vanno letti nei log di ai-deploy-watcher.log prima di aprire una Pull Request.
• Policy AI/Codex:
  • Codex può proporre fix automatici SOLO se la build e i test sono verdi (no merge con build rossa).
  • Se la build fallisce, il watcher fornisce log dettagliato e suggerisce il fix AI.
  • Aggiorna AGENTS.md se cambia lo script watcher, la policy CI o la struttura del progetto.

🧪 Dev Environment & Toolchain

• Per nuovi pacchetti React+Vite:
  pnpm create vite@latest <project_name> -- --template react-ts
• Usa sempre la versione Node.js >= 20.x
• Conferma che il campo "name" sia corretto in ogni package.json di sub-package.
• Usa pnpm dlx turbo run where <project_name> per individuare la directory.

📦 Workspace Policy (Monorepo)

• Non lasciare pacchetti inutilizzati o orphan.
• Installa solo le dipendenze necessarie su ogni sotto-pacchetto.
• Aggiorna la documentazione ogni volta che cambia la struttura.

📝 PR & Commit Instructions

• Titolo PR: [<project_name>] Breve descrizione
• Commit message: chiaro, descrittivo, riferito a issue/task.
• PR message: deve includere:
  • Sommario delle modifiche
  • Output di test (“Testing done”) e, se utile, log generato dallo script AI watcher
  • Issue reference (se c’è)
• Prima del merge:
  • Assicurati che TUTTI i test/lint/build siano verdi
  • Verifica che il watcher AI non abbia segnalato errori Vercel non risolti

🔐 Security & Best Practice

• Non committare mai .env, chiavi, token o segreti (usa GitHub/Vercel Secrets).
• Le variabili d’ambiente richieste (OPENAI_API_KEY, VERCEL_TOKEN, PROJECT_ID, ecc.) vanno impostate nelle rispettive UI cloud, mai in chiaro nei file.
• Aggiorna AGENTS.md e README.md se cambi toolchain, policy o script.

📚 Documentazione & Manutenzione

• Mantieni README.md e AGENTS.md sempre allineati con i comandi e policy correnti.
• Aggiorna la documentazione dopo ogni refactoring, cambio toolchain, aggiornamento CI/CD, o modifica importante.