feat: add PR diff, PR review, and structured error handling commands

README.md

@@ -9,13 +9,15 @@
 ## Features
 
 - Multi-instance support (works with any Forgejo instance)
-- Pull request management (create, list, view, merge)
+- Pull request management (create, list, view, merge, diff, comment, review)
 - Issue tracking (create, list, view, comment, close, labels)
 - Repository operations (view, list, create, clone, fork)
 - Forgejo Actions (workflow runs, watch/rerun/cancel, enable/disable, secrets, variables)
 - Releases (create, upload, delete)
+- Raw API access (`fgj api`) for arbitrary REST calls
 - Shell completions (bash, zsh, fish, PowerShell) and man pages
 - JSON output (`--json`) for all list/view commands
+- Structured JSON error output (`--json-errors`) for machine consumption
 - Automatic repository and hostname detection from git context
 - Secure authentication with personal access tokens
 - XDG Base Directory compliant config location
@@ -125,6 +127,33 @@ fgj pr create -t "PR Title" -b "PR Description" -H feature-branch -B main
 
 # Merge a pull request
 fgj pr merge 123 --merge-method squash
+
+# View PR diff
+fgj pr diff 123
+
+# View diff with color
+fgj pr diff 123 --color always
+
+# Show only changed file names
+fgj pr diff 123 --name-only
+
+# Show diffstat summary
+fgj pr diff 123 --stat
+
+# Comment on a pull request
+fgj pr comment 123 -b "Looks good, minor nit on line 42"
+
+# Comment from a file
+fgj pr comment 123 --body-file review-notes.md
+
+# Approve a pull request
+fgj pr review 123 --approve -b "LGTM"
+
+# Request changes
+fgj pr review 123 --request-changes -b "Please fix the error handling"
+
+# Submit a review comment (neither approve nor request changes)
+fgj pr review 123 --comment -b "Some observations"
 ```
 
 ### Issues
@@ -275,6 +304,31 @@ fgj actions variable update MY_VAR "new value"
 fgj actions variable delete MY_VAR
 ```
 
+### Raw API Access
+
+```bash
+# GET request (auto-detects owner/repo from git context)
+fgj api /repos/{owner}/{repo}/pulls
+
+# POST with fields
+fgj api /repos/{owner}/{repo}/issues -X POST -f title="Bug report" -f body="Description"
+
+# Explicit method and hostname
+fgj api /repos/myorg/myrepo/labels --hostname my-forgejo.example.com
+
+# Read request body from file
+fgj api /repos/{owner}/{repo}/issues -X POST --input issue.json
+
+# Read from stdin
+echo '{"title":"test"}' | fgj api /repos/{owner}/{repo}/issues -X POST --input -
+
+# Include response headers
+fgj api /repos/{owner}/{repo} -i
+
+# Suppress output (useful for DELETE)
+fgj api /repos/{owner}/{repo}/issues/123 -X DELETE --silent
+```
+
 ## Shell Completions and Man Pages
 
 ```bash
@@ -297,6 +351,23 @@ fgj issue view 456 --json
 fgj release list --json
 fgj actions run list --json
 fgj actions workflow view ci.yml --json
+
+# Get JSON output from PR comment/review
+fgj pr comment 123 -b "LGTM" --json
+fgj pr review 123 --approve -b "Ship it" --json
+```
+
+### Structured Error Output
+
+For machine consumption (ideal for AI agents and scripts), use `--json-errors` to get structured JSON errors on stderr:
+
+```bash
+# Errors are written to stderr as JSON
+fgj pr view 9999 --json-errors
+# stderr: {"error":{"code":"not_found","message":"...","status":404}}
+
+# Combine with --json for fully machine-readable I/O
+fgj pr list --json --json-errors
 ```
 
 ## Configuration
@@ -337,7 +408,7 @@ When working in a git repository, `fgj` automatically detects the Forgejo instan
 
 ## Use with AI Coding Agents
 
-`fgj` is designed to work seamlessly with AI coding agents like Claude Code. Common patterns:
+`fgj` is designed to work seamlessly with AI coding agents like Claude Code. Use `--json` and `--json-errors` for fully machine-readable I/O:
 
 ```bash
 # Create PR from agent's changes
@@ -348,13 +419,27 @@ fgj pr create -R owner/repo -t "feat: add new feature" -b "$(cat <<EOF
 
 Generated with AI assistance
 EOF
-)"
+)" --json
 
 # Check PR status during development
-fgj pr list -R owner/repo --state open
+fgj pr list -R owner/repo --state open --json
 
-# View PR details for review
-fgj pr view 123 -R owner/repo
+# Review a PR diff, then approve
+fgj pr diff 123
+fgj pr review 123 --approve -b "LGTM" --json
+
+# Post review feedback
+fgj pr comment 123 -b "Consider using a map here for O(1) lookup" --json
+
+# Request changes with detailed feedback
+fgj pr review 123 --request-changes --body-file feedback.md --json
+
+# Use raw API for anything not covered by commands
+fgj api /repos/{owner}/{repo}/topics --json-errors
+fgj api /repos/{owner}/{repo}/labels -X POST -f name=agent-reviewed -f color="#00ff00"
+
+# Fully machine-readable error handling
+fgj pr view 9999 --json --json-errors 2>errors.json
 ```
 
 ## Supported Forgejo Instances
@@ -376,8 +461,8 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 **Not Yet Implemented:**
 - `run delete` - Delete a workflow run
 - `run download` - Download workflow run artifacts
-- `pr checkout`, `pr close/reopen`, `pr comment`, `pr diff`
-- `pr review`, `pr checks`, `pr ready/draft`
+- `pr checkout`, `pr close/reopen`
+- `pr checks`, `pr ready/draft`
 - `issue reopen`, `issue assign`
 - `release edit`, `release download`, `release generate-notes`
 - `repo delete`, `repo rename`, `repo visibility`