wkgeo-cli 0.2.0

package/lib/runtime.mjs

@@ -0,0 +1,287 @@
+/**
+ * 运行期上下文：把「解析命令行 → 生效配置 → API 客户端 → 输出器 → 登录态」串起来。
+ *
+ * 为什么要有这一层：
+ *   每个命令都需要那几样东西（配置/api/输出/凭据），如果每个命令自己 new 一遍，
+ *   测试就没法注入（不能替换 fetch、不能指定临时凭据文件）。
+ *   集中在这里之后，单测里 `createRuntime({argv, env, stdout, fetchImpl})` 就能把整条链路变成离线的。
+ *
+ * 输出契约（**给 AI 端消费用的，必须稳定**）：
+ *   * `--json`：stdout **只有一个 JSON 对象**（成功/失败都是），字段见 okEnvelope/errorEnvelope。
+ *   * **非 TTY 时自动用 JSON**（AI/管道场景最省事，不用记得加 --json）；
+ *     想强制人类可读输出用 `--text`。
+ *   * 人类可读的诊断信息一律走 stderr，绝不混进 stdout 的 JSON 里。
+ *   * 例外：`login` 天生长跑，JSON 模式下按 **JSONL 事件流**输出（见 commands/auth.mjs 的说明）。
+ */
+
+import { parseArgv, coerceFlags, checkPositionals, resolveCommand } from './args.mjs';
+import { resolveConfig } from './config.mjs';
+import { createApi } from './api.mjs';
+import { requireCredentials, readCredentials } from './credentials.mjs';
+import { createPalette, renderTable, safeJson } from './format.mjs';
+import { UsageError, EXIT } from './errors.mjs';
+import { detectProxy, proxyWarningPayload } from './proxy.mjs';
+
+/** 成功信封 */
+export function okEnvelope(command, data, meta) {
+  return { ok: true, command, data, meta };
+}
+
+/** 失败信封：**结构化**，带 code / message / hint，让 AI 端能自己决定下一步 */
+export function errorEnvelope(command, err, meta) {
+  return {
+    ok: false,
+    command,
+    error: {
+      kind: (err && err.kind) || 'error',
+      code: err && err.code !== undefined ? err.code : null,
+      message: (err && err.message) || String(err),
+      hint: (err && err.hint) || null,
+      retry_after: err && err.retryAfter !== undefined ? err.retryAfter : null,
+    },
+    meta,
+  };
+}
+
+/** 输出器：人类可读 + `--json` 两套；"令牌不进终端"这件事只在这里发生一次 */
+export function createOutput({ stdout, stderr, json = false, color = true, meta = () => ({}) }) {
+  const p = createPalette({ enabled: color && !json });
+  const w = (s) => stdout.write(s);
+  const we = (s) => stderr.write(s);
+  return {
+    palette: p,
+    json,
+    line: (s = '') => {
+      if (!json) w(String(s) + '\n');
+    },
+    /**
+     * 原样写 stdout，**无视 json 模式**（注意与 line/info 的区别：那三个在 json 模式下什么都不写）。
+     *
+     * 为什么需要它：`skill` 的产物**本身就是文档**（markdown 原文）。全 CLI 的通用约定是
+     * "非终端自动 JSON"，但把 markdown 套进 JSON 信封会毁掉可读性（换行被转义、重定向出来
+     * 不能直接读）。所以那条命令要一个"必须写 stdout、且不套信封"的出口 —— 就是这里，
+     * 保持"谁写 stdout"只在本文件里出现一次。
+     */
+    plain: (s = '') => w(String(s)),
+    head: (title) => {
+      if (!json) w(`\n${p.bold(title)}\n`);
+    },
+    ok: (s) => {
+      if (!json) w(`${p.green('✔')} ${s}\n`);
+      else we(`✔ ${s}\n`);
+    },
+    warn: (s) => {
+      if (!json) w(`${p.yellow('!')} ${s}\n`);
+      else we(`! ${s}\n`);
+    },
+    info: (s) => {
+      if (!json) w(`${p.dim(s)}\n`);
+    },
+    /**
+     * ★ 人类提示块：人读模式走 stdout，**JSON 模式走 stderr**。
+     *
+     * 为什么需要它（与 line/info 的区别）：`--json` / 非 TTY 下 stdout 必须只有机器可读 JSON，
+     * 而"⚠️ 浏览器没能自动打开，请手动复制这个地址…（含完整 URL）"这类**要给用户看**的提示
+     * 又不能因为切了 JSON 就消失（用户得能照着它手动打开授权页/收银台）。
+     * 走 stderr 既不污染 stdout，AI 客户端也照样能看到。
+     */
+    notice: (s = '') => {
+      if (!json) w(String(s) + '\n');
+      else we(String(s) + '\n');
+    },
+    err: (s) => we(`${p.red('✖')} ${s}\n`),
+    raw: (s) => we(String(s) + '\n'),
+    table: (columns, rows) => {
+      if (!json) w(renderTable(columns, rows) + '\n');
+    },
+    /** 直接打一个对象（JSONL 事件流用），**不做信封包装** */
+    event: (obj) => w(safeJson(obj, 0) + '\n'),
+    emitOk: (command, data) => {
+      if (json) w(safeJson(okEnvelope(command, data, meta()), 2) + '\n');
+    },
+    emitErr: (command, err) => {
+      if (json) w(safeJson(errorEnvelope(command, err, meta()), 2) + '\n');
+      else {
+        const code = err && err.code !== null && err.code !== undefined ? `[code=${err.code}] ` : '';
+        we(`${p.red('✖')} ${code}${(err && err.message) || String(err)}\n`);
+        if (err && err.hint) we(`  ${p.yellow('↳')} ${err.hint}\n`);
+        if (err && err.retryAfter !== undefined && err.retryAfter !== null) {
+          we(`  ${p.yellow('↳')} 建议 ${err.retryAfter} 秒后重试\n`);
+        }
+      }
+    },
+  };
+}
+
+/**
+ * @param {object} args
+ * @param {string[]} args.argv              process.argv.slice(2)
+ * @param {Array} args.commands             命令注册表
+ * @param {object} [args.env]
+ * @param {object} [args.stdout]            {write, isTTY}
+ * @param {object} [args.stderr]
+ * @param {Function} [args.fetchImpl]
+ */
+export function createRuntime({
+  argv = [],
+  commands,
+  env = process.env,
+  stdout = process.stdout,
+  stderr = process.stderr,
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+  /**
+   * 这两个是给"需要外部动作"的命令（login）用的注入点：
+   *   openBrowser —— 测试里替换成空函数，避免真的弹浏览器
+   *   sleep       —— 设备码轮询的等待，测试里替换成假时钟
+   * ⚠️ 踩过的坑：一开始没把 fetchImpl/openBrowser 从 run() 透传到 runLogin/runDeviceLogin，
+   *    结果命令层单测会**真的去打网络/弹浏览器**（静默变成集成测试）。
+   */
+  openBrowser = undefined,
+  sleep = undefined,
+  /**
+   * 「设备码先成功后，本地回调监听再多留多久」的注入点（毫秒；见 lib/login.mjs 的
+   * `DEFAULT_POST_DEVICE_GRACE_MS`）。**只为单测**：注入一个小值就能确定性地验证
+   * "迟到的回调拿到'已完成'页"，不必让用例真的等几秒。
+   */
+  postDeviceGraceMs = undefined,
+  /**
+   * `spawnImpl` —— `child_process.spawn` 的注入点（**只为单测**）。
+   *
+   * ★ 为什么必须透传到命令层才有意义：`--open-browser` / "非 TTY 不弹"这两条行为，
+   *   要在**命令层**端到端验证"到底有没有真的去 spawn 浏览器"。
+   *   只注入一个假的 `openBrowser` 只能证明"我们没调用注入的实现"，
+   *   而真正要钉的是**生产接线**（defaultOpenBrowserAsync → child_process.spawn）在 AI 场景下
+   *   一次都不发生。生产不传 = 真 spawn。
+   */
+  spawnImpl = undefined,
+  /**
+   * 代理检测的两个注入点（见 lib/proxy.mjs）：
+   *   platform —— 让单测能在任意平台上验证 Windows/macOS 的解析分支；
+   *   exec     —— 跑 `reg query` / `scutil --proxy` 的函数。**单测必须注入**，
+   *               否则单测会真的去起子进程、结果还随宿主机代理设置漂移。
+   */
+  platform = process.platform,
+  exec,
+  /**
+   * `skill` 命令要读的那份手册的位置（默认 = 包根目录的 `SKILL.md`，见 lib/commands/skill.mjs）。
+   * 之所以做成注入点：**"包里没有手册"这个分支没法在真实仓库里造**（总不能把 SKILL.md 删了
+   * 或改名 —— 那是并行跑的其它用例依赖的真文件）。单测传入一个不存在的路径即可稳定覆盖该分支。
+   */
+  skillUrl = undefined,
+} = {}) {
+  const startedAt = now();
+  const { positionals, flags: rawFlags } = parseArgv(argv);
+
+  const resolved = resolveCommand(commands, positionals);
+  if (!resolved) {
+    const err = new UsageError(`不认识的命令：${positionals.join(' ') || '（空）'}`);
+    err.showHelp = true;
+    throw err;
+  }
+  const { spec, rest } = resolved;
+  const flags = coerceFlags(spec, rawFlags);
+  const positional = checkPositionals(spec, rest);
+  const config = resolveConfig(flags, env);
+  config.cmdName = 'wkgeo';
+
+  /**
+   * 是否 JSON 输出。
+   * ⚠️ 默认值依赖 `isTTY`：**非 TTY（管道 / AI 子进程）自动切 JSON**。
+   *    这个默认值是刻意的 —— 父进程多半是脚本或 AI，人类可读的表格对他们没用。
+   */
+  const json = flags.json === true ? true : flags.text === true ? false : !stdout.isTTY;
+
+  const colorEnabled = config.color !== false && !env.NO_COLOR && !!stdout.isTTY && !json;
+
+  const api = createApi({ config, fetchImpl });
+
+  /**
+   * 代理检测结果：**懒加载 + 记忆化**。
+   *
+   * ⚠️ 为什么不在这里直接算：Windows 上要起一次 `reg.exe`（约 30-50ms 真机实测）。
+   *    如果每个命令、每次输出都探测一遍，等于给所有命令加一笔固定开销；
+   *    而"代理会不会挡回调"这件事**只有 login（和诊断用的 config）关心**。
+   * 所以：谁需要谁调 `runtime.proxyInfo()`；`meta()` 只在**已经算过**时才把它带出去，
+   * 这样 `--json` 的错误信封里也能带上它（AI 端据此判断"是不是代理的锅"），
+   * 同时不给其它命令增加任何成本。
+   */
+  const proxyState = { computed: false, info: null };
+  const proxyInfo = () => {
+    if (!proxyState.computed) {
+      proxyState.computed = true;
+      try {
+        proxyState.info = detectProxy({ platform, env, exec });
+      } catch (e) {
+        // 检测本身绝不能让命令失败：退化成"没检测到"，只留一条诊断
+        proxyState.info = { detected: false, risk: false, loopback_bypassed: false, sources: [], platform, probe_error: String((e && e.message) || e) };
+      }
+    }
+    return proxyState.info;
+  };
+
+  const meta = () => {
+    const m = {
+      base: config.base,
+      client_id: config.clientId,
+      credentials_file: config.credentialsFile,
+      duration_ms: Math.max(0, now() - startedAt),
+    };
+    // 只有"真的探测过"才带这个字段：没探测过 = 结论未知，不该编一个 false 出来
+    if (proxyState.computed) m.proxy_warning = proxyWarningPayload(proxyState.info, { cmdName: config.cmdName || 'wkgeo' });
+    return m;
+  };
+
+  const out = createOutput({ stdout, stderr, json, color: colorEnabled, meta });
+
+  const runtime = {
+    spec,
+    flags,
+    positional,
+    config,
+    api,
+    out,
+    env,
+    now,
+    meta,
+    /** ★ 代理检测（懒加载 + 记忆化；见上面 proxyState 的说明） */
+    proxyInfo,
+    /** 透传给 login/device 的依赖（见上面 createRuntime 的说明） */
+    fetchImpl,
+    openBrowser,
+    spawnImpl,
+    sleep,
+    /** ★ 「设备码先成功后的监听宽限期」注入点（只为单测；见 createRuntime 的说明） */
+    postDeviceGraceMs,
+    platform,
+    /**
+     * ★ 「是不是人在终端」—— `resolveBrowserIntent()` 的输入之一。
+     *
+     * 为什么放在 runtime 里算：只有这里同时知道 **stdout 是不是 TTY** 与 **是不是 JSON 输出**
+     * （`json` 的默认值也依赖 `isTTY`，见上面）。命令层原样透传即可，
+     * **绝不能**各命令自己判断一遍 —— 那迟早会出现"授权不弹、支付还弹"。
+     */
+    isTTY: !!stdout.isTTY,
+    /** ★ `skill` 命令读手册的位置（默认包内 SKILL.md；单测可注入不存在的路径） */
+    skillUrl,
+    /** 读登录态（未登录/过期 → 抛带提示的 CliError，exit 3） */
+    requireAuth({ allowExpired = false } = {}) {
+      return requireCredentials(config.credentialsFile, { allowExpired, now: now() });
+    },
+    readCredentials() {
+      return readCredentials(config.credentialsFile);
+    },
+    /** 调业务接口：自动带上凭据里的 token */
+    callData(action, payload = {}, opts = {}) {
+      const creds = opts.credentials || runtime.requireAuth({ allowExpired: opts.allowExpired });
+      return api.data(action, payload, { token: creds.access_token });
+    },
+    /** 成功收尾（JSON 模式输出信封；人类模式什么都不做，由命令自己打印） */
+    done(data) {
+      out.emitOk(spec.name, data);
+    },
+  };
+  return runtime;
+}
+
+export { EXIT };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "wkgeo-cli",
+  "version": "0.2.0",
+  "description": "云站平台官方命令行客户端：授权登录一次，之后建站 / 下单 / 钱包支付 / 查余额都不用再登录（OAuth 授权码 + PKCE，公共客户端，零第三方依赖）",
+  "keywords": [
+    "wkgeo",
+    "云站",
+    "cli",
+    "oauth",
+    "pkce",
+    "cloudbase"
+  ],
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "wkgeo": "./wkgeo.mjs"
+  },
+  "main": "./lib/index.mjs",
+  "exports": {
+    ".": "./lib/index.mjs"
+  },
+  "files": [
+    "wkgeo.mjs",
+    "lib",
+    "README.md",
+    "SKILL.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "start": "node wkgeo.mjs",
+    "build:zip": "node scripts/build-zip.mjs",
+    "build:exe": "node scripts/build-exe.mjs",
+    "verify:live": "node scripts/live-verify.mjs",
+    "verify:live:sql": "node scripts/live-sql.mjs",
+    "prepublishOnly": "node --test \"test/*.test.mjs\""
+  },
+  "dependencies": {},
+  "optionalDependencies": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://www.wkgeo.com/"
+  },
+  "homepage": "https://www.wkgeo.com/"
+}

package/wkgeo.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * 云站平台官方 CLI 的可执行入口。
+ *
+ * 用法：
+ *   npx -y wkgeo-cli@latest login            # AI / 开发者首选（不装依赖，直接跑）
+ *   npm i -g wkgeo-cli && wkgeo login        # 全局安装后
+ *   node cli/wkgeo.mjs login                 # 在本仓库里直接跑
+ *
+ * 为什么入口薄成这样：真正的逻辑都在 lib/ 里，且不依赖 process ——
+ * 这样单测可以直接 `run(['wallet'], {stdout: 假对象})`，把整条链路变成离线的。
+ */
+
+import { run } from './lib/cli.mjs';
+
+const code = await run(process.argv.slice(2));
+process.exitCode = code;