@palettelab/cli 0.3.17 → 0.3.19

package/README.md

@@ -8,7 +8,8 @@ The installed executable is `pltt`.
 
 - Node.js 18+
 - Python 3.12+ for local backend simulation
-- Docker Desktop only for `pltt dev --platform`
+- No Docker is required for normal app development, testing, or publishing.
+- Docker Desktop is only for internal `pltt dev --platform` parity checks.
 
 ## Install
 
@@ -48,8 +49,10 @@ Run a no-Docker local SDK simulator with your plugin mounted live. Run this from
 
 ```bash
 pltt dev
-pltt dev --platform
+pltt sandbox --env staging
+pltt dev --sandbox --env staging
 pltt dev --cloud --env staging
+pltt dev --platform
 ```
 
 By default this starts:
@@ -57,18 +60,27 @@ 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
-integration/parity testing. It pulls `ghcr.io/palette-lab/platform-dev:latest`
-and mounts your plugin at `/plugins/<your-id>`.
+`pltt dev --sandbox` skips Docker and publishes a reviewable preview to a configured Palette sandbox. This is the payment-gateway-style flow: your app uses local SDKs, while real platform services such as login, Data Room, storage, database policies, logs, review, and publish lifecycle run in the hosted sandbox. It defaults to `--env staging` unless `--env` or `PALETTE_ENV` is set, adds a 24-hour preview TTL by default, and prints the preview/status/log commands returned by the platform.
+
+`pltt dev --cloud` is kept as an alias for `--sandbox`.
 
-`pltt dev --cloud` skips Docker and publishes a reviewable preview to a configured cloud sandbox. It defaults to `--env staging` unless `--env` or `PALETTE_ENV` is set, adds a 24-hour preview TTL by default, and prints the preview/status/log commands returned by the platform.
+`pltt sandbox --env staging` is the same hosted preview flow as
+`pltt dev --sandbox --env staging`.
+
+`pltt dev --platform` runs the full Docker `platform-dev` image for internal platform parity testing. App developers should not need it. It pulls `ghcr.io/palette-lab/platform-dev:latest` and mounts your plugin at `/plugins/<your-id>`.
 
 Environment variables:
 
@@ -77,6 +89,16 @@ 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 login`
+
+Save a Palette sandbox or production environment URL plus token in `~/.palette/config.json` with file mode `0600`. Environment variables still override the stored token when present.
+
+```bash
+pltt login --env staging --url https://sandbox.pltt.ai --token <publish-token>
+pltt dev --sandbox --env staging
+```
 
 ### `pltt doctor`
 
@@ -86,7 +108,15 @@ Check local tooling and common setup problems.
 pltt doctor
 ```
 
-Checks include Node version, Docker availability, platform image availability, port availability, manifest validity, entry files, and frontend bundling.
+Checks include Node version, port availability, manifest validity, entry files, and frontend bundling.
+
+Docker is intentionally skipped by default:
+
+```bash
+pltt doctor --platform
+```
+
+Use `--platform` only when validating the internal Docker parity harness.
 
 ### `pltt build`
 
@@ -135,7 +165,7 @@ pltt publish --env staging --ttl-hours 24
 
 Publishing first runs the same contract checks as `pltt test`. If preflight passes, it bundles frontend/backend artifacts, uploads them, creates a `pending_review` publish record, and prints review/preview URLs when the platform returns them.
 
-`--ttl-hours` sets an expiration on the preview URL. It is mainly used by `pltt dev --cloud`, which defaults previews to 24 hours.
+`--ttl-hours` sets an expiration on the preview URL. It is mainly used by `pltt dev --sandbox`, which defaults previews to 24 hours.
 
 Environment config is read from `./palette.config.json`, `~/.palette/config.json`, or `PALETTE_<ENV>_URL` plus `PALETTE_<ENV>_TOKEN` / `PALETTE_PUBLISH_TOKEN`.
 
@@ -176,7 +206,7 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 - `bin/pltt.js` — entry point
 - `backend-sdk/` — backend SDK files used by local contract tests and simulator
 - `lib/` — pure-Node command implementations (no runtime dependencies)
