@wazir-dev/cli 1.0.0

package/expertise/architecture/patterns/plugin-architecture.md

@@ -0,0 +1,735 @@
+# Plugin Architecture — Architecture Expertise Module
+
+> Plugin architecture (micro-kernel, extension point) separates a stable core from optional extensions that can be added, removed, or replaced without modifying the core. The core defines extension points — explicit contracts where third-party or first-party code can inject behavior — while a plugin loader discovers, validates, and manages the lifecycle of extensions at runtime. Used when the system needs third-party extensibility or when features must be optional and swappable.
+
+> **Category:** Pattern
+> **Complexity:** Complex
+> **Applies when:** Platforms for third-party extension, systems with optional/swappable features, product tiers with different capabilities, community-driven ecosystems
+
+---
+
+## What This Is (and What It Isn't)
+
+### The Micro-Kernel Pattern
+
+The micro-kernel (or plug-in) architecture pattern separates a **minimal, stable core system** from **variable plug-in modules** that extend its functionality. The core provides just enough infrastructure to operate — event routing, plugin lifecycle management, a registry, and a base set of capabilities. Everything else is a plugin.
+
+This is the architecture behind VS Code, WordPress, IntelliJ IDEA, Figma, webpack, Eclipse, and every browser extension system. It is not new. The pattern traces back to operating system design (Mach, MINIX) where a small kernel provides IPC, scheduling, and memory management while file systems, device drivers, and networking run as user-space services.
+
+In application software, the same idea applies: the **core** handles plugin discovery, loading, lifecycle, security boundaries, and inter-plugin communication. The **plugins** implement actual features — a syntax highlighter, a payment gateway, an image filter, a build optimization pass.
+
+### The Plugin Lifecycle
+
+Every plugin system implements some variation of this lifecycle:
+
+1. **Discover** — The core finds available plugins. This happens through file system scanning (a `plugins/` directory), manifest registration (a `plugin.xml` or `package.json`), service loader mechanisms (Java `ServiceLoader`, Python `entry_points`), or a remote registry (npm, VS Code Marketplace, WordPress Plugin Directory).
+
+2. **Resolve** — The core checks that the plugin's declared dependencies are satisfied. Version constraints are validated. Conflicts are detected. Load order is determined from the dependency graph.
+
+3. **Load** — The plugin's code is loaded into memory. Depending on the isolation model, this might mean importing a module into the same process, spawning a child process, loading a WebAssembly module, or starting a container. Class loaders in Java (OSGi bundles), dynamic `import()` in JavaScript, and `dlopen` in C all serve this role.
+
+4. **Initialize** — The plugin's `activate` or `init` function is called. The core passes a context object providing the plugin with access to the APIs it is permitted to use. The plugin registers its contributions — commands, menu items, event handlers, UI components — with the core's registry.
+
+5. **Execute** — The plugin responds to events, handles requests, or extends behavior at defined extension points. This is the steady state. The core invokes plugin-registered callbacks when relevant events occur.
+
+6. **Deactivate / Unload** — The plugin is given a chance to clean up resources (close file handles, cancel timers, flush buffers) before being removed from memory. Hot-unloading without restart is a hallmark of mature plugin systems (OSGi, VS Code, Eclipse).
+
+### What This Is Not
+
+**Not just "modular code."** Splitting an application into modules or packages does not make it a plugin architecture. Modules are compile-time organizational units with static dependencies. Plugins are runtime-discovered, independently deployable units with dynamic binding to extension points. A Go application with 50 well-organized packages is modular. It is not a plugin system unless those packages can be added and removed by end users without recompiling the core.
+
+**Not dependency injection.** DI frameworks (Spring, Guice, .NET DI) swap implementations of interfaces at configuration time. This enables testability and loose coupling, but it does not provide a plugin lifecycle, discovery mechanism, manifest system, versioning model, or security boundary. A DI container wires up known components. A plugin loader discovers unknown components. The overlap is in interface-based contracts, but the operational model is fundamentally different.
+
+**Not microservices.** Microservices decompose a system into independently deployable network services. Plugins decompose a system into independently deployable in-process (or sandboxed) extensions of a single host application. Microservices communicate over the network. Plugins communicate through the host's API. The deployment unit, communication mechanism, and failure isolation model are all different.
+
+**Not feature flags.** Feature flags toggle behavior that already exists in the codebase. Plugins add behavior that does not exist in the codebase at all. Feature flags are a deployment mechanism. Plugins are an extensibility mechanism. They can be complementary — a plugin system might use feature flags internally — but they solve different problems.
+
+---
+
+## When to Use It
+
+### The Qualifying Conditions
+
+Apply plugin architecture when **two or more** of these are true:
+
+**You are building a platform for third-party extension.** This is the canonical use case. VS Code has over 60,000 extensions on its Marketplace, built by thousands of independent developers. WordPress powers 43% of the web and hosts over 60,000 free plugins in its official directory plus an estimated 30,000 premium plugins across third-party marketplaces. IntelliJ IDEA's JetBrains Marketplace lists over 8,000 plugins. Figma's community plugin ecosystem has over 3,000 plugins. These numbers are only possible because the core defines a stable, well-documented extension API that third parties can build against without coordinating with the core team.
+
+**Features must be optional or swappable.** A product that ships different capabilities to different customer tiers (free vs. pro vs. enterprise) benefits from a plugin model where each tier simply activates different plugins. Eclipse pioneered this approach: even core features like the Java editor are plugins, and different Eclipse distributions (Eclipse IDE for Java, Eclipse IDE for C++, Eclipse for PHP) are simply different plugin configurations of the same core.
+
+**The community must be able to contribute.** Open source projects that want to accept contributions without giving commit access to the core benefit from a plugin boundary. Contributors build plugins. The core team reviews plugin APIs, not plugin implementations. Babel's entire transformation pipeline is plugin-based — over 100 official plugins and thousands of community plugins transform JavaScript syntax, and the core parser/generator never needs modification.
+
+**You need runtime extensibility.** The system must load new capabilities without restart, recompilation, or redeployment. Chat platforms (Slack apps, Discord bots), CI/CD systems (Jenkins with 1,800+ plugins, GitHub Actions), and monitoring platforms (Grafana with 200+ data source plugins) all need this.
+
+**You are building developer tooling.** Build tools (webpack, Rollup, esbuild, Vite), linters (ESLint with 3,000+ community rules), test frameworks (Jest with custom matchers/transformers), and CLI frameworks (oclif, yargs) all benefit from plugin architecture because developers expect to customize every aspect of their toolchain.
+
+### Real-World Case Studies
+
+**VS Code** — Microsoft designed VS Code as a thin Electron shell with a Node.js extension host running extensions in a separate process. The core provides: text editor (Monaco), file system access, terminal, debugger protocol, SCM integration, and a contribution point system declared in `package.json` manifests. Extensions cannot access the DOM directly — they interact through VS Code's API surface, which provides `vscode.window`, `vscode.workspace`, `vscode.commands`, and other namespaces. This isolation means a misbehaving extension cannot crash the editor. Extensions are lazily activated based on activation events (e.g., `onLanguage:python` only loads when a Python file is opened), keeping startup fast despite thousands of installed extensions.
+
+**WordPress** — WordPress uses an event-driven hook system with two primitives: **actions** (fire-and-forget events like `init`, `wp_head`, `save_post`) and **filters** (data transformation pipelines like `the_content`, `the_title`). Plugins register callbacks via `add_action()` and `add_filter()` with priority numbers controlling execution order. This model is simple enough that non-programmers can write plugins, which explains the ecosystem's size. The downside is zero isolation — plugins run in the same PHP process, share global state, and a fatal error in one plugin crashes the entire site.
+
+**Webpack** — Webpack's architecture is built on the Tapable library, which provides typed hook classes: `SyncHook`, `SyncBailHook`, `SyncWaterfallHook`, `AsyncSeriesHook`, `AsyncParallelHook`, and `AsyncSeriesBailHook`. The `Compiler` and `Compilation` objects expose dozens of hooks that plugins tap into. A plugin is a class with an `apply(compiler)` method that taps into specific hooks. The hook types encode execution semantics: bail hooks stop on the first non-undefined return, waterfall hooks pass each return value to the next tap, and parallel hooks run taps concurrently. This type system prevents an entire class of plugin interaction bugs at the API level.
+
+**IntelliJ Platform** — JetBrains uses a declarative extension point system. Plugins declare their contributions in `plugin.xml` using extension point references like `com.intellij.fileType`, `com.intellij.annotator`, or `com.intellij.codeInsight.template.postfixTemplateProvider`. The platform provides three service scopes: application-level (global singleton), project-level (one per open project), and module-level (one per module). Since 2019.3, "Light Services" annotated with `@Service` skip XML registration entirely. Plugins can also declare their own extension points, enabling plugin-to-plugin extension.
+
+---
+
+## When NOT to Use It
+
+This section is equally important. Plugin architecture is one of the most over-applied patterns in software, because the fantasy of third-party extensibility is appealing even when no third party will ever extend the system.
+
+### The Disqualifying Conditions
+
+**Internal applications with a single development team.** If the only people who will ever modify the system are the team that builds it, a plugin architecture adds indirection without value. The team can modify the core directly. They do not need a plugin manifest, a loader, an extension point registry, or a versioned API contract. They need well-organized modules and good tests. An internal CRM, an admin dashboard, a reporting tool — these are not platforms. They are applications. Build them as applications.
+
+**Speculative extensibility ("someday someone might want to extend this").** This is the most common YAGNI violation in architecture. A team builds a plugin system for an e-commerce checkout flow because "merchants might want custom checkout steps." Two years later, no merchant has written a plugin. The team has maintained a plugin API, a loader, manifest validation, and extension point documentation for zero external consumers while paying the complexity cost on every feature they ship. Martin Fowler's articulation of YAGNI is precise: you pay the cost of carrying the abstraction (increased complexity, slower feature development, harder debugging) whether or not the speculative use case materializes. If it never materializes, the cost is pure waste.
+
+**Plugin APIs are permanent commitments.** Once you publish a plugin API and third parties build against it, that API surface becomes load-bearing. Changing it breaks external code you do not control and cannot update. Hyrum's Law applies with maximum force: every observable behavior of your API — including bugs, timing characteristics, and undocumented side effects — will be depended upon by someone. WordPress cannot change the signature of `add_filter()` without breaking millions of plugins. VS Code maintains meticulous API stability guarantees and runs extension tests against proposed API changes. Eclipse's history is littered with painful API migrations that fractured the plugin ecosystem. Do not publish an extension API until you are confident in its design and prepared to maintain it for years.
+
+**When feature flags solve the problem.** If the goal is to enable/disable features per customer tier, environment, or rollout stage, feature flags are simpler, more predictable, and easier to test. Feature flags operate on code that already exists in the binary. Plugins operate on code that is discovered at runtime from external sources. If all your "plugins" ship inside the main binary and are written by your team, you have feature flags wearing a plugin costume.
+
+**When the extension surface is tiny.** If there are only two or three points where behavior might vary, define interfaces for those variation points and use configuration or DI to select implementations. A notification service that can send via email, SMS, or push does not need a plugin system — it needs a `NotificationChannel` interface with three implementations and a configuration file that lists which channels are active.
+
+**Fewer than five anticipated extensions.** A plugin system's overhead (loader, registry, manifest schema, lifecycle management, documentation, versioning) is amortized across extensions. With fewer than five, the overhead per extension is too high. Write the five implementations directly and revisit if the number grows past ten.
+
+### Real-World Cautionary Examples
+
+**Over-engineered internal tools.** A fintech company built a plugin architecture for their internal reconciliation engine, anticipating that different teams would write reconciliation plugins. After 18 months, exactly one team used it — the team that built it. The plugin manifest schema, loader, and registry added 3,000 lines of infrastructure code that was maintained by one team for one consumer. They eventually ripped it out and replaced it with a strategy pattern and a configuration file.
+
+**Eclipse's API surface problem.** Eclipse's commitment to backward compatibility across its vast extension point surface made evolution painful. API churn across major releases (Eclipse 3.x to Eclipse 4.x) broke thousands of plugins and fractured the community. Many plugin authors abandoned maintenance rather than migrating. The lesson: a large plugin API surface is a long-term maintenance liability, not just a short-term investment.
+
+**Never-used extension points.** A CMS product shipped 47 extension points at launch. Usage telemetry after two years showed that only 8 were ever used by third-party plugins. The remaining 39 imposed ongoing maintenance cost — every internal refactoring had to preserve their contracts — for zero external value.
+
+---
+
+## How It Works
+
+### Core Responsibilities
+
+The core system in a plugin architecture has a specific, limited set of responsibilities:
+
+1. **Plugin discovery** — Finding available plugins via file system scanning, manifest enumeration, service loader, or registry query.
+2. **Dependency resolution** — Building a dependency graph, detecting conflicts, and determining load order.
+3. **Lifecycle management** — Loading, initializing, activating, deactivating, and unloading plugins in the correct order.
+4. **Extension point registry** — Maintaining a registry of extension points (contracts that plugins can implement) and the plugins that have registered implementations for each.
+5. **API surface** — Providing the APIs that plugins use to interact with the core and with each other. This surface must be stable, versioned, and documented.
+6. **Security boundary enforcement** — Controlling what plugins can access (file system, network, other plugins' data, core internals).
+7. **Error isolation** — Ensuring that a failing plugin does not crash the core or other plugins.
+
+### Plugin Contracts
+
+A plugin contract defines what a plugin must provide and what it receives in return:
+
+**Manifest** — A declarative description of the plugin: name, version, author, dependencies, extension points it implements, activation conditions, permissions it requires. Examples: VS Code's `package.json` with `contributes` and `activationEvents`, IntelliJ's `plugin.xml` with `<extensions>` and `<depends>`, WordPress's plugin header comment block.
+
+**Entry point** — A known function or class that the loader calls to initialize the plugin. VS Code: `activate(context: ExtensionContext)`. Webpack: `apply(compiler: Compiler)`. WordPress: the plugin's main PHP file with hooks registered at the top level.
+
+**Extension point implementation** — The actual code that extends the core. A VS Code language extension implements `DocumentFormattingEditProvider`. A webpack plugin taps `compiler.hooks.emit`. A WordPress plugin calls `add_filter('the_content', myTransform)`.
+
+**Capability declaration** — What the plugin needs access to. VS Code extensions declare capabilities in `package.json` (e.g., `"capabilities": { "untrustedWorkspaces": { "supported": true } }`). Browser extensions declare permissions in their manifest. Android apps declare permissions in `AndroidManifest.xml`. This enables the security model.
+
+### Discovery Mechanisms
+
+| Mechanism | How It Works | Examples |
+|---|---|---|
+| **File system scanning** | Core scans a known directory for plugin files/folders | WordPress scans `wp-content/plugins/`, Jest scans `node_modules` for `jest-*` packages |
+| **Manifest registration** | Plugins declare themselves in a configuration file | IntelliJ's `plugin.xml`, VS Code's `package.json` with `engines.vscode` |
+| **Service loader** | Language-level service discovery | Java `ServiceLoader` reads `META-INF/services/`, Python `pkg_resources.iter_entry_points()` |
+| **Remote registry** | Core queries an online registry for available plugins | VS Code Marketplace API, npm registry, WordPress Plugin Directory |
+| **Convention-based** | Naming conventions identify plugins | Babel plugins prefixed `babel-plugin-*`, ESLint rules prefixed `eslint-plugin-*` |
+| **Explicit registration** | Plugin is registered programmatically | `app.use(myPlugin)` in Express/Fastify, `Vue.use(plugin)` |
+
+### Loading and Isolation Models
+
+**Same-process, no isolation** — The simplest model. Plugins run in the same process and address space as the core. WordPress, Express middleware, Babel plugins, and ESLint rules all use this model. The advantage is zero overhead for plugin-to-core communication. The disadvantage is that a crashing plugin crashes the host, and a malicious plugin has full access to the process.
+
+**Separate process** — Plugins run in a child process or worker. VS Code runs extensions in a separate Node.js "Extension Host" process. The core communicates with extensions via JSON-RPC over IPC. This provides crash isolation (a failing extension does not crash the editor) and security isolation (extensions cannot access the editor's DOM). The cost is serialization overhead for every API call.
+
+**Sandboxed execution** — Plugins run in a sandbox with restricted capabilities. Browser extensions run in content scripts with limited DOM access and background scripts with limited API access. Figma plugins run in a sandboxed iframe with a postMessage bridge. Envoy Proxy runs extensions as WebAssembly modules with resource constraints. Deno plugins run with explicit permission grants. This provides strong security guarantees at the cost of API design complexity.
+
+**Container/VM isolation** — The strongest isolation model. Jenkins runs certain plugins in Docker containers. GitHub Actions runs each action in a container. Kubernetes operators run as separate pods. This enables language-agnostic plugins but introduces significant latency and resource overhead.
+
+### Inter-Plugin Communication
+
+Plugins often need to interact with each other. The core mediates this through:
+
+**Extension points declared by plugins** — IntelliJ allows plugins to declare their own extension points that other plugins implement. Plugin A defines an extension point; Plugin B implements it. The platform manages the wiring.
+
+**Event bus / pub-sub** — Plugins emit and listen for events on a shared bus. VS Code's `EventEmitter` pattern, WordPress's action/filter hooks, and webpack's Tapable hooks all serve this purpose. The core acts as the message broker.
+
+**Service registry** — Plugins register services that other plugins can look up. OSGi's service registry, IntelliJ's service locator (`ServiceManager.getService()`), and Eclipse's extension registry all provide this. The core owns the registry and controls visibility.
+
+**Shared context object** — The core provides a context or workspace object that plugins read from and write to. VS Code's `ExtensionContext`, webpack's `Compilation` object, and Koa's `ctx` object all serve as shared state containers with defined access patterns.
+
+### Versioning and Compatibility
+
+**Semantic versioning of the host API** — The host declares its API version. Plugins declare the range of host versions they support. VS Code extensions declare `"engines": { "vscode": "^1.74.0" }`. IntelliJ plugins declare `<idea-version since-build="223" until-build="232.*"/>`. The loader rejects plugins whose version constraints are not satisfied.
+
+**API deprecation policy** — Mature plugin systems establish formal deprecation timelines: announce deprecation in version N, emit warnings in version N+1, remove in version N+2. VS Code marks APIs as `@deprecated` with migration guidance. JetBrains uses `@ApiStatus.ScheduledForRemoval(inVersion = "2024.2")`.
+
+**Extension API vs. internal API** — A critical distinction. The extension API is the stable, public surface that plugins build against. Internal APIs are implementation details that can change freely. VS Code enforces this with a separate `vscode.d.ts` type definition file that includes only the public API. IntelliJ uses `@ApiStatus.Internal` annotations. Webpack distinguishes between documented hooks and internal implementation.
+
+### Security Model
+
+**Permission system** — Plugins declare what they need (file system access, network access, clipboard, notifications). The host grants or denies based on policy. Browser extensions use a manifest-declared permission model. VS Code extensions declare capabilities. Mobile app stores enforce permission review.
+
+**API surface restriction** — Plugins only see the APIs explicitly provided to them. VS Code passes a curated `vscode` namespace to extensions, not the entire Node.js API. Figma plugins receive a restricted `figma` API object, not browser globals. This is enforced architecturally, not by convention.
+
+**Code review / marketplace review** — Human or automated review before publication. The VS Code Marketplace scans extensions for known vulnerability patterns. WordPress.org reviews all submitted plugins. Apple's App Store review process examines permissions usage. This is a social/process control, not a technical one.
+
+**Runtime sandboxing** — Process isolation, WebAssembly sandboxing, iframe sandboxing, or capability-based security restricts what plugin code can do at runtime regardless of what it tries. This is the strongest technical control.
+
+---
+
+## Trade-Offs Matrix
+
+| Dimension | Benefit | Cost |
+|---|---|---|
+| **Extensibility** | Third parties can add capabilities the core team never anticipated. VS Code's 60,000+ extensions cover use cases Microsoft could never staff. | The plugin API becomes a permanent public contract. Every change risks breaking external code. API design errors are costly to fix. |
+| **Modularity** | Features are isolated in self-contained units with explicit boundaries. Adding or removing a feature is a plugin install/uninstall. | Debugging crosses plugin boundaries. Stack traces span the core, the loader, and the plugin. Error messages from deep in the plugin system are often opaque. |
+| **Core stability** | The core changes less frequently because features live in plugins. Core releases can focus on infrastructure improvements. | Plugin authors must track core API changes. A major core version bump can orphan hundreds of plugins (Eclipse 3.x to 4.x). |
+| **Independent deployment** | Plugins ship on their own schedule. A plugin author can fix a bug and release without waiting for a core release cycle. | Version matrix explosion. N core versions times M plugin versions creates N*M compatibility combinations to reason about. |
+| **Community leverage** | A plugin ecosystem multiplies the core team's output by orders of magnitude. WordPress's 60,000 plugins represent millions of developer-hours the core team did not spend. | Quality variance is extreme. Plugin marketplaces contain abandoned, insecure, incompatible, and poorly written plugins. Curation, review, and rating systems are necessary but imperfect. |
+| **Runtime flexibility** | Plugins can be loaded, unloaded, and updated at runtime without restarting the host. OSGi bundles support hot-swapping. | Hot-loading introduces state management complexity. What happens to in-flight requests when a plugin is unloaded? What about cached references to plugin-provided services? |
+| **Security isolation** | Process/sandbox isolation means a compromised plugin cannot access the core's memory or other plugins' data. | Isolation mechanisms add latency (IPC serialization), memory overhead (per-plugin process/sandbox), and API design constraints (everything must be serializable). |
+| **Performance** | Lazy loading means unused plugins consume zero resources. VS Code only activates extensions when their activation events fire. | Plugin boundaries prevent certain optimizations. Data must cross serialization boundaries. Hot paths through multiple plugins accumulate overhead. |
+| **Testability** | Plugins can be tested in isolation against a mock core. The core can be tested without any plugins loaded. | Integration testing is harder. The combinatorial space of plugin interactions is large. Plugin A works alone, Plugin B works alone, but A+B together exhibit emergent bugs. |
+| **Adoption and ecosystem** | A healthy plugin ecosystem is a powerful moat. Developers choose VS Code partly because of its extension ecosystem. | Bootstrap problem: no users without plugins, no plugin authors without users. Seeding the ecosystem requires the core team to write the first wave of plugins. |
+
+---
+
+## Evolution Path
+
+Most plugin architectures evolve through a predictable sequence of stages. Jumping to the end is almost always a mistake.
+
+### Stage 1: Hardcoded Features
+
+All features live in the core codebase. There is no extension mechanism. This is correct for early-stage products. Ship features, validate the product, learn what the actual variation points are.
+
+**When to move on:** You find yourself adding `if/else` or `switch` statements for every new variation of the same concept. Or external developers are forking your project to add features you cannot accept into core.
+
+### Stage 2: Identify the Stable Core
+
+Analyze your codebase to determine what changes frequently and what remains stable. The stable parts become the core. The frequently-changing parts become plugin candidates. This analysis requires real usage data, not speculation.
+
+Common stable cores: text editor engine (VS Code), content management and rendering pipeline (WordPress), compilation pipeline stages (webpack), code model and PSI tree (IntelliJ).
+
+Common plugin candidates: language-specific features, theme/appearance, integrations with external services, output format variations, custom rules/checks.
+
+### Stage 3: Extract Interfaces at Variation Points
+
+Define interfaces (ports, contracts, extension points) at the boundaries between the stable core and the variable features. These interfaces become the plugin API. Start with a small number of high-value extension points — three to five — rather than trying to make everything extensible.
+
+**Critical decision:** The interface design at this stage determines the long-term extensibility surface. Invest time in getting the abstractions right. Study how existing plugins in your domain (competitors, similar tools) define their extension contracts.
+
+### Stage 4: Build the Plugin Loader
+
+Implement the minimal infrastructure: a discovery mechanism (scan a directory), a loader (import the module), a registry (track what is loaded), and lifecycle hooks (init/destroy). Resist the urge to build a sophisticated plugin framework. Start with the simplest thing that works.
+
+A minimal plugin loader in most languages is 50-200 lines of code. If your loader is 2,000 lines before you have your first plugin, you are over-engineering.
+
+### Stage 5: Migrate Internal Features to Plugins
+
+Move your own features from hardcoded core code to the plugin model. This is the critical validation step. If your own features are painful to implement as plugins, third-party developers will find it impossible. VS Code's built-in language features (TypeScript, JSON, Markdown) are implemented as built-in extensions using the same API available to third parties. This "eat your own dog food" approach ensures API quality.
+
+### Stage 6: Document and Open the API
+
+Write comprehensive documentation: getting started guide, API reference, example plugins, migration guides. Establish versioning policy, deprecation timelines, and contribution guidelines. Set up a plugin template/scaffold (VS Code's Yeoman generator, IntelliJ's Plugin DevKit).
+
+**Only open the API when you are confident in its stability.** Every extension point you publish is a commitment. It is easier to add extension points later than to remove or change existing ones.
+
+### Stage 7: Build the Ecosystem
+
+Create a marketplace or registry. Establish review processes. Build tooling for plugin developers (debugging, testing, packaging). Foster a community. This stage is ongoing and requires sustained investment.
+
+---
+
+## Failure Modes
+
+### API Churn
+
+**The problem:** The core team changes the plugin API frequently, breaking existing plugins with each release. Plugin authors spend more time adapting to API changes than building features. The ecosystem stagnates as authors abandon plugins rather than migrating.
+
+**Real example:** Eclipse's transition from 3.x to 4.x (the "e4" platform) introduced a new dependency injection-based programming model that was incompatible with the existing extension point model. Thousands of plugins required significant rewriting. Many were never updated. The ecosystem fragmented.
+
+**Prevention:** Establish a formal API stability policy before publishing any extension point. Use semantic versioning rigorously. Provide automated migration tools (codemods) for breaking changes. Maintain a compatibility layer for at least one major version cycle. Run the full suite of popular plugins against proposed API changes before releasing them.
+
+### Security Vulnerabilities
+
+**The problem:** Plugins run with the same privileges as the core or have insufficient sandboxing. A malicious or compromised plugin can steal credentials, exfiltrate data, or compromise the host system.
+
+**Real examples:** WordPress plugin vulnerabilities are a leading cause of website compromises — a 2023 study found that vulnerable plugins were responsible for the majority of WordPress security incidents. Browser extension malware has affected millions of users through permission abuse, with extensions requesting broad permissions (access to all websites) then injecting ads, tracking users, or stealing credentials. npm supply chain attacks (event-stream, ua-parser-js) compromised packages that were used as plugins/dependencies by thousands of projects.
+
+**Prevention:** Implement least-privilege permission models. Run plugins in sandboxed processes. Review plugins before marketplace publication. Implement runtime monitoring for suspicious behavior. Provide users with clear permission prompts. Use capability-based security where the plugin only receives references to resources it needs.
+
+### Load Order Dependencies
+
+**The problem:** Plugins assume other plugins are loaded first. Plugin A registers a service; Plugin B depends on that service during initialization. If B loads before A, B crashes. This creates fragile, order-dependent startup sequences.
+
+**Real example:** WordPress plugins load in alphabetical order by directory name. Developers have resorted to naming their plugin directories with leading underscores or numbers to ensure early loading. Some plugins check for the existence of other plugins in their init hooks and retry on failure, creating timing-sensitive initialization races.
+
+**Prevention:** Use a dependency graph with topological sort for load ordering. Require plugins to declare their dependencies explicitly in their manifest. Defer service consumption to lazy resolution (look up the service when first needed, not at init time). Provide lifecycle phases where all plugins are loaded before any plugin is initialized.
+
+### Memory Leaks and Resource Exhaustion
+
+**The problem:** Plugins allocate resources (event listeners, timers, file handles, DOM nodes, WebSocket connections) during activation but fail to release them during deactivation. Over time, repeated plugin activate/deactivate cycles leak resources.
+
+**Real example:** VS Code extensions that register `onDidChangeTextDocument` listeners without disposing them cause memory leaks that grow with each file opened. The VS Code team introduced the `ExtensionContext.subscriptions` array specifically to address this: extensions push disposables into this array, and the platform disposes them all when the extension deactivates.
+
+**Prevention:** Provide a disposable/cleanup pattern (VS Code's `Disposable`, React's cleanup functions in `useEffect`). Track all resources registered by each plugin and forcibly clean them up on deactivation. Implement memory budgets per plugin. Monitor resource usage and warn or disable plugins that exceed thresholds.
+
+### Version Conflicts (Dependency Hell)
+
+**The problem:** Two plugins depend on different, incompatible versions of the same library. Plugin A needs `lodash@3` and Plugin B needs `lodash@4`. In a shared-process model, only one version can be loaded.
+
+**Real example:** OSGi struggled with this extensively. Java's original class loading model assumed global visibility, and many popular libraries used static singletons, `Thread.currentThread().getContextClassLoader()`, and other patterns that break under modular class loading. OSGi's per-bundle classloader solved the technical problem but introduced "class loading hell" — the same class loaded by two different classloaders is treated as two different types by the JVM.
+
+**Prevention:** Provide per-plugin dependency isolation (separate node_modules, per-bundle classloaders, WebAssembly module instances). In ecosystems where full isolation is too expensive, establish conventions: the host provides common dependencies (peer dependencies in npm), and plugins must use the host-provided versions. Document which libraries are available from the host and which versions are guaranteed.
+
+### Plugin Interaction Bugs
+
+**The problem:** Plugins work correctly in isolation but exhibit bugs when loaded together. Plugin A modifies shared state that Plugin B relies on. Plugin A's filter transforms data in a way that Plugin B's filter does not expect.
+
+**Real example:** WordPress's filter pipeline allows multiple plugins to modify the same content. A security plugin that sanitizes HTML and a formatting plugin that adds HTML classes can interfere with each other depending on their priority ordering. These bugs are hard to reproduce because they depend on the exact combination of installed plugins.
+
+**Prevention:** Minimize shared mutable state. Use immutable data structures in plugin pipelines. Provide typed hook signatures (webpack's Tapable) that constrain what plugins can return. Build combinatorial testing infrastructure that tests popular plugin combinations.
+
+### Ecosystem Fragmentation
+
+**The problem:** Multiple competing plugin APIs emerge for the same host. Or a major version bump creates an ecosystem split between old-API and new-API plugins.
+
+**Real example:** The Vim plugin ecosystem fragmented across multiple plugin managers (Vundle, Pathogen, vim-plug, dein.vim) with slightly different conventions. The Python packaging ecosystem has struggled with competing plugin mechanisms (`setuptools` entry points, namespace packages, `importlib.metadata`). Each mechanism has different discovery, loading, and compatibility characteristics.
+
+**Prevention:** Establish one canonical plugin mechanism early. Invest in backward compatibility. When breaking changes are unavoidable, provide a compatibility shim that allows old plugins to run on the new API with deprecation warnings.
+
+---
+
+## Technology Landscape
+
+### JavaScript / TypeScript
+
+**VS Code Extension API** — The gold standard for desktop application plugin architecture. Extensions are npm packages with a `package.json` manifest declaring `contributes` (contribution points for commands, views, languages, themes) and `activationEvents` (lazy loading triggers). Extensions run in a separate Extension Host process, communicating with the main process via JSON-RPC. The `vscode` module provides a typed API (`vscode.d.ts`) that is stable across releases. Extension development uses Yeoman scaffolding, `vsce` for packaging, and the Extension Development Host for debugging.
+
+**Webpack Plugins** — Built on the Tapable library. Plugins are classes with an `apply(compiler)` method. They tap into typed hooks on `Compiler` and `Compilation` objects. Hook types (Sync, AsyncSeries, AsyncParallel, Bail, Waterfall, Loop) encode execution semantics, preventing misuse. The compiler hook pipeline covers the entire build lifecycle: `environment` → `afterEnvironment` → `entryOption` → `afterPlugins` → `compile` → `thisCompilation` → `compilation` → `make` → `afterCompile` → `emit` → `afterEmit` → `done`.
+
+**Babel Plugins** — Visitor-pattern plugins that traverse and transform the AST. A plugin exports a function that receives a `babel` API object and returns a visitor object mapping AST node types to enter/exit handlers. Plugins compose in a pipeline: each plugin's output AST is the next plugin's input. Presets are ordered collections of plugins. The visitor pattern constrains what plugins can do — they transform AST nodes — making the system predictable but limiting extensibility to AST transformations.
+
+**ESLint Rules** — Each rule is a plugin that exports a `create(context)` function returning a visitor. The `context` object provides `report()` for flagging violations, `getSourceCode()` for reading the AST, and `getFilename()` for context. Rules are pure functions from AST to reports, making them easy to test and compose.
+
+**Rollup/Vite Plugins** — Rollup plugins implement a hooks-based interface with methods like `resolveId`, `load`, `transform`, `renderChunk`, and `generateBundle`. Vite extends this with additional hooks for dev server functionality. The hook interface is simpler than Webpack's Tapable system, trading flexibility for ease of authorship.
+
+### Java
+
+**OSGi (Open Service Gateway Initiative)** — The most comprehensive plugin framework in the Java ecosystem. Bundles (plugins) are JARs with a `MANIFEST.MF` declaring exported packages, imported packages, required bundles, and service registrations. The OSGi container manages per-bundle classloaders, service registry, lifecycle (INSTALLED → RESOLVED → STARTING → ACTIVE → STOPPING → UNINSTALLED), and hot-swapping. Used by Eclipse IDE, Apache Felix, Apache Karaf, and many enterprise middleware platforms. The learning curve is steep, and non-modular libraries that assume global classloader visibility are a persistent source of pain.
+
+**Java ServiceLoader** — A lightweight, built-in plugin mechanism since Java 6. Implementations of a service interface are listed in `META-INF/services/com.example.MyService`. `ServiceLoader.load(MyService.class)` discovers and instantiates them. Simple and zero-dependency, but provides no lifecycle management, dependency resolution, or isolation. Suitable for small extension points (JDBC drivers, charset providers) but insufficient for complex plugin systems.
+
+**Spring Plugin (formerly Hera)** — Provides plugin discovery and ordering on top of Spring's DI container. Plugins implement a marker interface and are discovered via classpath scanning. Useful when the host is already a Spring application.
+
+### .NET
+
+**Managed Extensibility Framework (MEF)** — Built into .NET Framework and .NET Core. Uses attributes (`[Export]`, `[Import]`, `[ImportMany]`) to declare and consume extension points. Catalogs scan assemblies for exports. Supports lazy loading, metadata filtering, and recomposition. Used by Visual Studio's extension system.
+
+**System.Composition** — The lightweight successor to MEF in .NET Core. Same attribute-based model but with a smaller footprint and convention-based composition.
+
+### Python
+
+**setuptools entry_points** — The standard Python plugin mechanism. Packages declare entry points in `setup.cfg` or `pyproject.toml` under `[options.entry_points]`. The host discovers plugins via `importlib.metadata.entry_points(group='myapp.plugins')`. Used by pytest (plugins discovered via `pytest11` entry point group), tox, flake8, and many CLI tools.
+
+**pluggy** — The plugin framework used by pytest. Provides a hook specification/implementation model with `@hookspec` and `@hookimpl` decorators. Supports `firstresult` (bail) hooks, `tryfirst`/`trylast` ordering, and wrapper hooks. More structured than raw entry points.
+
+### Go
+
+**hashicorp/go-plugin** — Uses gRPC over a local socket to communicate between the host and plugin processes. Plugins are compiled as separate binaries. The host launches the plugin binary as a subprocess and communicates via a typed gRPC interface. Used by Terraform (providers are go-plugin processes), Vault, Consul, Packer, and Nomad. Provides strong process isolation and language-agnostic plugins (any language that speaks gRPC can be a plugin) at the cost of startup latency and serialization overhead.
+
+### Cross-Language
+
+**WebAssembly (Wasm)** — Emerging as a universal plugin format. Plugins compile to Wasm modules and run in a sandboxed VM (Wasmtime, Wasmer, V8). The host defines imports (functions the plugin can call) and exports (functions the host calls). Memory is isolated. CPU and memory limits are enforceable. Language-agnostic: plugins can be written in Rust, C, C++, Go, AssemblyScript, or any language targeting Wasm. Used by Envoy Proxy, Zellij terminal multiplexer, Fermyon Spin, and Extism. The tooling is maturing rapidly.
+
+**gRPC-based plugin protocols** — Similar to HashiCorp's go-plugin model. The host and plugin communicate via gRPC over a local socket or stdio. Language-agnostic but requires gRPC tooling for each target language. Suitable when strong isolation and multi-language support are requirements.
+
+---
+
+## Decision Tree
+
+Use this decision tree to determine whether plugin architecture is appropriate:
+
+```
+Is a third-party ecosystem a product requirement?
+├─ YES → Plugin architecture is likely correct.
+│         Define extension points carefully.
+│         Budget for ecosystem tooling and documentation.
+│
+└─ NO → Is runtime extensibility required (load new code without restart)?
+         ├─ YES → Plugin architecture may be appropriate.
+         │         Consider lighter alternatives first:
+         │         - Dynamic imports with a convention
+         │         - Script evaluation in a sandbox
+         │         - Configuration-driven behavior
+         │
+         └─ NO → Do features need to be independently deployable by different teams?
+                  ├─ YES → Consider microservices or modular monolith first.
+                  │         Plugin architecture within a monolith is unusual
+                  │         for this use case.
+                  │
+                  └─ NO → Do you need to enable/disable features per customer or tier?
+                           ├─ YES → Feature flags are almost certainly simpler.
+                           │         Use plugin architecture only if:
+                           │         - Features are large (> 5K LOC each)
+                           │         - Features have independent dependencies
+                           │         - Features must be deployable by non-core teams
+                           │
+                           └─ NO → Is the extensibility "just in case" or "someday"?
+                                    ├─ YES → Do NOT build a plugin system.
+                                    │         Apply YAGNI. Use well-structured
+                                    │         modules with interfaces at known
+                                    │         variation points. Revisit when a
+                                    │         concrete need materializes.
+                                    │
+                                    └─ NO → Internal app with < 5 variation points?
+                                             ├─ YES → Strategy pattern + config.
+                                             │         No plugin infrastructure needed.
+                                             │
+                                             └─ NO → Evaluate case-by-case.
+                                                      Consider modular monolith or
+                                                      hexagonal architecture first.
+```
+
+---
+
+## Implementation Sketch
+
+### Plugin Interface (TypeScript)
+
+```typescript
+/**
+ * Every plugin must implement this interface.
+ * The host calls these methods in lifecycle order.
+ */
+interface Plugin {
+  /** Unique identifier, e.g., "com.example.my-plugin" */
+  readonly id: string;
+
+  /** Semver version string */
+  readonly version: string;
+
+  /**
+   * Called once when the plugin is loaded.
+   * Receives a context object with the host's API surface.
+   * Register contributions (commands, handlers, providers) here.
+   * Return a disposable or cleanup function.
+   */
+  activate(context: PluginContext): Promise<Disposable | void>;
+
+  /**
+   * Called when the plugin is being unloaded.
+   * Release all resources: close connections, cancel timers,
+   * remove event listeners.
+   */
+  deactivate?(): Promise<void>;
+}
+
+interface PluginContext {
+  /** Subscribe to host events */
+  readonly events: EventBus;
+
+  /** Register commands that users or other plugins can invoke */
+  registerCommand(id: string, handler: CommandHandler): Disposable;
+
+  /** Register a provider for an extension point */
+  registerProvider<T>(extensionPoint: string, provider: T): Disposable;
+
+  /** Plugin-scoped storage */
+  readonly storage: PluginStorage;
+
+  /** Logger scoped to this plugin */
+  readonly logger: Logger;
+
+  /** Subscriptions array — all disposables here are cleaned up on deactivate */
+  readonly subscriptions: Disposable[];
+}
+
+interface Disposable {
+  dispose(): void;
+}
+```
+
+### Plugin Manifest
+
+```json
+{
+  "id": "com.example.markdown-preview",
+  "name": "Markdown Preview",
+  "version": "1.2.0",
+  "description": "Live preview for Markdown files",
+  "author": "Example Corp",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "engines": {
+    "host": ">=2.0.0 <4.0.0"
+  },
+  "dependencies": {
+    "com.example.file-watcher": "^1.0.0"
+  },
+  "activationEvents": [
+    "onFileType:markdown",
+    "onCommand:markdown.preview"
+  ],
+  "contributes": {
+    "commands": [
+      {
+        "id": "markdown.preview",
+        "title": "Open Markdown Preview"
+      }
+    ]
+  },
+  "permissions": [
+    "filesystem:read",
+    "webview:create"
+  ]
+}
+```
+
+### Plugin Loader
+
+```typescript
+import { readdir, readFile } from 'fs/promises';
+import { join, resolve } from 'path';
+
+interface LoadedPlugin {
+  manifest: PluginManifest;
+  instance: Plugin;
+  disposables: Disposable[];
+  state: 'discovered' | 'resolved' | 'active' | 'failed';
+}
+
+class PluginLoader {
+  private plugins = new Map<string, LoadedPlugin>();
+  private extensionPoints = new Map<string, Set<unknown>>();
+
+  constructor(
+    private pluginDir: string,
+    private hostVersion: string,
+  ) {}
+
+  /**
+   * Phase 1: Discover — scan plugin directory for manifests
+   */
+  async discover(): Promise<PluginManifest[]> {
+    const entries = await readdir(this.pluginDir, { withFileTypes: true });
+    const manifests: PluginManifest[] = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const manifestPath = join(this.pluginDir, entry.name, 'manifest.json');
+      try {
+        const raw = await readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(raw) as PluginManifest;
+        manifests.push(manifest);
+        this.plugins.set(manifest.id, {
+          manifest,
+          instance: null!,
+          disposables: [],
+          state: 'discovered',
+        });
+      } catch {
+        // Skip directories without valid manifests
+      }
+    }
+    return manifests;
+  }
+
+  /**
+   * Phase 2: Resolve — check version constraints and dependency graph
+   */
+  resolve(): string[] {
+    const errors: string[] = [];
+
+    for (const [id, plugin] of this.plugins) {
+      // Check host version compatibility
+      if (!satisfiesVersion(this.hostVersion, plugin.manifest.engines.host)) {
+        errors.push(
+          `${id}: requires host ${plugin.manifest.engines.host}, ` +
+          `have ${this.hostVersion}`
+        );
+        plugin.state = 'failed';
+        continue;
+      }
+
+      // Check plugin dependencies
+      for (const [depId, depRange] of
+        Object.entries(plugin.manifest.dependencies ?? {})) {
+        const dep = this.plugins.get(depId);
+        if (!dep) {
+          errors.push(`${id}: missing dependency ${depId}`);
+          plugin.state = 'failed';
+        } else if (!satisfiesVersion(dep.manifest.version, depRange)) {
+          errors.push(
+            `${id}: needs ${depId}@${depRange}, ` +
+            `have ${dep.manifest.version}`
+          );
+          plugin.state = 'failed';
+        }
+      }
+
+      if (plugin.state !== 'failed') {
+        plugin.state = 'resolved';
+      }
+    }
+    return errors;
+  }
+
+  /**
+   * Phase 3: Activate — load code and call activate() in dependency order
+   */
+  async activateAll(): Promise<void> {
+    const order = this.topologicalSort();
+
+    for (const id of order) {
+      const plugin = this.plugins.get(id)!;
+      if (plugin.state !== 'resolved') continue;
+
+      try {
+        const modulePath = resolve(
+          this.pluginDir, id, plugin.manifest.main
+        );
+        const mod = await import(modulePath);
+        plugin.instance = mod.default ?? mod;
+
+        const context = this.createContext(id);
+        const disposable = await plugin.instance.activate(context);
+        if (disposable) {
+          plugin.disposables.push(disposable);
+        }
+        plugin.disposables.push(...context.subscriptions);
+        plugin.state = 'active';
+      } catch (err) {
+        plugin.state = 'failed';
+        console.error(`Failed to activate plugin ${id}:`, err);
+      }
+    }
+  }
+
+  /**
+   * Deactivate a single plugin — cleanup resources
+   */
+  async deactivate(id: string): Promise<void> {
+    const plugin = this.plugins.get(id);
+    if (!plugin || plugin.state !== 'active') return;
+
+    try {
+      await plugin.instance.deactivate?.();
+    } finally {
+      // Always dispose resources, even if deactivate() throws
+      for (const d of plugin.disposables) {
+        try { d.dispose(); } catch { /* swallow */ }
+      }
+      plugin.disposables = [];
+      plugin.state = 'resolved';
+    }
+  }
+
+  private createContext(pluginId: string): PluginContext {
+    const subscriptions: Disposable[] = [];
+    return {
+      events: this.createScopedEventBus(pluginId),
+      registerCommand: (cmdId, handler) => {
+        return this.registerCommand(`${pluginId}.${cmdId}`, handler);
+      },
+      registerProvider: (ep, provider) => {
+        if (!this.extensionPoints.has(ep)) {
+          this.extensionPoints.set(ep, new Set());
+        }
+        this.extensionPoints.get(ep)!.add(provider);
+        return {
+          dispose: () => this.extensionPoints.get(ep)?.delete(provider),
+        };
+      },
+      storage: this.createPluginStorage(pluginId),
+      logger: this.createScopedLogger(pluginId),
+      subscriptions,
+    };
+  }
+
+  private topologicalSort(): string[] {
+    // Standard topological sort on dependency graph
+    const visited = new Set<string>();
+    const result: string[] = [];
+
+    const visit = (id: string) => {
+      if (visited.has(id)) return;
+      visited.add(id);
+      const plugin = this.plugins.get(id);
+      if (!plugin) return;
+      for (const depId of Object.keys(plugin.manifest.dependencies ?? {})) {
+        visit(depId);
+      }
+      result.push(id);
+    };
+
+    for (const id of this.plugins.keys()) visit(id);
+    return result;
+  }
+
+  // Stub methods — implementations depend on host application
+  private createScopedEventBus(pluginId: string): EventBus { /* ... */ }
+  private registerCommand(id: string, handler: CommandHandler): Disposable { /* ... */ }
+  private createPluginStorage(pluginId: string): PluginStorage { /* ... */ }
+  private createScopedLogger(pluginId: string): Logger { /* ... */ }
+}
+```
+
+### Example Plugin
+
+```typescript
+import type { Plugin, PluginContext, Disposable } from '@host/plugin-api';
+
+const markdownPreview: Plugin = {
+  id: 'com.example.markdown-preview',
+  version: '1.2.0',
+
+  async activate(context: PluginContext): Promise<void> {
+    // Register a command
+    context.subscriptions.push(
+      context.registerCommand('preview', async (args) => {
+        const content = await args.document.getText();
+        const html = renderMarkdown(content);
+        await context.events.emit('webview:create', {
+          title: 'Markdown Preview',
+          html,
+        });
+      })
+    );
+
+    // Listen for file changes to update preview
+    context.subscriptions.push(
+      context.events.on('document:change', async (event) => {
+        if (event.languageId !== 'markdown') return;
+        const html = renderMarkdown(event.document.getText());
+        await context.events.emit('webview:update', { html });
+      })
+    );
+
+    context.logger.info('Markdown Preview activated');
+  },
+
+  async deactivate(): Promise<void> {
+    // subscriptions are auto-disposed by the host
+    // only manual cleanup needed here (e.g., close network connections)
+  },
+};
+
+export default markdownPreview;
+```
+
+---
+
+## Cross-References
+
+- **[hexagonal-clean-architecture](./hexagonal-clean-architecture.md)** — Plugin architecture and hexagonal architecture are complementary. The core of a plugin system often uses hexagonal architecture internally, with plugins acting as adapters that plug into ports (extension points). The Dependency Rule applies: plugins depend on the core's API, never the reverse.
+
+- **[microservices](../../microservices.md)** — Microservices decompose across network boundaries; plugins decompose within a single application boundary. Choose microservices when teams need independent deployment and technology heterogeneity. Choose plugins when extensions must integrate tightly with a host application's UI, data model, or runtime.
+
+- **[feature-flags-and-rollouts](../../../design/feature-flags-and-rollouts.md)** — Feature flags toggle existing code; plugins add new code. For internal feature variation, feature flags are almost always simpler. For external extensibility, plugins are necessary. The two can coexist: a plugin system might use feature flags to gate experimental extension points.
+
+- **[coupling-and-cohesion](../../../design/coupling-and-cohesion.md)** — Plugin architecture achieves low coupling between the core and extensions through interface contracts and lifecycle isolation. High cohesion within each plugin (a plugin does one thing well) is a design goal. The plugin API surface is the coupling boundary — wider APIs create tighter coupling between core and plugins.