@objectstack/core 0.6.1 → 0.7.1

package/src/kernel.ts

@@ -1,4 +1,7 @@
-import { Plugin, PluginContext } from './types.js';
+import { Plugin } from './types.js';
+import { createLogger, ObjectLogger } from './logger.js';
+import type { LoggerConfig } from '@objectstack/spec/system';
+import { ObjectKernelBase } from './kernel-base.js';
 
 /**
  * ObjectKernel - MiniKernel Architecture
@@ -8,63 +11,28 @@ import { Plugin, PluginContext } from './types.js';
  * - Provides dependency injection via service registry
  * - Implements event/hook system for inter-plugin communication
  * - Handles dependency resolution (topological sort)
+ * - Provides configurable logging for server and browser
  * 
  * Core philosophy:
  * - Business logic is completely separated into plugins
  * - Kernel only manages lifecycle, DI, and hooks
  * - Plugins are loaded as equal building blocks
  */
-export class ObjectKernel {
-    private plugins: Map<string, Plugin> = new Map();
-    private services: Map<string, any> = new Map();
-    private hooks: Map<string, Array<(...args: any[]) => void | Promise<void>>> = new Map();
-    private state: 'idle' | 'initializing' | 'running' | 'stopped' = 'idle';
-
-    /**
-     * Plugin context - shared across all plugins
-     */
-    private context: PluginContext = {
-        registerService: (name, service) => {
-            if (this.services.has(name)) {
-                throw new Error(`[Kernel] Service '${name}' already registered`);
-            }
-            this.services.set(name, service);
-            this.context.logger.log(`[Kernel] Service '${name}' registered`);
-        },
-        getService: <T>(name: string) => {
-            const service = this.services.get(name);
-            if (!service) {
-                throw new Error(`[Kernel] Service '${name}' not found`);
-            }
-            return service as T;
-        },
-        hook: (name, handler) => {
-            if (!this.hooks.has(name)) {
-                this.hooks.set(name, []);
-            }
-            this.hooks.get(name)!.push(handler);
-        },
-        trigger: async (name, ...args) => {
-            const handlers = this.hooks.get(name) || [];
-            for (const handler of handlers) {
-                await handler(...args);
-            }
-        },
-        getServices: () => {
-             return new Map(this.services);
-        },
-        logger: console,
-        getKernel: () => this,
-    };
+export class ObjectKernel extends ObjectKernelBase {
+    constructor(config?: { logger?: Partial<LoggerConfig> }) {
+        const logger = createLogger(config?.logger);
+        super(logger);
+        
+        // Initialize context after logger is created
+        this.context = this.createContext();
+    }
 
     /**
      * Register a plugin
      * @param plugin - Plugin instance
      */
-    use(plugin: Plugin) {
-        if (this.state !== 'idle') {
-            throw new Error('[Kernel] Cannot register plugins after bootstrap has started');
-        }
+    use(plugin: Plugin): this {
+        this.validateIdle();
 
         const pluginName = plugin.name;
         if (this.plugins.has(pluginName)) {
@@ -75,51 +43,6 @@ export class ObjectKernel {
         return this;
     }
 
-    /**
-     * Resolve plugin dependencies using topological sort
-     * @returns Ordered list of plugins
-     */
-    private resolveDependencies(): Plugin[] {
-        const resolved: Plugin[] = [];
-        const visited = new Set<string>();
-        const visiting = new Set<string>();
-
-        const visit = (pluginName: string) => {
-            if (visited.has(pluginName)) return;
-            
-            if (visiting.has(pluginName)) {
-                throw new Error(`[Kernel] Circular dependency detected: ${pluginName}`);
-            }
-
-            const plugin = this.plugins.get(pluginName);
-            if (!plugin) {
-                throw new Error(`[Kernel] Plugin '${pluginName}' not found`);
-            }
-
-            visiting.add(pluginName);
-
-            // Visit dependencies first
-            const deps = plugin.dependencies || [];
-            for (const dep of deps) {
-                if (!this.plugins.has(dep)) {
-                    throw new Error(`[Kernel] Dependency '${dep}' not found for plugin '${pluginName}'`);
-                }
-                visit(dep);
-            }
-
-            visiting.delete(pluginName);
-            visited.add(pluginName);
-            resolved.push(plugin);
-        };
-
-        // Visit all plugins
-        for (const pluginName of this.plugins.keys()) {
-            visit(pluginName);
-        }
-
-        return resolved;
-    }
-
     /**
      * Bootstrap the kernel
      * 1. Resolve dependencies (topological sort)
@@ -127,62 +50,72 @@ export class ObjectKernel {
      * 3. Start phase - plugins execute business logic
      * 4. Trigger 'kernel:ready' hook
      */
-    async bootstrap() {
-        if (this.state !== 'idle') {
-            throw new Error('[Kernel] Kernel already bootstrapped');
-        }
+    async bootstrap(): Promise<void> {
+        this.validateState('idle');
 
         this.state = 'initializing';
-        this.context.logger.log('[Kernel] Bootstrap started...');
+        this.logger.info('Bootstrap started');
 
         // Resolve dependencies
         const orderedPlugins = this.resolveDependencies();
 
         // Phase 1: Init - Plugins register services
-        this.context.logger.log('[Kernel] Phase 1: Init plugins...');
+        this.logger.info('Phase 1: Init plugins');
         for (const plugin of orderedPlugins) {
-            this.context.logger.log(`[Kernel] Init: ${plugin.name}`);
-            await plugin.init(this.context);
+            await this.runPluginInit(plugin);
         }
 
         // Phase 2: Start - Plugins execute business logic
-        this.context.logger.log('[Kernel] Phase 2: Start plugins...');
+        this.logger.info('Phase 2: Start plugins');
         this.state = 'running';
+        
         for (const plugin of orderedPlugins) {
-            if (plugin.start) {
-                this.context.logger.log(`[Kernel] Start: ${plugin.name}`);
-                await plugin.start(this.context);
-            }
+            await this.runPluginStart(plugin);
         }
 
-        // Phase 3: Trigger kernel:ready hook
-        this.context.logger.log('[Kernel] Triggering kernel:ready hook...');
-        await this.context.trigger('kernel:ready');
-
-        this.context.logger.log('[Kernel] ✅ Bootstrap complete');
+        // Trigger ready hook
+        await this.triggerHook('kernel:ready');
+        this.logger.info('✅ Bootstrap complete', { 
+            pluginCount: this.plugins.size 
+        });
     }
 
     /**
      * Shutdown the kernel
      * Calls destroy on all plugins in reverse order
      */
-    async shutdown() {
-        if (this.state !== 'running') {
-            throw new Error('[Kernel] Kernel not running');
+    async shutdown(): Promise<void> {
+        await this.destroy();
+    }
+
+    /**
+     * Graceful shutdown - destroy all plugins in reverse order
+     */
+    async destroy(): Promise<void> {
+        if (this.state === 'stopped') {
+            this.logger.warn('Kernel already stopped');
+            return;
         }
 
-        this.context.logger.log('[Kernel] Shutdown started...');
-        this.state = 'stopped';
+        this.state = 'stopping';
+        this.logger.info('Shutdown started');
 
-        const orderedPlugins = Array.from(this.plugins.values()).reverse();
-        for (const plugin of orderedPlugins) {
-            if (plugin.destroy) {
-                this.context.logger.log(`[Kernel] Destroy: ${plugin.name}`);
-                await plugin.destroy();
-            }
+        // Trigger shutdown hook
+        await this.triggerHook('kernel:shutdown');
+
+        // Destroy plugins in reverse order
+        const orderedPlugins = this.resolveDependencies();
+        for (const plugin of orderedPlugins.reverse()) {
+            await this.runPluginDestroy(plugin);
         }
 
-        this.context.logger.log('[Kernel] ✅ Shutdown complete');
+        this.state = 'stopped';
+        this.logger.info('✅ Shutdown complete');
+        
+        // Cleanup logger resources
+        if (this.logger && typeof (this.logger as ObjectLogger).destroy === 'function') {
+            await (this.logger as ObjectLogger).destroy();
+        }
     }
 
     /**
@@ -199,11 +132,4 @@ export class ObjectKernel {
     isRunning(): boolean {
         return this.state === 'running';
     }
-
-    /**
-     * Get kernel state
-     */
-    getState(): string {
-        return this.state;
-    }
 }

package/src/logger.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { createLogger, ObjectLogger } from './logger';
+
+describe('ObjectLogger', () => {
+    let logger: ObjectLogger;
+
+    beforeEach(() => {
+        logger = createLogger();
+    });
+
+    afterEach(async () => {
+        await logger.destroy();
+    });
+
+    describe('Basic Logging', () => {
+        it('should create a logger with default config', () => {
+            expect(logger).toBeDefined();
+            expect(logger.info).toBeDefined();
+            expect(logger.debug).toBeDefined();
+            expect(logger.warn).toBeDefined();
+            expect(logger.error).toBeDefined();
+        });
+
+        it('should log info messages', () => {
+            expect(() => logger.info('Test message')).not.toThrow();
+        });
+
+        it('should log debug messages', () => {
+            expect(() => logger.debug('Debug message')).not.toThrow();
+        });
+
+        it('should log warn messages', () => {
+            expect(() => logger.warn('Warning message')).not.toThrow();
+        });
+
+        it('should log error messages', () => {
+            const error = new Error('Test error');
+            expect(() => logger.error('Error occurred', error)).not.toThrow();
+        });
+
+        it('should log with metadata', () => {
+            expect(() => logger.info('Message with metadata', { userId: '123', action: 'login' })).not.toThrow();
+        });
+    });
+
+    describe('Configuration', () => {
+        it('should respect log level configuration', async () => {
+            const warnLogger = createLogger({ level: 'warn' });
+            
+            // These should not throw but might not output anything
+            expect(() => warnLogger.debug('Debug message')).not.toThrow();
+            expect(() => warnLogger.info('Info message')).not.toThrow();
+            expect(() => warnLogger.warn('Warning message')).not.toThrow();
+            
+            await warnLogger.destroy();
+        });
+
+        it('should support different formats', async () => {
+            const jsonLogger = createLogger({ format: 'json' });
+            const textLogger = createLogger({ format: 'text' });
+            const prettyLogger = createLogger({ format: 'pretty' });
+            
+            expect(() => jsonLogger.info('JSON format')).not.toThrow();
+            expect(() => textLogger.info('Text format')).not.toThrow();
+            expect(() => prettyLogger.info('Pretty format')).not.toThrow();
+            
+            await jsonLogger.destroy();
+            await textLogger.destroy();
+            await prettyLogger.destroy();
+        });
+
+        it('should redact sensitive keys', async () => {
+            const logger = createLogger({ redact: ['password', 'apiKey'] });
+            
+            // This should work without exposing the password
+            expect(() => logger.info('User login', { 
+                username: 'john',
+                password: 'secret123',
+                apiKey: 'key-12345'
+            })).not.toThrow();
+            
+            await logger.destroy();
+        });
+    });
+
+    describe('Child Loggers', () => {
+        it('should create child logger with context', () => {
+            const childLogger = logger.child({ service: 'api', requestId: '123' });
+            
+            expect(childLogger).toBeDefined();
+            expect(() => childLogger.info('Child log message')).not.toThrow();
+        });
+
+        it('should support trace context', () => {
+            const tracedLogger = logger.withTrace('trace-123', 'span-456');
+            
+            expect(tracedLogger).toBeDefined();
+            expect(() => tracedLogger.info('Traced message')).not.toThrow();
+        });
+    });
+
+    describe('Environment Detection', () => {
+        it('should detect Node.js environment', async () => {
+            // This test runs in Node.js, so logger should detect it
+            const nodeLogger = createLogger({ format: 'json' });
+            expect(() => nodeLogger.info('Node environment')).not.toThrow();
+            await nodeLogger.destroy();
+        });
+    });
+
+    describe('Compatibility', () => {
+        it('should support console.log compatibility', () => {
+            expect(() => logger.log('Compatible log')).not.toThrow();
+        });
+    });
+});

package/src/logger.ts

@@ -0,0 +1,306 @@
+import type { LoggerConfig, LogLevel } from '@objectstack/spec/system';
+import type { Logger } from '@objectstack/spec/contracts';
+
+/**
+ * Universal Logger Implementation
+ * 
+ * A configurable logger that works in both browser and Node.js environments.
+ * - Node.js: Uses Pino for high-performance structured logging
+ * - Browser: Simple console-based implementation
+ * 
+ * Features:
+ * - Structured logging with multiple formats (json, text, pretty)
+ * - Log level filtering
+ * - Sensitive data redaction
+ * - File logging with rotation (Node.js only via Pino)
+ * - Browser console integration
+ * - Distributed tracing support (traceId, spanId)
+ */
+export class ObjectLogger implements Logger {
+    private config: Required<Omit<LoggerConfig, 'file' | 'rotation' | 'name'>> & { file?: string; rotation?: { maxSize: string; maxFiles: number }; name?: string };
+    private isNode: boolean;
+    private pinoLogger?: any; // Pino logger instance for Node.js
+    private pinoInstance?: any; // Base Pino instance for creating child loggers
+
+    constructor(config: Partial<LoggerConfig> = {}) {
+        // Detect runtime environment
+        this.isNode = typeof process !== 'undefined' && process.versions?.node !== undefined;
+
+        // Set defaults
+        this.config = {
+            name: config.name,
+            level: config.level ?? 'info',
+            format: config.format ?? (this.isNode ? 'json' : 'pretty'),
+            redact: config.redact ?? ['password', 'token', 'secret', 'key'],
+            sourceLocation: config.sourceLocation ?? false,
+            file: config.file,
+            rotation: config.rotation ?? {
+                maxSize: '10m',
+                maxFiles: 5
+            }
+        };
+
+        // Initialize Pino logger for Node.js
+        if (this.isNode) {
+            this.initPinoLogger();
+        }
+    }
+
+    /**
+     * Initialize Pino logger for Node.js
+     */
+    private initPinoLogger() {
+        if (!this.isNode) return;
+
+        try {
+            // Dynamic import for Pino (Node.js only)
+            const pino = require('pino');
+            
+            // Build Pino options
+            const pinoOptions: any = {
+                level: this.config.level,
+                redact: {
+                    paths: this.config.redact,
+                    censor: '***REDACTED***'
+                }
+            };
+
+            // Add name if provided
+            if (this.config.name) {
+                pinoOptions.name = this.config.name;
+            }
+
+            // Transport configuration for pretty printing or file output
+            const targets: any[] = [];
+
+            // Console transport
+            if (this.config.format === 'pretty') {
+                targets.push({
+                    target: 'pino-pretty',
+                    options: {
+                        colorize: true,
+                        translateTime: 'SYS:standard',
+                        ignore: 'pid,hostname'
+                    },
+                    level: this.config.level
+                });
+            } else if (this.config.format === 'json') {
+                // JSON to stdout
+                targets.push({
+                    target: 'pino/file',
+                    options: { destination: 1 }, // stdout
+                    level: this.config.level
+                });
+            } else {
+                // text format (simple)
+                targets.push({
+                    target: 'pino/file',
+                    options: { destination: 1 },
+                    level: this.config.level
+                });
+            }
+
+            // File transport (if configured)
+            if (this.config.file) {
+                targets.push({
+                    target: 'pino/file',
+                    options: {
+                        destination: this.config.file,
+                        mkdir: true
+                    },
+                    level: this.config.level
+                });
+            }
+
+            // Create transport
+            if (targets.length > 0) {
+                pinoOptions.transport = targets.length === 1 ? targets[0] : { targets };
+            }
+
+            // Create Pino logger
+            this.pinoInstance = pino(pinoOptions);
+            this.pinoLogger = this.pinoInstance;
+
+        } catch (error) {
+            // Fallback to console if Pino is not available
+            console.warn('[Logger] Pino not available, falling back to console:', error);
+            this.pinoLogger = null;
+        }
+    }
+
+    /**
+     * Redact sensitive keys from context object (for browser)
+     */
+    private redactSensitive(obj: any): any {
+        if (!obj || typeof obj !== 'object') return obj;
+
+        const redacted = Array.isArray(obj) ? [...obj] : { ...obj };
+
+        for (const key in redacted) {
+            const lowerKey = key.toLowerCase();
+            const shouldRedact = this.config.redact.some((pattern: string) => 
+                lowerKey.includes(pattern.toLowerCase())
+            );
+
+            if (shouldRedact) {
+                redacted[key] = '***REDACTED***';
+            } else if (typeof redacted[key] === 'object' && redacted[key] !== null) {
+                redacted[key] = this.redactSensitive(redacted[key]);
+            }
+        }
+
+        return redacted;
+    }
+
+    /**
+     * Format log entry for browser
+     */
+    private formatBrowserLog(level: LogLevel, message: string, context?: Record<string, any>): string {
+        if (this.config.format === 'json') {
+            return JSON.stringify({
+                timestamp: new Date().toISOString(),
+                level,
+                message,
+                ...context
+            });
+        }
+
+        if (this.config.format === 'text') {
+            const parts = [new Date().toISOString(), level.toUpperCase(), message];
+            if (context && Object.keys(context).length > 0) {
+                parts.push(JSON.stringify(context));
+            }
+            return parts.join(' | ');
+        }
+
+        // Pretty format
+        const levelColors: Record<LogLevel, string> = {
+            debug: '\x1b[36m',   // Cyan
+            info: '\x1b[32m',    // Green
+            warn: '\x1b[33m',    // Yellow
+            error: '\x1b[31m',   // Red
+            fatal: '\x1b[35m'    // Magenta
+        };
+        const reset = '\x1b[0m';
+        const color = levelColors[level] || '';
+
+        let output = `${color}[${level.toUpperCase()}]${reset} ${message}`;
+        
+        if (context && Object.keys(context).length > 0) {
+            output += ` ${JSON.stringify(context, null, 2)}`;
+        }
+
+        return output;
+    }
+
+    /**
+     * Log using browser console
+     */
+    private logBrowser(level: LogLevel, message: string, context?: Record<string, any>, error?: Error) {
+        const redactedContext = context ? this.redactSensitive(context) : undefined;
+        const mergedContext = error ? { ...redactedContext, error: { message: error.message, stack: error.stack } } : redactedContext;
+        
+        const formatted = this.formatBrowserLog(level, message, mergedContext);
+        
+        const consoleMethod = level === 'debug' ? 'debug' :
+                            level === 'info' ? 'log' :
+                            level === 'warn' ? 'warn' :
+                            level === 'error' || level === 'fatal' ? 'error' :
+                            'log';
+        
+        console[consoleMethod](formatted);
+    }
+
+    /**
+     * Public logging methods
+     */
+    debug(message: string, meta?: Record<string, any>): void {
+        if (this.isNode && this.pinoLogger) {
+            this.pinoLogger.debug(meta || {}, message);
+        } else {
+            this.logBrowser('debug', message, meta);
+        }
+    }
+
+    info(message: string, meta?: Record<string, any>): void {
+        if (this.isNode && this.pinoLogger) {
+            this.pinoLogger.info(meta || {}, message);
+        } else {
+            this.logBrowser('info', message, meta);
+        }
+    }
+
+    warn(message: string, meta?: Record<string, any>): void {
+        if (this.isNode && this.pinoLogger) {
+            this.pinoLogger.warn(meta || {}, message);
+        } else {
+            this.logBrowser('warn', message, meta);
+        }
+    }
+
+    error(message: string, error?: Error, meta?: Record<string, any>): void {
+        if (this.isNode && this.pinoLogger) {
+            const errorContext = error ? { err: error, ...meta } : meta || {};
+            this.pinoLogger.error(errorContext, message);
+        } else {
+            this.logBrowser('error', message, meta, error);
+        }
+    }
+
+    fatal(message: string, error?: Error, meta?: Record<string, any>): void {
+        if (this.isNode && this.pinoLogger) {
+            const errorContext = error ? { err: error, ...meta } : meta || {};
+            this.pinoLogger.fatal(errorContext, message);
+        } else {
+            this.logBrowser('fatal', message, meta, error);
+        }
+    }
+
+    /**
+     * Create a child logger with additional context
+     * Note: Child loggers share the parent's Pino instance
+     */
+    child(context: Record<string, any>): ObjectLogger {
+        const childLogger = new ObjectLogger(this.config);
+        
+        // For Node.js with Pino, create a Pino child logger
+        if (this.isNode && this.pinoInstance) {
+            childLogger.pinoLogger = this.pinoInstance.child(context);
+            childLogger.pinoInstance = this.pinoInstance;
+        }
+
+        return childLogger;
+    }
+
+    /**
+     * Set trace context for distributed tracing
+     */
+    withTrace(traceId: string, spanId?: string): ObjectLogger {
+        return this.child({ traceId, spanId });
+    }
+
+    /**
+     * Cleanup resources
+     */
+    async destroy(): Promise<void> {
+        if (this.pinoLogger && this.pinoLogger.flush) {
+            await new Promise<void>((resolve) => {
+                this.pinoLogger.flush(() => resolve());
+            });
+        }
+    }
+
+    /**
+     * Compatibility method for console.log usage
+     */
+    log(message: string, ...args: any[]): void {
+        this.info(message, args.length > 0 ? { args } : undefined);
+    }
+}
+
+/**
+ * Create a logger instance
+ */
+export function createLogger(config?: Partial<LoggerConfig>): ObjectLogger {
+    return new ObjectLogger(config);
+}