@palettelab/cli 0.1.0

package/README.md

@@ -0,0 +1,77 @@
+# @palettelab/cli
+
+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.
+
+## Requirements
+
+- Node.js 18+
+- Docker Desktop (for `palette dev`)
+
+## Install
+
+You don't have to install globally — use `npx`:
+
+```bash
+npx @palettelab/cli <command>
+```
+
+## Commands
+
+### `palette init <name>`
+
+Scaffold a new plugin directory from the official template.
+
+```bash
+npx @palettelab/cli init data-explorer
+cd data-explorer
+```
+
+Creates `data-explorer/` with a valid `palette-plugin.json`, a frontend React entry, and a FastAPI backend entry.
+
+### `palette dev`
+
+Boot the platform locally with your plugin mounted live. Run this from inside your plugin directory.
+
+```bash
+npx @palettelab/cli dev
+```
+
+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/&lt;your-id&gt;
+
+Your plugin directory is mounted into the container at `/plugins/<your-id>`. Edits to your frontend/backend sources hot-reload.
+
+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 build`
+
+Validate `palette-plugin.json` and check that all declared entry files exist. Run this before pushing a release.
+
+```bash
+npx @palettelab/cli build
+```
+
+## What gets shipped
+
+`@palettelab/cli` itself contains only:
+
+- `bin/palette.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
+
+## See also
+
+- `@palettelab/sdk` on GitHub Packages — frontend hooks and types
+- `palette-sdk` (git-installed from [palette-lab/virtual-organisation](https://github.com/palette-lab/virtual-organisation/tree/main/sdk/backend)) — backend `PluginRouter` + `ToolDefinition`
+- [Developer Guide](https://github.com/palette-lab/virtual-organisation/blob/main/sdk/DEVELOPER_GUIDE.md)

package/bin/palette.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+"use strict"
+
+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}`)
+  process.exit(1)
+})

package/lib/bundler.js

@@ -0,0 +1,90 @@
+"use strict"
+
+const path = require("path")
+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
+// not pay the load cost.
+function loadEsbuild() {
+  try {
+    return require("esbuild")
+  } catch (err) {
+    throw new Error(
+      "esbuild is required for `palette publish`. " +
+        "Run `npm install` inside your plugin directory, or install it globally.",
+    )
+  }
+}
+
+/**
+ * Bundle the plugin's frontend entry into a single ESM file.
+ *
+ * Externalises react, react-dom, and @palettelab/sdk so the prod platform's
+ * shared instances are used — avoids duplicate React trees + hook runtime errors.
+ *
+ * Returns the bundle as a Buffer.
+ */
+async function bundleFrontend(pluginDir, entry) {
+  const esbuild = loadEsbuild()
+  const absEntry = path.resolve(pluginDir, entry)
+  if (!fs.existsSync(absEntry)) {
+    throw new Error(`frontend entry not found: ${entry}`)
+  }
+
+  const result = await esbuild.build({
+    entryPoints: [absEntry],
+    bundle: true,
+    format: "esm",
+    platform: "browser",
+    target: ["es2022"],
+    write: false,
+    jsx: "automatic",
+    loader: { ".ts": "tsx", ".tsx": "tsx", ".js": "jsx", ".jsx": "jsx" },
+    external: ["react", "react-dom", "react-dom/client", "@palettelab/sdk"],
+    minify: true,
+    sourcemap: "inline",
+    logLevel: "silent",
+    absWorkingDir: pluginDir,
+  })
+
+  if (!result.outputFiles || result.outputFiles.length === 0) {
+    throw new Error("esbuild produced no output")
+  }
+  return Buffer.from(result.outputFiles[0].contents)
+}
+
+/**
+ * Tar-gzip the `backend/` directory + manifest using the system `tar` command.
+ * Returns a Buffer with the gzipped tarball contents.
+ *
+ * Resulting layout inside the archive:
+ *   ./backend/...
+ *   ./palette-plugin.json
+ */
+async function bundleBackend(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")
+  includes.push("palette-plugin.json")
+
+  const result = spawnSync(
+    "tar",
+    ["-czf", outPath, ...includes.flatMap((f) => ["--exclude=__pycache__", "--exclude=.venv"]), ...includes],
+    { cwd: pluginDir, stdio: "pipe" },
+  )
+  if (result.status !== 0) {
+    throw new Error(
+      `tar failed (exit ${result.status}): ${result.stderr?.toString() || "unknown error"}`,
+    )
+  }
+  const buf = fs.readFileSync(outPath)
+  fs.rmSync(tmp, { recursive: true, force: true })
+  return buf
+}
+
+module.exports = { bundleFrontend, bundleBackend }

package/lib/cli.js

@@ -0,0 +1,50 @@
+"use strict"
+
+const path = require("path")
+const init = require("./commands/init")
+const dev = require("./commands/dev")
+const build = require("./commands/build")
+const publish = require("./commands/publish")
+
+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",
+  },
+  build: { run: build, help: "Validate palette-plugin.json and check entry points exist" },
+  publish: {
+    run: publish,
+    help: "Bundle and publish the plugin to the platform appstore",
+  },
+}
+
+function printHelp() {
+  console.log("palette — Palette plugin developer CLI\n")
+  console.log("Usage: palette <command> [options]\n")
+  console.log("Commands:")
+  for (const [name, { help }] of Object.entries(COMMANDS)) {
+    console.log(`  ${name.padEnd(8)}  ${help}`)
+  }
+  console.log("\nExamples:")
+  console.log("  npx @palettelab/cli init my-app")
+  console.log("  cd my-app && npx @palettelab/cli dev")
+  console.log("  npx @palettelab/cli build")
+}
+
+async function run(argv) {
+  const cmd = argv[0]
+  if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
+    printHelp()
+    return
+  }
+  const entry = COMMANDS[cmd]
+  if (!entry) {
+    console.error(`[palette] unknown command: ${cmd}`)
+    printHelp()
+    process.exit(1)
+  }
+  await entry.run(argv.slice(1), { cwd: process.cwd() })
+}
+
+module.exports = { run }

package/lib/commands/build.js

@@ -0,0 +1,103 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+const { loadManifest, validateManifest } = require("../manifest")
+
+// Strings that must never appear in a plugin migration — they weaken the
+// tenant isolation guarantee that org-scoped apps rely on.
+const BANNED_PATTERNS = [
+  { re: /DROP\s+POLICY/i, reason: "DROP POLICY weakens RLS" },
+  { re: /DISABLE\s+ROW\s+LEVEL\s+SECURITY/i, reason: "DISABLE ROW LEVEL SECURITY removes tenant isolation" },
+  { re: /NO\s+FORCE\s+ROW\s+LEVEL\s+SECURITY/i, reason: "NO FORCE ROW LEVEL SECURITY lets table owners bypass RLS" },
+  { re: /\bpublic\./, reason: "plugin migrations must not reference the platform's public schema" },
+  { re: /\bSET\s+ROLE\b/i, reason: "SET ROLE in migrations escalates out of the plugin sandbox" },
+  { re: /\bALTER\s+ROLE\b/i, reason: "ALTER ROLE is reserved for the platform" },
+]
+
+function lintMigrationFile(absPath) {
+  const issues = []
+  const src = fs.readFileSync(absPath, "utf8")
+
+  for (const { re, reason } of BANNED_PATTERNS) {
+    if (re.test(src)) {
+      issues.push(`${path.basename(absPath)}: ${reason}`)
+    }
+  }
+
+  // Every op.create_table("foo", ...) in the file must have a matching
+  // ensure_org_rls(op, "foo") somewhere in the same file. Caveat: this is a
+  // cheap syntactic check, not a full AST walk. If your table name is dynamic
+  // or your migration is unusual, you can silence the check by adding the
+  // magic comment `# palette:rls-ok` on the same logical migration.
+  if (/#\s*palette:rls-ok\b/.test(src)) return issues
+
+  const tableNames = new Set()
+  const createTableRe = /op\.create_table\(\s*['"]([a-zA-Z_][a-zA-Z0-9_]*)['"]/g
+  let match
+  while ((match = createTableRe.exec(src)) !== null) {
+    tableNames.add(match[1])
+  }
+
+  for (const name of tableNames) {
+    const rlsRe = new RegExp(`ensure_org_rls\\(\\s*op\\s*,\\s*['"]${name}['"]`)
+    if (!rlsRe.test(src)) {
+      issues.push(
+        `${path.basename(absPath)}: create_table("${name}") is missing ensure_org_rls(op, "${name}"). ` +
+          `Inherit from OrgScopedTable and call ensure_org_rls, or mark the migration with # palette:rls-ok if the table is intentionally global.`,
+      )
+    }
+  }
+
+  return issues
+}
+
+function lintMigrationsDir(migrationsDir) {
+  const errors = []
+  const versionsDir = path.join(migrationsDir, "versions")
+  if (!fs.existsSync(versionsDir)) {
+    errors.push(`migrations directory has no versions/ subfolder: ${migrationsDir}`)
+    return errors
+  }
+  for (const entry of fs.readdirSync(versionsDir)) {
+    if (!entry.endsWith(".py")) continue
+    const abs = path.join(versionsDir, entry)
+    errors.push(...lintMigrationFile(abs))
+  }
+  return errors
+}
+
+async function run(args, { cwd }) {
+  const manifest = loadManifest(cwd)
+  const errors = validateManifest(manifest)
+
+  const checkEntry = (label, rel) => {
+    if (!rel) return
+    const abs = path.resolve(cwd, rel)
+    if (!fs.existsSync(abs)) errors.push(`${label} entry not found: ${rel}`)
+  }
+  checkEntry("frontend", manifest.frontend?.entry)
+  checkEntry("backend", manifest.backend?.entry)
+  for (const tool of manifest.tools || []) checkEntry(`tool[${tool.name}]`, tool.entry)
+
+  if (manifest.database) {
+    const migrationsRel = manifest.database.migrations || "./backend/migrations"
+    const migrationsAbs = path.resolve(cwd, migrationsRel)
+    if (!fs.existsSync(migrationsAbs)) {
+      errors.push(`database.migrations directory not found: ${migrationsRel}`)
+    } else if (!fs.existsSync(path.join(migrationsAbs, "env.py"))) {
+      errors.push(`database.migrations directory is missing env.py: ${migrationsRel}`)
+    } else {
+      errors.push(...lintMigrationsDir(migrationsAbs))
+    }
+  }
+
+  if (errors.length) {
+    console.error("[palette] validation failed:")
+    for (const e of errors) console.error(`  - ${e}`)
+    process.exit(1)
+  }
+  console.log(`[palette] ok — ${manifest.id} v${manifest.version}`)
+}
+
+module.exports = run

package/lib/commands/dev.js

@@ -0,0 +1,59 @@
+"use strict"
+
+const path = require("path")
+const { spawn, spawnSync } = require("child_process")
+const { loadManifest } = require("../manifest")
+
+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() {
+  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.",
+    )
+    process.exit(1)
+  }
+}
+
+async function run(args, { cwd }) {
+  const manifest = loadManifest(cwd)
+  const pluginId = manifest.id
+
+  ensureDocker()
+
+  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}`)
+
+  const env = {
+    ...process.env,
+    PALETTE_DEV_IMAGE: DEFAULT_IMAGE,
+    PALETTE_ACTIVE_PLUGIN: pluginId,
+    PALETTE_PLUGIN_DIR: cwd,
+    PALETTE_FRONTEND_PORT: FRONTEND_PORT,
+    PALETTE_BACKEND_PORT: BACKEND_PORT,
+  }
+
+  const projectName = `palette-dev-${pluginId}`
+  const upArgs = ["compose", "-f", COMPOSE_FILE, "-p", projectName, "up", "--remove-orphans"]
+  const child = spawn("docker", upArgs, { stdio: "inherit", env })
+
+  const stop = () => {
+    spawnSync(
+      "docker",
+      ["compose", "-f", COMPOSE_FILE, "-p", projectName, "down"],
+      { stdio: "inherit", env },
+    )
+  }
+  process.on("SIGINT", stop)
+  process.on("SIGTERM", stop)
+  await new Promise((resolve) => child.on("close", resolve))
+}
+
+module.exports = run

package/lib/commands/init.js

@@ -0,0 +1,91 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+const { spawnSync } = require("child_process")
+const os = require("os")
+
+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"
+
+function toSlug(name) {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "")
+}
+
+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],
+    { stdio: "inherit" },
+  )
+  if (git.status === 0) {
+    fs.rmSync(path.join(destDir, ".git"), { recursive: true, force: true })
+    return true
+  }
+  return false
+}
+
+function copyLocalFallback(destDir) {
+  const fallback = path.resolve(__dirname, "..", "..", "template-fallback")
+  if (!fs.existsSync(fallback)) return false
+  fs.cpSync(fallback, destDir, { recursive: true })
+  return true
+}
+
+function rewriteManifest(destDir, slug, displayName) {
+  const manifestPath = path.join(destDir, "palette-plugin.json")
+  if (!fs.existsSync(manifestPath)) return
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"))
+  manifest.id = slug
+  manifest.name = displayName
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n")
+}
+
+async function run(args, { cwd }) {
+  const name = args[0]
+  if (!name) {
+    console.error("[palette] usage: palette init <plugin-name>")
+    process.exit(1)
+  }
+  const slug = toSlug(name)
+  const displayName = name
+    .replace(/[-_]+/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+  const destDir = path.join(cwd, slug)
+  if (fs.existsSync(destDir)) {
+    console.error(`[palette] directory already exists: ${destDir}`)
+    process.exit(1)
+  }
+
+  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)
+  }
+  if (!ok) {
+    console.error(
+      "[palette] no template available — install git or ship template-fallback/ with the CLI",
+    )
+    process.exit(1)
+  }
+
+  fs.cpSync(tmp, destDir, { recursive: true })
+  fs.rmSync(tmp, { recursive: true, force: true })
+  rewriteManifest(destDir, slug, displayName)
+
+  console.log(`[palette] created ${destDir}`)
+  console.log("[palette] next steps:")
+  console.log(`  cd ${slug}`)
+  console.log(`  npx @palettelab/cli dev`)
+}
+
+module.exports = run

package/lib/commands/publish.js

@@ -0,0 +1,114 @@
+"use strict"
+
+const crypto = require("crypto")
+const { loadManifest, validateManifest } = require("../manifest")
+const { bundleFrontend, bundleBackend } = require("../bundler")
+
+const DEFAULT_PLATFORM_URL =
+  process.env.PALETTE_PLATFORM_URL || "https://platform.palette-lab.internal"
+
+function sha256(buf) {
+  return crypto.createHash("sha256").update(buf).digest("hex")
+}
+
+function token() {
+  const t = process.env.PALETTE_PUBLISH_TOKEN
+  if (!t) {
+    console.error(
+      "[palette] PALETTE_PUBLISH_TOKEN is required. Ask a superadmin to mint one for you via\n" +
+        "         POST /api/superadmin/publish-tokens — then `export PALETTE_PUBLISH_TOKEN=<token>`.",
+    )
+    process.exit(1)
+  }
+  return t
+}
+
+async function api(pathname, { method = "GET", body, headers = {} } = {}) {
+  const url = `${DEFAULT_PLATFORM_URL}${pathname}`
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token()}`,
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`${method} ${pathname} → ${res.status}: ${text}`)
+  }
+  const ct = res.headers.get("content-type") || ""
+  return ct.includes("application/json") ? res.json() : res.text()
+}
+
+async function put(url, buf, contentType) {
+  const res = await fetch(url, {
+    method: "PUT",
+    headers: { "Content-Type": contentType },
+    body: buf,
+  })
+  if (!res.ok) {
+    throw new Error(`PUT ${url} → ${res.status}: ${await res.text()}`)
+  }
+}
+
+async function run(args, { cwd }) {
+  const manifest = loadManifest(cwd)
+  const errors = validateManifest(manifest)
+  if (errors.length) {
+    console.error("[palette] manifest invalid:")
+    for (const e of errors) console.error(`  - ${e}`)
+    process.exit(1)
+  }
+
+  console.log(`[palette] publishing ${manifest.id}@${manifest.version}`)
+
+  console.log("[palette]   bundling frontend")
+  const frontend = await bundleFrontend(cwd, manifest.frontend?.entry || "./frontend/src/index.tsx")
+  console.log(`[palette]     ${frontend.length} bytes`)
+
+  console.log("[palette]   bundling backend")
+  const backend = await bundleBackend(cwd)
+  console.log(`[palette]     ${backend.length} bytes`)
+
+  const backendSha = sha256(backend)
+
+  console.log("[palette]   requesting signed URLs")
+  const signed = await api("/api/v1/appstore/sign-upload", {
+    method: "POST",
+    body: {
+      plugin_id: manifest.id,
+      version: manifest.version,
+      bundle_sha256: backendSha,
+    },
+  })
+
+  console.log("[palette]   uploading")
+  await Promise.all([
+    put(signed.frontend_upload_url, frontend, "application/javascript"),
+    put(signed.backend_upload_url, backend, "application/gzip"),
+    put(
+      signed.manifest_upload_url,
+      Buffer.from(JSON.stringify(manifest, null, 2)),
+      "application/json",
+    ),
+  ])
+
+  console.log("[palette]   finalizing")
+  const record = await api("/api/v1/appstore/publish", {
+    method: "POST",
+    body: {
+      plugin_id: manifest.id,
+      version: manifest.version,
+      bundle_path: signed.bundle_path,
+      bundle_sha256: backendSha,
+      manifest,
+    },
+  })
+
+  console.log(`[palette] published ${record.plugin_id}@${record.version}`)
+  console.log(`[palette] live at ${DEFAULT_PLATFORM_URL}${record.catalog_url}`)
+}
+
+module.exports = run

