dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/src/scan/engine.js

@@ -0,0 +1,419 @@
+import { buyShare } from "../live/flow.js";
+export const TRIGGER_IDS = ['vol', 'flow', 'fresh', 'breakout', 'liq', 'holders'];
+/** Points a fully-strong trigger contributes; a just-fired one contributes half. */
+export const WEIGHTS = { vol: 30, flow: 25, fresh: 20, breakout: 20, liq: 15, holders: 15 };
+export const DEFAULT_SCAN_CONFIG = Object.freeze({
+    minScore: 45, minTriggers: 2, minLiqUsd: 10_000,
+    volX: 3, volFullX: 10, volMinUsd: 2_000,
+    flowShare: 0.62, flowPrevMax: 0.52, flowMinTxns: 20, flowFullShare: 0.85,
+    freshMaxAgeMin: 60, freshMinTxns: 40, freshShare: 0.58, freshMinVolUsd: 5_000, freshFullTxns: 150,
+    breakoutLookback: 20, breakoutPct: 2, breakoutFullPct: 10,
+    liqJumpPct: 20, liqFullPct: 60,
+    holdersJumpPct: 5, holdersJumpMin: 25, holdersFullPct: 25,
+    windowMs: 10 * 60_000,
+    vetoAuthorities: true,
+    warmupS: 30,
+    maxAiPerHour: 8, maxAiPerCoin: 4,
+    refreshS: 90, movePct: 3, moveFlowPts: 10, moveVolX: 1.5,
+    coinCooldownS: 15 * 60, postLockS: 60,
+    tickerSize: 5,
+});
+/** Merge overrides onto the defaults, dropping non-finite numbers (a bad flag never poisons the engine). */
+export function scanConfig(over = {}) {
+    const out = { ...DEFAULT_SCAN_CONFIG };
+    for (const [k, v] of Object.entries(over)) {
+        if (!(k in DEFAULT_SCAN_CONFIG))
+            continue;
+        if (typeof DEFAULT_SCAN_CONFIG[k] === 'boolean') {
+            if (typeof v === 'boolean')
+                out[k] = v;
+            continue;
+        }
+        if (typeof v === 'number' && Number.isFinite(v))
+            out[k] = v;
+    }
+    return out;
+}
+const clamp01 = (x) => (Number.isFinite(x) ? Math.max(0, Math.min(1, x)) : 0);
+const pos = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
+const pct0 = (x) => `${Math.round(x * 100)}%`;
+/** `$12.4K` style for reasons (no locale, deterministic). */
+export function usd(n) {
+    const a = Math.abs(n);
+    if (a >= 1e9)
+        return `$${(n / 1e9).toFixed(1)}B`;
+    if (a >= 1e6)
+        return `$${(n / 1e6).toFixed(1)}M`;
+    if (a >= 1e3)
+        return `$${(n / 1e3).toFixed(1)}K`;
+    return `$${Math.round(n)}`;
+}
+const hit = (id, strength, reason) => {
+    const s = clamp01(strength);
+    return { id, strength: s, points: WEIGHTS[id] * (0.5 + 0.5 * s), reason };
+};
+/** The coin's own average 5-minute volume pace: vol6h/72, else vol1h/12, else vol24/288. */
+export function volBaseline(o) {
+    if (pos(o.vol6h))
+        return { per5m: o.vol6h / 72, basis: '6h' };
+    if (pos(o.vol1h))
+        return { per5m: o.vol1h / 12, basis: '1h' };
+    if (pos(o.vol24))
+        return { per5m: o.vol24 / 288, basis: '24h' };
+    return null;
+}
+export function volTrigger(o, cfg) {
+    if (!pos(o.vol5m) || o.vol5m < cfg.volMinUsd)
+        return null;
+    const b = volBaseline(o);
+    if (!b || b.per5m <= 0)
+        return null;
+    const ratio = o.vol5m / b.per5m;
+    if (ratio < cfg.volX)
+        return null;
+    return hit('vol', (ratio - cfg.volX) / Math.max(1e-9, cfg.volFullX - cfg.volX), `vol 5m ${usd(o.vol5m)} = ${ratio.toFixed(1)}× its ${b.basis} pace`);
+}
+export function flowTrigger(o, cfg) {
+    if (!o.m5 || !o.h1)
+        return null;
+    const n5 = o.m5.buys + o.m5.sells;
+    const s5 = buyShare(o.m5);
+    const s1 = buyShare(o.h1);
+    if (s5 === null || s1 === null || n5 < cfg.flowMinTxns)
+        return null;
+    if (s5 < cfg.flowShare || s1 > cfg.flowPrevMax)
+        return null;
+    return hit('flow', (s5 - cfg.flowShare) / Math.max(1e-9, cfg.flowFullShare - cfg.flowShare), `flow flip: 5m buys ${pct0(s5)} (${o.m5.buys}/${n5}) vs 1h ${pct0(s1)}`);
+}
+export function freshTrigger(o, cfg) {
+    if (o.ageMin === null || o.ageMin < 0 || o.ageMin > cfg.freshMaxAgeMin || !o.m5)
+        return null;
+    const n5 = o.m5.buys + o.m5.sells;
+    const s5 = buyShare(o.m5);
+    if (s5 === null || n5 < cfg.freshMinTxns || s5 < cfg.freshShare)
+        return null;
+    if (!pos(o.vol5m) || o.vol5m < cfg.freshMinVolUsd)
+        return null;
+    return hit('fresh', (n5 - cfg.freshMinTxns) / Math.max(1e-9, cfg.freshFullTxns - cfg.freshMinTxns), `fresh launch ${Math.round(o.ageMin)}m old: 5m ${n5} txns, ${pct0(s5)} buys, ${usd(o.vol5m)}`);
+}
+export function breakoutTrigger(o, cfg) {
+    const cs = o.candles;
+    const n = cfg.breakoutLookback;
+    if (!cs || n < 1 || cs.length < n + 1)
+        return null;
+    const last = cs[cs.length - 1];
+    let hi = -Infinity;
+    for (let i = cs.length - 1 - n; i < cs.length - 1; i++)
+        hi = Math.max(hi, cs[i].h);
+    if (!pos(hi) || !pos(last.c))
+        return null;
+    const p = (last.c / hi - 1) * 100;
+    if (p < cfg.breakoutPct)
+        return null;
+    return hit('breakout', (p - cfg.breakoutPct) / Math.max(1e-9, cfg.breakoutFullPct - cfg.breakoutPct), `breakout: close +${p.toFixed(1)}% above the ${n}-bar high`);
+}
+/** Ring samples strictly before `o.t` inside the look-back window. */
+function window(ring, t, ms) {
+    return (ring ?? []).filter((s) => s.t < t && t - s.t <= ms);
+}
+export function liqTrigger(o, ring, cfg) {
+    if (!pos(o.liq))
+        return null;
+    const prior = window(ring, o.t, cfg.windowMs).filter((s) => pos(s.liq));
+    if (!prior.length)
+        return null;
+    let lo = prior[0];
+    for (const s of prior)
+        if (s.liq < lo.liq)
+            lo = s;
+    const p = (o.liq / lo.liq - 1) * 100;
+    if (p < cfg.liqJumpPct)
+        return null;
+    return hit('liq', (p - cfg.liqJumpPct) / Math.max(1e-9, cfg.liqFullPct - cfg.liqJumpPct), `liquidity +${Math.round(p)}% in ${Math.max(1, Math.round((o.t - lo.t) / 60_000))}m (${usd(lo.liq)}→${usd(o.liq)})`);
+}
+export function holdersTrigger(o, ring, cfg) {
+    if (!pos(o.holders))
+        return null;
+    const prior = window(ring, o.t, cfg.windowMs).filter((s) => pos(s.holders));
+    if (!prior.length)
+        return null;
+    const first = prior[0]; // oldest in the window
+    const h0 = first.holders;
+    const d = o.holders - h0;
+    const p = (d / h0) * 100;
+    if (p < cfg.holdersJumpPct || d < cfg.holdersJumpMin)
+        return null;
+    return hit('holders', (p - cfg.holdersJumpPct) / Math.max(1e-9, cfg.holdersFullPct - cfg.holdersJumpPct), `holders +${d} (+${p.toFixed(1)}%) in ${Math.max(1, Math.round((o.t - first.t) / 60_000))}m`);
+}
+/** Every trigger for one coin, its score, the veto and whether it is EXCITING. Pure. */
+export function scoreCoin(o, ring, cfg) {
+    const base = { mint: o.mint, symbol: o.symbol, t: o.t };
+    if (!pos(o.liq) || o.liq < cfg.minLiqUsd)
+        return { ...base, score: 0, hits: [], veto: null, exciting: false };
+    const hits = [volTrigger(o, cfg), flowTrigger(o, cfg), freshTrigger(o, cfg), breakoutTrigger(o, cfg), liqTrigger(o, ring, cfg), holdersTrigger(o, ring, cfg)]
+        .filter((h) => h !== null)
+        .sort((a, b) => b.points - a.points);
+    let veto = null;
+    if (o.larp === 'LARP')
+        veto = 'vetoed: LARP verdict (larp-check)';
+    else if (cfg.vetoAuthorities && o.mintAuth === true)
+        veto = 'vetoed: mint authority enabled';
+    else if (cfg.vetoAuthorities && o.freezeAuth === true)
+        veto = 'vetoed: freeze authority enabled';
+    const raw = Math.min(100, Math.round(hits.reduce((s, h) => s + h.points, 0)));
+    const score = veto ? 0 : raw;
+    return { ...base, score, hits, veto, exciting: !veto && score >= cfg.minScore && hits.length >= cfg.minTriggers };
+}
+/** What changed enough since the last read to justify a refresh turn (empty = nothing material). */
+export function materialMove(prev, cur, prevHits, curHits, cfg) {
+    if (!prev)
+        return ['first read'];
+    const out = [];
+    if (pos(prev.price) && pos(cur.price)) {
+        const p = (cur.price / prev.price - 1) * 100;
+        if (Math.abs(p) >= cfg.movePct)
+            out.push(`price ${p >= 0 ? '+' : ''}${p.toFixed(1)}%`);
+    }
+    const a = buyShare(prev.m5), b = buyShare(cur.m5);
+    if (a !== null && b !== null && Math.abs(b - a) * 100 >= cfg.moveFlowPts)
+        out.push(`5m buy share ${pct0(a)}→${pct0(b)}`);
+    if (pos(prev.vol5m) && pos(cur.vol5m)) {
+        const f = cur.vol5m / prev.vol5m;
+        if (f >= cfg.moveVolX || f <= 1 / cfg.moveVolX)
+            out.push(`vol 5m ×${f.toFixed(2)}`);
+    }
+    const fresh = curHits.filter((id) => !prevHits.includes(id));
+    if (fresh.length)
+        out.push(`new trigger: ${fresh.join(', ')}`);
+    return out;
+}
+/** The first analyst turn of a lock: the reasons (engine-built text: numbers + fixed words, no token text). */
+export function lockQuestion(score, hits) {
+    return `SCAN TRIGGER on the SELECTED coin (scan score ${score}/100): ${hits.map((h) => h.reason).join('; ')}. `
+        + 'Give your short read now: call · why · levels · risk. Observe only: do not open tickets or navigate.';
+}
+/** A refresh turn on the warm session while LOCKED. */
+export function refreshQuestion(moved) {
+    return `SCAN REFRESH: the data moved since your last read (${moved.join('; ')}). `
+        + 'Give an UPDATED short read and say in one line what changed. Observe only.';
+}
+const HOUR = 3_600_000;
+const RING_MAX = 40;
+const MAX_MINTS = 800;
+const FORGET_MS = 30 * 60_000;
+/**
+ * The scan state machine. `observe()` takes the coins the app already has, `tick()` scores them and
+ * returns at most one decision (lock a coin / refresh the locked read). Invariants:
+ *   - off/paused never decide anything; locked only ever decides a refresh OF THE LOCKED COIN (no hop);
+ *   - every decision is one analyst invocation and is only returned when the hourly and per-coin caps
+ *     allow it; a refresh additionally needs refreshS since the last read, an idle analyst and a
+ *     material data move; a lock needs the warm-up, the post-lock cooldown and the coin's cooldown over.
+ */
+export class ScanEngine {
+    cfg;
+    mode = 'off';
+    startedAt = null;
+    lock = null;
+    /** Top coins by score (excluding vetoed / ineligible), for the SCANNING ticker. */
+    ticker = [];
+    /** Coins scored on the last tick (eligible by liquidity). */
+    scanned = 0;
+    /** Why nothing locked on the last tick (warming up, cooldown, ai cap …), for the ticker. */
+    note = null;
+    rings = new Map();
+    latest = new Map();
+    seenAt = new Map();
+    invocations = [];
+    barredUntil = new Map();
+    noLockUntil = 0;
+    constructor(cfg = {}) {
+        this.cfg = scanConfig(cfg);
+    }
+    get on() { return this.mode !== 'off'; }
+    /** off → scanning. Returns false when already on. */
+    start(now) {
+        if (this.mode !== 'off')
+            return false;
+        this.mode = 'scanning';
+        this.startedAt = now;
+        this.lock = null;
+        this.note = null;
+        return true;
+    }
+    /** Any state → off. The locked coin (if any) gets its cooldown. Returns the mint that was locked. */
+    stop(now) {
+        const was = this.lock?.mint ?? null;
+        if (was)
+            this.barredUntil.set(was, now + this.cfg.coinCooldownS * 1000);
+        this.mode = 'off';
+        this.lock = null;
+        this.ticker = [];
+        this.note = null;
+        this.startedAt = null;
+        return was;
+    }
+    /** locked → paused (the user cancelled the analysis). The coin stays pulled up; nothing else locks. */
+    cancelAnalysis(_now) {
+        if (this.mode !== 'locked')
+            return false;
+        this.mode = 'paused';
+        return true;
+    }
+    /** locked/paused → scanning (the "resume scan" key). The released coin is barred; a short global cooldown. */
+    resume(now) {
+        if (this.mode === 'off')
+            return this.start(now);
+        if (this.mode === 'scanning')
+            return false;
+        if (this.lock)
+            this.barredUntil.set(this.lock.mint, now + this.cfg.coinCooldownS * 1000);
+        this.lock = null;
+        this.noLockUntil = now + this.cfg.postLockS * 1000;
+        this.mode = 'scanning';
+        return true;
+    }
+    /** Feed the latest observations (the feed rows + the open token). Cheap; keeps a short ring per coin. */
+    observe(obs, now) {
+        for (const o of obs) {
+            if (!o.mint)
+                continue;
+            this.latest.set(o.mint, o);
+            this.seenAt.set(o.mint, now);
+            const ring = this.rings.get(o.mint) ?? [];
+            const last = ring[ring.length - 1];
+            if (!last || o.t > last.t) {
+                ring.push({ t: o.t, liq: o.liq, holders: o.holders });
+                while (ring.length > RING_MAX || (ring.length > 1 && o.t - ring[0].t > this.cfg.windowMs * 1.5))
+                    ring.shift();
+                this.rings.set(o.mint, ring);
+            }
+        }
+        // forget coins nobody has shown us for a while (bounded memory)
+        if (this.latest.size > MAX_MINTS || this.seenAt.size > MAX_MINTS) {
+            for (const [m, t] of this.seenAt)
+                if (now - t > FORGET_MS || this.latest.size > MAX_MINTS) {
+                    this.seenAt.delete(m);
+                    this.latest.delete(m);
+                    this.rings.delete(m);
+                }
+        }
+    }
+    /** Invocations in the last hour (overall and for one coin), and when the next slot frees. */
+    usage(now, mint) {
+        this.invocations = this.invocations.filter((x) => now - x.t < HOUR);
+        const coin = mint ? this.invocations.filter((x) => x.mint === mint).length : 0;
+        const full = this.invocations.length >= this.cfg.maxAiPerHour;
+        return {
+            hour: this.invocations.length, hourCap: this.cfg.maxAiPerHour, coin, coinCap: this.cfg.maxAiPerCoin,
+            nextFreeInMs: full && this.invocations.length ? Math.max(0, HOUR - (now - this.invocations[0].t)) : null,
+        };
+    }
+    canInvoke(now, mint) {
+        const u = this.usage(now, mint);
+        return u.hour < u.hourCap && u.coin < u.coinCap;
+    }
+    /** Score one observed coin with its ring (exposed for the ticker/tests). */
+    score(mint) {
+        const o = this.latest.get(mint);
+        return o ? scoreCoin(o, this.rings.get(mint), this.cfg) : null;
+    }
+    /** Score everything, update the ticker, and return at most one decision. */
+    tick(now, ctx = { analystBusy: false }) {
+        if (this.mode === 'off')
+            return null;
+        const scored = [];
+        for (const [m, o] of this.latest) {
+            if (!pos(o.liq) || o.liq < this.cfg.minLiqUsd)
+                continue;
+            scored.push(scoreCoin(o, this.rings.get(m), this.cfg));
+        }
+        this.scanned = scored.length;
+        scored.sort((a, b) => b.score - a.score || b.hits.length - a.hits.length || (a.mint < b.mint ? -1 : 1));
+        this.ticker = scored.filter((s) => !s.veto && s.score > 0).slice(0, this.cfg.tickerSize);
+        if (this.mode === 'paused') {
+            this.note = 'analysis cancelled · R resume scan · Z stop';
+            return null;
+        }
+        if (this.mode === 'locked' && this.lock) {
+            // NO-HOP: only the locked coin is ever considered here, whatever else scores higher.
+            const lock = this.lock;
+            const o = this.latest.get(lock.mint);
+            if (!o)
+                return null;
+            const cur = scoreCoin(o, this.rings.get(lock.mint), this.cfg);
+            lock.liveScore = cur.score;
+            if (ctx.analystBusy) {
+                this.note = 'reading…';
+                return null;
+            }
+            const wait = lock.lastReadAt + this.cfg.refreshS * 1000 - now;
+            if (wait > 0) {
+                this.note = `next read ≥ ${Math.ceil(wait / 1000)}s`;
+                return null;
+            }
+            const curIds = cur.hits.map((h) => h.id);
+            const moved = materialMove(lock.lastRead, o, lock.lastHits, curIds, this.cfg);
+            if (!moved.length) {
+                this.note = 'holding · data flat since last read';
+                return null;
+            }
+            if (!this.canInvoke(now, lock.mint)) {
+                this.note = this.capNote(now, lock.mint);
+                return null;
+            }
+            this.invocations.push({ t: now, mint: lock.mint });
+            lock.lastReadAt = now;
+            lock.lastRead = o;
+            lock.lastHits = curIds;
+            lock.reads += 1;
+            lock.moved = moved;
+            this.note = null;
+            return { kind: 'refresh', mint: lock.mint, symbol: lock.symbol, moved, question: refreshQuestion(moved) };
+        }
+        // SCANNING
+        if (this.startedAt !== null && now - this.startedAt < this.cfg.warmupS * 1000) {
+            this.note = `warming up ${Math.ceil((this.cfg.warmupS * 1000 - (now - this.startedAt)) / 1000)}s`;
+            return null;
+        }
+        if (now < this.noLockUntil) {
+            this.note = `cooldown ${Math.ceil((this.noLockUntil - now) / 1000)}s`;
+            return null;
+        }
+        // The UI is busy (a ticket, an overlay, an editor, a half-typed question): never pull a coin up now.
+        if (ctx.holdLock) {
+            this.note = 'holding: you are busy';
+            return null;
+        }
+        let capped = null;
+        const pick = scored.find((s) => {
+            if (!s.exciting)
+                return false;
+            if ((this.barredUntil.get(s.mint) ?? 0) > now)
+                return false;
+            if (!this.canInvoke(now, s.mint)) {
+                capped ??= s.mint;
+                return false;
+            }
+            return true;
+        });
+        if (!pick) {
+            this.note = capped ? this.capNote(now, capped) : null;
+            return null;
+        }
+        const o = this.latest.get(pick.mint);
+        this.invocations.push({ t: now, mint: pick.mint });
+        this.mode = 'locked';
+        this.lock = {
+            mint: pick.mint, symbol: pick.symbol, at: now, score: pick.score, hits: pick.hits, liveScore: pick.score,
+            lastReadAt: now, lastRead: o, lastHits: pick.hits.map((h) => h.id), reads: 1, moved: [],
+        };
+        this.note = null;
+        return { kind: 'lock', mint: pick.mint, symbol: pick.symbol, score: pick.score, hits: pick.hits, question: lockQuestion(pick.score, pick.hits) };
+    }
+    capNote(now, mint) {
+        const u = this.usage(now, mint);
+        if (u.hour >= u.hourCap)
+            return `ai cap ${u.hour}/${u.hourCap} per hour${u.nextFreeInMs !== null ? ` · next in ${Math.ceil(u.nextFreeInMs / 60_000)}m` : ''}`;
+        return `coin ai cap ${u.coin}/${u.coinCap} per hour`;
+    }
+}

