@lark-apaas/miaoda-cli 0.1.0 → 0.1.1-alpha.06e1628

package/dist/cli/handlers/file/sign.js

@@ -0,0 +1,96 @@
+"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.handleFileSign = handleFileSign;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const render_1 = require("../../../utils/render");
+const error_1 = require("../../../utils/error");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../api/file/index");
+const MAX_EXPIRES_SECONDS = 30 * 86400;
+const DEFAULT_EXPIRES_SECONDS = 86400; // 1d（PRD 规定）
+/**
+ * 把 <file> 解析为后端 sign 可用的 filePath。
+ *
+ * - `looksLikePath(input)`（`/path`、含 `/` 的 key、后端生成的 fileKey）→ 直接走 path，不反查
+ * - 其他输入按 file_name 走 FilterExpression 精确查询（多匹配 → AMBIGUOUS_FILE_NAME）
+ */
+async function resolveFilePath(appId, input) {
+    if ((0, index_1.looksLikePath)(input))
+        return (0, index_1.toAbsolutePath)(input);
+    const [resolved] = await api.file.resolveInputs({
+        appId,
+        inputs: [input],
+        forceAs: "name",
+    });
+    if (resolved.status === "error") {
+        throw new error_1.AppError(resolved.error.code, resolved.error.message, {
+            next_actions: resolved.error.hint ? [resolved.error.hint] : undefined,
+        });
+    }
+    return resolved.file.path;
+}
+async function handleFileSign(file, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    let expiresSec = DEFAULT_EXPIRES_SECONDS;
+    if (opts.expires) {
+        expiresSec = (0, render_1.parseDuration)(opts.expires);
+        if (expiresSec > MAX_EXPIRES_SECONDS) {
+            throw new error_1.AppError("FILE_SIGN_DURATION_EXCEEDED", `Expires duration '${opts.expires}' exceeds the maximum of 30d`, {
+                next_actions: [
+                    `Maximum allowed value is 30d. Use \`--expires 30d\` for the longest link.`,
+                ],
+            });
+        }
+    }
+    const filePath = await resolveFilePath(appId, file);
+    const result = await api.file.signDownload({
+        appId,
+        filePath,
+        expiresIn: expiresSec,
+    });
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emitOk)({
+            file_name: result.file_name,
+            path: result.path,
+            signed_url: result.signed_url,
+            expires_at: result.expires_at,
+        });
+        return;
+    }
+    // 默认输出 URL 一行（pretty 与 non-TTY 一致）
+    (0, output_1.emit)(result.signed_url);
+}

package/dist/cli/handlers/file/stat.js

@@ -0,0 +1,97 @@
+"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.handleFileStat = handleFileStat;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const render_1 = require("../../../utils/render");
+const error_1 = require("../../../utils/error");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../api/file/index");
+/**
+ * 解析 `<file>` 为后端 head 可用的 filePath。
+ *
+ * - `looksLikePath(input)`（`/path`、含 `/` 的 key、后端生成的 fileKey）→ 直接 HEAD
+ * - 其他输入按 file_name 走 FilterExpression 精确查询（多匹配 → AMBIGUOUS_FILE_NAME）
+ */
+async function resolveFile(appId, input) {
+    if ((0, index_1.looksLikePath)(input)) {
+        return api.file.statFile({ appId, filePath: (0, index_1.toAbsolutePath)(input) });
+    }
+    const [resolved] = await api.file.resolveInputs({
+        appId,
+        inputs: [input],
+        forceAs: "name",
+    });
+    if (resolved.status === "error") {
+        throw new error_1.AppError(resolved.error.code, resolved.error.message, {
+            next_actions: resolved.error.hint ? [resolved.error.hint] : undefined,
+        });
+    }
+    const head = await api.file.statFile({ appId, filePath: resolved.file.path });
+    // head 响应的 file_name 有时为空，用 list 响应补齐
+    if (!head.file_name)
+        head.file_name = resolved.file.file_name;
+    return head;
+}
+async function handleFileStat(file, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const info = await resolveFile(appId, file);
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emitOk)(info);
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const pairs = [
+        ["file_name", info.file_name || "—"],
+        ["path", info.path],
+        [
+            "size",
+            tty
+                ? `${(0, render_1.formatSize)(info.size_bytes)} (${String(info.size_bytes)} bytes)`
+                : String(info.size_bytes),
+        ],
+        ["type", info.type || "—"],
+        ["uploaded_at", (0, render_1.formatTime)(info.uploaded_at, tty)],
+    ];
+    if (info.uploaded_by) {
+        // uploaded_by 紧跟 uploaded_at 前插入（index = "uploaded_at" 之前）
+        pairs.splice(pairs.length - 1, 0, ["uploaded_by", info.uploaded_by]);
+    }
+    if (info.download_url) {
+        pairs.push(["download_url", info.download_url]);
+    }
+    (0, output_1.emit)((0, render_1.renderKeyValue)(pairs, tty));
+}

package/dist/cli/handlers/index.js

