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

package/dist/utils/http.js

@@ -6,7 +6,12 @@ exports.resetHttpClient = resetHttpClient;
 exports.setHttpClient = setHttpClient;
 exports.setRuntimeHttpClient = setRuntimeHttpClient;
 exports.applyCanaryHeader = applyCanaryHeader;
+exports.postInnerApi = postInnerApi;
+exports.getInnerApi = getInnerApi;
 const http_client_1 = require("@lark-apaas/http-client");
+const error_1 = require("./error");
+const config_1 = require("./config");
+const logger_1 = require("./logger");
 let adminClient;
 let runtimeClient;
 /**
@@ -65,3 +70,116 @@ function applyCanaryHeader(reqConfig) {
     reqConfig.headers = headers;
     return reqConfig;
 }
+/** 走管理端 innerapi 的 POST + 信封解析 */
+async function postInnerApi(url, body, opts) {
+    const startMs = logRequestStart("POST", url, body);
+    let response;
+    try {
+        response = await getHttpClient().post(url, body);
+    }
+    catch (err) {
+        logResponseFailure("POST", url, err, startMs);
+        throw err;
+    }
+    logResponseEnd("POST", url, response, startMs);
+    return handleInnerEnvelope(response, url, opts);
+}
+/** 走管理端 innerapi 的 GET + 信封解析 */
+async function getInnerApi(url, opts) {
+    const startMs = logRequestStart("GET", url);
+    let response;
+    try {
+        response = await getHttpClient().get(url);
+    }
+    catch (err) {
+        logResponseFailure("GET", url, err, startMs);
+        throw err;
+    }
+    logResponseEnd("GET", url, response, startMs);
+    return handleInnerEnvelope(response, url, opts);
+}
+async function handleInnerEnvelope(response, url, opts) {
+    if (!response.ok) {
+        throw new error_1.HttpError(response.status, url, `${opts.errPrefix}: ${String(response.status)} ${response.statusText}`);
+    }
+    const result = await response.json();
+    if (typeof result === "object" && result !== null && "status_code" in result) {
+        const env = result;
+        if (env.status_code !== undefined && env.status_code !== "0") {
+            const msg = env.message ?? env.error_msg ?? "unknown error";
+            // verbose: 把完整业务错误信封打到 stderr，便于追溯
+            if ((0, config_1.getConfig)().verbose) {
+                (0, logger_1.debug)(`  envelope: ${truncateForLog(safeStringify(env), 1000)}`);
+            }
+            const mapped = opts.mapErr?.(env.status_code, msg);
+            if (mapped)
+                throw mapped;
+            throw new error_1.AppError(opts.defaultErrCode ?? "INTERNAL_API_ERROR", `${opts.errPrefix}: ${msg}`);
+        }
+        // status_code = "0"：data 存在则解封；否则 envelope 自身就是业务体
+        if (env.data)
+            return env.data;
+        return result;
+    }
+    return result;
+}
+// ── verbose 调试日志 ────────────
+//
+// 仅作用于 inner-api 链路（postInnerApi / getInnerApi），即 app / deploy /
+// observability 三个域。--verbose 关闭时所有 helper 都直接退出，零开销。
+function logRequestStart(method, url, body) {
+    const startMs = Date.now();
+    if (!(0, config_1.getConfig)().verbose)
+        return startMs;
+    (0, logger_1.debug)(`→ ${method} ${url}`);
+    if (body !== undefined) {
+        (0, logger_1.debug)(`  body: ${truncateForLog(safeStringify(body), 1000)}`);
+    }
+    return startMs;
+}
+function logResponseEnd(method, url, response, startMs) {
+    if (!(0, config_1.getConfig)().verbose)
+        return;
+    const elapsedMs = Date.now() - startMs;
+    const logid = pickLogid(response.headers);
+    const tail = logid ? ` logid=${logid}` : "";
+    (0, logger_1.debug)(`← ${method} ${url} ${String(response.status)} ${String(elapsedMs)}ms${tail}`);
+}
+/**
+ * http-client 在 4xx/5xx / 网络错误时直接 reject（不返回 Response）；
+ * 这条路径下 logResponseEnd 不会跑——这里专门补一行，尽可能从 HttpError
+ * 上抠出 status / logid，让 verbose 仍能看到失败请求的关键信息。
+ */
+function logResponseFailure(method, url, err, startMs) {
+    if (!(0, config_1.getConfig)().verbose)
+        return;
+    const elapsedMs = Date.now() - startMs;
+    // @lark-apaas/http-client 的 HttpError.response: Response | undefined
+    const e = err;
+    const status = e.response?.status;
+    const logid = e.response?.headers ? pickLogid(e.response.headers) : null;
+    const statusPart = status !== undefined ? String(status) : "ERR";
+    const logidPart = logid ? ` logid=${logid}` : "";
+    const msgPart = e.message ? ` (${e.message})` : "";
+    (0, logger_1.debug)(`✗ ${method} ${url} ${statusPart} ${String(elapsedMs)}ms${logidPart}${msgPart}`);
+}
+/** BAM gateway 在不同 PSM/版本上 logid 落在不同 header；按命中顺序取第一个非空。 */
+function pickLogid(headers) {
+    return (headers.get("x-tt-logid") ??
+        headers.get("x-logid") ??
+        headers.get("logid") ??
+        headers.get("x-tt-trace-tag"));
+}
+function safeStringify(v) {
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function truncateForLog(s, n) {
+    if (s.length <= n)
+        return s;
+    return `${s.slice(0, n)}...(truncated, ${String(s.length)} chars)`;
+}

package/dist/utils/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.isJsonMode = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
+exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
 var error_1 = require("./error");
 Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return error_1.AppError; } });
 Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return error_1.HttpError; } });
