@objectstack/core 0.6.1 → 0.7.2

package/README.md

@@ -1,41 +1,328 @@
 # @objectstack/core
 
-The Microkernel for the ObjectStack Operating System.
+Microkernel Core for ObjectStack - A lightweight, plugin-based architecture with enterprise-grade features.
 
 ## Overview
 
 This package defines the fundamental runtime mechanics of the ObjectStack architecture:
-1.  **Dependency Injection (DI)**: A `services` registry.
-2.  **Plugin Lifecycle**: `init` (Registration) -> `start` (Execution).
-3.  **Event Bus**: Simple hook system (`hook`, `trigger`).
+1. **Dependency Injection (DI)**: Advanced service registry with factory functions and lifecycle management
+2. **Plugin Lifecycle**: `init` (Registration) -> `start` (Execution) -> `destroy` (Cleanup)
+3. **Event Bus**: Simple hook system (`hook`, `trigger`) for event-driven communication
+4. **Configurable Logging**: Universal logger using [Pino](https://github.com/pinojs/pino) for Node.js and simple console for browsers
+5. **Enhanced Features**: Version compatibility, health checks, timeout control, graceful shutdown, and more
 
 It is completely agnostic of "Data", "HTTP", or "Apps". It only knows `Plugin` and `Service`.
 
+## Features
+
+### Core Features
+- **Plugin-based Architecture**: Modular microkernel that manages plugin lifecycle
+- **Service Registry**: Dependency injection for inter-plugin communication
+- **Event/Hook System**: Flexible event-driven communication
+- **High-Performance Logging**: 
+  - Node.js: Powered by [Pino](https://github.com/pinojs/pino) - extremely fast, low-overhead structured logging
+  - Browser: Lightweight console-based logger
+- **Environment Detection**: Automatic runtime detection (Node.js/browser)
+- **Dependency Resolution**: Automatic topological sorting of plugin dependencies
+- **Security**: Automatic sensitive data redaction in logs
+
+### Enhanced Features (EnhancedObjectKernel)
+- **Async Plugin Loading**: Load plugins asynchronously with validation
+- **Version Compatibility**: Semantic versioning support and validation
+- **Plugin Signatures**: Security verification (extensible)
+- **Configuration Validation**: Zod-based schema validation for plugin configs
+- **Service Factories**: Factory-based service instantiation with lifecycle control
+- **Service Lifecycles**: Singleton, Transient, and Scoped service management
+- **Circular Dependency Detection**: Automatic detection and reporting
+- **Lazy Loading**: Services created on-demand
+- **Timeout Control**: Configurable timeouts for plugin initialization
+- **Failure Rollback**: Automatic rollback on startup failures
+- **Health Checks**: Monitor plugin health at runtime
+- **Performance Metrics**: Track plugin startup times
+- **Graceful Shutdown**: Proper cleanup with timeout control
+
 ## Installation
 
 ```bash
 npm install @objectstack/core
+# or
+pnpm add @objectstack/core
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { ObjectKernel, Plugin, PluginContext } from '@objectstack/core';
 
 // 1. Define a Plugin
-class MyPlugin implements Plugin {
-    name = 'my-plugin';
+const myPlugin: Plugin = {
+    name: 'my-plugin',
     
     async init(ctx: PluginContext) {
+        ctx.logger.info('Initializing plugin');
         ctx.registerService('my-service', { hello: 'world' });
     }
-}
+};
 
-// 2. Boot Kernel
-const kernel = new ObjectKernel();
-kernel.use(new MyPlugin());
+// 2. Boot Kernel with logging config
+const kernel = new ObjectKernel({
+  logger: {
+    level: 'info',
+    format: 'pretty'
+  }
+});
+
+kernel.use(myPlugin);
 await kernel.bootstrap();
 
 // 3. Use Service
-const service = kernel.context.getService('my-service');
+const service = kernel.getService('my-service');
+
+// 4. Cleanup
+await kernel.shutdown();
+```
+
+## Configurable Logger
+
+The logger uses **[Pino](https://github.com/pinojs/pino)** for Node.js environments (high-performance, low-overhead) and a simple console-based logger for browsers. It automatically detects the runtime environment.
+
+### Why Pino?
+
+- **Fast**: One of the fastest Node.js loggers available
+- **Low Overhead**: Minimal performance impact on your application
+- **Structured Logging**: Native JSON output for log aggregation tools
+- **Production Ready**: Battle-tested in production environments
+- **Feature Rich**: Automatic log rotation, transports, child loggers, and more
+
+### Logger Configuration
+
+```typescript
+const kernel = new ObjectKernel({
+  logger: {
+    level: 'debug',        // 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+    format: 'pretty',      // 'json' | 'text' | 'pretty'
+    sourceLocation: true,  // Include file/line numbers
+    redact: ['password', 'token', 'apiKey'], // Keys to redact
+    file: './logs/app.log',     // Node.js only
+    rotation: {                 // File rotation (Node.js only)
+      maxSize: '10m',
+      maxFiles: 5
+    }
+  }
+});
+```
+
+### Using Logger in Plugins
+
+```typescript
+const myPlugin: Plugin = {
+  name: 'my-plugin',
+  
+  init: async (ctx: PluginContext) => {
+    // Basic logging
+    ctx.logger.info('Plugin initialized');
+    ctx.logger.debug('Debug info', { details: 'data' });
+    ctx.logger.warn('Warning message');
+    ctx.logger.error('Error occurred', new Error('Oops'));
+    
+    // Sensitive data is automatically redacted
+    ctx.logger.info('User login', {
+      username: 'john',
+      password: 'secret123'  // Logged as '***REDACTED***'
+    });
+  }
+};
+```
+
+### Standalone Logger
+
+```typescript
+import { createLogger } from '@objectstack/core';
+
+const logger = createLogger({
+  level: 'info',
+  format: 'json'
+});
+
+logger.info('Application started');
+
+// Child logger with context
+const requestLogger = logger.child({
+  requestId: '123',
+  userId: 'user-456'
+});
+
+requestLogger.info('Processing request');
+
+// Distributed tracing
+const tracedLogger = logger.withTrace('trace-id-123', 'span-id-456');
+
+// Cleanup
+await logger.destroy();
+```
+
+## Log Formats
+
+### JSON (default for Node.js)
+```json
+{"timestamp":"2026-01-29T22:47:36.441Z","level":"info","message":"User action","context":{"userId":"123"}}
+```
+
+### Text
+```
+2026-01-29T22:47:36.441Z | INFO | User action | {"userId":"123"}
+```
+
+### Pretty (default for browser)
 ```
+[INFO] User action { userId: '123' }
+```
+
+## Plugin Development
+
+```typescript
+import { Plugin, PluginContext } from '@objectstack/core';
+
+const databasePlugin: Plugin = {
+  name: 'database',
+  version: '1.0.0',
+  
+  init: async (ctx: PluginContext) => {
+    const db = await connectToDatabase();
+    ctx.registerService('db', db);
+    ctx.logger.info('Database connected');
+  },
+  
+  start: async (ctx: PluginContext) => {
+    ctx.logger.info('Database ready');
+  },
+  
+  destroy: async () => {
+    await db.close();
+  }
+};
+
+const apiPlugin: Plugin = {
+  name: 'api',
+  dependencies: ['database'],  // Load after database
+  
+  init: async (ctx: PluginContext) => {
+    const db = ctx.getService('db');
+    const server = createServer(db);
+    ctx.registerService('api', server);
+  }
+};
+
+kernel.use(databasePlugin);
+kernel.use(apiPlugin);
+await kernel.bootstrap();
+```
+
+## Enhanced Kernel Usage
+
+For production applications, use `EnhancedObjectKernel` for advanced features:
+
+```typescript
+import { EnhancedObjectKernel, PluginMetadata, ServiceLifecycle } from '@objectstack/core';
+
+// Create enhanced kernel
+const kernel = new EnhancedObjectKernel({
+  logger: { level: 'info', format: 'pretty' },
+  defaultStartupTimeout: 30000,   // 30 seconds
+  gracefulShutdown: true,
+  shutdownTimeout: 60000,         // 60 seconds
+  rollbackOnFailure: true,        // Rollback on failures
+});
+
+// Plugin with version and health check
+const plugin: PluginMetadata = {
+  name: 'my-plugin',
+  version: '1.2.3',
+  startupTimeout: 10000,
+  
+  async init(ctx) {
+    ctx.registerService('my-service', serviceInstance);
+  },
+  
+  async healthCheck() {
+    return {
+      healthy: true,
+      message: 'Service is operational'
+    };
+  }
+};
+
+// Register service factory with lifecycle
+kernel.registerServiceFactory(
+  'database',
+  async (ctx) => await connectToDatabase(),
+  ServiceLifecycle.SINGLETON
+);
+
+await kernel.use(plugin);
+await kernel.bootstrap();
+
+// Check health
+const health = await kernel.checkPluginHealth('my-plugin');
+console.log(health);
+
+// Get metrics
+const metrics = kernel.getPluginMetrics();
+console.log(metrics);
+
+// Graceful shutdown
+await kernel.shutdown();
+```
+
+See [ENHANCED_FEATURES.md](./ENHANCED_FEATURES.md) for comprehensive documentation.
+See [examples/enhanced-kernel-example.ts](./examples/enhanced-kernel-example.ts) for a complete example.
+
+## Environment Support
+
+### Node.js Features (via Pino)
+- High-performance structured logging
+- Automatic file logging with rotation
+- JSON format for log aggregation tools (Elasticsearch, Splunk, etc.)
+- Pretty printing for development (via pino-pretty)
+- Child loggers with inherited context
+- Minimal performance overhead
+
+### Browser Features  
+- Pretty console output with colors
+- DevTools integration
+- Lightweight implementation
+- No external dependencies
+
+## Security
+
+Automatic sensitive data redaction:
+- Default keys: `password`, `token`, `secret`, `key`
+- Configurable via `redact` option
+- Recursive through nested objects
+
+## API Reference
+
+### ObjectKernel (Basic)
+- `ObjectKernel` - Basic microkernel class
+- `createLogger(config)` - Create standalone logger
+- `Plugin` - Plugin interface
+- `PluginContext` - Runtime context for plugins
+- `Logger` - Logger interface
+
+### EnhancedObjectKernel (Advanced)
+- `EnhancedObjectKernel` - Enhanced microkernel with production features
+- `PluginLoader` - Plugin loading and validation
+- `ServiceLifecycle` - Service lifecycle management (SINGLETON, TRANSIENT, SCOPED)
+- `PluginMetadata` - Extended plugin interface with metadata
+- `PluginHealthStatus` - Health check result interface
+
+See [TypeScript definitions](./src/types.ts) for complete API.
+
+## Documentation
+
+- [ENHANCED_FEATURES.md](./ENHANCED_FEATURES.md) - Comprehensive guide to enhanced features
+- [examples/enhanced-kernel-example.ts](./examples/enhanced-kernel-example.ts) - Complete working example
+
+## License
+
+Apache-2.0

package/dist/contracts/data-engine.d.ts

@@ -1,34 +1,41 @@
-import { QueryAST } from '@objectstack/spec/data';
-import { DriverOptions } from '@objectstack/spec/system';
+import { DataEngineQueryOptions, DataEngineInsertOptions, DataEngineUpdateOptions, DataEngineDeleteOptions, DataEngineAggregateOptions, DataEngineCountOptions, DataEngineRequest, // Added Request type for batch
+QueryAST, DriverOptions } from '@objectstack/spec/data';
 /**
  * IDataEngine - Standard Data Engine Interface
  *
  * Abstract interface for data persistence capabilities.
  * Following the Dependency Inversion Principle - plugins depend on this interface,
  * not on concrete database implementations.
+ *
+ * Aligned with 'src/data/data-engine.zod.ts' in @objectstack/spec.
  */
-export interface DataEngineFilter {
-    [key: string]: any;
-}
-export interface DataEngineQueryOptions {
-    /** Filter conditions */
-    filter?: DataEngineFilter;
-    /** Fields to select */
-    select?: string[];
-    /** Sort order */
-    sort?: Record<string, 1 | -1 | 'asc' | 'desc'>;
-    /** Limit number of results */
-    limit?: number;
-    /** Skip number of results */
-    skip?: number;
-    /** Maximum number of results */
-    top?: number;
-}
 export interface IDataEngine {
-    insert(objectName: string, data: any): Promise<any>;
     find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]>;
-    update(objectName: string, id: any, data: any): Promise<any>;
-    delete(objectName: string, id: any): Promise<boolean>;
+    findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;
+    insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
+    update(objectName: string, data: any, options?: DataEngineUpdateOptions): Promise<any>;
+    delete(objectName: string, options?: DataEngineDeleteOptions): Promise<any>;
+    count(objectName: string, query?: DataEngineCountOptions): Promise<number>;
+    aggregate(objectName: string, query: DataEngineAggregateOptions): Promise<any[]>;
+    /**
+     * Vector Search (AI/RAG)
+     */
+    vectorFind?(objectName: string, vector: number[], options?: {
+        filter?: any;
+        limit?: number;
+        select?: string[];
+        threshold?: number;
+    }): Promise<any[]>;
+    /**
+     * Batch Operations (Transactional)
+     */
+    batch?(requests: DataEngineRequest[], options?: {
+        transaction?: boolean;
+    }): Promise<any[]>;
+    /**
+     * Execute raw command (Escape hatch)
+     */
+    execute?(command: any, options?: Record<string, any>): Promise<any>;
 }
 export interface DriverInterface {
     name: string;
@@ -40,6 +47,16 @@ export interface DriverInterface {
     create(object: string, data: any, options?: DriverOptions): Promise<any>;
     update(object: string, id: any, data: any, options?: DriverOptions): Promise<any>;
     delete(object: string, id: any, options?: DriverOptions): Promise<any>;
+    /**
+     * Bulk & Batch Operations
+     */
+    bulkCreate?(object: string, data: any[], options?: DriverOptions): Promise<any>;
+    updateMany?(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<any>;
+    deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
     count?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+    /**
+     * Raw Execution
+     */
+    execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
 }
 //# sourceMappingURL=data-engine.d.ts.map

package/dist/contracts/data-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-engine.d.ts","sourceRoot":"","sources":["../../src/contracts/data-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,wBAAwB;IACxB,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,GAAG,MAAM,CAAC,CAAC;IAC/C,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACpD,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7D,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC/E,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAChF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACzE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAClF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnF"}
+{"version":3,"file":"data-engine.d.ts","sourceRoot":"","sources":["../../src/contracts/data-engine.ts"],"names":[],"mappings":"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"}

package/dist/contracts/logger.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Logger Contract
+ *
+ * Defines the interface for logging in ObjectStack.
+ * Compatible with both browser console and structured logging systems.
+ */
+export interface Logger {
+    /**
+     * Log a debug message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    debug(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log an informational message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    info(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log a warning message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    warn(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log an error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+    /**
+     * Log a fatal error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    fatal?(message: string, error?: Error, meta?: Record<string, any>): void;
+    /**
+     * Create a child logger with additional context
+     * @param context - Context to add to all logs from this child
+     */
+    child?(context: Record<string, any>): Logger;
+    /**
+     * Set trace context for distributed tracing
+     * @param traceId - Trace identifier
+     * @param spanId - Span identifier
+     */
+    withTrace?(traceId: string, spanId?: string): Logger;
+    /**
+     * Compatibility method for console.log usage
+     * @param message - The message to log
+     * @param args - Additional arguments
+     */
+    log?(message: string, ...args: any[]): void;
+    /**
+     * Cleanup resources (close file streams, etc.)
+     * Should be called when the logger is no longer needed
+     */
+    destroy?(): Promise<void>;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/contracts/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/contracts/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,MAAM;IACnB;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAEzD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAExD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAExD;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAExE;;;;;OAKG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAEzE;;;OAGG;IACH,KAAK,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC;IAE7C;;;;OAIG;IACH,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAErD;;;;OAIG;IACH,GAAG,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IAE5C;;;OAGG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B"}

package/dist/contracts/logger.js

@@ -0,0 +1 @@
+export {};

package/dist/enhanced-kernel.d.ts

@@ -0,0 +1,103 @@
+import { Plugin } from './types.js';
+import type { LoggerConfig } from '@objectstack/spec/system';
+import { ServiceLifecycle, ServiceFactory } from './plugin-loader.js';
+/**
+ * Enhanced Kernel Configuration
+ */
+export interface EnhancedKernelConfig {
+    logger?: Partial<LoggerConfig>;
+    /** Default plugin startup timeout in milliseconds */
+    defaultStartupTimeout?: number;
+    /** Whether to enable graceful shutdown */
+    gracefulShutdown?: boolean;
+    /** Graceful shutdown timeout in milliseconds */
+    shutdownTimeout?: number;
+    /** Whether to rollback on startup failure */
+    rollbackOnFailure?: boolean;
+}
+/**
+ * Enhanced ObjectKernel with Advanced Plugin Management
+ *
+ * Extends the basic ObjectKernel with:
+ * - Async plugin loading with validation
+ * - Version compatibility checking
+ * - Plugin signature verification
+ * - Configuration validation (Zod)
+ * - Factory-based dependency injection
+ * - Service lifecycle management (singleton/transient/scoped)
+ * - Circular dependency detection
+ * - Lazy loading services
+ * - Graceful shutdown
+ * - Plugin startup timeout control
+ * - Startup failure rollback
+ * - Plugin health checks
+ */
+export declare class EnhancedObjectKernel {
+    private plugins;
+    private services;
+    private hooks;
+    private state;
+    private logger;
+    private context;
+    private pluginLoader;
+    private config;
+    private startedPlugins;
+    private pluginStartTimes;
+    private shutdownHandlers;
+    constructor(config?: EnhancedKernelConfig);
+    /**
+     * Register a plugin with enhanced validation
+     */
+    use(plugin: Plugin): Promise<this>;
+    /**
+     * Register a service factory with lifecycle management
+     */
+    registerServiceFactory<T>(name: string, factory: ServiceFactory<T>, lifecycle?: ServiceLifecycle, dependencies?: string[]): this;
+    /**
+     * Bootstrap the kernel with enhanced features
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Graceful shutdown with timeout
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check health of a specific plugin
+     */
+    checkPluginHealth(pluginName: string): Promise<any>;
+    /**
+     * Check health of all plugins
+     */
+    checkAllPluginsHealth(): Promise<Map<string, any>>;
+    /**
+     * Get plugin startup metrics
+     */
+    getPluginMetrics(): Map<string, number>;
+    /**
+     * Get a service (sync helper)
+     */
+    getService<T>(name: string): T;
+    /**
+     * Get a service asynchronously (supports factories)
+     */
+    getServiceAsync<T>(name: string, scopeId?: string): Promise<T>;
+    /**
+     * Check if kernel is running
+     */
+    isRunning(): boolean;
+    /**
+     * Get kernel state
+     */
+    getState(): string;
+    private initPluginWithTimeout;
+    private startPluginWithTimeout;
+    private rollbackStartedPlugins;
+    private performShutdown;
+    private resolveDependencies;
+    private registerShutdownSignals;
+    /**
+     * Register a custom shutdown handler
+     */
+    onShutdown(handler: () => Promise<void>): void;
+}
+//# sourceMappingURL=enhanced-kernel.d.ts.map

package/dist/enhanced-kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhanced-kernel.d.ts","sourceRoot":"","sources":["../src/enhanced-kernel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAiB,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAgC,gBAAgB,EAAE,cAAc,EAAuB,MAAM,oBAAoB,CAAC;AAEzH;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAE/B,qDAAqD;IACrD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAE/B,0CAA0C;IAC1C,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,oBAAoB;IAC7B,OAAO,CAAC,OAAO,CAA0C;IACzD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,KAAK,CAA2E;IACxF,OAAO,CAAC,KAAK,CAAwE;IACrF,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAgB;IAC/B,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,cAAc,CAA0B;IAChD,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,OAAO,CAAC,gBAAgB,CAAkC;gBAE9C,MAAM,GAAE,oBAAyB;IAgE7C;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBxC;;OAEG;IACH,sBAAsB,CAAC,CAAC,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAC1B,SAAS,GAAE,gBAA6C,EACxD,YAAY,CAAC,EAAE,MAAM,EAAE,GACxB,IAAI;IAUP;;OAEG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAqDhC;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqC/B;;OAEG;IACG,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAIzD;;OAEG;IACG,qBAAqB,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAWxD;;OAEG;IACH,gBAAgB,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIvC;;OAEG;IACH,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAI9B;;OAEG;IACG,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpE;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACH,QAAQ,IAAI,MAAM;YAMJ,qBAAqB;YAerB,sBAAsB;YA6CtB,sBAAsB;YAkBtB,eAAe;IA2B7B,OAAO,CAAC,mBAAmB;IAyC3B,OAAO,CAAC,uBAAuB;IA2B/B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;CAGjD"}