rbytes 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a2018b6cc0392420457e2edd1a8ec027f55978148bbb4ea5fba8e517116dc166
-  data.tar.gz: de96f8614e325160cda52825af368626ba6f70769dc1323efab289a5023c47d0
+  metadata.gz: a2b785fc9d54a6ca927a015009e6dc828afd264c5bd9f2055ce903aa4ebd1c07
+  data.tar.gz: c6de88c97011399b70b77ffdbf138ef46edd26a9889451e74d0a954da553eee5
 SHA512:
-  metadata.gz: 0b1021dc75c1ae9c56732c385101d53e65f2d8500f72b37e001e685db01a4b713ec6cd9052c0d0959a7acde61902c52c487f314c580be600aec2153f60957d4b
-  data.tar.gz: 84e337dcbb359ac314731982e0ae8ebcb0dd1e879df4eba8fc05699a47b7bb0fef83d3485b320d9c88aa5370d0d1862bfde59bdaa9b4e3e3f77f6565aa7b6f18
+  metadata.gz: a7ef023c07d2b51593664bfa42de8de319ecfaad698d586905fc4cb93751e0fa40db2c7c1878893b8c3bbff2208604c5f536ba0a33f61e46e4dee2418798ffdc
+  data.tar.gz: d90ee6b3cfc3e1e1548d4c34862e355be5e3bfb10b8909a669ff1cc3cc4d05a8c7d9adac9940ae09ef24336c1e10ae05a0f3b203ce7eadd3f58b4f8e540853a3

data/CHANGELOG.md

@@ -2,4 +2,8 @@
 
 ## master
 
+## 0.1.0 (2023-03-17) 🍀
+
+- Initial release.
+
 [@palkan]: https://github.com/palkan

data/README.md

@@ -6,24 +6,184 @@ Ruby Bytes is a tool to build application templates for Ruby and Rails applicati
 
 - Build complex templates consisting of multiple independent components.
 - Test templates with ease.
+- Install application templates without Rails.
+- Publish templates to [RailsBytes][].
 
