@alphafox/cli 0.2.0 → 0.3.3

package/dist/engine-backtest/fetch-runtime.js

@@ -0,0 +1,170 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BLOB_RUNTIME_FILES = exports.DEFAULT_BACKTEST_WASM_MANIFEST_URL = exports.BACKTEST_RUNTIME_PROTOCOL = void 0;
+exports.resolveBacktestWasmManifestUrl = resolveBacktestWasmManifestUrl;
+exports.resolveRuntimeCacheDir = resolveRuntimeCacheDir;
+exports.parseEngineBacktestBlobManifest = parseEngineBacktestBlobManifest;
+exports.ensureBlobRuntime = ensureBlobRuntime;
+const node_fs_1 = require("node:fs");
+const promises_1 = require("node:fs/promises");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const promises_2 = require("node:stream/promises");
+const node_stream_1 = require("node:stream");
+const errors_1 = require("./errors");
+exports.BACKTEST_RUNTIME_PROTOCOL = 1;
+exports.DEFAULT_BACKTEST_WASM_MANIFEST_URL = "https://zwggllrrna54e2d6.public.blob.vercel-storage.com/engine-backtest/latest.json";
+exports.BLOB_RUNTIME_FILES = {
+    wasm: "tradingfox-backtest.wasm",
+    wasmExec: "wasm_exec.js",
+    worker: "worker.mjs",
+    client: "index.mjs",
+    node: "node.mjs",
+    nodeWorker: "worker-node.mjs",
+    nodeWorkerPath: "worker-node-path.mjs",
+};
+function resolveBacktestWasmManifestUrl(env = process.env) {
+    return (env.ALPHAFOX_BACKTEST_WASM_MANIFEST_URL?.trim() ||
+        exports.DEFAULT_BACKTEST_WASM_MANIFEST_URL);
+}
+function resolveRuntimeCacheDir(hash, env = process.env) {
+    const override = env.ALPHAFOX_BACKTEST_RUNTIME_CACHE_DIR?.trim();
+    if (override) {
+        return (0, node_path_1.join)(override, hash);
+    }
+    const xdg = env.XDG_CACHE_HOME?.trim();
+    return (0, node_path_1.join)(xdg || (0, node_path_1.join)((0, node_os_1.homedir)(), ".cache"), "alphafox", "engine-backtest", hash);
+}
+function parseEngineBacktestBlobManifest(value) {
+    if (!value || typeof value !== "object") {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_manifest_invalid",
+            message: "Backtest runtime manifest is not an object.",
+        });
+    }
+    const record = value;
+    if (record.protocol !== exports.BACKTEST_RUNTIME_PROTOCOL) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_protocol_mismatch",
+            message: `Backtest runtime protocol is incompatible (got ${String(record.protocol)}, expected ${exports.BACKTEST_RUNTIME_PROTOCOL}).`,
+        });
+    }
+    return {
+        version: readRequiredString(record.version, "version"),
+        hash: readRequiredString(record.hash, "hash"),
+        protocol: exports.BACKTEST_RUNTIME_PROTOCOL,
+        engineSha: readOptionalString(record.engineSha),
+        packageVersion: readOptionalString(record.packageVersion),
+        wasm: readRequiredHttps(record.wasm, "wasm"),
+        wasmExec: readRequiredHttps(record.wasmExec, "wasmExec"),
+        worker: readRequiredHttps(record.worker, "worker"),
+        client: readRequiredHttps(record.client, "client"),
+        node: readRequiredHttps(record.node, "node"),
+        nodeWorker: readRequiredHttps(record.nodeWorker, "nodeWorker"),
+        nodeWorkerPath: readRequiredHttps(record.nodeWorkerPath, "nodeWorkerPath"),
+    };
+}
+async function ensureBlobRuntime(env = process.env, hooks) {
+    const fetchImpl = hooks?.fetch ?? fetch;
+    const manifestUrl = resolveBacktestWasmManifestUrl(env);
+    let response;
+    try {
+        response = await fetchImpl(manifestUrl, { cache: "no-cache" });
+    }
+    catch (error) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_manifest_unavailable",
+            message: `Cannot load backtest runtime manifest: ${error instanceof Error ? error.message : String(error)}`,
+            hint: "Check network access to Vercel Blob, or set ALPHAFOX_USE_LOCAL_BACKTEST=1 with a local Engine build.",
+            details: { manifestUrl },
+        });
+    }
+    if (!response.ok) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_manifest_unavailable",
+            message: `Backtest runtime manifest unavailable (HTTP ${response.status}).`,
+            hint: "Check network access to Vercel Blob, or set ALPHAFOX_USE_LOCAL_BACKTEST=1 with a local Engine build.",
+            details: { manifestUrl, status: response.status },
+        });
+    }
+    const manifest = parseEngineBacktestBlobManifest(await response.json());
+    const directory = hooks?.cacheDir ?? resolveRuntimeCacheDir(manifest.hash, env);
+    await (0, promises_1.mkdir)(directory, { recursive: true });
+    for (const key of Object.keys(exports.BLOB_RUNTIME_FILES)) {
+        const fileName = exports.BLOB_RUNTIME_FILES[key];
+        const target = (0, node_path_1.join)(directory, fileName);
+        if (await fileExists(target)) {
+            continue;
+        }
+        await downloadFile(fetchImpl, manifest[key], target);
+    }
+    return {
+        manifest,
+        directory,
+        nodeEntry: (0, node_path_1.join)(directory, exports.BLOB_RUNTIME_FILES.node),
+    };
+}
+async function downloadFile(fetchImpl, url, target) {
+    let response;
+    try {
+        response = await fetchImpl(url);
+    }
+    catch (error) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_download_failed",
+            message: `Cannot download backtest runtime ${url}: ${error instanceof Error ? error.message : String(error)}`,
+        });
+    }
+    if (!response.ok || !response.body) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_download_failed",
+            message: `Backtest runtime file unavailable (${url} HTTP ${response.status}).`,
+        });
+    }
+    const tmp = `${target}.tmp`;
+    await (0, promises_2.pipeline)(node_stream_1.Readable.fromWeb(response.body), (0, node_fs_1.createWriteStream)(tmp));
+    await (0, promises_1.rename)(tmp, target);
+}
+async function fileExists(path) {
+    try {
+        const info = await (0, promises_1.stat)(path);
+        return info.isFile() && info.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function readRequiredHttps(value, field) {
+    const text = readRequiredString(value, field);
+    if (!text.startsWith("https://")) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_manifest_invalid",
+            message: `Backtest runtime manifest ${field} must be an https URL.`,
+        });
+    }
+    return text;
+}
+function readRequiredString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "runtime_manifest_invalid",
+            message: `Backtest runtime manifest is missing ${field}.`,
+        });
+    }
+    return value.trim();
+}
+function readOptionalString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed === "" ? undefined : trimmed;
+}

