cabriolet 0.1.2 → 0.2.0

data/lib/cabriolet/plugin.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  # Base class for all Cabriolet plugins
+  #
+  # Plugins extend Cabriolet's functionality by providing custom compression
+  # algorithms, format handlers, or other enhancements. All plugins must
+  # inherit from this base class and implement required methods.
+  #
+  # @abstract Subclass and implement {#metadata} and {#setup} to create
+  #   a plugin
+  #
+  # @example Creating a simple plugin
+  #   class MyPlugin < Cabriolet::Plugin
+  #     def metadata
+  #       {
+  #         name: "my-plugin",
+  #         version: "1.0.0",
+  #         author: "Your Name",
+  #         description: "Adds custom compression algorithm",
+  #         cabriolet_version: "~> 0.1"
+  #       }
+  #     end
+  #
+  #     def setup
+  #       register_algorithm(:custom, CustomAlgorithm,
+  #                         category: :compressor)
+  #     end
+  #   end
+  class Plugin
+    # Plugin states
+    STATES = %i[discovered loaded active failed disabled].freeze
+
+    # @return [Symbol] Current plugin state
+    attr_reader :state
+
+    # Initialize a new plugin
+    #
+    # @param manager [PluginManager] The plugin manager instance
+    def initialize(manager = nil)
+      @manager = manager
+      @state = :discovered
+    end
+
+    # Get plugin metadata
+    #
+    # @abstract Must be implemented by subclasses
+    #
+    # @return [Hash] Plugin metadata containing:
+    # @option return [String] :name Plugin name (required)
+    # @option return [String] :version Plugin version (required)
+    # @option return [String] :author Plugin author (required)
+    # @option return [String] :description Plugin description (required)
+    # @option return [String] :cabriolet_version Compatible Cabriolet
+    #   version (required)
+    # @option return [String] :homepage Plugin homepage URL (optional)
+    # @option return [String] :license Plugin license (optional)
+    # @option return [Array<String>] :dependencies Plugin dependencies
+    #   (optional)
+    # @option return [Array<String>] :tags Search tags (optional)
+    # @option return [Hash] :provides What the plugin provides (optional)
+    #
+    # @raise [NotImplementedError] If not implemented by subclass
+    #
+    # @example Minimal metadata
+    #   def metadata
+    #     {
+    #       name: "my-plugin",
+    #       version: "1.0.0",
+    #       author: "Your Name",
+    #       description: "Plugin description",
+    #       cabriolet_version: "~> 0.1"
+    #     }
+    #   end
+    #
+    # @example Full metadata
+    #   def metadata
+    #     {
+    #       name: "advanced-plugin",
+    #       version: "2.0.0",
+    #       author: "Developer",
+    #       description: "Advanced features",
+    #       cabriolet_version: ">= 0.1.0",
+    #       homepage: "https://example.com",
+    #       license: "MIT",
+    #       dependencies: ["other-plugin >= 1.0"],
+    #       tags: ["compression", "algorithm"],
+    #       provides: { algorithms: [:custom], formats: [:special] }
+    #     }
+    #   end
+    def metadata
+      raise NotImplementedError,
+            "#{self.class} must implement metadata method"
+    end
+
+    # Setup the plugin
+    #
+    # Called when the plugin is loaded. Use this method to register
+    # algorithms, formats, or perform other initialization tasks.
+    #
+    # @abstract Must be implemented by subclasses
+    #
+    # @raise [NotImplementedError] If not implemented by subclass
+    #
+    # @example Register an algorithm
+    #   def setup
+    #     register_algorithm(:myalgo, MyAlgorithm,
+    #                       category: :compressor)
+    #   end
+    #
+    # @example Register multiple items
+    #   def setup
+    #     register_algorithm(:algo1, Algo1, category: :compressor)
+    #     register_algorithm(:algo2, Algo2, category: :decompressor)
+    #     register_format(:myformat, MyFormatHandler)
+    #   end
+    def setup
+      raise NotImplementedError,
+            "#{self.class} must implement setup method"
+    end
+
+    # Activate the plugin
+    #
+    # Called when the plugin is activated. Override to perform actions
+    # when the plugin becomes active.
+    #
+    # @return [void]
+    #
+    # @example Add hooks on activation
+    #   def activate
+    #     puts "#{metadata[:name]} activated"
+    #     # Additional activation logic...
+    #   end
+    def activate
+      # Default implementation does nothing
+    end
+
+    # Deactivate the plugin
+    #
+    # Called when the plugin is deactivated. Override to perform cleanup
+    # when the plugin is deactivated.
+    #
+    # @return [void]
+    #
+    # @example Cleanup on deactivation
+    #   def deactivate
+    #     # Cleanup resources...
+    #     puts "#{metadata[:name]} deactivated"
+    #   end
+    def deactivate
+      # Default implementation does nothing
+    end
+
+    # Cleanup the plugin
+    #
+    # Called when the plugin is unloaded. Override to perform final
+    # cleanup tasks.
+    #
+    # @return [void]
+    #
+    # @example Final cleanup
+    #   def cleanup
+    #     # Release resources...
+    #     # Close connections...
+    #   end
+    def cleanup
+      # Default implementation does nothing
+    end
+
+    protected
+
+    # Register a compression or decompression algorithm
+    #
+    # @param type [Symbol] Algorithm type identifier
+    # @param klass [Class] Algorithm class
+    # @param options [Hash] Registration options
+    # @option options [Symbol] :category Required - :compressor or
+    #   :decompressor
+    # @option options [Integer] :priority Algorithm priority (default: 0)
+    # @option options [Symbol, nil] :format Format restriction (optional)
+    #
+    # @return [void]
+    #
+    # @raise [PluginError] If manager is not available
+    #
+    # @example Register a compressor
+    #   register_algorithm(:myalgo, MyCompressor,
+    #                     category: :compressor, priority: 10)
+    #
+    # @example Register a format-specific decompressor
+    #   register_algorithm(:special, SpecialDecompressor,
+    #                     category: :decompressor, format: :cab)
+    def register_algorithm(type, klass, **options)
+      raise PluginError, "Plugin manager not available" unless @manager
+
+      Cabriolet.algorithm_factory.register(type, klass, **options)
+    end
+
+    # Register a format handler
+    #
+    # @param format [Symbol] Format identifier
+    # @param handler [Class] Format handler class
+    #
+    # @return [void]
+    #
+    # @raise [PluginError] If manager is not available
+    #
+    # @example Register a format handler
+    #   register_format(:myformat, MyFormatHandler)
+    def register_format(format, handler)
+      raise PluginError, "Plugin manager not available" unless @manager
+
+      # Format registration will be implemented when format registry exists
+      # For now, store in manager's format registry
+      @manager.register_format(format, handler)
+    end
+
+    # Update plugin state
+    #
+    # @param new_state [Symbol] New state (must be in STATES)
+    #
+    # @return [void]
+    #
+    # @raise [ArgumentError] If state is invalid
+    def update_state(new_state)
+      unless STATES.include?(new_state)
+        raise ArgumentError, "Invalid state: #{new_state}"
+      end
+
+      @state = new_state
+    end
+  end
+end

