@coderpp/yunxiao-cli 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# @coderpp/yunxiao-cli
+
+用于评审和合并云效 Codeup 合并请求的命令行工具。
+
+## 安装
+
+```bash
+npm install
+npm run build
+```
+
+本地运行：
+
+```bash
+node dist/src/index.js --help
+```
+
+如果后续发布为 npm 包，安装后可直接使用 `yunxiao` 命令。
+
+## 通过 npx 使用
+
+发布到 npm 后，可以直接用 `npx` 执行：
+
+```bash
+npx @coderpp/yunxiao-cli mr list --state opened
+```
+
+也可以指定版本：
+
+```bash
+npx @coderpp/yunxiao-cli@0.1.0 mr list --json
+```
+
+包内的可执行命令名仍然是 `yunxiao`，全局安装后可这样使用：
+
+```bash
+npm install -g @coderpp/yunxiao-cli
+yunxiao mr list --state opened
+```
+
+## 配置
+
+不要把个人访问令牌写入代码或提交到仓库。建议通过环境变量提供：
+
+```bash
+export YUNXIAO_TOKEN="pt-..."
+export YUNXIAO_DOMAIN="openapi-rdc.aliyuncs.com"
+export YUNXIAO_ORGANIZATION_ID="your-organization-id"
+export YUNXIAO_EDITION="center"
+```
+
+说明：
+
+- 中心版默认使用 `openapi-rdc.aliyuncs.com`，并需要 `YUNXIAO_ORGANIZATION_ID`。
+- Region 版设置 `YUNXIAO_EDITION=region`，通常不需要组织 ID。
+- 也可以用命令参数覆盖配置：`--token`、`--domain`、`--organization-id`、`--edition`。
+
+## 命令
+
+查询合并请求列表：
+
+```bash
+node dist/src/index.js mr list --state opened --project-ids 2813489 --per-page 20
+```
+
+输出 JSON：
+
+```bash
+node dist/src/index.js mr list --state opened --json
+```
+
+评审通过指定合并请求：
+
+```bash
+node dist/src/index.js mr review 2813489 12 --comment "LGTM"
+```
+
+合并指定合并请求：
+
+```bash
+node dist/src/index.js mr merge 2813489 12 --yes
+```
+
+评审通过并合并：
+
+```bash
+node dist/src/index.js mr approve-and-merge 2813489 12 --yes --merge-type squash --remove-source-branch
+```
+
+查询变更文件树：
+
+```bash
+node dist/src/index.js mr tree 2813489 12 \
+  --from-patch-set-id target-version-id \
+  --to-patch-set-id source-version-id
+```
+
+查询版本列表：
+
+```bash
+node dist/src/index.js mr patches 2813489 12
+```
+
+## 参数补充
+
+`repositoryId` 可以是代码库 ID，也可以是仓库完整路径，工具会自动做 URL 编码。
+
+会改变仓库状态的命令需要 `--yes`：
+
+- `mr merge`
+- `mr approve-and-merge`
+
+这是为了避免误合并。
+
+未指定 `--merge-type` 时，默认使用 `no-fast-forward`。

package/dist/src/cli.d.ts

