gemstack 0.2.5 → 0.3.0

data/lib/gemstack/cli/doctor.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+require "gemstack/dev"
+require_relative "doctor/upgrade_check"
+
+module GemStack
+  class CLI < Thor
+    # `gemstack doctor` — checks that an application can run, and says how to
+    # fix what can't. Every check is independent: one
+    # failure never hides the others. `--production` checks the settings a
+    # deploy needs.
+    class Doctor
+      include UpgradeCheck
+
+      Result = Struct.new(:status, :title, :hint)
+
+      attr_reader :results
+
+      def initialize(root:, output: $stdout, production: false, color: output.tty?, run: nil)
+        @root = root
+        @output = output
+        @production = production
+        @color = color
+        @run = run || ->(*command) { Open3.capture2e(*command) }
+        @results = []
+      end
+
+      def run
+        header
+        check_ruby
+        check_node
+        check_frontend_dependencies
+        check_git_secrets
+        check_gemstack_upgrade
+        booted = check_boot
+        if booted
+          database_ok = check_database
+          check_migrations_and_jobs if database_ok
+          check_cache
+          check_realtime_broker
+          check_contract if database_ok
+        end
+        check_production_settings if @production
+        check_port unless @production
+        summary
+        self
+      end
+
+      def ok? = results.none? { |result| result.status == :fail }
+
+      # ── checks ─────────────────────────────────────────────────────────
+
+      def check_ruby
+        wanted = read(".ruby-version")&.strip&.delete_prefix("ruby-")
+        if !Dev::Toolchain.ruby_ok?
+          problem("Ruby #{RUBY_VERSION}", "GemStack needs Ruby #{Dev::Toolchain::MIN_RUBY} or newer — " \
+                                          "#{Dev::Toolchain.ruby_hint(wanted.to_s.empty? ? "3.4" : wanted)}")
+        elsif wanted && !wanted.empty? && !RUBY_VERSION.start_with?(wanted)
+          caution("Ruby #{RUBY_VERSION}", "the app pins #{wanted} (.ruby-version) — #{Dev::Toolchain.ruby_hint(wanted)}")
+        else
+          pass("Ruby #{RUBY_VERSION}#{" (YJIT available)" if defined?(RubyVM::YJIT)}")
+        end
+      end
+
+      def check_node
+        return unless File.directory?(path("frontend"))
+
+        node = Dev::Toolchain.node(@run)
+        wanted = read(".node-version")&.strip || read(".nvmrc")&.strip || Dev::Toolchain::LTS_NODE
+        if node.nil?
+          problem("Node.js not found", Dev::Toolchain.node_hint(wanted, nil))
+        elsif !Dev::Toolchain.node_ok?(node[:version])
+          problem("Node.js #{node[:version]} (#{node[:path]})",
+                  "Next.js 16 needs #{Dev::Toolchain::MIN_NODE.join(".")}+ — " \
+                  "#{Dev::Toolchain.node_hint(wanted, Dev::Toolchain.node_manager(node[:path]))}")
+        else
+          pass("Node.js #{node[:version]}")
+        end
+      end
+
+      def check_frontend_dependencies
+        return unless File.directory?(path("frontend"))
+
+        if File.file?(path("frontend/node_modules/.package-lock.json"))
+          lock = path("frontend/package-lock.json")
+          stale = File.file?(lock) && File.mtime(lock) > File.mtime(path("frontend/node_modules/.package-lock.json"))
+          if stale
+            caution("frontend dependencies",
+                    "package-lock.json changed — run: cd frontend && npm install")
+          else
+            pass("frontend dependencies installed")
+          end
+        else
+          problem("frontend dependencies missing", "run: cd frontend && npm install")
+        end
+      end
+
+      # Secrets committed to git stay in its history (and in every clone).
+      def check_git_secrets
+        return unless File.directory?(path(".git"))
+
+        out, status = @run.call("git", "-C", @root, "ls-files", "--", ".env", ".env.*", "*.pem", "*.key",
+                                "tmp/*_secret")
+        return unless status.success?
+
+        tracked = out.lines.map(&:strip).reject { |file| file.empty? || file.end_with?(".example") }
+        if tracked.empty?
+          pass("no secret files tracked by git")
+        else
+          problem("secret files tracked by git: #{tracked.join(", ")}",
+                  "remove them from git (git rm --cached …), rotate every secret they contain, and ask whoever " \
+                  "manages your infrastructure to check where the repository was shared")
+        end
+      end
+
+      def check_boot
+        ENV["GEMSTACK_ENV"] = "production" if @production
+        ENV["GEMSTACK_ENV"] ||= "development"
+        Project.load_config!(@root)
+        config = GemStack.config
+        config.reload_code = false
+        config.eager_load = false
+        config.logger.output = nil
+        config.db.log_queries = false if config.respond_to?(:db)
+        GemStack.boot!
+        pass("application boots (#{GemStack.env}, #{GemStack.application.routes.size} routes)")
+        true
+      rescue StandardError, ScriptError => e
+        problem("application fails to boot: #{e.class}: #{e.message.lines.first&.strip}", location(e))
+        false
+      end
+
+      def check_database
+        return true unless defined?(GemStack::DB)
+
+        settings = GemStack::DB.settings
+        where = "#{GemStack::DB::Configuration.describe(settings)}, from #{settings[:source]}"
+        if settings[:adapter] == "sqlite" && !GemStack::DB::Tasks.exists?(settings)
+          problem("SQLite database file missing (#{where})", "run: gemstack db:create")
+          return false
+        end
+        GemStack::DB.connection.test_connection
+        pass("database reachable (#{where})")
+        true
+      rescue StandardError, LoadError => e
+        message = e.message.lines.first.to_s.strip
+        message = message.split(/FATAL:\s*/, 2).last if message.include?("FATAL:")
+        hint = if message.match?(/does not exist|Unknown database/) then "run: gemstack db:create"
+               elsif e.is_a?(GemStack::ConfigurationError) then "fix config/database.yml or DATABASE_URL"
+               else "is the database server running? Check config/database.yml or DATABASE_URL (#{where})"
+               end
+        problem("database: #{message}", hint)
+        false
+      end
+
+      # MySQL/SQLite apps: a jobs worker is a separate process, and the memory
+      # broker can't carry its broadcasts to the web server.
+      def check_realtime_broker
+        return unless defined?(GemStack::Realtime) && defined?(GemStack::Jobs) && GemStack::Jobs.database_queue?
+        return unless GemStack.config.realtime.broker.to_s == "memory" && jobs_used?
+
+        caution("realtime uses the in-process memory broker",
+                "broadcasts from jobs won't reach the web server — set config.realtime.broker = :redis (REDIS_URL)")
+      end
+
+      def check_migrations_and_jobs
+        pending = GemStack::DB::Migrator.new.pending
+        if pending.empty?
+          pass("migrations up to date")
+        else
+          caution("#{pending.size} pending migration(s)", "run: gemstack db:migrate")
+        end
+        return unless defined?(GemStack::Jobs) && GemStack::Jobs.database_queue?
+        return unless jobs_used?
+
+        if GemStack::DB.connection.table_exists?(:gemstack_jobs)
+          pass("jobs table present")
+        elsif pending.empty?
+          problem("background jobs are used but the gemstack_jobs table is missing",
+                  "run: gemstack jobs:install && gemstack db:migrate")
+        end
+      end
+
+      def check_cache
+        return unless GemStack.config.respond_to?(:cache) && GemStack.config.cache.store.to_s == "redis"
+
+        GemStack.cache.write("gemstack:doctor", 1, expires_in: 5)
+        pass("Redis cache reachable")
+      rescue StandardError => e
+        problem("Redis cache: #{e.message.lines.first&.strip}", "is Redis running? Check REDIS_URL")
+      end
+
+      def check_contract
+        return unless File.directory?(path("frontend"))
+
+        contract = Contract.build(GemStack.application)
+        report = Contract.write(contract, root: @root, dry_run: true)
+        changed = report[:written] + report[:removed]
+        if changed.empty?
+          pass("TypeScript contract up to date")
+        else
+          caution("TypeScript contract out of date (#{changed.size} file(s))",
+                  "run: gemstack contract (gemstack dev does it on save)")
+        end
+        contract[:warnings].first(3).each { |message| caution("contract: #{message}", nil) }
+      rescue StandardError => e
+        caution("contract could not be built: #{e.message.lines.first&.strip}", "run: gemstack contract")
+      end
+
+      def check_production_settings
+        secret = GemStack.config.secret_key_base.to_s
+        if secret.empty? then problem("SECRET_KEY_BASE is not set", "generate one: openssl rand -hex 64")
+        elsif secret.length < 64 then problem("SECRET_KEY_BASE is too short", "use: openssl rand -hex 64")
+        else pass("SECRET_KEY_BASE is set")
+        end
+        check_production_database if defined?(GemStack::DB)
+        if defined?(GemStack::Mail) && GemStack.config.mail.delivery.to_s == "smtp"
+          env_check("SMTP_URL", "e.g. smtp://user:password@smtp.example.com:587")
+        end
+        env_check("APP_URL", "the frontend's public URL, used in email links") if defined?(GemStack::Auth)
+        check_storage_settings if defined?(GemStack::Storage)
+        return unless GemStack.config.respond_to?(:cache) && GemStack.config.cache.store.to_s == "redis"
+
+        env_check("REDIS_URL", "the Redis used by the cache")
+      end
+
+      def check_production_database
+        settings = GemStack::DB.settings
+        if settings[:source].start_with?("default")
+          problem("no production database configured",
+                  "set DATABASE_URL, or a production section in config/database.yml")
+        elsif settings[:adapter] == "sqlite"
+          caution("SQLite in production (#{settings[:database]})",
+                  "keep the file on a persistent volume and run a single server; back it up")
+        else
+          pass("production database: #{GemStack::DB::Configuration.describe(settings)} (#{settings[:source]})")
+        end
+      end
+
+      def check_storage_settings
+        return unless GemStack.config.storage.service.to_s == "s3"
+
+        env_check("S3_BUCKET", "the bucket uploads go to")
+        begin
+          require "aws-sdk-s3"
+          pass("aws-sdk-s3 available")
+        rescue LoadError
+          problem("storage uses S3 but aws-sdk-s3 isn't installed", "add gem \"aws-sdk-s3\" to the Gemfile")
+        end
+      end
+
+      def check_port
+        port = Integer(ENV.fetch("PORT", 3000))
+        TCPServer.new("127.0.0.1", port).close
+        pass("port #{port} is free for gemstack dev")
+      rescue Errno::EADDRINUSE
+        caution("port #{port} is in use", "stop the other process, or run: PORT=#{port + 1} gemstack dev")
+      rescue ArgumentError, SystemCallError
+        nil
+      end
+
+      private
+
+      def header
+        @output.puts("GemStack doctor · #{File.basename(@root)}#{" · production settings" if @production}\n\n")
+      end
+
+      def summary
+        failures = results.count { |r| r.status == :fail }
+        warnings = results.count { |r| r.status == :warn }
+        line = if failures.zero? && warnings.zero? then paint("Everything looks good.", 32)
+               else
+                 [(paint("#{failures} problem(s)", 31) if failures.positive?),
+                  (paint("#{warnings} warning(s)", 33) if warnings.positive?)].compact.join(", ")
+               end
+        @output.puts("\n#{line}")
+      end
+
+      def record(status, title, hint)
+        @results << Result.new(status, title, hint)
+        symbol = { ok: paint("✓", 32), warn: paint("!", 33), fail: paint("✗", 31) }.fetch(status)
+        @output.puts("  #{symbol} #{title}")
+        @output.puts("      → #{hint}") if hint
+      end
+
+      def pass(title) = record(:ok, title, nil)
+      def caution(title, hint) = record(:warn, title, hint)
+      def problem(title, hint) = record(:fail, title, hint)
+
+      def env_check(name, hint)
+        ENV.fetch(name, "").strip.empty? ? problem("#{name} is not set", hint) : pass("#{name} is set")
+      end
+
+      def jobs_used?
+        Generator.background_work?(@root)
+      end
+
+      def location(error)
+        frame = Array(error.backtrace_locations || error.backtrace).map(&:to_s).find { |line| line.start_with?(@root) }
+        frame ? "at #{frame.delete_prefix("#{@root}/")}" : "run `gemstack server` to see the full error"
+      end
+
+      def redact(url) = url.to_s.sub(%r{//([^:/@]+):[^@]+@}, '//\1:***@')
+      def path(relative) = File.join(@root, relative)
+      def read(relative) = File.file?(path(relative)) ? File.read(path(relative)) : nil
+      def paint(text, code) = @color ? "\e[#{code}m#{text}\e[0m" : text
+    end
+  end
+end

data/lib/gemstack/cli/generator.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "erb"
+require "fileutils"
+
+module GemStack
+  class CLI < Thor
+    # Shared machinery for generators: renders a template directory into a
+    # destination. Files ending in .tt are ERB templates evaluated against the
+    # generator; a leading "dot_" in a file name becomes "." (so dotfiles
+    # survive gem packaging). Existing files are never overwritten silently.
+    #
+    # Applications can override any template by placing a file with the same
+    # relative path in lib/templates/gemstack/<generator>/ (ARCHITECTURE §7).
+    class Generator
+      TEMPLATES = File.expand_path("../../../templates", __dir__)
+
+      attr_reader :created
+
+      def initialize(output: $stdout, force: false)
+        @output = output
+        @force = force
+        @created = []
+      end
+
+      def template_root(name) = File.join(TEMPLATES, name)
+
+      # Ruby core/stdlib names an app class must not reuse (a top-level class
+      # named Digest or Set would collide with Ruby's own). Constants already
+      # defined in this process (stdlib and gems loaded by the CLI) are
+      # checked too; the app's own code isn't loaded here, so those are always
+      # foreign.
+      RESERVED = %w[
+        Array BasicObject Benchmark Binding Class Comparable Data Date DateTime Digest Dir Encoding Enumerable
+        Enumerator Errno Exception FalseClass Fiber File FileTest FileUtils Float GC Hash IO Integer JSON Kernel
+        Logger Marshal MatchData Math Method Module Monitor Mutex NilClass Numeric Object ObjectSpace Observable
+        OpenStruct Pathname Proc Process Queue Random Range Rational Regexp Ripper Set Signal Socket String
+        StringIO Struct Symbol Thread Time Timeout TracePoint TrueClass URI Warning Zlib Rack Sequel Thor Puma
+        GemStack
+      ].freeze
+
+      def self.check_constant!(name, suggestion: nil)
+        top = name.to_s.split("::").first
+        return unless RESERVED.include?(top) || Object.const_defined?(top, false)
+
+        hint = suggestion ? " — try #{suggestion}" : ""
+        raise Thor::Error, "#{name} would clash with Ruby's (or a loaded gem's) #{top} constant#{hint}"
+      end
+
+      # A migration version not used yet in db/migrations: generating several
+      # migrations within one second must not give them the same version.
+      def self.migration_timestamp(root, time = Time.now.utc)
+        loop do
+          stamp = time.strftime("%Y%m%d%H%M%S")
+          return stamp if Dir.glob(File.join(root.to_s, "db/migrations/#{stamp}_*.rb")).empty?
+
+          time += 1
+        end
+      end
+
+      # Every template file for a generator, with app overrides applied.
+      # The app's base classes (written by `gemstack new` since 0.2.1). Apps
+      # created earlier get the ones a generator's code inherits from.
+      BASE_CLASSES = {
+        model: "app/models/application_model.rb", serializer: "app/serializers/application_serializer.rb",
+        job: "app/jobs/application_job.rb", mailer: "app/mailers/application_mailer.rb"
+      }.freeze
+
+      # Which GemStack modules an app uses. Since 0.3.0 the core modules are
+      # part of the gemstack gem and switched on with `require "gemstack/db"`
+      # (etc.) in config/app.rb; apps from before list gemstack-db in the
+      # Gemfile. Auth and realtime are gems of their own either way.
+      MODULE_GEMS = %w[auth realtime].freeze
+
+      def self.uses?(root, name)
+        name = name.to_s
+        gemfile = read_file(root, "Gemfile")
+        return true if gemfile.match?(/^\s*gem "gemstack-#{name}"/)
+        return false if MODULE_GEMS.include?(name)
+
+        read_file(root, "config/app.rb").match?(%r{^\s*require "gemstack/#{name}"})
+      end
+
+      def self.read_file(root, rel) = File.file?(File.join(root, rel)) ? File.read(File.join(root, rel)) : ""
+
+      # Whether the app has jobs or mailers of its own (base classes don't count).
+      def self.background_work?(root)
+        %w[app/jobs/*.rb app/mailers/*.rb].any? do |glob|
+          Dir.glob(File.join(root, glob)).any? { |file| !File.basename(file).start_with?("application_") }
+        end
+      end
+
+      def ensure_base_classes(root, *kinds)
+        kinds.each do |kind|
+          rel = BASE_CLASSES.fetch(kind)
+          target = File.join(root, rel)
+          write(target, File.read(File.join(template_root("app"), rel))) unless File.exist?(target)
+        end
+      end
+
+      def template_files(name, override_root: nil)
+        files = relative_files(template_root(name)).to_h { |rel| [rel, File.join(template_root(name), rel)] }
+        if override_root
+          custom = File.join(override_root, "lib/templates/gemstack", name)
+          relative_files(custom).each { |rel| files[rel] = File.join(custom, rel) } if File.directory?(custom)
+        end
+        files
+      end
+
+      def render_directory(name, destination, override_root: nil, skip: nil)
+        template_files(name, override_root: override_root).sort.each do |rel, source|
+          next if skip&.call(rel)
+
+          target = File.join(destination, output_path(rel))
+          content = File.binread(source)
+          content = render(content, source) if source.end_with?(".tt")
+          write(target, content, mode: File.stat(source).mode)
+        end
+      end
+
+      def render(content, source = "(template)")
+        erb = ERB.new(content, trim_mode: "-")
+        erb.filename = source
+        erb.result(binding)
+      end
+
+      def write(path, content, mode: nil)
+        if File.exist?(path) && !@force
+          if File.binread(path) == content
+            status("identical", path)
+          else
+            status("skip", path, "exists — not overwritten")
+          end
+          return false
+        end
+        FileUtils.mkdir_p(File.dirname(path))
+        File.binwrite(path, content)
+        File.chmod(mode & 0o777, path) if mode
+        @created << path
+        status("create", path)
+        true
+      end
+
+      def status(label, path, note = nil)
+        shown = path.delete_prefix("#{Dir.pwd}/")
+        @output.puts("  #{label.rjust(9)}  #{shown}#{"  (#{note})" if note}")
+      end
+
+      private
+
+      def relative_files(root)
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: root)
+           .reject { |rel| File.directory?(File.join(root, rel)) || File.basename(rel) == ".DS_Store" }
+      end
+
+      def output_path(rel)
+        rel.delete_suffix(".tt").split("/").map { |part| part.sub(/\Adot_/, ".") }.join("/")
+      end
+    end
+  end
+end

data/lib/gemstack/cli/job_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack generate job SendWelcomeEmail [queue]`
+    #
+    # Writes app/jobs/<name>.rb and a test, and — the first time — the
+    # migration for the gemstack_jobs table, so apps get the table only once
+    # they actually use background jobs.
+    class JobGenerator < Generator
+      MIGRATION_GLOB = "db/migrations/*_create_gemstack_jobs.rb"
+
+      attr_reader :class_name, :file_name, :queue_name
+
+      def self.install_migration(root, output: $stdout, timestamp: nil)
+        existing = Dir.glob(File.join(root, MIGRATION_GLOB)).first
+        generator = new("Placeholder", root: root, output: output)
+        return generator.status("identical", existing, "jobs table migration already present") if existing
+
+        require "gemstack/jobs"
+        stamp = timestamp || Generator.migration_timestamp(root)
+        generator.write(File.join(root, "db/migrations/#{stamp}_create_gemstack_jobs.rb"), Jobs::Migration::SOURCE)
+      end
+
+      def initialize(name, root:, queue: nil, output: $stdout, force: false)
+        super(output: output, force: force)
+        @root = root
+        base = Inflector.camelize(name.to_s).delete_suffix("Job")
+        raise Thor::Error, "Invalid job name #{name.inspect}" unless base.match?(/\A[A-Z][A-Za-z0-9]*\z/)
+
+        @class_name = name.to_s.end_with?("Job") ? Inflector.camelize(name.to_s) : base
+        @file_name = Inflector.underscore(@class_name)
+        @queue_name = queue
+        Generator.check_constant!(@class_name, suggestion: "#{@class_name}Job") unless name == "Placeholder"
+      end
+
+      def run
+        ensure_base_classes(@root, :job)
+        template_files("job", 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
+        self.class.install_migration(@root, output: @output) if File.directory?(File.join(@root, "db"))
+        self
+      end
+    end
+  end
+end

data/lib/gemstack/cli/migration_generator.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack generate migration NAME [fields]`
+    #
+    #   AddSkuToProducts sku:string:unique   → alter_table(:products) { add_column ... }
+    #   anything else                        → an empty `change` block
+    class MigrationGenerator < Generator
+      attr_reader :file_name, :table, :columns, :timestamp
+
+      def initialize(name, field_args, root:, output: $stdout, timestamp: nil)
+        super(output: output)
+        @root = root
+        @file_name = Inflector.underscore(name.to_s)
+        raise Thor::Error, "Invalid migration name #{name.inspect}" unless @file_name.match?(/\A[a-z][a-z0-9_]*\z/)
+
+        @timestamp = timestamp || Generator.migration_timestamp(root)
+        @table = @file_name[/\Aadd_\w+_to_(\w+)\z/, 1]
+        spec = ResourceSpec.new("Migration", field_args)
+        builder = ResourceGenerator.new(spec, root: root, output: output)
+        @columns = spec.fields.flat_map do |field|
+          [normalize(builder.migration_column(field),
+                     field)] + (field.index && !field.unique ? ["add_index :#{field.column}"] : [])
+        end
+      end
+
+      def run
+        template_files("migration", override_root: @root).each do |rel, source|
+          path = rel.delete_suffix(".tt").gsub("%timestamp%", timestamp).gsub("%file_name%", file_name)
+          write(File.join(@root, path), render(File.read(source), source))
+        end
+        self
+      end
+
+      private
+
+      # Turns a create_table column line into its alter_table equivalent.
+      def normalize(line, field)
+        if field.reference?
+          line.sub(/\Aforeign_key/, "add_foreign_key")
+        elsif line.start_with?("column ")
+          line.sub(/\Acolumn :(\w+), /, 'add_column :\1, ')
+        else
+          type, rest = line.split(" ", 2)
+          name, options = rest.split(",", 2)
+          "add_column #{name}, #{type}#{",#{options}" if options}"
+        end
+      end
+    end
+  end
+end

data/lib/gemstack/cli/policy_generator.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack generate policy Order` → app/policies/order_policy.rb + test.
+    class PolicyGenerator < Generator
+      attr_reader :model_name, :class_name, :file_name
+
+      def initialize(name, root:, output: $stdout, force: false)
+        super(output: output, force: force)
+        @root = root
+        @model_name = Inflector.camelize(name.to_s.delete_suffix("Policy").delete_suffix("_policy"))
+        unless @model_name.match?(/\A[A-Z][A-Za-z0-9]*(::[A-Z][A-Za-z0-9]*)*\z/)
+          raise Thor::Error,
+                "Invalid policy name #{name.inspect}"
+        end
+
+        @class_name = "#{@model_name}Policy"
+        @file_name = Inflector.underscore(@model_name)
+      end
+
+      def parent_class
+        File.file?(File.join(@root, "app/policies/application_policy.rb")) ? "ApplicationPolicy" : "GemStack::Policy"
+      end
+
+      def run
+        template_files("policy", 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
+        self
+      end
+    end
+  end
+end

data/lib/gemstack/cli/project.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # Locates the GemStack application the CLI is run from and makes sure
+    # commands run inside that application's bundle, so the app's own
+    # GemStack version and gems are used (like a binstub would).
+    module Project
+      MARKER = "config/app.rb"
+
+      module_function
+
+      def root(start = Dir.pwd)
+        dir = File.expand_path(start)
+        loop do
+          return dir if File.file?(File.join(dir, MARKER)) && File.file?(File.join(dir, "Gemfile"))
+
+          parent = File.dirname(dir)
+          return nil if parent == dir
+
+          dir = parent
+        end
+      end
+
+      def root!
+        root || abort("Not inside a GemStack application (no #{MARKER} found). Create one with `gemstack new myapp`.")
+      end
+
+      def in_bundle?(app_root)
+        gemfile = ENV.fetch("BUNDLE_GEMFILE", nil)
+        gemfile && File.expand_path(gemfile) == File.join(app_root, "Gemfile") && defined?(Bundler)
+      end
+
+      # Re-executes the current command under `bundle exec` unless the app's
+      # bundle is already active, then chdirs to the app root.
+      def ensure_bundle!(argv)
+        app_root = root!
+        unless in_bundle?(app_root)
+          Dir.chdir(app_root)
+          ENV["BUNDLE_GEMFILE"] = File.join(app_root, "Gemfile")
+          exec("bundle", "exec", "gemstack", *argv)
+        end
+        Dir.chdir(app_root)
+        app_root
+      end
+
+      # Loads config/app.rb (configuration + gems) without booting the app.
+      def load_config!(app_root)
+        require File.join(app_root, MARKER)
+      end
+    end
+  end
+end