overleaf-review 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel Castellano
+
+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.

package/README.md

@@ -0,0 +1,78 @@
+# overleaf-review
+
+**The missing review layer for Overleaf's Git bridge.**
+
+Overleaf's Git integration syncs your `.tex` source — but silently drops the entire
+collaborative review layer: co-authors' **comments** (with their text anchors) and
+**tracked changes** live in Overleaf's own data model and never reach your repo. So if you
+draft in your editor (e.g. VSCode + an AI assistant) and sync via Git, you can't see the
+feedback your co-authors leave in Overleaf, and you can't push suggestions back.
+
+`overleaf-review` bridges that gap, **both directions**:
+
+- **`pull`** — read comments + tracked changes into a Git-friendly sidecar (`.overleaf/reviews.md`
+  and `.json`) so your tools have every co-author note in context.
+- **`push`** — turn your local edits into tracked-change suggestions in Overleaf, mapping files
+  to Overleaf docs by path (push one with `--file`, or every changed `.tex` at once). `--dry-run`
+  previews the exact ops first.
+- **`comment` / `resolve`** — create a comment anchored on any text, and resolve/reopen threads.
+
+> ⚠️ **Unofficial.** Overleaf has no public API for comments or tracked changes. This tool
+> talks to the same real-time and thread endpoints the web editor uses. It is **not affiliated
+> with or endorsed by Overleaf**, may break when Overleaf changes internals, and should be used
+> on your own account and projects. MIT licensed — use at your own risk.
+
+## Status
+
+Early but functional. The full read/write path is **proven end-to-end against live overleaf.com**
+(see [`src/probes/`](src/probes/)). Working commands: **`login`**, **`link`**, **`pull`**,
+**`push`** (with `--dry-run`), **`comment`**, and **`resolve`** — comments *and* tracked changes,
+both directions. Next: multi-file mapping and `npm publish`.
+
+## Install
+
+```bash
+npm install -g overleaf-review
+```
+
+Then run `overleaf-review <command>` anywhere. For local development, clone the repo and use
+`npx tsx src/cli.ts <command>` (as shown below).
+
+## Getting started
+
+```bash
+npm install
+
+# 1. Authenticate (stored in ~/.config/overleaf-review/, chmod 600 — never in the repo)
+npx tsx src/cli.ts login             # paste your overleaf_session2 cookie, or:
+npx tsx src/cli.ts login --browser   # opens your Chrome, log in normally (SSO works)
+
+# 2. Link this repo to an Overleaf project (id from the project URL)
+npx tsx src/cli.ts link --project <projectId>
+
+# 3. Sync the review layer
+npx tsx src/cli.ts pull                              # comments + changes → .overleaf/
+npx tsx src/cli.ts push --dry-run                    # preview ALL changed .tex as suggestions
+npx tsx src/cli.ts push                              # send them as tracked changes
+npx tsx src/cli.ts push --file sections/intro.tex    # or just one file
+npx tsx src/cli.ts comment --anchor "Introduction" --message "Expand this section"
+npx tsx src/cli.ts resolve --thread <id>             # thread ids come from `pull`
+```
+
+Auth grants full account access, so it's treated like a password: `login` stores it in
+`~/.config/overleaf-review/credentials.json` (chmod 600), never in the repo. `--browser` needs
+Playwright (`npm i -D playwright`) and drives your installed Chrome — no extra download — and
+works with institutional SSO. For dev you can instead put `OVERLEAF_SESSION2` and
+`OVERLEAF_PROJECT_ID` in a gitignored `.env` (env vars take priority).
+
+## How it works
+
+overleaf.com's editor speaks an old **socket.io 0.9** protocol over a WebSocket. The client
+([`src/overleaf-socket.ts`](src/overleaf-socket.ts)) joins the project, reads each doc's
+`ranges` (comments + tracked changes), and — to write — sends `applyOtUpdate` ops:
+a tracked change is an insert/delete op with a `meta.tc` flag; a comment is a `c` op plus a
+REST post of the message text. Comment message bodies come from the project's threads endpoint.
+
+## License
+
+MIT © Miguel Castellano

package/dist/cli.js

