perp-cli 0.3.3

package/dist/commands/manage.js

@@ -0,0 +1,309 @@
+import { PacificaAdapter } from "../exchanges/pacifica.js";
+import { printJson, jsonOk } from "../utils.js";
+import chalk from "chalk";
+export function registerManageCommands(program, getAdapter, isJson, getPacificaAdapter) {
+    const manage = program.command("manage").description("Account management");
+    // Ensure adapter is initialized before accessing PacificaAdapter
+    async function pac() {
+        const adapter = await getAdapter();
+        if (!(adapter instanceof PacificaAdapter)) {
+            throw new Error("This command requires --exchange pacifica");
+        }
+        return adapter;
+    }
+    manage
+        .command("margin <symbol> <mode>")
+        .description("Set margin mode (cross/isolated)")
+        .action(async (symbol, mode) => {
+        const m = mode.toLowerCase();
+        if (m !== "cross" && m !== "isolated") {
+            console.error(chalk.red("Mode must be cross or isolated"));
+            process.exit(1);
+        }
+        const a = await pac();
+        const result = await a.sdk.updateMarginMode({ symbol: symbol.toUpperCase(), is_isolated: m === "isolated" }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Margin mode for ${symbol.toUpperCase()} set to ${m}.\n`));
+    });
+    manage
+        .command("withdraw <amount> <address>")
+        .description("Withdraw funds to a Solana address")
+        .action(async (amount, address) => {
+        const a = await pac();
+        const result = await a.sdk.withdraw({ amount, dest_address: address }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Withdrawal of $${amount} to ${address} submitted.\n`));
+    });
+    // Subaccounts
+    const sub = manage.command("sub").description("Subaccount management");
+    sub
+        .command("create <name>")
+        .description("Create a subaccount")
+        .action(async (name) => {
+        const a = await pac();
+        const result = await a.sdk.createSubaccount(name, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Subaccount "${name}" created.\n`));
+    });
+    sub
+        .command("list")
+        .description("List subaccounts")
+        .action(async () => {
+        const a = await pac();
+        const result = await a.sdk.listSubaccounts(a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        printJson(jsonOk(result));
+    });
+    sub
+        .command("transfer <from> <to> <amount>")
+        .description("Transfer funds between accounts")
+        .action(async (from, to, amount) => {
+        const a = await pac();
+        const result = await a.sdk.transferFunds({ from_account: from, to_account: to, amount }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Transferred $${amount}.\n`));
+    });
+    // Agent wallets
+    const agent = manage.command("agent").description("Agent wallet management");
+    agent
+        .command("bind <wallet>")
+        .description("Bind an agent wallet")
+        .action(async (wallet) => {
+        const a = await pac();
+        const result = await a.sdk.bindAgentWallet(wallet, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Agent wallet ${wallet} bound.\n`));
+    });
+    agent
+        .command("list")
+        .description("List agent wallets")
+        .action(async () => {
+        const a = await pac();
+        const result = await a.sdk.listAgentWallets(a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        printJson(jsonOk(result));
+    });
+    agent
+        .command("revoke <wallet>")
+        .description("Revoke an agent wallet")
+        .action(async (wallet) => {
+        const a = await pac();
+        const result = await a.sdk.revokeAgentWallet(wallet, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Agent wallet ${wallet} revoked.\n`));
+    });
+    agent
+        .command("revoke-all")
+        .description("Revoke all agent wallets")
+        .action(async () => {
+        const a = await pac();
+        const result = await a.sdk.revokeAllAgentWallets(a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green("\n  All agent wallets revoked.\n"));
+    });
+    // Lake (liquidity vaults)
+    const lake = manage.command("lake").description("Lake (liquidity vault) management");
+    lake
+        .command("create <symbol> <amount>")
+        .description("Create a new lake")
+        .action(async (symbol, amount) => {
+        const a = await pac();
+        const result = await a.sdk.createLake({ symbol: symbol.toUpperCase(), amount }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Lake created for ${symbol.toUpperCase()} with $${amount}.\n`));
+        printJson(jsonOk(result));
+    });
+    lake
+        .command("deposit <lakeId> <amount>")
+        .description("Deposit to a lake")
+        .action(async (lakeId, amount) => {
+        const a = await pac();
+        const result = await a.sdk.depositToLake({ lake_id: lakeId, amount }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Deposited $${amount} to lake ${lakeId}.\n`));
+    });
+    lake
+        .command("withdraw <lakeId> <amount>")
+        .description("Withdraw from a lake")
+        .action(async (lakeId, amount) => {
+        const a = await pac();
+        const result = await a.sdk.withdrawFromLake({ lake_id: lakeId, amount }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Withdrew $${amount} from lake ${lakeId}.\n`));
+    });
+    // Builder Codes
+    const builder = manage.command("builder").description("Builder code management (Pacifica)");
+    builder
+        .command("approve <code> <maxFeeRate>")
+        .description("Approve a builder code (e.g. approve MYCODE 0.001)")
+        .action(async (code, maxFeeRate) => {
+        const a = await pac();
+        const result = await a.sdk.approveBuilderCode({ builder_code: code, max_fee_rate: maxFeeRate }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Builder code "${code}" approved (max fee: ${maxFeeRate}).\n`));
+    });
+    builder
+        .command("revoke <code>")
+        .description("Revoke a builder code")
+        .action(async (code) => {
+        const a = await pac();
+        const result = await a.sdk.revokeBuilderCode({ builder_code: code }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Builder code "${code}" revoked.\n`));
+    });
+    builder
+        .command("list")
+        .description("List approved builder codes")
+        .action(async () => {
+        const a = await pac();
+        const result = await a.sdk.getBuilderApprovals(a.publicKey);
+        if (isJson())
+            return printJson(jsonOk(result));
+        const approvals = result;
+        if (!Array.isArray(approvals) || approvals.length === 0) {
+            console.log(chalk.gray("\n  No builder codes approved.\n"));
+            return;
+        }
+        console.log(chalk.cyan.bold("\n  Approved Builder Codes\n"));
+        for (const b of approvals) {
+            console.log(`  ${chalk.white(b.builder_code.padEnd(16))} max_fee: ${b.max_fee_rate}  ${chalk.gray(b.description || "")}`);
+        }
+        console.log();
+    });
+    builder
+        .command("overview")
+        .description("Show your builder code overview (if you are a builder)")
+        .action(async () => {
+        const a = await pac();
+        const result = await a.sdk.getBuilderOverview(a.publicKey);
+        if (isJson())
+            return printJson(jsonOk(result));
+        printJson(jsonOk(result));
+    });
+    builder
+        .command("trades <code>")
+        .description("Show trade history for a builder code")
+        .action(async (code) => {
+        const a = await pac();
+        const result = await a.sdk.getBuilderTrades(code);
+        if (isJson())
+            return printJson(jsonOk(result));
+        printJson(jsonOk(result));
+    });
+    builder
+        .command("leaderboard <code>")
+        .description("Show user leaderboard for a builder code")
+        .action(async (code) => {
+        const a = await pac();
+        const result = await a.sdk.getBuilderLeaderboard(code);
+        if (isJson())
+            return printJson(jsonOk(result));
+        printJson(jsonOk(result));
+    });
+    builder
+        .command("update-fee <code> <feeRate>")
+        .description("Update fee rate for your builder code (builder owners only)")
+        .action(async (code, feeRate) => {
+        const a = await pac();
+        const result = await a.sdk.updateBuilderFeeRate({ builder_code: code, fee_rate: feeRate }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Builder code "${code}" fee rate updated to ${feeRate}.\n`));
+    });
+    // Referral
+    const referral = manage.command("referral").description("Referral code management (Pacifica)");
+    referral
+        .command("claim <code>")
+        .description("Claim a referral code")
+        .action(async (code) => {
+        const a = await pac();
+        const result = await a.sdk.claimReferralCode({ code }, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  Referral code "${code}" claimed!\n`));
+    });
+    // API Keys
+    const apikey = manage.command("apikey").description("API key management");
+    apikey
+        .command("create <name> <maxFeeRate>")
+        .description("Create an API key")
+        .action(async (name, maxFeeRate) => {
+        const a = await pac();
+        const result = await a.sdk.createApiKey(name, maxFeeRate, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  API key "${name}" created.\n`));
+        printJson(jsonOk(result));
+    });
+    apikey
+        .command("list")
+        .description("List API keys")
+        .action(async () => {
+        const a = await pac();
+        const result = await a.sdk.listApiKeys(a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        printJson(jsonOk(result));
+    });
+    apikey
+        .command("revoke <key>")
+        .description("Revoke an API key")
+        .action(async (key) => {
+        const a = await pac();
+        const result = await a.sdk.revokeApiKey(key, a.publicKey, a.signer);
+        if (isJson())
+            return printJson(jsonOk(result));
+        console.log(chalk.green(`\n  API key revoked.\n`));
+    });
+    // === Lighter API Key Setup ===
+    manage
+        .command("setup-api-key")
+        .description("Generate & register a Lighter API key (required for trading)")
+        .option("--key-index <n>", "API key index (2-254, default: 2)", "2")
+        .action(async (opts) => {
+        const adapter = await getAdapter();
+        const { LighterAdapter } = await import("../exchanges/lighter.js");
+        if (!(adapter instanceof LighterAdapter)) {
+            throw new Error("This command requires --exchange lighter");
+        }
+        const keyIndex = parseInt(opts.keyIndex);
+        if (!isJson()) {
+            console.log(chalk.cyan.bold("\n  Lighter API Key Setup\n"));
+            console.log(chalk.gray(`  Account: ${adapter.address} (index: ${adapter.accountIndex})`));
+            console.log(chalk.gray(`  API Key Index: ${keyIndex}\n`));
+            console.log(chalk.gray("  Generating key pair + registering on-chain...\n"));
+        }
+        const { privateKey, publicKey } = await adapter.setupApiKey(keyIndex);
+        if (isJson()) {
+            return printJson(jsonOk({
+                privateKey,
+                publicKey,
+                address: adapter.address,
+                accountIndex: adapter.accountIndex,
+                apiKeyIndex: keyIndex,
+            }));
+        }
+        console.log(chalk.green("  API Key Registered!\n"));
+        console.log(`  ${chalk.bold("Private Key:")} ${privateKey}`);
+        console.log(`  ${chalk.bold("Public Key:")}  ${publicKey}`);
+        console.log();
+        console.log(chalk.yellow("  Add to your .env file:"));
+        console.log(chalk.white(`  LIGHTER_API_KEY=${privateKey}`));
+        console.log(chalk.white(`  LIGHTER_ACCOUNT_INDEX=${adapter.accountIndex}`));
+        console.log();
+    });
+}

