dexterm-cli 0.1.6 → 0.2.0

package/dist/packages/cli/src/autotrade-cmd/backtest.js

@@ -0,0 +1,216 @@
+// `dexterm autotrade backtest|sweep|extract` (task-1503 AT-1, AUTOTRADE-SPEC §3/§3a). PAPER, recorded data only:
+// the recorder DB is opened read-only, fills are modelled, no network, no model, no keys. Mechanical entries
+// (`auto`): the agent's judgement is what the runner card measures, so a backtest never spawns a session.
+import { dextermHome } from '../../../custom/src/index.js';
+import { defaultDbPath } from '../../../data/src/index.js';
+import { openHistoryReadOnly } from '../../../recorder/src/index.js';
+import { backtest, backtestEvidence, everyCandidate, recordBacktestEvidence, renderHeldOut, fmtIssue, loadTape, renderRecall, renderReport, renderSweep, renderYoloReplay, builtinTapePath, runnerRecall, saveTape, sweep, tapeFromDb, tapeFromDoc, yoloReplay, } from '../../../autotrade/src/index.js';
+import { parseArgs, resolveStrategyArg, storeFor } from "./strategies.js";
+const BOOL = ['json', 'every-candidate', 'no-held-out'];
+function strategyFrom(pos, opts, io, usage, anyMode = false) {
+    const arg = typeof opts.strategy === 'string' ? opts.strategy : pos[0];
+    const r = resolveStrategyArg(arg, io);
+    if (!r) {
+        io.stderr.write(`usage: ${usage}\n`);
+        return null;
+    }
+    for (const w of r.warnings)
+        io.stderr.write(`warning ${fmtIssue(w)}\n`);
+    if (!r.ok) {
+        for (const e of r.errors)
+            io.stderr.write(`error ${fmtIssue(e)}\n`);
+        return null;
+    }
+    if (r.strategy.mode !== 'paper' && !anyMode) {
+        io.stderr.write(`dexterm autotrade: ${r.strategy.id} is mode "${r.strategy.mode}": autotrade runs paper only\n`);
+        return null;
+    }
+    return r.strategy;
+}
+function numOpt(opts, k, dflt) {
+    const v = opts[k];
+    const n = typeof v === 'string' ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : dflt;
+}
+/**
+ * `dexterm autotrade yolo-replay <id|file>` (task-1532): a full-port paper replay of a strategy (a live-mode copy too:
+ * the replay always runs a paper copy) over recorded history, with the rugs, the loss spread and how often a run of
+ * entries zeroed the wallet. Read-only: recorded data, modelled fills, no network, no model, no keys.
+ */
+export async function yoloReplayCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, ['json']);
+    const usage = 'dexterm autotrade yolo-replay <id|file> [--tape FILE | --db PATH [--days N | --since T] [--until T]] [--seed N] [--json]';
+    const s = strategyFrom(pos, opts, io, usage, true);
+    if (!s)
+        return 2;
+    const tape = tapeFrom(opts, io);
+    if (!tape)
+        return 2;
+    const r = await yoloReplay(s, tape, { seed: numOpt(opts, 'seed', 1) });
+    io.stdout.write(opts.json ? JSON.stringify(r, null, 2) + '\n' : renderYoloReplay(r) + '\n');
+    return 0;
+}
+/** `--since/--until`: epoch ms or an ISO time (pins a backtest to the exact tape window of an earlier run). */
+function timeOpt(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const n = /^\d+$/.test(v) ? Number(v) : Date.parse(v);
+    return Number.isFinite(n) ? n : undefined;
+}
+/** The recorder DB, read-only; null when it is missing, in memory, or not a recorder DB. */
+function openDb(path) {
+    if (path === ':memory:')
+        return null;
+    try {
+        return openHistoryReadOnly(path);
+    }
+    catch {
+        return null;
+    }
+}
+/** A tape from --tape FILE, else read-only from the recorder DB (--db, DEXTERM_DB_PATH, the default path). */
+export function tapeFrom(opts, io) {
+    if (typeof opts.tape === 'string') {
+        try {
+            return loadTape(builtinTapePath(opts.tape));
+        }
+        catch (e) {
+            io.stderr.write(`dexterm autotrade: ${e.message}\n`);
+            return null;
+        }
+    }
+    const path = typeof opts.db === 'string' ? opts.db : (io.env.DEXTERM_DB_PATH || defaultDbPath(io.env));
+    const db = openDb(path);
+    if (!db) {
+        io.stderr.write(`dexterm autotrade: no recorded history in ${path} (run the app with the recorder on first, or pass --tape FILE)\n`);
+        return null;
+    }
+    try {
+        const days = numOpt(opts, 'days', 0);
+        return tapeFromDoc(tapeFromDb(db, {
+            since: timeOpt(opts.since) ?? (days > 0 ? Date.now() - days * 86_400_000 : undefined),
+            until: timeOpt(opts.until),
+            minPeakLiqUsd: numOpt(opts, 'min-peak-liq', 20_000),
+            spanHours: numOpt(opts, 'span-hours', 80),
+        }));
+    }
+    finally {
+        db.close();
+    }
+}
+export async function backtestCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const usage = 'dexterm autotrade backtest <id|file> [--tape FILE | --db PATH] [--days N | --since T] [--until T] [--every-candidate [--unit-usd 20]] [--recall 5,10] [--no-held-out] [--json]';
+    const arg = typeof opts.strategy === 'string' ? opts.strategy : pos[0];
+    const s0 = strategyFrom(pos, opts, io, usage);
+    if (!s0)
+        return 2;
+    const tape = tapeFrom(opts, io);
+    if (!tape)
+        return 2;
+    const s = opts['every-candidate'] ? everyCandidate(s0, numOpt(opts, 'unit-usd', 20)) : s0;
+    const { report, run } = await backtest(s, tape);
+    const recallAt = typeof opts.recall === 'string' ? opts.recall.split(',').map(Number).filter((x) => Number.isFinite(x) && x > 1) : [];
+    const recall = recallAt.length ? runnerRecall(s, tape, run, recallAt) : null;
+    if (!opts['every-candidate']) {
+        try {
+            storeFor(io).recordBacktest({ hash: s.hash, t: Date.now(), trades: report.trades, netUsd: report.netUsd, netPct: report.netPct, maxDrawdownPct: report.maxDrawdownPct, tape: `${report.tape.mints} coins ${report.tape.from ?? ''}..${report.tape.to ?? ''}` });
+        }
+        catch { /* the line is a convenience for `list`; never fail a backtest on it */ }
+    }
+    // task-1647: a stored strategy's backtest is journey evidence: the same rules on each half of the held-out split.
+    let evidence = null;
+    const stored = !!arg && !opts['every-candidate'] && !opts['no-held-out'] && storeFor(io).get(arg)?.ok === true && arg === s.id;
+    if (stored) {
+        const days = numOpt(opts, 'days', 0);
+        evidence = (await backtestEvidence(s, tape, { by: 'user', days: days > 0 ? days : null, full: { report, run } })).evidence;
+        try {
+            recordBacktestEvidence(dextermHome(io.env), evidence);
+        }
+        catch (e) {
+            io.stderr.write(`warning: the journey record was not written (${e.message})\n`);
+        }
+    }
+    if (opts.json) {
+        io.stdout.write(JSON.stringify({ ...report, ...(recall ? { recall } : {}), ...(evidence ? { heldOut: evidence.heldOut, evidence: { verdict: evidence.verdict, claim: evidence.claim, rulesHash: evidence.rulesHash } } : {}) }, null, 2) + '\n');
+        return 0;
+    }
+    io.stdout.write(renderReport(report) + '\n');
+    if (evidence)
+        io.stdout.write(renderHeldOut(evidence).join('\n') + `\n  journey: recorded as the backtest of ${s.id} v${s.version} (dexterm autotrade journey ${s.id})\n`);
+    if (opts['every-candidate'])
+        io.stdout.write(`  every-candidate copy of ${s0.id}: each candidate entered at $${numOpt(opts, 'unit-usd', 20)} with the book caps lifted (an evaluation, not a strategy to run)\n`);
+    if (recall)
+        io.stdout.write(renderRecall(recall, s) + '\n');
+    io.stdout.write('  Paper only, recorded data, not financial advice. A backtest is not a forecast.\n');
+    return 0;
+}
+export async function sweepCmd(argv, io) {
+    const { pos, opts } = parseArgs(argv, BOOL);
+    const usage = 'dexterm autotrade sweep <id|file> [--tape FILE | --db PATH] [--grid JSON] [--mode grid|random] [--max N] [--seed N] [--test-frac 0.3] [--json]';
+    const s0 = strategyFrom(pos, opts, io, usage);
+    if (!s0)
+        return 2;
+    let grid;
+    try {
+        grid = typeof opts.grid === 'string' ? JSON.parse(opts.grid) : defaultGrid(s0);
+        if (!grid || typeof grid !== 'object' || !Object.values(grid).every((v) => Array.isArray(v) && v.every((x) => typeof x === 'number')))
+            throw new Error('the grid maps parameter paths to arrays of numbers');
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade: --grid: ${e.message}\n`);
+        return 2;
+    }
+    const tape = tapeFrom(opts, io);
+    if (!tape)
+        return 2;
+    const s = opts['every-candidate'] ? everyCandidate(s0, numOpt(opts, 'unit-usd', 20)) : s0;
+    let r;
+    try {
+        r = await sweep(s, tape, grid, { mode: opts.mode === 'random' ? 'random' : 'grid', max: numOpt(opts, 'max', 64), seed: numOpt(opts, 'seed', 1), testFrac: numOpt(opts, 'test-frac', 0.3) });
+    }
+    catch (e) {
+        io.stderr.write(`dexterm autotrade: ${e.message}\n`);
+        return 2;
+    }
+    io.stdout.write(opts.json ? JSON.stringify(r, null, 2) + '\n' : renderSweep(r) + '\n  Paper only, recorded data, not financial advice.\n');
+    return 0;
+}
+/** A small default grid on the default exit profile's own knobs (only the ones the profile has). */
+export function defaultGrid(s) {
+    const p = s.exits.profiles[s.exits.default];
+    const g = {};
+    if (p.trailingStop)
+        g['profile.trailingStop.trailPct'] = [15, 25, 35];
+    if (p.tpLadder.length)
+        g['profile.tpLadder.0.atPct'] = [30, 50, 80];
+    if (p.costRecovery)
+        g['profile.costRecovery.atPct'] = [60, 100, 150];
+    if (p.bagTrail)
+        g['profile.bagTrail.trailPct'] = [35, 55, 75];
+    if (s.sizing.mode === 'pct' && s.sizing.pct !== undefined)
+        g['sizing.pct'] = [s.sizing.pct / 2, s.sizing.pct].map((x) => Math.round(x * 10) / 10);
+    return g;
+}
+export function extractCmd(argv, io) {
+    const { opts } = parseArgs(argv);
+    if (typeof opts.out !== 'string') {
+        io.stderr.write('usage: dexterm autotrade extract --out FILE [--db PATH] [--max-mints N] [--min-peak-liq USD] [--span-hours H]\n');
+        return 2;
+    }
+    const path = typeof opts.db === 'string' ? opts.db : (io.env.DEXTERM_DB_PATH || defaultDbPath(io.env));
+    const db = openDb(path);
+    if (!db) {
+        io.stderr.write(`dexterm autotrade: no recorded history in ${path}\n`);
+        return 2;
+    }
+    try {
+        const doc = tapeFromDb(db, { maxMints: typeof opts['max-mints'] === 'string' ? Number(opts['max-mints']) : undefined, minPeakLiqUsd: numOpt(opts, 'min-peak-liq', 20_000), spanHours: numOpt(opts, 'span-hours', 80) });
+        saveTape(opts.out, doc);
+        io.stdout.write(`wrote ${opts.out}: ${doc.mints.length} coins, ${doc.mints.reduce((a, m) => a + m.rows.length, 0)} rows (recorded market data only)\n`);
+        return 0;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/packages/cli/src/autotrade-cmd/executor.js

@@ -0,0 +1,91 @@
+// `dexterm autotrade executor …` (task-1654, 0.2.0 card E): is YOUR executor alive?
+//
+//   status     the last heartbeat, the last receipt, the receipt lag, and whether a real run would pause new buys now
+//   heartbeat  append one heartbeat (for executors that prefer to shell out; the kit appends or POSTs its own)
+//   kit        copy the executor reference kit (webhook / signal-cmd / JSONL tail, all dry run) to a folder of yours
+//
+// A heartbeat is data: it can only keep new buy signals from pausing. It cannot raise a limit, lift the kill switch,
+// reset the breaker or confirm a position (receipts do that, and only as data).
+import { copyFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dextermHome } from '../../../custom/src/index.js';
+import { Outbox, appendHeartbeat, effectiveLimits, executorHealth, healthLine, heartbeatPath, loadLimits, readReceipts, ACCOUNT_ID_RE } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+/** The kit inside the app (shipped in the npm package too: build-dist copies examples/). */
+export const KIT_DIR = fileURLToPath(new URL('../../../autotrade/examples/executor/', import.meta.url));
+const out = (io, s) => { io.stdout.write(`${s}\n`); };
+const err = (io, s) => { io.stderr.write(`dexterm autotrade executor: ${s}\n`); };
+export async function executorCmd(argv, io, deps = {}) {
+    const home = dextermHome(io.env);
+    const now = deps.now ?? Date.now;
+    const { pos, opts } = parseArgs(argv.slice(1), ['json', 'dry-run']);
+    switch (argv[0]) {
+        case undefined:
+        case 'help':
+            out(io, 'dexterm autotrade executor status [--json] | heartbeat [--name N] [--account ID] [--dry-run] [--nonce N] [--note TEXT] | kit --out DIR');
+            return 0;
+        case 'kit': {
+            if (typeof opts.out !== 'string') {
+                err(io, 'kit --out DIR (a new or empty folder)');
+                return 2;
+            }
+            const dir = resolve(opts.out);
+            if (existsSync(dir) && readdirSync(dir).length) {
+                err(io, `${dir} is not empty`);
+                return 1;
+            }
+            mkdirSync(dir, { recursive: true });
+            const files = readdirSync(KIT_DIR).filter((f) => /\.(mjs|md)$/.test(f));
+            for (const f of files)
+                copyFileSync(join(KIT_DIR, f), join(dir, f));
+            out(io, `executor reference kit (DRY RUN: it logs what it would do; no wallet code) copied to ${dir}: ${files.join(', ')}`);
+            out(io, `  start one:  node ${join(dir, 'webhook-executor.mjs')} --account main`);
+            out(io, '  wire it:    dexterm autotrade signal channels --webhook http://127.0.0.1:8787/signal');
+            out(io, '  prove it:   dexterm autotrade signal test   (then dexterm autotrade executor status)');
+            return 0;
+        }
+        case 'status': {
+            const l = loadLimits(home);
+            const e = effectiveLimits(l.ok ? l.doc : null, { strategyId: '-', accountId: '-', mode: 'real' });
+            const ob = Outbox.open(home, { channels: [], noLock: true });
+            const h = executorHealth(home, { now: now(), windowMin: e.values.executorSilenceMin ?? null, signal: (n) => ob.get(n), receipts: readReceipts(home).receipts });
+            if (opts.json) {
+                out(io, JSON.stringify(h, null, 2));
+                return 0;
+            }
+            out(io, `executor  ${healthLine(h)}`);
+            out(io, `  heartbeats: ${heartbeatPath(home)} (append, POST to the run's listener, or dexterm autotrade executor heartbeat)`);
+            if (h.alive === false)
+                out(io, '  a real run would PAUSE new buy signals now (exits still go out); start your executor, then dexterm autotrade signal test');
+            return 0;
+        }
+        case 'heartbeat': {
+            if (pos.length) {
+                err(io, `unexpected ${pos.join(' ')}`);
+                return 2;
+            }
+            const accountId = typeof opts.account === 'string' ? opts.account : null;
+            if (accountId && !ACCOUNT_ID_RE.test(accountId)) {
+                err(io, '--account: lowercase letters, digits, - and _');
+                return 2;
+            }
+            const nonce = opts.nonce === undefined ? null : Number(opts.nonce);
+            try {
+                const hb = appendHeartbeat(home, { at: now(), executor: typeof opts.name === 'string' ? opts.name : 'cli', accountId, dryRun: opts['dry-run'] === true ? true : null, lastNonce: nonce, note: typeof opts.note === 'string' ? opts.note : null });
+                if (opts.json)
+                    out(io, JSON.stringify(hb));
+                else
+                    out(io, `heartbeat from ${hb.executor} recorded`);
+                return 0;
+            }
+            catch (e) {
+                err(io, e.message);
+                return 2;
+            }
+        }
+        default:
+            err(io, `unknown subcommand ${JSON.stringify(argv[0])}`);
+            return 2;
+    }
+}

