dexterm-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,361 @@
+// dexterm doctor (task-1305): a pre-flight the user runs before anything else. It answers one
+// question — "will dexterm work on this machine, and if not, exactly what do I fix?" — as a plain
+// pass/warn/fail list with a copy-pasteable fix on every line that is not a pass.
+//
+// Everything that touches the outside world (the claude binary, the network) is injected so the
+// checks stay deterministic in tests and never hang: each probe carries its own timeout and any
+// failure is turned into a `fail`/`warn` line, never an exception. The doctor NEVER prints the
+// Helius key or any URL that could carry it — it reports the provider name only.
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { shellBinaryPath } from '../../popup/src/index.js';
+import { detectColorDepth, protocolFromEnv } from '../../tui/src/index.js';
+import { resolveRpcUrl, defaultDbPath } from '../../data/src/index.js';
+import { XTokenStore } from '../../data/src/index.js';
+import { SayTts, voiceDoctor, WHISPER_MODEL } from '../../voice/src/index.js';
+import { kbStore, skillStore } from "./kb-skill-cmd.js";
+/** The minimum Node that runs dexterm (type-stripping of the .ts entry needs 22.18). */
+export const MIN_NODE = [22, 18, 0];
+/** Cheap PATH lookup (no spawn) for the voice probe. */
+function onPath(bin) {
+    for (const p of (process.env.PATH ?? '').split(':'))
+        if (p && existsSync(join(p, bin)))
+            return true;
+    return false;
+}
+/**
+ * Default voice probe. Deliberately cheap and non-blocking: it never compiles the Swift helper (that
+ * is left to the first real `v` press), so resolvedStt is inferred from swiftc / whisper presence.
+ */
+export async function defaultVoiceProbe(platform = process.platform) {
+    const say = new SayTts();
+    const sayAvailable = platform === 'darwin' ? await say.available() : false;
+    const voices = sayAvailable ? await say.listVoices() : [];
+    const swiftcPresent = platform === 'darwin' && onPath('swiftc');
+    const whisperBinPresent = onPath('whisper-cli');
+    const whisperModelPresent = existsSync(WHISPER_MODEL);
+    const micToolPresent = onPath('sox') || onPath('rec') || onPath('ffmpeg');
+    const resolvedStt = swiftcPresent ? 'apple' : (whisperBinPresent && whisperModelPresent && micToolPresent) ? 'whisper' : null;
+    return { platform, sayAvailable, voiceCount: voices.length, swiftcPresent, whisperBinPresent, whisperModelPresent, micToolPresent, resolvedStt };
+}
+/** The keyless data sources the live app depends on, with a cheap reachability URL for each. */
+export const DATA_SOURCES = [
+    { name: 'DexScreener', url: 'https://api.dexscreener.com/latest/dex/search?q=SOL' },
+    { name: 'Jupiter', url: 'https://lite-api.jup.ag/price/v3?ids=So11111111111111111111111111111111111111112' },
+    { name: 'GeckoTerminal', url: 'https://api.geckoterminal.com/api/v2/networks' },
+    { name: 'RugCheck', url: 'https://api.rugcheck.xyz/v1/stats/new_tokens' },
+    { name: 'GoPlus', url: 'https://api.gopluslabs.io/api/v1/supported_chains' },
+    { name: 'Solana RPC', url: 'https://api.mainnet-beta.solana.com' },
+    // PumpPortal is a websocket; a plain GET to the host proves the network path (new pairs is a soft dep).
+    { name: 'PumpPortal', url: 'https://pumpportal.fun/', soft: true },
+];
+function parseVersion(v) {
+    const m = /(\d+)\.(\d+)\.(\d+)/.exec(v);
+    if (!m)
+        return [0, 0, 0];
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+/** Compare two semver triples: -1 / 0 / 1. */
+export function cmpVersion(a, b) {
+    for (let i = 0; i < 3; i++) {
+        const d = (a[i] ?? 0) - (b[i] ?? 0);
+        if (d)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
+/** Default live probe: a GET with a hard timeout. Any HTTP answer = reachable; only transport errors fail. */
+export async function livingProbe(url, timeoutMs = 4000) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    const t0 = Date.now();
+    try {
+        const res = await fetch(url, { method: 'GET', signal: ctl.signal, headers: { 'user-agent': 'dexterm-doctor' } });
+        // Drain a little so sockets close cleanly; we do not care about the body.
+        try {
+            await res.arrayBuffer();
+        }
+        catch { /* ignore */ }
+        return { reachable: true, status: res.status, ms: Date.now() - t0 };
+    }
+    catch (e) {
+        const err = e.name === 'AbortError' ? `timeout after ${timeoutMs}ms` : e.message;
+        return { reachable: false, error: err, ms: Date.now() - t0 };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** Default claude probe: spawn `claude --version` with a timeout. Presence only (login is not asserted here). */
+export async function claudeProbe(timeoutMs = 4000) {
+    const { execFile } = await import('node:child_process');
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (r) => { if (!done) {
+            done = true;
+            resolve(r);
+        } };
+        try {
+            const child = execFile('claude', ['--version'], { timeout: timeoutMs }, (err) => {
+                if (err && err.code === 'ENOENT')
+                    finish('missing');
+                else if (err)
+                    finish('present'); // on PATH but the probe errored/timed out: do not block on it
+                else
+                    finish('present');
+            });
+            child.on('error', () => finish('missing'));
+        }
+        catch {
+            finish('missing');
+        }
+    });
+}
+/** Default writable check: create the directory, write and remove a temp file. Returns an error message or null. */
+export function writableProbe(dir) {
+    try {
+        mkdirSync(dir, { recursive: true });
+        const tmp = mkdtempSync(join(dir, '.dexterm-doctor-'));
+        const f = join(tmp, 'probe');
+        writeFileSync(f, 'ok');
+        rmSync(tmp, { recursive: true, force: true });
+        return null;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
+export function defaultDeps(env = process.env, isTTY = process.stdout.isTTY === true) {
+    return {
+        env,
+        isTTY,
+        nodeVersion: process.versions.node,
+        platform: process.platform,
+        claude: () => claudeProbe(),
+        probe: (url) => livingProbe(url),
+        checkWritable: writableProbe,
+        offline: env.DEXTERM_OFFLINE === '1' || env.DEXTERM_OFFLINE === 'true',
+        popupShell: () => {
+            const path = shellBinaryPath(env);
+            const cargo = spawnSync('cargo', ['--version'], { stdio: 'ignore', timeout: 3000 }).status === 0;
+            return { path, built: existsSync(path), cargo };
+        },
+        voiceProbe: () => defaultVoiceProbe(process.platform),
+        content: () => ({ kb: kbStore(env).get(), skills: skillStore(env).get() }),
+    };
+}
+/** Run every check. Never throws; network and claude probes are the injected ones. */
+export async function runDoctor(deps) {
+    const checks = [];
+    // 1. Node version
+    const node = parseVersion(deps.nodeVersion);
+    if (cmpVersion(node, MIN_NODE) >= 0) {
+        checks.push({ name: 'Node', status: 'pass', detail: `v${deps.nodeVersion} (need ${MIN_NODE.join('.')}+)` });
+    }
+    else {
+        checks.push({
+            name: 'Node', status: 'fail',
+            detail: `v${deps.nodeVersion} is too old (need ${MIN_NODE.join('.')}+ for the TypeScript entry)`,
+            fix: 'Install Node 22.18+ : `nvm install 22` (nvm) or `brew install node` (Homebrew), then re-run.',
+        });
+    }
+    // 2. Terminal colour
+    const depth = detectColorDepth(deps.env, deps.isTTY);
+    const term = deps.env.TERM_PROGRAM || deps.env.TERM || 'unknown';
+    if (!deps.isTTY) {
+        checks.push({
+            name: 'Terminal', status: 'warn',
+            detail: 'not a TTY (output is being piped); the interactive UI needs a real terminal',
+            fix: 'Run dexterm directly in a terminal window, not through a pipe or a non-interactive shell.',
+        });
+    }
+    else if (depth === 'truecolor') {
+        checks.push({ name: 'Terminal colour', status: 'pass', detail: `24-bit truecolor (${term})` });
+    }
+    else if (depth === '256') {
+        checks.push({
+            name: 'Terminal colour', status: 'warn',
+            detail: `256-colour only (${term}); dexterm runs but the neon look is flattened`,
+            fix: 'Use a truecolor terminal (iTerm2, WezTerm, Ghostty, Kitty, Alacritty, Windows Terminal) or set COLORTERM=truecolor.',
+        });
+    }
+    else {
+        checks.push({
+            name: 'Terminal colour', status: 'warn',
+            detail: `no colour (${term}${deps.env.NO_COLOR ? ', NO_COLOR set' : ''}); dexterm falls back to monochrome`,
+            fix: 'Unset NO_COLOR and use a colour terminal for the full look; dexterm still works without it.',
+        });
+    }
+    // 2b. Coin images (task-1326): the protocol this terminal gets, judged from the environment alone (the
+    // interactive run also asks the tty). Apple Terminal.app is the one known no-images terminal → warn + fix.
+    {
+        const p = protocolFromEnv(deps.env);
+        const label = p.protocol === 'kitty' ? 'real pixels (kitty graphics)' : p.protocol === 'iterm' ? 'real pixels (iTerm2 inline images)' : p.protocol === 'sixel' ? 'real pixels (sixel)' : 'half-block art';
+        if (p.protocol === 'blocks' && /apple terminal/i.test(p.reason)) {
+            checks.push({ name: 'Coin images', status: 'warn', detail: `${label}: ${p.reason}`, fix: 'For real coin pictures use Ghostty (`brew install --cask ghostty`) or iTerm2 (`brew install --cask iterm2`); the block-art fallback still shows every coin here.' });
+        }
+        else {
+            checks.push({ name: 'Coin images', status: 'pass', detail: `${label} (${p.reason})${p.protocol === 'blocks' ? '; --no-images turns them off' : ''}` });
+        }
+    }
+    // 3. Claude CLI (the analyst). Not required to browse; required for the `a` analyst.
+    const claude = await deps.claude();
+    if (claude === 'missing') {
+        checks.push({
+            name: 'Claude CLI', status: 'warn',
+            detail: 'not found on PATH; the analyst (a) is disabled, the rest of dexterm works',
+            fix: 'Install Claude Code (https://claude.com/claude-code) and run `claude` once to log in.',
+        });
+    }
+    else {
+        checks.push({
+            name: 'Claude CLI', status: 'pass',
+            detail: 'found on PATH (the analyst runs your local `claude`; log in once with `claude` if the analyst errors)',
+        });
+    }
+    // 4b. Login with X (optional, task-1357): the user's own X app + login unlock X posts in the SOCIAL panel / TRENDING.
+    {
+        const xs = new XTokenStore({ env: deps.env });
+        const meta = xs.meta();
+        const modes = xs.modes();
+        const clientId = xs.clientId(deps.env);
+        if (meta.loggedIn) {
+            const loose = (modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700);
+            checks.push({ name: 'Login with X', status: loose ? 'warn' : 'pass', detail: `logged in${meta.user ? ` as @${meta.user.username}` : ''} · scopes ${meta.scopes.join(' ') || '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no'}${loose ? ' · token file permissions are looser than 0600' : ''}`, ...(loose ? { fix: `chmod 700 ${xs.dir} && chmod 600 ${xs.tokensPath}` } : {}) });
+        }
+        else if (clientId) {
+            checks.push({ name: 'Login with X', status: 'warn', detail: 'client id stored, not logged in — X posts stay off (keyless venues, news and on-chain rows still work)', fix: 'dexterm x login' });
+        }
+        else {
+            checks.push({ name: 'Login with X', status: 'pass', detail: 'not set up (optional) — X posts need your own X app: free Native App + `dexterm x set-client-id` + `dexterm x login`; see docs › Login with X' });
+        }
+    }
+    // 4. Helius key (optional; the app is live and keyless without it, just with fewer holders/safety fields).
+    const rpc = resolveRpcUrl({ env: deps.env, home: deps.env.HOME || undefined });
+    if (rpc.provider === 'helius') {
+        checks.push({ name: 'Helius RPC', status: 'pass', detail: `key configured (${rpc.basis}) — holders & safety enriched` });
+    }
+    else if (rpc.provider === 'custom') {
+        checks.push({ name: 'RPC', status: 'pass', detail: 'custom endpoint via DEXTERM_RPC_URL' });
+    }
+    else {
+        checks.push({
+            name: 'Helius RPC', status: 'warn',
+            detail: 'no key — dexterm uses the public RPC (holders & some safety fields will show as "needs key")',
+            fix: 'Free tier: make a key at https://dashboard.helius.dev, then `mkdir -p ~/.dexterm && printf %s "YOUR_KEY" > ~/.dexterm/helius.key && chmod 600 ~/.dexterm/helius.key`',
+        });
+    }
+    // 5. Network + each data source
+    if (deps.offline) {
+        checks.push({
+            name: 'Network', status: 'warn',
+            detail: 'DEXTERM_OFFLINE is set; skipped the live source probes (use --fixtures / --replay for offline data)',
+        });
+    }
+    else {
+        const results = await Promise.all(DATA_SOURCES.map(async (s) => ({ s, r: await deps.probe(s.url) })));
+        const down = results.filter((x) => !x.r.reachable);
+        const hardDown = down.filter((x) => !x.s.soft);
+        if (down.length === 0) {
+            const slow = results.filter((x) => (x.r.ms ?? 0) > 2500).map((x) => x.s.name);
+            checks.push({
+                name: 'Data sources', status: 'pass',
+                detail: `all ${results.length} reachable${slow.length ? ` (slow: ${slow.join(', ')})` : ''}`,
+            });
+        }
+        else {
+            checks.push({
+                name: 'Data sources', status: hardDown.length ? 'fail' : 'warn',
+                detail: `unreachable: ${down.map((x) => `${x.s.name} (${x.r.error ?? 'error'})`).join(', ')}`,
+                fix: hardDown.length
+                    ? 'Check your internet connection / VPN / firewall. If only some hosts fail, they may be regionally blocked — try again or use a different network.'
+                    : 'New pairs (PumpPortal) is unreachable; the rest of dexterm works. Check back later or your network may block its host.',
+            });
+        }
+    }
+    // 5b. task-1325: the native chart window (docked beside the terminal) vs the browser fallback
+    if (deps.popupShell) {
+        const sh = deps.popupShell();
+        if (sh.built)
+            checks.push({ name: 'Chart window', status: 'pass', detail: `native window ready (${sh.path}); C on a token opens it docked beside this terminal` });
+        else
+            checks.push({
+                name: 'Chart window', status: 'warn',
+                detail: `native window not built — C opens the chart in your browser instead`,
+                fix: sh.cargo ? 'Run `npm run build:shell` in packages/popup (about a minute the first time).' : 'Install Rust (https://rustup.rs), then run `npm run build:shell` in packages/popup.',
+            });
+    }
+    // 6. Writable DB path
+    const dbPath = defaultDbPath(deps.env);
+    const dbDir = dirname(dbPath);
+    const werr = deps.checkWritable(dbDir);
+    if (!werr) {
+        checks.push({ name: 'Data directory', status: 'pass', detail: `${dbDir} is writable (cache, watchlist, credit meter)` });
+    }
+    else {
+        checks.push({
+            name: 'Data directory', status: 'fail',
+            detail: `cannot write ${dbDir}: ${werr}`,
+            fix: `Fix the permissions (\`mkdir -p ${dbDir} && chmod u+rwx ${dbDir}\`) or run with \`--db :memory:\` for a throwaway session.`,
+        });
+    }
+    // 6b. task-1377: the user's KB / skill overlay. Warn-only: a bad user file is skipped and the bundled one stays in effect.
+    if (deps.content) {
+        try {
+            const { kb, skills } = deps.content();
+            const part = (label, m) => `${label} ${m.bundled} bundled · ${m.user} user (${m.overridden} overridden, ${m.added} new)${m.skipped.length ? ` · ${m.skipped.length} skipped` : ''}`;
+            const detail = `${part('KB', kb)} · ${part('skills', skills)}`;
+            const skipped = [...kb.skipped.map((s) => `kb ${s.id}: ${s.reason}`), ...skills.skipped.map((s) => `skill ${s.id}: ${s.reason}`)];
+            if (skipped.length) {
+                checks.push({ name: 'KB + skills', status: 'warn', detail: `${detail}; skipped ${skipped.slice(0, 3).join('; ')}`, fix: `Run \`dexterm kb check\` / \`dexterm skill check\` and fix the file, or \`dexterm kb|skill reset <id>\` to go back to the bundled one.` });
+            }
+            else {
+                checks.push({ name: 'KB + skills', status: 'pass', detail: `${detail} (yours: ${kb.dir}, ${skills.dir}; \`dexterm kb|skill list\`)` });
+            }
+        }
+        catch { /* an overlay problem must not break the doctor */ }
+    }
+    // 7. Voice mode (task-1282). Warn-only — voice always degrades to text, so it never fails the doctor.
+    if (deps.voiceProbe) {
+        try {
+            const vc = voiceDoctor(await deps.voiceProbe());
+            for (const c of vc)
+                checks.push(c);
+        }
+        catch { /* a voice probe failure must not break the doctor */ }
+    }
+    const ok = !checks.some((c) => c.status === 'fail');
+    return { checks, ok };
+}
+const GLYPH = { pass: '✓', warn: '!', fail: '✗' };
+const ANSI = { pass: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m' };
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+/** Render the result as a plain pass/fail list. `color` adds ANSI; off for pipes / NO_COLOR. */
+export function renderDoctor(result, opts = {}) {
+    const color = opts.color ?? false;
+    const paint = (s, code) => (color ? code + s + RESET : s);
+    const lines = [];
+    lines.push(paint('dexterm doctor', color ? BOLD : ''));
+    lines.push('');
+    const nameW = Math.max(...result.checks.map((c) => c.name.length));
+    for (const c of result.checks) {
+        const g = paint(GLYPH[c.status], color ? ANSI[c.status] : '');
+        lines.push(`  ${g}  ${c.name.padEnd(nameW)}  ${c.detail}`);
+        if (c.fix)
+            lines.push(`     ${' '.repeat(nameW)}  ${paint('→ ' + c.fix, color ? DIM : '')}`);
+    }
+    lines.push('');
+    const fails = result.checks.filter((c) => c.status === 'fail').length;
+    const warns = result.checks.filter((c) => c.status === 'warn').length;
+    if (result.ok && warns === 0)
+        lines.push(paint('All checks passed — run `dexterm` to start.', color ? ANSI.pass : ''));
+    else if (result.ok)
+        lines.push(paint(`Ready to run (${warns} warning${warns === 1 ? '' : 's'} above are optional).`, color ? ANSI.warn : ''));
+    else
+        lines.push(paint(`${fails} check${fails === 1 ? '' : 's'} failed — fix the ✗ lines above, then re-run \`dexterm doctor\`.`, color ? ANSI.fail : ''));
+    return lines.join('\n');
+}