@alphafox/cli 0.1.5 → 0.3.2

package/README.md

@@ -2,16 +2,43 @@
 
 Alphafox CLI (`alphafox`) — Agent and human entry for the versioned Public Application API on alphafox-web.
 
+Homepage: https://alphafoxai.github.io/alphafox-cli/
+
 ## Install
 
+Pick **one** of the following. Both install the CLI **and** register Agent
+Skills. `npm install -g @alphafox/cli` alone does **not** install Skills.
+
+### Method 1 — Manual wizard
+
 ```bash
-npm install -g @alphafox/cli
-# or
-npx alphafox-cli version
+npx @alphafox/cli@latest install
 ```
 
+This installs `@alphafox/cli` globally, runs `npx skills add` into detected
+agents (Cursor, Claude Code, Codex, …), and may prompt for
+`alphafox auth login --browser`. **Restart the AI tool** afterwards so Skills
+load.
+
+### Method 2 — Install via Agent
+
+Copy and send this to Cursor / Claude Code / Codex / Trae:
+
+```
+帮我安装 Alphafox CLI：https://github.com/alphafoxai/alphafox-cli/blob/main/docs/alphafox-cli-installation-guide.md
+```
+
+```
+Help me install Alphafox CLI: https://github.com/alphafoxai/alphafox-cli/blob/main/docs/alphafox-cli-installation-guide.md
+```
+
+The Agent follows that guide (`npm install -g`, `npx skills add`, login,
+`doctor`). **Restart the AI tool** when it finishes.
+
 ## Quick start
 
+After Method 1 or 2:
+
 ```bash
 alphafox version
 alphafox doctor
@@ -28,14 +55,25 @@ alphafox api GET /api/v1/me
 - Profiles: `production` (default), `staging`, `local` — isolated issuer/audience/client (ADR 0003).
 - High-risk writes require `--yes`. Automation tokens are **deferred** (ADR 0004).
 - Raw `api` only hits allowlisted `/api/v1/*` facade paths.
+- Writes validate `--body` / `--config @file` against the catalog schema
+  before HTTP. Agents must `alphafox schema <operationId>` first and must
+  not invent fields. Large objects use `--config @file`, not argv.
 
 ## Skills
 
-Co-versioned Agent Skills live under `skills/`. They route intent to public `operationId`s only.
+Co-versioned Agent Skills live under `skills/`. API-oriented skills route public
+`operationId`s; an explicit local-execution skill may call its co-versioned
+built-in command.
+
+`alphafox install` (and the [Agent install guide](docs/alphafox-cli-installation-guide.md))
+run `npx skills add` so those files land in Agent skill directories
+(`.cursor/skills`, `.claude/skills`, `~/.agents/skills`, …).
 
 ## Docs
 
+- [Homepage](https://alphafoxai.github.io/alphafox-cli/)
 - [Release / supply chain](docs/release-supply-chain.md)
+- [Agent install guide](docs/alphafox-cli-installation-guide.md)
 - [Staging E2E checklist](docs/e2e-staging.md)
 - Related ADRs and parity matrix live in the alphafox-web repository
 

package/dist/auth/browser-login.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interactive Authorization Code + PKCE with a loopback callback.
+ * The CLI listens on 127.0.0.1, opens the system browser, exchanges the
+ * code with the in-memory verifier, and stores tokens in the OS keychain.
+ */
+import type { ProfileConfig } from "../config/profiles";
+import { type OpenBrowserResult } from "./open-browser";
+export declare const DEFAULT_BROWSER_LOGIN_TIMEOUT_MS = 300000;
+export type BrowserLoginResult = {
+    readonly status: "authenticated";
+    readonly accessTokenFingerprint: string;
+    readonly expiresIn: number;
+    readonly requestId?: string;
+} | {
+    readonly status: "failed";
+    readonly reason: "listen_failed" | "browser_open_failed" | "timeout" | "state_mismatch" | "oauth_error" | "missing_code" | "token_exchange_failed";
+    readonly message: string;
+    readonly authorizeUrl?: string;
+    readonly oauthError?: string;
+};
+export type OpenBrowserFn = (url: string) => OpenBrowserResult | Promise<OpenBrowserResult>;
+export declare function browserLoginTimeoutMs(env?: NodeJS.ProcessEnv): number;
+export declare function resolveOpenBrowser(env?: NodeJS.ProcessEnv): OpenBrowserFn;
+export declare function runBrowserPkceLogin(input: {
+    readonly profile: ProfileConfig;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly timeoutMs?: number;
+    readonly openBrowser?: OpenBrowserFn;
+    readonly fetchImpl?: typeof fetch;
+}): Promise<BrowserLoginResult>;

