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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overleaf-comments-export
-Version: 0.2.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`.
@@ -137,19 +148,71 @@ by browser on macOS:
 | 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.
+can't decrypt. On Linux, snap-packaged browsers sandbox their cookie stores.
 
-On Linux, snap-packaged browsers sandbox their cookies — install browsers as
-native packages if you can.
+**If reading the cookie from your browser fails, paste it instead** — this
+works on every OS and browser:
 
-## Status & maintenance
+```bash
+overleaf-comments-export --project-url <url> --out ./out --cookie "PASTE_HERE"
+```
 
-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.
+Or set it once: `export OVERLEAF_SESSION="PASTE_HERE"`. In the GUI, choose
+**"Paste the cookie myself"** and click **How?** for step-by-step instructions.
 
-If Overleaf changes their internal API, this tool may stop working until
-someone (you?) adapts it.
+To find it: open Overleaf, press F12, go to Application (or Storage) →
+Cookies → `https://www.overleaf.com`, and copy the Value of `overleaf_session2`.
+Treat it like a password; it stops working when you sign out.
+
+## Troubleshooting
+
+| What you see | What it means |
+|---|---|
+| "Could not look up www.overleaf.com" | This computer is offline, or a VPN/DNS problem. Not an Overleaf issue. |
+| "Overleaf refused the request (not signed in)" | Your session expired. Sign in again in the browser, then re-run. |
+| "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. |
+
+## 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).
+
+## A caution
+
+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.2.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`.
@@ -101,19 +111,71 @@ by browser on macOS:
 | 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.
+can't decrypt. On Linux, snap-packaged browsers sandbox their cookie stores.
 
-On Linux, snap-packaged browsers sandbox their cookies — install browsers as
-native packages if you can.
+**If reading the cookie from your browser fails, paste it instead** — this
+works on every OS and browser:
 
-## Status & maintenance
+```bash
+overleaf-comments-export --project-url <url> --out ./out --cookie "PASTE_HERE"
+```
 
-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.
+Or set it once: `export OVERLEAF_SESSION="PASTE_HERE"`. In the GUI, choose
+**"Paste the cookie myself"** and click **How?** for step-by-step instructions.
 
-If Overleaf changes their internal API, this tool may stop working until
-someone (you?) adapts it.
+To find it: open Overleaf, press F12, go to Application (or Storage) →
+Cookies → `https://www.overleaf.com`, and copy the Value of `overleaf_session2`.
+Treat it like a password; it stops working when you sign out.
+
+## Troubleshooting
+
+| What you see | What it means |
+|---|---|
+| "Could not look up www.overleaf.com" | This computer is offline, or a VPN/DNS problem. Not an Overleaf issue. |
+| "Overleaf refused the request (not signed in)" | Your session expired. Sign in again in the browser, then re-run. |
+| "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. |
+
+## 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).
+
+## A caution
+
+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.4.0/overleaf_comments_export/__init__.py

@@ -0,0 +1,8 @@
+"""Export Overleaf comment threads and tracked changes."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("overleaf-comments-export")
+except PackageNotFoundError:  # running from a source checkout
+    __version__ = "0.0.0-dev"

overleaf_comments_export-0.4.0/overleaf_comments_export/__main__.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+import traceback
+from pathlib import Path
+
+from . import __version__
+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",
+        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(
+        "--cookie",
+        default=None,
+        metavar="VALUE",
+        help="Overleaf session cookie, pasted from your browser (DevTools → "
+        "Application → Cookies → overleaf_session2). Use this when reading "
+        "cookies from the browser fails. Also read from the OVERLEAF_SESSION "
+        "environment variable.",
+    )
+    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(
+        "--version", action="version", version=f"%(prog)s {__version__}"
+    )
+    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(
+        "--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",
+        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):
+        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).")
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+        stream=sys.stderr,
+    )
+
+    cookie_value = args.cookie or os.environ.get("OVERLEAF_SESSION") or None
+
+    try:
+        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,
+            cookie_value=cookie_value,
+            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,
+            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
+
+
+if __name__ == "__main__":
+    sys.exit(main())