@palettelab/cli 0.3.17 → 0.3.18

package/README.md

@@ -57,11 +57,17 @@ By default this starts:
 - A small local app shell on the first available port starting at http://localhost:3000
 - A local FastAPI backend runner on the first available port starting at http://localhost:8000
 - A mock Palette platform context for `usePlatform()`, toasts, org/user data, and authenticated API calls
+- A plugin-local SQLite database under `.palette/dev/` when `capabilities.database` or `database` is enabled
 
 Your frontend entry is bundled and watched. Your backend entry is loaded under
 `/api/v1/plugins/<your-id>/*` with a dev `PluginContext`, so normal SDK calls
 work without Docker or platform source.
 
+For Python apps with database tables, `ctx.db` is an async SQLAlchemy session in
+local dev. The simulator imports `backend/api/models.py` when present and creates
+tables from `palette_sdk.db.PluginBase.metadata`. Production installs still use
+the declared Alembic migrations and platform-managed Postgres/RLS.
+
 `3000` and `8000` are preferred defaults, not hard requirements. If either port is already in use, `pltt dev` automatically picks the next free port and prints the actual URLs.
 
 `pltt dev --platform` runs the full Docker `platform-dev` image for deeper
@@ -77,6 +83,7 @@ Environment variables:
 | `PALETTE_DEV_IMAGE` | `ghcr.io/palette-lab/platform-dev:latest` | Override the platform image for `--platform` |
 | `PALETTE_FRONTEND_PORT` | `3000` | Preferred starting host port for the frontend |
 | `PALETTE_BACKEND_PORT` | `8000` | Preferred starting host port for the backend |
+| `PALETTE_DEV_DATABASE_URL` | `.palette/dev/<plugin-id>.sqlite3` | Override the local dev database URL |
 
 ### `pltt doctor`
 

package/lib/commands/init.js

@@ -84,6 +84,9 @@ function rewriteScaffold(destDir, slug, displayName) {
   const rewrittenManifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"))
   rewrittenManifest.id = slug
   rewrittenManifest.name = displayName
+  if (rewrittenManifest.database?.schema) {
+    rewrittenManifest.database.schema = `app_${slug.replace(/-/g, "_")}`
+  }
   fs.writeFileSync(manifestPath, JSON.stringify(rewrittenManifest, null, 2) + "\n")
 }
 

package/lib/dev-simulator.js

@@ -44,12 +44,17 @@ function pyprojectDependencies(cwd) {
   return extractPyprojectDependencies(fs.readFileSync(pyprojectPath, "utf8"))
 }
 
