perp-cli 0.3.3

package/dist/index.js

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+import { config } from "dotenv";
+import { resolve } from "path";
+// Load ~/.perp/.env first (global), then CWD .env (overrides)
+config({ path: resolve(process.env.HOME || "~", ".perp", ".env") });
+config();
+import { Command } from "commander";
+import chalk from "chalk";
+import { loadPrivateKey, parseSolanaKeypair } from "./config.js";
+import { PacificaAdapter } from "./exchanges/pacifica.js";
+import { HyperliquidAdapter } from "./exchanges/hyperliquid.js";
+import { registerMarketCommands } from "./commands/market.js";
+import { registerAccountCommands } from "./commands/account.js";
+import { registerTradeCommands } from "./commands/trade.js";
+import { registerManageCommands } from "./commands/manage.js";
+import { registerStreamCommands } from "./commands/stream.js";
+import { registerArbCommands } from "./commands/arb.js";
+import { registerWalletCommands } from "./commands/wallet.js";
+import { registerBridgeCommands } from "./commands/bridge.js";
+import { registerDepositCommands } from "./commands/deposit.js";
+import { registerAlertCommands } from "./commands/alert.js";
+import { registerArbAutoCommands } from "./commands/arb-auto.js";
+import { registerArbManageCommands } from "./commands/arb-manage.js";
+import { registerGapCommands } from "./commands/gap.js";
+import { registerAgentCommands } from "./commands/agent.js";
+import { registerWithdrawCommands } from "./commands/withdraw.js";
+import { registerRebalanceCommands } from "./commands/rebalance.js";
+import { registerBotCommands } from "./commands/bot.js";
+import { registerHealthCommands } from "./commands/health.js";
+import { registerPortfolioCommands } from "./commands/portfolio.js";
+import { registerRiskCommands } from "./commands/risk.js";
+import { registerHistoryCommands } from "./commands/history.js";
+import { registerAnalyticsCommands } from "./commands/analytics.js";
+import { registerSettingsCommands } from "./commands/settings.js";
+import { registerDexCommands } from "./commands/dex.js";
+import { registerPlanCommands } from "./commands/plan.js";
+import { registerFundingCommands } from "./commands/funding.js";
+import { registerBacktestCommands } from "./commands/backtest.js";
+import { registerDashboardCommands } from "./commands/dashboard.js";
+import { registerInitCommand, EXCHANGE_ENV_MAP, validateKey } from "./commands/init.js";
+import { registerEnvCommands } from "./commands/env.js";
+import { loadSettings, saveSettings } from "./settings.js";
+import { setSharedApiNetwork } from "./shared-api.js";
+const program = new Command();
+// Resolve default exchange from settings (fallback: "pacifica")
+const _settings = loadSettings();
+const _defaultExchange = _settings.defaultExchange || "pacifica";
+program
+    .name("perp")
+    .description("Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter)")
+    .version("0.3.3")
+    .option("-e, --exchange <exchange>", `Exchange: pacifica, hyperliquid, lighter (default: ${_defaultExchange})`, _defaultExchange)
+    .option("-n, --network <network>", "Network: mainnet or testnet", "mainnet")
+    .option("-k, --private-key <key>", "Private key")
+    .option("--json", "Output raw JSON (for piping)")
+    .option("--dry-run", "Simulate trades without executing (log as simulated)")
+    .option("--dex <name>", "HIP-3 deployed perp dex name (Hyperliquid only)")
+    .configureOutput({
+    writeErr: (str) => {
+        if (process.argv.includes("--json")) {
+            const msg = str.replace(/^error:\s*/i, "").trim();
+            // Use inline envelope (jsonError import not available in sync context)
+            console.log(JSON.stringify({
+                ok: false,
+                error: { code: "CLI_ERROR", message: msg },
+                meta: { timestamp: new Date().toISOString() },
+            }));
+        }
+        else {
+            process.stderr.write(str);
+        }
+    },
+});
+let _adapter = null;
+let _pacificaAdapter = null;
+let _hlAdapter = null;
+let _lighterAdapter = null;
+function getExchange() {
+    return program.opts().exchange;
+}
+async function getAdapter() {
+    if (_adapter)
+        return _adapter;
+    const opts = program.opts();
+    const exchange = opts.exchange;
+    const network = opts.network;
+    const isTestnet = network === "testnet";
+    switch (exchange) {
+        case "pacifica": {
+            const pk = await loadPrivateKey("pacifica", opts.privateKey);
+            const keypair = parseSolanaKeypair(pk);
+            const pacNetwork = (isTestnet ? "testnet" : "mainnet");
+            const settings = loadSettings();
+            const builderCode = process.env.PACIFICA_BUILDER_CODE || settings.referralCodes.pacifica || "PERPCLI";
+            _pacificaAdapter = new PacificaAdapter(keypair, pacNetwork, builderCode);
+            _adapter = _pacificaAdapter;
+            break;
+        }
+        case "hyperliquid": {
+            const pk = await loadPrivateKey("hyperliquid", opts.privateKey);
+            _hlAdapter = new HyperliquidAdapter(pk, isTestnet);
+            if (opts.dex)
+                _hlAdapter.setDex(opts.dex);
+            await _hlAdapter.init();
+            const hlSettings = loadSettings();
+            if (hlSettings.referrals && !hlSettings.referralApplied.hyperliquid) {
+                const hlRef = process.env.HL_REFERRAL_CODE || hlSettings.referralCodes.hyperliquid;
+                if (hlRef) {
+                    _hlAdapter.autoSetReferrer(hlRef).then(() => {
+                        const s = loadSettings();
+                        s.referralApplied.hyperliquid = true;
+                        saveSettings(s);
+                    }).catch(() => {
+                        // Already referred or API error — mark as done either way
+                        const s = loadSettings();
+                        s.referralApplied.hyperliquid = true;
+                        saveSettings(s);
+                    });
+                }
+            }
+            _adapter = _hlAdapter;
+            break;
+        }
+        case "lighter": {
+            const pk = await loadPrivateKey("lighter", opts.privateKey);
+            const { LighterAdapter } = await import("./exchanges/lighter.js");
+            _lighterAdapter = new LighterAdapter(pk, isTestnet);
+            await _lighterAdapter.init();
+            const ltSettings = loadSettings();
+            if (ltSettings.referrals && !ltSettings.referralApplied.lighter) {
+                const ltRef = process.env.LIGHTER_REFERRAL_CODE || ltSettings.referralCodes.lighter;
+                if (ltRef) {
+                    _lighterAdapter.useReferralCode(ltRef).then(() => {
+                        const s = loadSettings();
+                        s.referralApplied.lighter = true;
+                        saveSettings(s);
+                    }).catch(() => {
+                        // Already referred or API error — mark as done either way
+                        const s = loadSettings();
+                        s.referralApplied.lighter = true;
+                        saveSettings(s);
+                    });
+                }
+            }
+            _adapter = _lighterAdapter;
+            break;
+        }
+        default:
+            throw new Error(`Unknown exchange: ${exchange}`);
+    }
+    return _adapter;
+}
+// Sync wrapper for commands that need adapter (lazy init)
+function getAdapterSync() {
+    if (!_adapter)
+        throw new Error("Adapter not initialized");
+    return _adapter;
+}
+function isJson() {
+    return !!program.opts().json;
+}
+function isDryRun() {
+    return !!program.opts().dryRun;
+}
+// Helper to get PacificaAdapter specifically (for Pacifica-only commands)
+function getPacificaAdapter() {
+    if (!_pacificaAdapter)
+        throw new Error("This command requires --exchange pacifica");
+    return _pacificaAdapter;
+}
+function getHLAdapter() {
+    if (!_hlAdapter)
+        throw new Error("This command requires --exchange hyperliquid");
+    return _hlAdapter;
+}
+// Register command groups with async adapter getter
+registerMarketCommands(program, getAdapter, isJson);
+registerAccountCommands(program, getAdapter, isJson);
+registerTradeCommands(program, getAdapter, isJson, isDryRun);
+registerManageCommands(program, getAdapter, isJson, getPacificaAdapter);
+registerStreamCommands(program, () => program.opts().network, getExchange, getAdapter);
+registerArbCommands(program, isJson);
+registerWalletCommands(program, isJson);
+registerBridgeCommands(program, isJson);
+registerDepositCommands(program, getAdapter, isJson, () => program.opts().network);
+registerAlertCommands(program, isJson, getAdapterForExchange);
+// Helper to get adapter for a specific exchange (used by arb-auto)
+async function getAdapterForExchange(exchange) {
+    const opts = program.opts();
+    const network = opts.network;
+    const isTestnet = network === "testnet";
+    switch (exchange) {
+        case "pacifica": {
+            if (_pacificaAdapter)
+                return _pacificaAdapter;
+            const pk = await loadPrivateKey("pacifica", opts.privateKey);
+            const keypair = parseSolanaKeypair(pk);
+            const pacNetwork = (isTestnet ? "testnet" : "mainnet");
+            const s1 = loadSettings();
+            const builderCode = process.env.PACIFICA_BUILDER_CODE || s1.referralCodes.pacifica || "PERPCLI";
+            _pacificaAdapter = new PacificaAdapter(keypair, pacNetwork, builderCode);
+            if (!_adapter)
+                _adapter = _pacificaAdapter;
+            return _pacificaAdapter;
+        }
+        case "hyperliquid": {
+            if (_hlAdapter)
+                return _hlAdapter;
+            const pk = await loadPrivateKey("hyperliquid", opts.privateKey);
+            _hlAdapter = new HyperliquidAdapter(pk, isTestnet);
+            if (opts.dex)
+                _hlAdapter.setDex(opts.dex);
+            await _hlAdapter.init();
+            const s2 = loadSettings();
+            if (s2.referrals && !s2.referralApplied.hyperliquid) {
+                const hlRef = process.env.HL_REFERRAL_CODE || s2.referralCodes.hyperliquid;
+                if (hlRef) {
+                    _hlAdapter.autoSetReferrer(hlRef).then(() => {
+                        const s = loadSettings();
+                        s.referralApplied.hyperliquid = true;
+                        saveSettings(s);
+                    }).catch(() => {
+                        const s = loadSettings();
+                        s.referralApplied.hyperliquid = true;
+                        saveSettings(s);
+                    });
+                }
+            }
+            if (!_adapter)
+                _adapter = _hlAdapter;
+            return _hlAdapter;
+        }
+        case "lighter": {
+            if (_lighterAdapter)
+                return _lighterAdapter;
+            const pk = await loadPrivateKey("lighter", opts.privateKey);
+            const { LighterAdapter } = await import("./exchanges/lighter.js");
+            _lighterAdapter = new LighterAdapter(pk, isTestnet);
+            await _lighterAdapter.init();
+            const s3 = loadSettings();
+            if (s3.referrals && !s3.referralApplied.lighter) {
+                const ltRef = process.env.LIGHTER_REFERRAL_CODE || s3.referralCodes.lighter;
+                if (ltRef) {
+                    _lighterAdapter.useReferralCode(ltRef).then(() => {
+                        const s = loadSettings();
+                        s.referralApplied.lighter = true;
+                        saveSettings(s);
+                    }).catch(() => {
+                        const s = loadSettings();
+                        s.referralApplied.lighter = true;
+                        saveSettings(s);
+                    });
+                }
+            }
+            if (!_adapter)
+                _adapter = _lighterAdapter;
+            return _lighterAdapter;
+        }
+        default:
+            throw new Error(`Unknown exchange: ${exchange}`);
+    }
+}
+// Helper to get an HL adapter configured for a specific HIP-3 dex
+const _dexAdapters = new Map();
+async function getHLAdapterForDex(dex) {
+    if (_dexAdapters.has(dex))
+        return _dexAdapters.get(dex);
+    const opts = program.opts();
+    const pk = await loadPrivateKey("hyperliquid", opts.privateKey);
+    const adapter = new HyperliquidAdapter(pk, opts.network === "testnet");
+    if (dex !== "hl")
+        adapter.setDex(dex);
+    await adapter.init();
+    _dexAdapters.set(dex, adapter);
+    return adapter;
+}
+registerArbAutoCommands(program, getAdapterForExchange, isJson, getHLAdapterForDex);
+registerArbManageCommands(program, getAdapterForExchange, isJson);
+registerGapCommands(program, isJson);
+registerAgentCommands(program, getAdapter, isJson);
+registerWithdrawCommands(program, getAdapter, isJson);
+registerRebalanceCommands(program, getAdapterForExchange, isJson);
+// Jobs & strategies
+import { registerJobsCommands } from "./commands/jobs.js";
+import { registerRunCommands } from "./commands/run.js";
+registerJobsCommands(program, isJson);
+registerRunCommands(program, getAdapter, getAdapterForExchange, isJson);
+registerBotCommands(program, getAdapter, getAdapterForExchange, isJson);
+// Agent-friendly commands
+registerHealthCommands(program, isJson);
+registerPortfolioCommands(program, getAdapterForExchange, isJson);
+registerRiskCommands(program, getAdapterForExchange, isJson);
+registerHistoryCommands(program, isJson);
+registerAnalyticsCommands(program, getAdapterForExchange, isJson);
+registerSettingsCommands(program, isJson);
+registerDexCommands(program, getAdapter, isJson);
+registerPlanCommands(program, getAdapter, isJson);
+registerFundingCommands(program, isJson);
+registerBacktestCommands(program, isJson);
+registerDashboardCommands(program, getAdapterForExchange, isJson, getHLAdapterForDex);
+registerInitCommand(program);
+registerEnvCommands(program, isJson);
+// Agent discovery: perp api-spec — returns full CLI spec as JSON
+program
+    .command("api-spec")
+    .description("Return full CLI command spec as JSON (for agent discovery)")
+    .action(async () => {
+    const { jsonOk, printJson } = await import("./utils.js");
+    const { getCliSpec } = await import("./cli-spec.js");
+    printJson(jsonOk(getCliSpec(program)));
+});
+// Status command
+program
+    .command("status")
+    .description("Quick overview: account + positions + open orders")
+    .action(async () => {
+    const adapter = await getAdapter();
+    const json = isJson();
+    try {
+        const [balance, positions, orders] = await Promise.all([
+            adapter.getBalance(),
+            adapter.getPositions(),
+            adapter.getOpenOrders(),
+        ]);
+        if (json) {
+            const { jsonOk, printJson } = await import("./utils.js");
+            return printJson(jsonOk({ exchange: adapter.name, balance, positions, orders }));
+        }
+        console.log(chalk.cyan.bold(`\n  ${adapter.name.toUpperCase()} Account Status\n`));
+        console.log(`  Equity:      $${Number(balance.equity).toFixed(2)}`);
+        console.log(`  Available:   $${Number(balance.available).toFixed(2)}`);
+        console.log(`  Margin Used: $${Number(balance.marginUsed).toFixed(2)}`);
+        console.log(`  Positions:   ${positions.length}`);
+        console.log(`  Open Orders: ${orders.length}`);
+        if (positions.length > 0) {
+            console.log(chalk.cyan.bold("\n  Positions:"));
+            positions.forEach((p) => {
+                const color = p.side === "long" ? chalk.green : chalk.red;
+                const pnlNum = Number(p.unrealizedPnl);
+                const pnlColor = pnlNum >= 0 ? chalk.green : chalk.red;
+                console.log(`    ${color(p.side.toUpperCase().padEnd(5))} ${chalk.white(p.symbol.padEnd(12))} ${p.size.padEnd(10)} entry: $${Number(p.entryPrice).toFixed(2)}  pnl: ${pnlColor(pnlNum >= 0 ? "+" : "")}$${pnlNum.toFixed(2)}`);
+            });
+        }
+        if (orders.length > 0) {
+            console.log(chalk.cyan.bold("\n  Open Orders:"));
+            orders.forEach((o) => {
+                const color = o.side === "buy" ? chalk.green : chalk.red;
+                console.log(`    ${color(o.side.toUpperCase().padEnd(4))} ${chalk.white(o.symbol.padEnd(12))} ${o.type.padEnd(8)} $${Number(o.price).toFixed(2)} x ${o.size}`);
+            });
+        }
+        console.log();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (isJson()) {
+            const { jsonError } = await import("./utils.js");
+            console.log(JSON.stringify(jsonError("COMMAND_ERROR", msg)));
+        }
+        else {
+            console.error(chalk.red(`Error: ${msg}`));
+        }
+        process.exit(1);
+    }
+});
+// Switch shared API URLs if --network testnet is used
+program.hook("preAction", () => {
+    const network = program.opts().network;
+    if (network === "testnet")
+        setSharedApiNetwork("testnet");
+});
+// Smart landing page: `perp` with no subcommand
+const rawArgs = process.argv.slice(2);
+const hasSubcommand = rawArgs.some((a) => !a.startsWith("-") && !["pacifica", "hyperliquid", "lighter", "mainnet", "testnet"].includes(a));
+if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawArgs.includes("--help") && !rawArgs.includes("-V") && !rawArgs.includes("--version"))) {
+    // No subcommand — show smart landing instead of help dump
+    (async () => {
+        try {
+            const { getWalletSetupStatus } = await import("./commands/wallet.js");
+            const status = getWalletSetupStatus();
+            const settings = loadSettings();
+            const hasEnvKey = !!(process.env.PRIVATE_KEY || process.env.PACIFICA_PRIVATE_KEY ||
+                process.env.HL_PRIVATE_KEY || process.env.HYPERLIQUID_PRIVATE_KEY ||
+                process.env.LIGHTER_PRIVATE_KEY);
+            if (!status.hasWallets && !hasEnvKey && !settings.defaultExchange) {
+                // Fresh install — onboarding
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.3\n"));
+                console.log("  Multi-DEX perpetual futures CLI for Pacifica, Hyperliquid, and Lighter.\n");
+                console.log(`  Get started:  ${chalk.cyan("perp init")}`);
+                console.log(chalk.gray(`\n  Or explore without a wallet:`));
+                console.log(`    ${chalk.green("perp market list")}              available markets`);
+                console.log(`    ${chalk.green("perp -e hyperliquid market list")}  Hyperliquid markets`);
+                console.log(`    ${chalk.green("perp arb rates")}                funding rate comparison`);
+                console.log(`    ${chalk.green("perp --help")}                   all commands\n`);
+            }
+            else {
+                // Configured — show status overview
+                const defaultEx = settings.defaultExchange || "pacifica";
+                const activeEntries = Object.entries(status.active);
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.3\n"));
+                console.log(`  Default exchange: ${chalk.cyan(defaultEx)}`);
+                if (activeEntries.length > 0) {
+                    console.log(chalk.white.bold("\n  Wallets:"));
+                    for (const [exchange, walletName] of activeEntries) {
+                        const w = status.wallets[walletName];
+                        if (w) {
+                            const addr = w.address.length > 20
+                                ? w.address.slice(0, 6) + "..." + w.address.slice(-4)
+                                : w.address;
+                            console.log(`    ${chalk.cyan(exchange.padEnd(14))} ${chalk.white(walletName)} ${chalk.gray(addr)}`);
+                        }
+                    }
+                }
+                else if (hasEnvKey) {
+                    console.log(chalk.white.bold("\n  Configured:"));
+                    for (const [exchange, info] of Object.entries(EXCHANGE_ENV_MAP)) {
+                        const key = process.env[info.envKey];
+                        if (key) {
+                            try {
+                                const { valid, address } = await validateKey(info.chain, key);
+                                const addr = valid ? address : "(invalid key)";
+                                console.log(`    ${chalk.cyan(exchange.padEnd(14))} ${chalk.green(addr)}`);
+                            }
+                            catch {
+                                console.log(`    ${chalk.cyan(exchange.padEnd(14))} ${chalk.gray("(error reading key)")}`);
+                            }
+                        }
+                    }
+                }
+                console.log(chalk.white.bold("\n  Quick commands:"));
+                console.log(`    ${chalk.green("perp status")}       account overview`);
+                console.log(`    ${chalk.green("perp market list")}   available markets`);
+                console.log(`    ${chalk.green("perp dashboard")}     live monitoring`);
+                console.log(`    ${chalk.green("perp arb rates")}     funding rate comparison`);
+                console.log(`    ${chalk.green("perp --help")}        all commands\n`);
+            }
+        }
+        catch {
+            program.help();
+        }
+    })();
+}
+else {
+    program.parseAsync().then(() => {
+        // Allow a short delay for any pending output, then exit cleanly.
+        // Without this, HL SDK's WebSocket keeps the process alive indefinitely.
+        setTimeout(() => process.exit(0), 500);
+    }).catch(async (err) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (isJson()) {
+            const { jsonError } = await import("./utils.js");
+            console.log(JSON.stringify(jsonError("FATAL", msg)));
+        }
+        else {
+            console.error(chalk.red(msg));
+        }
+        process.exit(1);
+    });
+}

