@armco/plugin-engine

Core plugin engine for Armco platform apps (Planner, Mesa, etc.).

What it provides

• Types — PluginManifest, InstalledPlugin, ExtensionPoint, PluginCapabilities, PluginPermissions, BoardSnapshot, PlanSnapshot, PluginMessage, etc.
• PluginRegistry — Singleton registry for installing, enabling/disabling, and discovering plugins. Persists state in localStorage.
• ManifestValidator — Validates plugin manifests against the schema. Enforces security constraints (sandbox requirements, permission restrictions for external plugins).
• PluginReadAPI — Factory for creating read-only data access APIs that plugins use to access host app data (boards, plans, trees).
• PluginAPIBridge — Handles postMessage communication between host app and sandboxed plugin iframes.

Usage

import {
  PluginManifest,
  getPluginRegistry,
  validateManifest,
  createPluginReadAPI,
  PluginAPIBridge,
} from "@armco/plugin-engine"

// Initialize registry
const registry = getPluginRegistry()
await registry.initialize()

// Install a plugin
const result = await registry.install(manifest)

// Create read API for a plugin
const api = createPluginReadAPI("my-plugin", () => storageService)

Development

This folder currently lives inside the Planner repo at /plugin-engine/. It will be moved to its own repo and published to npm as @armco/plugin-engine.

# Build
npm run build

# The host app (Planner) imports from this folder via path alias during dev

Architecture

@armco/plugin-engine (this package)
├── types/           — All shared TypeScript types and interfaces
└── core/
    ├── PluginRegistry.ts      — Plugin lifecycle management
    ├── ManifestValidator.ts   — Manifest validation
    └── PluginReadAPI.ts       — Read API + postMessage bridge

Host App (Planner, Mesa, etc.)
└── src/plugins/
    └── native/          — First-party plugins (stay in host app)