@alphafox/cli 0.2.0 → 0.3.3

package/dist/engine-backtest/run-command.js

@@ -0,0 +1,540 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfigValue = loadConfigValue;
+exports.executeEngineBacktestRun = executeEngineBacktestRun;
+exports.engineBacktestHelpData = engineBacktestHelpData;
+exports.cmdEngineBacktest = cmdEngineBacktest;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const profiles_1 = require("../config/profiles");
+const envelope_1 = require("../envelope");
+const client_1 = require("../http/client");
+const store_1 = require("../keychain/store");
+const errors_1 = require("./errors");
+const parse_args_1 = require("./parse-args");
+const persist_1 = require("./persist");
+const replay_timeframe_1 = require("./replay-timeframe");
+const resolve_packages_1 = require("./resolve-packages");
+const CREATE_EXPERIMENT_PATH = "/api/v1/engine-backtest/experiments";
+const SUBSCRIPTION_PATH = "/api/v1/subscriptions/me";
+const SUBSCRIPTION_TIERS = new Set([
+    "free",
+    "pro",
+    "pro_max",
+]);
+function runsPath(experimentId) {
+    return `/api/v1/engine-backtest/experiments/${encodeURIComponent(experimentId)}/runs`;
+}
+function loadConfigValue(raw, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const read = options.readFile ?? ((p) => (0, node_fs_1.readFileSync)(p, "utf8"));
+    if (raw.startsWith("@")) {
+        const rel = raw.slice(1);
+        if (!rel) {
+            throw new errors_1.EngineBacktestError({
+                type: "usage",
+                subtype: "missing_config",
+                message: "--config @path is empty",
+                status: 400,
+            });
+        }
+        const abs = (0, node_path_1.isAbsolute)(rel) ? rel : (0, node_path_1.resolve)(cwd, rel);
+        try {
+            return JSON.parse(read(abs));
+        }
+        catch (err) {
+            throw new errors_1.EngineBacktestError({
+                type: "usage",
+                subtype: "invalid_config",
+                message: `Cannot read --config file ${abs}: ${err instanceof Error ? err.message : String(err)}`,
+                status: 400,
+            });
+        }
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new errors_1.EngineBacktestError({
+            type: "usage",
+            subtype: "invalid_config",
+            message: "--config must be JSON or @path-to.json",
+            status: 400,
+        });
+    }
+}
+function extractErrorMessage(json, fallback) {
+    if (json && typeof json === "object") {
+        const o = json;
+        if (typeof o.message === "string")
+            return o.message;
+        if (typeof o.detail === "string")
+            return o.detail;
+        if (typeof o.error === "string")
+            return o.error;
+        if (o.error && typeof o.error === "object") {
+            const e = o.error;
+            if (typeof e.message === "string")
+                return e.message;
+        }
+    }
+    return fallback || "Request failed";
+}
+function extractErrorCode(json) {
+    if (json && typeof json === "object") {
+        const o = json;
+        if (typeof o.code === "string" || typeof o.code === "number")
+            return o.code;
+    }
+    return undefined;
+}
+function extractEntityId(json) {
+    if (!json || typeof json !== "object")
+        return undefined;
+    const o = json;
+    if (typeof o.id === "string" && o.id.trim())
+        return o.id.trim();
+    if (o.data && typeof o.data === "object") {
+        const d = o.data;
+        if (typeof d.id === "string" && d.id.trim())
+            return d.id.trim();
+    }
+    return undefined;
+}
+function isSupportedPlan(plan) {
+    return (!!plan &&
+        typeof plan === "object" &&
+        !("status" in plan && plan.status === "failed") &&
+        "support" in plan &&
+        plan.support?.status === "supported");
+}
+function definitionDisplay(args) {
+    const fallback = args.definitionId ?? "strategy";
+    return {
+        zh: args.definitionLabelZh?.trim() || fallback,
+        en: args.definitionLabelEn?.trim() || fallback,
+    };
+}
+function requireAuth(profile, env, loadTokensFn) {
+    const tokens = loadTokensFn(profile.name, env);
+    if (tokens?.accessToken?.trim())
+        return;
+    throw new errors_1.EngineBacktestError({
+        type: "http",
+        status: 401,
+        message: "Not authenticated. Run alphafox auth login.",
+        hint: "Tokens live in the OS keychain. Do not pass --token.",
+        subtype: "unauthenticated",
+    });
+}
+async function postJson(api, profile, env, path, body, mintId) {
+    const res = await api({
+        method: "POST",
+        path,
+        body,
+        profile,
+        idempotencyKey: mintId(),
+    }, env);
+    if (res.status >= 400) {
+        throw new errors_1.EngineBacktestError({
+            type: "http",
+            status: res.status,
+            message: extractErrorMessage(res.json, res.bodyText),
+            code: extractErrorCode(res.json),
+            details: res.json,
+        });
+    }
+    return res;
+}
+function extractSubscriptionTier(json) {
+    if (!json || typeof json !== "object")
+        return undefined;
+    const root = json;
+    const nested = root.data && typeof root.data === "object"
+        ? root.data
+        : undefined;
+    const value = root.subscriptionTier ?? nested?.subscriptionTier;
+    return typeof value === "string" &&
+        SUBSCRIPTION_TIERS.has(value)
+        ? value
+        : undefined;
+}
+async function loadAccountSubscriptionTier(api, profile, env) {
+    const res = await api({
+        method: "GET",
+        path: SUBSCRIPTION_PATH,
+        profile,
+    }, env);
+    if (res.status >= 400) {
+        throw new errors_1.EngineBacktestError({
+            type: "http",
+            status: res.status,
+            message: extractErrorMessage(res.json, res.bodyText),
+            code: extractErrorCode(res.json),
+            details: res.json,
+        });
+    }
+    const tier = extractSubscriptionTier(res.json);
+    if (!tier) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "subscription_tier_unresolved",
+            message: "subscriptions.me response did not include a valid subscriptionTier",
+            details: res.json,
+        });
+    }
+    return tier;
+}
+function emitProgress(flags, writeLine, stage, fraction, detail) {
+    if (flags.format !== "jsonl")
+        return;
+    writeLine({
+        event: "progress",
+        stage,
+        fraction,
+        ...(detail ? { detail } : {}),
+    });
+}
+async function executeEngineBacktestRun(args, flags, env = process.env, deps = {}) {
+    if (args.help) {
+        throw new errors_1.EngineBacktestError({
+            type: "usage",
+            message: "internal: help should be handled by the command wrapper",
+        });
+    }
+    if (!args.definitionId || !args.configRaw || !args.exchange || !args.range) {
+        throw new errors_1.EngineBacktestError({
+            type: "usage",
+            subtype: "invalid_args",
+            message: "Missing required run arguments",
+            status: 400,
+        });
+    }
+    const profile = (0, profiles_1.resolveProfile)(flags.profile, env, {
+        unsafeCustomEndpoint: flags.unsafeCustomEndpoint,
+    });
+    const api = deps.apiRequest ?? client_1.apiRequest;
+    const tokensFn = deps.loadTokens ?? store_1.loadTokens;
+    const mintId = deps.randomUUID ?? node_crypto_1.randomUUID;
+    const writeLine = deps.writeLine ??
+        ((value) => {
+            process.stdout.write(`${JSON.stringify(value)}\n`);
+        });
+    const persist = args.persist && !flags.dryRun;
+    const createExperiment = args.createExperiment && !flags.dryRun;
+    const needsApi = persist || createExperiment;
+    if (needsApi) {
+        requireAuth(profile, env, tokensFn);
+    }
+    const config = loadConfigValue(args.configRaw, {
+        cwd: deps.cwd,
+        readFile: deps.readFile,
+    });
+    let experimentId = args.experimentId;
+    if (!experimentId && !createExperiment) {
+        throw new errors_1.EngineBacktestError({
+            type: "usage",
+            subtype: "missing_experiment",
+            message: "Provide --experiment <uuid> or --create-experiment --name <name>",
+            status: 400,
+        });
+    }
+    let wasm;
+    let runner;
+    if (deps.createNodeBacktestClient &&
+        deps.loadTape &&
+        deps.assembleScenario &&
+        deps.resolveTapeExchange) {
+        wasm = { createNodeBacktestClient: deps.createNodeBacktestClient };
+        runner = {
+            loadTape: deps.loadTape,
+            assembleScenario: deps.assembleScenario,
+            resolveTapeExchange: deps.resolveTapeExchange,
+            DEFAULT_EXECUTION_MODEL: deps.defaultExecutionModel ?? persist_1.DEFAULT_EXECUTION_MODEL,
+        };
+    }
+    else {
+        const [wasmLoaded, runnerLoaded] = await Promise.all([
+            (0, resolve_packages_1.loadBacktestWasm)(env, deps.resolveHooks),
+            (0, resolve_packages_1.loadBacktestRunner)(env, deps.resolveHooks),
+        ]);
+        wasm = wasmLoaded.module;
+        runner = runnerLoaded.module;
+    }
+    const client = wasm.createNodeBacktestClient();
+    try {
+        if (typeof client.init === "function") {
+            await client.init();
+        }
+        let configSchemaVersion = args.configSchemaVersion;
+        if (configSchemaVersion === undefined) {
+            const listed = await client.strategyDefinitions();
+            const found = listed.definitions.find((d) => d.id === args.definitionId);
+            const version = found?.configSchemaVersion;
+            if (typeof version !== "number" || !Number.isInteger(version) || version <= 0) {
+                throw new errors_1.EngineBacktestError({
+                    type: "runtime",
+                    subtype: "config_schema_version_unresolved",
+                    message: `strategyDefinitions() has no configSchemaVersion for "${args.definitionId}"`,
+                    hint: "Pass --config-schema-version explicitly.",
+                    details: { definitionId: args.definitionId },
+                });
+            }
+            configSchemaVersion = version;
+        }
+        const plan = await client.planBacktest({
+            definitionId: args.definitionId,
+            configSchemaVersion,
+            config,
+        });
+        if (!isSupportedPlan(plan)) {
+            const reason = plan && typeof plan === "object" && "support" in plan
+                ? plan
+                    .support?.reason
+                : undefined;
+            const errors = plan && typeof plan === "object" && "errors" in plan
+                ? plan.errors
+                : undefined;
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: "plan_unsupported",
+                message: reason?.message ??
+                    `planBacktest does not support definition "${args.definitionId}"`,
+                code: reason?.code,
+                details: { reason, errors, plan },
+            });
+        }
+        let subscriptionTier = args.tier ?? "pro";
+        if (persist) {
+            const accountTier = await loadAccountSubscriptionTier(api, profile, env);
+            if (args.tier !== undefined && args.tier !== accountTier) {
+                throw new errors_1.EngineBacktestError({
+                    type: "usage",
+                    subtype: "subscription_tier_mismatch",
+                    message: `--tier ${args.tier} does not match account subscription tier ${accountTier}`,
+                    hint: "Remove --tier for persisted runs, or use --no-persist to simulate another tier.",
+                    status: 400,
+                    details: { requestedTier: args.tier, accountTier },
+                });
+            }
+            subscriptionTier = accountTier;
+        }
+        let exchange;
+        try {
+            exchange = runner.resolveTapeExchange(args.exchange);
+        }
+        catch (err) {
+            throw new errors_1.EngineBacktestError({
+                type: "usage",
+                subtype: "invalid_exchange",
+                message: err instanceof Error ? err.message : String(err),
+                status: 400,
+            });
+        }
+        const replayPlan = (0, replay_timeframe_1.mergeReplayTimeframeWithPlan)({
+            replayTimeframe: args.replayTimeframe,
+            planTimeframes: plan.timeframes,
+            seriesRequirements: plan.seriesRequirements,
+            symbols: plan.symbols,
+        });
+        let tapeResult;
+        try {
+            tapeResult = await runner.loadTape({
+                exchangeId: exchange.id,
+                exchange,
+                symbols: plan.symbols,
+                baseTimeframe: replayPlan.baseTimeframe,
+                timeframes: replayPlan.timeframes,
+                seriesRequirements: replayPlan.seriesRequirements,
+                needsFunding: plan.needsFunding,
+                auxiliaryDataRequirements: plan.auxiliaryDataRequirements,
+                fromMs: args.range.fromMs,
+                toMs: args.range.toMs,
+                dataQualityMode: args.dataQualityMode,
+                onProgress: (progress) => {
+                    emitProgress(flags, writeLine, progress.stage || "tape", progress.fraction, progress.detail);
+                },
+            });
+        }
+        catch (err) {
+            if ((0, errors_1.isEngineBacktestError)(err))
+                throw err;
+            const issues = err && typeof err === "object" && "issues" in err
+                ? err.issues
+                : undefined;
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: issues ? "tape_unavailable" : "tape_load_failed",
+                message: err instanceof Error ? err.message : String(err),
+                details: issues ? { issues } : undefined,
+            });
+        }
+        const runId = mintId();
+        const executionModel = {
+            ...(runner.DEFAULT_EXECUTION_MODEL ?? persist_1.DEFAULT_EXECUTION_MODEL),
+            ...args.executionModelOverride,
+        };
+        const scenario = runner.assembleScenario({
+            runId,
+            definitionId: args.definitionId,
+            configSchemaVersion,
+            config: plan.effectiveConfig ?? config,
+            subscriptionTier,
+            initialEquity: args.initialEquity,
+            tape: tapeResult.tape,
+            executionModel,
+        });
+        const result = await client.runBacktest(scenario, tapeResult.buffers, (fraction) => {
+            emitProgress(flags, writeLine, "wasm", fraction);
+        });
+        if (result.status === "failed") {
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: "backtest_failed",
+                message: "runBacktest returned status=failed",
+                details: { errors: result.errors, runId: result.runId },
+            });
+        }
+        const engineVersion = result.engineVersion?.trim() ||
+            (typeof client.version === "function" ? (await client.version()).trim() : "") ||
+            "node-wasm";
+        if (createExperiment) {
+            const body = {
+                name: args.name,
+                strategyDefinitionId: args.definitionId,
+                strategyDefinitionDisplay: definitionDisplay(args),
+            };
+            const res = await postJson(api, profile, env, CREATE_EXPERIMENT_PATH, body, mintId);
+            experimentId = extractEntityId(res.json);
+            if (!experimentId) {
+                throw new errors_1.EngineBacktestError({
+                    type: "runtime",
+                    subtype: "create_experiment_no_id",
+                    message: "experiments.create response did not include an id",
+                    details: res.json,
+                });
+            }
+        }
+        if (!experimentId) {
+            throw new errors_1.EngineBacktestError({
+                type: "usage",
+                subtype: "missing_experiment",
+                message: "Provide --experiment <uuid> or --create-experiment --name <name>",
+                status: 400,
+            });
+        }
+        let persistedRunId;
+        if (persist) {
+            const body = (0, persist_1.buildCreateRunRequest)({
+                clientRunId: mintId(),
+                scenario,
+                metrics: result.metrics,
+                exchangeId: exchange.id,
+                dataQualityMode: args.dataQualityMode,
+                engineVersion,
+            });
+            const res = await postJson(api, profile, env, runsPath(experimentId), body, mintId);
+            persistedRunId = extractEntityId(res.json);
+            if (!persistedRunId) {
+                throw new errors_1.EngineBacktestError({
+                    type: "runtime",
+                    subtype: "create_run_no_id",
+                    message: "runs.create response did not include an id",
+                    details: res.json,
+                });
+            }
+        }
+        return {
+            metrics: result.metrics,
+            engineVersion,
+            experimentId,
+            runId: persistedRunId,
+            experimentUrl: (0, persist_1.experimentPageUrl)(profile.name, experimentId),
+            persisted: Boolean(persistedRunId),
+            coverageWarnings: tapeResult.coverageWarnings ?? [],
+        };
+    }
+    finally {
+        client.terminate();
+    }
+}
+function engineBacktestHelpData() {
+    return {
+        name: "engine-backtest",
+        usage: [
+            ...parse_args_1.ENGINE_BACKTEST_RUN_USAGE,
+            "Catalog CRUD (underscore domain): alphafox engine_backtest experiments list|create|...",
+        ],
+        notes: [
+            "Local WASM run is hyphenated engine-backtest so it does not steal typed catalog engine_backtest.*",
+            "runs.create is write (not high-risk-write); --yes is not required",
+            "Do not pass --token; use alphafox auth login",
+            "--replay-timeframe defaults to 1m (min 1m). Indicator series still download their native plan timeframes.",
+        ],
+    };
+}
+async function cmdEngineBacktest(args, flags, env = process.env, deps = {}) {
+    const [sub, ...rest] = args;
+    if (!sub ||
+        sub === "help" ||
+        sub === "--help" ||
+        sub === "-h") {
+        (0, envelope_1.writeSuccess)(engineBacktestHelpData(), {
+            format: flags.format,
+            jq: flags.jq,
+        });
+        return 0;
+    }
+    if (sub !== "run") {
+        (0, envelope_1.writeError)({
+            type: "usage",
+            subtype: "unknown_subcommand",
+            message: `Unknown engine-backtest subcommand "${sub}"`,
+            hint: "Local WASM: alphafox engine-backtest run. Catalog CRUD: alphafox engine_backtest experiments list",
+        });
+    }
+    let parsed;
+    try {
+        parsed = (0, parse_args_1.parseEngineBacktestRunArgs)(rest);
+    }
+    catch (err) {
+        if ((0, errors_1.isEngineBacktestError)(err)) {
+            (0, envelope_1.writeError)({
+                type: err.type,
+                subtype: err.subtype,
+                message: err.message,
+                hint: err.hint,
+                status: err.status,
+                details: err.details,
+            }, { exitCode: err.status === 401 || err.status === 403 ? 77 : undefined });
+        }
+        throw err;
+    }
+    if (parsed.help) {
+        (0, envelope_1.writeSuccess)(engineBacktestHelpData(), {
+            format: flags.format,
+            jq: flags.jq,
+        });
+        return 0;
+    }
+    try {
+        const result = await executeEngineBacktestRun(parsed, flags, env, deps);
+        (0, envelope_1.writeSuccess)(result, { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    catch (err) {
+        if ((0, errors_1.isEngineBacktestError)(err)) {
+            (0, envelope_1.writeError)({
+                type: err.type,
+                subtype: err.subtype,
+                message: err.message,
+                hint: err.hint,
+                status: err.status,
+                code: err.code,
+                details: err.details,
+            }, { exitCode: err.status === 401 || err.status === 403 ? 77 : undefined });
+        }
+        throw err;
+    }
+}