@raintree-technology/perps 0.1.0

package/dist/commands/setup/index.js

@@ -0,0 +1,478 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { getOutputOptions } from "../../cli/program.js";
+import { output, outputError, outputSuccess } from "../../cli/output.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { createAccount, getAccountByAliasForExchange, } from "../../lib/db/index.js";
+import { privateKeyToAccount } from "viem/accounts";
+import { getCredentialVaultSummary, saveOnboardingProfileToVault, } from "../../lib/credential-vault.js";
+import { ALL_SETUP_CHAINS, ALL_SETUP_EXCHANGES, buildOnboardingEnvFile, parseSetupChains, parseSetupExchanges, parseSetupMode, resolveExchangesFromChains, runOnboardingStateMachine, } from "../../lib/onboarding.js";
+import { confirm, multiSelect, select } from "../../lib/prompts.js";
+import { hardenPrivateFile, PRIVATE_FILE_MODE } from "../../lib/fs-security.js";
+const MODE_DESCRIPTIONS = {
+    "mainnet-data": "No credentials. Use real mainnet data immediately.",
+    "testnet-execution": "Force selected exchanges to testnet for all commands.",
+    both: "Keep defaults: data=mainnet, execution=testnet (recommended).",
+};
+const CHAIN_DESCRIPTIONS = {
+    evm: "Hyperliquid, Aevo, Orderly",
+    aptos: "Decibel",
+    starknet: "Paradex",
+};
+function normalizeFundingOptions(opts) {
+    const orderlyBrokerId = opts.orderlyBrokerId ??
+        process.env.ORDERLY_TESTNET_FAUCET_BROKER_ID ??
+        process.env.ORDERLY_BROKER_ID;
+    const orderlyChainId = opts.orderlyChainId ?? process.env.ORDERLY_TESTNET_FAUCET_CHAIN_ID;
+    const aptosFaucetJwt = opts.aptosFaucetJwt ?? process.env.APTOS_TESTNET_FAUCET_JWT;
+    const aptosFaucetAmount = opts.aptosFaucetAmount ?? process.env.APTOS_TESTNET_FAUCET_AMOUNT;
+    return {
+        orderlyBrokerId,
+        orderlyChainId: orderlyChainId ? Number.parseInt(orderlyChainId, 10) : undefined,
+        aptosFaucetJwt,
+        aptosFaucetAmount: aptosFaucetAmount ? Number.parseInt(aptosFaucetAmount, 10) : undefined,
+    };
+}
+function normalizeAuthOptions(opts) {
+    const orderlyChainId = opts.orderlyChainId ??
+        process.env.ORDERLY_CHAIN_ID ??
+        process.env.ORDERLY_TESTNET_FAUCET_CHAIN_ID;
+    return {
+        decibelBearerToken: opts.decibelBearerToken ?? process.env.DECIBEL_API_BEARER_TOKEN,
+        aevoApiKey: opts.aevoApiKey ?? process.env.AEVO_API_KEY,
+        aevoApiSecret: opts.aevoApiSecret ?? process.env.AEVO_API_SECRET,
+        aevoAccountPrivateKey: (opts.aevoAccountPrivateKey ??
+            process.env.AEVO_ACCOUNT_PRIVATE_KEY),
+        aevoRestUrl: opts.aevoRestUrl ?? process.env.AEVO_REST_URL,
+        orderlyBrokerId: opts.orderlyBrokerId ??
+            process.env.ORDERLY_BROKER_ID ??
+            process.env.ORDERLY_TESTNET_FAUCET_BROKER_ID,
+        orderlyChainId: orderlyChainId ? Number.parseInt(orderlyChainId, 10) : undefined,
+        orderlyRestUrl: opts.orderlyRestUrl ?? process.env.ORDERLY_REST_URL,
+        orderlyAccountId: opts.orderlyAccountId ?? process.env.ORDERLY_ACCOUNT_ID,
+        orderlyKey: opts.orderlyKey ?? process.env.ORDERLY_KEY,
+        orderlySecret: opts.orderlySecret ?? process.env.ORDERLY_SECRET,
+        paradexApiBearerToken: opts.paradexBearerToken ?? process.env.PARADEX_API_BEARER_TOKEN,
+        paradexAccountAddress: opts.paradexAccountAddress ?? process.env.PARADEX_ACCOUNT_ADDRESS,
+        paradexEthereumAccount: opts.paradexEthereumAccount ?? process.env.PARADEX_ETHEREUM_ACCOUNT,
+        paradexRestUrl: opts.paradexRestUrl ?? process.env.PARADEX_REST_URL,
+    };
+}
+function syncGeneratedAccounts(profile) {
+    const alias = "setup";
+    const results = [];
+    const create = (args) => {
+        const { exchange, userAddress, privateKey, publicKey } = args;
+        if (!userAddress || !privateKey) {
+            results.push({
+                exchange,
+                alias,
+                status: "skipped",
+                detail: "missing address/private key",
+            });
+            return;
+        }
+        try {
+            const existing = getAccountByAliasForExchange(alias, exchange);
+            if (existing) {
+                results.push({
+                    exchange,
+                    alias,
+                    status: "skipped",
+                    detail: `alias "${alias}" already exists`,
+                });
+                return;
+            }
+            createAccount({
+                alias,
+                exchange,
+                userAddress: userAddress,
+                type: "api_wallet",
+                source: "cli_import",
+                apiWalletPrivateKey: privateKey,
+                apiWalletPublicKey: (publicKey ?? userAddress),
+                setAsDefault: false,
+            });
+            results.push({
+                exchange,
+                alias,
+                status: "created",
+                detail: `created "${alias}" profile`,
+            });
+        }
+        catch (err) {
+            results.push({
+                exchange,
+                alias,
+                status: "error",
+                detail: err instanceof Error ? err.message : String(err),
+            });
+        }
+    };
+    for (const exchange of profile.exchanges) {
+        if (exchange === "hyperliquid" && profile.credentials.hyperliquid) {
+            create({
+                exchange,
+                userAddress: profile.credentials.hyperliquid.walletAddress,
+                privateKey: profile.credentials.hyperliquid.privateKey,
+                publicKey: profile.credentials.hyperliquid.walletAddress,
+            });
+            continue;
+        }
+        if (exchange === "decibel" && profile.credentials.decibel) {
+            create({
+                exchange,
+                userAddress: profile.credentials.decibel.apiWalletAddress,
+                privateKey: profile.credentials.decibel.apiWalletPrivateKey,
+                publicKey: profile.credentials.decibel.apiWalletAddress,
+            });
+            continue;
+        }
+        if (exchange === "aevo" && profile.credentials.aevo) {
+            const signingKey = profile.credentials.aevo.signingKey;
+            const address = privateKeyToAccount(signingKey).address;
+            create({
+                exchange,
+                userAddress: address,
+                privateKey: signingKey,
+                publicKey: address,
+            });
+            continue;
+        }
+        if (exchange === "orderly" && profile.credentials.orderly) {
+            create({
+                exchange,
+                userAddress: profile.credentials.orderly.accountId ?? profile.wallets.evmAddress,
+                privateKey: profile.credentials.orderly.tradingSecret,
+                publicKey: profile.wallets.evmAddress,
+            });
+            continue;
+        }
+        if (exchange === "paradex" && profile.credentials.paradex) {
+            create({
+                exchange,
+                userAddress: profile.credentials.paradex.accountAddress,
+                privateKey: profile.credentials.paradex.privateKey,
+                publicKey: profile.credentials.paradex.starkPublicKey,
+            });
+            continue;
+        }
+        results.push({
+            exchange,
+            alias,
+            status: "skipped",
+            detail: "no generated credentials available",
+        });
+    }
+    return results;
+}
+async function resolveMode(opts, assumeDefaults) {
+    if (opts.mode) {
+        return parseSetupMode(opts.mode);
+    }
+    if (assumeDefaults) {
+        return "both";
+    }
+    return select("Choose onboarding mode", [
+        {
+            value: "both",
+            label: "Mainnet data + testnet execution (recommended)",
+            description: MODE_DESCRIPTIONS.both,
+        },
+        {
+            value: "mainnet-data",
+            label: "Mainnet data only",
+            description: MODE_DESCRIPTIONS["mainnet-data"],
+        },
+        {
+            value: "testnet-execution",
+            label: "Testnet everywhere",
+            description: MODE_DESCRIPTIONS["testnet-execution"],
+        },
+    ]);
+}
+async function resolveExchanges(opts, assumeDefaults) {
+    if (opts.exchanges) {
+        return parseSetupExchanges(opts.exchanges);
+    }
+    if (opts.chains) {
+        return resolveExchangesFromChains(parseSetupChains(opts.chains));
+    }
+    if (assumeDefaults) {
+        return [...ALL_SETUP_EXCHANGES];
+    }
+    const selectedChains = await multiSelect("Select chains for automated testnet onboarding", ALL_SETUP_CHAINS.map((chain) => ({
+        value: chain,
+        label: chain.toUpperCase(),
+        description: CHAIN_DESCRIPTIONS[chain],
+    })));
+    if (selectedChains.length === 0) {
+        throw new Error("At least one chain must be selected");
+    }
+    const chainExchanges = resolveExchangesFromChains(selectedChains);
+    const customize = await confirm("Customize exchanges inside selected chains?", false);
+    if (!customize) {
+        return chainExchanges;
+    }
+    const selectedExchanges = await multiSelect("Select exchanges", chainExchanges.map((exchange) => ({
+        value: exchange,
+        label: exchange,
+        description: CHAIN_DESCRIPTIONS[exchange === "decibel" ? "aptos" : exchange === "paradex" ? "starknet" : "evm"],
+    })));
+    if (selectedExchanges.length === 0) {
+        throw new Error("At least one exchange must be selected");
+    }
+    return selectedExchanges;
+}
+function printMainnetOnlySummary() {
+    outputSuccess("Mainnet data mode is already ready out-of-the-box.");
+    console.log("");
+    console.log("Try:");
+    console.log("  perps markets ls");
+    console.log("  perps -e aevo markets ls");
+    console.log("  perps -e paradex markets ls");
+    console.log("");
+}
+function printWizardSummary(args) {
+    outputSuccess("Onboarding state machine completed");
+    console.log("");
+    console.log(`Mode: ${args.mode}`);
+    console.log(`Exchanges: ${args.exchanges.join(", ")}`);
+    console.log(`State file:    ${args.stateFile}`);
+    if (args.vault) {
+        console.log(`Vault entry:   ${args.vault.id}`);
+        console.log(`Vault path:    ${args.vault.path}`);
+    }
+    if (args.exportedEnvFile) {
+        console.log(`Env export:    ${args.exportedEnvFile}`);
+    }
+    if (args.wallets.evmAddress) {
+        console.log(`EVM wallet:    ${args.wallets.evmAddress}`);
+    }
+    if (args.wallets.aptosAddress) {
+        console.log(`Aptos wallet:  ${args.wallets.aptosAddress}`);
+    }
+    if (args.wallets.starkPublicKey) {
+        console.log(`Stark pubkey:  ${args.wallets.starkPublicKey}`);
+    }
+    if (args.authResults.length > 0) {
+        console.log("");
+        console.log("Auth bootstrap:");
+        for (const result of args.authResults) {
+            console.log(`  [${result.status}] ${result.service}: ${result.detail}`);
+        }
+    }
+    if (args.fundingResults.length > 0) {
+        console.log("");
+        console.log("Funding:");
+        for (const result of args.fundingResults) {
+            console.log(`  [${result.status}] ${result.service}: ${result.detail}`);
+        }
+    }
+    if (args.accountSync.length > 0) {
+        console.log("");
+        console.log("Account sync:");
+        for (const result of args.accountSync) {
+            console.log(`  [${result.status}] ${result.exchange}/${result.alias}: ${result.detail}`);
+        }
+    }
+    if (args.manualFollowUps.length > 0) {
+        console.log("");
+        console.log("Manual follow-ups:");
+        for (const item of args.manualFollowUps) {
+            const envKeys = item.env.length > 0 ? ` (${item.env.join(", ")})` : "";
+            console.log(`  - ${item.exchange}${envKeys}: ${item.detail}`);
+        }
+    }
+    console.log("");
+    console.log("Next steps:");
+    if (args.exportedEnvFile) {
+        console.log(`1) source ${args.exportedEnvFile}`);
+        console.log("2) perps doctor --network");
+        console.log("3) perps markets ls");
+        console.log("4) perps order market buy BTC 0.001 --idempotency-key setup-smoke-001");
+    }
+    else {
+        console.log("1) Re-run with --export-env if you want a source-able env file");
+        console.log("2) perps doctor --network");
+        console.log("3) perps markets ls");
+        console.log("4) perps order market buy BTC 0.001 --idempotency-key setup-smoke-001");
+    }
+    console.log("");
+}
+export function registerSetupCommands(program) {
+    const setup = program.command("setup").description("Onboarding and environment setup");
+    setup
+        .command("wizard")
+        .description("Interactive setup for mainnet data defaults and testnet onboarding")
+        .option("--mode <mode>", `Onboarding mode (${["mainnet-data", "testnet-execution", "both"].join(", ")})`)
+        .option("--chains <chains>", "Comma-separated chains (evm,aptos,starknet)")
+        .option("--exchanges <exchanges>", "Comma-separated exchanges (overrides --chains)")
+        .option("--fund", "Attempt automated faucet requests where available")
+        .option("--orderly-broker-id <id>", "Orderly broker id (used for auth bootstrap + faucet)")
+        .option("--orderly-chain-id <id>", "Orderly chain id for auth/faucet bootstrap (default: 421614)")
+        .option("--aptos-faucet-jwt <jwt>", "Aptos faucet JWT for automated mint requests")
+        .option("--aptos-faucet-amount <amount>", "Aptos faucet amount in Octas")
+        .option("--no-bootstrap-auth", "Skip best-effort auth bootstrap")
+        .option("--decibel-bearer-token <token>", "Decibel bearer token override for bootstrap")
+        .option("--aevo-api-key <key>", "Aevo API key override for bootstrap")
+        .option("--aevo-api-secret <secret>", "Aevo API secret override for bootstrap")
+        .option("--aevo-account-private-key <key>", "Aevo account private key for auto-generating API creds")
+        .option("--aevo-rest-url <url>", "Aevo REST URL override for bootstrap auth")
+        .option("--orderly-account-id <id>", "Orderly account id override for bootstrap")
+        .option("--orderly-key <key>", "Orderly API key override for bootstrap")
+        .option("--orderly-secret <secret>", "Orderly API secret override for bootstrap")
+        .option("--orderly-rest-url <url>", "Orderly REST URL override for bootstrap auth")
+        .option("--paradex-bearer-token <token>", "Paradex bearer token override for bootstrap")
+        .option("--paradex-account-address <address>", "Paradex account address override for bootstrap")
+        .option("--paradex-ethereum-account <address>", "Paradex parent Ethereum account for onboarding bootstrap")
+        .option("--paradex-rest-url <url>", "Paradex REST URL override for bootstrap auth")
+        .option("--no-sync-accounts", "Skip syncing generated credentials to local account profiles")
+        .option("--file <path>", "Output file path", ".env.testnet.local")
+        .option("--export-env", "Export a source-able env file in addition to encrypted vault storage")
+        .option("--dry-run", "Show onboarding contract without writing state or files")
+        .option("--resume", "Resume from an existing onboarding state file")
+        .option("--state-file <path>", "Override onboarding state file path")
+        .option("--funding-retries <count>", "Retry failed automated funding tasks")
+        .option("--force", "Overwrite output file if it already exists")
+        .option("--yes", "Skip interactive prompts and use defaults")
+        .action(async function () {
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const hasInteractiveTty = process.stdin.isTTY && process.stdout.isTTY;
+        const assumeDefaults = Boolean(opts.yes) || !hasInteractiveTty;
+        try {
+            const mode = await resolveMode(opts, assumeDefaults);
+            const networkDefaults = mode === "testnet-execution"
+                ? { data: "testnet", execution: "testnet" }
+                : { data: "mainnet", execution: "testnet" };
+            if (mode === "mainnet-data") {
+                const contract = withJsonContract("setup.wizard.result", {
+                    mode,
+                    ready: true,
+                    networkDefaults,
+                    message: "Public data commands work immediately with mainnet defaults.",
+                    commands: ["perps markets ls", "perps -e aevo markets ls", "perps -e paradex markets ls"],
+                });
+                if (outputOpts.json) {
+                    output(contract, outputOpts);
+                }
+                else {
+                    printMainnetOnlySummary();
+                }
+                return;
+            }
+            const exchanges = await resolveExchanges(opts, assumeDefaults);
+            let shouldFund = Boolean(opts.fund);
+            if (!opts.fund && !assumeDefaults) {
+                shouldFund = await confirm("Attempt automated faucet funding now (best effort)?", true);
+            }
+            let shouldExportEnv = Boolean(opts.exportEnv);
+            if (!opts.exportEnv && !assumeDefaults) {
+                shouldExportEnv = await confirm("Also export a plaintext env file (credentials are always saved encrypted)?", false);
+            }
+            const fundingOptions = normalizeFundingOptions(opts);
+            const authOptions = normalizeAuthOptions(opts);
+            const shouldBootstrapAuth = opts.bootstrapAuth ?? true;
+            const shouldSyncAccounts = opts.syncAccounts ?? true;
+            const targetFile = resolve((opts.file ?? ".env.testnet.local").trim());
+            const stateFile = opts.stateFile ? resolve(opts.stateFile) : undefined;
+            const runResult = await runOnboardingStateMachine({
+                mode,
+                exchanges,
+                shouldFund,
+                fundingOptions,
+                shouldBootstrapAuth,
+                authOptions,
+                statePath: stateFile,
+                resume: Boolean(opts.resume),
+                fundingRetries: opts.fundingRetries ? Number.parseInt(opts.fundingRetries, 10) : undefined,
+            });
+            const profile = runResult.profile;
+            const authResults = runResult.authResults;
+            let vaultRef = null;
+            if (!opts.dryRun) {
+                vaultRef = saveOnboardingProfileToVault(profile);
+            }
+            const accountSync = !opts.dryRun && shouldSyncAccounts ? syncGeneratedAccounts(profile) : [];
+            let exportedEnvFile;
+            if (shouldExportEnv) {
+                const envFile = buildOnboardingEnvFile(profile);
+                const fileExists = existsSync(targetFile);
+                if (fileExists && !opts.force) {
+                    if (assumeDefaults) {
+                        throw new Error(`Refusing to overwrite existing file: ${targetFile}. Re-run with --force to replace it.`);
+                    }
+                    const overwrite = await confirm(`File exists (${targetFile}). Overwrite it?`, false);
+                    if (!overwrite) {
+                        throw new Error("Cancelled by user (file overwrite declined)");
+                    }
+                }
+                if (!opts.dryRun) {
+                    writeFileSync(targetFile, envFile, { mode: PRIVATE_FILE_MODE });
+                    hardenPrivateFile(targetFile);
+                }
+                exportedEnvFile = targetFile;
+            }
+            const payload = withJsonContract("setup.wizard.result", {
+                mode,
+                dryRun: Boolean(opts.dryRun),
+                networkDefaults,
+                stateFile: runResult.statePath,
+                idempotencyKey: runResult.state.idempotencyKey,
+                chains: profile.chains,
+                exchanges: profile.exchanges,
+                wallets: profile.wallets,
+                vault: vaultRef,
+                vaultSummary: getCredentialVaultSummary(),
+                file: exportedEnvFile,
+                auth: authResults,
+                funding: runResult.fundingResults,
+                accountsSynced: accountSync,
+                manualFollowUps: profile.manualFollowUps,
+                nextSteps: exportedEnvFile
+                    ? [
+                        `source ${exportedEnvFile}`,
+                        "perps doctor --network",
+                        "perps markets ls",
+                        "perps order market buy BTC 0.001 --idempotency-key setup-smoke-001",
+                    ]
+                    : [
+                        "perps setup wizard --export-env",
+                        "perps doctor --network",
+                        "perps markets ls",
+                        "perps order market buy BTC 0.001 --idempotency-key setup-smoke-001",
+                    ],
+                stateNotes: runResult.state.notes,
+                stateStatus: runResult.state.statusByStep,
+            });
+            if (opts.dryRun) {
+                if (outputOpts.json) {
+                    output(payload, outputOpts);
+                    return;
+                }
+                outputSuccess("Dry-run only: no vault/env files were written.");
+            }
+            if (outputOpts.json) {
+                output(payload, outputOpts);
+                return;
+            }
+            printWizardSummary({
+                mode,
+                exchanges: profile.exchanges,
+                stateFile: runResult.statePath,
+                vault: vaultRef,
+                exportedEnvFile,
+                wallets: profile.wallets,
+                authResults,
+                fundingResults: runResult.fundingResults,
+                accountSync,
+                manualFollowUps: profile.manualFollowUps,
+            });
+        }
+        catch (err) {
+            outputError(err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/signal/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerSignalCommands(program: Command): void;

package/dist/commands/signal/index.js

@@ -0,0 +1,129 @@
+import { getOutputOptions } from "../../cli/program.js";
+import { output, outputSuccess } from "../../cli/output.js";
+import { withJsonContract } from "../../lib/contracts.js";
+import { addSignal, querySignals, getSignalSummary, } from "../../lib/signals.js";
+export function registerSignalCommands(program) {
+    const signal = program.command("signal").description("Trade signal tracking (thumbs up/down feedback)");
+    signal
+        .command("add")
+        .description("Log a trade signal")
+        .requiredOption("--exchange <id>", "Exchange identifier")
+        .requiredOption("--signal <up|down>", "Signal value (up or down)")
+        .option("--trace <traceId>", "Trace ID to correlate with")
+        .option("--market <symbol>", "Market symbol (e.g. BTC-PERP)")
+        .option("--strategy <name>", "Strategy name")
+        .option("--reason <text>", "Reason for signal")
+        .option("--pnl <usd>", "Realized P&L in USD", Number.parseFloat)
+        .action(function () {
+        const opts = this.opts();
+        const signalValue = opts.signal.toLowerCase();
+        if (signalValue !== "up" && signalValue !== "down") {
+            console.error('Error: --signal must be "up" or "down"');
+            process.exitCode = 1;
+            return;
+        }
+        const id = addSignal({
+            traceId: opts.trace,
+            exchange: opts.exchange,
+            market: opts.market,
+            strategy: opts.strategy,
+            signal: signalValue,
+            reason: opts.reason,
+            pnlUsd: opts.pnl,
+        });
+        const outputOpts = getOutputOptions(this);
+        if (outputOpts.json) {
+            output(withJsonContract("signal.recorded", { id }), outputOpts);
+        }
+        else {
+            outputSuccess(`Signal recorded (id: ${id})`);
+        }
+    });
+    signal
+        .command("ls")
+        .description("List recent signals")
+        .option("--exchange <id>", "Filter by exchange")
+        .option("--market <symbol>", "Filter by market")
+        .option("--strategy <name>", "Filter by strategy")
+        .option("--signal <up|down>", "Filter by signal value")
+        .option("--last <minutes>", "Show signals from last N minutes", Number.parseFloat)
+        .option("--limit <n>", "Max results to return", Number.parseFloat)
+        .action(function () {
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const signalFilter = opts.signal?.toLowerCase();
+        if (signalFilter && signalFilter !== "up" && signalFilter !== "down") {
+            console.error('Error: --signal must be "up" or "down"');
+            process.exitCode = 1;
+            return;
+        }
+        const signals = querySignals({
+            exchange: opts.exchange,
+            market: opts.market,
+            strategy: opts.strategy,
+            signal: signalFilter,
+            minutes: opts.last,
+            limit: opts.limit,
+        });
+        if (outputOpts.json) {
+            output(withJsonContract("signal.list", { signals }), outputOpts);
+            return;
+        }
+        if (signals.length === 0) {
+            console.log("\nNo signals found.\n");
+            return;
+        }
+        const rows = signals.map((s) => ({
+            ID: s.id,
+            Signal: s.signal,
+            Exchange: s.exchange,
+            Market: s.market ?? "",
+            Strategy: s.strategy ?? "",
+            "P&L": s.pnlUsd != null ? `$${s.pnlUsd.toFixed(2)}` : "",
+            Reason: s.reason ?? "",
+            Time: new Date(s.createdAt).toISOString(),
+        }));
+        output(rows, outputOpts);
+    });
+    signal
+        .command("summary")
+        .description("Show win rate and P&L summary")
+        .option("--last <minutes>", "Time window in minutes (default: 1440 = 24h)", Number.parseFloat, 1440)
+        .option("--exchange <id>", "Filter by exchange")
+        .option("--strategy <name>", "Filter by strategy")
+        .action(function () {
+        const outputOpts = getOutputOptions(this);
+        const opts = this.opts();
+        const summary = getSignalSummary({
+            minutes: opts.last,
+            exchange: opts.exchange,
+            strategy: opts.strategy,
+        });
+        if (outputOpts.json) {
+            output(withJsonContract("signal.summary", summary), outputOpts);
+            return;
+        }
+        console.log(`\n  Signal Summary (last ${opts.last} min)`);
+        console.log(`  ${"─".repeat(40)}`);
+        console.log(`  Total signals:  ${summary.total}`);
+        console.log(`  Up / Down:      ${summary.up} / ${summary.down}`);
+        console.log(`  Win rate:       ${(summary.winRate * 100).toFixed(1)}%`);
+        console.log(`  Total P&L:      $${summary.totalPnlUsd.toFixed(2)}`);
+        console.log(`  Avg P&L:        $${summary.avgPnlUsd.toFixed(2)}`);
+        if (summary.byStrategy.length > 0) {
+            console.log(`\n  By Strategy`);
+            console.log(`  ${"─".repeat(40)}`);
+            for (const s of summary.byStrategy) {
+                console.log(`  ${s.strategy}: ${s.up}/${s.total} (${(s.winRate * 100).toFixed(1)}%) P&L: $${s.totalPnlUsd.toFixed(2)}`);
+            }
+        }
+        if (summary.byMarket.length > 0) {
+            console.log(`\n  By Market`);
+            console.log(`  ${"─".repeat(40)}`);
+            for (const m of summary.byMarket) {
+                console.log(`  ${m.market}: ${m.up}/${m.total} (${(m.winRate * 100).toFixed(1)}%) P&L: $${m.totalPnlUsd.toFixed(2)}`);
+            }
+        }
+        console.log("");
+    });
+}

package/dist/commands/state/index.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerStateCommands(program: Command): void;

package/dist/commands/state/index.js

@@ -0,0 +1,5 @@
+import { registerStateShowCommand } from "./show.js";
+export function registerStateCommands(program) {
+    const state = program.command("state").description("Portfolio state and agent context");
+    registerStateShowCommand(state);
+}

package/dist/commands/state/show.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerStateShowCommand(state: Command): void;