dexterm-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,131 @@
+// `dexterm rules <list|add|remove|enable|disable|check|dry-run|fields> …` (task-1358 Tier 3). No network, no
+// model, never touches a key file. Rules live in ~/.dexterm/config.json `rules[]`; every change goes through the
+// config journal (actor user) so `config.journal.jsonl` records it with its inverse.
+//   rules list                      every rule with enabled / when / then / source (+ the ones that fail to load)
+//   rules add "<rule text>"         parse (never eval), validate against the schema, append; refuses money-shaped args
+//   rules remove|enable|disable <id>
+//   rules check "<rule text>"       parse + show the JSON the config would store; exit 1 on a refusal
+//   rules dry-run "<rule text>"     "would match N rows" against the demo fixture rows (flat history: velocity = 1)
+//   rules fields                    the field / signal / tag / action vocabulary
+import { dextermHome, loadConfig, applyAndJournal, RulesEngine, ruleToJson, ruleToText, describeActions, FIELD_NAMES, TAG_NAMES, ACTIONS, SCOPES, RULE_POPUP_KINDS, MAX_PER_HOUR_CAP, TICKET_SIZE_CAP, slug } from '../../custom/src/index.js';
+export const RULES_USAGE = `usage: dexterm rules list | add "<rule>" | remove <id> | enable <id> | disable <id> | check "<rule>" | dry-run "<rule>" | fields
+  rule: [when] <cond> [for <n> ticks|<n>s|<n>m] then <action>+ [cooldown <dur>] [max <n>/h] [scope screener|watchlist|newpairs|positions|mint:<addr>] [window <dur>] [name "<s>"]
+  e.g.: dexterm rules add 'vol5m.velocity > 3 and cluster < 20 and liq > 25K for 2 ticks then alert(up, "surge") popup(chart) name "surge"'
+  actions only alert, annotate, open UI or PROPOSE (ticket/ask cards need your keypress; the paper ticket editor is where you confirm)`;
+export async function rulesCommand(argv, io) {
+    const home = dextermHome(io.env);
+    const [cmd, arg] = argv;
+    const bad = (s) => { io.stderr.write(`dexterm rules: ${s}\n${RULES_USAGE}\n`); return 2; };
+    const cfg = loadConfig(home);
+    for (const e of cfg.errors)
+        io.stderr.write(`dexterm rules: config: ${e}\n`);
+    const rules = cfg.config.rules ?? [];
+    switch (cmd) {
+        case undefined:
+        case 'list': {
+            io.stdout.write(`${cfg.path}${cfg.missing ? ' (no config: no rules)' : ''} · ${rules.length} rule(s)\n`);
+            const e = new RulesEngine({ rules });
+            for (const r of e.rules)
+                io.stdout.write(`  ${(r.enabled ? 'on ' : 'off')} ${r.id.padEnd(24)} when ${r.whenText}${r.for ? ` for ${'ticks' in r.for ? r.for.ticks + ' ticks' : Math.round(r.for.ms / 1000) + 's'}` : ''} → ${describeActions(r)} · ${r.source} · cooldown ${Math.round(r.cooldownMs / 60000)}m · max ${r.maxPerHour}/h · scope ${r.scope}\n`);
+            for (const x of e.errors)
+                io.stdout.write(`  ⚠   ${x.id.padEnd(24)} ${x.msg}\n`);
+            return 0;
+        }
+        case 'add': {
+            if (!arg)
+                return bad('add needs the rule text in quotes');
+            let json;
+            try {
+                json = ruleToJson(arg);
+            }
+            catch (e) {
+                io.stderr.write(`dexterm rules: refused: ${e.message}\n`);
+                return 1;
+            }
+            const taken = new Set(rules.map((r) => r.id));
+            let id = json.id;
+            let n = 2;
+            while (taken.has(id))
+                id = slug(`${json.id}-${n++}`);
+            json.id = id;
+            try {
+                applyAndJournal(home, [{ op: 'add', path: '/rules/-', value: json }], { actor: 'user', why: `dexterm rules add ${id}` });
+            }
+            catch (e) {
+                io.stderr.write(`dexterm rules: not saved: ${e.message}\n`);
+                return 1;
+            }
+            io.stdout.write(`added rule ${id}: ${ruleToText(json)}\n`);
+            return 0;
+        }
+        case 'remove':
+        case 'enable':
+        case 'disable': {
+            if (!arg)
+                return bad(`${cmd} needs a rule id`);
+            const i = rules.findIndex((r) => r.id === arg);
+            if (i < 0) {
+                io.stderr.write(`dexterm rules: no rule "${arg}"\n`);
+                return 1;
+            }
+            const ops = cmd === 'remove' ? [{ op: 'remove', path: `/rules/${i}` }] : [{ op: 'replace', path: `/rules/${i}/enabled`, value: cmd === 'enable' }];
+            try {
+                applyAndJournal(home, ops, { actor: 'user', why: `dexterm rules ${cmd} ${arg}` });
+            }
+            catch (e) {
+                io.stderr.write(`dexterm rules: not changed: ${e.message}\n`);
+                return 1;
+            }
+            io.stdout.write(`${cmd === 'remove' ? 'removed' : cmd + 'd'} rule ${arg}\n`);
+            return 0;
+        }
+        case 'check': {
+            if (!arg)
+                return bad('check needs the rule text in quotes');
+            try {
+                const json = ruleToJson(arg);
+                const e = new RulesEngine();
+                e.load(json);
+                io.stdout.write(`ok: ${ruleToText(json)}\n${JSON.stringify(json, null, 2)}\n`);
+                return 0;
+            }
+            catch (e) {
+                io.stdout.write(`✗ ${e.message}\n`);
+                return 1;
+            }
+        }
+        case 'dry-run': {
+            if (!arg)
+                return bad('dry-run needs the rule text in quotes');
+            const { makeFixtureState } = await import("./state.js");
+            const st = makeFixtureState();
+            const rows = st.screener.rows.filter((r) => !r.skeleton);
+            const e = new RulesEngine();
+            const t0 = Date.now() - 30_000;
+            for (let i = 0; i < 3; i++)
+                e.observe(rows, t0 + i * 10_000); // flat history so velocity/delta are defined (1 / 0)
+            const d = e.dryRun(arg, rows, t0 + 30_000);
+            if (d.error) {
+                io.stdout.write(`✗ ${d.error}\n`);
+                return 1;
+            }
+            io.stdout.write(`would match ${d.matches.length} of ${d.considered} demo rows right now (fixture data, flat history) → ${describeActions(d.rule)}\n`);
+            for (const m of d.matches)
+                io.stdout.write(`  ${m.symbol.padEnd(8)} ${m.reasons.map((r) => `${r.clause} (${r.value})`).join(', ')}\n`);
+            if (d.noHistory)
+                io.stdout.write(`  (${d.noHistory} rows had no history for a derived signal)\n`);
+            return 0;
+        }
+        case 'fields': {
+            io.stdout.write(`fields:  ${FIELD_NAMES.join(' ')}\n`);
+            io.stdout.write(`aliases: vol volume liquidity cap mc holder organic top locked cluster% clusterpct\n`);
+            io.stdout.write(`signals: <field>.velocity (current ÷ mean of earlier samples in the window) · <field>.delta (current − oldest in the window)\n`);
+            io.stdout.write(`tags:    ${TAG_NAMES.map((t) => t + ':').join(' ')}  (e.g. launchpad:pump flag:mint flag:clean verified:yes sus:no; prefix ! to negate)\n`);
+            io.stdout.write(`values:  $1.5M 25K 2B 20% 2h 30m 3d · ops > >= < <= = != · and or not ( )\n`);
+            io.stdout.write(`actions: ${ACTIONS.join(' ')}  alert(level, "text") ticket(buy|sell, size ≤ ${TICKET_SIZE_CAP}, sol|usd|pct) ask(skill) popup(${RULE_POPUP_KINDS.join('|')}) tag("label") sound(name) watch\n`);
+            io.stdout.write(`limits:  cooldown (default 10m) · max n/h (default 12, cap ${MAX_PER_HOUR_CAP}) · scope ${SCOPES.join('|')}|mint:<addr> · window (default 10m)\n`);
+            return 0;
+        }
+        default: return bad(`unknown subcommand "${cmd}"`);
+    }
+}

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

