npm - @erdemtuna/doc-review - Versions diffs - 0.7.0 → 0.8.1 - Mend

@erdemtuna/doc-review 0.7.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/src/chrome.html CHANGED Viewed

@@ -8,6 +8,27 @@
 </head>
 <body data-session="__SESSION_ID__" data-token="__TOKEN__">
   <div class="app">
+    <header class="toolbar" aria-label="Review controls">
+      <div class="toolbar-product" aria-hidden="true"></div>
+      <div class="mode-control">
+        <button type="button" id="modeButton" class="toolbar-btn" aria-haspopup="menu" aria-expanded="false">
+          <span id="modeIcon"></span><span id="modeLabel">View</span><span id="modeChevron"></span>
+        </button>
+        <div id="modeMenu" class="mode-menu" role="menu" hidden>
+          <button type="button" role="menuitemradio" aria-checked="true" data-mode="view">
+            <span data-icon="eye"></span><span><strong>View</strong><small>Editing off, comments enabled</small></span><span class="menu-check"></span>
+          </button>
+          <button type="button" role="menuitemradio" aria-checked="false" data-mode="edit">
+            <span data-icon="pencil"></span><span><strong>Edit</strong><small>Direct editing on</small></span><span class="menu-check"></span>
+          </button>
+        </div>
+      </div>
+      <div class="toolbar-actions">
+        <button type="button" id="commentsButton" class="toolbar-btn" aria-controls="drawer" aria-label="Comments" aria-expanded="false">
+          <span data-icon="messages"></span><span class="toolbar-label">Comments</span><span id="toolbarCount" class="count-badge">0</span>
+        </button>
+      </div>
+    </header>
     <main class="stage">
       <iframe
         id="frame"
@@ -15,34 +36,50 @@
         sandbox="allow-scripts allow-forms allow-modals"></iframe>
     </main>
-    <button type="button" id="handle" class="handle" title="Hide comments panel" aria-label="Hide comments panel">›</button>
-    <aside class="rail" id="rail">
-      <div class="rail-scroll">
-        <div class="rail-head">
-          <span class="section">Feedback</span>
-          <span class="dim" id="count">0</span>
-          <button type="button" id="theme" class="icon-btn" title="Switch chrome to dark" aria-label="Switch chrome to dark">☾</button>
+    <section id="compose" class="contextual-compose" role="dialog" aria-modal="false" aria-labelledby="composeTitle" hidden>
+      <div class="compose-head">
+        <div>
+          <span class="chip" id="composeKind">Selection</span>
+          <strong id="composeTitle">Add comment</strong>
         </div>
+        <button type="button" id="composeClose" class="icon-btn" title="Cancel comment" aria-label="Cancel comment"></button>
+      </div>
+      <div id="composeDirection" class="compose-direction" hidden>
+        <span id="composeDirectionText"></span>
+        <button type="button" id="composeReveal" class="link-action">Back to selection</button>
+      </div>
+      <p class="quote" id="composeQuote"></p>
+      <textarea id="composeText" rows="3" placeholder="What should change?" aria-label="Comment" aria-describedby="composeHelp"></textarea>
+      <p id="composeHelp" class="compose-help"><span>Enter to comment</span><span>Shift+Enter for new line</span></p>
+      <p id="composeError" class="compose-error" role="alert" hidden></p>
+      <div class="compose-actions">
+        <button type="button" id="composeAdd" class="btn-primary"><span data-icon="messageSquarePlus"></span><span id="composeAddLabel">Comment</span></button>
+        <button type="button" id="composeCancel" class="btn-ghost">Cancel</button>
+      </div>
+    </section>
-        <div id="compose" hidden>
-          <div class="compose">
-            <div class="compose-head">
-              <span class="chip" id="composeKind">Selection</span>
-              <span class="dim">Click to write · Esc to dismiss</span>
-            </div>
-            <p class="quote" id="composeQuote"></p>
-            <textarea id="composeText" rows="3" placeholder="What should change?"></textarea>
-            <div class="compose-actions">
-              <button type="button" id="composeAdd" class="btn-primary">Add comment <span class="key">⏎</span></button>
-              <button type="button" id="composeCancel" class="btn-ghost">Cancel</button>
-            </div>
-          </div>
+    <article id="alignedCard" class="aligned-card" hidden></article>
+    <aside class="drawer" id="drawer" aria-label="Review feedback" aria-hidden="true">
+      <div class="drawer-head">
+        <div>
+          <span class="section">Review</span>
+          <h2 id="drawerTitle">Comments</h2>
         </div>
