@alphafox/cli 0.2.0 → 0.3.3

package/vendor/backtest-runner/index.d.ts

@@ -0,0 +1,423 @@
+export const TAPE_SERIES_COLUMNS: readonly string[];
+
+export function encodeOhlcvColumns(
+  rows: ReadonlyArray<readonly [number, number, number, number, number, number]>
+): ArrayBuffer;
+
+export const DEFAULT_EXECUTION_MODEL: {
+  readonly pricePath: "ohlc_path_4";
+  readonly makerFeeRate: 0.0002;
+  readonly takerFeeRate: 0.0005;
+  readonly slippageRate: 0.0001;
+};
+
+export type TapeQuoteAsset = "USDT" | "USDC";
+export type TapeCcxtId =
+  | "binanceusdm"
+  | "okx"
+  | "bybit"
+  | "bitget"
+  | "hyperliquid";
+export type TapeExchangeId =
+  | "binance_perp_usdt"
+  | "okx_perp_usdt"
+  | "bybit_perp_usdt"
+  | "bitget_perp_usdt"
+  | "hyperliquid_perp_usdc";
+
+export interface TapeExchangeDefinition {
+  readonly id: TapeExchangeId | string;
+  readonly label: string;
+  readonly ccxtId: TapeCcxtId | string;
+  readonly marketType: "swap";
+  readonly quoteAsset: TapeQuoteAsset;
+}
+
+export const TAPE_EXCHANGES: readonly TapeExchangeDefinition[];
+export const PUBLIC_MARKET_EXCHANGE_BINANCE: "binance_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_OKX: "okx_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_BYBIT: "bybit_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_BITGET: "bitget_perp_usdt";
+export const PUBLIC_MARKET_EXCHANGE_HYPERLIQUID: "hyperliquid_perp_usdc";
+export const HYPERLIQUID_PUBLIC_MARKET_DEXES: readonly string[];
+
+export function resolveTapeExchange(
+  exchangeId: string | TapeExchangeDefinition
+): TapeExchangeDefinition;
+
+export interface TapeExchangeRuntimeConfig {
+  readonly ohlcvPageLimit: number;
+  readonly fundingPageLimit: number;
+  readonly requestParams: Readonly<Record<string, unknown>>;
+  readonly constructorOptions?: Readonly<Record<string, unknown>>;
+  readonly unsupportedTimeframes?: readonly string[];
+}
+
+export function tapeExchangeRuntimeConfig(
+  exchange: TapeExchangeDefinition
+): TapeExchangeRuntimeConfig;
+
+export const DEFAULT_TAPE_CACHE_DIR: string;
+export const CACHE_KEY_VERSION: "closed-series-v2";
+export const CACHE_MAX_AGE_MS: number;
+
+export type CachedOhlcvRow = readonly [
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+];
+
+export interface CachedOhlcvRange {
+  readonly sinceMs: number;
+  readonly untilMs: number;
+  readonly rows: CachedOhlcvRow[];
+}
+
+export interface OhlcvRangeSegment {
+  readonly sinceMs: number;
+  readonly untilMs: number;
+}
+
+export interface FileTapeCache {
+  readonly disabled: boolean;
+  readonly rootDir?: string;
+  read(key: string): Promise<CachedOhlcvRange | null>;
+  write(key: string, range: CachedOhlcvRange): Promise<void>;
+}
+
+export function ohlcvSeriesCacheKey(
+  exchangeId: string,
+  symbol: string,
+  timeframe: string
+): string;
+export function missingCachedOhlcvRanges(
+  cached: CachedOhlcvRange | null,
+  sinceMs: number,
+  untilMs: number
+): OhlcvRangeSegment[];
+export function mergeCachedOhlcvRanges(
+  cached: CachedOhlcvRange | null,
+  addition: CachedOhlcvRange
+): CachedOhlcvRange;
+export function createFileTapeCache(
+  rootDir?: string,
+  options?: { maxAgeMs?: number; nowMs?: number }
+): FileTapeCache;
+export function createDisabledTapeCache(): FileTapeCache;
+
+export type TapeDataQualityMode = "strict" | "basic";
+export type TapeDataIssueCode =
+  | "market_missing"
+  | "ohlcv_missing"
+  | "invalid_ohlcv"
+  | "non_monotonic"
+  | "internal_gap"
+  | "prefix_gap"
+  | "suffix_gap"
+  | "warmup_insufficient"
+  | "load_failed"
+  | "coverage_insufficient";
+
+export interface TapeDataIssue {
+  readonly code: TapeDataIssueCode;
+  readonly symbol: string;
+  readonly timeframe: string;
+  readonly expected?: number;
+  readonly actual?: number;
+  readonly timestamp?: number;
+  readonly message?: string;
+}
+
+export class TapeDataUnavailableError extends Error {
+  readonly issues: readonly TapeDataIssue[];
+  constructor(issues: readonly TapeDataIssue[]);
+}
+
+export function isTapeDataUnavailableError(
+  value: unknown
+): value is TapeDataUnavailableError;
+
+export type EngineBacktestPrecisionMode = "DECIMAL_PLACES" | "TICK_SIZE";
+export type EngineBacktestSubscriptionTier = "free" | "pro" | "pro_max";
+export type EngineBacktestPricePath = "ohlc_path_4" | "close_only";
+
+export interface EngineBacktestExecutionModel {
+  readonly pricePath: EngineBacktestPricePath;
+  readonly makerFeeRate: number;
+  readonly takerFeeRate: number;
+  readonly slippageRate: number;
+}
+
+export interface EngineBacktestTapeMarket {
+  readonly id: string;
+  readonly symbol: string;
+  readonly base?: string;
+  readonly quote?: string;
+  readonly settle?: string;
+  readonly contractSize: number;
+  readonly linear: boolean;
+  readonly precisionMode: EngineBacktestPrecisionMode;
+  readonly precisionAmount?: number;
+  readonly precisionPrice?: number;
+  readonly amountMin?: number;
+  readonly amountMax?: number;
+  readonly priceMin?: number;
+  readonly costMin?: number;
+}
+
+export interface EngineBacktestTapeSeriesRef {
+  readonly symbol: string;
+  readonly timeframe: string;
+  readonly buffer: string;
+  readonly rows: number;
+}
+
+export interface EngineBacktestFundingSample {
+  readonly timestamp: number;
+  readonly rate: number;
+  readonly interval: string;
+}
+
+export interface EngineBacktestTapeInput {
+  readonly from: string;
+  readonly to: string;
+  readonly baseTimeframe: string;
+  readonly markets: Readonly<Record<string, EngineBacktestTapeMarket>>;
+  readonly series: readonly EngineBacktestTapeSeriesRef[];
+  readonly fundingRates?: Readonly<
+    Record<string, readonly EngineBacktestFundingSample[]>
+  >;
+  readonly lowLiquiditySymbols?: readonly string[];
+}
+
+export interface EngineBacktestScenarioTrader {
+  readonly id?: string;
+  readonly name?: string;
+  readonly strategyDefinitionId: string;
+  readonly configSchemaVersion: number;
+  readonly subscriptionTier: EngineBacktestSubscriptionTier;
+  readonly config: unknown;
+}
+
+export interface EngineBacktestScenario {
+  readonly version: 1;
+  readonly runId: string;
+  readonly trader: EngineBacktestScenarioTrader;
+  readonly exchange: {
+    readonly positionSideDual: boolean;
+    readonly initialEquity: number;
+  };
+  readonly executionModel: EngineBacktestExecutionModel;
+  readonly tape: EngineBacktestTapeInput;
+}
+
+export interface EngineBacktestSeriesRequirement {
+  readonly symbol: string;
+  readonly timeframe: string;
+  readonly minWarmupCandles: number;
+}
+
+export interface EngineBacktestAuxiliaryDataRequirement {
+  readonly kind: string;
+  readonly parameters?: Record<string, unknown>;
+}
+
+export interface TapeLoadProgress {
+  readonly stage: "markets" | "ohlcv" | "validation";
+  readonly detail: string;
+  readonly fraction: number;
+}
+
+export interface TapeMarketsSnapshot {
+  readonly markets: Readonly<Record<string, TapeSymbolMarket>>;
+  readonly precisionMode?: number;
+  readonly nowMs?: number;
+}
+
+export interface TapeSymbolMarket {
+  readonly id?: string;
+  readonly symbol?: string;
+  readonly created?: number;
+  readonly base?: string;
+  readonly quote?: string;
+  readonly settle?: string;
+  readonly active?: boolean;
+  readonly type?: string;
+  readonly swap?: boolean;
+  readonly linear?: boolean;
+  readonly inverse?: boolean;
+  readonly contractSize?: number;
+  readonly precision?: { readonly amount?: number; readonly price?: number };
+  readonly limits?: {
+    readonly amount?: { readonly min?: number; readonly max?: number };
+    readonly price?: { readonly min?: number };
+    readonly cost?: { readonly min?: number };
+  };
+}
+
+export type TapeOhlcvFetcher = (
+  symbol: string,
+  timeframe: string,
+  since?: number,
+  limit?: number,
+  params?: Record<string, unknown>
+) => Promise<ReadonlyArray<readonly number[]>>;
+
+export type TapeFundingFetcher = (
+  symbol: string,
+  since?: number,
+  limit?: number,
+  params?: Record<string, unknown>
+) => Promise<ReadonlyArray<{ timestamp?: number; fundingRate?: number }>>;
+
+export interface TapeLoadRequest {
+  readonly exchangeId?: string;
+  readonly exchange?: TapeExchangeDefinition;
+  readonly symbols: readonly string[];
+  readonly baseTimeframe?: string;
+  readonly timeframes: readonly string[];
+  readonly seriesRequirements?: readonly EngineBacktestSeriesRequirement[];
+  readonly needsFunding?: boolean;
+  readonly auxiliaryDataRequirements?: readonly EngineBacktestAuxiliaryDataRequirement[];
+  readonly fromMs: number;
+  readonly toMs: number;
+  readonly dataQualityMode?: TapeDataQualityMode;
+  readonly signal?: AbortSignal;
+  readonly onProgress?: (progress: TapeLoadProgress) => void;
+  readonly nowMs?: number;
+  readonly ohlcvFetcher?: TapeOhlcvFetcher;
+  readonly fundingFetcher?: TapeFundingFetcher;
+  readonly marketsLoader?: () => Promise<TapeMarketsSnapshot>;
+}
+
+export interface TapeProxyOptions {
+  readonly httpsProxy?: string;
+  readonly httpProxy?: string;
+  readonly agent?: unknown;
+}
+
+export interface TapeLoadOptions extends TapeProxyOptions {
+  readonly cache?: FileTapeCache | false | "disable";
+  readonly cacheDir?: string;
+  readonly nowMs?: number;
+  readonly onProgress?: (progress: TapeLoadProgress) => void;
+  readonly createExchange?: (
+    exchange: TapeExchangeDefinition,
+    constructorOptions: Record<string, unknown>
+  ) => Promise<TapeRuntimeExchange> | TapeRuntimeExchange;
+}
+
+export interface TapeRuntimeExchange {
+  markets?: Readonly<Record<string, TapeSymbolMarket>>;
+  precisionMode?: number;
+  loadMarkets(): Promise<Readonly<Record<string, TapeSymbolMarket>>>;
+  fetchTime(): Promise<number>;
+  fetchOHLCV: TapeOhlcvFetcher;
+  fetchFundingRateHistory?: TapeFundingFetcher;
+}
+
+export interface TapeChartSeries {
+  readonly symbol: string;
+  readonly timeframe: string;
+  readonly rows: number;
+  readonly buffer: ArrayBuffer;
+}
+
+export interface TapeLoadResult {
+  readonly tape: EngineBacktestTapeInput;
+  readonly buffers: Record<string, ArrayBuffer>;
+  readonly coverageWarnings: readonly string[];
+  readonly chartData?: {
+    readonly exchangeId: string;
+    readonly series: readonly TapeChartSeries[];
+  };
+}
+
+export function loadTape(
+  request: TapeLoadRequest,
+  options?: TapeLoadOptions
+): Promise<TapeLoadResult>;
+
+export interface AssembleScenarioInput {
+  readonly runId: string;
+  readonly definitionId: string;
+  readonly configSchemaVersion: number;
+  readonly config: unknown;
+  readonly subscriptionTier: EngineBacktestSubscriptionTier;
+  readonly initialEquity: number;
+  readonly traderName?: string;
+  readonly traderId?: string;
+  readonly tape?: EngineBacktestTapeInput;
+  readonly preparedTape?: { readonly tape: EngineBacktestTapeInput };
+  readonly prepared?: { readonly tape: EngineBacktestTapeInput };
+  readonly executionModel?: Partial<EngineBacktestExecutionModel>;
+}
+
+export function assembleScenario(
+  input: AssembleScenarioInput
+): EngineBacktestScenario;
+
+export const TIMEFRAME_MS: Readonly<Record<string, number>>;
+export const ENGINE_BACKTEST_BASE_TIMEFRAME: string;
+export const ENGINE_BACKTEST_WARMUP_CANDLES: number;
+
+export function resolvePlanBaseTimeframe(input: {
+  readonly baseTimeframe?: string | null;
+  readonly timeframes?: readonly string[] | null;
+}): string;
+
+export function abortable<T>(
+  operation: Promise<T>,
+  signal?: AbortSignal
+): Promise<T>;
+
+export function resolveCcxtProxyOptions(
+  options?: TapeProxyOptions,
+  env?: NodeJS.ProcessEnv
+): { httpsProxy?: string; httpProxy?: string; agent?: unknown };
+
+export function buildCcxtConstructorOptions(
+  exchange: TapeExchangeDefinition,
+  options?: TapeProxyOptions & { runtimeConfig?: TapeExchangeRuntimeConfig }
+): Record<string, unknown>;
+
+export function isClosedCandle(
+  timestampMs: number,
+  timeframe: string,
+  toMs: number
+): boolean;
+
+export function ohlcvSeriesStartMs(
+  fromMs: number,
+  timeframe: string,
+  market?: Pick<TapeSymbolMarket, "created">
+): number;
+
+export function effectiveTapeEndMs(
+  requestedToMs: number,
+  nowMs?: number,
+  baseTimeframe?: string
+): number;
+
+export function inferFundingIntervals(
+  samples: readonly Omit<EngineBacktestFundingSample, "interval">[]
+): EngineBacktestFundingSample[];
+
+export function classifyTapeSymbolsForPreflight(
+  symbols: readonly string[],
+  markets: Readonly<Record<string, TapeSymbolMarket>>,
+  quoteAsset: TapeQuoteAsset
+): {
+  readonly availableSymbols: readonly string[];
+  readonly missingSymbols: readonly string[];
+};
+
+export function resolveEngineBacktestPrecisionMode(
+  precisionMode: number | undefined,
+  exchangeLabel: string
+): EngineBacktestPrecisionMode;
+
+export function resolveTapeCache(options?: TapeLoadOptions): FileTapeCache;

