@lark-apaas/miaoda-cli 0.1.0-alpha.08508f4

package/LICENSE

@@ -0,0 +1,13 @@
+MIT License
+
+Copyright (c) 2024 Lark Technologies Pte. Ltd. and/or its affiliates
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted,provided that the above copyright notice and this permission notice appear in all copies.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE
+INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
+CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
+DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
+ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# miaoda-cli
+
+妙搭开发平台 Code Agent 命令行工具，为 Agent 提供原子能力。
+
+## 安装
+
+```bash
+pnpm add -g @lark-apaas/miaoda-cli
+```
+
+## 使用
+
+```bash
+# 设置默认应用（需要应用上下文的命令可用 --app-id 覆盖）
+export MIAODA_APP_ID=app_demo_xxx
+
+# 插件管理
+miaoda plugin list-packages
+miaoda plugin install @demo/example-plugin
+```
+
+JSON 结构化输出（Agent 推荐）：
+
+```bash
+# 输出全部字段
+miaoda plugin list --json
+
+# 可选字段级选择
+miaoda plugin list --json id,name
+
+# 或通过 --output 指定格式
+miaoda plugin list --output json
+```
+
+## 命令树
+
+命令以"域"作为第一级命名空间：
+
+| 域 | 用途 |
+|---|---|
+| `miaoda plugin ...` | 插件管理：安装、更新、移除、插件实例查询 |
+
+完整命令通过 `miaoda --help` 或 `miaoda <domain> --help` 查看。
+
+## 全局参数
+
+- `--json [fields]`：输出结构化 JSON，可选字段级选择（如 `--json id,name`）。
+- `--output <pretty|json>`：输出格式，默认 `pretty`。
+- `--verbose`：输出调试日志到 stderr。
+
+> `--app-id <id>` 非全局参数，需要应用上下文的命令会各自声明，默认读取 `MIAODA_APP_ID` 环境变量。
+
+## 环境变量
+
+- `MIAODA_APP_ID`：默认应用 ID，等价于 `--app-id`。
+- `MIAODA_CANARY_HEADER`：设置后所有 HTTP 请求自动带上 `x-tt-env: <值>` 小流量头（例：`export MIAODA_CANARY_HEADER=boe_xxx`）。
+
+## 输出契约
+
+- 默认文本输出（pretty），`--json` 或 `--output json` 切换为 JSON。
+- 错误始终写 stderr，业务数据写 stdout。
+- 完整的输出格式、JSON envelope、错误 shape、错误码前缀、退出码分类等见 [Agent 友好 CLI 设计规范](./docs/agent-friendly-cli.md)。
+
+## 贡献
+
+详见 [AGENTS.md](./AGENTS.md)。

package/bin/miaoda.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/main.js");