package/dist/engine-backtest/native-import.d.ts

@@ -0,0 +1 @@
+export declare function importNativeModule(specifier: string): Promise<unknown>;

package/dist/engine-backtest/native-import.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importNativeModule = importNativeModule;
+// Keep import() behind a runtime compiler boundary. TypeScript rewrites a
+// directly-authored import() to require() when emitting this project as CJS,
+// and require() cannot load the runner/wasm .mjs entry points.
+const nativeImport = new Function("specifier", "return import(specifier);");
+function importNativeModule(specifier) {
+    return nativeImport(specifier);
+}

package/dist/engine-backtest/parse-args.d.ts

@@ -0,0 +1,6 @@
+import type { EngineBacktestRunArgs, ExecutionModel, InclusiveUtcDateRange } from "./types";
+export declare const ENGINE_BACKTEST_RUN_USAGE: string[];
+export declare function parseInclusiveUtcDateRange(rangeStart: string, rangeEnd: string): InclusiveUtcDateRange;
+export declare function parseRangeFlag(raw: string): InclusiveUtcDateRange;
+export declare function parseExecutionModelJson(raw: string): Partial<ExecutionModel>;
+export declare function parseEngineBacktestRunArgs(args: readonly string[]): EngineBacktestRunArgs;

package/dist/engine-backtest/parse-args.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_BACKTEST_RUN_USAGE = void 0;
+exports.parseInclusiveUtcDateRange = parseInclusiveUtcDateRange;
+exports.parseRangeFlag = parseRangeFlag;
+exports.parseExecutionModelJson = parseExecutionModelJson;
+exports.parseEngineBacktestRunArgs = parseEngineBacktestRunArgs;
+const errors_1 = require("./errors");
+const replay_timeframe_1 = require("./replay-timeframe");
+const DAY_MS = 86_400_000;
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TIERS = new Set(["free", "pro", "pro_max"]);
+const DATA_QUALITY = new Set(["strict", "basic"]);
+const PRICE_PATHS = new Set(["ohlc_path_4", "close_only"]);
+exports.ENGINE_BACKTEST_RUN_USAGE = [
+    "alphafox engine-backtest run --experiment <uuid> --definition <id> --config @file.json --exchange <id> --range YYYY-MM-DD..YYYY-MM-DD --initial-equity N [--replay-timeframe 1m]",
+    "alphafox engine-backtest run --create-experiment --name <name> --definition <id> --config @file.json --exchange <id> --from YYYY-MM-DD --to YYYY-MM-DD --initial-equity N",
+];
+function usage(message, subtype = "invalid_args") {
+    throw new errors_1.EngineBacktestError({
+        type: "usage",
+        subtype,
+        message,
+        hint: exports.ENGINE_BACKTEST_RUN_USAGE[0],
+        status: 400,
+    });
+}
+function takeValue(args, i, flag) {
+    const next = args[i + 1];
+    if (next === undefined || next.startsWith("--")) {
+        usage(`Missing value for ${flag}`, "missing_flag_value");
+    }
+    return { value: next, next: i + 1 };
+}
+function parseInclusiveUtcDateRange(rangeStart, rangeEnd) {
+    if (!ISO_DATE.test(rangeStart) || !ISO_DATE.test(rangeEnd)) {
+        usage(`Dates must be YYYY-MM-DD (got ${rangeStart}..${rangeEnd})`, "invalid_range");
+    }
+    const fromMs = Date.parse(`${rangeStart}T00:00:00Z`);
+    const endStartMs = Date.parse(`${rangeEnd}T00:00:00Z`);
+    const toMs = endStartMs + DAY_MS;
+    if (!Number.isFinite(fromMs) ||
+        !Number.isFinite(endStartMs) ||
+        !Number.isFinite(toMs) ||
+        new Date(fromMs).toISOString().slice(0, 10) !== rangeStart ||
+        new Date(endStartMs).toISOString().slice(0, 10) !== rangeEnd ||
+        endStartMs < fromMs) {
+        usage(`Invalid inclusive UTC range ${rangeStart}..${rangeEnd}`, "invalid_range");
+    }
+    return { rangeStart, rangeEnd, fromMs, toMs };
+}
+function parseRangeFlag(raw) {
+    const parts = raw.split("..");
+    if (parts.length !== 2 || !parts[0] || !parts[1]) {
+        usage(`--range must be YYYY-MM-DD..YYYY-MM-DD (got ${raw})`, "invalid_range");
+    }
+    return parseInclusiveUtcDateRange(parts[0], parts[1]);
+}
+function parseExecutionModelJson(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        usage("--execution-model must be JSON", "invalid_execution_model");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        usage("--execution-model must be a JSON object", "invalid_execution_model");
+    }
+    const o = parsed;
+    const out = {};
+    if (o.pricePath !== undefined) {
+        if (typeof o.pricePath !== "string" || !PRICE_PATHS.has(o.pricePath)) {
+            usage(`--execution-model.pricePath must be ohlc_path_4|close_only`, "invalid_execution_model");
+        }
+        out.pricePath = o.pricePath;
+    }
+    for (const key of ["makerFeeRate", "takerFeeRate", "slippageRate"]) {
+        if (o[key] === undefined)
+            continue;
+        const n = Number(o[key]);
+        if (!Number.isFinite(n)) {
+            usage(`--execution-model.${key} must be a finite number`, "invalid_execution_model");
+        }
+        out[key] = n;
+    }
+    return out;
+}
+function parseEngineBacktestRunArgs(args) {
+    let experimentId;
+    let createExperiment = false;
+    let name;
+    let definitionId;
+    let definitionLabelZh;
+    let definitionLabelEn;
+    let configRaw;
+    let exchange;
+    let rangeRaw;
+    let from;
+    let to;
+    let initialEquity;
+    let tier;
+    let dataQualityMode = "strict";
+    let configSchemaVersion;
+    let executionModelOverride;
+    let persist = true;
+    let help = false;
+    let replayTimeframe = replay_timeframe_1.ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME;
+    for (let i = 0; i < args.length; i += 1) {
+        const a = args[i];
+        if (a === "--help" || a === "-h") {
+            help = true;
+            continue;
+        }
+        if (a === "--create-experiment") {
+            createExperiment = true;
+            continue;
+        }
+        if (a === "--no-persist") {
+            persist = false;
+            continue;
+        }
+        if (!a.startsWith("--")) {
+            usage(`Unexpected argument: ${a}`, "unexpected_arg");
+        }
+        const eq = a.indexOf("=");
+        const flag = eq >= 0 ? a.slice(0, eq) : a;
+        const inline = eq >= 0 ? a.slice(eq + 1) : undefined;
+        const read = () => {
+            if (inline !== undefined)
+                return inline;
+            const taken = takeValue(args, i, flag);
+            i = taken.next;
+            return taken.value;
+        };
+        switch (flag) {
+            case "--experiment":
+                experimentId = read().trim();
+                break;
+            case "--name":
+                name = read();
+                break;
+            case "--definition":
+                definitionId = read().trim();
+                break;
+            case "--definition-label-zh":
+                definitionLabelZh = read();
+                break;
+            case "--definition-label-en":
+                definitionLabelEn = read();
+                break;
+            case "--config":
+                configRaw = read();
+                break;
+            case "--exchange":
+                exchange = read().trim();
+                break;
+            case "--range":
+                rangeRaw = read();
+                break;
+            case "--from":
+                from = read().trim();
+                break;
+            case "--to":
+                to = read().trim();
+                break;
+            case "--initial-equity": {
+                const raw = read();
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n <= 0) {
+                    usage("--initial-equity must be a positive number", "invalid_equity");
+                }
+                initialEquity = n;
+                break;
+            }
+            case "--tier": {
+                const raw = read().trim();
+                if (!TIERS.has(raw)) {
+                    usage("--tier must be free|pro|pro_max", "invalid_tier");
+                }
+                tier = raw;
+                break;
+            }
+            case "--data-quality": {
+                const raw = read().trim();
+                if (!DATA_QUALITY.has(raw)) {
+                    usage("--data-quality must be strict|basic", "invalid_data_quality");
+                }
+                dataQualityMode = raw;
+                break;
+            }
+            case "--config-schema-version": {
+                const n = Number(read());
+                if (!Number.isInteger(n) || n <= 0) {
+                    usage("--config-schema-version must be a positive integer", "invalid_config_schema_version");
+                }
+                configSchemaVersion = n;
+                break;
+            }
+            case "--execution-model":
+                executionModelOverride = parseExecutionModelJson(read());
+                break;
+            case "--replay-timeframe": {
+                const raw = read().trim();
+                if (!(0, replay_timeframe_1.isEngineBacktestReplayTimeframe)(raw)) {
+                    usage(`--replay-timeframe must be ${replay_timeframe_1.ENGINE_BACKTEST_REPLAY_TIMEFRAMES.join("|")} (got ${raw})`, "invalid_replay_timeframe");
+                }
+                replayTimeframe = raw;
+                break;
+            }
+            default:
+                usage(`Unknown flag: ${flag}`, "unknown_flag");
+        }
+    }
+    if (help) {
+        return {
+            help: true,
+            createExperiment: false,
+            tier,
+            dataQualityMode,
+            persist,
+            replayTimeframe,
+        };
+    }
+    if (!definitionId) {
+        usage("--definition is required", "missing_definition");
+    }
+    if (!configRaw) {
+        usage("--config is required (@file.json or JSON)", "missing_config");
+    }
+    if (!exchange) {
+        usage("--exchange is required", "missing_exchange");
+    }
+    if (initialEquity === undefined) {
+        usage("--initial-equity is required", "missing_equity");
+    }
+    let range;
+    if (rangeRaw) {
+        if (from || to) {
+            usage("Use either --range or --from/--to, not both", "range_conflict");
+        }
+        range = parseRangeFlag(rangeRaw);
+    }
+    else if (from || to) {
+        if (!from || !to) {
+            usage("--from and --to must be used together", "range_incomplete");
+        }
+        range = parseInclusiveUtcDateRange(from, to);
+    }
+    else {
+        usage("--range or --from/--to is required", "missing_range");
+    }
+    if (!experimentId && !createExperiment) {
+        usage("Provide --experiment <uuid> or --create-experiment --name <name>", "missing_experiment");
+    }
+    if (createExperiment && !name?.trim()) {
+        usage("--create-experiment requires --name", "missing_experiment_name");
+    }
+    if (experimentId && createExperiment) {
+        usage("Use either --experiment or --create-experiment, not both", "experiment_conflict");
+    }
+    return {
+        help: false,
+        experimentId,
+        createExperiment,
+        name: name?.trim(),
+        definitionId,
+        definitionLabelZh,
+        definitionLabelEn,
+        configRaw,
+        exchange,
+        range,
+        initialEquity,
+        tier,
+        dataQualityMode,
+        configSchemaVersion,
+        executionModelOverride,
+        persist,
+        replayTimeframe,
+    };
+}

