@lark-apaas/miaoda-cli 0.1.2 → 0.1.3-alpha.4bf312e

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

@@ -1,7 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerDbCommands = registerDbCommands;
+const error_1 = require("../../../utils/error");
 const index_1 = require("../../../cli/handlers/db/index");
+const shared_1 = require("../../../cli/commands/shared");
+function parsePositiveInt(raw) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1) {
+        throw new error_1.AppError("ARGS_INVALID", `--limit must be a positive integer (got '${raw}')`);
+    }
+    return n;
+}
 function registerDbCommands(program) {
     const dbCmd = program
         .command("db")
@@ -22,7 +31,7 @@ function registerDbCommands(program) {
         .usage("<query> [flags]")
         .argument("[query]", "要执行的 SQL 语句；省略时从标准输入读取")
         .action(async function (query) {
-        await (0, index_1.handleDbSql)(query, this.optsWithGlobals());
+        await (0, index_1.handleDbSql)(query, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -73,7 +82,7 @@ Examples:
         "查看单表完整结构请用 `schema get`；查看 DDL 变更历史请用 `changelog`（P1）。")
         .usage("[flags]")
         .action(async function () {
-        await (0, index_1.handleDbSchemaList)(this.optsWithGlobals());
+        await (0, index_1.handleDbSchemaList)({ ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Examples:
@@ -103,7 +112,7 @@ Examples:
         .argument("<table>", "表名（无需带 schema 前缀）")
         .option("--ddl", "强制输出 CREATE TABLE 建表语句（pretty 默认就是 DDL，--json 时配合此 flag 返 SQL 文本）")
         .action(async function (table) {
-        await (0, index_1.handleDbSchemaGet)(table, this.optsWithGlobals());
+        await (0, index_1.handleDbSchemaGet)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Examples:
@@ -144,7 +153,7 @@ Examples:
         .option("--table <name>", "目标表名；未指定时按文件名（不含扩展名）推断（如 users.csv → users）")
         .option("--format <fmt>", "文件格式 csv / json；未指定时按文件扩展名推断")
         .action(async function (file) {
-        await (0, index_1.handleDbDataImport)(file, this.optsWithGlobals());
+        await (0, index_1.handleDbDataImport)(file, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -181,7 +190,7 @@ Examples:
         .option("--limit <n>", "最多导出行数（不超过 5000）")
         .option("--force", "输出文件已存在时覆盖（默认报错）")
         .action(async function (table) {
-        await (0, index_1.handleDbDataExport)(table, this.optsWithGlobals());
+        await (0, index_1.handleDbDataExport)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
     })
         .addHelpText("after", `
 Notes:
@@ -205,5 +214,431 @@ Examples:
   $ miaoda db data export users
   Error: Output file 'users.csv' already exists
     hint: Use -f to specify a different path, or --force to overwrite.
+`);
+    // ── changelog ──
+    dbCmd
+        .command("changelog")
+        .summary("查看 DDL 变更历史")
+        .description("查看 DDL 变更记录（建表、改表、删表等）。默认按时间倒序显示，可按表名或时间范围过滤。")
+        .usage("[flags]")
+        .option("--table <name>", "按表名过滤")
+        .option("--since <time>", "起始时间，支持 YYYY-MM-DD（按当日 00:00:00 UTC）/ ISO 8601（如 2026-04-01T10:00:00Z）/ 相对时间（1h、2d、1w）")
+        .option("--until <time>", "截止时间，格式同 --since")
+        .option("--limit <n>", "返回条数上限（默认 20）", parsePositiveInt, 20)
+        .option("--cursor <token>", "从上一页返回的游标位置继续获取")
+        .option("--all", "获取全部结果，自动翻页")
+        .action(async function () {
+        await (0, index_1.handleDbChangelog)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - DDL 变更由系统自动记录，不可关闭，无需单独开启。
+  - 默认输出展示摘要（summary），完整 SQL 原文（statement）通过 --json 获取。
+
+Examples:
+  # 列出近期变更（statement 截断展示，完整 SQL 用 --json 获取）
+  $ miaoda db changelog
+  change_id          changed_at             operator   target_table   change_type             summary
+  1862462453263587   2026-04-16 13:24:59    zqy        users          ALTER_AUDIT_RETENTION   修改记录日志周期
+  1861814222210116   2026-04-08 20:12:37    zqy        users          CREATE_TABLE            创建并修改数据表
+
+  # 按条件过滤
+  $ miaoda db changelog --table users --since 2026-04-01
+  $ miaoda db changelog --limit 5
+
+  # JSON 输出包含完整 statement
+  $ miaoda db changelog --limit 1 --json
+  {
+    "data": [{
+      "change_id": "1861814222210116",
+      "changed_at": "2026-04-08T20:12:37Z",
+      "operator": "zqy",
+      "target_table": "users",
+      "change_type": "CREATE_TABLE",
+      "summary": "创建并修改数据表",
+      "statement": "CREATE TABLE ... ;"
+    }],
+    "next_cursor": null,
+    "has_more": false
+  }
+`);
+    // ── audit ──
+    const auditCmd = dbCmd
+        .command("audit")
+        .summary("表级数据审计开关与查询")
+        .description("配置表的数据审计 (enable/disable/retention)，查询审计状态与日志。")
+        .usage("<command> [flags]");
+    auditCmd.action(() => {
+        auditCmd.outputHelp();
+    });
+    auditCmd
+        .command("status")
+        .summary("查看审计开关状态")
+        .description("查看表的审计开关状态。不指定表则显示全部。")
+        .usage("[table] [flags]")
+        .argument("[table]", "表名；省略时返所有已配置审计的表")
+        .action(async function (table) {
+        await (0, index_1.handleDbAuditStatus)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  # 全部表
+  $ miaoda db audit status
+  table     enabled   enabled_at            retention
+  users     yes       2026-04-01 08:00:00   30d
+  orders    no        —                     —
+  products  yes       2026-03-15 10:30:00   forever
+
+  # 单表
+  $ miaoda db audit status users
+       Table:  users
+     Enabled:  yes
+  Enabled at:  2026-04-01 08:00:00
+   Retention:  30d
+
+  # JSON
+  $ miaoda db audit status --json
+  $ miaoda db audit status users --json
+`);
+    auditCmd
+        .command("enable")
+        .summary("启用表审计")
+        .description("开启指定表的审计，记录每次 INSERT / UPDATE / DELETE 操作。")
+        .usage("<table> [flags]")
+        .argument("<table>", "目标表名")
+        .option("--retention <period>", "审计日志保留时长，可选 7d / 30d / 180d / 360d / forever", "7d")
+        .action(async function (table) {
+        await (0, index_1.handleDbAuditEnable)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 开启审计会占用额外存储空间，计入应用的存储配额。
+  - 用 \`miaoda db quota\` 查看用量；用 \`miaoda db audit disable\` 或调整 --retention 控制开销。
+
+Examples:
+  # 默认保留 7 天
+  $ miaoda db audit enable orders
+  ✓ Audit enabled for table 'orders' (retention: 7d)
+
+  # 指定保留时长 / 永久保留
+  $ miaoda db audit enable orders --retention 180d
+  $ miaoda db audit enable orders --retention forever
+
+  # JSON
+  $ miaoda db audit enable orders --retention 180d --json
+
+  # 报错：已经开启
+  $ miaoda db audit enable orders
+  Error: Audit is already enabled for table 'orders'
+    hint: Use \`miaoda db audit status orders\` to check current retention,
+          or run this command with a different --retention to update.
+
+  # 报错：retention 值非法
+  $ miaoda db audit enable orders --retention 60d
+  Error: Invalid retention '60d'
+    hint: Allowed values: 7d, 30d, 180d, 360d, forever.
+`);
+    auditCmd
+        .command("disable")
+        .summary("关闭表审计")
+        .description("关闭指定表的审计。")
+        .usage("<table> [flags]")
+        .argument("<table>", "目标表名")
+        .action(async function (table) {
+        await (0, index_1.handleDbAuditDisable)(table, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db audit disable orders
+  ✓ Audit disabled for table 'orders'
+
+  # JSON
+  $ miaoda db audit disable orders --json
+
+  # 报错：未开启
+  $ miaoda db audit disable orders
+  Error: Audit is not enabled for table 'orders'
+    hint: Use \`miaoda db audit status\` to see which tables have audit enabled.
+`);
+    auditCmd
+        .command("list")
+        .summary("查询审计日志")
+        .description("查询一个或多个表的审计日志记录。多表查询时输出会带 target_table 列标识每条记录所属的表。")
+        .usage("<table...> [flags]")
+        .argument("<tables...>", "一个或多个表名")
+        .option("--since <time>", "起始时间，支持 YYYY-MM-DD / ISO 8601 / 相对时间（同 changelog --since）")
+        .option("--until <time>", "截止时间，格式同 --since")
+        .option("--limit <n>", "返回条数上限（默认 20）", parsePositiveInt, 20)
+        .option("--cursor <token>", "从上一页返回的游标位置继续获取")
+        .option("--all", "获取全部结果，自动翻页")
+        .action(async function (tables) {
+        await (0, index_1.handleDbAuditList)(tables, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 默认输出展示变更摘要（summary），完整变更快照（details 含 before / after）通过 --json 获取。
+  - 多表查询时不可用的表（未开启审计或不存在）会被跳过而非整体失败，全部不可用才返回错误。
+  - 退出码：只要有任何一张表有结果即为 0（跳过不算失败）；全部不可用才为 1。
+
+Examples:
+  # 单表
+  $ miaoda db audit list users --limit 5
+
+  # 多表（输出带 target_table 列区分来源）
+  $ miaoda db audit list users orders --limit 5
+
+  # 按时间范围
+  $ miaoda db audit list users --since 2026-04-14 --limit 10
+
+  # JSON（含完整 details / before / after）
+  $ miaoda db audit list users --limit 1 --json
+
+  # 报错：单表未开启
+  $ miaoda db audit list orders
+  Error: Audit is not enabled for table 'orders'
+    hint: Run \`miaoda db audit enable orders\` to start recording changes.
+
+  # 多表全部不可用才整体报错
+  $ miaoda db audit list orders invoices
+  Error: No audit data available for any of the specified tables
+    hint: Check audit status with \`miaoda db audit status\`.
+`);
+    // ── migration ──
+    const migrationCmd = dbCmd
+        .command("migration")
+        .summary("多环境管理（dev / online，仅专家模式应用）")
+        .description("init 拆分双环境，diff 预览待发布变更，apply 把 dev 同步到 online。")
+        .usage("<command> [flags]");
+    migrationCmd.action(() => {
+        migrationCmd.outputHelp();
+    });
+    migrationCmd
+        .command("init")
+        .summary("初始化多环境模式（dev / online）")
+        .description("初始化多环境模式（dev / online）。初始化后，dev 环境的数据库结构变更需要经 `migration apply` " +
+        "应用到 online；online 将无法直接更改数据库结构（仍可进行数据 DML 操作）。")
+        .usage("[flags]")
+        .option("--sync-data", "启用时将现有数据同步一份到 dev 环境")
+        .option("-y, --yes", "跳过确认提示直接执行")
+        .action(async function () {
+        await (0, index_1.handleDbMigrationInit)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 多环境模式一旦启用无法恢复为单库模式，请确认后再启用。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db migration init
+  ? This action is irreversible. Initialize multi-env (dev / online)? (y/N) y
+  ✓ Multi-env initialized (dev / online)
+
+  # --yes 跳过确认（Agent / CI 场景）
+  $ miaoda db migration init --sync-data --yes
+  ✓ Multi-env initialized, data synced to dev
+
+  # JSON
+  $ miaoda db migration init --yes --json
+  {"data": {"status": "initialized", "environments": ["dev", "online"], "data_synced": false}}
+
+  # 报错：已经初始化过
+  $ miaoda db migration init
+  Error: Multi-env is already initialized
+    hint: Run \`miaoda db migration diff\` to view pending changes.
+`);
+    migrationCmd
+        .command("diff")
+        .summary("预览 dev → online 待发布变更")
+        .description("预览 dev → online 的待发布变更。只读预览，不会实际发布。")
+        .usage("[flags]")
+        .action(async function () {
+        await (0, index_1.handleDbMigrationDiff)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db migration diff
+  dev → online (2 changes):
+
+    ALTER TABLE users ADD COLUMN avatar_url text;
+    CREATE INDEX idx_users_avatar ON users(avatar_url);
+
+  # JSON
+  $ miaoda db migration diff --json
+
+  # 报错：无待发布变更
+  $ miaoda db migration diff
+  Error: No pending changes between dev and online
+    hint: Make schema changes in dev first (e.g. \`miaoda db sql "ALTER TABLE ..." --env dev\`).
+
+  # 报错：多环境未初始化
+  $ miaoda db migration diff
+  Error: Multi-env is not initialized
+    hint: Run \`miaoda db migration init\` to set up multi-env first.
+`);
+    migrationCmd
+        .command("apply")
+        .summary("将 dev 的变更发布到 online（单事务原子）")
+        .description("将 dev 的变更发布到 online。")
+        .usage("[flags]")
+        .option("-y, --yes", "跳过确认提示直接执行")
+        .action(async function () {
+        await (0, index_1.handleDbMigrationApply)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 该操作会直接改动线上数据库，建议先用 \`migration diff\` 确认变更。
+  - 变更以单事务执行：多条 DDL 任何一条失败整批回滚，online 保持原状态。
+  - 退出码：0 表示全部成功；1 表示已回滚。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db migration apply
+  ? Apply 2 changes to online? (y/N) y
+  ✓ Applied dev → online (2 changes)
+
+  # --yes 跳过确认
+  $ miaoda db migration apply --yes
+  ✓ Applied dev → online (2 changes)
+
+  # JSON
+  $ miaoda db migration apply --yes --json
+  {"data": {"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}}
+
+  # 报错：无待发布变更
+  $ miaoda db migration apply
+  Error: No pending changes to apply
+    hint: Make schema changes in dev first, then run \`miaoda db migration diff\` to preview.
+
+  # 报错：多环境未启用
+  $ miaoda db migration apply
+  Error: Multi-env is not initialized
+    hint: Run \`miaoda db migration init\` to set up multi-env first.
+`);
+    // ── recovery（PITR）──
+    const recoveryCmd = dbCmd
+        .command("recovery")
+        .summary("基于时间点恢复（PITR）")
+        .description("把数据库整体恢复到指定时间点，diff 预览影响范围，apply 不可逆覆盖。")
+        .usage("<command> [flags]");
+    recoveryCmd.action(() => {
+        recoveryCmd.outputHelp();
+    });
+    recoveryCmd
+        .command("diff")
+        .summary("预览恢复到指定时间点的影响范围")
+        .description("预览恢复到指定时间点的影响范围（受影响的表、数据变更量、预计耗时）。只读预览，不改动数据。")
+        .usage("<timestamp> [flags]")
+        .argument("<timestamp>", "目标时间，YYYY-MM-DD 或 ISO 8601（如 2026-04-15T10:00:00Z）")
+        .action(async function (target) {
+        await (0, index_1.handleDbRecoveryDiff)(target, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 超出可恢复窗口的时间点会报错，错误信息中会标注当前可恢复窗口。
+
+Examples:
+  # TTY pretty
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z
+  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（管道，TAB 分列）
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z | cat
+  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	30
+
+  # JSON
+  $ miaoda db recovery diff 2026-04-15T10:00:00Z --json
+
+  # 无变更（目标时间点与当前状态一致）
+  $ miaoda db recovery diff 2026-04-15T14:00:00Z
+  Recovery preview (→ 2026-04-15T14:00:00Z):
+
+    No changes — database is already at this state.
+
+  # 超出可恢复窗口
+  $ miaoda db recovery diff 2026-04-05T10:00:00Z
+  Error: Timestamp is outside the recoverable window
+    hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
+
+  # 时间格式错误
+  $ miaoda db recovery diff 2026/04/15
+  Error: Invalid timestamp format '2026/04/15'
+    hint: Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z
+`);
+    recoveryCmd
+        .command("apply")
+        .summary("将数据库恢复到指定时间点的状态")
+        .description("将数据库恢复到指定时间点的状态。")
+        .usage("<timestamp> [flags]")
+        .argument("<timestamp>", "目标时间，YYYY-MM-DD 或 ISO 8601（如 2026-04-15T10:00:00Z）")
+        .option("-y, --yes", "跳过确认提示直接执行")
+        .action(async function (target) {
+        await (0, index_1.handleDbRecoveryApply)(target, this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Notes:
+  - 该操作会覆盖当前数据且不可撤销，建议先用 \`recovery diff\` 预览影响。
+  - 恢复过程是原子的：中途失败时数据库回到操作前的状态，不会出现部分恢复。
+  - 退出码：0 表示完成；1 表示已回滚。
+
+Examples:
+  # TTY 下会要求确认
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z
+  ? Restore database to 2026-04-15T10:00:00Z? This will overwrite current data. (y/N) y
+  ✓ Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
+
+  # --yes 跳过确认
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes
+
+  # JSON
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes --json
+
+  # 超出可恢复窗口
+  $ miaoda db recovery apply 2026-04-05T10:00:00Z
+  Error: Timestamp is outside the recoverable window
+    hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
+          Run \`miaoda db recovery diff <ts>\` within this window to preview impact.
+
+  # 并发冲突（已有恢复任务在执行）
+  $ miaoda db recovery apply 2026-04-15T10:00:00Z
+  Error: Another recovery is already in progress
+    hint: Wait for the current recovery to finish.
+`);
+    // ── quota ──
+    dbCmd
+        .command("quota")
+        .summary("查看数据库的存储用量与限额")
+        .description("查看数据库的存储用量、配额和表数量。")
+        .usage("[flags]")
+        .action(async function () {
+        await (0, index_1.handleDbQuota)(this.optsWithGlobals());
+    })
+        .addHelpText("after", `
+Examples:
+  $ miaoda db quota
+      Storage:  14.9 MB / 1 GB (1.5%)
+       Tables:  3
+        Views:  10
+
+  # JSON
+  $ miaoda db quota --json
+  {
+    "data": {
+      "storage_used_bytes": 15623782,
+      "storage_quota_bytes": 1073741824,
+      "usage_percent": 1.5,
+      "tables": 3,
+      "views": 10
+    }
+  }
 `);
 }

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

@@ -0,0 +1,155 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDeployCommands = registerDeployCommands;
+const commander_1 = require("commander");
+const shared_1 = require("../../../cli/commands/shared");
+const index_1 = require("../../../cli/handlers/deploy/index");
+const COMMON_TIME_HELP = `
+时间格式：
+  - 相对时间：30m（30 分钟前）、1h、2d、1w
+  - 日期：2026-04-01（本地时区当日 00:00:00）
+  - 本地日期+时间：2026-04-01T10:00:00（按本地时区，T 分隔）
+  - 带时区 ISO：2026-04-01T10:00:00Z（UTC）或 2026-04-01T10:00:00+08:00（指定偏移）
+  备注：
+    1) 不带时区的形式与 pretty 输出闭环（同机器复制粘贴稳定）；跨机器请带显式时区。
+    2) 必须用 T 分隔日期与时间，禁止空格——shell 会把不带引号的 'YYYY-MM-DD HH:mm:ss' 拆成两个参数。
+`;
+function registerDeployCommands(program) {
+    // PRD：`miaoda deploy` 自身即为触发发布；get / history / error-log 是子命令
+    const deployCmd = program
+        .command("deploy")
+        .description("触发发布；支持 --wait 阻塞到终态。子命令：get / history / error-log")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addOption((0, shared_1.branchOption)().hideHelp())
+        .option("--wait", "阻塞直到流水线终态", false)
+        .option("--timeout <sec>", "--wait 最长等待秒数（默认 300）", parseTimeout, 300)
+        .addHelpText("after", `
+不要用异步模式或后台模式调用 deploy（例如 &、nohup、后台 task、detached run，或任何会让命令提前返回的包装方式），否则调用可能提前结束，Agent 会误判发布已完成。
+部署前置检查（Agent 必须执行）
+  miaoda deploy 跑的是当前分支的远端 HEAD——本地未 commit / 未 push 的代码不会进发布产物。
+  调用前先 \`git status\` + \`git rev-list --count @{u}..HEAD\` 确认；有未提交 / 未推送时：
+    - 是本次任务的产物 → 先 commit + push 再 deploy
+    - 不能确定意图 → 用 AskUser 跟用户确认（不要默默继续）
+
+JSON 输出
+  不带 --wait：{"data": {"pipelineTaskID": "..."}}（pipelineTaskID 即 deploy-id）
+  带 --wait：data 额外包含 detail（pipeline 终态）
+  detail/status 字段为可读字符串；对应 *_code 字段保留 BAM 原始数字枚举。
+
+状态确认（Agent 必须执行）
+  优先使用 --wait，但无论是否传 --wait，只要 deploy 调用后没有明确的 success / failed / canceled 终态，
+  都必须每 2s 轮询一次当前发布状态：拿到 pipelineTaskID 就执行 \`miaoda deploy get <pipelineTaskID> --json\`；
+  如果没有拿到 deploy-id 或输出为空，先执行 \`miaoda deploy history --limit 1 --json\` 找到对应发布记录并取得 ID，
+  再用这个 ID 每 2s 执行一次 \`miaoda deploy get <ID> --json\`，直到 status 进入终态。
+
+示例
+  $ miaoda deploy
+  $ miaoda deploy --wait --timeout 600
+  $ miaoda deploy get 12345
+  $ miaoda deploy history --status failed
+`);
+    deployCmd.action((0, shared_1.withHelp)(deployCmd, async (rawOpts) => {
+        (0, shared_1.rejectCliOverride)(deployCmd, "appId", "branch");
+        await (0, index_1.handleDeploy)({
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            branch: rawOpts.branch,
+            wait: rawOpts.wait,
+            timeout: rawOpts.timeout,
+        });
+    }));
+    registerDeployGet(deployCmd);
+    registerDeployHistory(deployCmd);
+    registerDeployErrorLog(deployCmd);
+}
+function registerDeployGet(parent) {
+    const cmd = parent
+        .command("get")
+        .description("查看指定发布单的详情")
+        .argument("<deploy-id>", "发布单 ID")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addHelpText("after", `
+JSON 输出
+  {"data": {"ID": ..., "status": ..., "creator": "...", "createdAt": ..., "updatedAt": ..., ...}, "next_cursor": null, "has_more": false}
+  ID 即 deploy-id（== pipelineTaskID）
+  data.status 为可读字符串；data.status_code 为 BAM 原始数字枚举。
+
+示例
+  $ miaoda deploy get 12345
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (deployId, rawOpts) => {
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleDeployGet)({
+            deployId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+        });
+    }));
+}
+function registerDeployHistory(parent) {
+    const cmd = parent
+        .command("history")
+        .description("查询发布历史（按时间倒序，分页）")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addOption(new commander_1.Option("--status <status>", "状态过滤（pipeline 节点状态，大小写不敏感）")
+        .choices(["todo", "running", "success", "failed", "canceled", "hold_on"])
+        .argParser((0, shared_1.caseInsensitiveChoice)(["todo", "running", "success", "failed", "canceled", "hold_on"])))
+        .option("--since <time>", "起始时间")
+        .option("--until <time>", "截止时间")
+        .option("--limit <n>", "返回条数上限（1~100）", parseLimit, 50)
+        .option("--cursor <token>", "下一页游标")
+        .addHelpText("after", `${COMMON_TIME_HELP}
+JSON 输出
+  {"data": [...], "next_cursor": "...", "has_more": true|false}
+  data[].status 为可读字符串；data[].status_code 为 BAM 原始数字枚举。
+
+示例
+  $ miaoda deploy history --status failed
+  $ miaoda deploy history --since 7d
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (rawOpts) => {
+        (0, shared_1.validateTimeOptions)(rawOpts, "since", "until");
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleDeployHistory)({
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+            status: rawOpts.status,
+            since: rawOpts.since,
+            until: rawOpts.until,
+            limit: rawOpts.limit,
+            cursor: rawOpts.cursor,
+        });
+    }));
+}
+function registerDeployErrorLog(parent) {
+    const cmd = parent
+        .command("error-log")
+        .description("查询指定发布的错误日志")
+        .argument("<deploy-id>", "发布单 ID")
+        .addOption((0, shared_1.appIdOption)().hideHelp())
+        .addHelpText("after", `
+JSON 输出
+  {"data": [{"jobID": ..., "componentName": ..., "errorMsg": ...}], "next_cursor": null, "has_more": false}
+
+示例
+  $ miaoda deploy error-log 12345 --json
+`);
+    cmd.action((0, shared_1.withHelp)(cmd, async (deployId, rawOpts) => {
+        (0, shared_1.rejectCliOverride)(cmd, "appId");
+        await (0, index_1.handleDeployErrorLog)({
+            deployId,
+            appId: (0, shared_1.resolveAppId)({ appId: rawOpts.appId }),
+        });
+    }));
+}
+function parseLimit(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n)) {
+        throw new Error(`--limit 必须是数字，收到 '${value}'`);
+    }
+    return n;
+}
+function parseTimeout(value) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`--timeout 必须是正数，收到 '${value}'`);
+    }
+    return n;
+}