@backtest-kit/cli 5.10.2 → 5.11.1

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) {
@@ -118,6 +119,7 @@ BacktestKit.setConfig({
 BacktestKit.setConfig({
     CC_ENABLE_DCA_EVERYWHERE: true,
     CC_ENABLE_PPPL_EVERYWHERE: true,
+    CC_ENABLE_TRAILING_EVERYWHERE: true,
 });
 BacktestKit.setConfig({
     CC_MAX_SIGNAL_GENERATION_SECONDS: 15 * 60,
@@ -283,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 = () => {
@@ -445,6 +447,18 @@ var FrameName;
 })(FrameName || (FrameName = {}));
 var FrameName$1 = FrameName;
 
+const ALLOWED_EXTENSIONS = [
+    `.cjs`,
+    `.mjs`,
+    `.ts`,
+    `.tsx`,
+    `.js`,
+    `.pine`,
+];
+const DISALLOWED_PATHS = [
+    "node_modules",
+    "@backtest-kit",
+];
 const getArgs = functoolsKit.singleshot(() => {
     const { values, positionals } = util.parseArgs({
         args: process.argv,
@@ -539,6 +553,10 @@ const getArgs = functoolsKit.singleshot(() => {
                 type: "boolean",
                 default: false,
             },
+            init: {
+                type: "boolean",
+                default: false,
+            },
         },
         strict: false,
         allowPositionals: true,
@@ -548,6 +566,13 @@ const getArgs = functoolsKit.singleshot(() => {
         positionals,
     };
 });
+const getPositional = functoolsKit.singleshot(() => {
+    const { positionals = [] } = getArgs();
+    const result = positionals
+        .filter((value) => !DISALLOWED_PATHS.some((path) => value.includes(path)))
+        .find((value) => ALLOWED_EXTENSIONS.some((ext) => value.endsWith(ext)));
+    return result || null;
+});
 
 const ADD_FRAME_FN = (self) => {
     self.loggerService.log("Adding February 2024 as a default frame schema");
@@ -733,11 +758,11 @@ class BacktestMainService {
             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, positionals } = getArgs();
+            const { values } = getArgs();
             if (!values.backtest) {
                 return;
             }
-            const [entryPoint = null] = positionals.slice(-1);
+            const entryPoint = getPositional();
             if (!entryPoint) {
                 throw new Error("Entry point is required");
             }
@@ -812,11 +837,11 @@ class LiveMainService {
             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, positionals } = getArgs();
+            const { values } = getArgs();
             if (!values.live) {
                 return;
             }
-            const [entryPoint = null] = positionals.slice(-1);
+            const entryPoint = getPositional();
             if (!entryPoint) {
                 throw new Error("Entry point is required");
             }
@@ -885,11 +910,11 @@ class PaperMainService {
             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, positionals } = getArgs();
+            const { values } = getArgs();
             if (!values.paper) {
                 return;
             }
-            const [entryPoint = null] = positionals.slice(-1);
+            const entryPoint = getPositional();
             if (!entryPoint) {
                 throw new Error("Entry point is required");
             }
@@ -2206,7 +2231,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$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;
     }
@@ -2217,7 +2242,7 @@ const main$6 = async () => {
     await cli.backtestMainService.connect();
     listenGracefulShutdown$4();
 };
-main$6();
+main$7();
 
 const BEFORE_EXIT_FN$3 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$3);
@@ -2238,7 +2263,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$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;
     }
@@ -2249,7 +2274,7 @@ const main$5 = async () => {
     cli.paperMainService.connect();
     listenGracefulShutdown$3();
 };
-main$5();
+main$6();
 
 const BEFORE_EXIT_FN$2 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$2);
@@ -2270,7 +2295,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$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;
     }
@@ -2281,7 +2306,7 @@ const main$4 = async () => {
     await cli.liveMainService.connect();
     listenGracefulShutdown$2();
 };
-main$4();
+main$5();
 
 const BEFORE_EXIT_FN$1 = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN$1);
@@ -2291,7 +2316,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$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;
     }
@@ -2301,7 +2326,7 @@ const main$3 = async () => {
     }
     listenGracefulShutdown$1();
 };
-main$3();
+main$4();
 
 const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
     process.off("SIGINT", BEFORE_EXIT_FN);
@@ -2311,7 +2336,7 @@ const BEFORE_EXIT_FN = functoolsKit.singleshot(async () => {
 const listenGracefulShutdown = functoolsKit.singleshot(() => {
     process.on("SIGINT", BEFORE_EXIT_FN);
 });
-const main$2 = 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;
     }
@@ -2321,7 +2346,7 @@ const main$2 = async () => {
     }
     listenGracefulShutdown();
 };
-main$2();
+main$3();
 
 const EXTRACT_ROWS_FN = (plots, schema) => {
     const keys = Object.keys(schema);
@@ -2343,15 +2368,15 @@ const EXTRACT_ROWS_FN = (plots, schema) => {
     }
     return rows;
 };
-const main$1 = async () => {
+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, positionals } = getArgs();
+    const { values } = getArgs();
     if (!values.pine) {
         return;
     }
-    const [entryPoint = null] = positionals.slice(-1);
+    const entryPoint = getPositional();
     if (!entryPoint) {
         return;
     }
@@ -2415,9 +2440,9 @@ const main$1 = async () => {
     }
     console.log(await BacktestKitPinets.toMarkdown(signalId, plots, signalSchema));
 };
-main$1();
+main$2();
 
-const main = async () => {
+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;
     }
@@ -2462,6 +2487,83 @@ const main = async () => {
     }
     console.log(JSON.stringify(candles, null, 2));
 };
+main$1();
+
+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";
+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.endsWith(MUSTACHE_EXT)) {
+            const destName = entry.name.slice(0, -MUSTACHE_EXT.length);
+            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 = 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}`);
+};
 main();
 
 function setLogger(logger) {