package/dist/engine-backtest/persist.d.ts

@@ -0,0 +1,32 @@
+import type { ProfileName } from "../config/profiles";
+import type { CreateRunRequestBody, DataQualityMode, EngineBacktestMetrics, EngineBacktestScenario, ExecutionModel } from "./types";
+/** Aligned with `@alphafoxai/backtest-runner` DEFAULT_EXECUTION_MODEL. */
+export declare const DEFAULT_EXECUTION_MODEL: ExecutionModel;
+export declare const SNAPSHOT_SCHEMA_VERSION: 1;
+/**
+ * Web persist uses tape.to as an exclusive end, then subtracts 1ms and
+ * slices to YYYY-MM-DD so an inclusive calendar last-day is recovered.
+ */
+export declare function exclusiveTapeEndToRangeEnd(tapeTo: string): string;
+export declare function uniqueSeriesField(series: readonly {
+    readonly symbol: string;
+    readonly timeframe: string;
+}[], field: "symbol" | "timeframe"): string[];
+/**
+ * Build POST .../runs body from a completed WASM run.
+ * Field set matches web `buildCreateRunRequestFromCompleted`.
+ */
+export declare function buildCreateRunRequest(input: {
+    readonly clientRunId: string;
+    readonly scenario: EngineBacktestScenario;
+    readonly metrics: EngineBacktestMetrics;
+    readonly exchangeId: string;
+    readonly dataQualityMode: DataQualityMode;
+    readonly engineVersion: string;
+}): CreateRunRequestBody;
+/**
+ * Experiment detail URL. Locale prefix (`/zh`, `/en`) is optional — web
+ * `[locale]/dashboard/traders/backtest/[experimentId]` also serves the
+ * unprefixed `/dashboard/traders/backtest/{id}` path.
+ */
+export declare function experimentPageUrl(profile: ProfileName, experimentId: string): string;

