painapple-code 1.0.0__py3-none-any.whl

painapple_code/utils/excalidraw.py

@@ -0,0 +1,107 @@
+"""
+Excalidraw rendering utilities — converts .excalidraw / .excalidraw.md to SVG.
+
+Supports:
+  - Raw .excalidraw JSON (from excalidraw.com)
+  - Obsidian .excalidraw.md (LZ-string compressed-json format)
+
+Uses @excalidraw/utils via Node.js subprocess (tools/excalidraw-to-svg.js).
+Includes in-memory cache keyed by file content hash.
+"""
+
+import asyncio
+import hashlib
+import logging
+from pathlib import Path
+
+from painapple_code import PACKAGE_DIR
+
+logger = logging.getLogger(__name__)
+
+# Path to the Node renderer script (shipped in package)
+_SCRIPT = PACKAGE_DIR / "tools" / "excalidraw-to-svg.js"
+
+# Simple in-memory cache: content_hash -> svg_string
+_cache: dict[str, str] = {}
+_MAX_CACHE = 50  # max cached renderings
+
+
+async def render_excalidraw(source: str | bytes, dark_mode: bool = False) -> str:
+    """Render excalidraw JSON to SVG string.
+
+    Args:
+        source: Excalidraw JSON string or bytes
+        dark_mode: If True, render with dark mode filter
+    Returns:
+        SVG string
+    Raises:
+        RuntimeError: If rendering fails
+    """
+    if isinstance(source, str):
+        source = source.encode('utf-8')
+
+    # Check cache
+    content_hash = hashlib.md5(source + (b'dark' if dark_mode else b'')).hexdigest()
+    if content_hash in _cache:
+        return _cache[content_hash]
+
+    if not _SCRIPT.exists():
+        raise RuntimeError(f"Excalidraw renderer not found: {_SCRIPT}")
+
+    cmd = ["node", str(_SCRIPT)]
+    if dark_mode:
+        cmd.append("--dark")
+
+    proc = await asyncio.create_subprocess_exec(
+        *cmd,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            proc.communicate(input=source), timeout=15.0
+        )
+    except asyncio.TimeoutError:
+        proc.kill()
+        raise RuntimeError("Excalidraw render timed out (15s)")
+
+    if proc.returncode != 0:
+        error_msg = stderr.decode('utf-8', errors='replace').strip()
+        raise RuntimeError(f"Excalidraw render failed: {error_msg}")
+
+    svg = stdout.decode('utf-8')
+
+    # Cache result (evict oldest if full)
+    if len(_cache) >= _MAX_CACHE:
+        oldest = next(iter(_cache))
+        del _cache[oldest]
+    _cache[content_hash] = svg
+
+    # Log non-fatal warnings from stderr
+    if stderr:
+        for line in stderr.decode('utf-8', errors='replace').strip().split('\n'):
+            if line:
+                logger.debug("excalidraw-to-svg: %s", line)
+
+    return svg
+
+
+def is_excalidraw_file(path: str | Path) -> bool:
+    """Check if a file is an excalidraw file (.excalidraw or .excalidraw.md)."""
+    name = str(path).lower()
+    return name.endswith('.excalidraw') or name.endswith('.excalidraw.md')
+
+
+async def render_excalidraw_file(path: Path, dark_mode: bool = False) -> str:
+    """Render an .excalidraw or .excalidraw.md file to SVG string.
+
+    Args:
+        path: Path to .excalidraw or .excalidraw.md file
+        dark_mode: If True, render with dark mode filter
+    Returns:
+        SVG string
+    """
+    content = path.read_bytes()
+    return await render_excalidraw(content, dark_mode=dark_mode)

painapple_code/utils/file_lock.py

