feat: add general Git pager wrapper

Author: benvinegar

README.md

@@ -50,6 +50,7 @@ If you want a different install location, set `HUNK_INSTALL_DIR` before running
 - `hunk stash show [ref]` — review a stash entry in the full Hunk UI
 - `hunk diff <left> <right>` — compare two concrete files directly
 - `hunk patch [file|-]` — review a patch file or stdin, including pager mode
+- `hunk pager` — act as a general Git pager wrapper, opening Hunk for diff-like stdin and falling back to normal text paging otherwise
 - `hunk difftool <left> <right> [path]` — integrate with Git difftool
 - `hunk git [range]` — legacy alias for the original Git-style diff entrypoint
 
@@ -262,3 +263,9 @@ If you want Git to launch Hunk as a difftool for file-to-file comparisons:
 git config --global diff.tool hunk
 git config --global difftool.hunk.cmd 'hunk difftool "$LOCAL" "$REMOTE" "$MERGED"'
 ```
+e comparisons:
+
+```bash
+git config --global diff.tool hunk
+git config --global difftool.hunk.cmd 'hunk difftool "$LOCAL" "$REMOTE" "$MERGED"'
+```

src/core/cli.ts

@@ -1,6 +1,6 @@
 import { existsSync, statSync } from "node:fs";
 import { Command } from "commander";
-import type { CliInput, CommonOptions, LayoutMode, ParsedCliInput } from "./types";
+import type { CommonOptions, HelpCommandInput, LayoutMode, PagerCommandInput, ParsedCliInput } from "./types";
 
 /** Validate one requested layout mode from CLI input. */
 function parseLayoutMode(value: string): LayoutMode {
@@ -82,6 +82,7 @@ function renderCliHelp() {
     "  hunk show [ref] [-- <pathspec...>]      review the last commit or a given ref",
     "  hunk stash show [ref]                   review a stash entry",
     "  hunk patch [file]                       review a patch file or stdin",
+    "  hunk pager                              general Git pager wrapper with diff detection",
     "  hunk difftool <left> <right> [path]     review Git difftool file pairs",
     "  hunk git [range]                        legacy alias for git diff-style review",
     "",
@@ -97,6 +98,7 @@ function renderCliHelp() {
     "  hunk show HEAD~1",
     "  hunk show abc123 -- README.md",
     "  hunk patch -",
+    "  hunk pager",
     "",
   ].join("\n");
 }
@@ -120,15 +122,14 @@ function areExistingFiles(left: string, right: string) {
 }
 
 /** Parse one standalone command while letting us capture `--help` as plain text. */
-async function parseStandaloneCommand<T>(command: Command, tokens: string[]): Promise<T | null> {
+async function parseStandaloneCommand(command: Command, tokens: string[]) {
   command.exitOverride();
 
   try {
     await command.parseAsync(["bun", "hunk", ...tokens]);
-    return null;
   } catch (error) {
     if (error && typeof error === "object" && "code" in error && error.code === "commander.helpDisplayed") {
-      return null;
+      return;
     }
 
     throw error;
@@ -282,6 +283,27 @@ async function parsePatchCommand(tokens: string[], argv: string[]): Promise<Pars
   };
 }
 
+/** Parse the general pager wrapper command used from Git `core.pager`. */
+async function parsePagerCommand(tokens: string[], argv: string[]): Promise<PagerCommandInput | HelpCommandInput> {
+  const command = createCommand("pager", "general Git pager wrapper with diff detection");
+  let parsedOptions: Record<string, unknown> = {};
+
+  command.action((options: Record<string, unknown>) => {
+    parsedOptions = options;
+  });
+
+  if (tokens.includes("--help") || tokens.includes("-h")) {
+    return { kind: "help", text: `${command.helpInformation().trimEnd()}\n` };
+  }
+
+  await parseStandaloneCommand(command, tokens);
+
+  return {
+    kind: "pager",
+    options: buildCommonOptions(parsedOptions, argv),
+  };
+}
+
 /** Parse Git difftool-style two-file review commands. */
 async function parseDifftoolCommand(tokens: string[], argv: string[]): Promise<ParsedCliInput> {
   const command = createCommand("difftool", "review Git difftool file pairs")
@@ -379,6 +401,8 @@ export async function parseCli(argv: string[]): Promise<ParsedCliInput> {
       return parseGitCommand(rest, argv);
     case "patch":
       return parsePatchCommand(rest, argv);
+    case "pager":
+      return parsePagerCommand(rest, argv);
     case "difftool":
       return parseDifftoolCommand(rest, argv);
     case "stash":

src/core/loaders.ts

@@ -329,9 +329,10 @@ async function loadStashShowChangeset(input: StashShowCommandInput, agentContext
 /** Build a changeset from patch text supplied by file or stdin. */
 async function loadPatchChangeset(input: PatchCommandInput, agentContext: AgentContext | null) {
   const patchText =
-    !input.file || input.file === "-"
+    input.text ??
+    (!input.file || input.file === "-"
       ? await new Response(Bun.stdin.stream()).text()
-      : await Bun.file(input.file).text();
+      : await Bun.file(input.file).text());
 
   const label = input.file && input.file !== "-" ? input.file : "stdin patch";
   return normalizePatchChangeset(patchText, `Patch review: ${basename(label)}`, label, agentContext);

src/core/pager.ts

@@ -0,0 +1,55 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+
+/** Remove terminal escape sequences before deciding whether stdin looks like a patch. */
+function stripTerminalControl(text: string) {
+  return text
+    .replace(/\x1bP[\s\S]*?\x1b\\/g, "")
+    .replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)/g, "")
+    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/\x1b[@-_]/g, "");
+}
+
+/** Detect whether generic pager stdin looks like a diff/patch that Hunk should review. */
+export function looksLikePatchInput(text: string) {
+  const normalized = stripTerminalControl(text.replaceAll("\r\n", "\n"));
+
+  return (
+    /^diff --git /m.test(normalized) ||
+    (/^--- /m.test(normalized) && /^\+\+\+ /m.test(normalized)) ||
+    /^@@ /m.test(normalized)
+  );
+}
+
+/** Choose a plain-text pager command while avoiding recursive `hunk pager` launches. */
+export function resolveTextPagerCommand(env: NodeJS.ProcessEnv = process.env) {
+  const candidate = env.HUNK_TEXT_PAGER ?? env.PAGER;
+
+  if (!candidate || /(^|\s)hunk(\s|$)/.test(candidate)) {
+    return "less -R";
+  }
+
+  return candidate;
+}
+
+/** Stream plain text through a normal pager, or write directly when not attached to a terminal. */
+export async function pagePlainText(text: string, env: NodeJS.ProcessEnv = process.env) {
+  if (!process.stdout.isTTY) {
+    process.stdout.write(text);
+    return;
+  }
+
+  const pagerCommand = resolveTextPagerCommand(env);
+  const pager = spawn(pagerCommand, {
+    shell: true,
+    stdio: ["pipe", "inherit", "inherit"],
+    env,
+  });
+
+  pager.stdin?.end(text);
+  const [, code] = await once(pager, "close");
+
+  if (typeof code === "number" && code !== 0) {
+    throw new Error(`Pager command failed: ${pagerCommand}`);
+  }
+}

src/core/types.ts

@@ -71,6 +71,11 @@ export interface HelpCommandInput {
   text: string;
 }
 
+export interface PagerCommandInput {
+  kind: "pager";
+  options: CommonOptions;
+}
+
 export interface GitCommandInput {
   kind: "git";
   range?: string;
@@ -102,6 +107,7 @@ export interface FileCommandInput {
 export interface PatchCommandInput {
   kind: "patch";
   file?: string;
+  text?: string;
   options: CommonOptions;
 }
 
@@ -121,7 +127,7 @@ export type CliInput =
   | PatchCommandInput
   | DiffToolCommandInput;
 
-export type ParsedCliInput = CliInput | HelpCommandInput;
+export type ParsedCliInput = CliInput | HelpCommandInput | PagerCommandInput;
 
 export interface AppBootstrap {
   input: CliInput;

src/main.tsx

@@ -5,17 +5,37 @@ import { createRoot } from "@opentui/react";
 import { parseCli } from "./core/cli";
 import { persistViewPreferences, resolveConfiguredCliInput } from "./core/config";
 import { loadAppBootstrap } from "./core/loaders";
+import { looksLikePatchInput, pagePlainText } from "./core/pager";
 import { shutdownSession } from "./core/shutdown";
 import { openControllingTerminal, resolveRuntimeCliInput, usesPipedPatchInput } from "./core/terminal";
 import { App } from "./ui/App";
 
-const parsedCliInput = await parseCli(process.argv);
+let parsedCliInput = await parseCli(process.argv);
 
 if (parsedCliInput.kind === "help") {
   process.stdout.write(parsedCliInput.text);
   process.exit(0);
 }
 
+if (parsedCliInput.kind === "pager") {
+  const stdinText = await new Response(Bun.stdin.stream()).text();
+
+  if (!looksLikePatchInput(stdinText)) {
+    await pagePlainText(stdinText);
+    process.exit(0);
+  }
+
+  parsedCliInput = {
+    kind: "patch",
+    file: "-",
+    text: stdinText,
+    options: {
+      ...parsedCliInput.options,
+      pager: true,
+    },
+  };
+}
+
 const runtimeCliInput = resolveRuntimeCliInput(parsedCliInput);
 const configured = resolveConfiguredCliInput(runtimeCliInput);
 const cliInput = configured.input;

test/cli.test.ts

@@ -124,6 +124,17 @@ describe("parseCli", () => {
     });
   });
 
+  test("parses general pager mode", async () => {
+    const parsed = await parseCli(["bun", "hunk", "pager", "--theme", "paper"]);
+
+    expect(parsed).toMatchObject({
+      kind: "pager",
+      options: {
+        theme: "paper",
+      },
+    });
+  });
+
   test("parses stash show mode", async () => {
     const parsed = await parseCli(["bun", "hunk", "stash", "show", "stash@{1}"]);
 

test/help-output.test.ts

@@ -17,6 +17,27 @@ describe("CLI help output", () => {
     expect(stdout).toContain("Usage:");
     expect(stdout).toContain("hunk diff");
     expect(stdout).toContain("hunk show");
+    expect(stdout).toContain("hunk pager");
+    expect(stdout).not.toContain("\u001b[?1049h");
+  });
+
+  test("general pager mode falls back to plain text for non-diff stdin", () => {
+    const proc = Bun.spawnSync(["bash", "-lc", "printf '* main\\n  feature/demo\\n' | HUNK_TEXT_PAGER=cat bun run src/main.tsx pager"], {
+      cwd: process.cwd(),
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+      env: process.env,
+    });
+
+    const stdout = Buffer.from(proc.stdout).toString("utf8");
+    const stderr = Buffer.from(proc.stderr).toString("utf8");
+
+    expect(proc.exitCode).toBe(0);
+    expect(stderr).toBe("");
+    expect(stdout).toContain("* main");
+    expect(stdout).toContain("feature/demo");
+    expect(stdout).not.toContain("View  Navigate  Theme  Agent  Help");
     expect(stdout).not.toContain("\u001b[?1049h");
   });
 });

test/pager.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { looksLikePatchInput } from "../src/core/pager";
+
+describe("general pager detection", () => {
+  test("detects git-style patch input even when ANSI-colored", () => {
+    const patch = [
+      "\u001b[1mdiff --git a/src/example.ts b/src/example.ts\u001b[m",
+      "index 1111111..2222222 100644",
+      "--- a/src/example.ts",
+      "+++ b/src/example.ts",
+      "@@ -1 +1,2 @@",
+      "-export const value = 1;",
+      "+export const value = 2;",
+      "+export const extra = true;",
+    ].join("\n");
+
+    expect(looksLikePatchInput(patch)).toBe(true);
+  });
+
+  test("does not misclassify plain git pager text as a patch", () => {
+    const branchOutput = ["* main", "  feat/persist-view-config", "  release/0.1.0"].join("\n");
+
+    expect(looksLikePatchInput(branchOutput)).toBe(false);
+  });
+});

test/tty-render-smoke.test.ts

@@ -137,10 +137,11 @@ async function runTtySmoke(options: { mode?: "split" | "stack"; pager?: boolean;
   return stripTerminalControl(await Bun.file(transcript).text());
 }
 
-async function runStdinPagerSmoke(options?: { input?: string; inputCommand?: string; lines?: number }) {
+async function runStdinPagerSmoke(options?: { input?: string; inputCommand?: string; lines?: number; command?: "patch" | "pager" }) {
   const fixture = createFixtureFiles(options?.lines ?? 1);
   const transcript = join(fixture.dir, "stdin-pager-transcript.txt");
-  const patchCommand = `cat ${shellQuote(fixture.coloredPatch)} | bun run src/main.tsx patch -`;
+  const subcommand = options?.command === "pager" ? "pager" : "patch -";
+  const patchCommand = `cat ${shellQuote(fixture.coloredPatch)} | bun run src/main.tsx ${subcommand}`;
   const scriptCommand = `timeout 5 script -q -f -e -c ${shellQuote(patchCommand)} ${shellQuote(transcript)}`;
   const inputCommand = options?.inputCommand ?? `(sleep 1; printf ${shellQuote(options?.input ?? "q")})`;
   const proc = Bun.spawnSync(["bash", "-lc", `${inputCommand} | ${scriptCommand}`], {
@@ -235,4 +236,17 @@ describe("TTY render smoke", () => {
     expect(output).toContain("before_23");
     expect(output).toContain("after_06");
   });
+
+  test("general pager mode opens Hunk pager UI for diff-like stdin", async () => {
+    if (!ttyToolsAvailable) {
+      return;
+    }
+
+    const output = await runStdinPagerSmoke({ command: "pager" });
+
+    expect(output).not.toContain("View  Navigate  Theme  Agent  Help");
+    expect(output).toContain("after.ts");
+    expect(output).toContain("@@ -1 +1,2 @@");
+    expect(output).toContain("export const answer = 42;");
+  });
 });