@palettelab/cli 0.3.48 → 0.3.49

package/README.md

@@ -533,10 +533,35 @@ Environment variables:
 | `PALETTE_DEV_LOG_TAIL` | `200` | Initial hosted log events shown by `pltt dev --sandbox` / `--cloud` |
 | `APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS` | `false` | Backend setting for hosted sandboxes; auto-approve passing preview publishes so developers can test full OS behavior without manual review |
 
-### `pltt secrets`
+### `.env` and secrets
 
-Palette secrets are declared in `palette-plugin.json` and resolved through
-`ctx.secret("NAME")`.
+For normal app development, put environment values in root `.env` files and run
+the usual CLI command. No separate input is required:
+
+```bash
+pltt dev
+pltt sandbox --env staging
+pltt preview --env staging
+pltt publish --env staging
+```
+
+The CLI automatically reads these files, with later files overriding earlier
+ones:
+
+```text
+.env
+.env.local
+.env.<env>
+.env.<env>.local
+```
+
+Server-only keys such as `OPENAI_API_KEY` or `STRIPE_SECRET` are uploaded during
+hosted preview/publish as encrypted plugin secrets and resolved through
+`ctx.secret("NAME")`. Public keys prefixed with `NEXT_PUBLIC_` are bundled into
+the frontend and are not uploaded as backend secrets.
+
+You can still declare secrets explicitly in `palette-plugin.json` when you need
+install-scoped values or labels/help text:
 
 ```json
 {
@@ -549,7 +574,7 @@ Palette secrets are declared in `palette-plugin.json` and resolved through
 }
 ```
 
-Commands:
+Optional management commands:
 
 ```bash
 pltt secrets init
@@ -559,10 +584,9 @@ pltt secrets list --env staging
 pltt publish --env staging --secrets-file plugin-secrets.env
 ```
 
-`dev` secrets live in `.palette/.env.local`, are loaded by `pltt dev`, and are
-never uploaded. `plugin` secrets are encrypted by the platform and attached to
-the plugin/environment. `install` secrets are filled by the installing org.
-Frontend bundles may only receive public values such as `NEXT_PUBLIC_*`.
+`.palette/.env.local` remains supported for older projects. `plugin` secrets
+are encrypted by the platform and attached to the plugin/environment.
+`install` secrets are filled by the installing org.
 
 Managed platform services do not require developer Redis/Qdrant keys. Declare
 them and use scoped SDK clients:

package/docs/python-backend-sdk.md