+        <button type="button" id="theme" class="icon-btn" title="Switch chrome to dark" aria-label="Switch chrome to dark"></button>
+        <button type="button" id="drawerClose" class="icon-btn" title="Close review drawer" aria-label="Close review drawer"></button>
+      </div>
+      <div id="commentsSection" class="drawer-inventory" tabindex="-1" aria-labelledby="inventoryHeading">
+        <section>
+          <div class="rail-head">
+            <span class="section" id="inventoryHeading">Comments</span>
+            <span class="dim" id="count">0</span>
+          </div>
-        <div id="cards" class="cards"></div>
+          <div id="cards" class="cards"></div>
-        <div id="empty" class="empty">Select text or click an element to comment on it</div>
+          <div id="empty" class="empty">Select text or focus an element, then use the comment button</div>
+        </section>
         <section id="othersBox" hidden>
           <div class="rail-head tight">
@@ -61,21 +98,30 @@
           <div class="save-line" id="saveLine"><span class="dot"></span><span id="saveText"></span></div>
           <div class="edit-list" id="editList"></div>
         </section>
-      </div>
-      <div class="rail-foot">
-        <textarea id="note" rows="2" placeholder="Overall note…"></textarea>
-        <button type="button" id="send" class="send" disabled>Nothing to send yet</button>
-        <div class="agent-line" id="agentLine" hidden><span class="dot amber"></span><span id="agentText"></span></div>
-        <div class="handoff" id="handoff" hidden>
-          <p class="handoff-title">Sent — but no agent is listening yet.</p>
-          <p class="handoff-body">Paste this into your agent — Claude Code, Codex, or Cursor:</p>
-          <div class="handoff-cmd"><code id="handoffCmd"></code></div>
-          <button type="button" id="handoffCopy" class="btn-ghost">Copy prompt</button>
-        </div>
-        <button type="button" id="endReview" class="end-review" title="Stop this review and release the waiting agent">End review</button>
       </div>
+      <footer id="sendSection" class="drawer-footer send-section" tabindex="-1" aria-label="Send feedback">
+        <div class="send-primary">
+          <div class="rail-head tight">
+            <span class="section">Send feedback</span>
+          </div>
+          <textarea id="note" rows="2" placeholder="Overall note…"></textarea>
+          <button type="button" id="send" class="send" disabled>Nothing to send yet</button>
+          <div class="agent-line" id="agentLine" hidden><span class="dot amber"></span><span id="agentText"></span></div>
+        </div>
+        <div class="send-secondary">
+          <div class="handoff" id="handoff" hidden>
+            <p class="handoff-title">Sent — but no agent is listening yet.</p>
+            <p class="handoff-body">Paste this into your agent — Claude Code, Codex, or Cursor:</p>
+            <div class="handoff-cmd"><code id="handoffCmd"></code></div>
+            <button type="button" id="handoffCopy" class="btn-ghost">Copy prompt</button>
+          </div>
+          <button type="button" id="endReview" class="end-review" title="Stop this review and release the waiting agent">End review</button>
+        </div>
+      </footer>
     </aside>
+    <div id="drawerBackdrop" class="drawer-backdrop" hidden></div>
+    <div id="liveRegion" class="sr-only" role="status" aria-live="polite"></div>
   </div>
   <script type="module" src="/chrome.js"></script>

package/src/cli.js CHANGED Viewed

@@ -1,12 +1,20 @@
 #!/usr/bin/env node
 import fs from "node:fs";
