datex-studio-cli 0.4.17__tar.gz → 0.4.18__tar.gz

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/CONTEXT.md

@@ -7,3 +7,7 @@ The command-line interface (`dxs`) through which LLM agents and humans work with
 **Quartermaster**:
 The Datex-owned service that is the dxs CLI's server-side counterpart — it issues supplies (skills, context) and keeps the records (telemetry, config index).
 _Avoid_: companion service, dxs backend, dxs service
+
+**Endpoint family**:
+A cohesive group of Quartermaster endpoints serving one CLI capability (telemetry ingest, feedback, skills distribution, OData proxy, config indexing, context store). The unit in which Quartermaster is composed, enabled, and — when one earns it — deployed separately.
+_Avoid_: module, microservice, subsystem

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datex-studio-cli
-Version: 0.4.17
+Version: 0.4.18
 Summary: CLI for Datex Studio low-code platform, designed for LLM-based AI agents
 Project-URL: Homepage, https://github.com/datex/datex-studio-cli
 Project-URL: Documentation, https://github.com/datex/datex-studio-cli

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "datex-studio-cli"
-version = "0.4.17"
+version = "0.4.18"
 description = "CLI for Datex Studio low-code platform, designed for LLM-based AI agents"
 readme = "README.md"
 license = "MIT"

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/src/dxs/__init__.py

@@ -1,4 +1,4 @@
 """Datex Studio CLI - Command-line interface for Datex Studio platform."""
 
-__version__ = "0.4.17"
+__version__ = "0.4.18"
 __app_name__ = "dxs"

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/src/dxs/commands/devops.py

@@ -1,13 +1,20 @@
-"""Azure DevOps commands: dxs devops [workitem|workitems|attachments]."""
+"""Azure DevOps commands: dxs devops [workitem|workitems|attachments|search|wiql]."""
 
 import pathlib
+from typing import Any
 
 import click
 
 from dxs.cli import DxsContext, pass_context
 from dxs.core.auth import require_auth
 from dxs.core.devops import AzureDevOpsClient
-from dxs.core.devops.helpers import resolve_attachment, resolve_devops_org
+from dxs.core.devops.helpers import (
+    chunk_ids,
+    resolve_attachment,
+    resolve_devops_org,
+    validate_wiql_query,
+)
+from dxs.core.devops.models import DevOpsWorkItemDto, WiqlResultDto
 from dxs.utils.errors import ValidationError
 from dxs.utils.responses import list_response, search_response, single
 
@@ -25,6 +32,7 @@ def devops() -> None:
         dxs devops workitems 1234,1235,1236 --org myorg
         dxs devops attachments 1234 --org myorg
         dxs devops search "login bug" --org myorg
