@alphafox/cli 0.1.5 → 0.3.2

package/dist/auth/refresh.js

@@ -1,13 +1,17 @@
 "use strict";
 /**
- * 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.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ACCESS_TOKEN_REFRESH_SKEW_MS = void 0;
 exports.accessTokenNeedsRefresh = accessTokenNeedsRefresh;
 exports.refreshStoredTokens = refreshStoredTokens;
+exports.refreshStoredTokensOrNull = refreshStoredTokensOrNull;
 exports.clearRefreshInflightForTests = clearRefreshInflightForTests;
+const version_1 = require("../version");
 const store_1 = require("../keychain/store");
 /** Refresh when access token expires within this window. */
 exports.ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
@@ -21,16 +25,20 @@ function accessTokenNeedsRefresh(tokens, now = Date.now()) {
 }
 /**
  * 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.
  */
 async function refreshStoredTokens(profile, env = process.env, fetchImpl = fetch, options = {}) {
     const existing = (0, store_1.loadTokens)(profile.name, env);
     if (!existing?.refreshToken?.trim()) {
-        return null;
+        return {
+            status: "no_session",
+            reason: "no_refresh_token",
+            tokens: null,
+        };
     }
     if (!options.force &&
         !accessTokenNeedsRefresh(existing, options.now ?? Date.now())) {
-        return existing;
+        return { status: "unchanged", tokens: existing };
     }
     const key = profile.name;
     const pending = inflightByProfile.get(key);
@@ -43,6 +51,17 @@ async function refreshStoredTokens(profile, env = process.env, fetchImpl = fetch
     inflightByProfile.set(key, work);
     return work;
 }
+/**
+ * Convenience for callers that only need tokens on successful refresh/unchanged.
+ * Returns null for no_session and failed — never pretends failure is success.
+ */
+async function refreshStoredTokensOrNull(profile, env = process.env, fetchImpl = fetch, options = {}) {
+    const outcome = await refreshStoredTokens(profile, env, fetchImpl, options);
+    if (outcome.status === "refreshed" || outcome.status === "unchanged") {
+        return outcome.tokens;
+    }
+    return null;
+}
 async function performRefresh(profile, existing, env, fetchImpl) {
     const origin = profile.apiBaseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
     const url = `${origin}/api/auth/oauth/token`;
@@ -59,27 +78,43 @@ async function performRefresh(profile, existing, env, fetchImpl) {
                 Accept: "application/json",
                 "Content-Type": "application/json",
                 "X-Alphafox-Client": "alphafox-cli",
-                "X-Alphafox-Client-Version": env.ALPHAFOX_CLI_VERSION ?? "0.1.0",
+                "X-Alphafox-Client-Version": env.ALPHAFOX_CLI_VERSION ?? version_1.CLI_VERSION,
             },
             body: JSON.stringify(body),
             redirect: "manual",
         });
     }
