overleaf-review 0.2.1 → 0.3.0

package/README.md

@@ -35,13 +35,40 @@ workflow and carries the review layer Git can't represent.
 - 📥 **`pull`** — read comments + tracked changes (with anchors) into a Git-friendly sidecar
   (`.overleaf/reviews.md` + `.json`), so your tools have every co-author note in context.
 - 📤 **`push`** — turn local edits into **tracked-change suggestions**, mapping files to Overleaf
-  docs by path (one file, or every changed `.tex` at once). `--dry-run` previews the exact ops.
+  docs by path (one file, or every changed `.tex` at once). `--dry-run` previews the exact ops;
+  `--direct` sends plain edits instead of suggestions.
+- 🔄 **`fetch`** — write Overleaf's current text back down into your repo (read-only on Overleaf, so
+  it cannot disturb a single comment or tracked change).
+- 🖼️ **`upload`** — push figures, PDFs, or new files into Overleaf.
 - 💬 **`comment` / `reply` / `resolve` / `delete-comment` / `delete-message`** — full comment
   control: start a thread, reply, resolve/reopen, delete a whole thread or a single message.
 - ✅ **`accept` / `reject`** — act on your collaborators' tracked changes from the CLI.
 - 🔑 **`login`** — validated auth stored outside your repo (chmod 600); `--browser` mode is
   institutional-SSO friendly.
 