@@ -631,9 +631,10 @@ Declare secret ownership in `palette-plugin.json`:
 ```
 
 `ctx.secret("KEY")` resolves declared secrets from the configured scope:
-install config, plugin-scope encrypted secrets, or local `.palette/.env.local`
-during `pltt dev`. Undeclared keys still fall back to the process environment
-for local compatibility.
+install config, plugin-scope encrypted secrets, or local root `.env` files
+during `pltt dev`. During hosted preview/publish, server-only `.env` keys are
+uploaded automatically as encrypted plugin secrets. Undeclared keys still fall
+back to the process environment for local compatibility.
 
 Managed Redis, vector, and storage services are declared in the manifest:
 

package/lib/bundler.js

@@ -509,7 +509,7 @@ async function watchFrontend(pluginDir, entry, outfile, frontend = {}) {
  *   ./backend/...
  *   ./palette-plugin.json
  */
-async function bundleBackend(pluginDir) {
+async function bundleBackend(pluginDir, options = {}) {
   pluginDir = path.resolve(pluginDir)
   const { spawnSync } = require("child_process")
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "palette-bundle-"))
@@ -531,9 +531,16 @@ async function bundleBackend(pluginDir) {
     const backendDir = path.join(pluginDir, "backend")
     if (fs.existsSync(backendDir)) copy(backendDir, path.join(stage, "backend"))
     for (const metadataFile of ["package.json", "pyproject.toml", "palette-plugin.json"]) {
+      if (metadataFile === "palette-plugin.json" && options.manifest) continue
       const src = path.join(pluginDir, metadataFile)
       if (fs.existsSync(src)) fs.copyFileSync(src, path.join(stage, metadataFile))
     }
+    if (options.manifest) {
+      fs.writeFileSync(
+        path.join(stage, "palette-plugin.json"),
+        JSON.stringify(options.manifest, null, 2),
+      )
+    }
 
     const sdkDir = path.resolve(__dirname, "..", "backend-sdk", "palette_sdk")
     const targetSdkDir = path.join(stage, "backend", "palette_sdk")

package/lib/cli.js

@@ -11,6 +11,7 @@ const pkg = require("./commands/package")
 const status = require("./commands/status")
 const logs = require("./commands/logs")
 const secrets = require("./commands/secrets")
+const services = require("./commands/services")
 
 const COMMANDS = {
   init: { run: init, help: "Scaffold a new plugin directory from the template" },
@@ -50,6 +51,10 @@ const COMMANDS = {
     run: secrets,
     help: "Initialize local env files and manage plugin-scope secrets",
   },
+  services: {
+    run: services,
+    help: "Inspect / pull / scaffold OS-broker services (list, pull, scaffold)",
+  },
 }
 
 function printHelp() {
@@ -77,6 +82,11 @@ function printHelp() {
   console.log("\nLogs flags:")
   console.log("  --tail <n>       Tail last n events (default 50)")
   console.log("  -f, --follow     Stream events (poll every 3s)")
+  console.log("\nServices (OS broker):")
+  console.log("  pltt services list            # show provided services/events in the org")
+  console.log("  pltt services add TARGET      # add a consumed service/event target")
+  console.log("  pltt services pull            # generate typed TS+Python clients from consumes")
+  console.log("  pltt services scaffold NAME   # add a provider method (schemas + handler stub)")
   console.log("\nSecrets:")
   console.log("  pltt secrets init")
   console.log("  pltt secrets set NAME --value <secret> --env staging")

package/lib/commands/doctor.js

@@ -6,7 +6,7 @@ const { spawnSync } = require("child_process")
 const { loadManifest, validateManifest } = require("../manifest")
 const { bundleFrontend } = require("../bundler")
 const { DEFAULT_BACKEND_DEV_PORT, DEFAULT_FRONTEND_DEV_PORT, resolveDevPorts } = require("../ports")
-const { declaredSecrets, loadLocalEnv } = require("../secrets")
+const { declaredSecrets, loadLocalEnvDetails } = require("../secrets")
 
 const DEFAULT_IMAGE =
   process.env.PALETTE_DEV_IMAGE || "ghcr.io/palette-lab/platform-dev:latest"
@@ -122,19 +122,20 @@ async function run(args, { cwd }) {
     }
 
     const secrets = declaredSecrets(manifest)
-    const localSecrets = loadLocalEnv(cwd, { apply: false })
+    const localEnv = loadLocalEnvDetails(cwd, { apply: false })
+    const localSecrets = localEnv.values
     if (Object.keys(secrets).length === 0) {
       ok("no manifest secrets declared")
     } else {
       ok(`manifest declares ${Object.keys(secrets).length} secret(s)`)
       for (const [name, spec] of Object.entries(secrets)) {
         if (spec.scope.includes("dev") && !localSecrets[name]) {
-          warn(`local dev secret missing: ${name}`, "Run pltt secrets init and fill .palette/.env.local.")
+          warn(`local dev secret missing: ${name}`, "Add it to .env, .env.local, or an environment-specific .env file.")
         }
         if (spec.scope.includes("plugin") && spec.required && !localSecrets[name] && !process.env[name]) {
           warn(
             `plugin secret missing locally: ${name}`,
-            "Set an env var, pass --secrets-file to publish, or run pltt secrets set after first publish.",
+            "Add it to .env/.env.local, set an env var, pass --secrets-file, or run pltt secrets set.",
           )
         }
       }

package/lib/commands/publish.js

@@ -12,10 +12,13 @@ const {
   confirmProduction,
 } = require("../environments")
 const {
+  canAutoUploadEnvKey,
   declaredSecrets,
+  isPublicEnvKey,
+  isReservedAutoEnvKey,
+  loadLocalEnvDetails,
   loadLocalEnv,
   parseDotEnv,
-  readDotEnvFile,
   redactValue,
 } = require("../secrets")
 
@@ -138,12 +141,12 @@ function printPreflightFailure(payload, fallbackOutput) {
   console.error("[pltt] Need machine-readable details? Run `pltt test --json`.")
 }
 
-function runPreflight(cwd, json, publishType = "release") {
+function runPreflight(cwd, json, publishType = "release", environment) {
   const cliBin = path.resolve(__dirname, "..", "..", "bin", "pltt.js")
   const res = spawnSync(process.execPath, [cliBin, "test", "--json", "--publish-type", publishType], {
     cwd,
     encoding: "utf8",
-    env: process.env,
+    env: environment ? { ...process.env, PALETTE_ENV: environment } : process.env,
   })
 
   if (res.status === 0) {
@@ -218,7 +221,18 @@ async function put(url, buf, contentType) {
   }
 }
 
-function collectPluginSecrets(cwd, manifest, env, flags, log) {
+function scopesOf(spec) {
+  if (!spec || typeof spec !== "object" || Array.isArray(spec)) return ["dev"]
+  if (Array.isArray(spec.scope)) return spec.scope
+  if (typeof spec.scope === "string") return [spec.scope]
+  return ["dev"]
+}
+
+function cloneManifest(manifest) {
+  return JSON.parse(JSON.stringify(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)
@@ -232,7 +246,8 @@ function collectPluginSecrets(cwd, manifest, env, flags, log) {
   if (flags.secretsFile) {
     fileValues = parseDotEnv(fs.readFileSync(path.resolve(cwd, flags.secretsFile), "utf8"))
   }
-  const localValues = readDotEnvFile(path.join(cwd, ".palette", ".env.local"))
+  const localValues = localEnv?.values || loadLocalEnv(cwd, { apply: false, environment: env.name })
+  const candidateValues = { ...localValues, ...fileValues }
   const values = {}
   const missing = []
   for (const [name, spec] of pluginSecrets) {
@@ -249,10 +264,61 @@ function collectPluginSecrets(cwd, manifest, env, flags, log) {
         `Set env vars, pass --secrets-file, or run pltt secrets set <NAME> --env ${env.name}.`,
     )
   }
+  const effectiveManifest = cloneManifest(manifest)
+  effectiveManifest.secrets =
+    effectiveManifest.secrets && typeof effectiveManifest.secrets === "object" && !Array.isArray(effectiveManifest.secrets)
+      ? { ...effectiveManifest.secrets }
+      : {}
+  const autoUploaded = []
+  const publicBundled = []
+  const skippedReserved = []
+  const skippedInvalid = []
+  for (const [name, value] of Object.entries(candidateValues)) {
+    if (!value) continue
+    if (isPublicEnvKey(name)) {
+      publicBundled.push(name)
+      continue
+    }
+    const explicitSpec = effectiveManifest.secrets[name]
+    if (explicitSpec) {
+      if (scopesOf(explicitSpec).includes("plugin")) values[name] = fileValues[name] ?? process.env[name] ?? localValues[name]
+      continue
+    }
+    if (isReservedAutoEnvKey(name)) {
+      skippedReserved.push(name)
+      continue
+    }
+    if (!canAutoUploadEnvKey(name)) {
+      skippedInvalid.push(name)
+      continue
+    }
+    effectiveManifest.secrets[name] = {
+      scope: "plugin",
+      required: false,
+      help: "Auto-uploaded from local .env by Palette CLI.",
+    }
+    values[name] = fileValues[name] ?? process.env[name] ?? localValues[name]
+    autoUploaded.push(name)
+  }
+  if (localEnv?.files?.length) {
+    log(`[pltt]   env files: ${localEnv.files.join(", ")}`)
+  }
+  if (autoUploaded.length) {
+    log(`[pltt]   auto plugin secrets from .env: ${autoUploaded.sort().join(", ")}`)
+  }
+  if (publicBundled.length) {
+    log(`[pltt]   public env bundled in frontend: ${Array.from(new Set(publicBundled)).sort().join(", ")}`)
+  }
+  if (skippedReserved.length) {
+    log(`[pltt]   skipped reserved env keys: ${Array.from(new Set(skippedReserved)).sort().join(", ")}`)
+  }
+  if (skippedInvalid.length) {
+    log(`[pltt]   skipped invalid env keys: ${Array.from(new Set(skippedInvalid)).sort().join(", ")}`)
+  }
   for (const [name, value] of Object.entries(values)) {
     log(`[pltt]   plugin secret ${name}=${redactValue(value)} (${env.name})`)
   }
-  return values
+  return { manifest: effectiveManifest, pluginSecrets: values }
 }
 
 async function run(argv, { cwd }) {
@@ -288,7 +354,7 @@ async function run(argv, { cwd }) {
 
   const manifest = loadManifest(cwd)
   const publishType = parsePublishType(argv)
-  loadLocalEnv(cwd)
+  const localEnv = loadLocalEnvDetails(cwd, { environment: env.name })
   const errors = validateManifest(manifest)
   if (errors.length) {
     console.error("[pltt] manifest invalid:")
@@ -296,7 +362,23 @@ async function run(argv, { cwd }) {
     process.exit(1)
   }
 
-  runPreflight(cwd, flags.json, publishType)
+  runPreflight(cwd, flags.json, publishType, env.name)
+  let pluginSecrets = {}
+  let publishManifest = manifest
+  try {
+    const collected = collectPluginSecrets(cwd, manifest, env, flags, log, localEnv)
+    pluginSecrets = collected.pluginSecrets
+    publishManifest = collected.manifest
+  } catch (err) {
+    console.error(`[pltt] ${err instanceof Error ? err.message : String(err)}`)
+    process.exit(1)
+  }
+  const effectiveErrors = validateManifest(publishManifest)
+  if (effectiveErrors.length) {
+    console.error("[pltt] generated manifest invalid:")
+    for (const e of effectiveErrors) console.error(`  - ${e}`)
+    process.exit(1)
+  }
 
   log(
     `[pltt] publishing ${manifest.id}@${manifest.version} → ${env.name} (${env.url})`,
@@ -312,18 +394,11 @@ async function run(argv, { cwd }) {
   }
 
   log("[pltt]   bundling backend")
-  const backend = await bundleBackend(cwd)
+  const backend = await bundleBackend(cwd, { manifest: publishManifest })
   log(`[pltt]     ${backend.length} bytes`)
 
   const backendSha = sha256(backend)
   const api = makeApi(env)
-  let pluginSecrets = {}
-  try {
-    pluginSecrets = collectPluginSecrets(cwd, manifest, env, flags, log)
-  } catch (err) {
-    console.error(`[pltt] ${err instanceof Error ? err.message : String(err)}`)
-    process.exit(1)
-  }
 
   log("[pltt]   requesting signed URLs")
   const signed = await api("/api/v1/appstore/sign-upload", {
@@ -341,7 +416,7 @@ async function run(argv, { cwd }) {
     put(signed.backend_upload_url, backend, "application/gzip"),
     put(
       signed.manifest_upload_url,
-      Buffer.from(JSON.stringify(manifest, null, 2)),
+      Buffer.from(JSON.stringify(publishManifest, null, 2)),
       "application/json",
     ),
   ]
@@ -356,7 +431,7 @@ async function run(argv, { cwd }) {
     version: manifest.version,
     bundle_path: signed.bundle_path,
     bundle_sha256: backendSha,
-    manifest,
+    manifest: publishManifest,
     publish_type: publishType,
     environment: env.name,
   }

package/lib/commands/services.js

@@ -0,0 +1,426 @@
+"use strict"
+
+/**
+ * pltt services — OS broker developer tools.
+ *
+ *   pltt services list      — show every service/event the org's installed
+ *                             apps make available; useful for "what can I
+ *                             consume?".
+ *   pltt services pull      — read consumes block from palette-plugin.json,
+ *                             fetch JSON Schemas from the platform, and
+ *                             generate typed clients into:
+ *                               .palette/types/services.d.ts
+ *                               .palette/types/services.ts   (proxy)
+ *                               .palette/python/services.py  (pydantic)
+ *   pltt services scaffold <method>
+ *                           — emit a provider stub (schemas + handler) in
+ *                             the current plugin under ./broker/.
+ *   pltt services add <target>
+ *                           — add a consumed service/event target to
+ *                             palette-plugin.json.
+ */
+
+const fs = require("fs")
+const path = require("path")
+const { parseFlags, resolveEnvironment } = require("../environments")
+
+function readManifest(cwd) {
+  const p = path.join(cwd, "palette-plugin.json")
+  if (!fs.existsSync(p)) {
+    throw new Error("no palette-plugin.json found in current directory")
+  }
+  return JSON.parse(fs.readFileSync(p, "utf8"))
+}
+
+function writeManifest(cwd, manifest) {
+  const p = path.join(cwd, "palette-plugin.json")
+  fs.writeFileSync(p, JSON.stringify(manifest, null, 2) + "\n")
+}
+
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true })
+}
+
+async function authFetch(env, path, init = {}) {
+  const url = `${env.url}${path}`
+  const headers = { "Content-Type": "application/json", ...(init.headers || {}) }
+  if (env.token) headers.Authorization = `Bearer ${env.token}`
+  const res = await fetch(url, { ...init, headers })
+  if (!res.ok) {
+    const text = await res.text()
+    throw new Error(`${init.method || "GET"} ${url} → ${res.status}: ${text}`)
+  }
+  return res.json()
+}
+
+// ---- list --------------------------------------------------------------------
+
+async function runList(argv, { cwd }) {
+  const { flags } = parseFlags(argv)
+  const env = resolveEnvironment({ cwd, flags })
+  const catalog = await authFetch(env, "/api/v1/os-broker/catalog")
+  if (argv.includes("--json")) {
+    process.stdout.write(JSON.stringify(catalog, null, 2) + "\n")
+    return
+  }
+  const byNs = {}
+  for (const svc of catalog.services || []) {
+    const key = `${svc.namespace}/${svc.version}`
+    byNs[key] = byNs[key] || { services: [], events: [], providers: new Set() }
+    byNs[key].services.push(svc)
+    byNs[key].providers.add(svc.provider_app_id)
+  }
+  for (const evt of catalog.events || []) {
+    const key = `${evt.namespace}/${evt.version}`
+    byNs[key] = byNs[key] || { services: [], events: [], providers: new Set() }
+    byNs[key].events.push(evt)
+    byNs[key].providers.add(evt.provider_app_id)
+  }
+  const keys = Object.keys(byNs).sort()
+  if (keys.length === 0) {
+    console.log("[pltt] no services or events registered for the current org.")
+    return
+  }
+  for (const key of keys) {
+    const entry = byNs[key]
+    console.log(`\n${key}   (provider: ${Array.from(entry.providers).join(", ")})`)
+    for (const svc of entry.services) {
+      const scope = svc.scope ? `  [scope: ${svc.scope}]` : ""
+      console.log(`  service  ${key}#${svc.method}${scope}`)
+      if (svc.description) console.log(`           ${svc.description}`)
+    }
+    for (const evt of entry.events) {
+      console.log(`  event    ${key}#${evt.topic}`)
+      if (evt.description) console.log(`           ${evt.description}`)
+    }
+  }
+}
+
+// ---- pull (codegen) ----------------------------------------------------------
+
+function consumeTargets(manifest) {
+  const consumes = manifest.consumes || {}
+  const normalize = (entry) => {
+    if (typeof entry === "string") return entry
+    if (entry && typeof entry === "object" && typeof entry.target === "string") return entry.target
+    return null
+  }
+  const services = (consumes.services || []).map(normalize).filter(Boolean)
+  const events = (consumes.events || []).map(normalize).filter(Boolean)
+  return { services, events }
+}
+
+function targetFromConsumeEntry(entry) {
+  if (typeof entry === "string") return entry
+  if (entry && typeof entry === "object" && typeof entry.target === "string") return entry.target
+  return null
+}
+
+function brokerTargetLooksValid(target) {
+  return typeof target === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[A-Za-z0-9_.-]+$/.test(target)
+}
+
+function valueAfter(argv, name) {
+  const index = argv.indexOf(name)
+  if (index === -1) return null
+  return argv[index + 1] || null
+}
+
+function jsonSchemaToTs(schema, indent = "") {
+  if (!schema || typeof schema !== "object") return "any"
+  if (schema.type === "string") return "string"
+  if (schema.type === "number" || schema.type === "integer") return "number"
+  if (schema.type === "boolean") return "boolean"
+  if (schema.type === "array") return `${jsonSchemaToTs(schema.items)}[]`
+  if (schema.type === "object" || schema.properties) {
+    const props = schema.properties || {}
+    const required = new Set(schema.required || [])
+    const lines = []
+    for (const [name, prop] of Object.entries(props)) {
+      const opt = required.has(name) ? "" : "?"
+      lines.push(`${indent}  ${JSON.stringify(name)}${opt}: ${jsonSchemaToTs(prop, indent + "  ")}`)
+    }
+    return `{\n${lines.join("\n")}\n${indent}}`
+  }
+  return "any"
+}
+
+function jsonSchemaToPydantic(name, schema) {
+  if (!schema || typeof schema !== "object") {
+    return { code: "", ref: "dict" }
+  }
+  if (schema.type === "object" || schema.properties) {
+    const props = schema.properties || {}
+    const required = new Set(schema.required || [])
+    const fieldLines = []
+    for (const [field, prop] of Object.entries(props)) {
+      const opt = required.has(field) ? "" : " | None = None"
+      fieldLines.push(`    ${field}: ${pythonScalar(prop)}${opt}`)
+    }
+    const code =
+      `class ${name}(BaseModel):\n` +
+      (fieldLines.length ? fieldLines.join("\n") : "    pass") +
+      "\n"
+    return { code, ref: name }
+  }
+  return { code: "", ref: pythonScalar(schema) }
+}
+
+function pythonScalar(schema) {
+  if (!schema) return "Any"
+  if (schema.type === "string") return "str"
+  if (schema.type === "integer") return "int"
+  if (schema.type === "number") return "float"
+  if (schema.type === "boolean") return "bool"
+  if (schema.type === "array") return `list[${pythonScalar(schema.items)}]`
+  return "Any"
+}
+
+function safeIdent(s) {
+  return s.replace(/[^A-Za-z0-9_]/g, "_")
+}
+
+function tsHeader() {
+  return (
+    "// AUTOGENERATED by `pltt services pull` — do not edit by hand.\n" +
+    "// Re-run after adding to consumes.services / consumes.events.\n\n" +
+    'import { palette } from "@palettelab/sdk"\n\n'
+  )
+}
+
+function pyHeader() {
+  return (
+    '"""AUTOGENERATED by `pltt services pull` — do not edit by hand."""\n\n' +
+    "from __future__ import annotations\n\n" +
+    "from typing import Any\n\n" +
+    "from pydantic import BaseModel\n" +
+    "from palette_sdk import services as _services\n\n"
+  )
+}
+
+async function runPull(argv, { cwd }) {
+  const manifest = readManifest(cwd)
+  const { services, events } = consumeTargets(manifest)
+  const targets = [...new Set([...services, ...events])]
+  if (targets.length === 0) {
+    console.log("[pltt] palette-plugin.json declares no consumes.services or consumes.events — nothing to pull.")
+    return
+  }
+  const { flags } = parseFlags(argv)
+  const env = resolveEnvironment({ cwd, flags })
+  const targetsParam = encodeURIComponent(targets.join(","))
+  const schemas = await authFetch(env, `/api/v1/os-broker/schemas?targets=${targetsParam}`)
+
+  const byTarget = new Map(schemas.map((s) => [s.target, s]))
+  const missing = targets.filter((t) => !byTarget.has(t))
+  if (missing.length) {
+    console.warn(`[pltt] warning: no schema returned for: ${missing.join(", ")}`)
+  }
+
+  // ---- TypeScript output
+  const tsLines = [tsHeader()]
+  const tsProxies = {}
+  for (const target of targets) {
+    const entry = byTarget.get(target)
+    if (!entry) continue
+    const proxyKey = `${entry.namespace}/${entry.version}`
+    tsProxies[proxyKey] = tsProxies[proxyKey] || []
+    if (entry.kind === "service") {
+      const inT = entry.input_schema ? jsonSchemaToTs(entry.input_schema) : "Record<string, unknown>"
+      const outT = entry.output_schema ? jsonSchemaToTs(entry.output_schema) : "unknown"
+      tsProxies[proxyKey].push({ kind: "service", method: entry.method, inT, outT, scope: entry.scope })
+    } else if (entry.kind === "event") {
+      const payT = entry.payload_schema ? jsonSchemaToTs(entry.payload_schema) : "Record<string, unknown>"
+      tsProxies[proxyKey].push({ kind: "event", topic: entry.topic, payT })
+    }
+  }
+  for (const [ns, items] of Object.entries(tsProxies)) {
+    const safe = safeIdent(ns)
+    tsLines.push(`// ----- ${ns} -----`)
+    const services = items.filter((i) => i.kind === "service")
+    const events = items.filter((i) => i.kind === "event")
+    if (services.length) {
+      tsLines.push(`export const ${safe} = {`)
+      for (const svc of services) {
+        const comment = svc.scope ? `  /** scope: ${svc.scope} */` : ""
+        if (comment) tsLines.push(comment)
+        tsLines.push(`  async ${JSON.stringify(svc.method)}(input: ${svc.inT}): Promise<${svc.outT}> {`)
+        tsLines.push(`    return (await palette.broker.call(${JSON.stringify(ns + "#" + svc.method)}, input)) as ${svc.outT}`)
+        tsLines.push(`  },`)
+      }
+      tsLines.push(`}\n`)
+    }
+    if (events.length) {
+      tsLines.push(`export const ${safe}Events = {`)
+      for (const evt of events) {
+        tsLines.push(`  on${safeIdent(evt.topic).replace(/^(.)/, (m) => m.toUpperCase())}(handler: (payload: ${evt.payT}) => void) {`)
+        tsLines.push(`    return palette.events.on(${JSON.stringify(ns + "#" + evt.topic)}, (payload) => handler(payload as ${evt.payT}))`)
+        tsLines.push(`  },`)
+      }
+      tsLines.push(`}\n`)
+    }
+  }
+  const tsDir = path.join(cwd, ".palette", "types")
+  ensureDir(tsDir)
+  fs.writeFileSync(path.join(tsDir, "services.ts"), tsLines.join("\n"))
+
+  // ---- Python output
+  const pyParts = [pyHeader()]
+  for (const target of targets) {
+    const entry = byTarget.get(target)
+    if (!entry) continue
+    const safeNs = safeIdent(`${entry.namespace}_${entry.version}`)
+    const safeMethod = safeIdent(entry.method || entry.topic)
+    if (entry.kind === "service") {
+      const { code: inCode, ref: inRef } = jsonSchemaToPydantic(`${safeNs}_${safeMethod}_Input`, entry.input_schema)
+      const { code: outCode, ref: outRef } = jsonSchemaToPydantic(`${safeNs}_${safeMethod}_Output`, entry.output_schema)
+      if (inCode) pyParts.push(inCode)
+      if (outCode) pyParts.push(outCode)
+      pyParts.push(
+        `async def ${safeNs}_${safeMethod}(ctx, payload: ${inRef}) -> ${outRef}:\n` +
+          `    """Call ${entry.namespace}/${entry.version}#${entry.method}.\n\n` +
+          (entry.scope ? `    Scope: ${entry.scope}\n    """\n` : `    """\n`) +
+          `    return await _services.services(ctx).call(${JSON.stringify(target)}, payload if isinstance(payload, dict) else payload.model_dump())\n`,
+      )
+    } else if (entry.kind === "event") {
+      const { code: payCode, ref: payRef } = jsonSchemaToPydantic(`${safeNs}_${safeMethod}_Payload`, entry.payload_schema)
+      if (payCode) pyParts.push(payCode)
+      pyParts.push(
+        `def on_${safeNs}_${safeMethod}(handler):\n` +
+          `    """Subscribe to ${target}. Returns the underlying SDK subscribe call."""\n` +
+          `    from palette_sdk.events import subscribe_event\n` +
+          `    subscribe_event(${JSON.stringify(target)}, handler)\n`,
+      )
+    }
+  }
+  const pyDir = path.join(cwd, ".palette", "python")
+  ensureDir(pyDir)
+  fs.writeFileSync(path.join(pyDir, "services.py"), pyParts.join("\n"))
+
+  console.log(`[pltt] generated:`)
+  console.log(`  ${path.relative(cwd, path.join(tsDir, "services.ts"))}`)
+  console.log(`  ${path.relative(cwd, path.join(pyDir, "services.py"))}`)
+  if (missing.length) process.exit(2)
+}
+
+// ---- scaffold provider stub --------------------------------------------------
+
+async function runScaffold(argv, { cwd }) {
+  const positional = argv.filter((a) => !a.startsWith("-"))
+  const method = positional[0]
+  if (!method) {
+    console.error("[pltt] usage: pltt services scaffold <method>")
+    process.exit(1)
+  }
+  const manifest = readManifest(cwd)
+  const namespace = (manifest.provides && manifest.provides.namespace) || manifest.id
+  const provides = manifest.provides || {}
+  provides.namespace = namespace
+  provides.services = provides.services || []
+  // Ensure a default service slot.
+  let svc = provides.services.find((s) => (s.id || "") === method) || null
+  if (!svc) {
+    svc = { id: method, version: "v1", methods: [] }
+    provides.services.push(svc)
+  }
+  svc.methods = svc.methods || []
+  if (!svc.methods.find((m) => m && m.name === method)) {
+    svc.methods.push({
+      name: method,
+      scope: `${namespace}.${method}`,
+      input_schema: `schemas/${method}.in.json`,
+      output_schema: `schemas/${method}.out.json`,
+    })
+  }
+  manifest.provides = provides
+  writeManifest(cwd, manifest)
+
+  const schemasDir = path.join(cwd, "schemas")
+  ensureDir(schemasDir)
+  for (const suffix of ["in", "out"]) {
+    const p = path.join(schemasDir, `${method}.${suffix}.json`)
+    if (!fs.existsSync(p)) {
+      fs.writeFileSync(
+        p,
+        JSON.stringify(
+          {
+            $schema: "https://json-schema.org/draft/2020-12/schema",
+            type: "object",
+            properties: {},
+            required: [],
+          },
+          null,
+          2,
+        ) + "\n",
+      )
+    }
+  }
+
+  const brokerDir = path.join(cwd, "broker")
+  ensureDir(brokerDir)
+  const handlerPath = path.join(brokerDir, `${safeIdent(method)}.py`)
+  if (!fs.existsSync(handlerPath)) {
+    fs.writeFileSync(
+      handlerPath,
+      `from palette_sdk import service, PluginContext\n\n` +
+        `@service(${JSON.stringify(method)}, scope=${JSON.stringify(namespace + "." + method)})\n` +
+        `async def ${safeIdent(method)}(ctx: PluginContext, payload: dict) -> dict:\n` +
+        `    """Provider handler for ${namespace}/v1#${method}.\n\n` +
+        `    The OS broker validates payload against schemas/${method}.in.json and the\n` +
+        `    response against schemas/${method}.out.json before routing.\n    """\n` +
+        `    return {}\n`,
+    )
+  }
+  console.log(`[pltt] scaffolded ${namespace}/v1#${method}`)
+  console.log(`  manifest:  palette-plugin.json (updated)`)
+  console.log(`  schemas:   schemas/${method}.in.json, schemas/${method}.out.json`)
+  console.log(`  handler:   ${path.relative(cwd, handlerPath)}`)
+  console.log(`  import the handler from your backend entry to register it.`)
+}
+
+// ---- add consumed target -----------------------------------------------------
+
+async function runAdd(argv, { cwd }) {
+  const target = argv.find((arg) => !arg.startsWith("-"))
+  if (!target || !brokerTargetLooksValid(target)) {
+    console.error("[pltt] usage: pltt services add <namespace/version#name> [--event] [--optional] [--reason <text>]")
+    process.exit(1)
+  }
+  const manifest = readManifest(cwd)
+  manifest.consumes = manifest.consumes || {}
+  const bucket = argv.includes("--event") || valueAfter(argv, "--type") === "event" ? "events" : "services"
+  manifest.consumes[bucket] = manifest.consumes[bucket] || []
+  const existing = new Set(manifest.consumes[bucket].map(targetFromConsumeEntry).filter(Boolean))
+  if (!existing.has(target)) {
+    const reason = valueAfter(argv, "--reason")
+    const optional = argv.includes("--optional")
+    const entry = reason || optional ? { target, required: !optional, ...(reason ? { reason } : {}) } : target
+    manifest.consumes[bucket].push(entry)
+    writeManifest(cwd, manifest)
+    console.log(`[pltt] added ${target} to consumes.${bucket}`)
+  } else {
+    console.log(`[pltt] ${target} is already declared in consumes.${bucket}`)
+  }
+}
+
+// ---- dispatch ----------------------------------------------------------------
+
+async function run(argv, ctx) {
+  const sub = argv[0]
+  const rest = argv.slice(1)
+  if (sub === "list") return runList(rest, ctx)
+  if (sub === "pull") return runPull(rest, ctx)
+  if (sub === "scaffold") return runScaffold(rest, ctx)
+  if (sub === "add") return runAdd(rest, ctx)
+  console.log("pltt services <command>\n")
+  console.log("  list      Show services/events available to the current org.")
+  console.log("  pull      Generate typed TS+Python clients from consumes block.")
+  console.log("  scaffold  Add a new provider method + schemas + handler stub.")
+  console.log("  add       Add a consumed service/event target to palette-plugin.json.")
+  if (sub && !["help", "--help", "-h"].includes(sub)) {
+    console.error(`\n[pltt] unknown subcommand: ${sub}`)
+    process.exit(1)
+  }
+}
+
+module.exports = run

