@milian/linker-cli 0.0.0-stage → 0.17.3

package/README.md

@@ -1,3 +1,118 @@
-# Temporary Holding Version
+# @milian/linker-cli
 
-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.
+iPaaS 集成管理平台的命令行客户端。零运行时依赖，只用 Node.js 内置模块。
+
+在终端里完成登录、查询连接器、创建并发布 API 资源、把接口封装成 MCP 工具等操作。
+
+## 环境要求
+
+Node.js 18 或以上。
+
+## 安装
+
+```bash
+npm install --global @milian/linker-cli
+```
+
+安装后提供 `linker-cli` 命令（Windows 为 `linker-cli.cmd`）。
+
+## 快速开始
+
+```bash
+linker-cli auth login      # 打开登录页
+linker-cli auth status     # 确认登录状态
+linker-cli platforms       # 列出连接器
+```
+
+`auth login` 会在本机起一个登录页并用默认浏览器打开。首次使用需要在页面上填写**平台地址（含端口）**和账号密码；地址会被记住，下次登录自动预填。
+
+不想自动开浏览器时加 `--no-browser`，终端会打印地址供手动访问。
+
+## 命令
+
+### 认证
+
+| 命令 | 说明 |
+|---|---|
+| `auth login` | 登录，默认拉起本地登录页 |
+| `auth login --quick` | 纯终端交互输入账密（仅限本地调试） |
+| `auth status` | 检查登录状态，已登录 exit 0 |
+| `auth logout` | 登出并清除本地凭证（幂等） |
+| `whoami` | 查看当前登录用户 |
+
+### 查询
+
+| 命令 | 说明 |
+|---|---|
+| `platforms` | 连接器应用列表，支持 `--name` 模糊查 |
+| `groups` | API 分组列表（含分组 code） |
+| `api list` | 某连接器下的 API 资源 |
+| `mcp sources` | 可创建 MCP 工具的来源 |
+| `config show` | 当前配置与生效的环境变量 |
+
+查询类命令都支持 `--json` 输出完整字段。
+
+### 写入
+
+| 命令 | 说明 |
+|---|---|
+| `platform create` | 创建连接器应用，先查分组 code 判重 |
+| `api create` | 创建并发布 API 资源 |
+| `api publish` | 重新发布已保存的 API 资源 |
+| `mcp create` | 把来源封装成 MCP 工具，支持批量 |
+
+写入类命令都支持 `--dry-run` 预览将要提交的内容，建议先预览再执行。
+
+### 兜底
+
+| 命令 | 说明 |
+|---|---|
+| `request <METHOD> <PATH>` | 携带授权发起任意请求，用于上面未覆盖的接口 |
+
+## 配置与凭证
+
+| 路径 | 内容 |
+|---|---|
+| `~/.linker-cli/config.json` | 平台地址、网关前缀、加密方式等 |
+| `~/.linker-cli/credentials.json` | 登录凭证，文件权限 0600 |
+
+用 `LINKER_CONFIG_DIR` 可以把这两份文件放到别处（测试时很有用）：
+
+```bash
+LINKER_CONFIG_DIR=/tmp/lk linker-cli auth status
+```
+
+**密码不落盘。** 它只在登录时用于生成加密串，不写入任何文件、也不进日志。
+
+## 环境变量
+
+优先级高于本地配置。
+
+| 变量 | 说明 |
+|---|---|
+| `LINKER_BASE_URL` | 平台地址。设置后登录页的地址栏会被锁定 |
+| `LINKER_CONFIG_DIR` | 配置与凭证目录 |
+| `LINKER_NO_BROWSER` | 设为 `1` 时不自动打开浏览器 |
+
+完整列表见 `linker-cli config env`。
+
+## 退出登录
+
+```bash
+linker-cli auth logout
+```
+
+删除本地凭证，**保留**平台地址等配置（下次登录仍会预填）。不调用任何远端接口，因此 token 在服务端仍有效直至自然过期。
+
+命令是幂等的，重复执行返回 `Already logged out` 且退出码为 0。
+
+## 更多
+
+```bash
+linker-cli --help              # 命令总览
+linker-cli api create --help   # 单个命令的完整参数
+```
+
+## License
+
+UNLICENSED

