@alphafox/cli 0.2.0 → 0.3.2

package/dist/install/wizard.js

@@ -0,0 +1,332 @@
+"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 = [
+        "Restart the AI tool so newly installed Skills are loaded.",
+    ];
+    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 install guide: ${types_1.AGENT_INSTALL_GUIDE_BLOB_URL}`);
+    if (input.dryRun) {
+        steps.unshift("This was --dry-run; re-run without it to apply changes.");
+    }
+    return steps;
+}
+async function runInstallWizard(flags, env = process.env, runner = (0, exec_1.createDefaultInstallRunner)(env, defaultSearchDirs())) {
+    runner.log("Setting up 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(`Already installed (${installedVer}). Skipped`);
+        return {
+            action: flags.dryRun ? "planned" : "skipped",
+            version: installedVer,
+            latestVersion: latestVer ?? undefined,
+        };
+    }
+    if (flags.dryRun) {
+        runner.log(needsUpgrade
+            ? `Would upgrade ${version_1.CLI_PACKAGE} (${installedVer} → ${latestVer ?? "latest"})`
+            : `Would install ${version_1.CLI_PACKAGE} globally`);
+        return {
+            action: "planned",
+            previousVersion: installedVer ?? undefined,
+            latestVersion: latestVer ?? undefined,
+        };
+    }
+    runner.log(needsUpgrade
+        ? `Upgrading ${version_1.CLI_PACKAGE} (${installedVer} → ${latestVer})...`
+        : `Installing ${version_1.CLI_PACKAGE} globally...`);
+    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: `Failed to install ${version_1.CLI_PACKAGE} globally.`,
+            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 ? `Upgraded to ${after}` : "Installed globally");
+    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 already installed. Skipped");
+        return {
+            action: "skipped",
+            source: sources[0],
+            scope: "global",
+            alreadyPresent: true,
+        };
+    }
+    if (flags.dryRun) {
+        runner.log(`Would install Skills from ${sources[0] ?? types_1.SKILLS_GITHUB_SOURCE}`);
+        return {
+            action: "planned",
+            source: sources[0] ?? types_1.SKILLS_GITHUB_SOURCE,
+            scope: "global",
+        };
+    }
+    runner.log("Installing 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 installed (${source})`);
+            return { action: "installed", source, scope: "global" };
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    throw new types_1.InstallError({
+        type: "install",
+        subtype: "skills_add_failed",
+        message: "Failed to install 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("To finish setup, run:\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("Would prompt for alphafox auth login --browser");
+        return { action: "planned", reason: "tty" };
+    }
+    const yes = await runner.confirm("Log in now so Agents can call the public Application API?");
+    if (!yes) {
+        runner.log("Skipped login. Run alphafox auth login later.");
+        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 binary not found after install.",
+            hint: "Ensure the npm global bin directory is on PATH, then run alphafox auth login --browser.",
+        });
+    }
+    try {
+        await runner.execInherit(bin, ["auth", "login", "--browser"], {
+            timeoutMs: 10 * 60_000,
+        });
+        runner.log("Login complete");
+        return { action: "completed" };
+    }
+    catch (err) {
+        runner.log("Login failed. Run alphafox auth login --browser to retry.");
+        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: "Install @alphafox/cli globally and copy co-versioned Agent Skills into detected agents (Cursor, Claude Code, Codex, …) via npx skills add.",
+        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.2";
 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.2";
 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>