package/lib/commands/test.js

@@ -5,7 +5,7 @@ const path = require("path")
 const { spawnSync } = require("child_process")
 const { loadManifest, validateManifest, KNOWN_PERMISSIONS } = require("../manifest")
 const { bundleFrontend, bundleBackend } = require("../bundler")
-const { declaredSecrets, loadLocalEnv } = require("../secrets")
+const { declaredSecrets, loadLocalEnv, loadLocalEnvDetails } = require("../secrets")
 const buildCommand = require("./build")
 
 const DEFAULT_FRONTEND_BUNDLE_LIMIT = 15 * 1024 * 1024
@@ -664,31 +664,32 @@ function checkDeclaredSecrets(cwd, manifest, out) {
     out.ok("no manifest secrets declared")
     return 0
   }
-  const localValues = loadLocalEnv(cwd, { apply: false })
+  const localEnv = loadLocalEnvDetails(cwd, { apply: false })
+  const localValues = localEnv.values
   let failures = 0
   for (const [name, spec] of Object.entries(declared)) {
     if (spec.scope.includes("dev") && spec.required && !localValues[name]) {
       out.warn(
-        `required dev secret ${name} is missing from .palette/.env.local`,
-        "Run pltt secrets init and fill the local value before pltt dev.",
+        `required dev secret ${name} is missing from local .env files`,
+        "Add it to .env, .env.local, or an environment-specific .env file.",
         { secret: name, scope: spec.scope },
       )
     }
     if (spec.scope.includes("plugin") && spec.required && !localValues[name] && !process.env[name]) {
       out.warn(
         `required plugin secret ${name} has no local value`,
-        "Set it before publish with an env var, --secrets-file, or pltt secrets set.",
+        "Add it to .env/.env.local, set an env var, pass --secrets-file, or run pltt secrets set.",
         { secret: name, scope: spec.scope },
       )
     }
   }
