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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/dist/api/app/api.js +3 -3
  2. package/dist/api/app/schemas.js +43 -43
  3. package/dist/api/db/api.js +108 -112
  4. package/dist/api/db/client.js +41 -41
  5. package/dist/api/db/parsers.js +20 -20
  6. package/dist/api/db/sql-keywords.js +87 -87
  7. package/dist/api/deploy/api.js +5 -5
  8. package/dist/api/deploy/schemas.js +32 -32
  9. package/dist/api/file/api.js +74 -87
  10. package/dist/api/file/client.js +22 -22
  11. package/dist/api/file/detect.js +3 -3
  12. package/dist/api/file/parsers.js +18 -7
  13. package/dist/api/observability/api.js +6 -6
  14. package/dist/api/observability/schemas.js +14 -14
  15. package/dist/api/plugin/api.js +31 -31
  16. package/dist/cli/commands/app/index.js +12 -12
  17. package/dist/cli/commands/db/index.js +268 -163
  18. package/dist/cli/commands/deploy/index.js +28 -28
  19. package/dist/cli/commands/file/index.js +81 -61
  20. package/dist/cli/commands/observability/index.js +69 -69
  21. package/dist/cli/commands/plugin/index.js +27 -27
  22. package/dist/cli/commands/shared.js +10 -10
  23. package/dist/cli/handlers/app/update.js +2 -2
  24. package/dist/cli/handlers/db/audit.js +52 -43
  25. package/dist/cli/handlers/db/changelog.js +25 -12
  26. package/dist/cli/handlers/db/data.js +31 -30
  27. package/dist/cli/handlers/db/migration.js +27 -27
  28. package/dist/cli/handlers/db/quota.js +3 -3
  29. package/dist/cli/handlers/db/recovery.js +111 -82
  30. package/dist/cli/handlers/db/schema.js +33 -33
  31. package/dist/cli/handlers/db/sql.js +69 -69
  32. package/dist/cli/handlers/deploy/deploy.js +4 -4
  33. package/dist/cli/handlers/deploy/error-log.js +1 -1
  34. package/dist/cli/handlers/deploy/get.js +3 -3
  35. package/dist/cli/handlers/deploy/polling.js +11 -11
  36. package/dist/cli/handlers/file/cp.js +30 -30
  37. package/dist/cli/handlers/file/ls.js +5 -5
  38. package/dist/cli/handlers/file/quota.js +2 -2
  39. package/dist/cli/handlers/file/rm.js +24 -24
  40. package/dist/cli/handlers/file/sign.js +3 -3
  41. package/dist/cli/handlers/file/stat.js +10 -9
  42. package/dist/cli/handlers/observability/analytics.js +47 -47
  43. package/dist/cli/handlers/observability/helpers.js +2 -2
  44. package/dist/cli/handlers/observability/log.js +9 -9
  45. package/dist/cli/handlers/observability/metric.js +26 -26
  46. package/dist/cli/handlers/observability/trace.js +5 -5
  47. package/dist/cli/handlers/plugin/plugin-local.js +53 -53
  48. package/dist/cli/handlers/plugin/plugin.js +15 -15
  49. package/dist/cli/help.js +16 -16
  50. package/dist/main.js +12 -12
  51. package/dist/utils/args.js +1 -1
  52. package/dist/utils/colors.js +2 -2
  53. package/dist/utils/config.js +2 -2
  54. package/dist/utils/devops-error.js +9 -9
  55. package/dist/utils/error.js +2 -2
  56. package/dist/utils/git.js +4 -4
  57. package/dist/utils/http.js +19 -19
  58. package/dist/utils/output.js +47 -47
  59. package/dist/utils/poll.js +2 -2
  60. package/dist/utils/render.js +27 -27
  61. package/dist/utils/time.js +47 -42
  62. package/package.json +1 -1
@@ -7,33 +7,33 @@ const shared_1 = require("../../../cli/commands/shared");
7
7
  function parsePositiveInt(raw) {
8
8
  const n = Number(raw);
9
9
  if (!Number.isInteger(n) || n < 1) {
10
- throw new error_1.AppError("ARGS_INVALID", `--limit must be a positive integer (got '${raw}')`);
10
+ throw new error_1.AppError('ARGS_INVALID', `--limit must be a positive integer (got '${raw}')`);
11
11
  }
12
12
  return n;
13
13
  }
