@cnbcool/cnb-api-generate 1.2.8 → 2.1.0

package/client/lib/format-output.ts

@@ -0,0 +1,79 @@
+import { printJSON } from './print-json';
+import { summarizeResponse } from './summary-extractors';
+
+/**
+ * 精简响应对象（非 verbose 模式使用）
+ * - 去掉 trace（仅错误时保留）
+ * - 去掉 header（原始 x-cnb-* 头）
+ * - 仅列表 API 时保留分页信息
+ */
+export function compactResponse(response: any): any {
+  if (!response || typeof response !== 'object') return response;
+
+  const compact: any = { status: response.status };
+
+  // 仅错误时保留 trace
+  if (response.status >= 300 && response.trace) {
+    compact.trace = response.trace;
+  }
+
+  // 仅列表 API 时保留分页信息
+  if (response.total != null) {
+    compact.page = response.page;
+    compact.pageSize = response.pageSize;
+    compact.total = response.total;
+    compact.totalPages = response.totalPages;
+  }
+
+  compact.data = response.data;
+  return compact;
+}
+
+/**
+ * 判断是否是标准响应结构（有 status + data 字段）
+ * cag.config.js 中的 responseConverter 可能返回裸 data（不含 status），需要区分处理
+ */
+export function isStandardResponse(response: any): boolean {
+  return response && typeof response === 'object' && typeof response.status === 'number' && 'data' in response;
+}
+
+/**
+ * 格式化 CLI 输出
+ * - verbose 模式：完整 JSON（含 trace、header 等全部字段）
+ * - 快捷命令默认：只输出核心摘要字段
+ * - 非快捷命令默认：精简 JSON（去掉 trace、header，保留完整 data）
+ * @param response 原始响应
+ * @param verbose 是否 verbose 模式
+ * @param summary 是否 summary 模式
+ * @param toolKey 当前 tool 标识，格式为 "module/tool"，用于匹配摘要配置
+ */
+export function formatOutput(response: any, verbose: boolean, summary: boolean, toolKey: string): string {
+  // --verbose 模式：输出完整原始信息
+  if (verbose) {
+    return printJSON(response, verbose);
+  }
+
+  // converter 可能返回裸 data（没有标准 {status, data} 结构），直接输出
+  if (!isStandardResponse(response)) {
+    if (summary) {
+      const summarized = summarizeResponse(response, toolKey);
+      if (summarized !== null) {
+        return printJSON(summarized);
+      }
+    }
+    return printJSON(response);
+  }
+
+  // 精简响应
+  const compact = compactResponse(response);
+
+  // summary 模式：对特定 tool 应用摘要提取（仅成功响应）
+  if (summary && compact.status >= 200 && compact.status < 300) {
+    const summarized = summarizeResponse(compact.data, toolKey);
+    if (summarized !== null) {
+      compact.data = summarized;
+    }
+  }
+
+  return printJSON(compact);
+}

package/client/lib/format-params.ts

