perp-cli 0.3.3

package/dist/__tests__/integration/bridge.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration/bridge.integration.test.js

@@ -0,0 +1,309 @@
+/**
+ * Integration tests for bridge engine — READ-ONLY operations only.
+ *
+ * Tests real API calls to:
+ * - deBridge DLN quote API (GET, no signing)
+ * - Circle CCTP fee API (GET)
+ * - deBridge status API (GET)
+ * - getCctpQuote() (pure calculation, no RPC)
+ * - getBestQuote() (CCTP preferred, deBridge fallback)
+ *
+ * NO transactions are executed. NO funds are spent.
+ *
+ * Note: deBridge API has strict rate limits (~5 req/min).
+ * Tests are structured to minimize API calls and run sequentially.
+ */
+import { describe, it, expect } from "vitest";
+import { getDebridgeQuote, getCctpQuote, getBestQuote, checkDebridgeStatus, CHAIN_IDS, USDC_ADDRESSES, EXCHANGE_TO_CHAIN, } from "../../bridge-engine.js";
+// Dummy addresses for quote-only calls (never used for signing)
+const DUMMY_EVM = "0x0000000000000000000000000000000000000001";
+const DUMMY_SOLANA = "11111111111111111111111111111111";
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+describe("Bridge Integration — Read-Only", { timeout: 60000 }, () => {
+    // ══════════════════════════════════════════════════════════
+    // Constants & Configuration (no API calls)
+    // ══════════════════════════════════════════════════════════
+    describe("chain constants", () => {
+        it("all chains have valid chain IDs", () => {
+            for (const [chain, id] of Object.entries(CHAIN_IDS)) {
+                expect(typeof id).toBe("number");
+                expect(id).toBeGreaterThan(0);
+                expect(chain.length).toBeGreaterThan(0);
+            }
+        });
+        it("all USDC addresses are valid format", () => {
+            for (const [chain, addr] of Object.entries(USDC_ADDRESSES)) {
+                if (chain === "solana") {
+                    expect(addr.length).toBeGreaterThan(30);
+                    expect(addr.length).toBeLessThan(50);
+                }
+                else {
+                    expect(addr).toMatch(/^0x[0-9a-fA-F]{40}$/);
+                }
+            }
+        });
+        it("exchange-to-chain mapping covers all exchanges", () => {
+            expect(EXCHANGE_TO_CHAIN.pacifica).toBe("solana");
+            expect(EXCHANGE_TO_CHAIN.hyperliquid).toBe("hyperliquid");
+            expect(EXCHANGE_TO_CHAIN.lighter).toBe("arbitrum");
+        });
+        it("CCTP-supported chains have matching USDC addresses", () => {
+            for (const chain of ["solana", "arbitrum", "base"]) {
+                expect(USDC_ADDRESSES[chain]).toBeDefined();
+            }
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // Circle CCTP V2 Quotes (local calculation + fee API)
+    // No deBridge API calls — these are safe from rate limiting
+    // ══════════════════════════════════════════════════════════
+    describe("CCTP V2 quotes", () => {
+        it("solana → arbitrum: forwarding fee (standard finality)", async () => {
+            const quote = await getCctpQuote("solana", "arbitrum", 500);
+            expect(quote.provider).toBe("cctp");
+            expect(quote.fee).toBeLessThan(1); // forwarding ~$0.22
+            expect(quote.amountOut).toBeGreaterThan(499);
+            expect(quote.estimatedTime).toBeGreaterThan(0);
+        });
+        it("arbitrum → base: forwarding fee (L2 to L2)", async () => {
+            const quote = await getCctpQuote("arbitrum", "base", 200);
+            expect(quote.provider).toBe("cctp");
+            expect(quote.fee).toBeLessThan(1); // forwarding ~$0.22
+            expect(quote.estimatedTime).toBeGreaterThan(0);
+        });
+        it("base → solana: relay fee (no forwarding for Solana dst)", async () => {
+            const quote = await getCctpQuote("base", "solana", 100);
+            expect(quote.provider).toBe("cctp");
+            expect(quote.fee).toBeLessThan(1);
+            expect(quote.estimatedTime).toBeGreaterThan(0);
+        });
+        it("CCTP quote for tiny amount ($0.01): still valid", async () => {
+            const quote = await getCctpQuote("arbitrum", "base", 0.01);
+            expect(quote.amountOut).toBeGreaterThan(-1);
+            expect(quote.fee).toBeLessThan(1);
+        });
+        it("getBestQuote selects cheapest provider", async () => {
+            const q1 = await getBestQuote("arbitrum", "base", 1000, DUMMY_EVM, DUMMY_EVM);
+            expect(["cctp", "relay"]).toContain(q1.provider);
+            expect(q1.fee).toBeLessThan(2);
+            const q2 = await getBestQuote("solana", "arbitrum", 500, DUMMY_SOLANA, DUMMY_EVM);
+            expect(["cctp", "relay"]).toContain(q2.provider);
+            expect(q2.fee).toBeLessThan(2);
+        });
+        it("all CCTP quotes have consistent shape", async () => {
+            const routes = [
+                ["solana", "arbitrum"],
+                ["arbitrum", "base"],
+                ["base", "solana"],
+            ];
+            for (const [src, dst] of routes) {
+                const q = await getCctpQuote(src, dst, 100);
+                expect(q.provider).toBe("cctp");
+                expect(typeof q.srcChain).toBe("string");
+                expect(typeof q.dstChain).toBe("string");
+                expect(typeof q.amountIn).toBe("number");
+                expect(typeof q.amountOut).toBe("number");
+                expect(typeof q.fee).toBe("number");
+                expect(typeof q.estimatedTime).toBe("number");
+                expect(q.amountIn).toBeGreaterThanOrEqual(q.amountOut);
+                expect(q.raw).toBeDefined();
+            }
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // deBridge DLN Quote API (real HTTP calls — rate limited)
+    // Consolidated into fewer tests to avoid 429 errors
+    // ══════════════════════════════════════════════════════════
+    describe("deBridge DLN quotes (sequential, rate-limit aware)", () => {
+        it("solana → arbitrum: valid quote with fee breakdown", async () => {
+            const quote = await getDebridgeQuote("solana", "arbitrum", 100, DUMMY_SOLANA, DUMMY_EVM);
+            expect(quote.provider).toBe("debridge");
+            expect(quote.srcChain).toBe("solana");
+            expect(quote.dstChain).toBe("arbitrum");
+            expect(quote.amountIn).toBe(100);
+            expect(quote.amountOut).toBeGreaterThan(0);
+            expect(quote.amountOut).toBeLessThanOrEqual(100);
+            expect(quote.fee).toBeGreaterThanOrEqual(0);
+            expect(quote.fee).toBeLessThan(10); // < 10% for $100
+            expect(quote.estimatedTime).toBeGreaterThan(0);
+            expect(quote.raw).toBeDefined();
+            // Verify fee = amountIn - amountOut
+            expect(Math.abs(quote.fee - (quote.amountIn - quote.amountOut))).toBeLessThan(0.001);
+        });
+        it("arbitrum → solana: reverse route works", async () => {
+            await wait(1500); // respect rate limit
+            const quote = await getDebridgeQuote("arbitrum", "solana", 50, DUMMY_EVM, DUMMY_SOLANA);
+            expect(quote.provider).toBe("debridge");
+            expect(quote.amountIn).toBe(50);
+            expect(quote.amountOut).toBeGreaterThan(0);
+            expect(quote.amountOut).toBeLessThanOrEqual(50);
+        });
+        it("EVM-to-EVM route and small amount work", async () => {
+            await wait(1500);
+            // Test EVM-to-EVM
+            const quote = await getDebridgeQuote("base", "arbitrum", 200, DUMMY_EVM, DUMMY_EVM);
+            expect(quote.provider).toBe("debridge");
+            expect(quote.amountOut).toBeGreaterThan(0);
+            expect(quote.estimatedTime).toBeGreaterThan(0);
+        });
+        it("unsupported chain throws immediately (no API call)", async () => {
+            await expect(getDebridgeQuote("fakenet", "arbitrum", 100, DUMMY_EVM, DUMMY_EVM)).rejects.toThrow(/Unsupported chain/i);
+        });
+        it("zero amount: deBridge rejects", async () => {
+            await wait(1500);
+            await expect(getDebridgeQuote("solana", "arbitrum", 0, DUMMY_SOLANA, DUMMY_EVM)).rejects.toThrow();
+        });
+        it("getBestQuote returns valid quote (base → arbitrum)", async () => {
+            const quote = await getBestQuote("base", "arbitrum", 100, DUMMY_EVM, DUMMY_EVM);
+            expect(["cctp", "relay", "debridge"]).toContain(quote.provider);
+            expect(quote.amountOut).toBeGreaterThan(98);
+            expect(quote.fee).toBeLessThan(2);
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // CCTP vs deBridge Comparison (single deBridge call)
+    // ══════════════════════════════════════════════════════════
+    describe("CCTP vs deBridge comparison", () => {
+        it("CCTP is cheaper but slower than deBridge", async () => {
+            await wait(2000);
+            const cctp = await getCctpQuote("arbitrum", "base", 1000);
+            const debridge = await getDebridgeQuote("arbitrum", "base", 1000, DUMMY_EVM, DUMMY_EVM);
+            // CCTP is free, deBridge has fees
+            expect(cctp.fee).toBeLessThanOrEqual(debridge.fee);
+            expect(cctp.amountOut).toBeGreaterThanOrEqual(debridge.amountOut);
+            // deBridge is faster (~2s vs CCTP ~60-900s)
+            expect(debridge.estimatedTime).toBeLessThan(cctp.estimatedTime);
+            // Both have valid shapes
+            for (const q of [cctp, debridge]) {
+                expect(q.provider).toMatch(/^(cctp|debridge)$/);
+                expect(typeof q.srcChain).toBe("string");
+                expect(typeof q.dstChain).toBe("string");
+                expect(typeof q.amountIn).toBe("number");
+                expect(typeof q.amountOut).toBe("number");
+                expect(typeof q.fee).toBe("number");
+                expect(typeof q.estimatedTime).toBe("number");
+                expect(q.raw).toBeDefined();
+            }
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // deBridge Status API (single call)
+    // ══════════════════════════════════════════════════════════
+    describe("deBridge status check", () => {
+        it("non-existent order: returns response or 404", async () => {
+            await wait(1500);
+            try {
+                const status = await checkDebridgeStatus("0x0000000000000000000000000000000000000000000000000000000000000000");
+                expect(status).toBeDefined();
+            }
+            catch (err) {
+                expect(String(err)).toMatch(/failed|404|not found|429/i);
+            }
+        });
+        it("invalid order ID format: throws error", async () => {
+            await wait(1500);
+            try {
+                await checkDebridgeStatus("not-a-valid-order-id");
+                // If it doesn't throw, it should return something
+            }
+            catch (err) {
+                expect(err).toBeDefined();
+            }
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // Edge Cases (no API calls)
+    // ══════════════════════════════════════════════════════════
+    describe("edge cases (offline)", () => {
+        it("CCTP same-chain doesn't throw", async () => {
+            const quote = await getCctpQuote("arbitrum", "arbitrum", 100);
+            expect(quote.provider).toBe("cctp");
+            expect(quote.fee).toBeLessThan(1);
+            expect(quote.amountOut).toBeGreaterThan(99);
+        });
+        it("CCTP various amounts", async () => {
+            for (const amt of [0.01, 1, 100, 1000000]) {
+                const q = await getCctpQuote("arbitrum", "base", amt);
+                // Forwarding fee ~$0.22
+                expect(q.amountOut).toBeGreaterThanOrEqual(amt - 0.50);
+                expect(q.fee).toBeLessThan(1);
+            }
+        });
+        it("getBestQuote: all routes return valid cheapest provider", async () => {
+            const routes = [
+                ["solana", "arbitrum", DUMMY_SOLANA, DUMMY_EVM],
+                ["arbitrum", "base", DUMMY_EVM, DUMMY_EVM],
+                ["base", "solana", DUMMY_EVM, DUMMY_SOLANA],
+            ];
+            for (const [src, dst, sender, recipient] of routes) {
+                const quote = await getBestQuote(src, dst, 100, sender, recipient);
+                expect(["cctp", "relay", "debridge"]).toContain(quote.provider);
+                expect(quote.amountIn).toBeGreaterThanOrEqual(quote.amountOut);
+                expect(quote.amountOut).toBeGreaterThan(0);
+            }
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // CLI Command Integration (via process spawn)
+    // ══════════════════════════════════════════════════════════
+    describe("CLI bridge commands", () => {
+        const CLI_CWD = "/Users/hik/Documents/GitHub/pacifica/packages/cli";
+        const CLI_CMD = "npx tsx src/index.ts";
+        function runCliSafe(args) {
+            const { execSync } = require("child_process");
+            try {
+                const stdout = execSync(`${CLI_CMD} ${args}`, {
+                    encoding: "utf-8",
+                    cwd: CLI_CWD,
+                    timeout: 25000,
+                    env: { ...process.env, NODE_NO_WARNINGS: "1" },
+                    stdio: ["pipe", "pipe", "pipe"],
+                });
+                return { stdout, stderr: "", exitCode: 0 };
+            }
+            catch (err) {
+                const e = err;
+                return {
+                    stdout: e.stdout ?? "",
+                    stderr: e.stderr ?? "",
+                    exitCode: e.status ?? 1,
+                };
+            }
+        }
+        it("bridge chains: returns chain list as JSON", () => {
+            const { stdout } = runCliSafe("--json bridge chains");
+            const parsed = JSON.parse(stdout);
+            expect(parsed.ok).toBe(true);
+            expect(parsed.data.chains).toBeDefined();
+            expect(parsed.data.usdc).toBeDefined();
+            expect(parsed.data.exchanges).toBeDefined();
+            expect(parsed.data.chains.solana).toBe(7565164);
+            expect(parsed.data.chains.arbitrum).toBe(42161);
+        });
+        it("bridge chains: text mode has chain names", () => {
+            const { stdout } = runCliSafe("bridge chains");
+            expect(stdout).toContain("solana");
+            expect(stdout).toContain("arbitrum");
+            expect(stdout).toContain("ethereum");
+        });
+        it("bridge quote: CCTP route returns JSON (no deBridge API call)", () => {
+            // arbitrum → ethereum uses CCTP, avoids deBridge rate limit
+            const { stdout } = runCliSafe("--json bridge quote --from arbitrum --to ethereum --amount 500");
+            const parsed = JSON.parse(stdout);
+            expect(parsed.ok).toBe(true);
+            expect(parsed.data.provider).toBe("cctp");
+            expect(parsed.data.srcChain).toBe("arbitrum");
+            expect(parsed.data.dstChain).toBe("ethereum");
+            expect(parsed.data.amountIn).toBe(500);
+            expect(parsed.data.fee).toBeLessThan(1); // forwarding fee ~$0.22
+            expect(parsed.data.estimatedTime).toBeGreaterThan(0);
+        });
+        it("bridge --help lists subcommands", () => {
+            const { stdout } = runCliSafe("bridge --help");
+            expect(stdout).toContain("chains");
+            expect(stdout).toContain("quote");
+            expect(stdout).toContain("send");
+            expect(stdout).toContain("status");
+        });
+    });
+});

package/dist/__tests__/integration/cli-e2e.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration/cli-e2e.integration.test.js

@@ -0,0 +1,202 @@
+import { execSync } from "child_process";
+import { writeFileSync, unlinkSync, existsSync } from "fs";
+import { describe, it, expect, afterAll } from "vitest";
+const CLI_CWD = "/Users/hik/Documents/GitHub/pacifica/packages/cli";
+const CLI_CMD = "npx tsx src/index.ts";
+/** Temp files created during tests, cleaned up in afterAll */
+const tempFiles = [];
+function runCli(args) {
+    return execSync(`${CLI_CMD} ${args}`, {
+        encoding: "utf-8",
+        cwd: CLI_CWD,
+        timeout: 25000,
+        env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
+}
+function runCliSafe(args) {
+    try {
+        const stdout = execSync(`${CLI_CMD} ${args}`, {
+            encoding: "utf-8",
+            cwd: CLI_CWD,
+            timeout: 25000,
+            env: { ...process.env, NODE_NO_WARNINGS: "1" },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return { stdout, stderr: "", exitCode: 0 };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            stdout: e.stdout ?? "",
+            stderr: e.stderr ?? "",
+            exitCode: e.status ?? 1,
+        };
+    }
+}
+function writeTempFile(name, content) {
+    const path = `/tmp/${name}`;
+    writeFileSync(path, content, "utf-8");
+    tempFiles.push(path);
+    return path;
+}
+afterAll(() => {
+    for (const f of tempFiles) {
+        if (existsSync(f)) {
+            try {
+                unlinkSync(f);
+            }
+            catch { /* ignore */ }
+        }
+    }
+});
+describe("CLI E2E Integration Tests", { timeout: 30000 }, () => {
+    // ───────────────────── schema command ─────────────────────
+    describe("perp schema --json", () => {
+        let schema;
+        /** schema may be wrapped in envelope { ok, data } or raw */
+        function parseSchema(output) {
+            const parsed = JSON.parse(output);
+            return (parsed.data ?? parsed);
+        }
+        it("outputs valid JSON with expected top-level structure", () => {
+            const output = runCli("schema");
+            schema = parseSchema(output);
+            expect(schema).toHaveProperty("schemaVersion");
+            expect(schema).toHaveProperty("commands");
+            expect(schema).toHaveProperty("errorCodes");
+            expect(schema).toHaveProperty("exchanges");
+            expect(Array.isArray(schema.commands)).toBe(true);
+            expect(Array.isArray(schema.exchanges)).toBe(true);
+            expect(typeof schema.errorCodes).toBe("object");
+        });
+        it("commands array contains known command names", () => {
+            const output = runCli("schema");
+            schema = parseSchema(output);
+            const commandNames = schema.commands.map((c) => c.name);
+            expect(commandNames).toContain("market");
+            expect(commandNames).toContain("account");
+            expect(commandNames).toContain("trade");
+            expect(commandNames).toContain("arb");
+            expect(commandNames).toContain("plan");
+        });
+        it("errorCodes contains key error types with retryable flags", () => {
+            const output = runCli("schema");
+            schema = parseSchema(output);
+            const errorCodes = schema.errorCodes;
+            expect(errorCodes).toHaveProperty("INSUFFICIENT_BALANCE");
+            expect(errorCodes.INSUFFICIENT_BALANCE.retryable).toBe(false);
+            expect(errorCodes).toHaveProperty("RATE_LIMITED");
+            expect(errorCodes.RATE_LIMITED.retryable).toBe(true);
+            expect(errorCodes).toHaveProperty("TIMEOUT");
+            expect(errorCodes.TIMEOUT.retryable).toBe(true);
+            expect(errorCodes).toHaveProperty("EXCHANGE_UNREACHABLE");
+            expect(errorCodes.EXCHANGE_UNREACHABLE.retryable).toBe(true);
+            expect(errorCodes).toHaveProperty("UNKNOWN");
+            expect(errorCodes.UNKNOWN.retryable).toBe(false);
+        });
+    });
+    // ───────────────────── plan commands ─────────────────────
+    describe("perp plan example", () => {
+        it("outputs valid JSON with version 1.0 and steps array", () => {
+            const output = runCli("plan example");
+            const parsed = JSON.parse(output);
+            // plan example may be wrapped in envelope (ok/data) or raw
+            const plan = parsed.data ?? parsed;
+            expect(plan.version).toBe("1.0");
+            expect(Array.isArray(plan.steps)).toBe(true);
+            expect(plan.steps.length).toBeGreaterThan(0);
+            // Each step should have id, action, params
+            for (const step of plan.steps) {
+                expect(step).toHaveProperty("id");
+                expect(step).toHaveProperty("action");
+                expect(step).toHaveProperty("params");
+            }
+        });
+    });
+    describe("perp plan validate", () => {
+        it("succeeds for a valid plan (exit 0, output contains 'valid')", () => {
+            const validPlan = {
+                version: "1.0",
+                description: "Test plan",
+                steps: [
+                    {
+                        id: "step1",
+                        action: "check_balance",
+                        params: { minAvailable: 50 },
+                        onFailure: "abort",
+                    },
+                    {
+                        id: "step2",
+                        action: "market_order",
+                        params: { symbol: "ETH", side: "buy", size: "0.1" },
+                        onFailure: "abort",
+                        dependsOn: "step1",
+                    },
+                ],
+            };
+            const filePath = writeTempFile("test-valid-plan.json", JSON.stringify(validPlan, null, 2));
+            const { stdout, exitCode } = runCliSafe(`plan validate ${filePath}`);
+            expect(exitCode).toBe(0);
+            // The human-readable output says "valid" or the JSON output includes valid:true
+            const lower = stdout.toLowerCase();
+            expect(lower).toContain("valid");
+        });
+        it("reports errors for an invalid plan (wrong version) with --json", () => {
+            const invalidPlan = {
+                version: "999.0",
+                steps: [
+                    {
+                        id: "bad",
+                        action: "market_order",
+                        params: {},
+                    },
+                ],
+            };
+            const filePath = writeTempFile("test-invalid-plan.json", JSON.stringify(invalidPlan, null, 2));
+            const { stdout, exitCode } = runCliSafe(`--json plan validate ${filePath}`);
+            // Should still exit 0 because validation itself succeeds (reports errors in JSON)
+            expect(exitCode).toBe(0);
+            const parsed = JSON.parse(stdout);
+            expect(parsed.ok).toBe(true);
+            // The data.valid should be false
+            expect(parsed.data.valid).toBe(false);
+            expect(Array.isArray(parsed.data.errors)).toBe(true);
+            expect(parsed.data.errors.length).toBeGreaterThan(0);
+            // Should mention version mismatch
+            const allErrors = parsed.data.errors.join(" ");
+            expect(allErrors).toContain("version");
+        });
+    });
+    // ───────────────────── --json error wrapping ─────────────────────
+    describe("--json structured error output", () => {
+        it("outputs structured JSON error for a nonexistent plan file", () => {
+            // Use plan validate with a file that does not exist — this triggers
+            // withJsonErrors which wraps the ENOENT in the standard envelope.
+            const { stdout, exitCode } = runCliSafe("--json plan validate /tmp/__nonexistent_cli_test_file_99999.json");
+            expect(exitCode).toBe(0);
+            const parsed = JSON.parse(stdout);
+            expect(parsed.ok).toBe(false);
+            expect(parsed.error).toBeDefined();
+            expect(typeof parsed.error.code).toBe("string");
+            expect(typeof parsed.error.message).toBe("string");
+            expect(parsed.error.message).toContain("ENOENT");
+            expect(typeof parsed.error.retryable).toBe("boolean");
+            expect(parsed).toHaveProperty("meta");
+            expect(parsed.meta).toHaveProperty("timestamp");
+        });
+    });
+    // ───────────────────── help output ─────────────────────
+    describe("perp --help", () => {
+        it("includes all major commands in help output", () => {
+            const { stdout } = runCliSafe("--help");
+            const helpText = stdout.toLowerCase();
+            expect(helpText).toContain("schema");
+            expect(helpText).toContain("plan");
+            expect(helpText).toContain("trade");
+            expect(helpText).toContain("stream");
+            expect(helpText).toContain("market");
+            expect(helpText).toContain("account");
+            expect(helpText).toContain("arb");
+        });
+    });
+});

package/dist/__tests__/integration/dex-arb.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration/dex-arb.integration.test.js

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest";
+import { fetchAllDexAssets, findDexArbPairs, scanDexArb } from "../../dex-asset-map.js";
+/**
+ * Integration tests for HIP-3 cross-dex arb scanning.
+ *
+ * Hits real Hyperliquid mainnet API (read-only, no private key needed).
+ *
+ * Run: pnpm --filter perp-cli test -- --testPathPattern dex-arb.integration
+ */
+describe("fetchAllDexAssets — live API", () => {
+    it("returns assets from native HL and at least 3 deployed dexes", async () => {
+        const assets = await fetchAllDexAssets();
+        expect(assets.length).toBeGreaterThan(100);
+        // Check we have native HL assets
+        const hlAssets = assets.filter(a => a.dex === "hl");
+        expect(hlAssets.length).toBeGreaterThan(100);
+        expect(hlAssets.find(a => a.base === "BTC")).toBeTruthy();
+        // Check we have at least xyz dex
+        const xyzAssets = assets.filter(a => a.dex === "xyz");
+        expect(xyzAssets.length).toBeGreaterThan(10);
+        expect(xyzAssets.find(a => a.base === "TSLA")).toBeTruthy();
+        // Verify data shape
+        for (const asset of assets.slice(0, 10)) {
+            expect(asset.markPrice).toBeGreaterThan(0);
+            expect(typeof asset.fundingRate).toBe("number");
+            expect(asset.dex).toBeTruthy();
+            expect(asset.base).toBeTruthy();
+            expect(asset.raw).toBeTruthy();
+        }
+        const dexes = new Set(assets.map(a => a.dex));
+        console.log(`Dexes found: ${[...dexes].join(", ")} (${dexes.size} total)`);
+        console.log(`Total active assets: ${assets.length}`);
+    }, 30000);
+});
+describe("findDexArbPairs — live data", () => {
+    it("finds TSLA arb pairs across dexes", async () => {
+        const assets = await fetchAllDexAssets();
+        const tslaAssets = assets.filter(a => a.base === "TSLA");
+        expect(tslaAssets.length).toBeGreaterThanOrEqual(2);
+        const pairs = findDexArbPairs(tslaAssets);
+        // C(n,2) pairs if n dexes have TSLA
+        expect(pairs.length).toBeGreaterThanOrEqual(1);
+        for (const p of pairs) {
+            expect(p.underlying).toBe("TSLA");
+            expect(p.priceGapPct).toBeLessThan(2); // prices should be very close
+            expect(p.long.dex).not.toBe(p.short.dex);
+        }
+        const dexes = new Set(tslaAssets.map(a => a.dex));
+        console.log(`TSLA on dexes: ${[...dexes].join(", ")} → ${pairs.length} arb pairs`);
+        for (const p of pairs.slice(0, 3)) {
+            console.log(`  L:${p.long.dex} S:${p.short.dex} spread:${p.annualSpread.toFixed(1)}% gap:${p.priceGapPct.toFixed(3)}%`);
+        }
+    }, 30000);
+    it("finds BTC arb between hl native and hyna dex", async () => {
+        const assets = await fetchAllDexAssets();
+        const btcAssets = assets.filter(a => a.base === "BTC");
+        const hlBTC = btcAssets.find(a => a.dex === "hl");
+        const hynaBTC = btcAssets.find(a => a.dex === "hyna");
+        expect(hlBTC).toBeTruthy();
+        expect(hynaBTC).toBeTruthy();
+        // Prices should be very close (< 0.5%)
+        const gap = Math.abs(hlBTC.markPrice - hynaBTC.markPrice) / hlBTC.markPrice * 100;
+        expect(gap).toBeLessThan(0.5);
+        console.log(`BTC: hl=$${hlBTC.markPrice.toFixed(0)} hyna=$${hynaBTC.markPrice.toFixed(0)} gap:${gap.toFixed(4)}%`);
+    }, 30000);
+    it("correctly rejects USAR vs US500 (different products)", async () => {
+        const assets = await fetchAllDexAssets();
+        const usar = assets.find(a => a.base === "USAR");
+        const us500 = assets.find(a => a.base === "US500");
+        if (usar && us500) {
+            // Prices should be wildly different
+            const gap = Math.abs(usar.markPrice - us500.markPrice) / Math.min(usar.markPrice, us500.markPrice) * 100;
+            expect(gap).toBeGreaterThan(100); // way more than 5%
+            // findDexArbPairs should not match these
+            const pairs = findDexArbPairs([usar, us500]);
+            expect(pairs).toHaveLength(0);
+            console.log(`USAR=$${usar.markPrice.toFixed(2)} vs US500=$${us500.markPrice.toFixed(2)} → gap:${gap.toFixed(0)}% → correctly rejected`);
+        }
+    }, 30000);
+});
+describe("scanDexArb — live full scan", () => {
+    it("returns sorted arb opportunities", async () => {
+        const pairs = await scanDexArb({ minAnnualSpread: 5 });
+        expect(pairs.length).toBeGreaterThan(0);
+        // Should be sorted by annualSpread descending
+        for (let i = 1; i < pairs.length; i++) {
+            expect(pairs[i].annualSpread).toBeLessThanOrEqual(pairs[i - 1].annualSpread);
+        }
+        // All pairs should have different dexes
+        for (const p of pairs) {
+            expect(p.long.dex).not.toBe(p.short.dex);
+        }
+        // All pairs should have < 5% price gap
+        for (const p of pairs) {
+            expect(p.priceGapPct).toBeLessThan(5);
+        }
+        console.log(`Found ${pairs.length} arb opportunities (>5% annual spread)`);
+        console.log(`Top 5:`);
+        for (const p of pairs.slice(0, 5)) {
+            console.log(`  ${p.underlying}: ${p.annualSpread.toFixed(1)}% [${p.long.dex}↔${p.short.dex}]`);
+        }
+    }, 30000);
+    it("no-native mode excludes HL base assets", async () => {
+        const withNative = await scanDexArb({ minAnnualSpread: 0, includeNative: true });
+        const withoutNative = await scanDexArb({ minAnnualSpread: 0, includeNative: false });
+        // Without native, should have fewer pairs (no hl↔dex pairs)
+        const nativePairs = withNative.filter(p => p.long.dex === "hl" || p.short.dex === "hl");
+        const nonNativePairs = withoutNative.filter(p => p.long.dex === "hl" || p.short.dex === "hl");
+        expect(nonNativePairs.length).toBe(0);
+        if (nativePairs.length > 0) {
+            expect(withNative.length).toBeGreaterThan(withoutNative.length);
+        }
+        console.log(`With native: ${withNative.length} pairs (${nativePairs.length} include HL native)`);
+        console.log(`Without native: ${withoutNative.length} pairs`);
+    }, 30000);
+});

package/dist/__tests__/integration/envelope-consistency.integration.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Integration tests verifying JSON envelope consistency across all CLI commands.
+ *
+ * Every --json output must:
+ * 1. Be valid JSON (single object, no extra text)
+ * 2. Have ok: boolean
+ * 3. If ok=true: have data and meta.timestamp
+ * 4. If ok=false: have error.code, error.message, and meta.timestamp
+ *
+ * These tests spawn the real CLI process to catch any console.log leaks,
+ * chalk output in JSON mode, or missing envelope wrappers.
+ */
+import "dotenv/config";