overleaf-comments-export 0.2.0__tar.gz

overleaf_comments_export-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shivang (https://github.com/Mangluu)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overleaf_comments_export-0.2.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: overleaf-comments-export
+Version: 0.2.0
+Summary: Export comment threads and tracked changes from an Overleaf project to Markdown + JSON, optimized for AI-agent consumption.
+Author: Shivang
+License: MIT
+Project-URL: Homepage, https://github.com/Mangluu/overleaf-comments-export
+Project-URL: Issues, https://github.com/Mangluu/overleaf-comments-export/issues
+Project-URL: Source, https://github.com/Mangluu/overleaf-comments-export
+Keywords: overleaf,latex,research,comments,review,academic,tracked-changes,ai-agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+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 :: Text Processing :: Markup :: LaTeX
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyoverleaf>=0.1.7
+Requires-Dist: browser-cookie3>=0.19
+Requires-Dist: requests>=2.31
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: gui
+Requires-Dist: sv-ttk>=2.6; extra == "gui"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# overleaf-comments-export
+
+> **⚠️ Unofficial tool.** This is a third-party utility that talks to Overleaf's
+> undocumented internal HTTP endpoints. It is not affiliated with or endorsed
+> by Overleaf. Endpoints may change without notice. Use at your own risk and
+> in accordance with [Overleaf's Terms of Service](https://www.overleaf.com/legal).
+
+Export the comment threads and tracked changes from an Overleaf project into
+clean Markdown + structured JSON — designed so an AI assistant (Claude,
+ChatGPT, etc.) can ingest reviewer feedback and help you address it.
+
+[![CI](https://github.com/Mangluu/overleaf-comments-export/actions/workflows/ci.yml/badge.svg)](https://github.com/Mangluu/overleaf-comments-export/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/overleaf-comments-export.svg)](https://pypi.org/project/overleaf-comments-export/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+
+## Why
+
+Overleaf doesn't provide a way to export comments or tracked changes for use
+outside the editor. If you want to:
+
+- have an AI agent draft point-by-point replies to reviewers,
+- archive reviewer discussions outside of Overleaf,
+- batch-address feedback across a large paper, or
+- split feedback by reviewer to delegate work,
+
+… you currently have to copy comments by hand. This tool automates that, given
+an Overleaf project URL and a logged-in browser session.
+
+## Install
+
+```bash
+pip install overleaf-comments-export
+```
+
+Requires Python 3.10+. Works on macOS, Linux, and Windows.
+
+## Quick start
+
+### CLI
+
+```bash
+overleaf-comments-export \
+    --project-url https://www.overleaf.com/project/<24-hex-id> \
+    --out ./paper-comments \
+    --browser safari
+```
+
+The first time you run it, sign in to Overleaf in your browser of choice;
+the tool reads the session cookie from there.
+
+### GUI
+
+```bash
+overleaf-comments-export --gui
+```
+
+Opens a small Tkinter window with all options surfaced. Best for non-technical
+users.
+
+## What it produces
+
+In your output folder, by default:
+
+| File | Purpose |
+|---|---|
+| `comments-<date>.md` | Human-readable Markdown grouped by file → section → line, with stable IDs (`C001`, `C002`, …) and source-context snippets around each anchor. |
+| `comments.json` | Structured data — `summary`, top-level `threads`, `files`, `comments`, `tracked_changes`, etc. Schema described in `agents.md`. |
+| `comments.jsonl` | One self-contained JSON record per comment for streaming/pipelines. |
+| `agents.md` | A brief instruction file telling an AI agent how to consume the batch. |
+| `by-reviewer/<name>.md` | (Optional, `--per-reviewer`) One Markdown per reviewer with only their threads. |
+| `comments.log` | Diagnostic log for the run. |
+
+## Filtering
+
+```bash
+# Only open comments
+overleaf-comments-export --project-url … --out ./out --no-resolved
+
+# Only one reviewer's threads
+overleaf-comments-export --project-url … --out ./out --reviewer "Emma"
+
+# Compact (default) vs. detailed (multi-line code-fence) layout
+overleaf-comments-export --project-url … --out ./out --render-mode detailed
+
+# Per-reviewer sub-reports under ./out/by-reviewer/
+overleaf-comments-export --project-url … --out ./out --per-reviewer
+```
+
+Full flag reference: `overleaf-comments-export --help`.
+
+## Browser authentication
+
+The tool reads the `overleaf_session2` cookie from your browser. Trade-offs
+by browser on macOS:
+
+| Browser | Notes |
+|---|---|
+| Safari | Recommended. No Keychain prompt; macOS may ask once for permission to read `~/Library/Cookies/`. |
+| Firefox | No Keychain prompt; plain SQLite cookie store. |
+| Chrome / Edge / Brave | Cookies are AES-encrypted with a Keychain-stored key; **you'll get a Keychain password prompt every run.** Hidden behind an opt-in in the GUI. |
+
+On Windows, Chrome 127+ uses App-Bound Encryption that `browser-cookie3`
+doesn't fully decrypt yet — prefer Firefox or Edge on Windows.
+
+On Linux, snap-packaged browsers sandbox their cookies — install browsers as
+native packages if you can.
+
+## Status & maintenance
+
+This is a personal research utility published in case it's useful to others.
+It is provided as-is, with no guaranteed maintenance, no SLA, and no roadmap.
+Pull requests are welcome; issues may or may not be acted upon.
+
+If Overleaf changes their internal API, this tool may stop working until
+someone (you?) adapts it.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

overleaf_comments_export-0.2.0/README.md

@@ -0,0 +1,120 @@
+# overleaf-comments-export
+
+> **⚠️ Unofficial tool.** This is a third-party utility that talks to Overleaf's
+> undocumented internal HTTP endpoints. It is not affiliated with or endorsed
+> by Overleaf. Endpoints may change without notice. Use at your own risk and
+> in accordance with [Overleaf's Terms of Service](https://www.overleaf.com/legal).
+
+Export the comment threads and tracked changes from an Overleaf project into
+clean Markdown + structured JSON — designed so an AI assistant (Claude,
+ChatGPT, etc.) can ingest reviewer feedback and help you address it.
+
+[![CI](https://github.com/Mangluu/overleaf-comments-export/actions/workflows/ci.yml/badge.svg)](https://github.com/Mangluu/overleaf-comments-export/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/overleaf-comments-export.svg)](https://pypi.org/project/overleaf-comments-export/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+
+## Why
+
+Overleaf doesn't provide a way to export comments or tracked changes for use
+outside the editor. If you want to:
+
+- have an AI agent draft point-by-point replies to reviewers,
+- archive reviewer discussions outside of Overleaf,
+- batch-address feedback across a large paper, or
+- split feedback by reviewer to delegate work,
+
+… you currently have to copy comments by hand. This tool automates that, given
+an Overleaf project URL and a logged-in browser session.
+
+## Install
+
+```bash
+pip install overleaf-comments-export
+```
+
+Requires Python 3.10+. Works on macOS, Linux, and Windows.
+
+## Quick start
+
+### CLI
+
+```bash
+overleaf-comments-export \
+    --project-url https://www.overleaf.com/project/<24-hex-id> \
+    --out ./paper-comments \
+    --browser safari
+```
+
+The first time you run it, sign in to Overleaf in your browser of choice;
+the tool reads the session cookie from there.
+
+### GUI
+
+```bash
+overleaf-comments-export --gui
+```
+
+Opens a small Tkinter window with all options surfaced. Best for non-technical
+users.
+
+## What it produces
+
+In your output folder, by default:
+
+| File | Purpose |
+|---|---|
+| `comments-<date>.md` | Human-readable Markdown grouped by file → section → line, with stable IDs (`C001`, `C002`, …) and source-context snippets around each anchor. |
+| `comments.json` | Structured data — `summary`, top-level `threads`, `files`, `comments`, `tracked_changes`, etc. Schema described in `agents.md`. |
+| `comments.jsonl` | One self-contained JSON record per comment for streaming/pipelines. |
+| `agents.md` | A brief instruction file telling an AI agent how to consume the batch. |
+| `by-reviewer/<name>.md` | (Optional, `--per-reviewer`) One Markdown per reviewer with only their threads. |
+| `comments.log` | Diagnostic log for the run. |
+
+## Filtering
+
+```bash
+# Only open comments
+overleaf-comments-export --project-url … --out ./out --no-resolved
+
+# Only one reviewer's threads
+overleaf-comments-export --project-url … --out ./out --reviewer "Emma"
+
+# Compact (default) vs. detailed (multi-line code-fence) layout
+overleaf-comments-export --project-url … --out ./out --render-mode detailed
+
+# Per-reviewer sub-reports under ./out/by-reviewer/
+overleaf-comments-export --project-url … --out ./out --per-reviewer
+```
+
+Full flag reference: `overleaf-comments-export --help`.
+
+## Browser authentication
+
+The tool reads the `overleaf_session2` cookie from your browser. Trade-offs
+by browser on macOS:
+
+| Browser | Notes |
+|---|---|
+| Safari | Recommended. No Keychain prompt; macOS may ask once for permission to read `~/Library/Cookies/`. |
+| Firefox | No Keychain prompt; plain SQLite cookie store. |
+| Chrome / Edge / Brave | Cookies are AES-encrypted with a Keychain-stored key; **you'll get a Keychain password prompt every run.** Hidden behind an opt-in in the GUI. |
+
+On Windows, Chrome 127+ uses App-Bound Encryption that `browser-cookie3`
+doesn't fully decrypt yet — prefer Firefox or Edge on Windows.
+
+On Linux, snap-packaged browsers sandbox their cookies — install browsers as
+native packages if you can.
+
+## Status & maintenance
+
+This is a personal research utility published in case it's useful to others.
+It is provided as-is, with no guaranteed maintenance, no SLA, and no roadmap.
+Pull requests are welcome; issues may or may not be acted upon.
+
+If Overleaf changes their internal API, this tool may stop working until
+someone (you?) adapts it.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

overleaf_comments_export-0.2.0/overleaf_comments_export/__init__.py

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

overleaf_comments_export-0.2.0/overleaf_comments_export/__main__.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+from pathlib import Path
+
+from .client import OverleafClient
+from .export import ExportResult, run_export
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="overleaf-comments-export",
+        description="Export Overleaf comment threads and tracked changes to Markdown.",
+    )
+    parser.add_argument(
+        "--gui",
+        action="store_true",
+        help="Launch the graphical interface (default if no other args).",
+    )
+    parser.add_argument(
+        "--project-url",
+        help="Full Overleaf project URL, e.g. https://www.overleaf.com/project/<24-hex-id>.",
+    )
+    parser.add_argument(
+        "--out",
+        type=Path,
+        help="Directory to write comments-<date>.md, comments.json, and comments.log into.",
+    )
+    parser.add_argument(
+        "--project-title",
+        default=None,
+        help="Optional human-readable title for the report header. Defaults to the project id.",
+    )
+    parser.add_argument(
+        "--browser",
+        default="auto",
+        choices=list(OverleafClient.SUPPORTED_BROWSERS),
+        help="Which browser to read cookies from. Default: auto-detect.",
+    )
+    parser.add_argument(
+        "--base-url",
+        default="https://www.overleaf.com",
+        help="Override the Overleaf base URL (for self-hosted instances).",
+    )
+    parser.add_argument(
+        "-v", "--verbose", action="store_true", help="More logging."
+    )
+    parser.add_argument(
+        "--render-mode",
+        choices=["compact", "detailed"],
+        default="compact",
+        help="Markdown layout: 'compact' (one line per comment, default) or "
+        "'detailed' (multi-line code-fence with anchor highlighted).",
+    )
+    parser.add_argument(
+        "--no-open",
+        dest="include_open",
+        action="store_false",
+        help="Skip open (unresolved) comments.",
+    )
+    parser.add_argument(
+        "--no-resolved",
+        dest="include_resolved",
+        action="store_false",
+        help="Skip resolved comments.",
+    )
+    parser.add_argument(
+        "--no-changes",
+        dest="include_changes",
+        action="store_false",
+        help="Skip tracked changes.",
+    )
+    parser.add_argument(
+        "--reviewer",
+        action="append",
+        default=[],
+        metavar="NAME",
+        help="Only include threads/changes touching this reviewer "
+        "(case-insensitive substring match against name and email). "
+        "Pass multiple times for OR-of-reviewers.",
+    )
+    parser.add_argument(
+        "--include-raw",
+        action="store_true",
+        help="Embed the unprocessed Overleaf API payloads inside comments.json.",
+    )
+    parser.add_argument(
+        "--no-jsonl",
+        dest="write_jsonl",
+        action="store_false",
+        help="Skip writing comments.jsonl (the streaming-friendly companion).",
+    )
+    parser.add_argument(
+        "--per-reviewer",
+        action="store_true",
+        help="Also write one Markdown per reviewer into by-reviewer/.",
+    )
+    parser.set_defaults(
+        include_open=True,
+        include_resolved=True,
+        include_changes=True,
+        write_jsonl=True,
+    )
+    args = parser.parse_args(argv)
+
+    if args.gui or (not args.project_url and not args.out):
+        from .gui import launch_gui
+        return launch_gui()
+
+    if not args.project_url or not args.out:
+        parser.error("--project-url and --out are required in CLI mode (or pass --gui).")
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    result: ExportResult = run_export(
+        project_url=args.project_url,
+        out_dir=args.out,
+        project_title=args.project_title,
+        base_url=args.base_url,
+        browser=args.browser,
+        verbose=args.verbose,
+        include_raw=args.include_raw,
+        include_open=args.include_open,
+        include_resolved=args.include_resolved,
+        include_changes=args.include_changes,
+        reviewer_filter=args.reviewer,
+        render_mode=args.render_mode,
+        write_jsonl=args.write_jsonl,
+        per_reviewer_reports=args.per_reviewer,
+        progress=lambda msg: print(msg, file=sys.stderr),
+    )
+    print(f"\nDone. Open: {result.markdown_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

overleaf_comments_export-0.2.0/overleaf_comments_export/anchors.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from bisect import bisect_right
+
+from .model import DocText
+
+
+def build_line_starts(text: str) -> list[int]:
+    """line_starts[i] = char offset where line (i+1) starts. So
+    bisect_right(line_starts, offset) gives the 1-indexed line number."""
+    starts = [0]
+    for i, ch in enumerate(text):
+        if ch == "\n":
+            starts.append(i + 1)
+    return starts
+
+
+def offset_to_line_col(line_starts: list[int], offset: int) -> tuple[int, int]:
+    """Convert a flat character offset into a 1-indexed (line, column).
+    Column is 0-indexed (chars after the line start)."""
+    if offset < 0:
+        offset = 0
+    line_no = bisect_right(line_starts, offset)
+    if line_no <= 0:
+        line_no = 1
+    col = offset - line_starts[line_no - 1]
+    return line_no, col
+
+
+def resolve_anchor(
+    doc: DocText, offset: int, anchored_text: str, search_window: int = 200
+) -> tuple[int, int, int, bool]:
+    """Map an offset+expected-text anchor to (resolved_offset, line, col, stale).
+
+    If text[offset:offset+len(anchored_text)] matches anchored_text, we trust it.
+    Otherwise, search +/- search_window characters for the anchored text and
+    re-anchor. If still not found, return the original offset's coords and
+    mark stale=True."""
+    text = doc.text
+    n = len(anchored_text)
+    if n > 0 and 0 <= offset <= len(text) - n and text[offset : offset + n] == anchored_text:
+        line, col = offset_to_line_col(doc.line_starts, offset)
+        return offset, line, col, False
+
+    if n > 0:
+        # Nearby search
+        lo = max(0, offset - search_window)
+        hi = min(len(text), offset + search_window + n)
+        idx = text.find(anchored_text, lo, hi)
+        if idx != -1:
+            line, col = offset_to_line_col(doc.line_starts, idx)
+            return idx, line, col, False
+        # Last-resort whole-document search; mark stale (since it moved far)
+        # but still produce a usable line/col rather than guessing.
+        idx = text.find(anchored_text)
+        if idx != -1:
+            line, col = offset_to_line_col(doc.line_starts, idx)
+            return idx, line, col, True
+
+    line, col = offset_to_line_col(doc.line_starts, min(offset, max(0, len(text) - 1)))
+    return offset, line, col, True