@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/framework/templates/docs/spec.md

@@ -0,0 +1,149 @@
+# Feature Specification: {{titleCase FEATURE_NAME}}
+
+| Field | Value |
+|-------|-------|
+| **ID** | {{FEATURE_NAME}} |
+| **Status** | Draft / In Review / Approved / In Progress / Done |
+| **Created** | {{DATE}} |
+| **Stack** | {{STACK}} |
+| **Complexity** | Low / Medium / High |
+| **Estimated Cost** | $X/month |
+| **Agents** | Core: All / Specialists: {list} |
+
+---
+
+## Overview
+
+**Problem:** {What problem this feature solves}
+
+**Solution:** {High-level solution}
+
+**Success Criteria:**
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+
+---
+
+## Requirements
+
+**Functional:** FR1: {desc} | FR2: {desc} | FR3: {desc}
+
+**Non-Functional:** NFR1: Performance - {target} | NFR2: Reliability - {target}
+
+---
+
+## User Stories
+
+### US001: {Title}
+**As** {user type} **I want** {feature} **so that** {benefit}
+
+**Acceptance Criteria:** 1. {criterion} 2. {criterion}
+
+**Edge Cases:** {edge case}: {handling}
+
+---
+
+## Technical Design
+
+### Stack
+| Component | Technology |
+|-----------|------------|
+| Frontend | {Blazor Server / Next.js} |
+| Backend | .NET 10 / C# 14 |
+| Database | {Azure SQL / Cosmos DB} |
+
+### Data Model
+
+#### {EntityName}
+| Column | Type | Constraints |
+|--------|------|-------------|
+| Id | Guid | PK |
+| {Property} | {Type} | {Constraints} |
+| CreatedAt | datetime2 | Default: GETUTCDATE() |
+
+### Contracts
+
+> **Ref:** `framework/standards/blazor-efcore.md` for background operations
+
+```csharp
+public interface I{{pascalCase FEATURE_NAME}}Service
+{
+    Task<{{pascalCase FEATURE_NAME}}Dto> GetByIdAsync(int id);
+    Task<{{pascalCase FEATURE_NAME}}Dto> CreateAsync(Create{{pascalCase FEATURE_NAME}}Request request);
+}
+```
+
+**Contracts Workflow:** Generate `contracts.cs` FIRST → validate names → reference in spec → approve with user.
+
+**Validation Checklist:**
+- [ ] Property names are descriptive (not generic "Data", "Value")
+- [ ] Records use correct types (Stream vs byte[], Guid vs string)
+- [ ] Response DTOs have all properties needed for UI
+- [ ] Request DTOs have implicit validations (required, nullable)
+
+---
+
+## UI/UX Design (if front-end)
+
+### Wireframes
+```
+{ASCII wireframe per screen - include states: loading, error, empty}
+```
+
+### User Flow
+1. {Step} → {System response}
+
+---
+
+## Flows
+
+### {Flow Name}
+**Trigger:** {what starts this flow}
+1. {Actor} {action} → {system response}
+2. If {condition}: Path A / Else: Path B
+**End State:** {final state}
+
+---
+
+## Cost Estimate
+
+| Resource | SKU | Monthly Cost | Justification |
+|----------|-----|--------------|---------------|
+| {Resource} | {SKU} | ${X} | {Why} |
+| **Total** | | **${X}/month** | |
+
+---
+
+## ADRs (Architectural Decision Records)
+
+### ADR-001: {Decision Title}
+**Status:** Proposed / Accepted
+**Context:** {Why decide now}
+**Decision:** {What we chose}
+**Alternatives:** 1. {Alt} (pros/cons) 2. {Alt} (pros/cons)
+**Trade-offs:** {key trade-offs}
+
+---
+
+## Security
+
+| Action | Required Policy |
+|--------|-----------------|
+| View | CanView{Feature} |
+| Create | CanManage{Feature} |
+
+## Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| {Risk} | {H/M/L} | {Mitigation} |
+
+## Out of Scope
+- {Item}
+
+## Definition of Done
+- [ ] Code implemented
+- [ ] Tests >80% coverage
+- [ ] Code review approved
+- [ ] Deploy to staging
+- [ ] Recap.md generated

package/framework/templates/examples/design-system-examples.md

