plazbot-cli 0.2.26 → 0.3.2

package/src/commands/agent/export.ts

@@ -1,8 +1,9 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { createSpinner } from '../../utils/ui';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { createSpinner } from '../../utils/ui.js';
 import chalk from 'chalk';
 import fs from 'fs';
 import path from 'path';
@@ -173,14 +174,14 @@ function cleanAgentForExport(agentData: any): any {
 }
 
 export const exportCommand = new Command('export')
-  .description('Exportar configuracion limpia de un agente (compatible con importacion)')
-  .argument('<agentId>', 'ID del agente a exportar')
-  .option('-w, --workspace <id>', 'Workspace ID origen (sobreescribe config local)')
-  .option('-z, --zone <zone>', 'Zona LA o EU (sobreescribe config local)')
-  .option('-o, --output <path>', 'Ruta del archivo de salida (.json)')
-  .option('--no-channels', 'Excluir canales de la exportacion')
-  .option('--no-ai', 'Excluir configuracion de IA personalizada')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Export a clean agent configuration (compatible with import)')
+  .argument('<agentId>', 'Agent ID to export')
+  .option('-w, --workspace <id>', 'Source workspace ID (overrides local config)')
+  .option('-z, --zone <zone>', 'Zone LA or EU (overrides local config)')
+  .option('-o, --output <path>', 'Output file path (.json)')
+  .option('--no-channels', 'Exclude channels from export')
+  .option('--no-ai', 'Exclude custom AI configuration')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: {
     workspace?: string;
     zone?: string;
@@ -196,7 +197,7 @@ export const exportCommand = new Command('export')
       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({
@@ -206,13 +207,13 @@ export const exportCommand = new Command('export')
         ...(options.dev && { customUrl: 'http://localhost:5090' }),
       });
 
-      const spinner = createSpinner('Obteniendo agente...');
+      const spinner = createSpinner('Fetching agent...');
       spinner.start();
 
       const response: any = await agent.getAgentById({ id: agentId });
       const agentData = response.agent || response.data || response;
 
-      spinner.succeed('Agente obtenido');
+      spinner.succeed('Agent fetched');
 
       // Limpiar para exportacion
       const cleaned = cleanAgentForExport(agentData);
@@ -233,35 +234,46 @@ export const exportCommand = new Command('export')
       if (options.output) {
         const outputPath = path.resolve(options.output);
         fs.writeFileSync(outputPath, jsonOutput, 'utf-8');
-        console.log(chalk.hex('#4ade80')(`\n  Exportado a: ${outputPath}`));
+        console.log(chalk.hex('#4ade80')(`\n  Exported to: ${outputPath}`));
       } else {
         console.log();
         console.log(jsonOutput);
       }
 
       console.log();
-      console.log(chalk.gray('  Este JSON es compatible con:'));
-      console.log(chalk.gray('  - plazbot agent create <archivo.json>'));
-      console.log(chalk.gray('  - Importar JSON en la plataforma (AgentTraining)'));
+      console.log(chalk.gray('  This JSON is compatible with:'));
+      console.log(chalk.gray('  - plazbot agent create <file.json>'));
+      console.log(chalk.gray('  - Importing JSON in the platform (AgentTraining)'));
       console.log();
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
   });
 
+addExamples(exportCommand, [
+  { description: 'Print the cleaned JSON to stdout',
+    command: 'plazbot agent export agt_AbcDef123' },
+  { description: 'Write the cleaned JSON to a file',
+    command: 'plazbot agent export agt_AbcDef123 -o ./agent.json' },
+  { description: 'Export without channels nor AI credentials (portable JSON)',
+    command: 'plazbot agent export agt_AbcDef123 -o ./agent.json --no-channels --no-ai' },
+  { description: 'Export from a different workspace (support mode)',
+    command: 'plazbot agent export agt_AbcDef123 -w wok_Other123 -z LA -o ./agent.json' },
+]);
+
 export const crossCopyCommand = new Command('cross-copy')
