From b2c0ab152095ebecafed89d856432ae3d0edba3d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 30 Jul 2026 19:36:34 +0000 Subject: [PATCH] fix(objectql)!: retire the dead ObjectQLEngine.use() plugin path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The engine's own plugin loader — registerApp + an onEnable dispatch over an ObjectQLHostContext — has zero callers repo-wide: kernel plugins go through kernel.use() → init/start, and the manifest path routes through registerApp() directly. The onEnable dispatch is the engine-level twin of the #4212 disease (a lifecycle entry point that reads as a contract and never runs); the app-bundle onEnable module export is a different, real contract and is unchanged. Removed use(), the ObjectQLHostContext type (constructed only inside the dead method; un-exported from both barrels), and the write-only hostContext field — the constructor keeps its signature and its logger extraction, so new ObjectQL({ logger }) and ObjectQLPlugin's hostContext option are unaffected. Verified: objectql 1271 tests green (82 files) after a full turbo build (71 packages) with the change in place; the 42 pre-existing local failures reproduced identically on pristine main with the change stashed and disappeared after rebuilding stale sibling dists — unrelated to this diff. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh --- .changeset/objectql-dead-use-retired.md | 34 +++++++++++++++++ packages/objectql/src/core.ts | 2 +- packages/objectql/src/engine.ts | 50 ------------------------- packages/objectql/src/index.ts | 2 +- 4 files changed, 36 insertions(+), 52 deletions(-) create mode 100644 .changeset/objectql-dead-use-retired.md diff --git a/.changeset/objectql-dead-use-retired.md b/.changeset/objectql-dead-use-retired.md new file mode 100644 index 0000000000..1eafe3629c --- /dev/null +++ b/.changeset/objectql-dead-use-retired.md @@ -0,0 +1,34 @@ +--- +"@objectstack/objectql": major +--- + +fix(objectql)!: retire the dead `ObjectQLEngine.use()` plugin path (#4212 follow-up) + +`ObjectQLEngine.use(manifestPart, runtimePart)` was the engine's own plugin +loader: register a manifest, then dispatch the runtime part's `onEnable` with +an `ObjectQLHostContext`. **Nothing calls it** — not the kernel (plugins go +through `kernel.use()` → `init`/`start`), not the CLI, not a test, not an +example, repo-wide. Its `onEnable` dispatch is the engine-level twin of the +#4212 disease: a lifecycle entry point that reads as a contract and never +runs. The *app-bundle* `onEnable` module export is a different, real contract +(dispatched by AppPlugin at boot) and is unchanged. + +Removed: + +- `ObjectQLEngine.use()`. +- `ObjectQLHostContext` (exported from `@objectstack/objectql` and + `@objectstack/objectql/core`) — constructed only inside the dead method. +- The engine's private `hostContext` field — its only read outside the dead + method was the constructor's `logger` extraction, which stays; the + constructor signature is unchanged (`new ObjectQL({ logger })` keeps + working, as does `ObjectQLPlugin`'s `hostContext` option that feeds it). + +FROM → TO: + +- `engine.use(manifest)` → `engine.registerApp(manifest)` (the alive half — + the manifest service and ObjectQLPlugin already route through it). +- `engine.use(_, { onEnable })` → a kernel plugin: `kernel.use({ name, + init(ctx) { … } })`; the engine is `ctx.getService('objectql')`, drivers + register via `engine.registerDriver()`. +- `ObjectQLHostContext` → no replacement; the type described the context of + a hook that never fired. diff --git a/packages/objectql/src/core.ts b/packages/objectql/src/core.ts index 81a447169f..e188b8bfec 100644 --- a/packages/objectql/src/core.ts +++ b/packages/objectql/src/core.ts @@ -37,7 +37,7 @@ export type { CompanionFieldMeta, CompanionObjectMeta } from './search-companion // Engine export { ObjectQL, ObjectRepository, ScopedContext } from './engine.js'; -export type { ObjectQLHostContext, HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js'; +export type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js'; // Boot guard: thrown by `ObjectQL.init()` when a registered driver's connect() // fails (framework#3741). Embedders that boot the engine themselves can catch diff --git a/packages/objectql/src/engine.ts b/packages/objectql/src/engine.ts index 407362a2bb..2ddd1a97df 100644 --- a/packages/objectql/src/engine.ts +++ b/packages/objectql/src/engine.ts @@ -263,16 +263,6 @@ export type EngineMiddleware = ( next: () => Promise ) => Promise; -/** - * Host Context provided to plugins (Internal ObjectQL Plugin System) - */ -export interface ObjectQLHostContext { - ql: ObjectQL; - logger: Logger; - // Extensible map for host-specific globals (like HTTP Router, etc.) - [key: string]: any; -} - /** * Derive the registry key for a metadata item. * @@ -392,9 +382,6 @@ export class ObjectQL implements IDataEngine { // `engine.registerFunction(...)`. private functions = new Map(); - // Host provided context additions (e.g. Server router) - private hostContext: Record = {}; - // Realtime service for event publishing private realtimeService?: IRealtimeService; @@ -423,7 +410,6 @@ export class ObjectQL implements IDataEngine { private _registry: SchemaRegistry = new SchemaRegistry(); constructor(hostContext: Record = {}) { - this.hostContext = hostContext; // Use provided logger or create a new one this.logger = hostContext.logger || createLogger({ level: 'info', format: 'pretty' }); // Pick up production hardening switches from env so deployers can @@ -462,42 +448,6 @@ export class ObjectQL implements IDataEngine { return this._registry; } - /** - * Load and Register a Plugin - */ - async use(manifestPart: any, runtimePart?: any) { - this.logger.debug('Loading plugin', { - hasManifest: !!manifestPart, - hasRuntime: !!runtimePart - }); - - // 1. Validate / Register Manifest - if (manifestPart) { - this.registerApp(manifestPart); - } - - // 2. Execute Runtime - if (runtimePart) { - const pluginDef = (runtimePart as any).default || runtimePart; - if (pluginDef.onEnable) { - this.logger.debug('Executing plugin runtime onEnable'); - - const context: ObjectQLHostContext = { - ql: this, - logger: this.logger, - // Expose the driver registry helper explicitly if needed - drivers: { - register: (driver: IDataDriver) => this.registerDriver(driver) - }, - ...this.hostContext - }; - - await pluginDef.onEnable(context); - this.logger.debug('Plugin runtime onEnable completed'); - } - } - } - /** * Register a hook * @param event The event name (e.g. 'beforeFind', 'afterInsert') diff --git a/packages/objectql/src/index.ts b/packages/objectql/src/index.ts index f3cac898e4..d2aef705e8 100644 --- a/packages/objectql/src/index.ts +++ b/packages/objectql/src/index.ts @@ -47,7 +47,7 @@ export type { CompanionFieldMeta, CompanionObjectMeta } from './search-companion // Export Engine export { ObjectQL, ObjectRepository, ScopedContext } from './engine.js'; -export type { ObjectQLHostContext, HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js'; +export type { HookHandler, HookEntry, OperationContext, EngineMiddleware } from './engine.js'; export { SummaryRecomputeError } from './summary-errors.js'; export type { SummaryRecomputeFailure } from './summary-errors.js'; // Boot guard: thrown by `ObjectQL.init()` when a registered driver's connect()