@alphafox/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alphafox AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @alphafox/cli
+
+Alphafox CLI (`alphafox`) — Agent and human entry for the versioned Public Application API on alphafox-web.
+
+## Install
+
+```bash
+npm install -g @alphafox/cli
+# or
+npx @alphafox/cli version
+```
+
+## Quick start
+
+```bash
+alphafox version
+alphafox doctor
+alphafox auth login --no-wait          # Device Flow (headless-friendly)
+alphafox auth login --device-code <code>
+alphafox whoami
+alphafox schema me.whoami
+alphafox api GET /api/v1/me
+```
+
+## Security
+
+- Tokens live in the OS keychain (or controlled test injection). **Never** in config files or `--token` argv.
+- 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.
+
+## Skills
+
+Co-versioned Agent Skills live under `skills/`. They route intent to public `operationId`s only.
+
+## Docs
+
+- [Release / supply chain](docs/release-supply-chain.md)
+- [Staging E2E checklist](docs/e2e-staging.md)
+- Related ADRs and parity matrix live in the alphafox-web repository
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm test
+node dist/cli.js version
+```
+
+## License
+
+MIT

package/bin/alphafox.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/cli.js");

package/dist/auth/pkce.d.ts

@@ -0,0 +1,13 @@
+export declare function generatePkcePair(): {
+    readonly codeVerifier: string;
+    readonly codeChallenge: string;
+    readonly codeChallengeMethod: "S256";
+};
+export declare function buildAuthorizeUrl(input: {
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly codeChallenge: string;
+    readonly state: string;
+    readonly scope?: string;
+}): string;

package/dist/auth/pkce.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatePkcePair = generatePkcePair;
+exports.buildAuthorizeUrl = buildAuthorizeUrl;
+const node_crypto_1 = require("node:crypto");
+function generatePkcePair() {
+    const codeVerifier = (0, node_crypto_1.randomBytes)(32).toString("base64url");
+    const codeChallenge = (0, node_crypto_1.createHash)("sha256")
+        .update(codeVerifier, "utf8")
+        .digest("base64url");
+    return {
+        codeVerifier,
+        codeChallenge,
+        codeChallengeMethod: "S256",
+    };
+}
+function buildAuthorizeUrl(input) {
+    const authorize = new URL(`${input.issuer.replace(/\/$/, "")}/oauth/authorize`);
+    authorize.searchParams.set("response_type", "code");
+    authorize.searchParams.set("client_id", input.clientId);
+    authorize.searchParams.set("redirect_uri", input.redirectUri);
+    authorize.searchParams.set("code_challenge", input.codeChallenge);
+    authorize.searchParams.set("code_challenge_method", "S256");
+    authorize.searchParams.set("state", input.state);
+    authorize.searchParams.set("scope", input.scope ?? "openid profile offline_access");
+    return authorize.toString();
+}

package/dist/catalog/allowlist.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Raw API allowlist + internal path rejection.
+ * Mirrors alphafox-contracts public-api allowlist rules.
+ */
+/** MVP + core facade paths always allowed; full registry embedded for drift tests. */
+export declare const FACILITY_ALWAYS_ALLOW: readonly ["/api/v1/meta", "/api/v1/me", "/api/v1/operations", "/api/v1/openapi.json", "/api/v1/trading/strategy-definitions", "/api/v1/exchange-connectors", "/api/v1/trading/traders", "/api/v1/chats", "/api/v1/backtests"];
+export declare function normalizeApiPath(path: string): string;
+export declare function isInternalDisallowedPath(path: string): boolean;
+export declare function isFacadeAllowlistedPath(path: string, extraAllow?: readonly string[]): boolean;

package/dist/catalog/allowlist.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Raw API allowlist + internal path rejection.
+ * Mirrors alphafox-contracts public-api allowlist rules.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FACILITY_ALWAYS_ALLOW = void 0;
+exports.normalizeApiPath = normalizeApiPath;
+exports.isInternalDisallowedPath = isInternalDisallowedPath;
+exports.isFacadeAllowlistedPath = isFacadeAllowlistedPath;
+const INTERNAL_PREFIXES = [
+    "/backend",
+    "/control-plane",
+    "/signal-center",
+    "/api/backend",
+    "/api/control-plane",
+    "/api/signal-center",
+];
+/** MVP + core facade paths always allowed; full registry embedded for drift tests. */
+exports.FACILITY_ALWAYS_ALLOW = [
+    "/api/v1/meta",
+    "/api/v1/me",
+    "/api/v1/operations",
+    "/api/v1/openapi.json",
+    "/api/v1/trading/strategy-definitions",
+    "/api/v1/exchange-connectors",
+    "/api/v1/trading/traders",
+    "/api/v1/chats",
+    "/api/v1/backtests",
+];
+function normalizeApiPath(path) {
+    const trimmed = path.trim();
+    if (!trimmed)
+        return "/";
+    const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    return (withSlash.split("?")[0] ?? withSlash).split("#")[0].replace(/\/{2,}/g, "/");
+}
+function isInternalDisallowedPath(path) {
+    const n = normalizeApiPath(path);
+    return INTERNAL_PREFIXES.some((p) => n === p || n.startsWith(`${p}/`) || n.includes(`${p}/`));
+}
+function isFacadeAllowlistedPath(path, extraAllow = []) {
+    const n = normalizeApiPath(path);
+    if (isInternalDisallowedPath(n)) {
+        return false;
+    }
+    if (!n.startsWith("/api/v1")) {
+        return false;
+    }
+    const allow = [...exports.FACILITY_ALWAYS_ALLOW, ...extraAllow];
+    for (const a of allow) {
+        if (n === a || n.startsWith(`${a}/`)) {
+            return true;
+        }
+    }
+    // templated backtests etc.
+    if (/^\/api\/v1\/backtests\/[^/]+(\/.*)?$/.test(n)) {
+        return true;
+    }
+    if (/^\/api\/v1\/trading\/traders\/[^/]+(\/.*)?$/.test(n)) {
+        return true;
+    }
+    if (/^\/api\/v1\//.test(n)) {
+        // Allow any /api/v1/* that is not internal — facade is the allowlist boundary.
+        // Internal services are never mounted under /api/v1.
+        return true;
+    }
+    return false;
+}

package/dist/catalog/operations.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Embedded capability catalog (co-versioned with CLI).
+ * Source of truth for full matrix lives in alphafox-contracts + parity-matrix-m0.md.
+ */
+export interface CatalogOperation {
+    readonly operationId: string;
+    readonly method: string;
+    readonly path: string;
+    readonly role: string;
+    readonly risk: "read" | "write" | "high-risk-write" | string;
+    readonly scopes: readonly string[];
+    readonly stream?: boolean;
+    readonly mvp?: boolean;
+    readonly description?: string;
+}
+export declare const CATALOG_VERSION = "2026-08-11";
+export declare const CATALOG_OPERATIONS: readonly CatalogOperation[];
+export declare function findCatalogOperation(operationId: string): CatalogOperation | undefined;
+export declare function buildCapabilityManifest(): {
+    contractVersion: string;
+    registryVersion: string;
+    operations: {
+        operationId: string;
+        method: string;
+        path: string;
+        role: string;
+        risk: string;
+        scopes: readonly string[];
+        stream: boolean;
+        mvp: boolean;
+    }[];
+};
+/** Resolve path templates like /api/v1/backtests/{backtestId}. */
+export declare function resolveOperationPath(template: string, params: Record<string, string>): string;

package/dist/catalog/operations.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Embedded capability catalog (co-versioned with CLI).
+ * Source of truth for full matrix lives in alphafox-contracts + parity-matrix-m0.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CATALOG_OPERATIONS = exports.CATALOG_VERSION = void 0;
+exports.findCatalogOperation = findCatalogOperation;
+exports.buildCapabilityManifest = buildCapabilityManifest;
+exports.resolveOperationPath = resolveOperationPath;
+exports.CATALOG_VERSION = "2026-08-11";
+exports.CATALOG_OPERATIONS = [
+    {
+        operationId: "meta.get",
+        method: "GET",
+        path: "/api/v1/meta",
+        role: "public",
+        risk: "read",
+        scopes: [],
+        mvp: true,
+        description: "Environment, commit SHA, contract version",
+    },
+    {
+        operationId: "me.whoami",
+        method: "GET",
+        path: "/api/v1/me",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile"],
+        mvp: true,
+        description: "Authenticated user identity",
+    },
+    {
+        operationId: "trading.strategy_definitions.list",
+        method: "GET",
+        path: "/api/v1/trading/strategy-definitions",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "trading:read"],
+        mvp: true,
+    },
+    {
+        operationId: "exchange_connectors.list",
+        method: "GET",
+        path: "/api/v1/exchange-connectors",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "exchange-connectors:read"],
+        mvp: true,
+    },
+    {
+        operationId: "trading.traders.list",
+        method: "GET",
+        path: "/api/v1/trading/traders",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "trading:read"],
+        mvp: true,
+    },
+    {
+        operationId: "chats.create",
+        method: "POST",
+        path: "/api/v1/chats",
+        role: "user",
+        risk: "write",
+        scopes: ["openid", "profile", "chats:write"],
+        mvp: true,
+    },
+    {
+        operationId: "backtests.create",
+        method: "POST",
+        path: "/api/v1/backtests",
+        role: "user",
+        risk: "write",
+        scopes: ["openid", "profile", "backtests:write"],
+        mvp: true,
+    },
+    {
+        operationId: "backtests.byId.get",
+        method: "GET",
+        path: "/api/v1/backtests/{backtestId}",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "backtests:read"],
+        mvp: true,
+    },
+    {
+        operationId: "backtests.byId.stream",
+        method: "GET",
+        path: "/api/v1/backtests/{backtestId}/stream",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "backtests:read"],
+        stream: true,
+        mvp: true,
+    },
+    {
+        operationId: "backtests.byId.cancel",
+        method: "POST",
+        path: "/api/v1/backtests/{backtestId}/cancel",
+        role: "user",
+        risk: "write",
+        scopes: ["openid", "profile", "backtests:write"],
+        mvp: true,
+    },
+    {
+        operationId: "trading.traders.byId.start",
+        method: "POST",
+        path: "/api/v1/trading/traders/{traderId}/start",
+        role: "user",
+        risk: "high-risk-write",
+        scopes: ["openid", "profile", "trading:write", "trading:high-risk"],
+    },
+    {
+        operationId: "trading.traders.byId.stop",
+        method: "POST",
+        path: "/api/v1/trading/traders/{traderId}/stop",
+        role: "user",
+        risk: "high-risk-write",
+        scopes: ["openid", "profile", "trading:write", "trading:high-risk"],
+    },
+    {
+        operationId: "wallet.get",
+        method: "GET",
+        path: "/api/v1/wallet",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "wallet:read"],
+    },
+    {
+        operationId: "notification.channels.list",
+        method: "GET",
+        path: "/api/v1/notification/channels",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "notification:read"],
+    },
+    {
+        operationId: "account.exchange_uids.list",
+        method: "GET",
+        path: "/api/v1/account/exchange-uids",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "account:read"],
+    },
+    {
+        operationId: "subscriptions.me.get",
+        method: "GET",
+        path: "/api/v1/subscriptions/me",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "subscriptions:read"],
+    },
+    {
+        operationId: "managed_wallets.list",
+        method: "GET",
+        path: "/api/v1/managed-wallets",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "managed-wallets:read"],
+    },
+    {
+        operationId: "strategy_plaza.publications.list",
+        method: "GET",
+        path: "/api/v1/strategy-plaza/publications",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "strategy-plaza:read"],
+    },
+    {
+        operationId: "spread_radar.pairs.list",
+        method: "GET",
+        path: "/api/v1/spread-radar/pairs",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "spread-radar:read"],
+    },
+    {
+        operationId: "trader_dna.report.get",
+        method: "GET",
+        path: "/api/v1/trader-dna/report",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "trader-dna:read"],
+    },
+    {
+        operationId: "platform_statistics.get",
+        method: "GET",
+        path: "/api/v1/platform-statistics",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "platform-statistics:read"],
+    },
+    {
+        operationId: "asr.transcribe",
+        method: "POST",
+        path: "/api/v1/asr/transcribe",
+        role: "user",
+        risk: "write",
+        scopes: ["openid", "profile", "asr:write"],
+    },
+    {
+        operationId: "lite.catalog_config.get",
+        method: "GET",
+        path: "/api/v1/lite/catalog-config",
+        role: "user",
+        risk: "read",
+        scopes: ["openid", "profile", "lite:read"],
+    },
+    {
+        operationId: "admin.users.list",
+        method: "GET",
+        path: "/api/v1/admin/users",
+        role: "admin",
+        risk: "read",
+        scopes: ["openid", "profile", "admin:read"],
+    },
+];
+function findCatalogOperation(operationId) {
+    return exports.CATALOG_OPERATIONS.find((op) => op.operationId === operationId);
+}
+function buildCapabilityManifest() {
+    return {
+        contractVersion: exports.CATALOG_VERSION,
+        registryVersion: "1.0.0",
+        operations: exports.CATALOG_OPERATIONS.map((op) => ({
+            operationId: op.operationId,
+            method: op.method,
+            path: op.path,
+            role: op.role,
+            risk: op.risk,
+            scopes: op.scopes,
+            stream: Boolean(op.stream),
+            mvp: Boolean(op.mvp),
+        })),
+    };
+}
+/** Resolve path templates like /api/v1/backtests/{backtestId}. */
+function resolveOperationPath(template, params) {
+    return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, key) => {
+        const value = params[key];
+        if (!value) {
+            throw new Error(`Missing path parameter: ${key}`);
+        }
+        return encodeURIComponent(value);
+    });
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const run_1 = require("./commands/run");
+async function main() {
+    const code = await (0, run_1.runCli)(process.argv.slice(2), process.env);
+    if (typeof code === "number") {
+        process.exit(code);
+    }
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`${JSON.stringify({
+        ok: false,
+        error: { type: "runtime", message },
+    })}\n`);
+    process.exit(1);
+});

package/dist/commands/run.d.ts

@@ -0,0 +1,14 @@
+export interface GlobalFlags {
+    profile?: string;
+    format: "json" | "jsonl" | "text";
+    yes: boolean;
+    dryRun: boolean;
+    noInput: boolean;
+    unsafeCustomEndpoint?: string;
+    jq?: string;
+}
+export declare function parseGlobalFlags(argv: string[]): {
+    flags: GlobalFlags;
+    rest: string[];
+};
+export declare function runCli(argv: string[], env?: NodeJS.ProcessEnv): Promise<number>;