@@ -0,0 +1,766 @@
+#!/usr/bin/env node
+
+// src/commands/pull.ts
+import { writeFileSync as writeFileSync3, mkdirSync as mkdirSync3 } from "fs";
+import { join as join3 } from "path";
+
+// src/config.ts
+import "dotenv/config";
+
+// src/lib/credentials.ts
+import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function configDir() {
+  return process.env.OVERLEAF_REVIEW_CONFIG_DIR ?? join(homedir(), ".config", "overleaf-review");
+}
+function credentialsPath() {
+  return join(configDir(), "credentials.json");
+}
+function loadCredentials() {
+  try {
+    return JSON.parse(readFileSync(credentialsPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveCredentials(creds) {
+  mkdirSync(configDir(), { recursive: true });
+  const path = credentialsPath();
+  writeFileSync(path, JSON.stringify({ ...creds, savedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2) + "\n");
+  chmodSync(path, 384);
+  return path;
+}
+
+// src/lib/project-config.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, mkdirSync as mkdirSync2 } from "fs";
+import { join as join2 } from "path";
+var REPO_CONFIG_PATH = join2(".overleaf", "config.json");
+function loadProjectConfig() {
+  try {
+    return JSON.parse(readFileSync2(REPO_CONFIG_PATH, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function saveProjectConfig(cfg) {
+  mkdirSync2(".overleaf", { recursive: true });
+  writeFileSync2(REPO_CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n");
+  return REPO_CONFIG_PATH;
+}
+
+// src/config.ts
+function resolveBaseUrl() {
+  return process.env.OVERLEAF_BASE_URL ?? loadProjectConfig().baseUrl ?? loadCredentials().baseUrl ?? "https://www.overleaf.com";
+}
+function resolveSession2() {
+  const value = process.env.OVERLEAF_SESSION2 || loadCredentials().session2;
+  if (!value) {
+    throw new Error("Not authenticated \u2014 run `overleaf-review login` (or set OVERLEAF_SESSION2).");
+  }
+  return value;
+}
+function resolveProjectId() {
+  const value = process.env.OVERLEAF_PROJECT_ID || loadProjectConfig().projectId;
+  if (!value) {
+    throw new Error(
+      "No project linked \u2014 run `overleaf-review link --project <id>` (or set OVERLEAF_PROJECT_ID)."
+    );
+  }
+  return value;
+}
+var config = {
+  get baseUrl() {
+    return resolveBaseUrl();
+  },
+  get session2() {
+    return resolveSession2();
+  },
+  get projectId() {
+    return resolveProjectId();
+  },
+  /** Cookie header value used for both HTTP and the websocket handshake. */
+  get cookie() {
+    return `overleaf_session2=${this.session2}`;
+  }
+};
+
+// src/overleaf-socket.ts
+import WebSocket from "ws";
+var OverleafSocket = class {
+  constructor(baseUrl, cookie, opts = {}) {
+    this.baseUrl = baseUrl;
+    this.debug = opts.debug ?? true;
+    for (const part of cookie.split(";")) {
+      const eq = part.indexOf("=");
+      if (eq > 0) this.cookies.set(part.slice(0, eq).trim(), part.slice(eq + 1).trim());
+    }
+  }
+  baseUrl;
+  ws;
+  ackId = 1;
+  pendingAcks = /* @__PURE__ */ new Map();
+  handlers = /* @__PURE__ */ new Map();
+  heartbeat;
+  debug;
+  cookies = /* @__PURE__ */ new Map();
+  /** Browser-like headers — Overleaf's proxy can 502 non-browser upgrades. */
+  get browserHeaders() {
+    return {
+      Cookie: this.cookieHeader,
+      Origin: this.baseUrl,
+      "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36"
+    };
+  }
+  get cookieHeader() {
+    return [...this.cookies].map(([k, v]) => `${k}=${v}`).join("; ");
+  }
+  /** Merge Set-Cookie values — notably the GCLB load-balancer affinity cookie. */
+  absorbCookies(setCookies) {
+    for (const sc of setCookies) {
+      const pair = sc.split(";", 1)[0];
+      const eq = pair.indexOf("=");
+      if (eq > 0) this.cookies.set(pair.slice(0, eq).trim(), pair.slice(eq + 1).trim());
+    }
+  }
+  /** Subscribe to a server-pushed event (e.g. otUpdateApplied). */
+  on(event, handler) {
+    const list = this.handlers.get(event) ?? [];
+    list.push(handler);
+    this.handlers.set(event, list);
+  }
+  async connect(projectId) {
+    const handshakeUrl = `${this.baseUrl}/socket.io/1/?projectId=${projectId}&t=${Date.now()}`;
+    const res = await fetch(handshakeUrl, { headers: this.browserHeaders });
+    const setCookies = res.headers.getSetCookie?.() ?? [];
+    this.absorbCookies(setCookies);
+    if (this.debug) console.log(`[socket] cookies now: ${[...this.cookies.keys()].join(", ")}`);
+    if (!res.ok) {
+      throw new Error(
+        `socket.io handshake failed: ${res.status} ${res.statusText}. Check the session cookie and that the account is logged in.`
+      );
+    }
+    const body = await res.text();
+    const [sid, hbTimeout, , transports] = body.split(":");
+    if (this.debug) console.log(`[socket] handshake ok: ${body}`);
+    const wsUrl = `${this.baseUrl.replace(/^http/, "ws")}/socket.io/1/websocket/${sid}`;
+    if (this.debug) console.log(`[socket] transports=${transports}; ws=${wsUrl}`);
+    this.ws = new WebSocket(wsUrl, { headers: this.browserHeaders });
+    await new Promise((resolve2, reject) => {
+      this.ws.once("open", () => resolve2());
+      this.ws.once("error", reject);
+      this.ws.once("unexpected-response", (_req, response) => {
+        let errBody = "";
+        response.on("data", (chunk) => errBody += chunk.toString());
+        response.on(
+          "end",
+          () => reject(
+            new Error(
+              `ws upgrade rejected: ${response.statusCode} ${response.statusMessage}
+  headers: ${JSON.stringify(response.headers)}
+  body: ${errBody.slice(0, 800)}`
+            )
+          )
+        );
+      });
+    });
+    this.ws.on("message", (data) => this.onFrame(data.toString()));
+    const intervalMs = (Number(hbTimeout) || 30) * 800;
+    this.heartbeat = setInterval(() => this.send("2::"), intervalMs);
+    if (this.debug) console.log("[socket] websocket open");
+  }
+  /** Emit an event and resolve with the server's ack payload (array of args). */
+  emit(name, args, timeoutMs = 15e3) {
+    const id = this.ackId++;
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingAcks.delete(id);
+        reject(new Error(`emit('${name}') timed out after ${timeoutMs}ms with no ack`));
+      }, timeoutMs);
+      this.pendingAcks.set(id, (payload) => {
+        clearTimeout(timer);
+        resolve2(payload);
+      });
+      this.send(`5:${id}+::${JSON.stringify({ name, args })}`);
+    });
+  }
+  onFrame(frame) {
+    if (this.debug) console.log("[socket] <-", frame.slice(0, 200));
+    const type = frame[0];
+    const c1 = frame.indexOf(":");
+    const c2 = frame.indexOf(":", c1 + 1);
+    const c3 = frame.indexOf(":", c2 + 1);
+    const data = c3 === -1 ? "" : frame.slice(c3 + 1);
+    switch (type) {
+      case "2":
+        this.send("2::");
+        break;
+      case "5": {
+        try {
+          const { name, args } = JSON.parse(data);
+          for (const h of this.handlers.get(name) ?? []) h(args);
+        } catch {
+        }
+        break;
+      }
+      case "6": {
+        const plus = data.indexOf("+");
+        const ackId = Number(plus === -1 ? data : data.slice(0, plus));
+        const payload = plus === -1 ? [] : JSON.parse(data.slice(plus + 1));
+        this.pendingAcks.get(ackId)?.(payload);
+        this.pendingAcks.delete(ackId);
+        break;
+      }
+    }
+  }
+  send(frame) {
+    if (this.debug && !frame.startsWith("2")) console.log("[socket] ->", frame.slice(0, 200));
+    this.ws.send(frame);
+  }
+  close() {
+    if (this.heartbeat) clearInterval(this.heartbeat);
+    this.ws?.close();
+  }
+};
+
+// src/lib/session.ts
+function collectDocs(rootFolder) {
+  const out = [];
+  const walk = (folders, prefix) => {
+    for (const f of folders ?? []) {
+      const dir = f.name && f.name !== "rootFolder" ? prefix ? `${prefix}/${f.name}` : f.name : prefix;
+      for (const d of f.docs ?? []) {
+        out.push({ _id: d._id, name: d.name, path: dir ? `${dir}/${d.name}` : d.name });
+      }
+      walk(f.folders ?? [], dir);
+    }
+  };
+  walk(rootFolder ?? [], "");
+  return out;
+}
+async function openProject(opts = {}) {
+  const socket = new OverleafSocket(config.baseUrl, config.cookie, { debug: opts.debug ?? false });
+  const pushed = new Promise((resolve2) => socket.on("joinProjectResponse", resolve2));
+  await socket.connect(config.projectId);
+  const first = await Promise.race([
+    pushed,
+    new Promise((r) => setTimeout(() => r(null), 6e3))
+  ]);
+  let publicId = "";
+  let project;
+  if (first) {
+    publicId = first[0]?.publicId ?? "";
+    project = first[0]?.project;
+  } else {
+    const r = await socket.emit("joinProject", [{ project_id: config.projectId }]);
+    project = r[1];
+  }
+  return { socket, publicId, project, docs: collectDocs(project?.rootFolder) };
+}
+async function joinDoc(socket, docId) {
+  const res = await socket.emit("joinDoc", [docId, { encodeRanges: true }]);
+  const [err, lines, version, , ranges] = res;
+  if (err) throw new Error(`joinDoc error: ${JSON.stringify(err)}`);
+  return { version, lines: lines ?? [], ranges: ranges ?? {} };
+}
+
+// src/lib/rest.ts
+var UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+function headers(extra = {}) {
+  return { Cookie: config.cookie, "User-Agent": UA, Origin: config.baseUrl, ...extra };
+}
+async function getCsrfToken() {
+  const res = await fetch(`${config.baseUrl}/project/${config.projectId}`, { headers: headers() });
+  const html = await res.text();
+  const m = html.match(/<meta\s+name="ol-csrfToken"\s+content="([^"]+)"/) ?? html.match(/"csrfToken"\s*:\s*"([^"]+)"/) ?? html.match(/csrfToken\s*[:=]\s*["']([^"']+)["']/);
+  if (!m) {
+    throw new Error(
+      `CSRF token not found (HTTP ${res.status}). If this is a login page, the session cookie is invalid/expired.`
+    );
+  }
+  return m[1];
+}
+async function getThreads() {
+  const res = await fetch(`${config.baseUrl}/project/${config.projectId}/threads`, {
+    headers: headers()
+  });
+  if (!res.ok) throw new Error(`getThreads ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return res.json();
+}
+async function postThreadMessage(threadId, content, csrf) {
+  const res = await fetch(
+    `${config.baseUrl}/project/${config.projectId}/thread/${threadId}/messages`,
+    {
+      method: "POST",
+      headers: headers({ "Content-Type": "application/json", "X-CSRF-Token": csrf }),
+      body: JSON.stringify({ content })
+    }
+  );
+  if (!res.ok) {
+    throw new Error(`postThreadMessage ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  }
+  return res.status;
+}
+async function setThreadResolved(docId, threadId, reopen, csrf) {
+  const action = reopen ? "reopen" : "resolve";
+  const res = await fetch(
+    `${config.baseUrl}/project/${config.projectId}/doc/${docId}/thread/${threadId}/${action}`,
+    { method: "POST", headers: headers({ "X-CSRF-Token": csrf }) }
+  );
+  if (!res.ok) {
+    throw new Error(`${action} thread ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  }
+  return res.status;
+}
+async function validateSession(baseUrl, session2) {
+  const res = await fetch(`${baseUrl}/project`, {
+    headers: { Cookie: `overleaf_session2=${session2}`, "User-Agent": UA },
+    redirect: "follow"
+  });
+  const html = await res.text();
+  const looksLikeLogin = res.url.includes("/login") || /name="ol-page"\s+content="login"/.test(html) || html.includes('id="loginForm"');
+  if (looksLikeLogin) {
+    throw new Error("Session cookie is invalid or expired (got the login page).");
+  }
+  const m = html.match(/name="ol-usersEmail"\s+content="([^"]+)"/) ?? html.match(/"email":"([^"@]+@[^"]+)"/);
+  return m ? m[1] : "your Overleaf account";
+}
+
+// src/lib/anchors.ts
+function offsetToLine(lines, offset) {
+  let remaining = offset;
+  for (let i = 0; i < lines.length; i++) {
+    const len = lines[i].length;
+    if (remaining <= len) return i;
+    remaining -= len + 1;
+  }
+  return Math.max(0, lines.length - 1);
+}
+function lineContext(lines, line, radius = 1) {
+  const start = Math.max(0, line - radius);
+  const end = Math.min(lines.length - 1, line + radius);
+  const out = [];
+  for (let i = start; i <= end; i++) {
+    out.push(`${i === line ? ">" : " "} ${String(i + 1).padStart(3)}  ${lines[i]}`);
+  }
+  return out.join("\n");
+}
+
+// src/commands/pull.ts
+function buildMemberMap(project) {
+  const map = {};
+  const add = (u) => {
+    if (!u?._id) return;
+    map[u._id] = [u.first_name, u.last_name].filter(Boolean).join(" ") || u.email || u._id;
+  };
+  add(project?.owner);
+  for (const m of project?.members ?? []) add(m);
+  return map;
+}
+async function pull(outDir = ".overleaf") {
+  const { socket, project, docs } = await openProject();
+  const members = buildMemberMap(project);
+  const threads = await getThreads();
+  const comments = [];
+  const changes = [];
+  for (const doc of docs) {
+    const state = await joinDoc(socket, doc._id);
+    for (const c of state.ranges.comments ?? []) {
+      const line = offsetToLine(state.lines, c.op.p);
+      const thread = threads[c.op.t] ?? {};
+      comments.push({
+        doc: doc.path,
+        threadId: c.op.t,
+        anchor: c.op.c,
+        line: line + 1,
+        context: lineContext(state.lines, line),
+        resolved: Boolean(thread.resolved),
+        messages: (thread.messages ?? []).map((m) => ({
+          author: m.user?.first_name ?? members[m.user_id] ?? m.user_id,
+          email: m.user?.email,
+          content: m.content,
+          timestamp: m.timestamp
+        }))
+      });
+    }
+    for (const ch of state.ranges.changes ?? []) {
+      const isInsert = typeof ch.op.i === "string";
+      const line = offsetToLine(state.lines, ch.op.p);
+      changes.push({
+        doc: doc.path,
+        type: isInsert ? "insert" : "delete",
+        text: isInsert ? ch.op.i : ch.op.d,
+        line: line + 1,
+        context: lineContext(state.lines, line),
+        author: members[ch.metadata?.user_id] ?? ch.metadata?.user_id ?? "unknown",
+        ts: ch.metadata?.ts
+      });
+    }
+  }
+  socket.close();
+  const data = {
+    project: project?.name ?? "(unknown)",
+    projectId: config.projectId,
+    pulledAt: (/* @__PURE__ */ new Date()).toISOString(),
+    comments,
+    changes
+  };
+  mkdirSync3(outDir, { recursive: true });
+  writeFileSync3(join3(outDir, "reviews.json"), JSON.stringify(data, null, 2) + "\n");
+  writeFileSync3(join3(outDir, "reviews.md"), renderMarkdown(data));
+  return data;
+}
+function renderMarkdown(d) {
+  const L = [];
+  L.push(`# Overleaf review \u2014 ${d.project}`, "");
+  L.push(`_Pulled ${d.pulledAt} from project \`${d.projectId}\`._`, "");
+  L.push(`**${d.comments.length}** comment(s), **${d.changes.length}** tracked change(s).`, "");
+  const byDoc = (items) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const it of items) (m.get(it.doc) ?? m.set(it.doc, []).get(it.doc)).push(it);
+    return m;
+  };
+  if (d.comments.length) {
+    L.push("## Comments", "");
+    for (const [doc, items] of byDoc(d.comments)) {
+      L.push(`### ${doc}`, "");
+      for (const c of items) {
+        const flag = c.resolved ? " \u2014 \u2705 resolved" : "";
+        L.push(`#### \u{1F4AC} \u201C${c.anchor}\u201D \xB7 line ${c.line}${flag}`);
+        L.push("```", c.context, "```");
+        for (const m of c.messages) {
+          L.push(`- **${m.author}**: ${m.content}`);
+        }
+        if (!c.messages.length) L.push("- _(no message text)_");
+        L.push("");
+      }
+    }
+  }
+  if (d.changes.length) {
+    L.push("## Tracked changes", "");
+    for (const [doc, items] of byDoc(d.changes)) {
+      L.push(`### ${doc}`, "");
+      for (const ch of items) {
+        const verb = ch.type === "insert" ? "inserted" : "deleted";
+        L.push(`- **${verb}** at line ${ch.line} by ${ch.author}: \`${ch.text.replace(/\n/g, "\u23CE")}\``);
+        L.push("  ```", ch.context.replace(/^/gm, "  "), "  ```");
+      }
+      L.push("");
+    }
+  }
+  return L.join("\n");
+}
+
+// src/commands/push.ts
+import { readFileSync as readFileSync3, readdirSync } from "fs";
+import { relative, resolve as resolvePath, sep } from "path";
+import { randomBytes } from "crypto";
+import { diffChars } from "diff";
+function buildOps(remote, local) {
+  const ops = [];
+  let p = 0;
+  for (const part of diffChars(remote, local)) {
+    if (part.added) {
+      ops.push({ p, i: part.value });
+      p += part.value.length;
+    } else if (part.removed) {
+      ops.push({ p, d: part.value });
+    } else {
+      p += part.value.length;
+    }
+  }
+  return ops;
+}
+function preview(op) {
+  const kind = op.i != null ? "insert" : "delete";
+  const text = (op.i ?? op.d ?? "").replace(/\n/g, "\u23CE");
+  const clip = text.length > 60 ? text.slice(0, 60) + "\u2026" : text;
+  return `  ${kind.padEnd(6)} @ ${String(op.p).padStart(5)}  "${clip}"`;
+}
+function toOverleafPath(file) {
+  return relative(process.cwd(), resolvePath(file)).split(sep).join("/");
+}
+var IGNORE_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", ".overleaf", "tmp", "dist"]);
+function discoverLocalTex(dir = process.cwd(), acc = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || IGNORE_DIRS.has(entry.name)) continue;
+    const full = resolvePath(dir, entry.name);
+    if (entry.isDirectory()) discoverLocalTex(full, acc);
+    else if (entry.name.endsWith(".tex")) acc.push(toOverleafPath(full));
+  }
+  return acc;
+}
+function pickDoc(file, docName, docs, rootDocId, allowRootFallback) {
+  if (docName) return docs.find((d) => d.path === docName || d.name === docName);
+  const rel = toOverleafPath(file);
+  const base = rel.split("/").pop();
+  return docs.find((d) => d.path === rel) ?? docs.find((d) => d.name === base) ?? (allowRootFallback ? docs.find((d) => d._id === rootDocId) ?? docs[0] : void 0);
+}
+async function push(opts) {
+  const { socket, project, docs } = await openProject();
+  const files = opts.file ? [opts.file] : discoverLocalTex();
+  if (!files.length) {
+    console.log("No local .tex files found to push.");
+    socket.close();
+    return;
+  }
+  const plans = [];
+  for (const file of files) {
+    let local;
+    try {
+      local = readFileSync3(file, "utf8");
+    } catch {
+      console.log(`- ${file}: cannot read, skipped`);
+      continue;
+    }
+    const doc = pickDoc(file, opts.docName, docs, project.rootDoc_id, Boolean(opts.file));
+    if (!doc) {
+      console.log(`- ${file}: no matching Overleaf doc, skipped`);
+      continue;
+    }
+    const state = await joinDoc(socket, doc._id);
+    const ops = buildOps(state.lines.join("\n"), local);
+    if (ops.length) plans.push({ file, doc, ops, version: state.version });
+  }
+  if (!plans.length) {
+    console.log("Nothing to push \u2014 local files already match Overleaf.");
+    socket.close();
+    return;
+  }
+  for (const pl of plans) {
+    const ins = pl.ops.filter((o) => o.i != null).length;
+    const del = pl.ops.filter((o) => o.d != null).length;
+    console.log(`
+${pl.file} \u2192 ${pl.doc.path} (v${pl.version}): ${pl.ops.length} op(s), ${ins} ins / ${del} del`);
+    for (const op of pl.ops.slice(0, 12)) console.log(preview(op));
+    if (pl.ops.length > 12) console.log(`  \u2026 and ${pl.ops.length - 12} more`);
+  }
+  if (opts.dryRun) {
+    console.log("\n(dry run \u2014 nothing sent to Overleaf)");
+    socket.close();
+    return;
+  }
+  socket.on("otUpdateError", (a) => console.log("!! otUpdateError:", JSON.stringify(a)));
+  for (const pl of plans) {
+    const update = { doc: pl.doc._id, op: pl.ops, v: pl.version, meta: { tc: randomBytes(12).toString("hex") } };
+    const ack = await socket.emit("applyOtUpdate", [pl.doc._id, update], 2e4);
+    if (ack?.[0]) {
+      socket.close();
+      throw new Error(`Overleaf rejected ${pl.file}: ${JSON.stringify(ack[0])}`);
+    }
+  }
+  let allMatch = true;
+  for (const pl of plans) {
+    const after = await joinDoc(socket, pl.doc._id);
+    if (after.lines.join("\n") !== readFileSync3(pl.file, "utf8")) allMatch = false;
+  }
+  socket.close();
+  const totalOps = plans.reduce((n, p) => n + p.ops.length, 0);
+  console.log(
+    `
+\u2705 Pushed suggestions to ${plans.length} file(s), ${totalOps} tracked op(s) total \u2014 verified match: ${allMatch ? "yes" : "\u26A0\uFE0F NO, inspect"}`
+  );
+}
+
+// src/commands/comment.ts
+import { randomBytes as randomBytes2 } from "crypto";
+async function comment(opts) {
+  const { socket, project, docs } = await openProject();
+  const doc = opts.docName ? docs.find((d) => d.path === opts.docName || d.name === opts.docName) : docs.find((d) => d._id === project.rootDoc_id) ?? docs[0];
+  if (!doc) {
+    socket.close();
+    throw new Error(`doc not found: ${opts.docName ?? "(root)"}`);
+  }
+  const state = await joinDoc(socket, doc._id);
+  const flat = state.lines.join("\n");
+  const nth = Math.max(1, opts.occurrence ?? 1);
+  let p = -1;
+  let from = 0;
+  for (let i = 0; i < nth; i++) {
+    p = flat.indexOf(opts.anchor, from);
+    if (p < 0) break;
+    from = p + 1;
+  }
+  if (p < 0) {
+    socket.close();
+    throw new Error(`anchor text not found in ${doc.name}: "${opts.anchor}"`);
+  }
+  const threadId = randomBytes2(12).toString("hex");
+  const update = {
+    doc: doc._id,
+    op: [{ p, c: opts.anchor, t: threadId }],
+    v: state.version,
+    meta: {}
+  };
+  const ack = await socket.emit("applyOtUpdate", [doc._id, update], 15e3);
+  socket.close();
+  if (ack?.[0]) throw new Error(`Overleaf rejected the comment op: ${JSON.stringify(ack[0])}`);
+  const csrf = await getCsrfToken();
+  await postThreadMessage(threadId, opts.message, csrf);
+  console.log(`\u2705 Commented on "${opts.anchor}" in ${doc.name}  (thread ${threadId})`);
+}
+
+// src/commands/resolve.ts
+async function resolve(threadId, reopen = false) {
+  const { socket, docs } = await openProject();
+  let docId;
+  for (const doc of docs) {
+    const state = await joinDoc(socket, doc._id);
+    if ((state.ranges.comments ?? []).some((c) => c.op?.t === threadId)) {
+      docId = doc._id;
+      break;
+    }
+  }
+  socket.close();
+  if (!docId) {
+    throw new Error(
+      `thread ${threadId} not found in any doc's active comments (already resolved threads may not be locatable this way)`
+    );
+  }
+  const csrf = await getCsrfToken();
+  await setThreadResolved(docId, threadId, reopen, csrf);
+  console.log(`\u2705 Thread ${threadId} ${reopen ? "reopened" : "resolved"}`);
+}
+
+// src/commands/login.ts
+import { createInterface } from "readline/promises";
+async function login(opts) {
+  const baseUrl = opts.baseUrl ?? "https://www.overleaf.com";
+  let cookie = opts.cookie ?? process.env.OVERLEAF_SESSION2;
+  if (opts.browser) {
+    cookie = await captureCookieViaBrowser(baseUrl);
+  } else if (!cookie) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    console.log("Log into Overleaf in your browser (institutional SSO is fine), then copy the");
+    console.log("`overleaf_session2` cookie value:");
+    console.log("  devtools \u2192 Application \u2192 Cookies \u2192 your Overleaf host \u2192 overleaf_session2\n");
+    cookie = (await rl.question("Paste overleaf_session2: ")).trim();
+    rl.close();
+  }
+  if (!cookie) throw new Error("No cookie provided.");
+  const account = await validateSession(baseUrl, cookie);
+  const path = saveCredentials({ baseUrl, session2: cookie });
+  console.log(`
+\u2705 Logged in as ${account}. Saved to ${path} (chmod 600).`);
+}
+async function captureCookieViaBrowser(baseUrl) {
+  let chromium;
+  try {
+    const specifier = "playwright";
+    chromium = (await import(specifier)).chromium;
+  } catch {
+    throw new Error(
+      "Browser login needs Playwright. Install it with:\n  npm i -D playwright\nIt will drive your installed Chrome (no extra download)."
+    );
+  }
+  const browser = await chromium.launch({ headless: false, channel: "chrome" });
+  try {
+    const ctx = await browser.newContext();
+    const page = await ctx.newPage();
+    await page.goto(`${baseUrl}/login`);
+    console.log("A browser opened \u2014 log into Overleaf (SSO is fine). Waiting for the dashboard\u2026");
+    await page.waitForURL((url) => url.pathname.startsWith("/project"), { timeout: 3e5 });
+    const cookies = await ctx.cookies();
+    const found = cookies.find((c) => c.name === "overleaf_session2");
+    if (!found) throw new Error("Logged in, but no overleaf_session2 cookie was found.");
+    return found.value;
+  } finally {
+    await browser.close();
+  }
+}
+
+// src/commands/link.ts
+function link(projectId, baseUrl) {
+  const path = saveProjectConfig({ projectId, ...baseUrl ? { baseUrl } : {} });
+  console.log(`\u2705 Linked this repo to Overleaf project ${projectId} \u2192 ${path}`);
+  console.log("   (safe to commit \u2014 it contains no secrets.)");
+}
+
+// src/cli.ts
+function getFlag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : void 0;
+}
+function usage() {
+  console.log("overleaf-review \u2014 sync Overleaf review data with git\n");
+  console.log("Setup:");
+  console.log("  overleaf-review login [--cookie <val>] [--browser]");
+  console.log("      Authenticate and store your session (--browser is SSO-friendly)");
+  console.log("  overleaf-review link --project <id>");
+  console.log("      Link this repo to an Overleaf project (writes .overleaf/config.json)\n");
+  console.log("Review:");
+  console.log("  overleaf-review pull [--out <dir>]");
+  console.log("      Read comments + tracked changes into a sidecar (.overleaf/)");
+  console.log("  overleaf-review push [--file <f>] [--doc <name>] [--dry-run]");
+  console.log("      Send local edits as tracked-change suggestions (all changed .tex if no --file)");
+  console.log("  overleaf-review comment --anchor <text> --message <text> [--doc <name>] [--nth <n>]");
+  console.log("      Add a comment anchored on the given text");
+  console.log("  overleaf-review resolve --thread <id> [--reopen]");
+  console.log("      Resolve (or reopen) a comment thread (ids come from `pull`)");
+}
+async function main() {
+  const cmd = process.argv[2];
+  switch (cmd) {
+    case "login": {
+      await login({
+        cookie: getFlag("cookie"),
+        baseUrl: getFlag("base-url"),
+        browser: process.argv.includes("--browser")
+      });
+      break;
+    }
+    case "link": {
+      const project = getFlag("project");
+      if (!project) {
+        console.error("link requires --project <id>");
+        process.exit(1);
+      }
+      link(project, getFlag("base-url"));
+      break;
+    }
+    case "pull": {
+      const out = getFlag("out") ?? ".overleaf";
+      const data = await pull(out);
+      console.log(
+        `Pulled ${data.comments.length} comment(s) and ${data.changes.length} tracked change(s) from "${data.project}" \u2192 ${out}/`
+      );
+      break;
+    }
+    case "push": {
+      await push({ file: getFlag("file"), docName: getFlag("doc"), dryRun: process.argv.includes("--dry-run") });
+      break;
+    }
+    case "comment": {
+      const anchor = getFlag("anchor");
+      const message = getFlag("message");
+      if (!anchor || !message) {
+        console.error("comment requires --anchor <text> and --message <text>");
+        process.exit(1);
+      }
+      const nthRaw = getFlag("nth");
+      await comment({
+        docName: getFlag("doc"),
+        anchor,
+        message,
+        occurrence: nthRaw ? Number(nthRaw) : void 0
+      });
+      break;
+    }
+    case "resolve": {
+      const thread = getFlag("thread");
+      if (!thread) {
+        console.error("resolve requires --thread <id>");
+        process.exit(1);
+      }
+      await resolve(thread, process.argv.includes("--reopen"));
+      break;
+    }
+    default:
+      usage();
+      process.exit(cmd ? 1 : 0);
+  }
+}
+main().then(() => process.exit(0)).catch((e) => {
+  console.error(e instanceof Error ? e.message : e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "overleaf-review",
+  "version": "0.1.0",
+  "description": "The missing review layer for Overleaf's Git bridge — sync comments and tracked changes between Overleaf and your local repo.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Miguel Castellano",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michu5696/overleaf-review.git"
+  },
+  "homepage": "https://github.com/michu5696/overleaf-review#readme",
+  "bugs": {
+    "url": "https://github.com/michu5696/overleaf-review/issues"
+  },
+  "keywords": [
+    "overleaf",
+    "latex",
+    "git",
+    "comments",
+    "track-changes",
+    "review",
+    "cli"
+  ],
+  "bin": {
+    "overleaf-review": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/cli.js",
+    "pull": "tsx src/cli.ts pull",
+    "push": "tsx src/cli.ts push",
+    "probe:read": "tsx src/probes/01-read-ranges.ts",
+    "probe:comment": "tsx src/probes/02-write-comment.ts",
+    "probe:track": "tsx src/probes/03-write-track-change.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "diff": "^9.0.0",
+    "dotenv": "^16.4.5",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/diff": "^7.0.2",
+    "@types/node": "^22.10.0",
+    "@types/ws": "^8.5.13",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}