Merge pull request #155 from objectstack-ai/copilot/refactor-core-engine-plugin-structure

Author: huangyiirene

packages/foundation/core/README.md

@@ -1,22 +1,35 @@
 # @objectql/core
 
-The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**.
+The core ORM and runtime engine for ObjectQL. This package handles object querying, CRUD operations, database driver coordination, transaction management, and **metadata-driven validation**. As of version 4.0.0, it wraps the **ObjectStackKernel** for plugin architecture and lifecycle management.
 
 ## Features
 
-- **Unified Query Language**: A generic way to query data across different databases (SQL, Mongo, etc.).
-- **Repository Pattern**: `ObjectRepository` for managing object records.
-- **Driver Agnostic**: Abstraction layer for database drivers.
-- **Dynamic Schema**: Loads object definitions from metadata.
-- **Hooks & Actions**: Runtime logic injection.
-- **Validation Engine**: Metadata-driven validation with field-level, cross-field, and state machine rules.
+- **Plugin Architecture**: Built on top of `@objectstack/runtime` with kernel-based plugin system
+- **Unified Query Language**: A generic way to query data across different databases (SQL, Mongo, etc.)
+- **Repository Pattern**: `ObjectRepository` for managing object records
+- **Driver Agnostic**: Abstraction layer for database drivers
+- **Dynamic Schema**: Loads object definitions from metadata
+- **Hooks & Actions**: Runtime logic injection
+- **Validation Engine**: Metadata-driven validation with field-level, cross-field, and state machine rules
+- **Formula Engine**: Computed fields with dynamic formulas
+- **AI Integration**: Built-in AI agent capabilities
 
 ## Installation
 
 ```bash
-npm install @objectql/core @objectql/types
+npm install @objectql/core @objectql/types @objectstack/runtime @objectstack/spec
 ```
 
+## Architecture
+
+ObjectQL now wraps the `ObjectStackKernel` from `@objectstack/runtime`, providing:
+
+- **Kernel-based lifecycle management**: Initialization, startup, and shutdown
+- **Plugin system**: Extensible architecture with `ObjectQLPlugin`
+- **Enhanced features**: Repository, Validator, Formula, and AI capabilities as plugins
+
+See [RUNTIME_INTEGRATION.md](./RUNTIME_INTEGRATION.md) for detailed architecture documentation.
+
 ## Usage
 
 ### Basic Setup
@@ -31,7 +44,7 @@ const objectql = new ObjectQL({
     }
 });
 
-await objectql.init();
+await objectql.init(); // Initializes the kernel and all plugins
 
 // Use context for operations
 const ctx = objectql.createContext({ userId: 'u-1' });
@@ -40,6 +53,15 @@ const projects = await ctx.object('project').find({
 });
 ```
 
+### Accessing the Kernel
+
+For advanced use cases, you can access the underlying kernel:
+
+```typescript
+const kernel = objectql.getKernel();
+// Use kernel methods if needed
+```
+
 ### Validation System
 
 The validation system allows you to define validation rules in your object metadata and execute them programmatically.

packages/foundation/core/RUNTIME_INTEGRATION.md

@@ -4,39 +4,63 @@ This document explains the integration of `@objectstack/runtime` and `@objectsta
 
 ## Overview
 
-As of version 3.0.1, ObjectQL core natively uses the ObjectStack runtime packages:
+As of version 4.0.0, ObjectQL core uses the ObjectStack runtime packages with plugin architecture:
 
-- **@objectstack/spec@0.1.2**: Protocol specification with standard `DriverInterface`
-- **@objectstack/objectql@0.1.1**: Core ObjectQL engine with driver management
-- **@objectstack/runtime@0.1.1**: Runtime kernel with application lifecycle orchestration
+- **@objectstack/spec@0.2.0**: Protocol specification with standard `DriverInterface`
+- **@objectstack/objectql@0.2.0**: Core ObjectQL engine with driver management
+- **@objectstack/runtime@0.2.0**: Runtime kernel with application lifecycle orchestration and plugin system
 
 ## Architecture
 
 ### Package Relationship
 
 ```
 @objectql/core (this package)
+├── Wraps ObjectStackKernel from @objectstack/runtime
+├── Implements ObjectQLPlugin for enhanced features
 ├── Uses @objectstack/objectql for driver management
 ├── Natively uses @objectstack/spec.DriverInterface (no wrapper)
 └── Re-exports types from @objectstack/runtime
 ```
 
-### Driver Management Integration
+### Plugin Architecture (v4.0.0)
 
-**Breaking Change (v3.0.1):** The core package now **natively uses** `DriverInterface` from `@objectstack/spec`:
+**Breaking Change (v4.0.0):** The core package now **wraps `ObjectStackKernel`** and uses a plugin architecture:
 
 ```typescript
-import { ObjectQL } from '@objectql/core';
+import { ObjectQL, ObjectQLPlugin } from '@objectql/core';
 import type { DriverInterface } from '@objectstack/spec';
 
-// Drivers must implement DriverInterface from @objectstack/spec
+// ObjectQL now wraps ObjectStackKernel internally
 const app = new ObjectQL({
     datasources: {
         default: myDriver  // Must be DriverInterface
     }
 });
 
-await app.init();
+// Access the kernel if needed
+const kernel = app.getKernel();
+
+await app.init(); // This calls kernel.start() internally
+```
+
+### ObjectQLPlugin
+
+The new `ObjectQLPlugin` class implements the `RuntimePlugin` interface from `@objectstack/runtime`:
+
+```typescript
+import { ObjectQLPlugin, ObjectQLPluginConfig } from '@objectql/core';
+
+// Configure the plugin
+const plugin = new ObjectQLPlugin({
+    enableRepository: true,
+    enableValidator: true,
+    enableFormulas: true,
+    enableAI: true
+});
+
+// The plugin is automatically registered when you create an ObjectQL instance
+const app = new ObjectQL({ datasources: {} });
 ```
 
 ### Type Exports
