@palettelab/cli 0.3.45 → 0.3.47

package/README.md

@@ -328,6 +328,8 @@ async def sync_invoices(ctx: PluginContext = Depends(get_plugin_context)):
     return {"room": room, "folder": folder, "bytes": len(content or b"")}
 ```
 
+Storage upload responses include both snake_case and camelCase aliases for object metadata (`object_path`/`objectPath`, `file_url`/`fileUrl`, `content_type`/`contentType`) so local simulator and hosted OS responses can be consumed with the same app code.
+
 App storage is different from Data Room uploads. Use `ctx.storage` or `palette.storage` for app-owned files written directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` / `palette.dataRooms` only when the file should be managed as a Data Room document.
 
 Python backend app-storage example:

package/backend-sdk/palette_sdk/storage.py

@@ -83,6 +83,47 @@ def _content_type(filename: str | None, content_type: str | None) -> str:
     return browser_ct
 
 
+def _storage_metadata(
+    *,
+    bucket: str,
+    object_path: str,
+    file_url: str,
+    content_type: str,
+    size: int | None,
+) -> dict[str, Any]:
+    return {
+        "bucket": bucket,
+        "object_path": object_path,
+        "objectPath": object_path,
+        "file_url": file_url,
+        "fileUrl": file_url,
+        "content_type": content_type,
+        "contentType": content_type,
+        "size": size,
+    }
+
+
+def _resumable_metadata(
+    *,
+    bucket: str,
+    object_path: str,
+    file_url: str,
+    upload_url: str | None,
+    content_type: str,
+    size: int | None,
+) -> dict[str, Any]:
+    payload = _storage_metadata(
+        bucket=bucket,
+        object_path=object_path,
+        file_url=file_url,
+        content_type=content_type,
+        size=size,
+    )
+    payload["upload_url"] = upload_url
+    payload["uploadUrl"] = upload_url
+    return payload
+
+
 @dataclass
 class LocalStorageService:
     """Filesystem-backed ctx.storage implementation used by local SDK dev."""
@@ -122,13 +163,13 @@ class LocalStorageService:
         target = self._target(object_path)
         target.parent.mkdir(parents=True, exist_ok=True)
         target.write_bytes(content)
-        return {
-            "bucket": "local",
-            "object_path": object_path,
-            "file_url": target.as_uri(),
-            "content_type": _content_type(filename, content_type),
-            "size": len(content),
-        }
+        return _storage_metadata(
+            bucket="local",
+            object_path=object_path,
+            file_url=target.as_uri(),
+            content_type=_content_type(filename, content_type),
+            size=len(content),
+        )
 
     async def upload_file_stream(
         self,
@@ -168,13 +209,13 @@ class LocalStorageService:
                 chunk_count=chunk_count,
                 state="complete",
             )
-            return {
-                "bucket": "local",
-                "object_path": object_path,
-                "file_url": target.as_uri(),
-                "content_type": _content_type(filename, content_type),
-                "size": 0,
-            }
+            return _storage_metadata(
+                bucket="local",
+                object_path=object_path,
+                file_url=target.as_uri(),
+                content_type=_content_type(filename, content_type),
+                size=0,
+            )
         with target.open("wb") as out:
             chunk_index = 0
             while True:
@@ -194,13 +235,13 @@ class LocalStorageService:
                 )
         if loaded != total:
             raise RuntimeError(f"storage upload incomplete: uploaded {loaded} of {total} bytes")
-        return {
-            "bucket": "local",
-            "object_path": object_path,
-            "file_url": target.as_uri(),
-            "content_type": _content_type(filename, content_type),
-            "size": loaded,
-        }
+        return _storage_metadata(
+            bucket="local",
+            object_path=object_path,
+            file_url=target.as_uri(),
+            content_type=_content_type(filename, content_type),
+            size=loaded,
+        )
 
     async def upload_file_path(
         self,
@@ -234,11 +275,11 @@ class LocalStorageService:
         key: str | None = None,
     ) -> dict[str, Any]:
         object_path = self.object_path(filename, key=key)
