From 6f84e6fc026dfdc14ee86f8352dba78bf5de6012 Mon Sep 17 00:00:00 2001
From: HerenderKumar <herender121112@gmail.com>
Date: Tue, 14 Jul 2026 10:34:59 +0530
Subject: [PATCH] fix(watch): point the missing-watchdog hint at the [watch]
 extra (#1203)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`graphify watch` without watchdog said to run `pip install watchdog`,
which does nothing for uv tool / pipx installs — the package lives in
an isolated env, so users followed the hint and stayed broken (#1203).
Point the error at the [watch] extra instead, and document the extra
in the README: optional-extras table row plus notes on the two command
reference lines that show `watch`.
---
 README.md           | 5 +++--
 graphify/watch.py   | 2 +-
 tests/test_watch.py | 2 +-
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 0a883e75b..52c4f7823 100644
--- a/README.md
+++ b/README.md
@@ -245,6 +245,7 @@ Codex users also need `multi_agent = true` under `[features]` in `~/.codex/confi
 | `mcp` | MCP stdio server | `uv tool install "graphifyy[mcp]"` |
 | `neo4j` | Neo4j push support | `uv tool install "graphifyy[neo4j]"` |
 | `falkordb` | FalkorDB push support | `uv tool install "graphifyy[falkordb]"` |
+| `watch` | `graphify watch` auto-rebuild on file changes | `uv tool install "graphifyy[watch]"` |
 | `svg` | SVG graph export | `uv tool install "graphifyy[svg]"` |
 | `leiden` | Leiden community detection (Python < 3.13 only) | `uv tool install "graphifyy[leiden]"` |
 | `ollama` | Ollama local inference | `uv tool install "graphifyy[ollama]"` |
@@ -625,7 +626,7 @@ graphify-out/
 /graphify ./raw --neo4j-push bolt://localhost:7687
 /graphify ./raw --falkordb         # generate cypher.txt for FalkorDB
 /graphify ./raw --falkordb-push falkordb://localhost:6379
-/graphify ./raw --watch            # auto-sync as files change
+/graphify ./raw --watch            # auto-sync as files change (needs the [watch] extra)
 /graphify ./raw --mcp              # start MCP stdio server
 
 /graphify add https://arxiv.org/abs/1706.03762
@@ -741,7 +742,7 @@ GRAPHIFY_TRIAGE_BACKEND=kimi graphify prs --triage   # use a specific backend fo
 graphify clone https://github.com/karpathy/nanoGPT
 graphify merge-graphs a.json b.json --out merged.json
 graphify --version                                    # print installed version
-graphify watch ./src
+graphify watch ./src                # needs the [watch] extra
 graphify check-update ./src
 graphify update ./src
 graphify update ./src --no-cluster  # skip reclustering, write raw AST graph only
diff --git a/graphify/watch.py b/graphify/watch.py
index 14454bf08..9f754c694 100644
--- a/graphify/watch.py
+++ b/graphify/watch.py
@@ -1184,7 +1184,7 @@ def watch(watch_path: Path, debounce: float = 3.0) -> None:
         from watchdog.observers.polling import PollingObserver
         from watchdog.events import FileSystemEventHandler
     except ImportError as e:
-        raise ImportError("watchdog not installed. Run: pip install watchdog") from e
+        raise ImportError('watchdog not installed. Run: uv tool install "graphifyy[watch]"') from e
 
     last_trigger: float = 0.0
     pending: bool = False
diff --git a/tests/test_watch.py b/tests/test_watch.py
index 67c68639d..753561c6c 100644
--- a/tests/test_watch.py
+++ b/tests/test_watch.py
@@ -98,7 +98,7 @@ def mock_import(name, *args, **kwargs):
     monkeypatch.setattr(builtins, "__import__", mock_import)
 
     from graphify.watch import watch
-    with pytest.raises(ImportError, match="watchdog not installed"):
+    with pytest.raises(ImportError, match=r"watchdog not installed.*graphifyy\[watch\]"):
         watch(tmp_path)