-import http from "node:http";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { canonicalTarget, ensureStateDir, SERVER_PROTOCOL, serverPath, statePath, targetKey } from "./paths.js";
+import {
+  canonicalTarget,
+  ensureStateDir,
+  SERVER_PROTOCOL,
+  serverPath,
+  serverProtocolMatches,
+  statePath,
+  targetKey,
+} from "./paths.js";
 import { readServerLock } from "./server-lock.js";
 import { installSkills, shellQuote } from "./setup.js";
+import { createDeadline, DEFAULT_POLL_SECONDS, isRecoverableTransportError, parseServerResponse, pollUntilDeadline, requestRaw } from "./poll-transport.js";
 const here = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(fs.readFileSync(path.join(here, "..", "package.json"), "utf8"));
@@ -16,7 +24,7 @@ const HELP = `doc-review ${pkg.version}
   doc-review <file-or-localhost-url> Open a file or localhost page for review
   doc-review poll <target>          Wait for feedback, print it as JSON (for agents)
       --ack <batch_id>             Acknowledge that exact delivered batch, then keep waiting
-      --timeout <secs>             Exit with {"status":"timeout"} if nothing arrives
+      --timeout <secs>             End-to-end cutoff; default 12 hours (43200 seconds)
   doc-review status <target>        Report whether feedback is waiting, without blocking
   doc-review setup                  Teach Claude Code / Codex how to use doc-review
   doc-review setup --global         ...for every project, not just this one
@@ -34,72 +42,64 @@ function readServerRecord() {
   }
 }
-function request(server, options, body) {
-  const port = typeof server === "number" ? server : server.port;
-  const token = typeof server === "number" ? "" : server.token || "";
-  return new Promise((resolve, reject) => {
-    const req = http.request(
-      {
-        host: "127.0.0.1",
-        port,
-        ...options,
-        headers: { ...(token ? { "x-doc-review-token": token } : {}), ...(options.headers || {}) },
-      },
-      (res) => {
-        let raw = "";
-        res.setEncoding("utf8");
-        res.on("data", (chunk) => {
-          raw += chunk;
-        });
-        res.on("end", () => resolve({ status: res.statusCode, raw }));
-      }
-    );
-    req.on("error", reject);
-    if (options.timeout) req.setTimeout(options.timeout, () => req.destroy(new Error("timeout")));
-    if (body) req.write(JSON.stringify(body));
-    req.end();
-  });
-}
+const request = requestRaw;
-async function alive(server) {
+async function alive(server, deadline) {
+  if (!server?.port || !server.instance_id) return false;
+  const lock = readServerLock();
+  if (lock?.pid !== server.pid || lock?.instance_id !== server.instance_id) return false;
   try {
-    const lock = readServerLock();
-    if (lock?.pid !== server.pid || lock?.instance_id !== server.instance_id) return false;
-    const res = await request(server, { method: "GET", path: "/health", timeout: 1200 });
-    if (res.status !== 200) return false;
-    const health = JSON.parse(res.raw);
-    return (
-      health.protocol === SERVER_PROTOCOL &&
-      health.pid === server.pid &&
-      health.instance_id === server.instance_id
-    );
-  } catch {
-    return false;
+    deadline?.check();
+    const res = await request(server, {
+      method: "GET", path: "/health", timeout: Math.min(1200, deadline?.remaining() ?? 1200),
+    }, undefined, { time: deadline?.time });
+    deadline?.check();
+    const health = parseServerResponse(res);
+    if (health.pid !== server.pid || health.instance_id !== server.instance_id) {
+      throw new Error("The doc-review server identity does not match its writer lock. End the review and restart the server.");
+    }
+    if (!serverProtocolMatches(health.protocol) || !serverProtocolMatches(server.protocol)) {
+      throw new Error(
+        `Incompatible live doc-review server (protocol ${health.protocol}; this CLI requires ${SERVER_PROTOCOL}). ` +
+        "End active reviews and stop/restart the old doc-review server before retrying. " +
+        "Its live writer lock and queued feedback have not been changed.",
+      );
+    }
+    return true;
+  } catch (err) {
+    if (isRecoverableTransportError(err)) return false;
+    throw err;
   }
 }
-async function ensureServer() {
+async function ensureServer(deadline = createDeadline(20)) {
+  deadline.check();
   ensureStateDir();
   for (let launch = 0; launch < 3; launch += 1) {
     const saved = readServerRecord();
-    if (saved?.protocol === SERVER_PROTOCOL && saved.port && saved.instance_id && (await alive(saved))) return saved;
+    if (await alive(saved, deadline)) return saved;
+    deadline.check();
     const child = spawn(process.execPath, [path.join(here, "server-entry.js")], {
       detached: true,
       stdio: "ignore",
     });
+    let launchError;
+    child.on("error", (err) => { launchError = err; });
     child.unref();
     for (let attempt = 0; attempt < 60; attempt += 1) {
-      await new Promise((r) => setTimeout(r, 100));
+      await deadline.sleep(100);
+      if (launchError) throw launchError;
       const record = readServerRecord();
-      // Same protocol gate as above: a still-running server from an older
-      // version answers /health too, and must not be adopted here.
-      if (record?.protocol === SERVER_PROTOCOL && record.port && record.instance_id && (await alive(record))) return record;
+      if (await alive(record, deadline)) return record;
+      if (child.exitCode !== null && child.exitCode !== 0) {
+        throw new Error("The local doc-review server failed to start. Check the state directory permissions and server startup diagnostics before retrying.");
+      }
       if (child.exitCode !== null && !readServerLock()) break;
     }
   }
-  throw new Error("Could not start the local doc-review server.");
+  throw Object.assign(new Error("Could not start the local doc-review server yet."), { code: "SERVER_START_PENDING" });
 }
 function openBrowser(url) {
@@ -134,48 +134,6 @@ async function openCommand(input) {
   console.log(`\nWaiting for feedback? Run:\n  doc-review poll ${shellQuote(target.value)}`);
 }
-/**
- * One long-poll attempt. Resolves { kind: "data", raw } when the server
- * answers, or { kind: "timeout" } when the caller's deadline passes first.
- */
-function pollOnce(server, target, ackId, timeoutMs) {
-  const query = `target=${encodeURIComponent(target)}${ackId ? `&ack=${encodeURIComponent(ackId)}` : ""}`;
-  return new Promise((resolve, reject) => {
-    let done = false;
-    const settle = (fn, value) => {
-      if (done) return;
-      done = true;
-      clearTimeout(timer);
-      fn(value);
-    };
-    const req = http.request(
-      {
-        host: "127.0.0.1",
-        port: server.port,
-        method: "GET",
-        path: `/api/poll?${query}`,
-        headers: { "x-doc-review-token": server.token || "" },
-      },
-      (res) => {
-        let raw = "";
-        res.setEncoding("utf8");
-        res.on("data", (chunk) => {
-          raw += chunk;
-        });
-        res.on("end", () => settle(resolve, { kind: "data", raw: raw.trim() }));
-      }
-    );
-    const timer = timeoutMs
-      ? setTimeout(() => {
-          settle(resolve, { kind: "timeout" });
-          req.destroy();
-        }, timeoutMs)
-      : null;
-    req.on("error", (err) => settle(reject, err));
-    req.end();
-  });
-}
 /**
  * The consumer is an agent reading a pipe. process.exit() does not wait for
  * pending stdout writes, so a large payload could arrive truncated — always
@@ -185,50 +143,18 @@ function writeStdout(text) {
   return new Promise((resolve) => process.stdout.write(text, resolve));
 }
-function printTimeout(waitedSecs) {
-  const payload = {
-    status: "timeout",
-    waited_seconds: waitedSecs,
-    next_step:
-      "No feedback yet. Run the same poll command again to keep waiting, or `doc-review status <target>` to check without blocking.",
-  };
-  return writeStdout(`${JSON.stringify(payload, null, 2)}\n`);
-}
-async function pollCommand(input, { ackId = "", timeoutSecs = 0 } = {}) {
+async function pollCommand(input, { ackId = "", timeoutSecs = DEFAULT_POLL_SECONDS } = {}) {
+  const deadline = createDeadline(timeoutSecs);
   const target = canonicalTarget(input).value;
-  let server = await ensureServer();
   const label = /^https?:\/\//i.test(target) ? target : path.basename(target);
   process.stderr.write(`Waiting for feedback on ${label} — comment in the browser, then hit Send.\n`);
-  const deadline = timeoutSecs ? Date.now() + timeoutSecs * 1000 : null;
-  for (let attempt = 0; attempt < 3; attempt += 1) {
-    const remaining = deadline ? deadline - Date.now() : 0;
-    if (deadline && remaining <= 0) return printTimeout(timeoutSecs);
-    let result;
-    try {
-      result = await pollOnce(server, target, ackId && attempt === 0 ? ackId : "", remaining);
-    } catch (err) {
-      process.stderr.write(`Lost the connection (${err.message}); retrying.\n`);
-      server = await ensureServer();
-      continue;
-    }
-    if (result.kind === "timeout") return printTimeout(timeoutSecs);
-    if (!result.raw) {
-      server = await ensureServer();
-      continue;
-    }
-    try {
-      const batch = JSON.parse(result.raw);
-      await writeStdout(`${JSON.stringify(batch, null, 2)}\n`);
-      return;
-    } catch {
-      process.stderr.write("Unexpected response from the doc-review server; retrying.\n");
-    }
-  }
-  process.stderr.write("Gave up waiting for feedback.\n");
-  process.exit(1);
+  const batch = await pollUntilDeadline({
+    target, ackId, deadline, discover: ensureServer,
+    diagnostic: (text) => process.stderr.write(text),
+  });
+  await writeStdout(`${JSON.stringify(batch, null, 2)}\n`);
 }
 /**
@@ -239,7 +165,7 @@ async function pollCommand(input, { ackId = "", timeoutSecs = 0 } = {}) {
 async function statusCommand(input) {
   const target = canonicalTarget(input).value;
   const saved = readServerRecord();
-  if (saved?.protocol === SERVER_PROTOCOL && saved.port && saved.instance_id && (await alive(saved))) {
+  if (serverProtocolMatches(saved?.protocol) && saved.port && saved.instance_id && (await alive(saved))) {
     const res = await request(saved, { method: "GET", path: `/api/status?target=${encodeURIComponent(target)}` });
     if (res.status === 200) {
       process.stdout.write(`${JSON.stringify(JSON.parse(res.raw), null, 2)}\n`);
@@ -289,7 +215,7 @@ process.on("SIGINT", () => {
 });
 function parsePollArgs(rest) {
-  const parsed = { file: "", ackId: "", timeoutSecs: 0 };
+  const parsed = { file: "", ackId: "", timeoutSecs: DEFAULT_POLL_SECONDS };
   let sawTimeout = false;
   for (let i = 0; i < rest.length; i += 1) {
     const arg = rest[i];

package/src/comment-anchor.js ADDED Viewed

@@ -0,0 +1,22 @@
+const text = (value, limit) => typeof value === "string" ? value.slice(0, limit) : "";
+export function normalizeCommentAnchor(kind, anchor) {
+  if (!anchor || typeof anchor !== "object" || Array.isArray(anchor)) return null;
+  if (kind === "element") {
+    const selector = text(anchor.selector, 2000);
+    if (!selector) return null;
+    return {
+      selector,
+      ...(text(anchor.label, 500) ? { label: text(anchor.label, 500) } : {}),
+    };
+  }
+  const quote = text(anchor.quote, 4000);
+  if (!quote) return null;
+  return {
+    quote,
+    ...(text(anchor.prefix, 1000) ? { prefix: text(anchor.prefix, 1000) } : {}),
+    ...(text(anchor.suffix, 1000) ? { suffix: text(anchor.suffix, 1000) } : {}),
+    ...(text(anchor.selector, 2000) ? { selector: text(anchor.selector, 2000) } : {}),
+  };
+}

package/src/comment-target.js ADDED Viewed

@@ -0,0 +1,77 @@
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+export function sanitizeRect(rect) {
+  if (!rect) return null;
+  const values = ["left", "top", "right", "bottom", "width", "height"];
+  if (!values.every((key) => finite(rect[key]))) return null;
+  if (rect.width < 0 || rect.height < 0 || rect.right < rect.left || rect.bottom < rect.top) return null;
+  return {
+    left: rect.left,
+    top: rect.top,
+    right: rect.right,
+    bottom: rect.bottom,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+export function sanitizeClientRect(rect, viewport) {
+  const safe = sanitizeRect(rect);
+  if (!safe || !viewport || !finite(viewport.width) || !finite(viewport.height)) return null;
+  const { left: rawLeft, top: rawTop, right: rawRight, bottom: rawBottom } = safe;
+  if (rawRight <= 0 || rawBottom <= 0 || rawLeft >= viewport.width || rawTop >= viewport.height) return null;
+  const left = Math.max(0, Math.min(viewport.width, rawLeft));
+  const top = Math.max(0, Math.min(viewport.height, rawTop));
+  const right = Math.max(left, Math.min(viewport.width, rawRight));
+  const bottom = Math.max(top, Math.min(viewport.height, rawBottom));
+  return { left, top, right, bottom, width: right - left, height: bottom - top };
+}
+export function sanitizeClientRects(rects, viewport, limit = 64) {
+  if (!Array.isArray(rects)) return [];
+  return rects.slice(0, limit).map((rect) => sanitizeClientRect(rect, viewport)).filter(Boolean);
+}
+export function sanitizeClipRect(rect, viewport) {
+  const safe = sanitizeClientRect(rect, viewport);
+  return safe && safe.width > 0 && safe.height > 0 ? safe : null;
+}
+export function sanitizeRelation(value) {
+  return ["visible", "above", "below", "unavailable"].includes(value) ? value : "unavailable";
+}
+export function targetMessage(
+  { kind, quote, anchor, rects, generation, relation, clip, horizontal },
+  viewport
+) {
+  const safeRects = sanitizeClientRects(rects, viewport);
+  const safeClip = sanitizeClipRect(clip, viewport);
+  if (!Number.isSafeInteger(generation) || generation < 1) return null;
+  const safeRelation = sanitizeRelation(relation);
+  if (!safeClip || (safeRelation === "visible" && !safeRects.length)) return null;
+  return {
+    kind: kind === "element" ? "element" : "selection",
+    quote: String(quote || ""),
+    anchor: anchor || null,
+    rects: safeRects,
+    generation,
+    relation: safeRelation,
+    clip: safeClip,
+    horizontal: finite(horizontal) ? Math.max(safeClip.left, Math.min(safeClip.right, horizontal)) : null,
+  };
+}
+export function acceptsTargetGeometry(currentGeneration, incoming) {
+  return !!incoming && Number.isSafeInteger(incoming.generation) && incoming.generation === currentGeneration;
+}
+export function acceptedOpenGeneration(
+  { pendingGeneration = null, retargetGeneration = null },
+  { accepted, requestedGeneration }
+) {
+  if (!accepted) return pendingGeneration;
+  if (requestedGeneration === retargetGeneration) return retargetGeneration;
+  if (requestedGeneration === pendingGeneration) return pendingGeneration;
+  return null;
+}

package/src/edit-limits.js ADDED Viewed

@@ -0,0 +1,23 @@
+export const MAX_EDIT_CHARACTERS = 200_000;
+const EDIT_FIELDS = ["before", "after", "before_html", "after_html", "moved_after", "moved_before"];
+export function limitEditFields(input) {
+  const fields = {};
+  const truncatedFields = [];
+  for (const field of EDIT_FIELDS) {
+    const value = input[field];
+    if (typeof value !== "string") continue;
+    let end = 0;
+    let count = 0;
+    // Count Unicode code points, not UTF-16 halves of an astral character.
+    for (const character of value) {
+      if (count === MAX_EDIT_CHARACTERS) break;
+      end += character.length;
+      count += 1;
+    }
+    fields[field] = value.slice(0, end);
+    if (end < value.length) truncatedFields.push(field);
+  }
+  return { fields, truncated: truncatedFields.length > 0, truncated_fields: truncatedFields };
+}