package/vendor/backtest-runner/index.mjs

@@ -0,0 +1,59 @@
+export { TAPE_SERIES_COLUMNS, encodeOhlcvColumns } from "./lib/encode.mjs";
+export {
+  DEFAULT_EXECUTION_MODEL,
+  assembleScenario,
+} from "./lib/scenario.mjs";
+export {
+  TAPE_EXCHANGES,
+  PUBLIC_MARKET_EXCHANGE_BINANCE,
+  PUBLIC_MARKET_EXCHANGE_OKX,
+  PUBLIC_MARKET_EXCHANGE_BYBIT,
+  PUBLIC_MARKET_EXCHANGE_BITGET,
+  PUBLIC_MARKET_EXCHANGE_HYPERLIQUID,
+  HYPERLIQUID_PUBLIC_MARKET_DEXES,
+  resolveTapeExchange,
+  tapeExchangeRuntimeConfig,
+} from "./lib/exchanges.mjs";
+export {
+  DEFAULT_TAPE_CACHE_DIR,
+  CACHE_KEY_VERSION,
+  CACHE_MAX_AGE_MS,
+  ohlcvSeriesCacheKey,
+  missingCachedOhlcvRanges,
+  mergeCachedOhlcvRanges,
+  createFileTapeCache,
+  createDisabledTapeCache,
+} from "./lib/cache.mjs";
+export {
+  TapeDataUnavailableError,
+  isTapeDataUnavailableError,
+  evaluateOhlcvCoverage,
+  analyzeOhlcvCoverage,
+} from "./lib/coverage.mjs";
+export {
+  TIMEFRAME_MS,
+  ENGINE_BACKTEST_BASE_TIMEFRAME,
+  ENGINE_BACKTEST_WARMUP_CANDLES,
+  resolvePlanBaseTimeframe,
+} from "./lib/timeframes.mjs";
+export {
+  abortable,
+} from "./lib/abortable.mjs";
+export {
+  resolveCcxtProxyOptions,
+  buildCcxtConstructorOptions,
+} from "./lib/proxy.mjs";
+export {
+  isClosedCandle,
+  ohlcvSeriesStartMs,
+  fetchClosedOhlcvRange,
+  loadSeriesWithCache,
+} from "./lib/series.mjs";
+export {
+  loadTape,
+  resolveTapeCache,
+  effectiveTapeEndMs,
+  inferFundingIntervals,
+  classifyTapeSymbolsForPreflight,
+  resolveEngineBacktestPrecisionMode,
+} from "./lib/tape-loader.mjs";

