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

bmsdna_devtools-0.40.0/README.md → bmsdna_devtools-0.41.0/PKG-INFO

@@ -1,3 +1,17 @@
+Metadata-Version: 2.5
+Name: bmsdna-devtools
+Version: 0.41.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
+Requires-Dist: requests>=2.32.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: typer>=0.26.7
+Provides-Extra: lint
+Requires-Dist: sqlglot>=27.0.0; extra == 'lint'
+Description-Content-Type: text/markdown
+
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
@@ -233,11 +247,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 +267,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 +304,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 +354,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/PKG-INFO → bmsdna_devtools-0.41.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.5
-Name: bmsdna-devtools
-Version: 0.40.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
-Requires-Dist: requests>=2.32.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: tomli-w>=1.0.0
-Requires-Dist: typer>=0.26.7
-Provides-Extra: lint
-Requires-Dist: sqlglot>=27.0.0; extra == 'lint'
-Description-Content-Type: text/markdown
-
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status and a
@@ -247,11 +233,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 +253,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 +290,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 +340,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.41.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
 

{bmsdna_devtools-0.40.0 → bmsdna_devtools-0.41.0}/bmsdna/devtools/cli.py

@@ -26,6 +26,7 @@ from . import find_repo as find_repo_mod
 from . import issue_do as issue_do_mod
 from . import issue_watch as issue_watch_mod
 from . import gh_issue, gh_pr
+from . import issue_show as issue_show_mod
 from . import find_injection as find_injection_mod
 from . import lint as lint_mod
 from . import logs as logs_mod
@@ -211,6 +212,15 @@ def _merge_tags_and_labels(tag: list[str] | None, label: list[str] | None) -> li
     return merged
 
 
