diffprism 0.38.0 → 0.40.0

package/dist/bin.js

@@ -11,14 +11,14 @@ import {
 } from "./chunk-6J6PSBL2.js";
 import {
   demo
-} from "./chunk-UYZ3A2PB.js";
+} from "./chunk-FCDO5LRP.js";
 import {
   ensureServer,
   isServerAlive,
   readServerFile,
   startGlobalServer,
   submitReviewToServer
-} from "./chunk-ITPHDFOS.js";
+} from "./chunk-2HMWCMPU.js";
 import "./chunk-QGWYCEJN.js";
 import "./chunk-DHCVZGHE.js";
 import "./chunk-JSBRDJBE.js";
@@ -89,7 +89,7 @@ async function reviewPrFlow(pr, flags) {
     diffRef: `PR #${number}`
   });
   console.log(JSON.stringify(result, null, 2));
-  if (flags.postToGithub || result.decision !== "dismissed" && await promptPostToGithub()) {
+  if (result && (flags.postToGithub || result.decision !== "dismissed" && await promptPostToGithub())) {
     console.log("Posting review to GitHub...");
     const posted = await submitGitHubReview(client, owner, repo, number, result);
     if (posted) {
@@ -134,29 +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.
 
-- \`diff_ref\`: \`"working-copy"\` (or what the user specified, e.g. \`"staged"\`, or a GitHub PR ref like \`"owner/repo#123"\`)
-- \`title\`: Brief summary of the changes
-- \`reasoning\`: Your reasoning about the implementation decisions
-- \`post_to_github\`: Set to \`true\` to post the review back to GitHub (only for PR refs)
+## Workflow 1: Self-Review Before Human Review
 
-The tool blocks until the human submits their review. Handle the result:
+After making multi-file changes, **proactively self-review before requesting human review**:
 
+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\`
+
+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
@@ -327,7 +379,7 @@ async function setupInteractive(flags) {
 }
 async function runDemo(dev) {
   console.log("");
-  const { demo: demo2 } = await import("./demo-JH5YOKTZ.js");
+  const { demo: demo2 } = await import("./demo-75VOJNCC.js");
   await demo2({ dev });
 }
 async function setupBatch(flags) {
@@ -756,7 +808,7 @@ 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.38.0" : "0.0.0-dev");
+program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.40.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 (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));

package/dist/{chunk-ITPHDFOS.js → chunk-2HMWCMPU.js}

@@ -230,8 +230,11 @@ async function submitReviewToServer(serverInfo, diffRef, options = {}) {
       );
     }
   }
-  const pollIntervalMs = 2e3;
   const maxWaitMs = options.timeoutMs ?? 6e5;
+  if (maxWaitMs <= 0) {
+    return { result: null, sessionId };
+  }
+  const pollIntervalMs = 2e3;
   const start = Date.now();
   while (Date.now() - start < maxWaitMs) {
     const resultResponse = await fetch(
@@ -493,6 +496,7 @@ function toSummary(session) {
     projectPath: session.projectPath,
     branch: payload.metadata.currentBranch,
     title: payload.metadata.title,
+    reasoning: payload.metadata.reasoning,
     fileCount,
     additions,
     deletions,

package/dist/{chunk-UYZ3A2PB.js → chunk-FCDO5LRP.js}

@@ -1,7 +1,7 @@
 import {
   ensureServer,
   submitReviewToServer
-} from "./chunk-ITPHDFOS.js";
+} from "./chunk-2HMWCMPU.js";
 import {
   parseDiff
 } from "./chunk-QGWYCEJN.js";
@@ -210,10 +210,14 @@ async function demo(flags) {
       projectPath: "demo",
       diffRef: "demo"
     });
-    console.log(`
+    if (result) {
+      console.log(`
 Review submitted: ${result.decision}`);
-    if (result.comments.length > 0) {
-      console.log(`${result.comments.length} comment(s)`);
+      if (result.comments.length > 0) {
+        console.log(`${result.comments.length} comment(s)`);
+      }
+    } else {
+      console.log("\nReview opened in browser.");
     }
     console.log("\nNext steps:");
     console.log("  Run `npx diffprism setup` to configure for Claude Code");

package/dist/{demo-JH5YOKTZ.js → demo-75VOJNCC.js}

@@ -1,7 +1,7 @@
 import {
   demo
-} from "./chunk-UYZ3A2PB.js";
-import "./chunk-ITPHDFOS.js";
+} from "./chunk-FCDO5LRP.js";
+import "./chunk-2HMWCMPU.js";
 import "./chunk-QGWYCEJN.js";
 import "./chunk-DHCVZGHE.js";
 import "./chunk-JSBRDJBE.js";

package/dist/mcp-server.js

@@ -12,7 +12,7 @@ import {
   ensureServer,
   isServerAlive,
   submitReviewToServer
-} from "./chunk-ITPHDFOS.js";
+} from "./chunk-2HMWCMPU.js";
 import {
   getDiff
 } from "./chunk-QGWYCEJN.js";
@@ -38,12 +38,29 @@ async function handleLocalReview(diffRef, options) {
       reasoning: options.reasoning,
       cwd: process.cwd(),
       annotations: options.annotations,
-      diffRef
+      diffRef,
+      timeoutMs: options.timeoutMs ?? 0
     }
   );
+  if (result) {
+    return {
+      mcpResult: {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      },
+      sessionId,
+      serverInfo
+    };
+  }
   return {
     mcpResult: {
-      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      content: [{
+        type: "text",
+        text: JSON.stringify({
+          status: "session_created",
+          sessionId,
+          message: "Review session opened in DiffPrism dashboard. Use get_review_result to check for a decision."
+        }, null, 2)
+      }]
     },
     sessionId,
     serverInfo
@@ -84,9 +101,27 @@ async function handlePrReview(pr, options) {
     {
       injectedPayload: payload,
       projectPath: `github:${owner}/${repo}`,
-      diffRef: `PR #${number}`
+      diffRef: `PR #${number}`,
+      timeoutMs: options.timeoutMs ?? 0
     }
   );
+  if (!result) {
+    return {
+      mcpResult: {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "session_created",
+            sessionId,
+            pr: `${owner}/${repo}#${number}`,
+            message: "Review session opened in DiffPrism dashboard. Use get_review_result to check for a decision."
+          }, null, 2)
+        }]
+      },
+      sessionId,
+      serverInfo
+    };
+  }
   if ((options.post_to_github || result.postToGithub) && result.decision !== "dismissed") {
     const posted = await submitGitHubReview(client, owner, repo, number, result);
     if (posted) {
@@ -117,19 +152,20 @@ async function handlePrReview(pr, options) {
 async function startMcpServer() {
   const server = new McpServer({
     name: "diffprism",
-    version: true ? "0.38.0" : "0.0.0-dev"
+    version: true ? "0.40.0" : "0.0.0-dev"
   });
   server.tool(
     "open_review",
-    "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.",
+    "Open a review session in the DiffPrism dashboard for local git changes or a GitHub pull request. Returns immediately with the session ID after registering the session. Use `get_review_result` with `wait: true` when you need the reviewer's decision before proceeding.",
     {
       diff_ref: z.string().describe(
         '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"),
+      reasoning: z.string().optional().describe("Summarize what you were trying to accomplish in this session in plain English. This is displayed as the session subtitle in the DiffPrism dashboard and is the primary way users identify sessions at a glance. Always populate this."),
       post_to_github: z.boolean().optional().describe("Post the review back to GitHub after submission (only for PR refs, default: false)"),
+      timeout_ms: z.number().optional().describe("How long to wait for a review decision (ms). Defaults to 0 (non-blocking, returns immediately after session creation). Set to a positive value to poll for a result up to that duration before returning."),
       annotations: z.array(
         z.object({
           file: z.string().describe("File path within the diff to annotate"),
@@ -151,7 +187,7 @@ async function startMcpServer() {
         })
       ).optional().describe("Initial annotations to attach to the review")
     },
-    async ({ diff_ref, title, description, reasoning, post_to_github, annotations }) => {
+    async ({ diff_ref, title, description, reasoning, post_to_github, timeout_ms, annotations }) => {
       try {
         let mcpResult;
         let sessionId;
@@ -160,14 +196,16 @@ async function startMcpServer() {
           ({ mcpResult, sessionId, serverInfo } = await handlePrReview(diff_ref, {
             title,
             reasoning,
-            post_to_github
+            post_to_github,
+            timeoutMs: timeout_ms
           }));
         } else {
           ({ mcpResult, sessionId, serverInfo } = await handleLocalReview(diff_ref, {
             title,
             description,
             reasoning,
-            annotations
+            annotations,
+            timeoutMs: timeout_ms
           }));
         }
         if (sessionId) {
@@ -249,7 +287,7 @@ async function startMcpServer() {
   );
   server.tool(
     "get_review_result",
-    "Fetch the most recent review result from a DiffPrism session. Returns the reviewer's decision and comments if a review has been submitted, or a message indicating no pending result. Use wait=true to block until a result is available. Note: `open_review` already blocks and returns the result \u2014 this tool is only needed for advanced workflows where you want to check results separately.",
+    "Fetch the most recent review result from a DiffPrism session. Returns the reviewer's decision and comments if a review has been submitted, or a message indicating no pending result. Use wait=true to block until a result is available \u2014 this is the standard way to wait for a reviewer's decision after calling open_review.",
     {
       wait: z.boolean().optional().describe("If true, poll until a review result is available (blocks up to timeout)"),
       timeout: z.number().optional().describe("Max wait time in seconds when wait=true (default: 300, max: 600)")
@@ -705,43 +743,6 @@ async function startMcpServer() {
       }
     }
   );
-  server.tool(
-    "review_pr",
-    "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"'
-      ),
-      title: z.string().optional().describe("Override review title"),
-      reasoning: z.string().optional().describe("Agent reasoning about the PR changes"),
-      post_to_github: z.boolean().optional().describe("Post the review back to GitHub after submission (default: false)")
-    },
-    async ({ pr, title, reasoning, post_to_github }) => {
-      try {
-        const { mcpResult, sessionId, serverInfo } = await handlePrReview(pr, {
-          title,
-          reasoning,
-          post_to_github
-        });
-        if (sessionId) {
-          lastGlobalSessionId = sessionId;
-          lastGlobalServerInfo = serverInfo;
-        }
-        return mcpResult;
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Error: ${message}`
-            }
-          ],
-          isError: true
-        };
-      }
-    }
-  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

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