plum-cms 0.1.0

data/app/services/plum/theme.rb

@@ -0,0 +1,160 @@
+module Plum
+  class Theme
+    SUPPORTED_SETTING_TYPES = %w[text textarea color boolean select].freeze
+
+    attr_reader :handle, :root, :manifest
+
+    def initialize(root:, manifest: {})
+      @root = Pathname(root)
+      @manifest = manifest.to_h.deep_stringify_keys
+      @handle = @manifest["handle"].presence || @root.basename.to_s
+    end
+
+    def name
+      manifest["name"].presence || handle.titleize
+    end
+
+    def version
+      manifest["version"].presence
+    end
+
+    def author
+      manifest["author"].presence
+    end
+
+    def description
+      manifest["description"].presence
+    end
+
+    def category
+      manifest["category"].presence
+    end
+
+    def screenshot_path
+      path = normalize_asset_reference(manifest["screenshot"])
+      return if path.blank?
+
+      asset_path(path)&.file? ? path : nil
+    end
+
+    def parent_handle
+      manifest["extends"].presence || manifest["parent"].presence
+    end
+
+    def settings_fields
+      Array(manifest.dig("settings", "fields")).filter_map do |field|
+        normalize_setting_field(field)
+      end
+    end
+
+    def blocks
+      Array(manifest["blocks"]).filter_map do |block|
+        normalize_block_definition(block)
+      end
+    end
+
+    def block_definition(handle)
+      handle = handle.to_s
+      return if handle.blank?
+
+      blocks.find { |block| block["handle"] == handle }
+    end
+
+    def block_template(handle, variant: :web)
+      path = block_template_path(handle, variant: variant)
+      return unless path&.file?
+
+      path.read
+    end
+
+    def block_template_path(handle, variant: :web)
+      return unless variant.to_sym == :web
+
+      normalized_handle = handle.to_s
+      return if normalized_handle.blank? || !normalized_handle.match?(/\A[a-z][a-z0-9_]*\z/)
+
+      root.join("blocks", "#{normalized_handle}.liquid")
+    end
+
+    def asset_root
+      root.join("assets")
+    end
+
+    def asset_path(asset_name)
+      normalized_name = ThemeAssetPath.normalize(asset_name)
+      candidate = asset_root.join(normalized_name).expand_path
+      expanded_asset_root = asset_root.expand_path
+
+      return unless candidate.to_s.start_with?("#{expanded_asset_root}/")
+
+      candidate
+    rescue ThemeAssetPath::UnsafePathError
+      nil
+    end
+
+    def template_path(template_name)
+      root.join("templates", "#{template_name}.liquid")
+    end
+
+    def layout_path(layout_name = "base")
+      root.join("layouts", "#{layout_name}.liquid")
+    end
+
+    private
+
+    def normalize_asset_reference(asset_name)
+      raw_name = asset_name.to_s
+      return if raw_name.blank?
+
+      raw_name = raw_name.delete_prefix("assets/")
+      ThemeAssetPath.normalize(raw_name)
+    rescue ThemeAssetPath::UnsafePathError
+      nil
+    end
+
+    def normalize_setting_field(field)
+      return unless field.respond_to?(:to_h)
+
+      normalized = field.to_h.deep_stringify_keys
+      handle = normalized["handle"].to_s
+      return if handle.blank?
+
+      type = normalized["type"].presence || "text"
+      type = "text" unless SUPPORTED_SETTING_TYPES.include?(type)
+
+      normalized.merge(
+        "handle" => handle,
+        "type" => type,
+        "label" => normalized["label"].presence || handle.humanize
+      )
+    end
+
+    def normalize_block_definition(block)
+      return unless block.respond_to?(:to_h)
+
+      normalized = block.to_h.deep_stringify_keys
+      handle = normalized["handle"].to_s
+      return if handle.blank?
+
+      normalized.merge(
+        "handle" => handle,
+        "label" => normalized["label"].presence || handle.humanize,
+        "fields" => Array(normalized["fields"]).filter_map { |field| normalize_block_field(field) }
+      )
+    end
+
+    def normalize_block_field(field)
+      return unless field.respond_to?(:to_h)
+
+      normalized = field.to_h.deep_stringify_keys
+      handle = normalized["handle"].to_s
+      return if handle.blank?
+
+      normalized.merge(
+        "handle" => handle,
+        "type" => normalized["type"].presence || "text",
+        "label" => normalized["label"].presence || handle.humanize
+      )
+    end
+  end
+end