package/dist/packages/cli/src/scan/observe.js

@@ -0,0 +1,64 @@
+import { DS_TOKEN_CACHE_NS } from "../live/flow.js";
+/** Default cap on observed rows per pass: excitement needs volume, so the top 5m-volume rows. */
+export const OBSERVE_MAX = 120;
+function txns(get, mint) {
+    if (!get)
+        return { m5: null, h1: null };
+    let hit;
+    try {
+        hit = get(DS_TOKEN_CACHE_NS, mint);
+    }
+    catch {
+        return { m5: null, h1: null };
+    }
+    const pair = hit?.value?.pair;
+    const ok = (b) => (b && Number.isFinite(b.buys) && Number.isFinite(b.sells) ? { buys: b.buys, sells: b.sells } : null);
+    return { m5: ok(pair?.txns?.m5), h1: ok(pair?.txns?.h1) };
+}
+/**
+ * A cheap signature of the scan inputs: when it is unchanged the loop skips rebuilding observations
+ * (calm-mode CPU). Row count + newest fetch time + the open token's last load + verdict count.
+ */
+export function observeSig(src) {
+    let maxT = 0;
+    for (const r of src.rows)
+        if (r.fetchedAt !== null && r.fetchedAt > maxT)
+            maxT = r.fetchedAt;
+    return `${src.rows.length}:${maxT}:${src.token?.mint ?? ''}:${src.token?.updatedAt ?? 0}:${src.token?.candles.length ?? 0}:${src.larp?.size ?? 0}`;
+}
+/** One observation per eligible feed row, plus the open token (merged when it is also a row). */
+export function buildObservations(src) {
+    const max = src.max ?? OBSERVE_MAX;
+    const eligible = src.rows.filter((r) => !r.skeleton && !r.fixture && !!r.mint && r.liq !== null && r.liq >= src.minLiqUsd);
+    eligible.sort((a, b) => (b.vol5m ?? 0) - (a.vol5m ?? 0));
+    const out = new Map();
+    for (const r of eligible.slice(0, max)) {
+        const tx = txns(src.cacheGet, r.mint);
+        out.set(r.mint, {
+            mint: r.mint, symbol: r.symbol, t: r.fetchedAt ?? src.now,
+            price: r.price, vol5m: r.vol5m, vol1h: r.vol1h, vol6h: r.vol6h, vol24: r.vol24,
+            liq: r.liq, holders: r.holders, ageMin: r.ageMin, m5: tx.m5, h1: tx.h1,
+            candles: null, larp: src.larp?.get(r.mint)?.verdict ?? null, mintAuth: r.mintAuth, freezeAuth: r.freezeAuth,
+        });
+    }
+    const v = src.token;
+    if (v && v.mint) {
+        const row = out.get(v.mint);
+        const tx = row ? { m5: row.m5, h1: row.h1 } : txns(src.cacheGet, v.mint);
+        const px = src.livePrice?.(v.mint) ?? v.price;
+        if (row || (v.liq !== null && v.liq >= src.minLiqUsd)) {
+            out.set(v.mint, {
+                mint: v.mint, symbol: v.symbol, t: Math.max(row?.t ?? 0, v.updatedAt ?? 0) || src.now,
+                price: px ?? row?.price ?? null,
+                vol5m: row?.vol5m ?? null, vol1h: row?.vol1h ?? null, vol6h: row?.vol6h ?? null, vol24: row?.vol24 ?? v.vol24,
+                liq: v.liq ?? row?.liq ?? null, holders: v.holders ?? row?.holders ?? null, ageMin: v.ageMin ?? row?.ageMin ?? null,
+                m5: tx.m5, h1: tx.h1,
+                // the open token's candles are already on screen — the only candles the scan ever reads
+                candles: v.candles.length ? v.candles : null,
+                larp: src.larp?.get(v.mint)?.verdict ?? null,
+                mintAuth: v.mintAuth ?? row?.mintAuth ?? null, freezeAuth: v.freezeAuth ?? row?.freezeAuth ?? null,
+            });
+        }
+    }
+    return [...out.values()];
+}

