Files
archived-orca/src/shared/plugins/plugin-manifest.ts
T
Neil 5018241866 feat(plugins): app and terminal themes in one Theme list, painted safely (#30719)
* plugins: app and terminal theme contributions

Manifests can contribute themes (public CSS tokens over a light or dark
base) and terminal themes (an ANSI palette), each at most 16 KiB. App
themes must set --background and --foreground; omitted tokens are derived
from them (surfaces copy the background, muted text, borders and accents
mix the foreground into it), and values must be colors (no keywords,
lengths, calc, var or url). Both load through the shared artifact-pack
registry with the plugin's display name and a content revision, reach the
renderer over IPC and are re-validated there. Catalog releases can declare
app-theme and terminal-theme, and marketplaces stop hiding theme listings.
docs/reference/plugin-themes.md documents the format.

* plugins: resolve a selected plugin terminal palette on every host

Selecting a plugin terminal theme saves a copy of its palette in settings
(terminalPluginPalettes). The shared lookup reads it, so main, headless
serve and relays answer terminal color queries and native chat matches the
terminal without the plugin loaded; a malformed snapshot falls back to the
default theme.

* plugins: one Theme list with plugin themes, painted safely

Appearance keeps the System/Dark/Light control until a plugin offers a
theme; then Theme becomes one list with plugin themes after a divider,
labelled with the publisher when names collide. Choosing one stores its
base in theme and remembers the earlier built-in choice, which comes back
while the plugin is off or after it is uninstalled; a plugin update that
changes the base re-syncs theme. It also offers the plugin's terminal
colors in one click.

The renderer paints only values CSS parses as colors, checks every
text/surface pair, ring and border against the effective set (plugin
values over this mode's built-ins) and repeats until nothing changes, so
dropping one pair cannot expose another. The applied theme is cached with
its id and revision, painted before first render, and dropped as soon as
settings show it no longer applies. Main bounds the new settings on every
write and load, and uninstalling a plugin clears its theme choices and
palette copies. Terminal themes appear under Plugins in the picker with the
plugin's name and are passed to lookups instead of read from a store.

* plugins: type the theme settings normalizer input; let the store own its normalization

* fix(plugins): check text contrast on the editor surface and clear terminal overrides when adopting a theme's terminal colors

* fix(plugins): reject theme colors the canvas probe silently ignores
2026-10-28 15:13:10 -07:00

197 lines
7.3 KiB
TypeScript

import { z } from 'zod'
import { pluginCapabilitySchema } from './plugin-capabilities'
import {
PLUGIN_AGENT_PROFILE_LIMIT,
PLUGIN_KEYBINDING_LIMIT,
PLUGIN_LANGUAGE_PACK_LIMIT,
PLUGIN_TERMINAL_THEME_LIMIT,
PLUGIN_THEME_LIMIT,
PLUGIN_VM_RECIPE_LIMIT,
pluginAgentProfileContributionSchema,
pluginKeybindingContributionSchema,
pluginLanguagePackContributionSchema,
pluginThemeContributionSchema,
pluginVmRecipeContributionSchema
} from './plugin-content-pack-contributions'
import {
pluginCommandIdSchema,
pluginIdSchema,
pluginRelativePathSchema
} from './plugin-manifest-fields'
import { validatePluginManifestContributions } from './plugin-manifest-contribution-validation'
import {
pluginExecutionProfileSchema,
validatePluginExecutionProfile
} from './plugin-execution-profile'
/**
* Plugin manifest v1 and v2 (`orca-plugin.json` at the plugin root). The
* `contributes` key names deliberately mirror common Electron-ecosystem
* manifest conventions so future adapters stay cheap.
*
* Lives in `shared` so the desktop app, the headless `orca serve` runtime,
* the relay, and the CLI validate manifests identically (SSH/remote parity).
*
* Everything here is EXPERIMENTAL: no compatibility promises until pluginApi
* v1 freezes (see the plugin roadmap).
*/
const SEMVER_RE =
/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/
export const PLUGIN_PANEL_LIMIT = 64
export const PLUGIN_COMMAND_LIMIT = 256
// Closed >=x.y.z grammar keeps v0 gating predictable; richer ranges can be added later.
const orcaEngineRangeSchema = z
.string()
.max(64)
.regex(/^>=\d+\.\d+\.\d+$/, 'must be a ">=x.y.z" version range')
const panelContributionSchema = z.object({
id: pluginIdSchema,
title: z.string().min(1).max(256),
/** Lucide icon name rendered in the right-sidebar activity bar. */
icon: z.string().min(1).max(64).optional(),
/** HTML entry rendered inside a sandboxed panel frame. */
entry: pluginRelativePathSchema
})
const commandContributionSchema = z.object({
id: pluginCommandIdSchema,
title: z.string().min(1).max(256),
context: z.enum(['global', 'worktree']).optional(),
/** Built-in action aliases remain declarative and do not activate a worker. */
action: pluginCommandIdSchema.optional()
})
/** Closed event set permits server-side filtering to only subscribed events. */
export const PLUGIN_EVENT_NAMES = [
'worktree.created',
'worktree.removed',
'agent.status.changed'
] as const
export const PLUGIN_EVENT_SUBSCRIPTION_LIMIT = PLUGIN_EVENT_NAMES.length
export type PluginEventName = (typeof PLUGIN_EVENT_NAMES)[number]
const eventContributionSchema = z.object({
on: z.enum(PLUGIN_EVENT_NAMES)
})
const pluginManifestV1Object = z.object({
manifestVersion: z.literal(1),
id: pluginIdSchema,
/** Qualify as publisher.id: bare-id global uniqueness cannot be verified without a registry. */
publisher: pluginIdSchema,
name: z.string().min(1).max(256),
version: z.string().regex(SEMVER_RE, 'must be semver'),
description: z.string().max(4096).optional(),
author: z
.object({ name: z.string().min(1).max(256), url: z.string().max(2048).optional() })
.optional(),
repository: z.string().max(2048).optional(),
icon: pluginRelativePathSchema.optional(),
/** Minimum host version gate; the host refuses to load below it. */
engines: z.object({ orca: orcaEngineRangeSchema }),
/** Host-API major version this plugin targets. */
pluginApi: z.literal(1),
/** Node entry executed inside the out-of-process plugin worker. */
main: pluginRelativePathSchema.optional(),
contributes: z
.object({
panels: z.array(panelContributionSchema).max(PLUGIN_PANEL_LIMIT).default([]),
commands: z.array(commandContributionSchema).max(PLUGIN_COMMAND_LIMIT).default([]),
events: z.array(eventContributionSchema).max(PLUGIN_EVENT_SUBSCRIPTION_LIMIT).default([]),
languagePacks: z
.array(pluginLanguagePackContributionSchema)
.max(PLUGIN_LANGUAGE_PACK_LIMIT)
.default([]),
keybindings: z
.array(pluginKeybindingContributionSchema)
.max(PLUGIN_KEYBINDING_LIMIT)
.default([]),
vmRecipes: z.array(pluginVmRecipeContributionSchema).max(PLUGIN_VM_RECIPE_LIMIT).default([]),
agents: z
.array(pluginAgentProfileContributionSchema)
.max(PLUGIN_AGENT_PROFILE_LIMIT)
.default([]),
themes: z.array(pluginThemeContributionSchema).max(PLUGIN_THEME_LIMIT).default([]),
terminalThemes: z
.array(pluginThemeContributionSchema)
.max(PLUGIN_TERMINAL_THEME_LIMIT)
.default([])
})
.strict()
// Why prefault: runs `{}` through the schema, so every family's own default applies.
.prefault({}),
capabilities: z.array(pluginCapabilitySchema).max(32).default([])
})
// Why strict: v2 declares its execution profile, so unknown keys must not smuggle in behavior.
const pluginManifestV2Object = pluginManifestV1Object
.extend({ manifestVersion: z.literal(2), execution: pluginExecutionProfileSchema })
.strict()
export const pluginManifestSchema = z.discriminatedUnion('manifestVersion', [
pluginManifestV1Object.superRefine(validatePluginManifestContributions),
pluginManifestV2Object.superRefine((manifest, ctx) => {
validatePluginManifestContributions(manifest, ctx)
validatePluginExecutionProfile(manifest, ctx)
})
])
export type PluginManifest = z.infer<typeof pluginManifestSchema>
export type PluginPanelContribution = z.infer<typeof panelContributionSchema>
export type PluginCommandContribution = z.infer<typeof commandContributionSchema>
export type PluginEventContribution = z.infer<typeof eventContributionSchema>
export {
isSafePluginId,
PLUGIN_ID_MAX_LENGTH,
pluginCommandIdSchema
} from './plugin-manifest-fields'
export const PLUGIN_MANIFEST_FILENAME = 'orca-plugin.json'
/** Canonical install identity: `<publisher>.<id>` (also the install dir name). */
export function qualifiedPluginKey(manifest: Pick<PluginManifest, 'publisher' | 'id'>): string {
return `${manifest.publisher}.${manifest.id}`
}
export type PluginManifestParseResult =
| { ok: true; manifest: PluginManifest }
| { ok: false; error: string }
export function parsePluginManifest(raw: unknown): PluginManifestParseResult {
const parsed = pluginManifestSchema.safeParse(raw)
if (parsed.success) {
return { ok: true, manifest: parsed.data }
}
const issue = parsed.error.issues[0]
const path = issue?.path.join('.') || '(root)'
return { ok: false, error: `${path}: ${issue?.message ?? 'invalid manifest'}` }
}
/** v0 engines gate: supports the ">=x.y.z" grammar the schema enforces.
* Prerelease/build suffixes on the host version are ignored for ordering. */
export function satisfiesOrcaEngineRange(hostVersion: string, range: string): boolean {
const minimum = range.slice(2)
const parse = (value: string): number[] =>
value
.split(/[-+]/)[0]!
.split('.')
.map((part) => Number.parseInt(part, 10) || 0)
const host = parse(hostVersion)
const min = parse(minimum)
for (let i = 0; i < 3; i++) {
const a = host[i] ?? 0
const b = min[i] ?? 0
if (a !== b) {
return a > b
}
}
return true
}
export { isPluginPanelTabKey, isQualifiedPluginKey, pluginPanelTabKey } from './plugin-tab-key'