@objectstack/runtime 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @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
+
+- Unify all package versions to 0.4.2
+- Updated dependencies
+  - @objectstack/spec@0.4.2
+  - @objectstack/objectql@0.4.2
+  - @objectstack/types@0.4.2
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,277 @@
+# @objectstack/runtime
+
+ObjectStack Standard System Library
+
+## Overview
+
+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
+
+```bash
+npm install @objectstack/runtime
+```
+
+## Quick Start
+
+### Basic Setup (Recommended)
+
+```typescript
+import { ObjectKernel } from '@objectstack/core';
+import { ObjectQLPlugin, DriverPlugin, AppManifestPlugin } from '@objectstack/runtime';
+import { InMemoryDriver } from '@objectstack/driver-memory';
+
+const kernel = new ObjectKernel();
+
+kernel
+  // Register ObjectQL engine
+  .use(new ObjectQLPlugin())
+  
+  // Add database driver
+  .use(new DriverPlugin(new InMemoryDriver(), 'memory'))
+  
+  // Add your app configurations
+  // .use(new AppManifestPlugin(appConfig));
+
+await kernel.bootstrap();
+```
+
+### Custom ObjectQL Instance
+
+If you have a separate ObjectQL implementation or need custom configuration:
+
+```typescript
+import { ObjectKernel, ObjectQLPlugin, DriverPlugin, ObjectQL } from '@objectstack/runtime';
+
+// Create custom ObjectQL instance
+const customQL = new ObjectQL({
+  env: 'production',
+  customConfig: true
+});
+
+// Pre-configure with custom hooks
+customQL.registerHook('beforeInsert', async (ctx) => {
+  console.log(`Inserting into ${ctx.object}`);
+});
+
+const kernel = new ObjectKernel();
+
+kernel
+  // Use your custom ObjectQL instance
+  .use(new ObjectQLPlugin(customQL))
+  
+  // Add driver
+  .use(new DriverPlugin(new InMemoryDriver(), 'memory'));
+
+await kernel.bootstrap();
+
+// Access ObjectQL via service registry
+const objectql = kernel.getService('objectql');
+```
+
+## 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
+
+#### ObjectQLPlugin
+Registers the ObjectQL data engine as a service.
+
+```typescript
+new ObjectQLPlugin()                           // Default instance
+new ObjectQLPlugin(customQL)                   // Custom instance
+new ObjectQLPlugin(undefined, { env: 'prod' }) // With context
+```
+
+**Services**: `'objectql'`
+
+#### DriverPlugin
+Registers a data driver with ObjectQL.
+
+```typescript
+new DriverPlugin(driver, 'driver-name')
+```
+
+**Dependencies**: `['com.objectstack.engine.objectql']`
+
+#### AppManifestPlugin
+Wraps ObjectStack app manifests (objectstack.config.ts) as plugins.
+
+```typescript
+new AppManifestPlugin(appConfig)
+```
+
+**Dependencies**: `['com.objectstack.engine.objectql']`
+
+## API Reference
+
+### 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.
+
+```typescript
+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
+- `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
+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
+}
+```
+
+### 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
+- `test-mini-kernel.ts` - Comprehensive kernel test suite
+- `packages/runtime/src/test-interfaces.ts` - Capability contract interface examples
+
+## Benefits of MiniKernel
+
+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
+
+## Best Practices
+
+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
+
+## 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
+
+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,4 +1,6 @@
-export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
-export { ObjectStackKernel } from './kernel';
-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,5 +1,10 @@
 // Export core engine
-export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
-export { ObjectStackKernel } from './kernel';
-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 {};

package/package.json

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

package/src/app-manifest-plugin.ts

@@ -0,0 +1,48 @@
+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 class AppManifestPlugin implements Plugin {
+    name: string;
+    version?: string;
+    
+    // Dependencies removed: This plugin produces data. It doesn't need to consume the engine to register itself.
+    // Making it dependency-free allows it to initialize BEFORE the engine if needed.
+    
+    private manifest: any;
+
+    constructor(manifest: any) {
+        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: PluginContext) {
+        // 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: PluginContext) {
+        // No logic needed here. 
+        // Logic is inverted: The Engine will pull data from this service.
+    }
+}