@backtest-kit/cli 8.1.0 → 8.2.0

package/README.md

@@ -45,6 +45,7 @@ Point the CLI at your strategy file, choose a mode, and it handles exchange conn
 | **Pine Editor**  | `--editor`                 | Open the visual Pine Script editor in the browser   |
 | **Candle Dump**  | `--dump`                   | Fetch and save raw OHLCV candles to a file   |
 | **PnL Debug**    | `--pnldebug`               | Simulate per-minute PnL for a given entry price and direction |
+| **Broker Debug** | `--brokerdebug`            | Fire a single broker commit against the live broker adapter   |
 | **Flush**        | `--flush`                  | Delete report/log/markdown/agent folders from strategy dump dir |
 | **Init Project** | `--init`                   | Scaffold a new backtest-kit project          |
 
@@ -155,6 +156,8 @@ npm start -- --symbol BTCUSDT --ui
 | `--exchange`              | string  | Exchange name (default: first registered)                          |
 | `--frame`                 | string  | Backtest frame name (default: first registered)                    |
 | `--cacheInterval`         | string  | Intervals to pre-cache before backtest (default: `"1m, 15m, 30m, 4h"`) |
+| `--brokerdebug`           | boolean | Fire a single broker commit against the live broker adapter (default: `false`) |
+| `--commit`                | string  | Commit type for `--brokerdebug` (default: `"signal-open"`) |
 
 **Positional argument (required):** path to your strategy entry point file (set once in `package.json` scripts).
 
@@ -567,7 +570,8 @@ The CLI supports **mode-specific module files** that are loaded as side-effect i
 | `--live`          | `./modules/live.module.mjs`     | `Live.background()`         |
 | `--paper`         | `./modules/paper.module.mjs`    | `Live.background()` (paper) |
 | `--backtest`      | `./modules/backtest.module.mjs` | `Backtest.background()`     |
-| `--walker`        | `./modules/walker.module.mjs`   | `Walker.background()`       |
+| `--walker`        | `./modules/walker.module.mjs`     | `Walker.background()`          |
+| `--brokerdebug`   | `./modules/brokerdebug.module.mjs` | broker commit test            |
 
 > File is resolved relative to `cwd` (the strategy directory). All of `.mjs`, `.cjs`, `.ts` extensions are tried automatically. Missing module is a soft warning — not an error.
 
@@ -1170,6 +1174,63 @@ Symbol: BTCUSDT | Direction: short | PriceOpen: 64069.50 | From: 2025-02-25T00:0
   120 | 2025-02-25T02:00:00.000Z  |      63200.00 |   +1.36% |   +1.36% |    -0.06%
 ```
 
+## 🐛 Broker Debug (`--brokerdebug`)
+
+`@backtest-kit/cli` can fire a single broker commit against your live broker adapter without running a full strategy — useful for verifying that your `brokerdebug.module` correctly wires up exchange calls.
+
+### CLI Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--brokerdebug` | boolean | Enable broker debug mode |
+| `--commit` | string | Commit type to fire (default: `"signal-open"`) |
+| `--symbol` | string | Trading pair (default: `"BTCUSDT"`) |
+| `--exchange` | string | Exchange name (default: first registered) |
+
+**Available `--commit` values:**
+
+| Value | Broker hook |
+|-------|-------------|
+| `signal-open` | `onSignalOpenCommit` |
+| `signal-close` | `onSignalCloseCommit` |
+| `partial-profit` | `onPartialProfitCommit` |
+| `partial-loss` | `onPartialLossCommit` |
+| `average-buy` | `onAverageBuyCommit` |
+| `trailing-stop` | `onTrailingStopCommit` |
+| `trailing-take` | `onTrailingTakeCommit` |
+| `breakeven` | `onBreakevenCommit` |
+
+### How It Works
+
+The CLI loads `./modules/brokerdebug.module`, fetches the last candle for `--symbol` / `--timeframe`, derives synthetic payload values from `currentPrice` (TP = +2%, SL = -2%), and calls the selected broker hook once. Exits with code `0` on success.
+
+### Broker via `brokerdebug.module`
+
+Create a `modules/brokerdebug.module.ts` file and register your broker adapter:
+
+```typescript
+// modules/brokerdebug.module.ts
+import { Broker } from 'backtest-kit';
+import { myExchange } from './exchange.mjs';
+
+class MyBroker {
+  async onSignalOpenCommit({ symbol, priceOpen, position }) {
+    await myExchange.openPosition(symbol, position, priceOpen);
+  }
+  // ... other hooks
+}
+
+Broker.useBrokerAdapter(MyBroker);
+Broker.enable();
+```
+
+### Usage
+
+```bash
+npx @backtest-kit/cli --brokerdebug --commit signal-open --symbol BTCUSDT
+npx @backtest-kit/cli --brokerdebug --commit partial-profit --symbol ETHUSDT --timeframe 1h
+```
+
 ## 🗑️ Flushing Strategy Output (`--flush`)
 
 `@backtest-kit/cli` can delete generated output folders from one or more strategy dump directories without touching cached candle data.

