@coderpp/yunxiao-cli 0.1.11 → 0.2.0

package/dist/src/mr.js

@@ -0,0 +1,202 @@
+import { CliError } from "./errors.js";
+export function record(v) {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw new CliError("INVALID_RESPONSE", "Expected API object.", 1);
+    return v;
+}
+export function records(v) {
+    if (!Array.isArray(v))
+        throw new CliError("INVALID_RESPONSE", "Expected API array.", 1);
+    return v.map(record);
+}
+export function required(f, key) {
+    if (typeof f[key] !== "string" || !String(f[key]).trim())
+        throw new CliError("INVALID_ARGUMENT", `--${key} is required.`);
+    return String(f[key]);
+}
+export function confirmed(f) {
+    if (f.yes !== true)
+        throw new CliError("CONFIRMATION_REQUIRED", "This command changes state. Re-run with --yes after reviewing the operation.", 2);
+}
+export function latestPatch(patches, type) {
+    const list = patches
+        .filter((p) => p.relatedMergeItemType === type)
+        .sort((a, b) => Number(b.versionNo) - Number(a.versionNo));
+    if (!list.length)
+        throw new CliError("PATCH_NOT_FOUND", `No ${type} patch found; specify patch IDs.`, 5);
+    return list[0];
+}
+export async function patchPair(client, repo, id, f) {
+    const patches = records(await client.listChangeRequestPatchSets(repo, id));
+    function select(key, type) {
+        const p = f[key] === undefined
+            ? latestPatch(patches, type)
+            : patches.find((p) => p.patchSetBizId === f[key]);
+        if (!p ||
+            typeof p.patchSetBizId !== "string" ||
+            typeof p.commitId !== "string")
+            throw new CliError("PATCH_NOT_FOUND", `Invalid ${key} for this MR.`, 5);
+        return p;
+    }
+    return {
+        from: select("from-patch-set-id", "MERGE_TARGET"),
+        to: select("to-patch-set-id", "MERGE_SOURCE"),
+    };
+}
+export async function mrDiff(client, repo, id, f) {
+    const pair = await patchPair(client, repo, id, f);
+    const tree = record(await client.getChangeRequestTree(repo, id, {
+        fromPatchSetId: String(pair.from.patchSetBizId),
+        toPatchSetId: String(pair.to.patchSetBizId),
+    }));
+    const items = records(tree.changedTreeItems);
+    const comparison = record(await client.compare(repo, String(pair.from.commitId), String(pair.to.commitId), pair.from.relatedMergeItemType === "MERGE_SOURCE"));
+    const diffs = records(comparison.diffs);
+    const files = items.map((item) => {
+        const d = diffs.find((d) => d.newPath === item.newPath && d.oldPath === item.oldPath);
+        const text = typeof d?.diff === "string" ? d.diff : "";
+        let inHunk = false, added = 0, deleted = 0;
+        for (const line of text.split("\n")) {
+            if (line.startsWith("@@ ")) {
+                inHunk = true;
+                continue;
+            }
+            if (inHunk && line.startsWith("+"))
+                added++;
+            if (inHunk && line.startsWith("-"))
+                deleted++;
+        }
+        const binary = item.isBinary === true || d?.isBinary === true;
+        const matches = d &&
+            (!item.newObjectId || item.newObjectId === d.newId) &&
+            (!item.oldObjectId || item.oldObjectId === d.oldId);
+        const complete = !binary &&
+            !!matches &&
+            d?.truncated !== true &&
+            d?.tooLarge !== true &&
+            Number(item.addLines) === added &&
+            Number(item.delLines) === deleted;
+        return {
+            ...item,
+            diff: text,
+            complete,
+            reason: binary
+                ? "binary"
+                : complete
+                    ? undefined
+                    : "missing, truncated, or inconsistent comparison",
+        };
+    });
+    if (f.file &&
+        !files.some((x) => x.newPath === f.file || x.oldPath === f.file))
+        throw new CliError("FILE_NOT_FOUND", "File is not in this MR diff.", 4);
+    const selected = f.file
+        ? files.filter((x) => x.newPath === f.file || x.oldPath === f.file)
+        : files;
+    return {
+        fromPatchSetId: pair.from.patchSetBizId,
+        toPatchSetId: pair.to.patchSetBizId,
+        fromCommit: pair.from.commitId,
+        toCommit: pair.to.commitId,
+        complete: Number(tree.count) === items.length && selected.every((f) => f.complete),
+        files: selected,
+    };
+}
+export async function runExtendedMr(command, p, f, c) {
+    const repo = p[2];
+    const id = Number(p[3]);
+    if (command === "create") {
+        confirmed(f);
+        const source = required(f, "source"), target = required(f, "target"), title = required(f, "title");
+        const targetRepo = record(await c.getRepository(repo));
+        const sourceRepo = f["source-project-id"]
+            ? record(await c.getRepository(String(f["source-project-id"])))
+            : targetRepo;
+        if (targetRepo.id === undefined || sourceRepo.id === undefined)
+            throw new CliError("INVALID_RESPONSE", "Repository ID missing.", 1);
+        return c.createChangeRequest(repo, {
+            sourceBranch: source,
+            targetBranch: target,
+            title,
+            description: f.description,
+            sourceProjectId: String(sourceRepo.id),
+            targetProjectId: String(targetRepo.id),
+            reviewerUserIds: f.reviewers
+                ? String(f.reviewers).split(",").filter(Boolean)
+                : undefined,
+        });
+    }
+    if (!Number.isSafeInteger(id) || id < 1)
+        throw new CliError("INVALID_ARGUMENT", "MR ID must be a positive integer.");
+    if (command === "get")
+        return c.getChangeRequest(repo, id);
+    if (command === "diff")
+        return mrDiff(c, repo, id, f);
+    if (command === "comments")
+        return c.listChangeRequestComments(repo, id, {
+            file_path: f.file,
+            comment_type: f["comment-type"],
+            resolved: f.resolved,
+            patchset_biz_id_list: f["patch-set-ids"]
+                ? String(f["patch-set-ids"]).split(",")
+                : undefined,
+        });
+    if (command === "update") {
+        confirmed(f);
+        const body = { title: f.title, description: f.description };
+        if (body.title === undefined && body.description === undefined)
+            throw new CliError("INVALID_ARGUMENT", "Provide --title or --description.");
+        return c.updateChangeRequest(repo, id, body);
+    }
+    if (command === "close") {
+        confirmed(f);
+        return c.closeChangeRequest(repo, id);
+    }
+    if (command === "comment") {
+        confirmed(f);
+        const content = required(f, "content");
+        if (content.length > 65535)
+            throw new CliError("INVALID_ARGUMENT", "Comment exceeds 65535 characters.");
+        const inline = f.file !== undefined;
+        if (!inline &&
+            ["line", "side", "from-patch-set-id"].some((k) => f[k] !== undefined))
+            throw new CliError("INVALID_ARGUMENT", "Line comment options require --file.");
+        const body = {
+            comment_type: inline ? "INLINE_COMMENT" : "GLOBAL_COMMENT",
+            content,
+            draft: false,
+            resolved: false,
+            parent_comment_biz_id: f["parent-id"],
+        };
+        if (inline) {
+            required(f, "line");
+            required(f, "side");
+            required(f, "to-patch-set-id");
+            const pair = await patchPair(c, repo, id, f);
+            const tree = record(await c.getChangeRequestTree(repo, id, {
+                fromPatchSetId: String(pair.from.patchSetBizId),
+                toPatchSetId: String(pair.to.patchSetBizId),
+            }));
+            if (!records(tree.changedTreeItems).some((item) => item[f.side === "old" ? "oldPath" : "newPath"] === f.file))
+                throw new CliError("FILE_NOT_FOUND", "File is not present on the selected side of the MR diff.", 4);
+            Object.assign(body, {
+                file_path: f.file,
+                line_number: Number(f.line),
+                from_patchset_biz_id: pair.from.patchSetBizId,
+                to_patchset_biz_id: pair.to.patchSetBizId,
+                patchset_biz_id: f.side === "old" ? pair.from.patchSetBizId : pair.to.patchSetBizId,
+            });
+        }
+        else {
+            const patches = records(await c.listChangeRequestPatchSets(repo, id));
+            const patch = f["to-patch-set-id"]
+                ? patches.find((p) => p.patchSetBizId === f["to-patch-set-id"])
+                : latestPatch(patches, "MERGE_SOURCE");
+            if (!patch?.patchSetBizId)
+                throw new CliError("PATCH_NOT_FOUND", "Comment patch not found.", 5);
+            body.patchset_biz_id = patch.patchSetBizId;
+        }
+        return c.createChangeRequestComment(repo, id, body);
+    }
+    throw new CliError("INVALID_ARGUMENT", `Unknown MR command: ${command}`);
+}

