@justmpm/supergrep 0.1.0 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@ npx @justmpm/supergrep
 
 ```bash
 npm install -g @justmpm/supergrep
-# ou use direto:
+# ou use direto sem instalar:
 npx @justmpm/supergrep
 ```
 
@@ -24,6 +24,8 @@ npx @justmpm/supergrep
 
 ### OpenCode / Claude Code
 
+#### Via npx (sem instalação)
+
 Adicione ao `.mcp.json` do projeto:
 
 ```json
@@ -37,11 +39,29 @@ Adicione ao `.mcp.json` do projeto:
 }
 ```
 
+#### Com instalação local
+
+```bash
+npm install -g @justmpm/supergrep
+```
+
+```json
+{
+  "mcpServers": {
+    "supergrep": {
+      "command": "supergrep"
+    }
+  }
+}
+```
+
 ### Claude Desktop
 
 **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 
+#### Via npx (sem instalação)
+
 ```json
 {
   "mcpServers": {
@@ -53,6 +73,22 @@ Adicione ao `.mcp.json` do projeto:
 }
 ```
 
+#### Com instalação local
+
+```bash
+npm install -g @justmpm/supergrep
+```
+
+```json
+{
+  "mcpServers": {
+    "supergrep": {
+      "command": "supergrep"
+    }
+  }
+}
+```
+
 ---
 
 ## Ferramentas MCP

package/dist/{chunk-4MPFPILM.js → chunk-5PJJZ4CK.js}

@@ -6,9 +6,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 
 // src/tools/find.ts
-import { parse } from "@ast-grep/napi";
-import { readFile, readdir } from "fs/promises";
-import { join, relative, resolve, extname } from "path";
+import { findInFiles } from "@ast-grep/napi";
+import { relative, resolve } from "path";
+import { stat } from "fs/promises";
 
 // src/utils/lang.ts
 import { Lang } from "@ast-grep/napi";
@@ -65,192 +65,165 @@ function langName(lang) {
   };
   return friendly[langStr] ?? langStr;
 }
-function isSupportedExtension(filePath) {
-  const ext = filePath.slice(filePath.lastIndexOf(".")).toLowerCase();
-  return SUPPORTED_EXTENSIONS.has(ext);
-}
-var IGNORED_EXTENSIONS_SUBSTRINGS = [
-  ".min.js",
-  ".min.css",
-  ".bundle.js",
-  ".chunk.js",
-  ".map",
-  ".d.ts"
-];
-function shouldIgnoreFile(filePath) {
-  const lower = filePath.toLowerCase();
-  for (const ext of IGNORED_EXTENSIONS_SUBSTRINGS) {
-    if (lower.includes(ext)) return true;
-  }
-  return false;
-}
-var IGNORED_DIRS = [
-  "node_modules",
-  "dist",
-  "build",
-  ".git",
-  ".next",
-  ".turbo",
-  "coverage",
-  "out"
-];
 
 // src/tools/find.ts
