not_pressed-core 0.1.0

data/lib/not_pressed/theme.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module NotPressed
+  # Base class for NotPressed themes. Inherits from {Plugin} and adds
+  # DSL methods for layouts, stylesheets, color schemes, templates, and assets.
+  #
+  # Only one theme can be active at a time (managed by {ThemeRegistry}).
+  #
+  # @example Defining a theme
+  #   class MyTheme < NotPressed::Theme
+  #     name "my_theme"
+  #     version "1.0"
+  #
+  #     layout :default, label: "Default", primary: true
+  #     layout :sidebar, label: "With Sidebar"
+  #
+  #     stylesheet "my_theme/application"
+  #     templates_path "app/views/themes/my_theme"
+  #
+  #     color_scheme do
+  #       color :primary, "#3366cc", label: "Primary"
+  #     end
+  #   end
+  class Theme < Plugin
+    class << self
+      # @api private
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@theme_layouts, [])
+        subclass.instance_variable_set(:@theme_stylesheet, nil)
+        subclass.instance_variable_set(:@theme_color_scheme, [])
+        subclass.instance_variable_set(:@theme_templates_path, nil)
+        subclass.instance_variable_set(:@theme_assets_path, nil)
+      end
+
+      # Declares a layout provided by this theme.
+      #
+      # @param name [Symbol, String] layout identifier
+      # @param label [String] human-readable label
+      # @param primary [Boolean] whether this is the default layout
+      # @return [void]
+      def layout(name, label:, primary: false)
+        @theme_layouts << { name: name, label: label, primary: primary }
+      end
+
+      # @return [Array<Hash>] declared layout entries
+      def theme_layouts
+        @theme_layouts
+      end
+
+      # Returns the primary layout, or the first declared layout if none is marked primary.
+      #
+      # @return [Hash, nil] the primary layout entry
+      def primary_layout
+        @theme_layouts.find { |l| l[:primary] } || @theme_layouts.first
+      end
+
+      # Sets or gets the theme stylesheet path.
+      #
+      # @param path [String, nil] stylesheet path to set, or nil to read
+      # @return [String, nil] the current stylesheet path
+      def stylesheet(path = nil)
+        path ? @theme_stylesheet = path : @theme_stylesheet
+      end
+
+      # @return [String, nil] the declared stylesheet path
+      def theme_stylesheet
+        @theme_stylesheet
+      end
+
+      # Defines customizable colors using the {ColorSchemeBuilder} DSL.
+      #
+      # @yield block evaluated in the context of a {ColorSchemeBuilder}
+      # @return [void]
+      def color_scheme(&block)
+        builder = ColorSchemeBuilder.new
+        builder.instance_eval(&block)
+        @theme_color_scheme = builder.colors
+      end
+
+      # @return [Array<Hash>] declared color definitions
+      def theme_color_scheme
+        @theme_color_scheme
+      end
+
+      # Sets or gets the path to theme-specific view templates.
+      #
+      # @param path [String, nil] templates directory path to set, or nil to read
+      # @return [String, nil] the current templates path
+      def templates_path(path = nil)
+        path ? @theme_templates_path = path : @theme_templates_path
+      end
+
+      # @return [String, nil] the declared templates path
+      def theme_templates_path
+        @theme_templates_path
+      end
+
+      # Sets or gets the path to theme asset files.
+      #
+      # @param path [String, nil] assets directory path to set, or nil to read
+      # @return [String, nil] the current assets path
+      def assets_path(path = nil)
+        path ? @theme_assets_path = path : @theme_assets_path
+      end
+
+      # @return [String, nil] the declared assets path
+      def theme_assets_path
+        @theme_assets_path
+      end
+    end
+
+    # Instance methods — view path management
+
+    # Activates the theme by calling {Plugin#activate!}, then prepends
+    # template paths and registers stylesheet/assets with the Rails asset pipeline.
+    #
+    # @return [true]
+    def activate!
+      super
+      theme_class = self.class
+      if theme_class.theme_templates_path
+        path = resolve_templates_path(theme_class.theme_templates_path)
+        ActionController::Base.prepend_view_path(path)
+      end
+
+      if theme_class.theme_stylesheet
+        if defined?(Rails) && Rails.application&.config&.respond_to?(:assets)
+          assets_config = Rails.application.config.assets
+          unless assets_config.precompile.include?(theme_class.theme_stylesheet)
+            assets_config.precompile << theme_class.theme_stylesheet
+          end
+        end
+      end
+
+      if theme_class.theme_assets_path
+        path = resolve_templates_path(theme_class.theme_assets_path)
+        if defined?(Rails) && Rails.application&.config&.respond_to?(:assets)
+          unless Rails.application.config.assets.paths.include?(path)
+            Rails.application.config.assets.paths << path
+          end
+        end
+      end
+    end
+
+    # Deactivates the theme by calling {Plugin#deactivate!}, then removes
+    # the theme's templates path from the view paths.
+    #
+    # @return [false]
+    def deactivate!
+      super
+      theme_class = self.class
+      if theme_class.theme_templates_path
+        path = resolve_templates_path(theme_class.theme_templates_path)
+        ActionController::Base.view_paths = ActionController::Base.view_paths.reject { |vp| vp.to_s == path.to_s }
+      end
+    end
+
+    private
+
+    def resolve_templates_path(path)
+      if Pathname.new(path).absolute?
+        path
+      else
+        Rails.root.join(path).to_s
+      end
+    end
+  end
+
+  # DSL builder for defining theme color schemes.
+  #
+  # Used inside a +Theme.color_scheme+ block.
+  class ColorSchemeBuilder
+    # @return [Array<Hash>] the accumulated color definitions
+    attr_reader :colors
+
+    def initialize
+      @colors = []
+    end
+
+    # Declares a customizable color.
+    #
+    # @param key [Symbol] color identifier (used as CSS custom property name)
+    # @param default [String] default color value (e.g., hex code)
+    # @param label [String, nil] human-readable label
+    # @return [void]
+    def color(key, default, label: nil)
+      @colors << { key: key, default: default, label: label }
+    end
+  end
+end

