katapult 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 83b5fc8065a8a49c75139d70ffd14b8bd9f46153
-  data.tar.gz: da1546065c4be23023e74749f5ab80ce217f4a58
+  metadata.gz: a3cdc0f0b264fd596277340707b91532b302b8d2
+  data.tar.gz: 92f80d989c103b65434d22d9d33c0eb273f2dd40
 SHA512:
-  metadata.gz: ce71cf5e9ddd843be50e677070b5591a3f6dc48e2bff36eebc7f86651cbc2a8610f950476c9c47a407431550611202cfe65fd2a20318870f57e6745db9c6ed6a
-  data.tar.gz: 2285ddc6da1550f9cbf75165b49d2e6f65ba1894b97286d9b1e1b0f2efa61456e0534c37890b9758f5a37cebb40c02d2968933a8e58e26ade886fd9a0f1b9ed5
+  metadata.gz: 708499a49443d9384eb273369a0e81bf2f6578e0520a9bc460abeefdc2c8c97ff5d310407e391ac80fc8517791c0c12f89652d60a3ff42b7d0228b9466130871
+  data.tar.gz: d122fd0af16935458dd2b06867fa86b5d545a74b8a2fb2f746c49cd61cada320b333426282a627cb5f41340b14dade12795724496a80c2404af42dfa76d0bd0f

data/.gitignore

@@ -16,3 +16,4 @@ test/tmp
 test/version_tmp
 tmp
 .pt_project_id
+.idea

data/.ruby-version

@@ -1 +1 @@
-2.1.5
+2.3.0

data/README.md

@@ -3,13 +3,17 @@
 <img src="katapult.png" width="200px" align="right" />
 
 
