@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# @xinhe-oa/cli（Node 版）
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+心河 OA 客户端 CLI 的 **Node 实现**：多维表格 / 应用 / 权限的唯一命令行入口。
+
+> **这是客户端的唯一入口**（2026-10-16 起）。Rust 版（仓库里的 `cli/`）已**冻结**在
+> `0.1.7`：不更新、不发布，只留作命令面规格与对拍的基准。
+> **版本号以本包的 `package.json` 为权威**（`src/version.js` 必须与它一致）。
+
+```bash
+npx @xinhe-oa/cli config --set base_url=https://oa.example.com
+npx @xinhe-oa/cli login --phone 13800000000
+npx @xinhe-oa/cli login --phone 13800000000 --code 123456
+npx @xinhe-oa/cli me --json
+```
+
+装一次就够（`npm i -g @xinhe-oa/cli` 之后直接用 `xinhe-oa-cli`）：
+
+```bash
+npm i -g @xinhe-oa/cli
+xinhe-oa-cli bitable base --list --json
+```
+
+## 这是什么、不是什么
+
+- **是**客户端唯一实现：153 条命令、同一套退出码、同一份 `--json` 形状。
+  命令面由 Rust 产物生成并逐字节对拍（见下文"为什么可信"）；Rust 版已冻结为对照。
+- **不是**一个新客户端：配置目录、凭据文件、设备指纹、`User-Agent` 与 Rust 版
+  **完全一致**，所以**换用 Node 版不需要重新登录**（见下文"从 Rust 版迁移"）。
+- **不需要**下载平台二进制：一份 JS 跑在所有 Node 支持的平台上
+  （Windows / macOS / Linux，x64 / arm64）。这正是它存在的理由 ——
+  客户机上不再有"我的系统该下哪个包"这件事。
+
+## 环境要求
+
+- **Node ≥ 20.11**（`node --version` 自查）。Rust 版已冻结、不再发布，没有 Node 的机器
+  请先装 Node；服务端产物通道发的那份入口脚本也会在 Node 太旧时直接说清楚。
+- **零运行时依赖**：只用 Node 内置模块，`npm i` 不会拉进任何第三方代码。
+
+## 与 Rust 版的关系
+
+| 事项 | 口径 |
+|---|---|
+| 命令面 | 同一份冻结契约（`docs/31-cli-contract.md`）。Node 版的 `schema --json` 与 Rust 产物**逐字节一致**（版本号字段除外） |
+| 退出码 | 0 成功 · 2 用法 · 3 未登录 · 4 权限 · 5 冲突 · 6 服务端 · 7 网络 · 8 版本过旧 |
+| 输出 | `--json` = `{ok,data,meta}`（键按字典序，与 Rust 的 `serde_json` 同形）；stdout 只放结果，进度与日志一律 stderr |
+| 配置目录 | `~/.config/xinhe-oa-cli/`（`XINHE_OA_CONFIG_DIR` 可覆盖）；`config.json` `0600`、`credentials.json` `0600`、目录 `0700` |
+| 设备指纹 | 每个 profile 一个 `device_id`，与 Rust 版共用同一份文件 |
+| `User-Agent` | 固定 `xinhe-oa-cli/1`（**不含版本号**）。服务端把 refresh 绑在 `HMAC(UA + X-Device-Id)` 上，带版本号会让用户一升级就被 `auth.device_mismatch` 踢下线 |
+| 版本上报 | 走 `X-CLI-Version` 头（Node 版报自己的版本） |
+| 代理 | 尊重 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` 与 `NO_PROXY`；支持 `http(s)://` 与 `socks5(h)://`；**本机与私网地址永远直连** |
+| 令牌纪律 | 令牌不进 argv、不进日志、不进错误详情；`config --show` 只显示掩码 |
+
+## 从 Rust 版迁移（不用重新登录）
+
+两份实现**读同一个目录、同一份 JSON**。所以：
+
+```bash
+# 1) 装 Node 版
+npm i -g @xinhe-oa/cli
+
+# 2) 直接用它 —— 原来的登录还在
+xinhe-oa-cli me --json
+```
+
+三条纪律值得知道：
+
+- `device_id` 沿用凭据文件里的那一个。**别删** `~/.config/xinhe-oa-cli/credentials.json`：
+  服务端把 refresh 绑在设备指纹上，换了设备就是一次短信重登。
+- 两个版本可以**共存**（`xinhe-oa-cli` 这个名字会指向后装的那个；Rust 版二进制
+  在 `/usr/local/bin/xinhe-oa-cli` 或安装脚本给的目录里，直接按路径调用即可）。
+- 回退：删掉 npm 包、按老办法用 Rust 二进制，凭据一样不用重登。
+
+## 为什么可信
+
+这套实现不是"照文档抄的"，而是**对着已发布的 Rust 产物逐字节对拍**出来的：
+
+```
+cli-node/scripts/gen-spec.py     # 从 Rust 产物的 schema --json 生成命令面规格
+cli-node/test/schema-parity.test.js   # 与 Rust 产物逐字节对拍（含 --agent 全文）
+cli-node/test/parse-surface.test.js   # 153 条命令的接受面 / 用法错误 / --yes 闸门
+```
+
+`scripts/rust_args.py` 会把 `args.rs` 里"`schema` 没登记、但 clap 实际接受"的旗标
+（如 `config --show`）与"取值可省"的旗标（如 `--show`）一并抽出来 ——
+这些正是手工移植必然会漏掉的地方。
+
+```bash
+npm test          # 全部闸门
+npm run lint      # 语法自检
+```
+
+## 常见问题
+
+**`还没有配置后端地址`** —— 先指一次后端：
+
+```bash
+xinhe-oa-cli config --set base_url=https://oa.example.com
+```
+
+**连不上内网后端** —— 内网直连时把代理彻底关掉：
+
+```bash
+xinhe-oa-cli config --set proxy=none
+xinhe-oa-cli doctor          # 看它这次到底走的是代理还是直连
+```
+
+**导入慢或断在半路** —— 直接重跑同一条命令，进度记录在
+`<config>/checkpoints/`，只补剩余批次（`--fresh` 才从头来）。
+
+**升级** —— 跟着 npm 走，**这是唯一的升级通道**：
+
+```bash
+npm i -g @xinhe-oa/cli@latest
+```
+
+先看一眼该不该升：
+
+```bash
+xinhe-oa-cli doctor --upgrade      # 问一次 npm，告诉你是不是最新、该跑哪条命令
+```
+
+三条刻意的设计（改之前先读 `src/commands/doctor.js` 顶上那段注释）：
+
+- `doctor --upgrade` **不替换自己**：它只问 npm 的 `latest`、与本机版本比一比、
+  给出可直接照抄的命令。升级由包管理器做，CLI 不动自己所在的文件树
+  （那会把 npm 的账本与实际内容弄不一致）。
+- 升级**不需要登录**：问 npm 与凭据无关。连不上 registry 时如实说明，
+  不报错、不影响其它自检结论（`doctor` 没网也必须能用）。
+- 内网源用 `XINHE_OA_NPM_REGISTRY=<你的 registry>` 覆盖，包名用
+  `XINHE_OA_NPM_PACKAGE` 覆盖（默认 `@xinhe-oa/cli`）。
+
+`doctor --upgrade --out <路径>` 是另一件事：把**服务端当前发布的那份产物**写到那个
+路径（核对 sha256 / 装到别处 / 排障用），当前可执行文件一个字节都不动。服务端那条通道
+（`/cli/download/{os}/{arch}`）发的是**本包的入口脚本**（见下），不是二进制 ——
+真发来一个 ELF/PE 时会被拒绝落盘（`cli.artifact_not_javascript`）。
+
+## 发版（维护者）
+
+```bash
+# ① 客户端本体：npm 是唯一升级通道，版本号以 package.json 为准
+#    （src/version.js 必须与它一致，release-check 会拦）
+npm publish --access public
+
+# ② 服务端产物通道（/cli/download/{os}/{arch}）：发一份 Node 入口脚本
+bash scripts/publish-download-artifact.sh              # 生成 + 归集到 <repo>/dist/cli
+bash scripts/publish-download-artifact.sh --archive-legacy   # 顺手留档旧 Rust 产物到 dist/cli-rust/
+```
+
+产物脚本的生成器是 `scripts/make-download-artifact.mjs`，模板是
+`scripts/download-entry.template.js`，验收在 `test/download-artifact.test.js`
+（三平台各一份、内容逐字节一致、`#!` 开头、版本钉死、参数与退出码原样透传）。
+为什么那份模板写成"老式 JS + `new Function`"：见模板顶部注释（两种模块解析 + 旧 Node）。
+
+上线步骤、服务端要改的几处、以及"老 Rust 客户端会自毁"的兜法，都在
+[`GO-LIVE.md`](./GO-LIVE.md)。
+
+
+## 许可
+
+UNLICENSED（内部使用）。

