overleaf-comments-export 0.3.0__tar.gz → 0.4.0__tar.gz

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overleaf-comments-export
-Version: 0.3.0
+Version: 0.4.0
 Summary: Export comment threads and tracked changes from an Overleaf project to Markdown + JSON, optimized for AI-agent consumption.
 Author: Shivang
 License: MIT
@@ -19,6 +19,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Text Processing :: Markup :: LaTeX
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
@@ -69,7 +70,13 @@ an Overleaf project URL and a logged-in browser session.
 pip install overleaf-comments-export
 ```
 
-Requires Python 3.10+. Works on macOS, Linux, and Windows.
+Requires Python 3.10 or newer (tested up to 3.14). Works on macOS, Linux, and
+Windows.
+
+The graphical window needs Python's Tk toolkit, which most Linux distributions
+package separately (`sudo apt install python3-tk` on Debian/Ubuntu). The
+command line never needs it, and `--gui` tells you what to install if it is
+missing.
 
 ## Quick start
 
@@ -104,6 +111,7 @@ In your output folder, by default:
 | `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. |
+| `response-letter.md` | (Optional, `--response-letter`) A point-by-point reply document, pre-filled with every open comment grouped by who raised it, with blanks for your response. |
 | `by-reviewer/<name>.md` | (Optional, `--per-reviewer`) One Markdown per reviewer with only their threads. |
 | `comments.log` | Diagnostic log for the run. |
 
@@ -121,6 +129,9 @@ 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
+
+# Draft a point-by-point response letter for the open comments
+overleaf-comments-export --project-url … --out ./out --response-letter
 ```
 
 Full flag reference: `overleaf-comments-export --help`.
@@ -162,14 +173,46 @@ Treat it like a password; it stops working when you sign out.
 | "Could not read Overleaf cookies from chrome" | Use the paste-the-cookie method above. |
 | "Overleaf could not find that project" | Wrong link, or this account has no access. |
 
-## Status & maintenance
+## Feedback, questions, and contributing
+
+This tool is actively maintained, and feedback shapes what gets built next.
+
+- **Something broke, or the output was wrong?**
+  [Open an issue.](https://github.com/Mangluu/overleaf-comments-export/issues/new/choose)
+  You do not need to be a programmer — paste what the tool said and that is
+  plenty. If Overleaf changes something, everything here stops working at once,
+  and you may be the first person to notice.
+- **Want it to do something it doesn't?**
+  [Suggest a feature.](https://github.com/Mangluu/overleaf-comments-export/issues/new/choose)
+  Tell me what you are trying to do, not just the feature — the real task
+  usually leads somewhere better.
+- **Just a question, or want to show what you built with it?**
+  [Discussions.](https://github.com/Mangluu/overleaf-comments-export/discussions)
+- **Want to contribute code?** See [CONTRIBUTING.md](CONTRIBUTING.md). It takes
+  about two minutes to get the tests running, and there are items marked
+  *help wanted* in [ROADMAP.md](ROADMAP.md).
+
+Never include your session cookie in an issue — it is a password for your
+Overleaf account, and nobody needs it to fix a bug.
+
+Maintained by [Shivang Gupta](https://github.com/Mangluu), who wrote it to deal
+with the review comments on his own papers.
+
+## What's coming next
+
+See [ROADMAP.md](ROADMAP.md). Short version: a response-letter scaffold,
+writing out the full source so an AI can see more than a snippet, and a diff
+between two exports so you can work through review comments in waves.
+
+Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 
-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.
+## A caution
 
-If Overleaf changes their internal API, this tool may stop working until
-someone (you?) adapts it.
+This tool uses Overleaf's internal endpoints, which are undocumented and can
+change without notice. It identifies itself honestly in every request, backs
+off when asked to, and only ever reads — it cannot modify your project. Even
+so, it may stop working the day Overleaf changes something. If that happens,
+please say so in an issue.
 
 ## License
 

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/README.md

@@ -33,7 +33,13 @@ an Overleaf project URL and a logged-in browser session.
 pip install overleaf-comments-export
 ```
 