+## ⚠️ Don't mix this with Overleaf's Git/GitHub sync
+
+**Overleaf's Git integration writes documents by wholesale content replacement.** The review layer
+is stored separately, anchored by character offsets — so a bulk overwrite orphans or displaces your
+comments and tracked changes. (Overleaf's own docs advise against combining Git with track changes.)
+This isn't something a tool can patch around; it's inherent to how the bridge writes.
+
+`overleaf-review` writes through Overleaf's **real-time OT API** instead — incremental insert/delete
+ops that Overleaf *transforms the review ranges against*, so comments and tracked changes survive.
+
+**Recommended setup: unlink Overleaf's Git/GitHub sync and let `overleaf-review` be the only bridge.**
+
+| Need | Command |
+| --- | --- |
+| Overleaf text → your repo | `fetch` |
+| Your edits → Overleaf, as suggestions | `push` |
+| Your edits → Overleaf, directly | `push --direct` |
+| Figures / new files → Overleaf | `upload` |
+
+Your Git repo stays a completely normal repo — commit whatever you like, `.tex` included — and
+nothing bidirectional exists that can clobber the review record. (Renaming/deleting files is still
+done in the Overleaf UI.)
+
 ## 📦 Install
 
 ```bash
@@ -73,7 +100,9 @@ overleaf-review resolve --thread <id>       # thread ids come from `pull`
 | `login [--cookie <v>] [--browser]` | Authenticate and store your session (SSO-friendly `--browser`) |
 | `link --project <id>` | Link this repo to an Overleaf project (`.overleaf/config.json`) |
 | `pull [--out <dir>]` | Read comments + tracked changes into a sidecar |
-| `push [--file <f>] [--doc <name>] [--dry-run]` | Send local edits as tracked-change suggestions (all changed `.tex` if no `--file`) |
+| `fetch [--file <f>] [--dry-run]` | Write Overleaf's text down into local files (read-only on Overleaf) |
+| `upload <path…> [--folder <name>]` | Upload figures / new files into Overleaf |
+| `push [--file <f>] [--doc <name>] [--direct] [--dry-run]` | Send local edits as tracked suggestions (all changed `.tex` if no `--file`); `--direct` for plain edits |
 | `comment --anchor <text> --message <text> [--doc <name>] [--nth <n>]` | Add a comment anchored on the given text |
 | `reply --thread <id> --message <text>` | Reply to an existing comment thread |
 | `resolve --thread <id> [--reopen]` | Resolve (or reopen) a comment thread |
@@ -105,7 +134,7 @@ own account and projects. Use at your own risk.
 
 ## 🗺️ Roadmap
 
-- A `pull` that also writes doc content (not just the review sidecar)
+- File rename / delete (currently done in the Overleaf UI)
 - Trusted-publishing CI
 
 ## 📝 Changelog

package/dist/cli.js

@@ -327,6 +327,19 @@ async function acceptChanges(docId, changeIds, csrf) {
   if (!res.ok) throw new Error(`acceptChanges ${res.status}: ${(await res.text()).slice(0, 200)}`);
   return res.status;
 }
+async function uploadFile(folderId, name, bytes, csrf) {
+  const form = new FormData();
+  form.append("qqfile", new Blob([new Uint8Array(bytes)]), name);
+  form.append("name", name);
+  form.append("relativePath", "null");
+  const res = await fetch(
+    `${config.baseUrl}/project/${config.projectId}/upload?folder_id=${folderId}`,
+    // Deliberately no Content-Type — fetch sets the multipart boundary itself.
+    { method: "POST", headers: headers({ "X-CSRF-Token": csrf }), body: form }
+  );
+  if (!res.ok) throw new Error(`upload ${res.status}: ${(await res.text()).slice(0, 200)}`);
+  return res.json();
+}
 async function deleteMessage(threadId, messageId, csrf) {
   const res = await fetch(
     `${config.baseUrl}/project/${config.projectId}/thread/${threadId}/messages/${messageId}`,
@@ -567,6 +580,9 @@ async function push(opts) {
     socket.close();
     return;
   }
+  console.log(
+    opts.direct ? "Mode: DIRECT \u2014 plain edits (not marked as suggestions)" : "Mode: SUGGESTIONS \u2014 tracked changes for co-authors to accept/reject"
+  );
   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;
@@ -582,7 +598,8 @@ ${pl.file} \u2192 ${pl.doc.path} (v${pl.version}): ${pl.ops.length} op(s), ${ins
   }
   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 meta = opts.direct ? {} : { tc: randomBytes(12).toString("hex") };
+    const update = { doc: pl.doc._id, op: pl.ops, v: pl.version, meta };
     const ack = await socket.emit("applyOtUpdate", [pl.doc._id, update], 2e4);
     if (ack?.[0]) {
       socket.close();
@@ -596,12 +613,81 @@ ${pl.file} \u2192 ${pl.doc.path} (v${pl.version}): ${pl.ops.length} op(s), ${ins
   }
   socket.close();
   const totalOps = plans.reduce((n, p) => n + p.ops.length, 0);
+  const mode = opts.direct ? "direct edit(s)" : "tracked suggestion(s)";
   console.log(
     `
-\u2705 Pushed suggestions to ${plans.length} file(s), ${totalOps} tracked op(s) total \u2014 verified match: ${allMatch ? "yes" : "\u26A0\uFE0F NO, inspect"}`
+\u2705 Pushed ${totalOps} ${mode} across ${plans.length} file(s) \u2014 verified match: ${allMatch ? "yes" : "\u26A0\uFE0F NO, inspect"}`
+  );
+}
+
+// src/commands/fetch.ts
+import { writeFileSync as writeFileSync4, readFileSync as readFileSync4, mkdirSync as mkdirSync4, existsSync } from "fs";
+import { dirname } from "path";
+async function fetchDocs(opts) {
+  const { socket, docs } = await openProject();
+  const targets = opts.file ? docs.filter((d) => d.path === opts.file || d.name === opts.file) : docs;
+  if (!targets.length) {
+    console.log(`No matching doc for "${opts.file}".`);
+    socket.close();
+    return;
+  }
+  let changed = 0;
+  for (const doc of targets) {
+    const state = await joinDoc(socket, doc._id);
+    const remote = state.lines.join("\n");
+    const local = existsSync(doc.path) ? readFileSync4(doc.path, "utf8") : null;
+    if (local === remote) continue;
+    changed++;
+    const delta = local === null ? "(new file)" : `${local.length} \u2192 ${remote.length} chars`;
+    console.log(`  ${doc.path}  ${delta}`);
+    if (!opts.dryRun) {
+      mkdirSync4(dirname(doc.path), { recursive: true });
+      writeFileSync4(doc.path, remote);
+    }
+  }
+  socket.close();
+  if (!changed) {
+    console.log("Already up to date \u2014 local files match Overleaf.");
+    return;
+  }
+  console.log(
+    opts.dryRun ? `
+(dry run \u2014 ${changed} local file(s) would be overwritten)` : `
+\u2705 Fetched ${changed} file(s) from Overleaf.`
   );
 }
 
