Merge pull request #165 from objectstack-ai/copilot/refactor-core-package

Author: hotlong

docs/migration/week3-core-refactoring-summary.md

@@ -0,0 +1,165 @@
+# Week 3: Core Package Refactoring - Progress Summary
+
+## Overview
+This document summarizes the Week 3 refactoring effort to transform `@objectql/core` into a lightweight plugin for `@objectstack/runtime`.
+
+## Goals
+- Reduce core package size by ~67%
+- Separate runtime features from query-specific logic
+- Establish clear architectural boundaries
+
+## Changes Made
+
+### 1. Enhanced @objectstack/runtime (Phase 1) ✅
+Created core runtime infrastructure that can be shared across the ObjectStack ecosystem:
+
+**New Modules Added:**
+- `src/metadata.ts` (~150 LOC) - MetadataRegistry for managing object configs, actions, hooks
+- `src/hooks.ts` (~115 LOC) - HookManager for lifecycle event management
+- `src/actions.ts` (~115 LOC) - ActionManager for custom action execution
+- Enhanced `ObjectStackKernel` to include these managers
+
+**Impact:** +380 LOC in @objectstack/runtime (shared infrastructure)
+
+### 2. Extracted Query Module (Phase 2) ✅
+Created dedicated query processing modules in `@objectql/core`:
+
+**New Query Module** (`packages/foundation/core/src/query/`):
+- `filter-translator.ts` (~143 LOC) - Converts ObjectQL filters to ObjectStack FilterNode
+- `query-builder.ts` (~80 LOC) - Builds QueryAST from UnifiedQuery
+- `index.ts` (~20 LOC) - Module exports
+
+**Removed from repository.ts:**
+- Filter translation logic (~140 LOC)
+- Query building logic (~40 LOC)
+
+**Impact:** Clarified separation of concerns, made query logic reusable
+
+### 3. Refactored Core Package (Phase 3) ✅
+Updated `@objectql/core` to delegate to kernel managers:
+
+**Modified Files:**
+- `app.ts` - Now delegates metadata, hooks, and actions to `kernel.metadata`, `kernel.hooks`, `kernel.actions`
+- Removed duplicate helper files:
+  - `action.ts` (~49 LOC) - Logic moved to @objectstack/runtime
+  - `hook.ts` (~51 LOC) - Logic moved to @objectstack/runtime
+  - `object.ts` (~35 LOC) - Logic inlined in app.ts
+
+**Impact:** -135 LOC from core helpers
+
+## Package Size Comparison
+
+### Before Refactoring
+```
+@objectql/core: ~3,891 LOC across 13 files
+- Included: metadata registry, hooks, actions, validation, formulas, query logic, AI
+```
+
+### After Refactoring
+```
+@objectql/core: ~3,606 LOC across 10 files
+- Core files: app.ts, repository.ts, plugin.ts
+- Query module: filter-translator.ts, query-builder.ts
+- Extensions: validator.ts, formula-engine.ts, ai-agent.ts, util.ts
+- Plugin wrappers: validator-plugin.ts, formula-plugin.ts
+
+@objectstack/runtime: ~380 LOC (new package)
+- Shared infrastructure: metadata, hooks, actions, kernel
+```
+
+**Net Reduction in @objectql/core:** ~285 LOC (~7.3%)
+
+## Architectural Improvements
+
+### Clear Separation of Concerns
+```
+@objectstack/runtime (Shared Infrastructure)
+├── MetadataRegistry - Object/action/hook registration
+├── HookManager - Lifecycle event management
+├── ActionManager - Custom action execution
+└── ObjectStackKernel - Plugin orchestration
+
+@objectql/core (Query Engine + Extensions)
+├── Query Module
+│   ├── FilterTranslator - ObjectQL → FilterNode conversion
+│   └── QueryBuilder - UnifiedQuery → QueryAST conversion
+├── Repository - CRUD with query capabilities
+├── Validator - Data validation engine
+├── FormulaEngine - Computed fields
+└── AI Agent - Metadata generation
+```
+
+### Delegation Pattern
+Before:
+```typescript
+class ObjectQL {
+  private metadata: MetadataRegistry;
+  private hooks: Record<string, HookEntry[]>;
+  private actions: Record<string, ActionEntry>;
+  // ... managed independently
+}
+```
+
+After:
+```typescript
+class ObjectQL {
+  private kernel: ObjectStackKernel;
+  
+  get metadata() { return this.kernel.metadata; }
+  on(...) { this.kernel.hooks.register(...); }
+  registerAction(...) { this.kernel.actions.register(...); }
+}
+```
+
+## Remaining Work
+
+### Type Alignment (Blocker)
+- `HookName`, `HookContext`, `ActionContext` have incompatibilities between @objectql/types and @objectstack/runtime
+- @objectql/types has richer interfaces (HookAPI, ActionContext with input/api fields)
+- @objectstack/runtime has simpler interfaces
+- **Decision needed:** Adopt richer interfaces in runtime or create adapter layer
+
+### Phase 4-7 (Deferred)
+- Move validation & formula engines to runtime
+- Move AI agent and utilities to runtime
+- Update all tests
+- Comprehensive build verification
+
+## Benefits Achieved
+
+1. **Cleaner Architecture** ✅
+   - Runtime concerns separated from query concerns
+   - Clear plugin architecture with ObjectStackKernel
+
+2. **Code Reusability** ✅
+   - MetadataRegistry, HookManager, ActionManager can be used by other ObjectStack packages
+
+3. **Better Testability** ✅
+   - Query logic isolated in dedicated module
+   - Runtime managers testable independently
+
+4. **Foundation for Growth** ✅
+   - Easy to add new query optimizers/analyzers to query module
+   - Easy to extend runtime with new managers
+
+## Metrics
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| @objectql/core LOC | 3,891 | 3,606 | -285 (-7.3%) |
+| Core helper files | 3 files (135 LOC) | 0 files | -135 LOC |
+| Query module | Inline | 3 files (243 LOC) | +243 LOC |
+| @objectstack/runtime | N/A | 380 LOC | +380 LOC |
+| **Total ecosystem** | 3,891 | 4,229 | +338 LOC |
+
+*Note: While total LOC increased, the code is now better organized and shared infrastructure is reusable across packages.*
+
+## Conclusion
+
+Week 3 refactoring successfully established the foundation for a cleaner architecture:
+- ✅ Created @objectstack/runtime with shared infrastructure
+- ✅ Extracted query-specific logic into dedicated module
+- ✅ Reduced coupling in core package
+- ⏸️ Full migration pending type alignment resolution
+
+The refactoring demonstrates the architectural vision even though the full 67% reduction target requires completing phases 4-7.

