dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/cli/src/screener/filter.js

@@ -0,0 +1,241 @@
+const F = (key, kind, label, get) => ({ key, kind, label, get });
+/**
+ * Own-property lookup for the alias tables below. User text indexes these tables, and a plain
+ * `table[key]` would hand back inherited members for `__proto__`, `constructor`, `toString`, …
+ * (a function where a string was expected, which is how `__proto__:yes` once crashed the TUI).
+ */
+function own(table, key) {
+    return Object.hasOwn(table, key) ? table[key] : undefined;
+}
+/** Canonical fields; FIELD_ALIASES maps the spellings people type onto them. */
+export const FIELDS = [
+    F('vol24', 'usd', 'volume 24h', (r) => r.vol24),
+    F('vol6h', 'usd', 'volume 6h', (r) => r.vol6h),
+    F('vol1h', 'usd', 'volume 1h', (r) => r.vol1h),
+    F('vol5m', 'usd', 'volume 5m', (r) => r.vol5m),
+    F('liq', 'usd', 'liquidity', (r) => r.liq),
+    F('mcap', 'usd', 'market cap', (r) => r.mcap),
+    F('fdv', 'usd', 'FDV', (r) => r.fdv),
+    F('price', 'price', 'price', (r) => r.price),
+    F('age', 'age', 'age', (r) => r.ageMin),
+    F('holders', 'num', 'holders', (r) => r.holders),
+    F('buys', 'num', 'buys 24h', (r) => r.buys),
+    F('sells', 'num', 'sells 24h', (r) => r.sells),
+    F('org', 'num', 'organic score', (r) => r.org),
+    F('top10', 'pct', 'top-10 share', (r) => r.top10),
+    F('dev', 'pct', 'dev share', (r) => r.dev),
+    F('lplocked', 'pct', 'LP locked', (r) => r.lpLocked),
+    F('bundled', 'pct', 'bundled', (r) => r.bundled),
+    F('snipers', 'num', 'snipers', (r) => r.snipers),
+    F('m5', 'pct', 'change 5m', (r) => r.chg.m5),
+    F('h1', 'pct', 'change 1h', (r) => r.chg.h1),
+    F('h6', 'pct', 'change 6h', (r) => r.chg.h6),
+    F('h24', 'pct', 'change 24h', (r) => r.chg.h24),
+];
+const FIELD_ALIASES = {
+    vol: 'vol24', volume: 'vol24', v24: 'vol24', v6h: 'vol6h', v1h: 'vol1h', v5m: 'vol5m',
+    liquidity: 'liq', lp: 'liq', marketcap: 'mcap', cap: 'mcap', mc: 'mcap',
+    holder: 'holders', h: 'holders', organic: 'org', score: 'org',
+    top: 'top10', 'top-10': 'top10', devpct: 'dev', locked: 'lplocked', lplock: 'lplocked', bundle: 'bundled', sniper: 'snipers',
+    chg5m: 'm5', '5m': 'm5', chg1h: 'h1', '1h': 'h1', chg6h: 'h6', '6h': 'h6', chg24: 'h24', chg24h: 'h24', '24h': 'h24', change: 'h24',
+};
+const FIELD_BY_KEY = new Map(FIELDS.map((f) => [f.key, f]));
+export function fieldSpec(name) {
+    const k = name.toLowerCase();
+    return FIELD_BY_KEY.get(k) ?? FIELD_BY_KEY.get(own(FIELD_ALIASES, k) ?? '');
+}
+const TAG_ALIASES = { chain: 'chain', launchpad: 'launchpad', lp: 'launchpad', pad: 'launchpad', flag: 'flag', flags: 'flag', verified: 'verified', sus: 'sus' };
+const LAUNCHPAD_ALIASES = {
+    pump: 'pump.fun', pumpfun: 'pump.fun', 'pump.fun': 'pump.fun', dbc: 'dbc', 'meteora-dbc': 'dbc',
+    raydium: 'raydium', ray: 'raydium', meteora: 'meteora', met: 'meteora', bonk: 'bonk', letsbonk: 'bonk', unknown: 'unknown',
+};
+const FLAG_ALIASES = {
+    mint: 'MINT', freeze: 'FREEZE', top10: 'TOP10', dev: 'DEV', bundle: 'BUNDLE', bundled: 'BUNDLE', lp: 'LP', clean: 'clean', none: 'clean',
+};
+const OPS = { '>': '>', '>=': '>=', '<': '<', '<=': '<=', '=': '=', '==': '=', '!=': '!=' };
+export function tokenize(src) {
+    const out = [];
+    const re = /\s+|(>=|<=|!=|==|>|<|=)|(:)|(!)|([^\s<>=!:]+)/gy;
+    let m;
+    while ((m = re.exec(src)) !== null) {
+        if (m[0].length === 0)
+            break;
+        const at = m.index + 1;
+        if (m[1])
+            out.push({ kind: 'op', text: m[1], at });
+        else if (m[2])
+            out.push({ kind: 'colon', text: ':', at });
+        else if (m[3])
+            out.push({ kind: 'not', text: '!', at });
+        else if (m[4])
+            out.push({ kind: 'word', text: m[4], at });
+    }
+    return out;
+}
+const MONEY_UNITS = { k: 1e3, m: 1e6, b: 1e9 };
+const AGE_UNITS = { s: 1 / 60, m: 1, min: 1, h: 60, hr: 60, d: 1440, w: 10080, mo: 43200 };
+/** Parse a value for a field kind. Returns a number or an error string. */
+export function parseValue(raw, kind) {
+    let s = raw.toLowerCase().replace(/,/g, '');
+    if (kind === 'usd' || kind === 'price')
+        s = s.replace(/^\$/, '');
+    if (kind === 'pct')
+        s = s.replace(/%$/, '');
+    const m = s.match(/^(-?\d+(?:\.\d+)?)([a-z]*)$/);
+    if (!m)
+        return `bad number "${raw}"`;
+    const n = Number(m[1]);
+    const unit = m[2];
+    if (kind === 'age') {
+        if (!unit)
+            return `"${raw}" needs an age unit (s, m, h, d, w, mo)`;
+        const mult = own(AGE_UNITS, unit);
+        if (mult === undefined)
+            return `unknown age unit "${unit}" in "${raw}" (use s, m, h, d, w, mo)`;
+        return n * mult;
+    }
+    if (!unit)
+        return n;
+    if (kind === 'pct')
+        return `unknown suffix "${unit}" in "${raw}" (percentages take an optional %)`;
+    const mult = own(MONEY_UNITS, unit);
+    if (mult === undefined)
+        return `unknown unit "${unit}" in "${raw}" (use K, M, B)`;
+    return n * mult;
+}
+export function parseFilter(src) {
+    const toks = tokenize(src);
+    const clauses = [];
+    const fail = (error, at) => ({ ok: false, error, at });
+    let i = 0;
+    while (i < toks.length) {
+        const t = toks[i];
+        const next = toks[i + 1];
+        if (t.kind === 'op')
+            return fail(`"${t.text}" has no field in front of it`, t.at);
+        if (t.kind === 'colon')
+            return fail(`":" has no tag in front of it (try chain:, launchpad:, flag:)`, t.at);
+        if (t.kind === 'not') {
+            if (!next || next.kind !== 'word' || toks[i + 2]?.kind !== 'colon')
+                return fail(`"!" must be followed by a tag like !launchpad:pump`, t.at);
+            const r = parseTag(toks, i + 1, true);
+            if (typeof r === 'string')
+                return fail(r, next.at);
+            clauses.push(r.clause);
+            i = r.next;
+            continue;
+        }
+        // word
+        if (next?.kind === 'op') {
+            const field = fieldSpec(t.text);
+            if (!field)
+                return fail(`unknown field "${t.text}" (try ${FIELDS.slice(0, 7).map((f) => f.key).join(', ')}, …)`, t.at);
+            const op = own(OPS, next.text);
+            if (!op)
+                return fail(`unknown operator "${next.text}"`, next.at);
+            const val = toks[i + 2];
+            if (!val || val.kind !== 'word')
+                return fail(`"${t.text} ${next.text}" needs a value`, val ? val.at : next.at + next.text.length);
+            const v = parseValue(val.text, field.kind);
+            if (typeof v === 'string')
+                return fail(`${v} for ${field.key}`, val.at);
+            clauses.push({ kind: 'cmp', field, op, value: v, raw: `${field.key} ${op} ${val.text}` });
+            i += 3;
+            continue;
+        }
+        if (next?.kind === 'colon') {
+            const r = parseTag(toks, i, false);
+            if (typeof r === 'string')
+                return fail(r, t.at);
+            clauses.push(r.clause);
+            i = r.next;
+            continue;
+        }
+        clauses.push({ kind: 'text', value: t.text.toLowerCase(), raw: t.text });
+        i += 1;
+    }
+    const preds = clauses.map(clausePredicate);
+    const predicate = (r) => preds.every((p) => p(r));
+    return { ok: true, filter: { text: clauses.map((c) => (c.kind === 'tag' && c.not ? '!' : '') + c.raw).join('  '), clauses, predicate } };
+}
+function parseTag(toks, i, not) {
+    const name = toks[i];
+    const val = toks[i + 2];
+    const tag = own(TAG_ALIASES, name.text.toLowerCase());
+    if (!tag)
+        return `unknown tag "${name.text}:" (chain, launchpad, flag, verified, sus)`;
+    if (!val || val.kind !== 'word')
+        return `"${name.text}:" needs a value`;
+    const v = val.text.toLowerCase();
+    let value = v;
+    if (tag === 'chain') {
+        if (v !== 'solana' && v !== 'sol')
+            return `chain:${val.text} is not supported (solana only)`;
+        value = 'solana';
+    }
+    else if (tag === 'launchpad') {
+        const lp = own(LAUNCHPAD_ALIASES, v);
+        if (!lp)
+            return `unknown launchpad "${val.text}" (pump, dbc, raydium, meteora, bonk)`;
+        value = lp;
+    }
+    else if (tag === 'flag') {
+        const f = own(FLAG_ALIASES, v);
+        if (!f)
+            return `unknown flag "${val.text}" (mint, freeze, top10, dev, bundle, lp, clean)`;
+        value = f;
+    }
+    else {
+        if (!['yes', 'no', 'true', 'false', '1', '0'].includes(v))
+            return `${tag}: takes yes or no`;
+        value = v === 'yes' || v === 'true' || v === '1' ? 'yes' : 'no';
+    }
+    return { clause: { kind: 'tag', tag, value, not, raw: `${tag}:${value}` }, next: i + 3 };
+}
+function cmp(a, op, b) {
+    switch (op) {
+        case '>': return a > b;
+        case '>=': return a >= b;
+        case '<': return a < b;
+        case '<=': return a <= b;
+        case '=': return a === b;
+        case '!=': return a !== b;
+    }
+}
+export function clausePredicate(c) {
+    if (c.kind === 'cmp') {
+        const { field, op, value } = c;
+        return (r) => { const v = field.get(r); return v !== null && v !== undefined && !Number.isNaN(v) && cmp(v, op, value); };
+    }
+    if (c.kind === 'text') {
+        const q = c.value;
+        return (r) => r.symbol.toLowerCase().includes(q) || r.name.toLowerCase().includes(q);
+    }
+    let p;
+    switch (c.tag) {
+        case 'chain':
+            p = () => true;
+            break;
+        case 'launchpad':
+            p = (r) => r.launchpad === c.value;
+            break;
+        case 'flag':
+            p = c.value === 'clean' ? (r) => r.flags.length === 0 : (r) => r.flags.includes(c.value);
+            break;
+        case 'verified':
+            p = (r) => r.verified === (c.value === 'yes');
+            break;
+        case 'sus':
+            p = (r) => r.sus === (c.value === 'yes');
+            break;
+        // parseTag only emits the tags above; a clause built by hand with a stray tag matches nothing
+        default: p = () => false;
+    }
+    return c.not ? (r) => !p(r) : p;
+}
+/** Apply a parsed filter (or none) to rows, keeping order. */
+export function applyFilter(rows, f) {
+    if (!f || f.clauses.length === 0)
+        return rows.slice();
+    return rows.filter(f.predicate);
+}

