@palettelab/cli 0.2.0 → 0.3.1

package/README.md

@@ -2,10 +2,12 @@
 
 Developer CLI for building plugins for the Palette platform. Works without any access to the platform source — your plugin repo is the only thing you own.
 
+The installed executable is `pltt`.
+
 ## Requirements
 
 - Node.js 18+
-- Docker Desktop (for `palette dev`)
+- Docker Desktop (for `pltt dev`)
 
 ## Install
 
@@ -13,11 +15,13 @@ You don't have to install globally — use `npx`:
 
 ```bash
 npx @palettelab/cli <command>
+# or after global install
+pltt <command>
 ```
 
 ## Commands
 
-### `palette init <name>`
+### `pltt init <name>`
 
 Scaffold a new plugin directory from the official template.
 
@@ -28,7 +32,7 @@ cd data-explorer
 
 Creates `data-explorer/` with a valid `palette-plugin.json`, a frontend React entry, and a FastAPI backend entry.
 
-### `palette dev`
+### `pltt dev`
 
 Boot the platform locally with your plugin mounted live. Run this from inside your plugin directory.
 
@@ -53,7 +57,7 @@ Environment variables:
 | `PALETTE_FRONTEND_PORT` | `3000` | Host port for the frontend |
 | `PALETTE_BACKEND_PORT` | `8000` | Host port for the backend |
 
-### `palette build`
+### `pltt build`
 
 Validate `palette-plugin.json` and check that all declared entry files exist. Run this before pushing a release.
 
@@ -65,10 +69,10 @@ npx @palettelab/cli build
 
 `@palettelab/cli` itself contains only:
 
-- `bin/palette.js` — entry point
+- `bin/pltt.js` — entry point
 - `lib/` — pure-Node command implementations (no runtime dependencies)
-- `platform-dev/docker-compose.yml` — compose file for `palette dev`
-- `template-fallback/` — offline fallback for `palette init` if git is unavailable
+- `platform-dev/docker-compose.yml` — compose file for `pltt dev`
+- `template-fallback/` — offline fallback for `pltt init` if git is unavailable
 
 ## See also
 

package/bin/{palette.js → pltt.js}

@@ -5,6 +5,6 @@ const path = require("path")
 const cli = require(path.join(__dirname, "..", "lib", "cli.js"))
 
 cli.run(process.argv.slice(2)).catch((err) => {
-  console.error(`[palette] ${err.message || err}`)
+  console.error(`[pltt] ${err.message || err}`)
   process.exit(1)
 })

package/lib/bundler.js

@@ -5,14 +5,14 @@ const fs = require("fs")
 const os = require("os")
 
 // esbuild is declared as a dependency in package.json; installed via npm install.
