@lark-apaas/miaoda-cli 0.1.0-alpha.36c401b → 0.1.0-alpha.3879164

package/dist/api/db/_debug_trace.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceRequest = traceRequest;
+exports.traceResponse = traceResponse;
+exports.traceError = traceError;
+const config_1 = require("../../utils/config");
+const logger_1 = require("../../utils/logger");
+/**
+ * 从 HttpClient 实例抠出 baseURL，用于把相对 path 拼成完整 URL 输出。
+ * defaultConfig.baseURL 在 http-client 0.1.4 d.ts 里没声明但运行时可访问；
+ * 找不到时返回空串（trace 仍能输出 path，只是不完整）。
+ */
+function clientBaseURL(client) {
+    return client?.defaultConfig?.baseURL ?? "";
+}
+/**
+ * 给 client 注册一个最后的 request interceptor：等 platform plugin / canary
+ * 等其它拦截器把 JWT / AK/SK / X-Miaoda-Client-Token / x-tt-env 注入 cfg.headers
+ * 之后，用注入完毕的 cfg 拼一行可直接复制运行的 curl 命令打到 stderr。
+ *
+ * 拦截器只装一次（用 client 实例的 Symbol 标记），verbose 关闭时拦截器内
+ * 直接 return（零开销）。
+ */
+function installCurlTrace(client) {
+    const c = client;
+    if (c.__miaoda_curl_trace_installed__)
+        return;
+    // 单测里的 mock client 没有 interceptors，直接 noop 避免炸测试。
+    const interceptors = client.interceptors;
+    if (!interceptors)
+        return;
+    c.__miaoda_curl_trace_installed__ = true;
+    interceptors.request.use((cfg) => {
+        if (!(0, config_1.getConfig)().verbose)
+            return cfg;
+        const method = (cfg.method ?? "GET").toUpperCase();
+        const url = `${cfg.baseURL ?? ""}${cfg.url ?? ""}`;
+        const parts = [`curl -i -X ${method} '${url}'`];
+        const headers = cfg.headers instanceof Headers
+            ? cfg.headers
+            : new Headers(cfg.headers ?? {});
+        headers.forEach((v, k) => parts.push(`  -H '${k}: ${v}'`));
+        if (cfg.body !== undefined && cfg.body !== null) {
+            let body;
+            if (typeof cfg.body === "string")
+                body = cfg.body;
+            else if (cfg.body instanceof ArrayBuffer || cfg.body instanceof Uint8Array)
+                body = "<binary>";
+            else
+                body = JSON.stringify(cfg.body);
+            const escaped = body.replace(/'/g, "'\\''");
+            parts.push(`  -d '${escaped}'`);
+        }
+        (0, logger_1.debug)(`curl:\n${parts.join(" \\\n")}`);
+        return cfg;
+    });
+}
+/** 请求前打 method + 完整 URL；同时懒装 curl-trace 拦截器（idempotent）。 */
+function traceRequest(method, url, client) {
+    if (client)
+        installCurlTrace(client);
+    (0, logger_1.debug)(`http → ${method} ${clientBaseURL(client)}${url}`);
+}
+/** 响应后打 status + x-tt-logid。 */
+function traceResponse(method, url, status, headers, client) {
+    const logId = headers?.get("x-tt-logid") ?? headers?.get("X-Tt-Logid") ?? "(none)";
+    (0, logger_1.debug)(`http ← ${method} ${clientBaseURL(client)}${url} status=${String(status)} x-tt-logid=${logId}`);
+}
+/**
+ * 网络层错误（fetch failed / DNS / TLS / 连接拒绝）兜底：response 没回来，
+ * 没有 logid，但要把错误原因记到 trace，避免用户只看到 "Error: fetch failed"。
+ */
+function traceError(method, url, err, client) {
+    const msg = err instanceof Error ? err.message : String(err);
+    (0, logger_1.debug)(`http ✗ ${method} ${clientBaseURL(client)}${url} (no response, network-level error: ${msg})`);
+}

package/dist/api/db/api.js

@@ -5,6 +5,8 @@ exports.getSchema = getSchema;
 exports.importData = importData;
 exports.exportData = exportData;
 const http_1 = require("../../utils/http");
+// TODO(REMOVE-BEFORE-RELEASE): debug-only HTTP trace（详见 _debug_trace.ts）
+const _debug_trace_1 = require("./_debug_trace");
 const error_1 = require("../../utils/error");
 const client_1 = require("./client");
 // CLI 不再为 dbBranch 设默认值：
@@ -24,7 +26,16 @@ async function execSql(opts) {
     const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/sql", {
         dbBranch: opts.dbBranch,
     });