-- `platform-dev/docker-compose.yml` — compose file for `pltt dev --platform`
+- `platform-dev/docker-compose.yml` — compose file for internal `pltt dev --platform` parity checks
 - `template-fallback/` — offline fallback for `pltt init` if git is unavailable
 
 ## See also

package/lib/cli.js

@@ -6,6 +6,7 @@ const doctor = require("./commands/doctor")
 const build = require("./commands/build")
 const test = require("./commands/test")
 const publish = require("./commands/publish")
+const login = require("./commands/login")
 const pkg = require("./commands/package")
 const status = require("./commands/status")
 const logs = require("./commands/logs")
@@ -14,11 +15,16 @@ const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
   dev: {
     run: dev,
-    help: "Run the local SDK simulator; use --platform for Docker platform parity",
+    help: "Run the no-Docker SDK simulator; use --sandbox for hosted preview",
   },
+  sandbox: {
+    run: (args, ctx) => dev([...args, "--sandbox"], ctx),
+    help: "Publish a no-Docker hosted sandbox preview",
+  },
+  login: { run: login, help: "Save a Palette sandbox environment for publish/dev preview" },
   doctor: {
     run: doctor,
-    help: "Check local tooling, ports, manifest, Docker, and frontend bundling",
+    help: "Check local tooling, ports, manifest, and frontend bundling",
   },
   build: { run: build, help: "Validate palette-plugin.json and check entry points exist" },
   test: { run: test, help: "Run local plugin contract checks before publishing" },