data/lib/not_pressed/theme_importer.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "zip"
+require "json"
+
+module NotPressed
+  # Imports a theme 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::ThemeImporter.new("/tmp/starter-1.0.0.zip").import!
+  #   result[:name]            #=> "Starter"
+  #   result[:files_installed] #=> ["app/themes/not_pressed/starter_theme.rb"]
+  class ThemeImporter
+    # Raised when the zip archive is invalid, missing manifest, or contains
+    # dangerous paths.
+    class InvalidArchive < StandardError; end
+
+    # Raised when a theme with the same name is already registered.
+    class DuplicateTheme < StandardError; end
+
+    # @param zip_path [String] path to the theme zip archive
+    # @param force [Boolean] when true, overwrites an existing theme with the same name
+    def initialize(zip_path, force: false)
+      @zip_path = zip_path
+      @force = force
+    end
+
+    # Validates and extracts the theme 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 [DuplicateTheme] if a theme 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 theme with the given name is already registered.
+    #
+    # @param name [String] the theme name from the manifest
+    # @raise [DuplicateTheme] if the name exists and force is false
+    def check_duplicate!(name)
+      return if @force
+
+      if ThemeRegistry.available.include?(name)
+        raise DuplicateTheme, "Theme '#{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/theme_packager.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "zip"
+require "json"
+
+module NotPressed
+  # Exports a registered theme into a distributable zip archive.
+  #
+  # The archive contains a manifest.json with theme metadata and all
+  # associated source files (theme class file, layout templates, and stylesheet).
+  #
+  # @example
+  #   packager = NotPressed::ThemePackager.new("Starter")
+  #   zip_path = packager.package("/tmp/exports")
+  class ThemePackager
+    # @param theme_name [String] the registered theme name
+    def initialize(theme_name)
+      @theme_name = theme_name
+    end
+
+    # Creates a zip archive of the theme at the given output directory.
+    #
+    # @param output_path [String] directory where the zip will be written
+    # @return [String] absolute path to the created zip file
+    # @raise [ThemeRegistry::NotFound] if the theme is not registered
+    # @raise [ArgumentError] if output_path does not exist
+    def package(output_path)
+      entry = ThemeRegistry.find(@theme_name)
+      klass = entry[:klass]
+
+      raise ArgumentError, "Output directory does not exist: #{output_path}" unless Dir.exist?(output_path)
+
+      files = collect_files(klass)
+      manifest = build_manifest(klass, files)
+
+      zip_filename = "#{snake_name(klass)}-#{klass.plugin_version || '0.0.0'}.zip"
+      zip_path = File.join(output_path, zip_filename)
+
+      root = engine_root
+
+      Zip::File.open(zip_path, create: true) do |zip|
+        zip.get_output_stream("manifest.json") { |io| io.write(JSON.pretty_generate(manifest)) }
+
+        files.each do |relative_path|
+          absolute = File.join(root, relative_path)
+          zip.add(relative_path, absolute) if File.exist?(absolute)
+        end
+      end
+
+      zip_path
+    end
+
+    private
+
+    # Collects all files that belong to the theme.
+    #
+    # @param klass [Class] the theme class
+    # @return [Array<String>] relative file paths from engine root
+    def collect_files(klass)
+      files = []
+      root = engine_root
+
+      # Theme class file
+      theme_file = "app/themes/not_pressed/#{snake_name(klass)}_theme.rb"
+      files << theme_file if File.exist?(File.join(root, theme_file))
+
+      # Layout templates — theme_templates_path may be absolute.
+      # When the resolved path doesn't exist (e.g., expand_path resolved
+      # relative to the source file), fall back to app/views/themes/<name>.
+      if klass.theme_templates_path
+        templates_dir = resolve_templates_dir(klass.theme_templates_path, root, snake_name(klass))
+        if templates_dir
+          pattern = File.join(templates_dir, "**", "*.html.erb")
+          Dir.glob(pattern).each do |path|
+            relative = absolute_to_relative(path, root)
+            files << relative
+          end
+        end
+      end
+
+      # Stylesheet
+      if klass.theme_stylesheet
+        stylesheet_path = resolve_stylesheet_path(klass.theme_stylesheet, root)
+        if stylesheet_path
+          relative = absolute_to_relative(stylesheet_path, root)
+          files << relative
+        end
+      end
+
+      files
+    end
+
+    # Builds the manifest hash from theme DSL metadata.
+    #
+    # @param klass [Class] the theme class
+    # @param files [Array<String>] list of files included in the archive
+    # @return [Hash] manifest data
+    def build_manifest(klass, files)
+      {
+        name: klass.plugin_name,
+        version: klass.plugin_version,
+        description: klass.plugin_description,
+        author: klass.plugin_author,
+        layouts: (klass.theme_layouts || []).map { |l| stringify_keys(l) },
+        color_scheme: (klass.theme_color_scheme || []).map { |c| stringify_keys(c) },
+        stylesheet: klass.theme_stylesheet,
+        files: files
+      }
+    end
+
+    # Converts a theme class to its snake_case file name stem.
+    #
+    # @param klass [Class] the theme class
+    # @return [String] snake_case name
+    def snake_name(klass)
+      Module.instance_method(:name).bind_call(klass).split("::").last
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+        .sub(/_theme$/, "")
+    end
+
+    # Returns the engine root directory.
+    #
+    # @return [String]
+    def engine_root
+      NotPressed::Engine.root.to_s
+    end
+
+    # Converts an absolute path to a relative path from engine root.
+    # Handles both forward and back slashes for cross-platform compatibility.
+    #
+    # @param path [String] absolute file path
+    # @param root [String] engine root directory
+    # @return [String] relative path with forward slashes
+    def absolute_to_relative(path, root)
+      normalized_path = path.tr("\\", "/")
+      normalized_root = root.tr("\\", "/")
+      normalized_path.sub("#{normalized_root}/", "")
+    end
+
+    # Resolves the templates directory, falling back to the conventional
+    # app/views/themes/<name> path when the DSL-declared path doesn't exist.
+    #
+    # @param declared_path [String] the templates_path from the DSL
+    # @param root [String] engine root directory
+    # @param name [String] snake_case theme name
+    # @return [String, nil] absolute path to the templates directory
+    def resolve_templates_dir(declared_path, root, name)
+      return declared_path if Dir.exist?(declared_path)
+
+      # Fall back to conventional location under app/views/themes/<name>
+      conventional = File.join(root, "app/views/themes", name)
+      return conventional if Dir.exist?(conventional)
+
+      nil
+    end
+
+    # Resolves the stylesheet DSL value to an absolute file path.
+    #
+    # @param stylesheet [String] stylesheet path from the DSL (e.g., "not_pressed/themes/starter.css")
+    # @param root [String] engine root directory
+    # @return [String, nil] absolute path to the stylesheet file, or nil if not found
+    def resolve_stylesheet_path(stylesheet, root)
+      candidate = File.join(root, "app/assets/stylesheets", stylesheet)
+      return candidate if File.exist?(candidate)
+      nil
+    end
+
+    # Deep-converts symbol keys to strings for JSON serialization.
+    #
+    # @param hash [Hash] input hash
+    # @return [Hash] hash with string keys
+    def stringify_keys(hash)
+      hash.each_with_object({}) do |(k, v), h|
+        h[k.to_s] = v.is_a?(Hash) ? stringify_keys(v) : v
+      end
+    end
+  end
+end

