Refactor plugin and metadata loading lifecycle

Reorganize the ObjectQL app initialization to defer package, source, and object loading until after plugins are set up, allowing plugins to register custom loaders and modify metadata before it is loaded. Update documentation to clarify the execution lifecycle and plugin capabilities, including dynamic package management.

Author: hotlong

docs/guide/plugins.md

@@ -23,7 +23,24 @@ export interface ObjectQLPlugin {
 }
 ```
 
-## 2. Creating Plugins
+## 2. Execution Lifecycle
+
+Understanding valid execution timing is critical.
+
+1.  **Phase 1: Construction (`new ObjectQL`)**
+    *   Load Metadata from `packages`.
+    *   Load Metadata from `source` directories (`*.object.yml`).
+    *   Load Metadata from `config.objects`.
+    *   **Result:** `app.metadata` holds all static definitions.
+
+2.  **Phase 2: Initialization (`await app.init()`)**
+    *   **Step A: Remotes:** Fetch metadata from remote services.
+    *   **Step B: Plugins (`plugin.setup`)**:  <-- **YOU ARE HERE**
+        *   This is the last chance to modify metadata before it touches the DB.
+        *   You can access all objects loaded in Phase 1 & Step A.
+    *   **Step C: Drivers:** Drivers connect and synchronize schema (create tables, etc.).
+
+## 3. Creating Plugins
 
 You can define plugins in two styles: **Object** or **Class**.
 
@@ -148,7 +165,7 @@ setup(app) {
 ```
 
 **Example 3: Scanning a Directory**
-Plugins can also scan a directory to load `*.object.yml` files, just like the main application. This is useful for bundling a set of objects.
+Plugins can also scan a directory to load metadata files, just like the main application. This is useful for bundling a set of objects.
 
 ```typescript
 import * as path from 'path';
@@ -211,6 +228,19 @@ setup(app) {
 }
 ```
 
+### E. Manage Packages (Presets)
+Plugins can dynamically load or unload other packages. This is useful for plugins that act as "features" which bring in a set of dependencies.
+
+```typescript
+setup(app) {
+    // Dynamically load another package
+    app.addPackage('@objectos/standard-objects');
+
+    // Or remove a package if it conflicts with this plugin
+    app.removePackage('@objectos/legacy-objects');
+}
+```
+
 ## 5. Scope Isolation
 
 

packages/core/src/app.ts

@@ -31,8 +31,12 @@ export class ObjectQL implements IObjectQL {
     private hooks: Record<string, HookEntry[]> = {};
     private actions: Record<string, ActionEntry> = {};
     private pluginsList: ObjectQLPlugin[] = [];
+    
+    // Store config for lazy loading in init()
+    private config: ObjectQLConfig;
 
     constructor(config: ObjectQLConfig) {
+        this.config = config;
         this.metadata = config.registry || new MetadataRegistry();
         this.loader = new ObjectLoader(this.metadata);
         this.datasources = config.datasources || {};
@@ -42,18 +46,7 @@ export class ObjectQL implements IObjectQL {
             this.datasources['default'] = createDriverFromConnection(config.connection);
         }
 
-        // 1. Load Presets/Packages first (Base Layer)
-        if (config.packages) {
-            for (const name of config.packages) {
-                this.addPackage(name);
-            }
-        }
-        if (config.presets) {
-            for (const name of config.presets) {
-                this.addPackage(name);
-            }
-        }
-        
+        // Initialize Plugin List (but don't setup yet)
         if (config.plugins) {
             for (const plugin of config.plugins) {
                 if (typeof plugin === 'string') {
@@ -63,21 +56,6 @@ export class ObjectQL implements IObjectQL {
                 }
             }
         }
-
-        // 2. Load Local Sources (Application Layer - can override presets)
-        if (config.source) {
-            const sources = Array.isArray(config.source) ? config.source : [config.source];
-            for (const src of sources) {
-                this.loader.load(src);
-            }
-        }
-
-        // 3. Load In-Memory Objects (Dynamic Layer - highest priority)
-        if (config.objects) {
-            for (const [key, obj] of Object.entries(config.objects)) {
-                this.registerObject(obj);
-            }
-        }
     }
 
     addPackage(name: string) {
@@ -197,21 +175,7 @@ export class ObjectQL implements IObjectQL {
     }
 
     async init() {
-        // -1. Load Remotes
-        if (this.remotes.length > 0) {
-            console.log(`Loading ${this.remotes.length} remotes...`);
-            const results = await Promise.all(this.remotes.map(url => loadRemoteFromUrl(url)));
-            for (const res of results) {
-                if (res) {
-                    this.datasources[res.driverName] = res.driver;
-                    for (const obj of res.objects) {
-                        this.registerObject(obj);
-                    }
-                }
-            }
-        }
-
-        // 0. Init Plugins
+        // 0. Init Plugins (This allows plugins to register custom loaders)
         for (const plugin of this.pluginsList) {
             console.log(`Initializing plugin '${plugin.name}'...`);
 
@@ -238,9 +202,50 @@ export class ObjectQL implements IObjectQL {
             await plugin.setup(app);
         }
 
+        // 1. Load Presets/Packages (Base Layer) - AFTER plugins, so they can use new loaders
+        if (this.config.packages) {
+            for (const name of this.config.packages) {
+                this.addPackage(name);
+            }
+        }
+        if (this.config.presets) {
+            for (const name of this.config.presets) {
+                this.addPackage(name);
+            }
+        }
+
+        // 2. Load Local Sources (Application Layer)
+        if (this.config.source) {
+            const sources = Array.isArray(this.config.source) ? this.config.source : [this.config.source];
+            for (const src of sources) {
+                this.loader.load(src);
+            }
+        }
+
+        // 3. Load In-Memory Objects (Dynamic Layer)
+        if (this.config.objects) {
+            for (const [key, obj] of Object.entries(this.config.objects)) {
+                this.registerObject(obj);
+            }
+        }
+
+        // 4. Load Remotes
+        if (this.remotes.length > 0) {
+            console.log(`Loading ${this.remotes.length} remotes...`);
+            const results = await Promise.all(this.remotes.map(url => loadRemoteFromUrl(url)));
+            for (const res of results) {
+                if (res) {
+                    this.datasources[res.driverName] = res.driver;
+                    for (const obj of res.objects) {
+                        this.registerObject(obj);
+                    }
+                }
+            }
+        }
+
         const objects = this.metadata.list<ObjectConfig>('object');
 
-        // 1. Init Drivers (e.g. Sync Schema)
+        // 5. Init Drivers (e.g. Sync Schema)
         // Let's pass all objects to all configured drivers.
         for (const [name, driver] of Object.entries(this.datasources)) {
             if (driver.init) {