Merge pull request #238 from objectstack-ai/copilot/fix-runtimeplugin-issues

Author: hotlong

RUNTIME_PLUGIN_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,131 @@
+# RuntimePlugin Interface Implementation - Summary
+
+## Issue
+The GraphQL, OData V4, and JSON-RPC protocol plugins were not formally implementing a standard `RuntimePlugin` interface, leading to architectural inconsistency issues.
+
+## Solution
+We have successfully implemented the `RuntimePlugin` interface specification and updated all three protocol plugins to conform to it.
+
+## Changes Made
+
+### 1. RuntimePlugin Interface Definition (`@objectql/types`)
+
+Created `/packages/foundation/types/src/plugin.ts` defining:
+
+#### RuntimePlugin Interface
+```typescript
+export interface RuntimePlugin {
+  name: string;
+  version?: string;
+  install?(ctx: RuntimeContext): void | Promise<void>;
+  onStart?(ctx: RuntimeContext): void | Promise<void>;
+  onStop?(ctx: RuntimeContext): void | Promise<void>;
+}
+```
+
+#### RuntimeContext Interface
+```typescript
+export interface RuntimeContext {
+  engine: any;
+  getKernel?: () => any;
+}
+```
+
+### 2. Protocol Plugin Updates
+
+#### GraphQL Plugin (`@objectql/protocol-graphql`)
+- ✅ Implements `RuntimePlugin` interface
+- ✅ Removed dependency on `@objectstack/runtime`
+- ✅ Added helper methods for metadata and CRUD operations
+- ✅ Direct engine access via RuntimeContext
+
+#### OData V4 Plugin (`@objectql/protocol-odata-v4`)
+- ✅ Implements `RuntimePlugin` interface
+- ✅ Removed dependency on `@objectstack/runtime`
+- ✅ Added helper methods for metadata and CRUD operations
+- ✅ Direct engine access via RuntimeContext
+
+#### JSON-RPC Plugin (`@objectql/protocol-json-rpc`)
+- ✅ Implements `RuntimePlugin` interface
+- ✅ Removed dependency on `@objectstack/runtime`
+- ✅ Added helper methods for metadata and CRUD operations
+- ✅ Direct engine access via RuntimeContext
+
+### 3. Package Dependencies
+
+Updated all three plugin `package.json` files to:
+- Remove `@objectstack/runtime` dependency
+- Use only `@objectql/types` for interface definitions
+
+### 4. Tests
+
+Added comprehensive test suite in `/packages/foundation/types/test/plugin.test.ts`:
+- RuntimePlugin interface conformance tests
+- RuntimeContext functionality tests
+- Lifecycle hook execution order tests
+- Sync/async hook support tests
+
+### 5. Documentation
+
+Updated `/packages/protocols/README.md`:
+- Documented RuntimePlugin interface
+- Documented RuntimeContext
+- Updated plugin implementation pattern
+- Added Engine API documentation
+- Removed references to deprecated ObjectStackRuntimeProtocol
+
+## Architecture Compliance
+
+### ✅ Standard Lifecycle Hooks
+All plugins now implement:
+1. **install(ctx)** - Called during kernel initialization
+2. **onStart(ctx)** - Called when kernel starts
+3. **onStop(ctx)** - Called when kernel stops
+
+### ✅ Consistent Interface
+All plugins implement the same `RuntimePlugin` interface from `@objectql/types`, ensuring:
+- Uniform plugin architecture
+- Predictable lifecycle management
+- Easy plugin discovery and validation
+- Type-safe plugin development
+
+### ✅ Direct Engine Access
+Plugins no longer depend on a separate protocol bridge layer. Instead:
+- They access the kernel/engine directly via RuntimeContext
+- They implement their own helper methods for common operations
+- They maintain full control over their data access patterns
+
+## Impact
+
+### Architecture Consistency ✅
+- All protocol plugins follow the same interface
+- Clear lifecycle management
+- Consistent error handling
+
+### Plugin Extensibility ✅
+- Easy to add new protocol plugins
+- Clear contract to implement
+- Type-safe development
+
+### Maintenance Cost ✅
+- Reduced dependency on non-existent packages
+- Simpler architecture
+- Better testability
+
+## Testing Results
+
+- ✅ RuntimePlugin interface tests pass
+- ✅ Existing plugin lifecycle tests remain valid
+- ✅ No breaking changes to plugin APIs
+- ✅ TypeScript compilation successful (modulo external dependencies)
+
+## Next Steps
+
+The implementation is complete and ready for use. Protocol plugins can now be:
+1. Instantiated with their configuration
+2. Passed to the kernel/runtime
+3. Initialized via the install hook
+4. Started via the onStart hook
+5. Stopped via the onStop hook
+
+All three plugins (GraphQL, OData V4, JSON-RPC) are now fully compliant with the ObjectStack RuntimePlugin specification.

