difftab 0.4.1 → 0.5.1

package/README.md

@@ -3,84 +3,139 @@
   difftab
 </h1>
 
+<p align="center"><strong>See what your AI coding agent changed — in one browser tab.</strong></p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/difftab"><img src="https://img.shields.io/npm/v/difftab" alt="npm"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/difftab" alt="node"></a>
-  <a href="#never-writes-to-your-repository"><img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies"></a>
+  <a href="#security"><img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/difftab" alt="license"></a>
 </p>
 
-**See what your AI coding agent changed — in one tab.**
+<p align="center">
+  <a href="#installation">Install</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#why-difftab">Why</a> ·
+  <a href="#faq">FAQ</a> ·
+  <a href="README.zh-CN.md">中文文档</a>
+</p>
+
+A read-only, zero-dependency local viewer for your git working tree: the diff, the file
+tree and the branch status, refreshing itself while the agent keeps writing. Close the tab
+and it exits.
+
+## Why difftab
+
+You run Claude Code, Codex, OpenCode or another agent from a terminal. It finishes a task,
+and you want to see what it actually did. The agent's own diff scrolls past in the
+terminal, which is not the place to read a 300-line patch — so you open VS Code, or
+whatever IDE you keep around for this, not to edit anything, just to read the diff, glance
+at the tree, check the branch, and close it again.
 
-Run one command in your repo. A local page opens with your working-tree diff and branch
-status — what `git status` and `git diff HEAD` would show — read-only, refreshing itself
-while the agent keeps writing. Close the tab and the process exits.
+difftab is that half of the editor without the editor. One command, one tab, and only the
+three things you actually looked at. It only reads git, so it works with any agent, any
+language and any repository. And if an agent now writes all your code, you can uninstall
+the IDE.
 
-[中文文档](README.zh-CN.md)
+## Features
 