package/dist/src/pagination.d.ts

@@ -0,0 +1,10 @@
+export declare const pageMetadata: WeakMap<object, {
+    next?: number | null;
+    perPage?: number;
+}>;
+export declare function paginate(fetchPage: (page: number, perPage: number) => Promise<unknown>, options?: {
+    page?: number;
+    perPage?: number;
+    allPages?: boolean;
+    warn?: (s: string) => void;
+}): Promise<unknown[]>;

package/dist/src/pagination.js

@@ -0,0 +1,35 @@
+import { CliError } from "./errors.js";
+export const pageMetadata = new WeakMap();
+export async function paginate(fetchPage, options = {}) {
+    const result = [];
+    const seen = new Set();
+    const perPage = options.perPage ?? 20;
+    let page = options.page ?? 1;
+    for (let count = 0; count < 10000; count++) {
+        const response = await fetchPage(page, perPage);
+        if (!Array.isArray(response))
+            throw new CliError("INVALID_RESPONSE", "Expected a paginated array response.", 1);
+        const fingerprint = JSON.stringify(response);
+        if (response.length && seen.has(fingerprint))
+            throw new CliError("REPEATED_PAGE", `Server repeated page ${page}; full results unavailable.`, 6);
+        seen.add(fingerprint);
+        result.push(...response);
+        const meta = pageMetadata.get(response);
+        const next = meta?.next !== undefined
+            ? meta.next
+            : response.length >= (meta?.perPage ?? perPage)
+                ? page + 1
+                : null;
+        if (!options.allPages) {
+            if (next)
+                options.warn?.("More results may exist; use --all-pages for complete results.\n");
+            return result;
+        }
+        if (!next)
+            return result;
+        if (next <= page)
+            throw new CliError("INVALID_PAGE", "Server returned a non-advancing page.", 6);
+        page = next;
+    }
+    throw new CliError("PAGE_LIMIT", "Pagination exceeded 10000 pages; results are incomplete.", 6);
+}

