diffprism 0.37.3 → 0.39.0

package/dist/bin.js

@@ -3,11 +3,12 @@ import {
   createGitHubClient,
   fetchPullRequest,
   fetchPullRequestDiff,
+  isPrRef,
   normalizePr,
   parsePrRef,
   resolveGitHubToken,
   submitGitHubReview
-} from "./chunk-OR6PCPZX.js";
+} from "./chunk-6J6PSBL2.js";
 import {
   demo
 } from "./chunk-UYZ3A2PB.js";
@@ -26,6 +27,7 @@ import "./chunk-JSBRDJBE.js";
 import { Command } from "commander";
 
 // cli/src/commands/review.ts
+import readline from "readline";
 async function review(ref, flags) {
   let diffRef;
   if (flags.staged) {
@@ -38,65 +40,63 @@ async function review(ref, flags) {
     diffRef = "working-copy";
   }
   try {
-    const serverInfo = await ensureServer({ dev: flags.dev });
-    console.log("Opening review in browser...");
-    const { result } = await submitReviewToServer(serverInfo, diffRef, {
-      title: flags.title,
-      cwd: process.cwd(),
-      diffRef
-    });
-    console.log(JSON.stringify(result, null, 2));
-    process.exit(0);
+    if (isPrRef(diffRef)) {
+      await reviewPrFlow(diffRef, flags);
+    } else {
+      await reviewLocalFlow(diffRef, flags);
+    }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.error(`Error: ${message}`);
     process.exit(1);
   }
 }
-
-// cli/src/commands/review-pr.ts
-import readline from "readline";
-async function reviewPr(pr, flags) {
-  try {
-    const token = resolveGitHubToken();
-    const { owner, repo, number } = parsePrRef(pr);
-    console.log(`Fetching PR #${number} from ${owner}/${repo}...`);
-    const client = createGitHubClient(token);
-    const [prMetadata, rawDiff] = await Promise.all([
-      fetchPullRequest(client, owner, repo, number),
-      fetchPullRequestDiff(client, owner, repo, number)
-    ]);
-    if (!rawDiff.trim()) {
-      console.log("PR has no changes to review.");
-      return;
-    }
-    const { payload, diffSet } = normalizePr(rawDiff, prMetadata, {
-      title: flags.title,
-      reasoning: flags.reasoning
-    });
-    console.log(
-      `${diffSet.files.length} files, +${diffSet.files.reduce((s, f) => s + f.additions, 0)} -${diffSet.files.reduce((s, f) => s + f.deletions, 0)}`
-    );
-    const serverInfo = await ensureServer({ dev: flags.dev });
-    const { result } = await submitReviewToServer(serverInfo, `PR #${number}`, {
-      injectedPayload: payload,
-      projectPath: `github:${owner}/${repo}`,
-      diffRef: `PR #${number}`
-    });
-    console.log(JSON.stringify(result, null, 2));
-    if (flags.postToGithub || result.decision !== "dismissed" && await promptPostToGithub()) {
-      console.log("Posting review to GitHub...");
-      const posted = await submitGitHubReview(client, owner, repo, number, result);
-      if (posted) {
-        console.log(`Review posted: ${prMetadata.url}#pullrequestreview-${posted.reviewId}`);
-      }
+async function reviewLocalFlow(diffRef, flags) {
+  const serverInfo = await ensureServer({ dev: flags.dev });
+  console.log("Opening review in browser...");
+  const { result } = await submitReviewToServer(serverInfo, diffRef, {
+    title: flags.title,
+    cwd: process.cwd(),
+    diffRef
+  });
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}
+async function reviewPrFlow(pr, flags) {
+  const token = resolveGitHubToken();
+  const { owner, repo, number } = parsePrRef(pr);
+  console.log(`Fetching PR #${number} from ${owner}/${repo}...`);
+  const client = createGitHubClient(token);
+  const [prMetadata, rawDiff] = await Promise.all([
+    fetchPullRequest(client, owner, repo, number),
+    fetchPullRequestDiff(client, owner, repo, number)
+  ]);
+  if (!rawDiff.trim()) {
+    console.log("PR has no changes to review.");
+    return;
+  }
+  const { payload, diffSet } = normalizePr(rawDiff, prMetadata, {
+    title: flags.title,
+    reasoning: flags.reasoning
+  });
+  console.log(
+    `${diffSet.files.length} files, +${diffSet.files.reduce((s, f) => s + f.additions, 0)} -${diffSet.files.reduce((s, f) => s + f.deletions, 0)}`
+  );
+  const serverInfo = await ensureServer({ dev: flags.dev });
+  const { result } = await submitReviewToServer(serverInfo, `PR #${number}`, {
+    injectedPayload: payload,
+    projectPath: `github:${owner}/${repo}`,
+    diffRef: `PR #${number}`
+  });
+  console.log(JSON.stringify(result, null, 2));
+  if (flags.postToGithub || result.decision !== "dismissed" && await promptPostToGithub()) {
+    console.log("Posting review to GitHub...");
+    const posted = await submitGitHubReview(client, owner, repo, number, result);
+    if (posted) {
+      console.log(`Review posted: ${prMetadata.url}#pullrequestreview-${posted.reviewId}`);
     }
-    process.exit(0);
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.error(`Error: ${message}`);
-    process.exit(1);
   }
+  process.exit(0);
 }
 async function promptPostToGithub() {
   if (!process.stdin.isTTY) {
@@ -134,28 +134,81 @@ description: Open current code changes in DiffPrism's browser-based review UI fo
 
 # DiffPrism Review
 
-When the user invokes \`/review\`, call \`mcp__diffprism__open_review\` with:
+You have 9 DiffPrism MCP tools available. Use them proactively \u2014 don't wait for the user to ask.
+
+## Workflow 1: Self-Review Before Human Review
+
+After making multi-file changes, **proactively self-review before requesting human review**:
 
-- \`diff_ref\`: \`"working-copy"\` (or what the user specified, e.g. \`"staged"\`)
-- \`title\`: Brief summary of the changes
-- \`reasoning\`: Your reasoning about the implementation decisions
+1. Run \`mcp__diffprism__analyze_diff\` with \`diff_ref: "working-copy"\`
+2. Check the response for:
+   - **Pattern flags** \u2014 console.logs left in, TODO comments, security issues (hardcoded secrets, SQL injection, XSS)
+   - **Test coverage gaps** \u2014 new code paths without corresponding tests
+   - **High complexity scores** \u2014 functions or files with elevated complexity
+3. **Fix any issues found** \u2014 remove debug logs, add missing tests, simplify complex code
+4. Only then open a human review with \`mcp__diffprism__open_review\`
 
-The tool blocks until the human submits their review. Handle the result:
+This should happen automatically after significant changes. You don't need the user to ask.
 
+## Workflow 2: Annotated Human Review
+
+When opening a review, help the reviewer by flagging what matters:
+
+1. Call \`mcp__diffprism__open_review\` with:
+   - \`diff_ref\`: \`"working-copy"\` (or what the user specified, e.g. \`"staged"\`, \`"HEAD~3..HEAD"\`)
+   - \`title\`: Brief summary of the changes
+   - \`reasoning\`: Your reasoning about implementation decisions
+   - \`annotations\`: Array of inline findings to pre-populate the review (see tool schema)
+2. Use annotations to flag:
+   - Areas of uncertainty ("I chose approach X over Y because...")
+   - Security-sensitive changes
+   - Performance implications
+   - Anything the reviewer should look at closely
+3. After opening, use \`mcp__diffprism__flag_for_attention\` to highlight files that need careful review (e.g. auth logic, data migrations, public API changes)
+4. Use \`mcp__diffprism__add_annotation\` to post additional findings about specific lines if you discover issues while the review is open
+
+Handle the review result:
 - **\`approved\`** \u2014 Proceed with the task.
 - **\`changes_requested\`** \u2014 Read comments, make fixes, offer to re-review.
 - If \`postReviewAction\` is \`"commit"\` \u2014 commit the changes.
 - If \`postReviewAction\` is \`"commit_and_pr"\` \u2014 commit and open a PR.
 
-## Headless Tools
+## Workflow 3: PR Review
+
+To review a GitHub pull request:
+
+1. Call \`mcp__diffprism__review_pr\` with \`pr: "owner/repo#123"\` or a full GitHub PR URL
+2. Set \`post_to_github: true\` to post the review back to GitHub after the human submits
+3. The tool fetches the PR diff, runs analysis, and opens the review UI
+
+## Tool Reference
+
+### Review Lifecycle
+| Tool | Purpose |
+|------|---------|
+| \`open_review\` | Open browser review UI for local changes. Blocks until submitted. |
+| \`review_pr\` | Open browser review UI for a GitHub PR. Blocks until submitted. |
+| \`get_review_result\` | Fetch result from a previous review (advanced \u2014 \`open_review\` already returns it). |
+| \`update_review_context\` | Push updated reasoning/description to a running review session. |
+
+### Headless Analysis
+| Tool | Purpose |
+|------|---------|
+| \`analyze_diff\` | Returns analysis JSON (patterns, complexity, test gaps) without opening a browser. |
+| \`get_diff\` | Returns structured diff JSON (file-level and hunk-level changes). |
 
-- \`mcp__diffprism__analyze_diff\` \u2014 Returns analysis JSON (patterns, complexity, test gaps) without opening a browser. Use proactively to self-check before requesting review.
-- \`mcp__diffprism__get_diff\` \u2014 Returns structured diff JSON.
+### Annotation & Flagging
+| Tool | Purpose |
+|------|---------|
+| \`add_annotation\` | Post a finding/suggestion/question on a specific line in a running review. |
+| \`flag_for_attention\` | Mark files for human attention with warning annotations. |
+| \`get_review_state\` | Get current state of a review session including all annotations. |
 
 ## Rules
 
-- Only open a review when the user explicitly asks (\`/review\` or "review my changes").
-- Headless tools can be used proactively without user request.
+- **Self-review is proactive** \u2014 run \`analyze_diff\` after significant changes without being asked.
+- **Human review requires explicit request** \u2014 only open \`open_review\` when the user asks (\`/review\`, "review my changes", or as part of a defined workflow like PR creation).
+- **Annotate generously** \u2014 the more context you provide in annotations, the faster the reviewer can make decisions.
 `;
 
 // cli/src/commands/setup.ts
@@ -755,10 +808,10 @@ async function serverStop() {
 
 // cli/src/index.ts
 var program = new Command();
-program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.37.3" : "0.0.0-dev");
+program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.39.0" : "0.0.0-dev");
 program.command("demo").description("Open a sample review to see DiffPrism in action").option("--dev", "Use Vite dev server").action(demo);
-program.command("review [ref]").description("Open a browser-based diff review").option("--staged", "Review staged changes").option("--unstaged", "Review unstaged changes").option("-t, --title <title>", "Review title").option("--dev", "Use Vite dev server with HMR instead of static files").action(review);
-program.command("review-pr <pr>").description("Review a GitHub pull request in DiffPrism").option("-t, --title <title>", "Override review title").option("--reasoning <text>", "Agent reasoning about the PR").option("--dev", "Use Vite dev server with HMR instead of static files").option("--post-to-github", "Automatically post review back to GitHub without prompting").action(reviewPr);
+program.command("review [ref]").description("Open a browser-based diff review (local git ref or GitHub PR ref like owner/repo#123)").option("--staged", "Review staged changes").option("--unstaged", "Review unstaged changes").option("-t, --title <title>", "Review title").option("--reasoning <text>", "Agent reasoning about the changes").option("--dev", "Use Vite dev server with HMR instead of static files").option("--post-to-github", "Automatically post review back to GitHub without prompting").action(review);
+program.command("review-pr <pr>", { hidden: true }).action((pr, flags) => review(pr, flags));
 program.command("serve").description("Start the MCP server for Claude Code integration").action(serve);
 program.command("setup").description("Configure DiffPrism for Claude Code integration").option("--global", "Configure globally (skill + permissions, no git repo required)").option("--force", "Overwrite existing configuration files").option("--dev", "Use Vite dev server").option("--no-demo", "Skip the demo review after setup").action((flags) => {
   setup(flags);

package/dist/{chunk-OR6PCPZX.js → chunk-6J6PSBL2.js}

@@ -3719,6 +3719,11 @@ async function fetchPullRequestDiff(client, owner, repo, number) {
   });
   return data;
 }
+function isPrRef(input) {
+  if (/github\.com\/[^/]+\/[^/]+\/pull\/\d+/.test(input)) return true;
+  if (/^[^/]+\/[^#]+#\d+$/.test(input)) return true;
+  return false;
+}
 function parsePrRef(input) {
   const urlMatch = input.match(
     /github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/
@@ -3842,6 +3847,7 @@ export {
   createGitHubClient,
   fetchPullRequest,
   fetchPullRequestDiff,
+  isPrRef,
   parsePrRef,
   normalizePr,
   submitGitHubReview

package/dist/mcp-server.js

@@ -2,11 +2,12 @@ import {
   createGitHubClient,
   fetchPullRequest,
   fetchPullRequestDiff,
+  isPrRef,
   normalizePr,
   parsePrRef,
   resolveGitHubToken,
   submitGitHubReview
-} from "./chunk-OR6PCPZX.js";
+} from "./chunk-6J6PSBL2.js";
 import {
   ensureServer,
   isServerAlive,
@@ -26,21 +27,109 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 var lastGlobalSessionId = null;
 var lastGlobalServerInfo = null;
+async function handleLocalReview(diffRef, options) {
+  const serverInfo = await ensureServer({ silent: true });
+  const { result, sessionId } = await submitReviewToServer(
+    serverInfo,
+    diffRef,
+    {
+      title: options.title,
+      description: options.description,
+      reasoning: options.reasoning,
+      cwd: process.cwd(),
+      annotations: options.annotations,
+      diffRef
+    }
+  );
+  return {
+    mcpResult: {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    },
+    sessionId,
+    serverInfo
+  };
+}
+async function handlePrReview(pr, options) {
+  const token = resolveGitHubToken();
+  const { owner, repo, number } = parsePrRef(pr);
+  const client = createGitHubClient(token);
+  const [prMetadata, rawDiff] = await Promise.all([
+    fetchPullRequest(client, owner, repo, number),
+    fetchPullRequestDiff(client, owner, repo, number)
+  ]);
+  if (!rawDiff.trim()) {
+    return {
+      mcpResult: {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            decision: "approved",
+            comments: [],
+            summary: "PR has no changes to review."
+          }, null, 2)
+        }]
+      },
+      sessionId: "",
+      serverInfo: { httpPort: 0, wsPort: 0, pid: 0, startedAt: 0 }
+    };
+  }
+  const { payload } = normalizePr(rawDiff, prMetadata, {
+    title: options.title,
+    reasoning: options.reasoning
+  });
+  const serverInfo = await ensureServer({ silent: true });
+  const { result, sessionId } = await submitReviewToServer(
+    serverInfo,
+    `PR #${number}`,
+    {
+      injectedPayload: payload,
+      projectPath: `github:${owner}/${repo}`,
+      diffRef: `PR #${number}`
+    }
+  );
+  if ((options.post_to_github || result.postToGithub) && result.decision !== "dismissed") {
+    const posted = await submitGitHubReview(client, owner, repo, number, result);
+    if (posted) {
+      return {
+        mcpResult: {
+          content: [{
+            type: "text",
+            text: JSON.stringify({
+              ...result,
+              githubReviewId: posted.reviewId,
+              githubReviewUrl: `${prMetadata.url}#pullrequestreview-${posted.reviewId}`
+            }, null, 2)
+          }]
+        },
+        sessionId,
+        serverInfo
+      };
+    }
+  }
+  return {
+    mcpResult: {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    },
+    sessionId,
+    serverInfo
+  };
+}
 async function startMcpServer() {
   const server = new McpServer({
     name: "diffprism",
-    version: true ? "0.37.3" : "0.0.0-dev"
+    version: true ? "0.39.0" : "0.0.0-dev"
   });
   server.tool(
     "open_review",
-    "Open a browser-based code review for local git changes. Blocks until the engineer submits their review decision. The result may include a `postReviewAction` field ('commit' or 'commit_and_pr') if the reviewer requested a post-review action.",
+    "Open a browser-based code review for local git changes or a GitHub pull request. Blocks until the engineer submits their review decision. The result may include a `postReviewAction` field ('commit' or 'commit_and_pr') if the reviewer requested a post-review action.",
     {
       diff_ref: z.string().describe(
-        'Git diff reference: "staged", "unstaged", "working-copy" (staged+unstaged grouped), or a ref range like "HEAD~3..HEAD"'
+        'Git diff reference: "staged", "unstaged", "working-copy" (staged+unstaged grouped), a ref range like "HEAD~3..HEAD", or a GitHub PR ref like "owner/repo#123" or a GitHub PR URL'
       ),
       title: z.string().optional().describe("Title for the review"),
       description: z.string().optional().describe("Description of the changes"),
       reasoning: z.string().optional().describe("Agent reasoning about why these changes were made"),
+      post_to_github: z.boolean().optional().describe("Post the review back to GitHub after submission (only for PR refs, default: false)"),
       annotations: z.array(
         z.object({
           file: z.string().describe("File path within the diff to annotate"),
@@ -62,31 +151,30 @@ async function startMcpServer() {
         })
       ).optional().describe("Initial annotations to attach to the review")
     },
-    async ({ diff_ref, title, description, reasoning, annotations }) => {
+    async ({ diff_ref, title, description, reasoning, post_to_github, annotations }) => {
       try {
-        const serverInfo = await ensureServer({ silent: true });
-        const { result, sessionId } = await submitReviewToServer(
-          serverInfo,
-          diff_ref,
-          {
+        let mcpResult;
+        let sessionId;
+        let serverInfo;
+        if (isPrRef(diff_ref)) {
+          ({ mcpResult, sessionId, serverInfo } = await handlePrReview(diff_ref, {
+            title,
+            reasoning,
+            post_to_github
+          }));
+        } else {
+          ({ mcpResult, sessionId, serverInfo } = await handleLocalReview(diff_ref, {
             title,
             description,
             reasoning,
-            cwd: process.cwd(),
-            annotations,
-            diffRef: diff_ref
-          }
-        );
-        lastGlobalSessionId = sessionId;
-        lastGlobalServerInfo = serverInfo;
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ]
-        };
+            annotations
+          }));
+        }
+        if (sessionId) {
+          lastGlobalSessionId = sessionId;
+          lastGlobalServerInfo = serverInfo;
+        }
+        return mcpResult;
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return {
@@ -619,7 +707,7 @@ async function startMcpServer() {
   );
   server.tool(
     "review_pr",
-    "Open a browser-based code review for a GitHub pull request. Fetches the PR diff, runs DiffPrism analysis, and opens the review UI. Blocks until the engineer submits their review decision. Optionally posts the review back to GitHub. The result may include a `postReviewAction` field ('commit' or 'commit_and_pr') if the reviewer requested a post-review action.",
+    "Alias for open_review with a GitHub PR ref. Prefer using open_review with a PR ref in diff_ref instead.",
     {
       pr: z.string().describe(
         'GitHub PR reference: "owner/repo#123" or "https://github.com/owner/repo/pull/123"'
@@ -630,65 +718,16 @@ async function startMcpServer() {
     },
     async ({ pr, title, reasoning, post_to_github }) => {
       try {
-        const token = resolveGitHubToken();
-        const { owner, repo, number } = parsePrRef(pr);
-        const client = createGitHubClient(token);
-        const [prMetadata, rawDiff] = await Promise.all([
-          fetchPullRequest(client, owner, repo, number),
-          fetchPullRequestDiff(client, owner, repo, number)
-        ]);
-        if (!rawDiff.trim()) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({
-                  decision: "approved",
-                  comments: [],
-                  summary: "PR has no changes to review."
-                }, null, 2)
-              }
-            ]
-          };
-        }
-        const { payload } = normalizePr(rawDiff, prMetadata, { title, reasoning });
-        const serverInfo = await ensureServer({ silent: true });
-        const { result, sessionId } = await submitReviewToServer(
-          serverInfo,
-          `PR #${number}`,
-          {
-            injectedPayload: payload,
-            projectPath: `github:${owner}/${repo}`,
-            diffRef: `PR #${number}`
-          }
-        );
-        lastGlobalSessionId = sessionId;
-        lastGlobalServerInfo = serverInfo;
-        if ((post_to_github || result.postToGithub) && result.decision !== "dismissed") {
-          const posted = await submitGitHubReview(client, owner, repo, number, result);
-          if (posted) {
-            return {
-              content: [
-                {
-                  type: "text",
-                  text: JSON.stringify({
-                    ...result,
-                    githubReviewId: posted.reviewId,
-                    githubReviewUrl: `${prMetadata.url}#pullrequestreview-${posted.reviewId}`
-                  }, null, 2)
-                }
-              ]
-            };
-          }
+        const { mcpResult, sessionId, serverInfo } = await handlePrReview(pr, {
+          title,
+          reasoning,
+          post_to_github
+        });
+        if (sessionId) {
+          lastGlobalSessionId = sessionId;
+          lastGlobalServerInfo = serverInfo;
         }
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify(result, null, 2)
-            }
-          ]
-        };
+        return mcpResult;
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffprism",
-  "version": "0.37.3",
+  "version": "0.39.0",
   "type": "module",
   "description": "Local-first code review tool for agent-generated code changes",
   "bin": {