@palettelab/cli 0.3.52 → 0.3.54

package/README.md

@@ -502,11 +502,14 @@ work without Docker or platform source. The terminal streams local frontend
 requests, frontend rebuilds, and backend process output while `pltt dev` is
 running.
 
-The simulator also provides the same language fields that Palette OS provides:
-`language`, `fallbackLanguage`, `supportedLanguages`, and `setLanguage()`.
-Generated frontend templates include app-owned `frontend/src/translations.ts`
-files wired through `usePluginTranslations()`, so apps can switch when the OS
-language changes without storing copy in the platform.
+The simulator also provides the same OS context fields that Palette OS provides:
+`language`, `fallbackLanguage`, `supportedLanguages`, `setLanguage()`,
+`colorMode`, and `setColorMode()`. Generated frontend templates include
+app-owned `frontend/src/translations.ts` files wired through
+`usePluginTranslations()`, so apps can switch when the OS language changes
+without storing copy in the platform. Apps can read `usePlatform().colorMode`
+or listen for the `palette:theme-change` browser event to react when Palette OS
+changes between light and dark mode.
 
 For Python apps with database tables, `ctx.db` is an async SQLAlchemy session in
 local dev. The simulator imports `backend/api/models.py` when present and creates
@@ -783,6 +786,10 @@ If no plugin ID is provided, the CLI uses the current `palette-plugin.json` or `
 Inspect and generate OS-broker service integrations declared through
 `provides` and `consumes` in `palette-plugin.json`.
 
+Use this command family when one Palette app needs governed data, approvals, or
+events from another app. The CLI keeps the app manifest, local mocks, provider
+schema files, and generated clients aligned with the broker contract.
+
 ```bash
 pltt init employee-management --template provider-app
 pltt init leave-management --template consumer-app
@@ -810,6 +817,38 @@ 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.
 
+Recommended workflow:
+
+1. Provider app: implement backend methods with `@service(...)` and declare
+   event topics in `provides.events`.
+2. Provider app: run `pltt services sync` or `pltt services scaffold <method>`
+   to keep manifest methods and schema files current.
+3. Consumer app: run `pltt services add <target>` for each consumed service or
+   event, including a `--reason` for review and install UI.
+4. Consumer app: use `pltt services mock <target>` and `pltt services test
+   --offline` during local development.
+5. Consumer app: use `pltt services pull --env staging` to generate typed
+   clients from the live `/api/v1/os-broker/schemas` endpoint.
+6. Run `pltt test` before publish; contract checks include local
+   `provides`/`consumes`, mocks, schemas, and dependency-policy validation.
+
+Runtime behavior:
+
+- Service calls go through `POST /api/v1/os-broker/dispatch`.
+- Event publishes go through `POST /api/v1/os-broker/events/emit`.
+- Event subscriptions use `GET /api/v1/os-broker/events/stream`.
+- Catalog and generated client metadata come from `/api/v1/os-broker/catalog`
+  and `/api/v1/os-broker/schemas`.
+- Installs use `/api/v1/app-installs/<app_id>/dependency-plan` and can include
+  required provider apps with `?include_dependencies=true`.
+- Org owners/admins can revoke or restore individual cross-app grants from
+  Settings > Apps; the broker checks those grants on every call and stream.
+
+Provider methods can use inline JSON Schema objects or schema file paths in
+`input_schema`, `input`, `output_schema`, and `output`. Event topics can use
+`schema` or `payload_schema`. The CLI scaffolds schema files by default because
+they are easier to review and reuse for generated clients.
+
 ## Global Flags
 
 - `--json` emits machine-readable output for `package`, `publish`, `status`, `logs`, `test`, and `version`.

package/docs/python-backend-sdk.md

@@ -693,7 +693,18 @@ token = await ctx.connections.access_token("google_calendar")
 ## 11. App-To-App Services
 
 Apps can expose governed broker services and events, then consume them from