package/vendor/backtest-runner/lib/abortable.mjs

@@ -0,0 +1,23 @@
+export function abortError(signal) {
+  if (signal?.reason !== undefined) {
+    return signal.reason;
+  }
+  if (typeof DOMException === "function") {
+    return new DOMException("The operation was aborted", "AbortError");
+  }
+  const error = new Error("The operation was aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export function abortable(operation, signal) {
+  if (!signal) return operation;
+  signal.throwIfAborted();
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(resolve, reject).finally(() => {
+      signal.removeEventListener("abort", onAbort);
+    });
+  });
+}

package/vendor/backtest-runner/lib/cache.mjs

@@ -0,0 +1,159 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export const CACHE_KEY_VERSION = "closed-series-v2";
+export const CACHE_MAX_AGE_MS = 30 * 86_400_000;
+export const DEFAULT_TAPE_CACHE_DIR = path.join(
+  os.homedir(),
+  ".alphafox",
+  "cache",
+  "engine-backtest"
+);
+
+export function ohlcvSeriesCacheKey(exchangeId, symbol, timeframe) {
+  return `${CACHE_KEY_VERSION}|${exchangeId}|${symbol}|${timeframe}`;
+}
+
+export function missingCachedOhlcvRanges(cached, sinceMs, untilMs) {
+  if (untilMs <= sinceMs) return [];
+  if (!cached || cached.untilMs < sinceMs || cached.sinceMs > untilMs) {
+    return [{ sinceMs, untilMs }];
+  }
+
+  const missing = [];
+  if (sinceMs < cached.sinceMs) {
+    missing.push({ sinceMs, untilMs: Math.min(untilMs, cached.sinceMs) });
+  }
+  if (untilMs > cached.untilMs) {
+    missing.push({ sinceMs: Math.max(sinceMs, cached.untilMs), untilMs });
+  }
+  return missing.filter((range) => range.untilMs > range.sinceMs);
+}
+
+export function mergeCachedOhlcvRanges(cached, addition) {
+  if (
+    !cached ||
+    addition.untilMs < cached.sinceMs ||
+    addition.sinceMs > cached.untilMs
+  ) {
+    return addition;
+  }
+
+  const rowsByTimestamp = new Map();
+  for (const row of cached.rows) rowsByTimestamp.set(row[0], row);
+  for (const row of addition.rows) rowsByTimestamp.set(row[0], row);
+  return {
+    sinceMs: Math.min(cached.sinceMs, addition.sinceMs),
+    untilMs: Math.max(cached.untilMs, addition.untilMs),
+    rows: [...rowsByTimestamp.values()].sort(
+      (left, right) => left[0] - right[0]
+    ),
+  };
+}
+
+export function createDisabledTapeCache() {
+  return {
+    disabled: true,
+    async read() {
+      return null;
+    },
+    async write() {},
+  };
+}
+
+/**
+ * Filesystem closed-series cache. Semantics match the web IndexedDB cache:
+ * one rolling range per exchange+symbol+timeframe; hits only fetch gaps.
+ *
+ * @param {string} [rootDir]
+ * @param {{ maxAgeMs?: number, nowMs?: number }} [options]
+ */
+export function createFileTapeCache(
+  rootDir = DEFAULT_TAPE_CACHE_DIR,
+  options = {}
+) {
+  const resolvedRoot = path.resolve(rootDir);
+  const maxAgeMs = options.maxAgeMs ?? CACHE_MAX_AGE_MS;
+  const now = () => options.nowMs ?? Date.now();
+
+  return {
+    disabled: false,
+    rootDir: resolvedRoot,
+    async read(key) {
+      try {
+        const raw = await fs.readFile(filePathForKey(resolvedRoot, key), "utf8");
+        const record = JSON.parse(raw);
+        const fresh =
+          record &&
+          Number.isFinite(record.storedAt) &&
+          now() - record.storedAt <= maxAgeMs;
+        if (
+          !fresh ||
+          !Number.isFinite(record.sinceMs) ||
+          !Number.isFinite(record.untilMs) ||
+          record.untilMs <= record.sinceMs ||
+          !Array.isArray(record.rows) ||
+          !record.rows.every(isBasicOhlcvRow)
+        ) {
+          return null;
+        }
+        return {
+          sinceMs: record.sinceMs,
+          untilMs: record.untilMs,
+          rows: record.rows,
+        };
+      } catch (error) {
+        if (error && error.code === "ENOENT") {
+          return null;
+        }
+        // Cache unavailability must not block a run.
+        return null;
+      }
+    },
+    async write(key, range) {
+      try {
+        const filePath = filePathForKey(resolvedRoot, key);
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        const record = {
+          key,
+          sinceMs: range.sinceMs,
+          untilMs: range.untilMs,
+          rows: range.rows,
+          storedAt: now(),
+        };
+        const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(record), "utf8");
+        await fs.rename(tmp, filePath);
+      } catch {
+        // Best-effort cache; ignore write failures.
+      }
+    },
+  };
+}
+
+function isBasicOhlcvRow(row) {
+  return (
+    Array.isArray(row) &&
+    row.length === 6 &&
+    row.every(Number.isFinite)
+  );
+}
+
+export function filePathForKey(rootDir, key) {
+  const parts = key.split("|");
+  if (parts.length >= 4) {
+    const version = parts[0];
+    const exchangeId = parts[1];
+    const timeframe = parts[parts.length - 1];
+    const symbol = parts.slice(2, -1).join("|");
+    return path.join(
+      rootDir,
+      version,
+      exchangeId,
+      encodeURIComponent(symbol),
+      `${timeframe}.json`
+    );
+  }
+  return path.join(rootDir, `${encodeURIComponent(key)}.json`);
+}