data/lib/not_pressed/theme_registry.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module NotPressed
+  # Thread-safe registry for themes. Only one theme can be active at a time.
+  #
+  # Manages theme registration, activation, and deactivation. When a new theme
+  # is activated, the previously active theme is automatically deactivated.
+  module ThemeRegistry
+    # Raised when a theme name is not found in the registry.
+    class NotFound < StandardError; end
+
+    class << self
+      # Registers a theme class in the registry.
+      #
+      # @param theme_class [Class] a subclass of {NotPressed::Theme} with a declared name
+      # @raise [ArgumentError] if the class is not a valid Theme subclass or has no name
+      # @return [void]
+      def register(theme_class)
+        unless theme_class.is_a?(Class) && theme_class < NotPressed::Theme
+          raise ArgumentError, "#{theme_class} must be a subclass of NotPressed::Theme"
+        end
+
+        name = theme_class.plugin_name
+        raise ArgumentError, "Theme must declare a name using the `name` DSL" unless name
+
+        mutex.synchronize do
+          registry[name] = { klass: theme_class, status: :registered }
+        end
+      end
+
+      # Returns the currently active theme class.
+      #
+      # @return [Class, nil] the active theme class, or nil if no theme is active
+      def active
+        mutex.synchronize { @active_theme }
+      end
+
+      # Returns the currently active theme instance.
+      #
+      # @return [NotPressed::Theme, nil] the active theme instance
+      def active_instance
+        mutex.synchronize { @active_instance }
+      end
+
+      # Deactivates any current theme and activates the named theme.
+      #
+      # @param name [String] the theme name to activate
+      # @raise [NotFound] if the theme is not registered
+      # @return [void]
+      def activate(name)
+        info = find(name)
+
+        mutex.synchronize do
+          if @active_instance
+            @active_instance.deactivate!
+            active_name = @active_theme.plugin_name
+            registry[active_name][:status] = :inactive if registry.key?(active_name)
+          end
+
+          instance = info[:klass].new
+          instance.activate!
+          @active_theme = info[:klass]
+          @active_instance = instance
+          registry[name][:status] = :active
+        end
+      end
+
+      # Deactivates the current theme without activating a replacement.
+      #
+      # @return [void]
+      def deactivate
+        mutex.synchronize do
+          if @active_instance
+            @active_instance.deactivate!
+            active_name = @active_theme.plugin_name
+            registry[active_name][:status] = :inactive if registry.key?(active_name)
+          end
+          @active_theme = nil
+          @active_instance = nil
+        end
+      end
+
+      # Returns the names of all registered themes.
+      #
+      # @return [Array<String>]
+      def available
+        mutex.synchronize { registry.keys }
+      end
+
+      # Looks up a theme by name.
+      #
+      # @param name [String] the theme name
+      # @return [Hash] entry with :klass and :status keys
+      # @raise [NotFound] if the theme is not registered
+      def find(name)
+        mutex.synchronize do
+          registry[name] || raise(NotFound, "Theme '#{name}' not found")
+        end
+      end
+
+      # Clears the registry and deactivates any active theme.
+      #
+      # @return [void]
+      def reset!
+        mutex.synchronize do
+          @registry = {}
+          @active_theme = nil
+          @active_instance = nil
+        end
+      end
+
+      private
+
+      def mutex
+        @mutex ||= Mutex.new
+      end
+
+      def registry
+        @registry ||= {}
+      end
+    end
+  end
+end

