ruby_cms 0.2.1.1 → 1.0.0

data/lib/generators/ruby_cms/templates/views/layouts/admin/topbar/_profile_menu.html.erb

@@ -0,0 +1,86 @@
+<%# User avatar + dropdown menu (profile, settings, view site, logout). %>
+<%
+  user = current_user_cms
+  email = user&.respond_to?(:email_address) ? user.email_address : nil
+  initials = email.to_s.split(/[@.\s_-]/).first(2).map { |s| s[0].to_s.upcase }.join.presence || "??"
+  role_label = user&.admin? ? "Admin" : "Editor"
+%>
+<div class="relative">
+  <button type="button"
+          data-action="click->admin--topbar#toggleMenu"
+          data-admin--topbar-target="menuButton"
+          aria-label="<%= email.presence || 'Account menu' %>"
+          title="<%= email %>"
+          class="inline-flex items-center justify-center w-8 h-8 rounded-md border border-transparent hover:bg-[#faf8f3] transition-colors data-[active=true]:bg-[#faf8f3]">
+    <span class="inline-flex items-center justify-center w-6 h-6 rounded-md bg-blue-600 text-white text-[10.5px] font-semibold tracking-wide"><%= initials %></span>
+  </button>
+  <div data-admin--topbar-target="menuPanel" hidden
+       class="absolute right-0 top-[calc(100%+6px)] w-[min(280px,calc(100vw-1.5rem))] max-w-[280px] rounded-lg border border-[#e9e4d4] bg-white shadow-lg z-50 py-1">
+    <div class="flex items-center gap-2.5 px-3 py-2.5 border-b border-[#e9e4d4]">
+      <div class="inline-flex items-center justify-center w-9 h-9 rounded-md bg-blue-600 text-white text-[12.5px] font-semibold"><%= initials %></div>
+      <div class="min-w-0 flex-1">
+        <div class="text-[13.5px] font-semibold text-[#1c1917] truncate"><%= email %></div>
+        <div class="text-[11.5px] text-[#78716c]"><%= role_label %></div>
+      </div>
+      <%= status_pill(:danger, role_label) %>
+    </div>
+
+    <% if user&.id %>
+      <%= link_to admin_user_path(user), class: "flex items-center gap-2.5 px-3 py-2 text-[13px] text-[#1c1917] hover:bg-[#faf8f3] no-underline" do %>
+        <svg class="w-3.5 h-3.5 text-[#78716c]" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M16 7a4 4 0 11-8 0 4 4 0 018 0zM12 14a7 7 0 00-7 7h14a7 7 0 00-7-7z" /></svg>
+        <span class="flex-1"><%= t("ruby_cms.admin.topbar.profile", default: "Mijn profiel") %></span>
+      <% end %>
+    <% end %>
+
+    <%= link_to admin_settings_path, class: "flex items-center gap-2.5 px-3 py-2 text-[13px] text-[#1c1917] hover:bg-[#faf8f3] no-underline" do %>
+      <svg class="w-3.5 h-3.5 text-[#78716c]" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.066 2.573c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.573 1.066c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.066-2.573c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z" /><circle cx="12" cy="12" r="3" /></svg>
+      <span class="flex-1"><%= t("ruby_cms.admin.topbar.settings", default: "Settings") %></span>
+    <% end %>
+
+    <%# Language toggle — segmented, both options visible. Switches via fetch so the
+        menu stays open (new locale applies on the next navigation). %>
+    <% locales = cms_available_locales %>
+    <% if locales.size > 1 %>
+      <div class="flex items-center justify-between gap-2.5 px-3 py-2">
+        <span class="inline-flex items-center gap-2.5 text-[13px] text-[#1c1917]">
+          <svg class="w-3.5 h-3.5 text-[#78716c]" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 21a9 9 0 100-18 9 9 0 000 18zM3.6 9h16.8M3.6 15h16.8M11 3c-2.2 2.2-3.5 5.2-3.5 9s1.3 6.8 3.5 9m2 0c2.2-2.2 3.5-5.2 3.5-9S15.2 5.2 13 3" /></svg>
+          <%= t("ruby_cms.admin.topbar.language", default: "Taal") %>
+        </span>
+        <div class="inline-flex rounded-md border border-[#e9e4d4] bg-[#faf8f3] p-0.5" data-locale-url="<%= admin_locale_path %>">
+          <% locales.each do |loc| %>
+            <button type="button"
+                    data-locale="<%= loc %>"
+                    data-active="<%= loc == I18n.locale %>"
+                    data-action="click->admin--topbar#setLocale"
+                    class="h-6 px-2 rounded text-[11px] font-semibold uppercase text-[#78716c] transition-colors cursor-pointer data-[active=true]:bg-white data-[active=true]:text-[#1c1917] data-[active=true]:shadow-sm">
+              <%= loc.to_s %>
+            </button>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+
+    <button type="button" data-action="click->admin--topbar#closeAll click->admin--shortcuts-overlay#open"
+            class="w-full flex items-center gap-2.5 px-3 py-2 text-[13px] text-[#1c1917] hover:bg-[#faf8f3] border-0 bg-transparent cursor-pointer">
+      <svg class="w-3.5 h-3.5 text-[#78716c]" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="2" y="6" width="20" height="12" rx="2" /><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M8 18h8" /></svg>
+      <span class="flex-1 text-left"><%= t("ruby_cms.admin.topbar.shortcuts", default: "Toetsenbord shortcuts") %></span>
+      <kbd class="inline-flex items-center justify-center h-5 px-1.5 rounded border border-[#e9e4d4] bg-[#faf8f3] text-[10.5px] font-mono text-[#78716c]">?</kbd>
+    </button>
+
+    <div class="h-px bg-[#e9e4d4] my-1"></div>
+
+    <% if respond_to?(:main_app, true) && main_app.respond_to?(:root_path) %>
+      <%= link_to main_app.root_path, target: "_blank", class: "flex items-center gap-2.5 px-3 py-2 text-[13px] text-[#1c1917] hover:bg-[#faf8f3] no-underline" do %>
+        <svg class="w-3.5 h-3.5 text-[#78716c]" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10 6H6a2 2 0 00-2 2v10a2 2 0 002 2h10a2 2 0 002-2v-4M14 4h6m0 0v6m0-6L10 14" /></svg>
+        <span class="flex-1"><%= t("ruby_cms.admin.topbar.view_site", default: "Bekijk site") %></span>
+      <% end %>
+    <% end %>
+
+    <% if respond_to?(:main_app, true) && main_app.respond_to?(:session_path) %>
+      <%= button_to main_app.session_path, method: :delete, data: { turbo_confirm: t("nav.logout_confirm", default: "Are you sure you want to logout?") }, class: "w-full flex items-center gap-2.5 px-3 py-2 text-[13px] text-red-600 hover:bg-red-50 border-0 bg-transparent cursor-pointer" do %>
+        <svg class="w-3.5 h-3.5" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1" /></svg>
+        <span class="flex-1 text-left"><%= t("ruby_cms.admin.topbar.logout", default: "Uitloggen") %></span>
+      <% end %>
+    <% end %>
+  </div>
+</div>