package/dist/commands/market.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerMarketCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean): void;

package/dist/commands/market.js

@@ -0,0 +1,225 @@
+import { PacificaAdapter } from "../exchanges/pacifica.js";
+import { makeTable, formatUsd, formatPercent, printJson, jsonOk, jsonError } from "../utils.js";
+import chalk from "chalk";
+export function registerMarketCommands(program, getAdapter, isJson) {
+    const market = program.command("market").description("Market data commands");
+    market
+        .command("list")
+        .description("List all available markets")
+        .action(async () => {
+        const adapter = await getAdapter();
+        const markets = await adapter.getMarkets();
+        if (isJson())
+            return printJson(jsonOk(markets));
+        const rows = markets.map((m) => [
+            chalk.white.bold(m.symbol),
+            `$${formatUsd(m.markPrice)}`,
+            `$${formatUsd(m.indexPrice)}`,
+            formatPercent(m.fundingRate),
+            `$${formatUsd(m.volume24h)}`,
+            `$${formatUsd(m.openInterest)}`,
+            String(m.maxLeverage) + "x",
+        ]);
+        console.log(makeTable(["Symbol", "Mark", "Index", "Funding", "24h Vol", "OI", "Max Lev"], rows));
+    });
+    market
+        .command("prices")
+        .description("Get current prices for all markets")
+        .action(async () => {
+        const adapter = await getAdapter();
+        if (adapter instanceof PacificaAdapter) {
+            const prices = await adapter.sdk.getPrices();
+            if (isJson())
+                return printJson(jsonOk(prices));
+            const rows = prices.map((p) => [
+                chalk.white.bold(p.symbol),
+                `$${formatUsd(p.mark)}`,
+                `$${formatUsd(p.mid)}`,
+                `$${formatUsd(p.oracle)}`,
+                formatPercent(p.funding),
+            ]);
+            console.log(makeTable(["Symbol", "Mark", "Mid", "Oracle", "Funding"], rows));
+        }
+        else {
+            // Generic: use getMarkets as price source
+            const markets = await adapter.getMarkets();
+            if (isJson())
+                return printJson(jsonOk(markets));
+            const rows = markets.map((m) => [
+                chalk.white.bold(m.symbol),
+                `$${formatUsd(m.markPrice)}`,
+                `$${formatUsd(m.indexPrice)}`,
+                formatPercent(m.fundingRate),
+            ]);
+            console.log(makeTable(["Symbol", "Mark", "Index", "Funding"], rows));
+        }
+    });
+    market
+        .command("info <symbol>")
+        .description("Detailed info for a single market")
+        .action(async (symbol) => {
+        const adapter = await getAdapter();
+        const markets = await adapter.getMarkets();
+        const sym = symbol.toUpperCase();
+        const m = markets.find((mk) => mk.symbol === sym || mk.symbol === `${sym}-PERP` || mk.symbol.replace(/-PERP$/, "") === sym);
+        if (!m) {
+            if (isJson())
+                return printJson(jsonError("SYMBOL_NOT_FOUND", `Market ${sym} not found`));
+            console.log(chalk.red(`\n  Market "${sym}" not found.\n`));
+            return;
+        }
+        if (isJson())
+            return printJson(jsonOk(m));
+        console.log(chalk.cyan.bold(`\n  ${m.symbol} on ${adapter.name}\n`));
+        console.log(`  Mark Price:     $${formatUsd(m.markPrice)}`);
+        console.log(`  Index Price:    $${formatUsd(m.indexPrice)}`);
+        console.log(`  Funding Rate:   ${formatPercent(m.fundingRate)}`);
+        console.log(`  24h Volume:     $${formatUsd(m.volume24h)}`);
+        console.log(`  Open Interest:  $${formatUsd(m.openInterest)}`);
+        console.log(`  Max Leverage:   ${m.maxLeverage}x`);
+        console.log();
+    });
+    market
+        .command("book <symbol>")
+        .description("Show orderbook for a symbol")
+        .option("-d, --depth <n>", "Number of levels", "10")
+        .action(async (symbol, opts) => {
+        const adapter = await getAdapter();
+        const book = await adapter.getOrderbook(symbol.toUpperCase());
+        if (isJson())
+            return printJson(jsonOk(book));
+        const depth = parseInt(opts.depth);
+        const asks = book.asks.slice(0, depth).reverse();
+        const bids = book.bids.slice(0, depth);
+        console.log(chalk.cyan.bold(`\n  Orderbook: ${symbol.toUpperCase()} (${adapter.name})\n`));
+        console.log(chalk.gray("  Price          Size"));
+        console.log(chalk.gray("  ─────────────────────"));
+        asks.forEach(([p, a]) => {
+            console.log(chalk.red(`  ${formatUsd(p).padStart(12)}  ${a}`));
+        });
+        console.log(chalk.gray("  ─── spread ───"));
+        bids.forEach(([p, a]) => {
+            console.log(chalk.green(`  ${formatUsd(p).padStart(12)}  ${a}`));
+        });
+        console.log();
+    });
+    market
+        .command("trades <symbol>")
+        .description("Recent trades for a symbol")
+        .action(async (symbol) => {
+        const adapter = await getAdapter();
+        const trades = await adapter.getRecentTrades(symbol.toUpperCase(), 20);
+        if (isJson())
+            return printJson(jsonOk(trades));
+        if (trades.length === 0) {
+            console.log(chalk.gray("\n  No recent trades.\n"));
+            return;
+        }
+        const rows = trades.map((t) => [
+            new Date(t.time).toLocaleTimeString(),
+            t.side === "buy" ? chalk.green("BUY") : chalk.red("SELL"),
+            `$${formatUsd(t.price)}`,
+            t.size,
+        ]);
+        console.log(makeTable(["Time", "Side", "Price", "Size"], rows));
+    });
+    market
+        .command("funding <symbol>")
+        .description("Funding rate history")
+        .option("-l, --limit <n>", "Number of records", "10")
+        .action(async (symbol, opts) => {
+        const adapter = await getAdapter();
+        const history = await adapter.getFundingHistory(symbol.toUpperCase(), parseInt(opts.limit));
+        if (isJson())
+            return printJson(jsonOk(history));
+        if (history.length === 0) {
+            console.log(chalk.gray("\n  No funding history.\n"));
+            return;
+        }
+        const rows = history.map((h) => [
+            new Date(h.time).toLocaleString(),
+            formatPercent(h.rate),
+            `$${formatUsd(h.price)}`,
+        ]);
+        console.log(makeTable(["Time", "Funding Rate", "Oracle"], rows));
+    });
+    market
+        .command("mid <symbol>")
+        .description("Get mid price for a single symbol (fast)")
+        .action(async (symbol) => {
+        const sym = symbol.toUpperCase();
+        try {
+            const adapter = await getAdapter();
+            // Try orderbook mid (best bid + best ask) / 2
+            const book = await adapter.getOrderbook(sym);
+            const bestBid = book.bids[0]?.[0];
+            const bestAsk = book.asks[0]?.[0];
+            if (!bestBid && !bestAsk) {
+                if (isJson())
+                    return printJson(jsonError("SYMBOL_NOT_FOUND", `No orderbook data for ${sym}`));
+                console.log(chalk.red(`\n  No orderbook data for ${sym}.\n`));
+                return;
+            }
+            const bid = Number(bestBid ?? 0);
+            const ask = Number(bestAsk ?? 0);
+            const mid = bid && ask ? (bid + ask) / 2 : bid || ask;
+            const spread = bid && ask ? ((ask - bid) / mid * 100) : 0;
+            if (isJson())
+                return printJson(jsonOk({
+                    symbol: sym,
+                    mid: mid.toString(),
+                    bid: bestBid ?? null,
+                    ask: bestAsk ?? null,
+                    spread: spread.toFixed(6),
+                }));
+            console.log(chalk.cyan.bold(`\n  ${sym} Mid Price\n`));
+            console.log(`  Mid:    $${formatUsd(mid)}`);
+            if (bestBid)
+                console.log(`  Bid:    $${formatUsd(bestBid)}`);
+            if (bestAsk)
+                console.log(`  Ask:    $${formatUsd(bestAsk)}`);
+            console.log(`  Spread: ${spread.toFixed(4)}%`);
+            console.log();
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (isJson()) {
+                const { classifyError } = await import("../errors.js");
+                const classified = classifyError(err);
+                return printJson(jsonError(classified.code, classified.message, {
+                    status: classified.status,
+                    retryable: classified.retryable,
+                }));
+            }
+            console.error(chalk.red(`Error: ${msg}`));
+        }
+    });
+    market
+        .command("kline <symbol> <interval>")
+        .description("Kline/candlestick data (intervals: 1m,5m,15m,1h,4h,1d,...)")
+        .option("--start <ts>", "Start time (unix ms)")
+        .option("--end <ts>", "End time (unix ms)")
+        .action(async (symbol, interval, opts) => {
+        const adapter = await getAdapter();
+        const now = Date.now();
+        const startTime = opts.start ? parseInt(opts.start) : now - 24 * 60 * 60 * 1000;
+        const endTime = opts.end ? parseInt(opts.end) : now;
+        const klines = await adapter.getKlines(symbol.toUpperCase(), interval, startTime, endTime);
+        if (isJson())
+            return printJson(jsonOk(klines));
+        if (klines.length === 0) {
+            console.log(chalk.gray("\n  No kline data.\n"));
+            return;
+        }
+        const rows = klines.slice(-20).map((k) => [
+            new Date(k.time).toLocaleString(),
+            `$${formatUsd(k.open)}`,
+            `$${formatUsd(k.high)}`,
+            `$${formatUsd(k.low)}`,
+            `$${formatUsd(k.close)}`,
+            k.volume,
+            String(k.trades),
+        ]);
+        console.log(makeTable(["Time", "Open", "High", "Low", "Close", "Volume", "Trades"], rows));
+    });
+}

