@autocodeflow/cli 1.6.0 → 1.8.0

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.
@@ -2,7 +2,8 @@ import { Command } from 'commander';
2
2
  import Table from 'cli-table3';
3
3
  import chalk from 'chalk';
4
4
  import ora from 'ora';
5
- import { get, formatApiError } from '../client.js';
5
+ import { get } from '../client.js';
6
+ import { emitError } from '../ui.js';
6
7
  export function sopCommand() {
7
8
  const cmd = new Command('sop').description('Inspect SOP definitions');
8
9
  // acf sop list
@@ -11,6 +12,8 @@ export function sopCommand() {
11
12
  .option('--status <status>', 'Filter by SOP status (draft | published | deprecated)')
12
13
  .option('-p, --page <n>', 'Page number', '1')
13
14
  .option('-n, --page-size <n>', 'Page size (max 100)', '20')
15
+ // --json 补面(本轮 UX 统一):对齐 audit list 的信封直出口径
16
+ .option('--json', 'Emit raw JSON (CI-consumable, no table)')
14
17
  .action(async (opts) => {
15
18
  const spinner = ora('Fetching SOPs…').start();
16
19
  try {
@@ -20,6 +23,10 @@ export function sopCommand() {
20
23
  status: opts.status,
21
24
  });
22
25
  spinner.stop();
26
+ if (opts.json) {
27
+ console.log(JSON.stringify(data));
28
+ return;
29
+ }
23
30
  const items = data.items ?? [];
24
31
  const table = new Table({
25
32
  head: ['Title', 'Slug', 'Status', 'Version', 'Updated'],
@@ -39,19 +46,23 @@ export function sopCommand() {
39
46
  console.log(chalk.gray(`Total: ${data.total ?? items.length} page ${opts.page}`));
40
47
  }
41
48
  catch (e) {
42
- spinner.fail('Failed to list SOPs');
43
- console.error(chalk.red(formatApiError(e)));
44
- process.exit(1);
49
+ emitError('Failed to list SOPs', e, { spinner });
45
50
  }
46
51
  });
47
52
  // acf sop show <id>
48
53
  cmd.command('show <sopId>')
49
54
  .description('Show one SOP: status, current version and markdown body')
50
- .action(async (sopId) => {
55
+ // --json 补面(本轮 UX 统一):单对象形态 → pretty JSON
56
+ .option('--json', 'Emit raw JSON (CI-consumable, no table)')
57
+ .action(async (sopId, opts) => {
51
58
  const spinner = ora('Fetching SOP…').start();
52
59
  try {
53
60
  const s = await get(`/sop/${sopId}`);
54
61
  spinner.stop();
62
+ if (opts.json) {
63
+ console.log(JSON.stringify(s, null, 2));
64
+ return;
65
+ }
55
66
  console.log(chalk.bold(s.title));
56
67
  console.log(chalk.gray(`slug: ${s.slug} status: ${s.status} version: ${s.currentVersion ?? '-'} updated: ${s.updatedAt ?? '-'}`));
57
68
  if (s.bodyMarkdown) {
@@ -63,9 +74,7 @@ export function sopCommand() {
63
74
  }
64
75
  }
65
76
  catch (e) {
66
- spinner.fail('Failed to show SOP');
67
- console.error(chalk.red(formatApiError(e)));
68
- process.exit(1);
77
+ emitError('Failed to show SOP', e, { spinner });
69
78
  }
70
79
  });
71
80
  return cmd;
@@ -6,7 +6,8 @@ import axios from 'axios';
6
6
  import { spawnSync } from 'child_process';
7
7
  import * as fs from 'fs';
8
8
  import * as path from 'path';
9
- import { get, post, patch, del, formatApiError, ANALYZE_TIMEOUT_MS } from '../client.js';
9
+ import { get, post, patch, del, ANALYZE_TIMEOUT_MS } from '../client.js';
10
+ import { emitError, emitUsageError, UsageError, interruptExit } from '../ui.js';
10
11
  function statusColor(s) {
11
12
  if (s === 'success')
12
13
  return chalk.green(s);
@@ -58,9 +59,7 @@ export function tasksCommand() {
58
59
  console.log(chalk.gray(`Total: ${data.total} page ${data.page}/${Math.ceil(data.total / data.pageSize)}`));
59
60
  }
60
61
  catch (e) {
61
- spinner.fail('Failed to list tasks');
62
- console.error(chalk.red(formatApiError(e)));
63
- process.exit(1);
62
+ emitError('Failed to list tasks', e, { spinner });
64
63
  }
65
64
  });
66
65
  // acf task get <id>
@@ -86,9 +85,7 @@ export function tasksCommand() {
86
85
  console.log(' Cron :', t.cronExpression ?? '-');
87
86
  }
88
87
  catch (e) {
89
- spinner.fail('Failed');
90
- console.error(chalk.red(formatApiError(e)));
91
- process.exit(1);
88
+ emitError('Failed', e, { spinner });
92
89
  }
93
90
  });
94
91
  // acf task trigger <id>
@@ -131,15 +128,15 @@ export function tasksCommand() {
131
128
  }
132
129
  }
133
130
  catch (e) {
134
- spinner.fail('Failed to trigger');
135
- console.error(chalk.red(formatApiError(e)));
136
- process.exit(1);
131
+ emitError('Failed to trigger', e, { spinner });
137
132
  }
138
133
  });
139
134
  // acf task executions <id>
140
135
  cmd.command('executions <id>')
141
136
  .description('List recent executions for a task')
142
137
  .option('-n, --limit <n>', 'Number of results', '10')
138
+ // --json 补面(本轮 UX 统一):对齐 task list 的 ECO-02 CI 消费面
139
+ .option('--json', 'Emit raw JSON (CI-consumable, no table)')
143
140
  .action(async (id, opts) => {
144
141
  const spinner = ora('Fetching executions…').start();
145
142
  try {
@@ -150,6 +147,11 @@ export function tasksCommand() {
150
147
  page: 1,
151
148
  });
152
149
  spinner.stop();
150
+ if (opts.json) {
151
+ // ECO-02 同款:列表/信封形态 → 单行紧凑 JSON(与 task list --json 一致)
152
+ console.log(JSON.stringify(data));
153
+ return;
154
+ }
153
155
  const table = new Table({
154
156
  // U11: exitCode column — distinguishes "failed by callback
155
157
  // report" (exit 0 / null) from "process died" (non-zero).
@@ -169,9 +171,7 @@ export function tasksCommand() {
169
171
  console.log(table.toString());
170
172
  }
171
173
  catch (e) {
172
- spinner.fail('Failed');
173
- console.error(chalk.red(formatApiError(e)));
174
- process.exit(1);
174
+ emitError('Failed', e, { spinner });
175
175
  }
176
176
  });
177
177
  // acf task logs <execId>
@@ -222,9 +222,7 @@ export function tasksCommand() {
222
222
  }
223
223
  }
224
224
  catch (e) {
225
- spinner.fail('Failed to fetch logs');
226
- console.error(chalk.red(formatApiError(e)));
227
- process.exit(1);
225
+ emitError('Failed to fetch logs', e, { spinner });
228
226
  }
229
227
  });
