feat(runtime): add Runtime and ApiRegistryPlugin for enhanced API management

Author: hotlong

packages/runtime/src/api-registry-plugin.ts

@@ -0,0 +1,58 @@
+import { Plugin, PluginContext, IHttpServer } from '@objectstack/core';
+import { RestServer } from './rest-server.js';
+import { ObjectStackProtocol, RestServerConfig } from '@objectstack/spec/api';
+
+export interface ApiRegistryConfig {
+    serverServiceName?: string;
+    protocolServiceName?: string;
+    api?: RestServerConfig;
+}
+
+/**
+ * ApiRegistryPlugin
+ * 
+ * Responsibilities:
+ * 1. Consumes 'http.server' (or configured service)
+ * 2. Consumes 'protocol' (ObjectStackProtocol)
+ * 3. Instantiates RestServer to auto-generate routes
+ */
+export function createApiRegistryPlugin(config: ApiRegistryConfig = {}): Plugin {
+    return {
+        name: 'com.objectstack.runtime.api-registry',
+        version: '1.0.0',
+        
+        init: async (ctx: PluginContext) => {
+            // No service registration, this is a consumer plugin
+        },
+        
+        start: async (ctx: PluginContext) => {
+            const serverService = config.serverServiceName || 'http.server';
+            const protocolService = config.protocolServiceName || 'protocol';
+            
+            const server = ctx.getService<IHttpServer>(serverService);
+            const protocol = ctx.getService<ObjectStackProtocol>(protocolService);
+            
+            if (!server) {
+                ctx.logger.warn(`ApiRegistryPlugin: HTTP Server service '${serverService}' not found. REST routes skipped.`);
+                return;
+            }
+            
+            if (!protocol) {
+                ctx.logger.warn(`ApiRegistryPlugin: Protocol service '${protocolService}' not found. REST routes skipped.`);
+                return;
+            }
+            
+            ctx.logger.info('Hydrating REST API from Protocol...');
+            
+            try {
+                const restServer = new RestServer(server, protocol, config.api);
+                restServer.registerRoutes();
+                
+                ctx.logger.info('REST API successfully registered');
+            } catch (err: any) {
+                ctx.logger.error('Failed to register REST API routes', { error: err.message });
+                throw err;
+            }
+        }
+    };
+}

packages/runtime/src/index.ts

@@ -1,9 +1,15 @@
 // Export Kernels
 export { ObjectKernel } from '@objectstack/core';
 
+// Export Runtime
+export { Runtime } from './runtime.js';
+export type { RuntimeConfig } from './runtime.js';
+
 // Export Plugins
 export { DriverPlugin } from './driver-plugin.js';
 export { AppPlugin } from './app-plugin.js';
+export { createApiRegistryPlugin } from './api-registry-plugin.js';
+export type { ApiRegistryConfig } from './api-registry-plugin.js';
 
 // Export HTTP Server Components
 export { HttpServer } from './http-server.js';

packages/runtime/src/runtime.ts

@@ -0,0 +1,73 @@
+import { ObjectKernel, Plugin, IHttpServer } from '@objectstack/core';
+import { HttpServer } from './http-server.js';
+import { createApiRegistryPlugin, ApiRegistryConfig } from './api-registry-plugin.js';
+
+export interface RuntimeConfig {
+    /**
+     * Optional existing server instance (e.g. Hono, Express app)
+     * If provided, Runtime will use it as the 'http.server' service.
+     * If not provided, Runtime expects a server plugin (like HonoServerPlugin) to be registered manually.
+     */
+    server?: IHttpServer;
+    
+    /**
+     * API Registry Configuration
+     */
+    api?: ApiRegistryConfig;
+}
+
+/**
+ * ObjectStack Runtime
+ * 
+ * High-level entry point for bootstrapping an ObjectStack application.
+ * Wraps ObjectKernel and provides standard orchestration for:
+ * - HTTP Server binding
+ * - API Registry (REST Routes)
+ * - Plugin Management
+ */
+export class Runtime {
+    readonly kernel: ObjectKernel;
+    
+    constructor(config: RuntimeConfig = {}) {
+        this.kernel = new ObjectKernel();
+        
+        // If external server provided, register it immediately
+        if (config.server) {
+             // If the provided server is not already an HttpServer wrapper, wrap it?
+             // Since IHttpServer is the interface, we assume it complies.
+             // But HttpServer class in runtime is an adapter.
+             // If user passes raw Hono, it won't work unless they wrapped it.
+             // We'll assume they pass a compliant IHttpServer.
+             this.kernel.registerService('http.server', config.server);
+        }
+        
+        // Register API Registry by default
+        // This plugin is passive (wait for services) so it's safe to add early.
+        this.kernel.use(createApiRegistryPlugin(config.api));
+    }
+    
+    /**
+     * Register a plugin
+     */
+    use(plugin: Plugin) {
+        this.kernel.use(plugin);
+        return this;
+    }
+    
+    /**
+     * Start the runtime
+     * 1. Initializes all plugins (init phase)
+     * 2. Starts all plugins (start phase)
+     */
+    async start() {
+        await this.kernel.bootstrap();
+        return this;
+    }
+    
+    /**
+     * Get the kernel instance
+     */
+    getKernel() {
+        return this.kernel;
+    }
+}