@palettelab/cli 0.3.0 → 0.3.2

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,27 +15,38 @@ 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.
 
 ```bash
-npx @palettelab/cli init data-explorer
+pltt init data-explorer
+pltt init crm-dashboard --template dashboard
 cd data-explorer
 ```
 
 Creates `data-explorer/` with a valid `palette-plugin.json`, a frontend React entry, and a FastAPI backend entry.
 
-### `palette dev`
+Templates:
+
+- `dashboard`
+- `agent-tool`
+- `external-service`
+- `database`
+- `frontend-only`
+
+### `pltt dev`
 
 Boot the platform locally with your plugin mounted live. Run this from inside your plugin directory.
 
 ```bash
-npx @palettelab/cli dev
+pltt dev
 ```
 
 Under the hood this runs `docker compose up` with a bundled compose file. It starts:
@@ -53,22 +66,102 @@ Environment variables:
 | `PALETTE_FRONTEND_PORT` | `3000` | Host port for the frontend |
 | `PALETTE_BACKEND_PORT` | `8000` | Host port for the backend |
 
-### `palette build`
+### `pltt doctor`
+
+Check local tooling and common setup problems.
+
+```bash
+pltt doctor
+```
+
+Checks include Node version, Docker availability, platform image availability, port availability, manifest validity, entry files, and frontend bundling.
+
+### `pltt build`
 
 Validate `palette-plugin.json` and check that all declared entry files exist. Run this before pushing a release.
 
 ```bash
-npx @palettelab/cli build
+pltt build
+```
+
+Also lints plugin migrations for unsafe RLS patterns when `database.migrations` is declared.
+
+### `pltt test`
+
+Run local contract checks before publishing.
+
+```bash
+pltt test
+pltt test --json
 ```
 
+Checks include manifest validity, frontend bundling, backend import, route permission gates, route permission declarations, migration linting, frontend sandbox policy, and dependency policy for `package.json` / `pyproject.toml`.
+
+### `pltt package`
+
+Bundle the plugin into `dist/<plugin-id>-<version>.tar.gz` without uploading.
+
+```bash
+pltt package
+pltt package --json
+```
+
+Use this to inspect the publishable artifact before sending it to a Palette environment.
+
+### `pltt publish`
+
+Build and publish the plugin to a Palette appstore environment.
+
+```bash
+pltt publish --env local
+pltt publish --env staging
+pltt publish --env production
+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.
+
+Environment config is read from `./palette.config.json`, `~/.palette/config.json`, or `PALETTE_<ENV>_URL` plus `PALETTE_<ENV>_TOKEN` / `PALETTE_PUBLISH_TOKEN`.
+
+### `pltt status <publish-id>`
+
+Show review status and automated risk report details for a publish.
+
+```bash
+pltt status 123 --env staging
+pltt status --json
+```
+
+If no publish ID is provided, the CLI uses `.palette/last-publish.json` when available.
+
+### `pltt logs [plugin-id]`
+
+Fetch or stream telemetry events for a plugin.
+
+```bash
+pltt logs hello-sdk --env staging
+pltt logs --tail 100
+pltt logs --follow
+pltt logs --json
+```
+
+If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `.palette/last-publish.json`.
+
+## Global Flags
+
+- `--json` emits machine-readable output for `package`, `publish`, `status`, `logs`, and `test`.
+- `--env <name>` selects a configured publish/status/logs environment.
+- `-y, --yes` skips production publish confirmation.
+
 ## What gets shipped
 
 `@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,54 @@ 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}`)
@@ -39,7 +71,8 @@ async function run(args, { cwd }) {
   // 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 (!tryPullImage(DEFAULT_IMAGE)) {
+  if (!ensureImageAvailable(DEFAULT_IMAGE)) {
+    if (frontendWatcher) await frontendWatcher.dispose()
     console.error(
       `\n[palette] could not pull ${DEFAULT_IMAGE}.\n` +
       `          Most common causes:\n` +
@@ -70,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