claude-plan-review 0.3.2 → 0.4.0

package/src/server.js

@@ -7,6 +7,10 @@ import { DEFAULT_PORT, ROOT, SERVER_FILE } from "./paths.js";
 import {
   addComment,
   deleteComment,
+  deleteProject,
+  deleteVersion,
+  getDoc,
+  getManifest,
   getProjectMeta,
   getReview,
   getStorage,
@@ -16,9 +20,11 @@ import {
   listReviews,
   listVersions,
   pruneResolvedReviews,
+  recordPlan,
   resolveReview,
   setStorage,
 } from "./store.js";
+import { parsePlan, rewriteWikiLinks, validateDocs } from "./plan-parse.js";
 import { getChannel, listChannelStatus } from "./channels/index.js";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -27,10 +33,80 @@ const pkg = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8"));
 
 marked.setOptions({ gfm: true, breaks: false });
 
-function renderMarkdown(md) {
-  const html = marked.parse(md, { async: false });
+/**
+ * Render markdown, wrapping each top-level block in a `.md-block` div that
+ * carries its SOURCE line range (data-line-start / data-line-end). The browser
+ * uses these to map a text selection made in the rendered preview back to
+ * source line numbers, so comments stay line-anchored (same model the diff and
+ * comment store already use) while the reviewer works entirely in the preview.
+ *
+ * With `opts` ({key, version, validSlugs}) cross-document links are rewritten so
+ * they navigate inside the review UI instead of hitting the `doc:` pseudo-scheme:
+ *   1. pre-lex — `[[slug]]`/`[[slug|text]]` become `[text](doc:slug)`;
+ *   2. post-lex — every `link` token whose href starts `doc:` is rewritten to
+ *      `?project=KEY&version=N&doc=SLUG` and its anchor tagged `data-doc="SLUG"`
+ *      (the UI delegates clicks on `#preview a[data-doc]` to in-app nav).
+ * Only slugs present in `validSlugs` are rewritten. Called with NO opts the
+ * output is byte-identical to the plain single-document render.
+ */
+function renderMarkdown(md, opts) {
+  let src = md || "";
+  if (opts) src = rewriteWikiLinks(src); // step 1: pre-lex wiki-link normalization
+
+  const tokens = marked.lexer(src);
+
+  // step 2: rewrite `doc:` link tokens in place; remember href→slug so the
+  // rendered anchors can be tagged with data-doc (walkTokens can't add attrs).
+  const hrefToSlug = new Map();
+  if (opts) {
+    const validSlugs = opts.validSlugs ? new Set(opts.validSlugs) : null;
+    marked.walkTokens(tokens, (tok) => {
+      if (tok.type !== "link" || typeof tok.href !== "string" || !tok.href.startsWith("doc:")) {
+        return;
+      }
+      const slug = tok.href.slice(4).trim();
+      if (validSlugs && !validSlugs.has(slug)) return;
+      const params = [`doc=${encodeURIComponent(slug)}`];
+      if (opts.key != null) params.unshift(`version=${encodeURIComponent(opts.version)}`);
+      if (opts.key != null) params.unshift(`project=${encodeURIComponent(opts.key)}`);
+      const href = `?${params.join("&")}`;
+      tok.href = href;
+      // marked v14 leaves `&` literal in hrefs; register the escaped form too so
+      // the tag step is robust to a renderer that HTML-escapes the attribute.
+      hrefToSlug.set(href, slug);
+      hrefToSlug.set(href.replace(/&/g, "&"), slug);
+    });
+  }
+
+  let offset = 0; // running char offset into `src`; token.raw values concatenate to src
+  const out = [];
+  for (const tok of tokens) {
+    const raw = tok.raw || "";
+    if (tok.type !== "space") {
+      const before = src.slice(0, offset);
+      const startLine = before.length ? before.split("\n").length : 1;
+      const trimmed = raw.replace(/\s+$/, ""); // ignore trailing blank lines in the range
+      const endLine = src.slice(0, offset + trimmed.length).split("\n").length;
+      const one = [tok];
+      one.links = tokens.links; // preserve reference-style link definitions
+      let html = marked.parser(one);
+      if (hrefToSlug.size) html = tagDocLinks(html, hrefToSlug);
+      out.push(
+        `<div class="md-block" data-line-start="${startLine}" data-line-end="${endLine}">${html}</div>`,
+      );
+    }
+    offset += raw.length;
+  }
   // light sanitization — local tool, content authored by your own Claude session
-  return html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+  return out.join("\n").replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "");
+}
+
+/** Tag rewritten cross-doc anchors with `data-doc` (matched by exact href). */
+function tagDocLinks(html, hrefToSlug) {
+  return html.replace(/<a\s+href="([^"]*)"/g, (m, href) => {
+    const slug = hrefToSlug.get(href);
+    return slug ? `<a data-doc="${slug}" href="${href}"` : m;
+  });
 }
 
 const CONTENT_TYPES = {
@@ -123,18 +199,53 @@ async function handleApi(req, res, seg, url) {
   if (a === "projects" && !b) return sendJSON(res, listProjects());
 
   if (a === "projects" && b && !c) {
+    // DELETE /api/projects/:key?force= — whole project
+    if (method === "DELETE") {
+      if (!getProjectMeta(b)) return sendJSON(res, { error: "no such project" }, 404);
+      const r = deleteProject(b, { force: isForce(url) });
+      if (r.blocked)
+        return sendJSON(res, { error: "pending review blocks deletion", pendingReviews: r.pendingReviews }, 409);
+      return sendJSON(res, r);
+    }
     const meta = getProjectMeta(b);
     if (!meta) return sendJSON(res, { error: "no such project" }, 404);
     return sendJSON(res, { meta, versions: listVersions(b) });
   }
 
-  // /api/projects/:key/diff?from=&to=
+  // POST /api/projects/:key/bulk-delete — sibling of `versions`, immune to the NaN trap.
+  // ALWAYS 200 with partial success: {deleted:[n…], blocked:[{n,pendingReviews}…], meta}.
+  // (Never 409 — that stays only on single-version DELETE and project DELETE.) Done per
+  // version so a blocked one never stops the rest; force deletes blocked ones too.
+  if (a === "projects" && b && c === "bulk-delete" && !d && method === "POST") {
+    const body = JSON.parse((await readBody(req)) || "{}");
+    const versions = Array.isArray(body.versions)
+      ? body.versions.map(Number).filter(Number.isFinite)
+      : [];
+    if (!versions.length) return sendJSON(res, { error: "`versions` must be a non-empty array" }, 400);
+    const force = !!body.force;
+    const deleted = [];
+    const blocked = [];
+    for (const n of versions) {
+      const r = deleteVersion(b, n, { force });
+      if (r.deleted) deleted.push(n);
+      else if (r.blocked) blocked.push({ n, pendingReviews: r.pendingReviews });
+    }
+    return sendJSON(res, { deleted, blocked, meta: getProjectMeta(b) });
+  }
+
+  // /api/projects/:key/diff?from=&to=&doc=  (doc-scoped; default root)
   if (a === "projects" && b && c === "diff") {
     const from = Number(url.searchParams.get("from"));
     const to = Number(url.searchParams.get("to"));
+    const doc = url.searchParams.get("doc") || "root";
+    const fromDoc = getDoc(b, from, doc);
+    const toDoc = getDoc(b, to, doc);
     return sendJSON(res, {
-      from: { n: from, markdown: getVersion(b, from)?.markdown ?? "" },
-      to: { n: to, markdown: getVersion(b, to)?.markdown ?? "" },
+      doc,
+      fromMissing: !fromDoc,
+      toMissing: !toDoc,
+      from: { n: from, markdown: fromDoc?.markdown ?? "", missing: !fromDoc },
+      to: { n: to, markdown: toDoc?.markdown ?? "", missing: !toDoc },
     });
   }
 
@@ -147,21 +258,59 @@ async function handleApi(req, res, seg, url) {
   if (a === "projects" && b && c === "versions" && d) {
     const key = b;
     const n = Number(d);
+    if (!Number.isFinite(n)) return sendJSON(res, { error: "bad version number" }, 400);
+
+    // /api/projects/:key/versions/:n  (GET metadata | DELETE the version)
     if (!e) {
-      const v = getVersion(key, n);
-      if (!v) return sendJSON(res, { error: "no such version" }, 404);
-      return sendJSON(res, { n, markdown: v.markdown, html: renderMarkdown(v.markdown), meta: v.meta });
+      if (method === "DELETE") {
+        const r = deleteVersion(key, n, { force: isForce(url) });
+        if (r.blocked)
+          return sendJSON(res, { error: "pending review blocks deletion", pendingReviews: r.pendingReviews }, 409);
+        return sendJSON(res, r);
+      }
+      if (method === "GET") {
+        const v = getVersion(key, n);
+        if (!v) return sendJSON(res, { error: "no such version" }, 404);
+        const payload = { n, kind: v.kind, meta: v.meta, manifest: getManifest(key, n) };
+        if (v.kind === "single") {
+          payload.markdown = v.markdown;
+          payload.html = renderMarkdown(v.markdown);
+        }
+        return sendJSON(res, payload);
+      }
+      return sendJSON(res, { error: "method not allowed" }, 405);
+    }
+
+    // /api/projects/:key/versions/:n/docs/:slug  (GET one rendered document)
+    if (e === "docs" && seg[5] && method === "GET") {
+      const doc = getDoc(key, n, seg[5]);
+      if (!doc) return sendJSON(res, { error: "no such doc" }, 404);
+      const validSlugs = (getManifest(key, n)?.docs ?? []).map((x) => x.slug);
+      return sendJSON(res, {
+        slug: doc.slug,
+        title: doc.title,
+        parent: doc.parent,
+        markdown: doc.markdown,
+        html: renderMarkdown(doc.markdown, { key, version: n, validSlugs }),
+      });
     }
+
+    // /api/projects/:key/versions/:n/comments  (GET ?doc= filtered | POST)
     if (e === "comments" && !seg[5]) {
-      if (method === "GET") return sendJSON(res, listComments(key, n));
+      if (method === "GET") {
+        const doc = url.searchParams.get("doc");
+        return sendJSON(res, listComments(key, n, doc == null ? undefined : doc));
+      }
       if (method === "POST") {
         const body = JSON.parse((await readBody(req)) || "{}");
         if (!body.body?.trim()) return sendJSON(res, { error: "empty comment" }, 400);
         return sendJSON(
           res,
           addComment(key, n, {
+            doc: body.doc || "root",
             line: body.line ?? null,
             lineEnd: body.lineEnd ?? null,
+            quote: body.quote ?? null,
             body: body.body.trim(),
           }),
         );
@@ -177,6 +326,12 @@ async function handleApi(req, res, seg, url) {
     }
   }
 
+  // POST /api/plans — tools-first plan creation (same store path as the hook)
+  if (a === "plans" && !b && method === "POST") {
+    const body = JSON.parse((await readBody(req)) || "{}");
+    return handleCreatePlan(res, body, url);
+  }
+
   // /api/reviews ...
   if (a === "reviews" && !b) return sendJSON(res, listReviews());
   if (a === "reviews" && b === "pending")
@@ -194,6 +349,102 @@ async function handleApi(req, res, seg, url) {
   return sendJSON(res, { error: "unknown endpoint" }, 404);
 }
 
+/** True when a `?force=` query flag is present and not explicitly falsey. */
+function isForce(url) {
+  if (!url.searchParams.has("force")) return false;
+  const v = url.searchParams.get("force");
+  return v !== "false" && v !== "0";
+}
+
+/**
+ * Normalize a parent attribute → parent slug, or null for a top-level doc.
+ * Mirrors plan-parse/mcp's normParent (absent/""/"root"/self ⇒ top-level) so a
+ * `docs`-array POST stores an identical tree to the marker-parsed path.
+ */
+function normParent(parent, slug) {
+  if (parent == null) return null;
+  const v = String(parent).trim();
+  if (v === "" || v === "root" || v === slug) return null;
+  return v;
+}
+
+/** Turn a caller-supplied docs array into the store's tree shape. */
+function docsToTree(docs) {
+  const normalized = docs.map((d, i) => ({
+    slug: d.slug,
+    title: d.title,
+    parent: normParent(d.parent, d.slug),
+    body: d.body ?? "",
+    order: i,
+  }));
+  const root = normalized.find((d) => d.parent === null)?.slug ?? "root";
+  return { kind: "tree", root, docs: normalized };
+}
+
+/**
+ * POST /api/plans — record a plan and open a review WITHOUT the hook. Accepts
+ * exactly one of `docs` (structured tree), `markdown` (single doc), or `plan`
+ * (raw marker string the server parses). Records through the SAME `recordPlan`
+ * the hook uses, so store shapes are identical. 201 {key,version,reviewId,
+ * reviewUrl} on success; 400 {error, issues?} on a malformed plan.
+ */
+async function handleCreatePlan(res, body, url) {
+  const cwd = body?.cwd;
+  if (typeof cwd !== "string" || !cwd.trim()) {
+    return sendJSON(res, { error: "`cwd` is required (absolute project path)." }, 400);
+  }
+  const provided = ["docs", "markdown", "plan"].filter(
+    (k) => body[k] !== undefined && body[k] !== null,
+  );
+  if (provided.length !== 1) {
+    return sendJSON(
+      res,
+      {
+        error: provided.length
+          ? `Provide exactly one content field — got ${provided.join(", ")}. Use only one of docs / markdown / plan.`
+          : "Provide exactly one of `docs`, `markdown`, or `plan`.",
+      },
+      400,
+    );
+  }
+
+  let tree;
+  if (provided[0] === "docs") {
+    if (!Array.isArray(body.docs) || body.docs.length === 0) {
+      return sendJSON(res, { error: "`docs` must be a non-empty array of {slug, title, parent?, body}." }, 400);
+    }
+    const issues = validateDocs(body.docs);
+    if (issues.length) return sendJSON(res, { error: "The plan documents are invalid.", issues }, 400);
+    tree = docsToTree(body.docs);
+  } else {
+    const str = body[provided[0]];
+    if (typeof str !== "string" || !str.trim()) {
+      return sendJSON(res, { error: `\`${provided[0]}\` must be a non-empty string.` }, 400);
+    }
+    let parsed;
+    try {
+      parsed = parsePlan(str);
+    } catch (err) {
+      return sendJSON(res, { error: `Could not parse the plan: ${String(err?.message || err)}` }, 400);
+    }
+    if (parsed.error) return sendJSON(res, { error: "The plan documents are invalid.", issues: parsed.error.issues }, 400);
+    tree = parsed;
+  }
+
+  let recorded;
+  try {
+    recorded = recordPlan({ cwd, tree, origin: "api" });
+  } catch (err) {
+    return sendJSON(res, { error: `Failed to record the plan: ${String(err?.message || err)}` }, 500);
+  }
+  const { key, version, reviewId } = recorded;
+  const rootDoc = (tree && tree.root) || "root";
+  const reviewUrl = `${url.origin}/?project=${encodeURIComponent(
+    key,
+  )}&version=${version}&review=${reviewId}&doc=${encodeURIComponent(rootDoc)}`;
+  return sendJSON(res, { key, version, reviewId, reviewUrl }, 201);
+}
+
 /** POST /api/projects/:key/versions/:n/save — create or overwrite the channel's store. */
 async function handleSave(req, res, key, n) {
   const body = JSON.parse((await readBody(req)) || "{}");

package/src/stop-gate.js

@@ -0,0 +1,73 @@
+/**
+ * Claude Code Stop hook — hard enforcement for tools-first plan reviews.
+ *
+ * The MCP / HTTP submission paths (plan_review_submit, POST /api/plans) are
+ * non-blocking: Claude submits a plan and could end its turn before the user
+ * decides. plan_review_check long-polls and its tool-result text steers Claude to
+ * keep polling, but nothing PREVENTS the turn from ending. This Stop hook closes
+ * that gap: if the turn is about to end while a recent mcp/api-origin review is
+ * still pending, it blocks and tells Claude to resume polling.
+ *
+ * stdin  = { session_id, cwd, stop_hook_active, ... }
+ * stdout = { decision:"block", reason } to block; nothing (exit 0) to allow.
+ *
+ * Invariants (mirror hook.js):
+ *   • stop_hook_active === true  → exit 0 immediately (never double-block).
+ *   • Fail open on ANY error     → exit 0 so a bug never traps the user's turn.
+ *   • Only mcp/api reviews, still pending, created within the last 5 hours are
+ *     gated. Hook-origin (and legacy origin-less) reviews are never gated — the
+ *     PreToolUse hook already blocks synchronously for those.
+ */
+import { readFileSync } from "node:fs";
+import { projectKey } from "./paths.js";
+import { listReviews } from "./store.js";
+
+/** Only reviews this fresh are gated — an abandoned review shouldn't trap forever. */
+const GATE_WINDOW_MS = 5 * 60 * 60 * 1000;
+
+function main() {
+  let input = {};
+  try {
+    input = JSON.parse(readFileSync(0, "utf8")); // fd 0 = stdin (node + bun)
+  } catch {
+    process.exit(0); // unparseable stdin → don't interfere
+  }
+
+  // Never double-block: if we already blocked once this stop cycle, let it end.
+  if (input.stop_hook_active) process.exit(0);
+
+  try {
+    const cwd = input.cwd || process.cwd();
+    const key = projectKey(cwd);
+    const cutoff = Date.now() - GATE_WINDOW_MS;
+    const pending = listReviews()
+      .filter(
+        (r) =>
+          r.projectKey === key &&
+          r.status === "pending" &&
+          (r.origin === "mcp" || r.origin === "api") &&
+          r.createdAt &&
+          Date.parse(r.createdAt) >= cutoff,
+      )
+      // newest first — reference the most recent pending review
+      .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
+
+    if (pending.length) {
+      const r = pending[0];
+      process.stdout.write(
+        JSON.stringify({
+          decision: "block",
+          reason:
+            `A plan review you submitted is still pending (review ${r.id}, version ${r.version}). ` +
+            `Call plan_review_check with {reviewId:"${r.id}", wait:20} in a loop until it resolves, ` +
+            `then act on the decision. If ~5 hours pass with no decision, ask the user.`,
+        }),
+      );
+    }
+  } catch {
+    process.exit(0); // any failure → fail open
+  }
+  process.exit(0);
+}
+
+main();