package/dist/src/pipeline.d.ts

@@ -0,0 +1,3 @@
+import type { YunxiaoClient } from "./client.js";
+import type { Flags } from "./arguments.js";
+export declare function runExtendedPipeline(command: string, p: string[], f: Flags, c: YunxiaoClient): Promise<unknown>;

package/dist/src/pipeline.js

@@ -0,0 +1,50 @@
+import { confirmed, record, records } from "./mr.js";
+import { CliError } from "./errors.js";
+export async function runExtendedPipeline(command, p, f, c) {
+    const [, , pipelineId, runId, jobId] = p;
+    if (command === "logs")
+        return c.getPipelineJobLog(pipelineId, runId, jobId);
+    if (command === "jobs") {
+        const run = record(await c.getPipelineRun(pipelineId, runId));
+        return records(run.stages ?? []).flatMap((stage) => {
+            const info = record(stage.stageInfo ?? stage);
+            return records(info.jobs ?? []).map((job) => ({
+                ...job,
+                stageId: stage.id,
+                stageName: stage.name ?? info.name,
+            }));
+        });
+    }
+    if (command === "start") {
+        confirmed(f);
+        let params;
+        if (f.params !== undefined) {
+            try {
+                params = record(JSON.parse(String(f.params)));
+            }
+            catch {
+                throw new CliError("INVALID_ARGUMENT", "--params must be a JSON object.");
+            }
+        }
+        return {
+            pipelineId,
+            pipelineRunId: await c.startPipeline(pipelineId, params),
+        };
+    }
+    if (command === "cancel") {
+        confirmed(f);
+        const accepted = await c.cancelPipeline(pipelineId, runId);
+        try {
+            return {
+                pipelineId,
+                pipelineRunId: runId,
+                accepted,
+                run: await c.getPipelineRun(pipelineId, runId),
+            };
+        }
+        catch {
+            throw new CliError("PARTIAL_OPERATION", "Cancel accepted, but reading the final state failed.", 7, { pipelineId, pipelineRunId: runId, accepted });
+        }
+    }
+    throw new CliError("INVALID_ARGUMENT", `Unknown pipeline command: ${command}`);
+}

