@codigodoleo/wp-kit 2.0.4 → 3.0.1

package/.cspell.json

@@ -1,13 +1,8 @@
 {
   "version": "0.2",
   "language": "en,pt_BR",
-  "dictionaries": [
-    "php"
-  ],
-  "import": [
-    "@cspell/dict-php/cspell-ext.json",
-    "@cspell/dict-pt-br/cspell-ext.json"
-  ],
+  "dictionaries": ["php"],
+  "import": ["@cspell/dict-php/cspell-ext.json", "@cspell/dict-pt-br/cspell-ext.json"],
   "words": [
     "ACF",
     "appserver",
@@ -78,27 +73,12 @@
     "yzhang",
     "zhuangtongfa"
   ],
-  "ignorePaths": [
-    "node_modules/**",
-    "vendor/**",
-    "dist/**",
-    "public/**"
-  ],
-  "enableFiletypes": [
-    "php",
-    "js",
-    "ts",
-    "json",
-    "scss",
-    "md",
-    "html"
-  ],
+  "ignorePaths": ["node_modules/**", "vendor/**", "dist/**", "public/**"],
+  "enableFiletypes": ["php", "js", "ts", "json", "scss", "md", "html"],
   "languageSettings": [
     {
       "languageId": "php",
-      "dictionaries": [
-        "php"
-      ]
+      "dictionaries": ["php"]
     }
   ]
 }

package/README.md

@@ -3,33 +3,42 @@
 Simplifique e padronize seus projetos WordPress em minutos. Este CLI cria um esqueleto moderno, opinativo e pronto para CI/CD, com integração a temas (Sage), qualidade de código e fluxos de deploy — tudo com escolhas inteligentes e mínima fricção.
 
 ## Por que usar
+
 - Padronização entre projetos e equipes
 - Onboarding rápido (menos passos manuais, menos erros)
 - CI/CD dinâmico que se adapta às suas escolhas (GitLab, GitHub ou Bitbucket)
 - Convenções modernas (Conventional Commits, linters, hooks)
 
 ## Requisitos
+
 - Node.js 18+ (recomendado 22+)
 - npm
 - Git
 - PHP 8.2+ e Composer (necessário para tema Sage e ferramentas PHP)
 
 ## Quickstart (1 minuto)
+
 - Criar projeto interativo:
+
 ```bash
 npx @codigodoleo/wp-kit init --output meu-projeto
 ```
+
 - Projeto padrão (sem perguntas):
+
 ```bash
 npx @codigodoleo/wp-kit init --output meu-projeto --defaults
 ```
+
 - Instalação global (opcional):
+
 ```bash
 npm install -g @codigodoleo/wp-kit
 leo-wp init --output meu-projeto
 ```
 
 ## O que é gerado
+
 - Estrutura WordPress com `content/` (temas, plugins, uploads)
 - Configurações úteis em `server/` e arquivos base (`.env`, `.editorconfig`, etc.)
 - Workspace do VSCode (opcional)
@@ -41,6 +50,7 @@ leo-wp init --output meu-projeto
 - Integração opcional com tema Sage (v10/v11), com build automatizado
 
 ## Como funciona (visão rápida)
+
 1. Você roda `init` e responde às perguntas (ou usa `--defaults`).
 2. O CLI infere capacidades (Composer, Node, Sage, Docker) e monta `context.ci`.
 3. O módulo `deploy` gera o pipeline certo para seu provedor (GitLab/GitHub/Bitbucket) com jobs somente do que faz sentido para o seu projeto.
@@ -48,36 +58,45 @@ leo-wp init --output meu-projeto
 Exemplo: Se você ativar Sage 11, ajustamos versões automaticamente (PHP/Node/WP) e incluímos o job de build do tema no CI.
 
 ## Fluxo recomendado
+
 1. Execute o comando (interativo):
+
 ```bash
 npx @codigodoleo/wp-kit init --output meu-wp
 ```
+
 2. Escolha o provedor de Git (ex.: GitLab ou GitHub) no prompt do módulo "git".
 3. Ative o módulo "deploy" (gera a pipeline automática).
 4. Se desejar, habilite o tema Sage (o build entra na pipeline automaticamente).
 5. Faça o primeiro commit e suba o repositório. O CI já estará pronto para rodar.
 
 ## Comandos disponíveis
+
 - `init [options]` — Inicializa um novo projeto WordPress com DevOps
 - `--help` — Ajuda
 - `--version` — Versão
 
 ### Opções do `init`
+
 - `--output <path>` — Diretório de saída do projeto
 - `--defaults` — Usa configurações padrão sem interação
 
 ## Exemplos práticos
+
 - Interativo, escolhendo tudo pelo prompt:
+
 ```bash
 npx @codigodoleo/wp-kit init --output site-corporativo
 ```
 
 - Projeto padrão, sem prompts (padrões inteligentes):
+
 ```bash
 npx @codigodoleo/wp-kit init --output blog-interno --defaults
 ```
 
 ## Estrutura essencial de pastas
+
 ```
 meu-projeto/
   content/
@@ -90,25 +109,131 @@ meu-projeto/
 ```
 
 ## CI Dinâmico (como decidimos o que rodar)
+
 Detectamos automaticamente:
+
 - `composer.json` (root/tema) → job de Composer
 - `package.json` (root/tema) → job de Node
 - Tema Sage ativo → job de build do tema
 - Deploy Docker escolhido → job de deploy Docker
 
 Provedores suportados:
+
 - GitLab CI, GitHub Actions, Bitbucket Pipelines
 
 ## Convenções e qualidade
+
 - Commits: Conventional Commits (ex.: `feat:`, `fix:`, `docs:`)
-- Hooks: Husky + lint-staged
-- Linters: ESLint, Prettier, Stylelint, Pint
+- Hooks: Husky + lint-staged (validação automática ao fazer commit)
+- Linters: ESLint (flat config), Prettier, Stylelint, Pint
+- Commitlint: Validação de mensagens de commit convencionais
+- Interactive commits: Use `npm run commit` para commits interativos
+
+## Script de desenvolvimento
+
+Comandos disponíveis para desenvolvimento:
+
+- `npm run lint` — Validar código com ESLint
+- `npm run lint:fix` — Corrigir automaticamente problemas de linting
+- `npm run format` — Formatar código com Prettier
+- `npm run commit` — Criar commit interativo (cz)
+- `npm run test:setup` — Gerar sandbox de teste
+- `npm run test:scaffold` — Criar novo projeto de teste
+
+## Git Workflows
+
+O projeto usa Husky para automatizar validações:
+
+- **pre-commit**: Executa lint-staged em arquivos modificados
+- **commit-msg**: Valida mensagem com commitlint
+
+Se precisar pular hooks (situação de emergência apenas):
+
+```bash
+git commit --no-verify
+```
+
+## ESLint Flat Config (moderne)
+
+O projeto agora usa o novo formato ESLint flat config (`eslint.config.mjs`):
+
+- Melhor inicialização de projeto
+- Sem `eslintrc.json` legado
+- Ignores integradas na configuração principal
+- Melhor performance
+
+Projetos gerados também usarão este novo formato.
 
 ## Dicas e solução de problemas
+
 - Pipeline não foi gerado? Verifique se habilitou o módulo `deploy` e qual provedor selecionou no módulo `git`.
 - Tema Sage não compilou? Garanta Composer/Node instalados e que o tema existe em `content/themes/<projectName>`.
 
+## AI Co-Pilot Support 🤖
+
+wp-kit agora inclui suporte integrado para assistência de IA via **Claude Code** (e futuramente Cursor e VSCode).
+
+### Funcionalidades
+
+Três skills prontos para ajudar no desenvolvimento:
+
+1. **Building Sage Themes** — Master Sage 11 & Acorn
+   - Service providers e injeção de dependência
+   - Componentes Blade e view composers
+   - theme.json e configuração WordPress
+   - Padrões de desenvolvimento
+
+2. **Optimizing Vite Builds** — Performance de assets
+   - Configuração Vite e bundling
+   - Code splitting e análise de bundle
+   - Cache busting e asset versioning
+   - Monitoramento de performance
+
+3. **Developing ACF Blocks** — Criação de blocos Gutenberg
+   - Anatomia de blocos ACF
+   - Todos os 20+ tipos de campos ACF
+   - Templates com Blade
+   - Padrões avançados
+
+### Como usar
+
+#### Com Claude Code
+
+1. Abra seu projeto wp-kit no Claude Code
+2. Use `/` para ver os skills disponíveis
+3. Procure por "sage", "vite" ou "acf"
+4. Clique para acessar o skill
+
+#### Busca Direta
+
+```
+/building-sage-themes      → Desenvolvimento de temas
+/optimizing-vite-builds    → Otimização de assets
+/developing-acf-blocks     → Blocos Gutenberg
+```
+
+### Estrutura de Skills
+
+Cada skill segue um padrão progressivo:
+
+- **SKILL.md** — Quick start em 2-3 minutos
+- **Decision Trees** — Guias "qual ferramenta usar?"
+- **Reference Files** — Documentação completa com exemplos
+- **150+ Exemplos** — Código pronto para copiar/colar
+
+### Futuro
+
+Suporte planejado para:
+
+- ✅ Claude Code (atual, disponível)
+- ⏳ Cursor (em desenvolvimento)
+- ⏳ VSCode AI Assistant (em desenvolvimento)
+- ⏳ Plugin customizado (roadmap futuro)
+
+---
+
 ## Contribuição
