diffprism 0.20.2 → 0.21.0

package/README.md

@@ -12,11 +12,12 @@ DiffPrism gives you a visual review step for AI-written code — stage your chan
 - **Review briefing bar** — summary stats, complexity scoring, test coverage gaps, pattern flags, and dependency tracking
 - **Agent reasoning panel** — see why the AI made each change
 - **Dark/light mode** — toggle with theme persistence
-- **Keyboard shortcuts** — `j`/`k` navigate files, `s` cycles file status
+- **Keyboard shortcuts** — `j`/`k` navigate files, `s` cycles file status, `Cmd/Ctrl+Enter` saves comments, `?` toggles hotkey guide
 - **Three-way decisions** — approve, request changes, or approve with comments
 - **Branch display** — current git branch shown in the review header
 - **Global server mode** — `diffprism server` runs a persistent multi-session review server, multiple agents post reviews to one browser tab
-- **Multi-session UI** — session list with status badges, branch info, file counts, and change stats when running in server mode
+- **Multi-session UI** — session list with live status badges, branch info, file counts, and change stats; stale sessions auto-expire
+- **One-command setup & teardown** — `diffprism setup` configures Claude Code integration, `diffprism teardown` cleanly reverses it
 
 ## Quick Start
 
@@ -37,6 +38,14 @@ This single command configures everything:
 
 After running, restart Claude Code. The first time you use `/review`, Claude will ask your preferences and save them to `diffprism.config.json`.
 
+To remove DiffPrism from a project:
+
+```bash
+npx diffprism teardown
+```
+
+This reverses all changes made by `setup`: removes DiffPrism entries from `.mcp.json`, permissions, hooks, the skill file, `.gitignore`, and the `.diffprism/` directory. Non-DiffPrism entries are preserved.
+
 See the [full setup guide](docs/claude-setup.md) for manual configuration, Claude Desktop config, troubleshooting, and advanced options.
 
 ### Use from the CLI
@@ -64,6 +73,18 @@ diffprism review --staged --title "Add auth middleware"
 
 A browser window opens with the diff viewer. Review the changes and click **Approve**, **Request Changes**, or **Approve with Comments**.
 
+### Quick Start (setup + watch in one command)
+
+```bash
+# Configure Claude Code integration and start watching in one step
+diffprism start
+
+# With flags
+diffprism start --staged --title "Working on auth"
+```
+
+This runs `diffprism setup` (silently, if already configured) then starts watch mode. Ideal for first-time use or when switching projects.
+
 ### Watch Mode (live-updating)
 
 Keep a persistent browser tab that auto-refreshes as files change — ideal for reviewing while an agent is working:
@@ -102,13 +123,16 @@ diffprism server status
 diffprism server stop
 ```
 
-When the global server is running, MCP tools automatically detect it and route reviews there instead of opening ephemeral browser tabs. Each review appears as a session in the multi-session UI — click to switch between them.
+When the global server is running, MCP tools automatically detect it and route reviews there instead of opening ephemeral browser tabs. Each review appears as a session in the multi-session UI — click to switch between them. Session status badges update live, and submitted sessions auto-expire after 5 minutes.
 
 **Global setup** (optional, `diffprism server` runs this automatically):
 
 ```bash
 # Configure skill + permissions globally (no git repo required)
 diffprism setup --global