230
228
  // acf task analyze <taskId> <execId>
@@ -241,9 +239,7 @@ export function tasksCommand() {
241
239
  console.log(result.aiAnalysis || 'No analysis available (AI not configured).');
242
240
  }
243
241
  catch (e) {
244
- spinner.fail('Analysis failed');
245
- console.error(chalk.red(formatApiError(e)));
246
- process.exit(1);
242
+ emitError('Analysis failed', e, { spinner });
247
243
  }
248
244
  });
249
245
  // acf task suggest-schedule <id>
@@ -262,38 +258,46 @@ export function tasksCommand() {
262
258
  console.log(result.reasoning);
263
259
  }
264
260
  catch (e) {
265
- spinner.fail('Failed');
266
- console.error(chalk.red(formatApiError(e)));
267
- process.exit(1);
261
+ emitError('Failed', e, { spinner });
268
262
  }
269
263
  });
270
264
  // acf task stats <id>
271
265
  cmd.command('stats <id>')
272
266
  .description('Show execution statistics for a task')
273
- .action(async (id) => {
267
+ // --json 补面(本轮 UX 统一):单对象形态 → pretty JSON(与 task get --json 一致)
268
+ .option('--json', 'Emit raw JSON (CI-consumable, no table)')
269
+ .action(async (id, opts) => {
274
270
  const spinner = ora('Fetching stats…').start();
275
271
  try {
276
272
  const s = await get(`/tasks/${id}/stats`);
277
273
  spinner.stop();
274
+ if (opts.json) {
275
+ console.log(JSON.stringify(s, null, 2));
276
+ return;
277
+ }
278
278
  console.log(chalk.bold('Execution Stats'));
279
279
  console.log(` Success rate : ${chalk.green(s.successRate + '%')}`);
280
280
  console.log(` Avg duration : ${s.avgDuration}ms`);
281
281
  console.log(` Total runs : ${s.totalRuns}`);
282
282
  }
283
283
  catch (e) {
284
- spinner.fail('Failed');
285
- console.error(chalk.red(formatApiError(e)));
286
- process.exit(1);
284
+ emitError('Failed', e, { spinner });
287
285
  }
288
286
  });
289
287
  // acf task versions <id>
290
288
  cmd.command('versions <id>')
291
289
  .description('List historical versions of a task')
292
- .action(async (id) => {
290
+ // --json 补面(本轮 UX 统一):rollback/compare 前先拿 versionId 的脚本消费面
291
+ .option('--json', 'Emit raw JSON (CI-consumable, no table)')
292
+ .action(async (id, opts) => {
293
293
  const spinner = ora('Fetching task versions…').start();
294
294
  try {
295
295
  const versions = await get(`/tasks/${id}/versions`);
296
296
  spinner.stop();
297
+ if (opts.json) {
298
+ console.log(JSON.stringify(versions, null, 2));
299
+ return;
300
+ }
297
301
  const table = new Table({
298
302
  head: ['Version', 'Commit', 'Created By', 'Created', 'Description'],
299
303
  colWidths: [12, 14, 16, 25, 30],
@@ -311,9 +315,7 @@ export function tasksCommand() {
311
315
  console.log(table.toString());
312
316
  }
313
317
  catch (e) {
314
- spinner.fail('Failed to list versions');
315
- console.error(chalk.red(formatApiError(e)));
316
- process.exit(1);
318
+ emitError('Failed to list versions', e, { spinner });
317
319
  }
318
320
  });
319
321
  // acf task rollback <id>
@@ -328,19 +330,23 @@ export function tasksCommand() {
328
330
  console.log(chalk.gray(` name: ${t.name} status: ${statusColor(t.status)}`));
329
331
  }
330
332
  catch (e) {
331
- spinner.fail('Failed to roll back');
332
- console.error(chalk.red(formatApiError(e)));
333
- process.exit(1);
333
+ emitError('Failed to roll back', e, { spinner });
334
334
  }
335
335
  });
336
336
  // acf task compare <id> <versionId1> <versionId2>
337
337
  cmd.command('compare <id> <versionId1> <versionId2>')
338
338
  .description('Diff two task versions (shows fields whose values differ)')
339
- .action(async (id, versionId1, versionId2) => {
339
+ // --json 补面(本轮 UX 统一):diff 记录直出,脚本可断言具体字段
340
+ .option('--json', 'Emit raw JSON (CI-consumable, no table)')
341
+ .action(async (id, versionId1, versionId2, opts) => {
340
342
  const spinner = ora('Comparing versions…').start();
341
343
  try {
342
344
  const diff = await get(`/tasks/${id}/versions/${versionId1}/compare/${versionId2}`);
343
345
  spinner.stop();
346
+ if (opts.json) {
347
+ console.log(JSON.stringify(diff ?? {}, null, 2));
348
+ return;
349
+ }
344
350
  const keys = Object.keys(diff ?? {});
345
351
  if (keys.length === 0) {
346
352
  console.log(chalk.green('No differences between the two versions.'));
@@ -362,9 +368,7 @@ export function tasksCommand() {
362
368
  console.log(table.toString());
363
369
  }
364
370
  catch (e) {
365
- spinner.fail('Failed to compare versions');
366
- console.error(chalk.red(formatApiError(e)));
367
- process.exit(1);
371
+ emitError('Failed to compare versions', e, { spinner });
368
372
  }
369
373
  });
370
374
  // acf task create
@@ -377,10 +381,22 @@ export function tasksCommand() {
377
381
  const spinner = ora('Creating task…').start();
378
382
  try {
379
383
  const fs = await import('fs/promises');
380
- const raw = opts.file
381
- ? await fs.readFile(opts.file, 'utf-8')
382
- : opts.json;
383
- const body = JSON.parse(raw);
384
+ // 本地 payload 层错误(文件读不了/JSON 坏)= 用法错误(退出码 2),
385
+ // 与服务端拒绝(1)区分;口径与 apps.ts 的 loadJsonBody 一致。
386
+ let raw;
387
+ try {
388
+ raw = opts.file ? await fs.readFile(opts.file, 'utf-8') : opts.json;
389
+ }
390
+ catch (err) {
391
+ throw new UsageError(`Cannot read payload file: ${opts.file} (${err instanceof Error ? err.message : String(err)})`);
392
+ }
393
+ let body;
394
+ try {
395
+ body = JSON.parse(raw);
396
+ }
397
+ catch (err) {
398
+ throw new UsageError(`Invalid JSON payload: ${err instanceof Error ? err.message : String(err)}`);
399
+ }
384
400
  // R7 (N20): 显式 --executor 覆盖/补写 body.executorId(pinning)。
385
401
  if (opts.executor)
386
402
  body.executorId = opts.executor;
@@ -389,9 +405,7 @@ export function tasksCommand() {
389
405
  console.log(chalk.gray(` name: ${t.name} status: ${statusColor(t.status)}`));
390
406
  }
391
407
  catch (e) {
392
- spinner.fail('Failed to create task');
393
- console.error(chalk.red(formatApiError(e)));
394
- process.exit(1);
408
+ emitError('Failed to create task', e, { spinner });
395
409
  }
396
410
  });
397
411
  // acf task update <id>
@@ -404,10 +418,22 @@ export function tasksCommand() {
404
418
  const spinner = ora('Updating task…').start();
405
419
  try {
406
420
  const fs = await import('fs/promises');
407
- const raw = opts.file
408
- ? await fs.readFile(opts.file, 'utf-8')
409
- : opts.json;
410
- const body = JSON.parse(raw);
421
+ // 本地 payload 层错误(文件读不了/JSON 坏)= 用法错误(退出码 2),
422
+ // 与服务端拒绝(1)区分;口径与 apps.ts 的 loadJsonBody 一致。
423
+ let raw;
424
+ try {
425
+ raw = opts.file ? await fs.readFile(opts.file, 'utf-8') : opts.json;
426
+ }
427
+ catch (err) {
428
+ throw new UsageError(`Cannot read payload file: ${opts.file} (${err instanceof Error ? err.message : String(err)})`);
429
+ }
430
+ let body;
431
+ try {
432
+ body = JSON.parse(raw);
433
+ }
434
+ catch (err) {
435
+ throw new UsageError(`Invalid JSON payload: ${err instanceof Error ? err.message : String(err)}`);
436
+ }
411
437
  // R7 (N20): 显式 --executor 覆盖/补写 body.executorId(pinning)。
412
438
  if (opts.executor)
413
439
  body.executorId = opts.executor;
@@ -416,9 +442,7 @@ export function tasksCommand() {
416
442
  console.log(chalk.gray(` name: ${t.name} status: ${statusColor(t.status)}`));
417
443
  }
418
444
  catch (e) {
419
- spinner.fail('Failed to update task');
420
- console.error(chalk.red(formatApiError(e)));
421
- process.exit(1);
445
+ emitError('Failed to update task', e, { spinner });
422
446
  }
423
447
  });
424
448
  // acf task delete <id>
@@ -429,6 +453,9 @@ export function tasksCommand() {
429
453
  if (!opts.yes) {
430
454
  const readline = await import('readline/promises');
431
455
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
456
+ // raw 模式下 Ctrl+C 触发 rl 'SIGINT' 而非进程信号;无监听只会 pause,
457
+ // 确认提示处会假死。接住并走统一中断出口(130)。
458
+ rl.on('SIGINT', () => interruptExit());
432
459
  const answer = await rl.question(`Delete task ${id}? Running executions will be force-terminated. [y/N] `);
433
460
  rl.close();
434
461
  if (!/^y(es)?$/i.test(answer)) {
@@ -442,9 +469,7 @@ export function tasksCommand() {
442
469
  spinner.succeed(`Task ${id} deleted`);
443
470
  }
444
471
  catch (e) {
445
- spinner.fail('Failed to delete task');
446
- console.error(chalk.red(formatApiError(e)));
447
- process.exit(1);
472
+ emitError('Failed to delete task', e, { spinner });
448
473
  }
449
474
  });
450
475
  // acf task pause <id>
@@ -458,9 +483,7 @@ export function tasksCommand() {
458
483
  console.log(chalk.gray(` status: ${statusColor(t.status)}`));
459
484
  }
460
485
  catch (e) {
461
- spinner.fail('Failed to pause task');
462
- console.error(chalk.red(formatApiError(e)));
463
- process.exit(1);
486
+ emitError('Failed to pause task', e, { spinner });
464
487
  }
465
488
  });
466
489
  // acf task resume <id>
@@ -474,9 +497,7 @@ export function tasksCommand() {
474
497
  console.log(chalk.gray(` status: ${statusColor(t.status)}`));
475
498
  }
476
499
  catch (e) {
477
- spinner.fail('Failed to resume task');
478
- console.error(chalk.red(formatApiError(e)));
479
- process.exit(1);
500
+ emitError('Failed to resume task', e, { spinner });
480
501
  }
481
502
  });
482
503
  // acf task kill <taskId> <execId>
@@ -489,9 +510,7 @@ export function tasksCommand() {
489
510
  spinner.succeed(r.message || 'Execution cancelled');
490
511
  }
491
512
  catch (e) {
492
- spinner.fail('Failed to cancel execution');
493
- console.error(chalk.red(formatApiError(e)));
494
- process.exit(1);
513
+ emitError('Failed to cancel execution', e, { spinner });
495
514
  }
496
515
  });
497
516
  // ECO-02: acf task lint <file> —— 本地语法检查(node: 语法编译不执行;
@@ -506,8 +525,8 @@ export function tasksCommand() {
506
525
  source = fs.readFileSync(file, 'utf-8');
507
526
  }
508
527
  catch {
509
- console.error(chalk.red(`Cannot read file: ${file}`));
510
- process.exit(1);
528
+ // 本地参数/文件层错误 → 用法错误(退出码 2),与服务端拒绝(1)区分。
529
+ emitUsageError(`Cannot read file: ${file}`);
511
530
  }
512
531
  const ext = path.extname(file).toLowerCase();
513
532
  const lang = opts.language ??
@@ -519,8 +538,7 @@ export function tasksCommand() {
519
538
  ? 'shell'
520
539
  : undefined);
521
540
  if (!lang) {
522
- console.error(chalk.red(`Cannot infer language from extension "${ext}" — pass --language node|python|shell`));
523
- process.exit(1);
541
+ emitUsageError(`Cannot infer language from extension "${ext}" — pass --language node|python|shell`);
524
542
  }
525
543
  const ok = (msg) => {
526
544
  console.log(chalk.green(`✔ ${file}: ${msg}`));
@@ -623,9 +641,9 @@ async function pollExecution(execId, waitTimeoutSeconds = 600) {
623
641
  // 空转到 MAX_WAIT 并误报超时,掩盖真实错误;立即退出并透出后端消息。
624
642
  const status = axios.isAxiosError(e) ? e.response?.status : undefined;
625
643
  if (status && status >= 400 && status < 500 && status !== 429) {
626
- spinner.fail('Waiting for execution failed');
627
- console.error(chalk.red(formatApiError(e)));
628
- process.exit(1);
644
+ // 统一错误出口:4xx 按类别映射退出码(401→3、其余→1),网络/5xx 继续
645
+ // 轮询(下方 transient 分支)。
646
+ emitError('Waiting for execution failed', e, { spinner });
629
647
  }
630
648
  // transient (network / 429 / 5xx), keep polling
631
649
  }
package/dist/config.js CHANGED
@@ -17,6 +17,7 @@
17
17
  */
18
18
  import Conf from 'conf';
19
19
  import * as fs from 'fs';
20
+ import chalk from 'chalk';
20
21
  /** Owner-only (rw-------). Mirrors the private-credential intent of ADR-012. */
21
22
  const CONFIG_FILE_MODE = 0o600;
22
23
  /**
@@ -32,6 +33,14 @@ const configDir = process.env.ACF_CONFIG_DIR;
32
33
  * contention in tests, read-only mounts) the constructor can throw. Fall back to
33
34
  * a mode-less store rather than crashing the CLI — `hardenConfigPermissions()`
34
35
  * repairs the on-disk mode separately when the platform allows it.
36
+ *
37
+ * UX 打磨(本轮):mode-less 兜底仍失败时只有两种现实解释——
38
+ * 1. 配置文件损坏(conf 构造时反序列化,坏 JSON 直接抛裸 SyntaxError 堆栈,
39
+ * 用户看不到任何可操作指引);
40
+ * 2. 存储位置读写不了(只读挂载等)。
41
+ * 借 `deserialize` 钩子在 conf 抛出前把坏内容留证:确属损坏则备份坏内容、
42
+ * 告警并携默认配置继续 CLI(凭据可从备份手工找回,或 acf login 重登);
43
+ * 否则抛出带指引的错误,替代 conf 内部堆栈。
35
44
  */
36
45
  function createStore() {
37
46
  const base = {
@@ -50,11 +59,65 @@ function createStore() {
50
59
  refreshToken: '',
51
60
  },
52
61
  };
62
+ // conf 用 clearInvalidConfig 兜损坏时会「静默」返回空对象并在构造期把坏文件
63
+ // 覆写成 defaults——凭据无提示丢失。因此不用它做常规路径,只在已留证坏内容
64
+ // 之后的恢复存储上启用(那时覆写无妨,坏内容已在内存里)。
65
+ let corruptRaw = null;
66
+ const withDeserialize = {
67
+ ...base,
68
+ deserialize: (value) => {
69
+ try {
70
+ return JSON.parse(value);
71
+ }
72
+ catch {
73
+ corruptRaw = value;
74
+ throw new SyntaxError('config file is not valid JSON');
75
+ }
76
+ },
77
+ };
53
78
  try {
54
- return new Conf({ ...base, configFileMode: CONFIG_FILE_MODE });
79
+ return new Conf({ ...withDeserialize, configFileMode: CONFIG_FILE_MODE });
55
80
  }
56
81
  catch {
57
- return new Conf(base);
82
+ try {
83
+ return new Conf(withDeserialize);
84
+ }
85
+ catch {
86
+ if (corruptRaw === null) {
87
+ // 反序列化没被触发 → 不是坏 JSON,而是存储位置本身读写不了。
88
+ throw new Error('Cannot initialize the CLI config store (permission or IO problem). ' +
89
+ 'Set ACF_CONFIG_DIR to a writable directory and retry.');
90
+ }
91
+ // 损坏恢复:坏内容已留证;此时 conf 的常规构造必然再抛,改用
92
+ // clearInvalidConfig 让这次构造成功(原文件被覆写也无妨),随后把
93
+ // 留证内容写到 <path>.corrupt,用户随时可手工找回旧凭据。
94
+ try {
95
+ const recovered = new Conf({
96
+ ...withDeserialize,
97
+ configFileMode: CONFIG_FILE_MODE,
98
+ clearInvalidConfig: true,
99
+ });
100
+ const backupPath = `${recovered.path}.corrupt`;
101
+ try {
102
+ fs.writeFileSync(backupPath, corruptRaw, { mode: CONFIG_FILE_MODE });
103
+ process.stderr.write(chalk.yellow(`⚠ Config file is corrupted: ${recovered.path}\n` +
104
+ ' (invalid JSON — the CLI cannot read its own credentials from it.)\n' +
105
+ ` The previous content was preserved at ${backupPath}; inspect it if you need the old credentials.\n` +
106
+ ' Continuing with default settings. Run "acf login" to sign in again.\n'));
107
+ }
108
+ catch {
109
+ process.stderr.write(chalk.yellow(`⚠ Config file is corrupted: ${recovered.path} (invalid JSON), and the backup could not be written.\n` +
110
+ ' Continuing with default settings. Run "acf login" to sign in again.\n'));
111
+ }
112
+ return recovered;
113
+ }
114
+ catch (err) {
115
+ // 连恢复存储都建不出来(目录读写不了):给出可操作指引而非裸堆栈。
116
+ throw new Error('Cannot initialize the CLI config store (permission or IO problem). ' +
117
+ `Underlying error: ${err instanceof Error ? err.message : String(err)}. ` +
118
+ 'Set ACF_CONFIG_DIR to a writable directory and retry.');
119
+ }
120
+ }
58
121
  }
59
122
  }
60
123
  const store = createStore();
package/dist/help.d.ts ADDED
@@ -0,0 +1,21 @@
1
+ /**
2
+ * 集中式 help 体系:全 CLI 的命令示例表。
3
+ *
4
+ * 为什么集中:commander 15 已提供层级 help(用途一行 = description、参数表 =
5
+ * usage/options、逐级 --help),这部分直接收编、不重造。缺的只有「每个命令
6
+ * 至少一个示例」——若散在各命令文件里用 addHelpText 拼接,永远查不齐、也没法
7
+ * 守卫。这里用一张以命令路径为键的表('task list' → 示例行数组),由
8
+ * `applyExamples` 在 index.ts 的命令分发处统一走树注入,src/__tests__/
9
+ * ux-uniform.test.ts 再用真实命令树断言「每个叶子命令都有 Examples 块」——
10
+ * 新增命令忘写示例会直接红。
11
+ *
12
+ * 键约定:空串 = 顶层 acf;其余为 'login'、'task list' 这样的空格分隔路径。
13
+ */
14
+ import type { Command } from 'commander';
15
+ export declare const EXAMPLES: Record<string, string[]>;
16
+ /**
17
+ * Walk the whole command tree and attach the matching Examples block to every
18
+ * command that has one (leaf commands and the root). Called once from index.ts
19
+ * after all commands are registered — the single wiring point.
20
+ */
21
+ export declare function applyExamples(program: Command): void;
package/dist/help.js ADDED
@@ -0,0 +1,105 @@
1
+ export const EXAMPLES = {
2
+ '': [
3
+ 'acf login',
4
+ 'acf task trigger <taskId> --wait',
5
+ 'acf exec tail <execId>',
6
+ ],
7
+ login: [
8
+ 'acf login',
9
+ 'acf login --url https://acf.example.com --user admin',
10
+ 'ACF_PASSWORD=... acf login --user admin # CI: password via env, not argv',
11
+ ],
12
+ 'task list': [
13
+ 'acf task list --status active --page 1',
14
+ 'acf task list --json',
15
+ ],
16
+ 'task get': ['acf task get <taskId>', 'acf task get <taskId> --json'],
17
+ 'task trigger': [
18
+ 'acf task trigger <taskId> --wait --wait-timeout 900',
19
+ ],
20
+ 'task executions': [
21
+ 'acf task executions <taskId> -n 5',
22
+ 'acf task executions <taskId> --json',
23
+ ],
24
+ 'task logs': [
25
+ 'acf task logs <execId> --tail 100',
26
+ 'acf task logs <execId> --from-line 200 -n 100',
27
+ ],
28
+ 'task analyze': ['acf task analyze <taskId> <execId>'],
29
+ 'task suggest-schedule': ['acf task suggest-schedule <taskId>'],
30
+ 'task stats': ['acf task stats <taskId> --json'],
31
+ 'task versions': ['acf task versions <taskId> --json'],
32
+ 'task rollback': [
33
+ 'acf task rollback <taskId> --version <versionId> # versionId from: acf task versions <taskId>',
34
+ ],
35
+ 'task compare': ['acf task compare <taskId> <versionId1> <versionId2>'],
36
+ 'task create': [
37
+ 'acf task create --file task.json # required: name, version, runtime, triggerType',
38
+ "acf task create --json '{\"name\":\"nightly\",\"version\":\"1.0.0\",\"runtime\":\"node\",\"triggerType\":\"cron\",\"cronExpression\":\"0 2 * * *\"}'",
39
+ ],
40
+ 'task update': ['acf task update <taskId> --file patch.json'],
41
+ 'task delete': ['acf task delete <taskId> -y'],
42
+ 'task pause': ['acf task pause <taskId>'],
43
+ 'task resume': ['acf task resume <taskId>'],
44
+ 'task kill': ['acf task kill <taskId> <execId>'],
45
+ 'task lint': [
46
+ 'acf task lint glue.js',
47
+ 'acf task lint script.py --language python',
48
+ ],
49
+ 'app list': ['acf app list', 'acf app list --json'],
50
+ 'app get': ['acf app get <appId> --json'],
51
+ 'app create': [
52
+ 'acf app create --file app.json # required: name, version, runtime',
53
+ ],
54
+ 'app update': [
55
+ 'acf app update <appId> --json \'{"version":"2.0.0"}\' # renaming is not supported by the backend',
56
+ ],
57
+ 'app delete': ['acf app delete <appId> -y'],
58
+ 'app analyze': ['acf app analyze <appId>'],
59
+ 'app deploy': [
60
+ "acf app deploy <appId> -e <executorId> -m daemon --env '{\"KEY\":\"value\"}'",
61
+ ],
62
+ 'app deployments': ['acf app deployments <appId> -n 50 --json'],
63
+ 'app versions': ['acf app versions <appId> --json'],
64
+ 'executor list': ['acf executor list', 'acf executor list --json'],
65
+ 'executor get': ['acf executor get <executorId> --json'],
66
+ 'executor rotate': [
67
+ 'acf executor rotate executor-node --reason "quarterly rotation"',
68
+ ],
69
+ 'executor offline': ['acf executor offline executor-node'],
70
+ 'deploy upgrade': ['acf deploy upgrade <deploymentId>'],
71
+ 'deploy stop': ['acf deploy stop <deploymentId>'],
72
+ 'audit list': [
73
+ 'acf audit list --action task.trigger --start-time 2026-01-01T00:00:00Z',
74
+ 'acf audit list --json',
75
+ ],
76
+ 'exec tail': ['acf exec tail <execId>', 'acf exec tail <execId> --json'],
77
+ 'project list': ['acf project list', 'acf project list --json'],
78
+ 'project members': ['acf project members <projectId> --json'],
79
+ 'sop list': ['acf sop list --status published', 'acf sop list --json'],
80
+ 'sop show': ['acf sop show <sopId> --json'],
81
+ 'agent sessions': [
82
+ 'acf agent sessions --status waiting_input',
83
+ 'acf agent sessions --json',
84
+ ],
85
+ 'config show': ['acf config show'],
86
+ 'config set-url': ['acf config set-url http://localhost:3105'],
87
+ 'config set-token': ['acf config set-token <token> # prefer: acf login'],
88
+ };
89
+ /**
90
+ * Walk the whole command tree and attach the matching Examples block to every
91
+ * command that has one (leaf commands and the root). Called once from index.ts
92
+ * after all commands are registered — the single wiring point.
93
+ */
94
+ export function applyExamples(program) {
95
+ const walk = (cmd, path) => {
96
+ const lines = EXAMPLES[path];
97
+ if (lines?.length) {
98
+ cmd.addHelpText('after', `\nExamples:\n ${lines.join('\n ')}`);
99
+ }
100
+ for (const sub of cmd.commands) {
101
+ walk(sub, path ? `${path} ${sub.name()}` : sub.name());
102
+ }
103
+ };
104
+ walk(program, '');
105
+ }