@alphafox/cli 0.1.5 → 0.3.2

package/dist/commands/run.js

@@ -1,49 +1,23 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseGlobalFlags = parseGlobalFlags;
 exports.runCli = runCli;
 const node_crypto_1 = require("node:crypto");
 const operations_1 = require("../catalog/operations");
+const command_tree_1 = require("../catalog/command-tree");
 const allowlist_1 = require("../catalog/allowlist");
 const profiles_1 = require("../config/profiles");
 const envelope_1 = require("../envelope");
+const browser_login_1 = require("../auth/browser-login");
 const client_1 = require("../http/client");
 const store_1 = require("../keychain/store");
 const confirmation_1 = require("../safety/confirmation");
 const version_1 = require("../version");
+const run_command_1 = require("../engine-backtest/run-command");
+const validate_body_1 = require("../catalog/validate-body");
+const types_1 = require("../install/types");
+const wizard_1 = require("../install/wizard");
+const request_body_1 = require("./request-body");
 function parseGlobalFlags(argv) {
     const flags = {
         format: "json",
@@ -94,6 +68,14 @@ function parseGlobalFlags(argv) {
     return { flags, rest };
 }
 async function runCli(argv, env = process.env) {
+    if (argv.some((a) => a === "--token" || a.startsWith("--token="))) {
+        (0, envelope_1.writeError)({
+            type: "usage",
+            subtype: "token_argv_forbidden",
+            message: "Refusing --token on argv. Store credentials in the OS keychain via alphafox auth login.",
+            hint: "Automation tokens are not supported in v1. Do not copy refresh tokens into CI.",
+        });
+    }
     const { flags, rest } = parseGlobalFlags(argv);
     const [cmd, ...args] = rest;
     if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
@@ -102,22 +84,30 @@ async function runCli(argv, env = process.env) {
             usage: [
                 "alphafox version",
                 "alphafox doctor",
+                "alphafox install [--no-auth|--dry-run]",
                 "alphafox auth login [--no-wait|--device-code CODE|--browser]",
                 "alphafox auth status [--verify]",
                 "alphafox auth logout",
                 "alphafox whoami",
                 "alphafox profile list|use <name>",
                 "alphafox schema [operationId]",
-                "alphafox api METHOD PATH [--body JSON]",
+                "alphafox catalog",
+                "alphafox api METHOD PATH [--body JSON|--config @file]",
+                "alphafox engine-backtest run --experiment <uuid> --definition <id> --config @file --exchange <id> --range FROM..TO --initial-equity N",
                 "alphafox <domain> <resource> <action> [flags]",
             ],
-        }, { format: flags.format });
+        }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     try {
+        if (cmd !== "version" && cmd !== "install") {
+            assertCatalogCompatible();
+        }
         switch (cmd) {
             case "version":
                 return cmdVersion(flags);
+            case "install":
+                return await cmdInstall(args, flags, env);
             case "doctor":
                 return cmdDoctor(flags, env);
             case "whoami":
@@ -132,6 +122,19 @@ async function runCli(argv, env = process.env) {
                 return await cmdApi(args, flags, env);
             case "catalog":
                 return cmdCatalog(flags);
+            case "engine-backtest": {
+                const sub = args[0];
+                if (!sub ||
+                    sub === "run" ||
+                    sub === "help" ||
+                    sub === "--help" ||
+                    sub === "-h") {
+                    return await (0, run_command_1.cmdEngineBacktest)(args, flags, env);
+                }
+                // Hyphen built-in only owns `run`. Underscore/hyphen catalog CRUD
+                // (engine_backtest.experiments.*) still goes through the typed tree.
+                return await cmdTyped(cmd, args, flags, env);
+            }
             default:
                 return await cmdTyped(cmd, args, flags, env);
         }
@@ -154,18 +157,76 @@ async function runCli(argv, env = process.env) {
         }, { exitCode: status === 401 || status === 403 ? 77 : 1 });
     }
 }
