@objectstack/runtime 0.9.2 → 1.0.1

package/dist/rest-server.js

@@ -250,6 +250,34 @@ export class RestServer {
                 },
             });
         }
+        // PUT /meta/:type/:name - Save metadata item
+        // We always register this route, but return 501 if protocol doesn't support it
+        // This makes it discoverable even if not implemented
+        this.routeManager.register({
+            method: 'PUT',
+            path: `${metaPath}/:type/:name`,
+            handler: async (req, res) => {
+                try {
+                    if (!this.protocol.saveMetaItem) {
+                        res.status(501).json({ error: 'Save operation not supported by protocol implementation' });
+                        return;
+                    }
+                    const result = await this.protocol.saveMetaItem({
+                        type: req.params.type,
+                        name: req.params.name,
+                        item: req.body
+                    });
+                    res.json(result);
+                }
+                catch (error) {
+                    res.status(400).json({ error: error.message });
+                }
+            },
+            metadata: {
+                summary: 'Save specific metadata item',
+                tags: ['metadata'],
+            },
+        });
     }
     /**
      * Register CRUD endpoints for data operations

package/dist/runtime.d.ts

@@ -0,0 +1,45 @@
+import { ObjectKernel, Plugin, IHttpServer, ObjectKernelConfig } from '@objectstack/core';
+import { 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;
+    /**
+     * Kernel Configuration
+     */
+    kernel?: ObjectKernelConfig;
+}
+/**
+ * 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 declare class Runtime {
+    readonly kernel: ObjectKernel;
+    constructor(config?: RuntimeConfig);
+    /**
+     * Register a plugin
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Start the runtime
+     * 1. Initializes all plugins (init phase)
+     * 2. Starts all plugins (start phase)
+     */
+    start(): Promise<this>;
+    /**
+     * Get the kernel instance
+     */
+    getKernel(): ObjectKernel;
+}

package/dist/runtime.js