-function ensurePythonEnv(cwd, devDir) {
+function needsDatabase(manifest) {
+  return Boolean(manifest.database || manifest.capabilities?.database)
+}
+
+function ensurePythonEnv(cwd, devDir, manifest) {
   const hostPython = process.env.PALETTE_PYTHON || "python3"
   const venvDir = path.join(devDir, "backend-venv")
   const venvPython = path.join(venvDir, "bin", "python")
   const lockPath = path.join(venvDir, ".palette-dev-deps-lock")
-  const deps = Array.from(new Set([...pyprojectDependencies(cwd), "uvicorn>=0.30.0"]))
+  const dbDeps = needsDatabase(manifest) ? ["aiosqlite>=0.20.0", "greenlet>=3.0.0"] : []
+  const deps = Array.from(new Set([...pyprojectDependencies(cwd), ...dbDeps, "uvicorn>=0.30.0"]))
   const lock = JSON.stringify(deps)
 
   if (!fs.existsSync(venvPython)) {
@@ -88,10 +93,13 @@ function ensurePythonEnv(cwd, devDir) {
 function writeBackendRunner(cwd, devDir, manifest, backendEntry) {
   const runner = path.join(devDir, "backend_runner.py")
   const sdkPath = localBackendSdkPath()
+  const databasePath = path.join(devDir, `${manifest.id}.sqlite3`)
   const content = `from __future__ import annotations
 
+import importlib
 import importlib.util
 import json
+import os
 import pathlib
 import sys
 from types import SimpleNamespace
@@ -104,6 +112,8 @@ ROOT = pathlib.Path(${JSON.stringify(cwd)}).resolve()
 ENTRY = pathlib.Path(${JSON.stringify(path.resolve(cwd, backendEntry))}).resolve()
 MANIFEST = json.loads(${JSON.stringify(JSON.stringify(manifest))})
 SDK_PATH = ${JSON.stringify(sdkPath || "")}
+DATABASE_ENABLED = bool(MANIFEST.get("database") or MANIFEST.get("capabilities", {}).get("database"))
+DATABASE_URL = os.environ.get("PALETTE_DEV_DATABASE_URL", "sqlite+aiosqlite:///${databasePath.replace(/\\/g, "/")}")
 
 if SDK_PATH:
     sys.path.insert(0, SDK_PATH)
@@ -118,9 +128,21 @@ router = getattr(module, "router", None)
 if router is None:
     raise RuntimeError(f"backend entry has no router export: {ENTRY}")
 
+engine = None
+SessionLocal = None
+if DATABASE_ENABLED:
+    from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+    from palette_sdk.db import PluginBase
+
+    models_file = ENTRY.parent / "models.py"
+    if models_file.exists():
+        importlib.import_module("models")
+
+    engine = create_async_engine(DATABASE_URL)
+    SessionLocal = async_sessionmaker(engine, expire_on_commit=False)
+
 class DevPluginContextMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):
-        request.state.db = None
         request.state.user = SimpleNamespace(
             id="dev-user",
             email="developer@palette.local",
@@ -132,7 +154,17 @@ class DevPluginContextMiddleware(BaseHTTPMiddleware):
         request.state.plugin_permissions = MANIFEST.get("permissions", [])
         request.state.plugin_config = {}
         request.state.storage = None
-        return await call_next(request)
+        if SessionLocal is None:
+            request.state.db = None
+            return await call_next(request)
+
+        async with SessionLocal() as session:
+            request.state.db = session
+            try:
+                return await call_next(request)
+            except Exception:
+                await session.rollback()
+                raise
 
 app = FastAPI(title=f"{MANIFEST.get('name', 'Palette Plugin')} Local Backend")
 app.add_middleware(
@@ -144,6 +176,13 @@ app.add_middleware(
 )
 app.add_middleware(DevPluginContextMiddleware)
 app.include_router(router, prefix=f"/api/v1/plugins/{MANIFEST['id']}")
+
+@app.on_event("startup")
+async def create_local_database_tables():
+    if engine is None:
+        return
+    async with engine.begin() as conn:
+        await conn.run_sync(PluginBase.metadata.create_all)
 `
   fs.writeFileSync(runner, content)
   return runner
@@ -155,7 +194,7 @@ function startBackend(cwd, devDir, manifest, backendPort) {
   const absEntry = path.resolve(cwd, backendEntry)
   if (!fs.existsSync(absEntry)) throw new Error(`backend entry not found: ${backendEntry}`)
 
-  const python = ensurePythonEnv(cwd, devDir)
+  const python = ensurePythonEnv(cwd, devDir, manifest)
   const runner = writeBackendRunner(cwd, devDir, manifest, backendEntry)
   const sdkPath = localBackendSdkPath()
   const env = { ...process.env }

package/package.json

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

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

@@ -18,7 +18,7 @@ class NoteIn(BaseModel):
 async def list_notes(ctx: PluginContext = Depends(get_plugin_context)) -> list[dict]:
     rows = (
         await ctx.db.execute(
-            select(Note).where(Note.organization_id == ctx.organization_id).order_by(Note.id.desc())
+            select(Note).order_by(Note.id.desc())
         )
     ).scalars().all()
     return [{"id": r.id, "body": r.body} for r in rows]

package/template-fallback/templates/database/backend/migrations/env.py

@@ -0,0 +1,37 @@
+"""Alembic environment for the plugin database template."""
+
+from __future__ import annotations
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from models import Note  # noqa: F401 - registers model metadata
+from palette_sdk.db import PluginBase
+
+config = context.config
+target_metadata = PluginBase.metadata
+
+
+def run_migrations_offline() -> None:
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(url=url, target_metadata=target_metadata, literal_binds=True)
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(connection=connection, target_metadata=target_metadata)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

package/template-fallback/templates/database/backend/migrations/{001_init.py → versions/001_init.py}

@@ -1,8 +1,7 @@
-"""Initial migration — creates notes table with org RLS."""
+"""Initial migration - creates notes table with org RLS."""
 
 from alembic import op
 import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
 
 from palette_sdk.db import ensure_org_rls
 
@@ -14,13 +13,13 @@ def upgrade() -> None:
     op.create_table(
         "notes",
         sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
-        sa.Column("organization_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("organization_id", sa.BigInteger(), nullable=False),
         sa.Column("body", sa.Text(), nullable=False),
     )
-    op.create_index("ix_notes_organization_id", "notes", ["organization_id"])
-    ensure_org_rls("notes")
+    op.create_index("ix_notes_org", "notes", ["organization_id"])
+    ensure_org_rls(op, "notes")
 
 
 def downgrade() -> None:
-    op.drop_index("ix_notes_organization_id", table_name="notes")
+    op.drop_index("ix_notes_org", table_name="notes")
     op.drop_table("notes")

package/template-fallback/templates/database/frontend/src/index.tsx

@@ -6,52 +6,178 @@ import type { PluginComponentProps } from "@palettelab/sdk"
 
 type Note = { id: number; body: string }
 
+const styles = `
+.notes-app {
+  min-height: 100vh;
+  background: #f6f3ee;
+  color: #111827;
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+.notes-shell {
+  width: min(100%, 880px);
+  margin: 0 auto;
+  padding: 32px 20px;
+}
+.notes-kicker {
+  margin: 0 0 8px;
+  color: #7c3aed;
+  font-size: 12px;
+  font-weight: 800;
+  letter-spacing: .14em;
+  text-transform: uppercase;
+}
+.notes-title {
+  margin: 0;
+  font-size: clamp(32px, 4vw, 48px);
+  line-height: 1;
+}
+.notes-copy {
+  max-width: 640px;
+  margin: 14px 0 24px;
+  color: #667085;
+  line-height: 1.65;
+}
+.notes-form {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  gap: 10px;
+}
+.notes-input {
+  min-height: 48px;
+  border: 1px solid #c9c3ba;
+  background: #fff;
+  padding: 0 14px;
+  font: inherit;
+  outline: none;
+}
+.notes-input:focus {
+  border-color: #7c3aed;
+  box-shadow: 0 0 0 3px rgba(124, 58, 237, .14);
+}
+.notes-button {
+  min-height: 48px;
+  border: 0;
+  background: #7c3aed;
+  color: #fff;
+  padding: 0 22px;
+  font: inherit;
+  font-weight: 800;
+  cursor: pointer;
+}
+.notes-button:disabled {
+  background: #a7b1c2;
+  cursor: not-allowed;
+}
+.notes-list {
+  margin-top: 16px;
+  border: 1px solid #ded8cf;
+  background: #fff;
+  box-shadow: 0 18px 40px rgba(31, 41, 51, .08);
+}
+.notes-empty,
+.notes-item {
+  margin: 0;
+  padding: 16px 18px;
+  border-top: 1px solid #ece7df;
+}
+.notes-empty,
+.notes-item:first-child {
+  border-top: 0;
+}
+.notes-empty {
+  color: #667085;
+}
+@media (max-width: 680px) {
+  .notes-form {
+    grid-template-columns: 1fr;
+  }
+}
+`
+
 export default function NotesApp(_props: PluginComponentProps) {
-  const { apiFetch, showToast } = usePlatform()
+  const { apiFetch, showToast, user } = usePlatform()
   const [notes, setNotes] = useState<Note[]>([])
   const [body, setBody] = useState("")
+  const [loading, setLoading] = useState(true)
+  const [saving, setSaving] = useState(false)
 
   async function load() {
-    const r = await apiFetch("/api/v1/plugins/my-db-plugin/notes")
-    setNotes(await r.json())
+    setLoading(true)
+    try {
+      const response = await apiFetch("/api/v1/plugins/my-db-plugin/notes")
+      if (!response.ok) throw new Error("Could not load notes")
+      setNotes(await response.json())
+    } finally {
+      setLoading(false)
+    }
   }
+
   useEffect(() => {
     load()
-  }, [])
+  }, [apiFetch])
 
   async function add() {
-    if (!body.trim()) return
-    const r = await apiFetch("/api/v1/plugins/my-db-plugin/notes", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ body }),
-    })
-    if (r.ok) {
+    const cleaned = body.trim()
+    if (!cleaned) return
+    setSaving(true)
+    try {
+      const response = await apiFetch("/api/v1/plugins/my-db-plugin/notes", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ body: cleaned }),
+      })
+      if (!response.ok) throw new Error("Could not save note")
       setBody("")
       showToast("Note saved", "success")
-      load()
+      await load()
+    } finally {
+      setSaving(false)
     }
   }
 
   return (
-    <div className="p-6 space-y-3">
-      <h1 className="text-2xl font-bold">Notes</h1>
-      <div className="flex gap-2">
-        <input
-          className="border rounded px-2 py-1 text-sm flex-1"
-          value={body}
-          onChange={(e) => setBody(e.target.value)}
-          placeholder="New note…"
-        />
-        <button onClick={add} className="px-3 py-1 rounded bg-primary text-primary-foreground text-sm">
-          Add
-        </button>
-      </div>
-      <ul className="space-y-1 text-sm">
-        {notes.map((n) => (
-          <li key={n.id} className="border rounded px-2 py-1">{n.body}</li>
-        ))}
-      </ul>
+    <div className="notes-app">
+      <style>{styles}</style>
+      <main className="notes-shell">
+        <p className="notes-kicker">Palette DB App</p>
+        <h1 className="notes-title">Org Notes</h1>
+        <p className="notes-copy">
+          Built for {user.name}. This app uses a Python backend and the Palette
+          SDK database session exposed as <code>ctx.db</code>.
+        </p>
+        <section className="notes-form">
+          <input
+            className="notes-input"
+            value={body}
+            onChange={(event) => setBody(event.target.value)}
+            onKeyDown={(event) => {
+              if (event.key === "Enter") void add()
+            }}
+            placeholder="New note..."
+          />
+          <button
+            type="button"
+            onClick={() => void add()}
+            disabled={saving || body.trim().length === 0}
+            className="notes-button"
+          >
+            {saving ? "Saving" : "Add Note"}
+          </button>
+        </section>
+        <section className="notes-list">
+          {loading ? (
+            <p className="notes-empty">Loading notes...</p>
+          ) : notes.length === 0 ? (
+            <p className="notes-empty">No notes yet.</p>
+          ) : (
+            notes.map((note) => (
+              <p key={note.id} className="notes-item">
+                {note.body}
+              </p>
+            ))
+          )}
+        </section>
+      </main>
     </div>
   )
 }

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

@@ -20,6 +20,10 @@
     "file_uploads": false,
     "external_network": []
   },
+  "database": {
+    "schema": "app_my_db_plugin",
+    "migrations": "./backend/migrations"
+  },
   "frontend": { "entry": "./frontend/src/index.tsx", "sandbox": true },
   "backend": { "entry": "./backend/api/main.py" },
   "permissions": ["resources:read", "resources:write"]

package/template-fallback/templates/database/pyproject.toml

@@ -6,5 +6,7 @@ dependencies = [
   "fastapi>=0.129.0",
   "sqlalchemy>=2.0.47",
   "alembic>=1.17.0",
+  "aiosqlite>=0.20.0",
+  "greenlet>=3.0.0",
   # `pltt test` ships the backend SDK on PYTHONPATH.
 ]