@nexstone/rift-cli 0.1.1

package/dist/lib/credentials.js

@@ -0,0 +1,137 @@
+/**
+ * Wallet credential management — canonical snake_case schema, matching
+ * what the Python engine writes via `rift agent-pair` (rift_trade.api_wallet
+ * → rift_core.keys.APIWalletKey, serialized via Pydantic).
+ *
+ * File location: ~/.rift/credentials   (no extension, matches Python)
+ * Format: single-account JSON (snake_case fields).
+ *
+ * The loader is tolerant of two legacy formats:
+ *   (a) ~/.rift/credentials.json with camelCase fields (old TS auth.ts writer)
+ *   (b) Multi-account wrapped: {"default": {…}}
+ * Both are migrated to the canonical form on first read.
+ *
+ * The Python engine is the authoritative writer. The TS `rift auth setup`
+ * flow also writes to the same path + schema.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const CRED_DIR = path.join(process.env.HOME || '~', '.rift');
+const CANONICAL_PATH = path.join(CRED_DIR, 'credentials');
+const LEGACY_PATH = path.join(CRED_DIR, 'credentials.json');
+function ensureDir() {
+    if (!fs.existsSync(CRED_DIR)) {
+        fs.mkdirSync(CRED_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/** Map any of the known legacy formats onto the canonical snake_case shape. */
+function migrate(data) {
+    // Multi-account wrapper from old TS writer.
+    if (data && typeof data === 'object' && 'default' in data
+        && data.default && typeof data.default === 'object'
+        && !('private_key' in data) && !('privateKey' in data)) {
+        return migrate(data.default);
+    }
+    const private_key = data.private_key ?? data.privateKey;
+    const address = data.address ?? data.apiWalletAddress;
+    const network = data.network;
+    if (!private_key || !address)
+        return null;
+    // Mainnet-only post-testnet rip. Any legacy testnet-paired wallet is
+    // refused so the user gets a clear "re-pair on mainnet" message instead
+    // of trades silently misrouting.
+    if (network && network !== 'mainnet')
+        return null;
+    return {
+        address: String(address).toLowerCase(),
+        private_key: String(private_key).replace(/^0x/, '').toLowerCase(),
+        network: 'mainnet',
+        name: data.name,
+        registered_at: data.registered_at ?? data.createdAt,
+        registered_tx: data.registered_tx ?? null,
+        account_address: (data.account_address ?? data.accountAddress)?.toLowerCase(),
+        type: data.type,
+        agent_approved: data.agent_approved ?? data.agentApproved,
+        builder_fee_approved: data.builder_fee_approved ?? data.builderFeeApproved,
+    };
+}
+function readFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        return migrate(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadCredentials() {
+    // Canonical path first — matches Python's writer.
+    const canonical = readFile(CANONICAL_PATH);
+    if (canonical)
+        return canonical;
+    // Legacy TS path. If found, migrate it to the canonical location so
+    // future reads don't keep migrating.
+    const legacy = readFile(LEGACY_PATH);
+    if (legacy) {
+        try {
+            saveCredentials(legacy);
+        }
+        catch {
+            // Best effort — return what we read even if rewrite fails.
+        }
+        return legacy;
+    }
+    return null;
+}
+export function saveCredentials(creds) {
+    ensureDir();
+    // Atomic write: tmp + rename, with 0600 perms.
+    const payload = JSON.stringify(creds, null, 2);
+    const tmp = CANONICAL_PATH + '.tmp';
+    fs.writeFileSync(tmp, payload, { mode: 0o600 });
+    fs.renameSync(tmp, CANONICAL_PATH);
+    try {
+        fs.chmodSync(CANONICAL_PATH, 0o600);
+    }
+    catch {
+        // Permission tightening is best-effort.
+    }
+}
+export function hasCredentials() {
+    return loadCredentials() !== null;
+}
+/**
+ * Returns true if the wallet is ready for live trading (mainnet-only).
+ *
+ *   - File must exist with `address` + `private_key` (pairing complete).
+ *   - `agent_approved` defaults to true when the file exists — the file is
+ *     only written after a successful approveAgent transaction.
+ *   - `builder_fee_approved` must be explicit `true`. Absent → user is
+ *     prompted to run `rift approve-builder-fee` before their first trade.
+ */
+export function hasFullSetup() {
+    const creds = loadCredentials();
+    if (!creds)
+        return false;
+    if (!creds.private_key || !creds.address)
+        return false;
+    const agentOk = creds.agent_approved !== false; // absent = trust file
+    return agentOk && creds.builder_fee_approved === true;
+}
+/** Main wallet address — falls back to API wallet address when not stored
+ * (older Python-paired wallets don't include account_address). */
+export function getAccountAddress(creds) {
+    return creds.account_address ?? creds.address;
+}
+export function maskKey(key) {
+    if (key.length <= 10)
+        return '****';
+    return key.slice(0, 6) + '...' + key.slice(-4);
+}
+export function maskAddress(addr) {
+    if (addr.length <= 10)
+        return addr;
+    return addr.slice(0, 6) + '...' + addr.slice(-4);
+}

package/dist/lib/engine-passthrough.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Thin passthrough helper for TS wrappers around Python engine commands.
+ *
+ * Each engine command emits NDJSON over stdout. This helper:
+ *   - mirrors `progress` / `status` messages as human-readable lines,
+ *   - surfaces `error` messages via the caller's `error()` (which exits),
+ *   - pretty-prints any `result` payload as JSON.
+ *
+ * Wrappers that need to render rich tables/colors should NOT use this —
+ * see cost.ts for the per-command rendering pattern.
+ */
+export interface PassthroughOptions {
+    command: string;
+    args: string[];
+    /** Bound to the command's this.log */
+    log: (msg: string) => void;
+    /**
+     * Bound to the command's this.error — must exit with a non-zero code.
+     * Only invoked for genuine engine crashes (non-zero exit with no
+     * structured error message already surfaced).
+     */
+    error: (msg: string) => never;
+    /** Bound to the command's this.exit — silent non-zero exit. */
+    exit: (code: number) => never;
+    /** When true, only emit the final result JSON (no progress/status output) */
+    jsonOnly?: boolean;
+}
+export declare function passthroughToEngine(opts: PassthroughOptions): Promise<void>;

package/dist/lib/engine-passthrough.js

@@ -0,0 +1,60 @@
+/**
+ * Thin passthrough helper for TS wrappers around Python engine commands.
+ *
+ * Each engine command emits NDJSON over stdout. This helper:
+ *   - mirrors `progress` / `status` messages as human-readable lines,
+ *   - surfaces `error` messages via the caller's `error()` (which exits),
+ *   - pretty-prints any `result` payload as JSON.
+ *
+ * Wrappers that need to render rich tables/colors should NOT use this —
+ * see cost.ts for the per-command rendering pattern.
+ */
+import { runEngine } from './python-bridge.js';
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+export async function passthroughToEngine(opts) {
+    // Track whether the engine surfaced its own structured error message.
+    // If it did, we suppress the generic "Engine exited with code N" footer
+    // on the non-zero exit — the user already saw the helpful message.
+    let surfacedError = false;
+    try {
+        await runEngine(opts.command, opts.args, (msg) => {
+            const type = msg.type;
+            if (type === 'error' && msg.msg) {
+                // Log + flag instead of opts.error() — throwing CLIError from an
+                // async readline callback isn't caught by oclif's lifecycle and
+                // the message gets swallowed silently. Let the engine's non-zero
+                // exit propagate via runEngine's rejection path; the catch below
+                // exits silently when an error has already been surfaced.
+                if (!opts.jsonOnly)
+                    opts.log(`  ${red('Error:')} ${msg.msg}`);
+                surfacedError = true;
+                return;
+            }
+            if (opts.jsonOnly && type !== 'result')
+                return;
+            if (type === 'progress' && msg.msg) {
+                opts.log(dim(`  ${msg.msg}`));
+            }
+            else if (type === 'status' && msg.msg) {
+                opts.log(`  ${msg.msg}`);
+            }
+            else if (type === 'result') {
+                // Drop the type field; emit the rest as pretty JSON.
+                const { type: _t, ...rest } = msg;
+                opts.log(JSON.stringify(rest, null, 2));
+            }
+            else if (msg.msg) {
+                opts.log(`  ${msg.msg}`);
+            }
+        });
+    }
+    catch (err) {
+        if (surfacedError) {
+            opts.exit(1);
+        }
+        // Engine crashed without emitting a structured error message — re-raise
+        // via opts.error so the user sees the stderr-extracted message.
+        opts.error(err instanceof Error ? err.message : String(err));
+    }
+}

package/dist/lib/fees.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Builder fee management for Hyperliquid.
+ *
+ * Uses Hyperliquid's "builder code" system — a protocol-level fee for apps
+ * that place trades on behalf of users. NOT referral codes (that's separate).
+ *
+ * Two-layer consent:
+ * 1. Local consent — user agrees to fee in CLI (gates all commands)
+ * 2. On-chain approval — user's MAIN wallet signs ApproveBuilderFee (gates live trading)
+ *    API/agent wallets CANNOT sign this — only the main wallet.
+ *
+ * Fee mechanics:
+ * - Perps: 0.03% (f=30) on BOTH sides of perp trades
+ * - Spot: 1% (f=1000) on SELL side only
+ * - Hyperliquid charges automatically at execution, credits to builder wallet
+ * - Builder fees accumulate in Hyperliquid's referral rewards infrastructure
+ * - Claiming is MANUAL via app.hyperliquid.xyz UI (no API action for claiming)
+ * - Claimed rewards go to builder wallet's SPOT balance
+ *
+ * Backtesting, research, simulation, and workbench are free — no approval needed.
+ */
+export declare const BUILDER_ADDRESS: string;
+export declare const BUILDER_FEE_F = 30;
+export declare const BUILDER_FEE_F_PERP = 30;
+export declare const BUILDER_FEE_F_SPOT = 1000;
+export declare const BUILDER_FEE_RATE = "1%";
+export declare const BUILDER_FEE_DISPLAY = "0.03% perps / 1% spot";
+interface FeeConsent {
+    approved: boolean;
+    approvedAt: string;
+    feeRate: string;
+    onChainApproved?: boolean;
+    onChainApprovedAt?: string;
+}
+/** Check if user has given local CLI consent (required for all commands) */
+export declare function hasApprovedFees(): boolean;
+/** Record local CLI consent */
+export declare function approveFees(): void;
+/** Check if user has done on-chain approval (required for live trading) */
+export declare function hasOnChainApproval(): boolean;
+/** Record that on-chain approval was submitted */
+export declare function recordOnChainApproval(): void;
+export declare function getFeeStatus(): FeeConsent | null;
+/**
+ * Get the builder parameter to attach to every live order.
+ * This is what makes the fee collection work.
+ */
+export declare function getOrderBuilderParam(): {
+    b: string;
+    f: number;
+};
+export {};

package/dist/lib/fees.js

@@ -0,0 +1,97 @@
+/**
+ * Builder fee management for Hyperliquid.
+ *
+ * Uses Hyperliquid's "builder code" system — a protocol-level fee for apps
+ * that place trades on behalf of users. NOT referral codes (that's separate).
+ *
+ * Two-layer consent:
+ * 1. Local consent — user agrees to fee in CLI (gates all commands)
+ * 2. On-chain approval — user's MAIN wallet signs ApproveBuilderFee (gates live trading)
+ *    API/agent wallets CANNOT sign this — only the main wallet.
+ *
+ * Fee mechanics:
+ * - Perps: 0.03% (f=30) on BOTH sides of perp trades
+ * - Spot: 1% (f=1000) on SELL side only
+ * - Hyperliquid charges automatically at execution, credits to builder wallet
+ * - Builder fees accumulate in Hyperliquid's referral rewards infrastructure
+ * - Claiming is MANUAL via app.hyperliquid.xyz UI (no API action for claiming)
+ * - Claimed rewards go to builder wallet's SPOT balance
+ *
+ * Backtesting, research, simulation, and workbench are free — no approval needed.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+// RIFT builder wallet — resolved from segments (matches Python engine)
+const _B1 = '0x0916EAb573';
+const _B2 = '817F02b96665386c';
+const _B3 = '944e297A765d7C';
+export const BUILDER_ADDRESS = _B1 + _B2 + _B3;
+// Perp fee: 0.03% = 3 basis points = 30 tenths of basis points
+export const BUILDER_FEE_F = 30;
+export const BUILDER_FEE_F_PERP = 30;
+export const BUILDER_FEE_F_SPOT = 1000; // 1% on spot (sell side only)
+// Approval rate: 1% (covers both spot max and perps)
+export const BUILDER_FEE_RATE = '1%';
+export const BUILDER_FEE_DISPLAY = '0.03% perps / 1% spot';
+function getConfigPath() {
+    return path.join(process.env.HOME || '~', '.rift', 'config.json');
+}
+function loadConfig() {
+    const p = getConfigPath();
+    if (!fs.existsSync(p))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function saveConfig(config) {
+    const dir = path.dirname(getConfigPath());
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+/** Check if user has given local CLI consent (required for all commands) */
+export function hasApprovedFees() {
+    const config = loadConfig();
+    return config.fees?.approved === true;
+}
+/** Record local CLI consent */
+export function approveFees() {
+    const config = loadConfig();
+    config.fees = {
+        ...config.fees,
+        approved: true,
+        approvedAt: new Date().toISOString(),
+        feeRate: BUILDER_FEE_RATE,
+    };
+    saveConfig(config);
+}
+/** Check if user has done on-chain approval (required for live trading) */
+export function hasOnChainApproval() {
+    const config = loadConfig();
+    return config.fees?.onChainApproved === true;
+}
+/** Record that on-chain approval was submitted */
+export function recordOnChainApproval() {
+    const config = loadConfig();
+    config.fees = {
+        ...config.fees,
+        onChainApproved: true,
+        onChainApprovedAt: new Date().toISOString(),
+    };
+    saveConfig(config);
+}
+export function getFeeStatus() {
+    const config = loadConfig();
+    return config.fees || null;
+}
+/**
+ * Get the builder parameter to attach to every live order.
+ * This is what makes the fee collection work.
+ */
+export function getOrderBuilderParam() {
+    return { b: BUILDER_ADDRESS, f: BUILDER_FEE_F };
+}

package/dist/lib/python-bridge.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Bridge between the TypeScript CLI and the Python engine.
+ * Spawns Python processes and reads NDJSON output line by line.
+ */
+export interface EngineMessage {
+    type: 'progress' | 'result' | 'error' | 'status' | 'trade' | 'candle' | 'heartbeat' | 'shutdown' | 'step' | 'step_done' | 'soak';
+    [key: string]: unknown;
+}
+export declare function getDataDir(): string;
+export declare function runEngine(command: string, args: string[], onMessage: (msg: EngineMessage) => void, extraEnv?: Record<string, string>): Promise<void>;
+/** Get the child process from a runEngine promise (for sending signals) */
+export declare function getEngineProcess(promise: Promise<void>): import('node:child_process').ChildProcess | null;
+/**
+ * Spawn the Python engine as a detached daemon process.
+ * Returns immediately after the process is started.
+ * The daemon writes its own PID file and log file.
+ */
+export declare function spawnDaemon(command: string, args: string[], extraEnv?: Record<string, string>): {
+    pid: number;
+};
+/** Session directory paths (must match Python's ALGO_DIR layout) */
+export declare function getAlgoSessionsDir(): string;
+export declare function getAlgoPidsDir(): string;
+export declare function getAlgoLogsDir(): string;

package/dist/lib/python-bridge.js

@@ -0,0 +1,182 @@
+/**
+ * Bridge between the TypeScript CLI and the Python engine.
+ * Spawns Python processes and reads NDJSON output line by line.
+ */
+import { spawn, execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+function getEngineDir() {
+    let dir = path.resolve(__dirname);
+    for (let i = 0; i < 10; i++) {
+        const engineDir = path.join(dir, 'engine');
+        // Require both pyproject.toml AND the rift.cli entry point.
+        // Prevents matching packages/engine (the new rift_engine library)
+        // before reaching the legacy engine/ host that owns -m rift.cli.
+        if (fs.existsSync(path.join(engineDir, 'pyproject.toml')) &&
+            fs.existsSync(path.join(engineDir, 'src', 'rift', 'cli.py')))
+            return engineDir;
+        dir = path.dirname(dir);
+    }
+    throw new Error('Cannot find RIFT engine directory');
+}
+function findPython() {
+    // Check engine's uv-managed venv first
+    const engineVenv = path.join(getEngineDir(), '.venv', 'bin', 'python3');
+    if (fs.existsSync(engineVenv))
+        return engineVenv;
+    // Check for managed venv in data dir
+    const dataVenv = path.join(getDataDir(), 'venv', 'bin', 'python3');
+    if (fs.existsSync(dataVenv))
+        return dataVenv;
+    // Fall back to system Python
+    for (const cmd of ['python3.14', 'python3.13', 'python3']) {
+        try {
+            execSync(`${cmd} --version`, { stdio: 'ignore' });
+            return cmd;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error('Python 3.13+ not found. Install Python or run: rift setup');
+}
+function getStrategiesDir() {
+    let dir = path.resolve(__dirname);
+    for (let i = 0; i < 10; i++) {
+        const strategiesDir = path.join(dir, 'strategies');
+        if (fs.existsSync(strategiesDir))
+            return strategiesDir;
+        dir = path.dirname(dir);
+    }
+    const projectRoot = path.resolve(__dirname, '..', '..', '..', '..');
+    return path.join(projectRoot, 'strategies');
+}
+export function getDataDir() {
+    return path.join(process.env.HOME || '~', '.rift');
+}
+export async function runEngine(command, args, onMessage, extraEnv) {
+    const python = findPython();
+    const engineDir = getEngineDir();
+    const strategiesDir = getStrategiesDir();
+    const fullArgs = [
+        '-m', 'rift.cli',
+        command,
+        ...args,
+    ];
+    // Only add --strategies-dir for commands that accept it
+    if (['backtest', 'strategies', 'compare', 'walk-forward', 'sweep', 'montecarlo', 'portfolio-backtest', 'research', 'quick-test', 'algo'].includes(command)) {
+        fullArgs.push('--strategies-dir', strategiesDir);
+    }
+    const proc = spawn(python, fullArgs, {
+        cwd: engineDir,
+        env: {
+            ...process.env,
+            ...extraEnv,
+            PYTHONPATH: path.join(engineDir, 'src'),
+            PYTHONUNBUFFERED: '1',
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const promise = new Promise((resolve, reject) => {
+        const rl = createInterface({ input: proc.stdout });
+        rl.on('line', (line) => {
+            try {
+                const msg = JSON.parse(line);
+                onMessage(msg);
+            }
+            catch {
+                // Non-JSON output — ignore
+            }
+        });
+        let stderr = '';
+        proc.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        proc.on('close', (code) => {
+            if (code === 0 || code === null) {
+                resolve();
+            }
+            else {
+                const lines = stderr.trim().split('\n').filter(l => l.trim());
+                // Typer's click-rich style emits errors inside a unicode-box:
+                //   ╭─ Error ──...──╮
+                //   │ <message>     │
+                //   ╰────...──────╯
+                // Pull the message line out so the user sees "No such command X"
+                // instead of the box-drawing close character that happens to be
+                // the last stderr line.
+                const typerBoxMsg = (() => {
+                    for (const l of lines) {
+                        const m = l.match(/^\s*│\s+(.+?)\s+│?\s*$/);
+                        if (m && m[1].trim())
+                            return m[1].trim();
+                    }
+                    return null;
+                })();
+                const lastLine = lines[lines.length - 1] || '';
+                let errorLine = typerBoxMsg
+                    || lines.find(l => /^Error:/.test(l.trim()))
+                    || lines.find(l => /^(KeyError|ValueError|TypeError|RuntimeError|FileNotFoundError|ImportError|AttributeError|NameError):/.test(l.trim()))
+                    || lastLine;
+                errorLine = errorLine.trim().replace(/^Error:\s*/, '');
+                reject(new Error(errorLine || `Engine exited with code ${code}`));
+            }
+        });
+        proc.on('error', (err) => {
+            reject(new Error(`Failed to start engine: ${err.message}`));
+        });
+    });
+    promise._proc = proc;
+    return promise;
+}
+/** Get the child process from a runEngine promise (for sending signals) */
+export function getEngineProcess(promise) {
+    return promise?._proc ?? null;
+}
+/**
+ * Spawn the Python engine as a detached daemon process.
+ * Returns immediately after the process is started.
+ * The daemon writes its own PID file and log file.
+ */
+export function spawnDaemon(command, args, extraEnv) {
+    const python = findPython();
+    const engineDir = getEngineDir();
+    const fullArgs = [
+        '-m', 'rift.cli',
+        command,
+        ...args,
+        '--daemon',
+    ];
+    // Open /dev/null for stdio — daemon writes to its own log file
+    const devNull = fs.openSync('/dev/null', 'r+');
+    const proc = spawn(python, fullArgs, {
+        cwd: engineDir,
+        env: {
+            ...process.env,
+            ...extraEnv,
+            PYTHONPATH: path.join(engineDir, 'src'),
+            PYTHONUNBUFFERED: '1',
+        },
+        stdio: [devNull, devNull, devNull],
+        detached: true,
+    });
+    // Let the daemon run independently of this process
+    proc.unref();
+    const pid = proc.pid ?? 0;
+    fs.closeSync(devNull);
+    return { pid };
+}
+/** Session directory paths (must match Python's ALGO_DIR layout) */
+export function getAlgoSessionsDir() {
+    return path.join(getDataDir(), 'algo', 'sessions');
+}
+export function getAlgoPidsDir() {
+    return path.join(getDataDir(), 'algo', 'pids');
+}
+export function getAlgoLogsDir() {
+    return path.join(getDataDir(), 'algo', 'logs');
+}

package/dist/lib/setup-status.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Phase 0 setup-status detector.
+ *
+ * Determines what state the user's RIFT installation is in by checking
+ * file system state — cheap (just stat calls), runs on every CLI command
+ * to drive the status footer and bare-rift wizard routing.
+ *
+ * No Python required; pure TS for speed (every CLI invocation reads this).
+ */
+export type SetupState = 'fresh' | 'research-only' | 'incomplete' | 'live-ready' | 'kill-active' | 'agent-revoked';
+export interface SetupStatus {
+    state: SetupState;
+    agentAddress: string | null;
+    network: 'mainnet' | null;
+    hasMainWalletPaired: boolean;
+    hasApiWallet: boolean;
+    hasEnvConfig: boolean;
+    tokenCount: number;
+    killSwitchActive: boolean;
+    riftVersion: string;
+}
+/**
+ * Inspect the local file system and return the current setup state.
+ *
+ * Pure function — no network, no Python invocation, no chain calls.
+ * Safe to call from every CLI command (every footer render reads this).
+ */
+export declare function getSetupStatus(): SetupStatus;
+/** Convenience: true iff the user can run live trading right now. */
+export declare function canTradeNow(s?: SetupStatus): boolean;
+/** Convenience: short address ellipsis for display (0x1234…abcd). */
+export declare function shortAddr(addr: string | null): string;