-## Quick start
+- **The diff, the way an editor shows it** — staged, unstaged, untracked and conflicting
+  changes, side by side with syntax highlighting.
+- **The whole repository, not only what changed** — browse the file tree and open any file.
+- **Branch status you can trust** — ahead/behind, no upstream, detached HEAD, a rebase or
+  merge still in progress.
+- **Live while the agent writes** — the tab refreshes on its own as files change.
+- **Never writes to your repository** — read-only git only, enforced by CI gates rather
+  than by promise. Details under [Security](#security).
+- **Nothing to keep running** — starts instantly, zero dependencies, exits when you close
+  the tab.
+
+## Installation
+
+Requires **Node.js 22 or newer** on macOS, Windows or Linux. No other dependencies.
+
+```bash
+npm i -g difftab
+```
+
+Or try it without installing:
 
 ```bash
-cd /path/to/your/repo
 npx difftab
 ```
 
-Or install it once — `npm i -g difftab` — and just run `difftab`.
+## Usage
+
+Run it inside any git repository:
+
+```bash
+cd /path/to/your/repo
+difftab
+```
+
+A browser tab opens with the current diff. Keep it open next to the agent: the tab
+refreshes as files change, and when you close it the process exits on its own. Running
+`difftab` again in the same repository reuses the running instance instead of starting a
+second one.
+
+| Option | What it does |
+|---|---|
+| `--no-open` | Print the URL instead of opening a browser |
+| `-v`, `--version` | Print the version and exit |
+| `-h`, `--help` | Print help and exit |
+
+There is nothing to configure: no port to pick, no config file.
+
+## How it works
 
-Requires **Node.js 22 or newer** on macOS, Windows or Linux. Zero dependencies.
+`difftab` runs the same read-only git commands `git status` and `git diff HEAD` would, and
+serves the result from a local server on `127.0.0.1`. The page loads a patch when you click
+it and refreshes as files change; 45 seconds after the last tab closes, the process exits.
 
-- `--no-open` — print the URL instead of opening a browser
-- `-v`, `--version` — print the version and exit
-- `-h`, `--help` — print help and exit
+## Security
 
-Running it again in the same repository reuses the running instance.
+Read-only, local-only, nothing to trust but your own machine.
 
-## What you get
+**It never writes to your repository.** difftab only ever runs read-only git commands — no
+stage, commit, discard, pull, push, branch or stash. Two gates enforce this on every
+change: a `GIT_TRACE` allowlist over every git invocation, and a byte-for-byte comparison
+of `.git` before and after. `dist/server/main.js` ships unminified, so you can audit it by
+hand.
 
-- **Change list** — staged, unstaged, untracked and conflicting files in four groups, with
-  untracked directories expanded to files.
-- **Diffs, lazily** — click a file to load its patch, rendered by
-  [diff2html](https://diff2html.xyz/) + highlight.js in a VS Code-like theme, side by side
-  until the pane gets too narrow.
-- **File tree** — a second sidebar tab browses the whole repository rather than only what
-  changed: tracked, untracked and ignored files (the ignored ones dimmed), loaded one
-  directory at a time. Click any file to read it, highlighted by the same theme.
-- **Branch status** — branch name, ahead/behind counts, "no upstream", detached HEAD, and
-  an in-progress rebase / merge / cherry-pick / revert / bisect / `git am`.
-- **Auto-refresh** — a file watcher pushes changes over SSE, falling back to polling where
-  recursive watching would exhaust the inotify quota (and saying so in the UI).
-- **Exits on its own** — 45 seconds after the last tab closes.
-- **Cheap to run** — about 40 ms from launch to a listening server, well inside the 300 ms
-  budget CI enforces on every commit across nine Node × OS combinations; the JS bundle is
-  75 KB gzipped.
+**Nothing leaves your machine.** The server binds `127.0.0.1`; the only HTTP request
+difftab makes is to localhost, to see whether an instance is already running for this
+repository. No telemetry, no account, no cloud.
 
-Empty repositories, interrupted rebases, linked worktrees, submodules, binary and >5 MB
-files, renames, and paths with spaces, quotes, CJK or emoji are handled explicitly.
+**The local page is locked down.** Each session gets a random token, handed to the browser
+once through the URL and then kept in an `HttpOnly; SameSite=Strict` cookie while the URL
+is redirected clean. Every request is checked against the `Host` header — the actual
+defense against DNS rebinding, rather than the token alone — and against `Origin`, and the
+page runs under a `default-src 'none'` CSP that also blocks framing, `<base>` rewriting and
+form submission. There is no development escape hatch: no environment variable relaxes any
+of those checks.
 
-difftab is deliberately a viewer: no editing, history, blame or review workflow
-([out-of-scope list](CONTRIBUTING.md#the-read-only-promise-is-not-negotiable)).
+## FAQ
 
-## Never writes to your repository
+**Does it work with my agent?** — Yes. difftab never talks to the agent — it only reads
+git — so anything that writes files into a git working tree looks the same to it: Claude
+Code, Codex, OpenCode, Aider, a human with vim.
 
-Not a best-effort claim: difftab only ever runs read-only git commands — no stage, commit,
-discard, pull, push, branch or stash. Two gates enforce it on every change: a `GIT_TRACE`
-allowlist over every git invocation, and a byte-for-byte comparison of `.git` before and
-after. And `dist/server/main.js` ships unminified, so you can audit it by hand.
+**Can I stage, commit or discard from it?** — No, and it never will be. Read-only is the
+product's core promise, not a missing feature; see [Non-goals](#non-goals).
 
-## Nothing leaves your machine
+**The UI says "Polling" — is something wrong?** — No. It means difftab could not use native
+file watching here: Node older than 24.14 on Linux, a repository on a network drive or a
+Docker volume, or an exhausted inotify quota. It runs `git status` every 1.5 seconds
+instead, so everything still refreshes; it may just land a second or two later.
 
-The server binds `127.0.0.1` on a port the kernel picks, and the only HTTP request difftab
-makes is to localhost, to see whether an instance is already running for this repository.
-No telemetry, no account, no cloud.
+## Non-goals
 
-Each session gets a random token, handed to the browser once through the URL and then kept
-in an `HttpOnly; SameSite=Strict` cookie while the URL is redirected clean. Every request
-is checked against the `Host` header — the actual defense against DNS rebinding, rather
-than the token alone — and against `Origin`, and the page runs under a `default-src 'none'`
-CSP that also blocks framing, `<base>` rewriting and form submission. There is no
-development escape hatch: no environment variable relaxes any of those checks.
+difftab is deliberately a viewer. Permanently out of scope: any repository write operation,
+code editing, accounts and cloud sync, and multi-user review workflows. Out of the current
+version: commit history, branch lists, blame. The full list, and the reasoning, is in
+[CONTRIBUTING.md](CONTRIBUTING.md#the-read-only-promise-is-not-negotiable).
 
-## Development
+## Contributing
 
 ```bash
 pnpm install --frozen-lockfile

package/README.zh-CN.md

@@ -3,62 +3,100 @@
   difftab
 </h1>
 
+<p align="center"><strong>一个浏览器标签页，看懂 AI 编码 Agent 改了哪些代码。</strong></p>
+
 <p align="center">
   <a href="https://www.npmjs.com/package/difftab"><img src="https://img.shields.io/npm/v/difftab" alt="npm"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/node/v/difftab" alt="node"></a>
-  <a href="#全程零写操作"><img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies"></a>
+  <a href="#安全"><img src="https://img.shields.io/badge/dependencies-0-brightgreen" alt="dependencies"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/difftab" alt="license"></a>
 </p>
 
-**一个标签页，看懂 AI 编码 Agent 改了哪些代码。**
+<p align="center">
+  <a href="#安装">安装</a> ·
+  <a href="#用法">用法</a> ·
+  <a href="#为什么做-difftab">为什么</a> ·
+  <a href="#常见问题">常见问题</a> ·
+  <a href="README.md">English</a>
+</p>
+
+一个只读、零依赖的本地工作区查看器：diff、文件树、分支状态，在 agent 继续写的过程中自动刷新。关掉标签页，它就退出。
+
+## 为什么做 difftab
+
+你在终端里跑 Claude Code、Codex、OpenCode 之类的 agent。它做完一件事，你想看看它到底改了什么。agent 自带的 diff 在终端里刷过去，那不是读一份三百行补丁的地方——于是你打开 VS Code，或者手边为此留着的随便哪个 IDE，什么都不编辑，只是看看 diff、瞄一眼目录树、确认下分支，然后关掉。
 
-在仓库目录敲一条命令，本地网页随即打开，只读展示当前工作区的 diff 与分支状态（就是 `git status` 与 `git diff HEAD` 的内容），并在 agent 继续写的过程中自动刷新；关掉标签页，进程自行退出。
+difftab 就是编辑器里的这一半，去掉编辑器。一条命令、一个标签页，只装你真正会看的那三样。它只读 git，所以配哪个 agent、哪种语言、哪个仓库都一样。如果现在代码全由 agent 来写，IDE 就可以卸了。
 
-[English](README.md)
+## 特性
 
-## 快速开始
+- **像编辑器那样看 diff**——已暂存、未暂存、未跟踪、冲突一目了然，并排展示，带语法高亮。
+- **整个仓库，而不只是改动过的那些**——浏览文件树，点开任一文件即可查看。
+- **信得过的分支状态**——ahead/behind、无上游、游离 HEAD、进行到一半的 rebase 或 merge。
+- **agent 边写边看**——文件一变，标签页自己刷新。
+- **绝不写你的仓库**——只发只读的 git 命令，由 CI 门禁保证，不是靠承诺。细节见[安全](#安全)。
+- **不用养着**——瞬间启动，零依赖，关掉标签页就退出。
+
+## 安装
+
+要求 **Node.js 22 或更高**，macOS / Windows / Linux 三端均支持，没有其他依赖。
+
+```bash
+npm i -g difftab
+```
+
+也可以不装直接试：
 
 ```bash
-cd /path/to/your/repo
 npx difftab
 ```
 
-也可以装一次——`npm i -g difftab`——之后直接敲 `difftab`。
+## 用法
+
+在任意 git 仓库目录下执行：
+
+```bash
+cd /path/to/your/repo
+difftab
+```
+
+浏览器标签页随即打开，展示当前的 diff。让它在 agent 旁边开着：文件一变标签页就刷新，关掉它进程自己退出。在同一个仓库里再敲一次 `difftab`，会复用已在跑的实例，不会起第二个。
+
+| 选项 | 作用 |
+|---|---|
+| `--no-open` | 只打印 URL，不拉起浏览器 |
+| `-v`, `--version` | 打印版本号并退出 |
+| `-h`, `--help` | 打印帮助并退出 |
+
+没有任何东西需要配置：不用选端口，没有配置文件。
+
+## 工作原理
 
-要求 **Node.js 22 或更高**，macOS / Windows / Linux 三端均支持，零依赖。
+`difftab` 只运行 `git status` 与 `git diff HEAD` 那一类只读 git 命令，由一个只绑 `127.0.0.1` 的本地服务把结果交给页面。页面点到哪个补丁才加载哪个，文件一变就刷新；最后一个标签页关掉 45 秒后进程自行退出。
 
-- `--no-open`——只打印 URL，不拉起浏览器
-- `-v`, `--version`——打印版本号并退出
-- `-h`, `--help`——打印帮助并退出
+## 安全
 
-在同一个仓库里再敲一次，会复用已在跑的实例。
+只读、只在本机，除了你自己的电脑不需要信任任何东西。
 
-## 能看到什么
+**全程零写操作。** difftab 只发只读的 git 命令——不 stage、不 commit、不 discard、不 pull / push、不建分支、不 stash。两道门禁在每次改动上守着：一道是覆盖每一次 git 调用的 `GIT_TRACE` 命令白名单，另一道是 `.git` 前后逐字节比对。`dist/server/main.js` 不压缩不混淆发布，可以手工审计。
 
-- **变更列表**——已暂存、未暂存、未跟踪、冲突四组，未跟踪的目录展开到文件粒度。
-- **按文件懒加载的 diff**——点开某个文件才取它的补丁，渲染用 [diff2html](https://diff2html.xyz/) + highlight.js，配色仿 VS Code，面板窄到放不下两列时自动切成逐行。
-- **文件树**——侧栏第二个 tab 浏览整个仓库，而不只是改动过的那些：已跟踪、未跟踪与被忽略的文件（后者灰显），按目录懒加载。点任一文件在右侧只读查看，高亮复用同一套配色。
-- **分支状态**——当前分支、ahead/behind 计数、无上游、游离 HEAD，以及进行中的 rebase /
-  merge / cherry-pick / revert / bisect / `git am`。
-- **自动刷新**——文件监听经 SSE 推到前端；递归监听会耗尽 inotify 配额的场合改用轮询，并在界面上标注。
-- **自己退出**——最后一个标签页关掉 45 秒后自动退。
-- **跑起来很轻**——从启动到端口就绪约 40ms，远在 CI 每次提交都验的 300ms 预算之内（九个 Node × 平台组合各跑一遍）；打包后的 JS gzip 75KB。
+**全程不外传。** 服务只绑 `127.0.0.1`；difftab 发出的唯一一个 HTTP 请求是打到 localhost 上的，用来确认这个仓库是不是已经有实例在跑。无遥测、无账号、无云端。
 
-空仓库、停在中途的 rebase、linked worktree、submodule、二进制与超过 5MB 的文件、重命名，以及带空格、引号、中日韩文字或 emoji 的路径，都是被显式处理的。
+**本地页面也是锁死的。** 每次会话生成一个随机 token，先经 URL 交给浏览器，随后落进 `HttpOnly; SameSite=Strict` 的 cookie，并把 URL 上的 query 重定向掉。每个请求都校验 `Host` 头与 `Origin`——`Host` 那道才是 DNS rebinding 的正面防御，光靠 token 挡不住；页面跑在 `default-src 'none'` 的 CSP 之下，被嵌 iframe、`<base>` 改写相对 URL 与表单外发也一并挡掉。后端没有任何开发用的后门：不存在放宽这几道校验的环境变量。
 
-difftab 刻意只是个查看器：不编辑、不看历史、不做 blame、不承载评审流程（完整的不做清单见 [CONTRIBUTING.md](CONTRIBUTING.md#the-read-only-promise-is-not-negotiable)）。
+## 常见问题
 
-## 全程零写操作
+**能配我用的 agent 吗？**——能。difftab 从不与 agent 打交道，它只读 git，所以凡是往 git 工作区里写文件的东西在它眼里都一样：Claude Code、Codex、OpenCode、Aider、拿着 vim 的人。
 
-不是「尽量」：difftab 只发只读的 git 命令——不 stage、不 commit、不 discard、不 pull / push、不建分支、不 stash。两道门禁在每次改动上守着：一道是覆盖每一次 git 调用的 `GIT_TRACE` 命令白名单，另一道是 `.git` 前后逐字节比对。后端也支持手工审计：`dist/server/main.js` 不压缩不混淆发布。
+**能在里面 stage、commit 或 discard 吗？**——不能，将来也不会。只读是产品的核心承诺，不是还没做的功能；见[明确不做](#明确不做)。
 
-## 全程不外传
+**界面上写着「Polling」，是出问题了吗？**——没有。它表示 difftab 在这里用不了原生文件监听：Linux 上低于 24.14 的 Node、放在网络盘或 Docker 卷上的仓库、或 inotify 配额耗尽。于是改成每 1.5 秒跑一次 `git status`，一切照常刷新，只是可能晚一两秒。
 
-服务只绑 `127.0.0.1`，端口由内核随机分配，而 difftab 发出的唯一一个 HTTP 请求是打到 localhost 上的，用来确认这个仓库是不是已经有实例在跑。无遥测、无账号、无云端。
+## 明确不做
 
-每次会话生成一个随机 token，先经 URL 交给浏览器，随后落进 `HttpOnly; SameSite=Strict` 的 cookie，并把 URL 上的 query 重定向掉。每个请求都校验 `Host` 头与 `Origin`——`Host` 那道才是 DNS rebinding 的正面防御，光靠 token 挡不住；页面跑在 `default-src 'none'` 的 CSP 之下，被嵌 iframe、`<base>` 改写相对 URL 与表单外发也一并挡掉。后端没有任何开发用的后门：不存在放宽这几道校验的环境变量。
+difftab 刻意只是个查看器。长期不做：任何仓库写操作、代码编辑、账号与云同步、多用户评审流程。当前版本不做：提交历史、分支列表、blame。完整清单与理由见 [CONTRIBUTING.md](CONTRIBUTING.md#the-read-only-promise-is-not-negotiable)。
 
-## 开发
+## 参与开发
 
 ```bash
 pnpm install --frozen-lockfile