data/lib/cabriolet/plugin_manager.rb

@@ -0,0 +1,453 @@
+# frozen_string_literal: true
+
+require "singleton"
+require "yaml"
+
+module Cabriolet
+  # Manages plugin lifecycle and registry for Cabriolet
+  #
+  # The PluginManager is a thread-safe singleton that handles plugin
+  # discovery, loading, activation, and deactivation. It maintains plugin
+  # states and resolves dependencies.
+  #
+  # @example Access the plugin manager
+  #   manager = Cabriolet::PluginManager.instance
+  #   manager.discover_plugins
+  #   manager.load_plugin("my-plugin")
+  #   manager.activate_plugin("my-plugin")
+  #
+  # @example Using global accessor
+  #   Cabriolet.plugin_manager.discover_plugins
+  #   Cabriolet.plugin_manager.list_plugins(state: :active)
+  class PluginManager
+    include Singleton
+
+    # @return [Hash] Plugin registry by name
+    attr_reader :plugins
+
+    # @return [Hash] Format registry
+    attr_reader :formats
+
+    # Initialize the plugin manager
+    def initialize
+      @plugins = {}
+      @formats = {}
+      @mutex = Mutex.new
+      @config = load_config
+    end
+
+    # Discover available plugins
+    #
+    # Searches for plugins in gem paths using the pattern
+    # 'cabriolet/plugins/**/*.rb'. Discovered plugins are added to the
+    # registry in :discovered state.
+    #
+    # @return [Array<String>] List of discovered plugin names
+    #
+    # @example Discover plugins
+    #   manager.discover_plugins
+    #   #=> ["plugin1", "plugin2"]
+    def discover_plugins
+      @mutex.synchronize do
+        plugin_files = Gem.find_files("cabriolet/plugins/**/*.rb")
+
+        plugin_files.each do |file|
+          load_plugin_file(file)
+        rescue StandardError => e
+          warn "Failed to load plugin from #{file}: #{e.message}"
+        end
+
+        @plugins.keys
+      end
+    end
+
+    # Register a plugin instance
+    #
+    # Adds a plugin to the registry. The plugin must be a valid Plugin
+    # instance with proper metadata.
+    #
+    # @param plugin_instance [Plugin] Plugin instance to register
+    #
+    # @return [Boolean] True if registered successfully
+    #
+    # @raise [PluginError] If plugin is invalid
+    #
+    # @example Register a plugin
+    #   plugin = MyPlugin.new(manager)
+    #   manager.register(plugin)
+    def register(plugin_instance)
+      @mutex.synchronize do
+        unless plugin_instance.is_a?(Plugin)
+          raise PluginError,
+                "Plugin must inherit from Cabriolet::Plugin"
+        end
+
+        # Validate plugin
+        validation = PluginValidator.validate(plugin_instance.class)
+        unless validation[:valid]
+          raise PluginError,
+                "Plugin validation failed: #{validation[:errors].join(', ')}"
+        end
+
+        meta = plugin_instance.metadata
+        name = meta[:name]
+
+        if @plugins.key?(name)
+          raise PluginError, "Plugin '#{name}' already registered"
+        end
+
+        @plugins[name] = {
+          instance: plugin_instance,
+          metadata: meta,
+          state: :discovered,
+        }
+
+        true
+      end
+    end
+
+    # Load a plugin
+    #
+    # Loads and validates a discovered plugin. Calls the plugin's setup
+    # method and transitions to :loaded state.
+    #
+    # @param name [String] Plugin name
+    #
+    # @return [Boolean] True if loaded successfully
+    #
+    # @raise [PluginError] If plugin not found or load fails
+    #
+    # @example Load a plugin
+    #   manager.load_plugin("my-plugin")
+    def load_plugin(name)
+      @mutex.synchronize do
+        entry = @plugins[name]
+        raise PluginError, "Plugin '#{name}' not found" unless entry
+
+        if %i[loaded active].include?(entry[:state])
+          return true
+        end
+
+        begin
+          plugin = entry[:instance]
+
+          # Check dependencies
+          check_dependencies!(entry[:metadata])
+
+          # Call setup
+          plugin.setup
+          plugin.send(:update_state, :loaded)
+          entry[:state] = :loaded
+
+          true
+        rescue StandardError => e
+          plugin.send(:update_state, :failed)
+          entry[:state] = :failed
+          entry[:error] = e.message
+          raise PluginError, "Failed to load plugin '#{name}': #{e.message}"
+        end
+      end
+    end
+
+    # Activate a plugin
+    #
+    # Activates a loaded plugin. Calls the plugin's activate method and
+    # transitions to :active state.
+    #
+    # @param name [String] Plugin name
+    #
+    # @return [Boolean] True if activated successfully
+    #
+    # @raise [PluginError] If plugin not found or not loaded
+    #
+    # @example Activate a plugin
+    #   manager.activate_plugin("my-plugin")
+    def activate_plugin(name)
+      @mutex.synchronize do
+        entry = @plugins[name]
+        raise PluginError, "Plugin '#{name}' not found" unless entry
+
+        if entry[:state] == :active
+          return true
+        end
+
+        unless entry[:state] == :loaded
+          raise PluginError,
+                "Plugin '#{name}' must be loaded before activation"
+        end
+
+        begin
+          plugin = entry[:instance]
+          plugin.activate
+          plugin.send(:update_state, :active)
+          entry[:state] = :active
+
+          true
+        rescue StandardError => e
+          plugin.send(:update_state, :failed)
+          entry[:state] = :failed
+          entry[:error] = e.message
+          raise PluginError,
+                "Failed to activate plugin '#{name}': #{e.message}"
+        end
+      end
+    end
+
+    # Deactivate a plugin
+    #
+    # Deactivates an active plugin. Calls the plugin's deactivate method
+    # and transitions back to :loaded state.
+    #
+    # @param name [String] Plugin name
+    #
+    # @return [Boolean] True if deactivated successfully
+    #
+    # @raise [PluginError] If plugin not found
+    #
+    # @example Deactivate a plugin
+    #   manager.deactivate_plugin("my-plugin")
+    def deactivate_plugin(name)
+      @mutex.synchronize do
+        entry = @plugins[name]
+        raise PluginError, "Plugin '#{name}' not found" unless entry
+
+        if entry[:state] != :active
+          return true
+        end
+
+        begin
+          plugin = entry[:instance]
+          plugin.deactivate
+          plugin.send(:update_state, :loaded)
+          entry[:state] = :loaded
+
+          true
+        rescue StandardError => e
+          entry[:error] = e.message
+          raise PluginError,
+                "Failed to deactivate plugin '#{name}': #{e.message}"
+        end
+      end
+    end
+
+    # List plugins
+    #
+    # Returns plugin information, optionally filtered by state.
+    #
+    # @param state [Symbol, nil] Optional state filter (:discovered,
+    #   :loaded, :active, :failed, :disabled)
+    #
+    # @return [Hash] Plugin information keyed by name
+    #
+    # @example List all plugins
+    #   manager.list_plugins
+    #   #=> { "plugin1" => {...}, "plugin2" => {...} }
+    #
+    # @example List only active plugins
+    #   manager.list_plugins(state: :active)
+    #   #=> { "active-plugin" => {...} }
+    def list_plugins(state: nil)
+      @mutex.synchronize do
+        if state.nil?
+          @plugins.transform_values do |entry|
+            {
+              metadata: entry[:metadata],
+              state: entry[:state],
+              error: entry[:error],
+            }
+          end
+        else
+          @plugins.select { |_, entry| entry[:state] == state }
+            .transform_values do |entry|
+              {
+                metadata: entry[:metadata],
+                state: entry[:state],
+                error: entry[:error],
+              }
+          end
+        end
+      end
+    end
+
+    # Get a plugin by name
+    #
+    # @param name [String] Plugin name
+    #
+    # @return [Plugin, nil] Plugin instance or nil if not found
+    #
+    # @example Get a plugin
+    #   plugin = manager.plugin("my-plugin")
+    def plugin(name)
+      @mutex.synchronize do
+        @plugins[name]&.dig(:instance)
+      end
+    end
+
+    # Check if a plugin is active
+    #
+    # @param name [String] Plugin name
+    #
+    # @return [Boolean] True if plugin is active
+    #
+    # @example Check plugin status
+    #   manager.plugin_active?("my-plugin") #=> true
+    def plugin_active?(name)
+      @mutex.synchronize do
+        @plugins[name]&.dig(:state) == :active
+      end
+    end
+
+    # Register a format handler
+    #
+    # Called by plugins to register format handlers. This is used
+    # internally by Plugin#register_format.
+    #
+    # @param format [Symbol] Format identifier
+    # @param handler [Class] Handler class
+    #
+    # @return [void]
+    #
+    # @api private
+    def register_format(format, handler)
+      @mutex.synchronize do
+        @formats[format] = handler
+      end
+    end
+
+    # Get format handler
+    #
+    # @param format [Symbol] Format identifier
+    #
+    # @return [Class, nil] Handler class or nil
+    #
+    # @example Get format handler
+    #   handler = manager.format_handler(:myformat)
+    def format_handler(format)
+      @mutex.synchronize do
+        @formats[format]
+      end
+    end
+
+    private
+
+    # Load configuration from ~/.cabriolet/plugins.yml
+    #
+    # @return [Hash] Configuration hash
+    def load_config
+      config_path = File.expand_path("~/.cabriolet/plugins.yml")
+      return {} unless File.exist?(config_path)
+
+      YAML.load_file(config_path) || {}
+    rescue StandardError => e
+      warn "Failed to load plugin config: #{e.message}"
+      {}
+    end
+
+    # Load a plugin file
+    #
+    # @param file [String] Plugin file path
+    #
+    # @return [void]
+    def load_plugin_file(file)
+      require file
+
+      # After requiring, plugin classes should auto-register
+      # This is a convention - plugins call register in their class body
+    end
+
+    # Check plugin dependencies
+    #
+    # @param metadata [Hash] Plugin metadata
+    #
+    # @return [void]
+    #
+    # @raise [PluginError] If dependencies not met
+    def check_dependencies!(metadata)
+      dependencies = metadata[:dependencies] || []
+
+      dependencies.each do |dep|
+        dep_name, dep_version = parse_dependency(dep)
+
+        unless @plugins.key?(dep_name)
+          raise PluginError,
+                "Missing dependency: #{dep_name}"
+        end
+
+        dep_entry = @plugins[dep_name]
+        unless %i[loaded active].include?(dep_entry[:state])
+          raise PluginError,
+                "Dependency '#{dep_name}' not loaded"
+        end
+
+        if dep_version
+          actual_version = dep_entry[:metadata][:version]
+          unless version_satisfies?(actual_version, dep_version)
+            raise PluginError,
+                  "Dependency '#{dep_name}' version mismatch: " \
+                  "need #{dep_version}, have #{actual_version}"
+          end
+        end
+      end
+    end
+
+    # Parse dependency string
+    #
+    # @param dep [String] Dependency string (e.g., "plugin >= 1.0")
+    #
+    # @return [Array<String, String>] [name, version_requirement]
+    def parse_dependency(dep)
+      parts = dep.split
+      name = parts[0]
+      version = parts[1..].join(" ") if parts.length > 1
+
+      [name, version]
+    end
+
+    # Check if version satisfies requirement
+    #
+    # @param version [String] Actual version
+    # @param requirement [String] Version requirement
+    #
+    # @return [Boolean] True if satisfied
+    def version_satisfies?(version, requirement)
+      # Simple version check - can be enhanced with gem version logic
+      return true if requirement.nil?
+
+      # Parse requirement (e.g., ">= 1.0", "~> 2.0", "= 1.5")
+      if requirement.start_with?(">=")
+        min_version = requirement.sub(">=", "").strip
+        compare_versions(version, min_version) >= 0
+      elsif requirement.start_with?("~>")
+        # Pessimistic version constraint
+        base = requirement.sub("~>", "").strip
+        compare_versions(version, base) >= 0
+      elsif requirement.start_with?("=")
+        exact = requirement.sub("=", "").strip
+        version == exact
+      else
+        true
+      end
+    end
+
+    # Compare two version strings
+    #
+    # @param v1 [String] Version 1
+    # @param v2 [String] Version 2
+    #
+    # @return [Integer] -1, 0, or 1
+    def compare_versions(v1, v2)
+      parts1 = v1.split(".").map(&:to_i)
+      parts2 = v2.split(".").map(&:to_i)
+
+      [parts1.length, parts2.length].max.times do |i|
+        p1 = parts1[i] || 0
+        p2 = parts2[i] || 0
+
+        return -1 if p1 < p2
+        return 1 if p1 > p2
+      end
+
+      0
+    end
+  end
+end