@cnbcool/cnb-api-generate 1.2.8 → 2.0.0

package/client/index.ts

@@ -1,515 +1,40 @@
 #!/usr/bin/env node
 
-import fs from 'fs';
-import path from 'path';
-import { showModuleHelp } from './modules.help';
-import { showToolHelp } from './tools.help';
-import { showShort, resolveShortcut, summarizeResponse } from './shortcuts';
-import { handleUpload } from './utils/upload';
+import { Command } from 'commander';
+import { getExtraHelpText } from './lib/extra-help';
+import { registerModuleCommands } from './lib/register-modules';
+import { registerFallbackAction } from './lib/register-fallback';
 
-const helpFileContent = fs.readFileSync(
-  path.join(__dirname, 'help.json'),
-  'utf8',
-);
-if (!helpFileContent) {
-  console.error('help.json not found');
-  process.exit(1);
-}
+// ============================================================
+// Commander 程序定义
+// ============================================================
 
-const helpData = JSON.parse(helpFileContent);
+const program = new Command();
 
-/**
- * 解析命令行参数
- * 支持：--key value, --key=value, -k value (短参数), 位置参数 (module, tool)
- * @returns 解析后的参数对象
- */
-export function parseArguments() {
-  const args = process.argv.slice(2);
-  const result: Record<string, string | boolean | undefined> = {};
+program
+  .name(process.env.CNB_CLI_CMD || 'cnb')
+  .description('CNB OpenAPI 命令行工具')
+  .allowUnknownOption()
+  .allowExcessArguments()
+  .helpOption('-h, --help', '显示帮助文档')
+  .option('-s, --short', '显示当前仓库的快捷命令')
+  .addHelpText('after', getExtraHelpText());
 
-  let positionalCount = 0;
-  let i = 0;
+// ============================================================
+// 注册命令
+// ============================================================
 
-  while (i < args.length) {
-    const arg = args[i];
+registerModuleCommands(program);
+registerFallbackAction(program);
 
-    if (arg.startsWith('--')) {
-      // --- 处理命名参数 (Options) ---
-      const fullKey = arg.slice(2);
-      
-      // 支持 key=value 格式 (e.g., --config=file.json)
-      if (fullKey.includes('=')) {
-        const [key, ...valueParts] = fullKey.split('=');
-        result[key] = valueParts.join('=');
-        i++;
-        continue;
-      }
+// ============================================================
+// 导出（保持兼容性）
+// ============================================================
 
-      const key = fullKey;
-      
-      // 检查下一个参数是否是值（不以 - 开头）
-      const nextArg = args[i + 1];
-      const isNextArgValue = 
-        i + 1 < args.length && 
-        !nextArg.startsWith('--') && 
-        !nextArg.startsWith('-');
+export { parseUnknownOptions as parseArguments } from './lib/parsers';
 
-      if (isNextArgValue) {
-        result[key] = nextArg;
-        i += 2;
-      } else {
-        // 没有值，视为布尔标志
-        result[key] = true;
-        i++;
-      }
-    } else if (arg.startsWith('-') && arg.length > 1 && !/^-?\d+$/.test(arg)) {
-      // --- 处理短参数 (e.g., -h, -v)，排除负数 ---
-      const key = arg.slice(1);
-      
-      const nextArg = args[i + 1];
-      const isNextArgValue = 
-        i + 1 < args.length && 
-        !nextArg.startsWith('--') && 
-        !nextArg.startsWith('-');
+// ============================================================
+// 启动
+// ============================================================
 
-      // 只有单字符短参才吞并下一个值 (如 -o output.txt)
-      if (isNextArgValue && key.length === 1) {
-        result[key] = nextArg;
-        i += 2;
-      } else {
-        result[key] = true;
-        i++;
-      }
-    } else {
-      // --- 处理位置参数 (Positional Args) ---
-      if (positionalCount === 0) {
-        result.module = arg;
-      } else if (positionalCount === 1) {
-        result.tool = arg;
-      }
-      positionalCount++;
-      i++;
-    }
-  }
-
-  return result;
-}
-
-/**
- * 验证必须参数是否存在
- * @param params 解析后的参数对象
- * @returns 验证结果
- */
-function validateRequiredParams(
-  params: Record<string, string | boolean | undefined>,
-): boolean {
-  if (!params.tool || params.help) {
-    return false;
-  }
-  return true;
-}
-
-/**
- * 尝试解析JSON字符串
- * 先将真实控制字符转义为 JSON 合法形式，处理 shell/AI 传入的原始换行等情况
- * @param str 要解析的字符串
- * @returns 解析后的对象或原始字符串
- */
-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 / @- 语法）
- */
-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;
-}
-
-/**
- * 获取 tool 的参数定义（用于自动分发 --key value 到 path/query）
- */
-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 等
- */
-function formatParams(
-  params: Record<string, string | boolean | undefined>,
-): Record<string, any> {
-  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;
-
-  // 旧格式兼容：--path / --query / --data 是 JSON 字符串
-  if (typeof params.path === 'string') {
-    formatted.path = tryParseJSON(tryReadFileRef(params.path));
-  }
-  if (typeof params.query === 'string') {
-    formatted.query = tryParseJSON(tryReadFileRef(params.query));
-  }
-  if (typeof params.data === 'string') {
-    formatted.data = tryParseJSON(tryReadFileRef(params.data));
-  }
-
-  // 新格式：将其他 --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 reservedKeys = new Set([
-      'module', 'tool', 'help', 'short', 'verbose',
-      'path', 'query', 'data', 'h', 'v',
-    ]);
-
-    for (const [key, value] of Object.entries(params)) {
-      if (reservedKeys.has(key)) continue;
-      if (typeof value === 'boolean') 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 {
-        // 未知参数，尝试放入 query（兼容）
-        if (!formatted.query) formatted.query = {};
-        formatted.query[key] = typeof value === 'string' && !isNaN(Number(value)) ? Number(value) : value;
-      }
-    }
-  }
-
-  // 当没有传递 query 时，要判断当前 tool 是否支持 query
-  if (formatted.query === undefined) {
-    const paramDefs2 = getToolParamDefs(
-      formatted.module,
-      formatted.tool,
-    );
-    if (paramDefs2?.query) {
-      formatted.query = {};
-    }
-  }
-
-  return formatted;
-}
-
-/**
- * 精简响应对象（非 verbose 模式使用）
- * - 去掉 trace（仅错误时保留）
- * - 去掉 header（原始 x-cnb-* 头）
- * - 仅列表 API 时保留分页信息
- */
-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），需要区分处理
- */
-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"，用于匹配摘要配置
- */
-function formatOutput(response: any, verbose: boolean, summary: boolean, toolKey: string): string {
-  // --verbose 模式：输出完整原始信息
-  if (verbose) {
-    return JSON.stringify(response, null, 2);
-  }
-
-  // converter 可能返回裸 data（没有标准 {status, data} 结构），直接输出
-  if (!isStandardResponse(response)) {
-    if (summary) {
-      const summarized = summarizeResponse(response, toolKey);
-      if (summarized !== null) {
-        return JSON.stringify(summarized, null, 2);
-      }
-    }
-    return JSON.stringify(response, null, 2);
-  }
-
-  // 精简响应
-  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 JSON.stringify(compact, null, 2);
-}
-
-/**
- * 显示帮助文档
- * - 无参数：显示顶层帮助（模块列表 + 参数说明 + 用法示例）
- * - 指定 module：显示模块帮助（工具列表）
- * - 指定 module + tool：显示工具帮助（参数详情 + 示例）
- */
-function showHelp(moduleName?: string, tool?: string): void {
-  if (moduleName && tool) {
-    showToolHelp(helpData, moduleName, tool);
-  } else if (moduleName) {
-    showModuleHelp(helpData, moduleName);
-  } else {
-    const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
-
-    // 紧凑的模块列表
-    const moduleParts: string[] = [];
-    for (const [mod, count] of Object.entries(helpData.mainHelp)) {
-      moduleParts.push(`${mod}(${count})`);
-    }
-
-    // 每行放几个模块
-    const lines: string[] = [];
-    let currentLine = '  ';
-    for (const part of moduleParts) {
-      if (currentLine.length + part.length > 78) {
-        lines.push(currentLine);
-        currentLine = '  ' + part + ' ';
-      } else {
-        currentLine += part + ' ';
-      }
-    }
-    if (currentLine.trim()) lines.push(currentLine);
-
-    const helpMsg = `
-CNB OpenAPI CLI
-
-模块(tool数量):
-${lines.join('\n')}
-
-参数:
-  <module>          模块名称 (如: issues, pulls, git)
-  <tool>            工具名称 (如: list-issues, get-issue)
-  --key value       路径或查询参数，CLI 自动识别归类
-  --data 'JSON'     请求体参数，JSON 字符串
-  --verbose         输出完整原始响应（含 trace、header 等全部字段）
-  --help            显示帮助文档
-  --short           显示当前仓库的快捷命令
-
-用法: ${cliCmd} issues list-issues --repo my-org/my-repo --page 1 --pageSize 10
-      ${cliCmd} issues create-issue --repo my-org/my-repo --data '{"title":"Bug"}'
-帮助: ${cliCmd} <module> --help
-      ${cliCmd} <module> <tool> --help
-快捷: ${cliCmd} --short
-`;
-    console.log(helpMsg);
-  }
-}
-
-/**
- * 主函数
- */
-async function main() {
-  const params = parseArguments();
-
-  // 处理 --short
-  if (params.short) {
-    showShort();
-    process.exit(0);
-  }
-
-  // 尝试解析快捷命令
-  const shortcut = resolveShortcut(
-    params.module as string | undefined,
-    params.tool as string | undefined,
-  );
-  if (shortcut) {
-    params.module = shortcut.module;
-    params.tool = shortcut.tool;
-
-    // 自动注入 path 参数
-    for (const [key, value] of Object.entries(shortcut.autoPath)) {
-      if (!params[key]) {
-        params[key] = value;
-      }
-    }
-
-    // 自动注入 data 参数
-    if (shortcut.autoData && !params.data) {
-      params.data = JSON.stringify(shortcut.autoData);
-    }
-  }
-
-  // 验证必须参数
-  if (!validateRequiredParams(params)) {
-    showHelp(
-      params.module as string | undefined,
-      params.tool as string | undefined,
-    );
-    process.exit(0);
-  }
-
-  // 格式化参数
-  const formattedParams = formatParams(params);
-
-  // 参数预检：缺少必填 path 参数时自动输出 tool help
-  const toolHelpData = helpData.modulesHelp?.[formattedParams.module]?.[formattedParams.tool];
-  if (toolHelpData) {
-    const pathDef = toolHelpData.help?.parameter?.path;
-    if (pathDef) {
-      const missingRequired = Object.entries(pathDef)
-        .filter(([, p]: [string, any]) => p.required && !formattedParams.path?.[p.name])
-        .map(([k]) => `--${k}`);
-      if (missingRequired.length > 0) {
-        console.error(`缺少必填参数: ${missingRequired.join(', ')}\n`);
-        showToolHelp(helpData, formattedParams.module, formattedParams.tool);
-        process.exit(1);
-      }
-    }
-  }
-
-  // 动态引入模块
-  const toolPath = path.join(
-    __dirname,
-    '../modules',
-    `${formattedParams.module}/${formattedParams.tool}.js`,
-  );
-
-  if (!fs.existsSync(toolPath)) {
-    console.error(`工具文件不存在: ${toolPath}`);
-    process.exit(1);
-  }
-
-  const toolModule = require(toolPath);
-  const toolFunction = toolModule.default;
-
-  if (!toolFunction) {
-    console.error(`工具函数不存在`);
-    process.exit(1);
-  }
-
-  const toolsParam: any[] = [];
-  let pathAndQueryParams: Record<string, any> | string | null = null;
-
-  if (
-    formattedParams.path &&
-    Object.keys(formattedParams.path).length === 1 &&
-    !formattedParams.query
-  ) {
-    pathAndQueryParams =
-      formattedParams.path[Object.keys(formattedParams.path)[0]];
-  } else {
-    if (formattedParams.path) {
-      pathAndQueryParams = { ...formattedParams.path };
-    }
-
-    if (formattedParams.query) {
-      pathAndQueryParams = {
-        ...(pathAndQueryParams && typeof pathAndQueryParams === 'object'
-          ? pathAndQueryParams
-          : {}),
-        ...formattedParams.query,
-      };
-    }
-  }
-
-  if (pathAndQueryParams) {
-    toolsParam.push(pathAndQueryParams);
-  }
-
-  // 上传快捷命令：走完整上传流程（获取 URL → PUT 文件 → 返回结果）
-  let data: any;
-  if (shortcut?.upload) {
-    data = await handleUpload(shortcut, formattedParams.data?.file, toolFunction, pathAndQueryParams as { repo: string; number?: string });
-  } else {
-    if (formattedParams.data) {
-      toolsParam.push(formattedParams.data);
-    }
-    data = await toolFunction(...toolsParam);
-  }
-  const toolKey = `${formattedParams.module}/${formattedParams.tool}`;
-  // 快捷命令默认输出摘要，--verbose 时输出全部信息
-  const isVerbose = !!formattedParams.verbose;
-  const isSummary = shortcut ? !isVerbose : false;
-  console.log(formatOutput(data, isVerbose, isSummary, toolKey));
-}
-
-main();
+program.parseAsync(process.argv);

