Plugin manifest schema and validation for Refarm plugin ecosystem.
npm install @refarm.dev/plugin-manifestCreate plugin-manifest.json in your plugin root:
{
"id": "@mycompany/my-plugin",
"name": "My Awesome Plugin",
"version": "1.0.0",
"entry": "./dist/index.js",
"capabilities": {
"provides": ["storage:v1"],
"requires": ["kernel:events"]
},
"permissions": ["storage:read", "storage:write"],
"observability": {
"hooks": ["onLoad", "onInit", "onRequest", "onError", "onTeardown"]
}
}import {
validatePluginManifest,
assertValidPluginManifest,
} from "@refarm.dev/plugin-manifest";
import manifestJson from "./plugin-manifest.json";
// Option 1: Get validation result
const result = validatePluginManifest(manifestJson);
if (!result.valid) {
console.error("Manifest errors:", result.errors);
}
// Option 2: Assert (throws on invalid)
try {
assertValidPluginManifest(manifestJson);
console.log("Manifest is valid!");
} catch (error) {
console.error("Invalid manifest:", error.message);
}import { validatePluginManifest } from "@refarm.dev/plugin-manifest";
import manifest from "../plugin-manifest.json";
describe("Plugin manifest", () => {
it("is valid", () => {
const result = validatePluginManifest(manifest);
expect(result.valid).toBe(true);
});
});id: Scoped package name (e.g.,@vendor/plugin-name)name: Human-readable name (min 3 chars)version: Semantic version (e.g.,1.2.3)entry: Relative path to entry point (e.g.,./dist/index.js)capabilities.provides: Array of capabilities this plugin implementscapabilities.requires: Array of capabilities needed from kernel/other pluginspermissions: Array of permission stringsobservability.hooks: Array of telemetry hooks
All plugins MUST implement these hooks:
onLoad: Called when plugin is loadedonInit: Called when plugin initializesonRequest: Called on each capability requestonError: Called when errors occuronTeardown: Called when plugin unloads
Plugins may declare additive extension surfaces under extensions.surfaces so one package can expose UI, headless, automation, desktop, agent, or asset affordances without forcing every host to execute them:
{
"extensions": {
"surfaces": [
{
"layer": "homestead",
"kind": "panel",
"id": "stream-renderer",
"slot": "session-view",
"capabilities": ["ui:panel:render", "ui:stream:read"]
},
{
"layer": "asset",
"kind": "theme-pack",
"id": "stream-themes",
"assets": ["./themes/default.json"]
}
]
}
}Valid surface layers are tractor, homestead, pi, automation, desktop, and asset. Unknown hosts must ignore unknown surfaces safely; hosts that understand a surface still need to enforce capabilities, integrity, and trust policy before activation. Homestead panels that execute renderHomesteadSurface(request) should declare ui:panel:render; host-owned actions are exposed at runtime through request.host.actions and rendered controls identify the chosen action with data-refarm-surface-action-id. See docs/EXTENSIBILITY_MODEL.md in the monorepo for the long-term model.
pi skill surfaces have an additional central gate. A declaration with
layer: "pi" and kind: "skill" must carry non-empty capabilities, must not
declare a UI slot, and must include at least one relative package asset ending
in SKILL.md. This keeps local file: skill drafts and package-distributed
skill surfaces distinct before any runtime host evaluates the skill contract.
Host-neutral helpers are exported for discovery:
import {
extensionSurfaceKey,
getExtensionSurfaces,
isExtensionSurfaceLayer,
} from "@refarm.dev/plugin-manifest";
const homesteadSurfaces = getExtensionSurfaces(manifest, "homestead");Returns validation result with errors list.
Throws error if manifest is invalid.
interface PluginManifest {
id: string;
name: string;
version: string;
entry: string;
capabilities: PluginCapabilities;
permissions: string[];
observability: {
hooks: TelemetryHook[];
};
}
interface PluginCapabilities {
provides: string[];
requires: string[];
}
type TelemetryHook =
| "onLoad"
| "onInit"
| "onRequest"
| "onError"
| "onTeardown";idmust be scoped (@vendor/name)namemust be at least 3 charactersversionmust be valid semverentrymust be relative.js/.mjs/.cjsor.wasmpath (absolute paths are rejected).wasmentries must declareintegrityassha256-<base64|64hex>capabilities.providesmust have at least one capability- No duplicates in provides/requires/permissions/APIs
targetsmust be a non-empty array using onlybrowser,server,remote- All required telemetry hooks must be declared
- Optional
extensions.surfacesentries must use a known layer, non-emptykind/id, valid optional string arrays, and uniquelayer/idpairs pi+skillsurfaces must declare capabilities, avoid UI slots, and point at a relative packageSKILL.mdasset
Não. O contrato de manifesto aceita entry em .js/.mjs/.cjs ou .wasm.
.wasm: caminho recomendado para sandbox e hardening (integridadesha256-*obrigatória)..js/.mjs/.cjs: caminho válido para adoção gradual, especialmente para times que ainda não migraram para WASM. Notractor-ts, entradas JS já podem ser carregadas via módulo JS em runtime (com diferenças por ambiente).
Em resumo: WASM é o trilho de segurança mais forte, mas não é bloqueio absoluto para começar.
Para a política de produto/arquitetura em detalhes, veja docs/PLUGIN_AUTHORING_TRACKS.md no monorepo.
Besides schema validation, this package now exposes a shared binary-install contract:
parseSha256Integrity()verifyBufferIntegrity()installWasmArtifact(request, { cache, fetchFn })detectWasmBinaryKind(bytes)
installWasmArtifact is used by both Barn and Tractor install paths, so hash verification,
cache-hit validation, eviction-on-mismatch, fetch+persist semantics, and artifactKind
classification (module/component/unknown) stay consistent.
Advanced hosts can pass metadataExtensions in the install request to persist
runtime-specific install metadata (e.g. browser runtime module sidecars) without forking
core integrity/cache behavior.
Current browser-sidecar metadata keys used by tractor-ts:
browserRuntimeModule(url,integrity,format)browserRuntimeDescriptor(schemaVersion,descriptorHash,componentWasmUrl,source)browserRuntimeToolchain(name,version,generatedAt?)browserRuntimeProvenance(source,commitSha,buildId,sourceRepository?)
Descriptor distribution policy currently applied by tractor-ts install path:
- default
package-embedded: descriptor URL must be HTTPS, end with.runtime-descriptor.json, and share origin with component wasm URL. - optional
external-signed: requiresdescriptorIntegrity+ provenance/source repository metadata.- trust mode
repository-derived(default) derives trusted origins fromsourceRepository(including known GitHub release domains) - trust mode
strict-manualrequires explicitdescriptorTrustedOriginsallowlist.
- trust mode
To keep runtime behavior aligned across hosts, this package also exports:
detectEntryFormat(entry)evaluateEntryRuntimeCompatibility(entry, runtime, options?)assertEntryRuntimeCompatibility(entry, runtime, options?)options.allowBrowserWasmFromCachehabilita compatibilidade.wasmno browser para hosts que adotam execução cache-backed.
Current runtime policy:
- node:
.js,.mjs,.cjs,.wasm - browser:
.js,.mjsby default;.wasmis available only when the host opts into cache-backed execution (allowBrowserWasmFromCache) and.cjsstays blocked- cache-backed
.wasmhosts can useartifactKindmetadata to reject incompatible binaries (e.g. component artifacts pending dedicated runtime toolchain)
- cache-backed
@refarm.dev/plugin-manifest is a schema/validation contract, not a runtime capability contract.
Therefore, its conformance gate is the validator suite (src/validate.test.js) exposed via:
npm --prefix packages/plugin-manifest run test:conformanceA dedicated runManifestV1Conformance() harness is deferred until a separate runtime contract is introduced.
@refarm.dev/tractor now enforces a minimum manifest↔runtime alignment during plugin load when a
manifest is found next to the .wasm artifact (plugin-manifest.json or manifest.json).
Checks include:
- plugin id alignment (
manifest.idsuffix must match runtimeplugin_idderived from wasm filename) - required observability hooks (
onLoad,onInit,onRequest,onError,onTeardown) - minimal metadata compatibility (
metadata.version === manifest.version)
Critical mismatches fail load() with an explicit alignment error before plugin activation.
This package defines the formal "Contract" for plugin citizenship within Refarm. It ensures every plugin is well-behaved, traceable, and secure.
See ROADMAP.md for its evolution.
MIT