@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/util.js

@@ -0,0 +1,195 @@
+// 小工具：随机串、时间、手机号/令牌掩码、文本。
+//
+// 与 Rust 版逐条对齐的两处：
+//   * `randomHex()` 用 `crypto.randomBytes`（Rust 那边读 `/dev/urandom`）；
+//   * `nowRfc3339()` 输出 `2026-10-16T03:21:15Z` 这种**秒级、带 Z** 的形状
+//     （Rust 是 `to_rfc3339_opts(Secs, true)`），因为服务端与凭据文件里比较的就是它。
+
+import { randomBytes } from 'node:crypto';
+
+/** 32 位十六进制随机串（device_id / 请求 id / 幂等键用；不用于密码学）。 */
+export function randomHex() {
+  return randomBytes(16).toString('hex');
+}
+
+/** 请求 id：`req_<16 hex>`。字符集符合服务端 `_clean_request_id` 的要求。 */
+export function newRequestId() {
+  return `req_${randomHex().slice(0, 16)}`;
+}
+
+/** 新的设备指纹：`dev-<32 hex>`（首次登录时生成并持久化，契约 §4）。 */
+export function newDeviceId() {
+  return `dev-${randomHex()}`;
+}
+
+/**
+ * 幂等键：稳定字符串（服务端只要求 `[A-Za-z0-9_.:-]` 且 ≤128 字符）。
+ *
+ * scope 里的非字母数字字符统一折成 `-`，只取前 24 个字符 ——
+ * 与 Rust 的 `new_idempotency_key` 同形，判卷按形状断言时两边一致。
+ */
+export function newIdempotencyKey(scope) {
+  const cleaned = Array.from(String(scope ?? ''))
+    .map((ch) => (/[A-Za-z0-9]/.test(ch) ? ch : '-'))
+    .join('')
+    .slice(0, 24);
+  return `${cleaned}:${randomHex().slice(0, 24)}`;
+}
+
+/** 现在（UTC，RFC3339，秒级 + Z）。 */
+export function nowRfc3339() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+/**
+ * 解析 RFC3339 时间戳（服务端 `iso()` 的输出）。
+ * 解析不了返回 null（调用方据此决定"当作已过期"还是"当作没过期"）。
+ */
+export function parseRfc3339(raw) {
+  if (typeof raw !== 'string') return null;
+  const text = raw.trim();
+  if (text.length === 0) return null;
+  const millis = Date.parse(text);
+  return Number.isNaN(millis) ? null : millis;
+}
+
+/** 手机号掩码（日志/展示用；**永不打印完整号码**）。 */
+export function maskPhone(phone) {
+  const digits = Array.from(String(phone ?? ''))
+    .filter((ch) => ch >= '0' && ch <= '9')
+    .join('');
+  if (digits.length < 7) return '****';
+  return `${digits.slice(0, 3)}****${digits.slice(-4)}`;
+}
+
+/** 令牌掩码：只给前 4 位与长度，够"确认是哪一枚"但不够"拿来用"。 */
+export function maskToken(token) {
+  if (!token) return '<empty>';
+  const chars = Array.from(token);
+  return `${chars.slice(0, 4).join('')}…（共 ${chars.length} 字符）`;
+}
+
+/**
+ * 显示宽度：CJK 字符占两列（表格对齐用）。
+ *
+ * 与 Rust `display_width` 同一张区间表 —— 两边渲染出来的表格必须逐字符一致，
+ * 否则 `--format table` 的对比测试会一直红。
+ */
+export function displayWidth(text) {
+  let width = 0;
+  for (const ch of String(text ?? '')) {
+    const code = ch.codePointAt(0);
+    const wide =
+      (code >= 0x1100 && code <= 0x115f) ||
+      (code >= 0x2e80 && code <= 0xa4cf) ||
+      (code >= 0xac00 && code <= 0xd7a3) ||
+      (code >= 0xf900 && code <= 0xfaff) ||
+      (code >= 0xfe30 && code <= 0xfe6f) ||
+      (code >= 0xff00 && code <= 0xff60) ||
+      (code >= 0xffe0 && code <= 0xffe6);
+    width += wide ? 2 : 1;
+  }
+  return width;
+}
+
+/** 按**显示宽度**截断（不是字符数），否则中文列会错位。 */
+export function truncateWidth(text, maxWidth) {
+  const source = String(text ?? '');
+  if (displayWidth(source) <= maxWidth) return source;
+  let out = '';
+  let width = 0;
+  for (const ch of source) {
+    const charWidth = displayWidth(ch);
+    if (width + charWidth > Math.max(0, maxWidth - 1)) break;
+    out += ch;
+    width += charWidth;
+  }
+  return `${out}…`;
+}
+
+/** 按显示宽度右侧补空格。 */
+export function padWidth(text, width) {
+  const source = String(text ?? '');
+  const current = displayWidth(source);
+  return current >= width ? source : source + ' '.repeat(width - current);
+}
+
+/** 紧凑 JSON（对象键顺序保持插入序，与 Rust 的 serde_json Map 一致）。 */
+export function compactJson(value) {
+  return JSON.stringify(value);
+}
+
+/**
+ * 按 UTF-8 字节序递归排序对象键 —— **对齐 Rust 的 `serde_json`**。
+ *
+ * Rust 那份 CLI 没开 `preserve_order`，`serde_json::Map` 因此是 `BTreeMap`：
+ * 所有 JSON 对象（含 `meta`、`data` 里命令自己拼的那些）的键都是**字典序**。
+ * 这里不排序的话，Node 版与 Rust 版的差别只体现在"键的先后"上 ——
+ * 判卷做字节/文本比对时那是噪声，看 `diff` 的人也会被误导。
+ *
+ * 只影响输出；命令内部的对象顺序（表格列序等）不受影响。
+ */
+export function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value === null || typeof value !== 'object') return value;
+  const out = {};
+  for (const key of Object.keys(value).sort()) out[key] = sortKeysDeep(value[key]);
+  return out;
+}
+
+/**
+ * 把 Node 的 errno 渲染成 **Rust `std::io::Error` 的措辞**
+ * （`No such file or directory (os error 2)`）。
+ *
+ * 为什么值得这么做：`读不了文件 X：…` 这句话会进 `--json` 的 `error.message`，
+ * 而它是**对拍与判卷会逐字比**的字段。Node 原生给的是
+ * `ENOENT: no such file or directory, open './x.pdf'`（libuv 措辞），Rust 给的是
+ * `No such file or directory (os error 2)` —— 同一个事实、两种说法。
+ * 用户拿到的可执行信息（路径 + 原因）两者都有，所以这里只是把措辞对齐契约基线。
+ *
+ * 认不出来的错误码**退回 Node 原文**（不猜：宁可保留 libuv 措辞，
+ * 也不编一个可能不对的 os error 号）。
+ */
+const ERRNO_TEXT = {
+  EPERM: [1, 'Operation not permitted'],
+  ENOENT: [2, 'No such file or directory'],
+  ESRCH: [3, 'No such process'],
+  EINTR: [4, 'Interrupted system call'],
+  EIO: [5, 'Input/output error'],
+  ENXIO: [6, 'No such device or address'],
+  E2BIG: [7, 'Argument list too long'],
+  ENOEXEC: [8, 'Exec format error'],
+  EBADF: [9, 'Bad file descriptor'],
+  EAGAIN: [11, 'Resource temporarily unavailable'],
+  ENOMEM: [12, 'Cannot allocate memory'],
+  EACCES: [13, 'Permission denied'],
+  EFAULT: [14, 'Bad address'],
+  EBUSY: [16, 'Device or resource busy'],
+  EEXIST: [17, 'File exists'],
+  EXDEV: [18, 'Invalid cross-device link'],
+  ENODEV: [19, 'No such device'],
+  ENOTDIR: [20, 'Not a directory'],
+  EISDIR: [21, 'Is a directory'],
+  EINVAL: [22, 'Invalid argument'],
+  ENFILE: [23, 'Too many open files in system'],
+  EMFILE: [24, 'Too many open files'],
+  ENOTTY: [25, 'Inappropriate ioctl for device'],
+  EFBIG: [27, 'File too large'],
+  ENOSPC: [28, 'No space left on device'],
+  ESPIPE: [29, 'Illegal seek'],
+  EROFS: [30, 'Read-only file system'],
+  EMLINK: [31, 'Too many links'],
+  EPIPE: [32, 'Broken pipe'],
+  ENAMETOOLONG: [36, 'File name too long'],
+  ENOSYS: [38, 'Function not implemented'],
+  ENOTEMPTY: [39, 'Directory not empty'],
+  ELOOP: [40, 'Too many levels of symbolic links'],
+  EOVERFLOW: [75, 'Value too large for defined data type'],
+};
+
+/** `ENOENT: no such file or directory, open './x.pdf'` → `No such file or directory (os error 2)`。 */
+export function rustIoErrorText(err) {
+  const known = ERRNO_TEXT[err?.code];
+  if (known === undefined) return err?.message ?? String(err);
+  return `${known[1]} (os error ${known[0]})`;
+}

