@palettelab/cli 0.3.49 → 0.3.51

package/README.md

@@ -21,6 +21,13 @@ npx @palettelab/cli <command>
 pltt <command>
 ```
 
+Check the installed CLI version with:
+
+```bash
+pltt version
+pltt --version
+```
+
 ## Quick Start: Build And Test A Palette App
 
 Use this flow when a developer wants to create an app, run it locally, then test
@@ -667,6 +674,16 @@ pltt login --env staging --url https://sandbox.pltt.ai --token <publish-token>
 pltt dev --sandbox --env staging
 ```
 
+### `pltt version`
+
+Show the installed `pltt` CLI version.
+
+```bash
+pltt version
+pltt version --json
+pltt --version
+```
+
 ### `pltt doctor`
 
 Check local tooling and common setup problems.
@@ -761,9 +778,34 @@ pltt logs --json
 
 If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `.palette/last-publish.json`.
 
+### `pltt services`
+
+Inspect and generate OS-broker service integrations declared through
+`provides` and `consumes` in `palette-plugin.json`.
+
+```bash
+pltt services list --env staging
+pltt services add hr/v1#approvalChain.get --reason "Route approvals through HR"
+pltt services add hr/v1#hierarchy.updated --event --optional
+pltt services pull --env staging
+pltt services scaffold approvalChain.get
+```
+
+Subcommands:
+
+- `list`: fetches `/api/v1/os-broker/catalog` from the selected environment and prints services/events available to the current org. Use `--json` for the raw catalog.
+- `add <namespace/version#name>`: appends a consumed service target to `consumes.services`. Use `--event` or `--type event` for `consumes.events`, `--optional` for non-required dependencies, and `--reason <text>` to record why the dependency is needed.
+- `pull`: reads `consumes.services` and `consumes.events`, fetches JSON Schemas from `/api/v1/os-broker/schemas`, and generates `.palette/types/services.ts` plus `.palette/python/services.py`.
+- `scaffold <method>`: adds a provider method to `provides.services`, creates `schemas/<method>.in.json` and `schemas/<method>.out.json`, and writes a Python handler stub under `broker/`.
+
+Generated TypeScript clients use the SDK's default `palette` client. Generated
+Python clients call `palette_sdk.services(ctx)`, so backend routes still pass
+through Palette's broker permission and install checks.
+
 ## Global Flags
 
-- `--json` emits machine-readable output for `package`, `publish`, `status`, `logs`, and `test`.
+- `--json` emits machine-readable output for `package`, `publish`, `status`, `logs`, `test`, and `version`.
+- `-v, --version` prints the installed `pltt` CLI version.
 - `--env <name>` selects a configured publish/status/logs environment.
 - `-y, --yes` skips production publish confirmation.
 

package/backend-sdk/palette_sdk/__init__.py

@@ -34,7 +34,14 @@ from palette_sdk.permissions import (
     is_known_permission,
     require_permission,
 )
+from palette_sdk import events as events_module  # also exposed as `palette_sdk.events`
 from palette_sdk.events import Event, EventPublisher, subscribe_event
+from palette_sdk.services import (
+    BrokerCallError,
+    ServicesClient,
+    service,
+    services,
+)
 from palette_sdk.config import get_config, require_config
 from palette_sdk.webhooks import sign_webhook, verify_webhook_signature
 from palette_sdk.testing import route_permission_issues
@@ -77,6 +84,11 @@ __all__ = [
     "Event",
     "EventPublisher",
     "subscribe_event",
+    "events_module",
+    "service",
+    "services",
+    "ServicesClient",
+    "BrokerCallError",
     "get_config",
     "require_config",
     "sign_webhook",

package/backend-sdk/palette_sdk/apps.py

@@ -64,3 +64,15 @@ class AppInteropClient:
             json_body=json,
             timeout=timeout,
         )
+
+    async def broker_call(self, target: str, payload: dict[str, Any] | None = None) -> Any:
+        """OS-broker RPC call. Used by the high-level `services(ctx).call(...)`."""
+        if self._adapter is None:
+            raise MissingAppServiceError("Palette OS broker is not available in this runtime")
+        return await self._adapter.broker_call(target, payload or {})
+
+    async def broker_emit(self, target: str, payload: dict[str, Any] | None = None) -> None:
+        """Emit an event through the OS broker."""
+        if self._adapter is None:
+            raise MissingAppServiceError("Palette OS broker is not available in this runtime")
+        await self._adapter.broker_emit(target, payload or {})

package/backend-sdk/palette_sdk/events.py

@@ -44,6 +44,13 @@ _pending: list[tuple[str, Handler]] = []
 
 
 def subscribe_event(topic: str, handler: Handler) -> None:
+    """Subscribe to a topic.
+
+    Accepts either a legacy bare topic (`"task.created"`) or a fully qualified
+    broker target (`"core/v1#task.created"` or `"org/v1#member.updated"`). Both
+    forms are routed to the same core bus; the broker decodes the qualified
+    form on dispatch.
+    """
     _pending.append((topic, handler))
 
 
@@ -54,8 +61,31 @@ def drain_pending() -> list[tuple[str, Handler]]:
     return out
 
 
+def on(topic: str) -> Callable[[Handler], Handler]:
+    """Decorator form of `subscribe_event`.
+
+    Usage::
+
+        @events.on("org/v1#member.updated")
+        async def refresh(event):
+            ...
+    """
+
+    def decorator(fn: Handler) -> Handler:
+        subscribe_event(topic, fn)
+        return fn
+
+    return decorator
+
+
 class EventPublisher:
