hunkdiff 0.4.0 → 0.5.0

package/README.md

@@ -1,17 +1,17 @@
-# hunk
+<img width="384" height="384" alt="image" src="https://github.com/user-attachments/assets/85c5ba93-9de1-4757-87ae-4520b8fd659f" />
 
-<p align="center">
-  <a href="https://github.com/modem-dev/hunk/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/modem-dev/hunk/ci.yml?branch=main&style=for-the-badge&label=CI" alt="CI status"></a>
-  <a href="https://github.com/modem-dev/hunk/releases"><img src="https://img.shields.io/github/v/release/modem-dev/hunk?style=for-the-badge" alt="Latest release"></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
-</p>
+# hunk - TUI diff tool that's AI-friendly
 
-Hunk is a terminal diff viewer for reviewing agent-authored changesets with a desktop-style UI.
+[![CI status](https://img.shields.io/github/actions/workflow/status/modem-dev/hunk/ci.yml?branch=main&style=for-the-badge&label=CI)](https://github.com/modem-dev/hunk/actions/workflows/ci.yml?branch=main)
+[![Latest release](https://img.shields.io/github/v/release/modem-dev/hunk?style=for-the-badge)](https://github.com/modem-dev/hunk/releases)
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)
 
+Hunk is a desktop-inspired terminal diff viewer for reviewing agent-authored changesets.
+
+- AI annotations
 - full-screen multi-file review stream
+- keyboard & mouse support
 - split, stacked, and responsive auto layouts
-- keyboard and mouse navigation
-- optional agent rationale beside annotated hunks
 - Git pager and difftool integration
 
 ## Install
@@ -20,276 +20,153 @@ Hunk is a terminal diff viewer for reviewing agent-authored changesets with a de
 npm i -g hunkdiff
 ```
 
-## Requirements
+Requirements:
 
 - Node.js 18+
-- Git for `hunk diff`, `hunk show`, `hunk stash show`, and pager integration
+- Currently supported on macOS and Linux
+- Git is recommended for most workflows
 
-## Quick start
+## Usage
 
-Review your current working tree:
+### Basics
 
 ```bash
-hunk diff
+hunk           # show help
+hunk --version # get version
 ```
 
-Review staged changes:
+### Working with Git
 
 ```bash
+hunk diff         # review current repo changes
 hunk diff --staged
+hunk show         # review the latest commit
+hunk show HEAD~1  # review an earlier commit
 ```
 
-Review a commit:
+### Working with raw files/patches
 
 ```bash
-hunk show HEAD~1
+hunk diff before.ts after.ts        # compare two files directly
+git diff --no-color | hunk patch -  # review a patch from stdin
 ```
 
-Compare two files directly:
-
-```bash
-hunk diff before.ts after.ts
-```
+## Feature comparison
 
-Open a patch from stdin:
+| Capability                                                  | hunk | difftastic | delta | diff |
+| ----------------------------------------------------------- | ---- | ---------- | ----- | ---- |
+| Dedicated interactive review UI                             | ✅   | ❌         | ❌    | ❌   |
+| Multi-file review stream with navigation sidebar            | ✅   | ❌         | ❌    | ❌   |
+| Agent / AI rationale sidecar                                | ✅   | ❌         | ❌    | ❌   |
+| Split diffs                                                 | ✅   | ✅         | ✅    | ✅   |
+| Stacked diffs                                               | ✅   | ✅         | ✅    | ✅   |
+| Auto responsive layouts                                     | ✅   | ❌         | ❌    | ❌   |
+| Themes                                                      | ✅   | ❌         | ✅    | ❌   |
+| Syntax highlighting                                         | ✅   | ✅         | ✅    | ❌   |
+| Syntax-aware / structural diffing                           | ❌   | ✅         | ❌    | ❌   |
+| Mouse support inside the diff viewer                        | ✅   | ❌         | ❌    | ❌   |
+| Runtime toggles for wrapping / line numbers / hunk metadata | ✅   | ❌         | ❌    | ❌   |
+| Pager-compatible mode                                       | ✅   | ✅         | ✅    | ✅   |
 
-```bash
-git diff --no-color | hunk patch -
-```
+## Git integration
 
-## Feature comparison
+You can set Hunk as your Git pager so `git diff` and `git show` open in Hunk automatically.
 
-| Capability | hunk | difftastic | delta | diff |
-| --- | --- | --- | --- | --- |
-| Dedicated interactive review UI | ✅ | ❌ | ❌ | ❌ |
-| Multi-file review stream with navigation sidebar | ✅ | ❌ | ❌ | ❌ |
-| Agent / AI rationale sidecar | ✅ | ❌ | ❌ | ❌ |
-| Split diffs | ✅ | ✅ | ✅ | ✅ |
-| Stacked diffs | ✅ | ✅ | ✅ | ✅ |
-| Auto responsive layouts | ✅ | ❌ | ❌ | ❌ |
-| Themes | ✅ | ❌ | ✅ | ❌ |
-| Syntax highlighting | ✅ | ✅ | ✅ | ❌ |
-| Syntax-aware / structural diffing | ❌ | ✅ | ❌ | ❌ |
-| Mouse support inside the diff viewer | ✅ | ❌ | ❌ | ❌ |
-| Runtime toggles for wrapping / line numbers / hunk metadata | ✅ | ❌ | ❌ | ❌ |
-| Pager-compatible mode | ✅ | ✅ | ✅ | ✅ |
-
-## Benchmarks
-
-Quick local timing snapshot from one Linux machine on the same 120-line TypeScript file pair. Metric: time until a changed marker first became visible.
-
-| Tool | Avg first-visible changed output |
-| --- | ---: |
-| `diff` | ~37 ms |
-| `delta --paging=never` | ~35 ms |
-| `hunk diff` | ~219 ms |
-| `difft --display side-by-side` | ~266 ms |
-
-Takeaway:
-
-- `diff` and `delta` are fastest here because they print plain diff text and exit.
-- `hunk` spends more startup time on an interactive UI, syntax highlighting, navigation state, and optional agent context.
-- `difftastic` spends more startup time on structural diffing.
-
-## Common workflows
-
-- `hunk` — print CLI help
-- `hunk diff` — review working tree changes
-- `hunk diff --staged` / `hunk diff --cached` — review staged changes
-- `hunk diff <ref>` — review changes versus a branch, tag, or commit-ish
-- `hunk diff <ref1>..<ref2>` / `hunk diff <ref1>...<ref2>` — review Git ranges
-- `hunk diff -- <pathspec...>` — limit review to selected paths
-- `hunk show [ref]` — review the last commit or a specific ref
-- `hunk stash show [ref]` — review a stash entry
-- `hunk patch [file|-]` — review a patch file or stdin
-- `hunk pager` — act as a Git pager wrapper, opening Hunk for diff-like stdin and falling back to plain text paging otherwise
-- `hunk difftool <left> <right> [path]` — integrate with Git difftool
-- `hunk mcp serve` — run the local MCP daemon for agent-to-diff communication
-
-## MCP daemon (experimental)
-
-Hunk can run a local MCP daemon that brokers commands to live Hunk TUI sessions.
-
-Opening a normal Hunk review session now tries to register with the daemon automatically and will auto-start it on loopback when needed. You can still run the daemon explicitly:
+From the terminal:
 
 ```bash
-hunk mcp serve
+git config --global core.pager "hunk pager"
 ```
 
-Current v1 scope:
-
-- local loopback daemon only
-- live session discovery via `list_sessions` / `get_session`
-- inline diff comments via `comment`
-- Linux-first implementation, designed to stay portable to macOS later
-
-Environment variables:
+Or in your Git config:
 
-- `HUNK_MCP_HOST` — bind host for the daemon and session clients, default `127.0.0.1`
-- `HUNK_MCP_PORT` — bind port for the daemon and session clients, default `47657`
-- `HUNK_MCP_DISABLE=1` — disable background session registration for one Hunk process
-
-## Interaction
-
-- `1` split view
-- `2` stacked view
-- `0` auto layout
-- `t` cycle themes
-- `a` toggle the agent panel
-- `l` toggle line numbers
-- `w` toggle line wrapping
-- `m` toggle hunk metadata
-- `[` / `]` move between hunks
-- `space` / `b` page forward and backward
-- `/` focus the file filter
-- `tab` cycle focus regions
-- `q` or `Esc` quit
-
-## Git integration
+```ini
+[core]
+    pager = hunk pager
+```
 
-Use Hunk directly for full-screen review:
+If you’d rather keep Git’s default `diff` and `show` behavior, you can add optional aliases instead:
 
 ```bash
-hunk diff
-hunk diff --staged
-hunk diff main...feature
-hunk show
-hunk stash show
+git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
+git config --global alias.hshow "-c core.pager=\"hunk pager\" show"
 ```
 
-Use Hunk as a pager for `git diff` and `git show`:
+## Examples
 
-```bash
-git config --global core.pager 'hunk patch -'
-```
+Ready-to-run demo diffs live in [`examples/`](examples/README.md).
 
-Or scope it just to diff/show:
+Each example includes the exact command to run from the repository root.
 
-```bash
-git config --global pager.diff 'hunk patch -'
-git config --global pager.show 'hunk patch -'
-```
+## Agent skill
 
-Use Hunk as a Git difftool:
+Hunk ships a bundled agent skill named `hunk-review` in `skills/hunk-review/SKILL.md`.
 
-```bash
-git config --global diff.tool hunk
-git config --global difftool.hunk.cmd 'hunk difftool "$LOCAL" "$REMOTE" "$MERGED"'
-```
+It is written as a self-contained skill for skill-aware coding agents. The skill teaches an agent to:
+
+- briefly explain what Hunk is
+- prefer `hunk session ...` when a live Hunk review window already exists
+- inspect current review focus before navigating blindly
+- use `hunk session reload` to swap what an existing live session is showing
+- leave concise inline review comments tied to real diff lines
 
-## Configuration
+If your coding agent supports packaged or repo-local skills, point it at this repository or copy the `skills/hunk-review/` directory into that agent's skill search path.
 
-Hunk reads layered TOML config with this precedence:
+## Config
 
-1. built-in defaults
-2. global config: `$XDG_CONFIG_HOME/hunk/config.toml` or `~/.config/hunk/config.toml`
-3. repo-local config: `.hunk/config.toml`
-4. command-specific sections like `[diff]`, `[show]`, `[stash-show]`, `[patch]`, `[difftool]`
-5. `[pager]` when Hunk is running in pager mode
-6. explicit CLI flags
+Hunk reads config from:
+
+- `~/.config/hunk/config.toml`
+- `.hunk/config.toml`
 
 Example:
 
 ```toml
-theme = "midnight"
-mode = "auto"
+theme = "graphite" # graphite, midnight, paper, ember
+mode = "auto"      # auto, split, stack
 line_numbers = true
 wrap_lines = false
-hunk_headers = true
 agent_notes = false
-
-[pager]
-mode = "stack"
-line_numbers = false
-
-[diff]
-mode = "split"
-```
-
-Supported one-off CLI overrides:
-
-- `--mode <auto|split|stack>`
-- `--theme <theme>`
-- `--line-numbers` / `--no-line-numbers`
-- `--wrap` / `--no-wrap`
-- `--hunk-headers` / `--no-hunk-headers`
-- `--agent-notes` / `--no-agent-notes`
-
-## Agent context sidecar
-
-Use `--agent-context <file>` to load a JSON sidecar and show agent rationale next to the diff.
-
-The order of `files` in the sidecar is significant. Hunk uses that order for the sidebar and the main review stream so an agent can present a review narrative instead of raw patch order.
-
-```json
-{
-  "version": 1,
-  "summary": "High-level change summary from the agent.",
-  "files": [
-    {
-      "path": "src/core/loaders.ts",
-      "summary": "Normalizes git and patch inputs into one changeset model.",
-      "annotations": [
-        {
-          "newRange": [120, 156],
-          "summary": "Adds the patch loader entrypoint.",
-          "rationale": "Keeps all diff sources flowing through one normalized shape.",
-          "tags": ["parser", "architecture"],
-          "confidence": "high"
-        }
-      ]
-    }
-  ]
-}
 ```
 
-For local agent-driven review, keep a transient sidecar at `.hunk/latest.json` and load it with:
-
-```bash
-hunk diff --agent-context .hunk/latest.json
-```
+## Advanced workflows
 
-## Development
+- `hunk diff --agent-context <file>` loads inline agent rationale from a JSON sidecar
+- `hunk mcp serve` runs the local Hunk session daemon and websocket broker for manual startup or debugging
+  - normal Hunk sessions auto-start/register with it by default
+  - coding agents should usually interact through `hunk session ...`, not by managing the daemon directly
+  - Hunk keeps the daemon loopback-only by default
+  - if you intentionally need remote access, set `HUNK_MCP_UNSAFE_ALLOW_REMOTE=1` and choose a non-loopback `HUNK_MCP_HOST`
 
-Install dependencies:
+### Live session control CLI
 
-```bash
-bun install
-```
+`hunk session ...` is the user-facing and agent-facing interface to Hunk's local live review session daemon.
 
-Validate a change:
+Use explicit session targeting with either a live `<session-id>` or `--repo <path>` when exactly one live session matches that repo root.
 
 ```bash
-bun run typecheck
-bun test
-bun run test:tty-smoke
+hunk session list
+hunk session context --repo .
+hunk session navigate --repo . --file README.md --hunk 2
+hunk session reload --repo . -- diff
+hunk session reload --repo . -- show HEAD~1 -- README.md
+hunk session comment add --repo . --file README.md --new-line 103 --summary "Frame this as MCP-first"
+hunk session comment list --repo .
+hunk session comment rm --repo . <comment-id>
+hunk session comment clear --repo . --file README.md --yes
 ```
 
-Build the npm runtime bundle used for publishing:
-
-```bash
-bun run build:npm
-bun run check:pack
-```
+`hunk session reload ... -- <hunk command>` swaps the live session to a new `diff`, `show`, or other reviewable Hunk input without opening a new TUI window.
 
-Stage the prebuilt npm packages for the current host and smoke test the install path without Bun on `PATH`:
+The session CLI can inspect, navigate, annotate, and reload a live session, but it does not edit `.hunk/latest.json`.
 
-```bash
-bun run build:prebuilt:npm
-bun run check:prebuilt-pack
-bun run smoke:prebuilt-install
-```
+## Performance notes
 
-Prepare the multi-platform release directories from downloaded build artifacts and dry-run the publish order:
+Hunk spends more startup time than plain diff output tools because it launches an interactive UI with syntax highlighting, navigation state, and optional agent context. In exchange, it is optimized for reviewing a full changeset instead of printing static diff text and exiting.
 
-```bash
-bun run build:prebuilt:artifact
-bun run stage:prebuilt:release
-bun run check:prebuilt-pack
-bun run publish:prebuilt:npm -- --dry-run
-```
+## Contributing
 
-The automated tag/manual release workflow lives in `.github/workflows/release-prebuilt-npm.yml`.
+For source setup, tests, packaging checks, and repo architecture, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/bin/hunk.cjs

@@ -111,7 +111,9 @@ if (bunBinary) {
   run(bunBinary, [entrypoint, ...process.argv.slice(2)]);
 }
 
-const printablePackages = hostCandidates().map((candidate) => `"${candidate.packageName}"`).join(" or ");
+const printablePackages = hostCandidates()
+  .map((candidate) => `"${candidate.packageName}"`)
+  .join(" or ");
 console.error(
   printablePackages.length > 0
     ? `Failed to locate a matching prebuilt Hunk binary. Try reinstalling hunkdiff or manually installing ${printablePackages}.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hunkdiff",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Desktop-inspired terminal diff viewer for understanding agent-authored changesets.",
   "bin": {
     "hunk": "./bin/hunk.cjs"
@@ -11,12 +11,12 @@
     "LICENSE"
   ],
   "keywords": [
+    "ai",
+    "code-review",
     "diff",
     "git",
-    "tui",
     "terminal",
-    "code-review",
-    "ai"
+    "tui"
   ],
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "hunkdiff-darwin-arm64": "0.4.0",
-    "hunkdiff-darwin-x64": "0.4.0",
-    "hunkdiff-linux-x64": "0.4.0"
+    "hunkdiff-darwin-arm64": "0.5.0",
+    "hunkdiff-darwin-x64": "0.5.0",
+    "hunkdiff-linux-x64": "0.5.0"
   },
   "license": "MIT",
   "publishConfig": {