@polymorphism-tech/morph-spec 1.0.4 → 2.1.0

package/content/.morph/templates/ui-flows.md

@@ -0,0 +1,336 @@
+# UI Flows - {{FEATURE_NAME_TITLE}}
+
+> Fluxos de usuário completos mostrando navegação, decisões e edge cases.
+> Documenta COMO o usuário se move pela feature do início ao fim.
+
+---
+
+## Fluxo 1: {Nome do Fluxo Principal}
+
+### Contexto
+
+**Trigger (Gatilho):**
+{O que inicia este fluxo? Ex: "Usuário clica em [+ Novo Pedido]"}
+
+**Pré-condições:**
+- {Condição 1 que deve ser verdadeira para iniciar o fluxo}
+- {Condição 2}
+
+**Objetivo:**
+{O que o usuário quer alcançar ao final deste fluxo?}
+
+---
+
+### Happy Path (Caminho Ideal)
+
+#### Passos
+
+**1. {Tela/Componente Inicial}**: {Ação do usuário}
+   - Sistema: {Resposta do sistema}
+   - UI: {Mudança visual}
+   - Navegação: {Para onde vai}
+
+**2. {Próxima Tela/Componente}**: {Próxima ação}
+   - Sistema: {Processamento backend}
+   - UI: {Feedback visual}
+   - Validação: {Regras aplicadas}
+
+**3. {Tela/Componente Final}**: {Ação de conclusão}
+   - Sistema: {Persistência/salvamento}
+   - UI: {Mensagem de sucesso}
+   - Navegação: {Retorna para onde}
+
+**Tempo estimado:** {X segundos/minutos para usuário completar}
+
+---
+
+### Diagrama de Fluxo (Happy Path)
+
+```
+┌─────────────────┐
+│  Tela Inicial   │
+│  [Dashboard]    │
+└────────┬────────┘
+         │
+         │ Clica [+ Novo Pedido]
+         ▼
+┌─────────────────┐
+│   Modal/Wizard  │
+│   Aberto        │
+└────────┬────────┘
+         │
+         │ ⟨Step 1⟩ Seleciona Cliente
+         ▼
+┌─────────────────┐
+│  Cliente        │
+│  Selecionado    │
+└────────┬────────┘
+         │
+         │ Clica [Próximo]
+         ▼
+┌─────────────────┐
+│  ⟨Step 2⟩       │
+│  Produtos       │
+└────────┬────────┘
+         │
+         │ Adiciona Produtos
+         │ Total Calculado
+         ▼
+┌─────────────────┐
+│  Lista de       │
+│  Produtos OK    │
+└────────┬────────┘
+         │
+         │ Clica [Próximo]
+         ▼
+┌─────────────────┐
+│  ⟨Step 3⟩       │
+│  Revisão        │
+└────────┬────────┘
+         │
+         │ Clica [Confirmar]
+         ▼
+┌─────────────────┐
+│  ✅ Pedido      │
+│  Criado!        │
+└────────┬────────┘
+         │
+         │ Toast "Sucesso!"
+         │ Navega para Detalhes
+         ▼
+┌─────────────────┐
+│  Tela Detalhes  │
+│  Pedido #12345  │
+└─────────────────┘
+```
+
+---
+
+### Edge Cases (Casos de Exceção)
+
+#### 1. {Nome do Edge Case}
+
+**Cenário:**
+{Descrição da situação excepcional}
+
+**Como o sistema lida:**
+```
+┌─────────────────┐
+│  Passo Normal   │
+└────────┬────────┘
+         │
+         │ ❌ {Erro/Condição}
+         ▼
+┌─────────────────┐
+│  Mensagem Erro  │
+│  FluentDialog   │
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    │         │
+    ▼         ▼
+[Tentar]  [Cancelar]
+Novamente
+    │         │
+    │         └──▶ [Volta Dashboard]
+    │
+    └──▶ [Repete Passo]
+```
+
+**UI:**
+- Componente: {FluentDialog, FluentMessageBar, etc}
+- Mensagem: "{Texto exato da mensagem}"
+- Ações disponíveis: {Botões/links}
+
+**Exemplo de código:**
+```razor
+@if (!string.IsNullOrEmpty(_error))
+{
+    <FluentMessageBar Intent="MessageIntent.Error">
+        @_error
+        <FluentButton OnClick="@Retry">Tentar Novamente</FluentButton>
+    </FluentMessageBar>
+}
+```
+
+---
+
+#### 2. {Outro Edge Case}
+
+{Repita a estrutura acima}
+
+---
+
+### Fluxos Alternativos
+
+#### Alt 1: {Nome do Fluxo Alternativo}
+
+**Diverge em:** {Em qual passo do happy path este fluxo se ramifica}
+
+**Condição:** {O que causa a divergência}
+
+**Passos:**
+1. {Passo alternativo 1}
+2. {Passo alternativo 2}
+3. {Convergência de volta ao happy path OU conclusão diferente}
+
+**Diagrama:**
+```
+[Happy Path]
+     │
+     ├─{Condição}──▶ [Fluxo Alt]
+     │                    │
+     │                    └──▶ [Converge]
+     ▼
+[Continua...]
+```
+
+---
+
+## Fluxo 2: {Segundo Fluxo Importante}
+
+{Repita toda a estrutura acima para cada fluxo principal}
+
+---
+
+## Interações Comuns (Micro-Fluxos)
+
+### {Ação Rápida - Ex: "Buscar Item"}
+
+**Trigger:** {Usuário digita na search bar}
+
+**Fluxo:**
+```
+[Input vazio] ──▶ [Usuário digita] ──▶ [Debounce 300ms] ──▶ [API Call]
+                                                                  │
+                                                                  ▼
+                                                            [Resultados]
+                                                                  │
+                                                    ┌─────────────┴──────────┐
+                                                    ▼                        ▼
+                                             [Tem Resultados]         [Vazio]
+                                                    │                        │
+                                                    ▼                        ▼
+                                             [Mostra Lista]    [Mostra "Não encontrado"]
+```
+
+**Componente:** `FluentAutocomplete`
+
+**Código:**
+```razor
+<FluentAutocomplete TItem="Item"
+                   SearchAsync="@SearchItemsAsync"
+                   Placeholder="Buscar item..."
+                   MinLength="2"
+                   Debounce="300">
+    <ItemTemplate Context="item">
+        @item.Name
+    </ItemTemplate>
+</FluentAutocomplete>
+```
+
+---
+
+## Mapa de Navegação Completo
+
+Visão geral de TODAS as telas e como se conectam:
+
+```
+                    ┌──────────────┐
+                    │  Dashboard   │
+                    └──────┬───────┘
+                           │
+         ┌─────────────────┼─────────────────┐
+         │                 │                 │
+         ▼                 ▼                 ▼
+   ┌─────────┐      ┌──────────┐      ┌─────────┐
+   │ Pedidos │      │ Clientes │      │Produtos │
+   └────┬────┘      └────┬─────┘      └────┬────┘
+        │                │                   │
+        ▼                ▼                   ▼
+   [+ Novo]         [+ Novo]           [+ Novo]
+        │                │                   │
+        └────────────────┴──────────────────┬┘
+                                            │
+                                            ▼
+                                    ┌───────────────┐
+                                    │ Modal Wizard  │
+                                    │ (3 steps)     │
+                                    └───────┬───────┘
+                                            │
+                                            ▼
+                                      [Confirmar]
+                                            │
+                                            ▼
+                                    ┌───────────────┐
+                                    │ Tela Detalhes │
+                                    └───────┬───────┘
+                                            │
+                                    ┌───────┴───────┐
+                                    │               │
+                                    ▼               ▼
+                              [Editar]        [Voltar]
+                                    │               │
+                                    └───────┬───────┘
+                                            │
+                                            ▼
+                                    [Dashboard]
+```
+
+---
+
+## Estados de Loading
+
+### {Onde há loading na feature}
+
+**1. Carregamento Inicial:**
+- **Onde:** {Primeira tela ao abrir}
+- **Componente:** `FluentSkeleton` ou `FluentProgress`
+- **Duração esperada:** {X ms}
+
+**2. Carregamento de Ação:**
+- **Onde:** {Ao submeter form, por exemplo}
+- **Componente:** `FluentButton` com `Loading="true"`
+- **Duração esperada:** {X ms}
+
+**3. Carregamento Incremental:**
+- **Onde:** {Infinite scroll, paginação}
+- **Componente:** `FluentProgress` no rodapé
+- **Duração esperada:** {X ms}
+
+---
+
+## Validações e Feedback
+
+### Validações Client-Side
+
+| Campo | Validação | Mensagem de Erro | Componente |
+|-------|-----------|------------------|------------|
+| {Nome} | Required | "Campo obrigatório" | FluentTextField |
+| {Email} | Email format | "Email inválido" | FluentTextField |
+| {CPF} | CPF válido | "CPF inválido" | FluentTextField |
+
+### Validações Server-Side
+
+| Ação | Validação | Erro Possível | Como Mostra |
+|------|-----------|---------------|-------------|
+| Criar Pedido | Cliente ativo | "Cliente inativo" | FluentMessageBar |
+| Adicionar Produto | Estoque > 0 | "Sem estoque" | FluentDialog |
+
+---
+
+## Checklist de Fluxos
+
+- [ ] Happy path documentado com todos os passos
+- [ ] Diagramas ASCII de cada fluxo
+- [ ] Edge cases identificados (erro, vazio, retry)
+- [ ] Fluxos alternativos mapeados
+- [ ] Loading states especificados
+- [ ] Validações client-side e server-side listadas
+- [ ] Mensagens de erro/sucesso definidas
+- [ ] Navegação entre telas clara
+- [ ] Tempo estimado de cada fluxo
+
+---
+
+*Template MORPH-SPEC v2.1.0 by Polymorphism Tech*

