bmsdna-devtools 0.44.0__tar.gz → 0.46.0__tar.gz

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.44.0
+Version: 0.46.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: azure-identity>=1.19.0
@@ -122,7 +122,7 @@ it watches a branch-triggered build/workflow run, not any particular PR.)
 ## `bdt pr info`
 
 ```bash
-bdt pr info [--json] [--pr-id N] [--target-branch BRANCH]
+bdt pr info [--json] [--pr-id PR]... [--target-branch BRANCH] [--all]
 ```
 
 One-shot summary of the current branch's PR: link, state (open/merged/closed, draft), aggregate
@@ -133,6 +133,24 @@ the check rollup (only a failed check fails it; skipped/cancelled ones don't cou
 from the latest build of each pipeline (any failed result fails it; unfinished builds are pending, or
 `waiting` when a stage needs approval). `unknown` if Azure DevOps can't be asked.
 
+`--all` lists every open PR from the current branch (e.g. one into `dev` and one into `main`, which plain
+`bdt pr info` refuses to pick between): with `--json` an array of the same objects, `[]` (exit 0) when there is
+none; `--target-branch` narrows it, `--pr-id` can't be combined with it. Only open PRs are listed, and a PR with
+merge conflicts is listed like any other (plain `pr info` on Azure DevOps errors on it).
+
+`--pr-id` takes several PRs, also of other repos: repeat it and/or comma-separate (`--pr-id 12,34 --pr-id owner/repo#5`).
+Each entry is a bare number (a PR of the current repo), `owner/repo#N` (GitHub), `project/repo#N` or
+`org/project/repo#N` (Azure DevOps; the host is the current repo's, and the org is its org unless given), or the PR's
+URL (GitHub, `dev.azure.com` or `*.visualstudio.com`; the only form that needs no git checkout). One plain number
+behaves as before: the single object. One `owner/repo#N` is a single object too; two or more entries print a list in the
+order given (duplicates once), as `--json` an array like `--all`'s, as text with the repo in each header. A failing entry
+(unknown number, no access) doesn't hide the others: it is reported as `error: <entry>: <reason>` on stderr, the rest is
+still printed, and the exit code is 1. An unreadable entry is a usage error before anything is looked up. `--pr-id` can't
+be combined with `--all`; `--target-branch` is ignored for it, as before. Azure DevOps entries use one PAT/`az login` for
+every org, and a PR with merge conflicts is an error entry there.
+
+Every JSON object has a `repo` (`owner/repo` on GitHub, `org/project/repo` on Azure DevOps).
+
 Azure DevOps limits: the PR is found by the current branch (into `--target-branch` if given, else any target),
 a PR with merge conflicts is reported as an error (exit 1) like `pr status` does, and the closed
 work items are only those whose URL is in the PR description -- not ones linked via
@@ -283,6 +301,15 @@ 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 pr comment`
+
+```bash
+bdt pr comment --message "Looks good" [--screenshot shot.png] [--file report.pdf] [--pr-id 123]
+bdt pr comment --message-file plan.md          # post a file's text as the comment (`-` = stdin)
+```
+
+Use `--message-file` to post a markdown document (an implementation plan, review findings) as the comment.
+
 ## `bdt issue create` / `show` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
 
 ```bash
@@ -559,7 +586,9 @@ scan_jinja = ["backend/print"]         # "KEY" | tr in .jinja2/.j2/.html
 bdt worktree my-feature [--base dev] [--env-file .local_env] [--no-submodules] [--install "just install"]
 ```
 
-Creates `.worktrees/<name>` branched from `--base`, initializes submodules
+Creates `.worktrees/<name>` branched from `--base`. It first fetches `origin/<base>` and, if the local
+`<base>` is strictly behind it, branches from `origin/<base>` instead (so the PR starts on current code);
+a local base that is ahead of or has diverged from the remote is kept as is. Then it initializes submodules
 (unless `--no-submodules`), and copies an env file into the new worktree as
 `.env` (auto-detects `.local_env` then `.env` if `--env-file` isn't given).
 

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/README.md

@@ -104,7 +104,7 @@ it watches a branch-triggered build/workflow run, not any particular PR.)
 ## `bdt pr info`
 
 ```bash
-bdt pr info [--json] [--pr-id N] [--target-branch BRANCH]
+bdt pr info [--json] [--pr-id PR]... [--target-branch BRANCH] [--all]
 ```
 
 One-shot summary of the current branch's PR: link, state (open/merged/closed, draft), aggregate
@@ -115,6 +115,24 @@ the check rollup (only a failed check fails it; skipped/cancelled ones don't cou
 from the latest build of each pipeline (any failed result fails it; unfinished builds are pending, or
 `waiting` when a stage needs approval). `unknown` if Azure DevOps can't be asked.
 
+`--all` lists every open PR from the current branch (e.g. one into `dev` and one into `main`, which plain
+`bdt pr info` refuses to pick between): with `--json` an array of the same objects, `[]` (exit 0) when there is
+none; `--target-branch` narrows it, `--pr-id` can't be combined with it. Only open PRs are listed, and a PR with
+merge conflicts is listed like any other (plain `pr info` on Azure DevOps errors on it).
+
+`--pr-id` takes several PRs, also of other repos: repeat it and/or comma-separate (`--pr-id 12,34 --pr-id owner/repo#5`).
+Each entry is a bare number (a PR of the current repo), `owner/repo#N` (GitHub), `project/repo#N` or
+`org/project/repo#N` (Azure DevOps; the host is the current repo's, and the org is its org unless given), or the PR's
+URL (GitHub, `dev.azure.com` or `*.visualstudio.com`; the only form that needs no git checkout). One plain number
+behaves as before: the single object. One `owner/repo#N` is a single object too; two or more entries print a list in the
+order given (duplicates once), as `--json` an array like `--all`'s, as text with the repo in each header. A failing entry
+(unknown number, no access) doesn't hide the others: it is reported as `error: <entry>: <reason>` on stderr, the rest is
+still printed, and the exit code is 1. An unreadable entry is a usage error before anything is looked up. `--pr-id` can't
+be combined with `--all`; `--target-branch` is ignored for it, as before. Azure DevOps entries use one PAT/`az login` for
+every org, and a PR with merge conflicts is an error entry there.
+
+Every JSON object has a `repo` (`owner/repo` on GitHub, `org/project/repo` on Azure DevOps).
+
 Azure DevOps limits: the PR is found by the current branch (into `--target-branch` if given, else any target),
 a PR with merge conflicts is reported as an error (exit 1) like `pr status` does, and the closed
 work items are only those whose URL is in the PR description -- not ones linked via
@@ -265,6 +283,15 @@ 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 pr comment`
+
+```bash
+bdt pr comment --message "Looks good" [--screenshot shot.png] [--file report.pdf] [--pr-id 123]
+bdt pr comment --message-file plan.md          # post a file's text as the comment (`-` = stdin)
+```
+
+Use `--message-file` to post a markdown document (an implementation plan, review findings) as the comment.
+
 ## `bdt issue create` / `show` / `update` / `delete`, `bdt issue comment add` / `update` / `delete`
 
 ```bash
@@ -541,7 +568,9 @@ scan_jinja = ["backend/print"]         # "KEY" | tr in .jinja2/.j2/.html
 bdt worktree my-feature [--base dev] [--env-file .local_env] [--no-submodules] [--install "just install"]
 ```
 
-Creates `.worktrees/<name>` branched from `--base`, initializes submodules
+Creates `.worktrees/<name>` branched from `--base`. It first fetches `origin/<base>` and, if the local
+`<base>` is strictly behind it, branches from `origin/<base>` instead (so the PR starts on current code);
+a local base that is ahead of or has diverged from the remote is kept as is. Then it initializes submodules
 (unless `--no-submodules`), and copies an env file into the new worktree as
 `.env` (auto-detects `.local_env` then `.env` if `--env-file` isn't given).
 

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/bdt_config.py

@@ -1,6 +1,8 @@
 """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).
+looks for `.git`, so it works from any subdirectory of the repo). The walk stops at the
+repository root (the first directory holding a `.git` dir or file), so a submodule or nested
+repo never picks up the config of the repo that contains it.
 """
 
 from __future__ import annotations
@@ -15,6 +17,8 @@ def find_pyproject(start: Path | None = None) -> Path | None:
         candidate = directory / "pyproject.toml"
         if candidate.is_file():
             return candidate
+        if (directory / ".git").exists():
+            return None
     return None
 
 

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/cli.py

@@ -32,7 +32,7 @@ from . import find_injection as find_injection_mod
 from . import lint as lint_mod
 from . import logs as logs_mod
 from . import translate as translate_mod
-from . import pr_build, pr_info as pr_info_mod, pr_issue_link, pr_labels, pull as pull_mod, worktree as worktree_mod
+from . import pr_build, pr_info as pr_info_mod, pr_issue_link, pr_ref, pr_labels, pull as pull_mod, worktree as worktree_mod
 from .ado_auth import auth_header
 from .bdt_config import find_pyproject, load_bdt_table
 from .cli_tools import CLI_TIMEOUT_SECS, EXIT_WAIT_TIMEOUT, detect_agent_session, require_gh
@@ -42,6 +42,7 @@ from .usage.cli import usage_app
 from .gitrepo import (
     AdoRemote,
     GitHubRemote,
+    NotAzureDevOpsRemoteError,
     NotGitHubRemoteError,
     UnknownRemoteError,
     current_branch,
@@ -170,6 +171,69 @@ def _current_pr_info(pr_id: int | None, target_branch: str | None, pat: str | No
     return pr_info_mod.ado_info(session, pr, remote)
 
 
+def _open_prs_info(target_branch: str | None, pat: str | None) -> list[pr_info_mod.PrInfo]:
+    """`_current_pr_info` for every open PR from the current branch, `[]` if there is none."""
+    remote = current_remote()
+    if isinstance(remote, GitHubRemote):
+        gh = require_gh()
+        return [
+            pr_info_mod.github_info(gh_pr.get_pr(gh, number, fields=gh_pr.PR_INFO_FIELDS), remote)
+            for number in gh_pr.open_pr_numbers(gh, target_branch)
+        ]
+    session = requests.Session()
+    session.headers.update(auth_header(pat))
+    return [pr_info_mod.ado_info(session, pr, remote) for pr in pr_build.get_active_prs(session, remote, current_branch(), target_branch)]
+
+
+_REMOTE_ERRORS = (UnknownRemoteError, NotGitHubRemoteError, NotAzureDevOpsRemoteError)
+
+
+def _current_remote_or_none() -> AdoRemote | GitHubRemote | None:
+    """The current repo's remote, or None outside a checkout -- without git's own complaint, as that is no error here."""
+    r = subprocess.run(["git", "remote", "get-url", "origin"], capture_output=True, encoding="utf-8")
+    if r.returncode != 0:
+        return None
+    try:
+        return parse_remote(r.stdout.strip())
+    except _REMOTE_ERRORS:
+        return None
+
+
+def _ref_pr_info(ref: pr_ref.PrRef, pat: str | None, clients: dict) -> pr_info_mod.PrInfo:
+    """The PR `ref` names, in its own repo (the current one for a bare number). `clients` caches the GitHub client
+    and Azure DevOps session across the entries of one call, so the token and auth are looked up once."""
+    remote = ref.remote or current_remote()
+    if isinstance(remote, GitHubRemote):
+        if "gh" not in clients:
+            clients["gh"] = require_gh()
+        base = clients["gh"]
+        gh = base if ref.remote is None else base.for_repo(remote.owner, remote.repo)
+        return pr_info_mod.github_info(gh_pr.get_pr(gh, ref.pr_id, fields=gh_pr.PR_INFO_FIELDS), remote)
+    if "session" not in clients:
+        clients["session"] = requests.Session()
+        clients["session"].headers.update(auth_header(pat))
+    session = clients["session"]
+    return pr_info_mod.ado_info(session, pr_build.get_pr_by_id(session, remote, ref.pr_id), remote)
+
+
+def _failure_text(e: BaseException) -> str:
+    return str(e.code) if isinstance(e, SystemExit) and isinstance(e.code, str) else str(e) or type(e).__name__
+
+
+def _ref_infos(refs: list[pr_ref.PrRef], pat: str | None) -> tuple[list[pr_info_mod.PrInfo], list[str]]:
+    """`_ref_pr_info` for each of `refs`, in order: the PRs found and one message per entry that failed, so one
+    unreachable repo or unknown number doesn't hide the others."""
+    clients: dict = {}
+    infos: list[pr_info_mod.PrInfo] = []
+    errors: list[str] = []
+    for ref in refs:
+        try:
+            infos.append(_ref_pr_info(ref, pat, clients))
+        except (SystemExit, requests.RequestException, KeyError, *_REMOTE_ERRORS) as e:
+            errors.append(f"{ref}: {_failure_text(e)}")
+    return infos, errors
+
+
 def _gh_branch_for(gh: GitHubClient, pr_id: int | None, *, needed: bool) -> str:
     """Branch to namespace uploaded screenshots/files under (see `gh_pr.push_assets`) --
     the checked-out branch normally, or (when acting on a PR by `--pr-id`, which may not
@@ -510,25 +574,85 @@ def pr_status(
     pr_build.run(remote, pat, target_branch, wait, pr_id=pr_id, timeout=timeout)
 
 
+def _info_text(info: pr_info_mod.PrInfo, with_repo: bool = False) -> str:
+    flags = ", ".join([info.state, *(["draft"] if info.draft else []), f"build: {info.build}"])
+    name = f"PR {info.repo}#{info.number}" if with_repo and info.repo else f"PR #{info.number}"
+    return "\n".join([f"{name}: {info.title} ({flags})", info.url, *(f"Issue #{i.number}: {i.url}" for i in info.issues)])
+
+
+def _echo_infos(infos: list[pr_info_mod.PrInfo], as_json: bool, with_repo: bool) -> None:
+    if as_json:
+        typer.echo(json.dumps([i.to_json_dict() for i in infos]))
+    elif infos:
+        typer.echo("\n\n".join(_info_text(i, with_repo) for i in infos))
+
+
 @pr_app.command("info")
 def pr_info(
     as_json: bool = typer.Option(False, "--json", help="Print machine-readable JSON (for status integrations that poll it)"),
     target_branch: str | None = typer.Option(None, "--target-branch", help=_LOOKUP_TARGET_HELP),
-    pr_id: int | None = typer.Option(None, "--pr-id", help=_PR_ID_HELP),
+    pr_ids: list[str] | None = typer.Option(
+        None,
+        "--pr-id",
+        help="Summarise this PR directly, instead of resolving it from the current git branch (lets you skip having its "
+        f"branch checked out locally). Repeat it (or comma-separate) for several, as a list; a PR of another repo is {pr_ref.FORMS}",
+    ),
+    all_prs: bool = typer.Option(
+        False,
+        "--all",
+        help="Every open PR from the current branch (e.g. one into dev and one into main) instead of exactly one: "
+        "with --json a list of the objects, [] and exit 0 when there is none",
+    ),
     pat: str | None = typer.Option(None, "--pat", envvar=["AZURE_DEVOPS_EXT_PAT", "AZURE_DEVOPS_PAT"], help="Azure DevOps PAT (else uses DefaultAzureCredential, e.g. your `az login`)"),
 ) -> None:
     """One-shot summary of the PR opened from the current branch, or --pr-id directly: link, state,
     aggregate build state, and the issue(s)/work item(s) it closes. Exits 1 if there is no such PR.
     Build state is judged the way `pr status` does (latest build per pipeline on Azure DevOps).
+
+    --all and several --pr-id values list PRs instead (with --json an array, whatever the count).
     """
-    info = _current_pr_info(pr_id, target_branch, pat)
+    refs: list[pr_ref.PrRef] = []
+    values: list[str] = []
+    if pr_ids:
+        values = pr_ref.split_values(pr_ids)
+        if not values:
+            raise typer.BadParameter("no PR given", param_hint="--pr-id")
+        try:
+            parsed = [pr_ref.parse_pr_ref(v, current_remote) for v in values]
+        except pr_ref.PrRefError as e:
+            raise typer.BadParameter(str(e), param_hint="--pr-id") from None
+        here = _current_remote_or_none() if any(r.remote for r in parsed) else None
+        # `5,5` and `5,owner/repo#5` are still a list of what they name once
+        unique: dict[str, pr_ref.PrRef] = {}
+        for ref in (pr_ref.canonical(r, here) for r in parsed):
+            unique.setdefault(str(ref).casefold(), ref)
+        refs = list(unique.values())
+    if all_prs and refs:
+        raise typer.BadParameter("--all lists the PRs of the current branch, it can't be combined with --pr-id", param_hint="--all")
+
+    if all_prs:
+        _echo_infos(_open_prs_info(target_branch, pat), as_json, with_repo=False)
+        return
+    if len(values) > 1:
+        infos, errors = _ref_infos(refs, pat)
+        _echo_infos(infos, as_json, with_repo=True)
+        for error in errors:
+            typer.echo(f"error: {error}", err=True)
+        if errors:
+            raise typer.Exit(1)
+        return
+    if refs and refs[0].remote is not None:
+        infos, errors = _ref_infos(refs, pat)
+        if errors:
+            typer.echo(f"error: {errors[0]}", err=True)
+            raise typer.Exit(1)
+        info = infos[0]
+    else:
+        info = _current_pr_info(refs[0].pr_id if refs else None, target_branch, pat)
     if as_json:
         typer.echo(json.dumps(info.to_json_dict()))
         return
-    flags = ", ".join([info.state, *(["draft"] if info.draft else []), f"build: {info.build}"])
-    typer.echo(f"PR #{info.number}: {info.title} ({flags})\n{info.url}")
-    for issue in info.issues:
-        typer.echo(f"Issue #{issue.number}: {issue.url}")
+    typer.echo(_info_text(info))
 
 
 @pr_app.command("retry")
@@ -629,6 +753,9 @@ def pr_update(
 @pr_app.command("comment")
 def pr_comment(
     message: str | None = typer.Option(None, "--message", help="Comment text"),
+    message_file: str | None = typer.Option(
+        None, "--message-file", help="Read the comment text from this file (`-` = stdin), e.g. a markdown plan"
+    ),
     screenshot: list[str] = typer.Option(
         [], "--screenshot", help="Path to an image to embed in the comment (repeatable)"
     ),
@@ -647,6 +774,13 @@ def pr_comment(
     """Post a comment on the PR opened from the current branch, or --pr-id directly
     (Azure DevOps or GitHub, auto-detected).
     """
+    if message_file is not None:
+        if message is not None:
+            raise typer.BadParameter("pass either --message or --message-file, not both", param_hint="--message-file")
+        try:
+            message = sys.stdin.read() if message_file == "-" else Path(message_file).read_text(encoding="utf-8")
+        except OSError as e:
+            raise typer.BadParameter(f"cannot read {message_file!r}: {e}", param_hint="--message-file") from e
     for path in screenshot:
         if not Path(path).is_file():
             raise typer.BadParameter(f"Screenshot not found: {path}", param_hint="--screenshot")
@@ -654,7 +788,7 @@ def pr_comment(
         if not Path(path).is_file():
             raise typer.BadParameter(f"File not found: {path}", param_hint="--file")
     if not message and not screenshot and not file:
-        raise typer.BadParameter("Provide at least one of --message, --screenshot, --file")
+        raise typer.BadParameter("Provide at least one of --message, --message-file, --screenshot, --file")
 
     remote = current_remote()
     if isinstance(remote, GitHubRemote):

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/gh_pr.py

@@ -170,6 +170,11 @@ def resolve_pr_id(gh: GitHubClient, pr_id: int | None, target: str | None = None
     return prs[choose_pr(branch, candidates)]["number"]
 
 
+def open_pr_numbers(gh: GitHubClient, target: str | None = None) -> list[int]:
+    """Numbers of every open PR from the current branch (into `target` if given), newest first; `[]` if there is none."""
+    return [p["number"] for p in _branch_prs(gh, current_branch(), state="open", base=target)]
+
+
 _CONTEXT_FIELDS = """
 fragment ContextFields on StatusCheckRollupContext {
   __typename

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/github_api.py

@@ -55,6 +55,7 @@ class GitHubClient:
 
     def __init__(self, token: str, owner: str | None = None, repo: str | None = None, base_url: str = API_URL) -> None:
         self.base_url = base_url.rstrip("/")
+        self._token = token
         self._owner = owner
         self._repo = repo
         self.session = requests.Session()
@@ -67,6 +68,10 @@ class GitHubClient:
             }
         )
 
+    def for_repo(self, owner: str, repo: str) -> GitHubClient:
+        """The same credentials, addressing another repo."""
+        return GitHubClient(self._token, owner, repo, self.base_url)
+
     @property
     def owner(self) -> str:
         self._resolve_repo()

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/pr_build.py

@@ -207,6 +207,25 @@ def get_pr(session: requests.Session, remote: AdoRemote, source_branch: str, tar
     sys.exit(1)
 
 
+def get_active_prs(session: requests.Session, remote: AdoRemote, source_branch: str, target_branch: str | None) -> list[dict]:
+    """Every active PR from `source_branch` (into `target_branch` if given); `[]` if there is none.
+
+    Unlike `get_pr` nothing is asked about and merge conflicts aren't an error: the caller wants the whole list.
+    """
+    r = session.get(
+        f"{_base_url(remote)}/_apis/git/repositories/{remote.repo}/pullrequests",
+        params={
+            "searchCriteria.sourceRefName": f"refs/heads/{source_branch}",
+            **({"searchCriteria.targetRefName": f"refs/heads/{target_branch}"} if target_branch else {}),
+            "searchCriteria.status": "active",
+            "api-version": "7.1",
+        },
+        timeout=HTTP_TIMEOUT_SECS,
+    )
+    r.raise_for_status()
+    return r.json().get("value", [])
+
+
 def get_pr_by_id(session: requests.Session, remote: AdoRemote, pr_id: int) -> dict:
     """Fetch a PR directly by its ID -- for `--pr-id` overrides, where the caller wants to act
     on a specific PR without needing its source branch checked out locally (unlike `get_pr`,
@@ -561,13 +580,40 @@ def update(
 def link_work_item(session: requests.Session, remote: AdoRemote, pr_id: int, work_item_id: int) -> None:
     """Link work item `work_item_id` to PR `pr_id`, so it shows up in the PR's "Work Items" tab
     (and the work item's own "Development" links) -- the Azure DevOps equivalent of GitHub's
-    closing-keyword PR<->issue link, via the dedicated Pull Request Work Items REST resource
-    (POST .../pullRequests/{pr_id}/workitems/{work_item_id}, the same one `az repos pr work-item
-    add` itself calls). Idempotent -- linking an already-linked work item just re-confirms it.
+    closing-keyword PR<->issue link.
+
+    There is no REST resource that links "PR -> work item" directly; what `az repos pr work-item add`
+    does (and so do we) is add an `ArtifactLink` relation to the *work item*, pointing at the PR's
+    `vstfs:///Git/PullRequestId/{projectId}%2F{repoId}%2F{prId}` artifact URI. Idempotent -- an
+    already-linked work item is left alone (adding the relation twice would be rejected).
     """
-    r = session.post(
-        f"{_base_url(remote)}/_apis/git/repositories/{quote(remote.repo, safe='')}/pullRequests/{pr_id}/workitems/{work_item_id}",
+    r = session.get(
+        f"{_base_url(remote)}/_apis/git/repositories/{quote(remote.repo, safe='')}/pullrequests/{pr_id}",
+        params={"api-version": "7.1"},
+        timeout=HTTP_TIMEOUT_SECS,
+    )
+    r.raise_for_status()
+    repository = r.json()["repository"]
+    artifact_url = f"vstfs:///Git/PullRequestId/{repository['project']['id']}%2F{repository['id']}%2F{pr_id}"
+
+    work_item_url = f"{_base_url(remote)}/_apis/wit/workitems/{work_item_id}"
+    r = session.get(work_item_url, params={"$expand": "relations", "api-version": "7.1"}, timeout=HTTP_TIMEOUT_SECS)
+    r.raise_for_status()
+    existing = r.json().get("relations") or []
+    if any(rel.get("rel") == "ArtifactLink" and str(rel.get("url", "")).lower() == artifact_url.lower() for rel in existing):
+        return
+
+    r = session.patch(
+        work_item_url,
         params={"api-version": "7.1"},
+        json=[
+            {
+                "op": "add",
+                "path": "/relations/-",
+                "value": {"rel": "ArtifactLink", "url": artifact_url, "attributes": {"name": "Pull Request"}},
+            }
+        ],
+        headers={"Content-Type": "application/json-patch+json"},
         timeout=HTTP_TIMEOUT_SECS,
     )
     r.raise_for_status()

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/pr_info.py

@@ -40,6 +40,7 @@ class PrInfo:
     draft: bool
     build: str
     issues: list[IssueRef] = field(default_factory=list)
+    repo: str = ""  # "owner/repo" (GitHub) or "org/project/repo" (Azure DevOps): which repo the PR is in
 
     def to_json_dict(self) -> dict:
         return asdict(self)
@@ -95,6 +96,7 @@ def github_info(pr: dict, remote: GitHubRemote) -> PrInfo:
         draft=bool(pr.get("isDraft")),
         build=build_state(pr.get("statusCheckRollup") or []),
         issues=issues,
+        repo=f"{remote.owner}/{remote.repo}",
     )
 
 
@@ -143,4 +145,5 @@ def ado_info(session: requests.Session, pr: dict, remote: AdoRemote) -> PrInfo:
         draft=bool(pr.get("isDraft")),
         build=_ado_build(session, remote, pr),
         issues=issues,
+        repo=f"{remote.org}/{remote.project}/{remote.repo}",
     )

bmsdna_devtools-0.46.0/bmsdna/devtools/pr_ref.py

@@ -0,0 +1,90 @@
+"""`bdt pr info --pr-id` values: which PR, in which repo.
+
+A bare number is a PR of the current repo. For a PR of another repo (a status integration or an agent working
+across repos) an entry carries the repo too: `owner/repo#12` on GitHub, `project/repo#12` or `org/project/repo#12` on
+Azure DevOps (the host being the current repo's), or the PR's full web URL, which needs no checkout at all.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from .gitrepo import AdoRemote, GitHubRemote, NotAzureDevOpsRemoteError, parse_ado_remote
+
+FORMS = "a number, owner/repo#N (GitHub), project/repo#N or org/project/repo#N (Azure DevOps), or the PR's URL"
+
+
+class PrRefError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class PrRef:
+    pr_id: int
+    remote: AdoRemote | GitHubRemote | None  # None: the current repo
+
+    def __str__(self) -> str:
+        if isinstance(self.remote, GitHubRemote):
+            return f"{self.remote.owner}/{self.remote.repo}#{self.pr_id}"
+        if isinstance(self.remote, AdoRemote):
+            return f"{self.remote.org}/{self.remote.project}/{self.remote.repo}#{self.pr_id}"
+        return f"#{self.pr_id}"
+
+
+_GITHUB_PR_URL = re.compile(r"^https://github\.com/([^/\s]+)/([^/\s]+)/pull/(\d+)(?:[/?#].*)?$")
+_ADO_PR_URL = re.compile(r"^https://(?:dev\.azure\.com/|[^/\s]+\.visualstudio\.com/).*?/_git/[^/\s]+/pullrequest/(\d+)(?:[/?#].*)?$")
+_SHORTHAND = re.compile(r"^(.+)#(\d+)$")
+
+
+def split_values(values: list[str]) -> list[str]:
+    """Entries of repeated and/or comma-separated `--pr-id` values, blanks dropped."""
+    return [part.strip() for value in values for part in value.split(",") if part.strip()]
+
+
+def parse_pr_ref(text: str, current_remote: Callable[[], AdoRemote | GitHubRemote]) -> PrRef:
+    """`current_remote` is only called for the `repo#N` forms, which take their host from it."""
+    text = text.strip()
+    if re.fullmatch(r"#?\d+", text):
+        return PrRef(int(text.lstrip("#")), None)
+
+    if match := _GITHUB_PR_URL.match(text):
+        return PrRef(int(match.group(3)), GitHubRemote(match.group(1), match.group(2)))
+    if match := _ADO_PR_URL.match(text):
+        # the legacy `https://org.visualstudio.com/DefaultCollection/Project/_git/...` form has a collection segment
+        url = text.replace("/DefaultCollection/", "/", 1) if "visualstudio.com" in text else text
+        try:
+            return PrRef(int(match.group(1)), parse_ado_remote(url))
+        except (NotAzureDevOpsRemoteError, IndexError):
+            raise PrRefError(f"can't read the Azure DevOps repo from '{text}'") from None
+
+    if match := _SHORTHAND.match(text):
+        parts = match.group(1).split("/")
+        pr_id = int(match.group(2))
+        if all(parts) and len(parts) in (2, 3):
+            try:
+                here = current_remote()
+            except (SystemExit, Exception) as e:
+                raise PrRefError(
+                    f"'{text}' needs to know whether this repo is GitHub or Azure DevOps ({e}); use the PR's URL instead"
+                ) from None
+            if isinstance(here, GitHubRemote) and len(parts) == 2:
+                return PrRef(pr_id, GitHubRemote(parts[0], parts[1]))
+            if isinstance(here, AdoRemote):
+                if len(parts) == 2:
+                    return PrRef(pr_id, AdoRemote(here.org, parts[0], parts[1]))
+                return PrRef(pr_id, AdoRemote(parts[0], parts[1], parts[2]))
+            raise PrRefError(f"'{text}': GitHub PRs are owner/repo#N")
+    raise PrRefError(f"can't read '{text}' as a PR: use {FORMS}")
+
+
+def canonical(ref: PrRef, here: AdoRemote | GitHubRemote | None) -> PrRef:
+    """`ref` as a bare number when it names a PR of the current repo `here` (compared case-insensitively), so that
+    `5` and `owner/repo#5` are one PR; `here` None (no checkout) leaves it as it is."""
+    if ref.remote is None or here is None or type(ref.remote) is not type(here):
+        return ref
+    same = [str(getattr(ref.remote, f)).casefold() for f in ref.remote.__dataclass_fields__] == [
+        str(getattr(here, f)).casefold() for f in here.__dataclass_fields__
+    ]
+    return PrRef(ref.pr_id, None) if same else ref

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/bmsdna/devtools/worktree.py

@@ -59,6 +59,43 @@ def _run_capture(cmd: list[str], cwd: Path | None = None) -> subprocess.Complete
     return subprocess.run(cmd, cwd=cwd, capture_output=True, text=True, check=False)
 
 
+def _git_ok(args: list[str], cwd: Path, timeout: float = 5.0) -> bool:
+    try:
+        return subprocess.run(["git", *args], cwd=cwd, capture_output=True, check=False, timeout=timeout).returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def _start_point(root: Path, base: str) -> tuple[str, bool]:
+    """Where a new worktree branch should start, and whether that is a remote-tracking ref.
+
+    `base` is usually a long-lived local branch (`dev`) that nobody keeps up to date, so a worktree
+    branched from it starts behind -- the PR then shows merge conflicts and the plan gets written
+    against stale code. Fetch `origin/<base>` first and start from it when the local branch is
+    strictly behind. A local branch that is ahead of / diverged from the remote is left alone (its
+    unpushed work is on purpose), as is everything when there is no `origin` or it can't be reached.
+    """
+    local = f"refs/heads/{base}"
+    remote = f"refs/remotes/origin/{base}"
+    has_local = _git_ok(["rev-parse", "--verify", "--quiet", local], root)
+    if not _git_ok(["remote", "get-url", "origin"], root):
+        return base, False
+    if not _git_ok(["fetch", "--quiet", "origin", f"+refs/heads/{base}:{remote}"], root, timeout=pull_mod.CLI_TIMEOUT_SECS):
+        if has_local:
+            print(f"warning: could not fetch origin/{base}; branching from the local {base}, which may be behind", file=sys.stderr)
+        return base, False
+    if not has_local:
+        return f"origin/{base}", True
+    if _git_ok(["merge-base", "--is-ancestor", remote, local], root):
+        return base, False  # up to date or ahead of the remote
+    if _git_ok(["merge-base", "--is-ancestor", local, remote], root):
+        behind = _run_capture(["git", "rev-list", "--count", f"{local}..{remote}"], cwd=root).stdout.strip()
+        print(f"{base} is {behind} commit(s) behind origin/{base}; branching from origin/{base}")
+        return f"origin/{base}", True
+    print(f"warning: local {base} and origin/{base} have diverged; branching from the local {base}", file=sys.stderr)
+    return base, False
+
+
 def create(
     name: str,
     base: str = "dev",
@@ -72,7 +109,9 @@ def create(
     if path.exists():
         sys.exit(f"error: {path} already exists")
 
-    _run(["git", "worktree", "add", str(path), "-b", name, base], cwd=root)
+    start, remote_start = _start_point(root, base)
+    # --no-track: the new branch must not push to / compare against origin/<base>
+    _run(["git", "worktree", "add", *(["--no-track"] if remote_start else []), str(path), "-b", name, start], cwd=root)
 
     if submodules and (root / ".gitmodules").exists():
         _run(["git", "submodule", "update", "--init"], cwd=path)

{bmsdna_devtools-0.44.0 → bmsdna_devtools-0.46.0}/pyproject.toml

@@ -10,7 +10,7 @@ packages = ["bmsdna"]
 
 [project]
 name = "bmsdna-devtools"
-version = "0.44.0"
+version = "0.46.0"
 description = "Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects"
 readme = "README.md"
 requires-python = ">=3.14"  # pgdevkit>=0.7.1 requires 3.14; was >=3.11 before adding it as a dependency