@lark-apaas/miaoda-cli 0.1.0 → 0.1.1-alpha.07b4fd5

package/dist/cli/handlers/db/sql.js

@@ -0,0 +1,647 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDbSql = handleDbSql;
+const api = __importStar(require("../../../api/index"));
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const config_1 = require("../../../utils/config");
+const logger_1 = require("../../../utils/logger");
+const shared_1 = require("../../../cli/commands/shared");
+const render_1 = require("../../../utils/render");
+const colors_1 = require("../../../utils/colors");
+const fuzzy_match_1 = require("../../../utils/fuzzy-match");
+const index_1 = require("../../../api/db/index");
+const sql_keywords_1 = require("../../../api/db/sql-keywords");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * miaoda db sql <query> — 执行任意 SQL。
+ *
+ * - query 为空时读 stdin
+ * - --env 透传给后端 admin-inner（dbBranch 参数），不传时由后端按 workspace
+ *   多环境状态兜底（多环境 → dev / 单环境 → main）；后端检测到环境不存在
+ *   会返 k_dl_1600000 + "Invalid DB Branch:..."，CLI 侧映射为 MULTI_ENV_NOT_INITIALIZED
+ * - 多语句行为对齐 PRD：每条 statement 一个独立结果元素，pretty 逐条 +
+ *   末尾汇总，--json 输出 data 数组。
+ */
+async function handleDbSql(query, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const sql = await readSql(query);
+    if (!sql.trim()) {
+        throw new error_1.AppError("ARGS_INVALID", "Empty SQL (no inline query and stdin is empty)");
+    }
+    let results;
+    try {
+        results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
+    }
+    catch (err) {
+        // 错误抛出前富化 next_actions：识别"语法错误"/"表不存在"/"列不存在"
+        // 三类常见 PG 错误，做 fuzzy match 给 did-you-mean 提示。
+        // 富化失败任何环节都静默吞掉，不破坏原始错误信息。
+        await enrichSqlError(err, { appId, env: opts.env, sql });
+        // PRD 多语句失败：把服务端给的 partial_results 转成 `completed`，推断 `rolled_back`，
+        // 并把 pretty 模式的 `Statement N: ✓ ... / Statement K: ✗ ...` 立即打到 stderr。
+        enrichMultiStatementError(err, sql);
+        throw err;
+    }
+    if (results.length === 0) {
+        // 后端未返回任何结果，通常不会发生
+        if ((0, output_1.isJsonMode)()) {
+            (0, output_1.emit)({ data: [] });
+            return;
+        }
+        (0, output_1.emit)("✓ No results");
+        return;
+    }
+    if (results.length === 1) {
+        renderSingle(results[0]);
+        await maybeSyncAgentSchema(results);
+        return;
+    }
+    // 多语句：每条 statement 独立结果
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({ data: results.map((r) => toMultiElement((0, index_1.parseSqlResult)(r))) });
+    }
+    else {
+        renderMultiPretty(results);
+    }
+    await maybeSyncAgentSchema(results);
+}
+/**
+ * 当本次 SQL 包含成功执行的 DDL 时，触发 `npm run gen:db-schema`（实质执行
+ * fullstack-cli gen-db-schema → drizzle-kit introspect）同步 agent 项目的
+ * schema.ts。**弱依赖**：失败不阻塞主流程退出码。
+ *
+ * 行为细节：
+ *   - 仅当 cwd/package.json 定义了 gen:db-schema 脚本时才尝试运行；非 agent
+ *     项目静默跳过
+ *   - 默认静默捕获子进程 stdout/stderr，成功只打一行 "Agent schema synced"，
+ *     失败时把捕获的输出回放给用户排查；--verbose 实时透传方便看进度
+ *   - 加 60s 兜底超时：drizzle-kit introspect 通常 < 30s，超时直接 SIGKILL，
+ *     避免 DB 慢或网络抖动时把 CLI 挂死
+ *   - 子进程的 stdout / stderr 都不会进入当前 CLI 的 stdout，--json 输出干净
+ *
+ * 调用时机：在 SQL 主输出 emit 完成之后；execSql 已经返回意味着所有
+ * statement 都执行成功，无需再校验逐条状态。
+ */
+/** agent runtime 中固定的项目根目录；放在此处便于以后调整。 */
+const AGENT_PROJECT_ROOT = "/home/gem/workspace/code";
+/** drain 子进程 pipe stream：默认静默模式下消费 chunk 防止缓冲区反压。 */
+function drainChunk(_chunk) {
+    // 显式接 chunk 参数让 ESLint 不再当成 empty function；不做任何处理
+}
+async function maybeSyncAgentSchema(results) {
+    if (!hasDdl(results))
+        return;
+    const projectRoot = await resolveAgentProjectRoot();
+    if (!projectRoot) {
+        (0, logger_1.debug)("[db sql] agent project root not found or missing gen:db-schema script, skip schema sync");
+        return;
+    }
+    const verbose = (0, config_1.getConfig)().verbose;
+    // drizzle-kit introspect 通常 < 30s；60s 兜底，超过即认为卡住
+    const TIMEOUT_MS = 60_000;
+    (0, logger_1.debug)(`[db sql] DDL detected, running \`npm run gen:db-schema\` in ${projectRoot}`);
+    try {
+        await new Promise((resolve) => {
+            const proc = (0, node_child_process_1.spawn)("npm", ["run", "gen:db-schema"], {
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: projectRoot,
+            });
+            // --verbose：实时透传到 stderr 看进度；默认完全静默丢弃。
+            // 任何路径下子进程输出都不会进入当前 CLI 的 stdout，--json 模式安全。
+            // 注：默认路径必须 attach 监听器，否则 pipe 缓冲区写满会反压子进程。
+            if (verbose) {
+                proc.stdout.pipe(process.stderr);
+                proc.stderr.pipe(process.stderr);
+            }
+            else {
+                proc.stdout.on("data", drainChunk);
+                proc.stderr.on("data", drainChunk);
+            }
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                proc.kill("SIGKILL");
+            }, TIMEOUT_MS);
+            proc.on("close", (code) => {
+                clearTimeout(timer);
+                if (timedOut) {
+                    (0, logger_1.debug)(`[db sql] gen:db-schema timed out after ${String(TIMEOUT_MS / 1000)}s, killed`);
+                }
+                else if (code !== 0 && code !== null) {
+                    (0, logger_1.debug)(`[db sql] gen:db-schema exited with code ${String(code)}`);
+                }
+                else {
+                    (0, logger_1.debug)("[db sql] gen:db-schema completed");
+                }
+                resolve();
+            });
+            proc.on("error", (err) => {
+                clearTimeout(timer);
+                (0, logger_1.debug)(`[db sql] gen:db-schema spawn error: ${err.message}`);
+                resolve();
+            });
+        });
+    }
+    catch (err) {
+        (0, logger_1.debug)(`[db sql] gen:db-schema unexpected error: ${String(err)}`);
+    }
+}
+/**
+ * 校验 AGENT_PROJECT_ROOT 是否是一个有效的 agent 项目（package.json 含
+ * `gen:db-schema` 脚本）。命中返回路径；缺失任一条件返 null，让调用方静默跳过。
+ *
+ * 这里不再从 process.cwd() 向上查找：agent runtime 里项目根是固定路径，
+ * 在 CLI 之外（本地手动跑 miaoda db sql）也不应触发同步。
+ */
+async function resolveAgentProjectRoot() {
+    try {
+        const pkgPath = node_path_1.default.join(AGENT_PROJECT_ROOT, "package.json");
+        const raw = await node_fs_1.promises.readFile(pkgPath, "utf8");
+        const pkg = JSON.parse(raw);
+        if (pkg.scripts?.["gen:db-schema"])
+            return AGENT_PROJECT_ROOT;
+    }
+    catch {
+        // 路径不存在 / 不可读 / 不是 agent 项目 → 静默跳过
+    }
+    return null;
+}
+/** 是否有任意一条 statement 是 DDL（CREATE / ALTER / DROP / GRANT / TRUNCATE / COMMENT 等）。 */
+function hasDdl(results) {
+    return results.some((r) => (0, index_1.parseSqlResult)(r).kind === "ddl");
+}
+/** 读取 stdin 并返回完整 SQL 文本（stdin 不是 TTY 即认为被 pipe）。 */
+async function readSql(inline) {
+    if (inline !== undefined && inline.length > 0)
+        return inline;
+    const stdin = process.stdin;
+    if (stdin.isTTY)
+        return "";
+    return new Promise((resolve, reject) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on("end", () => {
+            resolve(data);
+        });
+        process.stdin.on("error", reject);
+    });
+}
+function renderSingle(raw) {
+    const parsed = (0, index_1.parseSqlResult)(raw);
+    const tty = (0, render_1.isStdoutTty)();
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)(toJson(parsed));
+        return;
+    }
+    if (parsed.kind === "select") {
+        if (parsed.rows.length === 0) {
+            (0, output_1.emit)("(0 rows)");
+            return;
+        }
+        const cols = collectColumns(parsed.rows);
+        const rows = parsed.rows.map((r) => cols.map((col) => formatCell(r[col], tty)));
+        (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(cols, rows) : (0, render_1.renderTsv)(cols, rows));
+        return;
+    }
+    if (parsed.kind === "dml") {
+        const verb = dmlVerb(parsed.sqlType);
+        (0, output_1.emit)(tty
+            ? colors_1.c.success(`✓ ${String(parsed.affectedRows)} row${parsed.affectedRows === 1 ? "" : "s"} ${verb}`)
+            : `OK ${String(parsed.affectedRows)} rows ${verb}`);
+        return;
+    }
+    // DDL
+    (0, output_1.emit)(tty ? colors_1.c.success("✓ DDL executed") : "OK DDL executed");
+}
+function toJson(parsed) {
+    if (parsed.kind === "select") {
+        // PRD 单 SELECT：data 直接是行数组（按 --json 字段投影裁剪）
+        return { data: projectRows(parsed.rows) };
+    }
+    if (parsed.kind === "dml") {
+        // PRD 单 DML：data = {command, rows_affected}
+        return {
+            data: {
+                command: parsed.sqlType,
+                rows_affected: parsed.affectedRows,
+            },
+        };
+    }
+    // PRD 单 DDL：data = {command, target?}。command 直接用后端给的细粒度
+    // （CREATE_TABLE / DROP_TABLE / ...），target 待后端给对象名后再加。
+    return { data: { command: parsed.sqlType } };
+}
+/**
+ * 多语句 --json 元素：与单 DDL/DML 形状一致，但 SELECT 包成
+ * {command:"SELECT", rows:[...]}（PRD 约定，避免数组里嵌套数组造成歧义）。
+ */
+function toMultiElement(parsed) {
+    if (parsed.kind === "select") {
+        return { command: "SELECT", rows: projectRows(parsed.rows) };
+    }
+    if (parsed.kind === "dml") {
+        return { command: parsed.sqlType, rows_affected: parsed.affectedRows };
+    }
+    // DDL：用后端给的细粒度 command
+    return { command: parsed.sqlType };
+}
+/**
+ * PRD：`--json id,name` 字段投影。--json 不带值（boolean true）等价于不裁剪。
+ * 字段不存在时按 undefined 处理（JSON.stringify 会忽略 undefined value 的 key），
+ * 这样 Agent 拿到的 row 永远只含请求过的列。
+ */
+function projectRows(rows) {
+    const fields = parseJsonFields();
+    if (!fields)
+        return rows;
+    return rows.map((r) => {
+        const out = {};
+        for (const f of fields) {
+            out[f] = r[f];
+        }
+        return out;
+    });
+}
+/** 读取 --json [fields]：返回字段列表；boolean true 或 undefined 返回 null（不裁剪）。 */
+function parseJsonFields() {
+    const v = (0, config_1.getConfig)().json;
+    if (typeof v !== "string" || v === "")
+        return null;
+    return v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+/** 多语句 pretty：逐条 `Statement N: ...` + 末尾 `✓ N statements executed`。 */
+function renderMultiPretty(results) {
+    const tty = (0, render_1.isStdoutTty)();
+    const lines = [];
+    for (let i = 0; i < results.length; i++) {
+        const parsed = (0, index_1.parseSqlResult)(results[i]);
+        const idx = i + 1;
+        if (parsed.kind === "select") {
+            const n = parsed.rows.length;
+            lines.push(`Statement ${String(idx)}: SELECT (${String(n)} row${n === 1 ? "" : "s"})`);
+            if (n > 0) {
+                const cols = collectColumns(parsed.rows);
+                const tbl = parsed.rows.map((r) => cols.map((col) => formatCell(r[col], tty)));
+                lines.push(tty ? (0, render_1.renderAlignedTable)(cols, tbl) : (0, render_1.renderTsv)(cols, tbl));
+            }
+            // 块间空行（最后一条不留）
+            if (i < results.length - 1)
+                lines.push("");
+            continue;
+        }
+        if (parsed.kind === "dml") {
+            const verb = dmlVerb(parsed.sqlType);
+            const n = parsed.affectedRows;
+            const body = `${String(n)} row${n === 1 ? "" : "s"} ${verb}`;
+            lines.push(`Statement ${String(idx)}: ${tty ? colors_1.c.success("✓ " + body) : body}`);
+            continue;
+        }
+        // DDL
+        lines.push(`Statement ${String(idx)}: ${tty ? colors_1.c.success("✓ DDL executed") : "DDL executed"}`);
+    }
+    // 汇总行：所有 statement 都跑完了
+    lines.push(tty
+        ? colors_1.c.success(`✓ ${String(results.length)} statements executed`)
+        : `OK ${String(results.length)} statements executed`);
+    (0, output_1.emit)(lines.join("\n"));
+}
+function dmlVerb(type) {
+    switch (type) {
+        case "INSERT": return "inserted";
+        case "UPDATE": return "updated";
+        case "DELETE": return "deleted";
+        case "MERGE": return "merged";
+        case "DML": return "affected"; // 未识别子类的兜底
+    }
+}
+/** 从第一行收集列顺序；缺失列保留空白（兼容稀疏行）。 */
+function collectColumns(rows) {
+    if (rows.length === 0)
+        return [];
+    return Object.keys(rows[0]);
+}
+/**
+ * SQL 单元格 → 字符串：
+ * - null / undefined → "NULL"（TTY 下用 dim+gray ANSI 弱化，对齐 mysql/DuckDB；
+ *   non-TTY 用裸字面量，避免被 cat / 管道吞掉样式；JSON 模式不会走到这里，
+ *   走 toJson 直接用 parsed.rows，JSON.stringify 输出 `null` 字面）
+ * - string → 原样
+ * - number / boolean → toString
+ * - object / array → JSON.stringify
+ */
+function formatCell(v, tty) {
+    if (v === null || v === undefined) {
+        return tty ? colors_1.c.muted("NULL") : "NULL";
+    }
+    if (typeof v === "string") {
+        // TTY 下检测到 ISO 8601 时间字符串 → 转成相对时间（"3h ago" / "2d ago" /
+        // "2026-03-15"），方便 _created_at / _updated_at 等列直观可读
+        if (tty && ISO_TIMESTAMP_RE.test(v) && !Number.isNaN(Date.parse(v))) {
+            return (0, render_1.formatTime)(v, tty);
+        }
+        return v;
+    }
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    // object / array → JSON
+    return JSON.stringify(v);
+}
+/**
+ * 匹配 PG / ISO 8601 形态的日期时间字符串：
+ *   2026-04-29
+ *   2026-04-29 19:07:43           （PG 默认 timestamp 形态）
+ *   2026-04-29T19:07:43
+ *   2026-04-29T19:07:43.882+08:00
+ *   2026-04-29T19:07:43.882Z
+ * 时间部分 / 毫秒 / 时区可选。
+ */
+const ISO_TIMESTAMP_RE = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+// ──────────────────────────────────────────────────────────────────────
+// db sql 错误富化：识别 PG 常见报错形态 → fuzzy match → 加 did-you-mean hint
+// ──────────────────────────────────────────────────────────────────────
+const SYNTAX_RE = /syntax error at or near "([^"]+)"/i;
+const RELATION_RE = /relation "([^"]+)" does not exist/i;
+const COLUMN_RE = /column "([^"]+)"(?: of relation "([^"]+)")? does not exist/i;
+/**
+ * 在错误抛出前富化 next_actions（最多 1 条 hint），按 PG 报错形态分发：
+ *
+ *   表 / 列不存在路径：
+ *     - `column "X" of relation "Y" does not exist`     → 在 Y 表的列里 fuzzy
+ *     - `column "X" does not exist`（未指定表）         → 跨表所有列合集 fuzzy
+ *     - `relation "X" does not exist`                   → 在所有表名里 fuzzy
+ *
+ *   语法错误路径（`syntax error at or near "X"`）三条互斥子路径：
+ *     a. X 字面就是保留字（用户拿 keyword 当标识符，如 `FROM order`，
+ *        但 `order` 是 PG 保留字）→ 当作"想引用的表名"，远程 schema fuzzy。
+ *        **不要建议 keyword 自己**，那只是把用户输入大写返还，毫无价值。
+ *     b. X 接近某 keyword（典型拼写错误，如 SELCT）→ suggest keyword
+ *     c. X 是数字 / 标点（如 `LIMITT 1` 报错点到 `1`）→ fallback 扫整段
+ *        SQL 找看似拼错的 keyword token
+ *
+ * 任一环节失败（pattern 不匹配 / 远程拉表失败 / 没 fuzzy 候选）都静默吞掉，
+ * 不破坏原始错误信息——原则："只在我们高置信能帮上忙时才插嘴"。
+ */
+async function enrichSqlError(err, ctx) {
+    if (!(err instanceof error_1.AppError))
+        return;
+    const msg = err.message;
+    // ── 表 / 列不存在路径 ──
+    // 注意：列报错 'column "X" of relation "Y"' 也含 'relation "Y"' 子串，
+    // 会同时命中 RELATION_RE。先 colMatch（更精确），命中后不再走 relation 分支。
+    const colMatch = COLUMN_RE.exec(msg);
+    const relMatch = colMatch ? null : RELATION_RE.exec(msg);
+    if (relMatch || colMatch) {
+        const tableMap = await loadTableMap(ctx);
+        if (!tableMap)
+            return;
+        if (relMatch) {
+            enrichRelationNotExist(err, relMatch[1], tableMap);
+        }
+        else if (colMatch) {
+            enrichColumnNotExist(err, colMatch, tableMap);
+        }
+        return;
+    }
+    // ── 语法错误路径 ──
+    const kwMatch = SYNTAX_RE.exec(msg);
+    if (!kwMatch)
+        return;
+    const token = kwMatch[1];
+    const upper = token.toUpperCase();
+    // 子路径 a：token 字面就是 keyword → 用户拿保留字当标识符
+    if (sql_keywords_1.SQL_KEYWORDS.includes(upper)) {
+        const tableMap = await loadTableMap(ctx);
+        if (!tableMap)
+            return;
+        const guess = (0, fuzzy_match_1.suggest)(token, Object.keys(tableMap));
+        if (guess) {
+            err.next_actions.push(`Did you mean table '${guess}'? '${token}' is a reserved keyword; ` +
+                `quote it as "${token}" if you really mean a table named '${token}'.`);
+        }
+        return;
+    }
+    // 子路径 b：token 接近 keyword（拼写错误）
+    const guess = (0, fuzzy_match_1.suggest)(upper, sql_keywords_1.SQL_KEYWORDS);
+    if (guess && guess !== upper) {
+        err.next_actions.push(`Check SQL keyword spelling. Did you mean "${guess}"?`);
+        return;
+    }
+    // 子路径 c：PG 错误位置点到了下一个 token（如 `LIMITT 1` → 报错指向 "1"），
+    //          扫整段 SQL 找看似拼错的 keyword
+    const typo = findKeywordTypo(ctx.sql);
+    if (typo) {
+        err.next_actions.push(`Check SQL keyword spelling. '${typo.input}' looks like '${typo.suggest}'.`);
+    }
+}
+/** 远程拉一次 schema 并扁平化为 `tableName → fieldName[]`。失败返 null（调用方静默不加 hint）。 */
+async function loadTableMap(ctx) {
+    try {
+        const resp = await api.db.getSchema({
+            appId: ctx.appId,
+            format: "schema",
+            dbBranch: ctx.env,
+        });
+        return extractTableFieldMap(resp.schema);
+    }
+    catch {
+        return null;
+    }
+}
+function enrichRelationNotExist(err, relation, tableMap) {
+    const guess = (0, fuzzy_match_1.suggest)(relation, Object.keys(tableMap));
+    if (guess) {
+        err.next_actions.push(`Did you mean '${guess}'? Run \`miaoda db schema list\` to see all tables.`);
+    }
+}
+function enrichColumnNotExist(err, colMatch, tableMap) {
+    const colName = colMatch[1];
+    // TS RegExpMatchArray 数字索引类型 = string，但 optional capture group `(...)?`
+    // 没匹配时运行时返 undefined；as cast 把这个事实告诉类型系统。
+    const relation = colMatch[2];
+    const relationCols = relation !== undefined
+        ? tableMap[relation]
+        : undefined;
+    if (relation !== undefined && relationCols !== undefined) {
+        // 指定了表 → 在该表的列里找
+        const guess = (0, fuzzy_match_1.suggest)(colName, relationCols);
+        if (guess) {
+            err.next_actions.push(`Did you mean column '${guess}' in table '${relation}'?`);
+        }
+    }
+    else {
+        // 没指定表（CTE / 别名 / 子查询场景）→ 在所有表的列合集里找
+        const allCols = Array.from(new Set(Object.values(tableMap).flat()));
+        const guess = (0, fuzzy_match_1.suggest)(colName, allCols);
+        if (guess) {
+            err.next_actions.push(`Did you mean '${guess}'? Run \`miaoda db schema get <table>\` to see columns.`);
+        }
+    }
+}
+/**
+ * 扫整段 SQL 找一个看似"拼错的关键字"token：纯字母 + 长度 ≥ 3 + 不是已知 keyword
+ * + fuzzy 命中某个 keyword（且距离 > 0）。返第一个命中的 token。
+ *
+ * 用于 `syntax error at or near "<X>"` 的 X 是数字 / 标点的兜底场景——例如
+ * `... LIMITT 1` 报错点到 `1`，但用户真正的拼写错误在 LIMITT。
+ *
+ * 阈值复用 suggest()，候选词越短匹配越严，避免把 `userid` / `usrname` 这种
+ * 用户标识符误抓为关键字 typo。
+ */
+function findKeywordTypo(sql) {
+    const tokens = sql.split(/[\s,;()'"`*=<>+\-./]+/).filter((t) => /^[A-Za-z_]{3,}$/.test(t));
+    for (const tok of tokens) {
+        const upper = tok.toUpperCase();
+        if (sql_keywords_1.SQL_KEYWORDS.includes(upper))
+            continue; // 写对的关键字
+        const guess = (0, fuzzy_match_1.suggest)(upper, sql_keywords_1.SQL_KEYWORDS);
+        if (guess && guess !== upper) {
+            return { input: tok, suggest: guess };
+        }
+    }
+    return null;
+}
+/** 从 InnerSchemaRespVO 提取 `tableName → fieldName[]` 映射，扁平化 tables/views/mvs 三池。 */
+function extractTableFieldMap(s) {
+    const out = {};
+    if (!s)
+        return out;
+    const pools = [s.tables?.data, s.views?.data, s.materializedViews?.data];
+    for (const pool of pools) {
+        if (!pool)
+            continue;
+        for (const t of pool) {
+            out[t.tableName] = (t.fields ?? []).map((f) => f.fieldName);
+        }
+    }
+    return out;
+}
+/**
+ * 多语句 SQL 失败时把服务端透传的 partial_results 包装成 PRD 期望形态：
+ *   - 用现有 toMultiElement 把每条 SQLExecuteResult 转成 `{command, ...}` 元素，
+ *     与正常 multi-statement 成功路径的 data[] 结构完全一致
+ *   - 推断 rolled_back：扫 completed 数组里 BEGIN/COMMIT/ROLLBACK 计数；失败时
+ *     还在 user tx 内 ⇒ 服务端 closeUserTxIfOpen 已发 ROLLBACK，标 true
+ *   - rolled_back=true 时给 next_actions 追加一句 spec 文案
+ *   - pretty 模式（非 JSON）把 `Statement N: ✓ ... / K: ✗ ...` 立即打到 stderr，
+ *     与 emitError 的 Error/hint 行连成一段 PRD 期望的 multi-statement 报告
+ */
+function enrichMultiStatementError(err, sql) {
+    if (!(err instanceof error_1.AppError))
+        return;
+    const partial = err.partial_results;
+    if (!Array.isArray(partial) || partial.length === 0)
+        return;
+    // 把 SQLExecuteResult[] 转成 PRD 兼容的 completed 数组
+    const completed = partial.map((r) => toMultiElement((0, index_1.parseSqlResult)(r)));
+    err.completed = completed;
+    err.rolled_back = inferRolledBack(completed);
+    err.total_statements = countStatements(sql);
+    // pretty 模式（非 JSON）打 per-statement breakdown 到 stderr
+    if (!(0, output_1.isJsonMode)()) {
+        writeMultiStatementBreakdown(err, completed);
+    }
+    // rolled_back=true 时追加 spec hint："Transaction rolled back; no changes persisted."
+    if (err.rolled_back) {
+        err.next_actions.push("Transaction rolled back; no changes persisted.");
+    }
+}
+/**
+ * 推断本次多语句执行最终是否处于"事务被回滚"状态：
+ *   遍历 completed[] 数组，BEGIN +1 / COMMIT|ROLLBACK -1；
+ *   失败时 depth > 0 → 用户事务还开着 → 服务端 closeUserTxIfOpen 发了 ROLLBACK
+ *   失败时 depth = 0 → 失败语句在 autocommit 模式 → 已成功的 statement 真实落库
+ */
+function inferRolledBack(completed) {
+    let depth = 0;
+    for (const e of completed) {
+        if (e.command === "BEGIN")
+            depth++;
+        else if (e.command === "COMMIT" || e.command === "ROLLBACK")
+            depth--;
+    }
+    return depth > 0;
+}
+/**
+ * 数 SQL 里有几条独立语句：先去掉单 / 双引号字面量（防止 'a;b' 里的分号被算成
+ * 分隔符），再按分号 split，过滤空条。CLI 用户场景几乎都是简单 SQL，不处理
+ * dollar-quoted（$$..$$）等高级形态——估错 ±1 不影响 hint 可读性。
+ */
+function countStatements(sql) {
+    const stripped = sql
+        .replace(/'(?:''|[^'])*'/g, "''")
+        .replace(/"(?:""|[^"])*"/g, '""');
+    return stripped.split(/;+/).filter((s) => s.trim().length > 0).length;
+}
+/**
+ * 写 `Statement N: ✓ ... / Statement K: ✗ ...` 到 stderr，对齐 PRD spec 的
+ * 多语句失败 pretty 输出形态。
+ */
+function writeMultiStatementBreakdown(err, completed) {
+    const tty = (0, render_1.isStdoutTty)();
+    const lines = [];
+    for (let i = 0; i < completed.length; i++) {
+        const e = completed[i];
+        const verb = e.command === "BEGIN" || e.command === "COMMIT" || e.command === "ROLLBACK"
+            ? e.command
+            : describeCompleted(e);
+        lines.push(`Statement ${String(i + 1)}: ${tty ? colors_1.c.success("✓ ") : "✓ "}${verb}`);
+    }
+    // 失败那条
+    const failedIdx = err.statement_index ?? completed.length;
+    lines.push(`Statement ${String(failedIdx + 1)}: ${tty ? colors_1.c.fail("✗ ") : "✗ "}${err.message}`);
+    process.stderr.write(lines.join("\n") + "\n\n");
+}
+/** completed 单条结果的人类可读描述（用于 stderr breakdown 行尾）。 */
+function describeCompleted(e) {
+    const r = e;
+    if (r.command === "SELECT" && Array.isArray(r.rows)) {
+        return `SELECT (${String(r.rows.length)} row${r.rows.length === 1 ? "" : "s"})`;
+    }
+    if (typeof r.rows_affected === "number") {
+        const verb = dmlVerb(r.command);
+        return `${String(r.rows_affected)} row${r.rows_affected === 1 ? "" : "s"} ${verb}`;
+    }
+    return `${r.command} executed`;
+}