-We also provide a GitHub action to deploy _compiled_ templates to [RailsBytes][].
+We also provide a [GitHub action](#github-action) to compile and deploy templates continuously.
 
-Templates built with Ruby Bytes can be used with the `rails app:template` command or with a custom [Thor command](#thor-integration) (if you want to use a template in a Rails-less environment)
+## Examples
+
+- [ruby-on-whales][]
+- [view_component-contrib][]
+
+See also examples in the [templates](https://github.com/palkan/rbytes/tree/master/templates) folder.
 
 ## Installation
 
-In your Gemfile:
+To install templates, install the `rbytes` executable via the gem:
+
+```sh
+gem install rbytes
+```
+
+For templates development, add `rbytes` to your Gemfile or gemspec:
 
 ```ruby
 # Gemfile
 gem "rbytes"
 ```
 
-## Building templates
+## Installing templates
+
+You can use `rbytes install <url>` similarly to `rails app:template` but without needing to install Rails. It's useful if you want to use a template in a Rails-less environment.
+
+Usage example:
+
+```sh
+$ rbytes install https://railsbytes.com/script/x7msKX
+
+Run template from: https://railsbytes.com/script/x7msKX
+  apply  https://railsbytes.com/script/x7msKX
+hello world from https://railsbytes.com 👋
+```
+
+**IMPORTANT**: Not all templates from RailsBytes may be supported as of yet. Please, let us know if you find incompatibilities with `rails app:template`, so we can fix them.
+
+You can also install Ruby Bytes as a plugin for Thor (see [Thor integration](#thor-integration)).
+
+## Writing templates
+
+Ruby Bytes adds partial support to Thor/Rails templates. For that, you can use `#include` and `#render` methods:
+
+```erb
+say "Welcome to a custom Rails template!"
+
+<%= include "setup_gems" %>
+
+file "config/initializers/my-gem.rb", <%= code("initializer.rb") %>
+```
+
+The `#include` helper simply injects the contents of the partial into the resulting file.
+
+The `#code` method allows you to inject dynamic contents depending on the local variables defined. For example, given the following template and a partial:
+
+```erb
+# _anycable.yml.tt
+development:
+  broadcast_adapter: <%= cable_adapter %>
+
+# template.rb
+cable_adapter = ask? "Which AnyCable pub/sub adapter do you want to use?"
+
+file "config/anycable.yml", <%= code("anycable.yml") %>
+```
+
+The compiled template will like like this:
+
+```erb
+cable_adapter = ask? "Which AnyCable pub/sub adapter do you want to use?"
+
+file "config/anycable.yml", ERB.new(
+  *[
+  <<~'CODE'
+    development:
+      broadcast_adapter: <%= cable_adapter %>
+  CODE
+  ], trim_mode: "<>").result(binding)
+```
+
+**NOTE:** By default, we assume that partials are stored next to the template's entrypoint. Partials may have "_" prefix and ".rb"/".tt" suffixes.
+
+### Compiling templates
+
+You can compile a template by using the `rbytes` executable:
+
+```sh
+$ rbytes compile path/to/template
+
+<compiled template>
+```
+
+You can also specify a custom partials directory:
+
+```sh
+rbytes compile path/to/template --root=path/to/partials
+```
 
 ### Testing
 
+We provide a Minitest integration to test your templates.
+
+Here is an example usage:
+
+```ruby
+require "ruby_bytes/test_case"
+
+class TemplateTest < RubyBytes::TestCasee
+  # Specify root path for your template (for partials lookup)
+  root File.join(__dir__, "../template")
+
+  # You can test partials in isolation by declaring a custom template
+  template <<~RUBY
+    say "Hello from some partial"
+    <%= include "some_partial" %>
+  RUBY
+
+  def test_some_partial
+    run_generator do |output|
+      assert_file "application.rb"
+
+      assert_file_contains(
+        "application.rb",
+        <<~CODE
+          module Rails
+            class << self
+              def application
+        CODE
+      )
+
+      refute_file_contains(
+        "application.rb",
+        "Nothing"
+      )
+
+      assert_line_printed output, "Hello from some partial"
+    end
+  end
+end
+```
+
+If you use prompt in your templates, you can prepopulate standard input:
+
+```ruby
+class TemplateTest < RubyBytes::TestCasee
+  # Specify root path for your template (for partials lookup)
+  root File.join(__dir__, "../template")
+
+  # You can test partials in isolation by declaring a custom template
+  template <<~RUBY
+    say "Hello from some partial"
+    if yes?("Do you write tests?")
+      say "Gut"
+    else
+      say "Why not?"
+    end
+  RUBY
+
+  def test_prompt_yes
+    run_generator(input: ["y"]) do |output|
+      assert_line_printed output, "Gut"
+    end
+  end
+
+  def test_prompt_no
+    run_generator(input: ["n"]) do |output|
+      assert_line_printed output, "Why not?"
+    end
+  end
+end
+```
+
 ## Thor integration
 
 We provide a custom Thor command, which can be used to apply templates (similar to `rails app:template`).
@@ -46,6 +206,43 @@ Run template from: https://railsbytes.com/script/x7msKX
 hello world from https://railsbytes.com 👋
 ```
 
+## GitHub action
+
+You can use our GitHub action to deploy your templates to RailsBytes.
+
+Here is an example:
+
+```yml
+name: Publish
+
+on:
+  push:
+    tags:
+      - v*
+  workflow_dispatch:
+
+jobs:
+  publish:
+    uses: palkan/rbytes/.github/workflows/railsbytes.yml@master
+    with:
+      template: templates/my-template.rb
+    secrets:
+      RAILS_BYTES_ACCOUNT_ID: "${{ secrets.RAILS_BYTES_ACCOUNT_ID }}"
+      RAILS_BYTES_TOKEN: "${{ secrets.RAILS_BYTES_TOKEN }}"
+      RAILS_BYTES_TEMPLATE_ID: "${{ secrets.RAILS_TEMPLATE_ID }}"
+```
+
+## Publishing manually
+
+You can use the `rbytes publish` command to compile and publish a template to RailsBytes:
+
+```sh
+RAILS_BYTES_ACCOUNT_ID=aaa \
+RAILS_BYTES_TOKEN=bbb \
+RAILS_BYTES_TEMPLATE_ID=ccc \
+rbytes publish path/to/template
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/palkan/rbytes](https://github.com/palkan/rbytes).
@@ -59,3 +256,5 @@ This gem is generated via [new-gem-generator](https://github.com/palkan/new-gem-
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
 
 [RailsBytes]: https://railsbytes.com
+[ruby-on-whales]: https://github.com/evilmartians/ruby-on-whales
+[view_component-contrib]: https://github.com/palkan/view_component-contrib

data/bin/rbytes

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require "ruby_bytes/cli"
+
+begin
+  cli = RubyBytes::CLI.new
+  cli.run(*ARGV)
+rescue => e
+  raise e if $DEBUG
+  STDERR.puts e.message
+  STDERR.puts e.backtrace.join("\n") if $DEBUG
+  exit 1
+end

data/lib/rbytes.rb

@@ -1,3 +1,5 @@
 # frozen_string_literal: true
 
-require "rbytes/version"
+require "ruby_bytes/version"
+require "ruby_bytes/compiler"
+require "ruby_bytes/publisher"

data/lib/ruby_bytes/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "rbytes"
+require "optparse"
+
+module RubyBytes
+  class CLI
+    COMMANDS = %w[
+      compile
+      publish
+      install
+    ].freeze
+
+    def run(command, *args)
+      raise ArgumentError, "Unknown command: #{command}\nAvailable commands are: #{COMMANDS.join(", ")}\nRuby Bytes: v#{RubyBytes::VERSION}" unless COMMANDS.include?(command)
+
+      public_send(command, *args)
+    end
+
+    def compile(*args)
+      root = nil # rubocop:disable Lint/UselessAssignment
+
+      path, args = *args
+
+      OptionParser.new do |o|
+        o.on "-v", "--version", "Print version and exit" do |_arg|
+          $stdout.puts "Ruby Bytes: v#{RubyBytes::VERSION}"
+          exit(0)
+        end
+
+        o.on "--root [DIR]", "Location of partial template files" do
+          raise ArgumentError, "Directory not found: #{_1}" unless File.directory?(_1)
+          root = _1
+        end
+
+        o.on_tail "-h", "--help", "Show help" do
+          $stdout.puts <<~USAGE
+            rbytes compile PATH [options]
+
+            Options:
+                --root DIR Location of partial template files
+          USAGE
+
+          exit(0)
+        end
+      end.parse!(args || [])
+
+      raise ArgumentError, "File not found: #{path}" unless File.file?(path)
+
+      $stdout.puts Compiler.new(path, root: root).render
+    end
+
+    def publish(*args)
+      root = nil # rubocop:disable Lint/UselessAssignment
+
+      path, args = *args
+
+      OptionParser.new do |o|
+        o.on "-v", "--version", "Print version and exit" do |_arg|
+          $stdout.puts "Ruby Bytes: v#{RubyBytes::VERSION}"
+          exit(0)
+        end
+
+        o.on "--root [DIR]", "Location of partial template files" do
+          raise ArgumentError, "Directory not found: #{_1}" unless File.directory?(_1)
+          root = _1
+        end
+
+        o.on_tail "-h", "--help", "Show help" do
+          $stdout.puts <<~USAGE
+            rbytes publish PATH [options]
+
+            Options:
+                --root DIR Location of partial template files
+          USAGE
+
+          exit(0)
+        end
+      end.parse!(args || [])
+
+      raise ArgumentError, "File not found: #{path}" unless File.file?(path)
+
+      contents = Compiler.new(path, root: root).render
+
+      Publisher.new.call(contents)
+
+      $stdout.puts "Published successfully ✅"
+    end
+
+    def install(*args)
+      url, args = *args
+
+      OptionParser.new do |o|
+        o.on "-v", "--version", "Print version and exit" do |_arg|
+          $stdout.puts "Ruby Bytes: v#{RubyBytes::VERSION}"
+          exit(0)
+        end
+
+        o.on_tail "-h", "--help", "Show help" do
+          $stdout.puts <<~USAGE
+            rbytes install URL
+          USAGE
+
+          exit(0)
+        end
+      end.parse!(args || [])
+
+      raise ArgumentError, "Template URL or location must be provided" unless url
+
+      require "thor"
+      require "ruby_bytes/thor"
+
+      Rbytes.new.template(url)
+    end
+  end
+end

data/lib/ruby_bytes/compiler.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module RubyBytes
+  class Compiler
+    attr_reader :path, :template, :root
+
+    def initialize(path, root: nil)
+      @path = path
+      raise ArgumentError, "There is no file at the path: #{path}" unless File.file?(path)
+
+      @template = File.read(path)
+      @root = root || File.dirname(File.expand_path(path))
+    end
+
+    def render(contents = template)
+      ERB.new(contents, trim_mode: "<>").result(binding)
+    end
+
+    def code(path)
+      contents = File.read(resolve_path(path))
+      %(ERB.new(
+    *[
+  <<~'CODE'
+  #{contents}
+  CODE
+  ], trim_mode: "<>").result(binding))
+    end
+
+    def include(path, indent: 0)
+      indented(File.read(resolve_path(path)), indent)
+    end
+
+    private
+
+    PATH_CANDIDATES = [
+      "%{path}",
+      "_%{path}",
+      "%{path}.rb",
+      "_%{path}.rb",
+      "%{path}.tt",
+      "_%{path}.tt"
+    ].freeze
+
+    def resolve_path(path)
+      PATH_CANDIDATES.each do |pattern|
+        resolved = File.join(root, pattern % {path: path})
+        return resolved if File.file?(resolved)
+      end
+
+      raise "File not found: #{path}"
+    end
+
+    def indented(content, multiplier = 2) # :doc:
+      spaces = " " * multiplier
+      content.each_line.map { |line| (!line.match?(/\S/)) ? line : "#{spaces}#{line}" }.join
+    end
+  end
+end

data/lib/ruby_bytes/publisher.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module RubyBytes
+  class Publisher
+    attr_reader :account_id, :token, :template_id
+
+    def initialize(
+      account_id: ENV.fetch("RAILS_BYTES_ACCOUNT_ID"),
+      token: ENV.fetch("RAILS_BYTES_TOKEN"),
+      template_id: ENV.fetch("RAILS_BYTES_TEMPLATE_ID")
+    )
+      @account_id = account_id
+      @token = token
+      @template_id = template_id
+    end
+
+    def call(template)
+      require "net/http"
+      require "json"
+
+      path = "/api/v1/accounts/#{account_id}/templates/#{template_id}.json"
+      data = JSON.dump(script: template)
+
+      Net::HTTP.start("railsbytes.com", 443, use_ssl: true) do |http|
+        http.patch(
+          path,
+          data,
+          {
+            "Content-Type" => "application/json",
+            "Authorization" => "Bearer GGpxArFDSa2x3MT4BQNcyxG6"
+          }
+        )
+      end.then do |response|
+        raise "Failed to publish template: #{response.code} — #{response.message}" unless response.code == "200"
+      end
+    end
+  end
+end

data/lib/ruby_bytes/test_case.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "fileutils"
+require "stringio"
+require "thor"
+
+require "ruby_bytes/thor"
+
+module RubyBytes
+  class TestCase < Minitest::Test
+    TMP_DIR = File.join(Dir.pwd, "tmp", "rbytes_test")
+
+    FileUtils.rm_rf(TMP_DIR) if File.directory?(TMP_DIR)
+    FileUtils.mkdir_p(TMP_DIR)
+
+    Rbytes::Base.source_paths << TMP_DIR
+
+    # Patch Thor::LineEditor to use Basic in tests
+    $rbytes_testing = false
+
+    Thor::LineEditor.singleton_class.prepend(Module.new do
+      def best_available
+        return super unless $rbytes_testing
+
+        Thor::LineEditor::Basic
+      end
+    end)
+
+    class << self
+      attr_reader :template_contents
+
+      def destination_root(val = nil)
+        if val
+          @destination_root = val
+        end
+
+        return @destination_root if instance_variable_defined?(:@destination_root)
+
+        @destination_root =
+          if superclass.respond_to?(:destination_root)
+            superclass.destination_root
+          else
+            TMP_DIR
+          end
+      end
+
+      def root(val = nil)
+        if val
+          @root = val
+        end
+
+        return @root if instance_variable_defined?(:@root)
+
+        @root =
+          if superclass.respond_to?(:root)
+            superclass.root
+          end
+      end
+
+      # Set the path to dummy app.
+      # Dummy app is copied to the temporary directory for every run
+      # and set as a destination root.
+      def dummy_app(val = nil)
+        if val
+          @dummy_app = val
+        end
+
+        return @dummy_app if instance_variable_defined?(:@dummy_app)
+
+        @dummy_app =
+          if superclass.respond_to?(:dummy_app)
+            superclass.dummy_app
+          end
+      end
+
+      def template(contents)
+        @template_contents = contents
+      end
+    end
+
+    attr_accessor :destination
+
+    def prepare_dummy
+      # Then, copy the dummy app if any
+      dummy = self.class.dummy_app
+      return unless dummy
+
+      return if @dummy_prepared
+
+      raise ArgumentError, "Dummy app must be a directory" unless File.directory?(dummy)
+
+      tmp_dummy_path = File.join(TMP_DIR, "dummy")
+      FileUtils.rm_rf(tmp_dummy_path) if File.directory?(tmp_dummy_path)
+      FileUtils.cp_r(dummy, tmp_dummy_path)
+      self.destination = tmp_dummy_path
+
+      if block_given?
+        Dir.chdir(tmp_dummy_path) { yield }
+      end
+
+      @dummy_prepared = true
+    end
+
+    def run_generator(input: [])
+      # First, compile the template (if not yet)
+      path = File.join(TMP_DIR, "current_template.rb")
+
+      if File.file?(path)
+        File.delete(path)
+      end
+
+      File.write(path, "")
+
+      rendered = Compiler.new(path, root: self.class.root).render(self.class.template_contents)
+      File.write(path, rendered)
+
+      self.destination = self.class.destination_root
+
+      prepare_dummy
+
+      original_stdout = $stdout
+      original_stdin = $stdin
+
+      if input.size > 0
+        $rbytes_testing = true
+
+        io = StringIO.new
+        input.each { io.puts(_1) }
+        io.rewind
+        $stdin = io
+        $stdin.sync = true
+      end
+
+      $stdout = StringIO.new
+      $stdout.sync = true
+
+      begin
+        Dir.chdir(destination) do
+          Rbytes::Base.new(
+            [destination], {}, {destination_root: destination}
+          ).apply("current_template.rb")
+        end
+        yield $stdout.string if block_given?
+      ensure
+        $stdout = original_stdout
+        $stdin = original_stdin
+        $rbytes_testing = false
+        @dummy_prepared = false
+      end
+    end
+
+    def assert_line_printed(io, line)
+      lines = io.lines
+
+      assert lines.any? { _1.include?(line) }, "Expected to print line: #{line}. Got: #{io}"
+    end
+
+    def assert_file_contains(path, body)
+      fullpath = File.join(destination, path)
+      assert File.file?(fullpath), "File not found: #{path}"
+
+      actual = File.read(fullpath)
+      assert_includes actual, body
+    end
+
+    def assert_file(path)
+      fullpath = File.join(destination, path)
+      assert File.file?(fullpath), "File not found: #{path}"
+    end
+
+    def refute_file_contains(path, body)
+      fullpath = File.join(destination, path)
+      assert File.file?(fullpath), "File not found: #{path}"
+
+      actual = File.read(fullpath)
+      refute_includes actual, body
+    end
+  end
+end