diffity 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,94 @@
+<img src="./packages/ui/public/brand.svg" width="80" />
+
+# diffity
+
+[![npm version](https://img.shields.io/npm/v/diffity)](https://www.npmjs.com/package/diffity)
+[![license](https://img.shields.io/npm/l/diffity)](https://github.com/kamranahmedse/diffity/blob/main/LICENSE)
+
+Diffity 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`
+
+## Multiple projects
+
+Diffity supports running multiple projects simultaneously. Each gets its own port automatically:
+
+```bash
+# Terminal 1 — starts on :5391
+cd ~/projects/app && diffity
+
+# Terminal 2 — starts on :5392
+cd ~/projects/api && diffity
+```
+
+If you run `diffity` in a repo that already has a running instance, it opens the existing one instead of starting a new server. Use `--new` to kill the existing instance and start fresh.
+
+```bash
+diffity list               # show all running instances
+diffity list --json        # machine-readable output
+```
+
+## Options
+
+```
+--port <port>   Custom port (default: auto-assigned from 5391)
+--no-open       Don't open browser
+--dark          Dark mode
+--unified       Unified view (default: split)
+--quiet         Minimal terminal output
+--new           Stop existing instance and start fresh
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -3,9 +3,10 @@
 // src/index.ts
 import { Command } from "commander";
 import { execSync as execSync3 } from "node:child_process";
-import { rmSync, existsSync as existsSync2 } from "node:fs";
-import { join as join5 } from "node:path";
-import { homedir as homedir2 } from "node:os";
+import { rmSync, existsSync as existsSync3 } from "node:fs";
+import { join as join6 } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { createHash as createHash3 } from "node:crypto";
 import { createRequire } from "node:module";
 import open from "open";
 import pc2 from "picocolors";
@@ -196,8 +197,8 @@ function getRecentCommits(query) {
 // src/server.ts
 import { createServer } from "node:http";
 import { createHash as createHash2 } from "node:crypto";
-import { readFileSync as readFileSync2, existsSync } from "node:fs";
-import { join as join4, extname } from "node:path";
+import { readFileSync as readFileSync3, existsSync as existsSync2 } from "node:fs";
+import { join as join5, extname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { dirname } from "node:path";
 
@@ -722,6 +723,116 @@ function handleReviewRoute(req, res, pathname, url) {
   return !1;
 }
 
+// src/registry.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync, existsSync, statSync, mkdirSync as mkdirSync2 } from "node:fs";
+import { join as join4 } from "node:path";
+import { homedir as homedir2 } from "node:os";
+var DIFFITY_DIR = join4(homedir2(), ".diffity"), REGISTRY_PATH = join4(DIFFITY_DIR, "registry.json"), LOCK_PATH = join4(DIFFITY_DIR, "registry.lock"), LOCK_STALE_MS = 5e3, LOCK_TIMEOUT_MS = 3e3, BASE_PORT = 5391, MAX_PORT_ATTEMPTS = 10;
+function isProcessAlive(pid) {
+  try {
+    return process.kill(pid, 0), !0;
+  } catch {
+    return !1;
+  }
+}
+function acquireLock() {
+  mkdirSync2(DIFFITY_DIR, { recursive: !0 });
+  let start = Date.now();
+  for (; ; )
+    try {
+      writeFileSync2(LOCK_PATH, String(process.pid), { flag: "wx" });
+      return;
+    } catch {
+      try {
+        let stat = statSync(LOCK_PATH);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          try {
+            unlinkSync(LOCK_PATH);
+          } catch {
+          }
+          continue;
+        }
+      } catch {
+        continue;
+      }
+      if (Date.now() - start > LOCK_TIMEOUT_MS) {
+        try {
+          unlinkSync(LOCK_PATH);
+        } catch {
+        }
+        try {
+          writeFileSync2(LOCK_PATH, String(process.pid), { flag: "wx" });
+          return;
+        } catch {
+          throw new Error("Could not acquire registry lock");
+        }
+      }
+      let wait = Date.now() + 50;
+      for (; Date.now() < wait; )
+        ;
+    }
+}
+function releaseLock() {
+  try {
+    unlinkSync(LOCK_PATH);
+  } catch {
+  }
+}
+function withLock(fn) {
+  acquireLock();
+  try {
+    return fn();
+  } finally {
+    releaseLock();
+  }
+}
+function readRegistryRaw() {
+  if (!existsSync(REGISTRY_PATH))
+    return [];
+  try {
+    return JSON.parse(readFileSync2(REGISTRY_PATH, "utf-8"));
+  } catch {
+    return [];
+  }
+}
+function writeRegistryRaw(entries) {
+  mkdirSync2(DIFFITY_DIR, { recursive: !0 }), writeFileSync2(REGISTRY_PATH, JSON.stringify(entries, null, 2));
+}
+function cleanStaleEntries(entries) {
+  return entries.filter((entry) => isProcessAlive(entry.pid));
+}
+function readRegistry() {
+  return withLock(() => {
+    let entries = readRegistryRaw(), clean = cleanStaleEntries(entries);
+    return clean.length !== entries.length && writeRegistryRaw(clean), clean;
+  });
+}
+function registerInstance(entry) {
+  withLock(() => {
+    let filtered = cleanStaleEntries(readRegistryRaw()).filter((e) => e.pid !== entry.pid);
+    filtered.push(entry), writeRegistryRaw(filtered);
+  });
+}
+function deregisterInstance(pid) {
+  withLock(() => {
+    let filtered = readRegistryRaw().filter((e) => e.pid !== pid);
+    writeRegistryRaw(filtered);
+  });
+}
+function findInstanceForRepo(repoHash) {
+  let match = readRegistry().find((e) => e.repoHash === repoHash);
+  return match || null;
+}
+function findAvailablePort() {
+  let entries = readRegistry(), usedPorts = new Set(entries.map((e) => e.port));
+  for (let i = 0; i < MAX_PORT_ATTEMPTS; i++) {
+    let candidate = BASE_PORT + i;
+    if (!usedPorts.has(candidate))
+      return candidate;
+  }
+  return 0;
+}
+
 // src/server.ts
 var __dirname = dirname(fileURLToPath(import.meta.url)), MIME_TYPES = {
   ".html": "text/html",
@@ -739,11 +850,11 @@ function sendError2(res, status, message) {
   res.writeHead(status, { "Content-Type": "application/json" }), res.end(JSON.stringify({ error: message }));
 }
 function serveStatic(res, filePath) {
-  if (!existsSync(filePath)) {
+  if (!existsSync2(filePath)) {
     sendError2(res, 404, "Not found");
     return;
   }
-  let ext = extname(filePath), mime = MIME_TYPES[ext] || "application/octet-stream", content = readFileSync2(filePath);
+  let ext = extname(filePath), mime = MIME_TYPES[ext] || "application/octet-stream", content = readFileSync3(filePath);
   res.writeHead(200, { "Content-Type": mime }), res.end(content);
 }
 function descriptionForRef(ref) {
@@ -780,7 +891,7 @@ function readBody2(req) {
   });
 }
 function startServer(options) {
-  let { port, diffArgs, description, effectiveRef } = options, sessionId = null, reviewsEnabled = isActionableRef(effectiveRef);
+  let { port, portIsExplicit, diffArgs, description, effectiveRef, registryInfo } = options, sessionId = null, reviewsEnabled = isActionableRef(effectiveRef);
   reviewsEnabled && effectiveRef && (sessionId = findOrCreateSession(effectiveRef).id);
   let includeUntracked = diffArgs.length === 0;
   function enrichWithLineCounts(diff, baseRef) {
@@ -801,7 +912,7 @@ function startServer(options) {
     }
     return raw;
   }
-  let uiDir = join4(__dirname, "ui"), server = createServer(async (req, res) => {
+  let uiDir = join5(__dirname, "ui"), server = createServer(async (req, res) => {
     let url = new URL(req.url || "/", `http://localhost:${port}`), pathname = url.pathname;
     if (res.setHeader("Access-Control-Allow-Origin", "*"), res.setHeader("Access-Control-Allow-Methods", "GET, POST, PATCH, DELETE, OPTIONS"), res.setHeader("Access-Control-Allow-Headers", "Content-Type"), req.method === "OPTIONS") {
       res.writeHead(204), res.end();
@@ -927,17 +1038,28 @@ function startServer(options) {
     }
     if (handleReviewRoute(req, res, pathname, url))
       return;
-    let filePath = join4(uiDir, pathname === "/" ? "index.html" : pathname);
-    existsSync(filePath) || (filePath = join4(uiDir, "index.html")), serveStatic(res, filePath);
-  }), closeFn = () => server.close();
+    let filePath = join5(uiDir, pathname === "/" ? "index.html" : pathname);
+    existsSync2(filePath) || (filePath = join5(uiDir, "index.html")), serveStatic(res, filePath);
+  }), closeFn = () => {
+    deregisterInstance(process.pid), server.close();
+  };
   return new Promise((resolve, reject) => {
-    let retries = 0, maxRetries = 30, onError = (err) => {
-      err.code === "EADDRINUSE" && retries < maxRetries ? (retries++, server.close(), setTimeout(() => server.listen(port), 500)) : reject(err);
+    let currentPort = port, retries = 0, maxRetries = portIsExplicit ? 0 : 10, onError = (err) => {
+      err.code === "EADDRINUSE" && retries < maxRetries ? (retries++, server.close(), currentPort++, setTimeout(() => server.listen(currentPort), 200)) : err.code === "EADDRINUSE" && portIsExplicit ? reject(new Error(`Port ${port} is already in use`)) : reject(err);
     };
     server.on("error", onError), server.on("listening", () => {
       let addr = server.address();
-      addr && typeof addr != "string" && resolve({ port: addr.port, close: closeFn });
-    }), server.listen(port);
+      addr && typeof addr != "string" && (registryInfo && registerInstance({
+        pid: process.pid,
+        port: addr.port,
+        repoRoot: registryInfo.repoRoot,
+        repoHash: registryInfo.repoHash,
+        repoName: registryInfo.repoName,
+        ref: effectiveRef || "work",
+        description: description || "Unstaged changes",
+        startedAt: (/* @__PURE__ */ new Date()).toISOString()
+      }), resolve({ port: addr.port, close: closeFn }));
+    }), server.listen(currentPort);
   });
 }
 
@@ -1020,7 +1142,7 @@ Examples:
 
 // src/index.ts
 var require2 = createRequire(import.meta.url), pkg = require2("../package.json"), program = new Command();
-program.name("diffity").description("GitHub-style git diff viewer in the browser").version(pkg.version).argument("[refs...]", "Git refs to diff (e.g. HEAD~3, main, main..feature)").option("--port <port>", "Port to use", "5391").option("--no-open", "Do not open browser automatically").option("--quiet", "Minimal terminal output").option("--dark", "Open in dark mode (default: light)").option("--unified", "Open in unified view (default: split)").addHelpText("after", `
+program.name("diffity").description("GitHub-style git diff viewer in the browser").version(pkg.version).argument("[refs...]", "Git refs to diff (e.g. HEAD~3, main, main..feature)").option("--port <port>", "Port to use (default: auto-assigned from 5391)", "5391").option("--no-open", "Do not open browser automatically").option("--quiet", "Minimal terminal output").option("--dark", "Open in dark mode (default: light)").option("--unified", "Open in unified view (default: split)").option("--new", "Stop existing instance and start fresh").addHelpText("after", `
 Examples:
   $ diffity                    Working tree changes
   $ diffity HEAD~1             Last commit vs working tree
@@ -1037,29 +1159,89 @@ Examples:
     let ref = refs[0];
     ref.includes("..") ? (diffArgs.push(ref), description = ref) : (diffArgs.push(ref), description = `Changes from ${ref}`);
   } else refs.length === 2 ? (diffArgs.push(`${refs[0]}..${refs[1]}`), description = `${refs[0]}..${refs[1]}`) : description = "Unstaged changes";
-  let port = parseInt(opts.port, 10), effectiveRef;
+  let effectiveRef;
   refs.length > 0 ? effectiveRef = refs.length === 2 ? `${refs[0]}..${refs[1]}` : refs[0] : effectiveRef = "work";
+  let repoRoot = getRepoRoot(), repoHash = createHash3("sha256").update(repoRoot).digest("hex").slice(0, 12), repoName = getRepoName(), existing = findInstanceForRepo(repoHash);
+  if (existing)
+    if (opts.new) {
+      try {
+        process.kill(existing.pid, "SIGTERM");
+      } catch {
+      }
+      deregisterInstance(existing.pid), opts.quiet || console.log(pc2.dim(`  Stopped existing instance (pid ${existing.pid})`));
+    } else {
+      let urlParams = new URLSearchParams({ ref: effectiveRef });
+      opts.dark && urlParams.set("theme", "dark"), opts.unified && urlParams.set("view", "unified");
+      let url = `http://localhost:${existing.port}/?${urlParams.toString()}`;
+      opts.quiet || (console.log(""), console.log(pc2.bold("  diffity")), console.log(`  ${pc2.dim("Already running for this repo")}`), console.log(""), console.log(`  ${pc2.green("\u2192")} ${pc2.cyan(url)}`), console.log("")), opts.open !== !1 && await open(url);
+      return;
+    }
+  let explicitPort = program.getOptionValueSource("port") === "cli", port = explicitPort ? parseInt(opts.port, 10) : findAvailablePort();
   try {
-    let { port: actualPort, close } = await startServer({ port, diffArgs, description, effectiveRef }), urlParams = new URLSearchParams({ ref: effectiveRef });
+    let { port: actualPort, close } = await startServer({
+      port,
+      portIsExplicit: explicitPort,
+      diffArgs,
+      description,
+      effectiveRef,
+      registryInfo: { repoRoot, repoHash, repoName }
+    }), urlParams = new URLSearchParams({ ref: effectiveRef });
     opts.dark && urlParams.set("theme", "dark"), opts.unified && urlParams.set("view", "unified");
     let url = `http://localhost:${actualPort}/?${urlParams.toString()}`;
     opts.quiet || (console.log(""), console.log(pc2.bold("  diffity")), console.log(`  ${pc2.dim(description)}`), console.log(""), console.log(`  ${pc2.green("\u2192")} ${pc2.cyan(url)}`), console.log(`  ${pc2.dim("Press Ctrl+C to stop")}`), console.log("")), process.on("SIGINT", () => {
       opts.quiet || console.log(pc2.dim(`
-  Shutting down...`)), close(), process.exit(0);
+  Shutting down...`)), deregisterInstance(process.pid), close(), process.exit(0);
     }), process.on("SIGTERM", () => {
-      close(), process.exit(0);
+      deregisterInstance(process.pid), close(), process.exit(0);
     }), opts.open !== !1 && await open(url);
   } catch (err) {
     console.error(pc2.red(`Failed to start server: ${err}`)), process.exit(1);
   }
 });
+program.command("list").description("List all running diffity instances").option("--json", "Output as JSON").action((opts) => {
+  let entries = readRegistry();
+  if (opts.json) {
+    console.log(JSON.stringify(entries, null, 2));
+    return;
+  }
+  if (entries.length === 0) {
+    console.log(pc2.dim("No running diffity instances."));
+    return;
+  }
+  console.log(""), console.log(
+    `  ${pc2.dim("PORT")}   ${pc2.dim("PID".padEnd(8))}${pc2.dim("REPO".padEnd(22))}${pc2.dim("REF".padEnd(22))}${pc2.dim("STARTED")}`
+  );
+  for (let entry of entries) {
+    let ago = getTimeAgo(entry.startedAt);
+    console.log(
+      `  ${String(entry.port).padEnd(7)}${String(entry.pid).padEnd(8)}${entry.repoName.slice(0, 20).padEnd(22)}${entry.ref.slice(0, 20).padEnd(22)}${pc2.dim(ago)}`
+    );
+  }
+  console.log("");
+});
+function getTimeAgo(isoDate) {
+  let diff = Date.now() - new Date(isoDate).getTime(), seconds = Math.floor(diff / 1e3);
+  if (seconds < 60)
+    return "just now";
+  let minutes = Math.floor(seconds / 60);
+  if (minutes < 60)
+    return `${minutes}m ago`;
+  let hours = Math.floor(minutes / 60);
+  return hours < 24 ? `${hours}h ago` : `${Math.floor(hours / 24)}d ago`;
+}
 program.command("prune").description("Remove all diffity data (database, sessions) for all repos").action(() => {
-  let dir = join5(homedir2(), ".diffity");
-  if (!existsSync2(dir)) {
+  let dir = join6(homedir3(), ".diffity");
+  if (!existsSync3(dir)) {
     console.log(pc2.dim("Nothing to prune."));
     return;
   }
-  rmSync(dir, { recursive: !0, force: !0 }), console.log(pc2.green("Pruned all diffity data (~/.diffity)."));
+  let running = readRegistry();
+  for (let entry of running)
+    try {
+      process.kill(entry.pid, "SIGTERM");
+    } catch {
+    }
+  running.length > 0 && console.log(pc2.dim(`  Stopped ${running.length} running instance${running.length > 1 ? "s" : ""}.`)), rmSync(dir, { recursive: !0, force: !0 }), console.log(pc2.green("Pruned all diffity data (~/.diffity)."));
 });
 program.command("update").description("Update diffity to the latest version").action(() => {
   try {