-    catch {
-        return null;
+    catch (err) {
+        return {
+            status: "failed",
+            reason: err instanceof Error ? err.message : "network_error",
+            tokens: existing,
+        };
     }
     if (response.status >= 400) {
-        return null;
+        return {
+            status: "failed",
+            reason: `http_${response.status}`,
+            tokens: existing,
+        };
     }
     let json;
     try {
         json = await response.json();
     }
     catch {
-        return null;
+        return {
+            status: "failed",
+            reason: "invalid_json",
+            tokens: existing,
+        };
     }
     if (!json || typeof json !== "object") {
-        return null;
+        return {
+            status: "failed",
+            reason: "invalid_body",
+            tokens: existing,
+        };
     }
     const o = json;
     const access = typeof o.access_token === "string"
@@ -93,16 +128,18 @@ async function performRefresh(profile, existing, env, fetchImpl) {
             ? o.refreshToken
             : null;
     if (!access || !refresh) {
-        return null;
+        return {
+            status: "failed",
+            reason: "missing_tokens",
+            tokens: existing,
+        };
     }
     const expiresIn = typeof o.expires_in === "number"
         ? o.expires_in
         : typeof o.expiresIn === "number"
             ? o.expiresIn
             : 600;
-    const scopeRaw = typeof o.scope === "string"
-        ? o.scope
-        : existing.scopes.join(" ");
+    const scopeRaw = typeof o.scope === "string" ? o.scope : existing.scopes.join(" ");
     const next = {
         accessToken: access,
         refreshToken: refresh,
@@ -114,7 +151,7 @@ async function performRefresh(profile, existing, env, fetchImpl) {
         scopes: scopeRaw.split(/\s+/).filter(Boolean),
     };
     (0, store_1.saveTokens)(profile.name, next, env);
-    return next;
+    return { status: "refreshed", tokens: next };
 }
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 async function fetchFollowingSameSiteRedirects(fetchImpl, startUrl, init, maxHops = 5) {

package/dist/catalog/allowlist.d.ts

@@ -1,9 +1,25 @@
 /**
- * Raw API allowlist + internal path rejection.
- * Mirrors alphafox-contracts public-api allowlist rules.
+ * Raw API allowlist from the generated Operation Registry.
+ * Finite set: infra catalog paths + CLI-included operation facade paths.
+ * Unknown `/api/v1/*` paths are denied — raw API cannot bypass the catalog.
+ */
+/**
+ * Infra paths always allowed (exact, except `/api/v1/operations/*`).
+ * Product routes must match a registry facadePath — no prefix smuggling.
+ */
+export declare const FACILITY_ALWAYS_ALLOW: readonly ["/api/v1/meta", "/api/v1/openapi.json", "/api/v1/openapi", "/api/v1/operations"];
+/**
+ * Normalize API paths for allowlist decisions:
+ * strip query/hash, collapse //, decode %2e-style segments, resolve `.`/`..`.
+ * Escaping above `/` via `..` is clamped at root (POSIX-style).
  */
-/** 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;
+/** Match OpenAPI-style templates: /api/v1/backtests/{backtestId}/cancel */
+export declare function pathTemplateMatches(template: string, actual: string, catchAll?: boolean): boolean;
+/**
+ * Finite allow set: infra catalog paths + generated operation facade paths.
+ * Unknown `/api/v1/*` paths are denied.
+ * Matching always uses the segment-resolved path (no `..` prefix smuggling).
+ */
 export declare function isFacadeAllowlistedPath(path: string, extraAllow?: readonly string[]): boolean;

package/dist/catalog/allowlist.js

@@ -1,13 +1,16 @@
 "use strict";
 /**
- * Raw API allowlist + internal path rejection.
- * Mirrors alphafox-contracts public-api allowlist rules.
+ * Raw API allowlist from the generated Operation Registry.
+ * Finite set: infra catalog paths + CLI-included operation facade paths.
+ * Unknown `/api/v1/*` paths are denied — raw API cannot bypass the catalog.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FACILITY_ALWAYS_ALLOW = void 0;
 exports.normalizeApiPath = normalizeApiPath;
 exports.isInternalDisallowedPath = isInternalDisallowedPath;
+exports.pathTemplateMatches = pathTemplateMatches;
 exports.isFacadeAllowlistedPath = isFacadeAllowlistedPath;
+const operations_1 = require("./operations");
 const INTERNAL_PREFIXES = [
     "/backend",
     "/control-plane",
@@ -16,53 +19,151 @@ const INTERNAL_PREFIXES = [
     "/api/control-plane",
     "/api/signal-center",
 ];
-/** MVP + core facade paths always allowed; full registry embedded for drift tests. */
+/**
+ * Infra paths always allowed (exact, except `/api/v1/operations/*`).
+ * Product routes must match a registry facadePath — no prefix smuggling.
+ */
 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",
+    "/api/v1/openapi",
+    "/api/v1/operations",
 ];
+/**
+ * Decode percent-encoded path segments (up to twice for double-encoding)
+ * without turning encoded slashes into separators mid-segment incorrectly:
+ * each segment is decoded independently so %2F stays inside a segment name.
+ */
+function decodePathSegments(path) {
+    let current = path;
+    for (let pass = 0; pass < 2; pass += 1) {
+        const next = current
+            .split("/")
+            .map((seg) => {
+            if (!seg.includes("%"))
+                return seg;
+            try {
+                return decodeURIComponent(seg);
+            }
+            catch {
+                return seg;
+            }
+        })
+            .join("/");
+        if (next === current)
+            break;
+        current = next;
+    }
+    return current;
+}
+/**
+ * Normalize API paths for allowlist decisions:
+ * strip query/hash, collapse //, decode %2e-style segments, resolve `.`/`..`.
+ * Escaping above `/` via `..` is clamped at root (POSIX-style).
+ */
 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, "/");
+    let raw = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    raw = (raw.split("?")[0] ?? raw).split("#")[0];
+    raw = decodePathSegments(raw);
+    raw = raw.replace(/\/{2,}/g, "/");
+    const resolved = [];
+    for (const seg of raw.split("/")) {
+        if (seg === "" || seg === ".") {
+            continue;
+        }
+        if (seg === "..") {
+            if (resolved.length > 0) {
+                resolved.pop();
+            }
+            continue;
+        }
+        if (seg.includes("\0") || seg.includes("\\")) {
+            return "/";
+        }
+        resolved.push(seg);
+    }
+    return resolved.length === 0 ? "/" : `/${resolved.join("/")}`;
 }
 function isInternalDisallowedPath(path) {
     const n = normalizeApiPath(path);
     return INTERNAL_PREFIXES.some((p) => n === p || n.startsWith(`${p}/`) || n.includes(`${p}/`));
 }