package/lib/manifest.js

@@ -0,0 +1,35 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const MANIFEST_FILE = "palette-plugin.json"
+
+function loadManifest(cwd) {
+  const manifestPath = path.join(cwd, MANIFEST_FILE)
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`no ${MANIFEST_FILE} in ${cwd}`)
+  }
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, "utf8"))
+  } catch (err) {
+    throw new Error(`${MANIFEST_FILE} is not valid JSON: ${err.message}`)
+  }
+}
+
+// Lightweight subset validator — full JSON-schema validation happens at
+// container startup. This covers the fields the CLI itself consumes.
+function validateManifest(m) {
+  const errors = []
+  if (!m.id || typeof m.id !== "string") errors.push("id is required (string)")
+  else if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(m.id))
+    errors.push("id must be lowercase kebab-case")
+  if (!m.name) errors.push("name is required")
+  if (!m.version) errors.push("version is required")
+  else if (!/^\d+\.\d+\.\d+/.test(m.version)) errors.push("version must be semver")
+  if (m.frontend && !m.frontend.entry) errors.push("frontend.entry is required when frontend is set")
+  if (m.backend && !m.backend.entry) errors.push("backend.entry is required when backend is set")
+  return errors
+}
+
+module.exports = { loadManifest, validateManifest }

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@palettelab/cli",
+  "version": "0.1.0",
+  "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
+  "bin": {
+    "palette": "./bin/palette.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "platform-dev",
+    "template-fallback",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "esbuild": "^0.24.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/palette-lab/virtual-organisation.git",
+    "directory": "sdk/cli-npm"
+  },
+  "license": "MIT",
+  "keywords": [
+    "palette",
+    "plugin",
+    "sdk",
+    "cli"
+  ]
+}

