gemstack 0.2.5 → 0.3.0

data/lib/gemstack/storage.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+require "json"
+require "time"
+require "gemstack/core"
+require "gemstack/http"
+
+module GemStack
+  # File storage: files go from the browser straight to
+  # the storage service, never through a Ruby process.
+  #
+  #   # POST /api/uploads → presigned upload for the browser
+  #   upload = GemStack::Storage.direct_upload(filename: "cat.png", content_type: "image/png", byte_size: 52_000)
+  #   # browser: PUT the file to upload[:url] with upload[:headers]
+  #   # later:   product.update(image_key: GemStack::Storage.key_for_signed_id(params[:image]))
+  #   GemStack::Storage.url(product.image_key)   # short-lived signed download URL
+  #
+  # Services: :disk (development and tests; files under storage/, served and
+  # accepted by a signed endpoint at /api/storage) and :s3 (S3, R2, MinIO…).
+  module Storage
+    class Config < Settings
+      # :disk, :s3, or a service object.
+      setting :service, default: -> { ENV.fetch("STORAGE_SERVICE", GemStack.env.production? ? "s3" : "disk").to_sym }
+      setting :root, default: -> { File.join(GemStack.config.root, "storage", GemStack.env.test? ? "test" : "") }
+      # Where the disk service's signed URLs point (handled by Storage::Endpoint).
+      setting :path, default: -> { "#{GemStack.config.http.api_path}/storage" }
+      setting :bucket, default: -> { ENV.fetch("S3_BUCKET", nil) }
+      setting :region, default: -> { ENV.fetch("AWS_REGION", ENV.fetch("S3_REGION", "us-east-1")) }
+      # For S3-compatible services: https://<account>.r2.cloudflarestorage.com, http://localhost:9000
+      setting :endpoint, default: -> { ENV.fetch("S3_ENDPOINT", nil) }
+      # Credentials come from the usual AWS chain (AWS_ACCESS_KEY_ID…, instance roles) unless set.
+      setting :s3_options, default: {}
+      setting :url_expires_in, default: 300
+      setting :max_upload_size, default: 10 * 1024 * 1024
+      # MIME types accepted by direct_upload ("image/*" style wildcards).
+      # SVG and HTML are excluded on purpose: they can carry scripts.
+      setting :allowed_content_types, default: %w[image/png image/jpeg image/gif image/webp image/avif application/pdf]
+    end
+
+    class InvalidUpload < ValidationError; end
+
+    # Served inline by browsers; everything else is sent as an attachment.
+    INLINE_TYPES = %w[image/png image/jpeg image/gif image/webp image/avif application/pdf text/plain].freeze
+
+    class << self
+      def config = GemStack.config.storage
+
+      def service
+        @service ||= build_service(config.service)
+      end
+
+      attr_writer :service
+
+      def reset! = @service = nil
+
+      # Validates an upload request and returns what the browser needs:
+      #   { key:, signed_id:, url:, method: "PUT", headers: {…} }
+      def direct_upload(filename:, content_type:, byte_size:, prefix: "uploads")
+        content_type = content_type.to_s.downcase.split(";").first.to_s.strip
+        byte_size = Integer(byte_size, exception: false)
+        validate_upload!(content_type, byte_size)
+
+        key = generate_key(prefix, filename, content_type)
+        upload = service.presigned_upload(key, content_type: content_type, byte_size: byte_size,
+                                               expires_in: config.url_expires_in)
+        { key: key, signed_id: sign(key, purpose: "upload"), **upload }
+      end
+
+      # The key behind a signed_id from direct_upload; 422 when tampered with
+      # (so clients can't point records at other people's files).
+      def key_for_signed_id(signed_id)
+        verify(signed_id, purpose: "upload") ||
+          raise(InvalidUpload.new("Invalid upload reference", errors: { file: ["is invalid"] }))
+      end
+
+      def url(key, expires_in: config.url_expires_in, disposition: nil, filename: nil)
+        service.url(key, expires_in: expires_in, disposition: disposition || disposition_for(key), filename: filename)
+      end
+
+      def upload(key, io, content_type:) = service.upload(key, io, content_type: content_type)
+      def download(key) = service.download(key)
+      def delete(key) = service.delete(key)
+      def exist?(key) = service.exist?(key)
+
+      def allowed_content_type?(type)
+        Array(config.allowed_content_types).any? do |pattern|
+          pattern.end_with?("/*") ? type.start_with?(pattern.delete_suffix("*")) : type == pattern
+        end
+      end
+
+      # Tamper-proof, expiring tokens (HMAC with GemStack.key_for("storage")).
+      def sign(value, purpose:, expires_in: nil)
+        payload = { "v" => value, "p" => purpose }
+        payload["e"] = Time.now.to_i + expires_in if expires_in
+        data = [JSON.generate(payload)].pack("m0").tr("+/", "-_").delete("=")
+        "#{data}--#{digest(data)}"
+      end
+
+      def verify(token, purpose:)
+        data, mac = token.to_s.split("--", 2)
+        return nil unless data && mac && OpenSSL.fixed_length_secure_compare(digest(data), mac)
+
+        payload = JSON.parse(data.tr("-_", "+/").ljust((data.length + 3) & ~3, "=").unpack1("m0"))
+        return nil unless payload["p"] == purpose
+        return nil if payload["e"] && payload["e"] < Time.now.to_i
+
+        payload["v"]
+      rescue ArgumentError, JSON::ParserError
+        nil
+      end
+
+      # Keys are ours, not the client's: uploads/2026/09/<uuid>/<clean name>.
+      # The extension always matches the validated content type, so a file
+      # declared as image/png can't be served as HTML because it's named x.html.
+      def generate_key(prefix, filename, content_type)
+        base = File.basename(filename.to_s, ".*").unicode_normalize(:nfkc).gsub(/[^\w-]+/, "-").gsub(/\A-+|-+\z/, "")
+        base = "file" if base.empty?
+        [prefix, Time.now.utc.strftime("%Y/%m"), SecureRandom.uuid, "#{base[0, 100]}#{extension_for(content_type)}"]
+          .reject(&:empty?).join("/")
+      end
+
+      EXTENSIONS = { "image/jpeg" => ".jpg", "image/png" => ".png", "image/gif" => ".gif", "image/webp" => ".webp",
+                     "image/avif" => ".avif", "application/pdf" => ".pdf", "text/plain" => ".txt",
+                     "text/csv" => ".csv" }.freeze
+
+      def extension_for(content_type) = EXTENSIONS[content_type] || Rack::Mime::MIME_TYPES.key(content_type) || ".bin"
+
+      def content_type_for(key) = Rack::Mime.mime_type(File.extname(key.to_s), "application/octet-stream")
+
+      private
+
+      def build_service(service)
+        case service
+        when :disk, "disk" then Services::Disk.new(root: config.root, path: config.path)
+        when :s3, "s3"
+          require_relative "storage/services/s3"
+          Services::S3.new(bucket: config.bucket, region: config.region, endpoint: config.endpoint,
+                           **config.s3_options)
+        else
+          unless service.respond_to?(:presigned_upload)
+            raise ConfigurationError, "unknown config.storage.service #{service.inspect} (use :disk, :s3 or an object)"
+          end
+
+          service
+        end
+      end
+
+      def validate_upload!(content_type, byte_size)
+        errors = {}
+        errors[:content_type] = ["#{content_type.inspect} is not allowed"] unless allowed_content_type?(content_type)
+        max = config.max_upload_size
+        if byte_size.nil? || byte_size <= 0
+          errors[:byte_size] = ["must be a positive number of bytes"]
+        elsif byte_size > max
+          errors[:byte_size] = ["is too large (maximum #{max / 1024 / 1024} MB)"]
+        end
+        raise InvalidUpload.new("Upload refused", errors: errors) unless errors.empty?
+      end
+
+      # Browsers show images and PDFs inline; anything else downloads.
+      def disposition_for(key) = INLINE_TYPES.include?(content_type_for(key)) ? "inline" : "attachment"
+
+      def digest(data) = OpenSSL::HMAC.hexdigest("SHA256", GemStack.key_for("storage"), data)
+    end
+  end
+end
+
+require_relative "storage/services/disk"
+require_relative "storage/endpoint"
+
+GemStack::Config.namespace(:storage, GemStack::Storage::Config)
+
+GemStack::Plugins.register(:storage) do |app|
+  next unless app.respond_to?(:config)
+
+  stack = app.config.http.middleware
+  # Before BodyLimit: signed uploads carry their own size limit.
+  unless stack.include?(GemStack::Storage::Endpoint)
+    stack.insert_before(GemStack::HTTP::Middleware::BodyLimit, GemStack::Storage::Endpoint)
+  end
+end

