wkgeo-cli 0.2.0 → 0.2.2

package/lib/oauth-urls.mjs

@@ -0,0 +1,163 @@
+/**
+ * 授权站页面地址的「归一化」——**唯一入口**。
+ *
+ * ## 为什么需要它（2026-10-18 域名统一到路径）
+ * 平台把三个业务前端统一到了路径：
+ *   * 客户后台   `https://wkgeo.com/cms/`     （老：`https://cms.wkgeo.com/`）
+ *   * 会员站     `https://wkgeo.com/user/`    （老：`https://user.wkgeo.com/`）
+ *   * 授权站     `https://wkgeo.com/oauth/`   （老：`https://oauth.wkgeo.com/`）
+ *   * 收银台     `https://pay.wkgeo.com/`     —— **支付独立，没动**
+ * 老地址一律**继续可用**（老板要求并存），但 CLI 的 canonical 地址要切到新路径。
+ *
+ * ## 问题在哪
+ * CLI 的授权地址有两个来源：
+ *   1. 线上 metadata 的 `authorization_endpoint` / `device_verification_uri`
+ *      —— 由云函数 `tencent/functions/oauth/index.js` 的 `ADMIN_WEB_BASE` 决定，
+ *      它的**线上环境变量里还写着老地址**，所以在服务端切完并重新部署之前，
+ *      这两个字段一直返回 `https://oauth.wkgeo.com/...`；
+ *   2. CLI 自己的兜底 `${config.oauthWebBase}/authorize`。
+ * 只改 (2) 没用 —— (1) 永远优先，用户看到的还是老子域。
+ *
+ * ## 采取的口径
+ * **配置基址（`WKONGAI_OAUTH_WEB_BASE` / `--web-base`）是 canonical，服务端只提供"路径"。**
+ * 拿到任何平台内的地址后，把它的 pathname 挪到当前配置的基址下：
+ *   老站 `/authorize/`  + 新基址 `https://wkgeo.com/oauth` → `https://wkgeo.com/oauth/authorize/`
+ *   新站 `/oauth/authorize/` + 老基址 `https://oauth.wkgeo.com` → `https://oauth.wkgeo.com/authorize/`
+ * 这样：
+ *   * **默认走新路径**（`DEFAULT_OAUTH_WEB_BASE` 已改成 `https://wkgeo.com/oauth`）；
+ *   * **回滚只要一条环境变量**：`WKONGAI_OAUTH_WEB_BASE=https://oauth.wkgeo.com`
+ *     （不用改代码、不用发版）；
+ *   * 服务端将来把 `ADMIN_WEB_BASE` 切过来之后，这里**不动**也仍然正确（幂等）。
+ *
+ * ## 边界（不许放宽）
+ *   * 只处理 http/https；
+ *   * 只认**本平台域名**：`wkgeo.com` / `*.wkgeo.com` / `wkgeo.cn` / `*.wkgeo.cn`
+ *     —— 历史上真的被 `authorization_endpoint=http://localhost:8000` 坑过一次，
+ *     打开用户本机端口是**最坏**的一种失败；
+ *   * 平台之外的地址一律不跟随，直接回落到基址 + `fallbackPath`，并如实返回 `reason`
+ *     让调用方打日志（不要静默纠正）。
+ */
+
+/** 平台根域（裸域也认：路径化之后授权站的 host 就是 `wkgeo.com`） */
+const PLATFORM_ROOTS = ['wkgeo.com', 'wkgeo.cn'];
+
+/**
+ * 已知的「站前缀」——路径化之后各站挂在同一个域的不同前缀下。
+ *
+ * 只列 `/oauth`：它是**授权站自己**的前缀。归一化时如果目标基址不带 `/oauth`（回滚到
+ * 老站 `oauth.wkgeo.com`，它的 `/authorize` 在站根），就必须把它剥掉，
+ * 否则会拼出 `https://oauth.wkgeo.com/oauth/authorize/`（老站没有这个路由 → 404）。
+ * 其它站前缀（`/user`、`/cms`）不该出现在授权地址里，不做猜测。
+ */
+const OAUTH_PATH_PREFIX = '/oauth';
+
+/**
+ * hostname 是否属于本平台。
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isPlatformHost(hostname) {
+  const h = String(hostname || '').toLowerCase().replace(/\.$/, '');
+  if (!h) return false;
+  return PLATFORM_ROOTS.some((root) => h === root || h.endsWith(`.${root}`));
+}
+
+/** `https://a/b/` 的路径部分，去掉结尾斜杠；空路径返回 `''` */
+function trimBasePath(pathname) {
+  return String(pathname || '').replace(/\/+$/, '');
+}
+
+/**
+ * 把 pathname 里与基址重复的段、以及已知站前缀剥掉，只留下"站内路由"。
+ * 例：基址 `/oauth`，输入 `/oauth/authorize/` → `/authorize/`
+ *     基址 ``（老站根），输入 `/oauth/authorize/` → `/authorize/`
+ */
+function siteRelativePath(pathname, basePath) {
+  let p = String(pathname || '/');
+  if (basePath && (p === basePath || p.startsWith(`${basePath}/`))) {
+    p = p.slice(basePath.length) || '/';
+  }
+  if (basePath !== OAUTH_PATH_PREFIX && (p === OAUTH_PATH_PREFIX || p.startsWith(`${OAUTH_PATH_PREFIX}/`))) {
+    p = p.slice(OAUTH_PATH_PREFIX.length) || '/';
+  }
+  if (!p.startsWith('/')) p = `/${p}`;
+  return p;
+}
+
+/**
+ * 归一化一个「用户浏览器要打开的授权站页面地址」。
+ *
+ * @param {string} rawUrl                服务端给的地址（可能是老站 / 新路径 / 本机地址 / 垃圾）
+ * @param {string} oauthWebBase          canonical 授权站基址（`config.oauthWebBase`）
+ * @param {object} [opts]
+ * @param {string} [opts.fallbackPath]   拿不到可用地址时用的站内路径（`/authorize` / `/device`）
+ * @returns {{url: string, changed: boolean, reason: 'ok'|'other_site'|'not_platform'|'unparsable'}}
+ *   * `changed` —— 地址被改写过（调用方应打一条提示，别静默）
+ *   * `reason`  —— 为什么改：
+ *       `other_site`   平台内另一个站（典型：老 `oauth.wkgeo.com`）
+ *       `not_platform` 平台之外的域名（含 `localhost` / 局域网 IP）
+ *       `unparsable`   根本不是 URL
+ */
+export function canonicalOauthUrl(rawUrl, oauthWebBase, { fallbackPath = '/' } = {}) {
+  const baseText = String(oauthWebBase || '').trim();
+  if (!baseText) {
+    // 没有基址就什么都不做 —— 调用方自己的默认值已经兜住了
+    return { url: String(rawUrl || ''), changed: false, reason: 'ok' };
+  }
+
+  let base;
+  try {
+    base = new URL(baseText);
+  } catch {
+    return { url: String(rawUrl || ''), changed: false, reason: 'ok' };
+  }
+  const basePath = trimBasePath(base.pathname);
+
+  /** 用基址 + 站内路径拼出最终地址（保留基址自身可能带的端口） */
+  const buildFromBase = (relPath, search = '', hash = '') =>
+    `${base.origin}${basePath}${relPath === '/' ? '/' : relPath}${search}${hash}`;
+
+  let u;
+  try {
+    u = new URL(String(rawUrl || ''));
+  } catch {
+    return { url: buildFromBase(fallbackPath), changed: true, reason: 'unparsable' };
+  }
+
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    return { url: buildFromBase(fallbackPath), changed: true, reason: 'not_platform' };
+  }
+
+  /*
+   * 本机/局域网地址：历史上 `authorization_endpoint` 真被配成 `http://localhost:8000`
+   * （云函数默认值没配环境变量），打开的是**用户自己机器**的端口 —— 必须纠偏。
+   */
+  const host = u.hostname.toLowerCase();
+  const isLoopback =
+    host === 'localhost' ||
+    host === '127.0.0.1' ||
+    host === '::1' ||
+    host === '[::1]' ||
+    /^127\./.test(host) ||
+    /^10\./.test(host) ||
+    /^192\.168\./.test(host) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(host);
+
+  if (!isLoopback && !isPlatformHost(host)) {
+    return { url: buildFromBase(fallbackPath), changed: true, reason: 'not_platform' };
+  }
+  if (isLoopback) {
+    return { url: buildFromBase(fallbackPath), changed: true, reason: 'not_platform' };
+  }
+
+  const relPath = siteRelativePath(u.pathname, basePath);
+  const normalized = buildFromBase(relPath, u.search, u.hash);
+
+  /**
+   * `changed` 的判定：**host 或前缀变了**才算改写。
+   * 同一个地址原样返回（服务端已经配对了、或者已经是新路径）时不能让调用方误报"纠正过"。
+   */
+  const sameHost = u.origin === base.origin;
+  const changed = !sameHost || u.pathname !== `${basePath}${relPath}`;
+  return { url: normalized, changed, reason: changed ? 'other_site' : 'ok' };
+}

