katapult 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a3cdc0f0b264fd596277340707b91532b302b8d2
-  data.tar.gz: 92f80d989c103b65434d22d9d33c0eb273f2dd40
+SHA256:
+  metadata.gz: ddcf0832f9fb8d7597253465296fe0726761e1bd2d3088d741e4bedf51e05cf7
+  data.tar.gz: 293a4ba645e9710e1392707ae59df834e9d14cbd841920e919d02d3d0db02e73
 SHA512:
-  metadata.gz: 708499a49443d9384eb273369a0e81bf2f6578e0520a9bc460abeefdc2c8c97ff5d310407e391ac80fc8517791c0c12f89652d60a3ff42b7d0228b9466130871
-  data.tar.gz: d122fd0af16935458dd2b06867fa86b5d545a74b8a2fb2f746c49cd61cada320b333426282a627cb5f41340b14dade12795724496a80c2404af42dfa76d0bd0f
+  metadata.gz: 2ead2ca1d7f9bbee69ad9bdac6e5043c513e23deffa6f73119b3b4145206d56f7cf3537067d7116b39d04b0e7c07f795eb839600dedd14f9e22d6bc501e8f33e
+  data.tar.gz: cd2336671a2317373433ff47a3568e35073757c21ff2972d1a8d3004830c764adcc7c422e55b34966255952516760eee329a0468687159adf78c5aa2c46551f3

data/.rspec

@@ -1,2 +1,3 @@
+--require spec_helper
 --color
 --format progress

data/.ruby-version

@@ -1 +1 @@
-2.3.0
+2.5.0

data/Gemfile

@@ -2,3 +2,12 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in katapult.gemspec
 gemspec
+
+gem 'bundler', '~> 1.5'
+gem 'rake'
+gem 'pry'
+
+# Test
+gem 'aruba', '~> 0.10'
+gem 'guard-cucumber'
+gem 'rspec', '~> 3.4'

data/README.md

