@polymorphism-tech/morph-spec 4.3.3 → 4.3.5

package/docs/troubleshooting.md

@@ -1,269 +0,0 @@
-# Troubleshooting - CLI Auto Context Detection
-
-Common issues and solutions for MORPH-SPEC auto-detection.
-
-## Claude Code Issues
-
-### Issue: "Claude Code environment not detected"
-
-**Cause**: Auto-detection requires Claude Code CLI to be installed and active.
-
-**Solutions**:
-
-1. **Use wizard mode** (recommended for first-time setup):
-   ```bash
-   morph-spec init --wizard
-   ```
-
-2. **Install Claude Code** and retry:
-   - Download from https://claude.ai/claude-code
-   - Ensure `claude` command is in PATH
-   - Retry `morph-spec init`
-
-3. **Skip auto-detection** and configure manually later:
-   ```bash
-   morph-spec init --skip-detection
-   # Later: morph-spec update --wizard
-   ```
-
-### Issue: "LLM analysis timeout"
-
-**Cause**: Analysis taking longer than 60 seconds (default timeout for interactive mode).
-
-**Solutions**:
-
-1. **Clean project before analysis**:
-   ```bash
-   rm -rf node_modules dist build .next
-   morph-spec init
-   ```
-
-2. **Use wizard mode** (instant):
-   ```bash
-   morph-spec init --wizard
-   ```
-
-3. **Check Claude Code performance**:
-   - Restart Claude Code
-   - Check system resources (CPU, memory)
-
-## LLM Analysis Errors
-
-### Issue: "Schema validation failed"
-
-**Cause**: LLM returned JSON that doesn't match the expected schema.
-
-**Diagnosis**:
-```bash
-# Enable debug mode to see LLM response
-DEBUG=1 morph-spec init
-```
-
-**Solutions**:
-
-1. **Use wizard mode** to provide manual input:
-   ```bash
-   morph-spec init --wizard
-   ```
-
-2. **Report issue** if recurring:
-   - Include project type in issue report
-   - Share anonymized `package.json` or `.csproj` structure
-
-### Issue: "LLM response is not valid JSON"
-
-**Cause**: LLM returned malformed JSON (rare).
-
-**Solutions**:
-
-1. **Retry** - may be a one-time error:
-   ```bash
-   morph-spec init
-   ```
-
-2. **Use wizard mode**:
-   ```bash
-   morph-spec init --wizard
-   ```
-
-## File System Issues
-
-### Issue: "Permission denied" when creating .morph/
-
-**Cause**: Insufficient permissions in project directory.
-
-**Solutions**:
-
-1. **Run with correct permissions**:
-   ```bash
-   sudo morph-spec init  # Unix/Mac
-   # Or run as administrator on Windows
-   ```
-
-2. **Check directory ownership**:
-   ```bash
-   ls -la .  # Should show your user as owner
-   ```
-
-### Issue: Config files getting overwritten
-
-**Cause**: Running `morph-spec update` without reviewing changes.
-
-**Protection**: Auto-detection creates backups:
-- `.morph/project.md.YYYY-MM-DDTHH-MM-SS.backup`
-- `.morph/config/config.json.YYYY-MM-DDTHH-MM-SS.backup`
-
-**Solutions**:
-
-1. **Review diff before approving**:
-   - Auto-detection shows diff when updating
-   - Choose "Edit" to modify before saving
-
-2. **Restore from backup** if needed:
-   ```bash
-   cp .morph/project.md.2026-02-14T10-30-00.backup .morph/project.md
-   ```
-
-3. **Skip auto-detection** during update:
-   ```bash
-   morph-spec update --skip-detection
-   ```
-
-## Detection Accuracy Issues
-
-### Issue: Wrong project type detected
-
-**Example**: Monorepo detected as `nextjs` instead of `monorepo`.
-
-**Solutions**:
-
-1. **Use wizard mode** for accurate manual input:
-   ```bash
-   morph-spec init --wizard
-   ```
-
-2. **Edit config after generation**:
-   - Choose "Edit" during review
-   - Manually correct `type` field in config.json
-
-3. **Report detection issue**:
-   - Helps improve LLM prompt and examples
-
-### Issue: Missing dependencies detected
-
-**Cause**: Auto-detection only reads whitelisted files (package.json, .csproj).
-
-**Solution**:
-
-- This is by design (privacy/security)
-- If critical dependency is missed, manually edit `.morph/project.md`
-
-### Issue: Low confidence score (<70%)
-
-**Cause**: Project structure is unclear or non-standard.
-
-**Solutions**:
-
-1. **Add README.md or CLAUDE.md** with project description
-2. **Use wizard mode** for manual configuration
-3. **Accept low confidence** - configs can be edited later
-
-## Edge Case Handling
-
-### Empty Project (no package.json or .csproj)
-
-**Behavior**: Auto-fallback to wizard mode.
-
-**Solution**: Answer 7 wizard questions to configure manually.
-
-### Monorepo with Multiple Stacks
-
-**Behavior**: Detects all stacks, sets `type: "monorepo"`.
-
-**Example Output**:
-```json
-{
-  "type": "monorepo",
-  "stack": {
-    "frontend": { "tech": "Next.js", "version": "15" },
-    "backend": { "tech": ".NET", "version": "10" }
-  }
-}
-```
-
-### Project with No Database
-
-**Behavior**: `stack.database` set to `null`.
-
-**Warning**: May show "Database technology not detected" in warnings.
-
-### Git Repo Without Remote
-
-**Behavior**: `gitRemote` set to `null`.
-
-**Not an error** - local repos are valid.
-
-## Privacy & Security Concerns
-
-### Question: What data is sent to LLM?
-
-**Answer**: Only sanitized, whitelisted data:
-- package.json (dependencies only, secrets removed)
-- .csproj filenames (not contents)
-- First 500 chars of README.md and CLAUDE.md
-- Directory structure (folder names only)
-- Infrastructure file counts (not contents)
-
-**Never sent**:
-- `.env` files
-- Secrets/passwords/API keys
-- File contents (except whitelisted files)
-- node_modules/
-- Source code
-
-### Question: Is data sent to Anthropic servers?
-
-**Answer**: No. LLM analysis runs locally in Claude Code. No external API calls.
-
-### Question: What if sensitive data is detected?
-
-**Behavior**: Secret redaction removes:
-- API keys (10+ patterns detected)
-- Passwords in connection strings
-- Bearer tokens
-- Private keys (PEM format)
-- GitHub/NPM tokens
-
-**Verification**: Review sanitized context in debug mode:
-```bash
-DEBUG=1 morph-spec init
-```
-
-## Getting Help
-
-### Enable Debug Mode
-
-```bash
-DEBUG=1 morph-spec init
-```
-
-Shows:
-- Full LLM prompts
-- Raw LLM responses
-- Schema validation errors
-- File read operations
-
-### Report Issues
-
-GitHub: https://github.com/polymorphism-tech/morph-spec-framework/issues
-
-Include:
-- MORPH-SPEC version (`morph-spec --version`)
-- Claude Code version
-- Project type (Next.js, Blazor, etc.)
-- Error message (with DEBUG=1 output if possible)
-- Anonymized `package.json` or `.csproj` structure
-
----
-
-**Need more help?** Check the [CLI Auto Detection Guide](./cli-auto-detection.md).

