bmsdna-devtools 0.40.0__tar.gz → 0.42.0__tar.gz

{bmsdna_devtools-0.40.0 → bmsdna_devtools-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.40.0
+Version: 0.42.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: pgdevkit[db]>=0.7.1
@@ -50,7 +50,7 @@ Find the PR opened from the current branch and report build/check status
 GitHub — whichever `origin` points at.
 
 ```bash
-bdt pr status [--target-branch BRANCH] [--wait]
+bdt pr status [--target-branch BRANCH] [--pr-id N] [--wait [--timeout SECONDS]]
 ```
 
 Every command that acts on an existing PR (`pr status/info/retry/publish/update/comment`, `issue take` without
@@ -75,6 +75,12 @@ stage/check needs a reviewer plus a link to act on it, and exits **3**
 build/check has already failed, that's reported instead (exit 1) even when
 one is also waiting on approval.
 
+`--wait --timeout SECONDS` gives up after that long when the checks are still running: it prints the current
+state of every pipeline/check, ends with `Still running after N s. Re-run ... to keep waiting.` (the command pins `--pr-id` to the PR it watched) and exits **4**
+(like `issue watch`). Use it where the caller's own limit is shorter than CI, e.g. an agent's shell tool, which
+kills the command after a few minutes and discards its output; re-run the same command to keep waiting.
+Without `--timeout` (or with `0`) it waits until everything is done, as before. `--timeout` needs `--wait`.
+
 On Azure DevOps, `--wait` on a PR with no builds yet also checks that the target branch has an enabled
 Build validation policy; if it doesn't, no build will ever run, so it exits 1 with an error instead of
 polling forever (a failed policy lookup is ignored and the wait continues).
@@ -247,11 +253,14 @@ create prints a reminder to run `bdt pr status` afterward to check whether
 the CI build passes. This is a best-effort check — failures reading policy
 config (auth, permissions) fail open and simply skip the reminder.
 
-## `bdt issue create` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
+## `bdt issue create` / `show` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
 
 ```bash
 bdt issue create --title "Nightly job fails" --description "..." --type Bug --screenshot before.png
+bdt issue create --title "Add retries" --type Task --iteration 'MyProject\Sprint 1' --parent 1200 --blocked-by 1210
+bdt issue show 1234 [--json]
 bdt issue update 1234 --state Resolved --tag fixed
+bdt issue update 1234 --iteration 'MyProject\Sprint 2' --parent 1200 --blocked-by 1210 --blocked-by 1211
 bdt issue delete 1234 --yes
 
 bdt issue comment add 1234 --message "Repro'd, see attached" --screenshot repro.png
@@ -264,6 +273,17 @@ adds/edits/deletes comments on one, auto-detected from `origin` like `bdt pr
 *`. `bdt issue comment add` prints the new comment's ID so you can pass it to
 `update`/`delete` later.
 
+`issue show NUMBER` prints one issue / work item: state, title, URL, description, tags, links to other
+issues (parent, children, blocked by, blocks; related on Azure DevOps), the Azure DevOps Type / Area /
+Iteration / Assigned to (GitHub: assignees, milestone) and all comments (Azure DevOps HTML is shown as plain
+text). `--json` prints the same as one JSON document (`number, title, state, url, body, tags, fields,
+parent, children, blocked_by, blocks, related, comments`).
+
+`--parent ID` and `--blocked-by ID` (repeatable) on `create` and `update` link the item to its parent and to
+the issues / work items that block it, on both backends. On `update` only the links that are missing are
+added, so repeating a command is harmless (like `--tag`); `--parent` replaces a different current parent.
+They only ever add links: removing one still goes through the web UI.
+
 Destructive commands (`issue delete`, `issue comment delete`) require an
 explicit `--yes` — there's no interactive confirmation prompt, since `bdt` is
 also invoked by AI-agent callers that can't answer one.
@@ -290,6 +310,17 @@ literal text, but the work item Discussion/Comments control has always
 rendered Markdown. `issue delete` soft-deletes to the project's Recycle Bin
 (restorable, not permanent).
 
+`--iteration <path>` on `create` and `update` sets `System.IterationPath`, e.g. `'MyProject\Sprint 1'` (in
+Basic-process projects a work item without an iteration doesn't show on the team backlog). It is Azure DevOps
+only: on a GitHub repo it fails with a usage error (exit 2) instead of being ignored. On `create` it defaults
+to `[tool.bdt.ado].iteration` from `pyproject.toml`; on `update` it is only applied when given. `bdt` doesn't
+look up the board team's current iteration, so name the path yourself:
+
+```toml
+[tool.bdt.ado]
+iteration = 'MyProject\Sprint 1'   # single quotes: TOML takes the backslash literally
+```
+
 `--board <team>` sets the work item's Area Path to that Azure Boards team's
 default, so it shows up on that team's board — a CLI flag beats
 `[tool.bdt.ado].board` in `pyproject.toml`, which beats filing under the
@@ -329,6 +360,11 @@ subcommand for editing/deleting an arbitrary comment by ID). Extra arguments
 to `bdt issue create` pass through to `gh issue create`, e.g.
 `bdt issue create --title "..." -- --assignee @me`.
 
+`--parent` / `--blocked-by` use GitHub's sub-issues and issue dependencies (`gh issue create --parent` /
+`--blocked-by`, `gh issue edit --parent` / `--add-blocked-by`), which need a recent `gh`; `issue show` reads
+them with `gh issue view --json parent,subIssues,blockedBy,blocking`. `--iteration` isn't supported: a
+GitHub Projects (v2) iteration is a per-project field, not a property of the issue.
+
 `--board <name>` on `create` adds the issue to that GitHub Projects (v2)
 board by title (needs a token with the `project` scope — `gh auth refresh -s
 project`). On `search`, `--board` (title or number) scopes results to issues

{bmsdna_devtools-0.40.0 → bmsdna_devtools-0.42.0}/README.md

@@ -36,7 +36,7 @@ Find the PR opened from the current branch and report build/check status
 GitHub — whichever `origin` points at.
 
 ```bash
-bdt pr status [--target-branch BRANCH] [--wait]
+bdt pr status [--target-branch BRANCH] [--pr-id N] [--wait [--timeout SECONDS]]
 ```
 
 Every command that acts on an existing PR (`pr status/info/retry/publish/update/comment`, `issue take` without
@@ -61,6 +61,12 @@ stage/check needs a reviewer plus a link to act on it, and exits **3**
 build/check has already failed, that's reported instead (exit 1) even when
 one is also waiting on approval.
 
+`--wait --timeout SECONDS` gives up after that long when the checks are still running: it prints the current
+state of every pipeline/check, ends with `Still running after N s. Re-run ... to keep waiting.` (the command pins `--pr-id` to the PR it watched) and exits **4**
+(like `issue watch`). Use it where the caller's own limit is shorter than CI, e.g. an agent's shell tool, which
+kills the command after a few minutes and discards its output; re-run the same command to keep waiting.
+Without `--timeout` (or with `0`) it waits until everything is done, as before. `--timeout` needs `--wait`.
+
 On Azure DevOps, `--wait` on a PR with no builds yet also checks that the target branch has an enabled
 Build validation policy; if it doesn't, no build will ever run, so it exits 1 with an error instead of
 polling forever (a failed policy lookup is ignored and the wait continues).
@@ -233,11 +239,14 @@ create prints a reminder to run `bdt pr status` afterward to check whether
 the CI build passes. This is a best-effort check — failures reading policy
 config (auth, permissions) fail open and simply skip the reminder.
 
-## `bdt issue create` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
+## `bdt issue create` / `show` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
 
 ```bash
 bdt issue create --title "Nightly job fails" --description "..." --type Bug --screenshot before.png
+bdt issue create --title "Add retries" --type Task --iteration 'MyProject\Sprint 1' --parent 1200 --blocked-by 1210
+bdt issue show 1234 [--json]
 bdt issue update 1234 --state Resolved --tag fixed
+bdt issue update 1234 --iteration 'MyProject\Sprint 2' --parent 1200 --blocked-by 1210 --blocked-by 1211
 bdt issue delete 1234 --yes
 
 bdt issue comment add 1234 --message "Repro'd, see attached" --screenshot repro.png
@@ -250,6 +259,17 @@ adds/edits/deletes comments on one, auto-detected from `origin` like `bdt pr
 *`. `bdt issue comment add` prints the new comment's ID so you can pass it to
 `update`/`delete` later.
 
+`issue show NUMBER` prints one issue / work item: state, title, URL, description, tags, links to other
+issues (parent, children, blocked by, blocks; related on Azure DevOps), the Azure DevOps Type / Area /
+Iteration / Assigned to (GitHub: assignees, milestone) and all comments (Azure DevOps HTML is shown as plain
+text). `--json` prints the same as one JSON document (`number, title, state, url, body, tags, fields,
+parent, children, blocked_by, blocks, related, comments`).
+
+`--parent ID` and `--blocked-by ID` (repeatable) on `create` and `update` link the item to its parent and to
+the issues / work items that block it, on both backends. On `update` only the links that are missing are
+added, so repeating a command is harmless (like `--tag`); `--parent` replaces a different current parent.
+They only ever add links: removing one still goes through the web UI.
+
 Destructive commands (`issue delete`, `issue comment delete`) require an
 explicit `--yes` — there's no interactive confirmation prompt, since `bdt` is
 also invoked by AI-agent callers that can't answer one.
@@ -276,6 +296,17 @@ literal text, but the work item Discussion/Comments control has always
 rendered Markdown. `issue delete` soft-deletes to the project's Recycle Bin
 (restorable, not permanent).
 
+`--iteration <path>` on `create` and `update` sets `System.IterationPath`, e.g. `'MyProject\Sprint 1'` (in
+Basic-process projects a work item without an iteration doesn't show on the team backlog). It is Azure DevOps
+only: on a GitHub repo it fails with a usage error (exit 2) instead of being ignored. On `create` it defaults
+to `[tool.bdt.ado].iteration` from `pyproject.toml`; on `update` it is only applied when given. `bdt` doesn't
+look up the board team's current iteration, so name the path yourself:
+
+```toml
+[tool.bdt.ado]
+iteration = 'MyProject\Sprint 1'   # single quotes: TOML takes the backslash literally
+```
+
 `--board <team>` sets the work item's Area Path to that Azure Boards team's
 default, so it shows up on that team's board — a CLI flag beats
 `[tool.bdt.ado].board` in `pyproject.toml`, which beats filing under the
@@ -315,6 +346,11 @@ subcommand for editing/deleting an arbitrary comment by ID). Extra arguments
 to `bdt issue create` pass through to `gh issue create`, e.g.
 `bdt issue create --title "..." -- --assignee @me`.
 
+`--parent` / `--blocked-by` use GitHub's sub-issues and issue dependencies (`gh issue create --parent` /
+`--blocked-by`, `gh issue edit --parent` / `--add-blocked-by`), which need a recent `gh`; `issue show` reads
+them with `gh issue view --json parent,subIssues,blockedBy,blocking`. `--iteration` isn't supported: a
+GitHub Projects (v2) iteration is a per-project field, not a property of the issue.
+
 `--board <name>` on `create` adds the issue to that GitHub Projects (v2)
 board by title (needs a token with the `project` scope — `gh auth refresh -s
 project`). On `search`, `--board` (title or number) scopes results to issues

{bmsdna_devtools-0.40.0 → bmsdna_devtools-0.42.0}/bmsdna/devtools/ado_issue.py

@@ -6,7 +6,7 @@ Built directly on the Work Item Tracking REST API (api-version 7.1):
   - Update:      PATCH   {org}/{project}/_apis/wit/workitems/{id}
   - Delete:      DELETE  {org}/{project}/_apis/wit/workitems/{id} (soft-delete to the Recycle Bin — recoverable;
                  there is no `destroy=true` support here on purpose, since that's a permanent, unrecoverable delete)
-  - Get:         GET     {org}/{project}/_apis/wit/workitems/{id}
+  - Get:         GET     {org}/{project}/_apis/wit/workitems/{id}[?$expand=relations]
   - Attachments: POST    {org}/{project}/_apis/wit/attachments?fileName=...
   - Comments:    POST/PATCH/DELETE {org}/{project}/_apis/wit/workItems/{id}/comments[/{commentId}]
                  (api-version 7.1-preview.4 — the "Comments"/discussion resource is still in preview
@@ -40,6 +40,7 @@ a field is saved as Markdown it can't be switched back to HTML via the API.
 
 from __future__ import annotations
 
+import re
 import sys
 from collections.abc import Callable
 from dataclasses import replace
@@ -51,17 +52,35 @@ import requests
 from .bdt_config import load_bdt_table
 from .cli_tools import ensure_agent_session_note
 from .gitrepo import AdoRemote
+from .issue_show import IssueDetails
+from .issue_watch import html_to_text, to_comments
 from .pr_issue_link import PR_AVAILABLE_LABEL
 from .pr_markdown import build_comment_content_html
 
 COMMENTS_API_VERSION = "7.1-preview.4"
 
+# Work item link types. The "Reverse" end sits on the item that points at the other one: a child
+# carries a Hierarchy-Reverse link to its parent, and a blocked item a Dependency-Reverse link to its
+# predecessor (the blocker).
+PARENT_REL = "System.LinkTypes.Hierarchy-Reverse"
+CHILD_REL = "System.LinkTypes.Hierarchy-Forward"
+BLOCKED_BY_REL = "System.LinkTypes.Dependency-Reverse"
+BLOCKS_REL = "System.LinkTypes.Dependency-Forward"
+RELATED_REL = "System.LinkTypes.Related"
+
+_WORK_ITEM_URL_ID_RE = re.compile(r"/workitems/(\d+)$", re.IGNORECASE)
+
 
 def resolve_board(board: str | None, start: Path | None = None) -> str | None:
     """--board wins; else `[tool.bdt.ado].board` from pyproject.toml; else None."""
     return board or load_bdt_table("ado", start).get("board")
 
 
+def resolve_iteration(iteration: str | None, start: Path | None = None) -> str | None:
+    """--iteration wins; else `[tool.bdt.ado].iteration` from pyproject.toml; else None."""
+    return iteration or load_bdt_table("ado", start).get("iteration")
+
+
 def check_board(board: str | None, start: Path | None = None, *, creating: bool = False) -> str | None:
     """Enforce `[tool.bdt.ado]`'s `allowed_boards` / `require_board` on an already-resolved `board`
     (see `resolve_board`) and return the board to use, in the casing the config spells it.
@@ -127,6 +146,8 @@ def build_create_ops(
     description: str | None = None,
     area_path: str | None = None,
     tags: list[str] | None = None,
+    iteration_path: str | None = None,
+    relation_ops: list[dict] | None = None,
 ) -> list[dict]:
     """The JSON Patch document body for creating a work item with these fields."""
     ops = [{"op": "add", "path": "/fields/System.Title", "value": title}]
@@ -137,6 +158,46 @@ def build_create_ops(
         ops.append({"op": "add", "path": "/fields/System.AreaPath", "value": area_path})
     if tags:
         ops.append({"op": "add", "path": "/fields/System.Tags", "value": "; ".join(tags)})
+    if iteration_path:
+        ops.append({"op": "add", "path": "/fields/System.IterationPath", "value": iteration_path})
+    return [*ops, *(relation_ops or [])]
+
+
+def _work_item_api_url(remote: AdoRemote, work_item_id: int) -> str:
+    """What a relation's `url` must hold to point at a work item (not its web page)."""
+    return f"{_org_url(remote)}/_apis/wit/workItems/{work_item_id}"
+
+
+def _relation_target_id(relation: dict) -> int | None:
+    match = _WORK_ITEM_URL_ID_RE.search(relation.get("url") or "")
+    return int(match.group(1)) if match else None
+
+
+def build_relation_ops(
+    remote: AdoRemote,
+    parent: int | None = None,
+    blocked_by: list[int] | None = None,
+    existing: list[dict] | None = None,
+) -> list[dict]:
+    """JSON Patch ops linking a work item to its `parent` and to the work items blocking it
+    (`blocked_by`, its predecessors), skipping every link `existing` (the work item's current
+    `relations`, as `$expand=relations` returns them; none for a new work item) already has.
+
+    A work item has at most one parent, so setting a different one first removes the current link
+    (Azure DevOps rejects a second parent link) -- by its index in `existing`, which the `remove`
+    op addresses `/relations/` by.
+    """
+    existing = existing or []
+    ops: list[dict] = []
+    if parent is not None:
+        current = [(i, rel) for i, rel in enumerate(existing) if rel.get("rel") == PARENT_REL]
+        if not any(_relation_target_id(rel) == parent for _, rel in current):
+            ops += [{"op": "remove", "path": f"/relations/{i}"} for i, _ in reversed(current)]
+            ops.append({"op": "add", "path": "/relations/-", "value": {"rel": PARENT_REL, "url": _work_item_api_url(remote, parent)}})
+    already_blocked_by = {_relation_target_id(rel) for rel in existing if rel.get("rel") == BLOCKED_BY_REL}
+    for blocker in dict.fromkeys(blocked_by or []):
+        if blocker not in already_blocked_by:
+            ops.append({"op": "add", "path": "/relations/-", "value": {"rel": BLOCKED_BY_REL, "url": _work_item_api_url(remote, blocker)}})
     return ops
 
 
@@ -154,6 +215,8 @@ def build_update_ops(
     area_path: str | None = None,
     tags: list[str] | None = None,
     state: str | None = None,
+    iteration_path: str | None = None,
+    relation_ops: list[dict] | None = None,
 ) -> list[dict]:
     """The JSON Patch document body for updating a work item — only fields that aren't None are touched."""
     ops = []
@@ -168,7 +231,9 @@ def build_update_ops(
         ops.append({"op": "add", "path": "/fields/System.Tags", "value": "; ".join(tags)})
     if state is not None:
         ops.append({"op": "add", "path": "/fields/System.State", "value": state})
-    return ops
+    if iteration_path is not None:
+        ops.append({"op": "add", "path": "/fields/System.IterationPath", "value": iteration_path})
+    return [*ops, *(relation_ops or [])]
 
 
 def create_work_item(
@@ -179,8 +244,10 @@ def create_work_item(
     description: str | None = None,
     area_path: str | None = None,
     tags: list[str] | None = None,
+    iteration_path: str | None = None,
+    relation_ops: list[dict] | None = None,
 ) -> dict:
-    ops = build_create_ops(title, description, area_path, tags)
+    ops = build_create_ops(title, description, area_path, tags, iteration_path, relation_ops)
 
     r = session.post(
         f"{_base_url(remote)}/_apis/wit/workitems/${quote(work_item_type, safe='')}",
@@ -203,10 +270,12 @@ def update_work_item(
     area_path: str | None = None,
     tags: list[str] | None = None,
     state: str | None = None,
+    iteration_path: str | None = None,
+    relation_ops: list[dict] | None = None,
 ) -> dict:
-    ops = build_update_ops(title, description, area_path, tags, state)
+    ops = build_update_ops(title, description, area_path, tags, state, iteration_path, relation_ops)
     if not ops:
-        sys.exit("Nothing to update — provide at least one of --title, --description, --board, --tag, --state.")
+        sys.exit("Nothing to update — provide at least one of --title, --description, --board, --iteration, --tag, --state, --parent, --blocked-by.")
 
     r = session.patch(
         f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}",
@@ -243,6 +312,54 @@ def get_valid_states(session: requests.Session, remote: AdoRemote, work_item_typ
     return [s["name"] for s in r.json()["value"]]
 
 
+def get_work_item(session: requests.Session, remote: AdoRemote, work_item_id: int) -> dict:
+    """The whole work item, with its `relations` (links to other work items, attachments, PRs, ...)."""
+    r = session.get(
+        f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}",
+        params={"$expand": "relations", "api-version": "7.1"},
+    )
+    if r.status_code == 404:
+        sys.exit(f"Work item #{work_item_id} not found in project '{remote.project}'.")
+    r.raise_for_status()
+    return r.json()
+
+
+def get_details(session: requests.Session, remote: AdoRemote, work_item_id: int) -> IssueDetails:
+    """What `bdt issue show` prints for a work item: its fields, links and comments. Long text
+    (Description, comments) is HTML as stored; it is shown as plain text."""
+    work_item = get_work_item(session, remote, work_item_id)
+    fields = work_item.get("fields", {})
+    relations = work_item.get("relations") or []
+
+    def linked(rel: str) -> list[int]:
+        return [i for r in relations if r.get("rel") == rel and (i := _relation_target_id(r)) is not None]
+
+    assigned_to = fields.get("System.AssignedTo")
+    if isinstance(assigned_to, dict):
+        assigned_to = assigned_to.get("displayName")
+    parents = linked(PARENT_REL)
+    return IssueDetails(
+        number=work_item_id,
+        title=fields.get("System.Title", ""),
+        state=fields.get("System.State", ""),
+        url=edit_url(remote, work_item_id),
+        body=html_to_text(fields.get("System.Description") or ""),
+        tags=[t.strip() for t in (fields.get("System.Tags") or "").split(";") if t.strip()],
+        fields={
+            "Type": fields.get("System.WorkItemType"),
+            "Area": fields.get("System.AreaPath"),
+            "Iteration": fields.get("System.IterationPath"),
+            "Assigned to": assigned_to,
+        },
+        parent=parents[0] if parents else None,
+        children=linked(CHILD_REL),
+        blocked_by=linked(BLOCKED_BY_REL),
+        blocks=linked(BLOCKS_REL),
+        related=linked(RELATED_REL),
+        comments=to_comments(list_all_comments(session, remote, work_item_id), is_html=True),
+    )
+
+
 def get_work_item_tags(session: requests.Session, remote: AdoRemote, work_item_id: int) -> list[str]:
     r = session.get(
         f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}",
@@ -373,16 +490,38 @@ def list_comments(session: requests.Session, remote: AdoRemote, work_item_id: in
     )
     r.raise_for_status()
     url = edit_url(remote, work_item_id)
-    return [
-        {
-            "id": c["id"],
-            "author": (c.get("createdBy") or {}).get("displayName") or "unknown",
-            "created_at": c.get("createdDate") or "",
-            "url": url,
-            "body": c.get("text") or "",
-        }
-        for c in reversed(r.json().get("comments") or [])
-    ]
+    return [_comment_dict(c, url) for c in reversed(r.json().get("comments") or [])]
+
+
+def _comment_dict(comment: dict, url: str) -> dict:
+    return {
+        "id": comment["id"],
+        "author": (comment.get("createdBy") or {}).get("displayName") or "unknown",
+        "created_at": comment.get("createdDate") or "",
+        "url": url,
+        "body": comment.get("text") or "",
+    }
+
+
+def list_all_comments(session: requests.Session, remote: AdoRemote, work_item_id: int) -> list[dict]:
+    """Every comment on the work item, oldest first, as `list_comments` returns them -- which is
+    capped to the newest `_LIST_COMMENTS_TOP`, enough for a watcher but not for showing the item.
+    """
+    url = edit_url(remote, work_item_id)
+    comments: list[dict] = []
+    token: str | None = None
+    while True:
+        params = {"api-version": COMMENTS_API_VERSION, "$top": 200, "order": "asc"}
+        if token:
+            params["continuationToken"] = token
+        r = session.get(f"{_base_url(remote)}/_apis/wit/workItems/{work_item_id}/comments", params=params)
+        r.raise_for_status()
+        body = r.json()
+        comments += [_comment_dict(c, url) for c in body.get("comments") or []]
+        next_token = body.get("continuationToken")
+        if not next_token or next_token == token:
+            return comments
+        token = next_token
 
 
 def update_comment(session: requests.Session, remote: AdoRemote, work_item_id: int, comment_id: int, text: str) -> dict:
@@ -662,10 +801,14 @@ def create(
     tags: list[str],
     screenshot_paths: list[str],
     file_paths: list[str] | None = None,
+    iteration: str | None = None,
+    parent: int | None = None,
+    blocked_by: list[int] | None = None,
 ) -> dict:
     area_path = get_team_area_path(session, remote, board) if board else None
     description = ensure_agent_session_note(description, also_check=title)
-    work_item = create_work_item(session, remote, work_item_type, title, description, area_path, tags)
+    relation_ops = build_relation_ops(remote, parent, blocked_by)
+    work_item = create_work_item(session, remote, work_item_type, title, description, area_path, tags, iteration, relation_ops)
     work_item_id = work_item["id"]
 
     print(f"Created {work_item_type} #{work_item_id}: {title}")
@@ -689,10 +832,18 @@ def update(
     tags: list[str] | None = None,
     remove_tags: list[str] | None = None,
     state: str | None = None,
+    iteration: str | None = None,
+    parent: int | None = None,
+    blocked_by: list[int] | None = None,
 ) -> dict | None:
     """Update a work item's fields. Unlike `create`, `board` is only resolved (and the Area Path only
     touched) when explicitly given — it never falls back to `[tool.bdt.ado].board`, so an unrelated
     field update (e.g. just `--title`) can't silently move the item to a different team's board.
+    The same goes for `iteration` and `[tool.bdt.ado].iteration`.
+
+    `parent` / `blocked_by` link the work item to its parent / the work items blocking it, adding
+    only the links it doesn't have yet (see `build_relation_ops`) -- like `add_tag`, so running
+    the same update twice doesn't PATCH, or fail on, a link that is already there.
 
     `remove_tags` removes just those tags, leaving the rest untouched -- unlike `tags` (which
     replaces the whole `System.Tags` field, mirroring GitHub's `--remove-label` alongside the
@@ -729,11 +880,24 @@ def update(
             applied_state = None
 
     has_tag_change = tags is not None or bool(remove_tags)
-    if title is None and description is None and area_path is None and not has_tag_change and applied_state is None:
+    has_link_change = parent is not None or bool(blocked_by)
+    if (
+        title is None and description is None and area_path is None and iteration is None
+        and not has_tag_change and not has_link_change and applied_state is None
+    ):
         if state is not None:
             print(f"Work item #{work_item_id}: '{state}' isn't a valid state here — noted in a comment.")
             return None
-        sys.exit("Nothing to update — provide at least one of --title, --description, --board, --tag, --remove-tag, --state.")
+        sys.exit(
+            "Nothing to update — provide at least one of --title, --description, --board, --iteration, --tag, --remove-tag, "
+            "--state, --parent, --blocked-by."
+        )
+
+    relation_ops: list[dict] = []
+    if has_link_change:
+        if work_item_id == parent or work_item_id in (blocked_by or []):
+            sys.exit(f"Work item #{work_item_id} can't be linked to itself.")
+        relation_ops = build_relation_ops(remote, parent, blocked_by, get_work_item(session, remote, work_item_id).get("relations"))
 
     if remove_tags:
         removal_set = {t.casefold() for t in remove_tags}
@@ -746,7 +910,7 @@ def update(
             filtered_tags = [t for t in current_tags if t.casefold() not in removal_set]
             if filtered_tags != current_tags:
                 tags = filtered_tags
-            elif title is None and description is None and area_path is None and applied_state is None:
+            elif title is None and description is None and area_path is None and iteration is None and applied_state is None and not relation_ops:
                 # None of `remove_tags` were actually present, and nothing else was given either --
                 # mirrors `add_tag`'s own idempotency check (same file) so this doesn't needlessly
                 # bump the work item's revision/history with a same-value System.Tags PATCH.
@@ -755,10 +919,17 @@ def update(
             # else: leave `tags` as None -- other given fields still get their own ops below,
             # without forcing a redundant, unchanged System.Tags op alongside them.
 
+    if title is None and description is None and area_path is None and iteration is None and tags is None and applied_state is None and not relation_ops:
+        # only --parent / --blocked-by were given, and the work item already has those links
+        if state is not None:
+            print(f"Work item #{work_item_id}: '{state}' isn't a valid state here — noted in a comment.")
+        print(f"Work item #{work_item_id}: already linked as requested — nothing to do.")
+        return None
+
     if description is not None:
         description = ensure_agent_session_note(description, also_check=title)
 
-    work_item = update_work_item(session, remote, work_item_id, title, description, area_path, tags, applied_state)
+    work_item = update_work_item(session, remote, work_item_id, title, description, area_path, tags, applied_state, iteration, relation_ops)
     print(f"Updated work item #{work_item_id}")
     return work_item