@lark-apaas/miaoda-cli 0.1.2-alpha.4d0ff57 → 0.1.2-alpha.746290f

package/dist/api/db/client.js

@@ -140,7 +140,7 @@ const BIZ_ERR_MAP = new Map(Object.entries({
     },
     k_dl_1310003: {
         code: "INVALID_RETENTION",
-        hint: "Allowed values: 7d / 30d / 180d / 360d.",
+        hint: "Allowed values: 7d, 30d, 180d, 360d, forever.",
     },
     // migration
     k_dl_1320001: {

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

@@ -251,7 +251,7 @@ Examples:
         .summary("启用表审计")
         .usage("<table> [flags]")
         .argument("<table>", "目标表名")
-        .option("--retention <ttl>", "保留时长 7d / 30d / 180d / 360d", "7d")
+        .option("--retention <ttl>", "保留时长 7d / 30d / 180d / 360d / forever", "7d")
         .action(async function (table) {
         await (0, index_1.handleDbAuditEnable)(table, this.optsWithGlobals());
     });

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

@@ -44,8 +44,7 @@ const error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 const index_2 = require("../../../api/db/index");
-// "forever" 不在后端支持范围（pg_audit ValidDay 只接 int64 天数），CLI 提前拦截
-const VALID_RETENTION = new Set(["7d", "30d", "180d", "360d"]);
+const VALID_RETENTION = new Set(["7d", "30d", "180d", "360d", "forever"]);
 async function handleDbAuditStatus(table, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const sql = table !== undefined && table !== ""
@@ -53,13 +52,19 @@ async function handleDbAuditStatus(table, opts) {
         : `SELECT "table", enabled, enabled_at, retention FROM _dl_audit_config ORDER BY "table"`;
     const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
     const rows = collectSelectRows(results);
-    // 单表查询：表未配置时给个 enabled=false 占位项，让 CLI 输出语义统一
+    // 单表查询且 _dl_audit_config 没记录 → enabled=false 占位
     if (table !== undefined && table !== "" && rows.length === 0) {
         rows.push({ table, enabled: false });
     }
     const items = rows.map(toAuditStatus);
+    // PRD JSON：单表返 object，多表返 array
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)({ items });
+        if (table !== undefined && items.length === 1) {
+            (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(items[0]));
+        }
+        else {
+            (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(items));
+        }
         return;
     }
     if (items.length === 0) {
@@ -67,56 +72,59 @@ async function handleDbAuditStatus(table, opts) {
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    // 单表显式查询（rows.length=1 且对应输入 table）走 key/value 形态，更可读
+    // 单表 → key:value 形态（PRD 示例）
     if (table !== undefined && items.length === 1) {
         const it = items[0];
         (0, output_1.emit)((0, render_1.renderKeyValue)([
-            ["table", it.table],
-            ["enabled", String(it.enabled)],
-            ["enabled_at", it.enabled_at ? (0, render_1.formatTime)(it.enabled_at, tty) : "—"],
-            ["retention", it.retention ?? "—"],
+            ["Table", it.table],
+            ["Enabled", boolToYesNo(it.enabled)],
+            ["Enabled at", it.enabled_at ? (0, render_1.formatTime)(it.enabled_at, tty) : "—"],
+            ["Retention", it.retention ?? "—"],
         ], tty));
         return;
     }
+    // 列表 → table 形态
     const headers = ["table", "enabled", "enabled_at", "retention"];
     const out = items.map((it) => [
         it.table,
-        String(it.enabled),
+        boolToYesNo(it.enabled),
         it.enabled_at ? (0, render_1.formatTime)(it.enabled_at, tty) : "—",
         it.retention ?? "—",
     ]);
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, out) : (0, render_1.renderTsv)(headers, out));
 }
 function toAuditStatus(row) {
+    // retention 列存的是后端 ValidDay (int64 天数)，按 sentinel 反向映射成 PRD 字符串
+    const rawRetention = row.retention;
+    let retention = null;
+    if (rawRetention != null) {
+        if (typeof rawRetention === "number") {
+            retention = retentionDaysToString(rawRetention);
+        }
+        else if (typeof rawRetention === "string") {
+            // 兼容存的就是字符串形态（"7d" / "forever"）
+            retention = rawRetention;
+        }
+    }
     return {
         table: asString(row.table),
         enabled: Boolean(row.enabled),
         enabled_at: row.enabled_at == null ? null : asString(row.enabled_at),
-        retention: row.retention == null ? null : asString(row.retention),
+        retention,
     };
 }
-// asString 把 SELECT 结果里的列值（unknown）安全地转成字符串。SQL 返回值通常是
-// string / number / boolean / null，但极端情况下也可能是 JSON 反序列化出的对象。
-// 直接 String(obj) 会得到 "[object Object]"，这里改用 typeof 分类避免。
-function asString(v, fallback = "") {
-    if (v == null)
-        return fallback;
-    if (typeof v === "string")
-        return v;
-    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint")
-        return String(v);
-    return JSON.stringify(v);
-}
 async function handleDbAuditEnable(table, opts) {
     if (!table) {
         throw new error_1.AppError("ARGS_INVALID", "table name is required", {
-            next_actions: ["Usage: miaoda db audit enable <table> [--retention 7d|30d|180d|360d]"],
+            next_actions: [
+                "Usage: miaoda db audit enable <table> [--retention 7d|30d|180d|360d|forever]",
+            ],
         });
     }
     const retention = opts.retention ?? "7d";
     if (!VALID_RETENTION.has(retention)) {
-        throw new error_1.AppError("INVALID_RETENTION", `invalid retention: ${retention}`, {
-            next_actions: ["Allowed values: 7d / 30d / 180d / 360d."],
+        throw new error_1.AppError("INVALID_RETENTION", `Invalid retention '${retention}'`, {
+            next_actions: ["Allowed values: 7d, 30d, 180d, 360d, forever."],
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
@@ -127,11 +135,18 @@ async function handleDbAuditEnable(table, opts) {
         retention,
         dbBranch: opts.env,
     });
+    // PRD JSON：{"data": {"table": "...", "enabled": true, "retention": "..."}}
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)({ status });
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            table: status.table,
+            enabled: status.enabled,
+            retention: status.retention ?? retention,
+        }));
         return;
     }
-    (0, output_1.emit)(`✓ Audit enabled for '${status.table}' (retention=${status.retention ?? retention})`);
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    (0, output_1.emit)(`${prefix} Audit enabled for table '${status.table}' (retention: ${status.retention ?? retention})`);
 }
 async function handleDbAuditDisable(table, opts) {
     if (!table) {
@@ -147,10 +162,15 @@ async function handleDbAuditDisable(table, opts) {
         dbBranch: opts.env,
     });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)({ status });
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            table: status.table,
+            enabled: status.enabled,
+        }));
         return;
     }
