hunkdiff 0.9.4-beta.0 → 0.9.4

package/README.md

@@ -67,9 +67,20 @@ git diff --no-color | hunk patch -          # review a patch from stdin
 
 ### Working with agents
 
-Load the [`skills/hunk-review/SKILL.md`](skills/hunk-review/SKILL.md) skill in your coding agent (e.g. Claude, Codex, Opencode, Pi).
+1. Open Hunk in another terminal with `hunk diff` or `hunk show`.
+2. Load the Hunk review skill: [`skills/hunk-review/SKILL.md`](skills/hunk-review/SKILL.md).
+3. Ask your agent to use the skill against the live Hunk session.
 
-Open Hunk in another window, then ask your agent to leave comments.
+A good generic prompt is:
+
+```text
+Load the Hunk skill and use it for this review.
+```
+
+> [!NOTE]
+> `hunk skill path` lands in Hunk 0.10.0. Until that release is out, load the skill from the repo path above.
+
+For the full live-session and `--agent-context` workflow guide, see [docs/agent-workflows.md](docs/agent-workflows.md).
 
 ## Feature comparison
 
@@ -134,80 +145,11 @@ git config --global alias.hdiff "-c core.pager=\"hunk pager\" diff"
 git config --global alias.hshow "-c core.pager=\"hunk pager\" show"
 ```
 
-### Agent workflows
-
-Hunk supports two agent workflows:
-
-- steer a live Hunk window from another terminal with `hunk session ...` (recommended)
-- load agent comments from a file with `--agent-context`
-
-#### Steer a live Hunk window
-
-Use the Hunk review skill: [`skills/hunk-review/SKILL.md`](skills/hunk-review/SKILL.md).
-
-A good generic prompt is:
-
-```text
-> Load the Hunk skill and use it for this review
-```
-
-That skill teaches the agent how to inspect a live Hunk session, navigate it, reload it, and leave inline comments.
-
-#### How remote control works
-
-When a Hunk TUI starts, it registers with a local loopback daemon. `hunk session ...` talks to that daemon to find the right live window and control it.
-
-Use it to:
-
-- inspect the current review context
-- export the loaded review structure for agent workflows
-- optionally include raw patch text when an agent truly needs it
-- jump to a file, hunk, or line
-- reload the current window with a different `diff` or `show` command
-- add, batch-apply, list, and remove inline comments
-
-Most users only need `hunk session ...`. Use `hunk mcp serve` only for manual startup or debugging of the local daemon.
-
-```bash
-hunk session list
-hunk session get --repo .
-hunk session context --repo .
-hunk session review --repo . --json
-hunk session review --repo . --include-patch --json
-hunk session navigate --repo . --file README.md --hunk 2
-hunk session reload --repo . -- diff
-hunk session reload --repo /path/to/worktree -- diff
-hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff
-hunk session reload --repo . -- show HEAD~1 -- README.md
-hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording"
-hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" --focus
-printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin
-printf '%s\n' '{"comments":[{"filePath":"README.md","hunk":2,"summary":"Explain this hunk"}]}' | hunk session comment apply --repo . --stdin --focus
-hunk session comment list --repo .
-hunk session comment rm --repo . <comment-id>
-hunk session comment clear --repo . --file README.md --yes
-```
-
-`hunk session review --json` returns file and hunk structure by default. Add `--include-patch` only when a caller truly needs raw unified diff text in the response.
-
-`hunk session reload ... -- <hunk command>` swaps what a live session is showing without opening a new TUI window.
-Pass `--focus` to jump the live session to the new note, or to the first note in a batch apply.
-
-`hunk session comment apply` reads one stdin JSON object with a top-level `comments` array. Each item needs `filePath`, `summary`, and exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine`.
+### OpenTUI component
 
-- `--repo <path>` selects the live session by its current loaded repo root.
-- `--source <path>` is reload-only: it changes where the nested `diff` / `show` command runs, but does not select the session.
-- For normal worktree use, prefer targeting the worktree session directly with `hunk session reload --repo /path/to/worktree -- diff`.
-- Use `--session-path` + `--source` only for advanced cases where you want to repoint an already-open live window to another checkout or path.
+Hunk also publishes `HunkDiffView` from `hunkdiff/opentui` for embedding the same diff renderer in your own OpenTUI app.
 
-#### Load agent comments from a file
-
-Use `--agent-context` to attach agent-written comments or rationale from a JSON sidecar file. For a compact real example, see [`examples/3-agent-review-demo/agent-context.json`](examples/3-agent-review-demo/agent-context.json).
-
-```bash
-hunk diff --agent-context notes.json
-hunk patch change.patch --agent-context notes.json
-```
+See [docs/opentui-component.md](docs/opentui-component.md) for install, API, and runnable examples.
 
 ## Examples
 

package/bin/hunk.cjs

