@objectstack/spec 0.8.2 → 0.9.1

package/dist/system/plugin-loading.zod.js

@@ -0,0 +1,612 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PluginLoadingStateSchema = exports.PluginLoadingEventSchema = exports.PluginLoadingConfigSchema = exports.PluginPerformanceMonitoringSchema = exports.PluginSandboxingSchema = exports.PluginCachingSchema = exports.PluginHotReloadSchema = exports.PluginDependencyResolutionSchema = exports.PluginInitializationSchema = exports.PluginDynamicImportSchema = exports.PluginCodeSplittingSchema = exports.PluginPreloadConfigSchema = exports.PluginLoadingStrategySchema = void 0;
+const zod_1 = require("zod");
+/**
+ * # Plugin Loading Protocol
+ *
+ * Defines the enhanced plugin loading mechanism for the microkernel architecture.
+ * Inspired by industry best practices from:
+ * - Kubernetes CRDs and Operators
+ * - OSGi Dynamic Module System
+ * - Eclipse Plugin Framework
+ * - Webpack Module Federation
+ *
+ * This protocol enables:
+ * - Lazy loading and code splitting
+ * - Dynamic imports and parallel initialization
+ * - Capability-based discovery
+ * - Hot reload in development
+ * - Advanced caching strategies
+ */
+/**
+ * Plugin Loading Strategy
+ * Determines how and when a plugin is loaded into memory
+ */
+exports.PluginLoadingStrategySchema = zod_1.z.enum([
+    'eager', // Load immediately during bootstrap (critical plugins)
+    'lazy', // Load on first use (feature plugins)
+    'parallel', // Load in parallel with other plugins
+    'deferred', // Load after initial bootstrap complete
+    'on-demand', // Load only when explicitly requested
+]).describe('Plugin loading strategy');
+/**
+ * Plugin Preloading Configuration
+ * Configures preloading behavior for faster activation
+ */
+exports.PluginPreloadConfigSchema = zod_1.z.object({
+    /**
+     * Enable preloading for this plugin
+     */
+    enabled: zod_1.z.boolean().default(false),
+    /**
+     * Preload priority (lower = higher priority)
+     */
+    priority: zod_1.z.number().int().min(0).default(100),
+    /**
+     * Resources to preload
+     */
+    resources: zod_1.z.array(zod_1.z.enum([
+        'metadata', // Plugin manifest and metadata
+        'dependencies', // Plugin dependencies
+        'assets', // Static assets (icons, translations)
+        'code', // JavaScript code chunks
+        'services', // Service definitions
+    ])).optional(),
+    /**
+     * Conditions for preloading
+     */
+    conditions: zod_1.z.object({
+        /**
+         * Preload only on specific routes
+         */
+        routes: zod_1.z.array(zod_1.z.string()).optional(),
+        /**
+         * Preload only for specific user roles
+         */
+        roles: zod_1.z.array(zod_1.z.string()).optional(),
+        /**
+         * Preload based on device type
+         */
+        deviceType: zod_1.z.array(zod_1.z.enum(['desktop', 'mobile', 'tablet'])).optional(),
+        /**
+         * Network connection quality threshold
+         */
+        minNetworkSpeed: zod_1.z.enum(['slow-2g', '2g', '3g', '4g']).optional(),
+    }).optional(),
+}).describe('Plugin preloading configuration');
+/**
+ * Plugin Code Splitting Configuration
+ * Configures how plugin code is split for optimal loading
+ */
+exports.PluginCodeSplittingSchema = zod_1.z.object({
+    /**
+     * Enable code splitting for this plugin
+     */
+    enabled: zod_1.z.boolean().default(true),
+    /**
+     * Split strategy
+     */
+    strategy: zod_1.z.enum([
+        'route', // Split by UI routes
+        'feature', // Split by feature modules
+        'size', // Split by bundle size threshold
+        'custom', // Custom split points defined by plugin
+    ]).default('feature'),
+    /**
+     * Chunk naming strategy
+     */
+    chunkNaming: zod_1.z.enum(['hashed', 'named', 'sequential']).default('hashed'),
+    /**
+     * Maximum chunk size in KB
+     */
+    maxChunkSize: zod_1.z.number().int().min(10).optional().describe('Max chunk size in KB'),
+    /**
+     * Shared dependencies optimization
+     */
+    sharedDependencies: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(true),
+        /**
+         * Minimum times a module must be shared before extraction
+         */
+        minChunks: zod_1.z.number().int().min(1).default(2),
+    }).optional(),
+}).describe('Plugin code splitting configuration');
+/**
+ * Plugin Dynamic Import Configuration
+ * Configures dynamic import behavior for runtime module loading
+ */
+exports.PluginDynamicImportSchema = zod_1.z.object({
+    /**
+     * Enable dynamic imports
+     */
+    enabled: zod_1.z.boolean().default(true),
+    /**
+     * Import mode
+     */
+    mode: zod_1.z.enum([
+        'async', // Asynchronous import (recommended)
+        'sync', // Synchronous import (blocking)
+        'eager', // Eager evaluation
+        'lazy', // Lazy evaluation
+    ]).default('async'),
+    /**
+     * Prefetch strategy
+     */
+    prefetch: zod_1.z.boolean().default(false).describe('Prefetch module in idle time'),
+    /**
+     * Preload strategy
+     */
+    preload: zod_1.z.boolean().default(false).describe('Preload module in parallel with parent'),
+    /**
+     * Webpack magic comments support
+     */
+    webpackChunkName: zod_1.z.string().optional().describe('Custom chunk name for webpack'),
+    /**
+     * Import timeout in milliseconds
+     */
+    timeout: zod_1.z.number().int().min(100).default(30000).describe('Dynamic import timeout (ms)'),
+    /**
+     * Retry configuration on import failure
+     */
+    retry: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(true),
+        maxAttempts: zod_1.z.number().int().min(1).max(10).default(3),
+        backoffMs: zod_1.z.number().int().min(0).default(1000).describe('Exponential backoff base delay'),
+    }).optional(),
+}).describe('Plugin dynamic import configuration');
+/**
+ * Plugin Initialization Configuration
+ * Configures how plugin initialization is executed
+ */
+exports.PluginInitializationSchema = zod_1.z.object({
+    /**
+     * Initialization mode
+     */
+    mode: zod_1.z.enum([
+        'sync', // Synchronous initialization
+        'async', // Asynchronous initialization
+        'parallel', // Parallel with other plugins
+        'sequential', // Must complete before next plugin
+    ]).default('async'),
+    /**
+     * Initialization timeout in milliseconds
+     */
+    timeout: zod_1.z.number().int().min(100).default(30000),
+    /**
+     * Startup priority (lower = higher priority, earlier initialization)
+     */
+    priority: zod_1.z.number().int().min(0).default(100),
+    /**
+     * Whether to continue bootstrap if this plugin fails
+     */
+    critical: zod_1.z.boolean().default(false).describe('If true, kernel bootstrap fails if plugin fails'),
+    /**
+     * Retry configuration on initialization failure
+     */
+    retry: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(false),
+        maxAttempts: zod_1.z.number().int().min(1).max(5).default(3),
+        backoffMs: zod_1.z.number().int().min(0).default(1000),
+    }).optional(),
+    /**
+     * Health check interval for monitoring
+     */
+    healthCheckInterval: zod_1.z.number().int().min(0).optional().describe('Health check interval in ms (0 = disabled)'),
+}).describe('Plugin initialization configuration');
+/**
+ * Plugin Dependency Resolution Configuration
+ * Advanced dependency resolution using semantic versioning
+ */
+exports.PluginDependencyResolutionSchema = zod_1.z.object({
+    /**
+     * Dependency resolution strategy
+     */
+    strategy: zod_1.z.enum([
+        'strict', // Exact version match required
+        'compatible', // Semver compatible versions (^)
+        'latest', // Always use latest compatible
+        'pinned', // Lock to specific version
+    ]).default('compatible'),
+    /**
+     * Peer dependency handling
+     */
+    peerDependencies: zod_1.z.object({
+        /**
+         * Whether to resolve peer dependencies
+         */
+        resolve: zod_1.z.boolean().default(true),
+        /**
+         * Action on missing peer dependency
+         */
+        onMissing: zod_1.z.enum(['error', 'warn', 'ignore']).default('warn'),
+        /**
+         * Action on peer version mismatch
+         */
+        onMismatch: zod_1.z.enum(['error', 'warn', 'ignore']).default('warn'),
+    }).optional(),
+    /**
+     * Optional dependency handling
+     */
+    optionalDependencies: zod_1.z.object({
+        /**
+         * Whether to attempt loading optional dependencies
+         */
+        load: zod_1.z.boolean().default(true),
+        /**
+         * Action on optional dependency load failure
+         */
+        onFailure: zod_1.z.enum(['warn', 'ignore']).default('warn'),
+    }).optional(),
+    /**
+     * Conflict resolution
+     */
+    conflictResolution: zod_1.z.enum([
+        'fail', // Fail on any version conflict
+        'latest', // Use latest version
+        'oldest', // Use oldest version
+        'manual', // Require manual resolution
+    ]).default('latest'),
+    /**
+     * Circular dependency handling
+     */
+    circularDependencies: zod_1.z.enum([
+        'error', // Throw error on circular dependency
+        'warn', // Warn but continue
+        'allow', // Allow circular dependencies
+    ]).default('warn'),
+}).describe('Plugin dependency resolution configuration');
+/**
+ * Plugin Hot Reload Configuration
+ * Enables hot module replacement for development
+ */
+exports.PluginHotReloadSchema = zod_1.z.object({
+    /**
+     * Enable hot reload
+     */
+    enabled: zod_1.z.boolean().default(false),
+    /**
+     * Hot reload strategy
+     */
+    strategy: zod_1.z.enum([
+        'full', // Full plugin reload (destroy and reinitialize)
+        'partial', // Partial reload (update changed modules only)
+        'state-preserve', // Preserve plugin state during reload
+    ]).default('full'),
+    /**
+     * Files to watch for changes
+     */
+    watchPatterns: zod_1.z.array(zod_1.z.string()).optional().describe('Glob patterns for files to watch'),
+    /**
+     * Files to ignore
+     */
+    ignorePatterns: zod_1.z.array(zod_1.z.string()).optional().describe('Glob patterns for files to ignore'),
+    /**
+     * Debounce delay in milliseconds
+     */
+    debounceMs: zod_1.z.number().int().min(0).default(300),
+    /**
+     * Whether to preserve state during reload
+     */
+    preserveState: zod_1.z.boolean().default(false),
+    /**
+     * State serialization
+     */
+    stateSerialization: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(false),
+        /**
+         * Path to state serialization handler
+         */
+        handler: zod_1.z.string().optional(),
+    }).optional(),
+    /**
+     * Hooks for hot reload lifecycle
+     */
+    hooks: zod_1.z.object({
+        beforeReload: zod_1.z.string().optional().describe('Function to call before reload'),
+        afterReload: zod_1.z.string().optional().describe('Function to call after reload'),
+        onError: zod_1.z.string().optional().describe('Function to call on reload error'),
+    }).optional(),
+}).describe('Plugin hot reload configuration');
+/**
+ * Plugin Caching Configuration
+ * Configures caching strategy for faster subsequent loads
+ */
+exports.PluginCachingSchema = zod_1.z.object({
+    /**
+     * Enable caching
+     */
+    enabled: zod_1.z.boolean().default(true),
+    /**
+     * Cache storage type
+     */
+    storage: zod_1.z.enum([
+        'memory', // In-memory cache (fastest, not persistent)
+        'disk', // Disk cache (persistent)
+        'indexeddb', // Browser IndexedDB (persistent, browser only)
+        'hybrid', // Memory + Disk hybrid
+    ]).default('memory'),
+    /**
+     * Cache key strategy
+     */
+    keyStrategy: zod_1.z.enum([
+        'version', // Cache by plugin version
+        'hash', // Cache by content hash
+        'timestamp', // Cache by last modified timestamp
+    ]).default('version'),
+    /**
+     * Cache TTL in seconds
+     */
+    ttl: zod_1.z.number().int().min(0).optional().describe('Time to live in seconds (0 = infinite)'),
+    /**
+     * Maximum cache size in MB
+     */
+    maxSize: zod_1.z.number().int().min(1).optional().describe('Max cache size in MB'),
+    /**
+     * Cache invalidation triggers
+     */
+    invalidateOn: zod_1.z.array(zod_1.z.enum([
+        'version-change',
+        'dependency-change',
+        'manual',
+        'error',
+    ])).optional(),
+    /**
+     * Compression
+     */
+    compression: zod_1.z.object({
+        enabled: zod_1.z.boolean().default(false),
+        algorithm: zod_1.z.enum(['gzip', 'brotli', 'deflate']).default('gzip'),
+    }).optional(),
+}).describe('Plugin caching configuration');
+/**
+ * Plugin Sandboxing Configuration
+ * Security isolation for untrusted plugins
+ */
+exports.PluginSandboxingSchema = zod_1.z.object({
+    /**
+     * Enable sandboxing
+     */
+    enabled: zod_1.z.boolean().default(false),
+    /**
+     * Sandbox isolation level
+     */
+    isolationLevel: zod_1.z.enum([
+        'none', // No isolation
+        'process', // Separate process (Node.js worker threads)
+        'vm', // VM context isolation
+        'iframe', // iframe isolation (browser)
+        'web-worker', // Web Worker (browser)
+    ]).default('none'),
+    /**
+     * Allowed capabilities
+     */
+    allowedCapabilities: zod_1.z.array(zod_1.z.string()).optional().describe('List of allowed capability IDs'),
+    /**
+     * Resource quotas
+     */
+    resourceQuotas: zod_1.z.object({
+        /**
+         * Maximum memory usage in MB
+         */
+        maxMemoryMB: zod_1.z.number().int().min(1).optional(),
+        /**
+         * Maximum CPU time in milliseconds
+         */
+        maxCpuTimeMs: zod_1.z.number().int().min(100).optional(),
+        /**
+         * Maximum number of file descriptors
+         */
+        maxFileDescriptors: zod_1.z.number().int().min(1).optional(),
+        /**
+         * Maximum network bandwidth in KB/s
+         */
+        maxNetworkKBps: zod_1.z.number().int().min(1).optional(),
+    }).optional(),
+    /**
+     * Permissions
+     */
+    permissions: zod_1.z.object({
+        /**
+         * Allowed API access
+         */
+        allowedAPIs: zod_1.z.array(zod_1.z.string()).optional(),
+        /**
+         * Allowed file system paths
+         */
+        allowedPaths: zod_1.z.array(zod_1.z.string()).optional(),
+        /**
+         * Allowed network endpoints
+         */
+        allowedEndpoints: zod_1.z.array(zod_1.z.string()).optional(),
+        /**
+         * Allowed environment variables
+         */
+        allowedEnvVars: zod_1.z.array(zod_1.z.string()).optional(),
+    }).optional(),
+}).describe('Plugin sandboxing configuration');
+/**
+ * Plugin Performance Monitoring Configuration
+ * Telemetry and performance tracking
+ */
+exports.PluginPerformanceMonitoringSchema = zod_1.z.object({
+    /**
+     * Enable performance monitoring
+     */
+    enabled: zod_1.z.boolean().default(false),
+    /**
+     * Metrics to collect
+     */
+    metrics: zod_1.z.array(zod_1.z.enum([
+        'load-time',
+        'init-time',
+        'memory-usage',
+        'cpu-usage',
+        'api-calls',
+        'error-rate',
+        'cache-hit-rate',
+    ])).optional(),
+    /**
+     * Sampling rate (0-1, where 1 = 100%)
+     */
+    samplingRate: zod_1.z.number().min(0).max(1).default(1),
+    /**
+     * Reporting interval in seconds
+     */
+    reportingInterval: zod_1.z.number().int().min(1).default(60),
+    /**
+     * Performance budget thresholds
+     */
+    budgets: zod_1.z.object({
+        /**
+         * Maximum load time in milliseconds
+         */
+        maxLoadTimeMs: zod_1.z.number().int().min(0).optional(),
+        /**
+         * Maximum init time in milliseconds
+         */
+        maxInitTimeMs: zod_1.z.number().int().min(0).optional(),
+        /**
+         * Maximum memory usage in MB
+         */
+        maxMemoryMB: zod_1.z.number().int().min(0).optional(),
+    }).optional(),
+    /**
+     * Action on budget violation
+     */
+    onBudgetViolation: zod_1.z.enum(['warn', 'error', 'ignore']).default('warn'),
+}).describe('Plugin performance monitoring configuration');
+/**
+ * Complete Plugin Loading Configuration
+ * Combines all loading-related configurations
+ */
+exports.PluginLoadingConfigSchema = zod_1.z.object({
+    /**
+     * Loading strategy
+     */
+    strategy: exports.PluginLoadingStrategySchema.default('lazy'),
+    /**
+     * Preloading configuration
+     */
+    preload: exports.PluginPreloadConfigSchema.optional(),
+    /**
+     * Code splitting configuration
+     */
+    codeSplitting: exports.PluginCodeSplittingSchema.optional(),
+    /**
+     * Dynamic import configuration
+     */
+    dynamicImport: exports.PluginDynamicImportSchema.optional(),
+    /**
+     * Initialization configuration
+     */
+    initialization: exports.PluginInitializationSchema.optional(),
+    /**
+     * Dependency resolution configuration
+     */
+    dependencyResolution: exports.PluginDependencyResolutionSchema.optional(),
+    /**
+     * Hot reload configuration (development only)
+     */
+    hotReload: exports.PluginHotReloadSchema.optional(),
+    /**
+     * Caching configuration
+     */
+    caching: exports.PluginCachingSchema.optional(),
+    /**
+     * Sandboxing configuration
+     */
+    sandboxing: exports.PluginSandboxingSchema.optional(),
+    /**
+     * Performance monitoring
+     */
+    monitoring: exports.PluginPerformanceMonitoringSchema.optional(),
+}).describe('Complete plugin loading configuration');
+/**
+ * Plugin Loading Event
+ * Emitted during plugin loading lifecycle
+ */
+exports.PluginLoadingEventSchema = zod_1.z.object({
+    /**
+     * Event type
+     */
+    type: zod_1.z.enum([
+        'load-started',
+        'load-completed',
+        'load-failed',
+        'init-started',
+        'init-completed',
+        'init-failed',
+        'preload-started',
+        'preload-completed',
+        'cache-hit',
+        'cache-miss',
+        'hot-reload',
+    ]),
+    /**
+     * Plugin identifier
+     */
+    pluginId: zod_1.z.string(),
+    /**
+     * Timestamp
+     */
+    timestamp: zod_1.z.number().int().min(0),
+    /**
+     * Duration in milliseconds
+     */
+    durationMs: zod_1.z.number().int().min(0).optional(),
+    /**
+     * Additional metadata
+     */
+    metadata: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
+    /**
+     * Error if event represents a failure
+     */
+    error: zod_1.z.object({
+        message: zod_1.z.string(),
+        code: zod_1.z.string().optional(),
+        stack: zod_1.z.string().optional(),
+    }).optional(),
+}).describe('Plugin loading lifecycle event');
+/**
+ * Plugin Loading State
+ * Tracks the current loading state of a plugin
+ */
+exports.PluginLoadingStateSchema = zod_1.z.object({
+    /**
+     * Plugin identifier
+     */
+    pluginId: zod_1.z.string(),
+    /**
+     * Current state
+     */
+    state: zod_1.z.enum([
+        'pending', // Not yet loaded
+        'loading', // Currently loading
+        'loaded', // Code loaded, not initialized
+        'initializing', // Currently initializing
+        'ready', // Fully initialized and ready
+        'failed', // Failed to load or initialize
+        'reloading', // Hot reloading in progress
+    ]),
+    /**
+     * Load progress (0-100)
+     */
+    progress: zod_1.z.number().min(0).max(100).default(0),
+    /**
+     * Loading start time
+     */
+    startedAt: zod_1.z.number().int().min(0).optional(),
+    /**
+     * Loading completion time
+     */
+    completedAt: zod_1.z.number().int().min(0).optional(),
+    /**
+     * Last error
+     */
+    lastError: zod_1.z.string().optional(),
+    /**
+     * Retry count
+     */
+    retryCount: zod_1.z.number().int().min(0).default(0),
+}).describe('Plugin loading state');

package/json-schema/ai/FeedbackLoop.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/FeedbackLoop",
+  "definitions": {
+    "FeedbackLoop": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/Issue.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/Issue",
+  "definitions": {
+    "Issue": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/MetadataSource.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/MetadataSource",
+  "definitions": {
+    "MetadataSource": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/ai/Resolution.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/Resolution",
+  "definitions": {
+    "Resolution": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/api/ApiChangelogEntry.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ApiChangelogEntry",
+  "definitions": {
+    "ApiChangelogEntry": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/api/ApiDiscoveryQuery.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ApiDiscoveryQuery",
+  "definitions": {
+    "ApiDiscoveryQuery": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/api/ApiDiscoveryResponse.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ApiDiscoveryResponse",
+  "definitions": {
+    "ApiDiscoveryResponse": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/api/ApiDocumentationConfig.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ApiDocumentationConfig",
+  "definitions": {
+    "ApiDocumentationConfig": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/api/ApiEndpointRegistration.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ApiEndpointRegistration",
+  "definitions": {
+    "ApiEndpointRegistration": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/json-schema/api/ApiMetadata.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/ApiMetadata",
+  "definitions": {
+    "ApiMetadata": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}