@@ -0,0 +1,220 @@
+import { helpData } from './help-data';
+import { tryParseJSON } from './parsers';
+import { buildNestedFieldMap } from '../utils/build-nested-field-map';
+import type { NestedFieldMapping } from '../utils/build-nested-field-map';
+import { restoreOriginalKeys } from '../utils/restore-original-keys';
+import { matchArrayObjectField } from '../utils/match-array-object-field';
+
+/**
+ * 获取 tool 的参数定义（用于自动分发 --key value 到 path/query）
+ */
+export function getToolParamDefs(moduleName: string, toolName: string) {
+  const toolHelp = helpData.modulesHelp?.[moduleName]?.[toolName];
+  if (!toolHelp) return null;
+  return toolHelp.help?.parameter || {};
+}
+
+/**
+ * 格式化参数
+ * 支持新的 --key value 扁平格式，同时向后兼容旧的 --path/--query JSON 格式。
+ * 根据 help.json 中的参数定义，自动将扁平参数分发到 path 或 query。
+ * @param params 原始参数对象
+ * @returns 格式化后的参数对象，包含 module, tool, path, query, data 等
+ */
+export function formatParams(
+  params: Record<string, string | string[] | boolean | undefined>,
+): Record<string, any> {
+  console.log(JSON.stringify(params))
+  // 先将 CLI 带 '-' 的参数名还原为原始 '_'/'@' 参数名
+  params = restoreOriginalKeys(params);
+  console.log(params)
+  const formatted: Record<string, any> = {
+    module: params.module,
+    tool: params.tool,
+  };
+
+  // 保留控制标志
+  if (params.help) formatted.help = true;
+  if (params.short) formatted.short = true;
+  if (params.verbose) formatted.verbose = true;
+
+  // 新格式：将其他 --key value 根据 help.json 自动分发到 path/query
+  const paramDefs = getToolParamDefs(
+    params.module as string,
+    params.tool as string,
+  );
+
+  if (paramDefs) {
+    const pathDef = paramDefs.path || {};
+    const queryDef = paramDefs.query || {};
+    const bodyProps = paramDefs.body?.schema?.properties || {};
+
+    const reservedKeys = new Set([
+      'module', 'tool', 'help', 'short', 'verbose',
+      'path', 'query', 'data', 'h', 'v',
+    ]);
+
+    // 收集 array<object> 展开字段的临时存储：{ arrayName: { propName: string[] } }
+    const arrayObjectCollector: Record<string, Record<string, string[]>> = {};
+
+    // 收集嵌套对象展开字段的临时存储（深层嵌套结构）：{ rootObjectKey: { nested: { path: value } } }
+    const nestedObjectCollector: Record<string, Record<string, any>> = {};
+
+    // 预建所有嵌套对象字段的 camelCased flat key → pathKeys 映射表
+    const nestedFieldMap = new Map<string, NestedFieldMapping>();
+    for (const [rootKey, rootProp] of Object.entries(bodyProps) as [string, any][]) {
+      if (rootProp.type === 'object' && rootProp.properties && Object.keys(rootProp.properties).length > 0) {
+        const subMap = buildNestedFieldMap(rootProp.properties, rootKey, [rootKey]);
+        for (const [k, v] of subMap) {
+          nestedFieldMap.set(k, v);
+        }
+      }
+    }
+
+    for (const [key, value] of Object.entries(params)) {
+      if (reservedKeys.has(key)) continue;
+      // boolean 值需要特殊处理：嵌套对象的 boolean 子字段不能跳过
+      if (typeof value === 'boolean') {
+        const nestedMapping = nestedFieldMap.get(key);
+        if (nestedMapping && nestedMapping.leafSchema?.type === 'boolean') {
+          const { pathKeys } = nestedMapping;
+          const rootKey = pathKeys[0];
+          if (!nestedObjectCollector[rootKey]) {
+            nestedObjectCollector[rootKey] = {};
+          }
+          const subPathKeys = pathKeys.slice(1);
+          let target = nestedObjectCollector[rootKey];
+          for (let pi = 0; pi < subPathKeys.length - 1; pi++) {
+            if (!target[subPathKeys[pi]] || typeof target[subPathKeys[pi]] !== 'object') {
+              target[subPathKeys[pi]] = {};
+            }
+            target = target[subPathKeys[pi]];
+          }
+          target[subPathKeys[subPathKeys.length - 1]] = value;
+        }
+        continue;
+      }
+
+      if (pathDef[key]) {
+        // 归入 path
+        if (!formatted.path) formatted.path = {};
+        formatted.path[key] = value;
+      } else if (queryDef[key]) {
+        // 归入 query
+        if (!formatted.query) formatted.query = {};
+        const paramType = queryDef[key].type;
+        if (paramType === 'number' && typeof value === 'string' && !isNaN(Number(value))) {
+          formatted.query[key] = Number(value);
+        } else {
+          formatted.query[key] = value;
+        }
+      } else if (bodyProps[key]) {
+        // body 字段（无冲突，直接用原 key）
+        if (!formatted.data) formatted.data = {};
+        formatted.data[key] = Array.isArray(value) ? value : tryParseJSON(value as string);
+      } else {
+        // 处理 d- 前缀（冲突时 CLI 以 d- 前缀传入）
+        const stripped = (key.startsWith('d-') || key.startsWith('d_'))
+          ? key.replace(/^d[-_]/, '')
+          : key;
+
+        // 尝试匹配嵌套对象展开字段（通过预建映射表，兼容 Commander camelCase）
+        const nestedMapping = nestedFieldMap.get(stripped);
+        // 尝试匹配 array<object> 展开字段
+        const arrayMatch = matchArrayObjectField(stripped, bodyProps);
+
+        if (nestedMapping) {
+          // 匹配到嵌套对象叶子字段
+          const { pathKeys, leafSchema } = nestedMapping;
+          const rootKey = pathKeys[0];
+          if (!nestedObjectCollector[rootKey]) {
+            nestedObjectCollector[rootKey] = {};
+          }
+          // 类型转换
+          let convertedValue: any = value;
+          if (leafSchema?.type === 'number' && typeof value === 'string' && !isNaN(Number(value))) {
+            convertedValue = Number(value);
+          } else if (leafSchema?.type === 'boolean') {
+            convertedValue = value === 'true' || (value as any) === true;
+          } else if (typeof value === 'string') {
+            convertedValue = tryParseJSON(value);
+          }
+          // 用 pathKeys（去掉根 key）深度设置到 collector 中
+          const subPathKeys = pathKeys.slice(1);
+          let target = nestedObjectCollector[rootKey];
+          for (let pi = 0; pi < subPathKeys.length - 1; pi++) {
+            if (!target[subPathKeys[pi]] || typeof target[subPathKeys[pi]] !== 'object') {
+              target[subPathKeys[pi]] = {};
+            }
+            target = target[subPathKeys[pi]];
+          }
+          target[subPathKeys[subPathKeys.length - 1]] = convertedValue;
+        } else if (arrayMatch) {
+          // 收集到 collector 中，后续统一 zip
+          if (!arrayObjectCollector[arrayMatch.arrayKey]) {
+            arrayObjectCollector[arrayMatch.arrayKey] = {};
+          }
+          const vals = Array.isArray(value) ? value : [value as string];
+          arrayObjectCollector[arrayMatch.arrayKey][arrayMatch.subKey] = vals;
+        } else if (key.startsWith('d-') || key.startsWith('d_')) {
+          // body 字段（有冲突，CLI 中以 d- 或 d_ 前缀传入）
+          const originalKey = key.replace(/^d[-_]/, '');
+          if (bodyProps[originalKey]) {
+            if (!formatted.data) formatted.data = {};
+            formatted.data[originalKey] = Array.isArray(value) ? value : tryParseJSON(value as string);
+          } else {
+            if (!formatted.query) formatted.query = {};
+            formatted.query[key] = typeof value === 'string' && !isNaN(Number(value)) ? Number(value) : value;
+          }
+        } else {
+          // 未知参数，尝试放入 query（兼容）
+          if (!formatted.query) formatted.query = {};
+          formatted.query[key] = typeof value === 'string' && !isNaN(Number(value)) ? Number(value) : value;
+        }
+      }
+    }
+
+    // 将 array<object> 展开字段按索引 zip 合并为对象数组
+    for (const [arrayKey, subProps] of Object.entries(arrayObjectCollector)) {
+      if (!formatted.data) formatted.data = {};
+      const subKeys = Object.keys(subProps);
+      const maxLen = Math.max(...subKeys.map(k => subProps[k].length));
+      const result: Record<string, any>[] = [];
+      for (let i = 0; i < maxLen; i++) {
+        const obj: Record<string, any> = {};
+        for (const subKey of subKeys) {
+          const val = subProps[subKey][i];
+          if (val !== undefined) {
+            const itemProp = bodyProps[arrayKey]?.items?.properties?.[subKey];
+            if (itemProp?.type === 'number' && !isNaN(Number(val))) {
+              obj[subKey] = Number(val);
+            } else {
+              obj[subKey] = val;
+            }
+          }
+        }
+        result.push(obj);
+      }
+      formatted.data[arrayKey] = result;
+    }
+
+    // 将嵌套对象展开字段组装回嵌套结构
+    for (const [objectKey, subProps] of Object.entries(nestedObjectCollector)) {
+      if (!formatted.data) formatted.data = {};
+      formatted.data[objectKey] = subProps;
+    }
+  }
+
+  // 当没有传递 query 时，要判断当前 tool 是否支持 query
+  if (formatted.query === undefined) {
+    const paramDefs2 = getToolParamDefs(
+      formatted.module,
+      formatted.tool,
+    );
+    if (paramDefs2?.query) {
+      formatted.query = {};
+    }
+  }
+
+  return formatted;
+}

