@adea-ai/plugins
The marketplace toolkit for AI agent plugin catalogs, published as one package. Parse marketplace sources, verify provenance against pinned Git trees, merge into a canonical catalog, compile provenance-checked static artifacts, and produce per-harness installation plans. The package does not install plugin files into a runtime or execute upstream content. Its materialization functions return in-memory package bytes or structured plans; they do not write to a harness or start an MCP server or command.
Install
bun add @adea-ai/plugins
Version 4 migration
Import portable planning from @adea-ai/plugins/harness, not the removed
@adea-ai/plugins/agent-plugins/harness subpath. The legacy materialization API
has been removed: use createCatalogInstallationPlan or createInstallationPlan
with the required instance identity and negotiated harness profile. A returned
plan describes work; it does not grant activation permission.
Entry points
| Import | Contents |
|---|---|
@adea-ai/plugins | Catalog compilation, artifacts, integrity, and last-known-good publication. |
@adea-ai/plugins/schema | Zod-backed versioned contracts and runtime parsing. |
@adea-ai/plugins/sources | OpenAI, Cursor, and Claude marketplace dialects, ref normalization, path and URL gates. |
@adea-ai/plugins/harness | Capability-negotiated v2 plans and MCP launch descriptors; no process launch. |
@adea-ai/plugins/publication | Where a published catalog lives, and the URLs that address it. |
@adea-ai/plugins/portable-catalog | Offline synchronization and verification against a source lock. |
@adea-ai/plugins/agent-plugins | Canonical package compilation. |
@adea-ai/plugins/agent-plugins/schema | Agent plugin and harness profile schemas. |
The former @adea-ai/catalog-core, @adea-ai/catalog-schema,
@adea-ai/source-adapters, and @adea-ai/harness-adapters packages are
consolidated here. Their dependency graph was already total, so they versioned
in lockstep; the subpaths above keep each surface addressable on its own.
What's inside
- Catalog compilation: merge parsed marketplace sources into one canonical, policy-checked catalog.
- Integrity verification: sha256 content digests, SHA-pinned Git trees,
and
verifyArtifactsfor published artifact sets. - Publication artifacts:
catalog.v1.json,catalog-summary.v1.json,categories.v1.json,compatibility.v1.json,sources.lock.json, andintegrity.jsonwith deterministic serialization. - Policy enforcement: repository protocol/host allowlists and source trust classification.
- Harness planning: v2 installation plans keyed by stable instance data, plus MCP launch and connect descriptors. These describe proposed file and binding operations; they do not authorize or perform an installation.
The catalog is not in this package
A catalog snapshot is roughly 38 MB and changes whenever an upstream
marketplace moves, several times a day. Shipping it inside a semver package
would force a toolkit release on every data change and churn every consumer's
lockfile, so the catalog is published to the content-addressed catalog-assets
branch instead. @adea-ai/plugins addresses those URLs; it does not embed
them. See the consumer contract.
Usage
import { verifyArtifacts } from '@adea-ai/plugins'
import { catalogSnapshotBaseUrl } from '@adea-ai/plugins/publication'
Direct callers of verifyShardArtifact must supply the expected catalog ID as
its fourth argument, obtained from a separately verified catalog. Earlier
three-argument calls did not check shard catalog identity; they now fail with
SHARD_CATALOG_ID_REQUIRED. Callers that verify a complete artifact set can use
verifyArtifacts, which supplies the catalog ID internally.
import { verifyShardArtifact } from '@adea-ai/plugins'
// `verifiedCatalog` is the catalog whose identity and provenance the caller verified.
verifyShardArtifact(shard, shardContent, verification, verifiedCatalog.catalogId)
Design rules
- Same inputs, same bytes: compilation is deterministic and offline-safe.
- Every artifact carries provenance;
sources.lock.jsonpins the exact Git trees and digests a catalog was built from. - The compiler is a metadata and planning boundary. It never installs or executes upstream plugins, hooks, MCP servers, lifecycle scripts, or binaries.
License
Apache-2.0