Plugin Kit

@channek/plugin-kit is a zero-runtime-dependency kernel for manifest-driven plugin systems. It contains no UI framework, filesystem, desktop-shell, or product extension-point knowledge.

Manifest protocol

A manifest declares identity, compatibility, trust, dependencies, extension points, and contributions. validateManifest performs structural validation and returns ok, error, or incompatible plus stable rule-tagged issues. Unknown top-level fields and contribution points are warnings so older hosts remain forward compatible. Known declarations with an unknown enum value are handled at the owning extension point as a V15 warning and skipped individually.

Trust is explicit:

• declarative manifests contain data only and cannot declare entries, permissions, or an API.
• sandboxed manifests require API version 1 and a sandbox entry.
• privileged manifests require API version 1 and a main entry; they may also expose sandbox UI.

All asset paths are plugin-root relative. Dependency ranges intentionally support only exact three-part versions and >=x.y.z.

Extension points and registry

Hosts define an ExtensionPointDefinition with a mode, owner, fail-closed declaration validator, and whether an implementation is required. Plugins may define their own points with a small declarative schema. Assembly has two passes: register every point, then register contributions.

PluginRegistry stores declarations independently from implementations. It supports:

• typed and string point lookup;
• implementation bindings returned as Disposable values;
• point refinements after activation;
• reversible enable/disable without rebuilding declarations;
• plugin removal and exact-point change events;
• stable contribution arbitration and single-point user choices.

Consumers must retain a host fallback for every optional contribution.

Lifecycle

DisposableStore releases subscriptions in reverse order and is idempotent. PluginContext provides logging, normalized settings, subscriptions, and dependency exports. The exports registry lets dependency reads wait for activation and resolves optional or failed dependencies as undefined.

Loader port

PluginLoader is the discovery boundary. It returns validated LoadedPlugin records with a scope, resource root URL, and issues. Discovery and filesystem policy stay in the host; this package only defines the port.

Utilities

• evaluateWhen supports equality, inequality, and conjunction over a fixed host-state key set.
• normalizePluginSettings applies defaults and type/range constraints only when reading. It never mutates or rewrites raw persisted data.
• resolveDependencies returns activation order, unresolved reasons, and cycles.
• schema/plugin-manifest.schema.json is the draft-07 authoring schema.

Run pnpm test, pnpm typecheck, and pnpm run lint:purity before publishing a change.