Define RuntimePlugin interface and update protocol plugins for conformance

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,
+      }
+    }],
+  },
 };

packages/drivers/fs/package.json

@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*"
+    "@objectstack/spec": "^0.6.1"
   },
   "devDependencies": {
     "@types/jest": "^29.0.0",

packages/drivers/localstorage/package.json

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

packages/drivers/memory/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/memory/package.json

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

packages/drivers/mongo/package.json

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

packages/drivers/redis/package.json

@@ -20,7 +20,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*",
+    "@objectstack/spec": "^0.6.1",
     "redis": "^4.6.0"
   },
   "devDependencies": {

packages/drivers/sdk/package.json

@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*"
+    "@objectstack/spec": "^0.6.1"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

packages/drivers/sql/package.json

@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*",
+    "@objectstack/spec": "^0.6.1",
     "knex": "^3.1.0",
     "nanoid": "^3.3.11"
   },

packages/foundation/core/package.json

@@ -22,11 +22,11 @@
     "test": "jest"
   },
   "dependencies": {
-    "@objectstack/runtime": "workspace:*",
     "@objectql/types": "workspace:*",
-    "@objectstack/spec": "workspace:*",
-    "@objectstack/objectql": "workspace:*",
-    "@objectstack/core": "workspace:*",
+    "@objectstack/spec": "^0.6.1",
+    "@objectstack/runtime": "^0.6.1",
+    "@objectstack/objectql": "^0.6.1",
+    "@objectstack/core": "^0.6.1",
     "js-yaml": "^4.1.0",
     "openai": "^4.28.0"
   },

packages/foundation/core/src/app.ts

@@ -90,12 +90,26 @@ export class ObjectQL implements IObjectQL {
              }
         }
 
+        // Helper to unwrap content property (matching MetadataRegistry behavior)
+        const unwrapContent = (item: any) => {
+            if (item && item.content) {
+                return item.content;
+            }
+            return item;
+        };
+
         // Stub legacy accessors
         (this.kernel as any).metadata = {
             register: (type: string, item: any) => SchemaRegistry.registerItem(type, item, item.id ? 'id' : 'name'),
-            get: (type: string, name: string) => SchemaRegistry.getItem(type, name),
+            get: (type: string, name: string) => {
+                const item = SchemaRegistry.getItem(type, name) as any;
+                return unwrapContent(item);
+            },
             getEntry: (type: string, name: string) => SchemaRegistry.getItem(type, name),
-            list: (type: string) => SchemaRegistry.listItems(type),
+            list: (type: string) => {
+                const items = SchemaRegistry.listItems(type);
+                return items.map(unwrapContent);
+            },
             unregister: (type: string, name: string) => {
                  // Access private static storage using any cast
                  const metadata = (SchemaRegistry as any).metadata;