novacode-cli 1.2.0__py3-none-any.whl

novacode_cli/daemons/__init__.py

@@ -0,0 +1 @@
+"""Detached-daemon support: a JSON pid registry for long-lived background processes."""

novacode_cli/daemons/registry.py

@@ -0,0 +1,342 @@
+"""Detached-daemon registry — a JSON file-backed pid store that survives restarts.
+
+A *daemon* is a long-lived background process launched by the ``daemon`` tool that
+outlives the CLI session (unlike an in-session :class:`~novacode_cli.shell.jobs.BackgroundJob`,
+which dies with the CLI). This module tracks those daemons by name in a small JSON
+file under ``~/.nova/daemons/registry.json`` so the agent can list, check, and stop
+them across CLI restarts.
+
+Because the registry outlives the process that wrote it, three things that would
+be safe in a single session are not safe here, and each is handled explicitly:
+
+**A pid is not an identity.** Pids are recycled, so a stale entry can name an
+unrelated live process. Every entry records the process's real creation time and
+:func:`is_ours` checks it before anything acts on the pid — without that,
+stopping a long-dead daemon could force-kill a stranger's process tree.
+
+**Another session may be writing too.** The registry is explicitly shared, so a
+thread lock is not enough: reads and writes take a cross-process file lock, and
+the temp file is per-process, or concurrent sessions lose each other's entries
+(measured: 43 of 80) and can promote a half-written file over the real one.
+
+**A name becomes a path.** Names are sanitized before they reach the filesystem;
+``../..`` in a name would otherwise write a log outside the daemons directory.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import threading
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+#: Directory holding daemon logs + the registry.
+DAEMONS_DIR = Path.home() / ".nova" / "daemons"
+#: Registry file path.
+REGISTRY_PATH = DAEMONS_DIR / "registry.json"
+
+_lock = threading.RLock()
+
+#: Maximum wait for an OS lock held by a live or stalled writer.
+_LOCK_TIMEOUT = 5.0
+
+#: Tolerance when matching a recorded creation time against the live process.
+#: Windows FILETIME and the epoch conversion round; the value only needs to be
+#: far tighter than the gap between a pid dying and being reissued.
+_CREATE_TIME_TOLERANCE = 0.001
+
+
+def _lock_path() -> Path:
+    return REGISTRY_PATH.with_name(REGISTRY_PATH.name + ".lock")
+
+
+@contextlib.contextmanager
+def _file_lock() -> Iterator[None]:
+    """Use an OS lock that a dead process releases without unlink races."""
+    path = _lock_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    deadline = time.monotonic() + _LOCK_TIMEOUT
+    fd = os.open(str(path), os.O_CREAT | os.O_RDWR)
+    locked = False
+    try:
+        while not locked:
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                if os.name == "nt":
+                    import msvcrt
+
+                    msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+                else:
+                    import fcntl
+
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                locked = True
+            except OSError as exc:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError("Daemon registry lock timed out") from exc
+                time.sleep(0.01)
+        yield
+    finally:
+        if locked:
+            os.lseek(fd, 0, os.SEEK_SET)
+            if os.name == "nt":
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            else:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+def safe_name(name: str) -> str:
+    """Reduce *name* to something that cannot escape the daemons directory.
+
+    ``name`` is chosen by the agent and is interpolated into a log path, so
+    ``../../x`` would otherwise write outside ``~/.nova/daemons``. Mirrors the
+    sanitizer in :mod:`novacode_cli.integrations.sandbox_registry`.
+    """
+    cleaned = "".join(c for c in str(name) if c.isalnum() or c in "-_.")[:120]
+    # A name of dots alone still resolves to a parent directory.
+    if not cleaned or set(cleaned) <= {"."}:
+        return "unnamed"
+    return cleaned
+
+
+@dataclass
+class DaemonInfo:
+    """A registered daemon's metadata."""
+
+    name: str
+    pid: int
+    command: str
+    log_path: str
+    started_at: float
+    cwd: str = "."
+    #: The OS-reported process creation time, used to tell this daemon apart
+    #: from whatever later inherits its pid. 0.0 when the platform could not
+    #: report one (then only liveness is known — see :func:`is_ours`).
+    create_time: float = 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize to a JSON-able dict."""
+        return {
+            "name": self.name,
+            "pid": self.pid,
+            "command": self.command,
+            "log_path": self.log_path,
+            "started_at": self.started_at,
+            "cwd": self.cwd,
+            "create_time": self.create_time,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DaemonInfo:
+        """Deserialize from a dict (as written by :meth:`to_dict`)."""
+        return cls(
+            name=str(data.get("name", "")),
+            pid=int(data.get("pid", 0)),
+            command=str(data.get("command", "")),
+            log_path=str(data.get("log_path", "")),
+            started_at=float(data.get("started_at", 0.0)),
+            cwd=str(data.get("cwd", ".")),
+            create_time=float(data.get("create_time", 0.0) or 0.0),
+        )
+
+
+def _read() -> dict[str, dict[str, Any]]:
+    if not REGISTRY_PATH.exists():
+        return {}
+    try:
+        data = json.loads(REGISTRY_PATH.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            return data
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return {}
+
+
+def _write(data: dict[str, dict[str, Any]]) -> None:
+    DAEMONS_DIR.mkdir(parents=True, exist_ok=True)
+    # Per-process temp name: a shared one lets two sessions interleave into a
+    # single half-written file and then promote it over the real registry.
+    tmp = REGISTRY_PATH.with_name(f"{REGISTRY_PATH.name}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
+        tmp.replace(REGISTRY_PATH)
+    finally:
+        with contextlib.suppress(OSError):
+            if tmp.exists():
+                tmp.unlink()
+
+
+def register(info: DaemonInfo) -> None:
+    """Add or update a daemon in the registry."""
+    with _lock, _file_lock():
+        data = _read()
+        data[info.name] = info.to_dict()
+        _write(data)
+
+
+def unregister(name: str) -> bool:
+    """Remove a daemon by name. Returns True if it was present."""
+    with _lock, _file_lock():
+        data = _read()
+        if name not in data:
+            return False
+        del data[name]
+        _write(data)
+        return True
+
+
+def get(name: str) -> DaemonInfo | None:
+    """Look up a daemon by name, or None."""
+    with _lock, _file_lock():
+        data = _read()
+        raw = data.get(name)
+        if raw is None:
+            return None
+        return DaemonInfo.from_dict(raw)
+
+
+def list_daemons() -> list[DaemonInfo]:
+    """Return all registered daemons, sorted by name."""
+    with _lock, _file_lock():
+        data = _read()
+        return sorted(
+            (DaemonInfo.from_dict(raw) for raw in data.values()),
+            key=lambda d: d.name,
+        )
+
+
+def process_created_at(pid: int) -> float | None:
+    """The OS-reported creation time of *pid* as a unix timestamp, or None.
+
+    None means "this platform could not tell us", not "the process is gone".
+    Windows and Linux are covered; elsewhere identity cannot be confirmed and
+    callers fall back to liveness alone.
+    """
+    if pid <= 0:
+        return None
+    if os.name == "nt":
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+            handle = kernel32.OpenProcess(0x1000, False, int(pid))
+            if not handle:
+                return None
+            try:
+                creation = wintypes.FILETIME()
+                exit_t, kernel_t, user_t = (
+                    wintypes.FILETIME(),
+                    wintypes.FILETIME(),
+                    wintypes.FILETIME(),
+                )
+                ok = kernel32.GetProcessTimes(
+                    handle,
+                    ctypes.byref(creation),
+                    ctypes.byref(exit_t),
+                    ctypes.byref(kernel_t),
+                    ctypes.byref(user_t),
+                )
+                if not ok:
+                    return None
+                ticks = (creation.dwHighDateTime << 32) | creation.dwLowDateTime
+                # FILETIME: 100 ns units since 1601-01-01.
+                return ticks / 10_000_000.0 - 11_644_473_600.0
+            finally:
+                kernel32.CloseHandle(handle)
+        except Exception:  # noqa: BLE001 — probing must never raise
+            return None
+    try:
+        # Linux: field 22 of /proc/<pid>/stat is start time in clock ticks
+        # since boot; /proc/stat's btime is boot time in epoch seconds.
+        stat = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
+        fields = stat[stat.rindex(")") + 2 :].split()
+        start_ticks = float(fields[19])
+        hz = os.sysconf("SC_CLK_TCK")
+        boot = 0.0
+        for line in Path("/proc/stat").read_text(encoding="utf-8").splitlines():
+            if line.startswith("btime "):
+                boot = float(line.split()[1])
+                break
+        if not boot or not hz:
+            return None
+    except (OSError, ValueError, IndexError, AttributeError):
+        return None
+    return boot + start_ticks / hz
+
+
+def is_alive(pid: int) -> bool:
+    """True when a process with *pid* exists.
+
+    Conservative on purpose: only a *definite* "no such process" returns False.
+    An indeterminate probe (a live process we lack rights to open) must not read
+    as dead, or the caller starts a duplicate daemon and orphans the first.
+    """
+    if pid <= 0:
+        return False
+    if os.name == "posix":
+        try:
+            os.kill(pid, 0)
+        except ProcessLookupError:
+            return False
+        except PermissionError:
+            return True  # exists, owned by another user
+        except OSError:
+            return True  # indeterminate — assume alive
+        # kill(pid, 0) also succeeds for Linux zombies. A shell spawned by
+        # this process can remain unreaped until another Popen cleans up, but
+        # it has exited and cannot run or respond to another stop signal.
+        try:
+            stat = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
+            state = stat[stat.rindex(")") + 2:].split()[0]
+            if state in {"Z", "X", "x"}:
+                return False
+        except (OSError, ValueError, IndexError):
+            pass  # non-Linux POSIX or an indeterminate probe: keep liveness
+        return True
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined]
+        handle = kernel32.OpenProcess(0x1000, False, int(pid))  # QUERY_LIMITED
+        if not handle:
+            return False
+        try:
+            code = ctypes.c_ulong()
+            if kernel32.GetExitCodeProcess(handle, ctypes.byref(code)):
+                return code.value == 259  # STILL_ACTIVE
+            return True
+        finally:
+            kernel32.CloseHandle(handle)
+    except Exception:  # noqa: BLE001 — can't probe ⇒ assume alive
+        return True
+
+
+def is_ours(info: DaemonInfo) -> bool:
+    """True when *info*'s pid is still the daemon we registered.
+
+    A live pid is not enough. Pids are reused, and this registry survives
+    reboots, so an entry can name a process that merely inherited the number —
+    acting on that would stop (or force-kill the tree of) an unrelated process.
+    """
+    if not is_alive(info.pid):
+        return False
+    if not info.create_time:
+        # Recorded before creation times were captured, or a platform that
+        # cannot report one: liveness is all we know.
+        return True
+    actual = process_created_at(info.pid)
+    if actual is None:
+        return True
+    return abs(actual - info.create_time) <= _CREATE_TIME_TOLERANCE
+
+
+def log_path_for(name: str) -> Path:
+    """Return the log file path for a daemon (without creating it)."""
+    return DAEMONS_DIR / f"{safe_name(name)}.log"

novacode_cli/desktop_notifications.py

@@ -0,0 +1,302 @@
+"""Windows notifications with a click target belonging to the emitting TUI.
+
+Uses Shell_NotifyIcon directly: no command strings, protocol registration, or
+second Nova process is needed. The native window and icon live on one thread.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import queue
+import struct
+import sys
+import threading
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+ICON_PATH = Path(__file__).parent / "assets" / "Nova.png"
+
+
+def icon_resource(path: Path = ICON_PATH) -> bytes:
+    """Convert the packaged PNG to a Windows icon resource in memory."""
+    from PIL import Image
+
+    with Image.open(path) as image:
+        output = io.BytesIO()
+        image.convert("RGBA").save(output, format="ICO", sizes=[(32, 32)], bitmap_format="bmp")
+    data = output.getvalue()
+    length, offset = struct.unpack_from("<II", data, 14)
+    return data[offset : offset + length]
+
+
+class DesktopNotifier:
+    """Own a bounded set of native notifications until click, timeout, or exit."""
+
+    def __init__(self, activate, *, native=None):
+        self.activate = activate
+        self.commands = queue.Queue(maxsize=64)
+        self.closed = threading.Event()
+        self.ready = threading.Event()
+        self.native = native
+        self.thread = None
+        self.window = None
+
+    def start(self):
+        if self.thread is not None or sys.platform != "win32":
+            return
+        if self.native is None:
+            self.native = _WindowsShell()
+        self.window = self.native.capture_terminal()
+        self.thread = threading.Thread(target=self._run, name="nova-notifications", daemon=True)
+        self.thread.start()
+
+    def show(self, sid: str, notification_id: str, title: str, message: str):
+        if self.closed.is_set():
+            return
+        try:
+            self.commands.put_nowait((sid, notification_id, title, message))
+        except queue.Full:
+            logger.debug("Desktop notification queue full; retained in TUI")
+            return
+        if self.ready.is_set():
+            self.native.wake()
+
+    def close(self):
+        self.closed.set()
+        if self.ready.is_set():
+            self.native.stop()
+        if self.thread is not None and self.thread is not threading.current_thread():
+            self.thread.join(timeout=2)
+
+    def _clicked(self, sid, notification_id):
+        if self.closed.is_set():
+            return
+        self.native.focus(self.window)
+        self.activate(sid, notification_id)
+
+    def _run(self):
+        try:
+            self.native.open(icon_resource(), self._clicked)
+            self.ready.set()
+            if self.closed.is_set():
+                return
+            self.native.wake()
+            self.native.run(self.commands)
+        except Exception:  # noqa: BLE001 — retain the in-terminal notification
+            logger.warning("Windows desktop notifications unavailable", exc_info=True)
+        finally:
+            self.closed.set()
+            self.native.close()
+
+
+class _WindowsShell:
+    """Win32 message-loop adapter. All pointer-sized arguments are declared."""
+
+    CALLBACK = 0x8001
+    WAKE = 0x8002
+
+    def __init__(self):
+        import ctypes as c
+        from ctypes import wintypes as w
+
+        self.c, self.w = c, w
+        self.user = c.WinDLL("user32", use_last_error=True)
+        self.shell = c.WinDLL("shell32", use_last_error=True)
+        self.kernel = c.WinDLL("kernel32", use_last_error=True)
+        self.hwnd = None
+        self.icon = None
+        self.items = {}
+        self.next_id = 1
+        self.proc_type = c.WINFUNCTYPE(c.c_ssize_t, w.HWND, w.UINT, w.WPARAM, w.LPARAM)
+
+        class WindowClass(c.Structure):
+            _fields_ = [
+                ("style", w.UINT),
+                ("proc", self.proc_type),
+                ("class_extra", c.c_int),
+                ("window_extra", c.c_int),
+                ("instance", w.HINSTANCE),
+                ("icon", w.HICON),
+                ("cursor", w.HANDLE),
+                ("background", w.HBRUSH),
+                ("menu", w.LPCWSTR),
+                ("name", w.LPCWSTR),
+            ]
+
+        class NotifyData(c.Structure):
+            _fields_ = [
+                ("size", w.DWORD),
+                ("hwnd", w.HWND),
+                ("id", w.UINT),
+                ("flags", w.UINT),
+                ("callback", w.UINT),
+                ("icon", w.HICON),
+                ("tip", w.WCHAR * 128),
+                ("state", w.DWORD),
+                ("state_mask", w.DWORD),
+                ("info", w.WCHAR * 256),
+                ("version", w.UINT),
+                ("title", w.WCHAR * 64),
+                ("info_flags", w.DWORD),
+                ("guid", c.c_byte * 16),
+                ("balloon_icon", w.HICON),
+            ]
+
+        self.WindowClass, self.NotifyData = WindowClass, NotifyData
+        signatures = {
+            "GetForegroundWindow": ([], w.HWND),
+            "GetClassNameW": ([w.HWND, w.LPWSTR, c.c_int], c.c_int),
+            "GetWindowThreadProcessId": ([w.HWND, c.POINTER(w.DWORD)], w.DWORD),
+            "IsWindow": ([w.HWND], w.BOOL),
+            "ShowWindow": ([w.HWND, c.c_int], w.BOOL),
+            "SetForegroundWindow": ([w.HWND], w.BOOL),
+            "RegisterClassW": ([c.POINTER(WindowClass)], w.WORD),
+            "UnregisterClassW": ([w.LPCWSTR, w.HINSTANCE], w.BOOL),
+            "CreateWindowExW": (
+                [
+                    w.DWORD,
+                    w.LPCWSTR,
+                    w.LPCWSTR,
+                    w.DWORD,
+                    c.c_int,
+                    c.c_int,
+                    c.c_int,
+                    c.c_int,
+                    w.HWND,
+                    w.HMENU,
+                    w.HINSTANCE,
+                    w.LPVOID,
+                ],
+                w.HWND,
+            ),
+            "DefWindowProcW": ([w.HWND, w.UINT, w.WPARAM, w.LPARAM], c.c_ssize_t),
+            "PostMessageW": ([w.HWND, w.UINT, w.WPARAM, w.LPARAM], w.BOOL),
+            "GetMessageW": ([c.POINTER(w.MSG), w.HWND, w.UINT, w.UINT], c.c_int),
+            "TranslateMessage": ([c.POINTER(w.MSG)], w.BOOL),
+            "DispatchMessageW": ([c.POINTER(w.MSG)], c.c_ssize_t),
+            "DestroyWindow": ([w.HWND], w.BOOL),
+            "DestroyIcon": ([w.HICON], w.BOOL),
+            "CreateIconFromResourceEx": (
+                [c.POINTER(c.c_byte), w.DWORD, w.BOOL, w.DWORD, c.c_int, c.c_int, w.UINT],
+                w.HICON,
+            ),
+        }
+        for name, (args, result) in signatures.items():
+            function = getattr(self.user, name)
+            function.argtypes, function.restype = args, result
+        self.kernel.GetModuleHandleW.argtypes = [w.LPCWSTR]
+        self.kernel.GetModuleHandleW.restype = w.HINSTANCE
+        self.shell.Shell_NotifyIconW.argtypes = [w.DWORD, c.POINTER(NotifyData)]
+        self.shell.Shell_NotifyIconW.restype = w.BOOL
+
+    def capture_terminal(self):
+        hwnd = self.user.GetForegroundWindow()
+        name = self.c.create_unicode_buffer(256)
+        self.user.GetClassNameW(hwnd, name, len(name))
+        if name.value not in {
+            "CASCADIA_HOSTING_WINDOW_CLASS",
+            "ConsoleWindowClass",
+            "VirtualConsoleClass",
+        }:
+            return None
+        pid = self.w.DWORD()
+        self.user.GetWindowThreadProcessId(hwnd, self.c.byref(pid))
+        return hwnd, pid.value
+
+    def focus(self, window):
+        if not window:
+            return
+        hwnd, expected_pid = window
+        pid = self.w.DWORD()
+        if self.user.IsWindow(hwnd):
+            self.user.GetWindowThreadProcessId(hwnd, self.c.byref(pid))
+            if pid.value == expected_pid:
+                self.user.ShowWindow(hwnd, 9)  # SW_RESTORE
+                self.user.SetForegroundWindow(hwnd)
+
+    def open(self, resource, clicked):
+        self.clicked = clicked
+        raw = (self.c.c_byte * len(resource)).from_buffer_copy(resource)
+        self.icon = self.user.CreateIconFromResourceEx(raw, len(resource), True, 0x30000, 32, 32, 0)
+        if not self.icon:
+            raise self.c.WinError(self.c.get_last_error())
+        self.instance = self.kernel.GetModuleHandleW(None)
+        self.name = f"NovaNotifications-{id(self)}"
+        self.callback = self.proc_type(self._message)
+        wc = self.WindowClass(proc=self.callback, instance=self.instance, name=self.name)
+        if not self.user.RegisterClassW(self.c.byref(wc)):
+            raise self.c.WinError(self.c.get_last_error())
+        self.hwnd = self.user.CreateWindowExW(
+            0, self.name, "NovaCode notifications", 0, 0, 0, 0, 0, None, None, self.instance, None
+        )
+        if not self.hwnd:
+            raise self.c.WinError(self.c.get_last_error())
+
+    def _message(self, hwnd, message, uid, event):
+        if message == self.CALLBACK:
+            if event == 0x405 and uid in self.items:  # NIN_BALLOONUSERCLICK
+                sid, nid = self.items[uid]
+                try:
+                    self.clicked(sid, nid)
+                except Exception:
+                    logger.warning("Notification click could not be routed", exc_info=True)
+            if event in (0x403, 0x404, 0x405):  # hide / timeout / click
+                self._remove(uid)
+            return 0
+        return self.user.DefWindowProcW(hwnd, message, uid, event)
+
+    def _data(self, uid):
+        return self.NotifyData(size=self.c.sizeof(self.NotifyData), hwnd=self.hwnd, id=uid)
+
+    def _remove(self, uid):
+        self.shell.Shell_NotifyIconW(2, self.c.byref(self._data(uid)))
+        self.items.pop(uid, None)
+
+    def wake(self):
+        self.user.PostMessageW(self.hwnd, self.WAKE, 0, 0)
+
+    def stop(self):
+        self.user.PostMessageW(self.hwnd, 0x12, 0, 0)  # WM_QUIT
+
+    def run(self, commands):
+        msg = self.w.MSG()
+        while (result := self.user.GetMessageW(self.c.byref(msg), None, 0, 0)) > 0:
+            if msg.message == self.WAKE:
+                while True:
+                    try:
+                        sid, nid, title, text = commands.get_nowait()
+                    except queue.Empty:
+                        break
+                    if len(self.items) >= 32:
+                        self._remove(next(iter(self.items)))
+                    uid = self.next_id
+                    self.next_id += 1
+                    data = self._data(uid)
+                    data.flags = 1 | 2 | 4 | 16  # MESSAGE | ICON | TIP | INFO
+                    data.callback, data.icon, data.balloon_icon = (
+                        self.CALLBACK,
+                        self.icon,
+                        self.icon,
+                    )
+                    data.tip = "NovaCode"
+                    data.title, data.info = title[:63], text[:255]
+                    data.info_flags = 4 | 16 | 32 | 128  # USER | NOSOUND | LARGE_ICON | QUIET_TIME
+                    self.items[uid] = sid, nid
+                    if not self.shell.Shell_NotifyIconW(0, self.c.byref(data)):
+                        self.items.pop(uid, None)
+            else:
+                self.user.TranslateMessage(self.c.byref(msg))
+                self.user.DispatchMessageW(self.c.byref(msg))
+        if result < 0:
+            raise self.c.WinError(self.c.get_last_error())
+
+    def close(self):
+        for uid in list(self.items):
+            self._remove(uid)
+        if self.hwnd:
+            self.user.DestroyWindow(self.hwnd)
+        if self.icon:
+            self.user.DestroyIcon(self.icon)
+        if getattr(self, "name", None):
+            self.user.UnregisterClassW(self.name, self.instance)