dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/src/trade.js

@@ -0,0 +1,319 @@
+// dexterm — PAPER trade ticket state machine (task-1310 T0, SPEC §6.1). Pure and TTY-free so the
+// ticket maths and the keypress confirm gate are unit-testable. The interactive loop and the live
+// binding drive this reducer and perform the side effects (quote fetch, executor.execute).
+//
+// Safety: this file builds an *order* and reads a *quote*. It never signs, holds a key, or sends a
+// transaction, and it imports no wallet/signing library (SPEC §6.0). Every ticket is labelled PAPER
+// and the confirm gate is ON by default: arming needs a deliberate keypress, and sizes above a
+// configurable threshold must be typed back (SPEC §6.1 step 3).
+import { solToLamports, LAMPORTS_PER_SOL } from '../../data/src/index.js';
+/** Default slippage and the SOL notional above which the confirm requires a typed-back amount. */
+export const DEFAULT_SLIPPAGE_BPS = 50;
+export const DEFAULT_TYPEBACK_THRESHOLD_SOL = 1;
+export const MAX_SLIPPAGE_BPS = 5000;
+export function openTicket(seed) {
+    return {
+        mint: seed.mint,
+        symbol: seed.symbol,
+        decimals: typeof seed.decimals === 'number' && Number.isFinite(seed.decimals) && seed.decimals > 0 ? seed.decimals : 9,
+        side: seed.side,
+        sizeUnit: seed.side === 'buy' ? 'sol' : 'pct',
+        sizeInput: '',
+        slippageInput: String(seed.slippageBps ?? DEFAULT_SLIPPAGE_BPS),
+        field: 'size',
+        phase: 'editing',
+        mode: seed.mode ?? 'paper',
+        gateOn: seed.gateOn ?? true,
+        typebackRequired: false,
+        typeback: '',
+        message: null,
+    };
+}
+function parseNum(s) {
+    const n = Number(s);
+    return Number.isFinite(n) ? n : NaN;
+}
+export function slippageBps(ts) {
+    if (ts.slippageInput.trim() === '')
+        return DEFAULT_SLIPPAGE_BPS;
+    const n = parseNum(ts.slippageInput);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_SLIPPAGE_BPS;
+    return Math.min(MAX_SLIPPAGE_BPS, Math.round(n));
+}
+/** The raw amount an order would spend, given the live context; 0n when the size is empty/invalid. */
+export function orderAmountRaw(ts, ctx) {
+    const n = parseNum(ts.sizeInput);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0n;
+    if (ts.side === 'buy') {
+        if (ts.sizeUnit === 'sol')
+            return solToLamports(n);
+        // % of free SOL balance
+        const pct = Math.min(100, n);
+        return (ctx.balanceLamports * BigInt(Math.round(pct * 100))) / 10000n;
+    }
+    // sell: % of the held position
+    const pct = Math.min(100, n);
+    return (ctx.positionTokensRaw * BigInt(Math.round(pct * 100))) / 10000n;
+}
+/** Build the order the ticket represents (amount already in raw base units). */
+export function toOrder(ts, ctx) {
+    return { mint: ts.mint, symbol: ts.symbol, side: ts.side, decimals: ts.decimals, amountRaw: orderAmountRaw(ts, ctx), slippageBps: slippageBps(ts) };
+}
+/** Is the current size a fillable order (positive amount, and for a sell there are tokens to sell)? */
+export function orderValid(ts, ctx) {
+    const amt = orderAmountRaw(ts, ctx);
+    if (amt <= 0n)
+        return false;
+    if (ts.side === 'sell' && ctx.positionTokensRaw <= 0n)
+        return false;
+    return true;
+}
+const DIGIT = /[0-9.]/;
+function editField(ts, key) {
+    const cur = ts.field === 'size' ? ts.sizeInput : ts.slippageInput;
+    if (key.name === 'backspace') {
+        const next = cur.slice(0, -1);
+        if (ts.field === 'size')
+            ts.sizeInput = next;
+        else
+            ts.slippageInput = next;
+        return true;
+    }
+    if ((key.name === 'char') && key.ch && DIGIT.test(key.ch) && !key.ctrl && !key.alt) {
+        // one decimal point only; slippage is integer bps
+        if (key.ch === '.' && (ts.field === 'slippage' || cur.includes('.')))
+            return true;
+        const next = (cur + key.ch).slice(0, 12);
+        if (ts.field === 'size')
+            ts.sizeInput = next;
+        else
+            ts.slippageInput = next;
+        return true;
+    }
+    return false;
+}
+/**
+ * Advance the ticket by one key. Returns the effect the caller performs:
+ *  - 'changed' : the order inputs changed → re-fetch the warm quote;
+ *  - 'confirm' : the gate was satisfied → the caller must execute the order now;
+ *  - 'close'   : leave the ticket (back to the token screen);
+ *  - 'none'    : nothing to do.
+ * A stray key during the confirm step can NEVER confirm — it cancels back to editing.
+ */
+export function ticketKey(ts, key, ctx) {
+    ts.message = null;
+    if (ts.phase === 'filling' || ts.phase === 'signing')
+        return 'none'; // in-flight: ignore input
+    if (ts.phase === 'planning')
+        return 'none'; // the signer is building; esc is handled by the binding (cancel)
+    if (ts.phase === 'filled' || ts.phase === 'error' || ts.phase === 'refused') {
+        // a receipt is showing: esc closes, any other key starts a fresh ticket for the same mint (same mode)
+        if (key.name === 'esc')
+            return 'close';
+        const side = ts.side;
+        Object.assign(ts, openTicket({ mint: ts.mint, symbol: ts.symbol, decimals: ts.decimals, side, gateOn: ts.gateOn, slippageBps: slippageBps(ts), mode: ts.mode }));
+        return 'changed';
+    }
+    // ---- LIVE plan screen (task-1328): the keypress gate for a REAL trade. Y / ⏎ confirms (with the
+    // typed-back size above the threshold, exactly like paper); esc returns to editing; ANY other key
+    // cancels — a stray key can never confirm, and never navigates mid-plan.
+    if (ts.phase === 'plan') {
+        if (key.name === 'esc') {
+            ts.phase = 'editing';
+            ts.typeback = '';
+            return 'drop-plan';
+        }
+        if (ts.typebackRequired && key.name === 'char' && key.ch && DIGIT.test(key.ch)) {
+            if (key.ch === '.' && ts.typeback.includes('.'))
+                return 'none';
+            ts.typeback = (ts.typeback + key.ch).slice(0, 12);
+            return 'none';
+        }
+        if (ts.typebackRequired && key.name === 'backspace') {
+            ts.typeback = ts.typeback.slice(0, -1);
+            return 'none';
+        }
+        const confirmKey = (key.name === 'char' && (key.ch === 'y' || key.ch === 'Y')) || key.name === 'enter';
+        if (confirmKey) {
+            if (ts.typebackRequired) {
+                const want = parseNum(ts.sizeInput);
+                const got = parseNum(ts.typeback);
+                if (!(Number.isFinite(got) && Math.abs(got - want) < 1e-9)) {
+                    ts.message = `type the size (${ts.sizeInput}) to confirm this LIVE ${ts.side}`;
+                    return 'none';
+                }
+            }
+            ts.phase = 'signing';
+            return 'confirm-live';
+        }
+        ts.phase = 'editing';
+        ts.typeback = '';
+        ts.message = 'plan cancelled';
+        return 'drop-plan';
+    }
+    if (ts.phase === 'confirm') {
+        if (key.name === 'esc') {
+            ts.phase = 'editing';
+            ts.typeback = '';
+            return 'none';
+        }
+        if (ts.typebackRequired && key.name === 'char' && key.ch && DIGIT.test(key.ch)) {
+            if (key.ch === '.' && ts.typeback.includes('.'))
+                return 'none';
+            ts.typeback = (ts.typeback + key.ch).slice(0, 12);
+            return 'none';
+        }
+        if (ts.typebackRequired && key.name === 'backspace') {
+            ts.typeback = ts.typeback.slice(0, -1);
+            return 'none';
+        }
+        const confirmKey = (key.name === 'char' && (key.ch === 'y' || key.ch === 'Y')) || key.name === 'enter';
+        if (confirmKey) {
+            if (ts.typebackRequired) {
+                const want = parseNum(ts.sizeInput);
+                const got = parseNum(ts.typeback);
+                if (!(Number.isFinite(got) && Math.abs(got - want) < 1e-9)) {
+                    ts.message = `type the size (${ts.sizeInput}) to confirm this PAPER ${ts.side}`;
+                    return 'none';
+                }
+            }
+            ts.phase = 'filling';
+            return 'confirm';
+        }
+        // any other key cancels the arm (a stray key never confirms, and never navigates mid-confirm)
+        ts.phase = 'editing';
+        ts.typeback = '';
+        ts.message = 'confirm cancelled';
+        return 'none';
+    }
+    // ---- editing
+    if (key.name === 'esc')
+        return 'close';
+    if (key.name === 'char' && (key.ch === 'L' || key.ch === 'l') && !key.ctrl && !key.alt)
+        return 'toggle-live';
+    if (key.name === 'tab') {
+        ts.field = ts.field === 'size' ? 'slippage' : 'size';
+        return 'none';
+    }
+    if (key.name === 'left' || key.name === 'right') {
+        ts.side = ts.side === 'buy' ? 'sell' : 'buy';
+        ts.sizeUnit = ts.side === 'buy' ? ts.sizeUnit : 'pct';
+        ts.typeback = '';
+        return 'changed';
+    }
+    if (key.name === 'char' && key.ch === 'u' && !key.ctrl) {
+        if (ts.side === 'buy') {
+            ts.sizeUnit = ts.sizeUnit === 'sol' ? 'pct' : 'sol';
+            return 'changed';
+        }
+        return 'none'; // sell is always % of the position
+    }
+    if (key.name === 'enter') {
+        if (!orderValid(ts, ctx)) {
+            ts.message = ts.side === 'sell' && ctx.positionTokensRaw <= 0n ? `no ${ts.symbol} position to sell` : 'enter a size first';
+            return 'none';
+        }
+        ts.typebackRequired = ts.gateOn && ctx.notionalSol > ctx.typebackThresholdSol;
+        ts.typeback = '';
+        if (ts.mode === 'live') {
+            ts.phase = 'planning';
+            return 'plan';
+        }
+        ts.phase = 'confirm';
+        return 'none';
+    }
+    // task-1368: f on a LIVE buy = size the order to the signer's cap (the binding knows the caps + SOL/USD; the
+    // reducer only names the effect). Inert on PAPER (no caps) and on a sell (sized in % of the position).
+    if (key.name === 'char' && (key.ch === 'f' || key.ch === 'F') && !key.ctrl && !key.alt) {
+        return ts.mode === 'live' && ts.side === 'buy' ? 'fit-cap' : 'none';
+    }
+    if (editField(ts, key))
+        return 'changed';
+    return 'none';
+}
+// --------------------------------------------------------------------------- task-1368 preflight + hints (pure)
+/**
+ * Fees + token-account rent the signer's simulated SOL-out may add on top of the size of a BUY (a tx fee, a priority
+ * fee and one associated-token-account rent of 0.00203928 SOL when the wallet has never held the token). The
+ * signer prices the LARGER of the planned SOL leg and the simulated SOL out, so a size that is exactly the cap in
+ * USD is refused once rent lands on top; `fitSizeSol` leaves this much room.
+ */
+export const CAP_FIT_OVERHEAD_SOL = 0.0025;
+const usd = (n) => `$${n.toFixed(2).replace(/\.00$/, '')}`;
+/**
+ * Size vs the signer's caps BEFORE ⏎ (task-1368 item b): the USD value of the size at the signer's own SOL/USD, the
+ * per-trade cap and what is left of the daily cap, a red verdict when the size is over, and the size that fits.
+ * Pure: the signer still decides at precheck/confirm — this only stops the user from building a plan that will be
+ * refused for a reason they could not see.
+ */
+export function capPreflight(i) {
+    const sizeSol = Number.isFinite(i.sizeSol) && i.sizeSol > 0 ? i.sizeSol : 0;
+    const price = i.solUsd !== null && Number.isFinite(i.solUsd) && i.solUsd > 0 ? i.solUsd : null;
+    const perTradeUsd = Math.max(0, i.perTradeUsd);
+    const dailyRemainingUsd = Math.max(0, i.dailyUsd - Math.max(0, i.spentTodayUsd));
+    const capUsd = Math.min(perTradeUsd, dailyRemainingUsd);
+    const sizeUsd = price !== null && sizeSol > 0 ? sizeSol * price : null;
+    const over = sizeUsd !== null && sizeUsd > capUsd + 1e-9;
+    const binding = !over ? null : dailyRemainingUsd < perTradeUsd ? 'daily' : 'per-trade';
+    const overhead = Math.max(0, i.overheadSol ?? CAP_FIT_OVERHEAD_SOL);
+    let fitSizeSol = null;
+    if (price !== null && capUsd > 0) {
+        const fit = Math.floor((capUsd / price - overhead) * 1000) / 1000;
+        fitSizeSol = fit > 0 ? fit : null;
+    }
+    const capText = `cap ${usd(perTradeUsd)}/trade · ${usd(dailyRemainingUsd)} left of ${usd(Math.max(0, i.dailyUsd))} today`;
+    let line;
+    if (sizeSol <= 0)
+        line = `${capText} · enter a size`;
+    else if (price === null)
+        line = `${sizeSol} SOL = $? (the signer has no SOL/USD yet; it will refuse an unpriced trade on mainnet) · ${capText}`;
+    else if (over) {
+        const which = binding === 'daily' ? `${usd(dailyRemainingUsd)} left today` : `${usd(perTradeUsd)} cap`;
+        line = `${sizeSol} SOL = ${usd(sizeUsd)} > ${which}: ${fitSizeSol !== null ? `use ≤ ${fitSizeSol} SOL (f fits it; fees + token-account rent counted)` : 'nothing fits — the cap is spent for today'}`;
+    }
+    else
+        line = `${sizeSol} SOL ≈ ${usd(sizeUsd)} at SOL ${usd(price)} · ${capText}`;
+    return { sizeSol, sizeUsd, perTradeUsd, dailyRemainingUsd, capUsd, over, fitSizeSol, binding, line };
+}
+const WSOL = 'So11111111111111111111111111111111111111112';
+/**
+ * task-1368 item c: a DEVNET signer + a Jupiter swap = a transaction built on MAINNET state (there is no Jupiter
+ * devnet): it can never simulate or fill on devnet, so say so BEFORE ⏎ and name the two ways out. Null for the
+ * probe (built for devnet on purpose), for wrapped SOL itself, and on mainnet.
+ */
+export function devnetMintWarning(a) {
+    if (a.network !== 'devnet' || a.probe || a.mint === WSOL)
+        return null;
+    const caps = `caps ${usd(a.perTradeUsd ?? 5)}/${usd(a.dailyUsd ?? 20)}`;
+    return `DEVNET cannot fill mainnet tokens: paper trade (L) or restart with --mainnet (real funds, ${caps})`;
+}
+const MAINNET_STATE_ERR = /invalid transaction|blockhash|account.*not found|not found|could not find|address (table|lookup)|AccountNotFound|ProgramAccountNotFound|unknown program|InvalidAccountData/i;
+/**
+ * task-1368 item f: a plain-English hint under a failed simulation when the failure pattern is the devnet-vs-mainnet
+ * mismatch (a mainnet route simulated on a devnet node: accounts, lookup tables or blockhash not found). Null when
+ * the simulation passed, was not run, or failed for another reason (the full error is still shown).
+ */
+export function simFailureHint(p, caps) {
+    if (p.kind !== 'swap' || !p.sim.ran || p.sim.ok)
+        return null;
+    const err = p.sim.error ?? '';
+    const mainnetState = MAINNET_STATE_ERR.test(err);
+    if (p.network === 'devnet' && (mainnetState || p.mintOnNetwork === false)) {
+        const mint = p.mintOnNetwork === false ? ' (the mint does not exist on devnet)' : '';
+        return `devnet-vs-mainnet wall${mint}: a Jupiter swap is built on MAINNET state (accounts, lookup tables, blockhash) that a devnet node does not have. Paper trade (L) or restart with --mainnet (real funds, caps ${usd(caps?.perTradeUsd ?? 5)}/${usd(caps?.dailyUsd ?? 20)}).`;
+    }
+    if (mainnetState)
+        return 'the node could not find the route\'s accounts or blockhash: a stale plan or the wrong RPC network — rebuild with ⏎, or check --trade-rpc';
+    return null;
+}
+/** SOL notional of a buy order sized in SOL/%, used to gate the typed-back step without a quote. */
+export function buyNotionalSol(ts, balanceLamports) {
+    const n = parseNum(ts.sizeInput);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    if (ts.sizeUnit === 'sol')
+        return n;
+    return (Number(balanceLamports) / 1e9) * Math.min(100, n) / 100;
+}

