@backtest-kit/cli 9.8.4 → 10.2.0

package/build/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import * as BacktestKit from 'backtest-kit';
-import { setConfig, Notification, Recent, Storage, Markdown, Report, Dump, State, Memory, MarkdownWriter, ReportWriter, PersistSignalAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistPartialAdapter, PersistBreakevenAdapter, PersistCandleAdapter, PersistStorageAdapter, PersistNotificationAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistIntervalAdapter, PersistMemoryAdapter, PersistRecentAdapter, PersistStateAdapter, PersistSessionAdapter, Log, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, RecentLive, RecentBacktest, Broker, SessionLive, SessionBacktest, MemoryLive, MemoryBacktest, StateLive, StateBacktest, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, shutdown, listenSignal, listStrategySchema, overrideExchangeSchema, Backtest, System, Cache, Interval, alignToInterval, addWalkerSchema, overrideWalkerSchema, Walker, listenDoneWalker, Live, getCandles, checkCandles, warmCandles, listenRisk, listenStrategyCommit, listenSync, listenSignalNotify, Exchange } from 'backtest-kit';
-import { getErrorMessage, errorData, singleshot, str, compose, BehaviorSubject, createAwaiter, execpool, queued, sleep, randomString, TIMEOUT_SYMBOL, typo, retry, trycatch, memoize, isObject } from 'functools-kit';
+import { setConfig, Notification, Cron, Recent, Storage, Markdown, Report, Dump, State, Memory, MarkdownWriter, ReportWriter, PersistSignalAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistPartialAdapter, PersistBreakevenAdapter, PersistCandleAdapter, PersistStorageAdapter, PersistNotificationAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistIntervalAdapter, PersistMemoryAdapter, PersistRecentAdapter, PersistStateAdapter, PersistSessionAdapter, Log, StorageLive, StorageBacktest, NotificationLive, NotificationBacktest, RecentLive, RecentBacktest, Broker, SessionLive, SessionBacktest, MemoryLive, MemoryBacktest, StateLive, StateBacktest, listExchangeSchema, addExchangeSchema, roundTicks, listFrameSchema, addFrameSchema, listenDoneLive, listenDoneBacktest, shutdown, listenSignal, listStrategySchema, overrideExchangeSchema, Backtest, System, Cache, Interval, alignToInterval, addWalkerSchema, overrideWalkerSchema, Walker, listenDoneWalker, Live, getCandles, checkCandles, warmCandles, listenRisk, listenStrategyCommit, listenSync, listenSignalNotify, Exchange } from 'backtest-kit';
+import { getErrorMessage, errorData, singleshot, str, compose, BehaviorSubject, sleep, createAwaiter, execpool, queued, randomString, TIMEOUT_SYMBOL, typo, retry, trycatch, memoize, isObject } from 'functools-kit';
 import fs, { constants, realpathSync } from 'fs';
 import * as stackTrace from 'stack-trace';
 import path, { join, resolve, dirname, basename, extname } from 'path';
@@ -11,6 +11,7 @@ import { createActivator } from 'di-kit';
 import { fileURLToPath } from 'url';
 import ccxt from 'ccxt';
 import { parseArgs } from 'util';
+import { exec, spawn } from 'child_process';
 import * as BacktestKitUi from '@backtest-kit/ui';
 import { lib, serve } from '@backtest-kit/ui';
 import QuickChart from 'quickchart-js';
@@ -31,7 +32,6 @@ import * as BacktestKitPinets from '@backtest-kit/pinets';
 import { run as run$1, Code, toMarkdown } from '@backtest-kit/pinets';
 import * as BacktestKitSignals from '@backtest-kit/signals';
 import open from 'open';
