not_pressed-core 0.1.0

data/lib/not_pressed/plugin.rb

@@ -0,0 +1,354 @@
+# frozen_string_literal: true
+
+module NotPressed
+  # Base class for all NotPressed plugins.
+  #
+  # Provides a class-level DSL for declaring metadata, hooks, filters,
+  # block types, admin menus, settings, dependencies, and routes.
+  # Instance methods handle activation/deactivation lifecycle and
+  # namespaced settings access.
+  #
+  # @example Defining a plugin
+  #   class MyPlugin < NotPressed::Plugin
+  #     name "my_plugin"
+  #     version "1.0.0"
+  #     description "Does useful things"
+  #
+  #     on :after_page_save do |page|
+  #       Rails.logger.info "Saved: #{page.title}"
+  #     end
+  #
+  #     settings do
+  #       string :api_key, label: "API Key"
+  #     end
+  #   end
+  class Plugin
+    class << self
+      # @api private
+      def inherited(subclass)
+        subclass.instance_variable_set(:@plugin_hooks, [])
+        subclass.instance_variable_set(:@plugin_filters, [])
+        subclass.instance_variable_set(:@plugin_block_types, [])
+        subclass.instance_variable_set(:@plugin_admin_menus, [])
+        subclass.instance_variable_set(:@plugin_settings_schema, [])
+        subclass.instance_variable_set(:@plugin_dependencies, [])
+        subclass.instance_variable_set(:@plugin_routes, [])
+        super
+      end
+
+      # Sets or gets the plugin name. Required for registration.
+      #
+      # @param val [String, nil] the plugin name to set, or nil to read
+      # @return [String, nil] the current plugin name
+      def name(val = nil)
+        val ? @plugin_name = val : @plugin_name
+      end
+
+      # Sets or gets the plugin version.
+      #
+      # @param val [String, nil] the version string to set, or nil to read
+      # @return [String, nil] the current version
+      def version(val = nil)
+        val ? @plugin_version = val : @plugin_version
+      end
+
+      # Sets or gets the plugin description.
+      #
+      # @param val [String, nil] the description to set, or nil to read
+      # @return [String, nil] the current description
+      def description(val = nil)
+        val ? @plugin_description = val : @plugin_description
+      end
+
+      # Sets or gets the plugin author.
+      #
+      # @param val [String, nil] the author to set, or nil to read
+      # @return [String, nil] the current author
+      def author(val = nil)
+        val ? @plugin_author = val : @plugin_author
+      end
+
+      # Sets or gets the plugin URL.
+      #
+      # @param val [String, nil] the URL to set, or nil to read
+      # @return [String, nil] the current URL
+      def url(val = nil)
+        val ? @plugin_url = val : @plugin_url
+      end
+
+      # @return [String, nil] the declared plugin name
+      def plugin_name
+        @plugin_name
+      end
+
+      # @return [String, nil] the declared plugin version
+      def plugin_version
+        @plugin_version
+      end
+
+      # @return [String, nil] the declared plugin description
+      def plugin_description
+        @plugin_description
+      end
+
+      # @return [String, nil] the declared plugin author
+      def plugin_author
+        @plugin_author
+      end
+
+      # @return [String, nil] the declared plugin URL
+      def plugin_url
+        @plugin_url
+      end
+
+      # Registers a hook callback for the given event.
+      #
+      # @param event [Symbol] the hook event name
+      # @yield the callback block invoked when the event fires
+      # @return [void]
+      def on(event, &block)
+        @plugin_hooks << { event: event, callback: block }
+      end
+
+      # @return [Array<Hash>] registered hook entries with :event and :callback keys
+      def plugin_hooks
+        @plugin_hooks
+      end
+
+      # Registers a filter callback that transforms values through a chain.
+      #
+      # @param name [Symbol] the filter name
+      # @yield [value, *args] receives the current value and extra arguments
+      # @return [void]
+      def filter(name, &block)
+        @plugin_filters << { name: name, callback: block }
+      end
+
+      # @return [Array<Hash>] registered filter entries with :name and :callback keys
+      def plugin_filters
+        @plugin_filters
+      end
+
+      # Declares a custom content block type provided by this plugin.
+      #
+      # @param name [Symbol, String] block type identifier
+      # @param options [Hash] additional options for the block type
+      # @return [void]
+      def block_type(name, **options)
+        @plugin_block_types << { name: name, options: options }
+      end
+
+      # @return [Array<Hash>] registered block type entries
+      def plugin_block_types
+        @plugin_block_types
+      end
+
+      # Adds an entry to the admin sidebar when the plugin is active.
+      #
+      # @param label [String] display label for the menu item
+      # @param path [Symbol, String] route helper name or URL path
+      # @param icon [String, nil] icon identifier
+      # @return [void]
+      def admin_menu(label, path:, icon: nil)
+        @plugin_admin_menus << { label: label, path: path, icon: icon }
+      end
+
+      # @return [Array<Hash>] registered admin menu entries
+      def plugin_admin_menus
+        @plugin_admin_menus
+      end
+
+      # Defines a settings schema using the SettingsBuilder DSL.
+      #
+      # @yield block evaluated in the context of a {NotPressed::SettingsBuilder}
+      # @return [void]
+      def settings(&block)
+        builder = SettingsBuilder.new
+        builder.instance_eval(&block)
+        @plugin_settings_schema = builder.schema
+      end
+
+      # @return [Array<Hash>] the settings schema fields
+      def plugin_settings_schema
+        @plugin_settings_schema
+      end
+
+      # Declares a dependency on another plugin that must be active first.
+      #
+      # @param name [String] name of the required plugin
+      # @param constraint [String, nil] version constraint (currently unused)
+      # @return [void]
+      def depends_on(name, constraint = nil)
+        @plugin_dependencies << { name: name, constraint: constraint }
+      end
+
+      # @return [Array<Hash>] declared dependency entries
+      def plugin_dependencies
+        @plugin_dependencies
+      end
+
+      # Stores a routing block for the plugin.
+      #
+      # @yield routing DSL block
+      # @return [void]
+      def routes(&block)
+        @plugin_routes << block
+      end
+
+      # @return [Array<Proc>] stored route blocks
+      def plugin_routes
+        @plugin_routes
+      end
+    end
+
+    # Instance methods — settings
+
+    # Reads a namespaced setting value from the database.
+    #
+    # @param key [Symbol, String] the setting key (auto-prefixed with +plugin.<name>.+)
+    # @return [String, nil] the stored value
+    def get_setting(key)
+      namespaced_key = "plugin.#{self.class.plugin_name}.#{key}"
+      NotPressed::Setting.get(namespaced_key)
+    end
+
+    # Writes a namespaced setting value to the database.
+    #
+    # @param key [Symbol, String] the setting key
+    # @param value [Object] the value to store (converted to string)
+    # @return [NotPressed::Setting] the saved setting record
+    def set_setting(key, value)
+      namespaced_key = "plugin.#{self.class.plugin_name}.#{key}"
+      NotPressed::Setting.set(namespaced_key, value.to_s)
+    end
+
+    # Returns a hash of all settings defined in the schema with their current values.
+    #
+    # @return [Hash{String => String, nil}] setting keys mapped to stored values
+    def settings_values
+      schema = self.class.plugin_settings_schema || []
+      schema.each_with_object({}) do |field, hash|
+        hash[field[:key].to_s] = get_setting(field[:key])
+      end
+    end
+
+    # Instance methods (lifecycle)
+
+    # Activates the plugin by registering all hooks, filters, block types,
+    # and admin menus with the engine's global registries.
+    #
+    # @return [true]
+    def activate!
+      self.class.plugin_hooks.each do |hook|
+        NotPressed::Hooks.register(hook[:event], &hook[:callback])
+      end
+      self.class.plugin_filters.each do |filter|
+        NotPressed::Hooks.register_filter(filter[:name], &filter[:callback])
+      end
+      self.class.plugin_block_types.each do |bt|
+        NotPressed::ContentBlock.register_type(bt[:name].to_s)
+      end
+      self.class.plugin_admin_menus.each do |menu|
+        NotPressed::Admin::MenuRegistry.register(
+          menu[:label],
+          path: menu[:path],
+          icon: menu[:icon],
+          section: :main,
+          position: 100
+        )
+      end
+      @active = true
+    end
+
+    # Deactivates the plugin by unregistering all hooks, filters, block types,
+    # and admin menus from the engine's global registries.
+    #
+    # @return [false]
+    def deactivate!
+      self.class.plugin_hooks.each do |hook|
+        NotPressed::Hooks.unregister(hook[:event], hook[:callback])
+      end
+      self.class.plugin_filters.each do |filter|
+        NotPressed::Hooks.unregister_filter(filter[:name], filter[:callback])
+      end
+      self.class.plugin_block_types.each do |bt|
+        NotPressed::ContentBlock.custom_types.delete(bt[:name].to_s)
+      end
+      self.class.plugin_admin_menus.each do |menu|
+        NotPressed::Admin::MenuRegistry.unregister(menu[:label], path: menu[:path])
+      end
+      @active = false
+    end
+
+    # Returns whether this plugin instance is currently active.
+    #
+    # @return [Boolean]
+    def active?
+      @active || false
+    end
+  end
+
+  # DSL builder for defining plugin settings schemas.
+  #
+  # Used inside a +Plugin.settings+ block to declare typed fields.
+  #
+  # @example
+  #   settings do
+  #     string :api_key, label: "API Key"
+  #     boolean :enabled, label: "Enabled", default: true
+  #     integer :max_items, label: "Max Items"
+  #   end
+  class SettingsBuilder
+    # @return [Array<Hash>] the accumulated schema fields
+    attr_reader :schema
+
+    def initialize
+      @schema = []
+    end
+
+    # Declares a string setting field.
+    #
+    # @param key [Symbol] field identifier
+    # @param options [Hash] additional options (e.g., :label, :default)
+    # @return [void]
+    def string(key, **options)
+      @schema << { type: :string, key: key }.merge(options)
+    end
+
+    # Declares a text (multiline) setting field.
+    #
+    # @param key [Symbol] field identifier
+    # @param options [Hash] additional options
+    # @return [void]
+    def text(key, **options)
+      @schema << { type: :text, key: key }.merge(options)
+    end
+
+    # Declares a boolean setting field.
+    #
+    # @param key [Symbol] field identifier
+    # @param options [Hash] additional options
+    # @return [void]
+    def boolean(key, **options)
+      @schema << { type: :boolean, key: key }.merge(options)
+    end
+
+    # Declares a select (dropdown) setting field.
+    #
+    # @param key [Symbol] field identifier
+    # @param options [Hash] additional options (should include :choices)
+    # @return [void]
+    def select(key, **options)
+      @schema << { type: :select, key: key }.merge(options)
+    end
+
+    # Declares an integer setting field.
+    #
+    # @param key [Symbol] field identifier
+    # @param options [Hash] additional options
+    # @return [void]
+    def integer(key, **options)
+      @schema << { type: :integer, key: key }.merge(options)
+    end
+  end
+end