+def _reject_ado_only_options(**options: object) -> None:
+    """GitHub has no counterpart of these `issue create/update` options (Azure DevOps only): fail up front
+    instead of silently dropping them."""
+    for name, value in options.items():
+        if value:
+            flag = "--" + name.replace("_", "-")
+            raise typer.BadParameter(f"{flag} is only supported for Azure DevOps work items, not GitHub issues.", param_hint=flag)
+
+
 def _link_and_label_github(gh: str, remote: GitHubRemote, issue_numbers: list[int]) -> None:
     """Link every issue in `issue_numbers`, plus every issue `find_issue_refs_in_body` finds in
     the PR's actual body, to the current branch's PR, and label each `pr-available`.
@@ -653,6 +663,18 @@ def issue_create(
     file: list[str] = typer.Option(
         [], "--file", help="Path to an arbitrary file to attach to the issue / work item as a linked attachment (repeatable)"
     ),
+    iteration: str | None = typer.Option(
+        None,
+        "--iteration",
+        help=r"Iteration (sprint) Path to set, e.g. 'MyProject\Sprint 1' (Azure DevOps only; overrides \[tool.bdt.ado].iteration "
+        "in pyproject.toml). Work items without one don't show on the team backlog in Basic-process projects.",
+    ),
+    parent: int | None = typer.Option(
+        None, "--parent", help="Make the new issue / work item a child (sub-issue) of this issue / work item ID"
+    ),
+    blocked_by: list[int] = typer.Option(
+        [], "--blocked-by", help="Issue / work item ID blocking the new one -- its predecessor on Azure DevOps (repeatable)"
+    ),
     pat: str | None = typer.Option(
         None,
         "--pat",
@@ -672,15 +694,20 @@ def issue_create(
     tags_or_labels = _merge_tags_and_labels(tag, label) or []
     remote = current_remote()
     if isinstance(remote, GitHubRemote):
+        _reject_ado_only_options(iteration=iteration)
         resolved_board = gh_issue.resolve_board(board)
         gh_issue.create(
-            require_gh(), remote.owner, remote.repo, title, description, tags_or_labels, screenshot, args or [], file_paths=file, board=resolved_board
+            require_gh(), remote.owner, remote.repo, title, description, tags_or_labels, screenshot, args or [], file_paths=file, board=resolved_board,
+            parent=parent, blocked_by=blocked_by,
         )
     else:
         session = requests.Session()
         session.headers.update(auth_header(pat))
         resolved_board = ado_issue.check_board(ado_issue.resolve_board(board), creating=True)
-        ado_issue.create(session, remote, type_, title, description, resolved_board, tags_or_labels, screenshot, file)
+        ado_issue.create(
+            session, remote, type_, title, description, resolved_board, tags_or_labels, screenshot, file,
+            iteration=ado_issue.resolve_iteration(iteration), parent=parent, blocked_by=blocked_by,
+        )
 
 
 @issue_app.command("search")
@@ -1131,6 +1158,30 @@ issue_app.command("watch")(issue_watch)
 app.command("watch-issue", help="Alias for `bdt issue watch`")(issue_watch)
 
 
+@issue_app.command("show")
+def issue_show(
+    number: int = typer.Argument(..., help="Issue number (GitHub) or work item ID (Azure DevOps)"),
+    as_json: bool = typer.Option(False, "--json", help="Print one JSON document instead of text"),
+    pat: str | None = typer.Option(
+        None,
+        "--pat",
+        envvar=["AZURE_DEVOPS_EXT_PAT", "AZURE_DEVOPS_PAT"],
+        help="Azure DevOps PAT (else falls back to `az` login)",
+    ),
+) -> None:
+    """Show an issue / work item (Azure DevOps or GitHub, auto-detected): state, title, description, tags,
+    area / iteration (Azure DevOps), links to other issues / work items (parent, children, blocked by, blocks) and comments.
+    """
+    remote = current_remote()
+    if isinstance(remote, GitHubRemote):
+        details = gh_issue.get_details(require_gh(), remote.owner, remote.repo, number)
+    else:
+        session = requests.Session()
+        session.headers.update(auth_header(pat))
+        details = ado_issue.get_details(session, remote, number)
+    typer.echo(issue_show_mod.format_details(details, as_json=as_json))
+
+
 @issue_app.command("update")
 def issue_update(
     number: int = typer.Argument(..., help="Issue number (GitHub) or work item ID (Azure DevOps)"),
@@ -1170,6 +1221,20 @@ def issue_update(
     remove_label: list[str] | None = typer.Option(
         None, "--remove-label", help="Tag/label to remove (repeatable). Alias for --remove-tag."
     ),
+    iteration: str | None = typer.Option(
+        None,
+        "--iteration",
+        help=r"Move the work item to this Iteration (sprint) Path, e.g. 'MyProject\Sprint 1' (Azure DevOps only). Like --board, "
+        r"only applied when given here -- it does not fall back to \[tool.bdt.ado].iteration.",
+    ),
+    parent: int | None = typer.Option(
+        None,
+        "--parent",
+        help="Make this issue / work item a child (sub-issue) of this issue / work item ID; on Azure DevOps, replaces its current parent",
+    ),
+    blocked_by: list[int] = typer.Option(
+        [], "--blocked-by", help="Issue / work item ID blocking this one -- its predecessor on Azure DevOps (repeatable). Already-set links are left alone."
+    ),
     pat: str | None = typer.Option(
         None,
         "--pat",
@@ -1182,11 +1247,15 @@ def issue_update(
     removals = _merge_tags_and_labels(remove_tag, remove_label)
     remote = current_remote()
     if isinstance(remote, GitHubRemote):
-        gh_issue.update(require_gh(), number, title, description, tags_or_labels, removals, state)
+        _reject_ado_only_options(iteration=iteration)
+        gh_issue.update(require_gh(), number, title, description, tags_or_labels, removals, state, parent, blocked_by)
     else:
         session = requests.Session()
         session.headers.update(auth_header(pat))
-        ado_issue.update(session, remote, number, title, description, ado_issue.check_board(board), tags_or_labels, removals, state)
+        ado_issue.update(
+            session, remote, number, title, description, ado_issue.check_board(board), tags_or_labels, removals, state,
+            iteration=iteration, parent=parent, blocked_by=blocked_by,
+        )
 
 
 @issue_app.command("delete")