pixelweaver 0.1.0__py3-none-any.whl

pixelweaver/__init__.py

@@ -0,0 +1 @@
+"""PixelWeaver collaboration server."""

pixelweaver/__main__.py

@@ -0,0 +1,4 @@
+"""Enable python -m pixelweaver."""
+from pixelweaver.cli import main
+
+main()

pixelweaver/autosave.py

@@ -0,0 +1,114 @@
+"""Auto-save: periodic flush of in-memory state to disk.
+
+The auto-saver runs as an asyncio background task. State is saved when:
+    - A debounce timer expires after the last state mutation, OR
+    - A fixed interval elapses since the last save
+
+Whichever fires first triggers a save, preventing both data loss and
+excessive I/O.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+
+from pixelweaver.state import ServerState
+from pixelweaver.storage import save_project
+
+logger = logging.getLogger(__name__)
+
+
+class AutoSaver:
+    """Periodically flushes server state to disk."""
+
+    def __init__(
+        self,
+        state: ServerState,
+        save_dir: str,
+        debounce_ms: int = 500,
+        interval_s: int = 30,
+    ) -> None:
+        self.state = state
+        self.save_dir = save_dir
+        self.debounce_ms = debounce_ms
+        self.interval_s = interval_s
+        self._dirty = False
+        self._last_save: float = 0
+        self._task: asyncio.Task[None] | None = None
+        self._debounce_task: asyncio.Task[None] | None = None
+
+    def mark_dirty(self) -> None:
+        """Called after any state change to schedule a debounced save."""
+        self._dirty = True
+        # Reset the debounce timer
+        if self._debounce_task is not None and not self._debounce_task.done():
+            self._debounce_task.cancel()
+        self._debounce_task = asyncio.ensure_future(self._debounce_save())
+
+    async def _debounce_save(self) -> None:
+        """Wait for the debounce period, then save if still dirty."""
+        try:
+            await asyncio.sleep(self.debounce_ms / 1000.0)
+            if self._dirty:
+                await self.save_now()
+        except asyncio.CancelledError:
+            pass  # Debounce was reset by a newer mutation
+
+    async def start(self) -> None:
+        """Start the auto-save background task (periodic interval saves)."""
+        self._task = asyncio.ensure_future(self._periodic_loop())
+        logger.info(
+            "Auto-saver started (debounce=%dms, interval=%ds, dir=%s)",
+            self.debounce_ms,
+            self.interval_s,
+            self.save_dir,
+        )
+
+    async def stop(self) -> None:
+        """Stop the background task gracefully, saving any pending changes."""
+        if self._task is not None:
+            self._task.cancel()
+            try:
+                await self._task
+            except asyncio.CancelledError:
+                pass
+        if self._debounce_task is not None:
+            self._debounce_task.cancel()
+        # Final save if dirty
+        if self._dirty:
+            await self.save_now()
+
+    async def _periodic_loop(self) -> None:
+        """Run periodic saves on a fixed interval."""
+        try:
+            while True:
+                await asyncio.sleep(self.interval_s)
+                if self._dirty:
+                    await self.save_now()
+        except asyncio.CancelledError:
+            pass
+
+    async def save_now(self) -> None:
+        """Flush all project state to disk immediately."""
+        if not self.state.projects:
+            self._dirty = False
+            return
+
+        # Track per-loop failures so a single failed project doesn't lose
+        # the dirty marker for the rest. _dirty is a single flag here, so
+        # if anything failed we leave it set and the next debounce/interval
+        # tick will retry the whole batch.
+        any_failed = False
+        for project in self.state.projects.values():
+            try:
+                await asyncio.to_thread(save_project, project, self.save_dir)
+            except Exception:
+                any_failed = True
+                logger.error("Failed to save project %s", project.name, exc_info=True)
+
+        if not any_failed:
+            self._dirty = False
+        self._last_save = time.monotonic()
+        logger.debug("Auto-saved %d project(s) to %s", len(self.state.projects), self.save_dir)

pixelweaver/bridge.py

@@ -0,0 +1,127 @@
+"""Desktop file I/O bridge for pywebview.
+
+Provides native file dialogs and filesystem access callable from JavaScript
+via pywebview's js_api mechanism.  All binary data is transferred as
+base64-encoded strings since the JS bridge serializes return values as JSON.
+"""
+
+from __future__ import annotations
+
+import base64
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class DesktopBridge:
+    """File I/O bridge exposed to the frontend via pywebview js_api.
+
+    Methods on this class become callable from JavaScript as:
+        window.pywebview.api.method_name(args)
+    """
+
+    def save_file(
+        self,
+        data_b64: str,
+        default_name: str,
+        filter_name: str,
+        extensions: list[str],
+    ) -> str | None:
+        """Show a native Save dialog and write the file.
+
+        Returns the saved file path, or None if the user cancelled.
+        """
+        import webview
+
+        window = webview.windows[0]
+        file_types = (f"{filter_name} ({' '.join('*.' + e for e in extensions)})",)
+        result = window.create_file_dialog(
+            webview.SAVE_DIALOG,
+            save_filename=default_name,
+            file_types=file_types,
+        )
+        if not result:
+            return None
+        path = result if isinstance(result, str) else result[0]
+        try:
+            data = base64.b64decode(data_b64)
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+            Path(path).write_bytes(data)
+            return path
+        except Exception:
+            logger.exception("Failed to write file %s", path)
+            return None
+
+    def open_file(
+        self,
+        filter_name: str,
+        extensions: list[str],
+    ) -> dict | None:
+        """Show a native Open dialog and read the file.
+
+        Returns {"path": str, "data": base64_string} or None if cancelled.
+        """
+        import webview
+
+        window = webview.windows[0]
+        file_types = (f"{filter_name} ({' '.join('*.' + e for e in extensions)})",)
+        result = window.create_file_dialog(
+            webview.OPEN_DIALOG,
+            file_types=file_types,
+        )
+        if not result:
+            return None
+        path = result[0] if isinstance(result, (tuple, list)) else result
+        try:
+            data = Path(path).read_bytes()
+            return {
+                "path": str(path),
+                "data": base64.b64encode(data).decode("ascii"),
+            }
+        except Exception:
+            logger.exception("Failed to read file %s", path)
+            return None
+
+    def write_file(self, path: str, data_b64: str) -> bool:
+        """Write binary data to a specific path (no dialog)."""
+        try:
+            data = base64.b64decode(data_b64)
+            Path(path).parent.mkdir(parents=True, exist_ok=True)
+            Path(path).write_bytes(data)
+            return True
+        except Exception:
+            logger.exception("Failed to write file %s", path)
+            return False
+
+    def pick_directory(self) -> str | None:
+        """Show a native directory picker. Returns path or None if cancelled."""
+        import webview
+
+        window = webview.windows[0]
+        result = window.create_file_dialog(webview.FOLDER_DIALOG)
+        if not result:
+            return None
+        return result[0] if isinstance(result, (tuple, list)) else str(result)
+
+    def write_files_to_directory(
+        self,
+        dir_path: str,
+        files: list[dict],
+    ) -> bool:
+        """Write multiple files to a directory.
+
+        Each entry in files should be {"name": str, "data": base64_string}.
+        """
+        try:
+            base = Path(dir_path)
+            base.mkdir(parents=True, exist_ok=True)
+            for entry in files:
+                file_path = base / entry["name"]
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+                data = base64.b64decode(entry["data"])
+                file_path.write_bytes(data)
+            return True
+        except Exception:
+            logger.exception("Failed to write files to %s", dir_path)
+            return False

pixelweaver/cli.py

@@ -0,0 +1,199 @@
+"""PixelWeaver CLI."""
+
+from __future__ import annotations
+
+import platform
+import sys
+from pathlib import Path
+
+import strictcli
+from strictcli import App
+
+_DEFAULT_PID = Path(".pixelweaver.pid")
+
+
+def _get_version() -> str:
+    from importlib.metadata import version
+    return version("pixelweaver")
+
+
+def _pkg_version(package_name: str, module_name: str | None = None) -> str:
+    """Get package version, trying module attr first then importlib.metadata."""
+    if module_name:
+        try:
+            mod = __import__(module_name)
+            ver = getattr(mod, "__version__", None)
+            if ver:
+                return ver
+        except ImportError:
+            pass
+    try:
+        from importlib.metadata import version
+        return version(package_name)
+    except Exception:
+        return "NOT FOUND"
+
+
+app = App(
+    name="pixelweaver",
+    help="PixelWeaver collaboration server",
+    version=_get_version(),
+    config=True,
+)
+
+# Reusable tag for --data-dir flag (shared by multiple commands)
+_data_dir_tag = strictcli.Tag(name="data", flags=[
+    strictcli.Flag(
+        name="data-dir",
+        type=str,
+        help="Projects directory",
+        default="./projects",
+    ),
+])
+
+
+@app.command("serve", help="Start the server", tags=[_data_dir_tag])
+@strictcli.flag("host", type=str, help="Bind address", default="127.0.0.1")
+@strictcli.flag("port", type=int, help="Port", default=7779)
+@strictcli.flag("reload", type=bool, help="Auto-reload on file changes")
+def cmd_serve(*, host: str, port: int, data_dir: str, reload: bool, **_kw: object) -> None:
+    from pixelweaver.config import set_data_dir
+    from wesktop import serve
+    set_data_dir(data_dir)
+    serve("pixelweaver.main:app", foreground=True, host=host, port=port, pid_path=_DEFAULT_PID, reload=reload, name="PIXELWEAVER")
+
+
+@app.command(
+    "new",
+    help="Create a new project on disk",
+    args=[strictcli.Arg(name="name", help="Project name")],
+    tags=[_data_dir_tag],
+)
+@strictcli.flag("width", type=int, help="Canvas width in pixels")
+@strictcli.flag("height", type=int, help="Canvas height in pixels")
+def cmd_new(name: str, *, width: int, height: int, data_dir: str, **_kw: object) -> None:
+    from pixelweaver.state import ServerState
+    from pixelweaver.storage import save_project
+    state = ServerState()
+    project = state.create_project(name, width, height)
+    save_project(project, data_dir)
+    print(f"Created project '{name}' ({width}x{height}) in {data_dir}/")
+
+
+@app.command("list", help="List projects on disk", tags=[_data_dir_tag])
+def cmd_list(*, data_dir: str, **_kw: object) -> None:
+    from pixelweaver.storage import list_projects
+    projects = list_projects(data_dir)
+    if not projects:
+        print("No projects found.")
+    else:
+        for name in projects:
+            print(f"  {name}")
+
+
+@app.command("mcp", help="Start the MCP tool server (stdio)", tags=[_data_dir_tag])
+def cmd_mcp(*, data_dir: str, **_kw: object) -> None:
+    from pixelweaver.config import set_data_dir
+    from pixelweaver.mcp_server import run_mcp_server
+    set_data_dir(data_dir)
+    run_mcp_server()
+
+
+@app.command("dev", help="Development mode with Vite HMR", tags=[_data_dir_tag])
+@strictcli.flag("host", type=str, help="Bind address", default="127.0.0.1")
+@strictcli.flag("port", type=int, help="Port", default=7779)
+@strictcli.flag("vite-port", type=int, help="Vite dev server port", default=5173)
+def cmd_dev(*, host: str, port: int, data_dir: str, vite_port: int, **_kw: object) -> None:
+    from pixelweaver.config import set_data_dir
+    from wesktop import dev
+    set_data_dir(data_dir)
+    dev(
+        "pixelweaver.main:app",
+        vite_command="npm run dev",
+        vite_port=vite_port,
+        host=host,
+        port=port,
+        pid_path=_DEFAULT_PID,
+        name="PIXELWEAVER",
+    )
+
+
+@app.command("open", help="Launch desktop window", tags=[_data_dir_tag])
+@strictcli.flag("host", type=str, help="Bind address", default="127.0.0.1")
+@strictcli.flag("port", type=int, help="Port", default=7779)
+@strictcli.flag("browser", type=bool, help="Open in browser instead of native window")
+def cmd_open(*, host: str, port: int, data_dir: str, browser: bool, **_kw: object) -> None:
+    from pixelweaver.config import set_data_dir
+    set_data_dir(data_dir)
+
+    if browser:
+        import threading
+        import webbrowser
+        from wesktop import serve
+        url = serve(
+            "pixelweaver.main:app",
+            foreground=False,
+            host=host,
+            port=port,
+            pid_path=_DEFAULT_PID,
+            name="PIXELWEAVER",
+        )
+        webbrowser.open(url)
+        try:
+            threading.Event().wait()
+        except KeyboardInterrupt:
+            pass
+    else:
+        from pixelweaver.bridge import DesktopBridge
+        from wesktop import run
+        run(
+            "pixelweaver.main:app",
+            title="PixelWeaver",
+            width=1280,
+            height=800,
+            host=host,
+            port=port,
+            pid_path=_DEFAULT_PID,
+            icon=str(Path("assets/icon.png").resolve()),
+            js_api=DesktopBridge(),
+            name="PIXELWEAVER",
+        )
+
+
+@app.command("diagnose", help="Check runtime environment and dependencies")
+def cmd_diagnose(**_kw: object) -> None:
+    rows: list[tuple[str, str]] = []
+    rows.append(("Python", f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"))
+    rows.append(("pixelweaver", _get_version()))
+
+    for label, pkg, mod in [
+        ("wesktop", "wesktop", "wesktop"),
+        ("pywebview", "pywebview", "webview"),
+        ("pydantic", "pydantic", "pydantic"),
+        ("pillow", "pillow", "PIL"),
+        ("mcp", "mcp", "mcp"),
+    ]:
+        ver = _pkg_version(pkg, mod)
+        suffix = " (ok)" if ver != "NOT FOUND" else ""
+        rows.append((label, f"{ver}{suffix}"))
+
+    rows.append(("platform", f"{platform.system()} {platform.machine()}"))
+    rows.append(("config", app.config_file_path))
+
+    label_width = max(len(label) for label, _ in rows)
+    for label, value in rows:
+        print(f"  {label:<{label_width}}  {value}")
+
+
+@app.command("stop", help="Stop the running server")
+def cmd_stop(**_kw: object) -> None:
+    from wesktop import stop
+    if not _DEFAULT_PID.exists():
+        print(f"No PID file found at {_DEFAULT_PID}")
+        return
+    stop(_DEFAULT_PID)
+    print("Server stopped.")
+
+
+def main() -> None:
+    app.run()

pixelweaver/config.py

@@ -0,0 +1,24 @@
+"""Process-wide configuration for PixelWeaver server.
+
+Single source of truth for settings that are set once at startup (e.g. from
+CLI arguments) and then read throughout the application. Both the HTTP
+server (main.py) and the MCP server (mcp_server.py) share this module so
+they never drift out of sync.
+"""
+
+from __future__ import annotations
+
+# Default matches the CLI's DEFAULT_DATA_DIR; overridden via set_data_dir()
+# before the server app starts.
+_data_dir: str = "./projects"
+
+
+def get_data_dir() -> str:
+    """Return the currently configured projects data directory."""
+    return _data_dir
+
+
+def set_data_dir(data_dir: str) -> None:
+    """Set the projects data directory (called from CLI before app starts)."""
+    global _data_dir
+    _data_dir = data_dir

pixelweaver/connections.py

@@ -0,0 +1,54 @@
+"""WebSocket connection manager for PixelWeaver.
+
+Tracks active connections and provides helpers for sending messages
+to individual clients or broadcasting to all/most clients.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from wesktop import WebSocket
+
+logger = logging.getLogger(__name__)
+
+
+class ConnectionManager:
+    """Manages active WebSocket connections."""
+
+    def __init__(self) -> None:
+        self.active_connections: list[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket) -> None:
+        """Accept and register a new WebSocket connection."""
+        await websocket.accept()
+        self.active_connections.append(websocket)
+        logger.info("Client connected (%d total)", len(self.active_connections))
+
+    def disconnect(self, websocket: WebSocket) -> None:
+        """Unregister a WebSocket connection."""
+        try:
+            self.active_connections.remove(websocket)
+        except ValueError:
+            pass  # Already removed
+        logger.info("Client disconnected (%d remaining)", len(self.active_connections))
+
+    async def broadcast(
+        self,
+        message: dict[str, Any],
+        exclude: WebSocket | None = None,
+    ) -> None:
+        """Send a JSON message to all connected clients, optionally excluding one."""
+        # Snapshot the list so disconnects triggered by send failures (via
+        # exception handlers mutating active_connections) don't corrupt iteration.
+        for connection in list(self.active_connections):
+            if connection is not exclude:
+                try:
+                    await connection.send_json(message)
+                except Exception:
+                    logger.warning("Failed to send broadcast to a client", exc_info=True)
+
+    async def send(self, websocket: WebSocket, message: dict[str, Any]) -> None:
+        """Send a JSON message to a single client."""
+        await websocket.send_json(message)