data/lib/generators/ruby_cms/templates/views/layouts/admin/topbar/_search_trigger.html.erb

@@ -0,0 +1,9 @@
+<%# Global ⌘K search trigger — icon only (opens the command palette popup). %>
+<button type="button"
+        data-action="click->admin--command-palette#open"
+        title="<%= t('ruby_cms.admin.topbar.search', default: 'Zoek of spring naar…') %> (⌘K)"
+        aria-label="<%= t('ruby_cms.admin.topbar.search', default: 'Zoek of spring naar…') %>"
+        class="inline-flex items-center justify-center w-8 h-8 rounded-md border border-transparent text-[#78716c] hover:bg-[#faf8f3] hover:text-[#1c1917] transition-colors">
+  <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M21 21l-4.35-4.35M11 19a8 8 0 100-16 8 8 0 000 16z" /></svg>
+  <span class="sr-only" data-admin--topbar-target="modKey"></span>
+</button>

data/lib/generators/ruby_cms/templates/views/layouts/admin/topbar/_shortcuts_button.html.erb

@@ -0,0 +1,8 @@
+<%# Opens keyboard shortcuts overlay. %>
+<button type="button"
+        data-action="click->admin--shortcuts-overlay#open"
+        title="<%= t("ruby_cms.admin.topbar.shortcuts_title", default: "Toetsenbord shortcuts (?)") %>"
+        aria-label="Shortcuts"
+        class="inline-flex items-center justify-center w-8 h-8 rounded-md border border-transparent text-[#78716c] hover:bg-[#faf8f3] hover:text-[#1c1917] transition-colors">
+  <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24"><rect x="2" y="6" width="20" height="12" rx="2" /><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 10h.01M10 10h.01M14 10h.01M18 10h.01M6 14h.01M10 14h.01M18 14h.01M14 14h.01M8 18h8" /></svg>
+</button>

