create-genia-os 2.1.1 → 2.3.0

package/template/.genia/guidelines/clean-code.md

@@ -1,98 +1,98 @@
-# Guideline: Clean Code
-
-> Padroes de codigo pragmaticos - conciso, direto, sem over-engineering.
-
-## Principios Core
-
-| Principio | Regra |
-|-----------|-------|
-| **SRP** | Single Responsibility - cada funcao/classe faz UMA coisa |
-| **DRY** | Don't Repeat Yourself - extrair duplicatas, reusar |
-| **KISS** | Keep It Simple - solucao mais simples que funciona |
-| **YAGNI** | You Aren't Gonna Need It - nao construir features nao usadas |
-| **Boy Scout** | Deixar codigo mais limpo do que encontrou |
-
-## Regras de Naming
-
-| Elemento | Convencao |
-|----------|-----------|
-| **Variaveis** | Revelar intencao: `userCount` nao `n` |
-| **Funcoes** | Verbo + substantivo: `getUserById()` nao `user()` |
-| **Booleans** | Forma de pergunta: `isActive`, `hasPermission`, `canEdit` |
-| **Constantes** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
-
-> **Regra:** Se voce precisa de um comentario para explicar o nome, renomeie.
-
-## Regras de Funcao
-
-| Regra | Descricao |
-|-------|-----------|
-| **Pequena** | Max 20 linhas, idealmente 5-10 |
-| **Uma Coisa** | Faz uma coisa, faz bem |
-| **Um Nivel** | Um nivel de abstracao por funcao |
-| **Poucos Args** | Max 3 argumentos, preferir 0-2 |
-| **Sem Side Effects** | Nao mutar inputs inesperadamente |
-
-## Estrutura de Codigo
-
-| Padrao | Aplicar |
-|--------|---------|
-| **Guard Clauses** | Early returns para edge cases |
-| **Flat > Nested** | Evitar nesting profundo (max 2 niveis) |
-| **Composicao** | Funcoes pequenas compostas |
-| **Colocacao** | Manter codigo relacionado proximo |
-
-## Estilo de Codigo AI
-
-| Situacao | Acao |
-|----------|------|
-| Usuario pede feature | Escrever diretamente |
-| Usuario reporta bug | Corrigir, nao explicar |
-| Requisito nao claro | Perguntar, nao assumir |
-
-## Anti-Patterns
-
-| NAO Fazer | Fazer |
-|-----------|-------|
-| Comentar cada linha | Deletar comentarios obvios |
-| Helper para one-liner | Inline o codigo |
-| Factory para 2 objetos | Instanciacao direta |
-| utils.ts com 1 funcao | Colocar onde usado |
-| "First we import..." | Apenas escrever codigo |
-| Deep nesting | Guard clauses |
-| Magic numbers | Named constants |
-| God functions | Dividir por responsabilidade |
-
-## Antes de Editar Qualquer Arquivo
-
-| Pergunta | Por que |
-|----------|---------|
-| **O que importa este arquivo?** | Pode quebrar |
-| **O que este arquivo importa?** | Mudanca de interface |
-| **Quais testes cobrem isso?** | Testes podem falhar |
-| **E um componente compartilhado?** | Multiplos lugares afetados |
-
-> **Regra:** Editar arquivo + todos dependentes na MESMA tarefa.
-
-## Self-Check Antes de Completar
-
-| Check | Pergunta |
-|-------|----------|
-| **Objetivo alcancado?** | Fiz exatamente o que usuario pediu? |
-| **Arquivos editados?** | Modifiquei todos arquivos necessarios? |
-| **Codigo funciona?** | Testei/verifiquei a mudanca? |
-| **Sem erros?** | Lint e TypeScript passam? |
-| **Nada esquecido?** | Algum edge case perdido? |
-
-## Resumo
-
-| Fazer | Nao Fazer |
-|-------|-----------|
-| Escrever codigo direto | Escrever tutoriais |
-| Deixar codigo se auto-documentar | Adicionar comentarios obvios |
-| Corrigir bugs imediatamente | Explicar o fix primeiro |
-| Inline coisas pequenas | Criar arquivos desnecessarios |
-| Nomear coisas claramente | Usar abreviacoes |
-| Manter funcoes pequenas | Escrever funcoes 100+ linhas |
-
-> **Lembrar: O usuario quer codigo funcionando, nao uma aula de programacao.**
+# Guideline: Clean Code
+
+> Padroes de codigo pragmaticos - conciso, direto, sem over-engineering.
+
+## Principios Core
+
+| Principio | Regra |
+|-----------|-------|
+| **SRP** | Single Responsibility - cada funcao/classe faz UMA coisa |
+| **DRY** | Don't Repeat Yourself - extrair duplicatas, reusar |
+| **KISS** | Keep It Simple - solucao mais simples que funciona |
+| **YAGNI** | You Aren't Gonna Need It - nao construir features nao usadas |
+| **Boy Scout** | Deixar codigo mais limpo do que encontrou |
+
+## Regras de Naming
+
+| Elemento | Convencao |
+|----------|-----------|
+| **Variaveis** | Revelar intencao: `userCount` nao `n` |
+| **Funcoes** | Verbo + substantivo: `getUserById()` nao `user()` |
+| **Booleans** | Forma de pergunta: `isActive`, `hasPermission`, `canEdit` |
+| **Constantes** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+
+> **Regra:** Se voce precisa de um comentario para explicar o nome, renomeie.
+
+## Regras de Funcao
+
+| Regra | Descricao |
+|-------|-----------|
+| **Pequena** | Max 20 linhas, idealmente 5-10 |
+| **Uma Coisa** | Faz uma coisa, faz bem |
+| **Um Nivel** | Um nivel de abstracao por funcao |
+| **Poucos Args** | Max 3 argumentos, preferir 0-2 |
+| **Sem Side Effects** | Nao mutar inputs inesperadamente |
+
+## Estrutura de Codigo
+
+| Padrao | Aplicar |
+|--------|---------|
+| **Guard Clauses** | Early returns para edge cases |
+| **Flat > Nested** | Evitar nesting profundo (max 2 niveis) |
+| **Composicao** | Funcoes pequenas compostas |
+| **Colocacao** | Manter codigo relacionado proximo |
+
+## Estilo de Codigo AI
+
+| Situacao | Acao |
+|----------|------|
+| Usuario pede feature | Escrever diretamente |
+| Usuario reporta bug | Corrigir, nao explicar |
+| Requisito nao claro | Perguntar, nao assumir |
+
+## Anti-Patterns
+
+| NAO Fazer | Fazer |
+|-----------|-------|
+| Comentar cada linha | Deletar comentarios obvios |
+| Helper para one-liner | Inline o codigo |
+| Factory para 2 objetos | Instanciacao direta |
+| utils.ts com 1 funcao | Colocar onde usado |
+| "First we import..." | Apenas escrever codigo |
+| Deep nesting | Guard clauses |
+| Magic numbers | Named constants |
+| God functions | Dividir por responsabilidade |
+
+## Antes de Editar Qualquer Arquivo
+
+| Pergunta | Por que |
+|----------|---------|
+| **O que importa este arquivo?** | Pode quebrar |
+| **O que este arquivo importa?** | Mudanca de interface |
+| **Quais testes cobrem isso?** | Testes podem falhar |
+| **E um componente compartilhado?** | Multiplos lugares afetados |
+
+> **Regra:** Editar arquivo + todos dependentes na MESMA tarefa.
+
+## Self-Check Antes de Completar
+
+| Check | Pergunta |
+|-------|----------|
+| **Objetivo alcancado?** | Fiz exatamente o que usuario pediu? |
+| **Arquivos editados?** | Modifiquei todos arquivos necessarios? |
+| **Codigo funciona?** | Testei/verifiquei a mudanca? |
+| **Sem erros?** | Lint e TypeScript passam? |
+| **Nada esquecido?** | Algum edge case perdido? |
+
+## Resumo
+
+| Fazer | Nao Fazer |
+|-------|-----------|
+| Escrever codigo direto | Escrever tutoriais |
+| Deixar codigo se auto-documentar | Adicionar comentarios obvios |
+| Corrigir bugs imediatamente | Explicar o fix primeiro |
+| Inline coisas pequenas | Criar arquivos desnecessarios |
+| Nomear coisas claramente | Usar abreviacoes |
+| Manter funcoes pequenas | Escrever funcoes 100+ linhas |
+
+> **Lembrar: O usuario quer codigo funcionando, nao uma aula de programacao.**