-    (0, output_1.emit)(`✓ Audit disabled for '${status.table}'`);
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    (0, output_1.emit)(`${prefix} Audit disabled for table '${status.table}'`);
 }
 async function handleDbAuditList(tables, opts) {
     if (tables.length === 0) {
@@ -161,7 +181,7 @@ async function handleDbAuditList(tables, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const limit = opts.limit ?? 50;
+    const limit = opts.limit ?? 20;
     // since 优先级：opts.cursor（前一页末条 event_time）> opts.since
     const sinceRaw = opts.cursor ?? opts.since;
     const since = normalizeTime(sinceRaw, "--since/--cursor");
@@ -176,21 +196,29 @@ async function handleDbAuditList(tables, opts) {
         `FROM _dl_audit_log WHERE ${whereParts.join(" AND ")} ORDER BY event_time DESC LIMIT ${String(limit + 1)}`;
     const results = await api.db.execSql({ appId, sql, dbBranch: opts.env });
     const allRows = collectSelectRows(results);
-    // 多取一条用于判断 hasMore；最终只展示 limit 行
     const hasMore = allRows.length > limit;
     const visible = hasMore ? allRows.slice(0, limit) : allRows;
     const nextCursor = hasMore && visible.length > 0 ? asString(visible[visible.length - 1].event_time) : null;
-    // 多表混合时统计哪些表无记录，PRD 要求末尾汇总
+    // 多表混合时统计哪些表无记录
     const seen = new Set();
     for (const r of visible)
         seen.add(asString(r.target_table));
     const skipped = tables.filter((t) => !seen.has(t));
+    // PRD JSON：data 是数组，元素是事件对象（snake_case），分页信封 next_cursor / has_more
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitPaged)(visible, nextCursor, hasMore);
+        const items = visible.map((r) => ({
+            event_id: asString(r.event_id),
+            event_time: asString(r.event_time),
+            target_table: asString(r.target_table),
+            type: asString(r.type),
+            operator: asString(r.operator),
+            summary: asString(r.summary),
+            details: r.details, // 已经是结构化 JSON，透传
+        }));
+        (0, output_1.emitPaged)(items, nextCursor, hasMore);
         if (skipped.length > 0) {
             process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(", ")})\n`);
         }
-        // 退出码：任一表有数据 → 0；全空 → 1（PRD 约定）
         if (visible.length === 0)
             process.exitCode = 1;
         return;
@@ -204,14 +232,23 @@ async function handleDbAuditList(tables, opts) {
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    const headers = ["event_time", "target_table", "type", "operator", "summary"];
-    const rows = visible.map((it) => [
-        (0, render_1.formatTime)(asString(it.event_time), tty),
-        asString(it.target_table),
-        asString(it.type),
-        asString(it.operator, "—"),
-        asString(it.summary),
-    ]);
+    // PRD：多表渲染时第一列是 target_table，单表时去掉这一列
+    const isMultiTable = tables.length > 1;
+    const headers = isMultiTable
+        ? ["target_table", "event_time", "type", "event_id", "operator", "summary"]
+        : ["event_time", "type", "event_id", "operator", "summary"];
+    const rows = visible.map((it) => {
+        const eventTime = (0, render_1.formatTime)(asString(it.event_time), tty);
+        const eventId = truncateId(asString(it.event_id));
+        const cells = [
+            eventTime,
+            asString(it.type),
+            eventId,
+            asString(it.operator, "—"),
+            asString(it.summary),
+        ];
+        return isMultiTable ? [asString(it.target_table), ...cells] : cells;
+    });
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
     if (skipped.length > 0) {
         process.stderr.write(`(${String(skipped.length)} table(s) skipped: ${skipped.join(", ")})\n`);
@@ -224,8 +261,7 @@ async function handleDbAuditList(tables, opts) {
 function normalizeTime(input, flagName) {
     if (input === undefined || input === "")
         return undefined;
-    // ISO 8601 形如 2026-05-07T08:00:00Z 直接透传，避免 parseTimeFilterMs 在
-    // 严格 ISO 上重做一次会损精度
+    // ISO 8601 直接透传，避免 parseTimeFilterMs 在严格 ISO 上重做一次损精度
     if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/.test(input)) {
         return new Date(input).toISOString();
     }
@@ -241,10 +277,40 @@ function collectSelectRows(results) {
     }
     return out;
 }
-/**
- * SQL 字符串字面量转义。仅处理单引号；表名 / 时间戳由调用方控制范围（白名单或
- * 严格 ISO 8601 正则），不在此函数内做。
- */
+// SQL 字面量转义。表名 / 时间戳由调用方控制范围（白名单或严格 ISO 8601 正则）。
 function escapeSqlLiteral(s) {
     return s.replace(/'/g, "''");
 }
+// PRD 输出 enabled 列用 yes/no 而非 true/false
+function boolToYesNo(b) {
+    return b ? "yes" : "no";
+}
+// 后端 ValidDay (int64 天数) → PRD retention 字符串。-1 = 永久（前端 / 后端约定）
+function retentionDaysToString(days) {
+    if (days === -1)
+        return "forever";
+    if (days === 7)
+        return "7d";
+    if (days === 30)
+        return "30d";
+    if (days === 180)
+        return "180d";
+    if (days === 360)
+        return "360d";
+    return `${String(days)}d`;
+}
+function asString(v, fallback = "") {
+    if (v == null)
+        return fallback;
+    if (typeof v === "string")
+        return v;
+    if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint")
+        return String(v);
+    return JSON.stringify(v);
+}
+// audit list 的 event_id 在 TTY 视图里截断展示（PRD 示例 "01525416B44F..."）
+function truncateId(id) {
+    if (id.length <= 12)
+        return id;
+    return id.slice(0, 12) + "...";
+}

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

@@ -39,6 +39,17 @@ const index_1 = require("../../../api/file/index");
 const shared_1 = require("../../../cli/commands/shared");
 const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
+function toRow(it) {
+    return {
+        change_id: it.changeId,
+        changed_at: it.changedAt,
+        operator: it.operator,
+        target_table: it.targetTable,
+        change_type: it.changeType,
+        summary: it.summary,
+        statement: it.statement,
+    };
+}
 /** 把用户传入的 since/until 归一成 ISO 8601 UTC 字符串；空串返 undefined。 */
 function normalizeTime(input, flagName) {
     if (input === undefined || input === "")
@@ -74,12 +85,13 @@ async function handleDbChangelog(opts) {
         cursor = page.nextCursor;
     }
     if ((0, output_1.isJsonMode)()) {
+        const rows = allItems.map(toRow);
         // --all 时已经把所有页合一起返，has_more=false / next_cursor=null
         if (opts.all) {
-            (0, output_1.emitPaged)(allItems, null, false);
+            (0, output_1.emitPaged)((0, output_1.snakeCaseKeys)(rows), null, false);
         }
         else {
-            (0, output_1.emitPaged)(allItems, lastCursor, lastHasMore);
+            (0, output_1.emitPaged)((0, output_1.snakeCaseKeys)(rows), lastCursor, lastHasMore);
         }
         return;
     }
@@ -88,7 +100,8 @@ async function handleDbChangelog(opts) {
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
-    const headers = ["change_id", "changed_at", "operator", "target_table", "type", "summary"];
+    // PRD: change_id / changed_at / operator / target_table / change_type / summary
+    const headers = ["change_id", "changed_at", "operator", "target_table", "change_type", "summary"];
     const rows = allItems.map((it) => [
         it.changeId,
         (0, render_1.formatTime)(it.changedAt, tty),

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

@@ -46,7 +46,7 @@ const output_1 = require("../../../utils/output");
 const render_1 = require("../../../utils/render");
 async function handleDbMigrationInit(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    // PRD：不可逆操作，TTY 默认要求 y/N；--yes 跳过
+    // 不可逆操作，TTY 默认要求 y/N；--yes 跳过
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
         const ok = await confirm(`? Initialize multi-env (single → dev/online), this is IRREVERSIBLE${opts.syncData ? " and will copy existing data to dev" : ""}? (y/N) `);
         if (!ok) {
@@ -56,48 +56,73 @@ async function handleDbMigrationInit(opts) {
     }
     const result = await api.db.migrationInit({ appId, syncData: opts.syncData });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(result);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(result));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
     (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["status", result.status],
-        ["environments", result.environments.join(", ")],
-        ["data_synced", String(result.dataSynced)],
+        ["Status", result.status],
+        ["Environments", result.environments.join(", ")],
+        ["Data synced", String(result.dataSynced)],
     ], tty));
 }
 async function handleDbMigrationDiff(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const result = await api.db.migrate({ appId, dryRun: true });
-    renderMigrate(result);
+    renderDiff(result);
 }
 async function handleDbMigrationApply(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    // 先 diff 一次给用户确认
-    const preview = await api.db.migrate({ appId, dryRun: true });
-    if (preview.changes.length === 0) {
-        if ((0, output_1.isJsonMode)()) {
-            (0, output_1.emitOk)({ ...preview, status: "no_pending_changes" });
-        }
-        else {
-            (0, output_1.emit)("No pending changes from dev to online.");
-        }
-        return;
-    }
+    // TTY 下先 diff 给用户审；--yes 直接打到 online
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        renderMigrate(preview);
-        const ok = await confirm(`? Apply ${String(preview.changes.length)} change(s) from ${preview.from} to ${preview.to}? (y/N) `);
+        const preview = await api.db.migrate({ appId, dryRun: true });
+        if (preview.changes.length === 0) {
+            (0, output_1.emit)(`Error: No pending changes between ${preview.from} and ${preview.to}`);
+            (0, output_1.emit)(`  hint: Make schema changes in dev first.`);
+            process.exitCode = 1;
+            return;
+        }
+        renderDiff(preview);
+        const ok = await confirm(`? Apply ${String(preview.changes.length)} change(s) to ${preview.to}? (y/N) `);
         if (!ok) {
             (0, output_1.emit)("Aborted.");
             return;
         }
     }
     const result = await api.db.migrate({ appId, dryRun: false });
-    renderMigrate(result);
+    if ((0, output_1.isJsonMode)()) {
+        // PRD：{"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            status: result.status ?? "applied",
+            from: result.from,
+            to: result.to,
+            changesApplied: result.changesApplied ?? result.changes.length,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    const arrow = tty ? "→" : "->";
+    const applied = result.changesApplied ?? result.changes.length;
+    (0, output_1.emit)(`${prefix} Applied ${result.from} ${arrow} ${result.to} (${String(applied)} changes)`);
 }
-function renderMigrate(result) {
+// ── helpers ──
+// PRD diff 输出：
+//   dev → online (2 changes):
+//
+//     ALTER TABLE users ADD COLUMN avatar_url text;
+//     CREATE INDEX idx_users_avatar ON users(avatar_url);
+function renderDiff(result) {
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(result);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            from: result.from,
+            to: result.to,
+            changes: result.changes.map((c) => ({
+                type: c.type,
+                table: c.table,
+                statement: c.statement,
+            })),
+        }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
@@ -105,17 +130,10 @@ function renderMigrate(result) {
         (0, output_1.emit)(`No pending changes from ${result.from} to ${result.to}.`);
         return;
     }
-    const headers = ["type", "table", "statement"];
-    const rows = result.changes.map((c) => [c.type, c.table, c.statement]);
-    (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
-    if (result.dryRun) {
-        (0, output_1.emit)(`(dry-run: ${String(result.changes.length)} change(s) preview, run \`db migration apply\` to commit)`);
-    }
-    else {
-        (0, output_1.emit)(`✓ Applied ${String(result.changesApplied ?? result.changes.length)} change(s) from ${result.from} to ${result.to}`);
-    }
+    const arrow = tty ? "→" : "->";
+    (0, output_1.emit)(`${result.from} ${arrow} ${result.to} (${String(result.changes.length)} changes):\n\n` +
+        result.changes.map((c) => `  ${c.statement}`).join("\n"));
 }