package/dist/packages/cli/src/scan/ui.js

@@ -0,0 +1,98 @@
+// dexterm AI SCAN MODE (task-1324) — per-run scan UI state and the two one-line strips it draws on
+// row 1 (the blank band under the header, so no screen layout moves):
+//   - list screens: the SCANNING ticker — state, coins scanned, the top scores with their triggers;
+//   - the locked coin's token screen: WHY IT TRIGGERED — reasons, score, when, reads, next read, keys.
+// Rendering only; the decisions live in engine.ts and the loop in main.ts.
+import { clock, mix } from '../../../tui/src/index.js';
+import { cleanText } from "../screener/rows.js";
+import { ScanEngine } from "./engine.js";
+/** How often the loop runs a scan tick, and the forced recompute when inputs did not change. */
+export const SCAN_TICK_MS = 2_000;
+export const SCAN_RECOMPUTE_MS = 10_000;
+/** The analyst UI actions a scan session may request: NONE (observe-only). */
+export const SCAN_ACTION_TYPES = Object.freeze([]);
+export function makeScanUi(cfg = {}) {
+    return { engine: new ScanEngine(cfg), sig: '', lastTickAt: 0, lastComputeAt: 0, session: null, blocked: [], returnTo: null };
+}
+export const MODE_LABEL = { off: 'OFF', scanning: 'SCANNING', locked: 'LOCKED', paused: 'PAUSED' };
+const SHORT = { vol: 'vol', flow: 'flow', fresh: 'fresh', breakout: 'brk', liq: 'liq', holders: 'hold' };
+/** `◉ SCAN LOCKED $WIF` — the header's running indicator (state.ts headerModel). */
+export function scanIndicator(scan) {
+    const e = scan.engine;
+    const sym = e.lock ? ` $${cleanText(e.lock.symbol, 12)}` : '';
+    return `◉ AI SCAN ${MODE_LABEL[e.mode]}${sym}`;
+}
+function band(c) {
+    const t = c.theme;
+    const bg = mix(t.bg, t.ai, 0.14);
+    c.fill(0, 1, c.w, 1, ' ', { bg });
+    c.noRain(0, 1, c.w, 1);
+    return bg;
+}
+/** The SCANNING ticker on row 1 of the list screens. `ai` = the meter text (`ai 1/8 per h`). */
+export function renderScanTicker(c, scan, ai) {
+    const e = scan.engine;
+    if (!e.on)
+        return;
+    const t = c.theme;
+    const bg = band(c);
+    const end = c.w - 1;
+    let x = c.text(1, 1, '◉ AI SCAN ', { fg: t.ai, bg, b: true });
+    x = c.text(x, 1, MODE_LABEL[e.mode], { fg: e.mode === 'scanning' ? t.up : t.warn, bg, b: true }, end - x);
+    if (e.lock)
+        x = c.text(x + 1, 1, `$${cleanText(e.lock.symbol, 12)} · read ${e.lock.reads}`, { fg: t.text, bg, b: true }, end - x - 1);
+    x = c.text(x + 1, 1, `· ${e.scanned} coins`, { fg: t.muted, bg }, end - x - 1);
+    const right = ` ${e.note ? e.note + ' · ' : ''}${ai} · ${e.mode === 'scanning' ? 'Z stop' : 'R resume · Z stop'} `;
+    const rightX = Math.max(x + 2, end - right.length);
+    if (!e.ticker.length)
+        c.text(x + 2, 1, e.mode === 'scanning' ? 'watching… nothing scores yet' : '', { fg: t.dim, bg, i: true }, rightX - x - 3);
+    for (const s of e.ticker) {
+        if (x + 12 > rightX)
+            break;
+        x = c.text(x, 1, '  │ ', { fg: t.dim, bg }, rightX - x);
+        x = c.text(x, 1, `$${cleanText(s.symbol, 10)} `, { fg: t.text, bg }, rightX - x);
+        x = c.text(x, 1, String(s.score), { fg: s.exciting ? t.warn : t.muted, bg, b: s.exciting }, rightX - x);
+        if (s.hits.length)
+            x = c.text(x + 1, 1, s.hits.map((h) => SHORT[h.id]).join('·'), { fg: t.dim, bg }, rightX - x - 1);
+    }
+    c.text(rightX, 1, right, { fg: e.note && /cap/.test(e.note) ? t.warn : t.dim, bg }, end - rightX + 1);
+}
+/** WHY IT TRIGGERED on row 1 of the locked coin's token screen. */
+export function renderScanWhy(c, scan, _ai, now, timeZone) {
+    const e = scan.engine;
+    const lock = e.lock;
+    if (!lock)
+        return;
+    const t = c.theme;
+    const bg = band(c);
+    const end = c.w - 1;
+    let x = c.text(1, 1, '◉ AI SCAN ', { fg: t.ai, bg, b: true });
+    x = c.text(x, 1, MODE_LABEL[e.mode], { fg: e.mode === 'locked' ? t.up : t.warn, bg, b: true });
+    if (e.mode === 'paused')
+        x = c.text(x + 1, 1, '· analysis cancelled', { fg: t.warn, bg });
+    x = c.text(x + 1, 1, '· WHY IT TRIGGERED', { fg: t.ai, bg, b: true });
+    x = c.text(x + 1, 1, clock(new Date(lock.at), timeZone), { fg: t.muted, bg });
+    x = c.text(x + 1, 1, `· score ${lock.score}${lock.liveScore !== lock.score ? ` (now ${lock.liveScore})` : ''} ·`, { fg: t.warn, bg, b: true });
+    const keys = e.mode === 'paused' ? 'R resume · Z stop' : 'esc cancel · R resume · Z stop';
+    const sinceRead = Math.max(0, Math.round((now - lock.lastReadAt) / 1000));
+    // The analyst meter is already in the header; the strip keeps the read status + keys short so the
+    // reasons — the point of the strip — get the room.
+    const right = `read ${lock.reads} (${sinceRead}s ago)${e.note ? ' · ' + e.note : ''} · ${keys}`;
+    const room = Math.max(30, end - x - 3 - right.length);
+    // Full reasons while they fit; the rest by trigger id so the user still sees every trigger that fired.
+    let why = '';
+    const rest = [];
+    for (const h of lock.hits) {
+        const next = why ? `${why} · ${h.reason}` : h.reason;
+        if (!rest.length && next.length <= room)
+            why = next;
+        else
+            rest.push(h.id);
+    }
+    if (rest.length)
+        why = `${why}${why ? ' ' : ''}+ ${rest.join(', ')}`;
+    const wx = c.text(x + 1, 1, why, { fg: t.text, bg }, room);
+    const rx = Math.max(wx + 2, end - right.length);
+    if (rx < end)
+        c.text(rx, 1, right, { fg: t.dim, bg }, end - rx + 1);
+}