package/dist/src/release.d.ts

@@ -0,0 +1,2 @@
+import type { YunxiaoClient, ReleaseByRepositoryNameOptions, ReleaseResult } from "./client.js";
+export declare function release(c: YunxiaoClient, o: ReleaseByRepositoryNameOptions): Promise<ReleaseResult>;

package/dist/src/release.js

@@ -0,0 +1,203 @@
+import { YunxiaoApiError } from "./transport.js";
+import { CliError, errorInfo } from "./errors.js";
+import { paginate } from "./pagination.js";
+import { record, records, latestPatch } from "./mr.js";
+export async function release(c, o) {
+    const repositories = records(await paginate((page, perPage) => c.listRepositories({
+        page,
+        perPage,
+        search: o.repositoryName,
+        archived: false,
+    }), { allPages: true }));
+    const normalize = (s) => String(s ?? "")
+        .replace(/\s*\/\s*/g, "/")
+        .toLowerCase();
+    const matches = repositories.filter((r) => [r.name, r.path, r.nameWithNamespace, r.pathWithNamespace].some((v) => v && normalize(v) === normalize(o.repositoryName)));
+    if (matches.length !== 1)
+        throw new CliError(matches.length ? "AMBIGUOUS_REPOSITORY" : "NOT_FOUND", matches.length
+            ? "Multiple repositories match; use the full namespace path."
+            : `Repository not found by name: ${o.repositoryName}`, matches.length ? 5 : 4);
+    const repository = matches[0];
+    const repo = String(repository.id);
+    const matching = async () => records(await paginate((page, perPage) => c.listChangeRequests({
+        page,
+        perPage,
+        projectIds: repo,
+        state: "opened",
+    }), { allPages: true })).filter((m) => m.sourceBranch === o.sourceBranch &&
+        m.targetBranch === o.targetBranch &&
+        String(m.sourceProjectId) === repo &&
+        String(m.targetProjectId ?? m.projectId) === repo);
+    let mr;
+    let review = null;
+    let merge = null;
+    let stage = "lookup";
+    const completed = [];
+    const recovery = () => ({
+        repository,
+        changeRequest: mr,
+        completed,
+        failedStage: stage,
+        localId: mr?.localId,
+        url: mr?.detailUrl ?? mr?.webUrl,
+        resumeArgs: mr && Number.isSafeInteger(Number(mr.localId)) && Number(mr.localId) > 0
+            ? [
+                "mr",
+                "release",
+                o.repositoryName,
+                o.sourceBranch,
+                o.targetBranch,
+                "--resume",
+                String(mr.localId),
+                "--yes",
+                ...(o.createOnly ? ["--create-only"] : []),
+                ...(o.mergeType ? ["--merge-type", o.mergeType] : []),
+            ]
+            : undefined,
+    });
+    try {
+        if (o.resume) {
+            mr = record(await c.getChangeRequest(repo, o.resume));
+            if (mr.sourceBranch !== o.sourceBranch ||
+                mr.targetBranch !== o.targetBranch ||
+                String(mr.sourceProjectId) !== repo ||
+                String(mr.targetProjectId) !== repo)
+                throw new CliError("RESUME_MISMATCH", "MR does not match the requested repositories and branches.", 5);
+            if (String(mr.status ?? mr.state).toUpperCase() === "MERGED")
+                return {
+                    repository,
+                    changeRequest: mr,
+                    review,
+                    merge,
+                    status: "already-merged",
+                };
+            if (String(mr.status ?? mr.state).toUpperCase() === "CLOSED")
+                throw new CliError("MR_CLOSED", "Cannot resume a closed MR.", 5);
+        }
+        else {
+            const existing = await matching();
+            if (existing.length) {
+                mr = existing.length === 1 ? existing[0] : undefined;
+                throw new CliError("EXISTING_MR", "Matching open MR exists; explicitly select --resume <mrId>.", 5, { ...recovery(), matches: existing });
+            }
+            stage = "create";
+            const user = await c.getCurrentUser();
+            try {
+                const created = await c.createChangeRequest(repo, {
+                    sourceBranch: o.sourceBranch,
+                    targetBranch: o.targetBranch,
+                    sourceProjectId: repo,
+                    targetProjectId: repo,
+                    title: o.title ?? `Release ${o.sourceBranch} into ${o.targetBranch}`,
+                    description: o.description,
+                    reviewerUserIds: [user.id],
+                });
+                if (!created ||
+                    typeof created !== "object" ||
+                    Array.isArray(created) ||
+                    !Number.isSafeInteger(Number(created.localId)) ||
+                    Number(created.localId) < 1) {
+                    throw new CliError("WRITE_RESULT_UNKNOWN", "Create response did not identify the MR; verify server state before retrying.", 7);
+                }
+                mr = created;
+            }
+            catch (e) {
+                // Validation errors other than this exact no-change condition must remain failures.
+                if (e instanceof YunxiaoApiError &&
+                    /源分支相对目标分支没有改动，不能新建代码评审/.test(e.responseBody))
+                    return {
+                        repository,
+                        changeRequest: null,
+                        review,
+                        merge,
+                        status: "skipped",
+                    };
+                if (e instanceof CliError && e.exitCode === 7) {
+                    try {
+                        const found = await matching();
+                        if (found.length === 1)
+                            mr = found[0];
+                    }
+                    catch { }
+                    throw new CliError("WRITE_RESULT_UNKNOWN", "Create result was uncertain; inspect the matching MR before resuming.", 7, recovery());
+                }
+                throw e;
+            }
+            completed.push("create");
+        }
+        if (!Number.isSafeInteger(Number(mr.localId)) || Number(mr.localId) < 1)
+            throw new CliError("INVALID_RESPONSE", "Created MR response has no valid localId.", 7);
+        const id = Number(mr.localId);
+        if (o.createOnly)
+            return {
+                repository,
+                changeRequest: mr,
+                review,
+                merge,
+                status: "created",
+            };
+        stage = "review";
+        const before = latestPatch(records(await c.listChangeRequestPatchSets(repo, id)), "MERGE_SOURCE");
+        let alreadyReviewed = false;
+        if (o.resume) {
+            const user = await c.getCurrentUser();
+            const current = record(await c.getChangeRequest(repo, id));
+            const created = Date.parse(String(before.createTime));
+            alreadyReviewed =
+                Number.isFinite(created) &&
+                    records(current.reviewers ?? []).some((r) => r.userId === user.id &&
+                        r.reviewOpinionStatus === "PASS" &&
+                        Date.parse(String(r.reviewTime)) >= created);
+        }
+        if (!alreadyReviewed)
+            review = await c.reviewChangeRequest(repo, id, {
+                reviewComment: "Approved by yunxiao-cli release workflow",
+            });
+        completed.push("review");
+        const after = latestPatch(records(await c.listChangeRequestPatchSets(repo, id)), "MERGE_SOURCE");
+        if (!before.patchSetBizId ||
+            !before.commitId ||
+            before.patchSetBizId !== after.patchSetBizId ||
+            before.commitId !== after.commitId)
+            throw new CliError("VERSION_CHANGED", "Source version changed during review; inspect and resume.", 5);
+        stage = "merge";
+        try {
+            merge = await c.mergeChangeRequest(repo, id, {
+                mergeType: o.mergeType,
+                removeSourceBranch: false,
+            });
+        }
+        catch (e) {
+            if (e instanceof CliError && e.exitCode === 7) {
+                try {
+                    const current = record(await c.getChangeRequest(repo, id));
+                    if (String(current.status ?? current.state).toUpperCase() === "MERGED")
+                        return {
+                            repository,
+                            changeRequest: current,
+                            review,
+                            merge: null,
+                            status: "merged",
+                        };
+                }
+                catch { }
+            }
+            throw e;
+        }
+        completed.push("merge");
+        return { repository, changeRequest: mr, review, merge, status: "merged" };
+    }
+    catch (e) {
+        if (e instanceof CliError &&
+            ["EXISTING_MR", "RESUME_MISMATCH", "MR_CLOSED"].includes(e.code))
+            throw e;
+        if (e instanceof CliError && e.code === "WRITE_RESULT_UNKNOWN")
+            throw new CliError(e.code, e.message, 7, {
+                ...recovery(),
+                cause: e.details,
+            });
+        if (mr || completed.length)
+            throw new CliError("PARTIAL_OPERATION", errorInfo(e).message, 7, recovery());
+        throw e;
+    }
+}