-    """Publish app-owned events declared in palette-plugin.json provides.events."""
+    """Publish app-owned events declared in palette-plugin.json provides.events.
+
+    Accepts both legacy topics (`task.created`) and qualified broker targets
+    (`org/v1#member.updated`). The adapter (injected by the platform) routes
+    the call through the broker, which checks that the caller is the declared
+    provider and validates the payload against its schema.
+    """
 
     def __init__(self, adapter: Any = None):
         self._adapter = adapter
@@ -64,3 +94,7 @@ class EventPublisher:
         if self._adapter is None:
             raise RuntimeError("Palette event publisher is not available in this runtime")
         await self._adapter.publish(topic, payload or {})
+
+    # Alias: `events.emit(...)` reads more naturally for app-owned events.
+    async def emit(self, topic: str, payload: dict[str, Any] | None = None) -> None:
+        await self.publish(topic, payload)

package/backend-sdk/palette_sdk/manifest.py

@@ -4,9 +4,9 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 
 
 class AgentDefinition(BaseModel):
@@ -99,6 +99,22 @@ class AppServiceRouteSpec(BaseModel):
     description: str = ""
 
 
+class AppServiceMethodSpec(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(validation_alias=AliasChoices("id", "name"))
+    scope: str | None = None
+    version: str | None = None
+    label: str | None = None
+    description: str = ""
+    input_schema: dict[str, Any] | str | None = None
+    input: dict[str, Any] | str | None = None
+    output_schema: dict[str, Any] | str | None = None
+    output: dict[str, Any] | str | None = None
+    route_method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] | None = None
+    route_path: str | None = None
+
+
 class ProvidedAppServiceSpec(BaseModel):
     id: str
     version: str | None = None
@@ -106,6 +122,22 @@ class ProvidedAppServiceSpec(BaseModel):
     description: str = ""
     permissions: list[str] = Field(default_factory=list)
     routes: list[AppServiceRouteSpec] = Field(default_factory=list)
+    methods: list[AppServiceMethodSpec] = Field(default_factory=list)
+
+
+class ProvidedEventSpec(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    id: str = Field(validation_alias=AliasChoices("id", "topic"))
+    version: str | None = None
+    label: str | None = None
+    description: str = ""
+    payload_schema: dict[str, Any] | str | None = None
+    schema_: dict[str, Any] | str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("schema", "schema_"),
+        serialization_alias="schema",
+    )
 
 
 class AppDependencySpec(BaseModel):
@@ -123,9 +155,16 @@ class ServiceDependencySpec(BaseModel):
     provider: str | None = None
 
 
+class ConsumedBrokerTargetSpec(BaseModel):
+    target: str
+    required: bool = True
+    reason: str = ""
+
+
 class ProvidesSpec(BaseModel):
+    namespace: str | None = None
     services: list[ProvidedAppServiceSpec] = Field(default_factory=list)
-    events: list[str] = Field(default_factory=list)
+    events: list[str | ProvidedEventSpec] = Field(default_factory=list)
 
 
 class RequiresSpec(BaseModel):
@@ -134,6 +173,11 @@ class RequiresSpec(BaseModel):
     events: list[str] = Field(default_factory=list)
 
 
+class ConsumesSpec(BaseModel):
+    services: list[str | ConsumedBrokerTargetSpec] = Field(default_factory=list)
+    events: list[str | ConsumedBrokerTargetSpec] = Field(default_factory=list)
+
+
 class PlatformServiceSpec(BaseModel):
     required: bool = False
     billing: Literal["org_wallet", "plugin_owner", "platform"] | None = None
@@ -167,6 +211,7 @@ class PluginManifest(BaseModel):
     connections: list[ConnectionSpec] = Field(default_factory=list)
     provides: ProvidesSpec | None = None
     requires: RequiresSpec | None = None
+    consumes: ConsumesSpec | None = None
     platform_services: list[Literal["llm", "redis", "storage", "vector"]] | dict[str, PlatformServiceSpec] = Field(default_factory=list)
     rating: float = 0.0
     reviews: int = 0

package/backend-sdk/palette_sdk/services.py

