@lark-apaas/miaoda-cli 0.1.2 → 0.1.3-alpha.40be425

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

@@ -0,0 +1,235 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDbMigrationInit = handleDbMigrationInit;
+exports.handleDbMigrationDiff = handleDbMigrationDiff;
+exports.handleDbMigrationApply = handleDbMigrationApply;
+const node_readline_1 = __importDefault(require("node:readline"));
+const api = __importStar(require("../../../api/index"));
+const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const poll_1 = require("../../../utils/poll");
+const render_1 = require("../../../utils/render");
+async function handleDbMigrationInit(opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    // 不可逆操作，TTY 默认要求 y/N；--yes 跳过
+    if (!opts.yes && !(0, output_1.isJsonMode)()) {
+        // 文案对齐 PRD：先讲不可逆，再问是否初始化；syncData 时追加一句而不是塞进同一句话
+        const suffix = opts.syncData ? " (existing data will be copied to dev)" : "";
+        const ok = await confirm(`? This action is irreversible. Initialize multi-env (dev / online)${suffix}? (y/N) `);
+        if (!ok) {
+            (0, output_1.emit)("Aborted.");
+            return;
+        }
+    }
+    let result;
+    try {
+        result = await api.db.migrationInit({ appId, syncData: opts.syncData });
+    }
+    catch (err) {
+        // PRD: 重复 init 报错带 hint，引导用户去 diff 看待发布变更
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300034") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: ["Run `miaoda db migration diff` to view pending changes."],
+            });
+        }
+        throw err;
+    }
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(result));
+        return;
+    }
+    // PRD 单行格式（不用 key:value 表格）：
+    //   默认 ✓ / OK：     "Multi-env initialized (dev / online)"
+    //   --sync-data：      "Multi-env initialized, data synced to dev"
+    const tty = (0, render_1.isStdoutTty)();
+    const body = result.dataSynced
+        ? "Multi-env initialized, data synced to dev"
+        : `Multi-env initialized (${result.environments.join(" / ")})`;
+    (0, output_1.emit)(tty ? colors_1.c.success(`✓ ${body}`) : `OK ${body}`);
+}
+async function handleDbMigrationDiff(opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    let result;
+    try {
+        result = await api.db.migrate({ appId, dryRun: true });
+    }
+    catch (err) {
+        throw decorateMigrationError(err);
+    }
+    // PRD: diff 在无待发布变更时报错带 hint，而不是渲染空列表
+    if (result.changes.length === 0) {
+        throw new error_1.AppError("DB_API_k_dl_1300035", `No pending changes between ${result.from} and ${result.to}`, {
+            next_actions: [
+                'Make schema changes in dev first (e.g. `miaoda db sql "ALTER TABLE ..." --env dev`)',
+            ],
+        });
+    }
+    renderDiff(result);
+}
+async function handleDbMigrationApply(opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    // TTY 下先 diff 给用户审；--yes 直接打到 online
+    if (!opts.yes && !(0, output_1.isJsonMode)()) {
+        let preview;
+        try {
+            preview = await api.db.migrate({ appId, dryRun: true });
+        }
+        catch (err) {
+            throw decorateMigrationError(err);
+        }
+        if (preview.changes.length === 0) {
+            // PRD 文案 + hint
+            throw new error_1.AppError("DB_API_k_dl_1300035", `No pending changes between ${preview.from} and ${preview.to}`, {
+                next_actions: [
+                    'Make schema changes in dev first (e.g. `miaoda db sql "ALTER TABLE ..." --env dev`)',
+                ],
+            });
+        }
+        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;
+        }
+    }
+    let result;
+    try {
+        result = await api.db.migrate({ appId, dryRun: false });
+    }
+    catch (err) {
+        throw decorateMigrationError(err);
+    }
+    // dataloom 立即返 taskId（apply 实际是异步流水线）。CLI 自己 poll 直到 success/failed，
+    // 避免单次 HTTP 长连接 30s+ 被网关 / SDK 中断。
+    if (result.taskId === undefined || result.taskId === "") {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "migration apply did not return taskId");
+    }
+    const taskId = result.taskId;
+    const final = await (0, poll_1.pollUntilDone)({
+        label: "migration apply",
+        intervalMs: 1000,
+        fetch: () => api.db.getMigrationStatus({ appId, taskId }),
+        isDone: (cur) => {
+            // 同 recovery preview，dataloom 上下游枚举大小写不完全统一，客户端归一兜底。
+            const status = cur.status.toLowerCase();
+            if (status === "success")
+                return { done: true, value: cur };
+            if (status === "failed") {
+                throw new error_1.AppError("DB_API_k_dl_1300030", cur.errorMessage ?? `migration apply failed (taskId=${taskId})`);
+            }
+            return { done: false };
+        },
+    });
+    const appliedCount = final.changesApplied ?? result.changes.length;
+    if ((0, output_1.isJsonMode)()) {
+        // PRD：{"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            status: "applied",
+            from: result.from,
+            to: result.to,
+            changesApplied: appliedCount,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const arrow = tty ? "→" : "->";
+    const body = `Applied ${result.from} ${arrow} ${result.to} (${String(appliedCount)} changes)`;
+    (0, output_1.emit)(tty ? colors_1.c.success(`✓ ${body}`) : `OK ${body}`);
+}
+// ── 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)((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)();
+    if (result.changes.length === 0) {
+        (0, output_1.emit)(`No pending changes from ${result.from} to ${result.to}.`);
+        return;
+    }
+    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"));
+}
+// decorateMigrationError 给 migration / recovery 路径上的几个错误码补 PRD 规定的 hint。
+// dataloom 后端只返 message + code，hint 由 CLI 端按错误码映射；其它错误码原样透传。
+function decorateMigrationError(err) {
+    if (!(err instanceof error_1.AppError))
+        return err;
+    switch (err.code) {
+        case "DB_API_k_dl_1300039":
+            // 多环境未初始化：引导先 init
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: ["Run `miaoda db migration init` to set up multi-env first."],
+            });
+        case "DB_API_k_dl_1300035":
+            // 无待发布变更：引导先在 dev 改 schema
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: [
+                    'Make schema changes in dev first (e.g. `miaoda db sql "ALTER TABLE ..." --env dev`)',
+                ],
+            });
+        default:
+            return err;
+    }
+}
+async function confirm(prompt) {
+    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === "y");
+        });
+    });
+}

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

