nitpiq 0.1.0

package/README.md

@@ -0,0 +1,173 @@
+# nitpiq
+
+Terminal-based code review tool for local git changes. Built with Bun, TypeScript, React (Ink), and the React Compiler.
+
+Inspect uncommitted changes, leave anchored review comments, and expose an MCP server so AI tools can participate as a second reviewer.
+
+Review data is stored locally in `.git/nitpiq/review.db`.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) v1.1+
+
+## Install
+
+```bash
+bun install -g nitpiq
+```
+
+Or from source:
+
+```bash
+git clone <repo-url> && cd nitpiq
+bun install
+```
+
+## Usage
+
+### TUI
+
+Run inside any git repository:
+
+```bash
+nitpiq
+```
+
+Or with npx:
+
+```bash
+npx nitpiq
+```
+
+Options:
+
+```
+--theme=<name>   Set color theme (dark, catppuccin, nord, gruvbox)
+--demo           Launch with fixed demo data (no git required)
+--snapshot        Render a single frame and exit (for screenshots)
+```
+
+### MCP Server
+
+Start the MCP server for AI tool integration:
+
+```bash
+nitpiq-mcp /path/to/repo
+```
+
+Or with npx (useful for MCP client configuration):
+
+```bash
+npx nitpiq-mcp /path/to/repo
+```
+
+The server exposes these tools over stdio:
+
+| Tool | Description |
+|------|-------------|
+| `review_list_changes` | List uncommitted file changes |
+| `review_list_threads` | List review threads (filterable by file/status) |
+| `review_reply_thread` | Add a reply to a thread |
+| `review_resolve_thread` | Mark a thread as resolved |
+| `review_reopen_thread` | Reopen a resolved thread |
+| `review_apply_edit` | Write content to a file |
+| `review_stage_file` | Stage a file |
+| `review_unstage_file` | Unstage a file |
+
+#### MCP Client Configuration
+
+For Claude Desktop, add to your config:
+
+```json
+{
+  "mcpServers": {
+    "nitpiq": {
+      "command": "npx",
+      "args": ["nitpiq-mcp", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
+For Cursor, add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "nitpiq": {
+      "command": "npx",
+      "args": ["nitpiq-mcp", "/path/to/your/repo"]
+    }
+  }
+}
+```
+
+## Keybindings
+
+### File Sidebar
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Navigate files |
+| `l` / `Enter` | Open file in diff pane |
+| `/` | Filter files by name |
+| `s` | Stage / unstage file |
+| `f` | Toggle between git changes and all files |
+| `r` | Refresh |
+| `Tab` | Switch to diff pane |
+| `q` | Quit |
+
+### Diff Pane
+
+**Navigation (vim-style, supports count prefix e.g. `5j`):**
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Line up / down |
+| `gg` | Jump to top (or `[count]gg` to line N) |
+| `G` | Jump to bottom (or `[count]G` to line N) |
+| `Ctrl+D` / `Ctrl+U` | Half-page down / up |
+| `Ctrl+F` / `Ctrl+B` | Full-page down / up |
+| `H` / `M` / `L` | Top / middle / bottom of visible screen |
+| `{` / `}` | Previous / next block (hunk headers, blank lines) |
+| `w` / `b` | Next / previous changed line |
+| `[` / `]` | Previous / next review thread (cross-file) |
+| `zz` / `zt` / `zb` | Center / top / bottom current line on screen |
+| `:` | Go to line number |
+
+**Actions:**
+
+| Key | Action |
+|-----|--------|
+| `c` | Comment on current line (or reply if thread exists) |
+| `v` | Enter visual mode for range selection |
+| `d` | Delete thread at cursor (with confirmation) |
+| `r` | Resolve / reopen thread at cursor |
+| `/` | Search diff |
+| `n` / `N` | Next / previous search match |
+| `f` | Toggle diff view / full file view |
+| `e` | Cycle diff context (3 / 10 / full) |
+| `h` / `Esc` / `q` | Back to file sidebar |
+
+### Visual Mode
+
+| Key | Action |
+|-----|--------|
+| `j` / `k` | Extend selection |
+| `c` | Comment on selected range |
+| `Esc` | Cancel |
+
+## Themes
+
+Set with `--theme=<name>`:
+
+- **dark** (default) -- blue accent on dark background
+- **catppuccin** -- pastel mocha palette
+- **nord** -- arctic blue tones
+- **gruvbox** -- warm retro colors
+
+## Type Check
+
+```bash
+bun run check
+```