package/dist/commands/plan.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerPlanCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean): void;

package/dist/commands/plan.js

@@ -0,0 +1,95 @@
+import { readFileSync } from "fs";
+import { printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
+import { validatePlan, executePlan } from "../plan-executor.js";
+import chalk from "chalk";
+export function registerPlanCommands(program, getAdapter, isJson) {
+    const plan = program.command("plan").description("Composite execution plans (multi-step atomic operations)");
+    // ── plan validate ──
+    plan
+        .command("validate <file>")
+        .description("Validate a JSON execution plan without executing")
+        .action(async (file) => {
+        await withJsonErrors(isJson(), async () => {
+            const raw = file === "-" ? readFileSync(0, "utf-8") : readFileSync(file, "utf-8");
+            const planData = JSON.parse(raw);
+            const result = validatePlan(planData);
+            if (isJson())
+                return printJson(jsonOk(result));
+            if (result.valid) {
+                console.log(chalk.green(`\n  Plan is valid (${planData.steps?.length ?? 0} steps).\n`));
+            }
+            else {
+                console.log(chalk.red(`\n  Plan validation failed:\n`));
+                for (const err of result.errors) {
+                    console.log(chalk.red(`    • ${err}`));
+                }
+                console.log();
+            }
+        });
+    });
+    // ── plan execute ──
+    plan
+        .command("execute <file>")
+        .description("Execute a JSON plan (use - for stdin)")
+        .option("--dry-run", "Simulate without executing trades")
+        .action(async (file, opts) => {
+        await withJsonErrors(isJson(), async () => {
+            const raw = file === "-" ? readFileSync(0, "utf-8") : readFileSync(file, "utf-8");
+            const planData = JSON.parse(raw);
+            // Validate first
+            const validation = validatePlan(planData);
+            if (!validation.valid) {
+                if (isJson())
+                    return printJson(jsonError("INVALID_PARAMS", `Plan validation failed: ${validation.errors.join("; ")}`));
+                console.error(chalk.red(`\n  Plan validation failed:`));
+                for (const err of validation.errors)
+                    console.error(chalk.red(`    • ${err}`));
+                return;
+            }
+            const adapter = await getAdapter();
+            const log = isJson() ? () => { } : (msg) => console.log(chalk.gray(`  ${msg}`));
+            if (!isJson()) {
+                console.log(chalk.cyan.bold(`\n  Executing plan (${planData.steps.length} steps)${opts.dryRun ? " [DRY RUN]" : ""}...\n`));
+            }
+            const result = await executePlan(adapter, planData, {
+                dryRun: opts.dryRun,
+                log,
+            });
+            if (isJson())
+                return printJson(jsonOk(result));
+            // Pretty print results
+            for (const step of result.steps) {
+                const icon = step.status === "success" ? chalk.green("✓")
+                    : step.status === "dry_run" ? chalk.blue("○")
+                        : step.status === "skipped" ? chalk.yellow("–")
+                            : chalk.red("✗");
+                const duration = chalk.gray(`(${step.durationMs}ms)`);
+                const err = step.error ? chalk.red(` — ${step.error.message}`) : "";
+                console.log(`  ${icon} ${step.stepId} (${step.action}) ${duration}${err}`);
+            }
+            const statusColor = result.status === "completed" ? chalk.green
+                : result.status === "dry_run" ? chalk.blue
+                    : result.status === "partial" ? chalk.yellow
+                        : chalk.red;
+            console.log(`\n  Status: ${statusColor(result.status)} | ${result.totalDurationMs}ms\n`);
+        });
+    });
+    // ── plan example ──
+    plan
+        .command("example")
+        .description("Print an example execution plan")
+        .action(() => {
+        const example = {
+            version: "1.0",
+            description: "Open hedged position with stop loss",
+            steps: [
+                { id: "check", action: "check_balance", params: { minAvailable: 100 }, onFailure: "abort" },
+                { id: "leverage", action: "set_leverage", params: { symbol: "ETH", leverage: 5 }, onFailure: "abort" },
+                { id: "entry", action: "market_order", params: { symbol: "ETH", side: "buy", size: "0.5" }, onFailure: "rollback" },
+                { id: "verify", action: "check_position", params: { symbol: "ETH", mustExist: true }, dependsOn: "entry", onFailure: "rollback" },
+                { id: "stop", action: "stop_order", params: { symbol: "ETH", side: "sell", size: "0.5", triggerPrice: "1800", reduceOnly: true }, dependsOn: "verify", onFailure: "skip" },
+            ],
+        };
+        printJson(jsonOk(example));
+    });
+}

package/dist/commands/portfolio.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/interface.js";
+export declare function registerPortfolioCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;