bmsdna-devtools 0.2.2__tar.gz → 0.3.0__tar.gz

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.2.2
+Version: 0.3.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.11
 Requires-Dist: requests>=2.32.0
@@ -53,7 +53,7 @@ Exit code 1 either way.
 **Azure DevOps**: org/project/repo are auto-detected from
 `git remote get-url origin` (handles SSH, `dev.azure.com` HTTPS, and
 `*.visualstudio.com` HTTPS forms). Auth is an explicit PAT (`--pat` or
-`AZURE_DEVOPS_PAT` env var), falling back to a short-lived token from the
+`AZURE_DEVOPS_EXT_PAT`/`AZURE_DEVOPS_PAT` env var), falling back to a short-lived token from the
 caller's own `az login` — never embed a PAT literal in a script or CI file.
 `--target-branch` selects which PR to look at (ADO's search API needs one).
 

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/README.md

@@ -43,7 +43,7 @@ Exit code 1 either way.
 **Azure DevOps**: org/project/repo are auto-detected from
 `git remote get-url origin` (handles SSH, `dev.azure.com` HTTPS, and
 `*.visualstudio.com` HTTPS forms). Auth is an explicit PAT (`--pat` or
-`AZURE_DEVOPS_PAT` env var), falling back to a short-lived token from the
+`AZURE_DEVOPS_EXT_PAT`/`AZURE_DEVOPS_PAT` env var), falling back to a short-lived token from the
 caller's own `az login` — never embed a PAT literal in a script or CI file.
 `--target-branch` selects which PR to look at (ADO's search API needs one).
 

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/bmsdna/devtools/cli.py

@@ -2,8 +2,10 @@ from __future__ import annotations
 
 import subprocess
 import sys
+from collections.abc import Callable
 from pathlib import Path
 
+import requests
 import typer
 
 from . import app_service_logs, commit as commit_mod
@@ -11,8 +13,9 @@ from . import env_config
 from . import gh_pr
 from . import logs as logs_mod
 from . import pr_build, worktree as worktree_mod
+from .ado_auth import auth_header
 from .cli_tools import require_az, require_gh
-from .gitrepo import GitHubRemote, current_branch, current_remote
+from .gitrepo import AdoRemote, GitHubRemote, current_branch, current_remote
 
 # Non-ASCII output (checkmarks, en-dashes in ADO project names, etc.) needs a
 # UTF-8 stream — the default Windows console codepage isn't UTF-8, and would
@@ -30,28 +33,73 @@ logs_app = typer.Typer(name="logs", help="Application Insights / Log Analytics q
 app.add_typer(logs_app, name="logs")
 
 
+def _resolve_ado_pr(pat: str | None, remote: AdoRemote, source_branch: str, target: str) -> tuple[requests.Session, dict]:
+    session = requests.Session()
+    session.headers.update(auth_header(pat))
+    pr = pr_build.get_pr(session, remote, source_branch, target)
+    return session, pr
+
+
+def _attach_screenshots(attach: Callable[[], None]) -> None:
+    """Run an attach-screenshots step without letting its failure mask an already-successful `pr create`.
+
+    The PR itself is already live by the time this runs; a transient failure
+    here (a rejected push, an attachment upload error, a stale --target not
+    matching the PR ADO actually created) should surface as a warning, not
+    flip the whole command's exit code or hide the fact that the PR exists.
+    """
+    try:
+        attach()
+    except (Exception, SystemExit) as e:
+        print(f"Warning: PR created, but attaching screenshots failed: {e}")
+
+
 @pr_app.command("create")
 def pr_create(
     target: str = typer.Option("main", "--target", help="Target branch (e.g. main, test)"),
+    screenshot: list[str] = typer.Option(
+        [], "--screenshot", help="Path to an image to attach to the PR description (repeatable)"
+    ),
+    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)",
+    ),
     args: list[str] = typer.Argument(None, help="Extra args passed through to `az repos pr create` / `gh pr create`"),
 ) -> None:
     """Create a PR from the current branch into --target (Azure DevOps or GitHub, auto-detected)."""
+    for path in screenshot:
+        if not Path(path).is_file():
+            raise typer.BadParameter(f"Screenshot not found: {path}", param_hint="--screenshot")
+
     remote = current_remote()
+    source_branch = current_branch()
     if isinstance(remote, GitHubRemote):
         gh = require_gh()
         returncode = gh_pr.create(gh, target, args or [])
         build_policy = gh_pr.has_build_policy(gh, target)
