thinkstack-core 4.0.0__py3-none-any.whl

thinkstack_core/daemon/supervisor.py

@@ -0,0 +1,293 @@
+"""
+Background daemon supervisor for the ThinkStack CLI (S26).
+
+The daemon runs a filesystem watcher in the background and optionally the
+unified ThinkStack server.  It writes its PID to `.GCC/thinkstack_daemon.pid` and
+logs to `.GCC/thinkstack_daemon.log`.
+
+CLI commands:
+    thinkstack daemon start    # idempotent
+    thinkstack daemon stop
+    thinkstack daemon status
+    thinkstack daemon logs
+"""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+
+PID_FILE_NAME = "thinkstack_daemon.pid"
+LOG_FILE_NAME = "thinkstack_daemon.log"
+
+
+def _gcc_dir(project_root: Path) -> Path:
+    """Resolve the .GCC directory for a project root, ensuring it exists."""
+    from thinkstack_core import GCCRepository
+
+    repo = GCCRepository.at(project_root)
+    if not repo.is_initialized():
+        raise RuntimeError(f"No initialized .GCC/ found at {project_root}")
+    return repo.gcc_dir
+
+
+def _read_pid(gcc_dir: Path) -> Optional[int]:
+    """Read the daemon PID from the PID file, if present and valid."""
+    pid_path = gcc_dir / PID_FILE_NAME
+    if not pid_path.exists():
+        return None
+    try:
+        return int(pid_path.read_text(encoding="utf-8").strip())
+    except Exception:
+        return None
+
+
+def _is_alive(pid: int) -> bool:
+    """Check whether a process with the given PID is still running."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False
+
+
+def _wait_for_pid(
+    gcc_dir: Path,
+    timeout: float = 2.0,
+    interval: float = 0.1,
+) -> Optional[int]:
+    """Wait for a daemon PID file to appear and refer to a live process."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        pid = _read_pid(gcc_dir)
+        if pid is not None and _is_alive(pid):
+            return pid
+        time.sleep(interval)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# daemon process entry point
+# ---------------------------------------------------------------------------
+
+
+def _run_daemon(
+    project_root: Optional[str] = None,
+    run_server: bool = False,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    stop_event: Optional[threading.Event] = None,
+) -> None:
+    """Entry point for the daemon process.
+
+    This function is invoked by the subprocess spawned in `start_daemon`.
+    It writes the PID file, starts the project watcher, and optionally runs the
+    unified server.  The process keeps running until it receives SIGTERM/SIGINT.
+    """
+    if project_root is None:
+        project_root = os.environ.get("THINKSTACK_DAEMON_ROOT", str(Path.cwd()))
+    root = Path(project_root).resolve()
+
+    gcc_dir = _gcc_dir(root)
+    pid_path = gcc_dir / PID_FILE_NAME
+    pid_path.write_text(str(os.getpid()), encoding="utf-8")
+
+    if stop_event is None:
+        stop_event = threading.Event()
+
+    def _handle_signal(signum: int, frame: Any) -> None:
+        stop_event.set()
+
+    try:
+        signal.signal(signal.SIGTERM, _handle_signal)
+        signal.signal(signal.SIGINT, _handle_signal)
+    except Exception:
+        # May fail in some test environments; continue without signal handling.
+        pass
+
+    try:
+        from thinkstack_core.daemon.watcher import ProjectWatcher
+
+        watcher = ProjectWatcher(root)
+        watcher.start()
+    except Exception as exc:
+        print(f"Failed to start watcher: {exc}", file=sys.stderr)
+        pid_path.unlink(missing_ok=True)
+        raise
+
+    server_thread: Optional[threading.Thread] = None
+    if run_server:
+        try:
+            from thinkstack_core.serve import serve_all
+
+            def _serve() -> None:
+                try:
+                    serve_all(host=host, port=port, gcc_path=str(root))
+                except Exception as exc:
+                    print(f"Unified server exited: {exc}", file=sys.stderr)
+
+            server_thread = threading.Thread(target=_serve, daemon=True)
+            server_thread.start()
+        except Exception as exc:
+            print(f"Failed to start unified server: {exc}", file=sys.stderr)
+
+    print(f"ThinkStack daemon started (PID {os.getpid()}) watching {root}")
+    sys.stdout.flush()
+
+    try:
+        while not stop_event.is_set():
+            stop_event.wait(1.0)
+    finally:
+        watcher.stop()
+        print(f"ThinkStack daemon stopped (PID {os.getpid()})")
+        sys.stdout.flush()
+        pid_path.unlink(missing_ok=True)
+
+
+# ---------------------------------------------------------------------------
+# process spawning
+# ---------------------------------------------------------------------------
+
+
+def _build_daemon_command(project_root: Path, run_server: bool, host: str, port: int) -> list[str]:
+    """Build the command used to spawn the daemon subprocess."""
+    code = (
+        "from thinkstack_core.daemon.supervisor import _run_daemon; "
+        f"_run_daemon(project_root={str(project_root)!r}, run_server={run_server!r}, "
+        f"host={host!r}, port={port!r})"
+    )
+    return [sys.executable, "-c", code]
+
+
+# ---------------------------------------------------------------------------
+# public control functions
+# ---------------------------------------------------------------------------
+
+
+def start_daemon(
+    project_root: Path,
+    run_server: bool = False,
+    host: str = "127.0.0.1",
+    port: int = 8765,
+    popen_factory: Optional[Callable[..., Any]] = None,
+) -> tuple[bool, str]:
+    """Start the daemon if it is not already running.
+
+    Returns (success, message).  If the daemon is already running, reports
+    the existing PID without starting a new process (idempotent).
+    """
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError as exc:
+        return False, str(exc)
+
+    pid = _read_pid(gcc_dir)
+    if pid is not None and _is_alive(pid):
+        return True, f"ThinkStack daemon already running (PID {pid})"
+
+    log_path = gcc_dir / LOG_FILE_NAME
+    cmd = _build_daemon_command(project_root, run_server, host, port)
+
+    env = dict(os.environ)
+    env["THINKSTACK_DAEMON_ROOT"] = str(project_root)
+
+    if popen_factory is None:
+        popen_factory = subprocess.Popen
+
+    with open(log_path, "a", encoding="utf-8") as log_f:
+        process = popen_factory(
+            cmd,
+            stdout=log_f,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,
+            env=env,
+        )
+
+    new_pid = _wait_for_pid(gcc_dir)
+    if new_pid is not None:
+        return True, f"ThinkStack daemon started (PID {new_pid})"
+    return False, (
+        f"Daemon subprocess launched (PID {process.pid}) but PID file "
+        f"was not written to {gcc_dir / PID_FILE_NAME}"
+    )
+
+
+def stop_daemon(project_root: Path) -> tuple[bool, str]:
+    """Stop the daemon and clean up its PID file.
+
+    Returns (success, message).  If no daemon is running, returns a message
+    explaining that and cleans up any stale PID file.
+    """
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError as exc:
+        return False, str(exc)
+
+    pid = _read_pid(gcc_dir)
+    pid_path = gcc_dir / PID_FILE_NAME
+
+    if pid is None:
+        return False, "ThinkStack daemon is not running"
+
+    if not _is_alive(pid):
+        pid_path.unlink(missing_ok=True)
+        return False, f"Daemon PID {pid} is not alive; cleaned up stale PID file"
+
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except (OSError, ProcessLookupError):
+        pid_path.unlink(missing_ok=True)
+        return False, f"Failed to signal daemon PID {pid}; cleaned up PID file"
+
+    for _ in range(20):
+        if not _is_alive(pid):
+            break
+        time.sleep(0.1)
+
+    if _is_alive(pid):
+        try:
+            os.kill(pid, signal.SIGKILL)
+            time.sleep(0.1)
+        except (OSError, ProcessLookupError):
+            pass
+
+    pid_path.unlink(missing_ok=True)
+    return True, f"ThinkStack daemon stopped (PID {pid})"
+
+
+def daemon_status(project_root: Path) -> dict[str, Any]:
+    """Return a status dict for the daemon."""
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError as exc:
+        return {"running": False, "pid": None, "log_path": None, "error": str(exc)}
+
+    pid = _read_pid(gcc_dir)
+    log_path = gcc_dir / LOG_FILE_NAME
+    if pid is None:
+        return {"running": False, "pid": None, "log_path": str(log_path)}
+    alive = _is_alive(pid)
+    if not alive:
+        return {"running": False, "pid": pid, "log_path": str(log_path)}
+    return {"running": True, "pid": pid, "log_path": str(log_path)}
+
+
+def daemon_logs(project_root: Path, lines: int = 50) -> list[str]:
+    """Return the last N lines of the daemon log file."""
+    try:
+        gcc_dir = _gcc_dir(project_root)
+    except RuntimeError:
+        return []
+
+    log_path = gcc_dir / LOG_FILE_NAME
+    if not log_path.exists():
+        return []
+    with log_path.open("r", encoding="utf-8") as f:
+        return f.read().splitlines()[-lines:]

