@palettelab/cli 0.3.23 → 0.3.25

package/README.md

@@ -193,6 +193,133 @@ Use the right command for the kind of test you need:
 For normal app developers, Docker is not required. Docker is only needed for
 internal platform parity checks with `pltt dev --platform`.
 
+## App-Owned Data, Migrations, And Python Backends
+
+Palette apps can own their own Python backend, database tables, migrations, and
+organization-scoped data. The generated database template uses this structure:
+
+```text
+my-app/
+  palette-plugin.json
+  frontend/src/index.tsx
+  backend/api/main.py
+  backend/api/models.py
+  backend/migrations/env.py
+  backend/migrations/versions/001_init.py
+```
+
+Declare database ownership in `palette-plugin.json`:
+
+```json
+{
+  "capabilities": { "database": true },
+  "database": {
+    "schema": "app_my_app",
+    "migrations": "./backend/migrations"
+  }
+}
+```
+
+Define org-scoped models with the backend SDK:
+
+```python
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+from palette_sdk import OrgScopedTable
+
+class Invoice(OrgScopedTable):
+    __tablename__ = "invoices"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    customer_name: Mapped[str] = mapped_column(String(255))
+```
+
+Use the migration helper in Alembic migrations:
+
+```python
+from palette_sdk.db import ensure_org_rls
+
+def upgrade():
+    op.create_table(...)
+    ensure_org_rls(op, "invoices")
+```
+
+Use `ctx.repo(Model)` for org-safe CRUD:
+
+```python
+from fastapi import Depends
+from palette_sdk import PluginContext, get_plugin_context
+from models import Invoice
+
+@router.get("/invoices")
+async def list_invoices(ctx: PluginContext = Depends(get_plugin_context)):
+    rows = await ctx.repo(Invoice).list(order_by="-id")
+    return [{"id": r.id, "customer": r.customer_name} for r in rows]
+
+@router.post("/invoices")
+async def create_invoice(body: InvoiceIn, ctx: PluginContext = Depends(get_plugin_context)):
+    invoice = await ctx.repo(Invoice).create(**body.model_dump())
+    return {"id": invoice.id}
+```
+
+Backend SDK features for app-owned data:
+
+- `PluginContext` exposes `user_id`, `organization_id`, `plugin_id`, `permissions`, `config`, `storage`, and `ctx.db`.
+- `ctx.repo(Model)` gives org-safe CRUD helpers for app tables.
+- `ctx.data_rooms` gives backend access to Palette Data Rooms without importing platform internals.
+- `ctx.has_permission("...")` checks declared permissions.
+- `ctx.config_value("key")` and `ctx.require_config("key")` read app install/config values.
+- `ctx.secret("KEY")` reads app secrets from config or environment variables.
+- `LifecycleHooks` lets apps define install/update/enable/disable/uninstall hooks.
+- `OrgScopedTable` and `PluginBase` keep app data inside the plugin schema model set.
+
+Python backend Data Room example:
+
+```python
+@router.post("/sync-invoices", dependencies=[require_permission("data_rooms:write")])
+async def sync_invoices(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.ensure_room("Finance")
+    folder = await ctx.data_rooms.resolve_folder_path(
+        room["id"],
+        "Clients/Acme/Invoices",
+        create=True,
+    )
+    file = await ctx.data_rooms.find_file_by_name(
+        room["id"],
+        "jan.pdf",
+        folder_id=folder["id"] if folder else None,
+    )
+    content = await ctx.data_rooms.read_file_bytes(file["id"]) if file else None
+    return {"room": room, "folder": folder, "bytes": len(content or b"")}
+```
+
+The npm `@palettelab/sdk` package is for frontend JavaScript/React apps.
+Python backend code uses `palette_sdk`, which is embedded in the CLI for
+local dev/tests and injected by the hosted Palette runtime.
+
+Lifecycle example:
+
+```python
+from palette_sdk import LifecycleHooks, PluginContext
+
+lifecycle = LifecycleHooks()
+
+@lifecycle.on_install
+async def seed_defaults(ctx: PluginContext):
+    await ctx.repo(DefaultSetting).create(name="currency", value="USD")
+```
+
+Run local checks before publishing:
+
+```bash
+npx --yes @palettelab/cli@latest test
+npx --yes @palettelab/cli@latest package
+```
+
+The CLI validates manifest shape, SDK compatibility, frontend bundling, backend
+imports, backend route permission gates, declared permissions, migration safety,
+package dependency policy, and backend package size.
+
 ## Commands
 
 ### `pltt init <name>`