examples/integrations/express-server/jest.config.js

@@ -13,10 +13,18 @@ module.exports = {
   moduleNameMapper: {
   },
   transform: {
-    '^.+\\.ts$': ['ts-jest', {
+    '^.+\\.(t|j)sx?$': ['ts-jest', {
       isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+        allowJs: true,
+      }
     }],
   },
+  transformIgnorePatterns: [
+    "/node_modules/(?!(@objectstack|.pnpm))"
+  ],
   collectCoverageFrom: [
     'src/**/*.ts',
     '!src/**/*.d.ts',

examples/protocols/multi-protocol-server/package.json

@@ -14,7 +14,6 @@
     "@objectql/protocol-graphql": "workspace:*",
     "@objectql/protocol-json-rpc": "workspace:*",
     "@objectql/protocol-odata-v4": "workspace:*",
-    "@objectstack/runtime": "workspace:*",
     "@objectql/types": "workspace:*"
   },
   "devDependencies": {

examples/showcase/enterprise-erp/jest.config.js

@@ -13,10 +13,18 @@ module.exports = {
   moduleNameMapper: {
   },
   transform: {
-    '^.+\\.ts$': ['ts-jest', {
+    '^.+\\.(t|j)sx?$': ['ts-jest', {
       isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+        allowJs: true,
+      }
     }],
   },
+  transformIgnorePatterns: [
+    "/node_modules/(?!(@objectstack|.pnpm))"
+  ],
   collectCoverageFrom: [
     'src/**/*.ts',
     '!src/**/*.d.ts',

examples/showcase/enterprise-erp/package.json

@@ -43,7 +43,6 @@
     "@objectql/driver-sql": "workspace:*",
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*",
     "@types/jest": "^30.0.0",
     "@types/node": "^20.0.0",
     "jest": "^30.2.0",

examples/showcase/project-tracker/jest.config.js

@@ -13,10 +13,18 @@ module.exports = {
   moduleNameMapper: {
   },
   transform: {
-    '^.+\\.ts$': ['ts-jest', {
+    '^.+\\.(t|j)sx?$': ['ts-jest', {
       isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+        allowJs: true,
+      }
     }],
   },
+  transformIgnorePatterns: [
+    "/node_modules/(?!(@objectstack|.pnpm))"
+  ],
   collectCoverageFrom: [
     'src/**/*.ts',
     '!src/**/*.d.ts',

package.json

@@ -24,9 +24,6 @@
     "@changesets/cli": "^2.29.8",
     "@objectql/example-enterprise-erp": "workspace:*",
     "@objectql/example-project-tracker": "workspace:*",
-    "@objectstack/objectql": "workspace:*",
-    "@objectstack/runtime": "workspace:*",
-    "@objectstack/spec": "workspace:*",
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",

packages/drivers/excel/jest.config.js

@@ -13,5 +13,14 @@ module.exports = {
   collectCoverageFrom: ['src/**/*.ts'],
   moduleNameMapper: {
     '^@objectql/types$': '<rootDir>/../../foundation/types/src',
-  }
+  },
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+      }
+    }],
+  },
 };

packages/drivers/excel/package.json

@@ -21,7 +21,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*",
+    "@objectstack/spec": "^0.6.1",
     "exceljs": "^4.4.0"
   },
   "devDependencies": {

packages/drivers/fs/jest.config.js

@@ -13,5 +13,14 @@ module.exports = {
   collectCoverageFrom: ['src/**/*.ts'],
   moduleNameMapper: {
     '^@objectql/types$': '<rootDir>/../../foundation/types/src',
-  }
+  },
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      isolatedModules: true,
+      tsconfig: {
+        esModuleInterop: true,
+        allowSyntheticDefaultImports: true,
+      }
+    }],
+  },
 };