@palettelab/cli 0.3.8 → 0.3.10

package/README.md

@@ -61,7 +61,7 @@ Your plugin directory is mounted into the container at `/plugins/<your-id>`. Edi
 
 `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 --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.
+`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.
 
 Environment variables:
 
@@ -100,7 +100,7 @@ pltt test
 pltt test --json
 ```
 
-Checks include manifest validity, frontend bundling, backend import, route permission gates, route permission declarations, migration linting, frontend sandbox policy, and dependency policy for `package.json` / `pyproject.toml`.
+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`.
 
 ### `pltt package`
 
@@ -171,5 +171,5 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 ## See also
 
 - `@palettelab/sdk` on npm — frontend hooks and types
-- `palette-sdk` (git-installed from [palette-lab/virtual-organisation](https://github.com/palette-lab/virtual-organisation/tree/main/sdk/backend)) — backend `PluginRouter` + `ToolDefinition`
-- [Developer Guide](https://github.com/palette-lab/virtual-organisation/blob/main/sdk/DEVELOPER_GUIDE.md)
+- `palette-sdk` GitHub Release wheel on `sdk-backend-v*` — backend `PluginRouter` + `ToolDefinition`
+- `sdk/scripts/verify-release-registries.sh` — npmjs, GHCR, and backend SDK release verification

package/lib/commands/dev.js

@@ -77,16 +77,30 @@ async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
   const cloud = rest.includes("--cloud")
   if (cloud) {
+    const json = args.includes("--json")
     const publishArgs = []
     if (flags.env) publishArgs.push("--env", flags.env)
     if (flags.yes) publishArgs.push("--yes")
     if (args.includes("--json")) publishArgs.push("--json")
+    if (Number.isFinite(flags.ttlHours) && flags.ttlHours > 0) {
+      publishArgs.push("--ttl-hours", String(flags.ttlHours))
+    } else {
+      publishArgs.push("--ttl-hours", "24")
+    }
     if (!flags.env && !process.env.PALETTE_ENV) publishArgs.push("--env", "staging")
-    console.log(
-      "[pltt] cloud dev publishes a reviewable preview to the configured cloud sandbox.",
-    )
-    console.log("[pltt] use `pltt status <publish-id>` after upload to track review state.")
-    await publish(publishArgs, { cwd })
+    if (!json) {
+      console.log(
+        "[pltt] cloud dev publishes a reviewable preview to the configured cloud sandbox.",
+      )
+    }
+    const record = await publish(publishArgs, { cwd })
+    if (!json && record?.preview_url) {
+      console.log(`[pltt] preview URL: ${record.preview_url}`)
+    }
+    if (!json && record?.id) {
+      console.log(`[pltt] status: pltt status ${record.id} --env ${flags.env || process.env.PALETTE_ENV || "staging"}`)
+      console.log("[pltt] logs:   pltt logs --follow")
+    }
     return
   }
 

package/lib/commands/publish.js

@@ -79,6 +79,9 @@ async function put(url, buf, contentType) {
 
 async function run(argv, { cwd }) {
   const { flags } = parseFlags(argv)
+  const log = (...args) => {
+    if (!flags.json) console.log(...args)
+  }
 
   let env
   try {
@@ -115,27 +118,27 @@ async function run(argv, { cwd }) {
 
   runPreflight(cwd, flags.json)
 
-  console.log(
+  log(
     `[pltt] publishing ${manifest.id}@${manifest.version} → ${env.name} (${env.url})`,
   )
 
   let frontend = null
   if (manifest.frontend?.entry) {
-    console.log("[pltt]   bundling frontend")
+    log("[pltt]   bundling frontend")
     frontend = await bundleFrontend(cwd, manifest.frontend.entry)
-    console.log(`[pltt]     ${frontend.length} bytes`)
+    log(`[pltt]     ${frontend.length} bytes`)
   } else {
-    console.log("[pltt]   no frontend declared")
+    log("[pltt]   no frontend declared")
   }
 
-  console.log("[pltt]   bundling backend")
+  log("[pltt]   bundling backend")
   const backend = await bundleBackend(cwd)
-  console.log(`[pltt]     ${backend.length} bytes`)
+  log(`[pltt]     ${backend.length} bytes`)
 
   const backendSha = sha256(backend)
   const api = makeApi(env)
 
-  console.log("[pltt]   requesting signed URLs")
+  log("[pltt]   requesting signed URLs")
   const signed = await api("/api/v1/appstore/sign-upload", {
     method: "POST",
     body: {
@@ -145,7 +148,7 @@ async function run(argv, { cwd }) {
     },
   })
 
-  console.log("[pltt]   uploading")
+  log("[pltt]   uploading")
   const uploads = [
     put(signed.backend_upload_url, backend, "application/gzip"),
     put(
@@ -159,16 +162,20 @@ async function run(argv, { cwd }) {
   }
   await Promise.all(uploads)
 
-  console.log("[pltt]   finalizing")
+  log("[pltt]   finalizing")
+  const publishBody = {
+    plugin_id: manifest.id,
+    version: manifest.version,
+    bundle_path: signed.bundle_path,
+    bundle_sha256: backendSha,
+    manifest,
+  }
+  if (Number.isFinite(flags.ttlHours) && flags.ttlHours > 0) {
+    publishBody.preview_ttl_hours = flags.ttlHours
+  }
   const record = await api("/api/v1/appstore/publish", {
     method: "POST",
-    body: {
-      plugin_id: manifest.id,
-      version: manifest.version,
-      bundle_path: signed.bundle_path,
-      bundle_sha256: backendSha,
-      manifest,
-    },
+    body: publishBody,
   })
 
   try {
@@ -196,7 +203,7 @@ async function run(argv, { cwd }) {
 
   if (flags.json) {
     console.log(JSON.stringify(record, null, 2))
-    return
+    return record
   }
 
   console.log(
@@ -210,6 +217,7 @@ async function run(argv, { cwd }) {
     console.log(`[pltt] preview: ${record.preview_url}`)
   }
   console.log(`[pltt] once approved, live at ${env.url}${record.catalog_url}`)
+  return record
 }
 
 module.exports = run

package/lib/commands/test.js

@@ -7,6 +7,9 @@ const { loadManifest, validateManifest, KNOWN_PERMISSIONS } = require("../manife
 const { bundleFrontend, bundleBackend } = require("../bundler")
 const buildCommand = require("./build")
 
+const DEFAULT_FRONTEND_BUNDLE_LIMIT = 512 * 1024
+const DEFAULT_BACKEND_BUNDLE_LIMIT = 5 * 1024 * 1024
+
 function reporter(json, results) {
   return {
     ok(message, meta = {}) {
@@ -41,11 +44,94 @@ function backendPython(cwd) {
   )
 }
 
-function checkBackendContract(cwd, manifest, out) {
+function localBackendSdkPath() {
+  const candidate = path.resolve(__dirname, "..", "..", "..", "backend")
+  return fs.existsSync(path.join(candidate, "palette_sdk")) ? candidate : null
+}
+
+function pythonEnv(extra = {}) {
+  const paths = []
+  if (extra.PYTHONPATH) paths.push(extra.PYTHONPATH)
+  if (process.env.PYTHONPATH) paths.push(process.env.PYTHONPATH)
+  const localSdk = localBackendSdkPath()
+  if (localSdk) paths.unshift(localSdk)
+  return {
+    ...process.env,
+    ...extra,
+    PYTHONPATH: paths.filter(Boolean).join(path.delimiter),
+  }
+}
+
+function pyprojectDependencies(cwd) {
+  const pyprojectPath = path.join(cwd, "pyproject.toml")
+  if (!fs.existsSync(pyprojectPath)) return []
+  return extractPyprojectDependencies(fs.readFileSync(pyprojectPath, "utf8"))
+}
+
+function installPythonDependencies(cwd, out) {
+  const deps = pyprojectDependencies(cwd)
+  if (deps.length === 0) {
+    out.ok("no pyproject dependencies declared")
+    return { python: backendPython(cwd), env: pythonEnv(), failures: 0, dependencies: [] }
+  }
+
+  const hostPython = backendPython(cwd)
+  const venvDir = path.join(cwd, ".palette", "test-venv")
+  const venvPython = path.join(venvDir, "bin", "python")
+  const lockPath = path.join(venvDir, ".palette-deps-lock")
+  const lock = JSON.stringify(deps)
+
+  if (!fs.existsSync(venvPython)) {
+    const created = spawnSync(hostPython, ["-m", "venv", venvDir], {
+      cwd,
+      encoding: "utf8",
+      env: pythonEnv(),
+    })
+    if (created.status !== 0) {
+      return {
+        python: hostPython,
+        env: pythonEnv(),
+        failures: out.fail(
+          "could not create Python test virtualenv",
+          "Install Python's venv module or set PALETTE_PYTHON to a Python that can run `-m venv`.",
+          { stderr: (created.stderr || created.stdout || "").trim() },
+        ),
+        dependencies: deps,
+      }
+    }
+  }
+
+  if (!fs.existsSync(lockPath) || fs.readFileSync(lockPath, "utf8") !== lock) {
+    const installed = spawnSync(venvPython, ["-m", "pip", "install", ...deps], {
+      cwd,
+      encoding: "utf8",
+      env: pythonEnv(),
+    })
+    if (installed.status !== 0) {
+      return {
+        python: venvPython,
+        env: pythonEnv(),
+        failures: out.fail(
+          "could not install pyproject dependencies for backend import checks",
+          "Fix pyproject.toml dependencies or install them in .palette/test-venv before running pltt test.",
+          { stderr: (installed.stderr || installed.stdout || "").trim(), dependencies: deps },
+        ),
+        dependencies: deps,
+      }
+    }
+    fs.writeFileSync(lockPath, lock)
+  }
+
+  out.ok("pyproject dependencies installed for backend import checks", { dependencies: deps })
+  return { python: venvPython, env: pythonEnv(), failures: 0, dependencies: deps }
+}
+
+function checkBackendContract(cwd, manifest, out, pythonInfo) {
   const entry = manifest.backend?.entry
   if (!entry) return 0
   const abs = path.resolve(cwd, entry)
-  const python = backendPython(cwd)
+  const python = pythonInfo?.python || backendPython(cwd)
+  const env = pythonInfo?.env || pythonEnv()
   const script = [
     "import importlib.util, json, pathlib, sys",
     "entry = pathlib.Path(sys.argv[1]).resolve()",
@@ -86,7 +172,7 @@ function checkBackendContract(cwd, manifest, out) {
     "        ungated.append({'path': path, 'methods': methods})",
     "print(json.dumps({'routes': routes, 'used_permissions': sorted(used), 'ungated_routes': ungated, 'undeclared_permissions': sorted(used - declared), 'unused_declared_permissions': sorted(declared - used)}))",
   ].join("\n")
-  const res = spawnSync(python, ["-c", script, abs, JSON.stringify(manifest)], { encoding: "utf8" })
+  const res = spawnSync(python, ["-c", script, abs, JSON.stringify(manifest)], { encoding: "utf8", env })
   if (res.status === 0) {
     let report
     try {
@@ -220,6 +306,9 @@ function lintPackageJson(cwd, out) {
 
 function pythonDependencyRisk(dep) {
   const value = String(dep || "").trim()
+  const backendSdkRelease =
+    /^palette-sdk\s*@\s*https:\/\/github\.com\/palette-lab\/[-a-z0-9]+\/releases\/download\/sdk-backend-v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\/palette_sdk-\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:-py3-none-any\.whl|\.tar\.gz)$/i
+  if (backendSdkRelease.test(value)) return null
   if (/@\s*(https?:|file:)|\bgit\+|^\s*(https?:|file:)/i.test(value)) {
     return { level: "fail", reason: "dependency resolves from a local path, git repo, or URL" }
   }
@@ -274,6 +363,224 @@ function lintDependencyPolicy(cwd, out) {
   return lintPackageJson(cwd, out) + lintPyproject(cwd, out)
 }
 
+function parseVersion(version) {
+  const match = String(version || "").match(/^(\d+)\.(\d+)\.(\d+)/)
+  return match ? match.slice(1).map((n) => Number.parseInt(n, 10)) : null
+}
+
+function compareVersions(a, b) {
+  const av = parseVersion(a)
+  const bv = parseVersion(b)
+  if (!av || !bv) return 0
+  for (let i = 0; i < 3; i += 1) {
+    if (av[i] !== bv[i]) return av[i] - bv[i]
+  }
+  return 0
+}
+
+function versionSatisfies(version, range) {
+  if (!range) return true
+  const v = parseVersion(version)
+  if (!v) return false
+  const parts = String(range).trim().split(/\s+/)
+  if (parts.length > 1) return parts.every((part) => versionSatisfies(version, part))
+  const r = parts[0]
+  if (r === "*" || r.toLowerCase() === "latest") return false
+  if (r.startsWith("^")) {
+    const base = parseVersion(r.slice(1))
+    return !!base && v[0] === base[0] && compareVersions(version, r.slice(1)) >= 0
+  }
+  if (r.startsWith("~")) {
+    const base = parseVersion(r.slice(1))
+    return !!base && v[0] === base[0] && v[1] === base[1] && compareVersions(version, r.slice(1)) >= 0
+  }
+  if (r.startsWith(">=")) return compareVersions(version, r.slice(2)) >= 0
+  if (r.startsWith(">")) return compareVersions(version, r.slice(1)) > 0
+  if (r.startsWith("<=")) return compareVersions(version, r.slice(2)) <= 0
+  if (r.startsWith("<")) return compareVersions(version, r.slice(1)) < 0
+  return compareVersions(version, r) === 0
+}
+
+function packageVersion(...candidates) {
+  for (const candidate of candidates) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(candidate, "utf8"))
+      if (pkg.version) return pkg.version
+    } catch (_err) {
+      // Try the next candidate.
+    }
+  }
+  return null
+}
+
+function backendSdkVersionFromDependency(cwd) {
+  for (const dep of pyprojectDependencies(cwd)) {
+    const release = String(dep).match(/sdk-backend-v(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/)
+    if (release) return release[1]
+    const constrained = String(dep).match(/^palette-sdk\s*(?:[<>=~!]=?\s*)?(\d+\.\d+\.\d+)/)
+    if (constrained) return constrained[1]
+  }
+  const localPyproject = path.resolve(__dirname, "..", "..", "..", "backend", "pyproject.toml")
+  if (fs.existsSync(localPyproject)) {
+    const match = fs.readFileSync(localPyproject, "utf8").match(/^version\s*=\s*["']([^"']+)["']/m)
+    if (match) return match[1]
+  }
+  return null
+}
+
+function checkSdkCompatibility(cwd, manifest, out) {
+  let failures = 0
+  const frontendVersion = packageVersion(
+    path.join(cwd, "node_modules", "@palettelab", "sdk", "package.json"),
+    path.resolve(__dirname, "..", "..", "..", "frontend", "package.json"),
+  )
+  const backendVersion = backendSdkVersionFromDependency(cwd)
+  const platformVersion = process.env.PALETTE_PLATFORM_VERSION || "0.1.0"
+
+  if (manifest.sdk?.frontend) {
+    if (!frontendVersion || !versionSatisfies(frontendVersion, manifest.sdk.frontend)) {
+      failures += out.fail(
+        `frontend SDK compatibility failed: ${manifest.sdk.frontend}`,
+        "Install an @palettelab/sdk version that satisfies manifest.sdk.frontend.",
+        { installed: frontendVersion, required: manifest.sdk.frontend },
+      )
+    } else {
+      out.ok("frontend SDK compatibility passed", { installed: frontendVersion, required: manifest.sdk.frontend })
+    }
+  }
+
+  if (manifest.sdk?.backend) {
+    if (!backendVersion || !versionSatisfies(backendVersion, manifest.sdk.backend)) {
+      failures += out.fail(
+        `backend SDK compatibility failed: ${manifest.sdk.backend}`,
+        "Pin palette-sdk to a GitHub Release wheel that satisfies manifest.sdk.backend.",
+        { installed: backendVersion, required: manifest.sdk.backend },
+      )
+    } else {
+      out.ok("backend SDK compatibility passed", { installed: backendVersion, required: manifest.sdk.backend })
+    }
+  }
+
+  if (manifest.platform?.min_version || manifest.platform?.max_version) {
+    const minOk = !manifest.platform.min_version || versionSatisfies(platformVersion, `>=${manifest.platform.min_version}`)
+    const maxOk = !manifest.platform.max_version || versionSatisfies(platformVersion, `<=${manifest.platform.max_version}`)
+    if (!minOk || !maxOk) {
+      failures += out.fail(
+        "platform compatibility failed",
+        "Adjust manifest.platform or test against a compatible Palette platform version.",
+        { platform: platformVersion, required: manifest.platform },
+      )
+    } else {
+      out.ok("platform compatibility passed", { platform: platformVersion, required: manifest.platform })
+    }
+  }
+
+  return failures
+}
+
+function scanForbiddenImports(cwd, manifest, out) {
+  const roots = []
+  if (manifest.frontend?.entry) roots.push(path.resolve(cwd, "frontend"))
+  if (manifest.backend?.entry) roots.push(path.resolve(cwd, "backend"))
+  const forbidden = [
+    { re: /from\s+["'](?:@\/|app\/|backend\/|frontend\/)/, reason: "frontend imports platform source" },
+    { re: /import\s+["'](?:@\/|app\/|backend\/|frontend\/)/, reason: "frontend imports platform source" },
+    { re: /^\s*(?:from|import)\s+app(?:\.|\s)/m, reason: "backend imports platform app source" },
+  ]
+  const issues = []
+  const visit = (dir) => {
+    if (!fs.existsSync(dir)) return
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (["node_modules", ".venv", ".palette", "dist", "__pycache__"].includes(entry.name)) continue
+      const abs = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        visit(abs)
+        continue
+      }
+      if (!/\.(tsx?|jsx?|py)$/.test(entry.name)) continue
+      const src = fs.readFileSync(abs, "utf8")
+      for (const rule of forbidden) {
+        if (rule.re.test(src)) issues.push({ file: path.relative(cwd, abs), reason: rule.reason })
+      }
+    }
+  }
+  for (const root of roots) visit(root)
+  for (const issue of issues) {
+    out.fail(
+      `forbidden platform import in ${issue.file}`,
+      "Plugins must import only public SDK packages and their own local files.",
+      issue,
+    )
+  }
+  if (issues.length === 0) out.ok("forbidden platform import scan passed")
+  return issues.length
+}
+
+function checkSemverBump(cwd, manifest, out) {
+  const statePath = path.join(cwd, ".palette", "last-publish.json")
+  if (!fs.existsSync(statePath)) {
+    out.ok("semver bump check skipped; no previous publish state")
+    return 0
+  }
+  let previous
+  try {
+    previous = JSON.parse(fs.readFileSync(statePath, "utf8"))
+  } catch (_err) {
+    out.warn("semver bump check skipped; .palette/last-publish.json is invalid JSON")
+    return 0
+  }
+  const previousVersion = previous.version || previous.manifest?.version
+  if (!previousVersion) {
+    out.ok("semver bump check skipped; previous publish has no version")
+    return 0
+  }
+  if (compareVersions(manifest.version, previousVersion) <= 0) {
+    return out.fail(
+      `plugin version ${manifest.version} is not newer than last publish ${previousVersion}`,
+      "Bump manifest.version before publishing another build.",
+      { current: manifest.version, previous: previousVersion },
+    )
+  }
+  out.ok("semver bump check passed", { current: manifest.version, previous: previousVersion })
+  return 0
+}
+
+function bundleLimit(kind) {
+  const envName = kind === "frontend" ? "PALETTE_MAX_FRONTEND_BUNDLE_BYTES" : "PALETTE_MAX_BACKEND_BUNDLE_BYTES"
+  const fallback = kind === "frontend" ? DEFAULT_FRONTEND_BUNDLE_LIMIT : DEFAULT_BACKEND_BUNDLE_LIMIT
+  const parsed = Number.parseInt(process.env[envName] || "", 10)
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback
+}
+
+function checkBundleSize(kind, bytes, out) {
+  const limit = bundleLimit(kind)
+  if (bytes > limit) {
+    return out.fail(
+      `${kind} bundle exceeds size limit (${bytes} > ${limit} bytes)`,
+      `Reduce bundle size or set PALETTE_MAX_${kind.toUpperCase()}_BUNDLE_BYTES for a reviewed exception.`,
+      { bytes, limit },
+    )
+  }
+  out.ok(`${kind} bundle size within limit`, { bytes, limit })
+  return 0
+}
+
+function sandboxBridgeSmoke(cwd, manifest, out) {
+  if (!manifest.frontend?.entry) return 0
+  const entry = path.resolve(cwd, manifest.frontend.entry)
+  if (!fs.existsSync(entry)) return 0
+  const src = fs.readFileSync(entry, "utf8")
+  if (!/@palettelab\/sdk/.test(src)) {
+    out.warn(
+      "sandbox bridge smoke skipped; frontend does not import @palettelab/sdk",
+      "Use @palettelab/sdk helpers so sandboxed appstore runtime can communicate through the platform bridge.",
+    )
+    return 0
+  }
+  out.ok("sandbox bridge smoke passed")
+  return 0
+}
+
 async function run(args, { cwd }) {
   const json = args.includes("--json")
   let failures = 0
@@ -300,6 +607,10 @@ async function run(args, { cwd }) {
     out.ok(`manifest valid: ${manifest.id}@${manifest.version}`)
   }
 
+  failures += checkSdkCompatibility(cwd, manifest, out)
+  failures += scanForbiddenImports(cwd, manifest, out)
+  failures += checkSemverBump(cwd, manifest, out)
+
   for (const permission of manifest.permissions || []) {
     if (!KNOWN_PERMISSIONS.has(permission)) {
       failures += out.fail(
@@ -330,6 +641,8 @@ async function run(args, { cwd }) {
     try {
       const frontend = await bundleFrontend(cwd, manifest.frontend.entry)
       out.ok(`frontend bundles successfully (${frontend.length} bytes)`, { bytes: frontend.length })
+      failures += checkBundleSize("frontend", frontend.length, out)
+      failures += sandboxBridgeSmoke(cwd, manifest, out)
     } catch (err) {
       failures += out.fail(
         `frontend bundle failed: ${err instanceof Error ? err.message : String(err)}`,
@@ -339,17 +652,20 @@ async function run(args, { cwd }) {
   }
 
   if (manifest.backend?.entry) {
+    const pythonInfo = installPythonDependencies(cwd, out)
+    failures += pythonInfo.failures
     const backendEntry = path.resolve(cwd, manifest.backend.entry)
     if (!fs.existsSync(backendEntry)) {
       failures += out.fail(`backend entry not found: ${manifest.backend.entry}`)
     } else {
       out.ok(`backend entry exists: ${manifest.backend.entry}`)
-      failures += checkBackendContract(cwd, manifest, out)
+      failures += checkBackendContract(cwd, manifest, out, pythonInfo)
     }
 
     try {
       const backend = await bundleBackend(cwd)
       out.ok(`backend package builds successfully (${backend.length} bytes)`, { bytes: backend.length })
+      failures += checkBundleSize("backend", backend.length, out)
     } catch (err) {
       failures += out.fail(
         `backend package failed: ${err instanceof Error ? err.message : String(err)}`,

package/lib/environments.js

@@ -130,7 +130,7 @@ function resolveEnvironment({ cwd, flags }) {
  * Leaves positional args in `rest`.
  */
 function parseFlags(argv) {
-  const flags = { env: undefined, yes: false }
+  const flags = { env: undefined, yes: false, ttlHours: undefined, wait: false }
   const rest = []
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]
@@ -140,6 +140,12 @@ function parseFlags(argv) {
       flags.env = a.slice("--env=".length)
     } else if (a === "--yes" || a === "-y") {
       flags.yes = true
+    } else if (a === "--ttl-hours") {
+      flags.ttlHours = Number.parseInt(argv[++i] || "", 10)
+    } else if (a.startsWith("--ttl-hours=")) {
+      flags.ttlHours = Number.parseInt(a.slice("--ttl-hours=".length), 10)
+    } else if (a === "--wait") {
+      flags.wait = true
     } else {
       rest.push(a)
     }

package/lib/ports.js

@@ -13,13 +13,38 @@ function canBindPort(port, host = "0.0.0.0") {
   })
 }
 
+function canConnectPort(port, host, timeoutMs = 250) {
+  return new Promise((resolve) => {
+    const socket = net.createConnection({ port, host })
+    const done = (connected) => {
+      socket.removeAllListeners()
+      socket.destroy()
+      resolve(connected)
+    }
+    socket.setTimeout(timeoutMs)
+    socket.once("connect", () => done(true))
+    socket.once("timeout", () => done(false))
+    socket.once("error", () => done(false))
+  })
+}
+
+async function isPortAvailable(port, { bindHost = "0.0.0.0" } = {}) {
+  // Docker publishes host ports on localhost-facing addresses. A process bound
+  // only to 127.0.0.1 or ::1 can be missed by a single 0.0.0.0 bind probe on
+  // some host setups, so test the addresses users actually open in browsers.
+  for (const host of ["127.0.0.1", "::1", "localhost"]) {
+    if (await canConnectPort(port, host)) return false
+  }
+  return canBindPort(port, bindHost)
+}
+
 async function findFreePort(preferred, { host = "0.0.0.0", maxAttempts = 100 } = {}) {
   const start = Number(preferred)
   if (!Number.isInteger(start) || start <= 0 || start > 65535) {
     throw new Error(`invalid port: ${preferred}`)
   }
   for (let port = start; port < start + maxAttempts && port <= 65535; port++) {
-    if (await canBindPort(port, host)) return port
+    if (await isPortAvailable(port, { bindHost: host })) return port
   }
   throw new Error(`no free port found from ${start} to ${Math.min(start + maxAttempts - 1, 65535)}`)
 }
@@ -39,4 +64,4 @@ async function resolveDevPorts({
   }
 }
 
-module.exports = { canBindPort, findFreePort, resolveDevPorts }
+module.exports = { canBindPort, canConnectPort, isPortAvailable, findFreePort, resolveDevPorts }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.8",
+  "version": "0.3.10",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"
@@ -24,11 +24,7 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/palette-lab/virtual-organisation.git",
-    "directory": "sdk/cli-npm"
-  },
+  "homepage": "https://www.npmjs.com/package/@palettelab/cli",
   "license": "MIT",
   "keywords": [
     "pltt",

package/template-fallback/README.md

@@ -0,0 +1,20 @@
+# Palette Plugin Template
+
+Run the local contract gate before publishing:
+
+```bash
+pltt build
+pltt test --json
+pltt package --json
+```
+
+Expected preview flow:
+
+```bash
+pltt dev
+pltt dev --cloud --env staging
+```
+
+`pltt dev` opens the app locally at `/apps/<plugin-id>`. `pltt dev --cloud`
+publishes a temporary staging preview, returns the platform preview URL, and
+lets you poll review state with `pltt status <publish-id>`.

package/template-fallback/backend/tests/test_import.py

@@ -0,0 +1,11 @@
+import importlib.util
+from pathlib import Path
+
+
+def test_backend_entry_exports_router():
+    entry = Path(__file__).resolve().parents[1] / "api" / "main.py"
+    spec = importlib.util.spec_from_file_location("plugin_backend_entry", entry)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    assert getattr(module, "router", None) is not None

package/template-fallback/pyproject.toml

@@ -3,13 +3,16 @@ name = "palette-plugin-my-plugin"
 version = "1.0.0"
 description = "A Palette platform plugin"
 requires-python = ">=3.12"
-# palette-sdk is installed from the private platform repo. The
-# platform-dev container already has it on PYTHONPATH, so you do not
-# need to install it locally to run `pltt dev`. If you want to run
-# `pytest` on the backend outside the container, add this dependency
-# (replace $GH_PAT with your GitHub PAT with read:packages):
+# palette-sdk is distributed as a GitHub Release wheel on sdk-backend-vX.Y.Z.
+# The platform-dev container already has it on PYTHONPATH, so you do not need
+# to install it locally to run `pltt dev`. If you want to run pytest or IDE
+# imports outside the container, pin the backend SDK version you target:
 #
 # dependencies = [
-#     "palette-sdk @ git+https://${GH_PAT}@github.com/palette-lab/virtual-organisation.git#subdirectory=sdk/backend",
+#     "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-vX.Y.Z/palette_sdk-X.Y.Z-py3-none-any.whl",
 # ]
-dependencies = []
+dependencies = [
+    "fastapi>=0.129.0",
+    "sqlalchemy>=2.0.47",
+    # "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-vX.Y.Z/palette_sdk-X.Y.Z-py3-none-any.whl",
+]

package/template-fallback/templates/agent-tool/pyproject.toml

@@ -2,4 +2,8 @@
 name = "my-agent-tool"
 version = "1.0.0"
 requires-python = ">=3.12"
-dependencies = ["palette-sdk", "pydantic"]
+dependencies = [
+  "fastapi>=0.129.0",
+  "pydantic>=2.12.0",
+  # "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-vX.Y.Z/palette_sdk-X.Y.Z-py3-none-any.whl",
+]

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

@@ -2,4 +2,7 @@
 name = "my-dashboard"
 version = "1.0.0"
 requires-python = ">=3.12"
-dependencies = ["palette-sdk"]
+dependencies = [
+  "fastapi>=0.129.0",
+  # "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-vX.Y.Z/palette_sdk-X.Y.Z-py3-none-any.whl",
+]

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

@@ -2,4 +2,9 @@
 name = "my-db-plugin"
 version = "1.0.0"
 requires-python = ">=3.12"
-dependencies = ["palette-sdk", "sqlalchemy", "alembic"]
+dependencies = [
+  "fastapi>=0.129.0",
+  "sqlalchemy>=2.0.47",
+  "alembic>=1.17.0",
+  # "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-vX.Y.Z/palette_sdk-X.Y.Z-py3-none-any.whl",
+]

package/template-fallback/templates/external-service/pyproject.toml

@@ -2,4 +2,8 @@
 name = "my-external-svc"
 version = "1.0.0"
 requires-python = ">=3.12"
-dependencies = ["palette-sdk", "httpx"]
+dependencies = [
+  "fastapi>=0.129.0",
+  "httpx>=0.28.0",
+  # "palette-sdk @ https://github.com/palette-lab/palette-virtual-organization-backend/releases/download/sdk-backend-vX.Y.Z/palette_sdk-X.Y.Z-py3-none-any.whl",
+]