@palettelab/cli 0.3.3 → 0.3.5

package/README.md

@@ -53,12 +53,14 @@ 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:
@@ -66,8 +68,8 @@ 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`
 

package/lib/commands/dev.js

@@ -5,12 +5,11 @@ 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() {
@@ -29,17 +28,40 @@ function imageExistsLocally(image) {
 }
 
 function tryPullImage(image) {
-  const res = spawnSync("docker", ["pull", image], { stdio: "inherit" })
-  return res.status === 0
+  const res = spawnSync("docker", ["pull", image], { encoding: "utf8" })
+  if (res.stdout) process.stdout.write(res.stdout)
+  if (res.stderr) process.stderr.write(res.stderr)
+  return {
+    ok: res.status === 0,
+    output: `${res.stdout || ""}${res.stderr || ""}`,
+  }
 }
 
 function ensureImageAvailable(image) {
   // Accept a locally-built image (e.g. `platform-dev:test` from `docker build`)
   // without attempting a registry pull — local is authoritative if present.
-  if (imageExistsLocally(image)) return true
+  if (imageExistsLocally(image)) return { ok: true, output: "" }
   return tryPullImage(image)
 }
 
+function imagePullHelp(image, output) {
+  const arch = `${process.platform}/${process.arch}`
+  const archHint =
+    /no matching manifest|manifest.*unknown|not found/i.test(output || "")
+      ? `            • The image tag may not include your CPU architecture (${arch}).\n` +
+        "              Platform maintainers: publish a multi-arch image for linux/amd64 and linux/arm64.\n"
+      : ""
+  return (
+    `\n[pltt] could not pull ${image}.\n` +
+    `          Most common causes:\n` +
+    archHint +
+    `            • The image hasn't been published to the registry yet.\n` +
+    `              Platform maintainers: run the platform-dev publish workflow and push the latest tag.\n` +
+    `            • You are not logged in:  docker login ghcr.io -u <github-user> -p <pat>\n` +
+    `            • You are pointing at a different tag: set PALETTE_DEV_IMAGE=<your-image> to override.\n`
+  )
+}
+
 async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
   const cloud = rest.includes("--cloud")
@@ -61,6 +83,9 @@ async function run(args, { 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()
 
@@ -83,22 +108,22 @@ async function run(args, { cwd }) {
 
   console.log(`[pltt] starting ${DEFAULT_IMAGE} via docker compose`)
   console.log(`[pltt] mounting ${cwd} → /plugins/${pluginId}`)
-  console.log(`[pltt] frontend: http://localhost:${FRONTEND_PORT}/apps/${pluginId}`)
-  console.log(`[pltt] backend:  http://localhost:${BACKEND_PORT}/api/v1/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`
   // missing). Without this, the `docker compose up` failure is cryptic.
-  if (!ensureImageAvailable(DEFAULT_IMAGE)) {
+  const image = ensureImageAvailable(DEFAULT_IMAGE)
+  if (!image.ok) {
     if (frontendWatcher) await frontendWatcher.dispose()
-    console.error(
-      `\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` +
-      `            • You are not logged in:  docker login ghcr.io -u <github-user> -p <pat>\n` +
-      `            • You are pointing at a different tag: set PALETTE_DEV_IMAGE=<your-image> to override.\n`,
-    )
+    console.error(imagePullHelp(DEFAULT_IMAGE, image.output))
     process.exit(1)
   }
 
@@ -107,8 +132,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 {

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.3",
+  "version": "0.3.5",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"