@trading-boy/cli 0.3.6 → 1.2.0

package/dist/commands/trader.js

@@ -1,20 +1,11 @@
+import { readFileSync } from 'node:fs';
+import { Option } from 'commander';
 import chalk from 'chalk';
-import { getConfig, createLogger } from '@trading-boy/core';
-import { Neo4jClient } from '@trading-boy/graph-db';
-import { formatConnectionError } from '../utils.js';
-import { isRemoteMode, apiRequest, ApiError } from '../api-client.js';
-import { createTrader, listTraders, updateTrader, linkWallet, resolveTrader, getTraderWallets, } from '@trading-boy/graph-db';
+import { createLogger } from '@trading-boy/core';
+import { padRight } from '../utils.js';
+import { apiRequest, ApiError } from '../api-client.js';
 // ─── Logger ───
 const logger = createLogger('cli-trader');
-// ─── Neo4j Client Factory ───
-function createNeo4jClient() {
-    const config = getConfig();
-    return new Neo4jClient({
-        uri: config.NEO4J_URI,
-        username: config.NEO4J_USER,
-        password: config.NEO4J_PASSWORD,
-    });
-}
 // ─── Formatters ───
 /**
  * Format a single trader record for display.
@@ -27,10 +18,11 @@ export function formatTraderOutput(trader, wallets) {
     lines.push('');
     lines.push(`  ${chalk.gray('Name:')}              ${chalk.white(trader.name)}`);
     lines.push(`  ${chalk.gray('ID:')}                ${chalk.dim(trader.id)}`);
-    lines.push(`  ${chalk.gray('Max Drawdown:')}      ${chalk.yellow(String(trader.riskToleranceMax) + '%')}`);
-    lines.push(`  ${chalk.gray('Wallets:')}           ${chalk.white(String(trader.walletAddresses.length))}`);
-    if (trader.walletAddresses.length > 0) {
-        for (const addr of trader.walletAddresses) {
+    lines.push(`  ${chalk.gray('Max Drawdown:')}      ${chalk.yellow(String(trader.riskToleranceMax ?? trader.maxDrawdownPct ?? 'n/a') + '%')}`);
+    const walletAddrs = trader.walletAddresses ?? [];
+    lines.push(`  ${chalk.gray('Wallets:')}           ${chalk.white(String(walletAddrs.length))}`);
+    if (walletAddrs.length > 0) {
+        for (const addr of walletAddrs) {
             lines.push(`    ${chalk.dim('\u2022')} ${chalk.white(addr)}`);
         }
     }
@@ -94,52 +86,31 @@ export function registerTraderCommand(program) {
         .requiredOption('--name <name>', 'Trader display name')
         .option('--wallet <address>', 'Initial Solana wallet address')
         .option('--max-drawdown <pct>', 'Max acceptable drawdown percentage', parseFloatOption)
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
         .action(async (options) => {
-        // ─── Remote API mode ───
-        if (await isRemoteMode()) {
-            try {
-                const result = await apiRequest('/api/v1/traders', {
-                    method: 'POST',
-                    body: {
-                        name: options.name,
-                        wallet: options.wallet,
-                        maxDrawdown: options.maxDrawdown,
-                    },
-                });
+        try {
+            const result = await apiRequest('/api/v1/traders', {
+                method: 'POST',
+                body: {
+                    name: options.name,
+                    wallet: options.wallet,
+                    maxDrawdown: options.maxDrawdown,
+                },
+            });
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
                 console.log(formatTraderOutput(result));
                 console.log(chalk.green('  Trader registered successfully.'));
                 console.log('');
             }
-            catch (error) {
-                const message = error instanceof ApiError ? error.message : (error instanceof Error ? error.message : String(error));
-                console.error(chalk.red(`Error: ${message}`));
-                process.exitCode = 1;
-            }
-            return;
-        }
-        const client = createNeo4jClient();
-        try {
-            await client.connect();
-            const result = await createTrader(client, {
-                name: options.name,
-                walletAddress: options.wallet,
-                riskToleranceMax: options.maxDrawdown,
-            });
-            console.log(formatTraderOutput(result));
-            console.log(chalk.green('  Trader registered successfully.'));
-            console.log('');
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = error instanceof ApiError ? error.message : (error instanceof Error ? error.message : String(error));
             logger.error({ error: message }, 'Failed to register trader');
             console.error(chalk.red(`Error: ${message}`));
-            const guidance = formatConnectionError(message);
-            if (guidance)
-                console.error(guidance);
-            process.exitCode = 1;
-        }
-        finally {
-            await client.disconnect();
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
     });
     // ─── show ───
@@ -147,86 +118,50 @@ export function registerTraderCommand(program) {
         .command('show')
         .description('Show a trader profile by name or ID')
         .argument('<name-or-id>', 'Trader name or ID')
-        .action(async (nameOrId) => {
-        // ─── Remote API mode ───
-        if (await isRemoteMode()) {
-            try {
-                const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}`);
-                const { wallets, ...trader } = result;
-                console.log(formatTraderOutput(trader, wallets));
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .action(async (nameOrId, options) => {
+        try {
+            const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}`);
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
             }
-            catch (error) {
-                if (error instanceof ApiError && error.status === 404) {
-                    console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
-                }
-                else {
-                    const message = error instanceof Error ? error.message : String(error);
-                    console.error(chalk.red(`Error: ${message}`));
-                }
-                process.exitCode = 1;
+            else {
+                const { wallets, ...traderData } = result;
+                console.log(formatTraderOutput(traderData, wallets));
             }
-            return;
         }
-        const client = createNeo4jClient();
-        try {
-            await client.connect();
-            const result = await resolveTrader(client, nameOrId);
-            if (!result) {
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
                 console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
-                process.exitCode = 1;
-                return;
             }
-            const wallets = await getTraderWallets(client, result.id);
-            console.log(formatTraderOutput(result, wallets));
-        }
-        catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.error({ error: message }, 'Failed to show trader');
-            console.error(chalk.red(`Error: ${message}`));
-            const guidance = formatConnectionError(message);
-            if (guidance)
-                console.error(guidance);
-            process.exitCode = 1;
-        }
-        finally {
-            await client.disconnect();
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.error({ error: message }, 'Failed to show trader');
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
     });
     // ─── list ───
     trader
         .command('list')
         .description('List all registered traders')
-        .action(async () => {
-        // ─── Remote API mode ───
-        if (await isRemoteMode()) {
-            try {
-                const result = await apiRequest('/api/v1/traders');
-                console.log(formatTraderListOutput(result.traders));
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .action(async (options) => {
+        try {
+            const result = await apiRequest('/api/v1/traders');
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
             }
-            catch (error) {
-                const message = error instanceof ApiError ? error.message : (error instanceof Error ? error.message : String(error));
-                console.error(chalk.red(`Error: ${message}`));
-                process.exitCode = 1;
+            else {
+                console.log(formatTraderListOutput(result.traders));
             }
-            return;
-        }
-        const client = createNeo4jClient();
-        try {
-            await client.connect();
-            const traders = await listTraders(client);
-            console.log(formatTraderListOutput(traders));
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = error instanceof ApiError ? error.message : (error instanceof Error ? error.message : String(error));
             logger.error({ error: message }, 'Failed to list traders');
             console.error(chalk.red(`Error: ${message}`));
-            const guidance = formatConnectionError(message);
-            if (guidance)
-                console.error(guidance);
-            process.exitCode = 1;
-        }
-        finally {
-            await client.disconnect();
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
     });
     // ─── update ───
@@ -236,68 +171,40 @@ export function registerTraderCommand(program) {
         .argument('<name-or-id>', 'Trader name or ID')
         .option('--name <new-name>', 'New display name')
         .option('--max-drawdown <pct>', 'New max acceptable drawdown percentage', parseFloatOption)
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
         .action(async (nameOrId, options) => {
         if (options.name === undefined && options.maxDrawdown === undefined) {
             console.error(chalk.yellow('No updates provided. Use --name or --max-drawdown.'));
             process.exitCode = 1;
             return;
         }
-        // ─── Remote API mode ───
-        if (await isRemoteMode()) {
-            try {
-                const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}`, {
-                    method: 'PATCH',
-                    body: {
-                        name: options.name,
-                        maxDrawdown: options.maxDrawdown,
-                    },
-                });
-                console.log(formatTraderOutput(result));
-                console.log(chalk.green('  Trader updated successfully.'));
-                console.log('');
-            }
-            catch (error) {
-                if (error instanceof ApiError && error.status === 404) {
-                    console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
-                }
-                else {
-                    const message = error instanceof Error ? error.message : String(error);
-                    console.error(chalk.red(`Error: ${message}`));
-                }
-                process.exitCode = 1;
-            }
-            return;
-        }
-        const client = createNeo4jClient();
         try {
-            await client.connect();
-            const existing = await resolveTrader(client, nameOrId);
-            if (!existing) {
-                console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
-                process.exitCode = 1;
-                return;
-            }
-            const result = await updateTrader(client, existing.id, {
-                name: options.name,
-                riskToleranceMax: options.maxDrawdown,
+            const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}`, {
+                method: 'PATCH',
+                body: {
+                    name: options.name,
+                    maxDrawdown: options.maxDrawdown,
+                },
             });
-            if (result) {
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
                 console.log(formatTraderOutput(result));
                 console.log(chalk.green('  Trader updated successfully.'));
                 console.log('');
             }
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.error({ error: message }, 'Failed to update trader');
-            console.error(chalk.red(`Error: ${message}`));
-            const guidance = formatConnectionError(message);
-            if (guidance)
-                console.error(guidance);
-            process.exitCode = 1;
-        }
-        finally {
-            await client.disconnect();
+            if (error instanceof ApiError && error.status === 404) {
+                console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.error({ error: message }, 'Failed to update trader');
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
     });
     // ─── preferences ───
@@ -305,6 +212,7 @@ export function registerTraderCommand(program) {
         .command('preferences')
         .description('Update notification preferences')
         .option('--summary-time <hour>', 'Hour (0-23 UTC) to receive daily email summary', parseInt)
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
         .action(async (options) => {
         if (options.summaryTime === undefined) {
             console.error(chalk.yellow('No updates provided. Use --summary-time <hour>.'));
@@ -317,27 +225,26 @@ export function registerTraderCommand(program) {
             process.exitCode = 1;
             return;
         }
-        if (!(await isRemoteMode())) {
-            console.error(chalk.yellow('Preferences require a remote API connection.'));
-            console.error(chalk.dim('  Run: trading-boy subscribe -e you@email.com'));
-            process.exitCode = 1;
-            return;
-        }
         try {
             const result = await apiRequest('/api/v1/preferences/email', {
                 method: 'PATCH',
                 body: { summaryHourUtc: options.summaryTime },
             });
-            console.log('');
-            console.log(chalk.green('  Email preferences updated.'));
-            console.log(`  ${chalk.gray('Email:')}         ${chalk.white(result.email)}`);
-            console.log(`  ${chalk.gray('Summary time:')}  ${chalk.white(String(result.summaryHourUtc).padStart(2, '0') + ':00 UTC')}`);
-            console.log('');
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log('');
+                console.log(chalk.green('  Email preferences updated.'));
+                console.log(`  ${chalk.gray('Email:')}         ${chalk.white(result.email)}`);
+                console.log(`  ${chalk.gray('Summary time:')}  ${chalk.white(String(result.summaryHourUtc).padStart(2, '0') + ':00 UTC')}`);
+                console.log('');
+            }
         }
         catch (error) {
             const message = error instanceof ApiError ? error.message : (error instanceof Error ? error.message : String(error));
             console.error(chalk.red(`Error: ${message}`));
-            process.exitCode = 1;
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
     });
     // ─── link-wallet ───
@@ -347,65 +254,303 @@ export function registerTraderCommand(program) {
         .argument('<name-or-id>', 'Trader name or ID')
         .argument('<wallet-address>', 'Solana wallet address')
         .option('--chain <chain>', 'Blockchain name', 'solana')
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
         .action(async (nameOrId, walletAddress, options) => {
-        // ─── Remote API mode ───
-        if (await isRemoteMode()) {
-            try {
-                await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}/wallets`, {
-                    method: 'POST',
-                    body: {
-                        address: walletAddress,
-                        chain: options.chain,
-                    },
-                });
+        try {
+            await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}/wallets`, {
+                method: 'POST',
+                body: {
+                    address: walletAddress,
+                    chain: options.chain,
+                },
+            });
+            if (options.format === 'json') {
+                console.log(JSON.stringify({ linked: true, address: walletAddress, chain: options.chain }, null, 2));
+            }
+            else {
                 console.log('');
                 console.log(chalk.green(`  Wallet linked: ${walletAddress}`));
                 console.log('');
             }
-            catch (error) {
-                if (error instanceof ApiError && error.status === 404) {
-                    console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+                console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.error({ error: message }, 'Failed to link wallet');
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
+        }
+    });
+    // ─── soul ───
+    trader
+        .command('soul')
+        .description('Show or upload a SOUL document')
+        .argument('<name-or-id>', 'Trader name or ID')
+        .option('--file <path>', 'Path to SOUL document file to upload')
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .action(async (nameOrId, options) => {
+        try {
+            if (options.file) {
+                // Upload SOUL document
+                const document = readFileSync(options.file, 'utf-8');
+                const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}/soul`, { method: 'PUT', body: { document } });
+                if (options.format === 'json') {
+                    console.log(JSON.stringify(result, null, 2));
                 }
                 else {
-                    const message = error instanceof Error ? error.message : String(error);
-                    console.error(chalk.red(`Error: ${message}`));
+                    console.log('');
+                    console.log(chalk.green('  SOUL document uploaded successfully.'));
+                    const parsed = result.parsed;
+                    if (parsed) {
+                        if (parsed.tradingPersonality)
+                            console.log(`  ${chalk.gray('Personality:')}  ${chalk.white(String(parsed.tradingPersonality))}`);
+                        if (parsed.riskTolerance)
+                            console.log(`  ${chalk.gray('Risk:')}         ${chalk.white(String(parsed.riskTolerance))}`);
+                        const biases = parsed.biases;
+                        if (biases && biases.length > 0) {
+                            console.log(`  ${chalk.gray('Biases:')}       ${chalk.yellow(biases.map(b => b.canonicalName).join(', '))}`);
+                        }
+                    }
+                    console.log('');
                 }
-                process.exitCode = 1;
             }
-            return;
+            else {
+                // Show current SOUL document
+                const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}/soul`);
+                if (options.format === 'json') {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log('');
+                    console.log(chalk.bold.cyan('  SOUL Document'));
+                    console.log(chalk.gray('  ' + '\u2500'.repeat(50)));
+                    console.log('');
+                    console.log(result.rawDocument.split('\n').map(l => '  ' + l).join('\n'));
+                    console.log('');
+                    console.log(`  ${chalk.gray('Updated:')} ${chalk.dim(result.updatedAt)}`);
+                    console.log('');
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+                console.error(chalk.yellow(options.file ? `Trader not found: "${nameOrId}"` : 'No SOUL document found.'));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
-        const client = createNeo4jClient();
+    });
+    // ─── purpose ───
+    trader
+        .command('purpose')
+        .description('Show or upload a PURPOSE document')
+        .argument('<name-or-id>', 'Trader name or ID')
+        .option('--file <path>', 'Path to PURPOSE document file to upload')
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .action(async (nameOrId, options) => {
         try {
-            await client.connect();
-            const existing = await resolveTrader(client, nameOrId);
-            if (!existing) {
-                console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
-                process.exitCode = 1;
-                return;
+            if (options.file) {
+                const document = readFileSync(options.file, 'utf-8');
+                const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}/purpose`, { method: 'PUT', body: { document } });
+                if (options.format === 'json') {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log('');
+                    console.log(chalk.green('  PURPOSE document uploaded successfully.'));
+                    const parsed = result.parsed;
+                    if (parsed) {
+                        if (parsed.mission)
+                            console.log(`  ${chalk.gray('Mission:')}     ${chalk.white(String(parsed.mission).slice(0, 80))}`);
+                        const scope = parsed.assetScope;
+                        if (scope && scope.length > 0) {
+                            console.log(`  ${chalk.gray('Scope:')}       ${chalk.white(scope.join(', '))}`);
+                        }
+                        if (parsed.timeHorizon)
+                            console.log(`  ${chalk.gray('Horizon:')}     ${chalk.white(String(parsed.timeHorizon))}`);
+                    }
+                    console.log('');
+                }
+            }
+            else {
+                const result = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}/purpose`);
+                if (options.format === 'json') {
+                    console.log(JSON.stringify(result, null, 2));
+                }
+                else {
+                    console.log('');
+                    console.log(chalk.bold.cyan('  PURPOSE Document'));
+                    console.log(chalk.gray('  ' + '\u2500'.repeat(50)));
+                    console.log('');
+                    console.log(result.rawDocument.split('\n').map(l => '  ' + l).join('\n'));
+                    console.log('');
+                    console.log(`  ${chalk.gray('Updated:')} ${chalk.dim(result.updatedAt)}`);
+                    console.log('');
+                }
             }
-            await linkWallet(client, existing.id, walletAddress, options.chain);
-            console.log('');
-            console.log(chalk.green(`  Wallet linked to ${existing.name}: ${walletAddress}`));
-            console.log('');
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
-            logger.error({ error: message }, 'Failed to link wallet');
-            console.error(chalk.red(`Error: ${message}`));
-            const guidance = formatConnectionError(message);
-            if (guidance)
-                console.error(guidance);
-            process.exitCode = 1;
+            if (error instanceof ApiError && error.status === 404) {
+                console.error(chalk.yellow(options.file ? `Trader not found: "${nameOrId}"` : 'No PURPOSE document found.'));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
+        }
+    });
+    // ─── identity ───
+    trader
+        .command('identity')
+        .description('Show combined identity summary with bias-signal matrix')
+        .argument('<name-or-id>', 'Trader name or ID')
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .action(async (nameOrId, options) => {
+        try {
+            const traderResult = await apiRequest(`/api/v1/traders/${encodeURIComponent(nameOrId)}`);
+            // Fetch both documents (they may not exist)
+            let soulDoc = null;
+            let purposeDoc = null;
+            try {
+                soulDoc = await apiRequest(`/api/v1/traders/${encodeURIComponent(traderResult.id)}/soul`);
+            }
+            catch { /* no soul doc */ }
+            try {
+                purposeDoc = await apiRequest(`/api/v1/traders/${encodeURIComponent(traderResult.id)}/purpose`);
+            }
+            catch { /* no purpose doc */ }
+            const combined = {
+                trader: { id: traderResult.id, name: traderResult.name },
+                soul: soulDoc?.parsed ?? null,
+                purpose: purposeDoc?.parsed ?? null,
+                hasSoul: soulDoc !== null,
+                hasPurpose: purposeDoc !== null,
+            };
+            if (options.format === 'json') {
+                console.log(JSON.stringify(combined, null, 2));
+            }
+            else {
+                console.log('');
+                console.log(chalk.bold.cyan(`  Identity: ${traderResult.name}`));
+                console.log(chalk.gray('  ' + '\u2500'.repeat(50)));
+                console.log('');
+                if (soulDoc?.parsed) {
+                    const p = soulDoc.parsed;
+                    console.log(`  ${chalk.bold('SOUL')}`);
+                    if (p.tradingPersonality)
+                        console.log(`    ${chalk.gray('Personality:')}  ${chalk.white(String(p.tradingPersonality))}`);
+                    if (p.riskTolerance)
+                        console.log(`    ${chalk.gray('Risk:')}         ${chalk.white(String(p.riskTolerance))}`);
+                    if (p.decisionStyle)
+                        console.log(`    ${chalk.gray('Decisions:')}    ${chalk.white(String(p.decisionStyle))}`);
+                    const biases = p.biases;
+                    if (biases && biases.length > 0) {
+                        console.log(`    ${chalk.gray('Biases:')}`);
+                        for (const b of biases) {
+                            const color = b.severity === 'high' ? chalk.red : b.severity === 'medium' ? chalk.yellow : chalk.dim;
+                            console.log(`      ${chalk.dim('\u2022')} ${color(b.canonicalName)} ${chalk.dim(`(${b.severity})`)}`);
+                        }
+                    }
+                }
+                else {
+                    console.log(`  ${chalk.dim('No SOUL document. Upload with: trader soul <id> --file <path>')}`);
+                }
+                console.log('');
+                if (purposeDoc?.parsed) {
+                    const p = purposeDoc.parsed;
+                    console.log(`  ${chalk.bold('PURPOSE')}`);
+                    if (p.mission)
+                        console.log(`    ${chalk.gray('Mission:')}     ${chalk.white(String(p.mission).slice(0, 100))}`);
+                    const scope = p.assetScope;
+                    if (scope && scope.length > 0)
+                        console.log(`    ${chalk.gray('Scope:')}       ${chalk.white(scope.join(', '))}`);
+                    const outOfScope = p.outOfScope;
+                    if (outOfScope && outOfScope.length > 0)
+                        console.log(`    ${chalk.gray('Out of scope:')} ${chalk.dim(outOfScope.join(', '))}`);
+                    if (p.timeHorizon)
+                        console.log(`    ${chalk.gray('Horizon:')}     ${chalk.white(String(p.timeHorizon))}`);
+                    const goals = p.goals;
+                    if (goals && goals.length > 0) {
+                        console.log(`    ${chalk.gray('Goals:')}`);
+                        for (const g of goals)
+                            console.log(`      ${chalk.dim('\u2022')} ${chalk.white(g)}`);
+                    }
+                }
+                else {
+                    console.log(`  ${chalk.dim('No PURPOSE document. Upload with: trader purpose <id> --file <path>')}`);
+                }
+                console.log('');
+            }
         }
