@backtest-kit/cli 5.11.0 → 6.0.0

package/template/project/README.md

@@ -0,0 +1,207 @@
+# 🧿 Backtest Kit Project
+
+> A TypeScript framework for backtesting and live trading strategies on multi-asset, crypto, forex or [DEX (peer-to-peer marketplace)](https://en.wikipedia.org/wiki/Decentralized_finance#Decentralized_exchanges), spot, futures with crash-safe persistence, signal validation, and AI optimization.
+
+![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot16.png)
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
+[![npm](https://img.shields.io/npm/v/backtest-kit.svg?style=flat-square)](https://npmjs.org/package/backtest-kit)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
+[![Build](https://github.com/tripolskypetr/backtest-kit/actions/workflows/webpack.yml/badge.svg)](https://github.com/tripolskypetr/backtest-kit/actions/workflows/webpack.yml)
+
+A minimal project scaffold for [backtest-kit](https://github.com/tripolskypetr/backtest-kit). All infrastructure (exchange registration, candle caching, runner, UI, Telegram) is handled by `@backtest-kit/cli` — this project contains only your strategy files.
+
+## 📋 Quick Start
+
+```bash
+npm start         # Run the CLI (append flags below)
+npm run sync:lib  # Refresh library docs in docs/lib/
+```
+
+## 🏃 Running Modes
+
+All modes are invoked via `npm start -- <flags> <entry-point>`.
+
+### 🧪 Backtest
+
+Runs the strategy against historical candle data defined by a `FrameSchema`.
+
+```bash
+npm start -- --backtest --symbol BTCUSDT --strategy feb_2026_strategy --exchange ccxt-exchange --frame feb_2026_frame ./content/feb_2026.strategy.ts
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--backtest` | boolean | — | Enable backtest mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--strategy` | string | first registered | Strategy name from `addStrategySchema` |
+| `--exchange` | string | first registered | Exchange name from `addExchangeSchema` |
+| `--frame` | string | first registered | Frame name from `addFrameSchema` |
+| `--cacheInterval` | string | `1m, 15m, 30m, 1h, 4h` | Comma-separated intervals to pre-cache before the run |
+| `--noCache` | boolean | `false` | Skip candle cache warming |
+| `--verbose` | boolean | `false` | Log every candle fetch to stdout |
+| `--ui` | boolean | `false` | Start web dashboard at `http://localhost:60050` |
+| `--telegram` | boolean | `false` | Send trade notifications to Telegram |
+
+Before the backtest starts, the CLI warms the candle cache for every interval in `--cacheInterval`. On subsequent runs the cache is used directly — no extra API calls. Pass `--noCache` to skip this step.
+
+Module file `./modules/backtest.module.ts` (or `.mjs`) is loaded automatically if it exists.
+
+### 📄 Paper Trading
+
+Connects to the live exchange but places no real orders. Identical code path to `--live` — safe for strategy validation.
+
+```bash
+npm start -- --paper --symbol BTCUSDT --strategy feb_2026_strategy --exchange ccxt-exchange ./content/feb_2026.strategy.ts
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--paper` | boolean | — | Enable paper trading mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--strategy` | string | first registered | Strategy name |
+| `--exchange` | string | first registered | Exchange name |
+| `--verbose` | boolean | `false` | Log every candle fetch to stdout |
+| `--ui` | boolean | `false` | Start web dashboard |
+| `--telegram` | boolean | `false` | Enable Telegram notifications |
+
+Module file `./modules/paper.module.ts` is loaded automatically if it exists.
+
+### 📈 Live Trading
+
+Deploys a real trading bot. Requires exchange API keys in `.env`.
+
+```bash
+npm start -- --live --symbol BTCUSDT --ui --telegram ./content/feb_2026.strategy.ts
+```
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--live` | boolean | — | Enable live trading mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--strategy` | string | first registered | Strategy name |
+| `--exchange` | string | first registered | Exchange name |
+| `--verbose` | boolean | `false` | Log every candle fetch to stdout |
+| `--ui` | boolean | `false` | Start web dashboard |
+| `--telegram` | boolean | `false` | Enable Telegram notifications |
+
+Module file `./modules/live.module.ts` is loaded automatically if it exists. Use it to register a `Broker` adapter that intercepts every trade mutation before internal state changes — exchange rejection rolls back the operation atomically.
+
+## 🌲 Running PineScript Indicators (`--pine`)
+
+Executes a local `.pine` file against a real exchange and prints the output as a Markdown table or saves it to a file.
+
+```bash
+npm start -- --pine ./math/feb_2026.pine --timeframe 15m --limit 500 --when "2026-02-28T00:00:00.000Z" --jsonl
+```
+
+Output file is created at `./math/dump/<name>.jsonl` (next to the `.pine` file).
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--pine` | boolean | — | Enable PineScript execution mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--timeframe` | string | `15m` | Candle interval |
+| `--limit` | string | `250` | Number of candles to fetch |
+| `--when` | string | now | End date — ISO 8601 or Unix ms |
+| `--exchange` | string | first registered | Exchange name |
+| `--output` | string | `.pine` file name | Output file base name (no extension) |
+| `--json` | boolean | `false` | Save output as JSON array |
+| `--jsonl` | boolean | `false` | Save output as JSONL (one row per line) |
+| `--markdown` | boolean | `false` | Save output as Markdown table |
+
+Module file `./modules/pine.module.ts` is loaded automatically. The project includes it pre-configured with CCXT Binance. Override it to use a different exchange.
+
+Only `plot()` calls with `display=display.data_window` produce output columns:
+
+```pine
+plot(close,    "Close",    display=display.data_window)
+plot(position, "Position", display=display.data_window)
+```
+
+## 💾 Dumping Raw Candles (`--dump`)
+
+Fetches raw OHLCV candles from an exchange and saves them to a file.
+
+```bash
+npm start -- --dump --timeframe 15m --limit 500 --when "2026-02-28T00:00:00.000Z" --jsonl
+```
+
+Output file is created at `./dump/<name>.jsonl`.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--dump` | boolean | — | Enable candle dump mode |
+| `--symbol` | string | `BTCUSDT` | Trading pair |
+| `--timeframe` | string | `15m` | Candle interval |
+| `--limit` | string | `250` | Number of candles |
+| `--when` | string | now | End date — ISO 8601 or Unix ms |
+| `--exchange` | string | first registered | Exchange name |
+| `--output` | string | `{SYMBOL}_{LIMIT}_{TIMEFRAME}_{TIMESTAMP}` | Output file base name |
+| `--json` | boolean | `false` | Save as JSON array |
+| `--jsonl` | boolean | `false` | Save as JSONL |
+
+Module file `./modules/dump.module.ts` is loaded automatically. The project includes it pre-configured with CCXT Binance.
+
+## 🧩 Module Hooks
+
+| File | Loaded by mode | Purpose |
+|------|----------------|---------|
+| `modules/backtest.module.ts` | `--backtest` | Register a `Broker` adapter for backtest |
+| `modules/paper.module.ts` | `--paper` | Register a `Broker` adapter for paper trading |
+| `modules/live.module.ts` | `--live` | Register a `Broker` adapter for live trading |
+| `modules/pine.module.ts` | `--pine` | Register an exchange schema for PineScript runs |
+| `modules/dump.module.ts` | `--dump` | Register an exchange schema for candle dumps |
+
+All files are optional — a missing module is a soft warning, not an error. Extensions `.ts`, `.mjs`, `.cjs` are tried automatically.
+
+## 🌍 Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Telegram notifications (required for --telegram)
+CC_TELEGRAM_TOKEN=your_bot_token_here
+CC_TELEGRAM_CHANNEL=-100123456789
+
+# Web UI server (optional, defaults shown)
+CC_WWWROOT_HOST=0.0.0.0
+CC_WWWROOT_PORT=60050
+```
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_TELEGRAM_TOKEN` | — | Telegram bot token (from @BotFather) |
+| `CC_TELEGRAM_CHANNEL` | — | Telegram channel or chat ID |
+| `CC_WWWROOT_HOST` | `0.0.0.0` | UI server bind address |
+| `CC_WWWROOT_PORT` | `60050` | UI server port |
+
+
+## 🗂️ Project Structure
+
+```
+├── content/                  # Strategy entry points (.ts)
+│   └── feb_2026.strategy.ts
+├── docs/                     # Documentation
+│   ├── lib/                  # Auto-fetched library READMEs (via sync:lib)
+│   └── *.md                  # Backtest Kit how-to guides
+├── math/                     # PineScript indicator files (.pine)
+│   └── feb_2026.pine
+├── modules/                  # Side-effect module hooks (loaded automatically)
+│   ├── dump.module.ts        # Exchange schema for --dump mode
+│   └── pine.module.ts        # Exchange schema for --pine mode
+├── report/                   # Strategy research reports (.md)
+│   └── feb_2026.md
+├── scripts/
+│   └── fetch_docs.mjs        # Downloads library READMEs into docs/lib/
+├── CLAUDE.md                 # AI-agent guide for writing strategies
+└── package.json
+```
+
+## 📚 Updating Library Documentation
+
+```bash
+npm run sync:lib
+```
+
+Downloads the latest README files for all bundled libraries into `docs/lib/`. Run this after updating package versions or when you want fresh documentation available to the AI agent.

package/template/project/content/feb_2026.strategy.ts

@@ -0,0 +1,114 @@
+import {
+  addExchangeSchema,
+  addFrameSchema,
+  addStrategySchema,
+  listenError,
+  Cache,
+  Log,
+} from "backtest-kit";
+import {
+  errorData,
+  getErrorMessage,
+  randomString,
+  singleshot,
+} from "functools-kit";
+import ccxt from "ccxt";
+import { run, File, extract } from "@backtest-kit/pinets";
+import { outputNode, resolve, sourceNode } from "@backtest-kit/graph";
+
+const getExchange = singleshot(async () => {
+  const exchange = new ccxt.binance({
+    options: {
+      defaultType: "spot",
+      adjustForTimeDifference: true,
+      recvWindow: 60000,
+    },
+    enableRateLimit: true,
+  });
+  await exchange.loadMarkets();
+  return exchange;
+});
+
+const pineSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const plots = await run(File.fromPath("feb_2026.pine", "../math"), {
+        symbol,
+        timeframe: "15m",
+        limit: 2688,
+      });
+
+      return await extract(plots, {
+        position: "Position",
+        entryPrice: "EntryPrice",
+        tp: "TP",
+        sl: "SL",
+      });
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+const signalOutput = outputNode(async ([pineSource]) => {
+  const position =
+    pineSource.position === -1
+      ? "short"
+      : pineSource.position === 1
+        ? "long"
+        : "wait";
+
+  if (position === "wait") {
+    return null;
+  }
+
+  return {
+    id: randomString(),
+    position,
+    priceOpen: pineSource.entryPrice,
+    priceTakeProfit: pineSource.tp,
+    priceStopLoss: pineSource.sl,
+    minuteEstimatedTime: Infinity,
+  } as const;
+}, pineSource);
+
+addExchangeSchema({
+  exchangeName: "ccxt-exchange",
+  getCandles: async (symbol, interval, since, limit) => {
+    const exchange = await getExchange();
+    const candles = await exchange.fetchOHLCV(
+      symbol,
+      interval,
+      since.getTime(),
+      limit,
+    );
+    return candles.map(([timestamp, open, high, low, close, volume]) => ({
+      timestamp,
+      open,
+      high,
+      low,
+      close,
+      volume,
+    }));
+  },
+});
+
+addFrameSchema({
+  frameName: "feb_2026_frame",
+  interval: "1m",
+  startDate: new Date("2026-02-01T00:00:00Z"),
+  endDate: new Date("2026-02-28T23:59:59Z"),
+  note: "February 2026",
+});
+
+addStrategySchema({
+  strategyName: "feb_2026_strategy",
+  interval: "1m",
+  getSignal: async () => await resolve(signalOutput),
+});
+
+listenError((error) => {
+  Log.debug("error", {
+    error: errorData(error),
+    message: getErrorMessage(error),
+  });
+});

package/template/project/docs/backtest_actions.md

@@ -0,0 +1,158 @@
+# Actions (addActionSchema / IPublicAction / pingActive)
+
+## Overview
+
+Actions are lifecycle hooks that run while a position is open. They are registered with `addActionSchema` and attached to a strategy via `actions` array. The most common use is `pingActive` — called on every tick while a pending signal exists.
+
+```ts
+import {
+  addActionSchema,
+  commitClosePending,
+  getPendingSignal,
+  IPublicAction,
+  ActivePingContract,
+} from "backtest-kit";
+```
+
+---
+
+## `addActionSchema`
+
+```ts
+addActionSchema({
+  actionName: "my_action",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      // called every tick while a position is open
+    }
+  },
+});
+```
+
+Attach to strategy:
+
+```ts
+addStrategySchema({
+  strategyName: "my_strategy",
+  interval: "15m",
+  getSignal: ...,
+  actions: ["my_action"],
+});
+```
+
+---
+
+## `ActivePingContract`
+
+Fields available inside `pingActive`:
+
+| Field | Type | Description |
+|---|---|---|
+| `symbol` | `string` | Trading pair (e.g. `"BTCUSDT"`) |
+
+---
+
+## `getPendingSignal(symbol)`
+
+Returns the currently active pending signal. Use it to read `position`, `priceOpen`, `priceTakeProfit`, `priceStopLoss`.
+
+```ts
+const pendingSignal = await getPendingSignal(event.symbol);
+pendingSignal.position        // "long" | "short"
+pendingSignal.priceOpen       // entry price
+pendingSignal.priceTakeProfit
+pendingSignal.priceStopLoss
+```
+
+---
+
+## `commitClosePending(symbol)`
+
+Closes the active pending signal immediately (market close).
+
+```ts
+await commitClosePending(event.symbol);
+```
+
+---
+
+## Pattern: Close on trend reversal
+
+Close an open position when the trend indicator reverses against it.
+
+```ts
+addActionSchema({
+  actionName: "trend_reversal_close",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      const shouldClose = await resolve(exitSignal);
+      if (shouldClose) {
+        await commitClosePending(event.symbol);
+      }
+    }
+  },
+});
+```
+
+Where `exitSignal` is an output node that returns `boolean`:
+
+```ts
+const exitSignal = outputNode(
+  async ([trend, pendingSignal]) => {
+    if (!pendingSignal) return false;
+    if (pendingSignal.position === "long"  && trend.position === -1) return true;
+    if (pendingSignal.position === "short" && trend.position ===  1) return true;
+    return false;
+  },
+  masterTrendSource,
+  pendingSignalSource,
+);
+```
+
+See `backtest_graph_multiple_outputs.md` for the full pattern with `enterSignal` / `exitSignal`.
+
+---
+
+## Other `IPublicAction` lifecycle methods
+
+Beyond `pingActive`, actions can implement:
+
+| Method | When called |
+|---|---|
+| `pingActive(event)` | Every tick while position is open |
+| `onOpen(event)` | Position just opened |
+| `onClose(event)` | Position closed (TP/SL/manual) |
+| `onIdle(event)` | Every tick when no position is open |
+
+All methods are optional — implement only what you need.
+
+---
+
+## Pattern: DCA (dollar-cost averaging)
+
+From `feb_2024.strategy.ts`:
+
+```ts
+addActionSchema({
+  actionName: "long_dollar_cost_averaging",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      const pendingSignal = await getPendingSignal(event.symbol);
+      if (pendingSignal.position !== "long") return;
+      if (pendingSignal.totalEntries > 5) return;
+      const currentPrice = await getAveragePrice(event.symbol);
+      if (currentPrice > pendingSignal.originalPriceOpen) return;
+      if (await getPositionEntryOverlap(event.symbol, currentPrice, {
+        lowerPercent: 0.5, upperPercent: 0.5,
+      })) return;
+      await commitAverageBuy(event.symbol);
+    }
+  },
+});
+```
+
+Key guards before DCA:
+1. `position !== "long"` — skip if wrong direction
+2. `totalEntries > 5` — cap at 5 entries
+3. `currentPrice > originalPriceOpen` — only average down, not up
+4. `getPositionEntryOverlap` — avoid averaging too close to an existing entry

package/template/project/docs/backtest_graph_multiple_outputs.md

@@ -0,0 +1,137 @@
+# Graph Pattern: Multiple Output Nodes (enterSignal / exitSignal)
+
+## Why Two Output Nodes
+
+A strategy can have separate output nodes for entry and exit logic. This keeps concerns separated and allows `exitSignal` to be reused in both an action (`pingActive`) and risk validators independently.
+
+```
+masterTrendSource ──┬──► enterSignal  →  getSignal()
+                    └──► exitSignal   →  pingActive() in action
+fundamentalSource ──►  enterSignal
+pendingSignalSource ──► exitSignal
+garchSource ────────►  risk validator (resolve directly)
+```
+
+---
+
+## Full Pattern
+
+```ts
+import { sourceNode, outputNode, resolve } from "@backtest-kit/graph";
+import { getPendingSignal, commitClosePending } from "backtest-kit";
+
+// --- Source nodes ---
+
+const masterTrendSource = sourceNode(
+  Cache.fn(
+    async (symbol: string) => {
+      const plots = await run(
+        File.fromPath("master_trend_15m.pine", "../../math"),
+        { symbol, timeframe: "15m", limit: 180 },
+      );
+      return extract(plots, {
+        position: "Position",  // -1 | 0 | 1
+        close: "Close",
+      });
+    },
+    { interval: "15m", key: ([symbol]: [string]) => symbol },
+  ),
+);
+
+// Raw source node — no cache, reads live state every tick
+const pendingSignalSource = sourceNode(
+  async (symbol) => await getPendingSignal(symbol),
+);
+
+// --- Output node: entry ---
+
+const enterSignal = outputNode(
+  async ([trend, fundamental]) => {
+    if (fundamental.position === "wait") return null;
+    if (trend.position === 0) return null;
+    const fundamentalDir = fundamental.position === "long" ? 1 : -1;
+    if (fundamentalDir !== trend.position) return null;
+
+    const position = fundamentalDir === 1 ? "long" : "short";
+    const price = trend.close;
+    return {
+      id: randomString(),
+      position,
+      priceTakeProfit: position === "long" ? price * 1.05 : price * 0.95,
+      priceStopLoss:   position === "long" ? price * 0.95 : price * 1.05,
+      minuteEstimatedTime: 480,
+    } as const;
+  },
+  masterTrendSource,
+  fundamentalSource,
+);
+
+// --- Output node: exit ---
+
+const exitSignal = outputNode(
+  async ([trend, pendingSignal]) => {
+    if (!pendingSignal) return false;
+    if (pendingSignal.position === "long"  && trend.position === -1) return true;
+    if (pendingSignal.position === "short" && trend.position ===  1) return true;
+    return false;
+  },
+  masterTrendSource,    // shared with enterSignal — resolved once per tick
+  pendingSignalSource,
+);
+
+// --- Action uses exitSignal ---
+
+addActionSchema({
+  actionName: "trend_reversal_close",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      const shouldClose = await resolve(exitSignal);
+      if (shouldClose) {
+        await commitClosePending(event.symbol);
+      }
+    }
+  },
+});
+
+// --- Strategy wires enterSignal ---
+
+addStrategySchema({
+  strategyName: "feb_2026_strategy",
+  interval: "15m",
+  getSignal: () => resolve(enterSignal),
+  actions: ["trend_reversal_close"],
+});
+```
+
+---
+
+## Shared Node Deduplication
+
+`masterTrendSource` is a dependency of both `enterSignal` and `exitSignal`. When both are resolved in the same tick, `@backtest-kit/graph` deduplicates by reference — the Pine script runs **once**, not twice.
+
+This is the main reason to split logic into multiple output nodes rather than one large node: each source is computed once regardless of how many output nodes depend on it.
+
+---
+
+## Raw sourceNode (no Cache.fn)
+
+`pendingSignalSource` has no `Cache.fn` wrapper:
+
+```ts
+const pendingSignalSource = sourceNode(
+  async (symbol) => await getPendingSignal(symbol),
+);
+```
+
+Use this pattern when:
+- The data changes every tick and must not be cached (live position state)
+- The source is cheap to fetch (single in-memory lookup)
+- Caching would return stale data within the same candle
+
+Contrast with `masterTrendSource` which uses `Cache.fn` with `interval: "15m"` — Pine runs once per 15m bar and the result is reused for all ticks within that bar.
+
+---
+
+## `exitSignal` return type
+
+`exitSignal` returns `boolean`, not `ISignalDto | null`. Output nodes are not limited to signal shapes — they can return any value that the consumer needs. The action reads `boolean`, the risk validator could read a number, etc.