data/lib/not_pressed/plugin_importer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "zip"
+require "json"
+
+module NotPressed
+  # Imports a plugin from an exported zip archive.
+  #
+  # Validates the archive structure, checks for duplicates, prevents
+  # path traversal attacks, and extracts files to the Rails root.
+  #
+  # @example
+  #   result = NotPressed::PluginImporter.new("/tmp/analytics-1.0.0.zip").import!
+  #   result[:name]            #=> "Analytics"
+  #   result[:files_installed] #=> ["app/plugins/not_pressed/analytics_plugin.rb"]
+  class PluginImporter
+    # Raised when the zip archive is invalid, missing manifest, or contains
+    # dangerous paths.
+    class InvalidArchive < StandardError; end
+
+    # Raised when a plugin with the same name is already registered.
+    class DuplicatePlugin < StandardError; end
+
+    # @param zip_path [String] path to the plugin zip archive
+    # @param force [Boolean] when true, overwrites an existing plugin with the same name
+    def initialize(zip_path, force: false)
+      @zip_path = zip_path
+      @force = force
+    end
+
+    # Validates and extracts the plugin archive.
+    #
+    # @return [Hash] result with :name, :version, :files_installed, :path keys
+    # @raise [ArgumentError] if the zip file does not exist
+    # @raise [InvalidArchive] if the archive is corrupt, missing manifest, or contains path traversal
+    # @raise [DuplicatePlugin] if a plugin with the same name is already registered (unless force: true)
+    def import!
+      validate_file_exists!
+      manifest = read_manifest
+      validate_manifest!(manifest)
+      check_duplicate!(manifest["name"])
+      files = validate_paths!(manifest["files"])
+      extract_files!(files)
+
+      {
+        name: manifest["name"],
+        version: manifest["version"],
+        files_installed: files,
+        path: @zip_path
+      }
+    end
+
+    private
+
+    # Raises ArgumentError if the zip file path does not exist.
+    def validate_file_exists!
+      raise ArgumentError, "Zip file does not exist: #{@zip_path}" unless File.exist?(@zip_path)
+    end
+
+    # Opens the zip and reads/parses manifest.json.
+    #
+    # @return [Hash] parsed manifest data
+    # @raise [InvalidArchive] if the zip is corrupt or missing manifest.json
+    def read_manifest
+      Zip::File.open(@zip_path) do |zip|
+        entry = zip.find_entry("manifest.json")
+        raise InvalidArchive, "Archive is missing manifest.json" unless entry
+
+        JSON.parse(entry.get_input_stream.read)
+      end
+    rescue Zip::Error
+      raise InvalidArchive, "Archive is not a valid zip file"
+    end
+
+    # Validates that the manifest contains required fields.
+    #
+    # @param manifest [Hash] parsed manifest data
+    # @raise [InvalidArchive] if required fields are missing
+    def validate_manifest!(manifest)
+      raise InvalidArchive, "Manifest is missing required field: name" unless manifest["name"].is_a?(String) && !manifest["name"].empty?
+      raise InvalidArchive, "Manifest is missing required field: version" unless manifest["version"]
+      raise InvalidArchive, "Manifest is missing required field: files" unless manifest["files"].is_a?(Array)
+    end
+
+    # Checks whether a plugin with the given name is already registered.
+    #
+    # @param name [String] the plugin name from the manifest
+    # @raise [DuplicatePlugin] if the name exists and force is false
+    def check_duplicate!(name)
+      return if @force
+
+      if PluginManager.registered.key?(name)
+        raise DuplicatePlugin, "Plugin '#{name}' is already registered. Use force: true to overwrite."
+      end
+    end
+
+    # Validates that all file paths are safe (no path traversal).
+    #
+    # @param files [Array<String>] relative file paths from manifest
+    # @return [Array<String>] the validated file paths
+    # @raise [InvalidArchive] if any path escapes the Rails root
+    def validate_paths!(files)
+      root = Rails.root.to_s
+
+      files.each do |relative_path|
+        absolute = File.expand_path(File.join(root, relative_path))
+        unless absolute.start_with?(root)
+          raise InvalidArchive, "Path traversal detected in archive entry: #{relative_path}"
+        end
+      end
+
+      files
+    end
+
+    # Extracts the listed files from the zip into the Rails root.
+    #
+    # @param files [Array<String>] relative file paths to extract
+    def extract_files!(files)
+      root = Rails.root.to_s
+
+      Zip::File.open(@zip_path) do |zip|
+        files.each do |relative_path|
+          entry = zip.find_entry(relative_path)
+          next unless entry
+
+          dest = File.join(root, relative_path)
+          FileUtils.mkdir_p(File.dirname(dest))
+          File.write(dest, entry.get_input_stream.read)
+        end
+      end
+    end
+  end
+end

