@backtest-kit/cli 5.11.0 → 5.11.1

package/template/project/CLAUDE.md

@@ -0,0 +1,158 @@
+## Guide
+
+### How to Write a Strategy
+
+**What NOT to do**
+
+- Don't read all project files and bloat the context.
+
+   Strategies are written as simple `.pine` files; the command to run them is below.
+
+- Don't brute-force iterate.
+
+   The worst thing you can do is start incrementally writing into an existing project file. That's not how this works — you need market analysis, not work for the sake of work.
+
+- Don't sacrifice efficiency for universality.
+
+   Markets change. By building a universal solution you lose the optimization that is the competitive edge actually generating profit at any given moment.
+
+- Don't write `.pine` files with side effects.
+
+   You don't need `var` and `na` in PineScript — compute all values on every iteration. This makes errors and unpredictable behavior more likely to surface before going to production. Keep the code easy to understand; avoid premature optimization.
+
+- Don't use hacks in trading strategy code.
+
+   You cannot disguise the absence of an SL by using ATR when the exit keeps shifting relative to the close price on every iteration. Trailing criteria must be finite — you cannot keep shifting the stop loss forever hoping for a bounce or a drop. Avoid HOLD in any form.
+
+- Don't build strategies that produce one signal every few days.
+
+   Three profitable signals is not a successful trading strategy — it's luck. To evaluate a strategy statistically you need at least one signal per day.
+
+**What TO do**
+
+- Every strategy is written for a single calendar month.
+
+   Follow the naming pattern or refuse to work. The money is in optimizing for current market conditions; a backtest spanning two or more months is mathematically meaningless because the final balance will wipe out profit through commission whipsaw.
+
+   * `./math/jan_2026.pine`, `./content/jan_2026.strategy.ts`
+   * `./math/feb_2026.pine`, `./content/feb_2026.strategy.ts`
+   * `./math/march_2026.pine`, `./content/march_2026.strategy.ts`
+   * `./math/apr_2026.pine`, `./content/apr_2026.strategy.ts`
+   * `./math/may_2026.pine`, `./content/may_2026.strategy.ts`
+
+- Read the news background for the chosen time period.
+
+   The focus should ALWAYS be on negative news. Searching for the Bitcoin price gives you marketing trash. Searching for analytics gives you SEO garbage. Use queries like:
+
+   * Bitcoin negative news March 2026 price drop regulatory problems…
+   * bitcoin price February 5 2024 current level forecast analytics BTC
+   * bitcoin negative news February 2024 problems regulator crackdown bitcoin
+   * bitcoin negative news March 2026 regulatory problems bans
+   * bitcoin security hackers fraud regulation negative news problems
+
+- Create a `--dump` to output candles.
+
+   You need to see where the money actually is in the market. Identify the general trend: if it's bearish, protect against LONGs; if it's bullish, protect against SHORTs. There may be a short-term bounce or panic driven by geopolitical news.
+
+- The market may be ranging (sideways).
+
+   There are cases when no position should be opened at all — your analysis must account for this.
+
+- TP/SL should be dynamic, but not scalping.
+
+   The exchange charges 0.2% to enter and 0.2% to exit. You may think the strategy is profitable, but it's whipsaw. Minimum TP: 1%.
+
+- Don't try to build an all-weather strategy.
+
+   I need to understand where the money is in the market only within the specified time period. If the strategy stops being profitable I'll simply ask you to run the analysis again.
+
+- Don't build HOLD strategies.
+
+   I need to find where the money actually is in the market, not sit in a position hoping for luck. The criterion for "where the money is" must be expressed as a formula that finds effective entry points that lead to profit directly.
+
+- Don't brut force strategies.
+
+    Use fresh strategies with different concepts. Do not edit existing strategy one cause this will give you a loop even if you coded it. I need concept engineering
+
+### Market Candle Dump
+
+File `BTCUSDT_500_15m_1772236800000.jsonl` will be created at `./dump/BTCUSDT_500_15m_1772236800000.jsonl`
+
+```
+npm start -- --dump --timeframe 15m --limit 500 --when "2026-02-28T00:00:00.000Z" --jsonl
+```
+
+### Running `.pine` Files
+
+File `impulse_trend_15m.jsonl` will be created at `./math/dump/impulse_trend_15m.jsonl`
+
+```
+npm start --  --pine ./math/impulse_trend_15m.pine --timeframe 15m --limit 500 --when "2026-02-28T00:00:00.000Z" --jsonl
+```
+
+### Algorithm
+
+**Planning the Work**
+
+1. Read the `.pine` file from the previous month if one exists.
+
+2. Read news from the internet for the current month with a focus on negative news.
+
+3. Correlate the news background with the candle dump. News sources must visibly influence the candle data for the chosen time period: price bounce, sideways range, neutral trend, decline, or rally.
+
+4. Understand why the previous month's file stopped working by interpreting its logic in the context of the new news background.
+
+5. In addition to news, review the candle dump independently: assess volatility, market gaps, trading volumes, and risks.
+
+**Writing the Strategy**
+
+1. Create NEW files for the current month and write them from scratch. Do not copy-paste and do not attempt to brute-force parameters. New month — new strategy.
+
+2. Run the `.pine` file and review the output. The acceptance criterion is a profitable trading strategy, not code for the sake of code. Do not stop until profit is achieved.
+
+3. After obtaining a profitable strategy, ALWAYS save the knowledge base used to build it into a markdown file with fundamental market analysis, following the naming pattern:
+
+   * `./report/jan_2026.md`
+   * `./report/feb_2026.md`
+   * `./report/march_2026.md`
+
+4. Run a code review as a separate agent.
+
+   The code review must check the strategy for perpetual hold without strict exit conditions — for example, a trailing SL that shifts forever relative to the close of the last candle. I need not just to make money, but to mathematically identify where the money is in the market in order to avoid large portfolio liquidity drawdowns.
+
+5. If the code review fails, incorporate the findings and rebuild the strategy from scratch following this guide.
+
+### Recommendations
+
+- Search the internet for ideas.
+
+   I welcome borrowing trading ideas from other people via internet search rather than brute-forcing options. It's important not only to find someone else's concept but also to verify in practice that it is actually profitable.
+
+- Analyze market structure.
+
+   Looking at the candles reveals the structures present in the current month: sideways range, neutral trend, bullish trend, bearish trend, high volatility. Think through how to identify and how to act in each case.
+
+- Use a TODO list.
+
+   This guide has many steps. Form a TODO list and work through it step by step, marking each item complete. Include news research, candle `--dump` analysis, pine strategy analysis — as granularly as possible.
+
+- Use deep research.
+
+   The guide calls for intelligent market analysis, not code for the sake of code. Think carefully; don't cut corners on tokens.
+
+- Think logically.
+
+   A 1% target cannot be reached in less than 4 hours. A target below 1% is uninteresting because slippage will knock the position out before achieving an effective Risk/Reward. I don't need a formal reply — I need market analysis.
+
+### Deliverable
+
+A `.pine` file free of marketing fluff:
+
+- Forbidden: TP=0.5% SL=-10% and any similar asymmetric nonsense. Risk management must be sound and must rule out holding on luck.
+- Clearly described and commented operating modes with references to the time period on which they were tested.
+- An honest profitability summary in the file header as a comment.
+- An honest average daily signal count in the file header.
+- An honest `sharpeRatio`, `avgPnl`, `stdDev` in the file header.
+- One or more signals per day — more is better.
+
+If it is impossible to make money, do not try to fudge the results. Write it as it is, without embellishment.

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.