14
14
  function registerDbCommands(program) {
15
15
  const dbCmd = program
16
- .command("db")
17
- .description("应用数据库(PostgreSQL)的命令行操作集合。")
18
- .usage("<command> [flags]")
16
+ .command('db')
17
+ .description('应用数据库(PostgreSQL)的命令行操作集合。')
18
+ .usage('<command> [flags]')
19
19
  // --env 注册在 db 父级,spec 把它列入 db --help 的 Global Flags;
20
20
  // leaf 命令仍各自接收 --env 值(commander 解析时父级 option 自动适用于子命令)
21
- .option("--env <name>", "指定目标环境(dev / online,仅专家模式应用支持)");
21
+ .option('--env <name>', '指定目标环境(dev / online,仅专家模式应用支持)');
22
22
  dbCmd.action(() => {
23
23
  dbCmd.outputHelp();
24
24
  });
25
25
  dbCmd
26
- .command("sql")
27
- .summary("执行任意 SQL(SELECT / DML / DDL,支持多条分号分隔)")
28
- .description("执行 SQL 语句,支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n" +
29
- "支持通过 stdin 读取(miaoda db sql < file.sql),多条语句以分号分隔。\n" +
30
- "事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。")
31
- .usage("<query> [flags]")
32
- .argument("[query]", "要执行的 SQL 语句;省略时从标准输入读取")
26
+ .command('sql')
27
+ .summary('执行任意 SQL(SELECT / DML / DDL,支持多条分号分隔)')
28
+ .description('执行 SQL 语句,支持 SELECT、DML、DDL 等所有标准 PostgreSQL 操作。\n' +
29
+ '支持通过 stdin 读取(miaoda db sql < file.sql),多条语句以分号分隔。\n' +
30
+ '事务控制使用 PG 原生的 BEGIN / COMMIT / ROLLBACK 语法。')
31
+ .usage('<query> [flags]')
32
+ .argument('[query]', '要执行的 SQL 语句;省略时从标准输入读取')
33
33
  .action(async function (query) {
34
34
  await (0, index_1.handleDbSql)(query, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
35
35
  })
36
- .addHelpText("after", `
36
+ .addHelpText('after', `
37
37
  Notes:
38
38
  - SELECT 结果超过 1000 行直接报错(RESULT_SET_TOO_LARGE),不做隐式截断。
39
39
  需要分页时请在 SQL 中用 LIMIT / OFFSET。
@@ -68,23 +68,23 @@ Examples:
68
68
  `);
69
69
  // schema 二级资源分组
70
70
  const schemaCmd = dbCmd
71
- .command("schema")
72
- .summary("查看数据库表结构")
73
- .description("查看应用数据库的表结构信息。")
74
- .usage("<command> [flags]");
71
+ .command('schema')
72
+ .summary('查看数据库表结构')
73
+ .description('查看应用数据库的表结构信息。')
74
+ .usage('<command> [flags]');
75
75
  schemaCmd.action(() => {
76
76
  schemaCmd.outputHelp();
77
77
  });
78
78
  schemaCmd
79
- .command("list")
80
- .summary("列出所有表的概览(表名、行数、大小等)")
81
- .description("列出当前应用所有表的概览信息:表名、描述、行数、大小、列数、最近更新时间。\n" +
82
- "查看单表完整结构请用 `schema get`;查看 DDL 变更历史请用 `changelog`(P1)。")
83
- .usage("[flags]")
79
+ .command('list')
80
+ .summary('列出所有表的概览(表名、行数、大小等)')
81
+ .description('列出当前应用所有表的概览信息:表名、描述、行数、大小、列数、最近更新时间。\n' +
82
+ '查看单表完整结构请用 `schema get`;查看 DDL 变更历史请用 `changelog`。')
83
+ .usage('[flags]')
84
84
  .action(async function () {
85
85
  await (0, index_1.handleDbSchemaList)({ ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
86
86
  })
87
- .addHelpText("after", `
87
+ .addHelpText('after', `
88
88
  Examples:
89
89
  $ miaoda db schema list
90
90
  name description rows size columns updated_at
@@ -104,17 +104,17 @@ Examples:
104
104
  }
105
105
  `);
106
106
  schemaCmd
107
- .command("get")
108
- .summary("查看单表完整结构(列定义、索引、约束)")
109
- .description("查看指定表的完整结构:列定义(含类型、可空、默认值、注释)、索引、行数、大小。\n" +
110
- "默认 pretty 输出 CREATE TABLE 的 SQL 文本;--json 输出结构化字段。")
111
- .usage("<table> [flags]")
112
- .argument("<table>", "表名(无需带 schema 前缀)")
113
- .option("--ddl", "强制输出 CREATE TABLE 建表语句(pretty 默认就是 DDL,--json 时配合此 flag 返 SQL 文本)")
107
+ .command('get')
108
+ .summary('查看单表完整结构(列定义、索引、约束)')
109
+ .description('查看指定表的完整结构:列定义(含类型、可空、默认值、注释)、索引、行数、大小。\n' +
110
+ '默认 pretty 输出 CREATE TABLE 的 SQL 文本;--json 输出结构化字段。')
111
+ .usage('<table> [flags]')
112
+ .argument('<table>', '表名(无需带 schema 前缀)')
113
+ .option('--ddl', '强制输出 CREATE TABLE 建表语句(pretty 默认就是 DDL,--json 时配合此 flag 返 SQL 文本)')
114
114
  .action(async function (table) {
115
115
  await (0, index_1.handleDbSchemaGet)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
116
116
  })
117
- .addHelpText("after", `
117
+ .addHelpText('after', `
118
118
  Examples:
119
119
  $ miaoda db schema get users
120
120
  CREATE TABLE users (
@@ -135,27 +135,27 @@ Examples:
135
135
  `);
136
136
  // data 二级资源分组
137
137
  const dataCmd = dbCmd
138
- .command("data")
139
- .summary("表数据导入导出")
140
- .description("表数据的批量导入导出,适合数据备份、跨环境迁移、外部分析。")
141
- .usage("<command> [flags]");
138
+ .command('data')
139
+ .summary('表数据导入导出')
140
+ .description('表数据的批量导入导出,适合数据备份、跨环境迁移、外部分析。')
141
+ .usage('<command> [flags]');
142
142
  dataCmd.action(() => {
143
143
  dataCmd.outputHelp();
144
144
  });
145
145
  dataCmd
146
- .command("import")
147
- .summary("从本地 CSV / JSON 文件导入数据到表")
148
- .description("从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误(主键冲突、\n" +
149
- "类型不匹配、列名不匹配等)会回滚已插入的所有行。\n" +
150
- "不支持 SQL 文件,SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。")
151
- .usage("<file> [flags]")
152
- .argument("<file>", "本地文件路径(CSV 或 JSON 格式)")
153
- .option("--table <name>", "目标表名;未指定时按文件名(不含扩展名)推断(如 users.csv → users)")
154
- .option("--format <fmt>", "文件格式 csv / json;未指定时按文件扩展名推断")
146
+ .command('import')
147
+ .summary('从本地 CSV / JSON 文件导入数据到表')
148
+ .description('从本地 CSV / JSON 文件导入数据到表。整个导入是原子的——遇到任何错误(主键冲突、\n' +
149
+ '类型不匹配、列名不匹配等)会回滚已插入的所有行。\n' +
150
+ '不支持 SQL 文件,SQL 备份请用 `miaoda db sql < <文件>.sql` 回放。')
151
+ .usage('<file> [flags]')
152
+ .argument('<file>', '本地文件路径(CSV 或 JSON 格式)')
153
+ .option('--table <name>', '目标表名;未指定时按文件名(不含扩展名)推断(如 users.csv → users)')
154
+ .option('--format <fmt>', '文件格式 csv / json;未指定时按文件扩展名推断')
155
155
  .action(async function (file) {
156
156
  await (0, index_1.handleDbDataImport)(file, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
157
157
  })
158
- .addHelpText("after", `
158
+ .addHelpText('after', `
159
159
  Notes:
160
160
  - 目标表必须已存在;CSV 表头 / JSON 顶层 key 必须与表字段名完全一致。
161
161
  - 导入为原子操作:遇到错误回滚所有已插入行,不会出现部分导入的中间状态。
@@ -180,19 +180,19 @@ Examples:
180
180
  \`miaoda db sql "DELETE FROM users WHERE id IN (...)"\`.
181
181
  `);
182
182
  dataCmd
183
- .command("export")
184
- .summary("导出表数据到本地 CSV / JSON / SQL 文件")
185
- .description("把指定表的所有数据导出到本地文件,支持 CSV / JSON / SQL 三种格式。")
186
- .usage("<table> [flags]")
187
- .argument("<table>", "表名(无需带 schema 前缀)")
188
- .option("--format <fmt>", "导出格式 csv / json / sql,默认 csv(sql 输出 INSERT 语句,可用 db sql < file.sql 回放)")
189
- .option("-f, --file <path>", "输出文件路径,默认 <表名>.<格式>")
190
- .option("--limit <n>", "最多导出行数(不超过 5000)")
191
- .option("--force", "输出文件已存在时覆盖(默认报错)")
183
+ .command('export')
184
+ .summary('导出表数据到本地 CSV / JSON / SQL 文件')
185
+ .description('把指定表的所有数据导出到本地文件,支持 CSV / JSON / SQL 三种格式。')
186
+ .usage('<table> [flags]')
187
+ .argument('<table>', '表名(无需带 schema 前缀)')
188
+ .option('--format <fmt>', '导出格式 csv / json / sql,默认 csv(sql 输出 INSERT 语句,可用 db sql < file.sql 回放)')
189
+ .option('-f, --file <path>', '输出文件路径,默认 <表名>.<格式>')
190
+ .option('--limit <n>', '最多导出行数(不超过 5000)')
191
+ .option('--force', '输出文件已存在时覆盖(默认报错)')
192
192
  .action(async function (table) {
193
193
  await (0, index_1.handleDbDataExport)(table, { ...this.optsWithGlobals(), appId: (0, shared_1.resolveAppId)({}) });
194
194
  })
195
- .addHelpText("after", `
195
+ .addHelpText('after', `
196
196
  Notes:
197
197
  - SQL 格式生成 INSERT 语句,可用 \`miaoda db sql < <文件>.sql\` 在其他环境回放。
198
198
  - 文件已存在时默认报错(FILE_ALREADY_EXISTS),用 --force 覆盖或 -f 改路径。
@@ -217,20 +217,20 @@ Examples:
217
217
  `);
218
218
  // ── changelog ──
219
219
  dbCmd
220
- .command("changelog")
221
- .summary("查看 DDL 变更历史")
222
- .description("查看 DDL 变更记录(建表、改表、删表等)。默认按时间倒序显示,可按表名或时间范围过滤。")
223
- .usage("[flags]")
224
- .option("--table <name>", "按表名过滤")
225
- .option("--since <time>", "起始时间,支持 YYYY-MM-DD(按当日 00:00:00 UTC)/ ISO 8601(如 2026-04-01T10:00:00Z)/ 相对时间(1h、2d、1w)")
226
- .option("--until <time>", "截止时间,格式同 --since")
227
- .option("--limit <n>", "返回条数上限(默认 20)", parsePositiveInt, 20)
228
- .option("--cursor <token>", "从上一页返回的游标位置继续获取")
229
- .option("--all", "获取全部结果,自动翻页")
220
+ .command('changelog')
221
+ .summary('查看 DDL 变更历史')
222
+ .description('查看 DDL 变更记录(建表、改表、删表等)。默认按时间倒序显示,可按表名或时间范围过滤。')
223
+ .usage('[flags]')
224
+ .option('--table <name>', '按表名过滤')
225
+ .option('--since <time>', '起始时间')
226
+ .option('--until <time>', '截止时间')
227
+ .option('--limit <n>', '返回条数上限(默认 20)', parsePositiveInt, 20)
228
+ .option('--cursor <token>', '从上一页返回的游标位置继续获取')
229
+ .option('--all', '获取全部结果,自动翻页')
230
230
  .action(async function () {
231
231
  await (0, index_1.handleDbChangelog)(this.optsWithGlobals());
232
232
  })
233
- .addHelpText("after", `
233
+ .addHelpText('after', `
234
234
  Notes:
235
235
  - DDL 变更由系统自动记录,不可关闭,无需单独开启。
236
236
  - 默认输出展示摘要(summary),完整 SQL 原文(statement)通过 --json 获取。
@@ -246,7 +246,7 @@ Examples:
246
246
  $ miaoda db changelog --table users --since 2026-04-01
247
247
  $ miaoda db changelog --limit 5
248
248
 
249
- # JSON 输出包含完整 statement
249
+ # --json 输出包含完整 statement
250
250
  $ miaoda db changelog --limit 1 --json
251
251
  {
252
252
  "data": [{
@@ -264,23 +264,23 @@ Examples:
264
264
  `);
265
265
  // ── audit ──
266
266
  const auditCmd = dbCmd
267
- .command("audit")
268
- .summary("表级数据审计开关与查询")
269
- .description("配置表的数据审计 (enable/disable/retention),查询审计状态与日志。")
270
- .usage("<command> [flags]");
267
+ .command('audit')
268
+ .summary('表级数据审计开关与查询')
269
+ .description('配置表的数据审计 (enable/disable/retention),查询审计状态与日志。')
270
+ .usage('<command> [flags]');
271
271
  auditCmd.action(() => {
272
272
  auditCmd.outputHelp();
273
273
  });
274
274
  auditCmd
275
- .command("status")
276
- .summary("查看审计开关状态")
277
- .description("查看表的审计开关状态。不指定表则显示全部。")
278
- .usage("[table] [flags]")
279
- .argument("[table]", "表名;省略时返所有已配置审计的表")
275
+ .command('status')
276
+ .summary('查看审计开关状态')
277
+ .description('查看表的审计开关状态。不指定表则显示全部。')
278
+ .usage('[table] [flags]')
279
+ .argument('[table]', '表名;省略时返所有已配置审计的表')
280
280
  .action(async function (table) {
281
281
  await (0, index_1.handleDbAuditStatus)(table, this.optsWithGlobals());
282
282
  })
283
- .addHelpText("after", `
283
+ .addHelpText('after', `
284
284
  Examples:
285
285
  # 全部表
286
286
  $ miaoda db audit status
@@ -296,21 +296,38 @@ Examples:
296
296
  Enabled at: 2026-04-01 08:00:00
297
297
  Retention: 30d
298
298
 
299
- # JSON
299
+ # --json(全部表)
300
300
  $ miaoda db audit status --json
301
+ {
302
+ "data": [
303
+ {"table": "users", "enabled": true, "enabled_at": "2026-04-01T08:00:00Z", "retention": "30d"},
304
+ {"table": "orders", "enabled": false, "enabled_at": null, "retention": null},
305
+ {"table": "products", "enabled": true, "enabled_at": "2026-03-15T10:30:00Z", "retention": "forever"}
306
+ ]
307
+ }
308
+
309
+ # --json(单表)
301
310
  $ miaoda db audit status users --json
311
+ {
312
+ "data": {
313
+ "table": "users",
314
+ "enabled": true,
315
+ "enabled_at": "2026-04-01T08:00:00Z",
316
+ "retention": "30d"
317
+ }
318
+ }
302
319
  `);
303
320
  auditCmd
304
- .command("enable")
305
- .summary("启用表审计")
306
- .description("开启指定表的审计,记录每次 INSERT / UPDATE / DELETE 操作。")
307
- .usage("<table> [flags]")
308
- .argument("<table>", "目标表名")
309
- .option("--retention <period>", "审计日志保留时长,可选 7d / 30d / 180d / 360d / forever", "7d")
321
+ .command('enable')
322
+ .summary('启用表审计')
323
+ .description('开启指定表的审计,记录每次 INSERT / UPDATE / DELETE 操作。')
324
+ .usage('<table> [flags]')
325
+ .argument('<table>', '目标表名')
326
+ .option('--retention <period>', '审计日志保留时长,可选 7d / 30d / 180d / 360d / forever', '7d')
310
327
  .action(async function (table) {
311
328
  await (0, index_1.handleDbAuditEnable)(table, this.optsWithGlobals());
312
329
  })
313
- .addHelpText("after", `
330
+ .addHelpText('after', `
314
331
  Notes:
315
332
  - 开启审计会占用额外存储空间,计入应用的存储配额。
316
333
  - 用 \`miaoda db quota\` 查看用量;用 \`miaoda db audit disable\` 或调整 --retention 控制开销。
@@ -324,8 +341,19 @@ Examples:
324
341
  $ miaoda db audit enable orders --retention 180d
325
342
  $ miaoda db audit enable orders --retention forever
326
343
 
327
- # JSON
344
+ # non-TTY
345
+ $ miaoda db audit enable orders | cat
346
+ OK Audit enabled for table 'orders' (retention: 7d)
347
+
348
+ # --json
328
349
  $ miaoda db audit enable orders --retention 180d --json
350
+ {
351
+ "data": {
352
+ "table": "orders",
353
+ "enabled": true,
354
+ "retention": "180d"
355
+ }
356
+ }
329
357
 
330
358
  # 报错:已经开启
331
359
  $ miaoda db audit enable orders
@@ -339,21 +367,31 @@ Examples:
339
367
  hint: Allowed values: 7d, 30d, 180d, 360d, forever.
340
368
  `);
341
369
  auditCmd
342
- .command("disable")
343
- .summary("关闭表审计")
344
- .description("关闭指定表的审计。")
345
- .usage("<table> [flags]")
346
- .argument("<table>", "目标表名")
370
+ .command('disable')
371
+ .summary('关闭表审计')
372
+ .description('关闭指定表的审计。')
373
+ .usage('<table> [flags]')
374
+ .argument('<table>', '目标表名')
347
375
  .action(async function (table) {
348
376
  await (0, index_1.handleDbAuditDisable)(table, this.optsWithGlobals());
349
377
  })
350
- .addHelpText("after", `
378
+ .addHelpText('after', `
351
379
  Examples:
352
380
  $ miaoda db audit disable orders
353
381
  ✓ Audit disabled for table 'orders'
354
382
 
355
- # JSON
383
+ # non-TTY
384
+ $ miaoda db audit disable orders | cat
385
+ OK Audit disabled for table 'orders'
386
+
387
+ # --json
356
388
  $ miaoda db audit disable orders --json
389
+ {
390
+ "data": {
391
+ "table": "orders",
392
+ "enabled": false
393
+ }
394
+ }
357
395
 
358
396
  # 报错:未开启
359
397
  $ miaoda db audit disable orders
@@ -361,20 +399,20 @@ Examples:
361
399
  hint: Use \`miaoda db audit status\` to see which tables have audit enabled.
362
400
  `);
363
401
  auditCmd
364
- .command("list")
365
- .summary("查询审计日志")
366
- .description("查询一个或多个表的审计日志记录。多表查询时输出会带 target_table 列标识每条记录所属的表。")
367
- .usage("<table...> [flags]")
368
- .argument("<tables...>", "一个或多个表名")
369
- .option("--since <time>", "起始时间,支持 YYYY-MM-DD / ISO 8601 / 相对时间(同 changelog --since)")
370
- .option("--until <time>", "截止时间,格式同 --since")
371
- .option("--limit <n>", "返回条数上限(默认 20)", parsePositiveInt, 20)
372
- .option("--cursor <token>", "从上一页返回的游标位置继续获取")
373
- .option("--all", "获取全部结果,自动翻页")
402
+ .command('list')
403
+ .summary('查询审计日志')
404
+ .description('查询一个或多个表的审计日志记录。多表查询时输出会带 target_table 列标识每条记录所属的表。')
405
+ .usage('<table...> [flags]')
406
+ .argument('<tables...>', '一个或多个表名')
407
+ .option('--since <time>', '起始时间')
408
+ .option('--until <time>', '截止时间')
409
+ .option('--limit <n>', '返回条数上限(默认 20)', parsePositiveInt, 20)
410
+ .option('--cursor <token>', '从上一页返回的游标位置继续获取')
411
+ .option('--all', '获取全部结果,自动翻页')
374
412
  .action(async function (tables) {
375
413
  await (0, index_1.handleDbAuditList)(tables, this.optsWithGlobals());
376
414
  })
377
- .addHelpText("after", `
415
+ .addHelpText('after', `
378
416
  Notes:
379
417
  - 默认输出展示变更摘要(summary),完整变更快照(details 含 before / after)通过 --json 获取。
380
418
  - 多表查询时不可用的表(未开启审计或不存在)会被跳过而非整体失败,全部不可用才返回错误。
@@ -390,8 +428,23 @@ Examples:
390
428
  # 按时间范围
391
429
  $ miaoda db audit list users --since 2026-04-14 --limit 10
392
430
 
393
- # JSON(含完整 details / before / after)
431
+ # --json(含完整 details / before / after)
394
432
  $ miaoda db audit list users --limit 1 --json
433
+ {
434
+ "data": [{
435
+ "event_id": "01525416B44F87001509F20CD000000002",
436
+ "event_time": "2026-04-15T10:30:00Z",
437
+ "target_table": "users",
438
+ "type": "UPDATE",
439
+ "operator": "alice",
440
+ "details": {
441
+ "before": {"id": "ef4db805-...", "age": 28},
442
+ "after": {"id": "ef4db805-...", "age": 29}
443
+ }
444
+ }],
445
+ "next_cursor": null,
446
+ "has_more": false
447
+ }
395
448
 
396
449
  # 报错:单表未开启
397
450
  $ miaoda db audit list orders
@@ -405,25 +458,25 @@ Examples:
405
458
  `);
406
459
  // ── migration ──
407
460
  const migrationCmd = dbCmd
408
- .command("migration")
409
- .summary("多环境管理(dev / online,仅专家模式应用)")
410
- .description("init 拆分双环境,diff 预览待发布变更,apply 把 dev 同步到 online。")
411
- .usage("<command> [flags]");
461
+ .command('migration')
462
+ .summary('多环境管理(dev / online,仅专家模式应用)')
463
+ .description('init 拆分双环境,diff 预览待发布变更,apply 把 dev 同步到 online。')
464
+ .usage('<command> [flags]');
412
465
  migrationCmd.action(() => {
413
466
  migrationCmd.outputHelp();
414
467
  });
415
468
  migrationCmd
416
- .command("init")
417
- .summary("初始化多环境模式(dev / online)")
418
- .description("初始化多环境模式(dev / online)。初始化后,dev 环境的数据库结构变更需要经 `migration apply` " +
419
- "应用到 online;online 将无法直接更改数据库结构(仍可进行数据 DML 操作)。")
420
- .usage("[flags]")
421
- .option("--sync-data", "启用时将现有数据同步一份到 dev 环境")
422
- .option("-y, --yes", "跳过确认提示直接执行")
469
+ .command('init')
470
+ .summary('初始化多环境模式(dev / online)')
471
+ .description('初始化多环境模式(dev / online)。初始化后,dev 环境的数据库结构变更需要经 `migration apply` ' +
472
+ '应用到 online;online 将无法直接更改数据库结构(仍可进行数据 DML 操作)。')
473
+ .usage('[flags]')
474
+ .option('--sync-data', '启用时将现有数据同步一份到 dev 环境')
475
+ .option('-y, --yes', '跳过确认提示直接执行')
423
476
  .action(async function () {
424
477
  await (0, index_1.handleDbMigrationInit)(this.optsWithGlobals());
425
478
  })
426
- .addHelpText("after", `
479
+ .addHelpText('after', `
427
480
  Notes:
428
481
  - 多环境模式一旦启用无法恢复为单库模式,请确认后再启用。
429
482
 
@@ -437,9 +490,19 @@ Examples:
437
490
  $ miaoda db migration init --sync-data --yes
438
491
  ✓ Multi-env initialized, data synced to dev
439
492
 
440
- # JSON
493
+ # non-TTY
494
+ $ miaoda db migration init --yes | cat
495
+ OK Multi-env initialized (dev / online)
496
+
497
+ # --json
441
498
  $ miaoda db migration init --yes --json
442
- {"data": {"status": "initialized", "environments": ["dev", "online"], "data_synced": false}}
499
+ {
500
+ "data": {
501
+ "status": "initialized",
502
+ "environments": ["dev", "online"],
503
+ "data_synced": false
504
+ }
505
+ }
443
506
 
444
507
  # 报错:已经初始化过
445
508
  $ miaoda db migration init
@@ -447,14 +510,14 @@ Examples:
447
510
  hint: Run \`miaoda db migration diff\` to view pending changes.
448
511
  `);
449
512
  migrationCmd
450
- .command("diff")
451
- .summary("预览 dev → online 待发布变更")
452
- .description("预览 dev → online 的待发布变更。只读预览,不会实际发布。")
453
- .usage("[flags]")
513
+ .command('diff')
514
+ .summary('预览 dev → online 待发布变更')
515
+ .description('预览 dev → online 的待发布变更。只读预览,不会实际发布。')
516
+ .usage('[flags]')
454
517
  .action(async function () {
455
518
  await (0, index_1.handleDbMigrationDiff)(this.optsWithGlobals());
456
519
  })
457
- .addHelpText("after", `
520
+ .addHelpText('after', `
458
521
  Examples:
459
522
  $ miaoda db migration diff
460
523
  dev → online (2 changes):
@@ -462,8 +525,18 @@ Examples:
462
525
  ALTER TABLE users ADD COLUMN avatar_url text;
463
526
  CREATE INDEX idx_users_avatar ON users(avatar_url);
464
527
 
465
- # JSON
528
+ # --json
466
529
  $ miaoda db migration diff --json
530
+ {
531
+ "data": {
532
+ "from": "dev",
533
+ "to": "online",
534
+ "changes": [
535
+ {"type": "ALTER_TABLE", "table": "users", "statement": "ALTER TABLE users ADD COLUMN avatar_url text;"},
536
+ {"type": "CREATE_INDEX", "table": "users", "statement": "CREATE INDEX idx_users_avatar ON users(avatar_url);"}
537
+ ]
538
+ }
539
+ }
467
540
 
468
541
  # 报错:无待发布变更
469
542
  $ miaoda db migration diff
@@ -476,15 +549,15 @@ Examples:
476
549
  hint: Run \`miaoda db migration init\` to set up multi-env first.
477
550
  `);
478
551
  migrationCmd
479
- .command("apply")
480
- .summary("将 dev 的变更发布到 online(单事务原子)")
481
- .description("将 dev 的变更发布到 online。")
482
- .usage("[flags]")
483
- .option("-y, --yes", "跳过确认提示直接执行")
552
+ .command('apply')
553
+ .summary('将 dev 的变更发布到 online(单事务原子)')
554
+ .description('将 dev 的变更发布到 online。')
555
+ .usage('[flags]')
556
+ .option('-y, --yes', '跳过确认提示直接执行')
484
557
  .action(async function () {
485
558
  await (0, index_1.handleDbMigrationApply)(this.optsWithGlobals());
486
559
  })
487
- .addHelpText("after", `
560
+ .addHelpText('after', `
488
561
  Notes:
489
562
  - 该操作会直接改动线上数据库,建议先用 \`migration diff\` 确认变更。
490
563
  - 变更以单事务执行:多条 DDL 任何一条失败整批回滚,online 保持原状态。
@@ -500,9 +573,20 @@ Examples:
500
573
  $ miaoda db migration apply --yes
501
574
  ✓ Applied dev → online (2 changes)
502
575
 
503
- # JSON
576
+ # non-TTY
577
+ $ miaoda db migration apply --yes | cat
578
+ OK Applied dev -> online (2 changes)
579
+
580
+ # --json
504
581
  $ miaoda db migration apply --yes --json
505
- {"data": {"status": "applied", "from": "dev", "to": "online", "changes_applied": 2}}
582
+ {
583
+ "data": {
584
+ "status": "applied",
585
+ "from": "dev",
586
+ "to": "online",
587
+ "changes_applied": 2
588
+ }
589
+ }
506
590
 
507
591
  # 报错:无待发布变更
508
592
  $ miaoda db migration apply
@@ -516,23 +600,23 @@ Examples:
516
600
  `);
517
601
  // ── recovery(PITR)──
518
602
  const recoveryCmd = dbCmd
519
- .command("recovery")
520
- .summary("基于时间点恢复(PITR)")
521
- .description("把数据库整体恢复到指定时间点,diff 预览影响范围,apply 不可逆覆盖。")
522
- .usage("<command> [flags]");
603
+ .command('recovery')
604
+ .summary('基于时间点恢复(PITR)')
605
+ .description('把数据库整体恢复到指定时间点,diff 预览影响范围,apply 不可逆覆盖。')
606
+ .usage('<command> [flags]');
523
607
  recoveryCmd.action(() => {
524
608
  recoveryCmd.outputHelp();
525
609
  });
526
610
  recoveryCmd
527
- .command("diff")
528
- .summary("预览恢复到指定时间点的影响范围")
529
- .description("预览恢复到指定时间点的影响范围(受影响的表、数据变更量、预计耗时)。只读预览,不改动数据。")
530
- .usage("<timestamp> [flags]")
531
- .argument("<timestamp>", "目标时间,YYYY-MM-DD 或 ISO 8601(如 2026-04-15T10:00:00Z)")
611
+ .command('diff')
612
+ .summary('预览恢复到指定时间点的影响范围')
613
+ .description('预览恢复到指定时间点的影响范围(受影响的表、数据变更量、预计耗时)。只读预览,不改动数据。')
614
+ .usage('<timestamp> [flags]')
615
+ .argument('<timestamp>', '目标时间')
532
616
  .action(async function (target) {
533
617
  await (0, index_1.handleDbRecoveryDiff)(target, this.optsWithGlobals());
534
618
  })
535
- .addHelpText("after", `
619
+ .addHelpText('after', `
536
620
  Notes:
537
621
  - 超出可恢复窗口的时间点会报错,错误信息中会标注当前可恢复窗口。
538
622
 
@@ -555,8 +639,19 @@ Examples:
555
639
  orders table will be restored (was dropped at 10:25:00)
556
640
  estimated_time 30
557
641
 
558
- # JSON
642
+ # --json
559
643
  $ miaoda db recovery diff 2026-04-15T10:00:00Z --json
644
+ {
645
+ "data": {
646
+ "target": "2026-04-15T10:00:00Z",
647
+ "tables_affected": 2,
648
+ "changes": [
649
+ {"table": "users", "inserted": 3, "deleted": 1, "modified": 5},
650
+ {"table": "orders", "action": "restore_table", "dropped_at": "2026-04-15T10:25:00Z"}
651
+ ],
652
+ "estimated_seconds": 30
653
+ }
654
+ }
560
655
 
561
656
  # 无变更(目标时间点与当前状态一致)
562
657
  $ miaoda db recovery diff 2026-04-15T14:00:00Z
@@ -568,23 +663,20 @@ Examples:
568
663
  $ miaoda db recovery diff 2026-04-05T10:00:00Z
569
664
  Error: Timestamp is outside the recoverable window
570
665
  hint: Current recoverable window: 2026-04-09T12:00:00Z ~ 2026-04-16T12:00:00Z
666
+ (limited by last migration apply at 2026-04-09T12:00:00Z)
571
667
 
572
- # 时间格式错误
573
- $ miaoda db recovery diff 2026/04/15
574
- Error: Invalid timestamp format '2026/04/15'
575
- hint: Use ISO 8601 format, e.g. 2026-04-15 or 2026-04-15T10:00:00Z
576
668
  `);
577
669
  recoveryCmd
578
- .command("apply")
579
- .summary("将数据库恢复到指定时间点的状态")
580
- .description("将数据库恢复到指定时间点的状态。")
581
- .usage("<timestamp> [flags]")
582
- .argument("<timestamp>", "目标时间,YYYY-MM-DD 或 ISO 8601(如 2026-04-15T10:00:00Z)")
583
- .option("-y, --yes", "跳过确认提示直接执行")
670
+ .command('apply')
671
+ .summary('将数据库恢复到指定时间点的状态')
672
+ .description('将数据库恢复到指定时间点的状态。')
673
+ .usage('<timestamp> [flags]')
674
+ .argument('<timestamp>', '目标时间')
675
+ .option('-y, --yes', '跳过确认提示直接执行')
584
676
  .action(async function (target) {
585
677
  await (0, index_1.handleDbRecoveryApply)(target, this.optsWithGlobals());
586
678
  })
587
- .addHelpText("after", `
679
+ .addHelpText('after', `
588
680
  Notes:
589
681
  - 该操作会覆盖当前数据且不可撤销,建议先用 \`recovery diff\` 预览影响。
590
682
  - 恢复过程是原子的:中途失败时数据库回到操作前的状态,不会出现部分恢复。
@@ -598,9 +690,22 @@ Examples:
598
690
 
599
691
  # --yes 跳过确认
600
692
  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes
693
+ ✓ Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
694
+
695
+ # non-TTY
696
+ $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes | cat
697
+ OK Database restored to 2026-04-15T10:00:00Z (2 tables affected, 30s elapsed)
601
698
 
602
- # JSON
699
+ # --json
603
700
  $ miaoda db recovery apply 2026-04-15T10:00:00Z --yes --json
701
+ {
702
+ "data": {
703
+ "status": "restored",
704
+ "target": "2026-04-15T10:00:00Z",
705
+ "tables_affected": 2,
706
+ "elapsed_seconds": 30
707
+ }
708
+ }
604
709
 
605
710
  # 超出可恢复窗口
606
711
  $ miaoda db recovery apply 2026-04-05T10:00:00Z
@@ -611,25 +716,25 @@ Examples:
611
716
  # 并发冲突(已有恢复任务在执行)
612
717
  $ miaoda db recovery apply 2026-04-15T10:00:00Z
613
718
  Error: Another recovery is already in progress
614
- hint: Wait for the current recovery to finish.
719
+ hint: Wait for the current recovery to finish. Started at 2026-04-16T12:30:00Z.
615
720
  `);
616
721
  // ── quota ──
617
722
  dbCmd
618
- .command("quota")
619
- .summary("查看数据库的存储用量与限额")
620
- .description("查看数据库的存储用量、配额和表数量。")
621
- .usage("[flags]")
723
+ .command('quota')
724
+ .summary('查看数据库的存储用量与限额')
725
+ .description('查看数据库的存储用量、配额和表数量。')
726
+ .usage('[flags]')
622
727
  .action(async function () {
623
728
  await (0, index_1.handleDbQuota)(this.optsWithGlobals());
624
729
  })
625
- .addHelpText("after", `
730
+ .addHelpText('after', `
626
731
  Examples:
627
732
  $ miaoda db quota
628
733
  Storage: 14.9 MB / 1 GB (1.5%)
629
734
  Tables: 3
630
735
  Views: 10
631
736
 
632
- # JSON
737
+ # --json
633
738
  $ miaoda db quota --json
634
739
  {
635
740
  "data": {