perp-cli 0.3.3

package/dist/__tests__/integration/agent-features.integration.test.js

@@ -0,0 +1,553 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { HyperliquidAdapter } from "../../exchanges/hyperliquid.js";
+import { validateTrade } from "../../trade-validator.js";
+import { startEventStream } from "../../event-stream.js";
+import { classifyError, ERROR_CODES } from "../../errors.js";
+import { validatePlan } from "../../plan-executor.js";
+/**
+ * Integration tests for agent-friendly features against REAL Hyperliquid mainnet API.
+ *
+ * These tests are READ-ONLY — no orders are placed, no private key is needed for
+ * most operations. We use a dummy private key to satisfy the adapter constructor
+ * and derive a deterministic (empty) address for account queries.
+ *
+ * Run:
+ *   pnpm --filter perp-cli test -- --testPathPattern integration/agent-features
+ */
+// Dummy private key — valid 32-byte hex, derives a real (but empty) address.
+// No funds, no positions — that is expected and part of the test.
+const DUMMY_PRIVATE_KEY = "0x" + "1".repeat(64);
+/** Helper: find market by base symbol (handles BTC vs BTC-PERP) */
+function findMarket(markets, base) {
+    return markets.find(m => m.symbol === base || m.symbol === `${base}-PERP` || m.symbol.replace(/-PERP$/, "") === base);
+}
+describe("Agent Features Integration (Hyperliquid Mainnet)", () => {
+    let adapter;
+    beforeAll(async () => {
+        adapter = new HyperliquidAdapter(DUMMY_PRIVATE_KEY, false);
+        await adapter.init();
+    }, 30_000);
+    // ─────────────────────────────────────────────────────────────────
+    //  1. trade-validator with real market data
+    // ─────────────────────────────────────────────────────────────────
+    describe("trade-validator with real market data", () => {
+        it("validates a BTC market buy and returns correct structure", async () => {
+            const result = await validateTrade(adapter, {
+                symbol: "BTC",
+                side: "buy",
+                size: 0.001,
+                type: "market",
+            });
+            // Structure checks
+            expect(result).toHaveProperty("valid");
+            expect(typeof result.valid).toBe("boolean");
+            expect(Array.isArray(result.checks)).toBe(true);
+            expect(result.checks.length).toBeGreaterThan(0);
+            expect(result).toHaveProperty("timestamp");
+            expect(new Date(result.timestamp).getTime()).toBeGreaterThan(0);
+            // Symbol check must pass — BTC exists on Hyperliquid
+            const symbolCheck = result.checks.find(c => c.check === "symbol_valid");
+            expect(symbolCheck).toBeTruthy();
+            expect(symbolCheck.passed).toBe(true);
+            expect(symbolCheck.message).toContain("BTC");
+            // Market info must have a real mark price
+            expect(result.marketInfo).toBeTruthy();
+            expect(result.marketInfo.symbol).toBe("BTC");
+            expect(result.marketInfo.markPrice).toBeGreaterThan(0);
+            expect(result.marketInfo.maxLeverage).toBeGreaterThan(0);
+            // Estimated cost should exist
+            expect(result.estimatedCost).toBeTruthy();
+            expect(result.estimatedCost.margin).toBeGreaterThan(0);
+            expect(result.estimatedCost.fee).toBeGreaterThan(0);
+        }, 30_000);
+        it("validates ETH and SOL symbols as valid", async () => {
+            const [ethResult, solResult] = await Promise.all([
+                validateTrade(adapter, { symbol: "ETH", side: "sell", size: 0.01, type: "market" }),
+                validateTrade(adapter, { symbol: "SOL", side: "buy", size: 0.1, type: "market" }),
+            ]);
+            const ethSymbol = ethResult.checks.find(c => c.check === "symbol_valid");
+            expect(ethSymbol?.passed).toBe(true);
+            expect(ethResult.marketInfo?.markPrice).toBeGreaterThan(0);
+            const solSymbol = solResult.checks.find(c => c.check === "symbol_valid");
+            expect(solSymbol?.passed).toBe(true);
+            expect(solResult.marketInfo?.markPrice).toBeGreaterThan(0);
+        }, 30_000);
+        it("rejects a non-existent symbol", async () => {
+            const result = await validateTrade(adapter, {
+                symbol: "XYZNOTREAL999",
+                side: "buy",
+                size: 1,
+                type: "market",
+            });
+            expect(result.valid).toBe(false);
+            const symbolCheck = result.checks.find(c => c.check === "symbol_valid");
+            expect(symbolCheck).toBeTruthy();
+            expect(symbolCheck.passed).toBe(false);
+            expect(symbolCheck.message).toContain("XYZNOTREAL999");
+            // Early return means no market info
+            expect(result.marketInfo).toBeUndefined();
+        }, 30_000);
+        it("balance check fails for empty account (dummy key)", async () => {
+            const result = await validateTrade(adapter, {
+                symbol: "BTC",
+                side: "buy",
+                size: 0.001,
+                type: "market",
+            });
+            // With a dummy key the account has $0 balance, so balance check should fail
+            // (unless the trade is tiny enough that margin rounds to 0)
+            const balanceCheck = result.checks.find(c => c.check === "balance_sufficient");
+            expect(balanceCheck).toBeTruthy();
+            // The check should fail because 0 available < margin required for BTC
+            expect(balanceCheck.passed).toBe(false);
+            expect(balanceCheck.message).toContain("Insufficient");
+        }, 30_000);
+        it("liquidity check runs for market orders", async () => {
+            const result = await validateTrade(adapter, {
+                symbol: "BTC",
+                side: "buy",
+                size: 0.001,
+                type: "market",
+            });
+            const liqCheck = result.checks.find(c => c.check === "liquidity_ok");
+            expect(liqCheck).toBeTruthy();
+            // BTC is highly liquid — a 0.001 BTC order should pass liquidity check
+            expect(liqCheck.passed).toBe(true);
+        }, 30_000);
+    });
+    // ─────────────────────────────────────────────────────────────────
+    //  2. event-stream with real data (single poll)
+    // ─────────────────────────────────────────────────────────────────
+    describe("event-stream with real data", () => {
+        it("completes a single poll cycle without crashing", async () => {
+            const events = [];
+            const controller = new AbortController();
+            // Abort immediately after the first poll completes.
+            // startEventStream does an initial poll, then enters the while-loop.
+            // We signal abort so the loop exits after the first iteration.
+            setTimeout(() => controller.abort(), 100);
+            await startEventStream(adapter, {
+                intervalMs: 60_000, // long interval so only the initial poll runs
+                onEvent: (event) => {
+                    events.push(event);
+                },
+                signal: controller.signal,
+            });
+            // With an empty account we expect 0 events (no positions, no orders, no balance changes).
+            // The key assertion: it did NOT throw. Real API data was fetched and processed.
+            expect(Array.isArray(events)).toBe(true);
+            // If any events were emitted, they must have valid structure
+            for (const ev of events) {
+                expect(ev).toHaveProperty("type");
+                expect(ev).toHaveProperty("exchange");
+                expect(ev).toHaveProperty("timestamp");
+                expect(ev).toHaveProperty("data");
+                expect(ev.exchange).toBe("hyperliquid");
+                expect(new Date(ev.timestamp).getTime()).toBeGreaterThan(0);
+            }
+        }, 30_000);
+        it("emits error event on invalid adapter state gracefully", async () => {
+            // Create an adapter that will fail on API calls (testnet URL with mainnet-ish key)
+            // Actually, even a bad address just returns empty data, not errors.
+            // Instead, test that abort signal works correctly.
+            const events = [];
+            const controller = new AbortController();
+            // Abort before even the first poll interval elapses
+            controller.abort();
+            await startEventStream(adapter, {
+                intervalMs: 1000,
+                onEvent: (event) => events.push(event),
+                signal: controller.signal,
+            });
+            // The initial poll should still have run (abort is checked after poll)
+            // No crash = success
+            expect(true).toBe(true);
+        }, 30_000);
+    });
+    // ─────────────────────────────────────────────────────────────────
+    //  3. errors.ts classifyError with real exchange error patterns
+    // ─────────────────────────────────────────────────────────────────
+    describe("classifyError with real exchange error patterns", () => {
+        it("classifies 'Insufficient margin' as MARGIN_INSUFFICIENT", () => {
+            const err = classifyError(new Error("Insufficient margin for this order"), "hyperliquid");
+            expect(err.code).toBe("MARGIN_INSUFFICIENT");
+            expect(err.retryable).toBe(false);
+            expect(err.exchange).toBe("hyperliquid");
+            expect(err.status).toBe(400);
+        });
+        it("classifies 'Asset not found' as SYMBOL_NOT_FOUND", () => {
+            const err = classifyError(new Error("Asset not found: XYZABC"), "hyperliquid");
+            expect(err.code).toBe("SYMBOL_NOT_FOUND");
+            expect(err.retryable).toBe(false);
+            expect(err.status).toBe(404);
+        });
+        it("classifies rate limit response as RATE_LIMITED", () => {
+            const err = classifyError(new Error("429 Too Many Requests - rate limit exceeded"), "hyperliquid");
+            expect(err.code).toBe("RATE_LIMITED");
+            expect(err.retryable).toBe(true);
+            expect(err.retryAfterMs).toBe(1000);
+            expect(err.status).toBe(429);
+        });
+        it("classifies network error as EXCHANGE_UNREACHABLE", () => {
+            const cases = [
+                "fetch failed: ECONNREFUSED",
+                "ENOTFOUND api.hyperliquid.xyz",
+                "Network error: unable to reach server",
+            ];
+            for (const msg of cases) {
+                const err = classifyError(new Error(msg), "hyperliquid");
+                expect(err.code).toBe("EXCHANGE_UNREACHABLE");
+                expect(err.retryable).toBe(true);
+                expect(err.status).toBe(503);
+            }
+        });
+        it("classifies timeout as TIMEOUT", () => {
+            const err = classifyError(new Error("Request timed out after 30000ms"), "hyperliquid");
+            expect(err.code).toBe("TIMEOUT");
+            expect(err.retryable).toBe(true);
+            expect(err.status).toBe(504);
+        });
+        it("classifies unknown Hyperliquid error as EXCHANGE_ERROR", () => {
+            const err = classifyError(new Error("Some unexpected internal error from HL"), "hyperliquid");
+            expect(err.code).toBe("EXCHANGE_ERROR");
+            expect(err.exchange).toBe("hyperliquid");
+            expect(err.retryable).toBe(true);
+        });
+        it("preserves original error message in structured output", () => {
+            const originalMsg = "Margin not enough for cross-mode order on BTC";
+            const err = classifyError(new Error(originalMsg), "hyperliquid");
+            expect(err.message).toBe(originalMsg);
+        });
+        it("handles string inputs (non-Error objects)", () => {
+            const err = classifyError("rate limit hit", "hyperliquid");
+            expect(err.code).toBe("RATE_LIMITED");
+            expect(err.message).toBe("rate limit hit");
+        });
+        it("all ERROR_CODES have consistent structure", () => {
+            for (const [key, val] of Object.entries(ERROR_CODES)) {
+                expect(val.code).toBe(key);
+                expect(typeof val.status).toBe("number");
+                expect(typeof val.retryable).toBe("boolean");
+            }
+        });
+    });
+    // ─────────────────────────────────────────────────────────────────
+    //  4. plan-executor validatePlan with realistic plans
+    // ─────────────────────────────────────────────────────────────────
+    describe("plan-executor validatePlan with realistic plans", () => {
+        it("validates a realistic multi-step BTC long plan", () => {
+            const plan = {
+                version: "1.0",
+                exchange: "hyperliquid",
+                description: "Open leveraged BTC long with stop loss and take profit",
+                steps: [
+                    {
+                        id: "check-balance",
+                        action: "check_balance",
+                        params: { minAvailable: 100 },
+                        onFailure: "abort",
+                    },
+                    {
+                        id: "set-lev",
+                        action: "set_leverage",
+                        params: { symbol: "BTC", leverage: 10 },
+                        dependsOn: "check-balance",
+                        onFailure: "abort",
+                    },
+                    {
+                        id: "open-long",
+                        action: "market_order",
+                        params: { symbol: "BTC", side: "buy", size: "0.001" },
+                        dependsOn: "set-lev",
+                        onFailure: "abort",
+                        clientId: "btc-long-001",
+                    },
+                    {
+                        id: "set-sl",
+                        action: "stop_order",
+                        params: { symbol: "BTC", side: "sell", size: "0.001", triggerPrice: "90000" },
+                        dependsOn: "open-long",
+                        onFailure: "skip",
+                    },
+                    {
+                        id: "verify-position",
+                        action: "check_position",
+                        params: { symbol: "BTC", mustExist: true },
+                        dependsOn: "open-long",
+                        onFailure: "skip",
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it("validates a multi-asset hedging plan", () => {
+            const plan = {
+                version: "1.0",
+                exchange: "hyperliquid",
+                description: "Hedge BTC long with ETH and SOL shorts",
+                steps: [
+                    {
+                        id: "long-btc",
+                        action: "market_order",
+                        params: { symbol: "BTC", side: "buy", size: "0.01" },
+                        onFailure: "abort",
+                    },
+                    {
+                        id: "short-eth",
+                        action: "market_order",
+                        params: { symbol: "ETH", side: "sell", size: "0.1" },
+                        dependsOn: "long-btc",
+                        onFailure: "skip",
+                    },
+                    {
+                        id: "short-sol",
+                        action: "market_order",
+                        params: { symbol: "SOL", side: "sell", size: "1" },
+                        dependsOn: "long-btc",
+                        onFailure: "skip",
+                    },
+                    {
+                        id: "wait-settle",
+                        action: "wait",
+                        params: { ms: 2000 },
+                        dependsOn: "long-btc",
+                    },
+                    {
+                        id: "check-btc-pos",
+                        action: "check_position",
+                        params: { symbol: "BTC", mustExist: true },
+                        dependsOn: "wait-settle",
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it("validates a close-all-and-cancel plan", () => {
+            const plan = {
+                version: "1.0",
+                description: "Emergency: cancel all orders and close BTC position",
+                steps: [
+                    {
+                        id: "cancel-all",
+                        action: "cancel_all",
+                        params: {},
+                        onFailure: "skip",
+                    },
+                    {
+                        id: "close-btc",
+                        action: "close_position",
+                        params: { symbol: "BTC" },
+                        dependsOn: "cancel-all",
+                        onFailure: "rollback",
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(true);
+            expect(result.errors).toHaveLength(0);
+        });
+        it("rejects plan with missing required params", () => {
+            const plan = {
+                version: "1.0",
+                steps: [
+                    {
+                        id: "bad-order",
+                        action: "market_order",
+                        params: { symbol: "BTC" }, // missing side and size
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+            expect(result.errors.some(e => e.includes("side"))).toBe(true);
+            expect(result.errors.some(e => e.includes("size"))).toBe(true);
+        });
+        it("rejects plan with invalid action", () => {
+            const plan = {
+                version: "1.0",
+                steps: [
+                    {
+                        id: "bad-action",
+                        action: "nuke_everything",
+                        params: {},
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("invalid action"))).toBe(true);
+        });
+        it("rejects plan with duplicate step IDs", () => {
+            const plan = {
+                version: "1.0",
+                steps: [
+                    { id: "step-1", action: "check_balance", params: {} },
+                    { id: "step-1", action: "check_balance", params: {} },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("duplicate"))).toBe(true);
+        });
+        it("rejects plan with non-existent dependsOn reference", () => {
+            const plan = {
+                version: "1.0",
+                steps: [
+                    {
+                        id: "step-1",
+                        action: "market_order",
+                        params: { symbol: "BTC", side: "buy", size: "0.001" },
+                        dependsOn: "phantom-step",
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("phantom-step"))).toBe(true);
+        });
+        it("rejects plan with wrong version", () => {
+            const plan = {
+                version: "2.0",
+                steps: [{ id: "s1", action: "check_balance", params: {} }],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("version"))).toBe(true);
+        });
+        it("validates a limit order plan with price param", () => {
+            const plan = {
+                version: "1.0",
+                steps: [
+                    {
+                        id: "limit-buy",
+                        action: "limit_order",
+                        params: { symbol: "ETH", side: "buy", size: "0.1", price: "1500" },
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(true);
+        });
+        it("rejects limit order without price", () => {
+            const plan = {
+                version: "1.0",
+                steps: [
+                    {
+                        id: "bad-limit",
+                        action: "limit_order",
+                        params: { symbol: "ETH", side: "buy", size: "0.1" },
+                    },
+                ],
+            };
+            const result = validatePlan(plan);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some(e => e.includes("price"))).toBe(true);
+        });
+    });
+    // ─────────────────────────────────────────────────────────────────
+    //  5. Schema generation with real adapter context
+    // ─────────────────────────────────────────────────────────────────
+    describe("schema and adapter capabilities", () => {
+        it("adapter exposes correct name", () => {
+            expect(adapter.name).toBe("hyperliquid");
+        });
+        it("adapter has loaded a non-empty asset map after init", async () => {
+            // HL SDK mainnet uses BTC-PERP style names in asset map
+            const markets = await adapter.getMarkets();
+            expect(markets.length).toBeGreaterThan(50);
+            // Verify we can look up at least one symbol using the exact format from the map
+            const firstSymbol = markets[0].symbol;
+            expect(adapter.getAssetIndex(firstSymbol)).toBeGreaterThanOrEqual(0);
+        }, 30_000);
+        it("adapter getAssetIndex throws for unknown symbol", () => {
+            expect(() => adapter.getAssetIndex("XYZNOTREAL999FAKE")).toThrow("Unknown symbol");
+        });
+        it("adapter getMarkets returns well-formed data from real API", async () => {
+            const markets = await adapter.getMarkets();
+            expect(markets.length).toBeGreaterThan(50); // HL has 100+ perps
+            const btc = findMarket(markets, "BTC");
+            expect(btc).toBeTruthy();
+            expect(Number(btc.markPrice)).toBeGreaterThan(1000);
+            expect(btc.maxLeverage).toBeGreaterThanOrEqual(20);
+            expect(Number(btc.volume24h)).toBeGreaterThan(0);
+            expect(Number(btc.openInterest)).toBeGreaterThan(0);
+            // All markets have required fields
+            for (const m of markets) {
+                expect(m.symbol).toBeTruthy();
+                expect(typeof m.markPrice).toBe("string");
+                expect(typeof m.fundingRate).toBe("string");
+                expect(typeof m.maxLeverage).toBe("number");
+            }
+        }, 30_000);
+        it("adapter getOrderbook returns bids and asks for BTC", async () => {
+            // HL SDK mainnet may need exact symbol (BTC-PERP)
+            const markets = await adapter.getMarkets();
+            const btcSym = findMarket(markets, "BTC").symbol;
+            const book = await adapter.getOrderbook(btcSym);
+            expect(book.bids.length).toBeGreaterThan(0);
+            expect(book.asks.length).toBeGreaterThan(0);
+            // Bids and asks are [price, size] tuples
+            const [bidPrice, bidSize] = book.bids[0];
+            expect(Number(bidPrice)).toBeGreaterThan(0);
+            expect(Number(bidSize)).toBeGreaterThan(0);
+            const [askPrice, askSize] = book.asks[0];
+            expect(Number(askPrice)).toBeGreaterThan(0);
+            expect(Number(askSize)).toBeGreaterThan(0);
+            // Best ask should be >= best bid
+            expect(Number(askPrice)).toBeGreaterThanOrEqual(Number(bidPrice));
+        }, 30_000);
+        it("adapter getBalance returns numeric fields for empty account", async () => {
+            const balance = await adapter.getBalance();
+            expect(balance).toHaveProperty("equity");
+            expect(balance).toHaveProperty("available");
+            expect(balance).toHaveProperty("marginUsed");
+            expect(balance).toHaveProperty("unrealizedPnl");
+            // All should be parseable as numbers
+            expect(Number.isFinite(Number(balance.equity))).toBe(true);
+            expect(Number.isFinite(Number(balance.available))).toBe(true);
+            expect(Number.isFinite(Number(balance.marginUsed))).toBe(true);
+            expect(Number.isFinite(Number(balance.unrealizedPnl))).toBe(true);
+        }, 30_000);
+        it("adapter getPositions returns an array (empty for dummy account)", async () => {
+            const positions = await adapter.getPositions();
+            expect(Array.isArray(positions)).toBe(true);
+            // Dummy account should have no positions
+            expect(positions.length).toBe(0);
+        }, 30_000);
+        it("adapter getOpenOrders returns an array (empty for dummy account)", async () => {
+            const orders = await adapter.getOpenOrders();
+            expect(Array.isArray(orders)).toBe(true);
+            expect(orders.length).toBe(0);
+        }, 30_000);
+        it("ERROR_CODES cover all expected agent error scenarios", () => {
+            const expectedCodes = [
+                "INVALID_PARAMS",
+                "SYMBOL_NOT_FOUND",
+                "ORDER_NOT_FOUND",
+                "POSITION_NOT_FOUND",
+                "INSUFFICIENT_BALANCE",
+                "MARGIN_INSUFFICIENT",
+                "SIZE_TOO_SMALL",
+                "SIZE_TOO_LARGE",
+                "RISK_VIOLATION",
+                "DUPLICATE_ORDER",
+                "EXCHANGE_UNREACHABLE",
+                "RATE_LIMITED",
+                "PRICE_STALE",
+                "SIGNATURE_FAILED",
+                "EXCHANGE_ERROR",
+                "TIMEOUT",
+                "UNKNOWN",
+            ];
+            for (const code of expectedCodes) {
+                expect(ERROR_CODES).toHaveProperty(code);
+                expect(ERROR_CODES[code].code).toBe(code);
+            }
+        });
+    });
+});

package/dist/__tests__/integration/atomic-commands.integration.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Integration tests for new atomic commands against Hyperliquid mainnet (read-only).
+ *
+ * Tests:
+ * - market mid: real orderbook mid price
+ * - account margin: position-not-found for dummy/real account
+ * - trade status: order-not-found for dummy order
+ * - trade fills: empty fills for dummy account / real fills if any
+ * - Error response shapes and classification
+ *
+ * Requires: HYPERLIQUID_PRIVATE_KEY or HL_PRIVATE_KEY env var
+ */
+import "dotenv/config";