@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/output.js

@@ -0,0 +1,300 @@
+// 输出渲染（契约 §3.1 / §3.3）。
+//
+// 两条硬规矩：
+//
+// 1. **stdout 只放结果**；日志与进度一律 stderr（`warn` / `verbose` / `progress`）。
+//    否则管道与判卷会被污染。
+// 2. `--json` 的形状**稳定**：成功 `{ok,data,meta}`，失败 `{ok:false,error,meta}`，
+//    失败也要有 `meta.request_id`（与服务端审计对齐）。
+//
+// 人类可读输出默认 `table`，`--format md|table|json` 可切换。
+
+import { CliError } from './error.js';
+import { compactJson, displayWidth, padWidth, sortKeysDeep, truncateWidth } from './util.js';
+import { VERSION } from '../version.js';
+
+/** 输出格式。 */
+export const Format = Object.freeze({
+  Table: 'table',
+  Markdown: 'md',
+  Json: 'json',
+});
+
+export function parseFormat(raw) {
+  const text = String(raw ?? '').trim().toLowerCase();
+  if (text === 'json') return Format.Json;
+  if (text === 'md' || text === 'markdown') return Format.Markdown;
+  if (text === 'table' || text === 'text') return Format.Table;
+  throw CliError.usage(`--format 只能是 table / md / json，收到 ${JSON.stringify(text)}`);
+}
+
+/** 一次调用的元信息（`meta` 段）。**六个键永远都在**（判卷按形状断言）。 */
+export class Meta {
+  constructor(init = {}) {
+    this.command = init.command ?? '';
+    this.cliVersion = init.cliVersion ?? '';
+    this.serverVersion = init.serverVersion ?? null;
+    this.requestId = init.requestId ?? null;
+    this.durationMs = init.durationMs ?? 0;
+    this.profile = init.profile ?? 'default';
+  }
+
+  toJson() {
+    return {
+      command: this.command,
+      cli_version: this.cliVersion.length > 0 ? this.cliVersion : VERSION,
+      server_version: this.serverVersion,
+      request_id: this.requestId,
+      duration_ms: this.durationMs,
+      profile: this.profile,
+    };
+  }
+}
+
+function writeLine(text) {
+  process.stdout.write(`${text}\n`);
+}
+
+/** 成功输出。`data` 是命令专属内容，`meta` 是这次调用的元信息。 */
+export function renderSuccess(data, meta, format) {
+  return renderSuccessWith(data, null, meta, format);
+}
+
+/**
+ * 成功输出 + **调用方给的人类可读视图**。
+ *
+ * 有些命令的 `data` 是给机器读的（`me` 的身份/范围/能力、`--import --dry-run` 的完整计划），
+ * 通用表格渲染说不出重点。这些命令用 `human` 给一份给人看的文本；
+ * **`--json` 一个字都不变**（机器面稳定）。
+ */
+export function renderSuccessWith(data, human, meta, format) {
+  if (format === Format.Json) {
+    // `sortKeysDeep`：Rust 的 serde_json 是 BTreeMap，键全按字典序（见 util.js）。
+    writeLine(JSON.stringify(sortKeysDeep({ ok: true, data, meta: meta.toJson() }), null, 2));
+    return;
+  }
+  writeLine(humanText(data, human, format === Format.Markdown));
+}
+
+/** 失败输出。**`--json` 下也走 stdout**（判卷要解析统一的失败形状），
+ * 但人类可读时把错误写 stderr —— 这样 `cmd > out.txt` 不会把报错混进结果。 */
+export function renderFailure(error, meta, format) {
+  if (format === Format.Json) {
+    writeLine(
+      JSON.stringify(
+        sortKeysDeep({ ok: false, error: error.toErrorJson(), meta: meta.toJson() }),
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+  const lines = [`✗ [${error.kindLabel}] ${error.message}（${error.code}）`];
+  // 给人看的细节优先（冲突清单这种又长又密的东西压成一行 JSON 等于没说）：
+  // 先摆事实，再给「下一步」—— 顺序反了会让人先看到结论再看到依据。
+  if (error.human) {
+    lines.push(error.human);
+  } else if (error.details && !isEmptyObject(error.details) && error.details !== null) {
+    lines.push(`  详情：${compactJson(error.details)}`);
+  }
+  if (error.hint) lines.push(`  下一步：${error.hint}`);
+  if (error.requestId) lines.push(`  request_id：${error.requestId}`);
+  process.stderr.write(`${lines.join('\n')}\n`);
+}
+
+function isEmptyObject(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.keys(value).length === 0
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 日志与进度（一律 stderr）
+// ---------------------------------------------------------------------------
+/** 告警：**不受 `--quiet` 影响**（那属于"结果的一部分"）。 */
+export function warn(message) {
+  process.stderr.write(`· ${message}\n`);
+}
+
+export function verbose(enabled, message) {
+  if (enabled) process.stderr.write(`· ${message}\n`);
+}
+
+/**
+ * 进度行（长任务专用）：`--quiet` 时静默。
+ *
+ * 与 `verbose` 的区别是**默认开着**：一次 5 分钟的导入，中途一行输出都没有，
+ * 用户只会以为进程挂了。告警（字段建失败、重试、降并发）走 `warn`。
+ */
+export function progress(quiet, message) {
+  if (!quiet) process.stderr.write(`${message}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// 人类可读渲染
+// ---------------------------------------------------------------------------
+/** table / md 下到底打印哪段文本：调用方给了 `human` 就用它，否则走通用渲染。 */
+function humanText(data, human, markdown) {
+  if (typeof human === 'string' && human.trim().length > 0) return human;
+  return renderHuman(data, markdown);
+}
+
+/**
+ * 人类可读渲染：能识别的形状渲染成表格，其余退回 JSON。
+ *
+ * 识别三种形状（覆盖全部命令的返回）：
+ * - `{"<name>s": [ {...}, ... ]}`（列表：bases / tables / fields / records / …）
+ * - 单条对象
+ * - 标量/其它 → JSON
+ */
+export function renderHuman(data, markdown) {
+  const list = listOf(data);
+  if (list) {
+    const { name, rows } = list;
+    let out = renderRows(name, rows, markdown);
+    const extras = extraScalars(data, name);
+    if (extras.length > 0) {
+      out += `${extras.map(([key, value]) => `${key}=${value}`).join('  ')}\n`;
+    }
+    return out;
+  }
+  if (isPlainObject(data)) {
+    // 单条对象：字段-值两列。
+    const rows = Object.entries(data)
+      .filter(([, value]) => value !== null && value !== undefined)
+      .map(([key, value]) => [key, scalar(value)]);
+    if (rows.length > 0 && rows.length <= 40) return renderPairs(rows, markdown);
+  }
+  if (data === null || data === undefined) return '';
+  return JSON.stringify(data, null, 2);
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 找 `{"<name>s":[...]}` 这种列表形状（**空列表也算**：`（bases：0 条）`
+ * 比把 `{"bases":[]}` 原样吐出来有用得多）。
+ */
+function listOf(data) {
+  if (!isPlainObject(data)) return null;
+  for (const [key, value] of Object.entries(data)) {
+    if (Array.isArray(value) && key.endsWith('s') && value.every(isPlainObject)) {
+      return { name: key, rows: value };
+    }
+  }
+  return null;
+}
+
+/** 列表之外还有哪些顶层标量（`total` / `has_more` / `next_seq` …）——
+ * 只渲染表格会把它们丢掉，而它们常常正是"下一页怎么翻"的答案。 */
+function extraScalars(data, listKey) {
+  if (!isPlainObject(data)) return [];
+  return Object.entries(data)
+    .filter(
+      ([key, value]) =>
+        key !== listKey &&
+        value !== null &&
+        value !== undefined &&
+        !Array.isArray(value) &&
+        !isPlainObject(value),
+    )
+    .map(([key, value]) => [key, scalar(value)]);
+}
+
+function renderRows(name, rows, markdown) {
+  if (rows.length === 0) return `（${name}：0 条 —— 这里现在什么都没有）`;
+  // 列 = 各行的键并集（保持首次出现顺序），最多 8 列。
+  const columns = [];
+  for (const row of rows) {
+    for (const key of Object.keys(row)) {
+      if (!columns.includes(key) && columns.length < 8) columns.push(key);
+    }
+  }
+  const body = rows.slice(0, 200).map((row) =>
+    columns.map((column) =>
+      Object.prototype.hasOwnProperty.call(row, column) ? scalar(row[column]) : '',
+    ),
+  );
+  let out = renderTable(columns, body, markdown);
+  out += `\n${
+    rows.length > 200
+      ? `（${name}：共 ${rows.length} 条，这里显示前 200 条；完整数据用 --json）`
+      : `（${name}：${rows.length} 条）`
+  }\n`;
+  const first = rows[0];
+  if (isPlainObject(first) && typeof first.id === 'string') {
+    out += `提示：第一条的 id = ${first.id}（后续命令可以直接用它）\n`;
+  }
+  return out;
+}
+
+function renderPairs(rows, markdown) {
+  const columns = ['字段', '值'];
+  const body = rows.map(([key, value]) => [key, value]);
+  return renderTable(columns, body, markdown);
+}
+
+/** 不带外部依赖的表格渲染。 */
+export function renderTable(columns, rows, markdown) {
+  const widths = columns.map((column, index) => {
+    let width = displayWidth(column);
+    for (const row of rows) {
+      const cell = row[index];
+      if (cell !== undefined) width = Math.max(width, displayWidth(truncateWidth(cell, 48)));
+    }
+    return width;
+  });
+
+  let out = '';
+  if (markdown) {
+    out += `| ${columns.map((column, i) => padWidth(column, widths[i])).join(' | ')} |\n`;
+    out += `|${widths.map((width) => '-'.repeat(width + 2)).join('|')}|\n`;
+    for (const row of rows) {
+      out += `| ${columns
+        .map((_, index) => padWidth(truncateWidth(row[index] ?? '', 48), widths[index]))
+        .join(' | ')} |\n`;
+    }
+    return out;
+  }
+
+  out += `${columns.map((column, i) => padWidth(column, widths[i])).join('  ')}\n`;
+  out += `${widths.map((width) => '-'.repeat(width)).join('  ')}\n`;
+  for (const row of rows) {
+    out += `${columns
+      .map((_, index) => padWidth(truncateWidth(row[index] ?? '', 48), widths[index]))
+      .join('  ')}\n`;
+  }
+  return out.replace(/\s+$/, '');
+}
+
+/** 值的单行表示：标量直接给，数组/对象压成一行 JSON。 */
+function scalar(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return numberToString(value);
+  if (typeof value === 'string') return value.replace(/\n/g, ' ');
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '—';
+    if (value.every((item) => typeof item === 'string' || typeof item === 'number')) {
+      return value.map((item) => (typeof item === 'string' ? item : numberToString(item))).join(', ');
+    }
+    return `${value.length} 项`;
+  }
+  if (isPlainObject(value)) {
+    if (typeof value.name === 'string') return value.name;
+    if (typeof value.id === 'string') return value.id;
+    return compactJson(value);
+  }
+  return String(value);
+}
+
+/** 数字渲染：整数值不要打印成 `1.0`（Rust 的 `Number::to_string` 也是这么做的）。 */
+function numberToString(value) {
+  if (Number.isInteger(value) && Math.abs(value) < 1e21) return String(value);
+  return String(value);
+}

package/src/core/runtime.js

@@ -0,0 +1,302 @@
+// 运行时：一次命令调用需要的全部上下文（profile / 服务端地址 / 凭据 / HTTP）。
+//
+// 这一层把"用户敲的那条命令"翻译成"要发给哪个后端、带哪枚令牌、要不要先续期"，
+// 并统一落实两条纪律：
+//
+// - **高风险写操作必须 `--yes`**（契约 §3.4）：没有 `--yes` 就本地退出码 2，不发请求。
+// - **`--dry-run` 只打印将发送的请求**（契约 §2.1）：一行都不落。
+
+import fs from 'node:fs';
+
+import { CliError, Kind, loginHint } from './error.js';
+import { CredentialStore, ConfigStore, Paths, hasAccess, hasRefresh, toCredentialJson } from './config.js';
+import { Http, Auth, ProxyPlan, USER_AGENT, proxyPlan, requestSpec } from './http.js';
+import { authedSend, authedUpload, ensureFresh } from './auth.js';
+import { Format, Meta, parseFormat, renderSuccess, renderSuccessWith } from './output.js';
+import { newDeviceId, newIdempotencyKey, rustIoErrorText } from './util.js';
+import { VERSION } from '../version.js';
+
+export class Runtime {
+  /**
+   * @param {object} globals 全局旗标（`parseArgv` 的输出）
+   * @param {string} command 命令标签（`meta.command`，如 `bitable base --list`）
+   */
+  constructor(globals, command) {
+    this.paths = Paths.resolve();
+    this.config = ConfigStore.load(this.paths);
+    this.credentials = CredentialStore.load(this.paths);
+    const profileOverride = globals.profile && globals.profile.trim().length > 0 ? globals.profile : null;
+    this.profile = profileOverride ?? this.config.currentName();
+    this.baseUrl = this.config.effectiveBaseUrl(globals.baseUrl, this.profile);
+    this.proxy = this.config.effectiveProxy();
+    this.format = globals.format ? parseFormat(globals.format) : globals.json ? Format.Json : Format.Table;
+    this.dryRun = globals.dryRun === true;
+    this.yes = globals.yes === true;
+    this.verbose = globals.verbose === true;
+    this.quiet = globals.quiet === true;
+    this.timeoutMs = globals.timeout === null || globals.timeout === undefined
+      ? null
+      : Number(globals.timeout) * 1000;
+    this.command = command;
+    this.startedAt = Date.now();
+    /** `me --json` 之类要按 markdown 渲染人类面时用。 */
+    this.markdown = this.format === Format.Markdown;
+  }
+
+  meta(requestId = null, serverVersion = null) {
+    return new Meta({
+      command: this.command,
+      cliVersion: VERSION,
+      serverVersion: serverVersion ?? null,
+      requestId: requestId ?? null,
+      durationMs: Date.now() - this.startedAt,
+      profile: this.profile,
+    });
+  }
+
+  /** 用给定的 request_id / server_version 收尾输出。 */
+  finish(data, requestId = null, serverVersion = null) {
+    renderSuccess(data, this.meta(requestId, serverVersion), this.format);
+  }
+
+  finishFrom(response, data) {
+    this.finish(data, response?.request_id ?? null, response?.server_version ?? null);
+  }
+
+  /** 收尾：`--json` 走 `data`（机器面稳定），table / md 用调用方给的人类可读视图。 */
+  finishWithHuman(data, human) {
+    const text = typeof human === 'function' ? human(this.markdown) : human;
+    renderSuccessWith(data, text, this.meta(), this.format);
+  }
+
+  finishFromWithHuman(response, data, human) {
+    const text = typeof human === 'function' ? human(this.markdown) : human;
+    renderSuccessWith(data, text, this.meta(response?.request_id ?? null, response?.server_version ?? null), this.format);
+  }
+
+  /** 高风险写操作的 `--yes` 闸门。 */
+  requireYes(what, example) {
+    return gateHighRisk(this.yes, what, example);
+  }
+
+  /** 需要后端地址的命令在这里统一报错（配置缺失 ≠ 网络故障）。 */
+  requireBaseUrl() {
+    if (!this.baseUrl) {
+      throw CliError.usage('还没有配置后端地址').withHint(
+        '先指一次后端：xinhe-oa-cli config --set base_url=http://127.0.0.1:8102',
+      );
+    }
+    return this.baseUrl;
+  }
+
+  /**
+   * 已登录上下文：没有凭据就是退出码 3 + 登录 hint。
+   *
+   * 返回的 `session.credential` 在续期时会被**原地替换** —— 调用方在请求结束后
+   * 应当 `runtime.persistCredentials(session)`，否则轮换后的 refresh 就丢了。
+   */
+  authed() {
+    const baseUrl = this.requireBaseUrl();
+    const stored = this.credentials.get(this.profile);
+    if (!stored || (!hasRefresh(stored) && !hasAccess(stored))) {
+      const phone = this.config.profile(this.profile).phone ?? null;
+      throw new CliError(Kind.Auth, 'auth.missing_token', '本机还没有登录凭据').withHint(
+        loginHint(phone),
+      );
+    }
+    const http = new Http(baseUrl, this.proxy, stored.device_id ?? '', this.timeoutMs);
+    return {
+      profile: this.profile,
+      http,
+      credential: stored,
+      store: this.credentials,
+      verbose: this.verbose,
+      runtime: this,
+    };
+  }
+
+  /** 把（可能已经轮换过的）凭据落盘。 */
+  persistCredentials(session) {
+    this.credentials.put(this.profile, toCredentialJson(session.credential));
+  }
+
+  /** 不需要凭据的 HTTP（登录流程、健康检查）。 */
+  anonymousHttp() {
+    const baseUrl = this.requireBaseUrl();
+    return new Http(baseUrl, this.proxy, this.deviceIdForLogin(), this.timeoutMs);
+  }
+
+  /** 登录前先确保 device_id 存在（服务端把 refresh 绑在它上面）。 */
+  deviceIdForLogin() {
+    const stored = this.credentials.get(this.profile);
+    if (stored && typeof stored.device_id === 'string' && stored.device_id.length > 0) {
+      return stored.device_id;
+    }
+    return newDeviceId();
+  }
+
+  /** 生成 device_id 并立刻落盘（`login` 的第一步就是它）。 */
+  ensureDeviceId() {
+    const stored = this.credentials.get(this.profile);
+    if (stored && typeof stored.device_id === 'string' && stored.device_id.length > 0) {
+      return stored.device_id;
+    }
+    const deviceId = newDeviceId();
+    this.credentials.put(this.profile, {
+      base_url: this.baseUrl ?? undefined,
+      device_id: deviceId,
+      tokens: {},
+    });
+    if (this.verbose) process.stderr.write(`· 生成设备指纹 ${deviceId} 并落盘\n`);
+    return deviceId;
+  }
+
+  /** 已认证请求 + 自动续期（凭据轮换后**立即落盘**）。 */
+  async sendAuthed(method, path, spec) {
+    const session = this.authed();
+    try {
+      const response = await authedSend(session, method, path, spec, this.command);
+      this.persistCredentials(session);
+      return response;
+    } catch (err) {
+      // 续期可能已经改了凭据；失败也要把它落盘（刷新过就是刷新过了）。
+      this.persistCredentials(session);
+      throw err;
+    }
+  }
+
+  /** 匿名请求（登录）。 */
+  async sendAnonymous(method, path, spec) {
+    const http = this.anonymousHttp();
+    return http.send(method, path, Auth.none(), spec, this.command);
+  }
+
+  /** multipart 上传（附件）。 */
+  async sendUpload(path, form, idempotencyKey = null) {
+    const session = this.authed();
+    try {
+      const response = await authedUpload(session, path, form, this.command, idempotencyKey);
+      this.persistCredentials(session);
+      return response;
+    } finally {
+      // 上传也可能触发续期：无论成败都把凭据落盘。
+      this.persistCredentials(session);
+    }
+  }
+
+  /** 先续期（有些命令要在本地算完再发请求，不能等到 send 那一刻）。 */
+  async ensureFreshToken() {
+    const session = this.authed();
+    await ensureFresh(session, this.verbose);
+    this.persistCredentials(session);
+  }
+
+  /** `--dry-run`：把将发送的请求打印出来（**不发**）。 */
+  dryRunReport(method, path, spec) {
+    const data = {
+      dry_run: true,
+      request: this.dryRunRequest(method, path, spec),
+      note: '--dry-run：没有发出任何请求，也没有写任何东西',
+    };
+    renderSuccess(data, this.meta(), this.format);
+  }
+
+  /** `--dry-run` 的单个请求描述（多请求的命令自己拼清单）。 */
+  dryRunRequest(method, path, spec) {
+    const base = this.baseUrl ?? '<未配置>';
+    const stored = this.credentials.get(this.profile);
+    const deviceId = stored?.device_id && stored.device_id.length > 0 ? stored.device_id : '<未生成>';
+    const headers = {
+      'User-Agent': USER_AGENT,
+      'X-CLI-Version': VERSION,
+      'X-Device-Id': deviceId,
+      'X-Request-Id': '<每请求生成>',
+      'Idempotency-Key': spec.idempotencyKey ?? null,
+      Authorization: stored ? 'Bearer <从凭据文件读，不打印>' : '<未登录>',
+    };
+    // `multipart` **永远在**（不是 multipart 请求时是 `null`）：与 Rust 的
+    // `dry_run_request` 逐字对齐 —— 少了这个键，`--dry-run` 的对拍就会有差异。
+    const request = {
+      method,
+      url: `${base.replace(/\/+$/, '')}${path}`,
+      headers,
+      query: (spec.query ?? []).map(([key, value]) => ({ [key]: value })),
+      body: spec.body ?? null,
+      multipart: spec.multipart
+        ? {
+            fields: spec.multipart.fields.map(([key]) => key),
+            file: spec.multipart.file
+              ? {
+                  field: spec.multipart.file[0],
+                  name: spec.multipart.file[1],
+                  bytes: Buffer.byteLength(spec.multipart.file[2]),
+                }
+              : null,
+          }
+        : null,
+    };
+    return request;
+  }
+
+  /** 代理策略的一句话描述（`doctor` / `config --show` 用）。 */
+  proxyDescription() {
+    const base = this.baseUrl ?? '';
+    const mode = this.proxy;
+    if (base.length === 0) return `${mode}（还没配 base_url）`;
+    const plan = proxyPlan(base, mode);
+    const explanation =
+      plan === ProxyPlan.DirectLoopback
+        ? '直连（本机/内网地址，忽略环境代理）'
+        : plan === ProxyPlan.System
+          ? '尊重环境代理（含 NO_PROXY）'
+          : '直连（配置里指定 proxy=none）';
+    return `${mode}：${explanation}`;
+  }
+}
+
+/**
+ * 高风险写操作的 `--yes` 闸门（纯函数：`--yes` 与"该不该问"都不碰网络）。
+ *
+ * 契约 §3.4：`high-risk-write` 没有 `--yes` 就是**本地**退出码 2，一个请求都不发。
+ */
+export function gateHighRisk(yes, what, example) {
+  if (yes) return;
+  throw CliError.usage(`${what} 是高风险写操作，必须显式确认`).withHint(
+    `确认后重跑：${example} --yes`,
+  );
+}
+
+/**
+ * 服务端 `{"data": ...}` 拆包。
+ *
+ * **键在就是它**（哪怕值是 `null`）：`{"data": null}` 要回 `null`，
+ * 不能因为"值是 null"就退回整个信封 —— 那会让调用方看到 `{"data": null}`
+ * 这种"多一层"的形状，与 Rust 的 `data_of` 不一致。
+ * 没有 `data` 键才原样返回整个 body。
+ */
+export function dataOf(response) {
+  const body = response?.body;
+  if (body !== null && typeof body === 'object' && Object.prototype.hasOwnProperty.call(body, 'data')) {
+    return body.data;
+  }
+  return body ?? {};
+}
+
+/** 生成幂等键（写操作自动带；`--idempotency-key` 可覆盖）。 */
+export function idempotencyKey(command, override) {
+  if (override !== null && override !== undefined && String(override).trim().length > 0) {
+    return String(override);
+  }
+  return newIdempotencyKey(command);
+}
+
+/** 读本地文件（附件上传、manifest 安装）。 */
+export function readFileBytes(path) {
+  try {
+    return fs.readFileSync(path);
+  } catch (err) {
+    throw CliError.usage(`读不了文件 ${path}：${rustIoErrorText(err)}`);
+  }
+}
+
+export { requestSpec };