@objectstack/runtime 0.4.2 → 0.6.0

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@objectstack/runtime",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "ObjectStack Core Runtime & Query Engine",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/objectql": "0.4.2",
-    "@objectstack/types": "0.4.2",
-    "@objectstack/spec": "0.4.2"
+    "@objectstack/core": "0.6.0",
+    "@objectstack/objectql": "0.6.0",
+    "@objectstack/types": "0.6.0",
+    "@objectstack/spec": "0.6.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0"

package/src/app-manifest-plugin.ts

@@ -0,0 +1,48 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * AppManifestPlugin
+ * 
+ * Adapts a static Manifest JSON into a dynamic Kernel Service.
+ * This allows the ObjectQL Engine to "discover" this app during its start phase.
+ * 
+ * Flow:
+ * 1. AppPlugin registers `app.<id>` service (init phase)
+ * 2. ObjectQL Engine discovers `app.*` services (start phase)
+ */
+export class AppManifestPlugin implements Plugin {
+    name: string;
+    version?: string;
+    
+    // Dependencies removed: This plugin produces data. It doesn't need to consume the engine to register itself.
+    // Making it dependency-free allows it to initialize BEFORE the engine if needed.
+    
+    private manifest: any;
+
+    constructor(manifest: any) {
+        this.manifest = manifest;
+        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
+        const sys = manifest.manifest || manifest;
+        const appId = sys.id || sys.name || 'unnamed-app';
+        
+        this.name = `plugin.app.${appId}`; // Unique plugin name
+        this.version = sys.version;
+    }
+
+    async init(ctx: PluginContext) {
+        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
+        const sys = this.manifest.manifest || this.manifest;
+        const appId = sys.id || sys.name;
+
+        ctx.logger.log(`[AppManifestPlugin] Registering App Service: ${appId}`);
+        
+        // Register the app manifest as a service
+        const serviceName = `app.${appId}`;
+        ctx.registerService(serviceName, this.manifest);
+    }
+
+    async start(ctx: PluginContext) {
+        // No logic needed here. 
+        // Logic is inverted: The Engine will pull data from this service.
+    }
+}

package/src/driver-plugin.ts

@@ -0,0 +1,40 @@
+import { Plugin, PluginContext } from '@objectstack/core';
+
+/**
+ * Driver Plugin
+ * 
+ * Generic plugin wrapper for ObjectQL drivers.
+ * Registers a driver with the ObjectQL engine.
+ * 
+ * Dependencies: None (Registers service for ObjectQL to discover)
+ * Services: driver.{name}
+ * 
+ * @example
+ * const memoryDriver = new InMemoryDriver();
+ * const driverPlugin = new DriverPlugin(memoryDriver, 'memory');
+ * kernel.use(driverPlugin);
+ */
+export class DriverPlugin implements Plugin {
+    name: string;
+    version = '1.0.0';
+    // dependencies = ['com.objectstack.engine.objectql']; // Removed: Driver is a producer, not strictly a consumer during init
+
+    private driver: any;
+
+    constructor(driver: any, driverName?: string) {
+        this.driver = driver;
+        this.name = `com.objectstack.driver.${driverName || driver.name || 'unknown'}`;
+    }
+
+    async init(ctx: PluginContext) {
+        // Register driver as a service instead of directly to objectql
+        const serviceName = `driver.${this.driver.name || 'unknown'}`;
+        ctx.registerService(serviceName, this.driver);
+        ctx.logger.log(`[DriverPlugin] Registered driver service: ${serviceName}`);
+    }
+
+    async start(ctx: PluginContext) {
+        // Drivers don't need start phase, initialization happens in init
+        ctx.logger.log(`[DriverPlugin] Driver ready: ${this.driver.name || 'unknown'}`);
+    }
+}

package/src/index.ts

@@ -1,8 +1,15 @@
 // Export core engine
-export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
-export { ObjectStackKernel } from './kernel';
-export { ObjectQLPlugin } from './objectql-plugin';
-export { ObjectStackRuntimeProtocol } from './protocol';
+export { ObjectQL, SchemaRegistry, ObjectStackProtocolImplementation } from '@objectstack/objectql';
+
+// Export Kernels
+export { ObjectKernel } from '@objectstack/core';
+
+// Export Plugins
+export { ObjectQLPlugin } from '@objectstack/objectql';
+export { DriverPlugin } from './driver-plugin';
+export { AppManifestPlugin } from './app-manifest-plugin';
+
+// Export Types
+export * from '@objectstack/core';
 
-export * from './types';
 

package/src/test-interfaces.ts

@@ -0,0 +1,170 @@
+/**
+ * Test file to verify capability contract interfaces
+ * 
+ * This file demonstrates how plugins can implement the IHttpServer
+ * and IDataEngine interfaces without depending on concrete implementations.
+ */
+
+import { IHttpServer, IDataEngine, RouteHandler, IHttpRequest, IHttpResponse, Middleware, DataEngineQueryOptions } from './index.js';
+
+/**
+ * Example: Mock HTTP Server Plugin
+ * 
+ * Shows how a plugin can implement the IHttpServer interface
+ * without depending on Express, Fastify, or any specific framework.
+ */
+class MockHttpServer implements IHttpServer {
+    private routes: Map<string, { method: string; handler: RouteHandler }> = new Map();
+    
+    get(path: string, handler: RouteHandler): void {
+        this.routes.set(`GET:${path}`, { method: 'GET', handler });
+        console.log(`✅ Registered GET ${path}`);
+    }
+    
+    post(path: string, handler: RouteHandler): void {
+        this.routes.set(`POST:${path}`, { method: 'POST', handler });
+        console.log(`✅ Registered POST ${path}`);
+    }
+    
+    put(path: string, handler: RouteHandler): void {
+        this.routes.set(`PUT:${path}`, { method: 'PUT', handler });
+        console.log(`✅ Registered PUT ${path}`);
+    }
+    
+    delete(path: string, handler: RouteHandler): void {
+        this.routes.set(`DELETE:${path}`, { method: 'DELETE', handler });
+        console.log(`✅ Registered DELETE ${path}`);
+    }
+    
+    patch(path: string, handler: RouteHandler): void {
+        this.routes.set(`PATCH:${path}`, { method: 'PATCH', handler });
+        console.log(`✅ Registered PATCH ${path}`);
+    }
+    
+    use(path: string | Middleware, handler?: Middleware): void {
+        console.log(`✅ Registered middleware`);
+    }
+    
+    async listen(port: number): Promise<void> {
+        console.log(`✅ Mock HTTP server listening on port ${port}`);
+    }
+    
+    async close(): Promise<void> {
+        console.log(`✅ Mock HTTP server closed`);
+    }
+}
+
+/**
+ * Example: Mock Data Engine Plugin
+ * 
+ * Shows how a plugin can implement the IDataEngine interface
+ * without depending on ObjectQL, Prisma, or any specific database.
+ */
+class MockDataEngine implements IDataEngine {
+    private store: Map<string, Map<string, any>> = new Map();
+    private idCounter = 0;
+    
+    async insert(objectName: string, data: any): Promise<any> {
+        if (!this.store.has(objectName)) {
+            this.store.set(objectName, new Map());
+        }
+        
+        const id = `${objectName}_${++this.idCounter}`;
+        const record = { id, ...data };
+        this.store.get(objectName)!.set(id, record);
+        
+        console.log(`✅ Inserted into ${objectName}:`, record);
+        return record;
+    }
+    
+    async find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]> {
+        const objectStore = this.store.get(objectName);
+        if (!objectStore) {
+            return [];
+        }
+        
+        const results = Array.from(objectStore.values());
+        console.log(`✅ Found ${results.length} records in ${objectName}`);
+        return results;
+    }
+    
+    async update(objectName: string, id: any, data: any): Promise<any> {
+        const objectStore = this.store.get(objectName);
+        if (!objectStore || !objectStore.has(id)) {
+            throw new Error(`Record ${id} not found in ${objectName}`);
+        }
+        
+        const existing = objectStore.get(id);
+        const updated = { ...existing, ...data };
+        objectStore.set(id, updated);
+        
+        console.log(`✅ Updated ${objectName}/${id}:`, updated);
+        return updated;
+    }
+    
+    async delete(objectName: string, id: any): Promise<boolean> {
+        const objectStore = this.store.get(objectName);
+        if (!objectStore) {
+            return false;
+        }
+        
+        const deleted = objectStore.delete(id);
+        console.log(`✅ Deleted ${objectName}/${id}: ${deleted}`);
+        return deleted;
+    }
+}
+
+/**
+ * Test the interfaces
+ */
+async function testInterfaces() {
+    console.log('\n=== Testing IHttpServer Interface ===\n');
+    
+    const httpServer: IHttpServer = new MockHttpServer();
+    
+    // Register routes using the interface
+    httpServer.get('/api/users', async (req, res) => {
+        res.json({ users: [] });
+    });
+    
+    httpServer.post('/api/users', async (req, res) => {
+        res.status(201).json({ id: 1, ...req.body });
+    });
+    
+    await httpServer.listen(3000);
+    
+    console.log('\n=== Testing IDataEngine Interface ===\n');
+    
+    const dataEngine: IDataEngine = new MockDataEngine();
+    
+    // Use the data engine interface
+    const user1 = await dataEngine.insert('user', {
+        name: 'John Doe',
+        email: 'john@example.com'
+    });
+    
+    const user2 = await dataEngine.insert('user', {
+        name: 'Jane Smith',
+        email: 'jane@example.com'
+    });
+    
+    const users = await dataEngine.find('user');
+    console.log(`Found ${users.length} users after inserts`);
+    
+    const updatedUser = await dataEngine.update('user', user1.id, {
+        name: 'John Updated'
+    });
+    console.log(`Updated user:`, updatedUser);
+    
+    const deleted = await dataEngine.delete('user', user2.id);
+    console.log(`Delete result: ${deleted}`);
+    
+    console.log('\n✅ All interface tests passed!\n');
+    
+    if (httpServer.close) {
+        await httpServer.close();
+    }
+}
+
+// Run tests
+testInterfaces().catch(console.error);

package/dist/kernel.d.ts

@@ -1,147 +0,0 @@
-import { ObjectQL } from '@objectstack/objectql';
-/**
- * ObjectStack Kernel (Microkernel)
- *
- * The central container orchestrating the application lifecycle,
- * plugins, and the core ObjectQL engine.
- */
-export declare class ObjectStackKernel {
-    ql?: ObjectQL;
-    private plugins;
-    constructor(plugins?: any[]);
-    /**
-     * Ensure ObjectQL engine is initialized
-     * @throws Error if ObjectQL is not available
-     */
-    private ensureObjectQL;
-    start(): Promise<void>;
-    seed(): Promise<void>;
-    find(objectName: string, query: any): Promise<{
-        value: any;
-        count: any;
-    }>;
-    get(objectName: string, id: string): Promise<any>;
-    create(objectName: string, data: any): Promise<any>;
-    update(objectName: string, id: string, data: any): Promise<any>;
-    delete(objectName: string, id: string): Promise<any>;
-    getMetadata(objectName: string): {
-        fields: Record<string, {
-            type: "number" | "boolean" | "code" | "date" | "text" | "textarea" | "email" | "url" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "file" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "json" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector";
-            required: boolean;
-            searchable: boolean;
-            multiple: boolean;
-            unique: boolean;
-            deleteBehavior: "set_null" | "cascade" | "restrict";
-            hidden: boolean;
-            readonly: boolean;
-            encryption: boolean;
-            index: boolean;
-            externalId: boolean;
-            options?: {
-                value: string;
-                label: string;
-                color?: string | undefined;
-                default?: boolean | undefined;
-            }[] | undefined;
-            min?: number | undefined;
-            max?: number | undefined;
-            formula?: string | undefined;
-            label?: string | undefined;
-            precision?: number | undefined;
-            name?: string | undefined;
-            description?: string | undefined;
-            format?: string | undefined;
-            defaultValue?: any;
-            maxLength?: number | undefined;
-            minLength?: number | undefined;
-            scale?: number | undefined;
-            reference?: string | undefined;
-            referenceFilters?: string[] | undefined;
-            writeRequiresMasterRead?: boolean | undefined;
-            expression?: string | undefined;
-            summaryOperations?: {
-                object: string;
-                function: "count" | "sum" | "avg" | "min" | "max";
-                field: string;
-            } | undefined;
-            language?: string | undefined;
-            theme?: string | undefined;
-            lineNumbers?: boolean | undefined;
-            maxRating?: number | undefined;
-            allowHalf?: boolean | undefined;
-            displayMap?: boolean | undefined;
-            allowGeocoding?: boolean | undefined;
-            addressFormat?: "us" | "uk" | "international" | undefined;
-            colorFormat?: "hex" | "rgb" | "rgba" | "hsl" | undefined;
-            allowAlpha?: boolean | undefined;
-            presetColors?: string[] | undefined;
-            step?: number | undefined;
-            showValue?: boolean | undefined;
-            marks?: Record<string, string> | undefined;
-            barcodeFormat?: "qr" | "ean13" | "ean8" | "code128" | "code39" | "upca" | "upce" | undefined;
-            qrErrorCorrection?: "L" | "M" | "Q" | "H" | undefined;
-            displayValue?: boolean | undefined;
-            allowScanning?: boolean | undefined;
-            currencyConfig?: {
-                precision: number;
-                currencyMode: "dynamic" | "fixed";
-                defaultCurrency: string;
-            } | undefined;
-            vectorConfig?: {
-                dimensions: number;
-                distanceMetric: "cosine" | "euclidean" | "dotProduct" | "manhattan";
-                normalized: boolean;
-                indexed: boolean;
-                indexType?: "flat" | "hnsw" | "ivfflat" | undefined;
-            } | undefined;
-        }>;
-        name: string;
-        active: boolean;
-        isSystem: boolean;
-        abstract: boolean;
-        datasource: string;
-        tags?: string[] | undefined;
-        label?: string | undefined;
-        description?: string | undefined;
-        search?: {
-            fields: string[];
-            displayFields?: string[] | undefined;
-            filters?: string[] | undefined;
-        } | undefined;
-        pluralLabel?: string | undefined;
-        icon?: string | undefined;
-        tableName?: string | undefined;
-        indexes?: {
-            fields: string[];
-            type?: "hash" | "btree" | "gin" | "gist" | undefined;
-            name?: string | undefined;
-            unique?: boolean | undefined;
-        }[] | undefined;
-        validations?: any[] | undefined;
-        titleFormat?: string | undefined;
-        compactLayout?: string[] | undefined;
-        enable?: {
-            searchable: boolean;
-            trackHistory: boolean;
-            apiEnabled: boolean;
-            files: boolean;
-            feeds: boolean;
-            activities: boolean;
-            trash: boolean;
-            mru: boolean;
-            clone: boolean;
-            apiMethods?: ("update" | "delete" | "get" | "list" | "create" | "upsert" | "bulk" | "aggregate" | "history" | "search" | "restore" | "purge" | "import" | "export")[] | undefined;
-        } | undefined;
-    };
-    getView(objectName: string, viewType?: 'list' | 'form'): {
-        type: string;
-        title: string;
-        columns: {
-            field: string;
-            label: string;
-            width: number;
-        }[];
-        actions: string[];
-    } | null;
-    private ensureSchema;
-}

package/dist/kernel.js

@@ -1,173 +0,0 @@
-import { SchemaRegistry, ObjectQL } from '@objectstack/objectql';
-/**
- * ObjectStack Kernel (Microkernel)
- *
- * The central container orchestrating the application lifecycle,
- * plugins, and the core ObjectQL engine.
- */
-export class ObjectStackKernel {
-    constructor(plugins = []) {
-        this.plugins = plugins;
-        // Check if any plugin provides ObjectQL via type: 'objectql'
-        // This aligns with the manifest schema that supports objectql as a package type
-        const hasObjectQLPlugin = plugins.some(p => p && typeof p === 'object' && p.type === 'objectql');
-        if (!hasObjectQLPlugin) {
-            // Backward compatibility: Initialize ObjectQL directly if no plugin provides it
-            console.warn('[Kernel] No ObjectQL plugin found, using default initialization. Consider using ObjectQLPlugin.');
-            this.ql = new ObjectQL({
-                env: process.env.NODE_ENV || 'development'
-            });
-        }
-    }
-    /**
-     * Ensure ObjectQL engine is initialized
-     * @throws Error if ObjectQL is not available
-     */
-    ensureObjectQL() {
-        if (!this.ql) {
-            throw new Error('[Kernel] ObjectQL engine not initialized. Ensure ObjectQLPlugin is registered or kernel is properly initialized.');
-        }
-        return this.ql;
-    }
-    async start() {
-        console.log('[Kernel] Starting...');
-        // 0. Register Provided Plugins
-        for (const p of this.plugins) {
-            // Check if it is a Runtime Plugin (System Capability)
-            if ('onStart' in p || 'install' in p) {
-                console.log(`[Kernel] Loading Runtime Plugin: ${p.name}`);
-                if (p.install)
-                    await p.install({ engine: this });
-                continue;
-            }
-            // Otherwise treat as App Manifest
-            console.log(`[Kernel] Loading App Manifest: ${p.id || p.name}`);
-            SchemaRegistry.registerPlugin(p);
-            // Register Objects from App/Plugin
-            if (p.objects) {
-                for (const obj of p.objects) {
-                    SchemaRegistry.registerObject(obj);
-                    console.log(`[Kernel] Registered Object: ${obj.name}`);
-                }
-            }
-        }
-        // 1. Load Drivers (Default to Memory if none provided in plugins)
-        // TODO: Detect driver from plugins. For now, we still hard load memory driver if needed?
-        // In strict mode, user should pass driver in plugins array (DriverManifest).
-        // check if driver is registered
-        // For Backwards Compat / Easy Dev, try dynamic import of memory driver if installed
-        try {
-            // @ts-ignore
-            const { InMemoryDriver } = await import('@objectstack/driver-memory');
-            const driver = new InMemoryDriver();
-            this.ensureObjectQL().registerDriver(driver);
-        }
-        catch (e) {
-            // Ignore if not present
-        }
-        // 2. Initialize Engine
-        await this.ensureObjectQL().init();
-        // 3. Seed Data
-        await this.seed();
-        // 4. Start Runtime Plugins
-        for (const p of this.plugins) {
-            if (('onStart' in p) && typeof p.onStart === 'function') {
-                console.log(`[Kernel] Starting Plugin: ${p.name}`);
-                await p.onStart({ engine: this });
-            }
-        }
-    }
-    async seed() {
-        // If no driver registered yet, this might fail or wait. 
-        // In real world, we wait for 'ready' event.
-        try {
-            // Mock System Table
-            try {
-                // We don't have SystemStatus defined in schema usually, skipping for general engine
-                // await this.ql.insert('SystemStatus', { status: 'OK', uptime: 0 });
-            }
-            catch { }
-            // Iterate over all registered plugins/apps and check for 'data' property in manifest
-            const plugins = SchemaRegistry.getRegisteredTypes(); // This returns types like 'plugin', 'app'
-            // This is a bit hacky because we don't have a direct "getAllManifests" API exposed easily
-            // We will iterate known apps for now, or improve Registry API later.
-            // Actually, SchemaRegistry.listItems('app') returns the manifests!
-            const apps = [...SchemaRegistry.listItems('app'), ...SchemaRegistry.listItems('plugin')];
-            for (const appItem of apps) {
-                const app = appItem; // Cast to access data prop safely
-                if (app.data && Array.isArray(app.data)) {
-                    console.log(`[Kernel] Seeding data for ${app.name || app.id}...`);
-                    for (const seed of app.data) {
-                        try {
-                            // Check if data exists
-                            const existing = await this.ensureObjectQL().find(seed.object, { top: 1 });
-                            if (existing.length === 0) {
-                                console.log(`[Kernel] Inserting ${seed.records.length} records into ${seed.object}`);
-                                for (const record of seed.records) {
-                                    await this.ensureObjectQL().insert(seed.object, record);
-                                }
-                            }
-                        }
-                        catch (e) {
-                            console.warn(`[Kernel] Failed to seed ${seed.object}`, e);
-                        }
-                    }
-                }
-            }
-        }
-        catch (e) {
-            console.warn('Seed failed (driver might not be ready):', e);
-        }
-    }
-    // Forward methods to ObjectQL
-    async find(objectName, query) {
-        this.ensureSchema(objectName);
-        const results = await this.ensureObjectQL().find(objectName, { top: 100 });
-        return { value: results, count: results.length };
-    }
-    async get(objectName, id) {
-        this.ensureSchema(objectName);
-        // Find One
-        const results = await this.ensureObjectQL().find(objectName, { top: 1 }); // Mock implementation
-        return results[0];
-    }
-    async create(objectName, data) {
-        this.ensureSchema(objectName);
-        return this.ensureObjectQL().insert(objectName, data);
-    }
-    async update(objectName, id, data) {
-        this.ensureSchema(objectName);
-        return this.ensureObjectQL().update(objectName, id, data);
-    }
-    async delete(objectName, id) {
-        this.ensureSchema(objectName);
-        return this.ensureObjectQL().delete(objectName, id);
-    }
-    // [New Methods for ObjectUI]
-    getMetadata(objectName) {
-        return this.ensureSchema(objectName);
-    }
-    getView(objectName, viewType = 'list') {
-        const schema = this.ensureSchema(objectName);
-        // Auto-Scaffold Default View
-        if (viewType === 'list') {
-            return {
-                type: 'datagrid',
-                title: `${schema.label || objectName} List`,
-                columns: Object.keys(schema.fields || {}).map(key => ({
-                    field: key,
-                    label: schema.fields?.[key]?.label || key,
-                    width: 150
-                })),
-                actions: ['create', 'edit', 'delete']
-            };
-        }
-        return null;
-    }
-    ensureSchema(name) {
-        const schema = SchemaRegistry.getObject(name);
-        if (!schema)
-            throw new Error(`Unknown object: ${name}`);
-        return schema;
-    }
-}

package/dist/objectql-plugin.d.ts

@@ -1,27 +0,0 @@
-import { ObjectQL } from '@objectstack/objectql';
-import { RuntimePlugin, RuntimeContext } from '@objectstack/types';
-/**
- * ObjectQL Engine Plugin
- *
- * Registers the ObjectQL engine instance with the kernel.
- * This allows users to provide their own ObjectQL implementation or configuration.
- *
- * Usage:
- * - new ObjectQLPlugin() - Creates new ObjectQL with default settings
- * - new ObjectQLPlugin(existingQL) - Uses existing ObjectQL instance
- * - new ObjectQLPlugin(undefined, { custom: 'context' }) - Creates new ObjectQL with custom context
- */
-export declare class ObjectQLPlugin implements RuntimePlugin {
-    name: string;
-    type: "objectql";
-    private ql;
-    /**
-     * @param ql - Existing ObjectQL instance to use (optional)
-     * @param hostContext - Host context for new ObjectQL instance (ignored if ql is provided)
-     */
-    constructor(ql?: ObjectQL, hostContext?: Record<string, any>);
-    /**
-     * Install the ObjectQL engine into the kernel
-     */
-    install(ctx: RuntimeContext): Promise<void>;
-}