@palettelab/cli 0.3.22 → 0.3.24

package/README.md

@@ -21,6 +21,280 @@ npx @palettelab/cli <command>
 pltt <command>
 ```
 
+## Quick Start: Build And Test A Palette App
+
+Use this flow when a developer wants to create an app, run it locally, then test
+it inside the real Palette OS without Docker.
+
+```bash
+npx --yes @palettelab/cli@latest init simple-todo --template database
+cd simple-todo
+npm install
+npx --yes @palettelab/cli@latest dev
+```
+
+`pltt dev` runs the local SDK simulator. It is the fastest loop for frontend,
+backend, manifest, SDK hooks, and local database checks. It does not require
+Docker and does not publish anything to the platform.
+
+When the app is ready to test with real Palette OS services, configure a hosted
+sandbox environment and run:
+
+```bash
+npx --yes @palettelab/cli@latest login \
+  --env staging \
+  --url https://YOUR-PALETTE-STAGING-URL \
+  --token pltt_xxxxx
+
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+The hosted sandbox flow packages the app, uploads it to the configured Palette
+environment, creates a preview publish, and prints a real OS preview URL. Use
+that URL to test routing, OS shell behavior, login context, organization
+context, Data Room APIs, storage, install/review behavior, logs, permissions,
+and platform APIs.
+
+## Staging URL
+
+The staging URL is the base URL of the Palette platform backend/API
+environment. The CLI appends the API paths itself, for example:
+
+- `/api/v1/appstore/sign-upload`
+- `/api/v1/appstore/publish`
+- `/api/v1/developer/publish-tokens`
+- `/api/superadmin/publish-tokens`
+
+Use the same public origin only if that origin proxies API routes to the
+backend. For example, `https://apps.pltt.xyz` is valid only when these paths are
+served by the backend, not by the frontend catch-all route:
+
+```text
+/api/v1/*
+/api/superadmin/*
+```
+
+Validate a staging URL before giving it to developers:
+
+```bash
+curl https://YOUR-PALETTE-STAGING-URL/api/v1/health
+```
+
+A valid staging URL returns a backend health JSON response. If it returns the
+Palette frontend HTML, it is a frontend-only URL and the CLI cannot publish to
+it. In that case either use the real backend domain, for example
+`https://api.your-domain.example`, or update the web server/reverse proxy so
+`/api/v1/*` and `/api/superadmin/*` go to the backend.
+
+## Publish Token
+
+Every developer needs a publish token before they can use hosted sandbox or
+publish commands. Tokens start with `pltt_`.
+
+Developers can create their own token after logging in to Palette:
+
+1. Open Palette OS in the browser.
+2. Open Settings.
+3. Go to Developer.
+4. Create a developer publish token.
+5. Copy the token immediately. The raw token is shown only once.
+
+Superadmins can also allocate tokens from the superadmin publish-token section.
+Use superadmin allocation for service accounts, CI, or developers who should
+not create their own token.
+
+Do not commit tokens to a repository. Store them through `pltt login` or an
+environment variable.
+
+## Configure A Hosted Sandbox
+
+The recommended setup is `pltt login`, which writes
+`~/.palette/config.json` with file mode `0600`:
+
+```bash
+npx --yes @palettelab/cli@latest login \
+  --env staging \
+  --url https://YOUR-PALETTE-STAGING-URL \
+  --token pltt_xxxxx
+```
+
+You can verify the saved environment with:
+
+```bash
+cat ~/.palette/config.json
+```
+
+You can also use environment variables instead of storing the token:
+
+```bash
+export PALETTE_STAGING_URL=https://YOUR-PALETTE-STAGING-URL
+export PALETTE_STAGING_TOKEN=pltt_xxxxx
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+Environment variable precedence:
+
+1. `PALETTE_<ENV>_URL` and `PALETTE_<ENV>_TOKEN`
+2. `PALETTE_PUBLISH_TOKEN` as a token fallback
+3. `~/.palette/config.json`
+4. `./palette.config.json` for repo-local overrides
+
+## Test Inside The Real Palette OS Without Docker
+
+Use hosted sandbox for real OS testing:
+
+```bash
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+This is the correct flow for internal teams that need real platform features
+without pushing the app to production approval and without running Docker on the
+developer machine.
+
+Expected behavior:
+
+1. The CLI runs local contract checks.
+2. The CLI bundles frontend and backend artifacts.
+3. The CLI uploads the package to the staging Palette environment.
+4. The platform creates a preview/review publish.
+5. The CLI prints the preview URL, status command, and logs command.
+6. The developer opens the preview URL inside the real Palette OS.
+
+For developer sandboxes where manual review should not block testing, the
+backend environment should run with:
+
+```bash
+APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true
+```
+
+With that backend setting enabled, passing sandbox preview publishes are marked
+active automatically, so developers can test OS shell, auth, Data Room,
+organization, install, permission, log, and platform API behavior immediately.
+
+Useful follow-up commands:
+
+```bash
+npx --yes @palettelab/cli@latest status --env staging
+npx --yes @palettelab/cli@latest logs simple-todo --env staging --follow
+```
+
+## Local-Only Versus OS Testing
+
+Use the right command for the kind of test you need:
+
+| Goal | Command | Docker | Uses real OS services |
+|---|---|---:|---:|
+| Fast SDK/frontend/backend loop | `pltt dev` | No | No |
+| Real OS preview in hosted cloud sandbox | `pltt dev --sandbox --env staging` | No | Yes |
+| Alias for hosted cloud sandbox | `pltt dev --cloud --env staging` | No | Yes |
+| Internal full local platform parity | `pltt dev --platform` | Yes | Local platform container |
+| Production/review publish | `pltt publish --env production` | No | Yes |
+
+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.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.
+
+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,8 @@
 
 from palette_sdk.plugin_router import PluginRouter
 from palette_sdk.plugin_context import PluginContext, get_plugin_context
+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 +26,8 @@ __all__ = [
     "PluginRouter",
     "PluginContext",
     "get_plugin_context",
+    "OrgRepository",
+    "LifecycleHooks",
     "ToolDefinition",
     "PluginManifest",
     "load_manifest",
@@ -45,4 +49,4 @@ __all__ = [
     "route_permission_issues",
 ]
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

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,6 +3,8 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+import logging
+import os
 from typing import Any
 
 from fastapi import Depends, Request
@@ -35,6 +37,29 @@ class PluginContext:
     permissions: list[str] = field(default_factory=list)
     storage: Any = None  # Platform storage service injected at runtime
     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:
@@ -60,4 +85,5 @@ async def get_plugin_context(request: Request) -> PluginContext:
         permissions=getattr(state, "plugin_permissions", []),
         storage=getattr(state, "storage", 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.4"
 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.22",
+  "version": "0.3.24",
   "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.9"
   },
   "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.9",
     "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.9", "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.9", "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.9",
     "react": "^19.0.0"
   }
 }