package/dist/packages/cli/src/screener/presets.js

@@ -0,0 +1,80 @@
+import { gate, COLUMN_SOURCES, FEATURE_SOURCES } from '../../../data/src/index.js';
+import { parseFilter } from "./filter.js";
+/** Jupiter's "runner" criteria (SPEC §4.2): mcap ≥ $1M, liq ≥ $100K, holders ≥ 1K, organic ≥ 75 within 24h of launch. */
+export const RUNNER_FILTER = 'mcap >= 1M  liq >= 100K  holders >= 1000  org >= 75  age < 24h';
+/**
+ * Trench feed (task-1311, QA M4): what a Solana memecoin trader wants first — fresh pump.fun and
+ * young memecoins over a sane liquidity floor. `verified:no` drops the Jupiter-verified set (blue
+ * chips, wrapped assets, tokenized stocks and stablecoins), which stay reachable under Trending /
+ * Top traded / All. `live` folds the PumpPortal new-pairs stream in so fresh launches surface.
+ */
+export const TRENCH_FILTER = 'verified:no  liq >= 5K';
+/**
+ * Graduating — keyless approximation (task-1356 Tier 6). The real signal is bonding-curve progress
+ * (COLUMN_SOURCES 'bonding', D-08), which needs a keyed launch source. Keyless we approximate "a
+ * bonding-curve launch closing on graduation" by the mcap band a pump.fun/bonk/dbc coin sits in as it
+ * fills (roughly $30K–$120K), still young, with a real-ish pool forming. It is an APPROXIMATION, not the
+ * true graduation %, and the UI says so; when 'bonding' is served the preset swaps to the real column.
+ */
+export const GRADUATING_APPROX_FILTER = 'launchpad:pump  mcap >= 30K  mcap <= 120K  liq >= 4K  age < 24h';
+export const PRESETS = [
+    { id: 'trench', label: 'Trench', feeds: ['trending', 'organic', 'recent'], baked: TRENCH_FILTER, live: true },
+    { id: 'trending', label: 'Trending', feeds: ['trending'] },
+    { id: 'runners', label: 'Runners', feeds: ['trending', 'organic', 'recent'], baked: RUNNER_FILTER },
+    { id: 'organic', label: 'Organic', feeds: ['organic'] },
+    { id: 'graduating', label: 'Graduating', feeds: ['recent'], baked: GRADUATING_APPROX_FILTER, live: true, gate: { id: 'bonding', of: 'column' }, approx: 'approx' },
+    { id: 'smart', label: 'Smart money', feeds: ['trending'], gate: { id: 'top-traders', of: 'feature' } },
+    // task-1303 feed switcher: the remaining Jupiter / DexScreener nets, keyless and always available.
+    { id: 'traded', label: 'Top traded', feeds: ['traded'] },
+    { id: 'new', label: 'New', feeds: ['recent'], live: true },
+    { id: 'boosted', label: 'Boosted', feeds: ['boosted'] },
+    { id: 'all', label: 'All', feeds: ['trending', 'organic', 'traded', 'recent', 'boosted'], live: true },
+];
+export function presetSpec(id) {
+    return PRESETS.find((p) => p.id === id || p.label.toLowerCase() === id.toLowerCase());
+}
+const CAPTION = { 'needs-key': 'needs key', degraded: 'degraded', disabled: 'off', ok: '' };
+/** Availability of every preset. Without a registry (fixtures mode) everything is on for the demo. */
+export function presetViews(health) {
+    return PRESETS.map((p) => {
+        if (!health)
+            return { id: p.id, label: p.label, available: true, caption: p.approx ? p.approx : null, approx: !!p.approx };
+        if (p.pending)
+            return { id: p.id, label: p.label, available: false, caption: p.pending };
+        // An approximation preset is served keyless by its baked filter over keyless fields, so it is always
+        // selectable. The dexterm filter grammar has no real bonding-% field at this tier, so the preset is
+        // ALWAYS the approximation (the `gate` only marks the future upgrade to a real column); the 'approx'
+        // caption therefore stays visible even when available, so the UI never implies the keyed signal.
+        if (p.approx)
+            return { id: p.id, label: p.label, available: true, caption: p.approx, approx: true };
+        if (!p.gate)
+            return { id: p.id, label: p.label, available: true, caption: null };
+        const spec = p.gate.of === 'column' ? COLUMN_SOURCES[p.gate.id] : FEATURE_SOURCES[p.gate.id];
+        const g = gate(health, p.gate.id, spec);
+        return { id: p.id, label: p.label, available: g.available, caption: g.available ? null : CAPTION[g.state] || g.state };
+    });
+}
+const bakedCache = new Map();
+export function bakedFilter(p) {
+    if (!p.baked)
+        return null;
+    let f = bakedCache.get(p.baked);
+    if (!f) {
+        const r = parseFilter(p.baked);
+        if (!r.ok)
+            throw new Error(`preset ${p.id} has a bad baked filter: ${r.error}`);
+        f = r.filter;
+        bakedCache.set(p.baked, f);
+    }
+    return f;
+}
+/** Next/previous selectable preset from `cur` (wraps; disabled presets are skipped). */
+export function cyclePreset(views, cur, step) {
+    const i = Math.max(0, views.findIndex((v) => v.id === cur));
+    for (let k = 1; k <= views.length; k++) {
+        const v = views[(i + step * k + views.length * k) % views.length];
+        if (v.available)
+            return v.id;
+    }
+    return cur;
+}

