@lark-apaas/miaoda-cli 0.1.2-alpha.87ead47 → 0.1.2-alpha.8f744c0

package/dist/api/db/api.js

@@ -33,6 +33,22 @@ async function mapDbHttpError(err, url, ctx,
 onErrorBody) {
     if (err instanceof error_1.AppError)
         throw err;
+    // 客户端超时 / abort：SdkHttpError 时 response 通常缺失（status=0），落到 throw 时
+    // message 形如 'Failed to recover: 0' 让用户看不懂。识别 abort / timeout 关键字
+    // 转成专用错误码 + 友好 hint。
+    if (err instanceof Error) {
+        const msg = err.message.toLowerCase();
+        if (msg.includes("aborted") ||
+            msg.includes("timeout") ||
+            err.name === "AbortError" ||
+            err.name === "TimeoutError") {
+            throw new error_1.AppError("REQUEST_TIMEOUT", `${ctx}: request timed out`, {
+                next_actions: [
+                    "Server-side async tasks may take up to 60s. Retry the command if the underlying task likely succeeded.",
+                ],
+            });
+        }
+    }
     if (err instanceof http_client_1.HttpError) {
         const status = err.response?.status ?? 0;
         const statusText = err.response?.statusText ?? "";

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

@@ -112,13 +112,27 @@ async function handleDbAuditEnable(table, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const status = await api.db.setAuditConfig({
-        appId,
-        table,
-        enabled: true,
-        retention,
-        dbBranch: opts.env,
-    });
+    let status;
+    try {
+        status = await api.db.setAuditConfig({
+            appId,
+            table,
+            enabled: true,
+            retention,
+            dbBranch: opts.env,
+        });
+    }
+    catch (err) {
+        // PRD: 重复 enable 报错时附带 hint，引导用户去 status 看 retention 或换值更新
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300030") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: [
+                    `Use \`miaoda db audit status ${table}\` to check current retention, or run this command with a different --retention to update.`,
+                ],
+            });
+        }
+        throw err;
+    }
     // PRD JSON：{"data": {"table": "...", "enabled": true, "retention": "..."}}
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -141,12 +155,24 @@ async function handleDbAuditDisable(table, opts) {
         });
     }
     const appId = (0, shared_1.resolveAppId)(opts);
-    const status = await api.db.setAuditConfig({
-        appId,
-        table,
-        enabled: false,
-        dbBranch: opts.env,
-    });
+    let status;
+    try {
+        status = await api.db.setAuditConfig({
+            appId,
+            table,
+            enabled: false,
+            dbBranch: opts.env,
+        });
+    }
+    catch (err) {
+        // PRD: 重复 disable / 未启用就 disable 报错时附带 hint，引导用户去看哪些表已开启
+        if (err instanceof error_1.AppError && err.code === "DB_API_k_dl_1300031") {
+            throw new error_1.AppError(err.code, err.message, {
+                next_actions: ["Use `miaoda db audit status` to see which tables have audit enabled."],
+            });
+        }
+        throw err;
+    }
     if ((0, output_1.isJsonMode)()) {
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
             table: status.table,
@@ -220,8 +246,8 @@ async function handleDbAuditList(tables, opts) {
         : ["event_time", "type", "event_id", "operator", "summary"];
     const rows = visible.map((it) => {
         const eventTime = (0, render_1.formatTime)(it.eventTime, tty);
-        const eventId = truncateId(it.eventId);
-        const cells = [eventTime, it.type, eventId, it.operator || "—", it.summary];
+        // event_id 完整透传——PRD 截图里的 "..." 只是文档省略写法，不是 CLI 行为
+        const cells = [eventTime, it.type, it.eventId, it.operator || "—", it.summary];
         return isMultiTable ? [it.targetTable, ...cells] : cells;
     });
     (0, output_1.emit)(tty ? (0, render_1.renderAlignedTable)(headers, rows) : (0, render_1.renderTsv)(headers, rows));
@@ -257,9 +283,3 @@ function safeParseJson(s) {
 function boolToYesNo(b) {
     return b ? "yes" : "no";
 }
-// 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/migration.js

@@ -42,45 +42,85 @@ 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 error_1 = require("../../../utils/error");
 const output_1 = require("../../../utils/output");
 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)()) {
-        const ok = await confirm(`? Initialize multi-env (single → dev/online), this is IRREVERSIBLE${opts.syncData ? " and will copy existing data to dev" : ""}? (y/N) `);
+        // 文案对齐 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;
         }
     }
