bmsdna-devtools 0.4.0__tar.gz → 0.5.0__tar.gz

{bmsdna_devtools-0.4.0 → bmsdna_devtools-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.4.0
+Version: 0.5.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.11
 Requires-Dist: requests>=2.32.0
@@ -11,9 +11,10 @@ Description-Content-Type: text/markdown
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status, PR
-creation, git worktrees, a commit-and-push helper with pre-flight checks,
-and Azure log queries. `bdt pr *` auto-detects whether the current repo's
-`origin` remote is Azure DevOps or GitHub and uses `az`/`gh` accordingly.
+creation, issue/work item creation and comments, git worktrees, a
+commit-and-push helper with pre-flight checks, and Azure log queries.
+`bdt pr *` and `bdt issue *` auto-detect whether the current repo's `origin`
+remote is Azure DevOps or GitHub and use `az`/`gh` accordingly.
 Consolidates near-duplicate scripts that used to be copy-pasted across
 OneSales, ccmt2, and MDMApp into one versioned package with a `bdt` CLI.
 
@@ -83,6 +84,65 @@ 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`
+
+```bash
+bdt issue create --title "Nightly job fails" --description "..." --type Bug --screenshot before.png
+bdt issue update 1234 --state Resolved --tag fixed
+bdt issue delete 1234 --yes
+
+bdt issue comment add 1234 --message "Repro'd, see attached" --screenshot repro.png
+bdt issue comment update 1234 5678 --message "Actually, see the second screenshot"
+bdt issue comment delete 1234 5678 --yes
+```
+
+Creates/updates/deletes an issue (GitHub) or work item (Azure DevOps), and
+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.
+
+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.
+
+**Azure DevOps**: `--type` selects the work item type on `create` (`Bug`,
+`Task`, `User Story`, ... — whatever the project's process defines; default
+`Bug`). `--tag` sets/replaces the full tag list (repeatable; omit on
+`update` to leave tags unchanged). `--state` (`update` only) sets
+`System.State`, e.g. `Active`, `Resolved`, `Closed`. `--screenshot` uploads
+each image as a work item attachment (visible in the Attachments tab) and
+posts a comment embedding them inline with Markdown — the Description field
+defaults to HTML via the REST API, where a raw `![]()` would just show as
+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).
+
+`--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
+project's root area:
+
+```toml
+[tool.bdt.ado]
+board = "My Team"
+```
+
+On `update`, `--board` only moves the item when you pass it explicitly — it
+never falls back to `pyproject.toml`, so an unrelated field update (e.g.
+just `--title`) can't silently relocate the item to a different board.
+
+**GitHub**: a thin wrapper around `gh issue create` / `edit` / `delete` /
+`comment`. `--label` adds a label on `create`, or adds/removes one on
+`update` (paired with `--remove-label`); labels must already exist in the
+repo. `--screenshot` pushes images to a `pr-assets` branch (same trick `bdt
+pr create --screenshot` uses, since GitHub has no API for uploading an image
+into an issue) and appends them to the issue body / comment as Markdown.
+`issue delete` is **permanent** — GitHub has no recycle bin for issues.
+Comment update/delete go through `gh api` directly (`gh issue` has no
+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`.
+
 ## `bdt worktree`
 
 ```bash

{bmsdna_devtools-0.4.0 → bmsdna_devtools-0.5.0}/README.md

@@ -1,9 +1,10 @@
 # bmsdna-devtools
 
 Shared developer tooling for BMS projects: PR build/check status, PR
-creation, git worktrees, a commit-and-push helper with pre-flight checks,
-and Azure log queries. `bdt pr *` auto-detects whether the current repo's
-`origin` remote is Azure DevOps or GitHub and uses `az`/`gh` accordingly.
+creation, issue/work item creation and comments, git worktrees, a
+commit-and-push helper with pre-flight checks, and Azure log queries.
+`bdt pr *` and `bdt issue *` auto-detect whether the current repo's `origin`
+remote is Azure DevOps or GitHub and use `az`/`gh` accordingly.
 Consolidates near-duplicate scripts that used to be copy-pasted across
 OneSales, ccmt2, and MDMApp into one versioned package with a `bdt` CLI.
 
@@ -73,6 +74,65 @@ 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`
+
+```bash
+bdt issue create --title "Nightly job fails" --description "..." --type Bug --screenshot before.png
+bdt issue update 1234 --state Resolved --tag fixed
+bdt issue delete 1234 --yes
+
+bdt issue comment add 1234 --message "Repro'd, see attached" --screenshot repro.png
+bdt issue comment update 1234 5678 --message "Actually, see the second screenshot"
+bdt issue comment delete 1234 5678 --yes
+```
+
+Creates/updates/deletes an issue (GitHub) or work item (Azure DevOps), and
+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.
+
+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.
+
+**Azure DevOps**: `--type` selects the work item type on `create` (`Bug`,
+`Task`, `User Story`, ... — whatever the project's process defines; default
+`Bug`). `--tag` sets/replaces the full tag list (repeatable; omit on
+`update` to leave tags unchanged). `--state` (`update` only) sets
+`System.State`, e.g. `Active`, `Resolved`, `Closed`. `--screenshot` uploads
+each image as a work item attachment (visible in the Attachments tab) and
+posts a comment embedding them inline with Markdown — the Description field
+defaults to HTML via the REST API, where a raw `![]()` would just show as
+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).
+
+`--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
+project's root area:
+
+```toml
+[tool.bdt.ado]
+board = "My Team"
+```
+
+On `update`, `--board` only moves the item when you pass it explicitly — it
+never falls back to `pyproject.toml`, so an unrelated field update (e.g.
+just `--title`) can't silently relocate the item to a different board.
+
+**GitHub**: a thin wrapper around `gh issue create` / `edit` / `delete` /
+`comment`. `--label` adds a label on `create`, or adds/removes one on
+`update` (paired with `--remove-label`); labels must already exist in the
+repo. `--screenshot` pushes images to a `pr-assets` branch (same trick `bdt
+pr create --screenshot` uses, since GitHub has no API for uploading an image
+into an issue) and appends them to the issue body / comment as Markdown.
+`issue delete` is **permanent** — GitHub has no recycle bin for issues.
+Comment update/delete go through `gh api` directly (`gh issue` has no
+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`.
+
 ## `bdt worktree`
 
 ```bash

bmsdna_devtools-0.5.0/bmsdna/devtools/ado_issue.py

@@ -0,0 +1,314 @@
+"""Azure DevOps work items ("issues"): create/update/delete, comment
+add/update/delete, and screenshot support.
+
+Built directly on the Work Item Tracking REST API (api-version 7.1):
+  - Create:      POST    {org}/{project}/_apis/wit/workitems/${type}
+  - 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}
+  - 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
+                 even on the 7.1 line)
+
+Screenshots are handled in two steps, since the classic long-text fields
+(Description, Repro Steps, ...) default to HTML formatting via the REST API
+(Markdown is an explicit opt-in per field via `/multilineFieldsFormat/...`)
+while a raw `![name](url)` would just render as literal text there:
+  1. Upload each screenshot as an attachment and link it to the work item via
+     an "AttachedFile" relation, so it shows up in the Attachments tab.
+  2. Post/append a comment embedding the same images with Markdown `![]()`
+     syntax — the work item Discussion/Comments control has rendered
+     Markdown (including inline images) since it replaced the old HTML
+     System.History field, independent of the Description field's
+     HTML/Markdown toggle.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from urllib.parse import quote
+
+import requests
+
+from .bdt_config import load_bdt_table
+from .gitrepo import AdoRemote
+from .pr_markdown import build_screenshots_section
+
+COMMENTS_API_VERSION = "7.1-preview.4"
+
+
+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 _base_url(remote: AdoRemote) -> str:
+    return f"https://dev.azure.com/{quote(remote.org, safe='')}/{quote(remote.project, safe='')}"
+
+
+def get_team_area_path(session: requests.Session, remote: AdoRemote, team: str) -> str:
+    """The Area Path new work items need to be filed under to show up on `team`'s board."""
+    r = session.get(
+        f"{_base_url(remote)}/{quote(team, safe='')}/_apis/work/teamsettings/teamfieldvalues",
+        params={"api-version": "7.1"},
+    )
+    if r.status_code == 404:
+        sys.exit(f"Board/team '{team}' not found in project '{remote.project}'. Check --board / [tool.bdt.ado].board in pyproject.toml.")
+    r.raise_for_status()
+    return r.json()["defaultValue"]
+
+
+def build_create_ops(
+    title: str,
+    description: str | None = None,
+    area_path: str | None = None,
+    tags: list[str] | 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}]
+    if description:
+        ops.append({"op": "add", "path": "/fields/System.Description", "value": description})
+    if area_path:
+        ops.append({"op": "add", "path": "/fields/System.AreaPath", "value": area_path})
+    if tags:
+        ops.append({"op": "add", "path": "/fields/System.Tags", "value": "; ".join(tags)})
+    return ops
+
+
+def build_attach_ops(images: list[tuple[str, str]]) -> list[dict]:
+    """The JSON Patch document body for linking already-uploaded attachments via 'AttachedFile' relations."""
+    return [
+        {"op": "add", "path": "/relations/-", "value": {"rel": "AttachedFile", "url": url, "attributes": {"comment": name}}}
+        for name, url in images
+    ]
+
+
+def build_update_ops(
+    title: str | None = None,
+    description: str | None = None,
+    area_path: str | None = None,
+    tags: list[str] | None = None,
+    state: str | None = None,
+) -> list[dict]:
+    """The JSON Patch document body for updating a work item — only fields that aren't None are touched."""
+    ops = []
+    if title is not None:
+        ops.append({"op": "add", "path": "/fields/System.Title", "value": title})
+    if description is not None:
+        ops.append({"op": "add", "path": "/fields/System.Description", "value": description})
+    if area_path is not None:
+        ops.append({"op": "add", "path": "/fields/System.AreaPath", "value": area_path})
+    if tags is not None:
+        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
+
+
+def create_work_item(
+    session: requests.Session,
+    remote: AdoRemote,
+    work_item_type: str,
+    title: str,
+    description: str | None = None,
+    area_path: str | None = None,
+    tags: list[str] | None = None,
+) -> dict:
+    ops = build_create_ops(title, description, area_path, tags)
+
+    r = session.post(
+        f"{_base_url(remote)}/_apis/wit/workitems/${quote(work_item_type, safe='')}",
+        params={"api-version": "7.1"},
+        json=ops,
+        headers={"Content-Type": "application/json-patch+json"},
+    )
+    if r.status_code == 404:
+        sys.exit(f"Work item type '{work_item_type}' not found in project '{remote.project}'. Check --type.")
+    r.raise_for_status()
+    return r.json()
+
+
+def update_work_item(
+    session: requests.Session,
+    remote: AdoRemote,
+    work_item_id: int,
+    title: str | None = None,
+    description: str | None = None,
+    area_path: str | None = None,
+    tags: list[str] | None = None,
+    state: str | None = None,
+) -> dict:
+    ops = build_update_ops(title, description, area_path, tags, state)
+    if not ops:
+        sys.exit("Nothing to update — provide at least one of --title, --description, --board, --tag, --state.")
+
+    r = session.patch(
+        f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}",
+        params={"api-version": "7.1"},
+        json=ops,
+        headers={"Content-Type": "application/json-patch+json"},
+    )
+    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 delete_work_item(session: requests.Session, remote: AdoRemote, work_item_id: int) -> None:
+    """Soft-delete: moves the work item to the project's Recycle Bin, where it can be restored.
+
+    Deliberately doesn't expose the REST API's `destroy=true` option — that's
+    a permanent, unrecoverable delete, and there's no confirmation step that
+    makes that safe to offer from a CLI flag.
+    """
+    r = session.delete(f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}", params={"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()
+
+
+def upload_attachment(session: requests.Session, remote: AdoRemote, attachment_name: str, file_path: str) -> tuple[str, str]:
+    """Upload `file_path` as a work item attachment named `attachment_name`; returns (id, download url)."""
+    r = session.post(
+        f"{_base_url(remote)}/_apis/wit/attachments",
+        params={"fileName": attachment_name, "api-version": "7.1"},
+        data=Path(file_path).read_bytes(),
+        headers={"Content-Type": "application/octet-stream"},
+    )
+    r.raise_for_status()
+    body = r.json()
+    return body["id"], body["url"]
+
+
+def _upload_screenshots(session: requests.Session, remote: AdoRemote, screenshot_paths: list[str]) -> list[tuple[str, str]]:
+    """Upload each screenshot as an attachment; returns (display name, download url) pairs.
+
+    Attachment names are index-prefixed so two screenshots sharing a basename
+    (e.g. two 'before.png' from different folders) don't overwrite each other.
+    """
+    return [
+        (Path(path).name, upload_attachment(session, remote, f"{i:02d}-{Path(path).name}", path)[1])
+        for i, path in enumerate(screenshot_paths)
+    ]
+
+
+def link_attachments(session: requests.Session, remote: AdoRemote, work_item_id: int, images: list[tuple[str, str]]) -> None:
+    """Link already-uploaded attachments to a work item so they show up in its Attachments tab."""
+    ops = build_attach_ops(images)
+    r = session.patch(
+        f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}",
+        params={"api-version": "7.1"},
+        json=ops,
+        headers={"Content-Type": "application/json-patch+json"},
+    )
+    r.raise_for_status()
+
+
+def add_comment(session: requests.Session, remote: AdoRemote, work_item_id: int, text: str) -> dict:
+    r = session.post(
+        f"{_base_url(remote)}/_apis/wit/workItems/{work_item_id}/comments",
+        params={"api-version": COMMENTS_API_VERSION},
+        json={"text": text},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def update_comment(session: requests.Session, remote: AdoRemote, work_item_id: int, comment_id: int, text: str) -> dict:
+    r = session.patch(
+        f"{_base_url(remote)}/_apis/wit/workItems/{work_item_id}/comments/{comment_id}",
+        params={"api-version": COMMENTS_API_VERSION},
+        json={"text": text},
+    )
+    if r.status_code == 404:
+        sys.exit(f"Comment #{comment_id} not found on work item #{work_item_id}.")
+    r.raise_for_status()
+    print(f"Updated comment #{comment_id} on work item #{work_item_id}")
+    return r.json()
+
+
+def delete_comment(session: requests.Session, remote: AdoRemote, work_item_id: int, comment_id: int) -> None:
+    r = session.delete(
+        f"{_base_url(remote)}/_apis/wit/workItems/{work_item_id}/comments/{comment_id}",
+        params={"api-version": COMMENTS_API_VERSION},
+    )
+    if r.status_code == 404:
+        sys.exit(f"Comment #{comment_id} not found on work item #{work_item_id}.")
+    r.raise_for_status()
+    print(f"Deleted comment #{comment_id} on work item #{work_item_id}")
+
+
+def add_screenshots(session: requests.Session, remote: AdoRemote, work_item_id: int, screenshot_paths: list[str]) -> None:
+    """Upload+link screenshots as attachments, then post a comment embedding them (Markdown)."""
+    images = _upload_screenshots(session, remote, screenshot_paths)
+    link_attachments(session, remote, work_item_id, images)
+    comment = add_comment(session, remote, work_item_id, build_screenshots_section(None, images).strip())
+    print(f"Attached {len(screenshot_paths)} screenshot(s) to work item #{work_item_id} (comment #{comment['id']})")
+
+
+def comment_with_screenshots(session: requests.Session, remote: AdoRemote, work_item_id: int, message: str | None, screenshot_paths: list[str]) -> dict:
+    """Post a comment, with a message and/or screenshots, on the work item."""
+    images = _upload_screenshots(session, remote, screenshot_paths) if screenshot_paths else []
+    if images:
+        link_attachments(session, remote, work_item_id, images)
+    content = build_screenshots_section(message, images).strip() if images else (message or "")
+    comment = add_comment(session, remote, work_item_id, content)
+    print(f"Added comment #{comment['id']} ({len(screenshot_paths)} screenshot(s)) to work item #{work_item_id}")
+    return comment
+
+
+def html_url(work_item: dict) -> str | None:
+    return work_item.get("_links", {}).get("html", {}).get("href")
+
+
+def create(
+    session: requests.Session,
+    remote: AdoRemote,
+    work_item_type: str,
+    title: str,
+    description: str | None,
+    board: str | None,
+    tags: list[str],
+    screenshot_paths: list[str],
+) -> dict:
+    area_path = get_team_area_path(session, remote, board) if board else None
+    work_item = create_work_item(session, remote, work_item_type, title, description, area_path, tags)
+    work_item_id = work_item["id"]
+
+    print(f"Created {work_item_type} #{work_item_id}: {title}")
+    url = html_url(work_item)
+    if url:
+        print(url)
+
+    if screenshot_paths:
+        add_screenshots(session, remote, work_item_id, screenshot_paths)
+
+    return work_item
+
+
+def update(
+    session: requests.Session,
+    remote: AdoRemote,
+    work_item_id: int,
+    title: str | None = None,
+    description: str | None = None,
+    board: str | None = None,
+    tags: list[str] | None = None,
+    state: str | None = None,
+) -> dict:
+    """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.
+    """
+    area_path = get_team_area_path(session, remote, board) if board else None
+    work_item = update_work_item(session, remote, work_item_id, title, description, area_path, tags, state)
+    print(f"Updated work item #{work_item_id}")
+    return work_item
+
+
+def delete(session: requests.Session, remote: AdoRemote, work_item_id: int) -> None:
+    delete_work_item(session, remote, work_item_id)
+    print(f"Deleted work item #{work_item_id} (moved to the Recycle Bin — restorable)")

bmsdna_devtools-0.5.0/bmsdna/devtools/bdt_config.py

@@ -0,0 +1,29 @@
+"""Shared lookup for `[tool.bdt.*]` configuration tables in the consuming
+repo's pyproject.toml (walks up from a start directory the same way `git`
+looks for `.git`, so it works from any subdirectory of the repo).
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+
+def find_pyproject(start: Path | None = None) -> Path | None:
+    start = start or Path.cwd()
+    for directory in (start, *start.parents):
+        candidate = directory / "pyproject.toml"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def load_bdt_table(key: str, start: Path | None = None) -> dict:
+    """Load the `[tool.bdt.<key>]` table (e.g. `key="envs"` -> `[tool.bdt.envs]`)."""
+    path = find_pyproject(start)
+    if path is None:
+        return {}
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+    value = data.get("tool", {}).get("bdt", {}).get(key, {})
+    return value if isinstance(value, dict) else {}