data/app/services/plum/theme_asset_path.rb

@@ -0,0 +1,31 @@
+require "erb"
+
+module Plum
+  class ThemeAssetPath
+    class UnsafePathError < StandardError; end
+
+    class << self
+      def normalize(path)
+        raw_path = path.to_s
+        raise UnsafePathError, "Theme asset path cannot be blank" if raw_path.blank?
+        raise UnsafePathError, "Theme asset path cannot contain null bytes" if raw_path.include?("\0")
+
+        parts = raw_path.split("/").reject(&:blank?)
+        if Pathname(raw_path).absolute? || parts.any? { |part| part == "." || part == ".." }
+          raise UnsafePathError, "Theme asset path must stay inside the theme assets directory"
+        end
+        raise UnsafePathError, "Theme asset path cannot be blank" if parts.blank?
+
+        parts.join("/")
+      end
+
+      def url(base_url:, path:)
+        encoded_path = normalize(path).split("/").map { |part| ERB::Util.url_encode(part) }.join("/")
+
+        "#{base_url.to_s.chomp("/")}/#{encoded_path}"
+      rescue UnsafePathError
+        ""
+      end
+    end
+  end
+end

data/app/services/plum/theme_package_installer.rb

@@ -0,0 +1,287 @@
+require "fileutils"
+require "tmpdir"
+require "yaml"
+require "zip"
+
+module Plum
+  class ThemePackageInstaller
+    HANDLE_PATTERN = /\A[a-z0-9][a-z0-9-]*\z/
+    SETTING_HANDLE_PATTERN = /\A[a-z][a-z0-9_]*\z/
+
+    PackageEntry = Struct.new(:zip_entry, :path, :directory?, keyword_init: true)
+
+    attr_reader :errors, :theme
+
+    def initialize(package, install_root: nil)
+      @package = package
+      @install_root = Pathname(install_root || default_install_root)
+      @errors = []
+      @theme = nil
+    end
+
+    def install
+      errors.clear
+
+      with_zip_entries do |entries|
+        manifest = load_manifest(entries)
+        next false if errors.any?
+
+        handle = validate_manifest(manifest)
+        validate_renderable_files(entries)
+        validate_screenshot(manifest, entries)
+        validate_settings(manifest)
+        next false if errors.any?
+
+        target_root = validate_target(handle)
+        next false if errors.any?
+
+        extract_entries(entries, target_root)
+        @theme = Theme.new(root: target_root, manifest: manifest)
+        true
+      end
+    end
+
+    private
+
+    attr_reader :package, :install_root
+
+    def default_install_root
+      Plum.configuration.theme_paths.first || Rails.root.join("app/themes")
+    end
+
+    def with_zip_entries
+      Zip::File.open(package_path) do |zip|
+        entries = normalize_entries(zip)
+        yield entries
+      end
+    rescue Zip::Error
+      errors << "Theme package must be a valid zip file"
+      false
+    rescue Errno::ENOENT
+      errors << "Theme package could not be found"
+      false
+    end
+
+    def package_path
+      if package.respond_to?(:path)
+        package.path
+      elsif package.respond_to?(:tempfile) && package.tempfile.respond_to?(:path)
+        package.tempfile.path
+      else
+        package.to_s
+      end
+    end
+
+    def normalize_entries(zip)
+      raw_entries = zip.reject { |entry| ignored_entry?(entry.name) }
+      package_root = detect_package_root(raw_entries.reject(&:directory?))
+
+      return [] if errors.any?
+
+      raw_entries.filter_map do |entry|
+        relative_path = entry.name.delete_prefix(package_root)
+        next if relative_path.blank?
+
+        PackageEntry.new(
+          zip_entry: entry,
+          path: normalize_entry_path(relative_path),
+          directory?: entry.directory?
+        )
+      rescue ThemeAssetPath::UnsafePathError => e
+        errors << e.message
+        nil
+      end
+    end
+
+    def detect_package_root(entries)
+      names = entries.map { |entry| normalize_entry_name(entry.name) }.compact
+
+      return "" if names.include?("theme.yml")
+
+      roots = names.filter_map { |name| name.split("/", 2).first if name.include?("/") }.uniq
+      root = roots.one? ? "#{roots.first}/" : nil
+
+      if root && names.all? { |name| name.start_with?(root) } && names.include?("#{root}theme.yml")
+        root
+      else
+        errors << "Theme package must contain theme.yml at the root"
+        ""
+      end
+    end
+
+    def normalize_entry_name(name)
+      normalize_entry_path(name)
+    rescue ThemeAssetPath::UnsafePathError => e
+      errors << e.message
+      nil
+    end
+
+    def normalize_entry_path(path)
+      raw_path = path.to_s
+      raise ThemeAssetPath::UnsafePathError, "Theme package paths cannot contain backslashes" if raw_path.include?("\\")
+
+      ThemeAssetPath.normalize(raw_path)
+    end
+
+    def ignored_entry?(name)
+      normalized_name = name.to_s
+
+      normalized_name.start_with?("__MACOSX/") || File.basename(normalized_name) == ".DS_Store"
+    end
+
+    def load_manifest(entries)
+      manifest_entry = entries.find { |entry| entry.path == "theme.yml" && !entry.directory? }
+
+      unless manifest_entry
+        errors << "Theme package must contain theme.yml at the root"
+        return {}
+      end
+
+      manifest = YAML.safe_load(manifest_entry.zip_entry.get_input_stream.read, aliases: true) || {}
+      return manifest.deep_stringify_keys if manifest.is_a?(Hash)
+
+      errors << "theme.yml must contain a mapping"
+      {}
+    rescue Psych::SyntaxError => e
+      errors << "theme.yml is invalid: #{e.message}"
+      {}
+    end
+
+    def validate_manifest(manifest)
+      handle = manifest["handle"].to_s
+      name = manifest["name"].to_s
+
+      errors << "theme.yml must define a name" if name.blank?
+      if handle.blank?
+        errors << "theme.yml must define a handle"
+      elsif !handle.match?(HANDLE_PATTERN)
+        errors << "theme.yml handle must use lowercase letters, numbers, and hyphens"
+      end
+
+      handle
+    end
+
+    def validate_screenshot(manifest, entries)
+      screenshot = manifest_asset_path(manifest["screenshot"])
+      return if screenshot.blank?
+
+      expected_entry_path = "assets/#{screenshot}"
+      has_screenshot = entries.any? do |entry|
+        !entry.directory? && entry.path == expected_entry_path
+      end
+
+      errors << "theme.yml screenshot must point to a file inside assets" unless has_screenshot
+    end
+
+    def validate_settings(manifest)
+      fields = manifest.dig("settings", "fields")
+      return if fields.blank?
+
+      unless fields.is_a?(Array)
+        errors << "theme.yml settings.fields must be an array"
+        return
+      end
+
+      fields.each_with_index do |field, index|
+        validate_setting_field(field, index + 1)
+      end
+    end
+
+    def validate_setting_field(field, position)
+      unless field.is_a?(Hash)
+        errors << "theme.yml settings field #{position} must be a mapping"
+        return
+      end
+
+      field = field.deep_stringify_keys
+      handle = field["handle"].to_s
+      type = field["type"].presence || "text"
+
+      if handle.blank?
+        errors << "theme.yml settings field #{position} must define a handle"
+      elsif !handle.match?(SETTING_HANDLE_PATTERN)
+        errors << "theme.yml settings field #{handle} must use lowercase letters, numbers, and underscores"
+      end
+
+      unless Theme::SUPPORTED_SETTING_TYPES.include?(type)
+        errors << "theme.yml settings field #{handle.presence || position} has unsupported type #{type}"
+        return
+      end
+
+      validate_select_setting(field, handle.presence || position) if type == "select"
+    end
+
+    def validate_select_setting(field, identifier)
+      values = select_option_values(field["options"])
+
+      if values.blank?
+        errors << "theme.yml settings field #{identifier} must define select options"
+        return
+      end
+
+      default_value = field["default"].to_s
+      if field.key?("default") && values.exclude?(default_value)
+        errors << "theme.yml settings field #{identifier} default must match one of its options"
+      end
+    end
+
+    def select_option_values(options)
+      return [] unless options.is_a?(Array)
+
+      options.filter_map do |option|
+        if option.is_a?(Hash)
+          option.deep_stringify_keys["value"].to_s.presence
+        else
+          option.to_s.presence
+        end
+      end
+    end
+
+    def manifest_asset_path(path)
+      raw_path = path.to_s
+      return if raw_path.blank?
+
+      raw_path = raw_path.delete_prefix("assets/")
+      normalize_entry_path(raw_path)
+    rescue ThemeAssetPath::UnsafePathError
+      errors << "theme.yml screenshot path must be a safe asset path"
+      nil
+    end
+
+    def validate_renderable_files(entries)
+      has_renderable_file = entries.any? do |entry|
+        !entry.directory? && entry.path.match?(%r{\A(layouts|templates)/.+\.liquid\z})
+      end
+
+      errors << "Theme package must include at least one Liquid layout or template" unless has_renderable_file
+    end
+
+    def validate_target(handle)
+      target_root = install_root.expand_path.join(handle)
+
+      errors << "Theme #{handle} is already installed" if target_root.exist?
+
+      target_root
+    end
+
+    def extract_entries(entries, target_root)
+      FileUtils.mkdir_p(install_root)
+
+      Dir.mktmpdir("plum-theme-package-") do |dir|
+        staging_root = Pathname(dir).join(target_root.basename.to_s)
+
+        entries.each do |entry|
+          destination = staging_root.join(entry.path)
+          if entry.directory?
+            FileUtils.mkdir_p(destination)
+          else
+            FileUtils.mkdir_p(destination.dirname)
+            destination.binwrite(entry.zip_entry.get_input_stream.read)
+          end
+        end
+
+        FileUtils.mv(staging_root, target_root)
+      end
+    end
+  end
+end