-// ── confirm ──
 async function confirm(prompt) {
     const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
     return new Promise((resolve) => {

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

@@ -42,19 +42,17 @@ async function handleDbQuota(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const data = await api.db.getDbQuota({ appId, dbBranch: opts.env });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(data);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(data));
         return;
     }
+    // PRD：单行 "Storage: 14.9 MB / 1 GB (1.5%)"；配额未对接时只显示 used
     const tty = (0, render_1.isStdoutTty)();
-    // quota=0 表示后端未对接配额上限，按 PRD 渲染 "—"
-    const used = (0, render_1.formatSize)(data.storageUsedBytes);
-    const total = data.storageQuotaBytes > 0 ? (0, render_1.formatSize)(data.storageQuotaBytes) : "—";
-    const pct = data.storageQuotaBytes > 0 ? `${data.usagePercent.toFixed(1)}%` : "—";
+    const storageLine = data.storageQuotaBytes > 0
+        ? `${(0, render_1.formatSize)(data.storageUsedBytes)} / ${(0, render_1.formatSize)(data.storageQuotaBytes)} (${data.usagePercent.toFixed(1)}%)`
+        : (0, render_1.formatSize)(data.storageUsedBytes);
     (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["used", used],
-        ["quota", total],
-        ["usage", pct],
-        ["tables", String(data.tables)],
-        ["views", String(data.views)],
+        ["Storage", storageLine],
+        ["Tables", String(data.tables)],
+        ["Views", String(data.views)],
     ], tty));
 }

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