package/bin/linker-cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * 管道被提前关闭（典型场景：`linker-cli platforms | head -5`）时，stdout 会抛 EPIPE。
+ * 这不是错误，直接安静退出即可；否则会打一屏 Node 堆栈，把真正的输出冲掉。
+ */
+function silenceEpipe(stream) {
+  stream.on('error', (err) => {
+    if (err && err.code === 'EPIPE') process.exit(0);
+    throw err;
+  });
+}
+
+silenceEpipe(process.stdout);
+silenceEpipe(process.stderr);
+
+require('../src/cli')
+  .main(process.argv.slice(2))
+  .catch((err) => {
+    const msg = err && err.message ? err.message : String(err);
+    process.stderr.write('[error] ' + msg + '\n');
+    process.exit(1);
+  });

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@milian/linker-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.17.3",
+  "description": "Command line client for Milian iPaaS platform. Used as the CLI backend of a WorkBuddy connector.",
+  "license": "UNLICENSED",
+  "bin": {
+    "linker-cli": "bin/linker-cli.js"
+  },
+  "main": "src/cli.js",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "node bin/linker-cli.js",
+    "test": "node test/crypto-check.js && node test/url-check.js && node test/api-check.js && node test/create-check.js && node test/schema-check.js && node test/mcp-check.js && node test/entry-check.js && node test/login-check.js && node test/keepalive-check.js"
+  }
+}

