feature: Plugin model on typed extension points + plugin test harness (wvlet.uni.plugin)

[xerial]

Why

Final layer of the multi-layer testing goal: make Uni a foundation for apps built from pluggable units, testable in isolation — VSCode's extension/plugin testing layer. Uni had no plugin/extension model; this adds a minimal one plus the harness to test plugins.

Since wvlet.uni.plugin is a top-level namespace alongside design, rx, surface — and uni is not Electron-specific — the core model must be generic: it hardcodes no contribution kinds and has no dependency on wvlet.uni.http.rpc. See adr/2026-07-06-plugin-extension-points.md.

What

wvlet.uni.plugin — a VSCode-style extension model built on typed extension points, shipped in the published uni artifact (cross-platform: JVM/JS/Native):

• Plugin — id + activate(context), mirroring VSCode's activate(context).
• PluginContext — deliberately minimal registration surface: contribute(point)(value) + onDeactivate(hook).
• ExtensionPoint[A] — a typed contribution slot, compared by identity (define points as shared vals). ExtensionPoint.keyed(name)(keyOf) makes contributions unique by key: a duplicate key — within a plugin or across plugins — is rejected at activation, so conflicts surface in tests rather than at runtime.
• PluginHost — activates plugins and owns the per-point registries: contributions(point), contribution(point, key), deactivate() (FILO hooks + reset). Re-activating the same plugin id is rejected.

Contribution kinds are defined next to their types, so dependency arrows point into the plugin layer:

• wvlet.uni.plugin.Command — Command.point (keyed by command id) + extension methods registerCommand, executeCommand, commandIds, hasCommand.
• wvlet.uni.http.rpc.RPCPlugin — routerPoint + extension methods registerRpcRouter, rpcRouters, rpcDispatcher (an RPCDispatcher over all contributed routers, ready to serve via HTTP or Electron IPC).

New kinds (views, menus, Design bindings) are added by defining a point — not by editing the core.

import wvlet.uni.plugin.Command.*
import wvlet.uni.http.rpc.RPCPlugin.*

class NotesPlugin extends Plugin:
  def id = "notes"
  def activate(ctx: PluginContext): Unit =
    ctx.registerRpcRouter(RPCRouter.of[NotesApi](NotesApiImpl()))
    ctx.registerCommand("notes.new")(_ => createNote())
    ctx.onDeactivate(() => flushToDisk())

Test harness

• wvlet.uni.plugin.testing.PluginTestHost — activate(plugin) / activateAll(plugins*) activate plugin(s) against a fresh host through the real activation path and return the host for assertions. Because the host is cross-platform, plugin tests run on the JVM with no Electron/browser runtime.

val host = PluginTestHost.activate(NotesPlugin())
host.commandIds shouldContain "notes.new"
host.executeCommand("notes.new") shouldBe expectedNote
host.rpcRouters.flatMap(_.routes.map(_.path)).exists(_.endsWith("/list")) shouldBe true

Tests

PluginHostTest (10 tests, JVM green; compiles on JS + Native): command registration/execution, unknown-command error, RPC-router contribution, app-defined extension points, unkeyed multi-contribution, lifecycle teardown, and conflict rejection (duplicate within a plugin, across plugins, and double-activation).

Roadmap status

unit → UI (#616) → Electron (#616) → tags (#617) → plugin (this). Richer contribution points (views, menus, a typed command API, Design bindings), and a JS bridge from RPCPlugin.rpcDispatcher into ElectronTestbed for full end-to-end plugin-RPC tests, are natural follow-ups.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a plugin system for the Uni desktop application, including the Plugin and PluginContext traits, a PluginHost runtime manager, a PluginTestHost helper for isolated testing, and corresponding unit tests. The feedback suggests improving the robustness of plugin activation by making it atomic to prevent partial registrations if activation fails, logging exceptions caught during deactivation instead of swallowing them silently, and adding a unit test to verify the rollback of partial registrations.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If a plugin throws an exception during its activate method, any commands, RPC routers, or deactivation hooks registered prior to the exception will remain in the host's global registries, while the plugin itself is not marked as activated. This leaves the PluginHost in a corrupted, partially-activated state.

To ensure atomicity, we should accumulate registrations in a temporary context during activation and only commit them to the host's global registries once the plugin's activate method completes successfully.

  /** Activate a single plugin. Returns this host for chaining. */
  def activate(plugin: Plugin): PluginHost = 
    if _activated.contains(plugin.id) then
      throw IllegalArgumentException(s"Plugin '${plugin.id}' is already activated")

    val localCommands = mutable.LinkedHashMap.empty[String, Seq[Any] => Any]
    val localRouters  = mutable.ListBuffer.empty[RPCRouter]
    val localHooks    = mutable.ListBuffer.empty[() => Unit]

    val context = new PluginContext:
      override def registerCommand(id: String)(handler: Seq[Any] => Any): Unit = 
        if commands.contains(id) || localCommands.contains(id) then
          throw IllegalArgumentException(
            s"Command '${id}' is already registered (attempted by plugin '${plugin.id}')"
          )
        localCommands(id) = handler

      override def registerRpcRouter(router: RPCRouter): Unit = 
        localRouters += router

      override def onDeactivate(hook: () => Unit): Unit = 
        localHooks += hook

    plugin.activate(context)

    // Commit contributions only after successful activation
    commands ++= localCommands
    _routers ++= localRouters
    deactivateHooks ++= localHooks
    _activated += plugin.id
    this

[gemini-code-assist]

Swallowing exceptions silently during deactivation makes debugging teardown issues extremely difficult. It is highly recommended to log these failures.

To do this, you can make PluginHost extend LogSupport (imported from wvlet.uni.log.LogSupport) and log a warning when a hook fails.

  def deactivate(): Unit = 
    deactivateHooks
      .reverseIterator
      .foreach { hook =>
        try
          hook()
        catch
          case e: Throwable =>
            warn(s"Error running deactivation hook: ${e.getMessage}", e)
      }

[gemini-code-assist]

Add a unit test to verify that partial registrations are correctly rolled back and not committed to the host if a plugin fails to activate.

  test("activating the same plugin id twice is rejected") {
    val host = PluginTestHost.activate(NotesPlugin())
    intercept[IllegalArgumentException] {
      host.activate(NotesPlugin())
    }
  }

  test("partial registrations are rolled back if activation fails") {
    val host = new PluginHost()
    val plugin =
      new Plugin:
        override def id: String                             = "failed-plugin"
        override def activate(context: PluginContext): Unit =
          context.registerCommand("partial-cmd")(_ => 1)
          context.registerRpcRouter(RPCRouter.of[NotesApi](NotesApiImpl()))
          throw new RuntimeException("activation failed")

    intercept[RuntimeException] {
      host.activate(plugin)
    }

    host.hasCommand("partial-cmd") shouldBe false
    host.routers shouldBe empty
    host.activatedPlugins shouldBe empty
  }

end PluginHostTest