+
+# Remove global configuration
+diffprism teardown --global
 ```
 
 Per-project MCP registration (`.mcp.json`) is still needed via `diffprism setup` in each project.
@@ -123,14 +147,14 @@ Opens a browser-based code review. Blocks until the engineer submits their decis
 
 | Parameter     | Required | Description                                                       |
 |---------------|----------|-------------------------------------------------------------------|
-| `diff_ref`    | Yes      | `"staged"`, `"unstaged"`, or a git ref range (e.g. `"HEAD~3..HEAD"`, `"main..feature"`) |
+| `diff_ref`    | Yes      | `"staged"`, `"unstaged"`, `"working-copy"` (staged+unstaged grouped), or a git ref range (e.g. `"HEAD~3..HEAD"`, `"main..feature"`) |
 | `title`       | No       | Title displayed in the review UI                                  |
 | `description` | No       | Description of the changes                                        |
 | `reasoning`   | No       | Agent reasoning about why the changes were made (shown in the reasoning panel) |
 
 ### `update_review_context`
 
-Pushes reasoning/context to a running `diffprism watch` session. Non-blocking — returns immediately.
+Pushes reasoning/context to a running DiffPrism session (watch mode or global server). Non-blocking — returns immediately.
 
 | Parameter     | Required | Description                                    |
 |---------------|----------|------------------------------------------------|
@@ -140,9 +164,12 @@ Pushes reasoning/context to a running `diffprism watch` session. Non-blocking
 
 ### `get_review_result`
 
-Fetches the most recent review result from a `diffprism watch` session. Non-blocking — returns immediately. The result is marked as consumed after retrieval so it won't be returned again.
+Fetches the most recent review result from a DiffPrism session (watch mode or global server). The result is marked as consumed after retrieval so it won't be returned again.
 
-No parameters.
+| Parameter | Required | Description                                                       |
+|-----------|----------|-------------------------------------------------------------------|
+| `wait`    | No       | If `true`, poll until a result is available (blocks up to timeout) |
+| `timeout` | No       | Max wait time in seconds when `wait=true` (default: 300, max: 600) |
 
 **Returns (all tools):** A `ReviewResult` JSON object:
 
@@ -195,7 +222,7 @@ packages/git        — Git diff extraction + unified diff parser
 packages/analysis   — Deterministic review briefing (complexity, test gaps, patterns)
 packages/ui         — React 19 + Vite 6 + Tailwind + Zustand diff viewer + session list
 packages/mcp-server — MCP tool server, auto-routes to global server when available
-cli/                — Commander CLI (review, serve, setup, server commands)
+cli/                — Commander CLI (review, start, watch, setup, teardown, server commands)
 ```
 
 ### Requirements
@@ -207,4 +234,5 @@ cli/                — Commander CLI (review, serve, setup, server commands)
 ## Documentation
 
 - [Claude Code / Claude Desktop Setup Guide](docs/claude-setup.md) — detailed MCP configuration, auto-approval, and troubleshooting
+- [Workflows Guide](docs/workflows.md) — ephemeral, watch, and global server modes explained
 - [UX Design Notes](docs/ux-design-notes.md) — design decisions, CLI defaults rationale, and multi-agent workflow thinking

package/dist/bin.js

@@ -6,7 +6,7 @@ import {
   startGlobalServer,
   startReview,
   startWatch
-} from "./chunk-3CQCLFF3.js";
+} from "./chunk-3IVV6O45.js";
 
 // cli/src/index.ts
 import { Command } from "commander";
@@ -832,7 +832,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.20.2" : "0.0.0-dev");
+program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.21.0" : "0.0.0-dev");
 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("start [ref]").description("Set up DiffPrism and start watching for changes").option("--staged", "Watch staged changes").option("--unstaged", "Watch unstaged changes").option("-t, --title <title>", "Review title").option("--interval <ms>", "Poll interval in milliseconds (default: 1000)").option("--dev", "Use Vite dev server with HMR instead of static files").option("--global", "Install skill globally (~/.claude/skills/)").option("--force", "Overwrite existing configuration files").action(start);
 program.command("watch [ref]").description("Start a persistent diff watcher with live-updating browser UI").option("--staged", "Watch staged changes").option("--unstaged", "Watch unstaged changes").option("-t, --title <title>", "Review title").option("--interval <ms>", "Poll interval in milliseconds (default: 1000)").option("--dev", "Use Vite dev server with HMR instead of static files").action(watch);

package/dist/{chunk-3CQCLFF3.js → chunk-3IVV6O45.js}

@@ -1447,6 +1447,9 @@ import { randomUUID } from "crypto";
 import getPort3 from "get-port";
 import open3 from "open";
 import { WebSocketServer as WebSocketServer3, WebSocket as WebSocket3 } from "ws";
+var SUBMITTED_TTL_MS = 5 * 60 * 1e3;
+var ABANDONED_TTL_MS = 60 * 60 * 1e3;
+var CLEANUP_INTERVAL_MS = 60 * 1e3;
 var sessions2 = /* @__PURE__ */ new Map();
 var clientSessions = /* @__PURE__ */ new Map();
 var sessionWatchers = /* @__PURE__ */ new Map();
@@ -1523,6 +1526,23 @@ function sendToSessionClients(sessionId, msg) {
     }
   }
 }
