plazbot-cli 0.2.26 → 0.3.2

package/dist/studio/state/store.js

@@ -0,0 +1,181 @@
+import { create } from 'zustand';
+import { randomUUID } from 'node:crypto';
+function uid() {
+    // randomUUID está disponible en Node >=14.17 con crypto. Fallback simple.
+    try {
+        return randomUUID();
+    }
+    catch {
+        return Math.random().toString(36).slice(2);
+    }
+}
+export const useStudioStore = create((set, get) => ({
+    messages: [],
+    steps: [],
+    agentConfig: null,
+    agentId: null,
+    usage: { inputTokens: 0, outputTokens: 0 },
+    streaming: false,
+    abortController: null,
+    waConnect: null,
+    pendingCompact: false,
+    pushUserMessage(content) {
+        const id = uid();
+        set((s) => ({ messages: [...s.messages, { id, role: 'user', content }] }));
+        return id;
+    },
+    pushSyntheticAssistant(content, opts) {
+        const id = uid();
+        set((s) => ({
+            messages: [...s.messages, { id, role: 'assistant', content, synthetic: true, error: opts?.error }],
+        }));
+        return id;
+    },
+    startAssistantMessage() {
+        const id = uid();
+        set((s) => ({ messages: [...s.messages, { id, role: 'assistant', content: '', streaming: true }] }));
+        return id;
+    },
+    appendAssistantText(id, delta) {
+        set((s) => ({
+            messages: s.messages.map((m) => (m.id === id ? { ...m, content: m.content + delta } : m)),
+        }));
+    },
+    finishAssistantMessage(id) {
+        set((s) => ({
+            messages: s.messages.map((m) => (m.id === id ? { ...m, streaming: false } : m)),
+        }));
+    },
+    startStep(toolName, afterMessageId) {
+        const id = uid();
+        set((s) => ({ steps: [...s.steps, { id, toolName, status: 'running', afterMessageId }] }));
+        return id;
+    },
+    resolveLastStep(toolName, status, result, errorMessage) {
+        set((s) => {
+            const idx = [...s.steps].reverse().findIndex((x) => x.toolName === toolName && x.status === 'running');
+            if (idx === -1)
+                return {};
+            const real = s.steps.length - 1 - idx;
+            const updated = [...s.steps];
+            updated[real] = { ...updated[real], status, result, errorMessage };
+            return { steps: updated };
+        });
+    },
+    failAllRunningSteps(message) {
+        set((s) => ({
+            steps: s.steps.map((x) => x.status === 'running' ? { ...x, status: 'error', errorMessage: message ?? 'Cancelado' } : x),
+        }));
+    },
+    setAgentConfig(cfg) {
+        set({ agentConfig: cfg });
+    },
+    setAgentId(id) {
+        set({ agentId: id });
+    },
+    addUsage(inT, outT) {
+        set((s) => ({
+            usage: {
+                inputTokens: s.usage.inputTokens + (inT || 0),
+                outputTokens: s.usage.outputTokens + (outT || 0),
+            },
+        }));
+    },
+    setStreaming(streaming) {
+        set({ streaming });
+    },
+    setAbortController(abortController) {
+        set({ abortController });
+    },
+    abortStream() {
+        const ctrl = get().abortController;
+        if (ctrl && !ctrl.signal.aborted)
+            ctrl.abort();
+    },
+    startWaConnect(linkData, anchorMessageId) {
+        const id = uid();
+        set({
+            waConnect: {
+                id,
+                linkData,
+                status: 'waiting',
+                anchorMessageId,
+                attempt: 0,
+            },
+        });
+        return id;
+    },
+    updateWaConnect(patch) {
+        set((s) => (s.waConnect ? { waConnect: { ...s.waConnect, ...patch } } : {}));
+    },
+    setWaStatus(status, extra) {
+        set((s) => (s.waConnect ? { waConnect: { ...s.waConnect, status, ...(extra ?? {}) } } : {}));
+    },
+    clearWaConnect() {
+        set({ waConnect: null });
+    },
+    clearMessages() {
+        const ctrl = get().abortController;
+        if (ctrl && !ctrl.signal.aborted)
+            ctrl.abort();
+        set({
+            messages: [],
+            steps: [],
+            streaming: false,
+            abortController: null,
+            waConnect: null,
+            pendingCompact: false,
+            // agentConfig, agentId, usage se mantienen para seguir trabajando.
+        });
+    },
+    setPendingCompact(v) {
+        set({ pendingCompact: v });
+    },
+    compactInto(id) {
+        set((s) => {
+            const summary = s.messages.find((m) => m.id === id);
+            if (!summary || !summary.content.trim()) {
+                return { pendingCompact: false };
+            }
+            const newId = uid();
+            return {
+                messages: [
+                    {
+                        id: newId,
+                        role: 'assistant',
+                        content: summary.content,
+                    },
+                ],
+                steps: [],
+                waConnect: null,
+                pendingCompact: false,
+            };
+        });
+    },
+    reset() {
+        const ctrl = get().abortController;
+        if (ctrl && !ctrl.signal.aborted)
+            ctrl.abort();
+        set({
+            messages: [],
+            steps: [],
+            agentConfig: null,
+            agentId: null,
+            usage: { inputTokens: 0, outputTokens: 0 },
+            streaming: false,
+            abortController: null,
+            waConnect: null,
+            pendingCompact: false,
+        });
+    },
+}));
+/**
+ * Construye el array `messages` que se envía al backend a partir del estado.
+ * Filtra mensajes sintéticos (synthetic === true) y los aún en streaming vacíos.
+ */
+export function selectBackendMessages() {
+    const { messages } = useStudioStore.getState();
+    return messages
+        .filter((m) => !m.synthetic && (m.role === 'user' || m.role === 'assistant') && m.content.trim().length > 0)
+        .map((m) => ({ role: m.role, content: m.content }));
+}

