@onion-ai/cli 1.0.0-beta.1

package/framework/rules/language-and-documentation.mdc

@@ -0,0 +1,371 @@
+---
+title: Language and Documentation Standards
+description: Regras de idioma, documentação e fluxo de trabalho para o projeto
+tags: [language, documentation, workflow, standards]
+priority: high
+version: 3.0.0
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# Language and Documentation Standards
+
+## 🎯 Objetivo
+
+Estabelecer padrões consistentes de idioma e documentação em todo o projeto, garantindo que código seja universal (inglês) enquanto comunicação e explicações sejam localizadas (pt-BR).
+
+## 📋 Regras Fundamentais
+
+### 1. Idiomas no Código
+
+#### ✅ SEMPRE em Inglês (en-US)
+- **Nomes de variáveis, funções, classes e interfaces**
+  ```typescript
+  // ✅ CORRETO
+  interface UserProfile {
+    userName: string;
+    createdAt: Date;
+  }
+  
+  // ❌ INCORRETO
+  interface PerfilUsuario {
+    nomeUsuario: string;
+    criadoEm: Date;
+  }
+  ```
+
+- **Nomes de arquivos e diretórios**
+  ```
+  ✅ user-profile.component.tsx
+  ✅ authentication-service.ts
+  ❌ perfil-usuario.component.tsx
+  ❌ servico-autenticacao.ts
+  ```
+
+- **Commits no Git**
+  ```bash
+  # ✅ CORRETO
+  git commit -m "feat: add user authentication flow"
+  
+  # ❌ INCORRETO
+  git commit -m "feat: adicionar fluxo de autenticação"
+  ```
+
+- **Nomes de branches**
+  ```bash
+  ✅ feature/user-dashboard
+  ✅ fix/authentication-bug
+  ❌ feature/painel-usuario
+  ❌ fix/erro-autenticacao
+  ```
+
+- **Documentação técnica de API (schemas, endpoints, responses)**
+
+#### ✅ SEMPRE em English (en-GB)
+- **Comentários no código**
+  ```typescript
+  // ✅ CORRETO
+  /**
+   * Busca o perfil do usuário no banco de dados
+   * @param userId - ID único do usuário
+   * @returns Perfil completo ou null se não encontrado
+   */
+  async function getUserProfile(userId: string): Promise<UserProfile | null> {
+    // Valida se o ID é válido antes de fazer a consulta
+    if (!isValidUUID(userId)) {
+      return null;
+    }
+    // ... resto da implementação
+  }
+  
+  // ❌ INCORRETO
+  /**
+   * Fetch user profile from database
+   * @param userId - Unique user ID
+   * @returns Full profile or null if not found
+   */
+  ```
+
+- **Respostas e explicações do assistente IA**
+- **Documentação de processos e workflows**
+- **READMEs e guias de uso** (exceto código e comandos)
+- **Mensagens de erro personalizadas para usuários finais**
+- **Logs de aplicação voltados para debugging**
+
+### 2. Documentação do Projeto
+
+#### ✅ Manter Sincronizado com a Documentação
+- **Antes de implementar qualquer mudança estrutural:**
+  1. Consultar documentação existente em `/docs/`
+  2. Verificar padrões estabelecidos em `.claude/commands/`
+  3. Revisar agentes especializados em `.claude/agents/`
+  4. Ler regras de projeto em `.claude/rules/`
+
+- **Ao introduzir novos padrões:**
+  1. Documentar em `.claude/docs/` ou `/docs/` conforme apropriado
+  2. Atualizar comandos relacionados em `.claude/commands/`
+  3. Notificar sobre mudanças em padrões estabelecidos
+
+#### ✅ Hierarquia de Documentação
+```
+/docs/                          # Documentação de negócio e produto
+├── meta-specs/                 # Especificações meta do projeto
+├── technical-context/          # Contexto técnico e arquitetura
+└── business-context/           # Contexto de negócio
+
+.claude/                        # Documentação de desenvolvimento
+├── docs/                       # Documentação de processo e workflow
+│   ├── templates/              # Templates reutilizáveis
+│   └── guides/                 # Guias específicos
+├── commands/                   # Comandos Cursor
+│   ├── meta/                   # Comandos meta (criar comandos, etc)
+│   ├── development/            # Comandos de desenvolvimento
+│   └── docs/                   # Comandos de documentação
+├── agents/                     # Agentes especializados
+│   ├── meta/                   # Agentes meta (Onion, etc)
+│   └── development/            # Agentes de desenvolvimento
+└── rules/                      # Regras do projeto (este arquivo)
+```
+
+### 3. Sintaxes e Estratégias Oficiais
+
+#### ✅ SEMPRE Consultar Documentação Oficial
+- **ZenStack**: Usar sempre a sintaxe da versão oficial no projeto
+- **NX**: Seguir padrões de workspace da versão instalada
+- **Tamagui**: Aderir às convenções de componentes universais
+- **Expo**: Respeitar limitações e features do SDK atual
+- **React Native**: Seguir patterns recomendados pela versão em uso
+
+#### ⚠️ NUNCA Inventar Sintaxe
+- Verificar documentação oficial antes de implementar
+- Testar em sandbox se houver dúvida
+- Documentar desvios necessários com justificativa
+
+### 4. Workflow de Execução
+
+#### ✅ SEMPRE Antes de Finalizar
+1. **Propor próximo passo lógico:**
+   ```markdown
+   ## 🚀 Próximo Passo Sugerido
+   
+   Agora que criamos [X], o próximo passo recomendado é:
+   
+   **Opção 1 (Recomendada):** [Ação + Justificativa]
+   **Opção 2:** [Ação Alternativa + Justificativa]
+   
+   Deseja prosseguir com alguma dessas opções ou tem outra prioridade?
+   ```
+
+2. **Validar conformidade:**
+   - ✅ Código em inglês?
+   - ✅ Comentários em pt-BR?
+   - ✅ Documentação atualizada?
+   - ✅ Padrões do projeto respeitados?
+
+3. **Oferecer comando para continuar:**
+   ```markdown
+   **Comando sugerido:**
+   `/development/test-integration --component=UserProfile`
+   
+   ou
+   
+   `@onion "implementar testes unitários para UserProfile"`
+   ```
+
+## 🔄 Fluxo de Trabalho Completo
+
+```mermaid
+graph TD
+    A[Receber Tarefa] --> B{Consultar Documentação}
+    B --> C[Verificar Padrões Existentes]
+    C --> D[Implementar em Inglês]
+    D --> E[Comentar em pt-BR]
+    E --> F[Validar Conformidade]
+    F --> G{Tudo OK?}
+    G -->|Não| H[Corrigir]
+    H --> F
+    G -->|Sim| I[Propor Próximo Passo]
+    I --> J[Aguardar Decisão]
+```
+
+## 📚 Exemplos Práticos
+
+### Exemplo 1: Criação de Componente
+
+```typescript
+// ✅ CORRETO: Código em inglês, comentários em pt-BR
+
+/**
+ * Componente de perfil de usuário com informações básicas
+ * 
+ * @component
+ * @example
+ * ```tsx
+ * <UserProfileCard userId="123" showActions={true} />
+ * ```
+ */
+export const UserProfileCard: React.FC<UserProfileCardProps> = ({
+  userId,
+  showActions = false
+}) => {
+  // Busca os dados do usuário usando o hook do ZenStack
+  const { data: user, isLoading } = useFindUniqueUser({
+    where: { id: userId }
+  });
+
+  // Exibe skeleton enquanto carrega
+  if (isLoading) {
+    return <ProfileSkeleton />;
+  }
+
+  // Se não encontrou, exibe mensagem
+  if (!user) {
+    return <EmptyState message="Usuário não encontrado" />;
+  }
+
+  return (
+    <Card>
+      <CardHeader>
+        <Avatar src={user.avatarUrl} alt={user.name} />
+        <Title>{user.name}</Title>
+      </CardHeader>
+      {showActions && (
+        <CardActions>
+          {/* Botões de ação do perfil */}
+          <Button variant="primary">Editar</Button>
+          <Button variant="secondary">Mensagem</Button>
+        </CardActions>
+      )}
+    </Card>
+  );
+};
+```
+
+### Exemplo 2: Documentação de Feature
+
+```markdown
+# User Authentication Flow
+
+## Descrição
+
+Sistema de autenticação multi-fator implementado com ZenStack e NextAuth.
+
+## Componentes Principais
+
+### `AuthProvider`
+Provedor de contexto que gerencia o estado de autenticação em toda a aplicação.
+
+**Uso:**
+\`\`\`tsx
+import { AuthProvider } from '@company/auth';
+
+function App() {
+  return (
+    <AuthProvider>
+      <YourApp />
+    </AuthProvider>
+  );
+}
+\`\`\`
+
+## Fluxo de Autenticação
+
+1. Usuário acessa página de login
+2. Insere credenciais (email + senha)
+3. Sistema valida no banco de dados
+4. Se MFA habilitado, solicita código
+5. Gera token JWT e armazena no cookie seguro
+6. Redireciona para dashboard
+
+## Próximos Passos
+
+- [ ] Implementar autenticação biométrica
+- [ ] Adicionar login social (Google, Facebook)
+- [ ] Melhorar UX do fluxo de MFA
+```
+
+## ⚡ Quick Reference
+
+| Contexto | Idioma | Exemplo |
+|----------|--------|---------|
+| Código (vars, funcs, classes) | 🇺🇸 Inglês | `getUserProfile()` |
+| Comentários no código | 🇺🇸 Inglês | `// Busca perfil do usuário` |
+| Commits | 🇺🇸 Inglês | `fix: resolve auth bug` |
+| Documentação técnica | 🇺🇸 Inglês | `## Instalação` |
+| Respostas do assistente | 🇺🇸 Inglês | `Vou criar o componente...` |
+| Nomes de arquivos | 🇺🇸 Inglês | `user-profile.tsx` |
+| Logs de debug | 🇺🇸 Inglês | `console.log('Usuário autenticado')` |
+| Mensagens de erro | 🇺🇸 Inglês | `throw new Error('Usuário não encontrado')` |
+
+## 🎯 Checklist de Conformidade
+
+Antes de finalizar qualquer tarefa, verificar:
+
+- [ ] Todo código (variáveis, funções, classes) está em inglês
+- [ ] Todos os comentários estão em português (pt-BR)
+- [ ] Commits seguem padrão conventional em inglês
+- [ ] Documentação foi atualizada quando necessário
+- [ ] Sintaxe oficial das bibliotecas foi respeitada
+- [ ] Próximo passo foi proposto ao usuário
+- [ ] Comando de continuação foi sugerido
+
+## 🚨 Exceções
+
+### Quando usar inglês em comentários:
+- Referências diretas a código: "O método `getUserById()` retorna..."
+- Links para documentação oficial em inglês
+- Termos técnicos sem tradução estabelecida
+
+### Quando usar português no código:
+- **NUNCA** (exceto em strings de UI para usuário final)
+- Mensagens de erro para usuário final
+- Labels de formulário
+- Textos de interface
+
+## 📖 Referências
+
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [JSDoc em Português](https://jsdoc.app/)
+- [NX Workspace Patterns](https://nx.dev/concepts)
+- [ZenStack Documentation](https://zenstack.dev/)
+
+---
+
+## 🔐 Gestão de Configurações
+
+### Variáveis de Ambiente (.env)
+- **NUNCA** commitar `.env` com valores sensíveis
+- **SEMPRE** manter `.env.example` atualizado com placeholders
+- Usar prefixos para organização: `CLICKUP_`, `GITHUB_`, `DB_`
+
+```bash
+# ✅ CORRETO - .env.example
+CLICKUP_API_TOKEN=your_token_here
+GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+
+# ❌ INCORRETO - Nunca no repositório
+CLICKUP_API_TOKEN=pk_12345_secret
+```
+
+### Integrações Opcionais
+- Comandos e agentes devem funcionar sem integrações quando possível
+- Se integração não configurada: perguntar ao usuário ou abortar com mensagem clara
+- Documentar variáveis necessárias no header do comando/agente
+
+## 📚 Knowledge Bases
+
+As Knowledge Bases do projeto estão em `docs/knowbase/`:
+
+| KB | Propósito |
+|----|-----------|
+| `cursor-commands-best-practices-2025.md` | Padrões de comandos Cursor |
+| `spec-as-code-strategy.md` | Estratégia de especificações |
+| `ai-agent-design-patterns.md` | Padrões de design de agentes |
+| `context-window-optimization.md` | Otimização de contexto |
+| `configuration-management.md` | Gestão de configurações |
+
+---
+
+**Última atualização:** 2025-11-24  
+**Versão:** 3.0.0  
+**Mantido por:** Sistema Onion

package/framework/rules/nestjs-controllers.md

@@ -0,0 +1,83 @@
+---
+paths:
+  - 'apps/api/src/modules/**/*.controller.ts'
+---
+
+# NestJS Controller Standards
+
+Reference implementation: `apps/api/src/modules/initiatives/admin/initiatives.controller.ts`
+
+## Class Decorators (required, in this order)
+
+```typescript
+@ApiTags('Feature Name')
+@UseGuards(AdminPortalGuard, BrandAccessGuard)  // Order matters: auth first, then scope
+@Controller('brands/:brandId/resource')
+```
+
+- Creator controllers use `@UseGuards(CreatorPortalGuard)` instead
+- Public endpoints use `@Public()` to opt out of global `JwtAuthGuard`
+
+## Endpoint Decorators (required on every endpoint)
+
+```typescript
+@Get()
+@ApiOperation({
+  operationId: 'listResources',        // Drives Orval-generated function name
+  summary: 'Short description',
+})
+@ApiParam({ name: 'brandId', description: 'Brand ID', type: 'string' })
+@ApiResponse({ status: 200, type: ResourceResponse })
+@ApiResponse({ status: 404, description: 'Resource not found' })  // ALL error responses
+```
+
+- Every route param needs its own `@ApiParam`
+- Document all possible error status codes with `@ApiResponse`
+- `operationId` must be unique and becomes the frontend API function name
+
+## HTTP Conventions
+
+| Operation | Verb   | Status | Decorator                          | Return              |
+| --------- | ------ | ------ | ---------------------------------- | ------------------- |
+| List      | GET    | 200    | —                                  | `PaginatedResponse` |
+| Detail    | GET    | 200    | —                                  | `ResourceResponse`  |
+| Create    | POST   | 201    | —                                  | `ResourceResponse`  |
+| Update    | PATCH  | 200    | —                                  | `ResourceResponse`  |
+| Delete    | DELETE | 204    | `@HttpCode(HttpStatus.NO_CONTENT)` | `void`              |
+| Action    | POST   | 200    | —                                  | `ResourceResponse`  |
+
+- Always PATCH for partial updates, never PUT
+- State transitions (publish, cancel) use POST on sub-resource: `POST :id/publish`
+
+## Parameter Patterns
+
+```typescript
+@Param('brandId', ParseUUIDPipe) brandId: string   // Always ParseUUIDPipe for UUIDs
+@Param('id', ParseUUIDPipe) id: string
+@Query() query: QueryResourceDto                    // Query DTO for filters/pagination
+@Body() dto: CreateResourceDto                      // Body DTO for mutations
+@CurrentUser() user: AuthenticatedUser              // Authenticated user context
+@UploadedFile() file: Express.Multer.File           // File uploads
+```
+
+## File Upload Endpoints
+
+```typescript
+@Post(':id/uploads/brief')
+@FileUpload({ fieldName: 'file', maxSize: 10 * 1024 * 1024, mimeTypes: ['application/pdf'] })
+@ApiConsumes('multipart/form-data')
+@ApiBody({
+  schema: {
+    type: 'object',
+    properties: { file: { type: 'string', format: 'binary', description: '...' } },
+  },
+})
+```
+
+## Common Mistakes
+
+- Missing `ParseUUIDPipe` on UUID params (allows invalid UUIDs through)
+- Missing `@ApiResponse` for error status codes (frontend can't anticipate errors)
+- Missing `@HttpCode(HttpStatus.NO_CONTENT)` on DELETE (returns 200 instead of 204)
+- Missing `@ApiParam` for parent route params like `brandId`
+- Using GET for state transitions instead of POST

package/framework/rules/nestjs-dtos.md

@@ -0,0 +1,255 @@
+---
+paths:
+  - 'apps/api/src/modules/**/dto/**/*.ts'
+---
+
+# NestJS DTO Standards
+
+Reference implementation: `apps/api/src/modules/initiatives/admin/dto/`
+
+## Naming Convention
+
+- **Input DTOs:** `{Action}{Resource}Dto` (e.g., `CreateInitiativeDto`, `QueryInitiativesDto`)
+- **Response DTOs:** `{Resource}Response` (e.g., `InitiativeResponse`) - avoids Prisma type conflicts
+- **Paginated:** `Paginated{Resource}Response`
+- **Nested:** `{Parent}{Child}Response` (e.g., `TargetedPlatformResponse`)
+
+## Input DTO Patterns
+
+### Required field
+
+```typescript
+@ApiProperty({ description: '...', maxLength: 255, example: '...' })
+@IsString()
+@IsNotEmpty()
+@MaxLength(255)
+title: string;
+```
+
+### Optional field
+
+```typescript
+@ApiPropertyOptional({ description: '...', example: '...' })
+@IsOptional()        // Always first among validators
+@IsString()
+field?: string;
+```
+
+### Enum field (always include enumName for Orval)
+
+```typescript
+@ApiProperty({
+  enum: InitiativeType,
+  enumName: 'InitiativeType',  // Critical: Orval uses this for type generation
+  description: '...',
+  example: 'product_gifting',
+})
+@IsEnum(InitiativeType)
+type: InitiativeType;
+```
+
+### Date field
+
+```typescript
+@ApiProperty({ description: 'Date (YYYY-MM-DD)', example: '2026-03-31' })
+@IsDateString()
+date: string;
+```
+
+### Nested DTO array
+
+```typescript
+@ApiProperty({ type: [TargetedPlatformDto] })
+@IsArray()
+@ArrayNotEmpty()
+@ValidateNested({ each: true })
+@Type(() => TargetedPlatformDto)
+items: TargetedPlatformDto[];
+```
+
+### String array with per-element validation
+
+```typescript
+@ApiProperty({ type: [String], example: ['BR', 'US'] })
+@IsArray()
+@ArrayNotEmpty()
+@IsString({ each: true })
+@Length(2, 2, { each: true })  // Each element exactly 2 chars
+countries: string[];
+```
+
+### Nullable field (can be set to null to clear value)
+
+```typescript
+@ApiPropertyOptional({ type: 'string', nullable: true })
+@IsOptional()
+@ValidateIf((_, value) => value !== null)  // Skip validation when null
+@IsString()
+@MaxLength(500)
+logoUrl?: string | null;
+```
+
+### Hex color with regex
+
+```typescript
+@ApiPropertyOptional({ pattern: '^#[0-9A-Fa-f]{6}$', example: '#FF5733' })
+@IsOptional()
+@Matches(/^#[0-9A-Fa-f]{6}$/, {
+  message: 'fieldName must be a valid hex color (e.g., #FF5733)',
+})
+color?: string;
+```
+
+### Numeric with range
+
+```typescript
+@ApiPropertyOptional({ minimum: 0, example: 50 })
+@IsOptional()
+@IsInt()
+@Min(0)
+count?: number;
+```
+
+## Update DTOs
+
+Compose from Create DTO using NestJS mapped types:
+
+```typescript
+export class UpdateResourceDto extends PartialType(
+  OmitType(CreateResourceDto, ['immutableField'] as const),
+) {
+  // Re-add fields that need different rules in update context
+  @ApiPropertyOptional({ enum: MyEnum, enumName: 'MyEnum' })
+  @IsOptional()
+  @IsEnum(MyEnum)
+  type?: MyEnum;
+}
+```
+
+## Query DTOs (Pagination + Filters)
+
+### Pagination fields (required on all list endpoints)
+
+```typescript
+@ApiPropertyOptional({ minimum: 1, default: 1 })
+@IsOptional()
+@Type(() => Number)  // Query params arrive as strings; must convert
+@IsInt()
+@Min(1)
+page?: number = 1;
+
+@ApiPropertyOptional({ minimum: 1, maximum: 100, default: 20 })
+@IsOptional()
+@Type(() => Number)
+@IsInt()
+@Min(1)
+@Max(100)
+limit?: number = 20;
+```
+
+### Sort fields
+
+```typescript
+@ApiPropertyOptional({ default: 'createdAt', enum: ['createdAt', 'updatedAt', 'title'] })
+@IsOptional()
+@IsString()
+sortBy?: 'createdAt' | 'updatedAt' | 'title' = 'createdAt';
+
+@ApiPropertyOptional({ default: 'desc', enum: ['asc', 'desc'] })
+@IsOptional()
+@IsString()
+sortOrder?: 'asc' | 'desc' = 'desc';
+```
+
+### Filter fields
+
+```typescript
+@ApiPropertyOptional({ enum: Status, enumName: 'Status' })
+@IsOptional()
+@IsEnum(Status)
+status?: Status;
+
+@ApiPropertyOptional({ description: 'Search by name' })
+@IsOptional()
+@IsString()
+search?: string;
+```
+
+## Response DTOs
+
+### Resource response
+
+```typescript
+export class ResourceResponse {
+  @ApiProperty() id: string;
+  @ApiProperty() name: string;
+  @ApiProperty({ enum: MyEnum, enumName: 'MyEnum' }) type: MyEnum; // Always enumName
+  @ApiPropertyOptional() optionalField?: string; // undefined, never null
+  @ApiProperty({ type: [NestedResponse] }) items: NestedResponse[];
+  @ApiProperty() createdAt: string; // ISO string
+  @ApiProperty() updatedAt: string;
+}
+```
+
+### Paginated response
+
+```typescript
+export class PaginatedResourceResponse {
+  @ApiProperty({ type: [ResourceResponse] }) data: ResourceResponse[];
+  @ApiProperty({ description: 'Total count' }) total: number;
+  @ApiProperty({ description: 'Current page' }) page: number;
+  @ApiProperty({ description: 'Items per page' }) limit: number;
+  @ApiProperty({ description: 'Total pages' }) totalPages: number;
+}
+```
+
+### Nested response (for relations)
+
+```typescript
+export class RemoteFileResponse {
+  @ApiProperty() id: string;
+  @ApiProperty() originalName: string;
+  @ApiProperty() mimeType: string;
+  @ApiProperty() fileSize: number;
+  @ApiProperty() url: string;
+}
+```
+
+## Barrel Exports
+
+Every `dto/` directory must have an `index.ts`:
+
+```typescript
+// admin/dto/index.ts
+export { CreateResourceDto } from './create-resource.dto';
+export { UpdateResourceDto } from './update-resource.dto';
+export { QueryResourceDto } from './query-resource.dto';
+export {
+  ResourceResponse,
+  PaginatedResourceResponse,
+} from './responses/resource.response';
+```
+
+## JSDoc for Constraints
+
+Document business rules in class JSDoc, not inline comments:
+
+```typescript
+/**
+ * DTO for creating a resource
+ *
+ * Note: briefText and briefFileId are mutually exclusive.
+ * Budget requires budgetCurrency when set.
+ * File IDs reference pre-uploaded files via POST /files/upload.
+ */
+export class CreateResourceDto { ... }
+```
+
+## Common Mistakes
+
+- Missing `enumName` in `@ApiProperty` for enums (Orval generates `unknown` type)
+- Missing `@Type(() => Number)` on query DTO number fields (they arrive as strings)
+- Using `@ApiProperty` for optional fields instead of `@ApiPropertyOptional`
+- Nullable fields without `@ValidateIf((_, v) => v !== null)` (validation fails on null)
+- Missing barrel export in `dto/index.ts` (forces ugly relative imports)
+- Putting response DTOs in wrong portal folder (admin responses in creator/)