@@ -5,6 +5,10 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 
+function bundledSkillPath() {
+  return path.join(__dirname, "..", "skills", "hunk-review", "SKILL.md");
+}
+
 function ensureExecutable(target) {
   if (process.platform === "win32") {
     return;
@@ -94,21 +98,33 @@ function bundledBunRuntime() {
   }
 }
 
+const forwardedArgs = process.argv.slice(2);
+if (forwardedArgs.length === 2 && forwardedArgs[0] === "skill" && forwardedArgs[1] === "path") {
+  const skillPath = bundledSkillPath();
+  if (!fs.existsSync(skillPath)) {
+    console.error(`hunk: could not locate the bundled Hunk review skill at ${skillPath}`);
+    process.exit(1);
+  }
+
+  process.stdout.write(`${skillPath}\n`);
+  process.exit(0);
+}
+
 const overrideBinary = process.env.HUNK_BIN_PATH;
 if (overrideBinary) {
-  run(overrideBinary, process.argv.slice(2));
+  run(overrideBinary, forwardedArgs);
 }
 
 const scriptDir = path.dirname(fs.realpathSync(__filename));
 const prebuiltBinary = findInstalledBinary(scriptDir);
 if (prebuiltBinary) {
-  run(prebuiltBinary, process.argv.slice(2));
+  run(prebuiltBinary, forwardedArgs);
 }
 
 const bunBinary = bundledBunRuntime();
 if (bunBinary) {
   const entrypoint = path.join(__dirname, "..", "dist", "npm", "main.js");
-  run(bunBinary, [entrypoint, ...process.argv.slice(2)]);
+  run(bunBinary, [entrypoint, ...forwardedArgs]);
 }
 
 const printablePackages = hostCandidates()

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "hunkdiff",
-  "version": "0.9.4-beta.0",
+  "version": "0.9.4",
   "description": "Desktop-inspired terminal diff viewer for understanding agent-authored changesets.",
   "bin": {
     "hunk": "./bin/hunk.cjs"
   },
   "files": [
     "bin",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -30,10 +31,10 @@
     "node": ">=18"
   },
   "optionalDependencies": {
-    "hunkdiff-darwin-arm64": "0.9.4-beta.0",
-    "hunkdiff-darwin-x64": "0.9.4-beta.0",
-    "hunkdiff-linux-arm64": "0.9.4-beta.0",
-    "hunkdiff-linux-x64": "0.9.4-beta.0"
+    "hunkdiff-darwin-arm64": "0.9.4",
+    "hunkdiff-darwin-x64": "0.9.4",
+    "hunkdiff-linux-arm64": "0.9.4",
+    "hunkdiff-linux-x64": "0.9.4"
   },
   "license": "MIT",
   "publishConfig": {

package/skills/hunk-review/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: hunk-review
+description: Interacts with live Hunk diff review sessions via CLI. Inspects review focus, navigates files and hunks, reloads session contents, and adds inline review comments. Use when the user has a Hunk session running or wants to review diffs interactively.
+---
+
+# Hunk Review
+
+Hunk is an interactive terminal diff viewer. The TUI is for the user -- do NOT run `hunk diff`, `hunk show`, or other interactive commands directly. Use `hunk session *` CLI commands to inspect and control live sessions through the local daemon.
+
+If no session exists, ask the user to launch Hunk in their terminal first.
+
+## Workflow
+
+```text
+1. hunk session list                                    # find live sessions
+2. hunk session get --repo .                            # inspect path / repo / source
+3. hunk session review --repo . --json                  # inspect file/hunk structure first
+4. hunk session review --repo . --include-patch --json  # opt into raw diff text only when needed
+5. hunk session context --repo .                        # check current focus when needed
+6. hunk session navigate ...                            # move to the right place
+7. hunk session reload -- <command>                     # swap contents if needed
+8. hunk session comment add ...                         # leave one review note
+9. hunk session comment apply ...                       # apply many agent notes in one stdin batch
+```
+
+## Session selection
+
+Most session commands accept:
+
+- `--repo <path>` -- match the live session by its current loaded repo root (most common)
+- `<session-id>` -- match by exact ID (use when multiple sessions share a repo)
+- If only one session exists, it auto-resolves
+
+`reload` also supports:
+
+- `--session-path <path>` -- match the live Hunk window by its current working directory
+- `--source <path>` -- load the replacement `diff` / `show` command from a different directory
+
+Use `--source` only for advanced reloads where the live session you want to control is not already associated with the checkout you want to load next. For a normal worktree session, prefer selecting it directly with `--repo /path/to/worktree`.
+
+## Commands
+
+### Inspect
+
+```bash
+hunk session list [--json]
+hunk session get (--repo . | <id>) [--json]
+hunk session context (--repo . | <id>) [--json]
+hunk session review (--repo . | <id>) [--json] [--include-patch]
+```
+
+- `get` shows the session `Path`, `Repo`, and `Source`, which helps when choosing between `--repo` and `--session-path`
+- `Repo` is what `--repo` matches; `Path` is what `--session-path` matches
+- `review --json` returns file and hunk structure by default; add `--include-patch` only when a caller truly needs raw unified diff text
+
+### Navigate
+
+Absolute navigation requires `--file` and exactly one of `--hunk`, `--new-line`, or `--old-line`:
+
+```bash
+hunk session navigate --repo . --file src/App.tsx --hunk 2
+hunk session navigate --repo . --file src/App.tsx --new-line 372
+hunk session navigate --repo . --file src/App.tsx --old-line 355
+```
+
+Relative comment navigation jumps between annotated hunks and does not require `--file`:
+
+```bash
+hunk session navigate --repo . --next-comment
+hunk session navigate --repo . --prev-comment
+```
+
+- `--hunk <n>` is 1-based
+- `--new-line` / `--old-line` are 1-based line numbers on that diff side
+- Use either `--next-comment` or `--prev-comment`, not both
+
+### Reload
+
+Swaps the live session's contents. Pass a Hunk review command after `--`:
+
+```bash
+hunk session reload --repo . -- diff
+hunk session reload --repo . -- diff main...feature -- src/ui
+hunk session reload --repo . -- show HEAD~1
+hunk session reload --repo . -- show HEAD~1 -- README.md
+hunk session reload --repo /path/to/worktree -- diff
+hunk session reload --session-path /path/to/live-window --source /path/to/other-checkout -- diff
+```
+
+- Always include `--` before the nested Hunk command
+- `--repo` or `<session-id>` usually selects the session you want
+- `--source` is advanced: it does not select the session; it only changes where the replacement review command runs
+- If the live session is already showing the target worktree, prefer `hunk session reload --repo /path/to/worktree -- diff`
+- `--session-path` targets the live window when you need to keep session selection separate from reload source
+
+### Comments
+
+```bash
+hunk session comment add --repo . --file README.md --new-line 103 --summary "Tighten this wording" [--rationale "..."] [--author "agent"] [--focus]
+printf '%s\n' '{"comments":[{"filePath":"README.md","newLine":103,"summary":"Tighten this wording"}]}' | hunk session comment apply --repo . --stdin [--focus]
+hunk session comment list --repo . [--file README.md]
+hunk session comment rm --repo . <comment-id>
+hunk session comment clear --repo . --yes [--file README.md]
+```
+
+- `comment add` is best for one note; `comment apply` is best when an agent already has several notes ready
+- `comment add` requires `--file`, `--summary`, and exactly one of `--old-line` or `--new-line`
+- `comment apply` payload items require `filePath`, `summary`, and exactly one target such as `hunk`, `hunkNumber`, `oldLine`, or `newLine`
+- `comment apply` reads a JSON batch from stdin and validates the full batch before mutating the live session
+- Pass `--focus` when you want to jump to the new note or the first note in a batch
+- `comment list` and `comment clear` accept optional `--file`
+- Quote `--summary` and `--rationale` defensively in the shell
+
+## New files in working-tree reviews
+
+`hunk diff` includes untracked files by default. If the user wants tracked changes only, reload with `--exclude-untracked`:
+
+```bash
+hunk session reload --repo . -- diff --exclude-untracked
+```
+
+## Guiding a review
+
+The user may ask you to walk them through a changeset or review code using Hunk. Start with `hunk session review --json` to understand the file/hunk structure without inflating agent context, then use `--include-patch` only for the files you truly need to read in raw diff form. Use `context` and `navigate` to line up the user's current view before adding comments.
+
+Your role is to narrate: steer the user's view to what matters and leave comments that explain what they're looking at.
+
+Typical flow:
+
+1. Load the right content (`reload` if needed)
+2. Navigate to the first interesting file / hunk
+3. Add a comment explaining what's happening and why
+4. If you already have several notes ready, prefer one `comment apply` batch over many separate shell invocations
+5. Summarize when done
+
+Guidelines:
+
+- Work in the order that tells the clearest story, not necessarily file order
+- Navigate before commenting so the user sees the code you're discussing
+- Use `comment apply` for agent-generated batches and `comment add` for one-off notes
+- Use `--focus` sparingly when the note itself should actively steer the review
+- Keep comments focused: intent, structure, risks, or follow-ups
+- Don't comment on every hunk -- highlight what the user wouldn't spot themselves
+
+## Common errors
+
+- **"No visible diff file matches ..."** -- the file is not in the loaded review. Check `context`, then `reload` if needed.
+- **"No active Hunk sessions"** -- ask the user to open Hunk in their terminal.
+- **"Multiple active sessions match"** -- pass `<session-id>` explicitly.
+- **"No active Hunk session matches session path ..."** -- for advanced split-path reloads, verify the live window `Path` via `hunk session get` or `list`, then use `--session-path`.
+- **"Pass the replacement Hunk command after `--`"** -- include `--` before the nested `diff` / `show` command.
+- **"Pass --stdin to read batch comments from stdin JSON."** -- `comment apply` only reads its batch payload from stdin.
+- **"Specify exactly one navigation target"** -- pick one of `--hunk`, `--old-line`, or `--new-line`.
+- **"Specify either --next-comment or --prev-comment, not both."** -- choose one comment-navigation direction.