heroku_tool 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4a4df4ad020a5fcd4575232f8654db71c229fc14a1b68d502ee86a43225ced7
+  data.tar.gz: 6c6bf214ab072c875b5c5d80d79b2021f2483f7c1c4a0fe16363a033d2e6ac7a
+SHA512:
+  metadata.gz: ef2ccc7731972da7546f744c90bfee348fcba8ed56d46a25683f0a6ab9306839f4778da7abe573e6905e949b105f96f4a834c79acb1f6ad6655c59cbc9824e4c
+  data.tar.gz: 06f6742e8c5567555db6484da17b4433c3abe95d6f168603982a66e11c83216f6cf523eed85d3da5209402058dcff97a52615527a11a44c29549c98419064b4f

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/Gemfile.lock
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.7
+before_install: gem install bundler -v 1.17.3

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## v0.4.0
+
+Dropped thor < 1.0
+
+## v0.3.0
+
+Works with thor <= 1.0
+
+## v0.2.0
+
+Now assumes a default of main as the main branch.
+Works after heroku git has had its repo reset (e.g. after switching from master to main, see https://help.heroku.com/O0EXQZTA/how-do-i-switch-branches-from-master-to-main).

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at tim@red56.uk. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in heroku_tool.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Tim Diggins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,123 @@
+# HerokuTool
+
+Tool for configurable one-shot deployment and db managment with heroku and rails
+
+If you're using continuous deployment with pipelines in Heroku, you won't need this. However if that style doesn't work, then this may allow you to manage databases and deployment with more control but less hassle.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'heroku_tool'
+```
+
+(you can add it to development/test only if you want)
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install heroku_tool
+
+## Configuration
+
+> TODO: Some of these manual configuration steps, would be nicer to make a bit more automatic perhaps by making this a Rails engine.
+
+1) Your database configuration (config/database.yml) needs to have a username if you want to use the db configurations
+
+2) Append `load "heroku_tool/tasks/db_drop_all_tables.rake"` to the end of Rakefile (see lib/templates/Rakefile if you are adding this gem in development/test only)
+
+3) Copy templates into codebase:
+
+       cp $(bundle show heroku_tool)/templates/heroku.thor ./lib/tasks
+       cp $(bundle show heroku_tool)/templates/heroku_targets.yml ./config
+
+4) update heroku_targets.yml with your staging and production targets. 
+  My set up for this is to have staging deploy the local version, but production 
+  deploy the origin/main.
+
+   NB: master vs main
+   heroku-tool (as of 0.2.0) assumes the new current standard of main as the main branch, but if you're on the older standard of "master" then adjust your deploy refs to origin/master and the heroku_target_ref: in defaults to be ref/heads/master
+   
+      > TODO: more detail
+ 
+5) You may want to set up a smoke test that your heroku targets are valid
+ 
+       require "heroku_tool/heroku_targets"
+       
+       RSpec.describe "heroku_targets.yml" do
+         it "is valid (smoke test)" do 
+           HerokuTool::HerokuTargets.from_file(Rails.root.join("config/heroku_targets.yml"))
+         end
+       end
+
+## Usage
+
+### Deploy 
+
+Deploy the latest with db migrate *(but see below) during maintenance
+
+    thor heroku:deploy staging
+
+or without maintenance*
+
+    thor heroku:deploy staging --no-maintenance
+
+or without migrating*
+
+    thor heroku:deploy staging --no-migrate
+    
+or a specific tag/branch
+
+    thor heroku:deploy staging hotfix-branch
+
+*Note on db:migrate:
+
+It is very possible to run migrations as part of the heroku release phase:
+* https://mentalized.net/journal/2017/04/22/run-rails-migrations-on-heroku-deploy/
+* https://devcenter.heroku.com/articles/release-phase#design-considerations
+
+In this case you should set `migrate_in_release_phase: true` in your defaults (see templates/heroku_targets.yml)
+and you won't run migrate as a separate step.
+
+### Sync
+
+Sync a database down from remote to local 
+
+    thor heroku:sync:grab -f staging
+    # when it finishes
+    rake db:drop_all_tables && thor heroku:sync:from_dump -f staging
+
+_FYI rake db:drop_all_tables is handy as it doesn't require you to disconnect any running processes from the database._
+
+Copy production db to staging
+
+    thor heroku:sync:to staging -f production
+
+NB: this won't work from a staging to a production environment (failsafe)
+    
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+Ensure standards before PR:
+
+    bundle exec standardrb --fix
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/red56/heroku_tool. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the HerokuTool project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/red56/heroku_tool/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "heroku_tool"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/heroku_tool.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "heroku_tool/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "heroku_tool"
+  spec.version = HerokuTool::VERSION
+  spec.authors = ["Tim Diggins"]
+  spec.email = ["tim@red56.uk"]
+
+  spec.summary = "Tool for configurable one-shot deployment and db managment with heroku and rails"
+  spec.homepage = "https://github.com/red56/heroku_tool"
+  spec.license = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path("..", __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "thor", "~> 1.0"
+  spec.add_dependency "activesupport"
+
+  spec.add_development_dependency "rake", ">= 12.3.3"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "standard", "~> 0.4.1"
+end

data/lib/heroku_tool/db_configuration.rb

@@ -0,0 +1,33 @@
+# NB need to specify a username in the database.yml if you want to use any of these commands
+module HerokuTool
+  class DbConfiguration
+    def config
+      db_config_from_file = ERB.new(File.read("config/database.yml")).result
+      @config ||= YAML.safe_load(db_config_from_file, [], [], true)
+    end
+
+    def generate_drop_tables_sql
+      sql = %(select 'DROP TABLE IF EXISTS \\"' || tablename || '\\" CASCADE;' from pg_tables where schemaname = 'public')
+      %(psql #{user_arg} #{database} -t -c "#{sql}")
+    end
+
+    def user_arg
+      username = db_config["username"]
+      username.present? && "-U #{username}" || ""
+    end
+
+    def database
+      db_config["database"]
+    end
+
+    private
+
+    def db_config
+      config[env]
+    end
+
+    def env
+      ENV["RAILS_ENV"] || "development"
+    end
+  end
+end

data/lib/heroku_tool/heroku_targets.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "active_support/all"
+require "yaml"
+
+module HerokuTool
+  class HerokuTargets
+    class << self
+      def from_string(heroku_targets_yml)
+        new(YAML.safe_load(heroku_targets_yml))
+      end
+
+      def from_file(yaml_file)
+        new(YAML.safe_load(File.read(yaml_file)))
+      end
+    end
+
+    attr_reader :targets, :staging_targets
+
+    DEFAULTS_KEY = "_defaults"
+
+    def initialize(targets_hash)
+      defaults = if targets_hash.keys.first == DEFAULTS_KEY
+        targets_hash.delete(DEFAULTS_KEY)
+      else
+        {}
+      end
+      specified = targets_hash.collect { |name, values|
+        heroku_target = HerokuTarget.new(defaults.merge(values), name)
+        [heroku_target.heroku_app, heroku_target]
+      }
+      built_in = [["local", LocalProxy.new(defaults)]]
+      @targets = TargetsContainer[(specified + built_in)].freeze
+      @staging_targets = TargetsContainer[@targets.select { |_name, target| target.staging? }]
+    end
+
+    class TargetsContainer < HashWithIndifferentAccess
+      def [](key)
+        return super if key?(key)
+        values.each do |value|
+          return value if value.name.to_s == key.to_s
+        end
+        nil
+      end
+    end
+
+    class HerokuTarget
+      attr_reader :name
+
+      def initialize(values_hash, name = nil)
+        @values = values_hash.symbolize_keys.freeze
+        @name = name.to_sym if name
+        %i[heroku_app git_remote deploy_ref].each do |required_name|
+          raise required_value(required_name) unless @values[required_name] || local?
+        end
+      end
+
+      def required_value(required_name)
+        ArgumentError.new("please specify '#{required_name}:' ")
+      end
+
+      def staging?
+        @values[:staging]
+      end
+
+      def local?
+        false
+      end
+
+      def display_name
+        @values[:display_name] || @values[:heroku_app]
+      end
+
+      def heroku_app
+        @values[:heroku_app]
+      end
+
+      def database_url
+        @values[:database_url]
+      end
+
+      def git_remote
+        @values[:git_remote]
+      end
+
+      def deploy_ref
+        @values[:deploy_ref]
+      end
+
+      def db_color
+        @values[:db_color] || "DATABASE"
+      end
+
+      def repository
+        @values[:repository] || raise(required_value(:repository))
+      end
+
+      def heroku_target_ref
+        @values[:heroku_target_ref] || "refs/heads/main"
+      end
+
+      def migrate_in_release_phase
+        @values[:migrate_in_release_phase]
+      end
+
+      def to_s
+        display_name
+      end
+
+      def dump_filename
+        File.expand_path("tmp/latest_#{heroku_app}_backup.dump")
+      end
+
+      def trackable_release_stage
+        @values[:trackable_release_stage].presence || (staging? ? "staging" : "production")
+      end
+    end
+
+    class LocalProxy < HerokuTarget
+      def initialize(defaults)
+        super(defaults.merge(staging: true, heroku_app: "local"), "local")
+      end
+
+      def local?
+        true
+      end
+    end
+  end
+end

data/lib/heroku_tool/tasks/db_drop_all_tables.rake

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+namespace :db do
+  desc "drop all tables without worrying about concurrent accesses"
+  task drop_all_tables: :environment do
+    require File.expand_path("../../db_configuration.rb", __FILE__)
+    abort("Don't run this on production") if Rails.env.production?
+
+    db_config = HerokuTool::DbConfiguration.new
+    generate_drop_tables_sql = db_config.generate_drop_tables_sql
+    cmd_string = %(#{generate_drop_tables_sql} | psql #{db_config.user_arg} #{db_config.database})
+    puts cmd_string
+    system(cmd_string)
+  end
+end

data/lib/heroku_tool/tasks/heroku.thor

@@ -0,0 +1,459 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "../db_configuration"
+require_relative "../heroku_targets"
+require_relative "../thor_utils"
+
+class Heroku < Thor
+  module Configuration
+    class << self
+      def platform_maintenance_urls(asset_host)
+        time = Time.now.strftime("%Y%m%d-%H%M-%S")
+        {
+          ERROR_PAGE_URL: "https://#{asset_host}/platform_error/#{time}",
+          MAINTENANCE_PAGE_URL: "https://#{asset_host}/platform_maintenance/#{time}"
+        }
+      end
+
+      def maintenance_mode_env_var
+        "X_HEROKU_TOOL_MAINTENANCE_MODE"
+      end
+
+      def app_revision_env_var
+        raise "choose between APP_REVISION and COMMIT_HASH"
+      end
+
+      def before_deploying(_instance, target, version, description: nil)
+        puts "about to deploy #{version} to #{target.name}"
+        puts "         #{description}" if description
+      end
+
+      def after_deploying(_instance, target, version, description: nil)
+        puts "deployed #{version} to #{target.name}"
+        puts "         #{description}" if description
+      end
+
+      def notify_of_deploy_tracking(running_thor_task, release_stage:, revision:, revision_describe:, repository:, target:, target_name:, deploy_ref:)
+        if ENV["BUGSNAG_API_KEY"].present?
+          running_thor_task.notify_bugsnag_of_deploy_tracking(deploy_ref, release_stage, repository, revision, revision_describe, target_name)
+        else
+          puts "can't notify of deploy tracking: env var not present: BUGSNAG_API_KEY"
+        end
+      end
+
+      def after_sync_down(instance)
+        # could add source ?
+        instance.puts_and_system "rake db:migrate"
+        instance.puts_and_system "rake db:test:prepare"
+      end
+
+      def after_sync_to(instance, target)
+        # could add source ?
+        instance.puts_and_system %(heroku run rake db:migrate -a #{target.heroku_app})
+      end
+    end
+  end
+
+  module Shared
+    attr_accessor :implied_source, :implied_target
+
+    include HerokuTool::ThorUtils
+
+    def self.exit_on_failure?
+      true
+    end
+
+    def lookup_heroku_staging(staging_target_name)
+      heroku_targets.staging_targets[staging_target_name] || raise_missing_target(staging_target_name, true)
+    end
+
+    def lookup_heroku(target_name)
+      heroku_targets.targets[target_name] || raise_missing_target(target_name, false)
+    end
+
+    def check_deploy_ref(deploy_ref, target = implied_target)
+      if deploy_ref && deploy_ref[0] == "-"
+        raise Thor::Error, "Invalid deploy ref '#{deploy_ref}'"
+      end
+
+      deploy_ref || target.deploy_ref
+    end
+
+    def raise_missing_target(target_name, staging)
+      if staging
+        description = "Staging target_name '#{target_name}'"
+        targets = heroku_targets.staging_targets.keys
+      else
+        description = "Target '#{target_name}'"
+        targets = heroku_targets.targets.keys
+      end
+      msg = "#{description} was not found. Valid targets are #{targets.collect { |t| "'#{t}'" }.join(",")}"
+      raise Thor::Error, msg
+    end
+
+    def heroku_targets
+      @heroku_targets ||= HerokuTool::HerokuTargets.from_file(File.expand_path("config/heroku_targets.yml"))
+    end
+
+    protected
+
+    def deploy_message(deploy_ref_describe, target = implied_target)
+      downtime = migrate_outside_of_release_phase?(target) ? "👷 There will be a very short maintenance downtime" : ""
+      message = <<-DEPLOY_MESSAGE
+     Deploying #{target.display_name} #{deploy_ref_describe}.
+     #{downtime} (in less than a minute from now).
+      DEPLOY_MESSAGE
+      message.gsub(/(\s|\n)+/, " ")
+    end
+
+    def migrate_outside_of_release_phase?(target = implied_target)
+      target.migrate_in_release_phase ? false : options[:migrate]
+    end
+
+    def maintenance_on(target = implied_target)
+      puts_and_system "heroku maintenance:on -a #{target.heroku_app}"
+      puts_and_system "heroku config:set #{Heroku::Configuration.maintenance_mode_env_var}=true -a #{target.heroku_app}"
+    end
+
+    def maintenance_off(target = implied_target)
+      puts_and_system "heroku maintenance:off -a #{target.heroku_app}"
+      puts_and_system "heroku config:unset #{Heroku::Configuration.maintenance_mode_env_var} -a #{target.heroku_app}"
+    end
+  end
+
+  include Shared
+
+  class_option :verbose, type: :boolean, aliases: "v", default: true
+  default_command :help
+
+  desc "configs", "collects configs as text files in tmp"
+
+  def configs
+    remote_targets = heroku_targets.targets.reject { |_name, target| target.local? }
+    remote_targets.each_with_index do |(_name, target), index|
+      print_output_progress(remote_targets, index)
+      cmd = "heroku config -s -a #{target.heroku_app} > tmp/config.#{target.heroku_app}.txt"
+      exec_with_clean_env(cmd)
+    end
+    print_output_progress(remote_targets)
+    puts ""
+  end
+
+  desc "details", "collects and prints some information local and each target"
+
+  def details
+    puts
+    details = heroku_targets.targets.map { |name, target|
+      next if target.local?
+
+      print "."
+      [
+        "Heroku #{name}",
+        "(versions suppressed -- takes too long)" || exec_with_clean_env("heroku run 'rails -v && ruby -v' -a #{target.heroku_app}"),
+        exec_with_clean_env("heroku releases -n 1 -a #{target.heroku_app}").split("\n").last
+      ]
+    }
+    puts
+    details << [
+      "Local",
+      exec_with_clean_env("rails -v && ruby -v"),
+      exec_with_clean_env("git describe --always")
+    ]
+    details.each do |n, v, d|
+      puts "-" * 80
+      puts n
+      puts "-" * 80
+      puts v
+      puts d
+    end
+  end
+
+  desc "deploy TARGET (REF)", "deploy the latest to TARGET (optionally give a REF like a tag to deploy)"
+  method_option :migrate, default: true, desc: "Run with migrations (unless part of release phase)", type: :boolean
+  method_option :maintenance, default: nil, desc: "Maintenance step", type: :boolean
+
+  def deploy(target_name, deploy_ref = nil)
+    self.implied_target = lookup_heroku(target_name)
+    deploy_ref = check_deploy_ref(deploy_ref, implied_target)
+    deploy_ref_description = deploy_ref_describe(deploy_ref)
+    maintenance = options[:maintenance].nil? && migrate_outside_of_release_phase?(implied_target) || options[:maintenance] || false
+    puts "Deploy #{deploy_ref_description} to #{implied_target} with migrate=#{implied_target.migrate_in_release_phase ? "(during release phase)" : migrate_outside_of_release_phase?(implied_target)} maintenance=#{maintenance} "
+
+    invoke :list_deployed, [target_name, deploy_ref], {}
+    message = deploy_message(deploy_ref_description)
+    Configuration.before_deploying(self, implied_target, deploy_ref_description)
+    set_message(target_name, message)
+    puts_and_system "git push -f #{implied_target.git_remote} #{deploy_ref}^{}:#{implied_target.heroku_target_ref}"
+
+    maintenance_on if maintenance
+    if migrate_outside_of_release_phase?
+      puts_and_system "heroku run rake db:migrate -a #{implied_target.heroku_app}"
+    end
+
+    puts_and_system %{heroku config:set #{Heroku::Configuration.app_revision_env_var}=$(git describe --always #{deploy_ref}) -a #{implied_target.heroku_app}}
+    if maintenance
+      maintenance_off
+    else
+      puts_and_system "heroku restart -a #{implied_target.heroku_app}"
+    end
+    set_message(target_name, nil)
+    Configuration.after_deploying(self, implied_target, deploy_ref_description)
+    deploy_tracking(target_name, deploy_ref)
+  end
+
+  desc "maintenance ON|OFF", "turn maintenance mode on or off"
+  method_option :target_name, aliases: "a", desc: "Target (app or remote)"
+
+  def maintenance(on_or_off)
+    self.implied_target = lookup_heroku(options[:target_name])
+    case on_or_off.upcase
+    when "ON"
+      maintenance_on
+    when "OFF"
+      maintenance_off
+    else
+      raise Thor::Error, "maintenance must be ON or OFF not #{on_or_off}"
+    end
+  end
+
+  desc "set_urls TARGET", "set and cache the error and maintenance page urls for TARGET"
+
+  def set_urls(target_name)
+    self.implied_target = lookup_heroku(target_name)
+    unless asset_host.presence
+      puts "asset host (ASSET_HOST) not found on #{implied_target.heroku_app}"
+      return
+    end
+    url_hash = Configuration.platform_maintenance_urls(asset_host)
+    url_hash.each do |_env, url|
+      puts_and_system "open #{url}"
+    end
+    puts_and_system(
+      "heroku config:set #{url_hash.map { |e, u| "#{e}=#{u}" }.join(" ")} -a #{implied_target.heroku_app}"
+    )
+  end
+
+  no_commands do
+    def asset_host(target = implied_target)
+      if target == implied_target
+        @asset_host ||= fetch_asset_host(target)
+      else
+        fetch_asset_host(target)
+      end
+    end
+
+    def get_config_env(target, env_var)
+      puts_and_exec("heroku config:get #{env_var} -a #{target.heroku_app}").strip.presence
+    end
+
+    def deploy_ref_describe(deploy_ref)
+      `git describe #{deploy_ref}`.strip
+    end
+
+    def notify_bugsnag_of_deploy_tracking(deploy_ref, release_stage, repository, revision, revision_describe, target_name)
+      api_key = ENV["BUGSNAG_API_KEY"]
+      data = %W[
+        apiKey=#{api_key}
+        releaseStage=#{release_stage}
+        repository=#{repository}
+        revision=#{revision}
+        appVersion=#{revision_describe}
+      ].join("&")
+      if api_key.blank?
+        puts "\n" + ("*" * 80) + "\n"
+        command = "curl -d #{data} http://notify.bugsnag.com/deploy"
+        puts command
+        puts "\n" + ("*" * 80) + "\n"
+        puts "NB: can't notify unless you specify BUGSNAG_API_KEY and rerun"
+        puts "  thor heroku:deploy_tracking #{target_name} #{deploy_ref}"
+      else
+        puts_and_system "curl -d \"#{data}\" http://notify.bugsnag.com/deploy"
+      end
+    end
+  end
+
+  desc "deploy_tracking TARGET (REF)", "set deploy tracking for TARGET and REF (used by deploy)"
+
+  def deploy_tracking(target_name, deploy_ref = nil)
+    self.implied_target = lookup_heroku(target_name)
+    deploy_ref = check_deploy_ref(deploy_ref)
+    revision = `git log -1 #{deploy_ref} --pretty=format:%H`
+    Heroku::Configuration.notify_of_deploy_tracking(
+      self,
+      deploy_ref: deploy_ref,
+      release_stage: implied_target.trackable_release_stage,
+      revision: revision,
+      target: implied_target,
+      target_name: target_name,
+      revision_describe: deploy_ref_describe(deploy_ref),
+      repository: implied_target.repository
+    )
+  end
+
+  include HerokuTool::ThorUtils
+  desc "set_message TARGET (MESSAGE)", "set message (no-op by default)"
+
+  def set_message(target_name, message = nil)
+    # no-op -- define as override
+  end
+
+  desc "list_deployed TARGET (DEPLOY_REF)", "list what would be deployed to TARGET (optionally specify deploy_ref)"
+
+  def list_deployed(target_name, deploy_ref = nil)
+    self.implied_target = lookup_heroku(target_name)
+    deploy_ref = check_deploy_ref(deploy_ref)
+    puts "------------------------------"
+    puts " Deploy to #{implied_target}:"
+    puts "------------------------------"
+    system_with_clean_env "git --no-pager log $(heroku config:get #{Heroku::Configuration.app_revision_env_var} -a #{implied_target.heroku_app})..#{deploy_ref}"
+    puts "------------------------------"
+  end
+
+  desc "about (TARGET)", "Describe available targets or one specific target"
+
+  def about(target_name = nil)
+    if target_name.nil?
+      puts "Targets: "
+      heroku_targets.targets.each_pair do |key, target|
+        puts " * #{key} (#{target})"
+      end
+    else
+      self.implied_target = lookup_heroku(target_name)
+      puts "Target #{target_name}:"
+      puts " * display_name: #{implied_target.display_name}"
+      puts " * heroku_app:   #{implied_target.heroku_app}"
+      puts " * git_remote:   #{implied_target.git_remote}"
+      puts " * deploy_ref:   #{implied_target.deploy_ref}"
+    end
+    puts
+    puts "(defined in config/heroku_targets.yml)"
+  end
+
+  class Sync < Thor
+    include Shared
+    class_option :from, type: :string, desc: "source target (production, staging...)", required: true, aliases: "f"
+
+    desc "down --from SOURCE_TARGET", "syncs db down from SOURCE_TARGET | thor heroku:sync -f production"
+
+    def down
+      invoke "grab", [], from: options[:from]
+      invoke "from_dump", [], from: options[:from]
+    end
+
+    desc "warn", "warn", hide: true
+
+    def warn
+      puts "should maybe 'rake db:drop_all_tables' first"
+      puts "if you have done some table-creating migrations that need tobe undone???"
+    end
+
+    desc "capture --from SOURCE_TARGET", "capture a backup (remotely) from SOURCE_TARGET", hide: true
+
+    def capture
+      source = lookup_heroku(options[:from])
+      capture_cmd = "heroku pg:backups:capture -a #{source.heroku_app}"
+      puts_and_system capture_cmd
+    end
+
+    desc "grab --from SOURCE_TARGET", "capture and download dump from SOURCE_TARGET", hide: true
+
+    def grab
+      invoke "capture", [], from: options[:from]
+      invoke "download", [], from: options[:from]
+    end
+
+    desc "download --from SOURCE_TARGET", "download latest db snapshot on source_target"
+
+    def download
+      source = lookup_heroku(options[:from])
+      download_cmd = "curl -o #{source.dump_filename} `heroku pg:backups:public-url -a #{source.heroku_app}`"
+      puts_and_system download_cmd
+    end
+
+    desc "from_dump --from SOURCE_TARGET", "make the db the same as the last target dump from SOURCE_TARGET"
+
+    method_option :just_restore, default: false, desc: "Just do restore without post-actions", type: :boolean
+
+    def from_dump
+      invoke "warn", [], from: options[:from]
+      source = lookup_heroku(options[:from])
+      rails_env = ENV["RAILS_ENV"] || "development"
+      db_config = HerokuTool::DbConfiguration.new.config[rails_env]
+      db_username = db_config["username"]
+      db = db_config["database"]
+      db_username_params = db_username.blank? && "" || "-U #{db_username}"
+      puts_and_system "pg_restore --verbose --clean --no-acl --no-owner -h localhost #{db_username_params} -d #{db} #{source.dump_filename}"
+      Configuration.after_sync_down(self) unless options[:just_restore]
+    end
+
+    desc "dump_to_tmp", "dump to tmp directory"
+    method_option(:from, type: :string, default: "local", desc: "heroku target (defaults to local)", required: false, aliases: "f")
+
+    def dump_to_tmp
+      source = lookup_heroku(options[:from])
+      dump_local(source.dump_filename)
+    end
+
+    desc "to STAGING_TARGET --from=SOURCE_TARGET", "push db onto STAGING_TARGET from SOURCE_TARGET"
+
+    def to(to_target_name)
+      self.implied_target = lookup_heroku_staging(to_target_name)
+      self.implied_source = lookup_heroku(options[:from])
+
+      maintenance_on # target, not source
+
+      puts_and_system %(
+        heroku pg:copy #{implied_source.heroku_app}::#{implied_source.db_color} #{implied_target.db_color} -a #{implied_target.heroku_app} --confirm #{implied_target.heroku_app}
+      )
+      Configuration.after_sync_to(self, implied_target) unless options[:just_copy]
+      puts_and_system %(heroku restart -a #{implied_target.heroku_app})
+      maintenance_off
+    end
+
+    private
+
+    def dump_local(dumpfilepath)
+      puts "dumping postgres to #{dumpfilepath}"
+      rails_env = ENV["RAILS_ENV"] || "development"
+      db_config = HerokuTool::DbConfiguration.new.config[rails_env]
+      db_username = db_config["username"]
+      db = db_config["database"]
+      system_with_clean_env "pg_dump --verbose --clean --no-acl --no-owner -h localhost -U #{db_username} --format=c #{db} > #{dumpfilepath}"
+    end
+  end
+
+  class Db < Thor
+    include Shared
+
+    desc "drop_all_tables on STAGING_TARGET", "drop all tables on STAGING_TARGET"
+
+    def drop_all_tables(staging_target_name)
+      self.implied_target = lookup_heroku_staging(staging_target_name)
+      generate_drop_tables_sql = `#{HerokuTool::DbConfiguration.new.generate_drop_tables_sql}`
+      cmd_string = %(heroku pg:psql -a #{implied_target.heroku_app} -c "#{generate_drop_tables_sql}")
+      puts_and_system(cmd_string)
+    end
+
+    desc "anonymize STAGING_TARGET", "run anonymization scripts on STAGING_TARGET"
+
+    def anonymize(staging_target_name)
+      self.implied_target = lookup_heroku_staging(staging_target_name)
+      puts_and_system %(
+        heroku run rake data:anonymize -a #{implied_target.heroku_app}
+      )
+    end
+  end
+
+  private
+
+  def fetch_asset_host(target)
+    get_config_env(target, "ASSET_HOST")
+  end
+
+  def print_output_progress(remote_targets, index = nil)
+    index ||= remote_targets.length
+    remainder = remote_targets.length - index
+    print "\routputting configs to tmp/config.*.txt: #{index}/#{remote_targets.count} ▕#{'██' * index}#{"  " * remainder}▏\r"
+  end
+end

data/lib/heroku_tool/thor_utils.rb

@@ -0,0 +1,37 @@
+module HerokuTool
+  module ThorUtils
+    def puts_and_system(cmd)
+      puts cmd
+      puts "-------------"
+      system_with_clean_env cmd
+      puts "-------------"
+    end
+
+    protected
+
+    def puts_and_exec(cmd)
+      puts cmd
+      exec_with_clean_env(cmd)
+    end
+
+    def system_with_clean_env(cmd)
+      if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+        Bundler.with_unbundled_env { system cmd }
+      elsif defined?(Bundler)
+        Bundler.with_clean_env { system cmd }
+      else
+        system cmd
+      end
+    end
+
+    def exec_with_clean_env(cmd)
+      if defined?(Bundler) && Bundler.respond_to?(:with_unbundled_env)
+        Bundler.with_unbundled_env { `#{cmd}` }
+      elsif defined?(Bundler)
+        Bundler.with_clean_env { `#{cmd}` }
+      else
+        `#{cmd}`
+      end
+    end
+  end
+end

data/lib/heroku_tool/version.rb

@@ -0,0 +1,3 @@
+module HerokuTool
+  VERSION = "0.4.0"
+end

data/lib/heroku_tool.rb

@@ -0,0 +1,7 @@
+require "heroku_tool/db_configuration"
+require "heroku_tool/heroku_targets"
+require "heroku_tool/version"
+
+module HerokuTool
+  class Error < StandardError; end
+end

data/templates/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require_relative "config/application"
+
+Rails.application.load_tasks
+
+begin
+  spec = Gem::Specification.find_by_name "heroku_tool"
+  load File.expand_path("lib/heroku_tool/tasks/db_drop_all_tables.rake", spec.gem_dir)
+rescue LoadError
+  # not loading db_drop_all_tables -- not defined in this environment?
+end

data/templates/heroku.thor

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+begin
+  require "thor"
+  spec = Gem::Specification.find_by_name "heroku_tool"
+  Thor::Util.load_thorfile(File.expand_path("lib/heroku_tool/tasks/heroku.thor", spec.gem_dir))
+rescue LoadError, StandardError
+  puts "Not loading HerokuTool"
+end
+
+# respecifying Heroku tasks
+class Heroku
+  module MyConfig
+    include HerokuTool::ThorUtils if defined?(HerokuTool)
+
+    def platform_maintenance_urls(asset_host)
+      time = Time.now.strftime("%Y%m%d-%H%M-%S")
+      {
+        ERROR_PAGE_URL: "https://#{asset_host}/platform_error/#{time}",
+        MAINTENANCE_PAGE_URL: "https://#{asset_host}/platform_maintenance/#{time}"
+      }
+    end
+
+    def maintenance_mode_env_var
+      "X_HEROKU_TOOL_MAINTENANCE_MODE"
+    end
+
+    # def notify_of_deploy_tracking(running_thor_task, release_stage:, revision:, revision_describe:, repository:, target:, target_name:, deploy_ref:)
+    # end
+
+    # def app_revision_env_var
+    #  "APP_REVISION"
+    # end
+    #
+    # def after_sync_down(instance)
+    #  super
+    #  instance.puts_and_system "rake dev:dev_data"
+    # end
+    #
+    # def after_sync_to(instance, target)
+    #  super
+    #  instance.puts_and_system %(heroku run rake dev:staging_data -a #{target.heroku_app})
+    # end
+    #
+    # def before_deploying(instance, target, version)
+    #   # override
+    # end
+    #
+    # def after_deploying(instance, target, version)
+    #   # override
+    # end
+  end
+
+  module Configuration
+    class << self
+      prepend MyConfig
+    end
+  end
+
+  # desc "set_message TARGET (MESSAGE)", "sets a MESSAGE to display on the TARGET server. If you give no MESSAGE, it will clear the message"
+  #
+  # def set_message(target_name, message = nil)
+  #   target = lookup_heroku(target_name)
+  #   if message
+  #     puts_and_system "heroku run rake data:util:set_message[\"#{message}\"] -a #{target.heroku_app}"
+  #   else
+  #     puts_and_system "heroku run rake data:util:set_message -a #{target.heroku_app}"
+  #   end
+  # end
+end

data/templates/heroku_targets.yml

@@ -0,0 +1,27 @@
+# find `database_url` by running `heroku pg:info --app=APP_NAME`
+_defaults:
+  repository: https://github.com/red56/heroku_tool
+  # what you are deploying to -- this should either be refs/head/main (the default) or refs/head/master
+  heroku_target_ref: refs/heads/main
+  # set to true if you are doing migrate as part of the heroku release phase, otherwise leave as false, or delete
+  #  https://mentalized.net/journal/2017/04/22/run-rails-migrations-on-heroku-deploy/
+  #  https://devcenter.heroku.com/articles/release-phase
+  migrate_in_release_phase: false
+production:
+  heroku_app : some-heroku-production
+  git_remote : heroku-production
+  deploy_ref : origin/main
+  display_name : production (heroku_tool)
+demo:
+  heroku_app : some-heroku-demo
+  git_remote : heroku-demo
+  deploy_ref : HEAD
+  display_name : demo (heroku_tool)
+  trackable_release_stage : demo
+  staging : true
+staging:
+  heroku_app : some-heroku-staging
+  git_remote : heroku-staging
+  deploy_ref : HEAD
+  display_name : staging (heroku_tool)
+  staging : true

metadata

@@ -0,0 +1,136 @@
+--- !ruby/object:Gem::Specification
+name: heroku_tool
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Tim Diggins
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 12.3.3
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+description:
+email:
+- tim@red56.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- heroku_tool.gemspec
+- lib/heroku_tool.rb
+- lib/heroku_tool/db_configuration.rb
+- lib/heroku_tool/heroku_targets.rb
+- lib/heroku_tool/tasks/db_drop_all_tables.rake
+- lib/heroku_tool/tasks/heroku.thor
+- lib/heroku_tool/thor_utils.rb
+- lib/heroku_tool/version.rb
+- templates/Rakefile
+- templates/heroku.thor
+- templates/heroku_targets.yml
+homepage: https://github.com/red56/heroku_tool
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: Tool for configurable one-shot deployment and db managment with heroku and
+  rails
+test_files: []