package/content/.morph/templates/ui-mockups.md

@@ -0,0 +1,133 @@
+# UI Mockups - {{FEATURE_NAME_TITLE}}
+
+> Wireframes ASCII e descrições de cada tela/componente da feature.
+> Este arquivo documenta VISUALMENTE como o usuário interagirá com o sistema.
+> Generated: {{DATE}}
+
+---
+
+## Tela 1: {Nome da Tela}
+
+### Wireframe
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  [{≡}] {Título da Página}           [🔔] [👤] [⚙]      │
+├─────────────────────────────────────────────────────────┤
+│                                                          │
+│  {Desenhe o wireframe ASCII aqui}                       │
+│                                                          │
+│  Dicas:                                                  │
+│  - Use ┌─┐└┘├┤ para bordas                             │
+│  - Use │ para separadores verticais                     │
+│  - Use ─ para separadores horizontais                   │
+│  - Use [...] para botões                                │
+│  - Use [{x}] para checkboxes/toggles                    │
+│  - Use emojis para ícones (🔍 📊 ⚙ 👤 etc)           │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Descrição
+
+- **Propósito**: {O que o usuário pode fazer nesta tela? Qual problema resolve?}
+- **Componentes Principais**:
+  - {Componente 1}: {Descrição breve}
+  - {Componente 2}: {Descrição breve}
+  - {Componente 3}: {Descrição breve}
+- **Interações**:
+  - **Click em {elemento}**: {O que acontece}
+  - **Hover em {elemento}**: {Feedback visual}
+  - **Submit form**: {Ação realizada}
+- **Estados**:
+  - **Default**: {Aparência inicial}
+  - **Loading**: {Como mostra carregamento? Skeleton? Spinner?}
+  - **Error**: {Como mostra erros? Toast? Message bar?}
+  - **Empty**: {Mensagem quando não há dados? CTA para criar?}
+  - **Success**: {Feedback de sucesso?}
+
+### Responsividade
+
+- **Desktop (> 1024px)**: {Descrição do layout desktop}
+- **Tablet (768px - 1024px)**: {Mudanças no layout}
+- **Mobile (< 768px)**: {Layout mobile - stack vertical? Menu hamburger?}
+
+### Navegação
+
+- **De**: {Tela/componente anterior}
+- **Para**: {Próximas telas possíveis}
+- **Ações**:
+  - [{Botão}]: Navega para {tela}
+  - [{Link}]: Abre {modal/página}
+
+### Acessibilidade
+
+- **Foco inicial**: {Onde o cursor deve iniciar?}
+- **Tab order**: {Ordem lógica de navegação}
+- **Screen reader**: {Principais ARIA labels}
+
+---
+
+## Tela 2: {Nome da Próxima Tela}
+
+{Repita a estrutura acima para cada tela}
+
+---
+
+## Componentes Reutilizáveis
+
+### {Nome do Componente}
+
+**Wireframe:**
+```
+{ASCII art do componente isolado}
+```
+
+**Uso:**
+- Aparece em: {Lista de telas onde este componente aparece}
+- Variantes: {Diferentes versões/estados do componente}
+- Props: {Parâmetros que o componente recebe}
+
+---
+
+## Fluxo de Navegação (Overview)
+
+```
+[Tela Inicial]
+     │
+     ├─[Ação 1]──▶ [Tela A]
+     │                  │
+     │                  └─[Voltar]──▶ [Tela Inicial]
+     │
+     ├─[Ação 2]──▶ [Tela B]
+     │                  │
+     │                  ├─[Próximo]──▶ [Tela C]
+     │                  │
+     │                  └─[Cancelar]──▶ [Tela Inicial]
+     │
+     └─[Ação 3]──▶ [Tela D]
+```
+
+---
+
+## Notas de Design
+
+### Paleta de Cores
+- **Primária**: {Cor principal da interface}
+- **Secundária**: {Cor para ações secundárias}
+- **Sucesso**: {Verde para feedback positivo}
+- **Erro**: {Vermelho para erros}
+- **Warning**: {Amarelo para alertas}
+
+### Tipografia
+- **Títulos**: {Font, tamanho}
+- **Corpo**: {Font, tamanho}
+- **Labels**: {Font, tamanho}
+
+### Espaçamento
+- **Padding padrão**: {16px, 24px, etc}
+- **Gap entre elementos**: {8px, 12px, etc}
+
+---
+
+*Template MORPH-SPEC v2.1.0 by Polymorphism Tech*