package/platform-dev/docker-compose.yml

@@ -0,0 +1,52 @@
+# Bundled docker-compose for `palette dev`. The CLI references this file
+# from the installed npm package. Third-party developers never edit it.
+#
+# Usage (handled by @palettelab/cli):
+#   docker compose -f docker-compose.yml up --no-build
+#
+# The `platform` service mounts the developer's plugin repo at /plugins/<id>.
+
+services:
+  platform:
+    image: ${PALETTE_DEV_IMAGE:-ghcr.io/palette-lab/platform-dev:latest}
+    ports:
+      - "${PALETTE_FRONTEND_PORT:-3000}:3000"
+      - "${PALETTE_BACKEND_PORT:-8000}:8000"
+    environment:
+      PALETTE_DEV_MODE: "1"
+      NEXT_PUBLIC_PALETTE_DEV_MODE: "1"
+      PALETTE_ACTIVE_PLUGIN: "${PALETTE_ACTIVE_PLUGIN:-}"
+      DATABASE_URL: "postgresql+asyncpg://postgres:postgres@postgres:5432/app"
+      REDIS_URL: "redis://redis:6379/0"
+      JWT_SECRET: "dev-secret-do-not-use-in-prod"
+      FRONTEND_URL: "http://localhost:${PALETTE_FRONTEND_PORT:-3000}"
+      # Disable optional features that need real credentials
+      RAG_ENABLED: "false"
+      OPENAI_API_KEY: ""
+    volumes:
+      - "${PALETTE_PLUGIN_DIR}:/plugins/${PALETTE_ACTIVE_PLUGIN}"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+
+  postgres:
+    image: postgres:17-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 10

