@andre.buzeli/git-mcp 15.12.5

package/src/tools/git-remote.js

@@ -0,0 +1,492 @@
+import Ajv from "ajv";
+import axios from "axios";
+import fs from "node:fs";
+import path from "node:path";
+import archiver from "archiver";
+import { asToolError, asToolResult, errorToResponse, mapExternalError } from "../utils/errors.js";
+import { getRepoNameFromPath, validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+import { runBoth } from "../utils/providerExec.js";
+
+/**
+ * Compacta uma pasta em ZIP e retorna o caminho do arquivo temporário
+ * @param {string} folderPath - Caminho da pasta a compactar
+ * @param {string} zipName - Nome do arquivo ZIP (sem extensão)
+ * @returns {Promise<string>} Caminho do arquivo ZIP criado
+ */
+async function compactFolder(folderPath, zipName) {
+  return new Promise((resolve, reject) => {
+    const outputPath = path.join(process.cwd(), 'temp_scripts', `${zipName}.zip`);
+    const output = fs.createWriteStream(outputPath);
+    const archive = archiver('zip', { zlib: { level: 9 } });
+
+    output.on('close', () => resolve(outputPath));
+    output.on('error', reject);
+    archive.on('error', reject);
+
+    archive.pipe(output);
+    archive.directory(folderPath, false);
+    archive.finalize();
+  });
+}
+
+/**
+ * Faz upload de um asset para um release
+ * @param {Object} pm - Provider Manager
+ * @param {string} owner - Dono do repo
+ * @param {string} repo - Nome do repo
+ * @param {number} releaseId - ID do release
+ * @param {string} assetPath - Caminho do arquivo a fazer upload
+ * @param {string} assetName - Nome do asset (com extensão)
+ * @returns {Promise<Object>} Resultado do upload
+ */
+async function uploadAsset(pm, owner, repo, releaseId, assetPath, assetName) {
+  const fileBuffer = fs.readFileSync(assetPath);
+  const fileSize = fs.statSync(assetPath).size;
+
+  const out = await runBoth(pm, {
+    github: async () => {
+      const response = await pm.github.request("POST /repos/{owner}/{repo}/releases/{release_id}/assets", {
+        owner,
+        repo,
+        release_id: releaseId,
+        name: assetName,
+        data: fileBuffer,
+        headers: {
+          'content-type': 'application/octet-stream',
+          'content-length': fileSize
+        }
+      });
+      return { ok: true, id: response.data.id, url: response.data.browser_download_url };
+    },
+    gitea: async () => {
+      const base = pm.giteaUrl.replace(/\/$/, "");
+
+      const response = await axios.post(
+        `${base}/api/v1/repos/${owner}/${repo}/releases/${releaseId}/assets?name=${encodeURIComponent(assetName)}`,
+        fileBuffer,
+        {
+          headers: {
+            'Authorization': `token ${pm.giteaToken}`,
+            'Content-Type': 'application/octet-stream',
+            'Content-Length': fileSize
+          }
+        }
+      );
+      return { ok: true, id: response.data.id, url: response.data.browser_download_url };
+    }
+  });
+
+  return out;
+}
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitRemoteTool(pm, git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: {
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: {
+        type: "string",
+        enum: [
+          "list", "list-all", "list-orgs", "ensure", "repo-delete",
+          "release-create", "topics-set", "milestone-create", "label-create",
+          "fork-create", "fork-list", "star-set", "star-unset",
+          "subscription-set", "subscription-unset", "contents-create"
+        ],
+        description: `Ação a executar:
+
+CONFIGURAÇÃO:
+CONFIGURAÇÃO:
+- list: Lista remotes configurados (github, gitea, origin)
+- list-all: Lista TODOS os repositórios da conta ou organização (GitHub + Gitea)
+- list-orgs: Lista organizações disponíveis no GitHub e Gitea
+- ensure: Cria repos no GitHub/Gitea e configura remotes (USE ESTE se push falhar)
+
+REPOSITÓRIO:
+- repo-delete: Deleta repositório no GitHub E Gitea (⚠️ PERIGOSO)
+- release-create: Cria release/versão no GitHub e Gitea
+- topics-set: Define tópicos/tags do repositório
+- milestone-create: Cria milestone para organização
+- label-create: Cria label para issues
+
+SOCIAL:
+- star-set: Adiciona estrela ao repo
+- star-unset: Remove estrela
+- fork-create: Cria fork do repositório
+- fork-list: Lista forks existentes
+
+NOTIFICAÇÕES:
+- subscription-set: Ativa notificações do repo
+- subscription-unset: Desativa notificações
+
+ARQUIVOS VIA API:
+- contents-create: Cria arquivo diretamente via API (sem git local)`
+      },
+      tag: {
+        type: "string",
+        description: "Tag para release-create. Ex: 'v1.0.0'"
+      },
+      name: {
+        type: "string",
+        description: "Nome da release, label, etc."
+      },
+      body: {
+        type: "string",
+        description: "Descrição/corpo da release"
+      },
+      assets: {
+        type: "array",
+        items: {
+          oneOf: [
+            { type: "string" },  // path simples: "dist/app.exe"
+            {
+              type: "object",
+              properties: {
+                path: { type: "string" },  // "dist/build"
+                name: { type: "string" }   // "MeuApp-Windows" (sem extensao)
+              },
+              required: ["path"]
+            }
+          ]
+        },
+        description: "Assets para upload. String = nome automatico, Objeto = nome custom. Pastas são compactadas automaticamente"
+      },
+      topics: {
+        type: "array",
+        items: { type: "string" },
+        description: "Lista de tópicos para topics-set. Ex: ['javascript', 'nodejs', 'mcp']"
+      },
+      path: {
+        type: "string",
+        description: "Caminho do arquivo para contents-create"
+      },
+      content: {
+        type: "string",
+        description: "Conteúdo do arquivo para contents-create"
+      },
+      branch: {
+        type: "string",
+        description: "Branch alvo para contents-create. Default: main"
+      },
+      color: {
+        type: "string",
+        description: "Cor do label em hex (sem #). Ex: 'ff0000' para vermelho"
+      },
+      title: {
+        type: "string",
+        description: "Título do milestone"
+      },
+      isPublic: {
+        type: "boolean",
+        description: "Se true, repositório será PÚBLICO. Default: false (privado). Aplica-se a action='ensure'"
+      },
+      organization: {
+        type: "string",
+        description: "Opcional. Nome da organização no GitHub/Gitea. Se informado, operações são feitas na org em vez da conta pessoal. Ex: 'automacao-casa', 'cliente-joao'"
+      }
+    },
+    required: ["projectPath", "action"],
+    additionalProperties: false
+  };
+
+  const description = `Operações em repositórios remotos GitHub e Gitea.
+
+AÇÕES MAIS USADAS:
+- ensure: Configurar remotes e criar repos (ESSENCIAL antes de push)
+- list: Ver remotes configurados
+- release-create: Publicar nova versão
+
+EXECUÇÃO PARALELA:
+Todas as operações são executadas em AMBOS os providers (GitHub + Gitea) simultaneamente.
+
+QUANDO USAR:
+- Se git-workflow push falhar: use action='ensure'
+- Para publicar release: use action='release-create'
+- Para configurar tópicos: use action='topics-set'`;
+
+  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 === "list") {
+        const remotes = await git.listRemotes(projectPath);
+
+        // Debug info: calculate what URLs should be
+        let repoName = getRepoNameFromPath(projectPath);
+        if (repoName === "GIT_MCP") repoName = "git-mcp";
+        const calculated = await pm.getRemoteUrls(repoName, args.organization);
+
+        return asToolResult({
+          remotes,
+          configured: remotes.length > 0,
+          hasGithub: remotes.some(r => r.remote === "github"),
+          hasGitea: remotes.some(r => r.remote === "gitea"),
+          debug: {
+            repoName,
+            calculatedUrls: calculated,
+            env: {
+              hasGithubToken: !!pm.githubToken,
+              hasGiteaToken: !!pm.giteaToken,
+              giteaUrl: pm.giteaUrl
+            }
+          },
+          message: remotes.length === 0 ? "Nenhum remote configurado. Use action='ensure' para configurar." : undefined
+        });
+      }
+
+      if (action === "list-all") {
+        const repos = await pm.listAllRepos({ organization: args.organization });
+        const summary = [];
+        if (repos.github?.length) summary.push(`${repos.github.length} GitHub repos`);
+        if (repos.gitea?.length) summary.push(`${repos.gitea.length} Gitea repos`);
+
+        return asToolResult({
+          success: true,
+          organization: args.organization || undefined,
+          summary: summary.join(", "),
+          github: repos.github,
+          gitea: repos.gitea
+        });
+      }
+      if (action === "list-orgs") {
+        const orgs = await pm.listOrgs();
+        const summary = [];
+        if (orgs.github?.length) summary.push(`${orgs.github.length} GitHub orgs`);
+        if (orgs.gitea?.length) summary.push(`${orgs.gitea.length} Gitea orgs`);
+
+        return asToolResult({
+          success: true,
+          summary: summary.length > 0 ? summary.join(", ") : "Nenhuma organização encontrada",
+          github: orgs.github,
+          gitea: orgs.gitea,
+          _aiContext: {
+            hint: "Use o nome da organização no parâmetro 'organization' das outras actions para criar/gerenciar repos dentro da org"
+          }
+        });
+      }
+      if (action === "ensure") {
+        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 });
+        const urls = await pm.getRemoteUrls(repo, organization);
+        await git.ensureRemotes(projectPath, { githubUrl: urls.github || "", giteaUrl: urls.gitea || "" });
+        const remotes = await git.listRemotes(projectPath);
+        return asToolResult({
+          success: true,
+          isPrivate: !isPublic,
+          organization: organization || undefined,
+          ensured,
+          remotes,
+          urls,
+          message: "Remotes configurados. Agora pode usar git-workflow push." + (organization ? ` [org: ${organization}]` : "")
+        });
+      }
+      if (action === "repo-delete") {
+        const repo = getRepoNameFromPath(projectPath);
+        const out = await runBoth(pm, {
+          github: async (owner) => { await pm.github.rest.repos.delete({ owner, repo }); return { ok: true }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.delete(`${base}/api/v1/repos/${owner}/${repo}`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), deleted: repo, providers: out, warning: "Repositório deletado permanentemente!" });
+      }
+      if (action === "release-create") {
+        const repo = getRepoNameFromPath(projectPath);
+        if (!args.tag) return asToolError("MISSING_PARAMETER", "tag é obrigatório para criar release", { parameter: "tag", example: "v1.0.0" });
+        const tag = args.tag;
+        const name = args.name || tag;
+        const body = args.body || "";
+
+        // Criar release primeiro
+        const out = await runBoth(pm, {
+          github: async (owner) => { const r = await pm.github.rest.repos.createRelease({ owner, repo, tag_name: tag, name, body, draft: false, prerelease: false }); return { ok: true, id: r.data.id, url: r.data.html_url }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${base}/api/v1/repos/${owner}/${repo}/releases`, { tag_name: tag, name, body }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, id: r.data?.id }; }
+        }, { organization: args.organization });
+
+        const releaseCreated = !!(out.github?.ok || out.gitea?.ok);
+        if (!releaseCreated) {
+          return asToolResult({ success: false, tag, name, providers: out, error: "Falha ao criar release" });
+        }
+
+        // Processar assets se fornecidos
+        let assetsUploaded = [];
+        if (args.assets && args.assets.length > 0) {
+          const tempFiles = []; // Arquivos temporários a serem deletados
+          const [ghOwner, geOwner] = await Promise.all([
+            pm.getGitHubOwner().catch(() => ""),
+            pm.getGiteaOwner().catch(() => "")
+          ]);
+
+          for (const asset of args.assets) {
+            try {
+              const assetPath = typeof asset === 'string' ? asset : asset.path;
+              const customName = typeof asset === 'object' ? asset.name : null;
+
+              // Resolver caminho absoluto
+              const absolutePath = path.resolve(projectPath, assetPath);
+
+              // Verificar se existe
+              if (!fs.existsSync(absolutePath)) {
+                assetsUploaded.push({ path: assetPath, error: "Arquivo/pasta não encontrado" });
+                continue;
+              }
+
+              const stats = fs.statSync(absolutePath);
+              let uploadPath = absolutePath;
+              let uploadName = customName;
+              let isTempFile = false;
+
+              if (stats.isDirectory()) {
+                // Compactar pasta
+                const zipName = customName || path.basename(absolutePath);
+                const zipPath = await compactFolder(absolutePath, zipName);
+                uploadPath = zipPath;
+                uploadName = `${zipName}.zip`;
+                tempFiles.push(zipPath);
+                isTempFile = true;
+              } else {
+                // Arquivo direto
+                if (!uploadName) {
+                  uploadName = path.basename(absolutePath);
+                } else {
+                  // Adicionar extensão se não tiver
+                  const ext = path.extname(absolutePath);
+                  if (!uploadName.includes('.')) {
+                    uploadName += ext;
+                  }
+                }
+              }
+
+              // Upload para GitHub e Gitea
+              const uploadResult = await uploadAsset(pm, ghOwner || geOwner, repo, out.github?.id || out.gitea?.id, uploadPath, uploadName);
+
+              assetsUploaded.push({
+                path: assetPath,
+                name: uploadName,
+                uploaded: !!(uploadResult.github?.ok || uploadResult.gitea?.ok),
+                providers: uploadResult
+              });
+
+              // Deletar arquivo temporário se foi criado
+              if (isTempFile && tempFiles.includes(uploadPath)) {
+                try {
+                  fs.unlinkSync(uploadPath);
+                  tempFiles.splice(tempFiles.indexOf(uploadPath), 1);
+                } catch (e) {
+                  console.warn(`Falha ao deletar arquivo temporário: ${uploadPath}`);
+                }
+              }
+
+            } catch (error) {
+              assetsUploaded.push({ path: typeof asset === 'string' ? asset : asset.path, error: String(error.message || error) });
+            }
+          }
+        }
+
+        return asToolResult({
+          success: releaseCreated,
+          tag,
+          name,
+          providers: out,
+          assets: assetsUploaded.length > 0 ? assetsUploaded : undefined
+        });
+      }
+      if (action === "topics-set") {
+        const repo = getRepoNameFromPath(projectPath);
+        const topics = Array.isArray(args.topics) ? args.topics : [];
+        if (topics.length === 0) return asToolError("MISSING_PARAMETER", "topics é obrigatório", { parameter: "topics", example: ["javascript", "nodejs"] });
+        const out = await runBoth(pm, {
+          github: async (owner) => { await pm.github.request("PUT /repos/{owner}/{repo}/topics", { owner, repo, names: topics, headers: { accept: "application/vnd.github.mercy-preview+json" } }); return { ok: true }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.put(`${base}/api/v1/repos/${owner}/${repo}/topics`, { topics }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), topics, providers: out });
+      }
+      if (action === "milestone-create") {
+        const repo = getRepoNameFromPath(projectPath);
+        const title = args.title || args.name || "v1.0";
+        const out = await runBoth(pm, {
+          github: async (owner) => { const r = await pm.github.request("POST /repos/{owner}/{repo}/milestones", { owner, repo, title }); return { ok: true, id: r.data?.id }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${base}/api/v1/repos/${owner}/${repo}/milestones`, { title }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, id: r.data?.id }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), title, providers: out });
+      }
+      if (action === "label-create") {
+        const repo = getRepoNameFromPath(projectPath);
+        const name = args.name || "bug";
+        const color = String(args.color || "ff0000").replace(/^#/, "");
+        const out = await runBoth(pm, {
+          github: async (owner) => { await pm.github.request("POST /repos/{owner}/{repo}/labels", { owner, repo, name, color }); return { ok: true }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.post(`${base}/api/v1/repos/${owner}/${repo}/labels`, { name, color }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), label: { name, color }, providers: out });
+      }
+      if (action === "fork-create") {
+        const repo = getRepoNameFromPath(projectPath);
+        const out = await runBoth(pm, {
+          github: async (owner) => { const r = await pm.github.rest.repos.createFork({ owner, repo }); return { ok: true, full_name: r.data?.full_name }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.post(`${base}/api/v1/repos/${owner}/${repo}/forks`, {}, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, full_name: r.data?.full_name }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), providers: out });
+      }
+      if (action === "fork-list") {
+        const repo = getRepoNameFromPath(projectPath);
+        const out = await runBoth(pm, {
+          github: async (owner) => { const r = await pm.github.rest.repos.listForks({ owner, repo }); return { ok: true, count: r.data.length }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); const r = await axios.get(`${base}/api/v1/repos/${owner}/${repo}/forks`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true, count: (r.data || []).length }; }
+        }, { organization: args.organization });
+        return asToolResult({ providers: out });
+      }
+      if (action === "star-set" || action === "star-unset") {
+        const repo = getRepoNameFromPath(projectPath);
+        const out = await runBoth(pm, {
+          github: async (owner) => {
+            if (action === "star-set") { await pm.github.request("PUT /user/starred/{owner}/{repo}", { owner, repo }); return { ok: true }; }
+            await pm.github.request("DELETE /user/starred/{owner}/{repo}", { owner, repo }); return { ok: true };
+          },
+          gitea: async (owner) => {
+            const base = pm.giteaUrl.replace(/\/$/, "");
+            if (action === "star-set") { await axios.put(`${base}/api/v1/user/starred/${owner}/${repo}`, {}, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+            await axios.delete(`${base}/api/v1/user/starred/${owner}/${repo}`, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true };
+          }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), action, providers: out });
+      }
+      if (action === "subscription-set" || action === "subscription-unset") {
+        const repo = getRepoNameFromPath(projectPath);
+        const out = await runBoth(pm, {
+          github: async (owner) => { if (action === "subscription-set") { await pm.github.request("PUT /repos/{owner}/{repo}/subscription", { owner, repo, subscribed: true }); } else { await pm.github.request("DELETE /repos/{owner}/{repo}/subscription", { owner, repo }); } return { ok: true }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); if (action === "subscription-set") { await axios.put(`${base}/api/v1/repos/${owner}/${repo}/subscription`, { subscribed: true }, { headers: { Authorization: `token ${pm.giteaToken}` } }); } else { await axios.delete(`${base}/api/v1/repos/${owner}/${repo}/subscription`, { headers: { Authorization: `token ${pm.giteaToken}` } }); } return { ok: true }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), action, providers: out });
+      }
+      if (action === "contents-create") {
+        const repo = getRepoNameFromPath(projectPath);
+        if (!args.path) return asToolError("MISSING_PARAMETER", "path é obrigatório", { parameter: "path" });
+        if (!args.content) return asToolError("MISSING_PARAMETER", "content é obrigatório", { parameter: "content" });
+        const filePath = args.path;
+        const message = args.message || `Add ${filePath}`;
+        const data = args.content;
+        const branch = args.branch || "main";
+        const b64 = Buffer.from(data, "utf8").toString("base64");
+        const out = await runBoth(pm, {
+          github: async (owner) => { await pm.github.request("PUT /repos/{owner}/{repo}/contents/{path}", { owner, repo, path: filePath, message, content: b64, branch }); return { ok: true }; },
+          gitea: async (owner) => { const base = pm.giteaUrl.replace(/\/$/, ""); await axios.post(`${base}/api/v1/repos/${owner}/${repo}/contents/${encodeURIComponent(filePath)}`, { content: b64, message, branch }, { headers: { Authorization: `token ${pm.giteaToken}` } }); return { ok: true }; }
+        }, { organization: args.organization });
+        return asToolResult({ success: !!(out.github?.ok || out.gitea?.ok), path: filePath, branch, providers: out });
+      }
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, {
+        availableActions: ["list", "list-all", "list-orgs", "ensure", "repo-delete", "release-create", "topics-set", "milestone-create", "label-create", "fork-create", "fork-list", "star-set", "star-unset", "subscription-set", "subscription-unset", "contents-create"]
+      });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-remote", description, inputSchema, handle };
+}