package/backend-sdk/palette_sdk/__init__.py

@@ -2,6 +2,9 @@
 
 from palette_sdk.plugin_router import PluginRouter
 from palette_sdk.plugin_context import PluginContext, get_plugin_context
+from palette_sdk.data_rooms import DataRoomsClient
+from palette_sdk.repository import OrgRepository
+from palette_sdk.lifecycle import LifecycleHooks
 from palette_sdk.tool_definition import ToolDefinition
 from palette_sdk.manifest import PluginManifest, load_manifest
 from palette_sdk.schemas import (
@@ -24,6 +27,9 @@ __all__ = [
     "PluginRouter",
     "PluginContext",
     "get_plugin_context",
+    "DataRoomsClient",
+    "OrgRepository",
+    "LifecycleHooks",
     "ToolDefinition",
     "PluginManifest",
     "load_manifest",
@@ -45,4 +51,4 @@ __all__ = [
     "route_permission_issues",
 ]
 
-__version__ = "0.1.3"
+__version__ = "0.1.5"

package/backend-sdk/palette_sdk/data_rooms.py

@@ -0,0 +1,110 @@
+"""Backend Data Room helpers for plugin Python code."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class DataRoomsClient:
+    """Thin wrapper around the platform-injected Data Room service.
+
+    In production/hosted sandbox the platform injects the service into
+    `PluginContext`. In local unit tests, pass a fake service with the same
+    async methods.
+    """
+
+    def __init__(self, service: Any = None):
+        self._service = service
+
+    def _require_service(self) -> Any:
+        if self._service is None:
+            raise RuntimeError(
+                "Data Room service is not available in this runtime. "
+                "Run inside Palette OS/hosted sandbox or inject a fake service in tests."
+            )
+        return self._service
+
+    async def list(self) -> list[dict[str, Any]]:
+        return await self._require_service().list_rooms()
+
+    async def create(self, name: str, description: str | None = None) -> dict[str, Any]:
+        return await self._require_service().create_room(name, description)
+
+    async def find_room_by_name(self, name: str, *, case_sensitive: bool = False) -> dict[str, Any] | None:
+        return await self._require_service().find_room_by_name(name, case_sensitive=case_sensitive)
+
+    async def require_room_by_name(self, name: str, *, case_sensitive: bool = False) -> dict[str, Any]:
+        room = await self.find_room_by_name(name, case_sensitive=case_sensitive)
+        if room is None:
+            raise LookupError(f"Data Room not found: {name}")
+        return room
+
+    async def ensure_room(self, name: str, description: str | None = None) -> dict[str, Any]:
+        return await self._require_service().ensure_room(name, description)
+
+    async def contents(self, room_id: int, folder_id: int | None = None) -> dict[str, Any]:
+        return await self._require_service().contents(room_id, folder_id)
+
+    async def create_folder(
+        self,
+        room_id: int,
+        name: str,
+        parent_folder_id: int | None = None,
+    ) -> dict[str, Any]:
+        return await self._require_service().create_folder(room_id, name, parent_folder_id)
+
+    async def find_folder_by_name(
+        self,
+        room_id: int,
+        name: str,
+        *,
+        parent_folder_id: int | None = None,
+        case_sensitive: bool = False,
+    ) -> dict[str, Any] | None:
+        return await self._require_service().find_folder_by_name(
+            room_id,
+            name,
+            parent_folder_id=parent_folder_id,
+            case_sensitive=case_sensitive,
+        )
+
+    async def ensure_folder(
+        self,
+        room_id: int,
+        name: str,
+        parent_folder_id: int | None = None,
+    ) -> dict[str, Any]:
+        return await self._require_service().ensure_folder(room_id, name, parent_folder_id)
+
+    async def resolve_folder_path(
+        self,
+        room_id: int,
+        path: str | list[str],
+        *,
+        create: bool = False,
+        case_sensitive: bool = False,
+    ) -> dict[str, Any] | None:
+        return await self._require_service().resolve_folder_path(
+            room_id,
+            path,
+            create=create,
+            case_sensitive=case_sensitive,
+        )
+
+    async def find_file_by_name(
+        self,
+        room_id: int,
+        name: str,
+        *,
+        folder_id: int | None = None,
+        case_sensitive: bool = False,
+    ) -> dict[str, Any] | None:
+        return await self._require_service().find_file_by_name(
+            room_id,
+            name,
+            folder_id=folder_id,
+            case_sensitive=case_sensitive,
+        )
+
+    async def read_file_bytes(self, file_id: int) -> bytes:
+        return await self._require_service().read_file_bytes(file_id)

package/backend-sdk/palette_sdk/lifecycle.py

@@ -0,0 +1,58 @@
+"""Lifecycle hook registry for install/update/uninstall behavior."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Literal
+
+from palette_sdk.plugin_context import PluginContext
+
+LifecycleEvent = Literal["install", "update", "enable", "disable", "uninstall"]
+LifecycleHandler = Callable[[PluginContext], Awaitable[None]]
+
+
+@dataclass
+class LifecycleHooks:
+    """Register optional app lifecycle hooks.
+
+    App backends can export a `lifecycle` object from `backend/api/main.py`.
+    The platform can call these hooks during install/update/uninstall, and tests
+    can call `run()` directly.
+    """
+
+    _handlers: dict[LifecycleEvent, list[LifecycleHandler]] = field(
+        default_factory=lambda: {
+            "install": [],
+            "update": [],
+            "enable": [],
+            "disable": [],
+            "uninstall": [],
+        }
+    )
+
+    def on(self, event: LifecycleEvent):
+        def decorator(fn: LifecycleHandler) -> LifecycleHandler:
+            self._handlers[event].append(fn)
+            return fn
+
+        return decorator
+
+    def on_install(self, fn: LifecycleHandler) -> LifecycleHandler:
+        return self.on("install")(fn)
+
+    def on_update(self, fn: LifecycleHandler) -> LifecycleHandler:
+        return self.on("update")(fn)
+
+    def on_enable(self, fn: LifecycleHandler) -> LifecycleHandler:
+        return self.on("enable")(fn)
+
+    def on_disable(self, fn: LifecycleHandler) -> LifecycleHandler:
+        return self.on("disable")(fn)
+
+    def on_uninstall(self, fn: LifecycleHandler) -> LifecycleHandler:
+        return self.on("uninstall")(fn)
+
+    async def run(self, event: LifecycleEvent, ctx: PluginContext) -> None:
+        for handler in self._handlers[event]:
+            await handler(ctx)

package/backend-sdk/palette_sdk/plugin_context.py

@@ -3,11 +3,15 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+import logging
+import os
 from typing import Any
 
 from fastapi import Depends, Request
 from sqlalchemy.ext.asyncio import AsyncSession
 
+from palette_sdk.data_rooms import DataRoomsClient
+
 
 @dataclass
 class PluginContext:
@@ -34,7 +38,31 @@ class PluginContext:
     plugin_id: str = ""
     permissions: list[str] = field(default_factory=list)
     storage: Any = None  # Platform storage service injected at runtime
+    data_rooms: DataRoomsClient = field(default_factory=DataRoomsClient)
     config: dict[str, Any] = field(default_factory=dict)
+    logger: logging.Logger = field(default_factory=lambda: logging.getLogger("palette_sdk.plugin"))
+
+    def has_permission(self, permission: str) -> bool:
+        return permission in self.permissions
+
+    def config_value(self, key: str, default: Any = None) -> Any:
+        return self.config.get(key, default)
+
+    def require_config(self, key: str) -> Any:
+        if key not in self.config or self.config[key] in (None, ""):
+            raise KeyError(f"missing plugin config value: {key}")
+        return self.config[key]
+
+    def secret(self, key: str, default: str | None = None) -> str | None:
+        secrets = self.config.get("secrets")
+        if isinstance(secrets, dict) and key in secrets:
+            return secrets[key]
+        return os.environ.get(key, default)
+
+    def repo(self, model: type[Any]):
+        from palette_sdk.repository import OrgRepository
+
+        return OrgRepository(self.db, model, self.organization_id)
 
 
 async def get_plugin_context(request: Request) -> PluginContext:
@@ -59,5 +87,7 @@ async def get_plugin_context(request: Request) -> PluginContext:
         plugin_id=getattr(state, "plugin_id", ""),
         permissions=getattr(state, "plugin_permissions", []),
         storage=getattr(state, "storage", None),
+        data_rooms=DataRoomsClient(getattr(state, "data_rooms", None)),
         config=getattr(state, "plugin_config", {}),
+        logger=getattr(state, "plugin_logger", logging.getLogger(f"palette_sdk.plugin.{getattr(state, 'plugin_id', 'unknown')}")),
     )

package/backend-sdk/palette_sdk/repository.py

@@ -0,0 +1,119 @@
+"""Org-safe repository helpers for plugin-owned data."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Generic, TypeVar
+
+from sqlalchemy import asc, desc, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+T = TypeVar("T")
+
+
+class OrgRepository(Generic[T]):
+    """Small CRUD helper for plugin models.
+
+    The platform still enforces plugin schema isolation and database RLS in
+    production. This helper adds the same organization guard in app code, which
+    keeps local SQLite/dev tests honest and reduces repeated query boilerplate.
+    """
+
+    def __init__(self, db: AsyncSession, model: type[T], organization_id: int):
+        self.db = db
+        self.model = model
+        self.organization_id = organization_id
+
+    def _org_filter(self):
+        if hasattr(self.model, "organization_id"):
+            return self.model.organization_id == self.organization_id
+        return None
+
+    def _base_select(self):
+        stmt = select(self.model)
+        org_filter = self._org_filter()
+        if org_filter is not None:
+            stmt = stmt.where(org_filter)
+        return stmt
+
+    def _apply_filters(self, stmt, filters: Mapping[str, Any] | None):
+        for key, value in (filters or {}).items():
+            if not hasattr(self.model, key):
+                raise ValueError(f"{self.model.__name__} has no column {key!r}")
+            stmt = stmt.where(getattr(self.model, key) == value)
+        return stmt
+
+    def _apply_order(self, stmt, order_by: str | Sequence[str] | None):
+        if order_by is None:
+            return stmt
+        fields = [order_by] if isinstance(order_by, str) else list(order_by)
+        clauses = []
+        for field in fields:
+            direction = desc if field.startswith("-") else asc
+            key = field[1:] if field.startswith("-") else field
+            if not hasattr(self.model, key):
+                raise ValueError(f"{self.model.__name__} has no column {key!r}")
+            clauses.append(direction(getattr(self.model, key)))
+        return stmt.order_by(*clauses)
+
+    async def list(
+        self,
+        *,
+        filters: Mapping[str, Any] | None = None,
+        order_by: str | Sequence[str] | None = None,
+        limit: int = 100,
+        offset: int = 0,
+    ) -> list[T]:
+        stmt = self._apply_filters(self._base_select(), filters)
+        stmt = self._apply_order(stmt, order_by)
+        stmt = stmt.limit(max(1, min(limit, 500))).offset(max(0, offset))
+        return list((await self.db.execute(stmt)).scalars().all())
+
+    async def count(self, *, filters: Mapping[str, Any] | None = None) -> int:
+        stmt = select(func.count()).select_from(self.model)
+        org_filter = self._org_filter()
+        if org_filter is not None:
+            stmt = stmt.where(org_filter)
+        stmt = self._apply_filters(stmt, filters)
+        return int((await self.db.execute(stmt)).scalar_one())
+
+    async def get(self, id: Any) -> T | None:
+        stmt = self._base_select().where(self.model.id == id)
+        return (await self.db.execute(stmt)).scalar_one_or_none()
+
+    async def require(self, id: Any) -> T:
+        row = await self.get(id)
+        if row is None:
+            raise LookupError(f"{self.model.__name__} {id!r} not found")
+        return row
+
+    async def create(self, **values: Any) -> T:
+        if hasattr(self.model, "organization_id"):
+            values["organization_id"] = self.organization_id
+        row = self.model(**values)
+        self.db.add(row)
+        await self.db.commit()
+        await self.db.refresh(row)
+        return row
+
+    async def update(self, id: Any, **values: Any) -> T | None:
+        row = await self.get(id)
+        if row is None:
+            return None
+        values.pop("id", None)
+        values.pop("organization_id", None)
+        for key, value in values.items():
+            if not hasattr(row, key):
+                raise ValueError(f"{self.model.__name__} has no attribute {key!r}")
+            setattr(row, key, value)
+        await self.db.commit()
+        await self.db.refresh(row)
+        return row
+
+    async def delete(self, id: Any) -> bool:
+        row = await self.get(id)
+        if row is None:
+            return False
+        await self.db.delete(row)
+        await self.db.commit()
+        return True

package/backend-sdk/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "palette-sdk"
-version = "0.1.3"
+version = "0.1.5"
 description = "Palette Platform SDK for building backend plugins"
 readme = "README.md"
 requires-python = ">=3.12"

package/lib/dev-simulator.js

@@ -250,9 +250,11 @@ const platform = {
     org_role: "owner",
   },
   organizationId: 1,
+  pluginId: ${JSON.stringify(manifest.id)},
   orgRole: "owner",
   orgs: [{ id: 1, name: "Local Dev Org", slug: "local-dev", theme_id: "default", logo_url: null }],
   agents: [],
+  permissions: ${JSON.stringify(manifest.permissions || [])},
   apiFetch,
   navigate: (path) => window.history.pushState(null, "", path),
   showToast: (message, type = "info") => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.7"
+    "@palettelab/sdk": "^0.1.10"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/template-fallback/templates/dashboard/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.7",
+    "@palettelab/sdk": "^0.1.10",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/database/backend/api/main.py

@@ -2,8 +2,6 @@
 
 from fastapi import Depends, HTTPException
 from pydantic import BaseModel
-from sqlalchemy import select
-
 from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
 from models import Note
 
@@ -16,11 +14,7 @@ class NoteIn(BaseModel):
 
 @router.get("/notes", dependencies=[require_permission("resources:read")])
 async def list_notes(ctx: PluginContext = Depends(get_plugin_context)) -> list[dict]:
-    rows = (
-        await ctx.db.execute(
-            select(Note).order_by(Note.id.desc())
-        )
-    ).scalars().all()
+    rows = await ctx.repo(Note).list(order_by="-id")
     return [{"id": r.id, "body": r.body} for r in rows]
 
 
@@ -31,8 +25,5 @@ async def create_note(
 ) -> dict:
     if not body.body.strip():
         raise HTTPException(status_code=400, detail="body required")
-    note = Note(organization_id=ctx.organization_id, body=body.body)
-    ctx.db.add(note)
-    await ctx.db.commit()
-    await ctx.db.refresh(note)
+    note = await ctx.repo(Note).create(body=body.body)
     return {"id": note.id, "body": note.body}

package/template-fallback/templates/database/package.json

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.7", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.10", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/package.json

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.7", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.10", "react": "^19.0.0" }
 }

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.7",
+    "@palettelab/sdk": "^0.1.10",
     "react": "^19.0.0"
   }
 }