package/dist/auth/browser-login.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Interactive Authorization Code + PKCE with a loopback callback.
+ * The CLI listens on 127.0.0.1, opens the system browser, exchanges the
+ * code with the in-memory verifier, and stores tokens in the OS keychain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BROWSER_LOGIN_TIMEOUT_MS = void 0;
+exports.browserLoginTimeoutMs = browserLoginTimeoutMs;
+exports.resolveOpenBrowser = resolveOpenBrowser;
+exports.runBrowserPkceLogin = runBrowserPkceLogin;
+const node_crypto_1 = require("node:crypto");
+const client_1 = require("../http/client");
+const store_1 = require("../keychain/store");
+const loopback_callback_1 = require("./loopback-callback");
+const open_browser_1 = require("./open-browser");
+const pkce_1 = require("./pkce");
+exports.DEFAULT_BROWSER_LOGIN_TIMEOUT_MS = 300_000;
+function browserLoginTimeoutMs(env = process.env) {
+    const raw = env.ALPHAFOX_BROWSER_LOGIN_TIMEOUT_MS?.trim();
+    if (!raw)
+        return exports.DEFAULT_BROWSER_LOGIN_TIMEOUT_MS;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : exports.DEFAULT_BROWSER_LOGIN_TIMEOUT_MS;
+}
+function resolveOpenBrowser(env = process.env) {
+    if (env.ALPHAFOX_TEST_BROWSER_OPEN === "fail") {
+        return () => ({ ok: false, reason: "test_browser_open_disabled" });
+    }
+    return open_browser_1.openSystemBrowser;
+}
+async function runBrowserPkceLogin(input) {
+    const env = input.env ?? process.env;
+    const openBrowser = input.openBrowser ?? resolveOpenBrowser(env);
+    const timeoutMs = input.timeoutMs ?? browserLoginTimeoutMs(env);
+    const state = (0, node_crypto_1.randomUUID)();
+    const pkce = (0, pkce_1.generatePkcePair)();
+    let loopback;
+    try {
+        loopback = await (0, loopback_callback_1.startLoopbackCallbackServer)({
+            expectedState: state,
+            timeoutMs,
+        });
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            reason: "listen_failed",
+            message: err instanceof Error
+                ? `Could not bind loopback callback server: ${err.message}`
+                : "Could not bind loopback callback server.",
+        };
+    }
+    const authorizeUrl = (0, pkce_1.buildAuthorizeUrl)({
+        issuer: input.profile.issuer,
+        clientId: input.profile.clientId,
+        redirectUri: loopback.redirectUri,
+        codeChallenge: pkce.codeChallenge,
+        state,
+    });
+    try {
+        let opened;
+        try {
+            opened = await openBrowser(authorizeUrl);
+        }
+        catch (err) {
+            return {
+                status: "failed",
+                reason: "browser_open_failed",
+                message: err instanceof Error
+                    ? `Could not open the system browser (${err.message}).`
+                    : "Could not open the system browser.",
+                authorizeUrl,
+            };
+        }
+        if (!opened.ok) {
+            return {
+                status: "failed",
+                reason: "browser_open_failed",
+                message: `Could not open the system browser (${opened.reason}).`,
+                authorizeUrl,
+            };
+        }
+        const callback = await loopback.wait();
+        if (callback.status === "timeout") {
+            return {
+                status: "failed",
+                reason: "timeout",
+                message: "Browser login timed out waiting for the localhost callback.",
+            };
+        }
+        if (callback.status === "state_mismatch") {
+            return {
+                status: "failed",
+                reason: "state_mismatch",
+                message: "OAuth callback state did not match the login attempt.",
+            };
+        }
+        if (callback.status === "oauth_error") {
+            return {
+                status: "failed",
+                reason: "oauth_error",
+                message: `Authorization server returned ${callback.error}.`,
+                oauthError: callback.error,
+            };
+        }
+        if (callback.status === "missing_code") {
+            return {
+                status: "failed",
+                reason: "missing_code",
+                message: "OAuth callback did not include an authorization code.",
+            };
+        }
+        let res;
+        try {
+            res = await (0, client_1.apiRequest)({
+                method: "POST",
+                path: "/api/auth/oauth/token",
+                profile: input.profile,
+                skipAuth: true,
+                body: {
+                    grant_type: "authorization_code",
+                    code: callback.code,
+                    redirect_uri: loopback.redirectUri,
+                    client_id: input.profile.clientId,
+                    code_verifier: pkce.codeVerifier,
+                },
+            }, env, input.fetchImpl ?? fetch);
+        }
+        catch (err) {
+            return {
+                status: "failed",
+                reason: "token_exchange_failed",
+                message: err instanceof Error
+                    ? `Token exchange failed (${err.message}).`
+                    : "Token exchange failed.",
+            };
+        }
+        if (res.status >= 400) {
+            return {
+                status: "failed",
+                reason: "token_exchange_failed",
+                message: `Token exchange failed (HTTP ${res.status}).`,
+            };
+        }
+        const tokens = parseTokenPair(res.json);
+        if (!tokens) {
+            return {
+                status: "failed",
+                reason: "token_exchange_failed",
+                message: "Token response missing access_token/refresh_token.",
+            };
+        }
+        (0, store_1.saveTokens)(input.profile.name, {
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token,
+            expiresAt: Date.now() + (tokens.expires_in ?? 600) * 1000,
+            environment: input.profile.name,
+            issuer: input.profile.issuer,
+            audience: input.profile.audience,
+            clientId: input.profile.clientId,
+            scopes: (tokens.scope ?? "openid profile").split(/\s+/).filter(Boolean),
+        }, env);
+        return {
+            status: "authenticated",
+            accessTokenFingerprint: (0, store_1.tokenFingerprint)(tokens.access_token),
+            expiresIn: tokens.expires_in ?? 600,
+            requestId: res.requestId,
+        };
+    }
+    finally {
+        await loopback.close();
+    }
+}
+function parseTokenPair(json) {
+    if (!json || typeof json !== "object")
+        return null;
+    const o = json;
+    const access = o.access_token ?? o.accessToken;
+    const refresh = o.refresh_token ?? o.refreshToken;
+    if (typeof access !== "string" || typeof refresh !== "string")
+        return null;
+    return {
+        access_token: access,
+        refresh_token: refresh,
+        expires_in: typeof o.expires_in === "number"
+            ? o.expires_in
+            : typeof o.expiresIn === "number"
+                ? o.expiresIn
+                : undefined,
+        scope: typeof o.scope === "string" ? o.scope : undefined,
+    };
+}