package/dist/packages/cli/src/voice-hud.js

@@ -0,0 +1,42 @@
+// Transcripts and model text are UNTRUSTED input (task-1282): strip C0/C1 control characters and DEL
+// before they are drawn, so an injected escape sequence in a transcript can never reach the terminal.
+const sanitize = (s) => s.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+/** Render the one-line voice badge at (1,1). Clipped to the width; never wraps. */
+export function renderVoiceHud(c, v, t) {
+    if (!v.enabled)
+        return;
+    const bg = t.bg;
+    let x = 1;
+    const y = 1;
+    const mute = v.muted ? ' ⌀muted' : '';
+    const voiceName = v.voice ? ` · ${v.voice}` : '';
+    if (v.mode === 'listening') {
+        // The loud, unmistakable mic-live state.
+        x = c.text(x, y, ' ● LISTENING ', { fg: t.bg, bg: t.down, b: true });
+        x = c.text(x, y, ' speak — v to send, esc to cancel', { fg: t.down, bg, b: true });
+    }
+    else if (v.mode === 'transcribing') {
+        x = c.text(x, y, ' ◍ transcribing… ', { fg: t.warn, bg, b: true });
+    }
+    else if (v.mode === 'thinking') {
+        x = c.text(x, y, ' ◌ asking the analyst… ', { fg: t.borderFocus, bg, b: true });
+    }
+    else if (v.mode === 'speaking') {
+        x = c.text(x, y, ' ▸ speaking ', { fg: t.up, bg, b: true });
+        x = c.text(x, y, '(v/esc stop)', { fg: t.muted, bg });
+    }
+    else {
+        // idle but enabled: a quiet "ready" badge with the key hints.
+        x = c.text(x, y, ' ◎ voice ', { fg: t.borderFocus, bg, b: true });
+        x = c.text(x, y, `v talk · m ${v.muted ? 'unmute' : 'mute'} · , voice${voiceName}`, { fg: t.muted, bg });
+    }
+    if (mute && v.mode !== 'off')
+        x = c.text(x, y, mute, { fg: t.warn, bg, b: true });
+    // A short echo of what was heard / said, to the right, when there is room.
+    const echo = v.message ? `⚠ ${sanitize(v.message)}` : v.transcript ? `“${sanitize(v.transcript)}”` : v.say ? `▸ ${sanitize(v.say)}` : '';
+    if (echo && x + 3 < c.w) {
+        const room = c.w - x - 2;
+        const shown = echo.length > room ? echo.slice(0, Math.max(0, room - 1)) + '…' : echo;
+        c.text(x + 1, y, shown, { fg: v.message ? t.warn : t.dim, bg });
+    }
+}