@wkgeo/cli 0.0.0-stage → 1.0.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.
Files changed (51) hide show
  1. package/CHANGELOG.md +208 -0
  2. package/LICENSE +21 -0
  3. package/README.md +1042 -3
  4. package/SKILL.md +927 -0
  5. package/lib/ai/client.mjs +161 -0
  6. package/lib/ai/config.mjs +221 -0
  7. package/lib/ai/context.mjs +468 -0
  8. package/lib/ai/log.mjs +53 -0
  9. package/lib/api.mjs +339 -0
  10. package/lib/args.mjs +235 -0
  11. package/lib/cli.mjs +168 -0
  12. package/lib/cms.mjs +330 -0
  13. package/lib/commands/ai.mjs +392 -0
  14. package/lib/commands/apps.mjs +116 -0
  15. package/lib/commands/auth.mjs +1288 -0
  16. package/lib/commands/billing.mjs +666 -0
  17. package/lib/commands/cms.mjs +2533 -0
  18. package/lib/commands/config-auth.mjs +621 -0
  19. package/lib/commands/config.mjs +434 -0
  20. package/lib/commands/dnscred.mjs +428 -0
  21. package/lib/commands/domainops.mjs +546 -0
  22. package/lib/commands/domainorder.mjs +439 -0
  23. package/lib/commands/import.mjs +164 -0
  24. package/lib/commands/index.mjs +528 -0
  25. package/lib/commands/logs.mjs +141 -0
  26. package/lib/commands/orders.mjs +444 -0
  27. package/lib/commands/overview.mjs +394 -0
  28. package/lib/commands/plugins.mjs +678 -0
  29. package/lib/commands/site.mjs +435 -0
  30. package/lib/commands/siteops.mjs +1012 -0
  31. package/lib/commands/sites.mjs +905 -0
  32. package/lib/commands/skill.mjs +119 -0
  33. package/lib/config.mjs +351 -0
  34. package/lib/credentials.mjs +160 -0
  35. package/lib/device-store.mjs +132 -0
  36. package/lib/device.mjs +464 -0
  37. package/lib/errors.mjs +299 -0
  38. package/lib/format.mjs +339 -0
  39. package/lib/http.mjs +71 -0
  40. package/lib/index.mjs +44 -0
  41. package/lib/local-import.mjs +185 -0
  42. package/lib/login.mjs +1638 -0
  43. package/lib/oauth-urls.mjs +163 -0
  44. package/lib/page.mjs +393 -0
  45. package/lib/pkce.mjs +48 -0
  46. package/lib/proxy.mjs +454 -0
  47. package/lib/qr.mjs +31 -0
  48. package/lib/runtime.mjs +650 -0
  49. package/lib/site-state.mjs +137 -0
  50. package/package.json +53 -4
  51. package/wkgeo.mjs +17 -0
