@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/config.js

@@ -0,0 +1,407 @@
+// 配置与凭据落盘（契约 §4）。
+//
+// 两个文件，都在 `~/.config/xinhe-oa-cli/`（`XINHE_OA_CONFIG_DIR` 可覆盖）：
+//
+// | 文件               | 权限   | 内容                                              |
+// |--------------------|--------|---------------------------------------------------|
+// | `config.json`      | `0600` | profile（后端地址、代理策略）与当前选中的 profile  |
+// | `credentials.json` | `0600` | 每个 profile 一份：`device_id` + 令牌 + 用户摘要   |
+//
+// 目录 `0700`、文件 `0600`：这两个文件里有机密（refresh 令牌），
+// 同机器上的其它用户不该读到。凭据只由 CLI 读写 —— **不进 argv、不进日志**。
+//
+// **与 Rust 版逐字节兼容**：文件形状是跨实现的契约。老用户用 Rust 版登过录，
+// 换成 Node 版必须**继续用得上**（同一个目录、同一份 JSON、同一个 device_id）——
+// 否则每换一次实现就要重新短信登录一次，而 `device_id` 一变，服务端的
+// `HMAC(UA + X-Device-Id)` 绑定立刻 `auth.device_mismatch`。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from './error.js';
+import { rustIoErrorText } from './util.js';
+import { nowRfc3339 } from './util.js';
+
+export const DEFAULT_PROFILE = 'default';
+
+/** 目录/文件的 Unix 权限位（Windows 上这两个调用是 no-op）。 */
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+
+function envNonEmpty(key) {
+  const value = process.env[key];
+  return value && value.trim().length > 0 ? value : null;
+}
+
+/** 配置目录与两个文件的位置。 */
+export class Paths {
+  constructor(dir) {
+    this.dir = dir;
+  }
+
+  /**
+   * 解析配置目录（按优先级）：
+   *
+   * 1. `XINHE_OA_CONFIG_DIR` —— 显式指定，测试与多环境隔离用；
+   * 2. **Windows**：`APPDATA\xinhe-oa-cli`（`%APPDATA%` 是 Windows 的漫游配置目录），
+   *    退而用 `USERPROFILE\.config\xinhe-oa-cli`；
+   * 3. 类 Unix：`XDG_CONFIG_HOME/xinhe-oa-cli`，再退 `$HOME/.config/xinhe-oa-cli`。
+   *
+   * **为什么 Windows 单独处理**：cmd.exe / PowerShell 默认不设 `HOME`
+   * （只有 `USERPROFILE`）。只认 `HOME` 的话 Windows 用户第一次运行就拿到
+   * "找不到 HOME 环境变量" —— 而这句话对 Windows 用户毫无指导意义。
+   */
+  static resolve() {
+    const explicit = envNonEmpty('XINHE_OA_CONFIG_DIR');
+    if (explicit) return new Paths(explicit);
+
+    if (process.platform === 'win32') {
+      const appdata = envNonEmpty('APPDATA');
+      if (appdata) return new Paths(path.join(appdata, 'xinhe-oa-cli'));
+      const profile = envNonEmpty('USERPROFILE');
+      if (profile) return new Paths(path.join(profile, '.config', 'xinhe-oa-cli'));
+    } else {
+      const xdg = envNonEmpty('XDG_CONFIG_HOME');
+      if (xdg) return new Paths(path.join(xdg, 'xinhe-oa-cli'));
+    }
+
+    const home = envNonEmpty('HOME') ?? envNonEmpty('USERPROFILE');
+    if (!home) {
+      const hint =
+        process.platform === 'win32'
+          ? 'Windows 上请确认 USERPROFILE 或 APPDATA 存在（正常安装的 Windows 都有），或用 XINHE_OA_CONFIG_DIR=<目录> 指定配置目录'
+          : '设置 HOME，或用 XINHE_OA_CONFIG_DIR=<目录> 指定配置目录';
+      throw CliError.usage('找不到用户主目录，无法定位配置目录').withHint(hint);
+    }
+    return new Paths(path.join(home, '.config', 'xinhe-oa-cli'));
+  }
+
+  get configFile() {
+    return path.join(this.dir, 'config.json');
+  }
+
+  get credentialsFile() {
+    return path.join(this.dir, 'credentials.json');
+  }
+
+  /**
+   * 断点续传记录目录（`<config>/checkpoints/`）。
+   *
+   * 放配置目录而不是当前工作目录：导入可以在任何目录下发起，
+   * "换个目录重跑就找不到上次的进度"正是续传最容易被废掉的方式。
+   */
+  get checkpointsDir() {
+    return path.join(this.dir, 'checkpoints');
+  }
+
+  /** 建目录并**把权限收成 0700**（已存在也要收：别人可能建成了 0755）。 */
+  ensureDir() {
+    try {
+      fs.mkdirSync(this.dir, { recursive: true, mode: DIR_MODE });
+    } catch (err) {
+      throw CliError.usage(`建不了配置目录 ${this.dir}：${rustIoErrorText(err)}`);
+    }
+    if (process.platform !== 'win32') {
+      try {
+        // 已存在的目录不会被 mkdir 的 mode 改到，这里再收一次。
+        fs.chmodSync(this.dir, DIR_MODE);
+      } catch (err) {
+        throw CliError.usage(`配置目录权限收不紧（应为 0700）：${this.dir}：${err.message}`);
+      }
+    }
+  }
+}
+
+/**
+ * 写文件：**先收权限再写内容**，避免"先落明文、后 chmod"的窗口。
+ *
+ * 顺序是硬要求：`open(..., {mode: 0600})` 在创建时就把权限定死，
+ * 写完再 `chmod` 只兜"文件早就存在、权限被别人放宽了"这一种情况。
+ */
+function writePrivate(target, content) {
+  let fd;
+  try {
+    fd = fs.openSync(target, 'w', FILE_MODE);
+    fs.writeFileSync(fd, content);
+    fs.fsyncSync(fd);
+  } catch (err) {
+    throw CliError.usage(`写不了 ${target}：${rustIoErrorText(err)}`);
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        /* 关不掉就算了：内容已经落盘 */
+      }
+    }
+  }
+  if (process.platform !== 'win32') {
+    try {
+      fs.chmodSync(target, FILE_MODE);
+    } catch (err) {
+      throw CliError.usage(`${target} 权限收不紧：${err.message}`);
+    }
+  }
+}
+
+function readJson(target) {
+  let text;
+  try {
+    text = fs.readFileSync(target, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw CliError.usage(`读不了 ${target}：${rustIoErrorText(err)}`);
+  }
+  if (text.trim().length === 0) return null;
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw CliError.usage(`${target} 不是合法 JSON：${err.message}`).withHint(
+      '可以删掉它重新配置：xinhe-oa-cli config --set base_url=<地址>',
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// config.json：profile 与代理策略
+// ---------------------------------------------------------------------------
+/** 出网代理策略（值就两个字符串，序列化成小写，与 Rust 的 serde 一致）。 */
+export const ProxyMode = Object.freeze({
+  /** 尊重进程环境里的 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 与 `NO_PROXY`（默认）。 */
+  System: 'system',
+  /** 完全不走代理（客户在**内网直连**后端时用这个）。 */
+  None: 'none',
+});
+
+/** 解析 proxy 取值：`system` / `env` / 空 → system；`none` / `off` / `direct` → none。 */
+export function parseProxyMode(raw) {
+  const text = String(raw ?? '').trim().toLowerCase();
+  if (text === 'system' || text === 'env' || text === '') return ProxyMode.System;
+  if (text === 'none' || text === 'off' || text === 'direct') return ProxyMode.None;
+  throw CliError.usage(`proxy 只能是 system 或 none，收到 ${JSON.stringify(text)}`).withHint(
+    'xinhe-oa-cli config --set proxy=none（内网直连）| proxy=system（默认）',
+  );
+}
+
+/** config.json 的读写。 */
+export class ConfigStore {
+  constructor(paths, file) {
+    this.paths = paths;
+    this.file = file ?? { current: '', profiles: {} };
+    if (!this.file.profiles || typeof this.file.profiles !== 'object') this.file.profiles = {};
+  }
+
+  static load(paths) {
+    const raw = readJson(paths.configFile);
+    return new ConfigStore(paths, raw ?? { current: '', profiles: {} });
+  }
+
+  /** 当前 profile 名（`config --use` 切换；默认 `default`）。 */
+  currentName() {
+    const current = this.file.current;
+    return typeof current === 'string' && current.trim().length > 0 ? current : DEFAULT_PROFILE;
+  }
+
+  profile(name) {
+    const found = this.file.profiles[name];
+    return found && typeof found === 'object' ? found : {};
+  }
+
+  currentProfile() {
+    return this.profile(this.currentName());
+  }
+
+  names() {
+    const names = Object.keys(this.file.profiles).sort();
+    return names.length === 0 ? [DEFAULT_PROFILE] : names;
+  }
+
+  setCurrent(name) {
+    this.file.current = name;
+    if (!this.file.profiles[name]) this.file.profiles[name] = {};
+  }
+
+  setCurrentBaseUrl(value) {
+    this.ensureProfile().base_url = value;
+  }
+
+  setCurrentProxy(mode) {
+    this.ensureProfile().proxy = mode;
+  }
+
+  setPhone(phone) {
+    const profile = this.ensureProfile();
+    if (phone === null || phone === undefined) delete profile.phone;
+    else profile.phone = phone;
+  }
+
+  ensureProfile() {
+    const name = this.currentName();
+    if (!this.file.profiles[name] || typeof this.file.profiles[name] !== 'object') {
+      this.file.profiles[name] = {};
+    }
+    return this.file.profiles[name];
+  }
+
+  /**
+   * 落盘形状：**与 Rust 版逐字节同形**。
+   *
+   * 两处刻意的处理：
+   *   * profile 按名字排序（Rust 侧是 `BTreeMap`）—— 同一份配置在两种实现下
+   *     序列化出的字节相同，`git diff` / 对拍才有意义；
+   *   * 值为 `null` 的字段**整个省掉**（Rust 的 `skip_serializing_if = "Option::is_none"`）。
+   */
+  toJson() {
+    const profiles = {};
+    for (const name of Object.keys(this.file.profiles).sort()) {
+      const raw = this.file.profiles[name] ?? {};
+      const profile = {};
+      if (typeof raw.base_url === 'string') profile.base_url = raw.base_url;
+      if (raw.proxy === ProxyMode.System || raw.proxy === ProxyMode.None) profile.proxy = raw.proxy;
+      if (typeof raw.phone === 'string') profile.phone = raw.phone;
+      profiles[name] = profile;
+    }
+    return { current: this.file.current ?? '', profiles };
+  }
+
+  save() {
+    this.paths.ensureDir();
+    writePrivate(this.paths.configFile, `${JSON.stringify(this.toJson(), null, 2)}\n`);
+  }
+
+  /**
+   * 生效的 base_url：命令行 `--base-url` > 指定 profile > 环境 `XINHE_OA_BASE_URL`
+   * > 当前 profile。
+   */
+  effectiveBaseUrl(cliOverride, profileOverride) {
+    if (cliOverride && cliOverride.trim().length > 0) return cliOverride.trim();
+    if (profileOverride) {
+      const url = this.profile(profileOverride).base_url;
+      if (url && url.trim().length > 0) return url;
+    }
+    const fromEnv = envNonEmpty('XINHE_OA_BASE_URL');
+    if (fromEnv) return fromEnv;
+    const current = this.currentProfile().base_url;
+    return current && current.trim().length > 0 ? current : null;
+  }
+
+  /** 生效的代理策略：环境 `XINHE_OA_PROXY` > 当前 profile > `system`。 */
+  effectiveProxy() {
+    const fromEnv = envNonEmpty('XINHE_OA_PROXY');
+    if (fromEnv) return parseProxyMode(fromEnv);
+    const configured = this.currentProfile().proxy;
+    return configured === undefined || configured === null
+      ? ProxyMode.System
+      : parseProxyMode(configured);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// credentials.json：设备指纹 + 令牌
+// ---------------------------------------------------------------------------
+/** 空令牌组（形状与服务端 `POST /auth/*` 的 `data.tokens` 对齐）。 */
+export function emptyTokens() {
+  return { access_token: '', refresh_token: '' };
+}
+
+/** 一个 profile 的凭据（默认全空）。 */
+export function emptyCredential() {
+  return { device_id: '', tokens: emptyTokens() };
+}
+
+/** 把服务端给的令牌组补成完整形状（缺的字段按 Rust 的 `Tokens` 默认值补）。 */
+export function normalizeTokens(raw) {
+  const tokens = raw && typeof raw === 'object' ? raw : {};
+  const out = {
+    access_token: typeof tokens.access_token === 'string' ? tokens.access_token : '',
+    refresh_token: typeof tokens.refresh_token === 'string' ? tokens.refresh_token : '',
+  };
+  if (typeof tokens.access_expires_at === 'string') out.access_expires_at = tokens.access_expires_at;
+  if (typeof tokens.refresh_expires_at === 'string') {
+    out.refresh_expires_at = tokens.refresh_expires_at;
+  }
+  return out;
+}
+
+/**
+ * 落盘形状：**与 Rust 版逐字节同形**（字段顺序固定、`null`/缺省字段省掉）。
+ *
+ * 这条不是洁癖：老用户先用 Rust 版登过录，再用 Node 版跑一次 —— 如果这里
+ * 把 `tokens` 之外的东西写坏（比如漏掉 `device_id`、或把 `user` 写成 null），
+ * 就是"换个实现就要重新短信登录一次"，而 `device_id` 一丢服务端立刻
+ * `auth.device_mismatch`。
+ */
+export function toCredentialJson(credential) {
+  const out = {};
+  if (typeof credential?.base_url === 'string') out.base_url = credential.base_url;
+  out.device_id = typeof credential?.device_id === 'string' ? credential.device_id : '';
+  out.tokens = normalizeTokens(credential?.tokens);
+  if (credential?.user !== undefined && credential?.user !== null) out.user = credential.user;
+  if (typeof credential?.phone === 'string') out.phone = credential.phone;
+  if (typeof credential?.updated_at === 'string') out.updated_at = credential.updated_at;
+  return out;
+}
+
+export function hasRefresh(credential) {
+  return Boolean(credential?.tokens?.refresh_token);
+}
+
+export function hasAccess(credential) {
+  return Boolean(credential?.tokens?.access_token);
+}
+
+/** credentials.json 的读写。**唯一的凭据落点**。 */
+export class CredentialStore {
+  constructor(paths, file) {
+    this.paths = paths;
+    this.file = file ?? { profiles: {} };
+    if (!this.file.profiles || typeof this.file.profiles !== 'object') this.file.profiles = {};
+  }
+
+  static load(paths) {
+    const raw = readJson(paths.credentialsFile);
+    return new CredentialStore(paths, raw ?? { profiles: {} });
+  }
+
+  get(name) {
+    const found = this.file.profiles[name];
+    return found && typeof found === 'object' ? found : null;
+  }
+
+  put(name, credential) {
+    this.file.profiles[name] = credential;
+    this.save();
+  }
+
+  remove(name) {
+    const existed = Object.prototype.hasOwnProperty.call(this.file.profiles, name);
+    if (existed) {
+      delete this.file.profiles[name];
+      this.save();
+    }
+    return existed;
+  }
+
+  /** 落盘形状：字段顺序固定，`null` / 缺省字段省掉（见 `toCredentialJson`）。 */
+  toJson() {
+    const profiles = {};
+    for (const name of Object.keys(this.file.profiles).sort()) {
+      profiles[name] = toCredentialJson(this.file.profiles[name]);
+    }
+    return { profiles };
+  }
+
+  save() {
+    this.paths.ensureDir();
+    writePrivate(this.paths.credentialsFile, `${JSON.stringify(this.toJson(), null, 2)}\n`);
+  }
+
+  /** 文件实际权限（`doctor` 与测试用它验证 0600）。Windows 上返回 null。 */
+  fileMode() {
+    if (process.platform === 'win32') return null;
+    try {
+      return fs.statSync(this.paths.credentialsFile).mode & 0o777;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/core/error.js

@@ -0,0 +1,217 @@
+// 错误与退出码（契约 §3.2，冻结）。
+//
+// | 码 | 含义                                                    |
+// |----|---------------------------------------------------------|
+// | 0  | 成功                                                    |
+// | 2  | 用法错误（CLI 本地判定，**不发请求**）                  |
+// | 3  | 未登录 / 凭据失效（含 refresh 过期）                    |
+// | 4  | 权限不足                                                |
+// | 5  | 冲突 / 幂等 / 乐观锁                                    |
+// | 6  | 服务端错误                                              |
+// | 7  | 网络不可达 / 超时                                       |
+// | 8  | 版本过旧（服务端要求升级）                              |
+//
+// 一条纪律：错误里**永不**出现令牌。服务端的 error.details 原样带回去给调用方，
+// 但 CLI 自己新造的任何 hint / message 都必须只提命令与参数。
+
+/** 成功。 */
+export const EXIT_OK = 0;
+/** 用法错误：参数拼错、缺必填、高风险命令没带 `--yes`。**本地判定，不发请求**。 */
+export const EXIT_USAGE = 2;
+/** 未登录 / 凭据失效。 */
+export const EXIT_AUTH = 3;
+/** 权限不足。 */
+export const EXIT_AUTHZ = 4;
+/** 冲突 / 幂等 / 乐观锁。 */
+export const EXIT_CONFLICT = 5;
+/** 服务端错误。 */
+export const EXIT_SERVER = 6;
+/** 网络不可达 / 超时。 */
+export const EXIT_NETWORK = 7;
+/** 版本过旧（服务端要求升级 CLI）。 */
+export const EXIT_TOO_OLD = 8;
+
+/** 错误分类（由 `error.code` + HTTP 状态共同决定）。 */
+export const Kind = Object.freeze({
+  Usage: 'Usage',
+  Auth: 'Auth',
+  Authz: 'Authz',
+  Conflict: 'Conflict',
+  Server: 'Server',
+  Network: 'Network',
+  TooOld: 'TooOld',
+});
+
+const KIND_EXIT = Object.freeze({
+  [Kind.Usage]: EXIT_USAGE,
+  [Kind.Auth]: EXIT_AUTH,
+  [Kind.Authz]: EXIT_AUTHZ,
+  [Kind.Conflict]: EXIT_CONFLICT,
+  [Kind.Server]: EXIT_SERVER,
+  [Kind.Network]: EXIT_NETWORK,
+  [Kind.TooOld]: EXIT_TOO_OLD,
+});
+
+const KIND_LABEL = Object.freeze({
+  [Kind.Usage]: 'usage',
+  [Kind.Auth]: 'auth',
+  [Kind.Authz]: 'authz',
+  [Kind.Conflict]: 'conflict',
+  [Kind.Server]: 'server',
+  [Kind.Network]: 'network',
+  [Kind.TooOld]: 'too_old',
+});
+
+/**
+ * 服务端错误码 → 退出码分类（契约 §3.2 的判据）。
+ *
+ * 判定顺序是刻意的：先看码（码比 HTTP 状态更精确），再兜 HTTP 状态。
+ * `httpStatus` 为 null / undefined 表示这不是一次 HTTP 往返（本地判定或网络故障）。
+ */
+export function classify(code, httpStatus) {
+  const text = typeof code === 'string' ? code : '';
+  const status = typeof httpStatus === 'number' ? httpStatus : null;
+  if (text.startsWith('cli.too_old')) return Kind.TooOld;
+  if (text.startsWith('authz.')) {
+    // 契约 §3.2 点名的是 `authz.missing_scope`；`authz.*` 家族
+    // （field_forbidden / tenant_endorsement_required / delegate_*）在语义上
+    // 全是"权限不足"，归到同一个退出码才是对调用方有用的行为。
+    return Kind.Authz;
+  }
+  if (text === 'skill.not_owner') {
+    // docs/34 §3 第二步：`--on-conflict update` 只有原创建者或企业负责人能选。
+    // 服务端用的是 `skill.*` 命名空间（不是 `authz.*`），但语义就是"你没有这个权力"。
+    return Kind.Authz;
+  }
+  if (text === 'file.not_owner' || text === 'file.visibility_exceeds_ceiling') {
+    // FILE-005：改可见性 / 移动 / 软删只有所有者（或企业负责人）能做；
+    // 超出容器上限同样要容器管理员 —— 两者服务端都是 403，语义都是"权限不足"。
+    return Kind.Authz;
+  }
+  if (text === 'skill.name_reserved') {
+    // 内置技能不可覆盖：归 5 而不是 2 —— 退出码 2 的判据写死了"CLI 本地判定、不发请求"，
+    // 而这个码只可能从服务端回来；它的出路（换个名字重来）与 `--on-conflict rename` 同类。
+    return Kind.Conflict;
+  }
+  if (text.startsWith('auth.')) return Kind.Auth;
+  // 契约写的是 `write.conflict*` 与 `idempotency.*`；服务端实际的码是
+  // `write.version_conflict` / `write.duplicate_row` / `write.duplicate_idempotency_key`。
+  // 按**语义**归并：冲突与幂等一类进 5。`write.missing_idempotency_key` /
+  // `write.invalid_idempotency_key` 是调用方的请求错误（400），不算"冲突"，留在 6。
+  const idempotencyFamily =
+    text.includes('idempotency') &&
+    !text.endsWith('missing_idempotency_key') &&
+    !text.endsWith('invalid_idempotency_key');
+  if (text.includes('conflict') || idempotencyFamily || status === 409) return Kind.Conflict;
+  if (status !== null && status >= 500) return Kind.Server;
+  return Kind.Server;
+}
+
+/** CLI 的统一错误类型。 */
+export class CliError extends Error {
+  /**
+   * @param {string} kind   Kind.*
+   * @param {string} code   服务端 `error.code`（CLI 不新造码；本地错误用 `cli.*` 前缀）
+   * @param {string} message 给人看的一句话
+   */
+  constructor(kind, code, message) {
+    super(message);
+    this.name = 'CliError';
+    this.kind = kind;
+    this.code = code;
+    this.details = {};
+    this.hint = null;
+    this.requestId = null;
+    /** 分类前的 HTTP 状态（排障用，不进 `--json`）。 */
+    this.httpStatus = null;
+    /**
+     * 给人看的细节（人类可读输出用它替代 `details` 的紧凑 JSON）。
+     * `details` 是**机器**形状（判卷与脚本读它），有时又长又密（比如冲突清单）；
+     * 直接压成一行 JSON 甩给人等于没说。这一栏只影响 `table` / `md` 渲染，
+     * **不进 `--json`** —— 两种读者的形状各自保持稳定。
+     */
+    this.human = null;
+  }
+
+  /** 用法错误（退出码 2）。`hint` 里给可直接照抄的下一步。 */
+  static usage(message) {
+    return new CliError(Kind.Usage, 'cli.usage', message);
+  }
+
+  /** 本地错误（网络故障等），没有服务端参与。 */
+  static local(message) {
+    return new CliError(Kind.Network, 'cli.network', message);
+  }
+
+  withHint(hint) {
+    this.hint = hint;
+    return this;
+  }
+
+  withDetails(details) {
+    this.details = details === undefined || details === null ? {} : details;
+    return this;
+  }
+
+  /** 给人看的细节（只影响 `table` / `md` 渲染；`--json` 的 `details` 不变）。 */
+  withHumanDetails(human) {
+    this.human = human;
+    return this;
+  }
+
+  withRequestId(requestId) {
+    this.requestId = requestId ?? null;
+    return this;
+  }
+
+  get exitCode() {
+    return KIND_EXIT[this.kind] ?? EXIT_SERVER;
+  }
+
+  /** 错误分类标签（人类可读输出里标一下"这是权限问题还是网络问题"）。 */
+  get kindLabel() {
+    return KIND_LABEL[this.kind] ?? 'server';
+  }
+
+  /** `--json` 的失败形状（契约 §3.1）。 */
+  toErrorJson() {
+    return {
+      code: this.code,
+      message: this.message,
+      details: this.details ?? {},
+      hint: this.hint ?? null,
+    };
+  }
+}
+
+/** 凭据问题的统一提示（契约 §4：`hint` 必须给出短信登录命令）。 */
+export function loginHint(phone) {
+  if (phone && phone.length > 0) {
+    return (
+      `凭据已失效，重新登录：xinhe-oa-cli login --phone ${phone}（再用收到的验证码跑 ` +
+      `xinhe-oa-cli login --phone ${phone} --code <验证码>）`
+    );
+  }
+  return (
+    '凭据已失效，重新登录：xinhe-oa-cli login --phone <你的手机号> ' +
+    '（再用收到的验证码跑 xinhe-oa-cli login --phone <你的手机号> --code <验证码>）'
+  );
+}
+
+/**
+ * 把一组"候选动作"收成一个：0 个或多于 1 个都是用法错误。
+ *
+ * @param {Array<[string, boolean]>} selected [动作名, 是否被选中]
+ * @param {string} what 动作所在的位置（如 `bitable base`）
+ * @param {string} hint
+ */
+export function exactlyOne(selected, what, hint) {
+  const picked = selected.filter(([, on]) => on).map(([name]) => name);
+  if (picked.length === 1) return picked[0];
+  if (picked.length === 0) {
+    throw CliError.usage(`\`${what}\` 必须给一个动作`).withHint(hint);
+  }
+  throw CliError.usage(
+    `\`${what}\` 一次只能给一个动作，收到 ${picked.length} 个：${picked.join(' / ')}`,
+  ).withHint(hint);
+}