-  .description('Copiar un agente de un workspace a otro')
-  .argument('<agentId>', 'ID del agente a copiar')
-  .requiredOption('--from-workspace <id>', 'Workspace ID de origen')
-  .requiredOption('--to-workspace <id>', 'Workspace ID de destino')
-  .option('--from-zone <zone>', 'Zona del workspace origen (LA o EU)', 'LA')
-  .option('--to-zone <zone>', 'Zona del workspace destino (LA o EU)', 'LA')
-  .option('--no-channels', 'No copiar canales (recomendado)')
-  .option('--no-ai', 'No copiar configuracion de IA personalizada')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Copy an agent from one workspace to another')
+  .argument('<agentId>', 'Agent ID to copy')
+  .requiredOption('--from-workspace <id>', 'Source workspace ID')
+  .requiredOption('--to-workspace <id>', 'Target workspace ID')
+  .option('--from-zone <zone>', 'Source workspace zone (LA or EU)', 'LA')
+  .option('--to-zone <zone>', 'Target workspace zone (LA or EU)', 'LA')
+  .option('--no-channels', 'Do not copy channels (recommended)')
+  .option('--no-ai', 'Do not copy custom AI configuration')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: {
     fromWorkspace: string;
     toWorkspace: string;
@@ -278,16 +290,16 @@ export const crossCopyCommand = new Command('cross-copy')
 
       console.log();
       console.log(chalk.hex('#4CAF50')('  ┌' + '─'.repeat(58) + '┐'));
-      console.log(chalk.hex('#4CAF50')('  │') + chalk.bold('  Copiar agente entre workspaces').padEnd(68) + chalk.hex('#4CAF50')('│'));
+      console.log(chalk.hex('#4CAF50')('  │') + chalk.bold('  Copy agent between workspaces').padEnd(68) + chalk.hex('#4CAF50')('│'));
       console.log(chalk.hex('#4CAF50')('  └' + '─'.repeat(58) + '┘'));
       console.log();
-      console.log(chalk.gray(`  Origen:  ${options.fromWorkspace} (${fromZone})`));
-      console.log(chalk.gray(`  Destino: ${options.toWorkspace} (${toZone})`));
-      console.log(chalk.gray(`  Agente:  ${agentId}`));
+      console.log(chalk.gray(`  Source: ${options.fromWorkspace} (${fromZone})`));
+      console.log(chalk.gray(`  Target: ${options.toWorkspace} (${toZone})`));
+      console.log(chalk.gray(`  Agent:  ${agentId}`));
       console.log();
 
       // 1. Obtener agente del workspace origen
-      const spinnerGet = createSpinner('Obteniendo agente del workspace origen...');
+      const spinnerGet = createSpinner('Fetching agent from source workspace...');
       spinnerGet.start();
 
       const sourceAgent = new Agent({
@@ -301,11 +313,11 @@ export const crossCopyCommand = new Command('cross-copy')
       const agentData = response.agent || response.data || response;
 
       if (!agentData || !agentData.name) {
-        spinnerGet.fail('No se encontro el agente en el workspace origen');
+        spinnerGet.fail('Agent not found in source workspace');
         process.exit(1);
       }
 
-      spinnerGet.succeed(`Agente obtenido: ${agentData.name}`);
+      spinnerGet.succeed(`Agent fetched: ${agentData.name}`);
 
       // 2. Limpiar JSON
       const cleaned = cleanAgentForExport(agentData);
@@ -329,29 +341,29 @@ export const crossCopyCommand = new Command('cross-copy')
 
       // 3. Mostrar resumen
       console.log();
-      console.log(chalk.bold('  Configuracion a copiar:'));
-      console.log(chalk.gray(`  Nombre:       ${cleaned.name}`));
-      console.log(chalk.gray(`  Zona destino: ${cleaned.zone}`));
-      console.log(chalk.gray(`  Canales:      ${cleaned.channels?.length || 0}`));
-      console.log(chalk.gray(`  Servicios:    ${cleaned.services?.length || 0}`));
-      console.log(chalk.gray(`  Acciones:     ${cleaned.actions?.length || 0}`));
-      console.log(chalk.gray(`  AI Custom:    ${cleaned.customAIConfig ? 'Si' : 'No'}`));
+      console.log(chalk.bold('  Configuration to copy:'));
+      console.log(chalk.gray(`  Name:        ${cleaned.name}`));
+      console.log(chalk.gray(`  Target zone: ${cleaned.zone}`));
+      console.log(chalk.gray(`  Channels:    ${cleaned.channels?.length || 0}`));
+      console.log(chalk.gray(`  Services:    ${cleaned.services?.length || 0}`));
+      console.log(chalk.gray(`  Actions:     ${cleaned.actions?.length || 0}`));
+      console.log(chalk.gray(`  Custom AI:   ${cleaned.customAIConfig ? 'Yes' : 'No'}`));
       console.log();
 
       const { confirm } = await (inquirer as any).prompt([{
         type: 'confirm',
         name: 'confirm',
-        message: 'Crear este agente en el workspace destino?',
+        message: 'Create this agent in the target workspace?',
         default: true,
       }]);
 
       if (!confirm) {
-        console.log(chalk.gray('  Operacion cancelada.'));
+        console.log(chalk.gray('  Operation cancelled.'));
         return;
       }
 
       // 4. Crear en workspace destino
-      const spinnerCreate = createSpinner('Creando agente en workspace destino...');
+      const spinnerCreate = createSpinner('Creating agent in target workspace...');
       spinnerCreate.start();
 
       const targetAgent = new Agent({
@@ -364,24 +376,33 @@ export const crossCopyCommand = new Command('cross-copy')
       const result: any = await targetAgent.addAgent(cleaned);
 
       if (result?.success === false) {
-        spinnerCreate.fail(`Error: ${result.message || 'No se pudo crear el agente'}`);
+        spinnerCreate.fail(`Error: ${result.message || 'Could not create the agent'}`);
         process.exit(1);
       }
 
       const newId = result?.agentId || result?.id || result?.data?.agentId;
-      spinnerCreate.succeed('Agente creado exitosamente');
+      spinnerCreate.succeed('Agent created successfully');
 
       console.log();
       if (newId) {
-        console.log(chalk.hex('#4ade80')(`  Nuevo ID: ${newId}`));
+        console.log(chalk.hex('#4ade80')(`  New ID: ${newId}`));
       }
-      console.log(chalk.gray('  Widget deshabilitado por defecto.'));
-      console.log(chalk.gray('  Canales deben configurarse manualmente en el workspace destino.'));
+      console.log(chalk.gray('  Widget disabled by default.'));
+      console.log(chalk.gray('  Channels must be configured manually in the target workspace.'));
       console.log();
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
   });
+
+addExamples(crossCopyCommand, [
+  { description: 'Copy an agent between two LA workspaces (skip channels)',
+    command: 'plazbot agent cross-copy agt_AbcDef123 --from-workspace wok_Source123 --to-workspace wok_Target456' },
+  { description: 'Copy across zones (LA → EU)',
+    command: 'plazbot agent cross-copy agt_AbcDef123 --from-workspace wok_Source123 --from-zone LA --to-workspace wok_Target456 --to-zone EU' },
+  { description: 'Copy preserving channels and AI providers',
+    command: 'plazbot agent cross-copy agt_AbcDef123 --from-workspace wok_Source123 --to-workspace wok_Target456 --channels --ai' },
+]);

package/src/commands/agent/files.ts

@@ -1,18 +1,30 @@
 import { Command } from 'commander';
 import { Agent } from 'plazbot';
-import { getStoredCredentials } from '../../utils/credentials';
-import { logger } from '../../utils/logger';
-import { createSpinner, createTable, theme, section, statusBadge } from '../../utils/ui';
-import { AgentCommandOptions } from '../../types/agent';
+import { getStoredCredentials } from '../../utils/credentials.js';
+import { logger } from '../../utils/logger.js';
+import { addExamples } from '../../utils/help.js';
+import { createSpinner, createTable, theme, section, statusBadge } from '../../utils/ui.js';
+import { AgentCommandOptions } from '../../types/agent.js';
 
 const filesGroup = new Command('files')
-  .description('Gestionar archivos de la base de conocimiento del agente');
+  .description('Manage files in the agent knowledge base');
+
+addExamples(filesGroup, [
+  { description: 'List the knowledge-base files of an agent',
+    command: 'plazbot agent files list agt_AbcDef123' },
+  { description: 'Add a remote PDF/DOC to the knowledge base',
+    command: 'plazbot agent files add agt_AbcDef123 -u https://files.example.com/manual.pdf -r manual -t docs,onboarding' },
+  { description: 'Check whether a file finished processing',
+    command: 'plazbot agent files status file_AbcDef123' },
+  { description: 'Remove a file from the knowledge base',
+    command: 'plazbot agent files delete agt_AbcDef123 file_AbcDef123' },
+]);
 
 // Listar archivos
 filesGroup.command('list')
-  .description('Listar archivos del agente')
-  .argument('<agentId>', 'ID del agente')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('List agent files')
+  .argument('<agentId>', 'Agent ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: AgentCommandOptions) => {
     try {
       const credentials = await getStoredCredentials();
@@ -23,31 +35,31 @@ filesGroup.command('list')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Cargando archivos...');
+      const spinner = createSpinner('Loading files...');
       spinner.start();
       const _res: any = await agent.getAgentById({ id: agentId });
       const agentData = _res.agent || _res.data || _res;
       spinner.stop();
 
       const files = (agentData as any).files || [];
-      console.log(section('Archivos - ' + (agentData.name || agentId)));
+      console.log(section('Files - ' + (agentData.name || agentId)));
 
       if (files.length === 0) {
-        console.log(theme.muted('\n  No hay archivos en la base de conocimiento'));
-        console.log(theme.muted('  Usa: plazbot agent files add <agentId> --url <url>\n'));
+        console.log(theme.muted('\n  No files in the knowledge base'));
+        console.log(theme.muted('  Use: plazbot agent files add <agentId> --url <url>\n'));
         return;
       }
 
       const rows = files.map((f: any) => [
         f.fileId || f.id || 'N/A',
-        f.name || f.reference || 'Sin nombre',
+        f.name || f.reference || 'Untitled',
         (f.tags || []).join(', ') || '-',
       ]);
 
-      console.log(createTable(['ID', 'Nombre', 'Tags'], rows));
+      console.log(createTable(['ID', 'Name', 'Tags'], rows));
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
@@ -55,12 +67,12 @@ filesGroup.command('list')
 
 // Agregar archivo
 filesGroup.command('add')
-  .description('Agregar archivo a la base de conocimiento')
-  .argument('<agentId>', 'ID del agente')
-  .requiredOption('-u, --url <url>', 'URL del archivo (PDF, DOC, DOCX)')
-  .option('-r, --reference <name>', 'Nombre de referencia', 'documento')
-  .option('-t, --tags <tags>', 'Tags separados por coma', '')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Add a file to the knowledge base')
+  .argument('<agentId>', 'Agent ID')
+  .requiredOption('-u, --url <url>', 'File URL (PDF, DOC, DOCX)')
+  .option('-r, --reference <name>', 'Reference name', 'documento')
+  .option('-t, --tags <tags>', 'Comma-separated tags', '')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, options: any) => {
     try {
       const credentials = await getStoredCredentials();
@@ -71,7 +83,7 @@ filesGroup.command('add')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Subiendo archivo...');
+      const spinner = createSpinner('Uploading file...');
       spinner.start();
 
       const tags = options.tags ? options.tags.split(',').map((t: string) => t.trim()) : [];
@@ -82,16 +94,16 @@ filesGroup.command('add')
         tags,
       });
 
-      spinner.succeed('Archivo agregado');
+      spinner.succeed('File added');
 
       if (result?.fileId) {
         logger.label('File ID', result.fileId);
-        logger.dim('El archivo esta siendo procesado. Verifica con:');
+        logger.dim('The file is being processed. Check status with:');
         logger.dim(`plazbot agent files status ${result.fileId}`);
       }
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
@@ -99,9 +111,9 @@ filesGroup.command('add')
 
 // Verificar estado
 filesGroup.command('status')
-  .description('Verificar estado de procesamiento de un archivo')
-  .argument('<fileId>', 'ID del archivo')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Check the processing status of a file')
+  .argument('<fileId>', 'File ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (fileId: string, options: AgentCommandOptions) => {
     try {
       const credentials = await getStoredCredentials();
@@ -112,17 +124,17 @@ filesGroup.command('status')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Verificando...');
+      const spinner = createSpinner('Checking...');
       spinner.start();
       const result = await agent.validateFile({ fileId });
       spinner.stop();
 
-      logger.title('Estado del archivo');
+      logger.title('File status');
       logger.label('File ID', fileId);
-      logger.label('Estado', result?.status ? 'Completado' : 'En proceso');
+      logger.label('Status', result?.status ? 'Completed' : 'Processing');
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }
@@ -130,10 +142,10 @@ filesGroup.command('status')
 
 // Eliminar archivo
 filesGroup.command('delete')
-  .description('Eliminar archivo de la base de conocimiento')
-  .argument('<agentId>', 'ID del agente')
-  .argument('<fileId>', 'ID del archivo')
-  .option('--dev', 'Usar ambiente de desarrollo', false)
+  .description('Delete a file from the knowledge base')
+  .argument('<agentId>', 'Agent ID')
+  .argument('<fileId>', 'File ID')
+  .option('--dev', 'Use development environment', false)
   .action(async (agentId: string, fileId: string, options: AgentCommandOptions) => {
     try {
       const credentials = await getStoredCredentials();
@@ -144,13 +156,13 @@ filesGroup.command('delete')
         ...(options.dev && { customUrl: "http://localhost:5090" })
       });
 
-      const spinner = createSpinner('Eliminando archivo...');
+      const spinner = createSpinner('Deleting file...');
       spinner.start();
       await agent.deleteFile({ fileId, agentId });
-      spinner.succeed('Archivo eliminado');
+      spinner.succeed('File deleted');
 
     } catch (error) {
-      const message = error instanceof Error ? error.message : 'Error desconocido';
+      const message = error instanceof Error ? error.message : 'Unknown error';
       logger.error(message);
       process.exit(1);
     }