pixelweaver 0.1.0

package/server/src/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()

package/server/src/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

package/server/src/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)

package/server/src/pixelweaver/main.py

@@ -0,0 +1,271 @@
+"""wesktop application for PixelWeaver collaboration server.
+
+Provides REST endpoints for project management and a WebSocket endpoint
+for the real-time server-authoritative protocol.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from wesktop import (
+    AppConfig,
+    BytesResponse,
+    JSONResponse,
+    Request,
+    Router,
+    TextResponse,
+    WebSocket,
+    create_app,
+)
+from wesktop.asgi import HTTPError
+from pydantic import BaseModel, Field, field_validator
+
+from pixelweaver.autosave import AutoSaver
+from pixelweaver.config import get_data_dir
+from pixelweaver.connections import ConnectionManager
+from pixelweaver.mcp_bridge import deserialize_into_state, serialize_state
+from pixelweaver.state import ServerState
+from pixelweaver.storage import export_frame_png, list_projects, load_project, save_project
+from pixelweaver.websocket import broadcast_full_state, handle_message
+
+logger = logging.getLogger(__name__)
+
+# Module-level singletons -- initialized before the app starts
+state = ServerState()
+manager = ConnectionManager()
+
+_auto_saver: AutoSaver | None = None
+
+router = Router()
+
+
+@asynccontextmanager
+async def lifespan(scope):
+    """Startup/shutdown lifecycle: load projects from disk, start auto-saver."""
+    global _auto_saver
+
+    data_dir = get_data_dir()
+
+    # Load existing projects from disk
+    for name in list_projects(data_dir):
+        try:
+            project_dir = f"{data_dir}/{name}"
+            project = load_project(project_dir)
+            state.projects[project.name] = project
+            if state.active_project is None:
+                state.active_project = project.name
+            logger.info("Loaded project: %s", name)
+        except Exception:
+            logger.error("Failed to load project: %s", name, exc_info=True)
+
+    # Start auto-saver
+    _auto_saver = AutoSaver(state, data_dir)
+    await _auto_saver.start()
+
+    yield {}
+
+    # Shutdown: flush pending saves
+    if _auto_saver is not None:
+        await _auto_saver.stop()
+
+
+# ---------------------------------------------------------------------------
+# Health
+# ---------------------------------------------------------------------------
+
+
+@router.get("/health")
+async def health_check(req: Request):
+    """Health check endpoint."""
+    return {"status": "ok"}
+
+
+# ---------------------------------------------------------------------------
+# Project management REST API
+# ---------------------------------------------------------------------------
+
+
+class CreateProjectRequest(BaseModel):
+    name: str
+    width: int = Field(ge=1, le=4096)
+    height: int = Field(ge=1, le=4096)
+
+    @field_validator("name")
+    @classmethod
+    def name_must_be_safe(cls, v: str) -> str:
+        """Reject names that could escape the project data directory."""
+        import re
+
+        if not re.match(r"^[a-zA-Z0-9][a-zA-Z0-9 _.\-]{0,63}$", v):
+            raise ValueError(
+                "Project name must be 1-64 characters, start with an alphanumeric, "
+                "and contain only alphanumerics, spaces, underscores, hyphens, or dots."
+            )
+        return v
+
+
+@router.get("/api/projects")
+async def list_all_projects(req: Request):
+    """List all projects."""
+    return {"projects": state.list_projects()}
+
+
+@router.post("/api/projects")
+async def create_project(req: Request):
+    """Create a new project."""
+    data = req.json_as(CreateProjectRequest)
+
+    if data.name in state.projects:
+        return JSONResponse({"detail": f"Project {data.name!r} already exists"}, status=409)
+
+    project = state.create_project(data.name, data.width, data.height)
+
+    # Persist immediately
+    await asyncio.to_thread(save_project, project, get_data_dir())
+
+    return JSONResponse(
+        {"name": project.name, "width": project.width, "height": project.height},
+        status=201,
+    )
+
+
+@router.get("/api/projects/{name}")
+async def get_project(req: Request):
+    """Get project metadata."""
+    name = req.path_params["name"]
+    project = state.get_project(name)
+    if project is None:
+        raise HTTPError(404, f"Project {name!r} not found")
+    return project.to_dict()
+
+
+@router.delete("/api/projects/{name}")
+async def delete_project(req: Request):
+    """Delete a project from memory (does not delete files on disk)."""
+    name = req.path_params["name"]
+    if not state.delete_project(name):
+        raise HTTPError(404, f"Project {name!r} not found")
+    return TextResponse("", status=204)
+
+
+# ---------------------------------------------------------------------------
+# Export
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/projects/{name}/export/png/{canvas}/{frame:int}")
+async def export_png(req: Request):
+    """Export a frame as a composited PNG."""
+    name = req.path_params["name"]
+    canvas = req.path_params["canvas"]
+    frame = req.path_params["frame"]
+    project = state.get_project(name)
+    if project is None:
+        raise HTTPError(404, f"Project {name!r} not found")
+
+    try:
+        png_bytes = await asyncio.to_thread(export_frame_png, project, canvas, frame)
+    except ValueError as exc:
+        raise HTTPError(404, str(exc))
+
+    return BytesResponse(png_bytes, content_type="image/png")
+
+
+# ---------------------------------------------------------------------------
+# MCP state sync  (used by the MCP bridge to round-trip state)
+# ---------------------------------------------------------------------------
+
+
+@router.get("/api/state/full")
+async def get_full_state(req: Request):
+    """Return the full serialized server state for MCP sync.
+
+    The MCP server calls this before executing a tool so it operates on
+    the latest state held by the collab server.
+    """
+    return serialize_state(state)
+
+
+@router.post("/api/state/sync")
+async def sync_state_from_mcp(req: Request):
+    """Accept full state from the MCP server and broadcast changes.
+
+    After the MCP server executes a tool, it pushes the modified state
+    here.  The collab server overwrites its in-memory state and broadcasts
+    a full-state patch to every connected WebSocket client so the frontend
+    sees the mutation.
+    """
+    payload: dict[str, Any] = req.json
+
+    async with state.mutation_lock:
+        deserialize_into_state(state, payload)
+
+    # Broadcast full-state to all WebSocket clients for every project
+    # that has changed.  In practice MCP works on the active project,
+    # so broadcasting that one is sufficient.
+    active = state.active_project
+    if active and active in state.projects:
+        await broadcast_full_state(state, manager, project_name=active)
+
+    # Mark dirty so the auto-saver persists the change
+    if _auto_saver is not None:
+        _auto_saver.mark_dirty()
+
+    return {"success": True}
+
+
+# ---------------------------------------------------------------------------
+# WebSocket
+# ---------------------------------------------------------------------------
+
+
+def _on_dirty() -> None:
+    """Callback passed to message handler to mark state as dirty."""
+    if _auto_saver is not None:
+        _auto_saver.mark_dirty()
+
+
+@router.ws("/ws")
+async def websocket_endpoint(ws: WebSocket):
+    """WebSocket endpoint for the server-authoritative protocol."""
+    await manager.connect(ws)
+    try:
+        while True:
+            msg = await ws.receive_raw()
+            if msg.get("type") == "websocket.disconnect":
+                break
+            raw: dict[str, Any] = json.loads(msg.get("text", ""))
+            await handle_message(ws, raw, state, manager, on_dirty=_on_dirty)
+    except Exception:
+        logger.error("WebSocket error", exc_info=True)
+        try:
+            await ws.close(code=1011)
+        except Exception:
+            pass
+    finally:
+        manager.disconnect(ws)
+
+
+# ---------------------------------------------------------------------------
+# App creation
+# ---------------------------------------------------------------------------
+
+_dist = Path("dist")
+_spa = _dist / "index.html"
+
+app = create_app(
+    router,
+    AppConfig(
+        lifespan=lifespan,
+        cors_origins=["*"],
+        static_dir=_dist if _spa.is_file() else None,
+        spa_fallback=_spa if _spa.is_file() else None,
+        api_prefix="/api",
+    ),
+)