@objectstack/runtime 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @objectstack/runtime
 
+## 0.7.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@0.7.1
+  - @objectstack/types@0.7.1
+  - @objectstack/core@0.7.1
+
+## 0.6.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@0.6.1
+  - @objectstack/types@0.6.1
+  - @objectstack/core@0.6.1
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -8,7 +8,7 @@ The runtime package provides the **Standard Library** for the ObjectStack Operat
 
 ### Architecture Highlights
 
-- **Standard Library**: Contains essential plugins (`AppManifestPlugin`, `DriverPlugin`)
+- **Standard Library**: Contains essential plugins (`AppPlugin`, `DriverPlugin`)
 - **Core Integration**: Re-exports `ObjectKernel` for convenience
 - **Capability Contracts**: Abstract interfaces for HTTP server and data persistence
 
@@ -24,7 +24,8 @@ npm install @objectstack/runtime
 
 ```typescript
 import { ObjectKernel } from '@objectstack/core';
-import { ObjectQLPlugin, DriverPlugin, AppManifestPlugin } from '@objectstack/runtime';
+import { DriverPlugin, AppPlugin } from '@objectstack/runtime';
+import { ObjectQLPlugin } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
 const kernel = new ObjectKernel();
@@ -37,7 +38,7 @@ kernel
   .use(new DriverPlugin(new InMemoryDriver(), 'memory'))
   
   // Add your app configurations
-  // .use(new AppManifestPlugin(appConfig));
+  // .use(new AppPlugin(appConfig));
 
 await kernel.bootstrap();
 ```
@@ -47,7 +48,8 @@ await kernel.bootstrap();
 If you have a separate ObjectQL implementation or need custom configuration:
 
 ```typescript
-import { ObjectKernel, ObjectQLPlugin, DriverPlugin, ObjectQL } from '@objectstack/runtime';
+import { ObjectKernel, DriverPlugin } from '@objectstack/runtime';
+import { ObjectQLPlugin, ObjectQL } from '@objectstack/objectql';
 
 // Create custom ObjectQL instance
 const customQL = new ObjectQL({
@@ -107,14 +109,14 @@ new DriverPlugin(driver, 'driver-name')
 
 **Dependencies**: `['com.objectstack.engine.objectql']`
 
-#### AppManifestPlugin
+#### AppPlugin
 Wraps ObjectStack app manifests (objectstack.config.ts) as plugins.
 
 ```typescript
-new AppManifestPlugin(appConfig)
+new AppPlugin(appConfig)
 ```
 
-**Dependencies**: `['com.objectstack.engine.objectql']`
+**Services**: `'app.{id}'`
 
 ## API Reference
 
@@ -246,7 +248,7 @@ See the `examples/` directory for complete examples:
 - `examples/host/` - Full server setup with Hono
 - `examples/msw-react-crud/` - Browser-based setup with MSW
 - `test-mini-kernel.ts` - Comprehensive kernel test suite
-- `packages/runtime/src/test-interfaces.ts` - Capability contract interface examples
+- `packages/runtime/src/
 
 ## Benefits of MiniKernel
 

package/dist/app-plugin.d.ts

@@ -0,0 +1,18 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+/**
+ * AppPlugin
+ *
+ * Adapts a generic App Bundle (Manifest + Runtime Code) into a Kernel Plugin.
+ *
+ * Responsibilities:
+ * 1. Register App Manifest as a service (for ObjectQL discovery)
+ * 2. Execute Runtime `onEnable` hook (for code logic)
+ */
+export declare class AppPlugin implements Plugin {
+    name: string;
+    version?: string;
+    private bundle;
+    constructor(bundle: any);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+}

package/dist/app-plugin.js