data/app/services/plum/theme_registry.rb

@@ -0,0 +1,63 @@
+require "yaml"
+
+module Plum
+  class ThemeManifestError < StandardError; end
+
+  class ThemeRegistry
+    DEFAULT_THEME_HANDLE = "default"
+
+    attr_reader :theme_paths
+
+    def initialize(theme_paths: Plum.configuration.theme_paths)
+      @theme_paths = Array(theme_paths).compact.map { |path| Pathname(path).expand_path }.uniq(&:to_s)
+    end
+
+    def all
+      themes_by_handle.values
+    end
+
+    def find(handle)
+      themes_by_handle[handle.to_s] if handle.present?
+    end
+
+    def fetch(handle)
+      find(handle) || default_theme
+    end
+
+    def default_theme
+      find(DEFAULT_THEME_HANDLE)
+    end
+
+    private
+
+    def themes_by_handle
+      @themes_by_handle ||= discover_themes
+    end
+
+    def discover_themes
+      theme_paths.each_with_object({}) do |theme_path, themes|
+        next unless theme_path.directory?
+
+        theme_path.children.select(&:directory?).sort.each do |theme_root|
+          theme = build_theme(theme_root)
+          themes[theme.handle] ||= theme
+        end
+      end
+    end
+
+    def build_theme(theme_root)
+      Theme.new(root: theme_root, manifest: load_manifest(theme_root.join("theme.yml")))
+    end
+
+    def load_manifest(path)
+      return {} unless path.file?
+
+      manifest = YAML.safe_load(path.read, aliases: true) || {}
+      return manifest if manifest.is_a?(Hash)
+
+      {}
+    rescue Psych::SyntaxError => e
+      raise ThemeManifestError, "#{path}: #{e.message}"
+    end
+  end
+end

