@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/config.js

@@ -0,0 +1,186 @@
+// 配置：`config --list|--show|--set|--use`（契约 §2、§4）。
+//
+// 一条硬规矩：**永不打印令牌**。`--show` 里的凭据一律掩码
+// （`abcd…（共 42 字符）`），只够确认"是哪一枚"，不够拿来用。
+
+import { CliError } from '../core/error.js';
+import { DEFAULT_PROFILE, ProxyMode, parseProxyMode } from '../core/config.js';
+import { Auth, USER_AGENT, hostOf, normalizeBaseUrl, requestSpec } from '../core/http.js';
+import { maskPhone, maskToken } from '../core/util.js';
+
+/** `config --list` / `--show` / `--set` / `--use` 的分发。 */
+export async function handleConfig({ args, runtime }) {
+  if (args['--list'] === true) return list(runtime);
+  if (args['--show'] === true) return show(runtime);
+  if (args['--set'] !== undefined) return set(runtime, String(args['--set']));
+  if (args['--use'] !== undefined) return useProfile(runtime, String(args['--use']));
+  throw CliError.usage('`config` 必须给一个动作').withHint(
+    '四选一：--list | --show | --set 键=值 | --use <名字>',
+  );
+}
+
+function list(runtime) {
+  const current = runtime.config.currentName();
+  const profiles = runtime.config.names().map((name) => {
+    const profile = runtime.config.profile(name);
+    const credential = runtime.credentials.get(name);
+    const entry = {
+      name,
+      current: name === current,
+      base_url: profile.base_url ?? null,
+      proxy: profile.proxy ?? ProxyMode.System,
+      phone_masked: profile.phone ? maskPhone(profile.phone) : null,
+      has_credentials: credential
+        ? Boolean(credential.tokens?.access_token || credential.tokens?.refresh_token)
+        : false,
+      device_id: credential?.device_id ?? null,
+      tokens_valid_until: credential?.tokens?.refresh_expires_at ?? null,
+    };
+    return entry;
+  });
+  runtime.finish({
+    current,
+    config_file: runtime.paths.configFile,
+    credentials_file: runtime.paths.credentialsFile,
+    profiles,
+    note: '令牌**永不打印**：这里只有掩码与有效期。',
+  });
+}
+
+function show(runtime) {
+  const profile = runtime.config.profile(runtime.profile);
+  const credential = runtime.credentials.get(runtime.profile);
+  const data = {
+    profile: runtime.profile,
+    base_url: profile.base_url ?? '<未配置>',
+    effective_base_url: runtime.baseUrl ?? null,
+    proxy: profile.proxy ?? ProxyMode.System,
+    proxy_effective: runtime.proxyDescription(),
+    phone_masked: profile.phone ? maskPhone(profile.phone) : null,
+    device: credential
+      ? {
+          device_id: credential.device_id,
+          user_agent: USER_AGENT,
+          note: '服务端把 refresh 绑在 HMAC(User-Agent + X-Device-Id) 上；换设备会被 auth.device_mismatch 拒',
+        }
+      : null,
+    credentials: credential
+      ? {
+          access_token: maskToken(credential.tokens?.access_token ?? ''),
+          refresh_token: maskToken(credential.tokens?.refresh_token ?? ''),
+          access_expires_at: credential.tokens?.access_expires_at ?? null,
+          refresh_expires_at: credential.tokens?.refresh_expires_at ?? null,
+          user: credential.user ?? null,
+          updated_at: credential.updated_at ?? null,
+          file_mode: process.platform === 'win32' ? null : '0600',
+        }
+      : null,
+    paths: {
+      config: runtime.paths.configFile,
+      credentials: runtime.paths.credentialsFile,
+      config_dir: runtime.paths.dir,
+    },
+  };
+  runtime.finish(data);
+}
+
+function set(runtime, pair) {
+  const index = pair.indexOf('=');
+  if (index < 0) {
+    throw CliError.usage('--set 的写法是 `键=值`').withHint(
+      '支持：base_url=<地址> | proxy=system|none | profile=<名字>；例：xinhe-oa-cli config --set base_url=http://127.0.0.1:8102',
+    );
+  }
+  const key = pair.slice(0, index).trim().toLowerCase();
+  const value = pair.slice(index + 1).trim();
+  const updated = {};
+  let nextStep;
+  if (key === 'base_url' || key === 'base-url' || key === 'url') {
+    if (value.length === 0) {
+      throw CliError.usage('base_url 不能为空').withHint('例：--set base_url=http://127.0.0.1:8102');
+    }
+    const normalized = normalizeBaseUrl(value);
+    // 纯 IP + 端口也合法（容器里的 LLM 常走 http://172.17.0.1:8100）。
+    if (hostOf(normalized) === null) {
+      throw CliError.usage(`看不出来这是个地址：${JSON.stringify(value)}`).withHint(
+        '例：--set base_url=http://127.0.0.1:8102',
+      );
+    }
+    runtime.config.setCurrentBaseUrl(normalized);
+    runtime.baseUrl = normalized;
+    updated.base_url = normalized;
+    nextStep = '接着登录：xinhe-oa-cli login --phone <手机号>';
+  } else if (key === 'proxy') {
+    const mode = parseProxyMode(value);
+    runtime.config.setCurrentProxy(mode);
+    runtime.proxy = mode;
+    updated.proxy = mode;
+    nextStep = '验证连通性：xinhe-oa-cli doctor';
+  } else if (key === 'profile') {
+    if (value.length === 0) throw CliError.usage('profile 名字不能为空');
+    runtime.config.setCurrent(value);
+    runtime.profile = value;
+    updated.profile = value;
+    nextStep = '查看配置：xinhe-oa-cli config --list';
+  } else {
+    throw CliError.usage(`不认识的配置项 ${JSON.stringify(key)}`).withHint(
+      '支持：base_url=<地址> | proxy=system|none | profile=<名字>',
+    );
+  }
+  runtime.config.save();
+  runtime.finish({
+    updated,
+    profile: runtime.profile,
+    config_file: runtime.paths.configFile,
+    proxy_effective: runtime.proxyDescription(),
+    next_step: nextStep,
+  });
+}
+
+function useProfile(runtime, name) {
+  if (name.trim().length === 0) {
+    throw CliError.usage('--use 需要 profile 名字').withHint(
+      `例：xinhe-oa-cli config --use ${DEFAULT_PROFILE}`,
+    );
+  }
+  runtime.config.setCurrent(name);
+  runtime.config.save();
+  const profile = runtime.config.profile(name);
+  const credential = runtime.credentials.get(name);
+  runtime.finish({
+    current: name,
+    base_url: profile.base_url ?? null,
+    phone_masked: profile.phone ? maskPhone(profile.phone) : null,
+    has_credentials: credential
+      ? Boolean(credential.tokens?.access_token || credential.tokens?.refresh_token)
+      : false,
+    next_step:
+      credential !== null
+        ? '确认还能用：xinhe-oa-cli me --json'
+        : '这个 profile 还没有凭据：xinhe-oa-cli login --phone <手机号>',
+  });
+}
+
+/** 探一次 `/health`（`doctor` 用）。 */
+export async function probeHealth(runtime) {
+  const http = runtime.anonymousHttp();
+  const response = await http.send('GET', '/health', Auth.none(), requestSpec(), 'doctor');
+  return response.body;
+}
+
+/**
+ * 问一次 `/cli/latest`（#71 的版本协商面）。
+ *
+ * 三点刻意如此：
+ * - **匿名**（`capability="public"`）：首次安装、以及"手上这枚令牌已经失效"的旧客户端
+ *   都要能问出该装哪个版本 —— 把它关在登录之后就等于让登不上来的人连自救都做不了；
+ * - **带上 `X-CLI-Version`**：不发这个头服务端不做门禁（它只拦"确实太旧"），
+ *   而我们要的就是被明确告知"你太旧了，去升级"（`cli.too_old` → 退出码 8）；
+ * - **响应体不套 `data` 信封**，所以这里回整个响应体，由调用方按字段名取。
+ */
+export async function fetchLatestRelease(runtime) {
+  const http = runtime.anonymousHttp();
+  const response = await http.send('GET', '/cli/latest', Auth.none(), requestSpec(), 'doctor');
+  return response.body;
+}
+

