perp-cli 0.3.3

package/dist/commands/gap.js

@@ -0,0 +1,305 @@
+import chalk from "chalk";
+import { printJson, jsonOk } from "../utils.js";
+import { fetchPacificaPricesRaw, parsePacificaRaw, fetchHyperliquidAllMidsRaw, fetchLighterOrderBookDetailsRaw, } from "../shared-api.js";
+async function fetchAllPrices() {
+    const [pacRes, hlRes, ltRes] = await Promise.all([
+        fetchPacificaPricesRaw(),
+        fetchHyperliquidAllMidsRaw(),
+        fetchLighterOrderBookDetailsRaw(),
+    ]);
+    const { prices: pacPrices } = parsePacificaRaw(pacRes);
+    const hlPrices = new Map();
+    if (hlRes && typeof hlRes === "object" && !Array.isArray(hlRes)) {
+        for (const [symbol, price] of Object.entries(hlRes)) {
+            const p = Number(price);
+            if (p > 0)
+                hlPrices.set(symbol, p);
+        }
+    }
+    const ltPrices = new Map();
+    if (ltRes) {
+        const details = (ltRes.order_book_details ?? []);
+        for (const m of details) {
+            const sym = String(m.symbol ?? "").replace(/_USDC$/, "");
+            const price = Number(m.last_trade_price ?? m.mark_price ?? 0);
+            if (sym && price > 0)
+                ltPrices.set(sym, price);
+        }
+    }
+    const allSymbols = new Set([...pacPrices.keys(), ...hlPrices.keys(), ...ltPrices.keys()]);
+    const snapshots = [];
+    for (const sym of allSymbols) {
+        const pac = pacPrices.get(sym) ?? null;
+        const hl = hlPrices.get(sym) ?? null;
+        const lt = ltPrices.get(sym) ?? null;
+        // Need at least 2 exchanges
+        const available = [];
+        if (pac !== null)
+            available.push({ ex: "PAC", price: pac });
+        if (hl !== null)
+            available.push({ ex: "HL", price: hl });
+        if (lt !== null)
+            available.push({ ex: "LT", price: lt });
+        if (available.length < 2)
+            continue;
+        available.sort((a, b) => a.price - b.price);
+        const cheapest = available[0];
+        const expensive = available[available.length - 1];
+        const maxGap = expensive.price - cheapest.price;
+        const mid = (cheapest.price + expensive.price) / 2;
+        const maxGapPct = mid > 0 ? (maxGap / mid) * 100 : 0;
+        snapshots.push({
+            symbol: sym,
+            pacPrice: pac,
+            hlPrice: hl,
+            ltPrice: lt,
+            maxGap,
+            maxGapPct,
+            cheapest: cheapest.ex,
+            expensive: expensive.ex,
+        });
+    }
+    return snapshots.sort((a, b) => b.maxGapPct - a.maxGapPct);
+}
+function formatPrice(p) {
+    if (p >= 1000)
+        return p.toFixed(2);
+    if (p >= 1)
+        return p.toFixed(4);
+    return p.toFixed(6);
+}
+function printGapTable(snapshots, minGap) {
+    const filtered = snapshots.filter((s) => s.maxGapPct >= minGap);
+    if (filtered.length === 0) {
+        console.log(chalk.gray(`\n  No gaps above ${minGap}%\n`));
+        return;
+    }
+    console.log(chalk.cyan.bold("\n  Symbol      Pacifica          Hyperliquid       Lighter           Gap($)      Gap(%)    Buy/Sell\n"));
+    for (const s of filtered) {
+        const gapColor = s.maxGapPct >= 0.5
+            ? chalk.red.bold
+            : s.maxGapPct >= 0.1
+                ? chalk.yellow
+                : chalk.gray;
+        const fmtP = (p) => p !== null ? `$${formatPrice(p).padEnd(16)}` : chalk.gray("-".padEnd(17));
+        console.log(`  ${chalk.white.bold(s.symbol.padEnd(10))} ` +
+            `${fmtP(s.pacPrice)} ` +
+            `${fmtP(s.hlPrice)} ` +
+            `${fmtP(s.ltPrice)} ` +
+            `${gapColor("$" + s.maxGap.toFixed(4).padEnd(10))} ` +
+            `${gapColor(s.maxGapPct.toFixed(4).padEnd(8) + "%")} ` +
+            `${chalk.green(s.cheapest)}→${chalk.red(s.expensive)}`);
+    }
+    const avgGap = filtered.reduce((sum, s) => sum + s.maxGapPct, 0) / filtered.length;
+    const top = filtered[0];
+    console.log(chalk.gray(`\n  ${filtered.length} pairs | Avg gap: ${avgGap.toFixed(4)}% | Max: ${top.symbol} ${top.maxGapPct.toFixed(4)}%\n`));
+}
+export function registerGapCommands(program, isJson) {
+    const gap = program
+        .command("gap")
+        .description("Cross-exchange price gap monitoring (Pacifica vs Hyperliquid vs Lighter)");
+    // ── gap show (default) ──
+    gap
+        .command("show", { isDefault: true })
+        .description("Show current price gaps between exchanges")
+        .option("--min <pct>", "Minimum gap % to display", "0.01")
+        .option("--symbol <sym>", "Filter by symbol (e.g. BTC, ETH)")
+        .option("--top <n>", "Show top N gaps only")
+        .action(async (opts) => {
+        const minGap = parseFloat(opts.min);
+        if (!isJson())
+            console.log(chalk.cyan("\n  Fetching prices from Pacifica, Hyperliquid & Lighter...\n"));
+        let snapshots = await fetchAllPrices();
+        if (opts.symbol) {
+            const sym = opts.symbol.toUpperCase();
+            snapshots = snapshots.filter((s) => s.symbol.includes(sym));
+        }
+        if (opts.top) {
+            snapshots = snapshots.slice(0, parseInt(opts.top));
+        }
+        if (isJson())
+            return printJson(jsonOk(snapshots.filter((s) => s.maxGapPct >= minGap)));
+        printGapTable(snapshots, minGap);
+    });
+    // ── gap watch ── (live monitoring)
+    gap
+        .command("watch")
+        .description("Live-monitor price gaps (auto-refresh)")
+        .option("--min <pct>", "Minimum gap % to display", "0.05")
+        .option("--interval <seconds>", "Refresh interval", "5")
+        .option("--symbol <sym>", "Filter by symbol")
+        .option("--beep", "Beep on gaps above 0.5%")
+        .action(async (opts) => {
+        const minGap = parseFloat(opts.min);
+        const intervalMs = parseInt(opts.interval) * 1000;
+        const beep = !!opts.beep;
+        if (!isJson()) {
+            console.log(chalk.cyan.bold("\n  Price Gap Monitor"));
+            console.log(`  Min gap:   ${minGap}%`);
+            console.log(`  Interval:  ${opts.interval}s`);
+            if (opts.symbol)
+                console.log(`  Symbol:    ${opts.symbol.toUpperCase()}`);
+            console.log(chalk.gray("  Ctrl+C to stop\n"));
+        }
+        const cycle = async () => {
+            try {
+                let snapshots = await fetchAllPrices();
+                if (opts.symbol) {
+                    const sym = opts.symbol.toUpperCase();
+                    snapshots = snapshots.filter((s) => s.symbol.includes(sym));
+                }
+                // Clear screen for live view
+                process.stdout.write("\x1B[2J\x1B[0f");
+                const now = new Date().toLocaleTimeString();
+                console.log(chalk.cyan.bold(`  Price Gap Monitor`) +
+                    chalk.gray(`  ${now}  (refresh: ${opts.interval}s)\n`));
+                printGapTable(snapshots, minGap);
+                // Alert on large gaps
+                const bigGaps = snapshots.filter((s) => s.maxGapPct >= 0.5);
+                if (bigGaps.length > 0) {
+                    console.log(chalk.red.bold(`  !! ${bigGaps.length} large gap(s): ` +
+                        bigGaps
+                            .map((s) => `${s.symbol}(${s.maxGapPct.toFixed(3)}%)`)
+                            .join(", ")));
+                    if (beep)
+                        process.stdout.write("\x07");
+                }
+            }
+            catch (err) {
+                console.error(chalk.gray(`  Error: ${err instanceof Error ? err.message : String(err)}`));
+            }
+        };
+        await cycle();
+        setInterval(cycle, intervalMs);
+        await new Promise(() => { }); // keep alive
+    });
+    // ── gap history ── (track gap over time for a symbol)
+    gap
+        .command("track")
+        .description("Track a symbol's gap over time and print stats")
+        .requiredOption("-s, --symbol <sym>", "Symbol to track (e.g. BTC)")
+        .option("--duration <minutes>", "How long to track (minutes)", "10")
+        .option("--interval <seconds>", "Sample interval", "10")
+        .action(async (opts) => {
+        const symbol = opts.symbol.toUpperCase();
+        const durationMs = parseInt(opts.duration) * 60 * 1000;
+        const intervalMs = parseInt(opts.interval) * 1000;
+        const endTime = Date.now() + durationMs;
+        const samples = [];
+        if (!isJson()) {
+            console.log(chalk.cyan.bold(`\n  Tracking ${symbol} price gap\n`));
+            console.log(`  Duration:  ${opts.duration} min`);
+            console.log(`  Interval:  ${opts.interval}s`);
+            console.log(chalk.gray("  Collecting samples...\n"));
+        }
+        const sample = async () => {
+            const snapshots = await fetchAllPrices();
+            const s = snapshots.find((x) => x.symbol === symbol);
+            if (!s) {
+                console.log(chalk.gray(`  ${new Date().toLocaleTimeString()} — ${symbol} not found on both exchanges`));
+                return;
+            }
+            samples.push({
+                time: new Date().toLocaleTimeString(),
+                gap: s.maxGap,
+                gapPct: s.maxGapPct,
+                direction: `${s.cheapest}→${s.expensive}`,
+            });
+            const gapColor = s.maxGapPct >= 0.1 ? chalk.yellow : chalk.gray;
+            const parts = [`PAC: ${s.pacPrice !== null ? "$" + formatPrice(s.pacPrice) : "-"}`];
+            parts.push(`HL: ${s.hlPrice !== null ? "$" + formatPrice(s.hlPrice) : "-"}`);
+            parts.push(`LT: ${s.ltPrice !== null ? "$" + formatPrice(s.ltPrice) : "-"}`);
+            console.log(`  ${chalk.white(s.symbol.padEnd(6))} ` +
+                `${parts.join("  ")}  ` +
+                `${gapColor(`${s.maxGapPct.toFixed(4)}%`)}  ${s.cheapest}→${s.expensive}`);
+        };
+        await sample();
+        const timer = setInterval(async () => {
+            if (Date.now() >= endTime) {
+                clearInterval(timer);
+                printTrackSummary(symbol, samples);
+                return;
+            }
+            await sample();
+        }, intervalMs);
+        await new Promise((resolve) => {
+            setTimeout(resolve, durationMs + 1000);
+        });
+    });
+    // ── gap alert ── (one-shot: notify when gap exceeds threshold)
+    gap
+        .command("alert")
+        .description("Wait until a symbol's gap exceeds a threshold, then exit")
+        .requiredOption("-s, --symbol <sym>", "Symbol to watch")
+        .requiredOption("--above <pct>", "Gap % threshold to trigger")
+        .option("--interval <seconds>", "Check interval", "5")
+        .action(async (opts) => {
+        const symbol = opts.symbol.toUpperCase();
+        const threshold = parseFloat(opts.above);
+        const intervalMs = parseInt(opts.interval) * 1000;
+        if (!isJson())
+            console.log(chalk.cyan(`\n  Waiting for ${symbol} gap > ${threshold}%...\n`));
+        const check = async () => {
+            const snapshots = await fetchAllPrices();
+            const s = snapshots.find((x) => x.symbol === symbol);
+            if (!s)
+                return false;
+            const now = new Date().toLocaleTimeString();
+            if (!isJson())
+                console.log(chalk.gray(`  ${now} ${symbol} gap: ${s.maxGapPct.toFixed(4)}%`));
+            if (s.maxGapPct >= threshold) {
+                if (isJson()) {
+                    printJson(jsonOk(s));
+                }
+                else {
+                    console.log(chalk.green.bold(`\n  TRIGGERED! ${symbol} gap: ${s.maxGapPct.toFixed(4)}% (> ${threshold}%)`));
+                    const lines = [];
+                    if (s.pacPrice !== null)
+                        lines.push(`  Pacifica:    $${formatPrice(s.pacPrice)}`);
+                    if (s.hlPrice !== null)
+                        lines.push(`  Hyperliquid: $${formatPrice(s.hlPrice)}`);
+                    if (s.ltPrice !== null)
+                        lines.push(`  Lighter:     $${formatPrice(s.ltPrice)}`);
+                    lines.push(`  Gap:         $${s.maxGap.toFixed(4)} (${s.cheapest}→${s.expensive})`);
+                    console.log(lines.join("\n") + "\n");
+                }
+                return true;
+            }
+            return false;
+        };
+        if (await check())
+            return;
+        await new Promise((resolve) => {
+            const timer = setInterval(async () => {
+                if (await check()) {
+                    clearInterval(timer);
+                    resolve();
+                }
+            }, intervalMs);
+        });
+    });
+}
+function printTrackSummary(symbol, samples) {
+    if (samples.length === 0) {
+        console.log(chalk.gray("\n  No samples collected.\n"));
+        return;
+    }
+    const gaps = samples.map((s) => s.gapPct);
+    const avg = gaps.reduce((a, b) => a + b, 0) / gaps.length;
+    const max = Math.max(...gaps);
+    const min = Math.min(...gaps);
+    const maxSample = samples[gaps.indexOf(max)];
+    // Count direction frequencies
+    const dirCounts = new Map();
+    for (const s of samples) {
+        dirCounts.set(s.direction, (dirCounts.get(s.direction) ?? 0) + 1);
+    }
+    console.log(chalk.cyan.bold(`\n  ${symbol} Gap Summary (${samples.length} samples)\n`));
+    console.log(`  Avg gap:    ${avg.toFixed(4)}%`);
+    console.log(`  Max gap:    ${max.toFixed(4)}% at ${maxSample.time}`);
+    console.log(`  Min gap:    ${min.toFixed(4)}%`);
+    for (const [dir, count] of [...dirCounts.entries()].sort((a, b) => b[1] - a[1])) {
+        console.log(`  ${dir.padEnd(10)} ${count} times (${((count / samples.length) * 100).toFixed(0)}%)`);
+    }
+    console.log();
+}