@@ -0,0 +1,7 @@
+import { type Fetcher } from "./client.js";
+export interface CliIo {
+    fetcher?: Fetcher;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+export declare function runCli(args?: string[], env?: NodeJS.ProcessEnv, io?: CliIo): Promise<number>;

package/dist/src/cli.js

@@ -0,0 +1,204 @@
+import { YunxiaoClient } from "./client.js";
+const mergeTypes = new Set(["ff-only", "no-fast-forward", "squash", "rebase"]);
+export async function runCli(args = process.argv.slice(2), env = process.env, io = {}) {
+    const stdout = io.stdout ?? ((text) => process.stdout.write(text));
+    const stderr = io.stderr ?? ((text) => process.stderr.write(text));
+    try {
+        const parsed = parseArgs(args);
+        if (parsed.positionals.length === 0 || parsed.flags.help) {
+            stdout(helpText());
+            return 0;
+        }
+        const [scope, command, repositoryId, localIdRaw] = parsed.positionals;
+        if (scope !== "mr" || !command) {
+            throw new Error(`Unknown command: ${parsed.positionals.join(" ")}`);
+        }
+        const client = createClient(parsed.flags, env, io.fetcher);
+        let result;
+        if (command === "list") {
+            result = await client.listChangeRequests(listOptions(parsed.flags));
+            printResult(result, Boolean(parsed.flags.json), stdout);
+            return 0;
+        }
+        if (!repositoryId || !localIdRaw) {
+            throw new Error(`Command mr ${command} requires <repositoryId> and <localId>.`);
+        }
+        const localId = parseLocalId(localIdRaw);
+        switch (command) {
+            case "review":
+                result = await client.reviewChangeRequest(repositoryId, localId, {
+                    reviewComment: optionalString(parsed.flags.comment)
+                });
+                break;
+            case "merge":
+                requireConfirmation(parsed.flags);
+                result = await client.mergeChangeRequest(repositoryId, localId, mergeOptions(parsed.flags));
+                break;
+            case "approve-and-merge":
+                requireConfirmation(parsed.flags);
+                result = await client.approveAndMerge(repositoryId, localId, {
+                    reviewComment: optionalString(parsed.flags.comment),
+                    ...mergeOptions(parsed.flags)
+                });
+                break;
+            case "tree":
+                result = await client.getChangeRequestTree(repositoryId, localId, {
+                    fromPatchSetId: requiredFlag(parsed.flags, "from-patch-set-id"),
+                    toPatchSetId: requiredFlag(parsed.flags, "to-patch-set-id")
+                });
+                break;
+            case "patches":
+                result = await client.listChangeRequestPatchSets(repositoryId, localId);
+                break;
+            default:
+                throw new Error(`Unknown mr command: ${command}`);
+        }
+        printResult(result, Boolean(parsed.flags.json), stdout);
+        return 0;
+    }
+    catch (error) {
+        stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+function createClient(flags, env, fetcher) {
+    return new YunxiaoClient({
+        token: stringFlag(flags.token) ?? env.YUNXIAO_TOKEN ?? "",
+        domain: stringFlag(flags.domain) ?? env.YUNXIAO_DOMAIN ?? "openapi-rdc.aliyuncs.com",
+        organizationId: stringFlag(flags["organization-id"]) ?? env.YUNXIAO_ORGANIZATION_ID,
+        edition: (stringFlag(flags.edition) ?? env.YUNXIAO_EDITION),
+        fetcher
+    });
+}
+function parseArgs(args) {
+    const positionals = [];
+    const flags = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const [rawName, inlineValue] = arg.slice(2).split("=", 2);
+        if (inlineValue !== undefined) {
+            flags[rawName] = inlineValue;
+            continue;
+        }
+        const next = args[index + 1];
+        if (next && !next.startsWith("--") && !["json", "yes", "remove-source-branch", "help"].includes(rawName)) {
+            flags[rawName] = next;
+            index += 1;
+        }
+        else {
+            flags[rawName] = true;
+        }
+    }
+    return { positionals, flags };
+}
+function listOptions(flags) {
+    return {
+        page: optionalNumber(flags.page),
+        perPage: optionalNumber(flags["per-page"]),
+        projectIds: optionalString(flags["project-ids"]),
+        authorIds: optionalString(flags["author-ids"]),
+        reviewerIds: optionalString(flags["reviewer-ids"]),
+        state: optionalString(flags.state),
+        search: optionalString(flags.search),
+        orderBy: optionalString(flags["order-by"]),
+        sort: optionalString(flags.sort),
+        createdBefore: optionalString(flags["created-before"]),
+        createdAfter: optionalString(flags["created-after"])
+    };
+}
+function mergeOptions(flags) {
+    const mergeType = optionalString(flags["merge-type"]) ?? "no-fast-forward";
+    if (!mergeTypes.has(mergeType)) {
+        throw new Error(`Invalid --merge-type: ${mergeType}`);
+    }
+    return {
+        mergeMessage: optionalString(flags.message),
+        mergeType: mergeType,
+        removeSourceBranch: Boolean(flags["remove-source-branch"])
+    };
+}
+function requireConfirmation(flags) {
+    if (!flags.yes) {
+        throw new Error("This command changes repository state. Re-run with --yes after you have reviewed the merge request.");
+    }
+}
+function printResult(result, asJson, stdout) {
+    if (asJson) {
+        stdout(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    if (Array.isArray(result)) {
+        stdout(formatTable(result));
+        return;
+    }
+    stdout(`${JSON.stringify(result, null, 2)}\n`);
+}
+function formatTable(rows) {
+    if (rows.length === 0) {
+        return "No records found.\n";
+    }
+    const normalizedRows = rows.map((row) => (isRecord(row) ? row : { value: row }));
+    const keys = ["localId", "projectId", "title", "state", "sourceBranch", "targetBranch", "detailUrl"].filter((key) => normalizedRows.some((row) => row[key] !== undefined));
+    const widths = keys.map((key) => Math.max(key.length, ...normalizedRows.map((row) => String(row[key] ?? "").length)));
+    const line = (values) => values.map((value, index) => value.padEnd(widths[index])).join("  ");
+    return [
+        line(keys),
+        line(keys.map((_, index) => "-".repeat(widths[index]))),
+        ...normalizedRows.map((row) => line(keys.map((key) => String(row[key] ?? ""))))
+    ].join("\n") + "\n";
+}
+function parseLocalId(value) {
+    const localId = Number(value);
+    if (!Number.isInteger(localId) || localId <= 0) {
+        throw new Error(`<localId> must be a positive integer: ${value}`);
+    }
+    return localId;
+}
+function requiredFlag(flags, name) {
+    const value = optionalString(flags[name]);
+    if (!value) {
+        throw new Error(`Missing required flag --${name}.`);
+    }
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function stringFlag(value) {
+    return optionalString(value);
+}
+function optionalNumber(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const number = Number(value);
+    if (!Number.isInteger(number) || number <= 0) {
+        throw new Error(`Expected a positive integer, got: ${value}`);
+    }
+    return number;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function helpText() {
+    return `yunxiao - Yunxiao Codeup merge request helper
+
+Usage:
+  yunxiao mr list [--state opened] [--project-ids 2813489] [--json]
+  yunxiao mr review <repositoryId> <localId> [--comment "LGTM"]
+  yunxiao mr merge <repositoryId> <localId> --yes [--merge-type no-fast-forward]
+  yunxiao mr approve-and-merge <repositoryId> <localId> --yes [--merge-type no-fast-forward]
+  yunxiao mr tree <repositoryId> <localId> --from-patch-set-id <id> --to-patch-set-id <id>
+  yunxiao mr patches <repositoryId> <localId>
+
+Config:
+  YUNXIAO_TOKEN              Personal access token
+  YUNXIAO_DOMAIN             API domain, default openapi-rdc.aliyuncs.com
+  YUNXIAO_ORGANIZATION_ID    Required for center edition
+  YUNXIAO_EDITION            center or region
+`;
+}

package/dist/src/client.d.ts

@@ -0,0 +1,60 @@
+export type YunxiaoEdition = "center" | "region";
+export type Fetcher = (url: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export interface YunxiaoClientOptions {
+    token: string;
+    domain?: string;
+    organizationId?: string;
+    edition?: YunxiaoEdition;
+    fetcher?: Fetcher;
+}
+export interface ListChangeRequestsOptions {
+    page?: number;
+    perPage?: number;
+    projectIds?: string;
+    authorIds?: string;
+    reviewerIds?: string;
+    state?: "opened" | "merged" | "closed" | string;
+    search?: string;
+    orderBy?: "created_at" | "updated_at" | string;
+    sort?: "asc" | "desc" | string;
+    createdBefore?: string;
+    createdAfter?: string;
+}
+export interface ReviewChangeRequestOptions {
+    reviewComment?: string;
+    reviewOpinion?: "PASS" | "NOT_PASS";
+    submitDraftCommentIds?: string[];
+}
+export interface MergeChangeRequestOptions {
+    mergeMessage?: string;
+    mergeType?: "ff-only" | "no-fast-forward" | "squash" | "rebase";
+    removeSourceBranch?: boolean;
+}
+export interface ChangeRequestTreeOptions {
+    fromPatchSetId: string;
+    toPatchSetId: string;
+}
+export interface ApproveAndMergeOptions extends ReviewChangeRequestOptions, MergeChangeRequestOptions {
+}
+export declare class YunxiaoApiError extends Error {
+    readonly status: number;
+    readonly responseBody: string;
+    constructor(message: string, status: number, responseBody: string);
+}
+export declare class YunxiaoClient {
+    private readonly token;
+    private readonly domain;
+    private readonly organizationId?;
+    private readonly edition;
+    private readonly fetcher;
+    constructor(options: YunxiaoClientOptions);
+    listChangeRequests(options?: ListChangeRequestsOptions): Promise<unknown>;
+    reviewChangeRequest(repositoryId: string, localId: number, options?: ReviewChangeRequestOptions): Promise<unknown>;
+    mergeChangeRequest(repositoryId: string, localId: number, options?: MergeChangeRequestOptions): Promise<unknown>;
+    approveAndMerge(repositoryId: string, localId: number, options?: ApproveAndMergeOptions): Promise<unknown>;
+    getChangeRequestTree(repositoryId: string, localId: number, options: ChangeRequestTreeOptions): Promise<unknown>;
+    listChangeRequestPatchSets(repositoryId: string, localId: number): Promise<unknown>;
+    private changeRequestsPath;
+    private repositoryChangeRequestPath;
+    private request;
+}

package/dist/src/client.js

@@ -0,0 +1,118 @@
+export class YunxiaoApiError extends Error {
+    status;
+    responseBody;
+    constructor(message, status, responseBody) {
+        super(message);
+        this.status = status;
+        this.responseBody = responseBody;
+        this.name = "YunxiaoApiError";
+    }
+}
+export class YunxiaoClient {
+    token;
+    domain;
+    organizationId;
+    edition;
+    fetcher;
+    constructor(options) {
+        if (!options.token) {
+            throw new Error("Yunxiao token is required. Set YUNXIAO_TOKEN or pass --token.");
+        }
+        this.token = options.token;
+        this.domain = stripProtocol(options.domain ?? "openapi-rdc.aliyuncs.com");
+        this.organizationId = options.organizationId;
+        this.edition = options.edition ?? (options.organizationId ? "center" : "region");
+        this.fetcher = options.fetcher ?? fetch;
+        if (this.edition === "center" && !this.organizationId) {
+            throw new Error("Center edition requires organizationId. Set YUNXIAO_ORGANIZATION_ID or pass --organization-id.");
+        }
+    }
+    listChangeRequests(options = {}) {
+        return this.request("GET", this.changeRequestsPath(), options);
+    }
+    reviewChangeRequest(repositoryId, localId, options = {}) {
+        return this.request("POST", `${this.repositoryChangeRequestPath(repositoryId, localId)}/review`, undefined, {
+            ...compactBody({
+                reviewComment: options.reviewComment,
+                submitDraftCommentIds: options.submitDraftCommentIds
+            }),
+            reviewOpinion: options.reviewOpinion ?? "PASS"
+        });
+    }
+    mergeChangeRequest(repositoryId, localId, options = {}) {
+        return this.request("POST", `${this.repositoryChangeRequestPath(repositoryId, localId)}/merge`, undefined, {
+            ...compactBody({
+                mergeMessage: options.mergeMessage,
+                removeSourceBranch: options.removeSourceBranch
+            }),
+            mergeType: options.mergeType ?? "no-fast-forward"
+        });
+    }
+    async approveAndMerge(repositoryId, localId, options = {}) {
+        await this.reviewChangeRequest(repositoryId, localId, {
+            reviewComment: options.reviewComment,
+            reviewOpinion: options.reviewOpinion ?? "PASS",
+            submitDraftCommentIds: options.submitDraftCommentIds
+        });
+        return this.mergeChangeRequest(repositoryId, localId, {
+            mergeMessage: options.mergeMessage,
+            mergeType: options.mergeType,
+            removeSourceBranch: options.removeSourceBranch
+        });
+    }
+    getChangeRequestTree(repositoryId, localId, options) {
+        return this.request("GET", `${this.repositoryChangeRequestPath(repositoryId, localId)}/diffs/changeTree`, options);
+    }
+    listChangeRequestPatchSets(repositoryId, localId) {
+        return this.request("GET", `${this.repositoryChangeRequestPath(repositoryId, localId)}/diffs/patches`);
+    }
+    changeRequestsPath() {
+        if (this.edition === "center") {
+            return `/oapi/v1/codeup/organizations/${encodePathSegment(this.organizationId ?? "")}/changeRequests`;
+        }
+        return "/oapi/v1/codeup/changeRequests";
+    }
+    repositoryChangeRequestPath(repositoryId, localId) {
+        const encodedRepositoryId = encodePathSegment(repositoryId);
+        if (this.edition === "center") {
+            return `/oapi/v1/codeup/organizations/${encodePathSegment(this.organizationId ?? "")}/repositories/${encodedRepositoryId}/changeRequests/${localId}`;
+        }
+        return `/oapi/v1/codeup/repositories/${encodedRepositoryId}/changeRequests/${localId}`;
+    }
+    async request(method, path, query, body) {
+        const url = new URL(`https://${this.domain}${path}`);
+        for (const [key, value] of Object.entries(query ?? {})) {
+            if (value !== undefined && value !== null && value !== "") {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        const init = {
+            method,
+            headers: {
+                "content-type": "application/json",
+                "x-yunxiao-token": this.token
+            }
+        };
+        if (body) {
+            init.body = JSON.stringify(compactBody(body));
+        }
+        const response = await this.fetcher(url.toString(), init);
+        const text = await response.text();
+        if (!response.ok) {
+            throw new YunxiaoApiError(`Yunxiao API request failed with HTTP ${response.status}`, response.status, text);
+        }
+        if (!text) {
+            return null;
+        }
+        return JSON.parse(text);
+    }
+}
+function stripProtocol(domain) {
+    return domain.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}
+function encodePathSegment(value) {
+    return encodeURIComponent(value);
+}
+function compactBody(body) {
+    return Object.fromEntries(Object.entries(body).filter(([, value]) => value !== undefined && value !== null && value !== ""));
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+const exitCode = await runCli();
+process.exitCode = exitCode;

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@coderpp/yunxiao-cli",
+  "version": "0.1.0",
+  "description": "A CLI for Yunxiao Codeup merge request review and merge workflows.",
+  "type": "module",
+  "bin": {
+    "yunxiao": "dist/src/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "test": "tsc -p tsconfig.json && node --test dist/test/*.test.js"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.12",
+    "typescript": "^5.4.5"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ]
+}