zidane/plugins

Default parent of every plugin's ${PLUGIN_DATA} directory.

Deliberately OUTSIDE any plugin root: the spec requires the data directory to persist across plugin updates, and an update replaces the package tree. Keyed by plugin name so two copies of the same plugin (project + user) share state, which is what an author storing a cache or a token expects.

Routed through resolveStorageDirs rather than hardcoding ~/.zidane so it honours ZIDANE_STORAGE_DIR and the XDG dirs like every other persisted location — otherwise an XDG-mode install would scatter plugin data into a ~/.zidane nothing else in the app touches.

NB: resolveStorageDirs does NOT read ZIDANE_PREFIX; it defaults prefix to .zidane. Callers with a configured prefix must pass it, or plugin data lands beside a prefix the rest of the install doesn't use.

function defaultPluginDataRoot(opts?: ResolveStorageDirsOptions): string

Substitute the two reserved placeholders in one string.

Single-pass by construction (String.replace never re-scans its own output), so a ${PLUGIN_ROOT} whose value somehow contained ${PLUGIN_DATA} cannot expand twice. Unknown ${...} text is left verbatim: the spec defines exactly two placeholders, and silently blanking anything else would corrupt legitimate literals.

function expandPluginVars(value: string, vars: Record<string, string>): string

Parse manifest text, then validate it.

A JSON syntax error is fatal — unlike mcps.json (where parseJsonTolerant repairs copy-paste whitespace artifacts), a plugin manifest is a package file produced by a build or an author's editor, not pasted into a settings box. Repairing it would mean guessing at the contents of a third-party package.

function parsePluginManifest(text: string): ManifestValidation

Split a canonical $schema identifier into its document kind + version. Returns null for anything that isn't a canonical identifier; the caller decides whether that's fatal (manifest) or component-scoped (mcp.json).

Purely syntactic: it never fetches. The spec forbids retrieving a schema during load, so version support is a lookup against SUPPORTED_AGENT_PLUGINS_VERSIONS, not a download.

function parseSchemaId(
  value: string,
): { kind: PluginSchemaKind; version: string } | null

Validate an already-parsed manifest value against the closed 1.0.0 schema.

Fatal violations short-circuit: $schema and name are checked first because without them there is no contract to validate against and no identity to report problems under.

function validatePluginManifest(raw: unknown): ManifestValidation

Agent Plugins spec versions this loader implements, newest first.

The spec requires clients to select validation rules from the manifest's $schema WITHOUT retrieving it, and to let plugins keep targeting older versions under a locally supported compatibility policy. Our policy: a version is supported iff it appears in this list. Adding 1.1.0 later means adding it here plus any rule deltas in ./manifest — never reinterpreting an already-published identifier, which the spec forbids.

const SUPPORTED_AGENT_PLUGINS_VERSIONS: readonly ['1.0.0']

A load-time finding. Mirrors SkillDiagnostic's shape (severity + stable code + message) so host UIs already rendering skill diagnostics can render these with no new plumbing.

severity: 'error' on a returned plugin means a narrow boundary fired (a component type disabled, a skill skipped) — NOT that the whole plugin failed. Plugin-level rejection is signalled by LoadedPlugin.ok === false.

interface PluginDiagnostic

A validated plugin.json. Only spec fields survive validation — unknown top-level keys are reported and dropped, so consumers can never accidentally depend on a non-portable field.

version here is the PLUGIN's own version string; the spec version selected by $schema lands on PluginManifest.specVersion.

interface PluginManifest

Per-component-type outcome. The spec insists a missing fixed location is NOT an error, and that an invalid one disables only its own component type — so these four states are load-bearing, not cosmetic:

• absent fixed location not present. Valid.
• loaded discovered (possibly zero entries, e.g. an empty skills/).
• invalid wrong filesystem kind, or the location escaped the root.
• unsupported never discovered — not implemented by this client, disabled by the caller, or the plugin was rejected before component discovery ran.

type PluginComponentStatus = 'absent' | 'loaded' | 'invalid' | 'unsupported'