package/template-fallback/backend/api/main.py

@@ -0,0 +1,42 @@
+"""Plugin backend API.
+
+Define your plugin's API endpoints here. The router will be automatically
+mounted at /api/v1/plugins/{your-plugin-id}/ by the platform.
+
+Available dependencies:
+    from palette_sdk import PluginContext, get_plugin_context
+    ctx: PluginContext = Depends(get_plugin_context)
+
+The PluginContext provides:
+    - ctx.db           — async SQLAlchemy session
+    - ctx.user_id      — authenticated user's UUID
+    - ctx.organization_id — current org ID
+    - ctx.org_role     — user's role (owner/admin/member)
+    - ctx.plugin_id    — this plugin's ID
+    - ctx.permissions  — declared permissions from manifest
+"""
+
+from fastapi import Depends
+
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, SuccessResponse
+
+router = PluginRouter(tags=["my-plugin"])
+
+
+@router.get("/status")
+async def get_status(ctx: PluginContext = Depends(get_plugin_context)):
+    """Example endpoint — returns plugin status."""
+    return SuccessResponse(
+        message="Plugin is running",
+        data={
+            "plugin_id": ctx.plugin_id,
+            "user_id": ctx.user_id,
+            "organization_id": ctx.organization_id,
+        },
+    )
+
+
+@router.get("/hello")
+async def hello(ctx: PluginContext = Depends(get_plugin_context)):
+    """Example endpoint — simple hello."""
+    return {"message": f"Hello from plugin! User: {ctx.user_id}"}