-  if (!fs.existsSync(path.join(cwd, ".palette", ".env.local"))) {
+  if (!localEnv.files.length) {
     out.warn(
-      ".palette/.env.local is missing",
-      "Run pltt secrets init to create local developer env files.",
+      "no local .env files found",
+      "Create .env or .env.local when your app needs local environment values.",
     )
   } else {
-    out.ok(".palette/.env.local is present")
+    out.ok(`local env files present: ${localEnv.files.join(", ")}`)
   }
   out.ok(`manifest declares ${names.length} secret(s)`, { secrets: names })
   return failures

package/lib/manifest.js

@@ -53,6 +53,7 @@ const TOP_LEVEL_KEYS = new Set([
   "platform_services",
   "provides",
   "requires",
+  "consumes",
 ])
 
 function loadManifest(cwd) {
@@ -237,6 +238,10 @@ function isCapabilityId(value) {
   return typeof value === "string" && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value)
 }
 
+function isBrokerTarget(value) {
+  return typeof value === "string" && /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+#[A-Za-z0-9_.-]+$/.test(value)
+}
+
 function validateServiceRoutes(value, label, errors) {
   if (value === undefined) return
   if (!Array.isArray(value)) {
@@ -262,13 +267,63 @@ function validateServiceRoutes(value, label, errors) {
   })
 }
 
+function validateServiceMethods(value, label, errors) {
+  if (value === undefined) return
+  if (!Array.isArray(value)) {
+    errors.push(`${label}.methods must be an array`)
+    return
+  }
+  const methods = new Set(["GET", "POST", "PUT", "PATCH", "DELETE"])
+  const seen = new Set()
+  value.forEach((method, i) => {
+    const methodLabel = `${label}.methods[${i}]`
+    if (!isObject(method)) {
+      errors.push(`${methodLabel} must be an object`)
+      return
+    }
+    unknownKeys(
+      method,
+      new Set([
+        "name",
+        "scope",
+        "label",
+        "description",
+        "input_schema",
+        "input",
+        "output_schema",
+        "output",
+        "route_method",
+        "route_path",
+      ]),
+      methodLabel,
+      errors,
+    )
+    if (typeof method.name !== "string" || !/^[A-Za-z0-9_.-]+$/.test(method.name)) {
+      errors.push(`${methodLabel}.name must be a broker method name`)
+    } else if (seen.has(method.name)) {
+      errors.push(`duplicate provided method name: ${method.name}`)
+    }
+    seen.add(method.name)
+    for (const key of ["scope", "label", "description", "input_schema", "input", "output_schema", "output", "route_path"]) {
+      requireString(method, key, methodLabel, errors)
+    }
+    if (method.route_method !== undefined && !methods.has(String(method.route_method).toUpperCase())) {
+      errors.push(`${methodLabel}.route_method must be one of ${Array.from(methods).join(", ")}`)
+    }
+    if (method.route_path !== undefined && (typeof method.route_path !== "string" || !method.route_path.startsWith("/"))) {
+      errors.push(`${methodLabel}.route_path must start with '/'`)
+    }
+  })
+}
+
 function validateProvides(value, errors) {
   if (value === undefined) return
   if (!isObject(value)) {
     errors.push("provides must be an object")
     return
   }
-  unknownKeys(value, new Set(["services", "events"]), "provides", errors)
+  unknownKeys(value, new Set(["namespace", "services", "events"]), "provides", errors)
+  requireString(value, "namespace", "provides", errors)
   if (value.services !== undefined) {
     if (!Array.isArray(value.services)) {
       errors.push("provides.services must be an array")
@@ -280,7 +335,7 @@ function validateProvides(value, errors) {
           errors.push(`${label} must be an object`)
           return
         }
-        unknownKeys(service, new Set(["id", "version", "label", "description", "permissions", "routes"]), label, errors)
+        unknownKeys(service, new Set(["id", "version", "label", "description", "permissions", "routes", "methods"]), label, errors)
         if (!isCapabilityId(service.id)) {
           errors.push(`${label}.id must be a dotted lowercase capability id`)
         } else if (seen.has(service.id)) {
@@ -302,6 +357,7 @@ function validateProvides(value, errors) {
           }
         }
         validateServiceRoutes(service.routes, label, errors)
+        validateServiceMethods(service.methods, label, errors)
       })
     }
   }
