create-fluxstack 1.0.0

package/core/plugins/registry.ts

@@ -0,0 +1,424 @@
+import type { Plugin, PluginManifest, PluginLoadResult, PluginDiscoveryOptions } from "./types"
+import type { FluxStackConfig } from "../config/schema"
+import type { Logger } from "../utils/logger/index"
+import { FluxStackError } from "../utils/errors"
+import { readdir, readFile } from "fs/promises"
+import { join, resolve } from "path"
+import { existsSync } from "fs"
+
+export interface PluginRegistryConfig {
+  logger?: Logger
+  config?: FluxStackConfig
+  discoveryOptions?: PluginDiscoveryOptions
+}
+
+export class PluginRegistry {
+  private plugins: Map<string, Plugin> = new Map()
+  private manifests: Map<string, PluginManifest> = new Map()
+  private loadOrder: string[] = []
+  private dependencies: Map<string, string[]> = new Map()
+  private conflicts: string[] = []
+  private logger?: Logger
+  private config?: FluxStackConfig
+
+  constructor(options: PluginRegistryConfig = {}) {
+    this.logger = options.logger
+    this.config = options.config
+  }
+
+  /**
+   * Register a plugin with the registry
+   */
+  async register(plugin: Plugin, manifest?: PluginManifest): Promise<void> {
+    if (this.plugins.has(plugin.name)) {
+      throw new FluxStackError(
+        `Plugin '${plugin.name}' is already registered`,
+        'PLUGIN_ALREADY_REGISTERED',
+        400
+      )
+    }
+
+    // Validate plugin structure
+    this.validatePlugin(plugin)
+
+    // Validate plugin configuration if schema is provided
+    if (plugin.configSchema && this.config?.plugins.config[plugin.name]) {
+      this.validatePluginConfig(plugin, this.config.plugins.config[plugin.name])
+    }
+
+    this.plugins.set(plugin.name, plugin)
+    
+    if (manifest) {
+      this.manifests.set(plugin.name, manifest)
+    }
+
+    // Update dependency tracking
+    if (plugin.dependencies) {
+      this.dependencies.set(plugin.name, plugin.dependencies)
+    }
+
+    // Update load order
+    this.updateLoadOrder()
+
+    this.logger?.debug(`Plugin '${plugin.name}' registered successfully`, {
+      plugin: plugin.name,
+      version: plugin.version,
+      dependencies: plugin.dependencies
+    })
+  }
+
+  /**
+   * Unregister a plugin from the registry
+   */
+  unregister(name: string): void {
+    if (!this.plugins.has(name)) {
+      throw new FluxStackError(
+        `Plugin '${name}' is not registered`,
+        'PLUGIN_NOT_FOUND',
+        404
+      )
+    }
+
+    // Check if other plugins depend on this one
+    const dependents = this.getDependents(name)
+    if (dependents.length > 0) {
+      throw new FluxStackError(
+        `Cannot unregister plugin '${name}' because it is required by: ${dependents.join(', ')}`,
+        'PLUGIN_HAS_DEPENDENTS',
+        400
+      )
+    }
+
+    this.plugins.delete(name)
+    this.manifests.delete(name)
+    this.dependencies.delete(name)
+    this.loadOrder = this.loadOrder.filter(pluginName => pluginName !== name)
+
+    this.logger?.debug(`Plugin '${name}' unregistered successfully`)
+  }
+
+  /**
+   * Get a plugin by name
+   */
+  get(name: string): Plugin | undefined {
+    return this.plugins.get(name)
+  }
+
+  /**
+   * Get plugin manifest by name
+   */
+  getManifest(name: string): PluginManifest | undefined {
+    return this.manifests.get(name)
+  }
+
+  /**
+   * Get all registered plugins
+   */
+  getAll(): Plugin[] {
+    return Array.from(this.plugins.values())
+  }
+
+  /**
+   * Get all plugin manifests
+   */
+  getAllManifests(): PluginManifest[] {
+    return Array.from(this.manifests.values())
+  }
+
+  /**
+   * Get plugins in load order
+   */
+  getLoadOrder(): string[] {
+    return [...this.loadOrder]
+  }
+
+  /**
+   * Get plugins that depend on the specified plugin
+   */
+  getDependents(pluginName: string): string[] {
+    const dependents: string[] = []
+    
+    for (const [name, deps] of this.dependencies.entries()) {
+      if (deps.includes(pluginName)) {
+        dependents.push(name)
+      }
+    }
+    
+    return dependents
+  }
+
+  /**
+   * Get plugin dependencies
+   */
+  getDependencies(pluginName: string): string[] {
+    return this.dependencies.get(pluginName) || []
+  }
+
+  /**
+   * Check if a plugin is registered
+   */
+  has(name: string): boolean {
+    return this.plugins.has(name)
+  }
+
+  /**
+   * Get registry statistics
+   */
+  getStats() {
+    return {
+      totalPlugins: this.plugins.size,
+      enabledPlugins: this.config?.plugins.enabled.length || 0,
+      disabledPlugins: this.config?.plugins.disabled.length || 0,
+      conflicts: this.conflicts.length,
+      loadOrder: this.loadOrder.length
+    }
+  }
+
+  /**
+   * Validate all plugin dependencies
+   */
+  validateDependencies(): void {
+    this.conflicts = []
+
+    for (const plugin of this.plugins.values()) {
+      if (plugin.dependencies) {
+        for (const dependency of plugin.dependencies) {
+          if (!this.plugins.has(dependency)) {
+            const error = `Plugin '${plugin.name}' depends on '${dependency}' which is not registered`
+            this.conflicts.push(error)
+            this.logger?.error(error, { plugin: plugin.name, dependency })
+          }
+        }
+      }
+    }
+
+    if (this.conflicts.length > 0) {
+      throw new FluxStackError(
+        `Plugin dependency validation failed: ${this.conflicts.join('; ')}`,
+        'PLUGIN_DEPENDENCY_ERROR',
+        400,
+        { conflicts: this.conflicts }
+      )
+    }
+  }
+
+  /**
+   * Discover plugins from filesystem
+   */
+  async discoverPlugins(options: PluginDiscoveryOptions = {}): Promise<PluginLoadResult[]> {
+    const results: PluginLoadResult[] = []
+    const {
+      directories = ['core/plugins/built-in', 'plugins', 'node_modules'],
+      patterns: _patterns = ['**/plugin.{js,ts}', '**/index.{js,ts}'],
+      includeBuiltIn: _includeBuiltIn = true,
+      includeExternal: _includeExternal = true
+    } = options
+
+    for (const directory of directories) {
+      if (!existsSync(directory)) {
+        continue
+      }
+
+      try {
+        const pluginResults = await this.discoverPluginsInDirectory(directory, _patterns)
+        results.push(...pluginResults)
+      } catch (error) {
+        this.logger?.warn(`Failed to discover plugins in directory '${directory}'`, { error })
+        results.push({
+          success: false,
+          error: `Failed to scan directory: ${error instanceof Error ? error.message : String(error)}`
+        })
+      }
+    }
+
+    return results
+  }
+
+  /**
+   * Load a plugin from file path
+   */
+  async loadPlugin(pluginPath: string): Promise<PluginLoadResult> {
+    try {
+      // Check if manifest exists
+      const manifestPath = join(pluginPath, 'plugin.json')
+      let manifest: PluginManifest | undefined
+
+      if (existsSync(manifestPath)) {
+        const manifestContent = await readFile(manifestPath, 'utf-8')
+        manifest = JSON.parse(manifestContent)
+      }
+
+      // Try to import the plugin
+      const pluginModule = await import(resolve(pluginPath))
+      const plugin: Plugin = pluginModule.default || pluginModule
+
+      if (!plugin || typeof plugin !== 'object' || !plugin.name) {
+        return {
+          success: false,
+          error: 'Invalid plugin: must export a plugin object with a name property'
+        }
+      }
+
+      // Register the plugin
+      await this.register(plugin, manifest)
+
+      return {
+        success: true,
+        plugin,
+        warnings: manifest ? [] : ['No plugin manifest found']
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : String(error)
+      }
+    }
+  }
+
+  /**
+   * Validate plugin structure
+   */
+  private validatePlugin(plugin: Plugin): void {
+    if (!plugin.name || typeof plugin.name !== 'string') {
+      throw new FluxStackError(
+        'Plugin must have a valid name property',
+        'INVALID_PLUGIN_STRUCTURE',
+        400
+      )
+    }
+
+    if (plugin.version && typeof plugin.version !== 'string') {
+      throw new FluxStackError(
+        'Plugin version must be a string',
+        'INVALID_PLUGIN_STRUCTURE',
+        400
+      )
+    }
+
+    if (plugin.dependencies && !Array.isArray(plugin.dependencies)) {
+      throw new FluxStackError(
+        'Plugin dependencies must be an array',
+        'INVALID_PLUGIN_STRUCTURE',
+        400
+      )
+    }
+
+    if (plugin.priority && typeof plugin.priority !== 'number') {
+      throw new FluxStackError(
+        'Plugin priority must be a number',
+        'INVALID_PLUGIN_STRUCTURE',
+        400
+      )
+    }
+  }
+
+  /**
+   * Validate plugin configuration against schema
+   */
+  private validatePluginConfig(plugin: Plugin, config: any): void {
+    if (!plugin.configSchema) {
+      return
+    }
+
+    // Basic validation - in a real implementation, you'd use a proper JSON schema validator
+    if (plugin.configSchema.required) {
+      for (const requiredField of plugin.configSchema.required) {
+        if (!(requiredField in config)) {
+          throw new FluxStackError(
+            `Plugin '${plugin.name}' configuration missing required field: ${requiredField}`,
+            'INVALID_PLUGIN_CONFIG',
+            400
+          )
+        }
+      }
+    }
+  }
+
+  /**
+   * Update the load order based on dependencies and priorities
+   */
+  private updateLoadOrder(): void {
+    const visited = new Set<string>()
+    const visiting = new Set<string>()
+    const order: string[] = []
+
+    const visit = (pluginName: string) => {
+      if (visiting.has(pluginName)) {
+        throw new FluxStackError(
+          `Circular dependency detected involving plugin '${pluginName}'`,
+          'CIRCULAR_DEPENDENCY',
+          400
+        )
+      }
+
+      if (visited.has(pluginName)) {
+        return
+      }
+
+      visiting.add(pluginName)
+
+      const plugin = this.plugins.get(pluginName)
+      if (plugin?.dependencies) {
+        for (const dependency of plugin.dependencies) {
+          if (this.plugins.has(dependency)) {
+            visit(dependency)
+          }
+        }
+      }
+
+      visiting.delete(pluginName)
+      visited.add(pluginName)
+      order.push(pluginName)
+    }
+
+    // Visit all plugins to build dependency order
+    for (const pluginName of this.plugins.keys()) {
+      visit(pluginName)
+    }
+
+    // Sort by priority within dependency groups
+    this.loadOrder = order.sort((a, b) => {
+      const pluginA = this.plugins.get(a)
+      const pluginB = this.plugins.get(b)
+      if (!pluginA || !pluginB) return 0
+      const priorityA = typeof pluginA.priority === 'number' ? pluginA.priority : 0
+      const priorityB = typeof pluginB.priority === 'number' ? pluginB.priority : 0
+      return priorityB - priorityA
+    })
+  }
+
+  /**
+   * Discover plugins in a specific directory
+   */
+  private async discoverPluginsInDirectory(
+    directory: string,
+    _patterns: string[]
+  ): Promise<PluginLoadResult[]> {
+    const results: PluginLoadResult[] = []
+    
+    try {
+      const entries = await readdir(directory, { withFileTypes: true })
+      
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const pluginDir = join(directory, entry.name)
+          
+          // Check if this looks like a plugin directory
+          const hasPluginFile = existsSync(join(pluginDir, 'index.ts')) || 
+                               existsSync(join(pluginDir, 'index.js')) ||
+                               existsSync(join(pluginDir, 'plugin.ts')) ||
+                               existsSync(join(pluginDir, 'plugin.js'))
+          
+          if (hasPluginFile) {
+            const result = await this.loadPlugin(pluginDir)
+            results.push(result)
+          }
+        }
+      }
+    } catch (error) {
+      this.logger?.error(`Failed to read directory '${directory}'`, { error })
+    }
+    
+    return results
+  }
+}

