@alphafox/cli 0.2.0 → 0.3.2

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

@@ -0,0 +1,249 @@
+export type SubscriptionTier = "free" | "pro" | "pro_max";
+export type DataQualityMode = "strict" | "basic";
+export type PricePath = "ohlc_path_4" | "close_only";
+export interface ExecutionModel {
+    readonly pricePath: PricePath;
+    readonly makerFeeRate: number;
+    readonly takerFeeRate: number;
+    readonly slippageRate: number;
+}
+export interface InclusiveUtcDateRange {
+    readonly rangeStart: string;
+    readonly rangeEnd: string;
+    readonly fromMs: number;
+    readonly toMs: number;
+}
+export interface EngineBacktestRunArgs {
+    readonly help: boolean;
+    readonly experimentId?: string;
+    readonly createExperiment: boolean;
+    readonly name?: string;
+    readonly definitionId?: string;
+    readonly definitionLabelZh?: string;
+    readonly definitionLabelEn?: string;
+    readonly configRaw?: string;
+    readonly exchange?: string;
+    readonly range?: InclusiveUtcDateRange;
+    readonly initialEquity?: number;
+    /** Explicit --tier value. Persisted runs otherwise use the account tier. */
+    readonly tier?: SubscriptionTier;
+    readonly dataQualityMode: DataQualityMode;
+    readonly configSchemaVersion?: number;
+    readonly executionModelOverride?: Partial<ExecutionModel>;
+    readonly persist: boolean;
+    /** Replay/download bar. Defaults to 1m; never finer. */
+    readonly replayTimeframe: string;
+}
+export interface EngineBacktestSeriesRequirement {
+    readonly symbol: string;
+    readonly timeframe: string;
+    readonly minWarmupCandles: number;
+}
+export interface EngineBacktestTapeSeriesRef {
+    readonly symbol: string;
+    readonly timeframe: string;
+    readonly buffer: string;
+    readonly rows: number;
+}
+export interface EngineBacktestTapeInput {
+    readonly from: string;
+    readonly to: string;
+    readonly baseTimeframe: string;
+    readonly markets: Readonly<Record<string, unknown>>;
+    readonly series: readonly EngineBacktestTapeSeriesRef[];
+    readonly fundingRates?: Readonly<Record<string, readonly unknown[]>>;
+    readonly lowLiquiditySymbols?: readonly string[];
+}
+export interface EngineBacktestScenario {
+    readonly version: 1;
+    readonly runId: string;
+    readonly trader: {
+        readonly id?: string;
+        readonly name?: string;
+        readonly strategyDefinitionId: string;
+        readonly configSchemaVersion: number;
+        readonly subscriptionTier: SubscriptionTier;
+        readonly config: unknown;
+    };
+    readonly exchange: {
+        readonly positionSideDual: boolean;
+        readonly initialEquity: number;
+    };
+    readonly executionModel: ExecutionModel;
+    readonly tape: EngineBacktestTapeInput;
+}
+export interface EngineBacktestMetrics {
+    readonly initialEquity: number;
+    readonly finalEquity: number;
+    readonly netPnl: number;
+    readonly returnPct: number;
+    readonly maxDrawdownPct: number;
+    readonly sharpeRatio: number;
+    readonly orderCount: number;
+    readonly filledOrderCount: number;
+    readonly canceledOrderCount: number;
+    readonly tradeCount: number;
+    readonly winningTrades: number;
+    readonly losingTrades: number;
+    readonly winRatePct: number;
+    readonly feesPaid: number;
+    readonly slippagePaid: number;
+    readonly liquidated: boolean;
+}
+export interface EngineBacktestResult {
+    readonly runId: string;
+    readonly status: "completed" | "failed";
+    readonly engineVersion?: string;
+    readonly metrics: EngineBacktestMetrics;
+    readonly equityCurve?: unknown[];
+    readonly orders?: unknown[];
+    readonly openPositions?: unknown[];
+    readonly errors?: Array<{
+        code: string;
+        message: string;
+        path?: string;
+    }>;
+    readonly warnings?: string[];
+}
+export interface EngineBacktestSupportReason {
+    readonly code: string;
+    readonly message: string;
+}
+export interface EngineSupportedBacktestPlan {
+    readonly definitionId: string;
+    readonly configSchemaVersion: number;
+    readonly support: {
+        readonly status: "supported";
+    };
+    readonly effectiveConfig: Record<string, unknown>;
+    readonly universe: {
+        readonly kind: "fixed";
+        readonly symbols: string[];
+    };
+    readonly symbols: string[];
+    readonly timeframes: string[];
+    readonly seriesRequirements: EngineBacktestSeriesRequirement[];
+    readonly needsFunding: boolean;
+    readonly auxiliaryDataRequirements: Array<{
+        readonly kind: string;
+        readonly parameters?: Record<string, unknown>;
+    }>;
+    readonly configFingerprint: string;
+}
+export interface EngineUnsupportedBacktestPlan {
+    readonly definitionId: string;
+    readonly configSchemaVersion: number;
+    readonly support: {
+        readonly status: "unsupported";
+        readonly reason: EngineBacktestSupportReason;
+    };
+    readonly needsFunding: false;
+}
+export interface EngineBacktestFailure {
+    readonly status: "failed";
+    readonly errors: Array<{
+        readonly code: string;
+        readonly message: string;
+    }>;
+}
+export type EngineBacktestPlan = EngineSupportedBacktestPlan | EngineUnsupportedBacktestPlan;
+export interface TapeLoadProgress {
+    readonly stage: "markets" | "ohlcv" | "validation" | string;
+    readonly detail: string;
+    readonly fraction: number;
+}
+export interface TapeExchangeDefinition {
+    readonly id: string;
+    readonly label: string;
+    readonly ccxtId: string;
+    readonly marketType: string;
+    readonly quoteAsset: string;
+}
+export interface TapeLoadResult {
+    readonly tape: EngineBacktestTapeInput;
+    readonly buffers: Record<string, ArrayBuffer>;
+    readonly coverageWarnings: readonly string[];
+}
+export interface BacktestClientLike {
+    init(): Promise<string>;
+    version(): Promise<string>;
+    strategyDefinitions(): Promise<{
+        readonly engineVersion: string;
+        readonly definitions: Array<Record<string, unknown> & {
+            readonly id: string;
+            readonly configSchemaVersion?: number;
+        }>;
+    }>;
+    planBacktest(request: {
+        readonly definitionId: string;
+        readonly configSchemaVersion: number;
+        readonly config: unknown;
+    }): Promise<EngineBacktestPlan | EngineBacktestFailure>;
+    runBacktest(scenario: EngineBacktestScenario, buffers: Record<string, ArrayBuffer>, onProgress?: (fraction: number) => void): Promise<EngineBacktestResult>;
+    terminate(): void;
+}
+export interface BacktestWasmModule {
+    createNodeBacktestClient(options?: unknown): BacktestClientLike;
+}
+export interface BacktestRunnerModule {
+    loadTape(request: {
+        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 unknown[];
+        readonly fromMs: number;
+        readonly toMs: number;
+        readonly dataQualityMode?: DataQualityMode;
+        readonly onProgress?: (progress: TapeLoadProgress) => void;
+    }, options?: unknown): Promise<TapeLoadResult>;
+    assembleScenario(input: {
+        readonly runId: string;
+        readonly definitionId: string;
+        readonly configSchemaVersion: number;
+        readonly config: unknown;
+        readonly subscriptionTier: SubscriptionTier;
+        readonly initialEquity: number;
+        readonly tape?: EngineBacktestTapeInput;
+        readonly executionModel?: Partial<ExecutionModel>;
+    }): EngineBacktestScenario;
+    resolveTapeExchange(exchangeId: string | TapeExchangeDefinition): TapeExchangeDefinition;
+    DEFAULT_EXECUTION_MODEL: ExecutionModel;
+}
+export interface PersistedSnapshot {
+    readonly snapshotSchemaVersion: 1;
+    readonly strategyDefinitionId: string;
+    readonly configSchemaVersion: number;
+    readonly config: unknown;
+    readonly exchangeId: string;
+    readonly rangeStart: string;
+    readonly rangeEnd: string;
+    readonly initialEquity: number;
+    readonly subscriptionTier: SubscriptionTier;
+    readonly dataQualityMode: DataQualityMode;
+    readonly symbols: string[];
+    readonly timeframes: string[];
+    readonly baseTimeframe: string;
+    readonly executionModel: ExecutionModel;
+    readonly positionSideDual: boolean;
+    readonly engineVersion: string;
+}
+export interface CreateRunRequestBody {
+    readonly clientRunId: string;
+    readonly snapshot: PersistedSnapshot;
+    readonly metrics: EngineBacktestMetrics;
+    readonly engineVersion: string;
+    readonly configSchemaVersion: number;
+}
+export interface EngineBacktestRunSuccess {
+    readonly metrics: EngineBacktestMetrics;
+    readonly engineVersion: string;
+    readonly experimentId: string;
+    readonly runId?: string;
+    readonly experimentUrl: string;
+    readonly persisted: boolean;
+    readonly coverageWarnings: readonly string[];
+}