package/dist/jobs.d.ts

@@ -0,0 +1,37 @@
+export interface JobEntry {
+    id: string;
+    strategy: string;
+    exchange: string;
+    params: Record<string, unknown>;
+    tmuxSession: string;
+    pid?: number;
+    startedAt: string;
+    status: "running" | "stopped" | "done" | "error";
+    result?: Record<string, unknown>;
+}
+export declare function logFile(id: string): string;
+export declare function saveJob(job: JobEntry): void;
+export declare function loadJob(id: string): JobEntry | null;
+export declare function listJobs(): JobEntry[];
+/**
+ * Start a job in a tmux background session.
+ * Returns the job entry.
+ */
+export declare function startJob(opts: {
+    strategy: string;
+    exchange: string;
+    params: Record<string, unknown>;
+    cliArgs: string[];
+}): JobEntry;
+/**
+ * Stop a running job.
+ */
+export declare function stopJob(id: string): boolean;
+/**
+ * Update job state file (called from within the running job).
+ */
+export declare function updateJobState(id: string, data: Partial<JobEntry>): void;
+/**
+ * Remove a job entry.
+ */
+export declare function removeJob(id: string): boolean;

package/dist/jobs.js

@@ -0,0 +1,152 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+const JOBS_DIR = join(homedir(), ".perp", "jobs");
+const LOGS_DIR = join(homedir(), ".perp", "logs");
+function ensureDirs() {
+    mkdirSync(JOBS_DIR, { recursive: true });
+    mkdirSync(LOGS_DIR, { recursive: true });
+}
+function jobFile(id) {
+    return join(JOBS_DIR, `${id}.json`);
+}
+export function logFile(id) {
+    return join(LOGS_DIR, `${id}.log`);
+}
+function genId() {
+    return randomBytes(4).toString("hex");
+}
+function hasTmux() {
+    try {
+        execSync("which tmux", { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function tmuxSessionExists(name) {
+    try {
+        execSync(`tmux has-session -t ${name} 2>/dev/null`, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function saveJob(job) {
+    ensureDirs();
+    writeFileSync(jobFile(job.id), JSON.stringify(job, null, 2));
+}
+export function loadJob(id) {
+    const path = jobFile(id);
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(readFileSync(path, "utf-8"));
+}
+export function listJobs() {
+    ensureDirs();
+    const files = readdirSync(JOBS_DIR).filter((f) => f.endsWith(".json"));
+    return files.map((f) => {
+        const job = JSON.parse(readFileSync(join(JOBS_DIR, f), "utf-8"));
+        // Check if tmux session is still alive
+        if (job.status === "running" && !tmuxSessionExists(job.tmuxSession)) {
+            job.status = "done";
+            saveJob(job);
+        }
+        return job;
+    });
+}
+import { readdirSync } from "node:fs";
+/**
+ * Start a job in a tmux background session.
+ * Returns the job entry.
+ */
+export function startJob(opts) {
+    if (!hasTmux()) {
+        throw new Error("tmux is required for background jobs. Install with: brew install tmux");
+    }
+    ensureDirs();
+    const id = genId();
+    const session = `perp-${id}`;
+    const log = logFile(id);
+    // Build the command — re-invoke ourselves with `run` subcommand
+    const nodeCmd = process.argv[0];
+    const cliPath = process.argv[1];
+    const envVars = buildEnvString();
+    const args = opts.cliArgs.join(" ");
+    const cmd = `${envVars} ${nodeCmd} ${cliPath} run ${opts.strategy} ${args} --job-id ${id} 2>&1 | tee -a ${log}`;
+    // Create tmux session
+    execSync(`tmux new-session -d -s ${session} '${cmd.replace(/'/g, "'\\''")}'`);
+    const job = {
+        id,
+        strategy: opts.strategy,
+        exchange: opts.exchange,
+        params: opts.params,
+        tmuxSession: session,
+        startedAt: new Date().toISOString(),
+        status: "running",
+    };
+    saveJob(job);
+    return job;
+}
+/**
+ * Stop a running job.
+ */
+export function stopJob(id) {
+    const job = loadJob(id);
+    if (!job)
+        return false;
+    if (tmuxSessionExists(job.tmuxSession)) {
+        try {
+            execSync(`tmux kill-session -t ${job.tmuxSession}`);
+        }
+        catch { /* already dead */ }
+    }
+    job.status = "stopped";
+    saveJob(job);
+    return true;
+}
+/**
+ * Update job state file (called from within the running job).
+ */
+export function updateJobState(id, data) {
+    const job = loadJob(id);
+    if (!job)
+        return;
+    Object.assign(job, data);
+    saveJob(job);
+}
+/**
+ * Remove a job entry.
+ */
+export function removeJob(id) {
+    const path = jobFile(id);
+    if (!existsSync(path))
+        return false;
+    unlinkSync(path);
+    // Also remove log
+    const log = logFile(id);
+    if (existsSync(log))
+        unlinkSync(log);
+    return true;
+}
+/**
+ * Build env string to pass through to tmux session.
+ */
+function buildEnvString() {
+    const keys = [
+        "LIGHTER_PRIVATE_KEY", "LIGHTER_API_KEY", "LIGHTER_ACCOUNT_INDEX", "LIGHTER_API_KEY_INDEX",
+        "PRIVATE_KEY", "pk",
+        "PACIFICA_BUILDER_CODE", "NEXT_PUBLIC_BUILDER_CODE",
+        "HL_REFERRAL_CODE", "LIGHTER_REFERRAL_CODE",
+    ];
+    const parts = [];
+    for (const k of keys) {
+        if (process.env[k])
+            parts.push(`${k}='${process.env[k]}'`);
+    }
+    return parts.join(" ");
+}

package/dist/liquidity.d.ts

@@ -0,0 +1,34 @@
+import type { ExchangeAdapter } from "./exchanges/interface.js";
+export interface LiquidityCheck {
+    /** Max executable size (base) within slippage tolerance */
+    maxSize: number;
+    /** Estimated avg fill price for the given size */
+    avgFillPrice: number;
+    /** Estimated slippage % vs mid price */
+    slippagePct: number;
+    /** Total depth in USD on the relevant side */
+    depthUsd: number;
+    /** Whether the full requested size can be filled */
+    canFillFull: boolean;
+    /** Recommended size (capped by liquidity) */
+    recommendedSize: number;
+}
+/**
+ * Walk through orderbook levels and compute how much can be filled
+ * within the given slippage tolerance.
+ *
+ * @param levels - [[price, size], ...] from getOrderbook (asks for buy, bids for sell)
+ * @param maxSlippagePct - max acceptable slippage from best price (default 0.5%)
+ * @param requestedSizeUsd - desired position size in USD
+ */
+export declare function computeExecutableSize(levels: [string, string][], requestedSizeUsd: number, maxSlippagePct?: number): LiquidityCheck;
+/**
+ * Check liquidity on both sides for an arb entry.
+ * Returns adjusted size or 0 if not viable.
+ */
+export declare function checkArbLiquidity(longAdapter: ExchangeAdapter, shortAdapter: ExchangeAdapter, symbol: string, sizeUsd: number, maxSlippagePct?: number, log?: (msg: string) => void): Promise<{
+    viable: boolean;
+    adjustedSizeUsd: number;
+    longSlippage: number;
+    shortSlippage: number;
+}>;