nex-framework-cli 1.0.6 → 1.0.9

package/cli/nex-cli.js

@@ -15,17 +15,51 @@ const __dirname = path.dirname(__filename)
 
 const program = new Command()
 
+// Custom help formatting
+program.configureHelp({
+  helpWidth: 100,
+  sortSubcommands: true,
+  subcommandTerm: (cmd) => {
+    const aliases = cmd.aliases().length > 0 ? `|${cmd.aliases().join('|')}` : ''
+    return chalk.cyan(`${cmd.name()}${aliases}`)
+  }
+})
+
 program
   .name('nex')
   .description('NEX Framework - Framework completo de agentes AI')
-  .version('1.0.0')
+  .version('1.0.8', '-v, --version', 'Mostra a versão')
+  .addHelpText('before', chalk.bold.cyan(`
+╔════════════════════════════════════════════════════════════════╗
+║              NEX Framework - CLI v1.0.8                        ║
+║         Framework completo de agentes AI                        ║
+╚════════════════════════════════════════════════════════════════╝
+`))
+  .addHelpText('after', chalk.gray(`
+📚 Exemplos rápidos:
+  ${chalk.cyan('nex agent list --all')}              Lista todos os agentes disponíveis
+  ${chalk.cyan('nex agent search planning')}        Busca agentes por termo
+  ${chalk.cyan('nex agent install anx')}             Instala um agente
+  ${chalk.cyan('nex agent info anx')}               Mostra informações de um agente
+
+📖 Para mais informações sobre um comando:
+  ${chalk.cyan('nex <comando> --help')}             Ex: nex agent --help
+
+🔗 Documentação: https://github.com/INOSX/nex-store
+`))
 
 // Comando: init
 program
   .command('init')
   .description('Inicializa um novo projeto NEX')
   .option('-n, --name <name>', 'Nome do projeto')