package/client/lib/help-data.ts

@@ -0,0 +1,13 @@
+import fs from 'fs';
+import path from 'path';
+
+const helpFileContent = fs.readFileSync(
+  path.join(__dirname, '../help.json'),
+  'utf8',
+);
+if (!helpFileContent) {
+  console.error('help.json not found');
+  process.exit(1);
+}
+
+export const helpData = JSON.parse(helpFileContent);

package/client/lib/key-mapping-data.ts

@@ -0,0 +1,13 @@
+import fs from 'fs';
+import path from 'path';
+
+const keyMappingFilePath = path.join(__dirname, '../key-mapping.json');
+
+let data: Record<string, Record<string, Record<string, string>>> = {};
+
+if (fs.existsSync(keyMappingFilePath)) {
+  const content = fs.readFileSync(keyMappingFilePath, 'utf8');
+  data = JSON.parse(content);
+}
+
+export const keyMappingData = data;

package/client/lib/parsers.ts

@@ -0,0 +1,130 @@
+import fs from 'fs';
+
+/**
+ * 尝试解析JSON字符串
+ * 先将真实控制字符转义为 JSON 合法形式，处理 shell/AI 传入的原始换行等情况
+ * @param str 要解析的字符串
+ * @returns 解析后的对象或原始字符串
+ */
+export function tryParseJSON(str: string | boolean | undefined): any {
+  if (typeof str !== 'string') return str;
+
+  const escaped = str.replace(/[\x00-\x1F\x7F]/g, (ch) => {
+    const map = { '\n': '\\n', '\r': '\\r', '\t': '\\t', '\b': '\\b', '\f': '\\f' };
+    return map[ch] || '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0');
+  });
+  try {
+    return JSON.parse(escaped);
+  } catch (error) {
+    return str;
+  }
+}
+
+/**
+ * 尝试从文件引用或 stdin 读取内容（类似 curl 的 @file / @- 语法）
+ */
+export function tryReadFileRef(str: string | boolean | undefined) {
+  if (typeof str !== 'string' || !str.startsWith('@')) return str;
+
+  const ref = str.slice(1);
+
+  // @- 表示从 stdin 读取
+  if (ref === '-') {
+    try {
+      return fs.readFileSync(0, 'utf8').trim();
+    } catch (e) {
+      console.error('从 stdin 读取失败:', e.message);
+      return str;
+    }
+  }
+
+  // @/path/to/file 表示从文件读取
+  if (fs.existsSync(ref)) {
+    return fs.readFileSync(ref, 'utf8').trim();
+  }
+
+  return str;
+}
+
+/**
+ * 解析 commander 未识别的未知选项
+ * commander 开启 allowUnknownOption 后，未知选项会残留在 process.argv 中，
+ * 这里手动解析它们，行为与原 parseArguments 对未知 --key value 的处理一致。
+ */
+export function parseUnknownOptions(
+  params: Record<string, string | boolean | undefined>,
+): void {
+  const knownLongOptions = new Set([
+    'help', 'short', 'verbose', 'path', 'query', 'data',
+  ]);
+
+  // 获取 commander 解析后的剩余参数（未被识别的选项）
+  const rawArgs = process.argv.slice(2);
+  // 跳过已被 commander 消费的位置参数和已知选项，手动扫描未知选项
+  let i = 0;
+  while (i < rawArgs.length) {
+    const arg = rawArgs[i];
+
+    if (arg.startsWith('--')) {
+      const fullKey = arg.slice(2);
+
+      // 处理 --key=value 格式
+      if (fullKey.includes('=')) {
+        const [key, ...valueParts] = fullKey.split('=');
+        if (!knownLongOptions.has(key) && key !== 'module' && key !== 'tool') {
+          params[key] = valueParts.join('=');
+        }
+        i++;
+        continue;
+      }
+
+      const key = fullKey;
+
+      // 已知选项跳过（commander 已处理）
+      if (knownLongOptions.has(key)) {
+        // 如果是带值的已知选项（path/query/data），跳过值
+        if (['path', 'query', 'data'].includes(key) && i + 1 < rawArgs.length && !rawArgs[i + 1].startsWith('-')) {
+          i += 2;
+        } else {
+          i++;
+        }
+        continue;
+      }
+
+      // 未知选项：检查下一个参数是否是值
+      const nextArg = rawArgs[i + 1];
+      const isNextArgValue =
+        i + 1 < rawArgs.length &&
+        !nextArg.startsWith('--') &&
+        !nextArg.startsWith('-');
+
+      if (isNextArgValue) {
+        params[key] = nextArg;
+        i += 2;
+      } else {
+        params[key] = true;
+        i++;
+      }
+    } else if (arg.startsWith('-') && arg.length > 1 && !/^-?\d+$/.test(arg)) {
+      // 短参数
+      const key = arg.slice(1);
+
+      const nextArg = rawArgs[i + 1];
+      const isNextArgValue =
+        i + 1 < rawArgs.length &&
+        !nextArg.startsWith('--') &&
+        !nextArg.startsWith('-');
+
+      if (isNextArgValue && key.length === 1) {
+        params[key] = nextArg;
+        i += 2;
+      } else {
+        params[key] = true;
+        i++;
+      }
+    } else {
+      // 位置参数，跳过（已被 commander 消费）
+      i++;
+    }
+  }
+}

