@alphafox/cli 0.2.0 → 0.3.3

package/dist/engine-backtest/resolve-packages.d.ts

@@ -0,0 +1,27 @@
+import { type FetchRuntimeHooks } from "./fetch-runtime";
+import type { BacktestRunnerModule, BacktestWasmModule } from "./types";
+export type PackageKind = "wasm" | "runner";
+export interface ResolvedPackagePath {
+    readonly kind: PackageKind;
+    readonly specifier: string;
+    readonly filePath: string;
+    readonly source: "env_dir" | "engine_root" | "sibling" | "vendor" | "blob";
+}
+export interface ResolvePackageHooks extends FetchRuntimeHooks {
+    readonly requireResolve?: (specifier: string) => string;
+    readonly importModule?: (fileUrl: string) => Promise<unknown>;
+    readonly exists?: (path: string) => boolean;
+    readonly readFile?: (path: string) => string;
+    readonly cliRoot?: string;
+    readonly callerFilename?: string;
+}
+export declare function findCliRoot(startDir: string, hooks?: ResolvePackageHooks): string | undefined;
+export declare function resolveBacktestPackagePath(kind: PackageKind, env?: NodeJS.ProcessEnv, hooks?: ResolvePackageHooks): ResolvedPackagePath;
+export declare function loadBacktestWasm(env?: NodeJS.ProcessEnv, hooks?: ResolvePackageHooks): Promise<{
+    readonly module: BacktestWasmModule;
+    readonly resolved: ResolvedPackagePath;
+}>;
+export declare function loadBacktestRunner(env?: NodeJS.ProcessEnv, hooks?: ResolvePackageHooks): Promise<{
+    readonly module: BacktestRunnerModule;
+    readonly resolved: ResolvedPackagePath;
+}>;

package/dist/engine-backtest/resolve-packages.js