@@ -0,0 +1,339 @@
+import { RulesEngine, ruleToJson, ruleToText, slug, applyAndJournal, describeActions, } from '../../custom/src/index.js';
+export const RULE_INPUT_MAX = 400;
+/** The engine observes/evaluates at most this often (the feed itself moves every 10 s; fixtures drift every tick). */
+export const RULES_TICK_MS = 2_000;
+export const MAX_LOG = 60;
+export const MAX_PROPOSALS = 20;
+export function newRulesUi(engine = new RulesEngine()) {
+    return {
+        engine, errors: [], pane: 'rules', selected: 0, selectedProposal: 0, input: null, editingId: null, dry: null, notice: null,
+        log: [], proposals: [], pending: { popups: [], bells: 0, ask: null, ticket: null }, lastTickAt: 0, nextId: 1, fires: 0,
+    };
+}
+/**
+ * Build the engine from `config.rules` plus the rules of installed packs (task-1358 Tier 4: a pack rule whose id the
+ * user already has in config.rules is shadowed by the user's copy). Bad rules are reported, good ones run. Never throws.
+ */
+export function initRules(custom, now = Date.now()) {
+    const own = custom?.config.rules ?? [];
+    const ids = new Set(own.map((r) => r.id));
+    const rules = [...own, ...(custom?.packRules ?? []).filter((r) => !ids.has(r.id))];
+    const engine = new RulesEngine({ rules, now });
+    const ui = newRulesUi(engine);
+    ui.errors = engine.errors.map((e) => `rule ${e.id}: ${e.msg}`);
+    if (custom)
+        for (const e of ui.errors)
+            if (!custom.configErrors.includes(e))
+                custom.configErrors.push(e);
+    return ui;
+}
+/** The rules state for this run, created from the loaded config on first use. */
+export function rulesUiOf(state) {
+    if (!state.rulesUi)
+        state.rulesUi = initRules(state.custom, state.now.getTime());
+    return state.rulesUi;
+}
+/** The rows a rule can see: the screener feed (no skeletons) with the wallet-intel top-cluster share attached when the scan ran. */
+export function ruleRowsOf(state) {
+    const out = [];
+    const seen = new Set();
+    const clusterOf = (mint) => {
+        const res = state.live?.intel.entry(mint)?.result;
+        if (!res || res.state !== 'ok')
+            return null;
+        const c = res.analysis.clusters[0];
+        return c ? c.pct : null;
+    };
+    for (const r of state.screener.rows) {
+        if (!r.mint || r.skeleton || seen.has(r.mint))
+            continue;
+        seen.add(r.mint);
+        out.push(Object.assign(Object.create(null), r, { cluster: clusterOf(r.mint) }));
+    }
+    return out;
+}
+/**
+ * One engine tick: observe the rows, evaluate, and turn the outputs into app state. Self-throttled to RULES_TICK_MS.
+ * Alerts become the first pending toast + log lines; ticket/ask become PROPOSAL cards; watch/tag touch the user's
+ * own watchlist (live mode) or just the log; popup/sound queue UI work for the loop. Returns null when throttled.
+ */
+export function rulesTick(state, now) {
+    const ui = state.rulesUi;
+    if (!ui || !ui.engine.rules.some((r) => r.enabled))
+        return null;
+    if (now - ui.lastTickAt < RULES_TICK_MS)
+        return null;
+    ui.lastTickAt = now;
+    const rows = ruleRowsOf(state);
+    if (!rows.length)
+        return null;
+    ui.engine.observe(rows, now);
+    const watch = state.live?.watch.store ?? null;
+    const positions = state.live?.positions ?? null;
+    const res = ui.engine.evaluate(rows, now, {
+        watchlist: watch ? { has: (m) => watch.has(m) } : undefined,
+        positions: positions ? { has: (m) => positions.held(m) !== null } : undefined,
+    });
+    const summary = applyOutputs(state, ui, res, rows, now);
+    if (ui.input !== null)
+        ui.dry = ui.engine.dryRun(ui.input, rows, now);
+    return summary;
+}
+function applyOutputs(state, ui, res, rows, now) {
+    const summary = { fired: res.fired.length, alerts: [], proposals: 0, suppressed: res.suppressed.length };
+    const rowOf = (mint) => rows.find((r) => r.mint === mint);
+    const push = (e) => { ui.log.unshift(e); if (ui.log.length > MAX_LOG)
+        ui.log.length = MAX_LOG; };
+    ui.fires += res.fired.length;
+    for (const f of res.fired) {
+        for (const a of f.actions) {
+            const base = { at: now, rule: f.rule, name: f.name, source: f.source, mint: f.mint, symbol: f.symbol };
+            if (a.kind === 'alert') {
+                push({ ...base, kind: 'alert', level: a.level, text: a.text });
+                summary.alerts.push(`${f.symbol}: ${a.text}`);
+            }
+            else if (a.kind === 'proposal') {
+                const card = a.type === 'ticket'
+                    ? { id: ui.nextId++, ...base, type: 'ticket', side: a.side, size: a.size, unit: a.unit, why: a.why, status: 'proposal', requiresKeypress: true, armedBy: null }
+                    : { id: ui.nextId++, ...base, type: 'ask', skill: a.skill, why: a.why, status: 'proposal', requiresKeypress: true, armedBy: null };
+                ui.proposals.unshift(card);
+                if (ui.proposals.length > MAX_PROPOSALS)
+                    ui.proposals.length = MAX_PROPOSALS;
+                summary.proposals += 1;
+                push({ ...base, kind: 'proposal', level: 'info', text: `PROPOSAL ${describeCard(card)} — ctrl+r, tab, ⏎ to act (you confirm there)` });
+            }
+            else if (a.kind === 'annotation') {
+                const store = state.live?.watch.store ?? null;
+                const row = rowOf(f.mint);
+                if (a.type === 'watch') {
+                    if (store && !store.has(f.mint) && row) {
+                        const r = row;
+                        store.add({ mint: r.mint, symbol: r.symbol, name: r.name ?? r.symbol, launchpad: r.launchpad ?? 'unknown', entryPrice: r.price ?? null, note: `rule:${f.rule}` });
+                        push({ ...base, kind: 'annotation', level: 'info', text: `watch: added ${f.symbol} to the watchlist (rule ${f.rule})` });
+                    }
+                    else
+                        push({ ...base, kind: 'annotation', level: 'info', text: store ? `watch: ${f.symbol} already on the watchlist` : `watch: ${f.symbol} (watchlist needs live mode)` });
+                }
+                else {
+                    if (store && store.has(f.mint)) {
+                        store.setNote(f.mint, `rule:${f.rule} ${a.label}`.slice(0, 80));
+                        push({ ...base, kind: 'annotation', level: 'info', text: `tag "${a.label}" on ${f.symbol} (watchlist note)` });
+                    }
+                    else
+                        push({ ...base, kind: 'annotation', level: 'info', text: `tag "${a.label}" on ${f.symbol}` });
+                }
+            }
+            else if (a.kind === 'ui') {
+                if (a.type === 'popup') {
+                    ui.pending.popups.push({ kind: a.popup, mint: f.mint, symbol: f.symbol, rule: f.rule });
+                    push({ ...base, kind: 'ui', level: 'info', text: `popup ${a.popup} for ${f.symbol}` });
+                }
+                else {
+                    ui.pending.bells += 1;
+                    push({ ...base, kind: 'ui', level: 'info', text: `sound ${a.name}` });
+                }
+            }
+        }
+    }
+    if (summary.alerts.length)
+        state.pendingToast = summary.alerts.length === 1 ? `⚑ ${summary.alerts[0]}` : `⚑ ${summary.alerts[0]} (+${summary.alerts.length - 1} more · ctrl+r)`;
+    else if (summary.proposals)
+        state.pendingToast = `⚑ ${summary.proposals} rule proposal${summary.proposals > 1 ? 's' : ''} · ctrl+r then tab to review (nothing armed)`;
+    return summary;
+}
+export function describeCard(c) {
+    return c.type === 'ticket' ? `ticket ${c.side.toUpperCase()} ${c.size} ${c.unit} on ${c.symbol}` : `ask ${c.skill} about ${c.symbol}`;
+}
+// ------------------------------------------------------------------ editing + persistence
+export function selectedRule(ui) {
+    const rules = ui.engine.rules;
+    if (!rules.length)
+        return null;
+    return rules[Math.max(0, Math.min(rules.length - 1, ui.selected))] ?? null;
+}
+export function selectedProposal(ui) {
+    if (!ui.proposals.length)
+        return null;
+    return ui.proposals[Math.max(0, Math.min(ui.proposals.length - 1, ui.selectedProposal))] ?? null;
+}
+/** Re-run the dry-run of the text being typed against the current rows. */
+export function dryRunNow(state) {
+    const ui = state.rulesUi;
+    if (!ui || ui.input === null)
+        return;
+    const text = ui.input.trim();
+    if (!text) {
+        ui.dry = null;
+        return;
+    }
+    ui.dry = ui.engine.dryRun(text, ruleRowsOf(state), state.now.getTime());
+}
+/** Begin typing: a new rule, or the selected rule's text when `edit` is set. */
+export function beginRuleInput(ui, edit) {
+    if (edit) {
+        const r = selectedRule(ui);
+        if (!r) {
+            ui.notice = 'no rule selected';
+            return;
+        }
+        ui.editingId = r.id;
+        ui.input = ruleToText(compiledToJson(r));
+    }
+    else {
+        ui.editingId = null;
+        ui.input = '';
+    }
+    ui.dry = null;
+    ui.notice = null;
+}
+function compiledToJson(r) {
+    const json = { id: r.id, name: r.name, enabled: r.enabled, when: r.whenText, then: r.then.map((a) => ({ action: a.action, args: { ...a.args } })), scope: r.scope, cooldown: msToDur(r.cooldownMs), maxPerHour: r.maxPerHour, window: msToDur(r.windowMs), source: r.source };
+    if (r.for)
+        json.for = 'ticks' in r.for ? `${r.for.ticks} ticks` : msToDur(r.for.ms);
+    return json;
+}
+function msToDur(ms) { return ms % 3_600_000 === 0 && ms > 0 ? `${ms / 3_600_000}h` : ms % 60_000 === 0 && ms > 0 ? `${ms / 60_000}m` : `${Math.round(ms / 1000)}s`; }
+/** Persist one change to `config.rules` through the journal (actor: user). Throws with a reason when it cannot. */
+function persist(state, ops, why) {
+    const custom = state.custom;
+    if (!custom)
+        throw new Error('no config loaded (one-shot frame)');
+    const { config } = applyAndJournal(custom.home, ops, { actor: 'user', why, now: state.now.getTime() });
+    custom.config = config;
+}
+function ruleIndex(state, id) { return (state.custom?.config.rules ?? []).findIndex((r) => r.id === id); }
+/** Save the text being typed: parse → JSON → config (add or replace) → engine. Returns the notice. */
+export function saveRuleInput(state) {
+    const ui = rulesUiOf(state);
+    const text = (ui.input ?? '').trim();
+    const editingId = ui.editingId;
+    ui.input = null;
+    ui.editingId = null;
+    ui.dry = null;
+    if (!text)
+        return 'nothing saved (empty rule)';
+    let json;
+    try {
+        const existing = editingId ? ui.engine.get(editingId) : null;
+        json = ruleToJson(text, { id: editingId ?? undefined, source: existing?.source ?? 'user', enabled: existing ? existing.enabled : true });
+        if (!editingId) {
+            // a new rule never overwrites another one: bump the slug until it is free
+            const taken = new Set([...ui.engine.rules.map((r) => r.id), ...(state.custom?.config.rules ?? []).map((r) => r.id)]);
+            let id = json.id;
+            let n = 2;
+            while (taken.has(id))
+                id = slug(`${json.id}-${n++}`);
+            json.id = id;
+        }
+        if (json.source !== 'user')
+            json.source = 'user'; // an edited pack/jarvis rule becomes the user's own (it no longer matches the pack)
+        const probe = new RulesEngine();
+        probe.load(json);
+    }
+    catch (e) {
+        return `not saved: ${e.message}`;
+    }
+    try {
+        if (editingId) {
+            const i = ruleIndex(state, editingId);
+            persist(state, i >= 0 ? [{ op: 'replace', path: `/rules/${i}`, value: json }] : [{ op: 'add', path: '/rules/-', value: json }], `edit rule ${json.id}`);
+        }
+        else
+            persist(state, [{ op: 'add', path: '/rules/-', value: json }], `add rule ${json.id}`);
+    }
+    catch (e) {
+        const msg = e.message;
+        if (!/no config loaded/.test(msg))
+            return `not saved: ${msg}`;
+        ui.engine.load(json);
+        return `rule ${json.id} loaded for this run only (${msg})`;
+    }
+    ui.engine.load(json);
+    ui.selected = Math.max(0, ui.engine.rules.findIndex((r) => r.id === json.id));
+    return `${editingId ? 'updated' : 'saved'} rule ${json.id}: ${describeActions(ui.engine.get(json.id))}`;
+}
+export function removeSelectedRule(state) {
+    const ui = rulesUiOf(state);
+    const r = selectedRule(ui);
+    if (!r)
+        return 'no rule selected';
+    try {
+        const i = ruleIndex(state, r.id);
+        if (i >= 0)
+            persist(state, [{ op: 'remove', path: `/rules/${i}` }], `remove rule ${r.id}`);
+    }
+    catch (e) {
+        if (!/no config loaded/.test(e.message))
+            return `not removed: ${e.message}`;
+    }
+    ui.engine.remove(r.id);
+    ui.selected = Math.max(0, Math.min(ui.engine.rules.length - 1, ui.selected));
+    return `removed rule ${r.id}`;
+}
+export function toggleSelectedRule(state) {
+    const ui = rulesUiOf(state);
+    const r = selectedRule(ui);
+    if (!r)
+        return 'no rule selected';
+    const on = !r.enabled;
+    let copied = false;
+    try {
+        const i = ruleIndex(state, r.id);
+        if (i >= 0)
+            persist(state, [{ op: 'replace', path: `/rules/${i}/enabled`, value: on }], `${on ? 'enable' : 'disable'} rule ${r.id}`);
+        else if (r.source.startsWith('pack:')) {
+            // task-1358 Tier 4: a pack rule is read-only inside its pack; enabling it makes the USER's copy in config.rules
+            // (same id, same source label, the user's enabled flag). The pack's version stays shadowed from then on.
+            const packRule = state.custom?.packRules.find((p) => p.id === r.id);
+            persist(state, [{ op: 'add', path: '/rules/-', value: { ...(packRule ?? compiledToJson(r)), enabled: on } }], `${on ? 'enable' : 'disable'} pack rule ${r.id} (copied to config.rules)`);
+            copied = true;
+        }
+    }
+    catch (e) {
+        if (!/no config loaded/.test(e.message))
+            return `not changed: ${e.message}`;
+    }
+    ui.engine.setEnabled(r.id, on);
+    return `rule ${r.id} ${on ? 'enabled' : 'disabled'}${copied ? ' (your copy of the pack rule; dexterm rules remove to drop it)' : ''}`;
+}
+/** Dismiss the selected proposal (nothing else happens: it was inert). */
+export function dismissSelectedProposal(state) {
+    const ui = rulesUiOf(state);
+    const c = selectedProposal(ui);
+    if (!c)
+        return 'no proposal selected';
+    ui.proposals = ui.proposals.filter((p) => p.id !== c.id);
+    ui.selectedProposal = Math.max(0, Math.min(ui.proposals.length - 1, ui.selectedProposal));
+    ui.log.unshift({ at: state.now.getTime(), rule: c.rule, name: c.name, source: c.source, mint: c.mint, symbol: c.symbol, kind: 'dismissed', level: 'info', text: `dismissed ${describeCard(c)}` });
+    return `dismissed ${describeCard(c)}`;
+}
+/**
+ * Act on the selected proposal: queue the PAPER ticket editor (the user sizes + confirms there) or the analyst
+ * question for the loop. The card is consumed either way; nothing is armed, confirmed or sent here.
+ */
+export function actOnSelectedProposal(state) {
+    const ui = rulesUiOf(state);
+    const c = selectedProposal(ui);
+    if (!c)
+        return 'no proposal selected';
+    const row = state.screener.rows.find((r) => r.mint === c.mint);
+    if (c.type === 'ticket') {
+        ui.pending.ticket = { mint: c.mint, symbol: c.symbol, name: row?.name ?? c.symbol, side: c.side, size: c.size, unit: c.unit };
+    }
+    else {
+        ui.pending.ask = `${c.skill.replace(/-/g, ' ')} for ${c.symbol} (${c.mint}) — rule "${c.name}" fired: ${c.why}`.slice(0, 400);
+    }
+    ui.proposals = ui.proposals.filter((p) => p.id !== c.id);
+    ui.selectedProposal = Math.max(0, Math.min(ui.proposals.length - 1, ui.selectedProposal));
+    ui.log.unshift({ at: state.now.getTime(), rule: c.rule, name: c.name, source: c.source, mint: c.mint, symbol: c.symbol, kind: 'acted', level: 'info', text: c.type === 'ticket' ? `opening the PAPER ticket editor for ${c.symbol} (${c.side} ${c.size} ${c.unit} proposed; you size + confirm)` : `asking the analyst: ${c.skill} for ${c.symbol}` });
+    return c.type === 'ticket' ? `PAPER ticket editor for ${c.symbol} — proposed ${c.side} ${c.size} ${c.unit}; nothing is confirmed until you do` : `asking the analyst (${c.skill}) about ${c.symbol}`;
+}
+/** Move the cursor on whichever pane is active. */
+export function rulesMove(ui, delta) {
+    if (ui.input !== null)
+        return;
+    if (ui.pane === 'proposals')
+        ui.selectedProposal = Math.max(0, Math.min(Math.max(0, ui.proposals.length - 1), ui.selectedProposal + delta));
+    else
+        ui.selected = Math.max(0, Math.min(Math.max(0, ui.engine.rules.length - 1), ui.selected + delta));
+}