package/dist/auth/loopback-callback.d.ts

@@ -0,0 +1,32 @@
+/**
+ * One-shot RFC 8252 loopback callback server for Authorization Code + PKCE.
+ * Binds 127.0.0.1 only. HTML responses never include code, token, or verifier.
+ */
+export declare const LOOPBACK_CALLBACK_PATH = "/callback";
+export type LoopbackCallbackResult = {
+    readonly status: "success";
+    readonly code: string;
+    readonly state: string;
+} | {
+    readonly status: "oauth_error";
+    readonly error: string;
+    readonly errorDescription?: string;
+} | {
+    readonly status: "state_mismatch";
+} | {
+    readonly status: "missing_code";
+} | {
+    readonly status: "timeout";
+};
+export interface LoopbackCallbackServer {
+    readonly redirectUri: string;
+    readonly port: number;
+    wait(): Promise<LoopbackCallbackResult>;
+    close(): Promise<void>;
+}
+export declare function startLoopbackCallbackServer(options: {
+    readonly expectedState: string;
+    readonly timeoutMs?: number;
+    readonly path?: string;
+    readonly port?: number;
+}): Promise<LoopbackCallbackServer>;

package/dist/auth/loopback-callback.js

@@ -0,0 +1,175 @@
+"use strict";
+/**
+ * One-shot RFC 8252 loopback callback server for Authorization Code + PKCE.
+ * Binds 127.0.0.1 only. HTML responses never include code, token, or verifier.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LOOPBACK_CALLBACK_PATH = void 0;
+exports.startLoopbackCallbackServer = startLoopbackCallbackServer;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = __importDefault(require("node:http"));
+exports.LOOPBACK_CALLBACK_PATH = "/callback";
+const SUCCESS_HTML = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Alphafox CLI</title></head>
+<body><p>Signed in. You can close this window and return to the CLI.</p></body></html>
+`;
+const FAILURE_HTML = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Alphafox CLI</title></head>
+<body><p>Authorization failed. You can close this window and return to the CLI.</p></body></html>
+`;
+const DUPLICATE_HTML = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Alphafox CLI</title></head>
+<body><p>This login callback was already used. You can close this window.</p></body></html>
+`;
+async function startLoopbackCallbackServer(options) {
+    const callbackPath = options.path ?? exports.LOOPBACK_CALLBACK_PATH;
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const expectedState = options.expectedState;
+    let settled = false;
+    let timer;
+    let resolveDone;
+    const done = new Promise((resolve) => {
+        resolveDone = resolve;
+    });
+    const server = node_http_1.default.createServer((req, res) => {
+        handleLoopbackRequest(req, res, {
+            callbackPath,
+            expectedState,
+            isSettled: () => settled,
+            settle: (result, httpStatus) => {
+                if (settled) {
+                    res.writeHead(409, htmlHeaders());
+                    res.end(DUPLICATE_HTML);
+                    return;
+                }
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                res.writeHead(httpStatus, htmlHeaders());
+                res.end(httpStatus === 200 ? SUCCESS_HTML : FAILURE_HTML);
+                resolveDone(result);
+            },
+        });
+    });
+    await listenLoopback(server, options.port ?? 0);
+    const addr = server.address();
+    if (!addr || typeof addr === "string") {
+        server.close();
+        throw new Error("loopback server did not bind a TCP port");
+    }
+    const redirectUri = `http://127.0.0.1:${addr.port}${callbackPath}`;
+    timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        resolveDone({ status: "timeout" });
+    }, timeoutMs);
+    timer.unref?.();
+    let closed = false;
+    return {
+        redirectUri,
+        port: addr.port,
+        wait: () => done,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            clearTimeout(timer);
+            await closeServer(server);
+        },
+    };
+}
+function htmlHeaders() {
+    return {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+    };
+}
+function handleLoopbackRequest(req, res, ctx) {
+    if (ctx.isSettled()) {
+        res.writeHead(409, htmlHeaders());
+        res.end(DUPLICATE_HTML);
+        return;
+    }
+    if (!isLoopbackHostHeader(req.headers.host)) {
+        res.writeHead(400, htmlHeaders());
+        res.end(FAILURE_HTML);
+        return;
+    }
+    if (req.method !== "GET") {
+        res.writeHead(405, htmlHeaders());
+        res.end(FAILURE_HTML);
+        return;
+    }
+    let parsed;
+    try {
+        parsed = new URL(req.url ?? "/", "http://127.0.0.1");
+    }
+    catch {
+        res.writeHead(400, htmlHeaders());
+        res.end(FAILURE_HTML);
+        return;
+    }
+    if (parsed.pathname !== ctx.callbackPath) {
+        res.writeHead(404, htmlHeaders());
+        res.end(FAILURE_HTML);
+        return;
+    }
+    const oauthError = parsed.searchParams.get("error");
+    if (oauthError) {
+        ctx.settle({
+            status: "oauth_error",
+            error: oauthError,
+            errorDescription: parsed.searchParams.get("error_description") ?? undefined,
+        }, 400);
+        return;
+    }
+    const state = parsed.searchParams.get("state") ?? "";
+    if (!statesEqual(state, ctx.expectedState)) {
+        ctx.settle({ status: "state_mismatch" }, 400);
+        return;
+    }
+    const code = parsed.searchParams.get("code")?.trim() ?? "";
+    if (!code) {
+        ctx.settle({ status: "missing_code" }, 400);
+        return;
+    }
+    ctx.settle({ status: "success", code, state }, 200);
+}
+function isLoopbackHostHeader(host) {
+    if (!host)
+        return false;
+    const hostname = host.split(":")[0]?.toLowerCase() ?? "";
+    return hostname === "127.0.0.1" || hostname === "localhost";
+}
+function statesEqual(actual, expected) {
+    const a = Buffer.from(actual);
+    const b = Buffer.from(expected);
+    if (a.length !== b.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(a, b);
+}
+function listenLoopback(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off("error", onError);
+            reject(err);
+        };
+        server.once("error", onError);
+        server.listen({ host: "127.0.0.1", port }, () => {
+            server.off("error", onError);
+            resolve();
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve) => {
+        if (typeof server.closeAllConnections === "function") {
+            server.closeAllConnections();
+        }
+        server.close(() => resolve());
+    });
+}

package/dist/auth/open-browser.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Open a URL in the OS browser. Failure is explicit — callers must not
+ * continue as if the page was shown.
+ */
+export type OpenBrowserResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function systemBrowserCommand(url: string, platform?: NodeJS.Platform): {
+    readonly command: string;
+    readonly args: readonly string[];
+};
+export declare function openSystemBrowser(url: string): OpenBrowserResult;

