@andre.buzeli/git-mcp 16.0.8 → 16.1.3

package/src/tools/git-workflow.js

@@ -1,456 +1,605 @@
-import Ajv from "ajv";
-import fs from "fs";
-import path from "path";
-import { MCPError, asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
-import { getRepoNameFromPath, detectProjectType, GITIGNORE_TEMPLATES, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
-
-const ajv = new Ajv({ allErrors: true });
-
-export function createGitWorkflowTool(pm, git) {
-  const inputSchema = {
-    type: "object",
-    properties: {
-      projectPath: {
-        type: "string",
-        description: "Caminho absoluto do diretório do projeto (ex: 'C:/Users/user/projeto' ou '/home/user/projeto')"
-      },
-      action: {
-        type: "string",
-        enum: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update"],
-        description: `Ação a executar:
-- init: Inicializa repositório git local E cria repos no GitHub/Gitea automaticamente
-- status: Retorna arquivos modificados, staged, untracked (use ANTES de commit para ver o que mudou)
-- add: Adiciona arquivos ao staging (use ANTES de commit)
-- remove: Remove arquivos do staging
-- commit: Cria commit com os arquivos staged (use DEPOIS de add)
-- push: Envia commits para GitHub E Gitea em paralelo (use DEPOIS de commit)
-- ensure-remotes: Configura remotes GitHub e Gitea (use se push falhar por falta de remote)
-- clean: Remove arquivos não rastreados do working directory
-- update: RECOMENDADO - Executa fluxo completo automatizado (status → add → commit → push) em uma única chamada`
-      },
-      files: {
-        type: "array",
-        items: { type: "string" },
-        description: "Lista de arquivos para add/remove. Use ['.'] para todos os arquivos. Ex: ['src/index.js', 'package.json']"
-      },
-      message: {
-        type: "string",
-        description: "Mensagem do commit. Obrigatório para action='commit'. Ex: 'feat: adiciona nova funcionalidade'"
-      },
-      force: {
-        type: "boolean",
-        description: "Force push (use apenas se push normal falhar com erro de histórico divergente). Default: false"
-      },
-      createGitignore: {
-        type: "boolean",
-        description: "Se true, cria .gitignore padrão baseado no tipo de projeto (action='init'). Default: true"
-      },
-      isPublic: {
-        type: "boolean",
-        description: "Se true, repositório será PÚBLICO. Default: false (privado). Aplica-se a action='init' e 'ensure-remotes'"
-      },
-      dryRun: {
-        type: "boolean",
-        description: "Se true, simula a operação sem executar (útil para testes). Default: false"
-      },
-      skipIfClean: {
-        type: "boolean",
-        description: "Para action='update': se true, pula silenciosamente se não houver mudanças. Default: false"
-      },
-      gitignore: {
-        type: "array",
-        items: {
-          type: "string"
-        },
-        description: "Para action='update': lista de padrões para adicionar ao .gitignore antes de atualizar"
-      },
-      organization: {
-        type: "string",
-        description: "Opcional. Nome da organização no GitHub/Gitea onde o repositório será criado/gerenciado. Se não informado, usa a conta pessoal. Ex: 'automacao-casa', 'cliente-joao'"
-      }
-    },
-    required: ["projectPath", "action"],
-    additionalProperties: false
-  };
-
-  const description = `Operações Git essenciais com sincronização automática GitHub + Gitea.
-
-⭐ RECOMENDADO - FLUXO AUTOMATIZADO:
-• action="update" → Executa status, add, commit e push em uma única chamada
-• Exemplo: { "projectPath": "/path", "action": "update", "message": "feat: nova feature" }
-
-FLUXO MANUAL (se preferir controle individual):
-1. git-workflow status → ver arquivos modificados
-2. git-workflow add → adicionar arquivos ao staging  
-3. git-workflow commit → criar commit
-4. git-workflow push → enviar para GitHub e Gitea
-
-QUANDO USAR CADA ACTION:
-- update: ⭐ RECOMENDADO - Fluxo completo automatizado (status → add → commit → push)
-- status: Para verificar estado atual do repositório
-- add: Quando há arquivos modificados para commitar
-- commit: Após add, para salvar as mudanças
-- push: Após commit, para sincronizar com remotes
-- init: Apenas uma vez, para novos projetos (cria .gitignore automaticamente)
-- ensure-remotes: Se push falhar por falta de configuração
-- clean: Limpar arquivos não rastreados
-
-EXEMPLOS DE USO:
-• ⭐ Atualizar tudo: { "projectPath": "/path/to/project", "action": "update", "message": "feat: descrição" }
-• Iniciar projeto: { "projectPath": "/path/to/project", "action": "init" }
-• Ver mudanças: { "projectPath": "/path/to/project", "action": "status" }`;
-
-  async function handle(args) {
-    const validate = ajv.compile(inputSchema);
-    if (!validate(args || {})) {
-      return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
-    }
-    const { projectPath, action } = args;
-    try {
-      // #region agent log
-      if (process.env.DEBUG_AGENT_LOG) {
-        fetch('http://127.0.0.1:8243/ingest/a7114eec-653b-43b0-9f09-7073baee17bf', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId: 'debug-session', runId: 'run1', hypothesisId: 'H1', location: 'git-workflow.js:handle-entry', message: 'handle start', data: { action, projectPath }, timestamp: Date.now() }) }).catch(() => { });
-      }
-      // #endregion
-
-      validateProjectPath(projectPath);
-      // #region agent log
-      if (process.env.DEBUG_AGENT_LOG) {
-        fetch('http://127.0.0.1:8243/ingest/a7114eec-653b-43b0-9f09-7073baee17bf', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId: 'debug-session', runId: 'run1', hypothesisId: 'H1', location: 'git-workflow.js:handle-validated', message: 'projectPath validated', data: { action }, timestamp: Date.now() }) }).catch(() => { });
-      }
-      // #endregion
-      if (action === "init") {
-        if (args.dryRun) {
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: "DRY RUN: Repositório seria inicializado localmente e nos providers",
-            repoName: getRepoNameFromPath(projectPath),
-            gitignoreCreated: shouldCreateGitignore
-          });
-        }
-
-        const isRepo = await git.isRepo(projectPath);
-        if (!isRepo) {
-          await git.init(projectPath);
-        }
-
-        // Criar .gitignore baseado no tipo de projeto (apenas se não existir ou se for novo repo)
-        const shouldCreateGitignore = args.createGitignore !== false;
-        let gitignoreCreated = false;
-
-        if (shouldCreateGitignore) {
-          const hasGitignore = fs.existsSync(path.join(projectPath, ".gitignore"));
-          if (!hasGitignore) {
-            const projectType = detectProjectType(projectPath);
-            const patterns = GITIGNORE_TEMPLATES[projectType] || GITIGNORE_TEMPLATES.general;
-            await git.createGitignore(projectPath, patterns);
-            gitignoreCreated = true;
-          }
-        }
-
-        const repo = getRepoNameFromPath(projectPath);
-        const isPublic = args.isPublic === true; // Default: privado
-        const organization = args.organization || undefined;
-        const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true, isPublic, organization });
-
-        // Configurar remotes com org se fornecida
-        const urls = await pm.getRemoteUrls(repo, organization);
-        await git.ensureRemotes(projectPath, { githubUrl: urls.github || "", giteaUrl: urls.gitea || "" });
-
-        return asToolResult({
-          success: true,
-          ensured,
-          isPrivate: !isPublic,
-          organization: organization || undefined,
-          gitignoreCreated,
-          message: "Repositório inicializado localmente e nos providers" + (organization ? ` [org: ${organization}]` : "") + (gitignoreCreated ? " (.gitignore criado)" : "") + (!isPublic ? " [PRIVADO]" : " [PÚBLICO]")
-        });
-      }
-      if (action === "status") {
-        const st = await git.status(projectPath);
-        // #region agent log
-        if (process.env.DEBUG_AGENT_LOG) {
-          fetch('http://127.0.0.1:8243/ingest/a7114eec-653b-43b0-9f09-7073baee17bf', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId: 'debug-session', runId: 'run1', hypothesisId: 'H2', location: 'git-workflow.js:status', message: 'status result', data: { modified: st.modified.length, created: st.created.length, deleted: st.deleted.length, notAdded: st.not_added.length, isClean: st.isClean }, timestamp: Date.now() }) }).catch(() => { });
-        }
-        // #endregion
-
-        if (args.dryRun) {
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: "DRY RUN: Status seria verificado",
-            ...st
-          });
-        }
-
-        // Adicionar contexto para AI Agent decidir próximo passo
-        const hasUnstaged = st.not_added?.length > 0 || st.modified?.length > 0 || st.created?.length > 0;
-        const hasStaged = st.staged?.length > 0;
-        const hasConflicts = st.conflicted?.length > 0;
-
-        let _aiContext = {
-          needsAdd: hasUnstaged && !hasStaged,
-          readyToCommit: hasStaged && !hasConflicts,
-          hasConflicts: hasConflicts,
-          isClean: st.isClean,
-          suggestedAction: null
-        };
-
-        if (hasConflicts) {
-          _aiContext.suggestedAction = "Resolva os conflitos manualmente antes de continuar";
-        } else if (hasStaged) {
-          _aiContext.suggestedAction = "Use action='commit' com uma mensagem descritiva";
-        } else if (hasUnstaged) {
-          _aiContext.suggestedAction = "Use action='add' com files=['.'] para adicionar todas as mudanças";
-        } else {
-          _aiContext.suggestedAction = "Working tree limpa. Modifique arquivos ou use action='push' se há commits pendentes";
-        }
-
-        return asToolResult({ ...st, _aiContext }, { tool: 'workflow', action: 'status' });
-      }
-      if (action === "add") {
-        const files = Array.isArray(args.files) && args.files.length ? args.files : ["."];
-
-        if (args.dryRun) {
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: `DRY RUN: Arquivos seriam adicionados: ${files.join(", ")}`,
-            files
-          });
-        }
-
-        await git.add(projectPath, files);
-        return asToolResult({ success: true, files }, { tool: 'workflow', action: 'add' });
-      }
-      if (action === "remove") {
-        const files = Array.isArray(args.files) ? args.files : [];
-        await git.remove(projectPath, files);
-        return asToolResult({ success: true, files });
-      }
-      if (action === "commit") {
-        if (!args.message) {
-          return asToolError("MISSING_PARAMETER", "message é obrigatório para commit", { parameter: "message" });
-        }
-
-        if (args.dryRun) {
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: `DRY RUN: Commit seria criado com mensagem: "${args.message}"`
-          });
-        }
-
-        const sha = await git.commit(projectPath, args.message);
-        // #region agent log
-        if (process.env.DEBUG_AGENT_LOG) {
-          fetch('http://127.0.0.1:8243/ingest/a7114eec-653b-43b0-9f09-7073baee17bf', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ sessionId: 'debug-session', runId: 'run1', hypothesisId: 'H3', location: 'git-workflow.js:commit', message: 'commit created', data: { sha, message: args.message }, timestamp: Date.now() }) }).catch(() => { });
-        }
-        // #endregion
-        return asToolResult({ success: true, sha, message: args.message }, { tool: 'workflow', action: 'commit' });
-      }
-      if (action === "clean") {
-        if (args.dryRun) {
-          const result = await git.cleanUntracked(projectPath);
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: `DRY RUN: ${result.cleaned.length} arquivo(s) seriam removidos`,
-            wouldClean: result.cleaned
-          });
-        }
-
-        const result = await git.cleanUntracked(projectPath);
-        return asToolResult({
-          success: true,
-          ...result,
-          message: result.cleaned.length > 0
-            ? `${result.cleaned.length} arquivo(s) não rastreados removidos`
-            : "Nenhum arquivo para limpar"
-        });
-      }
-      if (action === "ensure-remotes") {
-        const repo = getRepoNameFromPath(projectPath);
-        const isPublic = args.isPublic === true; // Default: privado
-        const organization = args.organization || undefined;
-
-        if (args.dryRun) {
-          const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: false, isPublic, organization }); // Don't create for dry run
-          const urls = await pm.getRemoteUrls(repo, organization);
-
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: "DRY RUN: Remotes seriam configurados" + (organization ? ` [org: ${organization}]` : ""),
-            repo,
-            organization: organization || undefined,
-            githubUrl: urls.github || "",
-            giteaUrl: urls.gitea || "",
-            ensured
-          });
-        }
-
-        const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true, isPublic, organization });
-        // Build URLs from actual ensureRepos results (handles GitHub fallback to personal account)
-        const githubUrl = ensured.github?.ok && ensured.github.repo
-          ? `https://github.com/${ensured.github.repo}.git` : "";
-        const giteaBase = pm.giteaUrl?.replace(/\/$/, "");
-        const giteaUrl = ensured.gitea?.ok && ensured.gitea.repo && giteaBase
-          ? `${giteaBase}/${ensured.gitea.repo}.git` : "";
-        await git.ensureRemotes(projectPath, { githubUrl, giteaUrl, organization });
-        const remotes = await git.listRemotes(projectPath);
-        return asToolResult({ success: true, ensured, remotes, isPrivate: !isPublic, organization: organization || undefined }, { tool: 'workflow', action: 'ensure-remotes' });
-      }
-      if (action === "push") {
-        const branch = await git.getCurrentBranch(projectPath);
-        const force = !!args.force;
-
-        if (args.dryRun) {
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: `DRY RUN: Push seria executado na branch '${branch}'${force ? ' (force)' : ''}`,
-            branch,
-            force
-          });
-        }
-
-        const organization = args.organization || undefined;
-
-        // Retry logic for push (often fails due to network or concurrent updates)
-        const result = await withRetry(
-          () => git.pushParallel(projectPath, branch, force, organization),
-          3,
-          "push"
-        );
-
-        return asToolResult({ success: true, branch, ...result });
-      }
-
-      // ============ UPDATE - FLUXO AUTOMATIZADO COMPLETO ============
-      if (action === "update") {
-        if (!args.message) {
-          return asToolError("MISSING_PARAMETER", "message é obrigatório para update", { parameter: "message" });
-        }
-
-        const files = Array.isArray(args.files) && args.files.length ? args.files : ["."];
-        const force = !!args.force;
-        const skipIfClean = !!args.skipIfClean;
-        const gitignorePatterns = Array.isArray(args.gitignore) ? args.gitignore : [];
-
-        // 0. Gitignore (se solicitado)
-        let gitignored = [];
-        if (gitignorePatterns.length > 0) {
-          if (args.dryRun) {
-            gitignored = gitignorePatterns;
-          } else {
-            await git.addToGitignore(projectPath, gitignorePatterns);
-            gitignored = gitignorePatterns;
-          }
-        }
-
-        // 1. Status para ver o que mudou
-        const status = await git.status(projectPath);
-
-        const hasChanges = !status.isClean ||
-          (status.not_added?.length > 0) ||
-          (status.modified?.length > 0) ||
-          (status.created?.length > 0) ||
-          (status.deleted?.length > 0) ||
-          (status.staged?.length > 0);
-
-        if (!hasChanges && skipIfClean && gitignored.length === 0) {
-          return asToolResult({
-            success: true,
-            skipped: true,
-            reason: "Working tree limpa, nada para atualizar",
-            status
-          });
-        }
-
-        if (!hasChanges && gitignored.length === 0) {
-          return asToolResult({
-            success: false,
-            error: "NOTHING_TO_UPDATE",
-            message: "Nenhuma mudança para atualizar. Use skipIfClean=true para pular silenciosamente.",
-            status
-          });
-        }
-
-        if (args.dryRun) {
-          return asToolResult({
-            success: true,
-            dryRun: true,
-            message: "DRY RUN: Update seria executado",
-            wouldExecute: ["gitignore (opcional)", "status", "add", "commit", "push"],
-            files,
-            commitMessage: args.message,
-            gitignored,
-            status
-          });
-        }
-
-        // 2. Add
-        await git.add(projectPath, files);
-
-        // 3. Commit  
-        const sha = await git.commit(projectPath, args.message);
-
-        // 3.5. Garantir remotes com organization (se fornecida)
-        const organization = args.organization || undefined;
-        if (organization) {
-          const repo = getRepoNameFromPath(projectPath);
-          const isPublic = args.isPublic === true;
-          const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true, isPublic, organization });
-          // Build URLs from actual ensureRepos results (handles GitHub fallback to personal account)
-          const githubUrl = ensured.github?.ok && ensured.github.repo
-            ? `https://github.com/${ensured.github.repo}.git` : "";
-          const giteaBase = pm.giteaUrl?.replace(/\/$/, "");
-          const giteaUrl = ensured.gitea?.ok && ensured.gitea.repo && giteaBase
-            ? `${giteaBase}/${ensured.gitea.repo}.git` : "";
-          await git.ensureRemotes(projectPath, { githubUrl, giteaUrl, organization });
-        }
-
-        // 4. Push
-        const branch = await git.getCurrentBranch(projectPath);
-        const pushResult = await withRetry(
-          () => git.pushParallel(projectPath, branch, force, organization),
-          3,
-          "push"
-        );
-
-        return asToolResult({
-          success: true,
-          action: "update",
-          steps: ["status", "add", "commit", "push"],
-          sha,
-          message: args.message,
-          branch,
-          filesAdded: files,
-          gitignored,
-          organization: organization || undefined,
-          push: pushResult,
-          _aiContext: {
-            completed: true,
-            message: "Ciclo completo: arquivos adicionados, commit criado e push realizado" + (organization ? ` [org: ${organization}]` : "")
-          }
-        }, { tool: 'workflow', action: 'update' });
-      }
-
-      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, {
-        availableActions: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update"],
-        suggestion: "Use action='update' para fluxo completo automatizado"
-      });
-    } catch (e) {
-      return errorToResponse(e);
-    }
-  }
-
-  return {
-    name: "git-workflow",
-    description,
-    inputSchema,
-    handle
-  };
-}
+import Ajv from "ajv";
+import fs from "fs";
+import path from "path";
+import { asToolError, asToolResult, errorToResponse, createError } from "../utils/errors.js";
+import { getRepoNameFromPath, detectProjectType, GITIGNORE_TEMPLATES, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+import { sendLog } from "../utils/mcpNotify.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+function resolveRemoteBranch(branchName, channel) {
+  if (channel === "production") return branchName;
+  if (channel === "beta") return `${branchName}-beta`;
+  if (channel === "alpha") return `${branchName}-alpha`;
+  return branchName;
+}
+
+export function createGitWorkflowTool(pm, git, server) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: {
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto no IDE (ex: '/home/user/meu-projeto' ou 'C:/Users/user/meu-projeto'). IMPORTANTE: este valor não pode ser inferido automaticamente pelo servidor — o agente deve fornecer o path real do projeto sendo trabalhado, não o diretório home do usuário."
+      },
+      action: {
+        type: "string",
+        enum: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update", "init-branch"],
+        description: `Ação a executar:
+- init: Inicializa repositório git local E cria repos no GitHub/Gitea automaticamente
+- status: Retorna arquivos modificados, staged, untracked (use ANTES de commit para ver o que mudou)
+- add: Adiciona arquivos ao staging (use ANTES de commit)
+- remove: Remove arquivos do staging
+- commit: Cria commit com os arquivos staged (use DEPOIS de add)
+- push: Envia commits para GitHub E Gitea em paralelo (use DEPOIS de commit)
+- ensure-remotes: Configura remotes GitHub e Gitea (use se push falhar por falta de remote)
+- clean: Remove arquivos não rastreados do working directory
+- update: RECOMENDADO - Executa fluxo completo automatizado (status → add → commit → push) em uma única chamada
+- init-branch: Atalho para criar um novo worktree/branch (use git-worktree add preferencialmente)`
+      },
+      files: {
+        type: "array",
+        items: { type: "string" },
+        default: ["."],
+        description: "Lista de arquivos para add/remove. Default: ['.'] (todos). Ex: ['src/index.js', 'package.json']"
+      },
+      message: {
+        type: "string",
+        description: "Mensagem do commit. Obrigatório para action='commit'. Ex: 'feat: adiciona nova funcionalidade'"
+      },
+      branch: {
+        type: "string",
+        description: "Nome da branch (para action='init-branch')"
+      },
+      channel: {
+        type: "string",
+        enum: ["production", "beta", "alpha"],
+        description: "Canal de deploy para push (action='update'). Sobrescreve o channel salvo para este push."
+      },
+      syncBranches: {
+        type: "boolean",
+        description: "Se true e executado no principal (action='update'), propaga commits para todos os worktrees registrados."
+      },
+      force: {
+        type: "boolean",
+        default: false,
+        description: "Force push (use apenas se push normal falhar com erro de histórico divergente). Default: false"
+      },
+      createGitignore: {
+        type: "boolean",
+        default: true,
+        description: "Se true, cria .gitignore padrão baseado no tipo de projeto (action='init'). Default: true"
+      },
+      isPublic: {
+        type: "boolean",
+        default: false,
+        description: "Se true, repositório será PÚBLICO. Default: false (privado). Aplica-se a action='init' e 'ensure-remotes'"
+      },
+      dryRun: {
+        type: "boolean",
+        default: false,
+        description: "Se true, simula a operação sem executar (útil para testes). Default: false"
+      },
+      skipIfClean: {
+        type: "boolean",
+        default: false,
+        description: "Para action='update': se true, pula silenciosamente se não houver mudanças. Default: false"
+      },
+      gitignore: {
+        type: "array",
+        items: {
+          type: "string"
+        },
+        description: "Para action='update': lista de padrões para adicionar ao .gitignore antes de atualizar"
+      },
+      organization: {
+        type: "string",
+        description: "Opcional. Nome da organização no GitHub/Gitea onde o repositório será criado/gerenciado. Se não informado, usa a conta pessoal. Ex: 'automacao-casa', 'cliente-joao'"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `IMPORTANTE — projectPath:
+Informe o caminho absoluto do projeto aberto no IDE. O servidor MCP não tem acesso ao
+contexto do IDE e não consegue detectar automaticamente qual projeto está sendo trabalhado.
+
+Operações Git essenciais com sincronização automática GitHub + Gitea.
+
+⭐ RECOMENDADO - FLUXO AUTOMATIZADO:
+• action="update" → Executa status, add, commit e push em uma única chamada
+• Exemplo: { "projectPath": "/path", "action": "update", "message": "feat: nova feature" }
+
+FLUXO MANUAL (se preferir controle individual):
+1. git-workflow status → ver arquivos modificados
+2. git-workflow add → adicionar arquivos ao staging  
+3. git-workflow commit → criar commit
+4. git-workflow push → enviar para GitHub e Gitea
+
+QUANDO USAR CADA ACTION:
+- update: ⭐ RECOMENDADO - Fluxo completo automatizado (status → add → commit → push)
+- status: Para verificar estado atual do repositório
+- add: Quando há arquivos modificados para commitar
+- commit: Após add, para salvar as mudanças
+- push: Após commit, para sincronizar com remotes
+- init: Apenas uma vez, para novos projetos (cria .gitignore automaticamente)
+- ensure-remotes: Se push falhar por falta de configuração
+- clean: Limpar arquivos não rastreados
+
+EXEMPLOS DE USO:
+• ⭐ Atualizar tudo: { "projectPath": "/path/to/project", "action": "update", "message": "feat: descrição" }
+• Iniciar projeto: { "projectPath": "/path/to/project", "action": "init" }
+• Ver mudanças: { "projectPath": "/path/to/project", "action": "status" }`;
+
+  async function handle(args) {
+    const validate = ajv.compile(inputSchema);
+    if (!validate(args || {})) {
+      return asToolError("VALIDATION_ERROR", "Parâmetros inválidos", validate.errors);
+    }
+    const { projectPath, action } = args;
+    try {
+      validateProjectPath(projectPath);
+      if (action === "init") {
+        const shouldCreateGitignore = args.createGitignore !== false;
+
+        if (args.dryRun) {
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: "DRY RUN: Repositório seria inicializado localmente e nos providers",
+            repoName: getRepoNameFromPath(projectPath),
+            gitignoreCreated: shouldCreateGitignore
+          });
+        }
+
+        const isRepo = await git.isRepo(projectPath);
+        if (!isRepo) {
+          await git.init(projectPath);
+        }
+
+        // Criar .gitignore baseado no tipo de projeto (apenas se não existir ou se for novo repo)
+        let gitignoreCreated = false;
+
+        if (shouldCreateGitignore) {
+          const hasGitignore = fs.existsSync(path.join(projectPath, ".gitignore"));
+          if (!hasGitignore) {
+            const projectType = detectProjectType(projectPath);
+            const patterns = GITIGNORE_TEMPLATES[projectType] || GITIGNORE_TEMPLATES.general;
+            await git.createGitignore(projectPath, patterns);
+            gitignoreCreated = true;
+          }
+        }
+
+        const repo = getRepoNameFromPath(projectPath);
+        const isPublic = args.isPublic === true; // Default: privado
+        const organization = args.organization || undefined;
+        const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true, isPublic, organization });
+
+        // Configurar remotes com org se fornecida
+        const urls = await pm.getRemoteUrls(repo, organization);
+        await git.ensureRemotes(projectPath, { githubUrl: urls.github || "", giteaUrl: urls.gitea || "" });
+
+        return asToolResult({
+          success: true,
+          ensured,
+          isPrivate: !isPublic,
+          organization: organization || undefined,
+          gitignoreCreated,
+          message: "Repositório inicializado localmente e nos providers" + (organization ? ` [org: ${organization}]` : "") + (gitignoreCreated ? " (.gitignore criado)" : "") + (!isPublic ? " [PRIVADO]" : " [PÚBLICO]")
+        });
+      }
+      if (action === "status") {
+        const st = await git.status(projectPath);
+
+        if (args.dryRun) {
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: "DRY RUN: Status seria verificado",
+            ...st
+          });
+        }
+
+        // Adicionar contexto para AI Agent decidir próximo passo
+        const hasUnstaged = st.not_added?.length > 0 || st.modified?.length > 0 || st.created?.length > 0;
+        const hasStaged = st.staged?.length > 0;
+        const hasConflicts = st.conflicted?.length > 0;
+
+        let _aiContext = {
+          needsAdd: hasUnstaged && !hasStaged,
+          readyToCommit: hasStaged && !hasConflicts,
+          hasConflicts: hasConflicts,
+          isClean: st.isClean,
+          suggestedAction: null
+        };
+
+        if (hasConflicts) {
+          _aiContext.suggestedAction = "Resolva os conflitos manualmente antes de continuar";
+        } else if (hasStaged) {
+          _aiContext.suggestedAction = "Use action='commit' com uma mensagem descritiva";
+        } else if (hasUnstaged) {
+          _aiContext.suggestedAction = "Use action='add' com files=['.'] para adicionar todas as mudanças";
+        } else {
+          _aiContext.suggestedAction = "Working tree limpa. Modifique arquivos ou use action='push' se há commits pendentes";
+        }
+
+        return asToolResult({ ...st, _aiContext }, { tool: 'workflow', action: 'status' });
+      }
+      if (action === "add") {
+        const files = Array.isArray(args.files) && args.files.length ? args.files : ["."];
+
+        if (args.dryRun) {
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: `DRY RUN: Arquivos seriam adicionados: ${files.join(", ")}`,
+            files
+          });
+        }
+
+        await git.add(projectPath, files);
+        return asToolResult({ success: true, files }, { tool: 'workflow', action: 'add' });
+      }
+      if (action === "remove") {
+        const files = Array.isArray(args.files) ? args.files : [];
+        await git.remove(projectPath, files);
+        return asToolResult({ success: true, files });
+      }
+      if (action === "commit") {
+        if (!args.message) {
+          return asToolError("MISSING_PARAMETER", "message é obrigatório para commit", { parameter: "message" });
+        }
+
+        if (args.dryRun) {
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: `DRY RUN: Commit seria criado com mensagem: "${args.message}"`
+          });
+        }
+
+        const sha = await git.commit(projectPath, args.message);
+        return asToolResult({ success: true, sha, message: args.message }, { tool: 'workflow', action: 'commit' });
+      }
+      if (action === "clean") {
+        if (args.dryRun) {
+          const result = await git.cleanUntracked(projectPath);
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: `DRY RUN: ${result.cleaned.length} arquivo(s) seriam removidos`,
+            wouldClean: result.cleaned
+          });
+        }
+
+        const result = await git.cleanUntracked(projectPath);
+        return asToolResult({
+          success: true,
+          ...result,
+          message: result.cleaned.length > 0
+            ? `${result.cleaned.length} arquivo(s) não rastreados removidos`
+            : "Nenhum arquivo para limpar"
+        });
+      }
+      if (action === "ensure-remotes") {
+        const repo = getRepoNameFromPath(projectPath);
+        const isPublic = args.isPublic === true; // Default: privado
+        const organization = args.organization || undefined;
+
+        if (args.dryRun) {
+          const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: false, isPublic, organization }); // Don't create for dry run
+          const urls = await pm.getRemoteUrls(repo, organization);
+
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: "DRY RUN: Remotes seriam configurados" + (organization ? ` [org: ${organization}]` : ""),
+            repo,
+            organization: organization || undefined,
+            githubUrl: urls.github || "",
+            giteaUrl: urls.gitea || "",
+            ensured
+          });
+        }
+
+        const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true, isPublic, organization });
+        // Build URLs from actual ensureRepos results (handles GitHub fallback to personal account)
+        const githubUrl = ensured.github?.ok && ensured.github.repo
+          ? `https://github.com/${ensured.github.repo}.git` : "";
+        const giteaBase = pm.giteaUrl?.replace(/\/$/, "");
+        const giteaUrl = ensured.gitea?.ok && ensured.gitea.repo && giteaBase
+          ? `${giteaBase}/${ensured.gitea.repo}.git` : "";
+        await git.ensureRemotes(projectPath, { githubUrl, giteaUrl, organization });
+        const remotes = await git.listRemotes(projectPath);
+        return asToolResult({ success: true, ensured, remotes, isPrivate: !isPublic, organization: organization || undefined }, { tool: 'workflow', action: 'ensure-remotes' });
+      }
+      if (action === "push") {
+        const branch = await git.getCurrentBranch(projectPath);
+        const force = !!args.force;
+
+        if (args.dryRun) {
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: `DRY RUN: Push seria executado na branch '${branch}'${force ? ' (force)' : ''}`,
+            branch,
+            force
+          });
+        }
+
+        const organization = args.organization || undefined;
+        
+        // Log push start
+        await sendLog(server, "info", "push iniciado", { branch, force, organization });
+
+        // Retry logic for push (often fails due to network or concurrent updates)
+        const result = await withRetry(
+          () => git.pushParallel(projectPath, branch, force, organization),
+          3,
+          "push"
+        );
+
+        return asToolResult({ success: true, branch, ...result });
+      }
+
+      if (action === "init-branch") {
+        const branch = args.branch;
+        if (!branch) {
+            return asToolError("MISSING_PARAMETER", "Parâmetro 'branch' é obrigatório para action='init-branch'");
+        }
+        
+        const channel = args.channel || "production";
+        const wtPath = path.join(projectPath, branch);
+
+        if (fs.existsSync(wtPath)) {
+            return asToolError("WORKTREE_PATH_EXISTS", `Diretório '${wtPath}' já existe.`, { suggestion: "Use git-worktree add se quiser configurar path customizado" });
+        }
+
+        try {
+            await git.addWorktree(projectPath, branch, wtPath);
+            await git.setWorktreeConfig(projectPath, branch, { path: wtPath, channel });
+            
+            return asToolResult({
+                success: true,
+                branch,
+                path: wtPath,
+                channel,
+                message: `Worktree '${branch}' criado com sucesso no canal '${channel}'`
+            });
+        } catch (e) {
+            return errorToResponse(e);
+        }
+      }
+
+      // ============ UPDATE - FLUXO AUTOMATIZADO COMPLETO ============
+      if (action === "update") {
+        if (!args.message) {
+          return asToolError("MISSING_PARAMETER", "message é obrigatório para update", { parameter: "message" });
+        }
+
+        const files = Array.isArray(args.files) && args.files.length ? args.files : ["."];
+        const force = !!args.force;
+        const skipIfClean = !!args.skipIfClean;
+        const gitignorePatterns = Array.isArray(args.gitignore) ? args.gitignore : [];
+        const syncBranches = !!args.syncBranches;
+
+        // 0. Gitignore (se solicitado)
+        let gitignored = [];
+        if (gitignorePatterns.length > 0) {
+          if (args.dryRun) {
+            gitignored = gitignorePatterns;
+          } else {
+            await git.addToGitignore(projectPath, gitignorePatterns);
+            gitignored = gitignorePatterns;
+          }
+        }
+
+        // 1. Status para ver o que mudou
+        const status = await git.status(projectPath);
+
+        const hasChanges = !status.isClean ||
+          (status.not_added?.length > 0) ||
+          (status.modified?.length > 0) ||
+          (status.created?.length > 0) ||
+          (status.deleted?.length > 0) ||
+          (status.staged?.length > 0);
+
+        if (!hasChanges && skipIfClean && gitignored.length === 0) {
+          return asToolResult({
+            success: true,
+            skipped: true,
+            reason: "Working tree limpa, nada para atualizar",
+            status
+          });
+        }
+
+        if (!hasChanges && gitignored.length === 0) {
+          return asToolResult({
+            success: false,
+            error: "NOTHING_TO_UPDATE",
+            message: "Nenhuma mudança para atualizar. Use skipIfClean=true para pular silenciosamente.",
+            status
+          });
+        }
+
+        if (args.dryRun) {
+          return asToolResult({
+            success: true,
+            dryRun: true,
+            message: "DRY RUN: Update seria executado",
+            wouldExecute: ["gitignore (opcional)", "status", "add", "commit", "push" + (syncBranches ? " (sync all worktrees)" : "")],
+            files,
+            commitMessage: args.message,
+            gitignored,
+            status,
+            syncBranches
+          });
+        }
+
+        // 2. Add
+        await git.add(projectPath, files);
+
+        // 3. Commit  
+        const sha = await git.commit(projectPath, args.message);
+
+        // 3.5. Garantir remotes com organization (se fornecida)
+        const organization = args.organization || undefined;
+        if (organization) {
+          const repo = getRepoNameFromPath(projectPath);
+          const isPublic = args.isPublic === true;
+          const ensured = await pm.ensureRepos({ repoName: repo, createIfMissing: true, isPublic, organization });
+          // Build URLs from actual ensureRepos results (handles GitHub fallback to personal account)
+          const githubUrl = ensured.github?.ok && ensured.github.repo
+            ? `https://github.com/${ensured.github.repo}.git` : "";
+          const giteaBase = pm.giteaUrl?.replace(/\/$/, "");
+          const giteaUrl = ensured.gitea?.ok && ensured.gitea.repo && giteaBase
+            ? `${giteaBase}/${ensured.gitea.repo}.git` : "";
+          await git.ensureRemotes(projectPath, { githubUrl, giteaUrl, organization });
+        }
+
+        // 4. Push Strategy
+        const branch = await git.getCurrentBranch(projectPath);
+        let pushResult = {};
+        let synced = [];
+        let errors = [];
+
+        // Determine Channel
+        let channel = args.channel;
+        if (!channel) {
+             const storedChannel = await git.getConfig(projectPath, `worktree-branch.${branch}.channel`);
+             if (storedChannel) channel = storedChannel;
+        }
+        
+        // Default channel
+        if (!channel) channel = "production";
+
+        // SYNC BRANCHES
+        if (syncBranches) {
+            // Só permitido no principal (onde .git é diretório)
+            if (fs.existsSync(path.join(projectPath, ".git")) && fs.statSync(path.join(projectPath, ".git")).isFile()) {
+                return asToolError("INVALID_OPERATION", "syncBranches=true só pode ser executado a partir do repositório principal, não de um worktree.");
+            }
+
+            // 1. Push do principal (current)
+            const remoteBranch = resolveRemoteBranch(branch, channel);
+            const remotes = await git.listRemotes(projectPath);
+            
+            await sendLog(server, "info", "update: push iniciado (sync)", { branch, remoteBranch, force });
+
+            const mainPushed = [];
+            const mainFailed = [];
+            for (const r of remotes) {
+                try {
+                    await git.pushRefspec(projectPath, r.remote, branch, remoteBranch, force);
+                    mainPushed.push(r.remote);
+                } catch(e) {
+                    mainFailed.push({ remote: r.remote, error: e.message });
+                }
+            }
+
+            // 2. Propagar para worktrees
+            // Req 8.3: synced.length + errors.length === N (número de worktrees registrados)
+            // O principal NÃO entra no contador — só os worktrees registrados
+            const configs = await git.getWorktreeConfigs(projectPath);
+            
+            for (const wt of configs) {
+                // Pula se for a própria branch principal (caso esteja registrada)
+                if (wt.branch === branch) continue;
+
+                try {
+                    // Merge main -> worktree
+                    await git.merge(wt.path, branch);
+                    
+                    // Resolve remote branch do worktree
+                    const wtRemoteBranch = resolveRemoteBranch(wt.branch, wt.channel);
+                    
+                    // Push worktree
+                    const wtRemotes = await git.listRemotes(wt.path);
+                    for (const r of wtRemotes) {
+                        await git.pushRefspec(wt.path, r.remote, wt.branch, wtRemoteBranch, false); // Nunca force no sync
+                    }
+                    synced.push({ branch: wt.branch, remoteBranch: wtRemoteBranch, channel: wt.channel });
+                } catch (e) {
+                    errors.push({ branch: wt.branch, error: e.message });
+                }
+            }
+
+            pushResult = {
+                main: { branch, remoteBranch, channel, pushed: mainPushed, failed: mainFailed },
+                synced,
+                errors
+            };
+        } else {
+            // NORMAL UPDATE (SINGLE BRANCH)
+            const remoteBranch = resolveRemoteBranch(branch, channel);
+            
+            if (remoteBranch === branch) {
+                // Comportamento padrão (production)
+                await sendLog(server, "info", "update: push iniciado", { branch, force });
+                pushResult = await withRetry(
+                  () => git.pushParallel(projectPath, branch, force, organization),
+                  3,
+                  "push"
+                );
+            } else {
+                // Comportamento customizado (beta/alpha) -> pushRefspec
+                const remotes = await git.listRemotes(projectPath);
+                
+                const pushed = [];
+                const failed = [];
+                
+                await sendLog(server, "info", "update: push iniciado (refspec)", { branch, remoteBranch, force });
+
+                for (const r of remotes) {
+                    try {
+                        await git.pushRefspec(projectPath, r.remote, branch, remoteBranch, force);
+                        pushed.push(r.remote);
+                    } catch (e) {
+                        failed.push({ remote: r.remote, error: e.message });
+                    }
+                }
+                
+                if (pushed.length === 0 && failed.length > 0) {
+                    // Melhor retornar erro se TODOS falharem
+                    throw createError("PUSH_REJECTED", { message: "Push falhou para todos os remotes customizados", errors: failed });
+                }
+                pushResult = { pushed, failed, remoteBranch };
+            }
+        }
+
+        return asToolResult({
+          success: true,
+          action: "update",
+          steps: ["status", "add", "commit", "push"],
+          sha,
+          message: args.message,
+          branch,
+          filesAdded: files,
+          gitignored,
+          organization: organization || undefined,
+          push: pushResult,
+          _aiContext: {
+            completed: true,
+            message: "Ciclo completo: arquivos adicionados, commit criado e push realizado" + (organization ? ` [org: ${organization}]` : "")
+          }
+        }, { tool: 'workflow', action: 'update' });
+      }
+
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, {
+        availableActions: ["init", "status", "add", "remove", "commit", "push", "ensure-remotes", "clean", "update", "init-branch"],
+        suggestion: "Use action='update' para fluxo completo automatizado"
+      });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return {
+    name: "git-workflow",
+    description,
+    inputSchema,
+    handle,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false }
+  };
+}