package/bin/nitpiq-mcp.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli/nitpiq-mcp.ts";

package/bin/nitpiq.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli/nitpiq.tsx";

package/bunfig.toml

@@ -0,0 +1 @@
+preload = ["./plugins/react-compiler.ts"]

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "nitpiq",
+  "version": "0.1.0",
+  "description": "Terminal-based code review tool for local git changes",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "nitpiq": "bin/nitpiq.ts",
+    "nitpiq-mcp": "bin/nitpiq-mcp.ts"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "plugins/",
+    "bunfig.toml"
+  ],
+  "scripts": {
+    "nitpiq": "bun run src/cli/nitpiq.tsx",
+    "nitpiq-mcp": "bun run src/cli/nitpiq-mcp.ts",
+    "dev": "bun run src/cli/nitpiq.tsx",
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.29.0",
+    "@babel/plugin-syntax-jsx": "^7.28.6",
+    "@babel/plugin-syntax-typescript": "^7.28.6",
+    "@types/bun": "latest",
+    "@types/react": "^19.2.14",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "eslint-plugin-react-hooks": "^7.0.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "fuse.js": "^7.1.0",
+    "ink": "^6.8.0",
+    "parse-diff": "^0.11.1",
+    "picocolors": "^1.1.1",
+    "react": "^19.2.4",
+    "zod": "^4.3.6"
+  }
+}

package/plugins/react-compiler.ts

@@ -0,0 +1,28 @@
+import { plugin } from "bun";
+import { transformSync } from "@babel/core";
+import ReactCompilerPlugin from "babel-plugin-react-compiler";
+
+plugin({
+  name: "react-compiler",
+  setup(build) {
+    build.onLoad({ filter: /\.tsx$/ }, async (args) => {
+      const source = await Bun.file(args.path).text();
+
+      const result = transformSync(source, {
+        filename: args.path,
+        plugins: [
+          [ReactCompilerPlugin, {}],
+          ["@babel/plugin-syntax-typescript", { isTSX: true }],
+          "@babel/plugin-syntax-jsx",
+        ],
+        configFile: false,
+        babelrc: false,
+      });
+
+      return {
+        contents: result?.code ?? source,
+        loader: "tsx",
+      };
+    });
+  },
+});

package/src/cli/nitpiq-mcp.ts