data/app/services/plum/theme_resolver.rb

@@ -0,0 +1,55 @@
+module Plum
+  class ThemeResolver
+    def initialize(registry: ThemeRegistry.new, fallback_handle: ThemeRegistry::DEFAULT_THEME_HANDLE)
+      @registry = registry
+      @fallback_handle = fallback_handle
+    end
+
+    def theme(handle)
+      registry.fetch(handle)
+    end
+
+    def find_template(theme_handle, template_name)
+      template_candidates(theme_handle, template_name).find(&:file?)
+    end
+
+    def find_layout(theme_handle, layout_name = "base")
+      themes_for(theme_handle).map { |theme| theme.layout_path(layout_name) }.find(&:file?)
+    end
+
+    def find_asset(theme_handle, asset_name)
+      themes_for(theme_handle).filter_map { |theme| theme.asset_path(asset_name) }.find(&:file?)
+    end
+
+    private
+
+    attr_reader :registry, :fallback_handle
+
+    def template_candidates(theme_handle, template_name)
+      themes_for(theme_handle).flat_map do |theme|
+        paths = [ theme.template_path(template_name) ]
+        paths << theme.template_path("entries/_default") if template_name.to_s.start_with?("entries/")
+        paths << theme.template_path("collections/_default") if template_name.to_s.start_with?("collections/")
+        paths << theme.template_path("taxonomies/_default") if template_name.to_s.start_with?("taxonomies/")
+        paths
+      end
+    end
+
+    def themes_for(theme_handle)
+      theme_chain(theme_handle).uniq { |theme| theme.root.to_s }
+    end
+
+    def theme_chain(theme_handle)
+      themes = []
+      current_theme = registry.find(theme_handle) || registry.default_theme
+
+      while current_theme && themes.none? { |theme| theme.handle == current_theme.handle }
+        themes << current_theme
+        current_theme = registry.find(current_theme.parent_handle)
+      end
+
+      themes << registry.find(fallback_handle)
+      themes.compact
+    end
+  end
+end