+function assertCatalogCompatible() {
+    const result = (0, operations_1.checkGeneratedCatalogCompatibility)(version_1.CLI_VERSION);
+    if (result.ok)
+        return;
+    (0, envelope_1.writeError)({
+        type: "compatibility",
+        subtype: result.code,
+        message: result.message,
+        hint: "Upgrade or pin @alphafox/cli to the catalog minCliVersion/maxCliVersion range.",
+    });
+}
+async function cmdInstall(args, flags, env) {
+    const parsed = (0, wizard_1.parseInstallArgs)(args);
+    if (parsed.unknown.length > 0) {
+        (0, envelope_1.writeError)({
+            type: "usage",
+            subtype: "unknown_install_flag",
+            message: `Unknown install flag: ${parsed.unknown.join(" ")}`,
+            hint: "Usage: alphafox install [--no-auth] [--dry-run]",
+        });
+    }
+    if (parsed.help) {
+        (0, envelope_1.writeSuccess)((0, wizard_1.installHelpData)(), { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    try {
+        const data = await (0, wizard_1.runInstallWizard)({
+            format: flags.format,
+            yes: flags.yes,
+            dryRun: flags.dryRun,
+            noInput: flags.noInput,
+            jq: flags.jq,
+            noAuth: parsed.noAuth,
+            help: false,
+        }, env);
+        (0, envelope_1.writeSuccess)(data, { format: flags.format, jq: flags.jq });
+        return data.auth.action === "failed" ? 1 : 0;
+    }
+    catch (err) {
+        if ((0, types_1.isInstallError)(err)) {
+            (0, envelope_1.writeError)({
+                type: err.type,
+                subtype: err.subtype,
+                message: err.message,
+                hint: err.hint,
+                details: err.details,
+            });
+        }
+        throw err;
+    }
+}
 function cmdVersion(flags) {
+    const compatibility = (0, operations_1.checkGeneratedCatalogCompatibility)(version_1.CLI_VERSION);
     (0, envelope_1.writeSuccess)({
         name: version_1.CLI_NAME,
         package: version_1.CLI_PACKAGE,
         version: version_1.CLI_VERSION,
         contractVersion: version_1.CLI_CONTRACT_VERSION,
         catalogVersion: operations_1.CATALOG_VERSION,
+        registryVersion: operations_1.COMPATIBILITY_RANGE.registryVersion,
+        minCliVersion: operations_1.COMPATIBILITY_RANGE.minCliVersion,
+        maxCliVersion: operations_1.COMPATIBILITY_RANGE.maxCliVersion,
+        openapi: operations_1.COMPATIBILITY_RANGE.openapi,
+        contractsSha: operations_1.CATALOG_SOURCE.contractsSha,
+        compatibility,
         node: process.version,
         platform: process.platform,
         arch: process.arch,
-    }, { format: flags.format });
-    return 0;
+    }, { format: flags.format, jq: flags.jq });
+    return compatibility.ok ? 0 : 1;
 }
 function cmdDoctor(flags, env) {
     const profile = (0, profiles_1.resolveProfile)(flags.profile, env, {
@@ -174,6 +235,7 @@ function cmdDoctor(flags, env) {
     // Avoid macOS `security` stderr noise when no item exists; file keychain is fine for doctor.
     const doctorEnv = { ...env, ALPHAFOX_FORCE_FILE_KEYCHAIN: env.ALPHAFOX_FORCE_FILE_KEYCHAIN ?? "1" };
     const tokens = (0, store_1.loadTokens)(profile.name, doctorEnv);
+    const probe = (0, store_1.probeOsKeychain)(env);
     const checks = [
         {
             name: "node",
@@ -202,6 +264,13 @@ function cmdDoctor(flags, env) {
                 ? `token present (fp=${(0, store_1.tokenFingerprint)(tokens.accessToken)})`
                 : "no tokens stored",
         },
+        {
+            name: "osKeychain",
+            ok: true,
+            detail: probe.available
+                ? probe.kind
+                : `${probe.kind} unavailable; file fallback (0600) if tokens are saved`,
+        },
         {
             name: "configHasNoTokens",
             ok: true,
@@ -212,9 +281,14 @@ function cmdDoctor(flags, env) {
             ok: true,
             detail: "v1 deferred (interactive login only)",
         },
+        {
+            name: "catalogCompatibility",
+            ok: (0, operations_1.checkGeneratedCatalogCompatibility)(version_1.CLI_VERSION).ok,
+            detail: `${version_1.CLI_VERSION} in [${operations_1.COMPATIBILITY_RANGE.minCliVersion}, ${operations_1.COMPATIBILITY_RANGE.maxCliVersion}] contract ${operations_1.COMPATIBILITY_RANGE.contractVersion}`,
+        },
     ];
     const ok = checks.every((c) => c.ok);
-    (0, envelope_1.writeSuccess)({ ok, profile: profile.name, checks }, { format: flags.format });
+    (0, envelope_1.writeSuccess)({ ok, profile: profile.name, checks }, { format: flags.format, jq: flags.jq });
     return ok ? 0 : 1;
 }
 async function cmdWhoami(flags, env) {
@@ -236,7 +310,7 @@ async function cmdWhoami(flags, env) {
             code: extractErrorCode(res.json),
         }, { requestId: res.requestId, exitCode: res.status === 401 ? 77 : 1 });
     }
-    (0, envelope_1.writeSuccess)(res.json, { requestId: res.requestId, format: flags.format });
+    (0, envelope_1.writeSuccess)(res.json, { requestId: res.requestId, format: flags.format, jq: flags.jq });
     return 0;
 }
 async function cmdAuth(args, flags, env) {
@@ -252,7 +326,7 @@ async function cmdAuth(args, flags, env) {
                 authenticated: false,
                 profile: profile.name,
                 verified: false,
-            }, { format: flags.format });
+            }, { format: flags.format, jq: flags.jq });
             return 0;
         }
         let verified = null;
@@ -278,14 +352,15 @@ async function cmdAuth(args, flags, env) {
             expiresAt: tokens.expiresAt,
             verified,
             whoami,
-        }, { format: flags.format });
+        }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     if (sub === "logout") {
         const tokens = (0, store_1.loadTokens)(profile.name, env);
+        let remoteRevoke = "skipped";
         if (tokens?.refreshToken) {
             try {
-                await (0, client_1.apiRequest)({
+                const res = await (0, client_1.apiRequest)({
                     method: "POST",
                     path: "/api/auth/oauth/revoke",
                     profile,
@@ -295,14 +370,26 @@ async function cmdAuth(args, flags, env) {
                     },
                     skipAuth: false,
                 }, env);
+                remoteRevoke =
+                    res.status >= 200 && res.status < 300 ? "ok" : "failed";
             }
             catch {
-                // still clear local
+                remoteRevoke = "failed";
             }
         }
         (0, store_1.deleteTokens)(profile.name, env);
-        (0, envelope_1.writeSuccess)({ loggedOut: true, profile: profile.name }, { format: flags.format });
-        return 0;
+        const localCleared = true;
+        const fullyLoggedOut = remoteRevoke !== "failed";
+        // Never claim a clean remote logout when revoke failed while an RT was present.
+        (0, envelope_1.writeSuccess)({
+            localCleared,
+            remoteRevoke,
+            fullyLoggedOut,
+            // retained for compatibility; false when remote revoke failed
+            loggedOut: fullyLoggedOut,
+            profile: profile.name,
+        }, { format: flags.format, jq: flags.jq });
+        return fullyLoggedOut ? 0 : 1;
     }
     if (sub === "login") {
         return await cmdAuthLogin(args.slice(1), flags, env, profile);
@@ -370,7 +457,7 @@ async function cmdAuthLogin(args, flags, env, profile) {
             profile: profile.name,
             accessTokenFingerprint: (0, store_1.tokenFingerprint)(tokens.access_token),
             expiresIn: tokens.expires_in,
-        }, { format: flags.format, requestId: res.requestId });
+        }, { format: flags.format, jq: flags.jq, requestId: res.requestId });
         return 0;
     }
     if (deviceCode) {
@@ -389,7 +476,7 @@ async function cmdAuthLogin(args, flags, env, profile) {
             (0, envelope_1.writeSuccess)({
                 status: "authorization_pending",
                 profile: profile.name,
-            }, { format: flags.format, requestId: res.requestId });
+            }, { format: flags.format, jq: flags.jq, requestId: res.requestId });
             return 0;
         }
         if (res.status >= 400) {
@@ -415,7 +502,7 @@ async function cmdAuthLogin(args, flags, env, profile) {
             profile: profile.name,
             accessTokenFingerprint: (0, store_1.tokenFingerprint)(tokens.access_token),
             expiresIn: tokens.expires_in,
-        }, { format: flags.format, requestId: res.requestId });
+        }, { format: flags.format, jq: flags.jq, requestId: res.requestId });
         return 0;
     }
     // Start device flow (default headless path)