package/dist/engine-backtest/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -13,3 +13,7 @@ export { runBrowserPkceLogin } from "./auth/browser-login";
 export { startLoopbackCallbackServer } from "./auth/loopback-callback";
 export { CATALOG_OPERATIONS, CATALOG_SOURCE, CATALOG_VERSION, COMPATIBILITY_RANGE, findCatalogOperation, findCatalogOperationByRoute, getOperationSchemaDocument, buildCapabilityManifest, checkGeneratedCatalogCompatibility, } from "./catalog/operations";
 export { CLI_VERSION, CLI_PACKAGE, CLI_CONTRACT_VERSION } from "./version";
+export { validateCatalogWriteBody } from "./catalog/validate-body";
+export { parseRequestBodyFlags, loadJsonArg } from "./commands/request-body";
+export { parseInstallArgs, runInstallWizard, semverLessThan, skillsListHasAlphafox, } from "./install/wizard";
+export { AGENT_INSTALL_GUIDE_BLOB_URL, AGENT_INSTALL_GUIDE_URL, SKILLS_GITHUB_SOURCE, } from "./install/types";

package/dist/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CLI_CONTRACT_VERSION = exports.CLI_PACKAGE = exports.CLI_VERSION = exports.checkGeneratedCatalogCompatibility = exports.buildCapabilityManifest = exports.getOperationSchemaDocument = exports.findCatalogOperationByRoute = exports.findCatalogOperation = exports.COMPATIBILITY_RANGE = exports.CATALOG_VERSION = exports.CATALOG_SOURCE = exports.CATALOG_OPERATIONS = exports.startLoopbackCallbackServer = exports.runBrowserPkceLogin = exports.accessTokenNeedsRefresh = exports.refreshStoredTokensOrNull = exports.refreshStoredTokens = exports.requiresHighRiskConfirmation = exports.inferRawApiRisk = exports.assertHighRiskConfirmation = exports.resolveTypedCommand = exports.checkCliCompatibility = exports.pathTemplateMatches = exports.normalizeApiPath = exports.isInternalDisallowedPath = exports.isFacadeAllowlistedPath = exports.WINDOWS_CRED_MAX_BYTES = exports.windowsCredentialTarget = exports.linuxSecretToolBin = exports.linuxSecretServiceArgs = exports.keychainPlatform = exports.probeOsKeychain = exports.getLastTokenSaveResult = exports.tokenFingerprint = exports.deleteTokens = exports.loadTokens = exports.saveTokens = exports.assertNoTokenFields = exports.saveConfigFile = exports.loadConfigFile = exports.resolveProfile = exports.applyJqFilter = exports.writeError = exports.writeSuccess = exports.parseJsonEnvelope = exports.errorEnvelope = exports.successEnvelope = exports.parseGlobalFlags = exports.runCli = void 0;
+exports.validateCatalogWriteBody = exports.CLI_CONTRACT_VERSION = exports.CLI_PACKAGE = exports.CLI_VERSION = exports.checkGeneratedCatalogCompatibility = exports.buildCapabilityManifest = exports.getOperationSchemaDocument = exports.findCatalogOperationByRoute = exports.findCatalogOperation = exports.COMPATIBILITY_RANGE = exports.CATALOG_VERSION = exports.CATALOG_SOURCE = exports.CATALOG_OPERATIONS = exports.startLoopbackCallbackServer = exports.runBrowserPkceLogin = exports.accessTokenNeedsRefresh = exports.refreshStoredTokensOrNull = exports.refreshStoredTokens = exports.requiresHighRiskConfirmation = exports.inferRawApiRisk = exports.assertHighRiskConfirmation = exports.resolveTypedCommand = exports.checkCliCompatibility = exports.pathTemplateMatches = exports.normalizeApiPath = exports.isInternalDisallowedPath = exports.isFacadeAllowlistedPath = exports.WINDOWS_CRED_MAX_BYTES = exports.windowsCredentialTarget = exports.linuxSecretToolBin = exports.linuxSecretServiceArgs = exports.keychainPlatform = exports.probeOsKeychain = exports.getLastTokenSaveResult = exports.tokenFingerprint = exports.deleteTokens = exports.loadTokens = exports.saveTokens = exports.assertNoTokenFields = exports.saveConfigFile = exports.loadConfigFile = exports.resolveProfile = exports.applyJqFilter = exports.writeError = exports.writeSuccess = exports.parseJsonEnvelope = exports.errorEnvelope = exports.successEnvelope = exports.parseGlobalFlags = exports.runCli = void 0;
+exports.SKILLS_GITHUB_SOURCE = exports.AGENT_INSTALL_GUIDE_URL = exports.AGENT_INSTALL_GUIDE_BLOB_URL = exports.skillsListHasAlphafox = exports.semverLessThan = exports.runInstallWizard = exports.parseInstallArgs = exports.loadJsonArg = exports.parseRequestBodyFlags = void 0;
 var run_1 = require("./commands/run");
 Object.defineProperty(exports, "runCli", { enumerable: true, get: function () { return run_1.runCli; } });
 Object.defineProperty(exports, "parseGlobalFlags", { enumerable: true, get: function () { return run_1.parseGlobalFlags; } });