package/dist/packages/cli/src/screener/rows.js

@@ -0,0 +1,146 @@
+/** How many placeholder rows the screener shows while the first live fetch is in flight (task-1323). */
+export const SKELETON_ROWS = 12;
+/** Placeholder rows for the empty-feed first paint (task-1323): shimmer bars, no data, no mint. */
+export function skeletonRows(n = SKELETON_ROWS) {
+    const bars = ['░░░░░', '░░░░', '░░░░░░', '░░░'];
+    return Array.from({ length: n }, (_, i) => ({
+        mint: '', symbol: bars[i % bars.length], name: i === 0 ? 'loading feed…' : '', launchpad: 'unknown',
+        price: null, mcap: null, mcapFlagged: false, fdv: null, liq: null, vol24: null, vol6h: null, vol1h: null, vol5m: null,
+        ageMin: null, holders: null, holders24: null, holdersChgPct: null, chg: { m5: null, h1: null, h6: null, h24: null },
+        spark: undefined, buys: null, sells: null, org: null, top10: null, dev: null, lpLocked: null, mintAuth: null, freezeAuth: null,
+        snipers: null, bundled: null, flags: [], verified: false, sus: false, bonding: null, pair: null, sources: [], stale: true,
+        fetchedAt: null, aiNote: null, image: null, skeleton: true,
+    }));
+}
+/** Risk flags from the audit fields, same thresholds as the prototype fixtures. */
+export function deriveFlags(r) {
+    const flags = [];
+    if (r.mintAuth)
+        flags.push('MINT');
+    if (r.freezeAuth)
+        flags.push('FREEZE');
+    if (r.top10 !== null && r.top10 > 35)
+        flags.push('TOP10');
+    if (r.dev !== null && r.dev > 5)
+        flags.push('DEV');
+    if (r.bundled !== null && r.bundled > 15)
+        flags.push('BUNDLE');
+    if (r.lpLocked !== null && r.lpLocked < 50)
+        flags.push('LP');
+    return flags;
+}
+export function fromFixture(tk) {
+    const verdict = tk.flags.length >= 2 ? 'avoid: holder structure fragile' : tk.org >= 60 ? 'watch: organic flow, decent spread' : 'speculative: thin, mostly bots';
+    return {
+        mint: tk.mint, symbol: tk.symbol, name: tk.name, launchpad: tk.launchpad,
+        price: tk.price, mcap: tk.mcap, mcapFlagged: false, fdv: tk.fdv, liq: tk.liq,
+        vol24: tk.vol24, vol6h: tk.vol24 * 0.3, vol1h: tk.vol24 * 0.06, vol5m: tk.vol24 * 0.005,
+        ageMin: tk.ageMin, holders: tk.holders, holders24: tk.holders24, holdersChgPct: null,
+        chg: { ...tk.chg }, spark: tk.spark, buys: tk.buys, sells: tk.sells, org: tk.org,
+        top10: tk.top10, dev: tk.dev, lpLocked: tk.lpLocked, mintAuth: tk.mintAuth, freezeAuth: tk.freezeAuth,
+        snipers: tk.snipers, bundled: tk.bundled, flags: tk.flags, verified: false, sus: false, bonding: tk.bonding, pair: null,
+        sources: ['fixture'], stale: false, fetchedAt: null, aiNote: verdict, image: null, fixture: tk,
+    };
+}
+/**
+ * Terminal safety only (CL-06 firewalling is D-12): drop control, bidi and zero-width characters,
+ * replace glyphs the cell canvas cannot place in one column (East Asian wide, emoji) with ▯, cap length.
+ */
+export function cleanText(s, max = 48) {
+    if (!s)
+        return '';
+    let out = '';
+    for (const ch of s) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20 || (cp >= 0x7f && cp <= 0x9f))
+            continue;
+        if (cp === 0x200b || cp === 0x200c || cp === 0x200d || cp === 0x2060 || cp === 0xfeff)
+            continue; // zero-width
+        if ((cp >= 0x200e && cp <= 0x200f) || (cp >= 0x202a && cp <= 0x202e) || (cp >= 0x2066 && cp <= 0x2069))
+            continue; // bidi
+        if ((cp >= 0x0300 && cp <= 0x036f) || (cp >= 0xfe00 && cp <= 0xfe0f) || (cp >= 0x1f3fb && cp <= 0x1f3ff))
+            continue; // combining / variation / skin tone
+        out += isWide(cp) ? '▯' : ch;
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/** Code points that terminals render two columns wide (EAW W/F ranges) or as emoji. */
+export function isWide(cp) {
+    return (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0x303e) || (cp >= 0x3041 && cp <= 0x33ff)
+        || (cp >= 0x3400 && cp <= 0x4dbf) || (cp >= 0x4e00 && cp <= 0x9fff) || (cp >= 0xa000 && cp <= 0xa4cf)
+        || (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xf900 && cp <= 0xfaff) || (cp >= 0xfe30 && cp <= 0xfe4f)
+        || (cp >= 0xff00 && cp <= 0xff60) || (cp >= 0xffe0 && cp <= 0xffe6) || (cp >= 0x1f000 && cp <= 0x1faff)
+        || (cp >= 0x20000 && cp <= 0x3fffd);
+}
+/**
+ * The 24h trend implied by the window deltas: the price 24h/6h/1h/5m ago and now, interpolated
+ * on a linear time axis. Not a tick history (that is D-17's history table); it is the path the
+ * reported changes describe, which is what the 24H TREND column claims.
+ */
+export function impliedSpark(price, chg, cells = 16) {
+    if (price === null || !(price > 0))
+        return undefined;
+    const anchors = [];
+    const at = (min, c) => { if (c !== null && c > -100)
+        anchors.push([min, price / (1 + c / 100)]); };
+    at(1440, chg.h24);
+    at(360, chg.h6);
+    at(60, chg.h1);
+    at(5, chg.m5);
+    anchors.push([0, price]);
+    if (anchors.length < 2)
+        return undefined;
+    const span = anchors[0][0];
+    const out = [];
+    for (let i = 0; i < cells; i++) {
+        const t = span - (i / (cells - 1)) * span; // minutes ago
+        let k = 0;
+        while (k < anchors.length - 2 && anchors[k + 1][0] >= t)
+            k++;
+        const [t0, p0] = anchors[k], [t1, p1] = anchors[k + 1];
+        const f = t0 === t1 ? 1 : (t0 - t) / (t0 - t1);
+        out.push(p0 + (p1 - p0) * Math.min(1, Math.max(0, f)));
+    }
+    return out;
+}
+export function fromSnapshot(r, nowMs) {
+    const { token, pair, stats, audit } = r;
+    const createdAt = token.createdAt ?? pair.createdAt;
+    const chg = { m5: pair.priceChange.m5, h1: pair.priceChange.h1, h6: pair.priceChange.h6, h24: pair.priceChange.h24 };
+    const price = pair.priceUsd > 0 ? pair.priceUsd : r.price?.usdPrice ?? null;
+    const launchpad = token.launchpad;
+    // SPEC §3.6: pump.fun / PumpSwap pools burn LP by design; RugCheck (D-06) fills the rest.
+    const lpLocked = audit?.lpLockedPct ?? (launchpad === 'pump.fun' ? 100 : null);
+    const base = {
+        mintAuth: audit?.mintAuthority ?? null,
+        freezeAuth: audit?.freezeAuthority ?? null,
+        top10: audit?.top10Pct ?? null,
+        dev: audit?.devPct ?? null,
+        bundled: null,
+        lpLocked,
+    };
+    const fetchedAt = Math.max(pair.fetchedAt, token.fetchedAt, stats?.fetchedAt ?? 0);
+    // MCAP: the D-06 cross-source rule (larger of DexScreener/Jupiter when they agree within 5x, else
+    // DexScreener's number flagged); FDV as the last fallback.
+    const mcap = r.mcap ? r.mcap.value : pair.mcap ?? pair.fdv;
+    return {
+        mint: r.mint, symbol: cleanText(token.symbol, 12) || '?', name: cleanText(token.name, 40), launchpad,
+        price,
+        mcap, mcapFlagged: r.mcap?.flagged ?? false, fdv: pair.fdv, liq: pair.liquidityUsd,
+        vol24: pair.volume.h24, vol6h: pair.volume.h6, vol1h: pair.volume.h1, vol5m: pair.volume.m5,
+        ageMin: createdAt ? Math.max(0, (nowMs - createdAt) / 60000) : null,
+        // Jupiter's holderChange is a percentage, not a count: keep the two apart so the UI never shows "+-1.02".
+        holders: stats?.holderCount ?? null, holders24: null, holdersChgPct: stats?.holders24hDelta ?? null,
+        chg, spark: r.sparkline ?? impliedSpark(price, chg),
+        buys: pair.txns.h24?.buys ?? null, sells: pair.txns.h24?.sells ?? null,
+        org: stats?.organicScore ?? null,
+        ...base,
+        snipers: null,
+        flags: deriveFlags(base),
+        verified: token.verified, sus: token.sus, bonding: null, pair: pair.pairAddress || null,
+        sources: r.sources, stale: r.stale, fetchedAt: fetchedAt || null, aiNote: null,
+        image: typeof token.image === 'string' && /^https?:\/\//i.test(token.image) ? token.image : null,
+    };
+}

