@alphafox/cli 0.2.0 → 0.3.3

package/dist/install/wizard.js

@@ -0,0 +1,330 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseInstallArgs = parseInstallArgs;
+exports.semverLessThan = semverLessThan;
+exports.parseNpmListVersion = parseNpmListVersion;
+exports.skillsListHasAlphafox = skillsListHasAlphafox;
+exports.nextSteps = nextSteps;
+exports.runInstallWizard = runInstallWizard;
+exports.installHelpData = installHelpData;
+exports.resolveLocalSkillsDir = resolveLocalSkillsDir;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const version_1 = require("../version");
+const exec_1 = require("./exec");
+const package_root_1 = require("./package-root");
+const types_1 = require("./types");
+const NPM_TIMEOUT_MS = 120_000;
+const SKILLS_TIMEOUT_MS = 120_000;
+function parseInstallArgs(args) {
+    let noAuth = false;
+    let help = false;
+    const unknown = [];
+    for (const arg of args) {
+        if (arg === "--no-auth") {
+            noAuth = true;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            help = true;
+        }
+        else {
+            unknown.push(arg);
+        }
+    }
+    return { noAuth, help, unknown };
+}
+function semverLessThan(a, b) {
+    const pa = stripPrerelease(a).split(".").map((part) => Number(part) || 0);
+    const pb = stripPrerelease(b).split(".").map((part) => Number(part) || 0);
+    for (let i = 0; i < 3; i += 1) {
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return true;
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+function parseNpmListVersion(output) {
+    const match = output.match(/@(\d+\.\d+\.\d+[^\s]*)/);
+    return match?.[1] ?? null;
+}
+function skillsListHasAlphafox(output) {
+    const prefix = types_1.SKILLS_NAME_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|\\s)${prefix}[\\w-]+`, "m").test(output);
+}
+function nextSteps(input) {
+    const steps = ["请重启 AI 工具，以便加载刚安装的 Skills。"];
+    if (input.auth.action === "skipped" || input.auth.action === "planned") {
+        steps.push("alphafox auth login --browser --format json --no-input", "alphafox auth login --no-wait --format json --no-input");
+    }
+    steps.push("alphafox doctor --format json --no-input", `Agent 安装指南：${types_1.AGENT_INSTALL_GUIDE_BLOB_URL}`);
+    if (input.dryRun) {
+        steps.unshift("这是 --dry-run，去掉该参数再运行才会真正安装。");
+    }
+    return steps;
+}
+async function runInstallWizard(flags, env = process.env, runner = (0, exec_1.createDefaultInstallRunner)(env, defaultSearchDirs())) {
+    runner.log("正在安装 Alphafox CLI…");
+    const installedVer = await readGloballyInstalledVersion(runner);
+    const latestVer = await readLatestVersion(runner);
+    const needsUpgrade = Boolean(installedVer) &&
+        Boolean(latestVer) &&
+        semverLessThan(installedVer, latestVer);
+    const cli = await stepInstallCli(flags, runner, {
+        installedVer,
+        latestVer,
+        needsUpgrade,
+    });
+    const skills = await stepInstallSkills(flags, runner);
+    const auth = await stepAuth(flags, runner);
+    return {
+        cli,
+        skills,
+        auth,
+        next: nextSteps({ auth, dryRun: flags.dryRun }),
+    };
+}
+function defaultSearchDirs() {
+    return [__dirname, process.cwd()];
+}
+function stripPrerelease(version) {
+    return version.replace(/-.*$/, "");
+}
+async function readGloballyInstalledVersion(runner) {
+    try {
+        const { stdout, stderr } = await runner.exec("npm", ["list", "-g", version_1.CLI_PACKAGE, "--depth=0"], { timeoutMs: 15_000 });
+        return parseNpmListVersion(`${stdout}\n${stderr}`);
+    }
+    catch {
+        return null;
+    }
+}
+async function readLatestVersion(runner) {
+    try {
+        const { stdout } = await runner.exec("npm", ["view", version_1.CLI_PACKAGE, "version"], {
+            timeoutMs: 15_000,
+        });
+        const ver = stdout.trim();
+        return /^\d+\.\d+\.\d+/.test(ver) ? ver : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function npmRootGlobal(runner) {
+    try {
+        const { stdout } = await runner.exec("npm", ["root", "-g"], {
+            timeoutMs: 15_000,
+        });
+        const root = stdout.trim();
+        return root.length > 0 ? root : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function npmPrefixGlobal(runner) {
+    try {
+        const { stdout } = await runner.exec("npm", ["prefix", "-g"], {
+            timeoutMs: 15_000,
+        });
+        const prefix = stdout.trim();
+        return prefix.length > 0 ? prefix : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function stepInstallCli(flags, runner, versions) {
+    const { installedVer, latestVer, needsUpgrade } = versions;
+    if (installedVer && !needsUpgrade) {
+        runner.log(`已安装（${installedVer}），已跳过`);
+        return {
+            action: flags.dryRun ? "planned" : "skipped",
+            version: installedVer,
+            latestVersion: latestVer ?? undefined,
+        };
+    }
+    if (flags.dryRun) {
+        runner.log(needsUpgrade
+            ? `将升级 ${version_1.CLI_PACKAGE}（${installedVer} → ${latestVer ?? "latest"}）`
+            : `将全局安装 ${version_1.CLI_PACKAGE}`);
+        return {
+            action: "planned",
+            previousVersion: installedVer ?? undefined,
+            latestVersion: latestVer ?? undefined,
+        };
+    }
+    runner.log(needsUpgrade
+        ? `正在升级 ${version_1.CLI_PACKAGE}（${installedVer} → ${latestVer}）…`
+        : `正在全局安装 ${version_1.CLI_PACKAGE}…`);
+    try {
+        await runner.exec("npm", ["install", "-g", version_1.CLI_PACKAGE], {
+            timeoutMs: NPM_TIMEOUT_MS,
+        });
+    }
+    catch (err) {
+        throw new types_1.InstallError({
+            type: "install",
+            subtype: "npm_global_failed",
+            message: `全局安装 ${version_1.CLI_PACKAGE} 失败。`,
+            hint: `npm install -g ${version_1.CLI_PACKAGE}`,
+            details: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const after = (await readGloballyInstalledVersion(runner)) ?? latestVer ?? version_1.CLI_VERSION;
+    runner.log(needsUpgrade ? `已升级到 ${after}` : "已全局安装");
+    return {
+        action: needsUpgrade ? "upgraded" : "installed",
+        version: after,
+        previousVersion: installedVer ?? undefined,
+        latestVersion: latestVer ?? undefined,
+    };
+}
+async function resolveSkillsSources(runner) {
+    const override = runner.env.ALPHAFOX_SKILLS_SOURCE?.trim();
+    if (override)
+        return [override];
+    const sources = [];
+    const npmRoot = await npmRootGlobal(runner);
+    if (npmRoot) {
+        const globalRoot = (0, package_root_1.globalPackageRoot)(npmRoot);
+        if ((0, package_root_1.packageHasSkills)(globalRoot))
+            sources.push(globalRoot);
+    }
+    const localRoot = (0, package_root_1.findAlphafoxPackageRoot)(runner.packageSearchDirs());
+    if (localRoot && !sources.includes(localRoot) && (0, package_root_1.packageHasSkills)(localRoot)) {
+        sources.push(localRoot);
+    }
+    sources.push(types_1.SKILLS_GITHUB_SOURCE);
+    return sources;
+}
+async function skillsAlreadyInstalled(runner) {
+    try {
+        const { stdout, stderr } = await runner.exec("npx", ["-y", "skills", "ls", "-g"], { timeoutMs: SKILLS_TIMEOUT_MS });
+        return skillsListHasAlphafox(`${stdout}\n${stderr}`);
+    }
+    catch {
+        return false;
+    }
+}
+async function stepInstallSkills(flags, runner) {
+    const sources = await resolveSkillsSources(runner);
+    const already = flags.dryRun ? false : await skillsAlreadyInstalled(runner);
+    if (already) {
+        runner.log("Skills 已安装，已跳过");
+        return {
+            action: "skipped",
+            source: sources[0],
+            scope: "global",
+            alreadyPresent: true,
+        };
+    }
+    if (flags.dryRun) {
+        runner.log(`将从 ${sources[0] ?? types_1.SKILLS_GITHUB_SOURCE} 安装 Skills`);
+        return {
+            action: "planned",
+            source: sources[0] ?? types_1.SKILLS_GITHUB_SOURCE,
+            scope: "global",
+        };
+    }
+    runner.log("正在安装 AI Skills…");
+    let lastError;
+    for (const source of sources) {
+        try {
+            await runner.exec("npx", ["-y", "skills", "add", source, "-y", "-g"], { timeoutMs: SKILLS_TIMEOUT_MS });
+            runner.log(`Skills 已安装（${source}）`);
+            return { action: "installed", source, scope: "global" };
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    throw new types_1.InstallError({
+        type: "install",
+        subtype: "skills_add_failed",
+        message: "安装 Agent Skills 失败。",
+        hint: `npx skills add ${types_1.SKILLS_GITHUB_SOURCE} -y -g`,
+        details: lastError instanceof Error ? lastError.message : String(lastError),
+    });
+}
+async function resolveAlphafoxBin(runner) {
+    const prefix = await npmPrefixGlobal(runner);
+    if (prefix) {
+        const bin = (0, package_root_1.globalBinPath)(prefix);
+        if ((0, node_fs_1.existsSync)(bin))
+            return bin;
+    }
+    try {
+        const { stdout } = await runner.exec(process.platform === "win32" ? "where" : "which", ["alphafox"], { timeoutMs: 10_000 });
+        const first = stdout.split(/\r?\n/)[0]?.trim();
+        return first || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function stepAuth(flags, runner) {
+    if (flags.noAuth) {
+        return { action: "skipped", reason: "no-auth" };
+    }
+    if (flags.noInput || !runner.isTty()) {
+        if (flags.dryRun) {
+            return { action: "planned", reason: "non-interactive" };
+        }
+        runner.log("要完成安装，请运行：\n  alphafox auth login --browser\n  alphafox auth login --no-wait --format json --no-input");
+        return { action: "skipped", reason: "non-interactive" };
+    }
+    if (flags.dryRun) {
+        runner.log("将提示运行 alphafox auth login --browser");
+        return { action: "planned", reason: "tty" };
+    }
+    const yes = await runner.confirm("现在登录，以便 Agent 可以调用公开 Application API？");
+    if (!yes) {
+        runner.log("已跳过登录。之后可运行 alphafox auth login。");
+        return { action: "skipped", reason: "declined" };
+    }
+    const bin = await resolveAlphafoxBin(runner);
+    if (!bin) {
+        throw new types_1.InstallError({
+            type: "install",
+            subtype: "cli_bin_missing",
+            message: "安装完成后找不到 alphafox 可执行文件。",
+            hint: "请确认 npm 全局 bin 目录在 PATH 中，然后运行 alphafox auth login --browser。",
+        });
+    }
+    try {
+        await runner.execInherit(bin, ["auth", "login", "--browser"], {
+            timeoutMs: 10 * 60_000,
+        });
+        runner.log("登录完成");
+        return { action: "completed" };
+    }
+    catch (err) {
+        runner.log("登录失败。请运行 alphafox auth login --browser 重试。");
+        return {
+            action: "failed",
+            reason: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function installHelpData() {
+    return {
+        name: "install",
+        usage: [
+            "npx @alphafox/cli@latest install",
+            "alphafox install",
+            "alphafox install --no-auth",
+            "alphafox install --dry-run",
+        ],
+        description: "全局安装 @alphafox/cli，并通过 npx skills add 把同版本 Agent Skills 写入本机已检测到的 Agent（Cursor、Claude Code、Codex 等）的用户级目录。",
+        agentGuide: types_1.AGENT_INSTALL_GUIDE_BLOB_URL,
+    };
+}
+function resolveLocalSkillsDir(searchDirs) {
+    const root = (0, package_root_1.findAlphafoxPackageRoot)(searchDirs);
+    if (!root)
+        return null;
+    const skillsDir = (0, node_path_1.join)(root, "skills");
+    return (0, package_root_1.packageHasSkills)(root) ? skillsDir : null;
+}

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 export declare const CLI_NAME = "alphafox";
 export declare const CLI_PACKAGE = "@alphafox/cli";
-export declare const CLI_VERSION = "0.2.0";
+export declare const CLI_VERSION = "0.3.3";
 export { CATALOG_VERSION as CLI_CONTRACT_VERSION } from "./catalog/operations";

package/dist/version.js

@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLI_CONTRACT_VERSION = exports.CLI_VERSION = exports.CLI_PACKAGE = exports.CLI_NAME = void 0;
 exports.CLI_NAME = "alphafox";
 exports.CLI_PACKAGE = "@alphafox/cli";
-exports.CLI_VERSION = "0.2.0";
+exports.CLI_VERSION = "0.3.3";
 var operations_1 = require("./catalog/operations");
 Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return operations_1.CATALOG_VERSION; } });

package/docs/alphafox-cli-installation-guide.md

@@ -0,0 +1,105 @@
+# Alphafox CLI installation guide
+
+The following steps are designed for AI Agents. Some steps require the user
+to complete a browser or Device Flow approval. Always use
+`--format json --no-input` when invoking the CLI. Never pass `--token`.
+
+Raw copy of this file:
+https://raw.githubusercontent.com/alphafoxai/alphafox-cli/main/docs/alphafox-cli-installation-guide.md
+
+## Prerequisites
+
+- Node.js 20+ (`npm` / `npx`)
+
+## Step 1: Install the CLI and Agent Skills
+
+Skills do **not** register with Cursor / Claude Code / Codex from
+`npm install -g` alone. The second command is required.
+
+```shell
+# Install CLI
+npm install -g @alphafox/cli
+
+# Install CLI SKILL (required) — project-local, current workspace
+npx -y skills add "$(npm root -g)/@alphafox/cli" -y
+```
+
+If the local package path fails (older tarball without `skills/`, or
+`npm root -g` is wrong), fall back to the public GitHub source:
+
+```shell
+npx -y skills add alphafoxai/alphafox-cli -y
+```
+
+To install Skills for every project on this machine instead of the current
+repo, add `-g`:
+
+```shell
+npx -y skills add "$(npm root -g)/@alphafox/cli" -y -g
+```
+
+Do not invent a second catalog. Skills must stay co-versioned with the CLI
+that was just installed.
+
+## Step 2: Login
+
+### Device Flow (headless / Agent)
+
+1. Start login and extract `verification_uri` / `user_code` from the JSON
+   envelope. Send those to the user. Do not poll in a tight loop.
+
+```shell
+alphafox auth login --no-wait --format json --no-input
+```
+
+2. After the user approves, resume with the `device_code` from step 1:
+
+```shell
+alphafox auth login --device-code <device_code> --format json --no-input
+```
+
+### Browser loopback (human on this machine)
+
+If the user is at a local desktop and can use a browser:
+
+```shell
+alphafox auth login --browser --format json --no-input
+```
+
+The CLI binds `127.0.0.1` and opens the system browser. If the browser
+cannot open, the error includes a copyable `authorizeUrl` — send that to
+the user. Do not retry as Device Flow unless the operator is headless.
+
+Default profile is `production`. Use `--profile staging|local` only when
+the user explicitly asks.
+
+## Step 3: Verify
+
+```shell
+alphafox doctor --format json --no-input
+alphafox auth status --verify --format json --no-input
+alphafox whoami --format json --no-input
+```
+
+Parse the JSON envelope: `ok === true` means success. Errors land on
+**stderr**. A 401 / expired session means re-run Step 2 — do not pass
+`--token` and do not reuse a token from another profile.
+
+## Step 4: Tell the user to restart
+
+Ask the user to **restart the AI tool** so the new Skills are loaded.
+Then they can ask the Agent to use Alphafox (auth, catalog, trading,
+engine-backtest, …).
+
+## Human wizard (do not run this from an Agent)
+
+Humans who prefer an interactive terminal should run this instead of
+stepping through the commands above:
+
+```shell
+npx @alphafox/cli@latest install
+```
+
+That wizard installs the CLI globally, runs `npx skills add … -y -g`,
+and may prompt for `alphafox auth login --browser`. It is TTY-oriented.
+Agents must follow Steps 1–4 in this document rather than the wizard.

package/docs/favicon.svg

@@ -0,0 +1,4 @@
+<svg width="880" height="1320" viewBox="560 400 880 1320" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M600 859.99V448.467C600 444.343 603.341 440.997 607.455 441.283C633.947 443.127 687.377 454.464 738.326 489.713C790.889 526.08 819.686 577.964 829.376 603.853C830.516 606.899 833.375 608.999 836.627 608.999H974.473C977.797 608.999 980.699 606.816 981.805 603.682C989.573 581.673 1012.28 537.164 1054.85 499.081C1097.95 460.53 1170.23 445.26 1207.73 441.629C1212.01 441.215 1215.61 444.632 1215.61 448.934V860.713C1215.61 864.837 1212.28 868.175 1208.15 868.278C1166.66 869.316 1082.4 878.881 1024.32 911.272C971.303 940.844 930.998 987.234 911.43 1015.2C907.935 1020.2 899.832 1019.72 896.775 1014.44C882.18 989.258 849.547 947.01 795.65 911.272C735.079 871.11 650.192 865.287 608.157 867.588C603.768 867.828 600 864.385 600 859.99Z" fill="#FF991F"/>
+<path d="M600.58 1235.01L600.58 969.867C600.58 965.744 603.924 962.4 608.047 962.458C675.284 963.412 740.225 977.952 799.655 1043.32C866.429 1116.76 897.008 1187.09 1027.44 1187.09L1133.53 1187.09C1290.79 1187.09 1400 1305.96 1400 1452.22L1400 1676.91C1400 1684.08 1391.55 1686.6 1387.59 1680.62C1357.88 1635.76 1286.34 1537.49 1154.22 1537.49L897.008 1537.49C718.527 1537.49 600.58 1420.82 600.58 1235.01Z" fill="#FF991F"/>
+</svg>