@@ -65,3 +66,17 @@ var version_1 = require("./version");
 Object.defineProperty(exports, "CLI_VERSION", { enumerable: true, get: function () { return version_1.CLI_VERSION; } });
 Object.defineProperty(exports, "CLI_PACKAGE", { enumerable: true, get: function () { return version_1.CLI_PACKAGE; } });
 Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return version_1.CLI_CONTRACT_VERSION; } });
+var validate_body_1 = require("./catalog/validate-body");
+Object.defineProperty(exports, "validateCatalogWriteBody", { enumerable: true, get: function () { return validate_body_1.validateCatalogWriteBody; } });
+var request_body_1 = require("./commands/request-body");
+Object.defineProperty(exports, "parseRequestBodyFlags", { enumerable: true, get: function () { return request_body_1.parseRequestBodyFlags; } });
+Object.defineProperty(exports, "loadJsonArg", { enumerable: true, get: function () { return request_body_1.loadJsonArg; } });
+var wizard_1 = require("./install/wizard");
+Object.defineProperty(exports, "parseInstallArgs", { enumerable: true, get: function () { return wizard_1.parseInstallArgs; } });
+Object.defineProperty(exports, "runInstallWizard", { enumerable: true, get: function () { return wizard_1.runInstallWizard; } });
+Object.defineProperty(exports, "semverLessThan", { enumerable: true, get: function () { return wizard_1.semverLessThan; } });
+Object.defineProperty(exports, "skillsListHasAlphafox", { enumerable: true, get: function () { return wizard_1.skillsListHasAlphafox; } });
+var types_1 = require("./install/types");
+Object.defineProperty(exports, "AGENT_INSTALL_GUIDE_BLOB_URL", { enumerable: true, get: function () { return types_1.AGENT_INSTALL_GUIDE_BLOB_URL; } });
+Object.defineProperty(exports, "AGENT_INSTALL_GUIDE_URL", { enumerable: true, get: function () { return types_1.AGENT_INSTALL_GUIDE_URL; } });
+Object.defineProperty(exports, "SKILLS_GITHUB_SOURCE", { enumerable: true, get: function () { return types_1.SKILLS_GITHUB_SOURCE; } });

