@palettelab/cli 0.3.0 → 0.3.1

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
-    "palette": "./bin/palette.js"
+    "pltt": "bin/pltt.js"
   },
   "files": [
     "bin",
     "lib",
     "platform-dev",
     "template-fallback",
+    "!template-fallback/**/__pycache__",
+    "!template-fallback/**/*.pyc",
     "palette.config.example.json",
     "README.md"
   ],
@@ -20,17 +22,16 @@
     "esbuild": "^0.24.0"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
-    "access": "public"
+    "registry": "https://npm.pkg.github.com"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/palette-lab/virtual-organisation.git",
+    "url": "git+https://github.com/palette-lab/virtual-organisation.git",
     "directory": "sdk/cli-npm"
   },
   "license": "MIT",
   "keywords": [
-    "palette",
+    "pltt",
     "plugin",
     "sdk",
     "cli"

package/platform-dev/docker-compose.yml

@@ -1,4 +1,4 @@
-# Bundled docker-compose for `palette dev`. The CLI references this file
+# Bundled docker-compose for `pltt dev`. The CLI references this file
 # from the installed npm package. Third-party developers never edit it.
 #
 # Usage (handled by @palettelab/cli):
@@ -20,6 +20,9 @@ services:
       REDIS_URL: "redis://redis:6379/0"
       JWT_SECRET: "dev-secret-do-not-use-in-prod"
       FRONTEND_URL: "http://localhost:${PALETTE_FRONTEND_PORT:-3000}"
+      BACKEND_BASE_URL: "http://localhost:${PALETTE_BACKEND_PORT:-8000}"
+      STORAGE_BACKEND: "local"
+      LOCAL_STORAGE_DIR: "/srv/storage"
       # Disable optional features that need real credentials
       RAG_ENABLED: "false"
       OPENAI_API_KEY: ""

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

@@ -18,12 +18,18 @@ The PluginContext provides:
 
 from fastapi import Depends
 
-from palette_sdk import PluginRouter, PluginContext, get_plugin_context, SuccessResponse
+from palette_sdk import (
+    PluginRouter,
+    PluginContext,
+    SuccessResponse,
+    get_plugin_context,
+    require_permission,
+)
 
 router = PluginRouter(tags=["my-plugin"])
 
 
-@router.get("/status")
+@router.get("/status", dependencies=[require_permission("tasks:read")])
 async def get_status(ctx: PluginContext = Depends(get_plugin_context)):
     """Example endpoint — returns plugin status."""
     return SuccessResponse(
@@ -36,7 +42,7 @@ async def get_status(ctx: PluginContext = Depends(get_plugin_context)):
     )
 
 
-@router.get("/hello")
+@router.get("/hello", dependencies=[require_permission("tasks:read")])
 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/palette-plugin.json

@@ -1,4 +1,5 @@
 {
+  "manifest_version": "1",
   "id": "my-plugin",
   "name": "My Plugin",
   "version": "1.0.0",
@@ -11,8 +12,30 @@
     "bg": "linear-gradient(135deg, #6366F1, #8B5CF6)",
     "text": "#fff"
   },
+  "sdk": {
+    "frontend": "^0.1.0",
+    "backend": "^0.1.0"
+  },
+  "platform": {
+    "min_version": "0.1.0"
+  },
+  "capabilities": {
+    "frontend": true,
+    "backend": true,
+    "database": false,
+    "webhooks": false,
+    "scheduled_jobs": false,
+    "file_uploads": false,
+    "external_network": []
+  },
+  "public_routes": [],
+  "scheduled_jobs": [],
+  "rate_limit": {
+    "per_minute": 60
+  },
   "frontend": {
-    "entry": "./frontend/src/index.tsx"
+    "entry": "./frontend/src/index.tsx",
+    "sandbox": true
   },
   "backend": {
     "entry": "./backend/api/main.py"

package/template-fallback/pyproject.toml

@@ -5,7 +5,7 @@ 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
+# need to install it locally to run `pltt 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):
 #

package/template-fallback/templates/agent-tool/README.md

@@ -0,0 +1,4 @@
+# Agent-tool plugin
+
+Defines a callable tool (`echo`) under `backend/tools/`. Any agent in the org
+can invoke it once installed.

package/template-fallback/templates/agent-tool/backend/api/main.py

@@ -0,0 +1,14 @@
+"""Agent-tool plugin backend.
+
+This plugin's primary surface is the tool defined in backend/tools/echo.py.
+The router exists so superadmin health checks have something to ping.
+"""
+
+from palette_sdk import PluginRouter
+
+router = PluginRouter(tags=["my-agent-tool"])
+
+
+@router.get("/health")
+async def health() -> dict:
+    return {"status": "ok"}

package/template-fallback/templates/agent-tool/backend/tools/echo.py

@@ -0,0 +1,15 @@
+"""Echo tool — agents can call this to echo a message back."""
+
+from pydantic import BaseModel
+
+
+class EchoInput(BaseModel):
+    message: str
+
+
+class EchoOutput(BaseModel):
+    echoed: str
+
+
+async def run(inp: EchoInput) -> EchoOutput:
+    return EchoOutput(echoed=inp.message)

package/template-fallback/templates/agent-tool/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "my-agent-tool",
+  "version": "1.0.0",
+  "private": true
+}

package/template-fallback/templates/agent-tool/palette-plugin.json

@@ -0,0 +1,29 @@
+{
+  "manifest_version": "1",
+  "id": "my-agent-tool",
+  "name": "My Agent Tool",
+  "version": "1.0.0",
+  "developer": "Your Team",
+  "category": "Agents",
+  "tagline": "A tool an agent can call",
+  "description": "Registers a callable tool that any agent in the org can invoke.",
+  "icon": "Toolbox",
+  "gradient": { "bg": "linear-gradient(135deg, #F59E0B, #EF4444)", "text": "#fff" },
+  "sdk": { "backend": "^0.1.0" },
+  "platform": { "min_version": "0.1.0" },
+  "capabilities": {
+    "frontend": false,
+    "backend": true,
+    "database": false,
+    "webhooks": false,
+    "scheduled_jobs": false,
+    "file_uploads": false,
+    "external_network": []
+  },
+  "backend": { "entry": "./backend/api/main.py" },
+  "public_routes": ["/health"],
+  "tools": [
+    { "name": "echo", "description": "Echo a string back", "entry": "./backend/tools/echo.py" }
+  ],
+  "permissions": ["tasks:read", "tasks:write"]
+}

package/template-fallback/templates/agent-tool/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "my-agent-tool"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = ["palette-sdk", "pydantic"]

package/template-fallback/templates/dashboard/README.md

@@ -0,0 +1,3 @@
+# Dashboard widget plugin
+
+Exposes a backend `/series` endpoint and renders the data as a bar chart.

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

@@ -0,0 +1,23 @@
+"""Dashboard widget backend.
+
+Exposes a single data-source endpoint that the widget renders. Real plugins
+would source this from the org's data rooms or installed data sources.
+"""
+
+from fastapi import Depends
+
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+
+router = PluginRouter(tags=["my-dashboard"])
+
+
+@router.get("/series", dependencies=[require_permission("data_rooms:read")])
+async def series(ctx: PluginContext = Depends(get_plugin_context)) -> list[dict]:
+    """Stub data source — replace with a query against the org's tables."""
+    return [
+        {"label": "Mon", "value": 12},
+        {"label": "Tue", "value": 19},
+        {"label": "Wed", "value": 8},
+        {"label": "Thu", "value": 22},
+        {"label": "Fri", "value": 17},
+    ]

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

@@ -0,0 +1,46 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { usePlatform } from "@palettelab/sdk"
+import type { PluginComponentProps } from "@palettelab/sdk"
+
+type Series = { label: string; value: number }
+
+export default function DashboardWidget(_props: PluginComponentProps) {
+  const { apiFetch } = usePlatform()
+  const [data, setData] = useState<Series[]>([])
+  const [loading, setLoading] = useState(true)
+
+  useEffect(() => {
+    apiFetch("/api/v1/plugins/my-dashboard/series")
+      .then((r) => r.json())
+      .then(setData)
+      .finally(() => setLoading(false))
+  }, [apiFetch])
+
+  const max = Math.max(1, ...data.map((d) => d.value))
+
+  return (
+    <div className="p-6 space-y-4">
+      <h1 className="text-2xl font-bold">Dashboard Widget</h1>
+      {loading ? (
+        <p className="text-muted-foreground">Loading…</p>
+      ) : (
+        <div className="space-y-2">
+          {data.map((d) => (
+            <div key={d.label} className="flex items-center gap-3">
+              <span className="w-24 text-sm">{d.label}</span>
+              <div className="flex-1 h-3 rounded bg-muted">
+                <div
+                  className="h-3 rounded bg-primary"
+                  style={{ width: `${(d.value / max) * 100}%` }}
+                />
+              </div>
+              <span className="text-sm tabular-nums">{d.value}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}

package/template-fallback/templates/dashboard/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "my-dashboard",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@palettelab/sdk": "^0.1.0",
+    "react": "^19.0.0"
+  }
+}

package/template-fallback/templates/dashboard/palette-plugin.json

@@ -0,0 +1,26 @@
+{
+  "manifest_version": "1",
+  "id": "my-dashboard",
+  "name": "My Dashboard Widget",
+  "version": "1.0.0",
+  "developer": "Your Team",
+  "category": "Analytics",
+  "tagline": "A dashboard widget",
+  "description": "A widget that exposes a dashboard data source and renders a chart from it.",
+  "icon": "ChartBar",
+  "gradient": { "bg": "linear-gradient(135deg, #06B6D4, #6366F1)", "text": "#fff" },
+  "sdk": { "frontend": "^0.1.0", "backend": "^0.1.0" },
+  "platform": { "min_version": "0.1.0" },
+  "capabilities": {
+    "frontend": true,
+    "backend": true,
+    "database": false,
+    "webhooks": false,
+    "scheduled_jobs": false,
+    "file_uploads": false,
+    "external_network": []
+  },
+  "frontend": { "entry": "./frontend/src/index.tsx", "sandbox": true },
+  "backend": { "entry": "./backend/api/main.py" },
+  "permissions": ["tasks:read", "data_rooms:read"]
+}

package/template-fallback/templates/dashboard/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "my-dashboard"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = ["palette-sdk"]

package/template-fallback/templates/database/README.md

@@ -0,0 +1,7 @@
+# Database plugin
+
+Org-isolated notes table with row-level security.
+
+```bash
+pltt dev    # applies migrations on container start
+```

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

@@ -0,0 +1,38 @@
+"""Database plugin backend — org-scoped notes."""
+
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy import select
+
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+from models import Note
+
+router = PluginRouter(tags=["my-db-plugin"])
+
+
+class NoteIn(BaseModel):
+    body: str
+
+
+@router.get("/notes", dependencies=[require_permission("resources:read")])
+async def list_notes(ctx: PluginContext = Depends(get_plugin_context)) -> list[dict]:
+    rows = (
+        await ctx.db.execute(
+            select(Note).where(Note.organization_id == ctx.organization_id).order_by(Note.id.desc())
+        )
+    ).scalars().all()
+    return [{"id": r.id, "body": r.body} for r in rows]
+
+
+@router.post("/notes", dependencies=[require_permission("resources:write")])
+async def create_note(
+    body: NoteIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+) -> dict:
+    if not body.body.strip():
+        raise HTTPException(status_code=400, detail="body required")
+    note = Note(organization_id=ctx.organization_id, body=body.body)
+    ctx.db.add(note)
+    await ctx.db.commit()
+    await ctx.db.refresh(note)
+    return {"id": note.id, "body": note.body}

package/template-fallback/templates/database/backend/api/models.py

@@ -0,0 +1,11 @@
+from sqlalchemy import Integer, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from palette_sdk.db import OrgScopedTable
+
+
+class Note(OrgScopedTable):
+    __tablename__ = "notes"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    body: Mapped[str] = mapped_column(Text, nullable=False)

package/template-fallback/templates/database/backend/migrations/001_init.py

@@ -0,0 +1,26 @@
+"""Initial migration — creates notes table with org RLS."""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from palette_sdk.db import ensure_org_rls
+
+revision = "001_init"
+down_revision = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "notes",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("organization_id", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("body", sa.Text(), nullable=False),
+    )
+    op.create_index("ix_notes_organization_id", "notes", ["organization_id"])
+    ensure_org_rls("notes")
+
+
+def downgrade() -> None:
+    op.drop_index("ix_notes_organization_id", table_name="notes")
+    op.drop_table("notes")

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

@@ -0,0 +1,57 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { usePlatform } from "@palettelab/sdk"
+import type { PluginComponentProps } from "@palettelab/sdk"
+
+type Note = { id: number; body: string }
+
+export default function NotesApp(_props: PluginComponentProps) {
+  const { apiFetch, showToast } = usePlatform()
+  const [notes, setNotes] = useState<Note[]>([])
+  const [body, setBody] = useState("")
+
+  async function load() {
+    const r = await apiFetch("/api/v1/plugins/my-db-plugin/notes")
+    setNotes(await r.json())
+  }
+  useEffect(() => {
+    load()
+  }, [])
+
+  async function add() {
+    if (!body.trim()) return
+    const r = await apiFetch("/api/v1/plugins/my-db-plugin/notes", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ body }),
+    })
+    if (r.ok) {
+      setBody("")
+      showToast("Note saved", "success")
+      load()
+    }
+  }
+
+  return (
+    <div className="p-6 space-y-3">
+      <h1 className="text-2xl font-bold">Notes</h1>
+      <div className="flex gap-2">
+        <input
+          className="border rounded px-2 py-1 text-sm flex-1"
+          value={body}
+          onChange={(e) => setBody(e.target.value)}
+          placeholder="New note…"
+        />
+        <button onClick={add} className="px-3 py-1 rounded bg-primary text-primary-foreground text-sm">
+          Add
+        </button>
+      </div>
+      <ul className="space-y-1 text-sm">
+        {notes.map((n) => (
+          <li key={n.id} className="border rounded px-2 py-1">{n.body}</li>
+        ))}
+      </ul>
+    </div>
+  )
+}

package/template-fallback/templates/database/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "my-db-plugin",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": { "@palettelab/sdk": "^0.1.0", "react": "^19.0.0" }
+}

package/template-fallback/templates/database/palette-plugin.json

@@ -0,0 +1,26 @@
+{
+  "manifest_version": "1",
+  "id": "my-db-plugin",
+  "name": "My Database Plugin",
+  "version": "1.0.0",
+  "developer": "Your Team",
+  "category": "Productivity",
+  "tagline": "Org-isolated database CRUD",
+  "description": "Stores notes per organization with RLS-enforced isolation.",
+  "icon": "Database",
+  "gradient": { "bg": "linear-gradient(135deg, #8B5CF6, #EC4899)", "text": "#fff" },
+  "sdk": { "frontend": "^0.1.0", "backend": "^0.1.0" },
+  "platform": { "min_version": "0.1.0" },
+  "capabilities": {
+    "frontend": true,
+    "backend": true,
+    "database": true,
+    "webhooks": false,
+    "scheduled_jobs": false,
+    "file_uploads": false,
+    "external_network": []
+  },
+  "frontend": { "entry": "./frontend/src/index.tsx", "sandbox": true },
+  "backend": { "entry": "./backend/api/main.py" },
+  "permissions": ["resources:read", "resources:write"]
+}

package/template-fallback/templates/database/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "my-db-plugin"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = ["palette-sdk", "sqlalchemy", "alembic"]

package/template-fallback/templates/external-service/README.md

@@ -0,0 +1,4 @@
+# External-service plugin
+
+Calls a third-party API. Notice the manifest declares `capabilities.external_network`
+— the platform enforces this allowlist at runtime.

package/template-fallback/templates/external-service/backend/api/main.py

@@ -0,0 +1,28 @@
+"""External-service plugin backend.
+
+Reads a per-org config token (set when the org installs the plugin) and
+forwards a request to a declared external host. The host MUST be listed
+in capabilities.external_network in the manifest — the platform enforces
+the allowlist at runtime.
+"""
+
+import os
+from fastapi import Depends, HTTPException
+
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+
+router = PluginRouter(tags=["my-external-svc"])
+
+EXTERNAL_HOST = "https://api.example.com"
+
+
+@router.get("/proxy", dependencies=[require_permission("resources:read")])
+async def proxy(ctx: PluginContext = Depends(get_plugin_context)) -> dict:
+    import httpx
+
+    token = os.environ.get("EXAMPLE_API_TOKEN")
+    if not token:
+        raise HTTPException(status_code=500, detail="EXAMPLE_API_TOKEN not configured")
+    async with httpx.AsyncClient() as client:
+        r = await client.get(f"{EXTERNAL_HOST}/v1/ping", headers={"Authorization": f"Bearer {token}"})
+        return {"upstream_status": r.status_code, "body": r.text[:200]}

package/template-fallback/templates/external-service/frontend/src/index.tsx

@@ -0,0 +1,26 @@
+"use client"
+
+import { useState } from "react"
+import { usePlatform } from "@palettelab/sdk"
+import type { PluginComponentProps } from "@palettelab/sdk"
+
+export default function ExternalServiceWidget(_props: PluginComponentProps) {
+  const { apiFetch } = usePlatform()
+  const [result, setResult] = useState<string>("")
+
+  return (
+    <div className="p-6 space-y-3">
+      <h1 className="text-2xl font-bold">External Service</h1>
+      <button
+        className="px-3 py-1.5 rounded bg-primary text-primary-foreground text-sm"
+        onClick={async () => {
+          const r = await apiFetch("/api/v1/plugins/my-external-svc/proxy")
+          setResult(await r.text())
+        }}
+      >
+        Call api.example.com
+      </button>
+      {result && <pre className="text-xs">{result}</pre>}
+    </div>
+  )
+}

package/template-fallback/templates/external-service/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "my-external-svc",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": { "@palettelab/sdk": "^0.1.0", "react": "^19.0.0" }
+}