package/dist/api/db/api.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.execSql = execSql;
+exports.getSchema = getSchema;
+exports.importData = importData;
+exports.exportData = exportData;
+const http_1 = require("../../utils/http");
+const error_1 = require("../../utils/error");
+const client_1 = require("./client");
+// CLI 不再为 dbBranch 设默认值：
+// 用户没传 --env 就完全不携带 dbBranch query 参数，由后端 admin-inner 中间件
+// 按 workspace 多环境状态决定（多环境 → dev / 单环境 → main）。
+// 这样可以避免单环境应用被强行打到 main 之外、或多环境应用被默认打到 main 上线库。
+// ── db sql → InnerAdminExecuteSQL ──
+/**
+ * 执行 SQL（admin-inner）。
+ * 后端：POST /v1/dataloom/app/{appId}/db/sql?dbBranch=main
+ *
+ * 返回所有 results[]（多条语句时每条一项）；CLI 侧按 PRD 仅取最后一条展示，
+ * 但 API 层保留完整列表以便测试和高级用法。
+ */
+async function execSql(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/sql", {
+        dbBranch: opts.dbBranch,
+    });
+    const start = Date.now();
+    const response = await client.post(url, { sql: opts.sql });
+    (0, client_1.traceHttp)("POST", url, start, response);
+    if (!response.ok) {
+        // 4xx / 5xx：尝试解析 body 取 status_code 映射业务错误
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // ignore
+        }
+        if (body)
+            (0, client_1.extractData)(body);
+        throw new error_1.HttpError(response.status, url, `Failed to execute SQL: ${String(response.status)} ${response.statusText}`);
+    }
+    const body = (await response.json());
+    const data = (0, client_1.extractData)(body);
+    return data.results ?? [];
+}
+// ── db schema → InnerGetSchema ──
+/**
+ * 查询 schema（admin-inner）。
+ * 后端：GET /v1/dataloom/app/{appId}/db/schema?format=schema|ddl&tableNames=...&includeStats=...&dbBranch=main
+ *
+ * 返回 body.data（含 `schema` 或 `ddl`）供 handler 使用。
+ */
+async function getSchema(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/db/schema", {
+        format: opts.format ?? "schema",
+        tableNames: opts.tableNames,
+        includeStats: opts.includeStats ? "true" : undefined,
+        dbBranch: opts.dbBranch,
+    });
+    const start = Date.now();
+    const response = await client.get(url);
+    (0, client_1.traceHttp)("GET", url, start, response);
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // ignore
+        }
+        if (body)
+            (0, client_1.extractData)(body);
+        throw new error_1.HttpError(response.status, url, `Failed to get schema: ${String(response.status)} ${response.statusText}`);
+    }
+    const body = (await response.json());
+    return (0, client_1.extractData)(body);
+}
+// ── db data import → InnerAdminImportData ──
+/**
+ * 导入文件。
+ * 后端：POST /v1/dataloom/app/{appId}/data/import
+ *
+ * 全字段走 JSON body envelope（idl-larkgw 36125a2f）：
+ *   {tableName, format, records, dbBranch?}
+ *
+ * `records` 字段携带 CSV / JSON 文本内容（utf8 字符串），与 dataloom 上
+ * Import/ExportAdminRecords 命名风格对齐。CLI 端把 Buffer 解码成 utf8
+ * 字符串后塞进 envelope 即可。
+ */
+async function importData(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/data/import");
+    const reqBody = {
+        tableName: opts.tableName,
+        format: opts.format,
+        records: opts.body.toString("utf8"),
+    };
+    if (opts.dbBranch !== undefined && opts.dbBranch !== "") {
+        reqBody.dbBranch = opts.dbBranch;
+    }
+    const start = Date.now();
+    const response = await client.post(url, reqBody);
+    (0, client_1.traceHttp)("POST", url, start, response);
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // ignore
+        }
+        if (body)
+            (0, client_1.extractData)(body);
+        throw new error_1.HttpError(response.status, url, `Failed to import data: ${String(response.status)} ${response.statusText}`);
+    }
+    // 后端 InnerAdminImportData 响应里 data 直接返 {tableName, recordCount, durationMs}
+    const body = (await response.json());
+    const data = (0, client_1.extractData)(body);
+    return {
+        tableName: data.tableName ?? opts.tableName,
+        recordCount: data.recordCount ?? 0,
+        durationMs: data.durationMs ?? 0,
+    };
+}
+// ── db data export → InnerAdminExportData ──
+/**
+ * 导出数据。
+ * 后端：POST /v1/dataloom/app/{appId}/data/export?tableName=...&format=csv|json&limit=5000&dbBranch=main
+ *
+ * 所有参数（含 limit）均按 IDL `api.query` 走 query string；HTTP 方法是 POST（对齐
+ * inner_api 网关插件路由约定，与 InnerAdminExecuteSQL 同 method）。请求体为空。
+ * 响应 body 为原始 CSV/JSON 字节，RecordCount 通过响应头 `X-Miaoda-Record-Count`
+ * 回传，错误仍走 HTTP 4xx/5xx + envelope。
+ */
+async function exportData(opts) {
+    const client = (0, http_1.getHttpClient)();
+    const url = (0, client_1.buildInnerUrl)(opts.appId, "/data/export", {
+        tableName: opts.tableName,
+        format: opts.format,
+        limit: String(opts.limit ?? 5000),
+        dbBranch: opts.dbBranch,
+    });
+    // POST + 空 body：所有业务参数都在 query 里
+    const start = Date.now();
+    const response = await client.request({ method: "POST", url });
+    (0, client_1.traceHttp)("POST", url, start, response);
+    if (!response.ok) {
+        // 错误路径：body 是 JSON envelope
+        let body = null;
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // ignore
+        }
+        if (body)
+            (0, client_1.extractData)(body);
+        throw new error_1.HttpError(response.status, url, `Failed to export data: ${String(response.status)} ${response.statusText}`);
+    }
+    // 成功路径：响应 body 通常是原始 CSV/JSON 字节，但部分错误场景下网关会返
+    // HTTP 200 + JSON envelope（status_code != "0"），需要在这里嗅探兜底。
+    const contentType = response.headers.get("Content-Type") ??
+        (opts.format === "csv" ? "text/csv" : "application/json");
+    const ab = await response.arrayBuffer();
+    const buf = Buffer.from(new Uint8Array(ab));
+    if (buf.length === 0) {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "Empty export response body");
+    }
+    // Envelope sniff：HTTP 200 + Content-Type 为 application/json + body 解析得到
+    // InnerEnvelope 且 status_code 非 "0" 时，按业务错误抛出。
+    // 仅 CSV 格式做 sniff —— JSON 格式正常成功响应也是 application/json，会误判。
+    if (opts.format === "csv" && /application\/json/i.test(contentType)) {
+        try {
+            const parsed = JSON.parse(buf.toString("utf8"));
+            if (parsed.status_code != null && parsed.status_code !== "0") {
+                // 复用 extractData 的错误映射逻辑（throw AppError）
+                (0, client_1.extractData)(parsed);
+            }
+        }
+        catch (err) {
+            // 已经被 extractData 抛成 AppError → 透传；否则 JSON.parse 失败说明 body
+            // 真的是 CSV 文本，继续按成功流程走
+            if (err instanceof error_1.AppError)
+                throw err;
+        }
+    }
+    // 后端通过响应头回传记录数（避免污染 body）；header 缺失或解析失败 → undefined
+    const recordCountHeader = response.headers.get("X-Miaoda-Record-Count");
+    const parsedCount = recordCountHeader != null ? Number(recordCountHeader) : NaN;
+    const recordCount = Number.isFinite(parsedCount) && parsedCount >= 0 ? parsedCount : undefined;
+    return {
+        tableName: opts.tableName,
+        format: opts.format,
+        contentType,
+        body: buf,
+        recordCount,
+    };
+}

