@palettelab/cli 0.3.48 → 0.3.50

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
@@ -757,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,
     })
   }
 
@@ -786,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/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,
+}