data/lib/gemstack/types.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "time"
+
+module GemStack
+  # The type system shared by model fields, request schemas, serializers and
+  # the TypeScript/OpenAPI generators — one name per concept everywhere:
+  #
+  #   field :price, :decimal          (model)
+  #   required :price, :decimal       (request schema)
+  #   attribute :price, :decimal      (serializer)
+  #   price: string                   (generated TypeScript)
+  #
+  # Each type knows how to coerce input (strings from forms and query strings,
+  # JSON values), how to dump values into JSON, and its TypeScript / OpenAPI
+  # representation. Register your own with Types.register.
+  module Types
+    # Raised by a coercer when a value can't be converted; the message is the
+    # client-facing validation message ("must be an integer").
+    class CoercionError < StandardError; end
+
+    Type = Struct.new(:name, :ts, :openapi, :coercer, :dumper, keyword_init: true) do
+      def coerce(value) = coercer ? coercer.call(value) : value
+      def dump(value) = value.nil? || dumper.nil? ? value : dumper.call(value)
+    end
+
+    INTEGER = /\A[-+]?\d+\z/
+    NUMBER = /\A[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?\z/
+    UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/i
+    TRUE_VALUES = [true, 1, "1", "true", "TRUE", "True", "on", "yes"].freeze
+    FALSE_VALUES = [false, 0, "0", "false", "FALSE", "False", "off", "no"].freeze
+
+    CLASS_ALIASES = {
+      String => :string, Integer => :integer, Float => :float, BigDecimal => :decimal,
+      TrueClass => :boolean, FalseClass => :boolean, Date => :date, Time => :datetime,
+      DateTime => :datetime, Hash => :json
+    }.freeze
+
+    @registry = {}
+
+    class << self
+      def register(name, ts:, openapi:, coerce: nil, dump: nil)
+        @registry[name.to_sym] = Type.new(name: name.to_sym, ts: ts, openapi: openapi.freeze,
+                                          coercer: coerce, dumper: dump).freeze
+      end
+
+      # Accepts a type name (:string) or a Ruby class (String, Integer, ...).
+      def fetch(name)
+        key = CLASS_ALIASES.fetch(name, name)
+        @registry.fetch(key.to_sym) do
+          raise ArgumentError, "unknown type #{name.inspect}; known types: #{@registry.keys.join(", ")}"
+        end
+      end
+
+      def type?(name)
+        CLASS_ALIASES.key?(name) || ((name.is_a?(Symbol) || name.is_a?(String)) && @registry.key?(name.to_sym))
+      end
+
+      def names = @registry.keys
+
+      def fail!(message) = raise(CoercionError, message)
+
+      def to_integer(value)
+        case value
+        when Integer then value
+        when Float then value == value.floor ? value.to_i : fail!("must be an integer")
+        when String then value.strip.match?(INTEGER) ? Integer(value.strip, 10) : fail!("must be an integer")
+        else fail!("must be an integer")
+        end
+      end
+
+      def to_float(value)
+        case value
+        when Float then value
+        when Numeric then value.to_f
+        when String then value.strip.match?(NUMBER) ? Float(value.strip) : fail!("must be a number")
+        else fail!("must be a number")
+        end
+      end
+
+      def to_decimal(value)
+        case value
+        when BigDecimal then value
+        when Integer then BigDecimal(value)
+        when Float then BigDecimal(value.to_s)
+        when String then value.strip.match?(NUMBER) ? BigDecimal(value.strip) : fail!("must be a decimal number")
+        else fail!("must be a decimal number")
+        end
+      end
+
+      def to_boolean(value)
+        return true if TRUE_VALUES.include?(value)
+        return false if FALSE_VALUES.include?(value)
+
+        fail!("must be true or false")
+      end
+
+      def to_date(value)
+        case value
+        when DateTime, Time then value.to_date
+        when Date then value
+        when String then Date.iso8601(value.strip)
+        else fail!("must be a date (YYYY-MM-DD)")
+        end
+      rescue ArgumentError # includes Date::Error
+        fail!("must be a date (YYYY-MM-DD)")
+      end
+
+      def to_datetime(value)
+        case value
+        when Time then value
+        when DateTime then value.to_time
+        when String then parse_time(value.strip)
+        else fail!("must be a date-time (ISO 8601)")
+        end
+      end
+
+      private
+
+      # ISO 8601 with a zone, or a zone-less "YYYY-MM-DDTHH:MM[:SS]" (as sent
+      # by <input type="datetime-local">), which is read as UTC.
+      def parse_time(string)
+        Time.iso8601(string)
+      rescue ArgumentError
+        match = string.match(/\A(\d{4})-(\d\d)-(\d\d)[T ](\d\d):(\d\d)(?::(\d\d))?\z/)
+        fail!("must be a date-time (ISO 8601)") unless match
+        Time.utc(*match.captures.compact.map(&:to_i))
+      end
+    end
+
+    string = lambda do |value|
+      case value
+      when String then value
+      when Symbol, Numeric then value.to_s
+      else fail!("must be a string")
+      end
+    end
+    iso_time = ->(value) { (value.respond_to?(:to_time) ? value.to_time : value).utc.iso8601(3) }
+
+    register :string, ts: "string", openapi: { type: "string" }, coerce: string
+    register :text, ts: "string", openapi: { type: "string" }, coerce: string
+    register :integer, ts: "number", openapi: { type: "integer" }, coerce: method(:to_integer)
+    register :bigint, ts: "number", openapi: { type: "integer", format: "int64" }, coerce: method(:to_integer)
+    register :references, ts: "number", openapi: { type: "integer", format: "int64" }, coerce: method(:to_integer)
+    register :float, ts: "number", openapi: { type: "number" }, coerce: method(:to_float)
+    # Decimals travel as strings so no precision is lost in JavaScript.
+    register :decimal, ts: "string", openapi: { type: "string", format: "decimal" },
+                       coerce: method(:to_decimal),
+                       dump: ->(value) { (value.is_a?(BigDecimal) ? value : BigDecimal(value.to_s)).to_s("F") }
+    register :boolean, ts: "boolean", openapi: { type: "boolean" }, coerce: method(:to_boolean)
+    register :date, ts: "string", openapi: { type: "string", format: "date" },
+                    coerce: method(:to_date), dump: lambda(&:iso8601)
+    register :datetime, ts: "string", openapi: { type: "string", format: "date-time" },
+                        coerce: method(:to_datetime), dump: iso_time
+    register :uuid, ts: "string", openapi: { type: "string", format: "uuid" },
+                    coerce: lambda { |value|
+                      value.is_a?(String) && value.match?(UUID) ? value.downcase : fail!("must be a UUID")
+                    }
+    register :json, ts: "unknown", openapi: {}
+  end
+end

data/lib/gemstack/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module GemStack
+  # All GemStack gems are released together under a single version.
+  VERSION = "0.3.0"
+end

data/lib/gemstack.rb

@@ -33,7 +33,7 @@ module GemStack
   #   class ApplicationController < GemStack::Controller
   Controller = HTTP::Controller
   Params = HTTP::Params
-  # GemStack::Schema, GemStack::Serializer and GemStack::Types come from gemstack-schema.
+  # GemStack::Schema, GemStack::Serializer and GemStack::Types come from gemstack/schema.
 
   class << self
     def application

data/templates/app/Gemfile.tt

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+<% if gemstack_path -%>
+# GemStack from a local checkout.
+path "<%= gemstack_path %>" do
+  gem "gemstack"
+end
+<% else -%>
+gem "gemstack", "~> <%= version %>" # the framework: config/app.rb chooses the modules it loads
+<% end -%>
+gem "puma", ">= 6.4"
+<% if database? -%>
+gem "<%= driver_gem %>", "<%= driver_version %>" # the <%= database_adapter %> driver (config/database.yml)
+<% end -%>
+
+# 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 gem, not a default one, in newer Rubies)
+  gem "minitest", "~> 5.25"
+  gem "rack-test", "~> 2.2"
+end

data/templates/app/README.md.tt

@@ -0,0 +1,29 @@
+# <%= module_name %>
+
+A [GemStack](https://github.com/gemstack/gemstack) application: a Ruby API with a
+Next.js + TypeScript frontend, served from one origin.
+
+```bash
+gemstack dev          # http://localhost:3000  (/api/* → Ruby, everything else → Next.js)
+gemstack routes       # list API routes
+gemstack test         # run the Ruby tests
+gemstack console      # IRB with the app loaded
+gemstack generate controller Status show
+```
+
+## Layout
+
+| Path | What lives there |
+|---|---|
+| `config/app.rb` | configuration (`GemStack.configure`) |
+| `config/routes.rb` | API routes, relative to `/api` |
+| `app/` | autoloaded code: `controllers/`, and any folder you add (`services/`, ...) |
+| `test/` | Minitest + rack-test (`GemStack::TestCase`) |
+| `frontend/` | the Next.js app; `lib/gemstack/client.ts` talks to the API |
+
+## Production
+
+Run the API with `gemstack server` (Puma, `config/puma.rb`) and the frontend
+with `npm run build && npm start` in `frontend/`. Either route `/api/*` to the
+API with your reverse proxy, or set `GEMSTACK_API_URL` for the Next.js process
+and it will proxy `/api/*` itself.

data/templates/app/app/controllers/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Shared behaviour for every controller: before callbacks (e.g. authentication),
+# rescue_from handlers and helpers.
+class ApplicationController < GemStack::Controller
+end

data/templates/app/app/jobs/application_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The base class for this app's background jobs (docs/background-jobs.md):
+# retry and discard rules declared here apply to every job.
+class ApplicationJob < GemStack::Job
+  # retry_on Net::ReadTimeout, attempts: 5, wait: 30   # seconds, :exponential or ->(attempt) { … }
+  # discard_on GemStack::NotFound                      # e.g. the record was deleted before the job ran
+  # queue :default
+end

data/templates/app/app/mailers/application_mailer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# The base class for this app's mailers (docs/mail.md). Templates live in
+# app/mailers/templates/<mailer>/<action>.{text,html}.erb.
+class ApplicationMailer < GemStack::Mailer
+  # default from: "My App <hello@example.com>"          # otherwise config.mail.default_from (MAIL_FROM)
+  # default reply_to: "support@example.com"
+end

data/templates/app/app/models/application_model.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# The base class for this app's models — add plugins, validations and helpers
+# every model should share here. `class Product < ApplicationModel` maps to the
+# products table (docs/models.md).
+#
+# Created with Class.new on purpose: `class ApplicationModel < GemStack::Model`
+# would make Sequel look for an "application_models" table.
+ApplicationModel = Class.new(GemStack::Model) # rubocop:disable Style/EmptyClassDefinition
+
+class ApplicationModel
+  # Sequel plugins for every model, e.g.:
+  # plugin :dirty                                    # previous values after an update (column_changes)
+
+  # Shared query helpers:
+  # dataset_module do
+  #   def recent = order(Sequel.desc(:created_at))
+  # end
+end

data/templates/app/app/serializers/application_serializer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The base class for this app's serializers (docs/serialization.md): attributes
+# and helpers defined here are shared by every serializer.
+class ApplicationSerializer < GemStack::Serializer
+end

data/templates/app/bin/gemstack

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runs the GemStack CLI from this application's bundle.
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup"
+load Gem.bin_path("gemstack-cli", "gemstack")

data/templates/app/config/app.rb.tt

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gemstack"
+<% if database? -%>
+require "gemstack/db"       # models and migrations — the connection is in config/database.yml
+<% end -%>
+require "gemstack/jobs"     # background jobs (app/jobs)
+require "gemstack/mail"     # mailers (app/mailers)
+# require "gemstack/storage" # file uploads — `gemstack add storage` turns this on
+
+# Sets the application root and loads .env files (development/test).
+GemStack.setup(root: File.expand_path("..", __dir__))
+
+# Require the gems listed in the Gemfile for the current environment.
+Bundler.require(:default, GemStack.env.to_sym)
+
+GemStack.configure do |config|
+  config.name = "<%= name %>"
+
+  # Settings for every environment. Everything below is optional: each line
+  # shows the default — uncomment one to change it. Per-environment settings go
+  # in config/environments/*.rb. All settings: docs/configuration.md.
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.api_path = "/api"                  # where the API lives (routes are relative to it)
+  # config.http.max_body_size = 10 * 1024 * 1024   # bytes; larger requests get 413
+  # config.http.json = :json                       # or :oj (add gem "oj"), or your own codec
+  # config.http.cors.origins = []                  # only for frontends on another domain
+  # config.http.middleware.use MyMiddleware        # add / insert_before / swap / delete
+
+  # ── Pagination: paginate(...) in controllers, ?page=2&per_page=50 (docs/pagination.md) ──
+  # config.http.pagination.per_page = 25           # records per page when the client doesn't say
+  # config.http.pagination.max_per_page = 100      # the most a client may ask for with ?per_page=
+
+  # ── Responses ───────────────────────────────────────────────────────────
+  # config.http.compression.enabled = true         # gzip/Brotli responses over 1 KB (add gem "brotli" for br)
+  # config.http.etags = true                       # ETag + 304 Not Modified for GET responses
+
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :debug                   # :info in production (or GEMSTACK_LOG_LEVEL)
+  # config.filter_parameters += %w[iban]           # masked in logs, next to password, token, secret…
+<% if database? -%>
+
+  # ── Database — the connection is in config/database.yml (DATABASE_URL overrides it) ──
+  # config.db.pool_size = 5                        # default: GEMSTACK_MAX_THREADS (one per Puma thread)
+  # config.db.statement_timeout = 5_000            # ms
+<% end -%>
+
+  # ── Cache (GemStack.cache) ──────────────────────────────────────────────
+  # config.cache.store = :memory                   # :redis to share it between processes (gem "redis-client")
+  # config.cache.default_expires_in = nil          # seconds; nil = until evicted
+
+  # ── Background jobs ─────────────────────────────────────────────────────
+  # config.jobs.default_queue = "default"
+  # config.jobs.default_max_attempts = 10          # then the job is kept as failed
+
+  # ── Mail ────────────────────────────────────────────────────────────────
+  # config.mail.default_from = "<%= name %> <no-reply@localhost>"   # or MAIL_FROM
+end

data/templates/app/config/database.yml.tt

@@ -0,0 +1,61 @@
+# Database connection (docs/database.md) — the same format as Rails' database.yml.
+# DATABASE_URL (TEST_DATABASE_URL in tests) overrides this file when set, which
+# is what most hosting platforms provide. Adapters: sqlite3, postgresql, mysql2,
+# trilogy (add the matching gem: sqlite3, pg, mysql2, trilogy).
+default: &default
+<% if database_adapter == "sqlite3" -%>
+  adapter: sqlite3
+  pool: <%%= ENV.fetch("GEMSTACK_MAX_THREADS", 5) %>
+
+development:
+  <<: *default
+  database: db/development.sqlite3
+
+test:
+  <<: *default
+  database: db/test.sqlite3
+
+# Keep the file on persistent storage (a volume); or set DATABASE_URL=sqlite3:/data/app.sqlite3.
+production:
+  <<: *default
+  database: db/production.sqlite3
+<% elsif database_adapter == "postgresql" -%>
+  adapter: postgresql
+  pool: <%%= ENV.fetch("GEMSTACK_MAX_THREADS", 5) %>
+  # Without host/username, the local server is used as your OS user.
+  # host: localhost
+  # username: <%= database_name %>
+  # password: <%%= ENV["DATABASE_PASSWORD"] %>
+
+development:
+  <<: *default
+  database: <%= database_name %>_development
+
+test:
+  <<: *default
+  database: <%= database_name %>_test
+
+# In production, DATABASE_URL (postgres://user:password@host:5432/name) usually replaces this.
+production:
+  <<: *default
+  database: <%= database_name %>_production
+<% else -%>
+  adapter: <%= database_adapter %>
+  pool: <%%= ENV.fetch("GEMSTACK_MAX_THREADS", 5) %>
+  host: <%%= ENV.fetch("DATABASE_HOST", "127.0.0.1") %>
+  username: root
+  password: <%%= ENV["DATABASE_PASSWORD"] %>
+
+development:
+  <<: *default
+  database: <%= database_name %>_development
+
+test:
+  <<: *default
+  database: <%= database_name %>_test
+
+# In production, DATABASE_URL (<%= database_adapter %>://user:password@host:3306/name) usually replaces this.
+production:
+  <<: *default
+  database: <%= database_name %>_production
+<% end -%>

data/templates/app/config/environments/development.rb.tt

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Development settings: applied after config/app.rb when GEMSTACK_ENV=development
+# (the default). Each line shows the default value — uncomment one to change it.
+# All settings: docs/configuration.md.
+GemStack.configure do |config|
+  # ── Code ────────────────────────────────────────────────────────────────
+  # config.reload_code = true                  # reload app/ and config/routes.rb when they change
+  # config.eager_load = false                  # load app/ lazily, for a faster boot
+  # config.jit = nil                           # :yjit or :zjit to try Ruby's JIT locally
+
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :debug               # :debug, :info, :warn, :error (or GEMSTACK_LOG_LEVEL)
+  # config.logger.format = :pretty             # readable lines; :json to see what production logs
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.show_exceptions = true         # 500s carry the exception; browsers get an error page
+  # config.contract.docs = true                # interactive API docs at /api/docs
+
+  # ── gemstack dev ────────────────────────────────────────────────────────
+  # config.dev.port = 3000                     # the one public port (or PORT)
+  # config.dev.jobs_command = %w[bundle exec gemstack jobs]   # nil: don't start a jobs worker
+<% if database? -%>
+
+  # ── Database (connection: config/database.yml) ──────────────────────────
+  # config.db.log_queries = true               # every SQL statement at DEBUG
+  # config.db.slow_query_ms = 500              # slower queries are logged at WARN
+<% end -%>
+
+  # ── Cache ───────────────────────────────────────────────────────────────
+  # config.cache.store = :memory               # :null to switch caching off, :redis to share it
+
+  # ── Mail ────────────────────────────────────────────────────────────────
+  # config.mail.delivery = :log                # saved to tmp/mail (.eml + .html); :smtp really sends
+end