@lark-apaas/miaoda-cli 0.1.0 → 0.1.1-alpha.06e1628

package/dist/cli/commands/file/index.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFileCommands = registerFileCommands;
+const index_1 = require("../../../cli/handlers/file/index");
+const error_1 = require("../../../utils/error");
+/**
+ * commander option 校验器：把 --limit <n> 解析成正整数（≥1）。
+ * 默认值（如 "50"）会先经过这里被规范化成 number。
+ * 非整数 / 负数 / 0 抛 AppError("ARGS_INVALID")，由 main.ts 的全局 catch
+ * 走 emitError，同时 process.exitCode 由 commander 自然为 1。
+ */
+function parsePositiveInt(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new error_1.AppError("ARGS_INVALID", `--limit must be a positive integer (got '${raw}')`);
+    }
+    return n;
+}
+function registerFileCommands(program) {
+    const fileCmd = program
+        .command("file")
+        .description("应用文件存储（TOS）的命令行操作集合。操作对象是 UGC 资源（用户上传的文件、应用运行时\n" +
+        "生成的报表 / 导出文件等），不涉及代码仓库里的本地文件。")
+        .usage("<command> [flags]");
+    fileCmd.action(() => {
+        fileCmd.outputHelp();
+    });
+    fileCmd
+        .command("ls")
+        .summary("列出 / 筛选文件")
+        .description("列出当前应用存储里的文件，支持按文件名、大小、上传时间筛选，以及游标分页。\n" +
+        "默认 pretty 输出省略 download_url（列宽限制），需获取请用 --json。")
+        .usage("[query] [flags]")
+        .argument("[query]", "筛选值：以 / 开头视为路径精确匹配，否则按文件名精确匹配")
+        .option("--path <path>", "按路径精确匹配")
+        .option("--name <name>", "按文件名精确匹配")
+        .option("--type <mime>", "按 MIME 类型筛选（如 image/png）")
+        .option("--size-gt <size>", "文件大小下限（支持 B / KB / MB / GB）")
+        .option("--size-lt <size>", "文件大小上限（支持 B / KB / MB / GB）")
+        .option("--uploaded-since <time>", "上传时间下限（晚于该时间），支持：相对时间 1h / 2d / 1w；日期 YYYY-MM-DD；ISO 8601 如 2026-04-01T10:00:00Z")
+        .option("--uploaded-until <time>", "上传时间上限（早于该时间），支持：相对时间 1h / 2d / 1w；日期 YYYY-MM-DD；ISO 8601 如 2026-04-01T10:00:00Z")
+        .option("--limit <n>", "单次返回上限（正整数,默认 50）", parsePositiveInt, 50)
+        .option("--cursor <token>", "分页游标，从上次响应的 next_cursor 取值")
+        .option("--all", "自动翻页返回全部结果")
+        .action(async (query, opts) => {
+        await (0, index_1.handleFileLs)({ ...opts, query });
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda file ls
+  file_name    path                                size      type              uploaded_at
+  logo.png     /images/brand/1858537546760216.png  24 KB     image/png         3h ago
+  hero.jpg     /images/1858537546760217.jpg        128 KB    image/jpeg        2d ago
+  report.pdf   /docs/1858537546760218.pdf          2.1 MB    application/pdf   2026-04-10
+
+  $ miaoda file ls --name logo.png
+  file_name    path                                size      type        uploaded_at
+  logo.png     /images/brand/1858537546760216.png  24 KB     image/png   3h ago
+
+  $ miaoda file ls --uploaded-since 7d --size-gt 1MB
+  ...
+`);
+    fileCmd
+        .command("stat")
+        .summary("查看单文件元数据")
+        .description("查看单文件完整元数据，含 download_url（应用内消费）。\n" +
+        "需要公网可访问的临时链接请用 `file sign` 生成 signed_url。")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名（自动识别）")
+        .action(async (file, opts) => {
+        await (0, index_1.handleFileStat)(file, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - <file> 可传 path（推荐，全局唯一）或 file_name。
+  - file_name 重名时报 AMBIGUOUS_FILE_NAME，需先 \`ls --name\` 拿到 path 再调用。
+
+Examples:
+  $ miaoda file stat /images/brand/1858537546760216.png
+       file_name:  logo.png
+            path:  /images/brand/1858537546760216.png
+            size:  24 KB (24580 bytes)
+            type:  image/png
+     uploaded_by:  alice
+     uploaded_at:  2026-04-15 10:30:00
+    download_url:  /spark/app/.../1858537546760216.png
+
+  # 报错：file_name 多匹配
+  $ miaoda file stat logo.png
+  Error: Multiple files match name 'logo.png' (2 found)
+    hint: Use path instead. Run \`miaoda file ls --name logo.png\` to see candidates.
+`);
+    fileCmd
+        .command("cp")
+        .summary("上传或下载文件（方向由路径前缀自动判断）")
+        .description("上传或下载文件，方向由 src/dst 路径前缀自动判断：\n" +
+        "  / 开头           → 远程 TOS 路径\n" +
+        "  ./、~/、裸文件名  → 本地路径")
+        .usage("<src> <dst> [flags]")
+        .argument("<src>", "源：本地文件路径或远程文件路径 / 文件名")
+        .argument("<dst>", "目标：本地路径或远程路径")
+        .option("--rename <name>", "上传后在远端使用的新文件名")
+        .action(async (src, dst, opts) => {
+        await (0, index_1.handleFileCp)(src, dst, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - 单文件上限 100 MB，超过请拆分或用 web console 上传。
+  - 同目录下允许同 file_name 并存（每次上传生成新的 path），不会因重名失败。
+  - 下载时 src 必须是完整 path（裸 file_name 会被识别为本地路径）。
+  - 上传成功返回 download_url，可写入数据库 / 应用代码作为永久引用。
+
+Examples:
+  # 上传：本地 → 远程
+  $ miaoda file cp ./logo.png /images/brand/
+  ✓ Uploaded logo.png → /images/brand/1858537546760216.png
+         file_name:  logo.png
+              path:  /images/brand/1858537546760216.png
+              size:  24 KB (24580 bytes)
+              type:  image/png
+      download_url:  /spark/app/.../1858537546760216.png
+
+  # 下载：远程 → 本地
+  $ miaoda file cp /images/brand/1858537546760216.png ~/Desktop/
+  ✓ Downloaded 1858537546760216.png → ~/Desktop/logo.png (24 KB)
+
+  # 上传时改名
+  $ miaoda file cp ./photo.png /images/ --rename avatar.png
+  ✓ Uploaded photo.png → /images/1858537546760301.png
+
+  # 报错：本地源文件不存在
+  $ miaoda file cp ./missing.png /images/
+  Error: Local file './missing.png' does not exist
+
+  # 报错：超过上传上限
+  $ miaoda file cp ./video.mp4 /videos/
+  Error: File size 230 MB exceeds the 100 MB upload limit
+    hint: Split the file, or use the web console for large uploads.
+`);
+    fileCmd
+        .command("rm")
+        .summary("删除一个或多个文件")
+        .description("删除一个或多个文件。<file> 可传 path（推荐）或 file_name，可混用。\n" +
+        "操作不可撤销（不进回收站），TTY 下默认会要求二次确认。")
+        .usage("[paths...] [flags]")
+        .argument("[paths...]", "要删除的文件，每项可填路径或文件名（自动识别）")
+        .option("-n, --name <name>", "按文件名删除（可重复指定）", (value, prev) => [...(prev ?? []), value])
+        .option("-y, --yes", "跳过交互确认；非交互场景必加")
+        .action(async (paths, opts) => {
+        await (0, index_1.handleFileRm)(paths, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - 删除不可撤销，没有回收站。
+  - 批量场景下失败项不影响其他项；全部成功退出码 0，任意一项失败退出码 1。
+  - --json 输出每项保留输入顺序，含 status: "ok" | "error" 字段。
+
+Examples:
+  # 单文件删除（TTY 下需确认）
+  $ miaoda file rm /images/brand/1858537546760216.png
+  ? Delete '/images/brand/1858537546760216.png'? (y/N) y
+  ✓ Deleted /images/brand/1858537546760216.png
+
+  # 批量删除（混用 path 与 file_name）
+  $ miaoda file rm /images/A.png /images/B.png /docs/C.pdf --yes
+  ✓ Deleted /images/A.png
+  ✓ Deleted /images/B.png
+  ✓ Deleted /docs/C.pdf
+  Deleted 3 of 3 files
+
+  # 部分失败（其他项仍会被删除）
+  $ miaoda file rm logo.png missing.png report.pdf --yes
+  ✓ Deleted logo.png
+  ✗ missing.png: File does not exist
+  ✓ Deleted report.pdf
+  Deleted 2 of 3 files (1 failed)
+
+  # 报错：file_name 多匹配
+  $ miaoda file rm logo.png --yes
+  Error: Multiple files match name 'logo.png' (2 found)
+    hint: Use path instead. Run \`miaoda file ls --name logo.png\` to see candidates.
+`);
+    fileCmd
+        .command("sign")
+        .summary("生成公网可访问的临时下载链接")
+        .description("生成 signed_url——公网可直接访问的临时下载链接，带过期时间。\n" +
+        "仅在需要浏览器打开 / 公网分享时使用；应用代码内引用文件请用 download_url\n" +
+        "（来自 cp 或 stat），无需 sign。")
+        .usage("<file> [flags]")
+        .argument("<file>", "文件的路径或文件名")
+        .option("--expires <duration>", "链接有效期，支持 30m / 24h / 7d 等单位（默认 1d，最长 30d）")
+        .action(async (file, opts) => {
+        await (0, index_1.handleFileSign)(file, opts);
+    })
+        .addHelpText("after", `
+Notes:
+  - <file> 可传 path（推荐）或 file_name；重名报 AMBIGUOUS_FILE_NAME。
+  - signed_url 会过期，不要持久化到数据库。永久引用请用 download_url。
+
+Examples:
+  $ miaoda file sign /images/brand/1858537546760216.png
+  https://miaoda.feishu.cn/storage/.../1858537546760216.png?token=xxx&expires=86400
+
+  $ miaoda file sign /images/brand/1858537546760216.png --expires 30d
+  https://miaoda.feishu.cn/storage/.../1858537546760216.png?token=xxx&expires=2592000
+
+  # 报错：过期时间超过上限
+  $ miaoda file sign /images/brand/1858537546760216.png --expires 60d
+  Error: Expires duration '60d' exceeds the maximum of 30d
+    hint: Maximum allowed value is 30d. Use \`--expires 30d\` for the longest link.
+`);
+}

package/dist/cli/commands/index.js

@@ -2,6 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerCommands = registerCommands;
 const index_1 = require("../../cli/commands/plugin/index");
+const index_2 = require("../../cli/commands/file/index");
+const index_3 = require("../../cli/commands/db/index");
 function registerCommands(program) {
     (0, index_1.registerPluginCommands)(program);
+    (0, index_2.registerFileCommands)(program);
+    (0, index_3.registerDbCommands)(program);
 }

package/dist/cli/commands/plugin/index.js

@@ -5,7 +5,8 @@ const index_1 = require("../../../cli/handlers/plugin/index");
 function registerPluginCommands(program) {
     const pluginCmd = program
         .command("plugin")
-        .description("插件管理：安装/更新/移除插件包，查询 capability 实例");
+        .description("插件管理：安装/更新/移除插件包，查询 capability 实例")
+        .usage("<command> [flags]");
     pluginCmd.action(() => {
         pluginCmd.outputHelp();
     });

package/dist/cli/commands/shared.js

@@ -1,29 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.appIdOption = appIdOption;
 exports.softRequiredOption = softRequiredOption;
 exports.resolveAppId = resolveAppId;
 exports.withHelp = withHelp;
 exports.failArgs = failArgs;
 const commander_1 = require("commander");
 const error_1 = require("../../utils/error");
-/** --app-id option，需要应用上下文的命令自行 .addOption(appIdOption()) */
-function appIdOption() {
-    return new commander_1.Option("--app-id <id>", "指定目标应用").env("MIAODA_APP_ID");
-}
 /**
  * soft-required: Commander 类型上 optional，runtime 校验必填。
  */
 function softRequiredOption(name, desc) {
     return new commander_1.Option(name, desc);
 }
-/** 解析 appId，CLI flag > env > 抛错 */
+/**
+ * 解析 appId，从环境变量 MIAODA_APP_ID 或 app_id（小写下划线，部分外部沙箱注入）读取。
+ * 缺失时抛 APP_ID_MISSING，由全局 catch 处理。
+ *
+ * opts 里仍保留 appId（可选），用于测试 / 高级场景显式注入；正常 CLI 不暴露此 flag。
+ */
 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: [
-                "传入 --app-id <id>",
                 "设置 export MIAODA_APP_ID=<id>",
             ],
         });

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

@@ -0,0 +1,183 @@
+"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.handleDbDataImport = handleDbDataImport;
+exports.handleDbDataExport = handleDbDataExport;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const api = __importStar(require("../../../api/index"));
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const shared_1 = require("../../../cli/commands/shared");
+const render_1 = require("../../../utils/render");
+// P0 规格（对齐技术方案关键决策 2）
+const MAX_SIZE_BYTES = 1 * 1024 * 1024; // 1 MB
+const MAX_ROWS = 5000;
+async function handleDbDataImport(file, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const ext = path.extname(file).toLowerCase();
+    const format = resolveFormat(opts.format, ext, "import");
+    let body;
+    try {
+        body = await fs.readFile(file);
+    }
+    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 err;
+    }
+    if (body.length > MAX_SIZE_BYTES) {
+        throw new error_1.AppError("IMPORT_SIZE_EXCEEDED", `Import exceeds 1 MB limit (file is ${String(body.length)} bytes)`, { next_actions: ["Split the file into chunks of ≤ 5000 rows / 1 MB and import separately."] });
+    }
+    const rowCount = countRows(body, format);
+    if (rowCount > MAX_ROWS) {
+        throw new error_1.AppError("IMPORT_ROWS_EXCEEDED", `Import exceeds 5000 rows limit (file has ${String(rowCount)} rows)`, { next_actions: ["Split the file into chunks of ≤ 5000 rows / 1 MB and import separately."] });
+    }
+    const tableName = opts.table ?? path.basename(file, ext);
+    if (!tableName) {
+        throw new error_1.AppError("ARGS_INVALID", "Cannot infer target table from file name; specify --table");
+    }
+    const result = await api.db.importData({
+        appId,
+        tableName,
+        format,
+        body,
+    });
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({
+            data: {
+                file,
+                table: result.tableName,
+                rows: result.recordCount,
+            },
+        });
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    (0, output_1.emit)(tty
+        ? `✓ Imported ${file} → table '${result.tableName}' (${String(result.recordCount)} rows)`
+        : `OK Imported ${file} -> table '${result.tableName}' (${String(result.recordCount)} rows)`);
+}
+async function handleDbDataExport(table, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const format = resolveFormat(opts.format, undefined, "export", "csv");
+    const outputPath = opts.file ?? `${table}.${format}`;
+    const limit = opts.limit ? Number(opts.limit) : MAX_ROWS;
+    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,
+        format,
+        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.`] });
+    }
+    await fs.writeFile(outputPath, result.body);
+    // 优先信任后端 X-Miaoda-Record-Count header；header 缺失时再用 body 行数兜底
+    const rows = result.recordCount ?? countRows(result.body, format);
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({
+            data: {
+                table,
+                file: outputPath,
+                format,
+                rows,
+            },
+        });
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    (0, output_1.emit)(tty
+        ? `✓ Exported ${table} → ${outputPath} (${String(rows)} rows)`
+        : `OK Exported ${table} -> ${outputPath} (${String(rows)} rows)`);
+}
+// ── 共用辅助 ──
+function resolveFormat(explicit, ext, scope, fallback) {
+    const raw = (explicit ?? ext ?? fallback ?? "").replace(/^\./, "").toLowerCase();
+    if (raw === "csv")
+        return "csv";
+    if (raw === "json")
+        return "json";
+    // sql 仅 export 路径接受 —— import 端后端仍只支持 csv/json。
+    if (raw === "sql" && scope === "export")
+        return "sql";
+    const code = scope === "import" ? "IMPORT_FORMAT_UNSUPPORTED" : "EXPORT_FORMAT_UNSUPPORTED";
+    throw new error_1.AppError(code, `Unrecognized format '${raw || "(unspecified)"}'`, {
+        next_actions: [
+            scope === "import"
+                ? "Supported formats: .csv, .json. Convert the file first, or rename with the correct extension."
+                : "Supported formats: csv, json, sql. Pass --format csv|json|sql.",
+        ],
+    });
+}
+function countRows(body, format) {
+    if (format === "csv") {
+        // 粗估：非空行数 - 表头 1 行
+        let lines = 0;
+        const text = body.toString("utf8");
+        for (const line of text.split(/\r?\n/)) {
+            if (line.length > 0)
+                lines += 1;
+        }
+        return Math.max(0, lines - 1);
+    }
+    // JSON：期望是顶层数组
+    try {
+        const parsed = JSON.parse(body.toString("utf8"));
+        if (Array.isArray(parsed))
+            return parsed.length;
+        return 1;
+    }
+    catch {
+        return 0;
+    }
+}

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

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDbDataExport = exports.handleDbDataImport = exports.handleDbSchemaGet = exports.handleDbSchemaList = exports.handleDbSql = void 0;
+var sql_1 = require("./sql");
+Object.defineProperty(exports, "handleDbSql", { enumerable: true, get: function () { return sql_1.handleDbSql; } });
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "handleDbSchemaList", { enumerable: true, get: function () { return schema_1.handleDbSchemaList; } });
+Object.defineProperty(exports, "handleDbSchemaGet", { enumerable: true, get: function () { return schema_1.handleDbSchemaGet; } });
+var data_1 = require("./data");
+Object.defineProperty(exports, "handleDbDataImport", { enumerable: true, get: function () { return data_1.handleDbDataImport; } });
+Object.defineProperty(exports, "handleDbDataExport", { enumerable: true, get: function () { return data_1.handleDbDataExport; } });

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

@@ -0,0 +1,174 @@
+"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.handleDbSchemaList = handleDbSchemaList;
+exports.handleDbSchemaGet = handleDbSchemaGet;
+const api = __importStar(require("../../../api/index"));
+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 tables = (0, index_1.flattenSchemaList)(resp.schema);
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emit)({ data: tables });
+        return;
+    }
+    if (tables.length === 0) {
+        (0, output_1.emit)("No tables found.");
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    // PRD 对齐：TTY 表头用 `size`（友好格式），non-TTY 用 `size_bytes`（原始整数）。
+    // updated_at 暂时不展示——PG pg_catalog 不存真实表时间，详见 renderDetail 注释。
+    const headers = [
+        "name",
+        "description",
+        "estimated_row_count",
+        tty ? "size" : "size_bytes",
+        "columns",
+    ];
+    const rows = tables.map((t) => [
+        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)),
+        String(t.columns),
+    ]);
+    (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
+}
+async function handleDbSchemaGet(table, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const tty = (0, render_1.isStdoutTty)();
+    const forceDdl = Boolean(opts.ddl);
+    const wantsStructured = (0, output_1.isJsonMode)() || (tty && !forceDdl);
+    if (!wantsStructured) {
+        // non-TTY 或 --ddl：直接取完整 DDL 输出
+        const ddlResp = await api.db.getSchema({
+            appId,
+            format: "ddl",
+            tableNames: table,
+            dbBranch: opts.env,
+        });
+        const sql = ddlResp.ddl?.[table];
+        if (!sql) {
+            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.`,
+                ],
+            });
+        }
+        (0, output_1.emit)(sql.trimEnd());
+        return;
+    }
+    // TTY / JSON：取结构化
+    const resp = await api.db.getSchema({
+        appId,
+        format: "schema",
+        tableNames: table,
+        includeStats: true,
+        dbBranch: opts.env,
+    });
+    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.`,
+            ],
+        });
+    }
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emitOk)(detail);
+        return;
+    }
+    (0, output_1.emit)(renderDetail(detail, tty));
+}
+function renderDetail(d, tty) {
+    const systemFields = d.columns.filter((c) => c.name.startsWith("_"));
+    const userFields = d.columns.filter((c) => !c.name.startsWith("_"));
+    // header 布局：Name / Description / Columns(含"+ N system") / Estimated Rows / Size。
+    // 不展示 Created / Updated：PG pg_catalog 不存表创建时间，dataloom 用 OID
+    // 构造的伪时间戳（baseTime=2020-01-01 + OID 秒偏移），仅保排序意义、绝对值
+    // 误导性强，先去掉。后续如果接 ddl_change_log 取真实时间再加回。
+    const header = [
+        // 表名做 cyan 强调（spec：spec 里的"命令名/表名"类强调值都走 highlight）
+        ["Name", tty ? colors_1.c.highlight(d.name) : d.name],
+        ["Description", d.description ?? "—"],
+        [
+            "Columns",
+            systemFields.length > 0
+                ? `${String(userFields.length)} (+ ${String(systemFields.length)} system)`
+                : String(userFields.length),
+        ],
+        ["Estimated Rows", d.estimated_row_count === null ? "—" : String(d.estimated_row_count)],
+        ["Size", d.size_bytes === null ? "—" : (0, render_1.formatSize)(d.size_bytes)],
+    ];
+    const colHeaders = ["column", "type", "nullable", "default", "comment"];
+    const colRows = userFields.map((c) => [
+        c.name,
+        c.type,
+        c.nullable ? "yes" : "no",
+        c.default ?? "—",
+        c.comment ?? "—",
+    ]);
+    const parts = [];
+    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:");
+        for (const idx of d.indexes) {
+            const line = `${idx.name} ON ${idx.columns.join(", ")} USING ${idx.method}`;
+            parts.push(tty ? `    ${line}` : line);
+        }
+    }
+    return parts.join("\n");
+}