overleaf-for-agents 0.1.0__tar.gz

overleaf_for_agents-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.pyright/
+pyrightconfig.json
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# leaf runtime
+.leaf/
+*.olauth
+~/.olauth
+
+# Claude Code
+.claude/
+.omc/

overleaf_for_agents-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: overleaf-for-agents
+Version: 0.1.0
+Summary: Bidirectional LaTeX sync for Overleaf — push, pull, and conflict resolution via git worktree
+Project-URL: Repository, https://github.com/yqi96/overleaf-for-agents
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: click>=8.0
+Requires-Dist: pychrome>=0.2
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# overleaf-for-agents
+
+Bidirectional sync between local files and Overleaf.
+
+## Installation
+
+```bash
+pip install overleaf-for-agents
+uv tool install overleaf-for-agents          # recommended with uv
+uv pip install -e /path/to/leaf             # local dev
+```
+
+## For Claude Code agents
+
+When the user asks to set up Overleaf sync, run:
+
+```bash
+leaf claude
+```
+
+Then read the output and follow every step.
+
+## License
+
+MIT

overleaf_for_agents-0.1.0/README.md

@@ -0,0 +1,25 @@
+# overleaf-for-agents
+
+Bidirectional sync between local files and Overleaf.
+
+## Installation
+
+```bash
+pip install overleaf-for-agents
+uv tool install overleaf-for-agents          # recommended with uv
+uv pip install -e /path/to/leaf             # local dev
+```
+
+## For Claude Code agents
+
+When the user asks to set up Overleaf sync, run:
+
+```bash
+leaf claude
+```
+
+Then read the output and follow every step.
+
+## License
+
+MIT

overleaf_for_agents-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "overleaf-for-agents"
+version = "0.1.0"
+description = "Bidirectional LaTeX sync for Overleaf — push, pull, and conflict resolution via git worktree"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "requests>=2.28",
+    "beautifulsoup4>=4.12",
+    "click>=8.0",
+    "pychrome>=0.2",   # CDP login backend (20 KB, uses existing Chrome)
+]
+
+[project.scripts]
+leaf = "leaf.cli:main"
+
+[project.urls]
+Repository = "https://github.com/yqi96/overleaf-for-agents"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/leaf"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "responses>=0.26.2",
+]

overleaf_for_agents-0.1.0/src/leaf/__init__.py

@@ -0,0 +1,2 @@
+"""leaf: push local LaTeX files to Overleaf."""
+__version__ = "0.1.0"

overleaf_for_agents-0.1.0/src/leaf/auth.py