package/template-fallback/templates/external-service/palette-plugin.json

@@ -0,0 +1,26 @@
+{
+  "manifest_version": "1",
+  "id": "my-external-svc",
+  "name": "My External Service",
+  "version": "1.0.0",
+  "developer": "Your Team",
+  "category": "Integrations",
+  "tagline": "Calls a third-party API",
+  "description": "Demonstrates declared external_network access and a scoped per-org config token.",
+  "icon": "CloudArrowUp",
+  "gradient": { "bg": "linear-gradient(135deg, #10B981, #06B6D4)", "text": "#fff" },
+  "sdk": { "frontend": "^0.1.0", "backend": "^0.1.0" },
+  "platform": { "min_version": "0.1.0" },
+  "capabilities": {
+    "frontend": true,
+    "backend": true,
+    "database": false,
+    "webhooks": false,
+    "scheduled_jobs": false,
+    "file_uploads": false,
+    "external_network": ["api.example.com"]
+  },
+  "frontend": { "entry": "./frontend/src/index.tsx", "sandbox": true },
+  "backend": { "entry": "./backend/api/main.py" },
+  "permissions": ["resources:read"]
+}

package/template-fallback/templates/external-service/pyproject.toml

@@ -0,0 +1,5 @@
+[project]
+name = "my-external-svc"
+version = "1.0.0"
+requires-python = ">=3.12"
+dependencies = ["palette-sdk", "httpx"]

package/template-fallback/templates/frontend-only/README.md

@@ -0,0 +1,7 @@
+# Frontend-only plugin
+
+Pure React widget. Runs inside the platform iframe sandbox.
+
+```bash
+pltt dev
+```

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

@@ -0,0 +1,16 @@
+"use client"
+
+import { usePlatform } from "@palettelab/sdk"
+import type { PluginComponentProps } from "@palettelab/sdk"
+
+export default function FrontendOnlyPlugin(_props: PluginComponentProps) {
+  const { user } = usePlatform()
+  return (
+    <div className="p-6">
+      <h1 className="text-2xl font-bold">Hello, {user.name}</h1>
+      <p className="text-muted-foreground mt-2">
+        This plugin runs entirely in the browser sandbox — no backend.
+      </p>
+    </div>
+  )
+}