@@ -0,0 +1,357 @@
+# Design System CSS Index Template
+
+> Template de indice estruturado para arquivos CSS grandes.
+> Copie este header para o inicio do seu `design-system.css`.
+
+## Indice Padrao
+
+```css
+/* ===========================================================================
+   {PROJECT_NAME} Design System
+   ===========================================================================
+
+   Indice de Secoes
+   ================
+
+   1-99:     Tokens e Variaveis CSS
+   100-199:  Reset e Base Styles
+   200-299:  Tipografia
+   300-399:  Layout e Containers
+   400-499:  Componentes Base (buttons, inputs, cards)
+   500-599:  Componentes Compostos (forms, tables, lists)
+   600-699:  Navegacao (header, sidebar, footer, menus)
+   700-799:  Paginas Especificas
+   800-849:  Modais e Overlays
+   850-899:  Animacoes e Keyframes
+   900-949:  Responsivo e Media Queries
+   950-979:  Utilities e Helpers
+   980-989:  Overrides de Fluent UI / MudBlazor
+   990-999:  Hotfixes e Temporarios
+
+   Convencoes de Nomenclatura
+   ==========================
+
+   Prefixo por Pagina:
+   - .home-*      : Pagina inicial
+   - .checkout-*  : Pagina de checkout
+   - .dashboard-* : Pagina de dashboard
+   - .auth-*      : Paginas de autenticacao
+
+   Prefixo por Componente:
+   - .btn-*       : Botoes
+   - .card-*      : Cards
+   - .modal-*     : Modais
+   - .form-*      : Formularios
+   - .nav-*       : Navegacao
+
+   Sufixos de Estado:
+   - *--active    : Estado ativo
+   - *--disabled  : Estado desabilitado
+   - *--loading   : Estado de loading
+   - *--error     : Estado de erro
+
+   Validacao:
+   morph-spec validate-css src/MyApp.Web
+
+   =========================================================================== */
+
+
+/* ===========================================================================
+   SECAO 1-99: TOKENS E VARIAVEIS CSS
+   =========================================================================== */
+
+:root {
+  /* Cores Primarias */
+  --primary: #3b82f6;
+  --primary-hover: #2563eb;
+  --primary-active: #1d4ed8;
+
+  /* Cores Secundarias */
+  --secondary: #6b7280;
+  --secondary-hover: #4b5563;
+
+  /* Cores Semanticas */
+  --success: #10b981;
+  --warning: #f59e0b;
+  --error: #ef4444;
+  --info: #06b6d4;
+
+  /* Neutros */
+  --neutral-50: #f9fafb;
+  --neutral-100: #f3f4f6;
+  --neutral-200: #e5e7eb;
+  --neutral-300: #d1d5db;
+  --neutral-400: #9ca3af;
+  --neutral-500: #6b7280;
+  --neutral-600: #4b5563;
+  --neutral-700: #374151;
+  --neutral-800: #1f2937;
+  --neutral-900: #111827;
+
+  /* Tipografia */
+  --font-family: 'Inter', system-ui, -apple-system, sans-serif;
+  --font-family-mono: 'JetBrains Mono', monospace;
+
+  --font-size-xs: 0.75rem;   /* 12px */
+  --font-size-sm: 0.875rem;  /* 14px */
+  --font-size-base: 1rem;    /* 16px */
+  --font-size-lg: 1.125rem;  /* 18px */
+  --font-size-xl: 1.25rem;   /* 20px */
+  --font-size-2xl: 1.5rem;   /* 24px */
+  --font-size-3xl: 1.875rem; /* 30px */
+  --font-size-4xl: 2.25rem;  /* 36px */
+
+  /* Espacamento (base 4px) */
+  --space-1: 0.25rem;  /* 4px */
+  --space-2: 0.5rem;   /* 8px */
+  --space-3: 0.75rem;  /* 12px */
+  --space-4: 1rem;     /* 16px */
+  --space-5: 1.25rem;  /* 20px */
+  --space-6: 1.5rem;   /* 24px */
+  --space-8: 2rem;     /* 32px */
+  --space-10: 2.5rem;  /* 40px */
+  --space-12: 3rem;    /* 48px */
+
+  /* Border Radius */
+  --radius-sm: 0.25rem;  /* 4px */
+  --radius-md: 0.5rem;   /* 8px */
+  --radius-lg: 0.75rem;  /* 12px */
+  --radius-xl: 1rem;     /* 16px */
+  --radius-full: 9999px;
+
+  /* Sombras */
+  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);
+
+  /* Transicoes */
+  --transition-fast: 150ms ease;
+  --transition-normal: 300ms ease;
+  --transition-slow: 500ms ease;
+
+  /* Z-Index */
+  --z-dropdown: 1000;
+  --z-sticky: 1020;
+  --z-fixed: 1030;
+  --z-modal-backdrop: 1040;
+  --z-modal: 1050;
+  --z-popover: 1060;
+  --z-tooltip: 1070;
+}
+
+
+/* ===========================================================================
+   SECAO 100-199: RESET E BASE STYLES
+   =========================================================================== */
+
+/* ... */
+
+
+/* ===========================================================================
+   SECAO 200-299: TIPOGRAFIA
+   =========================================================================== */
+
+/* ... */
+
+
+/* ===========================================================================
+   SECAO 300-399: LAYOUT E CONTAINERS
+   =========================================================================== */
+
+.page-layout {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.page-content {
+  flex: 1;
+  padding: var(--space-6);
+}
+
+.container {
+  width: 100%;
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 0 var(--space-4);
+}
+
+
+/* ===========================================================================
+   SECAO 400-499: COMPONENTES BASE
+   =========================================================================== */
+
+/* Botoes */
+.btn-primary { /* ... */ }
+.btn-secondary { /* ... */ }
+
+/* Cards */
+.card { /* ... */ }
+.card-premium { /* ... */ }
+
+/* Inputs */
+.input { /* ... */ }
+
+
+/* ===========================================================================
+   SECAO 500-599: COMPONENTES COMPOSTOS
+   =========================================================================== */
+
+/* Forms */
+.form-group { /* ... */ }
+.form-label { /* ... */ }
+
+/* Tables */
+.data-table { /* ... */ }
+
+
+/* ===========================================================================
+   SECAO 600-699: NAVEGACAO
+   =========================================================================== */
+
+.page-header-nav { /* ... */ }
+.page-footer { /* ... */ }
+.sidebar { /* ... */ }
+
+
+/* ===========================================================================
+   SECAO 700-799: PAGINAS ESPECIFICAS
+   =========================================================================== */
+
+/* Home */
+.home-hero { /* ... */ }
+.home-features { /* ... */ }
+
+/* Checkout */
+.checkout-form { /* ... */ }
+.checkout-summary { /* ... */ }
+
+
+/* ===========================================================================
+   SECAO 800-849: MODAIS E OVERLAYS
+   =========================================================================== */
+
+.modal-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(4px);
+  z-index: var(--z-modal-backdrop);
+}
+
+.modal-container {
+  position: fixed;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  z-index: var(--z-modal);
+}
+
+
+/* ===========================================================================
+   SECAO 850-899: ANIMACOES E KEYFRAMES
+   =========================================================================== */
+
+@keyframes slideInUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes scaleIn {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.animate-slideInUp {
+  animation: slideInUp var(--transition-normal) forwards;
+}
+
+.animate-scaleIn {
+  animation: scaleIn var(--transition-fast) forwards;
+}
+
+/* Stagger delays para animacoes em sequencia */
+.stagger-1 { animation-delay: 0.1s; }
+.stagger-2 { animation-delay: 0.2s; }
+.stagger-3 { animation-delay: 0.3s; }
+.stagger-4 { animation-delay: 0.4s; }
+.stagger-5 { animation-delay: 0.5s; }
+
+
+/* ===========================================================================
+   SECAO 900-949: RESPONSIVO E MEDIA QUERIES
+   =========================================================================== */
+
+@media (max-width: 768px) {
+  /* Tablet e Mobile */
+}
+
+@media (max-width: 480px) {
+  /* Mobile */
+}
+
+
+/* ===========================================================================
+   SECAO 950-979: UTILITIES E HELPERS
+   =========================================================================== */
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+
+/* ===========================================================================
+   SECAO 980-989: OVERRIDES DE FLUENT UI / MUDBLAZOR
+   =========================================================================== */
+
+/* Fluent UI overrides */
+.fluent-card {
+  /* Customizacoes */
+}
+
+
+/* ===========================================================================
+   SECAO 990-999: HOTFIXES E TEMPORARIOS
+   =========================================================================== */
+
+/* TODO: Remover apos fix no componente X */
+```
+
+## Uso
+
+1. Copie o header para o inicio do seu `design-system.css`
+2. Substitua `{PROJECT_NAME}` pelo nome do seu projeto
+3. Adicione suas classes CSS nas secoes apropriadas
+4. Mantenha o indice atualizado conforme adiciona novas secoes
+
+## Beneficios
+
+- **Navegacao rapida:** Use Ctrl+G (go to line) para pular para secoes
+- **Organizacao clara:** Cada tipo de componente em sua secao
+- **Facil manutencao:** Encontre onde adicionar novos estilos
+- **Evita conflitos:** Prefixos por pagina previnem colisoes
+
+---
+
+*Template MORPH-SPEC v2.2.0 by Polymorphism Tech*

