@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.
package/dist/index.d.ts CHANGED
@@ -1,2 +1,34 @@
1
1
  #!/usr/bin/env node
2
- export {};
2
+ /**
3
+ * ACF CLI — AutoCodeFlow command-line interface
4
+ *
5
+ * Usage:
6
+ * acf login
7
+ * acf task list
8
+ * acf task trigger <id> --wait
9
+ * acf task versions <id> | compare <id> <v1> <v2> | rollback <id> --version <vid>
10
+ * acf task analyze <taskId> <execId>
11
+ * acf task suggest-schedule <id>
12
+ * acf app list | create | update <id> | delete <id>
13
+ * acf app analyze <id>
14
+ * acf deploy upgrade <deploymentId> | stop <deploymentId>
15
+ * acf executor list | get <id> | rotate <name|id> | offline <name|id>
16
+ * acf exec tail <execId>
17
+ * acf task lint <file>
18
+ * acf audit list
19
+ * acf sop list | show <sopId>
20
+ * acf agent sessions
21
+ * acf config show
22
+ *
23
+ * 退出码表(docs 详见 README.md「Exit codes」,单一事实源在 src/ui.ts 的
24
+ * EXIT_CODES):0 成功;1 运行失败;2 用法/参数错误;3 认证失败;
25
+ * 4 网络失败;130 中断(SIGINT)。
26
+ */
27
+ import { Command } from 'commander';
28
+ export declare const program: Command;
29
+ /**
30
+ * Map a commander parse outcome to the CLI exit code.
31
+ * `--help` / `--version` / `acf help <cmd>` 是用户主动要的正常出口 → 0;
32
+ * 其余解析错误(缺参/未知命令/未知选项/非法取值)= 用法错误 → 2。
33
+ */
34
+ export declare function parseErrorExitCode(e: unknown): number;
package/dist/index.js CHANGED
@@ -19,8 +19,13 @@
19
19
  * acf sop list | show <sopId>
20
20
  * acf agent sessions
21
21
  * acf config show
22
+ *
23
+ * 退出码表(docs 详见 README.md「Exit codes」,单一事实源在 src/ui.ts 的
24
+ * EXIT_CODES):0 成功;1 运行失败;2 用法/参数错误;3 认证失败;
25
+ * 4 网络失败;130 中断(SIGINT)。
22
26
  */
23
- import { Command } from 'commander';
27
+ import { Command, CommanderError } from 'commander';
28
+ import { pathToFileURL } from 'node:url';
24
29
  import chalk from 'chalk';
25
30
  import { loginCommand } from './commands/login.js';
26
31
  import { tasksCommand } from './commands/tasks.js';
@@ -33,6 +38,8 @@ import { projectsCommand } from './commands/projects.js';
33
38
  import { sopCommand } from './commands/sop.js';
34
39
  import { agentCommand } from './commands/agent.js';
35
40
  import { showConfig, setApiUrl, setToken } from './config.js';
41
+ import { applyExamples } from './help.js';
42
+ import { EXIT_CODES, interruptExit } from './ui.js';
36
43
  // 版本号单一事实源:直接读 package.json,而不是硬编码字面量。
37
44
  //
38
45
  // 原实现写死 `.version('1.0.0')`,而 package.json 是 `version-guard` 与
@@ -44,11 +51,16 @@ import { showConfig, setApiUrl, setToken } from './config.js';
44
51
  // 视为 src 之外的输入,故走运行时解析(发布物里 package.json 与 dist/ 同级,
45
52
  // 路径稳定)。本包为 ESM(type: module),JSON 导入须带 import attribute。
46
53
  import pkg from '../package.json' with { type: 'json' };
47
- const program = new Command();
54
+ // 导出命令树供测试复用(结构守卫:每个叶子命令都必须有 Examples)。配合底部
55
+ // 的 main-guard,import 本文件不会触发 parseAsync。
56
+ export const program = new Command();
48
57
  program
49
58
  .name('acf')
50
59
  .description('AutoCodeFlow CLI — manage tasks, executions, applications and projects')
51
60
  .version(pkg.version);
61
+ // ---------------------------------------------------------------------------
62
+ // 解析期行为统一(全树,见下方 applyParseErrorBehavior 的说明)
63
+ // ---------------------------------------------------------------------------
52
64
  // Global options that override stored config