+/** Match OpenAPI-style templates: /api/v1/backtests/{backtestId}/cancel */
+function pathTemplateMatches(template, actual, catchAll = false) {
+    const t = normalizeApiPath(template).split("/").filter(Boolean);
+    const a = normalizeApiPath(actual).split("/").filter(Boolean);
+    if (catchAll) {
+        if (a.length < t.length)
+            return false;
+        for (let i = 0; i < t.length; i += 1) {
+            const seg = t[i];
+            if (seg.startsWith("{") && seg.endsWith("}"))
+                continue;
+            if (seg !== a[i])
+                return false;
+        }
+        return true;
+    }
+    if (t.length !== a.length)
+        return false;
+    for (let i = 0; i < t.length; i += 1) {
+        const seg = t[i];
+        if (seg.startsWith("{") && seg.endsWith("}"))
+            continue;
+        if (seg !== a[i])
+            return false;
+    }
+    return true;
+}
+function isInfraAllowlisted(n) {
+    if (n === "/api/v1/meta" ||
+        n === "/api/v1/openapi.json" ||
+        n === "/api/v1/openapi" ||
+        n === "/api/v1/operations" ||
+        n.startsWith("/api/v1/operations/")) {
+        return true;
+    }
+    return false;
+}
+function isCatalogPathMatch(n) {
+    for (const op of operations_1.CATALOG_OPERATIONS) {
+        if (pathTemplateMatches(op.path, n, Boolean(op.catchAll))) {
+            return true;
+        }
+    }
+    return false;
+}
+function isExtraAllowMatch(n, extraAllow) {
+    for (const a of extraAllow) {
+        if (n === a || n.startsWith(`${a}/`) || pathTemplateMatches(a, n)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Finite allow set: infra catalog paths + generated operation facade paths.
+ * Unknown `/api/v1/*` paths are denied.
+ * Matching always uses the segment-resolved path (no `..` prefix smuggling).
+ */
 function isFacadeAllowlistedPath(path, extraAllow = []) {
     const n = normalizeApiPath(path);
     if (isInternalDisallowedPath(n)) {
         return false;
     }
-    if (!n.startsWith("/api/v1")) {
+    if (n !== "/api/v1" && !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)) {
+    if (isInfraAllowlisted(n)) {
         return true;
     }
-    if (/^\/api\/v1\/trading\/traders\/[^/]+(\/.*)?$/.test(n)) {
+    if (isExtraAllowMatch(n, extraAllow)) {
         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.
+    if (isCatalogPathMatch(n)) {
         return true;
     }
     return false;

package/dist/catalog/command-tree.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Typed command tree derived from registry operationIds.
+ * Shortcuts may only compose operationIds — never a second schema catalog.
+ */
+import { type CatalogOperation } from "./operations";
+export declare function splitCommandTokens(tokens: readonly string[]): {
+    readonly commandTokens: string[];
+    readonly flagArgs: string[];
+    readonly help: boolean;
+};
+export declare function operationsWithPrefix(prefix: string): CatalogOperation[];
+export type TypedResolution = {
+    readonly kind: "operation";
+    readonly operation: CatalogOperation;
+    readonly flagArgs: string[];
+    readonly help: boolean;
+} | {
+    readonly kind: "help";
+    readonly prefix: string;
+    readonly operations: readonly CatalogOperation[];
+    readonly flagArgs: string[];
+} | {
+    readonly kind: "ambiguous";
+    readonly prefix: string;
+    readonly candidates: readonly string[];
+} | {
+    readonly kind: "missing";
+    readonly prefix: string;
+};
+export declare function resolveTypedCommand(tokens: readonly string[]): TypedResolution;
+export declare function typedCommandExample(op: CatalogOperation): {
+    readonly typed: string;
+    readonly api: string;
+    readonly config?: string;
+};

package/dist/catalog/command-tree.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Typed command tree derived from registry operationIds.
+ * Shortcuts may only compose operationIds — never a second schema catalog.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitCommandTokens = splitCommandTokens;
+exports.operationsWithPrefix = operationsWithPrefix;
+exports.resolveTypedCommand = resolveTypedCommand;
+exports.typedCommandExample = typedCommandExample;
+const operations_1 = require("./operations");
+function hyphenToUnderscore(token) {
+    return token.replace(/-/g, "_");
+}
+function splitCommandTokens(tokens) {
+    const commandTokens = [];
+    const flagArgs = [];
+    let help = false;
+    let inFlags = false;
+    for (const token of tokens) {
+        if (!inFlags && (token === "--help" || token === "-h")) {
+            help = true;
+            continue;
+        }
+        if (!inFlags && token.startsWith("--")) {
+            inFlags = true;
+        }
+        if (inFlags) {
+            flagArgs.push(token);
+        }
+        else {
+            commandTokens.push(token);
+        }
+    }
+    return { commandTokens, flagArgs, help };
+}
+function lookupId(id) {
+    return ((0, operations_1.findCatalogOperation)(id) ??
+        (0, operations_1.findCatalogOperation)(hyphenToUnderscore(id)));
+}
+function operationsWithPrefix(prefix) {
+    const norm = hyphenToUnderscore(prefix);
+    return operations_1.CATALOG_OPERATIONS.filter((op) => op.operationId === norm || op.operationId.startsWith(`${norm}.`));
+}
+function uniqueSuffixMatch(tokens) {
+    if (tokens.length < 2)
+        return [];
+    const domain = hyphenToUnderscore(tokens[0]);
+    const action = hyphenToUnderscore(tokens[tokens.length - 1]);
+    const middle = tokens.slice(1, -1).map(hyphenToUnderscore);
+    return operations_1.CATALOG_OPERATIONS.filter((op) => {
+        if (!op.operationId.startsWith(`${domain}.`))
+            return false;
+        if (!op.operationId.endsWith(`.${action}`) && op.operationId !== action) {
+            return false;
+        }
+        for (const part of middle) {
+            if (!op.operationId.includes(`.${part}.`) && !op.operationId.includes(`${part}.`)) {
+                return false;
+            }
+        }
+        return true;
+    });
+}
+function resolveTypedCommand(tokens) {
+    const { commandTokens, flagArgs, help } = splitCommandTokens(tokens);
+    if (commandTokens.length === 0) {
+        return { kind: "missing", prefix: "" };
+    }
+    const joined = commandTokens.join(".");
+    const exact = lookupId(joined);
+    if (exact) {
+        return { kind: "operation", operation: exact, flagArgs, help };
+    }
+    const suffixHits = uniqueSuffixMatch(commandTokens);
+    if (suffixHits.length === 1) {
+        return {
+            kind: "operation",
+            operation: suffixHits[0],
+            flagArgs,
+            help,
+        };
+    }
+    if (suffixHits.length > 1) {
+        return {
+            kind: "ambiguous",
+            prefix: joined,
+            candidates: suffixHits.map((op) => op.operationId),
+        };
+    }
+    const prefixOps = operationsWithPrefix(joined);
+    if (prefixOps.length > 0) {
+        return {
+            kind: "help",
+            prefix: hyphenToUnderscore(joined),
+            operations: prefixOps,
+            flagArgs,
+        };
+    }
+    return { kind: "missing", prefix: joined };
+}
+function typedCommandExample(op) {
+    const segments = op.operationId.split(".");
+    const schemaNames = op.path.match(/\{([a-zA-Z0-9_]+)\}/g)?.map((s) => s.slice(1, -1)) ?? [];
+    const pathFlags = schemaNames.map((name) => `--${name} <${name}>`).join(" ");
+    const riskFlag = op.risk === "high-risk-write" || op.risk === "unknown" ? " --yes" : "";
+    const writesBody = op.method !== "GET" && op.method !== "HEAD" && op.method !== "DELETE";
+    const bodyFlag = writesBody ? " --body '{…}'" : "";
+    const typedFlags = [pathFlags, bodyFlag.trim(), riskFlag.trim()]
+        .filter(Boolean)
+        .join(" ");
+    return {
+        typed: `alphafox ${segments.join(" ")}${typedFlags ? ` ${typedFlags}` : ""}`,
+        api: `alphafox api ${op.method} ${op.path}${bodyFlag}${riskFlag}`,
+        config: writesBody
+            ? `alphafox ${segments.join(" ")} --config @./${op.operationId}.json${riskFlag}`
+            : undefined,
+    };
+}

package/dist/catalog/compatibility.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Equivalent of `@alphafoxai/contracts/public-api` `checkCliCompatibility`.
+ * Fail closed on CLI/contract version skew. Do not invent a second range:
+ * callers must pass the generated registry compatibility block.
+ */
+export interface CompatibilityRange {
+    readonly contractVersion: string;
+    readonly registryVersion: string;
+    readonly minCliVersion: string;
+    readonly maxCliVersion: string;
+    readonly openapi: string;
+}
+export type CompatibilityResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly code: "cli_too_old" | "cli_too_new" | "contract_mismatch" | "invalid_version";
+    readonly message: string;
+};
+export declare function checkCliCompatibility(input: {
+    readonly cliVersion: string;
+    readonly contractVersion: string;
+}, range: CompatibilityRange): CompatibilityResult;

package/dist/catalog/compatibility.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Equivalent of `@alphafoxai/contracts/public-api` `checkCliCompatibility`.
+ * Fail closed on CLI/contract version skew. Do not invent a second range:
+ * callers must pass the generated registry compatibility block.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCliCompatibility = checkCliCompatibility;
+function parseSemver(raw) {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(raw.trim());
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+function cmpSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb)
+        return null;
+    for (let i = 0; i < 3; i += 1) {
+        if (pa[i] !== pb[i])
+            return pa[i] - pb[i];
+    }
+    return 0;
+}
+function checkCliCompatibility(input, range) {
+    const cliVsMin = cmpSemver(input.cliVersion, range.minCliVersion);
+    const cliVsMax = cmpSemver(input.cliVersion, range.maxCliVersion);
+    if (cliVsMin === null || cliVsMax === null) {
+        return {
+            ok: false,
+            code: "invalid_version",
+            message: `CLI version ${input.cliVersion} is not valid semver (expected MAJOR.MINOR.PATCH).`,
+        };
+    }
+    if (cliVsMin < 0) {
+        return {
+            ok: false,
+            code: "cli_too_old",
+            message: `CLI ${input.cliVersion} is older than minCliVersion ${range.minCliVersion} for contract ${range.contractVersion}.`,
+        };
+    }
+    if (cliVsMax > 0) {
+        return {
+            ok: false,
+            code: "cli_too_new",
+            message: `CLI ${input.cliVersion} is newer than maxCliVersion ${range.maxCliVersion} for contract ${range.contractVersion}.`,
+        };
+    }
+    if (input.contractVersion !== range.contractVersion) {
+        return {
+            ok: false,
+            code: "contract_mismatch",
+            message: `Server contractVersion ${input.contractVersion} does not match CLI catalog ${range.contractVersion}.`,
+        };
+    }
+    return { ok: true };
+}