@coderpp/yunxiao-cli 0.1.11 → 0.2.0

package/dist/src/cli.js

@@ -1,41 +1,195 @@
-import { readWorkitemContent, downloadWorkitemImages, downloadWorkitemAttachments, parseWorkitemUrl } from "./workitem-content.js";
-import { YunxiaoClient } from "./client.js";
+import { readFileSync } from "node:fs";
+import { parseArgs, validateArgs, loadFileFlags, commandHelp, } from "./arguments.js";
+import { resolveConfig, configCommand } from "./config.js";
+import { CliError, errorInfo, redact } from "./errors.js";
+import { paginate } from "./pagination.js";
+import { runExtendedMr } from "./mr.js";
+import { runExtendedPipeline } from "./pipeline.js";
+import { readWorkitemContent, downloadWorkitemImages, downloadWorkitemAttachments, parseWorkitemUrl, } from "./workitem-content.js";
+import { YunxiaoClient, } from "./client.js";
 const mergeTypes = new Set(["ff-only", "no-fast-forward", "squash", "rebase"]);
-const outputFormats = new Set(["table", "json"]);
-const booleanFlags = new Set(["download-attachments", "all-pages", "create-only", "help", "json", "remove-source-branch", "yes"]);
+const outputFormats = new Set(["table", "json", "text"]);
 const workitemStateNames = new Map([
     ["todo", ["TODO", "待处理", "待办"]],
     ["opened", ["TODO", "待处理", "待办"]],
     ["doing", ["DOING", "IN_PROGRESS", "PROCESSING", "进行中", "处理中"]],
     ["in-progress", ["DOING", "IN_PROGRESS", "PROCESSING", "进行中", "处理中"]],
     ["done", ["DONE", "COMPLETED", "CLOSED", "已完成", "完成", "已关闭"]],
-    ["completed", ["DONE", "COMPLETED", "CLOSED", "已完成", "完成", "已关闭"]]
+    ["completed", ["DONE", "COMPLETED", "CLOSED", "已完成", "完成", "已关闭"]],
 ]);
 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));