-        finally {
-            await client.disconnect();
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+                console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
+        }
+    });
+    // ─── history ───
+    trader
+        .command('history')
+        .description('Show document revision history')
+        .argument('<name-or-id>', 'Trader name or ID')
+        .option('--type <type>', 'Filter by document type (SOUL or PURPOSE)')
+        .addOption(new Option('--format <format>', 'Output format').choices(['text', 'json']).default('text'))
+        .action(async (nameOrId, options) => {
+        try {
+            let url = `/api/v1/traders/${encodeURIComponent(nameOrId)}/documents/history`;
+            if (options.type)
+                url += `?type=${options.type.toUpperCase()}`;
+            const result = await apiRequest(url);
+            if (options.format === 'json') {
+                console.log(JSON.stringify(result, null, 2));
+            }
+            else {
+                console.log('');
+                console.log(chalk.bold.cyan('  Document Revision History'));
+                console.log(chalk.gray('  ' + '\u2500'.repeat(50)));
+                console.log('');
+                if (result.revisions.length === 0) {
+                    console.log(`  ${chalk.dim('No document revisions found.')}`);
+                }
+                else {
+                    console.log('  ' + padRight('Type', 12) + padRight('Version', 10) + 'Created');
+                    console.log('  ' + '\u2500'.repeat(50));
+                    for (const r of result.revisions) {
+                        console.log('  ' +
+                            padRight(r.documentType, 12) +
+                            padRight(`v${r.version}`, 10) +
+                            chalk.dim(r.createdAt));
+                    }
+                }
+                console.log('');
+            }
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.status === 404) {
+                console.error(chalk.yellow(`Trader not found: "${nameOrId}"`));
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(chalk.red(`Error: ${message}`));
+            }
+            process.exitCode = error instanceof ApiError ? 2 : 1;
         }
     });
 }
 // ─── Helpers ───
-function padRight(str, len) {
-    return str.length >= len ? str.slice(0, len) : str + ' '.repeat(len - str.length);
-}
 function parseFloatOption(value) {
     return parseFloat(value);
 }