-other installed apps without knowing another app's URL.
+other installed apps without knowing another app's URL. The broker is the only
+supported integration path for cross-app business data. Do not read another
+app's database tables and do not call another app's private backend route
+directly.
+
+Palette enforces the app-to-app contract in four places:
+
+- Manifest review: providers declare `provides`, consumers declare `consumes`.
+- Install: required provider apps are resolved before the consumer is activated.
+- Org grants: owners/admins can allow or revoke each consumed service/event.
+- Runtime: every service call, event emit, and event stream is checked against
+  same-org install state, `consumes`, grants, and JSON Schemas.
 
 Provider apps declare a namespace and callable methods with `provides`:
 
@@ -705,25 +716,40 @@ Provider apps declare a namespace and callable methods with `provides`:
       {
         "id": "hr.directory",
         "methods": [
-          { "name": "approvalChain.get", "input_schema": "schemas/approval-chain.input.json" }
+          {
+            "name": "approvalChain.get",
+            "input_schema": "schemas/approval-chain.input.json",
+            "output_schema": "schemas/approval-chain.output.json"
+          }
         ]
       }
     ],
-    "events": [{ "topic": "hierarchy.updated" }]
+    "events": [
+      {
+        "topic": "hierarchy.updated",
+        "schema": "schemas/hierarchy-updated.json"
+      }
+    ]
   }
 }
 ```
 
-Expose the handler with `@service`:
+Expose the handler with `@service`. The platform registers handlers when the
+plugin loads and injects a full `PluginContext` at dispatch time:
 
 ```python
 from palette_sdk import PluginContext, service
 
-@service("approvalChain.get")
+@service("approvalChain.get", scope="members:read")
 async def approval_chain(ctx: PluginContext, payload: dict) -> dict:
     return {"approvers": [{"user_id": ctx.user_id, "step": 1}]}
 ```
 
+If a method also declares `route_method` and `route_path`, Palette can fall back
+to signed internal HTTP transport when no in-process handler is registered. New
+provider apps should prefer `@service(...)` because it avoids URL coupling and
+keeps dispatch inside the broker lifecycle.
+
 Consumers declare qualified targets with `consumes`:
 
 ```json
@@ -746,8 +772,11 @@ Consumers declare qualified targets with `consumes`:
 The CLI can update the manifest and generate typed clients for those targets:
 
 ```bash
+pltt services sync
 pltt services add hr/v1#approvalChain.get --reason "Route leave approvals through HR"
 pltt services add hr/v1#hierarchy.updated --event --optional
+pltt services mock hr/v1#approvalChain.get
+pltt services test --offline
 pltt services pull --env staging
 ```
 
