codetherapy 0.1.0__py3-none-any.whl

codetherapy/server.py

@@ -0,0 +1,163 @@
+"""Code Therapy: the MCP surface (six PM tools) and the token-guarded Streamable HTTP app."""
+from __future__ import annotations
+
+import threading
+from typing import Callable
+
+import anyio
+import uvicorn
+from mcp.server.mcpserver import MCPServer
+from mcp.server.transport_security import TransportSecuritySettings
+from mcp.types import ToolAnnotations
+from starlette.applications import Starlette
+
+from codetherapy import context, deep, notes, search
+from codetherapy.config import Config
+from codetherapy.projects import Project, ProjectIndex
+from codetherapy.sessions import summarize
+
+LIST_LIMIT = 15
+READ_ONLY = ToolAnnotations(read_only_hint=True)
+# Each deep lookup is a full `claude -p` run; cap how many the connector runs at once.
+DEEP_SLOTS = threading.BoundedSemaphore(2)
+DEEP_BUSY_MESSAGE = "Another deep lookup is already running; try again in a minute."
+SERVER_NAME = "Code Therapy"
+
+INSTRUCTIONS = """\
+You are the project manager for the user's software projects, which they build with Claude Code. \
+The user is usually talking to you by voice, so your answers are spoken aloud: lead with the status, \
+keep it to a few sentences, and avoid code blocks, tables and long lists unless asked.
+- If you aren't sure which project they mean, call list_projects with what they said.
+- Call get_project_brief before answering questions about a project.
+- Use get_recent_activity for "what happened lately" questions.
+- For "where is X / find the file that..." questions, use search_project: it answers in about a second.
+- Use ask_project only for questions the brief and search can't answer, such as how something works in the code. It is slow, so tell the user before you call it.
+- When the user makes a decision or names a to-do, offer to save it with record_note.
+Anything about the user's projects goes through these Code Therapy tools, never your own sandbox, shell, git or web search: these tools read the user's real project folders on their computer. The tools behave the same in voice and text sessions.
+Tools by speed: fast (about 1 second): list_projects, get_project_brief, get_recent_activity, search_project, record_note. Slow (20-90 seconds): ask_project."""
+
+
+def _resolve(index: ProjectIndex, query: str) -> tuple[Project | None, str]:
+    result = index.resolve(query)
+    if result.project:
+        return result.project, ""
+    if result.candidates:
+        names = ", ".join(p.name for p in result.candidates)
+        return None, f"Did you mean: {names}? Ask again with the exact name."
+    return None, f'No project matches "{query}". Call list_projects to see them all.'
+
+
+def limited(slots: threading.BoundedSemaphore, work: Callable[[], str]) -> str:
+    """Run work if a slot is free right now; otherwise say so instead of queueing."""
+    if not slots.acquire(blocking=False):
+        return DEEP_BUSY_MESSAGE
+    try:
+        return work()
+    finally:
+        slots.release()
+
+
+def _project_line(project: Project) -> str:
+    line = f"- {project.name} (last active {project.last_active:%Y-%m-%d})"
+    if project.session_files:
+        try:
+            if title := summarize(project.session_files[0]).title:
+                line += f': latest session "{title}"'
+        except OSError:
+            pass
+    if not project.exists:
+        line += " [folder missing]"
+    return line
+
+
+def build_server(index: ProjectIndex, claude_command: list[str] | None = None) -> MCPServer:
+    server = MCPServer(SERVER_NAME, instructions=INSTRUCTIONS)
+
+    @server.tool(annotations=READ_ONLY)
+    def list_projects(query: str = "") -> str:
+        """List the user's Claude Code projects, most recently active first, each with its latest session title.
+        Pass query (whatever the user called the project) to narrow the list."""
+        projects = index.all()
+        if not projects:
+            return "No Claude Code projects found."
+        if query.strip():
+            result = index.resolve(query)
+            matches = [result.project] if result.project else list(result.candidates)
+            if matches:
+                return "\n".join(_project_line(p) for p in matches)
+            prefix = f'No project matches "{query}". The most recent are:\n'
+        else:
+            prefix = f"{len(projects)} projects; the {min(len(projects), LIST_LIMIT)} most recent:\n"
+        return prefix + "\n".join(_project_line(p) for p in projects[:LIST_LIMIT])
+
+    @server.tool(annotations=READ_ONLY)
+    def get_project_brief(project: str) -> str:
+        """Current state of one project: overview (CLAUDE.md/README), git branch and recent commits,
+        recent Claude Code sessions, and open PM notes. Call this before discussing a project."""
+        found, message = _resolve(index, project)
+        return context.brief(found) if found else message
+
+    @server.tool(annotations=READ_ONLY)
+    def get_recent_activity(project: str, days: int = 7) -> str:
+        """What was worked on in a project over the last N days: Claude Code sessions and git commits."""
+        found, message = _resolve(index, project)
+        return context.activity(found, days) if found else message
+
+    @server.tool(annotations=READ_ONLY)
+    async def ask_project(project: str, question: str) -> str:
+        """Slow: 20-90 seconds. BEFORE calling, tell the user you're starting a lookup that can take up to a
+        minute or so; don't go quiet. For "where is X / find the file that..." questions, try search_project
+        first; it answers in about a second. Otherwise this has Claude Code read the project (read-only) to
+        answer a detailed question about its code that get_project_brief can't answer.
+        If the result says another lookup is running or the lookup failed, retry once. If it says it needs a
+        longer look (timeout), don't retry; suggest asking in Claude Code instead."""
+        found, message = _resolve(index, project)
+        if found is None:
+            return message
+        return await anyio.to_thread.run_sync(
+            lambda: limited(DEEP_SLOTS, lambda: deep.ask(found.path, question, command=claude_command)))
+
+    @server.tool(annotations=READ_ONLY)
+    def search_project(project: str, query: str) -> str:
+        """Fast (about 1 second) literal search of a project's file names and file contents. Use it for
+        "where is X / find the file that mentions Y" questions. Case-insensitive plain text, not regex;
+        returns file paths and matching lines. Secret files such as .env are never searched."""
+        found, message = _resolve(index, project)
+        return search.search(found.path, query) if found else message
+
+    @server.tool(annotations=ToolAnnotations(read_only_hint=False, destructive_hint=False))
+    def record_note(project: str, kind: str, text: str) -> str:
+        """Save a decision, to-do or note to PM_NOTES.md in the project for the user's next coding session.
+        kind is one of: decision, todo, note."""
+        found, message = _resolve(index, project)
+        if found is None:
+            return message
+        try:
+            line = notes.record(found.path, kind, text)
+        except (ValueError, OSError) as error:
+            return f"Couldn't save that: {error}"
+        return f"Saved to {found.name}/{notes.NOTES_FILE}: {line}"
+
+    return server
+
+
+def build_app(server: MCPServer, config: Config) -> Starlette:
+    hosts = ["127.0.0.1:*", "localhost:*", "[::1]:*"]
+    origins = ["http://127.0.0.1:*", "http://localhost:*", "http://[::1]:*", "https://claude.ai"]
+    if config.public_host:
+        hosts.append(config.public_host)
+        origins.append(f"https://{config.public_host}")
+    return server.streamable_http_app(
+        streamable_http_path=f"/mcp/{config.token}",
+        stateless_http=True,
+        transport_security=TransportSecuritySettings(
+            enable_dns_rebinding_protection=True, allowed_hosts=hosts, allowed_origins=origins),
+    )
+
+
+def run(config: Config) -> None:
+    app = build_app(build_server(ProjectIndex(config.projects_dir)), config)
+    print(f"Code Therapy listening on http://127.0.0.1:{config.port}/mcp/<token> "
+          f"(public host: {config.public_host or 'none'})", flush=True)
+    # access_log off: the secret token is part of every request path.
+    uvicorn.run(app, host="127.0.0.1", port=config.port, access_log=False, log_level="info")

