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

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

@@ -56,7 +56,9 @@ async function handleDbDataImport(file, opts) {
     catch (err) {
         const code = err.code;
         if (code === "ENOENT") {
-            throw new error_1.AppError("IMPORT_FILE_NOT_FOUND", `Local file '${file}' does not exist`, { next_actions: ["Check the file path."] });
+            throw new error_1.AppError("IMPORT_FILE_NOT_FOUND", `Local file '${file}' does not exist`, {
+                next_actions: ["Check the file path."],
+            });
         }
         throw err;
     }
@@ -100,6 +102,20 @@ async function handleDbDataExport(table, opts) {
     if (!Number.isInteger(limit) || limit <= 0 || limit > MAX_ROWS) {
         throw new error_1.AppError("ARGS_INVALID", `--limit must be a positive integer ≤ ${String(MAX_ROWS)}`);
     }
+    if (!opts.force) {
+        try {
+            await fs.access(outputPath);
+            throw new error_1.AppError("FILE_ALREADY_EXISTS", `Output file '${outputPath}' already exists`, {
+                next_actions: ["Use -f to specify a different path, or --force to overwrite."],
+            });
+        }
+        catch (err) {
+            if (err instanceof error_1.AppError)
+                throw err;
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+    }
     const result = await api.db.exportData({
         appId,
         tableName: table,
@@ -107,7 +123,11 @@ async function handleDbDataExport(table, opts) {
         limit,
     });
     if (result.body.length > MAX_SIZE_BYTES) {
-        throw new error_1.AppError("EXPORT_SIZE_EXCEEDED", `Export exceeds 1 MB limit (body is ${String(result.body.length)} bytes)`, { next_actions: [`Filter the table with "miaoda db sql" (e.g. WHERE/LIMIT) and export smaller subsets.`] });
+        throw new error_1.AppError("EXPORT_SIZE_EXCEEDED", `Export exceeds 1 MB limit (body is ${String(result.body.length)} bytes)`, {
+            next_actions: [
+                `Filter the table with "miaoda db sql" (e.g. WHERE/LIMIT) and export smaller subsets.`,
+            ],
+        });
     }
     await fs.writeFile(outputPath, result.body);
     // 优先信任后端 X-Miaoda-Record-Count header；header 缺失时再用 body 行数兜底

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

@@ -40,11 +40,17 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
 const index_1 = require("../../../api/db/index");
 // ── schema list ──
 async function handleDbSchemaList(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    const resp = await api.db.getSchema({ appId, format: "schema", includeStats: true, dbBranch: opts.env });
+    const resp = await api.db.getSchema({
+        appId,
+        format: "schema",
+        includeStats: true,
+        dbBranch: opts.env,
+    });
     const tables = (0, index_1.flattenSchemaList)(resp.schema);
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emit)({ data: tables });
@@ -68,7 +74,7 @@ async function handleDbSchemaList(opts) {
         t.name,
         t.description ?? "—",
         t.estimated_row_count === null ? "—" : String(t.estimated_row_count),
-        t.size_bytes === null ? "—" : (tty ? (0, render_1.formatSize)(t.size_bytes) : String(t.size_bytes)),
+        t.size_bytes === null ? "—" : tty ? (0, render_1.formatSize)(t.size_bytes) : String(t.size_bytes),
         String(t.columns),
     ]);
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
@@ -108,9 +114,7 @@ async function handleDbSchemaGet(table, opts) {
     const detail = (0, index_1.pickTableDetail)(resp.schema, table);
     if (!detail) {
         throw new error_1.AppError("TABLE_NOT_FOUND", `Table '${table}' does not exist`, {
-            next_actions: [
-                `Did you mean another table? Run "miaoda db schema list" to see all tables.`,
-            ],
+            next_actions: [`Did you mean another table? Run "miaoda db schema list" to see all tables.`],
         });
     }
     if ((0, output_1.isJsonMode)()) {
@@ -127,7 +131,8 @@ function renderDetail(d, tty) {
     // 构造的伪时间戳（baseTime=2020-01-01 + OID 秒偏移），仅保排序意义、绝对值
     // 误导性强，先去掉。后续如果接 ddl_change_log 取真实时间再加回。
     const header = [
-        ["Name", d.name],
+        // 表名做 cyan 强调（spec：spec 里的"命令名/表名"类强调值都走 highlight）
+        ["Name", tty ? colors_1.c.highlight(d.name) : d.name],
         ["Description", d.description ?? "—"],
         [
             "Columns",
@@ -150,12 +155,21 @@ function renderDetail(d, tty) {
     parts.push((0, render_1.renderKeyValue)(header, tty));
     parts.push("");
     parts.push(tty ? (0, render_1.renderAlignedTable)(colHeaders, colRows) : (0, render_1.renderTsv)(colHeaders, colRows));
+    // Constraints 段（PRIMARY KEY / UNIQUE）：表级约束独立成段，与普通索引分离展示
+    if (d.constraints.length > 0) {
+        parts.push("");
+        parts.push(tty ? "  Constraints:" : "Constraints:");
+        for (const c of d.constraints) {
+            const line = `${c.type} (${c.columns.join(", ")})`;
+            parts.push(tty ? `    ${line}` : line);
+        }
+    }
+    // Indexes 段：普通索引，格式 "<name> ON <col1, col2> USING <method>"
     if (d.indexes.length > 0) {
         parts.push("");
         parts.push(tty ? "  Indexes:" : "Indexes:");
-        // PRD 格式: "TYPE (col1, col2)"，不展示索引名
         for (const idx of d.indexes) {
-            const line = `${idx.type} (${idx.columns.join(", ")})`;
+            const line = `${idx.name} ON ${idx.columns.join(", ")} USING ${idx.method}`;
             parts.push(tty ? `    ${line}` : line);
         }
     }

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

@@ -44,7 +44,10 @@ 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"));
@@ -64,7 +67,20 @@ async function handleDbSql(query, opts) {
     if (!sql.trim()) {
         throw new error_1.AppError("ARGS_INVALID", "Empty SQL (no inline query and stdin is empty)");
     }
-    const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
+    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)()) {
@@ -225,19 +241,19 @@ function renderSingle(raw) {
             return;
         }
         const cols = collectColumns(parsed.rows);
-        const rows = parsed.rows.map((r) => cols.map((c) => formatCell(r[c], tty)));
+        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
-            ? `✓ ${String(parsed.affectedRows)} row${parsed.affectedRows === 1 ? "" : "s"} ${verb}`
+            ? 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 ? "✓ DDL executed" : "OK DDL executed");
+    (0, output_1.emit)(tty ? colors_1.c.success("✓ DDL executed") : "OK DDL executed");
 }
 function toJson(parsed) {
     if (parsed.kind === "select") {
@@ -293,7 +309,10 @@ 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);
+    return v
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
 }
 /** 多语句 pretty：逐条 `Statement N: ...` + 末尾 `✓ N statements executed`。 */
 function renderMultiPretty(results) {
@@ -307,7 +326,7 @@ function renderMultiPretty(results) {
             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((c) => formatCell(r[c], tty)));
+                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));
             }
             // 块间空行（最后一条不留）
@@ -318,25 +337,31 @@ function renderMultiPretty(results) {
         if (parsed.kind === "dml") {
             const verb = dmlVerb(parsed.sqlType);
             const n = parsed.affectedRows;
-            lines.push(`Statement ${String(idx)}: ${tty ? "✓ " : ""}${String(n)} row${n === 1 ? "" : "s"} ${verb}`);
+            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 ? "✓ " : ""}DDL executed`);
+        lines.push(`Statement ${String(idx)}: ${tty ? colors_1.c.success("✓ DDL executed") : "DDL executed"}`);
     }
     // 汇总行：所有 statement 都跑完了
     lines.push(tty
-        ? `✓ ${String(results.length)} statements executed`
+        ? 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"; // 未识别子类的兜底
+        case "INSERT":
+            return "inserted";
+        case "UPDATE":
+            return "updated";
+        case "DELETE":
+            return "deleted";
+        case "MERGE":
+            return "merged";
+        case "DML":
+            return "affected"; // 未识别子类的兜底
     }
 }
 /** 从第一行收集列顺序；缺失列保留空白（兼容稀疏行）。 */
@@ -356,12 +381,275 @@ function collectColumns(rows) {
  */
 function formatCell(v, tty) {
     if (v === null || v === undefined) {
-        return tty ? "\u001b[2;90mNULL\u001b[0m" : "NULL";
+        return tty ? colors_1.c.muted("NULL") : "NULL";
     }
-    if (typeof v === "string")
+    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));
+    err.next_actions.push(guess
+        ? `Did you mean '${guess}'? Run \`miaoda db schema list\` to see all tables.`
+        : "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);
+        err.next_actions.push(guess
+            ? `Did you mean column '${guess}' in table '${relation}'?`
+            : `Run \`miaoda db schema get ${relation}\` to see all columns.`);
+        return;
+    }
+    // 没指定表（CTE / 别名 / 子查询 / 单表 SELECT 但 PG 报错没带 relation 等场景）
+    // → 跨表所有列合集 fuzzy；没命中也给一句通用 hint，让用户知道下一步去哪查。
+    const allCols = Array.from(new Set(Object.values(tableMap).flat()));
+    const guess = (0, fuzzy_match_1.suggest)(colName, allCols);
+    err.next_actions.push(guess
+        ? `Did you mean '${guess}'? Run \`miaoda db schema get <table>\` to see columns.`
+        : "Run `miaoda db schema get <table>` to see all 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;
+    // 用 SQL 文本判断是否多语句，而不是 partial.length——第一条就失败时
+    // partial_results=[]，但仍需输出统一的多语句 envelope 字段保持格式一致。
+    const total = countStatements(sql);
+    if (total <= 1)
+        return;
+    const partial = Array.isArray(err.partial_results)
+        ? err.partial_results
+        : [];
+    const completed = partial.map((r) => toMultiElement((0, index_1.parseSqlResult)(r)));
+    err.completed = completed;
+    err.rolled_back = inferRolledBack(completed);
+    err.total_statements = total;
+    // 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`;
+}

package/dist/cli/handlers/deploy/deploy.js

@@ -0,0 +1,83 @@
+"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.handleDeploy = handleDeploy;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../api/deploy/index");
+const polling_1 = require("./polling");
+/** miaoda deploy [--branch ...] [--wait] [--timeout 300] */
+async function handleDeploy(opts) {
+    const appID = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    const resp = await api.deploy.createRelease({ appID, branch: opts.branch });
+    const pipelineTaskID = resp.pipelineTaskID ?? "";
+    if (!opts.wait) {
+        if (!(0, output_1.isJsonMode)()) {
+            process.stdout.write(`✓ Deployment triggered. (deploy-id: ${pipelineTaskID})\n`);
+        }
+        (0, output_1.emit)({
+            data: { pipelineTaskID },
+            next_cursor: null,
+            has_more: false,
+        });
+        return;
+    }
+    if (!(0, output_1.isJsonMode)()) {
+        process.stdout.write(`Waiting for deployment to complete... (deploy-id: ${pipelineTaskID})\n`);
+    }
+    const detail = await (0, polling_1.waitForPipeline)({
+        appID,
+        pipelineTaskID,
+        timeoutSec: opts.timeout ?? 300,
+    });
+    if (!(0, output_1.isJsonMode)()) {
+        if (detail.status === index_1.NodeStatus.SUCCESS) {
+            process.stdout.write("✓ 发布成功\n");
+        }
+        else if (detail.status === index_1.NodeStatus.FAILED) {
+            process.stdout.write("✗ 发布失败\n");
+            process.stdout.write(`  hint: Run \`miaoda deploy error-log ${pipelineTaskID}\` to view error logs\n`);
+        }
+        else {
+            process.stdout.write("• 发布已取消\n");
+        }
+    }
+    (0, output_1.emit)({
+        data: { pipelineTaskID, detail },
+        next_cursor: null,
+        has_more: false,
+    });
+}

package/dist/cli/handlers/deploy/error-log.js

@@ -0,0 +1,61 @@
+"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.handleDeployErrorLog = handleDeployErrorLog;
+const api = __importStar(require("../../../api/index"));
+const output_1 = require("../../../utils/output");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../api/deploy/index");
+const helpers_1 = require("./helpers");
+/** miaoda deploy error-log <deploy-id> */
+async function handleDeployErrorLog(opts) {
+    if (!opts.deployId)
+        (0, shared_1.failArgs)("<deploy-id> 必填");
+    const appID = (0, shared_1.resolveAppId)({ appId: opts.appId });
+    (0, helpers_1.parseDeployId)(opts.deployId); // 仅校验数字形式；URL 直接用原字符串
+    const instanceID = opts.deployId;
+    const resp = await api.deploy.getErrorLog({ appID, instanceID });
+    // 信封带上 status 元信息（非 errorJobs 主体），便于 JSON 消费方读取
+    (0, output_1.emit)({
+        data: resp.errorJobs,
+        next_cursor: null,
+        has_more: false,
+    }, index_1.errorJobSchema);
+    // pretty 模式额外打一行整体状态（status 是 NodeStatus 数字）
+    if (!process.stdout.isTTY)
+        return;
+    const statusText = (0, index_1.nodeStatusText)(resp.status) ?? String(resp.status);
+    process.stdout.write(`\n— pipeline status: ${statusText}\n`);
+}