+        if returncode == 0 and screenshot:
+            _attach_screenshots(lambda: gh_pr.add_screenshots(gh, remote.owner, remote.repo, source_branch, screenshot))
     else:
         az = require_az()
         cmd = [
             az, "repos", "pr", "create",
             "--target-branch", target,
-            "--source-branch", current_branch(),
+            "--source-branch", source_branch,
             "--auto-complete", "false",
             *(args or []),
         ]
         returncode = subprocess.run(cmd).returncode
-        build_policy = pr_build.has_build_policy(remote, target)
+        session = requests.Session()
+        session.headers.update(auth_header(pat))
+        build_policy = pr_build.has_build_policy(session, remote, target)
+        if returncode == 0 and screenshot:
+            def _add() -> None:
+                pr = pr_build.get_pr(session, remote, source_branch, target)
+                pr_build.add_screenshots(session, remote, pr, screenshot)
+
+            _attach_screenshots(_add)
 
     if returncode == 0 and build_policy:
         print("\nRun `bdt pr status` to check whether the CI build passes.")
@@ -63,7 +111,7 @@ def pr_create(
 def pr_status(
     target_branch: str = typer.Option("main", "--target-branch", help="Target branch of the PR (Azure DevOps only — gh has no equivalent filter, it always resolves the PR for the current branch)"),
     wait: bool = typer.Option(False, "--wait", help="Poll until all pipelines/checks are completed"),
-    pat: str | None = typer.Option(None, "--pat", envvar="AZURE_DEVOPS_PAT", help="Azure DevOps PAT (else falls back to `az` login)"),
+    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 build/check status for the PR opened from the current branch (Azure DevOps or GitHub, auto-detected)."""
     remote = current_remote()
@@ -73,6 +121,69 @@ def pr_status(
     pr_build.run(remote, pat, target_branch, wait)
 
 
+@pr_app.command("update")
+def pr_update(
+    title: str | None = typer.Option(None, "--title", help="New PR title"),
+    description: str | None = typer.Option(
+        None, "--description", help="New PR description (replaces the existing one)"
+    ),
+    screenshot: list[str] = typer.Option(
+        [], "--screenshot", help="Path to an image to append to the PR description (repeatable)"
+    ),
+    target: str = typer.Option("main", "--target", help="Target branch of the PR (Azure DevOps only)"),
+    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:
+    """Update the title/description of the PR opened from the current branch (Azure DevOps or GitHub, auto-detected)."""
+    for path in screenshot:
+        if not Path(path).is_file():
+            raise typer.BadParameter(f"Screenshot not found: {path}", param_hint="--screenshot")
+    if title is None and description is None and not screenshot:
+        raise typer.BadParameter("Provide at least one of --title, --description, --screenshot")
+
+    remote = current_remote()
+    source_branch = current_branch()
+    if isinstance(remote, GitHubRemote):
+        gh_pr.update(require_gh(), remote.owner, remote.repo, source_branch, title, description, screenshot)
+    else:
+        session, pr = _resolve_ado_pr(pat, remote, source_branch, target)
+        pr_build.update(session, remote, pr, title, description, screenshot)
+
+
+@pr_app.command("comment")
+def pr_comment(
+    message: str | None = typer.Option(None, "--message", help="Comment text"),
+    screenshot: list[str] = typer.Option(
+        [], "--screenshot", help="Path to an image to embed in the comment (repeatable)"
+    ),
+    target: str = typer.Option("main", "--target", help="Target branch of the PR (Azure DevOps only)"),
+    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:
+    """Post a comment on the PR opened from the current branch (Azure DevOps or GitHub, auto-detected)."""
+    for path in screenshot:
+        if not Path(path).is_file():
+            raise typer.BadParameter(f"Screenshot not found: {path}", param_hint="--screenshot")
+    if not message and not screenshot:
+        raise typer.BadParameter("Provide at least one of --message, --screenshot")
+
+    remote = current_remote()
+    source_branch = current_branch()
+    if isinstance(remote, GitHubRemote):
+        gh_pr.comment_with_screenshots(require_gh(), remote.owner, remote.repo, source_branch, message, screenshot)
+    else:
+        session, pr = _resolve_ado_pr(pat, remote, source_branch, target)
+        pr_build.comment_with_screenshots(session, remote, pr["pullRequestId"], message, screenshot)
+
+
 @app.command()
 def worktree(
     name: str,

bmsdna_devtools-0.3.0/bmsdna/devtools/gh_pr.py

@@ -0,0 +1,290 @@
+"""GitHub PR merge/check status and creation via the `gh` CLI.
+
+Deliberately avoids `gh pr checks --json` — that flag was only added in a
+later `gh` release than some machines still run (confirmed missing on gh
+2.45.0). Everything here is built on `gh pr view --json ...`, whose --json
+support has been stable for a long time, plus statusCheckRollup entries
+categorized ourselves using GitHub's documented GraphQL enums.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+from .pr_markdown import build_screenshots_section
+
+PR_VIEW_FIELDS = "number,title,baseRefName,mergeable,statusCheckRollup"
+
+# GitHub has no API for uploading images to a PR description (only the web
+# UI's drag-and-drop, which needs a browser session). The standard
+# workaround: keep screenshots on their own orphan branch, one folder per
+# source branch, and link to them with a raw blob URL.
+SCREENSHOTS_BRANCH = "pr-assets"
+
+# PullRequest.mergeable (GraphQL MergeableState).
+CONFLICTING = "CONFLICTING"
+UNKNOWN_MERGEABLE = "UNKNOWN"
+
+# statusCheckRollup entries are a union of CheckRun | StatusContext.
+# CheckRun.conclusion (GraphQL CheckConclusionState) -> bucket.
+_CHECK_RUN_BUCKET = {
+    "SUCCESS": "pass",
+    "NEUTRAL": "pass",
+    "SKIPPED": "skipping",
+    "CANCELLED": "cancel",
+    "FAILURE": "fail",
+    "TIMED_OUT": "fail",
+    "ACTION_REQUIRED": "fail",
+    "STALE": "fail",
+}
+# Legacy commit Status.state (GraphQL StatusState) -> bucket.
+_STATUS_CONTEXT_BUCKET = {
+    "SUCCESS": "pass",
+    "PENDING": "pending",
+    "EXPECTED": "pending",
+    "ERROR": "fail",
+    "FAILURE": "fail",
+}
+
+
+def _run_gh_json(gh: str, args: list[str]) -> dict:
+    r = subprocess.run([gh, *args], capture_output=True, encoding="utf-8")
+    if r.returncode != 0:
+        sys.exit((r.stderr or r.stdout).strip() or f"`gh {' '.join(args)}` failed")
+    return json.loads(r.stdout)
+
+
+def get_pr(gh: str) -> dict:
+    """The PR for the current branch, however `gh` resolves it — there's no
+    target-branch filter on `gh pr view` the way ADO's search API has one.
+    """
+    return _run_gh_json(gh, ["pr", "view", "--json", PR_VIEW_FIELDS])
+
+
+def check_bucket(check: dict) -> str:
+    if check.get("__typename") == "StatusContext":
+        return _STATUS_CONTEXT_BUCKET.get(check.get("state"), "pending")
+    if check.get("status") != "COMPLETED":
+        return "pending"
+    return _CHECK_RUN_BUCKET.get(check.get("conclusion"), "fail")
+
+
+def check_label(check: dict) -> str:
+    name = check.get("name", "?")
+    workflow = check.get("workflowName")
+    return f"{workflow} / {name}" if workflow and workflow not in name else name
+
+
+def merge_conflict_message(pr: dict) -> str | None:
+    if pr.get("mergeable") != CONFLICTING:
+        return None
+    return f"PR #{pr.get('number')} ({pr.get('title', '?')!r}) has merge conflicts with '{pr.get('baseRefName', '?')}' (mergeable=CONFLICTING)"
+
+
+def print_check(check: dict) -> None:
+    bucket = check_bucket(check)
+    icon = {"pass": "✓", "fail": "✗", "cancel": "⊘"}.get(bucket, "…")
+    print(f"  [{icon} {bucket.upper()}] {check_label(check)}")
+
+
+def run(gh: str, wait: bool) -> None:
+    last_line = ""
+    while True:
+        pr = get_pr(gh)
+
+        # GitHub hasn't finished computing mergeability yet (usually resolves
+        # within a couple seconds); worth a short wait even outside --wait mode
+        # isn't safe (could spin forever if it never resolves) — only retry
+        # when the caller already opted into waiting.
+        if pr.get("mergeable") == UNKNOWN_MERGEABLE and wait:
+            time.sleep(3)
+            continue
+
+        conflict = merge_conflict_message(pr)
+        if conflict:
+            sys.exit(conflict)
+
+        pr_number = pr.get("number")
+        title = pr.get("title", "?")
+        base = pr.get("baseRefName", "?")
+        msg = f"\rPR #{pr_number}: {title} (base={base})"
+
+        checks = pr.get("statusCheckRollup") or []
+        if not checks:
+            print(msg + " | no checks found.")
+            return
+
+        buckets = [check_bucket(c) for c in checks]
+        msg += " | " + ", ".join(f"{check_label(c)}: {check_bucket(c)}" for c in checks)
+
+        if "pending" in buckets and wait:
+            if msg != last_line:
+                print(msg, end="", flush=True)
+                last_line = msg
+            time.sleep(30)
+            continue
+
+        print(msg)
+        print("\nDetails:")
+        for c in checks:
+            print_check(c)
+
+        if "fail" in buckets:
+            sys.exit(1)
+        return
+
+
+def create(gh: str, target: str, extra_args: list[str]) -> int:
+    """Create a GitHub PR from the current branch into `target`.
+
+    --fill autofills title/body from commit info so this never blocks on an
+    interactive prompt; pass --title/--body in extra_args to override (gh
+    lets explicit values take precedence over --fill).
+    """
+    cmd = [gh, "pr", "create", "--base", target, "--fill", *extra_args]
+    return subprocess.run(cmd).returncode
+
+
+def _git(args: list[str], env: dict[str, str] | None = None) -> str:
+    r = subprocess.run(["git", *args], capture_output=True, encoding="utf-8", env=env)
+    if r.returncode != 0:
+        sys.exit((r.stderr or r.stdout).strip() or f"`git {' '.join(args)}` failed")
+    return r.stdout.strip()
+
+
+def push_screenshots(owner: str, repo: str, branch: str, paths: list[str], max_attempts: int = 5) -> list[str]:
+    """Push `paths` to a `<branch>/` folder on the `pr-assets` branch and return their raw blob URLs.
+
+    Built entirely from plumbing commands (hash-object/read-tree/write-tree/
+    commit-tree) against a throwaway index file, so nothing is checked out —
+    safe to call no matter what the current working tree looks like.
+
+    Tree paths are index-prefixed so two screenshots sharing a basename don't
+    overwrite each other. Retries on push rejection (another `pr create
+    --screenshot` moved the branch tip in the meantime) by re-fetching the new
+    tip and rebuilding the commit on top of it.
+    """
+    for attempt in range(1, max_attempts + 1):
+        remote_ref = subprocess.run(
+            ["git", "ls-remote", "origin", f"refs/heads/{SCREENSHOTS_BRANCH}"], capture_output=True, encoding="utf-8"
+        ).stdout.split()
+        parent = remote_ref[0] if remote_ref else None
+
+        with tempfile.TemporaryDirectory() as tmp:
+            env = {**os.environ, "GIT_INDEX_FILE": str(Path(tmp) / "index")}
+            if parent:
+                _git(["fetch", "origin", SCREENSHOTS_BRANCH], env=env)
+                _git(["read-tree", parent], env=env)
+
+            urls = []
+            for i, path in enumerate(paths):
+                blob_sha = _git(["hash-object", "-w", path])
+                tree_path = f"{branch}/{i:02d}-{Path(path).name}"
+                _git(["update-index", "--add", "--cacheinfo", f"100644,{blob_sha},{tree_path}"], env=env)
+                urls.append(f"https://github.com/{owner}/{repo}/blob/{SCREENSHOTS_BRANCH}/{tree_path}?raw=true")
+
+            tree_sha = _git(["write-tree"], env=env)
+
+        commit_args = ["commit-tree", tree_sha, "-m", f"screenshots: {branch}"]
+        if parent:
+            commit_args += ["-p", parent]
+        commit_sha = _git(commit_args)
+
+        push = subprocess.run(
+            ["git", "push", "origin", f"{commit_sha}:refs/heads/{SCREENSHOTS_BRANCH}"],
+            capture_output=True,
+            encoding="utf-8",
+        )
+        if push.returncode == 0:
+            return urls
+        if attempt == max_attempts:
+            sys.exit((push.stderr or push.stdout).strip() or "`git push` failed")
+
+    return []  # unreachable; loop always returns or exits
+
+
+def _screenshot_images(owner: str, repo: str, branch: str, screenshot_paths: list[str]) -> list[tuple[str, str]]:
+    urls = push_screenshots(owner, repo, branch, screenshot_paths)
+    return list(zip((Path(p).name for p in screenshot_paths), urls))
+
+
+def add_screenshots(gh: str, owner: str, repo: str, branch: str, screenshot_paths: list[str]) -> None:
+    """Push screenshots to the `pr-assets` branch and append them to the current branch's PR body."""
+    images = _screenshot_images(owner, repo, branch, screenshot_paths)
+    pr = _run_gh_json(gh, ["pr", "view", "--json", "number,body"])
+    body = build_screenshots_section(pr.get("body"), images)
+    r = subprocess.run([gh, "pr", "edit", str(pr["number"]), "--body", body], capture_output=True, encoding="utf-8")
+    if r.returncode != 0:
+        sys.exit((r.stderr or r.stdout).strip() or "`gh pr edit` failed")
+    print(f"Attached {len(screenshot_paths)} screenshot(s) to PR #{pr['number']}")
+
+
+def update(
+    gh: str,
+    owner: str,
+    repo: str,
+    branch: str,
+    title: str | None = None,
+    description: str | None = None,
+    screenshot_paths: list[str] | None = None,
+) -> None:
+    """Update a PR's title and/or body, optionally appending screenshots to the body."""
+    pr = _run_gh_json(gh, ["pr", "view", "--json", "number,body"])
+    args = [gh, "pr", "edit", str(pr["number"])]
+    if title:
+        args += ["--title", title]
+    if description is not None or screenshot_paths:
+        new_body: str = description if description is not None else (pr.get("body") or "")
+        if screenshot_paths:
+            new_body = build_screenshots_section(new_body, _screenshot_images(owner, repo, branch, screenshot_paths))
+        args += ["--body", new_body]
+    if len(args) == 3:
+        return
+    r = subprocess.run(args, capture_output=True, encoding="utf-8")
+    if r.returncode != 0:
+        sys.exit((r.stderr or r.stdout).strip() or "`gh pr edit` failed")
+    print(f"Updated PR #{pr['number']}")
+
+
+def comment_with_screenshots(gh: str, owner: str, repo: str, branch: str, message: str | None, screenshot_paths: list[str]) -> None:
+    """Post a comment, with a message and/or screenshots, on the current branch's PR."""
+    images = _screenshot_images(owner, repo, branch, screenshot_paths) if screenshot_paths else []
+    content = build_screenshots_section(message, images).strip() if images else (message or "")
+    r = subprocess.run([gh, "pr", "comment", "--body", content], capture_output=True, encoding="utf-8")
+    if r.returncode != 0:
+        sys.exit((r.stderr or r.stdout).strip() or "`gh pr comment` failed")
+    print(f"Added comment ({len(screenshot_paths)} screenshot(s)) to the current PR")
+
+
+def protection_requires_status_checks(protection: dict) -> bool:
+    """True if a branch's `.../protection` response requires status checks to pass."""
+    return bool(protection.get("required_status_checks"))
+
+
+def has_build_policy(gh: str, branch: str) -> bool:
+    """Best-effort check for whether `branch` has branch protection requiring status checks.
+
+    Only used to decide whether to print a `bdt pr status` reminder after
+    `pr create` — `{owner}`/`{repo}` are resolved by `gh` from the current
+    repo, and any failure (no permission to read protection settings, branch
+    not protected at all, etc.) fails open (returns False) rather than
+    blocking PR creation.
+    """
+    r = subprocess.run(
+        [gh, "api", f"repos/{{owner}}/{{repo}}/branches/{branch}/protection"],
+        capture_output=True,
+        encoding="utf-8",
+    )
+    if r.returncode != 0:
+        return False
+    try:
+        data = json.loads(r.stdout)
+    except json.JSONDecodeError:
+        return False
+    return protection_requires_status_checks(data)

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/bmsdna/devtools/pr_build.py

@@ -5,12 +5,14 @@ from __future__ import annotations
 import re
 import sys
 import time
+from pathlib import Path
 from urllib.parse import quote
 
 import requests
 
 from .ado_auth import auth_header
 from .gitrepo import AdoRemote, current_branch
+from .pr_markdown import build_screenshots_section
 
 # Matches an ISO 8601 timestamp at the start of a log line, e.g. 2024-03-21T15:01:23.1234567Z
 TIMESTAMP_RE = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s*")
@@ -55,7 +57,7 @@ def policy_configs_include_branch(configs: list, repo_id: str, branch: str, defa
     return False
 
 
-def has_build_policy(remote: AdoRemote, branch: str, pat: str | None = None) -> bool:
+def has_build_policy(session: requests.Session, remote: AdoRemote, branch: str) -> bool:
     """Best-effort check for whether `branch` has an enabled Build policy configured.
 
     Only used to decide whether to print a `bdt pr status` reminder after
@@ -63,9 +65,6 @@ def has_build_policy(remote: AdoRemote, branch: str, pat: str | None = None) ->
     (return False) rather than blocking PR creation.
     """
     try:
-        session = requests.Session()
-        session.headers.update(auth_header(pat))
-
         r = session.get(
             f"{_base_url(remote)}/_apis/git/repositories/{quote(remote.repo, safe='')}",
             params={"api-version": "7.1"},
@@ -119,6 +118,95 @@ def get_pr(session: requests.Session, remote: AdoRemote, source_branch: str, tar
     sys.exit(1)
 
 
+def upload_attachment(session: requests.Session, remote: AdoRemote, pr_id: int, attachment_name: str, file_path: str) -> str:
+    """Upload `file_path` as a pull request attachment named `attachment_name`; returns its download URL.
+
+    Embedding that URL in the PR description works because the browser
+    request for the image is same-origin (dev.azure.com) and carries the
+    viewer's own auth session/cookies — no separate hosting needed.
+    """
+    r = session.post(
+        f"{_base_url(remote)}/_apis/git/repositories/{quote(remote.repo, safe='')}"
+        f"/pullRequests/{pr_id}/attachments/{quote(attachment_name, safe='')}",
+        params={"api-version": "7.1"},
+        data=Path(file_path).read_bytes(),
+        headers={"Content-Type": "application/octet-stream"},
+    )
+    r.raise_for_status()
+    return r.json()["url"]
+
+
+def _upload_screenshots(session: requests.Session, remote: AdoRemote, pr_id: int, screenshot_paths: list[str]) -> list[tuple[str, str]]:
+    """Upload each screenshot as a PR attachment; returns (display name, 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, pr_id, f"{i:02d}-{Path(path).name}", path))
+        for i, path in enumerate(screenshot_paths)
+    ]
+
+
+def _patch_pr(session: requests.Session, remote: AdoRemote, pr_id: int, fields: dict) -> None:
+    r = session.patch(
+        f"{_base_url(remote)}/_apis/git/repositories/{quote(remote.repo, safe='')}/pullRequests/{pr_id}",
+        params={"api-version": "7.1"},
+        json=fields,
+    )
+    r.raise_for_status()
+
+
+def add_screenshots(session: requests.Session, remote: AdoRemote, pr: dict, screenshot_paths: list[str]) -> None:
+    """Upload each screenshot as a PR attachment and append them to the PR description."""
+    pr_id = pr["pullRequestId"]
+    images = _upload_screenshots(session, remote, pr_id, screenshot_paths)
+    _patch_pr(session, remote, pr_id, {"description": build_screenshots_section(pr.get("description"), images)})
+    print(f"Attached {len(screenshot_paths)} screenshot(s) to PR #{pr_id}")
+
+
+def update(
+    session: requests.Session,
+    remote: AdoRemote,
+    pr: dict,
+    title: str | None = None,
+    description: str | None = None,
+    screenshot_paths: list[str] | None = None,
+) -> None:
+    """Update a PR's title and/or description, optionally appending screenshots to the description."""
+    pr_id = pr["pullRequestId"]
+    fields: dict = {}
+    if title:
+        fields["title"] = title
+    if description is not None or screenshot_paths:
+        new_description = description if description is not None else pr.get("description")
+        if screenshot_paths:
+            new_description = build_screenshots_section(new_description, _upload_screenshots(session, remote, pr_id, screenshot_paths))
+        fields["description"] = new_description
+    if not fields:
+        return
+    _patch_pr(session, remote, pr_id, fields)
+    print(f"Updated PR #{pr_id}")
+
+
+def add_comment(session: requests.Session, remote: AdoRemote, pr_id: int, content: str) -> None:
+    """Post a new top-level comment thread on the PR."""
+    r = session.post(
+        f"{_base_url(remote)}/_apis/git/repositories/{quote(remote.repo, safe='')}/pullRequests/{pr_id}/threads",
+        params={"api-version": "7.1"},
+        json={"comments": [{"parentCommentId": 0, "content": content, "commentType": 1}], "status": 1},
+    )
+    r.raise_for_status()
+
+
+def comment_with_screenshots(session: requests.Session, remote: AdoRemote, pr_id: int, message: str | None, screenshot_paths: list[str]) -> None:
+    """Post a comment, with a message and/or screenshots, on the PR."""
+    images = _upload_screenshots(session, remote, pr_id, screenshot_paths) if screenshot_paths else []
+    content = build_screenshots_section(message, images).strip() if images else (message or "")
+    add_comment(session, remote, pr_id, content)
+    print(f"Added comment ({len(screenshot_paths)} screenshot(s)) to PR #{pr_id}")
+
+
 def get_builds_for_pr(session: requests.Session, remote: AdoRemote, source_branch: str, pr_id: int) -> list:
     builds = []
     for ref in [f"refs/pull/{pr_id}/merge", f"refs/heads/{source_branch}"]:

bmsdna_devtools-0.3.0/bmsdna/devtools/pr_markdown.py

@@ -0,0 +1,9 @@
+"""Markdown building shared by the Azure DevOps and GitHub screenshot-attach paths."""
+
+from __future__ import annotations
+
+
+def build_screenshots_section(existing_text: str | None, images: list[tuple[str, str]]) -> str:
+    """Append a '## Screenshots' markdown section of `images` (name, url) to `existing_text`."""
+    section = "\n".join(f"![{name}]({url})" for name, url in images)
+    return f"{existing_text or ''}\n\n## Screenshots\n\n{section}\n"

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/pyproject.toml

@@ -10,7 +10,7 @@ packages = ["bmsdna"]
 
 [project]
 name = "bmsdna-devtools"
-version = "0.2.2"
+version = "0.3.0"
 description = "Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects"
 readme = "README.md"
 requires-python = ">=3.11"

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/skills/bmsdna-devtools/SKILL.md

@@ -51,7 +51,7 @@ current branch regardless, so the flag is ignored there — the PR's actual
 base branch is shown in the output instead.
 
 Auth: Azure DevOps works with no setup if the caller is already `az
-login`'d (only pass `--pat`/`AZURE_DEVOPS_PAT` if there's no `az` session
+login`'d (only pass `--pat`/`AZURE_DEVOPS_EXT_PAT`/`AZURE_DEVOPS_PAT` if there's no `az` session
 available); GitHub uses whatever `gh auth login` session is active.
 
 ## Creating a PR

bmsdna_devtools-0.3.0/tests/test_pr_markdown.py

@@ -0,0 +1,13 @@
+from bmsdna.devtools.pr_markdown import build_screenshots_section
+
+
+def test_build_screenshots_section_appends_section_with_images() -> None:
+    text = build_screenshots_section("existing text", [("before.png", "https://x/1"), ("after.png", "https://x/2")])
+    assert text.startswith("existing text\n\n## Screenshots\n\n")
+    assert "![before.png](https://x/1)" in text
+    assert "![after.png](https://x/2)" in text
+
+
+def test_build_screenshots_section_handles_no_existing_text() -> None:
+    text = build_screenshots_section(None, [("shot.png", "https://x/1")])
+    assert text == "\n\n## Screenshots\n\n![shot.png](https://x/1)\n"

{bmsdna_devtools-0.2.2 → bmsdna_devtools-0.3.0}/uv.lock

@@ -13,7 +13,7 @@ wheels = [
 
 [[package]]
 name = "bmsdna-devtools"
-version = "0.2.2"
+version = "0.3.0"
 source = { editable = "." }
 dependencies = [
     { name = "requests" },

bmsdna_devtools-0.2.2/bmsdna/devtools/gh_pr.py

@@ -1,168 +0,0 @@
-"""GitHub PR merge/check status and creation via the `gh` CLI.
-
-Deliberately avoids `gh pr checks --json` — that flag was only added in a
-later `gh` release than some machines still run (confirmed missing on gh
-2.45.0). Everything here is built on `gh pr view --json ...`, whose --json
-support has been stable for a long time, plus statusCheckRollup entries
-categorized ourselves using GitHub's documented GraphQL enums.
-"""
-
-from __future__ import annotations
-
-import json
-import subprocess
-import sys
-import time
-
-PR_VIEW_FIELDS = "number,title,baseRefName,mergeable,statusCheckRollup"
-
-# PullRequest.mergeable (GraphQL MergeableState).
-CONFLICTING = "CONFLICTING"
-UNKNOWN_MERGEABLE = "UNKNOWN"
-
-# statusCheckRollup entries are a union of CheckRun | StatusContext.
-# CheckRun.conclusion (GraphQL CheckConclusionState) -> bucket.
-_CHECK_RUN_BUCKET = {
-    "SUCCESS": "pass",
-    "NEUTRAL": "pass",
-    "SKIPPED": "skipping",
-    "CANCELLED": "cancel",
-    "FAILURE": "fail",
-    "TIMED_OUT": "fail",
-    "ACTION_REQUIRED": "fail",
-    "STALE": "fail",
-}
-# Legacy commit Status.state (GraphQL StatusState) -> bucket.
-_STATUS_CONTEXT_BUCKET = {
-    "SUCCESS": "pass",
-    "PENDING": "pending",
-    "EXPECTED": "pending",
-    "ERROR": "fail",
-    "FAILURE": "fail",
-}
-
-
-def _run_gh_json(gh: str, args: list[str]) -> dict:
-    r = subprocess.run([gh, *args], capture_output=True, encoding="utf-8")
-    if r.returncode != 0:
-        sys.exit((r.stderr or r.stdout).strip() or f"`gh {' '.join(args)}` failed")
-    return json.loads(r.stdout)
-
-
-def get_pr(gh: str) -> dict:
-    """The PR for the current branch, however `gh` resolves it — there's no
-    target-branch filter on `gh pr view` the way ADO's search API has one.
-    """
-    return _run_gh_json(gh, ["pr", "view", "--json", PR_VIEW_FIELDS])
-
-
-def check_bucket(check: dict) -> str:
-    if check.get("__typename") == "StatusContext":
-        return _STATUS_CONTEXT_BUCKET.get(check.get("state"), "pending")
-    if check.get("status") != "COMPLETED":
-        return "pending"
-    return _CHECK_RUN_BUCKET.get(check.get("conclusion"), "fail")
-
-
-def check_label(check: dict) -> str:
-    name = check.get("name", "?")
-    workflow = check.get("workflowName")
-    return f"{workflow} / {name}" if workflow and workflow not in name else name
-
-
-def merge_conflict_message(pr: dict) -> str | None:
-    if pr.get("mergeable") != CONFLICTING:
-        return None
-    return f"PR #{pr.get('number')} ({pr.get('title', '?')!r}) has merge conflicts with '{pr.get('baseRefName', '?')}' (mergeable=CONFLICTING)"
-
-
-def print_check(check: dict) -> None:
-    bucket = check_bucket(check)
-    icon = {"pass": "✓", "fail": "✗", "cancel": "⊘"}.get(bucket, "…")
-    print(f"  [{icon} {bucket.upper()}] {check_label(check)}")
-
-
-def run(gh: str, wait: bool) -> None:
-    last_line = ""
-    while True:
-        pr = get_pr(gh)
-
-        # GitHub hasn't finished computing mergeability yet (usually resolves
-        # within a couple seconds); worth a short wait even outside --wait mode
-        # isn't safe (could spin forever if it never resolves) — only retry
-        # when the caller already opted into waiting.
-        if pr.get("mergeable") == UNKNOWN_MERGEABLE and wait:
-            time.sleep(3)
-            continue
-
-        conflict = merge_conflict_message(pr)
-        if conflict:
-            sys.exit(conflict)
-
-        pr_number = pr.get("number")
-        title = pr.get("title", "?")
-        base = pr.get("baseRefName", "?")
-        msg = f"\rPR #{pr_number}: {title} (base={base})"
-
-        checks = pr.get("statusCheckRollup") or []
-        if not checks:
-            print(msg + " | no checks found.")
-            return
-
-        buckets = [check_bucket(c) for c in checks]
-        msg += " | " + ", ".join(f"{check_label(c)}: {check_bucket(c)}" for c in checks)
-
-        if "pending" in buckets and wait:
-            if msg != last_line:
-                print(msg, end="", flush=True)
-                last_line = msg
-            time.sleep(30)
-            continue
-
-        print(msg)
-        print("\nDetails:")
-        for c in checks:
-            print_check(c)
-
-        if "fail" in buckets:
-            sys.exit(1)
-        return
-
-
-def create(gh: str, target: str, extra_args: list[str]) -> int:
-    """Create a GitHub PR from the current branch into `target`.
-
-    --fill autofills title/body from commit info so this never blocks on an
-    interactive prompt; pass --title/--body in extra_args to override (gh
-    lets explicit values take precedence over --fill).
-    """
-    cmd = [gh, "pr", "create", "--base", target, "--fill", *extra_args]
-    return subprocess.run(cmd).returncode
-
-
-def protection_requires_status_checks(protection: dict) -> bool:
-    """True if a branch's `.../protection` response requires status checks to pass."""
-    return bool(protection.get("required_status_checks"))
-
-
-def has_build_policy(gh: str, branch: str) -> bool:
-    """Best-effort check for whether `branch` has branch protection requiring status checks.
-
-    Only used to decide whether to print a `bdt pr status` reminder after
-    `pr create` — `{owner}`/`{repo}` are resolved by `gh` from the current
-    repo, and any failure (no permission to read protection settings, branch
-    not protected at all, etc.) fails open (returns False) rather than
-    blocking PR creation.
-    """
-    r = subprocess.run(
-        [gh, "api", f"repos/{{owner}}/{{repo}}/branches/{branch}/protection"],
-        capture_output=True,
-        encoding="utf-8",
-    )
-    if r.returncode != 0:
-        return False
-    try:
-        data = json.loads(r.stdout)
-    except json.JSONDecodeError:
-        return False
-    return protection_requires_status_checks(data)