@lark-apaas/miaoda-cli 0.1.1 → 0.1.2-alpha.08ca9fb

package/dist/cli/handlers/observability/trace.js

@@ -0,0 +1,102 @@
+"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.handleObservabilityTraceList = handleObservabilityTraceList;
+exports.handleObservabilityTraceGet = handleObservabilityTraceGet;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../api/observability/index");
+const helpers_1 = require("./helpers");
+/** miaoda observability trace list */
+async function handleObservabilityTraceList(opts) {
+    const appID = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    const appEnv = "runtime";
+    const limit = (0, helpers_1.validateLimit)(opts.limit ?? 50);
+    // 过滤 key 对齐 BAM Span 字段名：
+    //   - 顶层字段：traceID（注意大小写）
+    //   - attributes 业务字段：user_id（snake_case）
+    //   - 入口 span：BAM 没有 entrySpanName fieldFilter，统一走 fuzzyFilter（trace endpoint
+    //     默认作用于 span name），所以 --root-span 不进 fieldFilters
+    const fieldFilters = (0, helpers_1.buildFieldFilters)([
+        { key: "trace_id", value: opts.traceId ? (0, helpers_1.eqFilter)(opts.traceId) : undefined },
+        { key: "user_id", value: opts.userId ? (0, helpers_1.eqFilter)(opts.userId, "i64") : undefined },
+    ]);
+    const req = {
+        appID,
+        appEnv,
+        startTimestampNs: (0, helpers_1.parseToNs)(opts.since),
+        endTimestampNs: (0, helpers_1.parseToNs)(opts.until),
+        limit,
+        pageToken: opts.cursor,
+        fieldFilters,
+        fuzzyFilter: opts.rootSpan ? (0, helpers_1.fuzzyFilter)(opts.rootSpan) : undefined,
+    };
+    const resp = await api.observability.searchTraces(req);
+    emitSearchTracesResponse(resp);
+}
+function emitSearchTracesResponse(resp) {
+    (0, output_1.emit)({
+        data: resp.spans ?? [],
+        next_cursor: resp.hasMore ? resp.nextPageToken : null,
+        has_more: resp.hasMore,
+    }, index_1.spanSchema);
+}
+/** miaoda observability trace get <trace-id> */
+async function handleObservabilityTraceGet(opts) {
+    if (!opts.traceId)
+        (0, shared_1.failArgs)("<trace-id> 必填");
+    const appID = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    const appEnv = "runtime";
+    const resp = await api.observability.getTraces({
+        appID,
+        appEnv,
+        traceID: opts.traceId,
+        withLogSeverityCount: opts.withLogSeverityCount,
+    });
+    emitGetTraceResponse(resp);
+}
+function emitGetTraceResponse(resp) {
+    // JSON 模式：保持单条信封语义，便于下游一次解析
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({
+            data: { spans: resp.spans ?? [], isBreak: resp.isBreak },
+        });
+        return;
+    }
+    // Pretty 模式：先打头部 key-value（断链状态等元信息），再按 spanSchema 渲染主表
+    (0, output_1.emit)({ data: { isBreak: resp.isBreak } });
+    (0, output_1.emit)({ data: resp.spans ?? [] }, index_1.spanSchema);
+}

package/dist/cli/handlers/plugin/plugin-local.js