package/template/.genia/guidelines/testing.md

@@ -1,176 +1,176 @@
-# Guideline: Testing Patterns
-
-> Principios para suites de teste confiaveis.
-
-## Piramide de Testes
-
-```
-        /\          E2E (Poucos)
-       /  \         Fluxos criticos
-      /----\
-     /      \       Integration (Alguns)
-    /--------\      API, DB queries
-   /          \
-  /------------\    Unit (Muitos)
-                    Funcoes, classes
-```
-
-## Padrao AAA
-
-| Etapa | Proposito |
-|-------|-----------|
-| **Arrange** | Configurar dados de teste |
-| **Act** | Executar codigo sob teste |
-| **Assert** | Verificar resultado |
-
-## Selecao de Tipo de Teste
-
-| Tipo | Melhor Para | Velocidade |
-|------|-------------|------------|
-| **Unit** | Funcoes puras, logica | Rapido (<50ms) |
-| **Integration** | API, DB, servicos | Medio |
-| **E2E** | Fluxos criticos do usuario | Lento |
-
-## Principios de Unit Test
-
-### Bons Unit Tests (FIRST)
-
-| Principio | Significado |
-|-----------|-------------|
-| Fast | < 100ms cada |
-| Isolated | Sem deps externos |
-| Repeatable | Mesmo resultado sempre |
-| Self-checking | Sem verificacao manual |
-| Timely | Escritos com o codigo |
-
-### O Que Testar
-
-| Testar | Nao Testar |
-|--------|------------|
-| Business logic | Codigo do framework |
-| Edge cases | Libs de terceiros |
-| Error handling | Getters simples |
-
-## Principios de Integration Test
-
-### O Que Testar
-
-| Area | Foco |
-|------|------|
-| API endpoints | Request/response |
-| Database | Queries, transactions |
-| External services | Contratos |
-
-### Setup/Teardown
-
-| Fase | Acao |
-|------|------|
-| Before All | Conectar recursos |
-| Before Each | Resetar estado |
-| After Each | Limpar |
-| After All | Desconectar |
-
-## Principios de Mocking
-
-### Quando Fazer Mock
-
-| Mock | Nao Mock |
-|------|----------|
-| External APIs | Codigo sob teste |
-| Database (unit) | Dependencias simples |
-| Time/random | Funcoes puras |
-| Network | Stores in-memory |
-
-### Tipos de Mock
-
-| Tipo | Uso |
-|------|-----|
-| Stub | Retornar valores fixos |
-| Spy | Rastrear chamadas |
-| Mock | Definir expectativas |
-| Fake | Implementacao simplificada |
-
-## Organizacao de Testes
-
-### Naming
-
-| Padrao | Exemplo |
-|--------|---------|
-| Should behavior | "should return error when..." |
-| When condition | "when user not found..." |
-| Given-when-then | "given X, when Y, then Z" |
-
-### Agrupamento
-
-| Nivel | Uso |
-|-------|-----|
-| describe | Agrupar testes relacionados |
-| it/test | Caso individual |
-| beforeEach | Setup comum |
-
-## Dados de Teste
-
-### Estrategias
-
-| Abordagem | Uso |
-|-----------|-----|
-| Factories | Gerar dados de teste |
-| Fixtures | Datasets predefinidos |
-| Builders | Criacao fluente de objetos |
-
-### Principios
-- Usar dados realistas
-- Randomizar valores nao essenciais (faker)
-- Compartilhar fixtures comuns
-- Manter dados minimos
-
-## Best Practices
-
-| Pratica | Por que |
-|---------|---------|
-| Um assert por teste | Razao clara de falha |
-| Testes independentes | Sem dependencia de ordem |
-| Testes rapidos | Rodar frequentemente |
-| Nomes descritivos | Auto-documentacao |
-| Limpar | Evitar side effects |
-
-## Anti-Patterns
-
-| NAO Fazer | Fazer |
-|-----------|-------|
-| Testar implementacao | Testar comportamento |
-| Duplicar codigo de teste | Usar factories |
-| Setup complexo | Simplificar ou dividir |
-| Ignorar testes flaky | Corrigir causa raiz |
-| Pular cleanup | Resetar estado |
-
-## Exemplo de Teste
-
-```typescript
-describe('UserService', () => {
-  describe('createUser', () => {
-    it('should create user with valid data', async () => {
-      // Arrange
-      const userData = { name: 'John', email: 'john@test.com' };
-
-      // Act
-      const user = await userService.createUser(userData);
-
-      // Assert
-      expect(user.id).toBeDefined();
-      expect(user.name).toBe('John');
-    });
-
-    it('should throw error when email is invalid', async () => {
-      // Arrange
-      const userData = { name: 'John', email: 'invalid' };
-
-      // Act & Assert
-      await expect(userService.createUser(userData))
-        .rejects.toThrow('Invalid email');
-    });
-  });
-});
-```
-
-> **Lembrar:** Testes sao documentacao. Se alguem nao consegue entender o que o codigo faz pelos testes, reescreva-os.
+# Guideline: Testing Patterns
+
+> Principios para suites de teste confiaveis.
+
+## Piramide de Testes
+
+```
+        /\          E2E (Poucos)
+       /  \         Fluxos criticos
+      /----\
+     /      \       Integration (Alguns)
+    /--------\      API, DB queries
+   /          \
+  /------------\    Unit (Muitos)
+                    Funcoes, classes
+```
+
+## Padrao AAA
+
+| Etapa | Proposito |
+|-------|-----------|
+| **Arrange** | Configurar dados de teste |
+| **Act** | Executar codigo sob teste |
+| **Assert** | Verificar resultado |
+
+## Selecao de Tipo de Teste
+
+| Tipo | Melhor Para | Velocidade |
+|------|-------------|------------|
+| **Unit** | Funcoes puras, logica | Rapido (<50ms) |
+| **Integration** | API, DB, servicos | Medio |
+| **E2E** | Fluxos criticos do usuario | Lento |
+
+## Principios de Unit Test
+
+### Bons Unit Tests (FIRST)
+
+| Principio | Significado |
+|-----------|-------------|
+| Fast | < 100ms cada |
+| Isolated | Sem deps externos |
+| Repeatable | Mesmo resultado sempre |
+| Self-checking | Sem verificacao manual |
+| Timely | Escritos com o codigo |
+
+### O Que Testar
+
+| Testar | Nao Testar |
+|--------|------------|
+| Business logic | Codigo do framework |
+| Edge cases | Libs de terceiros |
+| Error handling | Getters simples |
+
+## Principios de Integration Test
+
+### O Que Testar
+
+| Area | Foco |
+|------|------|
+| API endpoints | Request/response |
+| Database | Queries, transactions |
+| External services | Contratos |
+
+### Setup/Teardown
+
+| Fase | Acao |
+|------|------|
+| Before All | Conectar recursos |
+| Before Each | Resetar estado |
+| After Each | Limpar |
+| After All | Desconectar |
+
+## Principios de Mocking
+
+### Quando Fazer Mock
+
+| Mock | Nao Mock |
+|------|----------|
+| External APIs | Codigo sob teste |
+| Database (unit) | Dependencias simples |
+| Time/random | Funcoes puras |
+| Network | Stores in-memory |
+
+### Tipos de Mock
+
+| Tipo | Uso |
+|------|-----|
+| Stub | Retornar valores fixos |
+| Spy | Rastrear chamadas |
+| Mock | Definir expectativas |
+| Fake | Implementacao simplificada |
+
+## Organizacao de Testes
+
+### Naming
+
+| Padrao | Exemplo |
+|--------|---------|
+| Should behavior | "should return error when..." |
+| When condition | "when user not found..." |
+| Given-when-then | "given X, when Y, then Z" |
+
+### Agrupamento
+
+| Nivel | Uso |
+|-------|-----|
+| describe | Agrupar testes relacionados |
+| it/test | Caso individual |
+| beforeEach | Setup comum |
+
+## Dados de Teste
+
+### Estrategias
+
+| Abordagem | Uso |
+|-----------|-----|
+| Factories | Gerar dados de teste |
+| Fixtures | Datasets predefinidos |
+| Builders | Criacao fluente de objetos |
+
+### Principios
+- Usar dados realistas
+- Randomizar valores nao essenciais (faker)
+- Compartilhar fixtures comuns
+- Manter dados minimos
+
+## Best Practices
+
+| Pratica | Por que |
+|---------|---------|
+| Um assert por teste | Razao clara de falha |
+| Testes independentes | Sem dependencia de ordem |
+| Testes rapidos | Rodar frequentemente |
+| Nomes descritivos | Auto-documentacao |
+| Limpar | Evitar side effects |
+
+## Anti-Patterns
+
+| NAO Fazer | Fazer |
+|-----------|-------|
+| Testar implementacao | Testar comportamento |
+| Duplicar codigo de teste | Usar factories |
+| Setup complexo | Simplificar ou dividir |
+| Ignorar testes flaky | Corrigir causa raiz |
+| Pular cleanup | Resetar estado |
+
+## Exemplo de Teste
+
+```typescript
+describe('UserService', () => {
+  describe('createUser', () => {
+    it('should create user with valid data', async () => {
+      // Arrange
+      const userData = { name: 'John', email: 'john@test.com' };
+
+      // Act
+      const user = await userService.createUser(userData);
+
+      // Assert
+      expect(user.id).toBeDefined();
+      expect(user.name).toBe('John');
+    });
+
+    it('should throw error when email is invalid', async () => {
+      // Arrange
+      const userData = { name: 'John', email: 'invalid' };
+
+      // Act & Assert
+      await expect(userService.createUser(userData))
+        .rejects.toThrow('Invalid email');
+    });
+  });
+});
+```
+
+> **Lembrar:** Testes sao documentacao. Se alguem nao consegue entender o que o codigo faz pelos testes, reescreva-os.