@objectstack/runtime 0.4.2 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @objectstack/runtime
 
+## 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
+
+- b2df5f7: Unified version bump to 0.5.0
+
+  - Standardized all package versions to 0.5.0 across the monorepo
+  - Fixed driver-memory package.json paths for proper module resolution
+  - Ensured all packages are in sync for the 0.5.0 release
+
+### Patch Changes
+
+- Updated dependencies [b2df5f7]
+  - @objectstack/spec@0.6.0
+  - @objectstack/objectql@0.6.0
+  - @objectstack/types@0.6.0
+  - @objectstack/core@0.6.0
+
 ## 0.4.2
 
 ### Patch Changes

package/README.md

@@ -1,10 +1,16 @@
 # @objectstack/runtime
 
-ObjectStack Core Runtime & Query Engine
+ObjectStack Standard System Library
 
 ## Overview
 
-The runtime package provides the `ObjectStackKernel` - the central orchestrator for ObjectStack applications. It manages the application lifecycle, plugins, and the ObjectQL data engine.
+The runtime package provides the **Standard Library** for the ObjectStack Operating System. It bridges the pure **ObjectKernel** (from `@objectstack/core`) with the **Data Engine** (`@objectstack/objectql`) and provides essential infrastructure adapters.
+
+### Architecture Highlights
+
+- **Standard Library**: Contains essential plugins (`AppPlugin`, `DriverPlugin`)
+- **Core Integration**: Re-exports `ObjectKernel` for convenience
+- **Capability Contracts**: Abstract interfaces for HTTP server and data persistence
 
 ## Installation
 
@@ -12,26 +18,29 @@ The runtime package provides the `ObjectStackKernel` - the central orchestrator
 npm install @objectstack/runtime
 ```
 
-## Usage
+## Quick Start
 
-### Basic Setup
+### Basic Setup (Recommended)
 
 ```typescript
-import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
+import { ObjectKernel } from '@objectstack/core';
+import { DriverPlugin, AppPlugin } from '@objectstack/runtime';
+import { ObjectQLPlugin } from '@objectstack/objectql';
 import { InMemoryDriver } from '@objectstack/driver-memory';
 
-const kernel = new ObjectStackKernel([
+const kernel = new ObjectKernel();
+
+kernel
   // Register ObjectQL engine
-  new ObjectQLPlugin(),
+  .use(new ObjectQLPlugin())
   
   // Add database driver
-  new InMemoryDriver(),
+  .use(new DriverPlugin(new InMemoryDriver(), 'memory'))
   
   // Add your app configurations
-  // appConfig,
-]);
+  // .use(new AppPlugin(appConfig));
 
-await kernel.start();
+await kernel.bootstrap();
 ```
 
 ### Custom ObjectQL Instance
@@ -39,7 +48,8 @@ await kernel.start();
 If you have a separate ObjectQL implementation or need custom configuration:
 
 ```typescript