@@ -448,7 +535,7 @@ async function cmdAuthLogin(args, flags, env, profile) {
             expires_in: data.expires_in,
             interval: data.interval,
             next: "Open verification_uri, approve, then: alphafox auth login --device-code <device_code>",
-        }, { format: flags.format, requestId: res.requestId });
+        }, { format: flags.format, jq: flags.jq, requestId: res.requestId });
         if (noWait) {
             return 0;
         }
@@ -494,7 +581,7 @@ async function cmdAuthLogin(args, flags, env, profile) {
                 authenticated: true,
                 profile: profile.name,
                 accessTokenFingerprint: (0, store_1.tokenFingerprint)(tokens.access_token),
-            }, { format: flags.format, requestId: poll.requestId });
+            }, { format: flags.format, jq: flags.jq, requestId: poll.requestId });
             return 0;
         }
         (0, envelope_1.writeError)({
@@ -503,36 +590,34 @@ async function cmdAuthLogin(args, flags, env, profile) {
             subtype: "expired_token",
         });
     }
-    // Browser Authorization Code + PKCE (RFC 7636 S256)
+    // Browser Authorization Code + PKCE with loopback callback (RFC 8252).
     if (browser || args.includes("--pkce")) {
-        const { createHash, randomBytes } = await Promise.resolve().then(() => __importStar(require("node:crypto")));
-        const state = (0, node_crypto_1.randomUUID)();
-        const codeVerifier = randomBytes(32).toString("base64url");
-        const codeChallenge = createHash("sha256")
-            .update(codeVerifier, "utf8")
-            .digest("base64url");
-        const redirectUri = redirectUriArg;
-        const authorize = new URL(`${profile.issuer}/oauth/authorize`);
-        authorize.searchParams.set("response_type", "code");
-        authorize.searchParams.set("client_id", profile.clientId);
-        authorize.searchParams.set("redirect_uri", redirectUri);
-        authorize.searchParams.set("code_challenge", codeChallenge);
-        authorize.searchParams.set("code_challenge_method", "S256");
-        authorize.searchParams.set("state", state);
-        authorize.searchParams.set("scope", "openid profile offline_access");
+        const result = await (0, browser_login_1.runBrowserPkceLogin)({
+            profile,
+            env,
+            timeoutMs: (0, browser_login_1.browserLoginTimeoutMs)(env),
+            openBrowser: (0, browser_login_1.resolveOpenBrowser)(env),
+        });
+        if (result.status !== "authenticated") {
+            (0, envelope_1.writeError)({
+                type: "auth",
+                subtype: result.reason,
+                message: result.message,
+                details: result.authorizeUrl
+                    ? { authorizeUrl: result.authorizeUrl }
+                    : undefined,
+                hint: result.authorizeUrl
+                    ? "Copy authorizeUrl into a browser, or use Device Flow: alphafox auth login --no-wait"
+                    : undefined,
+            });
+        }
         (0, envelope_1.writeSuccess)({
+            authenticated: true,
             flow: "authorization_code_pkce",
             profile: profile.name,
-            authorizeUrl: authorize.toString(),
-            redirect_uri: redirectUri,
-            state,
-            code_challenge: codeChallenge,
-            code_challenge_method: "S256",
-            // Required for the follow-up exchange; store securely (not in config).
-            code_verifier: codeVerifier,
-            next: `After browser redirect: alphafox auth login --code <code> --code-verifier ${codeVerifier} --redirect-uri ${redirectUri}`,
-            note: "Sign in at authorizeUrl if prompted. Prefer Device Flow for headless agents.",
-        }, { format: flags.format });
+            accessTokenFingerprint: result.accessTokenFingerprint,
+            expiresIn: result.expiresIn,
+        }, { format: flags.format, jq: flags.jq, requestId: result.requestId });
         return 0;
     }
     (0, envelope_1.writeError)({
@@ -547,7 +632,7 @@ function cmdProfile(args, flags, env) {
         (0, envelope_1.writeSuccess)({
             activeProfile: file.activeProfile,
             profiles: ["production", "staging", "local"].map((name) => (0, profiles_1.resolveProfile)(name, env)),
-        }, { format: flags.format });
+        }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     if (sub === "use") {
@@ -560,7 +645,7 @@ function cmdProfile(args, flags, env) {
         }
         const file = (0, profiles_1.loadConfigFile)(env);
         (0, profiles_1.saveConfigFile)({ ...file, activeProfile: name }, env);
-        (0, envelope_1.writeSuccess)({ activeProfile: name }, { format: flags.format });
+        (0, envelope_1.writeSuccess)({ activeProfile: name }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     (0, envelope_1.writeError)({ type: "usage", message: "Usage: alphafox profile list|use" });
@@ -570,12 +655,17 @@ function cmdSchema(args, flags) {
     if (!operationId) {
         (0, envelope_1.writeSuccess)({
             contractVersion: operations_1.CATALOG_VERSION,
+            registryVersion: operations_1.COMPATIBILITY_RANGE.registryVersion,
+            openapi: operations_1.COMPATIBILITY_RANGE.openapi,
+            minCliVersion: operations_1.COMPATIBILITY_RANGE.minCliVersion,
+            maxCliVersion: operations_1.COMPATIBILITY_RANGE.maxCliVersion,
             operations: operations_1.CATALOG_OPERATIONS.map((o) => o.operationId),
-        }, { format: flags.format });
+        }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     const op = (0, operations_1.findCatalogOperation)(operationId);
-    if (!op) {
+    const schema = (0, operations_1.getOperationSchemaDocument)(operationId);
+    if (!op || !schema) {
         (0, envelope_1.writeError)({
             type: "not_found",
             message: `Unknown operationId: ${operationId}`,
@@ -583,26 +673,13 @@ function cmdSchema(args, flags) {
         });
     }
     (0, envelope_1.writeSuccess)({
-        operationId: op.operationId,
-        method: op.method,
-        path: op.path,
-        role: op.role,
-        risk: op.risk,
-        scopes: op.scopes,
-        stream: op.stream ?? false,
-        mvp: op.mvp ?? false,
-        description: op.description,
-        input: {
-            type: "object",
-            note: "See OpenAPI at GET /api/v1/openapi.json and alphafox-contracts Zod schemas",
-        },
-        output: { type: "object" },
-        errors: ["401", "403", "404", "409", "422", "429", "5xx"],
-    }, { format: flags.format });
+        ...schema,
+        examples: (0, command_tree_1.typedCommandExample)(op),
+    }, { format: flags.format, jq: flags.jq });
     return 0;
 }
 function cmdCatalog(flags) {
-    (0, envelope_1.writeSuccess)((0, operations_1.buildCapabilityManifest)(), { format: flags.format });
+    (0, envelope_1.writeSuccess)((0, operations_1.buildCapabilityManifest)(), { format: flags.format, jq: flags.jq });
     return 0;
 }
 async function cmdApi(args, flags, env) {
@@ -611,7 +688,7 @@ async function cmdApi(args, flags, env) {
     if (!method || !path) {
         (0, envelope_1.writeError)({
             type: "usage",
-            message: "Usage: alphafox api METHOD PATH [--body JSON]",
+            message: "Usage: alphafox api METHOD PATH [--body JSON|--config @file]",
         });
     }
     if ((0, allowlist_1.isInternalDisallowedPath)(path) || !(0, allowlist_1.isFacadeAllowlistedPath)(path)) {
@@ -623,26 +700,44 @@ async function cmdApi(args, flags, env) {
         }, { exitCode: 77 });
     }
     let body;
-    const bodyIdx = args.indexOf("--body");
-    if (bodyIdx >= 0) {
-        body = JSON.parse(args[bodyIdx + 1] ?? "{}");
+    try {
+        body = (0, request_body_1.parseRequestBodyFlags)(args).body;
+    }
+    catch (err) {
+        if ((0, request_body_1.isRequestBodyError)(err)) {
+            (0, envelope_1.writeError)({
+                type: err.type,
+                subtype: err.subtype,
+                message: err.message,
+                hint: err.hint,
+            });
+        }
+        throw err;
     }
     const profile = (0, profiles_1.resolveProfile)(flags.profile, env, {
         unsafeCustomEndpoint: flags.unsafeCustomEndpoint,
     });
-    // Infer risk from catalog if possible
-    const catalogHit = operations_1.CATALOG_OPERATIONS.find((o) => o.method === method && pathMatches(o.path, path));
-    if (catalogHit) {
-        const gate = (0, confirmation_1.assertHighRiskConfirmation)({
-            risk: catalogHit.risk,
-            yes: flags.yes,
-            dryRun: flags.dryRun,
-            action: `api ${method} ${path}`,
-        });
-        if (!gate.allowed && gate.error) {
-            process.stderr.write(`${JSON.stringify((0, envelope_1.errorEnvelope)(gate.error))}\n`);
-            return 10;
-        }
+    // Infer risk from catalog; uncataloged mutations are treated as high-risk.
+    const catalogHit = (0, operations_1.findCatalogOperationByRoute)(method, (0, allowlist_1.normalizeApiPath)(path));
+    const validated = (0, validate_body_1.validateCatalogWriteBody)({
+        method,
+        operationId: catalogHit?.operationId,
+        body,
+    });
+    if (!validated.ok) {
+        (0, envelope_1.writeError)(validated.error);
+    }
+    body = validated.body;
+    const risk = (0, confirmation_1.inferRawApiRisk)(method, catalogHit?.risk);
+    const gate = (0, confirmation_1.assertHighRiskConfirmation)({
+        risk,
+        yes: flags.yes,
+        dryRun: flags.dryRun,
+        action: `api ${method} ${path}`,
+    });
+    if (!gate.allowed && gate.error) {
+        process.stderr.write(`${JSON.stringify((0, envelope_1.errorEnvelope)(gate.error))}\n`);
+        return 10;
     }
     if (flags.dryRun) {
         (0, envelope_1.writeSuccess)({
@@ -650,8 +745,10 @@ async function cmdApi(args, flags, env) {
             method,
             path,
             profile: profile.name,
-            risk: catalogHit?.risk ?? "unknown",
-        }, { format: flags.format });
+            risk,
+            operationId: catalogHit?.operationId,
+            body,
+        }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     const res = await (0, client_1.apiRequest)({
@@ -669,44 +766,47 @@ async function cmdApi(args, flags, env) {
             code: extractErrorCode(res.json),
         }, { requestId: res.requestId, exitCode: res.status === 401 ? 77 : 1 });
     }
-    (0, envelope_1.writeSuccess)(res.json, { requestId: res.requestId, format: flags.format });
+    (0, envelope_1.writeSuccess)(res.json, { requestId: res.requestId, format: flags.format, jq: flags.jq });
     return 0;
 }
 async function cmdTyped(domain, args, flags, env) {
-    // alphafox trading traders list
-    // alphafox chats create --body ...
-    const resource = args[0];
-    const action = args[1];
-    if (!resource || !action) {
-        // try domain as operationId
-        const asOp = (0, operations_1.findCatalogOperation)(domain);
-        if (asOp) {
-            return await invokeOperation(asOp.operationId, args, flags, env);
-        }
+    const resolved = (0, command_tree_1.resolveTypedCommand)([domain, ...args]);
+    if (resolved.kind === "help") {
+        (0, envelope_1.writeSuccess)({
+            prefix: resolved.prefix,
+            operations: resolved.operations.map((op) => ({
+                operationId: op.operationId,
+                method: op.method,
+                path: op.path,
+                risk: op.risk,
+                scopes: op.scopes,
+                stream: Boolean(op.stream),
+                file: Boolean(op.file),
+                pagination: Boolean(op.pagination),
+                examples: (0, command_tree_1.typedCommandExample)(op),
+            })),
+        }, { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    if (resolved.kind === "ambiguous") {
         (0, envelope_1.writeError)({
             type: "usage",
-            message: `Unknown command "${domain}". Try alphafox schema or alphafox catalog.`,
+            message: `Ambiguous command "${resolved.prefix}"`,
+            hint: `Matches: ${resolved.candidates.join(", ")}`,
         });
     }
-    const candidates = operations_1.CATALOG_OPERATIONS.filter((o) => {
-        const parts = o.operationId.split(".");
-        return (parts[0]?.replace(/_/g, "-") === domain.replace(/_/g, "-") ||
-            o.operationId.startsWith(domain.replace(/-/g, "_")));
-    });
-    const op = candidates.find((o) => o.operationId.endsWith(`.${action}`) ||
-        o.operationId.includes(`.${resource}.`) &&
-            o.operationId.endsWith(action)) ||
-        (0, operations_1.findCatalogOperation)(`${domain}.${resource}.${action}`) ||
-        (0, operations_1.findCatalogOperation)(`${domain.replace(/-/g, "_")}.${resource.replace(/-/g, "_")}.${action}`);
-    if (!op) {
+    if (resolved.kind === "missing") {
         (0, envelope_1.writeError)({
             type: "not_found",
-            message: `No catalog operation for ${domain} ${resource} ${action}`,
+            message: `No catalog operation for ${resolved.prefix || domain}`,
             status: 404,
             hint: "Run alphafox schema for operationIds",
         });
     }
-    return await invokeOperation(op.operationId, args.slice(2), flags, env);
+    if (resolved.help) {
+        return cmdSchema([resolved.operation.operationId], flags);
+    }
+    return await invokeOperation(resolved.operation.operationId, resolved.flagArgs, flags, env);
 }
 async function invokeOperation(operationId, args, flags, env) {
     const op = (0, operations_1.findCatalogOperation)(operationId);
@@ -728,19 +828,52 @@ async function invokeOperation(operationId, args, flags, env) {
         return 10;
     }
     const params = {};
+    const extra = {};
+    const pathParamNames = new Set((0, operations_1.getOperationSchemaDocument)(operationId)?.request.pathParamNames ??
+        (0, operations_1.extractPathParamNames)(op.path));
     for (let i = 0; i < args.length; i += 1) {
         const a = args[i];
-        if (a.startsWith("--") && a !== "--body") {
+        if (a.startsWith("--") && a !== "--body" && a !== "--config") {
             const key = a.slice(2);
-            params[key] = args[++i] ?? "";
+            const value = args[++i] ?? "";
+            if (pathParamNames.has(key)) {
+                params[key] = value;
+            }
+            else {
+                extra[key] = value;
+            }
         }
     }
     let body;
-    const bodyIdx = args.indexOf("--body");
-    if (bodyIdx >= 0) {
-        body = JSON.parse(args[bodyIdx + 1] ?? "{}");
+    try {
+        body = (0, request_body_1.parseRequestBodyFlags)(args).body;
+    }
+    catch (err) {
+        if ((0, request_body_1.isRequestBodyError)(err)) {
+            (0, envelope_1.writeError)({
+                type: err.type,
+                subtype: err.subtype,
+                message: err.message,
+                hint: err.hint,
+            });
+        }
+        throw err;
+    }
+    const validated = (0, validate_body_1.validateCatalogWriteBody)({
+        method: op.method,
+        operationId,
+        body,
+    });
+    if (!validated.ok) {
+        (0, envelope_1.writeError)(validated.error);
+    }
+    body = validated.body;
+    let path = (0, operations_1.resolveOperationPath)(op.path, params);
+    if ((op.method === "GET" || op.method === "HEAD") &&
+        Object.keys(extra).length > 0) {
+        const query = new URLSearchParams(extra).toString();
+        path = `${path}?${query}`;
     }
-    const path = (0, operations_1.resolveOperationPath)(op.path, params);
     const profile = (0, profiles_1.resolveProfile)(flags.profile, env, {
         unsafeCustomEndpoint: flags.unsafeCustomEndpoint,
     });
@@ -752,7 +885,8 @@ async function invokeOperation(operationId, args, flags, env) {
             path,
             risk: op.risk,
             profile: profile.name,
-        }, { format: flags.format });
+            body: op.method === "GET" || op.method === "HEAD" ? undefined : body,
+        }, { format: flags.format, jq: flags.jq });
         return 0;
     }
     const res = await (0, client_1.apiRequest)({
@@ -772,7 +906,7 @@ async function invokeOperation(operationId, args, flags, env) {
     }
     (0, envelope_1.writeSuccess)(res.json, {
         requestId: res.requestId,
-        format: flags.format,
+        format: flags.format, jq: flags.jq,
         meta: { operationId },
     });
     return 0;
@@ -835,19 +969,6 @@ function extractErrorCode(json) {
     }
     return undefined;
 }
-function pathMatches(template, actual) {
-    const t = template.split("/").filter(Boolean);
-    const a = actual.split("/").filter(Boolean);
-    if (t.length !== a.length)
-        return false;
-    for (let i = 0; i < t.length; i += 1) {
-        if (t[i].startsWith("{") && t[i].endsWith("}"))
-            continue;
-        if (t[i] !== a[i])
-            return false;
-    }
-    return true;
-}
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }