ruby_cms 0.2.1.0 → 1.0.0

data/lib/ruby_cms/file_installer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+require "ruby_cms/path_map"
+
+module RubyCms
+  # Copies the template files belonging to a set of modules into a host app.
+  class FileInstaller
+    def initialize(templates_root:, app_root:)
+      @templates_root = Pathname.new(templates_root)
+      @app_root = Pathname.new(app_root)
+    end
+
+    # modules: array of Manifest::Module. Returns array of app-relative paths written.
+    def install(modules)
+      written = []
+      modules.flat_map(&:files).uniq.each do |template_glob|
+        expand(template_glob).each do |template_rel|
+          src = @templates_root.join(template_rel)
+          next unless src.file?
+
+          dest = @app_root.join(PathMap.to_app(template_rel))
+          FileUtils.mkdir_p(dest.dirname)
+          FileUtils.cp(src, dest)
+          written << dest.relative_path_from(@app_root).to_s
+        end
+      end
+      written
+    end
+
+    private
+
+    def expand(template_glob)
+      return [template_glob] unless template_glob.include?("*")
+
+      @templates_root.glob(template_glob).select(&:file?)
+                     .map {|abs| abs.relative_path_from(@templates_root).to_s }
+    end
+  end
+end

data/lib/ruby_cms/gem_setup.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyCms
+  # Ensures the host app's Gemfile declares the gems the admin templates require.
+  # Pure Gemfile manipulation — the actual `bundle install` is run by the Installer.
+  class GemSetup
+    RUNTIME_GEMS = {
+      "pagy" => ">= 43.0",
+      "discard" => "~> 1.4",
+      "audited" => "~> 5.7",
+      "friendly_id" => "~> 5.5",
+      "noticed" => "~> 2.6",
+      "aasm" => "~> 5.5",
+      "acts_as_list" => "~> 1.2",
+      "pg_search" => "~> 2.3",
+      "oj" => "~> 3.16",
+      "lograge" => "~> 0.14",
+      "rails-i18n" => "~> 8.0",
+      "tailwindcss-rails" => nil,
+      "ransack" => nil
+    }.freeze
+
+    # ruby_ui ships the Phlex admin components; installed in the development group
+    # with require:false, matching the old generator's behavior.
+    DEV_GEMS = { "ruby_ui" => nil }.freeze
+
+    def initialize(app_root:)
+      @gemfile = Pathname.new(app_root).join("Gemfile")
+    end
+
+    # Appends any missing gems to the Gemfile. Returns the list of names added.
+    # include_base: add the base RUNTIME/DEV gems (true on a fresh install); on
+    # `--add` pass false so only the newly-selected modules' own gems are added.
+    def ensure_gems!(modules: [], include_base: true)
+      return [] unless @gemfile.exist?
+
+      original = @gemfile.read
+      added = []
+
+      if include_base
+        RUNTIME_GEMS.each do |name, version|
+          next if gem_present?(original, name)
+
+          line = version ? %(gem "#{name}", "#{version}") : %(gem "#{name}")
+          append("\n#{line}")
+          added << name
+        end
+
+        DEV_GEMS.each_key do |name|
+          next if gem_present?(original, name)
+
+          append(%(\n\ngroup :development do\n  gem "#{name}", require: false\nend))
+          added << name
+        end
+      end
+
+      modules.each do |mod|
+        next unless mod.respond_to?(:gems) && mod.gems
+
+        mod.gems.each do |name, version|
+          next if gem_present?(original, name)
+
+          line = version ? %(gem "#{name}", "#{version}") : %(gem "#{name}")
+          append("\n#{line}")
+          added << name
+        end
+      end
+
+      added
+    end
+
+    private
+
+    def gem_present?(content, name)
+      content.match?(/^\s*gem\s+["']#{Regexp.escape(name)}["']/)
+    end
+
+    def append(text)
+      @gemfile.open("a") {|f| f.write(text) }
+    end
+  end
+end

data/lib/ruby_cms/helper_wiring.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyCms
+  # Mixes the modules RubyCMS admin views rely on into the host app's ApplicationHelper:
+  #   * RubyUI            — Phlex::Kit, makes components callable as methods in ERB
+  #                         (e.g. AdminPageHeader(...)); defined by ruby_ui:install
+  #   * CmsApplicationHelpers / ContentBlocksHelper — shipped by the gem
+  #   * Pagy::Frontend    — pagination helpers
+  # Idempotent: only adds includes that are missing.
+  class HelperWiring
+    INCLUDES = %w[CmsApplicationHelpers RubyUI ContentBlocksHelper Pagy::Frontend].freeze
+
+    def initialize(app_root:)
+      @path = Pathname.new(app_root).join("app/helpers/application_helper.rb")
+    end
+
+    def apply! # rubocop:disable Naming/PredicateMethod
+      return false unless @path.exist?
+
+      content = @path.read
+      missing = INCLUDES.reject {|mod| content.include?("include #{mod}") }
+      return false if missing.empty?
+      return false unless content.include?("module ApplicationHelper\n")
+
+      lines = missing.map {|mod| "  include #{mod}" }.join("\n")
+      @path.write(content.sub("module ApplicationHelper\n", "module ApplicationHelper\n#{lines}\n"))
+      true
+    end
+  end
+end

data/lib/ruby_cms/importmap_wiring.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyCms
+  # Adds the importmap pins the admin JS needs to the host app's config/importmap.rb:
+  # the "admin" entrypoint plus the CDN-hosted libraries the admin Stimulus controllers
+  # and ruby_ui components import. No-op for apps without importmap (esbuild/bun) or
+  # when every pin is already present.
+  class ImportmapWiring
+    # name => full pin line. Order preserved on append.
+    PINS = {
+      "admin" => 'pin "admin"',
+      "@floating-ui/dom" => 'pin "@floating-ui/dom", to: "https://cdn.jsdelivr.net/npm/@floating-ui/dom/+esm"',
+      "sortablejs" => 'pin "sortablejs", to: "https://cdn.jsdelivr.net/npm/sortablejs@1.15.7/+esm"',
+      "maska" => 'pin "maska", to: "https://ga.jspm.io/npm:maska@3.1.1/dist/maska.mjs"',
+      "motion" => 'pin "motion", to: "https://cdn.jsdelivr.net/npm/motion@11.11.17/+esm"',
+      "fuse.js" => 'pin "fuse.js", to: "https://cdn.jsdelivr.net/npm/fuse.js@7.0.0/+esm"',
+      "tippy.js" => 'pin "tippy.js", to: "https://cdn.jsdelivr.net/npm/tippy.js@6.3.7/+esm"',
+      "@popperjs/core" => 'pin "@popperjs/core", to: "https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.8/+esm"',
+      "embla-carousel" => 'pin "embla-carousel", to: "https://cdn.jsdelivr.net/npm/embla-carousel@8.5.2/+esm"',
+      "mustache" => 'pin "mustache", to: "https://cdn.jsdelivr.net/npm/mustache@4.2.0/+esm"'
+    }.freeze
+
+    def initialize(app_root:)
+      @path = Pathname.new(app_root).join("config/importmap.rb")
+    end
+
+    def apply! # rubocop:disable Naming/PredicateMethod
+      return false unless @path.exist?
+
+      content = @path.read
+      missing = PINS.reject {|name, _| content.match?(/^\s*pin\s+["']#{Regexp.escape(name)}["']/) }
+      return false if missing.empty?
+
+      additions = missing.values.join("\n")
+      @path.write("#{content.rstrip}\n\n# RubyCMS admin importmap pins\n#{additions}\n")
+      true
+    end
+  end
+end

data/lib/ruby_cms/installer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "ruby_cms/gem_setup"
+require "ruby_cms/app_wiring"
+require "ruby_cms/auth_wiring"
+require "ruby_cms/helper_wiring"
+require "ruby_cms/importmap_wiring"
+require "ruby_cms/passkey_wiring"
+require "ruby_cms/file_installer"
+require "ruby_cms/routes_assembler"
+require "ruby_cms/nav_assembler"
+require "ruby_cms/migration_installer"
+require "ruby_cms/lockfile"
+
+module RubyCms
+  # Composes the gem/file/routes/nav/migration installers, runs the Rails shell steps,
+  # and records the installed modules in the lockfile.
+  class Installer
+    # Raised when a step the rest of the install depends on (bundle, migrate) fails.
+    class Error < StandardError; end
+
+    # Framework generators the admin templates depend on (run once, on a fresh install).
+    BASE_FRAMEWORK_STEPS = [
+      "bin/rails generate ruby_ui:install",
+      "bin/rails tailwindcss:install",
+      "bin/rails action_text:install",
+      "bin/rails noticed:install:migrations"
+    ].freeze
+
+    AHOY_STEP = "bin/rails generate ahoy:install"
+
+    def initialize(manifest:, templates_root:, app_root:, shell:, version:)
+      @manifest = manifest
+      @templates_root = templates_root
+      @app_root = app_root
+      @shell = shell
+      @version = version
+    end
+
+    # selected: array of optional module keys chosen by the user.
+    # framework_setup: run gem + framework scaffolding (true for a fresh install).
+    def install(selected:, framework_setup: true)
+      modules = @manifest.resolve(selected)
+
+      # Gems first: base + module gems on a fresh install; on `--add`, only the newly
+      # selected modules' own gems (so e.g. adding passkeys pulls in webauthn).
+      added = GemSetup.new(app_root: @app_root).ensure_gems!(modules: modules, include_base: framework_setup)
+      run_critical("bundle install") if added.any?
+
+      # Framework scaffolding runs on the still-vanilla app, fresh install only, so the
+      # Rails generators don't collide with (and interactively prompt about) gem files.
+      if framework_setup
+        run_auth_setup
+        run_framework_steps(modules)
+      end
+
+      # Copy each module's files (overwriting any generator output), one line per module.
+      file_installer = FileInstaller.new(templates_root: @templates_root, app_root: @app_root)
+      @shell.heading("Installing modules:")
+      modules.each do |mod|
+        file_installer.install([mod])
+        @shell.ok(mod.key.to_s, hint: mod.description)
+      end
+
+      AppWiring.new(app_root: @app_root).apply!
+      HelperWiring.new(app_root: @app_root).apply!
+      ImportmapWiring.new(app_root: @app_root).apply!
+      PasskeyWiring.new(app_root: @app_root).apply! if modules.any? {|m| m.key == :passkeys }
+      RoutesAssembler.new(templates_root: @templates_root, app_root: @app_root).inject(modules)
+      NavAssembler.new(templates_root: @templates_root, app_root: @app_root).write(modules)
+
+      # Migrations last so they are re-stamped to run after the ahoy/action_text tables
+      # the framework generators created.
+      MigrationInstaller.new(templates_root: @templates_root, app_root: @app_root).install(modules)
+      run_rails_steps
+      # Rebuild Tailwind AFTER admin views/components exist so their utility classes are
+      # compiled — on fresh install AND on `--add` (a new module brings new view classes).
+      @shell.run("bin/rails tailwindcss:build")
+      Lockfile.new(@app_root).write!(modules: modules.map(&:key), version: @version)
+      modules
+    end
+
+    # Layer additional modules onto an existing install. Routes/nav are regenerated
+    # for the full union; gem + framework scaffolding are NOT re-run.
+    def add(new_keys:)
+      lock = Lockfile.new(@app_root)
+      added_keys = Array(new_keys).map(&:to_sym)
+      prior = lock.modules
+      union = (prior + added_keys).uniq
+      install(selected: union - @manifest.base_modules.map(&:key), framework_setup: false)
+      return unless added_keys.include?(:analytics) && !prior.include?(:analytics)
+
+      @shell.run(AHOY_STEP)
+      run_critical("bin/rails db:migrate")
+    end
+
+    private
+
+    # Generate Rails authentication if absent, then wire current_user + Permittable.
+    def run_auth_setup
+      auth = AuthWiring.new(app_root: @app_root)
+      unless auth.user_model_present?
+        run_critical("bin/rails generate authentication")
+        run_critical("bundle install")
+      end
+      auth.patch!
+    end
+
+    def run_framework_steps(modules)
+      steps = BASE_FRAMEWORK_STEPS.dup
+      steps.insert(2, AHOY_STEP) if modules.any? {|m| m.key == :analytics }
+      steps.each {|cmd| @shell.run(cmd) }
+    end
+
+    def run_rails_steps
+      run_critical("bin/rails db:migrate")
+      @shell.run("bin/rails ruby_cms:seed_permissions")
+    end
+
+    # Run a command the rest of the install depends on; abort with a clear message
+    # (rather than limping on to a misleading "installed") when it fails.
+    def run_critical(cmd)
+      return if @shell.run(cmd)
+
+      raise Error, "`#{cmd}` failed. Fix the error shown above, then re-run `ruby_cms install`."
+    end
+  end
+end

data/lib/ruby_cms/lockfile.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+
+module RubyCms
+  # Reads/writes .ruby_cms.yml at the host app root: which modules are installed.
+  class Lockfile
+    FILENAME = ".ruby_cms.yml"
+
+    def initialize(app_root)
+      @path = Pathname.new(app_root).join(FILENAME)
+    end
+
+    def modules
+      return [] unless @path.exist?
+
+      Array(data["modules"]).map(&:to_sym)
+    end
+
+    # App-relative globs the host never wants overwritten by update/sync.
+    def excludes
+      return [] unless @path.exist?
+
+      Array(data["exclude"]).map(&:to_s)
+    end
+
+    def version
+      data["version"] if @path.exist?
+    end
+
+    def write!(modules:, version:)
+      existing_exclude = @path.exist? ? Array(data["exclude"]) : []
+      @data = { "version" => version, "modules" => modules.map(&:to_s).uniq.sort }
+      @data["exclude"] = existing_exclude unless existing_exclude.empty?
+      @path.write(YAML.dump(@data))
+    end
+
+    def add!(modules, version:)
+      write!(modules: (self.modules + Array(modules)).uniq, version: version)
+    end
+
+    private
+
+    def data
+      @data ||= YAML.safe_load(@path.read) || {}
+    end
+  end
+end

data/lib/ruby_cms/manifest.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubyCms
+  class Manifest
+    Module = Struct.new(
+      :key, :base, :depends_on, :files, :routes, :nav, :permissions, :migrations, :gems,
+      :description,
+      keyword_init: true
+    ) do
+      def base? = base
+    end
+
+    # Collects one module's declarations via the DSL block.
+    class Builder
+      def initialize(key, base, depends_on)
+        @key = key
+        @base = base
+        @depends_on = depends_on
+        @files = []
+        @routes = nil
+        @nav = nil
+        @permissions = []
+        @migrations = []
+        @gems = {}
+        @description = nil
+      end
+
+      def files(list) = @files.concat(Array(list))
+      def routes(path) = (@routes = path)
+      def nav(path) = (@nav = path)
+      def permissions(list) = @permissions.concat(Array(list))
+      def migrations(list) = @migrations.concat(Array(list))
+      def gems(hash) = @gems.merge!(hash)
+      def description(text) = (@description = text)
+
+      def to_module
+        Module.new(
+          key: @key, base: @base, depends_on: @depends_on, files: @files,
+          routes: @routes, nav: @nav, permissions: @permissions, migrations: @migrations,
+          gems: @gems, description: @description
+        )
+      end
+    end
+
+    def self.build(&)
+      manifest = new
+      manifest.instance_eval(&)
+      manifest
+    end
+
+    attr_reader :modules
+
+    def initialize
+      @modules = {}
+    end
+
+    def module_def(key, base: false, depends_on: [], &block)
+      raise ArgumentError, "duplicate module #{key}" if @modules.key?(key)
+
+      builder = Builder.new(key, base, depends_on)
+      builder.instance_eval(&block) if block
+      @modules[key] = builder.to_module
+    end
+
+    def [](key) = @modules[key]
+    def base_modules = @modules.values.select(&:base?)
+    def optional_modules = @modules.values.reject(&:base?)
+
+    # Expand selected optional keys into the full ordered set incl. base + deps.
+    def resolve(selected_keys)
+      result = base_modules.map(&:key)
+      queue = Array(selected_keys).dup
+      until queue.empty?
+        key = queue.shift
+        next if result.include?(key)
+
+        mod = @modules.fetch(key)
+        result << key
+        queue.concat(mod.depends_on)
+      end
+      result.uniq.map {|k| @modules.fetch(k) }
+    end
+
+    def all_files
+      @modules.values.flat_map(&:files).uniq
+    end
+  end
+end