data/app/services/plum/theme_settings_params.rb

@@ -0,0 +1,54 @@
+module Plum
+  class ThemeSettingsParams
+    def initialize(theme)
+      @theme = theme
+    end
+
+    def normalize(raw_settings)
+      raw_settings = raw_settings.to_h.stringify_keys
+
+      theme.settings_fields.each_with_object({}) do |field, settings|
+        handle = field["handle"].to_s
+        next if handle.blank?
+
+        value = raw_settings.key?(handle) ? raw_settings[handle] : field["default"]
+        settings[handle] = normalize_value(field, value)
+      end
+    end
+
+    private
+
+    attr_reader :theme
+
+    def normalize_value(field, value)
+      case field["type"].to_s
+      when "boolean"
+        value.nil? ? false : ActiveModel::Type::Boolean.new.cast(value)
+      when "select"
+        normalize_select_value(field, value)
+      else
+        value.to_s
+      end
+    end
+
+    def normalize_select_value(field, value)
+      values = select_option_values(field)
+      normalized_value = value.to_s
+
+      return normalized_value if values.blank? || values.include?(normalized_value)
+
+      default_value = field["default"].to_s
+      values.include?(default_value) ? default_value : values.first
+    end
+
+    def select_option_values(field)
+      Array(field["options"]).filter_map do |option|
+        if option.is_a?(Hash)
+          option.stringify_keys["value"].to_s.presence
+        else
+          option.to_s.presence
+        end
+      end
+    end
+  end
+end