data/lib/not_pressed/plugin_manager.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module NotPressed
+  # Thread-safe module for registering, enabling, disabling, and discovering plugins.
+  #
+  # Manages the full plugin lifecycle including dependency resolution.
+  # All public methods are synchronized via an internal mutex.
+  module PluginManager
+    # Raised when a plugin name is not found in the registry.
+    class NotFound < StandardError; end
+
+    # Raised when a plugin has unmet dependencies that prevent activation.
+    class DependencyError < StandardError; end
+
+    class << self
+      # Registration
+
+      # Registers a plugin class in the registry.
+      #
+      # @param plugin_class [Class] a subclass of {NotPressed::Plugin} with a declared name
+      # @raise [ArgumentError] if the class is not a valid Plugin subclass or has no name
+      # @return [void]
+      def register(plugin_class)
+        unless plugin_class.is_a?(Class) && plugin_class < NotPressed::Plugin
+          raise ArgumentError, "#{plugin_class} must be a subclass of NotPressed::Plugin"
+        end
+
+        name = plugin_class.plugin_name
+        raise ArgumentError, "Plugin must declare a name using the `name` DSL" unless name
+
+        mutex.synchronize do
+          registry[name] = { klass: plugin_class, instance: nil, status: :registered }
+        end
+      end
+
+      # Returns a snapshot of all registered plugins.
+      #
+      # @return [Hash{String => Hash}] keyed by plugin name; values contain :klass, :instance, :status
+      def registered
+        mutex.synchronize { registry.dup }
+      end
+
+      # Looks up a plugin by name.
+      #
+      # @param name [String] the plugin name
+      # @return [Hash] entry with :klass, :instance, and :status keys
+      # @raise [NotFound] if the plugin is not registered
+      def find(name)
+        mutex.synchronize do
+          registry[name] || raise(NotFound, "Plugin '#{name}' not found")
+        end
+      end
+
+      # Lifecycle
+
+      # Creates a plugin instance, checks dependencies, activates it, and marks it active.
+      #
+      # @param name [String] the plugin name
+      # @raise [NotFound] if the plugin is not registered
+      # @raise [DependencyError] if the plugin has unmet dependencies
+      # @return [void]
+      def enable(name)
+        info = find(name)
+        plugin_class = info[:klass]
+
+        unmet = check_dependencies(plugin_class)
+        unless unmet.empty?
+          raise DependencyError,
+                "Plugin '#{name}' has unmet dependencies: #{unmet.join(', ')}"
+        end
+
+        instance = plugin_class.new
+        instance.activate!
+
+        mutex.synchronize do
+          registry[name] = { klass: plugin_class, instance: instance, status: :active }
+        end
+      end
+
+      # Deactivates a plugin instance and marks it inactive.
+      #
+      # @param name [String] the plugin name
+      # @raise [NotFound] if the plugin is not registered
+      # @return [void]
+      def disable(name)
+        info = find(name)
+
+        if info[:instance]
+          info[:instance].deactivate!
+        end
+
+        mutex.synchronize do
+          registry[name] = { klass: info[:klass], instance: nil, status: :inactive }
+        end
+      end
+
+      # Checks whether a plugin is currently active.
+      #
+      # @param name [String] the plugin name
+      # @return [Boolean]
+      def enabled?(name)
+        mutex.synchronize do
+          registry.key?(name) && registry[name][:status] == :active
+        end
+      end
+
+      # Dependency resolution
+
+      # Returns a list of unmet dependency names for the given plugin class.
+      #
+      # @param plugin_class [Class] a subclass of {NotPressed::Plugin}
+      # @return [Array<String>] names of inactive or unregistered dependencies
+      def check_dependencies(plugin_class)
+        deps = plugin_class.plugin_dependencies || []
+        deps.each_with_object([]) do |dep, unmet|
+          dep_name = dep[:name]
+          unless mutex.synchronize { registry.key?(dep_name) && registry[dep_name][:status] == :active }
+            unmet << dep_name
+          end
+        end
+      end
+
+      # Bulk operations
+
+      # Attempts to enable all registered plugins in dependency order.
+      #
+      # Uses multiple passes to resolve dependencies; stops when no further
+      # progress is possible.
+      #
+      # @return [void]
+      def enable_all
+        # Simple topological approach: try to enable each plugin,
+        # retry those with unmet deps after others are enabled
+        remaining = mutex.synchronize { registry.keys.select { |n| registry[n][:status] != :active } }
+        max_passes = remaining.size + 1
+        pass = 0
+
+        while remaining.any? && pass < max_passes
+          pass += 1
+          still_remaining = []
+          remaining.each do |name|
+            begin
+              enable(name)
+            rescue DependencyError
+              still_remaining << name
+            end
+          end
+          break if still_remaining.size == remaining.size # no progress
+          remaining = still_remaining
+        end
+      end
+
+      # Disables all currently active plugins.
+      #
+      # @return [void]
+      def disable_all
+        active_names = mutex.synchronize { registry.keys.select { |n| registry[n][:status] == :active } }
+        active_names.each { |name| disable(name) }
+      end
+
+      # Clears the entire plugin registry.
+      #
+      # @return [void]
+      def reset!
+        mutex.synchronize do
+          @registry = {}
+        end
+      end
+
+      # Discovery
+
+      # Scans all subclasses of {NotPressed::Plugin} and registers any
+      # that have a declared name but are not yet registered.
+      #
+      # @return [void]
+      def discover
+        NotPressed::Plugin.subclasses.each do |klass|
+          next unless klass.plugin_name
+          next if mutex.synchronize { registry.key?(klass.plugin_name) }
+
+          register(klass)
+        end
+      end
+
+      private
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end