bmsdna-devtools 0.23.0__tar.gz → 0.25.0__tar.gz

{bmsdna_devtools-0.23.0 → bmsdna_devtools-0.25.0}/PKG-INFO

@@ -1,12 +1,14 @@
 Metadata-Version: 2.5
 Name: bmsdna-devtools
-Version: 0.23.0
+Version: 0.25.0
 Summary: Shared Azure DevOps / GitHub / git / Azure Monitor developer tooling for BMS projects
 Requires-Python: >=3.14
 Requires-Dist: pgdevkit[db]>=0.7.1
 Requires-Dist: requests>=2.32.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.26.7
+Provides-Extra: lint
+Requires-Dist: sqlglot>=27.0.0; extra == 'lint'
 Description-Content-Type: text/markdown
 
 # bmsdna-devtools
@@ -14,7 +16,9 @@ Description-Content-Type: text/markdown
 Shared developer tooling for BMS projects: PR build/check status, PR
 creation, issue/work item creation and comments, git worktrees (creation and
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
-pre-flight checks, and Azure log queries.
+pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
+postgres/psycopg SQL rules, pydantic-model placement, hand-wired HTTP access in
+TypeScript, and baseline tooling.
 `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
@@ -75,6 +79,12 @@ is shown in the output. Check status is computed from
 `gh pr view --json statusCheckRollup` rather than `gh pr checks --json`,
 since the latter flag isn't available in all `gh` releases.
 
+Pass `--pr-id <number>` to check a specific PR directly instead of resolving
+it from the current branch — useful when that PR's branch isn't checked out
+locally at all. `bdt pr retry`, `pr publish`, `pr update`, and `pr comment`
+all accept the same option, for the same reason. (`pr watch-deploy` doesn't:
+it watches a branch-triggered build/workflow run, not any particular PR.)
+
 ## `bdt pr retry`
 
 Retry only the **failed** job(s)/stage(s) of the most recent build/run for the
@@ -86,7 +96,8 @@ bdt pr retry [--target-branch main]
 ```
 
 No build/run ID needed — like `bdt pr status`, it resolves the PR (and its
-latest build/run per pipeline/workflow) from the current branch.
+latest build/run per pipeline/workflow) from the current branch, or from
+`--pr-id` directly if given.
 
 **Azure DevOps**: uses the `retry=true` query parameter on the "Update
 Build" REST API
@@ -215,10 +226,20 @@ 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.
 
+`--tag` and `--label` are aliases of each other (repeatable on `create`,
+`search`, and `update`) — pass whichever reads naturally; the values are
+merged and routed to tags on Azure DevOps or labels on GitHub, whichever
+backend is actually active, instead of being silently ignored by the other
+one. Same for `update`'s `--remove-tag`/`--remove-label`.
+
 **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
+`Bug`). `--tag`/`--label` set/replace the full tag list (repeatable; omit
+both on `update` to leave tags unchanged). `update`'s `--remove-tag`/
+`--remove-label` instead removes just the named tag(s) and leaves the rest —
+unlike `--tag`/`--label`, which replace the whole set — by reading the work
+item's current tags first (there's no Azure DevOps "remove one tag" patch
+op). `--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
@@ -242,9 +263,9 @@ 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
+`comment`. `--label`/`--tag` add a label on `create`, or add/remove one on
+`update` (paired with `--remove-label`/`--remove-tag`); 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.
@@ -466,6 +487,94 @@ bdt logs fetch --env prod
 bdt logs fetch --env prod --out logs/ --keep-archive
 ```
 
