@palettelab/cli 0.3.46 → 0.3.48

package/README.md

@@ -678,9 +678,10 @@ Run local contract checks before publishing.
 ```bash
 pltt test
 pltt test --json
+pltt test --publish-type preview
 ```
 
-Checks include manifest validity, SDK/platform compatibility, semver bump detection, forbidden platform imports, frontend bundling and size limits, sandbox bridge smoke, backend dependency installation/import, route permission gates, route permission declarations, migration linting, frontend sandbox policy, and dependency policy for `package.json` / `pyproject.toml`. The default frontend and backend bundle limits are 15 MiB; set `PALETTE_MAX_FRONTEND_BUNDLE_BYTES` or `PALETTE_MAX_BACKEND_BUNDLE_BYTES` for reviewed exceptions.
+Checks include manifest validity, SDK/platform compatibility, release semver bump detection, forbidden platform imports, frontend bundling and size limits, sandbox bridge smoke, backend dependency installation/import, route permission gates, route permission declarations, migration linting, frontend sandbox policy, and dependency policy for `package.json` / `pyproject.toml`. The semver bump check is skipped for `--publish-type preview` because hosted previews may reuse the current app version. The default frontend and backend bundle limits are 15 MiB; set `PALETTE_MAX_FRONTEND_BUNDLE_BYTES` or `PALETTE_MAX_BACKEND_BUNDLE_BYTES` for reviewed exceptions.
 
 ### `pltt package`
 
@@ -706,7 +707,7 @@ pltt publish --env staging --json
 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.
+Publishing first runs the same contract checks as `pltt test`. Preview publishes skip the release semver bump check, while release publishes still require a version newer than the last release. If preflight passes, it bundles frontend/backend artifacts, uploads them, creates a review 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 --sandbox`, which defaults previews to 24 hours.
 

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.`,
     }
   }
 
@@ -131,9 +138,9 @@ function printPreflightFailure(payload, fallbackOutput) {
   console.error("[pltt] Need machine-readable details? Run `pltt test --json`.")
 }
 
-function runPreflight(cwd, json) {
+function runPreflight(cwd, json, publishType = "release") {
   const cliBin = path.resolve(__dirname, "..", "..", "bin", "pltt.js")
-  const res = spawnSync(process.execPath, [cliBin, "test", "--json"], {
+  const res = spawnSync(process.execPath, [cliBin, "test", "--json", "--publish-type", publishType], {
     cwd,
     encoding: "utf8",
     env: process.env,
@@ -289,7 +296,7 @@ async function run(argv, { cwd }) {
     process.exit(1)
   }
 
-  runPreflight(cwd, flags.json)
+  runPreflight(cwd, flags.json, publishType)
 
   log(
     `[pltt] publishing ${manifest.id}@${manifest.version} → ${env.name} (${env.url})`,
@@ -361,28 +368,28 @@ async function run(argv, { cwd }) {
     method: "POST",
     body: publishBody,
   })
+  const lastPublish = {
+    id: record.id,
+    plugin_id: record.plugin_id,
+    version: record.version,
+    env: env.name,
+    url: env.url,
+    publish_type: record.publish_type || publishType,
+    preview_url: record.preview_url,
+    preview_expires_at: record.preview_expires_at,
+    published_at: new Date().toISOString(),
+  }
 
   try {
     const dir = path.join(cwd, ".palette")
     fs.mkdirSync(dir, { recursive: true })
     fs.writeFileSync(
       path.join(dir, "last-publish.json"),
-      JSON.stringify(
-        {
-          id: record.id,
-          plugin_id: record.plugin_id,
-          version: record.version,
-          env: env.name,
-          url: env.url,
-          publish_type: record.publish_type || publishType,
-          preview_url: record.preview_url,
-          preview_expires_at: record.preview_expires_at,
-          published_at: new Date().toISOString(),
-        },
-        null,
-        2,
-      ),
+      JSON.stringify(lastPublish, null, 2),
     )
+    if ((record.publish_type || publishType) === "release") {
+      fs.writeFileSync(path.join(dir, "last-release.json"), JSON.stringify(lastPublish, null, 2))
+    }
   } catch (err) {
     // best-effort
   }

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
 }
@@ -537,17 +554,51 @@ function scanForbiddenImports(cwd, manifest, out) {
   return issues.length
 }
 
-function checkSemverBump(cwd, manifest, out) {
-  const statePath = path.join(cwd, ".palette", "last-publish.json")
+function parsePublishType(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === "--preview") return "preview"
+    if (arg === "--release") return "release"
+    if (arg === "--publish-type") return argv[i + 1] === "preview" ? "preview" : "release"
+    if (arg.startsWith("--publish-type=")) {
+      return arg.slice("--publish-type=".length) === "preview" ? "preview" : "release"
+    }
+  }
+  return "release"
+}
+
+function readPublishState(statePath) {
   if (!fs.existsSync(statePath)) {
-    out.ok("semver bump check skipped; no previous publish state")
-    return 0
+    return { state: null, invalid: false }
   }
-  let previous
   try {
-    previous = JSON.parse(fs.readFileSync(statePath, "utf8"))
+    return { state: JSON.parse(fs.readFileSync(statePath, "utf8")), invalid: false }
   } catch (_err) {
-    out.warn("semver bump check skipped; .palette/last-publish.json is invalid JSON")
+    return { state: null, invalid: true }
+  }
+}
+
+function checkSemverBump(cwd, manifest, out, publishType = "release") {
+  if (publishType === "preview") {
+    out.ok("semver bump check skipped for preview publish")
+    return 0
+  }
+
+  const releaseStatePath = path.join(cwd, ".palette", "last-release.json")
+  const publishStatePath = path.join(cwd, ".palette", "last-publish.json")
+  let { state: previous, invalid } = readPublishState(releaseStatePath)
+  if (!previous && !invalid) {
+    const lastPublish = readPublishState(publishStatePath)
+    invalid = lastPublish.invalid
+    if (lastPublish.state?.publish_type !== "preview") previous = lastPublish.state
+  }
+
+  if (!previous && !invalid) {
+    out.ok("semver bump check skipped; no previous release state")
+    return 0
+  }
+  if (invalid) {
+    out.warn("semver bump check skipped; previous publish state is invalid JSON")
     return 0
   }
   const previousVersion = previous.version || previous.manifest?.version
@@ -557,7 +608,7 @@ function checkSemverBump(cwd, manifest, out) {
   }
   if (compareVersions(manifest.version, previousVersion) <= 0) {
     return out.fail(
-      `plugin version ${manifest.version} is not newer than last publish ${previousVersion}`,
+      `plugin version ${manifest.version} is not newer than last release ${previousVersion}`,
       "Bump manifest.version before publishing another build.",
       { current: manifest.version, previous: previousVersion },
     )
@@ -666,6 +717,7 @@ function checkFrontendSecretLeaks(cwd, frontendBuffer, manifest, out) {
 
 async function run(args, { cwd }) {
   const json = args.includes("--json")
+  const publishType = parsePublishType(args)
   let failures = 0
   const results = []
   const out = reporter(json, results)
@@ -692,7 +744,7 @@ async function run(args, { cwd }) {
 
   failures += checkSdkCompatibility(cwd, manifest, out)
   failures += scanForbiddenImports(cwd, manifest, out)
-  failures += checkSemverBump(cwd, manifest, out)
+  failures += checkSemverBump(cwd, manifest, out, publishType)
   failures += checkDeclaredSecrets(cwd, manifest, out)
 
   for (const permission of manifest.permissions || []) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.46",
+  "version": "0.3.48",
   "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": {