git-watchtower 2.1.0 → 2.1.2

package/README.md

@@ -1,10 +1,26 @@
+<div align="center">
+
 # Git Watchtower
 
+## Keep up with your AI coding agents.
+
+### Monitor git branches in real-time with activity sparklines, instant notifications, and a web dashboard.
+
+Built for teams working with Claude Code, Codex, and other AI agents.
+
 [![npm version](https://img.shields.io/npm/v/git-watchtower.svg)](https://www.npmjs.com/package/git-watchtower)
 [![npm downloads](https://img.shields.io/npm/dm/git-watchtower.svg)](https://www.npmjs.com/package/git-watchtower)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-Monitor and switch between git branches in real-time. Built for working with web-based AI coding agents, like Claude Code Web & Codex.
+#### Visit our website &rarr; [gitwatchtower.dev](https://gitwatchtower.dev)
+
+[Quick Start](https://gitwatchtower.dev/guides/quick-start/) · [Configuration](https://gitwatchtower.dev/guides/configuration/) · [Web Dashboard](https://gitwatchtower.dev/guides/web-dashboard/) · [Keyboard Controls](https://gitwatchtower.dev/guides/keyboard-controls/) · [Server Modes](https://gitwatchtower.dev/guides/server-modes/) · [Troubleshooting](https://gitwatchtower.dev/guides/troubleshooting/)
+
+</div>
+
+![Git Watchtower Screenshot](assets/git-watchtower-screenshot.png)
+
+## Features
 
 - **Live branch monitoring** with activity sparklines and ahead/behind counters
 - **Web dashboard** for browser-based branch management and PR workflows
@@ -14,32 +30,14 @@ Monitor and switch between git branches in real-time. Built for working with web
 - **Optional dev server** with live reload, or run your own command (Next.js, Vite, etc.)
 - **Zero dependencies** — uses only Node.js built-in modules
 
-![Git Watchtower Screenshot](assets/git-watchtower-screenshot.png)
-
 ## Why Git Watchtower?
 
-When you're using AI coding agents on the web (Claude, OpenAI Codex, etc.) they create branches and push commits while you're not looking. You end up with multiple branches to check on and no easy way to know when they've been updated or what changed.
+When you're using AI coding agents on the web — Claude Code, OpenAI Codex, and others — they create branches and push commits while you're not looking. You end up with multiple branches to check on and no easy way to know when they've been updated or what changed.
 
 Git Watchtower watches your remote and notifies you when branches are updated. Preview what changed, switch with a keypress, undo if needed.
 
 Also works for human collaborators, but the primary use case is keeping tabs on AI agents coding on different branches.
 
-## Web Dashboard
-
-Launch a browser-based dashboard alongside the terminal UI with `--web`:
-
-```bash
-git-watchtower --web
-```
-
-![Web Dashboard](assets/git-watchtower-web-ui.png)
-
-The web dashboard provides real-time branch monitoring, PR workflows, CI status, session statistics, and more — all in a rich browser interface. When running multiple instances across different projects, they coordinate automatically into a single multi-project dashboard.
-
-Press `W` in the TUI to toggle the web dashboard on or off at any time.
-
-[Full web dashboard documentation &rarr;](docs/web-dashboard.md)
-
 ## Installation
 
 ```bash
@@ -53,10 +51,7 @@ npx git-watchtower
 ## Quick Start
 
 ```bash
-# Navigate to any git repository
 cd your-project
-
-# Start Git Watchtower
 git-watchtower
 ```
 
@@ -84,11 +79,19 @@ git-watchtower --init
 git-watchtower --help
 ```
 
-[Full CLI reference &rarr;](docs/configuration.md#cli-flags)
+## Web Dashboard
+
+Launch a browser-based dashboard alongside the terminal UI with `--web`:
 
-## Server Modes
+```bash
+git-watchtower --web
+```
+
+![Web Dashboard](assets/git-watchtower-web-ui.png)
 
-Git Watchtower supports three server modes:
+Real-time branch monitoring, PR workflows, CI status, and session statistics — all in a rich browser interface. When running multiple instances across different projects, they coordinate automatically into a single multi-project dashboard. Press `W` in the TUI to toggle the web dashboard on or off at any time.
+
+## Server Modes
 
 | Mode | Flag | Description |
 |------|------|-------------|
@@ -96,46 +99,28 @@ Git Watchtower supports three server modes:
 | **Custom Command** | `--mode command -c "npm run dev"` | Run your own dev server (Next.js, Vite, Nuxt, etc.) |
 | **No Server** | `--no-server` | Branch monitoring only |
 
-[Full server modes documentation &rarr;](docs/server-modes.md)
-
-## Configuration
+## 🎰 Casino Mode
 
-Settings are saved to `.watchtowerrc.json` in your project directory. Key settings:
+Yes, it's a real feature. Every `git fetch` is a slot-machine spin, every commit is a payout. Enable with `--casino` or `"casinoMode": true`.
 
-| Setting | Description | Default |
-|---------|-------------|---------|
-| Server mode | static, command, or none | static |
-| Port | Server port number | 3000 |
-| Web dashboard | Enable browser dashboard | false (use `--web`) |
-| Auto-pull | Auto-pull when current branch has updates | true |
-| Polling interval | How often to check for git updates | 5 seconds |
-| Sound notifications | Audio alerts for updates | true |
-| Visible branches | Number of branches shown in list | 7 |
+## Documentation
 
-[Full configuration reference &rarr;](docs/configuration.md)
+Full docs at **[gitwatchtower.dev](https://gitwatchtower.dev)**.
 
-## Keyboard Controls
-
-| Key | Action |
-|-----|--------|
-| `Up` / `k`, `Down` / `j` | Navigate branch list |
-| `Enter` | Switch to selected branch |
-| `v` | Preview branch (commits & files) |
-| `/` | Search/filter branches |
-| `b` | Branch actions (PR, CI, merge, approve) |
-| `u` | Undo last branch switch |
-| `S` | Stash changes |
-| `W` | Toggle web dashboard |
-| `q` | Quit |
-
-[Full keyboard reference &rarr;](docs/keyboard-controls.md)
+- [Quick Start](https://gitwatchtower.dev/guides/quick-start/) — install, first run, and the configuration wizard
+- [Configuration](https://gitwatchtower.dev/guides/configuration/) — every setting, CLI flag, and environment variable
+- [Web Dashboard](https://gitwatchtower.dev/guides/web-dashboard/) — browser UI with PR workflows and CI status
+- [Keyboard Controls](https://gitwatchtower.dev/guides/keyboard-controls/) — full key reference
+- [Server Modes](https://gitwatchtower.dev/guides/server-modes/) — static site, custom command, and no-server modes
+- [Troubleshooting](https://gitwatchtower.dev/guides/troubleshooting/) — common issues and fixes
 
 ## Requirements
 
-- **Node.js** 18.0.0 or higher
+- **Node.js** 20.0.0 or higher
 - **Git** installed and in PATH
 - **Git remote** configured (any name, defaults to `origin`)
 - **Terminal** with ANSI color support
+- **Optional**: [`gh`](https://cli.github.com/) or [`glab`](https://gitlab.com/gitlab-org/cli) CLI for branch actions (PR create, approve, merge, CI status)
 
 ## How It Works
 
@@ -146,10 +131,6 @@ Settings are saved to `.watchtowerrc.json` in your project directory. Key settin
 5. **Live Reload** — In static site mode, notifies connected browsers via SSE when files change
 6. **Web Dashboard** — Optional browser UI that mirrors and extends the TUI via SSE
 
-## Troubleshooting
-
-Common issues and solutions are covered in the [troubleshooting guide](docs/troubleshooting.md).
-
 ## Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
@@ -174,6 +155,14 @@ npm test
 node bin/git-watchtower.js
 ```
 
+The documentation site lives in [`website/`](website/) and is built with Astro Starlight:
+
+```bash
+cd website
+npm install
+npm run dev
+```
+
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
+MIT License — see [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-watchtower",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "description": "Terminal-based Git branch monitor with activity sparklines and optional dev server with live reload",
   "main": "bin/git-watchtower.js",
   "bin": {
@@ -47,7 +47,7 @@
   "bugs": {
     "url": "https://github.com/drummel/git-watchtower/issues"
   },
-  "homepage": "https://github.com/drummel/git-watchtower#readme",
+  "homepage": "https://gitwatchtower.dev",
   "engines": {
     "node": ">=20.0.0"
   },

package/src/git/branch.js

@@ -103,7 +103,7 @@ async function getAllBranches(options = {}) {
     // Use \x1f (Unit Separator) as delimiter since | can appear in commit subjects
     const delimiter = '\x1f';
     const localResult = await execGit(
-      ['for-each-ref', '--sort=-committerdate', `--format=%(refname:short)${delimiter}%(committerdate:iso8601)${delimiter}%(objectname:short)${delimiter}%(subject)`, 'refs/heads/'],
+      ['for-each-ref', '--sort=-committerdate', `--format=%(refname:short)${delimiter}%(committerdate:iso8601-strict)${delimiter}%(objectname:short)${delimiter}%(subject)`, 'refs/heads/'],
       { cwd }
     );
 
@@ -128,7 +128,7 @@ async function getAllBranches(options = {}) {
 
     // Get remote branches
     const remoteResult = await execGit(
-      ['for-each-ref', '--sort=-committerdate', `--format=%(refname:short)${delimiter}%(committerdate:iso8601)${delimiter}%(objectname:short)${delimiter}%(subject)`, `refs/remotes/${remoteName}/`],
+      ['for-each-ref', '--sort=-committerdate', `--format=%(refname:short)${delimiter}%(committerdate:iso8601-strict)${delimiter}%(objectname:short)${delimiter}%(subject)`, `refs/remotes/${remoteName}/`],
       { cwd }
     );
 

package/src/git/commands.js

@@ -261,8 +261,12 @@ async function getCommitsByDay(branchName, days = 7, cwd) {
   const counts = new Array(days).fill(0);
 
   try {
+    // %cI is strict ISO 8601 (YYYY-MM-DDTHH:MM:SS±HH:MM). %ci uses a
+    // space separator and a compact ±HHMM offset — V8 parses it today,
+    // but the spec doesn't require engines to accept non-strict forms,
+    // so rely on the strict variant for Date(string) parsing.
     const { stdout } = await execGit(
-      ['log', branchName, '--format=%ci', `--since=${days} days ago`],
+      ['log', branchName, '--format=%cI', `--since=${days} days ago`],
       { cwd, timeout: 10000 }
     );
 

package/src/server/coordinator.js

@@ -459,12 +459,26 @@ class Coordinator {
 
   /**
    * Send a JSON message over a socket.
+   *
+   * Honours outbound backpressure: if the per-socket write buffer is
+   * already at or above MAX_IPC_BUFFER, drop the worker rather than
+   * letting Node's internal buffer grow without bound. A wedged or
+   * paused worker would otherwise let coordinator memory climb on
+   * every pushState / command broadcast — symmetric with the inbound
+   * MAX_IPC_BUFFER policy in _handleWorkerConnection. The worker is
+   * expected to reconnect; until it does, dropping it is preferable
+   * to OOM-ing the coordinator.
+   *
    * @param {net.Socket} socket
    * @param {Object} msg
    * @private
    */
   _sendMessage(socket, msg) {
     try {
+      if (socket.writableLength >= MAX_IPC_BUFFER) {
+        socket.destroy();
+        return;
+      }
       socket.write(JSON.stringify(msg) + '\n');
     } catch (e) { /* peer socket closed between iteration and write — peer will reconnect if it recovers */ }
   }
@@ -643,12 +657,25 @@ class Worker {
   // ─── Private ─────────────────────────────────────────────────
 
   /**
+   * Send a JSON message to the coordinator.
+   *
+   * Outbound backpressure mirrors Coordinator._sendMessage: if the
+   * write buffer already exceeds MAX_IPC_BUFFER, destroy the socket
+   * rather than letting state pushes accumulate unboundedly while
+   * a wedged coordinator can't drain them. The worker's _connected
+   * flag flips to false on socket close, so subsequent pushState
+   * calls become no-ops until reconnect.
+   *
    * @param {Object} msg
    * @private
    */
   _send(msg) {
     if (this.socket && this._connected) {
       try {
+        if (this.socket.writableLength >= MAX_IPC_BUFFER) {
+          this.socket.destroy();
+          return;
+        }
         this.socket.write(JSON.stringify(msg) + '\n');
       } catch (e) { /* coordinator socket closed between isConnected() check and write */ }
     }
@@ -694,4 +721,5 @@ module.exports = {
   WATCHTOWER_DIR,
   LOCK_FILE,
   SOCKET_PATH,
+  MAX_IPC_BUFFER,
 };