ado-search 0.1.0__tar.gz

ado_search-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: ado-search
+Version: 0.1.0
+Summary: Sync and search Azure DevOps work items and wiki pages for AI agents
+Author: Samuel Hurley
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/HurleySk/ado-search
+Project-URL: Repository, https://github.com/HurleySk/ado-search
+Project-URL: Issues, https://github.com/HurleySk/ado-search/issues
+Keywords: azure-devops,search,work-items,wiki,agents
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+
+# ado-search
+
+Sync and search Azure DevOps work items and wiki pages locally for AI agents.
+
+## Install
+
+```bash
+pip install ado-search
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/HurleySk/ado-search.git
+```
+
+## Quick Start
+
+```bash
+# Configure (requires az login first)
+ado-search init --org https://dev.azure.com/yourorg --project YourProject
+
+# Pull data
+ado-search sync
+
+# Search
+ado-search search "login bug"
+ado-search search "auth" --type Bug --state Active
+ado-search search "setup guide" --format paths
+```
+
+## How It Works
+
+1. **Sync** pulls work items and wiki pages from Azure DevOps
+   - Tries **OData analytics** first (fetches all items in one call — fast)
+   - Falls back to **az devops CLI** if analytics isn't available
+2. Content is stored as compact **markdown files** (one per item)
+3. Metadata is indexed in **SQLite with FTS5** for fast full-text search
+4. Agents search the index, then read only the files they need — minimal context
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ado-search init` | Configure organization, project, and auth |
+| `ado-search sync` | Pull latest data from Azure DevOps |
+| `ado-search search "query"` | Full-text search with filters |
+| `ado-search show <id>` | Display full content of an item |
+
+## Auth Methods
+
+- **az-cli** (default): Uses `az devops` commands. Requires `az login`.
+- **az-powershell**: Uses Azure PowerShell + REST. Requires `Connect-AzAccount`.
+
+Set via `ado-search init --auth-method az-powershell` or in `config.toml`.
+
+## Search Formats
+
+```bash
+ado-search search "query"                          # compact (default)
+ado-search search "query" --format detail           # with description snippets
+ado-search search "query" --format json             # machine-readable
+ado-search search "query" --format paths            # file paths only (for agent piping)
+ado-search search "query" --type Bug --state Active # filtered
+```
+
+## Prerequisites
+
+- Python 3.10+
+- Azure CLI with `azure-devops` extension (`az extension add --name azure-devops`)
+- `az login` completed

ado_search-0.1.0/README.md

@@ -0,0 +1,71 @@
+# ado-search
+
+Sync and search Azure DevOps work items and wiki pages locally for AI agents.
+
+## Install
+
+```bash
+pip install ado-search
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/HurleySk/ado-search.git
+```
+
+## Quick Start
+
+```bash
+# Configure (requires az login first)
+ado-search init --org https://dev.azure.com/yourorg --project YourProject
+
+# Pull data
+ado-search sync
+
+# Search
+ado-search search "login bug"
+ado-search search "auth" --type Bug --state Active
+ado-search search "setup guide" --format paths
+```
+
+## How It Works
+
+1. **Sync** pulls work items and wiki pages from Azure DevOps
+   - Tries **OData analytics** first (fetches all items in one call — fast)
+   - Falls back to **az devops CLI** if analytics isn't available
+2. Content is stored as compact **markdown files** (one per item)
+3. Metadata is indexed in **SQLite with FTS5** for fast full-text search
+4. Agents search the index, then read only the files they need — minimal context
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `ado-search init` | Configure organization, project, and auth |
+| `ado-search sync` | Pull latest data from Azure DevOps |
+| `ado-search search "query"` | Full-text search with filters |
+| `ado-search show <id>` | Display full content of an item |
+
+## Auth Methods
+
+- **az-cli** (default): Uses `az devops` commands. Requires `az login`.
+- **az-powershell**: Uses Azure PowerShell + REST. Requires `Connect-AzAccount`.
+
+Set via `ado-search init --auth-method az-powershell` or in `config.toml`.
+
+## Search Formats
+
+```bash
+ado-search search "query"                          # compact (default)
+ado-search search "query" --format detail           # with description snippets
+ado-search search "query" --format json             # machine-readable
+ado-search search "query" --format paths            # file paths only (for agent piping)
+ado-search search "query" --type Bug --state Active # filtered
+```
+
+## Prerequisites
+
+- Python 3.10+
+- Azure CLI with `azure-devops` extension (`az extension add --name azure-devops`)
+- `az login` completed

ado_search-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ado-search"
+version = "0.1.0"
+description = "Sync and search Azure DevOps work items and wiki pages for AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{name = "Samuel Hurley"}]
+keywords = ["azure-devops", "search", "work-items", "wiki", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "click>=8.0",
+    "tomli>=2.0; python_version < '3.11'",
+]
+
+[project.urls]
+Homepage = "https://github.com/HurleySk/ado-search"
+Repository = "https://github.com/HurleySk/ado-search"
+Issues = "https://github.com/HurleySk/ado-search/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+]
+
+[project.scripts]
+ado-search = "ado_search.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

ado_search-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ado_search-0.1.0/src/ado_search/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

ado_search-0.1.0/src/ado_search/auth.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+ADO_RESOURCE_ID = "499b84ac-1321-427f-aa17-267ca6975798"
+
+
+def build_az_cli_command(
+    operation: str,
+    *,
+    org: str,
+    project: str,
+    wiql: str | None = None,
+    work_item_id: int | None = None,
+    wiki: str | None = None,
+    path: str | None = None,
+    url: str | None = None,
+) -> list[str]:
+    base = ["az"]
+
+    if operation == "query":
+        return [*base, "boards", "query",
+                "--wiql", wiql,
+                "--org", org, "--project", project,
+                "--output", "json"]
+
+    if operation == "show":
+        return [*base, "boards", "work-item", "show",
+                "--id", str(work_item_id),
+                "--org", org,
+                "--output", "json"]
+
+    if operation == "wiki-list":
+        return [*base, "devops", "wiki", "list",
+                "--org", org, "--project", project,
+                "--output", "json"]
+
+    if operation == "wiki-page-list":
+        # az devops wiki page show doesn't return subPages recursively,
+        # so use az rest with the wiki pages API and recursionLevel=full
+        # Note: & must be escaped for Windows cmd.exe batch file processing
+        api_url = f"{org}/{project}/_apis/wiki/wikis/{wiki}/pages"
+        return [*base, "rest", "--method", "get",
+                "--resource", ADO_RESOURCE_ID,
+                "--url", api_url,
+                "--url-parameters", "path=/", "recursionLevel=full", "api-version=7.1",
+                "--output", "json"]
+
+    if operation == "wiki-page-show":
+        api_url = f"{org}/{project}/_apis/wiki/wikis/{wiki}/pages"
+        return [*base, "rest", "--method", "get",
+                "--resource", ADO_RESOURCE_ID,
+                "--url", api_url,
+                "--url-parameters", f"path={path}", "includeContent=true", "api-version=7.1",
+                "--output", "json"]
+
+    if operation == "comments":
+        return [*base, "devops", "invoke",
+                "--area", "wit", "--resource", "comments",
+                "--route-parameters", f"id={work_item_id}",
+                "--org", org,
+                "--api-version", "7.1-preview.4",
+                "--output", "json"]
+
+    if operation == "odata-query":
+        return [*base, "rest", "--method", "get",
+                "--resource", ADO_RESOURCE_ID,
+                "--url", url,
+                "--output", "json"]
+
+    raise ValueError(f"Unknown operation: {operation}")
+
+
+def build_powershell_command(
+    operation: str,
+    *,
+    org: str,
+    project: str,
+    wiql: str | None = None,
+    work_item_id: int | None = None,
+    wiki: str | None = None,
+    path: str | None = None,
+    url: str | None = None,
+) -> list[str]:
+    token_expr = f"(Get-AzAccessToken -ResourceUrl '{ADO_RESOURCE_ID}').Token"
+    headers = '@{Authorization = "Bearer $token"; "Content-Type" = "application/json"}'
+
+    safe_org = _escape_ps(org)
+    safe_project = _escape_ps(project)
+    safe_wiki = _escape_ps(wiki)
+
+    if operation == "query":
+        api_url = f"{safe_org}/{safe_project}/_apis/wit/wiql?api-version=7.1"
+        body = '{{"query": "{wiql}"}}'.replace("{wiql}", _escape_ps(wiql))
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"$body = '{body}'; "
+            f"Invoke-RestMethod -Uri '{api_url}' -Method Post -Headers $headers -Body $body | ConvertTo-Json -Depth 10"
+        )
+    elif operation == "show":
+        api_url = f"{safe_org}/{safe_project}/_apis/wit/workitems/{work_item_id}?$expand=all&api-version=7.1"
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"Invoke-RestMethod -Uri '{api_url}' -Method Get -Headers $headers | ConvertTo-Json -Depth 10"
+        )
+    elif operation == "wiki-list":
+        api_url = f"{safe_org}/{safe_project}/_apis/wiki/wikis?api-version=7.1"
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"Invoke-RestMethod -Uri '{api_url}' -Method Get -Headers $headers | ConvertTo-Json -Depth 10"
+        )
+    elif operation == "wiki-page-list":
+        api_url = f"{safe_org}/{safe_project}/_apis/wiki/wikis/{safe_wiki}/pages?recursionLevel=full&api-version=7.1"
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"Invoke-RestMethod -Uri '{api_url}' -Method Get -Headers $headers | ConvertTo-Json -Depth 10"
+        )
+    elif operation == "wiki-page-show":
+        safe_path = _escape_ps(path)
+        encoded_path = safe_path.replace("/", "%2F") if safe_path else ""
+        api_url = f"{safe_org}/{safe_project}/_apis/wiki/wikis/{safe_wiki}/pages?path={encoded_path}&includeContent=true&api-version=7.1"
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"Invoke-RestMethod -Uri '{api_url}' -Method Get -Headers $headers | ConvertTo-Json -Depth 10"
+        )
+    elif operation == "comments":
+        api_url = f"{safe_org}/{safe_project}/_apis/wit/workitems/{work_item_id}/comments?api-version=7.1-preview.4"
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"Invoke-RestMethod -Uri '{api_url}' -Method Get -Headers $headers | ConvertTo-Json -Depth 10"
+        )
+    elif operation == "odata-query":
+        safe_url = _escape_ps(url)
+        script = (
+            f"$token = {token_expr}; "
+            f"$headers = {headers}; "
+            f"Invoke-RestMethod -Uri '{safe_url}' -Method Get -Headers $headers | ConvertTo-Json -Depth 10"
+        )
+    else:
+        raise ValueError(f"Unknown operation: {operation}")
+
+    return ["pwsh", "-NoProfile", "-Command", script]
+
+
+def _escape_ps(s: str | None) -> str:
+    if s is None:
+        return ""
+    return s.replace('"', '`"').replace("'", "''")
+
+
+def build_command(operation: str, auth_method: str, **kwargs) -> list[str]:
+    """Dispatch to az-cli or PowerShell command builder based on auth method."""
+    if auth_method == "az-cli":
+        return build_az_cli_command(operation, **kwargs)
+    return build_powershell_command(operation, **kwargs)

