@thinkingai/ae-cli 6.0.30 → 6.0.31

package/README.md

@@ -84,7 +84,6 @@ ae-cli auth logout
 | Domain | Commands | Description |
 |--------|----------|-------------|
 | `analysis` | 30+ | Analysis workflows: alerts, reports, dashboards, ad-hoc/drilldown, entity/event details, analysis schema |
-| `analysis_audience` | 10+ | Audience operations: clusters, tags, and cluster/tag definition schema |
 | `analysis_meta` | 20+ | Metadata governance: events/properties, metrics, virtual metadata, project config, tracking plan, mark times, entity catalog |
 | `engage` | 40+ | Hermes Engage MCP: channels, tasks, configs, flows, strategies |
 | `dataops_repo` | 1 | DataOps repo utilities: space discovery |
@@ -124,9 +123,10 @@ Retrieval primitives for external agents (`+index` → `+grep` → `+read`); the
 |--------|-------------|---------|
 | `--host <url>` | Override active AE host URL | from config |
 | `--format <json\|table>` | Output format | json |
-| `--jq <expr>` | Filter expression | - |
-| `--dry-run` | Preview request | false |
-| `--yes` | Skip confirmation | false |
+| `--jq <expr>` | jq 1.8 expression (jq-wasm) over command payload before output envelope | - |
+| `--validate` | Fix params: capability gateway `/validate` only (curated gateway commands). Do not combine with `--dry-run` | false |
+| `--dry-run` | Confirm ready to run: capability gateway `/dry-run` (or local transport preview). Do not combine with `--validate` | false |
+| `--yes` | Skip high-risk write confirmation | false |
 | `--no-update-check` | Skip checking for newer ae-cli versions | false |
 
 ## Skills
@@ -188,7 +188,7 @@ ae-cli is built with:
 - **TypeScript** (~8000 lines of code)
 - **Commander.js** for CLI framework
 - **WebSocket** for MCP server integration
-- **Node.js** runtime (v18+)
+- **Node.js** runtime (v20+)
 
 The project structure:
 ```
@@ -200,7 +200,6 @@ src/
     ├── auth.ts
     ├── config.ts
     ├── te-analysis/
-    ├── te-audience/
     ├── te-meta/
     ├── te-engage/
     ├── te-dataops/
@@ -213,7 +212,6 @@ src/
 
 ```bash
 npm run verify:analysis-tools
-npm run verify:analysis-audience-tools
 npm run verify:analysis-meta-tools
 npm run verify:analysis-common-tools
 ```

package/README.zh.md

@@ -84,7 +84,6 @@ ae-cli auth logout
 | 域 | 命令数 | 描述 |
 |---|---|---|
 | `analysis` | 30+ | 分析工作流：告警、报表、仪表板、即时分析/下钻、实体/事件详情、分析模型 |
-| `analysis_audience` | 10+ | 受众运营：分群、标签及其定义模型 |
 | `analysis_meta` | 20+ | 元数据治理：事件/属性、指标、虚拟元数据、项目配置、埋点方案、标记时间、实体目录 |
 | `engage` | 40+ | Hermes Engage MCP：渠道、任务、配置、流程、策略 |
 | `dataops_repo` | 1 | DataOps 仓库辅助：空间发现 |
@@ -125,9 +124,10 @@ ae-cli auth logout
 |---|---|---|
 | `--host <url>` | 覆盖当前 AE 主机 URL | 从配置读取 |
 | `--format <json\|table>` | 输出格式 | json |
-| `--jq <expr>` | 过滤表达式 | - |
-| `--dry-run` | 预览请求 | false |
-| `--yes` | 跳过确认 | false |
+| `--jq <expr>` | jq 1.8 表达式（jq-wasm），作用于命令业务结果，再包进输出信封 | - |
+| `--validate` | 改对参数：仅能力网关 `/validate`（精选网关命令）。勿与 `--dry-run` 同用 | false |
+| `--dry-run` | 确认可以跑：能力网关 `/dry-run`（或其它传输的请求预览）。勿与 `--validate` 同用 | false |
+| `--yes` | 跳过高风险写操作确认 | false |
 | `--no-update-check` | 跳过 ae-cli 新版本检查 | false |
 
 ## Skills
@@ -189,7 +189,7 @@ ae-cli 基于：
 - **TypeScript**（约 8000 行代码）
 - **Commander.js** 作为 CLI 框架
 - **WebSocket** 用于 MCP 服务器集成
-- **Node.js** 运行时（v18+）
+- **Node.js** 运行时（v20+）
 
 项目结构：
 ```