@@ -0,0 +1,50 @@
+import { ObjectKernel } from '@objectstack/core';
+import { createApiRegistryPlugin } from './api-registry-plugin.js';
+/**
+ * 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 {
+    constructor(config = {}) {
+        this.kernel = new ObjectKernel(config.kernel);
+        // 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) {
+        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;
+    }
+}

package/dist/runtime.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Runtime } from './runtime';
+// Mock ObjectKernel to isolate Runtime logic
+vi.mock('@objectstack/core', async () => {
+    const actual = await vi.importActual('@objectstack/core');
+    return {
+        ...actual,
+        ObjectKernel: class {
+            constructor() {
+                this.use = vi.fn();
+                this.registerService = vi.fn();
+                this.bootstrap = vi.fn().mockResolvedValue(undefined);
+                this.getServices = vi.fn().mockReturnValue(new Map());
+            }
+        }
+    };
+});
+describe('Runtime', () => {
+    it('should initialize successfully', () => {
+        const runtime = new Runtime();
+        expect(runtime).toBeDefined();
+        // Should create a kernel
+        expect(runtime.getKernel()).toBeDefined();
+    });
+    it('should register api registry plugin by default', () => {
+        const runtime = new Runtime();
+        const kernel = runtime.getKernel();
+        // Check if use was called (at least once for api registry)
+        expect(kernel.use).toHaveBeenCalled();
+    });
+    it('should register external http server if provided', () => {
+        const mockServer = {
+            listen: vi.fn(),
+            close: vi.fn(),
+            get: vi.fn(),
+            post: vi.fn(),
+            put: vi.fn(),
+            delete: vi.fn(),
+            patch: vi.fn(),
+            use: vi.fn(),
+        };
+        const runtime = new Runtime({ server: mockServer });
+        const kernel = runtime.getKernel();
+        expect(kernel.registerService).toHaveBeenCalledWith('http.server', mockServer);
+    });
+    it('should delegate use() to kernel', () => {
+        const runtime = new Runtime();
+        const mockPlugin = { name: 'test', init: vi.fn() };
+        runtime.use(mockPlugin);
+        expect(runtime.getKernel().use).toHaveBeenCalledWith(mockPlugin);
+    });
+    it('should delegate start() to kernel.bootstrap()', async () => {
+        const runtime = new Runtime();
+        await runtime.start();
+        expect(runtime.getKernel().bootstrap).toHaveBeenCalled();
+    });
+});

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "@objectstack/runtime",
-  "version": "0.9.2",
+  "version": "1.0.1",
+  "license": "Apache-2.0",
   "description": "ObjectStack Core Runtime & Query Engine",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/core": "0.9.2",
-    "@objectstack/spec": "0.9.2",
-    "@objectstack/types": "0.9.2"
+    "@objectstack/core": "1.0.1",
+    "@objectstack/spec": "1.0.1",
+    "@objectstack/types": "1.0.1"
   },
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
   },
   "scripts": {
     "build": "tsc",
-    "dev": "tsc -w"
+    "dev": "tsc -w",
+    "test": "vitest run"
   }
 }

package/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 as any);
+                restServer.registerRoutes();
+                
+                ctx.logger.info('REST API successfully registered');
+            } catch (err: any) {
+                ctx.logger.error('Failed to register REST API routes', { error: err.message } as any);
+                throw err;
+            }
+        }
+    };
+}

package/src/app-plugin.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AppPlugin } from './app-plugin';
+import { PluginContext } from '@objectstack/core';
+
+describe('AppPlugin', () => {
+    let mockContext: PluginContext;
+
+    beforeEach(() => {
+        mockContext = {
+            logger: { 
+                info: vi.fn(), 
+                error: vi.fn(),
+                warn: vi.fn(),
+                debug: vi.fn()
+            },
+            registerService: vi.fn(),
+            getService: vi.fn(),
+            getServices: vi.fn()
+        } as unknown as PluginContext;
+    });
+
+    it('should initialize with manifest info', () => {
+        const bundle = {
+            id: 'com.test.app',
+            name: 'Test App',
+            version: '1.0.0'
+        };
+        const plugin = new AppPlugin(bundle);
+        expect(plugin.name).toBe('plugin.app.com.test.app');
+        expect(plugin.version).toBe('1.0.0');
+    });
+
+    it('should handle nested stack definition manifest', () => {
+        const bundle = {
+            manifest: {
+                id: 'com.test.stack',
+                version: '2.0.0'
+            },
+            objects: []
+        };
+        const plugin = new AppPlugin(bundle);
+        expect(plugin.name).toBe('plugin.app.com.test.stack');
+        expect(plugin.version).toBe('2.0.0');
+    });
+
+    it('registerService should register raw manifest in init phase', async () => {
+        const bundle = {
+            id: 'com.test.simple',
+            objects: []
+        };
+        const plugin = new AppPlugin(bundle);
+        
+        await plugin.init(mockContext);
+        
+        expect(mockContext.registerService).toHaveBeenCalledWith('app.com.test.simple', bundle);
+    });
+
+    it('start should do nothing if no runtime hooks', async () => {
+        const bundle = { id: 'com.test.static' };
+        const plugin = new AppPlugin(bundle);
+        
+        vi.mocked(mockContext.getService).mockReturnValue({}); // Mock ObjectQL exists
+        
+        await plugin.start!(mockContext);
+        // Only logs, no errors
+        expect(mockContext.logger.debug).toHaveBeenCalled();
+    });
+
+    it('start should invoke onEnable if present', async () => {
+        const onEnableSpy = vi.fn();
+        const bundle = { 
+            id: 'com.test.code',
+            onEnable: onEnableSpy
+        };
+        const plugin = new AppPlugin(bundle);
+        
+        // Mock ObjectQL engine
+        const mockQL = { registry: {} };
+        vi.mocked(mockContext.getService).mockReturnValue(mockQL);
+        
+        await plugin.start!(mockContext);
+        
+        expect(onEnableSpy).toHaveBeenCalled();
+        // Check context passed to onEnable
+        const callArg = onEnableSpy.mock.calls[0][0];
+        expect(callArg.ql).toBe(mockQL);
+    });
+
+    it('start should warn if objectql not found', async () => {
+        const bundle = { id: 'com.test.warn' };
+        const plugin = new AppPlugin(bundle);
+        
+        vi.mocked(mockContext.getService).mockReturnValue(undefined); // No ObjectQL
+        
+        await plugin.start!(mockContext);
+        
+        expect(mockContext.logger.warn).toHaveBeenCalledWith(
+            expect.stringContaining('ObjectQL engine service not found'), 
+            expect.any(Object)
+        );
+    });
+});

package/src/app-plugin.ts

@@ -25,7 +25,7 @@ export class AppPlugin implements Plugin {
         this.version = sys.version;
     }
 
-    async init(ctx: PluginContext) {
+    init = async (ctx: PluginContext) => {
         const sys = this.bundle.manifest || this.bundle;
         const appId = sys.id || sys.name;
 
@@ -48,7 +48,7 @@ export class AppPlugin implements Plugin {
         ctx.registerService(serviceName, servicePayload);
     }
 
-    async start(ctx: PluginContext) {
+    start = async (ctx: PluginContext) => {
         const sys = this.bundle.manifest || this.bundle;
         const appId = sys.id || sys.name;
         

package/src/driver-plugin.ts

@@ -26,7 +26,7 @@ export class DriverPlugin implements Plugin {
         this.name = `com.objectstack.driver.${driverName || driver.name || 'unknown'}`;
     }
 
-    async init(ctx: PluginContext) {
+    init = async (ctx: PluginContext) => {
         // Register driver as a service instead of directly to objectql
         const serviceName = `driver.${this.driver.name || 'unknown'}`;
         ctx.registerService(serviceName, this.driver);
@@ -37,7 +37,7 @@ export class DriverPlugin implements Plugin {
         });
     }
 
-    async start(ctx: PluginContext) {
+    start = async (ctx: PluginContext) => {
         // Drivers don't need start phase, initialization happens in init
         ctx.logger.debug('Driver plugin started', { driverName: this.driver.name || 'unknown' });
     }

package/src/http-dispatcher.test.ts

@@ -0,0 +1,107 @@
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { HttpDispatcher } from './http-dispatcher.js';
+import { ObjectKernel } from '@objectstack/core';
+
+describe('HttpDispatcher', () => {
+    let kernel: ObjectKernel;
+    let dispatcher: HttpDispatcher;
+    let mockProtocol: any;
+    let mockBroker: any;
+
+    beforeEach(() => {
+        // Mock Kernel
+        mockProtocol = {
+            saveMetaItem: vi.fn().mockResolvedValue({ success: true, message: 'Saved' }),
+            getMetaItem: vi.fn().mockResolvedValue({ success: true, item: { foo: 'bar' } })
+        };
+        
+        mockBroker = {
+            call: vi.fn(),
+        };
+
+        kernel = {
+            broker: mockBroker,
+            context: {
+                getService: (name: string) => {
+                    if (name === 'protocol') return mockProtocol;
+                    return null;
+                }
+            }
+        } as any;
+
+        dispatcher = new HttpDispatcher(kernel);
+    });
+
+    describe('handleMetadata', () => {
+        it('should handle PUT /metadata/:type/:name by calling protocol.saveMetaItem', async () => {
+            const context = { request: {} };
+            const body = { label: 'New Label' };
+            const path = '/objects/my_obj';
+
+            const result = await dispatcher.handleMetadata(path, context, 'PUT', body);
+
+            expect(result.handled).toBe(true);
+            expect(result.response?.status).toBe(200);
+            expect(mockProtocol.saveMetaItem).toHaveBeenCalledWith({
+                type: 'objects',
+                name: 'my_obj',
+                item: body
+            });
+            expect(result.response?.body).toEqual({
+                success: true,
+                data: { success: true, message: 'Saved' },
+                meta: undefined
+            });
+        });
+
+        it('should fallback to broker call if protocol is missing saveMetaItem', async () => {
+             // Mock protocol without saveMetaItem
+            (kernel as any).context.getService = () => ({}); 
+            // Mock broker success
+            mockBroker.call.mockResolvedValue({ success: true, fromBroker: true });
+
+            const context = { request: {} };
+            const body = { label: 'Fallback' };
+            const path = '/objects/my_obj';
+
+            const result = await dispatcher.handleMetadata(path, context, 'PUT', body);
+
+            expect(result.handled).toBe(true);
+            expect(mockBroker.call).toHaveBeenCalledWith(
+                'metadata.saveItem',
+                { type: 'objects', name: 'my_obj', item: body },
+                { request: context.request }
+            );
+            expect(result.response?.body?.data).toEqual({ success: true, fromBroker: true });
+        });
+
+        it('should return error if save fails', async () => {
+            mockProtocol.saveMetaItem.mockRejectedValue(new Error('Save failed'));
+
+            const context = { request: {} };
+            const body = {};
+            const path = '/objects/bad_obj';
+
+            const result = await dispatcher.handleMetadata(path, context, 'PUT', body);
+
+            expect(result.handled).toBe(true);
+            expect(result.response?.status).toBe(400);
+            expect(result.response?.body?.error?.message).toBe('Save failed');
+        });
+        
+        it('should handle READ operations as before', async () => {
+             mockBroker.call.mockResolvedValue({ name: 'my_obj' });
+             
+             const context = { request: {} };
+             const result = await dispatcher.handleMetadata('/objects/my_obj', context, 'GET');
+             
+             expect(result.handled).toBe(true);
+             expect(mockBroker.call).toHaveBeenCalledWith(
+                 'metadata.getObject', 
+                 { objectName: 'my_obj' }, 
+                 { request: context.request }
+             );
+        });
+    });
+});