frozen_rails 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e185eb3c340edef2f4261d427c7f89af260850823fd580424605617747da9737
-  data.tar.gz: fd604198415fdede3bf2e27565c96550d747d14a92c1faf04308c0fa99c764b0
+  metadata.gz: 4a88e369b28d7f01071814ba007495f9a1d573d3b8c0b0c59b0e48decb22637d
+  data.tar.gz: ea76d23b0fcedf87e504189e8019e39d21dc6ffe7b203cac5446a07d84cebe97
 SHA512:
-  metadata.gz: d618e3625585a1b41fa98665773113f9d12826881054dbcc38d9287829ad5b2fc1f4efabef3a4485542342280083845e4fbaaf0e786bbbfdb778479c00a6dcd0
-  data.tar.gz: c8b5371939545258ea853ed909f6acbe046874c914dfea7b2fd6d03e0aca75ca08c4bd879778ccaced3f25568347531175cdbab2b052ace3e2fb178181340716
+  metadata.gz: b8d60e302866a07592e7f2b1c5605583cffa49f2084c31a390441eb3f69a50859565ec0e0c72211ad551bb0715bc754d45be654552cea32e162f0afb99bb99dd
+  data.tar.gz: 2dd187e1d486d6b299fd731a7575d8e6560674ffe0e3e99479ff92fa0432c6c699c3d3085368d97a010bd63a8bf8527e79f37731d926ad03c92b697f2bd51679

data/README.md

@@ -4,7 +4,12 @@
 
 # Frozen Rails
 