data/lib/generators/ruby_cms/templates/views/shared/_maintenance_banner.html.erb

@@ -0,0 +1,10 @@
+<%# Visitor-facing maintenance banner. Shown when Settings → General → maintenance_mode is on. %>
+<% if cms_maintenance_active? && cms_maintenance_message.present? %>
+  <div role="status"
+       class="sticky top-0 z-[100] w-full bg-amber-500 text-amber-950 px-4 py-2.5 text-center text-sm font-medium shadow-md flex items-center justify-center gap-2">
+    <svg class="w-4 h-4 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
+      <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01M4.93 19h14.14c1.54 0 2.5-1.67 1.73-3L13.73 4a2 2 0 00-3.46 0L3.2 16c-.77 1.33.19 3 1.73 3z" />
+    </svg>
+    <span><%= cms_maintenance_message %></span>
+  </div>
+<% end %>

data/lib/ruby_cms/app_wiring.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyCms
+  # Wires the host app's config/application.rb so the copied runtime in lib/ruby_cms
+  # loads at boot:
+  #   * `require_relative "../lib/ruby_cms"` right after Bundler.require (defines
+  #     RubyCms.configure et al., which config/initializers/admin.rb depends on)
+  #   * adds `ruby_cms` to `config.autoload_lib(ignore: ...)` so Zeitwerk leaves the
+  #     manually-required tree alone.
+  # Idempotent: safe to run on every install/add.
+  class AppWiring
+    REQUIRE_LINE = 'require_relative "../lib/ruby_cms"'
+
+    def initialize(app_root:)
+      @path = Pathname.new(app_root).join("config/application.rb")
+    end
+
+    def apply! # rubocop:disable Naming/PredicateMethod
+      return false unless @path.exist?
+
+      content = @path.read
+      updated = add_autoload_ignore(add_require(content))
+      return false if updated == content
+
+      @path.write(updated)
+      true
+    end
+
+    private
+
+    def add_require(content)
+      return content if content.include?(REQUIRE_LINE)
+      return content unless content =~ /^([ \t]*)Bundler\.require.*\n/
+
+      indent = ::Regexp.last_match(1)
+      content.sub(/^([ \t]*Bundler\.require.*\n)/) { "#{::Regexp.last_match(1)}\n#{indent}#{REQUIRE_LINE}\n" }
+    end
+
+    def add_autoload_ignore(content)
+      if (m = content.match(/autoload_lib\(ignore:\s*%w[\[(]([^\])]*)[\])]\)/))
+        words = m[1].split
+        return content if words.include?("ruby_cms")
+
+        content.sub(m[0], "autoload_lib(ignore: %w[#{(words + ['ruby_cms']).join(' ')}])")
+      elsif content.include?("class Application < Rails::Application\n")
+        content.sub(/(class Application < Rails::Application\n)/) do
+          "#{::Regexp.last_match(1)}    config.autoload_lib(ignore: %w[assets tasks ruby_cms])\n"
+        end
+      else
+        content
+      end
+    end
+  end
+end