-import { spawn } from 'child_process';
 
 setConfig({
     CC_MAX_NOTIFICATIONS: 5000,
@@ -254,6 +254,9 @@ class SetupUtils {
                 const config = cli.configService.getNotificationConfig();
                 Notification.enable(config);
             }
+            {
+                Cron.enable();
+            }
             {
                 Recent.enable();
                 Storage.enable();
@@ -275,6 +278,9 @@ class SetupUtils {
                 return;
             }
             this.enable.clear();
+            {
+                Cron.disable();
+            }
             {
                 Recent.disable();
                 Storage.disable();
@@ -831,6 +837,129 @@ const notifyVerbose = singleshot(() => {
 
 const entrySubject = new BehaviorSubject();
 
+function killPid(pid, signal) {
+    try {
+        process.kill(pid, signal);
+    }
+    catch (err) {
+        if (err.code !== "ESRCH")
+            throw err;
+    }
+}
+function killAll(tree, signal, callback) {
+    const killed = {};
+    try {
+        for (const pid of Object.keys(tree).map(Number)) {
+            for (const child of tree[pid]) {
+                if (!killed[child]) {
+                    killPid(child, signal);
+                    killed[child] = true;
+                }
+            }
+            if (!killed[pid]) {
+                killPid(pid, signal);
+                killed[pid] = true;
+            }
+        }
+    }
+    catch (err) {
+        if (callback)
+            return callback(err);
+        throw err;
+    }
+    callback?.();
+}
+function buildProcessTree(parentPid, tree, pidsToProcess, spawnList, cb) {
+    const ps = spawnList(parentPid);
+    let allData = "";
+    ps.stdout.on("data", (data) => {
+        allData += data.toString("ascii");
+    });
+    ps.on("close", (code) => {
+        delete pidsToProcess[parentPid];
+        if (code !== 0) {
+            if (Object.keys(pidsToProcess).length === 0)
+                cb();
+            return;
+        }
+        const matches = allData.match(/\d+/g);
+        if (matches) {
+            for (const pidStr of matches) {
+                const pid = parseInt(pidStr, 10);
+                tree[parentPid].push(pid);
+                tree[pid] = [];
+                pidsToProcess[pid] = 1;
+                buildProcessTree(pid, tree, pidsToProcess, spawnList, cb);
+            }
+        }
+    });
+}
+function treeKill(pid, signalOrCallback, callback) {
+    let signal;
+    if (typeof signalOrCallback === "function") {
+        callback = signalOrCallback;
+        signal = undefined;
+    }
+    else {
+        signal = signalOrCallback;
+    }
+    pid = parseInt(pid, 10);
+    if (Number.isNaN(pid)) {
+        const err = new Error("pid must be a number");
+        if (callback)
+            return callback(err);
+        throw err;
+    }
+    const tree = { [pid]: [] };
+    const pidsToProcess = { [pid]: 1 };
+    switch (process.platform) {
+        case "win32":
+            exec(`taskkill /pid ${pid} /T /F`, (err) => callback?.(err ?? undefined));
+            break;
+        case "darwin":
+            buildProcessTree(pid, tree, pidsToProcess, (parentPid) => spawn("pgrep", ["-P", String(parentPid)]), () => killAll(tree, signal, callback));
+            break;
+        default: // Linux
+            buildProcessTree(pid, tree, pidsToProcess, (parentPid) => spawn("ps", ["-o", "pid", "--no-headers", "--ppid", String(parentPid)]), () => killAll(tree, signal, callback));
+            break;
+    }
+}
+
+const DRAIN_MAX_AWAIT = 250;
+const drainStream = (stream) => new Promise((resolve) => {
+    if (stream.writableLength === 0) {
+        stream.write("", () => resolve());
+        return;
+    }
+    stream.once("drain", () => {
+        stream.write("", () => resolve());
+    });
+});
+const flushStream = (stream) => {
+    const handle = stream._handle;
+    if (handle && typeof handle.setBlocking === "function") {
+        handle.setBlocking(true);
+        return new Promise((resolve) => stream.write("", () => resolve()));
+    }
+    return drainStream(stream);
+};
+const kill = singleshot(async (code = -1) => {
+    await Promise.race([
+        Promise.all([
+            flushStream(process.stdout),
+            flushStream(process.stderr)
+        ]),
+        sleep(DRAIN_MAX_AWAIT),
+    ]);
+    treeKill(process.pid, "SIGKILL", () => {
+        process.exit(code);
+    });
+});
+const notifyKill = singleshot(() => {
+    console.log("Press Ctrl+C again to force quit.");
+    process.on("SIGINT", () => kill());
+});
+
 const DEFAULT_CACHE_LIST$1 = ["1m", "15m", "30m", "1h", "4h"];
 const GET_CACHE_INTERVAL_LIST_FN$1 = () => {
     const { values } = getArgs();
@@ -858,6 +987,10 @@ class BacktestMainService {
             this.loggerService.log("backtestMainService run", {
                 payload,
             });
+            {
+                const cwd = process.cwd();
+                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+            }
             await this.configConnectionService.loadConfig("setup.config");
             {
                 const loader = await this.configConnectionService.loadConfig("loader.config");
@@ -871,7 +1004,8 @@ class BacktestMainService {
                 }
                 catch (error) {
                     console.error("Module loader failed", error);
-                    process.exit(-1);
+                    kill(-1);
+                    return;
                 }
             }
             {
@@ -882,10 +1016,6 @@ class BacktestMainService {
                 this.frontendProviderService.connect();
                 this.telegramProviderService.connect();
             }
-            {
-                const cwd = process.cwd();
-                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
-            }
             let absolutePath;
             {
                 absolutePath = await this.resolveService.attachJavascript(payload.entryPoint);
@@ -994,6 +1124,10 @@ class WalkerMainService {
         this.configConnectionService = inject(TYPES.configConnectionService);
         this.run = singleshot(async (payload) => {
             this.loggerService.log("walkerMainService run", { payload });
+            {
+                const cwd = process.cwd();
+                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+            }
             await this.configConnectionService.loadConfig("setup.config");
             {
                 const loader = await this.configConnectionService.loadConfig("loader.config");
@@ -1007,7 +1141,8 @@ class WalkerMainService {
                 }
                 catch (error) {
                     console.error("Module loader failed", error);
-                    process.exit(-1);
+                    kill(-1);
+                    return;
                 }
             }
             {
@@ -1043,10 +1178,6 @@ class WalkerMainService {
                 Cache.resetCounter();
                 Interval.resetCounter();
             }
-            {
-                const cwd = process.cwd();
-                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
-            }
             await this.moduleConnectionService.loadModule("walker.module");
             {
                 this.exchangeSchemaService.addSchema();
@@ -1175,7 +1306,7 @@ class WalkerMainService {
                 await mkdir(dumpDir, { recursive: true });
                 await writeFile(filePath, JSON.stringify(data, null, 2), "utf-8");
                 console.log(`Saved: ${filePath}`);
-                process.exit(0);
+                kill(0);
                 return;
             }
             if (payload.markdown) {
@@ -1184,12 +1315,13 @@ class WalkerMainService {
                 await mkdir(dumpDir, { recursive: true });
                 await writeFile(filePath, report, "utf-8");
                 console.log(`Saved: ${filePath}`);
-                process.exit(0);
+                kill(0);
                 return;
             }
             const report = await Walker.getReport(symbol, { walkerName: WalkerName$1.DefaultWalker });
             console.log(report);
-            process.exit(0);
+            kill(0);
+            return;
         });
         this.connect = singleshot(async () => {
             this.loggerService.log("walkerMainService connect");
@@ -1234,6 +1366,10 @@ class LiveMainService {
             this.loggerService.log("liveMainService run", {
                 payload,
             });
+            {
+                const cwd = process.cwd();
+                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+            }
             await this.configConnectionService.loadConfig("setup.config");
             {
                 const loader = await this.configConnectionService.loadConfig("loader.config");
@@ -1247,7 +1383,8 @@ class LiveMainService {
                 }
                 catch (error) {
                     console.error("Module loader failed", error);
-                    process.exit(-1);
+                    kill(-1);
+                    return;
                 }
             }
             {
@@ -1258,10 +1395,6 @@ class LiveMainService {
                 this.frontendProviderService.connect();
                 this.telegramProviderService.connect();
             }
-            {
-                const cwd = process.cwd();
-                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
-            }
             let absolutePath;
             {
                 absolutePath = await this.resolveService.attachJavascript(payload.entryPoint);
@@ -1337,6 +1470,10 @@ class PaperMainService {
         this.configConnectionService = inject(TYPES.configConnectionService);
         this.run = singleshot(async (payload) => {
             this.loggerService.log("paperMainService init");
+            {
+                const cwd = process.cwd();
+                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+            }
             await this.configConnectionService.loadConfig("setup.config");
             {
                 const loader = await this.configConnectionService.loadConfig("loader.config");
@@ -1350,7 +1487,8 @@ class PaperMainService {
                 }
                 catch (error) {
                     console.error("Module loader failed", error);
-                    process.exit(-1);
+                    kill(-1);
+                    return;
                 }
             }
             {
@@ -1361,10 +1499,6 @@ class PaperMainService {
                 this.frontendProviderService.connect();
                 this.telegramProviderService.connect();
             }
-            {
-                const cwd = process.cwd();
-                dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
-            }
             let absolutePath;
             {
                 absolutePath = await this.resolveService.attachJavascript(payload.entryPoint);
@@ -1832,7 +1966,7 @@ class TelegramApiService {
                 console.error("Telegram publish failure", {
                     error,
                 });
-                setTimeout(() => process.exit(-1), 5000);
+                setTimeout(() => kill(-1), 5000);
             });
             const result = await Promise.race([
                 waitForResult,
@@ -1846,7 +1980,7 @@ class TelegramApiService {
                 return "Message scheduled for publication";
             }
             if (TIMEOUT_COUNTER > MAX_TIMEOUT_COUNT) {
-                setTimeout(() => process.exit(-1), 5000);
+                setTimeout(() => kill(-1), 5000);
             }
             return "Message published successfully";
         };
@@ -2559,7 +2693,8 @@ const LOAD_MODULE_MODULE_FN = async (fileName, self) => {
         }
         catch {
             console.warn(`Module module import failed filePath=${filePath} baseDir=${baseDir}`);
-            process.exit(-1);
+            kill(-1);
+            return false;
         }
     }
     return false;
@@ -2679,7 +2814,8 @@ const TRANSPILE_FN = memoize(([path]) => `${path}`, (path, code, self, require)
     }
     catch (error) {
         console.log(`Error during transpilation error=\`${getErrorMessage(error)}\` path=\`${path}\` __filename=\`${__filename}\` __dirname=\`${__dirname}\``);
-        process.exit(-1);
+        kill(-1);
+        return;
     }
     return {
         require,
@@ -2939,7 +3075,7 @@ const GET_ALIAS_EXPORTS_FN = (self) => {
     }
     return null;
 };
-const INIT_ALIAS_FN = (self) => {
+const INIT_ALIAS_FN = singleshot((self) => {
     const alias = GET_ALIAS_EXPORTS_FN(self);
     if (!alias) {
         return;
@@ -2951,18 +3087,21 @@ const INIT_ALIAS_FN = (self) => {
         Object.entries(alias).forEach(([name, module]) => overrideModule(name, module));
         Object.assign(IMPORT_ALIAS, alias);
     }
-};
+});
 class LoaderService {
     constructor() {
         this.babelService = inject(TYPES.babelService);
         this.loggerService = inject(TYPES.loggerService);
         this.resolveService = inject(TYPES.resolveService);
-        this.getInstance = memoize(([basePath]) => `${basePath}`, (basePath) => new ClientLoader({
-            babel: this.babelService,
-            logger: this.loggerService,
-            resolve: this.resolveService,
-            path: basePath,
-        }));
+        this.getInstance = memoize(([basePath]) => `${basePath}`, (basePath) => {
+            INIT_ALIAS_FN(this);
+            return new ClientLoader({
+                babel: this.babelService,
+                logger: this.loggerService,
+                resolve: this.resolveService,
+                path: basePath,
+            });
+        });
         this.import = (filePath, basePath = process.cwd()) => {
             this.loggerService.log("loaderService import", {
                 filePath,
@@ -2979,10 +3118,6 @@ class LoaderService {
             const instance = this.getInstance(basePath);
             return instance.check(filePath);
         };
-        this.init = singleshot(() => {
-            this.loggerService.log("loaderService init");
-            INIT_ALIAS_FN(this);
-        });
     }
 }
 
@@ -3011,7 +3146,8 @@ const LOAD_CONFIG_CONFIG_FN = async (fileName, self) => {
         }
         catch {
             console.warn(`Module module import failed filePath=${filePath} baseDir=${baseDir}`);
-            process.exit(-1);
+            kill(-1);
+            return;
         }
     }
     return null;
@@ -3183,10 +3319,10 @@ init();
 
 const MODES = ["backtest", "walker", "paper", "live", "pine", "editor", "dump", "pnldebug", "brokerdebug", "flush", "init", "docker", "help", "version"];
 const ENTRY_PATH$1 = "./node_modules/@backtest-kit/cli/build/index.mjs";
-const HELP_TEXT$1 = `
-Example:
-
-  node ${ENTRY_PATH$1} --help
+const HELP_TEXT$1 = `
+Example:
+
+  node ${ENTRY_PATH$1} --help
 `.trimStart();
 const main$g = async () => {
     if (!getEntry(import.meta.url)) {
@@ -3196,7 +3332,7 @@ const main$g = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"9.8.4"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"10.2.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
@@ -3206,7 +3342,7 @@ const main$g = async () => {
 main$g();
 
 const notifyShutdown = singleshot(async () => {
-    console.log("Graceful shutdown initiated. Press Ctrl+C again to force quit.");
+    console.log("Graceful shutdown initiated.");
 });
 
 const FLUSH_DIRS = ["report", "log", "markdown", "agent"];
@@ -3245,6 +3381,7 @@ const BEFORE_EXIT_FN$5 = singleshot(async () => {
         return;
     }
     notifyShutdown();
+    notifyKill();
     const { exchangeName, frameName, strategyName, symbol, status } = running;
     if (status === "fulfilled") {
         return;
@@ -3285,6 +3422,7 @@ const BEFORE_EXIT_FN$4 = singleshot(async () => {
         return;
     }
     notifyShutdown();
+    notifyKill();
     const { walkerName, symbol, status } = running;
     if (status === "fulfilled") {
         return;
@@ -3322,6 +3460,7 @@ const BEFORE_EXIT_FN$3 = singleshot(async () => {
         return;
     }
     notifyShutdown();
+    notifyKill();
     const { exchangeName, strategyName, symbol, status } = running;
     if (status === "fulfilled") {
         return;
@@ -3357,6 +3496,7 @@ const BEFORE_EXIT_FN$2 = singleshot(async () => {
         return;
     }
     notifyShutdown();
+    notifyKill();
     const { exchangeName, strategyName, symbol, status } = running;
     if (status === "fulfilled") {
         return;
@@ -3457,6 +3597,7 @@ const createGracefulShutdown = (mode) => {
     const handler = singleshot(async () => {
         process.off("SIGINT", handler);
         notifyShutdown();
+        notifyKill();
         await stop();
     });
     return singleshot(() => {
@@ -3474,13 +3615,17 @@ const main$a = async () => {
     const mode = resolveMode(values);
     if (!mode) {
         console.error("--entry requires exactly one of --backtest, --live, --paper, --walker");
-        process.exit(1);
+        kill(1);
         return;
     }
     const entryPoints = getPositionals();
     if (!entryPoints.length) {
         throw new Error("At least one entry point is required");
     }
+    {
+        const cwd = process.cwd();
+        dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
+    }
     await cli.configConnectionService.loadConfig("setup.config");
     {
         const loader = await cli.configConnectionService.loadConfig("loader.config");
@@ -3494,7 +3639,8 @@ const main$a = async () => {
         }
         catch (error) {
             console.error("Module loader failed", error);
-            process.exit(-1);
+            kill(-1);
+            return;
         }
     }
     {
@@ -3504,9 +3650,6 @@ const main$a = async () => {
     cli.frontendProviderService.connect();
     cli.telegramProviderService.connect();
     const cwd = process.cwd();
-    {
-        dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
-    }
     if (entryPoints.length === 1) {
         const absolutePath = path.resolve(entryPoints[0]);
         const moduleRoot = path.dirname(absolutePath);
@@ -3536,6 +3679,7 @@ main$a();
 const BEFORE_EXIT_FN$1 = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
     notifyShutdown();
+    notifyKill();
     cli.frontendProviderService.disable();
 });
 const listenGracefulShutdown$1 = singleshot(() => {
@@ -3556,6 +3700,7 @@ main$9();
 const BEFORE_EXIT_FN = singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
     notifyShutdown();
+    notifyKill();
     cli.telegramProviderService.disable();
 });
 const listenGracefulShutdown = singleshot(() => {
@@ -3705,7 +3850,12 @@ const main$6 = async () => {
     }
     if (values.pine) {
         console.warn("--editor and --pine are mutually exclusive. Use one at a time.");
-        process.exit(1);
+        kill(1);
+        return;
+    }
+    {
+        const cwd = process.cwd();
+        dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
     }
     await cli.configConnectionService.loadConfig("setup.config");
     {
@@ -3720,17 +3870,14 @@ const main$6 = async () => {
         }
         catch (error) {
             console.error("Module loader failed", error);
-            process.exit(-1);
+            kill(-1);
+            return;
         }
     }
     {
         await cli.configService.waitForInit();
         Setup.enable();
     }
-    {
-        const cwd = process.cwd();
-        dotenv.config({ path: path.join(cwd, '.env'), override: true, quiet: true });
-    }
     await cli.moduleConnectionService.loadModule("editor.module");
     {
         await cli.exchangeSchemaService.addSchema();
@@ -3750,7 +3897,8 @@ const main$6 = async () => {
     const beforeExit = () => {
         process.off("SIGINT", beforeExit);
         unServer();
-        process.exit(0);
+        kill(0);
+        return;
     };
     process.on("SIGINT", beforeExit);
 };
@@ -4135,183 +4283,183 @@ const main$2 = async () => {
 main$2();
 
 const ENTRY_PATH = "./node_modules/@backtest-kit/cli/build/index.mjs";
-const HELP_TEXT = `
-Usage:
-  node index.mjs --<mode> [flags] [entry-point]
-
-Modes:
-
-  --backtest <entry>          Run strategy against historical candle data
-  --walker   <entry...>       Run Walker A/B strategy comparison across multiple strategies
-  --paper    <entry>          Paper trading (live prices, no real orders)
-  --live     <entry>          Live trading with real orders
-  --pine     <entry>    Execute a local .pine indicator file
-  --editor              Open the Pine Script visual editor in the browser
-  --dump                Fetch and save raw OHLCV candles
-  --pnldebug            Simulate PnL per minute for a given entry price and direction
-  --brokerdebug         Fire a single broker commit against the live broker adapter
-  --flush  <entry...>   Delete report/log/markdown/agent folders from strategy dump dir
-  --init                Scaffold a new project in the current directory
-  --docker              Scaffold a Docker workspace for running strategies in a container
-  --help                Print this help message
-
-Backtest flags:
-
-  --symbol      <string>   Trading pair (default: BTCUSDT)
-  --strategy    <string>   Strategy name from addStrategySchema (default: first registered)
-  --exchange    <string>   Exchange name from addExchangeSchema (default: first registered)
-  --frame       <string>   Frame name from addFrameSchema (default: first registered)
-  --cacheInterval <string> Comma-separated intervals to pre-cache (default: "1m, 15m, 30m, 4h")
-  --noCache                Skip candle cache warming before the run
-  --noFlush                Skip removing report/log/markdown/agent folders before backtest run
-  --verbose                Log every candle fetch to stdout
-  --ui                     Start web dashboard at http://localhost:60050
-  --telegram               Send trade notifications to Telegram
-
-Walker flags (--walker):
-
-  --symbol        <string>   Trading pair (default: BTCUSDT)
-  --cacheInterval <string>   Comma-separated intervals to pre-cache (default: "1m, 15m, 30m, 4h")
-  --noCache                  Skip candle cache warming before the run
-  --noFlush                  Skip removing report/log/markdown/agent folders before walker run
-  --verbose                  Log every candle fetch to stdout
-  --output        <string>   Output file base name (default: walker_{SYMBOL}_{TIMESTAMP})
-  --json                     Save results as JSON to ./dump/<output>.json
-  --markdown                 Save report as Markdown to ./dump/<output>.md
-
-  Each positional argument is a strategy entry point. All strategy files are loaded without
-  changing process.cwd() — .env is read from the working directory only.
-  addWalkerSchema is called automatically using the registered exchange and frame.
-  After comparison completes the report is printed to stdout (or saved if --json/--markdown).
-
-  Module file ./modules/walker.module is loaded automatically if it exists.
-
-Paper / Live flags:
-
-  --symbol    <string>   Trading pair (default: BTCUSDT)
-  --strategy  <string>   Strategy name (default: first registered)
-  --exchange  <string>   Exchange name (default: first registered)
-  --verbose              Log every candle fetch to stdout
-  --ui                   Start web dashboard
-  --telegram             Send Telegram notifications
-
-PineScript flags (--pine):
-
-  --symbol      <string>   Trading pair (default: BTCUSDT)
-  --timeframe   <string>   Candle interval (default: 15m)
-  --limit       <string>   Number of candles to fetch (default: 250)
-  --when        <string>   End date — ISO 8601 or Unix ms (default: now)
-  --exchange    <string>   Exchange name (default: first registered)
-  --output      <string>   Output file base name without extension
-  --json                   Save output as JSON array to <pine-dir>/dump/<output>.json
-  --jsonl                  Save output as JSONL to <pine-dir>/dump/<output>.jsonl
-  --markdown               Save output as Markdown table to <pine-dir>/dump/<output>.md
-
-  Only plot() calls with display=display.data_window produce output columns.
-  Module file ./modules/pine.module is loaded automatically if it exists.
-
-Candle dump flags (--dump):
-
-  --symbol      <string>   Trading pair (default: BTCUSDT)
-  --timeframe   <string>   Candle interval (default: 15m)
-  --limit       <string>   Number of candles (default: 250)
-  --when        <string>   End date — ISO 8601 or Unix ms (default: now)
-  --exchange    <string>   Exchange name (default: first registered)
-  --output      <string>   Output file base name (default: {SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP})
-  --json                   Save as JSON array to ./dump/<output>.json
-  --jsonl                  Save as JSONL to ./dump/<output>.jsonl
-
-  Module file ./modules/dump.module is loaded automatically if it exists.
-
-PnL debug flags (--pnldebug):
-
-  --symbol      <string>   Trading pair (default: BTCUSDT)
-  --priceopen   <number>   Entry price (required)
-  --direction   <string>   Position direction: long or short (default: long)
-  --when        <string>   Start timestamp — ISO 8601 or Unix ms (default: now)
-  --minutes     <string>   Number of 1m candles to simulate (default: 60)
-  --exchange    <string>   Exchange name (default: first registered)
-  --output      <string>   Output file base name (default: {SYMBOL}_{DIRECTION}_{PRICEOPEN}_{TIMESTAMP})
-  --json                   Save as JSON array to ./dump/<output>.json
-  --jsonl                  Save as JSONL to ./dump/<output>.jsonl
-  --markdown               Save as Markdown table to ./dump/<output>.md
-
-  Module file ./modules/pnldebug.module is loaded automatically if it exists.
-
-Broker debug flags (--brokerdebug):
-
-  --symbol      <string>   Trading pair (default: BTCUSDT)
-  --exchange    <string>   Exchange name (default: first registered)
-  --commit      <string>   Commit type to fire: signal-open, signal-close, partial-profit,
-                           partial-loss, average-buy, trailing-stop, trailing-take, breakeven
-                           (default: signal-open)
-
-  Loads ./live.module, fetches the last candle for --symbol/--timeframe, and calls
-  the selected broker commit with synthetic payload values derived from current price.
-
-Flush flags (--flush):
-
-  One or more positional entry points. For each entry point the following
-  subdirectories are removed from <entry-dir>/dump/:
-
-    report   log   markdown   agent
-
-Init flags (--init):
-
-  --output <string>   Target directory name (default: backtest-kit-project)
-
-  Scaffolds a project and runs scripts/fetch_docs.mjs to download library docs.
-
-Docker flags (--docker):
-
-  --output <string>   Target directory name (default: backtest-kit-docker)
-
-  Scaffolds a Docker workspace: docker-compose.yaml, .env.example, package.json,
-  tsconfig.json, and a sample strategy under content/. Run npm install then
-  docker compose up to start the container.
-
-Module hooks (loaded automatically by each mode):
-
-  modules/backtest.module   --backtest   Broker adapter for backtest
-  modules/walker.module     --walker     Broker adapter for walker comparison
-  modules/paper.module      --paper      Broker adapter for paper trading
-  modules/live.module       --live       Broker adapter for live trading
-  modules/pine.module       --pine       Exchange schema for PineScript runs
-  modules/editor.module     --editor     Exchange schema for the visual Pine editor
-  modules/dump.module       --dump       Exchange schema for candle dumps
-  modules/pnldebug.module   --pnldebug      Exchange schema for PnL debug runs
-  modules/brokerdebug.module  --brokerdebug   Broker adapter used for broker commit testing
-
-  --flush has no associated module. It only removes dump subdirectories.
-
-  Extensions .ts, .mjs, .cjs are tried automatically. Missing module = soft warning.
-
-Environment variables:
-
-  CC_TELEGRAM_TOKEN    Telegram bot token (required for --telegram)
-  CC_TELEGRAM_CHANNEL  Telegram channel or chat ID (required for --telegram)
-  CC_WWWROOT_HOST      UI server bind address (default: 0.0.0.0)
-  CC_WWWROOT_PORT      UI server port (default: 60050)
-
-Examples:
-
-  node ${ENTRY_PATH} --backtest ./content/feb_2026.strategy.ts
-  node ${ENTRY_PATH} --backtest --symbol BTCUSDT --noCache --noFlush --ui ./content/feb_2026.strategy.ts
-  node ${ENTRY_PATH} --walker ./content/feb_2026_v1.strategy.ts ./content/feb_2026_v2.strategy.ts ./content/feb_2026_v3.strategy.ts
-  node ${ENTRY_PATH} --walker --symbol BTCUSDT --noCache --noFlush --markdown ./content/feb_2026_v1.ts ./content/feb_2026_v2.ts
-  node ${ENTRY_PATH} --paper --symbol ETHUSDT ./content/feb_2026.strategy.ts
-  node ${ENTRY_PATH} --live --ui --telegram ./content/feb_2026.strategy.ts
-  node ${ENTRY_PATH} --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --jsonl
-  node ${ENTRY_PATH} --editor
-  node ${ENTRY_PATH} --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
-  node ${ENTRY_PATH} --pnldebug --symbol BTCUSDT --priceopen 64069.50 --direction short --when "2025-02-25" --minutes 120
-  node ${ENTRY_PATH} --pnldebug --priceopen 67956.73 --direction long --when 1772064000000 --minutes 60 --markdown
-  node ${ENTRY_PATH} --brokerdebug --commit signal-open --symbol BTCUSDT
-  node ${ENTRY_PATH} --brokerdebug --commit partial-profit --symbol ETHUSDT
-  node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts
-  node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts ./content/feb_2026.strategy/feb_2026.test.ts
-  node ${ENTRY_PATH} --init --output my-trading-bot
-  node ${ENTRY_PATH} --docker --output my-docker-workspace
+const HELP_TEXT = `
+Usage:
+  node index.mjs --<mode> [flags] [entry-point]
+
+Modes:
+
+  --backtest <entry>          Run strategy against historical candle data
+  --walker   <entry...>       Run Walker A/B strategy comparison across multiple strategies
+  --paper    <entry>          Paper trading (live prices, no real orders)
+  --live     <entry>          Live trading with real orders
+  --pine     <entry>    Execute a local .pine indicator file
+  --editor              Open the Pine Script visual editor in the browser
+  --dump                Fetch and save raw OHLCV candles
+  --pnldebug            Simulate PnL per minute for a given entry price and direction
+  --brokerdebug         Fire a single broker commit against the live broker adapter
+  --flush  <entry...>   Delete report/log/markdown/agent folders from strategy dump dir
+  --init                Scaffold a new project in the current directory
+  --docker              Scaffold a Docker workspace for running strategies in a container
+  --help                Print this help message
+
+Backtest flags:
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --strategy    <string>   Strategy name from addStrategySchema (default: first registered)
+  --exchange    <string>   Exchange name from addExchangeSchema (default: first registered)
+  --frame       <string>   Frame name from addFrameSchema (default: first registered)
+  --cacheInterval <string> Comma-separated intervals to pre-cache (default: "1m, 15m, 30m, 4h")
+  --noCache                Skip candle cache warming before the run
+  --noFlush                Skip removing report/log/markdown/agent folders before backtest run
+  --verbose                Log every candle fetch to stdout
+  --ui                     Start web dashboard at http://localhost:60050
+  --telegram               Send trade notifications to Telegram
+
+Walker flags (--walker):
+
+  --symbol        <string>   Trading pair (default: BTCUSDT)
+  --cacheInterval <string>   Comma-separated intervals to pre-cache (default: "1m, 15m, 30m, 4h")
+  --noCache                  Skip candle cache warming before the run
+  --noFlush                  Skip removing report/log/markdown/agent folders before walker run
+  --verbose                  Log every candle fetch to stdout
+  --output        <string>   Output file base name (default: walker_{SYMBOL}_{TIMESTAMP})
+  --json                     Save results as JSON to ./dump/<output>.json
+  --markdown                 Save report as Markdown to ./dump/<output>.md
+
+  Each positional argument is a strategy entry point. All strategy files are loaded without
+  changing process.cwd() — .env is read from the working directory only.
+  addWalkerSchema is called automatically using the registered exchange and frame.
+  After comparison completes the report is printed to stdout (or saved if --json/--markdown).
+
+  Module file ./modules/walker.module is loaded automatically if it exists.
+
+Paper / Live flags:
+
+  --symbol    <string>   Trading pair (default: BTCUSDT)
+  --strategy  <string>   Strategy name (default: first registered)
+  --exchange  <string>   Exchange name (default: first registered)
+  --verbose              Log every candle fetch to stdout
+  --ui                   Start web dashboard
+  --telegram             Send Telegram notifications
+
+PineScript flags (--pine):
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --timeframe   <string>   Candle interval (default: 15m)
+  --limit       <string>   Number of candles to fetch (default: 250)
+  --when        <string>   End date — ISO 8601 or Unix ms (default: now)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name without extension
+  --json                   Save output as JSON array to <pine-dir>/dump/<output>.json
+  --jsonl                  Save output as JSONL to <pine-dir>/dump/<output>.jsonl
+  --markdown               Save output as Markdown table to <pine-dir>/dump/<output>.md
+
+  Only plot() calls with display=display.data_window produce output columns.
+  Module file ./modules/pine.module is loaded automatically if it exists.
+
+Candle dump flags (--dump):
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --timeframe   <string>   Candle interval (default: 15m)
+  --limit       <string>   Number of candles (default: 250)
+  --when        <string>   End date — ISO 8601 or Unix ms (default: now)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name (default: {SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP})
+  --json                   Save as JSON array to ./dump/<output>.json
+  --jsonl                  Save as JSONL to ./dump/<output>.jsonl
+
+  Module file ./modules/dump.module is loaded automatically if it exists.
+
+PnL debug flags (--pnldebug):
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --priceopen   <number>   Entry price (required)
+  --direction   <string>   Position direction: long or short (default: long)
+  --when        <string>   Start timestamp — ISO 8601 or Unix ms (default: now)
+  --minutes     <string>   Number of 1m candles to simulate (default: 60)
+  --exchange    <string>   Exchange name (default: first registered)
+  --output      <string>   Output file base name (default: {SYMBOL}_{DIRECTION}_{PRICEOPEN}_{TIMESTAMP})
+  --json                   Save as JSON array to ./dump/<output>.json
+  --jsonl                  Save as JSONL to ./dump/<output>.jsonl
+  --markdown               Save as Markdown table to ./dump/<output>.md
+
+  Module file ./modules/pnldebug.module is loaded automatically if it exists.
+
+Broker debug flags (--brokerdebug):
+
+  --symbol      <string>   Trading pair (default: BTCUSDT)
+  --exchange    <string>   Exchange name (default: first registered)
+  --commit      <string>   Commit type to fire: signal-open, signal-close, partial-profit,
+                           partial-loss, average-buy, trailing-stop, trailing-take, breakeven
+                           (default: signal-open)
+
+  Loads ./live.module, fetches the last candle for --symbol/--timeframe, and calls
+  the selected broker commit with synthetic payload values derived from current price.
+
+Flush flags (--flush):
+
+  One or more positional entry points. For each entry point the following
+  subdirectories are removed from <entry-dir>/dump/:
+
+    report   log   markdown   agent
+
+Init flags (--init):
+
+  --output <string>   Target directory name (default: backtest-kit-project)
+
+  Scaffolds a project and runs scripts/fetch_docs.mjs to download library docs.
+
+Docker flags (--docker):
+
+  --output <string>   Target directory name (default: backtest-kit-docker)
+
+  Scaffolds a Docker workspace: docker-compose.yaml, .env.example, package.json,
+  tsconfig.json, and a sample strategy under content/. Run npm install then
+  docker compose up to start the container.
+
+Module hooks (loaded automatically by each mode):
+
+  modules/backtest.module   --backtest   Broker adapter for backtest
+  modules/walker.module     --walker     Broker adapter for walker comparison
+  modules/paper.module      --paper      Broker adapter for paper trading
+  modules/live.module       --live       Broker adapter for live trading
+  modules/pine.module       --pine       Exchange schema for PineScript runs
+  modules/editor.module     --editor     Exchange schema for the visual Pine editor
+  modules/dump.module       --dump       Exchange schema for candle dumps
+  modules/pnldebug.module   --pnldebug      Exchange schema for PnL debug runs
+  modules/brokerdebug.module  --brokerdebug   Broker adapter used for broker commit testing
+
+  --flush has no associated module. It only removes dump subdirectories.
+
+  Extensions .ts, .mjs, .cjs are tried automatically. Missing module = soft warning.
+
+Environment variables:
+
+  CC_TELEGRAM_TOKEN    Telegram bot token (required for --telegram)
+  CC_TELEGRAM_CHANNEL  Telegram channel or chat ID (required for --telegram)
+  CC_WWWROOT_HOST      UI server bind address (default: 0.0.0.0)
+  CC_WWWROOT_PORT      UI server port (default: 60050)
+
+Examples:
+
+  node ${ENTRY_PATH} --backtest ./content/feb_2026.strategy.ts
+  node ${ENTRY_PATH} --backtest --symbol BTCUSDT --noCache --noFlush --ui ./content/feb_2026.strategy.ts
+  node ${ENTRY_PATH} --walker ./content/feb_2026_v1.strategy.ts ./content/feb_2026_v2.strategy.ts ./content/feb_2026_v3.strategy.ts
+  node ${ENTRY_PATH} --walker --symbol BTCUSDT --noCache --noFlush --markdown ./content/feb_2026_v1.ts ./content/feb_2026_v2.ts
+  node ${ENTRY_PATH} --paper --symbol ETHUSDT ./content/feb_2026.strategy.ts
+  node ${ENTRY_PATH} --live --ui --telegram ./content/feb_2026.strategy.ts
+  node ${ENTRY_PATH} --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --jsonl
+  node ${ENTRY_PATH} --editor
+  node ${ENTRY_PATH} --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
+  node ${ENTRY_PATH} --pnldebug --symbol BTCUSDT --priceopen 64069.50 --direction short --when "2025-02-25" --minutes 120
+  node ${ENTRY_PATH} --pnldebug --priceopen 67956.73 --direction long --when 1772064000000 --minutes 60 --markdown
+  node ${ENTRY_PATH} --brokerdebug --commit signal-open --symbol BTCUSDT
+  node ${ENTRY_PATH} --brokerdebug --commit partial-profit --symbol ETHUSDT
+  node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts
+  node ${ENTRY_PATH} --flush ./content/feb_2026.strategy/feb_2026.strategy.ts ./content/feb_2026.strategy/feb_2026.test.ts
+  node ${ENTRY_PATH} --init --output my-trading-bot
+  node ${ENTRY_PATH} --docker --output my-docker-workspace
 `.trimStart();
 const main$1 = async () => {
     if (!getEntry(import.meta.url)) {
@@ -4321,7 +4469,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"9.8.4"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"10.2.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -4335,7 +4483,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"9.8.4"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"10.2.0"}\n`);
     process.exit(0);
 };
 main();