package/template-fallback/backend/tools/example_tool.py

@@ -0,0 +1,44 @@
+"""Example custom agent tool.
+
+To register this tool, add it to your palette-plugin.json:
+{
+  "tools": [{
+    "name": "example_tool",
+    "description": "An example custom tool",
+    "entry": "./backend/tools/example_tool.py"
+  }]
+}
+
+Then assign the tool name to an agent's tools list in the agents section:
+{
+  "agents": [{
+    "name": "My Agent",
+    "tools": ["example_tool"]
+  }]
+}
+"""
+
+from palette_sdk import ToolDefinition
+
+
+class ExampleTool(ToolDefinition):
+    name = "example_tool"
+    description = "An example tool that echoes input back. Replace this with your own logic."
+    input_schema = {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The input query to process",
+            },
+        },
+        "required": ["query"],
+    }
+
+    async def run(self, input_data: dict, context: dict) -> str:
+        query = input_data.get("query", "")
+        return f"ExampleTool received: {query}"
+
+
+# The plugin loader looks for a `tool` attribute or any ToolDefinition subclass
+tool = ExampleTool

package/template-fallback/frontend/src/index.tsx

@@ -0,0 +1,67 @@
+"use client"
+
+/**
+ * Plugin entry component.
+ *
+ * This is the root component that the platform renders when your plugin is opened.
+ * It receives a `platform` prop with access to the authenticated user, API client,
+ * navigation, and toast notifications.
+ *
+ * Available hooks from @palettelab/sdk:
+ *   - usePlatform()       — access user, org, apiFetch, navigate, showToast
+ *   - usePluginTasks()    — CRUD tasks
+ *   - usePluginDataRooms() — browse data rooms and files
+ *   - usePluginChat()     — chat with agents
+ */
+
+import { usePlatform, usePluginTasks } from "@palettelab/sdk"
+import type { PluginComponentProps } from "@palettelab/sdk"
+
+export default function MyPlugin({ platform }: PluginComponentProps) {
+  const { user, showToast } = usePlatform()
+  const { tasks, loading, createTask } = usePluginTasks()
+
+  return (
+    <div className="p-6 space-y-6">
+      <div>
+        <h1 className="text-2xl font-bold">My Plugin</h1>
+        <p className="text-muted-foreground mt-1">
+          Hello, {user.name}! This is your plugin template.
+        </p>
+      </div>
+
+      <div className="rounded-lg border p-4 space-y-3">
+        <h2 className="font-semibold">Quick Start</h2>
+        <ul className="text-sm text-muted-foreground space-y-1 list-disc list-inside">
+          <li>Edit <code>frontend/src/index.tsx</code> to build your UI</li>
+          <li>Edit <code>backend/api/main.py</code> to add API endpoints</li>
+          <li>Use <code>usePlatform()</code> to access the authenticated user and API</li>
+          <li>Use <code>usePluginTasks()</code> to manage tasks</li>
+          <li>Use <code>usePluginDataRooms()</code> to browse files</li>
+        </ul>
+      </div>
+
+      <div className="rounded-lg border p-4">
+        <h2 className="font-semibold mb-2">Tasks ({loading ? "..." : tasks.length})</h2>
+        {!loading && tasks.length === 0 && (
+          <p className="text-sm text-muted-foreground">No tasks yet.</p>
+        )}
+        {tasks.slice(0, 5).map(task => (
+          <div key={task.id} className="flex items-center justify-between py-1 text-sm">
+            <span>{task.title}</span>
+            <span className="text-xs text-muted-foreground">{task.status}</span>
+          </div>
+        ))}
+        <button
+          className="mt-3 px-3 py-1.5 text-sm bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
+          onClick={async () => {
+            await createTask({ title: "Sample task from plugin", priority: "medium" })
+            showToast("Task created!", "success")
+          }}
+        >
+          Create Sample Task
+        </button>
+      </div>
+    </div>
+  )
+}

