@palettelab/cli 0.3.2 → 0.3.4

package/README.md

@@ -47,24 +47,29 @@ Boot the platform locally with your plugin mounted live. Run this from inside yo
 
 ```bash
 pltt dev
+pltt dev --cloud --env staging
 ```
 
 Under the hood this runs `docker compose up` with a bundled compose file. It starts:
 
 - Postgres + Redis
-- The Palette frontend on http://localhost:3000
-- The Palette backend on http://localhost:8000
-- Your plugin at http://localhost:3000/apps/<your-id>
+- The Palette frontend on the first available port starting at http://localhost:3000
+- The Palette backend on the first available port starting at http://localhost:8000
+- Your plugin at the frontend URL printed by the CLI
 
 Your plugin directory is mounted into the container at `/plugins/<your-id>`. Edits to your frontend/backend sources hot-reload.
 
+`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.
+
 Environment variables:
 
 | Name | Default | Purpose |
 |---|---|---|
 | `PALETTE_DEV_IMAGE` | `ghcr.io/palette-lab/platform-dev:latest` | Override the platform image |
-| `PALETTE_FRONTEND_PORT` | `3000` | Host port for the frontend |
-| `PALETTE_BACKEND_PORT` | `8000` | Host port for the backend |
+| `PALETTE_FRONTEND_PORT` | `3000` | Preferred starting host port for the frontend |
+| `PALETTE_BACKEND_PORT` | `8000` | Preferred starting host port for the backend |
 
 ### `pltt doctor`
 
@@ -120,7 +125,7 @@ pltt publish --env production -y
 pltt publish --env staging --json
 ```
 
-Publishing 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`. 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.
 
 Environment config is read from `./palette.config.json`, `~/.palette/config.json`, or `PALETTE_<ENV>_URL` plus `PALETTE_<ENV>_TOKEN` / `PALETTE_PUBLISH_TOKEN`.
 
@@ -165,6 +170,6 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 
 ## See also
 
-- `@palettelab/sdk` on GitHub Packages — frontend hooks and types
+- `@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)

package/lib/bundler.js

@@ -101,14 +101,14 @@ async function watchFrontend(pluginDir, entry, outfile) {
         setup(build) {
           build.onEnd((result) => {
             if (result.errors.length) {
-              console.error("[palette] frontend bundle failed:")
+              console.error("[pltt] frontend bundle failed:")
               for (const err of result.errors) {
                 console.error(`  - ${err.text}`)
               }
               return
             }
             const size = fs.existsSync(outfile) ? fs.statSync(outfile).size : 0
-            console.log(`[palette] frontend bundle ready (${size} bytes)`)
+            console.log(`[pltt] frontend bundle ready (${size} bytes)`)
           })
         },
       },

package/lib/cli.js

@@ -49,6 +49,8 @@ function printHelp() {
   console.log("\nPublish flags:")
   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("  --cloud          Publish a reviewable preview to a configured cloud sandbox")
   console.log("\nInit flags:")
   console.log("  --template <name>  One of: dashboard, agent-tool, external-service, database, frontend-only")
   console.log("\nLogs flags:")

package/lib/commands/build.js

@@ -93,11 +93,11 @@ async function run(args, { cwd }) {
   }
 
   if (errors.length) {
-    console.error("[palette] validation failed:")
+    console.error("[pltt] validation failed:")
     for (const e of errors) console.error(`  - ${e}`)
     process.exit(1)
   }
-  console.log(`[palette] ok — ${manifest.id} v${manifest.version}`)
+  console.log(`[pltt] ok — ${manifest.id} v${manifest.version}`)
 }
 
 module.exports = run

package/lib/commands/dev.js

@@ -4,11 +4,12 @@ const path = require("path")
 const { spawn, spawnSync } = require("child_process")
 const { loadManifest } = require("../manifest")
 const { watchFrontend } = require("../bundler")