@@ -0,0 +1,162 @@
+"""Cross-platform advisory file locking.
+
+`fcntl` doesn't exist on Windows, and a bare module-level ``import fcntl``
+is an import-time crash for everything that transitively imports the
+module (this killed `shadow_git` → `agent_session` → `server` on win32;
+see docs-ai/plans/2026-08-08-windows-native-port.md §1.1).
+
+One context manager, exclusive + blocking, replacing the direct
+``fcntl.flock(LOCK_EX)`` pattern:
+
+    with FileLock(path.with_suffix(".lock")):
+        ...critical section...
+
+POSIX backs it with ``fcntl.flock``; Windows with ``msvcrt.locking`` on
+the first byte (region locks may extend past EOF, so an empty lock file
+is fine). The win32 branch polls ``LK_NBLCK`` with backoff rather than
+calling ``LK_LOCK``: LK_LOCK blocks ~10s inside the CRT (one attempt per
+second) before raising, so a caller-requested 2s timeout actually waited
+9-10s and the 5s slow-lock warning could never fire on time (measured on
+Windows 11 2026-08-09 — 9.2s to a ``timeout=2`` TimeoutError). The
+non-blocking probe returns immediately, putting the deadline and warn
+schedule under our own loop's control.
+
+Why that matters: ``FileLock`` is entered synchronously from
+``ShadowGit.track_modification``, which ``AgentManager`` calls on the
+asyncio event loop for the first Edit/Write of a turn. A retry loop that
+swallows every ``OSError`` spins the whole server at 100% CPU forever the
+moment the lock file is unopenable/unlockable for a non-contention
+reason (EACCES/EINVAL/EBADF all return immediately, with no internal
+sleep to throttle the loop). Anything not-contention is re-raised;
+contention waits with bounded backoff and finally gives up with a
+``TimeoutError`` (an ``OSError`` subclass, so existing handlers cover it)
+rather than pinning a core until the process is killed.
+"""
+
+import logging
+import sys
+import time
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["FileLock"]
+
+# Contention on this lock means "another process is mid JSON read+write" —
+# milliseconds. A minute of it means something is genuinely wedged, and
+# hanging the event loop forever is worse than failing loudly.
+LOCK_TIMEOUT = 60.0
+LOCK_WARN_AFTER = 5.0
+_BACKOFF_START = 0.02
+_BACKOFF_MAX = 0.5
+
+
+if sys.platform == "win32":
+    import errno
+    import msvcrt
+
+    # MS CRT `_locking` failure codes (docs: "_locking"): EACCES is the
+    # locking violation LK_NBLCK reports on contention — the retry case.
+    # EDEADLOCK (LK_LOCK's give-up code) is kept for safety should the
+    # mode ever change; EBADF/EINVAL are programming errors and must
+    # propagate.
+    _RETRYABLE = {
+        getattr(errno, "EDEADLOCK", None),
+        getattr(errno, "EDEADLK", None),
+        errno.EACCES,
+    } - {None}
+
+    class FileLock:
+        """Exclusive, blocking advisory lock on a dedicated lock file."""
+
+        def __init__(self, path, timeout: float = LOCK_TIMEOUT):
+            self._path = path
+            self._timeout = timeout
+            self._fh = None
+
+        def __enter__(self):
+            # "a" creates without truncating — truncation would race other
+            # holders of the same lock file. Nothing is ever read or written
+            # through this handle (it exists only to carry the lock), but the
+            # encoding is stated anyway so the file never depends on the
+            # machine's locale codec.
+            fh = open(self._path, "a", encoding="utf-8")
+            try:
+                self._acquire(fh)
+            except BaseException:
+                # __exit__ never runs when __enter__ raises, so the handle
+                # would leak for the life of the process.
+                fh.close()
+                raise
+            self._fh = fh
+            return self
+
+        def _acquire(self, fh):
+            started = time.monotonic()
+            deadline = started + self._timeout
+            backoff = _BACKOFF_START
+            warned = False
+            while True:
+                try:
+                    fh.seek(0)
+                    msvcrt.locking(fh.fileno(), msvcrt.LK_NBLCK, 1)
+                    return
+                except OSError as e:
+                    if e.errno not in _RETRYABLE:
+                        raise
+                    waited = time.monotonic() - started
+                    if waited >= self._timeout:
+                        raise TimeoutError(
+                            f"could not lock {self._path} after "
+                            f"{waited:.0f}s (held by another process)"
+                        ) from e
+                    if not warned and waited >= LOCK_WARN_AFTER:
+                        warned = True
+                        logger.warning(
+                            f"still waiting on {self._path} after "
+                            f"{waited:.0f}s — another process is holding it"
+                        )
+                # Bounded backoff — LK_NBLCK returns immediately, so this
+                # sleep is the only thing between attempts and the only
+                # thing keeping the loop off the CPU.
+                time.sleep(min(backoff, max(0.0, deadline - time.monotonic())))
+                backoff = min(backoff * 2, _BACKOFF_MAX)
+
+        def __exit__(self, exc_type, exc, tb):
+            try:
+                self._fh.seek(0)
+                msvcrt.locking(self._fh.fileno(), msvcrt.LK_UNLCK, 1)
+            finally:
+                self._fh.close()
+                self._fh = None
+            return False
+
+else:
+    import fcntl
+
+    class FileLock:
+        """Exclusive, blocking advisory lock on a dedicated lock file."""
+
+        def __init__(self, path, timeout: float = LOCK_TIMEOUT):
+            self._path = path
+            self._timeout = timeout   # accepted for API parity; flock blocks
+            self._fh = None
+
+        def __enter__(self):
+            # Lock-carrying handle only; see the win32 branch above.
+            fh = open(self._path, "a", encoding="utf-8")
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+            except BaseException:
+                # Same leak as the win32 branch: __exit__ won't run.
+                fh.close()
+                raise
+            self._fh = fh
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            try:
+                fcntl.flock(self._fh.fileno(), fcntl.LOCK_UN)
+            finally:
+                self._fh.close()
+                self._fh = None
+            return False