@@ -0,0 +1,80 @@
+/**
+ * AppPlugin
+ *
+ * Adapts a generic App Bundle (Manifest + Runtime Code) into a Kernel Plugin.
+ *
+ * Responsibilities:
+ * 1. Register App Manifest as a service (for ObjectQL discovery)
+ * 2. Execute Runtime `onEnable` hook (for code logic)
+ */
+export class AppPlugin {
+    constructor(bundle) {
+        this.bundle = bundle;
+        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
+        const sys = bundle.manifest || bundle;
+        const appId = sys.id || sys.name || 'unnamed-app';
+        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/driver-plugin.js

@@ -22,10 +22,14 @@ export class DriverPlugin {
         // Register driver as a service instead of directly to objectql
         const serviceName = `driver.${this.driver.name || 'unknown'}`;
         ctx.registerService(serviceName, this.driver);
-        ctx.logger.log(`[DriverPlugin] Registered driver service: ${serviceName}`);
+        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.log(`[DriverPlugin] Driver ready: ${this.driver.name || 'unknown'}`);
+        ctx.logger.debug('Driver plugin started', { driverName: this.driver.name || 'unknown' });
     }
 }

package/dist/http-server.d.ts

@@ -0,0 +1,84 @@
+import { IHttpServer, RouteHandler, Middleware } from '@objectstack/core';
+/**
+ * HttpServer - Unified HTTP Server Abstraction
+ *
+ * Provides a framework-agnostic HTTP server interface that wraps
+ * underlying server implementations (Hono, Express, Fastify, etc.)
+ *
+ * This class serves as an adapter between the IHttpServer interface
+ * and concrete server implementations, allowing plugins to register
+ * routes and middleware without depending on specific frameworks.
+ *
+ * Features:
+ * - Unified route registration API
+ * - Middleware management with ordering
+ * - Request/response lifecycle hooks
+ * - Framework-agnostic abstractions
+ */
+export declare class HttpServer implements IHttpServer {
+    protected server: IHttpServer;
+    protected routes: Map<string, RouteHandler>;
+    protected middlewares: Middleware[];
+    /**
+     * Create an HTTP server wrapper
+     * @param server - The underlying server implementation (Hono, Express, etc.)
+     */
+    constructor(server: IHttpServer);
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path: string, handler: RouteHandler): void;
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path: string, handler: RouteHandler): void;
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path: string, handler: RouteHandler): void;
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path: string, handler: RouteHandler): void;
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path: string, handler: RouteHandler): void;
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path: string | Middleware, handler?: Middleware): void;
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    listen(port: number): Promise<void>;
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    close(): Promise<void>;
+    /**
+     * Get registered routes
+     * @returns Map of route keys to handlers
+     */
+    getRoutes(): Map<string, RouteHandler>;
+    /**
+     * Get registered middlewares
+     * @returns Array of middleware functions
+     */
+    getMiddlewares(): Middleware[];
+}

package/dist/http-server.js

@@ -0,0 +1,125 @@
+/**
+ * HttpServer - Unified HTTP Server Abstraction
+ *
+ * Provides a framework-agnostic HTTP server interface that wraps
+ * underlying server implementations (Hono, Express, Fastify, etc.)
+ *
+ * This class serves as an adapter between the IHttpServer interface
+ * and concrete server implementations, allowing plugins to register
+ * routes and middleware without depending on specific frameworks.
+ *
+ * Features:
+ * - Unified route registration API
+ * - Middleware management with ordering
+ * - Request/response lifecycle hooks
+ * - Framework-agnostic abstractions
+ */
+export class HttpServer {
+    /**
+     * Create an HTTP server wrapper
+     * @param server - The underlying server implementation (Hono, Express, etc.)
+     */
+    constructor(server) {
+        this.server = server;
+        this.routes = new Map();
+        this.middlewares = [];
+    }
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path, handler) {
+        const key = `GET:${path}`;
+        this.routes.set(key, handler);
+        this.server.get(path, handler);
+    }
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path, handler) {
+        const key = `POST:${path}`;
+        this.routes.set(key, handler);
+        this.server.post(path, handler);
+    }
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path, handler) {
+        const key = `PUT:${path}`;
+        this.routes.set(key, handler);
+        this.server.put(path, handler);
+    }
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path, handler) {
+        const key = `DELETE:${path}`;
+        this.routes.set(key, handler);
+        this.server.delete(path, handler);
+    }
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path, handler) {
+        const key = `PATCH:${path}`;
+        this.routes.set(key, handler);
+        this.server.patch(path, handler);
+    }
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path, handler) {
+        if (typeof path === 'function') {
+            // Global middleware
+            this.middlewares.push(path);
+            this.server.use(path);
+        }
+        else if (handler) {
+            // Path-specific middleware
+            this.middlewares.push(handler);
+            this.server.use(path, handler);
+        }
+    }
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    async listen(port) {
+        await this.server.listen(port);
+    }
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    async close() {
+        if (this.server.close) {
+            await this.server.close();
+        }
+    }
+    /**
+     * Get registered routes
+     * @returns Map of route keys to handlers
+     */
+    getRoutes() {
+        return new Map(this.routes);
+    }
+    /**
+     * Get registered middlewares
+     * @returns Array of middleware functions
+     */
+    getMiddlewares() {
+        return [...this.middlewares];
+    }
+}

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-export { ObjectQL, SchemaRegistry, ObjectStackProtocolImplementation } from '@objectstack/objectql';
 export { ObjectKernel } from '@objectstack/core';