package/framework/templates/examples/spec-examples.md

@@ -0,0 +1,90 @@
+# Spec Template Reference
+
+> **Layer:** 3 | **Load:** on-demand | **Keywords:** spec, specification, template
+
+**Use the stack's `.morph/templates/spec.md` as the canonical template.**
+
+This file contains extended examples for each spec section.
+
+---
+
+## Example: Entity (Pseudo-code)
+
+```csharp
+class ProcessingJob {
+  Guid Id
+  string OriginalPhotoUrl     // Azure Blob URL, max 500 chars
+  string? ProcessedPhotoUrl   // Nullable, populated after processing
+  ProcessingStatus Status     // Enum: Pending, Processing, Completed, Failed
+  DateTime CreatedAt
+  ICollection<ExecutionLog> Logs  // 1:N relationship
+}
+
+enum ProcessingStatus {
+  Pending = 0, Processing = 1, Completed = 2,  // Normal flow
+  Failed = 100                                   // Error states (high values)
+}
+```
+
+## Example: Command (Pseudo-code)
+
+```csharp
+UploadPhotoCommand {
+  Input: IFormFile photo, string? email
+  Output: Guid jobId
+
+  Handler:
+    1. Validate file (size <= 10MB, type in [.jpg, .png])
+    2. Upload to Azure Blob Storage
+    3. Create ProcessingJob entity (status = Pending)
+    4. Enqueue Hangfire background job
+    5. Return jobId
+}
+```
+
+## Example: API Endpoints
+
+```csharp
+PhotoProcessingController {
+  POST /api/upload        → multipart/form-data → { jobId: Guid }
+  GET  /api/status/{id}   → jobId → { status, progress, createdAt }
+  GET  /api/download/{id} → jobId → Redirect to Blob URL or 404
+}
+```
+
+## Example: Flow
+
+```
+Upload Flow (Actor: User)
+1. User selects photo → System validates (size, type) → If invalid: show error
+2. User sees preview → clicks "Upload"
+3. System creates ProcessingJob → uploads to Blob → enqueues Hangfire job → returns jobId
+4. System navigates to /processing/{jobId} → polls every 5s
+End State: User on progress page, job processing in background
+```
+
+## Example: ADR
+
+### ADR-001: Use Hangfire for Background Jobs
+**Status:** Accepted
+**Context:** Need background processing for AI photo transformation (30-120s).
+**Decision:** Hangfire (self-hosted).
+**Alternatives:**
+1. Azure Functions — serverless, auto-scaling, but cold start + $10/mo for 50k jobs
+2. Hangfire — zero cost, simpler, but scales with app
+3. Quartz.NET — more features, but steeper learning curve
+**Trade-offs:** Simplicity vs Features (Hangfire sufficient for MVP)
+
+## Example: Cost Estimate
+
+| Resource | SKU | Monthly | Justification |
+|----------|-----|---------|---------------|
+| Blob Storage | LRS | $0.02 | Store photos, low redundancy OK |
+| Azure SQL | Basic | $4.99 | < 100k jobs/month |
+| Container App | Consumption | $0.49 | Scale to zero |
+| Hangfire | Self-hosted | $0.00 | In-process |
+| **Total** | | **~$5.50** | |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*