-        return {
-            "bucket": "local",
-            "object_path": object_path,
-            "file_url": self._target(object_path).as_uri(),
-            "upload_url": None,
-            "content_type": _content_type(filename, content_type),
-            "size": size,
-        }
+        return _resumable_metadata(
+            bucket="local",
+            object_path=object_path,
+            file_url=self._target(object_path).as_uri(),
+            upload_url=None,
+            content_type=_content_type(filename, content_type),
+            size=size,
+        )

package/docs/python-backend-sdk.md

@@ -1044,3 +1044,5 @@ async def create_note(
 
 This route stores app-owned data in the app database and writes a related file
 into Palette Data Rooms from the Python backend.
+
+Backend storage responses include both snake_case and camelCase aliases for object metadata (`object_path`/`objectPath`, `file_url`/`fileUrl`, `content_type`/`contentType`). The concrete values differ by environment, but the key contract is stable across local dev and hosted OS.

package/lib/commands/build.js

@@ -31,6 +31,22 @@ function pluginTablePrefix(pluginId) {
   return `${pluginSafeId(pluginId)}__`
 }
 
+function makeIssue(message, fix = null, meta = {}) {
+  return { message, fix, ...meta }
+}
+
+function formatIssue(issue) {
+  if (typeof issue === "string") return issue
+  const lines = [issue.message || String(issue)]
+  if (issue.details) lines.push(`Why: ${issue.details}`)
+  if (issue.fix) lines.push(`Fix: ${issue.fix}`)
+  if (issue.example) {
+    lines.push("Example:")
+    for (const line of String(issue.example).split("\n")) lines.push(`  ${line}`)
+  }
+  return lines.join("\n    ")
+}
+
 function crossPluginSchemaRefs(src, allowedSchema) {
   if (!allowedSchema) return []
   const refs = new Set()
@@ -43,28 +59,27 @@ function crossPluginSchemaRefs(src, allowedSchema) {
   return [...refs].sort()
 }
 
-function lintMigrationFile(absPath, pluginId) {
+function lintMigrationFile(absPath, pluginId, sharedTables = []) {
   const issues = []
   const src = fs.readFileSync(absPath, "utf8")
   const requiredPrefix = pluginId ? pluginTablePrefix(pluginId) : null
   const allowedSchema = pluginId ? pluginSchema(pluginId) : null
+  const sharedTableNames = new Set(sharedTables || [])
 
   for (const { re, reason } of BANNED_PATTERNS) {
     if (re.test(src)) {
-      issues.push(`${path.basename(absPath)}: ${reason}`)
+      issues.push(makeIssue(`${path.basename(absPath)}: ${reason}`))
     }
   }
 
   for (const schema of crossPluginSchemaRefs(src, allowedSchema)) {
-    issues.push(`${path.basename(absPath)}: plugin migrations must not reference another app schema (${schema})`)
+    issues.push(makeIssue(`${path.basename(absPath)}: plugin migrations must not reference another app schema (${schema})`))
   }
 
   // Every op.create_table("foo", ...) in the file must have a matching
-  // ensure_org_rls(op, "foo") somewhere in the same file. Caveat: this is a
-  // cheap syntactic check, not a full AST walk. If your table name is dynamic
-  // or your migration is unusual, you can silence the check by adding the
-  // magic comment `# palette:rls-ok` on the same logical migration.
-  const skipRlsCheck = /#\s*palette:rls-ok\b/.test(src)
+  // ensure_org_rls(op, "foo") somewhere in the same file unless the table is
+  // declared in manifest.shared_tables. Caveat: this is a cheap syntactic
+  // check, not a full AST walk.
 
   const tableNames = new Set()
   const createTableRe = /op\.create_table\(\s*['"]([a-zA-Z_][a-zA-Z0-9_]*)['"]/g
@@ -75,23 +90,48 @@ function lintMigrationFile(absPath, pluginId) {
 
   for (const name of tableNames) {
     if (requiredPrefix && !name.startsWith(requiredPrefix)) {
-      issues.push(
+      issues.push(makeIssue(
         `${path.basename(absPath)}: create_table("${name}") must use the app table prefix "${requiredPrefix}"`,
-      )
+        `Rename the table to "${requiredPrefix}${name}" or another name that starts with "${requiredPrefix}", then update model and query references.`,
+        {
+          code: "database_table_prefix",
+          file: path.basename(absPath),
+          table: name,
+          required_prefix: requiredPrefix,
+        },
+      ))
     }
     const rlsRe = new RegExp(`ensure_org_rls\\(\\s*op\\s*,\\s*['"]${name}['"]`)
-    if (!skipRlsCheck && !rlsRe.test(src)) {
-      issues.push(
+    if (!sharedTableNames.has(name) && !rlsRe.test(src)) {
+      const schemaHint = pluginId ? `${pluginSchema(pluginId)}.${name}` : name
+      issues.push(makeIssue(
         `${path.basename(absPath)}: create_table("${name}") is missing ensure_org_rls(op, "${name}"). ` +
-          `Inherit from OrgScopedTable and call ensure_org_rls, or mark the migration with # palette:rls-ok if the table is intentionally global.`,
-      )
+          `Preview/install will fail RLS compliance for ${schemaHint}: missing ENABLE + FORCE row level security.`,
+        `Import ensure_org_rls from palette_sdk.db and call ensure_org_rls(op, "${name}") immediately after op.create_table("${name}", ...). ` +
+          `Keep an organization_id column on tenant data tables. If this table is intentionally shared across every organization, add "${name}" to manifest.shared_tables instead and document why it is global.`,
+        {
+          code: "database_missing_org_rls",
+          file: path.basename(absPath),
+          table: name,
+          schema: pluginId ? pluginSchema(pluginId) : null,
+          details:
+            "Palette verifies every plugin table after migrations run. Tables that hold tenant data must have organization_id, at least one RLS policy, and ENABLE + FORCE row level security.",
+          example: [
+            "from palette_sdk.db import ensure_org_rls",
+            "",
+            "def upgrade():",
+            `    op.create_table("${name}", ...)`,
+            `    ensure_org_rls(op, "${name}")`,
+          ].join("\n"),
+        },
+      ))
     }
   }
 
   return issues
 }
 
-function lintMigrationsDir(migrationsDir, pluginId) {
+function lintMigrationsDir(migrationsDir, pluginId, sharedTables = []) {
   const errors = []
   const versionsDir = path.join(migrationsDir, "versions")
   if (!fs.existsSync(versionsDir)) {
@@ -101,7 +141,7 @@ function lintMigrationsDir(migrationsDir, pluginId) {
   for (const entry of fs.readdirSync(versionsDir)) {
     if (!entry.endsWith(".py")) continue
     const abs = path.join(versionsDir, entry)
-    errors.push(...lintMigrationFile(abs, pluginId))
+    errors.push(...lintMigrationFile(abs, pluginId, sharedTables))
   }
   return errors
 }
@@ -127,13 +167,13 @@ async function run(args, { cwd }) {
     } else if (!fs.existsSync(path.join(migrationsAbs, "env.py"))) {
       errors.push(`database.migrations directory is missing env.py: ${migrationsRel}`)
     } else {
-      errors.push(...lintMigrationsDir(migrationsAbs, manifest.id))
+      errors.push(...lintMigrationsDir(migrationsAbs, manifest.id, manifest.shared_tables || []))
     }
   }
 
   if (errors.length) {
     console.error("[pltt] validation failed:")
-    for (const e of errors) console.error(`  - ${e}`)
+    for (const e of errors) console.error(`  - ${formatIssue(e)}`)
     process.exit(1)
   }
   console.log(`[pltt] ok — ${manifest.id} v${manifest.version}`)
@@ -142,4 +182,5 @@ async function run(args, { cwd }) {
 module.exports = run
 module.exports.lintMigrationsDir = lintMigrationsDir
 module.exports.lintMigrationFile = lintMigrationFile
+module.exports.formatIssue = formatIssue
 module.exports.pluginTablePrefix = pluginTablePrefix

package/lib/commands/dev.js

@@ -1,5 +1,6 @@
 "use strict"
 
+const fs = require("fs")
 const path = require("path")
 const { spawn, spawnSync } = require("child_process")
 const { loadManifest } = require("../manifest")
@@ -8,6 +9,7 @@ const { parseFlags, resolveEnvironment } = require("../environments")
 const { resolveDevPorts } = require("../ports")
 const { startSimulator } = require("../dev-simulator")
 const { loadLocalEnv } = require("../secrets")
+const buildCommand = require("./build")
 const publish = require("./publish")
 const logs = require("./logs")
 
@@ -76,6 +78,26 @@ function imagePullHelp(image, output) {
   )
 }
 
+function lintMigrationsForDev(cwd, manifest) {
+  if (!manifest.database) return
+  const migrationsRel = manifest.database.migrations || "./backend/migrations"
+  const migrationsAbs = path.resolve(cwd, migrationsRel)
+  const errors = []
+  if (!fs.existsSync(migrationsAbs)) {
+    errors.push(`database.migrations directory not found: ${migrationsRel}`)
+  } else if (!fs.existsSync(path.join(migrationsAbs, "env.py"))) {
+    errors.push(`database.migrations directory is missing env.py: ${migrationsRel}`)
+  } else {
+    errors.push(...buildCommand.lintMigrationsDir(migrationsAbs, manifest.id, manifest.shared_tables || []))
+  }
+  if (!errors.length) return
+
+  console.error("[pltt] dev blocked by database migration validation:")
+  for (const err of errors) console.error(`  - ${buildCommand.formatIssue(err)}`)
+  console.error("[pltt] Fix these issues or run `pltt test --json` for machine-readable details.")
+  process.exit(1)
+}
+
 async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
   const cloud = rest.includes("--cloud") || rest.includes("--sandbox")
@@ -124,6 +146,7 @@ async function run(args, { cwd }) {
   }
 
   const manifest = loadManifest(cwd)
+  lintMigrationsForDev(cwd, manifest)
   const pluginId = manifest.id
   const ports = await resolveDevPorts({ host: platform ? "0.0.0.0" : "127.0.0.1" })
 

package/lib/commands/package.js

@@ -5,6 +5,7 @@ const path = require("path")
 const crypto = require("crypto")
 const { loadManifest, validateManifest } = require("../manifest")
 const { bundleFrontend, bundleBackend } = require("../bundler")
+const buildCommand = require("./build")
 
 function sha256(buf) {
   return crypto.createHash("sha256").update(buf).digest("hex")
@@ -20,6 +21,24 @@ async function run(argv, { cwd }) {
     process.exit(1)
   }
 
+  if (manifest.database) {
+    const migrationsRel = manifest.database.migrations || "./backend/migrations"
+    const migrationsAbs = path.resolve(cwd, migrationsRel)
+    const migrationErrors = []
+    if (!fs.existsSync(migrationsAbs)) {
+      migrationErrors.push(`database.migrations directory not found: ${migrationsRel}`)
+    } else if (!fs.existsSync(path.join(migrationsAbs, "env.py"))) {
+      migrationErrors.push(`database.migrations directory is missing env.py: ${migrationsRel}`)
+    } else {
+      migrationErrors.push(...buildCommand.lintMigrationsDir(migrationsAbs, manifest.id, manifest.shared_tables || []))
+    }
+    if (migrationErrors.length) {
+      console.error("[pltt] package blocked by database migration validation:")
+      for (const e of migrationErrors) console.error(`  - ${buildCommand.formatIssue(e)}`)
+      process.exit(1)
+    }
+  }
+
   const distDir = path.join(cwd, "dist")
   fs.mkdirSync(distDir, { recursive: true })
 

package/lib/commands/publish.js

@@ -80,14 +80,21 @@ function explainPreflightFailure(result) {
     }
   }
 
-  const migration = extractMigrationHint(message)
+  const migration =
+    result?.code === "database_missing_org_rls" && result?.table
+      ? { file: result.file || "migration", table: result.table }
+      : extractMigrationHint(message)
   if (migration) {
     return {
       title: "Database migration is missing organization RLS",
-      details: [`File: ${migration.file}`, `Table: ${migration.table}`],
+      details: [
+        `File: ${migration.file}`,
+        `Table: ${migration.table}`,
+        "Preview/install will reject this table unless RLS is enabled and forced.",
+      ],
       fix:
         fix ||
-        `Call ensure_org_rls(op, "${migration.table}") after create_table, or add # palette:rls-ok only if the table is intentionally global.`,
+        `Call ensure_org_rls(op, "${migration.table}") after create_table, or add "${migration.table}" to manifest.shared_tables only if the table is intentionally global.`,
     }
   }
 

package/lib/commands/test.js

@@ -12,6 +12,14 @@ const DEFAULT_FRONTEND_BUNDLE_LIMIT = 15 * 1024 * 1024
 const DEFAULT_BACKEND_BUNDLE_LIMIT = 15 * 1024 * 1024
 
 function reporter(json, results) {
+  function printExtra(meta) {
+    if (meta.details) console.log(`WHY  ${meta.details}`)
+    if (meta.example) {
+      console.log("EXAMPLE")
+      for (const line of String(meta.example).split("\n")) console.log(`  ${line}`)
+    }
+  }
+
   return {
     ok(message, meta = {}) {
       results.push({ status: "ok", message, ...meta })
@@ -22,6 +30,7 @@ function reporter(json, results) {
       if (!json) {
         console.log(`WARN ${message}`)
         if (fix) console.log(`FIX  ${fix}`)
+        printExtra(meta)
       }
       return 0
     },
@@ -30,6 +39,7 @@ function reporter(json, results) {
       if (!json) {
         console.log(`FAIL ${message}`)
         if (fix) console.log(`FIX  ${fix}`)
+        printExtra(meta)
       }
       return 1
     },
@@ -253,8 +263,15 @@ function lintMigrations(cwd, manifest, out) {
   if (!fs.existsSync(path.join(migrationsAbs, "env.py"))) {
     return out.fail(`database.migrations directory is missing env.py: ${migrationsRel}`)
   }
-  const errors = buildCommand.lintMigrationsDir(migrationsAbs, manifest.id)
-  for (const err of errors) out.fail(err)
+  const errors = buildCommand.lintMigrationsDir(migrationsAbs, manifest.id, manifest.shared_tables || [])
+  for (const err of errors) {
+    if (typeof err === "string") {
+      out.fail(err)
+    } else {
+      const { message, fix, ...meta } = err
+      out.fail(message, fix, meta)
+    }
+  }
   if (errors.length === 0) out.ok("migration lint passed")
   return errors.length
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.45",
+  "version": "0.3.47",
   "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.17"
+    "@palettelab/sdk": "^0.1.20"
   },
   "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.17",
+    "@palettelab/sdk": "^0.1.20",
     "react": "^19.0.0"
   }
 }

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.17", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.20", "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.17", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.20", "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.17",
+    "@palettelab/sdk": "^0.1.20",
     "react": "^19.0.0"
   }
 }

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

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

package/template-fallback/templates/palette-app/package.json

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