@@ -5,15 +5,25 @@
 
 `Katapult` is a kickstart generator for Rails applications. It creates new Rails
 applications with [lots of pre-configuration](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
-and offers ([makandra-flavored](https://leanpub.com/growing-rails)) code
-generation from an application model.
-These two features significally speed up the initial phase of a Rails project by
-doing in minutes what took you weeks. After modeling your application, which
-typically takes about an hour, you can instantly start implementing the meat of
-your application.
+and offers [makandra-flavored](https://leanpub.com/growing-rails) code
+generation from an application model. These two features significally speed up
+the initial phase of a Rails project by doing in minutes what otherwise would
+cost you weeks.
+After modeling your application, which typically takes about an hour, you can
+instantly start implementing the meat of your application.
 
-`Katapult` will only support current versions of Ruby and Rails, currently
-Rails 4.2 and Ruby 2.3.
+`Katapult` only supports a single Ruby and Rails version, currently it's Rails
+5.1.4 and Ruby 2.5.0.
+
+
+## Prerequisites
+
+Katapult uses *PostgreSQL* as database, so you'll need to install that upfront.
+Also, it drops the asset pipeline in favor of *Webpacker*, so you'll need Node
+and Yarn (see <https://makandracards.com/makandra/47477>).
+
+Also, it requires the *Bundler* and *Rake* Ruby gems, which are probably already
+installed on your system.
 
 
 ## Installation
@@ -28,14 +38,14 @@ in your Gemfile.
 
 ## Usage
 
-`Katapult` does two separate things:
+`katapult` does two distinct things for you:
 
 1. It creates a new Rails application, set up with many standard gems, snippets,
-   useful configuration, databases, testing libraries etc. See the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb) for details.
-2. It generates code from an application model, i.e. creates files for models,
-   views, controllers, routes, stylesheets; see the
+   useful configuration, databases, testing libraries etc.
+2. It generates code from an application model, i.e. it creates models and
+   views, controllers, styles etc. 
 
-You may use both or only one of them.
+You may use both or only one of them. Read on for details.
 
 
 ## 1) Creating a new Rails application
@@ -44,58 +54,44 @@ Run the following command:
 
     katapult new $APPLICATION_NAME
 
-This will:
- 
-- create a new Rails application
-- install common Gems
-- set up a `database.yml` file (for PostgreSQL)
-- create basic styles
-- install RSpec and Cucumber to the application
-- install Capistrano
-- create `lib/katapult/application_model.rb` (needed for step 2)
-
-See the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
-for details: Its methods are executed one-by-one and their names are a
-description of what it does.
-
-### Alternative: Using Katapult in existing Rails applications
-`katapult` expects a clean application (that it would usually generate itself).
+This will create a new Rails application and prepare it in more than 20 steps.
+Read the [BasicsGenerator](https://github.com/makandra/katapult/blob/master/lib/generators/katapult/basics/basics_generator.rb)
+for details: Its methods are executed one-by-one, while the method names are a
+description of what they do.
+
+### Alternative: Using Katapult in an existing Rails application
+`katapult` expects a fresh application (which it would usually generate itself).
 If you have an existing Rails application, you *may* use `katapult`, but be
 warned: it is not designed to respect existing files, although it will usually
-ask before overwriting anything.
+ask before overwriting something.
 
-After adding it to the Gemfile (see above), run any of the following generators:
+After adding it to the Gemfile, run the basics generator manually:
 
-    rails generate katapult:basics # Prepare the app with useful defaults
-    rails generate katapult:install # Create application model file
-    rails generate katapult:transform lib/katapult/application_model.rb
+    bin/rails generate katapult:basics
 
 
 ## 2) Generating code from an application model
 
-> If you only want to use the code generation feature of `katapult`, but did not
-> run `katapult new ...`, you need to add `katapult` to your Gemfile now and
-> install it with `rails generate katapult:install`. See above.
+After running `katapult new`, you will find a default application model in
+ `lib/katapult/application_model.rb`. It contains a full example of `katapult`'s
+features that you should replace with _your_ application model.
 
-After installation, you will find a file `lib/katapult/application_model.rb`
-where you will define the properties of your application. You're free to create
-more than one application model, however, you'll need to specify their location
-when running the transform.
-
-Inside the application model, use `katapult`'s simple DSL (domain specific
-language) to express yourself. When you are done developing the model, transform
-it into code with:
+When you are done, transform the model using:
 
     katapult fire [path/to/application_model]
 
+The path is optional and only needs to be specified when you've renamed the
+application model file. Note that you may well use separate model files for
+separate runs.
+
 See an overview of the DSL below. The respective sections hold examples of what
 options are available to each element. For details, dive into
 `lib/generators/katapult` where all generators are stored. The method names
-inside a generator tell what it does.
+of a generator tell what it does.
 
 ### Generic DSL syntax example
-The DSL consists of _elements_, e.g. `Model` or `WUI` (Web User Interface). Each
-`katapult` element has the same syntax, taking a name, options, and a block:
+The DSL consists of _elements_, e.g. `Model` or `WebUI`. Each `katapult` element
+has the following syntax, taking a name, options, and a block:
 
     element_type 'name', options: 'example' do |element|
       element.some_method
@@ -140,47 +136,51 @@ Defined on Model. Takes a name and options:
     model.attr :avoid, type: :plain_json # PostgreSQL "json"
 
 
-### WUI (Web User Interface)
+### WebUI
 Takes a name, options and a block:
 
-    wui 'Customer', model: 'User' do |wui|
-      # wui.crud, see Action element
-    end
+    web_ui 'Customer', model: 'User' do |web_ui|
+      web_ui.crud # Create all the standard rails actions
 
-    # Inferred model name: 'Customer'
-    wui 'Customer' do |wui|
-      # wui.crud, see Action element
+      # web_ui.action :custom etc, see Action element
     end
 
+    # Short syntax with inferred model name 'User'
+    web_ui 'User', &:crud
 
-#### Action
-Defined on WUI. Takes a name and options:
 
-    # Create all the standard rails actions
-    wui.crud
+#### Action
+Defined on WebUI. Takes a name and options:
 
     # Select single Rails actions
-    wui.action :index
-    wui.action :show
-    wui.action :create # also creates :new
-    wui.action :update # also creates :edit
-    wui.action :destroy
+    web_ui.action :index
+    web_ui.action :show
+    web_ui.action :create # also creates :new
+    web_ui.action :update # also creates :edit
+    web_ui.action :destroy
     
     # Add custom actions
-    wui.action :custom_action, method: :post, scope: :member
-    wui.action :other_action, method: :get, scope: :collection
+    web_ui.action :custom_action, method: :post, scope: :member
+    web_ui.action :other_action, method: :get, scope: :collection
     
+### Crud
+This is a shortcut for creating a model together with a WebUI with CRUD actions.
+
+    crud 'Customer' do |customer|
+      customer.attr :name
+    end
+
 
 ### Navigation
-Takes a name, will generate a navigation with links to the index pages of all
-WUIs.
+No arguments, will generate a main menu with links to the index pages of all
+WebUIs.
 
-    navigation :main
+    navigation
 
 
 ### Authenticate
-Takes the name of the user model (currently only `User` (case-insensitive) is
-supported) and an email address. Generates authentication with [Clearance](https://github.com/thoughtbot/clearance).
+Takes the name of the user model (currently only `User` is supported) and an
+email address. Generates authentication with [Clearance](https://github.com/thoughtbot/clearance).
 
     authenticate 'User', system_email: 'system@example.com'
 
@@ -190,43 +190,71 @@ requests.
 
 ## Development
 
-### Basic information
+### Getting started + continuing development
 `Katapult` is tested with [RSpec](http://rspec.info/) and
 [Cucumber](https://cucumber.io/) + [Aruba](https://github.com/cucumber/aruba)
 ([API-Doc](http://www.rubydoc.info/github/cucumber/aruba/master/)).
 
-It caches a pristine Rails application inside its `tmp/` directory to
-speed up test runs. Keep this in mind, as it may lead to caching issues when
-switching Ruby versions or installing a new version of the Rails gem.
+For its full-stack integration tests, `katapult` requires a PostgreSQL account.
+Create a dedicated account on your local PostgreSQL server:
 
-Since `katapult` has full-stack integration tests, it requires a PostgreSQL
-account. Create a dedicated account on your local PostgreSQL server:
-
-    $> sudo -iu postgres
-    postgres $> psql
+    $> sudo -u postgres psql
     postgres=# CREATE ROLE katapult WITH createdb LOGIN;
 
-### Continuing development
-When you continue development on `katapult`, remove its `tmp/` directory first.
-It contains cached data that might lead to confusion.
+Whenever you start working on `katapult`, you should run `script/update`, which
+will guide you through a quick update process.
+
+### Suggested workflow
+When adding a feature to `katapult`, it will usually take you some time to
+figure out how exactly the generated code should look like. You'll be switching
+between `katapult`'s tests, its generators and the generated code.
+
+Here's a the suggested process:
+
+1) Run a scenario (create one if needed)
+2) Tag that scenario with @no-clobber. This will leave the generated test app
+   untouched in subsequent test runs.
+3) Make a commit inside the generated test application, so you'll have a clean
+   working directory: `script/kta git add --all && script/kta git commit -m 'x'`
+4) Modify the test app as needed. Boot a development server with
+   `script/kta rails s` if you like.
+5) Re-run the @no-clobber scenario (modify it as needed) until test and test app
+   meet the expectations.
+6) Now look at the git diff in the test app and model everything with katapult's
+   generators.
+7) Remove the @no-clobber tag and run the scenario normally to see if it's still
+   green. Remember to stop the development server first.
 
 ### Debugging
 Add the `@announce-output` tag to `katapult` features in order to have any output
-logged to your terminal.
+logged to your terminal. Note that each step will print all output to date, so
+you will see things multiple times.
+
+To precisely debug errors occurring _inside_ the generated application, use
+`script/kta`. You could also just cd to the test app directory, but since it is
+destroyed between test runs, you'd need to `cd ../../aruba/katapult_test_app`
+after each test.
 
-To precisely debug errors occurring _inside_ the generated application, you may
-cd to `tmp/aruba/katapult_test_app`. Run the failing command manually.
+When fixing issues in the generated app, make a commit in the app first. When
+you've fixed it, the diff will show you what you need to port back to katapult.
 
-Note that after running a katapult feature, you need to call
-`cd ../../aruba/katapult_test_app` inside the generated app terminal. This is
-required because the `tmp/aruba` directory is being wiped before each scenario.
+### Typical issues
+Be sure to check this list when you encounter strange issues during development.
 
-### Typical errors
+- Spring was running in a directory that does not exist any more. This will
+  screw subsequent spring invocations. Run `ps aux | grep spring` and `kill`
+  suspect processes.
+- An outdated Rails application in `tmp/cached_*`
 - Timeout error because of a script waiting for user input
-- Executing (bash) commands in the test application without resetting the
-  katapult gem's Bundler settings. Wrap into `Bundler.with_clean_env { }`.
-- Spring running inside the test application encumbers parallel_tests
-- An outdated Rails application in `tmp/cached_test_app`
+
+### Fast tests
+Generating basics and transforming the application model take quite some time
+(about 20s), because it boots the Rails application, resolves Yarn dependencies
+and migrates databases. To speed that up, `katapult` tests cache prepared Rails
+applications in tmp/.
+
+When debugging test suite speed, `bundle exec cucumber --format usage` is your
+friend.
 
 
 ## Credits

data/Rakefile

@@ -12,3 +12,16 @@ Cucumber::Rake::Task.new(:features) do |t|
 end
 
 RSpec::Core::RakeTask.new(:spec)
+
+task :update_readme do
+  require_relative 'lib/katapult/version'
+  readme_path = 'README.md'
+  readme = File.read readme_path
+
+  # Using \s+ to support line breaks
+  readme.sub! /(currently\s+it's\s+Rails\s+)[\d\.]+/, "\\1#{Katapult::RAILS_VERSION}"
+  readme.sub! /(and\s+Ruby\s+)[\d\.]+\d/, "\\1#{Katapult::RUBY_VERSION}"
+  File.open readme_path, 'w' do |f|
+    f.write readme
+  end
+end

data/bin/katapult

@@ -2,47 +2,76 @@
 
 # This script simplifies the usage of `katapult` by grouping relevant actions
 # that the user else had to perform manually.
-# See bottom for USAGE.
 
+usage = 'Usage: katapult new APP_NAME | fire [path/to/model] | version'
+
+require_relative '../lib/katapult/version'
 require_relative '../lib/katapult/binary_util'
 util = Katapult::BinaryUtil
 
-case (transform_command = ARGV.shift)
+require 'optparse'
+options = {}
+OptionParser.new do |opts|
+  opts.on '-u', '--db-user USER', 'Database user name' do |name|
+    options[:dbuser] = name
+  end
+  opts.on '-p', '--db-password PASS', 'Database password' do |password|
+    options[:dbpass] = password
+  end
+  opts.on '-v', '--verbose', 'Verbose output' do |verbose|
+    options[:verbose] = verbose
+  end
+end.parse!
+
+# Check Ruby version ###########################################################
+supported_ruby = Katapult::RUBY_VERSION
+current_ruby = `ruby -v`.chomp # Long version string à la "ruby 2.5.0p0 ..."
+
+current_ruby.include?(supported_ruby) or util.fail <<-MSG
+Ruby version error
+
+Your current Ruby (#{current_ruby})
+is not supported by this version of katapult.
+Please switch to Ruby #{supported_ruby} and run again.
+MSG
+
+
+case ARGV.shift
 when 'new'
-  interactive = !ARGV.delete('--non-interactive')
-  app_name = ARGV.shift
-  basics_command = 'bundle exec rails generate katapult:basics'
+  app_name = ARGV.shift || util.ask('Please enter the application name:')
+  app_name = util.snake_case(app_name)
+  puts "Normalized application name: #{app_name}" if options[:verbose]
 
-  if interactive
-    util.puts 'Please enter your database user: '
-    basics_command << ' --db-user ' << gets.chomp
+  # Any options that haven't be passed via command line should be asked for
+  options[:dbuser] ||= util.ask 'Please enter the database user:'
+  options[:dbpass] ||= util.ask 'Please enter the database password:'
 
-    util.puts 'Please enter your database password: '
-    basics_command << ' --db-password ' << gets.chomp
-  end
+  basics_command = 'bundle exec rails generate katapult:basics'
+  basics_command << ' --db-user ' << options[:dbuser]
+  basics_command << ' --db-password ' << options[:dbpass]
 
-  util.puts 'Creating new Rails application ...'
+  util.pink "Creating new Rails application in #{app_name} ..."
   util.create_rails_app app_name
-
   Dir.chdir app_name
 
-  util.puts 'Initializing git repository ...'
+  util.pink 'Initializing git repository ...'
   util.run 'git init --quiet'
   util.git_commit "rails new #{ app_name }", '--quiet'
 
-  util.puts 'Installing katapult ...'
+  util.pink 'Installing katapult ...'
   File.open('Gemfile', 'a') do |file|
     file.puts "gem 'katapult'#{ ENV['KATAPULT_GEMFILE_OPTIONS'] }, group: :development"
   end
   util.run 'bundle install --quiet'
-  util.run 'bundle exec rails generate katapult:install'
-  util.git_commit 'rails generate katapult:install', '--quiet'
+  util.run 'bundle exec rails generate katapult:app_model'
+  util.git_commit 'rails generate katapult:app_model', '--quiet'
 
-  util.puts 'Generating katapult basics ...'
+  util.pink 'Generating katapult basics ...'
   util.run basics_command
+  # Do not use `basics_command` as commit message, as it contains the password!
   util.git_commit 'rails generate katapult:basics', '--quiet'
 
-  util.puts <<-INSTRUCTIONS
+  util.pink <<-INSTRUCTIONS
 Application initialization done.
 
 Next step: Model your application in lib/katapult/application_model.rb and
@@ -53,20 +82,25 @@ when 'fire'
   app_model_path = ARGV.shift || 'lib/katapult/application_model.rb'
   transform_command = 'bin/rails generate katapult:transform ' + app_model_path
 
-  util.puts 'Loading katapult ...'
+  util.pink 'Loading katapult ...'
   util.run transform_command
+
+  util.pink 'Committing result ...'
   util.git_commit transform_command
 
-  util.puts <<-INSTRUCTIONS
+  util.pink <<-INSTRUCTIONS
 Model transformation done.
 
 Now boot up your development server (e.g. with `rails server`) and try your
 kickstarted application in the browser!
   INSTRUCTIONS
 
+when 'version'
+  puts <<-VERSION
+Katapult #{Katapult::VERSION}
+Generating a Rails #{Katapult::RAILS_VERSION} app on Ruby #{Katapult::RUBY_VERSION}.
+  VERSION
+
 else
-  puts <<-USAGE
-Usage: katapult [new APP_NAME | fire [path/to/model] ]
-Suppress database credentials prompt with `--non-interactive`
-  USAGE
+  puts usage
 end

data/features/application_model.feature

@@ -0,0 +1,55 @@
+#@announce-output
+Feature: The application model prepared by Katapult
+
+  Scenario: Generating the application model template
+    Given a new Rails application with Katapult basics installed
+
+    When I generate the application model
+    Then the file "lib/katapult/application_model.rb" should contain:
+    """
+    # Define a model + generate views with CRUD actions
+    # Since this generates the first web UI with an index action, the products list
+    # will become the home page of the generated app
+    crud 'product' do |product|
+      # The first attribute of each model is taken as a human identifier/label
+      product.attr :title # Default type "string"
+
+      # The order of attributes is respected when generating the form for that model
+      product.attr :price, type: :money
+      product.attr :mode, assignable_values: %w[public private]
+      product.attr :provider, type: :url
+      product.attr :import_data, type: :json
+    end
+
+    # Define a model
+    model 'user' do |user|
+      user.attr :email # Type "email" derived from attribute name
+
+      user.attr :name
+      user.attr :last_visit, type: :datetime
+      user.attr :locked, type: :flag, default: false
+    end
+
+    # Add a web user interface for the 'user' model
+    web_ui 'user' do |web_ui|
+      # All CRUD actions: index, show, new, create, edit, update, destroy
+      web_ui.crud
+
+      # Custom action
+      web_ui.action :lock, scope: :member, method: :post
+    end
+
+    # Have a main menu
+    navigation
+
+    # Add authentication
+    authenticate 'user', system_email: 'system@example.com'
+
+    """
+
+    When I successfully transform the application model including migrations
+      And I run cucumber
+    Then the features should pass
+
+    When I run rspec
+    Then the specs should pass