bullet_train 1.2.4 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d69973f61994b65b605d9336953c6993b580b82781d412391583bc7d5bf9cd0
-  data.tar.gz: 4ea8ca252e6156f7fcbb01ef4b1115475bed681efd2b46fa83b328192a2652a3
+  metadata.gz: 7f272526d56b142f946f7a0b4ebdbb8537120199a0f78be7cad85ba7265003b6
+  data.tar.gz: 1e50a2ae1848bd7613f8ce2ece37de6bb2fb85c485207226cad6b39e5d7ed908
 SHA512:
-  metadata.gz: 17c23db90040684969305697f996aed697799c166e826dd8fbc29d58f57f5c4db2ff1d3b05e6f7e7e337e5fb50e235f26c72d2b0e7fb279e9d0d1477f91f3650
-  data.tar.gz: '06852869d26adba82a25a67033254d43125fb6a730f82e65d7c5ab6097dbf6b1ecd523b4c848ca637402f2cf4abefaccdd3fbc5f8f3fef6f3f32ef7ed7570eda'
+  metadata.gz: 34c1d594e23e6ba2e11dc06b69f012cb118d8901bc47d08e697f26ecd5081228e02bfeb923746906730ee2f4e5ec8a8338da11234b828feca22c5d2cf1090e87
+  data.tar.gz: 538ac4bb1e3723f929059c382c642b00e9e30ddaee8f2d68880ac75a83e197fa9d7d0463e951f21d41123cce765622b16a6ff52696d75ee8944b5e08b91e231e

data/app/controllers/sessions_controller.rb

@@ -10,6 +10,18 @@ class SessionsController < Devise::SessionsController
   end
   helper_method :user_return_to_is_oauth
 
+  def new
+    # We allow people to pass in a URL to redirect to after sign in is complete. We have to do this because Safari
+    # doesn't allow them to set this in a session before a redirect if there isn't already a session. However, for
+    # security reasons we have to make sure we control the URL where we will redirect to, otherwise people could
+    # trick folks into redirecting to a fake destination in a phishing scheme.
+    if params[:return_url]&.start_with?(ENV["BASE_URL"])
+      store_location_for(resource_name, params[:return_url])
+    end
+
+    super
+  end
+
   def destroy
     if params.include?(:onboard_logout)
       signed_out = (Devise.sign_out_all_scopes ? sign_out : sign_out(resource_name))

data/app/models/concerns/memberships/base.rb

@@ -25,6 +25,8 @@ module Memberships::Base
       end
     end
 
+    scope :excluding_platform_agents, -> { where(platform_agent_of: nil) }
+    scope :platform_agents, -> { where.not(platform_agent_of: nil) }
     scope :current_and_invited, -> { includes(:invitation).where("user_id IS NOT NULL OR invitations.id IS NOT NULL").references(:invitation) }
     scope :current, -> { where("user_id IS NOT NULL") }
     scope :tombstones, -> { includes(:invitation).where("user_id IS NULL AND invitations.id IS NULL AND platform_agent IS FALSE").references(:invitation) }

data/app/models/concerns/teams/base.rb

@@ -38,6 +38,12 @@ module Teams::Base
     validates :time_zone, inclusion: {in: ActiveSupport::TimeZone.all.map(&:name)}, allow_nil: true
   end
 
+  def platform_agent_access_tokens
+    # TODO This could be written better.
+    platform_agent_user_ids = memberships.platform_agents.map(&:user_id).compact
+    Platform::AccessToken.joins(:application).where(resource_owner_id: platform_agent_user_ids, application: {team: nil})
+  end
+
   def admins
     memberships.current_and_invited.admins
   end

data/app/views/layouts/docs.html.erb

@@ -215,15 +215,21 @@
               <% end %>
 
               <%= render 'account/shared/menu/section', title: 'Integration' do %>
-                <%= render 'account/shared/menu/item', url: '/docs/oauth', label: 'OAuth Providers' do |p| %>
+                <%= render 'account/shared/menu/item', url: '/docs/api', label: 'REST API' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-at ti ti-reload"></i>
+                    <i class="fal fa-brackets-curly ti ti-settings"></i>
                   <% end %>
                 <% end %>
 
-                <%= render 'account/shared/menu/item', url: '/docs/api', label: 'REST API' do |p| %>
+                <%= render 'account/shared/menu/item', url: '/docs/zapier', label: 'Zapier' do |p| %>
                   <% p.content_for :icon do %>
