dexterm-cli 0.1.6 → 0.1.7

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

@@ -0,0 +1,191 @@
+// @dexterm/data/basis (task-1537): THE price-basis module. Market cap is the default way dexterm shows and talks
+// about a coin ("entered at $69.7K, exited at $264.9K, 3.8x"); USD price per token is the alternative when the user
+// sets `display.priceMode: "price"` in ~/.dexterm/config.json (or for one run: `--price` / DEXTERM_PRICE_BASIS=price).
+//
+// One resolver (`resolveBasis`) decides what a price slot shows, one formatter pair (`fmtCap` / `fmtUsdPrice`) draws it,
+// and `basisLanguage` is the paragraph every model-facing prompt carries so the agents speak the same basis as the UI.
+//
+// Supply rule (shared with the PnL card, task-1518): a market cap the data source reports, else price × a supply that
+// is KNOWN: the source's own mcap ÷ price, the recorded FDV ÷ price, or pump.fun's fixed 1B for a pump.fun coin. A
+// supply is never guessed: with none, the slot shows the price and says why (`fallback`).
+//
+// Pure: no I/O, no imports. Display and wording only; nothing here is read by the signer, caps, plans or tickets.
+// JSON outputs keep BOTH `price` and `mcap` fields always (`withMcap`); only the human-facing text switches.
+export const PRICE_BASES = ['mcap', 'price'];
+/** The default basis everywhere (UI, CLI text, agent language) when config, flag and env say nothing. */
+export const DEFAULT_PRICE_BASIS = 'mcap';
+/** One-run override: `DEXTERM_PRICE_BASIS=price dexterm …` (the CLI flags `--price` / `--mcap` set it too). */
+export const PRICE_BASIS_ENV = 'DEXTERM_PRICE_BASIS';
+export function isPriceBasis(v) { return v === 'mcap' || v === 'price'; }
+/** The one-run override from the environment, or null when unset / not a basis. */
+export function envPriceBasis(env) {
+    const v = env?.[PRICE_BASIS_ENV]?.trim().toLowerCase();
+    return isPriceBasis(v) ? v : null;
+}
+/**
+ * The basis in effect: the one-run override (flag/env) wins, then the config value (`display.priceMode`), then mcap.
+ * A config written before task-1537 is migrated (custom v4 → v5), so `configured` is the user's saved choice.
+ */
+export function pickBasis(configured, env) {
+    return envPriceBasis(env) ?? (isPriceBasis(configured) ? configured : DEFAULT_PRICE_BASIS);
+}
+// ------------------------------------------------------------------------------------------------ formatters
+const SUB = '₀₁₂₃₄₅₆₇₈₉';
+const trim = (s) => (s.includes('.') ? s.replace(/0+$/, '').replace(/\.$/, '') : s);
+/**
+ * A market cap (or any large USD amount) in sentences, rows and lines: `$950`, `$69.7K`, `$264.9K`, `$1.2M`, `$1.23M`,
+ * `$4.5B`. K keeps one decimal, M / B / T two, trailing zeros dropped; the unit is promoted AFTER rounding so 999 960
+ * reads `$1M`, never `$1000K`. Null / non-finite → '—'. (Narrow table cells use the 3-significant-digit tui form.)
+ */
+export function fmtCap(n) {
+    if (n === null || n === undefined || !Number.isFinite(n))
+        return '—';
+    const sign = n < 0 ? '-' : '';
+    const a = Math.abs(n);
+    if (a < 999.5)
+        return `${sign}$${a < 1 ? trim(a.toFixed(2)) : String(Math.round(a))}`;
+    const units = ['K', 'M', 'B', 'T'];
+    let u = 0, v = a / 1000;
+    while (u < units.length - 1 && v >= 1000) {
+        v /= 1000;
+        u++;
+    }
+    const dp = (i) => (i === 0 ? 1 : 2);
+    let r = Number(v.toFixed(dp(u)));
+    if (r >= 1000 && u < units.length - 1) {
+        u++;
+        r = Number((r / 1000).toFixed(dp(u)));
+    }
+    return `${sign}$${trim(r.toFixed(dp(u)))}${units[u]}`;
+}
+/**
+ * A USD price per token, the usual small-number form with subscript zeros: `$0.0₄123`, `$0.0123`, `$1.234`, `$142.50`.
+ * Matches `fmtPrice` in @dexterm/tui (tested), so a price reads the same on every surface.
+ */
+export function fmtUsdPrice(p) {
+    if (p === null || p === undefined || !Number.isFinite(p))
+        return '—';
+    if (p < 0)
+        return `-${fmtUsdPrice(-p)}`;
+    if (p >= 1000)
+        return `$${p.toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
+    if (p >= 1)
+        return `$${p.toFixed(p >= 100 ? 2 : 3)}`;
+    if (p >= 0.01)
+        return `$${p.toFixed(4)}`;
+    const m = p.toFixed(12).match(/^0\.(0*)(\d+)/);
+    if (!m)
+        return `$${p}`;
+    const zeros = m[1].length;
+    const digits = m[2].replace(/0+$/, '').slice(0, 4) || '0';
+    if (zeros < 3)
+        return `$0.${m[1]}${digits}`;
+    return `$0.0${String(zeros).split('').map((c) => SUB[Number(c)]).join('')}${digits}`;
+}
+/** An x-multiple between two levels of the same basis: `3.8x`, `0.42x`, `12x`. Null when either side is unusable. */
+export function fmtX(from, to) {
+    if (from === null || from === undefined || to === null || to === undefined || !Number.isFinite(from) || !Number.isFinite(to) || from <= 0 || to < 0)
+        return null;
+    const x = to / from;
+    return `${x >= 10 ? x.toFixed(0) : x >= 1 ? x.toFixed(1) : x.toFixed(2)}x`;
+}
+// ------------------------------------------------------------------------------------------------ supply + resolver
+/** pump.fun mints a fixed 1,000,000,000 supply per coin (none is minted later), so its market cap is price × 1B. */
+export const PUMP_FUN_SUPPLY = 1_000_000_000;
+const pos = (n) => n !== null && n !== undefined && Number.isFinite(n) && n > 0;
+/**
+ * The KNOWN supply for a coin, or null. Order: an explicit supply; the source's mcap ÷ price; recorded FDV ÷ price
+ * (a fully diluted cap on a non-pump coin, and the source says so); pump.fun's fixed 1B for a pump.fun coin (by
+ * launchpad, or a `…pump` mint with no launchpad). Never guessed.
+ */
+export function knownSupply(h) {
+    const via = h.via ? ` (${h.via})` : '';
+    if (pos(h.supply))
+        return { tokens: h.supply, source: `recorded supply${via}` };
+    if (pos(h.mcap) && pos(h.price) && Number.isFinite(h.mcap / h.price))
+        return { tokens: h.mcap / h.price, source: `market cap ÷ price${via}` };
+    if (pos(h.fdv) && pos(h.price) && Number.isFinite(h.fdv / h.price))
+        return { tokens: h.fdv / h.price, source: `recorded FDV ÷ price${via}` };
+    const mint = h.mint ?? '';
+    if (h.launchpad === 'pump.fun' || ((!h.launchpad || h.launchpad === 'unknown') && mint.endsWith('pump')))
+        return { tokens: PUMP_FUN_SUPPLY, source: 'pump.fun fixed supply' };
+    return null;
+}
+/** Why a slot that wanted market cap shows a price instead (said next to the number, never hidden). */
+export const NO_SUPPLY_REASON = 'market cap unknown: no supply recorded, showing price';
+/**
+ * THE resolver every screen, line, table and prompt calls: the headline figure for one price slot.
+ * `price` is the USD (or the caller's unit) price at that moment; `mcap` a cap the source reports for the SAME moment.
+ * A historical price (an entry fill) is turned into a cap with a known supply (`supply` / FDV / pump.fun 1B).
+ */
+export function resolveBasis(want, o) {
+    const price = Number.isFinite(o.price) ? o.price : null;
+    const sup = knownSupply(o);
+    const mcap = pos(o.mcap) && !pos(o.supply) ? o.mcap : price !== null && sup ? price * sup.tokens : null;
+    const pText = fmtUsdPrice(price);
+    if (want === 'mcap' && mcap !== null) {
+        return { want, basis: 'mcap', price, mcap, text: fmtCap(mcap), both: price !== null ? `${fmtCap(mcap)} mcap (${pText})` : `${fmtCap(mcap)} mcap`, fallback: null, supply: sup };
+    }
+    const fallback = want === 'mcap' && price !== null ? NO_SUPPLY_REASON : null;
+    const both = mcap !== null ? `${pText} (mcap ${fmtCap(mcap)})` : fallback ? `${pText} (${fallback})` : pText;
+    return { want, basis: 'price', price, mcap, text: pText, both, fallback, supply: sup };
+}
+/** A level in a sentence: `$69.7K` (mcap) or `$0.0₄697` (price, or the mcap fallback with `· supply unknown`). */
+export function fmtLevel(want, o) {
+    const v = resolveBasis(want, o);
+    return v.fallback ? `${v.text} (price; supply unknown)` : v.text;
+}
+/**
+ * An entry → exit (or → now) sentence in the basis: mcap `entered at $69.7K, exited at $264.9K (3.8x)`, price
+ * `entered at $0.0₄697, exited at $0.0₃265 (3.8x)`. Both levels use the same supply, so the multiple is the same in
+ * either basis. `exit` null with `now` → `…, now $120K (1.7x)`.
+ */
+export function entryExitLine(want, o) {
+    const sup = knownSupply({ ...o, mcap: o.mcap, price: o.price });
+    const asCap = want === 'mcap' && sup !== null;
+    const f = (p) => (p === null || p === undefined || !Number.isFinite(p) ? '—' : asCap ? fmtCap(p * sup.tokens) : fmtUsdPrice(p));
+    const end = o.exit !== null && o.exit !== undefined ? o.exit : o.now ?? null;
+    const verb = o.exit !== null && o.exit !== undefined ? 'exited at' : 'now';
+    const x = fmtX(o.entry, end);
+    const tail = want === 'mcap' && !asCap ? ' (prices: supply unknown)' : '';
+    return `entered at ${f(o.entry)}${end !== null ? `, ${verb} ${f(end)}` : ''}${x ? ` (${x})` : ''}${tail}`;
+}
+/**
+ * JSON keeps BOTH numbers: return `obj` with a market-cap twin for each price key (`pairs` maps price key → cap key,
+ * e.g. `{ price: 'mcap', entryPrice: 'entryMcap' }`), from a known supply, else null. A cap already on the object (a
+ * source-reported one) is kept. Never removes or changes a price field.
+ */
+export function withMcap(obj, pairs, h) {
+    const sup = knownSupply(h);
+    const out = { ...obj };
+    for (const [k, name] of Object.entries(pairs)) {
+        if (typeof out[name] === 'number' && Number.isFinite(out[name]))
+            continue;
+        const p = obj[k];
+        out[name] = typeof p === 'number' && Number.isFinite(p) && sup ? p * sup.tokens : null;
+    }
+    return out;
+}
+// ------------------------------------------------------------------------------------------------ agent language
+/** A short hint for tool descriptions (MCP, agent tool table) so external agents also speak the basis. */
+export const MCAP_FIELD_HINT = 'Every price field has a market-cap twin (`mcap`, `entryMcap`, …; null when the supply is unknown). basis: talk in market cap by default (cap at entry, cap now, targets/stops as cap levels, x-multiples); use the price fields only when the user\'s display.priceMode is "price" or the cap is null.';
+/**
+ * The paragraph every model-facing prompt carries (the chat assistant, the autotrade candidate agent, help answers).
+ * Follows the basis AT RUN TIME: tests assert both texts.
+ */
+export function basisLanguage(basis) {
+    if (basis === 'price') {
+        return [
+            'PRICE BASIS: USD PRICE (the user set display.priceMode = "price").',
+            'Talk in USD price per token: the price at entry, the price now, targets and stops as price levels (with x-multiples).',
+            'Quote market cap only as a secondary number in brackets ("$0.0₄697 (mcap $69.7K)"). Tools return both `price` and `mcap` fields.',
+        ].join(' ');
+    }
+    return [
+        'PRICE BASIS: MARKET CAP (the default; display.priceMode = "mcap").',
+        'Talk about a coin the way traders do, in market cap: the cap at entry and the cap now ("in at $69.7K, now $264.9K, 3.8x"),',
+        'targets and stops as market-cap levels ("take profit at $500K, stop at $40K"), and moves as x-multiples.',
+        'Use the `mcap` / `*Mcap` fields tools return; write caps as $69.7K / $1.2M. A per-token price only in brackets when it helps,',
+        'or alone when the cap is null (the supply is unknown): then say "price only, supply unknown". Never invent a supply.',
+    ].join(' ');
+}

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

@@ -3,7 +3,10 @@
 // stale-while-revalidate, so the detail screen and the MCP tools share one
 // set of requests.
 import { TTL } from "./cache.js";
-const NS = { mint: 'rpc:mint', holders: 'rpc:holders', rug: 'rugcheck', pools: 'gt:pools', goplus: 'goplus', trades: 'gt:trades' };
+import { classifyHolder, EX_POOL_TAGS } from "./intel/holder-class.js";
+const NS = { mint: 'rpc:mint', holders: 'rpc:holders', ownerMeta: 'rpc:owner-meta', rug: 'rugcheck', pools: 'gt:pools', goplus: 'goplus', trades: 'gt:trades' };
+/** The program that owns an account (a pool, a curve PDA, a wallet) does not change: a week per owner. */
+const OWNER_META_TTL = 7 * 86_400_000;
 /** Pools for a mint change rarely; one lookup per hour per mint. */
 const POOLS_TTL = 3_600_000;
 /** The trades tape shares GeckoTerminal's 10/min bucket with the candles: refresh at most every 20 s per pool. */
@@ -51,7 +54,7 @@ export class TokenDetail {
         return this.cache.fetch(NS.holders, mint, async () => {
             const info = (await this.mintInfo(mint)).value;
             try {
-                return await this.pool.topHolders(mint, { info });
+                return await this.exPool(await this.pool.topHolders(mint, { info }));
             }
             catch (rpcErr) {
                 const agg = await this.aggregateHolders(mint, info).catch(() => null);
@@ -61,6 +64,54 @@ export class TokenDetail {
             }
         }, { ttlMs: TTL.holders, source: this.pool.primary.source });
     }
+    /**
+     * The HOLDERS panel's ex-pool rule (task-1367 `classifyHolder`) for every caller of `holders()` (the MCP
+     * `get_holders` / `get_dossier` concentration, the autotrade dossier, rug-check), task-1518. A top account whose
+     * owner is a pool, a bonding curve, a launch vault, a lock or the burn address is not a person's position: it gets
+     * `poolSide` (and `label: 'LP'` for a pool, curve or vault) and is left out of `top10Pct`. Without this, every young
+     * PumpSwap pool (the vault owner is the pool account) and every Meteora DAMM v2 pool (the global pool authority)
+     * read as one 80-95 % "holder". One extra getMultipleAccounts over the owners not yet known (no data, <= 20
+     * addresses, cached a week per owner: an account's program does not change), the same lookup the wallet-intel scan
+     * makes; when it fails, only the derived authorities and the pump.fun curve are recognised and every other owner
+     * stays counted (never hidden).
+     */
+    async exPool(h) {
+        if (h.aggregateOnly || !h.holders.length)
+            return h;
+        const owners = [...new Set(h.holders.map((x) => x.owner).filter((o) => !!o))];
+        const meta = new Map();
+        const misses = [];
+        for (const o of owners) {
+            const hit = this.cache.get(NS.ownerMeta, o);
+            if (hit)
+                meta.set(o, hit.value);
+            else
+                misses.push(o);
+        }
+        if (misses.length) {
+            try {
+                const got = await this.pool.accountMeta(misses);
+                // an address with no account yet can be created later: an hour for those, a week for accounts that exist
+                for (const [o, m] of got) {
+                    meta.set(o, m);
+                    this.cache.set(NS.ownerMeta, o, m, { ttlMs: m.exists ? OWNER_META_TTL : 3_600_000, source: this.pool.primary.source });
+                }
+            }
+            catch { /* counted, never hidden */ }
+        }
+        const holders = h.holders.map((x) => {
+            if (!x.owner || x.label)
+                return x;
+            const c = classifyHolder({ mint: h.mint, owner: x.owner, tokenAccounts: [x.tokenAccount], meta: meta.get(x.owner), cex: null, dev: null, poolRule: null, linked: null });
+            if (!EX_POOL_TAGS.has(c.tag))
+                return x;
+            return { ...x, ...(c.tag === 'POOL' || c.tag === 'CURVE' || c.tag === 'VAULT' ? { label: 'LP' } : {}), poolSide: { tag: c.tag, program: c.program, reason: c.reason } };
+        });
+        const sum = (xs) => Math.round(xs.reduce((s, x) => s + x.pct, 0) * 1000) / 1000;
+        const notCounted = new Set(['LP', 'cex', 'bridge']);
+        const counted = holders.filter((x) => !x.poolSide && !(x.label && notCounted.has(x.label))).slice(0, 10);
+        return { ...h, holders, top10Pct: h.top10Pct === null ? null : sum(counted), top10PctRaw: h.top10Pct === null ? null : sum(holders.slice(0, 10)) };
+    }
     /** Build an aggregate-only TopHolders from the keyless Jupiter holder data; null when unavailable. */
     async aggregateHolders(mint, info) {
         if (!this.holdersAggregate)

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

@@ -28,27 +28,13 @@ export * from "./credits.js";
 export * from "./budget.js";
 export * from "./watchlist.js";
 export * from "./paper.js";
-export * from "./trade/caps.js";
 export * from "./trade/bridge.js";
-export * from "./trade/swap-build.js";
-export * from "./trade/rpc-exec.js";
-export * from "./trade/executor.js";
 export * from "./trade/link-store.js";
 export * from "./trade/tx-decode.js";
-export * from "./trade/sol-usd.js";
 export * from "./trade/kill-switch.js";
-export * from "./trade/token-delta.js";
 // task-1443: the paper agent desk + its rendezvous (agents paper-trade inside an armed mandate; never sign/send).
 export * from "./trade/agent/paper-desk.js";
 export * from "./trade/agent/rendezvous.js";
-export * from "./trade/signer/protocol.js";
-export * from "./trade/signer/service.js";
-export * from "./trade/signer/host.js";
-export * from "./trade/signer/client.js";
-export * from "./trade/signer/probe-builder.js";
-export * from "./trade/signer/fast-wallet.js";
-export * from "./trade/signer/sol-usd-feed.js";
-export { parseSignerArgs, buildSignerService } from "./trade/signer/main.js";
 export * from "./larp/links.js";
 export * from "./larp/safe-fetch.js";
 export * from "./larp/evidence.js";

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 = {};