ado_search-0.1.0/src/ado_search/cli.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import asyncio
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+import click
+
+from ado_search.config import default_config, load_config, save_config
+from ado_search.db import Database
+from ado_search.search import search, format_results
+
+
+def _default_data_dir() -> Path:
+    return Path.cwd() / ".ado-search"
+
+
+@click.group()
+@click.version_option(package_name="ado-search")
+def main():
+    """Sync and search Azure DevOps data for AI agents."""
+    pass
+
+
+@main.command()
+@click.option("--org", prompt="Organization URL", help="e.g. https://dev.azure.com/contoso")
+@click.option("--project", prompt="Project name", help="Azure DevOps project name")
+@click.option("--auth-method", type=click.Choice(["az-cli", "az-powershell"]),
+              default="az-cli", help="Authentication method")
+@click.option("--data-dir", type=click.Path(), default=None,
+              help="Data directory (default: ./.ado-search)")
+def init(org: str, project: str, auth_method: str, data_dir: str | None):
+    """Initialize ado-search configuration."""
+    data_path = Path(data_dir) if data_dir else _default_data_dir()
+    data_path.mkdir(parents=True, exist_ok=True)
+
+    cfg = default_config()
+    cfg["organization"]["url"] = org
+    cfg["organization"]["project"] = project
+    cfg["auth"]["method"] = auth_method
+
+    config_path = data_path / "config.toml"
+    save_config(cfg, config_path)
+
+    db = Database(data_path / "index.db")
+    db.initialize()
+    db.close()
+
+    (data_path / "work-items").mkdir(exist_ok=True)
+    (data_path / "wiki").mkdir(exist_ok=True)
+
+    click.echo(f"Initialized ado-search at {data_path}")
+    click.echo(f"  Organization: {org}")
+    click.echo(f"  Project: {project}")
+    click.echo(f"  Auth method: {auth_method}")
+
+
+@main.command()
+@click.option("--data-dir", type=click.Path(exists=True), default=None)
+@click.option("--dry-run", is_flag=True, help="Show what would be synced without writing")
+def sync(data_dir: str | None, dry_run: bool):
+    """Sync work items and wiki pages from Azure DevOps."""
+    data_path = Path(data_dir) if data_dir else _default_data_dir()
+    config_path = data_path / "config.toml"
+
+    if not config_path.exists():
+        click.echo("Error: Not initialized. Run 'ado-search init' first.", err=True)
+        raise SystemExit(1)
+
+    cfg = load_config(config_path)
+    org = cfg["organization"]["url"]
+    project = cfg["organization"]["project"]
+    auth_method = cfg["auth"]["method"]
+    sync_cfg = cfg["sync"]
+
+    db = Database(data_path / "index.db")
+    db.initialize()
+
+    try:
+        from ado_search.sync_workitems import sync_work_items
+        from ado_search.sync_wiki import sync_wiki
+
+        click.echo("Syncing work items...")
+        wi_stats = asyncio.run(sync_work_items(
+            org=org, project=project, auth_method=auth_method,
+            data_dir=data_path, db=db,
+            work_item_types=sync_cfg.get("work_item_types", []),
+            area_paths=sync_cfg.get("area_paths", []),
+            states=sync_cfg.get("states", []),
+            last_sync=sync_cfg.get("last_sync", ""),
+            max_concurrent=sync_cfg.get("performance", {}).get("max_concurrent", 5),
+            dry_run=dry_run,
+        ))
+        click.echo(f"  Work items: {wi_stats['fetched']} synced, {wi_stats['errors']} errors")
+
+        click.echo("Syncing wiki pages...")
+        wiki_stats = asyncio.run(sync_wiki(
+            org=org, project=project, auth_method=auth_method,
+            data_dir=data_path, db=db,
+            wiki_names=sync_cfg.get("wiki_names", []),
+            max_concurrent=sync_cfg.get("performance", {}).get("max_concurrent", 5),
+            dry_run=dry_run,
+        ))
+        click.echo(f"  Wiki pages: {wiki_stats['fetched']} synced, {wiki_stats['errors']} errors")
+
+        if not dry_run:
+            cfg["sync"]["last_sync"] = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+            save_config(cfg, config_path)
+            click.echo("Sync complete.")
+
+    finally:
+        db.close()
+
+
+@main.command("search")
+@click.argument("query")
+@click.option("--type", "type_filter", default=None, help="Filter by work item type")
+@click.option("--state", "state_filter", default=None, help="Filter by state")
+@click.option("--area", "area_filter", default=None, help="Filter by area path (prefix match)")
+@click.option("--assigned-to", default=None, help="Filter by assignee email")
+@click.option("--tag", "tag_filter", default=None, help="Filter by tag")
+@click.option("--limit", default=20, type=int, help="Max results (default 20)")
+@click.option("--format", "fmt", type=click.Choice(["compact", "detail", "json", "paths"]),
+              default="compact", help="Output format")
+@click.option("--data-dir", type=click.Path(), default=None)
+def search_cmd(query, type_filter, state_filter, area_filter, assigned_to, tag_filter,
+               limit, fmt, data_dir):
+    """Search indexed Azure DevOps data."""
+    data_path = Path(data_dir) if data_dir else _default_data_dir()
+
+    if not (data_path / "index.db").exists():
+        click.echo("Error: No index found. Run 'ado-search init' and 'ado-search sync' first.", err=True)
+        raise SystemExit(1)
+
+    db = Database(data_path / "index.db")
+    db.initialize()
+
+    try:
+        results = search(
+            db, query, data_dir=data_path,
+            type_filter=type_filter, state_filter=state_filter,
+            area_filter=area_filter, assigned_to_filter=assigned_to,
+            tag_filter=tag_filter, limit=limit,
+        )
+
+        if not results:
+            click.echo(f'No results for "{query}"')
+            return
+
+        if fmt != "json":
+            click.echo(f'Results for "{query}" ({len(results)} matches):')
+
+        click.echo(format_results(results, fmt=fmt, data_dir=data_path))
+
+    finally:
+        db.close()
+
+
+@main.command()
+@click.argument("item_id")
+@click.option("--data-dir", type=click.Path(), default=None)
+def show(item_id: str, data_dir: str | None):
+    """Show full content of a work item or wiki page."""
+    data_path = Path(data_dir) if data_dir else _default_data_dir()
+
+    wi_path = data_path / "work-items" / f"{item_id}.md"
+    if wi_path.exists():
+        click.echo(wi_path.read_text(encoding="utf-8"))
+        return
+
+    wiki_path = data_path / "wiki" / f"{item_id.lstrip('/')}.md"
+    if wiki_path.exists():
+        click.echo(wiki_path.read_text(encoding="utf-8"))
+        return
+
+    click.echo(f"Error: Item '{item_id}' not found in work-items or wiki.", err=True)
+    raise SystemExit(1)