@@ -0,0 +1,311 @@
+"""
+Authentication helpers for Overleaf.
+
+Cookie storage format is compatible with overleaf-sync (ols) v1.x,
+so `ols login` can be used as an alternative to the built-in login command.
+
+Login backends (in priority order)
+------------------------------------
+1. CDP  (default) — connects to your already-installed Chrome via Chrome
+   DevTools Protocol.  Zero extra downloads.  Requires only `pychrome`.
+   Falls back to Manual (2) automatically on any failure.
+
+2. Manual — opens the system browser, asks the user to copy the session
+   cookie from DevTools and paste it.  Universal fallback; works on any
+   OS and any browser without any extra dependencies.
+
+Note: the Claude Code browser MCP (mcp__browser__*) uses browser-pilot,
+also a CDP-based tool — the same protocol as option 1 above.
+"""
+
+from __future__ import annotations
+
+import pickle
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import requests
+from bs4 import BeautifulSoup
+
+COOKIE_PATH = Path.home() / ".olauth"
+LOGIN_URL = "https://www.overleaf.com/login"
+PROJECT_URL = "https://www.overleaf.com/project"
+SESSION_COOKIE_NAME = "overleaf_session2"
+
+# Default CDP debug port
+CDP_PORT = 9222
+
+# Known Chrome executable paths by platform
+_CHROME_CANDIDATES = [
+    # macOS
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    # Linux
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium-browser",
+    "chromium",
+]
+
+
+# ── Cookie I/O ────────────────────────────────────────────────────────────────
+
+def save_cookies(cookies: dict, csrf: str = "") -> None:
+    """Persist cookies to ~/.olauth (ols-compatible pickle format)."""
+    COOKIE_PATH.write_bytes(pickle.dumps({"cookie": cookies, "csrf": csrf}))
+
+
+def load_cookies() -> dict:
+    """
+    Load cookies from ~/.olauth.
+
+    Raises FileNotFoundError if the file does not exist (user has not logged in).
+    """
+    if not COOKIE_PATH.exists():
+        raise FileNotFoundError(
+            f"{COOKIE_PATH} not found.\n"
+            "Run `leaf login` to authenticate first."
+        )
+    data = pickle.loads(COOKIE_PATH.read_bytes())
+    return data["cookie"]
+
+
+# ── CSRF ──────────────────────────────────────────────────────────────────────
+
+def fetch_csrf(session: requests.Session, project_id: str) -> str:
+    """
+    Fetch a fresh CSRF token from the project page.
+
+    Raises RuntimeError if the session has expired.
+    """
+    r = session.get(
+        f"https://www.overleaf.com/project/{project_id}",
+        headers={"Referer": "https://www.overleaf.com"},
+    )
+    r.raise_for_status()
+    meta = BeautifulSoup(r.content, "html.parser").find(
+        "meta", {"name": "ol-csrfToken"}
+    )
+    if not meta:
+        raise RuntimeError(
+            "CSRF token not found — session may have expired.\n"
+            "Run `leaf login` to re-authenticate."
+        )
+    return meta.get("content")
+
+
+# ── Manual login (universal fallback — no browser automation needed) ──────────
+
+def login_manual() -> None:
+    """
+    Guided manual cookie extraction — universal fallback.
+
+    Opens the Overleaf login page in the system browser and walks the user
+    through copying the session cookie from DevTools.  Works on any browser,
+    any OS, even when Chrome/CDP/Playwright are unavailable.
+    """
+    import webbrowser
+
+    print()
+    print("── Manual login ────────────────────────────────────────────────")
+    print("Opening https://www.overleaf.com in your browser...")
+    webbrowser.open(LOGIN_URL)
+    print()
+    print("After you have logged in:")
+    print("  Chrome / Edge : F12 → Application → Cookies → https://www.overleaf.com")
+    print("  Firefox       : F12 → Storage → Cookies → https://www.overleaf.com")
+    print("  Safari        : Cmd+Option+I → Storage → Cookies")
+    print()
+    print(f"Find the cookie named  {SESSION_COOKIE_NAME!r}  and copy its Value.")
+    print()
+
+    try:
+        value = input("Paste cookie value here: ").strip()
+    except (EOFError, KeyboardInterrupt):
+        print("\nCancelled.", file=sys.stderr)
+        sys.exit(1)
+
+    if not value:
+        print("No value entered — aborted.", file=sys.stderr)
+        sys.exit(1)
+
+    save_cookies({SESSION_COOKIE_NAME: value})
+    print(f"\nCookie saved to {COOKIE_PATH}")
+    print("Verify with:  leaf list")
+
+
+# ── CDP login (primary — uses existing Chrome installation) ───────────────────
+
+def _find_chrome() -> str | None:
+    """Return path to a Chrome/Chromium executable, or None."""
+    for candidate in _CHROME_CANDIDATES:
+        if candidate.startswith("/"):
+            if Path(candidate).exists():
+                return candidate
+        else:
+            if shutil.which(candidate):
+                return candidate
+    return None
+
+
+def login_cdp(port: int = CDP_PORT, timeout: int = 300) -> None:
+    """
+    Launch Chrome with a CDP debug port, open Overleaf login, and extract
+    the session cookie once the user reaches the project dashboard.
+
+    Uses the user's existing Chrome installation — no extra downloads needed.
+    Only requires `pychrome` (pure Python, ~20 KB).
+
+    Parameters
+    ----------
+    port:    CDP remote debugging port (default 9222).
+    timeout: Seconds to wait for the user to complete login (default 300).
+    """
+    import json as _json
+    import tempfile
+    import threading as _threading
+
+    try:
+        import pychrome
+    except ImportError:
+        print(
+            "pychrome is missing — falling back to manual cookie extraction.\n"
+            "(To fix: pip install --upgrade leaf)",
+            file=sys.stderr,
+        )
+        login_manual()
+        return
+
+    chrome_bin = _find_chrome()
+    if not chrome_bin:
+        print(
+            "Chrome not found.  Falling back to manual cookie extraction.\n"
+            "(Alternatively: `leaf login --backend playwright`)",
+            file=sys.stderr,
+        )
+        login_manual()
+        return
+
+    # Use a temp profile dir so Chrome starts as an independent process even
+    # when another Chrome window is already open.  Without this, macOS hands
+    # the URL to the existing process and the debug port never opens.
+    tmpdir = tempfile.mkdtemp(prefix="leaf-chrome-")
+
+    proc = subprocess.Popen(
+        [
+            chrome_bin,
+            f"--remote-debugging-port={port}",
+            f"--user-data-dir={tmpdir}",
+            "--no-first-run",
+            "--no-default-browser-check",
+            "--disable-extensions",
+            LOGIN_URL,
+        ],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+
+    print(f"Chrome opened (pid {proc.pid}) — please log in to Overleaf...")
+
+    # Suppress pychrome's _recv_loop JSONDecodeError when WebSocket closes.
+    _orig_excepthook = _threading.excepthook
+    def _quiet_excepthook(args):
+        if args.exc_type is _json.JSONDecodeError:
+            return
+        _orig_excepthook(args)
+    _threading.excepthook = _quiet_excepthook
+
+    # Wait for CDP REST endpoint to become available.
+    # Use requests directly — pychrome's Browser.list_tab() has a GenericAttr
+    # bug in 0.2.4 that causes TypeError on every call.
+    import requests as _req
+    for _ in range(30):
+        try:
+            _req.get(f"http://127.0.0.1:{port}/json", timeout=1).json()
+            break
+        except Exception:
+            time.sleep(0.5)
+    else:
+        proc.terminate()
+        print(
+            "Failed to connect to Chrome via CDP.\n"
+            "Falling back to manual cookie extraction.",
+            file=sys.stderr,
+        )
+        login_manual()
+        return
+
+    # Poll for the session cookie.
+    deadline = time.time() + timeout
+    cookies: dict[str, str] = {}
+
+    while time.time() < deadline:
+        try:
+            tabs_data = _req.get(
+                f"http://127.0.0.1:{port}/json", timeout=2
+            ).json()
+            for tab_json in tabs_data:
+                if tab_json.get("type") != "page":
+                    continue
+                tab_url = tab_json.get("url", "")
+                # Only accept cookies once the user reaches the project
+                # dashboard — that URL confirms a successful, *current* login.
+                # Accepting cookies from /login (or any other overleaf.com page)
+                # is unsafe: Chrome Sync can restore a stale overleaf_session2
+                # from the user's Google account into the temp profile *before*
+                # the user has entered their credentials.
+                if not tab_url.startswith("https://www.overleaf.com/project"):
+                    continue
+                try:
+                    tab = pychrome.Tab(**tab_json)
+                    tab.start()
+                    result = tab.Network.getCookies(
+                        urls=["https://www.overleaf.com"]
+                    )
+                    tab.stop()
+                    found = {
+                        c["name"]: c["value"]
+                        for c in result.get("cookies", [])
+                        if c["name"] in (SESSION_COOKIE_NAME, "GCLB")
+                    }
+                    if SESSION_COOKIE_NAME in found:
+                        cookies = found
+                except Exception:
+                    try:
+                        tab.stop()
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+
+        if SESSION_COOKIE_NAME in cookies:
+            break
+        time.sleep(1)
+
+    proc.terminate()
+
+    # Clean up the temporary profile directory
+    import shutil as _shutil
+    try:
+        _shutil.rmtree(tmpdir, ignore_errors=True)
+    except Exception:
+        pass
+
+    if SESSION_COOKIE_NAME not in cookies:
+        print(
+            f"\nCDP login not confirmed within {timeout}s.\n"
+            "Falling back to manual cookie extraction...",
+            file=sys.stderr,
+        )
+        login_manual()
+        return
+
+    save_cookies(cookies)
+    print(f"Logged in.  Cookies saved to {COOKIE_PATH}")
+
+
+# Default login backend
+login_browser = login_cdp