@backtest-kit/cli 12.4.0 → 12.5.0

package/build/index.mjs

@@ -73,11 +73,11 @@ const getEntrySubject = singleshot(() => {
     return new BehaviorSubject();
 });
 
-const main$h = () => {
+const main$i = () => {
     const entrySubject = getEntrySubject();
     entrySubject.subscribe((path) => console.log("Running", path));
 };
-main$h();
+main$i();
 
 const ERROR_HANDLER_INSTALLED = Symbol.for("error-handler-installed");
 function dumpStackTrace() {
@@ -638,6 +638,10 @@ const getArgs = singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            main: {
+                type: "boolean",
+                default: false,
+            },
             cacheInterval: {
                 type: "string",
                 default: "1m, 15m, 30m, 4h",
@@ -3329,14 +3333,14 @@ const cli = {
 };
 init();
 
-const MODES = ["backtest", "walker", "paper", "live", "pine", "editor", "dump", "pnldebug", "brokerdebug", "flush", "init", "docker", "help", "version"];
+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$g = async () => {
+const main$h = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3344,14 +3348,14 @@ const main$g = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"12.4.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"12.5.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
     process.stdout.write(HELP_TEXT$1);
     process.exit(0);
 };
-main$g();
+main$h();
 
 const notifyShutdown = singleshot(async () => {
     console.log("Graceful shutdown initiated.");
@@ -3367,7 +3371,7 @@ const flush = async (entryPoint) => {
         console.log(`Removed: ${target}`);
     }
 };
-const main$f = async () => {
+const main$g = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3384,10 +3388,10 @@ const main$f = async () => {
     }
     process.exit(0);
 };
-main$f();
+main$g();
 
-const BEFORE_EXIT_FN$5 = singleshot(async () => {
-    process.off("SIGINT", BEFORE_EXIT_FN$5);
+const BEFORE_EXIT_FN$6 = singleshot(async () => {
+    process.off("SIGINT", BEFORE_EXIT_FN$6);
     const [running = null] = await Backtest.list();
     if (!running) {
         return;
@@ -3404,10 +3408,10 @@ const BEFORE_EXIT_FN$5 = singleshot(async () => {
         frameName,
     });
 });
-const listenGracefulShutdown$5 = singleshot(() => {
-    process.on("SIGINT", BEFORE_EXIT_FN$5);
+const listenGracefulShutdown$6 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$6);
 });
-const main$e = async () => {
+const main$f = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3423,12 +3427,12 @@ const main$e = async () => {
         entryPoint && await flush(entryPoint);
     }
     await cli.backtestMainService.connect();
-    listenGracefulShutdown$5();
+    listenGracefulShutdown$6();
 };
-main$e();
+main$f();
 
-const BEFORE_EXIT_FN$4 = singleshot(async () => {
-    process.off("SIGINT", BEFORE_EXIT_FN$4);
+const BEFORE_EXIT_FN$5 = singleshot(async () => {
+    process.off("SIGINT", BEFORE_EXIT_FN$5);
     const [running = null] = await Walker.list();
     if (!running) {
         return;
@@ -3441,10 +3445,10 @@ const BEFORE_EXIT_FN$4 = singleshot(async () => {
     }
     Walker.stop(symbol, { walkerName });
 });
-const listenGracefulShutdown$4 = singleshot(() => {
-    process.on("SIGINT", BEFORE_EXIT_FN$4);
+const listenGracefulShutdown$5 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$5);
 });
-const main$d = async () => {
+const main$e = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3460,13 +3464,13 @@ const main$d = async () => {
             await flush(entryPoint);
         }
     }
-    listenGracefulShutdown$4();
+    listenGracefulShutdown$5();
     await cli.walkerMainService.connect();
 };
-main$d();
+main$e();
 
-const BEFORE_EXIT_FN$3 = singleshot(async () => {
-    process.off("SIGINT", BEFORE_EXIT_FN$3);
+const BEFORE_EXIT_FN$4 = singleshot(async () => {
+    process.off("SIGINT", BEFORE_EXIT_FN$4);
     const [running = null] = await Live.list();
     if (!running) {
         return;
@@ -3482,10 +3486,10 @@ const BEFORE_EXIT_FN$3 = singleshot(async () => {
         strategyName,
     });
 });
-const listenGracefulShutdown$3 = singleshot(() => {
-    process.on("SIGINT", BEFORE_EXIT_FN$3);
+const listenGracefulShutdown$4 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$c = async () => {
+const main$d = async () => {
     if (!getEntry(import.meta.url)) {
         return;
     }
@@ -3497,12 +3501,12 @@ const main$c = async () => {
         return;
     }
     cli.paperMainService.connect();
-    listenGracefulShutdown$3();
+    listenGracefulShutdown$4();
 };
-main$c();
+main$d();
 
-const BEFORE_EXIT_FN$2 = singleshot(async () => {
-    process.off("SIGINT", BEFORE_EXIT_FN$2);
+const BEFORE_EXIT_FN$3 = singleshot(async () => {
+    process.off("SIGINT", BEFORE_EXIT_FN$3);
     const [running = null] = await Live.list();
     if (!running) {
         return;
@@ -3518,6 +3522,84 @@ const BEFORE_EXIT_FN$2 = singleshot(async () => {
         strategyName,
     });
 });
+const listenGracefulShutdown$3 = singleshot(() => {
+    process.on("SIGINT", BEFORE_EXIT_FN$3);
+});
+const main$c = async () => {
+    if (!getEntry(import.meta.url)) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.live) {
+        return;
+    }
+    if (values.entry) {
+        return;
+    }
+    await cli.liveMainService.connect();
+    listenGracefulShutdown$3();
+};
+main$c();
+
+const stopBacktestList$1 = async () => {
+    for (const item of await Backtest.list()) {
+        if (item.status === "fulfilled") {
+            continue;
+        }
+        Backtest.stop(item.symbol, {
+            exchangeName: item.exchangeName,
+            strategyName: item.strategyName,
+            frameName: item.frameName,
+        });
+    }
+};
+const stopLiveList$1 = async () => {
+    for (const item of await Live.list()) {
+        if (item.status === "fulfilled") {
+            continue;
+        }
+        Live.stop(item.symbol, {
+            exchangeName: item.exchangeName,
+            strategyName: item.strategyName,
+        });
+    }
+};
+const stopWalkerList$1 = async () => {
+    for (const item of await Walker.list()) {
+        if (item.status === "fulfilled") {
+            continue;
+        }
+        Walker.stop(item.symbol, { walkerName: item.walkerName });
+    }
+};
+const stopMain$1 = async () => {
+    await stopBacktestList$1();
+    await stopLiveList$1();
+    await stopWalkerList$1();
+};
+const listenFinish$1 = singleshot(() => {
+    let disposeRef;
+    const unBacktest = listenDoneBacktest(() => {
+        console.log("Backtest trading finished");
+        disposeRef && disposeRef();
+    });
+    const unLive = listenDoneLive(() => {
+        console.log("Live trading finished");
+        disposeRef && disposeRef();
+    });
+    const unWalker = listenDoneWalker(() => {
+        console.log("Walker comparison finished");
+        disposeRef && disposeRef();
+    });
+    disposeRef = compose(() => unBacktest(), () => unLive(), () => unWalker());
+    shutdown();
+});
+const BEFORE_EXIT_FN$2 = singleshot(async () => {
+    process.off("SIGINT", BEFORE_EXIT_FN$2);
+    notifyShutdown();
+    notifyKill();
+    await stopMain$1();
+});
 const listenGracefulShutdown$2 = singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
@@ -3526,14 +3608,56 @@ const main$b = async () => {
         return;
     }
     const { values } = getArgs();
-    if (!values.live) {
+    if (!values.main) {
         return;
     }
     if (values.entry) {
         return;
     }
-    await cli.liveMainService.connect();
+    const [entryPoint = null] = getPositionals();
+    if (!entryPoint) {
+        throw new Error("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");
+        try {
+            if (typeof loader === "function") {
+                await loader();
+            }
+            if (typeof loader?.loader === "function") {
+                await loader.loader();
+            }
+        }
+        catch (error) {
+            console.error("Module loader failed", error);
+            kill(-1);
+            return;
+        }
+    }
+    {
+        await cli.configService.waitForInit();
+        Setup.enable();
+    }
+    const cwd = process.cwd();
+    {
+        const absolutePath = path.resolve(entryPoint);
+        const moduleRoot = path.dirname(absolutePath);
+        process.chdir(moduleRoot);
+        cwd !== moduleRoot && Setup.update();
+        dotenv.config({ path: path.join(moduleRoot, '.env'), override: true, quiet: true });
+    }
+    if (!values.noFlush) {
+        await flush(path.resolve(cwd, entryPoint));
+    }
+    await cli.moduleConnectionService.loadModule("main.module");
+    listenFinish$1();
     listenGracefulShutdown$2();
+    await cli.resolveService.attachEntry(path.resolve(cwd, entryPoint));
 };
 main$b();
 
@@ -3542,13 +3666,29 @@ const MODE_MODULE = {
     live: "live.module",
     paper: "paper.module",
     walker: "walker.module",
+    main: "main.module",
 };
+const MODE_LIST = ["backtest", "live", "paper", "walker", "main"];
 const resolveMode = (values) => {
-    const enabled = ["backtest", "live", "paper", "walker"].filter((mode) => Boolean(values[mode]));
-    if (enabled.length !== 1) {
+    if (MODE_LIST.filter((mode) => values[mode]).length > 1) {
         return null;
     }
-    return enabled[0];
+    if (values.main) {
+        return "main";
+    }
+    if (values.backtest) {
+        return "backtest";
+    }
+    if (values.live) {
+        return "live";
+    }
+    if (values.paper) {
+        return "paper";
+    }
+    if (values.walker) {
+        return "walker";
+    }
+    return null;
 };
 const stopBacktestList = async () => {
     for (const item of await Backtest.list()) {
@@ -3581,11 +3721,17 @@ const stopWalkerList = async () => {
         Walker.stop(item.symbol, { walkerName: item.walkerName });
     }
 };
+const stopMain = async () => {
+    await stopBacktestList();
+    await stopLiveList();
+    await stopWalkerList();
+};
 const MODE_STOP = {
     backtest: stopBacktestList,
     live: stopLiveList,
     paper: stopLiveList,
     walker: stopWalkerList,
+    main: stopMain,
 };
 const listenFinish = singleshot(() => {
     let disposeRef;
@@ -3626,12 +3772,12 @@ const main$a = async () => {
     }
     const mode = resolveMode(values);
     if (!mode) {
-        console.error("--entry requires exactly one of --backtest, --live, --paper, --walker");
+        console.error("--entry requires exactly one of --backtest, --live, --paper, --walker, --main");
         kill(1);
         return;
     }
     const entryPoints = getPositionals();
-    if (!entryPoints.length) {
+    if (mode !== "main" && !entryPoints.length) {
         throw new Error("At least one entry point is required");
     }
     {
@@ -3678,12 +3824,18 @@ const main$a = async () => {
     }
     await cli.moduleConnectionService.loadModule(MODE_MODULE[mode]);
     listenFinish();
-    createGracefulShutdown(mode)();
+    {
+        const listenShutdown = createGracefulShutdown(mode);
+        listenShutdown();
+    }
     let absolutePath;
     for (const entryPoint of entryPoints) {
         absolutePath = path.resolve(cwd, entryPoint);
         await cli.resolveService.attachEntry(absolutePath);
     }
+    if (mode === "main") {
+        return;
+    }
     await getEntrySubject().next(absolutePath);
 };
 main$a();
@@ -4295,183 +4447,204 @@ 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
+  --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
 `.trimStart();
 const main$1 = async () => {
     if (!getEntry(import.meta.url)) {
@@ -4481,7 +4654,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"12.4.0"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"12.5.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -4495,7 +4668,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"12.4.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"12.5.0"}\n`);
     process.exit(0);
 };
 main();
@@ -4517,17 +4690,17 @@ async function run(mode, args) {
     }
     if (mode === "backtest") {
         await cli.backtestMainService.run(args);
-        listenGracefulShutdown$5();
+        listenGracefulShutdown$6();
         return;
     }
     if (mode === "paper") {
         await cli.paperMainService.run(args);
-        listenGracefulShutdown$3();
+        listenGracefulShutdown$4();
         return;
     }
     if (mode === "live") {
         await cli.liveMainService.run(args);
-        listenGracefulShutdown$2();
+        listenGracefulShutdown$3();
         return;
     }
     throw new Error(`Invalid mode: ${mode}`);