@objectstack/runtime 0.9.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @objectstack/runtime
 
+## 1.0.0
+
+### Major Changes
+
+- Major version release for ObjectStack Protocol v1.0.
+  - Stabilized Protocol Definitions
+  - Enhanced Runtime Plugin Support
+  - Fixed Type Compliance across Monorepo
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@1.0.0
+  - @objectstack/core@1.0.0
+  - @objectstack/types@1.0.0
+
 ## 0.9.2
 
 ### Patch Changes

package/dist/api-registry-plugin.d.ts

@@ -0,0 +1,16 @@
+import { Plugin } from '@objectstack/core';
+import { 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 declare function createApiRegistryPlugin(config?: ApiRegistryConfig): Plugin;

package/dist/api-registry-plugin.js

@@ -0,0 +1,42 @@
+import { RestServer } from './rest-server.js';
+/**
+ * ApiRegistryPlugin
+ *
+ * Responsibilities:
+ * 1. Consumes 'http.server' (or configured service)
+ * 2. Consumes 'protocol' (ObjectStackProtocol)
+ * 3. Instantiates RestServer to auto-generate routes
+ */
+export function createApiRegistryPlugin(config = {}) {
+    return {
+        name: 'com.objectstack.runtime.api-registry',
+        version: '1.0.0',
+        init: async (ctx) => {
+            // No service registration, this is a consumer plugin
+        },
+        start: async (ctx) => {
+            const serverService = config.serverServiceName || 'http.server';
+            const protocolService = config.protocolServiceName || 'protocol';
+            const server = ctx.getService(serverService);
+            const protocol = ctx.getService(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) {
+                ctx.logger.error('Failed to register REST API routes', { error: err.message });
+                throw err;
+            }
+        }
+    };
+}

package/dist/app-plugin.d.ts

@@ -13,6 +13,6 @@ export declare class AppPlugin implements Plugin {
     version?: string;
     private bundle;
     constructor(bundle: any);
-    init(ctx: PluginContext): Promise<void>;
-    start(ctx: PluginContext): Promise<void>;
+    init: (ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
 }

package/dist/app-plugin.js

@@ -9,6 +9,67 @@
  */
 export class AppPlugin {
     constructor(bundle) {
+        this.init = async (ctx) => {
+            const sys = this.bundle.manifest || this.bundle;
+            const appId = sys.id || sys.name;
+            ctx.logger.info('Registering App Service', {
+                appId,
+                pluginName: this.name,
+                version: this.version
+            });
+            // Register the app manifest as a service
+            // ObjectQLPlugin will discover this and call ql.registerApp()
+            const serviceName = `app.${appId}`;
+            // Merge manifest with the bundle to ensure objects/apps are accessible at root
+            // This supports both Legacy Manifests and new Stack Definitions
+            const servicePayload = this.bundle.manifest
+                ? { ...this.bundle.manifest, ...this.bundle }
+                : this.bundle;
+            ctx.registerService(serviceName, servicePayload);
+        };
+        this.start = async (ctx) => {
+            const sys = this.bundle.manifest || this.bundle;
+            const appId = sys.id || sys.name;
+            // Execute Runtime Step
+            // Retrieve ObjectQL engine from services
+            // We cast to any/ObjectQL because ctx.getService returns unknown
+            const ql = ctx.getService('objectql');
+            if (!ql) {
+                ctx.logger.warn('ObjectQL engine service not found', {
+                    appName: this.name,
+                    appId
+                });
+                return;
+            }
+            ctx.logger.debug('Retrieved ObjectQL engine service', { appId });
+            const runtime = this.bundle.default || this.bundle;
+            if (runtime && typeof runtime.onEnable === 'function') {
+                ctx.logger.info('Executing runtime.onEnable', {
+                    appName: this.name,
+                    appId
+                });
+                // Construct the Host Context (mirroring old ObjectQL.use logic)
+                const hostContext = {
+                    ...ctx,
+                    ql,
+                    logger: ctx.logger,
+                    drivers: {
+                        register: (driver) => {
+                            ctx.logger.debug('Registering driver via app runtime', {
+                                driverName: driver.name,
+                                appId
+                            });
+                            ql.registerDriver(driver);
+                        }
+                    },
+                };
+                await runtime.onEnable(hostContext);
+                ctx.logger.debug('Runtime.onEnable completed', { appId });
+            }
+            else {
+                ctx.logger.debug('No runtime.onEnable function found', { appId });
+            }
+        };
         this.bundle = bundle;
         // Support both direct manifest (legacy) and Stack Definition (nested manifest)
         const sys = bundle.manifest || bundle;
@@ -16,65 +77,4 @@ export class AppPlugin {
         this.name = `plugin.app.${appId}`;
         this.version = sys.version;
     }
-    async init(ctx) {
-        const sys = this.bundle.manifest || this.bundle;
-        const appId = sys.id || sys.name;
-        ctx.logger.info('Registering App Service', {
-            appId,
-            pluginName: this.name,
-            version: this.version
-        });
-        // Register the app manifest as a service
-        // ObjectQLPlugin will discover this and call ql.registerApp()
-        const serviceName = `app.${appId}`;
-        // Merge manifest with the bundle to ensure objects/apps are accessible at root
-        // This supports both Legacy Manifests and new Stack Definitions
-        const servicePayload = this.bundle.manifest
-            ? { ...this.bundle.manifest, ...this.bundle }
-            : this.bundle;
-        ctx.registerService(serviceName, servicePayload);
-    }
-    async start(ctx) {
-        const sys = this.bundle.manifest || this.bundle;
-        const appId = sys.id || sys.name;
-        // Execute Runtime Step
-        // Retrieve ObjectQL engine from services
-        // We cast to any/ObjectQL because ctx.getService returns unknown
-        const ql = ctx.getService('objectql');
-        if (!ql) {
-            ctx.logger.warn('ObjectQL engine service not found', {
-                appName: this.name,
-                appId
-            });
-            return;
-        }
-        ctx.logger.debug('Retrieved ObjectQL engine service', { appId });
-        const runtime = this.bundle.default || this.bundle;
-        if (runtime && typeof runtime.onEnable === 'function') {
-            ctx.logger.info('Executing runtime.onEnable', {
-                appName: this.name,
-                appId
-            });
-            // Construct the Host Context (mirroring old ObjectQL.use logic)
-            const hostContext = {
-                ...ctx,
-                ql,
-                logger: ctx.logger,
-                drivers: {
-                    register: (driver) => {
-                        ctx.logger.debug('Registering driver via app runtime', {
-                            driverName: driver.name,
-                            appId
-                        });
-                        ql.registerDriver(driver);
-                    }
-                },
-            };
-            await runtime.onEnable(hostContext);
-            ctx.logger.debug('Runtime.onEnable completed', { appId });
-        }
-        else {
-            ctx.logger.debug('No runtime.onEnable function found', { appId });
-        }
-    }
 }

package/dist/app-plugin.test.d.ts

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

package/dist/app-plugin.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { AppPlugin } from './app-plugin';
+describe('AppPlugin', () => {
+    let mockContext;
+    beforeEach(() => {
+        mockContext = {
+            logger: {
+                info: vi.fn(),
+                error: vi.fn(),
+                warn: vi.fn(),
+                debug: vi.fn()
+            },
+            registerService: vi.fn(),
+            getService: vi.fn(),
+            getServices: vi.fn()
+        };
+    });
+    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/dist/driver-plugin.d.ts

@@ -18,6 +18,6 @@ export declare class DriverPlugin implements Plugin {
     version: string;
     private driver;
     constructor(driver: any, driverName?: string);
-    init(ctx: PluginContext): Promise<void>;
-    start(ctx: PluginContext): Promise<void>;
+    init: (ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
 }

package/dist/driver-plugin.js

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

package/dist/http-dispatcher.d.ts

@@ -0,0 +1,106 @@
+import { ObjectKernel } from '@objectstack/core';
+export interface HttpProtocolContext {
+    request: any;
+    response?: any;
+}
+export interface HttpDispatcherResult {
+    handled: boolean;
+    response?: {
+        status: number;
+        body?: any;
+        headers?: Record<string, string>;
+    };
+    result?: any;
+}
+export declare class HttpDispatcher {
+    private kernel;
+    constructor(kernel: ObjectKernel);
+    private success;
+    private error;
+    private ensureBroker;
+    /**
+     * Generates the discovery JSON response for the API root
+     */
+    getDiscoveryInfo(prefix: string): {
+        name: string;
+        version: string;
+        environment: string;
+        routes: {
+            data: string;
+            metadata: string;
+            auth: string;
+            graphql: string | undefined;
+            storage: string | undefined;
+            analytics: string | undefined;
+            hub: string | undefined;
+        };
+        features: {
+            graphql: boolean;
+            search: boolean;
+            websockets: boolean;
+            files: boolean;
+            analytics: boolean;
+            hub: boolean;
+        };
+        locale: {
+            default: string;
+            supported: string[];
+            timezone: string;
+        };
+    };
+    /**
+     * Handles GraphQL requests
+     */
+    handleGraphQL(body: {
+        query: string;
+        variables?: any;
+    }, context: HttpProtocolContext): Promise<any>;
+    /**
+     * Handles Auth requests
+     * path: sub-path after /auth/
+     */
+    handleAuth(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Metadata requests
+     * Standard: /metadata/:type/:name
+     * Fallback for backward compat: /metadata (all objects), /metadata/:objectName (get object)
+     */
+    handleMetadata(path: string, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Data requests
+     * path: sub-path after /data/ (e.g. "contacts", "contacts/123", "contacts/query")
+     */
+    handleData(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Analytics requests
+     * path: sub-path after /analytics/
+     */
+    handleAnalytics(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Hub requests
+     * path: sub-path after /hub/
+     */
+    handleHub(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Storage requests
+     * path: sub-path after /storage/
+     */
+    handleStorage(path: string, method: string, file: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Automation requests
+     * path: sub-path after /automation/
+     */
+    handleAutomation(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    private getServicesMap;
+    private getService;
+    private capitalize;
+    /**
+     * Main Dispatcher Entry Point
+     * Routes the request to the appropriate handler based on path and precedence
+     */
+    dispatch(method: string, path: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Custom API Endpoints defined in metadata
+     */
+    handleApiEndpoint(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+}