package/content/.morph/test-infra/example.bicep

@@ -0,0 +1,59 @@
+// Example Bicep file for testing cost calculator
+
+param location string = 'eastus2'
+param environment string = 'dev'
+
+// Azure SQL Database - Basic tier ($4.99/month)
+resource sqlDatabase 'Microsoft.Sql/servers/databases@2023-05-01-preview' = {
+  name: 'sqldb-myapp-${environment}'
+  location: location
+  sku: {
+    name: 'Basic'
+    tier: 'Basic'
+  }
+  properties: {
+    collation: 'SQL_Latin1_General_CP1_CI_AS'
+    maxSizeBytes: 2147483648 // 2 GB
+  }
+}
+
+// Container App - Scale-to-zero ($0/month)
+resource containerApp 'Microsoft.App/containerApps@2023-05-01' = {
+  name: 'ca-myapp-${environment}'
+  location: location
+  properties: {
+    configuration: {
+      ingress: {
+        external: true
+        targetPort: 8080
+      }
+    }
+    template: {
+      containers: [
+        {
+          name: 'main'
+          image: 'mcr.microsoft.com/azuredocs/containerapps-helloworld:latest'
+        }
+      ]
+      scale: {
+        minReplicas: 0  // Scale-to-zero = FREE
+        maxReplicas: 2
+      }
+    }
+  }
+}
+
+// Application Insights - Free tier ($0/month)
+resource appInsights 'Microsoft.Insights/components@2020-02-02' = {
+  name: 'appi-myapp-${environment}'
+  location: location
+  kind: 'web'
+  properties: {
+    Application_Type: 'web'
+  }
+  sku: {
+    name: 'Free'
+  }
+}
+
+// Total: $4.99/month (within $10 limit)

