dexterm-cli 0.0.0-stage → 0.1.2

package/dist/packages/cli/src/watch-cmd.js

@@ -0,0 +1,190 @@
+// dexterm — `dexterm watch` (task-1398): run the rules engine against the live feed with NO TUI and PUSH
+// every fired alert (and, when alerts.proposals is on, a one-line proposal summary) through the delivery
+// layer — so a price / holder / LARP / new-pair alert reaches you when the terminal is closed.
+//
+//   dexterm watch [--interval S] [--ticks N | --once] [--replay FILE] [--db PATH] [--verbose]
+//
+// SAFETY: this builds NO signer and passes no `trade` option; a rule can only alert / annotate / open an
+// inert PROPOSAL (RulesEngine's money-safety invariant). The notifier only reads an AlertDelivery. There is
+// no arm/sign/confirm/cap path anywhere under here (asserted by alerts-1398.test.ts).
+import { dextermHome, loadConfig, RulesEngine } from '../../custom/src/index.js';
+import { openHistoryReadOnly, LARP_PACK } from '../../recorder/src/index.js';
+import { buildNotifier } from "./alerts/notifier.js";
+import { alertToDelivery, proposalToDelivery } from "./alerts/format.js";
+import { redactCreds } from "./alerts/creds.js";
+import { larpGrade } from "./rules.js";
+export const WATCH_USAGE = `usage: dexterm watch [--interval S] [--ticks N | --once] [--replay FILE] [--db PATH] [--verbose]
+
+  Runs your rules headless and pushes alerts to the channels you enabled with \`dexterm alerts\`
+  (terminal line + desktop notification + your Telegram bot / Discord webhook). Ctrl-C to stop.
+`;
+function parseArgs(argv) {
+    const a = { intervalMs: 15_000, ticks: Infinity, replay: null, db: null, verbose: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const t = argv[i];
+        if (t === '--help' || t === '-h')
+            a.help = true;
+        else if (t === '--verbose' || t === '-v')
+            a.verbose = true;
+        else if (t === '--once')
+            a.ticks = 1;
+        else if (t === '--interval') {
+            const n = Number(argv[++i]);
+            if (!Number.isFinite(n) || n < 1)
+                return { error: '--interval needs seconds ≥ 1' };
+            a.intervalMs = Math.round(n * 1000);
+        }
+        else if (t === '--ticks') {
+            const n = Number(argv[++i]);
+            if (!Number.isInteger(n) || n < 1)
+                return { error: '--ticks needs an integer ≥ 1' };
+            a.ticks = n;
+        }
+        else if (t === '--replay') {
+            a.replay = argv[++i] ?? null;
+            if (!a.replay)
+                return { error: '--replay needs a FILE' };
+        }
+        else if (t === '--db') {
+            a.db = argv[++i] ?? null;
+            if (!a.db)
+                return { error: '--db needs a PATH' };
+        }
+        else
+            return { error: `unknown option "${t}"` };
+    }
+    return a;
+}
+/** Latest LARP verdict per mint from a read-only recorder DB (best effort; empty map on any problem). */
+function larpMapFromDb(path) {
+    const map = new Map();
+    if (!path || path === ':memory:')
+        return map;
+    const db = openHistoryReadOnly(path);
+    if (!db)
+        return map;
+    try {
+        const rows = db.prepare('SELECT mint, verdict FROM verdicts WHERE pack = ? AND verdict IS NOT NULL ORDER BY t').all(LARP_PACK);
+        for (const r of rows)
+            map.set(r.mint, r.verdict); // ORDER BY t → last write per mint wins
+    }
+    catch { /* table may not exist yet */ }
+    finally {
+        try {
+            db.close();
+        }
+        catch { /* ignore */ }
+    }
+    return map;
+}
+/** Map a screener row to a rule row (cluster is only known with the wallet-intel scan, absent headless; larp from the DB). */
+export function toRuleRow(r, larp) {
+    return Object.assign(Object.create(null), r, { cluster: null, larp: larpGrade(larp.get(r.mint)) });
+}
+/** The production source: refresh the live (or replay) feed, map rows, yield a snapshot. Replay yields once. */
+function createFeedSource(opts) {
+    let feed = null;
+    let yielded = 0;
+    const larp = larpMapFromDb(opts.db);
+    return {
+        async next() {
+            if (opts.stop.aborted)
+                return null;
+            const { createLiveFeed, createReplayFeed } = await import("./feed.js");
+            if (!feed)
+                feed = opts.replay ? createReplayFeed(opts.replay, {}) : createLiveFeed({ dbPath: opts.db ?? undefined });
+            else {
+                if (opts.replay)
+                    return null; // a recording is a single snapshot: one evaluate, then stop
+                await opts.stop.wait(opts.intervalMs);
+                if (opts.stop.aborted)
+                    return null;
+            }
+            const rows = await feed.refresh();
+            yielded++;
+            if (opts.verbose)
+                opts.io.stderr.write(`watch: tick ${yielded}, ${rows.length} rows\n`);
+            return { rows: rows.map((r) => toRuleRow(r, larp)), now: opts.now() };
+        },
+        close() { try {
+            feed?.close();
+        }
+        catch { /* ignore */ } },
+    };
+}
+export async function watchCommand(argv, io, deps = {}) {
+    const parsed = parseArgs(argv);
+    if ('error' in parsed) {
+        io.stderr.write(`dexterm watch: ${parsed.error}\n\n${WATCH_USAGE}`);
+        return 2;
+    }
+    if (parsed.help) {
+        io.stdout.write(WATCH_USAGE);
+        return 0;
+    }
+    const now = deps.now ?? (() => Date.now());
+    const home = dextermHome(io.env);
+    const loaded = loadConfig(home);
+    for (const e of loaded.errors)
+        io.stderr.write(`dexterm watch: config: ${e}\n`);
+    const rules = loaded.config.rules ?? [];
+    const engine = new RulesEngine({ rules, now: now() });
+    for (const e of engine.errors)
+        io.stderr.write(`dexterm watch: rule ${e.id}: ${e.msg}\n`);
+    const enabled = engine.rules.filter((r) => r.enabled).length;
+    if (enabled === 0)
+        io.stderr.write('dexterm watch: no enabled rules (add some with `dexterm rules add`); nothing will fire\n');
+    // SIGINT-aware sleeper for the production loop.
+    const stop = (() => {
+        let aborted = false;
+        let wake = () => { };
+        return {
+            get aborted() { return aborted; },
+            abort() { aborted = true; wake(); },
+            wake() { wake(); },
+            wait(ms) { return new Promise((res) => { const t = setTimeout(res, ms); wake = () => { clearTimeout(t); res(); }; }); },
+        };
+    })();
+    const notifier = deps.notifier ?? buildNotifier(home, loaded.config.alerts, {
+        toastSink: (line) => io.stdout.write(`${new Date(now()).toISOString().slice(11, 19)} ${line}\n`),
+    });
+    const source = deps.source ?? createFeedSource({ replay: parsed.replay, db: parsed.db, intervalMs: parsed.intervalMs, verbose: parsed.verbose, io, now, stop });
+    const ready = notifier.readyChannels();
+    if (parsed.verbose || !deps.notifier)
+        io.stderr.write(`dexterm watch: ${enabled} rule(s), channels: ${ready.length ? ready.join(', ') : 'toast'}\n`);
+    const onSigint = () => { io.stderr.write('\ndexterm watch: stopping…\n'); stop.abort(); };
+    const addSig = !deps.source; // only own SIGINT for the real loop (tests drive a finite source)
+    if (addSig)
+        process.on('SIGINT', onSigint);
+    let delivered = 0;
+    try {
+        for (let tick = 0; tick < parsed.ticks; tick++) {
+            const snap = await source.next();
+            if (!snap)
+                break;
+            engine.observe(snap.rows, snap.now);
+            const res = engine.evaluate(snap.rows, snap.now, { watchlist: snap.watchlist, positions: snap.positions });
+            for (const a of res.alerts) {
+                await notifier.deliver(alertToDelivery(a));
+                delivered++;
+            }
+            if (loaded.config.alerts?.proposals)
+                for (const p of res.proposals) {
+                    await notifier.deliver(proposalToDelivery(p));
+                    delivered++;
+                }
+        }
+    }
+    catch (e) {
+        io.stderr.write(`dexterm watch: ${redactCreds(e.message)}\n`);
+        return 1;
+    }
+    finally {
+        if (addSig)
+            process.removeListener('SIGINT', onSigint);
+        await source.close?.();
+    }
+    if (parsed.verbose || !deps.notifier)
+        io.stderr.write(`dexterm watch: delivered ${delivered} alert(s)\n`);
+    return 0;
+}

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

