perp-cli 0.3.3

package/dist/__tests__/integration/envelope-consistency.integration.test.js

@@ -0,0 +1,205 @@
+/**
+ * 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";
+import { execSync } from "child_process";
+import { describe, it, expect } from "vitest";
+const CLI_CWD = "/Users/hik/Documents/GitHub/pacifica/packages/cli";
+const CLI_CMD = "npx tsx src/index.ts";
+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 validateEnvelope(raw, label) {
+    // 1. Must be valid JSON
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`[${label}] stdout is not valid JSON:\n${raw.slice(0, 500)}`);
+    }
+    // 2. Must have ok: boolean
+    expect(typeof parsed.ok).toBe("boolean");
+    // 3. Must have meta.timestamp
+    expect(parsed.meta).toBeDefined();
+    expect(typeof parsed.meta.timestamp).toBe("string");
+    expect(parsed.meta.timestamp.length).toBeGreaterThan(0);
+    // Verify ISO 8601
+    const ts = new Date(parsed.meta.timestamp);
+    expect(ts.getTime()).toBeGreaterThan(0);
+    if (parsed.ok) {
+        // 4a. Success: must have data
+        expect(parsed.data).toBeDefined();
+    }
+    else {
+        // 4b. Error: must have error.code and error.message
+        expect(parsed.error).toBeDefined();
+        expect(typeof parsed.error.code).toBe("string");
+        expect(parsed.error.code.length).toBeGreaterThan(0);
+        expect(typeof parsed.error.message).toBe("string");
+    }
+    return parsed;
+}
+describe("JSON Envelope Consistency", { timeout: 30000 }, () => {
+    // ── Commands that require no adapter (always work) ──
+    describe("no-adapter commands", () => {
+        it("api-spec: valid success envelope", () => {
+            const { stdout } = runCliSafe("--json api-spec");
+            const env = validateEnvelope(stdout, "api-spec");
+            expect(env.ok).toBe(true);
+        });
+        it("plan example: valid JSON output", () => {
+            const { stdout } = runCliSafe("--json plan example");
+            const parsed = JSON.parse(stdout);
+            // plan example wraps in envelope in --json mode
+            if (parsed.ok !== undefined) {
+                // Envelope mode
+                expect(parsed.ok).toBe(true);
+                expect(parsed.data).toBeDefined();
+            }
+            else {
+                // Raw plan JSON (legacy)
+                expect(parsed.steps || parsed.version).toBeDefined();
+            }
+        });
+    });
+    // ── Error paths ──
+    describe("error envelopes", () => {
+        it("unknown command: CLI_ERROR envelope", () => {
+            const { stdout } = runCliSafe("--json nonexistentcommand999");
+            const env = validateEnvelope(stdout, "unknown command");
+            expect(env.ok).toBe(false);
+            expect(env.error.code).toBe("CLI_ERROR");
+        });
+        it("plan validate with bad file: error envelope", () => {
+            const { stdout } = runCliSafe("--json plan validate /tmp/__no_file_here_99.json");
+            const env = validateEnvelope(stdout, "plan validate bad file");
+            expect(env.ok).toBe(false);
+            expect(env.error.message).toBeTruthy();
+        });
+        it("stdout has no extra text before/after JSON", () => {
+            const { stdout } = runCliSafe("--json api-spec");
+            // Trim whitespace, should start with { and end with }
+            const trimmed = stdout.trim();
+            expect(trimmed.startsWith("{")).toBe(true);
+            expect(trimmed.endsWith("}")).toBe(true);
+            // No extra lines
+            const lines = trimmed.split("\n").filter((l) => l.trim().length > 0);
+            // All lines should be part of the JSON (indented)
+            const reparsed = JSON.parse(trimmed);
+            expect(reparsed.ok).toBeDefined();
+        });
+        it("stderr is empty in --json mode for error paths", () => {
+            const { stderr } = runCliSafe("--json nonexistentcommand999");
+            // In JSON mode, errors go to stdout as JSON, not stderr
+            // stderr should be empty or only contain warnings
+            // (Commander may still write to stderr in some cases)
+            // We mainly verify that stdout has the JSON envelope
+        });
+    });
+    // ── Commands that need HL adapter (read-only) ──
+    const HAS_KEY = !!(process.env.HYPERLIQUID_PRIVATE_KEY || process.env.HL_PRIVATE_KEY);
+    describe.skipIf(!HAS_KEY)("HL adapter commands — envelope validation", () => {
+        it("market list: success envelope with array data", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid market list");
+            const env = validateEnvelope(stdout, "market list");
+            expect(env.ok).toBe(true);
+            expect(Array.isArray(env.data)).toBe(true);
+            expect(env.data.length).toBeGreaterThan(0);
+        });
+        it("market mid BTC: success envelope with mid price", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid market mid BTC");
+            const env = validateEnvelope(stdout, "market mid BTC");
+            expect(env.ok).toBe(true);
+            const data = env.data;
+            expect(data.symbol).toBe("BTC");
+            expect(data.mid).toBeDefined();
+        });
+        it("market info BTC: success envelope with market info", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid market info BTC");
+            const env = validateEnvelope(stdout, "market info BTC");
+            expect(env.ok).toBe(true);
+        });
+        it("market book BTC: success envelope with orderbook", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid market book BTC");
+            const env = validateEnvelope(stdout, "market book BTC");
+            expect(env.ok).toBe(true);
+            const data = env.data;
+            expect(data.bids).toBeDefined();
+            expect(data.asks).toBeDefined();
+        });
+        it("account info: success envelope with balance", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid account info");
+            const env = validateEnvelope(stdout, "account info");
+            expect(env.ok).toBe(true);
+            const data = env.data;
+            expect(data.equity).toBeDefined();
+            expect(data.available).toBeDefined();
+        });
+        it("account positions: success envelope with array", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid account positions");
+            const env = validateEnvelope(stdout, "account positions");
+            expect(env.ok).toBe(true);
+            expect(Array.isArray(env.data)).toBe(true);
+        });
+        it("account orders: success envelope with array", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid account orders");
+            const env = validateEnvelope(stdout, "account orders");
+            expect(env.ok).toBe(true);
+            expect(Array.isArray(env.data)).toBe(true);
+        });
+        it("status: success envelope with exchange, balance, positions, orders", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid status");
+            const env = validateEnvelope(stdout, "status");
+            expect(env.ok).toBe(true);
+            const data = env.data;
+            expect(data.exchange).toBe("hyperliquid");
+            expect(data.balance).toBeDefined();
+            expect(data.positions).toBeDefined();
+            expect(data.orders).toBeDefined();
+        });
+        it("account margin XYZFAKE: POSITION_NOT_FOUND error envelope", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid account margin XYZFAKE");
+            const env = validateEnvelope(stdout, "account margin XYZFAKE");
+            expect(env.ok).toBe(false);
+            expect(env.error.code).toBe("POSITION_NOT_FOUND");
+        });
+        it("trade fills: success envelope with array", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid trade fills");
+            const env = validateEnvelope(stdout, "trade fills");
+            expect(env.ok).toBe(true);
+            expect(Array.isArray(env.data)).toBe(true);
+        });
+        it("health: success envelope with healthy flag", () => {
+            const { stdout } = runCliSafe("--json -e hyperliquid health");
+            const env = validateEnvelope(stdout, "health");
+            expect(env.ok).toBe(true);
+        });
+    });
+});

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

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

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

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+/**
+ * Integration tests for HIP-3 deployed perp dex support.
+ *
+ * These tests hit the real Hyperliquid mainnet API (read-only)
+ * to verify our parsing of allPerpMetas and dex-specific queries.
+ *
+ * No private key needed — all calls are public info endpoints.
+ *
+ * Run: pnpm --filter perp-cli test -- --testPathPattern hip3-dex.integration
+ */
+const HL_INFO_URL = "https://api.hyperliquid.xyz/info";
+async function infoPost(body) {
+    const res = await fetch(HL_INFO_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.json();
+}
+describe("HIP-3 Integration — allPerpMetas", () => {
+    it("returns an array with native perps as first entry", async () => {
+        const data = await infoPost({ type: "allPerpMetas" });
+        expect(Array.isArray(data)).toBe(true);
+        expect(data.length).toBeGreaterThanOrEqual(1);
+        // First entry: native perps (BTC, ETH, etc.)
+        const native = data[0];
+        expect(native).toHaveProperty("universe");
+        expect(Array.isArray(native.universe)).toBe(true);
+        expect(native.universe.length).toBeGreaterThan(100); // 200+ native perps
+        const btc = native.universe.find((a) => a.name === "BTC");
+        expect(btc).toBeTruthy();
+        expect(btc.maxLeverage).toBeGreaterThanOrEqual(40);
+    }, 15000);
+    it("has deployed dexes after index 0", async () => {
+        const data = await infoPost({ type: "allPerpMetas" });
+        expect(data.length).toBeGreaterThan(1); // at least 1 deployed dex
+        // Each deployed dex entry has universe with prefixed assets
+        for (let i = 1; i < data.length; i++) {
+            const entry = data[i];
+            expect(entry).toHaveProperty("universe");
+            expect(entry).toHaveProperty("collateralToken");
+            if (entry.universe.length === 0)
+                continue; // skip empty
+            // Assets should have a prefix with colon
+            const firstName = entry.universe[0].name;
+            expect(firstName).toContain(":");
+        }
+    }, 15000);
+    it("extracts known dex names (xyz, vntl, etc.)", async () => {
+        const data = await infoPost({ type: "allPerpMetas" });
+        const dexNames = [];
+        for (let i = 1; i < data.length; i++) {
+            const universe = data[i]?.universe ?? [];
+            if (universe.length === 0)
+                continue;
+            const first = universe[0].name;
+            const colon = first.indexOf(":");
+            if (colon > 0)
+                dexNames.push(first.slice(0, colon));
+        }
+        expect(dexNames.length).toBeGreaterThan(0);
+        // xyz is one of the most established deployed dexes
+        expect(dexNames).toContain("xyz");
+        console.log("Discovered deployed dexes:", dexNames.join(", "));
+    }, 15000);
+});
+describe("HIP-3 Integration — dex-specific metaAndAssetCtxs", () => {
+    it("fetches xyz dex markets with mark prices", async () => {
+        const data = await infoPost({ type: "metaAndAssetCtxs", dex: "xyz" });
+        expect(Array.isArray(data)).toBe(true);
+        expect(data.length).toBe(2); // [meta, ctxs]
+        const universe = data[0]?.universe ?? [];
+        const ctxs = data[1] ?? [];
+        expect(universe.length).toBeGreaterThan(0);
+        expect(ctxs.length).toBe(universe.length);
+        // All assets should have xyz: prefix
+        for (const asset of universe) {
+            expect(asset.name.startsWith("xyz:")).toBe(true);
+        }
+        // Check TSLA exists and has valid price
+        const tslaIdx = universe.findIndex((a) => a.name === "xyz:TSLA");
+        expect(tslaIdx).toBeGreaterThanOrEqual(0);
+        const tslaCtx = ctxs[tslaIdx];
+        expect(Number(tslaCtx.markPx)).toBeGreaterThan(0);
+        expect(tslaCtx).toHaveProperty("funding");
+        expect(tslaCtx).toHaveProperty("openInterest");
+        console.log(`xyz:TSLA — mark: $${tslaCtx.markPx}, funding: ${tslaCtx.funding}, OI: ${tslaCtx.openInterest}`);
+    }, 15000);
+    it("fetches dex-specific meta (used for asset map)", async () => {
+        const data = await infoPost({ type: "meta", dex: "xyz" });
+        expect(data).toHaveProperty("universe");
+        expect(data.universe.length).toBeGreaterThan(0);
+        expect(data.universe[0].name).toContain("xyz:");
+        // Verify assets can be mapped to indices
+        const assetMap = new Map();
+        data.universe.forEach((a, i) => {
+            assetMap.set(a.name, i);
+        });
+        expect(assetMap.has("xyz:TSLA")).toBe(true);
+        expect(assetMap.has("xyz:NVDA")).toBe(true);
+        console.log(`xyz dex has ${assetMap.size} assets`);
+    }, 15000);
+});
+describe("HIP-3 Integration — dex-specific clearinghouseState", () => {
+    it("returns valid structure for a random address", async () => {
+        // Use a zero address — no positions, but structure should be valid
+        const address = "0x0000000000000000000000000000000000000001";
+        const data = await infoPost({
+            type: "clearinghouseState",
+            user: address,
+            dex: "xyz",
+        });
+        // Should return clearinghouse state structure
+        expect(data).toBeTruthy();
+        expect(data).toHaveProperty("assetPositions");
+        expect(Array.isArray(data.assetPositions)).toBe(true);
+        // Zero address should have no positions
+        expect(data.assetPositions.length).toBe(0);
+        // Should have margin info
+        const hasMoney = data.marginSummary || data.crossMarginSummary;
+        expect(hasMoney).toBeTruthy();
+    }, 15000);
+});
+describe("HIP-3 Integration — native vs dex asset separation", () => {
+    it("native perps do not have prefixed names", async () => {
+        const data = await infoPost({ type: "metaAndAssetCtxs" });
+        const universe = data[0]?.universe ?? [];
+        // Native assets should NOT have colon prefix
+        const btc = universe.find((a) => a.name === "BTC");
+        expect(btc).toBeTruthy();
+        expect(btc.name).not.toContain(":");
+        // None of the native assets should be prefixed
+        const prefixed = universe.filter((a) => a.name.includes(":"));
+        expect(prefixed.length).toBe(0);
+    }, 15000);
+    it("dex perps all have matching prefix", async () => {
+        const data = await infoPost({ type: "metaAndAssetCtxs", dex: "xyz" });
+        const universe = data[0]?.universe ?? [];
+        // ALL xyz dex assets should have "xyz:" prefix
+        for (const asset of universe) {
+            expect(asset.name.startsWith("xyz:")).toBe(true);
+        }
+    }, 15000);
+});

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

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

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

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { HyperliquidAdapter } from "../../exchanges/hyperliquid.js";
+/**
+ * Integration tests for Hyperliquid exchange adapter (Testnet).
+ *
+ * Prerequisites:
+ *   1. Set HYPERLIQUID_PRIVATE_KEY env var (0x-prefixed EVM private key, 66 chars)
+ *   2. Have testnet ETH on Arbitrum Sepolia (for gas)
+ *   3. Have testnet USDC deposited into Hyperliquid testnet
+ *
+ * Run: HYPERLIQUID_PRIVATE_KEY=<key> pnpm --filter perp-cli test -- --testPathPattern integration/hyperliquid
+ */
+const SKIP = !process.env.HYPERLIQUID_PRIVATE_KEY;
+describe.skipIf(SKIP)("Hyperliquid Integration (Testnet)", () => {
+    let adapter;
+    beforeAll(async () => {
+        adapter = new HyperliquidAdapter(process.env.HYPERLIQUID_PRIVATE_KEY, true);
+        await adapter.init();
+    }, 30000);
+    describe("Read-only operations", () => {
+        it("initializes and has address", () => {
+            expect(adapter.address).toBeTruthy();
+            expect(adapter.address.startsWith("0x")).toBe(true);
+        });
+        it("fetches markets", async () => {
+            const markets = await adapter.getMarkets();
+            expect(markets.length).toBeGreaterThan(0);
+            const btc = markets.find((m) => m.symbol === "BTC");
+            expect(btc).toBeTruthy();
+            expect(Number(btc.markPrice)).toBeGreaterThan(0);
+        });
+        it("resolves asset index for BTC", () => {
+            const idx = adapter.getAssetIndex("BTC");
+            expect(typeof idx).toBe("number");
+            expect(idx).toBeGreaterThanOrEqual(0);
+        });
+        it("fetches orderbook for BTC", async () => {
+            const book = await adapter.getOrderbook("BTC");
+            expect(book.bids.length).toBeGreaterThan(0);
+            expect(book.asks.length).toBeGreaterThan(0);
+        });
+        it("fetches balance", async () => {
+            const balance = await adapter.getBalance();
+            expect(balance).toHaveProperty("equity");
+            expect(Number(balance.equity)).toBeGreaterThanOrEqual(0);
+        });
+        it("fetches positions", async () => {
+            const positions = await adapter.getPositions();
+            expect(Array.isArray(positions)).toBe(true);
+        });
+        it("fetches open orders", async () => {
+            const orders = await adapter.getOpenOrders();
+            expect(Array.isArray(orders)).toBe(true);
+        });
+    });
+    describe("Trading operations", () => {
+        const TEST_SYMBOL = "BTC";
+        let limitOrderId;
+        it("places a limit buy order (far from market)", async () => {
+            const result = await adapter.limitOrder(TEST_SYMBOL, "buy", "10000", "0.001");
+            expect(result).toBeTruthy();
+            const orders = await adapter.getOpenOrders();
+            const myOrder = orders.find((o) => o.symbol === TEST_SYMBOL && o.side === "buy");
+            if (myOrder) {
+                limitOrderId = myOrder.orderId;
+            }
+        });
+        it("cancels the limit order", async () => {
+            if (!limitOrderId)
+                return;
+            const result = await adapter.cancelOrder(TEST_SYMBOL, limitOrderId);
+            expect(result).toBeTruthy();
+        });
+        it("cancel all orders succeeds", async () => {
+            const result = await adapter.cancelAllOrders();
+            expect(result).toBeTruthy();
+        });
+    });
+});

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

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

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

@@ -0,0 +1,53 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { LighterAdapter } from "../../exchanges/lighter.js";
+/**
+ * Integration tests for Lighter exchange adapter (Mainnet ONLY — no testnet available).
+ *
+ * ⚠️  WARNING: Lighter has NO testnet. These tests run on MAINNET with REAL funds.
+ *     Only run if you understand the risks and have funded an account.
+ *
+ * Prerequisites:
+ *   1. Set LIGHTER_PRIVATE_KEY env var (0x-prefixed EVM private key, 66 chars)
+ *   2. Have ETH on Ethereum L1 for gas (~$3-10 per tx)
+ *   3. Have USDC deposited into Lighter (mainnet)
+ *
+ * Run: LIGHTER_PRIVATE_KEY=<key> LIGHTER_INTEGRATION=1 pnpm --filter perp-cli test -- --testPathPattern integration/lighter
+ */
+// Require BOTH the key AND explicit opt-in flag (since this is mainnet)
+const SKIP = !process.env.LIGHTER_PRIVATE_KEY || !process.env.LIGHTER_INTEGRATION;
+describe.skipIf(SKIP)("Lighter Integration (Mainnet)", () => {
+    let adapter;
+    beforeAll(async () => {
+        adapter = new LighterAdapter(process.env.LIGHTER_PRIVATE_KEY);
+        await adapter.init();
+    }, 30000);
+    describe("Read-only operations (safe)", () => {
+        it("initializes with account index", () => {
+            expect(adapter.accountIndex).toBeGreaterThanOrEqual(0);
+        });
+        it("fetches markets", async () => {
+            const markets = await adapter.getMarkets();
+            expect(Array.isArray(markets)).toBe(true);
+        });
+        it("fetches orderbook", async () => {
+            const book = await adapter.getOrderbook("BTC");
+            expect(book).toHaveProperty("bids");
+            expect(book).toHaveProperty("asks");
+        });
+        it("fetches balance", async () => {
+            const balance = await adapter.getBalance();
+            expect(balance).toHaveProperty("equity");
+            expect(Number(balance.equity)).toBeGreaterThanOrEqual(0);
+        });
+        it("fetches positions", async () => {
+            const positions = await adapter.getPositions();
+            expect(Array.isArray(positions)).toBe(true);
+        });
+        it("fetches open orders", async () => {
+            const orders = await adapter.getOpenOrders();
+            expect(Array.isArray(orders)).toBe(true);
+        });
+    });
+    // Trading tests intentionally omitted for Lighter (mainnet = real money)
+    // Use the CLI manually for trade testing: perp trade limit BTC buy 10000 0.001 --exchange lighter
+});

package/dist/__tests__/integration/new-commands-e2e.integration.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * E2E integration tests for new atomic commands and api-spec.
+ * These tests spawn the actual CLI process and verify JSON output.
+ *
+ * - api-spec: no adapter needed, always works
+ * - market mid: needs HL mainnet (read-only, no key needed for public data)
+ * - error envelopes: verify structured errors across commands
+ */
+import "dotenv/config";