Merge pull request #1019 from objectstack-ai/copilot/refactor-objectui-plugin-architecture

Author: hotlong

ROADMAP.md

@@ -1,6 +1,6 @@
 # ObjectUI Development Roadmap
 
-> **Last Updated:** March 2, 2026
+> **Last Updated:** March 4, 2026
 > **Current Version:** v0.5.x
 > **Spec Version:** @objectstack/spec v3.2.0
 > **Client Version:** @objectstack/client v3.2.0
@@ -1164,6 +1164,38 @@ The `FlowDesigner` is a canvas-based flow editor that bridges the gap between th
 - [ ] Conflict resolution on reconnection wired into Console flow
 - [ ] Optimistic updates with TransactionManager state application
 
+### P2.6 Plugin Modularization & Dynamic Management
+
+> **Status:** Phase 1 complete — Plugin class standard, install/uninstall API, example plugin classes.
+
+Plugin architecture refactoring to support true modular development, plugin isolation, and dynamic plugin install/uninstall at runtime.
+
+**Phase 1 — Plugin Class Standard & Example Plugins ✅**
+- [x] Define `AppMetadataPlugin` interface in `@object-ui/types` (name, version, type, description, init/start/stop/getConfig)
+- [x] Define `PluginContext` interface for lifecycle hook context (logger, kernel)
+- [x] Add `install(plugin)` / `uninstall(pluginName)` convenience methods to `PluginSystem` in `@object-ui/core`
+- [x] Create `CRMPlugin` with full lifecycle (init/start/stop/getConfig) — `examples/crm/plugin.ts`
+- [x] Create `TodoPlugin` — `examples/todo/plugin.ts`
+- [x] Create `KitchenSinkPlugin` — `examples/kitchen-sink/plugin.ts`
+- [x] Update `package.json` exports for all example apps (`./plugin` entry point)
+- [x] Refactor root `objectstack.config.ts` to use plugin-based config collection via `getConfig()`
+- [x] Unit tests for `install()` / `uninstall()` (5 new tests, 18 total in PluginSystem)
+
+**Phase 2 — Dynamic Plugin Loading (Planned)**
+- [ ] Hot-reload / lazy loading of plugins for development
+- [ ] Runtime plugin discovery and loading from registry
+- [ ] Plugin dependency graph visualization in Console
+
+**Phase 3 — Plugin Identity & Isolation (Planned)**
+- [ ] Preserve origin plugin metadata on objects, actions, dashboards for runtime inspection
+- [ ] Per-plugin i18n namespace support
+- [ ] Per-plugin permissions and data isolation
+
+**Phase 4 — Cross-Repo Plugin Ecosystem (Planned)**
+- [ ] Plugin marketplace / registry for third-party plugins
+- [ ] Plugin publish/validate tooling (spec v3.0.9 `PluginBuildOptions`, `PluginPublishOptions`)
+- [ ] Cross-repo plugin loading from npm packages
+
 ---
 
 ## 🔮 P3 — Future Vision (Deferred)

examples/crm/plugin.ts

@@ -18,6 +18,7 @@
  *   import { crmConfig } from '@object-ui/example-crm/plugin';
  */
 
+import type { AppPluginContext } from '@object-ui/types';
 import config from './objectstack.config';
 
 /** Raw CRM stack configuration for direct merging */
@@ -39,7 +40,7 @@ export class CRMPlugin {
     // No initialization needed
   }
 