package/dist/commands/health.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerHealthCommands(program: Command, isJson: () => boolean): void;

package/dist/commands/health.js

@@ -0,0 +1,67 @@
+import chalk from "chalk";
+import { printJson, jsonOk, makeTable } from "../utils.js";
+import { pingPacifica, pingHyperliquid, pingLighter } from "../shared-api.js";
+async function checkExchangeHealth(name, fn) {
+    const start = Date.now();
+    try {
+        await fn();
+        return { exchange: name, status: "ok", latency_ms: Date.now() - start };
+    }
+    catch (err) {
+        return {
+            exchange: name,
+            status: "down",
+            latency_ms: Date.now() - start,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export function registerHealthCommands(program, isJson) {
+    program
+        .command("health")
+        .description("Check exchange API connectivity and latency")
+        .action(async () => {
+        const [pacPing, hlPing, ltPing] = await Promise.all([
+            pingPacifica(),
+            pingHyperliquid(),
+            pingLighter(),
+        ]);
+        const toPingResult = (name, p) => ({
+            exchange: name,
+            status: p.ok ? "ok" : "down",
+            latency_ms: p.latencyMs,
+            error: p.ok ? undefined : `HTTP ${p.status}`,
+        });
+        const checks = [
+            toPingResult("pacifica", pacPing),
+            toPingResult("hyperliquid", hlPing),
+            toPingResult("lighter", ltPing),
+        ];
+        const allOk = checks.every(c => c.status === "ok");
+        if (isJson()) {
+            return printJson(jsonOk({ healthy: allOk, exchanges: checks }));
+        }
+        console.log(chalk.cyan.bold("\n  Exchange Health Check\n"));
+        const rows = checks.map(c => {
+            const statusIcon = c.status === "ok"
+                ? chalk.green("OK")
+                : c.status === "degraded"
+                    ? chalk.yellow("DEGRADED")
+                    : chalk.red("DOWN");
+            const latency = c.latency_ms < 500
+                ? chalk.green(`${c.latency_ms}ms`)
+                : c.latency_ms < 2000
+                    ? chalk.yellow(`${c.latency_ms}ms`)
+                    : chalk.red(`${c.latency_ms}ms`);
+            return [
+                chalk.white.bold(c.exchange),
+                statusIcon,
+                latency,
+                c.error ? chalk.red(c.error) : chalk.gray("-"),
+            ];
+        });
+        console.log(makeTable(["Exchange", "Status", "Latency", "Error"], rows));
+        const overall = allOk ? chalk.green("ALL HEALTHY") : chalk.red("ISSUES DETECTED");
+        console.log(`\n  Overall: ${overall}\n`);
+    });
+}

package/dist/commands/history.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerHistoryCommands(program: Command, isJson: () => boolean): void;

package/dist/commands/history.js

@@ -0,0 +1,235 @@
+import chalk from "chalk";
+import { printJson, jsonOk, makeTable, formatUsd, formatPnl, withJsonErrors } from "../utils.js";
+import { readExecutionLog, getExecutionStats, pruneExecutionLog } from "../execution-log.js";
+import { readPositionHistory, getPositionStats } from "../position-history.js";
+export function registerHistoryCommands(program, isJson) {
+    const history = program.command("history").description("Execution log & audit trail");
+    // ── history list ──
+    history
+        .command("list")
+        .description("Show recent executions")
+        .option("-n, --limit <n>", "Number of records to show", "20")
+        .option("-e, --exchange <exchange>", "Filter by exchange")
+        .option("-s, --symbol <symbol>", "Filter by symbol")
+        .option("-t, --type <type>", "Filter by type (market_order, limit_order, arb_entry, etc.)")
+        .option("--since <date>", "Show records since date (ISO format or relative like '24h', '7d')")
+        .option("--dry-run-only", "Show only dry-run simulations")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            // Parse relative dates
+            let since = opts.since;
+            if (since) {
+                const match = since.match(/^(\d+)(h|d|w)$/);
+                if (match) {
+                    const [, num, unit] = match;
+                    const ms = { h: 3600000, d: 86400000, w: 604800000 }[unit] ?? 86400000;
+                    since = new Date(Date.now() - parseInt(num) * ms).toISOString();
+                }
+            }
+            const records = readExecutionLog({
+                limit: parseInt(opts.limit),
+                exchange: opts.exchange,
+                symbol: opts.symbol,
+                type: opts.type,
+                since,
+                dryRunOnly: opts.dryRunOnly,
+            });
+            if (isJson()) {
+                return printJson(jsonOk(records));
+            }
+            if (records.length === 0) {
+                console.log(chalk.gray("\n  No execution records found.\n"));
+                return;
+            }
+            console.log(chalk.cyan.bold(`\n  Execution History (${records.length} records)\n`));
+            const rows = records.map(r => {
+                const statusColor = r.status === "success"
+                    ? chalk.green
+                    : r.status === "simulated"
+                        ? chalk.blue
+                        : chalk.red;
+                const sideColor = r.side === "buy" || r.side === "long" ? chalk.green : chalk.red;
+                const time = new Date(r.timestamp).toLocaleString();
+                const notional = r.notional ? `$${formatUsd(r.notional)}` : r.price ? `$${formatUsd(Number(r.price) * Number(r.size))}` : "-";
+                return [
+                    chalk.gray(time),
+                    chalk.white(r.exchange),
+                    r.type.replace(/_/g, " "),
+                    chalk.white.bold(r.symbol),
+                    sideColor(r.side),
+                    r.size,
+                    notional,
+                    statusColor(r.status),
+                    r.dryRun ? chalk.blue("DRY") : "",
+                ];
+            });
+            console.log(makeTable(["Time", "Exchange", "Type", "Symbol", "Side", "Size", "Notional", "Status", ""], rows));
+        });
+    });
+    // ── history stats ──
+    history
+        .command("stats")
+        .description("Execution statistics summary")
+        .option("--since <date>", "Stats since date (ISO or relative: 24h, 7d, 30d)")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            let since = opts.since;
+            if (since) {
+                const match = since.match(/^(\d+)(h|d|w)$/);
+                if (match) {
+                    const [, num, unit] = match;
+                    const ms = { h: 3600000, d: 86400000, w: 604800000 }[unit] ?? 86400000;
+                    since = new Date(Date.now() - parseInt(num) * ms).toISOString();
+                }
+            }
+            const stats = getExecutionStats(since);
+            if (isJson()) {
+                return printJson(jsonOk(stats));
+            }
+            console.log(chalk.cyan.bold("\n  Execution Stats\n"));
+            console.log(`  Total Trades:    ${stats.totalTrades}`);
+            console.log(`  Success Rate:    ${stats.successRate.toFixed(1)}%`);
+            if (Object.keys(stats.byExchange).length > 0) {
+                console.log(chalk.white.bold("\n  By Exchange:"));
+                for (const [ex, count] of Object.entries(stats.byExchange)) {
+                    console.log(`    ${ex.padEnd(14)} ${count}`);
+                }
+            }
+            if (Object.keys(stats.byType).length > 0) {
+                console.log(chalk.white.bold("\n  By Type:"));
+                for (const [type, count] of Object.entries(stats.byType)) {
+                    console.log(`    ${type.replace(/_/g, " ").padEnd(14)} ${count}`);
+                }
+            }
+            if (stats.recentErrors.length > 0) {
+                console.log(chalk.red.bold("\n  Recent Errors:"));
+                for (const err of stats.recentErrors) {
+                    console.log(`    ${chalk.red(err)}`);
+                }
+            }
+            console.log();
+        });
+    });
+    // ── history positions ──
+    history
+        .command("positions")
+        .description("Show position history (from event stream logging)")
+        .option("-n, --limit <n>", "Number of records to show", "20")
+        .option("-e, --exchange <exchange>", "Filter by exchange")
+        .option("-s, --symbol <symbol>", "Filter by symbol")
+        .option("--status <status>", "Filter by status (open, closed, updated)")
+        .option("--since <date>", "Show records since date (ISO format or relative like '24h', '7d')")
+        .option("--stats", "Show aggregate position stats instead of list")
+        .action(async (opts) => {
+        await withJsonErrors(isJson(), async () => {
+            // Parse relative dates
+            let since = opts.since;
+            if (since) {
+                const match = since.match(/^(\d+)(h|d|w)$/);
+                if (match) {
+                    const [, num, unit] = match;
+                    const ms = { h: 3600000, d: 86400000, w: 604800000 }[unit] ?? 86400000;
+                    since = new Date(Date.now() - parseInt(num) * ms).toISOString();
+                }
+            }
+            // Stats mode
+            if (opts.stats) {
+                const stats = getPositionStats({ exchange: opts.exchange, since });
+                if (isJson()) {
+                    return printJson(jsonOk(stats));
+                }
+                console.log(chalk.cyan.bold("\n  Position Stats\n"));
+                console.log(`  Total Trades:    ${stats.totalTrades}`);
+                console.log(`  Wins / Losses:   ${chalk.green(String(stats.wins))} / ${chalk.red(String(stats.losses))}`);
+                console.log(`  Win Rate:        ${stats.winRate.toFixed(1)}%`);
+                console.log(`  Total P&L:       ${formatPnl(stats.totalPnl)}`);
+                console.log(`  Avg P&L:         ${formatPnl(stats.avgPnl)}`);
+                console.log(`  Best Trade:      ${formatPnl(stats.bestTrade)}`);
+                console.log(`  Worst Trade:     ${formatPnl(stats.worstTrade)}`);
+                if (stats.avgDuration > 0) {
+                    const fmtDur = (ms) => {
+                        if (ms < 60000)
+                            return `${(ms / 1000).toFixed(0)}s`;
+                        if (ms < 3600000)
+                            return `${(ms / 60000).toFixed(1)}m`;
+                        return `${(ms / 3600000).toFixed(1)}h`;
+                    };
+                    console.log(`  Avg Duration:    ${fmtDur(stats.avgDuration)}`);
+                    console.log(`  Longest Trade:   ${fmtDur(stats.longestTrade)}`);
+                    console.log(`  Shortest Trade:  ${fmtDur(stats.shortestTrade)}`);
+                }
+                if (Object.keys(stats.bySymbol).length > 0) {
+                    console.log(chalk.white.bold("\n  By Symbol:"));
+                    for (const [sym, s] of Object.entries(stats.bySymbol)) {
+                        console.log(`    ${sym.padEnd(10)} ${s.trades} trades  ${formatPnl(s.pnl)}  ${s.winRate.toFixed(0)}% win`);
+                    }
+                }
+                if (Object.keys(stats.byExchange).length > 0) {
+                    console.log(chalk.white.bold("\n  By Exchange:"));
+                    for (const [ex, s] of Object.entries(stats.byExchange)) {
+                        console.log(`    ${ex.padEnd(14)} ${s.trades} trades  ${formatPnl(s.pnl)}`);
+                    }
+                }
+                console.log();
+                return;
+            }
+            // List mode
+            const records = readPositionHistory({
+                limit: parseInt(opts.limit),
+                exchange: opts.exchange,
+                symbol: opts.symbol,
+                status: opts.status,
+                since,
+            });
+            if (isJson()) {
+                return printJson(jsonOk(records));
+            }
+            if (records.length === 0) {
+                console.log(chalk.gray("\n  No position records found. Use `perp stream events --log-positions` to start logging.\n"));
+                return;
+            }
+            console.log(chalk.cyan.bold(`\n  Position History (${records.length} records)\n`));
+            const rows = records.map(r => {
+                const statusColor = r.status === "open"
+                    ? chalk.yellow
+                    : r.status === "closed"
+                        ? chalk.green
+                        : chalk.blue;
+                const sideColor = r.side === "long" ? chalk.green : chalk.red;
+                const time = new Date(r.updatedAt).toLocaleString();
+                const pnl = r.realizedPnl ? formatPnl(Number(r.realizedPnl)) : r.unrealizedPnl ? chalk.gray(formatPnl(Number(r.unrealizedPnl))) : "-";
+                const dur = r.duration
+                    ? r.duration < 60000
+                        ? `${(r.duration / 1000).toFixed(0)}s`
+                        : r.duration < 3600000
+                            ? `${(r.duration / 60000).toFixed(1)}m`
+                            : `${(r.duration / 3600000).toFixed(1)}h`
+                    : "-";
+                return [
+                    chalk.gray(time),
+                    chalk.white(r.exchange),
+                    chalk.white.bold(r.symbol),
+                    sideColor(r.side),
+                    r.size,
+                    `$${formatUsd(r.entryPrice)}`,
+                    pnl,
+                    dur,
+                    statusColor(r.status),
+                ];
+            });
+            console.log(makeTable(["Time", "Exchange", "Symbol", "Side", "Size", "Entry", "P&L", "Duration", "Status"], rows));
+        });
+    });
+    // ── history prune ──
+    history
+        .command("prune")
+        .description("Remove old execution records")
+        .option("--keep-days <days>", "Keep records from last N days", "30")
+        .action(async (opts) => {
+        const pruned = pruneExecutionLog(parseInt(opts.keepDays));
+        if (isJson()) {
+            return printJson(jsonOk({ pruned }));
+        }
+        console.log(chalk.green(`\n  Pruned ${pruned} old records (keeping last ${opts.keepDays} days).\n`));
+    });
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,15 @@
+import { Command } from "commander";
+declare const ENV_FILE: string;
+export { ENV_FILE, loadEnvFile, setEnvVar };
+declare function loadEnvFile(): Record<string, string>;
+declare function setEnvVar(key: string, value: string): void;
+export declare const EXCHANGE_ENV_MAP: Record<string, {
+    envKey: string;
+    chain: "solana" | "evm";
+    label: string;
+}>;
+export declare function validateKey(chain: "solana" | "evm", key: string): Promise<{
+    valid: boolean;
+    address: string;
+}>;
+export declare function registerInitCommand(program: Command): void;