@knowttl/ado-axi 0.0.0-stage → 0.4.8

package/dist/commands/workItem.js

@@ -0,0 +1,940 @@
+import { AxiError } from "axi-sdk-js";
+import { assertKnownFlags, flagNumber, flagString, flagBool, flagList, parseArgs } from "../lib/args.js";
+import { request, requestList } from "../lib/client.js";
+import { requireProject } from "../lib/config.js";
+import { profileFromArgs } from "../lib/context.js";
+import { countLine, htmlToText, personName, pickFields, shortDate, truncate } from "../lib/format.js";
+import { readStdinIfPiped } from "../lib/stdin.js";
+import { workItemAttachment } from "./workItemAttachment.js";
+const LIST_FLAGS = ["state", "type", "assigned-to", "iteration", "area", "tag", "search", "query", "limit"];
+const GET_FLAGS = ["comments", "relations"];
+const CREATE_FLAGS = ["type", "title", "description", "description-format", "assigned-to", "area", "iteration", "parent", "tags", "set"];
+const UPDATE_FLAGS = [
+    "title",
+    "state",
+    "assigned-to",
+    "area",
+    "iteration",
+    "description",
+    "description-format",
+    "tags",
+    "add-tags",
+    "remove-tags",
+    "set",
+    "reason",
+    "if-rev",
+];
+const COMMENT_FLAGS = ["body", "format"];
+const DELETE_FLAGS = ["if-rev", "destroy", "confirm-destroy"];
+const LINK_LIST_FLAGS = ["limit"];
+const LINK_ADD_FLAGS = ["parent", "child", "related", "pr", "commit", "branch", "repo", "comment", "if-rev"];
+const LINK_REMOVE_FLAGS = ["index", "if-rev"];
+const HIERARCHY = {
+    parent: "System.LinkTypes.Hierarchy-Reverse",
+    child: "System.LinkTypes.Hierarchy-Forward",
+    related: "System.LinkTypes.Related",
+};
+const RELATION_LABELS = {
+    "System.LinkTypes.Hierarchy-Reverse": "parent",
+    "System.LinkTypes.Hierarchy-Forward": "child",
+    "System.LinkTypes.Related": "related",
+    "System.LinkTypes.Dependency-Forward": "successor",
+    "System.LinkTypes.Dependency-Reverse": "predecessor",
+    "System.LinkTypes.Duplicate-Forward": "duplicate",
+    "System.LinkTypes.Duplicate-Reverse": "duplicate-of",
+    AttachedFile: "attachment",
+    Hyperlink: "hyperlink",
+};
+const DEFAULT_COLUMNS = ["id", "type", "title", "state", "assignee", "changed"];
+const FIELD_ALIASES = {
+    id: "System.Id",
+    type: "System.WorkItemType",
+    title: "System.Title",
+    state: "System.State",
+    assignee: "System.AssignedTo",
+    created: "System.CreatedDate",
+    changed: "System.ChangedDate",
+};
+const CLOSED_STATES = ["Closed", "Removed", "Done", "Resolved"];
+export async function workItemCommand(argv) {
+    const args = parseArgs(argv);
+    const sub = args.positionals[0] ?? "list";
+    const rest = { ...args, positionals: args.positionals.slice(1) };
+    switch (sub) {
+        case "attach":
+        case "attachment":
+            return workItemAttachment(sub, rest);
+        case "list":
+            return listWorkItems(rest);
+        case "get":
+        case "view":
+            return getWorkItem(rest);
+        case "create":
+            return createWorkItem(rest);
+        case "update":
+            return updateWorkItem(rest);
+        case "delete":
+            return deleteWorkItem(rest);
+        case "comment":
+            return commentWorkItem(rest);
+        case "link":
+        case "links":
+            return linkWorkItem(rest);
+        default:
+            throw new AxiError(`unknown subcommand \`work-item ${sub}\``, "VALIDATION_ERROR", [
+                "Subcommands: list | get | create | update | delete | comment | link | attach | attachment",
+                "Run `ado-axi work-item --help` for the full reference",
+            ]);
+    }
+}
+function escapeWiql(value) {
+    return value.replace(/'/g, "''");
+}
+function buildWiql(args, project) {
+    const raw = flagString(args, "query");
+    if (raw)
+        return raw;
+    const where = [`[System.TeamProject] = '${escapeWiql(project)}'`];
+    const state = flagString(args, "state") ?? "open";
+    if (state === "open") {
+        where.push(`[System.State] NOT IN (${CLOSED_STATES.map((s) => `'${s}'`).join(", ")})`);
+    }
+    else if (state !== "all") {
+        where.push(`[System.State] = '${escapeWiql(state)}'`);
+    }
+    const type = flagString(args, "type");
+    if (type)
+        where.push(`[System.WorkItemType] = '${escapeWiql(type)}'`);
+    const assignee = flagString(args, "assigned-to");
+    if (assignee) {
+        where.push(assignee === "@me"
+            ? "[System.AssignedTo] = @me"
+            : `[System.AssignedTo] CONTAINS '${escapeWiql(assignee)}'`);
+    }
+    const iteration = flagString(args, "iteration");
+    if (iteration) {
+        where.push(iteration === "@current"
+            ? "[System.IterationPath] = @currentIteration"
+            : `[System.IterationPath] UNDER '${escapeWiql(iteration)}'`);
+    }
+    const area = flagString(args, "area");
+    if (area)
+        where.push(`[System.AreaPath] UNDER '${escapeWiql(area)}'`);
+    const tag = flagString(args, "tag");
+    if (tag)
+        where.push(`[System.Tags] CONTAINS '${escapeWiql(tag)}'`);
+    const search = flagString(args, "search");
+    if (search)
+        where.push(`[System.Title] CONTAINS '${escapeWiql(search)}'`);
+    return `SELECT [System.Id] FROM WorkItems WHERE ${where.join(" AND ")} ORDER BY [System.ChangedDate] DESC`;
+}
+async function fetchWorkItems(profile, ids, fields, getOnly = false, asOf) {
+    const out = [];
+    for (let i = 0; i < ids.length; i += 200) {
+        const chunk = ids.slice(i, i + 200);
+        const result = await request(profile, {
+            method: getOnly ? "GET" : "POST",
+            path: getOnly ? "_apis/wit/workitems" : "_apis/wit/workitemsbatch",
+            ...(getOnly ? { query: { ids: chunk.join(","), fields: fields.join(","), asOf } }
+                : { body: { ids: chunk, fields, asOf } }),
+        });
+        out.push(...(result.value ?? []));
+    }
+    return out;
+}
+export async function listWorkItems(args, savedQuery) {
+    assertKnownFlags(args, savedQuery ? ["limit"] : LIST_FLAGS, savedQuery ? "query run" : "work-item list");
+    const columns = flagList(args, "fields");
+    const selected = columns?.length ? columns : DEFAULT_COLUMNS;
+    const requestedFields = selected.map((name) => {
+        const reference = Object.hasOwn(FIELD_ALIASES, name) ? FIELD_ALIASES[name] : undefined;
+        if (reference)
+            return reference;
+        if (name.includes("."))
+            return name;
+        throw new AxiError(`unknown field '${name}' in --fields`, "VALIDATION_ERROR", [
+            `Use aliases: ${Object.keys(FIELD_ALIASES).join(", ")}, or a field reference name such as Custom.EventSeverity`,
+        ]);
+    });
+    const profile = profileFromArgs(args);
+    const project = requireProject(profile, "work-item list");
+    const limit = flagNumber(args, "limit") ?? 30;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new AxiError("--limit must be a positive integer", "VALIDATION_ERROR");
+    }
+    const wiql = buildWiql(args, project);
+    const result = await request(profile, {
+        method: savedQuery ? "GET" : "POST",
+        path: savedQuery ? `_apis/wit/wiql/${encodeURIComponent(savedQuery)}` : "_apis/wit/wiql",
+        project,
+        query: { $top: limit },
+        ...(savedQuery ? {} : { body: { query: wiql } }),
+    });
+    const ids = result.workItems?.map((w) => w.id) ?? [...new Set((result.workItemRelations ?? []).flatMap((r) => [r.source?.id, r.target?.id])
+            .filter((id) => id !== undefined))];
+    if (ids.length === 0) {
+        return {
+            "work-items": `0 work items found in ${project} (${savedQuery ? "saved query" : describeFilter(args)})`,
+            help: [
+                "Run `ado-axi work-item list --state all` to include closed items",
+                'Run `ado-axi work-item list --query "SELECT [System.Id] FROM WorkItems WHERE ..."` for a raw WIQL query',
+                'Run `ado-axi work-item create --type Task --title "<title>"` to add one',
+            ],
+        };
+    }
+    const page = ids.slice(0, limit);
+    const items = await fetchWorkItems(profile, page, [...new Set(requestedFields)], savedQuery !== undefined, result.asOf);
+    const rows = items.map((item) => Object.fromEntries(selected.map((column, index) => {
+        const reference = requestedFields[index];
+        const value = reference === "System.Id" ? item.id : item.fields?.[reference];
+        if (column === "created" || column === "changed") {
+            return [column, shortDate(value)];
+        }
+        return [column, value && typeof value === "object" ? personName(value) : value ?? ""];
+    })));
+    const help = [`Run \`ado-axi work-item get <id>\` for full detail`];
+    help.push('Run `ado-axi work-item update <id> --state <state>` to change state');
+    return {
+        project,
+        org: profile.org,
+        count: `${rows.length} work items shown`,
+        "work-items": rows,
+        help,
+    };
+}
+function describeFilter(args) {
+    const parts = [];
+    const state = flagString(args, "state") ?? "open";
+    parts.push(`state=${state}`);
+    for (const key of ["type", "assigned-to", "iteration", "area", "tag", "search"]) {
+        const value = flagString(args, key);
+        if (value)
+            parts.push(`${key}=${value}`);
+    }
+    return parts.join(", ");
+}
+async function getWorkItem(args) {
+    assertKnownFlags(args, GET_FLAGS, "work-item get");
+    const profile = profileFromArgs(args);
+    const id = requireId(args, "work-item get <id>");
+    const item = await request(profile, {
+        path: `_apis/wit/workitems/${id}`,
+        query: { $expand: "all" },
+    });
+    const fields = item.fields ?? {};
+    const description = htmlToText(String(fields["System.Description"] ?? fields["Microsoft.VSTS.TCM.ReproSteps"] ?? ""));
+    const body = truncate(description, flagBool(args, "full") ? Number.MAX_SAFE_INTEGER : 1200);
+    const relations = (item.relations ?? []).filter((r) => r.rel?.startsWith("System.LinkTypes") || r.rel === "ArtifactLink");
+    const parent = (item.relations ?? []).find((r) => r.rel === "System.LinkTypes.Hierarchy-Reverse");
+    const out = {
+        "work-item": {
+            id: item.id,
+            rev: item.rev ?? "",
+            type: String(fields["System.WorkItemType"] ?? ""),
+            title: String(fields["System.Title"] ?? ""),
+            state: String(fields["System.State"] ?? ""),
+            reason: String(fields["System.Reason"] ?? ""),
+            assignee: personName(fields["System.AssignedTo"]),
+            area: String(fields["System.AreaPath"] ?? ""),
+            iteration: String(fields["System.IterationPath"] ?? ""),
+            tags: String(fields["System.Tags"] ?? ""),
+            created: shortDate(fields["System.CreatedDate"]),
+            changed: shortDate(fields["System.ChangedDate"]),
+            "changed-by": personName(fields["System.ChangedBy"]),
+            comments: Number(fields["System.CommentCount"] ?? 0),
+            links: relations.length,
+            parent: parent ? Number(parent.url?.split("/").pop()) : "",
+            url: item._links?.html?.href ?? "",
+            description: body.text,
+        },
+    };
+    if (flagBool(args, "full")) {
+        out.fields = Object.fromEntries(Object.entries(fields)
+            .filter(([reference]) => !reference.startsWith("System."))
+            .map(([reference, value]) => [reference,
+            typeof value === "string"
+                ? truncate(reference === "Microsoft.VSTS.TCM.ReproSteps" ? htmlToText(value) : value, 1200).text
+                : value,
+        ]));
+    }
+    if (flagBool(args, "relations") && relations.length > 0) {
+        out.links = relations.map((relation) => {
+            const described = describeRelation(relation);
+            return {
+                type: described.type,
+                target: described.target,
+                comment: relation.attributes?.comment ?? "",
+            };
+        });
+    }
+    if (flagBool(args, "comments") && Number(fields["System.CommentCount"] ?? 0) > 0) {
+        const comments = await request(profile, {
+            path: `_apis/wit/workItems/${id}/comments`,
+            project: profile.project,
+            query: { $top: 50 },
+            apiVersion: "7.1-preview.4",
+        });
+        out.comments = (comments.comments ?? []).map((c) => ({
+            id: c.id,
+            author: personName(c.createdBy),
+            date: shortDate(c.createdDate),
+            text: truncate(htmlToText(c.text ?? ""), 400).text,
+        }));
+    }
+    const help = [];
+    if (body.truncated)
+        help.push(`Run \`ado-axi work-item get ${id} --full\` for the complete description`);
+    if (!flagBool(args, "comments") && Number(fields["System.CommentCount"] ?? 0) > 0) {
+        help.push(`Run \`ado-axi work-item get ${id} --comments\` to include ${fields["System.CommentCount"]} comments`);
+    }
+    if (!flagBool(args, "relations") && relations.length > 0) {
+        help.push(`Run \`ado-axi work-item link list ${id}\` to see its ${relations.length} links`);
+    }
+    if (help.length > 0)
+        out.help = help;
+    return out;
+}
+function requireId(args, usage) {
+    const raw = args.positionals[0];
+    const id = Number(raw);
+    if (!raw || !Number.isFinite(id)) {
+        throw new AxiError("a numeric work item id is required", "VALIDATION_ERROR", [
+            `Usage: ado-axi ${usage}`,
+            "Run `ado-axi work-item list` to find ids",
+        ]);
+    }
+    return id;
+}
+function patch(op, path, value) {
+    return { op, path, value };
+}
+function setFlags(args) {
+    const raw = flagString(args, "set");
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new AxiError("--set expects a JSON object of field reference names", "VALIDATION_ERROR", [
+            `Example: --set '{"Microsoft.VSTS.Common.Priority": 1}'`,
+        ]);
+    }
+    return Object.entries(parsed).map(([key, value]) => patch("add", `/fields/${key}`, value));
+}
+function descriptionFormat(args, description) {
+    const value = flagString(args, "description-format");
+    if (value === undefined)
+        return undefined;
+    if (description === undefined) {
+        throw new AxiError("--description-format requires --description or a piped description", "VALIDATION_ERROR");
+    }
+    if (value.toLowerCase() === "markdown")
+        return "Markdown";
+    if (value.toLowerCase() === "html")
+        return "Html";
+    throw new AxiError("--description-format must be markdown or html", "VALIDATION_ERROR", [
+        "Use `--description-format markdown` for Markdown or `--description-format html` for HTML",
+    ]);
+}
+function commentFormat(args) {
+    const raw = args.flags.format;
+    if (raw === undefined)
+        return "markdown";
+    if (typeof raw !== "string") {
+        throw new AxiError("--format must be markdown or html", "VALIDATION_ERROR", [
+            "Use `--format markdown` for Markdown or `--format html` for HTML",
+        ]);
+    }
+    const value = raw.toLowerCase();
+    if (value === "markdown" || value === "html")
+        return value;
+    throw new AxiError("--format must be markdown or html", "VALIDATION_ERROR", [
+        "Use `--format markdown` for Markdown or `--format html` for HTML",
+    ]);
+}
+async function createWorkItem(args) {
+    assertKnownFlags(args, CREATE_FLAGS, "work-item create");
+    const profile = profileFromArgs(args);
+    const project = requireProject(profile, "work-item create");
+    const type = flagString(args, "type");
+    const title = flagString(args, "title");
+    if (!type || !title) {
+        throw new AxiError("--type and --title are required", "VALIDATION_ERROR", [
+            'Usage: ado-axi work-item create --type Task --title "..." [--description "..."] [--assigned-to <user>]',
+        ]);
+    }
+    const ops = [patch("add", "/fields/System.Title", title)];
+    const description = flagString(args, "description") ?? (await readStdinIfPiped())?.toString("utf8");
+    if (description !== undefined) {
+        ops.push(patch("add", "/fields/System.Description", description));
+        const format = descriptionFormat(args, description);
+        if (format)
+            ops.push(patch("add", "/multilineFieldsFormat/System.Description", format));
+    }
+    else {
+        descriptionFormat(args, description);
+    }
+    const assignee = flagString(args, "assigned-to");
+    if (assignee)
+        ops.push(patch("add", "/fields/System.AssignedTo", assignee));
+    const area = flagString(args, "area");
+    if (area)
+        ops.push(patch("add", "/fields/System.AreaPath", area));
+    const iteration = flagString(args, "iteration");
+    if (iteration)
+        ops.push(patch("add", "/fields/System.IterationPath", iteration));
+    const tags = flagString(args, "tags");
+    if (tags)
+        ops.push(patch("add", "/fields/System.Tags", tags));
+    const parent = flagString(args, "parent");
+    if (parent) {
+        ops.push(patch("add", "/relations/-", {
+            rel: "System.LinkTypes.Hierarchy-Reverse",
+            url: `https://dev.azure.com/${profile.org}/_apis/wit/workItems/${parent}`,
+        }));
+    }
+    ops.push(...setFlags(args));
+    const created = await request(profile, {
+        method: "POST",
+        path: `_apis/wit/workitems/$${encodeURIComponent(type)}`,
+        project,
+        body: ops,
+        contentType: "application/json-patch+json",
+    });
+    return {
+        created: {
+            id: created.id,
+            type: String(created.fields?.["System.WorkItemType"] ?? type),
+            title: String(created.fields?.["System.Title"] ?? title),
+            state: String(created.fields?.["System.State"] ?? ""),
+            url: created._links?.html?.href ?? "",
+        },
+        help: [
+            `Run \`ado-axi work-item get ${created.id}\` to view it`,
+            `Run \`ado-axi work-item update ${created.id} --assigned-to <user>\` to assign it`,
+        ],
+    };
+}
+export function parseTags(value) {
+    return String(value ?? "")
+        .split(";")
+        .map((t) => t.trim())
+        .filter(Boolean);
+}
+export function mergeTags(current, add, remove) {
+    const removeSet = new Set(remove.map((t) => t.toLowerCase()));
+    const kept = current.filter((t) => !removeSet.has(t.toLowerCase()));
+    const removed = current.filter((t) => removeSet.has(t.toLowerCase()));
+    const seen = new Set(kept.map((t) => t.toLowerCase()));
+    const added = [];
+    for (const tag of add) {
+        if (seen.has(tag.toLowerCase()))
+            continue;
+        seen.add(tag.toLowerCase());
+        kept.push(tag);
+        added.push(tag);
+    }
+    return { tags: kept, added, removed };
+}
+async function updateWorkItem(args) {
+    assertKnownFlags(args, UPDATE_FLAGS, "work-item update");
+    const profile = profileFromArgs(args);
+    const id = requireId(args, "work-item update <id> --state <state>");
+    const ifRev = flagNumber(args, "if-rev");
+    const current = await request(profile, { path: `_apis/wit/workitems/${id}` });
+    const fields = current.fields ?? {};
+    if (ifRev !== undefined && current.rev !== undefined && current.rev !== ifRev) {
+        throw new AxiError(`#${id} is at rev ${current.rev}, expected ${ifRev} — update refused`, "PRECONDITION_FAILED", [
+            `Someone else changed the work item (last change by ${personName(fields["System.ChangedBy"]) || "unknown"})`,
+            `Run \`ado-axi work-item get ${id}\` to re-read the current rev, then retry with --if-rev ${current.rev}`,
+        ]);
+    }
+    const ops = [];
+    const mapping = [
+        ["title", "System.Title"],
+        ["state", "System.State"],
+        ["assigned-to", "System.AssignedTo"],
+        ["area", "System.AreaPath"],
+        ["iteration", "System.IterationPath"],
+        ["description", "System.Description"],
+        ["tags", "System.Tags"],
+        ["reason", "System.Reason"],
+    ];
+    const unchanged = [];
+    const stdinDescription = flagString(args, "description") === undefined
+        ? (await readStdinIfPiped())?.toString("utf8")
+        : undefined;
+    for (const [flag, field] of mapping) {
+        const value = flag === "description" && stdinDescription !== undefined
+            ? stdinDescription
+            : flagString(args, flag);
+        if (value === undefined)
+            continue;
+        const currentValue = field === "System.AssignedTo" ? personName(fields[field]) : String(fields[field] ?? "");
+        if (currentValue === value && ifRev === undefined) {
+            unchanged.push(flag);
+            continue;
+        }
+        // Azure DevOps merges tags on `add`; only `replace` can drop existing tags.
+        const op = field === "System.Tags" && currentValue !== "" ? "replace" : "add";
+        ops.push(patch(op, `/fields/${field}`, value));
+    }
+    const description = stdinDescription ?? flagString(args, "description");
+    const format = descriptionFormat(args, description);
+    if (format)
+        ops.push(patch("add", "/multilineFieldsFormat/System.Description", format));
+    const addTags = flagList(args, "add-tags") ?? [];
+    const removeTags = flagList(args, "remove-tags") ?? [];
+    let tagChange;
+    if (addTags.length > 0 || removeTags.length > 0) {
+        if (flagString(args, "tags") !== undefined) {
+            throw new AxiError("--tags cannot be combined with --add-tags/--remove-tags", "VALIDATION_ERROR", [
+                "--tags replaces the whole tag string; --add-tags/--remove-tags mutate it in place",
+            ]);
+        }
+        const currentTags = parseTags(fields["System.Tags"]);
+        const merged = mergeTags(currentTags, addTags, removeTags);
+        if (merged.added.length > 0 || merged.removed.length > 0) {
+            ops.push(patch(currentTags.length > 0 ? "replace" : "add", "/fields/System.Tags", merged.tags.join("; ")));
+            tagChange = { added: merged.added, removed: merged.removed };
+        }
+        else {
+            unchanged.push("tags");
+        }
+    }
+    ops.push(...setFlags(args));
+    if (ops.length === 0) {
+        if (unchanged.length > 0) {
+            return {
+                "work-item": `#${id} already has ${unchanged.join(", ")} set to the requested value (no-op)`,
+            };
+        }
+        throw new AxiError("no changes requested", "VALIDATION_ERROR", [
+            `Usage: ado-axi work-item update ${id} --state <state> [--title "..."] [--assigned-to <user>]`,
+            `Fields: ${mapping.map(([f]) => `--${f}`).join(", ")}, --add-tags a,b, --remove-tags c, --set '{"<Field.Ref>": <value>}'`,
+        ]);
+    }
+    const expectedRev = ifRev ?? (tagChange ? current.rev : undefined);
+    if (tagChange && expectedRev === undefined) {
+        throw new AxiError(`#${id} has no revision — tag update refused`, "PRECONDITION_FAILED", [
+            `Run \`ado-axi work-item get ${id}\` to read the current rev, then retry`,
+        ]);
+    }
+    if (expectedRev !== undefined)
+        ops.unshift({ op: "test", path: "/rev", value: expectedRev });
+    let updated;
+    try {
+        updated = await request(profile, {
+            method: "PATCH",
+            path: `_apis/wit/workitems/${id}`,
+            body: ops,
+            contentType: "application/json-patch+json",
+        });
+    }
+    catch (err) {
+        if (expectedRev !== undefined &&
+            err instanceof AxiError &&
+            (err.code === "PRECONDITION_FAILED" || /VS403351|Test Operation/i.test(err.message))) {
+            throw new AxiError(`#${id} changed during the update — the ${ifRev !== undefined ? `--if-rev ${ifRev}` : `automatic revision ${expectedRev}`} check failed`, "PRECONDITION_FAILED", [
+                err.message,
+                `Run \`ado-axi work-item get ${id}\` to read the current rev, then retry`,
+            ]);
+        }
+        throw err;
+    }
+    const result = {
+        id: updated.id,
+        rev: updated.rev ?? "",
+        title: String(updated.fields?.["System.Title"] ?? ""),
+        state: String(updated.fields?.["System.State"] ?? ""),
+        assignee: personName(updated.fields?.["System.AssignedTo"]),
+        changed: expectedRev === undefined ? ops.length : ops.length - 1,
+        skipped: unchanged.join(", "),
+    };
+    if (tagChange) {
+        result.tags = String(updated.fields?.["System.Tags"] ?? "");
+        result["tags-added"] = tagChange.added.join(", ");
+        result["tags-removed"] = tagChange.removed.join(", ");
+    }
+    return { updated: result };
+}
+async function commentWorkItem(args) {
+    assertKnownFlags(args, COMMENT_FLAGS, "work-item comment");
+    const profile = profileFromArgs(args);
+    const project = requireProject(profile, "work-item comment");
+    const id = requireId(args, 'work-item comment <id> --body "..." [--format markdown|html]');
+    const body = flagString(args, "body") ?? (await readStdinIfPiped())?.toString("utf8") ?? args.positionals[1];
+    if (!body) {
+        throw new AxiError("--body is required", "VALIDATION_ERROR", [
+            `Usage: ado-axi work-item comment ${id} --body "..." [--format markdown|html]`,
+            "Pipe the comment to stdin when omitting --body",
+        ]);
+    }
+    const format = commentFormat(args);
+    const created = await request(profile, {
+        method: "POST",
+        path: `_apis/wit/workItems/${id}/comments`,
+        project,
+        query: { format },
+        body: { text: body },
+        apiVersion: "7.1-preview.4",
+    });
+    return { comment: { "work-item": id, id: created.id ?? "", posted: true } };
+}
+export { requestList };
+const ARTIFACT_LABELS = {
+    "pull request": "pull-request",
+    "fixed in commit": "commit",
+    "fixed in changeset": "changeset",
+    branch: "branch",
+    "integrated in build": "build",
+    "found in build": "build",
+};
+/** `vstfs:///Git/PullRequestId/<project>%2F<repo>%2F812` -> `812`, Ref links -> the branch name. */
+function artifactTarget(url) {
+    const decoded = decodeURIComponent(url);
+    const branch = decoded.match(/^vstfs:\/{3}Git\/Ref\/[^/]+\/[^/]+\/GB(.+)$/i);
+    if (branch)
+        return branch[1];
+    return decoded.split("/").filter(Boolean).pop() ?? "";
+}
+function describeRelation(relation) {
+    const rel = relation.rel ?? "";
+    const url = relation.url ?? "";
+    if (rel === "ArtifactLink") {
+        const raw = (relation.attributes?.name ?? "artifact").toLowerCase();
+        const name = ARTIFACT_LABELS[raw] ?? raw.replace(/\s+/g, "-");
+        const target = artifactTarget(url);
+        return { type: name, target: /^[0-9a-f]{40}$/i.test(target) ? target.slice(0, 8) : target };
+    }
+    const label = RELATION_LABELS[rel] ?? rel;
+    if (rel === "AttachedFile" || rel === "Hyperlink") {
+        return { type: label, target: relation.attributes?.name ?? url };
+    }
+    const id = Number(url.split("/").pop());
+    return { type: label, target: Number.isFinite(id) ? id : url };
+}
+async function linkWorkItem(args) {
+    const first = args.positionals[0] ?? "list";
+    const sub = /^\d+$/.test(first) ? "list" : first;
+    const rest = sub === first ? { ...args, positionals: args.positionals.slice(1) } : args;
+    switch (sub) {
+        case "list":
+            return listLinks(rest);
+        case "types":
+            return listLinkTypes(rest);
+        case "add":
+            return addLink(rest);
+        case "remove":
+            return removeLink(rest);
+        default:
+            throw new AxiError(`unknown subcommand \`work-item link ${sub}\``, "VALIDATION_ERROR", [
+                "Subcommands: list | types | add | remove",
+                "Run `ado-axi work-item --help` for the full reference",
+            ]);
+    }
+}
+async function listLinkTypes(args) {
+    assertKnownFlags(args, ["limit"], "work-item link types");
+    if (args.positionals.length > 0) {
+        throw new AxiError("Usage: ado-axi work-item link types [--limit 50] [--full]", "VALIDATION_ERROR");
+    }
+    const limit = flagNumber(args, "limit") ?? 50;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new AxiError("--limit must be a positive integer", "VALIDATION_ERROR");
+    }
+    const types = await requestList(profileFromArgs(args), { path: "_apis/wit/workitemrelationtypes" });
+    const shown = flagBool(args, "full") ? types : types.slice(0, limit);
+    return {
+        count: countLine(shown.length, types.length, "link types"),
+        "link-types": types.length === 0 ? "0 link types found" : pickFields(shown.map((type) => ({
+            reference: type.referenceName, name: type.name, usage: type.attributes?.usage ?? "",
+            enabled: type.attributes?.enabled ?? "",
+        })), flagList(args, "fields")),
+        ...(shown.length < types.length ? { "left-out": types.length - shown.length,
+            help: ["Run `ado-axi work-item link types --full` for all link types"] } : {}),
+    };
+}
+async function listLinks(args) {
+    assertKnownFlags(args, LINK_LIST_FLAGS, "work-item link list");
+    const profile = profileFromArgs(args);
+    const id = requireId(args, "work-item link list <id>");
+    const limit = flagNumber(args, "limit") ?? 50;
+    const item = await request(profile, {
+        path: `_apis/wit/workitems/${id}`,
+        query: { $expand: "relations" },
+    });
+    const relations = item.relations ?? [];
+    if (relations.length === 0) {
+        return {
+            links: `0 links on work item ${id}`,
+            help: [
+                `Run \`ado-axi work-item link add ${id} --parent <id>\` to place it in the hierarchy`,
+                `Run \`ado-axi work-item link add ${id} --pr <pull-request-id>\` to attach a pull request`,
+            ],
+        };
+    }
+    const shown = relations.slice(0, limit);
+    return {
+        "work-item": id,
+        rev: item.rev ?? "",
+        count: countLine(shown.length, relations.length, "links"),
+        links: pickFields(shown.map((relation, index) => {
+            const described = describeRelation(relation);
+            return {
+                index,
+                type: described.type,
+                target: described.target,
+                comment: relation.attributes?.comment ?? "",
+            };
+        }), flagList(args, "fields")),
+        help: [`Run \`ado-axi work-item link remove ${id} --index <index> --if-rev ${item.rev}\` to remove a relation`],
+    };
+}
+async function deleteWorkItem(args) {
+    assertKnownFlags(args, DELETE_FLAGS, "work-item delete");
+    const id = requireId(args, "work-item delete <id> --if-rev <n> [--destroy --confirm-destroy]");
+    const rev = requiredRevision(args, id);
+    if (args.positionals.length !== 1) {
+        throw new AxiError("exactly one work item id is required", "VALIDATION_ERROR");
+    }
+    const destroy = flagBool(args, "destroy");
+    if (destroy && !flagBool(args, "confirm-destroy")) {
+        throw new AxiError("permanent destruction requires --destroy --confirm-destroy and --if-rev <n>", "VALIDATION_ERROR", [
+            "Omit --destroy to move the work item to the recycle bin instead",
+        ]);
+    }
+    const profile = profileFromArgs(args);
+    const current = await request(profile, { path: `_apis/wit/workitems/${id}` });
+    checkRevision(current, rev);
+    // DELETE has no atomic revision predicate. This is a preflight check, not a JSON-Patch CAS.
+    await request(profile, {
+        method: "DELETE",
+        path: `_apis/wit/workitems/${id}`,
+        query: { destroy },
+    });
+    return {
+        deleted: { id, outcome: destroy ? "permanently destroyed" : "moved to recycle bin", "checked-rev": rev },
+    };
+}
+function requiredRevision(args, id) {
+    const rev = flagNumber(args, "if-rev");
+    if (rev === undefined || !Number.isInteger(rev) || rev < 1) {
+        throw new AxiError("--if-rev must be a positive integer", "VALIDATION_ERROR", [
+            `Run \`ado-axi work-item get ${id}\` to read the current rev`,
+        ]);
+    }
+    return rev;
+}
+function checkRevision(item, rev) {
+    if (item.rev !== rev) {
+        throw new AxiError(`#${item.id} is at rev ${item.rev ?? "unknown"}, expected ${rev} - write refused`, "PRECONDITION_FAILED", [
+            `Run \`ado-axi work-item get ${item.id}\` to re-read the current rev before retrying`,
+        ]);
+    }
+}
+async function removeLink(args) {
+    assertKnownFlags(args, LINK_REMOVE_FLAGS, "work-item link remove");
+    const id = requireId(args, "work-item link remove <id> --index <index> --if-rev <n>");
+    const rev = requiredRevision(args, id);
+    const index = flagNumber(args, "index");
+    if (args.positionals.length !== 1 || index === undefined || !Number.isInteger(index) || index < 0) {
+        throw new AxiError("--index must be a non-negative integer and exactly one work item id is required", "VALIDATION_ERROR", [
+            `Run \`ado-axi work-item link list ${id}\` to read relation indexes and rev`,
+        ]);
+    }
+    const profile = profileFromArgs(args);
+    const current = await request(profile, {
+        path: `_apis/wit/workitems/${id}`,
+        query: { $expand: "relations" },
+    });
+    checkRevision(current, rev);
+    const relation = current.relations?.[index];
+    if (!relation) {
+        throw new AxiError(`no relation at index ${index} on #${id} - removal refused`, "VALIDATION_ERROR", [
+            `Run \`ado-axi work-item link list ${id}\` to read relation indexes and rev`,
+        ]);
+    }
+    let updated;
+    try {
+        updated = await request(profile, {
+            method: "PATCH",
+            path: `_apis/wit/workitems/${id}`,
+            contentType: "application/json-patch+json",
+            body: [patch("test", "/rev", rev), { op: "remove", path: `/relations/${index}` }],
+        });
+    }
+    catch (err) {
+        if (err instanceof AxiError && (err.code === "PRECONDITION_FAILED" || /VS403351|Test Operation/i.test(err.message))) {
+            throw new AxiError(`#${id} changed during link removal - removal refused without retry`, "PRECONDITION_FAILED", [
+                `Run \`ado-axi work-item link list ${id}\` to re-read relation indexes and rev before retrying`,
+            ]);
+        }
+        throw err;
+    }
+    return {
+        removed: { "work-item": id, index, ...describeRelation(relation), rev: updated.rev ?? "" },
+        help: [`Run \`ado-axi work-item link list ${id}\` to see the remaining links`],
+    };
+}
+async function artifactLink(profile, args, project, kind, value) {
+    if (kind === "pr") {
+        const prId = Number(value);
+        if (!Number.isInteger(prId) || prId < 1) {
+            throw new AxiError("--pr expects a pull request id", "VALIDATION_ERROR", [
+                "Run `ado-axi pr list` to find pull request ids",
+            ]);
+        }
+        const repoFlag = flagString(args, "repo");
+        const pr = await request(profile, {
+            path: repoFlag
+                ? `_apis/git/repositories/${encodeURIComponent(repoFlag)}/pullrequests/${prId}`
+                : `_apis/git/pullrequests/${prId}`,
+            project: repoFlag ? project : undefined,
+        });
+        const repoId = pr.repository?.id;
+        const projectId = pr.repository?.project?.id;
+        if (!repoId || !projectId) {
+            throw new AxiError(`could not resolve the repository of pull request ${prId}`, "NOT_FOUND", [
+                "Pass --repo <repo> explicitly",
+            ]);
+        }
+        return {
+            rel: "ArtifactLink",
+            url: `vstfs:///Git/PullRequestId/${projectId}%2F${repoId}%2F${prId}`,
+            name: "Pull Request",
+            type: "pull-request",
+            target: String(prId),
+        };
+    }
+    const repo = flagString(args, "repo");
+    if (kind === "commit" && !/^[0-9a-f]{40}$/i.test(value)) {
+        throw new AxiError("--commit expects a 40-character commit id", "VALIDATION_ERROR", [
+            "Pass the full commit SHA, not an abbreviation",
+        ]);
+    }
+    if (!repo) {
+        throw new AxiError(`--repo <name> is required with --${kind}`, "VALIDATION_ERROR", [
+            `Usage: ado-axi work-item link add <id> --${kind} <value> --repo <name>`,
+            "Run `ado-axi repo list` to see repository names",
+        ]);
+    }
+    const repository = await request(profile, {
+        path: `_apis/git/repositories/${encodeURIComponent(repo)}`,
+        project,
+    });
+    const repoId = repository.id;
+    const projectId = repository.project?.id;
+    if (!repoId || !projectId) {
+        throw new AxiError(`could not resolve repository '${repo}'`, "NOT_FOUND", [
+            "Run `ado-axi repo list` to see repository names",
+        ]);
+    }
+    if (kind === "commit") {
+        return {
+            rel: "ArtifactLink",
+            url: `vstfs:///Git/Commit/${projectId}%2F${repoId}%2F${value}`,
+            name: "Fixed in Commit",
+            type: "commit",
+            target: value.slice(0, 8),
+        };
+    }
+    const branch = value.replace(/^refs\/heads\//, "");
+    return {
+        rel: "ArtifactLink",
+        url: `vstfs:///Git/Ref/${projectId}%2F${repoId}%2FGB${encodeURIComponent(branch)}`,
+        name: "Branch",
+        type: "branch",
+        target: branch,
+    };
+}
+/** Azure DevOps rewrites work item link URLs with the project GUID, so compare those by id. */
+function sameLink(relation, link) {
+    if ((relation.rel ?? "") !== link.rel)
+        return false;
+    const stored = decodeURIComponent(relation.url ?? "").toLowerCase();
+    const wanted = decodeURIComponent(link.url).toLowerCase();
+    if (link.rel === "ArtifactLink")
+        return stored === wanted;
+    return stored.split("/").pop() === wanted.split("/").pop();
+}
+async function addLink(args) {
+    assertKnownFlags(args, LINK_ADD_FLAGS, "work-item link add");
+    const profile = profileFromArgs(args);
+    const project = requireProject(profile, "work-item link add");
+    const id = requireId(args, "work-item link add <id> --parent <id> | --pr <id>");
+    const selected = ["parent", "child", "related", "pr", "commit", "branch"].filter((flag) => flagString(args, flag) !== undefined);
+    if (selected.length !== 1) {
+        throw new AxiError(selected.length === 0
+            ? "a link target is required"
+            : `pass exactly one link target, got ${selected.join(", ")}`, "VALIDATION_ERROR", [
+            `Usage: ado-axi work-item link add ${id} (--parent <id> | --child <id> | --related <id> | --pr <id> | --commit <40-hex> --repo <name> | --branch <name> --repo <name>)`,
+        ]);
+    }
+    const kind = selected[0];
+    const value = flagString(args, kind);
+    let link;
+    if (kind in HIERARCHY) {
+        const targetId = Number(value);
+        if (!Number.isInteger(targetId) || targetId < 1) {
+            throw new AxiError(`--${kind} expects a work item id`, "VALIDATION_ERROR", [
+                "Run `ado-axi work-item list` to find ids",
+            ]);
+        }
+        if (targetId === id)
+            throw new AxiError("a work item cannot link to itself", "VALIDATION_ERROR");
+        link = {
+            rel: HIERARCHY[kind],
+            url: `https://dev.azure.com/${profile.org}/_apis/wit/workItems/${targetId}`,
+            type: kind,
+            target: String(targetId),
+        };
+    }
+    else {
+        link = await artifactLink(profile, args, project, kind, value);
+    }
+    const current = await request(profile, {
+        path: `_apis/wit/workitems/${id}`,
+        query: { $expand: "relations" },
+    });
+    const existing = (current.relations ?? []).find((relation) => sameLink(relation, link));
+    if (existing) {
+        return {
+            link: `#${id} already links to ${link.target} as ${link.type} (no-op)`,
+            rev: current.rev ?? "",
+        };
+    }
+    const ops = [];
+    const ifRev = flagNumber(args, "if-rev");
+    if (ifRev !== undefined)
+        ops.push(patch("test", "/rev", ifRev));
+    const comment = flagString(args, "comment");
+    ops.push(patch("add", "/relations/-", {
+        rel: link.rel,
+        url: link.url,
+        attributes: {
+            ...(link.name ? { name: link.name } : {}),
+            ...(comment ? { comment } : {}),
+        },
+    }));
+    const updated = await request(profile, {
+        method: "PATCH",
+        path: `_apis/wit/workitems/${id}`,
+        project,
+        body: ops,
+        contentType: "application/json-patch+json",
+    });
+    return {
+        linked: {
+            "work-item": id,
+            type: link.type,
+            target: link.target,
+            rel: link.rel,
+            rev: updated.rev ?? "",
+        },
+        help: [`Run \`ado-axi work-item link list ${id}\` to see every link`],
+    };
+}
+//# sourceMappingURL=workItem.js.map