package/dist/engine-backtest/persist.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SNAPSHOT_SCHEMA_VERSION = exports.DEFAULT_EXECUTION_MODEL = void 0;
+exports.exclusiveTapeEndToRangeEnd = exclusiveTapeEndToRangeEnd;
+exports.uniqueSeriesField = uniqueSeriesField;
+exports.buildCreateRunRequest = buildCreateRunRequest;
+exports.experimentPageUrl = experimentPageUrl;
+const errors_1 = require("./errors");
+/** Aligned with `@alphafoxai/backtest-runner` DEFAULT_EXECUTION_MODEL. */
+exports.DEFAULT_EXECUTION_MODEL = {
+    pricePath: "ohlc_path_4",
+    makerFeeRate: 0.0002,
+    takerFeeRate: 0.0005,
+    slippageRate: 0.0001,
+};
+exports.SNAPSHOT_SCHEMA_VERSION = 1;
+/**
+ * Web persist uses tape.to as an exclusive end, then subtracts 1ms and
+ * slices to YYYY-MM-DD so an inclusive calendar last-day is recovered.
+ */
+function exclusiveTapeEndToRangeEnd(tapeTo) {
+    const exclusiveEndMs = Date.parse(tapeTo);
+    if (!Number.isFinite(exclusiveEndMs)) {
+        throw new errors_1.EngineBacktestError({
+            type: "usage",
+            subtype: "invalid_tape_end",
+            message: `Cannot derive rangeEnd from tape.to "${tapeTo}"`,
+            status: 400,
+        });
+    }
+    return new Date(exclusiveEndMs - 1).toISOString().slice(0, 10);
+}
+function uniqueSeriesField(series, field) {
+    return [...new Set(series.map((item) => item[field]))];
+}
+/**
+ * Build POST .../runs body from a completed WASM run.
+ * Field set matches web `buildCreateRunRequestFromCompleted`.
+ */
+function buildCreateRunRequest(input) {
+    const { scenario } = input;
+    const rangeStart = scenario.tape.from.slice(0, 10);
+    const rangeEnd = exclusiveTapeEndToRangeEnd(scenario.tape.to);
+    const symbols = uniqueSeriesField(scenario.tape.series, "symbol");
+    if (symbols.length === 0) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "persist_no_symbols",
+            message: "Completed run has no symbols to persist.",
+        });
+    }
+    const timeframes = uniqueSeriesField(scenario.tape.series, "timeframe");
+    const engineVersion = input.engineVersion.trim() || "node-wasm";
+    const snapshot = {
+        snapshotSchemaVersion: exports.SNAPSHOT_SCHEMA_VERSION,
+        strategyDefinitionId: scenario.trader.strategyDefinitionId,
+        configSchemaVersion: scenario.trader.configSchemaVersion,
+        config: scenario.trader.config,
+        exchangeId: input.exchangeId.trim() || "binance",
+        rangeStart,
+        rangeEnd,
+        initialEquity: scenario.exchange.initialEquity,
+        subscriptionTier: scenario.trader.subscriptionTier,
+        dataQualityMode: input.dataQualityMode,
+        symbols,
+        timeframes: timeframes.length > 0 ? timeframes : ["1m"],
+        baseTimeframe: scenario.tape.baseTimeframe || "1m",
+        executionModel: scenario.executionModel ?? exports.DEFAULT_EXECUTION_MODEL,
+        positionSideDual: scenario.exchange.positionSideDual,
+        engineVersion,
+    };
+    return {
+        clientRunId: input.clientRunId,
+        snapshot,
+        metrics: input.metrics,
+        engineVersion,
+        configSchemaVersion: snapshot.configSchemaVersion,
+    };
+}
+/**
+ * Experiment detail URL. Locale prefix (`/zh`, `/en`) is optional — web
+ * `[locale]/dashboard/traders/backtest/[experimentId]` also serves the
+ * unprefixed `/dashboard/traders/backtest/{id}` path.
+ */
+function experimentPageUrl(profile, experimentId) {
+    const path = `/dashboard/traders/backtest/${encodeURIComponent(experimentId)}`;
+    if (profile === "staging") {
+        return `https://staging.alphafox.app${path}`;
+    }
+    if (profile === "local") {
+        return `http://127.0.0.1:3000${path}`;
+    }
+    return `https://alphafox.app${path}`;
+}

