feat: add AppMetadataPlugin interface, install/uninstall methods, and example plugins

Copilot · hotlong · Copilot · commit e6f950da9189 · 2026-03-04T03:58:41.000Z
- Define AppMetadataPlugin and PluginContext interfaces in @object-ui/types
- Add install() and uninstall() convenience methods to PluginSystem
- Create TodoPlugin (examples/todo/plugin.ts) and KitchenSinkPlugin (examples/kitchen-sink/plugin.ts)
- Add stop() and getConfig() to CRMPlugin for full lifecycle support
- Update package.json exports for todo and kitchen-sink examples
- Refactor root objectstack.config.ts to use plugin-based config collection
- Add 5 new tests for install/uninstall (18 total, all passing)

Co-authored-by: hotlong &lt;50353452+hotlong@users.noreply.github.com&gt;
diff --git a/examples/crm/plugin.ts b/examples/crm/plugin.ts
@@ -53,6 +53,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;
diff --git a/examples/kitchen-sink/package.json b/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",
diff --git a/examples/kitchen-sink/plugin.ts b/examples/kitchen-sink/plugin.ts
@@ -0,0 +1,67 @@
+/**
+ * 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 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: any) {
+    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;
diff --git a/examples/todo/package.json b/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",
diff --git a/examples/todo/plugin.ts b/examples/todo/plugin.ts
@@ -0,0 +1,67 @@
+/**
+ * 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 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: any) {
+    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;
diff --git a/objectstack.config.ts b/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
diff --git a/packages/core/src/registry/PluginSystem.ts b/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 } 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?: Record<string, any>): 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);
+  }
 }
diff --git a/packages/core/src/registry/__tests__/PluginSystem.test.ts b/packages/core/src/registry/__tests__/PluginSystem.test.ts
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
diff --git a/packages/types/src/plugin-scope.ts b/packages/types/src/plugin-scope.ts

Original file line number	Diff line number	Diff line change
`@@ -53,6 +53,15 @@ export class CRMPlugin {`
`53`	`53`	`logger.info('[CRM] Config is available via crmConfig export for manual merging');`
`54`	`54`	`}`
`55`	`55`	`}`
	`56`	`+`
	`57`	`+ async stop() {`
	`58`	`+ // Teardown: no persistent resources to release`
	`59`	`+ }`
	`60`	`+`
	`61`	`+ /** Raw stack configuration for legacy/manual merging */`
	`62`	`+ getConfig() {`
	`63`	`+ return config;`
	`64`	`+ }`
`56`	`65`	`}`
`57`	`66`
`58`	`67`	`export default CRMPlugin;`