-  async start(ctx: any) {
+  async start(ctx: AppPluginContext) {
     const logger = ctx.logger || console;
 
     try {
@@ -53,6 +54,15 @@ export class CRMPlugin {
       logger.info('[CRM] Config is available via crmConfig export for manual merging');
     }
   }
+
+  async stop() {
+    // Teardown: no persistent resources to release
+  }
+
+  /** Raw stack configuration for legacy/manual merging */
+  getConfig() {
+    return config;
+  }
 }
 
 export default CRMPlugin;

examples/kitchen-sink/package.json

@@ -7,7 +7,8 @@
   "types": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
-    "./objectstack.config": "./objectstack.config.ts"
+    "./objectstack.config": "./objectstack.config.ts",
+    "./plugin": "./plugin.ts"
   },
   "scripts": {
     "serve": "objectstack serve objectstack.config.ts",

examples/kitchen-sink/plugin.ts

@@ -0,0 +1,68 @@
+/**
+ * Kitchen Sink Example Plugin
+ *
+ * Exports the Kitchen Sink configuration as an ObjectStack plugin that can be
+ * loaded by any ObjectStack application. Other projects can import
+ * the Kitchen Sink metadata (objects, apps, dashboards, manifest) without
+ * needing to know the internal structure.
+ *
+ * Usage in another project:
+ *
+ *   import { KitchenSinkPlugin } from '@object-ui/example-kitchen-sink/plugin';
+ *
+ *   const kernel = new ObjectKernel();
+ *   kernel.use(new KitchenSinkPlugin());
+ *
+ * Or import the raw config for merging:
+ *
+ *   import { kitchenSinkConfig } from '@object-ui/example-kitchen-sink/plugin';
+ */
+
+import type { AppPluginContext } from '@object-ui/types';
+import config from './objectstack.config';
+
+/** Raw Kitchen Sink stack configuration for direct merging */
+export const kitchenSinkConfig = config;
+
+/**
+ * Kitchen Sink Plugin — wraps the Kitchen Sink metadata as a kernel-compatible plugin.
+ *
+ * When loaded via `kernel.use(new KitchenSinkPlugin())`, ObjectStack's AppPlugin
+ * will register all Kitchen Sink objects, apps, dashboards, and seed data.
+ */
+export class KitchenSinkPlugin {
+  readonly name = '@object-ui/example-kitchen-sink';
+  readonly version = '1.0.0';
+  readonly type = 'app-metadata' as const;
+  readonly description = 'Kitchen Sink showcase metadata (all field types, views, and UI capabilities)';
+
+  async init() {
+    // No initialization needed
+  }
+
+  async start(ctx: AppPluginContext) {
+    const logger = ctx.logger || console;
+
+    try {
+      // Dynamically import AppPlugin to keep plugin.ts dependency-light
+      const { AppPlugin } = await import('@objectstack/runtime');
+      const appPlugin = new AppPlugin(config);
+      await ctx.kernel?.use?.(appPlugin);
+      logger.info('[KitchenSink] Metadata loaded: objects, apps, dashboards, seed data');
+    } catch (e: any) {
+      logger.warn(`[KitchenSink] Could not auto-register via AppPlugin: ${e.message}`);
+      logger.info('[KitchenSink] Config is available via kitchenSinkConfig export for manual merging');
+    }
+  }
+
+  async stop() {
+    // Teardown: no persistent resources to release
+  }
+
+  /** Raw stack configuration for legacy/manual merging */
+  getConfig() {
+    return config;
+  }
+}
+
+export default KitchenSinkPlugin;

examples/todo/package.json

@@ -5,7 +5,8 @@
   "private": true,
   "type": "module",
   "exports": {
-    "./objectstack.config": "./objectstack.config.ts"
+    "./objectstack.config": "./objectstack.config.ts",
+    "./plugin": "./plugin.ts"
   },
   "scripts": {
     "serve": "objectstack serve objectstack.config.ts",

examples/todo/plugin.ts

@@ -0,0 +1,68 @@
+/**
+ * Todo Example Plugin
+ *
+ * Exports the Todo configuration as an ObjectStack plugin that can be
+ * loaded by any ObjectStack application. Other projects can import
+ * the Todo metadata (objects, apps, dashboards, manifest) without
+ * needing to know the internal structure.
+ *
+ * Usage in another project:
+ *
+ *   import { TodoPlugin } from '@object-ui/example-todo/plugin';
+ *
+ *   const kernel = new ObjectKernel();
+ *   kernel.use(new TodoPlugin());
+ *
+ * Or import the raw config for merging:
+ *
+ *   import { todoConfig } from '@object-ui/example-todo/plugin';
+ */
+
+import type { AppPluginContext } from '@object-ui/types';
+import config from './objectstack.config';
+
+/** Raw Todo stack configuration for direct merging */
+export const todoConfig = config;
+
+/**
+ * Todo Plugin — wraps the Todo metadata as a kernel-compatible plugin.
+ *
+ * When loaded via `kernel.use(new TodoPlugin())`, ObjectStack's AppPlugin
+ * will register all Todo objects, apps, dashboards, and seed data.
+ */
+export class TodoPlugin {
+  readonly name = '@object-ui/example-todo';
+  readonly version = '1.0.0';
+  readonly type = 'app-metadata' as const;
+  readonly description = 'Task management metadata (objects, apps, dashboards, seed data)';
+
+  async init() {
+    // No initialization needed
+  }
+
+  async start(ctx: AppPluginContext) {
+    const logger = ctx.logger || console;
+
+    try {
+      // Dynamically import AppPlugin to keep plugin.ts dependency-light
+      const { AppPlugin } = await import('@objectstack/runtime');
+      const appPlugin = new AppPlugin(config);
+      await ctx.kernel?.use?.(appPlugin);
+      logger.info('[Todo] Metadata loaded: objects, apps, dashboards, seed data');
+    } catch (e: any) {
+      logger.warn(`[Todo] Could not auto-register via AppPlugin: ${e.message}`);
+      logger.info('[Todo] Config is available via todoConfig export for manual merging');
+    }
+  }
+
+  async stop() {
+    // Teardown: no persistent resources to release
+  }
+
+  /** Raw stack configuration for legacy/manual merging */
+  getConfig() {
+    return config;
+  }
+}
+
+export default TodoPlugin;

objectstack.config.ts

@@ -12,30 +12,33 @@
  * because CRM and Kitchen Sink both define an `account` object, which would
  * trigger an ownership conflict in the ObjectQL Schema Registry.
  *
+ * Plugins: Each example app exports a plugin class (CRMPlugin, TodoPlugin,
+ * KitchenSinkPlugin) that implements the AppMetadataPlugin interface.
+ * For standalone use, each plugin can be loaded independently via
+ * `kernel.use(new CRMPlugin())`. In the dev workspace, we collect their
+ * configs via `getConfig()` and merge them into a single AppPlugin.
  */
 import { defineStack } from '@objectstack/spec';
 import { AppPlugin, DriverPlugin } from '@objectstack/runtime';
 import { ObjectQLPlugin } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 import { HonoServerPlugin } from '@objectstack/plugin-hono-server';
 import { ConsolePlugin } from '@object-ui/console';
-import CrmConfig from './examples/crm/objectstack.config';
-import TodoConfig from './examples/todo/objectstack.config';
-import KitchenSinkConfig from './examples/kitchen-sink/objectstack.config';
+import { CRMPlugin } from './examples/crm/plugin';
+import { TodoPlugin } from './examples/todo/plugin';
+import { KitchenSinkPlugin } from './examples/kitchen-sink/plugin';
 
-const crm = (CrmConfig as any).default || CrmConfig;
-const todo = (TodoConfig as any).default || TodoConfig;
-const kitchenSink = (KitchenSinkConfig as any).default || KitchenSinkConfig;
+// Instantiate example plugins
+const plugins = [new CRMPlugin(), new TodoPlugin(), new KitchenSinkPlugin()];
 
-// Base objects from built-in examples
-const baseObjects = [
-  ...(crm.objects || []),
-  ...(todo.objects || []),
-  ...(kitchenSink.objects || []),
-];
+// Collect raw configs from each plugin via getConfig()
+const allConfigs = plugins.map((p) => {
+  const raw = p.getConfig();
+  return (raw as any).default || raw;
+});
 
-// Collect all example configs for view merging
-const allConfigs = [crm, todo, kitchenSink];
+// Base objects from all plugins
+const baseObjects = allConfigs.flatMap((cfg: any) => cfg.objects || []);
 
 // ---------------------------------------------------------------------------
 // Merge stack-level views into object definitions.
@@ -110,44 +113,22 @@ function mergeActionsIntoObjects(objects: any[], configs: any[]): any[] {
   });
 }
 