-    const result = await api.db.migrationInit({ appId, syncData: opts.syncData });
+    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)();
-    (0, output_1.emit)((0, render_1.renderKeyValue)([
-        ["Status", result.status],
-        ["Environments", result.environments.join(", ")],
-        ["Data synced", String(result.dataSynced)],
-    ], tty));
+    const prefix = tty ? "✓" : "OK";
+    const body = result.dataSynced
+        ? "Multi-env initialized, data synced to dev"
+        : `Multi-env initialized (${result.environments.join(" / ")})`;
+    (0, output_1.emit)(`${prefix} ${body}`);
 }
 async function handleDbMigrationDiff(opts) {
     const appId = (0, shared_1.resolveAppId)(opts);
-    const result = await api.db.migrate({ appId, dryRun: true });
+    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)()) {
-        const preview = await api.db.migrate({ appId, dryRun: true });
+        let preview;
+        try {
+            preview = await api.db.migrate({ appId, dryRun: true });
+        }
+        catch (err) {
+            throw decorateMigrationError(err);
+        }
         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;
+            // 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) `);
@@ -89,7 +129,13 @@ async function handleDbMigrationApply(opts) {
             return;
         }
     }
-    const result = await api.db.migrate({ appId, dryRun: false });
+    let result;
+    try {
+        result = await api.db.migrate({ appId, dryRun: false });
+    }
+    catch (err) {
+        throw decorateMigrationError(err);
+    }
     if ((0, output_1.isJsonMode)()) {
         // PRD：{"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -134,6 +180,28 @@ function renderDiff(result) {
     (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) => {

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

@@ -48,7 +48,13 @@ const render_1 = require("../../../utils/render");
 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 });
