plazbot-cli 0.4.0 → 0.5.0

package/dist/commands/agent/files.js

@@ -2,44 +2,63 @@ import { Command } from 'commander';
 import { Agent } from 'plazbot';
 import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
 import { createSpinner, createTable, theme, section } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { addYesOption, confirmAction } from '../../utils/confirm.js';
+function buildAgent(credentials, dev) {
+    return new Agent({
+        workspaceId: credentials.workspace,
+        apiKey: credentials.apiKey,
+        zone: credentials.zone,
+        ...(dev && { customUrl: "http://localhost:5090" })
+    });
+}
 const filesGroup = new Command('files')
     .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' },
+        command: 'plazbot agent files list age_AbcDef123' },
+    { description: 'Add a remote PDF/DOC/DOCX to the knowledge base',
+        command: 'plazbot agent files add age_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' },
+        command: 'plazbot agent files status fil_AbcDef123' },
     { description: 'Remove a file from the knowledge base',
-        command: 'plazbot agent files delete agt_AbcDef123 file_AbcDef123' },
+        command: 'plazbot agent files delete age_AbcDef123 fil_AbcDef123' },
 ]);
 // Listar archivos
-filesGroup.command('list')
-    .description('List agent files')
+const listCmd = filesGroup.command('list')
+    .description('List the files in the knowledge base of an agent')
     .argument('<agentId>', 'Agent ID')
