diffprism 0.10.1 → 0.11.0

package/README.md

@@ -2,97 +2,102 @@
 
 Local-first code review tool for agent-generated code changes. Opens a browser-based diff viewer from the CLI or Claude Code (via MCP).
 
-DiffPrism gives you a visual review step for AI-written code — stage your changes, run the tool, and a browser window opens with a syntax-highlighted diff viewer. Approve or request changes, and the result is returned as structured JSON.
+DiffPrism gives you a visual review step for AI-written code — stage your changes, run the tool, and a browser window opens with a full-featured diff viewer. Review inline, leave comments, and your decision is returned as structured JSON.
+
+## Features
+
+- **Syntax-highlighted diffs** — unified or split (side-by-side) view with toggle
+- **Inline line-level commenting** — click any line to add comments typed as `must_fix`, `suggestion`, `question`, or `nitpick`
+- **File-level review status** — mark each file as reviewed, approved, or needs changes
+- **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, `Space`/`Enter` cycle file status
+- **Three-way decisions** — approve, request changes, or approve with comments
+- **Branch display** — current git branch shown in the review header
 
 ## Quick Start
 
-```bash
-# Clone and install
-git clone <repo-url> && cd diffprism
-pnpm install
+### Use with Claude Code (recommended)
 
-# Review staged changes
-pnpm cli review --staged
+Run this from your project root:
+
+```bash
+npx diffprism setup
 ```
 
-A browser window opens with the diff viewer. Click **Approve** or **Request Changes**, and the result prints to stdout as JSON.
+This single command configures everything:
+- Creates `.mcp.json` with the DiffPrism MCP server
+- Creates `.claude/settings.json` with auto-approve permissions
+- Installs a `/review` skill so you can type `/review` in Claude Code at any time
+
+After running, restart Claude Code. The first time you use `/review`, Claude will ask your preferences and save them to `diffprism.config.json`.
 
-## Usage
+See the [full setup guide](docs/claude-setup.md) for manual configuration, Claude Desktop config, troubleshooting, and advanced options.
 
-### CLI
+### Use from the CLI
 
 ```bash
-# Review staged changes (default)
-pnpm cli review
-pnpm cli review --staged
+# Install globally (or use npx)
+npm install -g diffprism
 
-# Review unstaged changes
-pnpm cli review --unstaged
+# Review all changes (staged + unstaged, default)
+diffprism review
+
+# Review staged changes only
+diffprism review --staged
+
+# Review unstaged changes only
+diffprism review --unstaged
 
 # Review a specific ref range
-pnpm cli review HEAD~3
-pnpm cli review main..feature-branch
+diffprism review HEAD~3
+diffprism review main..feature-branch
 
 # Add a title to the review