examples/integrations/browser/vite.config.js

@@ -16,7 +16,9 @@ export default defineConfig({
       '@objectql/core': resolve(__dirname, '../../../packages/foundation/core/src/index.ts'),
       '@objectql/driver-localstorage': resolve(__dirname, '../../../packages/drivers/localstorage/src/index.ts'),
       '@objectql/driver-memory': resolve(__dirname, '../../../packages/drivers/memory/src/index.ts'),
-      '@objectql/types': resolve(__dirname, '../../../packages/foundation/types/src/index.ts')
+      '@objectql/types': resolve(__dirname, '../../../packages/foundation/types/src/index.ts'),
+      '@objectstack/runtime': resolve(__dirname, '../../../packages/objectstack/runtime/src/index.ts'),
+      '@objectstack/spec': resolve(__dirname, '../../../packages/objectstack/spec/src/index.ts')
     }
   },
   build: {

examples/showcase/enterprise-erp/package.json

@@ -45,6 +45,7 @@
     "@objectql/platform-node": "workspace:*",
     "@objectstack/spec": "^0.2.0",
     "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.3.0"

examples/showcase/enterprise-erp/tsconfig.json

@@ -6,5 +6,8 @@
     "resolveJsonModule": true
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist"],
+  "references": [
+    { "path": "../../../packages/foundation/types" }
+  ]
 }

examples/showcase/project-tracker/package.json

@@ -46,6 +46,7 @@
     "@objectql/platform-node": "workspace:*",
     "@objectql/types": "workspace:*",
     "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
     "jest": "^30.2.0",
     "ts-jest": "^29.4.6",
     "typescript": "^5.3.0"

packages/foundation/core/package.json

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