package/dist/install/exec.d.ts

@@ -0,0 +1,13 @@
+import type { ExecResult, InstallRunner } from "./types";
+export declare function wrapWindowsCommand(command: string, args: readonly string[], platform?: NodeJS.Platform): {
+    readonly file: string;
+    readonly argv: string[];
+};
+export declare function execCommand(command: string, args: readonly string[], options?: {
+    readonly timeoutMs?: number;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly inherit?: boolean;
+    readonly platform?: NodeJS.Platform;
+}): Promise<ExecResult>;
+export declare function confirmTty(message: string): Promise<boolean>;
+export declare function createDefaultInstallRunner(env: NodeJS.ProcessEnv, searchDirs: readonly string[]): InstallRunner;

package/dist/install/exec.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapWindowsCommand = wrapWindowsCommand;
+exports.execCommand = execCommand;
+exports.confirmTty = confirmTty;
+exports.createDefaultInstallRunner = createDefaultInstallRunner;
+const node_child_process_1 = require("node:child_process");
+const promises_1 = require("node:readline/promises");
+const node_util_1 = require("node:util");
+const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
+function wrapWindowsCommand(command, args, platform = process.platform) {
+    if (platform === "win32") {
+        return { file: "cmd.exe", argv: ["/c", command, ...args] };
+    }
+    return { file: command, argv: [...args] };
+}
+async function execCommand(command, args, options = {}) {
+    const { file, argv } = wrapWindowsCommand(command, args, options.platform ?? process.platform);
+    const timeout = options.timeoutMs ?? 120_000;
+    if (options.inherit) {
+        await new Promise((resolve, reject) => {
+            const child = (0, node_child_process_1.spawn)(file, argv, {
+                stdio: "inherit",
+                env: options.env,
+                timeout,
+            });
+            child.on("error", reject);
+            child.on("exit", (code) => {
+                if (code === 0)
+                    resolve();
+                else
+                    reject(new Error(`${command} exited ${code ?? "null"}`));
+            });
+        });
+        return { stdout: "", stderr: "" };
+    }
+    const { stdout, stderr } = await execFileAsync(file, argv, {
+        timeout,
+        encoding: "utf8",
+        env: options.env,
+        maxBuffer: 10 * 1024 * 1024,
+    });
+    return { stdout, stderr };
+}
+async function confirmTty(message) {
+    const rl = (0, promises_1.createInterface)({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await rl.question(`${message} [Y/n] `);
+        const token = answer.trim().toLowerCase();
+        return token === "" || token === "y" || token === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function createDefaultInstallRunner(env, searchDirs) {
+    return {
+        env,
+        packageSearchDirs: () => searchDirs,
+        isTty: () => Boolean(process.stdin.isTTY && process.stderr.isTTY),
+        log: (message) => {
+            process.stderr.write(`${message}\n`);
+        },
+        confirm: confirmTty,
+        exec: (command, args, options) => execCommand(command, args, { ...options, env }),
+        execInherit: async (command, args, options) => {
+            await execCommand(command, args, { ...options, env, inherit: true });
+        },
+    };
+}

package/dist/install/package-root.d.ts

@@ -0,0 +1,4 @@
+export declare function findAlphafoxPackageRoot(startDirs: readonly string[]): string | null;
+export declare function packageHasSkills(packageRoot: string): boolean;
+export declare function globalPackageRoot(npmRootGlobal: string): string;
+export declare function globalBinPath(npmPrefixGlobal: string, platform?: NodeJS.Platform): string;

package/dist/install/package-root.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAlphafoxPackageRoot = findAlphafoxPackageRoot;
+exports.packageHasSkills = packageHasSkills;
+exports.globalPackageRoot = globalPackageRoot;
+exports.globalBinPath = globalBinPath;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const version_1 = require("../version");
+function findAlphafoxPackageRoot(startDirs) {
+    for (const start of startDirs) {
+        const found = walkForPackage(start);
+        if (found)
+            return found;
+    }
+    return null;
+}
+function packageHasSkills(packageRoot) {
+    const skillsDir = (0, node_path_1.join)(packageRoot, "skills");
+    if (!(0, node_fs_1.existsSync)(skillsDir))
+        return false;
+    try {
+        return (0, node_fs_1.readdirSync)(skillsDir, { withFileTypes: true }).some((entry) => entry.isDirectory() &&
+            (0, node_fs_1.existsSync)((0, node_path_1.join)(skillsDir, entry.name, "SKILL.md")));
+    }
+    catch {
+        return false;
+    }
+}
+function globalPackageRoot(npmRootGlobal) {
+    return (0, node_path_1.join)(npmRootGlobal, "@alphafox", "cli");
+}
+function globalBinPath(npmPrefixGlobal, platform = process.platform) {
+    if (platform === "win32") {
+        return (0, node_path_1.join)(npmPrefixGlobal, "alphafox.cmd");
+    }
+    return (0, node_path_1.join)(npmPrefixGlobal, "bin", "alphafox");
+}
+function walkForPackage(startDir) {
+    let dir = startDir;
+    for (let i = 0; i < 10; i += 1) {
+        const pkgPath = (0, node_path_1.join)(dir, "package.json");
+        if ((0, node_fs_1.existsSync)(pkgPath) && packageHasSkills(dir)) {
+            try {
+                const parsed = JSON.parse((0, node_fs_1.readFileSync)(pkgPath, "utf8"));
+                if (parsed.name === version_1.CLI_PACKAGE)
+                    return dir;
+            }
+            catch {
+                // keep walking
+            }
+        }
+        const parent = (0, node_path_1.dirname)(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}

package/dist/install/types.d.ts

@@ -0,0 +1,69 @@
+export declare const SKILLS_GITHUB_SOURCE = "alphafoxai/alphafox-cli";
+export declare const SKILLS_NAME_PREFIX = "alphafox-";
+export declare const AGENT_INSTALL_GUIDE_URL = "https://raw.githubusercontent.com/alphafoxai/alphafox-cli/main/docs/alphafox-cli-installation-guide.md";
+export declare const AGENT_INSTALL_GUIDE_BLOB_URL = "https://github.com/alphafoxai/alphafox-cli/blob/main/docs/alphafox-cli-installation-guide.md";
+export type InstallCliAction = "installed" | "upgraded" | "skipped" | "planned";
+export type InstallSkillsAction = "installed" | "skipped" | "planned" | "failed";
+export type InstallAuthAction = "completed" | "skipped" | "failed" | "planned";
+export interface InstallCliStep {
+    readonly action: InstallCliAction;
+    readonly version?: string;
+    readonly previousVersion?: string;
+    readonly latestVersion?: string;
+}
+export interface InstallSkillsStep {
+    readonly action: InstallSkillsAction;
+    readonly source?: string;
+    readonly scope: "global";
+    readonly alreadyPresent?: boolean;
+}
+export interface InstallAuthStep {
+    readonly action: InstallAuthAction;
+    readonly reason?: string;
+}
+export interface InstallResult {
+    readonly cli: InstallCliStep;
+    readonly skills: InstallSkillsStep;
+    readonly auth: InstallAuthStep;
+    readonly next: readonly string[];
+}
+export interface InstallFlags {
+    readonly format: "json" | "jsonl" | "text";
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+    readonly noInput: boolean;
+    readonly jq?: string;
+    readonly noAuth: boolean;
+    readonly help: boolean;
+}
+export interface ExecResult {
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface InstallRunner {
+    readonly exec: (command: string, args: readonly string[], options?: {
+        readonly timeoutMs?: number;
+    }) => Promise<ExecResult>;
+    readonly execInherit: (command: string, args: readonly string[], options?: {
+        readonly timeoutMs?: number;
+    }) => Promise<void>;
+    readonly isTty: () => boolean;
+    readonly confirm: (message: string) => Promise<boolean>;
+    readonly log: (message: string) => void;
+    readonly packageSearchDirs: () => readonly string[];
+    readonly env: NodeJS.ProcessEnv;
+}
+export declare class InstallError extends Error {
+    readonly type: string;
+    readonly subtype?: string;
+    readonly hint?: string;
+    readonly details?: unknown;
+    constructor(input: {
+        readonly message: string;
+        readonly type?: string;
+        readonly subtype?: string;
+        readonly hint?: string;
+        readonly details?: unknown;
+    });
+}
+export declare function isInstallError(value: unknown): value is InstallError;

package/dist/install/types.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InstallError = exports.AGENT_INSTALL_GUIDE_BLOB_URL = exports.AGENT_INSTALL_GUIDE_URL = exports.SKILLS_NAME_PREFIX = exports.SKILLS_GITHUB_SOURCE = void 0;
+exports.isInstallError = isInstallError;
+exports.SKILLS_GITHUB_SOURCE = "alphafoxai/alphafox-cli";
+exports.SKILLS_NAME_PREFIX = "alphafox-";
+exports.AGENT_INSTALL_GUIDE_URL = "https://raw.githubusercontent.com/alphafoxai/alphafox-cli/main/docs/alphafox-cli-installation-guide.md";
+exports.AGENT_INSTALL_GUIDE_BLOB_URL = "https://github.com/alphafoxai/alphafox-cli/blob/main/docs/alphafox-cli-installation-guide.md";
+class InstallError extends Error {
+    type;
+    subtype;
+    hint;
+    details;
+    constructor(input) {
+        super(input.message);
+        this.name = "InstallError";
+        this.type = input.type ?? "runtime";
+        this.subtype = input.subtype;
+        this.hint = input.hint;
+        this.details = input.details;
+    }
+}
+exports.InstallError = InstallError;
+function isInstallError(value) {
+    return value instanceof InstallError;
+}

package/dist/install/wizard.d.ts

@@ -0,0 +1,21 @@
+import { type InstallAuthStep, type InstallFlags, type InstallResult, type InstallRunner } from "./types";
+export declare function parseInstallArgs(args: readonly string[]): {
+    readonly noAuth: boolean;
+    readonly help: boolean;
+    readonly unknown: readonly string[];
+};
+export declare function semverLessThan(a: string, b: string): boolean;
+export declare function parseNpmListVersion(output: string): string | null;
+export declare function skillsListHasAlphafox(output: string): boolean;
+export declare function nextSteps(input: {
+    readonly auth: InstallAuthStep;
+    readonly dryRun: boolean;
+}): string[];
+export declare function runInstallWizard(flags: InstallFlags, env?: NodeJS.ProcessEnv, runner?: InstallRunner): Promise<InstallResult>;
+export declare function installHelpData(): {
+    readonly name: string;
+    readonly usage: readonly string[];
+    readonly description: string;
+    readonly agentGuide: string;
+};
+export declare function resolveLocalSkillsDir(searchDirs: readonly string[]): string | null;