package/lib/runtime.mjs

@@ -17,6 +17,8 @@
 import { parseArgv, coerceFlags, checkPositionals, resolveCommand } from './args.mjs';
 import { resolveConfig } from './config.mjs';
 import { createApi } from './api.mjs';
+import { createCms } from './cms.mjs';
+import { readSiteState, writeSiteState } from './site-state.mjs';
 import { requireCredentials, readCredentials } from './credentials.mjs';
 import { createPalette, renderTable, safeJson } from './format.mjs';
 import { UsageError, EXIT } from './errors.mjs';
@@ -169,6 +171,14 @@ export function createRuntime({
    * 或改名 —— 那是并行跑的其它用例依赖的真文件）。单测传入一个不存在的路径即可稳定覆盖该分支。
    */
   skillUrl = undefined,
+  /**
+   * `runScript` —— **同步**跑一个外部命令的注入点（目前只有 `wkgeo import` 用）。
+   *
+   * 为什么和 `spawnImpl` 分开：`spawnImpl` 是 `child_process.spawn`（异步、给浏览器用的），
+   * 而导入是一个"人盯着看进度"的阻塞动作，默认实现是 `spawnSync`。
+   * 单测注入它就能验证"参数是怎么拼的、退出码怎么转述"，**不真的去起子进程抓网站**。
+   */
+  runScript = undefined,
 } = {}) {
   const startedAt = now();
   const { positionals, flags: rawFlags } = parseArgv(argv);
@@ -196,6 +206,14 @@ export function createRuntime({
 
   const api = createApi({ config, fetchImpl });
 
+  /**
+   * CMS 客户端（栏目 / 内容 / 素材 / 模板）。
+   *
+   * 它的地址、鉴权头、错误翻译都在 `lib/cms.mjs` 里；这里只把运行时依赖给它。
+   * 懒不懒加载无所谓：`createCms` 只是记住 base 与超时，不发任何请求。
+   */
+  const cms = createCms({ config, fetchImpl });
+
   /**
    * 代理检测结果：**懒加载 + 记忆化**。
    *
@@ -223,8 +241,12 @@ export function createRuntime({
   const meta = () => {
     const m = {
       base: config.base,
+      /** CMS 面是另一个地址：出问题时"打的是哪个 CMS"必须能从信封里看出来 */
+      cms_base: config.cmsBase,
       client_id: config.clientId,
       credentials_file: config.credentialsFile,
+      /** 本地"当前站点"记录（排障时要能一眼看到它到底读的哪个文件） */
+      site_file: config.siteStateFile,
       duration_ms: Math.max(0, now() - startedAt),
     };
     // 只有"真的探测过"才带这个字段：没探测过 = 结论未知，不该编一个 false 出来
@@ -244,6 +266,10 @@ export function createRuntime({
     env,
     now,
     meta,
+    /** CMS 接口基址（`site use` / 报错提示里要用；**不是**平台面那个 base） */
+    cmsBase: config.cmsBase,
+    /** 本地"当前站点"记录文件（`wkgeo site use` 写它） */
+    siteStateFile: config.siteStateFile,
     /** ★ 代理检测（懒加载 + 记忆化；见上面 proxyState 的说明） */
     proxyInfo,
     /** 透传给 login/device 的依赖（见上面 createRuntime 的说明） */
@@ -276,6 +302,61 @@ export function createRuntime({
       const creds = opts.credentials || runtime.requireAuth({ allowExpired: opts.allowExpired });
       return api.data(action, payload, { token: creds.access_token });
     },
+    /**
+     * **本次要操作哪个站**（CMS 命令的站点来源）。
+     *
+     * 优先级（高 → 低）：
+     *   1. `--site <站点ID>`（一次性覆盖，不改本地记录）；
+     *   2. 环境变量 `WKONGAI_SITE`（CI / 脚本里固定下来）；
+     *   3. 本地 `wkgeo site use` 选中的那个（`~/.wkongai/config.json`）；
+     *   4. **都没有 ⇒ `id: ''`（不带 `x-cms-site` 头）**，由服务端按令牌的成员关系判定
+     *      （一个成员站 → 就用它；多个 → 服务端回 400 让我们指定）。
+     *
+     * ⚠️ 为什么第 4 档不直接报错：Bearer 桥**故意**支持"只有一个成员站就自动用它"
+     *    （见 docs/功能-CMS认证.md 三·优先级 3），单站用户不该被迫先跑一次 `site use`。
+     *    但**多站**时绝不替用户猜：服务端回 400，`lib/cms.mjs` 会把它翻译成
+     *    "先 `wkgeo site use <站点ID>` 或加 `--site`"（`kind: cms_site_required`）。
+     *
+     * ⚠️ 为什么 `--site` 必须是**站点 id（uuid）**：CMS 的 `x-cms-site` 先按 `id::text` 查，
+     *    再按 Host 兜底 —— CLI 没有 Host，传域名等于没传（会被当成"没指定"）。
+     *    这种"看起来传了其实没生效"的事最难查，所以在本地就挡住并告诉他改用 `site use <域名>`。
+     *
+     * @returns {{id:string, label:string|null, source:'flag'|'env'|'local'|'none'}}
+     * @throws {UsageError} `--site` / `WKONGAI_SITE` 不是 uuid
+     */
+    cmsSite() {
+      const flagSite = flags.site !== undefined && flags.site !== '' ? String(flags.site).trim() : '';
+      const envSite = String((env && env.WKONGAI_SITE) || '').trim();
+      const explicit = flagSite || envSite;
+      if (explicit) {
+        if (!/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(explicit)) {
+          throw new UsageError(
+            `${flagSite ? '--site' : 'WKONGAI_SITE'} 要填**站点 ID（uuid）**，收到：${explicit}\n` +
+              `传域名请先解析成 ID：\`wkgeo site use ${explicit}\`（之后不带 --site 就直接用这个站）`,
+          );
+        }
+        return { id: explicit, label: null, source: flagSite ? 'flag' : 'env' };
+      }
+      const saved = readSiteState(config.siteStateFile);
+      if (saved && saved.id) return { id: saved.id, label: saved.label || null, source: 'local' };
+      return { id: '', label: null, source: 'none' };
+    },
+    /** 调 CMS 动作：自动带 `Authorization: Bearer <token>` +（有站点时）`x-cms-site` */
+    cmsCall(action, payload = {}) {
+      const creds = runtime.requireAuth();
+      const site = runtime.cmsSite();
+      return cms.call(action, payload, { token: creds.access_token, siteId: site.id || undefined });
+    },
+    /** 读本地"当前站点"记录（没选过 = null） */
+    readSiteState() {
+      return readSiteState(config.siteStateFile);
+    },
+    /** 写本地"当前站点"记录（给了就覆盖） */
+    writeSiteState(one) {
+      return writeSiteState(config.siteStateFile, one, { now: now() });
+    },
+    /** ★ `wkgeo import` 起子进程的注入点（生产 = `spawnSync`，见 lib/local-import.mjs） */
+    runScript,
     /** 成功收尾（JSON 模式输出信封；人类模式什么都不做，由命令自己打印） */
     done(data) {
       out.emitOk(spec.name, data);

package/lib/site-state.mjs

@@ -0,0 +1,137 @@
+/**
+ * 「当前选中站点」的本地状态：**`<凭据目录>/config.json`**（默认 `~/.wkongai/config.json`）。
+ *
+ * 为什么需要它：CMS（栏目 / 内容 / 素材 / 模板）的每个动作都必须落在一个站点上，
+ * 而 CMS 的 `site_id` **只从会话或 `x-cms-site` 头里取**（body 里的 `site_id` 后端故意忽略，
+ * 见 `tencent/functions/cms/index.js` 的 `resolveSite`）。CLI 没有 Cookie 会话，
+ * 所以只能把"我这次要操作哪个站"记在本地，之后每个请求带 `x-cms-site`。
+ *
+ * 为什么不放进 `credentials.json`：
+ *   * 那个文件是**凭据**（0600、只存令牌与账号），删除它 = 退出登录；
+ *   * "选了哪个站"只是操作上下文，`logout` 不该把它一起带走，反过来重新登录也不该丢。
+ *   分成两个文件之后，两件事的语义各自清楚。
+ *
+ * 为什么放在凭据文件同目录：`--credentials` / `WKONGAI_CREDENTIALS` 已经在做"换一套身份"的隔离
+ *   （单测、多人共机、联调都靠它），站点选择跟着走最不容易串；
+ *   默认情况下就是规划文档里写的 `~/.wkongai/config.json`。
+ *
+ * ⚠️ 这个文件**不含任何秘密**（只有站点 id / 名字），但仍然用原子写 + 0600：
+ *    权限口径统一，省得以后往里加别的东西时忘了。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { CliError } from './errors.mjs';
+
+/** 状态文件版本（将来改结构时用来判断要不要迁移；现在只写不读） */
+export const SITE_STATE_VERSION = 1;
+
+/** 文件名（与规划文档一致：`~/.wkongai/config.json`） */
+export const SITE_STATE_FILE_NAME = 'config.json';
+
+/** 读原始 JSON 对象；文件不存在 / 坏掉都返回 `{}`（写路径用，绝不因为"读不懂"而写不进去） */
+function readRawObjectQuiet(file) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 读当前选中的站点。
+ *
+ * @param {string} file 状态文件路径
+ * @returns {{id:string, label:string, saved_at:string|null}|null} 没选过 → `null`
+ * @throws {CliError} 文件存在但**不是合法 JSON / 内容形状不对**（明确报错，不静默当"没选"——
+ *   否则用户会一直看到"还没有选择站点"，却不知道自己有个坏文件在那儿）
+ */
+export function readSiteState(file) {
+  if (!file) return null;
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return null;
+    throw new CliError(`读取本地站点配置失败：${e.message}`, {
+      kind: 'config',
+      hint: `文件位置：${file}`,
+      cause: e,
+    });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (e) {
+    throw new CliError(`本地站点配置不是合法 JSON：${file}`, {
+      kind: 'config',
+      hint: '删掉它，或重新运行 `wkgeo site use <站点ID>`（会覆盖写入）',
+      cause: e,
+    });
+  }
+  const one = parsed && typeof parsed === 'object' ? parsed.cms_site : null;
+  if (!one || typeof one !== 'object' || !one.id) return null;
+  return {
+    id: String(one.id),
+    label: String(one.label || ''),
+    saved_at: one.saved_at || null,
+  };
+}
+
+/**
+ * 记住"当前站点"（**保留文件里的其它键**：以后往里放别的本地设置时不用改这里）。
+ *
+ * @param {string} file
+ * @param {{id:string, label?:string}} site
+ */
+export function writeSiteState(file, site, { now = Date.now() } = {}) {
+  const id = String((site && site.id) || '').trim();
+  if (!id) throw new CliError('内部错误：写本地站点配置时缺少站点 id');
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  const payload = {
+    version: SITE_STATE_VERSION,
+    ...readRawObjectQuiet(file),
+    cms_site: {
+      id,
+      label: String((site && site.label) || ''),
+      saved_at: new Date(now).toISOString(),
+    },
+  };
+
+  const tmp = `${file}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmp, 'w', 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  return payload.cms_site;
+}
+
+/**
+ * 取消选中（`wkgeo site use --clear`）。
+ *
+ * @returns {boolean} 之前有没有选中过（用来决定提示文案）
+ */
+export function clearSiteState(file) {
+  const raw = readRawObjectQuiet(file);
+  const had = Boolean(raw.cms_site && raw.cms_site.id);
+  delete raw.cms_site;
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = `${file}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmp, 'w', 0o600);
+  try {
+    fs.writeFileSync(fd, JSON.stringify({ version: SITE_STATE_VERSION, ...raw }, null, 2) + '\n', 'utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, file);
+  return had;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkgeo-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "云站平台官方命令行客户端：授权登录一次，之后建站 / 下单 / 钱包支付 / 查余额都不用再登录（OAuth 授权码 + PKCE，公共客户端，零第三方依赖）",
   "keywords": [
     "wkgeo",