+const { parseFlags } = require("../environments")
+const { resolveDevPorts } = require("../ports")
+const publish = require("./publish")
 
 const DEFAULT_IMAGE =
   process.env.PALETTE_DEV_IMAGE || "ghcr.io/palette-lab/platform-dev:latest"
-const FRONTEND_PORT = process.env.PALETTE_FRONTEND_PORT || "3000"
-const BACKEND_PORT = process.env.PALETTE_BACKEND_PORT || "8000"
 const COMPOSE_FILE = path.resolve(__dirname, "..", "..", "platform-dev", "docker-compose.yml")
 
 function ensureDocker() {
@@ -39,34 +40,59 @@ function ensureImageAvailable(image) {
 }
 
 async function run(args, { cwd }) {
+  const { flags, rest } = parseFlags(args)
+  const cloud = rest.includes("--cloud")
+  if (cloud) {
+    const publishArgs = []
+    if (flags.env) publishArgs.push("--env", flags.env)
+    if (flags.yes) publishArgs.push("--yes")
+    if (args.includes("--json")) publishArgs.push("--json")
+    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 })
+    return
+  }
+
   const manifest = loadManifest(cwd)
   const pluginId = manifest.id
   const frontendEntry = manifest.frontend?.entry || "./frontend/src/index.tsx"
   const frontendBundle = path.join(cwd, ".palette", "dist", "frontend.mjs")