package/dist/packages/cli/src/screener/rug.js

@@ -0,0 +1,50 @@
+// task-1361: p(rug) for a screener row, from the pre-registered H1-v0.1 heuristic in @dexterm/packs
+// (rug-model.ts). Zero model cost, zero requests: it reads the numbers already on the row. It is a MODEL
+// OUTPUT, not a fact: every surface that shows it names the model and how old the row's data is.
+// H1 is a hand-written additive heuristic (not learned); a trained v1 only replaces it once the recorder
+// has enough labelled outcomes and `dexterm backtest` says it is better (AI-SUITE-DESIGN §4.3).
+import { H1_FLAG_THRESHOLD, h1Model } from '../../../packs/src/index.js';
+/** The model the screener column scores with. */
+export const SCREENER_RUG_MODEL = h1Model();
+/** Short label for captions / the sort menu: `H1-v0.1 heuristic`. */
+export const RUG_MODEL_LABEL = `${SCREENER_RUG_MODEL.id} ${SCREENER_RUG_MODEL.kind}`;
+/** The canonical feature vector from what the screener row carries (nulls where no source said). */
+export function rugFeaturesFromRow(r) {
+    return {
+        liquidity_usd: r.liq,
+        mcap: r.mcap,
+        age_sec: r.ageMin === null ? null : r.ageMin * 60,
+        top_holders_pct: r.top10,
+        dev_pct: r.dev,
+        organic_score: r.org,
+        holder_count: r.holders,
+        mint_auth_enabled: r.mintAuth,
+        freeze_auth_enabled: r.freezeAuth,
+        has_pool: r.liq === null ? null : r.liq > 0,
+        is_verified: null,
+    };
+}
+/**
+ * p(rug) in [0.02, 0.98] for a row with market data, else null: a skeleton row, or one where no source
+ * has reported liquidity, cap, age or an audit yet (the heuristic would only be scoring its own defaults).
+ */
+export function rugP(r) {
+    if (r.skeleton)
+        return null;
+    if (r.liq === null && r.mcap === null && r.ageMin === null && r.mintAuth === null && r.freezeAuth === null)
+        return null;
+    return SCREENER_RUG_MODEL.score(rugFeaturesFromRow(r));
+}
+/** `0.45` — two decimals, never a percent (it reads as a probability, which is what the backtest measures). */
+export function fmtRugP(p) {
+    return p.toFixed(2);
+}
+/** The model's own flag line: at or above it the heuristic calls the token a likely rug. */
+export const RUG_FLAG_THRESHOLD = H1_FLAG_THRESHOLD;
+/** `42s` / `4m` / `3h` since the row's data was fetched; null when the row never recorded a fetch time. */
+export function rugDataAge(r, now) {
+    if (r.fetchedAt === null || !Number.isFinite(r.fetchedAt))
+        return null;
+    const s = Math.max(0, Math.round((now - r.fetchedAt) / 1000));
+    return s < 60 ? `${s}s` : s < 3600 ? `${Math.floor(s / 60)}m` : s < 86_400 ? `${Math.floor(s / 3600)}h` : `${Math.floor(s / 86_400)}d`;
+}