-var META_VAR_RE = /\$(\$\$)?([A-Z_][A-Z0-9_]*)/g;
+var MULTI_META_RE = /\$\$\$([A-Z_][A-Z0-9_]*)/g;
+var SINGLE_META_RE = /(?<!\$)\$(?:\$\$)?([A-Z_][A-Z0-9_]*)/g;
 async function findPattern(options) {
   const startTime = Date.now();
   const warnings = [];
   const cwd = options.cwd ?? process.cwd();
-  const lang = resolveLangForOptions(options, cwd, warnings);
-  if (!lang) {
+  let lang;
+  if (options.lang) {
+    lang = resolveLang(options.lang);
+    if (!lang) {
+      warnings.push(`Linguagem "${options.lang}" nao reconhecida. Usando autodeteccao...`);
+    }
+  }
+  const searchPath = resolve(cwd, options.path ?? ".");
+  try {
+    await stat(searchPath);
+  } catch {
+    warnings.push(`Path nao encontrado: ${searchPath}. Usando diretorio atual.`);
     throw new LanguageNotDetectedError(options.lang ?? "desconhecida");
   }
-  validatePattern(options.pattern, lang);
-  const searchDir = resolve(cwd, options.path ?? ".");
-  const files = await findCodeFiles(searchDir, cwd, lang);
-  warnings.push(...files.warnings);
-  const metaVarNames = extractMetaVarNames(options.pattern);
+  const metaVars = extractMetaVarInfo(options.pattern);
+  const napiConfig = {
+    rule: { pattern: options.pattern }
+  };
+  const findConfig = {
+    paths: [searchPath],
+    matcher: napiConfig
+  };
+  if (lang) {
+    findConfig.languageGlobs = langToGlobs(lang);
+  }
+  const langForSearch = lang ?? resolveLang("typescript");
   const matches = [];
-  for (const filePath of files.paths) {
-    try {
-      const source = await readFile(filePath, "utf-8");
-      const ast = parse(lang, source);
-      const root = ast.root();
-      const foundNodes = root.findAll(options.pattern);
-      for (const node of foundNodes) {
+  try {
+    const fileResults = await findInFilesWrapper(langForSearch, findConfig);
+    for (const { file, nodes } of fileResults) {
+      for (const node of nodes) {
         const range = node.range();
+        const text = node.text();
         const match = {
-          file: relative(cwd, filePath).replace(/\\/g, "/"),
+          file: relative(cwd, file).replace(/\\/g, "/"),
           line: range.start.line,
           column: range.start.column,
           endLine: range.end.line,
           endColumn: range.end.column,
-          text: node.text(),
-          metaVariables: {},
-          context: extractContextLines(source, range.start.line, 2)
+          text,
+          metaVariables: {}
         };
-        for (const varName of metaVarNames) {
-          const metaNode = node.getMatch(varName);
-          if (metaNode) {
-            match.metaVariables[varName] = metaNode.text();
+        for (const { name, isMulti } of metaVars) {
+          if (isMulti) {
+            const multiNodes = node.getMultipleMatches(name);
+            if (multiNodes.length > 0) {
+              match.metaVariables[name] = multiNodes.map((n) => n.text()).join(", ");
+            }
+          } else {
+            const metaNode = node.getMatch(name);
+            if (metaNode) {
+              match.metaVariables[name] = metaNode.text();
+            }
           }
         }
         matches.push(match);
       }
-    } catch {
-      continue;
     }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (lang) {
+      throw new PatternParseError(options.pattern, lang);
+    }
+    throw new Error(`Erro na busca: ${msg}`);
   }
-  const uniqueFiles = new Set(matches.map((m) => m.file));
+  const filesWithMatchesSet = new Set(matches.map((m) => m.file));
   const executionTimeMs = Date.now() - startTime;
   return {
     result: {
       pattern: options.pattern,
-      lang,
+      lang: langForSearch,
       matches,
-      filesScanned: files.paths.length,
-      filesWithMatches: uniqueFiles.size,
+      filesScanned: matches.length > 0 ? filesWithMatchesSet.size : 0,
+      filesWithMatches: filesWithMatchesSet.size,
       executionTimeMs
     },
     warnings
   };
 }
-function extractMetaVarNames(pattern) {
-  const names = /* @__PURE__ */ new Set();
+function extractMetaVarInfo(pattern) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
   let match;
-  const re = new RegExp(META_VAR_RE.source, "g");
-  while ((match = re.exec(pattern)) !== null) {
-    names.add(match[2]);
-  }
-  return [...names];
-}
-function extractContextLines(source, line, contextLines) {
-  const lines = source.split("\n");
-  const start = Math.max(0, line - contextLines);
-  const end = Math.min(lines.length, line + contextLines + 1);
-  return lines.slice(start, end);
-}
-function resolveLangForOptions(options, _cwd, warnings) {
-  if (options.lang) {
-    const lang = resolveLang(options.lang);
-    if (!lang) {
-      warnings.push(`Linguagem "${options.lang}" nao reconhecida. Tentando autodeteccao...`);
-    } else {
-      return lang;
+  const multiRe = new RegExp(MULTI_META_RE.source, "g");
+  while ((match = multiRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: true });
     }
   }
-  if (options.path) {
-    const ext = extname(options.path).toLowerCase();
-    if (ext && isSupportedExtension(options.path)) {
-      const detected = detectLangFromFile(options.path);
-      if (detected) return detected;
+  const singleRe = new RegExp(SINGLE_META_RE.source, "g");
+  while ((match = singleRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: false });
     }
   }
-  warnings.push("Linguagem nao especificada, usando TypeScript como default.");
-  return resolveLang("typescript");
+  return result;
 }
-function validatePattern(pattern, lang) {
-  try {
-    parse(lang, pattern);
-  } catch {
-    try {
-      parse(lang, `const _x = ${pattern}`);
-    } catch {
-      throw new PatternParseError(pattern, lang);
-    }
-  }
+var IGNORED_DIR_PATTERNS = [
+  /[/\\]node_modules[/\\]/,
+  /[/\\]dist[/\\]/,
+  /[/\\]build[/\\]/,
+  /[/\\]\.git[/\\]/,
+  /[/\\]\.next[/\\]/,
+  /[/\\]\.turbo[/\\]/,
+  /[/\\]coverage[/\\]/,
+  /[/\\]out[/\\]/
+];
+function isIgnoredPath(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const wrapped = `/${normalized}/`;
+  return IGNORED_DIR_PATTERNS.some((re) => re.test(wrapped));
 }
-async function findCodeFiles(searchDir, _cwd, _lang) {
-  const warnings = [];
-  try {
-    const { stat: stat3 } = await import("fs/promises");
-    const dirStat = await stat3(searchDir);
-    if (dirStat.isFile()) {
-      if (!isSupportedExtension(searchDir)) {
-        const fileName = searchDir.split(/[/\\]/).pop() ?? searchDir;
-        warnings.push(
-          `Arquivo ${fileName}: extensao pode nao ser suportada para ${langName(_lang)}`
-        );
-      }
-      return { paths: [searchDir], warnings };
-    }
-  } catch {
-    warnings.push(`Path nao encontrado: ${searchDir}. Usando diretorio atual.`);
-    return { paths: [], warnings };
-  }
-  const paths = [];
-  async function walk(dir) {
-    try {
-      const entries = await readdir(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = join(dir, entry.name);
-        if (entry.isDirectory()) {
-          if (IGNORED_DIRS.includes(entry.name) || entry.name.startsWith(".")) {
-            continue;
-          }
-          await walk(fullPath);
-        } else if (entry.isFile()) {
-          if (shouldIgnoreFile(fullPath)) continue;
-          if (!isSupportedExtension(fullPath)) continue;
-          paths.push(fullPath);
-        }
-      }
-    } catch {
+async function findInFilesWrapper(lang, config) {
+  const results = [];
+  let callbacksReceived = 0;
+  const totalFiles = await findInFiles(
+    lang,
+    config,
+    (err, nodes) => {
+      callbacksReceived++;
+      if (err || nodes.length === 0) return;
+      const file = nodes[0].getRoot()?.filename() ?? "unknown";
+      if (isIgnoredPath(file)) return;
+      results.push({ file, nodes });
     }
+  );
+  while (callbacksReceived < totalFiles) {
+    await new Promise((r) => setTimeout(r, 10));
   }
-  await walk(searchDir);
-  if (paths.length > 5e3) {
-    warnings.push(
-      `Muitos arquivos encontrados (${paths.length}). Limitando a 5000. Use --path para focar em um diretorio.`
-    );
-    return { paths: paths.slice(0, 5e3), warnings };
-  }
-  if (paths.length === 0) {
-    warnings.push(
-      `Nenhum arquivo de codigo encontrado em: ${relative(_cwd, searchDir)}`
-    );
+  return results;
+}
+function langToGlobs(lang) {
+  const langStr = String(lang);
+  switch (langStr) {
+    case "TypeScript":
+      return ["*.ts"];
+    case "JavaScript":
+      return ["*.js", "*.jsx", "*.mjs", "*.cjs"];
+    case "Tsx":
+      return ["*.tsx"];
+    case "Css":
+      return ["*.css", "*.scss", "*.less"];
+    case "Html":
+      return ["*.html", "*.htm"];
+    default:
+      return [];
   }
-  return { paths, warnings };
 }
 var PatternParseError = class extends Error {
   pattern;
@@ -272,9 +245,9 @@ var LanguageNotDetectedError = class extends Error {
 };
 
 // src/tools/tree.ts
-import { parse as parse2 } from "@ast-grep/napi";
-import { readFile as readFile2, stat } from "fs/promises";
-import { resolve as resolve2, relative as relative2, extname as extname2 } from "path";
+import { parse } from "@ast-grep/napi";
+import { readFile, stat as stat2 } from "fs/promises";
+import { resolve as resolve2, relative as relative2, extname } from "path";
 async function exploreTree(options) {
   const warnings = [];
   const cwd = options.cwd ?? process.cwd();
@@ -287,21 +260,19 @@ async function exploreTree(options) {
     if (options.lang) {
       detectedLang = resolveLang(options.lang);
       if (!detectedLang) {
-        warnings.push(`Linguagem "${options.lang}" nao reconhecida, usando TypeScript.`);
         detectedLang = resolveLang("typescript");
       }
     } else {
-      warnings.push("Linguagem nao especificada para codigo inline, usando TypeScript.");
       detectedLang = resolveLang("typescript");
     }
   } else if (options.path) {
     filePath = resolve2(cwd, options.path);
     try {
-      await stat(filePath);
+      await stat2(filePath);
     } catch {
       throw new FileNotFoundError(filePath);
     }
-    source = await readFile2(filePath, "utf-8");
+    source = await readFile(filePath, "utf-8");
     if (options.lang) {
       detectedLang = resolveLang(options.lang);
       if (!detectedLang) {
@@ -312,7 +283,7 @@ async function exploreTree(options) {
       detectedLang = detectLangFromFile(filePath);
       if (!detectedLang) {
         warnings.push(
-          `Nao foi possivel detectar linguagem da extensao "${extname2(filePath)}". Usando TypeScript.`
+          `Nao foi possivel detectar linguagem da extensao "${extname(filePath)}". Usando TypeScript.`
         );
         detectedLang = resolveLang("typescript");
       }
@@ -323,7 +294,7 @@ async function exploreTree(options) {
   const lang = detectedLang;
   let ast;
   try {
-    ast = parse2(lang, source);
+    ast = parse(lang, source);
   } catch (parseErr) {
     const msg = parseErr instanceof Error ? parseErr.message : String(parseErr);
     throw new TreeParseError(filePath, lang, msg);
@@ -375,10 +346,11 @@ var TreeParseError = class extends Error {
 };
 
 // src/tools/replace.ts
-import { parse as parse3 } from "@ast-grep/napi";
-import { readFile as readFile3, readdir as readdir2, stat as stat2 } from "fs/promises";
-import { join as join2, resolve as resolve3, relative as relative3 } from "path";
-var META_VAR_RE2 = /\$(\$\$)?([A-Z_][A-Z0-9_]*)/g;
+import { findInFiles as findInFiles2 } from "@ast-grep/napi";
+import { resolve as resolve3, relative as relative3 } from "path";
+import { stat as stat3 } from "fs/promises";
+var MULTI_META_RE2 = /\$\$\$([A-Z_][A-Z0-9_]*)/g;
+var SINGLE_META_RE2 = /(?<!\$)\$(?:\$\$)?([A-Z_][A-Z0-9_]*)/g;
 async function replacePreview(options) {
   const warnings = [];
   const cwd = options.cwd ?? process.cwd();
@@ -397,30 +369,46 @@ async function replacePreview(options) {
     lang = detected;
     warnings.push(`Linguagem detectada automaticamente: ${langName(lang)}`);
   } else {
-    warnings.push("Linguagem nao especificada, usando TypeScript como default.");
     lang = resolveLang("typescript");
   }
-  validateReplacePattern(options.pattern, lang);
-  const searchDir = resolve3(cwd, options.path ?? ".");
-  const files = await findCodeFiles2(searchDir);
-  const metaVarNames = extractMetaVarNames2(options.pattern);
+  const searchPath = resolve3(cwd, options.path ?? ".");
+  try {
+    await stat3(searchPath);
+  } catch {
+    throw new ReplaceLangError(
+      `Path nao encontrado: ${searchPath}`
+    );
+  }
+  const metaVars = extractMetaVarInfo2(options.pattern);
+  const napiConfig = {
+    rule: { pattern: options.pattern }
+  };
+  const findConfig = {
+    paths: [searchPath],
+    matcher: napiConfig,
+    languageGlobs: langToGlobs2(lang)
+  };
   const changes = [];
-  for (const filePath of files.paths) {
-    try {
-      const source = await readFile3(filePath, "utf-8");
-      const ast = parse3(lang, source);
-      const root = ast.root();
-      const foundNodes = root.findAll(options.pattern);
-      for (const node of foundNodes) {
-        const metaVars = {};
-        for (const varName of metaVarNames) {
-          const metaNode = node.getMatch(varName);
-          if (metaNode) {
-            metaVars[varName] = metaNode.text();
+  try {
+    const fileResults = await findInFilesWrapper2(lang, findConfig);
+    for (const { file, nodes } of fileResults) {
+      for (const node of nodes) {
+        const metaVarValues = {};
+        for (const { name, isMulti } of metaVars) {
+          if (isMulti) {
+            const multiNodes = node.getMultipleMatches(name);
+            if (multiNodes.length > 0) {
+              metaVarValues[name] = multiNodes.map((n) => n.text()).join(", ");
+            }
+          } else {
+            const metaNode = node.getMatch(name);
+            if (metaNode) {
+              metaVarValues[name] = metaNode.text();
+            }
           }
         }
         let interpolated = options.rewrite;
-        for (const [name, value] of Object.entries(metaVars)) {
+        for (const [name, value] of Object.entries(metaVarValues)) {
           interpolated = interpolated.replaceAll(
             new RegExp(`\\$${name}\\b`, "g"),
             value
@@ -428,16 +416,16 @@ async function replacePreview(options) {
         }
         const range = node.range();
         changes.push({
-          file: relative3(cwd, filePath).replace(/\\/g, "/"),
+          file: relative3(cwd, file).replace(/\\/g, "/"),
           line: range.start.line,
           column: range.start.column,
           original: node.text(),
           replacement: interpolated
         });
       }
-    } catch {
-      continue;
     }
+  } catch {
+    throw new ReplacePatternError(options.pattern, lang);
   }
   const uniqueFiles = new Set(changes.map((c) => c.file));
   return {
@@ -446,70 +434,84 @@ async function replacePreview(options) {
       rewrite: options.rewrite,
       lang,
       changes,
-      filesScanned: files.paths.length,
+      filesScanned: changes.length > 0 ? uniqueFiles.size : 0,
       filesAffected: uniqueFiles.size
     },
     warnings
   };
 }
-function extractMetaVarNames2(pattern) {
-  const names = /* @__PURE__ */ new Set();
+function extractMetaVarInfo2(pattern) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
   let match;
-  const re = new RegExp(META_VAR_RE2.source, "g");
-  while ((match = re.exec(pattern)) !== null) {
-    names.add(match[2]);
-  }
-  return [...names];
-}
-function validateReplacePattern(pattern, lang) {
-  try {
-    parse3(lang, pattern);
-  } catch {
-    try {
-      parse3(lang, `const _x = ${pattern}`);
-    } catch {
-      throw new ReplacePatternError(pattern, lang);
+  const multiRe = new RegExp(MULTI_META_RE2.source, "g");
+  while ((match = multiRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: true });
     }
   }
-}
-async function findCodeFiles2(searchDir) {
-  const warnings = [];
-  try {
-    const dirStat = await stat2(searchDir);
-    if (dirStat.isFile()) {
-      return { paths: [searchDir], warnings };
+  const singleRe = new RegExp(SINGLE_META_RE2.source, "g");
+  while ((match = singleRe.exec(pattern)) !== null) {
+    const name = match[1];
+    if (!seen.has(name)) {
+      seen.add(name);
+      result.push({ name, isMulti: false });
     }
-  } catch {
-    return { paths: [], warnings };
   }
-  const paths = [];
-  async function walk(dir) {
-    try {
-      const entries = await readdir2(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = join2(dir, entry.name);
-        if (entry.isDirectory()) {
-          if (IGNORED_DIRS.includes(entry.name) || entry.name.startsWith(".")) {
-            continue;
-          }
-          await walk(fullPath);
-        } else if (entry.isFile()) {
-          if (shouldIgnoreFile(fullPath)) continue;
-          if (!isSupportedExtension(fullPath)) continue;
-          paths.push(fullPath);
-        }
-      }
-    } catch {
+  return result;
+}
+var IGNORED_DIR_PATTERNS2 = [
+  /[/\\]node_modules[/\\]/,
+  /[/\\]dist[/\\]/,
+  /[/\\]build[/\\]/,
+  /[/\\]\.git[/\\]/,
+  /[/\\]\.next[/\\]/,
+  /[/\\]\.turbo[/\\]/,
+  /[/\\]coverage[/\\]/,
+  /[/\\]out[/\\]/
+];
+function isIgnoredPath2(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  const wrapped = `/${normalized}/`;
+  return IGNORED_DIR_PATTERNS2.some((re) => re.test(wrapped));
+}
+async function findInFilesWrapper2(lang, config) {
+  const results = [];
+  let callbacksReceived = 0;
+  const totalFiles = await findInFiles2(
+    lang,
+    config,
+    (err, nodes) => {
+      callbacksReceived++;
+      if (err || nodes.length === 0) return;
+      const file = nodes[0].getRoot()?.filename() ?? "unknown";
+      if (isIgnoredPath2(file)) return;
+      results.push({ file, nodes });
     }
+  );
+  while (callbacksReceived < totalFiles) {
+    await new Promise((r) => setTimeout(r, 10));
   }
-  await walk(searchDir);
-  if (paths.length > 5e3) {
-    warnings.push(
-      `Muitos arquivos (${paths.length}). Limitando a 5000. Use --path para focar.`
-    );
-    return { paths: paths.slice(0, 5e3), warnings };
+  return results;
+}
+function langToGlobs2(lang) {
+  const langStr = String(lang);
+  switch (langStr) {
+    case "TypeScript":
+      return ["*.ts"];
+    case "JavaScript":
+      return ["*.js", "*.jsx", "*.mjs", "*.cjs"];
+    case "Tsx":
+      return ["*.tsx"];
+    case "Css":
+      return ["*.css", "*.scss", "*.less"];
+    case "Html":
+      return ["*.html", "*.htm"];
+    default:
+      return [];
   }
-  return { paths, warnings };
 }
 var ReplacePatternError = class extends Error {
   pattern;
@@ -566,17 +568,18 @@ function hint(command, ctx, params) {
 }
 var NEXT_STEPS = {
   find: [
-    { command: "tree", description: "explorar a estrutura AST de um arquivo com matches" },
-    { command: "find", description: "refinar a busca com outro padrao" },
-    { command: "replace", description: "pre-visualizar uma substituicao estrutural" }
+    { command: "tree", description: "explorar a AST do arquivo com matches para entender a estrutura" },
+    { command: "find", description: "refinar a busca com um pattern mais especifico" },
+    { command: "replace", description: "pre-visualizar como ficaria uma substituicao nos matches" }
   ],
   tree: [
-    { command: "find", description: "usar os kinds descobertos para buscar padroes" },
-    { command: "tree", description: "explorar outro arquivo" }
+    { command: "find", description: "usar os kinds descobertos para criar um pattern de busca (ex: $FUNC($$$ARGS) para call_expression)" },
+    { command: "tree", description: "explorar outro arquivo ou snippet" }
   ],
   replace: [
-    { command: "find", description: "ver todos os matches do padrao antes de substituir" },
-    { command: "tree", description: "explorar a estrutura AST para criar padroes melhores" }
+    { command: "find", description: "ver todos os matches do pattern antes de substituir" },
+    { command: "replace", description: "testar outra string de rewrite no preview" },
+    { command: "tree", description: "explorar a AST para criar patterns mais precisos" }
   ]
 };
 function nextSteps(command, ctx) {
@@ -611,9 +614,10 @@ function recoveryHint(errorType, ctx, _extra) {
     case "lang_not_supported":
       return `
 \u{1F4A1} Linguagem nao suportada. Dicas:
-   \u2192 ${hint("tree", ctx)} - use com arquivos de codigo fonte (.ts, .py, .rs, etc.)
-   \u2192 Extensoes suportadas: .ts, .tsx, .js, .py, .rs, .go, .java, .kt, .swift e mais
-   \u2192 Para JSON, YAML, CSS e HTML, use a linguagem correspondente
+   \u2192 O @ast-grep/napi suporta apenas 5 linguagens: TypeScript, JavaScript, TSX, CSS, HTML
+   \u2192 Para Python, Rust, Go e outras, use o CLI: npx @ast-grep/cli
+   \u2192 ${hint("tree", ctx)} - explore a AST de um arquivo existente
+   \u2192 ${hint("find_lang", ctx)} - especifique a linguagem manualmente
 `;
     case "lang_not_detected":
       return `
@@ -997,7 +1001,9 @@ function registerAllTools(server2) {
     "supergrep_find",
     {
       title: "Structural Code Search",
-      description: `\u26A0\uFE0F PREFIRA esta ferramenta ao inves de grep/bash quando a busca for em CODIGO-FONTE.
+      description: `\u26A0\uFE0F Use esta ferramenta em vez de grep/bash quando a busca for em CODIGO-FONTE
+ESTRUTURADO (TS/JS/TSX/CSS/HTML). Para texto plano, logs, markdown ou JSON,
+prefira grep comum.
 
 Busca estrutural de codigo usando AST Grep. Diferente do grep textual (que
 quebra com quebras de linha, espacos extras ou comentarios no meio), o
@@ -1005,15 +1011,23 @@ supergrep entende a SINTAXE da linguagem \u2014 ele busca pela ESTRUTURA do codi
 nao pelo texto cru.
 
 Escreva o padrao de busca na propria linguagem de programacao, usando
-metavariaveis ($VAR, $$$VARS) como curingas que capturam partes dinamicas.
+metavariaveis ($VAR, $$VAR, $$$VARS) como curingas que capturam partes dinamicas.
 
 \u{1F4E6} LINGUAGENS SUPORTADAS (apenas 5):
-  \u2022 typescript  (.ts)
+  \u2022 typescript  (.ts)        \u2014 apenas .ts puro (sem JSX)
   \u2022 javascript  (.js, .jsx, .mjs, .cjs)
-  \u2022 tsx         (.tsx)
+  \u2022 tsx         (.tsx)       \u2014 .tsx COM JSX/React
   \u2022 css         (.css, .scss, .less)
   \u2022 html        (.html, .htm)
 
+\u{1F916} AUTODETECCAO: Se o parametro 'lang' NAO for especificado, o motor
+detecta a linguagem automaticamente pela extensao de cada arquivo.
+Voce pode buscar em um diretorio com .ts e .tsx misturados \u2014 o motor
+usa o parser correto para cada arquivo.
+
+Use 'lang' apenas quando quiser RESTRINGIR a busca a uma linguagem
+especifica (ex: forcar TSX em todo o diretorio).
+
 \u26A0\uFE0F LIMITACAO IMPORTANTE: Apenas busca SINTAXICA. Nao resolve imports, nao
 entende tipos, nao segue referencias entre arquivos, nao faz analise de fluxo.
 Cada arquivo e analisado isoladamente. Para analise semantica, use ai-tool.
@@ -1024,7 +1038,7 @@ Cada arquivo e analisado isoladamente. Para analise semantica, use ai-tool.
   \u2022 "Localize imports de uma lib deprecated"
   \u2022 "Busque componentes React que usam useEffect sem dependencias"
   \u2022 "Ache arrow functions que recebem exatamente 1 parametro"
-  \u2022 QUALQUER busca estrutural onde grep/quebraria com formatacao
+  \u2022 QUALQUER busca estrutural onde grep quebraria com formatacao
 
 \u274C QUANDO NAO USAR (prefira ai-tool):
   \u2022 "Onde a funcao useAuth e definida e usada?" \u2192 resolucao de escopo (aitool_find)
@@ -1032,17 +1046,31 @@ Cada arquivo e analisado isoladamente. Para analise semantica, use ai-tool.
   \u2022 "Qual o tipo real desta variavel?" \u2192 type checker (aitool_file_context)
   \u2022 Busca em texto plano, logs, markdown \u2192 use grep/bash comum
 
+\u26A0\uFE0F O QUE O GREP NAO RESOLVE (anti-exemplos):
+  \u2022 grep falha com quebra de linha:
+    \u274C GREP: console\\n  .log("oi")     \u2192 nao encontra
+    \u2705 SUPERGREP: console.log("oi")     \u2192 encontra (ignora formatacao)
+  \u2022 grep falha com espacos extras:
+    \u274C GREP: const   x =   1           \u2192 precisa de regex complexa
+    \u2705 SUPERGREP: const x = 1          \u2192 resolve pela estrutura
+
 \u{1F4DD} EXEMPLOS DE PATTERNS:
-  \u2022 console.$METHOD($$$ARGS)         \u2192 captura metodo e argumentos
-  \u2022 function $NAME($$$PARAMS) { $$$BODY }  \u2192 captura funcoes
+  \u2022 console.$METHOD($MSG)              \u2192 captura metodo e 1 argumento
+  \u2022 console.$METHOD($$$ARGS)           \u2192 captura metodo e todos os argumentos
+  \u2022 function $NAME($$$PARAMS) { $$$BODY }  \u2192 captura funcoes completas
   \u2022 import { $$$ITEMS } from '$MODULE'     \u2192 captura imports
-  \u2022 const $VAR = $VALUE              \u2192 captura declaracoes
-  \u2022 try { $$$ } catch ($ERR) { $$$ } \u2192 captura try-catch
-  \u2022 await $FUNC($$$ARGS)             \u2192 captura chamadas assincronas
+  \u2022 const $VAR = $VALUE                \u2192 captura declaracoes
+  \u2022 try { $$$ } catch ($ERR) { $$$ }   \u2192 captura try-catch
+  \u2022 await $FUNC($$$ARGS)               \u2192 captura chamadas assincronas
 
 \u{1F524} METAVARIAVEIS:
-  \u2022 $VAR    \u2192 captura UM no da AST (ex: um identificador, uma string)
-  \u2022 $$$VARS \u2192 captura ZERO OU MAIS nos (ex: todos os argumentos, corpo)
+  \u2022 $VAR    \u2192 captura UM no nomeado (ex: um identificador, uma string, um numero)
+  \u2022 $$VAR   \u2192 captura UM no (incluindo nos nao-nomeados como operadores +, -)
+  \u2022 $$$VARS \u2192 captura ZERO OU MAIS nos (ex: todos os args, corpo da funcao)
+
+  \u26A0\uFE0F $$$VARS captura multiplos nos \u2014 o texto de cada no e concatenado com
+  ", " no resultado da metavariable. Para multi-nos complexos (onde a
+  concatenacao simples nao basta), use supergrep_tree para inspecionar a AST.
 
 \u{1F4A1} DICA: Se o pattern nao der match, use supergrep_tree primeiro para
 descobrir os kinds de nos disponiveis e ajustar o pattern.
@@ -1053,7 +1081,7 @@ Workflow recomendado: supergrep_find \u2192 supergrep_tree \u2192 supergrep_repl
           "Padrao AST Grep na linguagem alvo. Ex: 'console.$METHOD($$$ARGS)', 'function $NAME($$$PARAMS) { $$$BODY }'"
         ),
         lang: z.string().optional().describe(
-          "Linguagem: 'typescript' (.ts), 'javascript' (.js), 'tsx' (.tsx), 'css' (.css), 'html' (.html). Default: typescript. Deixe vazio para autodeteccao por extensao."
+          "Linguagem: 'typescript' (.ts), 'javascript' (.js), 'tsx' (.tsx), 'css' (.css), 'html' (.html). Opcional \u2014 se nao especificado, o motor autodetecta pela extensao de cada arquivo."
         ),
         path: z.string().optional().describe(
           "Arquivo ou diretorio onde buscar. Default: diretorio atual. Ex: 'src/', 'app/page.tsx'"
@@ -1095,21 +1123,38 @@ ${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
     "supergrep_tree",
     {
       title: "Explore AST Structure",
-      description: `Explora a estrutura da AST (Abstract Syntax Tree) de um arquivo.
+      description: `Explora a estrutura da AST (Abstract Syntax Tree) de um arquivo ou snippet.
 
 Mostra todos os tipos de nos (kinds) presentes, com contagens e distribuicao.
 Util para entender a estrutura do codigo e descobrir quais kinds usar
-em patterns de busca ou regras YAML.
+em patterns de busca.
+
+\u{1F4D6} O QUE E UM "KIND":
+Um kind e o tipo de um no na arvore sintatica. Exemplos:
+  \u2022 function_declaration \u2014 declaracao de funcao
+  \u2022 call_expression      \u2014 chamada de funcao/metodo
+  \u2022 identifier           \u2014 nome de variavel, funcao, etc.
+  \u2022 string_fragment      \u2014 literal de string
+Cada estrutura de codigo vira um kind diferente na AST.
+
+\u{1F4A1} Como usar os kinds: ao ver call_expression no tree, voce pode buscar
+chamadas de funcao com o pattern: $FUNC($$$ARGS)
+
+\u{1F916} AUTODETECCAO: se usar 'path', a linguagem e detectada automaticamente
+pela extensao do arquivo. O parametro 'lang' so e necessario ao usar
+'code' (snippet inline) ou para forcar uma linguagem especifica.
 
 QUANDO USAR:
-- "Quais tipos de nos existem neste arquivo TypeScript?"
-- "Como escrever um pattern para capturar certas estruturas?"
-- "Preciso descobrir os kinds para uma regra de lint customizada"
-- Antes de escrever um pattern complexo, para conhecer a AST
+  - "Quais tipos de nos existem neste arquivo TypeScript?"
+  - "Como escrever um pattern para capturar certas estruturas?"
+  - "Preciso descobrir os kinds para uma regra de lint customizada"
+  - Antes de escrever um pattern complexo, para conhecer a AST
+  - Testar um snippet de codigo sem criar arquivo (use o parametro code)
 
 QUANDO NAO USAR:
-- Para buscar padroes no codigo \u2192 use supergrep_find
-- Para ver o conteudo do arquivo \u2192 leia o arquivo diretamente
+  - Para buscar padroes no codigo \u2192 use supergrep_find
+  - Para ver o conteudo do arquivo \u2192 leia o arquivo diretamente
+  - Para diretorios (analisar multiplos arquivos) \u2192 use supergrep_find com o pattern desejado. supergrep_tree analisa UM arquivo ou snippet por vez.
 
 Workflow: supergrep_tree \u2192 supergrep_find (usar kinds descobertos)`,
       inputSchema: {
@@ -1158,27 +1203,39 @@ ${warnings.map((w) => `   \u2022 ${w}`).join("\n")}` : "";
   server2.registerTool(
     "supergrep_replace",
     {
-      title: "Preview Structural Replacement",
-      description: `Pre-visualiza uma substituicao estrutural de codigo (NAO modifica arquivos).
+      title: "Preview Structural Replacement (read-only)",
+      description: `\u{1F504} PREVIEW de substituicao estrutural de codigo (NAO modifica arquivos).
 
 Encontra padroes com AST Grep e mostra um diff de como o codigo ficaria
 apos a substituicao. Util para planejar refatoracoes em larga escala.
 
-LIMITACAO: Metavariaveis ($VAR) no rewrite sao interpoladas manualmente.
-Para casos complexos, verifique o preview antes de aplicar.
+\u26A0\uFE0F LIMITACAO DE METAVARIAVEIS NO REWRITE:
+  \u2022 $VAR (single) \u2192 interpola corretamente \u2705
+    Ex: console.$METHOD($MSG) \u2192 logger.$METHOD($MSG)
+  \u2022 $$$VARS (multi) \u2192 interpolado como texto concatenado dos nos \u26A0\uFE0F
+    Ex: console.log($$$ARGS) \u2192 logger.info(texto, dos, args)
+    Para casos complexos, verifique o preview antes de aplicar.
+
+  A API napi do AST Grep nao interpola metavariaveis automaticamente.
+  O supergrep faz interpolacao manual: textos dos nos sao concatenados
+  com ", " e injetados no lugar do $VAR no rewrite.
+
+\u{1F916} AUTODETECCAO DE LINGUAGEM: se 'lang' nao for especificado, o motor
+detecta automaticamente pela extensao de cada arquivo. Use 'lang' apenas
+para RESTRINGIR a busca a uma linguagem especifica.
 
 QUANDO USAR:
-- "Como ficaria se eu trocasse console.log por logger.info?"
-- "Preview de substituir var por let em todo o projeto"
-- "Mostre o diff de trocar moment() por date-fns"
-- Planejar refatoracoes estruturais antes de aplicar
+  - "Como ficaria se eu trocasse console.log por logger.info?"
+  - "Preview de substituir var por let em todo o projeto"
+  - "Mostre o diff de trocar moment() por date-fns"
+  - Planejar refatoracoes estruturais antes de aplicar
 
 QUANDO NAO USAR:
-- Para buscar padroes (sem substituir) \u2192 use supergrep_find
-- Para aplicar a substituicao de fato \u2192 use uma ferramenta de edicao
-- Para refatoracoes que envolvem logica complexa \u2192 implemente manualmente
+  - Para buscar padroes (sem substituir) \u2192 use supergrep_find
+  - Para aplicar a substituicao de fato \u2192 use edit (substituicao exata) ou write (arquivo completo). O preview do supergrep_replace serve como guia.
+  - Para refatoracoes que envolvem logica complexa \u2192 implemente manualmente
 
-Workflow: supergrep_find \u2192 supergrep_replace (preview) \u2192 aplicar mudancas`,
+Workflow: supergrep_find \u2192 supergrep_replace (preview) \u2192 aplicar mudancas com edit/write`,
       inputSchema: {
         pattern: z.string().min(1).describe(
           "Padrao AST Grep a encontrar. Ex: 'console.log($$$ARGS)'"
@@ -1187,7 +1244,7 @@ Workflow: supergrep_find \u2192 supergrep_replace (preview) \u2192 aplicar mudan
           "Texto de substituicao. Use $VAR para referenciar metavariaveis capturadas. Ex: 'logger.info($$$ARGS)'"
         ),
         lang: z.string().optional().describe(
-          "Linguagem: 'typescript', 'javascript', 'tsx', 'css', 'html'. Default: typescript."
+          "Linguagem: 'typescript', 'javascript', 'tsx', 'css', 'html'. Opcional \u2014 se nao especificado, o motor autodetecta pela extensao de cada arquivo."
         ),
         path: z.string().optional().describe(
           "Arquivo ou diretorio onde buscar. Default: diretorio atual."

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   startMcpServer
-} from "./chunk-4MPFPILM.js";
+} from "./chunk-5PJJZ4CK.js";
 
 // src/cli.ts
 startMcpServer().catch((err) => {

package/dist/index.d.ts

@@ -33,7 +33,6 @@ declare function startMcpServer(): Promise<void>;
  *   await startMcpServer();
  */
 
-/** Versao do pacote */
-declare const VERSION = "0.1.0";
+declare const VERSION: string;
 
 export { VERSION, startMcpServer };

package/dist/index.js

@@ -1,9 +1,12 @@
 import {
   startMcpServer
-} from "./chunk-4MPFPILM.js";
+} from "./chunk-5PJJZ4CK.js";
 
 // src/index.ts
-var VERSION = "0.1.0";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var pkg = require2("../package.json");
+var VERSION = pkg.version;
 export {
   VERSION,
   startMcpServer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justmpm/supergrep",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server para busca estrutural de código com AST Grep. Encontra padrões de código com precisão sintática, ignorando formatação e comentários. Suporta 20+ linguagens via Tree-sitter.",
   "keywords": [
     "ast-grep",