@andrebuzeli/git-mcp 15.8.3 → 15.8.5

package/src/utils/errors.js

@@ -1,431 +1,431 @@
-// Sistema de Erros Melhorado para AI Agents
-
-export class MCPError extends Error {
-  constructor(code, message, data) {
-    super(message);
-    this.code = code;
-    this.data = data;
-  }
-}
-
-// Códigos de erro padronizados com sugestões para AI
-export const ERROR_CODES = {
-  // Auth
-  AUTH_GITHUB_INVALID: {
-    code: "AUTH_GITHUB_INVALID",
-    suggestion: "Verifique se GITHUB_TOKEN está configurado e é válido. Gere um novo token em github.com/settings/tokens"
-  },
-  AUTH_GITEA_INVALID: {
-    code: "AUTH_GITEA_INVALID", 
-    suggestion: "Verifique se GITEA_TOKEN e GITEA_URL estão configurados corretamente"
-  },
-  AUTH_NO_PERMISSION: {
-    code: "AUTH_NO_PERMISSION",
-    suggestion: "Token não tem permissão para esta operação. Verifique os scopes do token"
-  },
-  
-  // Repo
-  REPO_NOT_FOUND: {
-    code: "REPO_NOT_FOUND",
-    suggestion: "Repositório não existe. Use action='init' com createIfMissing=true para criar"
-  },
-  REPO_NO_WRITE: {
-    code: "REPO_NO_WRITE",
-    suggestion: "Sem permissão de escrita. Verifique se você é owner ou colaborador do repositório"
-  },
-  REPO_ALREADY_EXISTS: {
-    code: "REPO_ALREADY_EXISTS",
-    suggestion: "Repositório já existe. Use action='ensure' para verificar ou escolha outro nome"
-  },
-  
-  // Git Local
-  NOT_A_GIT_REPO: {
-    code: "NOT_A_GIT_REPO",
-    suggestion: "Diretório não é um repositório git. Use action='init' primeiro para inicializar"
-  },
-  NO_COMMITS: {
-    code: "NO_COMMITS",
-    suggestion: "Repositório não tem commits. Use action='add' e depois action='commit' primeiro"
-  },
-  NOTHING_TO_COMMIT: {
-    code: "NOTHING_TO_COMMIT",
-    suggestion: "Working tree limpa, nada para commitar. Modifique arquivos primeiro"
-  },
-  NOTHING_TO_PUSH: {
-    code: "NOTHING_TO_PUSH",
-    suggestion: "Nenhuma mudança para push. Faça commits primeiro"
-  },
-  
-  // Branches
-  BRANCH_NOT_FOUND: {
-    code: "BRANCH_NOT_FOUND",
-    suggestion: "Branch não existe. Use action='list' para ver branches disponíveis"
-  },
-  BRANCH_ALREADY_EXISTS: {
-    code: "BRANCH_ALREADY_EXISTS",
-    suggestion: "Branch já existe. Use outro nome ou delete a existente primeiro"
-  },
-  CANNOT_DELETE_CURRENT: {
-    code: "CANNOT_DELETE_CURRENT",
-    suggestion: "Não pode deletar branch atual. Faça checkout para outra branch primeiro"
-  },
-  
-  // Tags
-  TAG_NOT_FOUND: {
-    code: "TAG_NOT_FOUND",
-    suggestion: "Tag não existe. Use action='list' para ver tags disponíveis"
-  },
-  TAG_ALREADY_EXISTS: {
-    code: "TAG_ALREADY_EXISTS",
-    suggestion: "Tag já existe. Use outro nome ou delete a existente primeiro"
-  },
-  
-  // Refs
-  REF_NOT_FOUND: {
-    code: "REF_NOT_FOUND",
-    suggestion: "Referência não encontrada. Verifique se o commit/branch/tag existe. Use action='log' para ver histórico"
-  },
-  INSUFFICIENT_HISTORY: {
-    code: "INSUFFICIENT_HISTORY",
-    suggestion: "Histórico insuficiente para HEAD~N. Use action='log' para verificar quantos commits existem"
-  },
-  
-  // Stash
-  NOTHING_TO_STASH: {
-    code: "NOTHING_TO_STASH",
-    suggestion: "Working tree limpa, nada para stash. Modifique arquivos primeiro"
-  },
-  STASH_NOT_FOUND: {
-    code: "STASH_NOT_FOUND",
-    suggestion: "Stash não encontrado. Use action='list' para ver stashes disponíveis"
-  },
-  
-  // Remote
-  REMOTE_NOT_FOUND: {
-    code: "REMOTE_NOT_FOUND",
-    suggestion: "Remote não configurado. Use action='ensure-remotes' para configurar"
-  },
-  PUSH_REJECTED: {
-    code: "PUSH_REJECTED",
-    suggestion: "Push rejeitado (histórico divergente). Use force=true para forçar, ou faça pull primeiro"
-  },
-  MERGE_CONFLICT: {
-    code: "MERGE_CONFLICT",
-    suggestion: "Conflito de merge. Resolva conflitos manualmente e faça novo commit"
-  },
-  
-  // Network
-  NETWORK_TIMEOUT: {
-    code: "NETWORK_TIMEOUT",
-    suggestion: "Timeout de conexão. Verifique sua internet e tente novamente"
-  },
-  RATE_LIMIT: {
-    code: "RATE_LIMIT",
-    suggestion: "Rate limit excedido. Aguarde alguns minutos antes de tentar novamente"
-  },
-  
-  // Validation
-  VALIDATION_ERROR: {
-    code: "VALIDATION_ERROR",
-    suggestion: "Parâmetros inválidos. Verifique os parâmetros obrigatórios da action"
-  },
-  MISSING_PARAMETER: {
-    code: "MISSING_PARAMETER",
-    suggestion: "Parâmetro obrigatório faltando"
-  },
-  
-  // Files
-  FILE_NOT_FOUND: {
-    code: "FILE_NOT_FOUND",
-    suggestion: "Arquivo não encontrado no repositório. Use action='list' para ver arquivos disponíveis"
-  },
-  
-  // Issues/PRs
-  ISSUE_NOT_FOUND: {
-    code: "ISSUE_NOT_FOUND",
-    suggestion: "Issue não encontrada. Use action='list' para ver issues disponíveis"
-  },
-  PR_NOT_FOUND: {
-    code: "PR_NOT_FOUND",
-    suggestion: "Pull Request não encontrado. Use action='list' para ver PRs disponíveis"
-  },
-  
-  // Filesystem
-  DISK_FULL: {
-    code: "DISK_FULL",
-    suggestion: "Disco cheio. Libere espaço e tente novamente"
-  },
-  FILE_TOO_LARGE: {
-    code: "FILE_TOO_LARGE",
-    suggestion: "Arquivo muito grande para Git. Considere usar Git LFS para arquivos grandes"
-  },
-  PERMISSION_DENIED_FS: {
-    code: "PERMISSION_DENIED_FS",
-    suggestion: "Sem permissão para acessar arquivo/diretório. Verifique permissões do sistema de arquivos"
-  },
-  
-  // Git Corruption
-  GIT_CORRUPTED: {
-    code: "GIT_CORRUPTED",
-    suggestion: "Repositório Git corrompido. Tente: 1) git fsck --full, 2) git gc --prune=now, ou 3) re-clone do remote"
-  },
-  GIT_LOCK_FILE: {
-    code: "GIT_LOCK_FILE",
-    suggestion: "Arquivo de lock presente (.git/index.lock). Outro processo git pode estar rodando. Se não, delete o arquivo de lock manualmente"
-  },
-  
-  // Remote/URL
-  INVALID_REMOTE_URL: {
-    code: "INVALID_REMOTE_URL",
-    suggestion: "URL do remote inválida. Verifique o formato: https://github.com/user/repo.git ou git@github.com:user/repo.git"
-  },
-  REMOTE_UNREACHABLE: {
-    code: "REMOTE_UNREACHABLE",
-    suggestion: "Remote inacessível. Verifique: 1) URL está correta, 2) conexão de internet, 3) firewall/proxy"
-  },
-  SSL_ERROR: {
-    code: "SSL_ERROR",
-    suggestion: "Erro de SSL/TLS. Verifique certificados ou use http.sslVerify=false (não recomendado)"
-  },
-  
-  // Generic
-  UNKNOWN_ERROR: {
-    code: "UNKNOWN_ERROR",
-    suggestion: "Erro desconhecido. Verifique os logs para mais detalhes"
-  }
-};
-
-// Função para criar erro com sugestão
-export function createError(errorCode, details = {}) {
-  const errorInfo = ERROR_CODES[errorCode] || ERROR_CODES.UNKNOWN_ERROR;
-  return new MCPError(errorInfo.code, details.message || errorInfo.code, {
-    suggestion: errorInfo.suggestion,
-    ...details
-  });
-}
-
-// Função para mapear erros externos para códigos internos
-export function mapExternalError(error, context = {}) {
-  const msg = error?.message?.toLowerCase() || String(error).toLowerCase();
-  
-  // GitHub/Gitea API errors
-  if (msg.includes("bad credentials") || msg.includes("401")) {
-    return context.provider === "gitea" 
-      ? createError("AUTH_GITEA_INVALID", { originalError: msg })
-      : createError("AUTH_GITHUB_INVALID", { originalError: msg });
-  }
-  
-  if (msg.includes("not found") || msg.includes("404")) {
-    if (context.type === "repo") return createError("REPO_NOT_FOUND", { repo: context.repo, originalError: msg });
-    if (context.type === "branch") return createError("BRANCH_NOT_FOUND", { branch: context.branch, originalError: msg });
-    if (context.type === "tag") return createError("TAG_NOT_FOUND", { tag: context.tag, originalError: msg });
-    if (context.type === "file") return createError("FILE_NOT_FOUND", { file: context.file, originalError: msg });
-    if (context.type === "issue") return createError("ISSUE_NOT_FOUND", { number: context.number, originalError: msg });
-    if (context.type === "pr") return createError("PR_NOT_FOUND", { number: context.number, originalError: msg });
-    return createError("REF_NOT_FOUND", { ref: context.ref, originalError: msg });
-  }
-  
-  if (msg.includes("permission") || msg.includes("403") || msg.includes("forbidden")) {
-    return createError("AUTH_NO_PERMISSION", { originalError: msg });
-  }
-  
-  if (msg.includes("rate limit") || msg.includes("429")) {
-    return createError("RATE_LIMIT", { originalError: msg });
-  }
-  
-  if (msg.includes("timeout") || msg.includes("etimedout") || msg.includes("econnrefused")) {
-    return createError("NETWORK_TIMEOUT", { originalError: msg });
-  }
-  
-  if (msg.includes("push rejected") || msg.includes("non-fast-forward")) {
-    return createError("PUSH_REJECTED", { originalError: msg });
-  }
-  
-  if (msg.includes("conflict")) {
-    return createError("MERGE_CONFLICT", { originalError: msg });
-  }
-  
-  if (msg.includes("already exists")) {
-    if (context.type === "repo") return createError("REPO_ALREADY_EXISTS", { repo: context.repo, originalError: msg });
-    if (context.type === "branch") return createError("BRANCH_ALREADY_EXISTS", { branch: context.branch, originalError: msg });
-    if (context.type === "tag") return createError("TAG_ALREADY_EXISTS", { tag: context.tag, originalError: msg });
-    return createError("BRANCH_ALREADY_EXISTS", { originalError: msg });
-  }
-  
-  // isomorphic-git specific errors
-  if (msg.includes("could not find") && msg.includes("head~")) {
-    return createError("INSUFFICIENT_HISTORY", { originalError: msg });
-  }
-  
-  if (msg.includes("is not a git repository") || msg.includes("could not find .git")) {
-    return createError("NOT_A_GIT_REPO", { path: context.path, originalError: msg });
-  }
-  
-  if (msg.includes("nothing to commit") || msg.includes("working tree clean")) {
-    return createError("NOTHING_TO_COMMIT", { originalError: msg });
-  }
-  
-  if (msg.includes("could not resolve ref") || msg.includes("invalid reference")) {
-    return createError("REF_NOT_FOUND", { originalError: msg });
-  }
-  
-  if (msg.includes("branch") && (msg.includes("does not exist") || msg.includes("not found"))) {
-    return createError("BRANCH_NOT_FOUND", { originalError: msg });
-  }
-  
-  if (msg.includes("tag") && (msg.includes("does not exist") || msg.includes("not found"))) {
-    return createError("TAG_NOT_FOUND", { originalError: msg });
-  }
-  
-  if (msg.includes("no commits") || msg.includes("unknown revision")) {
-    return createError("NO_COMMITS", { originalError: msg });
-  }
-  
-  if (msg.includes("nada para stash") || msg.includes("nothing to stash") || msg.includes("no local changes")) {
-    return createError("NOTHING_TO_STASH", { originalError: msg });
-  }
-  
-  if (msg.includes("stash") && (msg.includes("not found") || msg.includes("não encontrado"))) {
-    return createError("STASH_NOT_FOUND", { originalError: msg });
-  }
-  
-  if (msg.includes("author") || msg.includes("committer")) {
-    return createError("VALIDATION_ERROR", { 
-      message: "Configure user.name e user.email", 
-      suggestion: "Use git-config para configurar ou forneça tokens de provider",
-      originalError: msg 
-    });
-  }
-  
-  // Filesystem errors
-  if (msg.includes("enospc") || msg.includes("no space left") || msg.includes("disk full")) {
-    return createError("DISK_FULL", { originalError: msg });
-  }
-  
-  if (msg.includes("file too large") || msg.includes("exceeds") || msg.includes("size limit")) {
-    return createError("FILE_TOO_LARGE", { originalError: msg });
-  }
-  
-  if (msg.includes("eacces") || msg.includes("eperm") || (msg.includes("permission") && msg.includes("denied"))) {
-    return createError("PERMISSION_DENIED_FS", { originalError: msg });
-  }
-  
-  // Git corruption
-  if (msg.includes("corrupt") || msg.includes("bad object") || msg.includes("broken") || 
-      msg.includes("missing object") || msg.includes("invalid sha") || msg.includes("fatal: packed")) {
-    return createError("GIT_CORRUPTED", { originalError: msg });
-  }
-  
-  if (msg.includes(".git/index.lock") || msg.includes("unable to create") && msg.includes("lock")) {
-    return createError("GIT_LOCK_FILE", { originalError: msg });
-  }
-  
-  // Remote/URL errors
-  if (msg.includes("invalid url") || msg.includes("malformed") || msg.includes("not a valid")) {
-    return createError("INVALID_REMOTE_URL", { originalError: msg });
-  }
-  
-  if (msg.includes("could not resolve host") || msg.includes("name resolution") || 
-      msg.includes("no address") || msg.includes("unreachable")) {
-    return createError("REMOTE_UNREACHABLE", { originalError: msg });
-  }
-  
-  if (msg.includes("ssl") || msg.includes("certificate") || msg.includes("tls")) {
-    return createError("SSL_ERROR", { originalError: msg });
-  }
-  
-  // Generic fallback
-  return createError("UNKNOWN_ERROR", { originalError: msg, context });
-}
-
-// ============ NEXT ACTIONS PARA AI AGENTS ============
-// Mapeia ação atual para próxima ação sugerida
-export const NEXT_ACTIONS = {
-  // git-workflow
-  "workflow:init": { tool: "git-workflow", action: "add", hint: "Adicione arquivos ao staging com files=['.']" },
-  "workflow:status": { tool: "git-workflow", action: "add", hint: "Se há arquivos modificados, adicione-os ao staging" },
-  "workflow:add": { tool: "git-workflow", action: "commit", hint: "Crie um commit com uma mensagem descritiva" },
-  "workflow:commit": { tool: "git-workflow", action: "push", hint: "Envie as mudanças para GitHub/Gitea" },
-  "workflow:push": null, // Fluxo completo
-  
-  // git-branches
-  "branches:create": { tool: "git-branches", action: "checkout", hint: "Mude para a nova branch criada" },
-  "branches:checkout": { tool: "git-workflow", action: "status", hint: "Verifique o estado da branch" },
-  "branches:delete": null,
-  
-  // git-stash
-  "stash:save": { tool: "git-branches", action: "checkout", hint: "Agora pode trocar de branch com segurança" },
-  "stash:pop": { tool: "git-workflow", action: "status", hint: "Verifique as mudanças restauradas" },
-  
-  // git-merge
-  "merge:merge": { tool: "git-workflow", action: "push", hint: "Envie o merge para os remotes" },
-  
-  // git-tags
-  "tags:create": { tool: "git-tags", action: "push", hint: "Envie a tag para os remotes" },
-  "tags:push": null,
-  
-  // git-remote
-  "remote:ensure": { tool: "git-workflow", action: "push", hint: "Agora pode fazer push" },
-  "remote:release-create": null,
-  
-  // git-sync
-  "sync:pull": { tool: "git-workflow", action: "status", hint: "Verifique mudanças após pull" },
-  "sync:fetch": { tool: "git-sync", action: "pull", hint: "Aplique as mudanças baixadas" },
-};
-
-/**
- * Retorna a próxima ação sugerida para o AI Agent
- * @param {string} tool - Nome da tool (git-workflow, git-branches, etc)
- * @param {string} action - Ação executada
- * @returns {object|null} - Próxima ação sugerida ou null se fluxo completo
- */
-export function getNextAction(tool, action) {
-  const key = `${tool.replace('git-', '')}:${action}`;
-  return NEXT_ACTIONS[key] || null;
-}
-
-// Resultado de sucesso com nextAction para AI
-export function asToolResult(result, options = {}) {
-  const { tool, action } = options;
-  const response = { ...result };
-  
-  // Adicionar próxima ação sugerida se disponível
-  if (tool && action) {
-    const next = getNextAction(tool, action);
-    if (next) {
-      response._nextAction = next;
-    } else {
-      response._flowComplete = true;
-    }
-  }
-  
-  return {
-    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
-    isError: false,
-  };
-}
-
-// Resultado de erro (formato melhorado para AI agents)
-export function asToolError(code, message, data) {
-  const errorInfo = ERROR_CODES[code] || {};
-  const response = {
-    error: true,
-    code: code,
-    message: message,
-    suggestion: errorInfo.suggestion || "Verifique os parâmetros e tente novamente",
-    ...data
-  };
-  return {
-    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
-    isError: true,
-  };
-}
-
-// Helper para converter MCPError em resposta
-export function errorToResponse(error) {
-  if (error instanceof MCPError) {
-    return asToolError(error.code, error.message, error.data);
-  }
-  const mapped = mapExternalError(error);
-  return asToolError(mapped.code, mapped.message, mapped.data);
-}
+// Sistema de Erros Melhorado para AI Agents
+
+export class MCPError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+}
+
+// Códigos de erro padronizados com sugestões para AI
+export const ERROR_CODES = {
+  // Auth
+  AUTH_GITHUB_INVALID: {
+    code: "AUTH_GITHUB_INVALID",
+    suggestion: "Verifique se GITHUB_TOKEN está configurado e é válido. Gere um novo token em github.com/settings/tokens"
+  },
+  AUTH_GITEA_INVALID: {
+    code: "AUTH_GITEA_INVALID", 
+    suggestion: "Verifique se GITEA_TOKEN e GITEA_URL estão configurados corretamente"
+  },
+  AUTH_NO_PERMISSION: {
+    code: "AUTH_NO_PERMISSION",
+    suggestion: "Token não tem permissão para esta operação. Verifique os scopes do token"
+  },
+  
+  // Repo
+  REPO_NOT_FOUND: {
+    code: "REPO_NOT_FOUND",
+    suggestion: "Repositório não existe. Use action='init' com createIfMissing=true para criar"
+  },
+  REPO_NO_WRITE: {
+    code: "REPO_NO_WRITE",
+    suggestion: "Sem permissão de escrita. Verifique se você é owner ou colaborador do repositório"
+  },
+  REPO_ALREADY_EXISTS: {
+    code: "REPO_ALREADY_EXISTS",
+    suggestion: "Repositório já existe. Use action='ensure' para verificar ou escolha outro nome"
+  },
+  
+  // Git Local
+  NOT_A_GIT_REPO: {
+    code: "NOT_A_GIT_REPO",
+    suggestion: "Diretório não é um repositório git. Use action='init' primeiro para inicializar"
+  },
+  NO_COMMITS: {
+    code: "NO_COMMITS",
+    suggestion: "Repositório não tem commits. Use action='add' e depois action='commit' primeiro"
+  },
+  NOTHING_TO_COMMIT: {
+    code: "NOTHING_TO_COMMIT",
+    suggestion: "Working tree limpa, nada para commitar. Modifique arquivos primeiro"
+  },
+  NOTHING_TO_PUSH: {
+    code: "NOTHING_TO_PUSH",
+    suggestion: "Nenhuma mudança para push. Faça commits primeiro"
+  },
+  
+  // Branches
+  BRANCH_NOT_FOUND: {
+    code: "BRANCH_NOT_FOUND",
+    suggestion: "Branch não existe. Use action='list' para ver branches disponíveis"
+  },
+  BRANCH_ALREADY_EXISTS: {
+    code: "BRANCH_ALREADY_EXISTS",
+    suggestion: "Branch já existe. Use outro nome ou delete a existente primeiro"
+  },
+  CANNOT_DELETE_CURRENT: {
+    code: "CANNOT_DELETE_CURRENT",
+    suggestion: "Não pode deletar branch atual. Faça checkout para outra branch primeiro"
+  },
+  
+  // Tags
+  TAG_NOT_FOUND: {
+    code: "TAG_NOT_FOUND",
+    suggestion: "Tag não existe. Use action='list' para ver tags disponíveis"
+  },
+  TAG_ALREADY_EXISTS: {
+    code: "TAG_ALREADY_EXISTS",
+    suggestion: "Tag já existe. Use outro nome ou delete a existente primeiro"
+  },
+  
+  // Refs
+  REF_NOT_FOUND: {
+    code: "REF_NOT_FOUND",
+    suggestion: "Referência não encontrada. Verifique se o commit/branch/tag existe. Use action='log' para ver histórico"
+  },
+  INSUFFICIENT_HISTORY: {
+    code: "INSUFFICIENT_HISTORY",
+    suggestion: "Histórico insuficiente para HEAD~N. Use action='log' para verificar quantos commits existem"
+  },
+  
+  // Stash
+  NOTHING_TO_STASH: {
+    code: "NOTHING_TO_STASH",
+    suggestion: "Working tree limpa, nada para stash. Modifique arquivos primeiro"
+  },
+  STASH_NOT_FOUND: {
+    code: "STASH_NOT_FOUND",
+    suggestion: "Stash não encontrado. Use action='list' para ver stashes disponíveis"
+  },
+  
+  // Remote
+  REMOTE_NOT_FOUND: {
+    code: "REMOTE_NOT_FOUND",
+    suggestion: "Remote não configurado. Use action='ensure-remotes' para configurar"
+  },
+  PUSH_REJECTED: {
+    code: "PUSH_REJECTED",
+    suggestion: "Push rejeitado (histórico divergente). Use force=true para forçar, ou faça pull primeiro"
+  },
+  MERGE_CONFLICT: {
+    code: "MERGE_CONFLICT",
+    suggestion: "Conflito de merge. Resolva conflitos manualmente e faça novo commit"
+  },
+  
+  // Network
+  NETWORK_TIMEOUT: {
+    code: "NETWORK_TIMEOUT",
+    suggestion: "Timeout de conexão. Verifique sua internet e tente novamente"
+  },
+  RATE_LIMIT: {
+    code: "RATE_LIMIT",
+    suggestion: "Rate limit excedido. Aguarde alguns minutos antes de tentar novamente"
+  },
+  
+  // Validation
+  VALIDATION_ERROR: {
+    code: "VALIDATION_ERROR",
+    suggestion: "Parâmetros inválidos. Verifique os parâmetros obrigatórios da action"
+  },
+  MISSING_PARAMETER: {
+    code: "MISSING_PARAMETER",
+    suggestion: "Parâmetro obrigatório faltando"
+  },
+  
+  // Files
+  FILE_NOT_FOUND: {
+    code: "FILE_NOT_FOUND",
+    suggestion: "Arquivo não encontrado no repositório. Use action='list' para ver arquivos disponíveis"
+  },
+  
+  // Issues/PRs
+  ISSUE_NOT_FOUND: {
+    code: "ISSUE_NOT_FOUND",
+    suggestion: "Issue não encontrada. Use action='list' para ver issues disponíveis"
+  },
+  PR_NOT_FOUND: {
+    code: "PR_NOT_FOUND",
+    suggestion: "Pull Request não encontrado. Use action='list' para ver PRs disponíveis"
+  },
+  
+  // Filesystem
+  DISK_FULL: {
+    code: "DISK_FULL",
+    suggestion: "Disco cheio. Libere espaço e tente novamente"
+  },
+  FILE_TOO_LARGE: {
+    code: "FILE_TOO_LARGE",
+    suggestion: "Arquivo muito grande para Git. Considere usar Git LFS para arquivos grandes"
+  },
+  PERMISSION_DENIED_FS: {
+    code: "PERMISSION_DENIED_FS",
+    suggestion: "Sem permissão para acessar arquivo/diretório. Verifique permissões do sistema de arquivos"
+  },
+  
+  // Git Corruption
+  GIT_CORRUPTED: {
+    code: "GIT_CORRUPTED",
+    suggestion: "Repositório Git corrompido. Tente: 1) git fsck --full, 2) git gc --prune=now, ou 3) re-clone do remote"
+  },
+  GIT_LOCK_FILE: {
+    code: "GIT_LOCK_FILE",
+    suggestion: "Arquivo de lock presente (.git/index.lock). Outro processo git pode estar rodando. Se não, delete o arquivo de lock manualmente"
+  },
+  
+  // Remote/URL
+  INVALID_REMOTE_URL: {
+    code: "INVALID_REMOTE_URL",
+    suggestion: "URL do remote inválida. Verifique o formato: https://github.com/user/repo.git ou git@github.com:user/repo.git"
+  },
+  REMOTE_UNREACHABLE: {
+    code: "REMOTE_UNREACHABLE",
+    suggestion: "Remote inacessível. Verifique: 1) URL está correta, 2) conexão de internet, 3) firewall/proxy"
+  },
+  SSL_ERROR: {
+    code: "SSL_ERROR",
+    suggestion: "Erro de SSL/TLS. Verifique certificados ou use http.sslVerify=false (não recomendado)"
+  },
+  
+  // Generic
+  UNKNOWN_ERROR: {
+    code: "UNKNOWN_ERROR",
+    suggestion: "Erro desconhecido. Verifique os logs para mais detalhes"
+  }
+};
+
+// Função para criar erro com sugestão
+export function createError(errorCode, details = {}) {
+  const errorInfo = ERROR_CODES[errorCode] || ERROR_CODES.UNKNOWN_ERROR;
+  return new MCPError(errorInfo.code, details.message || errorInfo.code, {
+    suggestion: errorInfo.suggestion,
+    ...details
+  });
+}
+
+// Função para mapear erros externos para códigos internos
+export function mapExternalError(error, context = {}) {
+  const msg = error?.message?.toLowerCase() || String(error).toLowerCase();
+  
+  // GitHub/Gitea API errors
+  if (msg.includes("bad credentials") || msg.includes("401")) {
+    return context.provider === "gitea" 
+      ? createError("AUTH_GITEA_INVALID", { originalError: msg })
+      : createError("AUTH_GITHUB_INVALID", { originalError: msg });
+  }
+  
+  if (msg.includes("not found") || msg.includes("404")) {
+    if (context.type === "repo") return createError("REPO_NOT_FOUND", { repo: context.repo, originalError: msg });
+    if (context.type === "branch") return createError("BRANCH_NOT_FOUND", { branch: context.branch, originalError: msg });
+    if (context.type === "tag") return createError("TAG_NOT_FOUND", { tag: context.tag, originalError: msg });
+    if (context.type === "file") return createError("FILE_NOT_FOUND", { file: context.file, originalError: msg });
+    if (context.type === "issue") return createError("ISSUE_NOT_FOUND", { number: context.number, originalError: msg });
+    if (context.type === "pr") return createError("PR_NOT_FOUND", { number: context.number, originalError: msg });
+    return createError("REF_NOT_FOUND", { ref: context.ref, originalError: msg });
+  }
+  
+  if (msg.includes("permission") || msg.includes("403") || msg.includes("forbidden")) {
+    return createError("AUTH_NO_PERMISSION", { originalError: msg });
+  }
+  
+  if (msg.includes("rate limit") || msg.includes("429")) {
+    return createError("RATE_LIMIT", { originalError: msg });
+  }
+  
+  if (msg.includes("timeout") || msg.includes("etimedout") || msg.includes("econnrefused")) {
+    return createError("NETWORK_TIMEOUT", { originalError: msg });
+  }
+  
+  if (msg.includes("push rejected") || msg.includes("non-fast-forward")) {
+    return createError("PUSH_REJECTED", { originalError: msg });
+  }
+  
+  if (msg.includes("conflict")) {
+    return createError("MERGE_CONFLICT", { originalError: msg });
+  }
+  
+  if (msg.includes("already exists")) {
+    if (context.type === "repo") return createError("REPO_ALREADY_EXISTS", { repo: context.repo, originalError: msg });
+    if (context.type === "branch") return createError("BRANCH_ALREADY_EXISTS", { branch: context.branch, originalError: msg });
+    if (context.type === "tag") return createError("TAG_ALREADY_EXISTS", { tag: context.tag, originalError: msg });
+    return createError("BRANCH_ALREADY_EXISTS", { originalError: msg });
+  }
+  
+  // isomorphic-git specific errors
+  if (msg.includes("could not find") && msg.includes("head~")) {
+    return createError("INSUFFICIENT_HISTORY", { originalError: msg });
+  }
+  
+  if (msg.includes("is not a git repository") || msg.includes("could not find .git")) {
+    return createError("NOT_A_GIT_REPO", { path: context.path, originalError: msg });
+  }
+  
+  if (msg.includes("nothing to commit") || msg.includes("working tree clean")) {
+    return createError("NOTHING_TO_COMMIT", { originalError: msg });
+  }
+  
+  if (msg.includes("could not resolve ref") || msg.includes("invalid reference")) {
+    return createError("REF_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("branch") && (msg.includes("does not exist") || msg.includes("not found"))) {
+    return createError("BRANCH_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("tag") && (msg.includes("does not exist") || msg.includes("not found"))) {
+    return createError("TAG_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("no commits") || msg.includes("unknown revision")) {
+    return createError("NO_COMMITS", { originalError: msg });
+  }
+  
+  if (msg.includes("nada para stash") || msg.includes("nothing to stash") || msg.includes("no local changes")) {
+    return createError("NOTHING_TO_STASH", { originalError: msg });
+  }
+  
+  if (msg.includes("stash") && (msg.includes("not found") || msg.includes("não encontrado"))) {
+    return createError("STASH_NOT_FOUND", { originalError: msg });
+  }
+  
+  if (msg.includes("author") || msg.includes("committer")) {
+    return createError("VALIDATION_ERROR", { 
+      message: "Configure user.name e user.email", 
+      suggestion: "Use git-config para configurar ou forneça tokens de provider",
+      originalError: msg 
+    });
+  }
+  
+  // Filesystem errors
+  if (msg.includes("enospc") || msg.includes("no space left") || msg.includes("disk full")) {
+    return createError("DISK_FULL", { originalError: msg });
+  }
+  
+  if (msg.includes("file too large") || msg.includes("exceeds") || msg.includes("size limit")) {
+    return createError("FILE_TOO_LARGE", { originalError: msg });
+  }
+  
+  if (msg.includes("eacces") || msg.includes("eperm") || (msg.includes("permission") && msg.includes("denied"))) {
+    return createError("PERMISSION_DENIED_FS", { originalError: msg });
+  }
+  
+  // Git corruption
+  if (msg.includes("corrupt") || msg.includes("bad object") || msg.includes("broken") || 
+      msg.includes("missing object") || msg.includes("invalid sha") || msg.includes("fatal: packed")) {
+    return createError("GIT_CORRUPTED", { originalError: msg });
+  }
+  
+  if (msg.includes(".git/index.lock") || msg.includes("unable to create") && msg.includes("lock")) {
+    return createError("GIT_LOCK_FILE", { originalError: msg });
+  }
+  
+  // Remote/URL errors
+  if (msg.includes("invalid url") || msg.includes("malformed") || msg.includes("not a valid")) {
+    return createError("INVALID_REMOTE_URL", { originalError: msg });
+  }
+  
+  if (msg.includes("could not resolve host") || msg.includes("name resolution") || 
+      msg.includes("no address") || msg.includes("unreachable")) {
+    return createError("REMOTE_UNREACHABLE", { originalError: msg });
+  }
+  
+  if (msg.includes("ssl") || msg.includes("certificate") || msg.includes("tls")) {
+    return createError("SSL_ERROR", { originalError: msg });
+  }
+  
+  // Generic fallback
+  return createError("UNKNOWN_ERROR", { originalError: msg, context });
+}
+
+// ============ NEXT ACTIONS PARA AI AGENTS ============
+// Mapeia ação atual para próxima ação sugerida
+export const NEXT_ACTIONS = {
+  // git-workflow
+  "workflow:init": { tool: "git-workflow", action: "add", hint: "Adicione arquivos ao staging com files=['.']" },
+  "workflow:status": { tool: "git-workflow", action: "add", hint: "Se há arquivos modificados, adicione-os ao staging" },
+  "workflow:add": { tool: "git-workflow", action: "commit", hint: "Crie um commit com uma mensagem descritiva" },
+  "workflow:commit": { tool: "git-workflow", action: "push", hint: "Envie as mudanças para GitHub/Gitea" },
+  "workflow:push": null, // Fluxo completo
+  
+  // git-branches
+  "branches:create": { tool: "git-branches", action: "checkout", hint: "Mude para a nova branch criada" },
+  "branches:checkout": { tool: "git-workflow", action: "status", hint: "Verifique o estado da branch" },
+  "branches:delete": null,
+  
+  // git-stash
+  "stash:save": { tool: "git-branches", action: "checkout", hint: "Agora pode trocar de branch com segurança" },
+  "stash:pop": { tool: "git-workflow", action: "status", hint: "Verifique as mudanças restauradas" },
+  
+  // git-merge
+  "merge:merge": { tool: "git-workflow", action: "push", hint: "Envie o merge para os remotes" },
+  
+  // git-tags
+  "tags:create": { tool: "git-tags", action: "push", hint: "Envie a tag para os remotes" },
+  "tags:push": null,
+  
+  // git-remote
+  "remote:ensure": { tool: "git-workflow", action: "push", hint: "Agora pode fazer push" },
+  "remote:release-create": null,
+  
+  // git-sync
+  "sync:pull": { tool: "git-workflow", action: "status", hint: "Verifique mudanças após pull" },
+  "sync:fetch": { tool: "git-sync", action: "pull", hint: "Aplique as mudanças baixadas" },
+};
+
+/**
+ * Retorna a próxima ação sugerida para o AI Agent
+ * @param {string} tool - Nome da tool (git-workflow, git-branches, etc)
+ * @param {string} action - Ação executada
+ * @returns {object|null} - Próxima ação sugerida ou null se fluxo completo
+ */
+export function getNextAction(tool, action) {
+  const key = `${tool.replace('git-', '')}:${action}`;
+  return NEXT_ACTIONS[key] || null;
+}
+
+// Resultado de sucesso com nextAction para AI
+export function asToolResult(result, options = {}) {
+  const { tool, action } = options;
+  const response = { ...result };
+  
+  // Adicionar próxima ação sugerida se disponível
+  if (tool && action) {
+    const next = getNextAction(tool, action);
+    if (next) {
+      response._nextAction = next;
+    } else {
+      response._flowComplete = true;
+    }
+  }
+  
+  return {
+    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+    isError: false,
+  };
+}
+
+// Resultado de erro (formato melhorado para AI agents)
+export function asToolError(code, message, data) {
+  const errorInfo = ERROR_CODES[code] || {};
+  const response = {
+    error: true,
+    code: code,
+    message: message,
+    suggestion: errorInfo.suggestion || "Verifique os parâmetros e tente novamente",
+    ...data
+  };
+  return {
+    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+    isError: true,
+  };
+}
+
+// Helper para converter MCPError em resposta
+export function errorToResponse(error) {
+  if (error instanceof MCPError) {
+    return asToolError(error.code, error.message, error.data);
+  }
+  const mapped = mapExternalError(error);
+  return asToolError(mapped.code, mapped.message, mapped.data);
+}