@backtest-kit/cli 14.1.0 → 15.1.0

package/build/index.mjs

@@ -85,17 +85,28 @@ const main$i = () => {
 main$i();
 
 const ERROR_HANDLER_INSTALLED = Symbol.for("error-handler-installed");
-function dumpStackTrace() {
-    const trace = stackTrace.get();
-    const result = [];
-    trace.forEach((callSite) => {
-        result.push(`File: ${callSite.getFileName()}`);
-        result.push(`Line: ${callSite.getLineNumber()}`);
-        result.push(`Function: ${callSite.getFunctionName() || "anonymous"}`);
-        result.push(`Method: ${callSite.getMethodName() || "none"}`);
-        result.push("---");
-    });
-    return str.newline(result);
+function dumpStackTrace(error) {
+    // Parse the ERROR's own stack — stackTrace.get() captured the handler's
+    // stack instead, so error.txt carried a useless trace of ErrorService itself.
+    if (!(error instanceof Error) || !error.stack) {
+        return "";
+    }
+    try {
+        const trace = stackTrace.parse(error);
+        const result = [];
+        trace.forEach((callSite) => {
+            result.push(`File: ${callSite.getFileName()}`);
+            result.push(`Line: ${callSite.getLineNumber()}`);
+            result.push(`Function: ${callSite.getFunctionName() || "anonymous"}`);
+            result.push(`Method: ${callSite.getMethodName() || "none"}`);
+            result.push("---");
+        });
+        return str.newline(result);
+    }
+    catch {
+        // Unparseable/exotic stack format — dump the raw stack rather than nothing
+        return error.stack;
+    }
 }
 const timeNow = () => {
     const d = new Date();
@@ -115,7 +126,7 @@ class ErrorService {
                 message: getErrorMessage(error),
                 data: errorData(error),
             }, null, 2);
-            const trace = dumpStackTrace();
+            const trace = dumpStackTrace(error);
             fs.appendFileSync("./error.txt", `${date}\n${msg}\n${trace}\n\n`);
         };
         this._listenForError = () => {
@@ -240,10 +251,6 @@ const SETUP_ADAPTER_FN = () => {
         StorageLive.usePersist();
         StorageBacktest.useMemory();
     }
-    {
-        RecentLive.usePersist();
-        RecentBacktest.useMemory();
-    }
     {
         NotificationLive.usePersist();
         NotificationBacktest.useMemory();
@@ -309,6 +316,7 @@ class SetupUtils {
                 Markdown.disable();
                 Report.disable();
                 Dump.disable();
+                State.disable();
                 Memory.disable();
             }
             {
@@ -497,7 +505,11 @@ const ADD_EXCHANGE_FN = (self) => {
         formatPrice: async (symbol, price) => {
             const exchange = await getExchange();
             const market = exchange.market(symbol);
-            const tickSize = market.limits?.price?.min || market.precision?.price;
+            // ccxt binance uses TICK_SIZE precision mode, so precision.price IS the
+            // tick size. limits.price.min (PRICE_FILTER minPrice) is only a fallback:
+            // it merely coincides with the tick on most Binance markets and is NOT
+            // the tick size by contract.
+            const tickSize = [market.precision?.price, market.limits?.price?.min].find((value) => typeof value === "number" && isFinite(value) && value > 0);
             if (tickSize !== undefined) {
                 return roundTicks(price, tickSize);
             }
@@ -506,7 +518,10 @@ const ADD_EXCHANGE_FN = (self) => {
         formatQuantity: async (symbol, quantity) => {
             const exchange = await getExchange();
             const market = exchange.market(symbol);
-            const stepSize = market.limits?.amount?.min || market.precision?.amount;
+            // Same rule as formatPrice: precision.amount is the LOT_SIZE step;
+            // limits.amount.min is minQty, which can exceed the step on some markets
+            // and would over-truncate quantities if preferred.
+            const stepSize = [market.precision?.amount, market.limits?.amount?.min].find((value) => typeof value === "number" && isFinite(value) && value > 0);
             if (stepSize !== undefined) {
                 return roundTicks(quantity, stepSize);
             }
@@ -651,7 +666,7 @@ const getArgs = singleshot(() => {
             },
             cacheInterval: {
                 type: "string",
-                default: "1m, 15m, 30m, 4h",
+                default: "1m, 15m, 30m, 1h, 4h",
             },
             // pinescript entry
             editor: {
@@ -983,6 +998,8 @@ const notifyKill = singleshot(() => {
     process.on("SIGINT", () => kill());
 });
 
+// Must match the getArgs --cacheInterval default ("1m, 15m, 30m, 1h, 4h"):
+// this fallback is only reachable with an explicit --cacheInterval ""
 const DEFAULT_CACHE_LIST$1 = ["1m", "15m", "30m", "1h", "4h"];
 const GET_CACHE_INTERVAL_LIST_FN$1 = () => {
     const { values } = getArgs();
@@ -1125,6 +1142,8 @@ var WalkerName;
 })(WalkerName || (WalkerName = {}));
 var WalkerName$1 = WalkerName;
 
+// Must match the getArgs --cacheInterval default ("1m, 15m, 30m, 1h, 4h"):
+// this fallback is only reachable with an explicit --cacheInterval ""
 const DEFAULT_CACHE_LIST = ["1m", "15m", "30m", "1h", "4h"];
 const GET_CACHE_INTERVAL_LIST_FN = () => {
     const { values } = getArgs();
@@ -1635,7 +1654,7 @@ const MAP_SYMBOL_CONFIG_FN = (config) => {
         symbol,
         icon,
         logo: logo ?? icon,
-        priority: priority ?? idx,
+        priority: priority ?? -idx,
         displayName: displayName ?? symbol,
         index: idx,
         ...other,
@@ -1799,20 +1818,33 @@ class QuickchartApiService {
 const HEALTH_CHECK_DELAY = 60000;
 let _is_stopped = false;
 const handleHealthCheck = singleshot(async (bot) => {
-    const fn = async () => {
-        if (_is_stopped) {
-            return;
-        }
-        try {
-            await bot.telegram.getMe();
-            setTimeout(fn, HEALTH_CHECK_DELAY);
-        }
-        catch (error) {
-            console.log("Bot is offline");
-            throw new Error("Telegram goes offline");
-        }
+    // Первый чек выполняется синхронно с запуском: ошибка уходит вызывающему
+    // getTelegram (бот не стартует, если Telegram недоступен сразу).
+    try {
+        await bot.telegram.getMe();
+    }
+    catch {
+        console.log("Bot is offline");
+        throw new Error("Telegram goes offline");
+    }
+    // Периодические чеки: раньше throw внутри setTimeout-цикла становился
+    // unhandledRejection (никем не await-ился) и ронял процесс неконтролируемо,
+    // оставляя дочерние процессы (UI-сервер) живыми. Теперь — управляемый kill.
+    const schedule = () => {
+        setTimeout(() => {
+            if (_is_stopped) {
+                return;
+            }
+            bot.telegram
+                .getMe()
+                .then(schedule)
+                .catch(() => {
+                console.log("Bot is offline");
+                kill(-1);
+            });
+        }, HEALTH_CHECK_DELAY);
     };
-    await fn();
+    schedule();
 });
 const getTelegram = singleshot(async () => {
     if (_is_stopped) {
@@ -1911,8 +1943,11 @@ const publishInternal = queued(async ({ channel, msg, images = [], onScheduled,
     onScheduled();
     let isOk = true;
     try {
+        // Must persist across flood retries: declared inside `execute` it was reset
+        // on every recursive retry, re-sending the media group (duplicate channel
+        // posts) when the flood error hit the follow-up sendMessage.
+        let isImagesPublished = false;
         const execute = async (retry = 0) => {
-            let isImagesPublished = false;
             try {
                 if (images?.length) {
                     console.log("Bot fetching images");
@@ -2013,21 +2048,67 @@ class TelegramApiService {
                 task.finally(() => {
                     TIMEOUT_COUNTER -= 1;
                 });
+                // The watchdog must fire HERE: when every publish is stuck, this branch is
+                // the only one executing — checking after the early return made the kill
+                // reachable only once a publish suddenly succeeded (problem already gone).
+                if (TIMEOUT_COUNTER > MAX_TIMEOUT_COUNT) {
+                    setTimeout(() => kill(-1), 5000);
+                }
                 return "Message scheduled for publication";
             }
-            if (TIMEOUT_COUNTER > MAX_TIMEOUT_COUNT) {
-                setTimeout(() => kill(-1), 5000);
-            }
             return "Message published successfully";
         };
     }
 }
 
-const TELEGAM_MAX_SYMBOLS = 4090;
+const TELEGRAM_MAX_SYMBOLS = 4090;
 const TELEGRAM_SYMBOL_RESERVED = 96;
+/** Void tags never get a closing counterpart when balancing truncated HTML. */
+const VOID_TAGS = new Set(["br"]);
+/**
+ * Truncates Telegram HTML without breaking it: a blunt substring could cut a
+ * tag or entity in half and leave unbalanced tags — Telegram then rejects the
+ * WHOLE message ("can't parse entities"), so the notification would be lost
+ * instead of shortened. Closing tags appended here fit into
+ * TELEGRAM_SYMBOL_RESERVED headroom.
+ */
+const truncateTelegramHtml = (html, maxChars) => {
+    let result = html.substring(0, maxChars);
+    // Don't cut a tag in half
+    const lastOpen = result.lastIndexOf("<");
+    if (lastOpen > result.lastIndexOf(">")) {
+        result = result.substring(0, lastOpen);
+    }
+    // Don't cut an HTML entity in half
+    result = result.replace(/&[a-zA-Z0-9#]*$/, "");
+    // Close tags left open by the cut (input is sanitize-html output — well-formed)
+    const stack = [];
+    const tagRe = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)(?:\s[^>]*)?>/g;
+    let match;
+    while ((match = tagRe.exec(result))) {
+        const [, slash, rawName] = match;
+        const name = rawName.toLowerCase();
+        if (VOID_TAGS.has(name)) {
+            continue;
+        }
+        if (slash) {
+            const index = stack.lastIndexOf(name);
+            if (index !== -1) {
+                stack.splice(index, 1);
+            }
+        }
+        else {
+            stack.push(name);
+        }
+    }
+    for (let i = stack.length - 1; i >= 0; i--) {
+        result += `</${stack[i]}>`;
+    }
+    return result;
+};
 // Function to convert Markdown to Telegram-compatible HTML
 function toTelegramHtml(markdown) {
-    const maxChars = TELEGAM_MAX_SYMBOLS - TELEGRAM_SYMBOL_RESERVED;
+    const maxChars = TELEGRAM_MAX_SYMBOLS - TELEGRAM_SYMBOL_RESERVED;
     // Initialize markdown-it with options
     const md = new MarkdownIt({
         html: false,
@@ -2040,6 +2121,15 @@ function toTelegramHtml(markdown) {
     markdown = markdown.replaceAll(typo.bullet, "&bull;");
     // Render Markdown to HTML
     let telegramHtml = md.render(markdown);
+    // List markers must be injected as TEXT inside <li> before sanitizing:
+    // sanitize-html transformTags cannot insert text (a transform returning a
+    // string like "- " is silently ignored), so list items were losing their
+    // bullets/numbers entirely. Ordered lists get 1./2./..., unordered get "-".
+    telegramHtml = telegramHtml.replace(/<ol>([\s\S]*?)<\/ol>/g, (_, inner) => {
+        let counter = 0;
+        return `<ol>${inner.replace(/<li>/g, () => `<li>${++counter}. `)}</ol>`;
+    });
+    telegramHtml = telegramHtml.replace(/<li>(?!\d+\. )/g, "<li>- ");
     // Post-process with sanitize-html to ensure Telegram compatibility
     telegramHtml = sanitizeHtml(telegramHtml, {
         allowedTags: [
@@ -2071,10 +2161,9 @@ function toTelegramHtml(markdown) {
             em: "i",
             // Remove p tags, replace with newlines
             p: () => "",
-            // Emulate unordered lists with bullets
+            // ul/ol/li tags are dropped by allowedTags; their text markers are injected
+            // BEFORE sanitizing (see above) — a string-returning transform can't do it
             ul: () => "",
-            li: () => "- ",
-            // Emulate ordered lists with numbers
             ol: () => "",
             // Remove hr, replace with text-based separator
             hr: () => "\n",
@@ -2095,7 +2184,7 @@ function toTelegramHtml(markdown) {
     // Check Telegram message length limit (4096 characters)
     if (telegramHtml.length > maxChars) {
         console.warn("HTML exceeds Telegram's 4096-character limit. Truncating...");
-        telegramHtml = telegramHtml.substring(0, maxChars);
+        telegramHtml = truncateTelegramHtml(telegramHtml, maxChars);
     }
     const telegramDom = new JSDOM(telegramHtml, {
         contentType: "text/html",
@@ -2336,7 +2425,7 @@ class TelegramLogicService {
             });
         };
         this.notifyRisk = async (event) => {
-            this.loggerService.log("telegramLogicService notifyClosed", {
+            this.loggerService.log("telegramLogicService notifyRisk", {
                 event,
             });
             const markdown = await this.telegramTemplateService.getRiskMarkdown(event);
@@ -2485,6 +2574,11 @@ class TelegramLogicService {
             });
             const unSync = listenSync(async (event) => {
                 if (event.action === "signal-open") {
+                    // type "schedule" is a resting-order PLACEMENT, not a position open:
+                    // the user already got the "scheduled" notification from listenSignal
+                    if (event.type !== "active") {
+                        return;
+                    }
                     await this.notifySignalOpen(event);
                     return;
                 }
@@ -2727,8 +2821,8 @@ const LOAD_MODULE_MODULE_FN = async (fileName, self) => {
                 return true;
             }
         }
-        catch {
-            console.warn(`Module module import failed filePath=${filePath} baseDir=${baseDir}`);
+        catch (error) {
+            console.warn(`Module import failed filePath=${filePath} baseDir=${baseDir}`, error);
             kill(-1);
             return false;
         }
@@ -2763,12 +2857,12 @@ registerPlugin("plugin-transform-modules-umd", pluginUMD);
 class BabelService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
-        this.transpile = (code) => {
-            this.loggerService.log("babelService transpile", { codeLen: code.length });
+        this.transpile = (code, filename) => {
+            this.loggerService.log("babelService transpile", { codeLen: code.length, filename });
             const { values } = getArgs();
             const result = transform(code, {
-                filename: "index.ts",
-                presets: ["env", "typescript"],
+                filename,
+                presets: filename.endsWith(".tsx") ? ["env", "react", "typescript"] : ["env", "typescript"],
                 plugins: [
                     [
                         "plugin-transform-modules-umd",
@@ -2846,7 +2940,7 @@ const TRANSPILE_FN = memoize(([path]) => `${path}`, (path, code, self, require)
     const module = { exports: {} };
     const exports = module.exports;
     try {
-        eval(self.params.babel.transpile(code));
+        eval(self.params.babel.transpile(code, path));
     }
     catch (error) {
         console.log(`Error during transpilation error=\`${getErrorMessage(error)}\` path=\`${path}\` __filename=\`${__filename}\` __dirname=\`${__dirname}\``);
@@ -2861,25 +2955,35 @@ const TRANSPILE_FN = memoize(([path]) => `${path}`, (path, code, self, require)
         module,
     };
 });
-const REQUIRE_ENTRY_FACTORY = (filePath, self, seen) => {
+const REQUIRE_ENTRY_FACTORY = (filePath, self, seen, errors) => {
     {
         return null;
     }
 };
-const BABEL_ENTRY_FACTORY = (filePath, self, seen) => {
+const BABEL_ENTRY_FACTORY = (filePath, self, seen, errors) => {
     try {
         const resolvedPath = path.resolve(self.__dirname, filePath);
         const code = fs.readFileSync(resolvedPath, "utf-8");
         const child = self.fork(path.dirname(resolvedPath));
-        const { module } = TRANSPILE_FN(resolvedPath, code, child, CREATE_BASE_REQUIRE_FN(child, seen));
+        const transpiled = TRANSPILE_FN(resolvedPath, code, child, CREATE_BASE_REQUIRE_FN(child, seen));
+        if (!transpiled) {
+            // TRANSPILE_FN already reported the error and scheduled kill(-1)
+            return null;
+        }
+        const { module } = transpiled;
         if (!USE_ESMODULE_DEFAULT) {
-            return module.exports;
+            return { exports: module.exports };
         }
-        return "default" in module.exports
-            ? module.exports.default
-            : module.exports;
+        return {
+            exports: "default" in module.exports
+                ? module.exports.default
+                : module.exports,
+        };
     }
-    catch {
+    catch (error) {
+        // Never swallow the cause: a nested "Circular dependency detected" (or any
+        // real load error) must surface instead of a generic "Failed to load module".
+        errors.push(error);
         return null;
     }
 };
@@ -2924,16 +3028,18 @@ const GET_RESOLVED_EXT_FN = (filePath) => {
     return filePath;
 };
 const ENTRY_FACTORY = (filePath, self, seen) => {
+    const errors = [];
     {
         let result = null;
         if ((result = REQUIRE_ENTRY_FACTORY())) {
-            return result;
+            return result.exports;
         }
-        if ((result = BABEL_ENTRY_FACTORY(filePath, self, seen))) {
-            return result;
+        if ((result = BABEL_ENTRY_FACTORY(filePath, self, seen, errors))) {
+            return result.exports;
         }
     }
-    throw new Error(`Failed to load module at ${filePath} (basepath: ${self.params.path})`);
+    const causes = errors.map(getErrorMessage).filter(Boolean).join("; ");
+    throw new Error(`Failed to load module at ${filePath} (basepath: ${self.params.path})${causes ? ` caused by: ${causes}` : ""}`);
 };
 const READ_IMPORT_PATHS_MAP_FN = singleshot((importPathsDir) => {
     const entries = fs.readdirSync(importPathsDir, { withFileTypes: true });
@@ -3213,8 +3319,8 @@ const LOAD_CONFIG_CONFIG_FN = async (fileName, self) => {
                 return await self.loaderService.import(filePath, baseDir);
             }
         }
-        catch {
-            console.warn(`Module module import failed filePath=${filePath} baseDir=${baseDir}`);
+        catch (error) {
+            console.warn(`Config import failed filePath=${filePath} baseDir=${baseDir}`, error);
             kill(-1);
             return;
         }
@@ -3388,10 +3494,10 @@ init();
 
 const MODES = ["backtest", "walker", "paper", "live", "main", "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$h = async () => {
     if (!getEntry(import.meta.url)) {
@@ -3401,7 +3507,7 @@ const main$h = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"14.1.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"15.1.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
@@ -3553,7 +3659,7 @@ const main$d = async () => {
     if (values.entry) {
         return;
     }
-    cli.paperMainService.connect();
+    await cli.paperMainService.connect();
     listenGracefulShutdown$4();
 };
 main$d();
@@ -4107,6 +4213,7 @@ const main$6 = async () => {
         isOk = true;
     }
     catch {
+        isOk = false;
     }
     finally {
         isOk && console.log(`Editor launched: http://localhost:${CC_WWWROOT_PORT}?pine=1`);
@@ -4500,204 +4607,207 @@ 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
-  --main     <entry>          Run an entry point with prepared environment, no trading harness
-  --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
-
-Main flags (--main):
-
-  --noFlush              Skip removing report/log/markdown/agent folders before the run
-
-  Prepares the runtime environment (loads .env, setup.config, loader.config and
-  modules/main.module) and runs the single positional entry point — but does NOT
-  start any trading harness. Unlike --backtest/--live/--walker, the CLI never calls
-  Backtest/Live/Walker.background; the entry point decides what to run.
-
-  Exactly one positional entry point is required. process.cwd() is changed to the
-  entry point directory and its local .env is loaded.
-
-  Backtest, Live and Walker runs started from userspace are still tracked: the run
-  finishes automatically when one of them completes, Ctrl+C stops any active run,
-  and a second Ctrl+C force-quits.
-
-  Module file ./modules/main.module is loaded automatically if it exists.
-
-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/main.module       --main       Environment setup for a custom entry point
-  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} --main ./tools/fetch_fear_and_greed.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
+  --main     <entry>          Run an entry point with prepared environment, no trading harness
+  --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, 1h, 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, 1h, 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. While an entry point is loaded
+  (and again before its strategy runs) process.cwd() is switched to its directory and
+  restored afterwards; .env is read from the launch directory first, then from the
+  entry point directory (the latter wins).
+  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
+
+Main flags (--main):
+
+  --noFlush              Skip removing report/log/markdown/agent folders before the run
+
+  Prepares the runtime environment (loads .env, setup.config, loader.config and
+  modules/main.module) and runs the single positional entry point — but does NOT
+  start any trading harness. Unlike --backtest/--live/--walker, the CLI never calls
+  Backtest/Live/Walker.background; the entry point decides what to run.
+
+  Exactly one positional entry point is required. process.cwd() is changed to the
+  entry point directory and its local .env is loaded.
+
+  Backtest, Live and Walker runs started from userspace are still tracked: the run
+  finishes automatically when one of them completes, Ctrl+C stops any active run,
+  and a second Ctrl+C force-quits.
+
+  Module file ./modules/main.module is loaded automatically if it exists.
+
+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
+  --markdown               Save as Markdown table to ./dump/<output>.md
+
+  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/main.module       --main       Environment setup for a custom entry point
+  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} --main ./tools/fetch_fear_and_greed.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)) {
@@ -4707,7 +4817,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"14.1.0"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"15.1.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -4721,7 +4831,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"14.1.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"15.1.0"}\n`);
     process.exit(0);
 };
 main();