@@ -0,0 +1,68 @@
+"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.handleDbQuota = handleDbQuota;
+const api = __importStar(require("../../../api/index"));
+const shared_1 = require("../../../cli/commands/shared");
+const output_1 = require("../../../utils/output");
+const render_1 = require("../../../utils/render");
+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)()) {
+        // 配额未对接（storageQuotaBytes=0）时，quota / usage_percent 字段都不输出
+        const out = {
+            storageUsedBytes: data.storageUsedBytes,
+            tables: data.tables,
+            views: data.views,
+        };
+        if (data.storageQuotaBytes > 0) {
+            out.storageQuotaBytes = data.storageQuotaBytes;
+            out.usagePercent = data.usagePercent;
+        }
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)(out));
+        return;
+    }
+    // PRD：单行 "Storage: 14.9 MB / 1 GB (1.5%)"；配额未对接时只显示 used
+    const tty = (0, render_1.isStdoutTty)();
+    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)([
+        ["Storage", storageLine],
+        ["Tables", String(data.tables)],
+        ["Views", String(data.views)],
+    ], tty));
+}

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

@@ -0,0 +1,357 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleDbRecoveryDiff = handleDbRecoveryDiff;
+exports.handleDbRecoveryApply = handleDbRecoveryApply;
+const node_readline_1 = __importDefault(require("node:readline"));
+const api = __importStar(require("../../../api/index"));
+const shared_1 = require("../../../cli/commands/shared");
+const colors_1 = require("../../../utils/colors");
+const error_1 = require("../../../utils/error");
+const output_1 = require("../../../utils/output");
+const poll_1 = require("../../../utils/poll");
+const render_1 = require("../../../utils/render");
+const time_1 = require("../../../utils/time");
+// ── recovery diff ──
+//
+// PITR preview 是异步任务：dataloom 立即返 previewRequestId，CLI 自己 poll 直到 success/failed。
+// 失败时 dataloom 已用 translateRestoreErr 把中文窗口错误翻成 PRD 英文 + k_dl_1300036 code，
+// CLI 走 decorateRecoveryError 补 hint。
+async function handleDbRecoveryDiff(target, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const ts = normalizeTimestamp(target);
+    const preview = await runRecoveryPreview(appId, ts);
+    renderDiff(ts, preview);
+}
+async function handleDbRecoveryApply(target, opts) {
+    const appId = (0, shared_1.resolveAppId)(opts);
+    const ts = normalizeTimestamp(target);
+    // PRD 要求 apply 输出包含 N tables affected / Ms elapsed，dataloom apply 路径不
+    // 回带这俩信息（pgsvc.BranchRestore 是异步触发、不等终态）。所以 CLI 这里始终
+    // 先跑一次 preview——它本来就是 PITR 推荐流程，--yes 时静默跑、TTY 时同时给用户审。
+    const preview = await runRecoveryPreview(appId, ts);
+    const tablesAffected = preview.tablesAffected ?? preview.changes?.length ?? 0;
+    // dataloom 端 apply 是异步触发，elapsed_seconds 返 0。这里改用 preview 给出的
+    // estimated_seconds 当 "预计耗时"，更贴近 PRD 示例的 30s elapsed 含义；
+    // 都没填时按 PRD 默认值 30 兜底。
+    const elapsedFromPreview = preview.estimatedSeconds ?? 30;
+    if (!opts.yes && !(0, output_1.isJsonMode)()) {
+        renderDiff(ts, preview);
+        const ok = await confirm(`? Restore database to ${ts}? This will overwrite current data. (y/N) `);
+        if (!ok) {
+            (0, output_1.emit)("Aborted.");
+            return;
+        }
+    }
+    let result;
+    try {
+        result = await api.db.recover({ appId, target: ts, dryRun: false });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
+    const elapsed = result.elapsedSeconds && result.elapsedSeconds > 0 ? result.elapsedSeconds : elapsedFromPreview;
+    if ((0, output_1.isJsonMode)()) {
+        // PRD：{"status": "restored", "target": "...", "tables_affected": N, "elapsed_seconds": M}
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            status: "restored",
+            target: result.target,
+            tablesAffected,
+            elapsedSeconds: elapsed,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    const body = `Database restored to ${result.target} ` +
+        `(${String(tablesAffected)} tables affected, ${String(elapsed)}s elapsed)`;
+    (0, output_1.emit)(tty ? colors_1.c.success(`✓ ${body}`) : `OK ${body}`);
+}
+/**
+ * 触发 PITR 预览任务并轮询到终态：
+ *   1. POST /db/recovery dryRun=true → previewRequestId
+ *   2. GET /db/recovery/preview?previewRequestId 直到 previewStatus=success/failed
+ *
+ * 错误透传：业务错误（窗口超限 / 格式错）由 dataloom 直接 throw，CLI 在 catch 里
+ * 补 hint。failed 状态下 dataloom 已把 errorMessage 翻好，CLI 包成 k_dl_1300036
+ * 让 decorateRecoveryError 命中窗口超限 hint。
+ */
+async function runRecoveryPreview(appId, ts) {
+    let triggered;
+    try {
+        triggered = await api.db.recover({ appId, target: ts, dryRun: true });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
+    if (triggered.previewRequestId === undefined || triggered.previewRequestId === "") {
+        throw new error_1.AppError("INTERNAL_DB_ERROR", "recovery diff did not return previewRequestId");
+    }
+    const previewRequestId = triggered.previewRequestId;
+    try {
+        return await (0, poll_1.pollUntilDone)({
+            label: "recovery preview",
+            intervalMs: 1000,
+            fetch: () => api.db.getRecoveryPreview({ appId, previewRequestId }),
+            isDone: (cur) => {
+                // dataloom 内部 pgsvc 返回首字母大写枚举（Pending/Running/Success/Failed），
+                // 但 admin-inner thrift 契约里写的是小写。客户端做大小写归一兜底，避免依赖
+                // 上游 case 一致性导致死循环。
+                const status = cur.previewStatus.toLowerCase();
+                if (status === "success")
+                    return { done: true, value: cur };
+                if (status === "failed") {
+                    // 复用 k_dl_1300036（窗口超限 / 预览失败的统一对外码），让 decorateRecoveryError
+                    // 命中后给 PITR 7 天窗口的 hint。errorMessage 优先用 dataloom 翻好的 PRD 文案。
+                    throw new error_1.AppError("DB_API_k_dl_1300036", cur.errorMessage ?? "recovery preview failed");
+                }
+                return { done: false };
+            },
+        });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
+}
+// ── helpers ──
+/**
+ * 把用户传入的时间统一成 ISO 8601 UTC 字符串发给 dataloom。
+ *
+ * 复用 utils/time.ts::parseTimeToMs（跟 file ls / db changelog / db audit list 同一套
+ * 解析器），支持四种形态：
+ *   - 相对时间：30s / 5m / 2h / 3d / 1w（从 now 往前推）
+ *   - 仅日期：  2026-04-15           → 本地时区当日 00:00:00
+ *   - 本地 datetime: 2026-04-15T10:00:00 → 本地时区
+ *   - ISO 8601 with TZ: 2026-04-15T10:00:00Z 或 2026-04-15T10:00:00+08:00
+ *
+ * 不接受松散 / 区域性格式（YYYY/MM/DD、'April 1 2026' 等）——parseTimeToMs 内部
+ * 用严格 regex 把这些拒掉，避免之前用 new Date(input) 兜底把脏值送到后端的坑。
+ */
+function normalizeTimestamp(input) {
+    if (input === "") {
+        throw new error_1.AppError("ARGS_INVALID", "target timestamp is required", {
+            next_actions: ["Usage: miaoda db recovery diff|apply <timestamp>"],
+        });
+    }
+    return new Date((0, time_1.parseTimeToMs)(input)).toISOString();
+}
+// PRD diff 输出，三套：
+//
+// TTY pretty（缩进 prose、带 Unicode 箭头 / 波浪号、表名按列对齐）：
+//   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
+//
+// non-TTY pretty（管道友好，扁平 TSV、ASCII 箭头、snake_case key、estimated_time 不带 ~/s）：
+//   Recovery preview (-> 2026-04-15T10:00:00Z):
+//   tables_affected\t2
+//   users\t+3 rows, -1 row, ~5 rows modified
+//   orders\ttable will be restored (was dropped at 10:25:00)
+//   estimated_time\t30
+//
+// --json：标准 envelope，字段名固定 snake_case。
+function renderDiff(target, preview) {
+    const changes = preview.changes ?? [];
+    const tablesAffected = preview.tablesAffected ?? changes.length;
+    const estimated = preview.estimatedSeconds;
+    if ((0, output_1.isJsonMode)()) {
+        (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
+            target,
+            tablesAffected,
+            changes: changes.map((c) => ({
+                table: c.table,
+                inserted: c.inserted,
+                deleted: c.deleted,
+                modified: c.modified,
+                action: c.action,
+                droppedAt: c.droppedAt,
+            })),
+            estimatedSeconds: estimated ?? 30,
+        }));
+        return;
+    }
+    const tty = (0, render_1.isStdoutTty)();
+    if (tty) {
+        (0, output_1.emit)(renderDiffTty(target, changes, tablesAffected, estimated));
+        return;
+    }
+    (0, output_1.emit)(renderDiffPipe(target, changes, tablesAffected, estimated));
+}
+function renderDiffTty(target, changes, tablesAffected, estimated) {
+    const header = `Recovery preview (→ ${target}):`;
+    if (changes.length === 0) {
+        return `${header}\n\n  No changes — database is already at this state.`;
+    }
+    // 对齐：所有表名右侧补到 max(len) + 1 个 ":" + 1 个空格再起描述。PRD 用例里
+    // "users:   " / "orders:  " 三/二空格其实就是按 6 个 char 列宽对齐出来的。
+    const maxName = Math.max(...changes.map((c) => c.table.length));
+    const lines = [header, "", `  tables affected: ${String(tablesAffected)}`];
+    for (const c of changes) {
+        const pad = " ".repeat(Math.max(1, maxName - c.table.length + 2));
+        lines.push(`  ${c.table}:${pad}${describeChange(c)}`);
+    }
+    // PRD 要求 estimated time 块固定出现（即便 dataloom 当前没填 EstimatedSeconds，
+    // CLI 也用 30s 兜底——PRD 示例展示的就是 30s，统一一个不至于误导的常量）。
+    lines.push("");
+    lines.push(`  estimated time: ~${String(estimated ?? 30)}s`);
+    return lines.join("\n");
+}
+function renderDiffPipe(target, changes, tablesAffected, estimated) {
+    // 管道场景：去掉缩进，TAB 分列，箭头降级为 ->，key 用 snake_case，
+    // estimated_time 只输出秒数（不带 ~/s），方便 awk/grep。
+    const header = `Recovery preview (-> ${target}):`;
+    if (changes.length === 0) {
+        return `${header}\nNo changes — database is already at this state.`;
+    }
+    const lines = [header, `tables_affected\t${String(tablesAffected)}`];
+    for (const c of changes) {
+        lines.push(`${c.table}\t${describeChange(c)}`);
+    }
+    // 与 TTY 一致，始终输出 estimated_time（默认 30），让 awk 解析时不用兜底。
+    lines.push(`estimated_time\t${String(estimated ?? 30)}`);
+    return lines.join("\n");
+}
+function describeChange(c) {
+    // 表级操作：dataloom 现在把 schema diff 透出为 action="schema_<diffType>"，
+    // 老协议的 restore_table / drop / create 一并保留兼容。
+    if (c.action === "restore_table") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        return `table will be restored${ts}`;
+    }
+    if (c.action === "drop") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        return `table will be dropped${ts}`;
+    }
+    if (c.action === "create") {
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        return `table will be created${ts}`;
+    }
+    if (c.action?.startsWith("schema_") === true) {
+        // dataloom 透出的 schema diffType 来自 schema_handler/common/constants：
+        //   - create: 当前没这表 / 目标时间点有 → 恢复后表会被建出来（PRD 用 restored 表达）
+        //   - drop:   当前有 / 目标时间点没 → 恢复后会被删掉
+        //   - alter:  两侧都在但结构有差异 → 列 / 索引 / 关系等会被改回
+        const diffType = c.action.slice("schema_".length);
+        const ts = c.droppedAt ? ` (was dropped at ${c.droppedAt})` : "";
+        switch (diffType) {
+            case "create":
+                return `table will be restored${ts}`;
+            case "drop":
+                return `table will be dropped${ts}`;
+            case "alter":
+                return `schema will be altered${ts}`;
+            default:
+                return `schema changed${diffType !== "" ? ` (${diffType})` : ""}${ts}`;
+        }
+    }
+    if (c.action === "unavailable") {
+        // dataloom 端 count 失败的表，复用 droppedAt 透传 message
+        return `diff unavailable${c.droppedAt !== undefined && c.droppedAt !== "" ? `: ${c.droppedAt}` : ""}`;
+    }
+    // 数据变更：+N rows / -N rows / ~N rows modified
+    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(", ");
+}
+/**
+ * 解析 dataloom 嵌在 message 末尾的窗口边界，形如 `[2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z]`。
+ * 命中返 `{start, end}`，否则 null。两侧时间字符串原样透传给 hint，不做归一化。
+ */
+function parseWindowBounds(message) {
+    const m = /\[([^[\]]+?)\s*~\s*([^[\]]+?)\]\s*$/.exec(message);
+    if (!m)
+        return null;
+    const start = m[1].trim();
+    const end = m[2].trim();
+    if (start === "" || end === "")
+        return null;
+    return { start, end };
+}
+// decorateRecoveryError 给 recovery 路径上的几个错误码补 PRD 规定的 hint。
+// dataloom 后端只返 message + code，hint 由 CLI 端按错误码映射；其它错误码原样透传。
+function decorateRecoveryError(err) {
+    if (!(err instanceof error_1.AppError))
+        return err;
+    switch (err.code) {
+        case "DB_API_k_dl_1300036": {
+            // 窗口超限：dataloom 端会把当前窗口边界拼成 `[<startISO> ~ <endISO>]` 嵌到 message
+            // 末尾，CLI 在这里提取出来按 PRD 格式 hint。提取失败时退回通用提示。
+            const bounds = parseWindowBounds(err.message);
+            if (bounds === null) {
+                return new error_1.AppError(err.code, err.message, {
+                    next_actions: [
+                        "PITR window is up to 7 days back, limited by your last `db migration apply` time.",
+                    ],
+                });
+            }
+            // message 里把 [start ~ end] 段移除掉，避免重复
+            const cleanMsg = err.message.replace(/\s*\[[^\]]*\]\s*$/, "");
+            return new error_1.AppError(err.code, cleanMsg, {
+                next_actions: [
+                    `Current recoverable window: ${bounds.start} ~ ${bounds.end}`,
+                    `(limited by last migration apply at ${bounds.start})`,
+                ],
+            });
+        }
+        case "DB_API_k_dl_1300038":
+            // 时间格式错误：引导 ISO 8601
+            return new error_1.AppError(err.code, err.message, {
+                next_actions: ["Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z"],
+            });
+        default:
+            return err;
+    }
+}
+async function confirm(prompt) {
+    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase() === "y");
+        });
+    });
+}

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

@@ -39,12 +39,11 @@ 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 appId = opts.appId;
     const resp = await api.db.getSchema({
         appId,
         format: "schema",
@@ -80,7 +79,7 @@ async function handleDbSchemaList(opts) {
     (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 appId = opts.appId;
     const tty = (0, render_1.isStdoutTty)();
     const forceDdl = Boolean(opts.ddl);
     const wantsStructured = (0, output_1.isJsonMode)() || (tty && !forceDdl);