sandals 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8706dd760aa94d3533ea6c2fb18bf8d265272a3c49250e1539300e8f2d960740
-  data.tar.gz: 87590e396a533c73abc3eb6689c90481f301d84c885e344bb21148845f602baf
+  metadata.gz: 79d2b3d1395db396acd1aad4055141b75c955ca0ff0462e5fcf700db819af32e
+  data.tar.gz: 1cc17abdffbbc21540ada84f192cf9b1139c63c9422ef8152c2767ad6091473b
 SHA512:
-  metadata.gz: b5cf4873ca1ebc024b7f45c744b3d7747ace37a867b6a0c9dfb9e85861398e3bf2ff99d7a431c1e7c9d063f1df1b5a65684918fa581ab2bfcf94915e2201fe81
-  data.tar.gz: 1e17469e4cb0a3bdf878ffafc07d45e083e620a8410704c012c2cd524268e2b22d3786a6c7cf0db04e1b28707fea3198b121dbe5e0cc5b6bf7323d6d039a3705
+  metadata.gz: 6002d0c758974e5e797e153ebd50c0422b2a706b8329d6831cd44c7a13daabee0c9f9bd55aa49b3389e7798c00195ad92156f8f205bc74afb1fcab7395c0df90
+  data.tar.gz: 075fb63042fd98661f107e249ff3af9c3c82bf203d44f7a58c937a8bdf7ac71fc235d4ae22246972b26ecb8cde00a246f9968bb343a9ffb9306a4f509e52d32f

data/README.md

@@ -19,12 +19,84 @@ Sandals requires Ruby 3.1 or later.
 
 ```sh
 gem install sandals
-sandals run app.rb
+sandals new hello
+sandals run hello.rb
 ```
 
 The server listens on `127.0.0.1`. All required assets are included in the gem,
 so a local app does not need an internet connection.
 
+## Quickstart
+
+Create your first application:
+
+```sh
+sandals new hello
+```
+
+This creates two files:
+
+```text
+hello.rb
+hello_test.rb
+```
+
+`hello.rb` is a small application with a text field and a greeting. Run it:
+
+```sh
+sandals run hello.rb
+```
+
+Keep Sandals running and open `hello.rb` in your editor. Change:
+
+```ruby
+title "Hello"
+```
+
+to:
+
+```ruby
+title "Hello from Ruby"
+```
+
+Save the file. The browser reloads automatically and shows the change.
+
+If the file contains a syntax or load error, Sandals keeps the last valid
+version running and reports the error with its location. Fix the file and save
+it again; the application recovers automatically.
+
+The generated test interacts with the application through visible labels and
+text. Run it with:
+
+```sh
+ruby hello_test.rb
+```
+
+The test fills in `"Your name"` and verifies that the greeting appears. It uses
+Minitest, which is installed with Sandals.
+
+## Startup errors
+
+Sandals reports startup failures with the error type, application file, and
+line number instead of printing an internal framework backtrace:
+
+```text
+sandals: SyntaxError at app.rb:12
+app.rb:12: syntax error, unexpected end-of-input
+```
+
+Missing dependencies are reported in the same way:
+
+```text
+sandals: LoadError at app.rb:1
+cannot load such file -- sqlite3
+Add the missing dependency to the app and try again.
+```
+
+Sandals also evaluates the initial view before opening the server, so an
+exception during the first render points to the relevant line in the
+application.
+
 ## The experience
 
 An application should normally fit in a single file:

data/lib/sandals/action_error.rb

@@ -17,15 +17,7 @@ module Sandals
     end
 
     def location
-      locations = original_error.backtrace_locations || []
-      relevant_location = locations.find do |candidate|
-        !candidate.absolute_path.to_s.include?("/lib/sandals/")
-      end || locations.first
-      return "Location unavailable" unless relevant_location
-
-      path = relevant_location.absolute_path || relevant_location.path
-      path = path.delete_prefix("#{Dir.pwd}/")
-      "#{path}:#{relevant_location.lineno}"
+      ErrorDetails.for(original_error).fetch(:location)
     end
   end
 

data/lib/sandals/cli.rb

@@ -5,6 +5,16 @@ require_relative "../sandals"
 
 module Sandals
   class CLI
