wkgeo-cli 0.2.0 → 0.2.1

package/lib/cms.mjs

@@ -0,0 +1,317 @@
+/**
+ * CMS 接口客户端 —— 客户站后台那一套动作（栏目 / 内容 / 素材 / 模板）。
+ *
+ * ## 接口形态（照 `tencent/functions/cms/index.js` 的动作表，别自己编）
+ *   `POST {CMS_BASE}/<action>`，JSON body，响应统一信封 `{code, message, data}`，
+ *   `code === 0` 才算成功 —— 与 `/api/data` 完全同一套约定。
+ *   `CMS_BASE` 默认 `https://api.wkgeo.com/cms`（`--cms-base` / `WKONGAI_CMS_BASE` 可覆盖），
+ *   动作名就是动作表的键（`categoryList` / `contentSave` / `templateGet` …），**URL 最后一段就是动作名**：
+ *   云函数支持"从路径取动作"（`actionFromPath`），所以 `/api/cms/categoryList` 与
+ *   `body.action = 'categoryList'` 等价；这里用路径写法，身体里只放业务参数（干净、可读）。
+ *
+ * ## 认证（**当前最大的外部依赖**）
+ *   CLI 手里只有 OAuth 的 Bearer 令牌，而 CMS 原本只认 `cms_session` Cookie。
+ *   两条通道由**另一个任务**在 `tencent/functions/cms` 里加："Bearer 令牌 → 用户 → 站点成员"。
+ *   ⇒ 所以这里有两条硬规矩：
+ *     1. 请求一律带 `Authorization: Bearer <token>`（桥上线后立刻可用，CLI 侧一行不用改）；
+ *     2. **桥还没上线时（服务端回 401）必须给一句人能照做的话**，不能把
+ *        "登录已过期，请重新登录" 原样甩出去 —— 那句话会让用户以为是自己令牌的问题，
+ *        而真实原因多半是"服务端还没启用 CLI 认证"（见 `cmsAuthCliError`）。
+ *
+ * ## 站点边界
+ *   站 id 一律走 **`x-cms-site` 头**（`resolveSite` 的第一优先级）。
+ *   ⚠️ 头的值必须是**站点 id（uuid）**：后端先按 `id::text` 精确查，再按 Host 兜底；
+ *   CLI 没有 Host，所以传域名等于没传（这是踩不出响声的坑，`runtime.cmsSite()` 里提前挡掉）。
+ *
+ * ## 为什么错误翻译放在这一层
+ *   命令层有十几个，逐个写"401 怎么说"迟早写歪。所有 CMS 响应只在 `unwrap()` 一处判定，
+ *   命令层拿到的要么是 `data`，要么是一个**带中文 hint 的 CliError**。
+ */
+
+import { request } from './http.mjs';
+import { CliError, EXIT, classifyResponse, networkError, toCliError } from './errors.mjs';
+
+/**
+ * 动作名（与 `tencent/functions/cms/index.js` 的 `actionTable` 一一对应）。
+ *
+ * 只列 CLI 用到的那些 —— 全表在云函数里，这里不是"权威清单"，
+ * 但用它代替散落在命令层的中英混排字符串，避免 `categorylist` 这类大小写手滑（后端会回"未知动作"）。
+ */
+export const CMS_ACTIONS = {
+  // 概览（发布状态用）
+  overview: 'overview',
+  me: 'me',
+  // 栏目
+  categoryList: 'categoryList',
+  categoryGet: 'categoryGet',
+  categorySave: 'categorySave',
+  categoryDelete: 'categoryDelete',
+  // 内容
+  contentList: 'contentList',
+  contentGet: 'contentGet',
+  contentSave: 'contentSave',
+  contentDelete: 'contentDelete',
+  // 素材（图片直传：签名 → 直传 OSS → 登记）
+  assetSign: 'assetSign',
+  assetRegister: 'assetRegister',
+  assetList: 'assetList',
+  // 模板
+  templateList: 'templateList',
+  templateGet: 'templateGet',
+  templateFileSave: 'templateFileSave',
+  // 前台渲染（免登录，发布说明里要引用它）
+  pageRender: 'pageRender',
+};
+
+/**
+ * 「服务端没接受 CLI 的令牌」时给的话。
+ *
+ * ## 为什么不能只写"请重新登录"
+ *   把令牌问题和服务端没上线混成一句，会让用户白跑一遍浏览器授权：
+ *   `whoami` 明明正常、`categories list` 却永远 401 —— 那是**桥没上线**，重登一万次也没用。
+ *
+ * ## 为什么同时给两种可能
+ *   本地能判定的只有"凭据没过期"（`requireAuth` 已经挡掉了本地过期的），
+ *   但服务端吊销 / 令牌被清掉是本地看不出来的。所以按可能性排序给两条路，
+ *   并明确说"CLI 侧不需要改"——省得用户去装新版、改 base。
+ */
+function cmsAuthCliError(action, raw) {
+  const text = String((raw && raw.message) || '服务端没有给出原因');
+  return new CliError(`CMS 接口没有接受 CLI 的授权令牌（${action}）：${text}`, {
+    kind: 'cms_auth',
+    code: (raw && raw.code !== undefined && raw.code !== null) ? raw.code : 401,
+    exitCode: EXIT.AUTH,
+    hint:
+      '① 最常见的原因是令牌已过期 / 被吊销：运行 `wkgeo login` 重新授权即可；' +
+      '② 若刚授权仍报 401（且 `wkgeo whoami` 正常），说明服务端是**旧部署** —— ' +
+      '还没启用 CLI 认证桥（OAuth Bearer 令牌 → CMS 站点成员），联系管理员升级云函数 `cms` 即可，CLI 侧不需要改。',
+    raw: { action, body: raw },
+  });
+}
+
+/**
+ * 「接口本身摸不到」时给的话（地址错 / 云函数没部署 / 网关返回 HTML）。
+ *
+ * 这一类**不是**令牌问题，绝不能引导去重新授权 —— 否则用户会陷入"重登 → 还是失败"的死循环。
+ */
+function cmsUnavailableError(action, res) {
+  const status = res && res.status ? res.status : 0;
+  const snippet = String((res && res.text) || '').replace(/\s+/g, ' ').slice(0, 200);
+  return new CliError(`CMS 接口不可用（${action}，HTTP ${status || '无响应'}）${snippet ? `：${snippet}` : ''}`, {
+    kind: 'cms_unavailable',
+    code: status || null,
+    hint:
+      '检查 `wkgeo config` 里的 CMS 基址（默认 `https://api.wkgeo.com/cms`，' +
+      '可用 `--cms-base` / `WKONGAI_CMS_BASE` 临时切换）；若地址没错，多半是云函数 `cms` 还没部署。',
+  });
+}
+
+/**
+ * **403 的三种含义要分开说**（Bearer 桥上线后这三种都会真实出现，混成一句就没法照做）。
+ *
+ *   1. 「你不是该站点的成员」/「你不是任何 CMS 站点的成员」→ 站点选错了 / 还没被邀请；
+ *   2. 「只读账号不能修改…」→ 站点角色是 viewer（有权限但只读）；
+ *   3. 「该令牌没有执行「X」的权限（需要 site:write …）」→ **scope** 不够，得重新授权。
+ *
+ * 另外 400 有一种固定文案：「这个账号有 N 个站点，请用 x-cms-site 头或 body._site 指定」——
+ * 那是"没选站 + 多成员站"，引导用户去 `wkgeo site use`。
+ */
+function cmsPolicyError(action, body) {
+  const message = String((body && body.message) || '无权限');
+  const code = body && body.code !== undefined ? body.code : 403;
+
+  if (/不是该站点的成员|不是任何 CMS 站点的成员/.test(message)) {
+    return new CliError(`CMS 拒绝访问（${action}）：${message}`, {
+      kind: 'cms_not_member',
+      code,
+      hint:
+        '站点 ID 不对或你不是它的成员：用 `wkgeo site use <正确的站点ID>` 重新选（`--site` 只影响一次）；' +
+        '如果是别人邀请你协作的站，需要该站 owner 先在后台把你加进成员。',
+    });
+  }
+  if (/只读账号/.test(message)) {
+    return new CliError(`CMS 拒绝写入（${action}）：${message}`, {
+      kind: 'cms_readonly',
+      code,
+      hint: '你这个站点角色是 viewer（只读）：让该站 owner 在后台「用户与角色」里把你提升为 editor。',
+    });
+  }
+  if (/没有执行|需要\s*site:write|需要\s*template:write|需要\s*attachment/.test(message)) {
+    return new CliError(`CMS 拒绝执行（${action}）：${message}`, {
+      kind: 'cms_scope',
+      code,
+      hint:
+        '令牌的能力（scope）不够：直接 `wkgeo login` 重新授权一次即可' +
+        '（CLI 现在的默认 scope 已含 site / template / attachment 三组）；' +
+        '要精确控制就写 `wkgeo login --scope "<原有 scope> <缺的那个>"`。' +
+        '⚠️ 升级前授权的**旧令牌**不会自动获得新能力，必须重新 login。',
+    });
+  }
+  if (/请用\s*x-cms-site|指定站点/.test(message)) {
+    return new CliError(`还没有确定站点（${action}）：${message}`, {
+      kind: 'cms_site_required',
+      code,
+      hint: '你的账号有多个站点，必须指明一个：`wkgeo site use <站点ID>`（记住），或本命令加 `--site <站点ID>`。',
+    });
+  }
+  return null;
+}
+
+/**
+ * 建一个 CMS 客户端。
+ *
+ * @param {object} args
+ * @param {object} args.config      `resolveConfig()` 的结果（只用 `cmsBase` / `httpTimeoutMs`）
+ * @param {Function} [args.fetchImpl]
+ */
+export function createCms({ config, fetchImpl = globalThis.fetch } = {}) {
+  const base = String((config && config.cmsBase) || '').replace(/\/+$/, '');
+  const timeoutMs = (config && config.httpTimeoutMs) || 30000;
+
+  async function raw(url, options = {}) {
+    return request(url, { ...options, fetchImpl, timeoutMs: options.timeoutMs ?? timeoutMs });
+  }
+
+  /**
+   * 判定成败 + 翻译错误（**全模块唯一一处**）。
+   * @returns `{code,message,data}` 里的 `data`（没有就是 null）
+   */
+  function unwrap(res, action) {
+    if (res.networkError) throw networkError(res.networkError, { raw: res });
+
+    /**
+     * 没有 JSON 响应体 = 打到的不是 CMS 云函数：
+     *   * 网关 404 / 502 的 HTML 错误页；
+     *   * 或者云函数没部署、路径没配。
+     * 这两种都不该按"业务错误"处理（也就不会有 code 可看）。
+     */
+    if (!res.body) {
+      if (res.status >= 200 && res.status < 300) {
+        // 200 但空体：极少见（网关吞了响应），当成功但无数据，别硬报错
+        return null;
+      }
+      throw cmsUnavailableError(action, res);
+    }
+
+    const cls = classifyResponse({
+      httpStatus: res.status,
+      body: res.body,
+      action,
+      retryAfterHeader:
+        res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null,
+      cmdName: (config && config.cmdName) || 'wkgeo',
+    });
+
+    if (cls.ok) {
+      const body = res.body;
+      return body && Object.prototype.hasOwnProperty.call(body, 'data') ? body.data : body;
+    }
+
+    /**
+     * 401 家族：可能是令牌真过期，也可能是桥没上线/没部署 —— 单独一段话（见 cmsAuthCliError）
+     */
+    if (cls.kind === 'expired' || cls.kind === 'revoked' || cls.kind === 'unauthenticated') {
+      throw cmsAuthCliError(action, res.body);
+    }
+
+    /**
+     * 403 / 400 里有几类**含义完全不同**的业务拒绝（不是成员 / 只读角色 / scope 不够 / 没定站），
+     * 通用 hint（"scope 不足"或"去网页后台做"）会把它们全说错 —— 先按文案细分。
+     */
+    if (cls.kind === 'forbidden' || cls.kind === 'bad_request' || cls.code === 403 || cls.code === 400) {
+      const policy = cmsPolicyError(action, res.body);
+      if (policy) throw policy;
+    }
+
+    /**
+     * 「未知动作」= CLI 与服务端版本不一致（新动作还没部署）。
+     * 这条错误原本是 `未知动作：templateFileSave`，对用户等于没说，所以补一句"是服务端缺口"。
+     */
+    if (String(cls.message || '').includes('未知动作')) {
+      throw new CliError(`服务端还没有这个动作：${action}`, {
+        kind: 'not_deployed',
+        code: cls.code,
+        hint: '这是**服务端缺口**（云函数 `cms` 版本落后），不是命令写错；等后端部署后重试，CLI 不需要升级。',
+      });
+    }
+
+    throw toCliError(cls, { action, raw: { status: res.status, body: res.body } });
+  }
+
+  return {
+    base,
+
+    /**
+     * 调一个 CMS 动作。
+     *
+     * @param {string} action 动作名（用 `CMS_ACTIONS` 里的常量，别手写）
+     * @param {object} [body] 业务参数（**不要**往这里塞 `site_id`：后端一律忽略，站点走 `x-cms-site`）
+     * @param {{token?:string, siteId?:string}} [opts]
+     * @returns {Promise<any>} 信封里的 `data`
+     */
+    async call(action, body = {}, { token, siteId } = {}) {
+      if (!action) throw new CliError('内部错误：缺少 CMS 动作名');
+      if (!base) throw new CliError('内部错误：CMS 基址为空（检查 WKONGAI_CMS_BASE）');
+      const headers = {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      };
+      if (token) headers.Authorization = `Bearer ${token}`;
+      if (siteId) headers['x-cms-site'] = String(siteId);
+      const res = await raw(`${base}/${action}`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body || {}),
+      });
+      return unwrap(res, action);
+    },
+  };
+}
+
+/**
+ * 把文件真正传上 OSS（**直传**：CLI 不碰 AK，也不会把二进制塞进云函数请求体）。
+ *
+ * 流程（与 `tencent/functions/cms` 的 `signDirectUpload` 对应）：
+ *   ① `assetSign` 拿票据（key / uploadUrl / fields 都锁死，10 分钟过期）；
+ *   ② 用 `multipart/form-data` POST 到 OSS（`fields` 在前，`file` **必须是最后一个字段**，
+ *      OSS 的 PostObject 要求如此）；
+ *   ③ 回 `assetRegister` 落库（它会回读一次 OSS，确认文件真的在）。
+ *
+ * ⚠️ `fields` 里有 `Content-Type`，而 multipart 的每个字段都要有自己的一段 — 直接
+ *    `form.append('Content-Type', ...)` 是对的（OSS 把它当表单字段读），**不要**改成请求头，
+ *    改了就破坏 boundary。
+ *
+ * @param {object} args
+ * @param {{uploadUrl:string, fields:Record<string,string>, mime:string}} args.ticket
+ * @param {Buffer} args.buffer      文件字节
+ * @param {string} args.fileName    文件名（客户端名，用来给 OSS 那一段命名）
+ * @returns {Promise<{status:number, text:string}>}
+ */
+export async function uploadToOss({ ticket, buffer, fileName, fetchImpl = globalThis.fetch, timeoutMs = 120000 }) {
+  const form = new FormData();
+  for (const [k, v] of Object.entries((ticket && ticket.fields) || {})) {
+    if (v === undefined || v === null) continue;
+    form.append(String(k), String(v));
+  }
+  /** `file` 必须最后追加（OSS PostObject 的约定） */
+  form.append('file', new Blob([buffer], { type: (ticket && ticket.mime) || 'application/octet-stream' }), String(fileName || 'file'));
+
+  const res = await request(String(ticket.uploadUrl), {
+    method: 'POST',
+    body: form,
+    /** ⚠️ 这里**绝不能**设 Content-Type：boundary 由 fetch 自己生成 */
+    headers: {},
+    fetchImpl,
+    timeoutMs,
+  });
+  if (res.networkError) throw networkError(`上传到素材库失败：${res.networkError}`, { raw: res });
+  if (res.status < 200 || res.status >= 300) {
+    const snippet = String(res.text || '').replace(/\s+/g, ' ').slice(0, 300);
+    throw new CliError(`上传到素材库失败（OSS HTTP ${res.status}）${snippet ? `：${snippet}` : ''}`, {
+      kind: 'upload_failed',
+      code: res.status,
+      hint: '票据 10 分钟过期，重新运行本命令即可；若一直是 403，检查素材桶的跨域/签名配置（服务端 OSS_ACCESS_KEY_*）',
+    });
+  }
+  return { status: res.status, text: String(res.text || '').slice(0, 200) };
+}

