@objectstack/runtime 0.4.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @objectstack/runtime
 
+## 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 (`AppManifestPlugin`, `DriverPlugin`)
+- **Core Integration**: Re-exports `ObjectKernel` for convenience
+- **Capability Contracts**: Abstract interfaces for HTTP server and data persistence
 
 ## Installation
 
@@ -12,26 +18,28 @@ 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 { ObjectQLPlugin, DriverPlugin, AppManifestPlugin } from '@objectstack/runtime';
 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 AppManifestPlugin(appConfig));
 
-await kernel.start();
+await kernel.bootstrap();
 ```
 
 ### Custom ObjectQL Instance
@@ -39,7 +47,7 @@ await kernel.start();
 If you have a separate ObjectQL implementation or need custom configuration:
 
 ```typescript
-import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
+import { ObjectKernel, ObjectQLPlugin, DriverPlugin, ObjectQL } from '@objectstack/runtime';
 
 // Create custom ObjectQL instance
 const customQL = new ObjectQL({
@@ -52,111 +60,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
+#### AppManifestPlugin
+Wraps ObjectStack app manifests (objectstack.config.ts) as plugins.
+
+```typescript
+new AppManifestPlugin(appConfig)
+```
+
+**Dependencies**: `['com.objectstack.engine.objectql']`
 
 ## 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/test-interfaces.ts` - Capability contract interface examples
 
-## 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-manifest-plugin.d.ts

@@ -0,0 +1,19 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+/**
+ * AppManifestPlugin
+ *
+ * Adapts a static Manifest JSON into a dynamic Kernel Service.
+ * This allows the ObjectQL Engine to "discover" this app during its start phase.
+ *
+ * Flow:
+ * 1. AppPlugin registers `app.<id>` service (init phase)
+ * 2. ObjectQL Engine discovers `app.*` services (start phase)
+ */
+export declare class AppManifestPlugin implements Plugin {
+    name: string;
+    version?: string;
+    private manifest;
+    constructor(manifest: any);
+    init(ctx: PluginContext): Promise<void>;
+    start(ctx: PluginContext): Promise<void>;
+}

package/dist/app-manifest-plugin.js

@@ -0,0 +1,33 @@
+/**
+ * AppManifestPlugin
+ *
+ * Adapts a static Manifest JSON into a dynamic Kernel Service.
+ * This allows the ObjectQL Engine to "discover" this app during its start phase.
+ *
+ * Flow:
+ * 1. AppPlugin registers `app.<id>` service (init phase)
+ * 2. ObjectQL Engine discovers `app.*` services (start phase)
+ */
+export class AppManifestPlugin {
+    constructor(manifest) {
+        this.manifest = manifest;
+        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
+        const sys = manifest.manifest || manifest;
+        const appId = sys.id || sys.name || 'unnamed-app';
+        this.name = `plugin.app.${appId}`; // Unique plugin name
+        this.version = sys.version;
+    }
+    async init(ctx) {
+        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
+        const sys = this.manifest.manifest || this.manifest;
+        const appId = sys.id || sys.name;
+        ctx.logger.log(`[AppManifestPlugin] Registering App Service: ${appId}`);
+        // Register the app manifest as a service
+        const serviceName = `app.${appId}`;
+        ctx.registerService(serviceName, this.manifest);
+    }
+    async start(ctx) {
+        // No logic needed here. 
+        // Logic is inverted: The Engine will pull data from this service.
+    }
+}

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,6 @@
-export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
-export { ObjectStackKernel } from './kernel';
-export { ObjectQLPlugin } from './objectql-plugin';
-export { ObjectStackRuntimeProtocol } from './protocol';
-export * from './types';
+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 * from '@objectstack/core';

package/dist/index.js

@@ -1,6 +1,10 @@
 // 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 { 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 Types
+export * from '@objectstack/core';

package/dist/test-interfaces.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Test file to verify capability contract interfaces
+ *
+ * This file demonstrates how plugins can implement the IHttpServer
+ * and IDataEngine interfaces without depending on concrete implementations.
+ */
+export {};

package/dist/test-interfaces.js

@@ -0,0 +1,138 @@
+/**
+ * Test file to verify capability contract interfaces
+ *
+ * This file demonstrates how plugins can implement the IHttpServer
+ * and IDataEngine interfaces without depending on concrete implementations.
+ */
+/**
+ * Example: Mock HTTP Server Plugin
+ *
+ * Shows how a plugin can implement the IHttpServer interface
+ * without depending on Express, Fastify, or any specific framework.
+ */
+class MockHttpServer {
+    constructor() {
+        this.routes = new Map();
+    }
+    get(path, handler) {
+        this.routes.set(`GET:${path}`, { method: 'GET', handler });
+        console.log(`✅ Registered GET ${path}`);
+    }
+    post(path, handler) {
+        this.routes.set(`POST:${path}`, { method: 'POST', handler });
+        console.log(`✅ Registered POST ${path}`);
+    }
+    put(path, handler) {
+        this.routes.set(`PUT:${path}`, { method: 'PUT', handler });
+        console.log(`✅ Registered PUT ${path}`);
+    }
+    delete(path, handler) {
+        this.routes.set(`DELETE:${path}`, { method: 'DELETE', handler });
+        console.log(`✅ Registered DELETE ${path}`);
+    }
+    patch(path, handler) {
+        this.routes.set(`PATCH:${path}`, { method: 'PATCH', handler });
+        console.log(`✅ Registered PATCH ${path}`);
+    }
+    use(path, handler) {
+        console.log(`✅ Registered middleware`);
+    }
+    async listen(port) {
+        console.log(`✅ Mock HTTP server listening on port ${port}`);
+    }
+    async close() {
+        console.log(`✅ Mock HTTP server closed`);
+    }
+}
+/**
+ * Example: Mock Data Engine Plugin
+ *
+ * Shows how a plugin can implement the IDataEngine interface
+ * without depending on ObjectQL, Prisma, or any specific database.
+ */
+class MockDataEngine {
+    constructor() {
+        this.store = new Map();
+        this.idCounter = 0;
+    }
+    async insert(objectName, data) {
+        if (!this.store.has(objectName)) {
+            this.store.set(objectName, new Map());
+        }
+        const id = `${objectName}_${++this.idCounter}`;
+        const record = { id, ...data };
+        this.store.get(objectName).set(id, record);
+        console.log(`✅ Inserted into ${objectName}:`, record);
+        return record;
+    }
+    async find(objectName, query) {
+        const objectStore = this.store.get(objectName);
+        if (!objectStore) {
+            return [];
+        }
+        const results = Array.from(objectStore.values());
+        console.log(`✅ Found ${results.length} records in ${objectName}`);
+        return results;
+    }
+    async update(objectName, id, data) {
+        const objectStore = this.store.get(objectName);
+        if (!objectStore || !objectStore.has(id)) {
+            throw new Error(`Record ${id} not found in ${objectName}`);
+        }
+        const existing = objectStore.get(id);
+        const updated = { ...existing, ...data };
+        objectStore.set(id, updated);
+        console.log(`✅ Updated ${objectName}/${id}:`, updated);
+        return updated;
+    }
+    async delete(objectName, id) {
+        const objectStore = this.store.get(objectName);
+        if (!objectStore) {
+            return false;
+        }
+        const deleted = objectStore.delete(id);
+        console.log(`✅ Deleted ${objectName}/${id}: ${deleted}`);
+        return deleted;
+    }
+}
+/**
+ * Test the interfaces
+ */
+async function testInterfaces() {
+    console.log('\n=== Testing IHttpServer Interface ===\n');
+    const httpServer = new MockHttpServer();
+    // Register routes using the interface
+    httpServer.get('/api/users', async (req, res) => {
+        res.json({ users: [] });
+    });
+    httpServer.post('/api/users', async (req, res) => {
+        res.status(201).json({ id: 1, ...req.body });
+    });
+    await httpServer.listen(3000);
+    console.log('\n=== Testing IDataEngine Interface ===\n');
+    const dataEngine = new MockDataEngine();
+    // Use the data engine interface
+    const user1 = await dataEngine.insert('user', {
+        name: 'John Doe',
+        email: 'john@example.com'
+    });
+    const user2 = await dataEngine.insert('user', {
+        name: 'Jane Smith',
+        email: 'jane@example.com'
+    });
+    const users = await dataEngine.find('user');
+    console.log(`Found ${users.length} users after inserts`);
+    const updatedUser = await dataEngine.update('user', user1.id, {
+        name: 'John Updated'
+    });
+    console.log(`Updated user:`, updatedUser);
+    const deleted = await dataEngine.delete('user', user2.id);
+    console.log(`Delete result: ${deleted}`);
+    console.log('\n✅ All interface tests passed!\n');
+    if (httpServer.close) {
+        await httpServer.close();
+    }
+}
+// Run tests
+testInterfaces().catch(console.error);
+export {};