data/lib/ruby_cms/auth_wiring.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyCms
+  # Wires the host app's authentication into RubyCMS:
+  #   * `include Permittable` in the User model (Permittable is copied by the core module)
+  #   * exposes `current_user` from the generated Authentication concern
+  # The actual `rails g authentication` run is driven by the Installer (it needs a boot);
+  # this unit only checks for the model and patches the generated files. Idempotent.
+  class AuthWiring
+    NOTIFICATIONS_ASSOCIATION =
+      %(  has_many :notifications, as: :recipient, dependent: :destroy, class_name: "Noticed::Notification")
+
+    def initialize(app_root:)
+      @root = Pathname.new(app_root)
+    end
+
+    def user_model_present?
+      @root.join("app/models/user.rb").exist?
+    end
+
+    # Patch the generated files. Returns the list of files changed.
+    def patch!
+      [patch_user, patch_authentication_concern].compact
+    end
+
+    private
+
+    def patch_user
+      path = @root.join("app/models/user.rb")
+      return nil unless path.exist?
+
+      content = path.read
+      additions = []
+      additions << "  include Permittable" unless content.include?("include Permittable")
+      additions << NOTIFICATIONS_ASSOCIATION unless content.include?("Noticed::Notification")
+      return nil if additions.empty?
+      return nil unless content =~ /class User .*\n/
+
+      path.write(content.sub(/(class User .*\n)/) { "#{::Regexp.last_match(1)}#{additions.join("\n")}\n" })
+      "app/models/user.rb"
+    end
+
+    def patch_authentication_concern
+      path = @root.join("app/controllers/concerns/authentication.rb")
+      return nil unless path.exist?
+
+      content = path.read
+      return nil if content.include?("def current_user")
+
+      content = content.sub(
+        "    helper_method :authenticated?\n",
+        "    helper_method :authenticated?, :current_user\n"
+      )
+      content = content.sub(/^(\s*)private\n/) do
+        indent = ::Regexp.last_match(1)
+        "#{indent}private\n\n#{indent}  def current_user\n#{indent}    Current.user\n#{indent}  end\n"
+      end
+      path.write(content)
+      "app/controllers/concerns/authentication.rb"
+    end
+  end
+end

data/lib/ruby_cms/cli.rb

@@ -1,168 +1,228 @@
 # frozen_string_literal: true
 
 require "thor"
+require "ruby_cms/manifest_data"
+require "ruby_cms/installer"
+require "ruby_cms/syncer"
+require "ruby_cms/updater"
+require "ruby_cms/version"
 
 module RubyCms
+  # Standalone `ruby_cms` CLI: install (interactive), sync (app->gem), update (gem->app).
   class CLI < Thor
-    default_task :setup_admin
+    def self.parse_modules(str)
+      return [] if str.nil? || str.strip.empty?
 
-    desc "setup_admin",
-         "Interactively create or select the first admin user and grant full permissions"
-    def setup_admin
-      RunSetupAdmin.call(shell:)
+      str.split(",").map {|s| s.strip.to_sym }
     end
 
-    private
-
-    def shell
-      @shell ||= Thor::Shell::Basic.new
-    end
-  end
+    def self.exit_on_failure? = true
 
-  # Logic for the interactive first-admin setup. Uses Thor::Shell for prompts.
-  class RunSetupAdmin
-    ADMIN_PERMISSION_KEYS = %w[
-      manage_admin manage_permissions manage_content_blocks manage_visitor_errors manage_analytics
-    ].freeze
+    desc "install", "Install RubyCMS admin into the current Rails app (interactive module picker)"
+    method_option :modules, type: :string, desc: "Comma list of optional modules (non-interactive)"
+    method_option :add, type: :string, desc: "Add modules to an existing install"
+    def install
+      app_root = detect_app_root!
+      installer = Installer.new(
+        manifest: RubyCms.manifest, templates_root: templates_root,
+        app_root: app_root, shell: ShellRunner.new(self, app_root), version: RubyCms::VERSION
+      )
 
-    class << self
-      def call(shell: Thor::Shell::Basic.new)
-        new(shell:).call
+      modules =
+        if options[:add]
+          installer.add(new_keys: self.class.parse_modules(options[:add]))
+        else
+          selected = options[:modules] ? self.class.parse_modules(options[:modules]) : pick_modules
+          installer.install(selected:)
+        end
+
+      say "\n#{set_color('✓ RubyCMS installed', :red, :bold)} — #{modules.size} modules"
+      say "  #{set_color(modules.map(&:key).join(', '), :cyan)}"
+
+      if yes?("\nCreate your admin user now? (runs ruby_cms:setup_admin) [y/N]")
+        # Interactive (prompts for email/password) — run with an inherited TTY, not the
+        # capturing ShellRunner.
+        system("bin/rails ruby_cms:setup_admin", chdir: app_root)
+        say "\nNext: #{set_color('bin/rails server', :yellow)} → #{set_color('/admin', :yellow)}"
+      else
+        say "\nNext: #{set_color('bin/rails ruby_cms:setup_admin', :yellow)} → " \
+            "#{set_color('bin/rails server', :yellow)} → #{set_color('/admin', :yellow)}"
       end
+    rescue Installer::Error => e
+      raise Thor::Error, "✗ Install aborted: #{e.message}"
+    end
+
+    desc "sync", "Push gem-owned files from a host app back into the gem templates"
+    method_option :from, type: :string, default: "../portfolio", desc: "Source app path"
+    method_option :dry_run, type: :boolean, default: false
+    method_option :include_new, type: :boolean, default: false,
+                                desc: "Also create files that don't exist in the gem yet (default: update existing only)"
+    def sync
+      result = Syncer.new(
+        manifest: RubyCms.manifest, source_root: File.expand_path(options[:from]),
+        templates_root: templates_root
+      ).sync(dry_run: options[:dry_run], include_new: options[:include_new])
+      say "#{'[dry-run] ' if options[:dry_run]}#{result.changed.size} changed, #{result.unchanged.size} unchanged.", :green
+      result.changed.each {|f| say "  ~ #{f}", :cyan }
+      report_skipped_new(result.skipped_new)
+      report_excluded(result.excluded)
+    end
+
+    desc "update", "Pull new gem versions of installed modules into the current app"
+    method_option :only, type: :string, desc: "Comma list to restrict the update"
+    method_option :dry_run, type: :boolean, default: false
+    def update
+      result = Updater.new(
+        manifest: RubyCms.manifest, templates_root: templates_root, app_root: detect_app_root!
+      ).update(dry_run: options[:dry_run], only: options[:only] && self.class.parse_modules(options[:only]))
+      say "#{'[dry-run] ' if options[:dry_run]}#{result.changed.size} file(s) updated.", :green
+      result.changed.each {|f| say "  ~ #{f}", :cyan }
+      report_excluded(result.excluded)
     end
 
-    def initialize(shell:)
-      @shell = shell
-    end
-
-    def call
-      RubyCms::Permission.ensure_defaults!
-      user_class = Rails.application.config.ruby_cms.user_class_name.constantize
-      email_attr = user_class.column_names.include?("email_address") ? :email_address : :email
+    private
 
-      user = choose_or_create_user(user_class, email_attr)
-      return if user.nil?
+    def report_skipped_new(skipped)
+      return unless skipped&.any?
 
-      grant_permissions(user)
-      notify_success(user, email_attr)
+      say "\n#{skipped.size} new file(s) skipped (not yet owned by the gem). " \
+          "Re-run with --include-new to add them deliberately:", :yellow
+      skipped.each {|f| say "  + #{f}", :yellow }
     end
 
-    private
+    def report_excluded(excluded)
+      return unless excluded&.any?
 
-    def notify_success(user, email_attr)
-      @shell.say(
-        "\nDone. #{user.public_send(email_attr)}
-        now has: #{ADMIN_PERMISSION_KEYS.join(', ')}.", :green
-      )
-      @shell.say("Visit /admin to sign in.", :green)
+      say "\n#{excluded.size} file(s) excluded (gem default or .ruby_cms.yml `exclude:`):", :yellow
+      excluded.each {|f| say "  − #{f}", :yellow }
     end
 
-    def choose_or_create_user(user_class, email_attr)
-      users = fetch_recent_users(user_class)
-
-      if users.any?
-        prompt_existing_users(users, email_attr)
-      else
-        @shell.say("\nNo users yet. Create the first admin user.")
-        create_user(user_class, email_attr)
-      end
+    def templates_root
+      File.expand_path("../generators/ruby_cms/templates", __dir__)
     end
 
-    def fetch_recent_users(user_class)
-      user_class.order(id: :asc).limit(20).to_a
-    end
+    def detect_app_root!
+      dir = Dir.pwd
+      loop do
+        return dir if File.file?(File.join(dir, "config/application.rb"))
 
-    def prompt_existing_users(users, email_attr)
-      display_users(users, email_attr)
-      choice = ask_for_user_choice(users.size)
+        parent = File.dirname(dir)
+        break if parent == dir
 
-      case choice
-      when "0"
-        find_or_create_by_email(users.first.class, email_attr)
-      else
-        select_user_or_fallback(users, choice.to_i, email_attr)
+        dir = parent
       end
+      raise Thor::Error, "Not in a Rails app (config/application.rb not found)."
     end
 