@@ -764,12 +793,42 @@ 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})
+await ctx.events.emit_durable("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.
 
+Useful platform endpoints when building or debugging integrations:
+
+```text
+GET  /api/v1/app-installs/{app_id}/dependency-plan
+POST /api/v1/app-installs/{app_id}?include_dependencies=true
+GET  /api/v1/app-installs/{app_id}/cross-app-grants
+PATCH /api/v1/app-installs/{app_id}/cross-app-grants
+GET  /api/v1/os-broker/catalog
+GET  /api/v1/os-broker/schemas?targets=hr/v1#approvalChain.get
+GET  /api/v1/os-broker/audit?app_id=leave-management
+```
+
+Local simulator workflows can use `.palette/app-services.local.json` mocks.
+The mock command writes the file for you:
+
+```bash
+pltt services mock hr/v1#approvalChain.get
+```
+
+Example mock:
+
+```json
+{
+  "hr/v1#approvalChain.get": {
+    "approvers": [{ "user_id": "manager-1", "step": 1 }]
+  }
+}
+```
+
 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

package/lib/commands/dev.js

@@ -8,7 +8,7 @@ const { watchFrontend } = require("../bundler")
 const { parseFlags, resolveEnvironment } = require("../environments")
 const { resolveDevPorts } = require("../ports")
 const { startSimulator } = require("../dev-simulator")
-const { loadLocalEnv } = require("../secrets")
+const { loadLocalEnvDetails } = require("../secrets")
 const buildCommand = require("./build")
 const publish = require("./publish")
 const logs = require("./logs")
@@ -98,11 +98,39 @@ function lintMigrationsForDev(cwd, manifest) {
   process.exit(1)
 }
 
+function formatEnvValue(value) {
+  if (value === undefined || value === null) return ""
+  const str = String(value)
+  if (!str) return ""
+  if (/[\s#"'\\]/.test(str)) return JSON.stringify(str)
+  return str
+}
+
+function writePlatformEnvFile(cwd, localEnv) {
+  const dir = path.join(cwd, ".palette")
+  fs.mkdirSync(dir, { recursive: true })
+  const envPath = path.join(dir, "platform.env")
+  const values = {}
+  for (const [key, value] of Object.entries(localEnv?.values || {})) {
+    values[key] = process.env[key] !== undefined ? process.env[key] : value
+  }
+  const lines = [
+    "# Generated by pltt dev --platform from local env files.",
+    "# Do not commit this file.",
+    "",
+  ]
+  for (const [key, value] of Object.entries(values).sort(([a], [b]) => a.localeCompare(b))) {
+    lines.push(`${key}=${formatEnvValue(value)}`)
+  }
+  fs.writeFileSync(envPath, `${lines.join("\n")}\n`)
+  return envPath
+}
+
 async function run(args, { cwd }) {
   const { flags, rest } = parseFlags(args)
   const cloud = rest.includes("--cloud") || rest.includes("--sandbox")
   const platform = rest.includes("--platform")
-  loadLocalEnv(cwd)
+  const localEnv = loadLocalEnvDetails(cwd, { environment: flags.env })
   if (cloud) {
     const json = args.includes("--json")
     const publishArgs = ["--publish-type", "preview"]
@@ -199,6 +227,9 @@ async function run(args, { cwd }) {
   }
   console.log(`[pltt] frontend: http://localhost:${frontendPort}/apps/${pluginId}`)
   console.log(`[pltt] backend:  http://localhost:${backendPort}/api/v1/plugins/${pluginId}`)
+  if (localEnv.files.length) {
+    console.log(`[pltt] env files: ${localEnv.files.join(", ")}`)
+  }
 
   // Pre-pull so we can give a useful error if the image isn't reachable
   // (common cause: maintainer hasn't pushed it yet, or `docker login ghcr.io`
@@ -210,11 +241,13 @@ async function run(args, { cwd }) {
     process.exit(1)
   }
 
+  const platformEnvFile = writePlatformEnvFile(cwd, localEnv)
   const env = {
     ...process.env,
     PALETTE_DEV_IMAGE: DEFAULT_IMAGE,
     PALETTE_ACTIVE_PLUGIN: pluginId,
     PALETTE_PLUGIN_DIR: cwd,
+    PALETTE_PLUGIN_ENV_FILE: platformEnvFile,
     PALETTE_FRONTEND_PORT: frontendPort,
     PALETTE_BACKEND_PORT: backendPort,
   }

package/lib/commands/publish.js

@@ -228,6 +228,14 @@ function scopesOf(spec) {
   return ["dev"]
 }
 
+function withPluginScope(spec) {
+  const scopes = Array.from(new Set([...scopesOf(spec), "plugin"]))
+  return {
+    ...spec,
+    scope: scopes.length === 1 ? scopes[0] : scopes,
+  }
+}
+
 function cloneManifest(manifest) {
   return JSON.parse(JSON.stringify(manifest))
 }
@@ -235,12 +243,6 @@ function cloneManifest(manifest) {
 function collectPluginSecrets(cwd, manifest, env, flags, log, localEnv) {
   const declared = declaredSecrets(manifest)
   const pluginSecrets = Object.entries(declared).filter(([, spec]) => spec.scope.includes("plugin"))
-  const devRequired = Object.entries(declared).filter(([, spec]) => spec.scope.includes("dev") && spec.required)
-  if (devRequired.length) {
-    log(
-      `[pltt]   dev-only secrets are not uploaded: ${devRequired.map(([name]) => name).join(", ")}`,
-    )
-  }
 
   let fileValues = {}
   if (flags.secretsFile) {
@@ -281,7 +283,14 @@ function collectPluginSecrets(cwd, manifest, env, flags, log, localEnv) {
     }
     const explicitSpec = effectiveManifest.secrets[name]
     if (explicitSpec) {
-      if (scopesOf(explicitSpec).includes("plugin")) values[name] = fileValues[name] ?? process.env[name] ?? localValues[name]
+      const value = fileValues[name] ?? process.env[name] ?? localValues[name]
+      if (scopesOf(explicitSpec).includes("plugin")) {
+        values[name] = value
+      } else if (canAutoUploadEnvKey(name)) {
+        effectiveManifest.secrets[name] = withPluginScope(explicitSpec)
+        values[name] = value
+        autoUploaded.push(name)
+      }
       continue
     }
     if (isReservedAutoEnvKey(name)) {

package/lib/dev-simulator.js

@@ -576,6 +576,21 @@ function normalizePaletteLanguage(language, fallback = "en") {
   return value ? value.split("-")[0] : fallback
 }
 
+function normalizePaletteColorMode(mode, fallback = "light") {
+  return mode === "dark" ? "dark" : fallback
+}
+
+function detectPaletteColorMode() {
+  return window.matchMedia?.("(prefers-color-scheme: dark)")?.matches ? "dark" : "light"
+}
+
+function applyPaletteColorMode(mode) {
+  const normalized = normalizePaletteColorMode(mode)
+  document.documentElement.classList.toggle("dark", normalized === "dark")
+  document.documentElement.style.colorScheme = normalized
+  window.dispatchEvent(new CustomEvent("palette:theme-change", { detail: { colorMode: normalized } }))
+}
+
 function Toasts() {
   const [items, setItems] = React.useState([])
   React.useEffect(() => {
@@ -594,6 +609,7 @@ function Toasts() {
 
 function Shell() {
   const [language, updateLanguage] = React.useState(() => normalizePaletteLanguage(navigator.language))
+  const [colorMode, updateColorMode] = React.useState(() => detectPaletteColorMode())
   const platform = React.useMemo(() => ({
     ...basePlatform,
     language,
@@ -605,18 +621,34 @@ function Shell() {
       document.documentElement.lang = normalized
       window.dispatchEvent(new CustomEvent("palette:language-change", { detail: { language: normalized } }))
     },
-  }), [language])
+    colorMode,
+    setColorMode: (nextMode) => {
+      updateColorMode(normalizePaletteColorMode(nextMode))
+    },
+  }), [language, colorMode])
 
   React.useEffect(() => {
     document.documentElement.lang = language
   }, [language])
 
+  React.useEffect(() => {
+    applyPaletteColorMode(colorMode)
+  }, [colorMode])
+
   React.useEffect(() => {
     const onLanguageChange = () => updateLanguage(normalizePaletteLanguage(navigator.language))
     window.addEventListener("languagechange", onLanguageChange)
     return () => window.removeEventListener("languagechange", onLanguageChange)
   }, [])
 
+  React.useEffect(() => {
+    const media = window.matchMedia?.("(prefers-color-scheme: dark)")
+    if (!media) return
+    const onColorModeChange = () => updateColorMode(detectPaletteColorMode())
+    media.addEventListener?.("change", onColorModeChange)
+    return () => media.removeEventListener?.("change", onColorModeChange)
+  }, [])
+
   return React.createElement(PluginProvider, { value: platform },
     React.createElement("main", { className: "palette-local-shell" },
       React.createElement(Plugin, { platform }),

package/lib/manifest.js

@@ -2,7 +2,7 @@
 
 const fs = require("fs")
 const path = require("path")
-const { SECRET_SCOPES } = require("./secrets")
+const { ENV_KEY_PATTERN, SECRET_SCOPES } = require("./secrets")
 
 const MANIFEST_FILE = "palette-plugin.json"
 const SUPPORTED_MANIFEST_VERSIONS = ["1"]
@@ -127,8 +127,8 @@ function validateSecrets(value, errors) {
   const allowed = new Set(["scope", "required", "label", "help", "validate"])
   for (const [name, spec] of Object.entries(value)) {
     const label = `secrets.${name}`
-    if (!/^[A-Z_][A-Z0-9_]*$/.test(name)) {
-      errors.push(`${label} must be an uppercase environment-style name`)
+    if (!ENV_KEY_PATTERN.test(name)) {
+      errors.push(`${label} must be a valid environment variable name`)
     }
     if (!isObject(spec)) {
       errors.push(`${label} must be an object`)

package/lib/secrets.js

@@ -6,6 +6,7 @@ const path = require("path")
 const LOCAL_ENV_PATH = path.join(".palette", ".env.local")
 const EXAMPLE_ENV_PATH = path.join(".palette", ".env.example")
 const SECRET_SCOPES = new Set(["dev", "plugin", "install", "platform"])
+const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
 const RESERVED_AUTO_ENV_KEYS = new Set([
   "CI",
   "HOME",
@@ -162,7 +163,7 @@ function declaredSecrets(manifest) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {}
   const out = {}
   for (const [name, meta] of Object.entries(raw)) {
-    if (!/^[A-Z_][A-Z0-9_]*$/.test(name)) continue
+    if (!ENV_KEY_PATTERN.test(name)) continue
     const item = meta && typeof meta === "object" && !Array.isArray(meta) ? meta : {}
     out[name] = {
       ...item,
@@ -210,7 +211,7 @@ function isReservedAutoEnvKey(key) {
 }
 
 function canAutoUploadEnvKey(key) {
-  return /^[A-Z_][A-Z0-9_]*$/.test(key) && !isPublicEnvKey(key) && !isReservedAutoEnvKey(key)
+  return ENV_KEY_PATTERN.test(key) && !isPublicEnvKey(key) && !isReservedAutoEnvKey(key)
 }
 
 function redactValue(value) {
@@ -222,6 +223,7 @@ function redactValue(value) {
 
 module.exports = {
   EXAMPLE_ENV_PATH,
+  ENV_KEY_PATTERN,
   LOCAL_ENV_PATH,
   SECRET_SCOPES,
   declaredSecrets,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.52",
+  "version": "0.3.54",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"

package/platform-dev/docker-compose.yml

@@ -9,6 +9,8 @@
 services:
   platform:
     image: ${PALETTE_DEV_IMAGE:-ghcr.io/palette-lab/platform-dev:latest}
+    env_file:
+      - ${PALETTE_PLUGIN_ENV_FILE:-/dev/null}
     ports:
       - "${PALETTE_FRONTEND_PORT:-7321}:3000"
       - "${PALETTE_BACKEND_PORT:-8732}:8000"
@@ -25,8 +27,8 @@ services:
       STORAGE_BACKEND: "local"
       LOCAL_STORAGE_DIR: "/srv/storage"
       # Disable optional features that need real credentials
-      RAG_ENABLED: "false"
-      OPENAI_API_KEY: ""
+      RAG_ENABLED: "${RAG_ENABLED:-false}"
+      OPENAI_API_KEY: "${OPENAI_API_KEY:-}"
     volumes:
       - "${PALETTE_PLUGIN_DIR}:/plugins/${PALETTE_ACTIVE_PLUGIN}"
     depends_on:

package/template-fallback/package.json

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

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

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.22",
+    "@palettelab/sdk": "^0.1.24",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   }

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

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.22",
+    "@palettelab/sdk": "^0.1.24",
     "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.22", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.24", "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.22", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.24", "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.22",
+    "@palettelab/sdk": "^0.1.24",
     "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.22",
+    "@palettelab/sdk": "^0.1.24",
     "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.22",
+    "@palettelab/sdk": "^0.1.24",
     "react": "^19.0.0"
   },
   "devDependencies": {

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

@@ -2,7 +2,7 @@
   "private": true,
   "type": "module",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.22",
+    "@palettelab/sdk": "^0.1.24",
     "react": "^19.0.0"
   }
 }