diffing 0.2.1 → 0.3.0

package/README.md

@@ -22,6 +22,16 @@ diffing
 ```
 This instantly spins up a local server, establishes an active repository watcher, and opens your default browser to an interactive code review dashboard.
 
+Prefer the terminal? Add `--tui` for a native-Rust terminal UI — same review flow, no browser:
+```bash
+diffing --tui
+```
+> [!WARNING]
+> The TUI is **experimental** in v0.3.0. The interface, keymap, and
+> `server.json` (`mode: "tui"`) on-disk format may change in a minor
+> release. The web UI is the supported path for production workflows.
+> See [Native Terminal UI (TUI)](#native-terminal-ui-tui) for the full feature set, keymap, and stability notes.
+
 ### 3. Update
 Check if a new version is available on npm and upgrade instantly via the CLI:
 ```bash
@@ -40,7 +50,7 @@ A local Hono-powered review server delivers a full-featured GitHub-like code rev
 - **Status Dashboard (Comment Tracker)** — Bottom panel tracking open, replied, and resolved comments with filter tabs and click-to-navigate references to the relevant file and line.
 - **Git Diff Stats** — Toolbar displays repo name, branch, file count, and additions/deletions (`+X/-Y`) computed from the patch.
 - **Server-Side State & Drafts Persistence** — No browser storage is used. All settings, UI panels sizing, session states, and comment drafts are securely stored and persisted server-side in the project's global `.diffing` directory (and global settings inside `~/.config/diffing/settings.json`).