ado_search-0.1.0/src/ado_search/config.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+def default_config() -> dict:
+    return {
+        "organization": {
+            "url": "",
+            "project": "",
+        },
+        "auth": {
+            "method": "az-cli",
+        },
+        "sync": {
+            "work_item_types": ["Bug", "User Story", "Task", "Epic", "Feature"],
+            "area_paths": [],
+            "states": [],
+            "wiki_names": [],
+            "last_sync": "",
+            "performance": {
+                "max_concurrent": 5,
+            },
+        },
+    }
+
+
+def save_config(config: dict, path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = _dict_to_toml(config)
+    path.write_text(lines, encoding="utf-8")
+
+
+def load_config(path: Path) -> dict:
+    if not path.exists():
+        raise FileNotFoundError(f"Config not found: {path}")
+    with open(path, "rb") as f:
+        return tomllib.load(f)
+
+
+def _dict_to_toml(d: dict, prefix: str = "") -> str:
+    """Minimal TOML serializer for our config structure."""
+    lines: list[str] = []
+    tables: list[tuple[str, dict]] = []
+
+    for key, value in d.items():
+        if isinstance(value, dict):
+            full_key = f"{prefix}{key}" if not prefix else f"{prefix}.{key}"
+            tables.append((full_key, value))
+        elif isinstance(value, list):
+            items = ", ".join(f'"{v}"' if isinstance(v, str) else str(v) for v in value)
+            lines.append(f"{key} = [{items}]")
+        elif isinstance(value, str):
+            lines.append(f'{key} = "{value}"')
+        elif isinstance(value, bool):
+            lines.append(f"{key} = {'true' if value else 'false'}")
+        elif isinstance(value, int):
+            lines.append(f"{key} = {value}")
+
+    result = "\n".join(lines)
+    for table_key, table_val in tables:
+        section = _dict_to_toml(table_val, prefix=table_key)
+        result += f"\n\n[{table_key}]\n{section}"
+
+    return result.strip() + "\n"