-// Merge all example configs into a single app bundle for AppPlugin
+// Merge all plugin configs into a single app bundle for AppPlugin
 const mergedApp = defineStack({
   manifest: {
     id: 'dev-workspace',
     name: 'dev_workspace',
     version: '0.0.0',
     description: 'ObjectUI monorepo development workspace',
     type: 'app',
-    data: [
-      ...(crm.manifest?.data || []),
-      ...(todo.manifest?.data || []),
-      ...(kitchenSink.manifest?.data || []),
-    ],
+    data: allConfigs.flatMap((cfg: any) => cfg.manifest?.data || []),
   },
   objects: baseObjects,
-  views: [
-    ...(crm.views || []),
-    ...(todo.views || []),
-    ...(kitchenSink.views || []),
-  ],
-  apps: [
-    ...(crm.apps || []),
-    ...(todo.apps || []),
-    ...(kitchenSink.apps || []),
-  ],
-  dashboards: [
-    ...(crm.dashboards || []),
-    ...(todo.dashboards || []),
-    ...(kitchenSink.dashboards || []),
-  ],
-  reports: [
-    ...(crm.reports || []),
-  ],
-  pages: [
-    ...(crm.pages || []),
-    ...(todo.pages || []),
-    ...(kitchenSink.pages || []),
-  ],
+  views: allConfigs.flatMap((cfg: any) => cfg.views || []),
+  apps: allConfigs.flatMap((cfg: any) => cfg.apps || []),
+  dashboards: allConfigs.flatMap((cfg: any) => cfg.dashboards || []),
+  reports: allConfigs.flatMap((cfg: any) => cfg.reports || []),
+  pages: allConfigs.flatMap((cfg: any) => cfg.pages || []),
 } as any);
 
 // Re-merge listViews and actions that defineStack stripped from objects