package/src/commands/dashboard.js

@@ -0,0 +1,132 @@
+// 看板：`dashboard --list|--show|--data|--create`（契约 §2）。
+//
+// 看板是"库（base）之上的只读视图集合"：block（指标/表格/图表/文本）各自绑一个
+// 数据源，`--data` 就是把它们**按你的权限现算一遍**（docs/26 §1.2）。
+//
+// 两条与直觉相反、但必须保持的口径：
+//
+// 1. `--data` 是 POST，却**不是写**：它没有 `--yes`、也不要幂等键 —— `--show` 给的是
+//    看板的**定义**（有哪些 block、怎么配的），`--data` 给的是**这一刻的数**。
+//    之所以用 POST，是因为 block 的取数参数（聚合/筛选）可以放在请求体里。
+// 2. `--create` 是 `write` 而不是 `high-risk-write`：它只往一个已有的库里加一块看板，
+//    删掉就回到原样，改不了任何既有对象。所以只要幂等键，不要 `--yes`。
+//
+// 与 Rust 版逐条对齐的细节：
+//   * `--list` 的 `--base` 空值**不进 query**（`query_pair` 会滤掉 trim 后为空的）；
+//   * `--create` 的 `key` 缺省由显示名推导（`deriveKey`），中文/数字开头推不出来时
+//     退化成 `d<8 位随机 hex>` —— 而不是静默造一个客户第二天认不出的机器名；
+//   * `--data` 的响应里 `blocks` 与 `clipped_blocks` 各自独立取键：被裁掉的 block 是
+//     "你看不见它"，不是"它不存在"，这两个字段不能互相兜底。
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagOn, flagValue } from '../core/args.js';
+import { dataOf, idempotencyKey, requestSpec } from '../core/runtime.js';
+import { randomHex } from '../core/util.js';
+import { queryPairs } from '../core/values.js';
+
+/** `dashboard --list|--show|--data|--create` 的分发。 */
+export async function handleDashboard({ args, runtime }) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--show', flagValue(args, '--show') !== null],
+      ['--data', flagValue(args, '--data') !== null],
+      ['--create', flagOn(args, '--create')],
+    ],
+    'dashboard',
+    '例：xinhe-oa-cli dashboard --list --json',
+  );
+  if (action === '--list') return list(runtime, args);
+  if (action === '--show') return show(runtime, flagValue(args, '--show'));
+  if (action === '--data') return data(runtime, flagValue(args, '--data'));
+  return create(runtime, args);
+}
+
+async function list(runtime, args) {
+  // `--base` 只做过滤：空串/纯空白等于没给（`queryPairs` 与 Rust 的 `query_pair` 同义），
+  // 但**非空值原样发**（不 trim）—— 服务端按原值匹配。
+  const query = queryPairs([['base_id', flagValue(args, '--base')]]);
+  const response = await runtime.sendAuthed('GET', '/dashboards', requestSpec({ query }));
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    dashboards: hasKey(data, 'dashboards') ? data.dashboards : [],
+    total: hasKey(data, 'total') ? data.total : null,
+    next_step: '取数：xinhe-oa-cli dashboard --data <DASHBOARD_ID> --json',
+  });
+}
+
+async function show(runtime, dashboardId) {
+  const response = await runtime.sendAuthed('GET', `/dashboards/${dashboardId}`, requestSpec());
+  // 定义（blocks / filters / layout）原样透传。
+  runtime.finishFrom(response, dataOf(response));
+}
+
+async function data(runtime, dashboardId) {
+  const path = `/dashboards/${dashboardId}/data`;
+  // 空对象是**有意义的请求体**（不是"没有体"）：服务端把 `{}` 读成"按看板自己的
+  // 配置取数"，而缺体在 FastAPI 里会走另一条分支。
+  const spec = requestSpec({ body: {} });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const body = dataOf(response);
+  runtime.finishFrom(response, {
+    // 没有 `blocks` 键时用整个 data 兜底（老版本直出数组）；有键就**如实**取它，
+    // 哪怕是 `null` —— 那表示"一个 block 都没算出来"。
+    blocks: hasKey(body, 'blocks') ? body.blocks : body,
+    clipped_blocks: hasKey(body, 'clipped_blocks') ? body.clipped_blocks : null,
+    note: '取数不是「看板授权」：每个 block 都按**你的**权限现算，看不见的被裁剪并说明原因',
+  });
+}
+
+async function create(runtime, args) {
+  const baseId = flagValue(args, '--base');
+  if (baseId === null) {
+    throw CliError.usage('`dashboard --create` 需要 --base <BASE_ID>').withHint(
+      '看板属于某个库：xinhe-oa-cli bitable base --list --json',
+    );
+  }
+  const name = flagValue(args, '--name');
+  if (name === null) {
+    throw CliError.usage('`dashboard --create` 需要 --name <看板名>');
+  }
+  // 机器名创建后不可变，所以：显式 `--key` 优先；否则从显示名推导；推导不出来
+  // （中文/数字开头、空名）退化成随机名 —— 与 Rust 的 `d{random_hex[..8]}` 同形。
+  const key = flagValue(args, '--key') ?? deriveKey(name) ?? `d${randomHex().slice(0, 8)}`;
+  const body = { base_id: baseId, key, name };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('dashboard --create', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/dashboards', spec);
+
+  const response = await runtime.sendAuthed('POST', '/dashboards', spec);
+  runtime.finishFrom(response, { dashboard: dataOf(response) });
+}
+
+/**
+ * 由显示名推导机器名 —— 与 Rust `bitable::derive_key` 逐条同义。
+ *
+ * 规则：只保留 ASCII 字母/数字（转小写），其余 ASCII 字符折成 `_`，
+ * 连续 `_` 合并、首尾去掉，截到 48 字符；**必须以小写字母开头**，否则算推导失败
+ * （返回 null）。中文名一个字符都不保留 —— 推不出来时由调用方决定怎么办，
+ * 这个函数绝不"尽力而为"地编一个名字出来。
+ */
+function deriveKey(name) {
+  let key = '';
+  for (const ch of String(name ?? '')) {
+    if (/^[A-Za-z0-9]$/.test(ch)) key += ch.toLowerCase();
+    else if (ch.codePointAt(0) < 128) key += '_';
+  }
+  key = key.replace(/_{2,}/g, '_').replace(/^_+|_+$/g, '');
+  if (key.length > 48) key = key.slice(0, 48);
+  if (key.length === 0 || !/^[a-z]/.test(key)) return null;
+  return key;
+}
+
+/** 键存在就取（`null` 也算存在）—— 对齐 Rust `Value::get`。 */
+function hasKey(value, key) {
+  return (
+    value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, key)
+  );
+}