-// We require it lazily so `palette init` / `palette dev` / `palette build` do
+// We require it lazily so `pltt init` / `pltt dev` / `pltt build` do
 // not pay the load cost.
 function loadEsbuild() {
   try {
     return require("esbuild")
   } catch (err) {
     throw new Error(
-      "esbuild is required for `palette publish`. " +
+      "esbuild is required for `pltt publish`. " +
         "Run `npm install` inside your plugin directory, or install it globally.",
     )
   }
@@ -27,6 +27,7 @@ function loadEsbuild() {
  * Returns the bundle as a Buffer.
  */
 async function bundleFrontend(pluginDir, entry) {
+  pluginDir = path.resolve(pluginDir)
   const esbuild = loadEsbuild()
   const absEntry = path.resolve(pluginDir, entry)
   if (!fs.existsSync(absEntry)) {
@@ -42,7 +43,14 @@ async function bundleFrontend(pluginDir, entry) {
     write: false,
     jsx: "automatic",
     loader: { ".ts": "tsx", ".tsx": "tsx", ".js": "jsx", ".jsx": "jsx" },
-    external: ["react", "react-dom", "react-dom/client", "@palettelab/sdk"],
+    external: [
+      "react",
+      "react-dom",
+      "react-dom/client",
+      "react/jsx-runtime",
+      "react/jsx-dev-runtime",
+      "@palettelab/sdk",
+    ],
     minify: true,
     sourcemap: "inline",
     logLevel: "silent",
@@ -55,6 +63,63 @@ async function bundleFrontend(pluginDir, entry) {
   return Buffer.from(result.outputFiles[0].contents)
 }
 
+async function watchFrontend(pluginDir, entry, outfile) {
+  pluginDir = path.resolve(pluginDir)
+  outfile = path.resolve(outfile)
+  const esbuild = loadEsbuild()
+  const absEntry = path.resolve(pluginDir, entry)
+  if (!fs.existsSync(absEntry)) {
+    throw new Error(`frontend entry not found: ${entry}`)
+  }
+
+  fs.mkdirSync(path.dirname(outfile), { recursive: true })
+
+  const ctx = await esbuild.context({
+    entryPoints: [absEntry],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: ["es2022"],
+    outfile,
+    jsx: "automatic",
+    loader: { ".ts": "tsx", ".tsx": "tsx", ".js": "jsx", ".jsx": "jsx" },
+    external: [
+      "react",
+      "react-dom",
+      "react-dom/client",
+      "react/jsx-runtime",
+      "react/jsx-dev-runtime",
+      "@palettelab/sdk",
+    ],
+    minify: false,
+    sourcemap: "inline",
+    logLevel: "silent",
+    absWorkingDir: pluginDir,
+    plugins: [
+      {
+        name: "palette-dev-watch-logger",
+        setup(build) {
+          build.onEnd((result) => {
+            if (result.errors.length) {
+              console.error("[palette] 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)`)
+          })
+        },
+      },
+    ],
+  })
+
+  await ctx.rebuild()
+  await ctx.watch()
+  return ctx
+}
+
 /**
  * Tar-gzip the `backend/` directory + manifest using the system `tar` command.
  * Returns a Buffer with the gzipped tarball contents.
@@ -64,12 +129,16 @@ async function bundleFrontend(pluginDir, entry) {
  *   ./palette-plugin.json
  */
 async function bundleBackend(pluginDir) {
+  pluginDir = path.resolve(pluginDir)
   const { spawnSync } = require("child_process")
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "palette-bundle-"))
   const outPath = path.join(tmp, "backend.tar.gz")
 
   const includes = []
   if (fs.existsSync(path.join(pluginDir, "backend"))) includes.push("backend")
+  for (const metadataFile of ["package.json", "pyproject.toml"]) {
+    if (fs.existsSync(path.join(pluginDir, metadataFile))) includes.push(metadataFile)
+  }
   includes.push("palette-plugin.json")
 
   const result = spawnSync(
@@ -87,4 +156,4 @@ async function bundleBackend(pluginDir) {
   return buf
 }
 
-module.exports = { bundleFrontend, bundleBackend }
+module.exports = { bundleFrontend, bundleBackend, watchFrontend }

package/lib/cli.js

@@ -1,10 +1,14 @@
 "use strict"
 
-const path = require("path")
 const init = require("./commands/init")
 const dev = require("./commands/dev")
+const doctor = require("./commands/doctor")
 const build = require("./commands/build")
+const test = require("./commands/test")
 const publish = require("./commands/publish")
+const pkg = require("./commands/package")
+const status = require("./commands/status")
+const logs = require("./commands/logs")
 
 const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
@@ -12,30 +16,51 @@ const COMMANDS = {
     run: dev,
     help: "Boot the platform-dev container and mount the current plugin for live development",
   },
+  doctor: {
+    run: doctor,
+    help: "Check local tooling, ports, manifest, Docker, and frontend bundling",
+  },
   build: { run: build, help: "Validate palette-plugin.json and check entry points exist" },
+  test: { run: test, help: "Run local plugin contract checks before publishing" },
+  package: { run: pkg, help: "Bundle the plugin into a tar.gz under dist/ (no upload)" },
   publish: {
     run: publish,
     help: "Bundle and publish the plugin to the platform appstore",
   },
+  status: {
+    run: status,
+    help: "Show review status + risk report for a published version",
+  },
+  logs: {
+    run: logs,
+    help: "Tail telemetry events for a plugin (--follow to stream)",
+  },
 }
 
 function printHelp() {
-  console.log("palette — Palette plugin developer CLI\n")
-  console.log("Usage: palette <command> [options]\n")
+  console.log("pltt — Palette plugin developer CLI\n")
+  console.log("Usage: pltt <command> [options]\n")
   console.log("Commands:")
   for (const [name, { help }] of Object.entries(COMMANDS)) {
     console.log(`  ${name.padEnd(8)}  ${help}`)
   }
+  console.log("\nGlobal flags:")
+  console.log("  --json           Emit machine-readable JSON output (status, logs, package, publish, test)")
   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("  --env <name>     Target environment from ~/.palette/config.json (default: local)")
+  console.log("  -y, --yes        Skip interactive confirmation for production pushes")
+  console.log("\nInit flags:")
+  console.log("  --template <name>  One of: dashboard, agent-tool, external-service, database, frontend-only")
+  console.log("\nLogs flags:")
+  console.log("  --tail <n>       Tail last n events (default 50)")
+  console.log("  -f, --follow     Stream events (poll every 3s)")
   console.log("\nExamples:")
-  console.log("  palette init my-app")
-  console.log("  cd my-app && palette dev")
-  console.log("  palette build")
-  console.log("  palette publish                      # default (local)")
-  console.log("  palette publish --env staging")
-  console.log("  palette publish --env production     # prompts for confirmation")
+  console.log("  pltt init my-app --template database")
+  console.log("  cd my-app && pltt dev")
+  console.log("  pltt package")
+  console.log("  pltt publish --env staging")
+  console.log("  pltt status")
+  console.log("  pltt logs --follow")
 }
 
 async function run(argv) {
@@ -46,7 +71,7 @@ async function run(argv) {
   }
   const entry = COMMANDS[cmd]
   if (!entry) {
-    console.error(`[palette] unknown command: ${cmd}`)
+    console.error(`[pltt] unknown command: ${cmd}`)
     printHelp()
     process.exit(1)
   }

package/lib/commands/build.js

@@ -101,3 +101,5 @@ async function run(args, { cwd }) {
 }
 
 module.exports = run
+module.exports.lintMigrationsDir = lintMigrationsDir
+module.exports.lintMigrationFile = lintMigrationFile

package/lib/commands/dev.js

@@ -3,6 +3,7 @@
 const path = require("path")
 const { spawn, spawnSync } = require("child_process")
 const { loadManifest } = require("../manifest")
+const { watchFrontend } = require("../bundler")
 
 const DEFAULT_IMAGE =
   process.env.PALETTE_DEV_IMAGE || "ghcr.io/palette-lab/platform-dev:latest"
@@ -14,23 +15,75 @@ function ensureDocker() {
   const check = spawnSync("docker", ["info"], { stdio: "ignore" })
   if (check.status !== 0) {
     console.error(
-      "[palette] docker is required for `palette dev`. Install Docker Desktop and make sure it is running.",
+      "[pltt] docker is required for `pltt dev`. Install Docker Desktop and make sure it is running.",
     )
     process.exit(1)
   }
 }
 
+function imageExistsLocally(image) {
+  const res = spawnSync("docker", ["image", "inspect", image], { stdio: "ignore" })
+  return res.status === 0
+}
+
+function tryPullImage(image) {
+  const res = spawnSync("docker", ["pull", image], { stdio: "inherit" })
+  return res.status === 0
+}
+
+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
+  return tryPullImage(image)
+}
+
 async function run(args, { cwd }) {
   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")
 
   ensureDocker()
 
+  let frontendWatcher = null
+  if (manifest.frontend?.entry) {
+    console.log(`[palette] bundling frontend ${frontendEntry} → .palette/dist/frontend.mjs`)
+    try {
+      frontendWatcher = await watchFrontend(cwd, frontendEntry, frontendBundle)
+    } catch (err) {
+      console.error(
+        `[palette] 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(`[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}`)
 
+  // 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)) {
+    if (frontendWatcher) await frontendWatcher.dispose()
+    console.error(
+      `\n[palette] 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`,
+    )
+    process.exit(1)
+  }
+
   const env = {
     ...process.env,
     PALETTE_DEV_IMAGE: DEFAULT_IMAGE,
@@ -50,10 +103,12 @@ async function run(args, { cwd }) {
       ["compose", "-f", COMPOSE_FILE, "-p", projectName, "down"],
       { stdio: "inherit", env },
     )
+    if (frontendWatcher) frontendWatcher.dispose().catch(() => {})
   }
   process.on("SIGINT", stop)
   process.on("SIGTERM", stop)
   await new Promise((resolve) => child.on("close", resolve))
+  if (frontendWatcher) await frontendWatcher.dispose()
 }
 
 module.exports = run

package/lib/commands/doctor.js

@@ -0,0 +1,143 @@
+"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 DEFAULT_IMAGE =
+  process.env.PALETTE_DEV_IMAGE || "ghcr.io/palette-lab/platform-dev:latest"
+const FRONTEND_PORT = Number(process.env.PALETTE_FRONTEND_PORT || "3000")
+const BACKEND_PORT = Number(process.env.PALETTE_BACKEND_PORT || "8000")
+
+function ok(message) {
+  console.log(`OK   ${message}`)
+}
+
+function warn(message, fix) {
+  console.log(`WARN ${message}`)
+  if (fix) console.log(`FIX  ${fix}`)
+}
+
+function fail(message, fix) {
+  console.log(`FAIL ${message}`)
+  if (fix) console.log(`FIX  ${fix}`)
+  return 1
+}
+
+function nodeMajor() {
+  return Number(process.versions.node.split(".")[0])
+}
+
+function dockerRunning() {
+  return spawnSync("docker", ["info"], { stdio: "ignore" }).status === 0
+}
+
+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)
+  if (!fs.existsSync(abs)) {
+    return fail(`${label} entry not found: ${rel}`)
+  }
+  ok(`${label} entry exists: ${rel}`)
+  return 0
+}
+
+async function run(args, { cwd }) {
+  let failures = 0
+
+  if (nodeMajor() >= 18) ok(`Node ${process.versions.node}`)
+  else failures += fail("Node 18+ is required", "Install Node.js 18 or newer.")
+
+  if (dockerRunning()) ok("Docker is running")
+  else failures += fail(
+    "Docker is not running",
+    "Start Docker Desktop, then rerun pltt doctor.",
+  )
+
+  if (imageExistsLocally(DEFAULT_IMAGE)) {
+    ok(`platform image is available locally: ${DEFAULT_IMAGE}`)
+  } else {
+    warn(
+      `platform image is not present locally: ${DEFAULT_IMAGE}`,
+      "pltt dev will try to pull it. If that fails, run docker login ghcr.io or set PALETTE_DEV_IMAGE.",
+    )
+  }
+
+  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`,
+  )
+
+  let manifest
+  try {
+    manifest = loadManifest(cwd)
+    ok("palette-plugin.json found")
+  } catch (err) {
+    failures += fail(
+      err instanceof Error ? err.message : String(err),
+      "Run this command from a Palette plugin root or create one with pltt init <name>.",
+    )
+  }
+
+  if (manifest) {
+    const errors = validateManifest(manifest)
+    if (errors.length) {
+      for (const err of errors) failures += fail(`manifest invalid: ${err}`)
+    } else {
+      ok(`manifest valid: ${manifest.id}@${manifest.version}`)
+    }
+
+    failures += checkEntry(cwd, "frontend", manifest.frontend?.entry)
+    failures += checkEntry(cwd, "backend", manifest.backend?.entry)
+    for (const tool of manifest.tools || []) {
+      failures += checkEntry(cwd, `tool[${tool.name}]`, tool.entry)
+    }
+
+    if (manifest.frontend?.entry) {
+      try {
+        const bundle = await bundleFrontend(cwd, manifest.frontend.entry)
+        ok(`frontend bundles successfully (${bundle.length} bytes)`)
+      } catch (err) {
+        failures += fail(
+          `frontend bundle failed: ${err instanceof Error ? err.message : String(err)}`,
+          "Install plugin dependencies and fix frontend compile errors, then rerun pltt doctor.",
+        )
+      }
+    }
+  }
+
+  if (failures > 0) {
+    console.log(`\n[palette] doctor found ${failures} blocking issue(s).`)
+    process.exit(1)
+  }
+  console.log("\n[palette] doctor passed.")
+}
+
+module.exports = run

package/lib/commands/init.js

@@ -9,6 +9,8 @@ const DEFAULT_TEMPLATE_REPO = "palette-lab/plugin-template"
 const TEMPLATE_REPO = process.env.PALETTE_TEMPLATE_REPO || DEFAULT_TEMPLATE_REPO
 const TEMPLATE_REF = process.env.PALETTE_TEMPLATE_REF || "main"
 
+const KNOWN_TEMPLATES = ["frontend-only", "dashboard", "agent-tool", "external-service", "database"]
+
 function toSlug(name) {
   return name
     .toLowerCase()
@@ -18,7 +20,6 @@ function toSlug(name) {
 }
 
 function fetchTemplate(destDir) {
-  // Try git first — works offline-ish if git is available.
   const git = spawnSync(
     "git",
     ["clone", "--depth=1", "--branch", TEMPLATE_REF, `https://github.com/${TEMPLATE_REPO}.git`, destDir],
@@ -31,10 +32,23 @@ function fetchTemplate(destDir) {
   return false
 }
 
-function copyLocalFallback(destDir) {
+function copyLocalFallback(destDir, template) {
+  if (template) {
+    const tplDir = path.resolve(__dirname, "..", "..", "template-fallback", "templates", template)
+    if (!fs.existsSync(tplDir)) return false
+    fs.cpSync(tplDir, destDir, { recursive: true })
+    return true
+  }
   const fallback = path.resolve(__dirname, "..", "..", "template-fallback")
   if (!fs.existsSync(fallback)) return false
-  fs.cpSync(fallback, destDir, { recursive: true })
+  // Skip the templates/ directory when copying default fallback.
+  fs.cpSync(fallback, destDir, {
+    recursive: true,
+    filter: (src) => {
+      const rel = path.relative(fallback, src)
+      return !rel.startsWith("templates")
+    },
+  })
   return true
 }
 
@@ -47,10 +61,24 @@ function rewriteManifest(destDir, slug, displayName) {
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n")
 }
 
+function getOpt(args, name) {
+  const i = args.indexOf(name)
+  if (i >= 0 && args[i + 1]) return args[i + 1]
+  return null
+}
+
 async function run(args, { cwd }) {
-  const name = args[0]
+  const positional = args.filter((a) => !a.startsWith("-"))
+  const name = positional[0]
   if (!name) {
-    console.error("[palette] usage: palette init <plugin-name>")
+    console.error("[pltt] usage: pltt init <plugin-name> [--template <name>]")
+    console.error(`[palette] 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(", ")}`)
     process.exit(1)
   }
   const slug = toSlug(name)
@@ -63,18 +91,21 @@ async function run(args, { cwd }) {
     process.exit(1)
   }
 
-  console.log(`[palette] creating plugin "${slug}" from ${TEMPLATE_REPO}@${TEMPLATE_REF}`)
+  if (template) {
+    console.log(`[palette] creating plugin "${slug}" from template "${template}"`)
+  } else {
+    console.log(`[palette] creating plugin "${slug}" from ${TEMPLATE_REPO}@${TEMPLATE_REF}`)
+  }
 
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "palette-tpl-"))
-  let ok = fetchTemplate(tmp)
-  if (!ok) {
-    console.warn("[palette] git clone failed, falling back to bundled template")
-    ok = copyLocalFallback(tmp)
+  let ok = false
+  if (!template) {
+    ok = fetchTemplate(tmp)
+    if (!ok) console.warn("[palette] git clone failed, falling back to bundled template")
   }
+  if (!ok) ok = copyLocalFallback(tmp, template)
   if (!ok) {
-    console.error(
-      "[palette] no template available — install git or ship template-fallback/ with the CLI",
-    )
+    console.error("[palette] no template available")
     process.exit(1)
   }
 
@@ -86,6 +117,7 @@ async function run(args, { cwd }) {
   console.log("[palette] next steps:")
   console.log(`  cd ${slug}`)
   console.log(`  npx @palettelab/cli dev`)
+  console.log(`  # or, after global install: pltt dev`)
 }
 
 module.exports = run