packages/core/src/registry/PluginSystem.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Registry } from './Registry.js';
-import type { PluginScope, PluginScopeConfig } from '@object-ui/types';
+import type { PluginScope, PluginScopeConfig, AppMetadataPlugin, AppPluginContext } from '@object-ui/types';
 import { PluginScopeImpl } from './PluginScopeImpl.js';
 
 export interface PluginDefinition {
@@ -158,4 +158,49 @@ export class PluginSystem {
   getAllPlugins(): PluginDefinition[] {
     return Array.from(this.plugins.values());
   }
+
+  /**
+   * Install an AppMetadataPlugin at runtime.
+   *
+   * Wraps the plugin as a PluginDefinition, calls its `init()` and `start()`
+   * lifecycle hooks, and loads it into the system.
+   *
+   * @param plugin - An AppMetadataPlugin instance
+   * @param registry - The component registry
+   * @param ctx - Optional context passed to the plugin's start() hook
+   */
+  async install(plugin: AppMetadataPlugin, registry: Registry, ctx?: AppPluginContext): Promise<void> {
+    if (this.loaded.has(plugin.name)) {
+      console.warn(`Plugin "${plugin.name}" is already installed. Skipping.`);
+      return;
+    }
+
+    await plugin.init();
+
+    const definition: PluginDefinition = {
+      name: plugin.name,
+      version: plugin.version,
+      register: () => {},
+      onLoad: async () => {
+        await plugin.start(ctx ?? { logger: console });
+      },
+      onUnload: async () => {
+        await plugin.stop();
+      },
+    };
+
+    await this.loadPlugin(definition, registry);
+  }
+
+  /**
+   * Uninstall an AppMetadataPlugin at runtime.
+   *
+   * Calls the plugin's `stop()` lifecycle hook (via onUnload) and
+   * removes it from the system.
+   *
+   * @param pluginName - Name of the plugin to uninstall
+   */
+  async uninstall(pluginName: string): Promise<void> {
+    await this.unloadPlugin(pluginName);
+  }
 }