@polymorphism-tech/morph-spec 3.2.0 → 4.2.0

package/bin/validate-phase.js

@@ -1,263 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * MORPH-SPEC Phase Validator
- *
- * Validates that required previous phases have been completed before advancing.
- * Prevents skipping phases accidentally.
- *
- * Usage:
- *   node bin/validate-phase.js <feature-name> <target-phase>
- *
- * Example:
- *   node bin/validate-phase.js scheduled-reports implement
- */
-
-import fs from 'fs';
-import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-// ANSI colors
-const colors = {
-  green: '\x1b[32m',
-  red: '\x1b[31m',
-  yellow: '\x1b[33m',
-  cyan: '\x1b[36m',
-  gray: '\x1b[90m',
-  reset: '\x1b[0m'
-};
-
-// Phase definitions with requirements
-const PHASES = {
-  'proposal': {
-    order: 0,
-    name: 'FASE 0: PROPOSAL',
-    requiredOutputs: ['proposal.md'],
-    description: 'Initial proposal and agent detection'
-  },
-  'setup': {
-    order: 1,
-    name: 'FASE 1: SETUP',
-    requiredOutputs: ['proposal.md'],
-    description: 'Load context and standards'
-  },
-  'uiux-design': {
-    order: 2,
-    name: 'FASE 1.5: UI/UX DESIGN',
-    requiredOutputs: ['proposal.md', 'ui-design-system.md', 'ui-mockups.md', 'ui-components.md', 'ui-flows.md'],
-    description: 'UI/UX design (conditional - only if frontend)',
-    optional: true
-  },
-  'design': {
-    order: 3,
-    name: 'FASE 2: DESIGN',
-    requiredOutputs: ['proposal.md', 'spec.md', 'contracts.cs', 'decisions.md'],
-    description: 'Technical specification and contracts'
-  },
-  'clarify': {
-    order: 4,
-    name: 'FASE 3: CLARIFY',
-    requiredOutputs: ['proposal.md', 'spec.md', 'contracts.cs'],
-    description: 'Clarify ambiguities and edge cases'
-  },
-  'tasks': {
-    order: 5,
-    name: 'FASE 4: TASKS',
-    requiredOutputs: ['proposal.md', 'spec.md', 'contracts.cs', 'tasks.json'],
-    description: 'Break down into executable tasks'
-  },
-  'implement': {
-    order: 6,
-    name: 'FASE 5: IMPLEMENT',
-    requiredOutputs: ['proposal.md', 'spec.md', 'contracts.cs', 'tasks.json'],
-    description: 'Execute tasks and implement code'
-  },
-  'sync': {
-    order: 7,
-    name: 'FASE 6: SYNC',
-    requiredOutputs: ['proposal.md', 'spec.md', 'decisions.md', 'recap.md'],
-    description: 'Sync decisions to project standards',
-    optional: true
-  }
-};
-
-/**
- * Check if output file exists
- */
-function checkOutput(featurePath, outputFile) {
-  const filePath = path.join(featurePath, outputFile);
-  return fs.existsSync(filePath);
-}
-
-/**
- * Validate phase requirements
- */
-function validatePhase(featureName, targetPhase) {
-  const featurePath = path.join(process.cwd(), '.morph/project/outputs', featureName);
-
-  // Check if feature directory exists
-  if (!fs.existsSync(featurePath)) {
-    return {
-      valid: false,
-      error: `Feature directory not found: ${featurePath}`,
-      missingOutputs: [],
-      phase: null
-    };
-  }
-
-  // Get target phase definition
-  const phaseDefinition = PHASES[targetPhase];
-  if (!phaseDefinition) {
-    return {
-      valid: false,
-      error: `Unknown phase: ${targetPhase}`,
-      validPhases: Object.keys(PHASES),
-      missingOutputs: [],
-      phase: null
-    };
-  }
-
-  // Check required outputs
-  const missingOutputs = [];
-  for (const output of phaseDefinition.requiredOutputs) {
-    if (!checkOutput(featurePath, output)) {
-      missingOutputs.push(output);
-    }
-  }
-
-  // Special validation: if target is 'implement', check tasks.json structure
-  if (targetPhase === 'implement' && checkOutput(featurePath, 'tasks.json')) {
-    try {
-      const tasksPath = path.join(featurePath, 'tasks.json');
-      const tasks = JSON.parse(fs.readFileSync(tasksPath, 'utf-8'));
-
-      if (!tasks.tasks || !Array.isArray(tasks.tasks) || tasks.tasks.length === 0) {
-        missingOutputs.push('tasks.json (must contain tasks array)');
-      }
-    } catch (error) {
-      missingOutputs.push('tasks.json (invalid JSON)');
-    }
-  }
-
-  return {
-    valid: missingOutputs.length === 0,
-    error: null,
-    missingOutputs,
-    phase: phaseDefinition,
-    featurePath
-  };
-}
-
-/**
- * Print validation result
- */
-function printResult(result, featureName, targetPhase) {
-  console.log(`\n${colors.cyan}╔════════════════════════════════════════════════╗${colors.reset}`);
-  console.log(`${colors.cyan}║     MORPH-SPEC PHASE VALIDATOR                 ║${colors.reset}`);
-  console.log(`${colors.cyan}╚════════════════════════════════════════════════╝${colors.reset}\n`);
-
-  console.log(`${colors.gray}Feature:${colors.reset} ${featureName}`);
-  console.log(`${colors.gray}Target Phase:${colors.reset} ${result.phase ? result.phase.name : targetPhase}`);
-
-  if (result.phase) {
-    console.log(`${colors.gray}Description:${colors.reset} ${result.phase.description}`);
-  }
-
-  if (result.valid) {
-    console.log(`\n${colors.green}✓ VALIDATION PASSED${colors.reset}`);
-    console.log(`${colors.green}  All required outputs are present.${colors.reset}`);
-    console.log(`${colors.green}  Safe to proceed to ${result.phase.name}${colors.reset}\n`);
-  } else {
-    console.log(`\n${colors.red}✗ VALIDATION FAILED${colors.reset}`);
-
-    if (result.error) {
-      console.log(`${colors.red}  Error: ${result.error}${colors.reset}\n`);
-
-      if (result.validPhases) {
-        console.log(`${colors.yellow}Valid phases:${colors.reset}`);
-        result.validPhases.forEach(phase => {
-          console.log(`  - ${phase}`);
-        });
-      }
-    } else {
-      console.log(`${colors.red}  Missing required outputs:${colors.reset}`);
-      result.missingOutputs.forEach(output => {
-        console.log(`  ${colors.gray}-${colors.reset} ${output}`);
-      });
-
-      console.log(`\n${colors.yellow}Action required:${colors.reset}`);
-      console.log(`  Complete the missing outputs before advancing to ${result.phase.name}`);
-    }
-    console.log('');
-  }
-}
-
-/**
- * Print help
- */
-function printHelp() {
-  console.log(`
-${colors.cyan}MORPH-SPEC Phase Validator${colors.reset}
-
-Validates that required previous phases have been completed before advancing.
-
-${colors.green}Usage:${colors.reset}
-  node bin/validate-phase.js <feature-name> <target-phase>
-
-${colors.green}Arguments:${colors.reset}
-  feature-name    Name of the feature (kebab-case)
-  target-phase    Phase you want to advance to
-
-${colors.green}Valid Phases:${colors.reset}
-  proposal        FASE 0: Initial proposal
-  setup           FASE 1: Load context and standards
-  uiux-design     FASE 1.5: UI/UX design (optional)
-  design          FASE 2: Technical specification
-  clarify         FASE 3: Clarify ambiguities
-  tasks           FASE 4: Break down into tasks
-  implement       FASE 5: Execute implementation
-  sync            FASE 6: Sync to project standards (optional)
-
-${colors.green}Examples:${colors.reset}
-  # Check if ready to implement
-  node bin/validate-phase.js scheduled-reports implement
-
-  # Check if ready for design phase
-  node bin/validate-phase.js user-auth design
-
-  # Use in slash command
-  node bin/validate-phase.js my-feature implement || exit 1
-
-${colors.green}Exit Codes:${colors.reset}
-  0 - Validation passed (safe to proceed)
-  1 - Validation failed (missing requirements)
-
-${colors.green}Integration:${colors.reset}
-  This validator is designed to be called from slash commands like
-  /morph-apply to ensure phase gates are respected.
-  `);
-}
-
-/**
- * Main function
- */
-function main() {
-  const args = process.argv.slice(2);
-
-  if (args.includes('--help') || args.includes('-h') || args.length < 2) {
-    printHelp();
-    process.exit(args.length < 2 ? 1 : 0);
-  }
-
-  const [featureName, targetPhase] = args;
-
-  const result = validatePhase(featureName, targetPhase);
-  printResult(result, featureName, targetPhase);
-
-  process.exit(result.valid ? 0 : 1);
-}
-
-main();