+    let parsed;
+    let effectiveEnv = env;
     try {
-        const parsed = parseArgs(args);
-        if (parsed.positionals.length === 0 || parsed.flags.help) {
-            stdout(helpText());
+        parsed = parseArgs(args);
+        if (parsed.flags.version === true) {
+            stdout(JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version + "\n");
             return 0;
         }
-        const [scope, command] = parsed.positionals;
-        if (!command) {
-            throw new Error(`Unknown command: ${parsed.positionals.join(" ")}`);
+        if (parsed.positionals.length === 0 || parsed.flags.help === true) {
+            stdout(parsed.positionals.length
+                ? commandHelp(parsed.positionals)
+                : "yunxiao - Yunxiao DevOps command helper\n\n" + commandHelp([]));
+            return 0;
         }
+        validateArgs(parsed);
+        await loadFileFlags(parsed.flags, io.stdin);
+        const [scope, command] = parsed.positionals;
         const outputFormat = outputFormatFromFlags(parsed.flags);
-        const client = createClient(parsed.flags, env, io.fetcher);
-        const result = await runCommand(scope, command, parsed, client, env);
-        printResult(result, scope === "workitem" && ["content", "images", "attachments"].includes(command) ? "json" : outputFormat, stdout);
+        if (scope === "config") {
+            printResult(await configCommand(command, parsed.positionals[2], parsed.flags, env), outputFormat, stdout);
+            return 0;
+        }
+        effectiveEnv = await resolveConfig(parsed.flags, env);
+        if (scope === "doctor" && parsed.flags.remote !== true) {
+            const checks = {
+                tokenConfigured: !!(parsed.flags.token ?? effectiveEnv.YUNXIAO_TOKEN),
+                domain: parsed.flags.domain ??
+                    effectiveEnv.YUNXIAO_DOMAIN ??
+                    "openapi-rdc.aliyuncs.com",
+                edition: parsed.flags.edition ??
+                    effectiveEnv.YUNXIAO_EDITION ??
+                    ((parsed.flags["organization-id"] ??
+                        effectiveEnv.YUNXIAO_ORGANIZATION_ID)
+                        ? "center"
+                        : "region"),
+            };
+            createClient(parsed.flags, effectiveEnv, io.fetcher);
+            printResult({ ...checks, valid: true, remoteChecked: false }, outputFormat, stdout);
+            return 0;
+        }
+        const client = createClient(parsed.flags, effectiveEnv, io.fetcher);
+        let result;
+        if (scope === "auth")
+            result = await client.getCurrentUser();
+        else if (scope === "doctor")
+            result = {
+                valid: true,
+                remoteChecked: true,
+                user: await client.getCurrentUser(),
+                writePermissions: "not verified",
+            };
+        else
+            result = await runCommand(scope, command, parsed, client, effectiveEnv, stderr);
+        if (outputFormat === "text") {
+            const r = result;
+            if (scope === "pipeline") {
+                stdout(String(r.content ?? ""));
+                if (r.more)
+                    stderr("Server reports more log content; this is a single snapshot.\n");
+            }
+            else {
+                stdout(r.files
+                    .map((f) => `${f.complete ? "" : `# INCOMPLETE: ${f.reason}\n`}${f.diff}`)
+                    .join("\n"));
+                if (!r.complete)
+                    stderr("Diff is incomplete; inspect JSON metadata.\n");
+            }
+        }
+        else
+            printResult(result, scope === "workitem" &&
+                ["content", "images", "attachments"].includes(command)
+                ? "json"
+                : outputFormat, stdout);
         return 0;
     }
     catch (error) {
-        stderr(`${error instanceof Error ? error.message : String(error)}\n`);
-        return 1;
+        const info = errorInfo(error);
+        if (parsed?.positionals[0] === "mr" &&
+            parsed.positionals[1] === "release" &&
+            info.details &&
+            typeof info.details === "object") {
+            const details = info.details;
+            if (Array.isArray(details.resumeArgs)) {
+                const contextArgs = [
+                    "config",
+                    "profile",
+                    "domain",
+                    "organization-id",
+                    "edition",
+                ].flatMap((key) => typeof parsed.flags[key] === "string"
+                    ? [`--${key}`, String(parsed.flags[key])]
+                    : []);
+                info.details = {
+                    ...details,
+                    resumeArgs: [...details.resumeArgs, ...contextArgs],
+                };
+            }
+        }
+        const secrets = [
+            String(parsed?.flags.token ?? ""),
+            effectiveEnv.YUNXIAO_TOKEN ?? "",
+        ];
+        const json = parsed?.flags["error-format"] === "json" ||
+            args.includes("--error-format=json") ||
+            args.some((v, i) => v === "--error-format" && args[i + 1] === "json");
+        stderr(redact(json
+            ? JSON.stringify({
+                error: {
+                    code: info.code,
+                    message: info.message,
+                    requestId: info.requestId,
+                    details: info.details,
+                },
+            })
+            : info.message +
+                (info.details ? "\n" + JSON.stringify(info.details) : ""), secrets) + "\n");
+        return info.exitCode;
+    }
+}
+async function runCommand(scope, command, parsed, client, env, warn) {
+    const f = parsed.flags;
+    const pageOptions = {
+        page: optionalNumber(f.page),
+        perPage: optionalNumber(f["per-page"]) ?? 20,
+        allPages: hasFlag(f, "all-pages"),
+        warn,
+    };
+    if (scope === "mr" &&
+        [
+            "get",
+            "diff",
+            "comments",
+            "comment",
+            "create",
+            "update",
+            "close",
+        ].includes(command))
+        return runExtendedMr(command, parsed.positionals, f, client);
+    if (scope === "pipeline" &&
+        ["jobs", "logs", "start", "cancel"].includes(command))
+        return runExtendedPipeline(command, parsed.positionals, f, client);
+    if (scope === "mr" && command === "list")
+        return paginate((page, perPage) => client.listChangeRequests({ ...listOptions(f), page, perPage }), pageOptions);
+    if (scope === "project" && command === "list")
+        return paginate((page, perPage) => client.searchProjects({ ...projectSearchOptions(f), page, perPage }), pageOptions);
+    if (scope === "member" && command === "list")
+        return paginate((page, perPage) => client.listMembers({ page, perPage }), pageOptions);
+    if (scope === "pipeline" && command === "runs")
+        return paginate((page, perPage) => client.listPipelineRuns(parsed.positionals[2], {
+            ...pipelineRunsOptions(f),
+            page,
+            perPage,
+        }), pageOptions);
+    if (scope === "pipeline" && command === "list")
+        return paginate((page, perPage) => client.listPipelines({
+            page,
+            perPage,
+            pipelineName: optionalString(f.name),
+            statusList: optionalString(f.status),
+            createStartTime: optionalNumber(f["create-start-time"]),
+            createEndTime: optionalNumber(f["create-end-time"]),
+            executeStartTime: optionalNumber(f["start-time"]),
+            executeEndTime: optionalNumber(f["end-time"]),
+        }), pageOptions);
+    if (scope === "workitem" && ["list", "mine"].includes(command)) {
+        const flags = command === "mine"
+            ? { ...f, "assigned-to": (await client.getCurrentUser()).id }
+            : f;
+        return searchWorkitems(client, flags, env, warn);
     }
-}
-async function runCommand(scope, command, parsed, client, env) {
     switch (scope) {
         case "mr":
             return runMergeRequestCommand(command, parsed, client);
@@ -50,7 +204,7 @@ async function runCommand(scope, command, parsed, client, env) {
         case "wi":
             return runWorkitemCommand(command, parsed, client, env);
         default:
-            throw new Error(`Unknown command scope: ${scope}`);
+            throw new CliError("INVALID_ARGUMENT", `Unknown command scope: ${scope}`);
     }
 }
 async function runMergeRequestCommand(command, parsed, client) {
@@ -59,7 +213,7 @@ async function runMergeRequestCommand(command, parsed, client) {
         return client.listChangeRequests(listOptions(parsed.flags));
     }
     if (!repositoryId || !localIdRaw) {
-        throw new Error(`Command mr ${command} requires <repositoryId> and <localId>.`);
+        throw new CliError("INVALID_ARGUMENT", `Command mr ${command} requires <repositoryId> and <localId>.`);
     }
     if (command === "release") {
         requireConfirmation(parsed.flags);
@@ -68,16 +222,18 @@ async function runMergeRequestCommand(command, parsed, client) {
             sourceBranch: localIdRaw,
             targetBranch: requiredPositional(parsed.positionals[4], "targetBranch"),
             createOnly: hasFlag(parsed.flags, "create-only"),
+            resume: optionalNumber(parsed.flags.resume),
             title: optionalString(parsed.flags.title),
             description: optionalString(parsed.flags.description),
-            mergeType: mergeOptions(parsed.flags).mergeType
+            mergeType: mergeOptions(parsed.flags).mergeType,
         });
     }
     const localId = parseLocalId(localIdRaw);
     switch (command) {
         case "review":
             return client.reviewChangeRequest(repositoryId, localId, {
-                reviewComment: optionalString(parsed.flags.comment)
+                reviewComment: optionalString(parsed.flags.comment),
+                reviewOpinion: parsed.flags.opinion === "not-pass" ? "NOT_PASS" : "PASS",
             });
         case "merge":
             requireConfirmation(parsed.flags);
@@ -86,17 +242,17 @@ async function runMergeRequestCommand(command, parsed, client) {
             requireConfirmation(parsed.flags);
             return client.approveAndMerge(repositoryId, localId, {
                 reviewComment: optionalString(parsed.flags.comment),
-                ...mergeOptions(parsed.flags)
+                ...mergeOptions(parsed.flags),
             });
         case "tree":
             return client.getChangeRequestTree(repositoryId, localId, {
                 fromPatchSetId: requiredFlag(parsed.flags, "from-patch-set-id"),
-                toPatchSetId: requiredFlag(parsed.flags, "to-patch-set-id")
+                toPatchSetId: requiredFlag(parsed.flags, "to-patch-set-id"),
             });
         case "patches":
             return client.listChangeRequestPatchSets(repositoryId, localId);
         default:
-            throw new Error(`Unknown mr command: ${command}`);
+            throw new CliError("INVALID_ARGUMENT", `Unknown mr command: ${command}`);
     }
 }
 async function runProjectCommand(command, parsed, client) {
@@ -110,7 +266,7 @@ async function runProjectCommand(command, parsed, client) {
         case "members":
             return client.listProjectMembers(requiredPositional(projectId, "projectId"), {
                 name: optionalString(parsed.flags.name),
-                roleId: optionalString(parsed.flags["role-id"])
+                roleId: optionalString(parsed.flags["role-id"]),
             });
         case "member-add":
         case "add-member":
@@ -118,7 +274,7 @@ async function runProjectCommand(command, parsed, client) {
             return client.createProjectMember(requiredPositional(projectId, "projectId"), {
                 operatorId: optionalString(parsed.flags["operator-id"]),
                 roleId: optionalString(parsed.flags["role-id"]) ?? "project.participant",
-                userIds: requiredCsvFlag(parsed.flags, "user-ids")
+                userIds: requiredCsvFlag(parsed.flags, "user-ids"),
             });
         case "member-remove":
         case "remove-member":
@@ -126,10 +282,10 @@ async function runProjectCommand(command, parsed, client) {
             return client.deleteProjectMember(requiredPositional(projectId, "projectId"), {
                 operatorId: optionalString(parsed.flags["operator-id"]),
                 roleId: optionalString(parsed.flags["role-id"]) ?? "project.participant",
-                userIds: requiredCsvFlag(parsed.flags, "user-ids")
+                userIds: requiredCsvFlag(parsed.flags, "user-ids"),
             });
         default:
-            throw new Error(`Unknown project command: ${command}`);
+            throw new CliError("INVALID_ARGUMENT", `Unknown project command: ${command}`);
     }
 }
 async function runMemberCommand(command, parsed, client) {
@@ -137,16 +293,18 @@ async function runMemberCommand(command, parsed, client) {
         case "list":
             return client.listMembers({
                 page: optionalNumber(parsed.flags.page),
-                perPage: optionalNumber(parsed.flags["per-page"])
+                perPage: optionalNumber(parsed.flags["per-page"]),
             });
         case "get":
             return client.getMember(requiredPositional(parsed.positionals[2], "memberId"));
         default:
-            throw new Error(`Unknown member command: ${command}`);
+            throw new CliError("INVALID_ARGUMENT", `Unknown member command: ${command}`);
     }
 }
 async function runPipelineCommand(command, parsed, client) {
-    if (command === "failed-runs" || command === "failed" || command === "latest-failed-runs") {
+    if (command === "failed-runs" ||
+        command === "failed" ||
+        command === "latest-failed-runs") {
         return client.listLatestFailedPipelineRuns(latestFailedPipelineRunsOptions(parsed.flags));
     }
     const pipelineId = requiredPositional(parsed.positionals[2], "pipelineId");
@@ -165,7 +323,7 @@ async function runPipelineCommand(command, parsed, client) {
             requireConfirmation(parsed.flags);
             return client.retryPipelineJobRun(pipelineId, requiredPositional(pipelineRunId, "pipelineRunId"), requiredPositional(jobId, "jobId"));
         default:
-            throw new Error(`Unknown pipeline command: ${command}`);
+            throw new CliError("INVALID_ARGUMENT", `Unknown pipeline command: ${command}`);
     }
 }
 async function runWorkitemCommand(command, parsed, client, env) {
@@ -182,19 +340,23 @@ async function runWorkitemCommand(command, parsed, client, env) {
             const link = requiredPositional(workitemId, "workitemUrl");
             const { projectId, workitemId: id } = parseWorkitemUrl(link);
             if (!workitemProjectIds(parsed.flags, env).includes(projectId))
-                throw new Error("Link project is outside the configured project scope.");
+                throw new CliError("INVALID_ARGUMENT", "Link project is outside the configured project scope.");
             return readWorkitemContent(client, link, {
                 dir: optionalString(parsed.flags.dir) ?? `workitem-${id}-content`,
-                downloadAttachments: hasFlag(parsed.flags, "download-attachments")
+                timeoutMs: optionalNumber(parsed.flags["timeout-ms"]),
+                downloadAttachments: hasFlag(parsed.flags, "download-attachments"),
             });
         }
         case "images":
             return downloadWorkitemImages(client, requiredPositional(workitemId, "workitemId"), {
-                dir: optionalString(parsed.flags.dir) ?? `workitem-${workitemId}-images`
+                timeoutMs: optionalNumber(parsed.flags["timeout-ms"]),
+                dir: optionalString(parsed.flags.dir) ?? `workitem-${workitemId}-images`,
             });
         case "attachments":
             return downloadWorkitemAttachments(client, requiredPositional(workitemId, "workitemId"), {
-                dir: optionalString(parsed.flags.dir) ?? `workitem-${workitemId}-attachments`
+                timeoutMs: optionalNumber(parsed.flags["timeout-ms"]),
+                dir: optionalString(parsed.flags.dir) ??
+                    `workitem-${workitemId}-attachments`,
             });
         case "get":
             return client.getWorkitem(requiredPositional(workitemId, "workitemId"));
@@ -211,57 +373,28 @@ async function runWorkitemCommand(command, parsed, client, env) {
             return client.createWorkitemComment(requiredPositional(workitemId, "workitemId"), {
                 content: requiredFlag(parsed.flags, "content"),
                 operatorId: optionalString(parsed.flags["operator-id"]),
-                parentId: optionalString(parsed.flags["parent-id"])
+                parentId: optionalString(parsed.flags["parent-id"]),
             });
         case "timeline":
         case "history":
             return client.getWorkitemTimeline(requiredPositional(workitemId, "workitemId"));
         default:
-            throw new Error(`Unknown workitem command: ${command}`);
+            throw new CliError("INVALID_ARGUMENT", `Unknown workitem command: ${command}`);
     }
 }
 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",
+        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
+        fetcher,
+        timeoutMs: optionalNumber(flags["timeout-ms"]),
+        retries: flags.retries === undefined ? undefined : Number(flags.retries),
     });
 }
-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) {
-            setFlag(flags, rawName, inlineValue);
-            continue;
-        }
-        const next = args[index + 1];
-        if (next && !next.startsWith("--") && !booleanFlags.has(rawName)) {
-            setFlag(flags, rawName, next);
-            index += 1;
-        }
-        else {
-            setFlag(flags, rawName, true);
-        }
-    }
-    return { positionals, flags };
-}
-function setFlag(flags, name, value) {
-    const existing = flags[name];
-    if (existing === undefined) {
-        flags[name] = value;
-        return;
-    }
-    flags[name] = [...flagValues(existing), ...flagValues(value)];
-}
 function listOptions(flags) {
     return {
         page: optionalNumber(flags.page),
@@ -274,17 +407,18 @@ function listOptions(flags) {
         orderBy: optionalString(flags["order-by"]),
         sort: optionalString(flags.sort),
         createdBefore: optionalString(flags["created-before"]),
-        createdAfter: optionalString(flags["created-after"])
+        createdAfter: optionalString(flags["created-after"]),
     };
 }
 function projectSearchOptions(flags) {
     return {
-        conditions: optionalString(flags.conditions) ?? projectNameConditions(optionalString(flags.name)),
+        conditions: optionalString(flags.conditions) ??
+            projectNameConditions(optionalString(flags.name)),
         extraConditions: optionalString(flags["extra-conditions"]),
         orderBy: optionalString(flags["order-by"]) ?? "gmtCreate",
         page: optionalNumber(flags.page) ?? 1,
         perPage: optionalNumber(flags["per-page"]) ?? 20,
-        sort: optionalString(flags.sort) ?? "desc"
+        sort: optionalString(flags.sort) ?? "desc",
     };
 }
 function pipelineRunsOptions(flags) {
@@ -294,7 +428,7 @@ function pipelineRunsOptions(flags) {
         startTime: optionalNumber(flags["start-time"]),
         endTime: optionalNumber(flags["end-time"]) ?? optionalNumber(flags["end-tme"]),
         status: optionalString(flags.status),
-        triggerMode: optionalNumber(flags["trigger-mode"])
+        triggerMode: optionalNumber(flags["trigger-mode"]),
     };
 }
 function latestFailedPipelineRunsOptions(flags) {
@@ -302,38 +436,34 @@ function latestFailedPipelineRunsOptions(flags) {
         hours: optionalNumber(flags.hours) ?? 24,
         startTime: optionalNumber(flags["start-time"]),
         endTime: optionalNumber(flags["end-time"]) ?? optionalNumber(flags["end-tme"]),
-        perPage: optionalNumber(flags["per-page"]) ?? 30
+        perPage: optionalNumber(flags["per-page"]) ?? 30,
     };
 }
-async function searchWorkitems(client, flags, env) {
+async function searchWorkitems(client, flags, env, warn) {
     const projectIds = workitemProjectIds(flags, env);
     const perPage = optionalNumber(flags["per-page"]) ?? 20;
     const firstPage = optionalNumber(flags.page) ?? 1;
     const results = [];
     for (const projectId of projectIds) {
-        let page = firstPage;
-        while (true) {
-            const response = await client.searchWorkitems(workitemSearchOptions(flags, projectId, page, perPage, env));
-            const rows = Array.isArray(response) ? response : [response];
-            results.push(...rows.map((row) => addQueryProjectId(row, projectId)));
-            if (!hasFlag(flags, "all-pages") || !Array.isArray(response) || response.length < perPage) {
-                break;
-            }
-            page += 1;
-        }
+        const rows = await paginate((page, size) => client.searchWorkitems(workitemSearchOptions(flags, projectId, page, size, env)), { page: firstPage, perPage, allPages: hasFlag(flags, "all-pages"), warn });
+        results.push(...rows.map((row) => addQueryProjectId(row, projectId)));
     }
+    if (flags.state && !hasFlag(flags, "all-pages"))
+        warn?.("State filtering applies only to fetched pages; use --all-pages for complete results.\n");
     return filterWorkitems(results, flags);
 }
 function workitemSearchOptions(flags, projectId, page, perPage, env) {
     return {
-        category: optionalString(flags.category) ?? env.YUNXIAO_WORKITEM_CATEGORIES ?? "Req,Task,Bug",
+        category: optionalString(flags.category) ??
+            env.YUNXIAO_WORKITEM_CATEGORIES ??
+            "Req,Task,Bug",
         conditions: workitemConditions(flags),
         orderBy: optionalString(flags["order-by"]) ?? "gmtCreate",
         page,
         perPage,
         sort: optionalString(flags.sort) ?? "desc",
         spaceId: projectId,
-        spaceType: optionalString(flags["space-type"]) ?? "Project"
+        spaceType: optionalString(flags["space-type"]) ?? "Project",
     };
 }
 function workitemConditions(flags) {
@@ -345,8 +475,9 @@ function workitemConditions(flags) {
     const subject = optionalString(flags.subject);
     const from = optionalString(flags.from) ?? optionalString(flags["created-after"]);
     const to = optionalString(flags.to) ?? optionalString(flags["created-before"]);
-    if (rawConditions && (assignedTo || creator || statusIds || subject || from || to)) {
-        throw new Error("--conditions cannot be combined with shortcut workitem filters.");
+    if (rawConditions &&
+        (assignedTo || creator || statusIds || subject || from || to)) {
+        throw new CliError("INVALID_ARGUMENT", "--conditions cannot be combined with shortcut workitem filters.");
     }
     if (rawConditions) {
         return rawConditions;
@@ -364,7 +495,7 @@ function workitemConditions(flags) {
             value: csvValues(statusIds),
             toValue: null,
             className: "status",
-            format: "list"
+            format: "list",
         });
     }
     if (subject) {
@@ -374,7 +505,7 @@ function workitemConditions(flags) {
             value: [subject],
             toValue: null,
             className: "string",
-            format: "input"
+            format: "input",
         });
     }
     if (from || to) {
@@ -384,10 +515,12 @@ function workitemConditions(flags) {
             value: from ? [from] : [],
             toValue: to ?? null,
             className: "dateTime",
-            format: "input"
+            format: "input",
         });
     }
-    return filters.length > 0 ? JSON.stringify({ conditionGroups: [filters] }) : undefined;
+    return filters.length > 0
+        ? JSON.stringify({ conditionGroups: [filters] })
+        : undefined;
 }
 function userCondition(fieldIdentifier, value) {
     return {
@@ -396,12 +529,12 @@ function userCondition(fieldIdentifier, value) {
         value,
         toValue: null,
         className: "user",
-        format: "list"
+        format: "list",
     };
 }
 function workitemUpdateBody(flags) {
     const body = {
-        ...jsonObjectFlag(flags.fields)
+        ...jsonObjectFlag(flags.fields),
     };
     for (const field of flagStrings(flags.field)) {
         const [key, value] = parseKeyValue(field, "--field");
@@ -415,39 +548,40 @@ function workitemUpdateBody(flags) {
     if (participants) {
         body.participants = csvValues(participants);
     }
-    const dueDate = optionalString(flags["due-date"]) ?? optionalString(flags["plan-finish-at"]);
+    const dueDate = optionalString(flags["due-date"]) ??
+        optionalString(flags["plan-finish-at"]);
     if (dueDate) {
         body[optionalString(flags["due-field"]) ?? "dueDate"] = dueDate;
     }
     if (Object.keys(body).length === 0) {
-        throw new Error("No workitem fields to update. Use --assigned-to, --participants, --due-date, --fields, or --field.");
+        throw new CliError("INVALID_ARGUMENT", "No workitem fields to update. Use --assigned-to, --participants, --due-date, --fields, or --field.");
     }
     return body;
 }
 function mergeOptions(flags) {
     const mergeType = optionalString(flags["merge-type"]) ?? "no-fast-forward";
     if (!mergeTypes.has(mergeType)) {
-        throw new Error(`Invalid --merge-type: ${mergeType}`);
+        throw new CliError("INVALID_ARGUMENT", `Invalid --merge-type: ${mergeType}`);
     }
     return {
         mergeMessage: optionalString(flags.message),
         mergeType: mergeType,
-        removeSourceBranch: hasFlag(flags, "remove-source-branch")
+        removeSourceBranch: hasFlag(flags, "remove-source-branch"),
     };
 }
 function requireConfirmation(flags) {
     if (!hasFlag(flags, "yes")) {
-        throw new Error("This command changes state. Re-run with --yes after you have reviewed the operation.");
+        throw new CliError("INVALID_ARGUMENT", "This command changes state. Re-run with --yes after you have reviewed the operation.");
     }
 }
 function outputFormatFromFlags(flags) {
     const requestedOutput = optionalString(flags.output);
     if (hasFlag(flags, "json") && requestedOutput && requestedOutput !== "json") {
-        throw new Error("--json cannot be combined with --output table.");
+        throw new CliError("INVALID_ARGUMENT", "--json cannot be combined with a non-JSON --output.");
     }
-    const output = hasFlag(flags, "json") ? "json" : requestedOutput ?? "table";
+    const output = hasFlag(flags, "json") ? "json" : (requestedOutput ?? "table");
     if (!outputFormats.has(output)) {
-        throw new Error(`Invalid --output: ${output}. Supported formats: table, json.`);
+        throw new CliError("INVALID_ARGUMENT", `Invalid --output: ${output}. Supported formats: table, json.`);
     }
     return output;
 }
@@ -474,7 +608,7 @@ function formatTable(rows) {
     if (rows.length === 0) {
         return "No records found.\n";
     }
-    const normalizedRows = rows.map((row) => (isRecord(row) ? row : { value: row }));
+    const normalizedRows = rows.map((row) => isRecord(row) ? row : { value: row });
     const preferredKeys = [
         "pipelineName",
         "pipelineRunId",
@@ -506,16 +640,16 @@ function formatTable(rows) {
         "email",
         "sourceBranch",
         "targetBranch",
-        "detailUrl"
+        "detailUrl",
     ].filter((key) => normalizedRows.some((row) => row[key] !== undefined));
     const keys = preferredKeys.length > 0 ? preferredKeys : uniqueKeys(normalizedRows);
     const widths = keys.map((key) => Math.max(key.length, ...normalizedRows.map((row) => formatCellValue(row[key]).length)));
     const line = (values) => values.map((value, index) => value.padEnd(widths[index])).join("  ");
-    return [
+    return ([
         line(keys),
         line(keys.map((_, index) => "-".repeat(widths[index]))),
-        ...normalizedRows.map((row) => line(keys.map((key) => formatCellValue(row[key]))))
-    ].join("\n") + "\n";
+        ...normalizedRows.map((row) => line(keys.map((key) => formatCellValue(row[key])))),
+    ].join("\n") + "\n");
 }
 function uniqueKeys(rows) {
     return Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
@@ -523,7 +657,7 @@ function uniqueKeys(rows) {
 function formatKeyValueTable(record) {
     const rows = Object.entries(record).map(([key, value]) => ({
         key,
-        value: formatCellValue(value)
+        value: formatCellValue(value),
     }));
     return formatTable(rows);
 }
@@ -535,7 +669,11 @@ function formatCellValue(value) {
         return value.map(formatCellValue).join(",");
     }
     if (isRecord(value)) {
-        const displayValue = value.displayName ?? value.name ?? value.userName ?? value.title ?? value.id;
+        const displayValue = value.displayName ??
+            value.name ??
+            value.userName ??
+            value.title ??
+            value.id;
         if (displayValue !== undefined) {
             return String(displayValue);
         }
@@ -545,21 +683,21 @@ function formatCellValue(value) {
 }
 function parseLocalId(value) {
     const localId = Number(value);
-    if (!Number.isInteger(localId) || localId <= 0) {
-        throw new Error(`<localId> must be a positive integer: ${value}`);
+    if (!Number.isSafeInteger(localId) || localId <= 0) {
+        throw new CliError("INVALID_ARGUMENT", `<localId> must be a positive integer: ${value}`);
     }
     return localId;
 }
 function requiredPositional(value, name) {
     if (!value) {
-        throw new Error(`Missing required positional argument <${name}>.`);
+        throw new CliError("INVALID_ARGUMENT", `Missing required positional argument <${name}>.`);
     }
     return value;
 }
 function requiredFlag(flags, name) {
     const value = optionalString(flags[name]);
     if (!value) {
-        throw new Error(`Missing required flag --${name}.`);
+        throw new CliError("INVALID_ARGUMENT", `Missing required flag --${name}.`);
     }
     return value;
 }
@@ -579,16 +717,18 @@ function projectNameConditions(name) {
                     format: "input",
                     operator: "CONTAINS",
                     toValue: null,
-                    value: [name]
-                }
-            ]
-        ]
+                    value: [name],
+                },
+            ],
+        ],
     });
 }
 function workitemProjectIds(flags, env) {
-    const value = optionalString(flags["project-ids"]) ?? optionalString(flags["project-id"]) ?? env.YUNXIAO_PROJECT_IDS;
+    const value = optionalString(flags["project-ids"]) ??
+        optionalString(flags["project-id"]) ??
+        env.YUNXIAO_PROJECT_IDS;
     if (!value) {
-        throw new Error("Missing workitem project scope. Set --project-id, --project-ids, or YUNXIAO_PROJECT_IDS.");
+        throw new CliError("INVALID_ARGUMENT", "Missing workitem project scope. Set --project-id, --project-ids, or YUNXIAO_PROJECT_IDS.");
     }
     return csvValues(value);
 }
@@ -606,18 +746,20 @@ function filterWorkitems(rows, flags) {
         if (statusNameEn && statusText(row.status, "nameEn") !== statusNameEn) {
             return false;
         }
-        if (statusName && statusText(row.status, "name") !== statusName && statusText(row.status, "displayName") !== statusName) {
+        if (statusName &&
+            statusText(row.status, "name") !== statusName &&
+            statusText(row.status, "displayName") !== statusName) {
             return false;
         }
         if (state && state !== "all") {
             const expected = workitemStateNames.get(state);
             if (!expected) {
-                throw new Error(`Invalid --state: ${state}. Supported values: todo, doing, in-progress, done, completed, all.`);
+                throw new CliError("INVALID_ARGUMENT", `Invalid --state: ${state}. Supported values: todo, doing, in-progress, done, completed, all.`);
             }
             const actualValues = [
                 statusText(row.status, "nameEn"),
                 statusText(row.status, "name"),
-                statusText(row.status, "displayName")
+                statusText(row.status, "displayName"),
             ].filter((value) => Boolean(value));
             return actualValues.some((actual) => expected.includes(actual));
         }
@@ -638,14 +780,14 @@ function jsonObjectFlag(value) {
     }
     const parsed = JSON.parse(raw);
     if (!isRecord(parsed) || Array.isArray(parsed)) {
-        throw new Error("--fields must be a JSON object.");
+        throw new CliError("INVALID_ARGUMENT", "--fields must be a JSON object.");
     }
     return parsed;
 }
 function parseKeyValue(value, flagName) {
     const separatorIndex = value.indexOf("=");
     if (separatorIndex <= 0) {
-        throw new Error(`${flagName} expects key=value, got: ${value}`);
+        throw new CliError("INVALID_ARGUMENT", `${flagName} expects key=value, got: ${value}`);
     }
     return [value.slice(0, separatorIndex), value.slice(separatorIndex + 1)];
 }
@@ -685,7 +827,9 @@ function hasFlag(flags, name) {
 }
 function optionalString(value) {
     if (Array.isArray(value)) {
-        return [...value].reverse().find((item) => typeof item === "string");
+        return [...value]
+            .reverse()
+            .find((item) => typeof item === "string");
     }
     return typeof value === "string" ? value : undefined;
 }
@@ -699,58 +843,10 @@ function optionalNumber(value) {
     }
     const number = Number(stringValue);
     if (!Number.isInteger(number) || number <= 0) {
-        throw new Error(`Expected a positive integer, got: ${stringValue}`);
+        throw new CliError("INVALID_ARGUMENT", `Expected a positive integer, got: ${stringValue}`);
     }
     return number;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
-function helpText() {
-    return `yunxiao - Yunxiao DevOps command helper
-
-Usage:
-  yunxiao mr list [--state opened] [--project-ids 2813489] [--output table|json]
-  yunxiao mr review <repositoryId> <localId> [--comment "LGTM"] [--output table|json]
-  yunxiao mr merge <repositoryId> <localId> --yes [--merge-type no-fast-forward] [--output table|json]
-  yunxiao mr approve-and-merge <repositoryId> <localId> --yes [--merge-type no-fast-forward] [--output table|json]
-  yunxiao mr release <repositoryName> <sourceBranch> <targetBranch> --yes [--create-only] [--title "Release"] [--output table|json]
-  yunxiao mr tree <repositoryId> <localId> --from-patch-set-id <id> --to-patch-set-id <id> [--output table|json]
-  yunxiao mr patches <repositoryId> <localId> [--output table|json]
-  yunxiao project list [--name keyword] [--output table|json]
-  yunxiao project get <projectId> [--output table|json]
-  yunxiao project members <projectId> [--name keyword] [--role-id project.admin] [--output table|json]
-  yunxiao project member-add <projectId> --user-ids user1,user2 [--role-id project.participant] --yes
-  yunxiao project member-remove <projectId> --user-ids user1,user2 [--role-id project.participant] --yes
-  yunxiao member list [--page 1] [--per-page 100] [--output table|json]
-  yunxiao member get <memberId> [--output table|json]
-  yunxiao pipeline failed-runs [--hours 24] [--output table|json]
-  yunxiao pipeline runs <pipelineId> [--status FAIL] [--start-time 1729178040000] [--end-time 1729181640000] [--output table|json]
-  yunxiao pipeline run <pipelineId> <pipelineRunId> [--output table|json]
-  yunxiao pipeline retry-job <pipelineId> <pipelineRunId> <jobId> --yes [--output table|json]
-  yunxiao workitem list --project-ids p1,p2 [--assigned-to userId] [--created-by userId] [--state todo|doing|done] [--from "2026-04-01 00:00:00"] [--to "2026-04-30 23:59:59"]
-  yunxiao workitem mine --project-ids p1,p2 [--state todo|doing|done] [--output table|json]
-  yunxiao workitem get <workitemId> [--output table|json]
-  yunxiao workitem content <workitemUrl> [--dir directory] [--download-attachments]
-  yunxiao workitem images <workitemId> [--dir directory]
-  yunxiao workitem attachments <workitemId> [--dir directory]
-  yunxiao workitem update <workitemId> --yes [--assigned-to userId] [--participants user1,user2] [--due-date "2026-05-01 18:00:00"] [--field key=value]
-  yunxiao workitem activities <workitemId> [--output table|json]
-  yunxiao workitem comments <workitemId> [--output table|json]
-  yunxiao workitem comment <workitemId> --content "comment" --yes [--output table|json]
-  yunxiao workitem timeline <workitemId> [--output table|json]
-
-Output:
-  --output table             Plain text table output, default
-  --output json              Pretty JSON output
-  --json                     Alias for --output json
-
-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
-  YUNXIAO_PROJECT_IDS        Default comma-separated project IDs for workitem commands
-  YUNXIAO_WORKITEM_CATEGORIES Default workitem categories, default Req,Task,Bug
-`;
-}