package/src/api.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { buildEncodeStr } = require('./crypto');
+
+function joinUrl(baseUrl, pathname) {
+  const base = String(baseUrl || '').replace(/\/+$/, '');
+  const p = String(pathname || '');
+  return base + (p.startsWith('/') ? p : '/' + p);
+}
+
+/**
+ * 补上网关上下文前缀（默认 /index）。
+ * 平台所有接口都在 /index 之下；缺前缀时网关会把请求当静态资源，返回 HTTP 200 + 前端 HTML，
+ * 看起来像成功、实际没调到接口——这是最容易误判的一种失败。
+ */
+function applyPrefix(cfg, pathname) {
+  const prefix = String(cfg.apiPrefix || '').replace(/\/+$/, '');
+  const p = String(pathname || '');
+  if (!prefix) return p;
+  const full = p.startsWith('/') ? p : '/' + p;
+  if (full === prefix || full.startsWith(prefix + '/')) return full;
+  return prefix + full;
+}
+
+async function readJsonResponse(res) {
+  const text = await res.text();
+  let json = null;
+  try {
+    json = text ? JSON.parse(text) : null;
+  } catch {
+    /* 非 JSON 响应，保留原文 */
+  }
+  const contentType = res.headers.get('content-type') || '';
+  const isHtml = /text\/html/i.test(contentType) || /^\s*<(!doctype|html)/i.test(text);
+  return { status: res.status, json, text, isHtml };
+}
+
+/**
+ * 调用登录接口，返回归一化后的授权信息。
+ *
+ * baseUrlOverride：登录页上用户填写的平台地址。没有默认地址，必须显式提供，
+ * 或由配置（含 LINKER_BASE_URL 环境变量）给出。
+ */
+async function login(cfg, username, password, baseUrlOverride) {
+  const baseUrl = String(baseUrlOverride || cfg.baseUrl || '').replace(/\/+$/, '');
+  if (!baseUrl) {
+    throw new Error('平台地址为空：请在登录页填写平台地址，或先执行 config set baseUrl <地址>');
+  }
+  const encodeStr = buildEncodeStr({ username, password }, cfg);
+  const url = joinUrl(baseUrl, applyPrefix(cfg, cfg.loginPath));
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({ encodeStr }),
+      signal: AbortSignal.timeout(cfg.requestTimeoutMs)
+    });
+  } catch (err) {
+    throw new Error(`无法连接登录接口 ${url}: ${err.message}`);
+  }
+
+  const { status, json, text, isHtml } = await readJsonResponse(res);
+
+  if (!json) {
+    if (isHtml) {
+      throw new Error(
+        `登录接口返回了网页而不是数据：${url}\n` +
+          `        请核对 baseUrl 与 apiPrefix（当前 apiPrefix="${cfg.apiPrefix || ''}"）。` +
+          `可用 config set baseUrl / config set apiPrefix 调整。`
+      );
+    }
+    throw new Error(`登录接口返回非 JSON（HTTP ${status}）：${String(text).slice(0, 200)}`);
+  }
+  if (json.code !== 200) {
+    throw new Error(`登录失败：code=${json.code} msg=${json.msg || '未知错误'}`);
+  }
+
+  const data = json.data || {};
+  if (!data.tokenValue) {
+    throw new Error('登录成功但响应缺少 data.tokenValue，请核对接口版本');
+  }
+
+  return {
+    tokenName: data.tokenName || cfg.tokenHeader,
+    tokenValue: data.tokenValue,
+    nickName: data.nickName || '',
+    userName: data.userName || username,
+    userId: data.userId || '',
+    deptId: data.deptId || '',
+    deptCode: data.deptCode || '',
+    roles: Array.isArray(data.roles) ? data.roles : [],
+    tenant: data.tenant || null,
+    // 记录签发时的平台地址，换地址后可判定旧凭证已失效
+    baseUrl
+  };
+}
+
+/**
+ * 携带 Authorization 的业务请求
+ */
+async function authedRequest(cfg, cred, method, pathname, body, extraHeaders) {
+  const baseUrl = String(cfg.baseUrl || '').replace(/\/+$/, '');
+  if (!baseUrl) {
+    throw new Error(
+      '平台地址为空：请先登录并在登录页填写平台地址（auth login），或执行 config set baseUrl <地址>'
+    );
+  }
+
+  const headers = Object.assign(
+    {
+      Accept: 'application/json',
+      [cfg.tokenHeader]: (cfg.tokenPrefix || '') + cred.tokenValue
+    },
+    extraHeaders || {}
+  );
+
+  const init = {
+    method: String(method || 'GET').toUpperCase(),
+    headers,
+    signal: AbortSignal.timeout(cfg.requestTimeoutMs)
+  };
+
+  if (body !== undefined && body !== null && init.method !== 'GET' && init.method !== 'HEAD') {
+    headers['Content-Type'] = 'application/json';
+    init.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+
+  const url = joinUrl(baseUrl, applyPrefix(cfg, pathname));
+  let res;
+  try {
+    res = await fetch(url, init);
+  } catch (err) {
+    throw new Error(`请求失败 ${url}: ${err.message}`);
+  }
+
+  const parsed = await readJsonResponse(res);
+  if (res.status === 401 || res.status === 403) {
+    throw new Error(
+      `授权失效（HTTP ${res.status}），请重新登录：wb auth login` +
+        (parsed.json && parsed.json.msg ? `\n        服务端：${parsed.json.msg}` : '')
+    );
+  }
+  if (parsed.isHtml) {
+    throw new Error(
+      `接口返回了网页而不是数据：${url}\n` +
+        `        多因路径缺少网关前缀（当前 apiPrefix="${cfg.apiPrefix || ''}"），或被路由到了前端页面。`
+    );
+  }
+  return parsed;
+}
+
+module.exports = { login, authedRequest, joinUrl, applyPrefix };

package/src/cli.js

@@ -0,0 +1,222 @@
+'use strict';
+
+const pkg = require('../package.json');
+const { loadConfig, saveConfig, CONFIG_PATH, CRED_PATH, HOME_DIR, ENV_MAP } = require('./config');
+const { describeCipher, buildEncodeStr } = require('./crypto');
+const { authLogin, authLoginInteractive } = require('./commands/auth');
+const { authStatus, authLogout, whoami } = require('./commands/session');
+const { commandRequest } = require('./commands/request');
+const { commandPlatforms } = require('./commands/platforms');
+const { commandGroups } = require('./commands/groups');
+const { commandPlatformCreate } = require('./commands/platform-create');
+const { commandApiList } = require('./commands/api-list');
+const { commandApiCreate } = require('./commands/api-create');
+const { commandApiPublish } = require('./commands/api-publish');
+const { commandMcpSources, commandMcpCreate } = require('./commands/mcp');
+const { applyPrefix } = require('./api');
+
+const HELP = `linker-cli ${pkg.version} — 幂链iPaaS集成管理平台命令行客户端
+
+用法:
+  linker-cli auth login [--quick|--no-browser]  登录（默认本地登录页；--no-browser 不自动开浏览器）
+  linker-cli auth status [--json]      检查授权状态（exit 0 = 已登录；--json 输出结构化结果）
+  linker-cli auth logout               登出并清除本地授权（幂等）
+  linker-cli whoami [--json]           查看当前登录用户
+  linker-cli request <METHOD> <PATH>   携带授权发起请求
+        [--data <json>] [--data-file <file>] [--header k:v]
+  linker-cli platforms [--name <kw>]   查询连接器应用列表（默认全量）
+        [--page N] [--size N] [--json]
+  linker-cli platform create           创建连接器应用（先查分组 code 判重）
+        --name <名称> --group <code> --host <http://ip:port>
+        [--remark <描述>] [--type 5] [--dry-run] [--force]
+  linker-cli groups [--name <kw>]      查询 API 分组（含分组 code）
+  linker-cli api list                  查询连接器下的 API 资源（按名称模糊查）
+        --platform <platformId|名称> [--name <kw>] [--all] [--json]
+  linker-cli api create                创建并发布 API 资源（多接口组合）
+        --platform <id|名称> --name <名称> --url </path>
+        [--method POST] [--body <json|@file>] [--result <json|@file>]
+        [--query "a=1"] [--header "e: 2"] [--content-type 1]
+        [--required a,b.d] [--label "b.d=订单号"] [--labels @labels.json]
+        [--remark <描述>]
+        [--no-publish] [--dry-run] [--max-retry 3] [--json]
+  linker-cli api publish               已保存的 API 资源重新发布（含路径冲突重试）
+        --platform <id|名称> --api <outboundApiId|名称> [--dry-run] [--max-retry 3]
+  linker-cli mcp sources               查询可创建 MCP 工具的来源
+        [--type 1|2] [--name <kw>] [--platform <id|名称>] [--json]
+  linker-cli mcp create                把来源封装成 MCP 工具（支持批量）
+        --source <sourceId|名称>[,<...>] [--type 1|2] [--platform <id|名称>]
+        [--skip-exists] [--dry-run] [--json]
+  linker-cli config show               查看当前配置（含生效的环境变量）
+  linker-cli config set <k> <v>        修改配置项
+  linker-cli config env                列出可用环境变量
+  linker-cli config path               打印配置与凭证路径
+  linker-cli crypto describe           查看加密配置与密钥长度
+  linker-cli crypto encode <user> <pw> 生成 encodeStr（调试用，不发起登录）
+
+环境变量（优先级高于本地配置）:
+${Object.keys(ENV_MAP)
+  .map((k) => `  ${k}`)
+  .join('\n')}
+  LINKER_CONFIG_DIR                    配置/凭证目录，默认 ~/.linker-cli
+
+示例:
+  linker-cli auth login                      # 登录（平台地址在登录页填写）
+  linker-cli config set baseUrl http://主机:端口 # 仅脚本场景需要，交互式不必
+  linker-cli whoami --json
+  linker-cli request POST /sys/api/v1/flow/list --data '{"page":1,"size":20}'
+  linker-cli platforms                       # 全部连接器（pageSize=10000）
+  linker-cli platforms --name 钉钉           # 按名称模糊查
+  linker-cli groups                          # 全部分组 code
+  linker-cli api list --platform 泛微E10      # 某连接器下的 API 资源
+  linker-cli api create --platform 泛微E10 --name 查询订单 --url /order/query \\
+      --method POST --body '{"b":{"c":["string"],"d":7}}' --dry-run
+  linker-cli api publish --platform 泛微E10 --api 2118594622711623680
+  linker-cli mcp sources --platform 泛微E10 --name 应收
+  linker-cli mcp create --source 2034441472166580229 --dry-run
+  linker-cli platform create --name 滴滴 --group didi --host http://192.168.0.88:6001 --dry-run
+`;
+
+function printConfig(cfg) {
+  const shown = Object.assign({}, cfg);
+  if (shown.publicKey) shown.publicKey = shown.publicKey.slice(0, 64) + '... (已配置)';
+  if (shown.aesKey) shown.aesKey = '****** (已配置)';
+  if (shown.aesIv) shown.aesIv = '****** (已配置)';
+  process.stdout.write(JSON.stringify(shown, null, 2) + '\n');
+
+  const env = cfg._envApplied || [];
+  process.stdout.write(
+    env.length ? `\n当前生效的环境变量: ${env.join(', ')}\n` : '\n当前无环境变量覆盖\n'
+  );
+  const loginUrl = cfg.baseUrl
+    ? `${cfg.baseUrl}${applyPrefix(cfg, cfg.loginPath)}`
+    : '（未配置：首次登录时在登录页填写）';
+  process.stdout.write(`实际登录地址: ${loginUrl}\n`);
+}
+
+async function main(argv) {
+  const args = argv.slice();
+  const cmd = args[0];
+
+  if (!cmd || cmd === '-h' || cmd === '--help' || cmd === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (cmd === '-v' || cmd === '--version') {
+    process.stdout.write(pkg.version + '\n');
+    return;
+  }
+
+  const cfg = loadConfig();
+
+  if (cmd === 'auth') {
+    const sub = args[1] || 'status';
+
+    if (sub === 'login') {
+      const quick = args.includes('--quick');
+      const noBrowser = args.includes('--no-browser') || process.env.LINKER_NO_BROWSER === '1';
+      const cred = quick ? await authLoginInteractive(cfg) : await authLogin(cfg, { noBrowser });
+      process.stdout.write('\nLogged in as ' + (cred.nickName || cred.userName) + '\n');
+      process.stdout.write('平台地址: ' + (cred.baseUrl || cfg.baseUrl) + '\n');
+      process.exitCode = 0;
+      return;
+    }
+    if (sub === 'status') return authStatus(cfg, args.includes('--json'));
+    if (sub === 'logout') return authLogout();
+
+    throw new Error(`未知子命令: auth ${sub}`);
+  }
+
+  if (cmd === 'whoami') {
+    return whoami(cfg, args.includes('--json'));
+  }
+
+  if (cmd === 'request') {
+    return commandRequest(cfg, args.slice(1));
+  }
+
+  // 连接器应用 = platform；apps 为等价别名
+  if (cmd === 'platforms' || cmd === 'apps') {
+    return commandPlatforms(cfg, args.slice(1));
+  }
+
+  if (cmd === 'platform' || cmd === 'app') {
+    const sub = args[1];
+    if (!sub || sub === 'list') return commandPlatforms(cfg, args.slice(sub ? 2 : 1));
+    if (sub === 'create') return commandPlatformCreate(cfg, args.slice(2));
+    throw new Error(`未知子命令: ${cmd} ${sub}`);
+  }
+
+  if (cmd === 'groups') {
+    return commandGroups(cfg, args.slice(1));
+  }
+
+  if (cmd === 'api' || cmd === 'apis') {
+    const sub = args[1];
+    // 没有子命令、或直接跟参数（api --platform xxx）时，默认走 list
+    if (!sub || sub.startsWith('-')) return commandApiList(cfg, args.slice(1));
+    if (sub === 'list' || sub === 'ls') return commandApiList(cfg, args.slice(2));
+    if (sub === 'create' || sub === 'new' || sub === 'add') return commandApiCreate(cfg, args.slice(2));
+    if (sub === 'publish' || sub === 'pub') return commandApiPublish(cfg, args.slice(2));
+    throw new Error(`未知子命令: api ${sub}（可用: list / create / publish）`);
+  }
+
+  if (cmd === 'mcp') {
+    const sub = args[1];
+    // 没子命令、或直接跟参数（mcp --type 2）时，默认走 sources
+    if (!sub || sub.startsWith('-')) return commandMcpSources(cfg, args.slice(1));
+    if (sub === 'sources' || sub === 'source' || sub === 'list' || sub === 'ls') {
+      return commandMcpSources(cfg, args.slice(2));
+    }
+    if (sub === 'create' || sub === 'add' || sub === 'new') return commandMcpCreate(cfg, args.slice(2));
+    throw new Error(`未知子命令: mcp ${sub}（可用: sources / create）`);
+  }
+
+  if (cmd === 'config') {
+    const sub = args[1] || 'show';
+    if (sub === 'show') return printConfig(cfg);
+    if (sub === 'path') {
+      process.stdout.write(`home    : ${HOME_DIR}\nconfig  : ${CONFIG_PATH}\ncred    : ${CRED_PATH}\n`);
+      return;
+    }
+    if (sub === 'set') {
+      const key = args[2];
+      const value = args.slice(3).join(' ');
+      if (!key) throw new Error('用法: wb config set <key> <value>');
+      saveConfig({ [key]: value });
+      process.stdout.write(`已设置 ${key}\n`);
+      if (key === 'baseUrl' || key === 'apiPrefix' || key === 'loginPath') {
+        process.stdout.write('注意：地址/路径变更后旧登录态失效，需要重新登录： linker-cli auth login\n');
+      }
+      return;
+    }
+    if (sub === 'env') {
+      process.stdout.write('可用环境变量（优先级高于本地配置）:\n');
+      for (const [envKey, cfgKey] of Object.entries(ENV_MAP)) {
+        process.stdout.write(`  ${envKey.padEnd(22)} -> ${cfgKey}\n`);
+      }
+      process.stdout.write(`  ${'LINKER_CONFIG_DIR'.padEnd(22)} -> 配置/凭证目录（默认 ~/.linker-cli）\n`);
+      return;
+    }
+    throw new Error(`未知子命令: config ${sub}`);
+  }
+
+  if (cmd === 'crypto') {
+    const sub = args[1] || 'describe';
+    if (sub === 'describe') {
+      process.stdout.write(describeCipher(cfg) + '\n');
+      return;
+    }
+    if (sub === 'encode') {
+      const username = args[2];
+      const password = args[3];
+      if (!username || !password) throw new Error('用法: wb crypto encode <username> <password>');
+      process.stdout.write(buildEncodeStr({ username, password }, cfg) + '\n');
+      return;
+    }
+    throw new Error(`未知子命令: crypto ${sub}`);
+  }
+
+  throw new Error(`未知命令: ${cmd}\n\n${HELP}`);
+}
+
+module.exports = { main };