package/src/tools/git-reset.js

@@ -0,0 +1,105 @@
+import Ajv from "ajv";
+import { asToolError, asToolResult, errorToResponse } from "../utils/errors.js";
+import { validateProjectPath, withRetry } from "../utils/repoHelpers.js";
+
+const ajv = new Ajv({ allErrors: true });
+
+export function createGitResetTool(git) {
+  const inputSchema = {
+    type: "object",
+    properties: {
+      projectPath: { 
+        type: "string",
+        description: "Caminho absoluto do diretório do projeto"
+      },
+      action: { 
+        type: "string", 
+        enum: ["soft", "mixed", "hard", "hard-clean"],
+        description: `Tipo de reset a executar:
+- soft: Desfaz commits mas MANTÉM mudanças staged (pronto para re-commit)
+- mixed: Desfaz commits e unstage, mas MANTÉM mudanças no working directory
+- hard: Desfaz commits e DESCARTA todas as mudanças (PERIGOSO - dados perdidos)
+- hard-clean: Como hard, mas também REMOVE arquivos não rastreados (MUITO PERIGOSO)`
+      },
+      ref: { 
+        type: "string",
+        description: "Referência para reset. Ex: 'HEAD~1' (volta 1 commit), 'HEAD~2' (volta 2), ou SHA específico"
+      }
+    },
+    required: ["projectPath", "action", "ref"],
+    additionalProperties: false
+  };
+
+  const description = `Reset Git - desfaz commits e/ou mudanças.
+
+⚠️ CUIDADO: Reset pode causar perda de dados!
+
+TIPOS DE RESET:
+- soft: Seguro - mantém tudo, apenas move HEAD
+- mixed: Moderado - remove do staging mas mantém arquivos
+- hard: PERIGOSO - descarta todas as mudanças
+- hard-clean: MUITO PERIGOSO - descarta mudanças E remove arquivos não rastreados
+
+EXEMPLOS COMUNS:
+- Desfazer último commit (manter mudanças): action='soft' ref='HEAD~1'
+- Desfazer último commit (unstage): action='mixed' ref='HEAD~1'
+- Descartar tudo e voltar ao commit anterior: action='hard' ref='HEAD~1'
+- Limpar completamente o workspace: action='hard-clean' ref='HEAD'
+
+REFERÊNCIAS:
+- HEAD~1: Um commit atrás
+- HEAD~2: Dois commits atrás
+- abc1234: SHA específico do commit`;
+
+  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, ref } = args;
+    try {
+      validateProjectPath(projectPath);
+      // Verificar se há commits suficientes para HEAD~N
+      if (ref.match(/HEAD~(\d+)/)) {
+        const match = ref.match(/HEAD~(\d+)/);
+        const steps = parseInt(match[1], 10);
+        const log = await git.log(projectPath, { maxCount: steps + 2 });
+        if (log.length <= steps) {
+          return asToolError("INSUFFICIENT_HISTORY", `Histórico insuficiente para ${ref}`, {
+            requestedSteps: steps,
+            availableCommits: log.length,
+            suggestion: `Use HEAD~${log.length - 1} no máximo, ou um SHA específico`,
+            recentCommits: log.slice(0, 5).map(c => ({ sha: c.sha.substring(0, 7), message: c.message.split("\n")[0] }))
+          });
+        }
+      }
+      
+      if (action === "soft") {
+        await withRetry(() => git.resetSoft(projectPath, ref), 3, "reset-soft");
+        return asToolResult({ success: true, action: "soft", ref, message: "Commits desfeitos, mudanças mantidas staged" });
+      }
+      if (action === "mixed") {
+        await withRetry(() => git.resetMixed(projectPath, ref), 3, "reset-mixed");
+        return asToolResult({ success: true, action: "mixed", ref, message: "Commits desfeitos, mudanças mantidas no working directory" });
+      }
+      if (action === "hard") {
+        await withRetry(() => git.resetHard(projectPath, ref), 3, "reset-hard");
+        return asToolResult({ success: true, action: "hard", ref, message: "⚠️ Reset hard executado - mudanças descartadas" });
+      }
+      if (action === "hard-clean") {
+        const result = await withRetry(() => git.resetHardClean(projectPath, ref), 3, "reset-hard-clean");
+        return asToolResult({ 
+          success: true, 
+          action: "hard-clean", 
+          ref, 
+          cleanedFiles: result.cleaned,
+          message: `⚠️ Reset hard-clean executado - mudanças descartadas e ${result.cleaned.length} arquivo(s) não rastreados removidos` 
+        });
+      }
+      
+      return asToolError("VALIDATION_ERROR", `Ação '${action}' não suportada`, { availableActions: ["soft", "mixed", "hard", "hard-clean"] });
+    } catch (e) {
+      return errorToResponse(e);
+    }
+  }
+
+  return { name: "git-reset", description, inputSchema, handle };
+}