kakaroto-config 1.0.1 → 1.0.2

package/bin/release.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const { execFileSync } = require('child_process');
+
+// Constants
+const HOME_CLAUDE = path.join(os.homedir(), '.claude');
+const PROJECT_ROOT = path.join(__dirname, '..');
+const CONFIG_DIR = path.join(PROJECT_ROOT, 'config');
+const PACKAGE_JSON = path.join(PROJECT_ROOT, 'package.json');
+
+// Exclusions - personal files not to publish
+const EXCLUDED_COMMANDS = ['audit-command', 'audit-command.md'];
+
+// Semver validation regex
+const SEMVER_REGEX = /^\d+\.\d+\.\d+$/;
+
+// Readline interface
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+function question(prompt) {
+  return new Promise((resolve) => {
+    rl.question(prompt, resolve);
+  });
+}
+
+function cleanDir(dir) {
+  if (fs.existsSync(dir)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function copyRecursive(src, dest, excludes = []) {
+  const stats = fs.statSync(src);
+
+  if (stats.isDirectory()) {
+    const baseName = path.basename(src);
+    if (excludes.includes(baseName)) {
+      return; // Skip excluded directories
+    }
+
+    if (!fs.existsSync(dest)) {
+      fs.mkdirSync(dest, { recursive: true });
+    }
+
+    const files = fs.readdirSync(src);
+    for (const file of files) {
+      if (excludes.includes(file)) {
+        continue; // Skip excluded files
+      }
+      copyRecursive(path.join(src, file), path.join(dest, file), excludes);
+    }
+  } else {
+    const baseName = path.basename(src);
+    if (excludes.includes(baseName)) {
+      return; // Skip excluded files
+    }
+    fs.copyFileSync(src, dest);
+    console.log(`  + ${path.relative(CONFIG_DIR, dest)}`);
+  }
+}
+
+function bumpVersion(version) {
+  if (!SEMVER_REGEX.test(version)) {
+    throw new Error(`Invalid semver format: ${version}. Expected X.Y.Z`);
+  }
+  const parts = version.split('.');
+  parts[2] = String(parseInt(parts[2], 10) + 1);
+  return parts.join('.');
+}
+
+function execCommandSafe(executable, args, description) {
+  console.log(`\n${description}...`);
+  try {
+    execFileSync(executable, args, { cwd: PROJECT_ROOT, stdio: 'inherit' });
+    return true;
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    return false;
+  }
+}
+
+function countFiles(dir, excludes = []) {
+  let count = 0;
+  if (!fs.existsSync(dir)) return 0;
+
+  const items = fs.readdirSync(dir);
+  for (const item of items) {
+    if (excludes.includes(item)) continue;
+
+    const fullPath = path.join(dir, item);
+    if (fs.statSync(fullPath).isDirectory()) {
+      count += countFiles(fullPath, excludes);
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+async function main() {
+  console.log('\n🥋 kakaroto-config - Release\n');
+
+  // Check ~/.claude exists
+  if (!fs.existsSync(HOME_CLAUDE)) {
+    console.error(`Error: ${HOME_CLAUDE} does not exist`);
+    rl.close();
+    process.exit(1);
+  }
+
+  // Read current version
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(PACKAGE_JSON, 'utf8'));
+  } catch (err) {
+    console.error(`Error reading package.json: ${err.message}`);
+    rl.close();
+    process.exit(1);
+  }
+
+  const currentVersion = pkg.version;
+  let newVersion;
+  try {
+    newVersion = bumpVersion(currentVersion);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    rl.close();
+    process.exit(1);
+  }
+
+  // Count files to sync
+  const commandsCount = countFiles(path.join(HOME_CLAUDE, 'commands'), EXCLUDED_COMMANDS);
+  const agentsCount = countFiles(path.join(HOME_CLAUDE, 'agents'));
+  const templatesCount = countFiles(path.join(HOME_CLAUDE, 'templates'));
+  const totalFiles = commandsCount + agentsCount + templatesCount + 2; // +2 for CLAUDE.md and ARCHITECTURE.md
+
+  // Show preview
+  console.log('This will:');
+  console.log(`  1. Sync ${totalFiles} files from ~/.claude/ to config/`);
+  console.log(`     - CLAUDE.md`);
+  console.log(`     - ARCHITECTURE.md`);
+  console.log(`     - commands/ (${commandsCount} files, excluding audit-command)`);
+  console.log(`     - agents/ (${agentsCount} files)`);
+  console.log(`     - templates/ (${templatesCount} files)`);
+  console.log(`  2. Bump version: ${currentVersion} → ${newVersion}`);
+  console.log(`  3. Git commit and push`);
+  console.log(`  4. Publish to npm\n`);
+
+  // Confirm
+  const answer = await question('Proceed with release? (Y/n): ');
+  if (answer.toLowerCase() === 'n') {
+    console.log('\nAborted. No changes made.');
+    rl.close();
+    process.exit(0);
+  }
+
+  console.log('\n--- Syncing files ---\n');
+
+  // Clean directories
+  cleanDir(path.join(CONFIG_DIR, 'commands'));
+  cleanDir(path.join(CONFIG_DIR, 'agents'));
+  cleanDir(path.join(CONFIG_DIR, 'templates'));
+
+  // Ensure config directory exists
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  }
+
+  // Copy files with existence check
+  const claudeMdPath = path.join(HOME_CLAUDE, 'CLAUDE.md');
+  if (fs.existsSync(claudeMdPath)) {
+    console.log('Copying CLAUDE.md...');
+    fs.copyFileSync(claudeMdPath, path.join(CONFIG_DIR, 'CLAUDE.md'));
+    console.log('  + CLAUDE.md');
+  } else {
+    console.warn('Warning: CLAUDE.md not found, skipping');
+  }
+
+  const archMdPath = path.join(HOME_CLAUDE, 'ARCHITECTURE.md');
+  if (fs.existsSync(archMdPath)) {
+    console.log('Copying ARCHITECTURE.md...');
+    fs.copyFileSync(archMdPath, path.join(CONFIG_DIR, 'ARCHITECTURE.md'));
+    console.log('  + ARCHITECTURE.md');
+  } else {
+    console.warn('Warning: ARCHITECTURE.md not found, skipping');
+  }
+
+  console.log('Copying commands/...');
+  copyRecursive(
+    path.join(HOME_CLAUDE, 'commands'),
+    path.join(CONFIG_DIR, 'commands'),
+    EXCLUDED_COMMANDS
+  );
+
+  console.log('Copying agents/...');
+  copyRecursive(
+    path.join(HOME_CLAUDE, 'agents'),
+    path.join(CONFIG_DIR, 'agents')
+  );
+
+  if (fs.existsSync(path.join(HOME_CLAUDE, 'templates'))) {
+    console.log('Copying templates/...');
+    copyRecursive(
+      path.join(HOME_CLAUDE, 'templates'),
+      path.join(CONFIG_DIR, 'templates')
+    );
+  }
+
+  // Update package.json
+  console.log('\n--- Updating version ---\n');
+  pkg.version = newVersion;
+  fs.writeFileSync(PACKAGE_JSON, JSON.stringify(pkg, null, 2) + '\n');
+  console.log(`Updated package.json: ${currentVersion} → ${newVersion}`);
+
+  // Git operations - use execCommandSafe for commands with user-derived values
+  if (!execCommandSafe('git', ['add', '.'], 'Staging changes')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  // Use execCommandSafe to prevent command injection via newVersion
+  if (!execCommandSafe('git', ['commit', '-m', `release: v${newVersion}`], 'Creating commit')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  if (!execCommandSafe('git', ['push'], 'Pushing to remote')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  // npm publish
+  if (!execCommandSafe('npm', ['publish'], 'Publishing to npm')) {
+    rl.close();
+    process.exit(1);
+  }
+
+  console.log(`\n✅ Release complete! Published v${newVersion}\n`);
+  console.log('Users can update with:');
+  console.log(`  npx kakaroto-config@${newVersion}\n`);
+
+  rl.close();
+}
+
+main().catch((err) => {
+  console.error(`Unexpected error: ${err.message}`);
+  rl.close();
+  process.exit(1);
+});

package/config/ARCHITECTURE.md

@@ -97,11 +97,9 @@ Este documento descreve a arquitetura de configuracao do Claude Code, otimizada
 │   │
 │   ├── debug.md             # /debug - orquestrador
 │   ├── debug/
-│   │   ├── 01-reproduce.md   # Fase 1: reproduzir bug
-│   │   ├── 02-investigate.md # Fase 2: 5 Whys
-│   │   ├── 03-fix.md         # Fase 3: correcao minima
-│   │   ├── 04-verify.md      # Fase 4: confirmar fix
-│   │   └── 05-commit.md      # Fase 5: commit
+│   │   ├── 01-investigate.md # Fase 1: 5 Whys
+│   │   ├── 02-fix.md         # Fase 2: correcao minima
+│   │   └── 03-verify.md      # Fase 3: confirmar fix
 │   │
 │   └── gate.md              # /gate - quality gate completo
 │
@@ -134,7 +132,8 @@ projeto/.claude/
 │
 ├── settings.json             # Config do Claude Code
 ├── visual-validation.json    # Routes para visual-validator (opcional)
-└── terraform-validation.json # Paths para terraform-validator (opcional)
+├── terraform-validation.json # Paths para terraform-validator (opcional)
+└── debug-logs.json           # Comandos para query de logs de producao (opcional)
 ```
 
 **Personalizacoes por projeto:**
@@ -144,6 +143,7 @@ projeto/.claude/
 | `commands/*.md` | Skills especificas (deploy, E2E, migrations) | Quando projeto tem workflows unicos |
 | `visual-validation.json` | Mapeia components → routes para teste | Projetos com UI complexa |
 | `terraform-validation.json` | Paths de env vars e terraform | Projetos com infra como codigo |
+| `debug-logs.json` | Comandos para query de logs de producao | Projetos com logs em Cloud Logging, CloudWatch, etc. |
 | `settings.json` | Modelo default, permissoes, etc. | Config avancada |
 
 **CLAUDE.md do projeto deve conter:**
@@ -218,28 +218,22 @@ User: "erro ao publicar video"
            │
            ▼
 ┌────────────────────────┐     ┌────────────────────────┐
-│   01-reproduce.md      │────►│   02-investigate.md    │
-│   - Criar teste que    │     │   - 5 Whys com         │
-│     reproduz o bug     │     │     EVIDENCIA          │
-│   - Confirmar falha    │     │   - Root cause         │
-└────────────────────────┘     └───────────┬────────────┘
+│   01-investigate.md    │────►│   02-fix.md            │
+│   - Reproduzir bug     │     │   - Gate de criticidade│
+│   - 5 Whys com         │     │   - EnterPlanMode se   │
+│     EVIDENCIA          │     │     path critico       │
+└────────────────────────┘     │   - Fix MINIMO         │
+                               │   - Testes obrigatorio │
+                               └───────────┬────────────┘
                                            │
                                            ▼
-┌────────────────────────┐     ┌────────────────────────┐
-│   04-verify.md         │◄────│   03-fix.md            │
-│   - Rodar teste        │     │   - Fix MINIMO         │
-│   - Confirmar que      │     │   - Apenas o necessario│
-│     passou             │     │   - Nao refatorar      │
-└───────────┬────────────┘     └────────────────────────┘
-            │
-            ▼
-┌────────────────────────┐
-│   05-commit.md         │
-│   - Commit do fix      │
-│   - Padrao de mensagem │
-│   - Memory sync se     │
-│     bug raro           │
-└────────────────────────┘
+                               ┌────────────────────────┐
+                               │   03-verify.md         │
+                               │   - Reproduzir fix     │
+                               │   - Quality gates      │
+                               │   - Salvar bug raro    │
+                               │     em MCP Memory      │
+                               └────────────────────────┘
 ```
 
 ### /gate (Quality Gate Antes de PR)

package/config/CLAUDE.md

@@ -22,3 +22,7 @@ Exceções: config files, .d.ts, UI puro sem lógica.
 ## Memory
 Namespace: ver CLAUDE.md do projeto.
 Sincronizar via `memory-sync` ao final de workflows.
+
+## Auto-Avaliacao
+Apos /feature e /debug: executar fase de avaliacao (07/06-evaluate).
+Dual-loop sequential thinking: diagnostico → sintese → propor melhorias ao user.

package/config/agents/memory-sync.md

@@ -15,14 +15,29 @@ Sincronizar conhecimento adquirido com MCP Memory apos desenvolvimento.
 2. `git diff --stat` para entender escopo das mudancas
 3. Identificar o prefixo do projeto via `mcp__memory__search_nodes({ query: "config" })`
 
-## Fase 2: Verificar Entidades Existentes
+## Fase 2: Verificar Entidades Existentes + Garbage Collection
 
 1. `mcp__memory__read_graph()` para ver todas entidades do projeto
 2. Filtrar entidades pelo prefixo do projeto (ex: `sm:` para social-medias)
-3. Para cada arquivo modificado/deletado:
+3. **CONTAR entidades do projeto atual**:
+   - Se > 50 entidades → executar Garbage Collection abaixo
+   - Se ≤ 50 → prosseguir normalmente
+
+### Garbage Collection (se > 50 entidades)
+
+Identificar e REMOVER:
+
+| Candidata | Critério | Ação |
+|-----------|----------|------|
+| Bugs | entityType === "bug" | DELETE todos |
+| Outros projetos | nome não começa com prefixo atual | DELETE |
+| Versões duplicadas | nome contém "-v2", "-v3" | MERGE em original, DELETE versão |
+| Arquivos inexistentes | observation referencia arquivo deletado | DELETE se única referência |
+
+4. Para cada arquivo modificado/deletado:
    - Buscar entidades que o referenciam (grep no campo observations)
-   - SE arquivo deletado -> marcar entidade para atualizacao
-   - SE arquivo renomeado -> atualizar referencias
+   - SE arquivo deletado -> marcar entidade para atualização
+   - SE arquivo renomeado -> atualizar referências
    - SE comportamento mudou -> atualizar observations
 
 ## Fase 3: Atualizar Entidades Obsoletas
@@ -45,13 +60,15 @@ Avaliar o que foi desenvolvido e criar entidades conforme tabela:
 
 | Situacao | Namespace | Criar? |
 |----------|-----------|--------|
-| Padrao novo implementado | `{prefix}:pattern:{nome}` | SIM |
+| Padrão novo implementado | `{prefix}:pattern:{nome}` | SIM |
 | Fluxo complexo entendido | `{prefix}:fluxo:{nome}` | SIM |
-| Bug nao-obvio resolvido | `{prefix}:bug:{nome}` | SIM |
-| Servico novo/modificado significativamente | `{prefix}:servico:{nome}` | SE significativo |
-| Tipo importante descoberto | `{prefix}:tipo:{nome}` | SE reutilizavel |
+| Serviço novo/modificado significativamente | `{prefix}:servico:{nome}` | SE significativo |
+| Tipo importante descoberto | `{prefix}:tipo:{nome}` | SE reutilizável |
 | Procedimento documentado | `{prefix}:procedimento:{nome}` | SIM |
-| Analise importante feita | `{prefix}:analise:{nome}` | SE referenciavel |
+| Análise importante feita | `{prefix}:analise:{nome}` | SE referenciável |
+| Config de projeto | `{prefix}:config:{nome}` | APENAS config:main |
+
+**REMOVIDO**: `{prefix}:bug:{nome}` - bugs são efêmeros, fixes vão no código
 
 ### Criterio "Vale Salvar"
 
@@ -68,18 +85,34 @@ Avaliar o que foi desenvolvido e criar entidades conforme tabela:
 - Detalhes de implementacao que mudam frequentemente
 - Duplicatas de entidades existentes
 
+### Pre-Flight Check (OBRIGATÓRIO antes de criar)
+
+Antes de `mcp__memory__create_entities`, verificar:
+
+```
+[ ] Nome usa prefixo correto do projeto atual?
+[ ] Nome está em kebab-case?
+[ ] Não é um bug? (bugs não devem ser salvos)
+[ ] Não existe entidade similar? (usar search_nodes)
+[ ] Não é versão de entidade existente? (update, não create)
+[ ] Máximo 10 observations?
+[ ] Informação não é óbvia pelo código?
+```
+
+Se QUALQUER check falhar → NÃO CRIAR
+
 ### Formato de Entidade
 
 ```javascript
 mcp__memory__create_entities({
   entities: [{
     name: "{prefix}:{tipo}:{nome-kebab-case}",
-    entityType: "{tipo}",  // pattern, bug, fluxo, servico, etc.
+    entityType: "{tipo}",  // pattern, fluxo, servico, etc. (NUNCA bug)
     observations: [
-      "Primeira linha: resumo do que e",
+      "Primeira linha: resumo do que é",
       "Segunda linha: arquivo principal: path/to/file.ts",
-      "Demais linhas: detalhes relevantes",
-      "Ultima linha: quando/por que foi criado"
+      "Demais linhas: detalhes relevantes (max 8 linhas adicionais)",
+      "Última linha: quando/por que foi criado"
     ]
   }]
 })
@@ -110,13 +143,48 @@ Ao final, reportar:
 - OU: Todas entidades ja estao atualizadas
 ```
 
-## Regras
+## Regras OBRIGATÓRIAS
+
+### Namespace & Escopo
+
+1. **Prefixo obrigatório**: TODA entidade DEVE usar o prefixo do projeto atual
+2. **NUNCA criar entidades de outros projetos** (ex: `ga:`, `kk:` quando trabalhando em `sm:`)
+3. **Validar namespace**: Antes de criar, verificar se prefixo corresponde ao projeto
+
+### Controle de Tamanho
+
+4. **Max 10 observations por entidade**: Se precisar de mais, dividir em entidades relacionadas
+5. **Max 50 entidades por projeto**: Se ultrapassar, fazer garbage collection
+6. **Nomes kebab-case**: `sm:pattern:graceful-shutdown`, não `sm:pattern:GracefulShutdown`
+7. **Observations atômicas**: Uma informação por linha, fácil de deletar/atualizar
+
+### O que NÃO salvar
+
+8. **NUNCA salvar bugs como entidades** - bugs são efêmeros, fixes vão no código
+   - Exception: Bug recorrente que revela pattern arquitetural → salvar como `pattern:`
+9. **NUNCA criar versões** (v2, v3) - ATUALIZAR a entidade existente
+10. **NUNCA duplicar**: Buscar entidade similar antes de criar (`search_nodes`)
+11. **Minimalismo radical**: Na dúvida, NÃO salvar
+
+### Garbage Collection (executar se >50 entidades)
+
+```javascript
+// Identificar candidatas a remoção:
+// 1. Entidades que referenciam arquivos deletados
+// 2. Entidades com >15 observations (muito verbosas)
+// 3. Entidades com informação duplicada de outra
+// 4. Bugs antigos (>30 dias)
+```
+
+### Anti-Patterns a EVITAR
 
-1. **Prefixo obrigatorio**: Toda entidade deve usar o prefixo do projeto
-2. **Nomes kebab-case**: `sm:bug:tiktok-media-id-vazio`, nao `sm:bug:TikTokMediaIdVazio`
-3. **Observations atomicas**: Uma informacao por linha, facil de deletar/atualizar
-4. **Nao duplicar**: Verificar se entidade similar ja existe antes de criar
-5. **Minimalismo**: Na duvida, nao salvar. Menos entidades de qualidade > muitas entidades ruins
+| Anti-Pattern | Exemplo | Correção |
+|--------------|---------|----------|
+| Bug como entidade | `sm:bug:login-error` | DELETE - fix está no código |
+| Versões separadas | `sm:pattern:X-v2` | UPDATE `sm:pattern:X` |
+| Cross-project | `ga:feature:Y` no sm: | DELETE - pertence a outro projeto |
+| Observations demais | 17 observations | Condensar em 8-10 |
+| Tipo duplicado | `pattern` + `padrao` | Usar apenas `pattern` |
 
 ---
 

package/config/agents/test-fixer.md

@@ -58,6 +58,30 @@ npm run test
 
 ---
 
+## Step Extra: CRUD Smoke Test (SE nova entidade)
+
+**Trigger:** Arquivo em `api/handlers/` com novo endpoint POST/PUT criado.
+
+1. Identificar endpoints novos:
+   ```bash
+   git diff --name-only HEAD~1 | grep 'api/handlers/'
+   ```
+
+2. Para cada arquivo de handler modificado:
+   - Buscar métodos POST/PUT/DELETE
+   - Construir payload de teste válido
+   - Executar request contra servidor local (se rodando)
+   - Verificar response 200/201
+
+3. Reportar:
+   - Endpoints testados
+   - Resultados (PASS/FAIL)
+   - Erros encontrados
+
+**Nota:** Este step é condicional. Só executar se houver novos endpoints CRUD.
+
+---
+
 ## Test Creation Guidelines
 
 ### File Location

package/config/agents/visual-validator.md

@@ -138,6 +138,23 @@ For each modified component file:
 
 ---
 
+### 6.5 Form Submit Test (SE form modificado)
+
+**Trigger:** Arquivo `*FormModal.tsx` ou `*Form.tsx` modificado.
+
+1. Identificar forms modificados via git diff
+2. Navegar ao form (browser_navigate)
+3. Preencher campos com dados válidos (browser_fill_form)
+4. Clicar submit
+5. Verificar:
+   - Sem erros de console
+   - Toast/mensagem de sucesso aparece
+   - Modal fecha ou redireciona
+
+**Nota:** Step condicional. Só executar se form de criação/edição foi modificado.
+
+---
+
 ### 7. Fix Loop (Max 3 Attempts)
 
 ```