dexterm-cli 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,319 @@
+// dexterm — PAPER trade ticket state machine (task-1310 T0, SPEC §6.1). Pure and TTY-free so the
+// ticket maths and the keypress confirm gate are unit-testable. The interactive loop and the live
+// binding drive this reducer and perform the side effects (quote fetch, executor.execute).
+//
+// Safety: this file builds an *order* and reads a *quote*. It never signs, holds a key, or sends a
+// transaction, and it imports no wallet/signing library (SPEC §6.0). Every ticket is labelled PAPER
+// and the confirm gate is ON by default: arming needs a deliberate keypress, and sizes above a
+// configurable threshold must be typed back (SPEC §6.1 step 3).
+import { solToLamports, LAMPORTS_PER_SOL } from '../../data/src/index.js';
+/** Default slippage and the SOL notional above which the confirm requires a typed-back amount. */
+export const DEFAULT_SLIPPAGE_BPS = 50;
+export const DEFAULT_TYPEBACK_THRESHOLD_SOL = 1;
+export const MAX_SLIPPAGE_BPS = 5000;
+export function openTicket(seed) {
+    return {
+        mint: seed.mint,
+        symbol: seed.symbol,
+        decimals: typeof seed.decimals === 'number' && Number.isFinite(seed.decimals) && seed.decimals > 0 ? seed.decimals : 9,
+        side: seed.side,
+        sizeUnit: seed.side === 'buy' ? 'sol' : 'pct',
+        sizeInput: '',
+        slippageInput: String(seed.slippageBps ?? DEFAULT_SLIPPAGE_BPS),
+        field: 'size',
+        phase: 'editing',
+        mode: seed.mode ?? 'paper',
+        gateOn: seed.gateOn ?? true,
+        typebackRequired: false,
+        typeback: '',
+        message: null,
+    };
+}
+function parseNum(s) {
+    const n = Number(s);
+    return Number.isFinite(n) ? n : NaN;
+}
+export function slippageBps(ts) {
+    if (ts.slippageInput.trim() === '')
+        return DEFAULT_SLIPPAGE_BPS;
+    const n = parseNum(ts.slippageInput);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_SLIPPAGE_BPS;
+    return Math.min(MAX_SLIPPAGE_BPS, Math.round(n));
+}
+/** The raw amount an order would spend, given the live context; 0n when the size is empty/invalid. */
+export function orderAmountRaw(ts, ctx) {
+    const n = parseNum(ts.sizeInput);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0n;
+    if (ts.side === 'buy') {
+        if (ts.sizeUnit === 'sol')
+            return solToLamports(n);
+        // % of free SOL balance
+        const pct = Math.min(100, n);
+        return (ctx.balanceLamports * BigInt(Math.round(pct * 100))) / 10000n;
+    }
+    // sell: % of the held position
+    const pct = Math.min(100, n);
+    return (ctx.positionTokensRaw * BigInt(Math.round(pct * 100))) / 10000n;
+}
+/** Build the order the ticket represents (amount already in raw base units). */
+export function toOrder(ts, ctx) {
+    return { mint: ts.mint, symbol: ts.symbol, side: ts.side, decimals: ts.decimals, amountRaw: orderAmountRaw(ts, ctx), slippageBps: slippageBps(ts) };
+}
+/** Is the current size a fillable order (positive amount, and for a sell there are tokens to sell)? */
+export function orderValid(ts, ctx) {
+    const amt = orderAmountRaw(ts, ctx);
+    if (amt <= 0n)
+        return false;
+    if (ts.side === 'sell' && ctx.positionTokensRaw <= 0n)
+        return false;
+    return true;
+}
+const DIGIT = /[0-9.]/;
+function editField(ts, key) {
+    const cur = ts.field === 'size' ? ts.sizeInput : ts.slippageInput;
+    if (key.name === 'backspace') {
+        const next = cur.slice(0, -1);
+        if (ts.field === 'size')
+            ts.sizeInput = next;
+        else
+            ts.slippageInput = next;
+        return true;
+    }
+    if ((key.name === 'char') && key.ch && DIGIT.test(key.ch) && !key.ctrl && !key.alt) {
+        // one decimal point only; slippage is integer bps
+        if (key.ch === '.' && (ts.field === 'slippage' || cur.includes('.')))
+            return true;
+        const next = (cur + key.ch).slice(0, 12);
+        if (ts.field === 'size')
+            ts.sizeInput = next;
+        else
+            ts.slippageInput = next;
+        return true;
+    }
+    return false;
+}
+/**
+ * Advance the ticket by one key. Returns the effect the caller performs:
+ *  - 'changed' : the order inputs changed → re-fetch the warm quote;
+ *  - 'confirm' : the gate was satisfied → the caller must execute the order now;
+ *  - 'close'   : leave the ticket (back to the token screen);
+ *  - 'none'    : nothing to do.
+ * A stray key during the confirm step can NEVER confirm — it cancels back to editing.
+ */
+export function ticketKey(ts, key, ctx) {
+    ts.message = null;
+    if (ts.phase === 'filling' || ts.phase === 'signing')
+        return 'none'; // in-flight: ignore input
+    if (ts.phase === 'planning')
+        return 'none'; // the signer is building; esc is handled by the binding (cancel)
+    if (ts.phase === 'filled' || ts.phase === 'error' || ts.phase === 'refused') {
+        // a receipt is showing: esc closes, any other key starts a fresh ticket for the same mint (same mode)
+        if (key.name === 'esc')
+            return 'close';
+        const side = ts.side;
+        Object.assign(ts, openTicket({ mint: ts.mint, symbol: ts.symbol, decimals: ts.decimals, side, gateOn: ts.gateOn, slippageBps: slippageBps(ts), mode: ts.mode }));
+        return 'changed';
+    }
+    // ---- LIVE plan screen (task-1328): the keypress gate for a REAL trade. Y / ⏎ confirms (with the
+    // typed-back size above the threshold, exactly like paper); esc returns to editing; ANY other key
+    // cancels — a stray key can never confirm, and never navigates mid-plan.
+    if (ts.phase === 'plan') {
+        if (key.name === 'esc') {
+            ts.phase = 'editing';
+            ts.typeback = '';
+            return 'drop-plan';
+        }
+        if (ts.typebackRequired && key.name === 'char' && key.ch && DIGIT.test(key.ch)) {
+            if (key.ch === '.' && ts.typeback.includes('.'))
+                return 'none';
+            ts.typeback = (ts.typeback + key.ch).slice(0, 12);
+            return 'none';
+        }
+        if (ts.typebackRequired && key.name === 'backspace') {
+            ts.typeback = ts.typeback.slice(0, -1);
+            return 'none';
+        }
+        const confirmKey = (key.name === 'char' && (key.ch === 'y' || key.ch === 'Y')) || key.name === 'enter';
+        if (confirmKey) {
+            if (ts.typebackRequired) {
+                const want = parseNum(ts.sizeInput);
+                const got = parseNum(ts.typeback);
+                if (!(Number.isFinite(got) && Math.abs(got - want) < 1e-9)) {
+                    ts.message = `type the size (${ts.sizeInput}) to confirm this LIVE ${ts.side}`;
+                    return 'none';
+                }
+            }
+            ts.phase = 'signing';
+            return 'confirm-live';
+        }
+        ts.phase = 'editing';
+        ts.typeback = '';
+        ts.message = 'plan cancelled';
+        return 'drop-plan';
+    }
+    if (ts.phase === 'confirm') {
+        if (key.name === 'esc') {
+            ts.phase = 'editing';
+            ts.typeback = '';
+            return 'none';
+        }
+        if (ts.typebackRequired && key.name === 'char' && key.ch && DIGIT.test(key.ch)) {
+            if (key.ch === '.' && ts.typeback.includes('.'))
+                return 'none';
+            ts.typeback = (ts.typeback + key.ch).slice(0, 12);
+            return 'none';
+        }
+        if (ts.typebackRequired && key.name === 'backspace') {
+            ts.typeback = ts.typeback.slice(0, -1);
+            return 'none';
+        }
+        const confirmKey = (key.name === 'char' && (key.ch === 'y' || key.ch === 'Y')) || key.name === 'enter';
+        if (confirmKey) {
+            if (ts.typebackRequired) {
+                const want = parseNum(ts.sizeInput);
+                const got = parseNum(ts.typeback);
+                if (!(Number.isFinite(got) && Math.abs(got - want) < 1e-9)) {
+                    ts.message = `type the size (${ts.sizeInput}) to confirm this PAPER ${ts.side}`;
+                    return 'none';
+                }
+            }
+            ts.phase = 'filling';
+            return 'confirm';
+        }
+        // any other key cancels the arm (a stray key never confirms, and never navigates mid-confirm)
+        ts.phase = 'editing';
+        ts.typeback = '';
+        ts.message = 'confirm cancelled';
+        return 'none';
+    }
+    // ---- editing
+    if (key.name === 'esc')
+        return 'close';
+    if (key.name === 'char' && (key.ch === 'L' || key.ch === 'l') && !key.ctrl && !key.alt)
+        return 'toggle-live';
+    if (key.name === 'tab') {
+        ts.field = ts.field === 'size' ? 'slippage' : 'size';
+        return 'none';
+    }
+    if (key.name === 'left' || key.name === 'right') {
+        ts.side = ts.side === 'buy' ? 'sell' : 'buy';
+        ts.sizeUnit = ts.side === 'buy' ? ts.sizeUnit : 'pct';
+        ts.typeback = '';
+        return 'changed';
+    }
+    if (key.name === 'char' && key.ch === 'u' && !key.ctrl) {
+        if (ts.side === 'buy') {
+            ts.sizeUnit = ts.sizeUnit === 'sol' ? 'pct' : 'sol';
+            return 'changed';
+        }
+        return 'none'; // sell is always % of the position
+    }
+    if (key.name === 'enter') {
+        if (!orderValid(ts, ctx)) {
+            ts.message = ts.side === 'sell' && ctx.positionTokensRaw <= 0n ? `no ${ts.symbol} position to sell` : 'enter a size first';
+            return 'none';
+        }
+        ts.typebackRequired = ts.gateOn && ctx.notionalSol > ctx.typebackThresholdSol;
+        ts.typeback = '';
+        if (ts.mode === 'live') {
+            ts.phase = 'planning';
+            return 'plan';
+        }
+        ts.phase = 'confirm';
+        return 'none';
+    }
+    // task-1368: f on a LIVE buy = size the order to the signer's cap (the binding knows the caps + SOL/USD; the
+    // reducer only names the effect). Inert on PAPER (no caps) and on a sell (sized in % of the position).
+    if (key.name === 'char' && (key.ch === 'f' || key.ch === 'F') && !key.ctrl && !key.alt) {
+        return ts.mode === 'live' && ts.side === 'buy' ? 'fit-cap' : 'none';
+    }
+    if (editField(ts, key))
+        return 'changed';
+    return 'none';
+}
+// --------------------------------------------------------------------------- task-1368 preflight + hints (pure)
+/**
+ * Fees + token-account rent the signer's simulated SOL-out may add on top of the size of a BUY (a tx fee, a priority
+ * fee and one associated-token-account rent of 0.00203928 SOL when the wallet has never held the token). The
+ * signer prices the LARGER of the planned SOL leg and the simulated SOL out, so a size that is exactly the cap in
+ * USD is refused once rent lands on top; `fitSizeSol` leaves this much room.
+ */
+export const CAP_FIT_OVERHEAD_SOL = 0.0025;
+const usd = (n) => `$${n.toFixed(2).replace(/\.00$/, '')}`;
+/**
+ * Size vs the signer's caps BEFORE ⏎ (task-1368 item b): the USD value of the size at the signer's own SOL/USD, the
+ * per-trade cap and what is left of the daily cap, a red verdict when the size is over, and the size that fits.
+ * Pure: the signer still decides at precheck/confirm — this only stops the user from building a plan that will be
+ * refused for a reason they could not see.
+ */
+export function capPreflight(i) {
+    const sizeSol = Number.isFinite(i.sizeSol) && i.sizeSol > 0 ? i.sizeSol : 0;
+    const price = i.solUsd !== null && Number.isFinite(i.solUsd) && i.solUsd > 0 ? i.solUsd : null;
+    const perTradeUsd = Math.max(0, i.perTradeUsd);
+    const dailyRemainingUsd = Math.max(0, i.dailyUsd - Math.max(0, i.spentTodayUsd));
+    const capUsd = Math.min(perTradeUsd, dailyRemainingUsd);
+    const sizeUsd = price !== null && sizeSol > 0 ? sizeSol * price : null;
+    const over = sizeUsd !== null && sizeUsd > capUsd + 1e-9;
+    const binding = !over ? null : dailyRemainingUsd < perTradeUsd ? 'daily' : 'per-trade';
+    const overhead = Math.max(0, i.overheadSol ?? CAP_FIT_OVERHEAD_SOL);
+    let fitSizeSol = null;
+    if (price !== null && capUsd > 0) {
+        const fit = Math.floor((capUsd / price - overhead) * 1000) / 1000;
+        fitSizeSol = fit > 0 ? fit : null;
+    }
+    const capText = `cap ${usd(perTradeUsd)}/trade · ${usd(dailyRemainingUsd)} left of ${usd(Math.max(0, i.dailyUsd))} today`;
+    let line;
+    if (sizeSol <= 0)
+        line = `${capText} · enter a size`;
+    else if (price === null)
+        line = `${sizeSol} SOL = $? (the signer has no SOL/USD yet; it will refuse an unpriced trade on mainnet) · ${capText}`;
+    else if (over) {
+        const which = binding === 'daily' ? `${usd(dailyRemainingUsd)} left today` : `${usd(perTradeUsd)} cap`;
+        line = `${sizeSol} SOL = ${usd(sizeUsd)} > ${which}: ${fitSizeSol !== null ? `use ≤ ${fitSizeSol} SOL (f fits it; fees + token-account rent counted)` : 'nothing fits — the cap is spent for today'}`;
+    }
+    else
+        line = `${sizeSol} SOL ≈ ${usd(sizeUsd)} at SOL ${usd(price)} · ${capText}`;
+    return { sizeSol, sizeUsd, perTradeUsd, dailyRemainingUsd, capUsd, over, fitSizeSol, binding, line };
+}
+const WSOL = 'So11111111111111111111111111111111111111112';
+/**
+ * task-1368 item c: a DEVNET signer + a Jupiter swap = a transaction built on MAINNET state (there is no Jupiter
+ * devnet): it can never simulate or fill on devnet, so say so BEFORE ⏎ and name the two ways out. Null for the
+ * probe (built for devnet on purpose), for wrapped SOL itself, and on mainnet.
+ */
+export function devnetMintWarning(a) {
+    if (a.network !== 'devnet' || a.probe || a.mint === WSOL)
+        return null;
+    const caps = `caps ${usd(a.perTradeUsd ?? 5)}/${usd(a.dailyUsd ?? 20)}`;
+    return `DEVNET cannot fill mainnet tokens: paper trade (L) or restart with --mainnet (real funds, ${caps})`;
+}
+const MAINNET_STATE_ERR = /invalid transaction|blockhash|account.*not found|not found|could not find|address (table|lookup)|AccountNotFound|ProgramAccountNotFound|unknown program|InvalidAccountData/i;
+/**
+ * task-1368 item f: a plain-English hint under a failed simulation when the failure pattern is the devnet-vs-mainnet
+ * mismatch (a mainnet route simulated on a devnet node: accounts, lookup tables or blockhash not found). Null when
+ * the simulation passed, was not run, or failed for another reason (the full error is still shown).
+ */
+export function simFailureHint(p, caps) {
+    if (p.kind !== 'swap' || !p.sim.ran || p.sim.ok)
+        return null;
+    const err = p.sim.error ?? '';
+    const mainnetState = MAINNET_STATE_ERR.test(err);
+    if (p.network === 'devnet' && (mainnetState || p.mintOnNetwork === false)) {
+        const mint = p.mintOnNetwork === false ? ' (the mint does not exist on devnet)' : '';
+        return `devnet-vs-mainnet wall${mint}: a Jupiter swap is built on MAINNET state (accounts, lookup tables, blockhash) that a devnet node does not have. Paper trade (L) or restart with --mainnet (real funds, caps ${usd(caps?.perTradeUsd ?? 5)}/${usd(caps?.dailyUsd ?? 20)}).`;
+    }
+    if (mainnetState)
+        return 'the node could not find the route\'s accounts or blockhash: a stale plan or the wrong RPC network — rebuild with ⏎, or check --trade-rpc';
+    return null;
+}
+/** SOL notional of a buy order sized in SOL/%, used to gate the typed-back step without a quote. */
+export function buyNotionalSol(ts, balanceLamports) {
+    const n = parseNum(ts.sizeInput);
+    if (!Number.isFinite(n) || n <= 0)
+        return 0;
+    if (ts.sizeUnit === 'sol')
+        return n;
+    return (Number(balanceLamports) / 1e9) * Math.min(100, n) / 100;
+}

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