-                    <i class="fal fa-brackets-curly ti ti-settings"></i>
+                    <i class="fal fa-bolt ti ti-bolt"></i>
+                  <% end %>
+                <% end %>
+
+                <%= render 'account/shared/menu/item', url: '/docs/oauth', label: 'OAuth Providers' do |p| %>
+                  <% p.content_for :icon do %>
+                    <i class="fal fa-at ti ti-reload"></i>
                   <% end %>
                 <% end %>
 

data/docs/api/versioning.md

@@ -0,0 +1,63 @@
+# API Versioning
+Bullet Train's API layer is designed to help support the need of software developers to evolve their API over time while continuing to maintain support for versions of the API that users have already built against.
+
+## What is API versioning?
+By default, Bullet Train will build out a "V1" version of your API. The version number is intended to represent a contract with your users that as long as they're hitting `/api/v1` endpoints, the structure of URLs, requests, and responses won't change in a way that will break the integrations they've created.
+
+If a change to the API would break the established contract, we want to bump the API version number so we can differentiate between developers building against the latest version of the API (e.g. "V2") and developers who wrote code against the earlier version of the API (e.g. "V1"). This allows us the opportunity to ensure that older versions of the API continue to work as previously expected by the earlier developers.
+
+## When should you take advantage of API versioning?
+You want to bump API versions as sparingly as possible. Even with all the tooling Bullet Train provides, maintaining backwards compatibility of older API versions comes at an ongoing cost. Generally speaking, you should only bump your API version when a customer is already using an API endpoint and you're making changes to the structure of your domain model that are not strictly additive and will break the established contract.
+
+Importantly, if the changes you're making to your domain model are only additive, you don't need to bump your API version. Users shouldn't care that you're adding new attributes or new endpoints to your API, just as long as the ones they're already using don't change in a way that is breaking for them.
+
+## Background
+By default, the following components in your API are created in versioned namespaces:
+
+ - API controllers are in `app/controllers/api/v1` and live in an `Api::V1` module.
+ - JSON views are in `app/controllers/api/v1`.
+ - Routes are in `config/routes/api/v1.rb`.
+ - Tests are in `test/controllers/api/v1` and live in an `Api::V1` module.
+
+> It's also impotant to keep in mind that some dependencies of your API and API tests like models, factories, and permissions are not versioned, but as we'll cover later, this is something our approach helps you work around.
+
+## Bumping Your API Version
+
+⚠️ You must do this _before_ making the breaking changes to your API.
+
+If you're in a situation where you know you need to bump your API version to help lock-in a backward compatible version of your API, you can simply run:
+
+```
+rake bullet_train:api:bump_version
+```
+
+> TODO This Rake task doesn't exist yet.
+
+## What happens when you bump an API version?
+When you bump your API version, all of the files and directories that are namespaced with the API version number will be duplicated into a new namespace for the new API version number.
+
+For example, when bumping from "V1" to "V2":
+
+ - A copy of all the API controllers in `app/controllers/api/v1` are copied into `app/controllers/api/v2`.
+ - A copy of all the JSON views in `app/views/api/v1` are copied into `app/views/api/v2`.
+ - A copy of all the routes in `config/routes/api/v1.rb` are copied into `config/routes/api/v2.rb`.
+ - A copy of all the tests in `test/controllers/api/v1` are copied into `test/controllers/api/v2`.
+
+We also bump the value of `BulletTrain::Api.current_version` in `config/initializers/api.rb` so tools like Super Scaffolding know which version of your API to update going forward.
+
+## How does this help?
+As a baseline, keeping a wholesale copy of the versioned API components helps lock in their behavior and protect them from change going forward. It's not a silver bullet, since unversioned dependencies (like your model, factories, and permissions) can still affect the behavior of these versioned API components, but even in that case these copied files give us a place where we can implement the logic that helps older versions of the API continue to operate even as unversioned components like our domain model continue changing.
+
+### Versioned API Tests
+By versioning our API tests, we lock in a copy of what the assumptions were for older versions of the API. Should unversioned dependencies like our domain model change in ways that break earlier versions of our API, the test suite will let us know and help us figure out when we've implemented the appropriate logic in the older version of the API controller to restore the expected behavior for that version of the API.
+
+## Advanced Topics
+
+### Object-Oriented Inheritance
+In order to reduce the surface area of legacy API controllers that you're maintaining, it might make sense in some cases to have an older versioned API controller simply inherit from a newer version or the current version of the same API controller. For example, this might make sense for endpoints that you know didn't have breaking changes across API versions.
+
+### Backporting New Features to Legacy API Versions
+Typically we'd recommend you use new feature availability to encourage existing API users to upgrade to the latest version of the API. However, in some situations you may really need to make a newer API feature available to a user who is locked into a legacy version of your API for some other endpoint. This is totally fine if the feature is only additive. For example, if you're just adding a newer API endpoint in a legacy version of the API, you can simply have the new API controller in the legacy version of the API inherit from the API controller in the current version of the API.
+
+### Pruning Unused Legacy API Endpoints
+Maintaining legacy endpoints has a very real cost, so you may choose to identify which endpoints aren't being used on legacy versions of your API and prune them from that version entirely. This has the effect of requiring existing API users to keep their API usage up-to-date before expanding the surface area of usage, which may or may not be desirable for you.

