@andre.buzeli/git-mcp 16.0.8 → 16.1.2

package/src/tools/git-help.js

@@ -1,284 +1,322 @@
-import { asToolResult } from "../utils/errors.js";
-
-/**
- * Tool de ajuda para AI Agents - fornece orientação sobre qual tool usar
- */
-export function createGitHelpTool() {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      query: {
-        type: "string",
-        description: "O que você quer fazer? Ex: 'criar repositório', 'fazer commit', 'criar branch'"
-      },
-      listTools: {
-        type: "boolean",
-        description: "Se true, lista todas as tools disponíveis com descrição resumida"
-      },
-      showFlows: {
-        type: "boolean",
-        description: "Se true, mostra fluxos de trabalho comuns"
-      }
-    },
-    additionalProperties: false
-  };
-
-  const TOOLS_SUMMARY = {
-    "git-workflow": {
-      purpose: "Operações básicas do dia-a-dia: init, status, add, commit, push, update (⭐ RECOMENDADO)",
-      actions: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update"],
-      useWhen: "Salvar e enviar mudanças. Use action='update' para fluxo automatizado completo (status → add → commit → push)"
-    },
-    "git-branches": {
-      purpose: "Gerenciar branches: criar, listar, trocar, deletar",
-      actions: ["list", "create", "checkout", "delete", "rename"],
-      useWhen: "Trabalhar em features isoladas, organizar desenvolvimento"
-    },
-    "git-merge": {
-      purpose: "Juntar branches após desenvolvimento",
-      actions: ["merge", "abort", "status"],
-      useWhen: "Integrar feature branch na main/develop"
-    },
-    "git-stash": {
-      purpose: "Salvar mudanças temporariamente sem commit",
-      actions: ["list", "save", "apply", "pop", "drop", "clear"],
-      useWhen: "Trocar de branch com mudanças não commitadas"
-    },
-    "git-tags": {
-      purpose: "Marcar versões/releases",
-      actions: ["list", "create", "delete", "push"],
-      useWhen: "Publicar versão (v1.0.0, v2.0.0)"
-    },
-    "git-history": {
-      purpose: "Ver histórico de commits",
-      actions: ["log"],
-      useWhen: "Encontrar commit específico, ver quem alterou o quê"
-    },
-    "git-diff": {
-      purpose: "Ver diferenças entre versões",
-      actions: ["show", "compare", "stat"],
-      useWhen: "Revisar mudanças antes de commit, comparar branches"
-    },
-    "git-reset": {
-      purpose: "Desfazer commits ou mudanças",
-      actions: ["soft", "mixed", "hard", "hard-clean"],
-      useWhen: "Desfazer último commit, limpar working directory"
-    },
-    "git-config": {
-      purpose: "Configurar Git (nome, email, etc)",
-      actions: ["get", "set", "unset", "list"],
-      useWhen: "Configurar autor dos commits"
-    },
-    "git-remote": {
-      purpose: "Operações em GitHub/Gitea",
-      actions: ["list", "ensure", "release-create", "topics-set", "label-create"],
-      useWhen: "Criar release, configurar repositório remoto"
-    },
-    "git-sync": {
-      purpose: "Sincronizar com remotes",
-      actions: ["fetch", "pull"],
-      useWhen: "Baixar mudanças de outros desenvolvedores"
-    },
-    "git-clone": {
-      purpose: "Clonar repositório existente",
-      actions: ["clone"],
-      useWhen: "Baixar projeto existente do GitHub/Gitea"
-    },
-    "git-ignore": {
-      purpose: "Gerenciar .gitignore",
-      actions: ["list", "create", "add", "remove"],
-      useWhen: "Ignorar arquivos (node_modules, .env, etc)"
-    },
-    "git-files": {
-      purpose: "Ler arquivos do histórico Git",
-      actions: ["list", "read"],
-      useWhen: "Ver arquivo em versão antiga"
-    },
-    "git-issues": {
-      purpose: "Gerenciar issues no GitHub/Gitea",
-      actions: ["create", "list", "comment"],
-      useWhen: "Reportar bugs, criar tarefas"
-    },
-    "git-pulls": {
-      purpose: "Gerenciar Pull Requests",
-      actions: ["create", "list", "files"],
-      useWhen: "Propor mudanças para review"
-    }
-  };
-
-  const COMMON_FLOWS = {
-    "novo-projeto": {
-      description: "Criar repositório do zero",
-      steps: [
-        { tool: "git-workflow", action: "init", note: "Inicializa git e cria repos no GitHub/Gitea" },
-        { tool: "git-workflow", action: "add", params: { files: ["."] } },
-        { tool: "git-workflow", action: "commit", params: { message: "Initial commit" } },
-        { tool: "git-workflow", action: "push" }
-      ]
-    },
-    "salvar-mudancas": {
-      description: "Salvar e enviar mudanças (fluxo automatizado)",
-      steps: [
-        { tool: "git-workflow", action: "update", params: { message: "sua mensagem" }, note: "⭐ Executa status, add, commit e push automaticamente" }
-      ]
-    },
-    "nova-feature": {
-      description: "Desenvolver feature em branch separada",
-      steps: [
-        { tool: "git-branches", action: "create", params: { branch: "feature/nome" } },
-        { tool: "git-branches", action: "checkout", params: { branch: "feature/nome" } },
-        { note: "... fazer mudanças ..." },
-        { tool: "git-workflow", action: "add" },
-        { tool: "git-workflow", action: "commit" },
-        { tool: "git-branches", action: "checkout", params: { branch: "main" } },
-        { tool: "git-merge", action: "merge", params: { branch: "feature/nome" } },
-        { tool: "git-workflow", action: "push" }
-      ]
-    },
-    "criar-release": {
-      description: "Publicar nova versão",
-      steps: [
-        { tool: "git-tags", action: "create", params: { tag: "v1.0.0", message: "Release v1.0.0" } },
-        { tool: "git-tags", action: "push", params: { tag: "v1.0.0" } },
-        { tool: "git-remote", action: "release-create", params: { tag: "v1.0.0", name: "v1.0.0" } }
-      ]
-    },
-    "desfazer-commit": {
-      description: "Desfazer último commit mantendo mudanças",
-      steps: [
-        { tool: "git-reset", action: "soft", params: { ref: "HEAD~1" } }
-      ]
-    },
-    "trocar-branch-com-mudancas": {
-      description: "Salvar mudanças e trocar de branch",
-      steps: [
-        { tool: "git-stash", action: "save", params: { message: "WIP" } },
-        { tool: "git-branches", action: "checkout", params: { branch: "outra-branch" } },
-        { note: "... fazer o que precisar ..." },
-        { tool: "git-branches", action: "checkout", params: { branch: "branch-original" } },
-        { tool: "git-stash", action: "pop" }
-      ]
-    }
-  };
-
-  // Mapeamento de intenções para tools
-  const INTENT_MAP = {
-    // Palavras-chave -> tool recomendada
-    "criar reposit": "git-workflow (action=init)",
-    "iniciar projeto": "git-workflow (action=init)",
-    "novo projeto": "git-workflow (action=init)",
-    "commit": "git-workflow (action=commit)",
-    "salvar": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
-    "atualizar": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
-    "update": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
-    "push": "git-workflow (action=push)",
-    "enviar": "git-workflow (action=push)",
-    "branch": "git-branches",
-    "criar branch": "git-branches (action=create)",
-    "trocar branch": "git-branches (action=checkout)",
-    "merge": "git-merge",
-    "juntar": "git-merge",
-    "stash": "git-stash",
-    "guardar": "git-stash (action=save)",
-    "tag": "git-tags",
-    "versão": "git-tags",
-    "release": "git-remote (action=release-create)",
-    "histórico": "git-history",
-    "log": "git-history",
-    "diff": "git-diff",
-    "diferença": "git-diff",
-    "desfazer": "git-reset",
-    "reset": "git-reset",
-    "clone": "git-clone",
-    "clonar": "git-clone",
-    "baixar projeto": "git-clone",
-    "issue": "git-issues",
-    "bug": "git-issues (action=create)",
-    "pull request": "git-pulls",
-    "pr": "git-pulls",
-    "ignorar": "git-ignore",
-    "gitignore": "git-ignore",
-    "config": "git-config",
-    "configurar": "git-config",
-    "status": "git-workflow (action=status)",
-    "ver mudanças": "git-workflow (action=status)"
-  };
-
-  const description = `Ajuda para AI Agents - descobre qual tool usar para cada situação.
-
-USE ESTA TOOL QUANDO:
-- Não sabe qual git-* tool usar
-- Precisa ver fluxos de trabalho comuns
-- Quer lista de todas as tools disponíveis
-
-EXEMPLOS:
-• { "query": "como criar um repositório?" }
-• { "listTools": true }
-• { "showFlows": true }`;
-
-  async function handle(args) {
-    const { query, listTools, showFlows } = args || {};
-
-    // Listar todas as tools
-    if (listTools) {
-      return asToolResult({
-        tools: TOOLS_SUMMARY,
-        tip: "Use query='o que você quer fazer' para recomendação específica"
-      });
-    }
-
-    // Mostrar fluxos comuns
-    if (showFlows) {
-      return asToolResult({
-        flows: COMMON_FLOWS,
-        tip: "Siga os steps em ordem para cada fluxo"
-      });
-    }
-
-    // Buscar por query
-    if (query) {
-      const q = query.toLowerCase();
-      const matches = [];
-
-      for (const [intent, tool] of Object.entries(INTENT_MAP)) {
-        if (q.includes(intent) || intent.includes(q)) {
-          matches.push({ intent, recommendation: tool });
-        }
-      }
-
-      if (matches.length > 0) {
-        return asToolResult({
-          query,
-          recommendations: matches,
-          tip: "Use a tool recomendada com os parâmetros indicados"
-        });
-      }
-
-      return asToolResult({
-        query,
-        message: "Não encontrei recomendação específica. Veja todas as tools:",
-        tools: Object.keys(TOOLS_SUMMARY),
-        tip: "Use listTools=true para ver detalhes de cada tool"
-      });
-    }
-
-    // Sem parâmetros - retornar overview
-    return asToolResult({
-      message: "Git MCP - Tools para AI Agents",
-      availableTools: Object.keys(TOOLS_SUMMARY).length,
-      usage: {
-        "Recomendação": "{ query: 'o que você quer fazer' }",
-        "Listar tools": "{ listTools: true }",
-        "Ver fluxos": "{ showFlows: true }"
-      },
-      quickStart: "Para começar um projeto: git-workflow com action='init'"
-    });
-  }
-
-  return {
-    name: "git-help",
-    description,
-    inputSchema,
-    handle
-  };
-}
+import { asToolResult } from "../utils/errors.js";
+
+/**
+ * Tool de ajuda para AI Agents - fornece orientação sobre qual tool usar
+ */
+export function createGitHelpTool() {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "O que você quer fazer? Ex: 'criar repositório', 'fazer commit', 'criar branch'"
+      },
+      listTools: {
+        type: "boolean",
+        description: "Se true, lista todas as tools disponíveis com descrição resumida"
+      },
+      showFlows: {
+        type: "boolean",
+        description: "Se true, mostra fluxos de trabalho comuns"
+      }
+    },
+    additionalProperties: false
+  };
+
+  const TOOLS_SUMMARY = {
+    "git-workflow": {
+      purpose: "Operações básicas do dia-a-dia: init, status, add, commit, push, update (⭐ RECOMENDADO)",
+      actions: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update"],
+      useWhen: "Salvar e enviar mudanças. Use action='update' para fluxo completo automatizado (status → add → commit → push)"
+    },
+    "git-worktree": {
+      purpose: "Gerenciar worktrees (multibranch)",
+      actions: ["add", "list", "remove", "setup", "set-channel"],
+      useWhen: "Trabalhar em múltiplas branches/plataformas simultaneamente no mesmo repo"
+    },
+    "git-branches": {
+      purpose: "Gerenciar branches: criar, listar, trocar, deletar",
+      actions: ["list", "create", "checkout", "delete", "rename"],
+      useWhen: "Trabalhar em features isoladas, organizar desenvolvimento"
+    },
+    "git-merge": {
+      purpose: "Juntar branches após desenvolvimento",
+      actions: ["merge", "abort", "status"],
+      useWhen: "Integrar feature branch na main/develop"
+    },
+    "git-stash": {
+      purpose: "Salvar mudanças temporariamente sem commit",
+      actions: ["list", "save", "apply", "pop", "drop", "clear"],
+      useWhen: "Trocar de branch com mudanças não commitadas"
+    },
+    "git-tags": {
+      purpose: "Marcar versões/releases",
+      actions: ["list", "create", "delete", "push"],
+      useWhen: "Publicar versão (v1.0.0, v2.0.0)"
+    },
+    "git-history": {
+      purpose: "Ver histórico de commits",
+      actions: ["log"],
+      useWhen: "Encontrar commit específico, ver quem alterou o quê"
+    },
+    "git-diff": {
+      purpose: "Ver diferenças entre versões",
+      actions: ["show", "compare", "stat"],
+      useWhen: "Revisar mudanças antes de commit, comparar branches"
+    },
+    "git-reset": {
+      purpose: "Desfazer commits ou mudanças",
+      actions: ["soft", "mixed", "hard", "hard-clean"],
+      useWhen: "Desfazer último commit, limpar working directory"
+    },
+    "git-config": {
+      purpose: "Configurar Git (nome, email, etc)",
+      actions: ["get", "set", "unset", "list"],
+      useWhen: "Configurar autor dos commits"
+    },
+    "git-remote": {
+      purpose: "Operações em GitHub/Gitea",
+      actions: ["list", "ensure", "release-create", "topics-set", "label-create"],
+      useWhen: "Criar release, configurar repositório remoto"
+    },
+    "git-sync": {
+      purpose: "Sincronizar com remotes",
+      actions: ["fetch", "pull"],
+      useWhen: "Baixar mudanças de outros desenvolvedores"
+    },
+    "git-clone": {
+      purpose: "Clonar repositório existente",
+      actions: ["clone"],
+      useWhen: "Baixar projeto existente do GitHub/Gitea"
+    },
+    "git-ignore": {
+      purpose: "Gerenciar .gitignore",
+      actions: ["list", "create", "add", "remove"],
+      useWhen: "Ignorar arquivos (node_modules, .env, etc)"
+    },
+    "git-files": {
+      purpose: "Ler arquivos do histórico Git",
+      actions: ["list", "read"],
+      useWhen: "Ver arquivo em versão antiga"
+    },
+    "git-issues": {
+      purpose: "Gerenciar issues no GitHub/Gitea",
+      actions: ["create", "list", "comment"],
+      useWhen: "Reportar bugs, criar tarefas"
+    },
+    "git-pulls": {
+      purpose: "Gerenciar Pull Requests",
+      actions: ["create", "list", "files"],
+      useWhen: "Propor mudanças para review"
+    }
+  };
+
+  const COMMON_FLOWS = {
+    "novo-projeto": {
+      description: "Criar repositório do zero",
+      steps: [
+        { tool: "git-workflow", action: "init", note: "Inicializa git e cria repos no GitHub/Gitea" },
+        { tool: "git-workflow", action: "add", params: { files: ["."] } },
+        { tool: "git-workflow", action: "commit", params: { message: "Initial commit" } },
+        { tool: "git-workflow", action: "push" }
+      ]
+    },
+    "salvar-mudancas": {
+      description: "Salvar e enviar mudanças (fluxo automatizado)",
+      steps: [
+        { tool: "git-workflow", action: "update", params: { message: "sua mensagem" }, note: "⭐ Executa status, add, commit e push automaticamente" }
+      ]
+    },
+    "nova-feature": {
+      description: "Desenvolver feature em branch separada",
+      steps: [
+        { tool: "git-branches", action: "create", params: { branch: "feature/nome" } },
+        { tool: "git-branches", action: "checkout", params: { branch: "feature/nome" } },
+        { note: "... fazer mudanças ..." },
+        { tool: "git-workflow", action: "add" },
+        { tool: "git-workflow", action: "commit" },
+        { tool: "git-branches", action: "checkout", params: { branch: "main" } },
+        { tool: "git-merge", action: "merge", params: { branch: "feature/nome" } },
+        { tool: "git-workflow", action: "push" }
+      ]
+    },
+    "criar-release": {
+      description: "Publicar nova versão",
+      steps: [
+        { tool: "git-tags", action: "create", params: { tag: "v1.0.0", message: "Release v1.0.0" } },
+        { tool: "git-tags", action: "push", params: { tag: "v1.0.0" } },
+        { tool: "git-remote", action: "release-create", params: { tag: "v1.0.0", name: "v1.0.0" } }
+      ]
+    },
+    "desfazer-commit": {
+      description: "Desfazer último commit mantendo mudanças",
+      steps: [
+        { tool: "git-reset", action: "soft", params: { ref: "HEAD~1" } }
+      ]
+    },
+    "trocar-branch-com-mudancas": {
+      description: "Salvar mudanças e trocar de branch",
+      steps: [
+        { tool: "git-stash", action: "save", params: { message: "WIP" } },
+        { tool: "git-branches", action: "checkout", params: { branch: "outra-branch" } },
+        { note: "... fazer o que precisar ..." },
+        { tool: "git-branches", action: "checkout", params: { branch: "branch-original" } },
+        { tool: "git-stash", action: "pop" }
+      ]
+    },
+    "multibranch-worktree": {
+      description: "Setup de ambiente multi-plataforma com worktrees",
+      steps: [
+        { tool: "git-worktree", action: "add", params: { branch: "mac", channel: "beta" } },
+        { tool: "git-worktree", action: "add", params: { branch: "win", channel: "production" } },
+        { tool: "git-workflow", action: "update", params: { message: "sync all", syncBranches: true }, note: "Propaga mudanças do principal para todos os worktrees" }
+      ]
+    }
+  };
+
+  const PROJECT_PATH_GUIDANCE = {
+    description: "Como obter o projectPath correto",
+    rule: "Use sempre o caminho absoluto do projeto sendo trabalhado no IDE",
+    howToFind: [
+      "No terminal do projeto: execute 'pwd' (Linux/Mac) ou 'cd' (Windows)",
+      "No IDE: copie o path mostrado na barra de título ou no explorador de arquivos",
+      "Exemplo Linux/Mac: '/home/usuario/meu-projeto'",
+      "Exemplo Windows: 'C:/Users/usuario/meu-projeto'"
+    ],
+    commonMistakes: [
+      "NÃO use o diretório home do usuário (ex: '/home/usuario' ou 'C:/Users/usuario')",
+      "NÃO use caminhos relativos (ex: './projeto' ou '../projeto')",
+      "NÃO omita o parâmetro — o servidor não consegue inferir o path automaticamente"
+    ]
+  };
+
+  // Mapeamento de intenções para tools
+  const INTENT_MAP = {
+    // Palavras-chave -> tool recomendada
+    "criar reposit": "git-workflow (action=init)",
+    "iniciar projeto": "git-workflow (action=init)",
+    "novo projeto": "git-workflow (action=init)",
+    "commit": "git-workflow (action=commit)",
+    "salvar": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
+    "atualizar": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
+    "update": "git-workflow (action=update) - ⭐ fluxo completo automatizado",
+    "push": "git-workflow (action=push)",
+    "enviar": "git-workflow (action=push)",
+    "branch": "git-branches",
+    "criar branch": "git-branches (action=create)",
+    "trocar branch": "git-branches (action=checkout)",
+    "merge": "git-merge",
+    "juntar": "git-merge",
+    "stash": "git-stash",
+    "guardar": "git-stash (action=save)",
+    "tag": "git-tags",
+    "versão": "git-tags",
+    "release": "git-remote (action=release-create)",
+    "histórico": "git-history",
+    "log": "git-history",
+    "diff": "git-diff",
+    "diferença": "git-diff",
+    "desfazer": "git-reset",
+    "reset": "git-reset",
+    "clone": "git-clone",
+    "clonar": "git-clone",
+    "baixar projeto": "git-clone",
+    "issue": "git-issues",
+    "bug": "git-issues (action=create)",
+    "pull request": "git-pulls",
+    "pr": "git-pulls",
+    "ignorar": "git-ignore",
+    "gitignore": "git-ignore",
+    "config": "git-config",
+    "configurar": "git-config",
+    "status": "git-workflow (action=status)",
+    "ver mudanças": "git-workflow (action=status)",
+    "worktree": "git-worktree",
+    "canal": "git-worktree (action=set-channel)",
+    "channel": "git-worktree (action=set-channel)",
+    "plataforma": "git-worktree (action=add)",
+    "sync branches": "git-workflow (action=update, syncBranches=true)",
+    "multibranch": "git-worktree"
+  };
+
+  const description = `Ajuda para AI Agents - descobre qual tool usar para cada situação.
+
+USE ESTA TOOL QUANDO:
+- Não sabe qual git-* tool usar
+- Precisa ver fluxos de trabalho comuns
+- Quer lista de todas as tools disponíveis
+
+EXEMPLOS:
+• { "query": "como criar um repositório?" }
+• { "listTools": true }
+• { "showFlows": true }`;
+
+  async function handle(args) {
+    const { query, listTools, showFlows } = args || {};
+
+    // Listar todas as tools
+    if (listTools) {
+      return asToolResult({
+        tools: TOOLS_SUMMARY,
+        projectPathGuidance: PROJECT_PATH_GUIDANCE,
+        tip: "Use query='o que você quer fazer' para recomendação específica"
+      });
+    }
+
+    // Mostrar fluxos comuns
+    if (showFlows) {
+      return asToolResult({
+        flows: COMMON_FLOWS,
+        tip: "Siga os steps em ordem para cada fluxo"
+      });
+    }
+
+    // Buscar por query
+    if (query) {
+      const q = query.toLowerCase();
+      const matches = [];
+
+      for (const [intent, tool] of Object.entries(INTENT_MAP)) {
+        if (q.includes(intent) || intent.includes(q)) {
+          matches.push({ intent, recommendation: tool });
+        }
+      }
+
+      if (matches.length > 0) {
+        return asToolResult({
+          query,
+          recommendations: matches,
+          tip: "Use a tool recomendada com os parâmetros indicados"
+        });
+      }
+
+      return asToolResult({
+        query,
+        message: "Não encontrei recomendação específica. Veja todas as tools:",
+        tools: Object.keys(TOOLS_SUMMARY),
+        tip: "Use listTools=true para ver detalhes de cada tool"
+      });
+    }
+
+    // Sem parâmetros - retornar overview
+    return asToolResult({
+      message: "Git MCP - Tools para AI Agents",
+      availableTools: Object.keys(TOOLS_SUMMARY).length,
+      projectPathGuidance: PROJECT_PATH_GUIDANCE,
+      usage: {
+        "Recomendação": "{ query: 'o que você quer fazer' }",
+        "Listar tools": "{ listTools: true }",
+        "Ver fluxos": "{ showFlows: true }"
+      },
+      quickStart: "Para começar um projeto: git-workflow com action='init'"
+    });
+  }
+
+  return {
+    name: "git-help",
+    description,
+    inputSchema,
+    handle,
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+  };
+}