gemstack 0.2.5 → 0.3.0

data/lib/gemstack/cli/app_generator.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "gemstack/dev"
+
+module GemStack
+  class CLI < Thor
+    # `gemstack new NAME` — a Ruby API + Next.js application containing the
+    # framework infrastructure and deliberately no business resources.
+    class AppGenerator < Generator
+      NAME = /\A[a-z][a-z0-9_-]*\z/
+      # `--database` values (Rails' names) and aliases.
+      DATABASES = { "sqlite3" => "sqlite3", "sqlite" => "sqlite3", "postgresql" => "postgresql",
+                    "postgres" => "postgresql", "pg" => "postgresql", "mysql2" => "mysql2", "mysql" => "mysql2",
+                    "trilogy" => "trilogy" }.freeze
+      DRIVERS = { "sqlite3" => ["sqlite3", "~> 2.0"], "postgresql" => ["pg", "~> 1.5"],
+                  "mysql2" => ["mysql2", "~> 0.5"], "trilogy" => ["trilogy", "~> 2.9"] }.freeze
+
+      # The gems/ directory of the GemStack checkout this CLI runs from, if any.
+      CHECKOUT = File.expand_path("../../../..", __dir__)
+
+      attr_reader :name, :module_name, :destination, :gemstack_path, :api_path
+
+      def initialize(name, options = {}, output: $stdout)
+        super(output: output)
+        @name = File.basename(name.to_s)
+        @destination = File.expand_path(name.to_s)
+        @options = options
+        @module_name = Inflector.camelize(@name.tr("-", "_"))
+        @gemstack_path = options[:gemstack_path] ? File.expand_path(options[:gemstack_path]) : detect_checkout
+        @api_path = "/api"
+      end
+
+      def version = GemStack::VERSION
+
+      # Pins the app to the Ruby that generated it, in files every version
+      # manager reads (.ruby-version: rbenv, rvm, chruby, asdf, mise;
+      # .tool-versions: asdf, mise), and Node.js likewise (.node-version,
+      # .nvmrc, .tool-versions).
+      def ruby_version = RUBY_VERSION
+      def node_version = @node_version ||= Dev::Toolchain.pinned_node_version
+      def frontend? = !@options[:skip_frontend]
+      def database? = !@options[:skip_database]
+
+      # sqlite3 (default), postgresql, mysql2 or trilogy.
+      def database_adapter
+        @database_adapter ||= DATABASES.fetch(@options[:database].to_s.downcase.then do |d|
+          d.empty? ? "sqlite3" : d
+        end) do
+          raise Thor::Error,
+                "Unknown --database #{@options[:database].inspect}. Use: sqlite3, postgresql, mysql2, trilogy"
+        end
+      end
+
+      def driver_gem = DRIVERS.fetch(database_adapter).first
+      def driver_version = DRIVERS.fetch(database_adapter).last
+      def database_name = name.tr("-", "_")
+
+      def run
+        validate!
+        database_adapter if database? # fail early on an unknown --database
+        @output.puts("Creating GemStack application #{name} in #{destination}")
+        render_directory("app", destination, skip: lambda { |rel|
+          (!database? && (rel.start_with?("db/", "app/models/") || rel == "config/database.yml.tt")) ||
+            (!frontend? && %w[dot_node-version.tt dot_nvmrc.tt].include?(rel))
+        })
+        render_directory("frontend", File.join(destination, "frontend")) if frontend?
+        install unless @options[:skip_install]
+        git_init unless @options[:skip_git]
+        summary
+        self
+      end
+
+      private
+
+      def validate!
+        unless NAME.match?(name)
+          raise Thor::Error,
+                "Invalid name #{name.inspect}: use lowercase letters, digits, - and _, starting with a letter"
+        end
+        return unless File.exist?(destination) && !Dir.empty?(destination)
+
+        raise Thor::Error, "#{destination} already exists and is not empty"
+      end
+
+      def detect_checkout
+        File.file?(File.join(CHECKOUT, "gemstack", "gemstack.gemspec")) ? CHECKOUT : nil
+      end
+
+      def install
+        bundled = run_step("bundle install", destination, "bundle", "install", "--quiet")
+        create_database if bundled && database?
+        return unless frontend?
+
+        run_step("npm install", File.join(destination, "frontend"), "npm", "install", "--no-fund",
+                 "--no-audit")
+        # The TypeScript contract, so frontend/lib/api/generated exists from the start.
+        run_step("gemstack contract", destination, "bin/gemstack", "contract", "--quiet") if bundled
+      end
+
+      # Best effort: a missing or password-protected database server shouldn't fail `new`.
+      def create_database
+        @output.puts("  #{"run".rjust(9)}  gemstack db:create")
+        ok = unbundled { system("bin/gemstack", "db:create", chdir: destination, out: File::NULL, err: File::NULL) }
+        return if ok
+
+        @output.puts("  #{"warning".rjust(9)}  couldn't create the database — " \
+                     "check config/database.yml (or set DATABASE_URL in .env), then run `gemstack db:create`")
+      end
+
+      def git_init
+        return if File.directory?(File.join(destination, ".git")) || !system("git --version", out: File::NULL)
+
+        run_step("git init", destination, "git", "init", "--quiet")
+      end
+
+      def run_step(label, dir, *command)
+        @output.puts("  #{"run".rjust(9)}  #{label}")
+        ok = unbundled { system(*command, chdir: dir) }
+        @output.puts("  #{"warning".rjust(9)}  `#{label}` failed — run it manually in #{dir}") unless ok
+        ok
+      end
+
+      # Run child commands with the new app's bundle, not the CLI's.
+      def unbundled(&)
+        defined?(Bundler) ? Bundler.with_unbundled_env(&) : yield
+      end
+
+      def summary
+        @output.puts <<~TEXT
+
+          GemStack application #{name} created.
+
+            cd #{name}
+            gemstack dev        # → http://localhost:3000
+
+          Next: gemstack generate resource Product name:string price:decimal
+          Useful commands: gemstack routes · gemstack test · gemstack console · gemstack db:migrate
+        TEXT
+      end
+    end
+  end
+end

