bridgetown-core 2.0.5 → 2.1.0.beta1

data/lib/bridgetown-core/commands/concerns/{actions.rb → automations.rb}

@@ -2,14 +2,33 @@
 
 module Bridgetown
   module Commands
-    module Actions
+    # Automation tasks to aid in setting up new Bridgetown site configs or plugin setup.
+    # Also includes all of the tasks provided by Freyia
+    module Automations
+      include Freyia::Setup
+
+      def self.included(klass)
+        klass.extend Freyia::Setup::ClassMethods
+      end
+
       using Bridgetown::Refinements
 
       GITHUB_REGEX = %r!https://github\.com!
       GITHUB_TREE_REGEX = %r!#{GITHUB_REGEX}/.*/.*/tree/.*/?!
       GITHUB_BLOB_REGEX = %r!#{GITHUB_REGEX}/.*/.*/blob/!
       GITHUB_REPO_REGEX = %r!github\.com/(.*?/[^/]*)!
+      GITLAB_REGEX = %r!https://gitlab\.com!
+      GITLAB_TREE_REGEX = %r!#{GITLAB_REGEX}/.*/.*/-/tree/.*/?!
+      GITLAB_BLOB_REGEX = %r!#{GITLAB_REGEX}/.*/.*/-/blob/!
+      GITLAB_REPO_REGEX = %r!gitlab\.com/(.*?/[^/]*)!
+      CODEBERG_REGEX = %r!https://codeberg\.org!
+      CODEBERG_TREE_REGEX = %r!#{CODEBERG_REGEX}/.*/.*/src/branch/.*/?!
+      CODEBERG_REPO_REGEX = %r!codeberg\.org/(.*?/[^/]*)!
 
+      # Creates a new Builder class with the provided filename and Ruby code
+      #
+      # @param filename [String]
+      # @param data [String] Ruby code, if block not provided
       def create_builder(filename, data = nil)
         say_status :create_builder, filename
         data ||= yield if block_given?
@@ -27,6 +46,10 @@ module Bridgetown
         create_file("plugins/builders/#{filename}", data, verbose: false)
       end
 
+      # Adds a new JavaScript import statement to the end of existing import statements (if any)
+      #
+      # @param data [String] Ruby code, if block not provided
+      # @param filename [String] supply a filename if the default `index.js` isn't desired
       def javascript_import(data = nil, filename: "index.js") # rubocop:todo Metrics/PerceivedComplexity
         data ||= yield if block_given?
         data += "\n" unless data[-1] == "\n"
@@ -54,6 +77,12 @@ module Bridgetown
         end
       end
 
+      # Uses `bundle add` to add a new gem to the project `Gemfile`
+      #
+      # @param gemname [String]
+      # @param group [String] normally the gem isn't added to any group, but you can specify
+      # a particular group
+      # @param version [String] useful if you need to force a specific version or range
       def add_gem(gemname, group: nil, version: nil)
         options = +""
         options += " -v \"#{version}\"" if version
@@ -66,6 +95,10 @@ module Bridgetown
       end
       alias_method :add_bridgetown_plugin, :add_gem
 
+      # Add an `init` statement to the project's `config/initializers.rb` file
+      #
+      # @param name [Symbol] initializer / plugin name
+      # @param data [String] additional Ruby code, if block not provided
       def add_initializer(name, data = "")
         say_status :initializer, name
         data = yield if block_given?
@@ -84,6 +117,11 @@ module Bridgetown
                          before: %r!^end$!, verbose: false, force: false
       end
 
+      # Similar to the `add_initializer` method, but supports adding arbitrary Ruby code of any
+      # kind to the `config/initializers.rb` file
+      #
+      # @param name [Symbol, String] name of configuration (purely for user display feedback)
+      # @param data [String] Ruby code, if block not provided
       def ruby_configure(name, data = "")
         say_status :configure, name
         data = yield if block_given?
@@ -101,6 +139,10 @@ module Bridgetown
                          before: %r!^end$!, verbose: false, force: false
       end
 
+      # Given the name of a gem, it will analyze that gem's metadata looking for a suitable NPM
+      # companion package. (Requires `npm_add` to be defined.)
+      #
+      # @param gemname [Symbol]
       def add_npm_for_gem(gemname)
         say_status :add_npm, gemname
 
@@ -112,14 +154,23 @@ module Bridgetown
       end
       alias_method :add_yarn_for_gem, :add_npm_for_gem
 
+      # Adds the provided NPM package to the project's `package.json`
+      #
+      # @param package_details [String] the package name, and any optional flags
       def add_npm_package(package_details)
         run "#{Bridgetown::PluginManager.package_manager} #{Bridgetown::PluginManager.package_manager_install_command} #{package_details}" # rubocop:disable Layout
       end
 
