tradelab 1.1.0 → 1.2.0

package/docs/superpowers/plans/2026-02-indicator-library.md

@@ -1,677 +0,0 @@
-# Indicator Library (`tradelab/ta`) Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Ship a real technical-analysis namespace (`tradelab/ta`) with RSI, MACD, Bollinger Bands, VWAP, Supertrend, Donchian, Keltner, and Stochastics, plus re-exports of the existing `ema`/`atr`/swing helpers.
-
-**Architecture:** One module per indicator family under `src/ta/`, aggregated by `src/ta/index.js`. Every indicator returns a **full-length array aligned to the input** (warmup region filled with `undefined` or the seed value, matching the existing `atr` convention) so values index 1:1 with candles inside `signal()`. Indicators consume either a `number[]` of closes (oscillators) or the candle array (range-based). A new subpath export `tradelab/ta` is added.
-
-**Tech Stack:** Node ESM, `node:test`. No new dependencies.
-
----
-
-### Task 1: Scaffold the `ta` subpath
-
-**Files:**
-
-- Create: `src/ta/index.js`
-- Modify: `package.json` (exports map + files)
-- Modify: `scripts/build-cjs.mjs` (add `ta` bundle)
-- Test: `test/ta/scaffold.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/ta/scaffold.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import * as ta from "../../src/ta/index.js";
-
-test("ta namespace re-exports existing ema and atr", () => {
-  assert.equal(typeof ta.ema, "function");
-  assert.equal(typeof ta.atr, "function");
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/ta/scaffold.test.js`
-Expected: FAIL — cannot find module `../../src/ta/index.js`.
-
-- [ ] **Step 3: Create src/ta/index.js**
-
-```js
-// src/ta/index.js
-export {
-  ema,
-  atr,
-  swingHigh,
-  swingLow,
-  detectFVG,
-  lastSwing,
-  structureState,
-} from "../utils/indicators.js";
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/ta/scaffold.test.js`
-Expected: PASS.
-
-- [ ] **Step 5: Add the subpath to package.json**
-
-In the `exports` object, after the `"./live"` block, add:
-
-```json
-    "./ta": {
-      "types": "./types/ta.d.ts",
-      "import": "./src/ta/index.js",
-      "require": "./dist/cjs/ta.cjs"
-    },
-```
-
-- [ ] **Step 6: Add the ta bundle to scripts/build-cjs.mjs**
-
-Open `scripts/build-cjs.mjs`, find the array/list of entry points it bundles
-(the existing `index`, `data`, `live` entries), and add a `ta` entry mirroring
-the `live` one. For example, if entries look like:
-
-```js
-const entries = [
-  { in: "src/index.js", out: "dist/cjs/index.cjs" },
-  { in: "src/data/index.js", out: "dist/cjs/data.cjs" },
-  { in: "src/live/index.js", out: "dist/cjs/live.cjs" },
-];
-```
-
-add:
-
-```js
-  { in: "src/ta/index.js", out: "dist/cjs/ta.cjs" },
-```
-
-(If the file uses a different shape, follow that shape — the requirement is one
-esbuild output `dist/cjs/ta.cjs` from `src/ta/index.js`.)
-
-- [ ] **Step 7: Verify the build produces the bundle**
-
-Run: `npm run build`
-Expected: exit 0; `dist/cjs/ta.cjs` now exists. Confirm with `ls dist/cjs/ta.cjs`.
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add src/ta/index.js test/ta/scaffold.test.js package.json scripts/build-cjs.mjs
-git commit -m "feat: scaffold tradelab/ta subpath
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 2: Oscillators — RSI, Stochastics, MACD
-
-**Files:**
-
-- Create: `src/ta/oscillators.js`
-- Modify: `src/ta/index.js`
-- Test: `test/ta/oscillators.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/ta/oscillators.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { rsi, stochastic, macd } from "../../src/ta/oscillators.js";
-
-test("rsi of a strictly rising series approaches 100", () => {
-  const closes = Array.from({ length: 30 }, (_, i) => 100 + i);
-  const out = rsi(closes, 14);
-  assert.equal(out.length, closes.length);
-  assert.equal(out[5], undefined); // warmup
-  assert.ok(out[29] > 99);
-});
-
-test("rsi of a strictly falling series approaches 0", () => {
-  const closes = Array.from({ length: 30 }, (_, i) => 100 - i);
-  const out = rsi(closes, 14);
-  assert.ok(out[29] < 1);
-});
-
-test("macd returns aligned macd/signal/histogram arrays", () => {
-  const closes = Array.from({ length: 60 }, (_, i) => 100 + Math.sin(i / 3) * 5);
-  const out = macd(closes, 12, 26, 9);
-  assert.equal(out.macd.length, closes.length);
-  assert.equal(out.signal.length, closes.length);
-  assert.equal(out.histogram.length, closes.length);
-  assert.ok(Number.isFinite(out.macd[59]));
-});
-
-test("stochastic %K stays within [0,100]", () => {
-  const bars = Array.from({ length: 40 }, (_, i) => ({
-    high: 101 + Math.sin(i),
-    low: 99 + Math.sin(i),
-    close: 100 + Math.sin(i) * 0.5,
-  }));
-  const out = stochastic(bars, 14, 3);
-  const k = out.k[39];
-  assert.ok(k >= 0 && k <= 100);
-  assert.equal(out.d.length, bars.length);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/ta/oscillators.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Implement src/ta/oscillators.js**
-
-```js
-// src/ta/oscillators.js
-import { ema } from "../utils/indicators.js";
-
-/**
- * Wilder's RSI. Returns a full-length array; warmup positions are `undefined`.
- */
-export function rsi(closes, period = 14) {
-  const out = new Array(closes.length).fill(undefined);
-  if (closes.length <= period) return out;
-
-  let gainSum = 0;
-  let lossSum = 0;
-  for (let i = 1; i <= period; i += 1) {
-    const change = closes[i] - closes[i - 1];
-    if (change >= 0) gainSum += change;
-    else lossSum -= change;
-  }
-  let avgGain = gainSum / period;
-  let avgLoss = lossSum / period;
-  out[period] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
-
-  for (let i = period + 1; i < closes.length; i += 1) {
-    const change = closes[i] - closes[i - 1];
-    const gain = change > 0 ? change : 0;
-    const loss = change < 0 ? -change : 0;
-    avgGain = (avgGain * (period - 1) + gain) / period;
-    avgLoss = (avgLoss * (period - 1) + loss) / period;
-    out[i] = avgLoss === 0 ? 100 : 100 - 100 / (1 + avgGain / avgLoss);
-  }
-  return out;
-}
-
-/**
- * MACD line, signal line, histogram. All full-length, aligned to input.
- */
-export function macd(closes, fast = 12, slow = 26, signalPeriod = 9) {
-  const emaFast = ema(closes, fast);
-  const emaSlow = ema(closes, slow);
-  const macdLine = closes.map((_, i) => emaFast[i] - emaSlow[i]);
-  const signalLine = ema(macdLine, signalPeriod);
-  const histogram = macdLine.map((v, i) => v - signalLine[i]);
-  return { macd: macdLine, signal: signalLine, histogram };
-}
-
-/**
- * Stochastic oscillator %K (smoothed close position in the high-low range) and
- * %D (SMA of %K). `bars` need { high, low, close }.
- */
-export function stochastic(bars, kPeriod = 14, dPeriod = 3) {
-  const k = new Array(bars.length).fill(undefined);
-  for (let i = kPeriod - 1; i < bars.length; i += 1) {
-    let hh = -Infinity;
-    let ll = Infinity;
-    for (let j = i - kPeriod + 1; j <= i; j += 1) {
-      if (bars[j].high > hh) hh = bars[j].high;
-      if (bars[j].low < ll) ll = bars[j].low;
-    }
-    const range = hh - ll;
-    k[i] = range === 0 ? 0 : ((bars[i].close - ll) / range) * 100;
-  }
-
-  const d = new Array(bars.length).fill(undefined);
-  for (let i = 0; i < bars.length; i += 1) {
-    if (i < kPeriod - 1 + dPeriod - 1) continue;
-    let sum = 0;
-    for (let j = i - dPeriod + 1; j <= i; j += 1) sum += k[j];
-    d[i] = sum / dPeriod;
-  }
-  return { k, d };
-}
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/ta/oscillators.test.js`
-Expected: PASS (4 tests).
-
-- [ ] **Step 5: Re-export from src/ta/index.js**
-
-Append to `src/ta/index.js`:
-
-```js
-export { rsi, macd, stochastic } from "./oscillators.js";
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/ta/oscillators.js src/ta/index.js test/ta/oscillators.test.js
-git commit -m "feat: add rsi, macd, stochastic to ta
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 3: Bands & channels — Bollinger, Donchian, Keltner
-
-**Files:**
-
-- Create: `src/ta/channels.js`
-- Modify: `src/ta/index.js`
-- Test: `test/ta/channels.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/ta/channels.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { bollinger, donchian, keltner } from "../../src/ta/channels.js";
-
-test("bollinger middle equals SMA and band width scales with stddev mult", () => {
-  const closes = Array.from({ length: 30 }, (_, i) => 100 + (i % 2 === 0 ? 1 : -1));
-  const out = bollinger(closes, 20, 2);
-  assert.equal(out.middle.length, closes.length);
-  const i = 25;
-  assert.ok(out.upper[i] > out.middle[i]);
-  assert.ok(out.lower[i] < out.middle[i]);
-  assert.ok(Math.abs(out.upper[i] - out.middle[i] - (out.middle[i] - out.lower[i])) < 1e-9);
-});
-
-test("donchian upper is the rolling high and lower is the rolling low", () => {
-  const bars = Array.from({ length: 25 }, (_, i) => ({
-    high: 100 + i,
-    low: 90 + i,
-    close: 95 + i,
-  }));
-  const out = donchian(bars, 20);
-  const i = 24;
-  assert.equal(out.upper[i], 100 + 24);
-  assert.equal(out.lower[i], 90 + 5);
-});
-
-test("keltner band is centered on EMA with ATR-scaled width", () => {
-  const bars = Array.from({ length: 40 }, (_, i) => ({
-    high: 101 + i * 0.1,
-    low: 99 + i * 0.1,
-    close: 100 + i * 0.1,
-  }));
-  const out = keltner(bars, 20, 14, 2);
-  const i = 39;
-  assert.ok(out.upper[i] > out.middle[i]);
-  assert.ok(out.lower[i] < out.middle[i]);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/ta/channels.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Implement src/ta/channels.js**
-
-```js
-// src/ta/channels.js
-import { ema, atr } from "../utils/indicators.js";
-
-function rollingMean(values, period, i) {
-  let sum = 0;
-  for (let j = i - period + 1; j <= i; j += 1) sum += values[j];
-  return sum / period;
-}
-
-/**
- * Bollinger Bands. `mult` standard deviations around the SMA middle band.
- */
-export function bollinger(closes, period = 20, mult = 2) {
-  const middle = new Array(closes.length).fill(undefined);
-  const upper = new Array(closes.length).fill(undefined);
-  const lower = new Array(closes.length).fill(undefined);
-  for (let i = period - 1; i < closes.length; i += 1) {
-    const avg = rollingMean(closes, period, i);
-    let variance = 0;
-    for (let j = i - period + 1; j <= i; j += 1) variance += (closes[j] - avg) ** 2;
-    const sd = Math.sqrt(variance / period);
-    middle[i] = avg;
-    upper[i] = avg + mult * sd;
-    lower[i] = avg - mult * sd;
-  }
-  return { middle, upper, lower };
-}
-
-/**
- * Donchian channel: rolling highest-high / lowest-low over `period` bars.
- */
-export function donchian(bars, period = 20) {
-  const upper = new Array(bars.length).fill(undefined);
-  const lower = new Array(bars.length).fill(undefined);
-  const middle = new Array(bars.length).fill(undefined);
-  for (let i = period - 1; i < bars.length; i += 1) {
-    let hh = -Infinity;
-    let ll = Infinity;
-    for (let j = i - period + 1; j <= i; j += 1) {
-      if (bars[j].high > hh) hh = bars[j].high;
-      if (bars[j].low < ll) ll = bars[j].low;
-    }
-    upper[i] = hh;
-    lower[i] = ll;
-    middle[i] = (hh + ll) / 2;
-  }
-  return { upper, lower, middle };
-}
-
-/**
- * Keltner channel: EMA middle, +/- mult * ATR width.
- */
-export function keltner(bars, emaPeriod = 20, atrPeriod = 14, mult = 2) {
-  const closes = bars.map((b) => b.close);
-  const mid = ema(closes, emaPeriod);
-  const range = atr(bars, atrPeriod);
-  const upper = new Array(bars.length).fill(undefined);
-  const lower = new Array(bars.length).fill(undefined);
-  const middle = new Array(bars.length).fill(undefined);
-  for (let i = 0; i < bars.length; i += 1) {
-    if (range[i] === undefined) continue;
-    middle[i] = mid[i];
-    upper[i] = mid[i] + mult * range[i];
-    lower[i] = mid[i] - mult * range[i];
-  }
-  return { upper, lower, middle };
-}
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/ta/channels.test.js`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Re-export**
-
-Append to `src/ta/index.js`:
-
-```js
-export { bollinger, donchian, keltner } from "./channels.js";
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/ta/channels.js src/ta/index.js test/ta/channels.test.js
-git commit -m "feat: add bollinger, donchian, keltner to ta
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 4: Trend & volume — Supertrend, VWAP
-
-**Files:**
-
-- Create: `src/ta/trend.js`
-- Modify: `src/ta/index.js`
-- Test: `test/ta/trend.test.js`
-
-- [ ] **Step 1: Write the failing test**
-
-```js
-// test/ta/trend.test.js
-import test from "node:test";
-import assert from "node:assert/strict";
-import { supertrend, vwap } from "../../src/ta/trend.js";
-
-test("supertrend marks an uptrend (dir=1) on a rising series", () => {
-  const bars = Array.from({ length: 40 }, (_, i) => ({
-    high: 101 + i,
-    low: 99 + i,
-    close: 100 + i,
-  }));
-  const out = supertrend(bars, 10, 3);
-  assert.equal(out.direction.length, bars.length);
-  assert.equal(out.direction[39], 1);
-  assert.ok(out.line[39] < bars[39].close); // support trails below price
-});
-
-test("vwap resets each UTC day and lies within the day's range", () => {
-  const day1 = Date.UTC(2025, 0, 2, 14, 30);
-  const day2 = Date.UTC(2025, 0, 3, 14, 30);
-  const bars = [
-    { time: day1, high: 102, low: 98, close: 100, volume: 10 },
-    { time: day1 + 60000, high: 104, low: 100, close: 103, volume: 30 },
-    { time: day2, high: 50, low: 48, close: 49, volume: 5 },
-  ];
-  const out = vwap(bars);
-  assert.equal(out.length, 3);
-  assert.ok(out[1] >= 98 && out[1] <= 104);
-  // day2 resets: vwap equals the typical price of the single day-2 bar
-  assert.ok(Math.abs(out[2] - (50 + 48 + 49) / 3) < 1e-9);
-});
-```
-
-- [ ] **Step 2: Run to verify it fails**
-
-Run: `node --test test/ta/trend.test.js`
-Expected: FAIL — cannot find module.
-
-- [ ] **Step 3: Implement src/ta/trend.js**
-
-```js
-// src/ta/trend.js
-import { atr } from "../utils/indicators.js";
-
-/**
- * Supertrend. Returns { line, direction } full-length.
- * direction: 1 = uptrend (line is support below price), -1 = downtrend.
- */
-export function supertrend(bars, period = 10, mult = 3) {
-  const range = atr(bars, period);
-  const line = new Array(bars.length).fill(undefined);
-  const direction = new Array(bars.length).fill(undefined);
-
-  let prevUpper = Infinity;
-  let prevLower = -Infinity;
-  let prevDir = 1;
-
-  for (let i = 0; i < bars.length; i += 1) {
-    if (range[i] === undefined) continue;
-    const mid = (bars[i].high + bars[i].low) / 2;
-    const basicUpper = mid + mult * range[i];
-    const basicLower = mid - mult * range[i];
-    const close = bars[i].close;
-    const prevClose = i > 0 ? bars[i - 1].close : close;
-
-    const upper = basicUpper < prevUpper || prevClose > prevUpper ? basicUpper : prevUpper;
-    const lower = basicLower > prevLower || prevClose < prevLower ? basicLower : prevLower;
-
-    let dir = prevDir;
-    if (prevDir === 1 && close < lower) dir = -1;
-    else if (prevDir === -1 && close > upper) dir = 1;
-
-    line[i] = dir === 1 ? lower : upper;
-    direction[i] = dir;
-
-    prevUpper = upper;
-    prevLower = lower;
-    prevDir = dir;
-  }
-  return { line, direction };
-}
-
-function dayKeyUTC(timeMs) {
-  const d = new Date(timeMs);
-  return d.getUTCFullYear() * 10000 + (d.getUTCMonth() + 1) * 100 + d.getUTCDate();
-}
-
-/**
- * Session VWAP, reset on each UTC calendar day. `bars` need
- * { time, high, low, close, volume }. When volume is missing/zero, falls back
- * to an unweighted cumulative typical-price average for that day.
- */
-export function vwap(bars) {
-  const out = new Array(bars.length).fill(undefined);
-  let currentDay = null;
-  let cumPV = 0;
-  let cumV = 0;
-  let cumTP = 0;
-  let count = 0;
-
-  for (let i = 0; i < bars.length; i += 1) {
-    const day = dayKeyUTC(bars[i].time);
-    if (day !== currentDay) {
-      currentDay = day;
-      cumPV = 0;
-      cumV = 0;
-      cumTP = 0;
-      count = 0;
-    }
-    const tp = (bars[i].high + bars[i].low + bars[i].close) / 3;
-    const vol = Number.isFinite(bars[i].volume) ? bars[i].volume : 0;
-    cumPV += tp * vol;
-    cumV += vol;
-    cumTP += tp;
-    count += 1;
-    out[i] = cumV > 0 ? cumPV / cumV : cumTP / count;
-  }
-  return out;
-}
-```
-
-- [ ] **Step 4: Run to verify it passes**
-
-Run: `node --test test/ta/trend.test.js`
-Expected: PASS (2 tests).
-
-- [ ] **Step 5: Re-export**
-
-Append to `src/ta/index.js`:
-
-```js
-export { supertrend, vwap } from "./trend.js";
-```
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/ta/trend.js src/ta/index.js test/ta/trend.test.js
-git commit -m "feat: add supertrend and session vwap to ta
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-### Task 5: Types + docs + README mention
-
-**Files:**
-
-- Create: `types/ta.d.ts`
-- Modify: `docs/api-reference.md`
-- Modify: `README.md` (mention the `ta` subpath under importing)
-
-- [ ] **Step 1: Write the type declaration file**
-
-```ts
-// types/ta.d.ts
-export type Candle = {
-  time: number;
-  open: number;
-  high: number;
-  low: number;
-  close: number;
-  volume?: number;
-};
-
-export function ema(values: number[], period?: number): number[];
-export function atr(bars: Candle[], period?: number): (number | undefined)[];
-export function rsi(closes: number[], period?: number): (number | undefined)[];
-export function macd(
-  closes: number[],
-  fast?: number,
-  slow?: number,
-  signalPeriod?: number
-): { macd: number[]; signal: number[]; histogram: number[] };
-export function stochastic(
-  bars: Candle[],
-  kPeriod?: number,
-  dPeriod?: number
-): { k: (number | undefined)[]; d: (number | undefined)[] };
-export function bollinger(
-  closes: number[],
-  period?: number,
-  mult?: number
-): { middle: (number | undefined)[]; upper: (number | undefined)[]; lower: (number | undefined)[] };
-export function donchian(
-  bars: Candle[],
-  period?: number
-): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
-export function keltner(
-  bars: Candle[],
-  emaPeriod?: number,
-  atrPeriod?: number,
-  mult?: number
-): { upper: (number | undefined)[]; lower: (number | undefined)[]; middle: (number | undefined)[] };
-export function supertrend(
-  bars: Candle[],
-  period?: number,
-  mult?: number
-): { line: (number | undefined)[]; direction: (number | undefined)[] };
-export function vwap(bars: Candle[]): (number | undefined)[];
-```
-
-- [ ] **Step 2: Typecheck**
-
-Run: `npm run typecheck`
-Expected: exit 0 (no errors introduced).
-
-- [ ] **Step 3: Document in docs/api-reference.md**
-
-Add a `### tradelab/ta` section listing each indicator, its input shape (closes
-array vs candle array), and its return shape — copy the signatures from
-`types/ta.d.ts` and add one line per indicator describing what it computes.
-
-- [ ] **Step 4: Mention in README importing section**
-
-Under `## Importing` → `### ESM`, add:
-
-```js
-import { rsi, macd, bollinger, vwap, supertrend } from "tradelab/ta";
-```
-
-and the CJS equivalent under `### CommonJS`.
-
-- [ ] **Step 5: Full build + test + lint, then commit**
-
-```bash
-npm run build && npm run lint && npm run format:check && npm test
-```
-
-Expected: all green.
-
-```bash
-git add types/ta.d.ts docs/api-reference.md README.md
-git commit -m "docs: document tradelab/ta indicator namespace
-
-Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
-```
-
----
-
-## Self-review checklist
-
-- [ ] Every indicator returns a full-length array/object aligned to the input (warmup = `undefined`), matching the existing `atr` convention so `signal()` can index by candle position. ✔
-- [ ] `tradelab/ta` resolves in ESM (`exports` map), CJS (`dist/cjs/ta.cjs` from build), and types (`types/ta.d.ts`). ✔ (Tasks 1, 5)
-- [ ] No existing export in `src/utils/indicators.js` changed — `ta` re-exports them. ✔
-- [ ] Signatures in `types/ta.d.ts` match the implementations (e.g. `macd` returns `{ macd, signal, histogram }`, `stochastic` returns `{ k, d }`). ✔