@lark-apaas/miaoda-cli 0.1.3 → 0.1.4-alpha.abaa17f

package/dist/utils/http.js

@@ -60,42 +60,48 @@ function createClient(opts) {
     instance.interceptors.request.use(applyCanaryHeader);
     return instance;
 }
-/** 若 MIAODA_CANARY_HEADER 已设置，注入 x-tt-env 小流量头 */
+/**
+ * 默认灰度泳道。当前 miaoda CLI 接入的新接口（modern deploy 等）只在该泳道生效，
+ * 缺省走这个。MIAODA_CANARY_HEADER 可显式覆盖；设为空字符串则去掉头。
+ */
+const DEFAULT_CANARY_HEADER = 'boe_miaoda_doubao';
+/** 注入 x-tt-env 小流量头：env 显式设值 > DEFAULT_CANARY_HEADER */
 function applyCanaryHeader(reqConfig) {
-    const canary = process.env.MIAODA_CANARY_HEADER;
+    // env 显式设为空字符串视为"去掉灰度头"；未设置时用 DEFAULT_CANARY_HEADER
+    const canary = process.env.MIAODA_CANARY_HEADER ?? DEFAULT_CANARY_HEADER;
     if (!canary)
         return reqConfig;
     const headers = new Headers(reqConfig.headers);
-    headers.set("x-tt-env", canary);
+    headers.set('x-tt-env', canary);
     reqConfig.headers = headers;
     return reqConfig;
 }
 /** 走管理端 innerapi 的 POST + 信封解析 */
 async function postInnerApi(url, body, opts) {
-    const startMs = logRequestStart("POST", url, body);
+    const startMs = logRequestStart('POST', url, body);
     let response;
     try {
         response = await getHttpClient().post(url, body);
     }
     catch (err) {
-        logResponseFailure("POST", url, err, startMs);
+        logResponseFailure('POST', url, err, startMs);
         throw err;
     }
-    logResponseEnd("POST", url, response, startMs);
+    logResponseEnd('POST', url, response, startMs);
     return handleInnerEnvelope(response, url, opts);
 }
 /** 走管理端 innerapi 的 GET + 信封解析 */
 async function getInnerApi(url, opts) {
-    const startMs = logRequestStart("GET", url);
+    const startMs = logRequestStart('GET', url);
     let response;
     try {
         response = await getHttpClient().get(url);
     }
     catch (err) {
-        logResponseFailure("GET", url, err, startMs);
+        logResponseFailure('GET', url, err, startMs);
         throw err;
     }
-    logResponseEnd("GET", url, response, startMs);
+    logResponseEnd('GET', url, response, startMs);
     return handleInnerEnvelope(response, url, opts);
 }
 async function handleInnerEnvelope(response, url, opts) {
@@ -103,10 +109,10 @@ async function handleInnerEnvelope(response, url, opts) {
         throw new error_1.HttpError(response.status, url, `${opts.errPrefix}: ${String(response.status)} ${response.statusText}`);
     }
     const result = await response.json();
-    if (typeof result === "object" && result !== null && "status_code" in result) {
+    if (typeof result === 'object' && result !== null && 'status_code' in result) {
         const env = result;
-        if (env.status_code !== undefined && env.status_code !== "0") {
-            const msg = env.message ?? env.error_msg ?? "unknown error";
+        if (env.status_code !== undefined && env.status_code !== '0') {
+            const msg = env.message ?? env.error_msg ?? 'unknown error';
             // verbose: 把完整业务错误信封打到 stderr，便于追溯
             if ((0, config_1.getConfig)().verbose) {
                 (0, logger_1.debug)(`  envelope: ${truncateForLog(safeStringify(env), 1000)}`);
@@ -114,7 +120,7 @@ async function handleInnerEnvelope(response, url, opts) {
             const mapped = opts.mapErr?.(env.status_code, msg);
             if (mapped)
                 throw mapped;
-            throw new error_1.AppError(opts.defaultErrCode ?? "INTERNAL_API_ERROR", `${opts.errPrefix}: ${msg}`);
+            throw new error_1.AppError(opts.defaultErrCode ?? 'INTERNAL_API_ERROR', `${opts.errPrefix}: ${msg}`);
         }
         // status_code = "0"：data 存在则解封；否则 envelope 自身就是业务体
         if (env.data)
@@ -142,7 +148,7 @@ function logResponseEnd(method, url, response, startMs) {
         return;
     const elapsedMs = Date.now() - startMs;
     const logid = pickLogid(response.headers);
-    const tail = logid ? ` logid=${logid}` : "";
+    const tail = logid ? ` logid=${logid}` : '';
     (0, logger_1.debug)(`← ${method} ${url} ${String(response.status)} ${String(elapsedMs)}ms${tail}`);
 }
 /**
@@ -158,17 +164,17 @@ function logResponseFailure(method, url, err, startMs) {
     const e = err;
     const status = e.response?.status;
     const logid = e.response?.headers ? pickLogid(e.response.headers) : null;
-    const statusPart = status !== undefined ? String(status) : "ERR";
-    const logidPart = logid ? ` logid=${logid}` : "";
-    const msgPart = e.message ? ` (${e.message})` : "";
+    const statusPart = status !== undefined ? String(status) : 'ERR';
+    const logidPart = logid ? ` logid=${logid}` : '';
+    const msgPart = e.message ? ` (${e.message})` : '';
     (0, logger_1.debug)(`✗ ${method} ${url} ${statusPart} ${String(elapsedMs)}ms${logidPart}${msgPart}`);
 }
 /** BAM gateway 在不同 PSM/版本上 logid 落在不同 header；按命中顺序取第一个非空。 */
 function pickLogid(headers) {
-    return (headers.get("x-tt-logid") ??
-        headers.get("x-logid") ??
-        headers.get("logid") ??
-        headers.get("x-tt-trace-tag"));
+    return (headers.get('x-tt-logid') ??
+        headers.get('x-logid') ??
+        headers.get('logid') ??
+        headers.get('x-tt-trace-tag'));
 }
 function safeStringify(v) {
     try {

package/dist/utils/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
+exports.pollUntilDone = exports.msToSec = exports.msToNs = exports.parseToSec = exports.parseToNs = exports.parseToMs = exports.parseTimeToMs = exports.getInnerApi = exports.postInnerApi = exports.setRuntimeHttpClient = exports.setHttpClient = exports.resetHttpClient = exports.getRuntimeHttpClient = exports.getHttpClient = exports.log = exports.debug = exports.fmt = exports.isJsonMode = exports.emitPaged = exports.emitOk = exports.emitError = exports.emit = exports.getLogId = exports.generateLogId = exports.initConfigFromOpts = exports.resetConfig = exports.setConfig = exports.getConfig = exports.HttpError = exports.AppError = void 0;
 var error_1 = require("./error");
 Object.defineProperty(exports, "AppError", { enumerable: true, get: function () { return error_1.AppError; } });
 Object.defineProperty(exports, "HttpError", { enumerable: true, get: function () { return error_1.HttpError; } });
@@ -37,3 +37,5 @@ Object.defineProperty(exports, "parseToNs", { enumerable: true, get: function ()
 Object.defineProperty(exports, "parseToSec", { enumerable: true, get: function () { return time_1.parseToSec; } });
 Object.defineProperty(exports, "msToNs", { enumerable: true, get: function () { return time_1.msToNs; } });
 Object.defineProperty(exports, "msToSec", { enumerable: true, get: function () { return time_1.msToSec; } });
+var poll_1 = require("./poll");
+Object.defineProperty(exports, "pollUntilDone", { enumerable: true, get: function () { return poll_1.pollUntilDone; } });

package/dist/utils/npm-pack.js

@@ -0,0 +1,55 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchNpmPackage = fetchNpmPackage;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const error_1 = require("./error");
+const logger_1 = require("./logger");
+const DEFAULT_REGISTRY = 'https://registry.npmmirror.com/';
+/**
+ * `npm pack <pkg>@<ver> --registry <r>` + `tar -xzf`，解到临时目录。
+ * extractDir 是包内容根（含 package.json）。使用完必须 cleanup()。
+ */
+function fetchNpmPackage(opts) {
+    const registry = opts.registry ?? process.env.MIAODA_NPM_REGISTRY ?? DEFAULT_REGISTRY;
+    const version = opts.version ?? 'latest';
+    const pkgSpec = `${opts.packageName}@${version}`;
+    const tmpDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'miaoda-pack-'));
+    try {
+        (0, logger_1.debug)(`npm pack ${pkgSpec} --registry ${registry} → ${tmpDir}`);
+        const stdout = (0, node_child_process_1.execFileSync)('npm', ['pack', pkgSpec, '--pack-destination', tmpDir, '--json', '--registry', registry], { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+        const packInfo = JSON.parse(stdout);
+        const tgzFilename = packInfo[0]?.filename;
+        const pkgVersion = packInfo[0]?.version ?? version;
+        if (!tgzFilename) {
+            throw new error_1.AppError('NPM_PACK_FAILED', `npm pack 未返回 filename：${pkgSpec}`);
+        }
+        const tgzPath = node_path_1.default.join(tmpDir, tgzFilename);
+        const extractDir = node_path_1.default.join(tmpDir, 'extracted');
+        node_fs_1.default.mkdirSync(extractDir, { recursive: true });
+        (0, node_child_process_1.execFileSync)('tar', ['-xzf', tgzPath, '-C', extractDir], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return {
+            extractDir: node_path_1.default.join(extractDir, 'package'),
+            version: pkgVersion,
+            cleanup: () => {
+                node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (err) {
+        node_fs_1.default.rmSync(tmpDir, { recursive: true, force: true });
+        if (err instanceof error_1.AppError)
+            throw err;
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new error_1.AppError('NPM_PACK_FAILED', `抓取 npm 包失败 (${pkgSpec}): ${msg}`, {
+            next_actions: [`确认包已发布到 registry：${registry}`, `检查版本号 / dist-tag 拼写`],
+        });
+    }
+}

package/dist/utils/output.js

@@ -6,6 +6,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");
@@ -25,13 +26,13 @@ const SERVER_ERROR_HINTS = {
     // key 用 BIZ_ERR_MAP 映射后的语义 code（不是原始服务端 k_dl_xxx），保持
     // 与 help / 文档里宣传的 RESULT_SET_TOO_LARGE 一致。
     RESULT_SET_TOO_LARGE: [
-        "Add `LIMIT <n>` to your SQL to narrow the result.",
-        "For counts, use `SELECT count(*) FROM ...`; for aggregation, use GROUP BY with filters.",
+        'Add `LIMIT <n>` to your SQL to narrow the result.',
+        'For counts, use `SELECT count(*) FROM ...`; for aggregation, use GROUP BY with filters.',
     ],
 };
 function isJsonMode() {
     const cfg = (0, config_1.getConfig)();
-    return cfg.output === "json" || Boolean(cfg.json);
+    return cfg.output === 'json' || Boolean(cfg.json);
 }
 // ── 默认 cell 格式化 ────────────
 /**
@@ -44,24 +45,24 @@ function isJsonMode() {
  */
 function defaultFormat(v) {
     if (v === null || v === undefined)
-        return "";
-    if (typeof v === "string")
+        return '';
+    if (typeof v === 'string')
         return v;
-    if (typeof v === "boolean" || typeof v === "number" || typeof v === "bigint")
+    if (typeof v === 'boolean' || typeof v === 'number' || typeof v === 'bigint')
         return String(v);
     const s = JSON.stringify(v);
     if (process.stdout.isTTY && s.length > 60)
-        return s.slice(0, 57) + "...";
+        return s.slice(0, 57) + '...';
     return s;
 }
 // ── 时间戳 / 时长 formatter ────────────
 function toMs(v, divisor) {
     let n;
-    if (typeof v === "number")
+    if (typeof v === 'number')
         n = v;
-    else if (typeof v === "bigint")
+    else if (typeof v === 'bigint')
         n = Number(v);
-    else if (typeof v === "string") {
+    else if (typeof v === 'string') {
         n = Number(v);
         if (!Number.isFinite(n))
             return null;
@@ -73,7 +74,7 @@ function toMs(v, divisor) {
     return n / divisor;
 }
 /** renderDate 默认模板：本地时区、人读友好。业务层可在 fmt.{ns,us,ms,sec}() 里覆盖。 */
-const DEFAULT_DATE_TEMPLATE = "yyyy-MM-dd HH:mm:ss";
+const DEFAULT_DATE_TEMPLATE = 'yyyy-MM-dd HH:mm:ss';
 /**
  * 把 Date 渲染成模板字符串；time zone 走运行时 local。
  * 支持的占位符：yyyy / MM / dd / HH / mm / ss / SSS（毫秒）。
@@ -86,14 +87,14 @@ function renderDate(date, template = DEFAULT_DATE_TEMPLATE) {
     // if (diffMs < 3_600_000) return `${String(Math.floor(diffMs / 60_000))}m ago`;
     // if (diffMs < 86_400_000) return `${String(Math.floor(diffMs / 3_600_000))}h ago`;
     // if (diffMs < 7 * 86_400_000) return `${String(Math.floor(diffMs / 86_400_000))}d ago`;
-    const pad2 = (n) => String(n).padStart(2, "0");
+    const pad2 = (n) => String(n).padStart(2, '0');
     const Y = String(date.getFullYear());
     const Mo = pad2(date.getMonth() + 1);
     const D = pad2(date.getDate());
     const H = pad2(date.getHours());
     const Mi = pad2(date.getMinutes());
     const S = pad2(date.getSeconds());
-    const Ms = String(date.getMilliseconds()).padStart(3, "0");
+    const Ms = String(date.getMilliseconds()).padStart(3, '0');
     // 顺序：先把 SSS 这种长 token 处理掉，再处理短 token，避免子串误覆盖
     return template
         .replace(/yyyy/g, Y)
@@ -138,7 +139,7 @@ function makeTruncateFormatter(n) {
         // 仅 TTY 截断，非 TTY 保留完整值（pipe 下游可解析）
         if (!process.stdout.isTTY || s.length <= n)
             return s;
-        return s.slice(0, Math.max(0, n - 3)) + "...";
+        return s.slice(0, Math.max(0, n - 3)) + '...';
     };
 }
 /**
@@ -175,10 +176,10 @@ exports.fmt = {
 // ── 字段选择 (--json field1,field2) ────────────
 function getFieldSelection() {
     const cfg = (0, config_1.getConfig)();
-    if (typeof cfg.json !== "string")
+    if (typeof cfg.json !== 'string')
         return null;
     const fields = cfg.json
-        .split(",")
+        .split(',')
         .map((s) => s.trim())
         .filter(Boolean);
     return fields.length > 0 ? fields : null;
@@ -198,22 +199,22 @@ function pickFields(obj, fields) {
 }
 function applyFieldSelection(data, fields) {
     if (Array.isArray(data)) {
-        return data.map((item) => typeof item === "object" && item !== null && !Array.isArray(item)
+        return data.map((item) => typeof item === 'object' && item !== null && !Array.isArray(item)
             ? pickFields(item, fields)
             : item);
     }
-    if (typeof data === "object" && data !== null) {
+    if (typeof data === 'object' && data !== null) {
         return pickFields(data, fields);
     }
     return data;
 }
 // ── 信封识别 ────────────
-const ENVELOPE_KEYS = new Set(["data", "next_cursor", "has_more"]);
+const ENVELOPE_KEYS = new Set(['data', 'next_cursor', 'has_more']);
 function isEnvelope(v) {
-    if (typeof v !== "object" || v === null)
+    if (typeof v !== 'object' || v === null)
         return false;
     const keys = Object.keys(v);
-    if (!keys.includes("data"))
+    if (!keys.includes('data'))
         return false;
     return keys.every((k) => ENVELOPE_KEYS.has(k));
 }
@@ -234,38 +235,38 @@ function emit(data, schema) {
         payload = { ...payload, data: applyFieldSelection(payload.data, fields) };
     }
     if (isJsonMode()) {
-        process.stdout.write(JSON.stringify(payload) + "\n");
+        process.stdout.write(JSON.stringify(payload) + '\n');
         return;
     }
     if (isEnvelope(payload)) {
         emitPrettyEnvelope(payload, schema);
         return;
     }
-    if (typeof payload === "string") {
-        process.stdout.write(payload + "\n");
+    if (typeof payload === 'string') {
+        process.stdout.write(payload + '\n');
     }
     else {
-        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
     }
 }
 function emitPrettyEnvelope(env, schema) {
     const { data, next_cursor, has_more } = env;
     if (Array.isArray(data)) {
         if (data.length === 0) {
-            process.stdout.write("(no results)\n");
+            process.stdout.write('(no results)\n');
         }
         else {
             writeTable(data, schema);
         }
     }
-    else if (data !== null && typeof data === "object") {
+    else if (data !== null && typeof data === 'object') {
         writeKeyValue(data, schema);
     }
     else if (data === null || data === undefined) {
-        process.stdout.write("(empty)\n");
+        process.stdout.write('(empty)\n');
     }
     else {
-        process.stdout.write(defaultFormat(data) + "\n");
+        process.stdout.write(defaultFormat(data) + '\n');
     }
     if (has_more && next_cursor) {
         const count = Array.isArray(data) ? data.length : 1;
@@ -318,10 +319,10 @@ function resolveColumnsForRows(items, schema) {
     return cols;
 }
 function writeTable(rows, schema) {
-    const items = rows.filter((r) => typeof r === "object" && r !== null && !Array.isArray(r));
+    const items = rows.filter((r) => typeof r === 'object' && r !== null && !Array.isArray(r));
     if (items.length === 0) {
         for (const row of rows)
-            process.stdout.write(defaultFormat(row) + "\n");
+            process.stdout.write(defaultFormat(row) + '\n');
         return;
     }
     const cols = resolveColumnsForRows(items, schema);
@@ -334,14 +335,14 @@ function writeTable(rows, schema) {
         for (const row of matrix) {
             const line = row
                 .map((cell, i) => cell.padEnd(widths[i] ?? 0))
-                .join("  ")
+                .join('  ')
                 .trimEnd();
-            process.stdout.write(line + "\n");
+            process.stdout.write(line + '\n');
         }
     }
     else {
         for (const row of matrix)
-            process.stdout.write(row.join("\t") + "\n");
+            process.stdout.write(row.join('\t') + '\n');
     }
 }
 function resolveColumnsForObject(obj, schema) {
@@ -365,7 +366,7 @@ function resolveColumnsForObject(obj, schema) {
 function writeKeyValue(obj, schema) {
     const cols = resolveColumnsForObject(obj, schema);
     if (cols.length === 0) {
-        process.stdout.write("(empty)\n");
+        process.stdout.write('(empty)\n');
         return;
     }
     if (process.stdout.isTTY) {
@@ -399,34 +400,34 @@ function emitError(err) {
         };
         if (hints.length > 0) {
             // JSON 输出压平成单行，更便于机器消费（脚本 / agent 拼字符串）
-            errObj.hint = hints.join(" ");
+            errObj.hint = hints.join(' ');
         }
-        if (typeof info.statement_index === "number") {
+        if (typeof info.statement_index === 'number') {
             errObj.statement_index = info.statement_index;
         }
         // PRD 多语句失败 envelope 额外字段：completed / rolled_back
         if (Array.isArray(info.completed)) {
             errObj.completed = info.completed;
         }
-        if (typeof info.rolled_back === "boolean") {
+        if (typeof info.rolled_back === 'boolean') {
             errObj.rolled_back = info.rolled_back;
         }
-        process.stderr.write(JSON.stringify({ error: errObj }) + "\n");
+        process.stderr.write(JSON.stringify({ error: errObj }) + '\n');
     }
     else {
         // stderr 染色：picocolors 默认按 stdout.isTTY 判断；stderr 通常也是 tty，
         // 这里复用 stdout 探测保持简单（stderr only-pipe 的极端场景留作后续优化）
         // 多语句失败时 Error 行末尾追加 "(at statement K of N)"，与 PRD spec 对齐
-        let errorLine = `${colors_1.c.fail("Error:")} ${info.message}`;
-        if (typeof info.statement_index === "number") {
+        let errorLine = `${colors_1.c.fail('Error:')} ${info.message}`;
+        if (typeof info.statement_index === 'number') {
             const k = info.statement_index + 1;
             const n = info.total_statements;
             errorLine +=
-                typeof n === "number" && n > 0
+                typeof n === 'number' && n > 0
                     ? ` (at statement ${String(k)} of ${String(n)})`
                     : ` (at statement ${String(k)})`;
         }
-        process.stderr.write(errorLine + "\n");
+        process.stderr.write(errorLine + '\n');
         // 多行 hint：第一行带 "hint:" 标签，后续行用 8 空格缩进对齐 "  hint: " 之后的列。
         // 对应 spec 期望的格式：
         //   Error: ...
@@ -434,7 +435,7 @@ function emitError(err) {
         //           第二条建议
         if (hints.length > 0) {
             const [first, ...rest] = hints;
-            process.stderr.write(`  ${colors_1.c.muted("hint:")} ${first}\n`);
+            process.stderr.write(`  ${colors_1.c.muted('hint:')} ${first}\n`);
             for (const line of rest) {
                 process.stderr.write(`        ${line}\n`);
             }
@@ -449,9 +450,30 @@ 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();
     const message = err instanceof Error ? err.message : String(err);
-    return { code: "UNKNOWN", message, retryable: false, next_actions: [] };
+    return { code: 'UNKNOWN', message, retryable: false, next_actions: [] };
 }

package/dist/utils/poll.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pollUntilDone = pollUntilDone;
+const error_1 = require("../utils/error");
+const spinner_1 = require("../utils/spinner");
+async function pollUntilDone(opts) {
+    const interval = opts.intervalMs ?? 1000;
+    const timeout = opts.timeoutMs ?? 300_000;
+    const deadline = Date.now() + timeout;
+    // 仅当传 spinnerLabel 时启动 spinner；非 TTY / JSON 模式内部自动 noop
+    const stopSpinner = opts.spinnerLabel ? (0, spinner_1.startSpinner)(opts.spinnerLabel) : () => undefined;
+    try {
+        // 立即拉一次（绝大多数轻量任务在 dataloom 端已是同步语义，第一次 fetch 就能拿到 success）
+        for (;;) {
+            const cur = await opts.fetch();
+            const verdict = opts.isDone(cur);
+            if (verdict.done)
+                return verdict.value;
+            if (Date.now() + interval > deadline) {
+                throw new error_1.AppError('TASK_TIMEOUT', `${opts.label} did not complete within ${String(Math.round(timeout / 1000))}s`, {
+                    next_actions: [
+                        'The task may still be running server-side. Retry the command, or check `miaoda db migration diff` to verify final state.',
+                    ],
+                });
+            }
+            await sleep(interval);
+        }
+    }
+    finally {
+        stopSpinner();
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}