@justmpm/ai-tool 0.9.3 → 1.0.1

package/dist/{chunk-5RMB6OEA.js → chunk-LJZCMVX5.js}

@@ -5,13 +5,15 @@ import {
   formatOutput,
   getAllCodeFiles,
   getCachedSymbolsIndex,
+  hint,
   indexProject,
   isCacheValid,
   isFileIgnored,
+  nextSteps,
   parseCommandOptions,
   readConfig,
   updateCacheMeta
-} from "./chunk-J3MX6NK3.js";
+} from "./chunk-4HAUIZQ7.js";
 
 // src/commands/describe.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
@@ -147,11 +149,34 @@ function findAreaMatches(normalizedQuery, candidates, config, cwd) {
 }
 async function describe(query, options = {}) {
   const { cwd, format } = parseCommandOptions(options);
+  const ctx = options.ctx || "cli";
   if (!query || query.trim().length === 0) {
     throw new Error("Query \xE9 obrigat\xF3ria. Exemplo: ai-tool describe 'autentica\xE7\xE3o'");
   }
   try {
     const config = readConfig(cwd);
+    const hasAreas = Object.keys(config.areas).length > 0;
+    if (!hasAreas) {
+      let out = `\u26A0\uFE0F Nenhuma area configurada neste projeto.
+
+`;
+      out += `O comando describe busca em areas configuradas.
+`;
+      out += `Para configurar areas:
+`;
+      out += `   1. ${hint("areas_init", ctx)} - gerar arquivo de configuracao
+`;
+      out += `   2. Edite .analyze/areas.config.json com as areas do projeto
+
+`;
+      out += `Enquanto isso, use:
+`;
+      out += `   \u2192 ${hint("find", ctx)} - buscar simbolos no codigo
+`;
+      out += `   \u2192 ${hint("map", ctx)} - ver estrutura do projeto
+`;
+      return out;
+    }
     const normalizedQuery = query.toLowerCase().trim();
     const candidates = Object.entries(config.areas).map(([id, area]) => ({
       id,
@@ -172,8 +197,8 @@ async function describe(query, options = {}) {
         { maxDistance: 2, limit: 3 }
       );
       suggestions.push(
-        ...similarAreaIds.map((id) => `\u2192 ai-tool describe ${id}`),
-        ...similarNames.map((name) => `\u2192 ai-tool describe "${name}"`)
+        ...similarAreaIds.map((id) => `\u2192 ${hint("describe", ctx, { "<termo>": id })}`),
+        ...similarNames.map((name) => `\u2192 ${hint("describe", ctx, { "<termo>": `"${name}"` })}`)
       );
     }
     const result = {
@@ -183,20 +208,20 @@ async function describe(query, options = {}) {
       areas: matches,
       suggestions: suggestions.length > 0 ? suggestions : void 0
     };
-    return formatOutput(result, format, formatDescribeText);
+    return formatOutput(result, format, (r) => formatDescribeText(r, ctx));
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Erro ao executar describe: ${message}`);
   }
 }
-function formatDescribeText(result) {
+function formatDescribeText(result, ctx = "cli") {
   let out = "";
   if (result.areas.length === 0) {
-    out += `\u274C Nenhuma \xE1rea encontrada para: "${result.query}"
+    out += `\u274C Nenhuma area encontrada para: "${result.query}"
 
 `;
     if (result.suggestions && result.suggestions.length > 0) {
-      out += `\u{1F4A1} Voc\xEA quis dizer?
+      out += `\u{1F4A1} Voce quis dizer?
 `;
       for (const suggestion of result.suggestions) {
         out += `   ${suggestion}
@@ -205,7 +230,12 @@ function formatDescribeText(result) {
       out += `
 `;
     }
-    out += `\u{1F4D6} Dica: Use 'ai-tool areas' para listar todas as \xE1reas dispon\xEDveis`;
+    out += `\u{1F4D6} Dicas:
+`;
+    out += `   \u2192 ${hint("areas", ctx)} - listar todas as areas disponiveis
+`;
+    out += `   \u2192 ${hint("find", ctx)} - buscar simbolos por nome
+`;
     return out;
   }
   out += `\u{1F50D} Busca: "${result.query}"
@@ -220,21 +250,25 @@ function formatDescribeText(result) {
 
 `;
     if (area.files.length > 0) {
+      const MAX_FILES = 5;
+      const filesToShow = area.files.slice(0, MAX_FILES);
+      const remaining = area.files.length - filesToShow.length;
       out += `Arquivos:
 `;
-      for (const file of area.files) {
+      for (const file of filesToShow) {
         out += `   \u2022 ${file}
+`;
+      }
+      if (remaining > 0) {
+        out += `   ... e mais ${remaining} arquivo(s)
+`;
+        out += `   \u2192 ${hint("area", ctx, { "<nome>": area.id })} - ver todos
 `;
       }
       out += "\n";
     }
   }
-  out += `\u{1F4D6} Pr\xF3ximos passos:
-`;
-  out += `   \u2192 ai-tool area <id> - ver detalhes de uma \xE1rea
-`;
-  out += `   \u2192 ai-tool context --area=<id> - contexto completo de uma \xE1rea
-`;
+  out += nextSteps("describe", ctx);
   return out;
 }
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   describe
-} from "./chunk-5RMB6OEA.js";
+} from "./chunk-LJZCMVX5.js";
 import {
   VERSION,
   area,
@@ -16,7 +16,7 @@ import {
   impact,
   map,
   suggest
-} from "./chunk-J3MX6NK3.js";
+} from "./chunk-4HAUIZQ7.js";
 
 // src/cli.ts
 import { resolve } from "path";
@@ -113,7 +113,7 @@ async function main() {
     }
   }
   if (flags.mcp) {
-    const { startMcpServer } = await import("./server-TDSMX4PG.js");
+    const { startMcpServer } = await import("./server-K4Z4PEO3.js");
     await startMcpServer();
     return;
   }

package/dist/index.d.ts

@@ -8,6 +8,7 @@ interface CommandOptions {
     cwd?: string;
     save?: boolean;
     cache?: boolean;
+    ctx?: "cli" | "mcp";
 }
 interface MapOptions extends CommandOptions {
     trackDependencies?: boolean;
@@ -35,6 +36,7 @@ interface MapResult {
     version: string;
     timestamp: string;
     cwd: string;
+    framework?: string;
     summary: {
         totalFiles: number;
         totalFolders: number;
@@ -160,6 +162,11 @@ interface TypeInfo {
     definition: string;
     isExported: boolean;
 }
+interface ConstantInfo {
+    name: string;
+    type: string;
+    isExported: boolean;
+}
 interface ContextResult {
     version: string;
     timestamp: string;
@@ -169,6 +176,7 @@ interface ContextResult {
     exports: string[];
     functions: FunctionInfo[];
     types: TypeInfo[];
+    constants?: ConstantInfo[];
 }
 interface AreaConfig {
     name: string;
@@ -284,9 +292,6 @@ interface AreaContextResult {
  * Comando MAP - Mapa do projeto usando Skott
  */
 
-/**
- * Executa o comando MAP
- */
 declare function map(options?: MapOptions): Promise<string>;
 
 /**
@@ -323,6 +328,51 @@ declare function impact(target: string, options?: ImpactOptions): Promise<string
  */
 declare function suggest(target: string, options?: SuggestOptions): Promise<string>;
 
+/**
+ * Sistema de dicas contextuais para CLI e MCP
+ *
+ * Gera instruções de uso corretas dependendo do contexto de execução.
+ * - CLI: "ai-tool impact Button"
+ * - MCP: "aitool_impact_analysis { target: 'Button' }"
+ *
+ * Também fornece "próximos passos" contextuais que guiam a IA ou
+ * o usuário para a ação mais relevante após cada comando.
+ */
+/**
+ * Contexto de execução: CLI (terminal) ou MCP (protocolo para IAs)
+ */
+type HintContext = "cli" | "mcp";
+/**
+ * Retorna a instrução de uso de um comando no formato correto (CLI ou MCP)
+ *
+ * @param command - Nome interno do comando (ex: "impact", "suggest")
+ * @param ctx - Contexto de execução
+ * @param params - Substituições de parâmetros (ex: { "<arquivo>": "Button.tsx" })
+ * @returns String de instrução formatada
+ */
+declare function hint(command: string, ctx: HintContext, params?: Record<string, string>): string;
+/**
+ * Gera seção de "Próximos passos" formatada para o contexto correto
+ *
+ * @param command - Comando que acabou de ser executado
+ * @param ctx - Contexto de execução (cli ou mcp)
+ * @returns String formatada com próximos passos
+ */
+declare function nextSteps(command: string, ctx: HintContext): string;
+/**
+ * Gera uma dica de recuperação quando algo dá errado.
+ * Sugere a ação mais relevante para o cenário de erro.
+ *
+ * @param errorType - Tipo de erro ocorrido
+ * @param ctx - Contexto de execução
+ * @param extra - Informação extra sobre o erro
+ * @returns String formatada com dica de recuperação
+ */
+type RecoveryErrorType = "file_not_found" | "area_not_found" | "no_results" | "no_firebase" | "no_areas_configured" | "symbol_not_found" | "index_failed" | "generic";
+declare function recoveryHint(errorType: RecoveryErrorType, ctx: HintContext, _extra?: {
+    command?: string;
+}): string;
+
 /**
  * Comando CONTEXT - Extrai assinaturas de funcoes e tipos de um arquivo
  * Também suporta --area para contexto consolidado de toda uma área
@@ -373,6 +423,7 @@ declare function areasInit(options?: InitOptions): Promise<string>;
  * Detecta automaticamente projetos Firebase e extrai informações
  * de triggers como path (Firestore) e schedule (cron).
  */
+
 /**
  * Informação de uma Cloud Function
  */
@@ -410,6 +461,7 @@ interface FunctionsOptions {
     format?: "text" | "json";
     cache?: boolean;
     trigger?: string;
+    ctx?: HintContext;
 }
 /**
  * Executa o comando FUNCTIONS
@@ -441,6 +493,7 @@ interface FindOptions {
     def?: boolean;
     refs?: boolean;
     cache?: boolean;
+    ctx?: HintContext;
 }
 /**
  * Representa uma ocorrência encontrada
@@ -691,55 +744,58 @@ declare function findBestMatch<T>(target: string, candidates: T[], extractKey?:
 declare function extractFileName(filePath: string): string;
 
 /**
- * Formatadores de mensagens de erro com sugestões inteligentes
+ * Formatadores de mensagens de erro com sugestoes inteligentes
  *
- * Todas as funções retornam strings formatadas para exibição,
- * com sugestões "você quis dizer?" e referência de comandos.
+ * Todas as funcoes recebem um parametro `ctx` (HintContext)
+ * que determina o formato das dicas de navegacao:
+ * - "cli": instrucoes no formato CLI (ex: "ai-tool impact Button")
+ * - "mcp": instrucoes no formato MCP (ex: "analyze__aitool_impact_analysis { target: 'Button' }")
  */
-/**
- * Referência rápida de comandos disponíveis
- */
-declare const COMMAND_REFERENCE: Record<string, string>;
+
 interface FormatFileNotFoundOptions {
     /** Termo buscado */
     target: string;
-    /** Lista de todos os arquivos disponíveis */
+    /** Lista de todos os arquivos disponiveis */
     allFiles: string[];
     /** Comando que gerou o erro (para contexto) */
     command?: string;
+    /** Contexto de execucao */
+    ctx?: HintContext;
 }
 /**
- * Formata mensagem de arquivo não encontrado
+ * Formata mensagem de arquivo nao encontrado
  *
- * Inclui sugestões de arquivos similares e referência de comandos.
+ * Inclui sugestoes de arquivos similares e referencia de comandos.
  */
 declare function formatFileNotFound(options: FormatFileNotFoundOptions): string;
 interface AreaInfo {
-    /** ID da área */
+    /** ID da area */
     id: string;
-    /** Número de arquivos na área */
+    /** Numero de arquivos na area */
     count: number;
 }
 interface FormatAreaNotFoundOptions {
     /** Termo buscado */
     target: string;
-    /** Lista de áreas disponíveis */
+    /** Lista de areas disponiveis */
     availableAreas: AreaInfo[];
+    /** Contexto de execucao */
+    ctx?: HintContext;
 }
 /**
- * Formata mensagem de área não encontrada
+ * Formata mensagem de area nao encontrada
  *
- * Inclui sugestões de áreas similares usando Levenshtein.
+ * Inclui sugestoes de areas similares usando Levenshtein.
  */
 declare function formatAreaNotFound(options: FormatAreaNotFoundOptions): string;
 /**
- * Formata mensagem de target obrigatório faltando
+ * Formata mensagem de target obrigatorio faltando
  */
-declare function formatMissingTarget(command: string): string;
+declare function formatMissingTarget(command: string, ctx?: HintContext): string;
 /**
- * Formata mensagem de comando inválido
+ * Formata mensagem de comando invalido
  */
-declare function formatInvalidCommand(command: string): string;
+declare function formatInvalidCommand(command: string, ctx?: HintContext): string;
 
 /**
  * Utilitários para detecção de Firebase Cloud Functions
@@ -879,4 +935,4 @@ declare function inferFileDescription(filePath: string, category: string): strin
 
 declare const VERSION: string;
 
-export { type AreaConfig, type AreaContextComponentInfo, type AreaContextFunctionInfo, type AreaContextResult, type AreaContextStoreInfo, type AreaContextTriggerInfo, type AreaContextTypeInfo, type AreaDetailResult, type AreaFile, type AreaInfo, type AreaOptions, type AreasConfigFile, type AreasOptions, type AreasResult, COMMAND_REFERENCE, type CloudFunctionInfo, type CommandOptions, type ContextOptions, type ContextResult, type DeadFile, type DeadOptions, type DeadResult, type DetectedArea, type FileCategory, type FileInfo, type FindMatch, type FindOptions, type FindResult, type FindSimilarOptions, type FolderStats, type FormatAreaNotFoundOptions, type FormatFileNotFoundOptions, type FunctionInfo, type FunctionsOptions, type FunctionsResult, type ImpactFile, type ImpactOptions, type ImpactResult, type ImportInfo$1 as ImportInfo, type MapOptions, type MapResult, type OutputFormat, type ParamInfo, type ProjectIndex, type RiskInfo, type SuggestOptions, type SuggestResult, type Suggestion, type SuggestionPriority, type SymbolInfo, type SymbolType, type TriggerInfo, type TypeInfo, type TypeKind, VERSION, area, areas, areasInit, categoryIcons, clearFirebaseCache, configExists, context, dead, deadFix, detectCategory, detectFileAreas, extractFileName, filterCloudFunctionsFalsePositives, find, findBestMatch, findSimilar, formatAreaNotFound, formatFileNotFound, formatInvalidCommand, formatMissingTarget, functions, getAreaDescription, getAreaName, getCacheDir, getFileDescription, hasFirebaseFunctions, impact, inferFileDescription, invalidateCache, isCacheValid, isCodeFile, isEntryPoint, isExportedCloudFunction, isFileIgnored, isFirebaseProject, levenshteinDistance, map, readConfig, removeArea, setArea, setFileDescription, suggest, writeConfig };
+export { type AreaConfig, type AreaContextComponentInfo, type AreaContextFunctionInfo, type AreaContextResult, type AreaContextStoreInfo, type AreaContextTriggerInfo, type AreaContextTypeInfo, type AreaDetailResult, type AreaFile, type AreaInfo, type AreaOptions, type AreasConfigFile, type AreasOptions, type AreasResult, type CloudFunctionInfo, type CommandOptions, type ContextOptions, type ContextResult, type DeadFile, type DeadOptions, type DeadResult, type DetectedArea, type FileCategory, type FileInfo, type FindMatch, type FindOptions, type FindResult, type FindSimilarOptions, type FolderStats, type FormatAreaNotFoundOptions, type FormatFileNotFoundOptions, type FunctionInfo, type FunctionsOptions, type FunctionsResult, type HintContext, type ImpactFile, type ImpactOptions, type ImpactResult, type ImportInfo$1 as ImportInfo, type MapOptions, type MapResult, type OutputFormat, type ParamInfo, type ProjectIndex, type RecoveryErrorType, type RiskInfo, type SuggestOptions, type SuggestResult, type Suggestion, type SuggestionPriority, type SymbolInfo, type SymbolType, type TriggerInfo, type TypeInfo, type TypeKind, VERSION, area, areas, areasInit, categoryIcons, clearFirebaseCache, configExists, context, dead, deadFix, detectCategory, detectFileAreas, extractFileName, filterCloudFunctionsFalsePositives, find, findBestMatch, findSimilar, formatAreaNotFound, formatFileNotFound, formatInvalidCommand, formatMissingTarget, functions, getAreaDescription, getAreaName, getCacheDir, getFileDescription, hasFirebaseFunctions, hint, impact, inferFileDescription, invalidateCache, isCacheValid, isCodeFile, isEntryPoint, isExportedCloudFunction, isFileIgnored, isFirebaseProject, levenshteinDistance, map, nextSteps, readConfig, recoveryHint, removeArea, setArea, setFileDescription, suggest, writeConfig };

package/dist/index.js

@@ -1,5 +1,4 @@
 import {
-  COMMAND_REFERENCE,
   VERSION,
   area,
   areas,
@@ -27,6 +26,7 @@ import {
   getCacheDir,
   getFileDescription,
   hasFirebaseFunctions,
+  hint,
   impact,
   inferFileDescription,
   invalidateCache,
@@ -38,15 +38,16 @@ import {
   isFirebaseProject,
   levenshteinDistance,
   map,
+  nextSteps,
   readConfig,
+  recoveryHint,
   removeArea,
   setArea,
   setFileDescription,
   suggest,
   writeConfig
-} from "./chunk-J3MX6NK3.js";
+} from "./chunk-4HAUIZQ7.js";
 export {
-  COMMAND_REFERENCE,
   VERSION,
   area,
   areas,
@@ -74,6 +75,7 @@ export {
   getCacheDir,
   getFileDescription,
   hasFirebaseFunctions,
+  hint,
   impact,
   inferFileDescription,
   invalidateCache,
@@ -85,7 +87,9 @@ export {
   isFirebaseProject,
   levenshteinDistance,
   map,
+  nextSteps,
   readConfig,
+  recoveryHint,
   removeArea,
   setArea,
   setFileDescription,