-export { ObjectQLPlugin } from '@objectstack/objectql';
-export { DriverPlugin } from './driver-plugin';
-export { AppManifestPlugin } from './app-manifest-plugin';
+export { DriverPlugin } from './driver-plugin.js';
+export { AppPlugin } from './app-plugin.js';
+export { HttpServer } from './http-server.js';
+export { RestServer } from './rest-server.js';
+export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export { MiddlewareManager } from './middleware.js';
 export * from '@objectstack/core';

package/dist/index.js

@@ -1,10 +1,12 @@
-// Export core engine
-export { ObjectQL, SchemaRegistry, ObjectStackProtocolImplementation } from '@objectstack/objectql';
 // Export Kernels
 export { ObjectKernel } from '@objectstack/core';
 // Export Plugins
-export { ObjectQLPlugin } from '@objectstack/objectql';
-export { DriverPlugin } from './driver-plugin';
-export { AppManifestPlugin } from './app-manifest-plugin';
+export { DriverPlugin } from './driver-plugin.js';
+export { AppPlugin } from './app-plugin.js';
+// Export HTTP Server Components
+export { HttpServer } from './http-server.js';
+export { RestServer } from './rest-server.js';
+export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export { MiddlewareManager } from './middleware.js';
 // Export Types
 export * from '@objectstack/core';

package/dist/middleware.d.ts

@@ -0,0 +1,111 @@
+import { Middleware } from '@objectstack/core';
+import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
+/**
+ * Middleware Entry
+ * Internal representation of registered middleware
+ */
+interface MiddlewareEntry {
+    name: string;
+    type: MiddlewareType;
+    middleware: Middleware;
+    order: number;
+    enabled: boolean;
+    paths?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+/**
+ * MiddlewareManager
+ *
+ * Manages middleware registration, ordering, and execution.
+ * Provides fine-grained control over middleware chains with:
+ * - Execution order management
+ * - Path-based filtering
+ * - Enable/disable individual middleware
+ * - Middleware categorization by type
+ *
+ * @example
+ * const manager = new MiddlewareManager();
+ *
+ * // Register middleware with configuration
+ * manager.register({
+ *   name: 'auth',
+ *   type: 'authentication',
+ *   order: 10,
+ *   paths: { exclude: ['/health', '/metrics'] }
+ * }, authMiddleware);
+ *
+ * // Get sorted middleware chain
+ * const chain = manager.getMiddlewareChain();
+ * chain.forEach(mw => server.use(mw));
+ */
+export declare class MiddlewareManager {
+    private middlewares;
+    constructor();
+    /**
+     * Register middleware with configuration
+     * @param config - Middleware configuration
+     * @param middleware - Middleware function
+     */
+    register(config: MiddlewareConfig, middleware: Middleware): void;
+    /**
+     * Unregister middleware by name
+     * @param name - Middleware name
+     */
+    unregister(name: string): void;
+    /**
+     * Enable middleware by name
+     * @param name - Middleware name
+     */
+    enable(name: string): void;
+    /**
+     * Disable middleware by name
+     * @param name - Middleware name
+     */
+    disable(name: string): void;
+    /**
+     * Get middleware entry by name
+     * @param name - Middleware name
+     */
+    get(name: string): MiddlewareEntry | undefined;
+    /**
+     * Get all middleware entries
+     */
+    getAll(): MiddlewareEntry[];
+    /**
+     * Get middleware by type
+     * @param type - Middleware type
+     */
+    getByType(type: MiddlewareType): MiddlewareEntry[];
+    /**
+     * Get middleware chain sorted by order
+     * Returns only enabled middleware
+     */
+    getMiddlewareChain(): Middleware[];
+    /**
+     * Get middleware chain with path filtering
+     * @param path - Request path to match against
+     */
+    getMiddlewareChainForPath(path: string): Middleware[];
+    /**
+     * Match path against pattern (simple glob matching)
+     * @param path - Request path
+     * @param pattern - Pattern to match (supports * wildcard)
+     */
+    private matchPath;
+    /**
+     * Clear all middleware
+     */
+    clear(): void;
+    /**
+     * Get middleware count
+     */
+    count(): number;
+    /**
+     * Create a composite middleware from the chain
+     * This can be used to apply all middleware at once
+     */
+    createCompositeMiddleware(): Middleware;
+}
+export {};