package/dist/api/db/client.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SQLSTATE_MAP = void 0;
+exports.traceHttp = traceHttp;
+exports.ensureInnerSuccess = ensureInnerSuccess;
+exports.extractData = extractData;
+exports.buildInnerUrl = buildInnerUrl;
+const error_1 = require("../../utils/error");
+const logger_1 = require("../../utils/logger");
+/**
+ * 输出一条 HTTP 调试日志（仅 --verbose 模式生效）。
+ *
+ * 主要用于把后端返回的 `x-tt-logid` 透出给用户，方便拿这个 id 去 server / 网关日志里
+ * 直接定位本次请求的 `[MiaodaCLI.metric]` 行与上下游 trace。
+ *
+ * 使用约定：
+ *   const start = Date.now();
+ *   const response = await client.post(url, body);
+ *   traceHttp("POST", url, start, response);
+ *   // 或错误路径：traceHttp("POST", url, start, err.response, err)
+ */
+function traceHttp(method, url, start, response, err) {
+    // debug() 内部已判断 verbose 开关，这里不重复判断；保持调用点轻量
+    try {
+        const cost = Date.now() - start;
+        const status = response?.status ?? 0;
+        const logid = response?.headers?.get?.("x-tt-logid") ?? "-";
+        if (err !== undefined) {
+            const errMsg = err instanceof Error
+                ? err.message
+                : typeof err === "string"
+                    ? err
+                    : JSON.stringify(err);
+            (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid} err=${errMsg}`);
+            return;
+        }
+        (0, logger_1.debug)(`http ${method} ${url} ${String(status)} cost=${String(cost)}ms x-tt-logid=${logid}`);
+    }
+    catch {
+        // debug 失败不应影响业务，吞掉
+    }
+}
+/**
+ * 校验 dataloom InnerAPI 响应的 envelope。
+ *
+ * 真实响应结构：`{ data: {...业务字段...}, status_code: "0" }`
+ * - `status_code == "0"` 或缺省视为成功
+ * - 其他值视为业务错误，按业务 code 或 SQLSTATE 映射到 CLI code
+ */
+function ensureInnerSuccess(body) {
+    if (!body) {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "empty response body");
+    }
+    const code = body.status_code ?? body.ErrorCode ?? "0";
+    if (code === "0" || code === "")
+        return;
+    const message = stripPgPrefix(body.error_msg ?? body.ErrorMessage ?? `dataloom API error [${code}]`);
+    // PRD 多语句失败：后端在 envelope 顶层透出 errorStatementIndex（从 0 起计），
+    // 单语句 / 单元执行不会带这个字段。下面的 AppError 都把它带上，让最终
+    // CLI JSON envelope 写到 error.statement_index。
+    const stmtIdx = typeof body.errorStatementIndex === "number" ? body.errorStatementIndex : undefined;
+    // k_dl_1300002 是 PG 执行透传错误；error_msg 里常带 SQLSTATE，优先按 SQLSTATE 映射
+    if (code === "k_dl_1300002") {
+        const sqlstate = extractSqlstate(message);
+        if (sqlstate && exports.SQLSTATE_MAP[sqlstate]) {
+            throw new error_1.AppError(exports.SQLSTATE_MAP[sqlstate], message, { statement_index: stmtIdx });
+        }
+    }
+    // k_dl_1600000 是 dataloom 通用参数错误，不能整体映射；
+    // message 以 "Invalid DB Branch" 开头的两种触发场景：
+    //   1) 单环境应用使用 --env（多环境未初始化）
+    //   2) 多环境应用传入了不存在的 env 名（如 --env staging）
+    // 两者外部表象一致：dbBranch 在 db_branch 表里查不到，固定映射为 MULTI_ENV_NOT_INITIALIZED。
+    if (code === "k_dl_1600000" && message.startsWith("Invalid DB Branch")) {
+        throw new error_1.AppError("MULTI_ENV_NOT_INITIALIZED", "--env is not available (multi-env not initialized)", {
+            next_actions: [
+                "Verify the --env value matches an existing dbBranch.",
+            ],
+        });
+    }
+    // 业务 code 优先映射到语义 CLI code；未知 code 透传为 DB_API_<code> 样式
+    const mapped = BIZ_ERR_MAP.get(code);
+    if (mapped) {
+        throw new error_1.AppError(mapped.code, mapped.message ?? message, {
+            next_actions: mapped.hint ? [mapped.hint] : undefined,
+            statement_index: stmtIdx,
+        });
+    }
+    // 兜底：dataloom 未映射的 code 原样透传
+    throw new error_1.AppError(`DB_API_${code}`, message, { statement_index: stmtIdx });
+}
+/**
+ * 剥掉 PG 透传错误的 "ERROR:" 前缀：CLI 输出本身就会前缀 "Error:"，
+ * 不去掉就会变成 `Error: ERROR: relation ...` 双重前缀，PRD 不要这种冗余。
+ * 大小写敏感，只匹配 PG 标准格式。
+ */
+function stripPgPrefix(msg) {
+    return msg.replace(/^ERROR:\s*/, "");
+}
+/** 从 PG 执行错误消息里提取 "(SQLSTATE XXXXX)"。 */
+function extractSqlstate(msg) {
+    const m = /SQLSTATE\s+([0-9A-Z]{5})/.exec(msg);
+    return m?.[1];
+}
+/**
+ * dataloom 业务错误码 → CLI 语义化 code 映射。
+ *
+ * 长期维护，观察到新 code 在此增补。
+ * 常见 dataloom 错误：详见 `common/dataloom_error/` 错误码定义（范围 `k_dl_*xxxxx`）。
+ */
+const BIZ_ERR_MAP = new Map(Object.entries({
+    // 来源：真实环境探测（dataloom InnerExecuteSQL / InnerGetSchema）
+    // k_dl_000001：DB 连接 / QPS 限流 等基础设施层错误
+    "k_dl_000001": { code: "INTERNAL_DB_ERROR", hint: "检查 dbBranch 与应用 PG 实例状态，或稍后重试" },
+    // k_dl_000002：SQL 解析 / 不支持的 SQL 类型（VACUUM、COPY、SET、SHOW 等）
+    "k_dl_000002": { code: "SQL_SYNTAX_ERROR" },
+    // k_dl_000003：查询命中系统表（pg_tables / pg_user 等）被拒
+    "k_dl_000003": { code: "SQL_OPERATION_FORBIDDEN" },
+    // k_dl_1300002：PG 执行错误；实际 SQLSTATE 由 extractSqlstate 单独映射
+    // 未匹配到 SQLSTATE 时走下面兜底 DB_API_<code>
+}));
+/** PG SQLSTATE → CLI code（当前 dataloom 不一定透传，预留未来使用） */
+exports.SQLSTATE_MAP = {
+    "42601": "SQL_SYNTAX_ERROR",
+    "42P01": "TABLE_NOT_FOUND",
+    "42703": "COLUMN_NOT_FOUND",
+    "57014": "STATEMENT_TIMEOUT",
+    "23505": "UNIQUE_VIOLATION",
+    "22P02": "TYPE_MISMATCH",
+};
+/**
+ * 从 envelope 里取 data 业务字段，校验成功后返回；失败则 throw。
+ */
+function extractData(body) {
+    ensureInnerSuccess(body);
+    if (!body?.data) {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "response missing data field");
+    }
+    return body.data;
+}
+/**
+ * 组装 `/v1/dataloom/app/{appId}/...` URL（admin-inner 链路）。
+ *
+ * 后端 IDL 已把 dataloom 的 4 个 inner 接口切到管理态（ForceAdminKctx），
+ * 路径前缀也统一改为 `/v1/dataloom/app/:appID/...`：
+ *   - sql:    POST /v1/dataloom/app/{appId}/db/sql
+ *   - schema: GET  /v1/dataloom/app/{appId}/db/schema
+ *   - import: POST /v1/dataloom/app/{appId}/data/import
+ *   - export: POST /v1/dataloom/app/{appId}/data/export
+ * 调用方传入的 path 已包含 `/db` / `/data` 中段，这里只负责拼前缀和 query。
+ */
+function buildInnerUrl(appId, path, query) {
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    let url = `/v1/dataloom/app/${encodeURIComponent(appId)}${normalized}`;
+    if (query) {
+        const usp = new URLSearchParams();
+        for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined && v !== "")
+                usp.append(k, v);
+        }
+        const qs = usp.toString();
+        if (qs)
+            url += `?${qs}`;
+    }
+    return url;
+}

package/dist/api/db/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickTableDetail = exports.flattenSchemaList = exports.parseSqlResult = exports.SQLSTATE_MAP = exports.ensureInnerSuccess = exports.buildInnerUrl = exports.exportData = exports.importData = exports.getSchema = exports.execSql = void 0;
+var api_1 = require("./api");
+Object.defineProperty(exports, "execSql", { enumerable: true, get: function () { return api_1.execSql; } });
+Object.defineProperty(exports, "getSchema", { enumerable: true, get: function () { return api_1.getSchema; } });
+Object.defineProperty(exports, "importData", { enumerable: true, get: function () { return api_1.importData; } });
+Object.defineProperty(exports, "exportData", { enumerable: true, get: function () { return api_1.exportData; } });
+var client_1 = require("./client");
+Object.defineProperty(exports, "buildInnerUrl", { enumerable: true, get: function () { return client_1.buildInnerUrl; } });
+Object.defineProperty(exports, "ensureInnerSuccess", { enumerable: true, get: function () { return client_1.ensureInnerSuccess; } });
+Object.defineProperty(exports, "SQLSTATE_MAP", { enumerable: true, get: function () { return client_1.SQLSTATE_MAP; } });
+var parsers_1 = require("./parsers");
+Object.defineProperty(exports, "parseSqlResult", { enumerable: true, get: function () { return parsers_1.parseSqlResult; } });
+Object.defineProperty(exports, "flattenSchemaList", { enumerable: true, get: function () { return parsers_1.flattenSchemaList; } });
+Object.defineProperty(exports, "pickTableDetail", { enumerable: true, get: function () { return parsers_1.pickTableDetail; } });

package/dist/api/db/parsers.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSqlResult = parseSqlResult;
+exports.flattenSchemaList = flattenSchemaList;
+exports.pickTableDetail = pickTableDetail;
+const error_1 = require("../../utils/error");
+// ── SQL 结果 ──
+/**
+ * 解析 InnerExecuteSQL 的单条 results[]（PRD 要求多条语句只取最后一条）。
+ */
+function parseSqlResult(r) {
+    if (r.sqlType === "SELECT") {
+        let rows = [];
+        if (r.data) {
+            try {
+                const parsed = JSON.parse(r.data);
+                if (Array.isArray(parsed))
+                    rows = parsed;
+            }
+            catch {
+                throw new error_1.AppError("INTERNAL_DB_ERROR", "Failed to parse SELECT result JSON");
+            }
+        }
+        return {
+            kind: "select",
+            rows,
+            recordCount: r.recordCount ?? rows.length,
+        };
+    }
+    if (r.sqlType === "INSERT" ||
+        r.sqlType === "UPDATE" ||
+        r.sqlType === "DELETE" ||
+        r.sqlType === "MERGE" ||
+        r.sqlType === "DML") {
+        const affected = r.affectedRows ?? extractRowCount(r.data);
+        return {
+            kind: "dml",
+            // 上面已 narrow，这里 cast 是为了 SqlType 联合里的 (string & {}) 让 TS 无法
+            // 自动收窄到字面量集合，不影响运行时安全
+            sqlType: r.sqlType,
+            affectedRows: affected,
+        };
+    }
+    // DDL or unknown — sqlType 透传后端给的细粒度（CREATE_TABLE / DROP_TABLE / ...
+    //  / 笼统 "DDL"），CLI JSON 输出直接当 command 用
+    return { kind: "ddl", sqlType: r.sqlType };
+}
+/** DML 的 data 通常是 `[{"rowCount": N}]`；兜底从这里读影响行数。 */
+function extractRowCount(data) {
+    if (!data)
+        return 0;
+    try {
+        const parsed = JSON.parse(data);
+        if (Array.isArray(parsed) && parsed.length > 0) {
+            const first = parsed[0];
+            const v = first.rowCount ?? first.affected_rows;
+            if (typeof v === "number")
+                return v;
+        }
+    }
+    catch {
+        // ignore
+    }
+    return 0;
+}
+// ── schema ──
+/**
+ * 合并 tables / views / materializedViews 为扁平 TableSummary[]（schema list 视图）。
+ * 统计信息（estimated_row_count / size_bytes）来自 `root.tableStats[tableName]`，
+ * 需请求带 `includeStats=true` 才会有。
+ */
+function flattenSchemaList(root) {
+    if (!root)
+        return [];
+    const statsMap = root.tableStats ?? {};
+    const out = [];
+    for (const t of root.tables?.data ?? [])
+        out.push(toSummary(t, statsMap[t.tableName]));
+    for (const v of root.views?.data ?? [])
+        out.push(toSummary(v, statsMap[v.tableName]));
+    for (const mv of root.materializedViews?.data ?? [])
+        out.push(toSummary(mv, statsMap[mv.tableName]));
+    return out;
+}
+function toSummary(t, stats) {
+    return {
+        name: t.tableName,
+        description: t.comment && t.comment.length > 0 ? t.comment : null,
+        columns: (t.fields ?? []).length,
+        estimated_row_count: typeof stats?.estimatedRowCount === "number" ? stats.estimatedRowCount : null,
+        size_bytes: typeof stats?.sizeBytes === "number" ? stats.sizeBytes : null,
+    };
+}
+/**
+ * 从 InnerSchemaRespVO 里定位单表 → 转 CLI TableDetail。
+ * 依次查 tables / views / materializedViews；找不到返回 null。
+ */
+function pickTableDetail(root, tableName) {
+    if (!root)
+        return null;
+    const stats = root.tableStats?.[tableName];
+    const pools = [
+        root.tables?.data,
+        root.views?.data,
+        root.materializedViews?.data,
+    ];
+    for (const arr of pools) {
+        if (!arr)
+            continue;
+        const hit = arr.find((t) => t.tableName === tableName);
+        if (hit)
+            return toDetail(hit, stats);
+    }
+    return null;
+}
+function toDetail(t, stats) {
+    // 优先用 tableStats.indexes（PRIMARY + UNIQUE + INDEX 统一视图）；
+    // 回退到 TableVO.indexes（仅二级索引，老后端没返回 tableStats 时使用）
+    const rawIndexes = stats?.indexes ?? t.indexes ?? [];
+    return {
+        name: t.tableName,
+        description: t.comment && t.comment.length > 0 ? t.comment : null,
+        columns: (t.fields ?? []).map(toColumn),
+        indexes: rawIndexes.map(toIndex),
+        estimated_row_count: typeof stats?.estimatedRowCount === "number" ? stats.estimatedRowCount : null,
+        size_bytes: typeof stats?.sizeBytes === "number" ? stats.sizeBytes : null,
+    };
+}
+function toColumn(f) {
+    const type = f.arrayElementType ? `${f.arrayElementType}[]` : f.type;
+    return {
+        name: f.fieldName,
+        type,
+        nullable: f.isNullable ?? false,
+        default: f.defaultValue ?? null,
+        // 后端 comment *string 在没有 comment 时可能返 "" 或 null，这里统一归一为 null（对齐 PRD）
+        comment: f.comment && f.comment.length > 0 ? f.comment : null,
+    };
+}
+function toIndex(i) {
+    return {
+        name: i.indexName,
+        type: translateIndexType(i.indexType),
+        columns: i.indexColumns ?? [],
+    };
+}
+/**
+ * 把后端原始 IndexType（小写：primary / unique / normal / foreign）翻译为 PRD 约定的展示值。
+ * 规则：
+ *   primary  → "PRIMARY KEY"
+ *   unique   → "UNIQUE"
+ *   其它    → "INDEX"（foreign 外键通过 relationships 表达，不进 indexes；真的遇到也归 INDEX）
+ */
+function translateIndexType(raw) {
+    const s = raw.toLowerCase();
+    if (s === "primary")
+        return "PRIMARY KEY";
+    if (s === "unique")
+        return "UNIQUE";
+    return "INDEX";
+}

package/dist/api/db/types.js

@@ -0,0 +1,10 @@
+"use strict";
+// ── dataloom InnerAPI 响应信封 ──
+//
+// 实际响应结构（与 file-storage 类似）：
+//   { "data": { ...业务字段... }, "status_code": "0", "error_msg": "..." }
+//
+// - `status_code == "0"` 成功
+// - `status_code != "0"` 业务错误（如 PG SQLSTATE 映射后的 code）
+// - 业务字段统一在 `data` 下：`results` / `schema` / `ddl` 等
+Object.defineProperty(exports, "__esModule", { value: true });