@@ -15,7 +15,10 @@ Object.defineProperty(exports, "getLogId", { enumerable: true, get: function ()
 var output_1 = require("./output");
 Object.defineProperty(exports, "emit", { enumerable: true, get: function () { return output_1.emit; } });
 Object.defineProperty(exports, "emitError", { enumerable: true, get: function () { return output_1.emitError; } });
+Object.defineProperty(exports, "emitOk", { enumerable: true, get: function () { return output_1.emitOk; } });
+Object.defineProperty(exports, "emitPaged", { enumerable: true, get: function () { return output_1.emitPaged; } });
 Object.defineProperty(exports, "isJsonMode", { enumerable: true, get: function () { return output_1.isJsonMode; } });
+Object.defineProperty(exports, "fmt", { enumerable: true, get: function () { return output_1.fmt; } });
 var logger_1 = require("./logger");
 Object.defineProperty(exports, "debug", { enumerable: true, get: function () { return logger_1.debug; } });
 Object.defineProperty(exports, "log", { enumerable: true, get: function () { return logger_1.log; } });
@@ -25,3 +28,12 @@ Object.defineProperty(exports, "getRuntimeHttpClient", { enumerable: true, get:
 Object.defineProperty(exports, "resetHttpClient", { enumerable: true, get: function () { return http_1.resetHttpClient; } });
 Object.defineProperty(exports, "setHttpClient", { enumerable: true, get: function () { return http_1.setHttpClient; } });
 Object.defineProperty(exports, "setRuntimeHttpClient", { enumerable: true, get: function () { return http_1.setRuntimeHttpClient; } });
+Object.defineProperty(exports, "postInnerApi", { enumerable: true, get: function () { return http_1.postInnerApi; } });
+Object.defineProperty(exports, "getInnerApi", { enumerable: true, get: function () { return http_1.getInnerApi; } });
+var time_1 = require("./time");
+Object.defineProperty(exports, "parseTimeToMs", { enumerable: true, get: function () { return time_1.parseTimeToMs; } });
+Object.defineProperty(exports, "parseToMs", { enumerable: true, get: function () { return time_1.parseToMs; } });
+Object.defineProperty(exports, "parseToNs", { enumerable: true, get: function () { return time_1.parseToNs; } });
+Object.defineProperty(exports, "parseToSec", { enumerable: true, get: function () { return time_1.parseToSec; } });
+Object.defineProperty(exports, "msToNs", { enumerable: true, get: function () { return time_1.msToNs; } });
+Object.defineProperty(exports, "msToSec", { enumerable: true, get: function () { return time_1.msToSec; } });

package/dist/utils/output.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.fmt = void 0;
 exports.isJsonMode = isJsonMode;
 exports.emit = emit;
 exports.emitError = emitError;
@@ -7,28 +8,379 @@ exports.emitOk = emitOk;
 exports.emitPaged = emitPaged;
 const config_1 = require("./config");
 const error_1 = require("./error");
+const colors_1 = require("./colors");
+/**
+ * 服务端错误码 → CLI 兜底 hint 文案。
+ *
+ * 服务端错误协议只有 `{code, msg}` 两个字段（dataloom InnerExecuteSQL 等 IDL
+ * 没有 hint / next_actions 通道），所以服务端给的错误本身永远没有 hint。
+ * 这里是 CLI 展示层为常见错误码补一份 spec 一致的 actionable 引导，按错误码
+ * 落到 next_actions。
+ *
+ * 仅在 next_actions 已经为空时介入——保留 handler / enrichSqlError 自己塞过的
+ * 具体 hint（如 did-you-mean、shared.resolveAppId 等），它们优先级更高。
+ */
+const SERVER_ERROR_HINTS = {
+    // SELECT 结果集超过 1000 行硬拦：spec 多行引导。
+    // key 用 BIZ_ERR_MAP 映射后的语义 code（不是原始服务端 k_dl_xxx），保持
+    // 与 help / 文档里宣传的 RESULT_SET_TOO_LARGE 一致。
+    RESULT_SET_TOO_LARGE: [
+        "Add `LIMIT <n>` to your SQL to narrow the result.",
+        "For counts, use `SELECT count(*) FROM ...`; for aggregation, use GROUP BY with filters.",
+    ],
+};
 function isJsonMode() {
     const cfg = (0, config_1.getConfig)();
     return cfg.output === "json" || Boolean(cfg.json);
 }
+// ── 默认 cell 格式化 ────────────
+/**
+ * 单元格的兜底渲染：
+ * - null/undefined → ""
+ * - string/number/bigint/boolean → toString
+ * - 复合值 → JSON.stringify
+ *   - TTY：超过 60 字符截断（UX 友好）
+ *   - 非 TTY：完整输出（不破坏管道下游解析）
+ */
+function defaultFormat(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "boolean" || typeof v === "number" || typeof v === "bigint")
+        return String(v);
+    const s = JSON.stringify(v);
+    if (process.stdout.isTTY && s.length > 60)
+        return s.slice(0, 57) + "...";
+    return s;
+}
+// ── 时间戳 / 时长 formatter ────────────
+function toMs(v, divisor) {
+    let n;
+    if (typeof v === "number")
+        n = v;
+    else if (typeof v === "bigint")
+        n = Number(v);
+    else if (typeof v === "string") {
+        n = Number(v);
+        if (!Number.isFinite(n))
+            return null;
+    }
+    else
+        return null;
+    if (!Number.isFinite(n))
+        return null;
+    return n / divisor;
+}
+/** renderDate 默认模板：本地时区、人读友好。业务层可在 fmt.{ns,us,ms,sec}() 里覆盖。 */
+const DEFAULT_DATE_TEMPLATE = "yyyy-MM-dd HH:mm:ss";
+/**
+ * 把 Date 渲染成模板字符串；time zone 走运行时 local。
+ * 支持的占位符：yyyy / MM / dd / HH / mm / ss / SSS（毫秒）。
+ */
+function renderDate(date, template = DEFAULT_DATE_TEMPLATE) {
+    // if (!process.stdout.isTTY) return date.toISOString();
+    // const diffMs = Date.now() - date.getTime();
+    // if (diffMs < 0) return date.toISOString();
+    // if (diffMs < 60_000) return `${String(Math.floor(diffMs / 1000))}s ago`;
+    // if (diffMs < 3_600_000) return `${String(Math.floor(diffMs / 60_000))}m ago`;
+    // if (diffMs < 86_400_000) return `${String(Math.floor(diffMs / 3_600_000))}h ago`;
+    // if (diffMs < 7 * 86_400_000) return `${String(Math.floor(diffMs / 86_400_000))}d ago`;
+    const pad2 = (n) => String(n).padStart(2, "0");
+    const Y = String(date.getFullYear());
+    const Mo = pad2(date.getMonth() + 1);
+    const D = pad2(date.getDate());
+    const H = pad2(date.getHours());
+    const Mi = pad2(date.getMinutes());
+    const S = pad2(date.getSeconds());
+    const Ms = String(date.getMilliseconds()).padStart(3, "0");
+    // 顺序：先把 SSS 这种长 token 处理掉，再处理短 token，避免子串误覆盖
+    return template
+        .replace(/yyyy/g, Y)
+        .replace(/SSS/g, Ms)
+        .replace(/MM/g, Mo)
+        .replace(/dd/g, D)
+        .replace(/HH/g, H)
+        .replace(/mm/g, Mi)
+        .replace(/ss/g, S);
+}
+function makeTimestampFormatter(divisor, template) {
+    return (v) => {
+        const ms = toMs(v, divisor);
+        // 0 视作"缺失/哨兵"，不渲染为 1970；越界数字也回退原值
+        if (ms === null || ms <= 0 || ms > 8.64e15)
+            return defaultFormat(v);
+        return renderDate(new Date(ms), template);
+    };
+}
+function formatDurationMs(ms) {
+    if (ms < 1)
+        return `${ms.toFixed(2)}ms`;
+    if (ms < 1000)
+        return `${ms.toFixed(0)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    if (ms < 3_600_000)
+        return `${(ms / 60_000).toFixed(1)}m`;
+    return `${(ms / 3_600_000).toFixed(1)}h`;
+}
+function makeDurationFormatter(divisor) {
+    return (v) => {
+        const ms = toMs(v, divisor);
+        if (ms === null || ms < 0)
+            return defaultFormat(v);
+        return formatDurationMs(ms);
+    };
+}
+function makeTruncateFormatter(n) {
+    return (v) => {
+        const s = defaultFormat(v);
+        // 仅 TTY 截断，非 TTY 保留完整值（pipe 下游可解析）
+        if (!process.stdout.isTTY || s.length <= n)
+            return s;
+        return s.slice(0, Math.max(0, n - 3)) + "...";
+    };
+}
+/**
+ * 内置格式化工厂：handler 在 schema 里按需挑选并按需传模板。
+ *
+ * 时间戳系列（ns / us / ms / sec）支持可选模板，缺省 "yyyy-MM-dd HH:mm:ss" 本地时区；
+ * 时长系列（durationNs / durationUs / durationMs）渲染成 "1.5s" / "200ms" 等可读形式；
+ * truncate 是字符截断工厂，参数为最大字符数。
+ *
+ * 业务层调用方式（注意调用，不是属性引用）：
+ *   { format: fmt.ns() }                              // 默认模板
+ *   { format: fmt.ns("yyyy-MM-dd HH:mm:ss.SSS") }     // 自定义模板
+ *   { format: fmt.durationMs() }
+ *   { format: fmt.truncate(120) }
+ */
+exports.fmt = {
+    /** 纳秒时间戳；可选模板 */
+    ns: (template) => makeTimestampFormatter(1e6, template),
+    /** 微秒时间戳；可选模板 */
+    us: (template) => makeTimestampFormatter(1e3, template),
+    /** 毫秒时间戳；可选模板 */
+    ms: (template) => makeTimestampFormatter(1, template),
+    /** 秒时间戳；可选模板 */
+    sec: (template) => makeTimestampFormatter(1 / 1000, template),
+    /** 纳秒时长 → "1.5s" / "200ms" 等可读形式 */
+    durationNs: () => makeDurationFormatter(1e6),
+    /** 微秒时长 */
+    durationUs: () => makeDurationFormatter(1e3),
+    /** 毫秒时长 */
+    durationMs: () => makeDurationFormatter(1),
+    /** 显式截断（仅 TTY 截断，pipe 保留完整值） */
+    truncate: makeTruncateFormatter,
+};
+// ── 字段选择 (--json field1,field2) ────────────
+function getFieldSelection() {
+    const cfg = (0, config_1.getConfig)();
+    if (typeof cfg.json !== "string")
+        return null;
+    const fields = cfg.json
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    return fields.length > 0 ? fields : null;
+}
+function pickFields(obj, fields) {
+    const out = {};
+    let matched = false;
+    for (const f of fields) {
+        if (f in obj) {
+            out[f] = obj[f];
+            matched = true;
+        }
+    }
+    // fail-open：异构 row（如 db sql 多语句的 INSERT 元素）一个 field 都没命中时
+    // 保留原 row，避免 INSERT 元数据被裁成空对象
+    return matched ? out : obj;
+}
+function applyFieldSelection(data, fields) {
+    if (Array.isArray(data)) {
+        return data.map((item) => typeof item === "object" && item !== null && !Array.isArray(item)
+            ? pickFields(item, fields)
+            : item);
+    }
+    if (typeof data === "object" && data !== null) {
+        return pickFields(data, fields);
+    }
+    return data;
+}
+// ── 信封识别 ────────────
+const ENVELOPE_KEYS = new Set(["data", "next_cursor", "has_more"]);
+function isEnvelope(v) {
+    if (typeof v !== "object" || v === null)
+        return false;
+    const keys = Object.keys(v);
+    if (!keys.includes("data"))
+        return false;
+    return keys.every((k) => ENVELOPE_KEYS.has(k));
+}
+// ── emit ────────────
 /**
  * 输出数据
- * - pretty 模式：格式化文本到 stdout
- * - json 模式：裸 JSON 到 stdout
+ * - JSON 模式：单行紧凑 JSON，**原样透传**（schema 不参与），仅 `--json a,b`
+ *   字段筛选会生效。这样下游消费者拿到的 JSON 形状与 BAM 接口契约一致。
+ * - Pretty 模式：信封 array → 表格；信封 object → key-value；非信封 → 缩进 JSON
+ *   - 有 schema 时：列顺序、标签、格式、derive 由 schema.columns 决定；
+ *     strict=false 时未声明字段在尾部追加
+ *   - 无 schema 时：时间戳字段按命名约定（*timestampNs/Us/Ms/sec）兜底渲染
  */
-function emit(data) {
+function emit(data, schema) {
+    let payload = data;
+    const fields = getFieldSelection();
+    if (fields && isEnvelope(payload)) {
+        payload = { ...payload, data: applyFieldSelection(payload.data, fields) };
+    }
     if (isJsonMode()) {
-        process.stdout.write(JSON.stringify(data) + "\n");
+        process.stdout.write(JSON.stringify(payload) + "\n");
+        return;
+    }
+    if (isEnvelope(payload)) {
+        emitPrettyEnvelope(payload, schema);
+        return;
+    }
+    if (typeof payload === "string") {
+        process.stdout.write(payload + "\n");
     }
     else {
-        if (typeof data === "string") {
-            process.stdout.write(data + "\n");
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    }
+}
+function emitPrettyEnvelope(env, schema) {
+    const { data, next_cursor, has_more } = env;
+    if (Array.isArray(data)) {
+        if (data.length === 0) {
+            process.stdout.write("(no results)\n");
         }
         else {
-            process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+            writeTable(data, schema);
         }
     }
+    else if (data !== null && typeof data === "object") {
+        writeKeyValue(data, schema);
+    }
+    else if (data === null || data === undefined) {
+        process.stdout.write("(empty)\n");
+    }
+    else {
+        process.stdout.write(defaultFormat(data) + "\n");
+    }
+    if (has_more && next_cursor) {
+        const count = Array.isArray(data) ? data.length : 1;
+        process.stdout.write(`\n— ${String(count)} results. Next: --cursor ${next_cursor}\n`);
+    }
+}
+function resolveColumnsFromSchema(schema) {
+    const cols = [];
+    const declared = new Set();
+    for (const col of schema.columns) {
+        declared.add(col.key);
+        cols.push({
+            key: col.key,
+            label: col.label ?? col.key,
+            format: col.format ?? defaultFormat,
+            derive: col.derive,
+        });
+    }
+    return { cols, declared };
+}
+function readCell(row, col) {
+    return col.derive ? col.derive(row) : row[col.key];
+}
+function resolveColumnsForRows(items, schema) {
+    if (schema) {
+        const { cols, declared } = resolveColumnsFromSchema(schema);
+        if (!schema.strict) {
+            for (const item of items) {
+                for (const k of Object.keys(item)) {
+                    if (!declared.has(k)) {
+                        declared.add(k);
+                        cols.push({ key: k, label: k, format: defaultFormat });
+                    }
+                }
+            }
+        }
+        return cols;
+    }
+    // 无 schema：列顺序按首次出现顺序，全部走 defaultFormat
+    const cols = [];
+    const seen = new Set();
+    for (const item of items) {
+        for (const k of Object.keys(item)) {
+            if (!seen.has(k)) {
+                seen.add(k);
+                cols.push({ key: k, label: k, format: defaultFormat });
+            }
+        }
+    }
+    return cols;
 }
+function writeTable(rows, schema) {
+    const items = rows.filter((r) => typeof r === "object" && r !== null && !Array.isArray(r));
+    if (items.length === 0) {
+        for (const row of rows)
+            process.stdout.write(defaultFormat(row) + "\n");
+        return;
+    }
+    const cols = resolveColumnsForRows(items, schema);
+    const matrix = [
+        cols.map((c) => c.label),
+        ...items.map((item) => cols.map((c) => c.format(readCell(item, c)))),
+    ];
+    if (process.stdout.isTTY) {
+        const widths = cols.map((_, i) => Math.max(...matrix.map((row) => row[i]?.length ?? 0)));
+        for (const row of matrix) {
+            const line = row
+                .map((cell, i) => cell.padEnd(widths[i] ?? 0))
+                .join("  ")
+                .trimEnd();
+            process.stdout.write(line + "\n");
+        }
+    }
+    else {
+        for (const row of matrix)
+            process.stdout.write(row.join("\t") + "\n");
+    }
+}
+function resolveColumnsForObject(obj, schema) {
+    if (schema) {
+        const { cols, declared } = resolveColumnsFromSchema(schema);
+        if (!schema.strict) {
+            for (const k of Object.keys(obj)) {
+                if (!declared.has(k)) {
+                    cols.push({ key: k, label: k, format: defaultFormat });
+                }
+            }
+        }
+        return cols;
+    }
+    return Object.keys(obj).map((k) => ({
+        key: k,
+        label: k,
+        format: defaultFormat,
+    }));
+}
+function writeKeyValue(obj, schema) {
+    const cols = resolveColumnsForObject(obj, schema);
+    if (cols.length === 0) {
+        process.stdout.write("(empty)\n");
+        return;
+    }
+    if (process.stdout.isTTY) {
+        const maxKey = Math.max(...cols.map((c) => c.label.length));
+        for (const c of cols) {
+            process.stdout.write(`${c.label.padStart(maxKey)}: ${c.format(readCell(obj, c))}\n`);
+        }
+    }
+    else {
+        for (const c of cols) {
+            process.stdout.write(`${c.label}\t${c.format(readCell(obj, c))}\n`);
+        }
+    }
+}
+// ── 错误输出 ────────────
 /**
  * 输出错误（写入 stderr）
  * - pretty 模式：Error: message\n  hint: ...
@@ -36,23 +388,56 @@ function emit(data) {
  */
 function emitError(err) {
     const info = toErrorInfo(err);
+    // 没人给过 next_actions 才走错误码兜底；handler 已经塞过具体 hint 时不覆盖
+    const hints = info.next_actions && info.next_actions.length > 0
+        ? info.next_actions
+        : (SERVER_ERROR_HINTS[info.code] ?? []);
     if (isJsonMode()) {
         const errObj = {
             code: info.code,
             message: info.message,
         };
-        if (info.next_actions && info.next_actions.length > 0) {
-            errObj.hint = info.next_actions.join(" ");
+        if (hints.length > 0) {
+            // JSON 输出压平成单行，更便于机器消费（脚本 / agent 拼字符串）
+            errObj.hint = hints.join(" ");
         }
         if (typeof info.statement_index === "number") {
             errObj.statement_index = info.statement_index;
         }
+        // PRD 多语句失败 envelope 额外字段：completed / rolled_back
+        if (Array.isArray(info.completed)) {
+            errObj.completed = info.completed;
+        }
+        if (typeof info.rolled_back === "boolean") {
+            errObj.rolled_back = info.rolled_back;
+        }
         process.stderr.write(JSON.stringify({ error: errObj }) + "\n");
     }
     else {
-        process.stderr.write(`Error: ${info.message}\n`);
-        if (info.next_actions && info.next_actions.length > 0) {
-            process.stderr.write(`  hint: ${info.next_actions.join(" ")}\n`);
+        // stderr 染色：picocolors 默认按 stdout.isTTY 判断；stderr 通常也是 tty，
+        // 这里复用 stdout 探测保持简单（stderr only-pipe 的极端场景留作后续优化）
+        // 多语句失败时 Error 行末尾追加 "(at statement K of N)"，与 PRD spec 对齐
+        let errorLine = `${colors_1.c.fail("Error:")} ${info.message}`;
+        if (typeof info.statement_index === "number") {
+            const k = info.statement_index + 1;
+            const n = info.total_statements;
+            errorLine +=
+                typeof n === "number" && n > 0
+                    ? ` (at statement ${String(k)} of ${String(n)})`
+                    : ` (at statement ${String(k)})`;
+        }
+        process.stderr.write(errorLine + "\n");
+        // 多行 hint：第一行带 "hint:" 标签，后续行用 8 空格缩进对齐 "  hint: " 之后的列。
+        // 对应 spec 期望的格式：
+        //   Error: ...
+        //     hint: 第一条建议
+        //           第二条建议
+        if (hints.length > 0) {
+            const [first, ...rest] = hints;
+            process.stderr.write(`  ${colors_1.c.muted("hint:")} ${first}\n`);
+            for (const line of rest) {
+                process.stderr.write(`        ${line}\n`);
+            }
         }
     }
 }