dexterm-cli 0.1.5 → 0.1.7

package/dist/packages/data/src/larp/x-account.js

@@ -0,0 +1,316 @@
+// LARP detector — keyless X account lookup (task-1471). Read-only, no login, no cookies, no X API key.
+//
+// Why a fallback chain: measured 2026-10-19 (handoff evidence x-repro.md), FxTwitter answers `404 User not found`
+// for accounts that exist on roughly one call in six, a missing handle gets a 302 to the project's GitHub page on
+// some calls, and "suspended" is reported only some of the time. vxtwitter serves a cached copy (its own
+// `fetched_on`, up to about a day old). X's own oEmbed endpoint says exists / missing and the canonical handle, and
+// nothing else. The X syndication timeline (429 / empty) and the Nitter-class mirrors (offline, suspended, or a 200
+// "offline" page) gave nothing usable and are not in the chain.
+//
+// So no single answer is a verdict: `active` needs one source returning the profile; `suspended` needs a source
+// saying so; `not_found` needs TWO independent sources (vxtwitter AND oEmbed) saying missing; anything else is
+// `unavailable`. Every field that could not be read is listed in `unavailable` and is never guessed.
+//
+// Politeness: one handle per user action, at most five calls, a per-host spacing limiter, a TTL cache, and a
+// circuit breaker per source (the shared HealthRegistry: 3 failures or 2× 429 in a minute → degraded, 30 s..10 min
+// backoff). The bio is untrusted text: the caller firewalls it before it reaches a model.
+import { HealthRegistry } from "../health.js";
+import { systemClock } from "../clock.js";
+import { parseHttpUrl } from "./links.js";
+const RESERVED = new Set(['i', 'home', 'search', 'intent', 'hashtag', 'share', 'explore', 'settings', 'messages', 'notifications', 'login', 'signup', 'tos', 'privacy', 'compose']);
+const HANDLE = /^[A-Za-z0-9_]{1,15}$/;
+const X_HOSTS = new Set(['x.com', 'twitter.com', 'mobile.twitter.com', 'mobile.x.com', 'fxtwitter.com', 'vxtwitter.com', 'fixupx.com', 'nitter.net']);
+const SOURCE_ID = { fxtwitter: 'fxtwitter', vxtwitter: 'vxtwitter', 'x-oembed': 'x-oembed' };
+const HOST = { fxtwitter: 'api.fxtwitter.com', vxtwitter: 'api.vxtwitter.com', 'x-oembed': 'publish.x.com' };
+/** Parse an advertised X link into its kind, handle and status id. Pure. */
+export function parseXLink(raw) {
+    const u = parseHttpUrl(raw);
+    if (!u)
+        return { kind: 'other', handle: null, statusId: null };
+    const host = u.hostname.toLowerCase().replace(/^www\./, '');
+    if (!X_HOSTS.has(host))
+        return { kind: 'other', handle: null, statusId: null };
+    const parts = u.pathname.split('/').filter(Boolean);
+    if (parts[0]?.toLowerCase() === 'i' && parts[1]?.toLowerCase() === 'communities')
+        return { kind: 'community', handle: null, statusId: null };
+    const h = parts[0] ?? '';
+    if (!HANDLE.test(h) || RESERVED.has(h.toLowerCase()))
+        return { kind: 'other', handle: null, statusId: null };
+    if (parts[1]?.toLowerCase() === 'status' && /^\d{1,25}$/.test(parts[2] ?? ''))
+        return { kind: 'status', handle: h, statusId: parts[2] };
+    return { kind: parts.length === 1 ? 'profile' : 'other', handle: h, statusId: null };
+}
+const json = (body) => {
+    try {
+        const v = JSON.parse(body);
+        return v && typeof v === 'object' ? v : null;
+    }
+    catch {
+        return null;
+    }
+};
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const str = (v) => (typeof v === 'string' && v ? v : null);
+const iso = (v) => { const t = typeof v === 'string' ? Date.parse(v) : NaN; return Number.isFinite(t) ? new Date(t).toISOString() : null; };
+const days = (now, at) => (at ? Math.max(0, Math.floor((now - Date.parse(at)) / 86_400_000)) : null);
+const bareHost = (raw) => { const u = raw ? parseHttpUrl(raw) : null; return u ? u.hostname.toLowerCase().replace(/^www\./, '') : null; };
+function mentionsToken(bio, ctx) {
+    const sym = (ctx.symbol ?? '').trim();
+    const name = (ctx.name ?? '').trim();
+    if (!sym && !name && !ctx.mint)
+        return null;
+    const b = bio.toLowerCase();
+    if (ctx.mint && bio.includes(ctx.mint))
+        return true;
+    if (sym.length >= 2 && new RegExp(`(^|[^a-z0-9])\\$?${sym.toLowerCase().replace(/[^a-z0-9]/g, '')}([^a-z0-9]|$)`).test(b))
+        return true;
+    if (name.length >= 3 && b.includes(name.toLowerCase()))
+        return true;
+    return false;
+}
+/** The lookup service: chain + cache + spacing + circuit breakers. One instance per process. */
+export class XAccountLookup {
+    fetchImpl;
+    clock;
+    health;
+    minIntervalMs;
+    ttlMs;
+    ttlUnavailableMs;
+    maxEntries;
+    cache = new Map();
+    lastCall = new Map();
+    constructor(opts) {
+        this.fetchImpl = opts.fetch;
+        this.clock = opts.clock ?? systemClock;
+        this.health = opts.health ?? new HealthRegistry({ clock: this.clock });
+        this.minIntervalMs = opts.minIntervalMs ?? 1000;
+        this.ttlMs = opts.ttlMs ?? 30 * 60_000;
+        this.ttlUnavailableMs = opts.ttlUnavailableMs ?? 10 * 60_000;
+        this.maxEntries = opts.maxEntries ?? 500;
+    }
+    /** Per-host spacing: calls to one host are serialized at least minIntervalMs apart. */
+    async spaced(host, fn) {
+        const prev = this.lastCall.get(host) ?? Promise.resolve();
+        let release;
+        const mine = new Promise((r) => { release = r; });
+        this.lastCall.set(host, prev.then(() => mine));
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            if (this.minIntervalMs > 0)
+                void this.clock.sleep(this.minIntervalMs).then(release);
+            else
+                release();
+        }
+    }
+    async get(source, endpoint, url, trace) {
+        const sid = SOURCE_ID[source];
+        if (!this.health.isAvailable(sid)) {
+            trace.push({ source, endpoint, status: null, result: 'skipped: circuit open (source degraded)', ms: 0 });
+            return null;
+        }
+        const t0 = this.clock.now();
+        try {
+            const r = await this.spaced(HOST[source], () => this.fetchImpl(url));
+            const ms = this.clock.now() - t0;
+            // 404 / 3xx are answers (a vote), not source failures; 429 and 5xx other than vxtwitter's suspended body are.
+            const failed = r.status === 0 || r.status === 429 || (r.status >= 500 && !/suspended/i.test(r.body));
+            this.health.record(sid, failed ? { ok: false, status: r.status, latencyMs: ms, error: `http ${r.status}` } : { ok: true, status: r.status, latencyMs: ms });
+            return { status: r.status, body: r.body, ms };
+        }
+        catch (e) {
+            const ms = this.clock.now() - t0;
+            this.health.record(sid, { ok: false, latencyMs: ms, error: e.message });
+            trace.push({ source, endpoint, status: null, result: `error: ${e.message}`.slice(0, 120), ms });
+            return null;
+        }
+    }
+    /** Look up the account behind an advertised X link. Never throws. */
+    async lookup(xUrl, ctx = {}) {
+        const link = parseXLink(xUrl);
+        const now = this.clock.now();
+        const key = `${link.handle?.toLowerCase() ?? xUrl}|${link.statusId ?? ''}|${(ctx.symbol ?? '').toLowerCase()}|${(ctx.name ?? '').toLowerCase()}|${ctx.mint ?? ''}|${bareHost(ctx.website) ?? ''}`;
+        const hit = this.cache.get(key);
+        if (hit && now - hit.at < (hit.report.status === 'unavailable' ? this.ttlUnavailableMs : this.ttlMs))
+            return { ...hit.report, cached: true };
+        const report = await this.uncached(xUrl, link, ctx);
+        this.cache.delete(key);
+        this.cache.set(key, { at: now, report });
+        while (this.cache.size > this.maxEntries)
+            this.cache.delete(this.cache.keys().next().value);
+        return report;
+    }
+    async uncached(url, link, ctx) {
+        const now = this.clock.now();
+        const trace = [];
+        const base = {
+            url, kind: link.kind, handle: link.handle, status: 'unavailable', screenName: null, id: null, renamed: null,
+            createdAt: null, ageDays: null, followers: null, following: null, tweets: null, lastPostAt: null, daysSinceLastPost: null,
+            bio: null, website: null, bioMentionsToken: null, linksSite: null, countsAsOf: null, countsSource: null,
+            unavailable: [], sources: trace, cached: false, fetchedAt: new Date(now).toISOString(),
+        };
+        if (!link.handle) {
+            base.unavailable = ['account (the X link is not an account or a post)'];
+            return base;
+        }
+        let h = link.handle;
+        // A status link: who wrote the post now. A different author means a renamed account or a borrowed post.
+        if (link.statusId) {
+            const r = await this.get('fxtwitter', 'status', `https://api.fxtwitter.com/${h}/status/${link.statusId}`, trace);
+            const j = r ? json(r.body) : null;
+            const author = str(j?.tweet?.author?.screen_name);
+            if (r)
+                trace.push({ source: 'fxtwitter', endpoint: 'status', status: r.status, result: author ? `post by @${author}` : `no post (${str(j?.message) ?? r.status})`, ms: r.ms });
+            if (author && author.toLowerCase() !== h.toLowerCase()) {
+                base.renamed = { from: h, to: author, evidence: `the linked post ${link.statusId} is now shown under @${author}` };
+                h = author;
+            }
+        }
+        let profile = null;
+        let suspended = false;
+        let missingVotes = 0;
+        const missingBy = [];
+        // 1) FxTwitter profile: fresh counts. A 404 is one vote only (measured false 404s).
+        const fx = await this.get('fxtwitter', 'profile', `https://api.fxtwitter.com/${h}`, trace);
+        if (fx) {
+            const j = json(fx.body);
+            const u = j?.user;
+            if (fx.status === 200 && u) {
+                profile = { screenName: str(u.screen_name), id: str(u.id), createdAt: iso(u.joined), followers: num(u.followers), following: num(u.following), tweets: num(u.tweets), bio: typeof u.description === 'string' ? u.description : null, website: str(u.website?.url), asOf: new Date(now).toISOString() };
+                trace.push({ source: 'fxtwitter', endpoint: 'profile', status: 200, result: 'profile', ms: fx.ms });
+            }
+            else if (str(j?.reason) === 'suspended') {
+                suspended = true;
+                trace.push({ source: 'fxtwitter', endpoint: 'profile', status: fx.status, result: 'suspended', ms: fx.ms });
+            }
+            else {
+                trace.push({ source: 'fxtwitter', endpoint: 'profile', status: fx.status, result: fx.status >= 300 && fx.status < 400 ? 'redirect (missing handle or error page)' : `no profile (${str(j?.message) ?? fx.status})`, ms: fx.ms });
+            }
+        }
+        // 2) vxtwitter: cached copy; says suspended / missing reliably in the probe.
+        if (!profile) {
+            const vx = await this.get('vxtwitter', 'profile', `https://api.vxtwitter.com/${h}`, trace);
+            if (vx) {
+                const j = json(vx.body);
+                if (vx.status === 200 && j && str(j.screen_name)) {
+                    const fetchedOn = num(j.fetched_on);
+                    profile = { screenName: str(j.screen_name), id: j.id === undefined || j.id === null ? null : String(j.id), createdAt: iso(j.created_at), followers: num(j.followers_count), following: num(j.following_count), tweets: num(j.tweet_count), bio: typeof j.description === 'string' ? j.description : null, website: null, asOf: fetchedOn ? new Date(fetchedOn * 1000).toISOString() : null };
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: 200, result: 'profile (cached copy)', ms: vx.ms });
+                }
+                else if (/suspended/i.test(str(j?.error) ?? '')) {
+                    suspended = true;
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: vx.status, result: 'suspended', ms: vx.ms });
+                }
+                else if (vx.status === 404) {
+                    missingVotes++;
+                    missingBy.push('vxtwitter');
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: 404, result: 'not found', ms: vx.ms });
+                }
+                else
+                    trace.push({ source: 'vxtwitter', endpoint: 'profile', status: vx.status, result: 'no answer', ms: vx.ms });
+            }
+        }
+        // 3) X oEmbed: exists vs missing (200 for a suspended account too).
+        let oembedExists = null;
+        if (!profile && !suspended) {
+            const oe = await this.get('x-oembed', 'oembed', `https://publish.x.com/oembed?url=${encodeURIComponent(`https://x.com/${h}`)}`, trace);
+            if (oe) {
+                const j = json(oe.body);
+                if (oe.status === 200 && j) {
+                    oembedExists = true;
+                    trace.push({ source: 'x-oembed', endpoint: 'oembed', status: 200, result: 'exists', ms: oe.ms });
+                }
+                else if (oe.status === 404) {
+                    oembedExists = false;
+                    missingVotes++;
+                    missingBy.push('x-oembed');
+                    trace.push({ source: 'x-oembed', endpoint: 'oembed', status: 404, result: 'not found', ms: oe.ms });
+                }
+                else
+                    trace.push({ source: 'x-oembed', endpoint: 'oembed', status: oe.status, result: 'no answer', ms: oe.ms });
+            }
+        }
+        // 4) Last post date (FxTwitter statuses), only for an account that exists.
+        let lastPostAt = null;
+        let postsRead = false;
+        if (profile) {
+            const st = await this.get('fxtwitter', 'statuses', `https://api.fxtwitter.com/2/profile/${h}/statuses`, trace);
+            const j = st ? json(st.body) : null;
+            const results = Array.isArray(j?.results) ? j.results : null;
+            if (st?.status === 200 && results) {
+                postsRead = true;
+                const times = results.map((r) => iso(r.created_at)).filter((t) => !!t).sort();
+                lastPostAt = times.at(-1) ?? null;
+                trace.push({ source: 'fxtwitter', endpoint: 'statuses', status: 200, result: `${results.length} recent posts`, ms: st.ms });
+            }
+            else if (st)
+                trace.push({ source: 'fxtwitter', endpoint: 'statuses', status: st.status, result: 'posts unavailable', ms: st.ms });
+        }
+        const out = { ...base };
+        if (profile) {
+            out.status = 'active';
+            Object.assign(out, {
+                screenName: profile.screenName, id: profile.id, createdAt: profile.createdAt, ageDays: days(now, profile.createdAt),
+                followers: profile.followers, following: profile.following, tweets: profile.tweets,
+                bio: profile.bio !== null ? profile.bio.slice(0, 280) : null, website: profile.website,
+                countsAsOf: profile.asOf, countsSource: trace.find((t) => t.endpoint === 'profile' && t.status === 200)?.source ?? null,
+                lastPostAt, daysSinceLastPost: days(now, lastPostAt),
+            });
+            // A posts list that came back empty for an account with zero tweets is "no posts", not missing.
+            if (postsRead && !lastPostAt && profile.tweets === 0)
+                out.daysSinceLastPost = null;
+            out.bioMentionsToken = profile.bio !== null ? mentionsToken(profile.bio, ctx) : null;
+            const site = bareHost(ctx.website);
+            if (site) {
+                const bioHit = (profile.bio ?? '').toLowerCase().includes(site);
+                const webHit = bareHost(profile.website) === site;
+                out.linksSite = bioHit || webHit ? true : (profile.website !== null || profile.bio !== null) ? false : null;
+            }
+        }
+        else if (suspended)
+            out.status = 'suspended';
+        else if (missingVotes >= 2)
+            out.status = 'not_found';
+        else if (oembedExists)
+            out.status = 'unavailable'; // exists per X, but no source returned the profile
+        const miss = [];
+        if (out.status !== 'active') {
+            if (out.status === 'unavailable')
+                miss.push(`account status (${missingBy.length ? `only ${missingBy.join(' + ')} said missing; ` : ''}no source returned the profile)`);
+        }
+        else {
+            if (out.createdAt === null)
+                miss.push('account created date');
+            if (out.followers === null)
+                miss.push('follower count');
+            if (out.following === null)
+                miss.push('following count');
+            if (out.tweets === null)
+                miss.push('post count');
+            if (!postsRead)
+                miss.push('last post date');
+            if (out.bio === null)
+                miss.push('bio');
+            if (ctx.website && out.linksSite === null)
+                miss.push('site cross-link');
+            if (out.bioMentionsToken === null && (ctx.symbol || ctx.name))
+                miss.push('bio mentions the token');
+        }
+        out.unavailable = miss;
+        return out;
+    }
+}
+/** Advertised handles per source, and whether they and the site's own X links agree. Pure. */
+export function xHandleAgreement(advertised, siteLinks) {
+    const handles = advertised.map((l) => ({ h: parseXLink(l.url), source: l.source })).filter((x) => x.h.handle).map((x) => ({ handle: x.h.handle, source: x.source }));
+    const distinct = [...new Set(handles.map((x) => x.handle.toLowerCase()))];
+    const siteHandles = siteLinks === null ? null : [...new Set(siteLinks.map((u) => parseXLink(u)).filter((x) => x.kind === 'profile' && x.handle).map((x) => x.handle.toLowerCase()))];
+    const siteLinksAdvertised = siteHandles === null || !distinct.length ? null : siteHandles.length === 0 ? false : siteHandles.some((s) => distinct.includes(s));
+    const agree = distinct.length === 0 ? null : distinct.length === 1 && (siteHandles === null || siteHandles.length === 0 || siteHandles.includes(distinct[0]));
+    const siteAgrees = !distinct.length || !siteHandles?.length ? null : siteHandles.some((s) => distinct.includes(s));
+    const note = distinct.length > 1 ? `sources advertise different X accounts: ${distinct.map((d) => `@${d}`).join(', ')}`
+        : agree === false && siteHandles?.length ? `the website links @${siteHandles.join(', @')} but the token lists @${distinct[0]}` : null;
+    return { handles, agree, siteAgrees, siteHandles, siteLinksAdvertised, note };
+}