@@ -82,7 +82,9 @@ function parsePluginName(input) {
 function readPackageJson() {
     const pkgPath = getPackageJsonPath();
     if (!node_fs_1.default.existsSync(pkgPath)) {
-        throw new error_1.AppError("PKG_JSON_NOT_FOUND", "package.json not found in current directory", { next_actions: ["在应用项目根目录运行"] });
+        throw new error_1.AppError("PKG_JSON_NOT_FOUND", "package.json not found in current directory", {
+            next_actions: ["在应用项目根目录运行"],
+        });
     }
     const content = node_fs_1.default.readFileSync(pkgPath, "utf-8");
     return JSON.parse(content);
@@ -189,9 +191,14 @@ function installMissingDeps(deps) {
     if (deps.length === 0)
         return;
     (0, logger_1.log)("plugin", `Installing missing dependencies: ${deps.join(", ")}`);
-    const result = (0, node_child_process_1.spawnSync)("npm", ["install", ...deps, "--no-save", "--no-package-lock"], { cwd: getProjectRoot(), stdio: "inherit" });
+    const result = (0, node_child_process_1.spawnSync)("npm", ["install", ...deps, "--no-save", "--no-package-lock"], {
+        cwd: getProjectRoot(),
+        stdio: "inherit",
+    });
     if (result.error) {
-        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, { next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"] });
+        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, {
+            next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"],
+        });
     }
     if (result.status !== 0) {
         throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed with exit code ${String(result.status)}`, { next_actions: ["检查上方 npm 输出日志定位具体错误"] });
@@ -200,7 +207,9 @@ function installMissingDeps(deps) {
 function npmInstall(tgzPath) {
     const result = (0, node_child_process_1.spawnSync)("npm", ["install", tgzPath, "--no-save", "--no-package-lock", "--ignore-scripts"], { cwd: getProjectRoot(), stdio: "inherit" });
     if (result.error) {
-        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, { next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"] });
+        throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed: ${result.error.message}`, {
+            next_actions: ["确认本机已安装 npm，可 --verbose 查看执行详情"],
+        });
     }
     if (result.status !== 0) {
         throw new error_1.AppError("INTERNAL_NPM_FAILED", `npm install failed with exit code ${String(result.status)}`, { next_actions: ["检查上方 npm 输出日志定位具体错误"] });
@@ -232,7 +241,9 @@ function listCapabilityIds() {
 function readCapability(id) {
     const filePath = node_path_1.default.join(getCapabilitiesDir(), `${id}.json`);
     if (!node_fs_1.default.existsSync(filePath)) {
-        throw new error_1.AppError("CAPABILITY_NOT_FOUND", `Capability not found: ${id}`, { next_actions: ["运行 miaoda plugin list 查看所有可用 capability id"] });
+        throw new error_1.AppError("CAPABILITY_NOT_FOUND", `Capability not found: ${id}`, {
+            next_actions: ["运行 miaoda plugin list 查看所有可用 capability id"],
+        });
     }
     try {
         const content = node_fs_1.default.readFileSync(filePath, "utf-8");
@@ -240,7 +251,9 @@ function readCapability(id) {
     }
     catch (error) {
         if (error instanceof SyntaxError) {
-            throw new error_1.AppError("INVALID_JSON", `Invalid JSON in capability file: ${id}.json`, { next_actions: [`检查 server/capabilities/${id}.json 的 JSON 语法`] });
+            throw new error_1.AppError("INVALID_JSON", `Invalid JSON in capability file: ${id}.json`, {
+                next_actions: [`检查 server/capabilities/${id}.json 的 JSON 语法`],
+            });
         }
         throw error;
     }
@@ -303,7 +316,9 @@ async function loadPlugin(pluginKey) {
     }
     catch (error) {
         if (error.code === "MODULE_NOT_FOUND") {
-            throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not installed: ${pluginKey}`, { next_actions: [`运行 miaoda plugin install ${pluginKey}`] });
+            throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin not installed: ${pluginKey}`, {
+                next_actions: [`运行 miaoda plugin install ${pluginKey}`],
+            });
         }
         throw new error_1.AppError("INTERNAL_PLUGIN_LOAD_FAILED", `Failed to load plugin ${pluginKey}: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -314,8 +329,7 @@ async function hydrateCapability(capability) {
         if (manifest.actions.length === 0) {
             throw new error_1.AppError("INTERNAL_PLUGIN_LOAD_FAILED", `Plugin ${capability.pluginKey} has no actions defined`);
         }
-        const hasDynamic = manifest.actions.some((action) => isDynamicSchema(action.inputSchema) ||
-            isDynamicSchema(action.outputSchema));
+        const hasDynamic = manifest.actions.some((action) => isDynamicSchema(action.inputSchema) || isDynamicSchema(action.outputSchema));
         let pluginInstance = null;
         if (hasDynamic) {
             const plugin = await loadPlugin(capability.pluginKey);

package/dist/cli/handlers/plugin/plugin.js

@@ -44,7 +44,9 @@ const output_1 = require("../../../utils/output");
 const error_1 = require("../../../utils/error");
 const logger_1 = require("../../../utils/logger");
 const plugin_local_1 = require("./plugin-local");
-const log = (msg) => { (0, logger_1.log)("plugin", msg); };
+const log = (msg) => {
+    (0, logger_1.log)("plugin", msg);
+};
 // ── Install ──
 function syncActionPluginsRecord(name, version) {
     const plugins = (0, plugin_local_1.readActionPlugins)();
@@ -63,7 +65,9 @@ async function installOne(nameWithVersion) {
             if (actualVersion === requestedVersion) {
                 log(`${name}@${requestedVersion} already installed`);
                 syncActionPluginsRecord(name, actualVersion);
-                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => { });
+                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => {
+                    /* fire-and-forget */
+                });
                 return { name, version: actualVersion, success: true, skipped: true };
             }
         }
@@ -74,7 +78,9 @@ async function installOne(nameWithVersion) {
             if (actualVersion === targetVersion) {
                 log(`${name} already up to date (${actualVersion})`);
                 syncActionPluginsRecord(name, actualVersion);
-                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => { });
+                api.plugin.reportCreateInstanceEvent(name, actualVersion).catch(() => {
+                    /* fire-and-forget */
+                });
                 return { name, version: actualVersion, success: true, skipped: true };
             }
             log(`Found newer version: ${targetVersion} (installed: ${actualVersion ?? "none"})`);
@@ -106,8 +112,12 @@ async function installOne(nameWithVersion) {
         (0, plugin_local_1.writeActionPlugins)(plugins);
         const source = fromCache ? "from cache" : "downloaded";
         log(`Installed ${name}@${installedVersion} (${source})`);
-        api.plugin.reportInstallEvent(name, installedVersion).catch(() => { });
-        api.plugin.reportCreateInstanceEvent(name, installedVersion).catch(() => { });
+        api.plugin.reportInstallEvent(name, installedVersion).catch(() => {
+            /* fire-and-forget */
+        });
+        api.plugin.reportCreateInstanceEvent(name, installedVersion).catch(() => {
+            /* fire-and-forget */
+        });
         return { name, version: installedVersion, success: true };
     }
     catch (error) {
@@ -193,7 +203,9 @@ async function handlePluginUpdate(opts) {
 function handlePluginRemove(opts) {
     const { name } = (0, plugin_local_1.parsePluginName)(opts.name);
     if (!(0, plugin_local_1.isPluginInstalled)(name)) {
-        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin ${name} is not installed`, { next_actions: ["运行 miaoda plugin list-packages 查看已安装插件"] });
+        throw new error_1.AppError("PLUGIN_NOT_FOUND", `Plugin ${name} is not installed`, {
+            next_actions: ["运行 miaoda plugin list-packages 查看已安装插件"],
+        });
     }
     (0, plugin_local_1.removePluginDirectory)(name);
     const plugins = (0, plugin_local_1.readActionPlugins)();
@@ -263,7 +275,9 @@ async function handlePluginInit() {
 // ── List (capability configs) ──
 async function handlePluginList(opts) {
     if (!(0, plugin_local_1.capabilitiesDirExists)()) {
-        throw new error_1.AppError("CAPABILITIES_DIR_NOT_FOUND", "server/capabilities directory not found", { next_actions: ["当前目录必须是含 server/capabilities/ 的应用项目"] });
+        throw new error_1.AppError("CAPABILITIES_DIR_NOT_FOUND", "server/capabilities directory not found", {
+            next_actions: ["当前目录必须是含 server/capabilities/ 的应用项目"],
+        });
     }
     if (opts.id) {
         const capability = (0, plugin_local_1.readCapability)(opts.id);

package/dist/cli/help.js

@@ -115,7 +115,9 @@ class MiaodaHelp extends commander_1.Help {
         out.push("Usage:", `  ${helper.commandUsage(cmd)}`, "");
         // 3. Commands（仅父级命令组有，spec 要求 Commands 在 Flags 前）
         //    spec 不展示 Arguments 段，参数说明放在 description 文本里
-        const subs = helper.visibleCommands(cmd).map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
+        const subs = helper
+            .visibleCommands(cmd)
+            .map((c) => formatItem(helper.subcommandTerm(c), helper.subcommandDescription(c)));
         if (subs.length) {
             out.push("Commands:", formatList(subs), "");
         }
@@ -125,7 +127,8 @@ class MiaodaHelp extends commander_1.Help {
         //    - `-h, --help` 永远不放 Flags 段，统一放 Global Flags（spec 约定）
         const isParent = subs.length > 0;
         if (!isRoot && !isParent) {
-            const opts = helper.visibleOptions(cmd)
+            const opts = helper
+                .visibleOptions(cmd)
                 .filter((o) => !isHelpOption(o))
                 .map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
             if (opts.length) {

package/dist/cli/version.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRootVersionArg = resolveRootVersionArg;
+function resolveRootVersionArg(args) {
+    if (args.length === 1 && (args[0] === "-v" || args[0] === "--version"))
+        return "show";
+    if (args.some(isLooseVersionArg))
+        return "invalid-variant";
+    if (args.includes("-v") || args.includes("--version"))
+        return "invalid-placement";
+    return "none";
+}
+function isLooseVersionArg(arg) {
+    return ((arg.startsWith("-v") && arg !== "-v") || (arg.startsWith("--version") && arg !== "--version"));
+}

package/dist/main.js

@@ -5,10 +5,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const index_1 = require("./cli/commands/index");
+const shared_1 = require("./cli/commands/shared");
 const help_1 = require("./cli/help");
 const config_1 = require("./utils/config");
 const log_id_1 = require("./utils/log_id");
 const output_1 = require("./utils/output");
+const error_1 = require("./utils/error");
+const version_1 = require("./cli/version");
 const package_json_1 = __importDefault(require("../package.json"));
 // MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）：
 // 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的
@@ -20,11 +23,14 @@ const program = new commander_1.Command();
 const { version } = package_json_1.default;
 program
     .name("miaoda")
-    .description("妙搭平台 CLI，提供数据服务、文件存储、插件管理等命令行操作。")
+    .description("妙搭平台 CLI，提供数据服务、文件存储等命令行操作。")
     .usage("<command> [flags]")
-    .version(version, "-v, --version", "显示版本号")
+    .option("-v, --version", "显示版本号")
     .option("--json [fields]", "JSON 输出，可选字段级选择")
-    .option("--output <format>", "输出格式（pretty|json）", "pretty")
+    .addOption(new commander_1.Option("--output <format>", "输出格式（pretty | json，大小写不敏感）")
+    .choices(["pretty", "json"])
+    .argParser((0, shared_1.caseInsensitiveChoice)(["pretty", "json"]))
+    .default("pretty"))
     .option("--verbose", "debug 日志到 stderr")
     .helpOption("-h, --help", "显示帮助信息")
     .hook("preAction", (_thisCmd, actionCmd) => {
@@ -33,7 +39,21 @@ program
     (0, config_1.initConfigFromOpts)(opts);
 });
 (0, index_1.registerCommands)(program);
-program.parseAsync(process.argv).catch((err) => {
-    (0, output_1.emitError)(err);
-    process.exitCode = 1;
-});
+const versionArg = (0, version_1.resolveRootVersionArg)(process.argv.slice(2));
+if (versionArg === "show") {
+    process.stdout.write(`${version}\n`);
+}
+else if (versionArg === "invalid-variant") {
+    (0, output_1.emitError)(new error_1.AppError("ARGS_INVALID", "版本参数仅支持精确的 -v 或 --version"));
+    process.exitCode = 2;
+}
+else if (versionArg === "invalid-placement") {
+    (0, output_1.emitError)(new error_1.AppError("ARGS_INVALID", "-v / --version 仅可在根命令单独使用，不能与其他命令或参数混用"));
+    process.exitCode = 2;
+}
+else {
+    program.parseAsync(process.argv).catch((err) => {
+        (0, output_1.emitError)(err);
+        process.exitCode = 1;
+    });
+}

package/dist/utils/colors.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * 终端彩色高亮的语义层封装。
+ *
+ * 三层结构（自上而下：稳定→灵活）：
+ *
+ *   1. **ColorAdapter**（公共契约）：6 个语义方法 string → string，业务代码
+ *      只接触这层，对底层库 0 感知。
+ *   2. **ColorFactory**（适配器签名）：`(useColor: boolean) => ColorAdapter`，
+ *      把"是否染色"参数化，便于按需构造。一个三方库对应一个 factory 实现。
+ *   3. **当前底层库实现**：picocolors（[picocolors npm](https://www.npmjs.com/package/picocolors)，~3KB）。
+ *      切换到 chalk / kleur 等只需新增一个 ColorFactory 实现，并改最下方的
+ *      `factory =` 一行赋值，业务代码与 ColorAdapter contract 0 改动。
+ *
+ * # 色谱（对齐 spec）
+ *
+ *   - header     表头 / 命令名 / key 标签：bold + cyan
+ *   - highlight  强调值（表名等）：cyan
+ *   - success    ✓ Uploaded / ✓ Deleted：green
+ *   - fail       ✗ / Error:：red
+ *   - warn       ⚠ Approaching quota：yellow
+ *   - muted      NULL / 辅助 hint / 次要信息：dim + gray
+ *
+ * # 染色判定（NO_COLOR / FORCE_COLOR / TTY，[no-color.org](https://no-color.org/) 业界标准）
+ *
+ *   - `NO_COLOR=1`            强制关颜色（任何非空值生效）
+ *   - `FORCE_COLOR=1`         强制开颜色（管道 / CI 场景）
+ *   - 否则按 `process.stdout.isTTY` 判定
+ *
+ * 每次调用 `c.xxx(s)` 时按当前状态实时构造 adapter——避免模块加载时缓存的
+ * `process.stdout.isTTY` 与测试 / pipe 切换脱节。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.c = void 0;
+exports.shouldColorize = shouldColorize;
+const picocolors_1 = require("picocolors");
+// ──────────────────────────────────────────────────────────────────────
+// 2. 库无关的染色判定：哪个 factory 都能复用
+// ──────────────────────────────────────────────────────────────────────
+/**
+ * 当前是否应当染色。读取的是**调用时**的状态，而非模块加载时缓存——
+ * 测试经常 `Object.defineProperty(process.stdout, "isTTY", ...)` 实时切换，
+ * 这里直接每次问 process。
+ *
+ * 优先级：FORCE_COLOR > NO_COLOR > TTY。
+ */
+function shouldColorize() {
+    const env = process.env;
+    const noColor = env.NO_COLOR != null && env.NO_COLOR !== "";
+    const forceColor = env.FORCE_COLOR != null && env.FORCE_COLOR !== "";
+    const isTTY = process.stdout.isTTY === true;
+    return forceColor || (!noColor && isTTY);
+}
+/** picocolors 实现：当前生产用 factory。~3KB，业界 CLI 标准之一。 */
+const picocolorsFactory = (useColor) => {
+    const x = (0, picocolors_1.createColors)(useColor);
+    return {
+        header: (s) => x.bold(x.cyan(s)),
+        highlight: (s) => x.cyan(s),
+        success: (s) => x.green(s),
+        fail: (s) => x.red(s),
+        warn: (s) => x.yellow(s),
+        muted: (s) => x.dim(x.gray(s)),
+    };
+};
+// ──────────────────────────────────────────────────────────────────────
+// 4. 唯一切换点：换库改这一行（其它都不用动）
+// ──────────────────────────────────────────────────────────────────────
+//
+// 切换示例：
+//
+//   import chalk, { Chalk } from "chalk";
+//   const chalkFactory: ColorFactory = (useColor) => {
+//     const k = new Chalk({ level: useColor ? 1 : 0 });
+//     return {
+//       header:    (s) => k.bold.cyan(s),
+//       highlight: (s) => k.cyan(s),
+//       success:   (s) => k.green(s),
+//       fail:      (s) => k.red(s),
+//       warn:      (s) => k.yellow(s),
+//       muted:     (s) => k.dim.gray(s),
+//     };
+//   };
+//   const factory: ColorFactory = chalkFactory;   // ← 改这里
+//
+const factory = picocolorsFactory;
+// ──────────────────────────────────────────────────────────────────────
+// 5. 公共出口：业务代码 import { c } from "../utils/colors"
+// ──────────────────────────────────────────────────────────────────────
+/** 语义染色器：业务代码唯一接触的对象。底层库切换 0 感知。 */
+exports.c = {
+    header: (s) => factory(shouldColorize()).header(s),
+    highlight: (s) => factory(shouldColorize()).highlight(s),
+    success: (s) => factory(shouldColorize()).success(s),
+    fail: (s) => factory(shouldColorize()).fail(s),
+    warn: (s) => factory(shouldColorize()).warn(s),
+    muted: (s) => factory(shouldColorize()).muted(s),
+};

package/dist/utils/devops-error.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapDevopsError = mapDevopsError;
+const error_1 = require("./error");
+/**
+ * 把 BAM lark.apaas.devops 的业务码（数字字符串）映射成 CLI 错误码。
+ * 来源：服务端技术方案 wiki L7P8wlNQ5iyShLkxzlOcCo8LnTg「业务错误码映射表」。
+ *
+ * 放在 utils 下而不是某个具体 api 域里：app / deploy 都跑在 lark.apaas.devops
+ * 这同一 PSM，业务码命名空间也共享；boundaries 规则又禁止 api 域间互引。
+ */
+function mapDevopsError(bizCode, message) {
+    switch (bizCode) {
+        case "400002577":
+        case "400002569":
+            return new error_1.AppError("APP_NOT_FOUND", message, {
+                next_actions: ["Run `miaoda app list` to see available apps"],
+            });
+        case "400002579":
+            return new error_1.AppError("APP_PERMISSION_DENIED", message);
+        case "400002575":
+            return new error_1.AppError("INVALID_ARG_VALUE", message, {
+                next_actions: ["缩短 --name / --description 后重试（后端有长度限制）"],
+            });
+        default:
+            return undefined;
+    }
+}

package/dist/utils/error.js

@@ -6,6 +6,14 @@ class AppError extends Error {
     retryable;
     next_actions;
     statement_index;
+    total_statements;
+    /**
+     * 多语句失败时由 api.db.execSql 透传服务端 results（已成功的 statement 原始结构）。
+     * 由 db sql handler 转成 PRD 友好的 `completed` 数组 + 推断 `rolled_back` 后挂回到本对象。
+     */
+    partial_results;
+    completed;
+    rolled_back;
     constructor(code, message, opts) {
         super(message);
         this.name = "AppError";
@@ -21,6 +29,9 @@ class AppError extends Error {
             retryable: this.retryable,
             next_actions: this.next_actions,
             statement_index: this.statement_index,
+            total_statements: this.total_statements,
+            completed: this.completed,
+            rolled_back: this.rolled_back,
         };
     }
 }

package/dist/utils/fuzzy-match.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * 模糊匹配：基于 Levenshtein 编辑距离的"did-you-mean"建议器。
+ *
+ * 用于 CLI 错误路径的拼写纠错提示——当用户输入的 token（关键字 / 表名 / 列名）
+ * 与某个有效候选词"接近"时，给出 "Did you mean X?" 类的 hint。
+ *
+ * # 设计取舍
+ *
+ *   - **算法**：Damerau-Levenshtein DP（在标准 Levenshtein 基础上把"相邻字符
+ *     交换"算 1 步编辑——SQL 用户最常见的拼写错误就是 FORM/FROM、SELCT/SELECT
+ *     这类 transposition；纯 Levenshtein 把它们算 2 步会过严，触发不到 hint）。
+ *     约 30 行二维 DP 实现，不引第三方库；业界 CLI 拼写纠错事实标准。
+ *   - **大小写不敏感**：CLI 用户混用 SELECT / select 是常态，统一 lowercase 比较
+ *   - **阈值按候选词长度自适应**：避免短词过度匹配（"id" 不应该建议成 "in"）
+ *       len ≤ 4：max 1 编辑（短词严）
+ *       len 5-8：max 2 编辑
+ *       len ≥ 9：max 3 编辑（长词宽）
+ *   - **同分多候选**：返第一个；调用方负责候选词列表的稳定排序
+ *   - **找不到不强凑**：阈值外返 null，不"硬贴"无关建议
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levenshtein = levenshtein;
+exports.suggest = suggest;
+/**
+ * 计算两个字符串的 Damerau-Levenshtein 编辑距离（不区分大小写）。
+ *
+ * 在标准 Levenshtein（增 / 删 / 替换）基础上加"相邻字符交换"作为单步编辑。
+ * 二维 DP 实现（transposition 需要回看 dp[i-2][j-2]，所以不再用单行优化）。
+ * 候选词通常 < 30 字符，二维 DP 的常数空间开销可忽略。
+ */
+function levenshtein(a, b) {
+    const aa = a.toLowerCase();
+    const bb = b.toLowerCase();
+    const m = aa.length;
+    const n = bb.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = aa[i - 1] === bb[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, // 删除
+            dp[i][j - 1] + 1, // 插入
+            dp[i - 1][j - 1] + cost);
+            // transposition: 当前字符 = 对方前一字符 && 我方前一字符 = 对方当前字符
+            // 例：aa="form", bb="from"，i=2,j=2 时 aa[1]=o=bb[0]=f? 不命中；i=3,j=3
+            // 时 aa[2]=r=bb[1]=r? bb[2]=o, aa[1]=o → 命中 → dp[3][3] = dp[1][1] + 1 = 1
+            if (i > 1 && j > 1 && aa[i - 1] === bb[j - 2] && aa[i - 2] === bb[j - 1]) {
+                dp[i][j] = Math.min(dp[i][j], dp[i - 2][j - 2] + 1);
+            }
+        }
+    }
+    return dp[m][n];
+}
+/** 默认阈值：候选词越短匹配越严，越长越宽。避免 "id" 错配 "in" 这种 false positive。 */
+function defaultThreshold(len) {
+    if (len <= 4)
+        return 1;
+    if (len <= 8)
+        return 2;
+    return 3;
+}
+/**
+ * 在候选词列表里找与 input 最相近的一个。
+ *
+ * 距离 ≤ 阈值时按"距离最小"返回；多个候选词相同距离时返"列表中最先出现"的；
+ * 阈值外没有命中返 null（调用方按 null 静默不加 hint，不要强凑）。
+ */
+function suggest(input, candidates, opts) {
+    if (!input || candidates.length === 0)
+        return null;
+    const threshold = opts?.maxDistance ?? defaultThreshold;
+    let best = null;
+    let bestDist = Number.POSITIVE_INFINITY;
+    for (const cand of candidates) {
+        const d = levenshtein(input, cand);
+        const limit = threshold(cand.length);
+        if (d <= limit && d < bestDist) {
+            best = cand;
+            bestDist = d;
+        }
+    }
+    return best;
+}

package/dist/utils/git.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCurrentGitBranch = getCurrentGitBranch;
+const node_child_process_1 = require("node:child_process");
+/**
+ * 读取 cwd 所在仓库的当前分支名。
+ *
+ * 不在 git 仓库、git 不可用、或处于 detached HEAD 时返回 undefined，
+ * 让调用方决定回退策略（如交给后端使用应用默认分支）。
+ */
+function getCurrentGitBranch(cwd = process.cwd()) {
+    let result;
+    try {
+        result = (0, node_child_process_1.spawnSync)("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+            cwd,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+    }
+    catch {
+        return undefined;
+    }
+    if (result.status !== 0)
+        return undefined;
+    const branch = result.stdout.trim();
+    if (!branch || branch === "HEAD")
+        return undefined;
+    return branch;
+}