-    def display_users(users, email_attr)
-      @shell.say("\nExisting users:", :bold)
-      users.each_with_index do |u, i|
-        @shell.say("  #{i + 1}. #{u.public_send(email_attr)}")
-      end
-      @shell.say("  0. Enter another email (or create new user)")
-    end
+    def pick_modules
+      require "tty-prompt"
+      prompt = TTY::Prompt.new(active_color: :red)
+      manifest = RubyCms.manifest
 
-    def ask_for_user_choice(max)
-      @shell.ask("Select (0–#{max}):", default: "1").to_s.strip
-    end
+      say set_color("Base modules (always installed):", :cyan, :bold)
+      manifest.base_modules.each do |m|
+        say "  #{set_color('✓', :red, :bold)} #{m.key}#{set_color(" — #{m.description}", :white)}"
+      end
 
-    def select_user_or_fallback(users, index, email_attr)
-      if index.between?(1, users.size)
-        users[index - 1]
-      else
-        find_or_create_by_email(users.first.class, email_attr)
+      prompt.multi_select(
+        set_color("Select optional modules (Space to toggle, Enter to confirm):", :cyan, :bold),
+        per_page: 20, echo: false
+      ) do |menu|
+        manifest.optional_modules.each do |mod|
+          menu.choice "#{mod.key} — #{mod.description}", mod.key
+        end
       end
     end
 
-    def find_or_create_by_email(user_class, email_attr)
-      email = @shell.ask("Email:").to_s.strip
-      return nil if email.blank?
+    # Runs shell commands in the host app root with a compact, fancy status line:
+    # a spinner while running, a red check on success (output hidden), or a red
+    # cross plus the captured output when a step fails.
+    class ShellRunner
+      FRAMES = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+
+      # Friendly labels per command (matched by substring); falls back to the command.
+      LABELS = {
+        "bundle install" => "Installing gems",
+        "generate authentication" => "Setting up authentication",
+        "ruby_ui:install" => "Installing UI components",
+        "tailwindcss:install" => "Installing Tailwind",
+        "ahoy:install" => "Installing analytics",
+        "action_text:install" => "Installing rich text",
+        "noticed:install:migrations" => "Installing notifications",
+        "db:migrate" => "Running migrations",
+        "seed_permissions" => "Seeding permissions",
+        "tailwindcss:build" => "Building styles"
+      }.freeze
+
+      # Noise lines suppressed even on failure (environment chatter, not real errors).
+      NOISE = %r{Unresolved or ambiguous specs|Clearing out unresolved|Available/installed versions|already initialized constant|report a bug if this causes|gem cleanup}
+
+      def initialize(thor, app_root)
+        @thor = thor
+        @app_root = app_root
+      end
 
-      user = user_class.find_by(email_attr => email)
-      if user
-        user
-      else
-        @shell.say("User not found.")
-        create = @shell.yes?("Create new user with this email?", default: true)
-        create ? create_user_with_email(user_class, email_attr, email) : nil
+      # Returns true on success, false on failure (so the Installer can decide whether
+      # a failed step is fatal).
+      def run(cmd) # rubocop:disable Naming/PredicateMethod
+        require "open3"
+        label = label_for(cmd)
+        done = false
+        spinner = spin(label) { done }
+        output, status = Open3.capture2e(cmd, chdir: @app_root.to_s)
+        done = true
+        spinner&.join
+
+        if status.success?
+          @thor.say("#{clear}  #{@thor.set_color('✓', :red, :bold)} #{label}")
+          true
+        else
+          @thor.say("#{clear}  #{@thor.set_color('✗', :red, :bold)} #{label}")
+          @thor.say(@thor.set_color(filter_noise(output), :red))
+          false
+        end
       end
-    end
 
-    def create_user(user_class, email_attr)
-      email = @shell.ask("Email:").to_s.strip
-      return nil if email.blank?
+      def say(msg, color=nil) = @thor.say(msg, color)
 
-      create_user_with_email(user_class, email_attr, email)
-    end
+      # A bold cyan section header.
+      def heading(text) = @thor.say(@thor.set_color(text, :cyan, :bold))
 
-    def create_user_with_email(user_class, email_attr, email)
-      password, password_confirmation = ask_password_and_confirmation
-      return nil if password.blank? || password_confirmation.blank?
-
-      attrs = {
-        email_attr => email, password: password,
-        password_confirmation: password_confirmation
-      }
-      user_class.create!(attrs)
-    rescue ActiveRecord::RecordInvalid => e
-      @shell.say("Could not create user: #{e.record.errors.full_messages.to_sentence}", :red)
-      nil
-    end
+      # A red ✓ item: bright check, plain label, dimmed hint (e.g. a description).
+      def ok(label, hint: nil)
+        line = "  #{@thor.set_color('✓', :red, :bold)} #{label}"
+        line += @thor.set_color(" — #{hint}", :white) if hint
+        @thor.say(line)
+      end
 
-    def ask_password_and_confirmation
-      password = ask_password("Password:")
-      return [nil, nil] if password.blank?
+      private
 
-      password_confirmation = ask_password("Password (again):")
-      return [password, password_confirmation] unless password != password_confirmation
+      def label_for(cmd)
+        LABELS.find {|fragment, _| cmd.include?(fragment) }&.last || cmd
+      end
 
-      @shell.say("Passwords did not match. Aborted.", :red)
-      [nil, nil]
-    end
+      def filter_noise(output)
+        output.each_line.grep_v(NOISE).map {|line| "    #{line}" }.join
+      end
 
-    def ask_password(prompt)
-      if $stdin.respond_to?(:noecho) && $stdin.tty?
-        @shell.say("#{prompt} (hidden)")
-        $stdin.noecho { $stdin.gets&.chomp }.to_s
-      else
-        @shell.ask("#{prompt}:").to_s.strip
+      # Cursor reset codes only when attached to a TTY (avoids raw escapes in logs).
+      def clear
+        $stdout.tty? ? "\r\e[2K" : ""
       end
-    end
 
-    def grant_permissions(user)
-      ADMIN_PERMISSION_KEYS.each do |key|
-        perm = RubyCms::Permission.find_by!(key:)
-        RubyCms::UserPermission.find_or_create_by!(user: user, permission: perm)
+      # Animate a spinner on the same line until the block returns true. No-op without a TTY.
+      def spin(label, &)
+        return nil unless $stdout.tty?
+
+        Thread.new do
+          i = 0
+          until yield
+            $stdout.print("\r\e[2K#{@thor.set_color(FRAMES[i % FRAMES.size], :cyan)} #{label}…")
+            $stdout.flush
+            sleep 0.08
+            i += 1
+          end
+        end
       end
     end
   end

data/lib/ruby_cms/excludes.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module RubyCms
+  # App-relative paths that `ruby_cms update` / `ruby_cms sync` must never touch.
+  #
+  # Two layers:
+  #   * DEFAULT — gem-owned files that hosts are expected to customize (config
+  #     initializers, generated nav). Shipped once, then left alone.
+  #   * Per-app — globs listed under `exclude:` in the host's .ruby_cms.yml.
+  #
+  # Both are matched against the APP-relative path with File.fnmatch (globs +
+  # extglob), e.g. "config/initializers/admin.rb" or "app/views/layouts/admin/*".
+  module Excludes
+    DEFAULT = [
+      "config/initializers/admin.rb",            # RubyCms.configure block — host config
+      "config/initializers/admin_dashboard.rb",  # dashboard blocks — host-arranged
+      "config/initializers/admin_nav.rb",        # sidebar nav — host-arranged / generated
+      "config/initializers/admin_pages.rb",      # app-registered admin pages
+      "config/initializers/ruby_cms_custom_settings.rb", # host-registered custom settings
+      "app/assets/builds/**"                     # compiled Tailwind/CSS — never overwrite
+    ].freeze
+
+    FNM_FLAGS = File::FNM_PATHNAME | File::FNM_EXTGLOB
+
+    module_function
+
+    # Combine gem defaults with the host's per-app excludes.
+    def all(extra=[])
+      (DEFAULT + Array(extra)).uniq
+    end
+
+    def excluded?(app_relative_path, extra=[])
+      # Normalize first ("./x", "a//b", "a/../b" → clean) so the safety net can't be
+      # bypassed by a non-canonical path.
+      path = Pathname.new(app_relative_path.to_s).cleanpath.to_s
+      all(extra).any? {|glob| File.fnmatch?(glob, path, FNM_FLAGS) }
+    end
+  end
+end