@palettelab/cli 0.3.3 → 0.3.4

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() {
@@ -61,6 +60,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,8 +85,14 @@ 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`
@@ -107,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 {

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