package/bin/xinhe-oa-cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// `xinhe-oa-cli` 入口（Node 版）。
+//
+// 这一层刻意只有三行：真正的解析/分发在 `src/main.js` 里，
+// 这样测试可以直接 import `runCli()` 而不用起子进程。
+//
+// argv[0] 今天是 `xinhe-oa-cli`，将来统一叫 `xinhe-oa`；两种名字都容忍
+// （`package.json` 的 `bin` 同时注册了两个名字）。
+import { runCli } from '../src/main.js';
+
+// 退出码由 `runCli` 返回：契约 §3.2 的 0/2/3/4/5/6/7/8。**不要**在这里兜底成 1 ——
+// 调用方（Agent、判卷、脚本）就是靠这个码分辨"用法错"与"网络不通"的。
+process.exitCode = await runCli(process.argv.slice(2));

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@xinhe-oa/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "心河 OA 客户端 CLI（Node 版）：多维表格 / 应用 / 权限的唯一命令行入口",
+  "keywords": [
+    "xinhe-oa",
+    "cli",
+    "bitable",
+    "oa"
+  ],
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "xinhe-oa-cli": "bin/xinhe-oa-cli.js",
+    "xinhe-oa": "bin/xinhe-oa-cli.js"
+  },
+  "main": "src/main.js",
+  "exports": {
+    ".": "./src/main.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.11"
+  },
+  "scripts": {
+    "test": "node --test --test-timeout 900000 test/*.test.js",
+    "lint": "node scripts/check-syntax.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xinhe-oa/cli.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/commands/application.js

@@ -0,0 +1,244 @@
+// 应用：`application --list|--show|--export|--install|--create|--copy`（契约 §2）。
+//
+// 应用 = 表 + 视图 + 表单 + 看板 + 工作流 + Skill + 权限的**可复制描述**（Manifest）。
+// 它是"把一套业务结构搬到另一家企业"的唯一入口，所以三条命令判 `high-risk-write`：
+//
+//   * `--install` / `--create`：往一家企业里**建结构**（建表 / 字段 / 视图 / 表单 /
+//     看板 / 工作流）。结构与数据不是一回事：写错一行记录删掉就完了，而表/字段一旦被
+//     业务用起来就改不回去 —— docs/26 §2.1 定的口径是 `mode=create` 只增不改、
+//     `update` 也只改显示名/视图配置且**永不删除**对象。后果不可逆，所以要 `--yes`。
+//   * `--copy`：把结构复制**到另一家企业** —— 目标企业是真实的生产环境，
+//     一次误敲就是往别人家里建了一整套表。
+//
+// 三条都在**发请求之前**过 `--yes` 闸门（退出码 2、一个字节都不发）。
+//
+// 与 Rust 版逐条对齐的四个细节：
+//
+// 1. **`--create` 是 `--install` 的别名**：Rust 的 `ApplicationAction::Install | Create`
+//    走同一个 `install()`，所以 `--create` 缺 `--file` 时报的是
+//    "`application --install` 需要 --file <manifest.json>"。这里照样只写一处实现。
+// 2. **manifest 只从本地文件读，不从 stdin 读**：manifest 是要被审阅、被复制、
+//    被 `--export --output` 落成文件的产物；stdin 一过手就没人能复核"我到底装了什么"。
+//    又因为它是本地 JSON，读文件与解析都在发请求**之前**做完 —— 坏文件当场退出码 2，
+//    不会变成一次服务端 400。
+// 3. **`--plan` 与 `--dry-run` 是两件事**：`--plan` 是服务端的 dry_run（只算不写，
+//    响应里的 `dry_run` 回显的是它）；全局 `--dry-run` 连请求都不发（契约 §2.1）。
+// 4. **`--list` 上的 `--tenant` 是兄弟参数**：clap 的扁平结构让 `--list` 也认这个旗标，
+//    但 Rust 的 `list()` 根本不读它 —— 这里同样不发 `tenant_id` query，
+//    保持"同参数 ⇒ 同请求"。
+
+import fs from 'node:fs';
+
+import { CliError, exactlyOne } from '../core/error.js';
+import { flagOn, flagValue } from '../core/args.js';
+import { dataOf, idempotencyKey, readFileBytes, requestSpec } from '../core/runtime.js';
+import { rustIoErrorText } from '../core/util.js';
+import { sortKeysDeep } from '../core/util.js';
+import { resolveTenant } from './tenant.js';
+
+/** `application --list|--show|--export|--install|--create|--copy` 的分发。 */
+export async function handleApplication({ args, runtime }) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--show', flagValue(args, '--show') !== null],
+      ['--export', flagValue(args, '--export') !== null],
+      ['--install', flagOn(args, '--install')],
+      ['--create', flagOn(args, '--create')],
+      ['--copy', flagValue(args, '--copy') !== null],
+    ],
+    'application',
+    '例：xinhe-oa-cli application --list --json',
+  );
+  if (action === '--list') return list(runtime);
+  if (action === '--show') return show(runtime, flagValue(args, '--show'));
+  if (action === '--export') return exportManifest(runtime, args, flagValue(args, '--export'));
+  if (action === '--install' || action === '--create') return install(runtime, args);
+  return copy(runtime, args, flagValue(args, '--copy'));
+}
+
+async function list(runtime) {
+  const response = await runtime.sendAuthed('GET', '/apps', requestSpec());
+  const data = dataOf(response);
+  // 缺键与显式 `null` 都要原样保留（`hasKey` 而不是 `??`）：服务端用
+  // `"total": null` 表达"这次不报总数"，套上默认值会把它变成一句假话。
+  runtime.finishFrom(response, {
+    apps: hasKey(data, 'apps') ? data.apps : [],
+    total: hasKey(data, 'total') ? data.total : null,
+    next_step: '看详情：xinhe-oa-cli application --show <APP_ID> --json',
+  });
+}
+
+async function show(runtime, appId) {
+  const response = await runtime.sendAuthed('GET', `/apps/${appId}`, requestSpec());
+  // 详情（含 manifest 与最近一次 apply_report）原样透传：调用方要什么键由服务端定，
+  // CLI 不加壳也不裁剪。
+  runtime.finishFrom(response, dataOf(response));
+}
+
+async function exportManifest(runtime, args, appId) {
+  const path = `/apps/${appId}/export`;
+  // 导出是 POST（服务端要算 checksum、可能要落审计），但**语义是读**：
+  // 风险级别是 `read`，所以它不需要 `--yes`，也不需要幂等键。
+  const spec = requestSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  // 服务端把可复制描述放在 `manifest` 键下；老版本/直出时没有这层包装，就用整个 data。
+  const manifest = hasKey(data, 'manifest') ? data.manifest : data;
+
+  // `--output` 与隐藏的 `--out` 是同一个出口（Rust：`output.or_else(out)`，output 优先）。
+  const target = flagValue(args, '--output') ?? flagValue(args, '--out');
+  if (target === null) {
+    runtime.finishFrom(response, { manifest });
+    return;
+  }
+
+  // 落盘要的是**与 Rust 相同的字节**：serde_json 的 pretty 是 2 空格缩进、
+  // 键按字典序、末尾一个换行。`bytes` 报的是**不含**那个换行的那段长度
+  // （Rust 先量 `body.len()` 再 `write(format!("{body}\n"))`）。
+  const body = JSON.stringify(sortKeysDeep(manifest), null, 2);
+  try {
+    fs.writeFileSync(target, `${body}\n`);
+  } catch (err) {
+    throw CliError.usage(`写不了 ${target}：${rustIoErrorText(err)}`);
+  }
+  runtime.finishFrom(response, {
+    path: target,
+    bytes: Buffer.byteLength(body, 'utf8'),
+    app_id: appId,
+    next_step: `装到另一个企业：xinhe-oa-cli application --install --file ${target} --tenant <TENANT_ID> --yes`,
+  });
+}
+
+/**
+ * `application --install` 与它的别名 `--create`。
+ *
+ * 闸门顺序**照抄 Rust**，因为顺序本身就是行为：确认 → `--file` → 企业 → `--mode`
+ * → 读文件 → 解析 JSON。没确认的调用连 `GET /me`（解析缺省企业）都不该发；
+ * `--mode` 拼错时也不该先去读盘（参数错与文件错同时存在时，先报参数错）。
+ */
+async function install(runtime, args) {
+  runtime.requireYes(
+    'application --install（应用会改结构：建表/字段/视图/表单/看板/工作流）',
+    'xinhe-oa-cli application --install --file <manifest.json> --tenant <TENANT_ID>',
+  );
+
+  const file = flagValue(args, '--file');
+  if (file === null) {
+    // 提示词里恒为 `--install`（Rust 的两个动作共用同一个函数）。
+    throw CliError.usage('`application --install` 需要 --file <manifest.json>').withHint(
+      'manifest 从 `application --export <APP_ID> --output ./app.json` 拿',
+    );
+  }
+
+  // 企业：显式 `--tenant` > 你的唯一可见企业（一次 `GET /me`）。
+  // **多企业时不替用户挑**（挑错就是往别人企业里建表）——`resolveTenant` 会以
+  // 退出码 2 报错并把候选企业列进 `details.visible_tenants`。
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  if (tenant === null) {
+    throw CliError.usage('安装应用必须指明企业').withHint(
+      '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 看有哪些企业',
+    );
+  }
+
+  // `--mode` 的 clap 默认值是 `create`：不给就等于 create（响应里也这么回显）。
+  //
+  // ⚠️ 这一步**刻意排在问企业之后**（与 Rust 同序）：于是"没给 --tenant 又把 --mode
+  // 写错"时会先发一次 `GET /me`（读）再报用法错误。不在这里"优化"成先判参数 ——
+  // 同参数下的请求序列也必须一样，否则对拍会红。
+  const mode = flagValue(args, '--mode') ?? 'create';
+  if (mode !== 'create' && mode !== 'update') {
+    throw CliError.usage(
+      `--mode 只能是 create（只增不改）或 update（允许改显示名/视图配置），收到 ${JSON.stringify(mode)}`,
+    );
+  }
+
+  // manifest 读到最后一刻才算数：解析失败 = 用法错误（2），不是服务端 400。
+  const manifest = parseManifest(file);
+  const plan = flagOn(args, '--plan');
+  const body = {
+    // 键序刻意按字典序摆：Rust 的 serde_json 是 BTreeMap，请求体里的键一律有序，
+    // 这样"同参数 ⇒ 同请求体"连字节面都对得上。
+    dry_run: plan,
+    manifest,
+    mode,
+    tenant_id: tenant,
+  };
+  // 写操作必带幂等键：网络抖动重发不会建出第二套结构（服务端按幂等键去重）。
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('application --install', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/apps', spec);
+
+  const response = await runtime.sendAuthed('POST', '/apps', spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    app_id: hasKey(data, 'id') ? data.id : hasKey(data, 'app_id') ? data.app_id : null,
+    mode,
+    dry_run: plan,
+    report: hasKey(data, 'report') ? data.report : data,
+    note: plan
+      ? '这是 --plan（服务端 dry_run）：一行都没落库'
+      : '应用 = 一次幂等的结构变更；同一 checksum 再应用会全部 skipped',
+  });
+}
+
+/** 复制结构到另一个企业（**一行数据都不搬**）。 */
+async function copy(runtime, args, appId) {
+  runtime.requireYes(
+    'application --copy（复制结构到另一个企业）',
+    `xinhe-oa-cli application --copy ${appId} --to-tenant <TENANT_ID>`,
+  );
+
+  // 只判"给没给"，不判空串：Rust 的 `Option<String>` 里 `Some("")` 也是给了，
+  // 服务端会自己拒掉空的企业 id（CLI 不替服务端发明校验规则）。
+  const target = flagValue(args, '--to-tenant');
+  if (target === null) {
+    throw CliError.usage('`application --copy` 需要 --to-tenant <TENANT_ID>');
+  }
+
+  // `semantic_map` 是"源字段语义 → 目标企业已有字段语义"的映射；本期恒为 null
+  // （docs/26 §2.1 第 4 条：目标企业已有同义字段时才需要映射）。
+  const body = { semantic_map: null, target_tenant_id: target };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('application --copy', flagValue(args, '--idempotency-key')),
+  });
+  const path = `/apps/${appId}/copy`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    app_id: appId,
+    target_tenant_id: target,
+    report: hasKey(data, 'report') ? data.report : data,
+    note: '复制只搬结构，**一行数据都不搬**（新企业记录数从 0 开始）',
+  });
+}
+
+/** 读 + 解析 manifest（读不了 / 不是 JSON 都是**本地**用法错误）。 */
+function parseManifest(file) {
+  const raw = readFileBytes(file);
+  let parsed;
+  try {
+    parsed = JSON.parse(raw.toString('utf8'));
+  } catch (err) {
+    throw CliError.usage(`${file} 不是合法 JSON：${err.message}`).withHint(
+      'manifest 应当是 `application --export` 导出的那个文件',
+    );
+  }
+  // 与 Rust 的 serde_json 同形：键按字典序（见 install() 里的说明）。
+  return sortKeysDeep(parsed);
+}
+
+/** 键存在就取（`null` 也算存在）—— 对齐 Rust `Value::get`：**不能**用 `??` 兜底，
+ * 否则服务端显式回的 `null` 会被当成"没这个键"而套上默认值。 */
+function hasKey(value, key) {
+  return (
+    value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, key)
+  );
+}