package/client/lib/execute-action.ts

@@ -0,0 +1,126 @@
+import fs from 'fs';
+import path from 'path';
+import { Command } from 'commander';
+import { showShort, resolveShortcut } from '../shortcuts';
+import { handleUpload } from '../utils/upload';
+import { formatParams } from './format-params';
+import { formatOutput } from './format-output';
+
+export async function executeAction(
+  moduleArg: string | undefined,
+  toolArg: string | undefined,
+  opts: Record<string, any>,
+  parentCmd: Command,
+) {
+  // Commander 已解析好所有 option，直接构建 params
+  const params: Record<string, string | boolean | undefined> = {};
+
+  if (moduleArg) params.module = moduleArg;
+  if (toolArg) params.tool = toolArg;
+
+  // 从 Commander 解析好的 opts 中取出所有参数
+  const reservedKeys = new Set(['help', 'h']);
+  for (const [key, value] of Object.entries(opts)) {
+    if (reservedKeys.has(key)) continue;
+    if (value !== undefined) {
+      params[key] = value;
+    }
+  }
+
+  if (params.short) {
+    showShort();
+    process.exit(0);
+  }
+
+  const shortcut = resolveShortcut(
+    params.module as string | undefined,
+    params.tool as string | undefined,
+  );
+  if (shortcut) {
+    params.module = shortcut.module;
+    params.tool = shortcut.tool;
+
+    for (const [key, value] of Object.entries(shortcut.autoPath)) {
+      if (!params[key]) {
+        params[key] = value;
+      }
+    }
+
+    if (shortcut.autoData) {
+      for (const [key, value] of Object.entries(shortcut.autoData)) {
+        if (params[key] === undefined) {
+          params[key] = value;
+        }
+      }
+    }
+  }
+
+  if (!params.tool) {
+    parentCmd.help();
+  }
+
+  const formattedParams = formatParams(params);
+
+  const toolPath = path.join(
+    __dirname,
+    '../../modules',
+    `${formattedParams.module}/${formattedParams.tool}.js`,
+  );
+
+  if (!fs.existsSync(toolPath)) {
+    console.error(`工具文件不存在: ${toolPath}`);
+    process.exit(1);
+  }
+
+  const toolModule = require(toolPath);
+  const toolFunction = toolModule.default;
+
+  if (!toolFunction) {
+    console.error(`工具函数不存在`);
+    process.exit(1);
+  }
+
+  const toolsParam: any[] = [];
+  let pathAndQueryParams: Record<string, any> | string | null = null;
+
+  if (
+    formattedParams.path &&
+    Object.keys(formattedParams.path).length === 1 &&
+    !formattedParams.query
+  ) {
+    pathAndQueryParams =
+      formattedParams.path[Object.keys(formattedParams.path)[0]];
+  } else {
+    if (formattedParams.path) {
+      pathAndQueryParams = { ...formattedParams.path };
+    }
+
+    if (formattedParams.query) {
+      pathAndQueryParams = {
+        ...(pathAndQueryParams && typeof pathAndQueryParams === 'object'
+          ? pathAndQueryParams
+          : {}),
+        ...formattedParams.query,
+      };
+    }
+  }
+
+  if (pathAndQueryParams) {
+    toolsParam.push(pathAndQueryParams);
+  }
+
+  let data: any;
+  if (shortcut?.upload) {
+    data = await handleUpload(shortcut, formattedParams.data?.file, toolFunction, pathAndQueryParams as { repo: string; number?: string });
+  } else {
+    if (formattedParams.data) {
+      toolsParam.push(formattedParams.data);
+    }
+    data = await toolFunction(...toolsParam);
+  }
+
+  const toolKey = `${formattedParams.module}/${formattedParams.tool}`;
+  const isVerbose = !!formattedParams.verbose;
+  const isSummary = shortcut ? !isVerbose : false;
+  console.log(formatOutput(data, isVerbose, isSummary, toolKey));
+}

package/client/lib/extra-help.ts

@@ -0,0 +1,15 @@
+/**
+ * 生成额外的帮助提示字符串
+ * 包含模块列表和用法示例，供 commander .addHelpText() 使用
+ */
+export function getExtraHelpText(): string {
+  const cliCmd = process.env.CNB_CLI_CMD || 'cnb';
+
+  return `
+
+用法: ${cliCmd} issues list-issues --repo my-org/my-repo --page 1 --pageSize 10
+      ${cliCmd} issues create-issue --repo my-org/my-repo --title Bug
+帮助: ${cliCmd} <module> --help
+      ${cliCmd} <module> <tool> --help
+快捷: ${cliCmd} --short`;
+}

package/client/lib/flat-options-data.ts

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