azdo-cli 0.10.0-develop.479 → 0.10.0-develop.490

package/README.md

@@ -68,6 +68,14 @@ azdo pipeline get-runs 12 --branch develop --limit 1
 azdo pipeline wait 3456                     # blocks; exit 0 success / non-zero failure / 124 timeout
 azdo pipeline get-run-detail 3456           # errors, failing tests, per-stage status
 azdo pipeline start 12 --branch develop --parameter env=staging
+
+# Work item relations — types, add, remove, list
+azdo relations types                        # list all relation types (Child, Parent, Related, ...)
+azdo relations types --json                 # machine-readable JSON array
+azdo relations add child 1000 2000          # make #2000 a child of #1000 (idempotent)
+azdo relations remove child 1000 2000       # remove the child relation
+azdo relations list 1000                    # show all relations on work item #1000
+azdo relations list 1000 --json             # JSON: { workItemId, relations: [...] }
 ```
 
 ## Documentation

package/dist/index.js

@@ -38,7 +38,7 @@ import {
 } from "./chunk-XVXMDWQE.js";
 
 // src/index.ts
-import { Command as Command16 } from "commander";
+import { Command as Command17 } from "commander";
 
 // src/version.ts
 import { readFileSync } from "fs";
@@ -4703,6 +4703,299 @@ function createDownloadAttachmentCommand() {
   return command;
 }
 
+// src/commands/relations.ts
+import { Command as Command16 } from "commander";
+
+// src/services/relations-client.ts
+var API_VERSION2 = "7.1";
+function buildRelationTypesUrl(context) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/_apis/wit/workitemrelationtypes`
+  );
+  url.searchParams.set("api-version", API_VERSION2);
+  return url;
+}
+function buildWorkItemUrl2(context, id, expand) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems/${id}`
+  );
+  url.searchParams.set("api-version", API_VERSION2);
+  if (expand) url.searchParams.set("$expand", expand);
+  return url;
+}
+function buildBatchWorkItemsUrl(context, ids) {
+  const url = new URL(
+    `https://dev.azure.com/${encodeURIComponent(context.org)}/${encodeURIComponent(context.project)}/_apis/wit/workitems`
+  );
+  url.searchParams.set("ids", ids.join(","));
+  url.searchParams.set("fields", "System.Id,System.Title");
+  url.searchParams.set("api-version", API_VERSION2);
+  return url;
+}
+function mapRelationType(raw) {
+  return {
+    referenceName: raw.referenceName,
+    name: raw.name,
+    usage: raw.attributes?.usage ?? "unknown",
+    enabled: raw.attributes?.enabled !== false,
+    directional: raw.attributes?.directional ?? null
+  };
+}
+async function readJsonResponse3(response) {
+  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  return await response.json();
+}
+function parseTargetId(url) {
+  const match = /\/workItems\/(\d+)$/i.exec(url);
+  return match ? Number(match[1]) : null;
+}
+async function getWorkItemRelationTypes(context, cred) {
+  const url = buildRelationTypesUrl(context);
+  const response = await fetchWithErrors(url.toString(), {
+    headers: authHeaders(cred)
+  });
+  const body = await readJsonResponse3(response);
+  return (body.value ?? []).map(mapRelationType).filter((t) => t.usage === "workItemLink" && t.enabled);
+}
+async function resolveRelationType(context, cred, alias) {
+  const types = await getWorkItemRelationTypes(context, cred);
+  const lower = alias.toLowerCase();
+  const match = types.find((t) => t.name.toLowerCase() === lower);
+  if (!match) throw new Error(`UNKNOWN_RELATION_TYPE:${alias}`);
+  return match;
+}
+async function getWorkItemWithRelations(context, cred, id) {
+  const url = buildWorkItemUrl2(context, id, "relations");
+  const response = await fetchWithErrors(url.toString(), {
+    headers: authHeaders(cred)
+  });
+  return readJsonResponse3(response);
+}
+async function addWorkItemRelation(context, cred, type, id1, id2) {
+  if (id1 === id2) throw new Error("SELF_RELATION");
+  const relType = await resolveRelationType(context, cred, type);
+  const workItem = await getWorkItemWithRelations(context, cred, id1);
+  const targetUrl = `https://dev.azure.com/${encodeURIComponent(context.org)}/_apis/wit/workItems/${id2}`;
+  const existing = (workItem.relations ?? []).find(
+    (r) => r.rel === relType.referenceName && r.url.toLowerCase() === targetUrl.toLowerCase()
+  );
+  if (existing) {
+    return { status: "already_exists", type: relType.name, referenceName: relType.referenceName, id1, id2 };
+  }
+  const patchUrl = buildWorkItemUrl2(context, id1);
+  const response = await fetchWithErrors(patchUrl.toString(), {
+    method: "PATCH",
+    headers: { ...authHeaders(cred), "Content-Type": "application/json-patch+json" },
+    body: JSON.stringify([
+      { op: "add", path: "/relations/-", value: { rel: relType.referenceName, url: targetUrl } }
+    ])
+  });
+  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  return { status: "added", type: relType.name, referenceName: relType.referenceName, id1, id2 };
+}
+async function removeWorkItemRelation(context, cred, type, id1, id2) {
+  if (id1 === id2) throw new Error("SELF_RELATION");
+  const relType = await resolveRelationType(context, cred, type);
+  const workItem = await getWorkItemWithRelations(context, cred, id1);
+  const relations = workItem.relations ?? [];
+  const index = relations.findIndex(
+    (r) => r.rel === relType.referenceName && parseTargetId(r.url) === id2
+  );
+  if (index === -1) {
+    return { status: "not_found", type: relType.name, referenceName: relType.referenceName, id1, id2 };
+  }
+  const patchUrl = buildWorkItemUrl2(context, id1);
+  const response = await fetchWithErrors(patchUrl.toString(), {
+    method: "PATCH",
+    headers: { ...authHeaders(cred), "Content-Type": "application/json-patch+json" },
+    body: JSON.stringify([{ op: "remove", path: `/relations/${index}` }])
+  });
+  if (!response.ok) throw new Error(`HTTP_${response.status}`);
+  return { status: "removed", type: relType.name, referenceName: relType.referenceName, id1, id2 };
+}
+async function listWorkItemRelations(context, cred, id) {
+  const workItem = await getWorkItemWithRelations(context, cred, id);
+  const allRelations = workItem.relations ?? [];
+  const wiRelations = allRelations.filter(
+    (r) => !r.rel.startsWith("AttachedFile") && !r.rel.startsWith("Hyperlink") && !r.rel.startsWith("ArtifactLink")
+  );
+  if (wiRelations.length === 0) {
+    return { workItemId: id, relations: [] };
+  }
+  const types = await getWorkItemRelationTypes(context, cred);
+  const typeNameMap = new Map(types.map((t) => [t.referenceName, t.name]));
+  const targetIds = wiRelations.map((r) => parseTargetId(r.url)).filter((n) => n !== null);
+  const titleMap = /* @__PURE__ */ new Map();
+  if (targetIds.length > 0) {
+    try {
+      const batchUrl = buildBatchWorkItemsUrl(context, targetIds);
+      const batchResponse = await fetchWithErrors(batchUrl.toString(), {
+        headers: authHeaders(cred)
+      });
+      const batchBody = await readJsonResponse3(batchResponse);
+      for (const item of batchBody.value ?? []) {
+        titleMap.set(item.id, item.fields["System.Title"] ?? "");
+      }
+    } catch {
+    }
+  }
+  const relations = wiRelations.map((r) => {
+    const targetId = parseTargetId(r.url);
+    return {
+      rel: r.rel,
+      relName: typeNameMap.get(r.rel) ?? r.rel,
+      targetId: targetId ?? 0,
+      targetTitle: targetId !== null ? titleMap.get(targetId) ?? null : null,
+      targetUrl: r.url,
+      comment: r.attributes?.comment ?? null
+    };
+  });
+  return { workItemId: id, relations };
+}
+
+// src/commands/relations.ts
+function addCommonOptions(cmd) {
+  return cmd.option("--json", "Output as JSON").option("--org <org>", "Azure DevOps organization").option("--project <project>", "Azure DevOps project");
+}
+async function resolveCredentials(opts) {
+  const context = resolveContext(opts);
+  const cred = await requireAuthCredential(context.org);
+  return { context, cred };
+}
+function formatRelationTypes(types) {
+  if (types.length === 0) return "No work item relation types found.";
+  const nameWidth = Math.max(...types.map((t) => t.name.length), 4);
+  const lines = ["Available work item relation types:", ""];
+  for (const t of types) {
+    lines.push(`${t.name.padEnd(nameWidth + 2)}${t.referenceName}`);
+  }
+  return lines.join("\n");
+}
+function formatRelationsList(workItemId, relations) {
+  if (relations.length === 0) return `Work item #${workItemId} has no relations.`;
+  const typeWidth = Math.max(...relations.map((r) => r.relName.length), 4) + 2;
+  const idWidth = Math.max(...relations.map((r) => String(r.targetId).length), 4) + 1;
+  const lines = [`Relations for work item #${workItemId}:`, ""];
+  for (const r of relations) {
+    const typeLabel = `[${r.relName}]`.padEnd(typeWidth);
+    const idLabel = `#${r.targetId}`.padEnd(idWidth);
+    lines.push(`${typeLabel}  ${idLabel}  ${r.targetTitle ?? "(unknown)"}`);
+  }
+  return lines.join("\n");
+}
+function handleRelationError(err, id1) {
+  const msg = err instanceof Error ? err.message : String(err);
+  if (msg === "SELF_RELATION") {
+    process.stderr.write(`Error: cannot relate a work item to itself (#${id1}).
+`);
+  } else if (msg.startsWith("UNKNOWN_RELATION_TYPE:")) {
+    const name = msg.replace("UNKNOWN_RELATION_TYPE:", "");
+    process.stderr.write(
+      `Error: unknown relation type "${name}". Run 'azdo relations types' to see valid names.
+`
+    );
+  } else if (msg.startsWith("NOT_FOUND")) {
+    const target = id1 !== void 0 ? id1 : "unknown";
+    process.stderr.write(`Error: work item #${target} not found.
+`);
+  } else if (msg === "AUTH_FAILED") {
+    process.stderr.write(
+      `Error: authentication failed. Check your PAT has Work Items \u2192 Read & Write scope.
+`
+    );
+  } else {
+    process.stderr.write(`Error: ${msg}
+`);
+  }
+  process.exit(1);
+}
+function parsePositiveInt(value, label) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n <= 0) {
+    process.stderr.write(`Error: ${label} must be a positive integer.
+`);
+    process.exit(1);
+  }
+  return n;
+}
+function createRelationsCommand() {
+  const relations = new Command16("relations").description("Manage work item relations");
+  addCommonOptions(
+    relations.command("types").description("List all available work item relation types")
+  ).action(async (opts) => {
+    try {
+      const { context, cred } = await resolveCredentials(opts);
+      const types = await getWorkItemRelationTypes(context, cred);
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(types, null, 2) + "\n");
+      } else {
+        process.stdout.write(formatRelationTypes(types) + "\n");
+      }
+    } catch (err) {
+      handleRelationError(err);
+    }
+  });
+  addCommonOptions(
+    relations.command("add <type> <id1> <id2>").description("Add a directed relation from work item <id1> to <id2>")
+  ).action(async (type, id1Str, id2Str, opts) => {
+    const id1 = parsePositiveInt(id1Str, "id1");
+    const id2 = parsePositiveInt(id2Str, "id2");
+    try {
+      const { context, cred } = await resolveCredentials(opts);
+      const result = await addWorkItemRelation(context, cred, type, id1, id2);
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else if (result.status === "already_exists") {
+        process.stdout.write(`Relation already exists: #${id1} --[${result.type}]--> #${id2}
+`);
+      } else {
+        process.stdout.write(`Added relation: #${id1} --[${result.type}]--> #${id2}
+`);
+      }
+    } catch (err) {
+      handleRelationError(err, id1);
+    }
+  });
+  addCommonOptions(
+    relations.command("remove <type> <id1> <id2>").description("Remove a directed relation of <type> from work item <id1> to <id2>")
+  ).action(async (type, id1Str, id2Str, opts) => {
+    const id1 = parsePositiveInt(id1Str, "id1");
+    const id2 = parsePositiveInt(id2Str, "id2");
+    try {
+      const { context, cred } = await resolveCredentials(opts);
+      const result = await removeWorkItemRelation(context, cred, type, id1, id2);
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else if (result.status === "not_found") {
+        process.stdout.write(`No relation of type '${result.type}' found between #${id1} and #${id2}
+`);
+      } else {
+        process.stdout.write(`Removed relation: #${id1} --[${result.type}]--> #${id2}
+`);
+      }
+    } catch (err) {
+      handleRelationError(err, id1);
+    }
+  });
+  addCommonOptions(
+    relations.command("list <id>").description("List all work item link relations on a work item")
+  ).action(async (idStr, opts) => {
+    const id = parsePositiveInt(idStr, "id");
+    try {
+      const { context, cred } = await resolveCredentials(opts);
+      const result = await listWorkItemRelations(context, cred, id);
+      if (opts.json) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else {
+        process.stdout.write(formatRelationsList(result.workItemId, result.relations) + "\n");
+      }
+    } catch (err) {
+      handleRelationError(err, id);
+    }
+  });
+  return relations;
+}
+
 // src/services/update-check.ts
 import fs2 from "fs";
 import path2 from "path";
@@ -4816,7 +5109,7 @@ function exitOnEpipe(err) {
 }
 process.stdout.on("error", exitOnEpipe);
 process.stderr.on("error", exitOnEpipe);
-var program = new Command16();
+var program = new Command17();
 program.name("azdo").description("Azure DevOps CLI tool").version(version, "-v, --version");
 program.option("--no-update-check", "Skip the check for a newer published version");
 program.addCommand(createGetItemCommand());
@@ -4834,6 +5127,7 @@ program.addCommand(createPrCommand());
 program.addCommand(createPipelineCommand());
 program.addCommand(createCommentsCommand());
 program.addCommand(createDownloadAttachmentCommand());
+program.addCommand(createRelationsCommand());
 program.showHelpAfterError();
 program.hook("postAction", async () => {
   const notice = await getUpdateNotice({ enabled: program.opts().updateCheck });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azdo-cli",
-  "version": "0.10.0-develop.479",
+  "version": "0.10.0-develop.490",
   "description": "Azure DevOps CLI tool",
   "type": "module",
   "bin": {