-TBD
+DISCLAIMER: I generated this repo with AI and haven't tested it yet.
+I will verify manually verify the functionality and use AI to generate a test suite as soon as I get to it. Until then, use at your own risk.
+
+This repo automates the instructions from [rails-static.com](https://rails-static.com) and some additional setup which was created by me.
+
+Running the full setup `bin/rails g frozen:rails` should turn a fresh Rails application into a full static-site generator that supports Markdown AND structured data (SQLite). The SSG is very developer-focused and might be cumbersome to use for non-devs.
 
 ## Installation
 
@@ -33,7 +38,78 @@ gem "frozen_rails"
 
 ## Usage
 
-TBD
+The gem ships with Rails generators under the `frozen` namespace. After including `frozen_rails` in your Rails application the following generators will be available:
+
+```bash
+# ✅ passes, ✅ works correctly, ❌ has test suite
+
+# - Adds `decant` with a custom extension.
+# - Adds `kramdown`, `rouge` and ERB interpolation for `.md` files.
+# - Adds application scaffold.
+
+bin/rails g frozen:md
+# - Prompts for a rouge theme. Pass `--rouge_theme=name` to run non-interactive.
+```
+
+```bash
+# ✅ passes, ✅ works correctly, ❌ has test suite
+
+# - Adds `parklife`
+# - Adds `.gitlab-ci.yml` and tweaks parklife config.
+
+bin/rails g frozen:ssg
+```
+
+```bash
+# ✅ passes, ❓ works correctly, ❌ has test suite
+
+# - sqlite uuid patch
+# - static_db initializer
+# - friendly_id and Avo configuration
+
+bin/rails g frozen:db
+```
+
+```bash
+# ✅ passes, ❓ works correctly, ❌ has test suite
+
+# - SEO helpers
+# - sitemap/robots skeleton
+
+bin/rails g frozen:seo
+```
+
+```bash
+# ✅ passes, ❓ works correctly, ❌ has test suite
+
+# - water.css
+# - sample importmap pin
+# - Hotwire Spark & Action Cable configuration
+# - Stimulus hotkey controller
+
+bin/rails g frozen:ui
+```
+
+```bash
+# ✅ passes, ❓ works correctly, ❌ has test suite
+
+# - copy custom lib templates
+# - add autoload/generator config to application.rb
+
+bin/rails g frozen:dx
+```
+
+```bash
+# ✅ passes, ❓ works correctly, ❌ has test suite
+
+# Full Rails setup (runs all frozen generators in order)
+
+bin/rails g frozen:rails
+```
+
+```bash
+# FUTURE: frozen:meetup
+```
 
 ## Contributing
 

data/lib/frozen_rails/appendable.rb

@@ -0,0 +1,14 @@
+module Appendable
+  extend ActiveSupport::Concern
+
+  private
+
+  def append_to_application_config(content)
+    inject_into_file "config/application.rb", optimize_indentation("\n#{content}", 4), before: /  end\nend(?:\n)\z/, verbose: false
+  end
+
+  def append_to_routes(content)
+    inject_into_file "config/routes.rb", optimize_indentation("\n#{content}", 2), before: /end(?:\n)\z/, verbose: false
+  end
+
+end

data/lib/frozen_rails/bundleable.rb

@@ -0,0 +1,11 @@
+module Bundleable
+  extend ActiveSupport::Concern
+
+  private
+
+  def bundle!
+    Bundler.with_unbundled_env do
+      system "bundle install"
+    end
+  end
+end

data/lib/frozen_rails/generator.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "frozen_rails/appendable"
+require "frozen_rails/bundleable"
+require "frozen_rails/taggable"
+
+module FrozenRails
+  class Generator < Rails::Generators::Base
+    include Appendable
+    include Bundleable
+    include Taggable
+  end
+end

data/lib/frozen_rails/taggable.rb

@@ -0,0 +1,59 @@
+module Taggable
+  extend ActiveSupport::Concern
+
+  included do
+    class_option :cleanup_frozen_tags, type: :boolean, default: true, hide: true
+  end
+
+  private
+
+  def add_frozen_gems(content, env: nil)
+    add_frozen_gemfile_tags(env:)
+    insert_into_file "Gemfile", optimize_indentation("#{content}\n", env ? 2 : 0), before: frozen_end_tag(env:)
+    cleanup_frozen_tags!(env:)
+  end
+
+  def frozen_start_tag(env: nil)
+    env_attribute = env ? " env=\"#{env}\"" : ""
+    "# <frozen_rails#{env_attribute}>"
+  end
+
+  def frozen_end_tag(env: nil)
+    frozen_start_tag(env:).gsub('# <', '# </')
+  end
+
+  def add_frozen_gemfile_tags(env: nil)
+    unless File.read("Gemfile").include?(frozen_start_tag(env:))
+      newlines = env ? "\n" : "\n\n"
+      tags = "#{frozen_start_tag(env:)}#{newlines}#{frozen_end_tag(env:)}"
+      insert_into_file "Gemfile", tags, after: frozen_tags_after(env:)
+    end
+  end
+
+  def frozen_tags_after(env: nil)
+    case env
+    when nil
+      /frozen_rails[^\n]*\n/
+    when 'local'
+      "group :development, :test do\n"
+    when 'development'
+      "group :development do\n"
+    else
+      raise "Unsupported env!"
+    end
+  end
+
+  def cleanup_frozen_tags!(env: nil)
+    if options[:cleanup_frozen_tags]
+      gsub_file! "Gemfile", /[^\n]*#{frozen_start_tag(env:)}[^\n]*\n/, ''
+      gsub_file! "Gemfile", /[^\n]*#{frozen_end_tag(env:)}[^\n]*\n/, ''
+    end
+  end
+
+  def cleanup_all_frozen_tags!
+    cleanup_frozen_tags!
+    cleanup_frozen_tags!(env: 'local')
+    cleanup_frozen_tags!(env: 'development')
+  end
+
+end

data/lib/frozen_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FrozenRails # :nodoc:
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/lib/frozen_rails.rb

@@ -1,4 +1,3 @@
 # frozen_string_literal: true
 
 require "frozen_rails/version"
-require "frozen_rails/railtie" if defined?(Rails::Railtie)

data/lib/generators/frozen/db_generator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "frozen_rails/generator"
+
+module Frozen
+  module Generators
+    class DbGenerator < FrozenRails::Generator
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Prepare a Rails app for SQLite UUIDs, static_db, Avo and FriendlyId"
+
+      def add_gems
+        add_frozen_gems <<~RUBY
+          # frozen:db
+          gem "sqlite_extensions-uuid"
+          gem "static_db"
+          gem "friendly_id"
+        RUBY
+
+        add_frozen_gems <<~RUBY, env: "local"
+          # frozen:db
+          gem "avo", ">= 3.2"
+        RUBY
+      end
+
+      def bundle_gems
+        bundle!
+      end
+
+      # configure database.yml for sqlite uuid extension
+      def configure_database_yml
+        return unless File.exist?("config/database.yml")
+
+        inject_into_file "config/database.yml", after: "adapter: sqlite3\n" do
+          <<~YML
+            extensions:
+              - <%= SqliteExtensions::UUID.to_path %>
+          YML
+        end
+      end
+
+      # create initializer for sqlite uuid generator patch
+      def create_sqlite_uuid_initializer
+        template "db/sqlite_uuid.rb", "config/initializers/sqlite_uuid.rb"
+      end
+
+      # create initializer for static_db configuration
+      def create_static_db_initializer
+        template "db/static_db.rb", "config/initializers/static_db.rb"
+      end
+
+      # create friendly_id initializer
+      def create_friendly_id_initializer
+        template "db/friendly_id.rb", "config/initializers/friendly_id.rb"
+      end
+
+      # create a minimal avo initializer stub
+      def create_avo_initializer
+        template "db/avo.rb", "config/initializers/avo.rb"
+      end
+
+      # reminder to run generators
+      def post_install_reminders
+        say_status :info, "Run `rails generate friendly_id` to create slug migrations."
+      end
+    end
+  end
+end

data/lib/generators/frozen/dx_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "frozen_rails/generator"
+
+module Frozen
+  module Generators
+    class DxGenerator < FrozenRails::Generator
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install developer experience helpers: custom lib templates and generator config"
+
+      # copy over the lib folder content from static example
+      def copy_lib_templates
+        directory "dx/lib", "lib"
+      end
+
+      # inject configuration into config/application.rb
+      def configure_application
+        return unless File.exist?("config/application.rb")
+
+        inject_into_file "config/application.rb",
+          after: "class Application < Rails::Application\n" do
+          <<~RUBY
+            # Please, add to the `ignore` list any other `lib` subdirectories that do
+            # not contain `.rb` files, or that should not be reloaded or eager loaded.
+            # Common ones are `templates`, `generators`, or `middleware`, for example.
+            config.autoload_lib(ignore: %w[assets tasks])
+
+            config.generators do |g|
+              g.orm :active_record, primary_key_type: :uuid
+              g.test_framework false
+            end
+
+            config.active_storage.draw_routes = true
+
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/generators/frozen/md_generator.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "frozen_rails/generator"
+
+module Frozen
+  module Generators
+    class MdGenerator < FrozenRails::Generator
+      source_root File.expand_path("templates", __dir__)
+
+      # When absent, the generator will prompt interactively (unless running non-interactively).
+      class_option :rouge_theme, type: :string, desc: "Rouge theme to install (runs non-interactive if provided)"
+
+      desc "Set up markdown-powered content with Decant, kramdown, ERB processing and Rouge highlighting"
+
+      def add_gems
+        add_frozen_gems <<~RUBY
+          # frozen:md
+          gem "decant"
+          gem "kramdown"
+          gem "kramdown-parser-gfm"
+          gem "rouge"
+        RUBY
+      end
+
+      def bundle_gems
+        bundle!
+      end
+
+      def create_content_directory
+        empty_directory "content/pages"
+      end
+
+      def copy_files
+        app_files = [
+          "controllers/categories_controller.rb",
+          "controllers/pages_controller.rb",
+          "helpers/markdown_helper.rb",
+          "models/concerns/linkable.rb",
+          "models/category.rb",
+          "models/page.rb",
+          "views/categories/index.html.erb",
+          "views/categories/show.html.erb",
+          "views/pages/show.html.erb",
+        ]
+
+        app_files.each do |app_file|
+          copy_file "md/#{app_file}", "app/#{app_file}"
+        end
+
+        config_files = [
+          "initializers/decant_extensions.rb",
+        ]
+
+        config_files.each do |config_file|
+          copy_file "md/#{config_file}", "config/#{config_file}"
+        end
+
+        content_files = [
+          "pages/frozen-rails.md",
+          "pages/rails-static.md",
+          "pages/rails-static/rails-static-logo.webp",
+        ]
+
+        content_files.each do |content_file|
+          copy_file "md/#{content_file}", "content/#{content_file}"
+        end
+      end
+
+      def add_config
+        append_to_application_config <<~RUBY
+          # frozen:md
+          config.assets.paths << Rails.root.join("content")
+          config.action_dispatch.rescue_responses["Decant::FileNotFound"] = :not_found
+        RUBY
+      end
+
+      # Add routes for pages
+      def add_routes
+        append_to_routes <<~RUBY
+          # frozen:md
+          root "categories#index"
+
+          # Use `Regexp.union` instead of array for constraints!
+          # https://github.com/rails/rails/issues/47726
+          constraints slug: Regexp.union(Category.all.map(&:slug)) do
+            resources :categories, param: :slug, only: [:index, :show]
+          end
+
+          resources :pages, param: :slug, only: [:show]
+        RUBY
+      end
+
+      def generate_rouge_css_stylesheet
+        theme = options[:rouge_theme]
+
+        if theme.blank? && behavior == :invoke && $stdin.tty?
+          # Run in subshell so we pick up newly installed gem without needing to require it in the current process.
+          themes = `bundle exec ruby -e "require 'rouge'; puts Rouge::Theme.registry.keys.sort"`.split("\n")
+
+          say_status :info, "Available Rouge themes (#{themes.size}):", :blue
+          themes.each_with_index { |t, i| say "  #{i + 1}. #{t}" }
+
+          answer = ask("Choose a theme (name or number) [github]")
+
+          theme = if /^\d+$/.match?(answer)
+            themes[answer.to_i - 1]
+          else
+            answer.presence
+          end
+        end
+
+        theme ||= "github"
+
+        say_status :info, "Generating Rouge CSS for theme #{theme}", :blue
+        run "rougify style #{theme} > app/assets/stylesheets/rouge.css"
+      end
+    end
+  end
+end

data/lib/generators/frozen/rails_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "frozen_rails/taggable"
+
+module Frozen
+  module Generators
+    # A meta-generator that runs the other frozen generators in a sensible order.
+    class RailsGenerator < Rails::Generators::Base
+      include Taggable
+
+      desc "Run all frozen setup generators (md, db, seo, ui, dx, ssg)"
+
+      # The method name doesn't matter much; Thor runs all public methods in
+      # order defined by source.
+      def run_all
+        say_status :info, "invoking frozen:md"
+        invoke "frozen:md", [], cleanup_frozen_tags: false
+
+        say_status :info, "invoking frozen:db"
+        invoke "frozen:db", [], cleanup_frozen_tags: false
+
+        say_status :info, "invoking frozen:seo"
+        invoke "frozen:seo", [], cleanup_frozen_tags: false
+
+        say_status :info, "invoking frozen:ui"
+        invoke "frozen:ui", [], cleanup_frozen_tags: false
+
+        say_status :info, "invoking frozen:dx"
+        invoke "frozen:dx", [], cleanup_frozen_tags: false
+
+        say_status :info, "invoking frozen:ssg"
+        invoke "frozen:ssg", [], cleanup_frozen_tags: false
+
+        cleanup_all_frozen_tags!
+      end
+    end
+  end
+end

data/lib/generators/frozen/seo_generator.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "frozen_rails/generator"
+
+module Frozen
+  module Generators
+    class SeoGenerator < FrozenRails::Generator
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Add SEO helpers, metadata partials and sitemap/robots models"
+
+      # add meta partial and update layout
+      def create_og_partial
+        template "seo/_og_meta_tags.html.erb", "app/views/layouts/_og_meta_tags.html.erb"
+      end
+
+      def inject_layout_tags
+        return unless File.exist?("app/views/layouts/application.html.erb")
+
+        inject_into_file "app/views/layouts/application.html.erb",
+          after: "<head>\n" do
+          <<~ERB
+            <%= render 'layouts/og_meta_tags', tags: {
+              title: title,
+              description: description,
+              image: image_url('og-image.jpg'),
+              author: author,
+              type: "website",
+              site_name: site_name,
+              url: canonical_url,
+            } %>
+
+            <%= tag :link, rel: "canonical", href: canonical_url %>
+
+            <%= favicon_link_tag 'favicon.ico', sizes: '32x32' %>
+            <%= favicon_link_tag 'icon.svg', type: 'image/svg+xml' %>
+            <%= favicon_link_tag 'apple-touch-icon.png', rel: 'apple-touch-icon' %>
+
+            <%= tag :meta, name: "robots", content: robots_content %>
+
+          ERB
+        end
+      end
+
+      # helpers for meta tags
+      def add_application_helpers
+        unless File.exist?("app/helpers/application_helper.rb")
+          create_file "app/helpers/application_helper.rb", "module ApplicationHelper\nend\n"
+        end
+
+        inject_into_file "app/helpers/application_helper.rb",
+          after: "module ApplicationHelper\n" do
+          <<~RUBY
+            def site_name
+              "Rails Static"
+            end
+
+            def title
+              [ @page&.title.presence, site_name ].uniq.compact.join(" · ")
+            end
+
+            def description
+              @page.frontmatter&.dig(:description)
+            end
+
+            def author
+              "François Catuhe"
+            end
+
+            def canonical_url
+              url_for(only_path: false)
+            end
+
+            def robots_content
+              Rails.env.production? ? "index, follow" : "noindex, nofollow"
+            end
+
+            def og_meta_tag(key, content)
+              case key
+              when :title, :description, :image
+                tag(:meta, name: key, property: "og:\#{key}", content: content)
+              when :author
+                tag(:meta, name: key, content: content)
+              else
+                tag(:meta, property: "og:\#{key}", content: content)
+              end
+            end
+
+          RUBY
+        end
+      end
+
+      def add_favicon_notice
+        say_status :info, "Add favicons (favicon.ico, icon.svg, apple-touch-icon.png) to app/assets/images and create og-image.jpg"
+      end
+
+      # sitemap models
+      def create_sitemap_models
+        template "seo/sitemap.rb", "app/models/sitemap.rb"
+        template "seo/sitemap_entry.rb", "app/models/sitemap/entry.rb"
+        template "seo/robots_generatable.rb", "app/models/sitemap/robots_generatable.rb"
+      end
+
+      def remove_default_robots
+        remove_file "public/robots.txt" if File.exist?("public/robots.txt")
+      end
+    end
+  end
+end

data/lib/generators/frozen/ssg_generator.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "frozen_rails/generator"
+
+module Frozen
+  module Generators
+    class SsgGenerator < FrozenRails::Generator
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Set up Parklife static site generation with CI workflows and helper scripts"
+
+      def add_gems
+        add_frozen_gems <<~RUBY
+          # frozen:ssg
+          gem "parklife-rails"
+        RUBY
+      end
+
+      def bundle_gems
+        bundle!
+      end
+
+      def run_parklife_init
+        unless system("bundle exec parklife init --rails --github-pages")
+          say_status :warn, "Unable to run parklife init. Please execute manually!"
+        end
+      end
+
+      def setup_gitlab_pages
+        copy_file "ssg/.gitlab-ci.yml", ".gitlab-ci.yml"
+        comment_lines "Parkfile", /config\.nested_index = false/
+      end
+
+    end
+  end
+end

data/lib/generators/frozen/templates/db/avo.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# generated by frozen:db
+# Minimal Avo configuration; adjust as needed.
+Avo.configure do |config|
+  config.root_path = "/avo"
+  config.authorization_client = nil
+  config.explicit_authorization = true
+  config.click_row_to_view_record = true
+end

data/lib/generators/frozen/templates/db/friendly_id.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# generated by frozen:db
+FriendlyId.defaults do |config|
+  # enable the most common modules
+  config.use :reserved
+  config.use :slugged
+  config.use :finders
+  config.use :history
+
+  # a UUID will be appended automatically when a unique slug cannot be generated
+  # suitable reserved words to avoid can be declared here.
+  config.reserved_words = %w[new edit index session login logout users admin]
+end