-    const response = await client.post(url, { sql: opts.sql });
+    let response;
+    try {
+        (0, _debug_trace_1.traceRequest)("POST", url, client);
+        response = await client.post(url, { sql: opts.sql });
+        (0, _debug_trace_1.traceResponse)("POST", url, response.status, response.headers, client);
+    }
+    catch (err) {
+        (0, _debug_trace_1.traceError)("POST", url, err, client);
+        throw err;
+    }
     if (!response.ok) {
         // 4xx / 5xx：尝试解析 body 取 status_code 映射业务错误
         let body = null;
@@ -57,7 +68,16 @@ async function getSchema(opts) {
         includeStats: opts.includeStats ? "true" : undefined,
         dbBranch: opts.dbBranch,
     });
-    const response = await client.get(url);
+    let response;
+    try {
+        (0, _debug_trace_1.traceRequest)("GET", url, client);
+        response = await client.get(url);
+        (0, _debug_trace_1.traceResponse)("GET", url, response.status, response.headers, client);
+    }
+    catch (err) {
+        (0, _debug_trace_1.traceError)("GET", url, err, client);
+        throw err;
+    }
     if (!response.ok) {
         let body = null;
         try {
@@ -89,12 +109,21 @@ async function importData(opts) {
     });
     const contentType = opts.format === "csv" ? "text/csv" : "application/json";
     const ab = opts.body.buffer.slice(opts.body.byteOffset, opts.body.byteOffset + opts.body.byteLength);
-    const response = await client.request({
-        method: "POST",
-        url,
-        headers: { "Content-Type": contentType },
-        body: ab,
-    });
+    let response;
+    try {
+        (0, _debug_trace_1.traceRequest)("POST", url, client);
+        response = await client.request({
+            method: "POST",
+            url,
+            headers: { "Content-Type": contentType },
+            body: ab,
+        });
+        (0, _debug_trace_1.traceResponse)("POST", url, response.status, response.headers, client);
+    }
+    catch (err) {
+        (0, _debug_trace_1.traceError)("POST", url, err, client);
+        throw err;
+    }
     if (!response.ok) {
         let body = null;
         try {
@@ -131,7 +160,16 @@ async function exportData(opts) {
         dbBranch: opts.dbBranch,
     });
     const reqBody = { limit: opts.limit ?? 5000 };
-    const response = await client.post(url, reqBody);
+    let response;
+    try {
+        (0, _debug_trace_1.traceRequest)("POST", url, client);
+        response = await client.post(url, reqBody);
+        (0, _debug_trace_1.traceResponse)("POST", url, response.status, response.headers, client);
+    }
+    catch (err) {
+        (0, _debug_trace_1.traceError)("POST", url, err, client);
+        throw err;
+    }
     if (!response.ok) {
         // 错误路径：body 是 JSON envelope
         let body = null;

package/dist/api/file/_debug_trace.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.traceRequest = traceRequest;
+exports.traceResponse = traceResponse;
+exports.traceError = traceError;
+const config_1 = require("../../utils/config");
+const logger_1 = require("../../utils/logger");
+function clientBaseURL(client) {
+    return client?.defaultConfig?.baseURL ?? "";
+}
+function installCurlTrace(client) {
+    const c = client;
+    if (c.__miaoda_curl_trace_installed__)
+        return;
+    // 单测里的 mock client 没有 interceptors，直接 noop 避免炸测试。
+    const interceptors = client.interceptors;
+    if (!interceptors)
+        return;
+    c.__miaoda_curl_trace_installed__ = true;
+    interceptors.request.use((cfg) => {
+        if (!(0, config_1.getConfig)().verbose)
+            return cfg;
+        const method = (cfg.method ?? "GET").toUpperCase();
+        const url = `${cfg.baseURL ?? ""}${cfg.url ?? ""}`;
+        const parts = [`curl -i -X ${method} '${url}'`];
+        const headers = cfg.headers instanceof Headers
+            ? cfg.headers
+            : new Headers(cfg.headers ?? {});
+        headers.forEach((v, k) => parts.push(`  -H '${k}: ${v}'`));
+        if (cfg.body !== undefined && cfg.body !== null) {
+            let body;
+            if (typeof cfg.body === "string")
+                body = cfg.body;
+            else if (cfg.body instanceof ArrayBuffer || cfg.body instanceof Uint8Array)
+                body = "<binary>";
+            else
+                body = JSON.stringify(cfg.body);
+            const escaped = body.replace(/'/g, "'\\''");
+            parts.push(`  -d '${escaped}'`);
+        }
+        (0, logger_1.debug)(`curl:\n${parts.join(" \\\n")}`);
+        return cfg;
+    });
+}
+/** 请求前打 method + 完整 URL；同时懒装 curl-trace 拦截器（idempotent）。 */
+function traceRequest(method, url, client) {
+    if (client)
+        installCurlTrace(client);
+    (0, logger_1.debug)(`http → ${method} ${clientBaseURL(client)}${url}`);
+}
+/** 响应后打 status + x-tt-logid。 */
+function traceResponse(method, url, status, headers, client) {
+    const logId = headers?.get("x-tt-logid") ?? headers?.get("X-Tt-Logid") ?? "(none)";
+    (0, logger_1.debug)(`http ← ${method} ${clientBaseURL(client)}${url} status=${String(status)} x-tt-logid=${logId}`);
+}
+/**
+ * 网络层错误（fetch failed / DNS / TLS / 连接拒绝）兜底：response 没回来，
+ * 没有 logid，但要把错误原因记到 trace，避免用户只看到 "Error: fetch failed"。
+ */
+function traceError(method, url, err, client) {
+    const msg = err instanceof Error ? err.message : String(err);
+    (0, logger_1.debug)(`http ✗ ${method} ${clientBaseURL(client)}${url} (no response, network-level error: ${msg})`);
+}

package/dist/api/file/client.js

@@ -8,6 +8,8 @@ exports.doPost = doPost;
 exports.doRequest = doRequest;
 const http_1 = require("../../utils/http");
 const error_1 = require("../../utils/error");
+// TODO(REMOVE-BEFORE-RELEASE): debug-only HTTP trace（详见 _debug_trace.ts）
+const _debug_trace_1 = require("./_debug_trace");
 const http_client_1 = require("@lark-apaas/http-client");
 /** 进程内 bucket 缓存：{appId: bucketId}。不跨进程。 */
 const bucketCache = new Map();
@@ -131,10 +133,18 @@ async function mapHttpError(err, opts) {
  */
 async function doGet(url, opts = {}, client = (0, http_1.getHttpClient)()) {
     try {
+        (0, _debug_trace_1.traceRequest)("GET", url, client);
         const response = await client.get(url);
+        (0, _debug_trace_1.traceResponse)("GET", url, response.status, response.headers, client);
         return (await response.json());
     }
     catch (err) {
+        if (err instanceof http_client_1.HttpError && err.response) {
+            (0, _debug_trace_1.traceResponse)("GET", url, err.response.status, err.response.headers, client);
+        }
+        else {
+            (0, _debug_trace_1.traceError)("GET", url, err, client);
+        }
         await mapHttpError(err, opts);
         throw err; // 不可达，mapHttpError 必定 throw
     }
@@ -142,10 +152,18 @@ async function doGet(url, opts = {}, client = (0, http_1.getHttpClient)()) {
 /** 包一层 client.post + HttpError 统一映射。默认 admin innerapi，可显式切 runtime。 */
 async function doPost(url, body, opts = {}, client = (0, http_1.getHttpClient)()) {
     try {
+        (0, _debug_trace_1.traceRequest)("POST", url, client);
         const response = await client.post(url, body);
+        (0, _debug_trace_1.traceResponse)("POST", url, response.status, response.headers, client);
         return (await response.json());
     }
     catch (err) {
+        if (err instanceof http_client_1.HttpError && err.response) {
+            (0, _debug_trace_1.traceResponse)("POST", url, err.response.status, err.response.headers, client);
+        }
+        else {
+            (0, _debug_trace_1.traceError)("POST", url, err, client);
+        }
         await mapHttpError(err, opts);
         throw err;
     }
@@ -153,10 +171,18 @@ async function doPost(url, body, opts = {}, client = (0, http_1.getHttpClient)()
 /** 包一层 client.request + HttpError 统一映射（DELETE 带 body 的场景）。 */
 async function doRequest(cfg, opts = {}, client = (0, http_1.getHttpClient)()) {
     try {
+        (0, _debug_trace_1.traceRequest)(cfg.method, cfg.url, client);
         const response = await client.request(cfg);
+        (0, _debug_trace_1.traceResponse)(cfg.method, cfg.url, response.status, response.headers, client);
         return (await response.json());
     }
     catch (err) {
+        if (err instanceof http_client_1.HttpError && err.response) {
+            (0, _debug_trace_1.traceResponse)(cfg.method, cfg.url, err.response.status, err.response.headers, client);
+        }
+        else {
+            (0, _debug_trace_1.traceError)(cfg.method, cfg.url, err, client);
+        }
         await mapHttpError(err, opts);
         throw err;
     }

package/dist/cli/commands/shared.js

@@ -7,7 +7,9 @@ exports.withHelp = withHelp;
 exports.failArgs = failArgs;
 const commander_1 = require("commander");
 const error_1 = require("../../utils/error");
-/** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption()) */
+/** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption())。
+ * Commander 的 .env() 只接受单个变量名，第二个兜底 `app_id` 在 resolveAppId 里手动检查。
+ */
 function appIdOption() {
     return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
 }
@@ -17,9 +19,12 @@ function appIdOption() {
 function softRequiredOption(name, desc) {
     return new commander_1.Option(name, desc);
 }
-/** 解析 appId，CLI flag > env > 抛错 */
+/**
+ * 解析 appId，优先级：CLI flag > MIAODA_APP_ID > app_id > 抛错。
+ * app_id 是部分外部沙箱环境注入应用 ID 的别名，作为兜底兼容（小写下划线形态）。
+ */
 function resolveAppId(opts) {
-    const id = opts.appId ?? process.env.MIAODA_APP_ID;
+    const id = opts.appId ?? process.env.MIAODA_APP_ID ?? process.env.app_id;
     if (!id) {
         throw new error_1.AppError("APP_ID_MISSING", "未指定应用", {
             next_actions: [

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

@@ -114,7 +114,7 @@ function renderSingle(raw) {
             return;
         }
         const cols = collectColumns(parsed.rows);
-        const rows = parsed.rows.map((r) => cols.map((c) => formatCell(r[c])));
+        const rows = parsed.rows.map((r) => cols.map((c) => formatCell(r[c], tty)));
         (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(cols, rows) : (0, render_1.renderTsv)(cols, rows));
         return;
     }
@@ -155,9 +155,19 @@ function collectColumns(rows) {
         return [];
     return Object.keys(rows[0]);
 }
-function formatCell(v) {
-    if (v === null || v === undefined)
-        return "—";
+/**
+ * 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 ? "\u001b[2;90mNULL\u001b[0m" : "NULL";
+    }
     if (typeof v === "string")
         return v;
     if (typeof v === "number" || typeof v === "boolean")

package/dist/utils/render.js

@@ -14,6 +14,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatSize = formatSize;
 exports.formatTime = formatTime;
+exports.visibleWidth = visibleWidth;
 exports.renderAlignedTable = renderAlignedTable;
 exports.renderTsv = renderTsv;
 exports.renderKeyValue = renderKeyValue;
@@ -64,21 +65,35 @@ function formatTime(iso, isTty) {
     const da = String(date.getDate()).padStart(2, "0");
     return `${y}-${mo}-${da}`;
 }
-/** 渲染 TTY 对齐表格（多行，列宽按最长内容）。 */
+/**
+ * SGR (Select Graphic Rendition) ANSI 转义匹配：`ESC[<digits;...>m`。
+ * 用于在列宽计算时剥离不显示的控制字符——否则带 ANSI 颜色的 cell 会按 .length
+ * 算进列宽（比如 dim "NULL" 实际占 4 字符但 .length=11），导致表格对齐错位。
+ */
+const ANSI_SGR_RE = /\[[0-9;]*m/g;
+/** cell 可见字符宽度：剥离 ANSI 转义后再算长度。 */
+function visibleWidth(s) {
+    return s.replace(ANSI_SGR_RE, "").length;
+}
+function padVisibleEnd(s, targetWidth) {
+    const w = visibleWidth(s);
+    return w >= targetWidth ? s : s + " ".repeat(targetWidth - w);
+}
+/** 渲染 TTY 对齐表格（多行，列宽按最长内容；ANSI 转义不计入列宽）。 */
 function renderAlignedTable(headers, rows) {
     const colWidths = headers.map((h, i) => {
-        let w = h.length;
+        let w = visibleWidth(h);
         for (const row of rows) {
-            const cell = row[i] || "";
-            if (cell.length > w)
-                w = cell.length;
+            const cw = visibleWidth(row[i] || "");
+            if (cw > w)
+                w = cw;
         }
         return w;
     });
     const lines = [];
-    lines.push(headers.map((h, i) => h.padEnd(colWidths[i])).join("  ").trimEnd());
+    lines.push(headers.map((h, i) => padVisibleEnd(h, colWidths[i])).join("  ").trimEnd());
     for (const row of rows) {
-        lines.push(row.map((cell, i) => (cell || "").padEnd(colWidths[i])).join("  ").trimEnd());
+        lines.push(row.map((cell, i) => padVisibleEnd(cell || "", colWidths[i])).join("  ").trimEnd());
     }
     return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/miaoda-cli",
-  "version": "0.1.0-alpha.36c401b",
+  "version": "0.1.0-alpha.3879164",
   "description": "Miaoda 平台命令行工具，面向 Agent 调用",
   "type": "commonjs",
   "bin": {