package/docs/validation-checklist.md

@@ -1,264 +0,0 @@
-# MORPH-SPEC Validation Checklist
-
-Checklist para validar o framework em um projeto real.
-
----
-
-## 1. Setup Validation
-
-### 1.1 Instalação
-- [ ] Script `setup.ps1` ou `setup.sh` executa sem erros
-- [ ] Pasta `.morph` criada corretamente
-- [ ] Pasta `.claude` criada corretamente
-- [ ] `CLAUDE.md` copiado para raiz do projeto
-- [ ] Pasta `infra` criada com templates Bicep
-
-### 1.2 Configuração
-- [ ] `config.json` criado a partir do template
-- [ ] Nome do projeto configurado
-- [ ] Stack selecionada (blazor/nextjs)
-- [ ] Azure subscription configurada (se aplicável)
-
-### 1.3 Estrutura de Arquivos
-- [ ] `.morph/standards/` contém 3 arquivos (coding, architecture, azure)
-- [ ] `.morph/templates/` contém todos os templates
-- [ ] `.morph/templates/infra/` contém 9 arquivos Bicep
-- [ ] `.morph/templates/integrations/` contém 4 arquivos
-- [ ] `.morph/templates/saas/` contém 2 arquivos
-- [ ] `.claude/commands/` contém 6 comandos
-- [ ] `.claude/skills/` contém 17 skills
-
----
-
-## 2. Slash Commands Validation
-
-### 2.1 /morph-proposal
-- [ ] Comando reconhecido pelo Claude Code
-- [ ] Carrega contexto do projeto
-- [ ] Identifica agentes por keywords
-- [ ] Gera `spec.md` na pasta correta
-- [ ] Gera `contracts.cs` com interfaces/DTOs
-- [ ] Gera `decisions.md` com ADRs
-- [ ] Para e aguarda aprovação
-
-### 2.2 /morph-apply
-- [ ] Comando reconhecido pelo Claude Code
-- [ ] Carrega spec existente
-- [ ] Quebra em tasks
-- [ ] Implementa task por task
-- [ ] Executa testes
-- [ ] Faz checkpoints a cada 3 tasks
-- [ ] Gera `recap.md` ao final
-
-### 2.3 /morph-status
-- [ ] Mostra features em andamento
-- [ ] Mostra fase atual de cada feature
-- [ ] Lista agentes ativos
-
-### 2.4 /morph-infra
-- [ ] `init` cria estrutura de infra
-- [ ] `validate` valida templates Bicep
-- [ ] `plan` mostra recursos que serão criados
-
-### 2.5 /morph-costs
-- [ ] Estima custos dos recursos
-- [ ] Mostra free tier vs paid
-- [ ] Alerta sobre custos acima do limite
-
-### 2.6 /morph-archive
-- [ ] Move feature para archive
-- [ ] Atualiza status
-
----
-
-## 3. Agent Activation Validation
-
-### 3.1 Core Agents (Sempre Ativos)
-- [ ] Standards Architect ativado em todas as features
-- [ ] Azure Architect ativado quando há infra
-- [ ] Cost Guardian monitora custos
-
-### 3.2 Stack Agents
-| Keyword | Agente Esperado | Status |
-|---------|-----------------|--------|
-| "blazor", "razor" | Blazor Builder | [ ] |
-| "nextjs", "react" | NextJS Expert | [ ] |
-
-### 3.3 Specialist Agents
-| Keyword | Agente Esperado | Status |
-|---------|-----------------|--------|
-| "database", "entity" | EF Modeler | [ ] |
-| "agent", "ai" | MS Agent Expert | [ ] |
-| "scheduled", "job" | Hangfire Orchestrator | [ ] |
-| "wizard", "dashboard" | UI/UX Designer | [ ] |
-| "unclear", "requirements" | PO/PM Advisor | [ ] |
-
-### 3.4 Integration Agents
-| Keyword | Agente Esperado | Status |
-|---------|-----------------|--------|
-| "asaas", "pix", "boleto" | Asaas Financial | [ ] |
-| "clerk", "auth" | Clerk Auth | [ ] |
-| "identity", "entra" | Azure Identity | [ ] |
-
-### 3.5 Infra Agents
-| Keyword | Agente Esperado | Status |
-|---------|-----------------|--------|
-| "bicep", "iac" | Bicep Architect | [ ] |
-| "pipeline", "ci/cd" | DevOps Engineer | [ ] |
-| "container", "docker" | Container Specialist | [ ] |
-
----
-
-## 4. Templates Validation
-
-### 4.1 Feature Templates
-- [ ] `spec.md` template funciona
-- [ ] `tasks.md` template funciona
-- [ ] `contracts.cs` template funciona
-- [ ] `decisions.md` template funciona
-- [ ] `recap.md` template funciona
-
-### 4.2 Code Templates
-- [ ] `component.razor` compila
-- [ ] `service.cs` compila
-- [ ] `repository.cs` compila
-- [ ] `test.cs` compila
-- [ ] `migration.cs` compila
-- [ ] `agent.cs` compila
-- [ ] `job.cs` compila
-
-### 4.3 IaC Templates
-- [ ] `main.bicep` valida (`az bicep build`)
-- [ ] `container-app.bicep` valida
-- [ ] `container-app-env.bicep` valida
-- [ ] `sql-database.bicep` valida
-- [ ] `storage.bicep` valida
-- [ ] `key-vault.bicep` valida
-- [ ] `app-insights.bicep` valida
-
-### 4.4 Integration Templates
-- [ ] `asaas-client.cs` compila
-- [ ] `asaas-webhook.cs` compila
-- [ ] `clerk-config.cs` compila
-- [ ] `azure-identity-config.cs` compila
-
-### 4.5 SaaS Templates
-- [ ] `subscription.cs` compila
-- [ ] `tenant.cs` compila
-
----
-
-## 5. Workflow Validation
-
-### 5.1 Fase 1: SETUP
-- [ ] Carrega `.morph/project.md`
-- [ ] Carrega `.morph/config/config.json`
-- [ ] Identifica stack do projeto
-- [ ] Cria pasta em `.morph/features/<feature>`
-
-### 5.2 Fase 2: DESIGN
-- [ ] Gera spec baseado na descrição
-- [ ] Consulta `.morph/standards/` para padrões
-- [ ] Gera contracts.cs com DTOs corretos
-- [ ] Estima custos e documenta
-- [ ] PARA para aprovação
-
-### 5.3 Fase 3: CLARIFY
-- [ ] Identifica ambiguidades
-- [ ] Faz perguntas relevantes
-- [ ] Atualiza spec com respostas
-
-### 5.4 Fase 4: TASKS
-- [ ] Quebra spec em tasks numeradas
-- [ ] Define dependências entre tasks
-- [ ] Estabelece checkpoints
-- [ ] PARA para aprovação
-
-### 5.5 Fase 5: IMPLEMENT
-- [ ] Implementa tasks na ordem
-- [ ] Segue padrões de `coding.md`
-- [ ] Executa testes após cada task
-- [ ] Faz checkpoint a cada 3 tasks
-- [ ] Gera recap ao final
-
----
-
-## 6. Cost Validation
-
-### 6.1 Limites
-- [ ] Alerta quando recurso ultrapassa free tier
-- [ ] Bloqueia recursos > $10/mês sem aprovação
-- [ ] Requer ADR para recursos > $10/mês
-
-### 6.2 Estimativas
-- [ ] Container Apps: $0 (scale-to-zero)
-- [ ] SQL Database: $0 (Free tier 32GB)
-- [ ] Storage: < $1/mês
-- [ ] App Insights: $0 (5GB free)
-
----
-
-## 7. End-to-End Test
-
-### 7.1 Cenário: Feature Simples
-```
-/morph-proposal user-profile
-Descrição: "Adicionar página de perfil do usuário com edição de dados"
-```
-
-**Esperado**:
-- [ ] Ativa: Standards Architect, Blazor Builder, EF Modeler
-- [ ] Gera spec com requisitos de perfil
-- [ ] Gera contracts com UserProfileDto
-- [ ] Tasks incluem: criar entity, criar service, criar página
-
-### 7.2 Cenário: Feature com Pagamento
-```
-/morph-proposal subscription-billing
-Descrição: "Implementar cobrança de assinaturas com Asaas, PIX e boleto"
-```
-
-**Esperado**:
-- [ ] Ativa: Asaas Financial, Cost Guardian
-- [ ] Consulta skill `asaas-financial.md`
-- [ ] Usa template `asaas-client.cs`
-- [ ] Usa template `subscription.cs`
-
-### 7.3 Cenário: Feature com Infra
-```
-/morph-proposal deploy-production
-Descrição: "Configurar deploy para produção com Container Apps e SQL"
-```
-
-**Esperado**:
-- [ ] Ativa: Bicep Architect, Container Specialist, Azure Architect
-- [ ] Usa templates de `infra/`
-- [ ] Estima custos
-- [ ] Gera `parameters.prod.json`
-
----
-
-## 8. Issues Found
-
-| # | Descrição | Severidade | Status |
-|---|-----------|------------|--------|
-| 1 | | | |
-| 2 | | | |
-| 3 | | | |
-
----
-
-## 9. Sign-off
-
-| Item | Responsável | Data | Status |
-|------|-------------|------|--------|
-| Setup | | | [ ] |
-| Commands | | | [ ] |
-| Agents | | | [ ] |
-| Templates | | | [ ] |
-| Workflow | | | [ ] |
-| E2E Tests | | | [ ] |
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/scripts/postinstall.js

