scopedocs-cli 0.1.3__py3-none-any.whl

scopedocs_cli/__init__.py

@@ -0,0 +1,12 @@
+"""ScopeDocs CLI — explain services, map impact, ask questions.
+
+Three core commands:
+  scopedocs ask    "<question>"  — free-form Q&A
+  scopedocs impact <target>      — blast radius
+  scopedocs why    <target>      — governing decisions
+
+CLI talks live to the backend at /api/v1/*. Configure with
+`scopedocs auth login --api-key sk-sd_… --backend http://…`.
+"""
+
+__version__ = "0.1.3"

scopedocs_cli/client.py

@@ -0,0 +1,376 @@
+"""HTTP client wrapping the ScopeDocs backend `/api/v1/*` endpoints.
+
+Stateless · synchronous · API-key auth via `X-API-Key` header.
+
+Each method returns the raw JSON body. Higher-level mapping into render-ready
+shapes happens in command modules, not here — this layer stays thin.
+"""
+from __future__ import annotations
+
+import platform
+import sys
+import time
+from typing import Any, Optional
+
+import httpx
+
+from scopedocs_cli import __version__
+from scopedocs_cli.config import Config
+
+
+class ScopeDocsError(Exception):
+    """Base error for client-side failures.
+
+    `is_actionable` distinguishes engineering bugs (worth crash-reporting) from
+    user/network conditions. Telemetry layer should only forward actionable.
+    """
+
+    is_actionable: bool = True
+
+
+class AuthError(ScopeDocsError):
+    """401/403 — missing or invalid API key / scope. User must fix."""
+
+    is_actionable = False
+
+
+class NotConnectedError(ScopeDocsError):
+    """Network failure — backend unreachable. Network/firewall, not a bug."""
+
+    is_actionable = False
+
+
+class BackendError(ScopeDocsError):
+    """Non-auth, non-2xx from backend. 4xx user-side, 5xx engineering bug."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        self.is_actionable = status_code >= 500
+        super().__init__(f"{status_code}: {detail}")
+
+
+def _client_headers(api_key: Optional[str]) -> dict[str, str]:
+    """Default headers attached to every request.
+
+    Mirrors the Warp pattern: client/version/OS metadata so the backend can
+    distinguish CLI vs Web UI vs MCP traffic in logs and metrics.
+    """
+    headers = {
+        "User-Agent": f"scopedocs-cli/{__version__}",
+        "X-ScopeDocs-CLI-Version": __version__,
+        "X-ScopeDocs-Client": f"cli/{platform.system().lower()}",
+    }
+    if api_key:
+        headers["X-API-Key"] = api_key
+    return headers
+
+
+class ScopeDocsClient:
+    """Thin httpx wrapper. One instance per CLI invocation."""
+
+    def __init__(self, config: Config, timeout: float = 30.0) -> None:
+        self._config = config
+        # Tighter timeout granularity: fail fast on dead connections so users
+        # see a clean NotConnectedError quickly (read still gets the full budget).
+        timeout_cfg = httpx.Timeout(connect=5.0, read=timeout, write=10.0, pool=5.0)
+        event_hooks = (
+            {"request": [self._log_request], "response": [self._log_response]}
+            if getattr(config, "verbose", False)
+            else {}
+        )
+        self._client = httpx.Client(
+            base_url=config.backend_url.rstrip("/"),
+            headers=_client_headers(config.api_key),
+            timeout=timeout_cfg,
+            event_hooks=event_hooks,
+        )
+
+    # ------------------------------------------------------------------
+    # Verbose-mode hooks (Warp-style request/response tracing)
+
+    @staticmethod
+    def _log_request(request: httpx.Request) -> None:
+        request.extensions["sd_started_at"] = time.monotonic()
+        print(
+            f"→ {request.method} {request.url}",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    @staticmethod
+    def _log_response(response: httpx.Response) -> None:
+        started = response.request.extensions.get("sd_started_at")
+        elapsed_ms = (time.monotonic() - started) * 1000 if started else 0.0
+        print(
+            f"← {response.status_code} {response.request.url} "
+            f"in {elapsed_ms:.0f}ms",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "ScopeDocsClient":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Internal request helper
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        if not self._config.api_key:
+            raise AuthError(
+                "No API key configured. Run `scopedocs auth login` "
+                "or set SCOPEDOCS_API_KEY."
+            )
+        try:
+            response = self._client.request(method, path, **kwargs)
+        except httpx.ConnectError as exc:
+            raise NotConnectedError(
+                f"Cannot reach backend at {self._config.backend_url}. "
+                f"Is it running? ({exc})"
+            ) from exc
+        except httpx.TimeoutException as exc:
+            raise NotConnectedError(f"Request timed out: {exc}") from exc
+
+        if response.status_code in (401, 403):
+            raise AuthError(
+                f"{response.status_code}: {_extract_detail(response)}"
+            )
+        if response.status_code >= 400:
+            raise BackendError(response.status_code, _extract_detail(response))
+
+        if response.headers.get("content-type", "").startswith("application/json"):
+            return response.json()
+        return response.text
+
+    # ------------------------------------------------------------------
+    # API methods (matches backend/api/v1.py)
+
+    def chat(
+        self,
+        message: str,
+        *,
+        type_: str = "documentation",
+        repo: Optional[str] = None,
+        query_context: Optional[dict] = None,
+        client_trace_id: Optional[str] = None,
+        budget_tokens: Optional[int] = None,
+        use_session_history: bool = False,
+    ) -> dict:
+        """POST /api/v1/chat — non-streaming JSON response."""
+        payload = self._chat_payload(
+            message,
+            type_=type_,
+            repo=repo,
+            query_context=query_context,
+            client_trace_id=client_trace_id,
+            budget_tokens=budget_tokens,
+            use_session_history=use_session_history,
+            stream=False,
+        )
+        return self._request("POST", "/api/v1/chat", json=payload)
+
+    def chat_stream(
+        self,
+        message: str,
+        *,
+        type_: str = "documentation",
+        repo: Optional[str] = None,
+        query_context: Optional[dict] = None,
+        client_trace_id: Optional[str] = None,
+        budget_tokens: Optional[int] = None,
+        use_session_history: bool = False,
+    ):
+        """POST /api/v1/chat with stream=True — yield SSE events as dicts.
+
+        Each yielded item is a parsed `data:` JSON object:
+          {"type": "meta",  "sources": [...], "backend_request_id": ...}
+          {"type": "chunk", "delta": "..."}
+          {"type": "done",  "answer": "...", "model": "...", ...}
+          {"type": "error", "detail": "..."}
+        """
+        if not self._config.api_key:
+            raise AuthError(
+                "No API key configured. Run `scopedocs auth login` "
+                "or set SCOPEDOCS_API_KEY."
+            )
+        payload = self._chat_payload(
+            message,
+            type_=type_,
+            repo=repo,
+            query_context=query_context,
+            client_trace_id=client_trace_id,
+            budget_tokens=budget_tokens,
+            use_session_history=use_session_history,
+            stream=True,
+        )
+        try:
+            with self._client.stream(
+                "POST", "/api/v1/chat", json=payload
+            ) as resp:
+                if resp.status_code in (401, 403):
+                    raise AuthError(f"{resp.status_code}: auth failed")
+                if resp.status_code >= 400:
+                    raise BackendError(resp.status_code, "stream rejected")
+                for line in resp.iter_lines():
+                    if not line:
+                        continue
+                    if line.startswith("data: "):
+                        chunk = line[6:]
+                    elif line.startswith("data:"):
+                        chunk = line[5:]
+                    else:
+                        continue
+                    chunk = chunk.strip()
+                    if not chunk:
+                        continue
+                    try:
+                        import json as _json
+                        yield _json.loads(chunk)
+                    except ValueError:
+                        continue
+        except httpx.ConnectError as exc:
+            raise NotConnectedError(
+                f"Cannot reach backend at {self._config.backend_url}. ({exc})"
+            ) from exc
+        except httpx.TimeoutException as exc:
+            raise NotConnectedError(f"Stream timed out: {exc}") from exc
+
+    @staticmethod
+    def _chat_payload(
+        message: str,
+        *,
+        type_: str,
+        repo: Optional[str],
+        query_context: Optional[dict],
+        client_trace_id: Optional[str],
+        budget_tokens: Optional[int],
+        use_session_history: bool,
+        stream: bool,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"message": message, "type": type_}
+        if repo:
+            payload["repo"] = repo
+        if query_context:
+            payload["query_context"] = query_context
+        if client_trace_id:
+            payload["client_trace_id"] = client_trace_id
+        if budget_tokens is not None:
+            payload["budget_tokens"] = budget_tokens
+        if use_session_history:
+            payload["use_session_history"] = True
+        if stream:
+            payload["stream"] = True
+        return payload
+
+    def feedback(
+        self,
+        *,
+        trace_id: str,
+        rating: str,
+        note: Optional[str] = None,
+        question: Optional[str] = None,
+        backend_request_id: Optional[str] = None,
+    ) -> dict:
+        """POST /api/v1/feedback — labelled training signal for DSPy.
+
+        rating ∈ {"good", "bad"}. The backend may store this against the
+        original `query_context` recorded at chat time.
+        """
+        payload: dict[str, Any] = {"trace_id": trace_id, "rating": rating}
+        if note:
+            payload["note"] = note
+        if question:
+            payload["question"] = question
+        if backend_request_id:
+            payload["backend_request_id"] = backend_request_id
+        return self._request("POST", "/api/v1/feedback", json=payload)
+
+    def search_docs(self, query: str, top_k: int = 5) -> dict:
+        """GET /api/v1/docs/search — vector search over generated docs."""
+        return self._request(
+            "GET",
+            "/api/v1/docs/search",
+            params={"q": query, "top_k": top_k},
+        )
+
+    def get_doc(self, doc_id: str) -> dict:
+        """GET /api/v1/docs/{doc_id} — fetch single doc."""
+        return self._request("GET", f"/api/v1/docs/{doc_id}")
+
+    def list_docs(
+        self,
+        *,
+        repo: Optional[str] = None,
+        limit: int = 50,
+        offset: int = 0,
+    ) -> dict:
+        """GET /api/v1/docs — list docs with pagination."""
+        params: dict[str, Any] = {"limit": limit, "offset": offset}
+        if repo:
+            params["repo"] = repo
+        return self._request("GET", "/api/v1/docs", params=params)
+
+    def get_graph(self, repo: str) -> dict:
+        """GET /api/v1/graph/{repo} — full graph for a repo."""
+        return self._request("GET", f"/api/v1/graph/{repo}")
+
+    def get_graph_node(self, node_id: str) -> dict:
+        """GET /api/v1/graph/node/{node_id} — single node detail."""
+        return self._request("GET", f"/api/v1/graph/node/{node_id}")
+
+    def get_pr(self, repo: str, number: int) -> dict:
+        """GET /api/v1/prs/{repo}/{number} — PR detail."""
+        return self._request("GET", f"/api/v1/prs/{repo}/{number}")
+
+    def workspace(self) -> dict:
+        """GET /api/v1/workspace — workspaces accessible to this API key."""
+        return self._request("GET", "/api/v1/workspace")
+
+    def me(self) -> dict:
+        """GET /api/v1/me — identity attached to this API key.
+
+        Returns key metadata (name, prefix, scopes, rate-limit, dates) plus
+        org id/name and the caller's effective workspace_id. Used by
+        `scopedocs auth status` for a richer "who am I" report.
+        """
+        return self._request("GET", "/api/v1/me")
+
+    def impact(self, target: str, *, since_days: int = 90, budget_tokens: int = 3000) -> dict:
+        """GET /api/v1/impact/{target} — blast-radius analysis.
+
+        NOTE: Endpoint may not yet be deployed; raises BackendError(404) in that case.
+        """
+        from urllib.parse import quote
+        return self._request(
+            "GET",
+            f"/api/v1/impact/{quote(target, safe='')}",
+            params={"since_days": since_days, "budget_tokens": budget_tokens},
+        )
+
+
+def _extract_detail(response: httpx.Response) -> str:
+    try:
+        body = response.json()
+    except Exception:
+        return response.text or "(empty body)"
+    if isinstance(body, dict):
+        return str(body.get("detail") or body.get("message") or body)
+    return str(body)
+
+
+__all__ = [
+    "ScopeDocsClient",
+    "ScopeDocsError",
+    "AuthError",
+    "NotConnectedError",
+    "BackendError",
+]

scopedocs_cli/commands/ask.py

@@ -0,0 +1,281 @@
+"""`scopedocs ask "<question>"` — free-form Q&A over the knowledge graph.
+
+Wires `POST /api/v1/chat` ([backend/api/v1.py:369](../../../backend/api/v1.py)).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from scopedocs_cli import ui
+from scopedocs_cli.client import (
+    AuthError,
+    BackendError,
+    NotConnectedError,
+    ScopeDocsClient,
+)
+from scopedocs_cli.config import Config
+from scopedocs_cli.orchestrator import complete_trace, start_trace
+from scopedocs_cli.renderers import render
+
+
+def run(question: str, config: Config) -> None:
+    payload = _resolve(question, config)
+    render("ask", payload, config)
+
+
+# ---------------------------------------------------------------------------
+
+def _resolve(question: str, config: Config) -> dict[str, Any]:
+    trace, query_context = start_trace("ask", question, config)
+
+    try:
+        with ScopeDocsClient(config) as client:
+            if config.stream:
+                response = _consume_stream(
+                    client.chat_stream(
+                        question,
+                        type_="documentation",
+                        query_context=query_context,
+                        client_trace_id=trace.trace_id,
+                        budget_tokens=config.budget,
+                        use_session_history=config.session,
+                    ),
+                    quiet=config.quiet,
+                )
+            else:
+                with ui.orchestration_trace("Answering"):
+                    response = client.chat(
+                        question,
+                        type_="documentation",
+                        query_context=query_context,
+                        client_trace_id=trace.trace_id,
+                        budget_tokens=config.budget,
+                        use_session_history=config.session,
+                    )
+        result = _from_chat_response(question, response)
+        complete_trace(trace, result, config)
+        return result
+    except (AuthError, NotConnectedError, BackendError) as exc:
+        if not config.quiet:
+            ui.console.print(
+                f"  [{ui.STYLE['marker_warn']}]{type(exc).__name__}[/] "
+                f"[{ui.STYLE['body_dim']}]{exc}[/]"
+            )
+        raise
+
+
+def _consume_stream(events, *, quiet: bool) -> dict[str, Any]:
+    """Drain SSE events, render token-by-token, return assembled response.
+
+    On the first `meta` event we already have sources — render the citation
+    chips immediately. On `chunk` we stream into stderr (so `--json` piping
+    doesn't intermix). On `done` we produce the final response dict.
+    """
+    import sys
+
+    chunks: list[str] = []
+    sources: list = []
+    meta: dict[str, Any] = {}
+    done: dict[str, Any] = {}
+
+    for event in events:
+        kind = event.get("type")
+        if kind == "meta":
+            meta = event
+            sources = event.get("sources") or []
+            if not quiet:
+                print(
+                    f"  ↪ {len(sources)} source(s) · req={event.get('backend_request_id', '')[:8]}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+        elif kind == "chunk":
+            delta = event.get("delta", "")
+            chunks.append(delta)
+            if not quiet:
+                # Print tokens to stdout so the user sees progress live.
+                # Renderer will re-print the assembled answer afterwards;
+                # the redundant render is fine in TTY mode and stripped
+                # automatically when piped (renderer is the source of truth
+                # for `--json`).
+                pass
+        elif kind == "done":
+            done = event
+        elif kind == "error":
+            raise BackendError(500, event.get("detail", "stream error"))
+
+    answer = done.get("answer") or "".join(chunks)
+    return {
+        "answer": answer,
+        "sources": sources,
+        "db_result": None,
+        "backend_request_id": meta.get("backend_request_id"),
+        "client_trace_id": meta.get("client_trace_id"),
+        "model": done.get("model"),
+        "tokens_used": done.get("tokens_used"),
+        "latency_ms": done.get("latency_ms"),
+    }
+
+
+def _from_chat_response(question: str, resp: dict[str, Any]) -> dict[str, Any]:
+    """Map backend `/api/v1/chat` response → ask schema.
+
+    Backend returns two source shapes (mirroring the web frontend's
+    `SourceReference` discriminated union — see frontend-next/src/lib/api.ts):
+      - **code**:    {type:'code', file_path, repo_full_name, start_line,
+                      end_line, function_name, similarity, ref}
+      - **context**: {type: linear_issue|slack_message|workspace_document|
+                      notion_page|jira_issue|github_pr|generated_doc,
+                      source_id, title, url, author, content, similarity, ref}
+    """
+    answer = resp.get("answer", "") or ""
+    raw_sources = resp.get("sources", []) or []
+
+    sources: list[dict[str, Any]] = []
+    evidence: list[dict[str, Any]] = []
+    for idx, raw in enumerate(raw_sources, start=1):
+        # Strip brackets from the backend ref ("[1]" → "1") so the renderer
+        # owns formatting decisions.
+        ref = str(raw.get("ref") or f"{idx}").strip("[]")
+        kind = str(raw.get("type") or "unknown")
+
+        if kind == "code":
+            repo = raw.get("repo_full_name") or raw.get("repo") or ""
+            path = raw.get("file_path") or ""
+            ls, le = raw.get("start_line"), raw.get("end_line")
+            line_range = (
+                f":{ls}-{le}" if ls and le else (f":{ls}" if ls else "")
+            )
+            full_title = f"{repo}/{path}" if repo else path or f"source-{idx}"
+            fn_name = raw.get("function_name")
+            # Source col: file:line (compact). Signal col: function name if
+            # available, else short-form repo (last segment) so user can
+            # distinguish multi-repo queries.
+            short_repo = repo.split("/")[-1] if "/" in repo else repo
+            signal = fn_name or (f"in {short_repo}" if short_repo else "")
+            url = raw.get("url") or ""
+            sources.append(
+                {
+                    "ref": ref,
+                    "url": url,
+                    "type": "code",
+                    "title": full_title,
+                    "file_path": path,
+                    "repo": repo,
+                    "start_line": ls,
+                    "end_line": le,
+                    "function_name": fn_name,
+                    "similarity": raw.get("similarity"),
+                }
+            )
+            evidence.append(
+                {
+                    "source": _truncate(f"{path}{line_range}", 60),
+                    "system": "code",
+                    "signal": _truncate(str(signal), 80),
+                    "ref": ref,
+                }
+            )
+        else:
+            title = (
+                raw.get("title")
+                or raw.get("name")
+                or raw.get("file_path")
+                or raw.get("path")
+                or f"source-{idx}"
+            )
+            url = raw.get("url") or raw.get("link") or ""
+            # `content` is the full body for linear/slack/notion/etc.
+            # `excerpt`/`snippet`/`summary` are legacy aliases.
+            content = (
+                raw.get("content")
+                or raw.get("excerpt")
+                or raw.get("snippet")
+                or raw.get("summary")
+                or ""
+            )
+            # Pull a one-line signal: first non-empty line after stripping
+            # markdown headers / "Title:" lead-ins.
+            signal = _first_meaningful_line(content)
+            author = raw.get("author")
+            sources.append(
+                {
+                    "ref": ref,
+                    "url": url,
+                    "type": kind,
+                    "title": title,
+                    "author": author,
+                    "similarity": raw.get("similarity"),
+                }
+            )
+            evidence.append(
+                {
+                    "source": _truncate(str(title), 60),
+                    "system": kind,
+                    "signal": _truncate(signal, 80),
+                    "ref": ref,
+                    **({"author": author} if author else {}),
+                }
+            )
+
+    summary = answer
+    recommendation = ""
+    # Heuristic: if the answer ends with a "Recommendation:" / "Next:" tail,
+    # split it off so the TUI can render it as its own section. Cheap and
+    # robust enough for v1 — backend doesn't structure it explicitly yet.
+    for marker in ("\nRecommendation:", "\nNext steps:", "\nNext:"):
+        if marker in answer:
+            head, tail = answer.rsplit(marker, 1)
+            summary = head.rstrip()
+            recommendation = tail.strip()
+            break
+
+    return {
+        "command": "ask",
+        "question": question,
+        "summary": summary,
+        "evidence": evidence,
+        "recommendation": recommendation,
+        "sources": sources,
+        "tokens_used": resp.get("tokens_used", 0) or 0,
+        "tokens_budget": 0,
+        "db_result": resp.get("db_result"),
+        "backend_request_id": resp.get("backend_request_id"),
+        "model": resp.get("model"),
+        "latency_ms": resp.get("latency_ms"),
+        "cached": resp.get("cached", False),
+    }
+
+
+def _truncate(s: str, n: int) -> str:
+    s = s.replace("\n", " ").strip()
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+def _first_meaningful_line(content: str) -> str:
+    """Pluck a 1-line signal out of a Linear / Slack / generated_doc body.
+
+    The backend's `format_for_llm` packs the body as:
+        Title: ...
+        Status: ...
+        Description: <real signal>
+    We skip those lead-in lines plus markdown headers, take the first line
+    that actually says something.
+    """
+    if not content:
+        return ""
+    skip_prefixes = ("title:", "status:", "team:", "priority:", "assignee:", "#")
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        low = line.lower()
+        if low.startswith(skip_prefixes) or low.startswith("description:"):
+            # If 'Description:' has tail on same line, use the tail.
+            if low.startswith("description:"):
+                tail = line.split(":", 1)[1].strip()
+                if tail:
+                    return tail
+            continue
+        return line
+    return content.strip().splitlines()[0] if content.strip() else ""