+
 Pull Requests são muito bem-vindos! Use commits convencionais, escreva mudanças pequenas e inclua atualizações na documentação quando necessário.
 
 —

package/lib/cli.js

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+
 import { initCommand } from './commands/init.js';
 
 const program = new Command();

package/lib/commands/init.js

@@ -1,10 +1,17 @@
-import { Command } from 'commander';
 import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { Command } from 'commander';
 import fs from 'fs-extra';
+
 import { runPrompts } from '../prompts/index.js';
 import { Generator } from '../core/generator.js';
 import { log, color } from '../utils/logger.js';
 import { inferCiCapabilities } from '../core/infer-ci-capabilities.js';
+import { validateVersionCompatibility } from '../config/versions.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 export const initCommand = new Command('init')
   .option('-o, --output <dir>', 'Output directory', '__test-sandbox__/test-project')
@@ -25,13 +32,28 @@ export const initCommand = new Command('init')
     // 🔧 Ajustes automáticos para Sage 11
     if (context.useSage && context.sageVersion === '11') {
       context.phpVersion = '8.3';
-      context.nodeVersion = '23';
-      context.wpCoreVersion = '7.5';
+      context.nodeVersion = '22';
+      context.wpCoreVersion = '6.8.1';
 
       log(color.orange, '🔧 Sage 11 selected — automatically adjusting versions:');
       log(color.orange, '  → PHP: 8.3');
-      log(color.orange, '  → Node: 23');
-      log(color.orange, '  → WP Core: 7.5');
+      log(color.orange, '  → Node: 22');
+      log(color.orange, '  → WP Core: 6.8.1');
+    }
+
+    // 📋 Validar compatibilidade de versões (se Sage está habilitado)
+    if (context.useSage) {
+      const validation = validateVersionCompatibility(
+        context.sageVersion,
+        context.phpVersion,
+        context.nodeVersion,
+        context.wpCoreVersion
+      );
+
+      if (validation.warnings.length > 0) {
+        log(color.orange, '⚠️  Version compatibility warnings:');
+        validation.warnings.forEach((warn) => log(color.orange, `  - ${warn}`));
+      }
     }
 
     context.cwd = target;
@@ -86,7 +108,7 @@ export const initCommand = new Command('init')
       modules: enabledModules,
       context,
       format: 'json',
