@palettelab/cli 0.3.15 → 0.3.17

package/README.md

@@ -7,7 +7,8 @@ The installed executable is `pltt`.
 ## Requirements
 
 - Node.js 18+
-- Docker Desktop (for `pltt dev`)
+- Python 3.12+ for local backend simulation
+- Docker Desktop only for `pltt dev --platform`
 
 ## Install
 
@@ -43,31 +44,37 @@ Templates:
 
 ### `pltt dev`
 
-Boot the platform locally with your plugin mounted live. Run this from inside your plugin directory.
+Run a no-Docker local SDK simulator with your plugin mounted live. Run this from inside your plugin directory.
 
 ```bash
 pltt dev
+pltt dev --platform
 pltt dev --cloud --env staging
 ```
 
-Under the hood this runs `docker compose up` with a bundled compose file. It starts:
+By default this starts:
 
-- Postgres + Redis
-- 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
+- A small local app shell on the first available port starting at http://localhost:3000
+- A local FastAPI backend runner on the first available port starting at http://localhost:8000
+- A mock Palette platform context for `usePlatform()`, toasts, org/user data, and authenticated API calls
 
-Your plugin directory is mounted into the container at `/plugins/<your-id>`. Edits to your frontend/backend sources hot-reload.
+Your frontend entry is bundled and watched. Your backend entry is loaded under
+`/api/v1/plugins/<your-id>/*` with a dev `PluginContext`, so normal SDK calls
+work without Docker or platform source.
 
 `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 --platform` runs the full Docker `platform-dev` image for deeper
+integration/parity testing. It pulls `ghcr.io/palette-lab/platform-dev:latest`
+and mounts your plugin at `/plugins/<your-id>`.
+
 `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:
 
 | Name | Default | Purpose |
 |---|---|---|
-| `PALETTE_DEV_IMAGE` | `ghcr.io/palette-lab/platform-dev:latest` | Override the platform image |
+| `PALETTE_DEV_IMAGE` | `ghcr.io/palette-lab/platform-dev:latest` | Override the platform image for `--platform` |
 | `PALETTE_FRONTEND_PORT` | `3000` | Preferred starting host port for the frontend |
 | `PALETTE_BACKEND_PORT` | `8000` | Preferred starting host port for the backend |
 
@@ -167,8 +174,9 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 `@palettelab/cli` itself contains only:
 
 - `bin/pltt.js` — entry point
+- `backend-sdk/` — backend SDK files used by local contract tests and simulator
 - `lib/` — pure-Node command implementations (no runtime dependencies)
-- `platform-dev/docker-compose.yml` — compose file for `pltt dev`
+- `platform-dev/docker-compose.yml` — compose file for `pltt dev --platform`
 - `template-fallback/` — offline fallback for `pltt init` if git is unavailable
 
 ## See also

package/lib/cli.js

@@ -14,7 +14,7 @@ const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
   dev: {
     run: dev,
-    help: "Boot the platform-dev container and mount the current plugin for live development",
+    help: "Run the local SDK simulator; use --platform for Docker platform parity",
   },
   doctor: {
     run: doctor,
@@ -50,6 +50,7 @@ function printHelp() {
   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("  --platform       Run the full Docker platform-dev container")
   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")

package/lib/commands/dev.js

@@ -6,6 +6,7 @@ const { loadManifest } = require("../manifest")
 const { watchFrontend } = require("../bundler")
 const { parseFlags } = require("../environments")
 const { resolveDevPorts } = require("../ports")
+const { startSimulator } = require("../dev-simulator")
 const publish = require("./publish")
 
 const DEFAULT_PLATFORM_IMAGE = "ghcr.io/palette-lab/platform-dev:latest"
@@ -16,7 +17,7 @@ function ensureDocker() {
   const check = spawnSync("docker", ["info"], { stdio: "ignore" })
   if (check.status !== 0) {
     console.error(
-      "[pltt] docker is required for `pltt dev`. Install Docker Desktop and make sure it is running.",
+      "[pltt] docker is required for `pltt dev --platform`. Install Docker Desktop and make sure it is running.",
     )
     process.exit(1)
   }
@@ -76,6 +77,7 @@ function imagePullHelp(image, output) {
 async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
   const cloud = rest.includes("--cloud")
+  const platform = rest.includes("--platform")
   if (cloud) {
     const json = args.includes("--json")
     const publishArgs = []
@@ -106,9 +108,21 @@ async function run(args, { cwd }) {
 
   const manifest = loadManifest(cwd)
   const pluginId = manifest.id
+  const ports = await resolveDevPorts({ host: platform ? "0.0.0.0" : "127.0.0.1" })
+
+  if (!platform) {
+    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}`)
+    }
+    await startSimulator({ cwd, frontendPort: ports.frontend, backendPort: ports.backend })
+    return
+  }
+
   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)
 

