@backtest-kit/cli 5.11.0 → 6.0.0

package/README.md

@@ -38,6 +38,9 @@ Point the CLI at your strategy file, choose a mode, and it handles exchange conn
 | **Live**         | `--live`                   | Real trades via exchange API                 |
 | **UI Dashboard** | `--ui`                     | Web dashboard at `http://localhost:60050`    |
 | **Telegram**     | `--telegram`               | Trade notifications with price charts        |
+| **PineScript**   | `--pine`                   | Run a local `.pine` indicator against exchange data |
+| **Candle Dump**  | `--dump`                   | Fetch and save raw OHLCV candles to a file   |
+| **Init Project** | `--init`                   | Scaffold a new backtest-kit project          |
 
 ## 🚀 Installation
 
@@ -705,6 +708,93 @@ Or add it to `package.json`:
 npx @backtest-kit/cli --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
 ```
 
+## 🗂️ Scaffolding a New Project (`--init`)
+
+`@backtest-kit/cli` can bootstrap a ready-to-use project directory with a pre-configured layout, example strategy files, and all documentation fetched automatically.
+
+### CLI Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `--init` | boolean | Scaffold a new project |
+| `--output` | string | Target directory name (default: `backtest-kit-project`) |
+
+### Usage
+
+```bash
+npx @backtest-kit/cli --init
+```
+
+Creates `./backtest-kit-project/` in the current working directory.
+
+Override the directory name with `--output`:
+
+```bash
+npx @backtest-kit/cli --init --output my-trading-bot
+```
+
+Creates `./my-trading-bot/`.
+
+The target directory must not exist or must be empty — the command aborts if it contains any files.
+
+### Generated Project Structure
+
+```
+backtest-kit-project/
+├── package.json              # pre-configured with all backtest-kit dependencies
+├── .gitignore
+├── CLAUDE.md                 # AI-agent guide for writing strategies
+├── content/
+│   └── feb_2026.strategy.ts  # example strategy entry point
+├── docs/
+│   ├── lib/                  # fetched automatically (see below)
+│   ├── backtest_actions.md
+│   ├── backtest_graph_pattern.md
+│   ├── backtest_logging_jsonl.md
+│   ├── backtest_pinets_usage.md
+│   ├── backtest_risk_async.md
+│   ├── backtest_strategy_structure.md
+│   ├── pine_debug.md
+│   └── pine_indicator_warmup.md
+├── math/
+│   └── feb_2026.pine         # example PineScript indicator
+├── modules/
+│   ├── dump.module.ts        # exchange schema for --dump mode
+│   └── pine.module.ts        # exchange schema for --pine mode
+├── report/
+│   └── feb_2026.md           # example strategy research report
+└── scripts/
+    └── fetch_docs.mjs        # utility: downloads library READMEs into docs/lib/
+```
+
+### Automatic Documentation Fetch
+
+After scaffolding, the CLI immediately runs `scripts/fetch_docs.mjs` inside the new project, which downloads the latest README files for all bundled libraries into `docs/lib/`:
+
+| File | Source |
+|------|--------|
+| `backtest-kit.md` | `backtest-kit` README |
+| `backtest-kit__graph.md` | `@backtest-kit/graph` README |
+| `backtest-kit__pinets.md` | `@backtest-kit/pinets` README |
+| `backtest-kit__cli.md` | `@backtest-kit/cli` README |
+| `garch.md` | `garch` README |
+| `volume-anomaly.md` | `volume-anomaly` README |
+| `agent-swarm-kit.md` | `agent-swarm-kit` README |
+| `functools-kit.md` | `functools-kit` README |
+
+You can re-run this script at any time to refresh the docs:
+
+```bash
+cd backtest-kit-project
+node ./scripts/fetch_docs.mjs
+```
+
+Or via the pre-configured npm script:
+
+```bash
+npm run sync:lib
+```
+
 ## 🌍 Environment Variables
 
 Create a `.env` file in your project root:

package/build/index.cjs

@@ -29,6 +29,7 @@ var BacktestKitGraph = require('@backtest-kit/graph');
 var BacktestKitOllama = require('@backtest-kit/ollama');
 var BacktestKitPinets = require('@backtest-kit/pinets');
 var BacktestKitSignals = require('@backtest-kit/signals');
+var child_process = require('child_process');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 function _interopNamespaceDefault(e) {
@@ -284,15 +285,15 @@ const TYPES = {
 
 const entrySubject = new functoolsKit.BehaviorSubject();
 
-const __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
-const __dirname$1 = path.dirname(__filename$1);
+const __filename$2 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+const __dirname$2 = path.dirname(__filename$2);
 let _is_launched = false;
 class ResolveService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.loaderService = inject(TYPES.loaderService);
-        this.DEFAULT_TEMPLATE_DIR = path.resolve(__dirname$1, '..', 'template');
-        this.DEFAULT_MODULES_DIR = path.resolve(__dirname$1, '..', 'modules');
+        this.DEFAULT_TEMPLATE_DIR = path.resolve(__dirname$2, '..', 'template');
+        this.DEFAULT_MODULES_DIR = path.resolve(__dirname$2, '..', 'modules');
         this.OVERRIDE_TEMPLATE_DIR = path.resolve(process.cwd(), 'template');
         this.OVERRIDE_MODULES_DIR = path.resolve(process.cwd(), 'modules');
         this.getIsLaunched = () => {
@@ -454,6 +455,10 @@ const ALLOWED_EXTENSIONS = [
     `.js`,
     `.pine`,
 ];
+const DISALLOWED_PATHS = [
+    "node_modules",
+    "@backtest-kit",
+];
 const getArgs = functoolsKit.singleshot(() => {
     const { values, positionals } = util.parseArgs({
         args: process.argv,
@@ -548,6 +553,18 @@ const getArgs = functoolsKit.singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            init: {
+                type: "boolean",
+                default: false,
+            },
+            help: {
+                type: "boolean",
+                default: false,
+            },
+            version: {
+                type: "boolean",
+                default: false,
+            },
         },
         strict: false,
         allowPositionals: true,
@@ -559,7 +576,9 @@ const getArgs = functoolsKit.singleshot(() => {
 });
 const getPositional = functoolsKit.singleshot(() => {
     const { positionals = [] } = getArgs();
-    const result = positionals.find((value) => ALLOWED_EXTENSIONS.some((ext) => value.endsWith(ext)));
+    const result = positionals
+        .filter((value) => !DISALLOWED_PATHS.some((path) => value.includes(path)))
+        .find((value) => ALLOWED_EXTENSIONS.some((ext) => value.endsWith(ext)));
     return result || null;
 });
 
@@ -2220,7 +2239,7 @@ const BEFORE_EXIT_FN$4 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$4 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$4);
 });
-const main$6 = async () => {
+const main$9 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2231,7 +2250,7 @@ const main$6 = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$4();
 };
-main$6();
+main$9();
 
 const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -2252,7 +2271,7 @@ const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$3 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$3);
 });
-const main$5 = async () => {
+const main$8 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2263,7 +2282,7 @@ const main$5 = async () => {
     cli.paperMainService.connect();
     listenGracefulShutdown$3();
 };
-main$5();
+main$8();
 
 const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$2);
@@ -2284,7 +2303,7 @@ const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$2 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$2);
 });
-const main$4 = async () => {
+const main$7 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2295,7 +2314,7 @@ const main$4 = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$2();
 };
-main$4();
+main$7();
 
 const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -2305,7 +2324,7 @@ const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown$1 = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN$1);
 });
-const main$3 = async () => {
+const main$6 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2315,7 +2334,7 @@ const main$3 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$3();
+main$6();
 
 const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -2325,7 +2344,7 @@ const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$2 = async () => {
+const main$5 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2335,7 +2354,7 @@ const main$2 = async () => {
     }
     listenGracefulShutdown();
 };
-main$2();
+main$5();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -2357,7 +2376,7 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main$1 = async () => {
+const main$4 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2410,6 +2429,7 @@ const main$1 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, JSON.stringify(rows, null, 2), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.jsonl) {
@@ -2418,6 +2438,7 @@ const main$1 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, rows.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.markdown) {
@@ -2425,13 +2446,15 @@ const main$1 = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     console.log(await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema));
+    process.exit(0);
 };
-main$1();
+main$4();
 
-const main = async () => {
+const main$3 = async () => {
     if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
         return;
     }
@@ -2465,6 +2488,7 @@ const main = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, JSON.stringify(candles, null, 2), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     if (values.jsonl) {
@@ -2472,9 +2496,221 @@ const main = async () => {
         await fs$1.mkdir(dumpDir, { recursive: true });
         await fs$1.writeFile(filePath, candles.map((r) => JSON.stringify(r)).join("\n"), "utf-8");
         console.log(`Saved: ${filePath}`);
+        process.exit(0);
         return;
     }
     console.log(JSON.stringify(candles, null, 2));
+    process.exit(0);
+};
+main$3();
+
+const __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+const __dirname$1 = path.dirname(__filename$1);
+const MUSTACHE_EXT = ".mustache";
+const MUSTACHE_RENAME = {
+    "gitignore": ".gitignore",
+    "package": "package.json",
+};
+async function isDirEmpty(dirPath) {
+    try {
+        const files = await fs$1.readdir(dirPath);
+        return files.length === 0;
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return true;
+        }
+        throw error;
+    }
+}
+async function copyDir(srcDir, destDir, data) {
+    await fs$1.mkdir(destDir, { recursive: true });
+    const entries = await fs$1.readdir(srcDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(srcDir, entry.name);
+        if (entry.isDirectory()) {
+            await copyDir(srcPath, path.join(destDir, entry.name), data);
+            continue;
+        }
+        if (entry.name === ".gitkeep") {
+            continue;
+        }
+        if (entry.name.endsWith(MUSTACHE_EXT)) {
+            const baseName = entry.name.slice(0, -MUSTACHE_EXT.length);
+            const destName = MUSTACHE_RENAME[baseName] ?? baseName;
+            const destPath = path.join(destDir, destName);
+            const template = await fs$1.readFile(srcPath, "utf-8");
+            const rendered = Mustache.render(template, data);
+            await fs$1.writeFile(destPath, rendered, "utf-8");
+            console.log(`  -> ${destPath}`);
+        }
+        else {
+            const destPath = path.join(destDir, entry.name);
+            await fs$1.copyFile(srcPath, destPath);
+            console.log(`  -> ${destPath}`);
+        }
+    }
+}
+function runScript(scriptPath, cwd) {
+    return new Promise((resolve, reject) => {
+        const node = process.execPath;
+        const child = child_process.spawn(node, [scriptPath], { cwd, stdio: "inherit" });
+        child.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`Script exited with code ${code}`));
+                return;
+            }
+            resolve();
+        });
+        child.on("error", reject);
+    });
+}
+const main$2 = async () => {
+    if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.init) {
+        return;
+    }
+    const projectName = values.output || "backtest-kit-project";
+    const projectPath = path.join(process.cwd(), projectName);
+    const templatePath = path.join(__dirname$1, "../template/project");
+    const isEmpty = await isDirEmpty(projectPath);
+    if (!isEmpty) {
+        console.error(`Directory "${projectName}" already exists and is not empty.`);
+        process.exit(1);
+    }
+    console.log(`Creating project in ${projectPath}`);
+    await copyDir(templatePath, projectPath, { PROJECT_NAME: projectName });
+    console.log(`Fetching docs...`);
+    await runScript(path.join(projectPath, "scripts/fetch_docs.mjs"), projectPath);
+    console.log(`Done! Project created at ${projectPath}`);
+    process.exit(0);
+};
+main$2();
+
+const HELP_TEXT = `
+@backtest-kit/cli
+
+Usage:
+  node index.mjs --<mode> [flags] [entry-point]
+
+Modes:
+
+  --backtest <entry>    Run strategy against historical candle data
+  --paper    <entry>    Paper trading (live prices, no real orders)
+  --live     <entry>    Live trading with real orders
+  --pine     <entry>    Execute a local .pine indicator file
+  --dump                Fetch and save raw OHLCV candles
+  --init                Scaffold a new project in the current directory
+  --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
+  --verbose                Log every candle fetch to stdout
+  --ui                     Start web dashboard at http://localhost:60050
+  --telegram               Send trade notifications to Telegram
+
+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.
+
+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.
+
+Module hooks (loaded automatically by each mode):
+
+  modules/backtest.module   --backtest   Broker adapter for backtest
+  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/dump.module       --dump       Exchange schema for candle dumps
+
+  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 index.mjs --backtest ./content/feb_2026.strategy.ts
+  node index.mjs --backtest --symbol BTCUSDT --noCache --ui ./content/feb_2026.strategy.ts
+  node index.mjs --paper --symbol ETHUSDT ./content/feb_2026.strategy.ts
+  node index.mjs --live --ui --telegram ./content/feb_2026.strategy.ts
+  node index.mjs --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --jsonl
+  node index.mjs --dump --symbol BTCUSDT --timeframe 15m --limit 500 --jsonl
+  node index.mjs --init --output my-trading-bot
+`.trimStart();
+const main$1 = async () => {
+    if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.help) {
+        return;
+    }
+    process.stdout.write(HELP_TEXT);
+    process.exit(0);
+};
+main$1();
+
+const main = async () => {
+    if (!getEntry((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)))) {
+        return;
+    }
+    const { values } = getArgs();
+    if (!values.version) {
+        return;
+    }
+    process.stdout.write(`@backtest-kit/cli ${"6.0.0"}\n`);
+    process.exit(0);
 };
 main();