+    let result;
+    try {
+        result = await api.db.recover({ appId, target: ts, dryRun: true });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
     renderDiff(result);
 }
 async function handleDbRecoveryApply(target, opts) {
@@ -56,7 +62,13 @@ async function handleDbRecoveryApply(target, opts) {
     const ts = normalizeTimestamp(target);
     // PITR 高危：TTY 下先 diff 给用户审；--yes 直接执行
     if (!opts.yes && !(0, output_1.isJsonMode)()) {
-        const preview = await api.db.recover({ appId, target: ts, dryRun: true });
+        let preview;
+        try {
+            preview = await api.db.recover({ appId, target: ts, dryRun: true });
+        }
+        catch (err) {
+            throw decorateRecoveryError(err);
+        }
         renderDiff(preview);
         const ok = await confirm(`? Restore database to ${preview.target}? This will overwrite current data. (y/N) `);
         if (!ok) {
@@ -64,7 +76,13 @@ async function handleDbRecoveryApply(target, opts) {
             return;
         }
     }
-    const result = await api.db.recover({ appId, target: ts, dryRun: false });
+    let result;
+    try {
+        result = await api.db.recover({ appId, target: ts, dryRun: false });
+    }
+    catch (err) {
+        throw decorateRecoveryError(err);
+    }
     if ((0, output_1.isJsonMode)()) {
         // PRD：{"status": "restored", "target": "...", "tables_affected": 2, "elapsed_seconds": 30}
         (0, output_1.emitOk)((0, output_1.snakeCaseKeys)({
@@ -82,21 +100,25 @@ async function handleDbRecoveryApply(target, opts) {
 }
 // ── helpers ──
 /**
- * 把用户传入的时间统一成 ISO 8601 UTC。
- * 接受：`YYYY-MM-DD` / `YYYY-MM-DD HH:MM:SS` / 完整 ISO 8601。
+ * 把用户传入的时间统一成 ISO 8601 UTC。PRD 只接受两种格式：
+ *   - `YYYY-MM-DD`（按 UTC 0 点解释）
+ *   - 完整 ISO 8601 `YYYY-MM-DDTHH:MM:SS[Z|±HH:MM]`
+ *
+ * 严格 regex 匹配 + 不用 new Date(input) 兜底——Node Date 解析 `2026/04/15` 这种
+ * 非 ISO 字符串居然成功（落到本地时区），绕过格式校验把脏值送到后端，导致用户拿到
+ * 「窗口超限」错误而不是「格式错误」。PRD 明确这两种格式以外的都应该报 INVALID_TIMESTAMP。
  */
 function normalizeTimestamp(input) {
-    const FORMAT_HINT = "Use ISO 8601 / yyyy-mm-dd / yyyy-mm-dd HH:MM:SS.";
+    // PRD hint 文案对齐 PRD 截图（同时是 dataloom 端 ErrInvalidTimestamp 的 hint）
+    const FORMAT_HINT = "Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z";
     if (input === "") {
         throw new error_1.AppError("ARGS_INVALID", "target timestamp is required", {
             next_actions: ["Usage: miaoda db recovery diff|apply <timestamp>"],
         });
     }
+    // 仅日期：YYYY-MM-DD → 按 UTC 0 点
     if (/^\d{4}-\d{2}-\d{2}$/.test(input)) {
-        return new Date(`${input}T00:00:00Z`).toISOString();
-    }
-    if (/^\d{4}-\d{2}-\d{2} \d{2}:\d{2}(:\d{2})?$/.test(input)) {
-        const d = new Date(input.replace(" ", "T"));
+        const d = new Date(`${input}T00:00:00Z`);
         if (Number.isNaN(d.getTime())) {
             throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
                 next_actions: [FORMAT_HINT],
@@ -104,13 +126,20 @@ function normalizeTimestamp(input) {
         }
         return d.toISOString();
     }
-    const d = new Date(input);
-    if (Number.isNaN(d.getTime())) {
-        throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
-            next_actions: [FORMAT_HINT],
-        });
+    // 完整 ISO 8601 datetime：T 分隔，秒可选 ms，Z 或 ±HH:MM 时区
+    if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})$/.test(input)) {
+        const d = new Date(input);
+        if (Number.isNaN(d.getTime())) {
+            throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
+                next_actions: [FORMAT_HINT],
+            });
+        }
+        return d.toISOString();
     }
-    return d.toISOString();
+    // 其它一律按格式错误拒绝（`2026/04/15` / `2026.04.15` / `2026年4月15日` 等都走这里）
+    throw new error_1.AppError("INVALID_TIMESTAMP", `Invalid timestamp format '${input}'`, {
+        next_actions: [FORMAT_HINT],
+    });
 }
 // PRD diff 输出（结构化 prose）：
 //   Recovery preview (→ 2026-04-15T10:00:00Z):
@@ -177,6 +206,28 @@ function describeChange(c) {
         parts.push(`~${String(c.modified)} rows modified`);
     return parts.length === 0 ? "no changes" : parts.join(", ");
 }
+// 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":
+            // 窗口超限：引导用户检查 last migration apply 时间
+            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.",
+                ],
+            });
+        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) => {

package/dist/utils/http.js

@@ -42,7 +42,11 @@ function setRuntimeHttpClient(custom) {
 }
 function createClient(opts) {
     const config = {
-        timeout: 30_000,
+        // 90s = dataloom admin-inner 异步轮询 asyncPollTimeout(60s) + 网络/解析 buffer(30s)。
+        // migration apply / recovery diff 等长轮询命令的服务端最长等 60s，CLI 超时短于
+        // 服务端会让请求被客户端 abort（'Failed to recover: 0' / 'Request aborted'），
+        // 用户拿不到真实结果。普通命令 1-2s 就返，30→90s 全局上限对短查询无可感知影响。
+        timeout: 90_000,
         platform: {
             enabled: true,
             adminInnerApi: opts.adminInnerApi,

package/package.json

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