package/dist/packages/cli/src/scan/command.js

@@ -0,0 +1,57 @@
+/**
+ * Parse a typed command: `/scan` (toggle) · `/scan on|start` · `/scan off|stop` · `/scan resume|next`
+ * · `/scan status`. The leading slash is optional (the screener's `/` line already ate it). Anything
+ * else — including a real screener filter — returns null and is handled as before.
+ */
+export function parseScanCommand(text) {
+    const m = /^\s*\/?scan(?:\s+(\S+))?\s*$/i.exec(String(text ?? ''));
+    if (!m)
+        return null;
+    const arg = (m[1] ?? '').toLowerCase();
+    if (arg === '')
+        return 'toggle';
+    if (arg === 'on' || arg === 'start')
+        return 'on';
+    if (arg === 'off' || arg === 'stop')
+        return 'off';
+    if (arg === 'resume' || arg === 'next')
+        return 'resume';
+    if (arg === 'status')
+        return 'status';
+    return { error: `unknown /scan command "${arg.slice(0, 16)}" (on · off · stop · resume · status)` };
+}
+/** `--scan-*` flags → ScanConfig keys (values are numbers). */
+export const SCAN_FLAGS = {
+    '--scan-min-score': 'minScore',
+    '--scan-min-triggers': 'minTriggers',
+    '--scan-min-liq': 'minLiqUsd',
+    '--scan-vol-x': 'volX',
+    '--scan-flow-share': 'flowShare',
+    '--scan-breakout-pct': 'breakoutPct',
+    '--scan-liq-jump-pct': 'liqJumpPct',
+    '--scan-holders-jump-pct': 'holdersJumpPct',
+    '--scan-warmup-s': 'warmupS',
+    '--scan-max-ai-per-hour': 'maxAiPerHour',
+    '--scan-max-ai-per-coin': 'maxAiPerCoin',
+    '--scan-refresh-s': 'refreshS',
+    '--scan-move-pct': 'movePct',
+    '--scan-cooldown-s': 'coinCooldownS',
+    '--scan-post-lock-s': 'postLockS',
+};
+/** Range check for a flag value (non-negative; shares are 0..1; caps are integers ≥ 0). */
+export function checkScanFlag(key, n) {
+    if (!Number.isFinite(n) || n < 0)
+        return 'expects a non-negative number';
+    if (key === 'flowShare' && n > 1)
+        return 'expects a share 0..1 (e.g. 0.62)';
+    if ((key === 'maxAiPerHour' || key === 'maxAiPerCoin' || key === 'minTriggers') && !Number.isInteger(n))
+        return 'expects a whole number';
+    return null;
+}
+export const SCAN_HELP = `  --scan                    start AI SCAN MODE on launch (also: Z key, or /scan on|off|resume in the / line or chat)
+  --scan-min-score N        lock when a coin scores ≥ N (default 45) with ≥ --scan-min-triggers (default 2) triggers
+  --scan-vol-x N            volume-spike trigger: 5m volume ≥ N× the coin's own pace (default 3)
+  --scan-max-ai-per-hour N  analyst turns the scan may start per hour (default 8; per coin --scan-max-ai-per-coin 4)
+  --scan-refresh-s N        min seconds between reads of the locked coin (default 90; only when data moved)
+  more: --scan-min-liq --scan-flow-share --scan-breakout-pct --scan-liq-jump-pct --scan-holders-jump-pct
+        --scan-warmup-s --scan-move-pct --scan-cooldown-s --scan-post-lock-s`;