Merge pull request #150 from objectstack-ai/copilot/execute-phase-1-migration

Author: hotlong

PHASE_1_COMPLETE.md

@@ -0,0 +1,153 @@
+# Phase 1 Migration Complete: Foundation & Core Types
+
+## Overview
+
+Phase 1 of the ObjectQL v4.0 migration has been completed. This phase establishes the foundation for the new plugin-based architecture.
+
+## What Changed
+
+### 1. New Directory Structure
+
+```
+packages/
+├── core/
+│   └── types/              # NEW: @objectql/types v4.0.0
+├── plugins/                # NEW: Plugin directory (empty, ready for plugins)
+├── foundation/             # EXISTING: v3.x packages (unchanged)
+│   ├── types/              # Will be deprecated in future
+│   ├── core/
+│   └── platform-node/
+├── drivers/                # EXISTING: Will be migrated to plugins
+└── tools/                  # EXISTING: Will be updated
+```
+
+### 2. New Package: @objectql/types v4.0.0
+
+A new types package has been created at `packages/core/types/` with:
+
+#### Plugin Interfaces
+
+- **`BasePlugin`** - Base interface for all plugins
+- **`QueryProcessorPlugin`** - For query validation, optimization, transformation
+- **`RepositoryPlugin`** - For extending repositories with batch ops, audit tracking
+- **`PluginMetadata`** - Plugin metadata and dependencies
+- **`PluginLifecycle`** - Setup and teardown hooks
+
+#### Query Types
+
+- **`UnifiedQuery`** - Core query structure
+- **`FilterExpression`** - Type-safe filter expressions  
+- **`QueryResult`** - Query results with pagination metadata
+- **`QueryOptions`** - Query execution options
+
+#### Runtime Types
+
+- **`RuntimeContext`** - Context available to plugins
+- **`ValidationResult`** - Query validation results
+- **`ValidationError`** - Validation error details
+
+### 3. Type Removals
+
+The following types have been removed from the new v4.0 package as they are now provided by `@objectstack/spec` or `@objectstack/runtime`:
+
+#### Removed (Now in @objectstack/spec):
+- `Driver` interface → Use `DriverInterface` from `@objectstack/spec`
+
+#### Removed (Now in @objectstack/runtime):
+- `MetadataRegistry` class
+- `Context` types
+- `Hook` types  
+- `Action` types
+
+### 4. Workspace Configuration
+
+- **pnpm-workspace.yaml**: Added `packages/core/*` and `packages/plugins/*`
+- **tsconfig.json**: Added reference to `packages/core/types`
+
+## Migration Impact
+
+### For Plugin Developers
+
+If you're developing plugins, use the new interfaces:
+
+```typescript
+// New v4.0 plugin
+import { QueryProcessorPlugin } from '@objectql/types';
+
+export function myPlugin(): QueryProcessorPlugin {
+  return {
+    name: '@myorg/plugin',
+    version: '1.0.0',
+    type: 'query-processor',
+    
+    async validateQuery(ast, context) {
+      return { valid: true, errors: [] };
+    },
+    
+    async beforeQuery(ast, context) {
+      return ast;
+    }
+  };
+}
+```
+
+### For Application Developers
+
+**No immediate action required.** The existing `@objectql/types` (v3.x) in `packages/foundation/types` remains unchanged and will continue to work.
+
+The new package at `packages/core/types` is for new plugin development and will be used by migrated packages in future phases.
+
+## Dependencies
+
+The new `@objectql/types` v4.0.0 depends on:
+
+- `@objectstack/spec` ^0.2.0 - Protocol specifications
+- `@objectstack/runtime` ^0.2.0 - Runtime types
+
+These packages provide the foundation for driver interfaces, metadata management, and runtime context.
+
+## Build Verification
+
+The new package has been built and verified:
+
+✅ TypeScript compilation successful  
+✅ All type definitions generated  
+✅ No circular dependencies  
+✅ Strict type checking enabled
+
+## Next Steps
+
+### Phase 2: Core Plugin Migration (Week 3-4)
+
+The following will be migrated in the next phase:
+
+- Create `@objectql/query-validation` plugin
+- Create `@objectql/advanced-repository` plugin
+- Extract functionality from `@objectql/core`
+
+### Phase 3: Driver Migration (Week 5-6)
+
+Drivers will be migrated to the plugin architecture:
+
+- `@objectql/driver-sql`
+- `@objectql/driver-memory`
+- `@objectql/driver-mongo`
+- `@objectql/driver-sdk`
+
+## Documentation
+
+- **Plugin Architecture**: See [PLUGIN_ARCHITECTURE.md](./PLUGIN_ARCHITECTURE.md)
+- **Package Restructuring**: See [PACKAGE_RESTRUCTURING.md](./PACKAGE_RESTRUCTURING.md)
+- **Implementation Roadmap**: See [IMPLEMENTATION_ROADMAP.md](./IMPLEMENTATION_ROADMAP.md)
+- **Plugin Directory**: See [packages/plugins/README.md](./packages/plugins/README.md)
+- **New Types Package**: See [packages/core/types/README.md](./packages/core/types/README.md)
+
+## Questions or Issues?
+
+If you encounter any issues with the new type definitions or have questions about plugin development, please open an issue on GitHub.
+
+---
+
+**Phase 1 Status**: ✅ Complete  
+**Date**: 2026-01-21  
+**Next Phase**: Week 3-4 (Core Plugin Migration)