@@ -0,0 +1,147 @@
+"""OS-broker service helpers - provider + consumer side.
+
+Provider example::
+
+    from palette_sdk import service, PluginContext
+
+    @service("members.list", scope="org/members.read")
+    async def list_members(ctx: PluginContext, payload: dict) -> dict:
+        return {"items": [...]}
+
+Consumer example::
+
+    from palette_sdk import services
+
+    members = await services(ctx).call("org/v1#members.list", {"team_id": 7})
+
+The decorator captures handlers at import time; the platform's plugin loader
+binds them into the broker registry when the plugin is mounted, prefixing the
+method names with the plugin's declared namespace/version.
+
+The consumer accessor goes through `ctx.apps.broker_call()`, which the
+platform injects with the same signed-internal-call transport used elsewhere.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+ServiceHandler = Callable[[Any, dict[str, Any]], Awaitable[Any]]
+
+
+@dataclass(frozen=True)
+class ServiceDecl:
+    name: str
+    handler: ServiceHandler
+    scope: str | None = None
+    label: str | None = None
+    description: str | None = None
+    input_schema: dict | None = None
+    output_schema: dict | None = None
+
+
+_pending: list[ServiceDecl] = []
+
+
+def service(
+    name: str,
+    *,
+    scope: str | None = None,
+    label: str | None = None,
+    description: str | None = None,
+    input_schema: dict | None = None,
+    output_schema: dict | None = None,
+) -> Callable[[ServiceHandler], ServiceHandler]:
+    """Mark an async function as a broker-callable service method."""
+
+    def decorator(fn: ServiceHandler) -> ServiceHandler:
+        _pending.append(
+            ServiceDecl(
+                name=name,
+                handler=fn,
+                scope=scope,
+                label=label,
+                description=description,
+                input_schema=input_schema,
+                output_schema=output_schema,
+            )
+        )
+        return fn
+
+    return decorator
+
+
+def drain_pending_services() -> list[ServiceDecl]:
+    """Platform-only. Drain and return services registered since last drain."""
+    out = list(_pending)
+    _pending.clear()
+    return out
+
+
+class BrokerCallError(RuntimeError):
+    """Raised when the broker rejects or fails a service call."""
+
+
+class ServicesClient:
+    """Returned by `services(ctx)`. Use `.call(target, payload)` or sugar `.proxy(...)`."""
+
+    def __init__(self, adapter: Any | None):
+        self._adapter = adapter
+
+    async def call(self, target: str, payload: dict[str, Any] | None = None) -> Any:
+        if self._adapter is None:
+            raise BrokerCallError(
+                "Palette OS broker is not available in this runtime. "
+                "This call must run inside a plugin request handler."
+            )
+        return await self._adapter.broker_call(target, payload or {})
+
+    async def emit(self, target: str, payload: dict[str, Any] | None = None) -> None:
+        if self._adapter is None:
+            raise BrokerCallError("Palette OS broker is not available in this runtime.")
+        await self._adapter.broker_emit(target, payload or {})
+
+    def proxy(self, namespace_version: str) -> "_Proxy":
+        return _Proxy(self, namespace_version)
+
+
+class _Proxy:
+    """Dotted-attribute syntax to broker target string."""
+
+    def __init__(self, client: ServicesClient, namespace_version: str, segments: tuple[str, ...] = ()):
+        if "/" not in namespace_version:
+            raise ValueError("namespace_version must look like 'org/v1'")
+        self._client = client
+        self._ns = namespace_version
+        self._segments = segments
+
+    def __getattr__(self, item: str) -> "_Proxy":
+        return _Proxy(self._client, self._ns, self._segments + (item,))
+
+    async def __call__(self, payload: dict[str, Any] | None = None) -> Any:
+        if not self._segments:
+            raise BrokerCallError("missing method name on proxy call")
+        method = ".".join(self._segments)
+        return await self._client.call(f"{self._ns}#{method}", payload)
+
+
+def services(ctx_or_adapter: Any) -> ServicesClient:
+    """Resolve a `ServicesClient` from either a `PluginContext` or an adapter."""
+    if ctx_or_adapter is None:
+        return ServicesClient(None)
+    apps = getattr(ctx_or_adapter, "apps", None)
+    if apps is not None and hasattr(apps, "broker_call"):
+        return ServicesClient(apps)
+    return ServicesClient(ctx_or_adapter)
+
+
+__all__ = [
+    "BrokerCallError",
+    "ServiceDecl",
+    "ServicesClient",
+    "drain_pending_services",
+    "service",
+    "services",
+]

package/docs/python-backend-sdk.md

@@ -114,7 +114,7 @@ Available context values:
 | `ctx.data_rooms` | Backend Data Room client |
 | `ctx.connections` | Palette-managed third-party connection client |
 | `ctx.members` | Current organisation member client |
-| `ctx.apps` | Governed app-to-app calls through declared `requires` contracts |
+| `ctx.apps` / `services(ctx)` | Governed app-to-app calls through declared `consumes` contracts |
 | `ctx.events` | Publish event topics declared in `provides.events` |
 | `ctx.redis` | Plugin/org-scoped Redis-style service when `platform_services` includes `redis` |
 | `ctx.vector` | Plugin/org-scoped vector service when `platform_services` includes `vector` |
@@ -141,13 +141,15 @@ These are the public Python helpers exported by `palette_sdk`.
 | `KNOWN_PERMISSIONS`, `is_known_permission(...)` | Permission vocabulary checks for manifests/tools |
 | `DataRoomsClient`, `ctx.data_rooms` | Backend Data Room room/folder/file helpers |
 | `OrganizationMembersClient`, `ctx.members` | Current-organization member lookup, invite, and role helpers |
-| `AppInteropClient`, `ctx.apps` | Call required apps/services without direct database access |
+| `PluginConnectionsClient`, `ConnectionStatus`, `MissingConnectionError`, `ctx.connections` | Third-party connection status and token helpers |
+| `AppInteropClient`, `AppServiceClient`, `MissingAppServiceError`, `ctx.apps` | Call required apps/services without direct database access |
+| `service(...)`, `services(ctx)`, `ServicesClient`, `BrokerCallError` | Provide and consume OS-broker service methods/events |
 | `OrgRepository`, `ctx.repo(Model)` | Org-safe convenience CRUD for app-owned models |
 | `PluginBase`, `OrgScopedTable` | SQLAlchemy declarative bases for plugin-owned tables |
 | `ensure_org_rls(op, table)` | Alembic helper that enables org row-level security |
 | `plugin_safe_id(...)`, `plugin_schema(...)`, `plugin_table_prefix(...)` | Manifest id to database-safe naming helpers |
 | `get_config(ctx, key)`, `require_config(ctx, key)` | Functional form of config reads when not using `ctx.config_value(...)` |
-| `LocalRedisService`, `LocalVectorService` | Local `pltt dev` service emulators and test fakes |
+| `LocalRedisService`, `LocalVectorService`, `LocalStorageService` | Local `pltt dev` service emulators and test fakes |
 | `PlatformServiceUnavailable`, `UnavailablePlatformService` | Clear errors when an undeclared platform service is used |
 | `LifecycleHooks` | Install/update/enable/disable/uninstall callbacks |
 | `Event`, `EventPublisher`, `subscribe_event(...)` | In-process event subscriptions and declared app event publishing |
@@ -690,57 +692,84 @@ token = await ctx.connections.access_token("google_calendar")
 
 ## 11. App-To-App Services
 
-Apps can expose governed services and depend on services from other installed
-apps. Declare provider capabilities with `provides`:
+Apps can expose governed broker services and events, then consume them from
+other installed apps without knowing another app's URL.
+
+Provider apps declare a namespace and callable methods with `provides`:
 
 ```json
 {
   "provides": {
+    "namespace": "hr",
     "services": [
       {
-        "id": "org.hierarchy",
-        "version": "1.0.0",
-        "routes": [
-          { "method": "GET", "path": "/hierarchy/approval-chain/{user_id}" }
+        "id": "hr.directory",
+        "methods": [
+          { "name": "approvalChain.get", "input_schema": "schemas/approval-chain.input.json" }
         ]
       }
     ],
-    "events": ["hierarchy.updated"]
+    "events": [{ "topic": "hierarchy.updated" }]
   }
 }
 ```
 
-Consumers declare dependencies with `requires`:
+Expose the handler with `@service`:
+
+```python
+from palette_sdk import PluginContext, service
+
+@service("approvalChain.get")
+async def approval_chain(ctx: PluginContext, payload: dict) -> dict:
+    return {"approvers": [{"user_id": ctx.user_id, "step": 1}]}
+```
+
+Consumers declare qualified targets with `consumes`:
 
 ```json
 {
-  "requires": {
+  "consumes": {
     "services": [
-      { "id": "org.hierarchy", "version": "^1.0.0", "reason": "Approval routing" }
+      {
+        "target": "hr/v1#approvalChain.get",
+        "required": true,
+        "reason": "Route leave approvals through the HR hierarchy"
+      }
+    ],
+    "events": [
+      { "target": "hr/v1#hierarchy.updated", "required": false }
     ]
   }
 }
 ```
 
-Then call through `ctx.apps`; never read another app's database directly. If
-the same app emits `leave.requested`, declare that topic under its own
-`provides.events` first:
+The CLI can update the manifest and generate typed clients for those targets:
 
-```python
-chain = await ctx.apps.service("org.hierarchy").get(f"/hierarchy/approval-chain/{ctx.user_id}")
-await ctx.events.publish("leave.requested", {"next_approver_id": chain["next_approver_id"]})
+```bash
+pltt services add hr/v1#approvalChain.get --reason "Route leave approvals through HR"
+pltt services add hr/v1#hierarchy.updated --event --optional
+pltt services pull --env staging
 ```
 
-Local mocks live in `.palette/app-services.local.json`:
+`pltt services pull` writes `.palette/types/services.ts` for frontend code and
+`.palette/python/services.py` for backend code from the schemas returned by the
+selected Palette environment.
 
-```json
-{
-  "org.hierarchy GET /hierarchy/approval-chain/dev-user": {
-    "next_approver_id": "manager-1"
-  }
-}
+Then call through the OS broker; never read another app's database directly.
+If the same app emits `leave.requested`, declare that topic under its own
+`provides.events` first and emit with `ctx.events.emit`:
+
+```python
+from palette_sdk import services
+
+chain = await services(ctx).call("hr/v1#approvalChain.get", {"user_id": ctx.user_id})
+await ctx.events.emit("leave/v1#leave.requested", {"approval_chain": chain})
 ```
 
+At install time, Palette checks required `consumes` targets and can show the
+provider apps that must also be installed. The org-level grant is saved on the
+install and the broker checks it on every call, emit, or event stream.
+
 App storage is separate from Data Rooms. Use `ctx.storage` and `palette.storage` for app-owned files that go directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` or `palette.dataRooms` only when the file should be visible and governed as a Data Room document.
 
 Palette scopes storage the same way. Files written through `ctx.storage` or the
@@ -887,7 +916,7 @@ point = ctx.vector.scoped_point(
 await client.upsert(collection_name=collection, points=[point])
 ```
 
-## 10. Lifecycle Hooks
+## 12. Lifecycle Hooks
 
 Lifecycle hooks let an app seed defaults or clean up app-owned data when the
 platform installs, updates, enables, disables, or uninstalls the app.
@@ -909,7 +938,7 @@ async def on_enable(ctx: PluginContext):
     ctx.logger.info("finance tools enabled for org %s", ctx.organization_id)
 ```
 
-## 11. Calling Backend APIs From Frontend
+## 13. Calling Backend APIs From Frontend
 
 Frontend code should call backend routes through the platform API helper, not by
 hardcoding backend origins.
@@ -926,7 +955,7 @@ async function loadInvoices() {
 During `pltt dev`, the simulator routes this to the local backend. In hosted
 sandbox or OS runtime, it goes through the real platform shell and auth context.
 
-## 12. Local Development
+## 14. Local Development
 
 Create and run an app:
 
@@ -948,7 +977,7 @@ The CLI checks manifest shape, SDK compatibility, frontend bundling, backend
 imports, backend route permission gates, declared permissions, migration safety,
 package dependency policy, and backend package size.
 
-## 13. Test In Real Palette OS Without Docker
+## 15. Test In Real Palette OS Without Docker
 
 Configure the hosted sandbox once:
 
@@ -978,7 +1007,7 @@ APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true
 
 That lets passing preview publishes become active without manual approval.
 
-## 14. Common Mistakes
+## 16. Common Mistakes
 
 - Do not import `@palettelab/sdk` from Python. That package is for frontend
   JavaScript/React code only.
@@ -993,7 +1022,7 @@ That lets passing preview publishes become active without manual approval.
 - Use hosted sandbox when you need real Data Rooms, login, organization,
   install, logs, and OS behavior without Docker.
 
-## 15. Complete Minimal Example
+## 17. Complete Minimal Example
 
 `backend/api/main.py`:
 

package/lib/bundler.js

@@ -4,6 +4,7 @@ const path = require("path")
 const fs = require("fs")
 const os = require("os")
 const { generatePaletteAppEntry } = require("./app-router")
+const { appendCssExport, scopePluginCss } = require("./css-scope")
 
 const NEXT_CONFIG_NAMES = [
   "frontend/next.config.ts",
@@ -246,6 +247,25 @@ function currentSearchParams() {
   return new URLSearchParams(window.location.search)
 }
 
+function preserveCurrentPreviewParams(path, pluginId) {
+  if (typeof window === "undefined" || !pluginId || /^https?:\\/\\//i.test(path)) return path
+
+  const currentParams = new URLSearchParams(window.location.search)
+  const previewPublishId = currentParams.get("preview_publish_id")
+  const previewToken = currentParams.get("preview_token")
+  if (!previewPublishId || !previewToken) return path
+
+  const [beforeHash, hash = ""] = path.split("#", 2)
+  const [pathname, query = ""] = beforeHash.split("?", 2)
+  if (pathname !== "/apps/" + pluginId && !pathname.startsWith("/apps/" + pluginId + "/")) return path
+
+  const params = new URLSearchParams(query)
+  params.set("preview_publish_id", previewPublishId)
+  params.set("preview_token", previewToken)
+  const serialized = params.toString()
+  return pathname + (serialized ? "?" + serialized : "") + (hash ? "#" + hash : "")
+}
+
 function renderRoute(route) {
   const page = createElement(route.page)
   return (route.layouts || []).reduceRight((children, Layout) => createElement(Layout, null, children), page)
@@ -283,8 +303,9 @@ export function PaletteAppRouter({ routes, notFound: NotFound }) {
     const osPath = inPalettePath && platform.pluginId
       ? "/apps/" + platform.pluginId + (pathname === "/" ? "" : pathname) + (queryPart ? "?" + queryPart : "")
       : next
-    if (replace && typeof window !== "undefined") window.history.replaceState(null, "", osPath)
-    else platform.navigate(osPath)
+    const preservedOsPath = preserveCurrentPreviewParams(osPath, platform.pluginId)
+    if (replace && typeof window !== "undefined") window.history.replaceState(null, "", preservedOsPath)
+    else platform.navigate(preservedOsPath)
   }, [platform])
   const state = useMemo(() => ({
     pathname: location.pathname,
@@ -382,6 +403,43 @@ function mergePlugins(...pluginGroups) {
   return pluginGroups.flat().filter(Boolean)
 }
 
+function pluginCssScopeId(frontend = {}) {
+  return frontend.pluginId || frontend.id || "plugin"
+}
+
+function cssOutputForJs(outfile) {
+  const ext = path.extname(outfile)
+  return `${outfile.slice(0, outfile.length - ext.length)}.css`
+}
+
+function outputPathFromMetafile(result, suffix) {
+  const outputs = Object.keys(result.metafile?.outputs || {})
+  return outputs.find((output) => output.endsWith(suffix)) || null
+}
+
+function writeScopedCssExport({ jsPath, cssPath, pluginId, deleteCss = true }) {
+  if (!cssPath || !fs.existsSync(cssPath)) return
+  const css = fs.readFileSync(cssPath, "utf8")
+  const scopedCss = scopePluginCss(css, pluginId)
+  if (scopedCss.trim()) {
+    const js = fs.readFileSync(jsPath, "utf8")
+    fs.writeFileSync(jsPath, appendCssExport(js, scopedCss))
+  }
+  if (deleteCss) fs.rmSync(cssPath, { force: true })
+}
+
+function bundleOutputsToFrontendBuffer(result, pluginId) {
+  const outputs = result.outputFiles || []
+  const jsOutput = outputs.find((file) => /\.(mjs|js)$/.test(file.path))
+  if (!jsOutput) throw new Error("esbuild produced no JavaScript output")
+  const css = outputs
+    .filter((file) => file.path.endsWith(".css"))
+    .map((file) => file.text)
+    .join("\n")
+  const js = jsOutput.text
+  return Buffer.from(appendCssExport(js, scopePluginCss(css, pluginId)))
+}
+
 /**
  * Bundle the plugin's frontend entry into a single ESM file.
  *
@@ -393,8 +451,8 @@ function mergePlugins(...pluginGroups) {
 async function bundleFrontend(pluginDir, entry, frontend = {}) {
   pluginDir = path.resolve(pluginDir)
   const esbuild = loadEsbuild()
-  const tmp = isPaletteApp(frontend) ? fs.mkdtempSync(path.join(os.tmpdir(), "palette-app-entry-")) : null
-  const bundleEntry = tmp
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "palette-frontend-"))
+  const bundleEntry = isPaletteApp(frontend)
     ? generatePaletteAppEntry(pluginDir, entry || "./frontend/app", path.join(tmp, "entry.tsx"))
     : entry
   const absEntry = path.resolve(pluginDir, bundleEntry)
@@ -407,6 +465,7 @@ async function bundleFrontend(pluginDir, entry, frontend = {}) {
     const result = await esbuild.build({
       entryPoints: [absEntry],
       bundle: true,
+      outfile: path.join(tmp, "frontend.mjs"),
       format: "esm",
       platform: "browser",
       target: ["es2022"],
@@ -432,9 +491,9 @@ async function bundleFrontend(pluginDir, entry, frontend = {}) {
     if (!result.outputFiles || result.outputFiles.length === 0) {
       throw new Error("esbuild produced no output")
     }
-    return Buffer.from(result.outputFiles[0].contents)
+    return bundleOutputsToFrontendBuffer(result, pluginCssScopeId(frontend))
   } finally {
-    if (tmp) fs.rmSync(tmp, { recursive: true, force: true })
+    fs.rmSync(tmp, { recursive: true, force: true })
   }
 }
 
@@ -473,6 +532,7 @@ async function watchFrontend(pluginDir, entry, outfile, frontend = {}) {
     ],
     minify: false,
     sourcemap: "inline",
+    metafile: true,
     logLevel: "silent",
     absWorkingDir: pluginDir,
     plugins: [
@@ -488,6 +548,12 @@ async function watchFrontend(pluginDir, entry, outfile, frontend = {}) {
               }
               return
             }
+            const cssPath = outputPathFromMetafile(result, ".css") || cssOutputForJs(outfile)
+            writeScopedCssExport({
+              jsPath: outfile,
+              cssPath,
+              pluginId: pluginCssScopeId(frontend),
+            })
             const size = fs.existsSync(outfile) ? fs.statSync(outfile).size : 0
             console.log(`[pltt] frontend bundle ready (${size} bytes)`)
           })

package/lib/cli.js

@@ -12,6 +12,7 @@ const status = require("./commands/status")
 const logs = require("./commands/logs")
 const secrets = require("./commands/secrets")
 const services = require("./commands/services")
+const version = require("./commands/version")
 
 const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
@@ -55,6 +56,7 @@ const COMMANDS = {
     run: services,
     help: "Inspect / pull / scaffold OS-broker services (list, pull, scaffold)",
   },
+  version: { run: version, help: "Show the installed pltt CLI version" },
 }
 
 function printHelp() {
@@ -65,7 +67,8 @@ function printHelp() {
     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("  --json           Emit machine-readable JSON output (status, logs, package, publish, test, version)")
+  console.log("  -v, --version    Show the installed pltt CLI version")
   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")
@@ -108,6 +111,10 @@ function printHelp() {
 
 async function run(argv) {
   const cmd = argv[0]
+  if (cmd === "--version" || cmd === "-v") {
+    version(argv.slice(1))
+    return
+  }
   if (!cmd || cmd === "--help" || cmd === "-h" || cmd === "help") {
     printHelp()
     return

package/lib/commands/dev.js

@@ -172,7 +172,10 @@ async function run(args, { cwd }) {
   if (manifest.frontend?.entry) {
     console.log(`[pltt] bundling frontend ${frontendEntry} → .palette/dist/frontend.mjs`)
     try {
-      frontendWatcher = await watchFrontend(cwd, frontendEntry, frontendBundle, manifest.frontend)
+      frontendWatcher = await watchFrontend(cwd, frontendEntry, frontendBundle, {
+        ...manifest.frontend,
+        pluginId,
+      })
     } catch (err) {
       console.error(
         `[pltt] could not start frontend bundler: ${

package/lib/commands/doctor.js

@@ -143,7 +143,10 @@ async function run(args, { cwd }) {
 
     if (manifest.frontend?.entry) {
       try {
-        const bundle = await bundleFrontend(cwd, manifest.frontend.entry, manifest.frontend)
+        const bundle = await bundleFrontend(cwd, manifest.frontend.entry, {
+          ...manifest.frontend,
+          pluginId: manifest.id,
+        })
         ok(`frontend bundles successfully (${bundle.length} bytes)`)
       } catch (err) {
         failures += fail(

package/lib/commands/package.js

@@ -43,7 +43,10 @@ async function run(argv, { cwd }) {
   fs.mkdirSync(distDir, { recursive: true })
 
   const frontend = manifest.frontend
-    ? await bundleFrontend(cwd, manifest.frontend.entry || "./frontend/src/index.tsx", manifest.frontend)
+    ? await bundleFrontend(cwd, manifest.frontend.entry || "./frontend/src/index.tsx", {
+        ...manifest.frontend,
+        pluginId: manifest.id,
+      })
     : null
   const backend = manifest.backend ? await bundleBackend(cwd) : null
 

package/lib/commands/publish.js

@@ -387,7 +387,10 @@ async function run(argv, { cwd }) {
   let frontend = null
   if (manifest.frontend?.entry) {
     log("[pltt]   bundling frontend")
-    frontend = await bundleFrontend(cwd, manifest.frontend.entry, manifest.frontend)
+    frontend = await bundleFrontend(cwd, manifest.frontend.entry, {
+      ...manifest.frontend,
+      pluginId: manifest.id,
+    })
     log(`[pltt]     ${frontend.length} bytes`)
   } else {
     log("[pltt]   no frontend declared")

package/lib/commands/test.js

@@ -758,14 +758,20 @@ async function run(args, { cwd }) {
   }
   if ((manifest.permissions || []).length) out.ok("declared permissions are known")
 
-  if (manifest.provides || manifest.requires) {
+  if (manifest.provides || manifest.requires || manifest.consumes) {
     const providedServices = manifest.provides?.services?.map((item) => item.id).filter(Boolean) || []
     const requiredServices = manifest.requires?.services?.map((item) => item.id).filter(Boolean) || []
     const requiredApps = manifest.requires?.apps?.map((item) => item.id).filter(Boolean) || []
+    const consumedServices =
+      manifest.consumes?.services?.map((item) => (typeof item === "string" ? item : item.target)).filter(Boolean) || []
+    const consumedEvents =
+      manifest.consumes?.events?.map((item) => (typeof item === "string" ? item : item.target)).filter(Boolean) || []
     out.ok("app-to-app contracts are valid", {
       provides_services: providedServices,
       requires_services: requiredServices,
       requires_apps: requiredApps,
+      consumes_services: consumedServices,
+      consumes_events: consumedEvents,
     })
   }
 
@@ -787,7 +793,10 @@ async function run(args, { cwd }) {
 
   if (manifest.frontend?.entry) {
     try {
-      const frontend = await bundleFrontend(cwd, manifest.frontend.entry, manifest.frontend)
+      const frontend = await bundleFrontend(cwd, manifest.frontend.entry, {
+        ...manifest.frontend,
+        pluginId: manifest.id,
+      })
       out.ok(`frontend bundles successfully (${frontend.length} bytes)`, { bytes: frontend.length })
       failures += checkBundleSize("frontend", frontend.length, out)
       failures += checkFrontendSecretLeaks(cwd, frontend, manifest, out)

package/lib/commands/version.js

@@ -0,0 +1,20 @@
+"use strict"
+
+const pkg = require("../../package.json")
+
+function version(args = []) {
+  if (args.includes("--json")) {
+    console.log(
+      JSON.stringify({
+        name: pkg.name,
+        bin: "pltt",
+        version: pkg.version,
+      }),
+    )
+    return
+  }
+
+  console.log(`pltt ${pkg.version}`)
+}
+
+module.exports = version

package/lib/css-scope.js

@@ -0,0 +1,124 @@
+"use strict"
+
+const postcss = require("postcss")
+const selectorParser = require("postcss-selector-parser")
+
+function cssString(value) {
+  return String(value).replace(/\\/g, "\\\\").replace(/"/g, '\\"')
+}
+
+function cssIdentifier(value) {
+  return String(value).replace(/[^a-zA-Z0-9_-]/g, "-")
+}
+
+function rootSelector(pluginId) {
+  return `[data-palette-plugin-root="${cssString(pluginId)}"]`
+}
+
+function isKeyframesRule(rule) {
+  let parent = rule.parent
+  while (parent) {
+    if (parent.type === "atrule" && /keyframes$/i.test(parent.name)) return true
+    parent = parent.parent
+  }
+  return false
+}
+
+function isRootLike(node) {
+  return (
+    (node.type === "tag" && /^(html|body)$/i.test(node.value)) ||
+    (node.type === "pseudo" && node.value === ":root")
+  )
+}
+
+function removeLeadingCombinators(selector) {
+  while (selector.nodes[0]?.type === "combinator") {
+    selector.nodes[0].remove()
+  }
+}
+
+function replaceRootLikeSelectors(selector, rootNode) {
+  let replaced = false
+  selector.walk((node) => {
+    if (!isRootLike(node)) return
+    node.replaceWith(rootNode.clone())
+    replaced = true
+  })
+  return replaced
+}
+
+function prefixSelector(selector, rootNode) {
+  if (!selector.nodes.length) return
+  if (replaceRootLikeSelectors(selector, rootNode)) {
+    removeLeadingCombinators(selector)
+    return
+  }
+  selector.prepend(selectorParser.combinator({ value: " " }))
+  selector.prepend(rootNode.clone())
+}
+
+function scopeSelectors(selector, pluginId) {
+  const rootNode = selectorParser.attribute({
+    attribute: "data-palette-plugin-root",
+    operator: "=",
+    quoteMark: '"',
+    value: String(pluginId),
+  })
+
+  return selectorParser((selectors) => {
+    selectors.each((sel) => prefixSelector(sel, rootNode))
+  }).processSync(selector)
+}
+
+function renameKeyframes(root, pluginId) {
+  const prefix = `palette-${cssIdentifier(pluginId)}-`
+  const names = new Map()
+
+  root.walkAtRules((atRule) => {
+    if (!/keyframes$/i.test(atRule.name)) return
+    const current = atRule.params.trim()
+    if (!current || /^["']/.test(current)) return
+    const next = `${prefix}${current}`
+    names.set(current, next)
+    atRule.params = next
+  })
+
+  if (names.size === 0) return
+
+  const namePattern = new RegExp(
+    `\\b(${Array.from(names.keys()).map((name) => name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})\\b`,
+    "g",
+  )
+  root.walkDecls((decl) => {
+    if (!/^animation(-name)?$/i.test(decl.prop)) return
+    decl.value = decl.value.replace(namePattern, (match) => names.get(match) || match)
+  })
+}
+
+function scopePluginCss(css, pluginId) {
+  if (!css || !String(css).trim()) return ""
+  const root = postcss.parse(css)
+
+  renameKeyframes(root, pluginId)
+  root.walkRules((rule) => {
+    if (isKeyframesRule(rule)) return
+    rule.selector = scopeSelectors(rule.selector, pluginId)
+  })
+
+  return root.toString()
+}
+
+function appendCssExport(js, css) {
+  if (!css || !css.trim()) return js
+  const exportLine = `export const __palettePluginCss = ${JSON.stringify(css)};\n`
+  const sourceMapPattern = /\n?\/\/# sourceMappingURL=data:application\/json[^]*$/m
+  const match = js.match(sourceMapPattern)
+  if (!match) return `${js}\n${exportLine}`
+  return `${js.slice(0, match.index)}\n${exportLine}${match[0]}`
+}
+
+module.exports = {
+  appendCssExport,
+  rootSelector,
+  scopePluginCss,
+}

package/lib/dev-simulator.js

@@ -8,7 +8,7 @@ const { spawn, spawnSync } = require("child_process")
 const { loadManifest } = require("./manifest")
 const { frontendBuildConfig } = require("./bundler")
 const { generatePaletteAppEntry } = require("./app-router")
-const { loadLocalEnv } = require("./secrets")
+const { declaredSecrets, loadLocalEnv } = require("./secrets")
 
 function loadEsbuild() {
   try {
@@ -51,6 +51,13 @@ function needsDatabase(manifest) {
   return Boolean(manifest.database || manifest.capabilities?.database)
 }
 
+function databaseDriverDependencies(databaseUrl) {
+  const url = String(databaseUrl || "")
+  if (/^postgres(?:ql)?(?:\+asyncpg)?:/i.test(url)) return ["asyncpg>=0.29.0"]
+  if (/^mysql\+aiomysql:/i.test(url)) return ["aiomysql>=0.2.0"]
+  return []
+}
+
 function loadLocalConnections(cwd, manifest) {
   const declared = Array.isArray(manifest.connections) ? manifest.connections : []
   const out = {}
@@ -103,13 +110,22 @@ function loadLocalAppServiceMocks(cwd) {
   }
 }
 
+function resolveDevSecrets(cwd, manifest) {
+  const values = loadLocalEnv(cwd, { apply: false })
+  for (const name of Object.keys(declaredSecrets(manifest))) {
+    if (process.env[name] !== undefined) values[name] = process.env[name]
+  }
+  return values
+}
+
 function ensurePythonEnv(cwd, devDir, manifest) {
   const hostPython = process.env.PALETTE_PYTHON || "python3"
   const venvDir = path.join(devDir, "backend-venv")
   const venvPython = path.join(venvDir, "bin", "python")
   const lockPath = path.join(venvDir, ".palette-dev-deps-lock")
   const dbDeps = needsDatabase(manifest) ? ["aiosqlite>=0.20.0", "greenlet>=3.0.0"] : []
-  const deps = Array.from(new Set([...pyprojectDependencies(cwd), ...dbDeps, "uvicorn>=0.30.0"]))
+  const dbDriverDeps = needsDatabase(manifest) ? databaseDriverDependencies(process.env.PALETTE_DEV_DATABASE_URL) : []
+  const deps = Array.from(new Set([...pyprojectDependencies(cwd), ...dbDeps, ...dbDriverDeps, "uvicorn>=0.30.0"]))
   const lock = JSON.stringify(deps)
 
   if (!fs.existsSync(venvPython)) {
@@ -149,7 +165,7 @@ function writeBackendRunner(cwd, devDir, manifest, backendEntry, backendPort) {
   const runner = path.join(devDir, "backend_runner.py")
   const sdkPath = localBackendSdkPath()
   const databasePath = path.join(devDir, `${manifest.id}.sqlite3`)
-  const devSecrets = loadLocalEnv(cwd, { apply: false })
+  const devSecrets = resolveDevSecrets(cwd, manifest)
   const devConnections = loadLocalConnections(cwd, manifest)
   const devAppMocks = loadLocalAppServiceMocks(cwd)
   const content = `from __future__ import annotations
@@ -615,6 +631,7 @@ function indexHtml(manifest) {
       .palette-local-toasts { position: fixed; right: 16px; bottom: 16px; display: grid; gap: 8px; z-index: 50; }
       .palette-local-toast { background: #1d1b18; color: white; padding: 10px 12px; font-size: 13px; box-shadow: 0 10px 30px rgba(0,0,0,.15); }
     </style>
+    <link rel="stylesheet" href="/simulator.css" />
   </head>
   <body>
     <div id="root"></div>
@@ -642,6 +659,7 @@ async function startFrontend(cwd, devDir, manifest, frontendPort, backendPort) {
   if (!fs.existsSync(absEntry)) throw new Error(`frontend entry not found: ${entry}`)
   const generatedEntry = path.join(devDir, "simulator-entry.jsx")
   const bundlePath = path.join(devDir, "simulator.js")
+  const cssPath = path.join(devDir, "simulator.css")
   fs.writeFileSync(generatedEntry, simulatorEntrySource(cwd, absEntry, manifest, backendPort))
   const buildConfig = frontendBuildConfig(cwd, { ...(manifest.frontend || {}), entry })
 
@@ -658,6 +676,7 @@ async function startFrontend(cwd, devDir, manifest, frontendPort, backendPort) {
     define: buildConfig.define,
     absWorkingDir: cwd,
     sourcemap: "inline",
+    metafile: true,
     logLevel: "silent",
     plugins: [
       ...buildConfig.plugins,
@@ -688,6 +707,17 @@ async function startFrontend(cwd, devDir, manifest, frontendPort, backendPort) {
       res.end(fs.readFileSync(bundlePath))
       return
     }
+    if (url.pathname === "/simulator.css") {
+      console.log(`[pltt] frontend GET ${url.pathname} -> ${fs.existsSync(cssPath) ? 200 : 204}`)
+      if (!fs.existsSync(cssPath)) {
+        res.writeHead(204, { "Cache-Control": "no-store" })
+        res.end()
+        return
+      }
+      res.writeHead(200, { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-store" })
+      res.end(fs.readFileSync(cssPath))
+      return
+    }
     console.log(`[pltt] frontend GET ${url.pathname} -> 200`)
     res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" })
     res.end(indexHtml(manifest))
@@ -736,4 +766,4 @@ async function startSimulator({ cwd, frontendPort, backendPort }) {
   await stop()
 }
 
-module.exports = { startSimulator }
+module.exports = { databaseDriverDependencies, resolveDevSecrets, startSimulator }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.49",
+  "version": "0.3.51",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"
@@ -23,7 +23,9 @@
     "node": ">=18"
   },
   "dependencies": {
-    "esbuild": "^0.24.0"
+    "esbuild": "^0.24.0",
+    "postcss": "^8.5.15",
+    "postcss-selector-parser": "^7.1.1"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.20"
+    "@palettelab/sdk": "^0.1.21"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

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

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.20",
+    "@palettelab/sdk": "^0.1.21",
     "react": "^19.0.0"
   }
 }

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

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.20", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.21", "react": "^19.0.0" }
 }

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

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.20", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.21", "react": "^19.0.0" }
 }

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.20",
+    "@palettelab/sdk": "^0.1.21",
     "react": "^19.0.0"
   }
 }

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

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.20",
+    "@palettelab/sdk": "^0.1.21",
     "react": "^19.0.0"
   },
   "devDependencies": {

package/template-fallback/templates/palette-app/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.20",
+    "@palettelab/sdk": "^0.1.21",
     "react": "^19.0.0"
   },
   "devDependencies": {