+    .addOption(jsonOption('Print the files as a JSON array (fileId, name, tags)'))
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, options) => {
     try {
         const credentials = await getStoredCredentials();
-        const agent = new Agent({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
+        const agent = buildAgent(credentials, options.dev);
         const spinner = createSpinner('Loading files...');
         spinner.start();
-        const _res = await agent.getAgentById({ id: agentId });
-        const agentData = _res.agent || _res.data || _res;
-        spinner.stop();
-        const files = agentData.files || [];
+        let agentData;
+        try {
+            const res = await agent.getAgentById({ id: agentId });
+            agentData = res?.agent || res?.data || res || {};
+        }
+        finally {
+            spinner.stop();
+        }
+        const files = Array.isArray(agentData.files) ? agentData.files : [];
+        if (isJsonMode()) {
+            printJson(files.map((f) => ({
+                fileId: f.fileId || f.id || null,
+                name: f.name || f.reference || null,
+                tags: Array.isArray(f.tags) ? f.tags : [],
+            })));
+            return;
+        }
         console.log(section('Files - ' + (agentData.name || agentId)));
         if (files.length === 0) {
-            console.log(theme.muted('\n  No files in the knowledge base'));
-            console.log(theme.muted('  Use: plazbot agent files add <agentId> --url <url>\n'));
+            console.log(theme.muted('\n  No files in the knowledge base.'));
+            console.log(theme.muted(`  Add one with: plazbot agent files add ${agentId} -u <url>\n`));
             return;
         }
         const rows = files.map((f) => [
@@ -50,102 +69,165 @@ filesGroup.command('list')
         console.log(createTable(['ID', 'Name', 'Tags'], rows));
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
+addExamples(listCmd, [
+    { description: 'List the files of an agent', command: 'plazbot agent files list age_AbcDef123' },
+    { description: 'Print the files as JSON', command: 'plazbot agent files list age_AbcDef123 --json' },
+]);
 // Agregar archivo
-filesGroup.command('add')
-    .description('Add a file to the knowledge base')
+const addCmd = filesGroup.command('add')
+    .description('Add a remote file (PDF, DOC, DOCX) 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', '')
+    .requiredOption('-u, --url <url>', 'Public http(s) URL of the file (PDF, DOC, DOCX)')
+    .option('-r, --reference <name>', 'Reference name shown in the knowledge base (default: the file name)')
+    .option('-t, --tags <tags>', 'Comma-separated tags, e.g. docs,onboarding', '')
+    .addOption(jsonOption('Print the result as JSON ({"fileId","agentId","reference","status"})'))
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, options) => {
     try {
+        let parsed;
+        try {
+            parsed = new URL(options.url);
+        }
+        catch {
+            throw new CliError(`Invalid URL "${options.url}".`, 'invalid_url', 'Pass a public link, e.g. -u https://files.example.com/manual.pdf');
+        }
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            throw new CliError('The file URL must start with http:// or https://.', 'invalid_url');
+        }
+        const fileName = decodeURIComponent(parsed.pathname.split('/').pop() || '');
+        const ext = fileName.includes('.') ? fileName.split('.').pop().toLowerCase() : '';
+        if (ext && !['pdf', 'doc', 'docx'].includes(ext)) {
+            logger.warning(`The file extension ".${ext}" may not be supported (expected PDF, DOC or DOCX).`);
+        }
+        const reference = options.reference?.trim() || fileName.replace(/\.[^.]+$/, '') || 'document';
         const credentials = await getStoredCredentials();
-        const agent = new Agent({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        const spinner = createSpinner('Uploading file...');
+        const agent = buildAgent(credentials, options.dev);
+        const spinner = createSpinner('Adding file...');
         spinner.start();
-        const tags = options.tags ? options.tags.split(',').map((t) => t.trim()) : [];
-        const result = await agent.addFile({
-            fileUrl: options.url,
-            reference: options.reference,
-            agentId,
-            tags,
-        });
+        const tags = options.tags ? options.tags.split(',').map((t) => t.trim()).filter(Boolean) : [];
+        let result;
+        try {
+            result = await agent.addFile({ fileUrl: options.url, reference, agentId, tags });
+        }
+        catch (err) {
+            spinner.fail('Could not add the file');
+            throw err;
+        }
+        if (result?.success === false) {
+            spinner.fail('Could not add the file');
+            throw new CliError(result.message || 'The API rejected the file.', 'add_file_failed');
+        }
         spinner.succeed('File added');
+        if (isJsonMode()) {
+            printJson({ fileId: result?.fileId ?? null, agentId, reference, status: 'processing' });
+            return;
+        }
+        logger.label('Reference', reference);
         if (result?.fileId) {
             logger.label('File ID', result.fileId);
-            logger.dim('The file is being processed. Check status with:');
+            logger.dim('The file is being processed. Check the status with:');
             logger.dim(`plazbot agent files status ${result.fileId}`);
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
+addExamples(addCmd, [
+    { description: 'Add a PDF manual',
+        command: 'plazbot agent files add age_AbcDef123 -u https://files.example.com/manual.pdf' },
+    { description: 'Add a file with a reference name and tags',
+        command: 'plazbot agent files add age_AbcDef123 -u https://files.example.com/prices.docx -r prices -t sales,2026' },
+]);
+addNotes(addCmd, [
+    'The URL must be publicly reachable. Processing is asynchronous: check it with "plazbot agent files status <fileId>".',
+]);
 // Verificar estado
-filesGroup.command('status')
+const statusCmd = filesGroup.command('status')
     .description('Check the processing status of a file')
-    .argument('<fileId>', 'File ID')
+    .argument('<fileId>', 'File ID (from "files add" or "files list")')
+    .addOption(jsonOption('Print the status as JSON ({"fileId","status"})'))
     .option('--dev', 'Use development environment', false)
     .action(async (fileId, options) => {
     try {
         const credentials = await getStoredCredentials();
-        const agent = new Agent({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
+        const agent = buildAgent(credentials, options.dev);
         const spinner = createSpinner('Checking...');
         spinner.start();
-        const result = await agent.validateFile({ fileId });
-        spinner.stop();
+        let result;
+        try {
+            result = await agent.validateFile({ fileId });
+        }
+        finally {
+            spinner.stop();
+        }
+        // La API devuelve status truthy cuando el archivo ya fue procesado
+        const raw = result?.status;
+        const processing = !raw || (typeof raw === 'string' && /process|pending|queue/i.test(raw));
+        const status = processing ? 'processing' : 'completed';
+        if (isJsonMode()) {
+            printJson({ fileId, status });
+            return;
+        }
         logger.title('File status');
         logger.label('File ID', fileId);
-        logger.label('Status', result?.status ? 'Completed' : 'Processing');
+        logger.label('Status', status === 'completed' ? 'Completed' : 'Processing');
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
+addExamples(statusCmd, [
+    { description: 'Check a file', command: 'plazbot agent files status fil_AbcDef123' },
+    { description: 'Check a file and print JSON', command: 'plazbot agent files status fil_AbcDef123 --json' },
+]);
 // Eliminar archivo
-filesGroup.command('delete')
+const deleteCmd = filesGroup.command('delete')
     .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, fileId, options) => {
+    .addOption(jsonOption('Print the result as JSON ({"agentId","fileId","deleted"})'))
+    .option('--dev', 'Use development environment', false);
+addYesOption(deleteCmd);
+deleteCmd.action(async (agentId, fileId, options) => {
     try {
+        const ok = await confirmAction(`Delete file ${fileId} from agent ${agentId}? This cannot be undone.`, options);
+        if (!ok) {
+            logger.dim('Aborted.');
+            process.exit(1);
+        }
         const credentials = await getStoredCredentials();
-        const agent = new Agent({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
+        const agent = buildAgent(credentials, options.dev);
         const spinner = createSpinner('Deleting file...');
         spinner.start();
-        await agent.deleteFile({ fileId, agentId });
+        let result;
+        try {
+            result = await agent.deleteFile({ fileId, agentId });
+        }
+        catch (err) {
+            spinner.fail('Could not delete the file');
+            throw err;
+        }
+        if (result?.success === false) {
+            spinner.fail('Could not delete the file');
+            throw new CliError(result.message || 'The API rejected the request.', 'delete_file_failed');
+        }
         spinner.succeed('File deleted');
+        if (isJsonMode()) {
+            printJson({ agentId, fileId, deleted: true });
+        }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
+addExamples(deleteCmd, [
+    { description: 'Delete a file (asks for confirmation)',
+        command: 'plazbot agent files delete age_AbcDef123 fil_AbcDef123' },
+    { description: 'Delete without prompting (scripts and CI)',
+        command: 'plazbot agent files delete age_AbcDef123 fil_AbcDef123 --yes' },
+]);
 export const filesCommand = filesGroup;

package/dist/commands/agent/get.js

@@ -1,24 +1,33 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { Agent } from 'plazbot';
 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 { jsonOption, isJsonMode, setJsonMode, printJson, fail, CliError } from '../../utils/output.js';
 import chalk from 'chalk';
 export const getCommand = new Command('get')
     .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)
+    // Legacy alias of --json
+    .addOption(new Option('--raw', 'Alias of --json').default(false).hideHelp())
+    .addOption(jsonOption('Print the agent as JSON'))
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, options) => {
+    if (options.raw)
+        setJsonMode(true);
     try {
         const credentials = await getStoredCredentials();
         const effectiveWorkspace = options.workspace || credentials.workspace;
-        const effectiveZone = (options.zone?.toUpperCase() === 'EU' ? 'EU' : options.zone?.toUpperCase() === 'LA' ? 'LA' : credentials.zone);
+        const zoneOverride = options.zone?.toUpperCase();
+        if (zoneOverride && zoneOverride !== 'LA' && zoneOverride !== 'EU') {
+            throw new CliError(`Invalid zone "${options.zone}".`, 'invalid_zone', 'Use -z LA or -z EU.');
+        }
+        const effectiveZone = (zoneOverride || credentials.zone);
         if (options.workspace || options.zone) {
-            console.log(chalk.hex('#FFA726')(`\n  Support mode: workspace=${effectiveWorkspace} zone=${effectiveZone}`));
+            logger.warning(`Support mode: workspace=${effectiveWorkspace} zone=${effectiveZone}`);
         }
         const agent = new Agent({
             workspaceId: effectiveWorkspace,
@@ -29,9 +38,9 @@ export const getCommand = new Command('get')
         // El SDK retorna { success, agent: {...} }
         const response = await agent.getAgentById({ id: agentId });
         const agentData = response.agent || response.data || response;
-        // Modo JSON crudo
-        if (options.raw) {
-            console.log(JSON.stringify(agentData, null, 2));
+        // Modo JSON (--json o el legado --raw)
+        if (isJsonMode()) {
+            printJson(agentData);
             return;
         }
         const label = (key, value) => {
@@ -177,13 +186,15 @@ export const getCommand = new Command('get')
             });
         }
         console.log();
-        console.log(chalk.gray('  Use --raw to see the full JSON'));
+        console.log(chalk.gray('  Use --json to see the full JSON'));
         console.log();
         if (options.dev) {
             logger.warning('Environment: development');
         }
     }
     catch (error) {
+        if (isJsonMode() || error instanceof CliError)
+            fail(error);
         const credentials = await getStoredCredentials().catch(() => null);
         if (credentials) {
             logger.error(describeAgentLoadError(error, agentId, credentials, {
@@ -191,19 +202,16 @@ export const getCommand = new Command('get')
                 workspaceOverride: options.workspace,
                 zoneOverride: options.zone,
             }));
+            process.exit(1);
         }
-        else {
-            const message = error instanceof Error ? error.message : 'Unknown error while fetching the agent';
-            logger.error(message);
-        }
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(getCommand, [
     { description: 'Show the agent in a human-friendly layout',
-        command: 'plazbot agent get agt_AbcDef123' },
+        command: 'plazbot agent get age_AbcDef123' },
     { description: 'Dump the full raw JSON (useful for piping to jq)',
-        command: 'plazbot agent get agt_AbcDef123 --raw' },
+        command: 'plazbot agent get age_AbcDef123 --json' },
     { description: 'Inspect an agent from another workspace (support mode)',
-        command: 'plazbot agent get agt_AbcDef123 -w wok_Other123 -z LA' },
+        command: 'plazbot agent get age_AbcDef123 -w wok_Other123 -z LA' },
 ]);

package/dist/commands/agent/index.js

@@ -18,7 +18,7 @@ import { monitorCommand } from './monitor.js';
 import { exportCommand, crossCopyCommand } from './export.js';
 import { validateCommand } from './validate.js';
 export const agentCommands = new Command('agent')
-    .description('Commands related to AI agents')
+    .description('Create, configure, test and monitor AI agents')
     .addCommand(listCommand)
     .addCommand(getCommand)
     .addCommand(deleteCommand)
@@ -40,14 +40,16 @@ export const agentCommands = new Command('agent')
 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',
+    { description: 'Create an agent from a JSON file',
         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' },
+    { description: 'Chat interactively with an agent',
+        command: 'plazbot agent chat age_AbcDef123' },
+    { description: 'Ask a single question (scripts)',
+        command: 'plazbot agent message age_AbcDef123 -q "What plans do you offer?" --json' },
+    { description: 'Export, edit and update an agent',
+        command: 'plazbot agent export age_AbcDef123 -o agent.json && plazbot agent update age_AbcDef123 agent.json' },
+    { description: 'Copy an agent to another workspace',
+        command: 'plazbot agent cross-copy age_AbcDef123 --from-workspace wok_Source123 --to-workspace wok_Target456' },
+    { description: 'Monitor the activity of an agent in real time',
+        command: 'plazbot agent monitor age_AbcDef123' },
 ]);

package/dist/commands/agent/list.js

@@ -3,33 +3,43 @@ import { Agent } from 'plazbot';
 import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
 import { addExamples } from '../../utils/help.js';
+import { jsonOption, isJsonMode, printJson, fail } from '../../utils/output.js';
 export const listCommand = new Command('list')
     .description('List all agents in the workspace')
+    .addOption(jsonOption('Print the agents as a JSON array (id, name, enable, description, createdAt)'))
     .option('--dev', 'Use development environment (localhost:5090)', false)
     .action(async (options) => {
     try {
-        // Obtener credenciales guardadas
         const credentials = await getStoredCredentials();
-        // Crear instancia del agente con las credenciales guardadas
         const agent = new Agent({
             workspaceId: credentials.workspace,
             apiKey: credentials.apiKey,
             zone: credentials.zone,
             ...(options.dev && { customUrl: "http://localhost:5090" })
         });
-        // Obtener lista de agentes
-        const agents = await agent.getAgents();
+        const agents = (await agent.getAgents()) || [];
+        if (isJsonMode()) {
+            printJson(agents.map((a) => ({
+                id: a.id,
+                name: a.name,
+                enable: a.enable,
+                description: a.description,
+                createdAt: a.createdAt,
+            })));
+            return;
+        }
         if (agents.length === 0) {
-            logger.info('No agents found in this workspace');
+            logger.info('No agents found in this workspace.');
+            logger.dim('Create one with: plazbot agent create');
             return;
         }
-        logger.info('\nAgents:');
+        logger.info(`\nAgents (${agents.length}):`);
         logger.doubleDivider();
         agents.forEach((a, index) => {
             logger.info(`${index + 1}. ID: ${a.id}`);
             logger.info(`   Name: ${a.name}`);
             logger.info(`   Status: ${a.enable ? 'Active' : 'Inactive'}`);
-            logger.info(`   Description: ${a.description}`);
+            logger.info(`   Description: ${a.description || '—'}`);
             logger.info(`   Created: ${a.createdAt ? new Date(a.createdAt).toLocaleString() : 'N/A'}`);
             logger.divider();
         });
@@ -38,12 +48,11 @@ export const listCommand = new Command('list')
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error while listing agents';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 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' },
+    { description: 'Print the agents as JSON', command: 'plazbot agent list --json' },
+    { description: 'Get only the agent IDs (for scripts)', command: "plazbot agent list --json | jq -r '.[].id'" },
 ]);