@@ -309,9 +365,29 @@ function validateProvides(value, errors) {
     if (!Array.isArray(value.events)) {
       errors.push("provides.events must be an array")
     } else {
-      for (const event of value.events) {
-        if (!isCapabilityId(event)) errors.push(`provides.events entries must be dotted lowercase topics: ${event}`)
-      }
+      const seen = new Set()
+      value.events.forEach((event, i) => {
+        const label = `provides.events[${i}]`
+        let topic
+        if (typeof event === "string") {
+          topic = event
+        } else if (isObject(event)) {
+          unknownKeys(event, new Set(["topic", "name", "version", "payload_schema", "schema", "description"]), label, errors)
+          topic = event.topic || event.name
+          for (const key of ["version", "payload_schema", "schema", "description"]) {
+            requireString(event, key, label, errors)
+          }
+        } else {
+          errors.push(`${label} must be a topic string or object`)
+          return
+        }
+        if (!isCapabilityId(topic)) {
+          errors.push(`${label}.topic must be a dotted lowercase topic`)
+        } else if (seen.has(topic)) {
+          errors.push(`duplicate provided event topic: ${topic}`)
+        }
+        seen.add(topic)
+      })
     }
   }
 }
@@ -375,6 +451,44 @@ function validateRequires(value, errors) {
   }
 }
 