@@ -15,3 +15,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("../../cli/handlers/plugin/index"), exports);
+__exportStar(require("../../cli/handlers/file/index"), exports);
+__exportStar(require("../../cli/handlers/db/index"), exports);

package/dist/cli/help.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MiaodaHelp = void 0;
+const commander_1 = require("commander");
+/**
+ * MiaodaHelp 重写 commander 默认的 --help 输出，使之对齐 CLI 文档规范：
+ *
+ *   1. 描述放在最前（commander 默认是 Usage 在前、描述在后）
+ *   2. "Options:" 重命名为 "Flags:"，"Global Options:" 重命名为 "Global Flags:"
+ *   3. Usage 段独占一行 Heading + 缩进展示 usage 行
+ *   4. 段落顺序：描述 → Usage → Arguments → Commands → Flags → Global Flags
+ *      → Notes（addHelpText） → Examples（addHelpText）
+ *      （父命令不带 Examples，由 formatHelp 末尾自动追加 "Use ... --help" 提示）
+ *   5. Root 命令的 local options 视作 Global Flags（root 无 command-specific flag）
+ *   6. 子命令隐藏 -v / --version（仅 root 暴露）和自动生成的 `help` 子命令
+ *
+ * Notes / Examples 段由各命令通过 addHelpText('after', ...) 自行追加，
+ * 本类不直接生成 —— 框架与文案分层。
+ */
+class MiaodaHelp extends commander_1.Help {
+    // 全局默认开启：所有子命令 --help 都展示 Global Flags 段
+    showGlobalOptions = true;
+    /**
+     * 父级 --help 的 Commands 列表里展示子命令调用形态。spec 要求只展示
+     * `name <args>` 不带 `[flags]` 尾巴：
+     *
+     *   - 子命令是分组（含下级 subcommand）→ 只显示 name
+     *   - 子命令是 leaf 且配置了 usage()  → "name <args>"（usage 末尾的 [flags] 去掉）
+     *   - leaf 没配置 usage              → 退回 commander 默认行为
+     */
+    subcommandTerm(cmd) {
+        if (cmd.commands.length > 0) {
+            return cmd.name();
+        }
+        const usage = cmd.usage();
+        if (usage) {
+            // 去掉末尾的 [flags] / [options]，对齐 spec 的 "name <args>" 形态
+            const argsOnly = usage.replace(/\s*\[(?:flags|options)\]\s*$/i, "").trim();
+            return argsOnly ? `${cmd.name()} ${argsOnly}` : cmd.name();
+        }
+        return super.subcommandTerm(cmd);
+    }
+    /**
+     * 父命令的 Commands 列表里：
+     *   - 优先用子命令的 .summary()（短摘要，对齐 spec 父级列表用的简短描述）
+     *   - 否则取 description 首行，避免多行 description 把列表撑乱
+     * 叶子命令自身 --help 仍展示完整 description。
+     */
+    subcommandDescription(cmd) {
+        const summary = cmd.summary();
+        if (summary)
+            return summary;
+        const desc = super.subcommandDescription(cmd);
+        const idx = desc.indexOf("\n");
+        return idx === -1 ? desc : desc.slice(0, idx);
+    }
+    /**
+     * Flags 段里去掉那些已经在父命令注册过的选项（避免在 Flags 与 Global Flags
+     * 里重复展示，例如 --env 在 db 父级注册后，leaf 即使本地也注册一份也只在
+     * Global Flags 里出现一次）。
+     */
+    visibleOptions(cmd) {
+        const opts = super.visibleOptions(cmd);
+        if (!cmd.parent)
+            return opts;
+        const parentLongs = new Set();
+        let p = cmd.parent;
+        while (p) {
+            for (const o of p.options) {
+                if (o.long)
+                    parentLongs.add(o.long);
+            }
+            p = p.parent;
+        }
+        return opts.filter((o) => !o.long || !parentLongs.has(o.long));
+    }
+    /**
+     * 子命令 --help 默认会从父级继承 -v, --version；spec 只在 root 列这条。
+     * 非 root 命令把 --version 从 Global Flags 列表里过滤掉。
+     */
+    visibleGlobalOptions(cmd) {
+        const opts = super.visibleGlobalOptions(cmd);
+        if (cmd.parent) {
+            return opts.filter((o) => o.long !== "--version" && o.short !== "-v");
+        }
+        return opts;
+    }
+    /**
+     * Root 命令默认会列 commander 自动生成的 `help [command]` 子命令；
+     * spec 不展示这一条，过滤掉。
+     */
+    visibleCommands(cmd) {
+        return super.visibleCommands(cmd).filter((c) => c.name() !== "help");
+    }
+    formatHelp(cmd, helper) {
+        const isRoot = cmd.parent == null;
+        const termWidth = helper.padWidth(cmd, helper);
+        const helpWidth = helper.helpWidth ?? 80;
+        const formatItem = (term, description) => {
+            if (description) {
+                const padding = " ".repeat(Math.max(termWidth - term.length, 0) + 2);
+                return `${term}${padding}${description}`;
+            }
+            return term;
+        };
+        const formatList = (lines) => lines.map((l) => "  " + l).join("\n");
+        void helpWidth; // 保留以备后续按宽度自动 wrap，当前直接透传 description
+        const out = [];
+        // 1. 描述
+        const desc = helper.commandDescription(cmd);
+        if (desc) {
+            out.push(desc, "");
+        }
+        // 2. Usage：独立 heading + 缩进
+        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)));
+        if (subs.length) {
+            out.push("Commands:", formatList(subs), "");
+        }
+        // 5. Flags（叶子命令专属 options）
+        //    - Root / 父命令组：local options 都视作"会被子命令继承的 globals"，渲染到 Global Flags 段
+        //    - 叶子命令（无子命令）：local options 渲染到 Flags 段（如 db data export 的 --format）
+        //    - `-h, --help` 永远不放 Flags 段，统一放 Global Flags（spec 约定）
+        const isParent = subs.length > 0;
+        if (!isRoot && !isParent) {
+            const opts = helper.visibleOptions(cmd)
+                .filter((o) => !isHelpOption(o))
+                .map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
+            if (opts.length) {
+                out.push("Flags:", formatList(opts), "");
+            }
+        }
+        // 6. Global Flags
+        //    - Root：local options 当 globals 渲染（root 自己就是 global 来源）
+        //    - 父命令组：继承自祖先的 globals + 自己的 local options（也会被子命令继承）
+        //    - 叶子命令：继承自祖先的 globals + 当前的 -h, --help
+        //    - 末尾确保 -h, --help 一条
+        const localOpts = helper.visibleOptions(cmd);
+        let globals = [];
+        if (isRoot) {
+            globals = localOpts;
+        }
+        else if (isParent) {
+            const inherited = helper.visibleGlobalOptions(cmd);
+            const localNonHelp = localOpts.filter((o) => !isHelpOption(o));
+            const helpOpt = localOpts.find(isHelpOption);
+            globals = [...inherited, ...localNonHelp];
+            if (helpOpt && !globals.includes(helpOpt))
+                globals.push(helpOpt);
+        }
+        else if (this.showGlobalOptions) {
+            const inherited = helper.visibleGlobalOptions(cmd);
+            const helpOpt = localOpts.find(isHelpOption);
+            globals = [...inherited];
+            if (helpOpt && !globals.includes(helpOpt))
+                globals.push(helpOpt);
+        }
+        if (globals.length) {
+            const lines = globals.map((o) => formatItem(helper.optionTerm(o), helper.optionDescription(o)));
+            out.push("Global Flags:", formatList(lines), "");
+        }
+        // 7. 父命令底部追加 "Use <cmd> <subcommand> --help" 提示，对齐 spec
+        if (subs.length > 0) {
+            const path = cmd.name() === "miaoda" ? "miaoda" : commandPath(cmd);
+            out.push(`Use "${path} <command> --help" for more information about a command.`, "");
+        }
+        // 保留末尾换行：commander 用 join('\n') 拼 addHelpText('after') 段，
+        // 这里多留一个 \n，让 Notes / Examples 段与上面段落之间空一行。
+        return out.join("\n").replace(/\n+$/, "\n");
+    }
+}
+exports.MiaodaHelp = MiaodaHelp;
+/** 判断是否为 -h / --help 选项。 */
+function isHelpOption(o) {
+    return o.long === "--help" || o.short === "-h";
+}
+/** 拼接命令完整路径，例如 db schema -> "miaoda db schema"。 */
+function commandPath(cmd) {
+    const names = [];
+    let cur = cmd;
+    while (cur) {
+        names.unshift(cur.name());
+        cur = cur.parent;
+    }
+    return names.join(" ");
+}