53
65
  program
54
66
  .option('--api-url <url>', 'Override API URL for this invocation (or set ACF_API_URL env var)')
@@ -83,11 +95,62 @@ configCmd.command('set-token <token>').description('Set auth token directly').ac
83
95
  console.log(chalk.green('✔ Token saved'));
84
96
  });
85
97
  program.addCommand(configCmd);
86
- // Better error display
87
- program.configureOutput({
88
- outputError: (str, write) => write(chalk.red(str)),
89
- });
90
- program.parseAsync(process.argv).catch((e) => {
91
- console.error(chalk.red('Error:'), e instanceof Error ? e.message : String(e));
92
- process.exit(1);
93
- });
98
+ // 集中式 help:把 help.ts 的 EXAMPLES 表按命令路径走树注入(每个命令至少一个
99
+ // 示例;覆盖面由 ux-uniform.test.ts 用本树做结构守卫)。
100
+ applyExamples(program);
101
+ /**
102
+ * 解析期行为统一到整棵命令树:
103
+ * - exitOverride:解析错误不再让 commander 内部直接 process.exit(1),而是抛
104
+ * CommanderError 到 runCli 的 catch 统一映射退出码(--help/--version → 0,
105
+ * 其余 → 2 用法错误)。--version 的行为由 release-metadata.test.ts 真实
106
+ * 执行构建产物钉死,改动后跑全量测试即可发现回归。
107
+ * - showHelpAfterError:缺参/未知命令/未知选项时在 error 行之后打印**该命令
108
+ * 的完整 help**(含 Examples)——用户在报错现场就能拿到可操作的用法。
109
+ * - configureOutput:error 行染红。
110
+ *
111
+ * 为什么走树补设而不是只在 program 上设一次:commander 只在 addCommand 时把
112
+ * 这些设置拷贝给**直接子命令**(copyInheritedSettings),而孙子级(task get /
113
+ * config show 等)在各命令工厂函数里创建,早于 addCommand——实测它们拿不到
114
+ * exitOverride,深层缺参错误会绕过退出码映射直接 process.exit(1),error 行也
115
+ * 不染红。在整棵树装配完成后逐命令补设是唯一覆盖全深度的方式。
116
+ */
117
+ function applyParseErrorBehavior(cmd) {
118
+ cmd.exitOverride();
119
+ cmd.showHelpAfterError();
120
+ cmd.configureOutput({
121
+ outputError: (str, write) => write(chalk.red(str)),
122
+ });
123
+ for (const sub of cmd.commands)
124
+ applyParseErrorBehavior(sub);
125
+ }
126
+ applyParseErrorBehavior(program);
127
+ /**
128
+ * Map a commander parse outcome to the CLI exit code.
129
+ * `--help` / `--version` / `acf help <cmd>` 是用户主动要的正常出口 → 0;
130
+ * 其余解析错误(缺参/未知命令/未知选项/非法取值)= 用法错误 → 2。
131
+ */
132
+ export function parseErrorExitCode(e) {
133
+ if (e instanceof CommanderError) {
134
+ return e.exitCode === 0 ? EXIT_CODES.OK : EXIT_CODES.USAGE;
135
+ }
136
+ return EXIT_CODES.GENERIC;
137
+ }
138
+ // 仅当本文件是进程入口时才启动解析。测试需要 import 本文件复用**真实**命令树
139
+ // (example 覆盖守卫不能靠复刻一份会漂移的镜像树),main-guard 让 import 无
140
+ // 副作用;正常执行路径(node dist/index.js、tsx src/index.ts、npm bin)下
141
+ // argv[1] 与本模块 URL 指向同一文件,守卫恒真。
142
+ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
143
+ // SIGINT 统一出口:Ctrl+C 补换行(spinner 帧不留半行)并以 128+SIGINT 惯例
144
+ // 码 130 退出。交互 readline 的 raw 模式不走进程信号,由各 prompt 内的
145
+ // rl.on('SIGINT') 接住后也汇入同一个 interruptExit。
146
+ process.on('SIGINT', () => interruptExit());
147
+ program.parseAsync(process.argv).catch((e) => {
148
+ if (e instanceof CommanderError) {
149
+ // error 行与 help 已由 commander 经 outputError/print 写出,这里只做
150
+ // 退出码映射,不重复打印。
151
+ process.exit(parseErrorExitCode(e));
152
+ }
153
+ console.error(chalk.red('Error:'), e instanceof Error ? e.message : String(e));
154
+ process.exit(EXIT_CODES.GENERIC);
155
+ });
156
+ }
package/dist/ui.d.ts ADDED
@@ -0,0 +1,55 @@
1
+ /**
2
+ * CLI 退出码表(README.md「Exit codes」为同一张表的人读版,两处必须同步改):
3
+ * 0 成功(含 --help / --version)
4
+ * 1 运行失败:服务端拒绝(400/403/404/409/5xx)、失败终态(--wait)、
5
+ * lint 语法错误、非 UsageError 的本地错误
6
+ * 2 用法/参数错误:缺参、未知命令/选项、非法取值(commander 解析层),
7
+ * 以及本地参数派生错误(lint 无法推断语言、JSON payload 解析失败)
8
+ * 3 认证失败:401(凭据缺失/过期且 401 自愈失败)→ 运行 acf login
9
+ * 4 网络失败:连接不通/超时/DNS → 检查 --api-url / ACF_API_URL
10
+ * 130 中断(SIGINT / Ctrl+C,128+2 惯例)
11
+ */
12
+ export declare const EXIT_CODES: {
13
+ readonly OK: 0;
14
+ readonly GENERIC: 1;
15
+ readonly USAGE: 2;
16
+ readonly AUTH: 3;
17
+ readonly NETWORK: 4;
18
+ readonly INTERRUPTED: 130;
19
+ };
20
+ /**
21
+ * 本地参数/负载层面的用法错误。与服务端拒绝区分开,让脚本能区分
22
+ * 「我的命令写错了(2)」和「服务端没答应(1)」。命令层抛出本类型,
23
+ * exitCodeFor 统一识别,不需要每个 catch 各自判断。
24
+ */
25
+ export declare class UsageError extends Error {
26
+ }
27
+ /** spinner 的最小结构面(ora 实例天然满足),避免 ui 层反向依赖 ora。 */
28
+ interface Failable {
29
+ fail(message?: string): unknown;
30
+ }
31
+ /**
32
+ * Map a thrown error to its exit code. `UsageError`(本地用法错误)优先——
33
+ * 它不是 axios 错误,若先走 classifyApiError 会被误归为 GENERIC。
34
+ */
35
+ export declare function exitCodeFor(e: unknown): number;
36
+ /**
37
+ * 统一错误出口。有 spinner 时 `spinner.fail(scope)`(失败行与进行中的转圈
38
+ * 原位收尾);无 spinner 时打 `✗ scope`。错误详情一律走 formatApiError,
39
+ * 保证 401/网络/后端 message 的呈现全 CLI 一致。
40
+ */
41
+ export declare function emitError(scope: string, e: unknown, opts?: {
42
+ spinner?: Failable;
43
+ }): never;
44
+ /**
45
+ * 本地用法错误出口(不涉及 API 调用)。第二条提示固定指向 `--help`——
46
+ * 每个叶子命令的帮助里都有示例,用户不需要去翻文档。
47
+ */
48
+ export declare function emitUsageError(message: string): never;
49
+ /**
50
+ * 中断(SIGINT / Ctrl+C)统一出口:补一个换行让被 spinner/提示符啃掉一半的
51
+ * 输出行完整落地,退出码 130。进程级 handler 与交互 readline 的 raw 模式
52
+ * `rl.on('SIGINT')` 共用这一个出口。
53
+ */
54
+ export declare function interruptExit(): never;
55
+ export {};
package/dist/ui.js ADDED
@@ -0,0 +1,87 @@
1
+ /**
2
+ * Unified terminal-output / exit-code layer for the CLI.
3
+ *
4
+ * 背景:10 个命令文件此前各自复制同一套「spinner.fail → console.error(red) →
5
+ * process.exit(1)」三连(约 40 处),失败类别(认证/网络/服务端/参数)全部挤在
6
+ * 退出码 1 里,CI 无法分类处理。本层把出口收敛为一个帮手:
7
+ * - 错误分类在 client 层做一次(classifyApiError),这里只负责映射退出码;
8
+ * - 人读文案沿用 formatApiError(含后端 message 与「下一步动作」提示);
9
+ * - spinner 的 scope 文案由调用方传入,保持各命令既有的失败措辞。
10
+ */
11
+ import chalk from 'chalk';
12
+ import { classifyApiError, formatApiError } from './client.js';
13
+ /**
14
+ * CLI 退出码表(README.md「Exit codes」为同一张表的人读版,两处必须同步改):
15
+ * 0 成功(含 --help / --version)
16
+ * 1 运行失败:服务端拒绝(400/403/404/409/5xx)、失败终态(--wait)、
17
+ * lint 语法错误、非 UsageError 的本地错误
18
+ * 2 用法/参数错误:缺参、未知命令/选项、非法取值(commander 解析层),
19
+ * 以及本地参数派生错误(lint 无法推断语言、JSON payload 解析失败)
20
+ * 3 认证失败:401(凭据缺失/过期且 401 自愈失败)→ 运行 acf login
21
+ * 4 网络失败:连接不通/超时/DNS → 检查 --api-url / ACF_API_URL
22
+ * 130 中断(SIGINT / Ctrl+C,128+2 惯例)
23
+ */
24
+ export const EXIT_CODES = {
25
+ OK: 0,
26
+ GENERIC: 1,
27
+ USAGE: 2,
28
+ AUTH: 3,
29
+ NETWORK: 4,
30
+ INTERRUPTED: 130,
31
+ };
32
+ /**
33
+ * 本地参数/负载层面的用法错误。与服务端拒绝区分开,让脚本能区分
34
+ * 「我的命令写错了(2)」和「服务端没答应(1)」。命令层抛出本类型,
35
+ * exitCodeFor 统一识别,不需要每个 catch 各自判断。
36
+ */
37
+ export class UsageError extends Error {
38
+ }
39
+ /**
40
+ * Map a thrown error to its exit code. `UsageError`(本地用法错误)优先——
41
+ * 它不是 axios 错误,若先走 classifyApiError 会被误归为 GENERIC。
42
+ */
43
+ export function exitCodeFor(e) {
44
+ if (e instanceof UsageError)
45
+ return EXIT_CODES.USAGE;
46
+ switch (classifyApiError(e)) {
47
+ case 'auth':
48
+ return EXIT_CODES.AUTH;
49
+ case 'network':
50
+ return EXIT_CODES.NETWORK;
51
+ default:
52
+ return EXIT_CODES.GENERIC;
53
+ }
54
+ }
55
+ /**
56
+ * 统一错误出口。有 spinner 时 `spinner.fail(scope)`(失败行与进行中的转圈
57
+ * 原位收尾);无 spinner 时打 `✗ scope`。错误详情一律走 formatApiError,
58
+ * 保证 401/网络/后端 message 的呈现全 CLI 一致。
59
+ */
60
+ export function emitError(scope, e, opts = {}) {
61
+ if (opts.spinner) {
62
+ opts.spinner.fail(scope);
63
+ }
64
+ else {
65
+ console.error(chalk.red(`✗ ${scope}`));
66
+ }
67
+ console.error(chalk.red(formatApiError(e)));
68
+ process.exit(exitCodeFor(e));
69
+ }
70
+ /**
71
+ * 本地用法错误出口(不涉及 API 调用)。第二条提示固定指向 `--help`——
72
+ * 每个叶子命令的帮助里都有示例,用户不需要去翻文档。
73
+ */
74
+ export function emitUsageError(message) {
75
+ console.error(chalk.red(`✗ ${message}`));
76
+ console.error(chalk.gray("Run the command with '--help' to see usage and examples."));
77
+ process.exit(EXIT_CODES.USAGE);
78
+ }
79
+ /**
80
+ * 中断(SIGINT / Ctrl+C)统一出口:补一个换行让被 spinner/提示符啃掉一半的
81
+ * 输出行完整落地,退出码 130。进程级 handler 与交互 readline 的 raw 模式
82
+ * `rl.on('SIGINT')` 共用这一个出口。
83
+ */
84
+ export function interruptExit() {
85
+ process.stderr.write('\n');
86
+ process.exit(EXIT_CODES.INTERRUPTED);
87
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@autocodeflow/cli",
3
- "version": "1.6.0",
3
+ "version": "1.8.0",
4
4
  "description": "AutoCodeFlow CLI — manage tasks, executions and applications from the terminal",
5
5
  "license": "MIT",
6
6
  "main": "dist/index.js",