Skip to content

refactor: align dev workflow config and docs with plugin-query/plugin-optimizations decomposition #375

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hotlong merged 3 commits into from
Feb 11, 2026
Merged

refactor: align dev workflow config and docs with plugin-query/plugin-optimizations decomposition #375

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4f62ecf
Initial plan
Copilot Feb 11, 2026
3e9b590
refactor: update dev workflow config and docs for plugin-query/plugin…
Copilot Feb 11, 2026
e2882f6
docs: add objectstack CLI commands and kernel config documentation to…
Copilot Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/config.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,25 @@
"@objectql/driver-fs",
"@objectql/driver-memory",
"@objectql/driver-mongo",
"@objectql/driver-pg-wasm",
"@objectql/driver-redis",
"@objectql/driver-sql",
"@objectql/driver-sqlite-wasm",
"@objectql/driver-tck",
"@objectql/edge-adapter",
"@objectql/platform-node",
"@objectql/plugin-formula",
"@objectql/plugin-multitenancy",
"@objectql/plugin-optimizations",
"@objectql/plugin-query",
"@objectql/plugin-security",
"@objectql/plugin-sync",
"@objectql/plugin-validator",
"@objectql/plugin-workflow",
"@objectql/protocol-graphql",
"@objectql/protocol-json-rpc",
"@objectql/protocol-odata-v4",
"@objectql/protocol-sync",
"@objectql/protocol-tck",
"@objectql/sdk",
"@objectql/types"
Expand Down
90 changes: 83 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,13 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
| Package | Environment | Description |
| :--- | :--- | :--- |
| **[`@objectql/types`](./packages/foundation/types)** | Universal | **The Contract.** Pure TypeScript interfaces defining the protocol. |
| **[`@objectql/core`](./packages/foundation/core)** | Universal | **The Engine.** The runtime logic, validation, and repository pattern. |
| **[`@objectql/platform-node`](./packages/foundation/platform-node)**| Node.js | Node.js platform utilities for file system integration, YAML loading, and plugin management. |
| **[`@objectql/core`](./packages/foundation/core)** | Universal | **The Engine.** Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins. |
| **[`@objectql/plugin-query`](./packages/foundation/plugin-query)** | Universal | **Query Plugin.** QueryService, QueryBuilder, QueryAnalyzer, and FilterTranslator. |
| **[`@objectql/plugin-optimizations`](./packages/foundation/plugin-optimizations)** | Universal | **Optimizations Plugin.** Connection pooling, query compilation, compiled hooks, lazy metadata loading, and SQL query optimization. |
| **[`@objectql/plugin-security`](./packages/foundation/plugin-security)**| Universal | **Security Plugin.** Comprehensive RBAC, Field-Level Security (FLS), and Row-Level Security (RLS) with AST-level enforcement. |
| **[`@objectql/plugin-validator`](./packages/foundation/plugin-validator)**| Universal | **Validation Plugin.** 5-type validation engine: field, cross-field, state machine, unique, and business rule. |
| **[`@objectql/plugin-formula`](./packages/foundation/plugin-formula)**| Universal | **Formula Plugin.** Computed fields with JavaScript expressions in a sandboxed evaluator. |
| **[`@objectql/platform-node`](./packages/foundation/platform-node)**| Node.js | Node.js platform utilities for file system integration, YAML loading, and plugin management. |

### Driver Layer

Expand Down Expand Up @@ -357,21 +361,75 @@ If you fork or clone the repository to contribute or run examples from source:

1. **Setup Workspace**
```bash
git clone https://github.com/objectql/objectql.git
git clone https://github.com/objectstack-ai/objectql.git
cd objectql
npm install -g pnpm
corepack enable && corepack prepare pnpm@10.28.2 --activate
pnpm install
```

2. **Build Packages**
You must build the core libraries before running examples, as they rely on local workspace builds.
You must build all packages before running examples or the dev server, as they rely on local workspace builds.
```bash
pnpm build
```

3. **Run Examples**
3. **Run Dev Server**
Start the full-stack development server with all plugins (ObjectQL + Security + GraphQL + OData + JSON-RPC):
```bash
pnpm dev
# Equivalent to: objectstack serve --dev
# Starts ObjectStack kernel at http://localhost:5050
# Loads project-tracker example metadata from objectstack.config.ts
```