@@ -76,6 +100,7 @@ The current `ObjectQL` class in this package is a **production-ready, feature-ri
 - Repository pattern
 - Formula engine
 - AI integration
+- **Wraps ObjectStackKernel for plugin architecture**
 - **Native driver management via @objectstack/objectql**
 
 The `ObjectQLEngine` from `@objectstack/objectql` is a **simpler, lightweight** implementation suitable for:
@@ -84,6 +109,46 @@ The `ObjectQLEngine` from `@objectstack/objectql` is a **simpler, lightweight**
 - Simple driver management
 - Minimal runtime overhead
 
+### Kernel Integration
+
+ObjectQL now wraps the `ObjectStackKernel` to provide plugin architecture and lifecycle management:
+
+```typescript
+// In @objectql/core
+import { ObjectStackKernel } from '@objectstack/runtime';
+import { ObjectQLPlugin } from './plugin';
+
+export class ObjectQL implements IObjectQL {
+    private kernel: ObjectStackKernel;
+    private kernelPlugins: any[] = [];
+    
+    constructor(config: ObjectQLConfig) {
+        // Add the ObjectQL plugin to provide enhanced features
+        this.kernelPlugins.push(new ObjectQLPlugin());
+        
+        // Create the kernel instance
+        this.kernel = new ObjectStackKernel(this.kernelPlugins);
+    }
+    
+    async init() {
+        console.log('[ObjectQL] Initializing with ObjectStackKernel...');
+        
+        // Start the kernel first - this will install and start all plugins
+        await this.kernel.start();
+        
+        // Continue with legacy initialization...
+    }
+    
+    /**
+     * Get the underlying ObjectStackKernel instance
+     * for advanced usage scenarios
+     */
+    getKernel(): ObjectStackKernel {
+        return this.kernel;
+    }
+}
+```
+
 ### Driver Management (No Compatibility Layer)
 
 ObjectQL now directly uses drivers conforming to `@objectstack/spec.DriverInterface`:
@@ -174,12 +239,73 @@ app.registerDriver('mydb', new MyCustomDriver(), false);
 
 ## Breaking Changes
 
+### v4.0.0: Plugin Architecture
+
+**What Changed:**
+- `ObjectQL` now wraps `ObjectStackKernel` from `@objectstack/runtime`
+- New `ObjectQLPlugin` class implements `RuntimePlugin` interface
+- Initialization process now calls `kernel.start()` which installs and starts all plugins
+- Dependencies updated to `@objectstack/*@0.2.0`
+- New `getKernel()` method provides access to the underlying kernel
+- **Removed legacy plugin support** - all plugins must now implement the `RuntimePlugin` interface
+
+**Migration Guide:**
+
+The ObjectQL API remains the same:
+```typescript
+import { ObjectQL } from '@objectql/core';
+import { MyDriver } from './my-driver';
+
+const app = new ObjectQL({
+    datasources: {
+        default: new MyDriver()
+    }
+});
+
+await app.init(); // Calls kernel.start() internally
+```
+
+Access the kernel for advanced use cases:
+```typescript
+const kernel = app.getKernel(); // Must call after init()
+```
+
+**Plugin Migration:**
+
+Old plugins with `onEnable` hook are no longer supported. Migrate to `RuntimePlugin`:
+
+```typescript
+// Old (no longer supported)
+const plugin = {
+    id: 'my-plugin',
+    onEnable: async (context) => {
+        // initialization logic
+    }
+};
+
+// New (required)
+import type { RuntimePlugin, RuntimeContext } from '@objectstack/runtime';
+
+class MyPlugin implements RuntimePlugin {
+    name = 'my-plugin';
+    
+    async install(ctx: RuntimeContext): Promise<void> {
+        // installation logic
+    }
+    
+    async onStart(ctx: RuntimeContext): Promise<void> {
+        // startup logic
+    }
+}
+
+const plugin = new MyPlugin();
+```
+
 ### v3.0.1: Native DriverInterface Adoption
 
 **What Changed:**
 - `ObjectQLConfig.datasources` now requires `Record<string, DriverInterface>` (from `@objectstack/spec`)
 - Removed compatibility wrapper for old `Driver` type
-- `app.registerDriver()` now accepts `DriverInterface` instead of legacy `Driver`
 - `app.datasource()` now returns `DriverInterface`
 - Driver lifecycle is fully managed by ObjectStack engine
 

packages/foundation/core/jest.config.js

@@ -12,10 +12,18 @@ module.exports = {
   testMatch: ['**/test/**/*.test.ts'],
   moduleNameMapper: {
     '^@objectql/(.*)$': '<rootDir>/../$1/src',
+    '^@objectstack/runtime$': '<rootDir>/test/__mocks__/@objectstack/runtime.ts',
   },
   transform: {
     '^.+\\.ts$': ['ts-jest', {
       isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+      }
     }],
   },
+  transformIgnorePatterns: [
+    'node_modules/(?!(@objectstack))',
+  ],
 };

packages/foundation/core/package.json

@@ -24,8 +24,8 @@
   "dependencies": {
     "@objectql/types": "workspace:*",
     "@objectstack/spec": "^0.2.0",
-    "@objectstack/runtime": "^0.1.1",
-    "@objectstack/objectql": "^0.1.1",
+    "@objectstack/runtime": "^0.2.0",
+    "@objectstack/objectql": "^0.2.0",
     "js-yaml": "^4.1.0",
     "openai": "^4.28.0"
   },