package/docs/examples.md

@@ -1,328 +0,0 @@
-# MORPH-SPEC Examples Guide
-
-Guia dos exemplos incluídos no framework.
-
----
-
-## Visão Geral
-
-| Exemplo | Stack | Complexidade | Tempo Est. |
-|---------|-------|--------------|------------|
-| [micro-saas](#micro-saas) | Blazor + Asaas | Alta | 2-3 dias |
-| [api-nextjs](#api-nextjs) | .NET + Next.js | Média | 1-2 dias |
-| [multi-agent](#multi-agent) | Semantic Kernel | Alta | 2-3 dias |
-
----
-
-## micro-saas
-
-**Localização**: `.morph/examples/micro-saas/`
-
-### Descrição
-
-SaaS completo com multi-tenancy e billing integrado via Asaas.
-
-### Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Frontend | Blazor Server |
-| Backend | .NET 8 Minimal APIs |
-| Database | SQL Server |
-| Auth | Clerk |
-| Billing | Asaas |
-| Infra | Azure Container Apps |
-
-### Features
-
-- **Multi-tenancy**: Isolamento completo por tenant
-- **Subscription Management**: Planos Free, Starter, Pro, Enterprise
-- **Payment Methods**: PIX, Boleto, Cartão de Crédito
-- **Dashboard**: Métricas e gestão
-- **User Management**: Convites, roles (Owner, Admin, Member)
-- **Webhooks**: Processamento de eventos Asaas
-
-### Arquivos
-
-```
-micro-saas/
-├── README.md           # Visão geral e arquitetura
-├── spec.md             # Especificação completa
-├── contracts.cs        # 50+ interfaces e DTOs
-├── tasks.md            # 51 tasks organizadas
-└── decisions.md        # 10 ADRs documentados
-```
-
-### ADRs Principais
-
-| ADR | Decisão |
-|-----|---------|
-| ADR-001 | Blazor Server vs WebAssembly |
-| ADR-002 | Asaas vs Stripe |
-| ADR-003 | Clerk vs Azure AD B2C |
-| ADR-004 | Single DB com Query Filters |
-| ADR-005 | Tenant Resolution Strategy |
-
-### Para Começar
-
-```bash
-# 1. Copie o exemplo para seu projeto
-cp -r .morph/examples/micro-saas/ .morph/features/
-
-# 2. Revise a spec
-cat .morph/features/micro-saas/spec.md
-
-# 3. Ajuste para suas necessidades
-# Edite spec.md com seus requisitos específicos
-
-# 4. Implemente
-/morph-apply micro-saas
-```
-
-### Custos Estimados
-
-| Recurso | Custo/mês |
-|---------|-----------|
-| Container Apps | ~$0 (scale-to-zero) |
-| SQL Database | $0 (Free tier) |
-| Storage | ~$0.50 |
-| Asaas | 2.99% + R$0.49/transação |
-| **Total** | **< $5/mês** |
-
----
-
-## api-nextjs
-
-**Localização**: `.morph/examples/api-nextjs/`
-
-### Descrição
-
-Arquitetura full-stack com API .NET e frontend Next.js.
-
-### Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Frontend | Next.js 14 (App Router) |
-| Backend | .NET 8 Minimal APIs |
-| Database | SQL Server |
-| Auth | Clerk |
-| Data Fetching | React Query |
-| UI | Tailwind + shadcn/ui |
-
-### Features
-
-- **Minimal APIs**: Endpoints organizados e documentados
-- **App Router**: Server Components + Client Components
-- **React Query**: Cache, mutations, optimistic updates
-- **TypeScript**: Types compartilhados (contracts.ts)
-- **Forms**: React Hook Form + Zod validation
-- **Dark Mode**: Theme switching
-
-### Arquivos
-
-```
-api-nextjs/
-├── README.md           # Arquitetura e setup
-├── spec.md             # Especificação detalhada
-├── contracts.ts        # Types TypeScript compartilhados
-└── tasks.md            # 67 tasks organizadas
-```
-
-### Estrutura do Projeto
-
-```
-project/
-├── src/
-│   ├── api/            # .NET Backend
-│   │   ├── Api/
-│   │   ├── Application/
-│   │   ├── Domain/
-│   │   └── Infrastructure/
-│   │
-│   └── web/            # Next.js Frontend
-│       ├── app/
-│       ├── components/
-│       ├── hooks/
-│       ├── lib/
-│       └── types/
-│
-└── infra/              # IaC
-```
-
-### Para Começar
-
-```bash
-# 1. Copie o exemplo
-cp -r .morph/examples/api-nextjs/ .morph/features/
-
-# 2. Revise contracts.ts para seu domínio
-# Este arquivo define os types compartilhados
-
-# 3. Ajuste spec.md
-# Modifique entidades e endpoints para seu caso
-
-# 4. Implemente
-/morph-apply api-nextjs
-```
-
-### Patterns Demonstrados
-
-| Pattern | Descrição |
-|---------|-----------|
-| API Client | Fetch wrapper com auth |
-| Query Keys | Organização de cache keys |
-| Data Hooks | useProducts, useOrders |
-| Form Pattern | React Hook Form + Zod |
-| Server Components | Data fetching no servidor |
-
----
-
-## multi-agent
-
-**Localização**: `.morph/examples/multi-agent/`
-
-### Descrição
-
-Sistema de agentes AI cooperativos com Semantic Kernel.
-
-### Stack
-
-| Camada | Tecnologia |
-|--------|------------|
-| Framework | Semantic Kernel |
-| LLM | Azure OpenAI |
-| Orchestration | Custom Orchestrator |
-| Storage | In-Memory / Cosmos DB |
-| Infra | Azure Container Apps |
-
-### Agentes
-
-| Agente | Responsabilidade |
-|--------|------------------|
-| **Orchestrator** | Coordena outros agentes |
-| **Research** | Busca e RAG |
-| **Analysis** | Análise e comparações |
-| **Writing** | Geração de texto |
-
-### Features
-
-- **Task Decomposition**: Quebra tarefas complexas
-- **Plugin System**: WebSearch, Documents, Calculator
-- **Conversation Memory**: Contexto por sessão
-- **Semantic Memory**: RAG com embeddings
-- **Streaming**: Server-Sent Events
-
-### Arquivos
-
-```
-multi-agent/
-├── README.md           # Visão geral
-├── spec.md             # Especificação detalhada
-├── contracts.cs        # Interfaces e DTOs
-└── tasks.md            # 53 tasks organizadas
-```
-
-### Fluxo de Execução
-
-```
-User Request
-    │
-    ▼
-┌─────────────┐
-│ Orchestrator│ → Decompõe tarefa
-└─────────────┘
-    │
-    ├──► Research Agent → Busca informações
-    │
-    ├──► Analysis Agent → Analisa dados
-    │
-    └──► Writing Agent → Gera output
-          │
-          ▼
-   Consolidated Response
-```
-
-### Para Começar
-
-```bash
-# 1. Configure Azure OpenAI
-# - Crie deployment gpt-4
-# - Crie deployment text-embedding-ada-002
-
-# 2. Copie o exemplo
-cp -r .morph/examples/multi-agent/ .morph/features/
-
-# 3. Configure appsettings
-# Adicione suas credenciais Azure OpenAI
-
-# 4. Implemente
-/morph-apply multi-agent
-```
-
-### Custos Estimados
-
-| Recurso | Custo |
-|---------|-------|
-| GPT-4 | ~$0.03/1K tokens |
-| Embeddings | ~$0.0001/1K tokens |
-| Container Apps | ~$0-10/mês |
-
-**Nota**: Custos variam com uso. Para dev, use gpt-3.5-turbo.
-
----
-
-## Como Usar os Exemplos
-
-### 1. Estudar a Estrutura
-
-Cada exemplo segue o padrão MORPH-SPEC:
-- `spec.md` - O quê construir
-- `contracts.cs/ts` - Interfaces e tipos
-- `tasks.md` - Como construir
-- `decisions.md` - Por que decisões foram tomadas
-
-### 2. Adaptar para Seu Projeto
-
-1. Copie o exemplo para `.morph/features/`
-2. Edite `spec.md` com seus requisitos
-3. Ajuste `contracts.cs` com suas entidades
-4. Revise `tasks.md` e remova o que não precisa
-
-### 3. Implementar
-
-```bash
-/morph-apply <nome-do-exemplo>
-```
-
-### 4. Customizar Templates
-
-Se precisar de padrões diferentes:
-1. Copie templates de `.morph/templates/`
-2. Modifique conforme necessário
-3. MORPH usará seus templates customizados
-
----
-
-## Comparação de Complexidade
-
-| Aspecto | micro-saas | api-nextjs | multi-agent |
-|---------|------------|------------|-------------|
-| **Entities** | 6 | 4 | 5 |
-| **Tasks** | 51 | 67 | 53 |
-| **Integrations** | 2 (Asaas, Clerk) | 1 (Clerk) | 2 (OpenAI, Bing) |
-| **IaC Resources** | 5 | 6 | 4 |
-| **Custo Infra** | < $5 | < $10 | Variável |
-
----
-
-## Próximos Passos
-
-1. Escolha o exemplo mais próximo do seu caso
-2. Leia a `spec.md` completa
-3. Revise os `contracts.*` para entender o modelo
-4. Use como base ou implemente diretamente
-
----
-
-*MORPH-SPEC by Polymorphism Tech*