@@ -0,0 +1,288 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCliRoot = findCliRoot;
+exports.resolveBacktestPackagePath = resolveBacktestPackagePath;
+exports.loadBacktestWasm = loadBacktestWasm;
+exports.loadBacktestRunner = loadBacktestRunner;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const errors_1 = require("./errors");
+const fetch_runtime_1 = require("./fetch-runtime");
+const native_import_1 = require("./native-import");
+const WASM_SPEC = "@alphafoxai/backtest-wasm/node";
+const RUNNER_SPEC = "@alphafoxai/backtest-runner";
+const PACKAGE_DESCRIPTORS = {
+    wasm: {
+        specifier: WASM_SPEC,
+        envKey: "ALPHAFOX_BACKTEST_WASM_DIR",
+        npmName: "backtest-wasm",
+        exportKey: "./node",
+        useMainFallback: false,
+        entryCandidates: ["node.mjs", "node.js", "node.cjs"],
+        installHint: "Set ALPHAFOX_BACKTEST_WASM_DIR / ALPHAFOX_ENGINE_ROOT, or ALPHAFOX_USE_LOCAL_BACKTEST=1 with a sibling Engine build. Otherwise the CLI downloads the Node runtime from Vercel Blob.",
+    },
+    runner: {
+        specifier: RUNNER_SPEC,
+        envKey: "ALPHAFOX_BACKTEST_RUNNER_DIR",
+        npmName: "backtest-runner",
+        exportKey: ".",
+        useMainFallback: true,
+        entryCandidates: ["index.mjs", "index.js", "index.cjs"],
+        installHint: "The tape runner is bundled with the CLI. Override with ALPHAFOX_BACKTEST_RUNNER_DIR / ALPHAFOX_ENGINE_ROOT.",
+    },
+};
+function existsPath(path, hooks) {
+    return hooks?.exists ? hooks.exists(path) : (0, node_fs_1.existsSync)(path);
+}
+function readText(path, hooks) {
+    return hooks?.readFile ? hooks.readFile(path) : (0, node_fs_1.readFileSync)(path, "utf8");
+}
+function callerFilename(hooks) {
+    return hooks?.callerFilename ?? __filename;
+}
+function findCliRoot(startDir, hooks) {
+    if (hooks?.cliRoot)
+        return hooks.cliRoot;
+    let dir = startDir;
+    for (let i = 0; i < 10; i += 1) {
+        const pkgPath = (0, node_path_1.join)(dir, "package.json");
+        if (existsPath(pkgPath, hooks)) {
+            try {
+                const pkg = JSON.parse(readText(pkgPath, hooks));
+                if (pkg.name === "@alphafox/cli")
+                    return dir;
+            }
+            catch {
+                // keep walking
+            }
+        }
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+function entryFromPackageDir(dir, kind, hooks) {
+    if (!existsPath(dir, hooks))
+        return undefined;
+    const descriptor = PACKAGE_DESCRIPTORS[kind];
+    const pkgPath = (0, node_path_1.join)(dir, "package.json");
+    if (existsPath(pkgPath, hooks)) {
+        try {
+            const req = (0, node_module_1.createRequire)(pkgPath);
+            return req.resolve(descriptor.specifier);
+        }
+        catch {
+            // fall through to known filenames
+        }
+        try {
+            const pkg = JSON.parse(readText(pkgPath, hooks));
+            const exp = pkg.exports?.[descriptor.exportKey];
+            const mainFallback = descriptor.useMainFallback ? pkg.main : undefined;
+            const file = typeof exp === "string"
+                ? exp
+                : exp && typeof exp === "object"
+                    ? String(exp.default ??
+                        exp.import ??
+                        mainFallback ??
+                        "")
+                    : (mainFallback ?? "");
+            if (file) {
+                const abs = (0, node_path_1.join)(dir, file);
+                if (existsPath(abs, hooks))
+                    return abs;
+            }
+        }
+        catch {
+            // ignore malformed package.json
+        }
+    }
+    for (const name of descriptor.entryCandidates) {
+        const abs = (0, node_path_1.join)(dir, name);
+        if (existsPath(abs, hooks))
+            return abs;
+    }
+    return undefined;
+}
+function toAbsDir(raw) {
+    return (0, node_path_1.isAbsolute)(raw) ? raw : (0, node_path_1.join)(process.cwd(), raw);
+}
+function shouldUseLocalOverride(env) {
+    return env.ALPHAFOX_USE_LOCAL_BACKTEST === "1";
+}
+function hasExplicitLocalDir(kind, env) {
+    return Boolean(env[PACKAGE_DESCRIPTORS[kind].envKey]?.trim() ||
+        env.ALPHAFOX_ENGINE_ROOT?.trim() ||
+        shouldUseLocalOverride(env));
+}
+function resolveBacktestPackagePath(kind, env = process.env, hooks) {
+    const descriptor = PACKAGE_DESCRIPTORS[kind];
+    const { specifier, envKey, npmName } = descriptor;
+    const tried = [];
+    const envDir = env[envKey]?.trim();
+    if (envDir) {
+        const abs = toAbsDir(envDir);
+        const entry = entryFromPackageDir(abs, kind, hooks);
+        if (entry) {
+            return { kind, specifier, filePath: entry, source: "env_dir" };
+        }
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_unresolved",
+            message: `Cannot resolve ${specifier} from ${envKey}=${abs}`,
+            hint: `Point ${envKey} at the npm/${npmName} package directory (must contain ${descriptor.entryCandidates[0]}).`,
+            details: { specifier, envKey, dir: abs, tried },
+        });
+    }
+    tried.push(`${envKey}:(unset)`);
+    const engineRoot = env.ALPHAFOX_ENGINE_ROOT?.trim();
+    if (engineRoot) {
+        const dir = (0, node_path_1.join)(toAbsDir(engineRoot), "npm", npmName);
+        const entry = entryFromPackageDir(dir, kind, hooks);
+        if (entry) {
+            return { kind, specifier, filePath: entry, source: "engine_root" };
+        }
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_unresolved",
+            message: `Cannot resolve ${specifier} from ALPHAFOX_ENGINE_ROOT=${engineRoot}`,
+            hint: `Expected ${dir} to contain the ${npmName} package.`,
+            details: { specifier, dir, tried },
+        });
+    }
+    tried.push("ALPHAFOX_ENGINE_ROOT:(unset)");
+    if (shouldUseLocalOverride(env)) {
+        const cliRoot = findCliRoot((0, node_path_1.dirname)(callerFilename(hooks)), hooks);
+        if (cliRoot) {
+            const dir = (0, node_path_1.join)(cliRoot, "..", "alphafox-engine", "npm", npmName);
+            const entry = entryFromPackageDir(dir, kind, hooks);
+            if (entry) {
+                return { kind, specifier, filePath: entry, source: "sibling" };
+            }
+            tried.push(`sibling:${dir}`);
+        }
+        else {
+            tried.push("sibling:(cli root not found)");
+        }
+    }
+    else {
+        tried.push("sibling:(requires ALPHAFOX_USE_LOCAL_BACKTEST=1)");
+    }
+    throw new errors_1.EngineBacktestError({
+        type: "runtime",
+        subtype: "package_unresolved",
+        message: `Cannot resolve ${specifier}`,
+        hint: descriptor.installHint,
+        details: { specifier, tried },
+    });
+}
+function resolveVendoredRunner(hooks) {
+    const cliRoot = findCliRoot((0, node_path_1.dirname)(callerFilename(hooks)), hooks);
+    if (!cliRoot) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_unresolved",
+            message: `Cannot resolve ${RUNNER_SPEC} from the vendored runner`,
+            hint: PACKAGE_DESCRIPTORS.runner.installHint,
+        });
+    }
+    const dir = (0, node_path_1.join)(cliRoot, "vendor", "backtest-runner");
+    const entry = entryFromPackageDir(dir, "runner", hooks);
+    if (!entry) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_unresolved",
+            message: `Cannot resolve ${RUNNER_SPEC} from ${dir}`,
+            hint: PACKAGE_DESCRIPTORS.runner.installHint,
+            details: { specifier: RUNNER_SPEC, dir },
+        });
+    }
+    return {
+        kind: "runner",
+        specifier: RUNNER_SPEC,
+        filePath: entry,
+        source: "vendor",
+    };
+}
+async function importFile(filePath, hooks) {
+    const url = (0, node_url_1.pathToFileURL)(filePath).href;
+    if (hooks?.importModule) {
+        return hooks.importModule(url);
+    }
+    return (0, native_import_1.importNativeModule)(url);
+}
+function assertWasmModule(mod, filePath) {
+    if (!mod ||
+        typeof mod !== "object" ||
+        typeof mod.createNodeBacktestClient !== "function") {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_invalid",
+            message: `${WASM_SPEC} does not export createNodeBacktestClient`,
+            details: { filePath },
+        });
+    }
+    return mod;
+}
+function assertRunnerModule(mod, filePath) {
+    if (!mod || typeof mod !== "object") {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_invalid",
+            message: `${RUNNER_SPEC} is not a module`,
+            details: { filePath },
+        });
+    }
+    const m = mod;
+    for (const name of [
+        "loadTape",
+        "assembleScenario",
+        "resolveTapeExchange",
+    ]) {
+        if (typeof m[name] !== "function") {
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: "package_invalid",
+                message: `${RUNNER_SPEC} does not export ${name}`,
+                details: { filePath },
+            });
+        }
+    }
+    if (!m.DEFAULT_EXECUTION_MODEL) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "package_invalid",
+            message: `${RUNNER_SPEC} does not export DEFAULT_EXECUTION_MODEL`,
+            details: { filePath },
+        });
+    }
+    return m;
+}
+async function loadBacktestWasm(env = process.env, hooks) {
+    if (hasExplicitLocalDir("wasm", env)) {
+        const resolved = resolveBacktestPackagePath("wasm", env, hooks);
+        const mod = assertWasmModule(await importFile(resolved.filePath, hooks), resolved.filePath);
+        return { module: mod, resolved };
+    }
+    const runtime = await (0, fetch_runtime_1.ensureBlobRuntime)(env, hooks);
+    const mod = assertWasmModule(await importFile(runtime.nodeEntry, hooks), runtime.nodeEntry);
+    return {
+        module: mod,
+        resolved: {
+            kind: "wasm",
+            specifier: WASM_SPEC,
+            filePath: runtime.nodeEntry,
+            source: "blob",
+        },
+    };
+}
+async function loadBacktestRunner(env = process.env, hooks) {
+    const resolved = hasExplicitLocalDir("runner", env)
+        ? resolveBacktestPackagePath("runner", env, hooks)
+        : resolveVendoredRunner(hooks);
+    const mod = assertRunnerModule(await importFile(resolved.filePath, hooks), resolved.filePath);
+    return { module: mod, resolved };
+}