package/dist/main.js

@@ -5,15 +5,23 @@ 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 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 package_json_1 = __importDefault(require("../package.json"));
+// MiaodaHelp 对齐 CLI 规范（描述置顶 / Flags / Global Flags / 段顺序）：
+// 在 Command.prototype 上 patch createHelp，让所有命令实例（含动态注册的
+// 子命令）统一走 MiaodaHelp 渲染，避免在每个子命令上重复 configureHelp。
+commander_1.Command.prototype.createHelp = function () {
+    return Object.assign(new help_1.MiaodaHelp(), this.configureHelp());
+};
 const program = new commander_1.Command();
 const { version } = package_json_1.default;
 program
     .name("miaoda")
-    .description("妙搭平台命令行工具")
+    .description("妙搭平台 CLI，提供数据服务、文件存储、插件管理等命令行操作。")
+    .usage("<command> [flags]")
     .version(version, "-v, --version", "显示版本号")
     .option("--json [fields]", "JSON 输出，可选字段级选择")
     .option("--output <format>", "输出格式（pretty|json）", "pretty")

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/error.js

@@ -5,12 +5,22 @@ class AppError extends Error {
     code;
     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";
         this.code = code;
         this.retryable = opts?.retryable ?? false;
         this.next_actions = opts?.next_actions ?? [];
+        this.statement_index = opts?.statement_index;
     }
     toJSON() {
         return {
@@ -18,6 +28,10 @@ class AppError extends Error {
             message: this.message,
             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;
+}