@@ -1,132 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script for @polymorphism-tech/morph-spec
- *
- * Checks if morph-spec is accessible in PATH and warns users
- * if it's not (common issue with nvm-windows).
- */
-
-import { execSync } from 'child_process';
-import { platform } from 'os';
-import chalk from 'chalk';
-
-const isWindows = platform() === 'win32';
-
-/**
- * Check if morph-spec command is in PATH
- */
-function isMorphSpecInPath() {
-  try {
-    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
-    execSync(command, { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect if nvm-windows is installed
- */
-function isUsingNvmWindows() {
-  if (!isWindows) return false;
-
-  try {
-    const path = process.env.PATH || '';
-    return path.includes('nvm4w') || path.includes('\\nvm\\');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get npm global prefix
- */
-function getNpmGlobalPrefix() {
-  try {
-    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
-    return prefix;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Show installation success message
- */
-function showSuccessMessage() {
-  console.log('');
-  console.log(chalk.green('✓ @polymorphism-tech/morph-spec installed successfully!'));
-  console.log('');
-  console.log(chalk.cyan('Quick start:'));
-  console.log(chalk.white('  morph-spec init'));
-  console.log(chalk.white('  morph-spec --help'));
-  console.log('');
-}
-
-/**
- * Show PATH warning for nvm-windows users
- */
-function showPathWarning() {
-  console.log('');
-  console.log(chalk.yellow('⚠ Warning: morph-spec command not found in PATH'));
-  console.log('');
-
-  if (isUsingNvmWindows()) {
-    console.log(chalk.white('You are using nvm-windows, which does not automatically add'));
-    console.log(chalk.white('npm global packages to your PATH.'));
-    console.log('');
-    console.log(chalk.cyan('Solution 1: Add npm global directory to PATH'));
-
-    const prefix = getNpmGlobalPrefix();
-    if (prefix) {
-      console.log(chalk.white(`  Add this to your PATH: ${chalk.yellow(prefix)}`));
-      console.log('');
-      console.log(chalk.gray('  PowerShell (as Administrator):'));
-      console.log(chalk.white(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
-      console.log('');
-      console.log(chalk.gray('  Or manually via System Properties > Environment Variables'));
-    }
-
-    console.log('');
-    console.log(chalk.cyan('Solution 2: Use npx (recommended)'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
-  } else {
-    console.log(chalk.white('The morph-spec command was not found in your PATH.'));
-    console.log('');
-    console.log(chalk.cyan('Solution: Use npx instead'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
-  }
-
-  console.log('');
-  console.log(chalk.gray('For more help, see: https://github.com/lucasPolymorphism/morph-spec-framework#troubleshooting'));
-  console.log('');
-}
-
-/**
- * Main postinstall check
- */
-function main() {
-  // Only show messages for global installs
-  // Skip for local installs (when used as dependency)
-  const isGlobalInstall = process.env.npm_config_global === 'true';
-
-  if (!isGlobalInstall) {
-    // Silent exit for local installs
-    return;
-  }
-
-  // Give npm a moment to set up the symlinks
-  setTimeout(() => {
-    if (isMorphSpecInPath()) {
-      showSuccessMessage();
-    } else {
-      showPathWarning();
-    }
-  }, 100);
-}
-
-main();

package/src/lib/stacks/index.js

@@ -1,7 +0,0 @@
-/**
- * Stack Resolution
- *
- * Utilities for detecting and resolving stack configurations (Blazor-Azure, Next.js-Supabase).
- */
-
-export * from '../stacks/stack-resolver.js';