+// src/commands/upload.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { basename } from "path";
+function findFolder(folder, wanted, prefix = "") {
+  for (const f of folder?.folders ?? []) {
+    const path = prefix ? `${prefix}/${f.name}` : f.name;
+    if (f.name === wanted || path === wanted) return f;
+    const deeper = findFolder(f, wanted, path);
+    if (deeper) return deeper;
+  }
+  return void 0;
+}
+async function upload(paths, folderName) {
+  const { socket, project } = await openProject();
+  socket.close();
+  const root = project?.rootFolder?.[0];
+  if (!root?._id) throw new Error("could not resolve the project root folder");
+  let folderId = root._id;
+  if (folderName) {
+    const found = findFolder(root, folderName);
+    if (!found) throw new Error(`folder not found in project: ${folderName}`);
+    folderId = found._id;
+  }
+  const csrf = await getCsrfToken();
+  for (const path of paths) {
+    const bytes = readFileSync5(path);
+    const res = await uploadFile(folderId, basename(path), bytes, csrf);
+    console.log(`\u2705 Uploaded ${path} \u2192 ${res.entity_type} ${res.entity_id}`);
+  }
+}
+
 // src/commands/comment.ts
 import { randomBytes as randomBytes2 } from "crypto";
 async function comment(opts) {
@@ -831,6 +917,9 @@ function usage() {
   console.log("  link --project <id>                       Link this repo to an Overleaf project\n");
   console.log("Read:");
   console.log("  pull [--out <dir>]                        Comments + tracked changes \u2192 sidecar\n");
+  console.log("Content (replaces the git bridge \u2014 review-safe):");
+  console.log("  fetch [--file <f>] [--dry-run]            Overleaf text \u2192 local files (read-only)");
+  console.log("  upload <path\u2026> [--folder <name>]          Upload figures / new files to Overleaf\n");
   console.log("Comments:");
   console.log("  comment --anchor <text> --message <text> [--doc <name>] [--nth <n>]");
   console.log("  reply --thread <id> --message <text>      Reply to an existing thread");
@@ -838,7 +927,8 @@ function usage() {
   console.log("  delete-comment --thread <id>              Delete a whole thread");
   console.log("  delete-message --message-id <id>          Delete a single message\n");
   console.log("Tracked changes:");
-  console.log("  push [--file <f>] [--doc <name>] [--dry-run]   Send local edits as suggestions");
+  console.log("  push [--file <f>] [--doc <name>] [--direct] [--dry-run]");
+  console.log("        Send local edits as tracked suggestions (--direct = plain edits)");
   console.log("  accept --change <id> [--change <id> \u2026]    Accept collaborators\u2019 changes");
   console.log("  reject --change <id> [--change <id> \u2026]    Reject collaborators\u2019 changes");
   console.log("\n(thread/change ids come from `pull`; --change accepts comma-separated lists too)");
@@ -868,8 +958,31 @@ async function main() {
       break;
     }
     case "push":
-      await push({ file: getFlag("file"), docName: getFlag("doc"), dryRun: process.argv.includes("--dry-run") });
+      await push({
+        file: getFlag("file"),
+        docName: getFlag("doc"),
+        direct: process.argv.includes("--direct"),
+        dryRun: process.argv.includes("--dry-run")
+      });
+      break;
+    case "fetch":
+      await fetchDocs({ file: getFlag("file"), dryRun: process.argv.includes("--dry-run") });
       break;
+    case "upload": {
+      const argv = process.argv.slice(3);
+      const paths = [];
+      for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === "--folder") {
+          i++;
+          continue;
+        }
+        if (argv[i].startsWith("--")) continue;
+        paths.push(argv[i]);
+      }
+      if (!paths.length) fail("upload requires at least one file path");
+      await upload(paths, getFlag("folder"));
+      break;
+    }
     case "comment": {
       const anchor = getFlag("anchor");
       const message = getFlag("message");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overleaf-review",
-  "version": "0.2.1",
+  "version": "0.3.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",