package/build/index.cjs

@@ -586,6 +586,14 @@ const getArgs = functoolsKit.singleshot(() => {
                 type: "string",
                 default: "",
             },
+            brokerdebug: {
+                type: "boolean",
+                default: false,
+            },
+            commit: {
+                type: "string",
+                default: "",
+            },
             init: {
                 type: "boolean",
                 default: false,
@@ -2999,7 +3007,7 @@ const cli = {
 };
 init();
 
-const MODES = ["backtest", "walker", "paper", "live", "pine", "editor", "dump", "pnldebug", "flush", "init", "help", "version"];
+const MODES = ["backtest", "walker", "paper", "live", "pine", "editor", "dump", "pnldebug", "brokerdebug", "flush", "init", "help", "version"];
 const ENTRY_PATH$1 = "./node_modules/@backtest-kit/cli/build/index.mjs";
 const HELP_TEXT$1 = `
 Example:
@@ -3014,7 +3022,7 @@ const main$e = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.1.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.2.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
@@ -3646,6 +3654,7 @@ Modes:
   --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
   --help                Print this help message
@@ -3733,6 +3742,17 @@ PnL debug flags (--pnldebug):
 
   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
@@ -3755,7 +3775,8 @@ Module hooks (loaded automatically by each mode):
   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/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.
 
@@ -3781,6 +3802,8 @@ Examples:
   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
@@ -3793,7 +3816,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.1.0"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.2.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -3807,7 +3830,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.1.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.2.0"}\n`);
     process.exit(0);
 };
 main();

package/build/index.mjs

