specfact-cli 0.26.1__tar.gz → 0.26.2__tar.gz

{specfact_cli-0.26.1 → specfact_cli-0.26.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.26.1
+Version: 0.26.2
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.26.1 → specfact_cli-0.26.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.26.1"
+version = "0.26.2"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"

{specfact_cli-0.26.1 → specfact_cli-0.26.2}/resources/prompts/specfact.backlog-refine.md

@@ -36,9 +36,23 @@ Refine backlog items from DevOps tools (GitHub Issues, Azure DevOps, etc.) into
 
 **Azure DevOps Adapter:**
 
-- `--ado-org ORG` - Azure DevOps organization (required for ADO adapter)
+- `--ado-org ORG` - Azure DevOps organization or collection name (required for ADO adapter, except when collection is in base_url)
 - `--ado-project PROJECT` - Azure DevOps project (required for ADO adapter)
-- `--ado-token TOKEN` - Azure DevOps PAT (optional, uses AZURE_DEVOPS_TOKEN env var if not provided)
+- `--ado-base-url URL` - Azure DevOps base URL (optional, defaults to `https://dev.azure.com` for cloud)
+  - **Cloud**: `https://dev.azure.com` (default)
+  - **On-premise**: `https://server` or `https://server/tfs/collection` (if collection included)
+- `--ado-token TOKEN` - Azure DevOps PAT (optional, uses AZURE_DEVOPS_TOKEN env var or stored token if not provided)
+
+**ADO Configuration Notes:**
+
+- **Cloud (Azure DevOps Services)**: Always requires `--ado-org` and `--ado-project`. Base URL defaults to `https://dev.azure.com`.
+- **On-premise (Azure DevOps Server)**:
+  - If base URL includes collection (e.g., `https://server/tfs/DefaultCollection`), `--ado-org` is optional.
+  - If base URL doesn't include collection, provide collection name via `--ado-org`.
+- **API Endpoints**:
+  - WIQL queries use POST to `{base_url}/{org}/{project}/_apis/wit/wiql?api-version=7.1` (project-level)
+  - Work items batch GET uses `{base_url}/{org}/_apis/wit/workitems?ids={ids}&api-version=7.1` (organization-level)
+  - The `api-version` parameter is **required** for all ADO API calls
 
 ### Filters
 
@@ -234,9 +248,15 @@ Items updated in remote backlog:
 # Refine GitHub issues with feature label (requires repo-owner and repo-name)
 /specfact.backlog-refine --adapter github --repo-owner nold-ai --repo-name specfact-cli --labels feature
 
-# Refine ADO work items in specific sprint (requires ado-org and ado-project)
+# Refine ADO work items (Azure DevOps Services - cloud)
 /specfact.backlog-refine --adapter ado --ado-org my-org --ado-project my-project --sprint "Sprint 1"
 
+# Refine ADO work items (Azure DevOps Server - on-premise, collection in base_url)
+/specfact.backlog-refine --adapter ado --ado-base-url "https://devops.company.com/tfs/DefaultCollection" --ado-project my-project --state Active
+
+# Refine ADO work items (Azure DevOps Server - on-premise, collection provided)
+/specfact.backlog-refine --adapter ado --ado-base-url "https://devops.company.com" --ado-org "DefaultCollection" --ado-project my-project --state Active
+
 # Refine with Scrum framework and Product Owner persona
 /specfact.backlog-refine --adapter github --repo-owner nold-ai --repo-name specfact-cli --framework scrum --persona product-owner
 
@@ -263,6 +283,30 @@ Items updated in remote backlog:
 # specfact sync bridge --adapter github --repo-owner my-org --repo-name my-repo --mode bidirectional
 ```
 
+## Troubleshooting
+
+### ADO API Errors
+
+**Error: "No HTTP resource was found that matches the request URI"**
+
+- **Cause**: Missing `api-version` parameter or incorrect URL format
+- **Solution**: Ensure `api-version=7.1` is included in all ADO API URLs. Check base URL format for on-premise installations.
+
+**Error: "The requested resource does not support http method 'GET'"**
+
+- **Cause**: Attempting to use GET on WIQL endpoint (which requires POST)
+- **Solution**: WIQL queries must use POST method with JSON body containing the query. This is handled automatically by SpecFact CLI.
+
+**Error: Organization removed from request string**
+
+- **Cause**: Incorrect base URL format (may already include organization/collection)
+- **Solution**: For on-premise, check if base URL already includes collection. If yes, omit `--ado-org` or adjust base URL accordingly.
+
+**Error: "Azure DevOps API token required"**
+
+- **Cause**: Missing authentication token
+- **Solution**: Provide token via `--ado-token`, `AZURE_DEVOPS_TOKEN` environment variable, or use `specfact auth azure-devops` for device code flow.
+
 ## Context
 
 {ARGS}

{specfact_cli-0.26.1 → specfact_cli-0.26.2}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Define the package version (kept in sync with pyproject.toml and setup.py)
-__version__ = "0.26.1"
+__version__ = "0.26.2"

{specfact_cli-0.26.1 → specfact_cli-0.26.2}/src/specfact_cli/__init__.py

@@ -9,6 +9,6 @@ This package provides command-line tools for:
 - Validating reproducibility
 """
 
-__version__ = "0.26.1"
+__version__ = "0.26.2"
 
 __all__ = ["__version__"]

{specfact_cli-0.26.1 → specfact_cli-0.26.2}/src/specfact_cli/adapters/ado.py

@@ -84,9 +84,100 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             self.auth_scheme = None
 
         # Base URL defaults to Azure DevOps Services (cloud)
-        self.base_url = base_url or "https://dev.azure.com"
+        # Normalize base_url: remove trailing slashes
+        # Note: For Azure DevOps Services (cloud), base_url should be "https://dev.azure.com"
+        # For Azure DevOps Server (on-premise), base_url might be "https://server" or "https://server/collection"
+        raw_base_url = base_url or "https://dev.azure.com"
+        self.base_url = raw_base_url.rstrip("/")
         self.work_item_type = work_item_type
 
+    def _is_on_premise(self) -> bool:
+        """
+        Detect if this is Azure DevOps Server (on-premise) vs Azure DevOps Services (cloud).
+
+        Returns:
+            True if on-premise (base_url doesn't contain dev.azure.com), False if cloud
+        """
+        return "dev.azure.com" not in self.base_url.lower()
+
+    def _build_ado_url(self, path: str, api_version: str = "7.1") -> str:
+        """
+        Build Azure DevOps API URL with proper formatting.
+
+        Supports both:
+        - Azure DevOps Services (cloud): https://dev.azure.com/{org}/{project}/_apis/...
+        - Azure DevOps Server (on-premise): https://{server}/tfs/{collection}/{project}/_apis/...
+                                          or https://{server}/{collection}/{project}/_apis/...
+
+        Args:
+            path: API path (e.g., "_apis/wit/workitems", "_apis/wit/wiql")
+            api_version: API version (default: "7.1")
+
+        Returns:
+            Full URL with proper format based on cloud vs on-premise
+
+        Note:
+            For on-premise, if base_url already includes /tfs/{collection} or /{collection},
+            it won't add org again. For cloud, always adds {org}/{project}.
+        """
+        if not self.project:
+            raise ValueError(f"project required to build ADO URL (project={self.project!r})")
+
+        # Normalize base_url (remove trailing slashes)
+        base_url_normalized = self.base_url.rstrip("/")
+
+        # Normalize path (remove leading slashes)
+        path_normalized = path.lstrip("/")
+
+        is_on_premise = self._is_on_premise()
+
+        if is_on_premise:
+            # Azure DevOps Server (on-premise)
+            # Format could be:
+            # - https://server/tfs/collection/{project}/_apis/... (older TFS format)
+            # - https://server/collection/{project}/_apis/... (newer format)
+            # - https://server/{project}/_apis/... (if collection in base_url)
+
+            base_lower = base_url_normalized.lower()
+            has_tfs = "/tfs/" in base_lower
+
+            # Check if base_url already includes a collection path
+            # If base_url contains /tfs/ or has more than just protocol + domain, collection is likely included
+            parts = [p for p in base_url_normalized.rstrip("/").split("/") if p and p not in ["http:", "https:"]]
+            # Collection is in base_url if:
+            # 1. It contains /tfs/ (older TFS format: server/tfs/collection)
+            # 2. It has more than 1 part after protocol (e.g., server/collection)
+            has_collection_in_base = has_tfs or len(parts) > 1
+
+            if has_collection_in_base:
+                # Collection already in base_url, just add project
+                url = f"{base_url_normalized}/{self.project}/{path_normalized}?api-version={api_version}"
+            elif self.org:
+                # Collection not in base_url, need to add it
+                # For on-premise, typically use /tfs/{collection} format unless explicitly newer format
+                # But if base_url doesn't have /tfs/, use newer format
+                if "/tfs" in base_url_normalized.lower() or not has_tfs:
+                    # If base_url mentions tfs anywhere or we're not sure, use /tfs/ format
+                    # Actually, if has_tfs is False, we should use newer format
+                    url = f"{base_url_normalized}/{self.org}/{self.project}/{path_normalized}?api-version={api_version}"
+                else:
+                    # Use /tfs/ format for older TFS servers
+                    url = f"{base_url_normalized}/tfs/{self.org}/{self.project}/{path_normalized}?api-version={api_version}"
+            else:
+                # No org provided, assume collection is in base_url or use project directly
+                console.print(
+                    "[yellow]Warning:[/yellow] On-premise detected but org (collection) not provided. Assuming collection is in base_url."
+                )
+                url = f"{base_url_normalized}/{self.project}/{path_normalized}?api-version={api_version}"
+        else:
+            # Azure DevOps Services (cloud)
+            # Format: https://dev.azure.com/{org}/{project}/_apis/...
+            if not self.org:
+                raise ValueError(f"org required for Azure DevOps Services (cloud) (org={self.org!r})")
+            url = f"{base_url_normalized}/{self.org}/{self.project}/{path_normalized}?api-version={api_version}"
+
+        return url
+
     # BacklogAdapterMixin abstract method implementations
 
     @beartype
@@ -2223,8 +2314,11 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             raise ValueError(msg)
 
         # Build WIQL (Work Item Query Language) query
-        wiql_parts = ["SELECT [System.Id], [System.Title], [System.State]"]
+        # WIQL syntax: SELECT fields FROM WorkItems WHERE conditions
+        # Use @project macro to reference the project context in project-scoped queries
+        wiql_parts = ["SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType]"]
         wiql_parts.append("FROM WorkItems")
+        # Use @project macro for project context (ADO automatically resolves this in project-scoped queries)
         wiql_parts.append("WHERE [System.TeamProject] = @project")
 
         conditions = []
@@ -2247,15 +2341,44 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
         wiql = " ".join(wiql_parts)
 
         # Execute WIQL query
-        url = f"{self.base_url}/{self.org}/{self.project}/_apis/wit/wiql"
+        # POST to project-level endpoint: {org}/{project}/_apis/wit/wiql?api-version=7.1
+        url = self._build_ado_url("_apis/wit/wiql", api_version="7.1")
         headers = {
             "Authorization": f"{self.auth_scheme} {self.api_token}" if self.auth_scheme else f"Basic {self.api_token}",
             "Content-Type": "application/json",
+            "Accept": "application/json",
         }
         payload = {"query": wiql}
 
-        response = requests.post(url, headers=headers, json=payload, timeout=30)
-        response.raise_for_status()
+        # Debug: Log URL construction for troubleshooting
+        console.print(f"[dim]ADO WIQL URL: {url}[/dim]")
+
+        try:
+            response = requests.post(url, headers=headers, json=payload, timeout=30)
+            response.raise_for_status()
+        except requests.HTTPError as e:
+            # Provide better error message with URL details
+            error_detail = ""
+            if e.response is not None:
+                try:
+                    error_json = e.response.json()
+                    error_detail = f"\nResponse: {error_json}"
+                except Exception:
+                    error_detail = f"\nResponse status: {e.response.status_code}"
+
+            error_msg = (
+                f"Azure DevOps API error: {e}{error_detail}\n"
+                f"URL: {url}\n"
+                f"Organization: {self.org}\n"
+                f"Project: {self.project}\n"
+                f"Base URL: {self.base_url}\n"
+                f"Expected format: https://dev.azure.com/{{org}}/{{project}}/_apis/wit/wiql?api-version=7.1\n"
+                f"If using Azure DevOps Server (on-premise), base_url format may differ."
+            )
+            # Create new exception with better message
+            new_exception = requests.HTTPError(error_msg)
+            new_exception.response = e.response
+            raise new_exception from e
         query_result = response.json()
 
         work_item_ids = [item["id"] for item in query_result.get("workItems", [])]
@@ -2264,18 +2387,84 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             return []
 
         # Fetch work item details
+        # Note: GET workitems by IDs uses organization-level endpoint, not project-level
+        # Format: https://dev.azure.com/{organization}/_apis/wit/workitems?ids={ids}&api-version={version}
         items: list[BacklogItem] = []
         batch_size = 200  # ADO API limit
 
+        # Build organization-level URL for work items batch fetch
+        base_url_normalized = self.base_url.rstrip("/")
+        is_on_premise = self._is_on_premise()
+
+        # For work items batch GET, URL is at organization level (not project level)
+        if is_on_premise:
+            # On-premise: if base_url has collection, use it; otherwise add org
+            parts = [p for p in base_url_normalized.split("/") if p and p not in ["http:", "https:"]]
+            has_collection_in_base = "/tfs/" in base_url_normalized.lower() or len(parts) > 1
+
+            if has_collection_in_base:
+                # Collection already in base_url
+                workitems_base_url = base_url_normalized
+            elif self.org:
+                # Need to add collection
+                if "/tfs" in base_url_normalized.lower():
+                    workitems_base_url = f"{base_url_normalized}/tfs/{self.org}"
+                else:
+                    workitems_base_url = f"{base_url_normalized}/{self.org}"
+            else:
+                workitems_base_url = base_url_normalized
+        else:
+            # Cloud: organization level
+            if not self.org:
+                raise ValueError(f"org required for Azure DevOps Services (cloud) (org={self.org!r})")
+            workitems_base_url = f"{base_url_normalized}/{self.org}"
+
         for i in range(0, len(work_item_ids), batch_size):
             batch = work_item_ids[i : i + batch_size]
             ids_str = ",".join(str(wi_id) for wi_id in batch)
 
-            url = f"{self.base_url}/{self.org}/{self.project}/_apis/wit/workitems"
+            # Work items batch GET is at organization level, not project level
+            # Format: {org}/_apis/wit/workitems?ids={ids}&api-version=7.1
+            url = f"{workitems_base_url}/_apis/wit/workitems?api-version=7.1"
             params = {"ids": ids_str, "$expand": "all"}
 
-            response = requests.get(url, headers=headers, params=params, timeout=30)
-            response.raise_for_status()
+            # Headers for work items batch GET (organization-level endpoint)
+            workitems_headers = {
+                "Authorization": f"{self.auth_scheme} {self.api_token}"
+                if self.auth_scheme
+                else f"Basic {self.api_token}",
+                "Accept": "application/json",
+            }
+
+            # Debug: Log URL construction for troubleshooting
+            console.print(f"[dim]ADO WorkItems URL: {url}&ids={ids_str}[/dim]")
+
+            try:
+                response = requests.get(url, headers=workitems_headers, params=params, timeout=30)
+                response.raise_for_status()
+            except requests.HTTPError as e:
+                # Provide better error message with URL details
+                error_detail = ""
+                if e.response is not None:
+                    try:
+                        error_json = e.response.json()
+                        error_detail = f"\nResponse: {error_json}"
+                    except Exception:
+                        error_detail = f"\nResponse status: {e.response.status_code}"
+
+                error_msg = (
+                    f"Azure DevOps API error: {e}{error_detail}\n"
+                    f"URL: {url}\n"
+                    f"Organization: {self.org}\n"
+                    f"Project: {self.project}\n"
+                    f"Base URL: {self.base_url}\n"
+                    f"Expected format: https://dev.azure.com/{{org}}/{{project}}/_apis/wit/workitems?ids={{ids}}&api-version=7.1\n"
+                    f"If using Azure DevOps Server (on-premise), base_url format may differ."
+                )
+                # Create new exception with better message
+                new_exception = requests.HTTPError(error_msg)
+                new_exception.response = e.response
+                raise new_exception from e
             work_items_data = response.json()
 
             # Convert ADO work items to BacklogItem
@@ -2354,7 +2543,7 @@ class AdoAdapter(BridgeAdapter, BacklogAdapterMixin, BacklogAdapter):
             raise ValueError(msg)
 
         work_item_id = int(item.id)
-        url = f"{self.base_url}/{self.org}/{self.project}/_apis/wit/workitems/{work_item_id}"
+        url = self._build_ado_url(f"_apis/wit/workitems/{work_item_id}", api_version="7.1")
         headers = {
             "Authorization": f"{self.auth_scheme} {self.api_token}" if self.auth_scheme else f"Basic {self.api_token}",
             "Content-Type": "application/json-patch+json",