These examples run as **scripts** to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory SQLite database.
The dev server is powered by `@objectstack/cli` (v2.0.6). It reads `objectstack.config.ts` in the project root, which configures the kernel with all plugins:

```typescript
// objectstack.config.ts
export default {
metadata: { name: 'objectos', version: '1.0.0' },
objects: loadObjects(projectTrackerDir),
plugins: [
Comment on lines +387 to +392
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The objectstack.config.ts example is presented as a copy/pasteable config, but it references loadObjects(projectTrackerDir) without defining/importing loadObjects or projectTrackerDir (and it omits required imports for the plugin classes). Either include a complete minimal example (with imports + helper definitions) or explicitly mark the snippet as abbreviated and link readers to the real ./objectstack.config.ts file for a working version.

Copilot uses AI. Check for mistakes.
new HonoServerPlugin({ port: 5050 }),
new ObjectQLPlugin({
enableRepository: true,
enableQueryService: true, // ← uses @objectql/plugin-query internally
enableValidator: true,
enableFormulas: true,
datasources: { default: new MemoryDriver() }
}),
new ObjectQLSecurityPlugin({ enableAudit: false }),
new GraphQLPlugin({ basePath: '/graphql' }),
new ODataV4Plugin({ basePath: '/odata' }),
new JSONRPCPlugin({ basePath: '/rpc' }),
]
};
```

**Available `objectstack` CLI commands** (via `@objectstack/cli`):

| Command | Description |
| :--- | :--- |
| `objectstack serve --dev` | Start dev server (same as `pnpm dev`) |
| `objectstack serve` | Start production server |
| `objectstack create` | Scaffold a new project |
| `objectstack doctor` | Diagnose environment issues |

4. **Run Tests**
```bash
# Run all tests
npx vitest run

# Run tests for a specific package
npx vitest run packages/foundation/core

# Run tests in watch mode
npx vitest --watch
```

5. **Run Examples**

These examples run as **scripts** to demonstrate the ObjectQL Core Engine capabilities (Validation, CRUD, Logic Hooks). They use an in-memory database.

**Starter (Project Tracker):**
```bash
Expand All @@ -387,6 +445,24 @@ If you fork or clone the repository to contribute or run examples from source:
# Output: Plugin initialization, Employee creation logs, Audit trails
```

### Architecture Note