@@ -561,6 +561,14 @@ const getArgs = singleshot(() => {
                 type: "string",
                 default: "",
             },
+            brokerdebug: {
+                type: "boolean",
+                default: false,
+            },
+            commit: {
+                type: "string",
+                default: "",
+            },
             init: {
                 type: "boolean",
                 default: false,
@@ -2970,7 +2978,7 @@ const cli = {
 };
 init();
 
-const MODES = ["backtest", "walker", "paper", "live", "pine", "editor", "dump", "pnldebug", "flush", "init", "help", "version"];
+const MODES = ["backtest", "walker", "paper", "live", "pine", "editor", "dump", "pnldebug", "brokerdebug", "flush", "init", "help", "version"];
 const ENTRY_PATH$1 = "./node_modules/@backtest-kit/cli/build/index.mjs";
 const HELP_TEXT$1 = `
 Example:
@@ -2985,7 +2993,7 @@ const main$e = async () => {
     if (MODES.some((mode) => values[mode])) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.1.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.2.0"}\n`);
     process.stdout.write("\n");
     process.stdout.write(`Run with --help to see available commands.\n`);
     process.stdout.write("\n");
@@ -3617,6 +3625,7 @@ Modes:
   --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
   --help                Print this help message
@@ -3704,6 +3713,17 @@ PnL debug flags (--pnldebug):
 
   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
@@ -3726,7 +3746,8 @@ Module hooks (loaded automatically by each mode):
   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/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.
 
@@ -3752,6 +3773,8 @@ Examples:
   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
@@ -3764,7 +3787,7 @@ const main$1 = async () => {
     if (!values.help) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.1.0"}\n\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.2.0"}\n\n`);
     process.stdout.write(HELP_TEXT);
     process.exit(0);
 };
@@ -3778,7 +3801,7 @@ const main = async () => {
     if (!values.version) {
         return;
     }
-    process.stdout.write(`@backtest-kit/cli ${"8.1.0"}\n`);
+    process.stdout.write(`@backtest-kit/cli ${"8.2.0"}\n`);
     process.exit(0);
 };
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backtest-kit/cli",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "description": "Zero-boilerplate CLI runner for backtest-kit strategies. Run backtests, paper trading, and live bots with candle cache warming, web dashboard, and Telegram notifications — no setup code required.",
   "author": {
     "name": "Petr Tripolsky",
@@ -62,11 +62,11 @@
   "devDependencies": {
     "@babel/plugin-transform-modules-umd": "7.27.1",
     "@babel/standalone": "7.29.1",
-    "@backtest-kit/graph": "8.1.0",
-    "@backtest-kit/ollama": "8.1.0",
-    "@backtest-kit/pinets": "8.1.0",
-    "@backtest-kit/signals": "8.1.0",
-    "@backtest-kit/ui": "8.1.0",
+    "@backtest-kit/graph": "8.2.0",
+    "@backtest-kit/ollama": "8.2.0",
+    "@backtest-kit/pinets": "8.2.0",
+    "@backtest-kit/signals": "8.2.0",
+    "@backtest-kit/ui": "8.2.0",
     "@rollup/plugin-replace": "6.0.3",
     "@rollup/plugin-typescript": "11.1.6",
     "@types/image-size": "0.7.0",
@@ -74,7 +74,7 @@
     "@types/mustache": "4.2.6",
     "@types/node": "22.9.0",
     "@types/stack-trace": "0.0.33",
-    "backtest-kit": "8.1.0",
+    "backtest-kit": "8.2.0",
     "glob": "11.0.1",
     "markdown-it": "14.1.1",
     "rimraf": "6.0.1",
@@ -89,12 +89,12 @@
   "peerDependencies": {
     "@babel/plugin-transform-modules-umd": "^7.27.1",
     "@babel/standalone": "^7.29.1",
-    "@backtest-kit/graph": "^8.1.0",
-    "@backtest-kit/ollama": "^8.1.0",
-    "@backtest-kit/pinets": "^8.1.0",
-    "@backtest-kit/signals": "^8.1.0",
-    "@backtest-kit/ui": "^8.1.0",
-    "backtest-kit": "^8.1.0",
+    "@backtest-kit/graph": "^8.2.0",
+    "@backtest-kit/ollama": "^8.2.0",
+    "@backtest-kit/pinets": "^8.2.0",
+    "@backtest-kit/signals": "^8.2.0",
+    "@backtest-kit/ui": "^8.2.0",
+    "backtest-kit": "^8.2.0",
     "markdown-it": "^14.1.1",
     "typescript": "^5.0.0"
   },

package/template/project/package.mustache

@@ -13,12 +13,12 @@
   "license": "ISC",
   "type": "commonjs",
   "dependencies": {
-    "@backtest-kit/cli": "^8.1.0",
-    "@backtest-kit/graph": "^8.1.0",
-    "@backtest-kit/pinets": "^8.1.0",
-    "@backtest-kit/ui": "^8.1.0",
+    "@backtest-kit/cli": "^8.2.0",
+    "@backtest-kit/graph": "^8.2.0",
+    "@backtest-kit/pinets": "^8.2.0",
+    "@backtest-kit/ui": "^8.2.0",
     "agent-swarm-kit": "^2.6.0",
-    "backtest-kit": "^8.1.0",
+    "backtest-kit": "^8.2.0",
     "functools-kit": "^2.3.0",
     "garch": "^1.2.3",
     "get-moment-stamp": "^1.1.2",