feat(cli): watch files with event streams

- Add a private SSE endpoint that emits file change events for authenticated clients.
- Replace the watch sleep loop with watchdog local file events and remote SSE triggers.
- Debounce local event bursts and keep watch running after transient sync failures.
- Add watchdog as a standalone CLI dependency and cover watch behavior in tests.
- Bump NanoShare to 1.25.0 and the standalone CLI to 0.4.0.

cli/nanoshare_client/cli.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 import argparse
 import json
 import sys
-import time
 from pathlib import Path
 
 from .app import make_client
@@ -14,6 +13,7 @@ from .config import DEFAULT_CONFIG
 from .remote_path import join_remote_path
 from .sync import sync_once
 from .table import format_table
+from .watch import watch_loop
 
 DEFAULT_NODE = 'picoshare'
 
@@ -99,12 +99,7 @@ def _cmd_sync(args) -> int:
     client.close()
 
 def _cmd_watch(args) -> int:
-  print(f'watching {args.folder} every {args.interval}s')
-  while True:
-    code = _cmd_sync(args)
-    if code:
-      return code
-    time.sleep(args.interval)
+  return watch_loop(args, _cmd_sync)
 
 def _cmd_completion(args) -> int:
   try:

cli/nanoshare_client/client.py

@@ -45,11 +45,17 @@ def list_remote(client, node: str) -> list[dict]:
   files = result.get('files', []) if isinstance(result, dict) else []
   return files if isinstance(files, list) else []
 
-def download_url(client, node: str, file_id: str) -> str:
+def node_url(client, node: str, path: str) -> str:
   base = client.registry.get(node)
   if not base:
     raise RuntimeError(f'unknown node: {node}')
-  return f"{base.rstrip('/')}/api/files/{quote(file_id, safe='')}/download"
+  return f"{base.rstrip('/')}{path}"
+
+def download_url(client, node: str, file_id: str) -> str:
+  return node_url(client, node, f"/api/files/{quote(file_id, safe='')}/download")
+
+def events_url(client, node: str) -> str:
+  return node_url(client, node, '/api/files/events')
 
 def download(client, node: str, file_id: str, path: Path) -> None:
   path.parent.mkdir(parents=True, exist_ok=True)

cli/nanoshare_client/watch.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Callable
+
+import httpx
+
+from .client import events_url
+from .ignore import is_ignored, load_ignore_patterns
+from .sync import relative, state_path, SYNC_DIR_NAME
+
+SyncFunc = Callable[[object], int]
+
+class _ChangeFlag:
+  def __init__(self) -> None:
+    self.event = threading.Event()
+
+  def notify(self) -> None:
+    self.event.set()
+
+  def wait(self, timeout: float) -> bool:
+    return self.event.wait(timeout)
+
+  def clear(self) -> None:
+    self.event.clear()
+
+def _is_relevant_path(root: Path, path: str, ignore_patterns: list[str]) -> bool:
+  try:
+    candidate = Path(path).expanduser().resolve()
+    rel = relative(root, candidate)
+  except ValueError:
+    return False
+  if candidate == state_path(root) or root / SYNC_DIR_NAME in candidate.parents:
+    return False
+  return not is_ignored(rel, ignore_patterns)
+
+def _remote_events_thread(args, flag: _ChangeFlag, stop: threading.Event) -> threading.Thread:
+  def run() -> None:
+    while not stop.is_set():
+      client = None
+      try:
+        from .app import make_client
+        client = make_client(args)
+        headers = {'Accept': 'text/event-stream', **client.auth_headers()}
+        with httpx.Client(timeout=None) as http:
+          with http.stream('GET', events_url(client, args.node), headers=headers) as response:
+            response.raise_for_status()
+            for line in response.iter_lines():
+              if stop.is_set():
+                return
+              if line.startswith('event: files.changed'):
+                flag.notify()
+      except Exception as exc:
+        if not stop.is_set():
+          print(f'remote event stream unavailable; retrying in 30s: {exc}', file=sys.stderr)
+          stop.wait(30)
+      finally:
+        if client:
+          client.close()
+
+  thread = threading.Thread(target=run, daemon=True)
+  thread.start()
+  return thread
+
+def _watchdog_observer(root: Path, ignore_patterns: list[str], flag: _ChangeFlag):
+  from watchdog.events import FileSystemEventHandler
+  from watchdog.observers import Observer
+
+  class Handler(FileSystemEventHandler):
+    def on_any_event(self, event):
+      paths = [event.src_path]
+      dest_path = getattr(event, 'dest_path', None)
+      if dest_path:
+        paths.append(dest_path)
+      if any(_is_relevant_path(root, path, ignore_patterns) for path in paths):
+        flag.notify()
+
+  observer = Observer()
+  observer.schedule(Handler(), str(root), recursive=True)
+  observer.start()
+  return observer
+
+def watch_loop(args, sync_func: SyncFunc) -> int:
+  root = Path(args.folder).expanduser().resolve()
+  root.mkdir(parents=True, exist_ok=True)
+  ignore_patterns = load_ignore_patterns(root, getattr(args, 'ignore', None))
+  interval = max(float(getattr(args, 'interval', 10.0)), 0.1)
+  flag = _ChangeFlag()
+  observer = None
+  stop_events = threading.Event()
+  events_thread = None
+
+  try:
+    try:
+      observer = _watchdog_observer(root, ignore_patterns, flag)
+      print(f'watching {args.folder} for local changes; remote events with {interval}s fallback')
+    except Exception as exc:
+      print(f'watchdog unavailable, polling every {interval}s: {exc}', file=sys.stderr)
+      print(f'watching {args.folder} every {interval}s')
+
+    events_thread = _remote_events_thread(args, flag, stop_events)
+
+    while True:
+      flag.clear()
+      code = sync_func(args)
+      if code:
+        print(f'watch sync failed; retrying in {interval}s', file=sys.stderr)
+        flag.wait(interval)
+        continue
+
+      if flag.wait(interval):
+        flag.clear()
+        time.sleep(1.0)
+        while flag.wait(1.0):
+          flag.clear()
+  except KeyboardInterrupt:
+    return 0
+  finally:
+    stop_events.set()
+    if observer:
+      observer.stop()
+      observer.join(timeout=5)
+    if events_thread:
+      events_thread.join(timeout=5)

cli/pyproject.toml

@@ -1,11 +1,12 @@
 [project]
 name = "nanoshare-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "NanoShare desktop CLI and folder sync client"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
   "httpx==0.28.1",
+  "watchdog==6.0.0",
 ]
 
 [project.scripts]