data/lib/gemstack/cli/commands/db.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    map "db:create" => :db_create, "db:drop" => :db_drop, "db:migrate" => :db_migrate,
+        "db:rollback" => :db_rollback, "db:seed" => :db_seed, "db:setup" => :db_setup,
+        "db:status" => :db_status, "db:reset" => :db_reset
+
+    class_option :environment, aliases: "-e", type: :string, desc: "Environment (default: GEMSTACK_ENV or development)"
+
+    desc "db:create", "Create the database (config/database.yml or DATABASE_URL)"
+    def db_create
+      with_database do
+        result = DB::Tasks.create
+        say("#{result == :created ? "Created" : "Already exists"}: #{DB::Tasks.database_name}")
+      end
+    end
+
+    desc "db:drop", "Drop the database (refused in production unless GEMSTACK_ALLOW_DB_DROP=1)"
+    def db_drop
+      with_database do
+        result = DB::Tasks.drop
+        say("#{result == :dropped ? "Dropped" : "Does not exist"}: #{DB::Tasks.database_name}")
+      end
+    end
+
+    desc "db:migrate", "Apply pending migrations (--target VERSION to migrate up or down to a version)"
+    method_option :target, type: :numeric
+    def db_migrate
+      with_database do
+        changed = DB::Migrator.new.migrate(target: options[:target])
+        changed.empty? ? say("No pending migrations.") : changed.sort.each { |file| say("  migrated  #{file}") }
+      end
+    end
+
+    desc "db:rollback", "Revert the last migration (--steps N for more)"
+    method_option :steps, type: :numeric, default: 1
+    def db_rollback
+      with_database do
+        reverted = DB::Migrator.new.rollback(steps: options[:steps])
+        if reverted.empty?
+          say("Nothing to roll back.")
+        else
+          reverted.sort.reverse_each do |file|
+            say("  reverted  #{file}")
+          end
+        end
+      end
+    end
+
+    desc "db:status", "List migrations and whether they are applied"
+    def db_status
+      with_database do
+        rows = DB::Migrator.new.status.map { |m| [m.applied ? "up" : "down", m.version.to_s, m.name] }
+        if rows.empty?
+          say("No migrations in #{DB.config.migrations_path}.")
+        else
+          print_table([%w[Status Version Name],
+                       *rows])
+        end
+      end
+    end
+
+    desc "db:seed", "Load db/seeds.rb"
+    def db_seed
+      with_database(boot: true) do
+        DB::Tasks.seed ? say("Seeded from #{DB.config.seeds_path}.") : say("No #{DB.config.seeds_path} found.")
+      end
+    end
+
+    desc "db:setup", "Create the database, migrate and seed"
+    def db_setup
+      db_create
+      db_migrate
+      db_seed
+    end
+
+    desc "db:reset", "Drop, recreate, migrate and seed (development/test only)"
+    def db_reset
+      db_drop
+      db_setup
+    end
+
+    desc "contract", "Generate TypeScript types, API clients and OpenAPI from the backend"
+    method_option :quiet, type: :boolean, default: false
+    def contract
+      root = Project.ensure_bundle!(self.class.argv)
+      ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+      Project.load_config!(root)
+      require "gemstack/contract"
+      GemStack.config.reload_code = false
+      GemStack.config.logger.level = :warn
+      GemStack.config.db.log_queries = false if GemStack.config.respond_to?(:db)
+      contract = Contract.build(GemStack.boot!)
+      report = Contract.write(contract, root: root, typescript: File.directory?(File.join(root, "frontend")))
+      print_contract_report(report, contract, root)
+    rescue Sequel::DatabaseConnectionError => e
+      abort("gemstack contract: database unreachable (#{e.message.lines.first.strip}). Models need it to load.")
+    end
+
+    no_commands do
+      def with_database(boot: false)
+        root = Project.ensure_bundle!(self.class.argv)
+        ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+        Project.load_config!(root)
+        unless defined?(GemStack::DB)
+          abort("This app doesn't load the database module. Add `require \"gemstack/db\"` to config/app.rb " \
+                "(and a config/database.yml) — see docs/database.md.")
+        end
+        GemStack.config.reload_code = false
+        GemStack.config.db.log_queries = false
+        GemStack.config.logger.level = :warn # these commands print their own summary
+        GemStack.boot! if boot
+        yield
+      rescue Sequel::DatabaseConnectionError => e
+        settings = DB.settings
+        abort("Can't connect to #{DB::Configuration.describe(settings)} (from #{settings[:source]}): " \
+              "#{e.message.lines.first.strip}\nCheck config/database.yml or DATABASE_URL — see docs/database.md.")
+      rescue GemStack::Error => e
+        abort(e.message)
+      end
+
+      def redact(url) = url.sub(%r{//([^:/@]+):[^@]+@}, '//\1:***@')
+
+      def print_contract_report(report, contract, root)
+        rel = ->(path) { path.delete_prefix("#{root}/") }
+        report[:written].each { |path| say("  #{"write".rjust(9)}  #{rel.call(path)}") }
+        report[:removed].each { |path| say("  #{"remove".rjust(9)}  #{rel.call(path)}") }
+        contract[:warnings].each { |w| say("  #{"warning".rjust(9)}  #{w}", :yellow) } unless options[:quiet]
+        return if options[:quiet] || !report[:written].empty? || !report[:removed].empty?
+
+        say("Contract up to date (#{contract[:resources].size} resources, #{contract[:types].size} types).")
+      end
+    end
+  end
+end

data/lib/gemstack/cli/commands/jobs.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    map "jobs:status" => :jobs_status, "jobs:retry" => :jobs_retry, "jobs:discard" => :jobs_discard,
+        "jobs:install" => :jobs_install, "jobs:failed" => :jobs_failed
+
+    desc "jobs", "Run a background job worker (PostgreSQL queue)"
+    method_option :queues, aliases: "-q", type: :string, desc: "Comma-separated queues (default: all)"
+    method_option :concurrency, aliases: "-c", type: :numeric,
+                                desc: "Worker threads (default: GEMSTACK_JOB_CONCURRENCY or 5)"
+    def jobs
+      with_jobs do |config|
+        config.jobs.queues = options[:queues].split(",").map(&:strip) if options[:queues]
+        config.jobs.concurrency = options[:concurrency] if options[:concurrency]
+        # Each worker thread holds a connection, plus LISTEN and the reaper.
+        config.db.pool_size = [config.db.pool_size, config.jobs.concurrency + 2].max
+        GemStack.boot!
+        GemStack.application.eager_load!
+        require "gemstack/jobs/worker"
+        Jobs::Worker.new.run
+      end
+    end
+
+    desc "jobs:status", "Show queued, scheduled, running and failed jobs per queue"
+    def jobs_status
+      with_jobs(quiet: true) do
+        stats = Jobs::Adapters::Database.new.stats
+        return say("No jobs.") if stats.empty?
+
+        rows = stats.sort.map { |queue, s| [queue, s[:ready], s[:scheduled], s[:running], s[:failed]].map(&:to_s) }
+        print_table([%w[Queue Ready Scheduled Running Failed], *rows])
+      end
+    end
+
+    desc "jobs:failed", "List recently failed jobs"
+    method_option :limit, type: :numeric, default: 20
+    def jobs_failed
+      with_jobs(quiet: true) do
+        failed = Jobs::Adapters::Database.new.failed(limit: options[:limit])
+        return say("No failed jobs.") if failed.empty?
+
+        failed.each do |job|
+          say("##{job[:id]} #{job[:job_class]} (#{job[:queue]}) " \
+              "attempts=#{job[:attempts]} failed_at=#{job[:failed_at]}")
+          say("    #{job[:last_error].to_s.lines.first&.strip}")
+        end
+      end
+    end
+
+    desc "jobs:retry [IDS...]", "Put failed jobs back on the queue (all failed jobs without IDS)"
+    def jobs_retry(*ids)
+      with_jobs(quiet: true) do
+        count = Jobs::Adapters::Database.new.retry_failed(ids.empty? ? nil : ids.map(&:to_i))
+        say("Re-queued #{count} job(s).")
+      end
+    end
+
+    desc "jobs:discard [IDS...]", "Delete failed jobs (all failed jobs without IDS)"
+    def jobs_discard(*ids)
+      with_jobs(quiet: true) do
+        count = Jobs::Adapters::Database.new.discard_failed(ids.empty? ? nil : ids.map(&:to_i))
+        say("Deleted #{count} failed job(s).")
+      end
+    end
+
+    desc "jobs:install", "Add the gemstack_jobs table migration (done automatically by `generate job`)"
+    def jobs_install
+      JobGenerator.install_migration(Project.root!, output: $stdout)
+    end
+
+    no_commands do
+      def with_jobs(quiet: false)
+        root = Project.ensure_bundle!(self.class.argv)
+        ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+        Project.load_config!(root)
+        unless defined?(GemStack::Jobs)
+          abort('This app doesn\'t load background jobs. Add `require "gemstack/jobs"` to config/app.rb.')
+        end
+        config = GemStack.config
+        config.reload_code = false
+        if quiet
+          config.logger.level = :warn
+          config.db.log_queries = false if config.respond_to?(:db)
+        end
+        yield config
+      rescue Sequel::DatabaseError => e
+        raise unless e.message.include?("gemstack_jobs")
+
+        abort("The gemstack_jobs table doesn't exist yet. Run `gemstack jobs:install && gemstack db:migrate`.")
+      rescue Sequel::DatabaseConnectionError => e
+        abort("Can't connect to the database: #{e.message.lines.first.strip}")
+      end
+    end
+  end
+end

data/lib/gemstack/cli/controller_generator.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack generate controller Products index show create`
+    #
+    # Creates the controller, a test per action and the matching routes.
+    # Conventional action names map to REST routes; any other action becomes
+    # GET /<resource>/<action>.
+    class ControllerGenerator < Generator
+      REST = {
+        "index" => ["get", ""], "show" => ["get", "/:id"], "create" => ["post", ""],
+        "update" => ["patch", "/:id"], "destroy" => ["delete", "/:id"]
+      }.freeze
+      ROUTES_BLOCK = /^GemStack\.routes do[ \t]*\n/
+
+      attr_reader :file_name, :class_name, :actions, :url_path
+
+      def initialize(name, actions, root:, output: $stdout, force: false)
+        super(output: output, force: force)
+        @root = root
+        @file_name = Inflector.underscore(name.to_s.delete_suffix("Controller")) # "admin/products"
+        @class_name = "#{Inflector.camelize(@file_name)}Controller"              # "Admin::ProductsController"
+        @actions = (actions.empty? ? ["index"] : actions).map { |a| Inflector.underscore(a) }.uniq
+        @url_path = "/#{@file_name.split("/").map { |part| Inflector.dasherize(part) }.join("/")}"
+        validate!
+      end
+
+      def run
+        template_files("controller", override_root: @root).each do |rel, source|
+          target = File.join(@root, rel.delete_suffix(".tt").gsub("%file_name%", file_name))
+          write(target, render(File.read(source), source))
+        end
+        add_routes
+        self
+      end
+
+      def route_for(action)
+        verb, suffix = REST.fetch(action) { ["get", "/#{Inflector.dasherize(action)}"] }
+        [verb, url_path + suffix]
+      end
+
+      # Example path for tests: :id becomes 1.
+      def request_path(action) = "/api#{route_for(action)[1].sub(":id", "1")}"
+
+      def route_line(action)
+        verb, path = route_for(action)
+        %(#{verb} "#{path}", to: "#{file_name}##{action}")
+      end
+
+      private
+
+      def validate!
+        invalid = actions.grep_v(/\A[a-z_][a-z0-9_]*\z/)
+        raise Thor::Error, "Invalid action name(s): #{invalid.join(", ")}" unless invalid.empty?
+        raise Thor::Error, "Invalid controller name" unless file_name.match?(%r{\A[a-z][a-z0-9_/]*\z})
+      end
+
+      def add_routes
+        path = File.join(@root, "config/routes.rb")
+        return status("skip", path, "not found — add routes manually") unless File.file?(path)
+
+        content = File.read(path)
+        lines = actions.map { |action| route_line(action) }.reject { |line| content.include?(line) }
+        return status("identical", path) if lines.empty?
+        return status("skip", path, "no `GemStack.routes do` block found") unless content.match?(ROUTES_BLOCK)
+
+        File.write(path, content.sub(ROUTES_BLOCK) { |open| open + lines.map { |l| "  #{l}\n" }.join })
+        status("route", path, lines.join("; "))
+      end
+    end
+  end
+end

data/lib/gemstack/cli/deploy_generator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack generate deploy` — Dockerfile (api + web targets), compose.yaml
+    # (Postgres, migrations, API, jobs, Next.js, Caddy), Caddyfile, Procfile and
+    # .dockerignore. Nothing is deployed anywhere.
+    class DeployGenerator < Generator
+      def initialize(root:, output: $stdout, force: false)
+        super(output: output, force: force)
+        @root = root
+      end
+
+      def app_name = File.basename(@root).downcase.gsub(/[^a-z0-9_-]/, "-")
+      def frontend? = File.file?(File.join(@root, "frontend/package.json"))
+
+      # A worker process is needed for background jobs (and auth's emails).
+      def jobs?
+        return true if Generator.uses?(@root, :auth)
+
+        Generator.uses?(@root, :jobs) && Generator.background_work?(@root)
+      end
+
+      def mail? = Generator.uses?(@root, :mail) || Generator.uses?(@root, :auth)
+      def database? = Generator.uses?(@root, :db)
+      def realtime? = Generator.uses?(@root, :realtime)
+
+      # From config/database.yml (production, else the first adapter listed);
+      # apps without one use PostgreSQL, GemStack's original default.
+      def database_adapter
+        path = File.join(@root, "config/database.yml")
+        return "postgresql" unless File.file?(path)
+
+        text = File.read(path)
+        production = text[/^production:.*?(?=^\S|\z)/m].to_s
+        (production[/^\s+adapter:\s*(\w+)/, 1] || text[/^\s+adapter:\s*(\w+)/, 1] || "postgresql")
+          .then { |name| { "postgres" => "postgresql", "sqlite" => "sqlite3", "mysql" => "mysql2" }.fetch(name, name) }
+      end
+
+      def sqlite? = database_adapter == "sqlite3"
+      def mysql? = %w[mysql2 trilogy].include?(database_adapter)
+      def postgresql? = database_adapter == "postgresql"
+      # A Redis for realtime fan-out when the database can't do it (PostgreSQL uses NOTIFY).
+      def redis? = realtime? && !postgresql?
+
+      def build_packages
+        (%w[build-essential libyaml-dev
+            git] + { "postgresql" => ["libpq-dev"], "mysql2" => ["default-libmysqlclient-dev"] }.fetch(database_adapter,
+                                                                                                       [])).join(" ")
+      end
+
+      def runtime_packages
+        (%w[libyaml-0-2
+            curl] + { "postgresql" => ["libpq5"], "mysql2" => ["libmariadb3"] }.fetch(database_adapter, [])).join(" ")
+      end
+
+      def database_url
+        case database_adapter
+        when "sqlite3" then "sqlite3:/data/production.sqlite3"
+        when "postgresql" then "postgres://app:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/app"
+        else "#{database_adapter}://app:${MYSQL_PASSWORD:?set MYSQL_PASSWORD}@db:3306/app"
+        end
+      end
+
+      def ruby_version
+        pinned = File.file?(File.join(@root, ".ruby-version")) && File.read(File.join(@root, ".ruby-version")).strip
+        pinned && !pinned.empty? ? pinned.delete_prefix("ruby-") : RUBY_VERSION
+      end
+
+      def node_version
+        tools = File.join(@root, ".tool-versions")
+        pinned = File.file?(tools) && File.read(tools)[/^nodejs\s+(\d+)/, 1]
+        pinned || "22"
+      end
+
+      def run
+        template_files("deploy", override_root: @root).sort.each do |rel, source|
+          content = File.read(source)
+          content = render(content, source) if rel.end_with?(".tt")
+          write(File.join(@root, output_path(rel.delete_suffix(".tt"))), content)
+        end
+        keep = File.join(@root, "vendor/.keep")
+        write(keep, "") unless File.exist?(keep) # the Dockerfile copies vendor/ (e.g. vendor/cache)
+        warn_about_local_gems
+        self
+      end
+
+      private
+
+      def gemfile = @gemfile ||= File.read(File.join(@root, "Gemfile"))
+
+      # Apps generated from a GemStack checkout point at it with an absolute
+      # path, which doesn't exist inside the image.
+      def warn_about_local_gems
+        return unless gemfile.match?(/^path "/)
+
+        status("warning", "Gemfile", "GemStack comes from a local path the image can't see — " \
+                                     "run `bundle cache --all` (vendor/cache) or use released gems")
+      end
+    end
+  end
+end

data/lib/gemstack/cli/doctor/upgrade_check.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    class Doctor
+      # `gemstack doctor` for apps generated before 0.3.0, when every module
+      # was its own gem: says exactly what to change to finish upgrading.
+      module UpgradeCheck
+        # Gems merged into gemstack in 0.3.0; their names still install (as shims).
+        RETIRED_GEMS = %w[core cache schema http db jobs mail storage contract dev].freeze
+        LOADED_BY_REQUIRE = %w[db jobs mail storage].freeze
+
+        # Apps generated before 0.3.0 list the retired gems in the Gemfile.
+        def check_gemstack_upgrade
+          gemfile = read("Gemfile").to_s
+          retired = RETIRED_GEMS.select { |name| gemfile.match?(/^\s*gem "gemstack-#{name}"/) }
+          return if retired.empty?
+
+          app_rb = read("config/app.rb").to_s
+          missing = (retired & LOADED_BY_REQUIRE).reject { |name| app_rb.include?(%(require "gemstack/#{name}")) }
+          gems = retired.map { |name| %(gem "gemstack-#{name}") }
+          requires = missing.map { |name| %(require "gemstack/#{name}") }
+          steps = []
+          steps << "remove #{gems.join(", ")} from the Gemfile" if gems.any?
+          steps << "add #{requires.join(", ")} to config/app.rb" if requires.any?
+          caution("set up for GemStack before 0.3",
+                  "#{steps.join("; ")}, then bundle install (CHANGELOG: upgrading to 0.3)")
+        end
+      end
+    end
+  end
+end