difftab 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhangwanli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# difftab
+
+**See what your AI coding agent changed — in one tab.**
+
+Run one command in your repo. A local page opens with your working-tree diff and
+branch status — read-only. Close the tab and the process exits on its own.
+
+[中文文档](README.zh-CN.md)
+
+difftab is built for the moment right after an agent finishes (or while it is still
+running): you want a quick look at the changes, not a review session. It shows the
+same thing `git status` and `git diff HEAD` would, rendered as side-by-side diffs with
+syntax highlighting, and it refreshes itself as the agent keeps writing. It never writes
+to your repository — the core promise, enforced by two CI gates and
+[described below](#never-writes-to-your-repository).
+
+## Install
+
+Nothing to install — run it in any repository:
+
+```bash
+npx difftab        # pnpm users: pnpm dlx difftab
+```
+
+The first run spends a few seconds downloading and unpacking the package; later runs come
+from the cache.
+
+If you reach for it after every agent run, install it once instead — an `npx` run spends
+more time resolving which version to fetch than difftab spends starting up:
+
+```bash
+npm i -g difftab   # or: pnpm add -g difftab
+```
+
+Requires **Node.js 22.0.0 or newer**. `dependencies` is empty: the backend uses only the
+Node standard library, and the frontend is bundled at build time, so a global install
+pulls in zero transitive packages.
+
+## Usage
+
+```bash
+cd /path/to/your/repo
+difftab            # or: npx difftab
+```
+
+| 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 |
+
+Running it again in the same repository reuses the running instance instead of starting a
+second process.
+
+## What you get
+
+- **Change list** — staged, unstaged and untracked files in three groups, plus conflicts
+  in their own group with both status letters. Untracked directories are expanded to
+  individual files rather than collapsed into a single `dir/` entry.
+- **Diffs, lazily** — click a file to load its patch; nothing fetches the whole-repo diff.
+  Rendered with [diff2html](https://diff2html.xyz/) and highlight.js in a VS Code-like
+  theme, light and dark following your system appearance.
+- **Branch status** — current branch and ahead/behind counts, "no upstream" when there is
+  none, and a label for detached HEAD or an in-progress rebase / merge / cherry-pick /
+  revert / bisect / `git am`.
+- **Auto-refresh** — a file watcher pushes changes over SSE, so the page keeps up while
+  an agent is still writing. Where recursive watching would exhaust the machine-wide
+  inotify quota (Linux on Node < 24.14.0), it polls instead and says so in the UI; while
+  polling, editing an *untracked* file's contents does not refresh the page (an untracked
+  entry is a single line in `git status` that does not change when its content does).
+- **Exits on its own** — 45 seconds after the last tab closes. Multiple tabs, page
+  reloads, sleep/wake and backgrounded tabs do not trigger it.
+
+Edge cases are handled explicitly rather than left to fail: empty repositories (no
+commits yet), detached HEAD, an interrupted rebase, linked worktrees, submodules, binary
+files, files over 5 MB, renames (annotated with the old path and similarity), deleted
+files, and paths containing spaces, quotes, CJK characters or emoji.
+
+difftab is deliberately a viewer: no editing, no history, no blame, no review workflow.
+The full out-of-scope list is in
+[CONTRIBUTING.md](CONTRIBUTING.md#the-read-only-promise-is-not-negotiable) and
+[`docs/spec.md`](docs/spec.md) §4.
+
+## Never writes to your repository
+
+Not a best-effort claim. difftab never stages, commits, discards, pulls, pushes,
+branches or stashes — it only ever runs read-only git commands. Two independent gates
+enforce that on every CI run, on all three platforms:
+
+1. **Command allowlist.** The whole flow runs under `GIT_TRACE`, and every git
+   invocation the product makes — including subprocesses git spawns internally, such as
+   an accidental `gc` — is asserted to be one of `status` / `diff` / `rev-parse` /
+   `ls-files` / `version`. A positive assertion checks the trace is not empty, so the
+   allowlist can never pass against nothing.
+2. **`.git` is byte-for-byte unchanged.** The flow runs once against a read-only `.git`,
+   and once against a writable one with a before/after snapshot of every file (size,
+   mtime, content digest). A control run proves the snapshot would have caught a change.
+
+The backend is also auditable by hand: `dist/server/main.js` ships unminified precisely
+so you can read which git commands it runs.
+
+## Local security
+
+The server binds `127.0.0.1` on a random port with a session token, and every request —
+including SSE and static assets — passes three checks *before* anything else is decided:
+
+- **`Host`** must be `127.0.0.1:<port>` or `localhost:<port>`. This, not the token, is the
+  real defence against DNS rebinding.
+- **`Origin`**, when present, must be the server's own. No CORS headers are ever sent.
+- **Token**, bound to this session's port, so a token that leaks to another localhost
+  service (cookies are scoped by host, not by port) cannot be replayed there.
+
+The token arrives in the URL once and is immediately swapped for an `HttpOnly;
+SameSite=Strict` cookie with a 302 that strips the query, so it does not linger in browser
+history. Responses carry a strict CSP (`default-src 'none'`, plus `frame-ancestors` /
+`base-uri` / `form-action`, which do not fall back to it), `Cache-Control: no-store` and
+`X-Content-Type-Options: nosniff`. Static assets are served from an in-memory allowlist,
+never by joining a request path onto a directory. There is no environment variable or code
+branch that relaxes any of this.
+
+## Platform support
+
+macOS, Windows and Linux are all supported and all tested. CI runs the full smoke suite
+across three platforms × Node 22 / 24 / 26, plus dedicated jobs for global installation,
+the Node version guard, and degrading to polling when the inotify quota is exhausted.
+What CI cannot cover is in [Known limitations](#known-limitations), below.
+
+## Known limitations
+
+- **The token is passed on a command line.** argv is readable by other users on the same
+  machine, so launching the browser opens a window of tens of milliseconds — one that
+  requires an attacker already logged in locally, polling in a tight loop. Closing it
+  properly conflicts with reusing a running instance, so it is revisited after 0.1.0. How
+  wide it is under `xdg-open` is deliberately *not* measured in CI: a headless number
+  would be reassuring and meaningless.
+- **The browser actually appearing on a Windows or Linux desktop is not covered by CI.**
+  Runners have no desktop session, so the *choice* of `open` / `cmd /c start ""` /
+  `xdg-open` and its argv are asserted, but not the window. Both of these wait on a first
+  real user.
+
+## Development
+
+```bash
+pnpm install --frozen-lockfile   # pnpm version is pinned by the packageManager field
+pnpm build                       # frontend (Vite) + backend (tsdown)
+node bin/difftab.js              # run it against any repository
+```
+
+[CONTRIBUTING.md](CONTRIBUTING.md) has the rest: the dev-server setup, the full list of
+gates, and the handful of things in this codebase that fail silently rather than loudly.
+Requirements and design live in [`docs/`](docs/README.md) and are the single source of
+truth — they change before the code does.
+
+## License
+
+[MIT](LICENSE)

package/README.zh-CN.md

@@ -0,0 +1,137 @@
+# difftab
+
+**一个标签页,看懂 AI 编码 Agent 改了哪些代码。**
+
+在仓库目录敲一条命令。本地网页随即打开,只读展示当前工作区的 diff 与分支状态。
+关掉标签页,进程自行退出。
+
+[English](README.md)
+
+difftab 面向的是 agent 刚跑完(或者还在跑)的那一刻:你想「瞥一眼」改了什么,而不是
+开一场代码评审。它展示的就是 `git status` 与 `git diff HEAD` 的内容,以并排 diff 加语法
+高亮呈现,并在 agent 继续写的过程中自动刷新。它对你的仓库**全程零写操作**——这是核心承诺,
+由两道 CI 门禁守着,详见[下文](#全程零写操作)。
+
+## 安装
+
+不用装,在任意仓库目录里直接跑:
+
+```bash
+npx difftab        # pnpm 用户:pnpm dlx difftab
+```
+
+首次要下载解包,多花几秒,之后走缓存。
+
+如果你每次 agent 跑完都要看一眼,那就装一次——`npx` 光是决定该跑哪个版本,就比 difftab
+自己启动还花时间:
+
+```bash
+npm i -g difftab   # 或:pnpm add -g difftab
+```
+
+要求 **Node.js 22.0.0 或更高**。`dependencies` 为空:后端只用 Node 标准库,前端在构建期
+就打进产物,所以全局安装是零传递依赖的。
+
+## 使用
+
+```bash
+cd /path/to/your/repo
+difftab            # 或:npx difftab
+```
+
+| 参数 | 作用 |
+|---|---|
+| `--no-open` | 只打印 URL,不拉起浏览器 |
+| `-v`, `--version` | 打印版本号并退出 |
+| `-h`, `--help` | 打印帮助并退出 |
+
+在同一个仓库里再敲一次,会复用已在跑的实例,而不是起第二个进程。
+
+## 能看到什么
+
+- **变更列表** —— 已暂存、未暂存、未跟踪三组,冲突文件自成一组并印出 XY 两位状态。未跟踪
+  的目录展开到文件粒度,而不是折叠成一行 `dir/`。
+- **按文件懒加载的 diff** —— 点开某个文件才取它的补丁,任何时候都不会去取整仓 diff。渲染
+  用 [diff2html](https://diff2html.xyz/) + highlight.js,配色仿 VS Code,深浅两套跟随系统
+  外观。
+- **分支状态** —— 当前分支与 ahead/behind 计数,无上游时明说「无上游」;游离 HEAD 与进行
+  中的 rebase / merge / cherry-pick / revert / bisect / `git am` 各出一个标注。
+- **自动刷新** —— 文件监听经 SSE 推到前端,agent 边改你边看。在递归监听会耗尽整机
+  inotify 配额的场合(Linux + Node < 24.14.0),改用轮询,并在界面上标注出来;轮询期间改
+  一个**未跟踪**文件的内容不会刷新页面(未跟踪条目在 `git status` 里只有一行,内容变了它
+  一个字节都不变)。
+- **自己退出** —— 最后一个标签页关掉 45 秒后自动退。多标签、刷新页面、系统休眠唤醒、浏览
+  器丢弃后台标签都不会误触发。
+
+边界情况是被显式处理的,而不是留着崩:空仓库(还没有提交)、游离 HEAD、停在中途的 rebase、
+linked worktree、submodule、二进制文件、超过 5MB 的文件、重命名(标注完整旧路径与相似度)、
+删除的文件,以及路径里带空格、引号、中日韩文字或 emoji 的文件。
+
+difftab 刻意只是个查看器:不编辑代码、不看历史、不做 blame、不承载评审流程。完整的不做
+清单在 [CONTRIBUTING.md](CONTRIBUTING.md#the-read-only-promise-is-not-negotiable) 与
+[`docs/spec.md`](docs/spec.md) §4。
+
+## 全程零写操作
+
+不是「尽量」。difftab 不 stage、不 commit、不 discard、不 pull / push、不建分支、
+不 stash——它只发只读的 git 命令。这条由两道互相独立的门禁在每次 CI、三个平台上守着:
+
+1. **命令白名单。** 整条流程跑在 `GIT_TRACE` 之下,产品发出的每一次 git 调用——包括 git
+   自己内部再起的子进程(比如一次意外触发的 `gc`)——都被断言只能是 `status` / `diff` /
+   `rev-parse` / `ls-files` / `version`。另配一条「确实记到了东西」的正面断言,白名单不会
+   对着一个空数组通过。
+2. **`.git` 逐字节不变。** 同一条流程跑两遍:一遍对着只读的 `.git`,一遍对着可写的
+   `.git` 并在前后各拍一次快照(每个文件的 size、mtime、内容摘要)比对。另有一组正面对照
+   证明这份快照真的抓得住变化。
+
+后端也支持手工审计:`dist/server/main.js` **不压缩不混淆**发布,就是为了让你自己读一遍它
+到底跑了哪些 git 命令。
+
+## 本地安全
+
+服务绑定 `127.0.0.1`,随机端口 + 会话级 token。每一个请求——包括 SSE 与静态资源——都要先
+过三道校验,**排在其余一切判定之前**:
+
+- **`Host`** 必须是 `127.0.0.1:<端口>` 或 `localhost:<端口>`。挡住 DNS rebinding 的是这一
+  道,不是 token。
+- **`Origin`** 非空时必须是服务自身。所有响应不带任何 CORS 头。
+- **token** 与本次会话的端口绑定——cookie 的作用域是 host 而非 origin,不隔离端口,绑上
+  端口后即使 token 漏给了同机另一个 localhost 服务,也没法在别处复用。
+
+token 只在 URL 里出现一次,首访即置换成 `HttpOnly; SameSite=Strict` cookie 并 302 掉
+query,不会长期滞留在浏览器历史里。响应带严格 CSP(`default-src 'none'`,外加不回退到它的
+`frame-ancestors` / `base-uri` / `form-action`),以及 `Cache-Control: no-store` 与
+`X-Content-Type-Options: nosniff`。静态资源按内存里的白名单映射,绝不用请求路径去拼目录。
+**后端不存在任何放宽上述校验的环境变量或分支。**
+
+## 平台支持
+
+macOS / Windows / Linux 三端均支持、均有测试。CI 在三平台 × Node 22 / 24 / 26 上跑完整冒烟
+套件,另有全局安装、Node 版本守卫、inotify 配额耗尽降级三个专用作业。CI 覆盖不到的部分在
+下面的[已知边界](#已知边界)。
+
+## 已知边界
+
+- **token 要经过一次命令行。** argv 对同机其他用户可读,所以拉起浏览器时有一个几十毫秒的
+  窗口——而它要求攻击者已经以另一个本机用户身份在紧循环轮询。真正关掉它与「再敲一次命令
+  复用已有实例」相冲突,留到 0.1.0 之后再看。这个窗口在 `xdg-open` 下有多宽**刻意不在 CI
+  里量**:headless 上量出来的数字会让人放心,但没有意义。
+- **浏览器在 Windows / Linux 桌面上真的弹出来,CI 覆盖不到。** runner 没有桌面会话,所以
+  `open` / `cmd /c start ""` / `xdg-open` 的**选择与 argv** 有断言,窗口本身没有。这两条
+  都等首个真实用户。
+
+## 开发
+
+```bash
+pnpm install --frozen-lockfile   # pnpm 版本由 packageManager 字段固定
+pnpm build                       # 前端 Vite + 后端 tsdown
+node bin/difftab.js              # 在任意 git 仓库目录下跑起来
+```
+
+其余在 [CONTRIBUTING.md](CONTRIBUTING.md):dev server 怎么起、完整的门禁清单,以及这个仓库
+里那几条「坏了不报错」的地方。需求与设计的唯一事实来源是 [`docs/`](docs/README.md)——需求要
+变,先改 docs 再改代码。
+
+## License
+
+[MIT](LICENSE)

package/bin/difftab.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// difftab CLI 入口 —— 版本守卫。
+//
+// 本文件手写维护,不参与 TypeScript 编译、不作为任何打包入口(spec §5.1 / §10)。
+// 一旦它进了构建管线,就可能被注入超出 Node 22 的语法或被合并进主模块,
+// 低于下限的用户拿到的将是解析期 SyntaxError —— 守卫在解析期即失效。
+//
+// 因此这里只用「保守语法」:ES2015 之内,不使用可选链 / 空值合并 /
+// 顶层 await / class 字段等更晚的语法。守卫通过后,才动态 import 主模块。
+//
+// `node:fs` 是**内建模块**,静态 import 它不违反上面那条 —— 守卫要防的是「解析期就
+// 炸掉」与「把主模块的新语法拖进来」,而内建模块两条都不沾,且在 Node 12 起就支持
+// `node:` 前缀。写成静态 import 而不是在分支里动态 import:那条路要么 `await`
+// (顶层 await 正是禁项),要么把报错塞进 `.then()` 回调里,而回调里的 `process.exit()`
+// 与本文件要修的问题是同一类。
+
+import { writeSync } from 'node:fs';
+
+/**
+ * 退出前的报错**一律 `writeSync(2, …)`**(spec §5.8 红线)。
+ *
+ * `process.stderr.write(…)` + `process.exit()` 在 Windows 上写**管道**时是异步的,
+ * 整条消息会被丢掉 —— 症状是 stderr 全空、只剩一个退出码。而**文件重定向看不出
+ * 区别**(那条是同步写),所以门禁那侧必须经管道取回 stderr,见 CI 的 old-node-guard。
+ *
+ * try/catch 是因为读端可能先走(`difftab | head -1`):此刻要报的是别的事,
+ * 不该被一个 EPIPE 顶掉。
+ */
+function writeStderr(message) {
+  try {
+    writeSync(2, message);
+  } catch (_cause) {
+    // 报不出来就算了 —— 退出码仍然是对的。
+    // 绑定写成 `_cause` 而不是省略:可选 catch 绑定是 ES2019,本文件只用 ES2015
+  }
+}
+
+// 下限只写一次。写成两个常量时,把 MIN_MAJOR 提到 24 却忘了改 MIN_VERSION,
+// 结果是守卫正确地拒掉 Node 22、却告诉用户「requires Node.js 22.0.0 or newer,
+// but this is v22.5.0」—— 没有任何门禁会因此变红。
+// 与 package.json 的 engines.node 对齐由冒烟测试断言。
+const MIN_MAJOR = 22;
+const MIN_VERSION = `${MIN_MAJOR}.0.0`;
+
+const raw = process.versions.node;
+const major = parseInt(raw.split('.')[0], 10);
+
+// 写成 !(major >= MIN_MAJOR) 而非 major < MIN_MAJOR:解析失败得到 NaN 时同样报错。
+if (!(major >= MIN_MAJOR)) {
+  writeStderr(
+    'difftab: requires Node.js ' +
+      MIN_VERSION +
+      ' or newer, but this is v' +
+      raw +
+      '.\n' +
+      'Please upgrade Node.js and try again: https://nodejs.org/\n',
+  );
+  process.exit(1);
+}
+
+import('../dist/server/main.js')
+  .then((mod) => mod.main(process.argv.slice(2)))
+  .catch((err) => {
+    const detail = err && err.stack ? err.stack : String(err);
+    writeStderr(`difftab: failed to start.\n${detail}\n`);
+    process.exit(1);
+  });