data/docs/api.md

@@ -0,0 +1,106 @@
+# REST API
+We believe every SaaS application should have an API and [webhooks](/docs/webhooks/outgoing.md) available to users, so Bullet Train aims to help automate the creation of a production-grade REST API using Rails-native tooling and provides a forward-thinking strategy for its long-term maintenance.
+
+## Background
+Vanilla Rails scaffolding actually provides simple API functionality out-of-the-box: You can append `.json` to the URL of any scaffold and it will render a JSON representation instead of an HTML view. This functionality continues to work in Bullet Train, but our API implementation also builds on this simple baseline using the same tools with additional organization and some new patterns. 
+
+## Goals
+
+### Zero-Effort API
+As with vanilla Rails scaffolding, Super Scaffolding automatically generates your API as you scaffold new models, and unlike vanilla Rails scaffolding, it will automatically keep it up-to-date as you scaffold additional attributes onto your models.
+
+### Versioning by Default
+By separating out and versioning API controllers, views, routes, and tests, Bullet Train provides [a methodology and tooling](/docs/api/versioning.md) to help ensure that once users have built against your API, changes in the structure of your domain model and API don't unexpectedly break existing integrations. You can [read more about API versioning](/docs/api/versioning.md).
+
+### Standard Rails Tooling
+APIs are built using standard Rails tools like `ActiveController::API`, [Strong Parameters](https://api.rubyonrails.org/classes/ActionController/StrongParameters.html), `config/routes.rb`, and [Jbuilder](https://github.com/rails/jbuilder). Maintaining API endpoints doesn't require special knowledge and feels like regular Rails development.
+
+### Outsourced Authentication
+In the same way we've adopted [Devise](https://github.com/heartcombo/devise) for best-of-breed and battle-tested authentication on the browser side, we've adopted [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper) for best-of-breed and battle-tested authentication on the API side.
+
+### DRY Authorization Logic
+Because our API endpoints are standard Rails controllers, they're able to leverage the exact same [permissions definitions and authorization logic](https://github.com/bullet-train-co/bullet_train-base/blob/main/docs/permissions.md) as our account controllers.
+
+## Structure
+Where vanilla Rails uses a single controller in `app/controllers` for both in-browser and API requests, Bullet Train splits these into two separate controllers, one in `app/controllers/account` and another in `app/controllers/api/v1`, although a lot of logic is shared between the two.
+
+API endpoints are defined in three parts:
+
+1. Routes are defined in `config/routes/api/v1.rb`.
+2. Controllers are defined in the `app/controllers/api/v1` directory.
+3. Jbuilder views are defined in the `app/views/api/v1` directory.
+
+## "API First" and Supporting Account Controllers
+As previously mentioned, there is a lot of shared logic between account and API controllers. Importantly, there are a couple of responsbilities that are implemented "API first" in API controllers and then utilized by account controllers.
+
+### Strong Parameters
+The primary definition of Strong Parameters for a given resource is defined in the most recent version of the API controller and included from there by the account controller. In account controllers, where you might expect to see a Strong Parameters definition, you'll see the following instead:
+
+```ruby
+include strong_parameters_from_api
+```
+
+> This may feel counter-intuitive to some developers and you might wonder why we don't flip this around and have the primary definition in the account controller and have the API controller delegate to it. The answer is a pragmatic one: creating and maintaining the defintion of Strong Paramters in the API controller means it gets automatically frozen in time should you ever need to [bump your API version number](/api/docs/versioning.md). We probably _could_ accomplish this if things were the other way around, but it wouldn't happen automatically.
+
+If by chance there are additional attributes that should be permitted or specific logic that needs to be run as part of the account controller (or inversely, only in the API controller), you can specify that in the controller like so:
+
+```ruby
+def permitted_fields
+  [:some_specific_attribute]
+end
+
+def permitted_arrays
+  {some_collection: []}
+end
+
+def process_params(strong_params)
+  assign_checkboxes(strong_params, :some_checkboxes)
+  strong_params
+end
+```
+
+### Delegating `.json` View Rendering on Account Controllers
+
+In Bullet Train, when you append `.json` to an account URL, the account controller doesn't actually have any `.json.jbuilder` templates in its view directory within `app/views/account`. Instead, by default the controller is configured to delegate the JSON rendering to the corresponding Jbuilder templates in the most recent version of the API, like so:
+
+```ruby
+# GET /account/projects/:id or /account/projects/:id.json
+def show
+  delegate_json_to_api
+end
+```
+
+## Usage Example
+First, provision a platform application in section titled "Your Applications" in the "Developers" menu of the application. When you create a new platform application, an access token that doesn't automatically expire will be automatically provisioned along with it. You can then use the access token to hit the API, as seen in the following Ruby-based example:
+
+```ruby
+require 'net/http'
+require 'uri'
+
+# Configure an API client.
+client = Net::HTTP.new('localhost', 3000)
+
+headers = {
+  "Content-Type" => "application/json",
+  "Authorization" => "Bearer GfNLkDmzOTqAacR1Kqv0VJo7ft2TT-S_p8C6zPDBFhg"
+}
+
+# Fetch the team details.
+response = client.get("/api/v1/teams/1", headers)
+
+# Parse response.
+team = JSON.parse(response.body)
+
+# Update team name.
+team["name"] = "Updated Team Name"
+
+# Push the update to the API.
+# Note that the team attributes are nested under a `team` key in the JSON body.
+response = client.patch("/api/v1/teams/1", {team: team}.to_json, headers)
+```
+
+## Advanced Topics
+ - [API Versioning](/docs/api/versioning.md)
+
+## A Note About Other Serializers and API Frameworks
+In early versions of Bullet Train we made the decision to adopt a specific serialization library, [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers) and in subsequent versions we went as far as to adopt an entire third-party framework ([Grape](https://github.com/ruby-grape/grape)) and a third-party API specification ([JSON:API](https://jsonapi.org)). We now consider it out-of-scope to try and make such decisions on behalf of developers. Support for them in Bullet Train applications and in Super Scaffolding could be created by third-parties.

data/docs/index.md

@@ -40,11 +40,12 @@
  - [Stripe](/docs/billing/stripe.md)
 
 ## Integration
- - [OAuth Providers](/docs/oauth.md)
  - [REST API](/docs/api.md)
+ - [Zapier](/docs/zapier.md)
+ - [OAuth Providers](/docs/oauth.md)
  - [Outgoing Webhooks](/docs/webhooks/outgoing.md)
  - [Incoming Webhooks](/docs/webhooks/incoming.md)
-
+ 
 ## Add-Ons
  - [Font Awesome Pro](/docs/font-awesome-pro.md)
 

data/docs/zapier.md

@@ -0,0 +1,46 @@
+# Integrating with Zapier
+Bullet Train provides out-of-the-box support for Zapier. New Bullet Train projects include a preconfigured Zapier CLI project that is ready to `zapier deploy`.
+
+## Background
+Zapier was designed to take advantage of an application's existing [REST API](/docs/api.md), [outgoing webhook capabilities](/docs/webhooks/outgoing.md), and OAuth2 authorization workflows. Thankfully for us, Bullet Train provides the first two and pre-configures Doorkeeper to provide the latter. We also have an smooth OAuth2 connection workflow that accounts for the mismatch between the user-based OAuth2 standard and team-based multitenancy.
+
+## Prerequitesites
+ - You must be developing in an environment with [tunneling enabled](/docs/tunneling.md).
+
+## Getting Started in Development
+First, install the Zapier CLI tooling and deploy:
+
+```
+cd zapier
+yarn install
+zapier login
+zapier register
+zapier push
+```
+
+Once the application is registered in your account, you can re-run seeds in your development environment and it will create a `Platform::Application` record for Zapier:
+
+```
+cd ..
+rake db:seed
+```
+
+When you do this for the first time, it will output some credentials for you to go back and configure for the Zapier application, like so:
+
+```
+cd zapier
+zapier env:set 1.0.0 \
+  BASE_URL=https://andrewculver.ngrok.io \
+  CLIENT_ID=... \
+  CLIENT_SECRET=...
+cd ..
+```
+
+You're done and can now test creating Zaps that react to example objects being created or create example objects based on other triggers.
+
+## Deploying in Production
+We haven't figured out a good suggested process for breaking out development and production versions of the Zapier application yet, but we'll update this section when we have.
+
+## Future Plans
+ - Extend Super Scaffolding to automatically add new resources to the Zapier CLI project. For now you have to extend the Zapier CLI definitions manually.
+

data/lib/bullet_train/version.rb

@@ -1,3 +1,3 @@
 module BulletTrain
-  VERSION = "1.2.4"
+  VERSION = "1.2.6"
 end

data/lib/tasks/bullet_train_tasks.rake

@@ -91,13 +91,15 @@ namespace :bullet_train do
       puts ""
     end
 
+    framework_packages = I18n.t("framework_packages")
+
     # Process any flags that were passed.
     if arguments[:all_options].present?
       flags_with_values = []
 
       arguments[:all_options].split(/\s+/).each do |option|
         if option.match?(/^--/)
-          flags_with_values << {flag: option.gsub(/^--/, "").to_sym, values: []}
+          flags_with_values << {flag: option, values: []}
         else
           flags_with_values.last[:values] << option
         end
@@ -105,34 +107,27 @@ namespace :bullet_train do
 
       if flags_with_values.any?
         flags_with_values.each do |process|
-          if process[:flag] == :link || process[:flag] == :reset
-            packages = process[:values]
-
-            gemfile_lines = File.readlines("./Gemfile")
-            new_lines = gemfile_lines.map do |line|
-              packages.each do |package|
-                if line.match?(package)
-                  original_path = "gem \"bullet_train#{"-" + package if package}\""
-                  local_path = "gem \"bullet_train#{"-" + package if package}\", path: \"local/bullet_train#{"-" + package if package}\""
-
-                  case process[:flag]
-                  when :link
-                    line.gsub!(original_path, local_path)
-                    puts "Setting local '#{package}' package to the Gemfile...".blue
-                    break
-                  when :reset
-                    line.gsub!(local_path, original_path)
-                    puts "Resetting '#{package}' package in the Gemfile...".blue
-                    break
-                  end
-                end
-              end
-
-              line
-            end
-
-            File.write("./Gemfile", new_lines.join)
-            system "bundle install"
+          case process[:flag]
+          when "--help"
+            puts "bin/hack: Clone bullet_train-core and link up gems (will only link up gems if already cloned).".blue
+            puts "bin/hack --link: Link all of your Bullet Train gems to `local/bullet_train-core`".blue
+            puts "bin/hack --reset: Resets all of your gems to their original definition.".blue
+            puts "bin/hack --watch-js: Watches for any changes in JavaScript files gems that have an npm package.".blue
+            puts "bin/hack --clean-js: Resets all of your npm packages from `local/bullet_train-core` to their original definition".blue
+            exit
+          when "--link", "--reset"
+            set_core_gems(process[:flag], framework_packages)
+            stream "bundle install"
+          when "--watch-js"
+            set_npm_packages(process[:flag], framework_packages)
+
+            puts "Proceeding to reset your Bullet Train npm packages according to your root directory's `package.json`.".yellow
+            puts "If you press `Ctrl + C` before the process completely exits, just run `bin/hack --clean-js`".yellow
+            set_npm_packages("--clean-js", framework_packages)
+            break
+          when "--clean-js"
+            set_npm_packages(process[:flag], framework_packages)
+            break
           end
         end
 
@@ -140,123 +135,147 @@ namespace :bullet_train do
       end
     end
 
-    framework_packages = I18n.t("framework_packages")
+    puts "Welcome! Let's get hacking.".blue
 
-    puts "Which framework package do you want to work on?".blue
-    puts ""
-    framework_packages.each do |gem, details|
-      puts "  #{framework_packages.keys.find_index(gem) + 1}. #{gem}".blue
-    end
-    puts ""
-    puts "Enter a number below and hit <Enter>:".blue
-    number = $stdin.gets.chomp
+    # Adding these flags enables us to execute git commands in the gem from our starter repo.
+    work_tree_flag = "--work-tree=local/bullet_train-core"
+    git_dir_flag = "--git-dir=local/bullet_train-core/.git"
 
-    gem = framework_packages.keys[number.to_i - 1]
+    if File.exist?("local/bullet_train-core")
+      puts "We found the repository in `local/bullet_train-core`. We will try to use what's already there.".yellow
+      puts ""
 
-    if gem
-      details = framework_packages[gem]
-      package = details[:git].split("/").last
+      git_status = `git #{work_tree_flag} #{git_dir_flag} status`
+      unless git_status.match?("nothing to commit, working tree clean")
+        puts "This package currently has uncommitted changes.".red
+        puts "Please make sure the branch is clean and try again.".red
+        exit
+      end
 
-      puts "OK! Let's work on `#{gem}` together!".green
-      puts ""
+      current_branch = `git #{work_tree_flag} #{git_dir_flag} branch`.split("\n").select { |branch_name| branch_name.match?(/^\*\s/) }.pop.gsub(/^\*\s/, "")
+      unless current_branch == "main"
+        puts "Previously on #{current_branch}.".blue
+        puts "Switching local/bullet_train-core to main branch.".blue
+        stream("git #{work_tree_flag} #{git_dir_flag} checkout main")
+      end
 
-      if File.exist?("local/#{package}")
-        puts "We found the repository in `local/#{package}`. We will try to use what's already there.".yellow
-        puts ""
+      puts "Updating the main branch with the latest changes.".blue
+      stream("git #{work_tree_flag} #{git_dir_flag} pull origin main")
+    else
+      # Use https:// URLs when using this task in Gitpod.
+      stream "git clone #{(`whoami`.chomp == "gitpod") ? "https://github.com/" : "git@github.com:"}/bullet-train-co/bullet_train-core.git local/bullet_train-core"
+    end
 
-        # Adding these flags enables us to execute git commands in the gem from our starter repo.
-        work_tree_flag = "--work-tree=local/#{package}"
-        git_dir_flag = "--git-dir=local/#{package}/.git"
+    stream("git #{work_tree_flag} #{git_dir_flag} fetch")
+    stream("git #{work_tree_flag} #{git_dir_flag} branch -r")
+    puts "The above is a list of remote branches.".blue
+    puts "If there's one you'd like to work on, please enter the branch name and press <Enter>.".blue
+    puts "If not, just press <Enter> to continue.".blue
+    input = $stdin.gets.strip
+    unless input.empty?
+      puts "Switching to #{input.gsub("origin/", "")}".blue # TODO: Should we remove origin/ here if the developer types it?
+      stream("git #{work_tree_flag} #{git_dir_flag} checkout #{input}")
+    end
 
-        git_status = `git #{work_tree_flag} #{git_dir_flag} status`
-        unless git_status.match?("nothing to commit, working tree clean")
-          puts "This package currently has uncommitted changes.".red
-          puts "Please make sure the branch is clean and try again.".red
-          exit
-        end
+    # Link all of the local gems to the current Gemfile.
+    puts "Now we'll try to link up the Bullet Train core repositories in the `Gemfile`.".blue
+    set_core_gems("--link", framework_packages)
 
-        current_branch = `git #{work_tree_flag} #{git_dir_flag} branch`.split("\n").select { |branch_name| branch_name.match?(/^\*\s/) }.pop.gsub(/^\*\s/, "")
-        unless current_branch == "main"
-          puts "Previously on #{current_branch}.".blue
-          puts "Switching local/#{package} to main branch.".blue
-          stream("git #{work_tree_flag} #{git_dir_flag} checkout main")
-        end
+    puts ""
+    puts "Now we'll run `bundle install`.".blue
+    stream "bundle install"
 
-        puts "Updating the main branch with the latest changes.".blue
-        stream("git #{work_tree_flag} #{git_dir_flag} pull origin main")
-      else
-        # Use https:// URLs when using this task in Gitpod.
-        stream "git clone #{(`whoami`.chomp == "gitpod") ? "https://github.com/" : "git@github.com:"}#{details[:git]}.git local/#{package}"
-      end
+    puts ""
+    puts "We'll restart any running Rails server now.".blue
+    stream "rails restart"
 
-      stream("git #{work_tree_flag} #{git_dir_flag} fetch")
-      stream("git #{work_tree_flag} #{git_dir_flag} branch -r")
-      puts "The above is a list of remote branches.".blue
-      puts "If there's one you'd like to work on, please enter the branch name and press <Enter>.".blue
-      puts "If not, just press <Enter> to continue.".blue
-      input = $stdin.gets.strip
-      unless input.empty?
-        puts "Switching to #{input.gsub("origin/", "")}".blue # TODO: Should we remove origin/ here if the developer types it?
-        stream("git #{work_tree_flag} #{git_dir_flag} checkout #{input}")
-      end
+    puts ""
+    puts "OK, we're opening bullet_train-core in your IDE, `#{ENV["IDE"] || "code"}`. (You can configure this with `export IDE=whatever`.)".blue
+    `#{ENV["IDE"] || "code"} local/bullet_train-core`
+    puts ""
 
-      glob = if package == "bullet_train-core"
-        ", glob: \"#{gem}/#{gem}.gemspec\""
-      end
+    puts "Bullet Train has a few npm packages, so we will and install those now.".blue
+    puts "We will also watch for any changes in your JavaScript files and recompile as we go.".blue
+    puts "When you're done, you can hit <Control + C> and we'll clean all off this up.".blue
+    puts ""
+    set_npm_packages("--watch-js", framework_packages)
 
-      puts ""
-      puts "Now we'll try to link up that repository in the `Gemfile`.".blue
-      if `cat Gemfile | grep "gem \\\"#{gem}\\\", path: \\\"local/#{package}\\\""`.chomp.present?
-        puts "This gem is already linked to a checked out copy in `local` in the `Gemfile`.".green
-      elsif `cat Gemfile | grep "gem \\\"#{gem}\\\","`.chomp.present?
-        puts "This gem already has some sort of alternative source configured in the `Gemfile`.".yellow
-        puts "We can't do anything with this. Sorry! We'll proceed, but you have to link this package yourself.".red
-      elsif `cat Gemfile | grep "gem \\\"#{gem}\\\""`.chomp.present?
-        puts "This gem is directly present in the `Gemfile`, so we'll update that line.".green
-        text = File.read("Gemfile")
-        new_contents = text.gsub(/gem "#{gem}"/, "gem \"#{gem}\", path: \"local/#{package}\"#{glob}")
-        File.open("Gemfile", "w") { |file| file.puts new_contents }
-      else
-        puts "This gem isn't directly present in the `Gemfile`, so we'll add it temporarily.".green
-        File.open("Gemfile", "a+") { |file|
-          file.puts
-          file.puts "gem \"#{gem}\", path: \"local/#{package}\"#{glob} # Added by `bin/develop`."
-        }
+    # Clean up the npm packages after the developer enters `Ctrl + C`.
+    puts "Cleaning up npm packages...".blue
+    puts "If you cancel out of this process early, just run `bin/hack --clean-js` to revert to your original npm packages.".blue
+    set_npm_packages("--clean-js", framework_packages)
+
+    puts ""
+    puts "OK, here's a list of things this script still doesn't do you for you:".yellow
+    puts "1. It doesn't clean up the repository that was cloned into `local`.".yellow
+    puts "2. Unless you remove it, it won't update that repository the next time you link to it.".yellow
+  end
+
+  # Pass "--link" or "--reset" as a flag to set the gems.
+  def set_core_gems(flag, framework_packages)
+    packages = framework_packages.keys
+    gemfile_lines = File.readlines("./Gemfile")
+    new_lines = gemfile_lines.map do |line|
+      packages.each do |package|
+        if line.match?(/"#{package}"/)
+          original_path = "gem \"#{package}\""
+          local_path = "gem \"#{package}\", path: \"local/bullet_train-core/#{package}\""
+
+          case flag
+          when "--link"
+            if `cat Gemfile | grep "gem \\\"#{package}\\\", path: \\\"local/#{package}\\\""`.chomp.present?
+              puts "#{package} is already linked to a checked out copy in `local` in the `Gemfile`.".green
+            elsif `cat Gemfile | grep "gem \\\"#{package}\\\","`.chomp.present?
+              puts "#{package} already has some sort of alternative source configured in the `Gemfile`.".yellow
+              puts "We can't do anything with this. Sorry! We'll proceed, but you have to link this package yourself.".red
+            elsif `cat Gemfile | grep "gem \\\"#{package}\\\""`.chomp.present?
+              puts "#{package} is directly present in the `Gemfile`, so we'll update that line.".green
+              line.gsub!(original_path, local_path)
+            end
+            break
+          when "--reset"
+            line.gsub!(local_path, original_path)
+            puts "Resetting '#{package}' package in the Gemfile...".blue
+            break
+          end
+        end
       end
+      line
+    end
 
-      puts ""
-      puts "Now we'll run `bundle install`.".blue
-      stream "bundle install"
+    File.write("./Gemfile", new_lines.join)
+  end
 
-      puts ""
-      puts "We'll restart any running Rails server now.".blue
-      stream "rails restart"
+  def set_npm_packages(flag, framework_packages)
+    packages = framework_packages.select { |k, v| v[:npm].present? }.compact
 
-      puts ""
-      puts "OK, we're opening that package in your IDE, `#{ENV["IDE"] || "code"}`. (You can configure this with `export IDE=whatever`.)".blue
-      `#{ENV["IDE"] || "code"} local/#{package}`
+    if flag == "--watch-js"
+      puts "Make sure your server is running before proceeding. When you're ready, press <Enter>".blue
+      $stdin.gets.strip
 
+      puts "Linking npm packages...".blue
       puts ""
-      if details[:npm]
-        puts "This package also has an npm package, so we'll link that up as well.".blue
-        stream "cd local/#{gem} && yarn install && npm_config_yes=true npx yalc link && cd ../.. && npm_config_yes=true npx yalc link \"#{details[:npm]}\""
 
+      yarn_watch_command = []
+      packages.each do |package_name, details|
+        puts "Linking JavaScript for #{package_name}".blue
+        stream "cd local/bullet_train-core/#{package_name} && yarn install && npm_config_yes=true && npx yalc link && cd ../../.. && npm_config_yes=true npx yalc link \"#{details[:npm]}\""
+        puts "#{package_name} has been linked.".blue
         puts ""
-        puts "And now we're going to watch for any changes you make to the JavaScript and recompile as we go.".blue
-        puts "When you're done, you can hit <Control + C> and we'll clean all off this up.".blue
-        stream "cd local/#{gem} && yarn watch"
-      else
-        puts "This package has no npm package, so we'll just hang out here and do nothing. However, when you hit <Enter> here, we'll start the process of cleaning all of this up.".blue
-        $stdin.gets
+        yarn_watch_command << "yarn --cwd local/bullet_train-core/#{package_name} watch"
       end
 
+      # We use `&` to run the processes in parallel.
+      puts "Preparing to watch changes".blue
+      stream yarn_watch_command.join(" & ")
+    elsif flag == "--clean-js"
+      puts "Resetting packages to their original path".blue
       puts ""
-      puts "OK, here's a list of things this script still doesn't do you for you:".yellow
-      puts "1. It doesn't clean up the repository that was cloned into `local`.".yellow
-      puts "2. Unless you remove it, it won't update that repository the next time you link to it.".yellow
-    else
-      puts ""
-      puts "Invalid option, \"#{number}\". Try again.".red
+
+      packages.each do |package_name, details|
+        system "yarn yalc remove #{details[:npm]}"
+        system "yarn add #{details[:npm]}"
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bullet_train
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.6
 platform: ruby
 authors:
 - Andrew Culver
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-17 00:00:00.000000000 Z
+date: 2022-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard
@@ -626,6 +626,8 @@ files:
 - db/migrate/20211020200855_add_doorkeeper_application_to_memberships.rb
 - db/migrate/20211027002944_add_doorkeeper_application_to_users.rb
 - docs/action-models.md
+- docs/api.md
+- docs/api/versioning.md
 - docs/application-options.md
 - docs/authentication.md
 - docs/billing/stripe.md
@@ -662,6 +664,7 @@ files:
 - docs/upgrades.md
 - docs/webhooks/incoming.md
 - docs/webhooks/outgoing.md
+- docs/zapier.md
 - lib/bullet_train.rb
 - lib/bullet_train/core_ext/string_emoji_helper.rb
 - lib/bullet_train/engine.rb