@@ -0,0 +1,294 @@
+// task-1397 — `dexterm update` and the quiet startup notice.
+//
+// The check is two anonymous GETs: the npm registry's `latest` for dexterm-cli and GitHub's latest published
+// release of dexterm-xyz/dexterm. Both carry only fixed headers (no version, no OS, no ids, no cookies); nothing
+// about the user or the machine is sent beyond the IP any request has. No telemetry.
+//
+// Startup: a live interactive run reads ~/.dexterm/update-check.json (no network) and shows one toast when a
+// newer version was seen; at most once a day it refreshes that file in the background (never blocks, never in
+// --fixtures/--replay, never with DEXTERM_OFFLINE/CI). Off switches: `dexterm update --off`,
+// DEXTERM_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1. `dexterm update` itself never upgrades anything: it prints
+// the exact command for how this copy was installed (npm, Homebrew, release tarball, git checkout).
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dextermHome } from "./boot-state.js";
+import { VERSION } from "./version.js";
+export const NPM_PACKAGE = 'dexterm-cli';
+export const GITHUB_REPO = 'dexterm-xyz/dexterm';
+export const NPM_LATEST_URL = `https://registry.npmjs.org/${NPM_PACKAGE}/latest`;
+export const GITHUB_LATEST_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
+export const RELEASES_URL = `https://github.com/${GITHUB_REPO}/releases`;
+/** Fixed request headers: the same bytes for every user (GitHub's API requires a user-agent). */
+export const REQUEST_HEADERS = Object.freeze({ accept: 'application/json', 'user-agent': 'dexterm' });
+export const CHECK_EVERY_MS = 24 * 60 * 60 * 1000;
+export const REQUEST_TIMEOUT_MS = 4000;
+export const UPDATE_FILE = 'update-check.json';
+export const UPDATE_USAGE = `usage: dexterm update          check npm + GitHub now and print the upgrade command for this install
+       dexterm update --off    turn the once-a-day startup check off (dexterm update still works)
+       dexterm update --on     turn it back on`;
+/** `1.2.3`, `v1.2.3`, `1.2.3-rc.1` → parts; anything else → null (never guessed). */
+export function parseVersion(s) {
+    if (typeof s !== 'string')
+        return null;
+    const m = /^v?(\d{1,6})\.(\d{1,6})\.(\d{1,6})(?:-([0-9A-Za-z.-]{1,64}))?(?:\+[0-9A-Za-z.-]{1,64})?$/.exec(s.trim());
+    if (!m)
+        return null;
+    return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]), pre: m[4] ? m[4].split('.') : [] };
+}
+/** Semver precedence: < 0 when a is older than b. Unparseable versions compare equal (no notice on junk). */
+export function compareVersions(a, b) {
+    const x = parseVersion(a), y = parseVersion(b);
+    if (!x || !y)
+        return 0;
+    for (const k of ['major', 'minor', 'patch'])
+        if (x[k] !== y[k])
+            return x[k] - y[k];
+    if (!x.pre.length || !y.pre.length)
+        return y.pre.length - x.pre.length; // a release outranks its prereleases
+    for (let i = 0; i < Math.max(x.pre.length, y.pre.length); i++) {
+        const p = x.pre[i], q = y.pre[i];
+        if (p === undefined)
+            return -1;
+        if (q === undefined)
+            return 1;
+        const pn = /^\d+$/.test(p), qn = /^\d+$/.test(q);
+        if (pn && qn) {
+            if (Number(p) !== Number(q))
+                return Number(p) - Number(q);
+        }
+        else if (pn !== qn)
+            return pn ? -1 : 1;
+        else if (p !== q)
+            return p < q ? -1 : 1;
+    }
+    return 0;
+}
+const bare = (v) => v.trim().replace(/^v/, '');
+/** This module's real path (symlinks resolved): …/node_modules/dexterm-cli/dist/…, …/Cellar/dexterm/…, or a source tree. */
+export function selfPath() {
+    const p = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** The source tree's root for a tarball/checkout install (this file is packages/cli/src/update.ts). */
+export function sourceRoot(path = selfPath()) {
+    return resolve(dirname(path), '..', '..', '..');
+}
+export function detectInstall(path = selfPath(), exists = existsSync) {
+    const p = path.replace(/\\/g, '/');
+    if (p.includes(`/node_modules/${NPM_PACKAGE}/`))
+        return 'npm';
+    if (/\/Cellar\/dexterm\/|\/opt\/homebrew\/|\/home\/linuxbrew\/\.linuxbrew\//.test(p))
+        return 'brew';
+    return exists(join(sourceRoot(path), '.git')) ? 'checkout' : 'tarball';
+}
+export const INSTALL_LABEL = {
+    npm: `npm (${NPM_PACKAGE})`, brew: 'Homebrew (dexterm-xyz/dexterm tap)', tarball: 'release tarball (install.sh)', checkout: 'git checkout',
+};
+/** The exact commands that move this install to `latest`. Nothing here is ever run by dexterm. */
+export function upgradeCommands(kind, latest, opts = {}) {
+    const v = bare(latest);
+    if (kind === 'npm')
+        return [`npm i -g ${NPM_PACKAGE}@${v}`];
+    if (kind === 'brew')
+        return ['brew update', 'brew upgrade dexterm'];
+    if (kind === 'checkout')
+        return [`git -C ${shellQuote(opts.root ?? sourceRoot())} pull --ff-only`];
+    const base = `${RELEASES_URL}/download/v${v}`;
+    const file = `dexterm-${v}-src.tar.gz`;
+    const sum = (opts.platform ?? process.platform) === 'darwin' ? 'shasum -a 256 -c' : 'sha256sum -c';
+    return [
+        `curl -fL -O ${base}/${file} -O ${base}/SHA256SUMS`,
+        `grep ' ${file}$' SHA256SUMS | ${sum}`,
+        `tar -xzf ${file} && cd dexterm-${v} && ./install.sh`,
+    ];
+}
+function shellQuote(s) {
+    return /^[\w@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+async function getJson(fetchFn, url, timeoutMs, cancel) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const res = await fetchFn(url, { headers: { ...REQUEST_HEADERS }, signal: cancel ? AbortSignal.any([cancel, timeout]) : timeout, redirect: 'follow' });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return res.json();
+}
+function why(e) {
+    const err = e;
+    if (err?.name === 'TimeoutError' || err?.name === 'AbortError')
+        return 'timed out';
+    return String(err?.message ?? e).slice(0, 120);
+}
+/** Ask both sources. Never throws; each side reports its own error. */
+export async function fetchLatest(fetchFn = fetch, timeoutMs = REQUEST_TIMEOUT_MS, cancel) {
+    const npm = getJson(fetchFn, NPM_LATEST_URL, timeoutMs, cancel).then((b) => {
+        const v = b?.version;
+        return parseVersion(v) ? { ok: true, version: bare(v), url: `https://www.npmjs.com/package/${NPM_PACKAGE}` } : { ok: false, error: 'no version in the registry reply' };
+    }, (e) => ({ ok: false, error: why(e) }));
+    const github = getJson(fetchFn, GITHUB_LATEST_URL, timeoutMs, cancel).then((b) => {
+        const r = b;
+        if (r?.draft || r?.prerelease || !parseVersion(r?.tag_name))
+            return { ok: false, error: 'no published release in the reply' };
+        const tag = r.tag_name;
+        return { ok: true, version: bare(tag), url: `${RELEASES_URL}/tag/${tag}` };
+    }, (e) => ({ ok: false, error: why(e) }));
+    return { npm: await npm, github: await github };
+}
+/** The newest stable version either source reported, or null. */
+export function newestOf(r) {
+    let best = null;
+    for (const s of [r.npm, r.github]) {
+        if (!s.ok || parseVersion(s.version)?.pre.length)
+            continue;
+        if (best === null || compareVersions(s.version, best) > 0)
+            best = s.version;
+    }
+    return best;
+}
+/** The version this install's channel can actually move to: npm → the registry; the rest → the GitHub release. */
+export function targetFor(kind, r) {
+    const primary = kind === 'npm' ? r.npm : r.github;
+    return primary.ok ? primary.version : newestOf(r);
+}
+export function updateStatePath(env) {
+    return join(dextermHome(env), UPDATE_FILE);
+}
+export function readUpdateState(env) {
+    try {
+        const j = JSON.parse(readFileSync(updateStatePath(env), 'utf8'));
+        return {
+            enabled: j.enabled !== false,
+            checkedAt: typeof j.checkedAt === 'number' && Number.isFinite(j.checkedAt) ? j.checkedAt : null,
+            latest: typeof j.latest === 'string' && parseVersion(j.latest) ? bare(j.latest) : null,
+        };
+    }
+    catch {
+        return { enabled: true, checkedAt: null, latest: null };
+    }
+}
+export function writeUpdateState(env, s) {
+    const p = updateStatePath(env);
+    mkdirSync(dirname(p), { recursive: true, mode: 0o700 });
+    const tmp = `${p}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(s, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, p);
+}
+const truthy = (v) => !!v && v !== '0' && v.toLowerCase() !== 'false';
+/** Why the startup check is off, or null when it may run. `dexterm update` itself ignores all but DEXTERM_OFFLINE. */
+export function startupCheckOff(env, s) {
+    if (truthy(env.DEXTERM_NO_UPDATE_CHECK))
+        return 'DEXTERM_NO_UPDATE_CHECK is set';
+    if (truthy(env.NO_UPDATE_NOTIFIER))
+        return 'NO_UPDATE_NOTIFIER is set';
+    if (truthy(env.DEXTERM_OFFLINE))
+        return 'DEXTERM_OFFLINE is set';
+    if (truthy(env.CI))
+        return 'CI is set';
+    if (!s.enabled)
+        return 'turned off with dexterm update --off';
+    return null;
+}
+/** The one-line notice for a cached result, or null. */
+export function noticeFor(current, latest) {
+    if (!latest || parseVersion(latest)?.pre.length || compareVersions(latest, current) <= 0)
+        return null;
+    return `dexterm ${bare(latest)} is available (you have ${bare(current)}) · run dexterm update`;
+}
+/**
+ * Startup: the cached notice now, plus a background refresh when the last check is older than a day.
+ * The caller decides where the notice goes (the interactive loop shows it as a toast after the boot).
+ */
+export function startupCheck(env, opts = {}) {
+    const s = readUpdateState(env);
+    const none = () => { };
+    if (startupCheckOff(env, s))
+        return { notice: null, refresh: null, cancel: none };
+    const current = opts.current ?? VERSION;
+    const now = opts.now ?? Date.now();
+    const notice = noticeFor(current, s.latest);
+    if (s.checkedAt !== null && now - s.checkedAt >= 0 && now - s.checkedAt < CHECK_EVERY_MS)
+        return { notice, refresh: null, cancel: none };
+    const ctl = new AbortController();
+    const refresh = fetchLatest(opts.fetchFn, REQUEST_TIMEOUT_MS, ctl.signal).then((r) => {
+        if (ctl.signal.aborted || (!r.npm.ok && !r.github.ok))
+            return null; // quit / offline / blocked: try again next launch
+        const latest = newestOf(r);
+        try {
+            writeUpdateState(env, { ...s, checkedAt: now, latest });
+        }
+        catch { /* read-only home: no cache */ }
+        // only a notice the cache did not already produce
+        const n = noticeFor(current, latest);
+        return n && n !== notice ? n : null;
+    }).catch(() => null);
+    return { notice, refresh, cancel: () => ctl.abort() };
+}
+export async function updateCommand(argv, io, deps = {}) {
+    const [arg, ...rest] = argv;
+    const env = io.env;
+    if (arg === '-h' || arg === '--help' || arg === 'help') {
+        io.stdout.write(UPDATE_USAGE + '\n');
+        return 0;
+    }
+    if (rest.length || (arg !== undefined && arg !== '--off' && arg !== '--on')) {
+        io.stderr.write(`dexterm update: unknown argument ${JSON.stringify(String(rest[0] ?? arg).slice(0, 20))}\n${UPDATE_USAGE}\n`);
+        return 2;
+    }
+    const state = readUpdateState(env);
+    if (arg === '--off' || arg === '--on') {
+        try {
+            writeUpdateState(env, { ...state, enabled: arg === '--on' });
+        }
+        catch (e) {
+            io.stderr.write(`dexterm update: ${e.message}\n`);
+            return 1;
+        }
+        io.stdout.write(arg === '--off'
+            ? `startup update check: off (saved to ${updateStatePath(env)}). dexterm update still checks when you run it.\n`
+            : `startup update check: on (at most once a day; saved to ${updateStatePath(env)})\n`);
+        return 0;
+    }
+    if (truthy(env.DEXTERM_OFFLINE)) {
+        io.stderr.write('dexterm update: DEXTERM_OFFLINE is set; the check needs the network\n');
+        return 2;
+    }
+    const current = deps.current ?? VERSION;
+    const kind = deps.install ?? detectInstall();
+    const r = await fetchLatest(deps.fetchFn);
+    const line = (label, s) => `  ${label.padEnd(20)} ${s.ok ? `${s.version.padEnd(10)} ${s.url}` : `unavailable (${s.error})`}\n`;
+    io.stdout.write(`dexterm ${current} · installed via ${INSTALL_LABEL[kind]}\n`);
+    io.stdout.write(line(`npm ${NPM_PACKAGE}`, r.npm));
+    io.stdout.write(line('GitHub release', r.github));
+    if (!r.npm.ok && !r.github.ok) {
+        io.stderr.write(`dexterm update: could not reach npm or GitHub; check your connection, or see ${RELEASES_URL}\n`);
+        return 1;
+    }
+    const latest = newestOf(r);
+    try {
+        writeUpdateState(env, { ...state, checkedAt: deps.now ?? Date.now(), latest });
+    }
+    catch { /* read-only home */ }
+    const target = targetFor(kind, r);
+    if (!target || compareVersions(target, current) <= 0) {
+        const ahead = latest && compareVersions(latest, current) > 0;
+        io.stdout.write(ahead
+            ? `You are on the newest version ${kind === 'npm' ? 'npm has' : 'the GitHub release has'} (${current}); ${latest} is out on the other channel and reaches yours shortly.\n`
+            : `You are up to date (${current}).\n`);
+    }
+    else {
+        io.stdout.write(`\ndexterm ${target} is available. Upgrade with:\n\n`);
+        for (const c of upgradeCommands(kind, target, { platform: deps.platform, root: deps.root }))
+            io.stdout.write(`  ${c}\n`);
+        io.stdout.write('\n');
+        if (kind === 'tarball')
+            io.stdout.write(`Verify the download first: ${RELEASES_URL}/tag/v${target} (docs/verify-your-download.md). Release notes: CHANGELOG.md.\n`);
+    }
+    const off = startupCheckOff(env, readUpdateState(env));
+    io.stdout.write(`startup check: ${off ? `off (${off})` : 'on, at most once a day; dexterm update --off or DEXTERM_NO_UPDATE_CHECK=1 turns it off'}. No telemetry: two anonymous GETs (registry.npmjs.org, api.github.com).\n`);
+    return 0;
+}

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

@@ -0,0 +1,3 @@
+// The one place the app's version lives (task-1397). --version, the help banner and `dexterm update` read it;
+// cli.test.ts keeps it equal to packages/cli/package.json (release.yml refuses a tag that differs).
+export const VERSION = '0.1.2';