package/dist/auth/open-browser.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Open a URL in the OS browser. Failure is explicit — callers must not
+ * continue as if the page was shown.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemBrowserCommand = systemBrowserCommand;
+exports.openSystemBrowser = openSystemBrowser;
+const node_child_process_1 = require("node:child_process");
+function systemBrowserCommand(url, platform = process.platform) {
+    if (platform === "darwin") {
+        return { command: "open", args: [url] };
+    }
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/c", "start", "", url] };
+    }
+    return { command: "xdg-open", args: [url] };
+}
+function openSystemBrowser(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return { ok: false, reason: "invalid_url" };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, reason: "unsupported_url_protocol" };
+    }
+    const { command, args } = systemBrowserCommand(url);
+    try {
+        const result = (0, node_child_process_1.spawnSync)(command, [...args], {
+            stdio: "ignore",
+            timeout: 15_000,
+            windowsHide: true,
+        });
+        if (result.error) {
+            return { ok: false, reason: result.error.message };
+        }
+        if (result.status !== 0 && result.status !== null) {
+            return { ok: false, reason: `exit_${result.status}` };
+        }
+        if (result.signal) {
+            return { ok: false, reason: `signal_${result.signal}` };
+        }
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: err instanceof Error ? err.message : "spawn_failed",
+        };
+    }
+}

