@mu-cabin/opms-cli

内部 OPMS 的 agent-first CLI。它把系统、资源池、系统菜单、角色资源/数据范围和人员角色关系封装成 可发现、可 dry-run、可回查的稳定命令；人员权限始终通过“人员 → 角色 → 资源/数据范围”管理。

构建

pnpm install
pnpm --filter @mu-cabin/opms-cli build:spec
pnpm --filter @mu-cabin/opms-cli typecheck
pnpm --filter @mu-cabin/opms-cli test
pnpm --filter @mu-cabin/opms-cli build

运行时只依赖 Node.js 18.17+，不调用 bash、chmod、rm 等外部命令；Windows 上由 npm 创建 opms.cmd shim，POSIX 上构建后额外设置可执行位。配置路径通过 node:path/os.homedir() 解析， 文件权限在 POSIX 固定为 0600，Windows 上以当前用户配置目录权限为保护边界。常规 npm 安装和 运行不依赖 POSIX shell；离线打包是维护脚本，需要在目标平台单独验证。

登录与配置

opms config init --base-url https://opms.example.invalid --username your.account
opms login
opms whoami --json

opms login 的账号提示可见、密码提示隐藏，两个提示都写 stderr。agent shell 没有 TTY 时应让用户在 自己的终端执行。CI 使用 --username + --password-stdin，不提供明文密码参数。

发布包不内置任何环境地址；首次使用必须通过 config init --base-url、全局 --base-url 或 OPMS_API_BASE 指定部署方提供的地址。配置保存在 ~/.opms/config.json，密码/token 保存在 ~/.opms/credentials.json。可用 OPMS_CONFIG_DIR、OPMS_PROFILE、OPMS_API_BASE、OPMS_USER、OPMS_PASSWORD、OPMS_TOKEN 覆盖。明文 HTTP 会产生 warning；仅在明确接受风险时设置 OPMS_ALLOW_HTTP=1。

每次响应若带 OpmsRefreshToken 会立即落盘。HTTP/业务码 401 时 CLI 使用已存账号密码重新登录， 只重试原请求一次，避免循环。

API 发现与通用调用

opms actions --search resource --json
opms schema queryBySystemId --json
opms call queryBySystemId -d '{"param":10}' --json
opms call bindToSystem -d @request.json --dry-run --json
opms update --dry-run --json

构建产物包含当前 /v3/api-docs 快照和 99 个 operation 的索引。重复 operationId 会使用规范化 action key；actions 会同时展示原 operationId。风险不能只看 HTTP method： risk-overrides.json 把全量覆盖、删除、解绑等 POST 标为 destructive。

领域命令

opms system list --json
opms resource-pool get "资源池名" --json
opms resource list --pool "资源池名" --json

opms menu get --system "系统名" --json
opms menu diff examples/menu.desired.json --json
opms menu apply examples/menu.desired.json --dry-run --json
opms menu apply examples/menu.desired.json --prune --yes --json

opms role grant-resource --role "角色" --system "系统" --resource code.a --dry-run --json
opms role revoke-resource --role "角色" --system "系统" --resource code.a --yes --json
opms role set-data-scope --role "角色" --resource code.a --system "系统" --branch-id 10 --dry-run --json

opms user permissions --user account --system "系统" --with-source --json
opms user grant-role --user account --role "角色" --dry-run --json
opms user revoke-role --user account --role "角色" --yes --json
opms user apply examples/user-roles.desired.json --dry-run --json

user permissions 查询指定人员在一个系统中实际生效的目录、菜单和控件，并默认只返回面向权限判断 所需的精简字段。--with-source 会额外标出每项资源来自哪个角色；输出不会包含 opmsRole、 opmsRoleName、GUEST 等内部人员分类字段。

menu apply 默认合并并保留 desired-state 未声明的系统资源；只有 --prune 才移除它们。user apply 默认只增加并保留现有角色；文件中的 replace:true 或命令行 --replace 才覆盖。产生移除时无 --yes 会以 exit 10 拦截。重复 apply 在状态一致时返回 changed:false，不会再写。

所有成功写操作都会回查；回查不一致返回 verification_failed，不能把 HTTP 200 当成最终成功。

输出与退出码

--json 始终输出单个 { ok, action, warnings?, data|error } envelope。主要退出码：

| exit | 含义 | | --- | --- | | 2 | 参数/用法错误 | | 3 | 未登录、token/账号密码失效 | | 4 | 唯一 ID 找不到 | | 5 | 网络、远端业务错误、回查失败 | | 7 | 配置格式无效 | | 8 | 已登录但无权限 | | 10 | destructive 变更需要确认 | | 11 | 本地校验或歧义失败 |

所有名称解析都要求精确唯一匹配；找不到或多候选时不会猜测。