data/lib/not_pressed/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NotPressed
+  VERSION = "0.1.0"
+end

data/lib/not_pressed.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "not_pressed/version"
+require "not_pressed/configuration"
+require "not_pressed/content_type"
+require "not_pressed/content_type_registry"
+require "not_pressed/content_type_builder"
+require "not_pressed/navigation"
+require "not_pressed/navigation/route_inspector"
+require "not_pressed/navigation/partial_parser"
+require "not_pressed/navigation/menu_item"
+require "not_pressed/navigation/menu"
+require "not_pressed/navigation/node"
+require "not_pressed/navigation/builder"
+require "not_pressed/hooks"
+require "not_pressed/plugin"
+require "not_pressed/plugin_manager"
+require "not_pressed/plugin_packager"
+require "not_pressed/plugin_importer"
+require "not_pressed/theme"
+require "not_pressed/theme_registry"
+require "not_pressed/theme_packager"
+require "not_pressed/theme_importer"
+require "not_pressed/rendering"
+require "not_pressed/rendering/block_renderer"
+require "not_pressed/seo/sitemap_builder"
+require "not_pressed/admin/authentication"
+require "not_pressed/admin/menu_registry"
+require "not_pressed/engine"
+
+module NotPressed
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+
+    def navigation(menu_name = "main")
+      @navigation_builder ||= Navigation::Builder.new
+      @navigation_builder.cached_build(menu_name)
+    end
+
+    def invalidate_navigation!
+      @navigation_builder&.invalidate_cache!
+      @navigation_builder = nil
+    end
+
+    def plugins
+      PluginManager.registered
+    end
+
+    def define_content_type(name, &block)
+      builder = ContentTypeBuilder.new(name)
+      builder.instance_eval(&block)
+      builder.register!
+    end
+  end
+end