+## `bdt lint`
+
+Static checks (implementing [bmsuisse/skills#52](https://github.com/bmsuisse/skills/issues/52))
+for the `postgres-best-practices` skill's SQL rules, pydantic-model placement, and
+that the repo has its baseline tooling actually set up:
+
+```bash
+bdt lint                       # scan the current directory, recursively
+bdt lint backend/              # scan one directory
+bdt lint backend/db/a.py b.py  # scan only these files -- e.g. from a prek/pre-commit
+                                # hook's staged-file list, so it can run on the diff only
+bdt lint --no-tooling-check    # skip the tooling-config check for this run
+```
+
+Every `.execute()`/`.executemany()` call whose SQL argument can be resolved to a
+literal or f-string/concatenation/`%`-format expression is checked (an
+unresolvable argument, e.g. a plain function parameter, is silently skipped --
+this can't false-positive on non-psycopg `.execute()` calls, or on dynamic SQL
+it can't see through):
+
+- **`sql-inline-too-complex`** — more than a trivial (≤4 line) query, or a
+  JOIN/CTE/subquery/aggregation, inline instead of `load_sql()`/a `.sql` file.
+- **`sql-fstring-injection`** / **`sql-concat-injection`** /
+  **`sql-percent-format-injection`** / **`sql-format-injection`** — SQL built
+  with an f-string, `+` concatenation, the `%` operator, or `str.format()`
+  instead of a psycopg t-string (3.14+), `psycopg.sql`, or bound params.
+- **`sql-positional-param`** — positional `%s` instead of named `%(name)s`.
+- **`sql-forbidden-join`** — `RIGHT JOIN`/`LATERAL JOIN`/`CROSS APPLY` (same
+  patterns the `prek` skill's `check_files.py` forbids in `.sql` files).
+
+A candidate is only ever flagged once its (resolved) text actually parses with
+[sqlglot](https://github.com/tobymao/sqlglot) as a `SELECT`/`INSERT`/`UPDATE`/
+`DELETE`/`UNION`/`MERGE` — this is what lets `bdt lint` scan *any* `.execute()`
+call, regardless of driver, without flagging e.g. a duckdb `COPY ... TO` export.
+
+**`pydantic-model-misplaced`** — a pydantic model (or `PostgresTableModel`)
+with more than 5 fields defined directly under an `api/` directory, instead of
+an `api/models/`(/`schemas/`/`dto/`) module.
+
+**`ts-handwired-http`** / **`ts-handwired-model`** (TypeScript, `.ts`/`.tsx`/`.mts`,
+[bmsuisse/devtools#52](https://github.com/bmsuisse/devtools/issues/52)) — a frontend
+package that already generates an API client from the backend's OpenAPI schema
+(its nearest `package.json` depends on `openapi-typescript`/`openapi-fetch`,
+`@hey-api/openapi-ts`, `orval`, ... or has an `openapi` script) should use it. The
+rule flags hand-wired `fetch(...)`, `axios`/`axios.create(...)` and
+`new XMLHttpRequest()` (`ts-handwired-http`), and a `.json()` result typed by
+casting/annotating a hand-written model (`ts-handwired-model`, only reported
+outside the block of a `fetch`/`axios` call, which the http rule already covers). Packages without a generator are skipped, as
+are generated code (`generated/`, `*.gen.ts`, `*.generated.ts`, `api-types.ts`,
+`*.d.ts`; also their `.mts`/`.tsx` variants), tests (`*.test.*`, `*.spec.*`, `__tests__/`, `e2e/`, `tests/`) and
+third-party URLs (`fetch("https://...")`). Hand-wired access is fine for files and
+other non-JSON traffic, since generators handle those badly, so a call is *not*
+flagged when its enclosing block mentions `FormData`, `Blob`/`.blob()`/
+`.arrayBuffer()`, `getReader()`/`response.body`/`TextDecoder`/`EventSource`/`SSE`,
+`createObjectURL`, `new File(`, an `application/octet-stream`/`multipart/`/
+`text/event-stream` content type, or returns `.text()` (a plain-text response), or sits in a `createClient(...)` setup (a `fetch` passed to the generated client).
+It's a tokenizer-level heuristic, not a type-aware analysis; to silence a
+legitimate exception, put a comment on (or right above) the line:
+
+```ts
+// bdt-lint: ignore ts-handwired-http -- websocket handshake, not in the schema
+```
+
+**Tooling config** — the repo must declare `ty`, `ruff` and `pytest` as
+dependencies, have `pytest` configured (`[tool.pytest.ini_options]` or a
+`pytest.ini`/`setup.cfg`), and have a `prek.toml` (see the `prek` skill).
+Never a hard block — bypass it for one run with `--no-tooling-check`, or
+permanently for the repo via `pyproject.toml`:
+
+```toml
+[tool.bdt.lint]
+skip_tooling_check = true
+```
+
+Other `[tool.bdt.lint]` knobs (all optional): `exclude_dirs` (extra directory
+names to skip, beyond the built-in `.venv`/`node_modules`/etc. list),
+`pydantic_field_threshold` (default 5), `pydantic_base_classes` (default
+`["BaseModel", "PostgresTableModel"]`), `pydantic_allowed_subdirs` (default
+`["models", "schemas", "dto"]`), `pydantic_api_dir_names` (default `["api"]`),
+`ts_exclude_globs` (repo-relative globs of TypeScript files to skip, e.g.
+`["src/legacy/*"]`), `ts_non_json_markers` (extra strings that mark a call's
+enclosing block as non-JSON traffic).
+
+Requires [sqlglot](https://pypi.org/project/sqlglot/) for the SQL checks —
+already pulled in transitively via `pgdevkit[db]`, but declared explicitly as
+the `bmsdna-devtools[lint]` extra; a clear install hint is printed (not a raw
+`ImportError`) if it's ever missing.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

{bmsdna_devtools-0.23.0 → bmsdna_devtools-0.25.0}/README.md

@@ -3,7 +3,9 @@
 Shared developer tooling for BMS projects: PR build/check status, PR
 creation, issue/work item creation and comments, git worktrees (creation and
 merged-worktree/orphaned-test-DB cleanup), a commit-and-push helper with
-pre-flight checks, and Azure log queries.
+pre-flight checks, Azure log queries, and static checks (`bdt lint`) for
+postgres/psycopg SQL rules, pydantic-model placement, hand-wired HTTP access in
+TypeScript, and baseline tooling.
 `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
@@ -64,6 +66,12 @@ is shown in the output. Check status is computed from
 `gh pr view --json statusCheckRollup` rather than `gh pr checks --json`,
 since the latter flag isn't available in all `gh` releases.
 
+Pass `--pr-id <number>` to check a specific PR directly instead of resolving
+it from the current branch — useful when that PR's branch isn't checked out
+locally at all. `bdt pr retry`, `pr publish`, `pr update`, and `pr comment`
+all accept the same option, for the same reason. (`pr watch-deploy` doesn't:
+it watches a branch-triggered build/workflow run, not any particular PR.)
+
 ## `bdt pr retry`
 
 Retry only the **failed** job(s)/stage(s) of the most recent build/run for the
@@ -75,7 +83,8 @@ bdt pr retry [--target-branch main]
 ```
 
 No build/run ID needed — like `bdt pr status`, it resolves the PR (and its
-latest build/run per pipeline/workflow) from the current branch.
+latest build/run per pipeline/workflow) from the current branch, or from
+`--pr-id` directly if given.
 
 **Azure DevOps**: uses the `retry=true` query parameter on the "Update
 Build" REST API
@@ -204,10 +213,20 @@ 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.
 
+`--tag` and `--label` are aliases of each other (repeatable on `create`,
+`search`, and `update`) — pass whichever reads naturally; the values are
+merged and routed to tags on Azure DevOps or labels on GitHub, whichever
+backend is actually active, instead of being silently ignored by the other
+one. Same for `update`'s `--remove-tag`/`--remove-label`.
+
 **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
+`Bug`). `--tag`/`--label` set/replace the full tag list (repeatable; omit
+both on `update` to leave tags unchanged). `update`'s `--remove-tag`/
+`--remove-label` instead removes just the named tag(s) and leaves the rest —
+unlike `--tag`/`--label`, which replace the whole set — by reading the work
+item's current tags first (there's no Azure DevOps "remove one tag" patch
+op). `--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
@@ -231,9 +250,9 @@ 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
+`comment`. `--label`/`--tag` add a label on `create`, or add/remove one on
+`update` (paired with `--remove-label`/`--remove-tag`); 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.
@@ -455,6 +474,94 @@ bdt logs fetch --env prod
 bdt logs fetch --env prod --out logs/ --keep-archive
 ```
 
+## `bdt lint`
+
+Static checks (implementing [bmsuisse/skills#52](https://github.com/bmsuisse/skills/issues/52))
+for the `postgres-best-practices` skill's SQL rules, pydantic-model placement, and
+that the repo has its baseline tooling actually set up:
+
+```bash
+bdt lint                       # scan the current directory, recursively
+bdt lint backend/              # scan one directory
+bdt lint backend/db/a.py b.py  # scan only these files -- e.g. from a prek/pre-commit
+                                # hook's staged-file list, so it can run on the diff only
+bdt lint --no-tooling-check    # skip the tooling-config check for this run
+```
+
+Every `.execute()`/`.executemany()` call whose SQL argument can be resolved to a
+literal or f-string/concatenation/`%`-format expression is checked (an
+unresolvable argument, e.g. a plain function parameter, is silently skipped --
+this can't false-positive on non-psycopg `.execute()` calls, or on dynamic SQL
+it can't see through):
+
+- **`sql-inline-too-complex`** — more than a trivial (≤4 line) query, or a
+  JOIN/CTE/subquery/aggregation, inline instead of `load_sql()`/a `.sql` file.
+- **`sql-fstring-injection`** / **`sql-concat-injection`** /
+  **`sql-percent-format-injection`** / **`sql-format-injection`** — SQL built
+  with an f-string, `+` concatenation, the `%` operator, or `str.format()`
+  instead of a psycopg t-string (3.14+), `psycopg.sql`, or bound params.
+- **`sql-positional-param`** — positional `%s` instead of named `%(name)s`.
+- **`sql-forbidden-join`** — `RIGHT JOIN`/`LATERAL JOIN`/`CROSS APPLY` (same
+  patterns the `prek` skill's `check_files.py` forbids in `.sql` files).
+
+A candidate is only ever flagged once its (resolved) text actually parses with
+[sqlglot](https://github.com/tobymao/sqlglot) as a `SELECT`/`INSERT`/`UPDATE`/
+`DELETE`/`UNION`/`MERGE` — this is what lets `bdt lint` scan *any* `.execute()`
+call, regardless of driver, without flagging e.g. a duckdb `COPY ... TO` export.
+
+**`pydantic-model-misplaced`** — a pydantic model (or `PostgresTableModel`)
+with more than 5 fields defined directly under an `api/` directory, instead of
+an `api/models/`(/`schemas/`/`dto/`) module.
+
+**`ts-handwired-http`** / **`ts-handwired-model`** (TypeScript, `.ts`/`.tsx`/`.mts`,
+[bmsuisse/devtools#52](https://github.com/bmsuisse/devtools/issues/52)) — a frontend
+package that already generates an API client from the backend's OpenAPI schema
+(its nearest `package.json` depends on `openapi-typescript`/`openapi-fetch`,
+`@hey-api/openapi-ts`, `orval`, ... or has an `openapi` script) should use it. The
+rule flags hand-wired `fetch(...)`, `axios`/`axios.create(...)` and
+`new XMLHttpRequest()` (`ts-handwired-http`), and a `.json()` result typed by
+casting/annotating a hand-written model (`ts-handwired-model`, only reported
+outside the block of a `fetch`/`axios` call, which the http rule already covers). Packages without a generator are skipped, as
+are generated code (`generated/`, `*.gen.ts`, `*.generated.ts`, `api-types.ts`,
+`*.d.ts`; also their `.mts`/`.tsx` variants), tests (`*.test.*`, `*.spec.*`, `__tests__/`, `e2e/`, `tests/`) and
+third-party URLs (`fetch("https://...")`). Hand-wired access is fine for files and
+other non-JSON traffic, since generators handle those badly, so a call is *not*
+flagged when its enclosing block mentions `FormData`, `Blob`/`.blob()`/
+`.arrayBuffer()`, `getReader()`/`response.body`/`TextDecoder`/`EventSource`/`SSE`,
+`createObjectURL`, `new File(`, an `application/octet-stream`/`multipart/`/
+`text/event-stream` content type, or returns `.text()` (a plain-text response), or sits in a `createClient(...)` setup (a `fetch` passed to the generated client).
+It's a tokenizer-level heuristic, not a type-aware analysis; to silence a
+legitimate exception, put a comment on (or right above) the line:
+
+```ts
+// bdt-lint: ignore ts-handwired-http -- websocket handshake, not in the schema
+```
+
+**Tooling config** — the repo must declare `ty`, `ruff` and `pytest` as
+dependencies, have `pytest` configured (`[tool.pytest.ini_options]` or a
+`pytest.ini`/`setup.cfg`), and have a `prek.toml` (see the `prek` skill).
+Never a hard block — bypass it for one run with `--no-tooling-check`, or
+permanently for the repo via `pyproject.toml`:
+
+```toml
+[tool.bdt.lint]
+skip_tooling_check = true
+```
+
+Other `[tool.bdt.lint]` knobs (all optional): `exclude_dirs` (extra directory
+names to skip, beyond the built-in `.venv`/`node_modules`/etc. list),
+`pydantic_field_threshold` (default 5), `pydantic_base_classes` (default
+`["BaseModel", "PostgresTableModel"]`), `pydantic_allowed_subdirs` (default
+`["models", "schemas", "dto"]`), `pydantic_api_dir_names` (default `["api"]`),
+`ts_exclude_globs` (repo-relative globs of TypeScript files to skip, e.g.
+`["src/legacy/*"]`), `ts_non_json_markers` (extra strings that mark a call's
+enclosing block as non-JSON traffic).
+
+Requires [sqlglot](https://pypi.org/project/sqlglot/) for the SQL checks —
+already pulled in transitively via `pgdevkit[db]`, but declared explicitly as
+the `bmsdna-devtools[lint]` extra; a clear install hint is printed (not a raw
+`ImportError`) if it's ever missing.
+
 ## Releasing
 
 Bump `version` in `pyproject.toml` as part of your PR, same as any other

{bmsdna_devtools-0.23.0 → bmsdna_devtools-0.25.0}/bmsdna/devtools/ado_issue.py

@@ -60,8 +60,12 @@ def resolve_board(board: str | None, start: Path | None = None) -> str | None:
     return board or load_bdt_table("ado", start).get("board")
 
 
+def _org_url(remote: AdoRemote) -> str:
+    return f"https://dev.azure.com/{quote(remote.org, safe='')}"
+
+
 def _base_url(remote: AdoRemote) -> str:
-    return f"https://dev.azure.com/{quote(remote.org, safe='')}/{quote(remote.project, safe='')}"
+    return f"{_org_url(remote)}/{quote(remote.project, safe='')}"
 
 
 def get_team_area_path(session: requests.Session, remote: AdoRemote, team: str) -> str:
@@ -395,8 +399,11 @@ def html_url(work_item: dict) -> str | None:
     return work_item.get("_links", {}).get("html", {}).get("href")
 
 
-def edit_url(remote: AdoRemote, work_item_id: int) -> str:
-    return f"{_base_url(remote)}/_workitems/edit/{work_item_id}"
+def edit_url(remote: AdoRemote, work_item_id: int, project: str | None = None) -> str:
+    """`project` overrides `remote.project` -- needed by an org-wide `search()`, whose results
+    can belong to a different project than the one the command was run in.
+    """
+    return f"{_org_url(remote)}/{quote(project or remote.project, safe='')}/_workitems/edit/{work_item_id}"
 
 
 def _escape_wiql_string(value: str) -> str:
@@ -415,11 +422,13 @@ def build_search_wiql(
     since: str | None = None,
     area_path: str | None = None,
     state: str = "open",
+    org_wide: bool = False,
+    tags: list[str] | None = None,
 ) -> str:
     """WIQL for work items whose Title or Description contains every given keyword (ANDed),
-    optionally restricted to items changed on/after `since` (an ISO 'YYYY-MM-DD' date) and/or
-    scoped to a board's Area Path subtree, most recently changed first. `keywords` may be empty,
-    to list work items without a text filter.
+    optionally restricted to items changed on/after `since` (an ISO 'YYYY-MM-DD' date), carrying
+    every given tag (ANDed), and/or scoped to a board's Area Path subtree, most recently changed
+    first. `keywords` may be empty, to list work items without a text filter.
 
     `since` is rendered as a UTC ISO 8601 literal (`'YYYY-MM-DDT00:00:00Z'`) — the one
     DateTime format WIQL accepts regardless of the querying account's locale/date-pattern
@@ -430,11 +439,21 @@ def build_search_wiql(
     CMMI use 'Closed' for their Completed-category state, Scrum and Basic use 'Done' — so
     `_TERMINAL_STATES` is the union across the built-in templates, not a per-project source of
     truth (a custom process with its own state names won't be filtered correctly).
+
+    `org_wide` drops the `[System.TeamProject] = @project` clause -- `@project` is only valid
+    when the query runs against a project-scoped WIQL endpoint (see `run_wiql`'s `org_wide`),
+    and dropping it is what actually lets the query match work items outside the current project.
+
+    `tags` is a separate filter from `keywords` -- `Contains Words` against Title/Description
+    doesn't match `System.Tags` at all, so a tag search (e.g. every work item tagged
+    'ready4implementation' across the whole org) needs its own `[System.Tags] Contains` clause.
     """
     clauses = [
         f"([System.Title] Contains Words '{_escape_wiql_string(k)}' OR [System.Description] Contains Words '{_escape_wiql_string(k)}')"
         for k in keywords
     ]
+    for tag in tags or []:
+        clauses.append(f"[System.Tags] Contains '{_escape_wiql_string(tag)}'")
     if since:
         clauses.append(f"[System.ChangedDate] >= '{since}T00:00:00Z'")
     if area_path:
@@ -443,13 +462,21 @@ def build_search_wiql(
         clauses.append(" AND ".join(f"[System.State] <> '{s}'" for s in _TERMINAL_STATES))
     elif state == "closed":
         clauses.append("(" + " OR ".join(f"[System.State] = '{s}'" for s in _TERMINAL_STATES) + ")")
-    where = " AND ".join(["[System.TeamProject] = @project", *clauses])
-    return f"SELECT [System.Id] FROM WorkItems WHERE {where} ORDER BY [System.ChangedDate] DESC"
+    if not org_wide:
+        clauses.insert(0, "[System.TeamProject] = @project")
+    query = "SELECT [System.Id] FROM WorkItems"
+    if clauses:
+        query += " WHERE " + " AND ".join(clauses)
+    return f"{query} ORDER BY [System.ChangedDate] DESC"
 
 
-def run_wiql(session: requests.Session, remote: AdoRemote, wiql: str, top: int) -> list[int]:
+def run_wiql(session: requests.Session, remote: AdoRemote, wiql: str, top: int, org_wide: bool = False) -> list[int]:
+    """`org_wide` runs the query against the org-level WIQL endpoint (no `/{project}` segment),
+    which Azure DevOps resolves across every project in the org instead of just `remote.project`.
+    """
+    base = _org_url(remote) if org_wide else _base_url(remote)
     r = session.post(
-        f"{_base_url(remote)}/_apis/wit/wiql",
+        f"{base}/_apis/wit/wiql",
         params={"api-version": "7.1", "$top": top},
         json={"query": wiql},
     )
@@ -457,16 +484,23 @@ def run_wiql(session: requests.Session, remote: AdoRemote, wiql: str, top: int)
     return [wi["id"] for wi in r.json()["workItems"]]
 
 
-def get_work_items(session: requests.Session, remote: AdoRemote, ids: list[int]) -> list[dict]:
-    """Batch-fetch Title/State for a set of work item ids, in the given `ids` order — WIQL only
-    returns ids (not field values), and this batch endpoint doesn't guarantee it echoes them back
-    in the order they were requested, so the caller's WIQL `ORDER BY` isn't preserved otherwise.
+def get_work_items(session: requests.Session, remote: AdoRemote, ids: list[int], org_wide: bool = False) -> list[dict]:
+    """Batch-fetch Title/State (plus TeamProject when `org_wide`) for a set of work item ids, in
+    the given `ids` order — WIQL only returns ids (not field values), and this batch endpoint
+    doesn't guarantee it echoes them back in the order they were requested, so the caller's WIQL
+    `ORDER BY` isn't preserved otherwise.
+
+    `org_wide` fetches via the org-level endpoint (ids from an org-wide `run_wiql` may belong to
+    a project other than `remote.project`) and also asks for `System.TeamProject`, so `search()`
+    can show which project each result came from.
     """
     if not ids:
         return []
+    base = _org_url(remote) if org_wide else _base_url(remote)
+    fields = "System.Title,System.State,System.TeamProject" if org_wide else "System.Title,System.State"
     r = session.get(
-        f"{_base_url(remote)}/_apis/wit/workitems",
-        params={"ids": ",".join(map(str, ids)), "fields": "System.Title,System.State", "api-version": "7.1"},
+        f"{base}/_apis/wit/workitems",
+        params={"ids": ",".join(map(str, ids)), "fields": fields, "api-version": "7.1"},
     )
     r.raise_for_status()
     by_id = {item["id"]: item for item in r.json()["value"]}
@@ -481,19 +515,31 @@ def search(
     board: str | None = None,
     top: int = 10,
     state: str = "open",
+    org_wide: bool = False,
+    tags: list[str] | None = None,
 ) -> list[dict]:
     """Search (or, with no keywords, just list) work items by keywords (ANDed, matched against
     Title or Description) and state, most recently changed first. `board` is an Azure Boards team
     name (like `create`'s `--board`) — resolved to its Area Path so results are scoped to that
-    team's subtree instead of the whole project.
+    team's subtree instead of the whole project. `tags` is a separate ANDed filter against
+    `System.Tags` (see `build_search_wiql`) -- a plain keyword doesn't match tags.
+
+    `org_wide` searches every project in `remote.org` instead of just `remote.project` --
+    mutually exclusive with `board`, since a team's Area Path only means something within a
+    single project.
     """
+    if org_wide and board:
+        sys.exit("--board can't be combined with --org-wide (a board's Area Path is scoped to a single project).")
     area_path = get_team_area_path(session, remote, board) if board else None
-    ids = run_wiql(session, remote, build_search_wiql(keywords, since, area_path, state), top)
-    items = get_work_items(session, remote, ids)
+    wiql = build_search_wiql(keywords, since, area_path, state, org_wide=org_wide, tags=tags)
+    ids = run_wiql(session, remote, wiql, top, org_wide=org_wide)
+    items = get_work_items(session, remote, ids, org_wide=org_wide)
     for item in items:
         fields = item["fields"]
-        print(f"#{item['id']} [{fields['System.State']}] {fields['System.Title']}")
-        print(edit_url(remote, item["id"]))
+        project = fields.get("System.TeamProject")
+        prefix = f"[{project}] " if org_wide else ""
+        print(f"{prefix}#{item['id']} [{fields['System.State']}] {fields['System.Title']}")
+        print(edit_url(remote, item["id"], project if org_wide else None))
     if not items:
         print("No matching work items found.")
     return items
@@ -534,12 +580,20 @@ def update(
     description: str | None = None,
     board: str | None = None,
     tags: list[str] | None = None,
+    remove_tags: list[str] | None = None,
     state: str | None = None,
 ) -> dict | None:
     """Update a work item's fields. Unlike `create`, `board` is only resolved (and the Area Path only
     touched) when explicitly given — it never falls back to `[tool.bdt.ado].board`, so an unrelated
     field update (e.g. just `--title`) can't silently move the item to a different team's board.
 
+    `remove_tags` removes just those tags, leaving the rest untouched -- unlike `tags` (which
+    replaces the whole `System.Tags` field, mirroring GitHub's `--remove-label` alongside the
+    add/replace `--tag`/`--label`). If `tags` is also given, `remove_tags` is applied on top of it
+    (so a value in both wins as "removed"); otherwise the work item's current tags are fetched
+    first as the base to remove from -- see `add_tag` for why there's no single "remove one tag"
+    Azure DevOps patch op.
+
     If `state` isn't one of this work item's type's valid states (state names, and which ones are
     terminal, are defined per work item type per process template — e.g. a Basic-process Issue has
     'Done' but no 'Closed'), the state is left unchanged and a comment records the exact state that
@@ -567,11 +621,32 @@ def update(
             )
             applied_state = None
 
-    if title is None and description is None and area_path is None and tags is None and applied_state is None:
+    has_tag_change = tags is not None or bool(remove_tags)
+    if title is None and description is None and area_path is None and not has_tag_change and applied_state is None:
         if state is not None:
             print(f"Work item #{work_item_id}: '{state}' isn't a valid state here — noted in a comment.")
             return None
-        sys.exit("Nothing to update — provide at least one of --title, --description, --board, --tag, --state.")
+        sys.exit("Nothing to update — provide at least one of --title, --description, --board, --tag, --remove-tag, --state.")
+
+    if remove_tags:
+        removal_set = {t.casefold() for t in remove_tags}
+        if tags is not None:
+            # An explicit `tags` (full replace) always writes, same as plain --tag on its own --
+            # `remove_tags` here is just a filter on top of the caller-given replacement list.
+            tags = [t for t in tags if t.casefold() not in removal_set]
+        else:
+            current_tags = get_work_item_tags(session, remote, work_item_id)
+            filtered_tags = [t for t in current_tags if t.casefold() not in removal_set]
+            if filtered_tags != current_tags:
+                tags = filtered_tags
+            elif title is None and description is None and area_path is None and applied_state is None:
+                # None of `remove_tags` were actually present, and nothing else was given either --
+                # mirrors `add_tag`'s own idempotency check (same file) so this doesn't needlessly
+                # bump the work item's revision/history with a same-value System.Tags PATCH.
+                print(f"Work item #{work_item_id}: none of the given --remove-tag value(s) were present — nothing to do.")
+                return None
+            # else: leave `tags` as None -- other given fields still get their own ops below,
+            # without forcing a redundant, unchanged System.Tags op alongside them.
 
     if description is not None:
         description = ensure_agent_session_note(description, also_check=title)