diffity 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run:*)",
+      "mcp__playwright__browser_navigate",
+      "mcp__playwright__browser_take_screenshot",
+      "mcp__playwright__browser_evaluate",
+      "mcp__playwright__browser_snapshot"
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamran Ahmed
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+<img src="./packages/ui/public/brand.svg" width="80" />
+
+# diffity
+
+[Diffity](https://diffity.com) is an agent-agnostic, GitHub-style diff viewer and code review tool.
+
+```bash
+npm install -g diffity
+```
+
+It works with Claude Code, Cursor, Codex, and any AI coding agent.
+
+## See your diffs
+
+Run `diffity` inside any git repo — your browser opens with a GitHub-style, syntax-highlighted diff.
+
+```bash
+diffity                    # working tree changes
+diffity HEAD~1             # last commit
+diffity HEAD~3             # last 3 commits
+diffity main..feature      # compare branches
+diffity v1.0.0..v2.0.0     # compare tags
+```
+
+For the working tree, you can leave comments, copy them into your agent with a button and ask it to resolve them. Alternatively, use the skills below to avoid this manual step and let your agent auto-solve them.
+
+## AI code review
+
+Install the skills for your coding agent (Claude Code, Cursor, Codex, etc.):
+
+```bash
+npx skills add kamranahmedse/diffity
+```
+
+Then use the slash commands:
+
+```
+# use this skill to open the browser with diff viewer
+# you can review the code yourself and leave comments
+/diffity-start
+
+# once done, you can come back to the agent and use the
+# below skill to ask agent to resolve your comments.
+/diffity-resolve
+
+# you can use this to have AI review your uncommitted
+# changes and leave comments in the diff viewer
+/diffity-review
+```
+
+The review uses severity tags so you know what matters:
+- `[must-fix]` — Bugs, security issues
+- `[suggestion]` — Meaningful improvements
+- `[nit]` — Style preferences
+- `[question]` — Needs clarification
+
+You can focus the review on what you care about: `/diffity-review security` or `/diffity-review performance`
+
+## Options
+
+```
+--port <port>   Custom port (default: 5391)
+--no-open       Don't open browser
+--dark          Dark mode
+--unified       Unified view (default: split)
+--quiet         Minimal terminal output
+```
+
+## License
+
+MIT

package/development.md

@@ -0,0 +1,156 @@
+# Development Guide
+
+## Prerequisites
+
+- Node.js (v22+ recommended)
+- npm
+- Git
+
+## Initial Setup
+
+```bash
+# Install dependencies
+npm install
+
+# Start all watchers (run this in the diffity repo)
+npm run dev
+```
+
+This automatically creates the `diffity-dev` binary, builds skills, adds `.bin` to your PATH (in `~/.zshrc` or `~/.bashrc`), and starts five concurrent processes:
+
+| Process | What it does |
+|---------|-------------|
+| **parser** | `tsc --watch` on `@diffity/parser` |
+| **git** | `tsc --watch` on `@diffity/git` |
+| **cli** | `tsc --watch` on the CLI package |
+| **ui** | `vite build --watch` on `@diffity/ui` |
+| **skills** | Rebuilds Claude skills on change |
+
+If this is your first time, source your shell profile to pick up the PATH change:
+
+```bash
+source ~/.zshrc  # or ~/.bashrc
+```
+
+Then, in any git repository:
+
+```bash
+diffity-dev
+```
+
+This opens a diff viewer for that repo's working tree changes.
+
+## How the Dev Loop Works
+
+### UI changes
+
+The UI uses `vite build --watch` instead of `vite dev`. This is intentional — `vite dev` serves files from memory and never writes to disk, but the CLI server serves static files from `packages/cli/dist/ui/`. Using `vite build --watch` rebuilds the output on every change so the CLI can serve it. Refresh the browser to see changes.
+
+### Server changes (CLI, git, parser)
+
+`tsc --watch` recompiles TypeScript to `dist/` on save. The `diffity-dev` binary uses `node --watch-path=packages/cli/dist` which auto-restarts the Node process when any file in `dist/` changes. The port is persisted across restarts — the server retries the same port if it's briefly held by the old process.
+
+### How `diffity-dev` works
+
+`diffity-dev` is a shell script (not a symlink) created by `scripts/link-dev.ts`. It runs:
+
+```bash
+node --watch-path=<dist-dir> <cli-entry> --no-open "$@"
+```
+
+- **Shell script, not symlink** — a symlink to `dist/index.js` would load the CLI once and never pick up server changes. The shell script wraps it with `node --watch-path` so it restarts on recompilation.
+- **`--watch-path`** — restarts the process when `tsc --watch` writes new files to `dist/`.
+- **`--no-open`** — prevents opening a new browser tab on every restart. Open the URL manually on first run.
+
+## Project Structure
+
+```
+diffity/
+├── packages/
+│   ├── cli/          # CLI server and entry point
+│   │   ├── src/
+│   │   └── dist/
+│   │       ├── index.js    # CLI binary
+│   │       └── ui/         # Built UI (served as static files)
+│   ├── git/          # Git operations (execSync wrappers)
+│   ├── parser/       # Diff parsing library
+│   └── ui/           # React frontend (Vite + Tailwind)
+├── scripts/
+│   ├── dev.ts        # Starts all watchers concurrently
+│   ├── link-dev.ts   # Creates the diffity-dev shell script
+│   ├── build.ts      # Production build (all packages in order)
+│   └── build-skills.ts
+└── .bin/
+    └── diffity-dev   # Generated shell script for development
+```
+
+### Package dependencies
+
+```
+@diffity/ui ──► @diffity/parser
+                     ▲
+@diffity/cli ────────┤
+                     │
+              @diffity/git
+```
+
+The UI builds into `packages/cli/dist/ui/` so the CLI can serve it as static files. In production, everything ships as a single `diffity` npm package.
+
+## Build Commands
+
+```bash
+# Full production build (all packages in dependency order)
+npm run build
+
+# Build a single package
+npm run build -w @diffity/parser
+npm run build -w @diffity/git
+npm run build -w @diffity/ui
+npm run build -w diffity
+```
+
+## Testing
+
+```bash
+# Run all tests
+npm run test
+
+# Run tests for a specific package
+npm run test -w @diffity/parser
+npm run test -w @diffity/ui
+
+# Watch mode
+npm run test:watch -w @diffity/parser
+npm run test:watch -w @diffity/ui
+```
+
+## CLI Usage (for reference while developing)
+
+```bash
+diffity-dev                        # Working tree changes
+diffity-dev HEAD~1                 # Last commit vs working tree
+diffity-dev HEAD~3                 # Last 3 commits vs working tree
+diffity-dev main..feature          # Compare branches
+diffity-dev --port 3000            # Custom port
+```
+
+## Troubleshooting
+
+### Port already in use
+
+If `diffity-dev` fails with `EADDRINUSE`, a previous process is still running:
+
+```bash
+# Find and kill the process
+lsof -i :5391
+kill <PID>
+```
+
+The server retries the same port up to 30 times (15 seconds) on startup to handle the brief overlap during `--watch` restarts. But if a completely separate process holds the port, you need to kill it manually.
+
+### Changes not showing up
+
+1. Make sure `npm run dev` is running in the diffity repo
+2. Check that the relevant watcher (ui/cli/parser/git) isn't showing errors
+3. Refresh the browser — there's no HMR in this setup
+4. For server changes, wait for the `--watch` restart (you'll see the diffity banner re-print in the terminal where `diffity-dev` is running)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "diffity",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "GitHub-style git diff viewer in the browser",
+  "workspaces": [
+    "packages/cli",
+    "packages/git",
+    "packages/parser",
+    "packages/ui"
+  ],
+  "scripts": {
+    "build": "tsx scripts/build.ts",
+    "build:skills": "tsx scripts/build-skills.ts",
+    "test": "npm run test -w @diffity/parser && npm run test -w @diffity/ui",
+    "link-dev": "tsx scripts/link-dev.ts",
+    "dev": "tsx scripts/dev.ts"
+  },
+  "keywords": [
+    "git",
+    "diff",
+    "viewer",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "concurrently": "^9.2.1",
+    "gray-matter": "^4.0.3",
+    "tsx": "^4.21.0"
+  }
+}

package/packages/cli/build.js

@@ -0,0 +1,38 @@
+import { build } from 'esbuild';
+import { rmSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distDir = join(__dirname, 'dist');
+
+// Clean all previous build output except the ui/ directory (built separately by vite)
+for (const entry of readdirSync(distDir)) {
+  if (entry === 'ui') {
+    continue;
+  }
+  const fullPath = join(distDir, entry);
+  const stat = statSync(fullPath);
+  rmSync(fullPath, { recursive: stat.isDirectory(), force: true });
+}
+
+await build({
+  entryPoints: [join(__dirname, 'src/index.ts')],
+  bundle: true,
+  platform: 'node',
+  target: 'node18',
+  format: 'esm',
+  outfile: join(distDir, 'index.js'),
+  banner: {
+    js: '#!/usr/bin/env node',
+  },
+  external: [
+    'better-sqlite3',
+    'commander',
+    'open',
+    'picocolors',
+  ],
+  sourcemap: false,
+  minifySyntax: true,
+  treeShaking: true,
+});

package/packages/cli/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "diffity",
+  "version": "0.1.0",
+  "description": "GitHub-style git diff viewer in the browser",
+  "type": "module",
+  "bin": {
+    "diffity": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "node build.js",
+    "dev": "tsx src/index.ts",
+    "dev:watch": "tsc --watch"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.8.0",
+    "commander": "latest",
+    "open": "latest",
+    "picocolors": "latest"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "git",
+    "diff",
+    "viewer",
+    "cli",
+    "code-review",
+    "github"
+  ],
+  "author": "Kamran Ahmed <kamranahmed.se@gmail.com> (https://kamranahmed.se)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kamranahmedse/diffity.git"
+  },
+  "homepage": "https://diffity.com",
+  "bugs": {
+    "url": "https://github.com/kamranahmedse/diffity/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^25.5.0",
+    "esbuild": "^0.27.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/packages/cli/src/agent.ts

@@ -0,0 +1,187 @@
+import type { Command } from 'commander';
+import pc from 'picocolors';
+import { isGitRepo } from '@diffity/git';
+import { getCurrentSession } from './session.js';
+import {
+  createThread,
+  getThreadsForSession,
+  getThread,
+  addReply,
+  updateThreadStatus,
+  type ThreadStatus,
+  type Thread,
+} from './threads.js';
+
+function requireSession() {
+  if (!isGitRepo()) {
+    console.error(pc.red('Error: Not a git repository'));
+    process.exit(1);
+  }
+
+  const session = getCurrentSession();
+  if (!session) {
+    console.error(pc.red('Error: No active review session.'));
+    console.error(pc.dim('Start diffity first to create a session.'));
+    process.exit(1);
+  }
+  return session;
+}
+
+function resolveThreadId(shortId: string, sessionId: string): Thread {
+  const thread = getThread(shortId);
+  if (!thread) {
+    console.error(pc.red(`Error: Thread not found: ${shortId}`));
+    process.exit(1);
+  }
+  if (thread.sessionId !== sessionId) {
+    console.error(pc.red(`Error: Thread ${shortId} does not belong to current session`));
+    process.exit(1);
+  }
+  return thread;
+}
+
+function formatThreadLine(thread: Thread): string {
+  const shortId = thread.id.slice(0, 8);
+  const isGeneral = thread.filePath === '__general__';
+  const statusColor = thread.status === 'open' ? pc.yellow : thread.status === 'resolved' ? pc.green : thread.status === 'dismissed' ? pc.dim : pc.cyan;
+  const statusLabel = statusColor(`[${thread.status}]`);
+  const firstComment = thread.comments[0]?.body || '';
+  const truncated = firstComment.length > 80 ? firstComment.slice(0, 77) + '...' : firstComment;
+
+  if (isGeneral) {
+    return `${statusLabel.padEnd(22)} ${pc.dim(shortId)}  ${pc.bold('General comment')}\n${''.padEnd(15)}${pc.dim('"')}${truncated}${pc.dim('"')}`;
+  }
+
+  const lineRange = thread.startLine === thread.endLine
+    ? `${thread.startLine}`
+    : `${thread.startLine}-${thread.endLine}`;
+  const location = `${thread.filePath}:${lineRange}`;
+  const sideLabel = thread.side === 'old' ? '(old)' : '(new)';
+
+  return `${statusLabel.padEnd(22)} ${pc.dim(shortId)}  ${location} ${pc.dim(sideLabel)}\n${''.padEnd(15)}${pc.dim('"')}${truncated}${pc.dim('"')}`;
+}
+
+export function registerAgentCommands(program: Command): void {
+  const agent = program
+    .command('agent')
+    .description('Agent commands for interacting with review comments')
+    .addHelpText('after', `
+Examples:
+  $ diffity agent list --status open --json
+  $ diffity agent comment --file src/app.ts --line 42 --body "Missing null check"
+  $ diffity agent resolve abc123 --summary "Added null check"
+  $ diffity agent reply abc123 --body "Good catch, fixed"
+  $ diffity agent general-comment --body "Overall this looks good, just a few nits"`);
+
+  agent
+    .command('list')
+    .description('List comment threads in the current session (use --json for full details)')
+    .option('--status <status>', 'Filter by status (open, resolved, dismissed)')
+    .option('--json', 'Output as JSON')
+    .action((opts) => {
+      const validStatuses = ['open', 'resolved', 'dismissed'];
+      if (opts.status && !validStatuses.includes(opts.status)) {
+        console.error(pc.red(`Error: Invalid status "${opts.status}". Must be one of: ${validStatuses.join(', ')}`));
+        process.exit(1);
+      }
+      const session = requireSession();
+      const threads = getThreadsForSession(session.id, opts.status as ThreadStatus | undefined);
+
+      if (opts.json) {
+        console.log(JSON.stringify(threads, null, 2));
+        return;
+      }
+
+      if (threads.length === 0) {
+        console.log(pc.dim('No threads found.'));
+        return;
+      }
+
+      for (const thread of threads) {
+        console.log(formatThreadLine(thread));
+      }
+    });
+
+  agent
+    .command('comment')
+    .description('Create a new comment thread')
+    .requiredOption('--file <path>', 'File path (relative to repo root)')
+    .requiredOption('--line <n>', 'Line number (1-indexed)', parseInt)
+    .option('--end-line <n>', 'End line for multi-line comments (1-indexed)', parseInt)
+    .option('--side <side>', 'Which side of the diff (new or old)', 'new')
+    .requiredOption('--body <text>', 'Comment body')
+    .action((opts) => {
+      if (opts.side !== 'new' && opts.side !== 'old') {
+        console.error(pc.red(`Error: Invalid side "${opts.side}". Must be "new" or "old"`));
+        process.exit(1);
+      }
+      const session = requireSession();
+      const endLine = opts.endLine ?? opts.line;
+      const thread = createThread(
+        session.id,
+        opts.file,
+        opts.side,
+        opts.line,
+        endLine,
+        opts.body,
+        { name: 'Agent', type: 'agent' },
+      );
+      console.log(pc.green(`Created thread ${thread.id.slice(0, 8)}`));
+    });
+
+  agent
+    .command('resolve')
+    .description('Resolve a thread (marks as fixed)')
+    .argument('<thread-id>', 'Thread ID (or 8-char prefix)')
+    .option('--summary <text>', 'What was done to resolve it')
+    .action((id: string, opts) => {
+      const session = requireSession();
+      const thread = resolveThreadId(id, session.id);
+      const author = opts.summary ? { name: 'Agent', type: 'agent' as const } : undefined;
+      updateThreadStatus(thread.id, 'resolved', opts.summary, author);
+      console.log(pc.green(`Resolved thread ${thread.id.slice(0, 8)}`));
+    });
+
+  agent
+    .command('dismiss')
+    .description('Dismiss a thread (marks as won\'t fix)')
+    .argument('<thread-id>', 'Thread ID (or 8-char prefix)')
+    .option('--reason <text>', 'Why the thread is being dismissed')
+    .action((id: string, opts) => {
+      const session = requireSession();
+      const thread = resolveThreadId(id, session.id);
+      const author = opts.reason ? { name: 'Agent', type: 'agent' as const } : undefined;
+      updateThreadStatus(thread.id, 'dismissed', opts.reason, author);
+      console.log(pc.green(`Dismissed thread ${thread.id.slice(0, 8)}`));
+    });
+
+  agent
+    .command('reply')
+    .description('Reply to a comment thread')
+    .argument('<thread-id>', 'Thread ID (or 8-char prefix)')
+    .requiredOption('--body <text>', 'Reply body')
+    .action((id: string, opts) => {
+      const session = requireSession();
+      const thread = resolveThreadId(id, session.id);
+      addReply(thread.id, opts.body, { name: 'Agent', type: 'agent' });
+      console.log(pc.green(`Replied to thread ${thread.id.slice(0, 8)}`));
+    });
+
+  agent
+    .command('general-comment')
+    .description('Create a general comment on the entire diff (not tied to a specific file or line)')
+    .requiredOption('--body <text>', 'Comment body')
+    .action((opts) => {
+      const session = requireSession();
+      const thread = createThread(
+        session.id,
+        '__general__',
+        'new',
+        0,
+        0,
+        opts.body,
+        { name: 'Agent', type: 'agent' },
+      );
+      console.log(pc.green(`Created general comment ${thread.id.slice(0, 8)}`));
+    });
+}

package/packages/cli/src/db.ts

@@ -0,0 +1,58 @@
+import Database from 'better-sqlite3';
+import { join } from 'node:path';
+import { getDiffityDir } from '@diffity/git';
+
+let db: Database.Database | null = null;
+
+export function getDb(): Database.Database {
+  if (db) {
+    return db;
+  }
+
+  const dbPath = join(getDiffityDir(), 'reviews.db');
+  db = new Database(dbPath);
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  migrateDb(db);
+  return db;
+}
+
+function migrateDb(db: Database.Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS review_sessions (
+      id TEXT PRIMARY KEY,
+      ref TEXT NOT NULL,
+      head_hash TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS comment_threads (
+      id TEXT PRIMARY KEY,
+      session_id TEXT NOT NULL REFERENCES review_sessions(id),
+      file_path TEXT NOT NULL,
+      side TEXT NOT NULL,
+      start_line INTEGER NOT NULL,
+      end_line INTEGER NOT NULL,
+      status TEXT NOT NULL DEFAULT 'open',
+      anchor_content TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS comments (
+      id TEXT PRIMARY KEY,
+      thread_id TEXT NOT NULL REFERENCES comment_threads(id) ON DELETE CASCADE,
+      author_name TEXT NOT NULL,
+      author_type TEXT NOT NULL,
+      body TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+
+export function closeDb(): void {
+  if (db) {
+    db.close();
+    db = null;
+  }
+}