@coderpp/yunxiao-cli 0.1.11 → 0.2.0

package/README.md

@@ -15,11 +15,11 @@ npm run build
 node dist/src/index.js --help
 ```
 
-如果后续发布为 npm 包，安装后可直接使用 `yunxiao` 命令。
+安装 npm 包后可直接使用 `yunxiao` 命令。
 
 ## 通过 npx 使用
 
-发布到 npm 后，可以直接用 `npx` 执行：
+可以直接用 `npx` 执行：
 
 ```bash
 npx @coderpp/yunxiao-cli mr list --state opened
@@ -453,3 +453,163 @@ npx --yes --package @coderpp/yunxiao-cli yunxiao workitem attachments <workitemI
 已有文件不覆盖，重复读取请选择新目录；失败返回非零退出码，清理未完成文件并保留已完成文件。
 仅支持带 `fileIdentifier` 的云效图片（PNG/JPEG/GIF/WebP/BMP/ICO）；外部图片和 data URL 会报错。
 需要工作项、评论、附件只读权限。完整内容不递归包含关联工作项或历史动态。
+
+## 0.2.0 新增能力
+
+以下命令与错误契约要求 `@coderpp/yunxiao-cli >= 0.2.0`。
+
+## 完整查询与可靠请求
+
+分页接口统一支持 `--page`、`--per-page`（1–100）、`--all-pages`：
+
+```bash
+yunxiao mr list --state opened --all-pages --output json
+yunxiao project list --all-pages
+yunxiao member list --all-pages
+yunxiao pipeline list --name 发布 --all-pages
+yunxiao pipeline runs 123 --all-pages
+yunxiao workitem mine --all-pages
+```
+
+默认每页 20 条；`pipeline failed-runs` 保持内部全量扫描和默认每页 30 条。
+工作项按项目分别分页后再过滤状态。没有使用 `--all-pages` 的状态查询会提示结果范围。
+分页优先采用响应头的下一页和实际页大小；无分页元信息时根据返回条数判断。
+重复页、分页中断或保护上限触发时返回非零退出码，不输出不完整的聚合结果。
+`project members`、工作项评论等无分页接口直接返回完整 API 响应，不接受分页选项。
+
+API 请求默认 `--timeout-ms 30000 --retries 2`。超时覆盖响应体读取；文件下载也使用该超时，失败清理未完成文件。
+仅只读操作会在网络临时错误、429、502/503/504 时退避重试，包括工作项/项目搜索和 MR 评论查询这些只读 POST。
+遵循 `Retry-After`；要求等待超过 60 秒时返回限流错误，由调用方稍后重试。
+写操作不自动重放，网络错误、超时或服务端 5xx 可能返回“写入结果未知”，应先查服务端状态。
+文件下载保留单次读取行为，不自动重试。
+
+未知参数、缺值、重复的非集合参数、额外位置参数、非法枚举和数值会报错。
+`--field` 可重复；`--key=a=b` 会完整保留 `a=b`。布尔参数支持 `--yes=false` 等写法。
+`--version` 和 `yunxiao mr diff --help` 等子命令帮助不需要 Token。
+原有 `pl`、`wi` 和命令别名继续支持，输出与主命令一致。
+
+## MR 详情、差异与评论
+
+```bash
+yunxiao mr get 2813489 12 --output json
+yunxiao mr diff 2813489 12 --output json
+yunxiao mr diff 2813489 12 --file src/example.ts --output text
+yunxiao mr diff 2813489 12 --from-patch-set-id target-id --to-patch-set-id source-id --output json
+yunxiao mr comments 2813489 12 --resolved=false --output json
+yunxiao mr comments 2813489 12 --comment-type INLINE_COMMENT --file src/example.ts
+
+yunxiao mr comment 2813489 12 --content-file ./review.md --yes
+yunxiao mr comment 2813489 12 --parent-id comment-id --content "已处理，请复核" --yes
+yunxiao mr comment 2813489 12 --file src/example.ts --line 42 --side new \
+  --from-patch-set-id target-id --to-patch-set-id source-id --content "这里需要处理空值" --yes
+```
+
+`mr diff` 从 MR 版本列表解析并固定版本 ID、提交 SHA；默认取最新目标和源版本。
+使用固定 SHA 调用代码比较 API（目标到源使用 merge-base；源版本之间使用直接比较），并与相同版本对的 MR 文件树核对文件对象 ID、数量及增删行数。
+响应包含版本 ID、SHA、`complete` 和逐文件原因；二进制、缺失、截断或比较不一致时标记不完整。
+这是完整性核对而非绕过服务端 diff 限额；跨库提交不可访问时会保留服务端错误。
+`--output text` 可直接读取 diff，但机器验收应检查 JSON 的 `complete`；成功读取不等同于内容完整。
+
+行内评论必须指定文件、正整数行号、`--side old|new` 和 `--to-patch-set-id`；未指定起始版本时解析最新目标版本。
+两端版本必须属于该 MR，文件必须存在于对应侧的变更树；服务端继续校验实际评论行位置。
+普通评论默认绑定最新源版本，也可用 `--to-patch-set-id` 固定版本。
+评论支持 `--parent-id` 回复，默认直接发表、未解决。评论编辑、删除、解决状态操作不在本轮范围。
+
+## 通用 MR 管理与发布恢复
+
+```bash
+yunxiao mr create 2813489 --source feature/demo --target master --title "功能说明" \
+  --description-file ./mr.md --reviewers user-1,user-2 --yes
+yunxiao mr update 2813489 12 --title "更新标题" --description-file ./mr.md --yes
+yunxiao mr update 2813489 12 --description= --yes
+yunxiao mr close 2813489 12 --yes
+yunxiao mr review 2813489 12 --opinion not-pass --comment-file ./review.md
+yunxiao mr release example-web master release --resume 12 --yes --output json
+```
+
+`mr create` 只创建；默认同仓库，可用 `--source-project-id` 指定源库。
+`mr review` 默认 `--opinion pass`，保留已有调用方式。
+新建、修改、关闭、评论、流水线启动和取消等新写命令都需要 `--yes`。
+
+发布按以下规则执行：
+
+- 仓库查询完整分页并精确匹配；同名歧义需要完整命名空间路径。
+- 创建前查找相同源/目标库及分支的未关闭 MR；发现已有 MR 返回错误、链接和显式恢复参数，避免自动接管。
+- `--resume` 校验 MR 的库及分支；已合并返回 `already-merged`，已关闭拒绝执行。
+- 仅在服务端能证明当前用户已于当前版本创建后评审通过时跳过评审，否则重新评审当前版本；评审前后核对源版本，变化时停止合并。
+- 创建请求结果未知时只读查询相同 MR 并返回恢复信息；不会自动再次创建或直接评审。
+- 合并响应丢失时查询 MR，已合并按成功返回，否则保留结果未知。
+- 明确的“源分支相对目标分支没有改动，不能新建代码评审”返回 `status: skipped`；其他创建错误仍失败。
+- 部分完成返回已创建 MR、已完成阶段、失败阶段及 `resumeArgs`。这些参数为数组，调用方应逐项传参；显式传入的 profile、配置文件、组织、域名和版本会被保留，Token 不会写入恢复参数。
+
+服务端最终负责合并冲突及门禁检查。版本检查和合并不是原子操作，无法保证检查后分支不会被其他人更新。
+MR 合并成功不表示流水线或部署成功；用流水线命令另行核对。
+
+## 流水线列表、日志、启动和取消
+
+```bash
+yunxiao pipeline list --name 发布 --all-pages
+yunxiao pipeline jobs 123 456 --output json
+yunxiao pipeline logs 123 456 789 --output text
+yunxiao pipeline start 123 --params-file ./run.json --yes --output json
+yunxiao pipeline cancel 123 456 --yes --output json
+```
+
+`jobs` 从运行详情整理阶段、任务信息；`logs` 返回单次日志快照，JSON 保留 `content`、`last`、`more`，文本模式在存在更多日志时提示。
+`start` 返回 `pipelineRunId`；`params-file` 内容直接写运行参数对象，CLI 按 API 要求包装成 `params` JSON 字符串。例如：
+
+```json
+{"envs":{"ENV":"test"},"runningBranchs":{"https://codeup.aliyun.com/org/app.git":"master"},"comment":"手动验证"}
+```
+
+`cancel` 返回接受结果和随后的运行状态；返回接受成功不代表运行已终止。读取状态失败返回部分完成错误。
+
+## 配置与诊断
+
+```bash
+yunxiao config set dev --organization-id org-id --edition center --token-env DEV_YUNXIAO_TOKEN --project-ids project-1
+yunxiao config use dev
+yunxiao config list
+yunxiao config show --profile dev
+yunxiao auth whoami --profile dev
+yunxiao doctor
+yunxiao doctor --remote
+```
+
+默认配置文件为 `$XDG_CONFIG_HOME/yunxiao/config.json`，未设置时为 `~/.config/yunxiao/config.json`。
+可用 `--config` 或 `YUNXIAO_CONFIG` 覆盖路径；配置文件权限为 0600。
+通过 `--profile`、`YUNXIAO_PROFILE` 或保存的当前 profile 选择配置。
+取值优先级：命令参数 > 环境变量 > profile > 默认值。
+profile 保存域名、组织、版本、项目、分类及 `token-env` 环境变量名，不保存明文 Token。
+`config show` 显示 profile 保存值；环境变量覆盖的最终效果可通过诊断核对。
+
+`doctor` 检查配置、Token 是否存在和域名/版本格式，不发请求。
+`doctor --remote` 额外读取当前用户验证连接和身份；不会验证每个项目的访问权限或写权限。
+
+## 文件输入与错误契约
+
+描述、内容、评审意见及运行参数分别支持 `--description-file`、`--content-file`、`--comment-file`、`--params-file`。
+文件名 `-` 读取 stdin；一次命令只能有一个 stdin 输入。相同字段的直接文本与文件输入互斥。
+UTF-8 内容、换行和等号原样保留；文件无法读取时在 API 调用前失败。
+
+```bash
+yunxiao workitem comment workitem-id --content-file ./comment.md --yes
+yunxiao workitem comment workitem-id --parent-id comment-id --content "回复" --yes
+yunxiao mr get 2813489 12 --output json --error-format json
+```
+
+成功结果写 stdout，分页提示与错误写 stderr。`--error-format json` 的错误结构：
+
+```json
+{"error":{"code":"PARTIAL_OPERATION","message":"...","details":{"localId":12,"completed":["create"],"failedStage":"review","resumeArgs":["mr","release","app","master","release","--resume","12","--yes"]}}}
+```
+
+服务端提供请求 ID 时错误中保留 `requestId`；Token 和带查询参数的 URL 会被脱敏。
+退出码从原先统一的 1 细分为：0 成功/明确跳过，1 未分类/响应格式错误，2 参数或配置错误，3 认证或权限错误，4 不存在，5 冲突或前置条件不满足，6 网络/超时/限流/服务不可用，7 部分完成或写入结果未知。
+已有脚本应以非零判断失败，需要细分时再按上述约定处理。
+
+### API 契约参考
+
+- [MR 版本列表](https://help.aliyun.com/zh/yunxiao/developer-reference/listchangerequestpatchsets-query-the-list-of-merge-request-versions)、[变更文件树](https://help.aliyun.com/zh/yunxiao/developer-reference/getchangerequesttree-queries-the-change-file-tree-for-merge-requests)、[固定提交比较](https://help.aliyun.com/zh/yunxiao/developer-reference/getcompare)
+- [MR 评论列表](https://help.aliyun.com/zh/yunxiao/developer-reference/listmergerequestcomments)、[创建 MR 评论](https://help.aliyun.com/zh/yunxiao/developer-reference/createchangerequestcomment)
+- [启动流水线](https://help.aliyun.com/zh/yunxiao/developer-reference/createpipelinerun)、[终止运行](https://help.aliyun.com/zh/yunxiao/developer-reference/updatepipelinerun)、[任务日志](https://help.aliyun.com/zh/yunxiao/developer-reference/getpipelinejobrunlog)

package/dist/src/arguments.d.ts

@@ -0,0 +1,11 @@
+export type FlagValue = string | boolean | Array<string | boolean>;
+export type Flags = Record<string, FlagValue>;
+export type ParsedArgs = {
+    positionals: string[];
+    flags: Flags;
+};
+export declare const specs: Record<string, [number, string]>;
+export declare function parseArgs(args: string[]): ParsedArgs;
+export declare function validateArgs(parsed: ParsedArgs): void;
+export declare function loadFileFlags(flags: Flags, stdin?: () => Promise<string>): Promise<void>;
+export declare function commandHelp(p: string[]): string;

package/dist/src/arguments.js

@@ -0,0 +1,271 @@
+import { readFile } from "node:fs/promises";
+import { CliError } from "./errors.js";
+const globals = "token domain organization-id edition profile config timeout-ms retries output json error-format help version";
+const pages = "page per-page all-pages";
+const merge = "yes merge-type message remove-source-branch";
+const workSearch = `${pages} project-id project-ids category assigned-to assignee created-by creator state status-ids status-name status-name-en subject created-after created-before from to date-field conditions order-by sort space-type`;
+export const specs = {
+    "mr list": [
+        0,
+        `${pages} state project-ids author-ids reviewer-ids search order-by sort created-before created-after`,
+    ],
+    "mr get": [2, ""],
+    "mr patches": [2, ""],
+    "mr tree": [2, "from-patch-set-id to-patch-set-id"],
+    "mr diff": [2, "file from-patch-set-id to-patch-set-id"],
+    "mr comments": [2, "file comment-type resolved patch-set-ids"],
+    "mr comment": [
+        2,
+        "yes content content-file file line side from-patch-set-id to-patch-set-id parent-id",
+    ],
+    "mr create": [
+        1,
+        "yes source target title description description-file reviewers source-project-id",
+    ],
+    "mr update": [2, "yes title description description-file"],
+    "mr close": [2, "yes"],
+    "mr review": [2, "comment comment-file opinion"],
+    "mr merge": [2, merge],
+    "mr approve-and-merge": [2, `${merge} comment comment-file`],
+    "mr release": [
+        3,
+        "yes create-only title description description-file merge-type resume",
+    ],
+    "project list": [
+        0,
+        `${pages} name conditions extra-conditions order-by sort`,
+    ],
+    "project get": [1, ""],
+    "project members": [1, "name role-id"],
+    "project member-add": [1, "yes user-ids role-id operator-id"],
+    "project member-remove": [1, "yes user-ids role-id operator-id"],
+    "member list": [0, pages],
+    "member get": [1, ""],
+    "pipeline list": [
+        0,
+        `${pages} name status create-start-time create-end-time start-time end-time`,
+    ],
+    "pipeline runs": [
+        1,
+        `${pages} status start-time end-time end-tme trigger-mode`,
+    ],
+    "pipeline failed-runs": [0, "hours start-time end-time end-tme per-page"],
+    "pipeline run": [2, ""],
+    "pipeline jobs": [2, ""],
+    "pipeline logs": [3, ""],
+    "pipeline start": [1, "yes params params-file"],
+    "pipeline cancel": [2, "yes"],
+    "pipeline retry-job": [3, "yes"],
+    "workitem list": [0, workSearch],
+    "workitem mine": [0, workSearch],
+    "workitem get": [1, ""],
+    "workitem activities": [1, ""],
+    "workitem comments": [1, ""],
+    "workitem timeline": [1, ""],
+    "workitem content": [1, "dir project-id project-ids download-attachments"],
+    "workitem images": [1, "dir"],
+    "workitem attachments": [1, "dir"],
+    "workitem comment": [1, "yes content content-file parent-id operator-id"],
+    "workitem update": [
+        1,
+        "yes fields field assigned-to assignee participants due-date plan-finish-at due-field",
+    ],
+    "auth whoami": [0, ""],
+    doctor: [0, "remote"],
+    "config list": [0, ""],
+    "config show": [0, ""],
+    "config use": [1, ""],
+    "config set": [1, "token-env project-ids category"],
+};
+const booleans = new Set("yes json help version all-pages create-only remove-source-branch download-attachments remote resolved".split(" "));
+const aliases = {
+    "project search": "project list",
+    "project add-member": "project member-add",
+    "project remove-member": "project member-remove",
+    "pipeline list-runs": "pipeline runs",
+    "pipeline get-run": "pipeline run",
+    "pipeline get": "pipeline run",
+    "pipeline retry": "pipeline retry-job",
+    "pipeline failed": "pipeline failed-runs",
+    "pipeline latest-failed-runs": "pipeline failed-runs",
+    "workitem search": "workitem list",
+    "workitem comment-create": "workitem comment",
+    "workitem history": "workitem timeline",
+};
+export function parseArgs(args) {
+    const positionals = [];
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--") {
+            positionals.push(...args.slice(i + 1));
+            break;
+        }
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const equal = arg.indexOf("=");
+        const name = arg.slice(2, equal < 0 ? undefined : equal);
+        let value;
+        if (booleans.has(name)) {
+            const raw = equal < 0 ? undefined : arg.slice(equal + 1);
+            if (raw !== undefined && raw !== "true" && raw !== "false")
+                throw new CliError("INVALID_ARGUMENT", `--${name} expects true or false.`);
+            value = raw !== "false";
+        }
+        else {
+            if (equal >= 0)
+                value = arg.slice(equal + 1);
+            else {
+                if (!args[i + 1] || args[i + 1].startsWith("--"))
+                    throw new CliError("INVALID_ARGUMENT", `--${name} requires a value.`);
+                value = args[++i];
+            }
+        }
+        if (flags[name] !== undefined && name !== "field")
+            throw new CliError("INVALID_ARGUMENT", `Duplicate --${name}.`);
+        flags[name] =
+            name === "field" && flags[name] !== undefined
+                ? [...(Array.isArray(flags[name]) ? flags[name] : [flags[name]]), value]
+                : value;
+    }
+    if (positionals[0] === "pl")
+        positionals[0] = "pipeline";
+    if (positionals[0] === "wi")
+        positionals[0] = "workitem";
+    const alias = aliases[positionals.slice(0, 2).join(" ")];
+    if (alias)
+        positionals.splice(0, 2, ...alias.split(" "));
+    return { positionals, flags };
+}
+export function validateArgs(parsed) {
+    const { positionals: p, flags: f } = parsed;
+    const key = p[0] === "doctor" ? "doctor" : p.slice(0, 2).join(" ");
+    const spec = specs[key];
+    if (!spec)
+        throw new CliError("INVALID_ARGUMENT", `Unknown command: ${key}`);
+    const allowed = new Set(`${globals} ${spec[1]}`.split(" "));
+    for (const name of Object.keys(f))
+        if (!allowed.has(name))
+            throw new CliError("INVALID_ARGUMENT", `Unknown option --${name} for ${key}.`);
+    const expected = (key === "doctor" ? 1 : 2) + spec[0];
+    if (p.length !== expected)
+        throw new CliError("INVALID_ARGUMENT", `${key} requires ${spec[0]} positional argument(s).`);
+    for (const name of [
+        "page",
+        "per-page",
+        "timeout-ms",
+        "hours",
+        "start-time",
+        "end-time",
+        "end-tme",
+        "create-start-time",
+        "create-end-time",
+        "trigger-mode",
+        "line",
+        "resume",
+        "retries",
+    ])
+        if (f[name] !== undefined) {
+            const n = Number(f[name]);
+            if (!Number.isSafeInteger(n) ||
+                n < (name === "retries" ? 0 : 1) ||
+                (name === "per-page" && n > 100) ||
+                (name === "retries" && n > 10))
+                throw new CliError("INVALID_ARGUMENT", `Invalid --${name}: ${f[name]}`);
+        }
+    for (const [name, values] of Object.entries({
+        edition: ["center", "region"],
+        sort: ["asc", "desc"],
+        opinion: ["pass", "not-pass"],
+        side: ["old", "new"],
+        output: ["table", "json", "text"],
+        "error-format": ["text", "json"],
+        "merge-type": ["ff-only", "no-fast-forward", "squash", "rebase"],
+        "comment-type": ["GLOBAL_COMMENT", "INLINE_COMMENT"],
+    }))
+        if (f[name] !== undefined && !values.includes(String(f[name])))
+            throw new CliError("INVALID_ARGUMENT", `Invalid --${name}: ${f[name]}`);
+    if (key === "mr list" &&
+        f.state !== undefined &&
+        !["opened", "merged", "closed"].includes(String(f.state)))
+        throw new CliError("INVALID_ARGUMENT", "Invalid --state.");
+    if (key.startsWith("workitem ") &&
+        f.state !== undefined &&
+        !["todo", "opened", "doing", "in-progress", "done", "completed"].includes(String(f.state)))
+        throw new CliError("INVALID_ARGUMENT", "Invalid --state.");
+    if (key === "mr comment" &&
+        f.file !== undefined &&
+        (!f.line || !f.side || !f["to-patch-set-id"]))
+        throw new CliError("INVALID_ARGUMENT", "Inline comments require --file, --line, --side and --to-patch-set-id.");
+    for (const [start, end] of [
+        ["start-time", "end-time"],
+        ["create-start-time", "create-end-time"],
+    ])
+        if (f[start] !== undefined &&
+            f[end] !== undefined &&
+            Number(f[start]) > Number(f[end]))
+            throw new CliError("INVALID_ARGUMENT", `--${start} must not exceed --${end}.`);
+    if (f.output === "text" && !["mr diff", "pipeline logs"].includes(key))
+        throw new CliError("INVALID_ARGUMENT", "--output text is only supported for mr diff and pipeline logs.");
+}
+export async function loadFileFlags(flags, stdin) {
+    let usedStdin = false;
+    for (const name of ["description", "content", "comment", "params"])
+        if (flags[`${name}-file`] !== undefined) {
+            if (flags[name] !== undefined)
+                throw new CliError("INVALID_ARGUMENT", `--${name} and --${name}-file are mutually exclusive.`);
+            const file = String(flags[`${name}-file`]);
+            if (file === "-" && usedStdin)
+                throw new CliError("INVALID_ARGUMENT", "stdin may only be read once.");
+            try {
+                flags[name] =
+                    file === "-"
+                        ? await (stdin
+                            ? stdin()
+                            : new Promise((resolve, reject) => {
+                                let text = "";
+                                process.stdin.setEncoding("utf8");
+                                process.stdin.on("data", (chunk) => (text += chunk));
+                                process.stdin.on("end", () => resolve(text));
+                                process.stdin.on("error", reject);
+                            }))
+                        : await readFile(file, "utf8");
+            }
+            catch {
+                throw new CliError("INVALID_ARGUMENT", `Unable to read --${name}-file.`);
+            }
+            if (file === "-")
+                usedStdin = true;
+        }
+}
+export function commandHelp(p) {
+    const prefix = p.join(" ");
+    function positionalNames(key, count) {
+        const [scope, command] = key.split(" ");
+        if (!count)
+            return [];
+        if (scope === "mr")
+            return command === "release"
+                ? ["repositoryName", "sourceBranch", "targetBranch"]
+                : ["repositoryId", "localId"].slice(0, count);
+        if (scope === "pipeline")
+            return ["pipelineId", "pipelineRunId", "jobId"].slice(0, count);
+        if (scope === "project")
+            return ["projectId"];
+        if (scope === "member")
+            return ["memberId"];
+        if (scope === "config")
+            return ["profileName"];
+        return [command === "content" ? "workitemUrl" : "workitemId"];
+    }
+    const formatFlag = (flag) => `--${flag}${booleans.has(flag) ? "" : " <value>"}`;
+    return (Object.entries(specs)
+        .filter(([key]) => !prefix || key === prefix || key.startsWith(prefix + " "))
+        .map(([key, [count, flags]]) => `yunxiao ${key}${positionalNames(key, count)
+        .map((name) => ` <${name}>`)
+        .join("")}\n  ${flags.split(" ").filter(Boolean).map(formatFlag).join(" ")}\n`)
+        .join("\n") +
+        `\nGlobal: ${globals.split(" ").map(formatFlag).join(" ")}\n`);
+}

package/dist/src/cli.d.ts

@@ -1,6 +1,7 @@
 import { type Fetcher } from "./client.js";
 export interface CliIo {
     fetcher?: Fetcher;
+    stdin?: () => Promise<string>;
     stdout?: (text: string) => void;
     stderr?: (text: string) => void;
 }