dexterm-cli 0.1.7 → 0.2.1

package/dist/packages/autotrade/src/service-install.js

@@ -0,0 +1,215 @@
+// dexterm autotrade — the always-on service's OS installers (0.2.0 card B, AUTOTRADE-SPEC §7.4).
+//
+// Every platform runs the same thing: `dexterm autotrade service ensure` once a minute and at login. `ensure` exits at
+// once while the service's heartbeat is fresh and otherwise starts it detached, so a crash costs at most one tick and
+// a clean stop stays stopped. The generators are pure (golden-file tested); the CLI shows the user every file and
+// command before anything is written, and records what it wrote (install manifest) so uninstall removes exactly that.
+//
+//   macOS    ~/Library/LaunchAgents/<label>.plist: StartInterval 60, RunAtLoad, ProcessType Background, Nice 10,
+//            LowPriorityIO, AbandonProcessGroup (the started service outlives the tick). NO KeepAlive and never
+//            `launchctl submit` (a KeepAlive job relaunches forever). Loaded with `launchctl bootout` + `bootstrap`:
+//            `kickstart -k` does NOT re-read the plist's arguments.
+//   Linux    ~/.config/systemd/user/<unit>.service (oneshot ensure, Nice 10, idle IO, KillMode=process so the started
+//            service survives the tick) + <unit>.timer (30 s after login, then every 60 s). Without
+//            `loginctl enable-linger` a user unit runs only while the user is logged in.
+//   Windows  a scheduled task (XML for `schtasks /Create /XML`): at logon + every minute, ignore-new on overlap,
+//            below-normal priority, least privilege, 5-minute limit for the tick itself.
+//
+// One label per DEXTERM_HOME: the default home gets `xyz.dexterm.autotrade`; any other home gets a suffix from a hash
+// of its path, so a test home never replaces (or removes) the real one. A non-default home is passed as `--home`.
+// Only PATH is copied into the job's environment (the service needs to find `claude`); nothing else, no secrets.
+import { createHash } from 'node:crypto';
+import { join, posix } from 'node:path';
+export const SERVICE_LABEL = 'xyz.dexterm.autotrade';
+export const INSTALL_MANIFEST_SCHEMA = 'dexterm-autotrade-service-install/1';
+/** The label for a DEXTERM_HOME: the default one, or one suffixed by a hash of the path. */
+export function serviceLabel(dexHome, defaultHome) {
+    if (dexHome === defaultHome)
+        return SERVICE_LABEL;
+    return `${SERVICE_LABEL}.h${createHash('sha256').update(dexHome).digest('hex').slice(0, 8)}`;
+}
+/** The tick's command line (`--quiet`: a tick that changes nothing prints nothing, so the tick log stays small). */
+export const ensureArgs = (s) => [s.nodePath, s.binPath, 'autotrade', 'service', 'ensure', '--quiet', ...(s.dexHome ? ['--home', s.dexHome] : [])];
+// ───────────────────────────── macOS ─────────────────────────────
+const xml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+// LaunchAgent and systemd paths are macOS / Linux paths whatever host computes the plan (task-1712: a Windows host
+// joined them with `\`); the Windows task and the manifest live under the local dexHome and use the host's join.
+export const launchAgentPath = (s) => posix.join(s.userHome, 'Library', 'LaunchAgents', `${s.label}.plist`);
+export function renderLaunchAgent(s) {
+    const args = ensureArgs(s).map((a) => `    <string>${xml(a)}</string>`).join('\n');
+    const env = s.path ? `  <key>EnvironmentVariables</key>\n  <dict>\n    <key>PATH</key>\n    <string>${xml(s.path)}</string>\n  </dict>\n` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${xml(s.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xml(s.workingDir)}</string>
+${env}  <key>StartInterval</key>
+  <integer>60</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>Nice</key>
+  <integer>10</integer>
+  <key>LowPriorityIO</key>
+  <true/>
+  <key>AbandonProcessGroup</key>
+  <true/>
+  <key>StandardOutPath</key>
+  <string>${xml(s.tickLog)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(s.tickLog)}</string>
+</dict>
+</plist>
+`;
+}
+// ───────────────────────────── Linux (systemd user) ─────────────────────────────
+export const systemdUnit = (s) => s.label.replace(/^xyz\./, '').replace(/\./g, '-');
+export const systemdDir = (s) => posix.join(s.userHome, '.config', 'systemd', 'user');
+/** systemd quoting: double quotes, backslash and quote escaped, `%` doubled (specifier expansion). */
+const sd = (a) => `"${a.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%')}"`;
+export function renderSystemdService(s) {
+    return `[Unit]
+Description=dexterm autotrade service: start it when it is not running (one tick)
+
+[Service]
+Type=oneshot
+ExecStart=${ensureArgs(s).map(sd).join(' ')}
+WorkingDirectory=${s.workingDir.replace(/%/g, '%%')}
+${s.path ? `Environment=${sd(`PATH=${s.path}`)}\n` : ''}Nice=10
+IOSchedulingClass=idle
+KillMode=process
+StandardOutput=append:${s.tickLog.replace(/%/g, '%%')}
+StandardError=append:${s.tickLog.replace(/%/g, '%%')}
+`;
+}
+export function renderSystemdTimer(s) {
+    return `[Unit]
+Description=dexterm autotrade service tick (every minute)
+
+[Timer]
+OnStartupSec=30
+OnUnitActiveSec=60
+AccuracySec=10
+Unit=${systemdUnit(s)}.service
+
+[Install]
+WantedBy=timers.target
+`;
+}
+// ───────────────────────────── Windows (scheduled task) ─────────────────────────────
+export const windowsTaskName = (s) => `\\dexterm\\${s.label.replace(/^xyz\.dexterm\./, '')}`;
+export const windowsTaskFile = (dexHome, s) => join(dexHome, 'autotrade', 'service', `${s.label}.task.xml`);
+/** Windows command-line quoting for one argument (CommandLineToArgvW rules). */
+export function winArg(a) {
+    if (a && !/[\s"]/.test(a))
+        return a;
+    let out = '"';
+    let bs = 0;
+    for (const ch of a) {
+        if (ch === '\\') {
+            bs++;
+            continue;
+        }
+        if (ch === '"') {
+            out += '\\'.repeat(bs * 2 + 1) + '"';
+            bs = 0;
+            continue;
+        }
+        out += '\\'.repeat(bs) + ch;
+        bs = 0;
+    }
+    return `${out}${'\\'.repeat(bs * 2)}"`;
+}
+export function renderWindowsTask(s) {
+    const [cmd, ...rest] = ensureArgs(s);
+    return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>dexterm autotrade service: start it when it is not running (one tick a minute)</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+    <TimeTrigger>
+      <Repetition>
+        <Interval>PT1M</Interval>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+      <StartBoundary>2026-01-01T00:00:00</StartBoundary>
+      <Enabled>true</Enabled>
+    </TimeTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT5M</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${xml(cmd)}</Command>
+      <Arguments>${xml(rest.map(winArg).join(' '))}</Arguments>
+      <WorkingDirectory>${xml(s.workingDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+// ───────────────────────────── the plan ─────────────────────────────
+export function installPlan(s, dexHome) {
+    if (s.platform === 'darwin') {
+        const path = launchAgentPath(s);
+        const domain = `gui/${s.uid}`;
+        return {
+            platform: s.platform, label: s.label, name: s.label,
+            files: [{ path, content: renderLaunchAgent(s) }],
+            activate: [['launchctl', 'bootout', `${domain}/${s.label}`], ['launchctl', 'bootstrap', domain, path]],
+            deactivate: [['launchctl', 'bootout', `${domain}/${s.label}`]],
+            notes: ['A LaunchAgent starts at login: the service runs while you are logged in on this Mac.', 'To change it later: edit nothing by hand; run `dexterm autotrade service install --load` again (bootout + bootstrap; `kickstart -k` would keep the old arguments).'],
+        };
+    }
+    if (s.platform === 'linux') {
+        const unit = systemdUnit(s);
+        const dir = systemdDir(s);
+        return {
+            platform: s.platform, label: s.label, name: `${unit}.timer`,
+            files: [{ path: posix.join(dir, `${unit}.service`), content: renderSystemdService(s) }, { path: posix.join(dir, `${unit}.timer`), content: renderSystemdTimer(s) }],
+            activate: [['systemctl', '--user', 'daemon-reload'], ['systemctl', '--user', 'enable', '--now', `${unit}.timer`]],
+            deactivate: [['systemctl', '--user', 'disable', '--now', `${unit}.timer`]],
+            notes: ['A systemd user timer runs while you are logged in; `loginctl enable-linger` (your choice) keeps it running after logout and from boot.'],
+        };
+    }
+    const file = windowsTaskFile(dexHome, s);
+    const name = windowsTaskName(s);
+    return {
+        platform: s.platform, label: s.label, name,
+        files: [{ path: file, content: renderWindowsTask(s), encoding: 'utf16le' }],
+        activate: [['schtasks', '/Create', '/TN', name, '/XML', file, '/F']],
+        deactivate: [['schtasks', '/Delete', '/TN', name, '/F']],
+        notes: ['The task runs at logon and every minute while you are logged in.'],
+    };
+}
+export const fileSha = (content, encoding = 'utf8') => createHash('sha256').update(encode(content, encoding)).digest('hex');
+/** The bytes written for a file (UTF-16 LE with a BOM for the Windows task XML). */
+export function encode(content, encoding = 'utf8') {
+    return encoding === 'utf16le' ? Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(content, 'utf16le')]) : Buffer.from(content, 'utf8');
+}
+export const installManifestPath = (dexHome) => join(dexHome, 'autotrade', 'service', 'install.json');

package/dist/packages/autotrade/src/service-recover.js

@@ -0,0 +1,232 @@
+// dexterm autotrade — safe resume after a crash or a reboot (0.2.0 card B, AUTOTRADE-SPEC §7.4 "Restart safety").
+//
+// The service records the fleet it hosts in service/state.json. When the next start finds that fleet without a
+// `fleet_end` (a crash, a kill -9, a power cut), recoverFleet() reads the fleet ledger for each strategy's runs and,
+// for every member run without a `run_end`:
+//   - checks its hash chain (a torn last line from a crash mid-write is dropped first and reported);
+//   - rebuilds the paper positions still open from the run's own events: `position_adopted` snapshots (an earlier
+//     resume) plus every `fill` of that position, minus the positions a `trade_closed` closed;
+//   - collects every coin the run took (any buy, any adopted position, an earlier resume's taken list).
+// The new run of the same strategy ADOPTS those positions (their exits keep running: stops, take-profits, trails,
+// max hold from the original open time) and REFUSES a new entry on every taken coin (vet rule
+// `service-resume-taken`), so a restart never buys a coin twice.
+//
+// Conservative choices, all in the direction of selling sooner and buying never:
+//   - an order still pending at the crash had no fill event, so it never happened: it is never re-sent;
+//   - an adopted position keeps no unfilled ladder tranche (no add after a restart) and its peak is the highest
+//     fill price (a trail measures from at most that);
+//   - a run whose chain is broken (an edited ledger) adopts nothing; its coins still count as taken.
+// Mode-agnostic: a paper position is adopted into the paper book; a real-mode position (card A) is the user's
+// executor's, and the same taken list keeps the next run from firing a second entry signal for it.
+import { existsSync, readFileSync } from 'node:fs';
+import { runFiles, verifyChain } from "./ledger.js";
+export const RESUME_TAKEN_RULE = 'service-resume-taken';
+/** Read a ledger file tolerating a torn final line (a crash mid-append); any other bad line is an error. */
+export function readLedgerTolerant(path) {
+    const lines = readFileSync(path, 'utf8').split('\n');
+    const events = [];
+    let torn = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim())
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch (e) {
+            const rest = lines.slice(i + 1).some((l) => l.trim());
+            if (rest)
+                throw new Error(`line ${i + 1} is not JSON: ${e.message}`);
+            torn = true;
+        }
+    }
+    return { events, torn };
+}
+const num = (v, d = 0) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+/** A placeholder tick at the last known price, until the live feed sends a real one (focus marks the coin held). */
+export function placeholderTick(mint, symbol, t, price) {
+    return {
+        mint, t, kind: 'live', symbol, launchpad: 'unknown', createdAt: null, price, mcap: null, mcapResolved: null, mcapFlagged: false,
+        liq: null, vol5m: null, vol1h: null, vol24: null, buys5m: null, sells5m: null, buys24: null, sells24: null,
+        chg5m: null, chg1h: null, chg6h: null, chg24h: null, holders: null, top10: null, dev: null, mintAuth: null, freezeAuth: null, org: null,
+    };
+}
+/** Open positions and taken coins from ONE run's events (pure; the run is known to have no run_end). */
+export function positionsFromEvents(events) {
+    const symbols = new Map();
+    const base = new Map();
+    const fills = new Map();
+    const closed = new Set();
+    const taken = new Set();
+    for (const e of events) {
+        const mint = typeof e.mint === 'string' ? e.mint : null;
+        if (e.kind === 'candidate' && mint && typeof e.symbol === 'string')
+            symbols.set(mint, e.symbol);
+        else if (e.kind === 'position_adopted' && e.position && typeof e.position === 'object') {
+            const p = e.position;
+            if (typeof p.id === 'string' && typeof p.mint === 'string') {
+                base.set(p.id, structuredClone(p));
+                taken.add(p.mint);
+                symbols.set(p.mint, p.symbol);
+            }
+        }
+        else if (e.kind === 'fill' && typeof e.positionId === 'string' && mint) {
+            const f = { t: num(e.t), side: e.side === 'sell' ? 'sell' : 'buy', usd: num(e.usd), tokens: num(e.tokens), price: num(e.price), avgPrice: num(e.avgPrice, num(e.price)), impactPct: num(e.impactPct), partial: !!e.partial, reason: String(e.reason ?? '') };
+            const cur = fills.get(e.positionId) ?? { mint, profile: null, fills: [] };
+            if (typeof e.profile === 'string')
+                cur.profile ??= e.profile;
+            cur.fills.push(f);
+            fills.set(e.positionId, cur);
+            if (f.side === 'buy')
+                taken.add(mint);
+        }
+        else if (e.kind === 'trade_closed' && e.trade && typeof e.trade === 'object') {
+            const t = e.trade;
+            if (typeof t.id === 'string')
+                closed.add(t.id);
+            if (typeof t.mint === 'string' && typeof t.symbol === 'string')
+                symbols.set(t.mint, t.symbol);
+        }
+    }
+    const out = [];
+    const ids = new Set([...base.keys(), ...fills.keys()]);
+    for (const id of ids) {
+        if (closed.has(id))
+            continue;
+        const b = base.get(id);
+        const f = fills.get(id);
+        const mint = b?.mint ?? f.mint;
+        const symbol = symbols.get(mint) ?? b?.symbol ?? `${mint.slice(0, 4)}…`;
+        const p = b ?? {
+            id, mint, symbol, profileId: f?.profile ?? 'default', openedAt: f.fills[0].t, sessionId: null,
+            tokens: 0, origTokens: 0, costUsd: 0, realizedUsd: 0, entryPrice: 0, peakPrice: 0, tpFilled: 0, trailArmed: false,
+            ladder: [], fills: [], status: 'open', stuck: false, closedAt: null, exitReason: null, liqWindow: [], lowTapeSince: null,
+            lastTick: placeholderTick(mint, symbol, f.fills[0].t, f.fills[0].price), wakeSent: {},
+        };
+        for (const x of f?.fills ?? []) {
+            if (x.side === 'buy') {
+                const tokens = p.tokens + x.tokens;
+                p.entryPrice = tokens > 0 ? (p.entryPrice * p.tokens + x.price * x.tokens) / tokens : x.price;
+                p.tokens = tokens;
+                p.origTokens += x.tokens;
+                p.costUsd += x.usd;
+            }
+            else {
+                p.tokens = Math.max(0, p.tokens - x.tokens);
+                p.realizedUsd += x.usd;
+                const tp = /^tp(\d+)$/.exec(x.reason);
+                if (tp)
+                    p.tpFilled = Math.max(p.tpFilled, Number(tp[1]));
+                if (x.reason === 'cost-recovery')
+                    p.costRecovered = true;
+            }
+            p.peakPrice = Math.max(p.peakPrice, x.price);
+            p.fills.push(x);
+        }
+        if (p.origTokens > 0 && p.tokens < p.origTokens * 1e-6)
+            continue; // sold out without a trade_closed line (torn)
+        if (!(p.tokens > 0))
+            continue;
+        const last = p.fills[p.fills.length - 1];
+        p.ladder = [];
+        p.sessionId = null;
+        p.status = 'open';
+        p.troughPrice = p.troughPrice ?? Math.min(...p.fills.map((x) => x.price));
+        if (last)
+            p.lastTick = placeholderTick(mint, p.symbol || symbol, last.t, last.price);
+        p.symbol = p.symbol || symbol;
+        out.push(p);
+    }
+    return { positions: out, taken: [...taken] };
+}
+/** What the crashed fleet left behind, per strategy (empty when it ended cleanly). */
+export function recoverFleet(home, fleetId) {
+    const res = { fleetId, crashed: false, members: [], problems: [] };
+    let fpath;
+    try {
+        fpath = runFiles(home, fleetId).ledger;
+    }
+    catch (e) {
+        res.problems.push(e.message);
+        return res;
+    }
+    if (!existsSync(fpath)) {
+        res.problems.push(`no fleet ledger for ${fleetId}`);
+        return res;
+    }
+    let fleet;
+    try {
+        fleet = readLedgerTolerant(fpath).events;
+    }
+    catch (e) {
+        res.problems.push(`fleet ledger: ${e.message}`);
+        return res;
+    }
+    if (fleet.some((e) => e.kind === 'fleet_end'))
+        return res;
+    res.crashed = true;
+    const runsOf = new Map();
+    for (const e of fleet)
+        if (e.kind === 'member_start' && typeof e.member === 'string' && typeof e.runId === 'string')
+            runsOf.set(e.member, [...(runsOf.get(e.member) ?? []), e.runId]);
+    // An earlier resume's taken coins (the service writes them into the fleet ledger), so a second crash keeps them.
+    const takenBefore = new Map();
+    for (const e of fleet) {
+        if (e.kind !== 'service_resume' || !e.members || typeof e.members !== 'object')
+            continue;
+        for (const [id, v] of Object.entries(e.members)) {
+            if (Array.isArray(v?.taken))
+                takenBefore.set(id, [...(takenBefore.get(id) ?? []), ...v.taken.filter((x) => typeof x === 'string')]);
+        }
+    }
+    for (const id of takenBefore.keys())
+        if (!runsOf.has(id))
+            runsOf.set(id, []);
+    for (const [member, runIds] of runsOf) {
+        const m = { member, runIds: [], positions: [], taken: [], problems: [] };
+        const taken = new Set(takenBefore.get(member) ?? []);
+        for (const runId of runIds) {
+            let path;
+            try {
+                path = runFiles(home, runId).ledger;
+            }
+            catch (e) {
+                m.problems.push(e.message);
+                continue;
+            }
+            if (!existsSync(path))
+                continue;
+            let ev;
+            try {
+                ev = readLedgerTolerant(path);
+            }
+            catch (e) {
+                m.problems.push(`${runId}: ${e.message}; nothing adopted from it`);
+                continue;
+            }
+            if (ev.events.some((e) => e.kind === 'run_end'))
+                continue;
+            m.runIds.push(runId);
+            if (ev.torn)
+                m.problems.push(`${runId}: a torn last line (the crash) was dropped`);
+            const r = positionsFromEvents(ev.events);
+            for (const t of r.taken)
+                taken.add(t);
+            const chain = verifyChain(ev.events);
+            if (!chain.ok) {
+                m.problems.push(`${runId}: the hash chain breaks at event ${chain.at} (${chain.error}); nothing adopted from it, its coins stay taken`);
+                continue;
+            }
+            // A book numbers its positions p1, p2, …: an adopted one keeps its origin in its id so it never collides with
+            // the new run's own (an id that already names a run came from an earlier resume).
+            for (const p of r.positions)
+                if (!p.id.includes('/'))
+                    p.id = `${runId}/${p.id}`;
+            m.positions.push(...r.positions);
+        }
+        m.taken = [...taken];
+        if (m.runIds.length || m.problems.length || m.taken.length)
+            res.members.push(m);
+    }
+    return res;
+}