@@ -0,0 +1,208 @@
+// dexterm — pack WIDGETS in the app (task-1358 Tier 5). A pack widget is an html page the popup host serves in a
+// loopback HUD window under a hash-only CSP (r2: no nonce — every inline block is allow-listed by sha256, nothing is
+// substituted into the pack html), fed PUBLIC view models over the host's socket. This adapter is the whole of what a
+// widget can see:
+//   * which widgets exist and are ENABLED (config.plugins['<pack>/<widget>'].enabled — the user's consent from
+//     `dexterm pack widget … --enable`; a pack cannot flip it);
+//   * the page bytes, read from the installed pack directory only after the pack re-hashes to its install record
+//     (a page edited after install is refused), never a symlink, never outside the pack, size-capped, and audited
+//     once more for loaders (<script src>, <link>, frames, <meta http-equiv>, @import, the __NONCE__ token);
+//   * the per-topic view models (rows · token · narrative · positions · alerts · theme) built from what the
+//     terminal already shows. No keys, no signer state, no caps, no mandates, no gate, no pair/source ids.
+// Widgets receive; they cannot ask for anything (the only events a page may send are the generic close/focus/drag).
+import { lstatSync, readFileSync, realpathSync, existsSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { checkIntegrity, packsDir, packWidgetKey, WIDGET_REF } from '../../custom/src/index.js';
+import { WIDGET_HTML_MAX, auditWidgetHtml } from '../../popup/src/index.js';
+import { popupThemeFrom } from "./popup.js";
+const REF = new RegExp(WIDGET_REF);
+/** Every widget of every installed pack, with its consent flag. */
+export function installedWidgets(ui) {
+    return (ui?.packs?.widgets ?? []).map((w) => ({ key: packWidgetKey(w.pack, w.name), pack: w.pack, name: w.name, dir: w.dir, enabled: w.enabled, manifest: w.manifest }));
+}
+/** Split `<pack>/<widget>[/<id>]`; null when malformed. */
+export function parseWidgetRef(ref) {
+    if (!REF.test(ref))
+        return null;
+    const [pack, name, id] = ref.split('/');
+    return { key: `${pack}/${name}`, pack, name, id: id ?? null };
+}
+export function widgetEnabled(ui, ref) {
+    const r = parseWidgetRef(ref);
+    if (!r)
+        return false;
+    return installedWidgets(ui).some((w) => w.key === r.key && w.enabled);
+}
+/**
+ * The page to serve for a widget ref, or a refusal. Consent (enabled), integrity (the installed pack still hashes to
+ * its record), containment (the page is a plain file under the widget directory) and size are all re-checked at
+ * open time, not trusted from startup.
+ */
+export function widgetPage(ui, ref) {
+    const r = parseWidgetRef(ref);
+    if (!r)
+        return { ok: false, reason: `bad widget ref "${ref}" (<pack>/<widget>[/<id>])` };
+    const w = installedWidgets(ui).find((x) => x.key === r.key);
+    if (!w)
+        return { ok: false, reason: `no installed widget ${r.key} (dexterm pack list)` };
+    if (!w.enabled)
+        return { ok: false, reason: `${r.key} is not enabled (dexterm pack widget ${r.pack} ${r.name} --enable)` };
+    const rec = (ui?.config.packs ?? []).find((p) => p.name === r.pack);
+    if (!rec || !ui)
+        return { ok: false, reason: `pack ${r.pack} has no install record` };
+    const packDir = join(packsDir(ui.home), `${rec.name}@${rec.version}`);
+    const integ = checkIntegrity(packDir);
+    if (!integ.ok || integ.hash !== rec.hash)
+        return { ok: false, reason: `pack ${r.pack} changed since install (${integ.ok ? 'hash differs' : integ.reason}); re-install it` };
+    const spec = r.id ? w.manifest.widgets.find((x) => x.id === r.id) : w.manifest.widgets[0];
+    if (!spec)
+        return { ok: false, reason: `${r.key} has no widget "${r.id}" (${w.manifest.widgets.map((x) => x.id).join(', ')})` };
+    const path = resolve(w.dir, spec.page);
+    let root;
+    try {
+        root = realpathSync(w.dir);
+    }
+    catch {
+        return { ok: false, reason: `${r.key}: directory missing` };
+    }
+    if (!existsSync(path) || lstatSync(path).isSymbolicLink())
+        return { ok: false, reason: `${r.key}: page ${spec.page} is missing or a symlink` };
+    const real = realpathSync(path);
+    if (!real.startsWith(root + sep) || !lstatSync(real).isFile())
+        return { ok: false, reason: `${r.key}: page ${spec.page} is outside the widget directory` };
+    const html = readFileSync(real, 'utf8');
+    if (html.length > WIDGET_HTML_MAX)
+        return { ok: false, reason: `${r.key}: page is ${html.length} chars (max ${WIDGET_HTML_MAX})` };
+    // r2: install refused loaders already; a pack installed before that check (or a hash-valid page nobody re-inspected)
+    // is refused here too, with the reason, before the host ever sees it
+    const problems = auditWidgetHtml(html);
+    if (problems.length)
+        return { ok: false, reason: `${r.key}: page ${spec.page} refused: ${problems.join('; ')}` };
+    return { ok: true, page: { key: r.id ? `${r.key}/${r.id}` : `${r.key}/${spec.id}`, title: spec.title, topics: [...spec.topics], html } };
+}
+// ------------------------------------------------------------------ view models (public columns only)
+const FORBIDDEN_KEYS = /^(arm|armed|sign|signer|keys?|caps?|mandates?|gate|secret|token|apiKey|passphrase|seed|privateKey)$/i;
+export function widgetRowsVM(state) {
+    const rows = [];
+    const seen = new Set();
+    for (const r of state.screener.rows) {
+        if (!r.mint || r.skeleton || seen.has(r.mint))
+            continue;
+        seen.add(r.mint);
+        rows.push({
+            symbol: r.symbol, name: r.name, mint: r.mint, launchpad: r.launchpad,
+            price: r.price, mcap: r.mcap, liq: r.liq, vol5m: r.vol5m, vol1h: r.vol1h, vol24: r.vol24,
+            chg: { ...r.chg }, ageMin: r.ageMin, holders: r.holders, org: r.org, top10: r.top10,
+            flags: r.flags.map((f) => String(f)), verified: r.verified,
+        });
+        if (rows.length >= 200)
+            break;
+    }
+    return { feed: state.screener.preset, rows, updatedAt: state.now.getTime() };
+}
+export function widgetPositionsVM(state) {
+    const rows = [];
+    const live = state.live;
+    if (live) {
+        try {
+            for (const p of live.positions.view().rows)
+                rows.push({ symbol: p.symbol, mint: p.mint, side: 'long', tokens: p.tokens, valueSol: p.valueSol, unrealizedSol: p.unrealizedSol, unrealizedPct: p.unrealizedPct, book: 'paper' });
+        }
+        catch { /* no paper book on this run */ }
+        const lp = live.livePositions;
+        if (lp) {
+            try {
+                for (const p of lp.positions()) {
+                    if (p.tokensRaw <= 0n)
+                        continue;
+                    const h = lp.held(p.mint);
+                    rows.push({ symbol: p.symbol, mint: p.mint, side: 'long', tokens: h?.tokens ?? Number(p.tokensRaw) / 10 ** p.decimals, valueSol: null, unrealizedSol: null, unrealizedPct: null, book: 'live' });
+                }
+            }
+            catch { /* ledger unreadable */ }
+        }
+    }
+    return { rows, updatedAt: state.now.getTime() };
+}
+export function widgetAlertsVM(state, limit = 50) {
+    const items = [];
+    const now = state.now.getTime();
+    for (const l of state.rulesUi?.log ?? [])
+        if (l.kind === 'alert' || l.kind === 'proposal')
+            items.push({ at: l.at, level: l.level, kind: `rule:${l.kind}`, text: l.text, symbol: l.symbol || null });
+    const store = state.live?.watch.store;
+    if (store) {
+        try {
+            const symbolOf = (mint) => (mint ? state.screener.rows.find((r) => r.mint === mint)?.symbol ?? null : null);
+            for (const e of store.events(limit))
+                items.push({ at: e.t, level: e.level, kind: e.kind, text: e.text, symbol: symbolOf(e.mint) });
+        }
+        catch { /* store closed */ }
+    }
+    else {
+        for (const a of state.fx.alerts)
+            items.push({ at: now - a.ago * 1000, level: a.level, kind: a.kind, text: a.text, symbol: null });
+    }
+    items.sort((a, b) => b.at - a.at);
+    return { items: items.slice(0, limit), updatedAt: now };
+}
+/** The payload for one topic right now, or null when that topic has nothing yet (token with no coin open, narrative before the board). */
+export function widgetPayload(state, topic, deps = {}) {
+    switch (topic) {
+        case 'rows': return widgetRowsVM(state);
+        case 'token': return deps.token?.() ?? null;
+        case 'narrative': return deps.narrative?.() ?? null;
+        case 'positions': return widgetPositionsVM(state);
+        case 'alerts': return widgetAlertsVM(state);
+        case 'theme': return popupThemeFrom(state.theme);
+        default: return null;
+    }
+}
+/** Defence in depth for tests and the sync path: no money-shaped key anywhere in a payload. */
+export function payloadKeys(v, acc = []) {
+    if (v && typeof v === 'object')
+        for (const [k, x] of Object.entries(v)) {
+            acc.push(k);
+            payloadKeys(x, acc);
+        }
+    return acc;
+}
+export function payloadIsPublic(v) { return !payloadKeys(v).some((k) => FORBIDDEN_KEYS.test(k)); }
+/** Minimum spacing between pushes of the same topic to the same widget (rows refresh every 10 s anyway). */
+export const WIDGET_SYNC_MS = 1000;
+/**
+ * Push fresh view models to every open widget (self-throttled per widget+topic). `force` ignores the throttle
+ * (first paint after `ready`, a theme change). Pure over the controller: a missing controller is a no-op.
+ */
+export function syncWidgetPopups(state, deps = {}, opts = {}) {
+    const p = state.popups;
+    if (!p?.openWidgets || !p.syncWidget)
+        return 0;
+    const open = p.openWidgets();
+    if (!open.length)
+        return 0;
+    const now = state.now.getTime();
+    const stamps = (state.widgetSync ??= new Map());
+    const cache = new Map();
+    let pushed = 0;
+    for (const w of open) {
+        if (opts.only && w.key !== opts.only)
+            continue;
+        for (const topic of w.topics) {
+            if (opts.topics && !opts.topics.includes(topic))
+                continue;
+            const stampKey = `${w.key}|${topic}`;
+            if (!opts.force && now - (stamps.get(stampKey) ?? -Infinity) < WIDGET_SYNC_MS)
+                continue;
+            if (!cache.has(topic))
+                cache.set(topic, widgetPayload(state, topic, deps));
+            const payload = cache.get(topic) ?? null;
+            if (!payload || !payloadIsPublic(payload))
+                continue;
+            p.syncWidget(w.key, topic, payload);
+            stamps.set(stampKey, now);
+            pushed++;
+        }
+    }
+    return pushed;
+}

package/dist/packages/cli/src/workspace-cmd.js

@@ -0,0 +1,68 @@
+// `dexterm workspace <list|show|remove|init> …` (task-1358 Tier 1): the workspace files under
+// ~/.dexterm/workspaces/ (DEXTERM_HOME overrides). No network, no model, never touches a key file.
+//   list            built-ins + files, with errors for files that do not validate
+//   show <name>     print the workspace JSON (a built-in prints its generated form)
+//   remove <name>   delete a user file (built-ins cannot be removed)
+//   init            write `default` as an editable file with the shipped layout trees, if it does not exist
+import { listWorkspaces, readWorkspace, removeWorkspace, writeWorkspace, dextermHome, builtinScreens, defaultWorkspace, workspacesDir } from '../../custom/src/index.js';
+export const WORKSPACE_USAGE = `usage: dexterm workspace list | show <name> | remove <name> | init
+  files: ~/.dexterm/workspaces/<name>.json (DEXTERM_HOME overrides); in the app: ctrl+w then w/n/N/s/m/o/d/1-9, or --workspace <name>`;
+export async function workspaceCommand(argv, io) {
+    const home = dextermHome(io.env);
+    const [cmd, name] = argv;
+    const bad = (s) => { io.stderr.write(`dexterm workspace: ${s}\n${WORKSPACE_USAGE}\n`); return 2; };
+    switch (cmd) {
+        case undefined:
+        case 'list': {
+            const list = listWorkspaces(home);
+            io.stdout.write(`${workspacesDir(home)}\n`);
+            for (const w of list) {
+                const tag = w.builtin ? 'built-in' : 'file';
+                const what = w.error ? `⚠ ${w.error}` : [w.workspace.description, w.workspace.start ? `starts on ${w.workspace.start}` : null, w.workspace.theme ? `theme ${w.workspace.theme}` : null, w.workspace.popups?.length ? `${w.workspace.popups.length} popup(s): ${w.workspace.popups.map((p) => p.kind).join(', ')}` : null].filter(Boolean).join(' · ');
+                io.stdout.write(`  ${w.name.padEnd(24)} ${tag.padEnd(9)} ${what}\n`);
+            }
+            return 0;
+        }
+        case 'show': {
+            if (!name)
+                return bad('show needs a name');
+            const ws = readWorkspace(home, name);
+            if (!ws) {
+                io.stderr.write(`dexterm workspace: no workspace "${name}" (see: dexterm workspace list)\n`);
+                return 1;
+            }
+            io.stdout.write(JSON.stringify(ws, null, 2) + '\n');
+            return 0;
+        }
+        case 'remove': {
+            if (!name)
+                return bad('remove needs a name');
+            const entry = listWorkspaces(home).find((w) => w.name === name);
+            if (!entry) {
+                io.stderr.write(`dexterm workspace: no workspace "${name}"\n`);
+                return 1;
+            }
+            if (entry.builtin) {
+                io.stderr.write(`dexterm workspace: "${name}" is built in; it cannot be removed (save a file with that name to override it)\n`);
+                return 1;
+            }
+            if (!removeWorkspace(home, name)) {
+                io.stderr.write(`dexterm workspace: could not remove ${entry.path}\n`);
+                return 1;
+            }
+            io.stdout.write(`removed ${entry.path}\n`);
+            return 0;
+        }
+        case 'init': {
+            const existing = listWorkspaces(home).find((w) => w.name === 'default' && !w.builtin);
+            if (existing) {
+                io.stdout.write(`${existing.path} already exists\n`);
+                return 0;
+            }
+            const path = writeWorkspace(home, { ...defaultWorkspace(), description: 'The shipped layout as editable pane trees (dexterm workspace init)', screens: builtinScreens() });
+            io.stdout.write(`wrote ${path}\n  edit the trees (weight / fixed / priority / collapseBelow), then ctrl+w d in the app or --workspace default\n`);
+            return 0;
+        }
+        default: return bad(`unknown subcommand "${cmd}"`);
+    }
+}

package/dist/packages/cli/src/x-cmd.js

@@ -0,0 +1,154 @@
+// dexterm — `dexterm x <status|set-client-id|login|logout>` (task-1357, lane I-02). Login with X through
+// OAuth 2.0 PKCE on the fixed loopback callback; each user brings their OWN X app Client ID (their developer
+// account, their rate limits, their bill). Tokens live in ~/.dexterm/x/tokens.json (0600) and are never
+// printed: `status` shows the handle, scopes, ages and file modes only. No `.write`/`dm.*` scope is ever
+// requested; dexterm never posts.
+import { XOAuth, XTokenStore, XAuthError, XApi, XSource, XSpendMeter, KolStore, X_SCOPES, callbackUri, redactXSecrets } from '../../data/src/index.js';
+export const X_HELP = `  dexterm x status             Login with X: client id stored? logged in as @handle? scopes, expiry, file modes
+  dexterm x set-client-id      store YOUR X app's Client ID (prompted on the terminal, or one line on stdin with --stdin)
+  dexterm x login              OAuth2 PKCE in your browser → tokens in ~/.dexterm/x/tokens.json (0600); read scopes only
+  dexterm x logout             revoke both tokens at X and delete the local record`;
+const fmtIn = (ms) => {
+    if (ms <= 0)
+        return 'expired';
+    const m = Math.round(ms / 60_000);
+    return m < 60 ? `${m} min` : `${Math.round(m / 6) / 10} h`;
+};
+/** Read one line from stdin (piped) or the TTY. Never echoes it back. */
+function readLine(io, prompt) {
+    const stdin = io.stdin;
+    if (!stdin)
+        return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let buf = '';
+        let done = false;
+        const finish = (v) => { if (done)
+            return; done = true; try {
+            stdin.off?.('data', onData);
+        }
+        catch { /* ignore */ } try {
+            stdin.pause?.();
+        }
+        catch { /* ignore */ } resolve(v); };
+        const onData = (chunk) => { buf += chunk.toString(); const nl = buf.indexOf('\n'); if (nl >= 0)
+            finish(buf.slice(0, nl).trim()); };
+        if (stdin.isTTY)
+            io.stderr.write(prompt);
+        stdin.setEncoding?.('utf8');
+        stdin.on('data', onData);
+        stdin.once?.('end', () => finish(buf.trim() || null));
+        stdin.resume?.();
+    });
+}
+function printStatus(io, store, now) {
+    const meta = store.meta();
+    const modes = store.modes();
+    const clientId = store.clientId(io.env);
+    const oct = (m) => (m === null ? '—' : m.toString(8).padStart(3, '0'));
+    io.stdout.write(`client id: ${clientId ? `stored (${io.env.DEXTERM_X_CLIENT_ID ? 'DEXTERM_X_CLIENT_ID' : store.clientIdPath})` : 'missing — run `dexterm x set-client-id` (create a Native App with callback ' + callbackUri() + ' in your X developer portal)'}\n`);
+    if (!meta.loggedIn) {
+        io.stdout.write(`login: not logged in — run \`dexterm x login\`${clientId ? '' : ' after storing the client id'}\n`);
+    }
+    else {
+        io.stdout.write(`login: ${meta.user ? `@${meta.user.username} (id ${meta.user.id})` : 'logged in (handle unknown)'} · scopes ${meta.scopes.join(' ') || '—'} · access token ${meta.expiresAt !== null ? (meta.expiresAt > now ? `valid ${fmtIn(meta.expiresAt - now)}` : 'expired (refreshes on next use)') : '?'} · refresh ${meta.hasRefresh ? 'yes' : 'no (login again)'}\n`);
+    }
+    io.stdout.write(`files: ${store.dir} (mode ${oct(modes.dir)}) · tokens.json ${modes.tokens === null ? 'absent' : `mode ${oct(modes.tokens)}`} · client-id ${modes.clientId === null ? 'absent' : `mode ${oct(modes.clientId)}`}\n`);
+    if ((modes.tokens !== null && modes.tokens !== 0o600) || (modes.dir !== null && modes.dir !== 0o700))
+        io.stderr.write('⚠ permissions are looser than 0600/0700; dexterm will tighten them on the next write (or chmod them now)\n');
+    io.stdout.write(`callback: ${callbackUri()} · tokens are never printed, logged, or sent to a model · X reads are user-context only (your rate limits, your bill)\n`);
+}
+/** Run the `x` subcommand. Returns a process exit code. */
+export async function runX(argv, io, over = {}) {
+    const sub = argv[0] ?? 'status';
+    const store = over.store ?? new XTokenStore({ env: io.env });
+    const now = over.now ?? (() => Date.now());
+    if (sub === 'status') {
+        printStatus(io, store, now());
+        return 0;
+    }
+    if (sub === 'set-client-id') {
+        const useStdin = argv.includes('--stdin');
+        if (!useStdin && !(io.stdin && io.stdin.isTTY)) {
+            io.stderr.write('dexterm x set-client-id: paste the id on a terminal, or pipe ONE line with --stdin (never put it on the command line)\n');
+            return 2;
+        }
+        const v = await readLine(io, 'paste your X app Client ID and press enter: ');
+        if (!v) {
+            io.stderr.write('dexterm x set-client-id: nothing read\n');
+            return 2;
+        }
+        try {
+            store.setClientId(v);
+        }
+        catch (e) {
+            io.stderr.write(`dexterm x set-client-id: ${e instanceof Error ? e.message : String(e)}\n`);
+            return 2;
+        }
+        io.stdout.write(`stored (${v.length} chars) at ${store.clientIdPath} (mode 600). Next: dexterm x login\n`);
+        return 0;
+    }
+    if (sub === 'login') {
+        const oauth = new XOAuth({ store, endpoints: over.endpoints, open: over.open, port: over.port, loginTimeoutMs: over.loginTimeoutMs, now: over.now });
+        if (!store.clientId(io.env)) {
+            io.stderr.write(`dexterm x login: no client id stored. Create a Native App (OAuth 2.0, callback ${callbackUri(over.port)}) in your X developer portal, then run \`dexterm x set-client-id\`.\n`);
+            return 2;
+        }
+        io.stdout.write(`Opening your browser to X (scopes: ${X_SCOPES.join(' ')} — read only; dexterm never posts). Callback ${callbackUri(over.port)}.\n`);
+        const t = setTimeout(() => { if (oauth.lastAuthorizeUrl)
+            io.stderr.write(`If the browser did not open, paste this URL into it:\n${oauth.lastAuthorizeUrl}\n`); }, 4000);
+        t.unref?.();
+        try {
+            const res = await oauth.login({ env: io.env });
+            clearTimeout(t);
+            io.stdout.write(`✓ logged in${res.user ? ` as @${res.user.username}` : ''} · scopes ${res.scopes.join(' ')} · access token valid ${fmtIn(res.expiresAt - now())} · refresh ${res.hasRefresh ? 'yes' : 'no'} · browser ${Math.round(res.callbackMs / 100) / 10}s · exchange ${res.exchangeMs}ms\n`);
+            io.stdout.write(`tokens: ${store.tokensPath} (mode 600). The SOCIAL panel and TRENDING board now read X with your own limits.\n`);
+            return 0;
+        }
+        catch (e) {
+            clearTimeout(t);
+            const msg = e instanceof Error ? e.message : String(e);
+            io.stderr.write(`dexterm x login failed: ${redactXSecrets(msg)}\n`);
+            if (e instanceof XAuthError && e.kind === 'exchange' && /invalid_client/.test(msg))
+                io.stderr.write('  the Client ID is not one X recognises — check the app in your developer portal and re-run `dexterm x set-client-id`\n');
+            if (e instanceof XAuthError && e.kind === 'port-busy')
+                io.stderr.write(`  port ${over.port ?? 41287} is in use; close the other login (or the process on that port) and retry\n`);
+            return 1;
+        }
+    }
+    if (sub === 'logout') {
+        const oauth = new XOAuth({ store, endpoints: over.endpoints, open: over.open, port: over.port, now: over.now });
+        const out = await oauth.logout(io.env);
+        if (!out.hadTokens) {
+            io.stdout.write('not logged in; nothing to revoke.\n');
+            return 0;
+        }
+        const parts = Object.entries(out.revoked).map(([k, s]) => `${k.replace('_token', '')} ${s === 200 ? 'revoked' : s === 0 ? 'unreachable' : `HTTP ${s}`}`);
+        io.stdout.write(`✓ logged out · ${parts.join(' · ') || 'nothing to revoke'} · local tokens deleted. You can also check x.com/settings/connected_apps.\n`);
+        return 0;
+    }
+    io.stderr.write(`dexterm x: unknown subcommand ${JSON.stringify(sub)} (expected status | set-client-id | login | logout)\n`);
+    return 2;
+}
+/**
+ * `dexterm kol import-x` (task-1357): the user's OWN X lists → `own-x-list` KOL lists (handles only). Needs a
+ * login; a degraded X (401/429/403/budget) is reported as text, never as an empty import.
+ */
+export async function importOwnXLists(opts) {
+    const store = opts.store ?? new XTokenStore({ env: opts.env });
+    if (!store.meta().loggedIn)
+        return { ok: false, error: 'not logged in to X — run `dexterm x login` first (your own X app, read scopes only)' };
+    const oauth = new XOAuth({ store, endpoints: opts.endpoints, now: opts.now });
+    const api = new XApi({ oauth, endpoints: opts.endpoints, cache: opts.cache, spend: new XSpendMeter({ cache: opts.cache, env: opts.env, now: opts.now }), env: opts.env });
+    const kol = new KolStore({ cache: opts.cache });
+    const x = new XSource({ api, store, kol, now: opts.now });
+    try {
+        const r = await x.importOwnLists();
+        return { ok: true, lists: r.lists };
+    }
+    catch (e) {
+        return { ok: false, error: redactXSecrets(e instanceof Error ? e.message : String(e)) };
+    }
+    finally {
+        x.close();
+    }
+}