-import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
+import { ObjectKernel, DriverPlugin } from '@objectstack/runtime';
+import { ObjectQLPlugin, ObjectQL } from '@objectstack/objectql';
 
 // Create custom ObjectQL instance
 const customQL = new ObjectQL({
@@ -52,111 +62,218 @@ customQL.registerHook('beforeInsert', async (ctx) => {
   console.log(`Inserting into ${ctx.object}`);
 });
 
-const kernel = new ObjectStackKernel([
+const kernel = new ObjectKernel();
+
+kernel
   // Use your custom ObjectQL instance
-  new ObjectQLPlugin(customQL),
+  .use(new ObjectQLPlugin(customQL))
   
-  // ... other plugins
-]);
+  // Add driver
+  .use(new DriverPlugin(new InMemoryDriver(), 'memory'));
+
+await kernel.bootstrap();
 
-await kernel.start();
+// Access ObjectQL via service registry
+const objectql = kernel.getService('objectql');
 ```
 
-### Backward Compatibility
+## Architecture
+
+### ObjectKernel (MiniKernel)
+
+The kernel provides:
+- **Plugin Lifecycle Management**: init → start → destroy phases
+- **Service Registry**: Dependency injection container
+- **Event/Hook System**: Inter-plugin communication
+- **Dependency Resolution**: Topological sort for plugin dependencies
+
+### Built-in Plugins
 
-For backward compatibility, the kernel will automatically initialize ObjectQL if no `ObjectQLPlugin` is provided:
+#### ObjectQLPlugin
+Registers the ObjectQL data engine as a service.
 
 ```typescript
-// This still works, but will show a deprecation warning
-const kernel = new ObjectStackKernel([
-  new InMemoryDriver(),
-  // ... other plugins
-]);
+new ObjectQLPlugin()                           // Default instance
+new ObjectQLPlugin(customQL)                   // Custom instance
+new ObjectQLPlugin(undefined, { env: 'prod' }) // With context
 ```
 
-## Architecture
+**Services**: `'objectql'`
 
-### ObjectStackKernel
+#### DriverPlugin
+Registers a data driver with ObjectQL.
 
-The kernel is responsible for:
-- Orchestrating application lifecycle
-- Managing plugins
-- Coordinating the ObjectQL engine
-- Handling data operations
+```typescript
+new DriverPlugin(driver, 'driver-name')
+```
 
-### ObjectQLPlugin
+**Dependencies**: `['com.objectstack.engine.objectql']`
 
-The `ObjectQLPlugin` provides:
-- Explicit ObjectQL engine registration
-- Support for custom ObjectQL instances
-- Clean separation of concerns
-- Better testability
+#### AppPlugin
+Wraps ObjectStack app manifests (objectstack.config.ts) as plugins.
+
+```typescript
+new AppPlugin(appConfig)
+```
+
+**Services**: `'app.{id}'`
 
 ## API Reference
 
-### ObjectStackKernel
+### Capability Contract Interfaces
+
+#### IHttpServer
+
+Abstract interface for HTTP server capabilities. Allows plugins to work with any HTTP framework (Express, Fastify, Hono, etc.) without tight coupling.
 
-#### Constructor
 ```typescript
-constructor(plugins: any[] = [])
+import { IHttpServer, IHttpRequest, IHttpResponse } from '@objectstack/runtime';
+
+// In your HTTP server plugin
+class MyHttpServerPlugin implements Plugin {
+  name = 'http-server';
+  
+  async init(ctx: PluginContext) {
+    const server: IHttpServer = createMyServer(); // Express, Hono, etc.
+    ctx.registerService('http-server', server);
+  }
+}
+
+// In your API plugin
+class MyApiPlugin implements Plugin {
+  name = 'api';
+  dependencies = ['http-server'];
+  
+  async start(ctx: PluginContext) {
+    const server = ctx.getService<IHttpServer>('http-server');
+    
+    // Register routes - works with any HTTP framework
+    server.get('/api/users', async (req, res) => {
+      res.json({ users: [] });
+    });
+  }
+}
 ```
 
+**Interface Methods:**
+- `get(path, handler)` - Register GET route
+- `post(path, handler)` - Register POST route  
+- `put(path, handler)` - Register PUT route
+- `delete(path, handler)` - Register DELETE route
+- `patch(path, handler)` - Register PATCH route
+- `use(path, handler?)` - Register middleware
+- `listen(port)` - Start server
+- `close()` - Stop server (optional)
+
+#### IDataEngine
+
+Abstract interface for data persistence. Allows plugins to work with any data layer (ObjectQL, Prisma, TypeORM, etc.) without tight coupling.
+
+```typescript
+import { IDataEngine } from '@objectstack/runtime';
+
+// In your data plugin
+class MyDataPlugin implements Plugin {
+  name = 'data';
+  
+  async init(ctx: PluginContext) {
+    const engine: IDataEngine = createMyDataEngine(); // ObjectQL, Prisma, etc.
+    ctx.registerService('data-engine', engine);
+  }
+}
+
+// In your business logic plugin
+class MyBusinessPlugin implements Plugin {
+  name = 'business';
+  dependencies = ['data'];
+  
+  async start(ctx: PluginContext) {
+    const engine = ctx.getService<IDataEngine>('data-engine');
+    
+    // CRUD operations - works with any data layer
+    const user = await engine.insert('user', { name: 'John' });
+    const users = await engine.find('user', { filter: { active: true } });
+    await engine.update('user', user.id, { name: 'Jane' });
+    await engine.delete('user', user.id);
+  }
+}
+```
+
+**Interface Methods:**
+- `insert(objectName, data)` - Create a record
+- `find(objectName, query?)` - Query records
+- `update(objectName, id, data)` - Update a record
+- `delete(objectName, id)` - Delete a record
+
+### ObjectKernel
+
 #### Methods
-- `start()`: Initialize and start the kernel
-- `find(objectName, query)`: Query data
-- `get(objectName, id)`: Get single record
-- `create(objectName, data)`: Create record
-- `update(objectName, id, data)`: Update record
-- `delete(objectName, id)`: Delete record
-- `getMetadata(objectName)`: Get object metadata
-- `getView(objectName, viewType)`: Get UI view definition
-
-### ObjectQLPlugin
-
-#### Constructor
+- `use(plugin: Plugin)`: Register a plugin
+- `bootstrap()`: Initialize and start all plugins
+- `shutdown()`: Stop all plugins in reverse order
+- `getService<T>(name: string)`: Get a service from registry
+- `isRunning()`: Check if kernel is running
+- `getState()`: Get current kernel state
+
+### Plugin Interface
+
 ```typescript
-constructor(ql?: ObjectQL, hostContext?: Record<string, any>)
+interface Plugin {
+  name: string;                              // Unique identifier
+  version?: string;                          // Plugin version
+  dependencies?: string[];                   // Required plugin names
+  
+  init(ctx: PluginContext): Promise<void>;   // Register services
+  start?(ctx: PluginContext): Promise<void>; // Execute business logic
+  destroy?(): Promise<void>;                  // Cleanup
+}
 ```
 
-#### Parameters
-- `ql` (optional): Custom ObjectQL instance
-- `hostContext` (optional): Host context configuration
+### PluginContext
+
+```typescript
+interface PluginContext {
+  registerService(name: string, service: any): void;
+  getService<T>(name: string): T;
+  hook(name: string, handler: Function): void;
+  trigger(name: string, ...args: any[]): Promise<void>;
+  logger: Console;
+  getKernel?(): any;
+}
+```
 
 ## Examples
 
 See the `examples/` directory for complete examples:
 - `examples/host/` - Full server setup with Hono
 - `examples/msw-react-crud/` - Browser-based setup with MSW
-- `examples/custom-objectql-example.ts` - Custom ObjectQL instance
+- `test-mini-kernel.ts` - Comprehensive kernel test suite
+- `packages/runtime/src/
 
-## Migration Guide
+## Benefits of MiniKernel
 
-### From Hardcoded ObjectQL to Plugin-Based
+1. **True Modularity**: Each plugin is independent and reusable
+2. **Capability Contracts**: Plugins depend on interfaces, not implementations
+3. **Testability**: Mock services easily in tests
+4. **Flexibility**: Load plugins conditionally, swap implementations
+5. **Extensibility**: Add new plugins without modifying kernel
+6. **Clear Dependencies**: Explicit dependency declarations
+7. **Better Architecture**: Separation of concerns with Dependency Inversion
 
-**Before:**
-```typescript
-const kernel = new ObjectStackKernel([appConfig, driver]);
-```
+## Best Practices
 
-**After (Recommended):**
-```typescript
-const kernel = new ObjectStackKernel([
-  new ObjectQLPlugin(),
-  appConfig, 
-  driver
-]);
-```
+1. **Keep plugins focused**: One responsibility per plugin
+2. **Use services**: Share functionality via service registry
+3. **Declare dependencies**: Make plugin requirements explicit
+4. **Use hooks**: Decouple plugins with event system
+5. **Handle errors**: Implement proper error handling in lifecycle methods
 
-**After (Custom Instance):**
-```typescript
-const customQL = new ObjectQL({ /* config */ });
-const kernel = new ObjectStackKernel([
-  new ObjectQLPlugin(customQL),
-  appConfig, 
-  driver
-]);
-```
+## Documentation
+
+- [MiniKernel Guide](../../MINI_KERNEL_GUIDE.md) - Complete API documentation and patterns
+- [MiniKernel Architecture](../../MINI_KERNEL_ARCHITECTURE.md) - Architecture diagrams and flows
+- [MiniKernel Implementation](../../MINI_KERNEL_IMPLEMENTATION.md) - Implementation details
 
 ## License
 
-MIT
+Apache-2.0

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,52 @@
+/**
+ * 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?.log(`[AppPlugin] Registering App Service: ${appId}`);
+        // Register the app manifest as a service
+        // ObjectQLPlugin will discover this and call ql.registerApp()
+        const serviceName = `app.${appId}`;
+        ctx.registerService(serviceName, this.bundle.manifest || this.bundle);
+    }
+    async start(ctx) {
+        // 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(`[AppPlugin] ObjectQL engine service not found for app: ${this.name}`);
+            return;
+        }
+        const runtime = this.bundle.default || this.bundle;
+        if (runtime && typeof runtime.onEnable === 'function') {
+            ctx.logger?.log(`[AppPlugin] Executing runtime.onEnable for: ${this.name}`);
+            // Construct the Host Context (mirroring old ObjectQL.use logic)
+            const hostContext = {
+                ...ctx,
+                ql,
+                logger: ctx.logger || console,
+                drivers: {
+                    register: (driver) => ql.registerDriver(driver)
+                },
+            };
+            await runtime.onEnable(hostContext);
+        }
+    }
+}

package/dist/driver-plugin.d.ts

@@ -0,0 +1,23 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+/**
+ * Driver Plugin
+ *
+ * Generic plugin wrapper for ObjectQL drivers.
+ * Registers a driver with the ObjectQL engine.
+ *
+ * Dependencies: None (Registers service for ObjectQL to discover)
+ * Services: driver.{name}
+ *
+ * @example
+ * const memoryDriver = new InMemoryDriver();
+ * const driverPlugin = new DriverPlugin(memoryDriver, 'memory');
+ * kernel.use(driverPlugin);
+ */
+export declare class DriverPlugin implements Plugin {
+    name: string;
+    version: string;
+    private driver;
+    constructor(driver: any, driverName?: string);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+}

package/dist/driver-plugin.js

@@ -0,0 +1,31 @@
+/**
+ * Driver Plugin
+ *
+ * Generic plugin wrapper for ObjectQL drivers.
+ * Registers a driver with the ObjectQL engine.
+ *
+ * Dependencies: None (Registers service for ObjectQL to discover)
+ * Services: driver.{name}
+ *
+ * @example
+ * const memoryDriver = new InMemoryDriver();
+ * const driverPlugin = new DriverPlugin(memoryDriver, 'memory');
+ * kernel.use(driverPlugin);
+ */
+export class DriverPlugin {
+    constructor(driver, driverName) {
+        this.version = '1.0.0';
+        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.log(`[DriverPlugin] Registered driver service: ${serviceName}`);
+    }
+    async start(ctx) {
+        // Drivers don't need start phase, initialization happens in init
+        ctx.logger.log(`[DriverPlugin] Driver ready: ${this.driver.name || 'unknown'}`);
+    }
+}

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
-export { ObjectStackKernel } from './kernel';
-export { ObjectQLPlugin } from './objectql-plugin';
-export { ObjectStackRuntimeProtocol } from './protocol';
-export * from './types';
+export { ObjectKernel } from '@objectstack/core';
+export { DriverPlugin } from './driver-plugin';
+export { AppPlugin } from './app-plugin';
+export * from '@objectstack/core';

package/dist/index.js

@@ -1,6 +1,7 @@
-// Export core engine
-export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
-export { ObjectStackKernel } from './kernel';
-export { ObjectQLPlugin } from './objectql-plugin';
-export { ObjectStackRuntimeProtocol } from './protocol';
-export * from './types';
+// Export Kernels
+export { ObjectKernel } from '@objectstack/core';
+// Export Plugins
+export { DriverPlugin } from './driver-plugin';
+export { AppPlugin } from './app-plugin';
+// Export Types
+export * from '@objectstack/core';

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@objectstack/runtime",
-  "version": "0.4.2",
+  "version": "0.6.1",
   "description": "ObjectStack Core Runtime & Query Engine",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/objectql": "0.4.2",
-    "@objectstack/types": "0.4.2",
-    "@objectstack/spec": "0.4.2"
+    "@objectstack/core": "0.6.1",
+    "@objectstack/types": "0.6.1",
+    "@objectstack/spec": "0.6.1"
   },
   "devDependencies": {
     "typescript": "^5.0.0"

package/src/app-plugin.ts

@@ -0,0 +1,69 @@
+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 class AppPlugin implements Plugin {
+    name: string;
+    version?: string;
+    
+    private bundle: any;
+
+    constructor(bundle: any) {
+        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: PluginContext) {
+        const sys = this.bundle.manifest || this.bundle;
+        const appId = sys.id || sys.name;
+
+        ctx.logger?.log(`[AppPlugin] Registering App Service: ${appId}`);
+        
+        // Register the app manifest as a service
+        // ObjectQLPlugin will discover this and call ql.registerApp()
+        const serviceName = `app.${appId}`;
+        ctx.registerService(serviceName, this.bundle.manifest || this.bundle);
+    }
+
+    async start(ctx: PluginContext) {
+        // Execute Runtime Step
+        // Retrieve ObjectQL engine from services
+        // We cast to any/ObjectQL because ctx.getService returns unknown
+        const ql = ctx.getService('objectql') as any;
+        
+        if (!ql) {
+            ctx.logger?.warn(`[AppPlugin] ObjectQL engine service not found for app: ${this.name}`);
+            return;
+        }
+
+        const runtime = this.bundle.default || this.bundle;
+        
+        if (runtime && typeof runtime.onEnable === 'function') {
+             ctx.logger?.log(`[AppPlugin] Executing runtime.onEnable for: ${this.name}`);
+             
+             // Construct the Host Context (mirroring old ObjectQL.use logic)
+             const hostContext = {
+                ...ctx,
+                ql,
+                logger: ctx.logger || console,
+                drivers: {
+                    register: (driver: any) => ql.registerDriver(driver)
+                },
+             };
+             
+             await runtime.onEnable(hostContext);
+        }
+    }
+}

package/src/driver-plugin.ts

@@ -0,0 +1,40 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Driver Plugin
+ * 
+ * Generic plugin wrapper for ObjectQL drivers.
+ * Registers a driver with the ObjectQL engine.
+ * 
+ * Dependencies: None (Registers service for ObjectQL to discover)
+ * Services: driver.{name}
+ * 
+ * @example
+ * const memoryDriver = new InMemoryDriver();
+ * const driverPlugin = new DriverPlugin(memoryDriver, 'memory');
+ * kernel.use(driverPlugin);
+ */
+export class DriverPlugin implements Plugin {
+    name: string;
+    version = '1.0.0';
+    // dependencies = ['com.objectstack.engine.objectql']; // Removed: Driver is a producer, not strictly a consumer during init
+
+    private driver: any;
+
+    constructor(driver: any, driverName?: string) {
+        this.driver = driver;
+        this.name = `com.objectstack.driver.${driverName || driver.name || 'unknown'}`;
+    }
+
+    async init(ctx: PluginContext) {
+        // 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}`);
+    }
+
+    async start(ctx: PluginContext) {
+        // Drivers don't need start phase, initialization happens in init
+        ctx.logger.log(`[DriverPlugin] Driver ready: ${this.driver.name || 'unknown'}`);
+    }
+}