packages/core/types/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.tsbuildinfo
+coverage
+.DS_Store

packages/core/types/CHANGELOG.md

@@ -0,0 +1,67 @@
+# @objectql/types v4.0.0
+
+## [4.0.0] - 2026-01-21
+
+### Breaking Changes
+
+- Complete rewrite of type system for plugin-based architecture
+- Removed types now in @objectstack/spec:
+  - `Driver` interface (use `DriverInterface` from @objectstack/spec)
+- Removed types now in @objectstack/runtime:
+  - `MetadataRegistry` class
+  - `Context` types
+  - `Hook` types
+  - `Action` types
+
+### Added
+
+- New plugin interfaces:
+  - `QueryProcessorPlugin` - For query validation, optimization, and transformation
+  - `RepositoryPlugin` - For extending repository with batch operations, audit tracking
+  - `BasePlugin` - Base interface for all plugins
+- Query-specific types:
+  - `UnifiedQuery` - Core query structure
+  - `FilterExpression` - Type-safe filter expressions
+  - `QueryResult` - Query result wrapper with pagination
+  - `QueryOptions` - Query execution options
+- Runtime types:
+  - `RuntimeContext` - Context available to plugins during execution
+  - `ValidationResult` - Query validation result
+  - `ValidationError` - Validation error details
+
+### Dependencies
+
+- Added `@objectstack/spec` ^0.2.0
+- Added `@objectstack/runtime` ^0.2.0
+
+### Migration Guide
+
+If you were using types that are now removed:
+
+```typescript
+// Old (v3.x)
+import { Driver, MetadataRegistry, Hook } from '@objectql/types';
+
+// New (v4.x)
+import { DriverInterface } from '@objectstack/spec';
+// MetadataRegistry, Hook, Action are now part of @objectstack/runtime
+```
+
+For plugin development:
+
+```typescript
+// New in v4.x
+import { QueryProcessorPlugin, RepositoryPlugin } from '@objectql/types';
+
+export function myPlugin(): QueryProcessorPlugin {
+  return {
+    name: '@myorg/plugin',
+    version: '1.0.0',
+    type: 'query-processor',
+    async beforeQuery(ast, context) {
+      // Transform query
+      return ast;
+    }
+  };
+}
+```

packages/core/types/README.md

@@ -0,0 +1,56 @@
+# @objectql/types
+
+Type definitions and plugin interfaces for ObjectQL v4.0.
+
+## Overview
+
+This package provides the core TypeScript type definitions for ObjectQL's plugin architecture. It includes:
+
+- **Plugin Interfaces**: Define custom query plugins, repository extensions, and query processors
+- **Query Types**: Type-safe query construction and manipulation
+- **Helper Types**: Utility types for working with ObjectQL queries
+
+## Key Principles
+
+1. **Zero Dependencies on Internal Packages**: This package depends only on `@objectstack/spec` and `@objectstack/runtime`
+2. **Protocol-Driven**: Types define the contract, implementation follows
+3. **Strict Type Safety**: All types use TypeScript strict mode
+
+## Installation
+
+```bash
+npm install @objectql/types
+```
+
+## Usage
+
+```typescript
+import { QueryPlugin, RepositoryPlugin, UnifiedQuery } from '@objectql/types';
+
+// Define a custom query plugin
+export function myQueryPlugin(): QueryPlugin {
+  return {
+    name: '@myorg/query-plugin',
+    version: '1.0.0',
+    type: 'query-processor',
+    async beforeQuery(ast, context) {
+      // Transform query before execution
+      return ast;
+    }
+  };
+}
+```
+
+## Migration from v3.x
+
+In v4.0, ObjectQL has transitioned to a plugin-based architecture built on `@objectstack/runtime`:
+
+- **Driver Interface**: Now uses `DriverInterface` from `@objectstack/spec`
+- **Metadata & Context**: Now managed by `@objectstack/runtime`
+- **Hooks & Actions**: Now part of `@objectstack/runtime`
+
+This package focuses exclusively on query-specific types and plugin interfaces.
+
+## License
+
+MIT © ObjectStack Inc.

packages/core/types/jest.config.js

@@ -0,0 +1,9 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/__tests__/**/*.test.ts'],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    '!src/**/*.d.ts',
+  ],
+};

packages/core/types/package-lock.json

@@ -0,0 +1,28 @@
+{
+  "name": "@objectql/types",
+  "version": "4.0.0",
+  "description": "Type definitions and plugin interfaces for ObjectQL - Query-specific types and plugin architecture",
+  "keywords": [
+    "objectql",
+    "types",
+    "typescript",
+    "interfaces",
+    "plugin",
+    "query",
+    "ai-native"
+  ],
+  "license": "MIT",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --passWithNoTests"
+  },
+  "dependencies": {
+    "@objectstack/spec": "^0.2.0",
+    "@objectstack/runtime": "^0.2.0"
+  }
+}