package/lib/commands/auth.mjs

@@ -165,7 +165,7 @@ function deviceStoppedError() {
  *    宁可让那次后台轮询在下一轮自己发现 `shouldStop()` 并退出，也不能把用户的登录卡在这里。
  * ⚠️ `deviceSide.promise` 内部两个分支都已 catch（不会 reject），这里 await 它不会抛。
  */
-async function 停掉设备码那条路(deviceSide, cancelGate) {
+async function stopDeviceCodeFlow(deviceSide, cancelGate) {
   if (!deviceSide.promise) return;
   deviceSide.cancelled = true;
   cancelGate.wakeAll();
@@ -434,7 +434,7 @@ export const loginCommand = {
 
     const pendingFile = pendingDeviceFile(config.credentialsFile);
     /** 申请到码之后立刻落盘：进程被 Ctrl+C / 终端被关掉，用户还能用 --device-continue 续上 */
-    const 保存待完成 = (device) => {
+    const savePending = (device) => {
       try {
         savePendingDevice(pendingFile, { ...device, base: config.base, client_id: config.clientId });
         return true;
@@ -494,7 +494,7 @@ export const loginCommand = {
     if (!result && useDevice) {
       try {
         const device = await requestDeviceCode({ config, deps: loginDeps });
-        保存待完成(device);
+        savePending(device);
         if (noWait) {
           /**
            * ★ AI 端友好路径：打印完就退出（不轮询）。
@@ -588,11 +588,11 @@ export const loginCommand = {
       /** 交接面：两边各填一半（`onSwitch` 由这里填，另两个由 runLogin 填；见 login.mjs 的 deps 说明） */
       const handoff = { onSwitch: null, finishWithDevice: null, abort: null };
 
-      const 跑设备码那条路 = async () => {
+      const runDeviceCodeFlow = async () => {
         const device = await requestDeviceCode({ config, deps: loginDeps });
         // 回调那条路已经赢了 → 一个用户可见的动作都不要再做（不打印短码、不弹浏览器、不落盘）
         if (deviceSide.cancelled) throw deviceStoppedError();
-        保存待完成(device);
+        savePending(device);
         if (deviceSide.cancelled) throw deviceStoppedError();
         announceDeviceCode({ config, log, deps: deviceDeps({ no_wait: false, proxy_warning: proxyPayload }), device });
         return pollDeviceToken({
@@ -616,7 +616,7 @@ export const loginCommand = {
            *    成功 → `finishWithDevice` 让回调流程带着这份结果收尾（监听留 grace）；
            *    失败 → `abort` 让回调流程用"两条路都不通"的错误结束（用户要看的是真原因）。
            */
-          deviceSide.promise = 跑设备码那条路().then(
+          deviceSide.promise = runDeviceCodeFlow().then(
             (res) => {
               deviceSide.result = res;
               if (typeof handoff.finishWithDevice === 'function') handoff.finishWithDevice(res);
@@ -664,7 +664,7 @@ export const loginCommand = {
         });
       } catch (e) {
         /** ★ 无论怎么失败，都先把设备码那条路收拾干净（不能留一个还在轮询的后台任务） */
-        await 停掉设备码那条路(deviceSide, cancelGate);
+        await stopDeviceCodeFlow(deviceSide, cancelGate);
         /** 设备码那条路也失败了 ⇒ 优先报"两条路都不通"（哪怕回调那边先抛了自己的错） */
         if (deviceSide.combinedError) throw deviceSide.combinedError;
         /**
@@ -680,9 +680,9 @@ export const loginCommand = {
           autoDevice && !wantsDevice && (e.kind === 'callback_first_wait' || e.kind === 'timeout' || e.kind === 'listen');
         if (!canSwitch) throw e;
         log('');
-        const 原因 =
+        const reason =
           e.kind === 'timeout' ? '等待超时' : e.kind === 'listen' ? '本地端口监听失败' : '首轮等待没收到回调';
-        log(`⚠️ 本地回调没有等到结果（${原因}）：${e.message}`);
+        log(`⚠️ 本地回调没有等到结果（${reason}）：${e.message}`);
         if (e.kind === 'callback_first_wait') {
           log('ℹ️ 等了这一小段时间没收到回调，已自动改用**设备码模式**继续（不需要本地回调）。');
         } else {
@@ -696,7 +696,7 @@ export const loginCommand = {
             loginTimeoutMs: config.loginTimeoutMs,
           });
         }
-        保存待完成(device);
+        savePending(device);
         announceDeviceCode({ config, log, deps: deviceDeps({ no_wait: false, proxy_warning: proxyPayload }), device });
         // 这一次再失败就如实抛出（不无限重试：两条路都失败，用户该看到真原因了）
         result = await pollDeviceToken({ config, log, deps: loginDeps, device });
@@ -730,7 +730,7 @@ export const loginCommand = {
            */
           deviceSide.cancelled = true;
           cancelGate.wakeAll();
-          await 停掉设备码那条路(deviceSide, cancelGate);
+          await stopDeviceCodeFlow(deviceSide, cancelGate);
           deletePendingDevice(pendingFile);
           log('ℹ️ 本地回调已经拿到令牌：设备码那条路已停止（刚才那个短码作废，不用再去浏览器里确认）。');
         }
@@ -903,8 +903,25 @@ export const configCommand = {
      */
     const proxy = proxyWarningPayload(ctx.proxyInfo(), { cmdName: config.cmdName || 'wkgeo' });
 
+    /**
+     * 本地"当前站点"（`wkgeo site use` 选的）。
+     * ⚠️ 诊断命令**不能**因为一个坏文件就整体失败：读失败时如实报出来，其它信息照常给。
+     */
+    let cmsSite = null;
+    let cmsSiteError = null;
+    try {
+      cmsSite = ctx.readSiteState();
+    } catch (e) {
+      cmsSiteError = (e && e.message) || String(e);
+    }
+
     const data = {
       base: config.base,
+      /**
+       * CMS 面（栏目/内容/素材/模板）是**另一个云函数、另一个域名**，
+       * 所以单独列一行 —— 排查"CMS 命令为什么 404"时第一眼看的就是它。
+       */
+      cms_base: config.cmsBase,
       /**
        * ⚠️ `web_base` 是**兼容字段**：三站拆分后它指向老站（管理端），
        * 已经没有任何代码用它打开页面 —— 保留只为不破坏既有自动化脚本。
@@ -920,6 +937,10 @@ export const configCommand = {
       callback: `http://${config.callbackHost}:${config.callbackPort}${config.callbackPath}`,
       http_timeout_ms: config.httpTimeoutMs,
       login_timeout_ms: config.loginTimeoutMs,
+      /** 本地"当前站点"（CMS 命令用；`site use` 写的） */
+      cms_site: cmsSite,
+      cms_site_file: config.siteStateFile,
+      cms_site_error: cmsSiteError,
       sources,
       logged_in: !!creds,
       expired: creds ? isExpired(creds, { now: ctx.now() }) : null,
@@ -934,6 +955,7 @@ export const configCommand = {
       out.head('生效配置');
       for (const [k, v] of Object.entries({
         'API 基址': data.base,
+        'CMS 接口基址': data.cms_base,
         '授权站基址': data.oauth_web_base,
         '收银台基址': data.pay_web_base,
         '会员站基址': data.user_web_base,
@@ -945,6 +967,15 @@ export const configCommand = {
       })) {
         out.line(`  ${k}：${v}`);
       }
+      out.line(
+        `  当前站点：${
+          data.cms_site && data.cms_site.id
+            ? `${data.cms_site.label ? `${data.cms_site.label}（` : ''}${data.cms_site.id}${data.cms_site.label ? '）' : ''}`
+            : data.cms_site_error
+              ? `⚠️ 读取失败：${data.cms_site_error}`
+              : '未选（CMS 命令前先 `wkgeo site use <站点ID或域名>`）'
+        }`,
+      );
       out.line(`  登录状态：${data.logged_in ? (data.expired ? '已过期（需重新 login）' : '已登录') : '未登录'}`);
       if (data.logged_in) {
         out.line(`  账号：${(data.account && (data.account.email || data.account.user_id)) || '-'}`);