-pnpm cli review --staged --title "Add auth middleware"
+diffprism review --staged --title "Add auth middleware"
 ```
 
-**Output:** A `ReviewResult` JSON object:
+A browser window opens with the diff viewer. Review the changes and click **Approve**, **Request Changes**, or **Approve with Comments**.
 
-```json
-{
-  "decision": "approved",
-  "comments": [],
-  "summary": ""
-}
-```
+## MCP Tool Reference
 
-Decisions are one of: `approved`, `changes_requested`, or `approved_with_comments`.
+The MCP server exposes one tool: **`open_review`**
 
-### Claude Code (MCP)
+| Parameter     | Required | Description                                                       |
+|---------------|----------|-------------------------------------------------------------------|
+| `diff_ref`    | Yes      | `"staged"`, `"unstaged"`, 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) |
 
-DiffPrism ships an MCP server so Claude Code can open reviews during a coding session.
-
-**Setup:** Add to your Claude Code MCP config (`.mcp.json` or project settings). See the [full setup guide](docs/claude-setup.md) for detailed instructions covering Claude Code, Claude Desktop, auto-approval, and troubleshooting.
+**Returns:** A `ReviewResult` JSON object:
 
 ```json
 {
-  "mcpServers": {
-    "diffprism": {
-      "command": "npx",
-      "args": ["diffprism", "serve"]
+  "decision": "approved",
+  "comments": [
+    {
+      "file": "src/index.ts",
+      "line": 42,
+      "body": "Consider adding a null check here",
+      "type": "suggestion"
     }
-  }
+  ],
+  "summary": "Looks good, one minor suggestion."
 }
 ```
 
-**Tool:** `open_review`
-
-| Parameter     | Required | Description                          |
-|---------------|----------|--------------------------------------|
-| `diff_ref`    | yes      | Git diff reference: `"staged"`, `"unstaged"`, or a ref range |
-| `title`       | no       | Title shown in the review UI         |
-| `description` | no       | Description of the changes           |
-| `reasoning`   | no       | Agent reasoning about why changes were made |
-
-The tool opens a browser, blocks until you submit a review, and returns the `ReviewResult` to Claude Code.
-
-**Auto-approve the tool:** By default Claude Code prompts for confirmation each time. To skip that, add `mcp__diffprism__open_review` to the `permissions.allow` array in your project's `.claude/settings.json` or your user-level `~/.claude/settings.json`:
-
-```json
-{
-  "permissions": {
-    "allow": [
-      "mcp__diffprism__open_review"
-    ]
-  }
-}
-```
+| Field | Description |
+|-------|-------------|
+| `decision` | `approved`, `changes_requested`, or `approved_with_comments` |
+| `comments` | Array of inline comments with file, line, body, and type (`must_fix`, `suggestion`, `question`, `nitpick`) |
+| `summary` | Optional reviewer summary |
 
 ## How It Works
 
 1. **Extract** — runs `git diff` and parses the output into a structured `DiffSet`
-2. **Analyze** — generates a `ReviewBriefing` with file stats, impact detection, and triage
+2. **Analyze** — generates a `ReviewBriefing`: file stats, complexity scores, test gap detection, pattern flags, dependency changes
 3. **Serve** — starts a Vite dev server (React UI) and WebSocket bridge on random ports
 4. **Review** — opens a browser to the diff viewer, waits for your decision
 5. **Return** — cleans up servers and returns the `ReviewResult`
@@ -100,8 +105,12 @@ The tool opens a browser, blocks until you submit a review, and returns the `Rev
 ## Development
 
 ```bash
-pnpm install                                    # Install all deps
+git clone https://github.com/CodeJonesW/diffprism.git
+cd diffprism
+pnpm install
 pnpm test                                       # Run all tests (Vitest)
+pnpm run build                                  # Build all packages
+pnpm cli review --staged                        # Run CLI from source
 npx tsc --noEmit -p packages/core/tsconfig.json # Type-check a package
 ```
 
@@ -110,15 +119,19 @@ npx tsc --noEmit -p packages/core/tsconfig.json # Type-check a package
 ```
 packages/core       — Shared types, pipeline orchestrator, WebSocket bridge
 packages/git        — Git diff extraction + unified diff parser
-packages/analysis   — Deterministic review briefing generation
-packages/ui         — React 19 + Vite + Tailwind diff viewer
+packages/analysis   — Deterministic review briefing (complexity, test gaps, patterns)
+packages/ui         — React 19 + Vite 6 + Tailwind + Zustand diff viewer
 packages/mcp-server — MCP tool server (open_review)
-packages/github     — Placeholder (future GitHub integration)
 cli/                — Commander CLI entry point
 ```
 
 ### Requirements
 
 - Node.js >= 20
-- pnpm
+- pnpm (for development)
 - Git
+
+## Documentation
+
+- [Claude Code / Claude Desktop Setup Guide](docs/claude-setup.md) — detailed MCP configuration, auto-approval, and troubleshooting
+- [UX Design Notes](docs/ux-design-notes.md) — design decisions, CLI defaults rationale, and multi-agent workflow thinking

package/dist/bin.js

@@ -40,9 +40,222 @@ async function serve() {
   await startMcpServer();
 }
 
+// cli/src/commands/setup.ts
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+// cli/src/templates/skill.ts
+var skillContent = `---
+name: review
+description: Open current code changes in DiffPrism's browser-based review UI for human review.
+---
+
+# DiffPrism Review Skill
+
+When the user invokes \`/review\`, open the current code changes in DiffPrism for browser-based human review.
+
+## Steps
+
+### 1. Check for Configuration
+
+Look for \`diffprism.config.json\` at the project root. If it exists, read it for preferences:
+
+\`\`\`json
+{
+  "reviewTrigger": "ask | before_commit | always",
+  "defaultDiffScope": "staged | unstaged | all",
+  "includeReasoning": true | false
+}
+\`\`\`
+
+**Defaults** (when fields are missing or file doesn't exist):
+- \`reviewTrigger\`: \`"ask"\`
+- \`defaultDiffScope\`: \`"all"\`
+- \`includeReasoning\`: \`true\`
+
+### 2. First-Run Onboarding
+
+If \`diffprism.config.json\` does **not** exist, ask the user these questions before proceeding:
+
+1. **"When should I open DiffPrism reviews?"**
+   - \`"ask"\` \u2014 Only when you explicitly ask (default)
+   - \`"before_commit"\` \u2014 Automatically before every commit
+   - \`"always"\` \u2014 After every code change
+
+2. **"What should the default diff scope be?"**
+   - \`"all"\` \u2014 All changes, staged and unstaged (default)
+   - \`"staged"\` \u2014 Only staged changes
+   - \`"unstaged"\` \u2014 Only unstaged changes
+
+3. **"Should I include my reasoning about the changes in reviews?"**
+   - Yes (default)
+   - No
+
+After collecting answers, create \`diffprism.config.json\` at the project root with the user's choices. Then proceed to open the review.
+
+### 3. Open the Review
+
+Call \`mcp__diffprism__open_review\` with:
+
+- \`diff_ref\`: Use the \`defaultDiffScope\` from config. If the user specified a scope in their message (e.g., "/review staged"), use that instead.
+- \`title\`: A short summary of the changes (generate from git status or the user's message).
+- \`description\`: A brief description of what changed and why.
+- \`reasoning\`: If \`includeReasoning\` is \`true\`, include your reasoning about the implementation decisions.
+
+### 4. Handle the Result
+
+The tool blocks until the user submits their review in the browser. When it returns:
+
+- **\`approved\`** \u2014 Acknowledge and proceed with whatever task was in progress.
+- **\`approved_with_comments\`** \u2014 Note the comments, address any actionable feedback.
+- **\`changes_requested\`** \u2014 Read the comments carefully, make the requested changes, and offer to open another review.
+
+### 5. Error Handling
+
+If the \`mcp__diffprism__open_review\` tool is not available:
+- Tell the user: "The DiffPrism MCP server isn't configured. Run \`npx diffprism setup\` to set it up, then restart Claude Code."
+
+## Behavior Rules
+
+- When invoked via \`/review\`, always open a review regardless of the \`reviewTrigger\` setting.
+- The \`reviewTrigger\` setting only applies to automatic review behavior during other workflows:
+  - \`"ask"\` \u2014 Never auto-review; only review when the user asks.
+  - \`"before_commit"\` \u2014 Open a review before creating any git commit.
+  - \`"always"\` \u2014 Open a review after any code change.
+- To re-run onboarding, the user can delete \`diffprism.config.json\` and invoke \`/review\` again.
+`;
+
+// cli/src/commands/setup.ts
+function findGitRoot(from) {
+  let dir = path.resolve(from);
+  while (true) {
+    if (fs.existsSync(path.join(dir, ".git"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+function readJsonFile(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function writeJsonFile(filePath, data) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+}
+function setupMcpJson(gitRoot, force) {
+  const filePath = path.join(gitRoot, ".mcp.json");
+  const existing = readJsonFile(filePath);
+  const servers = existing.mcpServers ?? {};
+  if (servers.diffprism && !force) {
+    return { action: "skipped", filePath };
+  }
+  servers.diffprism = {
+    command: "npx",
+    args: ["diffprism@latest", "serve"]
+  };
+  const action = fs.existsSync(filePath) ? "updated" : "created";
+  writeJsonFile(filePath, { ...existing, mcpServers: servers });
+  return { action, filePath };
+}
+function setupClaudeSettings(gitRoot, force) {
+  const filePath = path.join(gitRoot, ".claude", "settings.json");
+  const existing = readJsonFile(filePath);
+  const permissions = existing.permissions ?? {};
+  const allow = permissions.allow ?? [];
+  const toolName = "mcp__diffprism__open_review";
+  if (allow.includes(toolName) && !force) {
+    return { action: "skipped", filePath };
+  }
+  if (!allow.includes(toolName)) {
+    allow.push(toolName);
+  }
+  permissions.allow = allow;
+  const action = fs.existsSync(filePath) ? "updated" : "created";
+  writeJsonFile(filePath, { ...existing, permissions });
+  return { action, filePath };
+}
+function setupSkill(gitRoot, global, force) {
+  const skillDir = global ? path.join(os.homedir(), ".claude", "skills", "review") : path.join(gitRoot, ".claude", "skills", "review");
+  const filePath = path.join(skillDir, "SKILL.md");
+  if (fs.existsSync(filePath)) {
+    const existingContent = fs.readFileSync(filePath, "utf-8");
+    if (existingContent === skillContent) {
+      return { action: "skipped", filePath };
+    }
+    if (!force) {
+      console.log(
+        `  Warning: ${filePath} exists with different content. Use --force to overwrite.`
+      );
+      return { action: "skipped", filePath };
+    }
+  }
+  if (!fs.existsSync(skillDir)) {
+    fs.mkdirSync(skillDir, { recursive: true });
+  }
+  const action = fs.existsSync(filePath) ? "updated" : "created";
+  fs.writeFileSync(filePath, skillContent);
+  return { action, filePath };
+}
+async function setup(flags) {
+  const gitRoot = findGitRoot(process.cwd());
+  if (!gitRoot) {
+    console.error(
+      "Error: Not in a git repository. Run this command from inside a git project."
+    );
+    process.exit(1);
+    return;
+  }
+  const force = flags.force ?? false;
+  const global = flags.global ?? false;
+  console.log("Setting up DiffPrism for Claude Code...\n");
+  const result = { created: [], updated: [], skipped: [] };
+  const mcp = setupMcpJson(gitRoot, force);
+  result[mcp.action === "skipped" ? "skipped" : mcp.action === "created" ? "created" : "updated"].push(mcp.filePath);
+  const settings = setupClaudeSettings(gitRoot, force);
+  result[settings.action === "skipped" ? "skipped" : settings.action === "created" ? "created" : "updated"].push(settings.filePath);
+  const skill = setupSkill(gitRoot, global, force);
+  result[skill.action === "skipped" ? "skipped" : skill.action === "created" ? "created" : "updated"].push(skill.filePath);
+  if (result.created.length > 0) {
+    console.log("Created:");
+    for (const f of result.created) {
+      console.log(`  + ${path.relative(gitRoot, f)}`);
+    }
+  }
+  if (result.updated.length > 0) {
+    console.log("Updated:");
+    for (const f of result.updated) {
+      console.log(`  ~ ${path.relative(gitRoot, f)}`);
+    }
+  }
+  if (result.skipped.length > 0) {
+    console.log("Skipped (already configured):");
+    for (const f of result.skipped) {
+      console.log(`  - ${path.relative(gitRoot, f)}`);
+    }
+  }
+  console.log(
+    "\nYou can now use /review in Claude Code to open a DiffPrism review."
+  );
+  console.log(
+    "If Claude Code is running, restart it to pick up the new configuration."
+  );
+}
+
 // cli/src/index.ts
 var program = new Command();
-program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.10.1" : "0.0.0-dev");
+program.name("diffprism").description("Local-first code review tool for agent-generated changes").version(true ? "0.11.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("serve").description("Start the MCP server for Claude Code integration").action(serve);
+program.command("setup").description("Configure DiffPrism for Claude Code integration").option("--global", "Install skill globally (~/.claude/skills/)").option("--force", "Overwrite existing configuration files").action(setup);
 program.parse();

package/dist/mcp-server.js

@@ -11,7 +11,7 @@ import { z } from "zod";
 async function startMcpServer() {
   const server = new McpServer({
     name: "diffprism",
-    version: true ? "0.10.1" : "0.0.0-dev"
+    version: true ? "0.11.0" : "0.0.0-dev"
   });
   server.tool(
     "open_review",

package/package.json

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