package/dist/packages/cli/src/autotrade-cmd/flatten.js

@@ -0,0 +1,64 @@
+// `dexterm autotrade flatten` (task-1509 AT-7, AUTOTRADE-SPEC §6.3). PAPER ONLY.
+//
+// A stop (no new entries, sessions closed, orders dropped), then every paper position sells at its next tick; one
+// that cannot sell (a pulled pool) stays stuck and is retried every tick. The runner ends once nothing is held. It
+// asks for a y keypress on a real terminal first, or takes `--yes` (selling only lowers risk; nothing here can buy,
+// arm a mandate or sign). Nothing here touches a wallet, a key or the signer.
+import { dextermHome } from '../../../custom/src/index.js';
+import { activeRunner } from '../../../autotrade/src/index.js';
+import { parseArgs } from "./strategies.js";
+import { sendControl, waitArg } from "./stop.js";
+export const FLATTEN_USAGE = 'dexterm autotrade flatten [--strategy ID] [--yes] [--wait SEC] [--json]';
+export async function flattenCmd(argv, io, over = {}) {
+    const { pos, opts } = parseArgs(argv, ['json', 'yes']);
+    if (pos.length) {
+        io.stderr.write(`usage: ${FLATTEN_USAGE}\n`);
+        return 2;
+    }
+    const home = dextermHome(io.env);
+    const member = typeof opts.strategy === 'string' ? opts.strategy : null;
+    const r = activeRunner(home);
+    if (!r) {
+        if (opts.json)
+            io.stdout.write(`${JSON.stringify({ requested: false, runId: null, why: 'no autotrade runner is running' })}\n`);
+        else
+            io.stdout.write('no autotrade runner is running; nothing to flatten.\n');
+        return 0;
+    }
+    if (!opts.yes) {
+        const stdin = io.stdin;
+        if (!stdin || stdin.isTTY !== true) {
+            io.stderr.write('dexterm autotrade flatten: confirm with y on a real terminal, or pass --yes\n');
+            return 2;
+        }
+        io.stdout.write(member ? `flatten strategy ${member} only: stop it, then sell its paper positions at their next tick (the other strategies keep running)? y to confirm, any other key cancels… `
+            : `flatten run ${r.runId}: stop, then sell every paper position at its next tick (${r.positions} open)? y to confirm, any other key cancels… `);
+        const { ttyKeypress } = await import("../wallet-cmd.js");
+        const key = await ttyKeypress(stdin, over.keypressTimeoutMs ?? 30_000);
+        io.stdout.write('\n');
+        if (key !== 'y' && key !== 'Y') {
+            io.stdout.write('flatten cancelled; nothing was sold\n');
+            return 1;
+        }
+    }
+    // task-1529: one strategy of a parallel run; the others keep running.
+    if (member)
+        return (await import("./strategy-control.js")).memberStopCmd(io, member, 'flatten', opts);
+    const res = await sendControl(io, 'flatten', waitArg(opts.wait), r);
+    if ('error' in res) {
+        io.stderr.write(`dexterm autotrade flatten: ${res.error}\n`);
+        return 1;
+    }
+    if (opts.json) {
+        io.stdout.write(`${JSON.stringify(res)}\n`);
+        return 0;
+    }
+    io.stdout.write(`flatten ${res.already ? 'was already requested' : 'requested'} for run ${r.runId} (pid ${r.pid})\n`);
+    if (!res.acknowledged)
+        io.stdout.write('the runner has not confirmed yet: it reads the request on its next tick. Watch the Q screen, or run this again.\n');
+    else if (res.ended)
+        io.stdout.write('✓ flat: the runner sold what it held and stopped\n');
+    else
+        io.stdout.write(`✓ flattening: no new entries, sessions closed; ${res.positions} paper position${res.positions === 1 ? '' : 's'} sell${res.positions === 1 ? 's' : ''} at the next tick (a stuck one is retried every tick)\n`);
+    return 0;
+}