plazbot-cli 0.2.26 → 0.3.2

package/src/commands/agent/get.ts

@@ -1,17 +1,19 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { AgentCommandOptions } from '../../types/agent';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { describeAgentLoadError } from '../../utils/agent-errors.js';
+import { AgentCommandOptions } from '../../types/agent.js';
 import chalk from 'chalk';
 
 export const getCommand = new Command('get')
-  .description('Obtiene información detallada de un agente específico')
-  .argument('<agentId>', 'ID del agente a consultar')
-  .option('-w, --workspace <id>', 'Workspace ID (sobreescribe config local)')
-  .option('-z, --zone <zone>', 'Zona LA o EU (sobreescribe config local)')
-  .option('--raw', 'Mostrar el JSON completo sin formatear', false)
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Get detailed information about a specific agent')
+  .argument('<agentId>', 'Agent ID to fetch')
+  .option('-w, --workspace <id>', 'Workspace ID (overrides local config)')
+  .option('-z, --zone <zone>', 'Zone LA or EU (overrides local config)')
+  .option('--raw', 'Show full unformatted JSON', false)
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: AgentCommandOptions & { raw: boolean; workspace?: string; zone?: string }) => {
     try {
       const credentials = await getStoredCredentials();
@@ -20,7 +22,7 @@ export const getCommand = new Command('get')
       const effectiveZone = (options.zone?.toUpperCase() === 'EU' ? 'EU' : options.zone?.toUpperCase() === 'LA' ? 'LA' : credentials.zone) as 'LA' | 'EU';
 
       if (options.workspace || options.zone) {
-        console.log(chalk.hex('#FFA726')(`\n  Modo soporte: workspace=${effectiveWorkspace} zona=${effectiveZone}`));
+        console.log(chalk.hex('#FFA726')(`\n  Support mode: workspace=${effectiveWorkspace} zone=${effectiveZone}`));
       }
 
       const agent = new Agent({
@@ -53,23 +55,23 @@ export const getCommand = new Command('get')
 
       console.log();
       console.log(chalk.hex('#4CAF50')('  ┌' + '─'.repeat(58) + '┐'));
-      console.log(chalk.hex('#4CAF50')('  │') + chalk.bold(`  ${agentData.name || 'Agente'}`).padEnd(68) + chalk.hex('#4CAF50')('│'));
+      console.log(chalk.hex('#4CAF50')('  │') + chalk.bold(`  ${agentData.name || 'Agent'}`).padEnd(68) + chalk.hex('#4CAF50')('│'));
       console.log(chalk.hex('#4CAF50')('  │') + chalk.gray(`  ${agentId}`).padEnd(68) + chalk.hex('#4CAF50')('│'));
       console.log(chalk.hex('#4CAF50')('  └' + '─'.repeat(58) + '┘'));
 
       // Informacion basica
-      sectionHeader('Informacion Basica');
+      sectionHeader('Basic Information');
       label('ID', agentData.id);
-      label('Nombre', agentData.name);
-      label('Descripcion', agentData.description);
-      label('Estado', agentData.enable ? chalk.hex('#66BB6A')('Activo') : chalk.hex('#EF5350')('Inactivo'));
-      label('Zona', agentData.zone);
+      label('Name', agentData.name);
+      label('Description', agentData.description);
+      label('Status', agentData.enable ? chalk.hex('#66BB6A')('Active') : chalk.hex('#EF5350')('Inactive'));
+      label('Zone', agentData.zone);
       label('Buffer', agentData.buffer);
       label('Color', agentData.color);
-      label('Pregunta inicial', agentData.question);
-      label('Zona horaria', agentData.timezone);
-      label('Mostrar en chat', agentData.showInChat ? 'Si' : 'No');
-      label('Tool Calling', agentData.useToolCalling ? 'Activado' : 'Desactivado');
+      label('Initial question', agentData.question);
+      label('Timezone', agentData.timezone);
+      label('Show in chat', agentData.showInChat ? 'Yes' : 'No');
+      label('Tool Calling', agentData.useToolCalling ? 'Enabled' : 'Disabled');
 
       // Tags
       if (agentData.tags && agentData.tags.length > 0) {
@@ -87,7 +89,7 @@ export const getCommand = new Command('get')
 
       // Ejemplos
       if (agentData.examples && agentData.examples.length > 0) {
-        sectionHeader('Ejemplos');
+        sectionHeader('Examples');
         agentData.examples.forEach((example: any) => {
           console.log(chalk.white(`  - ${example.value || example}`));
         });
@@ -95,64 +97,64 @@ export const getCommand = new Command('get')
 
       // Instrucciones
       if (agentData.instructions) {
-        sectionHeader('Instrucciones');
+        sectionHeader('Instructions');
         const inst = agentData.instructions;
-        label('Tono', inst.tone);
-        label('Estilo', inst.style);
-        label('Personalidad', inst.personality);
-        label('Objetivo', inst.objective);
-        label('Idioma', inst.language);
-        label('Emojis', inst.emojis ? 'Si' : 'No');
-        label('Formato preferido', inst.preferredFormat);
-        label('Max palabras', inst.maxWords);
+        label('Tone', inst.tone);
+        label('Style', inst.style);
+        label('Personality', inst.personality);
+        label('Objective', inst.objective);
+        label('Language', inst.language);
+        label('Emojis', inst.emojis ? 'Yes' : 'No');
+        label('Preferred format', inst.preferredFormat);
+        label('Max words', inst.maxWords);
         if (inst.avoidTopics && inst.avoidTopics.length > 0) {
-          label('Temas a evitar', inst.avoidTopics.join(', '));
+          label('Topics to avoid', inst.avoidTopics.join(', '));
         }
-        label('Solo responder si sabe', inst.respondOnlyIfKnows ? 'Si' : 'No');
-        label('Saludo', inst.greeting);
+        label('Only respond if known', inst.respondOnlyIfKnows ? 'Yes' : 'No');
+        label('Greeting', inst.greeting);
       }
 
       // Persona
       if (agentData.person) {
         sectionHeader('Persona');
         const p = agentData.person;
-        label('Nombre', p.name);
-        label('Rol', p.role);
-        label('Primera persona', p.speaksInFirstPerson ? 'Si' : 'No');
-        label('Es humano', p.isHuman ? 'Si' : 'No');
+        label('Name', p.name);
+        label('Role', p.role);
+        label('First person', p.speaksInFirstPerson ? 'Yes' : 'No');
+        label('Is human', p.isHuman ? 'Yes' : 'No');
       }
 
       // Fallbacks
       if (agentData.fallbacks) {
         sectionHeader('Fallbacks');
         const fb = agentData.fallbacks;
-        label('Sin respuesta', fb.noAnswer);
-        label('Error de servicio', fb.serviceError);
-        label('No entiende', fb.doNotUnderstand);
+        label('No answer', fb.noAnswer);
+        label('Service error', fb.serviceError);
+        label('Does not understand', fb.doNotUnderstand);
       }
 
       // Reglas
       if (agentData.rules) {
-        sectionHeader('Reglas');
+        sectionHeader('Rules');
         const r = agentData.rules;
-        label('No mencionar precios', r.doNotMentionPrices ? 'Si' : 'No');
-        label('No diagnosticar', r.doNotDiagnose ? 'Si' : 'No');
+        label('Do not mention prices', r.doNotMentionPrices ? 'Yes' : 'No');
+        label('Do not diagnose', r.doNotDiagnose ? 'Yes' : 'No');
         if (r.doNotRespondOutsideHours) {
-          label('Fuera de horario', r.doNotRespondOutsideHours);
+          label('Out of hours', r.doNotRespondOutsideHours);
         }
       }
 
       // Servicios
       if (agentData.services && agentData.services.length > 0) {
-        sectionHeader(`Servicios (${agentData.services.length})`);
+        sectionHeader(`Services (${agentData.services.length})`);
         agentData.services.forEach((svc: any, i: number) => {
-          console.log(chalk.hex('#2196F3')(`  ${i + 1}. ${svc.intent || svc.reference || 'Servicio'}`));
-          label('    Referencia', svc.reference);
-          label('    Habilitado', svc.enabled ? 'Si' : 'No');
-          label('    Metodo', svc.method);
+          console.log(chalk.hex('#2196F3')(`  ${i + 1}. ${svc.intent || svc.reference || 'Service'}`));
+          label('    Reference', svc.reference);
+          label('    Enabled', svc.enabled ? 'Yes' : 'No');
+          label('    Method', svc.method);
           label('    Endpoint', svc.endpoint);
           if (svc.requiredFields && svc.requiredFields.length > 0) {
-            console.log(chalk.gray('    Campos:'));
+            console.log(chalk.gray('    Fields:'));
             svc.requiredFields.forEach((f: any) => {
               console.log(chalk.white(`      - ${f.name} (${f.type}): ${f.description || ''}`));
             });
@@ -162,17 +164,17 @@ export const getCommand = new Command('get')
 
       // Acciones
       if (agentData.actions && agentData.actions.length > 0) {
-        sectionHeader(`Acciones (${agentData.actions.length})`);
+        sectionHeader(`Actions (${agentData.actions.length})`);
         agentData.actions.forEach((act: any, i: number) => {
-          console.log(chalk.hex('#FFA726')(`  ${i + 1}. ${act.intent || act.reference || 'Accion'}`));
-          label('    Referencia', act.reference);
-          label('    Habilitado', act.enabled ? 'Si' : 'No');
+          console.log(chalk.hex('#FFA726')(`  ${i + 1}. ${act.intent || act.reference || 'Action'}`));
+          label('    Reference', act.reference);
+          label('    Enabled', act.enabled ? 'Yes' : 'No');
           if (act.tags && act.tags.length > 0) {
             label('    Tags', act.tags.join(', '));
           }
-          label('    Respuesta', act.responseMessage);
+          label('    Response', act.responseMessage);
           if (act.action && act.action.length > 0) {
-            console.log(chalk.gray('    Sub-acciones:'));
+            console.log(chalk.gray('    Sub-actions:'));
             act.action.forEach((sa: any) => {
               console.log(chalk.white(`      - ${sa.type}: ${sa.value || ''}`));
             });
@@ -182,32 +184,50 @@ export const getCommand = new Command('get')
 
       // Canales
       if (agentData.channels && agentData.channels.length > 0) {
-        sectionHeader(`Canales (${agentData.channels.length})`);
+        sectionHeader(`Channels (${agentData.channels.length})`);
         agentData.channels.forEach((ch: any) => {
-          console.log(chalk.white(`  ${chalk.hex('#22d3ee')(ch.channel || 'canal')}: ${ch.key || ''}`));
+          console.log(chalk.white(`  ${chalk.hex('#22d3ee')(ch.channel || 'channel')}: ${ch.key || ''}`));
         });
       }
 
       // AI Config
       if (agentData.customAIConfig && agentData.aiProviders && agentData.aiProviders.length > 0) {
-        sectionHeader('Modelo IA');
+        sectionHeader('AI Model');
         agentData.aiProviders.forEach((ai: any) => {
-          label('Proveedor', ai.provider);
-          label('Modelo', ai.model);
+          label('Provider', ai.provider);
+          label('Model', ai.model);
         });
       }
 
       console.log();
-      console.log(chalk.gray('  Usa --raw para ver el JSON completo'));
+      console.log(chalk.gray('  Use --raw to see the full JSON'));
       console.log();
 
       if (options.dev) {
-        logger.warning('Ambiente: desarrollo');
+        logger.warning('Environment: development');
       }
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido al obtener el agente';
-      logger.error(message);
+      const credentials = await getStoredCredentials().catch(() => null);
+      if (credentials) {
+        logger.error(describeAgentLoadError(error, agentId, credentials, {
+          dev: options.dev,
+          workspaceOverride: options.workspace,
+          zoneOverride: options.zone,
+        }));
+      } else {
+        const message = error instanceof Error ? error.message : 'Unknown error while fetching the agent';
+        logger.error(message);
+      }
       process.exit(1);
     }
-  }); 
+  });
+
+addExamples(getCommand, [
+  { description: 'Show the agent in a human-friendly layout',
+    command: 'plazbot agent get agt_AbcDef123' },
+  { description: 'Dump the full raw JSON (useful for piping to jq)',
+    command: 'plazbot agent get agt_AbcDef123 --raw' },
+  { description: 'Inspect an agent from another workspace (support mode)',
+    command: 'plazbot agent get agt_AbcDef123 -w wok_Other123 -z LA' },
+]);

package/src/commands/agent/index.ts

@@ -1,23 +1,25 @@
 import { Command } from 'commander';
-import { listCommand } from './list';
-import { getCommand } from './get';
-import { deleteCommand } from './delete';
-import { createCommand } from './create';
-import { updateCommand } from './update';
-import { enableCommand } from './enable-widget';
-import { chatCommand } from './chat';
-import { messageCommand } from './on-message';
-import { toolsCommand } from './tools';
-import { aiConfigCommand } from './ai-config';
-import { templatesCommand } from './templates';
-import { copyCommand } from './copy';
-import { filesCommand } from './files';
-import { setCommand } from './set';
-import { monitorCommand } from './monitor';
-import { exportCommand, crossCopyCommand } from './export';
+import { addExamples } from '../../utils/help.js';
+import { listCommand } from './list.js';
+import { getCommand } from './get.js';
+import { deleteCommand } from './delete.js';
+import { createCommand } from './create.js';
+import { updateCommand } from './update.js';
+import { enableCommand } from './enable-widget.js';
+import { chatCommand } from './chat.js';
+import { messageCommand } from './on-message.js';
+import { toolsCommand } from './tools.js';
+import { aiConfigCommand } from './ai-config.js';
+import { templatesCommand } from './templates.js';
+import { copyCommand } from './copy.js';
+import { filesCommand } from './files.js';
+import { setCommand } from './set.js';
+import { monitorCommand } from './monitor.js';
+import { exportCommand, crossCopyCommand } from './export.js';
+import { validateCommand } from './validate.js';
 
 export const agentCommands = new Command('agent')
-  .description('Comandos relacionados con agentes de IA')
+  .description('Commands related to AI agents')
   .addCommand(listCommand)
   .addCommand(getCommand)
   .addCommand(deleteCommand)
@@ -34,4 +36,20 @@ export const agentCommands = new Command('agent')
   .addCommand(setCommand)
   .addCommand(monitorCommand)
   .addCommand(exportCommand)
-  .addCommand(crossCopyCommand);
+  .addCommand(crossCopyCommand)
+  .addCommand(validateCommand);
+
+addExamples(agentCommands, [
+  { description: 'List agents in the active workspace',
+    command: 'plazbot agent list' },
+  { description: 'Chat interactively with an agent',
+    command: 'plazbot agent chat agt_AbcDef123' },
+  { description: 'Create an agent from a JSON template',
+    command: 'plazbot agent create ./agent.json' },
+  { description: 'Export an agent and copy it to another workspace',
+    command: 'plazbot agent cross-copy agt_AbcDef123 --from-workspace wok_Source --to-workspace wok_Target' },
+  { description: 'Monitor activity of an agent in real time',
+    command: 'plazbot agent monitor agt_AbcDef123' },
+  { description: 'Validate a local agent JSON file against the schema',
+    command: 'plazbot agent validate ./agent.json' },
+]);

package/src/commands/agent/list.ts

@@ -1,12 +1,13 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { ListAgentsOptions } from '../../types/agent';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { ListAgentsOptions } from '../../types/agent.js';
 
 export const listCommand = new Command('list')
-  .description('Lista todos los agentes del workspace')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('List all agents in the workspace')
+  .option('--dev', 'Use development environment (localhost:5090)', false)
   .action(async (options: ListAgentsOptions) => {
     try {
       // Obtener credenciales guardadas
@@ -24,29 +25,34 @@ export const listCommand = new Command('list')
       const agents = await agent.getAgents();
       
       if (agents.length === 0) {
-        logger.info('No se encontraron agentes en este workspace');
+        logger.info('No agents found in this workspace');
         return;
       }
 
-      logger.info('\nLista de Agentes:');
+      logger.info('\nAgents:');
       logger.doubleDivider();
-      
+
       agents.forEach((a: any, index: number) => {
         logger.info(`${index + 1}. ID: ${a.id}`);
-        logger.info(`   Nombre: ${a.name}`);
-        logger.info(`   Estado: ${a.enable ? 'Activo' : 'Inactivo'}`);
-        logger.info(`   Descripción: ${a.description}`);
-        logger.info(`   Creado: ${a.createdAt ? new Date(a.createdAt).toLocaleString() : 'N/A'}`);
+        logger.info(`   Name: ${a.name}`);
+        logger.info(`   Status: ${a.enable ? 'Active' : 'Inactive'}`);
+        logger.info(`   Description: ${a.description}`);
+        logger.info(`   Created: ${a.createdAt ? new Date(a.createdAt).toLocaleString() : 'N/A'}`);
         logger.divider();
       });
 
       if (options.dev) {
-        logger.warning('Ambiente: desarrollo');
+        logger.warning('Environment: development');
       }
-      
+
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido al listar agentes';
+      const message = error instanceof Error ? error.message : 'Unknown error while listing agents';
       logger.error(message);
       process.exit(1);
     }
-  }); 
+  });
+
+addExamples(listCommand, [
+  { description: 'List every agent in the active workspace',     command: 'plazbot agent list' },
+  { description: 'List against a local backend (dev mode)',      command: 'plazbot agent list --dev' },
+]);