gemstack-cli 0.1.0

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

data/lib/gemstack/cli/resource_generator.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # Generates a vertical slice for a ResourceSpec from composable parts:
+    #
+    #   migration   db/migrations/<ts>_create_<table>.rb
+    #   model       app/models/<name>.rb + test/models/<name>_test.rb
+    #   serializer  app/serializers/<name>_serializer.rb
+    #   controller  app/controllers/<plural>_controller.rb + test + routes
+    #   frontend    Next.js pages, components and TanStack Query hooks
+    #
+    # `generate model` uses [migration, model, serializer]; `generate resource`
+    # uses all parts (minus backend or frontend with --frontend-only/--api-only).
+    # Every template can be overridden in lib/templates/gemstack/resource/<part>/.
+    class ResourceGenerator < Generator
+      PARTS = %i[migration model serializer controller frontend].freeze
+
+      # Frontend files that only make sense for some actions.
+      REQUIRES = {
+        "new/page.tsx" => %w[create], "[id]/edit/page.tsx" => %w[update], "[id]/page.tsx" => %w[show],
+        "Card.tsx" => %w[show], "Form.tsx" => %w[create update]
+      }.freeze
+
+      attr_reader :spec, :timestamp, :tests
+
+      def initialize(spec, root:, parts: PARTS, tests: true, output: $stdout, force: false, timestamp: nil)
+        super(output: output, force: force)
+        @spec = spec
+        @root = root
+        @parts = parts
+        @tests = tests
+        @timestamp = timestamp || Generator.migration_timestamp(root)
+      end
+
+      def run
+        @parts.each { |part| render_part(part) }
+        add_routes if @parts.include?(:controller)
+        self
+      end
+
+      # --- template helpers -------------------------------------------------
+
+      def fields = spec.fields
+      def class_name = spec.class_name
+      def input_type = spec.action?(:create) ? "#{class_name}Input" : "#{class_name}UpdateInput"
+
+      # Sequel schema DSL per field type ("%s" is the column name).
+      COLUMN_TYPES = {
+        "string" => "String :%s", "text" => "String :%s, text: true", "integer" => "Integer :%s",
+        "bigint" => "Bignum :%s", "float" => "Float :%s", "decimal" => "BigDecimal :%s, size: [12, 2]",
+        "date" => "Date :%s", "datetime" => "column :%s, :timestamptz", "uuid" => "column :%s, :uuid",
+        "json" => "column :%s, :jsonb"
+      }.freeze
+
+      def migration_column(field)
+        null = field.required? ? ", null: false" : ""
+        case field.type
+        when "references"
+          "foreign_key :#{field.column}, :#{field.referenced_table}, type: :Bignum#{null}, on_delete: :restrict"
+        when "boolean" then "TrueClass :#{field.name}, null: false, default: false"
+        else
+          unique = field.unique && field.type != "json" ? ", unique: true" : ""
+          format(COLUMN_TYPES.fetch(field.type), field.name) + null + unique
+        end
+      end
+
+      def model_field(field)
+        options = []
+        options << "null: false" if field.required?
+        options << "null: false, default: false" if field.type == "boolean"
+        options << "size: 255" if field.type == "string"
+        ["field :#{field.column}, :#{field.model_type}", *options].join(", ")
+      end
+
+      def ts_value_type(field) = field.type == "boolean" ? "boolean" : "string"
+
+      # Expression turning a record (possibly undefined) into a form value.
+      def form_initial(field)
+        attr = "record?.#{field.column}"
+        case field.type
+        when "boolean" then "#{attr} ?? false"
+        when "integer", "bigint", "float", "references" then "String(#{attr} ?? \"\")"
+        when "datetime" then "(#{attr} ?? \"\").slice(0, 16)"
+        when "json" then "#{attr} == null ? \"\" : JSON.stringify(#{attr}, null, 2)"
+        else "#{attr} ?? \"\""
+        end
+      end
+
+      # Expression turning a form value into an API input value.
+      def form_output(field)
+        value = "values.#{field.column}"
+        return value if field.type == "boolean"
+
+        converted =
+          case field.type
+          when "integer", "bigint", "float", "references" then "Number(#{value})"
+          when "json" then "parseJson(#{value})"
+          else value
+          end
+        blank = field.required? ? "\"\"" : "null"
+        converted == value && field.required? ? value : "#{value} === \"\" ? #{blank} : #{converted}"
+      end
+
+      def form_control(field)
+        key = field.column
+        common = %(id="#{field.column}" name="#{field.column}")
+        required = field.required? ? " required" : ""
+        case field.type
+        when "boolean"
+          %(<input #{common} type="checkbox" checked={values.#{key}} onChange={set("#{key}")} />)
+        when "text", "json"
+          %(<textarea #{common} rows={4} value={values.#{key}} onChange={set("#{key}")}#{required} />)
+        else
+          attrs = { "integer" => %(type="number" step="1"), "bigint" => %(type="number" step="1"),
+                    "references" => %(type="number" step="1"), "float" => %(type="number" step="any"),
+                    "decimal" => %(type="text" inputMode="decimal"), "date" => %(type="date"),
+                    "datetime" => %(type="datetime-local") }.fetch(field.type, %(type="text"))
+          %(<input #{common} #{attrs} value={values.#{key}} onChange={set("#{key}")}#{required} />)
+        end
+      end
+
+      def table_fields = fields.first(4)
+      def uses_json? = fields.any? { |f| f.type == "json" }
+
+      private
+
+      def render_part(part)
+        template_files("resource/#{part}", override_root: @root).sort.each do |rel, source|
+          next if skip?(part, rel)
+
+          target = File.join(@root, substitute(rel.delete_suffix(".tt")))
+          write(target, render(File.read(source), source))
+        end
+      end
+
+      def skip?(part, rel)
+        return true if !tests && rel.start_with?("test/")
+        return false unless part == :frontend
+
+        requirement = REQUIRES.find { |suffix, _| rel.delete_suffix(".tt").end_with?(suffix) }&.last
+        requirement ? requirement.none? { |action| spec.action?(action) } : false
+      end
+
+      def substitute(path)
+        path.gsub(/%(\w+)%/) do
+          key = ::Regexp.last_match(1)
+          key == "timestamp" ? timestamp : spec.public_send(key)
+        end
+      end
+
+      def add_routes
+        path = File.join(@root, "config/routes.rb")
+        return status("skip", path, "not found — add `resources :#{spec.plural}` manually") unless File.file?(path)
+
+        only = spec.crud? ? "" : ", only: %i[#{spec.actions.join(" ")}]"
+        line = "resources :#{spec.plural}#{only}"
+        content = File.read(path)
+        return status("identical", path) if content.match?(/^\s*resources :#{spec.plural}\b/)
+        unless content.match?(ControllerGenerator::ROUTES_BLOCK)
+          return status("skip", path, "no `GemStack.routes do` block — add `#{line}`")
+        end
+
+        File.write(path, content.sub(ControllerGenerator::ROUTES_BLOCK) { |open| "#{open}  #{line}\n" })
+        status("route", path, line)
+      end
+    end
+  end
+end

data/lib/gemstack/cli/resource_spec.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # Everything the model/migration/resource generators need to know about a
+    # resource, parsed once from the command line (ARCHITECTURE §7):
+    #
+    #   gemstack generate resource Product name:string price:decimal description:text:optional \
+    #                                      sku:string:unique category:references active:boolean
+    #
+    # Field syntax: name:type[:modifier...]. Fields are required (NOT NULL)
+    # unless marked :optional. Booleans default to false. Modifiers: optional,
+    # unique, index.
+    class ResourceSpec
+      TYPES = %w[string text integer bigint float decimal boolean date datetime uuid json references].freeze
+      MODIFIERS = %w[optional unique index].freeze
+      REST_ACTIONS = %w[index show create update destroy].freeze
+
+      Field = Struct.new(:name, :type, :optional, :unique, :index, keyword_init: true) do
+        def required? = !optional && type != "boolean"
+        def reference? = type == "references"
+        def column = reference? ? "#{name}_id" : name
+        def label = Inflector.humanize(name)
+        def referenced_class = Inflector.camelize(name)
+        def referenced_table = Inflector.pluralize(name)
+        def model_type = reference? ? "references" : type
+      end
+
+      attr_reader :name, :fields, :actions
+
+      def initialize(name, field_args = [], actions: REST_ACTIONS)
+        @name = Inflector.camelize(Inflector.singularize(name.to_s.delete_suffix("Controller")))
+        unless @name.match?(/\A[A-Z][A-Za-z0-9]*\z/)
+          raise Thor::Error,
+                "Invalid resource name #{name.inspect}: use a single CamelCase or snake_case name (e.g. Product)"
+        end
+
+        Generator.check_constant!(@name, suggestion: "#{@name}Record") unless @name == "Migration"
+        @fields = field_args.map { |arg| parse_field(arg) }
+        duplicates = @fields.group_by(&:column).select { |_, list| list.size > 1 }.keys
+        raise Thor::Error, "Duplicate field(s): #{duplicates.join(", ")}" unless duplicates.empty?
+
+        @actions = actions.map(&:to_s)
+        invalid = @actions - REST_ACTIONS
+        return if invalid.empty?
+
+        raise Thor::Error,
+              "Unknown action(s) #{invalid.join(", ")}; resources support #{REST_ACTIONS.join(", ")}"
+      end
+
+      # Product / LineItem examples:
+      #   class_name Product · file_name product · plural products · plural_class Products
+      #   url_segment line-items · client_name lineItems · variable lineItem · human "Line item"
+      def class_name = name
+      def file_name = Inflector.underscore(name)
+      def plural = Inflector.pluralize(file_name)
+      def table = plural
+      def plural_class = Inflector.camelize(plural)
+      def url_segment = Inflector.dasherize(plural)
+      def client_name = lower_camel(plural)
+      def variable = lower_camel(file_name)
+      def human = Inflector.humanize(file_name)
+      def human_plural = Inflector.humanize(plural)
+
+      def action?(action) = actions.include?(action.to_s)
+      def crud? = actions.sort == REST_ACTIONS.sort
+      def references = fields.select(&:reference?)
+
+      private
+
+      def parse_field(arg)
+        name, type, *mods = arg.to_s.split(":")
+        type ||= "string"
+        type = "references" if type == "belongs_to"
+        raise Thor::Error, "Invalid field name in #{arg.inspect}" unless name&.match?(/\A[a-z][a-z0-9_]*\z/)
+        unless TYPES.include?(type)
+          raise Thor::Error,
+                "Unknown type #{type.inspect} in #{arg.inspect}; types: #{TYPES.join(", ")}"
+        end
+
+        unknown = mods - MODIFIERS
+        raise Thor::Error, "Unknown modifier(s) #{unknown.join(", ")} in #{arg.inspect}" unless unknown.empty?
+
+        name = name.delete_suffix("_id") if type == "references"
+        Field.new(name: name, type: type, optional: mods.include?("optional"), unique: mods.include?("unique"),
+                  index: mods.include?("index") || type == "references")
+      end
+
+      def lower_camel(term)
+        camel = Inflector.camelize(term)
+        camel[0].downcase + camel[1..]
+      end
+    end
+  end
+end

data/lib/gemstack/cli.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "thor"
+require "gemstack/core"
+
+module GemStack
+  # The `gemstack` command.
+  class CLI < Thor
+    require_relative "cli/project"
+    require_relative "cli/generator"
+    require_relative "cli/app_generator"
+    require_relative "cli/controller_generator"
+    require_relative "cli/resource_spec"
+    require_relative "cli/resource_generator"
+    require_relative "cli/migration_generator"
+    require_relative "cli/job_generator"
+    require_relative "cli/policy_generator"
+    require_relative "cli/doctor"
+    require_relative "cli/deploy_generator"
+    require_relative "cli/add_generator"
+    require_relative "cli/commands/db"
+    require_relative "cli/commands/jobs"
+
+    # Commands that need the application's bundle (see Project.ensure_bundle!).
+    class << self
+      attr_accessor :argv
+
+      def start(given_args = ARGV, config = {})
+        self.argv = given_args.dup
+        super
+      end
+
+      def exit_on_failure? = true
+
+      # Shown in help output regardless of how the CLI was launched.
+      def basename = "gemstack"
+    end
+
+    GENERATORS = "resource, model, migration, controller, job, policy, deploy"
+
+    map %w[-v --version] => :version
+    map "s" => :server
+    map "c" => :console
+    map "t" => :test
+    map "g" => :generate
+
+    desc "new NAME", "Create a new GemStack application (Ruby API + Next.js frontend)"
+    long_desc <<~DESC
+      Creates NAME/ with a Ruby API, a Next.js + TypeScript frontend and no business resources.
+
+      Then: cd NAME && gemstack dev
+    DESC
+    method_option :skip_install, type: :boolean, default: false, desc: "Don't run bundle install / npm install"
+    method_option :skip_git, type: :boolean, default: false, desc: "Don't initialise a git repository"
+    method_option :skip_frontend, type: :boolean, default: false, desc: "API only: no Next.js frontend"
+    method_option :skip_database, type: :boolean, default: false, desc: "No PostgreSQL / gemstack-db"
+    method_option :gemstack_path, type: :string, desc: "Use GemStack from a local checkout (its gems/ directory)"
+    def new(name)
+      AppGenerator.new(name, options.transform_keys(&:to_sym)).run
+    end
+
+    desc "dev", "Run the application: Next.js + Ruby API behind one origin (http://localhost:3000)"
+    def dev
+      root = Project.ensure_bundle!(self.class.argv)
+      ENV["GEMSTACK_ENV"] ||= "development"
+      Project.load_config!(root)
+      require "gemstack/dev"
+      Dev::Supervisor.new(root: root).run
+    rescue GemStack::Error => e
+      abort("gemstack dev: #{e.message}")
+    end
+
+    desc "server", "Run only the Ruby API with Puma (alias: s)"
+    method_option :port, aliases: "-p", type: :numeric, desc: "Port (default: GEMSTACK_API_PORT or 4000)"
+    def server
+      root = Project.ensure_bundle!(self.class.argv)
+      env = {}
+      env["GEMSTACK_API_PORT"] = options[:port].to_s if options[:port]
+      env["GEMSTACK_ENV"] = options[:environment] if options[:environment]
+      exec(env, "bundle", "exec", "puma", "-C", File.join(root, "config/puma.rb"))
+    end
+
+    desc "routes", "List API routes"
+    method_option :grep, aliases: "-g", type: :string, desc: "Only routes matching this text"
+    def routes
+      root = Project.ensure_bundle!(self.class.argv)
+      ENV["GEMSTACK_ENV"] ||= "development"
+      Project.load_config!(root)
+      GemStack.config.reload_code = false
+      GemStack.config.logger.level = :warn
+      GemStack.config.db.log_queries = false if GemStack.config.respond_to?(:db)
+      rows = GemStack.boot!.routes.map { |r| [r.verb, r.path, r.target] }
+      rows.select! { |row| row.join(" ").include?(options[:grep]) } if options[:grep]
+      return say("No routes defined. Add them to config/routes.rb.") if rows.empty?
+
+      print_table(rows)
+    end
+
+    desc "console", "Start an IRB session with the application loaded (alias: c)"
+    def console
+      root = Project.ensure_bundle!(self.class.argv)
+      ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+      Project.load_config!(root)
+      GemStack.boot!
+      require "irb"
+      say("GemStack #{GemStack::VERSION} console (#{GemStack.env}). `GemStack.application.reload!` reloads code.")
+      ARGV.clear
+      IRB.start
+    end
+
+    desc "test [FILES...]", "Run the Ruby test suite (alias: t)"
+    def test(*files)
+      root = Project.ensure_bundle!(self.class.argv)
+      files = Dir.glob("test/**/*_test.rb", base: root).sort if files.empty?
+      return say("No tests found in test/.") if files.empty?
+
+      loader = "ARGV.each { |f| require File.expand_path(f) }"
+      exec({ "GEMSTACK_ENV" => "test" }, RbConfig.ruby, "-Itest", "-e", loader, *files)
+    end
+
+    desc "generate GENERATOR NAME [ARGS]",
+         "Generate code (alias: g). Generators: resource, model, migration, controller, job, policy, deploy"
+    long_desc <<~DESC
+      gemstack generate resource Product name:string price:decimal description:text:optional active:boolean
+        Full vertical slice: migration, model, serializer, controller, routes, tests,
+        TypeScript client (via the contract) and Next.js pages. Without fields it asks interactively.
+        --api-only            backend only
+        --frontend-only       Next.js pages/components only (for an existing backend resource)
+        --actions=index,show  a subset of index,show,create,update,destroy (default: all = --crud)
+        --skip-tests
+
+      gemstack generate model Product name:string price:decimal
+        Migration, model, serializer and model test.
+
+      gemstack generate migration AddSkuToProducts sku:string:unique
+
+      gemstack generate controller Products index show publish
+
+      gemstack generate job SendWelcomeEmail [QUEUE]
+        app/jobs/send_welcome_email.rb + test (+ the gemstack_jobs migration the first time)
+
+      gemstack generate policy Order
+        app/policies/order_policy.rb + test (needs gemstack add auth)
+
+      gemstack generate deploy
+        Dockerfile (api + web images), compose.yaml, Caddyfile, Procfile, .dockerignore
+
+      Field syntax: name:type[:optional][:unique][:index]. Types: #{ResourceSpec::TYPES.join(", ")}.
+      Fields are required unless marked :optional.
+    DESC
+    method_option :api_only, type: :boolean, default: false, desc: "resource: backend only"
+    method_option :frontend_only, type: :boolean, default: false, desc: "resource: frontend only"
+    method_option :crud, type: :boolean, default: false, desc: "resource: all REST actions (the default)"
+    method_option :actions, type: :string, desc: "resource: comma-separated subset of REST actions"
+    method_option :skip_tests, type: :boolean, default: false
+    method_option :skip_contract, type: :boolean, default: false, desc: "don't regenerate the TypeScript contract"
+    method_option :force, type: :boolean, default: false, desc: "overwrite existing files"
+    def generate(generator = nil, name = nil, *args)
+      root = Project.root!
+      case generator
+      when "controller"
+        abort("Usage: gemstack generate controller NAME [ACTIONS...]") unless name
+        ControllerGenerator.new(name, args, root: root, force: options[:force]).run
+      when "model" then generate_model(root, name, args)
+      when "resource" then generate_resource(root, name, args)
+      when "migration"
+        abort("Usage: gemstack generate migration NAME [field:type ...]") unless name
+        MigrationGenerator.new(name, args, root: root).run
+      when "job" then generate_job(root, name, args)
+      when "policy" then generate_policy(root, name)
+      when "deploy"
+        DeployGenerator.new(root: root, force: options[:force]).run
+        say("\nNext: docker compose up --build (see compose.yaml) · recipes: docs/deployment.md")
+      when nil then abort("Usage: gemstack generate GENERATOR NAME. Generators: #{GENERATORS}")
+      else abort("Unknown generator #{generator.inspect}. Available: #{GENERATORS}")
+      end
+    end
+
+    desc "add FEATURE", "Add an optional module to this app: realtime, auth, storage"
+    long_desc <<~DESC
+      gemstack add realtime
+        Adds gemstack-realtime, config/channels.rb, frontend/lib/gemstack/realtime.ts and test helpers.
+
+      gemstack add auth
+        Sign up, log in/out, password reset and email verification, API tokens and policies:
+        migrations (users, sessions, auth_tokens), User model, controllers, routes, AuthMailer,
+        tests and Next.js pages (/login, /signup, /forgot-password, /reset-password, /verify-email, /account).
+
+      gemstack add storage
+        File uploads straight from the browser to disk (development) or S3: config, uploads
+        controller, routes and frontend/lib/upload.ts.
+    DESC
+    method_option :skip_install, type: :boolean, default: false
+    method_option :skip_contract, type: :boolean, default: false, desc: "don't regenerate the TypeScript contract"
+    def add(feature)
+      root = Project.root!
+      AddGenerator.new(feature, root: root, install: !options[:skip_install]).run
+      refresh_contract(root) if %w[auth
+                                   storage].include?(feature) && !options[:skip_install] && !options[:skip_contract]
+      say("\n#{ADD_NEXT_STEPS.fetch(feature)}")
+    end
+
+    ADD_NEXT_STEPS = {
+      "realtime" => "Next: declare channels in config/channels.rb, then GemStack.broadcast(...) — see docs/realtime.md",
+      "auth" => "Next: gemstack db:migrate · open http://localhost:3000/signup · " \
+                "`before :require_login` in controllers — see docs/authentication.md",
+      "storage" => "Next: uploadFile(file) from frontend/lib/upload.ts · production: STORAGE_SERVICE=s3, S3_BUCKET " \
+                   "— see docs/storage.md"
+    }.freeze
+
+    desc "doctor", "Check that this app can run (Ruby, Node, database, migrations, contract…) and how to fix it"
+    long_desc <<~DESC
+      gemstack doctor               checks for development
+      gemstack doctor --production  also checks the settings a deploy needs (run it with the production
+                                    environment variables: SECRET_KEY_BASE, DATABASE_URL, SMTP_URL…)
+    DESC
+    method_option :production, type: :boolean, default: false
+    def doctor
+      root = Project.ensure_bundle!(self.class.argv)
+      exit(1) unless Doctor.new(root: root, production: options[:production]).run.ok?
+    end
+
+    desc "version", "Print the GemStack version"
+    def version
+      say("GemStack #{GemStack::VERSION}")
+    end
+
+    no_commands do
+      def generate_model(root, name, args)
+        abort("Usage: gemstack generate model NAME field:type ...") unless name && !args.empty?
+        spec = ResourceSpec.new(name, args)
+        ResourceGenerator.new(spec, root: root, parts: %i[migration model serializer], tests: !options[:skip_tests],
+                                    force: options[:force]).run
+        say("\nNext: gemstack db:migrate")
+      end
+
+      def generate_job(root, name, args)
+        abort("Usage: gemstack generate job NAME [QUEUE]") unless name
+        JobGenerator.new(name, queue: args.first, root: root, force: options[:force]).run
+        say("\nNext: gemstack db:migrate (first job only) · #{Inflector.camelize(name)}.perform_later(...)")
+      end
+
+      def generate_policy(root, name)
+        abort("Usage: gemstack generate policy MODEL") unless name
+        PolicyGenerator.new(name, root: root, force: options[:force]).run
+        say("\nNext: authorize!(record) and policy_scope(#{Inflector.camelize(name)}) in controllers")
+      end
+
+      def generate_resource(root, name, args)
+        abort("Usage: gemstack generate resource NAME field:type ...") unless name
+        abort("--api-only and --frontend-only can't be combined") if options[:api_only] && options[:frontend_only]
+        interactive = args.empty? && $stdin.tty?
+        args = ask("Fields (e.g. name:string price:decimal description:text:optional):").split if interactive
+        abort("Give at least one field, e.g. `gemstack generate resource #{name} name:string`") if args.empty?
+
+        spec = ResourceSpec.new(name, args, actions: resource_actions(interactive))
+        parts = resource_parts(root, interactive)
+        tests = !options[:skip_tests] && (!interactive || yes?("Generate tests? [Y/n]"))
+        ResourceGenerator.new(spec, root: root, parts: parts, tests: tests, force: options[:force]).run
+        refresh_contract(root) unless options[:skip_contract]
+        page = " · open http://localhost:3000/#{spec.url_segment}" if parts.include?(:frontend)
+        say("\nNext: gemstack db:migrate#{page}")
+      end
+
+      def resource_parts(root, interactive)
+        parts = options[:frontend_only] ? [] : %i[migration model serializer controller]
+        frontend = File.directory?(File.join(root, "frontend")) && !options[:api_only]
+        frontend &&= yes?("Generate Next.js pages? [Y/n]") if interactive
+        frontend ? parts + [:frontend] : parts
+      end
+
+      def resource_actions(interactive)
+        return options[:actions].split(",").map(&:strip) if options[:actions]
+        return ResourceSpec::REST_ACTIONS if !interactive || yes?("Generate the full CRUD API? [Y/n]")
+
+        ask("Actions (comma-separated from #{ResourceSpec::REST_ACTIONS.join(",")}):").split(",").map(&:strip)
+      end
+
+      # Thor's yes? only accepts y/yes; treat an empty answer as "yes".
+      def yes?(question)
+        answer = ask(question).strip.downcase
+        answer.empty? || %w[y yes].include?(answer)
+      end
+
+      # Regenerates TypeScript types/clients in the app's own bundle.
+      def refresh_contract(root)
+        say("  #{"run".rjust(9)}  gemstack contract")
+        ok = (defined?(Bundler) ? Bundler.with_unbundled_env { contract_command(root) } : contract_command(root))
+        return if ok
+
+        say("  #{"warning".rjust(9)}  contract not generated — run `gemstack contract` once the database is reachable")
+      end
+
+      def contract_command(root)
+        system("bundle", "exec", "gemstack", "contract", "--quiet", chdir: root)
+      end
+    end
+  end
+end

data/templates/app/Gemfile.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+<% if gemstack_path -%>
+# GemStack from a local checkout.
+path "<%= gemstack_path %>" do
+  gem "gemstack"
+  gem "gemstack-cache"
+  gem "gemstack-cli"
+  gem "gemstack-contract"
+  gem "gemstack-core"
+<% if database? -%>
+  gem "gemstack-db"
+<% end -%>
+  gem "gemstack-jobs"
+  gem "gemstack-dev"
+  gem "gemstack-http"
+  gem "gemstack-schema"
+end
+<% else -%>
+gem "gemstack", "~> <%= version %>"
+<% if database? -%>
+gem "gemstack-db", "~> <%= version %>"
+<% end -%>
+gem "gemstack-jobs", "~> <%= version %>"
+<% end -%>
+gem "puma", ">= 6.4"
+
+# Any gem works here as usual, e.g.:
+# gem "brotli"         # Brotli compression (gzip is used without it)
+# gem "redis-client"   # shared cache: config.cache.store = :redis
+# gem "stripe"
+
+group :development, :test do
+  gem "irb" # `gemstack console`; a bundled (not default) gem since Ruby 4.0
+  gem "minitest", "~> 5.25"
+  gem "rack-test", "~> 2.2"
+end