@@ -201,7 +201,6 @@ src/
     ├── auth.ts
     ├── config.ts
     ├── te-analysis/
-    ├── te-audience/
     ├── te-meta/
     ├── te-engage/
     ├── te-dataops/
@@ -214,7 +213,6 @@ src/
 
 ```bash
 npm run verify:analysis-tools
-npm run verify:analysis-audience-tools
 npm run verify:analysis-meta-tools
 npm run verify:analysis-common-tools
 ```

package/dist/{auth-7TQRGLBC.js → auth-7H3HAAJ3.js}

@@ -1,7 +1,7 @@
 import {
   printError,
   printOutput
-} from "./chunk-ZAOL36CG.js";
+} from "./chunk-TNW2CI4W.js";
 import {
   clearCliToken,
   mintCliToken
@@ -302,12 +302,12 @@ function registerAuth(program) {
         activateHostAfterLogin(host, explicitHost);
         logger.info(`Device flow login successful for ${host} (resumed)`);
         emit("Login successful! Token saved securely.");
-        printOutput(loginSummary(host, tokens2), fmt);
+        await printOutput(loginSummary(host, tokens2), fmt);
         return;
       }
       if (opts.wait === false) {
         const authResp = await authorizeDevice(teClaudeBase);
-        printOutput(
+        await printOutput(
           {
             device_code: authResp.device_code,
             user_code: authResp.user_code,
@@ -325,7 +325,7 @@ function registerAuth(program) {
       activateHostAfterLogin(host, explicitHost);
       logger.info(`Device flow login successful for ${host}`);
       emit("Login successful! Token saved securely.");
-      printOutput(loginSummary(host, tokens), fmt);
+      await printOutput(loginSummary(host, tokens), fmt);
     } catch (err) {
       if (err instanceof DeviceFlowUnsupportedError) {
         printError(
@@ -342,13 +342,13 @@ function registerAuth(program) {
   auth.command("status").description("Show authentication status for a host (--host or active host)").option("--host <url>", HOST_OPTION_DESC).action(async (opts) => {
     const host = resolveAuthHost(program, opts);
     if (!host) {
-      printOutput({ authenticated: false, host: "(none)", hint: "Run: ae-cli config set-host <url>" }, program.opts().format || "json");
+      await printOutput({ authenticated: false, host: "(none)", hint: "Run: ae-cli config set-host <url>" }, program.opts().format || "json");
       return;
     }
     const secureEntry = load(host);
     if (secureEntry) {
       const pastStaticExpiry = new Date(secureEntry.accessExpiresAt).getTime() < Date.now();
-      printOutput(
+      await printOutput(
         {
           authenticated: true,
           host,
@@ -364,7 +364,7 @@ function registerAuth(program) {
     }
     const fallbackCliToken = getFallbackCliToken(host);
     if (fallbackCliToken) {
-      printOutput(
+      await printOutput(
         {
           authenticated: true,
           host,
@@ -376,9 +376,9 @@ function registerAuth(program) {
       );
       return;
     }
-    printOutput({ authenticated: false, host, source: "none" }, program.opts().format || "json");
+    await printOutput({ authenticated: false, host, source: "none" }, program.opts().format || "json");
   });
-  auth.command("logout").description("Clear stored credentials (access token, CLI token, and host config) for a host (--host or active host)").option("--host <url>", HOST_OPTION_DESC).action((opts) => {
+  auth.command("logout").description("Clear stored credentials (access token, CLI token, and host config) for a host (--host or active host)").option("--host <url>", HOST_OPTION_DESC).action(async (opts) => {
     const host = resolveAuthHost(program, opts);
     if (!host) {
       printError("config", "No AE host configured.", "Run: ae-cli config set-host <url>");
@@ -389,7 +389,7 @@ function registerAuth(program) {
     removeHost(host);
     process.stderr.write(`[ae-cli] Credentials and config cleared for ${host}
 `);
-    printOutput({ cleared: true, host }, program.opts().format || "json");
+    await printOutput({ cleared: true, host }, program.opts().format || "json");
   });
 }
 export {

package/dist/{capability-KVA55RMK.js → capability-SEH3JWLN.js}

@@ -2,20 +2,21 @@ import {
   normalizeRiskLevel,
   requiresConfirmation
 } from "./chunk-OO6XR6LK.js";
-import {
-  printError,
-  printOutput
-} from "./chunk-ZAOL36CG.js";
 import {
   findGatewayDomain
-} from "./chunk-CWZUGF2J.js";
+} from "./chunk-HL2AJQ4Q.js";
 import {
   CapabilityGatewayError,
   dryRunCapability,
   executeCapability,
   inspectCapability,
-  listCapabilities
-} from "./chunk-OJR23CIK.js";
+  listCapabilities,
+  validateCapability
+} from "./chunk-I4A62X3N.js";
+import {
+  printError,
+  printOutput
+} from "./chunk-TNW2CI4W.js";
 import {
   PermissionError
 } from "./chunk-NOO24N7W.js";
@@ -135,7 +136,31 @@ function registerCapability(program) {
       return inspectCapability(host, gatewayDomain, capabilityId);
     });
   }).addHelpText("after", "\nExample:\n  ae-cli capability inspect analysis.dashboard.list");
-  capability.command("dry-run").description("Validate and preview one capability invocation without executing it").argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+  capability.command("validate").description(
+    "Validate and normalize capability input only (schema/params). Does not execute business logic. Use when crafting complex payloads (nested objects, qp, share/member payloads) before dry-run/run. Success data: valid, capability_id, normalized_input. Unlike dry-run, does not return risk/output_mode/supports_cancel preview."
+  ).argument("<capability-id>", "Capability ID, such as metadata.data_table.sql_write").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+    await executeAndPrint(program, async (host) => {
+      const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
+      return validateCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
+    });
+  }).addHelpText(
+    "after",
+    `
+When to use:
+  Prefer validate while iterating complex input (required fields, types, qp shape), then run.
+  Prefer dry-run alone when you need risk / output mode / cancelability or a delete gate.
+  Motto: validate = fix params; dry-run = confirm ready to run.
+  Do not stack validate + dry-run on the same final input by default (dry-run already validates params).
+  Neither mutates business data. Curated gateway commands: global --validate / --dry-run.
+
+Examples:
+  ae-cli capability validate metadata.data_table.sql_write --input '{"project_id":1,"operation":"create",...}'
+  ae-cli metadata data-table sql-write --project-id 1 ... --validate
+  ae-cli capability validate analysis.project_space.create --input input.json`
+  );
+  capability.command("dry-run").description(
+    "Full pre-execution confirmation without running business logic: validates/normalizes input and returns risk, output_mode, and supports_cancel. Use alone when you need that preview or a delete gate (do not stack after validate on the same final input by default). Global --dry-run on curated/capability run also hits this endpoint."
+  ).argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
     await executeAndPrint(program, async (host) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       return dryRunCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
@@ -151,6 +176,15 @@ Examples:
     await executeAndPrint(program, async (host, globalOpts) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       const input = parseCapabilityInput(opts.input);
+      if (globalOpts.validate && globalOpts.dryRun) {
+        throw new CapabilityCommandValidationError(
+          "Cannot combine --validate and --dry-run.",
+          "Use --validate to fix parameters; use --dry-run as the pre-execution confirmation."
+        );
+      }
+      if (globalOpts.validate) {
+        return validateCapability(host, gatewayDomain, capabilityId, input);
+      }
       if (globalOpts.dryRun) {
         return dryRunCapability(host, gatewayDomain, capabilityId, input);
       }
@@ -172,7 +206,7 @@ Examples:
     `
 Examples:
   ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
-  ae-cli capability run analysis.dashboard.list --input input.json --yes`
+  ae-cli capability run analysis.dashboard.list --input input.json`
   );
 }
 async function executeAndPrint(program, action) {
@@ -186,9 +220,14 @@ async function executeAndPrint(program, action) {
   try {
     const result = await action(host, globalOpts);
     if (result !== void 0) {
-      printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
+      await printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
     }
   } catch (error) {
+    if (error?.type === "validation" && String(error?.message || "").includes("--jq")) {
+      printError("validation", error.message, error.hint);
+      process.exitCode = 1;
+      return;
+    }
     printCapabilityError(error);
     process.exitCode = 1;
   }

package/dist/{capability-LKHLZQPD.js → capability-SQ2IWKP3.js}

@@ -2,20 +2,21 @@ import {
   normalizeRiskLevel,
   requiresConfirmation
 } from "./chunk-OO6XR6LK.js";
-import {
-  printError,
-  printOutput
-} from "./chunk-ZAOL36CG.js";
 import {
   findGatewayDomain
-} from "./chunk-CWZUGF2J.js";
+} from "./chunk-HL2AJQ4Q.js";
 import {
   CapabilityGatewayError,
   dryRunCapability,
   executeCapability,
   inspectCapability,
-  listCapabilities
-} from "./chunk-THBBNYXI.js";
+  listCapabilities,
+  validateCapability
+} from "./chunk-DYOS6YY7.js";
+import {
+  printError,
+  printOutput
+} from "./chunk-TNW2CI4W.js";
 import {
   PermissionError
 } from "./chunk-NOO24N7W.js";
@@ -135,7 +136,31 @@ function registerCapability(program) {
       return inspectCapability(host, gatewayDomain, capabilityId);
     });
   }).addHelpText("after", "\nExample:\n  ae-cli capability inspect analysis.dashboard.list");
-  capability.command("dry-run").description("Validate and preview one capability invocation without executing it").argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+  capability.command("validate").description(
+    "Validate and normalize capability input only (schema/params). Does not execute business logic. Use when crafting complex payloads (nested objects, qp, share/member payloads) before dry-run/run. Success data: valid, capability_id, normalized_input. Unlike dry-run, does not return risk/output_mode/supports_cancel preview."
+  ).argument("<capability-id>", "Capability ID, such as metadata.data_table.sql_write").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
+    await executeAndPrint(program, async (host) => {
+      const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
+      return validateCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
+    });
+  }).addHelpText(
+    "after",
+    `
+When to use:
+  Prefer validate while iterating complex input (required fields, types, qp shape), then run.
+  Prefer dry-run alone when you need risk / output mode / cancelability or a delete gate.
+  Motto: validate = fix params; dry-run = confirm ready to run.
+  Do not stack validate + dry-run on the same final input by default (dry-run already validates params).
+  Neither mutates business data. Curated gateway commands: global --validate / --dry-run.
+
+Examples:
+  ae-cli capability validate metadata.data_table.sql_write --input '{"project_id":1,"operation":"create",...}'
+  ae-cli metadata data-table sql-write --project-id 1 ... --validate
+  ae-cli capability validate analysis.project_space.create --input input.json`
+  );
+  capability.command("dry-run").description(
+    "Full pre-execution confirmation without running business logic: validates/normalizes input and returns risk, output_mode, and supports_cancel. Use alone when you need that preview or a delete gate (do not stack after validate on the same final input by default). Global --dry-run on curated/capability run also hits this endpoint."
+  ).argument("<capability-id>", "Capability ID, such as analysis.query.export").option("--domain <domain>", "Override the capability namespace used for gateway routing").option("--input <json-or-path>", "Input JSON object, file path, @<path>, or - for stdin").action(async (capabilityId, opts) => {
     await executeAndPrint(program, async (host) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       return dryRunCapability(host, gatewayDomain, capabilityId, parseCapabilityInput(opts.input));
@@ -151,6 +176,15 @@ Examples:
     await executeAndPrint(program, async (host, globalOpts) => {
       const gatewayDomain = resolveCapabilityGatewayDomain(capabilityId, opts.domain);
       const input = parseCapabilityInput(opts.input);
+      if (globalOpts.validate && globalOpts.dryRun) {
+        throw new CapabilityCommandValidationError(
+          "Cannot combine --validate and --dry-run.",
+          "Use --validate to fix parameters; use --dry-run as the pre-execution confirmation."
+        );
+      }
+      if (globalOpts.validate) {
+        return validateCapability(host, gatewayDomain, capabilityId, input);
+      }
       if (globalOpts.dryRun) {
         return dryRunCapability(host, gatewayDomain, capabilityId, input);
       }
@@ -172,7 +206,7 @@ Examples:
     `
 Examples:
   ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
-  ae-cli capability run analysis.dashboard.list --input input.json --yes`
+  ae-cli capability run analysis.dashboard.list --input input.json`
   );
 }
 async function executeAndPrint(program, action) {
@@ -186,9 +220,14 @@ async function executeAndPrint(program, action) {
   try {
     const result = await action(host, globalOpts);
     if (result !== void 0) {
-      printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
+      await printOutput(result, globalOpts.format ?? "json", globalOpts.jq);
     }
   } catch (error) {
+    if (error?.type === "validation" && String(error?.message || "").includes("--jq")) {
+      printError("validation", error.message, error.hint);
+      process.exitCode = 1;
+      return;
+    }
     printCapabilityError(error);
     process.exitCode = 1;
   }

package/dist/{chunk-GWZ5MYWE.js → chunk-6LEYLOV3.js}

@@ -168,6 +168,16 @@ async function callMcpTool(url, toolName, args = {}, hostOverride) {
   };
 }
 function parseMcpResult(result) {
+  if (result.isError) {
+    const firstText = result.content.find((item) => item.type === "text")?.text || "";
+    let errorMessage = firstText.trim() || "MCP tool call failed";
+    try {
+      const parsed = safeJsonParse(firstText);
+      errorMessage = mcpResultErrorMessage(parsed) || errorMessage;
+    } catch {
+    }
+    throwMcpError(errorMessage);
+  }
   if (result.content.length > 0 && result.content[0].type === "text") {
     const text = result.content[0].text || "";
     let parsed;
@@ -178,10 +188,7 @@ function parseMcpResult(result) {
     }
     const errMsg = mcpResultErrorMessage(parsed);
     if (errMsg !== null) {
-      if (/no_auth|auth_error|permission|forbidden|unauthor|\u65e0\u6743/i.test(errMsg)) {
-        throw new PermissionError(errMsg);
-      }
-      throw new Error(errMsg);
+      throwMcpError(errMsg);
     }
     return parsed;
   }
@@ -190,6 +197,7 @@ function parseMcpResult(result) {
 function mcpResultErrorMessage(parsed) {
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
   if (parsed.success === true || parsed.ok === true) return null;
+  const explicitlyFailed = parsed.success === false || parsed.ok === false;
   const e = parsed.error;
   if (typeof e === "string" && e.trim()) return e;
   if (e && typeof e === "object") {
@@ -198,8 +206,21 @@ function mcpResultErrorMessage(parsed) {
     if (msg && code) return `${code}: ${msg}`;
     if (msg || code) return msg || code;
   }
+  if (explicitlyFailed) {
+    const msg = typeof parsed.message === "string" && parsed.message.trim() ? parsed.message.trim() : void 0;
+    const codeValue = parsed.errorCode ?? parsed.error_code ?? parsed.code;
+    const code = typeof codeValue === "string" && codeValue.trim() ? codeValue.trim() : void 0;
+    if (msg && code) return `${code}: ${msg}`;
+    return msg || code || "MCP tool call failed";
+  }
   return null;
 }
+function throwMcpError(message) {
+  if (/no_auth|auth_error|permission|forbidden|unauthor|\u65e0\u6743/i.test(message)) {
+    throw new PermissionError(message);
+  }
+  throw new Error(message);
+}
 
 export {
   registerMcpMappings,