@objectstack/runtime 4.0.4 → 4.1.0

package/src/app-plugin.test.ts

@@ -1,274 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { AppPlugin } from './app-plugin';
-import { PluginContext } from '@objectstack/core';
-
-describe('AppPlugin', () => {
-    let mockContext: PluginContext;
-
-    beforeEach(() => {
-        mockContext = {
-            logger: { 
-                info: vi.fn(), 
-                error: vi.fn(),
-                warn: vi.fn(),
-                debug: vi.fn()
-            },
-            registerService: vi.fn(),
-            getService: vi.fn(),
-            getServices: vi.fn()
-        } as unknown as PluginContext;
-    });
-
-    it('should initialize with manifest info', () => {
-        const bundle = {
-            id: 'com.test.app',
-            name: 'Test App',
-            version: '1.0.0'
-        };
-        const plugin = new AppPlugin(bundle);
-        expect(plugin.name).toBe('plugin.app.com.test.app');
-        expect(plugin.version).toBe('1.0.0');
-    });
-
-    it('should handle nested stack definition manifest', () => {
-        const bundle = {
-            manifest: {
-                id: 'com.test.stack',
-                version: '2.0.0'
-            },
-            objects: []
-        };
-        const plugin = new AppPlugin(bundle);
-        expect(plugin.name).toBe('plugin.app.com.test.stack');
-        expect(plugin.version).toBe('2.0.0');
-    });
-
-    it('registerService should register raw manifest in init phase', async () => {
-        const bundle = {
-            id: 'com.test.simple',
-            objects: []
-        };
-        const plugin = new AppPlugin(bundle);
-
-        // Mock the manifest service
-        const mockManifestService = { register: vi.fn() };
-        vi.mocked(mockContext.getService).mockReturnValue(mockManifestService);
-
-        await plugin.init(mockContext);
-
-        expect(mockContext.getService).toHaveBeenCalledWith('manifest');
-        expect(mockManifestService.register).toHaveBeenCalledWith(bundle);
-    });
-
-    it('start should do nothing if no runtime hooks', async () => {
-        const bundle = { id: 'com.test.static' };
-        const plugin = new AppPlugin(bundle);
-        
-        vi.mocked(mockContext.getService).mockReturnValue({}); // Mock ObjectQL exists
-        
-        await plugin.start!(mockContext);
-        // Only logs, no errors
-        expect(mockContext.logger.debug).toHaveBeenCalled();
-    });
-
-    it('start should invoke onEnable if present', async () => {
-        const onEnableSpy = vi.fn();
-        const bundle = { 
-            id: 'com.test.code',
-            onEnable: onEnableSpy
-        };
-        const plugin = new AppPlugin(bundle);
-        
-        // Mock ObjectQL engine
-        const mockQL = { registry: {} };
-        vi.mocked(mockContext.getService).mockReturnValue(mockQL);
-        
-        await plugin.start!(mockContext);
-        
-        expect(onEnableSpy).toHaveBeenCalled();
-        // Check context passed to onEnable
-        const callArg = onEnableSpy.mock.calls[0][0];
-        expect(callArg.ql).toBe(mockQL);
-    });
-
-    it('start should warn if objectql not found', async () => {
-        const bundle = { id: 'com.test.warn' };
-        const plugin = new AppPlugin(bundle);
-        
-        vi.mocked(mockContext.getService).mockReturnValue(undefined); // No ObjectQL
-        
-        await plugin.start!(mockContext);
-        
-        expect(mockContext.logger.warn).toHaveBeenCalledWith(
-            expect.stringContaining('ObjectQL engine service not found'), 
-            expect.any(Object)
-        );
-    });
-
-    it('start should handle getService throwing for objectql', async () => {
-        const bundle = { id: 'com.test.throw' };
-        const plugin = new AppPlugin(bundle);
-        
-        vi.mocked(mockContext.getService).mockImplementation(() => {
-            throw new Error("[Kernel] Service 'objectql' not found");
-        });
-        
-        await plugin.start!(mockContext);
-        
-        expect(mockContext.logger.warn).toHaveBeenCalledWith(
-            expect.stringContaining('ObjectQL engine service not found'), 
-            expect.any(Object)
-        );
-    });
-
-    // ═══════════════════════════════════════════════════════════════
-    // i18n translation auto-loading
-    // ═══════════════════════════════════════════════════════════════
-
-    describe('i18n translation loading', () => {
-        let mockI18n: any;
-        let mockQL: any;
-
-        beforeEach(() => {
-            mockI18n = {
-                loadTranslations: vi.fn(),
-                setDefaultLocale: vi.fn(),
-                getLocales: vi.fn().mockReturnValue([]),
-                getDefaultLocale: vi.fn().mockReturnValue('en'),
-            };
-            mockQL = { registry: {} };
-
-            vi.mocked(mockContext.getService).mockImplementation((name: string) => {
-                if (name === 'objectql') return mockQL;
-                if (name === 'i18n') return mockI18n;
-                return undefined;
-            });
-        });
-
-        it('should auto-load translations from bundle into i18n service', async () => {
-            const bundle = {
-                id: 'com.test.i18n',
-                translations: [
-                    {
-                        en: { objects: { task: { label: 'Task' } } },
-                        'zh-CN': { objects: { task: { label: '任务' } } },
-                    },
-                ],
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('en', { objects: { task: { label: 'Task' } } });
-            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('zh-CN', { objects: { task: { label: '任务' } } });
-        });
-
-        it('should set default locale from i18n config', async () => {
-            const bundle = {
-                id: 'com.test.locale',
-                i18n: { defaultLocale: 'zh-CN', supportedLocales: ['en', 'zh-CN'] },
-                translations: [{ en: { messages: { hello: 'Hello' } } }],
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            expect(mockI18n.setDefaultLocale).toHaveBeenCalledWith('zh-CN');
-        });
-
-        it('should skip translation loading when i18n service is not registered', async () => {
-            vi.mocked(mockContext.getService).mockImplementation((name: string) => {
-                if (name === 'objectql') return mockQL;
-                return undefined; // No i18n service
-            });
-
-            const bundle = {
-                id: 'com.test.noi18n',
-                translations: [{ en: { messages: { hello: 'Hello' } } }],
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            // Should log warning (translations exist but no i18n service) and not throw
-            expect(mockContext.logger.warn).toHaveBeenCalledWith(
-                expect.stringContaining('no i18n service is registered')
-            );
-        });
-
-        it('should skip translation loading when getService throws for i18n', async () => {
-            vi.mocked(mockContext.getService).mockImplementation((name: string) => {
-                if (name === 'objectql') return mockQL;
-                throw new Error("[Kernel] Service 'i18n' not found");
-            });
-
-            const bundle = {
-                id: 'com.test.i18nthrow',
-                translations: [{ en: { messages: { hello: 'Hello' } } }],
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            // Should log warning (translations exist but no i18n service) and not throw
-            expect(mockContext.logger.warn).toHaveBeenCalledWith(
-                expect.stringContaining('no i18n service is registered')
-            );
-        });
-
-        it('should handle bundle with no translations gracefully', async () => {
-            const bundle = { id: 'com.test.notrans' };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            expect(mockI18n.loadTranslations).not.toHaveBeenCalled();
-        });
-
-        it('should load translations from nested manifest.translations', async () => {
-            const bundle = {
-                manifest: {
-                    id: 'com.test.nested',
-                    translations: [
-                        { en: { messages: { save: 'Save' } } },
-                    ],
-                },
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('en', { messages: { save: 'Save' } });
-        });
-
-        it('should load multiple translation bundles', async () => {
-            const bundle = {
-                id: 'com.test.multi',
-                translations: [
-                    { en: { objects: { task: { label: 'Task' } } } },
-                    { en: { objects: { contact: { label: 'Contact' } } }, 'ja-JP': { objects: { contact: { label: '連絡先' } } } },
-                ],
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            expect(mockI18n.loadTranslations).toHaveBeenCalledTimes(3);
-        });
-
-        it('should handle errors in loadTranslations gracefully', async () => {
-            mockI18n.loadTranslations.mockImplementation((locale: string) => {
-                if (locale === 'zh-CN') throw new Error('Disk read failed');
-            });
-
-            const bundle = {
-                id: 'com.test.error',
-                translations: [
-                    { en: { messages: { save: 'Save' } }, 'zh-CN': { messages: { save: '保存' } } },
-                ],
-            };
-            const plugin = new AppPlugin(bundle);
-            await plugin.start!(mockContext);
-
-            // en should still be loaded despite zh-CN failure
-            expect(mockI18n.loadTranslations).toHaveBeenCalledWith('en', { messages: { save: 'Save' } });
-            expect(mockContext.logger.warn).toHaveBeenCalledWith(
-                expect.stringContaining('Failed to load translations'),
-                expect.objectContaining({ locale: 'zh-CN' })
-            );
-        });
-    });
-});

package/src/app-plugin.ts

@@ -1,285 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import { Plugin, PluginContext } from '@objectstack/core';
-import { SeedLoaderService } from './seed-loader.js';
-import type { IMetadataService, II18nService } from '@objectstack/spec/contracts';
-
-/**
- * AppPlugin
- * 
- * Adapts a generic App Bundle (Manifest + Runtime Code) into a Kernel Plugin.
- * 
- * Responsibilities:
- * 1. Register App Manifest as a service (for ObjectQL discovery)
- * 2. Execute Runtime `onEnable` hook (for code logic)
- * 3. Auto-load i18n translation bundles into the kernel's i18n service
- */
-export class AppPlugin implements Plugin {
-    name: string;
-    type = 'app';
-    version?: string;
-    
-    private bundle: any;
-
-    constructor(bundle: any) {
-        this.bundle = bundle;
-        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
-        const sys = bundle.manifest || bundle;
-        const appId = sys.id || sys.name || 'unnamed-app';
-        
-        this.name = `plugin.app.${appId}`;
-        this.version = sys.version;
-    }
-
-    init = async (ctx: PluginContext) => {
-        const sys = this.bundle.manifest || this.bundle;
-        const appId = sys.id || sys.name;
-
-        ctx.logger.info('Registering App Service', { 
-            appId, 
-            pluginName: this.name,
-            version: this.version 
-        });
-        
-        // Register the app manifest directly via the manifest service.
-        // This immediately decomposes the manifest into SchemaRegistry entries.
-        const servicePayload = this.bundle.manifest
-            ? { ...this.bundle.manifest, ...this.bundle }
-            : this.bundle;
-
-        ctx.getService<{ register(m: any): void }>('manifest').register(servicePayload);
-    }
-
-    start = async (ctx: PluginContext) => {
-        const sys = this.bundle.manifest || this.bundle;
-        const appId = sys.id || sys.name;
-        
-        // Execute Runtime Step
-        // Retrieve ObjectQL engine from services
-        // ctx.getService throws when a service is not registered, so we
-        // must use try/catch instead of a null-check.
-        let ql: any;
-        try {
-            ql = ctx.getService('objectql');
-        } catch {
-            // Service not registered — handled below
-        }
-
-        if (!ql) {
-            ctx.logger.warn('ObjectQL engine service not found', { 
-                appName: this.name,
-                appId 
-            });
-            return;
-        }
-
-        ctx.logger.debug('Retrieved ObjectQL engine service', { appId });
-
-        // Configure datasourceMapping if provided in the stack definition
-        if (this.bundle.datasourceMapping && Array.isArray(this.bundle.datasourceMapping)) {
-            ctx.logger.info('Configuring datasource mapping rules', {
-                appId,
-                ruleCount: this.bundle.datasourceMapping.length
-            });
-            ql.setDatasourceMapping(this.bundle.datasourceMapping);
-        }
-
-        const runtime = this.bundle.default || this.bundle;
-        
-        if (runtime && typeof runtime.onEnable === 'function') {
-             ctx.logger.info('Executing runtime.onEnable', { 
-                 appName: this.name,
-                 appId 
-             });
-             
-             // Construct the Host Context (mirroring old ObjectQL.use logic)
-             const hostContext = {
-                ...ctx,
-                ql,
-                logger: ctx.logger,
-                drivers: {
-                    register: (driver: any) => {
-                        ctx.logger.debug('Registering driver via app runtime', { 
-                            driverName: driver.name,
-                            appId 
-                        });
-                        ql.registerDriver(driver);
-                    }
-                },
-             };
-             
-             await runtime.onEnable(hostContext);
-             ctx.logger.debug('Runtime.onEnable completed', { appId });
-        } else {
-             ctx.logger.debug('No runtime.onEnable function found', { appId });
-        }
-
-        // ── i18n Translation Loading ─────────────────────────────────────
-        // Auto-load translation bundles from the app config into the
-        // kernel's i18n service, so discovery and handlers stay consistent.
-        this.loadTranslations(ctx, appId);
-
-        // Data Seeding
-        // Collect seed data from multiple locations (top-level `data` preferred, `manifest.data` for backward compat)
-        const seedDatasets: any[] = [];
-        
-        // 1. Top-level `data` field (new standard location on ObjectStackDefinition)
-        if (Array.isArray(this.bundle.data)) {
-            seedDatasets.push(...this.bundle.data);
-        }
-        
-        // 2. Legacy: `manifest.data` (backward compatibility)
-        const manifest = this.bundle.manifest || this.bundle;
-        if (manifest && Array.isArray(manifest.data)) {
-            seedDatasets.push(...manifest.data);
-        }
-
-        // Resolve short object names to FQN using the package's namespace.
-        // e.g., seed `object: 'task'` in namespace 'todo' → 'todo__task'
-        // Reserved namespaces ('base', 'system') are not prefixed.
-        const namespace = (this.bundle.manifest || this.bundle)?.namespace as string | undefined;
-        const RESERVED_NS = new Set(['base', 'system']);
-        const toFQN = (name: string) => {
-            if (name.includes('__') || !namespace || RESERVED_NS.has(namespace)) return name;
-            return `${namespace}__${name}`;
-        };
-        
-        if (seedDatasets.length > 0) {
-             ctx.logger.info(`[AppPlugin] Found ${seedDatasets.length} seed datasets for ${appId}`);
-
-             // Normalize dataset object names to FQN
-             const normalizedDatasets = seedDatasets
-                 .filter((d: any) => d.object && Array.isArray(d.records))
-                 .map((d: any) => ({
-                     ...d,
-                     object: toFQN(d.object),
-                 }));
-
-             // Use SeedLoaderService for metadata-driven loading with reference resolution
-             try {
-                 const metadata = ctx.getService('metadata') as IMetadataService | undefined;
-                 if (metadata) {
-                     const seedLoader = new SeedLoaderService(ql, metadata, ctx.logger);
-                     const { SeedLoaderRequestSchema } = await import('@objectstack/spec/data');
-                     const request = SeedLoaderRequestSchema.parse({
-                         datasets: normalizedDatasets,
-                         config: { defaultMode: 'upsert', multiPass: true },
-                     });
-                     const result = await seedLoader.load(request);
-                     ctx.logger.info('[Seeder] Seed loading complete', {
-                         inserted: result.summary.totalInserted,
-                         updated: result.summary.totalUpdated,
-                         errors: result.errors.length,
-                     });
-                 } else {
-                     // Fallback: basic insert when metadata service is not available
-                     ctx.logger.debug('[Seeder] No metadata service; using basic insert fallback');
-                     for (const dataset of normalizedDatasets) {
-                         ctx.logger.info(`[Seeder] Seeding ${dataset.records.length} records for ${dataset.object}`);
-                         for (const record of dataset.records) {
-                             try {
-                                 await ql.insert(dataset.object, record);
-                             } catch (err: any) {
-                                 ctx.logger.warn(`[Seeder] Failed to insert ${dataset.object} record:`, { error: err.message });
-                             }
-                         }
-                     }
-                     ctx.logger.info('[Seeder] Data seeding complete.');
-                 }
-             } catch (err: any) {
-                 // If SeedLoaderService fails (e.g., metadata not available), fall back to basic insert
-                 ctx.logger.warn('[Seeder] SeedLoaderService failed, falling back to basic insert', { error: err.message });
-                 for (const dataset of normalizedDatasets) {
-                     for (const record of dataset.records) {
-                         try {
-                             await ql.insert(dataset.object, record);
-                         } catch (insertErr: any) {
-                             ctx.logger.warn(`[Seeder] Failed to insert ${dataset.object} record:`, { error: insertErr.message });
-                         }
-                     }
-                 }
-                 ctx.logger.info('[Seeder] Data seeding complete (fallback).');
-             }
-        }
-    }
-
-    /**
-     * Auto-load i18n translation bundles from the app config into the
-     * kernel's i18n service. Handles both `translations` (array of
-     * TranslationBundle) and `i18n` config (default locale, etc.).
-     *
-     * Gracefully skips when the i18n service is not registered —
-     * this keeps AppPlugin resilient across server/dev/mock environments.
-     */
-    private loadTranslations(ctx: PluginContext, appId: string): void {
-        // ctx.getService throws when a service is not registered, so we
-        // must use try/catch to gracefully skip when no i18n plugin is loaded.
-        let i18nService: II18nService | undefined;
-        try {
-            i18nService = ctx.getService('i18n') as II18nService;
-        } catch {
-            // Service not registered — handled below
-        }
-
-        // Collect translation bundles early to determine if we have data
-        const bundles: Array<Record<string, unknown>> = [];
-        if (Array.isArray(this.bundle.translations)) {
-            bundles.push(...this.bundle.translations);
-        }
-        const manifest = this.bundle.manifest || this.bundle;
-        if (manifest && Array.isArray(manifest.translations) && manifest.translations !== this.bundle.translations) {
-            bundles.push(...manifest.translations);
-        }
-
-        if (!i18nService) {
-            if (bundles.length > 0) {
-                ctx.logger.warn(
-                    `[i18n] App "${appId}" has ${bundles.length} translation bundle(s) but no i18n service is registered. ` +
-                    'Translations will not be served via REST API. ' +
-                    'Register I18nServicePlugin from @objectstack/service-i18n, or use DevPlugin ' +
-                    'which auto-detects translations and registers the i18n service automatically.'
-                );
-            } else {
-                ctx.logger.debug('[i18n] No i18n service registered; skipping translation loading', { appId });
-            }
-            return;
-        }
-
-        // Apply i18n config (default locale, etc.)
-        const i18nConfig = this.bundle.i18n || (this.bundle.manifest || this.bundle)?.i18n;
-        if (i18nConfig?.defaultLocale && typeof i18nService.setDefaultLocale === 'function') {
-            i18nService.setDefaultLocale(i18nConfig.defaultLocale);
-            ctx.logger.debug('[i18n] Set default locale', { appId, locale: i18nConfig.defaultLocale });
-        }
-
-        if (bundles.length === 0) {
-            return;
-        }
-
-        let loadedLocales = 0;
-        for (const bundle of bundles) {
-            // Each bundle is a TranslationBundle: Record<locale, TranslationData>
-            for (const [locale, data] of Object.entries(bundle)) {
-                if (data && typeof data === 'object') {
-                    try {
-                        i18nService.loadTranslations(locale, data as Record<string, unknown>);
-                        loadedLocales++;
-                    } catch (err: any) {
-                        ctx.logger.warn('[i18n] Failed to load translations', { appId, locale, error: err.message });
-                    }
-                }
-            }
-        }
-
-        // Emit diagnostic when the active i18n service is a fallback/stub
-        const svcAny = i18nService as unknown as Record<string, unknown>;
-        if (svcAny._fallback || svcAny._dev) {
-            ctx.logger.info(
-                `[i18n] Loaded ${loadedLocales} locale(s) into in-memory i18n fallback for "${appId}". ` +
-                'For production, consider registering I18nServicePlugin from @objectstack/service-i18n.'
-            );
-        } else {
-            ctx.logger.info('[i18n] Loaded translation bundles', { appId, bundles: bundles.length, locales: loadedLocales });
-        }
-    }
-}