thinkstack_core/daemon/watcher.py

@@ -0,0 +1,244 @@
+"""
+Filesystem watcher for the ThinkStack background daemon (S26).
+
+Monitors project files for create/modify/delete events and emits them as
+`fs_change` events to `.GCC/events.log.jsonl`.
+
+Uses `watchdog` when available; otherwise falls back to a simple polling
+implementation.
+"""
+from __future__ import annotations
+
+import os
+import threading
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+
+def _emit_fs_change(project_root: Path, file_path: Path, event_kind: str) -> None:
+    """Append a fs_change event to the project's event log.
+
+    Uses the GCCRepository._append_event helper so the hash chain and
+    optional signing remain intact.
+    """
+    from thinkstack_core import GCCRepository
+
+    repo = GCCRepository.at(project_root)
+    if not repo.is_initialized():
+        return
+
+    mtime: Optional[float] = None
+    try:
+        if file_path.exists():
+            mtime = file_path.stat().st_mtime
+    except Exception:
+        pass
+
+    payload = {
+        "path": str(file_path),
+        "event_kind": event_kind,
+        "mtime": mtime,
+    }
+
+    try:
+        repo._append_event("fs_change", payload)
+    except Exception:
+        # Last-resort fallback: write directly without hash chain.
+        # This should only happen if the repo backend is unavailable.
+        try:
+            import json
+
+            log_path = repo.gcc_dir / "events.log.jsonl"
+            entry = {
+                "timestamp": _now_iso(),
+                "actor": "thinkstack-daemon",
+                "event_type": "fs_change",
+                "payload": payload,
+            }
+            with log_path.open("a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+        except Exception:
+            pass
+
+
+def _now_iso() -> str:
+    import datetime as dt
+    return dt.datetime.now(tz=dt.timezone.utc).isoformat()
+
+
+def _is_inside_gcc(path: Path, gcc_dir: Path) -> bool:
+    """Return True if path is inside or equal to the .GCC directory."""
+    try:
+        return str(path.resolve()).startswith(str(gcc_dir.resolve()))
+    except Exception:
+        return False
+
+
+# ---------------------------------------------------------------------------
+# watchdog-based implementation
+# ---------------------------------------------------------------------------
+
+try:
+    from watchdog.events import FileSystemEventHandler  # type: ignore
+    from watchdog.observers import Observer  # type: ignore
+
+    _HAS_WATCHDOG = True
+
+    class _WatchdogHandler(FileSystemEventHandler):  # type: ignore[misc]
+        def __init__(self, watcher: "ProjectWatcher") -> None:
+            self._watcher = watcher
+
+        def on_created(self, event: Any) -> None:
+            self._watcher._emit(Path(event.src_path), "created")  # noqa: SLF001
+
+        def on_modified(self, event: Any) -> None:
+            self._watcher._emit(Path(event.src_path), "modified")  # noqa: SLF001
+
+        def on_deleted(self, event: Any) -> None:
+            self._watcher._emit(Path(event.src_path), "deleted")  # noqa: SLF001
+
+except Exception:  # pragma: no cover
+    _HAS_WATCHDOG = False
+    Observer: Any = None  # type: ignore[no-redef]
+    FileSystemEventHandler: Any = None  # type: ignore[no-redef]
+
+
+# ---------------------------------------------------------------------------
+# polling-based implementation
+# ---------------------------------------------------------------------------
+
+
+class _PollingWatcher:
+    def __init__(self, project_root: Path, gcc_dir: Path, emit: Any, interval: float) -> None:
+        self.project_root = project_root
+        self.gcc_dir = gcc_dir
+        self.emit = emit
+        self.interval = interval
+        self._stop_event = threading.Event()
+        self._thread: Optional[threading.Thread] = None
+
+    def _build_snapshot(self) -> dict[str, float]:
+        snap: dict[str, float] = {}
+        for root, dirs, files in os.walk(self.project_root):
+            root_path = Path(root)
+            if _is_inside_gcc(root_path, self.gcc_dir):
+                dirs[:] = []
+                continue
+            for name in files:
+                p = root_path / name
+                if _is_inside_gcc(p, self.gcc_dir):
+                    continue
+                try:
+                    snap[str(p.resolve())] = p.stat().st_mtime
+                except Exception:
+                    pass
+        return snap
+
+    def _detect_changes(self, old: dict[str, float], new: dict[str, float]) -> None:
+        for p, mtime in new.items():
+            if p not in old:
+                self.emit(Path(p), "created")
+            elif old[p] != mtime:
+                self.emit(Path(p), "modified")
+        for p in old:
+            if p not in new:
+                self.emit(Path(p), "deleted")
+
+    def _run(self) -> None:
+        snapshot = self._build_snapshot()
+        while not self._stop_event.is_set():
+            self._stop_event.wait(self.interval)
+            if self._stop_event.is_set():
+                break
+            new_snapshot = self._build_snapshot()
+            self._detect_changes(snapshot, new_snapshot)
+            snapshot = new_snapshot
+
+    def start(self) -> None:
+        self._stop_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop_event.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+
+
+# ---------------------------------------------------------------------------
+# public watcher
+# ---------------------------------------------------------------------------
+
+
+class ProjectWatcher:
+    """Watch a project root for file changes and emit `fs_change` events."""
+
+    def __init__(self, project_root: Path, poll_interval: float = 1.0, use_watchdog: bool = True) -> None:
+        self.project_root = Path(project_root).resolve()
+        self.gcc_dir = self.project_root / ".GCC"
+        self.poll_interval = poll_interval
+        self.use_watchdog = use_watchdog
+        self._observer: Optional[Any] = None
+        self._polling: Optional[_PollingWatcher] = None
+
+    def _is_gcc_path(self, path: Path) -> bool:
+        return _is_inside_gcc(path, self.gcc_dir)
+
+    def _emit(self, path: Path, event_kind: str) -> None:
+        if self._is_gcc_path(path):
+            return
+        _emit_fs_change(self.project_root, path, event_kind)
+
+    def _start_watchdog(self) -> bool:
+        if not self.use_watchdog or not _HAS_WATCHDOG:
+            return False
+        observer = Observer()
+        handler = _WatchdogHandler(self)
+        observer.schedule(handler, str(self.project_root), recursive=True)
+        observer.start()
+        self._observer = observer
+        return True
+
+    def _start_polling(self) -> None:
+        polling = _PollingWatcher(
+            self.project_root,
+            self.gcc_dir,
+            self._emit,
+            self.poll_interval,
+        )
+        polling.start()
+        self._polling = polling
+
+    def start(self) -> None:
+        """Start watching the project root.
+
+        Tries to use watchdog if installed; otherwise falls back to polling.
+        """
+        if not self._start_watchdog():
+            self._start_polling()
+
+    def stop(self) -> None:
+        """Stop watching the project root."""
+        if self._observer is not None:
+            try:
+                self._observer.stop()
+                self._observer.join(timeout=2.0)
+            except Exception:
+                pass
+            self._observer = None
+        if self._polling is not None:
+            self._polling.stop()
+            self._polling = None
+
+    def is_alive(self) -> bool:
+        """Return True if the watcher is still running."""
+        if self._observer is not None:
+            try:
+                return self._observer.is_alive()
+            except Exception:
+                return False
+        if self._polling is not None:
+            return self._polling._thread is not None and self._polling._thread.is_alive()
+        return False