package/content/CLAUDE.md

@@ -255,6 +255,130 @@ infra/
 
 ---
 
+## TEMPLATES E PLACEHOLDERS
+
+### Princípio: Templates Auto-Populáveis
+
+> SEMPRE use o CLI `bin/render-template.js` para renderizar templates. NUNCA preencha placeholders manualmente.
+
+### Placeholders Padrão
+
+Todos os templates usam o formato `{{PLACEHOLDER}}` (duplo-chave). Os placeholders são substituídos automaticamente pelo CLI.
+
+| Placeholder | Descrição | Exemplo Input | Exemplo Output |
+|-------------|-----------|---------------|----------------|
+| `{{FEATURE_NAME}}` | Nome kebab-case da feature | `"scheduled-reports"` | `scheduled-reports` |
+| `{{FEATURE_NAME_PASCAL}}` | PascalCase (para C#) | `"scheduled-reports"` | `ScheduledReports` |
+| `{{FEATURE_NAME_CAMEL}}` | camelCase (para JS/TS) | `"scheduled-reports"` | `scheduledReports` |
+| `{{FEATURE_NAME_TITLE}}` | Title Case (para títulos) | `"scheduled-reports"` | `Scheduled Reports` |
+| `{{FEATURE_NAME_UPPER_SNAKE}}` | UPPER_SNAKE_CASE | `"scheduled-reports"` | `SCHEDULED_REPORTS` |
+| `{{FEATURE_NAME_LOWER_SNAKE}}` | lower_snake_case | `"scheduled-reports"` | `scheduled_reports` |
+| `{{STACK}}` | Stack do projeto | (auto) | `Blazor`, `Next.js` |
+| `{{DATE}}` | Data atual (YYYY-MM-DD) | (auto) | `2025-12-08` |
+| `{{YEAR}}` | Ano atual | (auto) | `2025` |
+| `{{AUTHOR}}` | Autor (de config.json) | (auto) | `MORPH-SPEC` |
+| `{{PROJECT_NAME}}` | Nome do projeto | (auto) | `MyProject` |
+| `{{NAMESPACE}}` | Namespace C# | (auto) | `MyProject` |
+
+**Transformações Automáticas:**
+- Forneça apenas `FEATURE_NAME` em kebab-case (ex: `"my-feature"`)
+- CLI gera automaticamente todas as variações de case
+- Valores auto-populados (DATE, AUTHOR, etc.) vêm de `config.json`
+
+### CLI de Renderização
+
+#### Uso Básico
+
+```bash
+node bin/render-template.js <template-path> <output-path> <variables-json>
+```
+
+#### Exemplos
+
+**Renderizar proposal.md:**
+```bash
+node bin/render-template.js \
+  content/.morph/templates/proposal.md \
+  .morph/project/outputs/scheduled-reports/proposal.md \
+  '{"FEATURE_NAME":"scheduled-reports"}'
+```
+
+**Renderizar contracts.cs com namespace customizado:**
+```bash
+node bin/render-template.js \
+  content/.morph/templates/contracts.cs \
+  src/Application/Features/ScheduledReports/Contracts.cs \
+  '{"FEATURE_NAME":"scheduled-report","NAMESPACE":"MyProject"}'
+```
+
+**Modo verbose (mostra placeholders substituídos):**
+```bash
+node bin/render-template.js \
+  content/.morph/templates/spec.md \
+  .morph/project/outputs/my-feature/spec.md \
+  '{"FEATURE_NAME":"my-feature","STACK":"Blazor"}' \
+  --verbose
+```
+
+**Dry-run (preview sem escrever arquivo):**
+```bash
+node bin/render-template.js \
+  content/.morph/templates/ui-mockups.md \
+  /dev/null \
+  '{"FEATURE_NAME":"user-dashboard"}' \
+  --dry-run
+```
+
+#### Flags Disponíveis
+
+| Flag | Descrição |
+|------|-----------|
+| `--verbose`, `-v` | Mostra placeholders substituídos e não-substituídos |
+| `--dry-run`, `-d` | Preview sem escrever arquivo |
+| `--help`, `-h` | Mostra ajuda completa |
+
+### Templates Disponíveis
+
+**Outputs MORPH:**
+- `.morph/templates/proposal.md` - FASE 0 (Proposal)
+- `.morph/templates/ui-design-system.md` - FASE 1.5 (Design System)
+- `.morph/templates/ui-mockups.md` - FASE 1.5 (Wireframes)
+- `.morph/templates/ui-components.md` - FASE 1.5 (Component Specs)
+- `.morph/templates/ui-flows.md` - FASE 1.5 (User Flows)
+- `.morph/templates/spec.md` - FASE 2 (Technical Spec)
+- `.morph/templates/contracts.cs` - FASE 2 (Interfaces/DTOs)
+- `.morph/templates/decisions.md` - FASE 2 (ADRs)
+- `.morph/templates/tasks.md` - FASE 4 (Task Breakdown)
+- `.morph/templates/recap.md` - FASE 5 (Recap)
+
+**Templates de Código:**
+- `.morph/templates/service.cs` - Service implementation
+- `.morph/templates/repository.cs` - Repository implementation
+- `.morph/templates/agent.cs` - AI Agent (Microsoft Agent Framework)
+- `.morph/templates/job.cs` - Hangfire background job
+- `.morph/templates/test.cs` - Unit test template
+
+### Integração com Slash Commands
+
+Os slash commands **devem usar o CLI de renderização** para gerar outputs:
+
+```markdown
+# Em morph-proposal.md
+
+node bin/render-template.js \
+  content/.morph/templates/proposal.md \
+  .morph/project/outputs/${FEATURE_NAME}/proposal.md \
+  "{\"FEATURE_NAME\":\"${FEATURE_NAME}\"}"
+```
+
+**Benefícios:**
+- ✅ **Consistência:** Todos os outputs seguem o mesmo formato
+- ✅ **Economia de tokens:** Claude não precisa preencher manualmente
+- ✅ **Zero erros:** Transformações de case são 100% corretas
+- ✅ **Rapidez:** CLI processa em <100ms
+
+---
+
 ## COMANDOS (Slash Commands)
 
 | Comando | Ação |