@@ -50,8 +56,13 @@ function printHelp() {
   console.log("  --env <name>     Target environment from ~/.palette/config.json (default: local)")
   console.log("  -y, --yes        Skip interactive confirmation for production pushes")
   console.log("\nDev flags:")
-  console.log("  --platform       Run the full Docker platform-dev container")
-  console.log("  --cloud          Publish a reviewable preview to a configured cloud sandbox")
+  console.log("  --sandbox        Publish a reviewable preview to a configured Palette sandbox (no Docker)")
+  console.log("  --cloud          Alias for --sandbox")
+  console.log("  --platform       Internal only: run the Docker platform-dev parity container")
+  console.log("\nLogin flags:")
+  console.log("  --url <url>      Palette platform URL for pltt login")
+  console.log("  --token <token>  Publish token for pltt login")
+  console.log("  --no-default     Do not make this environment the default")
   console.log("\nInit flags:")
   console.log("  --template <name>  One of: dashboard, agent-tool, external-service, database, frontend-only")
   console.log("\nLogs flags:")
@@ -59,7 +70,10 @@ function printHelp() {
   console.log("  -f, --follow     Stream events (poll every 3s)")
   console.log("\nExamples:")
   console.log("  pltt init my-app --template database")
+  console.log("  pltt login --env staging --url https://sandbox.pltt.ai --token <token>")
   console.log("  cd my-app && pltt dev")
+  console.log("  pltt sandbox --env staging")
+  console.log("  pltt dev --sandbox --env staging")
   console.log("  pltt package")
   console.log("  pltt publish --env staging")
   console.log("  pltt status")

package/lib/commands/dev.js

@@ -76,7 +76,7 @@ function imagePullHelp(image, output) {
 
 async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
-  const cloud = rest.includes("--cloud")
+  const cloud = rest.includes("--cloud") || rest.includes("--sandbox")
   const platform = rest.includes("--platform")
   if (cloud) {
     const json = args.includes("--json")
@@ -92,7 +92,7 @@ async function run(args, { cwd }) {
     if (!flags.env && !process.env.PALETTE_ENV) publishArgs.push("--env", "staging")
     if (!json) {
       console.log(
-        "[pltt] cloud dev publishes a reviewable preview to the configured cloud sandbox.",
+        "[pltt] sandbox dev publishes a reviewable preview to the configured Palette sandbox.",
       )
     }
     const record = await publish(publishArgs, { cwd })
@@ -146,6 +146,7 @@ async function run(args, { cwd }) {
   }
 
   console.log(`[pltt] starting ${DEFAULT_IMAGE} via docker compose`)
+  console.log("[pltt] --platform is for internal parity testing; app developers should use `pltt dev` or `pltt dev --sandbox`.")
   console.log(`[pltt] mounting ${cwd} → /plugins/${pluginId}`)
   if (ports.frontend !== ports.preferredFrontend) {
     console.log(`[pltt] frontend port ${ports.preferredFrontend} is busy; using ${ports.frontend}`)

package/lib/commands/doctor.js

@@ -51,27 +51,39 @@ function checkEntry(cwd, label, rel) {
 
 async function run(args, { cwd }) {
   let failures = 0
+  const platform = args.includes("--platform")
 
   if (nodeMajor() >= 18) ok(`Node ${process.versions.node}`)
   else failures += fail("Node 18+ is required", "Install Node.js 18 or newer.")
 
-  if (dockerRunning()) ok("Docker is running")
-  else failures += fail(
-    "Docker is not running",
-    "Start Docker Desktop, then rerun pltt doctor.",
-  )
+  if (platform) {
+    if (dockerRunning()) ok("Docker is running")
+    else failures += fail(
+      "Docker is not running",
+      "Start Docker Desktop, then rerun pltt doctor --platform.",
+    )
 
-  if (imageExistsLocally(DEFAULT_IMAGE)) {
-    ok(`platform image is available locally: ${DEFAULT_IMAGE}`)
+    if (imageExistsLocally(DEFAULT_IMAGE)) {
+      ok(`platform image is available locally: ${DEFAULT_IMAGE}`)
+    } else {
+      warn(
+        `platform image is not present locally: ${DEFAULT_IMAGE}`,
+        "pltt dev --platform will try to pull it. If that fails, run docker login ghcr.io or set PALETTE_DEV_IMAGE.",
+      )
+    }
   } else {
     warn(
-      `platform image is not present locally: ${DEFAULT_IMAGE}`,
-      "pltt dev will try to pull it. If that fails, run docker login ghcr.io or set PALETTE_DEV_IMAGE.",
+      "Docker check skipped",
+      "Normal app development uses no Docker. Run `pltt doctor --platform` only for internal platform parity testing.",
     )
   }
 
   try {
-    const ports = await resolveDevPorts({ frontend: FRONTEND_PORT, backend: BACKEND_PORT })
+    const ports = await resolveDevPorts({
+      frontend: FRONTEND_PORT,
+      backend: BACKEND_PORT,
+      host: platform ? "0.0.0.0" : "127.0.0.1",
+    })
     if (ports.frontend === FRONTEND_PORT) ok(`frontend port ${FRONTEND_PORT} is available`)
     else warn(`frontend port ${FRONTEND_PORT} is already in use`, `pltt dev will use ${ports.frontend}`)
     if (ports.backend === BACKEND_PORT) ok(`backend port ${BACKEND_PORT} is available`)

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/commands/login.js

@@ -0,0 +1,51 @@
+"use strict"
+
+const { parseFlags, writeUserEnvironment } = require("../environments")
+
+function tokenEnvFor(name) {
+  if (name === "production") return "PALETTE_PROD_TOKEN"
+  return `PALETTE_${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_TOKEN`
+}
+
+async function run(argv) {
+  const { flags } = parseFlags(argv)
+  const name = flags.env || process.env.PALETTE_ENV || "staging"
+  const url = flags.url || process.env.PALETTE_PLATFORM_URL || process.env[`PALETTE_${name.toUpperCase()}_URL`]
+  const token = flags.token || process.env.PALETTE_PUBLISH_TOKEN || process.env[tokenEnvFor(name)]
+
+  if (!url) {
+    console.error(
+      `[pltt] missing platform URL for "${name}".\n` +
+        `          Usage: pltt login --env ${name} --url https://palette.example.com --token <publish-token>`,
+    )
+    process.exit(1)
+  }
+  if (!token) {
+    console.error(
+      `[pltt] missing publish token for "${name}".\n` +
+        `          Pass --token <token> or set $PALETTE_PUBLISH_TOKEN.`,
+    )
+    process.exit(1)
+  }
+
+  const tokenEnv = tokenEnvFor(name)
+  const configPath = writeUserEnvironment({
+    name,
+    url,
+    token,
+    tokenEnv,
+    defaultEnvironment: flags.default,
+  })
+
+  if (flags.json) {
+    console.log(JSON.stringify({ ok: true, env: name, url: url.replace(/\/+$/, ""), token_env: tokenEnv, config: configPath }, null, 2))
+    return
+  }
+
+  console.log(`[pltt] saved ${name} → ${url.replace(/\/+$/, "")}`)
+  console.log(`[pltt] config: ${configPath}`)
+  console.log(`[pltt] token stored in user config with file mode 0600`)
+  console.log(`[pltt] env override: ${tokenEnv}`)
+}
+
+module.exports = run

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/lib/environments.js

@@ -65,6 +65,40 @@ function loadConfig(cwd) {
   return DEFAULTS
 }
 
+function mergeConfig(cfg) {
+  return {
+    ...DEFAULTS,
+    ...cfg,
+    environments: {
+      ...DEFAULTS.environments,
+      ...(cfg.environments || {}),
+    },
+  }
+}
+
+function userConfigPath() {
+  return path.join(os.homedir(), ".palette", "config.json")
+}
+
+function writeUserEnvironment({ name, url, token, tokenEnv, defaultEnvironment = true }) {
+  const target = userConfigPath()
+  const existing = readJsonIfExists(target) || {}
+  const cfg = mergeConfig(existing)
+  cfg.environments[name] = {
+    ...(cfg.environments[name] || {}),
+    url: url.replace(/\/+$/, ""),
+    token,
+    token_env: tokenEnv,
+    production: Boolean(cfg.environments[name]?.production),
+  }
+  if (defaultEnvironment) cfg.default_environment = name
+
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 })
+  fs.writeFileSync(target, `${JSON.stringify(cfg, null, 2)}\n`, { mode: 0o600 })
+  fs.chmodSync(target, 0o600)
+  return target
+}
+
 /**
  * Resolve the effective environment.
  *
@@ -106,7 +140,7 @@ function resolveEnvironment({ cwd, flags }) {
 
   const token = useLegacy
     ? process.env.PALETTE_PUBLISH_TOKEN || ""
-    : process.env[envCfg.token_env] || process.env.PALETTE_PUBLISH_TOKEN || ""
+    : process.env[envCfg.token_env] || process.env.PALETTE_PUBLISH_TOKEN || envCfg.token || ""
 
   if (!url) {
     throw new Error(
@@ -130,7 +164,16 @@ function resolveEnvironment({ cwd, flags }) {
  * Leaves positional args in `rest`.
  */
 function parseFlags(argv) {
-  const flags = { env: undefined, yes: false, ttlHours: undefined, wait: false }
+  const flags = {
+    env: undefined,
+    yes: false,
+    ttlHours: undefined,
+    wait: false,
+    json: false,
+    url: undefined,
+    token: undefined,
+    default: true,
+  }
   const rest = []
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
@@ -146,6 +189,18 @@ function parseFlags(argv) {
       flags.ttlHours = Number.parseInt(a.slice("--ttl-hours=".length), 10)
     } else if (a === "--wait") {
       flags.wait = true
+    } else if (a === "--json") {
+      flags.json = true
+    } else if (a === "--url") {
+      flags.url = argv[++i]
+    } else if (a.startsWith("--url=")) {
+      flags.url = a.slice("--url=".length)
+    } else if (a === "--token") {
+      flags.token = argv[++i]
+    } else if (a.startsWith("--token=")) {
+      flags.token = a.slice("--token=".length)
+    } else if (a === "--no-default") {
+      flags.default = false
     } else {
       rest.push(a)
     }
@@ -168,4 +223,10 @@ async function confirmProduction(env) {
   })
 }
 
-module.exports = { resolveEnvironment, parseFlags, confirmProduction, loadConfig }
+module.exports = {
+  resolveEnvironment,
+  parseFlags,
+  confirmProduction,
+  loadConfig,
+  writeUserEnvironment,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "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.
 ]