package/dist/studio/whatsapp/api.js

@@ -0,0 +1,63 @@
+import { getBaseUrl } from '../api/studioApi.js';
+function headers(opts) {
+    const h = {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${opts.apiKey}`,
+        'x-workspace-id': opts.workspaceId,
+    };
+    if (opts.userId)
+        h['x-user-id'] = opts.userId;
+    return h;
+}
+/**
+ * GET /api/workspace/{workspaceId} — the API returns an array of workspaces
+ * (the front uses `[0]`). Returns the first element or null.
+ */
+export async function getWorkspaceById(opts, signal) {
+    const url = `${getBaseUrl(opts.zone, opts.dev)}/api/workspace/${encodeURIComponent(opts.workspaceId)}`;
+    const res = await fetch(url, { method: 'GET', headers: headers(opts), signal });
+    if (!res.ok) {
+        throw new Error(`GET workspace ${res.status} ${res.statusText}`);
+    }
+    const json = (await res.json());
+    if (!json)
+        return null;
+    if (Array.isArray(json))
+        return json[0] ?? null;
+    return json;
+}
+/**
+ * POST /api/workspace/{workspaceId}/integrations/{integrationId}/activate
+ * Body: { isActive: true, platformCode: "whatsapp" }
+ */
+export async function activateIntegration(opts, integrationId, signal) {
+    const url = `${getBaseUrl(opts.zone, opts.dev)}/api/workspace/${encodeURIComponent(opts.workspaceId)}/integrations/${encodeURIComponent(integrationId)}/activate`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: headers(opts),
+        body: JSON.stringify({ isActive: true, platformCode: 'whatsapp' }),
+        signal,
+    });
+    const text = await res.text();
+    let parsed = {};
+    if (text) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch { /* not json */ }
+    }
+    if (!res.ok) {
+        return { success: false, message: parsed.message || `HTTP ${res.status} ${res.statusText}` };
+    }
+    return parsed.success === false ? parsed : { success: true, ...parsed };
+}
+/** Adapter: derives the workspace fetch options from a StudioStreamOptions. */
+export function workspaceOptsFromStream(stream) {
+    return {
+        apiKey: stream.apiKey,
+        workspaceId: stream.workspaceId,
+        zone: stream.zone,
+        dev: stream.dev,
+        userId: stream.userId,
+    };
+}

package/dist/studio/whatsapp/polling.js

@@ -0,0 +1,77 @@
+import { activateIntegration, getWorkspaceById } from './api.js';
+import { findNewWhatsappIntegration, WA_POLL_INTERVAL_MS, WA_POLL_MAX_ATTEMPTS, } from './types.js';
+/**
+ * Starts the polling loop. Returns a handle to cancel it. The loop:
+ * 1. GETs the workspace every WA_POLL_INTERVAL_MS up to WA_POLL_MAX_ATTEMPTS.
+ * 2. Looks for a whatsapp integration whose id isn't in `existingIntegrationIds`.
+ * 3. When found, calls POST .../activate and reports the result.
+ */
+export function startWhatsappPolling(opts, linkData, cb) {
+    const knownIds = new Set(linkData.existingIntegrationIds ?? []);
+    const controller = new AbortController();
+    let attempts = 0;
+    let busy = false;
+    let stopped = false;
+    let timer = null;
+    const stop = () => {
+        stopped = true;
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+        controller.abort();
+    };
+    const tick = async () => {
+        if (busy || stopped)
+            return;
+        busy = true;
+        attempts++;
+        cb.onAttempt(attempts);
+        try {
+            const ws = await getWorkspaceById(opts, controller.signal);
+            const newIntegration = findNewWhatsappIntegration(ws?.integrations, knownIds);
+            if (newIntegration?.id) {
+                const number = newIntegration.cellphoneNumberFormat ||
+                    newIntegration.cellphoneNumber ||
+                    '';
+                cb.onActivating(newIntegration.id, number);
+                if (timer) {
+                    clearInterval(timer);
+                    timer = null;
+                }
+                const res = await activateIntegration(opts, newIntegration.id, controller.signal);
+                if (res.success !== false) {
+                    cb.onConnected(number);
+                }
+                else {
+                    cb.onError(res.message || 'Could not activate the integration.');
+                }
+                stopped = true;
+                return;
+            }
+        }
+        catch (err) {
+            if (err.name === 'AbortError')
+                return;
+            // Transient network errors: swallow and keep polling.
+        }
+        finally {
+            busy = false;
+        }
+        if (attempts >= WA_POLL_MAX_ATTEMPTS) {
+            if (timer) {
+                clearInterval(timer);
+                timer = null;
+            }
+            stopped = true;
+            cb.onTimeout();
+        }
+    };
+    timer = setInterval(() => { void tick(); }, WA_POLL_INTERVAL_MS);
+    // Trigger the first attempt immediately so the user sees activity right away.
+    void tick();
+    return {
+        cancel() { stop(); },
+        get stopped() { return stopped; },
+    };
+}

package/dist/studio/whatsapp/types.js

@@ -0,0 +1,31 @@
+/**
+ * Types and helpers for the "connect WhatsApp from Agent Studio" flow.
+ *
+ * The backend tool `connect_whatsapp` emits a `tool_result` chunk with
+ * `type: "whatsapp_link"`. When `data.shortUrl` is present we render an
+ * inline card with the onboarding link and start polling the workspace
+ * until the new integration appears. Baseline of "known" ids comes from
+ * the server (`existingIntegrationIds`) to avoid race conditions.
+ *
+ * Mirror of /Plazbot-Front-v2.0/src/modules/agentStudio/whatsappConnect.ts
+ */
+export const WA_POLL_INTERVAL_MS = 5000;
+export const WA_POLL_MAX_ATTEMPTS = 60; // 5 minutes
+/**
+ * Returns a new whatsapp integration whose id is NOT in the baseline.
+ * If multiple are new, picks the most recently created one.
+ */
+export function findNewWhatsappIntegration(integrations, knownIds) {
+    if (!integrations?.length)
+        return null;
+    const candidates = integrations.filter((i) => (i.type === 'whatsapp' || i.type === 'whatsapp_business') &&
+        !!i.id &&
+        !knownIds.has(i.id));
+    if (!candidates.length)
+        return null;
+    return candidates.reduce((latest, current) => {
+        const a = latest.creationDate ? new Date(latest.creationDate).getTime() : 0;
+        const b = current.creationDate ? new Date(current.creationDate).getTime() : 0;
+        return b > a ? current : latest;
+    });
+}

package/dist/types/agent.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/auth.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/common.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/message.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/portal.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/types/workers.js

@@ -1,2 +1 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist/utils/agent-errors.js

@@ -0,0 +1,46 @@
+import chalk from 'chalk';
+/**
+ * Resuelve un error proveniente del SDK/axios al cargar un agente y devuelve
+ * un mensaje legible que oriente al usuario sobre la causa real (404 = ID o
+ * workspace/zona incorrectos, 401 = token expirado, etc.).
+ */
+export function describeAgentLoadError(error, agentId, credentials, context = {}) {
+    const err = error;
+    const status = err?.response?.status;
+    const workspace = context.workspaceOverride || credentials.workspace;
+    const zone = context.zoneOverride || credentials.zone;
+    const envHint = context.dev ? ' (env: --dev / localhost:5090)' : '';
+    if (status === 404) {
+        return [
+            `Agent "${agentId}" was not found in workspace ${workspace} (zone ${zone})${envHint}.`,
+            chalk.gray('  Verify the ID and active workspace:'),
+            chalk.gray('    plazbot status'),
+            chalk.gray('    plazbot agent list'),
+            chalk.gray('  If the agent lives in a different zone, re-init with the right one:'),
+            chalk.gray('    plazbot init -z LA   # or EU'),
+        ].join('\n');
+    }
+    if (status === 401) {
+        return [
+            'Authentication token rejected (401).',
+            chalk.gray('  Re-run: plazbot init -k <jwt> -w <workspace> -z LA|EU'),
+        ].join('\n');
+    }
+    if (status === 403) {
+        return [
+            `No permissions to access agent "${agentId}" in workspace ${workspace}.`,
+            chalk.gray('  Confirm your user has access to that workspace.'),
+        ].join('\n');
+    }
+    if (status === 429) {
+        return 'Rate limit reached. Try again in a few seconds.';
+    }
+    if (typeof status === 'number' && status >= 500) {
+        return [
+            `Backend error (HTTP ${status})${envHint}.`,
+            chalk.gray(`  ${err.response?.data?.message || err.message || ''}`).trimEnd(),
+        ].join('\n');
+    }
+    const fallback = err?.response?.data?.message || err?.message || 'Unknown error';
+    return fallback;
+}

package/dist/utils/api.js

@@ -1,25 +1,24 @@
-"use strict";
 // Utilidades para llamadas directas al API de Plazbot
 // Usado por comandos que no tienen clase SDK (ej: workers)
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createApiClient = createApiClient;
-const axios_1 = __importDefault(require("axios"));
+import axios from 'axios';
 function getBaseUrl(zone, dev) {
     if (dev)
         return 'http://localhost:5090';
     return zone === 'EU' ? 'https://apieu.plazbot.com' : 'https://api.plazbot.com';
 }
-function createApiClient(options) {
+export function createApiClient(options) {
     const baseURL = getBaseUrl(options.zone, options.dev);
-    return axios_1.default.create({
+    return axios.create({
         baseURL,
         headers: {
             'Content-Type': 'application/json',
+            // El apiKey almacenado en el CLI ya es un JWT válido. El backend espera
+            // Authorization: Bearer en endpoints nuevos (ej. /api/agent/studio).
+            // x-api-key se mantiene transitorio para no romper endpoints legacy.
+            'Authorization': `Bearer ${options.apiKey}`,
             'x-api-key': options.apiKey,
             'x-workspace-id': options.workspace,
         },
     });
 }
+export { getBaseUrl };

package/dist/utils/banner.js

@@ -1,13 +1,11 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.showBanner = showBanner;
-exports.showMiniHeader = showMiniHeader;
-const chalk_1 = __importDefault(require("chalk"));
-const credentials_1 = require("./credentials");
-const { version: VERSION } = require('../../package.json');
+import chalk from 'chalk';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { getStoredCredentials } from './credentials.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(__dirname, '..', '..', 'package.json');
+const { version: VERSION } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 // ASCII art del logo Plazbot (burbujas de chat)
 const logo = [
     '    ╭──────────╮     ',
@@ -19,51 +17,52 @@ const logo = [
     '   │    ╰────╯     │  ',
     '   ╰───────────────╯  ',
 ];
-const coloredLogo = logo.map(line => chalk_1.default.hex('#2E8B57')(line));
-async function showBanner() {
+const coloredLogo = logo.map(line => chalk.hex('#2E8B57')(line));
+export async function showBanner() {
     const width = 70;
     // Intentar cargar credenciales
     let credentials = null;
     try {
-        credentials = await (0, credentials_1.getStoredCredentials)();
+        credentials = await getStoredCredentials();
     }
     catch {
         // No hay credenciales guardadas
     }
     console.log();
-    console.log(chalk_1.default.hex('#4CAF50')('─'.repeat(width)));
+    console.log(chalk.hex('#4CAF50')('─'.repeat(width)));
     console.log();
     // Layout de 2 columnas
     const leftWidth = 30;
     const rightStart = leftWidth + 4;
     // Línea del título
-    const title = chalk_1.default.bold.hex('#4CAF50')(`  Plazbot CLI v${VERSION}`);
+    const title = chalk.bold.hex('#4CAF50')(`  Plazbot CLI v${VERSION}`);
     // Info columna derecha
     const rightColumn = [];
     if (credentials) {
-        rightColumn.push(chalk_1.default.bold.hex('#4CAF50')('Workspace conectado'));
-        rightColumn.push(chalk_1.default.gray(`  ${credentials.workspace || 'N/A'}`));
-        rightColumn.push(chalk_1.default.gray(`  ${credentials.email || ''}`));
-        rightColumn.push(chalk_1.default.gray(`  Zona: ${credentials.zone || 'N/A'}`));
+        rightColumn.push(chalk.bold.hex('#4CAF50')('Connected workspace'));
+        rightColumn.push(chalk.gray(`  ${credentials.workspace || 'N/A'}`));
+        if (credentials.email)
+            rightColumn.push(chalk.gray(`  ${credentials.email}`));
+        rightColumn.push(chalk.gray(`  Zone: ${credentials.zone || 'N/A'}`));
         rightColumn.push('');
-        rightColumn.push(chalk_1.default.hex('#4CAF50')('─'.repeat(35)));
+        rightColumn.push(chalk.hex('#4CAF50')('─'.repeat(35)));
         rightColumn.push('');
-        rightColumn.push(chalk_1.default.bold.hex('#4CAF50')('Comandos rapidos'));
-        rightColumn.push(chalk_1.default.white('  plazbot agent list'));
-        rightColumn.push(chalk_1.default.white('  plazbot agent create'));
-        rightColumn.push(chalk_1.default.white('  plazbot agent chat -a <id>'));
-        rightColumn.push(chalk_1.default.white('  plazbot whatsapp send-message'));
+        rightColumn.push(chalk.bold.hex('#4CAF50')('Quick commands'));
+        rightColumn.push(chalk.white('  plazbot agent list'));
+        rightColumn.push(chalk.white('  plazbot agent create'));
+        rightColumn.push(chalk.white('  plazbot agent chat -a <id>'));
+        rightColumn.push(chalk.white('  plazbot whatsapp send-message'));
     }
     else {
-        rightColumn.push(chalk_1.default.bold.hex('#FFA726')('No conectado'));
+        rightColumn.push(chalk.bold.hex('#FFA726')('Not connected'));
         rightColumn.push('');
-        rightColumn.push(chalk_1.default.bold.hex('#4CAF50')('Para comenzar'));
-        rightColumn.push(chalk_1.default.white('  plazbot init -e <email> -k <key> -w <workspace> -z <zone>'));
+        rightColumn.push(chalk.bold.hex('#4CAF50')('To get started'));
+        rightColumn.push(chalk.white('  plazbot init -e <email> -k <key> -w <workspace> -z <zone>'));
         rightColumn.push('');
-        rightColumn.push(chalk_1.default.hex('#4CAF50')('─'.repeat(35)));
+        rightColumn.push(chalk.hex('#4CAF50')('─'.repeat(35)));
         rightColumn.push('');
-        rightColumn.push(chalk_1.default.bold.hex('#4CAF50')('Documentacion'));
-        rightColumn.push(chalk_1.default.gray('  https://docs.plazbot.com'));
+        rightColumn.push(chalk.bold.hex('#4CAF50')('Documentation'));
+        rightColumn.push(chalk.gray('  https://docs.plazbot.com'));
     }
     // Imprimir título
     console.log(title);
@@ -79,9 +78,9 @@ async function showBanner() {
         console.log(`${left}${padding}  ${right}`);
     }
     console.log();
-    console.log(chalk_1.default.hex('#4CAF50')('─'.repeat(width)));
+    console.log(chalk.hex('#4CAF50')('─'.repeat(width)));
     console.log();
 }
-function showMiniHeader(command) {
-    console.log(chalk_1.default.hex('#4CAF50')(`\n  Plazbot`) + chalk_1.default.gray(` > ${command}\n`));
+export function showMiniHeader(command) {
+    console.log(chalk.hex('#4CAF50')(`\n  Plazbot`) + chalk.gray(` > ${command}\n`));
 }

package/dist/utils/credentials.js

@@ -1,19 +1,11 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStoredCredentials = getStoredCredentials;
-exports.saveCredentials = saveCredentials;
-exports.removeCredentials = removeCredentials;
-const promises_1 = __importDefault(require("fs/promises"));
-const path_1 = __importDefault(require("path"));
-const os_1 = __importDefault(require("os"));
-const configDir = path_1.default.join(os_1.default.homedir(), '.plazbot');
-const configPath = path_1.default.join(configDir, 'config.json');
-async function getStoredCredentials() {
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+const configDir = path.join(os.homedir(), '.plazbot');
+const configPath = path.join(configDir, 'config.json');
+export async function getStoredCredentials() {
     try {
-        const configRaw = await promises_1.default.readFile(configPath, 'utf-8');
+        const configRaw = await fs.readFile(configPath, 'utf-8');
         const config = JSON.parse(configRaw);
         if (!config.apiKey || !config.workspace || !config.zone) {
             throw new Error('Credenciales incompletas');
@@ -24,10 +16,10 @@ async function getStoredCredentials() {
         throw new Error("No se encontró una sesión activa. Ejecuta 'plazbot init' primero.");
     }
 }
-async function saveCredentials(credentials) {
-    await promises_1.default.mkdir(configDir, { recursive: true });
-    await promises_1.default.writeFile(configPath, JSON.stringify(credentials, null, 2));
+export async function saveCredentials(credentials) {
+    await fs.mkdir(configDir, { recursive: true });
+    await fs.writeFile(configPath, JSON.stringify(credentials, null, 2));
 }
-async function removeCredentials() {
-    await promises_1.default.rm(configPath, { force: true });
+export async function removeCredentials() {
+    await fs.rm(configPath, { force: true });
 }

package/dist/utils/help.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+/**
+ * Appends a colored "Examples" section to a Commander command's --help output.
+ *
+ * Usage:
+ *   addExamples(myCommand, [
+ *     { description: 'List all agents in the current workspace', command: 'plazbot agent list' },
+ *     { description: 'List as JSON for scripting',               command: 'plazbot agent list --json' },
+ *   ]);
+ *
+ * Renders as:
+ *   Examples:
+ *     # List all agents in the current workspace
+ *     $ plazbot agent list
+ *
+ *     # List as JSON for scripting
+ *     $ plazbot agent list --json
+ */
+export function addExamples(cmd, examples) {
+    if (!examples.length)
+        return cmd;
+    const lines = ['', chalk.bold('Examples:')];
+    for (const ex of examples) {
+        lines.push('  ' + chalk.gray('# ' + ex.description));
+        lines.push('  ' + chalk.cyan('$ ') + ex.command);
+        lines.push('');
+    }
+    cmd.addHelpText('after', lines.join('\n'));
+    return cmd;
+}
+/**
+ * Appends a "Notes" section after Examples. Use for caveats, links, or
+ * prerequisites the user should know before running the command.
+ */
+export function addNotes(cmd, notes) {
+    if (!notes.length)
+        return cmd;
+    const lines = ['', chalk.bold('Notes:')];
+    for (const n of notes)
+        lines.push('  ' + chalk.gray('• ') + n);
+    lines.push('');
+    cmd.addHelpText('after', lines.join('\n'));
+    return cmd;
+}