package/dist/packages/data/src/store.js

@@ -10,15 +10,24 @@ export const MCAP_AGREE_RATIO = 5;
  * (or `fdv` when absent) can reflect only the Solana-side supply of bridged/wrapped
  * tokens. Take the larger of DexScreener and Jupiter `mcap` when they agree within
  * 5x; otherwise keep DexScreener's number and flag the row. One side only: use it.
+ *
+ * task-1518: when both sources' prices are known, Jupiter's cap is first moved to DexScreener's price (its implied
+ * supply x the newer price), so "agree" compares the SUPPLY each source counts, which is what the rule is about. A
+ * Jupiter record served from the cache can be minutes old: on a coin that ran 6x since, the raw caps are 6x apart
+ * while both count the same supply. Comparing the raw caps flagged every fast runner (and the autotrade thesis-split
+ * exit sold it, "market-cap sources 1.0x apart"), and on a coin that dumped it showed the stale, larger cap.
  */
-export function resolveMcap(ds, jupMcap) {
+export function resolveMcap(ds, jupMcap, prices) {
     const d = ds ? (ds.mcap ?? ds.fdv) : null;
     const j = jupMcap ?? null;
-    const pos = (n) => n !== null && Number.isFinite(n) && n > 0;
+    const pos = (n) => n !== null && n !== undefined && Number.isFinite(n) && n > 0;
     if (pos(d) && pos(j)) {
-        const ratio = Math.max(d, j) / Math.min(d, j);
+        const dp = prices?.dexscreener, jp = prices?.jupiter;
+        // Jupiter's cap at DexScreener's (newer) price: its supply x the price the row shows.
+        const jNow = pos(dp) && pos(jp) ? j * (dp / jp) : j;
+        const ratio = Math.max(d, jNow) / Math.min(d, jNow);
         if (ratio <= MCAP_AGREE_RATIO) {
-            return j > d ? { value: j, basis: 'jupiter', flagged: false, dexscreener: d, jupiter: j } : { value: d, basis: 'dexscreener', flagged: false, dexscreener: d, jupiter: j };
+            return jNow > d ? { value: jNow, basis: 'jupiter', flagged: false, dexscreener: d, jupiter: j } : { value: d, basis: 'dexscreener', flagged: false, dexscreener: d, jupiter: j };
         }
         return { value: d, basis: 'dexscreener', flagged: true, dexscreener: d, jupiter: j };
     }
@@ -104,7 +113,7 @@ export class Store {
                 price: p,
                 sources,
                 stale: ds.stale.has(mint) || jup.stale.has(mint) || price.stale.has(mint),
-                mcap: resolveMcap(d?.pair, j?.pair.mcap),
+                mcap: resolveMcap(d?.pair, j?.pair.mcap, { dexscreener: d?.pair.priceUsd, jupiter: j?.pair.priceUsd }),
             });
         }
         const latencyMs = {};