gemstack-cli 0.1.0

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,64 @@
+# 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 (DECISIONS D-058). 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 gemfile.match?(/^\s*gem "gemstack-auth"/)
+
+        gemfile.match?(/^\s*gem "gemstack-jobs"/) &&
+          %w[app/jobs/*.rb app/mailers/*.rb].any? { |glob| !Dir.glob(File.join(@root, glob)).empty? }
+      end
+
+      def mail? = gemfile.match?(/^\s*gem "gemstack-(mail|auth)"/)
+
+      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.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "open3"
+require "socket"
+
+module GemStack
+  class CLI < Thor
+    # `gemstack doctor` — checks that an application can run, and says how to
+    # fix what can't (DECISIONS D-057). Every check is independent: one
+    # failure never hides the others. `--production` checks the settings a
+    # deploy needs.
+    class Doctor
+      Result = Struct.new(:status, :title, :hint)
+      MIN_NODE = [20, 9].freeze # Next.js 16
+
+      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
+        booted = check_boot
+        if booted
+          database_ok = check_database
+          check_migrations_and_jobs if database_ok
+          check_cache
+          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 wanted && !wanted.empty? && !RUBY_VERSION.start_with?(wanted)
+          caution("Ruby #{RUBY_VERSION}",
+                  "the app pins #{wanted} (.ruby-version) — install it: asdf install ruby #{wanted}")
+        elsif Gem::Version.new(RUBY_VERSION) < Gem::Version.new("4.0")
+          problem("Ruby #{RUBY_VERSION}", "GemStack needs Ruby 4.0 or newer")
+        else
+          pass("Ruby #{RUBY_VERSION}#{" (YJIT available)" if defined?(RubyVM::YJIT)}")
+        end
+      end
+
+      def check_node
+        return unless File.directory?(path("frontend"))
+
+        out, status = @run.call("node", "--version")
+        version = status.success? ? out.strip.delete_prefix("v") : nil
+        if version.nil?
+          problem("Node.js not found", "install Node.js #{MIN_NODE.join(".")}+ (the frontend is Next.js)")
+        elsif (version.split(".").map(&:to_i) <=> MIN_NODE).negative?
+          problem("Node.js #{version}", "Next.js 16 needs Node.js #{MIN_NODE.join(".")} or newer")
+        else
+          pass("Node.js #{version}")
+        end
+      rescue SystemCallError
+        problem("Node.js not found", "install Node.js #{MIN_NODE.join(".")}+ (the frontend is Next.js)")
+      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)
+
+        url = GemStack::DB.config.url
+        GemStack::DB.connection.test_connection
+        pass("PostgreSQL reachable (#{redact(url)})")
+        true
+      rescue StandardError => e
+        message = e.message.lines.first.to_s.strip
+        message = message.split(/FATAL:\s*/, 2).last if message.include?("FATAL:")
+        hint = if message.include?("does not exist") then "run: gemstack db:create"
+               else "is PostgreSQL running? Set DATABASE_URL (now #{redact(url.to_s)}) in .env or the environment"
+               end
+        problem("PostgreSQL: #{message}", hint)
+        false
+      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.config.jobs.adapter.to_s == "postgres"
+        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
+        env_check("DATABASE_URL", "the production PostgreSQL URL") 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_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?
+        %w[app/jobs/*.rb app/mailers/*.rb].any? { |glob| !Dir.glob(path(glob)).empty? }
+      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,122 @@
+# 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.
+      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,47 @@
+# 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
+        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