dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,261 @@
+// dexterm — the customization layer's app adapter (task-1358 Tier 1: workspaces). Pure helpers over
+// @dexterm/custom that the key handler, the interactive loop and the screens call: load config + workspaces
+// into `state.custom`, turn a workspace into a plan the loop applies (theme, intensity, screener preset /
+// filter / sort, token panel toggles, start screen, HUD popups), decide which popups to open, and hand the
+// renderers the solved layout numbers for the active workspace.
+//
+// A workspace switch is a UI action and nothing more: it can navigate, re-theme and open READ-ONLY popups
+// (the same popups the keys open). It never opens a ticket, never confirms, never arms, never signs.
+import { THEMES, THEME_NAMES, isThemeName, DEFAULT_KEYMAP, Keymap } from '../../tui/src/index.js';
+import { loadConfig, listWorkspaces, writeWorkspace, captureWorkspace, layoutNumbers, dextermHome, DEFAULT_WORKSPACE, MORNING_HUD, listUserThemes, resolveTheme, applyOverrides, applyKeymapConfig, loadPacks, } from '../../custom/src/index.js';
+import { parseSortArg } from "./screener/sort.js";
+import { presetSpec } from "./screener/presets.js";
+export const CHORD_TTL_MS = 1500;
+export const MAX_WORKSPACE_NAME = 40;
+/** Load config.json + the workspaces directory into `state.custom`. Never throws (problems land in configErrors). */
+export function initCustom(env = process.env, now = Date.now()) {
+    const home = dextermHome(env);
+    const loaded = loadConfig(home);
+    const keymapResult = applyKeymapConfig(DEFAULT_KEYMAP.bindings, loaded.config.keymap);
+    const ui = {
+        home, config: loaded.config, configErrors: loaded.errors, configNotes: loaded.notes,
+        workspaces: listWorkspaces(home), active: DEFAULT_WORKSPACE,
+        chord: null, chordAt: now, nameInput: null, pendingPopups: null, notice: null, listCursor: 0,
+        themes: listUserThemes(home, loaded.config), themeErrors: [],
+        keymap: keymapResult.errors.length ? DEFAULT_KEYMAP : new Keymap(keymapResult.bindings),
+        keymapResult,
+        packs: null, packRules: [],
+    };
+    // task-1358 Tier 4: installed packs contribute namespaced workspaces (`<pack>/<name>`), themes (`<pack>-<name>`)
+    // and rules. Widgets stay registered DISABLED until `dexterm pack widget … --enable`; a pack keymap is never
+    // merged here (only `dexterm pack keymap <name> --merge` does, through the same validation as config.keymap).
+    if (loaded.config.packs?.length) {
+        const packs = loadPacks(home, loaded.config);
+        ui.packs = packs;
+        for (const w of packs.workspaces)
+            if (!ui.workspaces.some((x) => x.name === w.name))
+                ui.workspaces.push({ name: w.name, path: w.path, workspace: w.workspace, builtin: false, pack: w.pack });
+        for (const t of packs.themes)
+            if (!ui.themes.some((x) => x.name === t.name))
+                ui.themes.push({ name: t.name, path: t.path, doc: t.doc, pack: t.pack });
+        ui.packRules = packs.rules;
+        for (const e of packs.errors)
+            ui.configErrors.push(e);
+        for (const n of packs.notes)
+            ui.configNotes.push(n);
+    }
+    for (const t of ui.themes)
+        if (t.error)
+            ui.themeErrors.push(`theme ${t.name}: ${t.error}`);
+    for (const e of keymapResult.errors)
+        ui.configErrors.push(`keymap ${e.path}: ${e.msg} (the default keys are in use)`);
+    const configured = loaded.config.layout?.workspace;
+    if (configured && ui.workspaces.some((w) => w.name === configured && !w.error))
+        ui.active = configured;
+    return ui;
+}
+// ------------------------------------------------------------------ themes
+/** Built-in names first (the `t` cycle order), then the user themes that load. */
+export function themeNames(ui) {
+    return [...THEME_NAMES, ...(ui?.themes ?? []).filter((t) => !t.error).map((t) => t.name)];
+}
+/**
+ * Resolve a theme by name: a built-in or a user theme merged over its base, with `config.theme.overrides`
+ * applied on top. A theme that fails the contrast / hue guard is null (the caller keeps the current one) and the
+ * reason lands in `ui.themeErrors` once.
+ */
+export function themeByName(ui, name) {
+    const overrides = ui?.config.theme?.overrides;
+    const note = (msg) => { if (ui && !ui.themeErrors.includes(msg))
+        ui.themeErrors.push(msg); };
+    let base = null;
+    if (isThemeName(name))
+        base = THEMES[name];
+    else {
+        const t = ui?.themes.find((x) => x.name === name && !x.error);
+        if (!t)
+            return null;
+        const r = resolveTheme(t.doc, THEMES);
+        if (!r.theme) {
+            note(`theme ${name}: ${r.errors[0].path} ${r.errors[0].msg}`);
+            return null;
+        }
+        base = r.theme;
+    }
+    const o = applyOverrides(base, overrides);
+    if (o.errors.length)
+        note(`theme overrides: ${o.errors[0].path} ${o.errors[0].msg} (ignored)`);
+    return o.theme;
+}
+/** The next theme in the cycle after `current` (built-ins, then user themes); skips themes that fail to resolve. */
+export function cycleTheme(ui, current) {
+    const names = themeNames(ui);
+    let i = names.indexOf(current.name);
+    for (let n = 0; n < names.length; n++) {
+        i = (i + 1) % names.length;
+        const t = themeByName(ui, names[i]);
+        if (t)
+            return t;
+    }
+    return current;
+}
+export function findWorkspace(ui, name) {
+    return ui.workspaces.find((w) => w.name === name && !w.error)?.workspace ?? null;
+}
+export function activeWorkspace(ui) {
+    return ui ? findWorkspace(ui, ui.active) : null;
+}
+/** Workspace names in list order (built-ins first), bad files excluded; the 1-9 slots of the overlay and `ctrl+w <digit>`. */
+export function workspaceSlots(ui) { return ui.workspaces.filter((w) => !w.error).map((w) => w.name); }
+export function nextWorkspaceName(ui, step) {
+    const names = workspaceSlots(ui);
+    if (!names.length)
+        return DEFAULT_WORKSPACE;
+    const i = Math.max(0, names.indexOf(ui.active));
+    return names[(i + step + names.length) % names.length];
+}
+const START_ACTION = {
+    screener: 'screen.screener', newpairs: 'screen.newpairs', watchlist: 'screen.watchlist', analyst: 'screen.analyst',
+    positions: 'screen.positions', narrative: 'screen.narrative', plans: 'screen.plans', trending: 'screen.trending',
+};
+export function planWorkspace(ws, opts = {}) {
+    const warnings = [];
+    const themeKnown = opts.themeKnown ?? ((n) => isThemeName(n));
+    let theme = null;
+    if (ws.theme) {
+        if (themeKnown(ws.theme))
+            theme = ws.theme;
+        else
+            warnings.push(`theme "${ws.theme}" is not installed (kept the current one)`);
+    }
+    let preset = null;
+    if (ws.screener?.preset) {
+        if (presetSpec(ws.screener.preset))
+            preset = presetSpec(ws.screener.preset).id;
+        else
+            warnings.push(`unknown preset "${ws.screener.preset}"`);
+    }
+    let sort = null;
+    if (ws.screener?.sort) {
+        try {
+            sort = parseSortArg(ws.screener.sort);
+        }
+        catch (e) {
+            warnings.push(`bad sort "${ws.screener.sort}": ${e.message}`);
+        }
+    }
+    const start = ws.start ?? null;
+    const startAction = start && start !== 'token' ? START_ACTION[start] ?? null : null;
+    return {
+        name: ws.name, theme, intensity: ws.intensity ?? null, priceMode: ws.priceMode ?? null,
+        screener: { preset, filter: ws.screener?.filter ?? null, sort },
+        token: { ...(ws.token ?? {}) },
+        start: startAction, startScreen: start,
+        popups: [...(ws.popups ?? [])], warnings,
+    };
+}
+/** Apply the theme part of a plan (the loop and tests both use it): built-in or user theme. */
+export function themeFor(name, ui) { return themeByName(ui, name); }
+/**
+ * Which of a workspace's popups the loop should open now. Chart/bubbles/token need an open token (the
+ * workspace says `mint: selected`); the roster window has no workspace binding yet and is reported, not
+ * guessed. Already-open popups are left alone (never toggled closed). A `widget` popup opens only when the
+ * user enabled that pack widget (`dexterm pack widget <pack> <w> --enable`): a workspace can never consent for them.
+ */
+export function planPopupOpens(specs, st) {
+    const out = { open: [], widgets: [], skipped: [] };
+    const seen = new Set();
+    for (const s of specs) {
+        const id = s.kind === 'widget' ? `widget:${s.widget ?? ''}` : s.kind;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        if (s.kind === 'widget') {
+            const ref = s.widget ?? '';
+            if (!ref)
+                out.skipped.push({ kind: 'widget', why: 'no widget named' });
+            else if (!st.widgetEnabled)
+                out.skipped.push({ kind: 'widget', why: `${ref}: widgets need live or replay mode` });
+            else if (!st.widgetEnabled(ref))
+                out.skipped.push({ kind: 'widget', why: `${ref} is not enabled (dexterm pack widget ${ref.split('/').slice(0, 2).join(' ')} --enable)` });
+            else if (!st.widgetOpen?.(ref))
+                out.widgets.push(ref);
+            continue;
+        }
+        switch (s.kind) {
+            case 'chart':
+                if (!st.hasToken)
+                    out.skipped.push({ kind: 'chart', why: 'no token open' });
+                else if (!st.chartOpen)
+                    out.open.push('chart');
+                break;
+            case 'bubbles':
+                if (!st.hasToken)
+                    out.skipped.push({ kind: 'bubbles', why: 'no token open' });
+                else if (!st.bubblesOpen)
+                    out.open.push('bubbles');
+                break;
+            case 'token':
+                if (!st.hasToken)
+                    out.skipped.push({ kind: 'token', why: 'no token open' });
+                else if (!st.tokenOpen)
+                    out.open.push('token');
+                break;
+            case 'narrative':
+                if (!st.narrativeOpen)
+                    out.open.push('narrative');
+                break;
+            case 'plans':
+                if (!st.plansOpen)
+                    out.open.push('plans');
+                break;
+            case 'feeds':
+                if (!st.feedsOpen)
+                    out.open.push('feeds');
+                break;
+            default: out.skipped.push({ kind: s.kind, why: 'not wired to workspaces yet' });
+        }
+    }
+    return out;
+}
+/** Validate a typed name and persist the current layout as a workspace file; returns the new file entry. */
+export function saveWorkspace(ui, input) {
+    const name = input.name.trim();
+    if (!/^[a-z][a-z0-9-]{0,39}$/.test(name))
+        throw new Error('name: lowercase letters, digits and dashes, starting with a letter (max 40)');
+    if (name === MORNING_HUD || name === DEFAULT_WORKSPACE)
+        throw new Error(`"${name}" is a built-in workspace; pick another name`);
+    const ws = captureWorkspace(name, { ...input, screens: activeWorkspace(ui)?.screens });
+    const path = writeWorkspace(ui.home, ws);
+    const entry = { name, path, workspace: ws, builtin: false };
+    const i = ui.workspaces.findIndex((w) => w.name === name);
+    if (i >= 0)
+        ui.workspaces[i] = entry;
+    else
+        ui.workspaces.push(entry);
+    return entry;
+}
+// ------------------------------------------------------------------ layout numbers for the renderers
+/** The solved layout numbers for the active workspace at this frame size (cached per workspace × size). */
+export function layoutFor(ui, w, h) {
+    if (!ui)
+        return layoutNumbers(null, w, h);
+    const key = `${ui.active}|${w}x${h}`;
+    if (ui.layoutCache?.key === key)
+        return ui.layoutCache.numbers;
+    const numbers = layoutNumbers(activeWorkspace(ui), w, h);
+    ui.layoutCache = { key, numbers };
+    return numbers;
+}
+/** Footer/band badge text for the workspace state, or null when there is nothing to show (default, idle). */
+export function workspaceBadge(ui, now = Date.now()) {
+    if (!ui)
+        return null;
+    if (ui.nameInput !== null)
+        return { text: ` save workspace as: ${ui.nameInput}▏ (⏎ save · esc cancel) `, kind: 'input' };
+    if (ui.chord && now - ui.chordAt <= CHORD_TTL_MS)
+        return { text: ' ^W  w list · n/N next/prev · s save · m morning HUD · o popups · d default · 1-9 pick ', kind: 'chord' };
+    if (ui.active !== DEFAULT_WORKSPACE)
+        return { text: ` ⌗ ${ui.active} `, kind: 'name' };
+    return null;
+}

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

