Migration assessment: ObjectQL → @objectstack/runtime plugin architecture

[Copilot]

Evaluates migration of ObjectQL from standalone ORM to plugin ecosystem for @objectstack/runtime. Repositions this codebase as query-related extensions (Repository pattern, Validators, Formula engine, 9 database drivers) on ObjectStack foundation.

Deliverables

9 comprehensive planning documents (89KB, 3,200+ lines)

• MIGRATION_INDEX.md - Navigation hub
• MIGRATION_QUICKSTART.md - Week 1 action plan
• ASSESSMENT_EXECUTIVE_SUMMARY.md - Stakeholder summary
• MIGRATION_TO_OBJECTSTACK.md - Strategic plan (EN)
• MIGRATION_TO_OBJECTSTACK.zh-CN.md - 战略计划 (中文)
• IMPLEMENTATION_ROADMAP.md - Day-by-day implementation guide with code examples
• WORK_BREAKDOWN.md - 41 trackable tasks, 77 person-day estimates
• MIGRATION_SUMMARY.md - API impact analysis (v3 → v4)
• .github/ISSUE_TEMPLATE/migration-task.md - Issue template

Scope Analysis

Repository: 97 TypeScript files, 14 packages
Timeline: 11 weeks, 8 phases, 41 tasks, 77 person-days
Team: 3-4 developers recommended

Package Transformation

Layer	Current Role	New Role
Foundation (3)	Standalone runtime	Plugin components
Drivers (9)	Custom interface	@objectstack/spec DriverInterface
Runtime (1)	Independent server	@objectstack/runtime extension
Tools (3)	Standalone CLI/VSCode	ObjectStack-aware tooling

Architectural Shift

// v3.x - Standalone
import { ObjectQL } from '@objectql/core';
const app = new ObjectQL({ datasources: {...} });

// v4.x - Plugin
import { ObjectStackKernel } from '@objectstack/runtime';
import { ObjectQLPlugin } from '@objectql/core';

const kernel = new ObjectStackKernel({ datasources: {...} });
kernel.use(new ObjectQLPlugin());

// v3.x API maintained via compatibility wrapper

Migration Phases

1. Dependency Alignment (Week 1-2): Update to @objectstack/* 0.2.0
2. Types Consolidation (Week 2-3): Deduplicate with @objectstack/spec
3. Core Refactoring (Week 3-5): Plugin architecture, backward compat layer
4. Driver Migration (Week 5-7): 9 drivers → DriverInterface
5. Runtime & Tools (Week 7-8): Server/CLI/VSCode integration
6. Documentation (Week 8-9): Migration guide, examples
7. Testing (Week 9-10): Integration tests, performance validation
8. Publishing (Week 10-11): v4.0.0 release

Risk Mitigation

• Backward compatibility via wrapper layer (v3.x API preserved)
• 6-month v3.x support period
• Automated migration tools in CLI
• Performance target: ≤5% regression

Next Steps

Create GitHub Project → Generate 41 issues from WORK_BREAKDOWN.md → Team kickoff → Begin Phase 1

Original prompt

评估现有代码全面迁移到@objectstack/runtime 新架构的工作清单，原则上这个仓库只是一个插件仓库，在objectstack的基础框架中开发插件扩展查询相关的功能

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
objectql-site	Ready	Preview, Comment	Jan 21, 2026 5:51pm

[huangyiirene]

第一步已安排迁移完成

根据迁移计划文档（特别是 IMPLEMENTATION_ROADMAP.md 和 MIGRATION_TO_OBJECTSTACK.zh-CN.md），@objectql/core 的迁移核心在于 Phase 3: Core Engine Refactoring (核心引擎重构)。

虽然 Phase 1 和 Phase 2 是前置准备（依赖更新和类型清理），但在架构层面，Phase 3 的第一部分（设计插件接口和重构 App 入口）才是真正的“内核迁移”起点。

以下是针对 Phase 3 核心引擎重构第一部分（即创建插件结构和兼容层）的完整提示词。你可以直接使用此提示词让 AI 助手执行代码修改。

针对内核包迁移第一部分的完整提示词 (Prompt)

Role: Expert TypeScript Architect & Migration Specialist
Context: ObjectQL Migration to @objectstack/runtime Plugin Architecture (PR #154)
Target: @objectql/core package
Reference Document: IMPLEMENTATION_ROADMAP.md (Phase 3)

Task:
Execute the first part of the Phase 3: Core Engine Refactoring. You need to transform the standalone ObjectQL core into a plugin compatible with the ObjectStackKernel, while maintaining backward compatibility.

Specific Actions:

Create Plugin Interface (packages/foundation/core/src/plugin.ts):

Define ObjectQLPluginConfig interface.
Implement ObjectQLPlugin class implementing the Plugin interface from @objectstack/runtime.
The install method should prepare to register components (Repository, Validator, Formula, AI) based on the config. Note: For this step, you can verify if these components exist or just setup the structure as placeholders/imports.
Refactor Main Entry (packages/foundation/core/src/app.ts):

Import ObjectStackKernel from @objectstack/runtime.
Refactor the ObjectQL class to wrap ObjectStackKernel.
In the constructor, initialize ObjectStackKernel with the provided datasources.
Use .use(new ObjectQLPlugin()) to register the new plugin.
Ensure legacy methods (like init, getObject, createContext) proxy to the kernel or the plugin's internal logic to maintain backward compatibility.
Code Reference (from Roadmap):

// packages/foundation/core/src/plugin.ts
import type { Plugin, ObjectStackKernel } from '@objectstack/runtime';

export interface ObjectQLPluginConfig {
enableRepository?: boolean;
enableValidator?: boolean;
enableFormulas?: boolean;
enableAI?: boolean;
}

export class ObjectQLPlugin implements Plugin {
name = '@objectql/core';
version = '4.0.0';

constructor(private config: ObjectQLPluginConfig = {}) {}

async install(kernel: ObjectStackKernel): Promise {
// Logic to register components (can be placeholders for now)
// if (this.config.enableRepository !== false) this.registerRepository(kernel);
}
}
// packages/foundation/core/src/app.ts
import { ObjectStackKernel } from '@objectstack/runtime';
import { ObjectQLPlugin } from './plugin';

// Legacy API Wrapper
export class ObjectQL {
private kernel: ObjectStackKernel;

constructor(config: any) { // Update type signature as needed
this.kernel = new ObjectStackKernel({
datasources: config.datasources
});
this.kernel.use(new ObjectQLPlugin());
// ... handle other legacy config migration
}

async init() {
await this.kernel.init();
}

// Proxy methods
getObject(name: string) {
return this.kernel.getObject(name);
}

createContext(options: any) {
return this.kernel.createContext(options);
}
}
Requirements:

Ensure all imports from @objectstack/runtime are correct.
The code must compile (assuming Phase 1 dependency updates are done).
Do not remove existing logic that hasn't been migrated yet; focusing on establishing the Plugin Structure and Kernel Integration.
💡 使用建议

确认依赖：在使用此提示词之前，请确保 Phase 1 (Dependency Alignment) 已经完成，即 package.json 中的依赖已更新为 @objectstack/* 的 0.2.0 版本，否则代码会报错。
分步执行：这个提示词涵盖了 Task 3.1 和 3.2。如果变更量大，可以拆分为“创建 plugin.ts”和“重构 app.ts”两个步骤。