-Requires Python 3.10+. Works on macOS, Linux, and Windows.
+Requires Python 3.10 or newer (tested up to 3.14). Works on macOS, Linux, and
+Windows.
+
+The graphical window needs Python's Tk toolkit, which most Linux distributions
+package separately (`sudo apt install python3-tk` on Debian/Ubuntu). The
+command line never needs it, and `--gui` tells you what to install if it is
+missing.
 
 ## Quick start
 
@@ -68,6 +74,7 @@ In your output folder, by default:
 | `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. |
+| `response-letter.md` | (Optional, `--response-letter`) A point-by-point reply document, pre-filled with every open comment grouped by who raised it, with blanks for your response. |
 | `by-reviewer/<name>.md` | (Optional, `--per-reviewer`) One Markdown per reviewer with only their threads. |
 | `comments.log` | Diagnostic log for the run. |
 
@@ -85,6 +92,9 @@ 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
+
+# Draft a point-by-point response letter for the open comments
+overleaf-comments-export --project-url … --out ./out --response-letter
 ```
 
 Full flag reference: `overleaf-comments-export --help`.
@@ -126,14 +136,46 @@ Treat it like a password; it stops working when you sign out.
 | "Could not read Overleaf cookies from chrome" | Use the paste-the-cookie method above. |
 | "Overleaf could not find that project" | Wrong link, or this account has no access. |
 