@@ -49,23 +49,36 @@ async function handleDbRecoveryDiff(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
     const result = await api.db.recover({ appId, target: ts, dryRun: true });
-    renderRecover(result);
+    renderDiff(result);
 }
 async function handleDbRecoveryApply(target, opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const ts = normalizeTimestamp(target);
-    // PITR 高危：apply 之前先强制 diff 给用户审；--yes 才能跳过
-    const preview = await api.db.recover({ appId, target: ts, dryRun: true });
+    // PITR 高危：TTY 下先 diff 给用户审；--yes 直接执行
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        renderRecover(preview);
-        const ok = await confirm(`? Restore ${String(preview.tablesAffected)} table(s) to ${preview.target}? This is IRREVERSIBLE. (y/N) `);
+        const preview = await api.db.recover({ appId, target: ts, dryRun: true });
+        renderDiff(preview);
+        const ok = await confirm(`? Restore database to ${preview.target}? This will overwrite current data. (y/N) `);
         if (!ok) {
             (0, output_1.emit)("Aborted.");
             return;
         }
     }
     const result = await api.db.recover({ appId, target: ts, dryRun: false });
-    renderRecover(result);
+    if ((0, output_1.isJsonMode)()) {
+        // PRD：{"status": "restored", "target": "...", "tables_affected": 2, "elapsed_seconds": 30}
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            status: result.status ?? "restored",
+            target: result.target,
+            tablesAffected: result.tablesAffected,
+            elapsedSeconds: result.elapsedSeconds ?? 0,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const prefix = tty ? "✓" : "OK";
+    (0, output_1.emit)(`${prefix} Database restored to ${result.target} ` +
+        `(${String(result.tablesAffected)} tables affected, ${String(result.elapsedSeconds ?? 0)}s elapsed)`);
 }
 // ── helpers ──
 /**
@@ -79,56 +92,90 @@ function normalizeTimestamp(input) {
             next_actions: ["Usage: miaoda db recovery diff|apply <timestamp>"],
         });
     }
-    // YYYY-MM-DD：按 UTC 00:00:00
     if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
         return new Date(`${input}T00:00:00Z`).toISOString();
     }
-    // YYYY-MM-DD HH:MM[:SS]：本地时间，让 Date 自己解析
     if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}(:\d{2})?$/.test(input)) {
         const d = new Date(input.replace(" ", "T"));
         if (Number.isNaN(d.getTime())) {
-            throw new error_1.AppError("INVALID_TIMESTAMP", `invalid timestamp: ${input}`, {
+            throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
                 next_actions: [FORMAT_HINT],
             });
         }
         return d.toISOString();
     }
-    // 完整 ISO 8601
     const d = new Date(input);
     if (Number.isNaN(d.getTime())) {
-        throw new error_1.AppError("INVALID_TIMESTAMP", `invalid timestamp: ${input}`, {
+        throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
             next_actions: [FORMAT_HINT],
         });
     }
     return d.toISOString();
 }
-function renderRecover(result) {
+// PRD diff 输出（结构化 prose）：
+//   Recovery preview (→ 2026-04-15T10:00:00Z):
+//
+//     tables affected: 2
+//     users:   +3 rows, -1 row, ~5 rows modified
+//     orders:  table will be restored (was dropped at 10:25:00)
+//
+//     estimated time: ~30s
+function renderDiff(result) {
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(result);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            target: result.target,
+            tablesAffected: result.tablesAffected,
+            changes: result.changes.map((c) => ({
+                table: c.table,
+                inserted: c.inserted,
+                deleted: c.deleted,
+                modified: c.modified,
+                action: c.action,
+                droppedAt: c.droppedAt,
+            })),
+            estimatedSeconds: result.estimatedSeconds ?? 0,
+        }));
         return;
     }
     const tty = (0, render_1.isStdoutTty)();
+    const arrow = tty ? "→" : "->";
     if (result.changes.length === 0) {
-        (0, output_1.emit)(`No tables affected at ${result.target}.`);
+        (0, output_1.emit)(`Recovery preview (${arrow} ${result.target}):\n\n` +
+            `  No changes — database is already at this state.`);
         return;
     }
-    const headers = ["table", "action", "inserted", "deleted", "modified", "dropped_at"];
-    const rows = result.changes.map((c) => [
-        c.table,
-        c.action ?? "—",
-        c.inserted !== undefined ? String(c.inserted) : "—",
-        c.deleted !== undefined ? String(c.deleted) : "—",
-        c.modified !== undefined ? String(c.modified) : "—",
-        c.droppedAt ?? "—",
-    ]);
-    (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
-    if (result.dryRun) {
-        const eta = result.estimatedSeconds !== undefined ? `, eta ~${String(result.estimatedSeconds)}s` : "";
-        (0, output_1.emit)(`(dry-run: ${String(result.tablesAffected)} table(s) affected${eta}; run \`db recovery apply\` to commit)`);
+    const lines = [
+        `Recovery preview (${arrow} ${result.target}):`,
+        "",
+        `  tables affected: ${String(result.tablesAffected)}`,
+    ];
+    for (const c of result.changes) {
+        lines.push(`  ${c.table}:  ${describeChange(c)}`);
+    }
+    if (result.estimatedSeconds !== undefined) {
+        lines.push("");
+        lines.push(`  estimated time: ~${String(result.estimatedSeconds)}s`);
+    }
+    (0, output_1.emit)(lines.join("\n"));
+}
+function describeChange(c) {
+    if (c.action === "restore_table" || c.action === "drop" || c.action === "create") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        if (c.action === "restore_table")
+            return `table will be restored${ts}`;
+        if (c.action === "drop")
+            return `table will be dropped${ts}`;
+        return `table will be created${ts}`;
     }
-    else {
-        (0, output_1.emit)(`✓ Restored ${String(result.tablesAffected)} table(s) to ${result.target} in ${String(result.elapsedSeconds ?? 0)}s`);
+    const parts = [];
+    if (c.inserted !== undefined && c.inserted !== 0)
+        parts.push(`+${String(c.inserted)} rows`);
+    if (c.deleted !== undefined && c.deleted !== 0) {
+        parts.push(`-${String(c.deleted)} ${c.deleted === 1 ? "row" : "rows"}`);
     }
+    if (c.modified !== undefined && c.modified !== 0)
+        parts.push(`~${String(c.modified)} rows modified`);
+    return parts.length === 0 ? "no changes" : parts.join(", ");
 }
 async function confirm(prompt) {
     const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });

package/dist/cli/handlers/file/quota.js

@@ -42,17 +42,16 @@ async function handleFileQuota(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
     const data = await api.file.getStorageQuota({ appId });
     if ((0, output_1.isJsonMode)()) {
-        (0, output_1.emitOk)(data);
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(data));
         return;
     }
+    // PRD：单行 "Storage: 150 MB / 1 GB (15%)"；配额未对接时只显示 used
     const tty = (0, render_1.isStdoutTty)();
-    const used = (0, render_1.formatSize)(data.storageUsedBytes);
-    const total = data.storageQuotaBytes > 0 ? (0, render_1.formatSize)(data.storageQuotaBytes) : "—";
-    const pct = data.storageQuotaBytes > 0 ? `${data.usagePercent.toFixed(1)}%` : "—";
+    const storageLine = data.storageQuotaBytes > 0
+        ? `${(0, render_1.formatSize)(data.storageUsedBytes)} / ${(0, render_1.formatSize)(data.storageQuotaBytes)} (${data.usagePercent.toFixed(1)}%)`
+        : (0, render_1.formatSize)(data.storageUsedBytes);
     (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["used", used],
-        ["quota", total],
-        ["usage", pct],
-        ["files", String(data.files)],
+        ["Storage", storageLine],
+        ["Files", String(data.files)],
     ], tty));
 }

package/dist/utils/output.js

@@ -5,6 +5,7 @@ exports.emit = emit;
 exports.emitError = emitError;
 exports.emitOk = emitOk;
 exports.emitPaged = emitPaged;
+exports.snakeCaseKeys = snakeCaseKeys;
 const config_1 = require("./config");
 const error_1 = require("./error");
 const colors_1 = require("./colors");
@@ -118,6 +119,27 @@ function emitOk(data) {
 function emitPaged(items, nextCursor, hasMore) {
     emit({ data: items, next_cursor: nextCursor, has_more: hasMore });
 }
+/**
+ * 把对象 / 数组里所有字符串 key 从 camelCase 转成 snake_case，递归处理嵌套对象。
+ * 后端 IDL 返回的 JSON 字段是 camelCase（`storageUsedBytes`），CLI 对外（PRD）
+ * 统一 snake_case（`storage_used_bytes`）；emit JSON 前过一遍这个函数。
+ */
+function snakeCaseKeys(input) {
+    if (Array.isArray(input)) {
+        return input.map((item) => snakeCaseKeys(item));
+    }
+    if (input !== null && typeof input === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(input)) {
+            out[camelToSnake(k)] = snakeCaseKeys(v);
+        }
+        return out;
+    }
+    return input;
+}
+function camelToSnake(s) {
+    return s.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
+}
 function toErrorInfo(err) {
     if (err instanceof error_1.AppError)
         return err.toJSON();

package/package.json

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