+  const ports = await resolveDevPorts()
+  const frontendPort = String(ports.frontend)
+  const backendPort = String(ports.backend)
 
   ensureDocker()
 
   let frontendWatcher = null
   if (manifest.frontend?.entry) {
-    console.log(`[palette] bundling frontend ${frontendEntry} → .palette/dist/frontend.mjs`)
+    console.log(`[pltt] bundling frontend ${frontendEntry} → .palette/dist/frontend.mjs`)
     try {
       frontendWatcher = await watchFrontend(cwd, frontendEntry, frontendBundle)
     } catch (err) {
       console.error(
-        `[palette] could not start frontend bundler: ${
+        `[pltt] could not start frontend bundler: ${
           err instanceof Error ? err.message : String(err)
         }`,
       )
       process.exit(1)
     }
   } else {
-    console.log("[palette] manifest has no frontend entry; skipping frontend bundler")
+    console.log("[pltt] manifest has no frontend entry; skipping frontend bundler")
   }
 
-  console.log(`[palette] starting ${DEFAULT_IMAGE} via docker compose`)
-  console.log(`[palette] mounting ${cwd} → /plugins/${pluginId}`)
-  console.log(`[palette] frontend: http://localhost:${FRONTEND_PORT}/apps/${pluginId}`)
-  console.log(`[palette] backend:  http://localhost:${BACKEND_PORT}/api/v1/plugins/${pluginId}`)
+  console.log(`[pltt] starting ${DEFAULT_IMAGE} via docker compose`)
+  console.log(`[pltt] mounting ${cwd} → /plugins/${pluginId}`)
+  if (ports.frontend !== ports.preferredFrontend) {
+    console.log(`[pltt] frontend port ${ports.preferredFrontend} is busy; using ${ports.frontend}`)
+  }
+  if (ports.backend !== ports.preferredBackend) {
+    console.log(`[pltt] backend port ${ports.preferredBackend} is busy; using ${ports.backend}`)
+  }
+  console.log(`[pltt] frontend: http://localhost:${frontendPort}/apps/${pluginId}`)
+  console.log(`[pltt] backend:  http://localhost:${backendPort}/api/v1/plugins/${pluginId}`)
 
   // Pre-pull so we can give a useful error if the image isn't reachable
   // (common cause: maintainer hasn't pushed it yet, or `docker login ghcr.io`
@@ -74,7 +100,7 @@ async function run(args, { cwd }) {
   if (!ensureImageAvailable(DEFAULT_IMAGE)) {
     if (frontendWatcher) await frontendWatcher.dispose()
     console.error(
-      `\n[palette] could not pull ${DEFAULT_IMAGE}.\n` +
+      `\n[pltt] could not pull ${DEFAULT_IMAGE}.\n` +
       `          Most common causes:\n` +
       `            • The image hasn't been published to the registry yet.\n` +
       `              Platform maintainers: see docker/platform-dev/README.md for the build + push flow.\n` +
@@ -89,8 +115,8 @@ async function run(args, { cwd }) {
     PALETTE_DEV_IMAGE: DEFAULT_IMAGE,
     PALETTE_ACTIVE_PLUGIN: pluginId,
     PALETTE_PLUGIN_DIR: cwd,
-    PALETTE_FRONTEND_PORT: FRONTEND_PORT,
-    PALETTE_BACKEND_PORT: BACKEND_PORT,
+    PALETTE_FRONTEND_PORT: frontendPort,
+    PALETTE_BACKEND_PORT: backendPort,
   }
 
   const projectName = `palette-dev-${pluginId}`

package/lib/commands/doctor.js

@@ -1,11 +1,11 @@
 "use strict"
 
 const fs = require("fs")
-const net = require("net")
 const path = require("path")
 const { spawnSync } = require("child_process")
 const { loadManifest, validateManifest } = require("../manifest")
 const { bundleFrontend } = require("../bundler")
+const { resolveDevPorts } = require("../ports")
 
 const DEFAULT_IMAGE =
   process.env.PALETTE_DEV_IMAGE || "ghcr.io/palette-lab/platform-dev:latest"
@@ -39,17 +39,6 @@ function imageExistsLocally(image) {
   return spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" }).status === 0
 }
 
-function canBindPort(port) {
-  return new Promise((resolve) => {
-    const server = net.createServer()
-    server.once("error", () => resolve(false))
-    server.once("listening", () => {
-      server.close(() => resolve(true))
-    })
-    server.listen(port, "127.0.0.1")
-  })
-}
-
 function checkEntry(cwd, label, rel) {
   if (!rel) return 0
   const abs = path.resolve(cwd, rel)
@@ -81,19 +70,18 @@ async function run(args, { cwd }) {
     )
   }
 
-  const frontendPortFree = await canBindPort(FRONTEND_PORT)
-  if (frontendPortFree) ok(`frontend port ${FRONTEND_PORT} is available`)
-  else failures += fail(
-    `frontend port ${FRONTEND_PORT} is already in use`,
-    `Run PALETTE_FRONTEND_PORT=${FRONTEND_PORT + 1} pltt dev`,
-  )
-
-  const backendPortFree = await canBindPort(BACKEND_PORT)
-  if (backendPortFree) ok(`backend port ${BACKEND_PORT} is available`)
-  else failures += fail(
-    `backend port ${BACKEND_PORT} is already in use`,
-    `Run PALETTE_BACKEND_PORT=${BACKEND_PORT + 1} pltt dev`,
-  )
+  try {
+    const ports = await resolveDevPorts({ frontend: FRONTEND_PORT, backend: BACKEND_PORT })
+    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`)
+    else warn(`backend port ${BACKEND_PORT} is already in use`, `pltt dev will use ${ports.backend}`)
+  } catch (err) {
+    failures += fail(
+      `could not find free dev ports: ${err instanceof Error ? err.message : String(err)}`,
+      "Free a local port or set PALETTE_FRONTEND_PORT / PALETTE_BACKEND_PORT to a wider available range.",
+    )
+  }
 
   let manifest
   try {
@@ -134,10 +122,10 @@ async function run(args, { cwd }) {
   }
 
   if (failures > 0) {
-    console.log(`\n[palette] doctor found ${failures} blocking issue(s).`)
+    console.log(`\n[pltt] doctor found ${failures} blocking issue(s).`)
     process.exit(1)
   }
-  console.log("\n[palette] doctor passed.")
+  console.log("\n[pltt] doctor passed.")
 }
 
 module.exports = run

package/lib/commands/init.js

@@ -72,13 +72,13 @@ async function run(args, { cwd }) {
   const name = positional[0]
   if (!name) {
     console.error("[pltt] usage: pltt init <plugin-name> [--template <name>]")
-    console.error(`[palette] templates: ${KNOWN_TEMPLATES.join(", ")}`)
+    console.error(`[pltt] templates: ${KNOWN_TEMPLATES.join(", ")}`)
     process.exit(1)
   }
   const template = getOpt(args, "--template")
   if (template && !KNOWN_TEMPLATES.includes(template)) {
-    console.error(`[palette] unknown template: ${template}`)
-    console.error(`[palette] templates: ${KNOWN_TEMPLATES.join(", ")}`)
+    console.error(`[pltt] unknown template: ${template}`)
+    console.error(`[pltt] templates: ${KNOWN_TEMPLATES.join(", ")}`)
     process.exit(1)
   }
   const slug = toSlug(name)
@@ -87,25 +87,25 @@ async function run(args, { cwd }) {
     .replace(/\b\w/g, (c) => c.toUpperCase())
   const destDir = path.join(cwd, slug)
   if (fs.existsSync(destDir)) {
-    console.error(`[palette] directory already exists: ${destDir}`)
+    console.error(`[pltt] directory already exists: ${destDir}`)
     process.exit(1)
   }
 
   if (template) {
-    console.log(`[palette] creating plugin "${slug}" from template "${template}"`)
+    console.log(`[pltt] creating plugin "${slug}" from template "${template}"`)
   } else {
-    console.log(`[palette] creating plugin "${slug}" from ${TEMPLATE_REPO}@${TEMPLATE_REF}`)
+    console.log(`[pltt] creating plugin "${slug}" from ${TEMPLATE_REPO}@${TEMPLATE_REF}`)
   }
 
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "palette-tpl-"))
   let ok = false
   if (!template) {
     ok = fetchTemplate(tmp)
-    if (!ok) console.warn("[palette] git clone failed, falling back to bundled template")
+    if (!ok) console.warn("[pltt] git clone failed, falling back to bundled template")
   }
   if (!ok) ok = copyLocalFallback(tmp, template)
   if (!ok) {
-    console.error("[palette] no template available")
+    console.error("[pltt] no template available")
     process.exit(1)
   }
 
@@ -113,8 +113,8 @@ async function run(args, { cwd }) {
   fs.rmSync(tmp, { recursive: true, force: true })
   rewriteManifest(destDir, slug, displayName)
 
-  console.log(`[palette] created ${destDir}`)
-  console.log("[palette] next steps:")
+  console.log(`[pltt] created ${destDir}`)
+  console.log("[pltt] next steps:")
   console.log(`  cd ${slug}`)
   console.log(`  npx @palettelab/cli dev`)
   console.log(`  # or, after global install: pltt dev`)

package/lib/commands/logs.js

@@ -50,7 +50,7 @@ async function run(argv, { cwd }) {
     }
   }
   if (!pluginId) {
-    console.error("[palette] no plugin id provided and no manifest found.")
+    console.error("[pltt] no plugin id provided and no manifest found.")
     process.exit(1)
   }
 
@@ -60,11 +60,11 @@ async function run(argv, { cwd }) {
   try {
     env = resolveEnvironment({ cwd, flags })
   } catch (err) {
-    console.error(`[palette] ${err.message}`)
+    console.error(`[pltt] ${err.message}`)
     process.exit(1)
   }
   if (!env.token) {
-    console.error(`[palette] no publish token for "${env.name}". set $${env.token_env}.`)
+    console.error(`[pltt] no publish token for "${env.name}". set $${env.token_env}.`)
     process.exit(1)
   }
 
@@ -74,7 +74,7 @@ async function run(argv, { cwd }) {
     try {
       data = await fetchLogs(env, pluginId, tail)
     } catch (err) {
-      console.error(`[palette] ${err.message}`)
+      console.error(`[pltt] ${err.message}`)
       process.exit(1)
     }
     const events = data.events || []

package/lib/commands/package.js

@@ -15,7 +15,7 @@ async function run(argv, { cwd }) {
   const manifest = loadManifest(cwd)
   const errors = validateManifest(manifest)
   if (errors.length) {
-    console.error("[palette] manifest invalid:")
+    console.error("[pltt] manifest invalid:")
     for (const e of errors) console.error(`  - ${e}`)
     process.exit(1)
   }
@@ -41,7 +41,7 @@ async function run(argv, { cwd }) {
   const { spawnSync } = require("child_process")
   const r = spawnSync("tar", ["-czf", out, "-C", stage, "."], { stdio: "inherit" })
   if (r.status !== 0) {
-    console.error("[palette] tar failed")
+    console.error("[pltt] tar failed")
     process.exit(1)
   }
 
@@ -56,8 +56,8 @@ async function run(argv, { cwd }) {
   if (json) {
     console.log(JSON.stringify(result, null, 2))
   } else {
-    console.log(`[palette] packaged ${manifest.id}@${manifest.version} → ${out} (${buf.length} bytes)`)
-    console.log(`[palette] sha256: ${result.sha256}`)
+    console.log(`[pltt] packaged ${manifest.id}@${manifest.version} → ${out} (${buf.length} bytes)`)
+    console.log(`[pltt] sha256: ${result.sha256}`)
   }
 }
 

package/lib/commands/publish.js

@@ -3,6 +3,7 @@
 const crypto = require("crypto")
 const fs = require("fs")
 const path = require("path")
+const { spawnSync } = require("child_process")
 const { loadManifest, validateManifest } = require("../manifest")
 const { bundleFrontend, bundleBackend } = require("../bundler")
 const {
@@ -15,6 +16,35 @@ function sha256(buf) {
   return crypto.createHash("sha256").update(buf).digest("hex")
 }
 
+function runPreflight(cwd, json) {
+  const cliBin = path.resolve(__dirname, "..", "..", "bin", "pltt.js")
+  const res = spawnSync(process.execPath, [cliBin, "test", "--json"], {
+    cwd,
+    encoding: "utf8",
+    env: process.env,
+  })
+
+  if (res.status === 0) {
+    if (!json) console.log("[pltt] preflight contract tests passed")
+    return
+  }
+
+  const output = `${res.stdout || ""}${res.stderr || ""}`.trim()
+  if (json) {
+    let payload = null
+    try {
+      payload = JSON.parse(res.stdout)
+    } catch {
+      payload = { ok: false, error: output || "pltt test failed" }
+    }
+    console.log(JSON.stringify({ ok: false, stage: "preflight", test: payload }, null, 2))
+  } else {
+    console.error("[pltt] preflight contract tests failed; publish cancelled.")
+    if (output) console.error(output)
+  }
+  process.exit(res.status || 1)
+}
+
 function makeApi(env) {
   return async function api(pathname, { method = "GET", body, headers = {} } = {}) {
     const url = `${env.url}${pathname}`
@@ -54,13 +84,13 @@ async function run(argv, { cwd }) {
   try {
     env = resolveEnvironment({ cwd, flags })
   } catch (err) {
-    console.error(`[palette] ${err.message}`)
+    console.error(`[pltt] ${err.message}`)
     process.exit(1)
   }
 
   if (!env.token) {
     console.error(
-      `[palette] no publish token for environment "${env.name}". ` +
+      `[pltt] no publish token for environment "${env.name}". ` +
         `Set $${env.token_env} (or $PALETTE_PUBLISH_TOKEN as fallback).\n` +
         `          Ask a superadmin to mint one via POST ${env.url}/api/superadmin/publish-tokens.`,
     )
@@ -70,7 +100,7 @@ async function run(argv, { cwd }) {
   if (env.production_unconfirmed) {
     const ok = await confirmProduction(env)
     if (!ok) {
-      console.error("[palette] publish cancelled.")
+      console.error("[pltt] publish cancelled.")
       process.exit(1)
     }
   }
@@ -78,32 +108,34 @@ async function run(argv, { cwd }) {
   const manifest = loadManifest(cwd)
   const errors = validateManifest(manifest)
   if (errors.length) {
-    console.error("[palette] manifest invalid:")
+    console.error("[pltt] manifest invalid:")
     for (const e of errors) console.error(`  - ${e}`)
     process.exit(1)
   }
 
+  runPreflight(cwd, flags.json)
+
   console.log(
-    `[palette] publishing ${manifest.id}@${manifest.version} → ${env.name} (${env.url})`,
+    `[pltt] publishing ${manifest.id}@${manifest.version} → ${env.name} (${env.url})`,
   )
 
   let frontend = null
   if (manifest.frontend?.entry) {
-    console.log("[palette]   bundling frontend")
+    console.log("[pltt]   bundling frontend")
     frontend = await bundleFrontend(cwd, manifest.frontend.entry)
-    console.log(`[palette]     ${frontend.length} bytes`)
+    console.log(`[pltt]     ${frontend.length} bytes`)
   } else {
-    console.log("[palette]   no frontend declared")
+    console.log("[pltt]   no frontend declared")
   }
 
-  console.log("[palette]   bundling backend")
+  console.log("[pltt]   bundling backend")
   const backend = await bundleBackend(cwd)
-  console.log(`[palette]     ${backend.length} bytes`)
+  console.log(`[pltt]     ${backend.length} bytes`)
 
   const backendSha = sha256(backend)
   const api = makeApi(env)
 
-  console.log("[palette]   requesting signed URLs")
+  console.log("[pltt]   requesting signed URLs")
   const signed = await api("/api/v1/appstore/sign-upload", {
     method: "POST",
     body: {
@@ -113,7 +145,7 @@ async function run(argv, { cwd }) {
     },
   })
 
-  console.log("[palette]   uploading")
+  console.log("[pltt]   uploading")
   const uploads = [
     put(signed.backend_upload_url, backend, "application/gzip"),
     put(
@@ -127,7 +159,7 @@ async function run(argv, { cwd }) {
   }
   await Promise.all(uploads)
 
-  console.log("[palette]   finalizing")
+  console.log("[pltt]   finalizing")
   const record = await api("/api/v1/appstore/publish", {
     method: "POST",
     body: {
@@ -168,16 +200,16 @@ async function run(argv, { cwd }) {
   }
 
   console.log(
-    `[palette] published ${record.plugin_id}@${record.version} (status=${record.status})`,
+    `[pltt] published ${record.plugin_id}@${record.version} (status=${record.status})`,
   )
-  console.log(`[palette] awaiting superadmin review on ${env.url}`)
+  console.log(`[pltt] awaiting superadmin review on ${env.url}`)
   if (record.review_url) {
-    console.log(`[palette] review queue: ${record.review_url}`)
+    console.log(`[pltt] review queue: ${record.review_url}`)
   }
   if (record.preview_url) {
-    console.log(`[palette] preview: ${record.preview_url}`)
+    console.log(`[pltt] preview: ${record.preview_url}`)
   }
-  console.log(`[palette] once approved, live at ${env.url}${record.catalog_url}`)
+  console.log(`[pltt] once approved, live at ${env.url}${record.catalog_url}`)
 }
 
 module.exports = run

package/lib/commands/status.js

@@ -22,7 +22,7 @@ async function run(argv, { cwd }) {
 
   if (!publishId) {
     console.error(
-      "[palette] no publish id provided and no .palette/last-publish.json found.",
+      "[pltt] no publish id provided and no .palette/last-publish.json found.",
     )
     console.error("          usage: pltt status <publish-id> [--env <name>]")
     process.exit(1)
@@ -35,13 +35,13 @@ async function run(argv, { cwd }) {
   try {
     env = resolveEnvironment({ cwd, flags })
   } catch (err) {
-    console.error(`[palette] ${err.message}`)
+    console.error(`[pltt] ${err.message}`)
     process.exit(1)
   }
 
   if (!env.token) {
     console.error(
-      `[palette] no publish token for environment "${env.name}". set $${env.token_env}.`,
+      `[pltt] no publish token for environment "${env.name}". set $${env.token_env}.`,
     )
     process.exit(1)
   }
@@ -52,7 +52,7 @@ async function run(argv, { cwd }) {
   })
   if (!res.ok) {
     const text = await res.text()
-    console.error(`[palette] GET ${url} → ${res.status}: ${text}`)
+    console.error(`[pltt] GET ${url} → ${res.status}: ${text}`)
     process.exit(1)
   }
   const data = await res.json()
@@ -62,7 +62,7 @@ async function run(argv, { cwd }) {
     return
   }
 
-  console.log(`[palette] ${data.plugin_id}@${data.version}`)
+  console.log(`[pltt] ${data.plugin_id}@${data.version}`)
   console.log(`  status:    ${data.status}`)
   if (data.review_decision) console.log(`  decision:  ${data.review_decision}`)
   if (data.review_reason) console.log(`  reason:    ${data.review_reason}`)

package/lib/commands/test.js

@@ -365,12 +365,12 @@ async function run(args, { cwd }) {
     if (json) {
       console.log(JSON.stringify({ ok: false, failures, results }, null, 2))
     } else {
-      console.log(`\n[palette] test failed with ${failures} issue(s).`)
+      console.log(`\n[pltt] test failed with ${failures} issue(s).`)
     }
     process.exit(1)
   }
   if (json) console.log(JSON.stringify({ ok: true, failures: 0, results }, null, 2))
-  else console.log("\n[palette] test passed.")
+  else console.log("\n[pltt] test passed.")
 }
 
 module.exports = run

package/lib/environments.js

@@ -52,7 +52,7 @@ function readJsonIfExists(p) {
     if (!fs.existsSync(p)) return null
     return JSON.parse(fs.readFileSync(p, "utf8"))
   } catch (err) {
-    console.error(`[palette] failed to parse ${p}: ${err.message}`)
+    console.error(`[pltt] failed to parse ${p}: ${err.message}`)
     return null
   }
 }
@@ -152,7 +152,7 @@ async function confirmProduction(env) {
     const readline = require("readline")
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
     rl.question(
-      `\n[palette] You are about to publish to PRODUCTION (${env.url}).\n` +
+      `\n[pltt] You are about to publish to PRODUCTION (${env.url}).\n` +
         `          Type the environment name ("${env.name}") to confirm, anything else cancels: `,
       (answer) => {
         rl.close()

package/lib/ports.js

@@ -0,0 +1,42 @@
+"use strict"
+
+const net = require("net")
+
+function canBindPort(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const server = net.createServer()
+    server.once("error", () => resolve(false))
+    server.once("listening", () => {
+      server.close(() => resolve(true))
+    })
+    server.listen(port, host)
+  })
+}
+
+async function findFreePort(preferred, { host = "127.0.0.1", 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
+  }
+  throw new Error(`no free port found from ${start} to ${Math.min(start + maxAttempts - 1, 65535)}`)
+}
+
+async function resolveDevPorts({
+  frontend = process.env.PALETTE_FRONTEND_PORT || 3000,
+  backend = process.env.PALETTE_BACKEND_PORT || 8000,
+} = {}) {
+  const frontendPort = await findFreePort(frontend)
+  const backendStart = Number(backend) === frontendPort ? frontendPort + 1 : backend
+  const backendPort = await findFreePort(backendStart)
+  return {
+    frontend: frontendPort,
+    backend: backendPort,
+    preferredFrontend: Number(frontend),
+    preferredBackend: Number(backend),
+  }
+}
+
+module.exports = { canBindPort, findFreePort, resolveDevPorts }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"
@@ -22,7 +22,7 @@
     "esbuild": "^0.24.0"
   },
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com"
+    "registry": "https://registry.npmjs.org"
   },
   "repository": {
     "type": "git",