@@ -0,0 +1,10 @@
+import { serveStdio } from "../mcp/server";
+
+const repoPath = process.argv[2];
+
+try {
+  await serveStdio(repoPath);
+} catch (error) {
+  console.error(`nitpiq-mcp: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/src/cli/nitpiq.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+import { render } from "ink";
+import { openRepoAt } from "../git/repo";
+import { initLog } from "../log/log";
+import { Store } from "../store/store";
+import { NitpiqApp } from "../tui/app";
+import { createDemoState } from "../tui/demo";
+
+try {
+  const args = process.argv.slice(2);
+  const demo = args.includes("--demo");
+  const snapshot = args.includes("--snapshot");
+  const themeArg = args.find((a) => a.startsWith("--theme="));
+  const themeName = themeArg?.split("=")[1];
+  const demoState = demo ? createDemoState() : undefined;
+  const repo = demoState?.repo ?? openRepoAt(process.cwd());
+  const store = demo ? null : Store.open(repo.root);
+  if (!demo) {
+    initLog(repo.root);
+  }
+  const useAltScreen = Boolean(process.stdout.isTTY);
+  if (useAltScreen) {
+    process.stdout.write("\u001b[?1049h\u001b[H");
+  }
+
+  const instance = render(<NitpiqApp repo={repo} store={store} demoState={demoState} snapshot={snapshot} theme={themeName} />);
+  instance.waitUntilExit().finally(() => {
+    if (useAltScreen) {
+      process.stdout.write("\u001b[?1049l");
+    }
+    store?.close();
+  });
+} catch (error) {
+  console.error(`nitpiq: ${error instanceof Error ? error.message : String(error)}`);
+  process.exit(1);
+}

package/src/git/repo.ts

@@ -0,0 +1,237 @@
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export type ChangeKind = "modified" | "added" | "deleted" | "renamed" | "copied" | "untracked";
+
+export interface FileChange {
+  path: string;
+  oldPath: string;
+  kind: ChangeKind;
+  staged: boolean;
+  unstaged: boolean;
+}
+
+export interface Repo {
+  root: string;
+  name: string;
+  hasHead: boolean;
+}
+
+export function kindSymbol(kind: ChangeKind): string {
+  switch (kind) {
+    case "modified":
+      return "M";
+    case "added":
+      return "A";
+    case "deleted":
+      return "D";
+    case "renamed":
+      return "R";
+    case "copied":
+      return "C";
+    case "untracked":
+      return "?";
+  }
+}
+
+export function openRepoAt(dir?: string): Repo {
+  const root = runGit(["rev-parse", "--show-toplevel"], dir || process.cwd()).trim();
+  const hasHead = runGitOptional(["rev-parse", "HEAD"], root).ok;
+
+  return {
+    root,
+    name: path.basename(root),
+    hasHead,
+  };
+}
+
+export function openRepo(): Repo {
+  return openRepoAt();
+}
+
+export function changes(repo: Repo): FileChange[] {
+  const output = runGit(["status", "--porcelain=v1", "-uall"], repo.root);
+  return parsePorcelain(output);
+}
+
+export function files(repo: Repo): string[] {
+  const output = runGit(["ls-files", "--cached", "--others", "--exclude-standard"], repo.root);
+  const seen = new Set<string>();
+  const result: string[] = [];
+
+  for (const line of output.split("\n")) {
+    const candidate = line.trim();
+    if (!candidate || seen.has(candidate)) {
+      continue;
+    }
+    seen.add(candidate);
+    result.push(candidate);
+  }
+
+  return result;
+}
+
+export function diff(repo: Repo, change: FileChange, contextLines = 3): string {
+  if (change.kind === "untracked") {
+    return diffUntracked(repo, change.path);
+  }
+
+  const context = `-U${contextLines}`;
+
+  if (repo.hasHead) {
+    const result = runGitOptional(["diff", context, "HEAD", "--", change.path], repo.root);
+    if (result.ok && result.stdout.trim()) {
+      return result.stdout;
+    }
+  }
+
+  const cached = runGitOptional(["diff", context, "--cached", "--", change.path], repo.root);
+  if (cached.ok && cached.stdout.trim()) {
+    return cached.stdout;
+  }
+
+  const working = runGitOptional(["diff", context, "--", change.path], repo.root);
+  if (working.ok && working.stdout.trim()) {
+    return working.stdout;
+  }
+
+  return "(no diff available)";
+}
+
+function diffUntracked(repo: Repo, relativePath: string): string {
+  const absolutePath = path.join(repo.root, relativePath);
+  const stat = statSync(absolutePath);
+  if (stat.isDirectory()) {
+    return `(directory: ${relativePath})`;
+  }
+
+  const result = Bun.spawnSync(["git", "diff", "--no-index", "--", "/dev/null", absolutePath], {
+    cwd: repo.root,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const text = `${result.stdout ? Buffer.from(result.stdout).toString() : ""}${result.stderr ? Buffer.from(result.stderr).toString() : ""}`;
+  return text || "(empty file)";
+}
+
+export function readFile(repo: Repo, relativePath: string): string {
+  const filePath = path.join(repo.root, relativePath);
+  const stat = statSync(filePath);
+  if (stat.isDirectory()) {
+    throw new Error(`${relativePath} is a directory`);
+  }
+  return readFileSync(filePath, "utf8");
+}
+
+export function stage(repo: Repo, relativePath: string): void {
+  runGit(["add", "--", relativePath], repo.root);
+}
+
+export function unstage(repo: Repo, relativePath: string): void {
+  const restore = runGitOptional(["restore", "--staged", "--", relativePath], repo.root);
+  if (restore.ok) {
+    return;
+  }
+
+  const reset = runGitOptional(["reset", "HEAD", "--", relativePath], repo.root);
+  if (reset.ok) {
+    return;
+  }
+
+  const remove = runGitOptional(["rm", "--cached", "--", relativePath], repo.root);
+  if (!remove.ok) {
+    throw new Error(remove.stderr || `failed to unstage ${relativePath}`);
+  }
+}
+
+function parsePorcelain(output: string): FileChange[] {
+  const result: FileChange[] = [];
+
+  for (const line of output.split("\n")) {
+    if (line.length < 4) {
+      continue;
+    }
+
+    const x = line[0] ?? " ";
+    const y = line[1] ?? " ";
+    let filePath = line.slice(3);
+    let oldPath = "";
+
+    if (filePath.endsWith("/")) {
+      continue;
+    }
+
+    const renameIndex = filePath.indexOf(" -> ");
+    if (renameIndex >= 0) {
+      oldPath = filePath.slice(0, renameIndex);
+      filePath = filePath.slice(renameIndex + 4);
+    }
+
+    const change: FileChange = {
+      path: filePath,
+      oldPath,
+      kind: "modified",
+      staged: false,
+      unstaged: false,
+    };
+
+    if (x === "?" && y === "?") {
+      change.kind = "untracked";
+      change.unstaged = true;
+    } else {
+      if (x !== " " && x !== "?") {
+        change.staged = true;
+        change.kind = charToKind(x);
+      }
+      if (y !== " " && y !== "?") {
+        change.unstaged = true;
+        if (!change.staged) {
+          change.kind = charToKind(y);
+        }
+      }
+    }
+
+    result.push(change);
+  }
+
+  return result;
+}
+
+function charToKind(char: string): ChangeKind {
+  switch (char) {
+    case "A":
+      return "added";
+    case "D":
+      return "deleted";
+    case "R":
+      return "renamed";
+    case "C":
+      return "copied";
+    case "M":
+    default:
+      return "modified";
+  }
+}
+
+function runGit(args: string[], cwd: string): string {
+  const result = runGitOptional(args, cwd);
+  if (!result.ok) {
+    throw new Error(result.stderr || `git ${args.join(" ")} failed`);
+  }
+  return result.stdout;
+}
+
+function runGitOptional(args: string[], cwd: string): { ok: boolean; stdout: string; stderr: string } {
+  const proc = Bun.spawnSync(["git", ...args], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  return {
+    ok: proc.exitCode === 0,
+    stdout: proc.stdout ? Buffer.from(proc.stdout).toString() : "",
+    stderr: proc.stderr ? Buffer.from(proc.stderr).toString().trim() : "",
+  };
+}

package/src/log/log.ts

@@ -0,0 +1,27 @@
+import { mkdirSync, appendFileSync } from "node:fs";
+import path from "node:path";
+
+let logPath: string | null = null;
+
+export function initLog(repoRoot: string): void {
+  const dir = path.join(repoRoot, ".git", "nitpiq");
+  mkdirSync(dir, { recursive: true });
+  logPath = path.join(dir, "debug.log");
+}
+
+function write(level: string, message: string): void {
+  if (!logPath) {
+    return;
+  }
+
+  const line = `[${new Date().toISOString()}] ${level} ${message}\n`;
+  appendFileSync(logPath, line);
+}
+
+export function debug(message: string): void {
+  write("DEBUG", message);
+}
+
+export function error(message: string): void {
+  write("ERROR", message);
+}

package/src/mcp/server.test.ts

@@ -0,0 +1,37 @@
+import { mkdirSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { describe, expect, test } from "bun:test";
+
+describe("nitpiq MCP server", () => {
+  test("keeps the store open after connect", async () => {
+    const repoRoot = mkdtempSync(path.join(tmpdir(), "nitpiq-mcp-"));
+    await Bun.write(path.join(repoRoot, "file.ts"), "export const value = 1;\n");
+
+    Bun.spawnSync(["git", "init"], { cwd: repoRoot, stdout: "ignore", stderr: "ignore" });
+
+    const dbDir = path.join(repoRoot, ".git", "nitpiq");
+    mkdirSync(dbDir, { recursive: true });
+
+    const client = new Client({ name: "nitpiq-test", version: "0.0.0" }, { capabilities: {} });
+    const transport = new StdioClientTransport({
+      command: "bun",
+      args: ["run", path.join(process.cwd(), "src/cli/nitpiq-mcp.ts"), repoRoot],
+      cwd: process.cwd(),
+      stderr: "pipe",
+    });
+
+    await client.connect(transport);
+
+    const result = await client.callTool({
+      name: "review_list_threads",
+      arguments: { status: "open" },
+    });
+
+    expect(result.isError).not.toBeTrue();
+
+    await transport.close();
+  });
+});