package/dist/auth/refresh.d.ts

@@ -1,19 +1,44 @@
 /**
- * Silent access-token renewal via refresh_token grant.
+ * Access-token renewal via refresh_token grant.
  * Access tokens are short-lived (~10m); refresh tokens last ~30d (web ADR).
+ *
+ * Outcomes are explicit: callers must not treat a failed refresh as a healthy session.
  */
 import type { ProfileConfig } from "../config/profiles";
 import { type StoredTokens } from "../keychain/store";
 /** Refresh when access token expires within this window. */
 export declare const ACCESS_TOKEN_REFRESH_SKEW_MS = 60000;
+export type RefreshOutcome = {
+    readonly status: "refreshed";
+    readonly tokens: StoredTokens;
+} | {
+    readonly status: "unchanged";
+    readonly tokens: StoredTokens;
+} | {
+    readonly status: "failed";
+    readonly reason: string;
+    readonly tokens: StoredTokens | null;
+} | {
+    readonly status: "no_session";
+    readonly reason: string;
+    readonly tokens: null;
+};
 export declare function accessTokenNeedsRefresh(tokens: StoredTokens, now?: number): boolean;
 /**
  * Exchange refresh_token for a new AT/RT pair and persist to keychain.
- * Returns null if no tokens, no refresh token, or the AS rejects renewal.
+ * Returns a discriminated outcome — never a bare success token on failure.
  */
 export declare function refreshStoredTokens(profile: ProfileConfig, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, options?: {
     readonly now?: number;
     readonly force?: boolean;
+}): Promise<RefreshOutcome>;
+/**
+ * Convenience for callers that only need tokens on successful refresh/unchanged.
+ * Returns null for no_session and failed — never pretends failure is success.
+ */
+export declare function refreshStoredTokensOrNull(profile: ProfileConfig, env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, options?: {
+    readonly now?: number;
+    readonly force?: boolean;
 }): Promise<StoredTokens | null>;
 /** Test helper: clear in-flight map between cases. */
 export declare function clearRefreshInflightForTests(): void;