-`Katapult` is a kickstart generator for Rails applications. It creates a basic
-application and generates ([makandra-flavored](https://leanpub.com/growing-rails))
-code from an application model, significantly speeding up the initial phase of a
-Rails project.
+`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.
 
-`Katapult` will always support current versions of Ruby and Rails, currently
-Rails 4.2 and Ruby 2.1.
+`Katapult` will only support current versions of Ruby and Rails, currently
+Rails 4.2 and Ruby 2.3.
 
 
 ## Installation
@@ -18,15 +22,18 @@ Install the `katapult` gem with
 
     gem install katapult
 
+If you intend to extend an existing application, add it to the development group
+in your Gemfile.
+
 
 ## Usage
 
 `Katapult` does two separate things:
 
-1. Create a new Rails application, set up with many standard gems, snippets,
-   useful configuration, databases etc.
-2. Generate code from an application model, i.e. create files for models, views,
-   controllers, routes, stylesheets
+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
 
 You may use both or only one of them.
 
@@ -37,28 +44,27 @@ Run the following command:
 
     katapult new $APPLICATION_NAME
 
-In detail, this will:
+This will:
  
-- create a new Rails application (without turbolinks)
-- install common Gems, some of them commented out
-- add a .gitignore and a .ruby-version file
-- set up a `database.yml` file (for MySQL)
+- create a new Rails application
+- install common Gems
+- set up a `database.yml` file (for PostgreSQL)
 - create basic styles
-- install some handy initializers
 - install RSpec and Cucumber to the application
-- create `lib/katapult/application_model.rb` (needed in Step 2)
+- install Capistrano
+- create `lib/katapult/application_model.rb` (needed for step 2)
 
-See `lib/generators/katapult/basics/basics_generator.rb`.
+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.
 
-### Using Katapult in existing Rails applications
+### Alternative: Using Katapult in existing Rails applications
 `katapult` expects a clean application (that 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 files.
+ask before overwriting anything.
 
-To add `katapult` to an existing Rails application, add
-`gem 'katapult', group: :development` to the Gemfile. Then run any of the
-following generators:
+After adding it to the Gemfile (see above), run any of the following generators:
 
     rails generate katapult:basics # Prepare the app with useful defaults
     rails generate katapult:install # Create application model file
@@ -72,16 +78,20 @@ following generators:
 > install it with `rails generate katapult:install`. See above.
 
 After installation, you will find a file `lib/katapult/application_model.rb`
-where you will define the properties of your application.
+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 this file, use `katapult`'s simple DSL (domain specific language) to
-express yourself. When you are done developing the application model, 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:
 
-    katapult fire
+    katapult fire [path/to/application_model]
 
 See an overview of the DSL below. The respective sections hold examples of what
-options are available to each element.
+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.
 
 ### Generic DSL syntax example
 The DSL consists of _elements_, e.g. `Model` or `WUI` (Web User Interface). Each
@@ -108,6 +118,10 @@ Defined on Model. Takes a name and options:
     
     # Inferred type :email (when attr name matches /email/)
     model.attr :email
+
+    # Inferred type :password. Password fields are rendered as password_field in
+    # forms, but never rendered in show views.
+    model.attr :password
     
     # Specify assignable values. Available options: allow_blank, default
     model.attr :age, type: :integer, assignable_values: 18..99, allow_blank: true
@@ -121,6 +135,10 @@ Defined on Model. Takes a name and options:
     # Boolean fields are modeled as flags. Default required!
     model.attr :locked, type: :flag, default: false
 
+    # JSON fields are supported
+    model.attr :prefer, type: :json # PostgreSQL "jsonb"
+    model.attr :avoid, type: :plain_json # PostgreSQL "json"
+
 
 ### WUI (Web User Interface)
 Takes a name, options and a block:
@@ -160,6 +178,16 @@ WUIs.
     navigation :main
 
 
+### 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).
+
+    authenticate 'User', system_email: 'system@example.com'
+
+The email address will be the sender for Clearance mails like password reset
+requests.
+
+
 ## Development
 
 ### Basic information
@@ -171,14 +199,12 @@ 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.
 
-Since `katapult` has full-stack integration tests, it requires a MySQL account.
-Create a dedicated account on your local MySQL server by running this command in
-a MySQL console (as-is):
-
-    GRANT ALL ON *.* TO 'katapult'@'localhost' IDENTIFIED BY 'secret';
+Since `katapult` has full-stack integration tests, it requires a PostgreSQL
+account. Create a dedicated account on your local PostgreSQL server:
 
-The user `katapult` is hereby granted any action (SELECT, UPDATE, etc. except
-for granting privileges) on any database and table (`*.*`).
+    $> sudo -iu postgres
+    postgres $> psql
+    postgres=# CREATE ROLE katapult WITH createdb LOGIN;
 
 ### Continuing development
 When you continue development on `katapult`, remove its `tmp/` directory first.

data/bin/katapult

@@ -4,18 +4,8 @@
 # that the user else had to perform manually.
 # See bottom for USAGE.
 
-require_relative '../lib/katapult/util'
-require 'bundler'
-
-def pink_puts(*args)
-  message = "\n> #{ args.join ' ' }"
-  Kernel.puts "\e[35m#{ message }\e[0m" # pink
-end
-
-# With clean Bundler env
-def run(command)
-  Bundler.with_clean_env { system command }
-end
+require_relative '../lib/katapult/binary_util'
+util = Katapult::BinaryUtil
 
 case (transform_command = ARGV.shift)
 when 'new'
@@ -24,35 +14,35 @@ when 'new'
   basics_command = 'bundle exec rails generate katapult:basics'
 
   if interactive
-    pink_puts 'Please enter your database user: '
+    util.puts 'Please enter your database user: '
     basics_command << ' --db-user ' << gets.chomp
 
-    pink_puts 'Please enter your database password: '
+    util.puts 'Please enter your database password: '
     basics_command << ' --db-password ' << gets.chomp
   end
 
-  pink_puts 'Creating new Rails application ...'
-  run "rails new #{ app_name } --skip-test-unit --skip-bundle --database mysql"
+  util.puts 'Creating new Rails application ...'
+  util.create_rails_app app_name
 
   Dir.chdir app_name
 
-  pink_puts 'Initializing git repository ...'
-  run 'git init'
-  Katapult::Util.git_commit "rails new #{ app_name }"
+  util.puts 'Initializing git repository ...'
+  util.run 'git init --quiet'
+  util.git_commit "rails new #{ app_name }", '--quiet'
 
-  pink_puts 'Installing katapult ...'
+  util.puts 'Installing katapult ...'
   File.open('Gemfile', 'a') do |file|
     file.puts "gem 'katapult'#{ ENV['KATAPULT_GEMFILE_OPTIONS'] }, group: :development"
   end
-  run 'bundle install'
-  run 'bundle exec rails generate katapult:install'
-  Katapult::Util.git_commit 'rails generate katapult:install'
+  util.run 'bundle install --quiet'
+  util.run 'bundle exec rails generate katapult:install'
+  util.git_commit 'rails generate katapult:install', '--quiet'
 
-  pink_puts 'Generating katapult basics ...'
-  run basics_command
-  Katapult::Util.git_commit 'rails generate katapult:basics'
+  util.puts 'Generating katapult basics ...'
+  util.run basics_command
+  util.git_commit 'rails generate katapult:basics', '--quiet'
 
-  pink_puts <<-INSTRUCTIONS
+  util.puts <<-INSTRUCTIONS
 Application initialization done.
 
 Next step: Model your application in lib/katapult/application_model.rb and
@@ -60,14 +50,14 @@ transform it into code by running `katapult fire`.
   INSTRUCTIONS
 
 when 'fire'
-  app_model_path = 'lib/katapult/application_model.rb'
+  app_model_path = ARGV.shift || 'lib/katapult/application_model.rb'
   transform_command = 'bin/rails generate katapult:transform ' + app_model_path
 
-  pink_puts 'Loading katapult ...'
-  run transform_command
-  Katapult::Util.git_commit transform_command
+  util.puts 'Loading katapult ...'
+  util.run transform_command
+  util.git_commit transform_command
 
-  pink_puts <<-INSTRUCTIONS
+  util.puts <<-INSTRUCTIONS
 Model transformation done.
 
 Now boot up your development server (e.g. with `rails server`) and try your
@@ -76,7 +66,7 @@ kickstarted application in the browser!
 
 else
   puts <<-USAGE
-Usage: katapult [new APP_NAME | fire]
-Hint: Suppress database credentials prompt with `--non-interactive`
+Usage: katapult [new APP_NAME | fire [path/to/model] ]
+Suppress database credentials prompt with `--non-interactive`
   USAGE
 end

data/features/authenticate.feature

@@ -0,0 +1,344 @@
+Feature: Add authentication to an application
+
+  Background:
+    Given a pristine Rails application
+    And I install katapult
+    And I generate katapult basics
+
+
+  Scenario: Authenticate with the User model
+    When I overwrite "lib/katapult/application_model.rb" with:
+      """
+      model 'user'
+      wui('user') { |w| w.crud }
+      authenticate 'user', system_email: 'system@example.com'
+      """
+    And I successfully transform the application model
+    Then the file "Gemfile" should contain "gem 'clearance'"
+    And the file "app/controllers/application_controller.rb" should contain:
+      """
+        include Clearance::Controller
+
+        before_action :require_login
+      """
+    And the file "app/controllers/passwords_controller.rb" should contain exactly:
+      """
+      class PasswordsController < Clearance::PasswordsController
+
+        def update
+          @user = find_user_for_update
+
+          if @user.update_password password_reset_params
+            sign_in @user
+            flash[:notice] = 'Password successfully changed' # <<- added
+            redirect_to url_after_update
+          else
+            flash_failure_after_update
+            render template: 'passwords/edit'
+          end
+        end
+
+      end
+      """
+    And the file "app/controllers/users_controller.rb" should match /permit.*email.*password/
+    And the file "app/views/users/_form.html.haml" should contain:
+      """
+          %dt
+            = form.label :email
+          %dd
+            = form.email_field :email
+      """
+    And the file "app/views/users/_form.html.haml" should contain:
+      """
+          %dt
+            = form.label :password
+          %dd
+            = form.password_field :password
+      """
+    And the file "app/views/clearance_mailer/change_password.html.haml" should contain exactly:
+      """
+      %p
+        To reset your password, please follow this link:
+
+      %p
+        = link_to 'Change password',
+          edit_user_password_url(@user, token: @user.confirmation_token.html_safe)
+
+      """
+    And the file "app/views/clearance_mailer/change_password.text.erb" should contain exactly:
+      """
+      To reset your password, please follow this link:
+
+      <%= edit_user_password_url(@user, token: @user.confirmation_token.html_safe) %>
+      """
+    And the file "app/views/passwords/create.html.haml" should contain exactly:
+      """
+      %h1
+        Password Reset Instructions Sent
+
+      %p
+        We've sent you an email with instructions on how to reset your password.
+      """
+    And the file "app/views/passwords/edit.html.haml" should contain exactly:
+      """
+      %h1
+        Reset Password
+
+      %p
+        Choose your new password:
+
+      = form_for :password_reset,
+        url: user_password_path(@user, token: @user.confirmation_token),
+        html: { method: :put } do |form|
+
+        .form-group
+          = form.label :password
+          = form.password_field :password, class: 'form-control',
+            placeholder: 'New Password'
+
+        = form.submit 'Update Password', class: 'btn btn-primary'
+      """
+    And the file "app/views/passwords/new.html.haml" should contain exactly:
+      """
+      %h1
+        Password Reset
+
+      %p
+        Please enter your email address. We will send you instructions on how
+        to reset your password.
+
+      = form_for :password, url: passwords_path do |form|
+        .form-group
+          = form.label :email
+          = form.email_field :email, class: 'form-control',
+            placeholder: 'Email Address'
+
+        = form.submit 'Request Instructions', class: 'btn btn-primary'
+      """
+    And the file "app/views/sessions/new.html.haml" should contain exactly:
+      """
+      %h1
+        Please sign in
+
+      = form_for :session, url: session_path do |form|
+        .form-group
+          = form.label :email
+          = form.email_field :email, class: 'form-control',
+            placeholder: 'Email Address', required: true, autofocus: true
+
+        .form-group
+          = form.label :password
+          = form.password_field :password, class: 'form-control', required: true,
+            placeholder: 'Password'
+
+        %p
+          = form.submit 'Sign in', class: 'btn btn-primary'
+
+        %p
+          = link_to 'Forgot password', new_password_path, class: 'text-muted'
+      """
+    And the file "config/environments/test.rb" should contain:
+      """
+        # Enable quick-signin in tests: `visit homepage(as: User.last!)`
+        config.middleware.use Clearance::BackDoor
+
+      """
+    And the file "config/initializers/clearance.rb" should contain exactly:
+      """
+      Clearance.configure do |config|
+        config.allow_sign_up = false
+        # config.cookie_domain = '.example.com'
+        # config.cookie_expiration = lambda { |cookies| 1.year.from_now.utc }
+        # config.cookie_name = 'remember_token'
+        # config.cookie_path = '/'
+        config.routes = false
+        # config.httponly = true
+        config.mailer_sender = 'system@example.com'
+        # config.password_strategy = Clearance::PasswordStrategies::BCrypt
+        # config.redirect_url = '/'
+        # config.secure_cookie = true
+        # config.sign_in_guards = []
+        # config.user_model = User
+      end
+      """
+    And a file named "config/locales/clearance.en.yml" should exist
+    And the file "config/routes.rb" should contain:
+      """
+        resources :users do
+          resource :password, controller: 'passwords',
+            only: %i[edit update]
+        end
+
+        # Clearance
+        get '/login', to: 'clearance/sessions#new', as: 'sign_in'
+        resource :session, controller: 'clearance/sessions', only: [:create]
+        resources :passwords, controller: 'passwords', only: [:create, :new]
+        delete '/logout', to: 'clearance/sessions#destroy', as: 'sign_out'
+      """
+    And there should be a migration with:
+      """
+      class AddClearanceToUsers < ActiveRecord::Migration
+        def self.up
+          change_table :users do |t|
+            t.string :encrypted_password, limit: 128
+            t.string :confirmation_token, limit: 128
+            t.string :remember_token, limit: 128
+          end
+
+          add_index :users, :email
+          add_index :users, :remember_token
+
+          users = select_all("SELECT id FROM users WHERE remember_token IS NULL")
+
+          users.each do |user|
+            update <<-SQL
+              UPDATE users
+              SET remember_token = '#{Clearance::Token.new}'
+              WHERE id = '#{user['id']}'
+            SQL
+          end
+        end
+
+        def self.down
+          change_table :users do |t|
+            t.remove :encrypted_password, :confirmation_token, :remember_token
+          end
+        end
+      end
+      """
+    And the file "features/authentication.feature" should contain exactly:
+      """
+      Feature: Everything about user authentication
+
+        Scenario: Login is required to visit the homepage
+          When I go to the homepage
+          Then I should see "Please sign in to continue" within the flash
+            And I should be on the sign-in form
+
+
+        Scenario: Login
+          Given there is a user with the email "henry@example.com" and the password "password"
+
+          When I go to the homepage
+          Then I should be on the sign-in form
+            And I should see "Please sign in"
+
+          # Wrong email
+          When I fill in "Email" with "nonsense"
+            And I fill in "Password" with "password"
+            And I press "Sign in"
+          Then I should see "Bad email or password" within the flash
+            And I should see "Please sign in"
+
+          # Wrong password
+          When I fill in "Email" with "admin@example.com"
+            And I fill in "Password" with "wrong"
+            And I press "Sign in"
+          Then I should see "Bad email or password" within the flash
+            And I should see "Please sign in"
+
+          # Correct credentials
+          When I fill in "Email" with "henry@example.com"
+            And I fill in "Password" with "password"
+            And I press "Sign in"
+          Then I should be on the homepage
+
+
+        Scenario: Logout
+          Given there is a user
+            And I am signed in as the user above
+
+          When I follow "Sign out"
+          Then I should be on the sign-in form
+
+          # Logged out
+          When I go to the homepage
+          Then I should be on the sign-in form
+
+
+        Scenario: Reset password as a signed-in user
+          Given there is a user with the email "henry@example.com"
+            And I sign in as the user above
+
+          When I go to the homepage
+            And I follow "henry@example.com" within the current user
+          Then I should be on the form for the user above
+
+          When I fill in "Password" with "new-password"
+            And I press "Save"
+          Then I should be on the page for the user above
+
+          When I follow "Sign out"
+            And I fill in "Email" with "henry@example.com"
+            And I fill in "Password" with "new-password"
+            And I press "Sign in"
+          Then I should be on the homepage
+
+
+        Scenario: Reset password as a signed-out user
+          Given there is a user with the email "henry@example.com"
+
+          When I go to the sign-in form
+            And I follow "Forgot password"
+          Then I should be on the reset password page
+            And I should see "Password Reset"
+
+          When I fill in "Email" with "henry@example.com"
+            And I press "Request Instructions"
+          Then an email should have been sent with:
+            \"\"\"
+            From: system@example.com
+            To: henry@example.com
+            Subject: Change your password
+
+            To reset your password, please follow this link:
+            \"\"\"
+
+          When I follow the first link in the email
+          Then I should be on the new password page for the user above
+            And I should see "Reset Password"
+
+          When I fill in "Choose password" with "new-password"
+            And I press "Update Password"
+          Then I should see "Password successfully changed" within the flash
+            And I should be on the homepage
+      """
+    And the file "features/users.feature" should contain:
+      """
+
+
+        Background:
+          Given there is a user
+            And I sign in as the user above
+
+      """
+    And the file "features/step_definitions/authentication_steps.rb" should contain exactly:
+      """
+      When /^I (?:am signed|sign) in as the user above$/ do
+        user = User.last!
+        visit root_path(as: user) # Using Clearance::BackDoor
+      end
+      """
+    And the file "features/support/paths.rb" should contain:
+      """
+
+          # Authentication
+          when 'the sign-in form'
+            sign_in_path
+          when 'the reset password page'
+            new_password_path
+          when 'the new password page for the user above'
+            edit_user_password_path(User.last!)
+
+      """
+    And the file "spec/factories/factories.rb" should contain:
+      """
+        factory :user do
+          sequence(:email) { |i| "user-#{ i }@example.com" }
+          password 'password'
+        end
+      """
+
+    When I run cucumber
+    Then the features should pass
+