package/core/plugins/types.ts

@@ -0,0 +1,254 @@
+import type { FluxStackConfig } from "../config/schema"
+import type { Logger } from "../utils/logger/index"
+
+export type PluginHook = 
+  | 'setup'
+  | 'onServerStart'
+  | 'onServerStop'
+  | 'onRequest'
+  | 'onBeforeRoute'
+  | 'onResponse'
+  | 'onError'
+  | 'onBuild'
+  | 'onBuildComplete'
+
+export type PluginPriority = 'highest' | 'high' | 'normal' | 'low' | 'lowest' | number
+
+export interface PluginContext {
+  config: FluxStackConfig
+  logger: Logger
+  app: any // Elysia app
+  utils: PluginUtils
+  registry?: any // Plugin registry reference
+}
+
+export interface PluginUtils {
+  // Utility functions that plugins can use
+  createTimer: (label: string) => { end: () => number }
+  formatBytes: (bytes: number) => string
+  isProduction: () => boolean
+  isDevelopment: () => boolean
+  getEnvironment: () => string
+  createHash: (data: string) => string
+  deepMerge: (target: any, source: any) => any
+  validateSchema: (data: any, schema: any) => { valid: boolean; errors: string[] }
+}
+
+export interface RequestContext {
+  request: Request
+  path: string
+  method: string
+  headers: Record<string, string>
+  query: Record<string, string>
+  params: Record<string, string>
+  body?: any
+  user?: any
+  startTime: number
+  handled?: boolean
+  response?: Response
+}
+
+export interface ResponseContext extends RequestContext {
+  response: Response
+  statusCode: number
+  duration: number
+  size?: number
+}
+
+export interface ErrorContext extends RequestContext {
+  error: Error
+  duration: number
+  handled: boolean
+}
+
+export interface BuildContext {
+  target: string
+  outDir: string
+  mode: 'development' | 'production'
+  config: FluxStackConfig
+}
+
+export interface PluginConfigSchema {
+  type: 'object'
+  properties: Record<string, any>
+  required?: string[]
+  additionalProperties?: boolean
+}
+
+export interface Plugin {
+  name: string
+  version?: string
+  description?: string
+  author?: string
+  dependencies?: string[]
+  priority?: number | PluginPriority
+  
+  // Lifecycle hooks
+  setup?: (context: PluginContext) => void | Promise<void>
+  onServerStart?: (context: PluginContext) => void | Promise<void>
+  onServerStop?: (context: PluginContext) => void | Promise<void>
+  onRequest?: (context: RequestContext) => void | Promise<void>
+  onBeforeRoute?: (context: RequestContext) => void | Promise<void>
+  onResponse?: (context: ResponseContext) => void | Promise<void>
+  onError?: (context: ErrorContext) => void | Promise<void>
+  onBuild?: (context: BuildContext) => void | Promise<void>
+  onBuildComplete?: (context: BuildContext) => void | Promise<void>
+  
+  // CLI commands
+  commands?: CliCommand[]
+  
+  // Configuration
+  configSchema?: PluginConfigSchema
+  defaultConfig?: any
+  
+  // Plugin metadata
+  enabled?: boolean
+  tags?: string[]
+  category?: string
+}
+
+export interface PluginManifest {
+  name: string
+  version: string
+  description: string
+  author: string
+  license: string
+  homepage?: string
+  repository?: string
+  keywords: string[]
+  dependencies: Record<string, string>
+  peerDependencies?: Record<string, string>
+  fluxstack: {
+    version: string
+    hooks: PluginHook[]
+    config?: PluginConfigSchema
+    category?: string
+    tags?: string[]
+  }
+}
+
+export interface PluginLoadResult {
+  success: boolean
+  plugin?: Plugin
+  error?: string
+  warnings?: string[]
+}
+
+export interface PluginRegistryState {
+  plugins: Map<string, Plugin>
+  manifests: Map<string, PluginManifest>
+  loadOrder: string[]
+  dependencies: Map<string, string[]>
+  conflicts: string[]
+}
+
+export interface PluginHookResult {
+  success: boolean
+  error?: Error
+  duration: number
+  plugin: string
+  hook: PluginHook
+  context?: any
+}
+
+export interface PluginMetrics {
+  loadTime: number
+  setupTime: number
+  hookExecutions: Map<PluginHook, number>
+  errors: number
+  warnings: number
+  lastExecution?: Date
+}
+
+export interface PluginDiscoveryOptions {
+  directories?: string[]
+  patterns?: string[]
+  includeBuiltIn?: boolean
+  includeExternal?: boolean
+  includeNpm?: boolean
+}
+
+export interface PluginInstallOptions {
+  version?: string
+  registry?: string
+  force?: boolean
+  dev?: boolean
+  source?: 'npm' | 'git' | 'local'
+}
+
+export interface PluginExecutionContext {
+  plugin: Plugin
+  hook: PluginHook
+  startTime: number
+  timeout?: number
+  retries?: number
+}
+
+export interface PluginValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+}
+
+// Plugin hook execution options
+export interface HookExecutionOptions {
+  timeout?: number
+  parallel?: boolean
+  stopOnError?: boolean
+  retries?: number
+}
+
+// Plugin lifecycle events
+export type PluginLifecycleEvent = 
+  | 'plugin:registered'
+  | 'plugin:unregistered'
+  | 'plugin:enabled'
+  | 'plugin:disabled'
+  | 'plugin:error'
+  | 'hook:before'
+  | 'hook:after'
+  | 'hook:error'
+
+// CLI Command interfaces
+export interface CliArgument {
+  name: string
+  description: string
+  required?: boolean
+  type?: 'string' | 'number' | 'boolean'
+  default?: any
+  choices?: string[]
+}
+
+export interface CliOption {
+  name: string
+  short?: string
+  description: string
+  type?: 'string' | 'number' | 'boolean' | 'array'
+  default?: any
+  required?: boolean
+  choices?: string[]
+}
+
+export interface CliCommand {
+  name: string
+  description: string
+  usage?: string
+  examples?: string[]
+  arguments?: CliArgument[]
+  options?: CliOption[]
+  aliases?: string[]
+  category?: string
+  hidden?: boolean
+  handler: (args: any[], options: any, context: CliContext) => Promise<void> | void
+}
+
+export interface CliContext {
+  config: FluxStackConfig
+  logger: Logger
+  utils: PluginUtils
+  workingDir: string
+  packageInfo: {
+    name: string
+    version: string
+  }
+}