-## Status & maintenance
+## Feedback, questions, and contributing
+
+This tool is actively maintained, and feedback shapes what gets built next.
+
+- **Something broke, or the output was wrong?**
+  [Open an issue.](https://github.com/Mangluu/overleaf-comments-export/issues/new/choose)
+  You do not need to be a programmer — paste what the tool said and that is
+  plenty. If Overleaf changes something, everything here stops working at once,
+  and you may be the first person to notice.
+- **Want it to do something it doesn't?**
+  [Suggest a feature.](https://github.com/Mangluu/overleaf-comments-export/issues/new/choose)
+  Tell me what you are trying to do, not just the feature — the real task
+  usually leads somewhere better.
+- **Just a question, or want to show what you built with it?**
+  [Discussions.](https://github.com/Mangluu/overleaf-comments-export/discussions)
+- **Want to contribute code?** See [CONTRIBUTING.md](CONTRIBUTING.md). It takes
+  about two minutes to get the tests running, and there are items marked
+  *help wanted* in [ROADMAP.md](ROADMAP.md).
+
+Never include your session cookie in an issue — it is a password for your
+Overleaf account, and nobody needs it to fix a bug.
+
+Maintained by [Shivang Gupta](https://github.com/Mangluu), who wrote it to deal
+with the review comments on his own papers.
+
+## What's coming next
+
+See [ROADMAP.md](ROADMAP.md). Short version: a response-letter scaffold,
+writing out the full source so an AI can see more than a snippet, and a diff
+between two exports so you can work through review comments in waves.
+
+Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 
-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.
+## A caution
 
-If Overleaf changes their internal API, this tool may stop working until
-someone (you?) adapts it.
+This tool uses Overleaf's internal endpoints, which are undocumented and can
+change without notice. It identifies itself honestly in every request, backs
+off when asked to, and only ever reads — it cannot modify your project. Even
+so, it may stop working the day Overleaf changes something. If that happens,
+please say so in an issue.
 
 ## License
 

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/overleaf_comments_export/__main__.py

@@ -4,6 +4,7 @@ import argparse
 import logging
 import os
 import sys
+import traceback
 from pathlib import Path
 
 from . import __version__
@@ -11,6 +12,35 @@ from .client import OverleafClient, UserFacingError
 from .export import ExportResult, run_export
 
 
+def _no_tkinter_message() -> str:
+    """Platform-specific instructions for installing Python's GUI toolkit."""
+    if sys.platform == "darwin":
+        fix = (
+            "Install Python from python.org (it includes the GUI toolkit), or\n"
+            "with Homebrew run:\n\n"
+            "  brew install python-tk"
+        )
+    elif sys.platform.startswith("win"):
+        fix = (
+            "Re-run the Python installer from python.org, choose \"Modify\", and\n"
+            "tick \"tcl/tk and IDLE\"."
+        )
+    else:
+        fix = (
+            "Install it with your package manager, for example:\n\n"
+            "  Debian/Ubuntu : sudo apt install python3-tk\n"
+            "  Fedora        : sudo dnf install python3-tkinter\n"
+            "  Arch          : sudo pacman -S tk"
+        )
+    return (
+        "The window cannot open because this Python has no GUI toolkit "
+        "installed.\n\n"
+        f"{fix}\n\n"
+        "Or skip the window entirely and use the command line:\n\n"
+        "  overleaf-comments-export --project-url <your project link> --out ./comments"
+    )
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         prog="overleaf-comments-export",
@@ -106,6 +136,13 @@ def main(argv: list[str] | None = None) -> int:
         action="store_false",
         help="Skip writing comments.jsonl (the streaming-friendly companion).",
     )
+    parser.add_argument(
+        "--response-letter",
+        action="store_true",
+        help="Also write response-letter.md: a point-by-point reply document "
+        "pre-filled with every open comment, grouped by who raised it, with "
+        "blanks for your response.",
+    )
     parser.add_argument(
         "--per-reviewer",
         action="store_true",
@@ -120,8 +157,31 @@ def main(argv: list[str] | None = None) -> int:
     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()
+        try:
+            from .gui import launch_gui
+        except ImportError:
+            # tkinter is NOT bundled with Python everywhere — most Linux
+            # distributions ship it as a separate system package, and it is
+            # missing from some minimal/conda builds.
+            print(_no_tkinter_message(), file=sys.stderr)
+            return 1
+        try:
+            return launch_gui()
+        except Exception as e:
+            # Typically TclError on a headless machine (SSH, server, container).
+            if "display" in str(e).lower() or type(e).__name__ == "TclError":
+                print(
+                    "There is no screen to open a window on.\n\n"
+                    "This looks like a computer without a desktop (a server, or "
+                    "a remote session). Use the command line instead, for "
+                    "example:\n\n"
+                    "  overleaf-comments-export --project-url <your project link> "
+                    "--out ./comments\n\n"
+                    "Run with --help to see every option.",
+                    file=sys.stderr,
+                )
+                return 1
+            raise
 
     if not args.project_url or not args.out:
         parser.error("--project-url and --out are required in CLI mode (or pass --gui).")
@@ -151,12 +211,26 @@ def main(argv: list[str] | None = None) -> int:
             render_mode=args.render_mode,
             write_jsonl=args.write_jsonl,
             per_reviewer_reports=args.per_reviewer,
+            response_letter=args.response_letter,
             progress=lambda msg: print(msg, file=sys.stderr),
         )
     except UserFacingError as e:
         # Expected, explainable failures: no traceback, just what to do next.
         print(f"\n{e}", file=sys.stderr)
         return 1
+    except Exception:
+        # Unexpected: show the traceback, but also tell people where to send it.
+        # The moment something breaks is the only moment we have their attention.
+        traceback.print_exc()
+        print(
+            f"\nThat looks like a bug in overleaf-comments-export {__version__}.\n"
+            "Please report it (copy the lines above) at\n"
+            "  https://github.com/Mangluu/overleaf-comments-export/issues/new/choose\n"
+            "It probably affects other people too, and it cannot be fixed if "
+            "nobody says anything.",
+            file=sys.stderr,
+        )
+        return 2
     print(f"\nDone. Open: {result.markdown_path}")
     return 0
 

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/overleaf_comments_export/export.py

@@ -19,7 +19,7 @@ from .model import (
     Thread,
     TrackedChange,
 )
-from .render import render_markdown
+from .render import render_markdown, render_response_letter
 from .sections import find_headings, nearest_heading
 
 SCHEMA_VERSION = "1.3"
@@ -76,6 +76,7 @@ class ExportResult:
     jsonl_path: Path | None = None
     by_reviewer_dir: Path | None = None
     agents_path: Path | None = None
+    response_letter_path: Path | None = None
 
 
 def _build_user_map(threads_raw: dict[str, Any]) -> dict[str, dict[str, str]]:
@@ -340,6 +341,7 @@ def run_export(
     render_mode: str = "compact",
     write_jsonl: bool = True,
     per_reviewer_reports: bool = False,
+    response_letter: bool = False,
     progress: ProgressCallback | None = None,
 ) -> ExportResult:
     """Programmatic entry point used by both the CLI and the GUI."""
@@ -668,6 +670,15 @@ def run_export(
             written += 1
         progress(f"Wrote {written} per-reviewer report(s) into by-reviewer/")
 
+    letter_path: Path | None = None
+    if response_letter:
+        letter_path = out_dir / "response-letter.md"
+        letter_path.write_text(
+            render_response_letter(title, project_id, threads, anchored),
+            encoding="utf-8",
+        )
+        progress(f"Wrote {letter_path.name}")
+
     agents_path = out_dir / "agents.md"
     agents_path.write_text(_build_agents_md(title, project_id, json_path.name, md_path.name), encoding="utf-8")
     progress(f"Wrote {agents_path.name}")
@@ -688,6 +699,7 @@ def run_export(
         jsonl_path=(out_dir / "comments.jsonl") if write_jsonl else None,
         by_reviewer_dir=(out_dir / "by-reviewer") if per_reviewer_reports else None,
         agents_path=agents_path,
+        response_letter_path=letter_path,
     )
 
 

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/overleaf_comments_export/gui.py

@@ -425,6 +425,9 @@ class App:
         self.per_reviewer_var = tk.BooleanVar(
             value=bool(self.config.get("per_reviewer_reports", False))
         )
+        self.response_letter_var = tk.BooleanVar(
+            value=bool(self.config.get("response_letter", False))
+        )
         self.include_raw_var = tk.BooleanVar(
             value=bool(self.config.get("include_raw", False))
         )
@@ -433,6 +436,11 @@ class App:
             text="comments.jsonl (streaming companion)",
             variable=self.write_jsonl_var,
         ).pack(anchor="w")
+        ttk.Checkbutton(
+            extras_row,
+            text="Response letter draft (response-letter.md)",
+            variable=self.response_letter_var,
+        ).pack(anchor="w")
         ttk.Checkbutton(
             extras_row,
             text="Per-reviewer reports (by-reviewer/<name>.md)",
@@ -579,6 +587,7 @@ class App:
                 "render_mode": self.render_mode_var.get(),
                 "write_jsonl": bool(self.write_jsonl_var.get()),
                 "per_reviewer_reports": bool(self.per_reviewer_var.get()),
+                "response_letter": bool(self.response_letter_var.get()),
                 "include_raw": bool(self.include_raw_var.get()),
             }
         )
@@ -603,6 +612,7 @@ class App:
             render_mode=self.render_mode_var.get(),
             write_jsonl=bool(self.write_jsonl_var.get()),
             per_reviewer_reports=bool(self.per_reviewer_var.get()),
+            response_letter=bool(self.response_letter_var.get()),
             include_raw=bool(self.include_raw_var.get()),
         )
         self.worker = threading.Thread(
@@ -653,6 +663,8 @@ class App:
             self._append_log(f"JSONL:    {result.jsonl_path}")
         if result.agents_path is not None:
             self._append_log(f"Agents:   {result.agents_path}")
+        if result.response_letter_path is not None:
+            self._append_log(f"Letter:   {result.response_letter_path}")
         if result.by_reviewer_dir is not None:
             self._append_log(f"Per-reviewer: {result.by_reviewer_dir}")
 

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/overleaf_comments_export/render.py

@@ -277,6 +277,103 @@ def render_markdown(
     return "\n".join(out).rstrip() + "\n"
 
 
+def render_response_letter(
+    project_title: str,
+    project_id: str,
+    threads: dict[str, Thread],
+    anchored: list[AnchoredComment],
+) -> str:
+    """A point-by-point reply document, pre-filled with every open comment.
+
+    Grouped by the person who raised each point, because that is how journals
+    ask for rebuttals. Each entry carries its `C###` id so it can be traced
+    back to the full export.
+    """
+    out: list[str] = []
+    pulled = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    # Only points that still need answering, keyed by whoever raised them.
+    by_reviewer: dict[str, list[AnchoredComment]] = defaultdict(list)
+    for c in anchored:
+        thread = threads.get(c.thread_id)
+        if thread is None or thread.resolved or not thread.messages:
+            continue
+        first = min(thread.messages, key=lambda m: m.timestamp_ms)
+        who = _humanize_user(first.user_name, first.user_email, first.user_id)
+        by_reviewer[who].append(c)
+
+    total = sum(len(v) for v in by_reviewer.values())
+
+    out.append(f"# Response to reviewers — {project_title}")
+    out.append("")
+    out.append(f"_Draft generated {pulled}. {total} point(s) to address._")
+    out.append("")
+    out.append(
+        "Fill in the **Response** and **Change made** lines under each point. "
+        "The `C###` ids match `comments.json`, so you can ask an AI assistant "
+        "to draft any of them by id."
+    )
+    out.append("")
+    out.append("---")
+    out.append("")
+
+    if not total:
+        out.append("No open comments. Nothing to respond to.")
+        out.append("")
+        return "\n".join(out).rstrip() + "\n"
+
+    out.append("## Summary of changes")
+    out.append("")
+    out.append("_A short paragraph on the main revisions goes here._")
+    out.append("")
+
+    for reviewer in sorted(by_reviewer):
+        items = by_reviewer[reviewer]
+        out.append(f"## {reviewer} — {len(items)} point(s)")
+        out.append("")
+        for c in items:
+            thread = threads[c.thread_id]
+            ordered = sorted(thread.messages, key=lambda m: m.timestamp_ms)
+            where = c.nearest_heading or "no enclosing section"
+            # Don't leak "<unknown-6a21dec…>" into a document someone sends to
+            # an editor; the line number alone is enough there.
+            if c.pathname.startswith("<unknown-"):
+                locus = f"line {c.line_no}"
+            else:
+                locus = f"`{c.pathname}` line {c.line_no}"
+            out.append(f"### {c.short_id} — § {where} ({locus})")
+            out.append("")
+            quote = (c.anchored_text or "").strip().replace("\n", " ")
+            if quote:
+                out.append(f"**Referring to:** “{quote}”")
+                out.append("")
+            out.append("**Comment:**")
+            out.append("")
+            for line in (ordered[0].content or "").strip().splitlines() or [""]:
+                out.append(f"> {line}")
+            out.append("")
+            if len(ordered) > 1:
+                out.append("**Discussion so far:**")
+                out.append("")
+                for msg in ordered[1:]:
+                    who = _humanize_user(msg.user_name, msg.user_email, msg.user_id)
+                    body = (msg.content or "").strip().replace("\n", " ")
+                    out.append(f"> ↳ {who}: {body}")
+                out.append("")
+            out.append("**Response:**")
+            out.append("")
+            out.append("_TODO_")
+            out.append("")
+            out.append("**Change made:**")
+            out.append("")
+            out.append("_TODO — what changed, and where._")
+            out.append("")
+            out.append("---")
+            out.append("")
+
+    return "\n".join(out).rstrip() + "\n"
+
+
 def _status_badge(thread: Thread | None, stale: bool) -> str:
     bits = []
     if thread and thread.resolved:

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/overleaf_comments_export.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overleaf-comments-export
-Version: 0.3.0
+Version: 0.4.0
 Summary: Export comment threads and tracked changes from an Overleaf project to Markdown + JSON, optimized for AI-agent consumption.
 Author: Shivang
 License: MIT
@@ -19,6 +19,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Text Processing :: Markup :: LaTeX
 Classifier: Topic :: Scientific/Engineering
 Requires-Python: >=3.10
@@ -69,7 +70,13 @@ an Overleaf project URL and a logged-in browser session.
 pip install overleaf-comments-export
 ```
 
-Requires Python 3.10+. Works on macOS, Linux, and Windows.
+Requires Python 3.10 or newer (tested up to 3.14). Works on macOS, Linux, and
+Windows.
+
+The graphical window needs Python's Tk toolkit, which most Linux distributions
+package separately (`sudo apt install python3-tk` on Debian/Ubuntu). The
+command line never needs it, and `--gui` tells you what to install if it is
+missing.
 
 ## Quick start
 
@@ -104,6 +111,7 @@ In your output folder, by default:
 | `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. |
+| `response-letter.md` | (Optional, `--response-letter`) A point-by-point reply document, pre-filled with every open comment grouped by who raised it, with blanks for your response. |
 | `by-reviewer/<name>.md` | (Optional, `--per-reviewer`) One Markdown per reviewer with only their threads. |
 | `comments.log` | Diagnostic log for the run. |
 
@@ -121,6 +129,9 @@ 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
+
+# Draft a point-by-point response letter for the open comments
+overleaf-comments-export --project-url … --out ./out --response-letter
 ```
 
 Full flag reference: `overleaf-comments-export --help`.
@@ -162,14 +173,46 @@ Treat it like a password; it stops working when you sign out.
 | "Could not read Overleaf cookies from chrome" | Use the paste-the-cookie method above. |
 | "Overleaf could not find that project" | Wrong link, or this account has no access. |
 
-## Status & maintenance
+## Feedback, questions, and contributing
+
+This tool is actively maintained, and feedback shapes what gets built next.
+
+- **Something broke, or the output was wrong?**
+  [Open an issue.](https://github.com/Mangluu/overleaf-comments-export/issues/new/choose)
+  You do not need to be a programmer — paste what the tool said and that is
+  plenty. If Overleaf changes something, everything here stops working at once,
+  and you may be the first person to notice.
+- **Want it to do something it doesn't?**
+  [Suggest a feature.](https://github.com/Mangluu/overleaf-comments-export/issues/new/choose)
+  Tell me what you are trying to do, not just the feature — the real task
+  usually leads somewhere better.
+- **Just a question, or want to show what you built with it?**
+  [Discussions.](https://github.com/Mangluu/overleaf-comments-export/discussions)
+- **Want to contribute code?** See [CONTRIBUTING.md](CONTRIBUTING.md). It takes
+  about two minutes to get the tests running, and there are items marked
+  *help wanted* in [ROADMAP.md](ROADMAP.md).
+
+Never include your session cookie in an issue — it is a password for your
+Overleaf account, and nobody needs it to fix a bug.
+
+Maintained by [Shivang Gupta](https://github.com/Mangluu), who wrote it to deal
+with the review comments on his own papers.
+
+## What's coming next
+
+See [ROADMAP.md](ROADMAP.md). Short version: a response-letter scaffold,
+writing out the full source so an AI can see more than a snippet, and a diff
+between two exports so you can work through review comments in waves.
+
+Changes are recorded in [CHANGELOG.md](CHANGELOG.md).
 
-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.
+## A caution
 
-If Overleaf changes their internal API, this tool may stop working until
-someone (you?) adapts it.
+This tool uses Overleaf's internal endpoints, which are undocumented and can
+change without notice. It identifies itself honestly in every request, backs
+off when asked to, and only ever reads — it cannot modify your project. Even
+so, it may stop working the day Overleaf changes something. If that happens,
+please say so in an issue.
 
 ## License
 

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/overleaf_comments_export.egg-info/SOURCES.txt

@@ -21,4 +21,5 @@ tests/test_client.py
 tests/test_errors_and_auth.py
 tests/test_export.py
 tests/test_render.py
-tests/test_replies_and_changes.py
+tests/test_replies_and_changes.py
+tests/test_response_letter.py

{overleaf_comments_export-0.3.0 → overleaf_comments_export-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "overleaf-comments-export"
-version = "0.3.0"
+version = "0.4.0"
 description = "Export comment threads and tracked changes from an Overleaf project to Markdown + JSON, optimized for AI-agent consumption."
 readme = "README.md"
 license = { text = "MIT" }
@@ -34,6 +34,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Text Processing :: Markup :: LaTeX",
     "Topic :: Scientific/Engineering",
 ]
@@ -46,7 +47,10 @@ dependencies = [
 
 [project.optional-dependencies]
 gui = [
-    # tkinter ships with Python; sv-ttk adds a modern look-and-feel.
+    # NOTE: tkinter itself cannot be installed from PyPI. It ships with the
+    # python.org installers, but most Linux distributions package it
+    # separately (python3-tk / python3-tkinter / tk). The CLI never needs it,
+    # and `--gui` explains how to install it if it is missing.
     "sv-ttk>=2.6",
 ]
 test = [

overleaf_comments_export-0.4.0/tests/test_response_letter.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from overleaf_comments_export.model import (
+    AnchoredComment,
+    Message,
+    SourceContext,
+    Thread,
+)
+from overleaf_comments_export.render import render_response_letter
+
+
+def _thread(tid, author, body, resolved=False, reply=None):
+    msgs = [
+        Message(id=f"{tid}m1", content=body, timestamp_ms=1_000, user_id=author,
+                user_name=author.title(), user_email=f"{author}@x.com")
+    ]
+    if reply:
+        msgs.append(
+            Message(id=f"{tid}m2", content=reply, timestamp_ms=2_000, user_id="co",
+                    user_name="Co Author", user_email="co@x.com")
+        )
+    return Thread(id=tid, messages=msgs, resolved=resolved)
+
+
+def _comment(tid, short_id, line=10, heading="Introduction", anchor="some phrase"):
+    return AnchoredComment(
+        thread_id=tid, short_id=short_id, doc_id="d1", pathname="main.tex",
+        offset=0, anchored_text=anchor, line_no=line, col=0,
+        nearest_heading=heading, stale=False,
+        context=SourceContext(before="a", anchor=anchor, after="b", line_no=line),
+    )
+
+
+def test_letter_has_a_slot_for_every_open_comment():
+    threads = {
+        "t1": _thread("t1", "emma", "needs a citation"),
+        "t2": _thread("t2", "emma", "unclear phrasing"),
+    }
+    md = render_response_letter(
+        "My Paper", "abc", threads, [_comment("t1", "C001"), _comment("t2", "C002")]
+    )
+    assert "C001" in md and "C002" in md
+    assert md.count("**Response:**") == 2
+    assert md.count("**Change made:**") == 2
+    assert "2 point(s) to address" in md
+
+
+def test_letter_groups_by_who_raised_the_point():
+    threads = {
+        "t1": _thread("t1", "emma", "point one"),
+        "t2": _thread("t2", "xinyi", "point two"),
+    }
+    md = render_response_letter(
+        "P", "abc", threads, [_comment("t1", "C001"), _comment("t2", "C002")]
+    )
+    assert "## Emma — 1 point(s)" in md
+    assert "## Xinyi — 1 point(s)" in md
+
+
+def test_letter_skips_resolved_comments():
+    threads = {
+        "t1": _thread("t1", "emma", "already handled", resolved=True),
+        "t2": _thread("t2", "emma", "still open"),
+    }
+    md = render_response_letter(
+        "P", "abc", threads, [_comment("t1", "C001"), _comment("t2", "C002")]
+    )
+    assert "C002" in md
+    assert "C001" not in md
+    assert "1 point(s) to address" in md
+
+
+def test_letter_includes_the_discussion_so_far():
+    threads = {"t1": _thread("t1", "emma", "the ask", reply="we could cite Smith")}
+    md = render_response_letter("P", "abc", threads, [_comment("t1", "C001")])
+    assert "**Discussion so far:**" in md
+    assert "we could cite Smith" in md
+    assert "↳ Co Author" in md
+
+
+def test_letter_carries_location_and_quote():
+    threads = {"t1": _thread("t1", "emma", "vague")}
+    md = render_response_letter(
+        "P", "abc", threads,
+        [_comment("t1", "C001", line=42, heading="Method", anchor="novel framework")],
+    )
+    assert "§ Method" in md
+    assert "`main.tex` line 42" in md
+    assert "“novel framework”" in md
+
+
+def test_letter_with_nothing_open_says_so():
+    threads = {"t1": _thread("t1", "emma", "done", resolved=True)}
+    md = render_response_letter("P", "abc", threads, [_comment("t1", "C001")])
+    assert "No open comments" in md
+    assert "**Response:**" not in md
+
+
+def test_letter_survives_a_comment_whose_thread_is_missing():
+    md = render_response_letter("P", "abc", {}, [_comment("gone", "C001")])
+    assert "No open comments" in md
+
+
+def test_letter_hides_unmapped_filenames():
+    """A reader of the letter should never see "<unknown-6a21dec…>"."""
+    threads = {"t1": _thread("t1", "emma", "vague")}
+    c = _comment("t1", "C001", line=42)
+    c.pathname = "<unknown-6a21dec6cb39c30917f5c477>"
+    md = render_response_letter("P", "abc", threads, [c])
+    assert "unknown-" not in md
+    assert "line 42" in md