+    class InitialAppError < StandardError
+      attr_reader :original_error, :path
+
+      def initialize(original_error, path)
+        @original_error = original_error
+        @path = path
+        super(original_error.message)
+      end
+    end
+
     def self.start(arguments)
       new(arguments).run
     end
@@ -15,18 +25,58 @@ module Sandals
 
     def run
       command = @arguments.shift
-      return usage unless command == "run"
-
-      run_app
-    rescue Interrupt
-      0
+      case command
+      when "run" then run_app
+      when "new" then new_app
+      else usage
+      end
+    rescue InitialAppError => error
+      report_initial_app_error(error)
     rescue StandardError => error
       warn "sandals: #{error.message}"
       1
+    rescue Interrupt
+      0
     end
 
     private
 
+    def new_app
+      name = @arguments.shift
+      raise ArgumentError, "missing app name" unless name
+      raise ArgumentError, "unexpected arguments: #{@arguments.join(' ')}" unless @arguments.empty?
+
+      base_name = name.delete_suffix(".rb")
+      unless base_name.match?(/\A[a-zA-Z0-9][a-zA-Z0-9_-]*\z/)
+        raise ArgumentError, "app name must contain only letters, numbers, underscores, or hyphens"
+      end
+
+      app_path = "#{base_name}.rb"
+      test_path = "#{base_name}_test.rb"
+      existing_path = [app_path, test_path].find { |path| File.exist?(path) }
+      raise ArgumentError, "#{existing_path} already exists" if existing_path
+
+      title = base_name.split(/[_-]+/).map(&:capitalize).join(" ")
+      File.open(app_path, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+        file.write(app_template(title))
+      end
+      File.open(test_path, File::WRONLY | File::CREAT | File::EXCL, 0o644) do |file|
+        file.write(test_template(base_name))
+      end
+
+      puts "Created #{app_path}"
+      puts "Created #{test_path}"
+      puts
+      puts "Run the app:"
+      puts "  sandals run #{app_path}"
+      puts
+      puts "Run the test:"
+      puts "  ruby #{test_path}"
+      0
+    rescue Errno::EEXIST
+      raise ArgumentError, "could not create app because a generated file already exists"
+    end
+
     def run_app
       options = { open: true, port: 0 }
       parser = OptionParser.new do |opts|
@@ -36,17 +86,36 @@ module Sandals
       parser.parse!(@arguments)
 
       path = resolve_app(@arguments.shift || "app")
-      application = Sandals.load(path)
+      application = load_initial_application(path)
       server = Server.new(application, port: options[:port], reload_path: path)
 
       trap("INT") { server.stop }
-      puts "Sandals está corriendo #{path}"
+      puts "Sandals is running #{path}"
       puts server.url
       open_browser(server.url) if options[:open]
       server.start
       0
     end
 
+    def load_initial_application(path)
+      application = Sandals.load(path)
+      application.render(development_reload: true)
+      application
+    rescue SyntaxError, LoadError, StandardError => error
+      raise InitialAppError.new(error, File.expand_path(path))
+    end
+
+    def report_initial_app_error(error)
+      original = error.original_error
+      details = ErrorDetails.for(original, fallback_path: error.path)
+      warn "sandals: #{details.fetch(:class)} at #{details.fetch(:location)}"
+      warn details.fetch(:message)
+      if original.is_a?(LoadError)
+        warn "Add the missing dependency to the app and try again."
+      end
+      1
+    end
+
     def resolve_app(name)
       candidates = [name]
       candidates << "#{name}.rb" unless name.end_with?(".rb")
@@ -67,8 +136,51 @@ module Sandals
       system(*command, out: File::NULL, err: File::NULL)
     end
 
+    def app_template(title)
+      <<~RUBY
+        require "sandals"
+
+        Sandals.app title: "#{title}" do
+          @name = ""
+
+          view do
+            stack do
+              title "#{title}"
+
+              text_field "Your name", value: @name do |value|
+                @name = value
+              end
+
+              para "Hello, \#{@name}!" unless @name.empty?
+            end
+          end
+        end
+      RUBY
+    end
+
+    def test_template(base_name)
+      <<~RUBY
+        require "minitest/autorun"
+        require_relative "#{base_name}"
+
+        class GeneratedAppTest < Minitest::Test
+          def test_greets_the_user
+            session = Sandals.test(Sandals.application)
+
+            session.field("Your name").fill("Ada")
+
+            assert session.text?("Hello, Ada!")
+          end
+        end
+      RUBY
+    end
+
     def usage
-      warn "Usage: sandals run APP [--no-open] [--port PORT]"
+      warn <<~USAGE
+        Usage:
+          sandals new NAME
+          sandals run APP [--no-open] [--port PORT]
+      USAGE
       1
     end
   end

data/lib/sandals/code_reloader.rb

@@ -2,9 +2,7 @@
 
 module Sandals
   class CodeReloader
-    ANSI_ESCAPE = /\e\[[0-9;]*m/
-
-    Result = Data.define(:version, :application, :error, :changed)
+    Result = Struct.new(:version, :application, :error, :changed)
 
     attr_reader :path
 
@@ -46,35 +44,7 @@ module Sandals
     end
 
     def error_details(error)
-      {
-        class: error.class.to_s,
-        message: clean_message(error),
-        location: error_location(error)
-      }
-    end
-
-    def error_location(error)
-      syntax_location =
-        clean_message(error).lines.first&.match(/\A(.+?):(\d+):/) if
-          error.is_a?(SyntaxError)
-      if syntax_location
-        source_path = syntax_location[1].delete_prefix("#{Dir.pwd}/")
-        return "#{source_path}:#{syntax_location[2]}"
-      end
-
-      locations = error.backtrace_locations || []
-      location = locations.find do |candidate|
-        !candidate.absolute_path.to_s.include?("/lib/sandals/")
-      end || locations.first
-      return path unless location
-
-      source_path = location.absolute_path || location.path
-      source_path = source_path.delete_prefix("#{Dir.pwd}/")
-      "#{source_path}:#{location.lineno}"
-    end
-
-    def clean_message(error)
-      error.message.gsub(ANSI_ESCAPE, "")
+      ErrorDetails.for(error, fallback_path: path)
     end
   end
 end

data/lib/sandals/error_details.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Sandals
+  class ErrorDetails
+    ANSI_ESCAPE = /\e\[[0-9;]*m/
+
+    def self.for(error, fallback_path: nil)
+      new(error, fallback_path:).to_h
+    end
+
+    def initialize(error, fallback_path:)
+      @error = error
+      @fallback_path = fallback_path
+    end
+
+    def to_h
+      {
+        class: @error.class.to_s,
+        message: clean_message,
+        location: error_location
+      }
+    end
+
+    private
+
+    def error_location
+      path, line = syntax_location || backtrace_location
+      return @fallback_path || "Location unavailable" unless path
+
+      relative_location(path, line)
+    end
+
+    def syntax_location
+      return unless @error.is_a?(SyntaxError)
+
+      line = clean_message.lines.first&.[](/:(\d+):/, 1)
+      [@error.path || @fallback_path, line] if line
+    end
+
+    def backtrace_location
+      locations = @error.backtrace_locations || []
+      location =
+        locations.find { |candidate| same_path?(candidate, @fallback_path) } ||
+        locations.find { |candidate| !sandals_path?(candidate) } ||
+        locations.first
+
+      [location&.absolute_path || location&.path, location&.lineno]
+    end
+
+    def same_path?(location, path)
+      path && File.expand_path(location.absolute_path || location.path) == File.expand_path(path)
+    end
+
+    def sandals_path?(location)
+      location.absolute_path.to_s.include?("/lib/sandals/")
+    end
+
+    def relative_location(path, line)
+      source_path = path.delete_prefix("#{Dir.pwd}/")
+      "#{source_path}:#{line}"
+    end
+
+    def clean_message
+      @error.message.gsub(ANSI_ESCAPE, "").strip
+    end
+  end
+end

data/lib/sandals/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sandals
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

data/lib/sandals.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "sandals/version"
+require_relative "sandals/error_details"
 require_relative "sandals/binding_resolver"
 require_relative "sandals/action_error"
 require_relative "sandals/uploaded_file"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sandals
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Benito Serna
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
 - !ruby/object:Gem::Dependency
   name: webrick
   requirement: !ruby/object:Gem::Requirement
@@ -42,6 +56,7 @@ files:
 - lib/sandals/binding_resolver.rb
 - lib/sandals/cli.rb
 - lib/sandals/code_reloader.rb
+- lib/sandals/error_details.rb
 - lib/sandals/event_dispatcher.rb
 - lib/sandals/html_renderer.rb
 - lib/sandals/server.rb