package/template-fallback/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "palette-plugin-my-plugin",
+  "version": "1.0.0",
+  "private": true,
+  "description": "A Palette platform plugin",
+  "dependencies": {
+    "@palettelab/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^19.0.0"
+  }
+}

package/template-fallback/palette-plugin.json

@@ -0,0 +1,27 @@
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "version": "1.0.0",
+  "developer": "Your Team",
+  "category": "Productivity",
+  "tagline": "A short description of what this plugin does",
+  "description": "A longer description explaining the plugin's features and capabilities.",
+  "icon": "Puzzle",
+  "gradient": {
+    "bg": "linear-gradient(135deg, #6366F1, #8B5CF6)",
+    "text": "#fff"
+  },
+  "frontend": {
+    "entry": "./frontend/src/index.tsx"
+  },
+  "backend": {
+    "entry": "./backend/api/main.py"
+  },
+  "agents": [],
+  "tools": [],
+  "permissions": [
+    "data_rooms:read",
+    "tasks:read",
+    "tasks:write"
+  ]
+}

package/template-fallback/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "palette-plugin-my-plugin"
+version = "1.0.0"
+description = "A Palette platform plugin"
+requires-python = ">=3.12"
+# palette-sdk is installed from the private platform repo. The
+# platform-dev container already has it on PYTHONPATH, so you do not
+# need to install it locally to run `palette dev`. If you want to run
+# `pytest` on the backend outside the container, add this dependency
+# (replace $GH_PAT with your GitHub PAT with read:packages):
+#
+# dependencies = [
+#     "palette-sdk @ git+https://${GH_PAT}@github.com/palette-lab/virtual-organisation.git#subdirectory=sdk/backend",
+# ]
+dependencies = []