-- **Dynamic Font Customization** — Dynamically load, cache, and apply any Google Fonts or local system fonts for both UI typography and monospace code rendering, easily configurable via the settings font picker.
+- **Dynamic Font Customization** — Pick any [Google Fonts](https://fonts.google.com/) family or locally-installed system font for both UI typography and monospace code rendering, configurable via the settings font picker. Google-hosted families are fetched automatically as web fonts and render everywhere; local fonts are applied by name (see the [note on custom fonts](#a-note-on-custom-fonts)).
 - **Resizable Panels** — Drag-to-resize sidebar (240px–640px) and comment tracker panel (100px–600px). Panel states are instantly saved server-side for absolute consistency across browser sessions.
 - **Skeleton Loading Screen** — Full shimmer placeholder UI for toolbar, sidebar, search, tree nodes, and file diffs during initial load.
 - **Image Diff Previews** — Visual side-by-side comparison for added, changed, and deleted image files (PNG, JPEG, GIF, WebP, SVG, BMP, ICO, AVIF).
@@ -131,6 +141,52 @@ A vim-style status bar at the bottom displays the current mode (NORMAL/INSERT),
 <img width="1840" height="1196" alt="image" src="https://github.com/user-attachments/assets/d230d020-4fb2-475a-a8a0-0ae11bb271ff" />
 
 
+---
+
+## Native Terminal UI (TUI) — *Experimental*
+
+> [!WARNING]
+> The TUI is **experimental** in v0.3.0. The interface, keymap, and on-disk
+> format of `server.json` (`mode: "tui"`) may change in a minor release
+> before stabilisation. The web UI is the supported path for production
+> workflows; please open an issue before depending on the TUI for CI / agent
+> automation. The web review flow, plan review, and PR review are unaffected.
+
+`diffing --tui` opens an **opt-in native-Rust terminal interface** that mirrors the web review dashboard — no browser, no Electron, no port. It's a leaf renderer in a new `crates/diffing-tui/` binary: the Node CLI is still the single source of truth for arg parsing, lockfile discovery, and agent handoff, and the TUI reads the same `~/.diffing/<repo>/*` state on disk and writes a `server.json` with `mode: "tui"`.
+
+The default `diffing` behaviour is **byte-identical** with and without `--tui` — the TUI is strictly opt-in. If the env cannot support a TUI (piped stdin, CI, no raw mode) or the binary is missing, you get a one-line stderr note and the normal `git diff` output. The web mode is also unaffected by the TUI build; the same `diffing` install serves either.
+
+```bash
+diffing --tui                       # Open the current working tree in the TUI
+diffing --tui --staged              # Review staged changes in the TUI
+diffing --tui HEAD~3                # Review working tree vs. 3 commits ago
+diffing --tui main..feature         # Compare two branches in the TUI
+diffing --tui -- -- src/            # Limit a TUI review to a directory
+```
+
+**Stack** — Rust 1.78+ workspace (`crates/diffing-core/` shared lib + `crates/diffing-tui/` binary), `ratatui` + `crossterm` for rendering, `syntect` for syntax highlighting, `notify-debouncer-full` for live updates.
+
+**Features**
+
+- **Unified diff render** with a virtualised file card, syntect highlighter, and the same 8 Shiki-compatible colour themes as the web UI.
+- **Vim-style file tree & keymap** — `j/k/gg/G/J/K/Tab/w/t/m/?/` motions, plus `c` (new comment), `e/r/x` (edit / reply / resolve), `]`/`[` (next / previous thread), `?` (help).
+- **Full comment CRUD** — mirrors `src/lib/comments.ts` byte-for-byte; the comment tracker at the bottom lists open / replied / resolved threads with click-to-jump navigation.
+- **Multi-line `tui-textarea` form** with markdown rendering in the preview pane.
+- **Live updates** via `notify` watcher on `comments.json` and the repo working tree — write a comment in another window and it appears immediately.
+- **Send review & agent handoff** — verdict radios + general-comment popover with a live XML preview. Submits via the same `format_comments` envelope as the web UI, copies to clipboard (`pbcopy` / `wl-copy` / `xclip` / `xsel` / `clip.exe`), and persists `pending-review.xml`. The agent-status indicator in the status bar mirrors the web UI's "Send to agent" connection dot.
+- **Cross-platform** — macOS, Linux, and Windows are all first-class. The TUI liveness probe uses `kill(pid, 0)` on Unix and `tasklist /NH /FO CSV` on Windows. Clipboard works on Wayland (`wl-copy`), X11 (`xclip` / `xsel`), macOS (`pbcopy`), and Windows (`clip.exe` / PowerShell `Set-Clipboard`).
+
+**Caveat** — the TUI's "Send to agent" writes the review to disk + clipboard but does not actively unblock a long-polling `diffing await-review`; that requires a Node-side change in a follow-up. The web UI's send button remains the supported native handoff path. The `pending-review.xml` is still produced and the review session is still round-incremented — only the long-poll wake-up is missing.
+
+**Building the binary locally**
+
+```bash
+pnpm build:tui               # debug build → target/debug/diffing-tui
+pnpm build:tui --release     # release build → target/release/diffing-tui
+```
+
+The CLI auto-discovers the binary in the following search order: sibling of `dist/cli.mjs`, `bin/`, `target/release/`, `target/debug/`, then `$PATH`. A `cargo build` (debug) workflow is supported out of the box; you don't need `--release` just to use the TUI.
+
 ---
 
 ## Console Startup Animations & Quotes
@@ -315,7 +371,79 @@ self-documenting `<plan-review>` envelope:
 
 <img width="1667" height="1087" alt="image" src="https://github.com/user-attachments/assets/00e884b5-4c90-4a9a-9e24-9ae57d80f3f2" />
 
+---
+
+## Reviewing a GitHub PR
+
+`diffing` can open a GitHub PR in the same diff UI you use for the working
+tree, and push your review back to GitHub when you're done. The "Send to
+agent" handoff is **structurally absent** in PR mode — there's no way to
+accidentally route a PR review to a coding agent.
+
+```text
+# All of these open PR #1234 in the current repo:
+diffing "gh pr 1234"
+diffing --gh-pr 1234
+
+# Full URL form:
+diffing "gh pr https://github.com/ahmedragab20/diffing/pull/1234"
+diffing --gh-pr https://github.com/ahmedragab20/diffing/pull/1234
+
+# owner/repo#N shorthand (skips the cwd-repo check):
+diffing "gh pr ahmedragab20/diffing#1234"
+```
+
+The PR diff loads in the existing `<DiffViewer>` / `<FileTree>` machinery.
+Existing review comments on the PR are fetched and shown as a read-only
+summary strip below each file so you can see what was already said before
+adding your own. Comments you write are kept visually distinct.
+
+When you click **Submit to GitHub**, `diffing` builds a `POST
+/repos/{owner}/{repo}/pulls/{pull_number}/reviews` payload and POSTs it
+to GitHub. Multi-line comments are expanded to N single-line comments
+with a `[part N/M]` prefix. Existing comments are **never re-POSTed** —
+only the new ones you wrote in this session.
+
+### Headless subcommands
+
+For CI / agent use, the same flow is exposed as a `gh` subcommand with no
+UI:
+
+```text
+# Submit the current in-progress review to GitHub.
+diffing gh pr-review 1234 --decision request-changes --body "Please address the range"
+
+# Dump PR metadata (title, owner, head SHA, existing comments) as JSON.
+diffing gh pr-fetch 1234
+
+# List the PR-mode comments in this diffing session (mirrors `diffing comments`).
+diffing gh pr-list-comments
+
+# Show the active PR session (ref, owner/repo#n, comment count, submitted status).
+diffing gh status
+```
+
+### Authentication
+
+The submit path uses the same precedence as the rest of the GitHub
+ecosystem:
+
+1. **`gh` CLI** — preferred; uses your existing `gh auth login` session.
+2. **Token env var** — `$GH_TOKEN`, then `$GITHUB_TOKEN`, then
+   `$GITHUB_API_TOKEN` (any of the three).
+3. If neither is available, the submit fails with a clear one-line
+   message telling you to run `gh auth login` or set `$GITHUB_TOKEN`.
+
+The `gh` binary is **only** used for the submit and refresh steps; the
+diff itself is rendered locally, so PR review works offline once the
+session is open.
+
+### Storage
 
+PR-mode state lives in `pr-session.json` (in the per-repo
+`~/.diffing/<repo>-<hash>/` directory) — a separate file from
+`comments.json` and `plans.json`, so a local review and a PR review can
+coexist without colliding.
 
 ---
 
@@ -354,6 +482,12 @@ Fine-grained control over how diffs are rendered:
 
 All settings persist to `~/.config/diffing/settings.json` and the UI updates are wrapped in `useTransition` for non-blocking responsiveness.
 
+#### A note on custom fonts
+
+Google-hosted families (e.g. `Fira Code`, `Source Code Pro`, `IBM Plex Mono`, `Roboto Mono`) are fetched automatically as web fonts and render in any browser. A **locally-installed** font — a Nerd Font, or a commercial font like `Dank Mono` — is applied by name and renders only if it is installed on your machine **and** your browser allows pages to use local fonts.
+
+Privacy-hardened browsers block this: **Brave**, with Shields / "Block fingerprinting" enabled (the default), refuses to render uncommon local fonts as an anti-fingerprinting measure, so the selection silently falls back to the default monospace even though it is installed. To use a local-only font there, either pick a Google-hosted equivalent, or open **Shields** for the diffing site, set fingerprinting to *Allow all*, and reload.
+
 ---
 
 ## Merge Conflict Resolution
@@ -410,6 +544,23 @@ To integrate flawlessly with your existing developer shell workflows, build pipe
 > [!TIP]
 > For a full list of all git option categories (algorithms, whitespace ignoring, context lines, word-level diffs, moved/copied detection, and path filtering) supported by `diffing`, see the [CLI Reference Manual](docs/cli.md).
 
+### `diffing show` — Review a Commit's Changes (Drop-in for `git show`)
+
+`diffing <sha>` runs `git diff <sha>`, which means "diff between `<sha>` and the working tree" — not the changes that commit introduced. If the working tree matches `<sha>`, the patch is empty and the file list renders blank.
+
+To review the changes **of** a commit, use the new `show` subcommand. It mirrors `git show` and surfaces each commit's metadata (subject, author, date, message body) above the diff in the web UI:
+
+```bash
+diffing show HEAD              # Review the tip commit's metadata + diff
+diffing show HEAD~3..HEAD      # Review the last 3 commits as a series
+diffing show v1.0              # The commit a tag points to
+diffing show abc123 def456     # Two specific commits, oldest-first
+diffing show HEAD -- src/      # Limit a commit review to a directory
+diffing show HEAD~2..HEAD --terminal   # Stream `git show` to your terminal
+```
+
+`show` accepts every form `git show` understands (single commit, range, tag, branch tip, multiple SHAs) and is strictly opt-in — `diffing <sha>` keeps its current `git diff <sha>` semantics so existing muscle memory and scripts are unaffected.
+
 ---
 
 ## Integration & Configuration
@@ -502,6 +653,12 @@ For advanced features, internal API endpoints, sequence specifications, and conf
 
 ---
 
+## Landing Page
+
+<img width="1287" height="6579" alt="screencapture-localhost-3000-2026-05-31-20_57_04" src="https://github.com/user-attachments/assets/a163b00e-a85a-428f-b8d5-2a33ff9fa1eb" />
+
+---
+
 👉🏻 The project was intially forked from **wong2/diffx**
 
 ## License

package/dist/{cli-agent-ZAkixf4c.mjs → cli-agent-KxNAFIPf.mjs}

@@ -1,4 +1,5 @@
-import { c as formatComments, n as readServerLock, o as formatPlanReview, t as isLockAlive } from "./server-lock-DpCrvL-Z.mjs";
+import { a as formatComments, n as readServerLock, t as isLockAlive } from "./server-lock-Dj9fG9md.mjs";
+import { n as formatPlanReview } from "./plan-format-f62JWFI-.mjs";
 import { parseArgs } from "node:util";
 import { readFile } from "node:fs/promises";
 //#region src/cli-agent.ts
@@ -435,8 +436,11 @@ async function runSubcommand(name, args) {
 		case "url": return url();
 		case "plan": return plan(args);
 		case "update":
-			const { runUpdateCommand } = await import("./update-check-DJuFE9w6.mjs");
+			const { runUpdateCommand } = await import("./update-check-DAPFCqpF.mjs");
 			return runUpdateCommand();
+		case "gh":
+			const { runGhSubcommand } = await import("./cli-gh-CDGSpndZ.mjs");
+			return runGhSubcommand(args);
 		default:
 			console.error(`Unknown subcommand: ${name}`);
 			return EXIT_USAGE;

package/dist/cli-gh-CDGSpndZ.mjs

@@ -0,0 +1,147 @@
+import { a as formatComments, n as readServerLock, t as isLockAlive } from "./server-lock-Dj9fG9md.mjs";
+import { parseArgs } from "node:util";
+//#region src/cli-gh.ts
+/**
+* `diffing gh …` — the headless / port-agnostic surface for the PR review
+* mode. Mirrors the shape of the local review CLI: each subcommand resolves
+* the running server from the per-repo lockfile and talks to it via
+* localhost HTTP. No port ever leaves the lockfile.
+*
+*   diffing gh pr-fetch <ref>           → GET  /api/gh/pr/init then dump
+*   diffing gh pr-review                → POST /api/gh/submit (current session)
+*   diffing gh pr-list-comments         → GET  /api/gh/pr-session/comments (XML)
+*   diffing gh status                   → GET  /api/gh/session (one-line summary)
+*/
+const EXIT_OK = 0;
+const EXIT_NO_SERVER = 3;
+const EXIT_NOT_FOUND = 4;
+const EXIT_USAGE = 5;
+function baseUrl() {
+	const lock = readServerLock();
+	if (!lock || !isLockAlive(lock)) {
+		console.error("No diffing server running for this repo. Start one with `diffing \"gh pr <ref>\"`.");
+		process.exit(EXIT_NO_SERVER);
+	}
+	return `http://${lock.host === "0.0.0.0" || lock.host === "::" ? "127.0.0.1" : lock.host}:${lock.port}`;
+}
+async function ghStatus() {
+	const base = baseUrl();
+	const res = await fetch(`${base}/api/gh/session`);
+	if (res.status === 404) {
+		console.error("No active PR session. Start one with `diffing \"gh pr <ref>\"`.");
+		return EXIT_NOT_FOUND;
+	}
+	const s = await res.json();
+	const submittedLine = s.submittedAt ? `submitted at ${new Date(s.submittedAt).toISOString()} → ${s.submittedReviewUrl ?? "(no url)"}` : "not submitted yet";
+	console.log(`${s.owner}/${s.repo}#${s.pullNumber}  ${s.title}`);
+	console.log(`  url:        ${s.url}`);
+	console.log(`  author:     ${s.author?.login ?? "(unknown)"}`);
+	console.log(`  +${s.additions} -${s.deletions}  (${s.changedFiles} files)`);
+	console.log(`  head:       ${s.headSha.slice(0, 7)}`);
+	console.log(`  base:       ${s.baseSha.slice(0, 7)}`);
+	console.log(`  existing:   ${s.existingComments?.length ?? 0} review comments (read-only context)`);
+	console.log(`  new:        ${s.comments?.length ?? 0} comments in this session`);
+	console.log(`  status:     ${submittedLine}`);
+	return EXIT_OK;
+}
+async function ghPrFetch(args) {
+	const { values, positionals } = parseArgs({
+		args,
+		options: { json: { type: "boolean" } },
+		allowPositionals: true
+	});
+	const ref = positionals[0];
+	if (!ref) {
+		console.error("Usage: diffing gh pr-fetch <ref> [--json]");
+		return EXIT_USAGE;
+	}
+	const base = baseUrl();
+	const res = await fetch(`${base}/api/gh/pr/init`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ ref })
+	});
+	if (!res.ok) {
+		const err = await res.json().catch(() => ({}));
+		console.error(`Failed to fetch PR: ${err.error ?? res.statusText}`);
+		return 1;
+	}
+	const result = await res.json();
+	if (values.json) process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+	else console.log(`${result.owner}/${result.repo}#${result.pullNumber}  ${result.url}`);
+	return EXIT_OK;
+}
+async function ghPrListComments() {
+	const base = baseUrl();
+	const res = await fetch(`${base}/api/gh/pr-session/comments`);
+	if (res.status === 404) {
+		console.error("No active PR session.");
+		return EXIT_NOT_FOUND;
+	}
+	const comments = await res.json();
+	process.stdout.write(formatComments(comments) + "\n");
+	return EXIT_OK;
+}
+async function ghPrReview(args) {
+	const { values } = parseArgs({
+		args,
+		options: {
+			decision: {
+				type: "string",
+				short: "d"
+			},
+			body: {
+				type: "string",
+				short: "b"
+			},
+			"dry-run": { type: "boolean" },
+			json: { type: "boolean" }
+		},
+		allowPositionals: false
+	});
+	const decision = values.decision;
+	if (decision !== "approve" && decision !== "comment" && decision !== "request-changes") {
+		console.error("Usage: diffing gh pr-review --decision <approve|comment|request-changes> [--body <text>] [--dry-run]");
+		return EXIT_USAGE;
+	}
+	const base = baseUrl();
+	const payload = {
+		decision,
+		body: values.body ?? "",
+		dryRun: values["dry-run"] === true
+	};
+	const res = await fetch(`${base}/api/gh/submit`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify(payload)
+	});
+	if (!res.ok) {
+		const err = await res.json().catch(() => ({}));
+		console.error(`Failed to submit review: ${err.error ?? res.statusText}`);
+		return 1;
+	}
+	const result = await res.json();
+	if (values.json) process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+	else if (result.ok) if (result.dryRun) console.log("Dry run OK — payload would have been accepted by GitHub.");
+	else console.log(`Review submitted via ${result.authSource}: ${result.reviewUrl ?? `#${result.reviewId}`}`);
+	else {
+		console.error(`Submit failed (auth=${result.authSource}): ${result.error ?? "unknown error"}`);
+		return 1;
+	}
+	return EXIT_OK;
+}
+async function runGhSubcommand(args) {
+	const action = args[0];
+	const rest = args.slice(1);
+	switch (action) {
+		case "status": return ghStatus();
+		case "pr-fetch": return ghPrFetch(rest);
+		case "pr-review": return ghPrReview(rest);
+		case "pr-list-comments": return ghPrListComments();
+		default:
+			console.error("Usage: diffing gh <status|pr-fetch|pr-review|pr-list-comments> [...]");
+			return EXIT_USAGE;
+	}
+}
+//#endregion
+export { runGhSubcommand };