+function broadcastSessionUpdate(session) {
+  broadcastToAll({
+    type: "session:updated",
+    payload: toSummary(session)
+  });
+}
+function broadcastSessionRemoved(sessionId) {
+  for (const [client, sid] of clientSessions.entries()) {
+    if (sid === sessionId) {
+      clientSessions.delete(client);
+    }
+  }
+  broadcastToAll({
+    type: "session:removed",
+    payload: { sessionId }
+  });
+}
 function hasViewersForSession(sessionId) {
   for (const [client, sid] of clientSessions.entries()) {
     if (sid === sessionId && client.readyState === WebSocket3.OPEN) {
@@ -1614,7 +1634,7 @@ async function handleApiRequest(req, res) {
   const method = req.method ?? "GET";
   const url = (req.url ?? "/").split("?")[0];
   res.setHeader("Access-Control-Allow-Origin", "*");
-  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
   res.setHeader("Access-Control-Allow-Headers", "Content-Type");
   if (method === "OPTIONS") {
     res.writeHead(204);
@@ -1696,7 +1716,7 @@ async function handleApiRequest(req, res) {
       const result = JSON.parse(body);
       session.result = result;
       session.status = "submitted";
-      broadcastToAll({ type: "session:updated", payload: toSummary(session) });
+      broadcastSessionUpdate(session);
       jsonResponse(res, 200, { ok: true });
     } catch {
       jsonResponse(res, 400, { error: "Invalid request body" });
@@ -1750,6 +1770,7 @@ async function handleApiRequest(req, res) {
   if (deleteParams) {
     stopSessionWatcher(deleteParams.id);
     if (sessions2.delete(deleteParams.id)) {
+      broadcastSessionRemoved(deleteParams.id);
       jsonResponse(res, 200, { ok: true });
     } else {
       jsonResponse(res, 404, { error: "Session not found" });
@@ -1802,7 +1823,7 @@ async function startGlobalServer(options = {}) {
       if (session) {
         session.status = "in_review";
         session.hasNewChanges = false;
-        broadcastToAll({ type: "session:updated", payload: toSummary(session) });
+        broadcastSessionUpdate(session);
         const msg = {
           type: "review:init",
           payload: session.payload
@@ -1822,7 +1843,7 @@ async function startGlobalServer(options = {}) {
           clientSessions.set(ws, session.id);
           session.status = "in_review";
           session.hasNewChanges = false;
-          broadcastToAll({ type: "session:updated", payload: toSummary(session) });
+          broadcastSessionUpdate(session);
           ws.send(JSON.stringify({
             type: "review:init",
             payload: session.payload
@@ -1840,7 +1861,7 @@ async function startGlobalServer(options = {}) {
             if (session) {
               session.result = msg.payload;
               session.status = "submitted";
-              broadcastToAll({ type: "session:updated", payload: toSummary(session) });
+              broadcastSessionUpdate(session);
             }
           }
         } else if (msg.type === "session:select") {
@@ -1850,7 +1871,7 @@ async function startGlobalServer(options = {}) {
             session.status = "in_review";
             session.hasNewChanges = false;
             startSessionWatcher(session.id);
-            broadcastToAll({ type: "session:updated", payload: toSummary(session) });
+            broadcastSessionUpdate(session);
             ws.send(JSON.stringify({
               type: "review:init",
               payload: session.payload
@@ -1881,6 +1902,19 @@ async function startGlobalServer(options = {}) {
     httpServer.on("error", reject);
     httpServer.listen(httpPort, () => resolve());
   });
+  function cleanupExpiredSessions() {
+    const now = Date.now();
+    for (const [id, session] of sessions2.entries()) {
+      const age = now - session.createdAt;
+      const expired = session.status === "submitted" && age > SUBMITTED_TTL_MS || session.status === "pending" && age > ABANDONED_TTL_MS;
+      if (expired) {
+        stopSessionWatcher(id);
+        sessions2.delete(id);
+        broadcastSessionRemoved(id);
+      }
+    }
+  }
+  const cleanupTimer = setInterval(cleanupExpiredSessions, CLEANUP_INTERVAL_MS);
   const serverInfo = {
     httpPort,
     wsPort,
@@ -1907,6 +1941,7 @@ Waiting for reviews...
     }
   };
   async function stop() {
+    clearInterval(cleanupTimer);
     stopAllWatchers();
     if (wss) {
       for (const client of wss.clients) {

package/dist/mcp-server.js

@@ -7,7 +7,7 @@ import {
   readReviewResult,
   readWatchFile,
   startReview
-} from "./chunk-3CQCLFF3.js";
+} from "./chunk-3IVV6O45.js";
 
 // packages/mcp-server/src/index.ts
 import fs from "fs";
@@ -76,7 +76,7 @@ async function reviewViaGlobalServer(serverInfo, diffRef, options) {
 async function startMcpServer() {
   const server = new McpServer({
     name: "diffprism",
-    version: true ? "0.20.2" : "0.0.0-dev"
+    version: true ? "0.21.0" : "0.0.0-dev"
   });
   server.tool(
     "open_review",

package/package.json

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