+        dxs devops wiql "SELECT [System.Id],[System.Title] FROM WorkItems WHERE ..." --org myorg
     """
     pass
 
@@ -502,3 +510,220 @@ def search(
             includes_description=description,
         )
     )
+
+
+# WIQL matches are hydrated one work item at a time, so the cap keeps an
+# open-ended query from turning into hundreds of batch requests.
+MAX_WIQL_LIMIT = 1000
+
+# The work items batch API accepts at most 200 IDs per request.
+WIQL_BATCH_SIZE = 200
+
+
+def _hydrated_row(
+    item: DevOpsWorkItemDto,
+    columns: list[str],
+    include_id: bool = True,
+) -> dict:
+    """Shape one hydrated work item for WIQL output.
+
+    Uses the query's SELECT columns when the response reported any, and falls
+    back to the standard summary shape when it did not.
+    """
+    if columns:
+        return item.to_columns(columns, include_id=include_id)
+
+    summary = item.to_summary()
+    if not include_id:
+        summary.pop("id", None)
+    return summary
+
+
+@devops.command()
+@click.argument("query", required=False)
+@click.option(
+    "-Q",
+    "--query-file",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Read the WIQL query from a file instead of the QUERY argument",
+)
+@click.option(
+    "--org",
+    "organization",
+    required=False,
+    default=None,
+    help="Azure DevOps organization name",
+)
+@click.option(
+    "--project",
+    default=None,
+    help="Azure DevOps project name (required for @project and project-scoped queries)",
+)
+@click.option(
+    "--team",
+    default=None,
+    help="Azure DevOps team name for team macros like @currentIteration (requires --project)",
+)
+@click.option(
+    "--limit",
+    "-l",
+    type=int,
+    default=200,
+    help=f"Maximum results to return (default: 200, max: {MAX_WIQL_LIMIT})",
+)
+@click.option(
+    "--ids-only",
+    is_flag=True,
+    default=False,
+    help="Return matched IDs without fetching field values",
+)
+@pass_context
+@require_auth
+def wiql(
+    ctx: DxsContext,
+    query: str | None,
+    query_file: str | None,
+    organization: str | None,
+    project: str | None,
+    team: str | None,
+    limit: int,
+    ids_only: bool,
+) -> None:
+    """Run an ad-hoc WIQL query.
+
+    Executes the query server-side, then fetches exactly the fields named in
+    its SELECT clause for each match. Both query shapes are supported:
+
+    \b
+      FROM WorkItems      flat  — one row per work item
+      FROM WorkItemLinks  tree / one-hop — one row per source→target link,
+                          with the target's fields merged into the row
+
+    'metadata.total_count' is how many results the query matched;
+    'metadata.count' is how many came back after --limit. 'truncated' is true
+    when the cap was reached and the query may have matched more.
+
+    \b
+    Arguments:
+        QUERY  WIQL query text (omit when using --query-file)
+
+    \b
+    Options:
+        --org ORG          Azure DevOps organization name
+        --project PROJ     Project to scope the query to
+        --team TEAM        Team to scope the query to (requires --project)
+        -Q, --query-file   Read the query from a file
+        -l, --limit N      Maximum results (default: 200)
+        --ids-only         Return IDs only, skipping the field fetch
+
+    \b
+    Examples:
+        dxs devops wiql "SELECT [System.Id],[System.Title],[System.State] \
+FROM WorkItems WHERE [System.State] = 'Active' ORDER BY [System.ChangedDate] DESC"
+        dxs devops wiql -Q ./active-bugs.wiql --org myorg --limit 25
+        dxs devops wiql "SELECT [System.Id] FROM WorkItems WHERE [System.AssignedTo] = @me" --ids-only
+        dxs devops wiql "SELECT [System.Id],[System.Title] FROM WorkItemLinks \
+WHERE [Source].[System.Id] = 1234 AND [System.Links.LinkType] = 'System.LinkTypes.Hierarchy-Forward' \
+MODE (Recursive)" --project FootPrint
+    """
+    if query and query_file:
+        raise ValidationError(
+            message="Pass the query as an argument or with --query-file, not both.",
+            code="DXS-DEVOPS-WIQL-003",
+            suggestions=["Drop the QUERY argument, or drop --query-file"],
+        )
+
+    if not query and not query_file:
+        raise ValidationError(
+            message="A WIQL query is required.",
+            code="DXS-DEVOPS-WIQL-004",
+            suggestions=[
+                "dxs devops wiql \"SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'\"",
+                "dxs devops wiql -Q query.wiql",
+            ],
+        )
+
+    if team and not project:
+        raise ValidationError(
+            message="--team also needs --project.",
+            code="DXS-DEVOPS-WIQL-005",
+            suggestions=["Teams are scoped to a project: --project <name> --team <name>"],
+        )
+
+    if limit < 1 or limit > MAX_WIQL_LIMIT:
+        raise ValidationError(
+            message=f"--limit must be between 1 and {MAX_WIQL_LIMIT}.",
+            code="DXS-DEVOPS-WIQL-006",
+            suggestions=["Narrow the query with a WHERE clause instead of raising the cap"],
+        )
+
+    raw_query = pathlib.Path(query_file).read_text(encoding="utf-8") if query_file else str(query)
+    wiql_query = validate_wiql_query(raw_query)
+
+    org = resolve_devops_org(organization)
+    ctx.log(f"Running WIQL query against {org}...")
+
+    with AzureDevOpsClient(org) as client:
+        result = WiqlResultDto.from_response(
+            client.run_wiql(wiql_query, project=project, team=team, top=limit)
+        )
+
+        links = result.links[:limit]
+        if result.is_link_query:
+            total_count = len(result.links)
+            # A tree result lists every node exactly once as a target, so
+            # hydrating targets covers the whole graph.
+            page = [link.target_id for link in links]
+            page = list(dict.fromkeys(page))
+        else:
+            total_count = len(result.ids)
+            page = result.ids[:limit]
+
+        hydrated: dict[int, DevOpsWorkItemDto] = {}
+        if not ids_only and page:
+            if total_count > limit:
+                ctx.log(f"{total_count} matched; fetching the first {limit}...")
+            fields = result.columns or None
+            for batch in chunk_ids(page, size=WIQL_BATCH_SIZE):
+                for item in client.get_workitems_batch(batch, fields=fields):
+                    hydrated[item.id] = item
+
+    items: list[Any] = []
+    if result.is_link_query:
+        for link in links:
+            row: dict = {
+                "rel": link.rel,
+                "source_id": link.source_id,
+                "target_id": link.target_id,
+            }
+            target = hydrated.get(link.target_id)
+            if target is not None:
+                row.update(_hydrated_row(target, result.columns, include_id=False))
+            items.append(row)
+        semantic_key = "workitem_links"
+    elif ids_only:
+        items.extend(page)
+        semantic_key = "workitems"
+    else:
+        # The batch API does not guarantee request order; restore the WIQL one.
+        items.extend(_hydrated_row(hydrated[i], result.columns) for i in page if i in hydrated)
+        semantic_key = "workitems"
+
+    ctx.output(
+        search_response(
+            items=items,
+            query=wiql_query,
+            total_count=total_count,
+            semantic_key=semantic_key,
+            organization=org,
+            project=project,
+            team=team,
+            query_type=result.query_type,
+            columns=result.columns,
+            as_of=result.as_of,
+            limit=limit,
+            truncated=total_count >= limit,
+            ids_only=ids_only,
+        )
+    )

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/src/dxs/core/devops/client.py

@@ -355,6 +355,47 @@ class AzureDevOpsClient:
         data = self._make_request("POST", url, json_data={"query": wiql})
         return [int(ref["id"]) for ref in data.get("workItems", [])]
 
+    def run_wiql(
+        self,
+        query: str,
+        project: str | None = None,
+        team: str | None = None,
+        top: int | None = None,
+    ) -> dict[str, Any]:
+        """Run an arbitrary WIQL query and return the raw response.
+
+        The API answers with references only — ``workItems`` (ids) for a flat
+        query, ``workItemRelations`` (source/target pairs) for a tree or
+        one-hop query. Parse with ``WiqlResultDto.from_response()`` and hydrate
+        the ids with ``get_workitems_batch()``.
+
+        Args:
+            query: WIQL query text.
+            project: Optional project to scope the query to. Required for the
+                ``@project`` macro and any project-scoped query.
+            team: Optional team to scope the query to, for team macros such as
+                ``@currentIteration``. Requires ``project``.
+            top: Server-side cap on results ($top).
+
+        Returns:
+            Raw WIQL response body.
+
+        Raises:
+            ValueError: If ``team`` is given without ``project``.
+            ApiError: If the request fails.
+        """
+        if team and not project:
+            raise ValueError("A team-scoped WIQL query also needs a project")
+
+        scope = "".join(f"/{part}" for part in (project, team) if part)
+        url = f"{self.base_url}{scope}/_apis/wit/wiql"
+
+        params: dict[str, Any] = {}
+        if top is not None:
+            params["$top"] = top
+
+        return self._make_request("POST", url, params=params, json_data={"query": query})
+
     def get_workitem_discussions(
         self,
         workitem_id: int,

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/src/dxs/core/devops/helpers.py

@@ -74,3 +74,59 @@ def resolve_attachment(
         code="DXS-DEVOPS-ATTACH-002",
         suggestions=[f"Available attachments: {', '.join(names)}"],
     )
+
+
+def validate_wiql_query(text: str) -> str:
+    """Validate ad-hoc WIQL text and return it stripped.
+
+    WIQL is a read-only query language, so anything that is not a SELECT is a
+    typo rather than a dangerous statement — it is rejected locally to save a
+    round trip that could only fail.
+
+    Args:
+        text: Raw query text from the CLI argument or --query-file.
+
+    Returns:
+        The query, stripped of surrounding whitespace.
+
+    Raises:
+        ValidationError: If the query is empty or does not start with SELECT.
+    """
+    query = text.strip()
+
+    if not query:
+        raise ValidationError(
+            message="WIQL query cannot be empty.",
+            code="DXS-DEVOPS-WIQL-001",
+            suggestions=[
+                "dxs devops wiql \"SELECT [System.Id] FROM WorkItems WHERE [System.State] = 'Active'\"",
+                "Or pass a file: dxs devops wiql -Q query.wiql",
+            ],
+        )
+
+    if not query.upper().startswith("SELECT"):
+        raise ValidationError(
+            message="WIQL queries must start with SELECT.",
+            code="DXS-DEVOPS-WIQL-002",
+            details={"query": query[:200]},
+            suggestions=[
+                "WIQL is read-only — only SELECT statements are valid",
+                "Flat form:  SELECT [System.Id],[System.Title] FROM WorkItems WHERE ...",
+                "Link form:  SELECT [System.Id] FROM WorkItemLinks WHERE ... MODE (Recursive)",
+            ],
+        )
+
+    return query
+
+
+def chunk_ids(ids: list[int], size: int = 200) -> list[list[int]]:
+    """Split work item IDs into batches the work items API will accept.
+
+    Args:
+        ids: Work item IDs to hydrate.
+        size: Maximum IDs per batch (the API caps a batch request at 200).
+
+    Returns:
+        List of ID batches, in order.
+    """
+    return [ids[i : i + size] for i in range(0, len(ids), size)]

{datex_studio_cli-0.4.17 → datex_studio_cli-0.4.18}/src/dxs/core/devops/models.py

@@ -91,6 +91,30 @@ def _flatten_person(value: Any) -> str:
     return str(value) if value else ""
 
 
+# Reference names whose values arrive as HTML and are converted to markdown.
+_HTML_FIELD_REF_NAMES = frozenset(ref for ref, _ in _HTML_FIELDS)
+
+
+def format_field_value(reference_name: str, value: Any) -> Any:
+    """Normalize a raw work item field value for CLI output.
+
+    Identity objects collapse to their display name and known HTML fields are
+    converted to markdown; every other value passes through unchanged.
+
+    Args:
+        reference_name: Field reference name (e.g. "System.AssignedTo").
+        value: Raw value from the work item's fields dict.
+
+    Returns:
+        Value shaped for output.
+    """
+    if isinstance(value, dict) and "displayName" in value:
+        return _flatten_person(value)
+    if reference_name in _HTML_FIELD_REF_NAMES and isinstance(value, str) and value:
+        return _html_to_markdown(value)
+    return value
+
+
 class DevOpsWorkItemDto(BaseModel):
     """Azure DevOps work item information."""
 
@@ -281,6 +305,33 @@ class DevOpsWorkItemDto(BaseModel):
 
         return detail
 
+    def to_columns(self, columns: list[str], include_id: bool = True) -> dict[str, Any]:
+        """Project the work item onto an explicit column list.
+
+        Used by ad-hoc WIQL queries, where the caller's SELECT clause - not a
+        curated field set - decides what comes back. Columns are emitted in
+        SELECT order; a selected field the work item does not carry is emitted
+        as null so every row has the same keys.
+
+        Args:
+            columns: Field reference names from the WIQL SELECT clause.
+                "System.Id" is ignored - the id is emitted as "id".
+            include_id: Emit the leading "id" key. Link-query rows address the
+                work item as "target_id" instead, so they turn this off.
+
+        Returns:
+            One row: optional id, the selected columns, then the web url.
+        """
+        row: dict[str, Any] = {"id": self.id} if include_id else {}
+        for reference_name in columns:
+            if reference_name == "System.Id":
+                continue
+            row[reference_name] = format_field_value(
+                reference_name, self.fields.get(reference_name)
+            )
+        row["url"] = self.web_url or self.url
+        return row
+
     def to_summary(
         self, include_description: bool = False, include_discussions: bool = False
     ) -> dict[str, Any]:
@@ -324,3 +375,82 @@ class DevOpsWorkItemDto(BaseModel):
             summary["discussion_count"] = len(self.discussions)
 
         return summary
+
+
+class WiqlLinkDto(BaseModel):
+    """One source -> target pair from a link (tree / one-hop) WIQL result."""
+
+    rel: str | None = None
+    source_id: int | None = None
+    target_id: int
+
+
+class WiqlResultDto(BaseModel):
+    """Normalized WIQL response.
+
+    Azure DevOps answers a WIQL query with references only: a flat query
+    returns ``workItems`` (ids), a link query returns ``workItemRelations``
+    (source/target pairs). This model flattens both into ids to hydrate plus,
+    for link queries, the relations to report.
+    """
+
+    query_type: str = "flat"
+    columns: list[str] = Field(default_factory=list)
+    as_of: str | None = None
+    ids: list[int] = Field(default_factory=list)
+    links: list[WiqlLinkDto] = Field(default_factory=list)
+
+    @property
+    def is_link_query(self) -> bool:
+        """True when the query returned relations rather than a flat list."""
+        return bool(self.links) or self.query_type in ("tree", "oneHop")
+
+    @classmethod
+    def from_response(cls, data: dict[str, Any]) -> "WiqlResultDto":
+        """Parse a raw WIQL API response.
+
+        Args:
+            data: JSON body from POST _apis/wit/wiql.
+
+        Returns:
+            Normalized result. For link queries ``ids`` holds the distinct
+            target ids in response order - in a tree result every node appears
+            exactly once as a target, so hydrating targets covers every node.
+        """
+        columns = [
+            str(col["referenceName"])
+            for col in data.get("columns", [])
+            if isinstance(col, dict) and col.get("referenceName")
+        ]
+
+        links: list[WiqlLinkDto] = []
+        ids: list[int] = []
+
+        if "workItemRelations" in data:
+            seen: set[int] = set()
+            for relation in data.get("workItemRelations") or []:
+                target = relation.get("target") or {}
+                target_id = target.get("id")
+                if target_id is None:
+                    continue
+                source = relation.get("source") or {}
+                links.append(
+                    WiqlLinkDto(
+                        rel=relation.get("rel"),
+                        source_id=source.get("id"),
+                        target_id=int(target_id),
+                    )
+                )
+                if int(target_id) not in seen:
+                    seen.add(int(target_id))
+                    ids.append(int(target_id))
+        else:
+            ids = [int(ref["id"]) for ref in data.get("workItems") or [] if ref.get("id")]
+
+        return cls(
+            query_type=str(data.get("queryType", "flat")),
+            columns=columns,
+            as_of=data.get("asOf"),
+            ids=ids,
+            links=links,
+        )