Since [#373](https://github.com/objectstack-ai/objectql/pull/373), `@objectql/core` has been decomposed into focused plugin packages:

- **`@objectql/plugin-query`** — QueryService, QueryBuilder, QueryAnalyzer, FilterTranslator
- **`@objectql/plugin-optimizations`** — Connection pooling, query compilation, compiled hooks, SQL optimization

`@objectql/core` re-exports these modules with `@deprecated` tags for backward compatibility. **New code should import directly from the plugin packages:**

```typescript
// ✅ Recommended
import { QueryService } from '@objectql/plugin-query';
import { QueryCompiler } from '@objectql/plugin-optimizations';

// ❌ Deprecated (still works, but will be removed in v5)
import { QueryService, QueryCompiler } from '@objectql/core';
```

---

## ⚖️ License
Expand Down
2 changes: 1 addition & 1 deletion docs/DESIGN_CORE_REFACTOR.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
> **Author:** ObjectStack Architecture Team
> **Date:** 2026-02-10
> **Updated:** 2026-02-11
> **Status:** Ready for Implementation — Upstream prerequisites met
> **Status:** ✅ Completed — Implemented in [PR #373](https://github.com/objectstack-ai/objectql/pull/373)
> **Scope:** Decompose `@objectql/core`, align with `@objectstack/objectql` plugin extension model
> **Upstream Repo:** https://github.com/objectstack-ai/spec (v2.0.5+, latest commit `33646a7`)
> **Local Repo:** https://github.com/objectstack-ai/objectql (v4.2.0)
Expand Down
22 changes: 11 additions & 11 deletions docs/ROADMAP_NEXT_PHASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -364,17 +364,17 @@ Each rule should be re-enabled incrementally after fixing violations:

### 7A. Core performance

The `packages/foundation/core/src/optimizations/` directory contains advanced optimization modules that are already implemented:

| Module | Status | Action |
|--------|--------|--------|
| `GlobalConnectionPool.ts` | ✅ Implemented | Benchmark and tune pool sizes |
| `QueryCompiler.ts` | ✅ Implemented | Add cache hit/miss metrics |
| `LazyMetadataLoader.ts` | ✅ Implemented | Verify lazy loading in production |
| `OptimizedValidationEngine.ts` | ✅ Implemented | Benchmark vs. base validator |
| `CompiledHookManager.ts` | ✅ Implemented | Profile hook chain overhead |
| `SQLQueryOptimizer.ts` | ✅ Implemented | Add query plan analysis |
| `DependencyGraph.ts` | ✅ Implemented | Ensure circular dependency detection |
The optimization modules have been extracted into `@objectql/plugin-optimizations` (see [PR #373](https://github.com/objectstack-ai/objectql/pull/373)):

| Module | Package | Status | Action |
|--------|---------|--------|--------|
| `GlobalConnectionPool.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Benchmark and tune pool sizes |
| `QueryCompiler.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Add cache hit/miss metrics |
| `LazyMetadataLoader.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Verify lazy loading in production |
Comment on lines +369 to +373
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This module list for @objectql/plugin-optimizations is incomplete: the package also includes OptimizedMetadataRegistry.ts (exported from packages/foundation/plugin-optimizations/src/index.ts). Consider adding it to the table so the roadmap stays aligned with the actual extracted module set.

Copilot uses AI. Check for mistakes.
| `OptimizedValidationEngine.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Benchmark vs. base validator |
| `CompiledHookManager.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Profile hook chain overhead |
| `SQLQueryOptimizer.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Add query plan analysis |
| `DependencyGraph.ts` | `@objectql/plugin-optimizations` | ✅ Implemented | Ensure circular dependency detection |

### 7B. Browser bundle optimization

Expand Down
22 changes: 12 additions & 10 deletions docs/WORK_PLAN_2026_Q1_P2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# ObjectQL Work Plan — 2026 Roadmap

> Created: 2026-02-08 | Last Updated: 2026-02-09 | Status: **Active**
> Created: 2026-02-08 | Last Updated: 2026-02-11 | Status: **Active**
> Current Version: **4.2.0** (all packages aligned, except `vscode-objectql` at 4.1.0)
Copy link

Copilot AI Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The header claims vscode-objectql is at 4.1.0, but the extension manifest currently declares version 4.2.0. Please update this line (or clarify if you mean the published marketplace version vs the repo version) to avoid confusing the release/version alignment story.

Suggested change
> Current Version: **4.2.0** (all packages aligned, except `vscode-objectql` at 4.1.0)
> Current Version: **4.2.0** (all packages aligned, including `vscode-objectql`)

Copilot uses AI. Check for mistakes.
> Runtime: `@objectstack/cli` v2.0.1 (Kernel pattern) — `@objectql/server` deprecated, `packages/runtime/` removed.
> @objectstack Platform: **v2.0.1** (upgraded from v2.0.0 — maintenance & stability patch)
> Runtime: `@objectstack/cli` v2.0.6 (Kernel pattern) — `@objectql/server` deprecated, `packages/runtime/` removed.
> @objectstack Platform: **v2.0.6**

---

Expand Down Expand Up @@ -429,7 +429,9 @@ Standardize third-party plugin distribution.
| Package | NPM Name | Environment | Description |
|---------|----------|-------------|-------------|
| `packages/foundation/types` | `@objectql/types` | Universal | **The Constitution.** Protocol-derived TypeScript types. Zero runtime deps. |
| `packages/foundation/core` | `@objectql/core` | Universal | **The Engine.** QueryBuilder, QueryCompiler, Repository, HookManager. No Node.js natives. |
| `packages/foundation/core` | `@objectql/core` | Universal | **The Engine.** Plugin orchestrator, repository pattern, and kernel factory. Delegates query and optimization logic to dedicated plugins. |
| `packages/foundation/plugin-query` | `@objectql/plugin-query` | Universal | **🆕 PR #373.** QueryService, QueryBuilder, QueryAnalyzer, FilterTranslator. Extracted from `@objectql/core`. |
| `packages/foundation/plugin-optimizations` | `@objectql/plugin-optimizations` | Universal | **🆕 PR #373.** Connection pooling, query compilation, compiled hooks, lazy metadata loading, SQL query optimization. Extracted from `@objectql/core`. |
| `packages/foundation/platform-node` | `@objectql/platform-node` | Node.js | File system integration, YAML loading, glob-based plugin discovery. |
| `packages/foundation/plugin-security` | `@objectql/plugin-security` | Universal | RBAC, Field-Level Security, Row-Level Security with AST-level enforcement. |
| `packages/foundation/plugin-validator` | `@objectql/plugin-validator` | Universal | 5-type validation engine: field, cross-field, state_machine, unique, business_rule. |
Expand Down Expand Up @@ -472,12 +474,12 @@ Standardize third-party plugin distribution.

| Package | Owner | Version | Role in ObjectQL |
|---------|-------|---------|-----------------|
| `@objectstack/cli` | ObjectStack | 2.0.1 | Kernel bootstrapper (`objectstack serve`) |
| `@objectstack/core` | ObjectStack | 2.0.1 | Kernel runtime, plugin lifecycle |
| `@objectstack/plugin-hono-server` | ObjectStack | 2.0.1 | HTTP server (Hono-based) |
| `@objectstack/spec` | ObjectStack | 2.0.1 | Formal protocol specifications (Zod schemas) |
| `@objectstack/runtime` | ObjectStack | 2.0.1 | Core runtime & query engine |
| `@objectstack/objectql` | ObjectStack | 2.0.1 | ObjectQL runtime bridge |
| `@objectstack/cli` | ObjectStack | 2.0.6 | Kernel bootstrapper (`objectstack serve`) |
| `@objectstack/core` | ObjectStack | 2.0.6 | Kernel runtime, plugin lifecycle |
| `@objectstack/plugin-hono-server` | ObjectStack | 2.0.6 | HTTP server (Hono-based) |
| `@objectstack/spec` | ObjectStack | 2.0.6 | Formal protocol specifications (Zod schemas) |
| `@objectstack/runtime` | ObjectStack | 2.0.6 | Core runtime & query engine |
| `@objectstack/objectql` | ObjectStack | 2.0.6 | ObjectQL runtime bridge |
| AI Agent / AI tooling | **Separate project** | — | Not in this monorepo |

---
Expand Down
10 changes: 10 additions & 0 deletions tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,15 @@
"references": [
// Foundation Layer
{ "path": "./packages/foundation/types" },
{ "path": "./packages/foundation/plugin-query" },
{ "path": "./packages/foundation/plugin-optimizations" },
{ "path": "./packages/foundation/plugin-validator" },
{ "path": "./packages/foundation/plugin-formula" },
{ "path": "./packages/foundation/plugin-security" },
{ "path": "./packages/foundation/plugin-multitenancy" },
{ "path": "./packages/foundation/plugin-workflow" },
{ "path": "./packages/foundation/plugin-sync" },
{ "path": "./packages/foundation/edge-adapter" },
{ "path": "./packages/foundation/core" },
{ "path": "./packages/foundation/platform-node" },

Expand All @@ -17,16 +23,20 @@
{ "path": "./packages/drivers/fs" },
{ "path": "./packages/drivers/redis" },
{ "path": "./packages/drivers/excel" },
{ "path": "./packages/drivers/sqlite-wasm" },
{ "path": "./packages/drivers/pg-wasm" },

// Protocols Layer
{ "path": "./packages/protocols/graphql" },
{ "path": "./packages/protocols/json-rpc" },
{ "path": "./packages/protocols/odata-v4" },
{ "path": "./packages/protocols/sync" },

// Tools Layer
{ "path": "./packages/tools/cli" },
{ "path": "./packages/tools/create" },
{ "path": "./packages/tools/driver-tck" },
{ "path": "./packages/tools/protocol-tck" },
{ "path": "./packages/tools/vscode-objectql" },

// Examples
Expand Down