freyia 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bf6cf315bb9c907a5e521b072379f571e10440205bd34dec31f44b91c7f5eca
+  data.tar.gz: 0f780348c2b60c049dba969b7a34f790739a7061003926a61a05c2624f0c77db
+SHA512:
+  metadata.gz: 8c0731ec3f312fb869009c1f4bddcae1d72a96f406bbf6f6f04a062fa372bd6b0a306c5c520fd5581dbb3b0954bd14c729a8180d3caccf8feba918d024f1427f
+  data.tar.gz: 4bf4c0a3321169d742108f5ccda4af3e86b6f5cf5462d56d26a459f520bb05e8adebd9ea0b6ed94587a86aa9b2a12013428da0c5110a43ad3e038e006769d2b4

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.5.0] - 2025-11-17
+
+- Initial creation of the Freyia gem, hard-fork of the shell/actions components of Thor

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2008 Yehuda Katz, Eric Hodel, et al., 2025 Jared White
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,62 @@
+# Freyia
+
+Define and execute automated tasks in Ruby like the party girl you are! Let your freak _Norse goddess_ flag fly. 🥳
+
+> [!NOTE]
+> Freyia is a hard-fork of extracted shell/actions components from the [Thor](https://github.com/rails/thor) project, now modernized and usable in any Ruby application with any command line tooling.
+
+## Installation
+
+```bash
+bundle add freyia
+```
+
+## Usage
+
+```ruby
+class TestAutomation < Freyia::Base
+  def call(external_file)
+    say_status :test, "This is a test!"
+    run "ls"
+    copy_file "data.txt"
+    apply external_file
+  end
+end
+
+TestAutomation.new(source: "dirs/source", dest: "dirs/dest").call("another/automation.rb")
+```
+
+You can also include a mixin into your own class, which will require you to set the source(s) and destination manually.
+
+```ruby
+class MyAutomationSuperclass
+  include Freyia::Setup
+
+  def initialize
+    self.source_paths = Array("my_src/folder").map { File.expand_path(_1, Dir.pwd) }
+    self.destination_root = File.expand_path("my_dest/folder", Dir.pwd)
+  end
+end
+
+class MyLatestAutomation < MyAutomationSuperclass
+  def call
+    # ...automation statements here
+  end
+end
+```
+
+Note that the use of `call` here is simply a convention…you can write automations in any method or architecture you prefer.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on Codeberg at https://codeberg.org/jaredwhite/freyia. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://codeberg.org/jaredwhite/freyia/src/branch/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[rubocop test]

data/lib/freyia/automations/create_file.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "empty_directory"
+
+module Freyia
+  module Automations
+    # Create a new file relative to the destination root with the given data,
+    # which is the return value of a block or a data string.
+    #
+    # ==== Parameters
+    # destination<String>:: the relative path to the destination root.
+    # data<String|NilClass>:: the data to append to the file.
+    # config<Hash>:: give :verbose => false to not log the status.
+    #
+    # ==== Examples
+    #
+    #   create_file "lib/fun_party.rb" do
+    #     hostname = ask("What is the virtual hostname I should use?")
+    #     "vhost.name = #{hostname}"
+    #   end
+    #
+    #   create_file "config/apache.conf", "your apache config"
+    #
+    def create_file(destination, *args, &block)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      data = args.first
+      action CreateFile.new(self, destination, block || data.to_s, config)
+    end
+    alias_method :add_file, :create_file
+
+    # CreateFile is a subset of Template, which instead of rendering a file with
+    # ERB, it gets the content from the user.
+    #
+    class CreateFile < EmptyDirectory #:nodoc:
+      attr_reader :data
+
+      def initialize(base, destination, data, config = {})
+        @data = data
+        super(base, destination, config)
+      end
+
+      # Checks if the content of the file at the destination is identical to the rendered result.
+      #
+      # ==== Returns
+      # Boolean:: true if it is identical, false otherwise.
+      #
+      def identical?
+        # binread uses ASCII-8BIT, so to avoid false negatives, the string must use the same
+        exists? && File.binread(destination) == String.new(render).force_encoding("ASCII-8BIT")
+      end
+
+      # Holds the content to be added to the file.
+      #
+      def render
+        @render ||= if data.is_a?(Proc)
+                      data.call
+                    else
+                      data
+                    end
+      end
+
+      def invoke!
+        invoke_with_conflict_check do
+          require "fileutils"
+          FileUtils.mkdir_p(File.dirname(destination))
+          File.open(destination, "wb", config[:perm]) { |f| f.write render }
+        end
+        given_destination
+      end
+
+      protected
+
+      # Now on conflict we check if the file is identical or not.
+      #
+      def on_conflict_behavior(&)
+        if identical?
+          say_status :identical, :blue
+        else
+          options = base.options.merge(config)
+          force_or_skip_or_conflict(options[:force], options[:skip], &)
+        end
+      end
+
+      # If force is true, run the action, otherwise check if it's not being
+      # skipped. If both are false, show the file_collision menu, if the menu
+      # returns true, force it, otherwise skip.
+      #
+      def force_or_skip_or_conflict(force, skip, &)
+        if force
+          say_status :force, :yellow
+          yield unless pretend?
+        elsif skip
+          say_status :skip, :yellow
+        else
+          say_status :conflict, :red
+          force_or_skip_or_conflict(force_on_collision?, true, &)
+        end
+      end
+
+      # Shows the file collision menu to the user and gets the result.
+      #
+      def force_on_collision?
+        base.shell.file_collision(destination) { render }
+      end
+    end
+  end
+end

data/lib/freyia/automations/create_link.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "create_file"
+
+module Freyia
+  module Automations
+    # Create a new file relative to the destination root from the given source.
+    #
+    # ==== Parameters
+    # destination<String>:: the relative path to the destination root.
+    # source<String|NilClass>:: the relative path to the source root.
+    # config<Hash>:: give :verbose => false to not log the status.
+    #   :: give :symbolic => false for hard link.
+    #
+    # ==== Examples
+    #
+    #   create_link "config/apache.conf", "/etc/apache.conf"
+    #
+    def create_link(destination, *args)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      source = args.first
+      action CreateLink.new(self, destination, source, config)
+    end
+    alias_method :add_link, :create_link
+
+    # CreateLink is a subset of CreateFile, which instead of taking a block of
+    # data, just takes a source string from the user.
+    #
+    class CreateLink < CreateFile #:nodoc:
+      attr_reader :data
+
+      # Checks if the content of the file at the destination is identical to the rendered result.
+      #
+      # ==== Returns
+      # Boolean:: true if it is identical, false otherwise.
+      #
+      def identical?
+        source = File.expand_path(render, File.dirname(destination))
+        exists? && File.identical?(source, destination)
+      end
+
+      def invoke!
+        invoke_with_conflict_check do
+          require "fileutils"
+          FileUtils.mkdir_p(File.dirname(destination))
+          # Create a symlink by default
+          config[:symbolic] = true if config[:symbolic].nil?
+          File.unlink(destination) if exists?
+          if config[:symbolic]
+            File.symlink(render, destination)
+          else
+            File.link(render, destination)
+          end
+        end
+        given_destination
+      end
+
+      def exists?
+        super || File.symlink?(destination)
+      end
+    end
+  end
+end

data/lib/freyia/automations/directory.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "empty_directory"
+
+module Freyia
+  module Automations
+    # Copies recursively the files from source directory to root directory.
+    # If any of the files finishes with .tt, it's considered to be a template
+    # and is placed in the destination without the extension .tt. If any
+    # empty directory is found, it's copied and all .empty_directory files are
+    # ignored. If any file name is wrapped within % signs, the text within
+    # the % signs will be executed as a method and replaced with the returned
+    # value. Let's suppose a doc directory with the following files:
+    #
+    #   doc/
+    #     components/.empty_directory
+    #     README
+    #     rdoc.rb.tt
+    #     %app_name%.rb
+    #
+    # When invoked as:
+    #
+    #   directory "doc"
+    #
+    # It will create a doc directory in the destination with the following
+    # files (assuming that the `app_name` method returns the value "blog"):
+    #
+    #   doc/
+    #     components/
+    #     README
+    #     rdoc.rb
+    #     blog.rb
+    #
+    # <b>Encoded path note:</b> Since Freyia internals use Object#respond_to? to check if it can
+    # expand %something%, this `something` should be a public method in the class calling
+    # #directory. If a method is private, Freyia stack raises PrivateMethodEncodedError.
+    #
+    # ==== Parameters
+    # source<String>:: the relative path to the source root.
+    # destination<String>:: the relative path to the destination root.
+    # config<Hash>:: give :verbose => false to not log the status.
+    #                If :recursive => false, does not look for paths recursively.
+    #                If :mode => :preserve, preserve the file mode from the source.
+    #                If :exclude_pattern => /regexp/, prevents copying files that match that regexp.
+    #
+    # ==== Examples
+    #
+    #   directory "doc"
+    #   directory "doc", "docs", :recursive => false
+    #
+    def directory(source, *args, &)
+      config = args.last.is_a?(Hash) ? args.pop : {}
+      destination = args.first || source
+      action Directory.new(self, source, destination || source, config, &)
+    end
+
+    class Directory < EmptyDirectory #:nodoc:
+      attr_reader :source
+
+      def initialize(base, source, destination = nil, config = {}, &block)
+        @source = File.expand_path(
+          Dir[Util.escape_globs(base.find_in_source_paths(source.to_s))].first
+        )
+        @block = block
+        super(base, destination, { recursive: true }.merge(config))
+      end
+
+      def invoke!
+        base.empty_directory given_destination, config
+        execute!
+      end
+
+      def revoke!
+        execute!
+      end
+
+      protected
+
+      def execute! # rubocop:todo Metrics
+        lookup = Util.escape_globs(source)
+        lookup = File.join(lookup, "**") if config[:recursive]
+        lookup = file_level_lookup(lookup)
+
+        files(lookup).sort.each do |file_source|
+          next if File.directory?(file_source)
+          next if config[:exclude_pattern] && file_source.match(config[:exclude_pattern])
+
+          file_destination = File.join(given_destination, file_source.gsub(source, "."))
+          file_destination.gsub!("/./", "/")
+
+          case file_source
+          when %r{\.empty_directory$}
+            dirname = File.dirname(file_destination).gsub(%r{/\.$}, "")
+            next if dirname == given_destination
+
+            base.empty_directory(dirname, config)
+          when %r{#{TEMPLATE_EXTNAME}$}o
+            base.template(file_source, file_destination[0..-4], config, &@block)
+          else
+            base.copy_file(file_source, file_destination, config, &@block)
+          end
+        end
+      end
+
+      def file_level_lookup(previous_lookup)
+        File.join(previous_lookup, "*")
+      end
+
+      def files(lookup)
+        Dir.glob(lookup, File::FNM_DOTMATCH)
+      end
+    end
+  end
+end

data/lib/freyia/automations/empty_directory.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Freyia
+  module Automations
+    # Creates an empty directory.
+    #
+    # ==== Parameters
+    # destination<String>:: the relative path to the destination root.
+    # config<Hash>:: give :verbose => false to not log the status.
+    #
+    # ==== Examples
+    #
+    #   empty_directory "doc"
+    #
+    def empty_directory(destination, config = {})
+      action EmptyDirectory.new(self, destination, config)
+    end
+
+    # Class which holds create directory logic. This is the base class for
+    # other automations like create_file and directory.
+    #
+    # This implementation is based in Templater automations, created by Jonas Nicklas
+    # and Michael S. Klishin under MIT LICENSE.
+    #
+    class EmptyDirectory #:nodoc:
+      attr_reader :base, :destination, :given_destination, :relative_destination, :config
+
+      # Initializes given the source and destination.
+      #
+      # ==== Parameters
+      # base<Freyia::Base>:: A Freyia::Base instance
+      # source<String>:: Relative path to the source of this file
+      # destination<String>:: Relative path to the destination of this file
+      # config<Hash>:: give :verbose => false to not log the status.
+      #
+      def initialize(base, destination, config = {})
+        @base = base
+        @config = { verbose: true }.merge(config)
+        self.destination = destination
+      end
+
+      # Checks if the destination file already exists.
+      #
+      # ==== Returns
+      # Boolean:: true if the file exists, false otherwise.
+      #
+      def exists?
+        ::File.exist?(destination)
+      end
+
+      def invoke!
+        invoke_with_conflict_check do
+          require "fileutils"
+          ::FileUtils.mkdir_p(destination)
+        end
+      end
+
+      def revoke!
+        say_status :remove, :red
+        require "fileutils"
+        ::FileUtils.rm_rf(destination) if !pretend? && exists?
+        given_destination
+      end
+
+      protected
+
+      # Shortcut for pretend.
+      #
+      def pretend?
+        base.options[:pretend]
+      end
+
+      # Sets the absolute destination value from a relative destination value.
+      # It also stores the given and relative destination. Let's suppose our
+      # script is being executed on "dest", it sets the destination root to
+      # "dest". The destination, given_destination and relative_destination
+      # are related in the following way:
+      #
+      #   inside "bar" do
+      #     empty_directory "baz"
+      #   end
+      #
+      #   destination          #=> dest/bar/baz
+      #   relative_destination #=> bar/baz
+      #   given_destination    #=> baz
+      #
+      def destination=(destination)
+        return unless destination
+
+        @given_destination = convert_encoded_instructions(destination.to_s)
+        @destination = ::File.expand_path(@given_destination, base.destination_root)
+        @relative_destination = base.relative_to_original_destination_root(@destination)
+      end
+
+      # Filenames in the encoded form are converted. If you have a file:
+      #
+      #   %file_name%.rb
+      #
+      # It calls #file_name from the base and replaces %-string with the
+      # return value (should be String) of #file_name:
+      #
+      #   user.rb
+      #
+      # The method referenced can be either public or private.
+      #
+      def convert_encoded_instructions(filename)
+        filename.gsub(%r{%(.*?)%}) do |initial_string|
+          method = ::Regexp.last_match(1).strip
+          base.respond_to?(method, true) ? base.send(method) : initial_string
+        end
+      end
+
+      # Receives a hash of options and just execute the block if some
+      # conditions are met.
+      #
+      def invoke_with_conflict_check(&)
+        if exists?
+          on_conflict_behavior(&)
+        else
+          yield unless pretend?
+          say_status :create, :green
+        end
+
+        destination
+      rescue Errno::EISDIR, Errno::EEXIST
+        on_file_clash_behavior
+      end
+
+      def on_file_clash_behavior
+        say_status :file_clash, :red
+      end
+
+      # What to do when the destination file already exists.
+      #
+      def on_conflict_behavior
+        say_status :exist, :blue
+      end
+
+      # Shortcut to say_status shell method.
+      #
+      def say_status(status, color)
+        base.shell.say_status status, relative_destination, color if config[:verbose]
+      end
+    end
+  end
+end