package/lib/api.mjs ADDED
@@ -0,0 +1,339 @@
1
+ /**
2
+ * 业务 API 封装:`/cli`(业务面,**全部动作走 CLI 自持云函数**)+ 插件面 `/<plug>` + `/api/oauth/*`(授权面)。
3
+ *
4
+ * ⚠️ 2026-10-22:`/api/data` 已下线。`wkgeo-data` 原本是"47 条动作全转发"的空壳,
5
+ * 现在 CLI 直连真实函数,不再经过它。
6
+ *
7
+ * ⚠️ 2026-10-28(老板拍板「所有 cli 的操作都通过自己的云函数来实现」):业务面**收敛到 `/cli`**
8
+ * (云函数 `wkgeo-cli-fc`)—— 站点 / 域名 / 模板 / 发布 / 资产 / 钱包 / 套餐 / 应用授权
9
+ * 这些动作在 `wkgeo-cli-fc` 里**自持重建**(进程内副本),金融面 14 条由它**白名单转发**给
10
+ * `wkgeo-order`。CLI 侧不再需要「action → 哪个函数」那套路由表猜谜。
11
+ * · 默认:`data()` 一律打 `/cli`;只有**插件面**动作按 `GATEWAY_PREFIXES` 打各自前缀
12
+ * (`/form` `/member` `/channel`;`/ai` `/ai-tools` 仅显式 `prefix:` 时用)。
13
+ * · 逃生阀:`WKONGAI_LEGACY_ENDPOINTS=1` 恢复 2026-10-28 之前的直连
14
+ * (order / domain / user 三个前缀各打各的),**默认关**;只为线上回滚留一条路。
15
+ *
16
+ * 设计约定:
17
+ * 1. **只在这里碰 HTTP**。命令层拿到的要么是 `data`,要么是抛出的 CliError。
18
+ * 2. `data()` 返回的是信封里的 `data` 字段(服务端 `ok(x)` → `{code:0,data:x}`)。
19
+ * 如果某个 action 的 data 是标量(字符串/数组),也原样返回。
20
+ * 3. **不做自动重试**。限流(429)自动重试会掩盖问题,也让"写操作"变得不可预测(重试下单=重复下单!)。
21
+ * 只在错误里给出 retry_after,让人/脚本决定。
22
+ * 4. token 只在 Authorization 头里出现;**任何日志/错误里都不带 token**。
23
+ */
24
+
25
+ import { request, encodeForm } from './http.mjs';
26
+ import { classifyResponse, toCliError, networkError, CliError } from './errors.mjs';
27
+
28
+ /**
29
+ * 金融面动作(`wkgeo-order` 的 14 条)—— 2026-10-28 起**不再由 CLI 直接寻址**,
30
+ * 而是 `wkgeo-cli-fc` 用白名单转发(`ORDER_FORWARD_ACTIONS`)。
31
+ *
32
+ * 这张表留在 CLI 侧只做两件事:
33
+ * ① 逃生阀 `WKONGAI_LEGACY_ENDPOINTS=1` 时恢复老直连(打 `/order`);
34
+ * ② 肉眼核对「哪些动作算钱」——转发白名单必须与它逐条一致。
35
+ *
36
+ * 为什么当初要把这份表搬到 CLI:CLI 以前统一打 `/api/data`,靠 data 内部转发;
37
+ * data 下线后必须自己决定打哪个函数。**只列 order / domain 的例外,其余一律 user**
38
+ * —— 与 data 的 47 条映射(29 user + 14 order + 4 domain)等价。
39
+ *
40
+ * ⚠️ 加新 action 时:先确认它属于哪个函数,不在这两个集合里就当 user(user 会回"未知操作",与以前 data 的行为一致)。
41
+ */
42
+ const FN_ORDER = new Set([
43
+ 'createRechargeOrder',
44
+ 'createRechargeTicket',
45
+ 'createRechargeOrderByTicket',
46
+ 'getRechargeTicketInfo',
47
+ 'createSubscriptionOrder',
48
+ 'createQuotaOrder',
49
+ 'createSiteRenewOrder',
50
+ 'userQuoteBundle',
51
+ 'userCreateBundleOrder',
52
+ 'getOrderPayParams',
53
+ 'cancelOrder',
54
+ 'checkOrder',
55
+ 'sweepOrders',
56
+ 'paymentNotify',
57
+ ]);
58
+
59
+ /**
60
+ * 域名函数(`aliyun/fc/wkgeo-domain/src/index.js`)的动作 —— 前缀 `/domain`。
61
+ *
62
+ * ⚠️ 这张表**漏一条,动作就会被发到 `/user`**,服务端回 `未知操作: <action>`,
63
+ * CLI 看起来像"后端没实现",其实是本地路由错(2026-10-28 task-9 / A7 踩过:
64
+ * `getSiteDomainReminders` 怎么调都 400)。加域名前先核对 domain 函数的 dispatch,
65
+ * 不要凭印象编。
66
+ */
67
+ const FN_DOMAIN = new Set([
68
+ 'provisionSiteDomain',
69
+ 'checkSiteProvision',
70
+ 'retrySiteProvision',
71
+ 'releaseSiteDomain',
72
+ // 2026-10-28 task-9 / A7 补:只读查询类(dispatch 见 wkgeo-domain/src/index.js:1211-1259)
73
+ 'getSiteProvisionStatus',
74
+ 'siteDomainRecords',
75
+ 'siteDomainCheck',
76
+ 'getSiteDomainReminders',
77
+ 'dnsProviderProbe',
78
+ ]);
79
+
80
+ /**
81
+ * 表单插件(`plug/contact-form/fn/src/index.js`)的后台动作 —— 前缀 `/form`。
82
+ *
83
+ * ⚠️ 这些动作**目前只有 CMS 会话 Cookie 能调**(`loadSession` 只认 `cms_session`,
84
+ * 不认 `Authorization: Bearer`),所以 CLI 真调会拿到 401/403。命令照发、错误照译,
85
+ * 后端补 Bearer 桥以后**不用改 CLI** —— 这就是这里保留映射的原因。
86
+ */
87
+ const FN_FORM = new Set([
88
+ 'formList',
89
+ 'formGet',
90
+ 'formEntryList',
91
+ 'formEntryDetail',
92
+ 'formEntryCounts',
93
+ ]);
94
+
95
+ /** 会员插件(`plug/member/fn/src/index.js`)→ 前缀 `/member` */
96
+ const FN_MEMBER = new Set(['memberRegister', 'memberLogin', 'memberMe', 'memberProfileSave']);
97
+
98
+ /** 渠道码插件(`plug/channel-code/fn/src/index.js`)→ 前缀 `/channel` */
99
+ const FN_CHANNEL = new Set(['channelVisit', 'channelRenderVisit']);
100
+
101
+ /**
102
+ * 网关前缀 → 目标云函数(来源:`aliyun/fc/wkgeo-gw/src/index.js` 的 `defaultRoutes`,**别猜**)。
103
+ *
104
+ * 前缀就是 URL 的第一段:`POST {base}/form` = 打到 contact-form 那个函数。
105
+ *
106
+ * **2026-10-28 收敛**:业务面只剩 `cli` 一个(`wkgeo-cli-fc`,自持 + 白名单转发),
107
+ * 其余都是**插件面**(动作在 body 里,函数自己的鉴权口径,CLI 只是把动作转发过去)。
108
+ * `order` / `domain` / `user` 三个前缀**已从这张表移除** —— 它们只在逃生阀
109
+ * `WKONGAI_LEGACY_ENDPOINTS=1` 时由 `fnOf()` 直接返回名字(不走这张表的合法性闸门)。
110
+ * `ai` / `ai-tools` 目前 CLI 不直调(`wkgeo ai` 连的是**本机**模型),但前缀先登记好,
111
+ * 将来加动作时直接可以 `data(action, payload, { prefix: 'ai' })`。
112
+ */
113
+ export const GATEWAY_PREFIXES = Object.freeze({
114
+ cli: 'wkgeo-cli-fc',
115
+ form: 'wkgeo-plugin-contact-form',
116
+ ai: 'wkgeo-ai',
117
+ member: 'wkgeo-plugin-member',
118
+ channel: 'wkgeo-plugin-channel-code',
119
+ 'ai-tools': 'wkgeo-plugin-ai-tools',
120
+ });
121
+
122
+ /** 前缀是否合法(HTTP 层的唯一闸门:不认的前缀直接报用法错误,绝不瞎打) */
123
+ export function isGatewayPrefix(prefix) {
124
+ return typeof prefix === 'string' && Object.prototype.hasOwnProperty.call(GATEWAY_PREFIXES, prefix);
125
+ }
126
+
127
+ /** 逃生阀:`WKONGAI_LEGACY_ENDPOINTS=1` ⇒ 回到 2026-10-28 之前的直连(默认关) */
128
+ const LEGACY_ENV = 'WKONGAI_LEGACY_ENDPOINTS';
129
+
130
+ export function legacyEndpointsEnabled(env = process.env) {
131
+ const v = String((env && env[LEGACY_ENV]) || '').trim().toLowerCase();
132
+ return v === '1' || v === 'true' || v === 'yes' || v === 'on';
133
+ }
134
+
135
+ /**
136
+ * 动作 → 网关前缀。
137
+ *
138
+ * 规则(默认,2026-10-28 起):
139
+ * 1. **插件面**(form / member / channel)照旧打各自前缀 —— 那是别人函数的面,CLI 只做信使;
140
+ * 2. **其余一切**(站点 / 域名 / 模板 / 发布 / 资产 / 钱包 / 套餐 / 应用授权 / 金融面 / 不认识的)
141
+ * 一律 `cli` —— `wkgeo-cli-fc` 自己分发;不认识的动作由它回 `400 未知动作`。
142
+ *
143
+ * 逃生阀 `WKONGAI_LEGACY_ENDPOINTS=1` 时退回老口径:
144
+ * order / domain / form / member / channel 按显式表,其余 `user`。
145
+ */
146
+ export function fnOf(action, { legacy = legacyEndpointsEnabled() } = {}) {
147
+ if (FN_FORM.has(action)) return 'form';
148
+ if (FN_MEMBER.has(action)) return 'member';
149
+ if (FN_CHANNEL.has(action)) return 'channel';
150
+ if (legacy) {
151
+ if (FN_ORDER.has(action)) return 'order';
152
+ if (FN_DOMAIN.has(action)) return 'domain';
153
+ return 'user';
154
+ }
155
+ return 'cli';
156
+ }
157
+
158
+ export function createApi({ config, fetchImpl = globalThis.fetch } = {}) {
159
+ const base = config.base;
160
+ const timeoutMs = config.httpTimeoutMs;
161
+
162
+ async function raw(url, options = {}) {
163
+ return request(url, { ...options, fetchImpl, timeoutMs: options.timeoutMs ?? timeoutMs });
164
+ }
165
+
166
+ /** 决定成败的唯一依据是 body.code(项目约定 HTTP 恒 200) */
167
+ function unwrap(res, action) {
168
+ if (res.networkError) throw networkError(res.networkError, { raw: res });
169
+ const cls = classifyResponse({
170
+ httpStatus: res.status,
171
+ body: res.body,
172
+ action,
173
+ retryAfterHeader: res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null,
174
+ cmdName: config.cmdName || 'wkgeo',
175
+ });
176
+ if (!cls.ok) throw toCliError(cls, { action, raw: { status: res.status, body: res.body } });
177
+ return res.body ? res.body.data : null;
178
+ }
179
+
180
+ return {
181
+ config,
182
+
183
+ /**
184
+ * 业务面:POST /<fn> {action, ...payload} —— fn 由 `fnOf(action)` 决定。
185
+ *
186
+ * 默认 `/cli`(`wkgeo-cli-fc`);插件面按 `GATEWAY_PREFIXES` 打各自前缀。
187
+ * 逃生阀 `WKONGAI_LEGACY_ENDPOINTS=1` 让 `fnOf()` 退回老的 order/domain/user 直连。
188
+ *
189
+ * @param {string} action
190
+ * @param {object} [payload]
191
+ * @param {{token?:string, prefix?:string, headers?:object, timeoutMs?:number}} [opts]
192
+ * `prefix` 覆盖自动推断(打 `/form` `/ai` `/member` `/channel` `/ai-tools` 时用;
193
+ * 只接受 `GATEWAY_PREFIXES` 里的值);`headers` 是额外请求头(如 `x-cms-site`、`Origin`)。
194
+ */
195
+ async data(action, payload = {}, { token, prefix, headers, timeoutMs } = {}) {
196
+ if (!action) throw new CliError('内部错误:缺少 action');
197
+ if (prefix !== undefined && !isGatewayPrefix(prefix)) {
198
+ throw new CliError(`内部错误:不支持的前缀「${prefix}」(可用:${Object.keys(GATEWAY_PREFIXES).join(' / ')})`, {
199
+ kind: 'internal',
200
+ });
201
+ }
202
+ const fn = prefix || fnOf(action);
203
+ const res = await raw(`${base}/${fn}`, {
204
+ method: 'POST',
205
+ timeoutMs,
206
+ headers: {
207
+ 'Content-Type': 'application/json',
208
+ Accept: 'application/json',
209
+ ...(token ? { Authorization: `Bearer ${token}` } : {}),
210
+ ...(headers || {}),
211
+ },
212
+ body: JSON.stringify({ action, ...payload }),
213
+ });
214
+ return unwrap(res, action);
215
+ },
216
+
217
+ /** 授权服务器元数据(授权前用它发现 authorization_endpoint / token 有效期策略) */
218
+ async metadata() {
219
+ const res = await raw(`${base}/api/oauth/metadata`, { method: 'GET', headers: { Accept: 'application/json' } });
220
+ if (res.networkError) throw networkError(res.networkError, { raw: res });
221
+ if (res.status !== 200 || !res.body) {
222
+ const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'metadata', cmdName: config.cmdName || 'wkgeo' });
223
+ throw toCliError(cls, { action: 'metadata', raw: { status: res.status, body: res.body } });
224
+ }
225
+ return res.body;
226
+ },
227
+
228
+ /**
229
+ * 用户信息(身份的唯一权威来源)。
230
+ * ⚠️ 这个端点**不走统一信封**:HTTP 401 + `{error:'invalid_token'}`。
231
+ */
232
+ async userinfo(token) {
233
+ const res = await raw(`${base}/api/oauth/userinfo`, {
234
+ method: 'GET',
235
+ headers: { Accept: 'application/json', Authorization: `Bearer ${token}` },
236
+ });
237
+ if (res.networkError) throw networkError(res.networkError, { raw: res });
238
+ if (res.status === 200 && res.body && res.body.sub) return res.body;
239
+ const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'userinfo', cmdName: config.cmdName || 'wkgeo' });
240
+ throw toCliError(cls, { action: 'userinfo', raw: { status: res.status, body: res.body } });
241
+ },
242
+
243
+ /**
244
+ * 换令牌 / 刷新令牌(OAuth 标准表单)。
245
+ * ⚠️ 成功响应里**有明文 access_token** —— 返回值只允许写进凭据文件,禁止打印。
246
+ */
247
+ async token(form) {
248
+ const res = await raw(`${base}/api/oauth/token`, {
249
+ method: 'POST',
250
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
251
+ body: encodeForm(form),
252
+ });
253
+ if (res.networkError) throw networkError(res.networkError, { raw: res });
254
+ if (res.status === 200 && res.body && res.body.access_token) return res.body;
255
+ const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'token', cmdName: config.cmdName || 'wkgeo' });
256
+ throw toCliError(cls, { action: 'token', raw: { status: res.status, body: res.body } });
257
+ },
258
+
259
+ /**
260
+ * 原样发一个 OAuth 表单请求,**不抛异常**(返回 status/body/networkError)。
261
+ *
262
+ * 为什么需要它:设备码轮询里 `authorization_pending` / `slow_down` / `expired_token`
263
+ * 都是**正常预期**的中间态,不是错误 —— 用一个会抛的封装会让轮询逻辑写成一团 try/catch。
264
+ */
265
+ async oauthForm(pathname, form) {
266
+ const res = await raw(`${base}${pathname}`, {
267
+ method: 'POST',
268
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
269
+ body: encodeForm(form),
270
+ });
271
+ return res;
272
+ },
273
+
274
+ /** 自省(RFC 7662):返回 {active,...},**不是错误**,调用方自己看 active */
275
+ async introspect(token) {
276
+ const res = await raw(`${base}/api/oauth/introspect`, {
277
+ method: 'POST',
278
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
279
+ body: encodeForm({ token }),
280
+ });
281
+ if (res.networkError) throw networkError(res.networkError, { raw: res });
282
+ if (res.status === 200 && res.body) return res.body;
283
+ const cls = classifyResponse({ httpStatus: res.status, body: res.body, action: 'introspect', cmdName: config.cmdName || 'wkgeo' });
284
+ throw toCliError(cls, { action: 'introspect', raw: { status: res.status, body: res.body } });
285
+ },
286
+
287
+ /**
288
+ * 吊销(RFC 7009)。
289
+ * best-effort:未知 token 也回 200;网络失败**不阻塞 logout**(本地删掉才是关键),
290
+ * 但把失败原因返回给调用方,让 logout 能如实告诉用户"服务端没吊销成功"。
291
+ */
292
+ async revoke(token) {
293
+ try {
294
+ const res = await raw(`${base}/api/oauth/revoke`, {
295
+ method: 'POST',
296
+ headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
297
+ body: encodeForm({ token, client_id: config.clientId }),
298
+ });
299
+ if (res.networkError) return { ok: false, reason: res.networkError };
300
+ if (res.status >= 200 && res.status < 300) return { ok: true };
301
+ return { ok: false, reason: `HTTP ${res.status} ${res.text ? res.text.slice(0, 200) : ''}`.trim() };
302
+ } catch (e) {
303
+ return { ok: false, reason: (e && e.message) || String(e) };
304
+ }
305
+ },
306
+ };
307
+ }
308
+
309
+ /**
310
+ * 具名动作封装(不用 this,避免解构后 this 丢失 —— 踩过)。
311
+ * 用法:`const api = createApi({config}); await api.data('listSites', {...}, {token})`
312
+ */
313
+ export const ACTIONS = {
314
+ sites: {
315
+ list: 'listSites',
316
+ get: 'getSite',
317
+ create: 'createSite',
318
+ remove: 'deleteSite',
319
+ purge: 'purgeSite',
320
+ },
321
+ wallet: {
322
+ get: 'getMyWallet',
323
+ billing: 'getMyBilling',
324
+ },
325
+ orders: {
326
+ createQuota: 'createQuotaOrder',
327
+ check: 'checkOrder',
328
+ list: 'listMyOrders',
329
+ cancel: 'cancelOrder',
330
+ },
331
+ catalog: {
332
+ products: 'listProducts',
333
+ entitlements: 'listMyEntitlements',
334
+ },
335
+ apps: {
336
+ list: 'listMyOAuthAuthorizations',
337
+ revoke: 'revokeMyOAuthAuthorization',
338
+ },
339
+ };
package/lib/args.mjs ADDED
@@ -0,0 +1,235 @@
1
+ /**
2
+ * 命令行解析(手写,零依赖)。
3
+ *
4
+ * 为什么手写而不是 yargs/commander:
5
+ * 1. 老板要求尽量零第三方依赖(npx 一行跑、审计面小)。
6
+ * 2. 我们只需要"多词命令 + 少量标志",手写 100 行就够,而且**能精确控制报错文案**(中文)。
7
+ *
8
+ * 支持的写法:
9
+ * wkgeo sites create --name "我的站" --template <id>
10
+ * wkgeo orders create --product=storage_mb --units 1
11
+ * wkgeo login --no-browser # --no-xxx → xxx=false
12
+ * wkgeo wallet -j # 短标志:-h/-v/-y/-j
13
+ *
14
+ * ⚠️ 已知取舍:`--name -abc` 这种"值本身以 - 开头"的写法会被当成布尔标志。
15
+ * 需要时用 `--name=-abc`。这也是大多数 CLI 的行为,不值得为它加复杂度。
16
+ */
17
+
18
+ import { UsageError } from './errors.mjs';
19
+
20
+ /** 全局标志:任何命令都接受(写在 spec 之外,避免每个命令重复声明) */
21
+ export const GLOBAL_FLAGS = {
22
+ base: { type: 'string', desc: 'API 基址(默认线上网关,可用 WKONGAI_BASE 覆盖)' },
23
+ /**
24
+ * CMS 面是**另一个云函数 / 另一个域名**(新写法 `https://api.wkgeo.com/cms`),
25
+ * 所以单独给一个基址开关:联调 / 换环境时不用去改平台面的 `--base`。
26
+ */
27
+ 'cms-base': { type: 'string', desc: 'CMS 接口基址(默认 https://api.wkgeo.com/cms,可用 WKONGAI_CMS_BASE 覆盖)' },
28
+ 'web-base': { type: 'string', desc: '前端基址(授权页兜底地址)' },
29
+ 'client-id': { type: 'string', desc: 'OAuth 客户端 id(默认 wkgeo-cli)' },
30
+ scope: { type: 'string', desc: '申请的能力范围(空格分隔)' },
31
+ credentials: { type: 'string', desc: '凭据文件路径(默认 ~/.wkongai/credentials.json)' },
32
+ 'callback-port': { type: 'string', desc: '本地回调端口(默认 53682)' },
33
+ 'callback-host': { type: 'string', desc: '本地回调监听地址(**只允许回环**,默认 127.0.0.1)' },
34
+ /**
35
+ * ⚠️ 单位是**秒**(不是毫秒)—— 原来按毫秒解释,`--timeout 600` 变成 600 毫秒、
36
+ * 0.8 秒就超时,用户按直觉写"600 秒"反而必然失败;`--help` 里当时也没写单位。
37
+ * 现在:纯数字按秒,也接受显式后缀 `600s` / `500ms`;非法值明确报错。
38
+ */
39
+ timeout: { type: 'string', desc: '等待授权回调的超时,**默认单位秒**(--timeout 600 = 600 秒;也支持 600s / 500ms;默认 300 秒)' },
40
+ 'http-timeout': { type: 'string', desc: '单次 HTTP 请求超时毫秒数(默认 30000)' },
41
+ json: { type: 'boolean', desc: '以 JSON 输出(默认:非 TTY 时自动 JSON)' },
42
+ text: { type: 'boolean', desc: '强制人类可读输出(管道里默认是 JSON,用它覆盖)' },
43
+ color: { type: 'boolean', desc: '彩色输出(--no-color 关闭)' },
44
+ verbose: { type: 'boolean', desc: '额外诊断信息(原始响应会先脱敏)' },
45
+ help: { type: 'boolean', desc: '显示帮助' },
46
+ version: { type: 'boolean', desc: '显示版本' },
47
+ };
48
+
49
+ const SHORT_FLAGS = { h: 'help', v: 'version', j: 'json' };
50
+
51
+ /** kebab-case → camelCase:`client-id` → `clientId` */
52
+ export function camel(key) {
53
+ return String(key).replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
54
+ }
55
+
56
+ /**
57
+ * 通用解析:只做"切成 positionals + flags",不校验具体命令。
58
+ * @returns {{positionals:string[], flags:Record<string, string|boolean>}}
59
+ */
60
+ export function parseArgv(argv = []) {
61
+ const flags = {};
62
+ const positionals = [];
63
+ for (let i = 0; i < argv.length; i++) {
64
+ const a = String(argv[i]);
65
+ if (a === '--') {
66
+ positionals.push(...argv.slice(i + 1).map(String));
67
+ break;
68
+ }
69
+ if (a.startsWith('--')) {
70
+ const eq = a.indexOf('=');
71
+ let key = eq === -1 ? a.slice(2) : a.slice(2, eq);
72
+ let val = eq === -1 ? undefined : a.slice(eq + 1);
73
+ if (!key) throw new UsageError('参数格式错误:`--` 后面没有标志名');
74
+ if (val === undefined) {
75
+ const next = argv[i + 1];
76
+ // 下一个词不是标志 → 当作本标志的值;否则本标志是布尔
77
+ if (next !== undefined && !String(next).startsWith('-')) {
78
+ val = String(next);
79
+ i++;
80
+ } else {
81
+ val = true;
82
+ }
83
+ }
84
+ if (key.startsWith('no-') && key.length > 3) flags[key.slice(3)] = false;
85
+ else flags[key] = val;
86
+ continue;
87
+ }
88
+ if (/^-[A-Za-z]$/.test(a)) {
89
+ const long = SHORT_FLAGS[a.slice(1)];
90
+ if (!long) throw new UsageError(`无法识别的短参数:${a}`);
91
+ flags[long] = true;
92
+ continue;
93
+ }
94
+ if (a.startsWith('-') && a !== '-') {
95
+ throw new UsageError(`无法识别的参数:${a}`);
96
+ }
97
+ positionals.push(a);
98
+ }
99
+ return { positionals, flags };
100
+ }
101
+
102
+ /**
103
+ * 按命令 spec 校验/转换标志。
104
+ * 未知标志直接报错(而不是静默忽略):拼错 `--nmae` 时静默忽略会让用户以为成功了,
105
+ * 这是最坑的一类"看起来成功其实没生效"。
106
+ */
107
+ export function coerceFlags(spec, flags) {
108
+ const defs = { ...GLOBAL_FLAGS, ...(spec.flags || {}) };
109
+ /**
110
+ * ⚠️ 特例:`--no-xxx` 在 `parseArgv` 里被统一当成"把 xxx 关掉"(`--no-color` / `--no-browser`),
111
+ * 但有的标志**名字本身就以 `no-` 开头**,而且是个**正向开关** —— 例如
112
+ * `login --no-wait`("不要等待,申请完码就退出")。
113
+ *
114
+ * 解析阶段拿不到命令 spec、无法区分这两种情况,所以会把它变成 `wait:false`。
115
+ * 这里按"注册表"还原:只有当 spec 里**确实定义了** `no-wait`、
116
+ * 且**没有人**定义 `wait` 时,`wait:false` 才只可能来自用户写的 `--no-wait`。
117
+ * (踩过的坑:不加这段的话 `login --no-wait` 会报"不认识的参数:--wait",
118
+ * 而 `--wait` 在帮助里根本不存在,用户完全看不懂自己写错了什么。)
119
+ */
120
+ const restored = { ...flags };
121
+ for (const key of Object.keys(defs)) {
122
+ if (!key.startsWith('no-')) continue;
123
+ const negated = key.slice(3);
124
+ if (defs[negated] === undefined && restored[key] === undefined && restored[negated] === false) {
125
+ restored[key] = true;
126
+ delete restored[negated];
127
+ }
128
+ }
129
+
130
+ const out = {};
131
+ const unknown = [];
132
+ for (const [key, val] of Object.entries(restored)) {
133
+ const def = defs[key];
134
+ if (!def) {
135
+ unknown.push(key);
136
+ continue;
137
+ }
138
+ const name = camel(key);
139
+ if (def.type === 'boolean') {
140
+ out[name] = val === false ? false : val === true ? true : !/^(false|0|no)$/i.test(String(val));
141
+ } else if (def.type === 'number') {
142
+ const n = Number(val);
143
+ if (!Number.isFinite(n)) throw new UsageError(`参数 --${key} 需要数字,收到:${val}`);
144
+ out[name] = n;
145
+ } else {
146
+ if (val === true) throw new UsageError(`参数 --${key} 缺少值(写成 --${key}=值 也可以)`);
147
+ out[name] = String(val);
148
+ }
149
+ }
150
+ if (unknown.length) {
151
+ const usable = Object.keys(defs).sort().join(' / ');
152
+ throw new UsageError(`不认识的参数:${unknown.map((u) => '--' + u).join(', ')}\n本命令可用参数:${usable}`);
153
+ }
154
+ for (const [key, def] of Object.entries(spec.flags || {})) {
155
+ if (def.required && out[camel(key)] === undefined) {
156
+ throw new UsageError(`缺少必填参数 --${key}${def.desc ? `(${def.desc})` : ''}`);
157
+ }
158
+ }
159
+ return out;
160
+ }
161
+
162
+ /**
163
+ * 位置参数校验:按顺序、必填在前。
164
+ *
165
+ * 最后一个 arg 可标 `variadic: true`(如 `domain check <域名…>`):
166
+ * 它会把剩下的位置参数全部收进一个**数组**,不再报「参数过多」。
167
+ */
168
+ export function checkPositionals(spec, rest) {
169
+ const wanted = spec.args || [];
170
+ const last = wanted[wanted.length - 1];
171
+ const variadic = Boolean(last && last.variadic);
172
+ const fixed = variadic ? wanted.length - 1 : wanted.length;
173
+ if (!variadic && rest.length > fixed) {
174
+ throw new UsageError(`参数过多:${rest.slice(fixed).map((r) => `"${r}"`).join(' ')}\n用法:${spec.usage}`);
175
+ }
176
+ for (let i = 0; i < fixed; i++) {
177
+ if (wanted[i].required && (rest[i] === undefined || rest[i] === '')) {
178
+ throw new UsageError(`缺少参数 <${wanted[i].name}>${wanted[i].desc ? `(${wanted[i].desc})` : ''}\n用法:${spec.usage}`);
179
+ }
180
+ }
181
+ if (variadic) {
182
+ const tail = rest.slice(fixed);
183
+ if (last.required && tail.length === 0) {
184
+ throw new UsageError(`缺少参数 <${last.name}>${last.desc ? `(${last.desc})` : ''}\n用法:${spec.usage}`);
185
+ }
186
+ const out = {};
187
+ for (let i = 0; i < fixed; i++) {
188
+ if (rest[i] !== undefined) out[wanted[i].name] = rest[i];
189
+ }
190
+ out[last.name] = tail;
191
+ return out;
192
+ }
193
+ const out = {};
194
+ wanted.forEach((w, i) => {
195
+ if (rest[i] !== undefined) out[w.name] = rest[i];
196
+ });
197
+ return out;
198
+ }
199
+
200
+ /**
201
+ * 从位置参数里认出命令(最长前缀匹配:支持 `domain dns credential set` 这类四词命令)。
202
+ * 先按 4 词、再 3 词、再 2 词、再 1 词试,命中即返回,剩下的位置参数归命令自己。
203
+ *
204
+ * ★ 2026-10-28:三词 → 四词(`domain dns credential set`)。顺带补一个坑:
205
+ * `wkgeo domain dns credential`(少打最后一个词)原本会退化命中两词命令 `domain dns`,
206
+ * 于是 "credential" 被当成域名参数传给一条完全不相干的命令 —— 报错文案极其误导。
207
+ * 所以这里先查"打了一半的更长命令",有就直接报"命令不完整"。
208
+ * @param {Array} commands 命令 spec 数组(必须带 name,如 'sites create')
209
+ */
210
+ export function resolveCommand(commands, positionals) {
211
+ const byName = new Map(commands.map((c) => [c.name, c]));
212
+ const typed = positionals.join(' ');
213
+ if (!byName.has(typed) && positionals.length >= 2) {
214
+ const partial = commands
215
+ .filter((c) => c.name.startsWith(`${typed} `))
216
+ .map((c) => c.name);
217
+ if (partial.length) {
218
+ throw new UsageError(`命令不完整:"${typed}" 还差子命令\n可用:${partial.join(' / ')}`);
219
+ }
220
+ }
221
+ const maxWords = Math.min(4, positionals.length);
222
+ for (let n = maxWords; n >= 1; n -= 1) {
223
+ const name = positionals.slice(0, n).join(' ');
224
+ if (byName.has(name)) return { spec: byName.get(name), rest: positionals.slice(n) };
225
+ }
226
+ // 命令名不完整(比如只打了 `sites`):给出该分组下的可用命令
227
+ const group = positionals[0];
228
+ if (group) {
229
+ const siblings = commands.filter((c) => c.name.startsWith(`${group} `)).map((c) => c.name);
230
+ if (siblings.length) {
231
+ throw new UsageError(`命令不完整:"${group}" 需要子命令\n可用:${siblings.join(' / ')}`);
232
+ }
233
+ }
234
+ return null;
235
+ }