@alphafox/cli 0.1.5 → 0.2.0

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,34 @@
+/**
+ * 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;
+};

package/dist/catalog/command-tree.js

@@ -0,0 +1,117 @@
+"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 bodyFlag = op.method !== "GET" && op.method !== "HEAD" && op.method !== "DELETE"
+        ? " --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}`,
+    };
+}

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 };
+}