+      # Removes an NPM package
+      #
+      # @param package_details [String] the package name, and any optional flags
       def remove_npm_package(package_details)
         run "#{Bridgetown::PluginManager.package_manager} #{Bridgetown::PluginManager.package_manager_uninstall_command} #{package_details}" # rubocop:disable Layout
       end
 
+      # Calls Freyia's `apply` method after transforming the URL according to Automations rules
+      #
+      # @param url [String] URL to a file or a repo
       def apply_from_url(url)
         apply transform_automation_url(url.dup)
       end
@@ -127,6 +178,7 @@ module Bridgetown
       private
 
       def determine_remote_filename(arg)
+        arg = arg.sub(%r!\?.*$!, "") # chop query string if need be
         if arg.end_with?(".rb")
           arg.split("/").then do |segments|
             arg.sub!(%r!/#{segments.last}$!, "")
@@ -138,36 +190,70 @@ module Bridgetown
       end
 
       # TODO: option to download and confirm remote automation?
-      # rubocop:disable Metrics/MethodLength
+      # @param arg [String]
       def transform_automation_url(arg)
         return arg unless arg.start_with?("http")
 
         remote_file = determine_remote_filename(arg)
-        github_match = GITHUB_REGEX.match(arg)
 
-        arg = if arg.start_with?("https://gist.github.com")
+        arg = case arg
+              when GITHUB_REGEX
+                transform_github_url arg
+              when %r{^https://gist.github.com}
                 arg.sub( # rubocop:disable Style/StringConcatenation
                   "https://gist.github.com", "https://gist.githubusercontent.com"
                 ) + "/raw"
-              elsif github_match
-                new_url = arg.sub(GITHUB_REGEX, "https://raw.githubusercontent.com")
-                github_tree_match = GITHUB_TREE_REGEX.match(arg)
-                github_blob_match = GITHUB_BLOB_REGEX.match(arg)
-
-                if github_tree_match
-                  new_url.sub("/tree/", "/")
-                elsif github_blob_match
-                  new_url.sub("/blob/", "/")
-                else
-                  "#{new_url}/#{Bridgetown::Utils.default_github_branch_name(arg)}"
-                end
+              when GITLAB_REGEX
+                transform_gitlab_url arg
+              when CODEBERG_REGEX
+                transform_codeberg_url arg
               else
                 arg
               end
 
         "#{arg}/#{remote_file}"
       end
-      # rubocop:enable Metrics/MethodLength
+
+      def transform_github_url(url)
+        new_url = url.sub(GITHUB_REGEX, "https://raw.githubusercontent.com")
+        tree_match = GITHUB_TREE_REGEX.match?(url)
+        blob_match = GITHUB_BLOB_REGEX.match?(url)
+
+        if tree_match
+          new_url.sub("/tree/", "/")
+        elsif blob_match
+          new_url.sub("/blob/", "/")
+        else
+          "#{new_url}/#{Bridgetown::Utils.default_github_branch_name(url)}"
+        end
+      end
+
+      def transform_gitlab_url(url)
+        new_url = url.dup
+        tree_match = GITLAB_TREE_REGEX.match?(url)
+        blob_match = GITLAB_BLOB_REGEX.match?(url)
+
+        if tree_match
+          new_url.sub("/tree/", "/raw/")
+        elsif blob_match
+          new_url.sub("/blob/", "/raw/")
+        else
+          "#{new_url}/-/raw/#{Bridgetown::Utils.default_gitlab_branch_name(url)}"
+        end
+      end
+
+      def transform_codeberg_url(url)
+        new_url = url.dup
+        tree_match = CODEBERG_TREE_REGEX.match?(url)
+
+        if tree_match
+          new_url.sub("/src/", "/raw/")
+        else
+          "#{new_url}/raw/branch/#{Bridgetown::Utils.default_codeberg_branch_name(url)}"
+        end
+      end
     end
+
+    Actions = Automations # alias
   end
 end

data/lib/bridgetown-core/commands/concerns/build_options.rb

@@ -3,66 +3,30 @@
 module Bridgetown
   module Commands
     module BuildOptions
-      def self.extended(klass)
-        klass.class_option :trace,
-                           type: :boolean,
-                           aliases: "-t",
-                           desc: "Show the full backtrace when an error occurs during watch mode"
-
-        klass.class_option :config,
-                           type: :array,
-                           banner: "FILE1 FILE2",
-                           desc: "Custom configuration file(s)"
-        klass.class_option :source,
-                           aliases: "-s",
-                           desc: "Source directory (defaults to src)"
-        klass.class_option :destination,
-                           aliases: "-d",
-                           desc: "Destination directory (defaults to output)"
-        klass.class_option :root_dir,
-                           aliases: "-r",
-                           desc: "The top-level root folder " \
-                                 "where config files are located"
-        klass.class_option :plugins_dir,
-                           aliases: "-p",
-                           type: :array,
-                           banner: "DIR1 DIR2",
-                           desc: "Plugins directory (defaults to plugins)"
-        klass.class_option :layouts_dir,
-                           desc: "Layouts directory (defaults to src/_layouts)"
-        klass.class_option :future,
-                           type: :boolean,
-                           desc: "Publishes posts with a future date"
-        klass.class_option :url,
-                           aliases: "-u",
-                           desc: "Override the configured url for the website"
-        klass.class_option :base_path,
-                           aliases: "-b",
-                           desc: "Serve the website from the given base path"
-        klass.class_option :force_polling,
-                           type: :boolean,
-                           desc: "Force watch to use polling"
-        klass.class_option :unpublished,
-                           type: :boolean,
-                           aliases: "-U",
-                           desc: "Render posts that were marked as unpublished"
-        klass.class_option :disable_disk_cache,
-                           type: :boolean,
-                           desc: "Disable caching to disk"
-        klass.class_option :profile,
-                           type: :boolean,
-                           desc: "Generate a Liquid rendering profile"
-        klass.class_option :quiet,
-                           aliases: "-q",
-                           type: :boolean,
-                           desc: "Silence output."
-        klass.class_option :verbose,
-                           aliases: "-V",
-                           type: :boolean,
-                           desc: "Print verbose output."
-        klass.class_option :strict_front_matter,
-                           type: :boolean,
-                           desc: "Fail if errors are present in front matter"
+      def self.include_options(klass) # rubocop:disable Metrics/MethodLength
+        klass.option "-t/--trace", "Show the full backtrace when an error occurs during watch mode"
+        klass.option "--config <FILE1,FILE2>", "Custom configuration file(s)" do |value|
+          value.split(%r{\s*,\s*})
+        end
+        klass.option "-s/--source <SOURCE>", "Source directory (defaults to src)"
+        klass.option "-d/--destination <DESTINATION>", "Destination directory (defaults to output)"
+        klass.option "-r/--root-dir <DIR>", "The top-level root folder " \
+                                            "where config files are located"
+        klass.option "-p/--plugins-dir <DIR1,DIR2>",
+                     "Plugins directory (defaults to plugins)" do |value|
+          value.split(%r{\s*,\s*})
+        end
+        klass.option "--layouts-dir <DIR>", "Layouts directory (defaults to src/_layouts)"
+        klass.option "--future", "Publishes posts with a future date"
+        klass.option "-u/--url <URL>", "Override the configured url for the website"
+        klass.option "-b/--base-path", "Serve the website from the given base path"
+        klass.option "--force-polling", "Force watch to use polling"
+        klass.option "-U/--unpublished", "Render posts that were marked as unpublished"
+        klass.option "--disable-disk-cache", "Disable caching to disk"
+        klass.option "--profile", "Generate a Liquid rendering profile"
+        klass.option "-q/--quiet", "Silence output"
+        klass.option "-V/--verbose", "Print verbose output"
+        klass.option "--strict-front-matter", "Fail if errors are present in front matter"
       end
     end
   end

data/lib/bridgetown-core/commands/concerns/configuration_overridable.rb

@@ -3,11 +3,9 @@
 module Bridgetown
   module Commands
     module ConfigurationOverridable
-      def self.included(klass)
+      def self.include_options(klass)
         desc = "The environment used for this command (aka development, test, production, etc.)"
-        klass.class_option :environment,
-                           aliases: "-e",
-                           desc:
+        klass.option "-e/--environment <ENV>", desc
       end
 
       # Create a full Bridgetown configuration with the options passed in as overrides

data/lib/bridgetown-core/commands/configure.rb

@@ -2,45 +2,42 @@
 
 module Bridgetown
   module Commands
-    class Configure < Thor::Group
-      include Thor::Actions
-      include Actions
-      extend Summarizable
+    class Configure < Bridgetown::Command
+      include Automations
 
-      Registrations.register do
-        register(Configure, "configure", "configure CONFIGURATION", Configure.summary)
-      end
+      self.description = "Set up bundled Bridgetown configurations"
 
-      def self.banner
-        "bridgetown configure CONFIGURATION(S)"
-      end
-      summary "Set up bundled Bridgetown configurations"
+      many :configurations, "One or more configuration names, separated by spaces"
 
-      def self.exit_on_failure?
-        true
+      def self.source_root
+        File.expand_path("../configurations", __dir__)
       end
 
-      def perform_configurations
+      def call(new_site_dir: nil)
+        self.source_paths = [self.class.source_root]
+        self.destination_root = new_site_dir || Dir.pwd
+
+        unless configurations
+          print_usage
+          list_configurations
+          return
+        end
+
         @logger = Bridgetown.logger
-        list_configurations if args.empty?
 
-        args.each do |configuration|
+        configurations.each do |configuration|
           configure configuration
-        rescue Thor::Error
+        rescue Freyia::Error
           @logger.error "Error:".red, "🚨 Configuration doesn't exist: #{configuration}"
         end
       end
 
-      def self.source_root
-        File.expand_path("../configurations", __dir__)
-      end
-
       protected
 
       def configure(configuration)
         configuration_file = find_in_source_paths("#{configuration}.rb")
 
-        inside(New.created_site_dir || Dir.pwd) do
+        inside(destination_root) do
           @templates_dir = File.expand_path("../configurations/#{configuration}", __dir__)
           apply configuration_file, verbose: false
         end
@@ -48,7 +45,8 @@ module Bridgetown
 
       def list_configurations
         say "Please specify a valid packaged configuration from the below list:\n\n"
-        configurations.each do |configuration|
+
+        configuration_files.each do |configuration|
           configuration = set_color configuration, :blue, :bold
           say configuration
         end
@@ -58,7 +56,7 @@ module Bridgetown
         say "For more info, check out the docs at: #{docs_url}"
       end
 
-      def configurations
+      def configuration_files
         inside self.class.source_root do
           return Dir.glob("*.rb").map { |file| file.sub(".rb", "") }.sort
         end
@@ -70,5 +68,7 @@ module Bridgetown
         end
       end
     end
+
+    register_command :configure, Configure
   end
 end

data/lib/bridgetown-core/commands/console.rb

@@ -25,39 +25,23 @@ module Bridgetown
   end
 
   module Commands
-    class Console < Thor::Group
-      extend Summarizable
+    class Console < Bridgetown::Command
       include ConfigurationOverridable
 
-      Registrations.register do
-        register(Console, "console", "console", Console.summary)
-      end
+      self.description = "Invoke an IRB console with the site loaded"
 
-      def self.banner
-        "bridgetown console [options]"
+      options do
+        ConfigurationOverridable.include_options(self)
+        option "--blank", "Skip reading content and running generators before opening console"
+        option "--bypass-ap", "Don't load AmazingPrint when IRB opens"
+        option "--config <FILE1,FILE2>", "Custom configuration file(s)" do |value|
+          value.split(%r{\s*,\s*})
+        end
+        option "-s/--server-config", "Load server configurations"
+        option "-V/--verbose", "Print verbose output"
       end
-      summary "Invoke an IRB console with the site loaded"
-
-      class_option :config,
-                   type: :array,
-                   banner: "FILE1 FILE2",
-                   desc: "Custom configuration file(s)"
-      class_option :"bypass-ap",
-                   type: :boolean,
-                   desc: "Don't load AmazingPrint when IRB opens"
-      class_option :blank,
-                   type: :boolean,
-                   desc: "Skip reading content and running generators before opening console"
-      class_option :"server-config",
-                   aliases: "-s",
-                   type: :boolean,
-                   desc: "Load server configurations"
-      class_option :verbose,
-                   aliases: "-V",
-                   type: :boolean,
-                   desc: "Print verbose output."
-
-      def console # rubocop:disable Metrics
+
+      def call # rubocop:disable Metrics
         require "irb"
         new_history_behavior = false
         begin
@@ -66,7 +50,7 @@ module Bridgetown
           # Code path for Ruby 3.3+
           new_history_behavior = true
         end
-        require "amazing_print" unless options[:"bypass-ap"]
+        require "amazing_print" unless options[:bypass_ap]
 
         Bridgetown.logger.adjust_verbosity(**options)
 
@@ -76,9 +60,19 @@ module Bridgetown
         Bridgetown.logger.info "Environment:", Bridgetown.environment.cyan
 
         config_options = configuration_with_overrides(options)
-        if options[:"server-config"]
+
+        if options[:server_config]
           require "bridgetown-core/rack/boot"
           Bridgetown::Rack.boot
+          begin
+            require "rack/test"
+            IRB::ExtendCommandBundle.include ::Rack::Test::Methods
+            ConsoleMethods.module_eval do
+              def app = Roda.subclasses[0].app
+            end
+            @rack_test_installed = true
+          rescue LoadError # rubocop:disable Lint/SuppressedException
+          end
         else
           config_options.run_initializers! context: :console
         end
@@ -92,13 +86,21 @@ module Bridgetown
         workspace.main.define_singleton_method(:site) { Bridgetown::Current.site }
         workspace.main.define_singleton_method(:collections) { site.collections }
         workspace.main.define_singleton_method(:helpers) do
-          Bridgetown::RubyTemplateView::Helpers.new
+          Bridgetown::TemplateView::Helpers.new
         end
         irb = IRB::Irb.new(workspace)
         IRB.conf[:IRB_RC]&.call(irb.context)
         IRB.conf[:MAIN_CONTEXT] = irb.context
         irb.context.io.load_history if new_history_behavior
-        Bridgetown.logger.info "Console:", "Your site is now available as #{"site".cyan}"
+        Bridgetown.logger.info "Console:", "Your site is now available as #{"site".cyan}."
+        if options[:server_config]
+          Bridgetown.logger.info "",
+                                 "Your Roda app is available as #{Roda.subclasses[0].to_s.cyan}."
+          if @rack_test_installed
+            Bridgetown.logger.info "", "You can use #{"Rack::Test".magenta} methods like #{"get".cyan}, #{"post".cyan}, and #{"last_response".cyan} to inspect" # rubocop:disable Layout/LineLength
+            Bridgetown.logger.info "", "  static & dynamic routes in your application."
+          end
+        end
         Bridgetown.logger.info "",
                                "You can also access #{"collections".cyan} or perform a " \
                                "#{"reload!".cyan}"
@@ -109,7 +111,7 @@ module Bridgetown
 
         begin
           catch(:IRB_EXIT) do
-            unless options[:"bypass-ap"]
+            unless options[:bypass_ap]
               AmazingPrint.defaults = {
                 indent: 2,
               }
@@ -123,5 +125,7 @@ module Bridgetown
         end
       end
     end
+
+    register_command :console, Console
   end
 end

data/lib/bridgetown-core/commands/esbuild.rb

@@ -2,30 +2,26 @@
 
 module Bridgetown
   module Commands
-    class Esbuild < Thor::Group
-      include Thor::Actions, Bridgetown::Commands::Actions
-      extend Summarizable
+    class Esbuild < Bridgetown::Command
+      include Automations
 
-      Registrations.register do
-        register(Esbuild, "esbuild", "esbuild ACTION", Esbuild.summary)
-      end
+      self.description = "Perform actions on the Bridgetown esbuild configuration"
 
-      def self.banner
-        "bridgetown esbuild ACTION"
-      end
-      summary "Perform actions on the Bridgetown esbuild configuration"
+      one :command, "setup, update, migrate-from-webpack"
 
       def self.exit_on_failure?
         true
       end
 
-      def esbuild
+      def call(new_site_dir: nil)
         @logger = Bridgetown.logger
-        return show_actions if args.empty?
+        return show_actions unless command
 
-        action = args.first
-        if supported_actions.include?(action.to_sym)
-          perform action
+        self.source_paths = [File.expand_path("../commands/esbuild", __dir__)]
+        self.destination_root = new_site_dir || config.root_dir
+
+        if supported_actions.include?(command.to_sym)
+          perform command
         else
           @logger.error "Error:".red, "🚨 Please enter a valid action."
           say "\n"
@@ -33,14 +29,6 @@ module Bridgetown
         end
       end
 
-      def self.source_root
-        File.expand_path("./esbuild", __dir__)
-      end
-
-      def self.destination_root
-        config.root_dir
-      end
-
       protected
 
       def config
@@ -56,7 +44,7 @@ module Bridgetown
 
       def perform(action)
         automation = find_in_source_paths("#{action}.rb")
-        inside(New.created_site_dir || Dir.pwd) do
+        inside(destination_root) do
           apply automation, verbose: false
         end
       end
@@ -79,5 +67,7 @@ module Bridgetown
         }
       end
     end
+
+    register_command :esbuild, Esbuild
   end
 end

data/lib/bridgetown-core/commands/help.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Commands
+    class Help < Bridgetown::Command
+      self.description = "Show detailed command usage information and exit"
+
+      one :command, "The name of a Bridgetown command", required: true
+
+      def call
+        found_command = parent.class.table[:command].commands[command]
+
+        found_command&.new(name: command)&.print_usage
+
+        return if found_command
+
+        puts "Unknown command: #{command}\n\n"
+        parent.print_usage
+      end
+    end
+
+    register_command :help, Help
+  end
+end