package/dist/engine-backtest/run-command.d.ts

@@ -0,0 +1,38 @@
+import type { ApiRequestOptions, ApiResponse } from "../http/client";
+import { loadTokens } from "../keychain/store";
+import { type ResolvePackageHooks } from "./resolve-packages";
+import type { BacktestRunnerModule, BacktestWasmModule, EngineBacktestRunArgs, EngineBacktestRunSuccess } from "./types";
+export interface EngineBacktestCliFlags {
+    readonly profile?: string;
+    readonly format: "json" | "jsonl" | "text";
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+    readonly noInput: boolean;
+    readonly unsafeCustomEndpoint?: string;
+    readonly jq?: string;
+}
+export interface EngineBacktestRunDeps {
+    readonly loadTape?: BacktestRunnerModule["loadTape"];
+    readonly assembleScenario?: BacktestRunnerModule["assembleScenario"];
+    readonly resolveTapeExchange?: BacktestRunnerModule["resolveTapeExchange"];
+    readonly defaultExecutionModel?: BacktestRunnerModule["DEFAULT_EXECUTION_MODEL"];
+    readonly createNodeBacktestClient?: BacktestWasmModule["createNodeBacktestClient"];
+    readonly apiRequest?: (options: ApiRequestOptions, env?: NodeJS.ProcessEnv) => Promise<ApiResponse>;
+    readonly loadTokens?: typeof loadTokens;
+    readonly readFile?: (path: string) => string;
+    readonly cwd?: string;
+    readonly randomUUID?: () => string;
+    readonly writeLine?: (value: unknown) => void;
+    readonly resolveHooks?: ResolvePackageHooks;
+}
+export declare function loadConfigValue(raw: string, options?: {
+    readonly cwd?: string;
+    readonly readFile?: (path: string) => string;
+}): unknown;
+export declare function executeEngineBacktestRun(args: EngineBacktestRunArgs, flags: EngineBacktestCliFlags, env?: NodeJS.ProcessEnv, deps?: EngineBacktestRunDeps): Promise<EngineBacktestRunSuccess>;
+export declare function engineBacktestHelpData(): {
+    readonly name: string;
+    readonly usage: string[];
+    readonly notes: string[];
+};
+export declare function cmdEngineBacktest(args: string[], flags: EngineBacktestCliFlags, env?: NodeJS.ProcessEnv, deps?: EngineBacktestRunDeps): Promise<number>;