package/src/core/values.js

@@ -0,0 +1,278 @@
+// `--type` / `--set` / `--filter` 这类**取值语法**的解析（对齐 Rust 的 args.rs）。
+//
+// 这一层与"哪些旗标存在"（`src/spec/command_surface.json`）分开：
+// 规格管"能不能这么写"，这里管"写出来的值是什么意思"。
+
+import { CliError } from './error.js';
+
+/** FILE-005 §6.2：本期能写的**三档**（`public` 刻意不在表里，本地就拦下）。 */
+export const FILE_VISIBILITY_TIERS = ['private', 'dept', 'internal'];
+/** 文件 ACL 只认两个动作（`download = read`）。 */
+export const FILE_ACL_ACTIONS = ['read', 'write'];
+export const FILE_SEARCH_MAX_LIMIT = 200;
+export const FILE_SEARCH_MAX_WORKERS = 16;
+export const FILE_SEARCH_MIN_QUERY = 2;
+
+export const REPORT_STATUSES = [
+  'pending',
+  'filled',
+  'submitted',
+  'confirmed',
+  'rejected',
+  'waived',
+];
+export const REPORT_CADENCES = ['daily', 'weekly', 'monthly', 'quarterly'];
+
+/** 值的字面量解析：数字/布尔/JSON/字符串。命令行里写 `true` 就该是布尔。 */
+export function parseScalar(raw) {
+  const trimmed = String(raw ?? '').trim();
+  if (trimmed.length === 0) return null;
+  if (trimmed === 'null') return null;
+
+  // 只有"规范写法"才当数字：带前导零的 `007` 是单据号，不是 7。
+  const canonicalInteger =
+    !trimmed.startsWith('0') ||
+    trimmed === '0' ||
+    trimmed.startsWith('0.') ||
+    trimmed.startsWith('-0.') ||
+    (trimmed.startsWith('-0') && trimmed.length > 2 && /^\d+$/.test(trimmed.slice(2)));
+  if (canonicalInteger) {
+    if (/^-?\d+$/.test(trimmed)) {
+      const asInt = Number.parseInt(trimmed, 10);
+      // 超出安全整数范围时退回字符串：JSON 里那个数已经不是它本来的值了。
+      if (Number.isSafeInteger(asInt)) return asInt;
+    } else if (/^-?\d*\.\d+([eE][+-]?\d+)?$/.test(trimmed)) {
+      const asFloat = Number.parseFloat(trimmed);
+      if (Number.isFinite(asFloat)) return asFloat;
+    }
+  }
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (
+    (trimmed.startsWith('[') && trimmed.endsWith(']')) ||
+    (trimmed.startsWith('{') && trimmed.endsWith('}'))
+  ) {
+    try {
+      return JSON.parse(trimmed);
+    } catch {
+      /* 不是合法 JSON 就当字符串 */
+    }
+  }
+  return trimmed;
+}
+
+/** `--key 键=值`：拆成 `[键, 值]`（值为字符串）。 */
+export function parsePairs(items, flag) {
+  const out = [];
+  for (const item of items) {
+    const index = String(item).indexOf('=');
+    if (index < 0) {
+      throw CliError.usage(`${flag} 的写法是 \`键=值\`，收到 ${JSON.stringify(item)}`).withHint(
+        `例：${flag} 金额=1200`,
+      );
+    }
+    const key = String(item).slice(0, index).trim();
+    if (key.length === 0) {
+      throw CliError.usage(`${flag} 的键不能为空（收到 ${JSON.stringify(item)}）`);
+    }
+    out.push([key, String(item).slice(index + 1)]);
+  }
+  return out;
+}
+
+/**
+ * `--set` 的一个键值对。
+ *
+ * `forceString` = 用户写了 `键:=值`，值**原样当字符串**，不做数字/布尔/JSON 推断。
+ *
+ * 为什么需要它：`--set 流水号=21474238` 会被 `parseScalar` 当整数发出去，
+ * 而 text 字段收到 int 会被服务端拒；加引号又会把引号一起存进去。于是
+ * "把纯数字文本写进 text 字段"这件事在现场没有任何写法能做到 ——
+ * 而流水号、手机号、门诊号、票据号全是这种值。用 `:=`（curl/jq 那一系的约定）解决。
+ */
+export function parseSetPairs(items, flag) {
+  const out = [];
+  for (const item of items) {
+    const text = String(item);
+    const eq = text.indexOf('=');
+    if (eq < 0) {
+      throw CliError.usage(
+        `${flag} 的写法是 \`键=值\`（或 \`键:=值\` 强制字符串），收到 ${JSON.stringify(item)}`,
+      ).withHint(`例：${flag} 金额=1200 ／ ${flag} 流水号:=21474238`);
+    }
+    // 判据只看**第一个** `=`：若它前一个字符是 `:`，就是强制字符串。
+    // 这样 `备注=a:=b` 不会被误判（第一个 `=` 前面是 `a`）。
+    const rawKey = text.slice(0, eq);
+    const forceString = rawKey.endsWith(':');
+    const key = (forceString ? rawKey.slice(0, -1) : rawKey).trim();
+    if (key.length === 0) {
+      throw CliError.usage(`${flag} 的键不能为空（收到 ${JSON.stringify(item)}）`);
+    }
+    out.push({ key, value: text.slice(eq + 1), forceString });
+  }
+  return out;
+}
+
+/** 把 `--set` 的键值转成 `values` 对象（`键:=值` 强制字符串）。 */
+export function valuesObject(pairs) {
+  const out = {};
+  for (const pair of pairs) {
+    out[pair.key] = pair.forceString ? pair.value : parseScalar(pair.value);
+  }
+  return out;
+}
+
+/**
+ * `--filter 字段:算子:值` → 视图过滤 AST（组内 AND，最多两层 —— 与服务端一致）。
+ *
+ * 字段用 **semantic_key**（`bitable field --list` 里的机器名）：写显示名不报错，
+ * 但客户端筛不到任何行，"静默 0 条"是这里最贵的坑。
+ */
+export function filtersToAst(items) {
+  if (items.length === 0) return null;
+  const children = [];
+  for (const item of items) {
+    const parts = String(item).split(':');
+    const field = (parts[0] ?? '').trim();
+    const operator = (parts[1] ?? '').trim();
+    const raw = parts.slice(2).join(':');
+    if (field.length === 0 || operator.length === 0) {
+      throw CliError.usage(`--filter 的写法是 \`字段:算子:值\`，收到 ${JSON.stringify(item)}`).withHint(
+        '写法是 `字段:算子:值`（字段用 semantic_key，例：--filter visit_date:gte:2026-01-01）',
+      );
+    }
+    children.push({ field, operator, value: parseScalar(raw) });
+  }
+  return { op: 'and', children };
+}
+
+/** `字段:asc` → 服务端的 `order` 参数（缺方向补 asc）。 */
+export function orderParam(raw) {
+  return String(raw)
+    .split(',')
+    .map((pieceRaw) => {
+      const piece = pieceRaw.trim();
+      const index = piece.lastIndexOf(':');
+      if (index > 0) {
+        const field = piece.slice(0, index).trim();
+        const direction = piece.slice(index + 1).trim().toLowerCase();
+        if (direction === 'asc' || direction === 'desc') return `${field}:${direction}`;
+      }
+      return `${piece}:asc`;
+    })
+    .join(',');
+}
+
+/**
+ * 校验 `--on-conflict` 与 `--new-key` / `--new-name` 的组合。
+ *
+ * | 输入 | 结果 |
+ * |---|---|
+ * | 缺失 + 没给 new-* | `null`：交给服务端判"有没有冲突" |
+ * | 缺失 + 给了 new-* | 退出码 2：`--new-key` 只在 `rename` 时才有意义 |
+ * | `rename` + 有 new-key | `{kind:'rename', newKey, newName}` |
+ * | `rename` + 缺 new-key | 退出码 2：改名却不给新 key，等于没表态 |
+ * | `update` + 给了 new-* | 退出码 2：update 是**覆盖**，不是改名 |
+ * | 其它值 | 退出码 2 |
+ */
+export function onConflictPlan(onConflict, newKey, newName) {
+  const trimmed = (value) => {
+    const text = value === null || value === undefined ? '' : String(value).trim();
+    return text.length > 0 ? text : null;
+  };
+  const key = trimmed(newKey);
+  const name = trimmed(newName);
+  const mode = trimmed(onConflict);
+  if (mode === null) {
+    if (key !== null || name !== null) {
+      throw CliError.usage(
+        '--new-key / --new-name 只在 `--on-conflict rename` 时才有意义',
+      ).withHint(
+        '要么 `--on-conflict rename --new-key <新KEY>`，要么先 `skills --conflicts` 看清冲突再决定',
+      );
+    }
+    return null;
+  }
+  if (mode === 'rename') {
+    if (key === null) {
+      throw CliError.usage('`--on-conflict rename` 必须给 --new-key <新KEY>').withHint(
+        '例：--on-conflict rename --new-key finance_monthly_v2 [--new-name 财务月结V2]',
+      );
+    }
+    return { kind: 'rename', newKey: key, newName: name };
+  }
+  if (mode === 'update') {
+    if (key !== null || name !== null) {
+      throw CliError.usage(
+        '`--on-conflict update` 的语义是**覆盖已有的那个技能**（发布新版本），不接受 --new-key / --new-name',
+      ).withHint('想改名就换 `--on-conflict rename --new-key <新KEY>`');
+    }
+    return { kind: 'update' };
+  }
+  throw CliError.usage(
+    `--on-conflict 只能是 rename（改名后分享）或 update（覆盖已有的那个），收到 ${JSON.stringify(mode)}`,
+  ).withHint('两条出路：--on-conflict rename --new-key <新KEY> | --on-conflict update');
+}
+
+/** 技能可见性：`private`（默认）| `shared` | `tenant`。 */
+export function parseVisibility(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (value === 'private' || value === 'shared' || value === 'tenant') return value;
+  throw CliError.usage(
+    `--visibility 只能是 private（默认，只有自己）/ shared（点对点分享过的）/ tenant（企业内共享，要审批），收到 ${JSON.stringify(value)}`,
+  ).withHint('例：--visibility tenant');
+}
+
+/** 新建技能时的可见性：**不传就是 private**（fail-closed）。 */
+export function createVisibility(raw) {
+  if (raw === null || raw === undefined) return 'private';
+  return parseVisibility(raw);
+}
+
+/** 文件可见性档位：只认 private / dept / internal（`public` 本地拒，不发请求）。 */
+export function parseFileVisibilityTier(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (FILE_VISIBILITY_TIERS.includes(value)) return value;
+  if (value === 'public') {
+    throw CliError.usage('`public` 这一档本期不可写（服务端会拒）').withHint(
+      `能写的是：${FILE_VISIBILITY_TIERS.join(' / ')}`,
+    );
+  }
+  throw CliError.usage(
+    `--set 只能是 ${FILE_VISIBILITY_TIERS.join(' / ')}，收到 ${JSON.stringify(value)}`,
+  );
+}
+
+/** 审批状态过滤：空串 = 不筛；只认已知状态。 */
+export function approvalStatusFilter(raw) {
+  const value = String(raw ?? '').trim().toLowerCase();
+  if (value.length === 0) return null;
+  const known = ['pending', 'approved', 'rejected', 'cancelled', 'reverted'];
+  if (!known.includes(value)) {
+    throw CliError.usage(`--status 只能是 ${known.join(' / ')}，收到 ${JSON.stringify(value)}`);
+  }
+  return value;
+}
+
+/** 从 URL 或本地路径里取文件名。 */
+export function fileNameOf(path) {
+  const parts = String(path ?? '').split(/[/\\]/);
+  return parts[parts.length - 1] ?? String(path ?? '');
+}
+
+/** `{key: value}` → 单个对象的查询参数数组（空值不进 query）。 */
+export function queryPairs(entries) {
+  const out = [];
+  for (const [key, value] of entries) {
+    if (value === null || value === undefined) continue;
+    const text = String(value);
+    if (text.trim().length === 0) continue;
+    out.push([key, text]);
+  }
+  return out;
+}
+
+/** 布尔渲染：`true` / `false`（服务端与文档都用字面量）。 */
+export function asBool(value) {
+  return value === true;
+}