+function validateConsumes(value, errors) {
+  if (value === undefined) return
+  if (!isObject(value)) {
+    errors.push("consumes must be an object")
+    return
+  }
+  unknownKeys(value, new Set(["services", "events"]), "consumes", errors)
+  for (const bucket of ["services", "events"]) {
+    if (value[bucket] === undefined) continue
+    if (!Array.isArray(value[bucket])) {
+      errors.push(`consumes.${bucket} must be an array`)
+      continue
+    }
+    const seen = new Set()
+    value[bucket].forEach((entry, i) => {
+      const label = `consumes.${bucket}[${i}]`
+      let target
+      if (typeof entry === "string") {
+        target = entry
+      } else if (isObject(entry)) {
+        unknownKeys(entry, new Set(["target", "required", "reason"]), label, errors)
+        target = entry.target
+        requireBoolean(entry, "required", label, errors)
+        requireString(entry, "reason", label, errors)
+      } else {
+        errors.push(`${label} must be a broker target string or object`)
+        return
+      }
+      if (!isBrokerTarget(target)) {
+        errors.push(`${label}.target must look like namespace/version#name`)
+        return
+      }
+      if (seen.has(target)) errors.push(`duplicate consumed ${bucket.slice(0, -1)} target: ${target}`)
+      seen.add(target)
+    })
+  }
+}
+
 function validateManifest(m) {
   const errors = []
   if (!isObject(m)) return ["manifest must be an object"]
@@ -445,6 +559,7 @@ function validateManifest(m) {
   validatePlatformServices(m.platform_services, errors)
   validateProvides(m.provides, errors)
   validateRequires(m.requires, errors)
+  validateConsumes(m.consumes, errors)
 
   if (m.sdk) {
     if (!isObject(m.sdk)) errors.push("sdk must be an object")

package/lib/secrets.js

@@ -6,6 +6,22 @@ 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 RESERVED_AUTO_ENV_KEYS = new Set([
+  "CI",
+  "HOME",
+  "HOST",
+  "HOSTNAME",
+  "LOGNAME",
+  "NODE_ENV",
+  "OLDPWD",
+  "PATH",
+  "PORT",
+  "PWD",
+  "SHELL",
+  "TERM",
+  "TMPDIR",
+  "USER",
+])
 
 function parseDotEnv(src) {
   const values = {}
@@ -31,6 +47,50 @@ function readDotEnvFile(filePath) {
   return parseDotEnv(fs.readFileSync(filePath, "utf8"))
 }
 
+function unique(items) {
+  return Array.from(new Set(items.filter(Boolean)))
+}
+
+function envFileNames(environment) {
+  return unique([
+    ".env",
+    ".env.local",
+    environment ? `.env.${environment}` : null,
+    environment ? `.env.${environment}.local` : null,
+  ])
+}
+
+function loadRootEnvFiles(cwd, { environment } = {}) {
+  const values = {}
+  const files = []
+  for (const name of envFileNames(environment || process.env.PALETTE_ENV)) {
+    const filePath = path.join(cwd, name)
+    if (!fs.existsSync(filePath)) continue
+    Object.assign(values, readDotEnvFile(filePath))
+    files.push(name)
+  }
+  return { values, files }
+}
+
+function loadLocalEnvDetails(cwd, { apply = true, environment, includePalette = true } = {}) {
+  const root = loadRootEnvFiles(cwd, { environment })
+  const values = { ...root.values }
+  const files = [...root.files]
+  if (includePalette) {
+    const palettePath = path.join(cwd, LOCAL_ENV_PATH)
+    if (fs.existsSync(palettePath)) {
+      Object.assign(values, readDotEnvFile(palettePath))
+      files.push(LOCAL_ENV_PATH)
+    }
+  }
+  if (apply) {
+    for (const [key, value] of Object.entries(values)) {
+      if (process.env[key] === undefined) process.env[key] = value
+    }
+  }
+  return { values, files }
+}
+
 function formatDotEnvValue(value) {
   if (value === undefined || value === null) return ""
   const str = String(value)
@@ -132,14 +192,25 @@ function initLocalEnv(cwd, manifest, { overwrite = false } = {}) {
   return { localPath, examplePath, declared }
 }
 
-function loadLocalEnv(cwd, { apply = true } = {}) {
-  const values = readDotEnvFile(path.join(cwd, LOCAL_ENV_PATH))
-  if (apply) {
-    for (const [key, value] of Object.entries(values)) {
-      if (process.env[key] === undefined) process.env[key] = value
-    }
-  }
-  return values
+function loadLocalEnv(cwd, { apply = true, environment, includePalette = true } = {}) {
+  return loadLocalEnvDetails(cwd, { apply, environment, includePalette }).values
+}
+
+function isPublicEnvKey(key) {
+  return key.startsWith("NEXT_PUBLIC_")
+}
+
+function isReservedAutoEnvKey(key) {
+  return (
+    RESERVED_AUTO_ENV_KEYS.has(key) ||
+    key.startsWith("PALETTE_") ||
+    key.startsWith("npm_") ||
+    key.startsWith("NPM_")
+  )
+}
+
+function canAutoUploadEnvKey(key) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(key) && !isPublicEnvKey(key) && !isReservedAutoEnvKey(key)
 }
 
 function redactValue(value) {
@@ -156,9 +227,13 @@ module.exports = {
   declaredSecrets,
   ensureGitignore,
   initLocalEnv,
+  loadLocalEnvDetails,
   loadLocalEnv,
   parseDotEnv,
   readDotEnvFile,
   redactValue,
   secretsForScope,
+  canAutoUploadEnvKey,
+  isPublicEnvKey,
+  isReservedAutoEnvKey,
 }

package/package.json

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