codebase-cortex 0.1.0__py3-none-any.whl

codebase_cortex/agents/sprint_reporter.py

@@ -0,0 +1,152 @@
+"""SprintReporter agent — generates weekly sprint summaries in Notion."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from codebase_cortex.agents.base import BaseAgent
+from codebase_cortex.notion.bootstrap import extract_page_id
+from codebase_cortex.state import CortexState
+
+SYSTEM_PROMPT = """You are a technical project manager writing a sprint summary.
+Given code analysis data and documentation updates, write a concise weekly sprint report.
+
+Structure the report with these sections:
+1. **Sprint Overview** - One paragraph summary
+2. **Key Changes** - Bullet list of significant changes
+3. **Documentation Updates** - What docs were created/updated
+4. **Open Tasks** - Tasks created for documentation gaps
+5. **Metrics** - Files changed, docs updated, tasks created
+
+Keep it professional and concise. Use markdown formatting."""
+
+
+class SprintReporterAgent(BaseAgent):
+    """Generates sprint summary reports in Notion."""
+
+    async def run(self, state: CortexState) -> dict:
+        analysis = state.get("analysis", "")
+        if not analysis:
+            return {"sprint_summary": ""}
+
+        changed_files = state.get("changed_files", [])
+        doc_updates = state.get("doc_updates", [])
+        tasks_created = state.get("tasks_created", [])
+        dry_run = state.get("dry_run", False)
+
+        now = datetime.now()
+        week_start = now - timedelta(days=now.weekday())
+
+        prompt = f"""Generate a sprint summary for the week of {week_start.strftime('%B %d, %Y')}.
+
+## Code Analysis
+{analysis}
+
+## Changes
+- {len(changed_files)} files changed
+- {sum(f.get('additions', 0) for f in changed_files)} lines added
+- {sum(f.get('deletions', 0) for f in changed_files)} lines deleted
+
+## Documentation Updates
+{self._format_doc_updates(doc_updates)}
+
+## Tasks Created
+{self._format_tasks(tasks_created)}
+
+Write a complete sprint report in markdown."""
+
+        try:
+            messages = [
+                SystemMessage(content=SYSTEM_PROMPT),
+                HumanMessage(content=prompt),
+            ]
+            sprint_summary = await self._invoke_llm(messages)
+        except Exception as e:
+            return {
+                "sprint_summary": "",
+                "errors": self._append_error(state, f"Sprint report failed: {e}"),
+            }
+
+        # Write to Notion Sprint Log page
+        if not dry_run and sprint_summary:
+            await self._write_to_notion(sprint_summary, week_start, state)
+
+        return {"sprint_summary": sprint_summary}
+
+    async def _write_to_notion(
+        self, summary: str, week_start: datetime, state: CortexState
+    ) -> None:
+        """Append sprint summary to the Sprint Log page in Notion."""
+        from codebase_cortex.mcp_client import notion_mcp_session, rate_limiter
+        from codebase_cortex.config import Settings
+        from codebase_cortex.notion.page_cache import PageCache
+        from codebase_cortex.utils.logging import get_logger
+
+        logger = get_logger()
+        settings = Settings.from_env()
+        cache = PageCache(cache_path=settings.page_cache_path)
+
+        sprint_page = cache.find_by_title("Sprint Log")
+        parent_page = cache.find_by_title("Codebase Cortex")
+        parent_id = (sprint_page or parent_page)
+        parent_id = parent_id.page_id if parent_id else None
+
+        try:
+            async with notion_mcp_session(settings) as session:
+                await rate_limiter.acquire()
+
+                week_label = week_start.strftime("%B %d, %Y")
+                content = f"# Sprint Report — Week of {week_label}\n\n{summary}"
+
+                if sprint_page:
+                    # Append to existing Sprint Log using insert_content_after
+                    await session.call_tool(
+                        "notion-update-page",
+                        arguments={
+                            "page_id": sprint_page.page_id,
+                            "command": "insert_content_after",
+                            "selection_with_ellipsis": "---\n*Auto-gen...by Codebase Cortex*",
+                            "new_str": f"\n\n---\n\n{content}",
+                        },
+                    )
+                    logger.info(f"Appended to Sprint Log for week of {week_label}")
+                else:
+                    # Create new sprint report page
+                    create_args: dict = {
+                        "pages": [
+                            {
+                                "properties": {"title": f"📋 Sprint Report — {week_label}"},
+                                "content": content,
+                            }
+                        ],
+                    }
+                    if parent_id:
+                        create_args["parent"] = {"page_id": parent_id}
+
+                    result = await session.call_tool(
+                        "notion-create-pages",
+                        arguments=create_args,
+                    )
+                    page_id = extract_page_id(result)
+                    if page_id:
+                        cache.upsert(page_id, "Sprint Log")
+                    logger.info(f"Created Sprint Report for week of {week_label}")
+
+        except Exception as e:
+            logger.error(f"Failed to write sprint report: {e}")
+
+    @staticmethod
+    def _format_doc_updates(updates: list[dict]) -> str:
+        if not updates:
+            return "No documentation updates this sprint."
+        return "\n".join(f"- {u.get('title', 'Untitled')} ({u.get('action', 'update')})" for u in updates)
+
+    @staticmethod
+    def _format_tasks(tasks: list[dict]) -> str:
+        if not tasks:
+            return "No new tasks created."
+        return "\n".join(
+            f"- [{t.get('priority', 'medium')}] {t.get('title', 'Untitled')}" for t in tasks
+        )

codebase_cortex/agents/task_creator.py

@@ -0,0 +1,138 @@
+"""TaskCreator agent — creates Notion tasks for undocumented areas."""
+
+from __future__ import annotations
+
+from langchain_core.messages import HumanMessage, SystemMessage
+
+from codebase_cortex.agents.base import BaseAgent
+from codebase_cortex.notion.bootstrap import extract_page_id
+from codebase_cortex.state import CortexState, TaskItem
+from codebase_cortex.utils.json_parsing import parse_json_array
+
+SYSTEM_PROMPT = """You are a documentation quality analyst. Given a code analysis,
+identify areas that need documentation but don't have it yet.
+
+Output a JSON array of tasks, each with:
+- "title": Brief task title (imperative form, e.g., "Document the auth flow")
+- "description": What needs to be documented and why
+- "priority": "high" (breaking changes, new APIs), "medium" (new features), or "low" (refactors, minor changes)
+
+Only create tasks for genuinely undocumented or under-documented areas.
+Don't create tasks for trivial changes (formatting, typos, minor refactors).
+Respond with ONLY the JSON array. If nothing needs documenting, return []."""
+
+
+class TaskCreatorAgent(BaseAgent):
+    """Creates tasks in Notion for areas needing documentation."""
+
+    async def run(self, state: CortexState) -> dict:
+        analysis = state.get("analysis", "")
+        if not analysis:
+            return {"tasks_created": []}
+
+        doc_updates = state.get("doc_updates", [])
+        dry_run = state.get("dry_run", False)
+
+        # Build context about what was already documented
+        already_documented = ""
+        if doc_updates:
+            already_documented = "\n\n## Already Documented\nThe following pages were just updated:\n"
+            for d in doc_updates:
+                already_documented += f"- {d['title']} ({d['action']})\n"
+
+        prompt = f"""Review this code analysis and identify documentation gaps.
+
+## Code Analysis
+{analysis}
+{already_documented}
+
+Create tasks only for areas NOT already covered by the doc updates above.
+Respond with a JSON array of tasks (title, description, priority). Return [] if all areas are covered."""
+
+        try:
+            messages = [
+                SystemMessage(content=SYSTEM_PROMPT),
+                HumanMessage(content=prompt),
+            ]
+            raw = await self._invoke_llm(messages)
+
+            tasks_data = parse_json_array(raw)
+
+        except Exception as e:
+            return {
+                "tasks_created": [],
+                "errors": self._append_error(state, f"Task creation failed: {e}"),
+            }
+
+        tasks: list[TaskItem] = [
+            TaskItem(
+                title=t.get("title", "Untitled task"),
+                description=t.get("description", ""),
+                priority=t.get("priority", "medium"),
+            )
+            for t in tasks_data
+        ]
+
+        # Create tasks in Notion (unless dry_run)
+        if not dry_run and tasks:
+            await self._create_in_notion(tasks, state)
+
+        return {"tasks_created": tasks}
+
+    async def _create_in_notion(self, tasks: list[TaskItem], state: CortexState) -> None:
+        """Create task items as child pages under the Task Board in Notion."""
+        from codebase_cortex.mcp_client import notion_mcp_session, rate_limiter
+        from codebase_cortex.config import Settings
+        from codebase_cortex.notion.page_cache import PageCache
+        from codebase_cortex.utils.logging import get_logger
+
+        logger = get_logger()
+        settings = Settings.from_env()
+        cache = PageCache(cache_path=settings.page_cache_path)
+
+        task_board = cache.find_by_title("Task Board")
+        parent_page = cache.find_by_title("Codebase Cortex")
+        parent_id = (task_board or parent_page)
+        parent_id = parent_id.page_id if parent_id else None
+
+        try:
+            async with notion_mcp_session(settings) as session:
+                for task in tasks:
+                    await rate_limiter.acquire()
+
+                    priority_icon = {"high": "🔴", "medium": "🟡", "low": "🟢"}.get(
+                        task["priority"], "⚪"
+                    )
+
+                    title = f"{priority_icon} {task['title']}"
+                    content = (
+                        f"## {task['title']}\n\n"
+                        f"**Priority:** {task['priority']}\n\n"
+                        f"{task['description']}\n\n"
+                        f"---\n*Auto-created by Codebase Cortex*"
+                    )
+
+                    create_args: dict = {
+                        "pages": [
+                            {
+                                "properties": {"title": title},
+                                "content": content,
+                            }
+                        ],
+                    }
+                    if parent_id:
+                        create_args["parent"] = {"page_id": parent_id}
+
+                    result = await session.call_tool(
+                        "notion-create-pages",
+                        arguments=create_args,
+                    )
+
+                    page_id = extract_page_id(result)
+                    if page_id:
+                        cache.upsert(page_id, task["title"])
+
+                    logger.info(f"Created task: {priority_icon} {task['title']}")
+
+        except Exception as e:
+            logger.error(f"Failed to create tasks in Notion: {e}")

codebase_cortex/auth/callback_server.py

@@ -0,0 +1,80 @@
+"""Local HTTP callback server for OAuth authorization code receipt."""
+
+from __future__ import annotations
+
+import asyncio
+from http.server import HTTPServer, BaseHTTPRequestHandler
+from urllib.parse import urlparse, parse_qs
+from threading import Thread
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    """Handles the OAuth callback and extracts the authorization code."""
+
+    code: str | None = None
+    state: str | None = None
+    error: str | None = None
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        params = parse_qs(parsed.query)
+
+        if "error" in params:
+            _CallbackHandler.error = params["error"][0]
+            self._respond("Authorization failed. You can close this tab.")
+        elif "code" in params:
+            _CallbackHandler.code = params["code"][0]
+            _CallbackHandler.state = params.get("state", [None])[0]
+            self._respond("Authorization successful! You can close this tab.")
+        else:
+            self._respond("Unexpected callback. You can close this tab.", status=400)
+
+    def _respond(self, message: str, status: int = 200) -> None:
+        self.send_response(status)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        html = f"<html><body><h2>{message}</h2></body></html>"
+        self.wfile.write(html.encode())
+
+    def log_message(self, format: str, *args: object) -> None:
+        pass  # Suppress request logging
+
+
+async def wait_for_callback(
+    port: int = 9876,
+    timeout: float = 120.0,
+) -> tuple[str, str | None]:
+    """Start a local HTTP server and wait for the OAuth callback.
+
+    Args:
+        port: Port to listen on.
+        timeout: Maximum seconds to wait for the callback.
+
+    Returns:
+        Tuple of (authorization_code, state).
+
+    Raises:
+        TimeoutError: If no callback received within timeout.
+        RuntimeError: If the authorization was denied or failed.
+    """
+    _CallbackHandler.code = None
+    _CallbackHandler.state = None
+    _CallbackHandler.error = None
+
+    server = HTTPServer(("localhost", port), _CallbackHandler)
+    thread = Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    try:
+        elapsed = 0.0
+        interval = 0.5
+        while elapsed < timeout:
+            if _CallbackHandler.code is not None:
+                return _CallbackHandler.code, _CallbackHandler.state
+            if _CallbackHandler.error is not None:
+                raise RuntimeError(f"OAuth error: {_CallbackHandler.error}")
+            await asyncio.sleep(interval)
+            elapsed += interval
+        raise TimeoutError("OAuth callback timed out")
+    finally:
+        server.shutdown()

codebase_cortex/auth/oauth.py

@@ -0,0 +1,173 @@
+"""OAuth 2.0 + PKCE flow for Notion MCP authorization."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+import webbrowser
+
+import httpx
+
+NOTION_MCP_METADATA_URL = "https://mcp.notion.com/.well-known/oauth-authorization-server"
+
+# Fallback URLs (prefer metadata-discovered endpoints)
+NOTION_AUTH_URL = "https://mcp.notion.com/authorize"
+NOTION_TOKEN_URL = "https://mcp.notion.com/token"
+NOTION_CLIENT_REGISTRATION_URL = "https://mcp.notion.com/register"
+
+
+def generate_pkce_pair() -> tuple[str, str]:
+    """Generate a PKCE code verifier and challenge (S256).
+
+    Returns:
+        Tuple of (code_verifier, code_challenge).
+    """
+    verifier = secrets.token_urlsafe(64)
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+async def fetch_oauth_metadata() -> dict:
+    """Fetch the OAuth authorization server metadata from Notion MCP."""
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(NOTION_MCP_METADATA_URL)
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def register_client(
+    redirect_uri: str,
+    registration_endpoint: str | None = None,
+) -> dict:
+    """Dynamically register an OAuth client with Notion MCP.
+
+    Args:
+        redirect_uri: The callback URI (e.g., http://localhost:9876/callback).
+        registration_endpoint: Override registration endpoint URL.
+
+    Returns:
+        Client registration response with client_id and client_secret.
+    """
+    endpoint = registration_endpoint or NOTION_CLIENT_REGISTRATION_URL
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            endpoint,
+            json={
+                "client_name": "Codebase Cortex",
+                "redirect_uris": [redirect_uri],
+                "grant_types": ["authorization_code", "refresh_token"],
+                "response_types": ["code"],
+                "token_endpoint_auth_method": "client_secret_post",
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+def build_authorization_url(
+    client_id: str,
+    redirect_uri: str,
+    code_challenge: str,
+    state: str,
+    authorization_endpoint: str | None = None,
+) -> str:
+    """Build the Notion OAuth authorization URL.
+
+    Args:
+        client_id: The registered client ID.
+        redirect_uri: Callback URI.
+        code_challenge: PKCE S256 challenge.
+        state: Random state for CSRF protection.
+        authorization_endpoint: Override auth endpoint URL.
+
+    Returns:
+        The full authorization URL to open in a browser.
+    """
+    endpoint = authorization_endpoint or NOTION_AUTH_URL
+    params = httpx.QueryParams(
+        client_id=client_id,
+        redirect_uri=redirect_uri,
+        response_type="code",
+        code_challenge=code_challenge,
+        code_challenge_method="S256",
+        state=state,
+        owner="user",
+    )
+    return f"{endpoint}?{params}"
+
+
+async def exchange_code(
+    code: str,
+    client_id: str,
+    client_secret: str,
+    redirect_uri: str,
+    code_verifier: str,
+    token_endpoint: str | None = None,
+) -> dict:
+    """Exchange authorization code for access and refresh tokens.
+
+    Args:
+        code: The authorization code from the callback.
+        client_id: Registered client ID.
+        client_secret: Registered client secret.
+        redirect_uri: The same redirect URI used in authorization.
+        code_verifier: The PKCE code verifier.
+        token_endpoint: Override token endpoint URL.
+
+    Returns:
+        Token response with access_token, refresh_token, expires_in.
+    """
+    endpoint = token_endpoint or NOTION_TOKEN_URL
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            endpoint,
+            data={
+                "grant_type": "authorization_code",
+                "code": code,
+                "redirect_uri": redirect_uri,
+                "client_id": client_id,
+                "client_secret": client_secret,
+                "code_verifier": code_verifier,
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def refresh_access_token(
+    refresh_token: str,
+    client_id: str,
+    client_secret: str,
+    token_endpoint: str | None = None,
+) -> dict:
+    """Refresh an expired access token.
+
+    Args:
+        refresh_token: The refresh token.
+        client_id: Registered client ID.
+        client_secret: Registered client secret.
+        token_endpoint: Override token endpoint URL.
+
+    Returns:
+        New token response with access_token and possibly new refresh_token.
+    """
+    endpoint = token_endpoint or NOTION_TOKEN_URL
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            endpoint,
+            data={
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+                "client_id": client_id,
+                "client_secret": client_secret,
+            },
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+def open_browser(url: str) -> None:
+    """Open the authorization URL in the user's browser."""
+    webbrowser.open(url)

codebase_cortex/auth/token_store.py

@@ -0,0 +1,90 @@
+"""Persist and manage OAuth tokens for Notion MCP."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from dataclasses import dataclass
+
+from codebase_cortex.auth.oauth import refresh_access_token
+
+
+@dataclass
+class TokenData:
+    """Stored OAuth token data."""
+
+    access_token: str
+    refresh_token: str
+    expires_at: float
+    client_id: str
+    client_secret: str
+    token_endpoint: str | None = None
+
+    @property
+    def is_expired(self) -> bool:
+        return time.time() >= self.expires_at - 60  # 60s buffer
+
+    def to_dict(self) -> dict:
+        return {
+            "access_token": self.access_token,
+            "refresh_token": self.refresh_token,
+            "expires_at": self.expires_at,
+            "client_id": self.client_id,
+            "client_secret": self.client_secret,
+            "token_endpoint": self.token_endpoint,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TokenData:
+        return cls(**data)
+
+
+def save_tokens(token_data: TokenData, path: Path) -> None:
+    """Save token data to a JSON file."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(token_data.to_dict(), indent=2))
+
+
+def load_tokens(path: Path) -> TokenData | None:
+    """Load token data from a JSON file, or None if not found."""
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text())
+    return TokenData.from_dict(data)
+
+
+async def get_valid_token(path: Path) -> str:
+    """Get a valid access token, refreshing if expired.
+
+    Args:
+        path: Path to the token JSON file.
+
+    Returns:
+        A valid access token string.
+
+    Raises:
+        FileNotFoundError: If no tokens are stored.
+        RuntimeError: If refresh fails.
+    """
+    token_data = load_tokens(path)
+    if token_data is None:
+        raise FileNotFoundError(f"No tokens found at {path}. Run 'cortex init' first.")
+
+    if not token_data.is_expired:
+        return token_data.access_token
+
+    result = await refresh_access_token(
+        refresh_token=token_data.refresh_token,
+        client_id=token_data.client_id,
+        client_secret=token_data.client_secret,
+        token_endpoint=token_data.token_endpoint,
+    )
+
+    token_data.access_token = result["access_token"]
+    if "refresh_token" in result:
+        token_data.refresh_token = result["refresh_token"]
+    token_data.expires_at = time.time() + result.get("expires_in", 3600)
+    save_tokens(token_data, path)
+
+    return token_data.access_token