@andrebuzeli/git-mcp 3.4.0 → 4.0.3

package/EXEMPLOS.md

@@ -0,0 +1,861 @@
+# 🚀 EXEMPLOS PRÁTICOS - MCP Git AI Unification Server
+
+## 📋 Casos de Uso Reais
+
+### 1. Inicialização de Projeto Novo
+
+```json
+// git-workflow init - Começar projeto do zero
+{
+  "action": "init",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Inicialização do projeto React com TypeScript"
+}
+```
+
+**Resultado esperado:**
+```json
+{
+  "success": true,
+  "action": "init",
+  "message": "Projeto inicializado com sucesso - repositório criado, remotes configurados",
+  "autoDetected": {
+    "repo": "meu-app",
+    "owner": "johndoe",
+    "providers": ["gitea"]
+  }
+}
+```
+
+### 2. Desenvolvimento Diário - Commit + Push
+
+```json
+// git-workflow commit - Após implementar uma feature
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Implementar autenticação JWT\n\n- Adicionar middleware de validação\n- Criar endpoints /login e /register\n- Implementar refresh token\n- Adicionar testes unitários"
+}
+```
+
+### 3. Sincronização Antes de Trabalhar
+
+```json
+// git-workflow sync - Atualizar com mudanças do time
+{
+  "action": "sync",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+### 4. Verificar Status do Projeto
+
+```json
+// git-workflow status - Overview completo
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+```
+
+**Output inclui:**
+- Status Git (modified, untracked, staged)
+- Branches locais/remotas
+- Últimos commits
+- Status de sincronização com providers
+
+### 5. Backup Estratégico
+
+```json
+// git-workflow backup - Antes de mudanças arriscadas
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Backup antes de refatoração da API"
+}
+```
+
+---
+
+## 📁 Gerenciamento de Arquivos
+
+### Criar Arquivo de Componente
+
+```json
+// git-files write - Novo componente React
+{
+  "action": "write",
+  "projectPath": "C:\\projetos\\meu-app",
+  "filePath": "src/components/LoginForm.tsx",
+  "content": "import React, { useState } from 'react';
+
+interface LoginFormProps {
+  onLogin: (credentials: {email: string, password: string}) => void;
+}
+
+export const LoginForm: React.FC<LoginFormProps> = ({ onLogin }) => {
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    onLogin({ email, password });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type=\"email\"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder=\"Email\"
+        required
+      />
+      <input
+        type=\"password\"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder=\"Senha\"
+        required
+      />
+      <button type=\"submit\">Entrar</button>
+    </form>
+  );
+};"
+}
+```
+
+### Buscar Funções no Código
+
+```json
+// git-files search - Encontrar todas as funções de validação
+{
+  "action": "search",
+  "projectPath": "C:\\projetos\\meu-app",
+  "query": "function.*validate|const.*validate",
+  "path": "src",
+  "caseSensitive": false
+}
+```
+
+### Backup de Arquivos de Configuração
+
+```json
+// git-files backup-files - Salvar configs importantes
+{
+  "action": "backup-files",
+  "projectPath": "C:\\projetos\\meu-app",
+  "patterns": ["*.json", "*.config.*", ".env*"],
+  "description": "Backup de arquivos de configuração"
+}
+```
+
+---
+
+## 🚀 Gerenciamento de Releases
+
+### Release Patch (Correção de Bug)
+
+```json
+// git-release create - Release automático de correção
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "changelog": true,
+  "notes": "Correção crítica no sistema de login",
+  "assets": ["dist/app.js", "dist/styles.css"]
+}
+```
+
+**Output:**
+- Versão automaticamente incrementada (ex: v1.2.3)
+- Changelog gerado automaticamente
+- Publicação em todos os providers configurados
+
+### Bump de Versão Manual
+
+```json
+// git-release version - Preparar para release major
+{
+  "action": "version",
+  "projectPath": "C:\\projetos\\meu-app",
+  "type": "major"
+}
+```
+
+### Rollback de Emergência
+
+```json
+// git-release rollback - Reverter release problemático
+{
+  "action": "rollback",
+  "projectPath": "C:\\projetos\\meu-app",
+  "createBackup": true
+}
+```
+
+---
+
+## 📊 Monitoramento e Analytics
+
+### Status Completo do Projeto
+
+```json
+// git-monitor status - Dashboard completo
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app",
+  "includeMetrics": true,
+  "detailed": true
+}
+```
+
+**Métricas incluídas:**
+- Commits por dia/semana
+- Arquivos modificados
+- Branches ativas
+- Tamanho do repositório
+- Status de sincronização
+
+### Análise de Produtividade
+
+```json
+// git-monitor metrics - Métricas de desenvolvimento
+{
+  "action": "metrics",
+  "projectPath": "C:\\projetos\\meu-app",
+  "period": "30d",
+  "includeCharts": true
+}
+```
+
+### Check-up de Saúde
+
+```json
+// git-monitor health - Diagnóstico de problemas
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "deep": true,
+  "suggestions": true
+}
+```
+
+---
+
+## 💾 Sistema de Backup
+
+### Backup Completo
+
+```json
+// git-backup create - Backup full do projeto
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "type": "full",
+  "name": "backup-semanal",
+  "compress": true,
+  "includeUntracked": true
+}
+```
+
+### Restauração Seletiva
+
+```json
+// git-backup restore - Restaurar versão específica
+{
+  "action": "restore",
+  "projectPath": "C:\\projetos\\meu-app",
+  "backupId": "backup-2025-09-25-full",
+  "preview": true,
+  "targetPath": "C:\\restauracao\\meu-app"
+}
+```
+
+### Backup Automático
+
+```json
+// git-backup auto - Configurar backup diário
+{
+  "action": "auto",
+  "projectPath": "C:\\projetos\\meu-app",
+  "enabled": true,
+  "schedule": "daily",
+  "retention": 30,
+  "maxBackups": 10
+}
+```
+
+---
+
+## 🌿 Gerenciamento de Branches
+
+### Feature Branch Completo
+
+```json
+// 1. Criar feature branch
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/user-authentication"
+}
+
+// 2. Trabalhar na feature (usar outras tools)
+
+// 3. Comparar com main antes do merge
+{
+  "action": "compare",
+  "projectPath": "C:\\projetos\\meu-app",
+  "base": "main",
+  "head": "feature/user-authentication",
+  "detailed": true
+}
+
+// 4. Merge inteligente
+{
+  "action": "merge",
+  "projectPath": "C:\\projetos\\meu-app",
+  "branch": "feature/user-authentication",
+  "strategy": "squash"
+}
+
+// 5. Limpar branch
+{
+  "action": "delete",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/user-authentication"
+}
+```
+
+### Hotfix Urgente
+
+```json
+// Criar hotfix branch
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "hotfix/critical-security-patch",
+  "from": "main"
+}
+
+// Implementar correção (usar git-files, git-workflow)
+
+// Merge direto na main
+{
+  "action": "switch",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "main"
+}
+
+{
+  "action": "merge",
+  "projectPath": "C:\\projetos\\meu-app",
+  "branch": "hotfix/critical-security-patch",
+  "strategy": "merge"
+}
+```
+
+---
+
+## 📝 Sistema de Issues Local
+
+### Criar Issue Estruturada
+
+```json
+// git-issues create - Nova feature
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "title": "Implementar sistema de notificações push",
+  "description": "Adicionar notificações em tempo real para ações do usuário",
+  "labels": ["feature", "frontend", "backend"],
+  "priority": "high",
+  "assignee": "johndoe",
+  "dueDate": "2025-10-15"
+}
+```
+
+### Auto-detecção de TODOs
+
+```json
+// git-issues scan - Converter TODOs em issues
+{
+  "action": "scan",
+  "projectPath": "C:\\projetos\\meu-app",
+  "createIssues": true,
+  "patterns": ["TODO", "FIXME", "HACK", "XXX"]
+}
+```
+
+**Converte automaticamente:**
+```javascript
+// TODO: Implementar validação de email
+// FIXME: Corrigir bug no login mobile
+```
+**Em issues estruturadas com:**
+- Título extraído do comentário
+- Prioridade baseada no tipo (TODO=medium, FIXME=high)
+- Localização do arquivo
+- Labels apropriadas
+
+### Gerenciamento de Sprint
+
+```json
+// Listar issues da sprint atual
+{
+  "action": "list",
+  "projectPath": "C:\\projetos\\meu-app",
+  "state": "open",
+  "sort": "priority",
+  "limit": 20
+}
+
+// Atualizar progresso
+{
+  "action": "update",
+  "projectPath": "C:\\projetos\\meu-app",
+  "id": "ISSUE-123",
+  "status": "in_progress"
+}
+
+// Fechar issue completa
+{
+  "action": "close",
+  "projectPath": "C:\\projetos\\meu-app",
+  "id": "ISSUE-123",
+  "comment": "Implementação concluída com testes unitários"
+}
+```
+
+---
+
+## 🏷️ Gerenciamento de Tags
+
+### Versionamento Semântico
+
+```json
+// Tag de release
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "v2.1.0",
+  "message": "Release v2.1.0 - Sistema de notificações\n\nFeatures:\n- Notificações push em tempo real\n- Configurações de preferências\n- Suporte a múltiplos idiomas\n\nBugfixes:\n- Correção de memory leak\n- Validação de formulários aprimorada",
+  "type": "annotated"
+}
+
+// Tag de pré-release
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "v2.1.0-beta.1",
+  "message": "Beta release para testes",
+  "type": "annotated"
+}
+```
+
+### Busca de Tags
+
+```json
+// Encontrar releases de produção
+{
+  "action": "search",
+  "projectPath": "C:\\projetos\\meu-app",
+  "query": "^v\\d+\\.\\d+\\.\\d+$",
+  "sort": "version"
+}
+```
+
+---
+
+## 💾 Gerenciamento de Stash
+
+### Work in Progress (WIP)
+
+```json
+// Salvar trabalho em andamento
+{
+  "action": "save",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "WIP: Refatoração da API de usuários",
+  "includeUntracked": true,
+  "keepIndex": true
+}
+
+// Ver stashes disponíveis
+{
+  "action": "list",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+
+// Aplicar stash específico
+{
+  "action": "apply",
+  "projectPath": "C:\\projetos\\meu-app",
+  "index": "1"
+}
+```
+
+### Context Switching
+
+```json
+// Salvar contexto atual
+{
+  "action": "save",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "Context: Implementação do dashboard"
+}
+
+// Mudar para hotfix urgente
+// ... trabalhar no hotfix ...
+
+// Retornar ao contexto anterior
+{
+  "action": "pop",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+---
+
+## 🔧 Configuração e Remotos
+
+### Setup Inicial de Remotos
+
+```json
+// Adicionar remote do Gitea
+{
+  "action": "add",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "origin",
+  "url": "https://gitea.example.com/johndoe/meu-app.git",
+  "provider": "gitea"
+}
+
+// Adicionar backup no GitHub
+{
+  "action": "add",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "github",
+  "url": "https://github.com/johndoe/meu-app.git",
+  "provider": "github"
+}
+```
+
+### Sincronização Multi-Provider
+
+```json
+// Verificar status de todos os remotos
+{
+  "action": "show",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+
+// Limpar referências obsoletas
+{
+  "action": "prune",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+---
+
+## 🚨 Tratamento de Erros e Recovery
+
+### Exemplo de Auto-Recovery
+
+```json
+// Request que pode falhar
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Nova funcionalidade"
+}
+```
+
+**Response com erro e sugestão:**
+```json
+{
+  "success": false,
+  "action": "commit",
+  "message": "Falha no commit",
+  "error": {
+    "code": "GIT_PUSH_FAILED",
+    "message": "Não foi possível fazer push para o remote",
+    "cause": "Remote 'origin' não encontrado ou sem permissão",
+    "suggestion": "Execute 'git remote add origin <url>' ou verifique as credenciais"
+  },
+  "autoDetected": {
+    "repo": "meu-app",
+    "owner": "johndoe",
+    "providers": []
+  }
+}
+```
+
+### Recovery Automático
+
+```json
+// Sistema tenta corrigir automaticamente
+{
+  "action": "sync",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+```
+
+**Output:**
+- Detecta problema
+- Tenta `git pull --rebase`
+- Se falhar, sugere resolução manual
+- Backup automático antes de operações arriscadas
+
+---
+
+## 🎯 Workflows Completos
+
+### Workflow de Desenvolvimento Diário
+
+```json
+// 1. Sincronizar com time
+{
+  "action": "sync",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+
+// 2. Ver status
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+
+// 3. Criar feature branch
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/dark-mode"
+}
+
+// 4. Implementar (usar git-files, etc.)
+
+// 5. Commit progressivo
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Implementar tema dark\n\n- Adicionar variáveis CSS\n- Toggle component\n- Persistir preferência"
+}
+
+// 6. Verificar qualidade
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app"
+}
+
+// 7. Merge na main
+{
+  "action": "merge",
+  "projectPath": "C:\\projetos\\meu-app",
+  "branch": "feature/dark-mode"
+}
+```
+
+### Workflow de Release
+
+```json
+// 1. Verificar saúde pré-release
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "deep": true
+}
+
+// 2. Backup estratégico
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Backup pré-release v2.0.0"
+}
+
+// 3. Bump versão
+{
+  "action": "version",
+  "projectPath": "C:\\projetos\\meu-app",
+  "type": "minor"
+}
+
+// 4. Release completo
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "changelog": true,
+  "notes": "Major release com redesign completo",
+  "assets": ["dist/bundle.js", "dist/styles.css"]
+}
+
+// 5. Tag de versão
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "v2.0.0",
+  "type": "annotated",
+  "message": "Release v2.0.0 - Redesign completo da interface"
+}
+```
+
+### Workflow de Troubleshooting
+
+```json
+// 1. Diagnosticar problema
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\meu-app",
+  "detailed": true
+}
+
+// 2. Verificar saúde
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "suggestions": true
+}
+
+// 3. Backup antes de mudanças
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Backup antes de troubleshooting"
+}
+
+// 4. Reset se necessário
+{
+  "action": "reset-to-commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "commit": "HEAD~1",
+  "type": "mixed"
+}
+
+// 5. Limpar stashes se houver
+{
+  "action": "clear",
+  "projectPath": "C:\\projetos\\meu-app",
+  "confirm": true
+}
+```
+
+---
+
+## 🔧 Configurações Avançadas
+
+### Ambiente de Desenvolvimento
+
+```bash
+# .env file
+GITEA_USERNAME=developer
+GITEA_TOKEN=your_personal_token
+GITEA_URL=https://gitea.company.com
+
+GITHUB_USERNAME=developer
+GITHUB_TOKEN=your_github_token
+
+# Optional
+DEMO_MODE=false
+LOG_LEVEL=debug
+```
+
+### Configuração Multi-Projeto
+
+```json
+// Para projetos diferentes, apenas mude o projectPath
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\api-backend"
+}
+
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\web-frontend"
+}
+
+{
+  "action": "status",
+  "projectPath": "C:\\projetos\\mobile-app"
+}
+```
+
+---
+
+## 💡 Dicas e Boas Práticas
+
+### 1. Commits Atômicos
+```json
+// ❌ Ruim
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "Update"
+}
+
+// ✅ Bom
+{
+  "action": "commit",
+  "projectPath": "C:\\projetos\\meu-app",
+  "message": "feat: Adicionar validação de formulário\n\n- Campo email obrigatório\n- Validação de formato\n- Mensagens de erro localizadas\n- Testes unitários incluídos"
+}
+```
+
+### 2. Branches por Feature
+```json
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "feature/user-profile-page"
+}
+
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "bugfix/login-validation"
+}
+
+{
+  "action": "create",
+  "projectPath": "C:\\projetos\\meu-app",
+  "name": "refactor/api-cleanup"
+}
+```
+
+### 3. Backups Estratégicos
+```json
+// Antes de mudanças arriscadas
+{
+  "action": "backup",
+  "projectPath": "C:\\projetos\\meu-app",
+  "description": "Antes de refatoração da arquitetura"
+}
+
+// Backups automáticos
+{
+  "action": "auto",
+  "projectPath": "C:\\projetos\\meu-app",
+  "enabled": true,
+  "schedule": "commit"
+}
+```
+
+### 4. Monitoramento Contínuo
+```json
+// Status diário
+{
+  "action": "metrics",
+  "projectPath": "C:\\projetos\\meu-app",
+  "period": "7d"
+}
+
+// Health checks
+{
+  "action": "health",
+  "projectPath": "C:\\projetos\\meu-app",
+  "suggestions": true
+}
+```