@@ -0,0 +1,191 @@
+// dexterm — the price display mode (task-1366): show USD price or MARKET CAP on every screen and both charts.
+//
+// A DISPLAY mode only. Market cap = price × supply, where the supply is what the data layer already reports
+// (the row's mcap / price at the latest tick: the "supply ratio"). Historical candles are scaled by the CURRENT
+// ratio, so every mcap axis says `mcap (current supply)`: a burn or a mint since that candle is not reflected,
+// and nobody should read it as exact historical market cap. When a token has no usable supply (mcap or price
+// missing / zero), the screen falls back to price and SAYS so; it never invents a number.
+//
+// No network calls, nothing here is read by the signer, the caps, tickets, plans or the confirm gate.
+import { fmtMcap, fmtMcapBare, fmtPrice } from '../../tui/src/index.js';
+import { applyAndJournal, configPath, dextermHome, loadConfig, DEFAULT_PRICE_MODE, PRICE_MODES } from '../../custom/src/index.js';
+export { PRICE_MODES, DEFAULT_PRICE_MODE };
+/** Axis / caption label for an mcap chart: the history is scaled by today's supply, and says so. */
+export const MCAP_AXIS_LABEL = 'mcap (current supply)';
+/** Shown wherever mcap mode is on but a token's supply is unknown, so the number on screen is a price. */
+export const MCAP_FALLBACK_NOTE = 'supply unknown · showing price';
+/** Short per-cell marker for a price shown in an MCAP column (fallback). */
+export const FALLBACK_MARK = 'ᵖ';
+export function isPriceMode(v) { return PRICE_MODES.includes(v); }
+/**
+ * Supply ratio = mcap / price at the latest tick (i.e. the circulating supply the source used). Null when either
+ * side is missing, non-finite or ≤ 0: the caller must fall back to price and say so.
+ */
+export function supplyRatio(price, mcap) {
+    if (price == null || mcap == null || !Number.isFinite(price) || !Number.isFinite(mcap) || price <= 0 || mcap <= 0)
+        return null;
+    const r = mcap / price;
+    return Number.isFinite(r) && r > 0 ? r : null;
+}
+/** A price expressed as market cap with the given supply ratio (null ratio or price → null). */
+export function mcapAt(price, ratio) {
+    if (price == null || ratio == null || !Number.isFinite(price))
+        return null;
+    return price * ratio;
+}
+/** Format a token's price slot: market cap in mcap mode when known, otherwise the price (flagged as a fallback). */
+export function priceCell(mode, price, mcap) {
+    if (mode === 'mcap') {
+        if (mcap != null && Number.isFinite(mcap) && mcap > 0)
+            return { text: fmtMcap(mcap), kind: 'mcap', fallback: false };
+        return { text: price == null ? '—' : fmtPrice(price), kind: 'price', fallback: price != null };
+    }
+    return { text: fmtPrice(price), kind: 'price', fallback: false };
+}
+/** "mcap $1.2M ($0.0₄123)": both numbers, for headers, tickets and tooltips. Price only when the supply is unknown. */
+export function mcapWithPrice(price, mcap) {
+    if (mcap != null && Number.isFinite(mcap) && mcap > 0)
+        return price != null ? `mcap ${fmtMcap(mcap)} (${fmtPrice(price)})` : `mcap ${fmtMcap(mcap)}`;
+    return price != null ? `${fmtPrice(price)} · ${MCAP_FALLBACK_NOTE}` : '—';
+}
+/**
+ * mcap mode for a table: the MCAP column takes the PRICE column's place AND priority (it is the headline number now)
+ * and PRICE moves to MCAP's old slot, so both stay on screen and every sort key keeps working. Price mode: unchanged.
+ */
+export function promoteMcap(cols, mode) {
+    if (mode !== 'mcap')
+        return cols;
+    const i = cols.findIndex((c) => c.key === 'price');
+    const j = cols.findIndex((c) => c.key === 'mcap');
+    if (i < 0 || j < 0)
+        return cols;
+    const out = cols.slice();
+    out[i] = { ...cols[j], prio: cols[i].prio };
+    out[j] = { ...cols[i], prio: cols[j].prio };
+    return out;
+}
+/** How many rows show a price in the MCAP column because their supply is unknown (for the panel caption). */
+export function fallbackCount(rows, get) {
+    let n = 0;
+    for (const r of rows) {
+        const v = get(r);
+        if (priceCell('mcap', v.price, v.mcap).fallback)
+            n++;
+    }
+    return n;
+}
+/** Caption segment for a table in mcap mode with fallback rows (null when there are none). */
+export function fallbackCaption(n) {
+    return n > 0 ? `${FALLBACK_MARK} ${n} price${n > 1 ? 's' : ''} (supply unknown)` : null;
+}
+/** The chart scale for a token: mcap mode with a known supply scales by the CURRENT supply ratio, else prices (+ a note). */
+export function chartMode(mode, price, mcap) {
+    if (mode !== 'mcap')
+        return { scale: null, axisFmt: undefined, kind: 'price', label: null };
+    const ratio = supplyRatio(price, mcap);
+    if (ratio === null)
+        return { scale: null, axisFmt: undefined, kind: 'price', label: MCAP_FALLBACK_NOTE };
+    return { scale: ratio, axisFmt: fmtMcapBare, kind: 'mcap', label: MCAP_AXIS_LABEL };
+}
+/**
+ * One plan level with BOTH numbers, in the order the mode prefers: mcap mode `mc ≤ $300K ($0.0003)`, price mode
+ * `≤ $0.0003 (mc $300K)`. The price of a market-cap trigger is mc / the plan's OWN supply snapshot (supplyAtProposal,
+ * the supply its triggers were read back against), so the preview never re-derives what the plan means.
+ */
+export function triggerLevel(t, supply, mode) {
+    if (t.kind === 'immediate')
+        return 'now';
+    const below = t.kind === 'mc-below' || t.kind === 'price-below';
+    const op = below ? '≤' : '≥';
+    const okSupply = Number.isFinite(supply) && supply > 0;
+    const mc = t.kind.startsWith('mc-') ? t.value : okSupply ? t.value * supply : null;
+    const px = t.kind.startsWith('price-') ? t.value : okSupply ? t.value / supply : null;
+    if (mode === 'mcap')
+        return `mc ${op} ${mc === null ? '—' : fmtMcap(mc)}${px === null ? '' : ` (${fmtPrice(px)})`}`;
+    return `${op} ${px === null ? '—' : fmtPrice(px)}${mc === null ? '' : ` (mc ${fmtMcap(mc)})`}`;
+}
+/** The order-plan preview line: entry · each take-profit · stop, each with market cap AND price. Display only. */
+export function planLevels(plan, mode) {
+    const s = plan.supplyAtProposal;
+    const parts = [`entry ${triggerLevel(plan.entry, s, mode)}`];
+    for (const e of plan.exits)
+        parts.push(`TP ${Math.round(e.fraction * 100)}% ${triggerLevel(e.at, s, mode)}`);
+    if (plan.stop)
+        parts.push(`stop ${triggerLevel(plan.stop, s, mode)}`);
+    return parts.join(' · ');
+}
+/**
+ * A held position's AVG / PRICE cells: with a supply (mcap mode, supply known) they read market cap — `AVG MC` is the
+ * average entry price × the CURRENT supply — else the existing price text (marked ᵖ when mcap mode had no supply).
+ * PnL and value cells are not touched: they stay USD / SOL.
+ */
+export function positionPriceCells(mode, supply, avgUsd, priceUsd, avgText, priceText) {
+    if (mode === 'mcap' && supply !== null && supply > 0) {
+        return {
+            avg: { label: 'AVG MC', value: avgUsd !== null ? fmtMcap(avgUsd * supply) : avgText === '—' ? '—' : avgText + FALLBACK_MARK },
+            price: { label: 'MCAP', value: priceUsd !== null ? fmtMcap(priceUsd * supply) : priceText === '—' ? '—' : priceText + FALLBACK_MARK },
+        };
+    }
+    const mark = mode === 'mcap' ? FALLBACK_MARK : '';
+    return { avg: { label: 'AVG ENTRY', value: avgText === '—' ? avgText : avgText + mark }, price: { label: 'PRICE', value: priceText === '—' ? priceText : priceText + mark } };
+}
+/** The mode in effect: the state's (set from config, a workspace or `$`), default price. */
+export function priceModeOf(state) {
+    return state?.priceMode === 'mcap' ? 'mcap' : 'price';
+}
+/** The mode a run starts in: config.display.priceMode, else price. */
+export function configPriceMode(cfg) {
+    const m = cfg?.display?.priceMode;
+    return isPriceMode(m) ? m : DEFAULT_PRICE_MODE;
+}
+/**
+ * `$`: flip the mode and persist it to config.display.priceMode through the journal (actor user, so `undo` works).
+ * Returns the notice for the toast. Persistence failure keeps the new mode for this run and says why.
+ */
+export function togglePriceMode(state) {
+    const next = priceModeOf(state) === 'mcap' ? 'price' : 'mcap';
+    state.priceMode = next;
+    const what = next === 'mcap' ? `showing MARKET CAP · charts: ${MCAP_AXIS_LABEL}` : 'showing USD PRICE';
+    const ui = state.custom;
+    if (!ui)
+        return `${what} (not saved: no config on this run)`;
+    try {
+        const op = ui.config.display ? { op: 'add', path: '/display/priceMode', value: next } : { op: 'add', path: '/display', value: { priceMode: next } };
+        const { config } = applyAndJournal(ui.home, [op], { actor: 'user', why: `$ price mode ${next}`, now: state.now.getTime() });
+        ui.config = config;
+        return `${what} · saved ($ to switch back)`;
+    }
+    catch (e) {
+        return `${what} (not saved: ${e.message})`;
+    }
+}
+export const DISPLAY_USAGE = 'usage: dexterm display [price|mcap]   show or set display.priceMode in ~/.dexterm/config.json ($ in the app toggles it)';
+/** `dexterm display [price|mcap]`: print the saved price display mode, or set it (journaled, actor user). No network. */
+export function displayCommand(argv, io) {
+    const home = dextermHome(io.env);
+    const [arg] = argv;
+    const loaded = loadConfig(home);
+    if (arg === undefined) {
+        if (!loaded.ok) {
+            io.stderr.write(`dexterm display: ${loaded.errors[0]}\n`);
+            return 1;
+        }
+        const m = configPriceMode(loaded.config);
+        io.stdout.write(`display.priceMode = ${m}${m === 'mcap' ? ` (tables show MCAP; charts: ${MCAP_AXIS_LABEL}; tokens without a supply fall back to price)` : ' (USD price per token)'}\n`);
+        return 0;
+    }
+    if (!isPriceMode(arg)) {
+        io.stderr.write(`dexterm display: unknown mode ${JSON.stringify(arg.slice(0, 20))}\n${DISPLAY_USAGE}\n`);
+        return 2;
+    }
+    try {
+        const op = loaded.config.display ? { op: 'add', path: '/display/priceMode', value: arg } : { op: 'add', path: '/display', value: { priceMode: arg } };
+        applyAndJournal(home, [op], { actor: 'user', why: `dexterm display ${arg}` });
+    }
+    catch (e) {
+        io.stderr.write(`dexterm display: ${e.message}\n`);
+        return 1;
+    }
+    io.stdout.write(`display.priceMode = ${arg} (saved to ${configPath(home)})\n`);
+    return 0;
+}