package/dist/packages/cli/src/screener/sort.js

@@ -0,0 +1,52 @@
+import { RUG_MODEL_LABEL, rugP } from "./rug.js";
+export const SORT_KEYS = [
+    { key: 'vol', label: 'vol 24h', defaultDir: 'desc', get: (r) => r.vol24 },
+    { key: 'liq', label: 'liquidity', defaultDir: 'desc', get: (r) => r.liq },
+    { key: 'mcap', label: 'mcap', defaultDir: 'desc', get: (r) => r.mcap },
+    { key: 'price', label: 'price', defaultDir: 'desc', get: (r) => r.price },
+    { key: 'age', label: 'age', defaultDir: 'asc', get: (r) => r.ageMin },
+    { key: 'm5', label: '5m change', defaultDir: 'desc', get: (r) => r.chg.m5 },
+    { key: 'h1', label: '1h change', defaultDir: 'desc', get: (r) => r.chg.h1 },
+    { key: 'h6', label: '6h change', defaultDir: 'desc', get: (r) => r.chg.h6 },
+    { key: 'h24', label: '24h change', defaultDir: 'desc', get: (r) => r.chg.h24 },
+    { key: 'holders', label: 'holders', defaultDir: 'desc', get: (r) => r.holders },
+    { key: 'org', label: 'organic score', defaultDir: 'desc', get: (r) => r.org },
+    { key: 'top10', label: 'top-10 share', defaultDir: 'asc', get: (r) => r.top10 },
+    // task-1361: the H1-v0.1 heuristic's p(rug) (a model output, see screener/rug.ts); safest first.
+    { key: 'rug', label: `p(rug) ${RUG_MODEL_LABEL}`, defaultDir: 'asc', get: (r) => rugP(r) },
+];
+export const DEFAULT_SORT = { key: 'vol', dir: 'desc' };
+export function sortSpec(key) {
+    return SORT_KEYS.find((s) => s.key === key);
+}
+/** Parse `--sort key[:asc|desc]`. */
+export function parseSortArg(s) {
+    const [k, d] = s.split(':');
+    const spec = sortSpec(k);
+    if (!spec)
+        throw new Error(`unknown sort key ${k} (expected ${SORT_KEYS.map((x) => x.key).join('|')})`);
+    if (d !== undefined && d !== 'asc' && d !== 'desc')
+        throw new Error(`sort direction must be asc or desc, got ${d}`);
+    return { key: spec.key, dir: d ?? spec.defaultDir };
+}
+/** Stable sort; rows without the value go last whichever direction is chosen. */
+export function sortRows(rows, key, dir) {
+    const spec = sortSpec(key);
+    if (!spec)
+        return rows.slice();
+    const sign = dir === 'desc' ? -1 : 1;
+    return rows
+        .map((r, i) => ({ r, i, v: spec.get(r) }))
+        .sort((a, b) => {
+        const an = a.v === null || a.v === undefined || Number.isNaN(a.v);
+        const bn = b.v === null || b.v === undefined || Number.isNaN(b.v);
+        if (an && bn)
+            return a.i - b.i;
+        if (an)
+            return 1;
+        if (bn)
+            return -1;
+        return a.v === b.v ? a.i - b.i : (a.v - b.v) * sign;
+    })
+        .map((x) => x.r);
+}