diffback-review 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +144 -0
- package/dist/cli.js +1761 -0
- package/package.json +35 -0
package/README.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# diffback
|
|
2
|
+
|
|
3
|
+
A local web tool to review AI-generated code changes. Think GitHub PR reviews, but for uncommitted diffs in your terminal workflow.
|
|
4
|
+
|
|
5
|
+
Instead of manually reading `git diff` output and typing feedback into a chat, `diffback` gives you a visual interface to browse changes, mark files as viewed, leave comments on specific lines, and generate a structured feedback prompt you can paste directly into your AI agent.
|
|
6
|
+
|
|
7
|
+
## Why
|
|
8
|
+
|
|
9
|
+
When working with AI coding agents (Claude Code, Cursor, Copilot, etc.), the review loop is painful:
|
|
10
|
+
|
|
11
|
+
1. The AI makes changes across multiple files
|
|
12
|
+
2. You run `git diff` and scroll through walls of text
|
|
13
|
+
3. You mentally track what you've reviewed and what needs fixing
|
|
14
|
+
4. You type feedback into the chat, forgetting half of what you noticed
|
|
15
|
+
5. The AI applies fixes, and you start over -- re-reviewing files that didn't change
|
|
16
|
+
|
|
17
|
+
`diffback` fixes this by giving you a proper review interface with persistent state that survives between rounds.
|
|
18
|
+
|
|
19
|
+
## Features
|
|
20
|
+
|
|
21
|
+
- **Web UI on localhost** -- file list + diff viewer + comment panel, opens in your browser
|
|
22
|
+
- **Mark files as viewed** -- track your progress across many files
|
|
23
|
+
- **Line comments** -- click a line number to reference it, add text or code suggestions
|
|
24
|
+
- **General comments** -- feedback not tied to any file ("run the tests", "don't generate config files")
|
|
25
|
+
- **Inline comment display** -- comments appear as bubbles directly under the referenced line
|
|
26
|
+
- **Generate feedback prompt** -- one click to produce a structured markdown prompt, auto-copied to clipboard
|
|
27
|
+
- **Persistent state between rounds** -- files you viewed stay viewed if unchanged; modified files get flagged automatically
|
|
28
|
+
- **Auto-refresh** -- detects external file changes every 3 seconds without manual reload
|
|
29
|
+
- **Code fold/expand** -- hidden code between hunks shown as expandable sections
|
|
30
|
+
- **Keyboard shortcuts** -- `j/k` navigate files, `a` mark viewed, `c` comment, `g` generate feedback
|
|
31
|
+
|
|
32
|
+
## Requirements
|
|
33
|
+
|
|
34
|
+
- Node.js >= 24
|
|
35
|
+
- Git
|
|
36
|
+
|
|
37
|
+
## Install
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install -g diffback
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Or run directly with npx:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx diffback
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Usage
|
|
50
|
+
|
|
51
|
+
From any git repository with uncommitted changes:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
diffback
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
This starts a local server and opens your browser. Review the changes, add comments, then click **Generate Feedback** to get a prompt you can paste into your AI agent.
|
|
58
|
+
|
|
59
|
+
### Options
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
diffback [options]
|
|
63
|
+
|
|
64
|
+
--port <number> Port to use (default: 3847)
|
|
65
|
+
--help, -h Show help
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Keyboard shortcuts
|
|
69
|
+
|
|
70
|
+
| Key | Action |
|
|
71
|
+
|-----|--------|
|
|
72
|
+
| `j` / `k` | Next / previous file |
|
|
73
|
+
| `a` | Mark current file as viewed (advances to next) |
|
|
74
|
+
| `c` | Focus comment input |
|
|
75
|
+
| `g` | Generate feedback prompt |
|
|
76
|
+
| `Cmd+Enter` | Submit comment |
|
|
77
|
+
|
|
78
|
+
## How state works
|
|
79
|
+
|
|
80
|
+
Review state is stored in `.diffback-local-diffs/<branch_name>/state.json` inside the reviewed project. Add `.diffback-local-diffs` to your `.gitignore`.
|
|
81
|
+
|
|
82
|
+
Between review rounds:
|
|
83
|
+
|
|
84
|
+
- **File unchanged** since last review -- stays marked as viewed
|
|
85
|
+
- **File modified** since last review -- automatically flagged as "changed since review", status reset to pending
|
|
86
|
+
- **File no longer in diff** (reverted or committed) -- removed from state
|
|
87
|
+
- **"Finish Review"** button -- deletes all state for the current branch
|
|
88
|
+
|
|
89
|
+
## Generated feedback format
|
|
90
|
+
|
|
91
|
+
The output is designed to be token-efficient and easy for AI agents to parse:
|
|
92
|
+
|
|
93
|
+
```markdown
|
|
94
|
+
# Code Review Feedback
|
|
95
|
+
|
|
96
|
+
2 files need changes. 3 comments total.
|
|
97
|
+
|
|
98
|
+
## src/users/model.py
|
|
99
|
+
- L42: Handle the null case before accessing user.name
|
|
100
|
+
- L58: Use a dataclass instead
|
|
101
|
+
```
|
|
102
|
+
@dataclass
|
|
103
|
+
class UserProfile:
|
|
104
|
+
name: str
|
|
105
|
+
email: str
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## General
|
|
109
|
+
- Run the tests before finishing
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Tech stack
|
|
113
|
+
|
|
114
|
+
- **TypeScript + Node.js** -- single `cli.ts` file for the server (~400 lines)
|
|
115
|
+
- **Single HTML file** -- all CSS and JS inline, served from the server
|
|
116
|
+
- **Node built-in `http`** -- no Express or framework dependencies
|
|
117
|
+
- **diff2html** -- diff rendering (loaded via CDN)
|
|
118
|
+
- **Solarized Dark theme** -- designed for accessibility
|
|
119
|
+
|
|
120
|
+
## Development
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
git clone https://github.com/verabravo/diffback.git
|
|
124
|
+
cd diffback
|
|
125
|
+
npm install
|
|
126
|
+
npm run build
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Test against any repo with uncommitted changes:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
cd /path/to/your/project
|
|
133
|
+
node /path/to/diffback/dist/cli.js
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Watch mode for development:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
npm run dev
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## License
|
|
143
|
+
|
|
144
|
+
MIT
|