package/dist/src/transport.d.ts

@@ -0,0 +1,16 @@
+import type { Fetcher } from "./client.js";
+export declare class YunxiaoApiError extends Error {
+    readonly status: number;
+    readonly responseBody: string;
+    readonly method: string;
+    readonly url: string;
+    readonly requestId?: string | undefined;
+    readonly apiCode?: string;
+    constructor(message: string, status: number, responseBody: string, method: string, url: string, requestId?: string | undefined);
+}
+export declare function requestJson(fetcher: Fetcher, url: URL, init: RequestInit, options: {
+    timeoutMs: number;
+    retries: number;
+    token: string;
+    readOnly: boolean;
+}): Promise<unknown>;

package/dist/src/transport.js

@@ -0,0 +1,119 @@
+import { CliError, redact } from "./errors.js";
+import { pageMetadata } from "./pagination.js";
+export class YunxiaoApiError extends Error {
+    status;
+    responseBody;
+    method;
+    url;
+    requestId;
+    apiCode;
+    constructor(message, status, responseBody, method, url, requestId) {
+        super(message);
+        this.status = status;
+        this.responseBody = responseBody;
+        this.method = method;
+        this.url = url;
+        this.requestId = requestId;
+        this.name = "YunxiaoApiError";
+        try {
+            const body = JSON.parse(responseBody);
+            this.apiCode = body.code ?? body.errorCode;
+        }
+        catch { }
+    }
+}
+export async function requestJson(fetcher, url, init, options) {
+    const method = init.method ?? "GET";
+    for (let attempt = 0;; attempt++) {
+        const controller = new AbortController();
+        let timer;
+        let retryAfter = 0;
+        try {
+            const operation = (async () => {
+                const response = await fetcher(url.toString(), {
+                    ...init,
+                    signal: controller.signal,
+                    redirect: "error",
+                });
+                const body = await response.text();
+                const raw = response.headers.get("retry-after");
+                if (raw)
+                    retryAfter = /^\d+(\.\d+)?$/.test(raw)
+                        ? Number(raw) * 1000
+                        : Math.max(0, Date.parse(raw) - Date.now());
+                if (!Number.isFinite(retryAfter))
+                    retryAfter = 0;
+                if (!response.ok) {
+                    const safe = redact(body, [options.token]);
+                    throw new YunxiaoApiError(`Yunxiao API request failed with HTTP ${response.status}: ${method} ${url.origin}${url.pathname}${safe ? "\n" + safe : ""}`, response.status, safe, method, url.origin + url.pathname, response.headers.get("x-request-id") ?? undefined);
+                }
+                if (!body)
+                    return null;
+                let value;
+                try {
+                    value = JSON.parse(body);
+                }
+                catch {
+                    throw new CliError("INVALID_RESPONSE", "API returned invalid JSON.", options.readOnly ? 1 : 7);
+                }
+                if (value === false ||
+                    (value &&
+                        typeof value === "object" &&
+                        !Array.isArray(value) &&
+                        (value.success === false ||
+                            value.result === false)))
+                    throw new CliError("API_REJECTED", "API reported an unsuccessful operation.", 5);
+                if (Array.isArray(value)) {
+                    const next = response.headers.get("x-next-page");
+                    const per = response.headers.get("x-per-page");
+                    if (next !== null &&
+                        next !== "" &&
+                        (!/^\d+$/.test(next) || Number(next) < 1))
+                        throw new CliError("INVALID_RESPONSE", "Invalid pagination response header.", 1);
+                    pageMetadata.set(value, {
+                        next: next === null ? undefined : next === "" ? null : Number(next),
+                        perPage: per && Number(per) > 0 ? Number(per) : undefined,
+                    });
+                }
+                return value;
+            })();
+            return await Promise.race([
+                operation,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => {
+                        controller.abort();
+                        reject(new CliError(options.readOnly ? "TIMEOUT" : "WRITE_RESULT_UNKNOWN", "Request timed out; " +
+                            (options.readOnly
+                                ? "read can be retried."
+                                : "verify server state before retrying."), options.readOnly ? 6 : 7));
+                    }, options.timeoutMs);
+                }),
+            ]);
+        }
+        catch (error) {
+            const transient = error instanceof YunxiaoApiError
+                ? [429, 502, 503, 504].includes(error.status)
+                : !(error instanceof CliError) || error.code === "TIMEOUT";
+            if (!options.readOnly &&
+                error instanceof YunxiaoApiError &&
+                error.status >= 500)
+                throw new CliError("WRITE_RESULT_UNKNOWN", "Server error during write; verify server state before retrying.", 7, { requestId: error.requestId, status: error.status });
+            if (!options.readOnly &&
+                !(error instanceof YunxiaoApiError) &&
+                !(error instanceof CliError))
+                throw new CliError("WRITE_RESULT_UNKNOWN", "Network error; verify server state before retrying this write.", 7);
+            if (!options.readOnly || !transient || attempt >= options.retries) {
+                if (!(error instanceof YunxiaoApiError) && !(error instanceof CliError))
+                    throw new CliError("NETWORK_ERROR", "Network request failed.", 6);
+                throw error;
+            }
+            if (retryAfter > 60000)
+                throw new CliError("RATE_LIMITED", "Server requests a retry delay longer than 60 seconds; retry later.", 6);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.max(retryAfter, Math.min(500 * 2 ** attempt, 5000) + Math.random() * 100)));
+    }
+}

package/dist/src/workitem-content.d.ts

@@ -9,6 +9,7 @@ export type ContentOptions = {
     dir: string;
     downloadAttachments?: boolean;
     fetcher?: Fetcher;
+    timeoutMs?: number;
 };
 export declare function parseWorkitemUrl(link: string): {
     projectId: string;