-      mergeStrategy: 'concat'
+      mergeStrategy: 'concat',
     });
 
     await generator.generateModularFile({
@@ -94,14 +116,14 @@ export const initCommand = new Command('init')
       modules: enabledModules,
       context,
       format: 'json',
-      mergeStrategy: 'concat'
+      mergeStrategy: 'concat',
     });
 
     await generator.generateModularFile({
       baseTemplate: '.lando.yml',
       modules: enabledModules,
       context,
-      mergeStrategy: 'concat'
+      mergeStrategy: 'concat',
     });
 
     await generator.generateModularFile({
@@ -110,11 +132,11 @@ export const initCommand = new Command('init')
       modules: enabledModules,
       context,
       format: 'json',
-      mergeStrategy: 'concat'
+      mergeStrategy: 'concat',
     });
 
     for (const mod of enabledModules) {
-      const modIndexPath = path.resolve('modules', mod, 'index.js');
+      const modIndexPath = path.resolve(__dirname, '../../modules', mod, 'index.js');
       if (await fs.pathExists(modIndexPath)) {
         const { setupModule } = await import(modIndexPath);
         if (typeof setupModule === 'function') {

package/lib/config/versions.js

@@ -0,0 +1,163 @@
+/**
+ * Version Registry - Centralized version management for wp-kit
+ * This file contains all version information for WordPress, PHP, Node.js, and Sage
+ *
+ * Benefits of centralized approach:
+ * - Single source of truth for all versions
+ * - Easy to update versions without searching codebase
+ * - Better documentation of version requirements
+ * - Compatibility matrix validation
+ * - Easy to script version updates
+ */
+
+export const VERSION_REGISTRY = {
+  /**
+   * WordPress Core Versions
+   * Maintains LTS and supported versions
+   */
+  wordpress: {
+    latest: '6.9.4',
+    lts: ['6.9.4', '6.8.1', '6.7'],
+    all: ['6.9.4', '6.8.1', '6.7', '6.6'],
+    eol: ['6.5', '6.0', '5.9'],
+    description: 'Available WordPress core versions for new projects',
+  },
+
+  /**
+   * Sage Theme Versions
+   * Each version specifies minimum PHP requirement and Acorn dependency
+   */
+  sage: {
+    11: {
+      tag: 'v11.0.1', // Update this when new versions are released
+      minPhp: '8.1',
+      acornVersion: '5.1.0',
+      nodeMin: '18',
+      status: 'active',
+      releaseDate: '2024-09-27',
+      url: 'https://github.com/roots/sage/releases/tag/v11.0.1',
+    },
+    10: {
+      tag: 'v10.8.2', // Legacy - consider only for compatibility projects
+      minPhp: '8.0',
+      acornVersion: '4.x',
+      nodeMin: '16',
+      status: 'legacy',
+      releaseDate: '2023-06-01',
+      url: 'https://github.com/roots/sage/releases/tag/v10.8.2',
+    },
+  },
+
+  /**
+   * PHP Versions
+   * Only actively supported versions per php.net
+   */
+  php: {
+    latest: '8.3',
+    supported: ['8.3', '8.2', '8.1'],
+    eol: ['8.0', '7.4', '7.3', '7.2'], // Deprecated - do not use
+    description: 'Supported PHP versions. PHP 7.4+ reached EOL on 2022-11-28',
+    // PHP version dates: https://www.php.net/supported-versions.php
+    eolDates: {
+      8.1: '2025-11-25',
+      '8.0': '2023-11-26',
+      7.4: '2022-11-28',
+    },
+  },
+
+  /**
+   * Node.js Versions
+   * Tracks LTS and current stable releases
+   */
+  node: {
+    latest: '22',
+    lts: ['22', '20', '18'],
+    all: ['22', '20', '18'],
+    deprecated: ['16', '14', '12', '10'],
+    description: 'Supported Node.js versions - prefer LTS releases',
+    // LTS information: https://nodejs.org/en/about/releases/
+    ltsDates: {
+      22: { start: '2024-10-29', end: '2027-04-30' },
+      20: { start: '2023-10-24', end: '2026-04-30' },
+      18: { start: '2022-10-25', end: '2025-04-30' },
+    },
+  },
+};
+
+/**
+ * Helper functions for version management
+ */
+
+/**
+ * Get minimum WordPress version for a given Sage version
+ */
+export function getMinWordPresForSage(sageVersion) {
+  // Sage 11 requires WordPress 5.9+ due to theme.json requirements
+  if (sageVersion === '11') return '6.0'; // Recommend 6.5+
+  if (sageVersion === '10') return '5.9';
+  return '5.9';
+}
+
+/**
+ * Validate version compatibility
+ */
+export function validateVersionCompatibility(sage, php, node, wp) {
+  const errors = [];
+  const warnings = [];
+
+  // Check Sage requirements
+  const sageConfig = VERSION_REGISTRY.sage[sage];
+  if (!sageConfig) {
+    errors.push(`Sage version ${sage} not supported`);
+  } else {
+    const minPhp = sageConfig.minPhp;
+    if (parseFloat(php) < parseFloat(minPhp)) {
+      errors.push(`Sage ${sage} requires PHP ${minPhp}+ (got ${php})`);
+    }
+
+    if (sageConfig.status === 'legacy') {
+      warnings.push(`Sage ${sage} is in legacy status. Consider upgrading.`);
+    }
+  }
+
+  // Check PHP is supported
+  if (!VERSION_REGISTRY.php.supported.includes(php)) {
+    warnings.push(`PHP ${php} is out of standard support`);
+  }
+
+  // Check Node is supported
+  if (!VERSION_REGISTRY.node.all.includes(node)) {
+    warnings.push(`Node.js ${node} is not recommended`);
+  }
+
+  // Check WordPress is available
+  if (!VERSION_REGISTRY.wordpress.all.includes(wp)) {
+    warnings.push(`WordPress ${wp} may not be available in the expected repository`);
+  }
+
+  return { errors, warnings, isValid: errors.length === 0 };
+}
+
+/**
+ * Get recommended version combination for a given Sage version
+ */
+export function getRecommendedVersions(sageVersion = '11') {
+  return {
+    sage: sageVersion,
+    php: '8.3',
+    node: '22',
+    wp: '6.9.4',
+  };
+}
+
+/**
+ * Format version info for display
+ */
+export function formatVersionInfo() {
+  return `
+WordPress: ${VERSION_REGISTRY.wordpress.all.join(', ')}
+PHP: ${VERSION_REGISTRY.php.supported.join(', ')}
+Node.js: ${VERSION_REGISTRY.node.lts.join(', ')}
+Sage: 11 (${VERSION_REGISTRY.sage[11].tag}), 10 (${VERSION_REGISTRY.sage[10].tag})
+  `;
+}