@palettelab/cli 0.3.25 → 0.3.27

package/docs/python-backend-sdk.md

@@ -0,0 +1,641 @@
+# Palette Python Backend SDK Developer Guide
+
+This guide is for developers building Palette apps with a Python/FastAPI
+backend. Frontend code uses the npm package `@palettelab/sdk`; Python backend
+code uses `palette_sdk`, which is embedded in `@palettelab/cli` for local dev
+and provided by the Palette runtime in hosted sandbox and production.
+
+## 1. Where The Backend Runs
+
+Palette supports three backend development modes:
+
+| Mode | Command | Uses real Palette OS services | Docker |
+|---|---|---:|---:|
+| Local SDK simulator | `pltt dev` | No | No |
+| Hosted sandbox preview | `pltt dev --sandbox --env staging` | Yes | No |
+| Internal local platform parity | `pltt dev --platform` | Local platform container | Yes |
+
+Use `pltt dev` for the fastest loop while writing code. Use hosted sandbox
+when the app must use real OS features such as login, organization context,
+Data Rooms, storage, install state, review previews, logs, and platform APIs.
+
+## 2. Generated App Structure
+
+A Python backend app normally looks like this:
+
+```text
+my-app/
+  palette-plugin.json
+  frontend/
+    src/index.tsx
+  backend/
+    api/
+      main.py
+      models.py
+    migrations/
+      env.py
+      versions/
+        001_init.py
+```
+
+The backend entry is declared in `palette-plugin.json`:
+
+```json
+{
+  "id": "finance-tools",
+  "name": "Finance Tools",
+  "frontend": { "entry": "./frontend/src/index.tsx" },
+  "backend": { "entry": "./backend/api/main.py" },
+  "permissions": [
+    "resources:read",
+    "resources:write",
+    "data_rooms:read",
+    "data_rooms:write"
+  ],
+  "capabilities": { "database": true },
+  "database": {
+    "schema": "app_finance_tools",
+    "migrations": "./backend/migrations"
+  }
+}
+```
+
+Declare only the permissions your app actually needs. Backend routes should
+also gate access with `require_permission(...)`.
+
+## 3. Basic Backend Route
+
+Every backend file exports a `PluginRouter`. Routes are mounted by the platform
+under `/api/v1/plugins/<plugin-id>`.
+
+```python
+from fastapi import Depends
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context
+
+router = PluginRouter(tags=["finance-tools"])
+
+
+@router.get("/me")
+async def me(ctx: PluginContext = Depends(get_plugin_context)):
+    return {
+        "user_id": ctx.user_id,
+        "organization_id": ctx.organization_id,
+        "org_role": ctx.org_role,
+        "plugin_id": ctx.plugin_id,
+    }
+```
+
+If the app id is `finance-tools`, this route is available at:
+
+```text
+GET /api/v1/plugins/finance-tools/me
+```
+
+## 4. PluginContext Reference
+
+`PluginContext` is injected into each route:
+
+```python
+async def route(ctx: PluginContext = Depends(get_plugin_context)):
+    ...
+```
+
+Available context values:
+
+| Field/helper | Purpose |
+|---|---|
+| `ctx.db` | Async SQLAlchemy session for the app backend |
+| `ctx.user_id` | Authenticated Palette user id |
+| `ctx.organization_id` | Current organization id |
+| `ctx.org_role` | User role in the current organization |
+| `ctx.plugin_id` | Current app/plugin id |
+| `ctx.permissions` | Permissions granted from `palette-plugin.json` |
+| `ctx.storage` | Runtime storage service, when available |
+| `ctx.data_rooms` | Backend Data Room client |
+| `ctx.config` | App install/config values |
+| `ctx.logger` | Runtime logger for backend code |
+| `ctx.repo(Model)` | Org-safe CRUD helper for app-owned tables |
+| `ctx.has_permission(permission)` | Check one declared permission |
+| `ctx.has_any_permission([...])` | Check at least one permission |
+| `ctx.has_all_permissions([...])` | Check every listed permission |
+| `ctx.config_value(key, default)` | Read optional config |
+| `ctx.require_config(key)` | Read required config or raise |
+| `ctx.secret(key, default)` | Read a secret from app config or environment |
+
+## 5. Permissions
+
+Use route-level permission guards for normal APIs:
+
+```python
+from fastapi import Depends
+from palette_sdk import (
+    PluginRouter,
+    PluginContext,
+    get_plugin_context,
+    require_permission,
+)
+
+router = PluginRouter(tags=["finance-tools"])
+
+
+@router.get("/reports", dependencies=[require_permission("resources:read")])
+async def reports(ctx: PluginContext = Depends(get_plugin_context)):
+    return {"items": []}
+```
+
+Use inline checks only when the route supports multiple behavior paths:
+
+```python
+@router.get("/dashboard", dependencies=[require_permission("resources:read")])
+async def dashboard(ctx: PluginContext = Depends(get_plugin_context)):
+    can_write = ctx.has_permission("resources:write")
+    can_sync = ctx.has_all_permissions(["data_rooms:read", "data_rooms:write"])
+
+    return {
+        "can_write": can_write,
+        "can_sync": can_sync,
+    }
+```
+
+Known permissions currently include:
+
+```text
+tasks:read, tasks:write
+data_rooms:read, data_rooms:write
+agents:read, agents:write
+chat:read, chat:write
+routines:read, routines:write
+members:read
+resources:read, resources:write
+```
+
+## 6. App-Owned Data
+
+Apps can ship their own tables and migrations. Use `OrgScopedTable` for data
+that belongs to an organization.
+
+`backend/api/models.py`:
+
+```python
+from sqlalchemy import Numeric, 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), nullable=False)
+    amount: Mapped[float] = mapped_column(Numeric(12, 2), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), default="draft")
+```
+
+`OrgScopedTable` adds `organization_id` automatically. Do not manually set
+`organization_id` in route code; `ctx.repo(Model)` handles it.
+
+### Migration Example
+
+`backend/migrations/versions/001_init.py`:
+
+```python
+from alembic import op
+import sqlalchemy as sa
+from palette_sdk.db import ensure_org_rls
+
+
+revision = "001_init"
+down_revision = None
+
+
+def upgrade():
+    op.create_table(
+        "invoices",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("organization_id", sa.BigInteger(), nullable=False),
+        sa.Column("customer_name", sa.String(length=255), nullable=False),
+        sa.Column("amount", sa.Numeric(12, 2), nullable=False),
+        sa.Column("status", sa.String(length=32), nullable=False),
+    )
+    op.create_index("ix_invoices_org", "invoices", ["organization_id"])
+    ensure_org_rls(op, "invoices")
+
+
+def downgrade():
+    op.drop_table("invoices")
+```
+
+`ensure_org_rls(op, "invoices")` enables row-level security so each
+organization can only access its own rows.
+
+## 7. Repository CRUD
+
+Use `ctx.repo(Model)` instead of writing repeated org filters.
+
+```python
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+from models import Invoice
+
+router = PluginRouter(tags=["finance-tools"])
+
+
+class InvoiceIn(BaseModel):
+    customer_name: str
+    amount: float
+
+
+@router.get("/invoices", dependencies=[require_permission("resources:read")])
+async def list_invoices(ctx: PluginContext = Depends(get_plugin_context)):
+    rows = await ctx.repo(Invoice).list(order_by="-id", limit=100)
+    return [
+        {
+            "id": row.id,
+            "customer_name": row.customer_name,
+            "amount": float(row.amount),
+            "status": row.status,
+        }
+        for row in rows
+    ]
+
+
+@router.post("/invoices", dependencies=[require_permission("resources:write")])
+async def create_invoice(
+    body: InvoiceIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    invoice = await ctx.repo(Invoice).create(
+        customer_name=body.customer_name,
+        amount=body.amount,
+    )
+    return {"id": invoice.id}
+
+
+@router.patch("/invoices/{invoice_id}", dependencies=[require_permission("resources:write")])
+async def update_invoice(
+    invoice_id: int,
+    body: InvoiceIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    invoice = await ctx.repo(Invoice).update(invoice_id, **body.model_dump())
+    if invoice is None:
+        raise HTTPException(status_code=404, detail="invoice not found")
+    return {"id": invoice.id}
+
+
+@router.delete("/invoices/{invoice_id}", dependencies=[require_permission("resources:write")])
+async def delete_invoice(
+    invoice_id: int,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    deleted = await ctx.repo(Invoice).delete(invoice_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="invoice not found")
+    return {"deleted": True}
+```
+
+Repository methods:
+
+```python
+await ctx.repo(Model).list(filters=None, order_by=None, limit=100, offset=0)
+await ctx.repo(Model).count(filters=None)
+await ctx.repo(Model).get(id)
+await ctx.repo(Model).require(id)
+await ctx.repo(Model).create(**values)
+await ctx.repo(Model).update(id, **values)
+await ctx.repo(Model).delete(id)
+```
+
+## 8. Data Rooms From Python
+
+Use `ctx.data_rooms` when backend code needs to create folders, find files, or
+read/write documents in Palette Data Rooms.
+
+### Create Or Find A Room
+
+```python
+@router.post("/setup-data-room", dependencies=[require_permission("data_rooms:write")])
+async def setup_data_room(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.ensure_room(
+        "Finance",
+        description="Finance documents used by the Finance Tools app",
+    )
+    return room
+```
+
+### Create Custom Folders By Name
+
+```python
+@router.post("/setup-folders", dependencies=[require_permission("data_rooms:write")])
+async def setup_folders(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/2026",
+        create=True,
+    )
+
+    return {
+        "room_id": room["id"],
+        "folder_id": folder["id"],
+        "folder_name": folder["name"],
+    }
+```
+
+`resolve_folder_path(..., create=True)` creates missing folders in the path.
+Pass a list instead of a string when folder names can contain `/`:
+
+```python
+folder = await ctx.data_rooms.resolve_folder_path(
+    room["id"],
+    ["Clients", "Acme/International", "Invoices"],
+    create=True,
+)
+```
+
+### Upload A File
+
+```python
+@router.post("/write-summary", dependencies=[require_permission("data_rooms:write")])
+async def write_summary(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.ensure_room("Finance")
+    folder = await ctx.data_rooms.resolve_folder_path(
+        room["id"],
+        "Reports/Monthly",
+        create=True,
+    )
+
+    file = await ctx.data_rooms.upload_file(
+        room["id"],
+        "summary.txt",
+        b"Generated from Python backend",
+        folder_id=folder["id"],
+        content_type="text/plain",
+    )
+
+    return file
+```
+
+### Find And Read A File
+
+```python
+@router.get("/read-summary", dependencies=[require_permission("data_rooms:read")])
+async def read_summary(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.require_room_by_name("Finance")
+    folder = await ctx.data_rooms.resolve_folder_path(room["id"], "Reports/Monthly")
+
+    if folder is None:
+        return {"found": False}
+
+    file = await ctx.data_rooms.find_file_by_name(
+        room["id"],
+        "summary.txt",
+        folder_id=folder["id"],
+    )
+
+    if file is None:
+        return {"found": False}
+
+    content = await ctx.data_rooms.read_file_bytes(file["id"])
+    return {
+        "found": True,
+        "text": content.decode("utf-8"),
+    }
+```
+
+### List Room Contents
+
+```python
+@router.get("/room-contents", dependencies=[require_permission("data_rooms:read")])
+async def room_contents(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.require_room_by_name("Finance")
+    contents = await ctx.data_rooms.contents(room["id"])
+    return contents
+```
+
+Available Data Room helpers:
+
+```python
+await ctx.data_rooms.list()
+await ctx.data_rooms.create(name, description=None)
+await ctx.data_rooms.find_room_by_name(name, case_sensitive=False)
+await ctx.data_rooms.require_room_by_name(name, case_sensitive=False)
+await ctx.data_rooms.ensure_room(name, description=None)
+await ctx.data_rooms.contents(room_id, folder_id=None)
+await ctx.data_rooms.create_folder(room_id, name, parent_folder_id=None)
+await ctx.data_rooms.find_folder_by_name(
+    room_id,
+    name,
+    parent_folder_id=None,
+    case_sensitive=False,
+)
+await ctx.data_rooms.ensure_folder(room_id, name, parent_folder_id=None)
+await ctx.data_rooms.resolve_folder_path(
+    room_id,
+    "A/B/C",
+    create=False,
+    case_sensitive=False,
+)
+await ctx.data_rooms.find_file_by_name(
+    room_id,
+    name,
+    folder_id=None,
+    case_sensitive=False,
+)
+await ctx.data_rooms.read_file_bytes(file_id)
+await ctx.data_rooms.upload_file(
+    room_id,
+    filename,
+    content,
+    folder_id=None,
+    content_type=None,
+)
+```
+
+In local unit tests outside the Palette runtime, inject a fake Data Room service
+if you need to test routes that call `ctx.data_rooms`. In hosted sandbox and
+real OS runtime, the platform injects the real service.
+
+## 9. Config And Secrets
+
+Use config for app install settings and secrets for sensitive values.
+
+```python
+@router.get("/sync-config", dependencies=[require_permission("resources:read")])
+async def sync_config(ctx: PluginContext = Depends(get_plugin_context)):
+    timezone = ctx.config_value("timezone", "UTC")
+    required_workspace = ctx.require_config("workspace_id")
+    api_key = ctx.secret("FINANCE_API_KEY")
+
+    return {
+        "timezone": timezone,
+        "workspace_id": required_workspace,
+        "has_api_key": bool(api_key),
+    }
+```
+
+`ctx.secret("KEY")` first checks app config secrets and then falls back to the
+process environment variable named `KEY`.
+
+## 10. Lifecycle Hooks
+
+Lifecycle hooks let an app seed defaults or clean up app-owned data when the
+platform installs, updates, enables, disables, or uninstalls the app.
+
+```python
+from palette_sdk import LifecycleHooks, PluginContext
+from models import DefaultSetting
+
+lifecycle = LifecycleHooks()
+
+
+@lifecycle.on_install
+async def seed_defaults(ctx: PluginContext):
+    await ctx.repo(DefaultSetting).create(name="currency", value="USD")
+
+
+@lifecycle.on_enable
+async def on_enable(ctx: PluginContext):
+    ctx.logger.info("finance tools enabled for org %s", ctx.organization_id)
+```
+
+## 11. Calling Backend APIs From Frontend
+
+Frontend code should call backend routes through the platform API helper, not by
+hardcoding backend origins.
+
+```tsx
+import { createPaletteClient } from "@palettelab/sdk"
+
+const palette = createPaletteClient()
+
+async function loadInvoices() {
+  const res = await palette.apiFetch("/api/v1/plugins/finance-tools/invoices")
+  return res.json()
+}
+```
+
+During `pltt dev`, the simulator routes this to the local backend. In hosted
+sandbox or OS runtime, it goes through the real platform shell and auth context.
+
+## 12. Local Development
+
+Create and run an app:
+
+```bash
+npx --yes @palettelab/cli@latest init finance-tools --template database
+cd finance-tools
+npm install
+npx --yes @palettelab/cli@latest dev
+```
+
+Useful local checks:
+
+```bash
+npx --yes @palettelab/cli@latest test
+npx --yes @palettelab/cli@latest package
+```
+
+The CLI checks manifest shape, SDK compatibility, frontend bundling, backend
+imports, backend route permission gates, declared permissions, migration safety,
+package dependency policy, and backend package size.
+
+## 13. Test In Real Palette OS Without Docker
+
+Configure the hosted sandbox once:
+
+```bash
+npx --yes @palettelab/cli@latest login \
+  --env staging \
+  --url https://YOUR-PALETTE-STAGING-URL \
+  --token pltt_xxxxx
+```
+
+Then publish a sandbox preview:
+
+```bash
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+The CLI packages the app, uploads it to the staging Palette environment,
+creates a preview publish, and prints a real OS preview URL. Open that URL to
+test the app with OS shell, auth context, organization context, Data Rooms,
+storage, logs, install/review behavior, and platform APIs.
+
+For internal test sandboxes, the backend environment can set:
+
+```bash
+APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true
+```
+
+That lets passing preview publishes become active without manual approval.
+
+## 14. Common Mistakes
+
+- Do not import `@palettelab/sdk` from Python. That package is for frontend
+  JavaScript/React code only.
+- Do not hardcode backend URLs in frontend code. Use the platform API helper.
+- Do not manually set `organization_id` when using `ctx.repo(Model).create`.
+- Do not query cross-org data. The platform runtime and RLS are designed around
+  the current organization context.
+- Do not skip `require_permission(...)` on backend routes unless the route is
+  intentionally configured as public in the manifest.
+- Do not commit publish tokens, app secrets, or generated `.palette/` local
+  state.
+- Use hosted sandbox when you need real Data Rooms, login, organization,
+  install, logs, and OS behavior without Docker.
+
+## 15. Complete Minimal Example
+
+`backend/api/main.py`:
+
+```python
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+from models import Note
+
+router = PluginRouter(tags=["notes-app"])
+
+
+class NoteIn(BaseModel):
+    body: str
+
+
+@router.get("/notes", dependencies=[require_permission("resources:read")])
+async def list_notes(ctx: PluginContext = Depends(get_plugin_context)):
+    rows = await ctx.repo(Note).list(order_by="-id")
+    return [{"id": row.id, "body": row.body} for row in rows]
+
+
+@router.post("/notes", dependencies=[require_permission("resources:write")])
+async def create_note(
+    body: NoteIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    if not body.body.strip():
+        raise HTTPException(status_code=400, detail="body required")
+
+    note = await ctx.repo(Note).create(body=body.body)
+
+    room = await ctx.data_rooms.ensure_room("Notes")
+    folder = await ctx.data_rooms.resolve_folder_path(
+        room["id"],
+        "Created From Backend",
+        create=True,
+    )
+    await ctx.data_rooms.upload_file(
+        room["id"],
+        f"note-{note.id}.txt",
+        note.body.encode("utf-8"),
+        folder_id=folder["id"],
+        content_type="text/plain",
+    )
+
+    return {"id": note.id, "body": note.body}
+```
+
+This route stores app-owned data in the app database and writes a related file
+into Palette Data Rooms from the Python backend.

package/lib/commands/build.js

@@ -13,6 +13,10 @@ const BANNED_PATTERNS = [
   { re: /\bpublic\./, reason: "plugin migrations must not reference the platform's public schema" },
   { re: /\bSET\s+ROLE\b/i, reason: "SET ROLE in migrations escalates out of the plugin sandbox" },
   { re: /\bALTER\s+ROLE\b/i, reason: "ALTER ROLE is reserved for the platform" },
+  { re: /\bGRANT\b/i, reason: "GRANT is reserved for the platform" },
+  { re: /\bCREATE\s+EXTENSION\b/i, reason: "CREATE EXTENSION is reserved for the platform" },
+  { re: /\bALTER\s+DATABASE\b/i, reason: "ALTER DATABASE is not allowed in plugin migrations" },
+  { re: /\bDROP\s+SCHEMA\b/i, reason: "DROP SCHEMA is not allowed in plugin migrations" },
 ]
 
 function lintMigrationFile(absPath) {

package/lib/dev-simulator.js

@@ -229,7 +229,7 @@ async function apiFetch(path, init) {
   return fetch(target, init)
 }
 
-const platform = {
+const basePlatform = {
   user: {
     id: "dev-user",
     email: "developer@palette.local",
@@ -263,6 +263,11 @@ const platform = {
   },
 }
 
+function normalizePaletteLanguage(language, fallback = "en") {
+  const value = String(language || "").trim().toLowerCase()
+  return value ? value.split("-")[0] : fallback
+}
+
 function Toasts() {
   const [items, setItems] = React.useState([])
   React.useEffect(() => {
@@ -280,6 +285,30 @@ function Toasts() {
 }
 
 function Shell() {
+  const [language, updateLanguage] = React.useState(() => normalizePaletteLanguage(navigator.language))
+  const platform = React.useMemo(() => ({
+    ...basePlatform,
+    language,
+    fallbackLanguage: "en",
+    supportedLanguages: ["en", "ko"],
+    setLanguage: (nextLanguage) => {
+      const normalized = normalizePaletteLanguage(nextLanguage)
+      updateLanguage(normalized)
+      document.documentElement.lang = normalized
+      window.dispatchEvent(new CustomEvent("palette:language-change", { detail: { language: normalized } }))
+    },
+  }), [language])
+
+  React.useEffect(() => {
+    document.documentElement.lang = language
+  }, [language])
+
+  React.useEffect(() => {
+    const onLanguageChange = () => updateLanguage(normalizePaletteLanguage(navigator.language))
+    window.addEventListener("languagechange", onLanguageChange)
+    return () => window.removeEventListener("languagechange", onLanguageChange)
+  }, [])
+
   return React.createElement(PluginProvider, { value: platform },
     React.createElement("main", { className: "palette-local-shell" },
       React.createElement(Plugin, { platform }),