package/lib/dev-simulator.js

@@ -0,0 +1,380 @@
+"use strict"
+
+const fs = require("fs")
+const http = require("http")
+const path = require("path")
+const { spawn, spawnSync } = require("child_process")
+
+const { loadManifest } = require("./manifest")
+
+function loadEsbuild() {
+  try {
+    return require("esbuild")
+  } catch (_err) {
+    throw new Error("esbuild is required for `pltt dev`. Run `npm install` inside your plugin directory.")
+  }
+}
+
+function localBackendSdkPath() {
+  const candidates = [
+    path.resolve(__dirname, "..", "backend-sdk"),
+    path.resolve(__dirname, "..", "..", "..", "backend"),
+  ]
+  return candidates.find((candidate) => fs.existsSync(path.join(candidate, "palette_sdk"))) || null
+}
+
+function extractPyprojectDependencies(src) {
+  const deps = []
+  src = src
+    .split(/\r?\n/)
+    .filter((line) => !line.trimStart().startsWith("#"))
+    .map((line) => line.replace(/\s+#.*$/, ""))
+    .join("\n")
+  const match = src.match(/dependencies\s*=\s*\[([\s\S]*?)\]/)
+  if (!match) return deps
+  const re = /"([^"]+)"|'([^']+)'/g
+  let item
+  while ((item = re.exec(match[1])) !== null) deps.push(item[1] || item[2])
+  return deps
+}
+
+function pyprojectDependencies(cwd) {
+  const pyprojectPath = path.join(cwd, "pyproject.toml")
+  if (!fs.existsSync(pyprojectPath)) return []
+  return extractPyprojectDependencies(fs.readFileSync(pyprojectPath, "utf8"))
+}
+
+function ensurePythonEnv(cwd, devDir) {
+  const hostPython = process.env.PALETTE_PYTHON || "python3"
+  const venvDir = path.join(devDir, "backend-venv")
+  const venvPython = path.join(venvDir, "bin", "python")
+  const lockPath = path.join(venvDir, ".palette-dev-deps-lock")
+  const deps = Array.from(new Set([...pyprojectDependencies(cwd), "uvicorn>=0.30.0"]))
+  const lock = JSON.stringify(deps)
+
+  if (!fs.existsSync(venvPython)) {
+    const created = spawnSync(hostPython, ["-m", "venv", venvDir], {
+      cwd,
+      encoding: "utf8",
+      env: process.env,
+    })
+    if (created.status !== 0) {
+      throw new Error(
+        "could not create Python dev virtualenv. Install Python venv support or set PALETTE_PYTHON.\n" +
+          (created.stderr || created.stdout || ""),
+      )
+    }
+  }
+
+  if (!fs.existsSync(lockPath) || fs.readFileSync(lockPath, "utf8") !== lock) {
+    const installed = spawnSync(venvPython, ["-m", "pip", "install", ...deps], {
+      cwd,
+      encoding: "utf8",
+      env: process.env,
+    })
+    if (installed.status !== 0) {
+      throw new Error(
+        "could not install Python dependencies for local backend dev.\n" +
+          "Fix pyproject.toml dependencies or preinstall them in .palette/dev/backend-venv.\n" +
+          (installed.stderr || installed.stdout || ""),
+      )
+    }
+    fs.writeFileSync(lockPath, lock)
+  }
+
+  return venvPython
+}
+
+function writeBackendRunner(cwd, devDir, manifest, backendEntry) {
+  const runner = path.join(devDir, "backend_runner.py")
+  const sdkPath = localBackendSdkPath()
+  const content = `from __future__ import annotations
+
+import importlib.util
+import json
+import pathlib
+import sys
+from types import SimpleNamespace
+
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.middleware.base import BaseHTTPMiddleware
+
+ROOT = pathlib.Path(${JSON.stringify(cwd)}).resolve()
+ENTRY = pathlib.Path(${JSON.stringify(path.resolve(cwd, backendEntry))}).resolve()
+MANIFEST = json.loads(${JSON.stringify(JSON.stringify(manifest))})
+SDK_PATH = ${JSON.stringify(sdkPath || "")}
+
+if SDK_PATH:
+    sys.path.insert(0, SDK_PATH)
+sys.path.insert(0, str(ROOT))
+sys.path.insert(0, str(ENTRY.parent))
+
+spec = importlib.util.spec_from_file_location("palette_local_backend", ENTRY)
+module = importlib.util.module_from_spec(spec)
+assert spec and spec.loader
+spec.loader.exec_module(module)
+router = getattr(module, "router", None)
+if router is None:
+    raise RuntimeError(f"backend entry has no router export: {ENTRY}")
+
+class DevPluginContextMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        request.state.db = None
+        request.state.user = SimpleNamespace(
+            id="dev-user",
+            email="developer@palette.local",
+            name="Palette Developer",
+            organization_id=1,
+        )
+        request.state.org_role = "owner"
+        request.state.plugin_id = MANIFEST.get("id", "")
+        request.state.plugin_permissions = MANIFEST.get("permissions", [])
+        request.state.plugin_config = {}
+        request.state.storage = None
+        return await call_next(request)
+
+app = FastAPI(title=f"{MANIFEST.get('name', 'Palette Plugin')} Local Backend")
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+app.add_middleware(DevPluginContextMiddleware)
+app.include_router(router, prefix=f"/api/v1/plugins/{MANIFEST['id']}")
+`
+  fs.writeFileSync(runner, content)
+  return runner
+}
+
+function startBackend(cwd, devDir, manifest, backendPort) {
+  const backendEntry = manifest.backend?.entry
+  if (!backendEntry) return null
+  const absEntry = path.resolve(cwd, backendEntry)
+  if (!fs.existsSync(absEntry)) throw new Error(`backend entry not found: ${backendEntry}`)
+
+  const python = ensurePythonEnv(cwd, devDir)
+  const runner = writeBackendRunner(cwd, devDir, manifest, backendEntry)
+  const sdkPath = localBackendSdkPath()
+  const env = { ...process.env }
+  if (sdkPath) {
+    env.PYTHONPATH = [sdkPath, env.PYTHONPATH].filter(Boolean).join(path.delimiter)
+  }
+  const child = spawn(
+    python,
+    ["-m", "uvicorn", `${path.basename(runner, ".py")}:app`, "--host", "127.0.0.1", "--port", String(backendPort), "--reload", "--reload-dir", path.dirname(absEntry)],
+    { cwd: devDir, stdio: "inherit", env },
+  )
+  return child
+}
+
+function simulatorEntrySource(pluginEntry, manifest, backendPort) {
+  return `
+import React from "react"
+import { createRoot } from "react-dom/client"
+import { PluginProvider } from "@palettelab/sdk"
+import Plugin from ${JSON.stringify(pluginEntry)}
+
+const backendBase = "http://127.0.0.1:${backendPort}"
+
+async function apiFetch(path, init) {
+  const target = String(path || "")
+  if (target.startsWith("http://") || target.startsWith("https://")) {
+    return fetch(target, init)
+  }
+  if (target.startsWith("/api/")) {
+    return fetch(backendBase + target, init)
+  }
+  return fetch(target, init)
+}
+
+const platform = {
+  user: {
+    id: "dev-user",
+    email: "developer@palette.local",
+    name: "Palette Developer",
+    is_active: true,
+    created_at: new Date().toISOString(),
+    onboarding_completed: true,
+    company_name: "Palette Local",
+    company_type: "Development",
+    org_theme: null,
+    org_logo: null,
+    org_enabled_menu_items: null,
+    org_menu_labels: null,
+    org_enabled_apps: [${JSON.stringify(manifest.id)}],
+    org_app_store_enabled: true,
+    org_enabled_agent_ids: null,
+    organization_id: 1,
+    org_role: "owner",
+  },
+  organizationId: 1,
+  orgRole: "owner",
+  orgs: [{ id: 1, name: "Local Dev Org", slug: "local-dev", theme_id: "default", logo_url: null }],
+  agents: [],
+  apiFetch,
+  navigate: (path) => window.history.pushState(null, "", path),
+  showToast: (message, type = "info") => {
+    window.dispatchEvent(new CustomEvent("palette-toast", { detail: { message, type } }))
+    console.log("[palette-toast]", type, message)
+  },
+}
+
+function Toasts() {
+  const [items, setItems] = React.useState([])
+  React.useEffect(() => {
+    const onToast = (event) => {
+      const id = Date.now()
+      setItems((current) => [...current, { id, ...event.detail }])
+      window.setTimeout(() => setItems((current) => current.filter((item) => item.id !== id)), 2500)
+    }
+    window.addEventListener("palette-toast", onToast)
+    return () => window.removeEventListener("palette-toast", onToast)
+  }, [])
+  return React.createElement("div", { className: "palette-local-toasts" },
+    items.map((item) => React.createElement("div", { key: item.id, className: "palette-local-toast" }, item.message))
+  )
+}
+
+function Shell() {
+  return React.createElement(PluginProvider, { value: platform },
+    React.createElement("main", { className: "palette-local-shell" },
+      React.createElement(Plugin, { platform }),
+      React.createElement(Toasts)
+    )
+  )
+}
+
+createRoot(document.getElementById("root")).render(React.createElement(Shell))
+`
+}
+
+function indexHtml(manifest) {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(manifest.name || manifest.id)} - Palette Local</title>
+    <style>
+      * { box-sizing: border-box; }
+      body { margin: 0; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f5f1ea; }
+      .palette-local-shell { min-height: 100vh; }
+      .palette-local-toasts { position: fixed; right: 16px; bottom: 16px; display: grid; gap: 8px; z-index: 50; }
+      .palette-local-toast { background: #1d1b18; color: white; padding: 10px 12px; font-size: 13px; box-shadow: 0 10px 30px rgba(0,0,0,.15); }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/simulator.js"></script>
+  </body>
+</html>`
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (ch) => ({
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+  }[ch]))
+}
+
+async function startFrontend(cwd, devDir, manifest, frontendPort, backendPort) {
+  const entry = manifest.frontend?.entry || "./frontend/src/index.tsx"
+  const absEntry = path.resolve(cwd, entry)
+  if (!fs.existsSync(absEntry)) throw new Error(`frontend entry not found: ${entry}`)
+  const generatedEntry = path.join(devDir, "simulator-entry.jsx")
+  const bundlePath = path.join(devDir, "simulator.js")
+  fs.writeFileSync(generatedEntry, simulatorEntrySource(absEntry, manifest, backendPort))
+
+  const esbuild = loadEsbuild()
+  const ctx = await esbuild.context({
+    entryPoints: [generatedEntry],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: ["es2022"],
+    outfile: bundlePath,
+    jsx: "automatic",
+    loader: { ".ts": "tsx", ".tsx": "tsx", ".js": "jsx", ".jsx": "jsx" },
+    absWorkingDir: cwd,
+    sourcemap: "inline",
+    logLevel: "silent",
+    plugins: [
+      {
+        name: "palette-simulator-watch",
+        setup(build) {
+          build.onEnd((result) => {
+            if (result.errors.length) {
+              console.error("[pltt] simulator bundle failed:")
+              for (const err of result.errors) console.error(`  - ${err.text}`)
+              return
+            }
+            const size = fs.existsSync(bundlePath) ? fs.statSync(bundlePath).size : 0
+            console.log(`[pltt] simulator bundle ready (${size} bytes)`)
+          })
+        },
+      },
+    ],
+  })
+  await ctx.rebuild()
+  await ctx.watch()
+
+  const server = http.createServer((req, res) => {
+    const url = new URL(req.url || "/", `http://127.0.0.1:${frontendPort}`)
+    if (url.pathname === "/simulator.js") {
+      res.writeHead(200, { "Content-Type": "text/javascript; charset=utf-8", "Cache-Control": "no-store" })
+      res.end(fs.readFileSync(bundlePath))
+      return
+    }
+    res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" })
+    res.end(indexHtml(manifest))
+  })
+
+  await new Promise((resolve) => server.listen(frontendPort, "127.0.0.1", resolve))
+  return { server, ctx }
+}
+
+async function startSimulator({ cwd, frontendPort, backendPort }) {
+  const manifest = loadManifest(cwd)
+  const devDir = path.join(cwd, ".palette", "dev")
+  fs.mkdirSync(devDir, { recursive: true })
+
+  const backend = startBackend(cwd, devDir, manifest, backendPort)
+  const frontend = await startFrontend(cwd, devDir, manifest, frontendPort, backendPort)
+
+  console.log("[pltt] running local SDK simulator (no Docker)")
+  console.log(`[pltt] app:     http://localhost:${frontendPort}/`)
+  if (backend) console.log(`[pltt] backend: http://localhost:${backendPort}/api/v1/plugins/${manifest.id}`)
+  console.log("[pltt] use `pltt dev --platform` for full Docker platform parity")
+
+  const stop = async () => {
+    frontend.server.close()
+    await frontend.ctx.dispose()
+    if (backend && !backend.killed) backend.kill("SIGTERM")
+  }
+  process.on("SIGINT", () => stop().then(() => process.exit(0)))
+  process.on("SIGTERM", () => stop().then(() => process.exit(0)))
+
+  await new Promise((resolve) => {
+    const exits = []
+    frontend.server.on("close", () => {
+      exits.push("frontend")
+      resolve()
+    })
+    if (backend) {
+      backend.on("close", (code) => {
+        exits.push("backend")
+        if (code && code !== 0) process.exitCode = code
+        resolve()
+      })
+    }
+  })
+  await stop()
+}
+
+module.exports = { startSimulator }

package/lib/ports.js

@@ -52,10 +52,11 @@ async function findFreePort(preferred, { host = "0.0.0.0", maxAttempts = 100 } =
 async function resolveDevPorts({
   frontend = process.env.PALETTE_FRONTEND_PORT || 3000,
   backend = process.env.PALETTE_BACKEND_PORT || 8000,
+  host = "0.0.0.0",
 } = {}) {
-  const frontendPort = await findFreePort(frontend)
+  const frontendPort = await findFreePort(frontend, { host })
   const backendStart = Number(backend) === frontendPort ? frontendPort + 1 : backend
-  const backendPort = await findFreePort(backendStart)
+  const backendPort = await findFreePort(backendStart, { host })
   return {
     frontend: frontendPort,
     backend: backendPort,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"