-  .option('-t, --template <template>', 'Template a usar')
+  .option('-t, --template <template>', 'Template a usar (blank, full-stack, api-only, mobile)')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex init')}                         Inicializa projeto interativamente
+  ${chalk.cyan('nex init -n meu-projeto')}          Inicializa com nome específico
+  ${chalk.cyan('nex init -t full-stack')}           Usa template full-stack
+`))
   .action(async (options) => {
     console.log(chalk.blue('🚀 Inicializando projeto NEX...'))
     
@@ -60,6 +94,14 @@ program
 program
   .command('plan')
   .description('Gera plano completo do projeto (PRD, arquitetura, etc.)')
+  .option('-r, --requirements <file>', 'Arquivo de requisitos JSON')
+  .option('-o, --output <dir>', 'Diretório de saída')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex plan')}                         Gera plano interativamente
+  ${chalk.cyan('nex plan -r requirements.json')}    Usa arquivo de requisitos
+  ${chalk.cyan('nex plan -o ./docs')}              Salva em diretório específico
+`))
   .option('-r, --requirements <file>', 'Arquivo de requisitos')
   .option('-o, --output <dir>', 'Diretório de saída')
   .action(async (options) => {
@@ -104,14 +146,24 @@ program
 const agentCmd = program
   .command('agent')
   .description('Gerencia agentes do NEX Marketplace')
+  .addHelpText('before', chalk.bold('\n📦 Marketplace de Agentes\n'))
+  .addHelpText('after', chalk.gray(`
+💡 Dica: Use ${chalk.cyan('nex agent list --all')} para ver todos os agentes disponíveis
+`))
 
 // agent search
 agentCmd
   .command('search <query>')
-  .description('Busca agentes no marketplace')
-  .option('-c, --category <category>', 'Filtrar por categoria')
+  .description('Busca agentes no marketplace por termo')
+  .option('-c, --category <category>', 'Filtrar por categoria (planning, execution, community)')
   .option('--official', 'Apenas agentes oficiais')
   .option('-l, --limit <number>', 'Limitar resultados', '50')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent search planning')}              Busca por "planning"
+  ${chalk.cyan('nex agent search "análise" --official')}  Busca apenas oficiais
+  ${chalk.cyan('nex agent search "" --category planning')} Lista todos de planejamento
+`))
   .action(async (query, options) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -121,9 +173,15 @@ agentCmd
 // agent install
 agentCmd
   .command('install <agentId>')
-  .description('Instala um agente')
+  .description('Instala um agente no projeto atual')
   .option('-v, --version <version>', 'Versão específica')
   .option('-m, --method <method>', 'Método de instalação (symlink|copy)')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent install anx')}                    Instala o agente ANX
+  ${chalk.cyan('nex agent install anx -v 1.0.0')}          Instala versão específica
+  ${chalk.cyan('nex agent install anx -m copy')}           Instala usando cópia
+`))
   .action(async (agentId, options) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -134,10 +192,17 @@ agentCmd
 agentCmd
   .command('list')
   .alias('ls')
-  .description('Lista agentes instalados')
-  .option('-a, --all', 'Mostrar todos os agentes disponíveis no marketplace')
-  .option('-c, --category <category>', 'Filtrar por categoria')
+  .description('Lista agentes instalados ou todos os agentes disponíveis no marketplace')
+  .option('-a, --all', 'Listar todos os agentes disponíveis no marketplace')
+  .option('-c, --category <category>', 'Filtrar por categoria (planning, execution, community)')
   .option('--official', 'Apenas agentes oficiais')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent list --all')}                          Lista todos os agentes disponíveis
+  ${chalk.cyan('nex agent list')}                                Lista apenas agentes instalados
+  ${chalk.cyan('nex agent list --all --category planning')}      Lista agentes de planejamento
+  ${chalk.cyan('nex agent list --all --official')}               Lista apenas agentes oficiais
+`))
   .action(async (options) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -155,6 +220,11 @@ agentCmd
 agentCmd
   .command('info <agentId>')
   .description('Mostra informações detalhadas do agente')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent info anx')}              Informações do agente ANX
+  ${chalk.cyan('nex agent info pmx')}              Informações do agente PMX
+`))
   .action(async (agentId) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -165,7 +235,12 @@ agentCmd
 agentCmd
   .command('uninstall <agentId>')
   .alias('remove')
-  .description('Remove um agente instalado')
+  .description('Remove um agente instalado do projeto')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent uninstall anx')}          Remove o agente ANX
+  ${chalk.cyan('nex agent remove anx')}             Alias para uninstall
+`))
   .action(async (agentId) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -175,8 +250,13 @@ agentCmd
 // agent update
 agentCmd
   .command('update [agentId]')
-  .description('Atualiza agente(s)')
-  .option('-a, --all', 'Atualizar todos os agentes')
+  .description('Atualiza agente(s) para a versão mais recente')
+  .option('-a, --all', 'Atualizar todos os agentes instalados')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent update anx')}              Atualiza o agente ANX
+  ${chalk.cyan('nex agent update --all')}           Atualiza todos os agentes
+`))
   .action(async (agentId, options) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -197,6 +277,10 @@ agentCmd
 agentCmd
   .command('register <agentId>')
   .description('Registra um agente no NEX Hub para uso')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent register anx')}           Registra o agente ANX no Hub
+`))
   .action(async (agentId) => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()
@@ -208,6 +292,11 @@ agentCmd
   .command('my-agents')
   .alias('registered')
   .description('Lista agentes registrados no NEX Hub')
+  .addHelpText('after', chalk.gray(`
+Exemplos:
+  ${chalk.cyan('nex agent my-agents')}              Lista seus agentes registrados
+  ${chalk.cyan('nex agent registered')}             Alias para my-agents
+`))
   .action(async () => {
     const { default: NEXMarketplace } = await import('../src/services/nex-marketplace/NEXMarketplace.js')
     const marketplace = new NEXMarketplace()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nex-framework-cli",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "description": "NEX CLI - Command-line interface for NEX Framework and Agent Marketplace",
   "type": "module",
   "main": "cli/nex-cli.js",

package/src/services/nex-marketplace/NEXMarketplace.js

@@ -102,28 +102,46 @@ export default class NEXMarketplace {
     
     try {
       let results = []
+      let apiError = null
       
-      // Search in Supabase if available
-      if (this.supabase) {
-        results = await this.searchRemote(query, options)
+      // Try remote search first
+      if (this.apiUrl || this.supabase) {
+        try {
+          results = await this.searchRemote(query, options)
+        } catch (error) {
+          apiError = error
+          // Continue with local search only
+          console.warn(chalk.yellow(`\n⚠️  Could not connect to marketplace: ${error.message}`))
+          console.log(chalk.gray('   Searching local registry only...\n'))
+        }
       }
       
-      // Also search local registry
+      // Always search local registry
       const localResults = await this.searchLocal(query, options)
       
       // Merge results (deduplicate by agent_id)
       const merged = this.mergeResults(results, localResults)
       
-      spinner.succeed(`Found ${merged.length} agents`)
+      if (merged.length > 0) {
+        spinner.succeed(`Found ${merged.length} agents`)
+      } else {
+        spinner.warn('No agents found')
+      }
       
       // Display results
       this.displaySearchResults(merged)
       
+      // Show warning if API failed
+      if (apiError && localResults.length > 0) {
+        console.log(chalk.yellow('\n💡 Tip: Some results may be missing. Check your connection.\n'))
+      }
+      
       return merged
       
     } catch (error) {
       spinner.fail('Search failed')
-      console.error(chalk.red(`Error: ${error.message}`))
+      console.error(chalk.red(`\nError: ${error.message}`))
+      console.log(chalk.gray('\n💡 Try searching locally or check your connection.\n'))
       throw error
     }
   }
@@ -149,20 +167,38 @@ export default class NEXMarketplace {
    * Search via Edge Function API (SEGURO - sem anon key)
    */
   async searchViaAPI(query, options = {}) {
-    const params = new URLSearchParams()
-    if (query) params.append('q', query)
-    if (options.category) params.append('category', options.category)
-    if (options.official) params.append('official', 'true')
-    if (options.limit) params.append('limit', options.limit.toString())
-    
-    const response = await fetch(`${this.apiUrl}/search?${params}`)
-    
-    if (!response.ok) {
-      throw new Error(`API error: ${response.statusText}`)
+    try {
+      const params = new URLSearchParams()
+      if (query) params.append('q', query)
+      if (options.category) params.append('category', options.category)
+      if (options.official) params.append('official', 'true')
+      if (options.limit) params.append('limit', options.limit.toString())
+      
+      // Timeout de 10 segundos
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), 10000)
+      
+      const response = await fetch(`${this.apiUrl}/search?${params}`, {
+        signal: controller.signal
+      })
+      
+      clearTimeout(timeoutId)
+      
+      if (!response.ok) {
+        throw new Error(`API error: ${response.statusText}`)
+      }
+      
+      const { agents } = await response.json()
+      return agents || []
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error('Connection timeout. The marketplace API is not responding.')
+      }
+      if (error.code === 'UND_ERR_CONNECT_TIMEOUT' || error.message.includes('timeout')) {
+        throw new Error('Connection timeout. Please check your internet connection or try again later.')
+      }
+      throw error
     }
-    
-    const { agents } = await response.json()
-    return agents || []
   }
 
   /**
@@ -173,30 +209,66 @@ export default class NEXMarketplace {
     
     try {
       let results = []
+      let apiError = null
       
-      // List from API/Remote if available
+      // Try API/Remote first
       if (this.apiUrl) {
-        results = await this.listAllViaAPI(options)
+        try {
+          results = await this.listAllViaAPI(options)
+        } catch (error) {
+          apiError = error
+          console.warn(chalk.yellow(`\n⚠️  Could not connect to marketplace API: ${error.message}`))
+          console.log(chalk.gray('   Falling back to local registry...\n'))
+          
+          // Try Supabase client as fallback
+          if (this.supabase) {
+            try {
+              results = await this.listAllViaClient(options)
+            } catch (clientError) {
+              // If both fail, continue with local only
+              results = []
+            }
+          }
+        }
       } else if (this.supabase) {
-        results = await this.listAllViaClient(options)
+        try {
+          results = await this.listAllViaClient(options)
+        } catch (error) {
+          apiError = error
+          results = []
+        }
       }
       
-      // Also include local registry
+      // Always include local registry
       const localResults = await this.searchLocal('', options)
       
       // Merge results
       const merged = this.mergeResults(results, localResults)
       
-      spinner.succeed(`Found ${merged.length} available agents`)
+      if (merged.length > 0) {
+        spinner.succeed(`Found ${merged.length} available agents`)
+      } else {
+        spinner.warn('No agents found')
+      }
       
       // Display results
       this.displaySearchResults(merged)
       
+      // Show warning if API failed but we have local results
+      if (apiError && localResults.length > 0) {
+        console.log(chalk.yellow('\n💡 Tip: Some agents may be missing. Check your connection or configure NEX_MARKETPLACE_API_URL\n'))
+      }
+      
       return merged
       
     } catch (error) {
       spinner.fail('Failed to load agents')
-      console.error(chalk.red(`Error: ${error.message}`))
+      console.error(chalk.red(`\nError: ${error.message}`))
+      console.log(chalk.gray('\n💡 Troubleshooting:'))
+      console.log(chalk.gray('   1. Check your internet connection'))
+      console.log(chalk.gray('   2. Verify the API URL: ' + (this.apiUrl || 'not configured')))
+      console.log(chalk.gray('   3. Try: nex agent list (shows only installed agents)'))
+      console.log(chalk.gray('   4. Configure custom API: export NEX_MARKETPLACE_API_URL=<your-url>\n'))
       throw error
     }
   }
@@ -205,14 +277,32 @@ export default class NEXMarketplace {
    * List all agents via Edge Function API
    */
   async listAllViaAPI(options = {}) {
-    const response = await fetch(`${this.apiUrl}/list`)
-    
-    if (!response.ok) {
-      throw new Error(`API error: ${response.statusText}`)
+    try {
+      // Timeout de 10 segundos
+      const controller = new AbortController()
+      const timeoutId = setTimeout(() => controller.abort(), 10000)
+      
+      const response = await fetch(`${this.apiUrl}/list`, {
+        signal: controller.signal
+      })
+      
+      clearTimeout(timeoutId)
+      
+      if (!response.ok) {
+        throw new Error(`API error: ${response.statusText}`)
+      }
+      
+      const { agents } = await response.json()
+      return agents || []
+    } catch (error) {
+      if (error.name === 'AbortError') {
+        throw new Error('Connection timeout. The marketplace API is not responding.')
+      }
+      if (error.code === 'UND_ERR_CONNECT_TIMEOUT' || error.message.includes('timeout')) {
+        throw new Error('Connection timeout. Please check your internet connection or try again later.')
+      }
+      throw error
     }
-    
-    const { agents } = await response.json()
-    return agents || []
   }
 
   /**