package/dist/engine-backtest/replay-timeframe.d.ts

@@ -0,0 +1,16 @@
+import type { EngineBacktestSeriesRequirement } from "./types";
+export declare const ENGINE_BACKTEST_REPLAY_TIMEFRAMES: readonly ["1m", "3m", "5m", "15m", "30m", "1h", "4h"];
+export type EngineBacktestReplayTimeframe = (typeof ENGINE_BACKTEST_REPLAY_TIMEFRAMES)[number];
+export declare const ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME = "1m";
+export declare function isEngineBacktestReplayTimeframe(value: string): value is EngineBacktestReplayTimeframe;
+export declare function parseReplayTimeframe(value: unknown): EngineBacktestReplayTimeframe;
+export declare function mergeReplayTimeframeWithPlan(input: {
+    readonly replayTimeframe: string;
+    readonly planTimeframes: readonly string[];
+    readonly seriesRequirements: readonly EngineBacktestSeriesRequirement[];
+    readonly symbols: readonly string[];
+}): {
+    readonly baseTimeframe: EngineBacktestReplayTimeframe;
+    readonly timeframes: readonly string[];
+    readonly seriesRequirements: readonly EngineBacktestSeriesRequirement[];
+};

package/dist/engine-backtest/replay-timeframe.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME = exports.ENGINE_BACKTEST_REPLAY_TIMEFRAMES = void 0;
+exports.isEngineBacktestReplayTimeframe = isEngineBacktestReplayTimeframe;
+exports.parseReplayTimeframe = parseReplayTimeframe;
+exports.mergeReplayTimeframeWithPlan = mergeReplayTimeframeWithPlan;
+exports.ENGINE_BACKTEST_REPLAY_TIMEFRAMES = [
+    "1m",
+    "3m",
+    "5m",
+    "15m",
+    "30m",
+    "1h",
+    "4h",
+];
+exports.ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME = "1m";
+function isEngineBacktestReplayTimeframe(value) {
+    return exports.ENGINE_BACKTEST_REPLAY_TIMEFRAMES.includes(value);
+}
+function parseReplayTimeframe(value) {
+    return typeof value === "string" && isEngineBacktestReplayTimeframe(value)
+        ? value
+        : exports.ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME;
+}
+function mergeReplayTimeframeWithPlan(input) {
+    const replay = parseReplayTimeframe(input.replayTimeframe);
+    const timeframes = input.planTimeframes.includes(replay)
+        ? [...input.planTimeframes]
+        : [replay, ...input.planTimeframes];
+    const requirements = [...input.seriesRequirements];
+    const seen = new Set(requirements.map((requirement) => `${requirement.symbol}\u0000${requirement.timeframe}`));
+    for (const symbol of input.symbols) {
+        const key = `${symbol}\u0000${replay}`;
+        if (seen.has(key))
+            continue;
+        requirements.push({
+            symbol,
+            timeframe: replay,
+            minWarmupCandles: 0,
+        });
+        seen.add(key);
+    }
+    return {
+        baseTimeframe: replay,
+        timeframes,
+        seriesRequirements: requirements,
+    };
+}