codetherapy/sessions.py

@@ -0,0 +1,101 @@
+"""Read Claude Code session logs (~/.claude/projects/<folder>/<session-id>.jsonl)."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import Iterator
+
+from codetherapy.textutil import clip, one_line
+
+PROMPT_LIMIT = 200
+
+
+@dataclass(frozen=True)
+class SessionSummary:
+    session_id: str
+    title: str
+    cwd: str
+    started: datetime | None
+    ended: datetime | None
+    git_branch: str
+    prompts: tuple[str, ...]
+
+
+def iter_records(path: Path) -> Iterator[dict]:
+    with path.open(encoding="utf-8", errors="replace") as f:
+        for line in f:
+            try:
+                record = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            if isinstance(record, dict):
+                yield record
+
+
+def _parse_timestamp(value: object) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _prompt_text(record: dict) -> str | None:
+    """A prompt the user actually typed: not tool results, not subagents, not <command> wrappers."""
+    if record.get("type") != "user" or record.get("isSidechain"):
+        return None
+    message = record.get("message")
+    content = message.get("content") if isinstance(message, dict) else None
+    if not isinstance(content, str):
+        return None
+    text = content.strip()
+    if not text or text.startswith("<"):
+        return None
+    return clip(one_line(text), PROMPT_LIMIT)
+
+
+def read_cwd(path: Path, max_records: int = 500) -> str:
+    """The session's working directory, or "" if the log has none or can't be read."""
+    try:
+        for i, record in enumerate(iter_records(path)):
+            if i >= max_records:
+                break
+            cwd = record.get("cwd")
+            if isinstance(cwd, str) and cwd:
+                return cwd
+    except OSError:  # locked, deleted mid-scan, or not a file: one bad log must not break discovery
+        pass
+    return ""
+
+
+def summarize(path: Path, max_prompts: int = 3) -> SessionSummary:
+    stat = path.stat()
+    return _summarize_cached(str(path), stat.st_mtime_ns, stat.st_size, max_prompts)
+
+
+@lru_cache(maxsize=1024)
+def _summarize_cached(path_str: str, _mtime_ns: int, _size: int, max_prompts: int) -> SessionSummary:
+    title = cwd = git_branch = ""
+    started: datetime | None = None
+    ended: datetime | None = None
+    prompts: list[str] = []
+    for record in iter_records(Path(path_str)):
+        if record.get("type") == "ai-title" and isinstance(record.get("aiTitle"), str):
+            title = record["aiTitle"]  # later titles supersede earlier ones
+        timestamp = _parse_timestamp(record.get("timestamp"))
+        if timestamp is not None:
+            started = started or timestamp
+            ended = timestamp
+        if not cwd and isinstance(record.get("cwd"), str):
+            cwd = record["cwd"]
+        if isinstance(record.get("gitBranch"), str) and record["gitBranch"]:
+            git_branch = record["gitBranch"]
+        if len(prompts) < max_prompts:
+            text = _prompt_text(record)
+            if text:
+                prompts.append(text)
+    return SessionSummary(Path(path_str).stem, title, cwd, started, ended, git_branch, tuple(prompts))

codetherapy/textutil.py

@@ -0,0 +1,11 @@
+"""Small string helpers shared by the context, sessions and deep modules."""
+
+
+def one_line(text: str) -> str:
+    return " ".join(text.split())
+
+
+def clip(text: str, limit: int, marker: str = "…") -> str:
+    if len(text) <= limit:
+        return text
+    return text[: max(0, limit - len(marker))].rstrip() + marker

codetherapy/tunnel.py

@@ -0,0 +1,134 @@
+"""Find and drive ngrok, and turn its log lines into plain-language problems."""
+from __future__ import annotations
+
+import collections
+import os
+import queue
+import re
+import shutil
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+LEFTOVER = (" (if an old `codetherapy start` crashed, end the leftover ngrok in Task Manager / Activity Monitor, "
+            "or `pkill ngrok`)")
+HINTS = {
+    "ERR_NGROK_4018": "ngrok has no authtoken. Run `ngrok config add-authtoken <token>` "
+                      "(token: https://dashboard.ngrok.com/get-started/your-authtoken).",
+    "ERR_NGROK_105": "ngrok rejected the authtoken. Copy it again from "
+                     "https://dashboard.ngrok.com/get-started/your-authtoken and run `ngrok config add-authtoken <token>`.",
+    "ERR_NGROK_108": "ngrok is already running somewhere else on your account (the free plan allows one). "
+                     f"Stop the other ngrok and try again{LEFTOVER}.",
+    "ERR_NGROK_334": f"Your ngrok domain is already online in another ngrok session. Stop it and try again{LEFTOVER}.",
+}
+STARTED = re.compile(r'msg="started tunnel".*?\burl=(\S+)')
+TAIL_LINES = 50
+
+
+class NgrokOutput:
+    """What wait_online reads from ngrok: lines go to `pending` until wait_online returns, then only
+    into the bounded `tail`. ngrok keeps being drained, so it never blocks on a full pipe."""
+
+    def __init__(self) -> None:
+        self.pending: queue.Queue[str | None] = queue.Queue()
+        self.tail: collections.deque[str] = collections.deque(maxlen=TAIL_LINES)
+        self.done = threading.Event()  # wait_online has returned
+        self.eof = threading.Event()  # ngrok's output has ended
+
+
+def recent_output(proc: subprocess.Popen, wait: float = 0.0) -> list[str]:
+    """The last ngrok log lines read by wait_online (at most TAIL_LINES). `wait` gives the reader
+    that long to reach the end of the output, for when ngrok has just exited."""
+    output = getattr(proc, "ngrok_output", None)
+    if not output:
+        return []
+    output.eof.wait(wait)
+    return list(output.tail)
+
+
+def find_ngrok() -> str | None:
+    found = shutil.which("ngrok")
+    if found:
+        return found
+    local = os.environ.get("LOCALAPPDATA")
+    if local:  # winget installs without updating the current shell's PATH
+        link = Path(local, "Microsoft", "WinGet", "Links", "ngrok.exe")
+        if link.is_file():
+            return str(link)
+        matches = sorted(Path(local, "Microsoft", "WinGet", "Packages").glob("Ngrok.Ngrok_*/ngrok.exe"))
+        if matches:
+            return str(matches[-1])
+    return None
+
+
+def ngrok_has_authtoken(ngrok: str) -> bool:
+    try:
+        result = subprocess.run([ngrok, "config", "check"], capture_output=True, text=True, encoding="utf-8",
+                                errors="replace", timeout=15)
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    match = re.search(r"configuration file at (.+)$", (result.stdout + result.stderr).strip(), re.MULTILINE)
+    if result.returncode != 0 or not match:
+        return False
+    try:
+        text = Path(match.group(1).strip()).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+    return re.search(r"^[ \t]*authtoken:[ \t]*\S+", text, re.MULTILINE) is not None
+
+
+def ngrok_command(ngrok: str, port: int, host: str) -> list[str]:
+    return [ngrok, "http", f"127.0.0.1:{port}", f"--url=https://{host}", "--inspect=false", "--log=stdout"]
+
+
+def hint_for(line: str) -> str | None:
+    for code, hint in HINTS.items():
+        if code in line:
+            return hint
+    if "lvl=eror" in line or "lvl=crit" in line:
+        return "ngrok reported a problem: " + line.strip()[:300]
+    return None
+
+
+def wait_online(proc: subprocess.Popen, timeout: float) -> tuple[bool, str]:
+    """Read ngrok's stdout until the tunnel starts, an error appears, ngrok exits, or timeout.
+
+    Reading continues in the background afterwards, into a bounded tail: see recent_output()."""
+    output = NgrokOutput()
+    proc.ngrok_output = output  # type: ignore[attr-defined]
+
+    def pump() -> None:
+        try:
+            for line in proc.stdout:  # type: ignore[union-attr]
+                output.tail.append(line)
+                if not output.done.is_set():
+                    output.pending.put(line)
+        except (OSError, ValueError):
+            pass
+        finally:
+            output.eof.set()
+            output.pending.put(None)
+
+    def finish(ok: bool, detail: str) -> tuple[bool, str]:
+        output.done.set()
+        while True:  # drop anything still queued; the tail keeps the recent lines
+            try:
+                output.pending.get_nowait()
+            except queue.Empty:
+                return ok, detail
+
+    threading.Thread(target=pump, daemon=True).start()
+    deadline = time.monotonic() + timeout
+    while (remaining := deadline - time.monotonic()) > 0:
+        try:
+            line = output.pending.get(timeout=min(remaining, 0.5))
+        except queue.Empty:
+            continue
+        if line is None:
+            return finish(False, "ngrok exited before the tunnel came online.")
+        if match := STARTED.search(line):
+            return finish(True, match.group(1))
+        if hint := hint_for(line):
+            return finish(False, hint)
+    return finish(False, f"ngrok didn't come online within {int(timeout)}s.")