package/client/lib/print-json.ts

@@ -0,0 +1,12 @@
+/**
+ * 将数据转换为格式化的 JSON 字符串
+ * @param data 要序列化的数据（可以是任意类型）缩进）
+ * @param verbose 是否 verbose 模式
+ * @returns 格式化的 JSON 字符串，如果序列化失败则返回错误信息的 JSON
+ */
+export function printJSON(
+  data: Record<string, any> | Array<any>,
+  verbose: boolean = false
+): string {
+  return verbose ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}

package/client/lib/register-fallback.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+import { executeAction } from './execute-action';
+
+/**
+ * 顶层 fallback action：处理快捷命令等未被子命令匹配的情况
+ */
+export function registerFallbackAction(program: Command): void {
+  program
+    .argument('[module]', '模块名称')
+    .argument('[tool]', '工具名称')
+    .action(async (moduleArg: string | undefined, toolArg: string | undefined, opts: Record<string, any>) => {
+      await executeAction(moduleArg, toolArg, opts, program);
+    });
+}

package/client/lib/register-modules.ts

@@ -0,0 +1,121 @@
+import { Command, Option } from 'commander';
+import { trimSummary } from './trim-summary';
+import { helpData } from './help-data';
+import { flatOptionsData } from './flat-options-data';
+import { executeAction } from './execute-action';
+import { resolveShortcut } from '../shortcuts';
+
+interface FlatOption {
+  optKey: string;
+  valuePlaceholder: string;
+  description: string;
+  required: boolean;
+  isArray: boolean;
+  choices?: string[];
+  defaultValue?: any;
+  source: 'path' | 'query' | 'body';
+  isArrayObject?: boolean;
+  isNestedField?: boolean;
+}
+
+/**
+ * 为单个 tool 子命令注册 Commander options
+ * 直接读取预生成的 flat-options.json 中已扁平化的参数定义，无需运行时计算
+ */
+function registerToolOptions(toolCmd: Command, moduleName: string, toolName: string): void {
+  const moduleOptions = flatOptionsData[moduleName];
+  if (!moduleOptions) return;
+  const toolOptions: Record<string, FlatOption> = moduleOptions[toolName];
+  if (!toolOptions) return;
+
+  for (const [, opt] of Object.entries(toolOptions) as [string, FlatOption][]) {
+    const option = new Option(
+      `--${opt.optKey} ${opt.valuePlaceholder}`.trim(),
+      opt.description,
+    );
+
+    if (opt.required && opt.source === 'path') {
+      option.makeOptionMandatory();
+    }
+
+    if (opt.choices) {
+      option.choices(opt.choices);
+    }
+
+    if (opt.defaultValue !== undefined) {
+      option.default(opt.defaultValue);
+    }
+
+    if (opt.required && opt.source === 'body' && !opt.isArrayObject && !opt.isNestedField) {
+      option.makeOptionMandatory();
+    }
+
+    if (opt.isArray || opt.isArrayObject) {
+      option.argParser((val: string, prev: string[] | undefined) => {
+        return (prev || []).concat(val);
+      });
+      option.default(undefined);
+    }
+
+    toolCmd.addOption(option);
+  }
+}
+
+/**
+ * 为每个模块注册子命令，使 cnb <module> -h 显示模块帮助
+ * 每个 tool 的参数通过 Commander 的 option 系统注册，--help 自动展示参数说明
+ */
+export function registerModuleCommands(program: Command): void {
+  const modulesHelp = helpData.modulesHelp || {};
+
+  for (const [moduleName, tools] of Object.entries(modulesHelp) as [string, Record<string, any>][]) {
+    const toolEntries = Object.values(tools);
+    const sub = program
+      .command(moduleName)
+      .description(`${moduleName} 模块 (${toolEntries.length} tools)`)
+      .helpOption('-h, --help', '显示帮助文档');
+
+    // 为每个 tool 注册子命令
+    for (const [toolName, toolInfo] of Object.entries(tools) as [string, any][]) {
+      const summary = trimSummary(toolInfo.summary || '');
+      const toolCmd = sub
+        .command(toolName)
+        .description(summary)
+        .option('-v, --verbose', '输出完整原始响应')
+        .helpOption('-h, --help', '显示帮助文档')
+        .showHelpAfterError(true)
+        .action(async (opts: Record<string, any>) => {
+          await executeAction(moduleName, toolName, opts, sub);
+        });
+
+      // 添加权限信息到帮助文本
+      if (toolInfo.permission) {
+        toolCmd.addHelpText('before', `权限: ${toolInfo.permission}\n`);
+      }
+
+      // 根据 flat-options.json 注册参数选项
+      registerToolOptions(toolCmd, moduleName, toolName);
+    }
+
+    // 允许未匹配到子命令时也能正常执行（不报错）
+    sub.allowUnknownOption();
+    sub.allowExcessArguments();
+
+    // 模块级 action：处理未匹配到子命令的情况
+    // 如果输入了快捷命令名（如 cnb issues get），Commander 匹配不到真实 tool 子命令，
+    // 会走到这里，此时尝试 resolveShortcut 将其转换为真实 tool
+    sub
+      .argument('[tool]', '工具名称（支持快捷命令）')
+      .action(async (toolArg: string | undefined, opts: Record<string, any>) => {
+        if (toolArg) {
+          const shortcut = resolveShortcut(moduleName, toolArg);
+          if (shortcut) {
+            // 快捷命令匹配成功，走 executeAction 流程
+            await executeAction(moduleName, toolArg, opts, sub);
+            return;
+          }
+        }
+        sub.help();
+      });
+  }
+}