gemstack-cli 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a7919922a3f8ef313ffffa34f0a8884905d6f552772d99ef38908696640de5a
-  data.tar.gz: 65dc878039db71201b6ab2514649e52d1f0b1ede7d4d0c52299cfa7c8e68b8c8
+  metadata.gz: 9d9243d3986f9d45d5aa9de84f699ea7fcac37504ed266d7998e5a4eab6ff484
+  data.tar.gz: 6cf9300583fb65e103c7b71b48859721863766837180a362365639ec0186c5fc
 SHA512:
-  metadata.gz: 6d00e50a3e84430210d7810dba99a89ebce41a7c9ddac5ede6dfe15f76d78f96ad60f15fa2ad4b24fcb2f5e8e49da602f3f7d81f736c72d2239fb92b8b3f9a68
-  data.tar.gz: 62a0bf6f9e50c21a636d27964a478aafd465f4ccf51f1012c94d57d8ad6e02e4822191bc87f928c5f3d76135ca968d55439a6adaefd801be94aa7555494d55c0
+  metadata.gz: 54009542d20d3bcc5ae67e2b89e19965c285e32b6400ca43e7ecf22af1f2bc3a8303803c2c1708cc967f5c50fed4c159e7807e5f41bdb9da702c87f9cc4e8229
+  data.tar.gz: 0acb8e759970a5154f11fae58d530c960575849ec4f93018f46b9a8ef70f1d43cfac289c0606ae16508efd16f843ade368b0fa49777e15caacdb42e42e9db22a

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.1
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
+## 0.2.0
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
 ## 0.1.0
 
 First release. See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/lib/gemstack/cli/add_generator.rb

@@ -70,6 +70,7 @@ module GemStack
 
       def add_storage
         add_gem("gemstack-storage")
+        ensure_base_classes(@root, :serializer)
         copy_feature_templates("storage")
         add_routes(%(post "/uploads", to: "uploads#create" # direct uploads (gemstack add storage)\n),
                    marker: "uploads#create")
@@ -94,6 +95,7 @@ module GemStack
         add_gem("gemstack-mail")
         add_gem("gemstack-auth")
         JobGenerator.install_migration(@root, output: @output) # emails are sent from background jobs
+        ensure_base_classes(@root, :model, :serializer, :mailer)
         copy_feature_templates("auth", skip_migration: "*_create_auth_tables.rb")
         include_in_application_controller("GemStack::Auth::Controller")
         add_routes(AUTH_ROUTES, marker: "/auth/login")

data/lib/gemstack/cli/app_generator.rb

@@ -6,6 +6,12 @@ module GemStack
     # framework infrastructure and deliberately no business resources.
     class AppGenerator < Generator
       NAME = /\A[a-z][a-z0-9_-]*\z/
+      # `--database` values (Rails' names) and aliases.
+      DATABASES = { "sqlite3" => "sqlite3", "sqlite" => "sqlite3", "postgresql" => "postgresql",
+                    "postgres" => "postgresql", "pg" => "postgresql", "mysql2" => "mysql2", "mysql" => "mysql2",
+                    "trilogy" => "trilogy" }.freeze
+      DRIVERS = { "sqlite3" => ["sqlite3", "~> 2.0"], "postgresql" => ["pg", "~> 1.5"],
+                  "mysql2" => ["mysql2", "~> 0.5"], "trilogy" => ["trilogy", "~> 2.9"] }.freeze
 
       # The gems/ directory of the GemStack checkout this CLI runs from, if any.
       CHECKOUT = File.expand_path("../../../..", __dir__)
@@ -29,10 +35,27 @@ module GemStack
       def frontend? = !@options[:skip_frontend]
       def database? = !@options[:skip_database]
 
+      # sqlite3 (default), postgresql, mysql2 or trilogy.
+      def database_adapter
+        @database_adapter ||= DATABASES.fetch(@options[:database].to_s.downcase.then do |d|
+          d.empty? ? "sqlite3" : d
+        end) do
+          raise Thor::Error,
+                "Unknown --database #{@options[:database].inspect}. Use: sqlite3, postgresql, mysql2, trilogy"
+        end
+      end
+
+      def driver_gem = DRIVERS.fetch(database_adapter).first
+      def driver_version = DRIVERS.fetch(database_adapter).last
+      def database_name = name.tr("-", "_")
+
       def run
         validate!
+        database_adapter if database? # fail early on an unknown --database
         @output.puts("Creating GemStack application #{name} in #{destination}")
-        render_directory("app", destination, skip: ->(rel) { !database? && rel.start_with?("db/") })
+        render_directory("app", destination, skip: lambda { |rel|
+          !database? && (rel.start_with?("db/", "app/models/") || rel == "config/database.yml.tt")
+        })
         render_directory("frontend", File.join(destination, "frontend")) if frontend?
         install unless @options[:skip_install]
         git_init unless @options[:skip_git]
@@ -63,16 +86,18 @@ module GemStack
 
         run_step("npm install", File.join(destination, "frontend"), "npm", "install", "--no-fund",
                  "--no-audit")
+        # The TypeScript contract, so frontend/lib/api/generated exists from the start.
+        run_step("gemstack contract", destination, "bin/gemstack", "contract", "--quiet") if bundled
       end
 
-      # Best effort: a missing or password-protected PostgreSQL shouldn't fail `new`.
+      # Best effort: a missing or password-protected database server shouldn't fail `new`.
       def create_database
         @output.puts("  #{"run".rjust(9)}  gemstack db:create")
         ok = unbundled { system("bin/gemstack", "db:create", chdir: destination, out: File::NULL, err: File::NULL) }
         return if ok
 
         @output.puts("  #{"warning".rjust(9)}  couldn't create the database — " \
-                     "set DATABASE_URL in .env, then run `gemstack db:create`")
+                     "check config/database.yml (or set DATABASE_URL in .env), then run `gemstack db:create`")
       end
 
       def git_init

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

@@ -8,7 +8,7 @@ module GemStack
 
     class_option :environment, aliases: "-e", type: :string, desc: "Environment (default: GEMSTACK_ENV or development)"
 
-    desc "db:create", "Create the database (config.db.url)"
+    desc "db:create", "Create the database (config/database.yml or DATABASE_URL)"
     def db_create
       with_database do
         result = DB::Tasks.create
@@ -112,8 +112,9 @@ module GemStack
         GemStack.boot! if boot
         yield
       rescue Sequel::DatabaseConnectionError => e
-        abort("Can't connect to #{redact(DB.config.url)}: #{e.message.lines.first.strip}\n" \
-              "Set DATABASE_URL (e.g. in .env) — see docs/models.md.")
+        settings = DB.settings
+        abort("Can't connect to #{DB::Configuration.describe(settings)} (from #{settings[:source]}): " \
+              "#{e.message.lines.first.strip}\nCheck config/database.yml or DATABASE_URL — see docs/database.md.")
       rescue GemStack::Error => e
         abort(e.message)
       end

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

@@ -25,7 +25,7 @@ module GemStack
     desc "jobs:status", "Show queued, scheduled, running and failed jobs per queue"
     def jobs_status
       with_jobs(quiet: true) do
-        stats = Jobs::Adapters::Postgres.new.stats
+        stats = Jobs::Adapters::Database.new.stats
         return say("No jobs.") if stats.empty?
 
         rows = stats.sort.map { |queue, s| [queue, s[:ready], s[:scheduled], s[:running], s[:failed]].map(&:to_s) }
@@ -37,7 +37,7 @@ module GemStack
     method_option :limit, type: :numeric, default: 20
     def jobs_failed
       with_jobs(quiet: true) do
-        failed = Jobs::Adapters::Postgres.new.failed(limit: options[:limit])
+        failed = Jobs::Adapters::Database.new.failed(limit: options[:limit])
         return say("No failed jobs.") if failed.empty?
 
         failed.each do |job|
@@ -51,7 +51,7 @@ module GemStack
     desc "jobs:retry [IDS...]", "Put failed jobs back on the queue (all failed jobs without IDS)"
     def jobs_retry(*ids)
       with_jobs(quiet: true) do
-        count = Jobs::Adapters::Postgres.new.retry_failed(ids.empty? ? nil : ids.map(&:to_i))
+        count = Jobs::Adapters::Database.new.retry_failed(ids.empty? ? nil : ids.map(&:to_i))
         say("Re-queued #{count} job(s).")
       end
     end
@@ -59,7 +59,7 @@ module GemStack
     desc "jobs:discard [IDS...]", "Delete failed jobs (all failed jobs without IDS)"
     def jobs_discard(*ids)
       with_jobs(quiet: true) do
-        count = Jobs::Adapters::Postgres.new.discard_failed(ids.empty? ? nil : ids.map(&:to_i))
+        count = Jobs::Adapters::Database.new.discard_failed(ids.empty? ? nil : ids.map(&:to_i))
         say("Deleted #{count} failed job(s).")
       end
     end

data/lib/gemstack/cli/deploy_generator.rb

@@ -18,11 +18,49 @@ module GemStack
       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? }
+        gemfile.match?(/^\s*gem "gemstack-jobs"/) && Generator.background_work?(@root)
       end
 
       def mail? = gemfile.match?(/^\s*gem "gemstack-(mail|auth)"/)
+      def database? = gemfile.match?(/^\s*gem "gemstack-db"/)
+      def realtime? = gemfile.match?(/^\s*gem "gemstack-realtime"/)
+
+      # From config/database.yml (production, else the first adapter listed);
+      # apps without one use PostgreSQL, GemStack's original default.
+      def database_adapter
+        path = File.join(@root, "config/database.yml")
+        return "postgresql" unless File.file?(path)
+
+        text = File.read(path)
+        production = text[/^production:.*?(?=^\S|\z)/m].to_s
+        (production[/^\s+adapter:\s*(\w+)/, 1] || text[/^\s+adapter:\s*(\w+)/, 1] || "postgresql")
+          .then { |name| { "postgres" => "postgresql", "sqlite" => "sqlite3", "mysql" => "mysql2" }.fetch(name, name) }
+      end
+
+      def sqlite? = database_adapter == "sqlite3"
+      def mysql? = %w[mysql2 trilogy].include?(database_adapter)
+      def postgresql? = database_adapter == "postgresql"
+      # A Redis for realtime fan-out when the database can't do it (PostgreSQL uses NOTIFY).
+      def redis? = realtime? && !postgresql?
+
+      def build_packages
+        (%w[build-essential libyaml-dev
+            git] + { "postgresql" => ["libpq-dev"], "mysql2" => ["default-libmysqlclient-dev"] }.fetch(database_adapter,
+                                                                                                       [])).join(" ")
+      end
+
+      def runtime_packages
+        (%w[libyaml-0-2
+            curl] + { "postgresql" => ["libpq5"], "mysql2" => ["libmariadb3"] }.fetch(database_adapter, [])).join(" ")
+      end
+
+      def database_url
+        case database_adapter
+        when "sqlite3" then "sqlite3:/data/production.sqlite3"
+        when "postgresql" then "postgres://app:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/app"
+        else "#{database_adapter}://app:${MYSQL_PASSWORD:?set MYSQL_PASSWORD}@db:3306/app"
+        end
+      end
 
       def ruby_version
         pinned = File.file?(File.join(@root, ".ruby-version")) && File.read(File.join(@root, ".ruby-version")).strip

data/lib/gemstack/cli/doctor.rb

@@ -35,6 +35,7 @@ module GemStack
           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
@@ -130,20 +131,36 @@ module GemStack
       def check_database
         return true unless defined?(GemStack::DB)
 
-        url = GemStack::DB.config.url
+        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("PostgreSQL reachable (#{redact(url)})")
+        pass("database reachable (#{where})")
         true
-      rescue StandardError => e
+      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.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"
+        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("PostgreSQL: #{message}", hint)
+        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?
@@ -151,7 +168,7 @@ module GemStack
         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 defined?(GemStack::Jobs) && GemStack::Jobs.database_queue?
         return unless jobs_used?
 
         if GemStack::DB.connection.table_exists?(:gemstack_jobs)
@@ -194,7 +211,7 @@ module GemStack
         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)
+        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
@@ -205,6 +222,19 @@ module GemStack
         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"
 
@@ -260,7 +290,7 @@ module GemStack
       end
 
       def jobs_used?
-        %w[app/jobs/*.rb app/mailers/*.rb].any? { |glob| !Dir.glob(path(glob)).empty? }
+        Generator.background_work?(@root)
       end
 
       def location(error)

data/lib/gemstack/cli/generator.rb

@@ -59,6 +59,28 @@ module GemStack
       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
+
+      # 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

data/lib/gemstack/cli/job_generator.rb

@@ -35,6 +35,7 @@ module GemStack
       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))

data/lib/gemstack/cli/resource_generator.rb

@@ -34,6 +34,7 @@ module GemStack
       end
 
       def run
+        ensure_base_classes(@root, *(%i[model serializer] & @parts))
         @parts.each { |part| render_part(part) }
         add_routes if @parts.include?(:controller)
         self

data/lib/gemstack/cli.rb

@@ -53,7 +53,9 @@ module GemStack
     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 :database, aliases: "-d", type: :string, default: "sqlite3",
+                             desc: "sqlite3 (default), postgresql, mysql2 or trilogy"
+    method_option :skip_database, type: :boolean, default: false, desc: "No database / 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

data/templates/app/Gemfile.tt

@@ -14,6 +14,7 @@ path "<%= gemstack_path %>" do
   gem "gemstack-db"
 <% end -%>
   gem "gemstack-jobs"
+  gem "gemstack-mail"
   gem "gemstack-dev"
   gem "gemstack-http"
   gem "gemstack-schema"
@@ -24,8 +25,12 @@ gem "gemstack", "~> <%= version %>"
 gem "gemstack-db", "~> <%= version %>"
 <% end -%>
 gem "gemstack-jobs", "~> <%= version %>"
+gem "gemstack-mail", "~> <%= version %>"
 <% 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)

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/config/app.rb.tt

@@ -23,7 +23,7 @@ GemStack.configure do |config|
   # config.filter_parameters += %w[iban]           # masked in logs
 <% if database? -%>
   #
-  # config.db.url = ENV["DATABASE_URL"]            # default: postgres:///<name>_<env> (TEST_DATABASE_URL in test)
+  # Connection: config/database.yml (DATABASE_URL / TEST_DATABASE_URL override it).
   # config.db.pool_size = 5                        # default: GEMSTACK_MAX_THREADS (one per Puma thread)
   # config.db.statement_timeout = 5_000            # ms
 <% 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

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Production settings: applied after config/app.rb when GEMSTACK_ENV=production.
+# Each line shows the default value — uncomment one to change it.
+#
+# Secrets and connections come from environment variables, never from files:
+# SECRET_KEY_BASE, <% if database? %>DATABASE_URL, <% end %>SMTP_URL, MAIL_FROM, APP_URL, REDIS_URL…
+# `gemstack doctor --production` checks what's missing (docs/deployment.md).
+GemStack.configure do |config|
+  # ── Code ────────────────────────────────────────────────────────────────
+  # config.eager_load = true                   # load all code at boot (copy-on-write friendly with Puma workers)
+  # config.jit = :yjit                         # Ruby's JIT (or GEMSTACK_JIT=yjit|zjit|off)
+
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :info
+  # config.logger.format = :json               # one JSON object per line, with the request id
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.show_exceptions = false        # never send exception details to clients
+  # config.http.hsts = "max-age=63072000; includeSubDomains"   # on HTTPS requests; nil if your proxy sets it
+  # config.http.cors.origins = ["https://app.example.com"]    # only if the frontend is on another domain
+  # config.http.max_body_size = 10 * 1024 * 1024               # larger requests get 413
+<% if database? -%>
+
+  # ── Database ────────────────────────────────────────────────────────────
+  # config.db.pool_size = 5                    # connections per process (GEMSTACK_MAX_THREADS)
+  # config.db.statement_timeout = 5_000        # ms; stop runaway queries (PostgreSQL, MySQL)
+  # config.db.slow_query_ms = 500              # slower queries are logged at WARN
+<% end -%>
+
+  # ── Cache: :memory is per process — use Redis with several processes or servers ──
+  # config.cache.store = :redis                # add gem "redis-client"; REDIS_URL
+
+  # ── Background jobs (`gemstack jobs`) ───────────────────────────────────
+  # config.jobs.concurrency = 5                # threads per worker (or GEMSTACK_JOB_CONCURRENCY)
+
+  # ── Mail ────────────────────────────────────────────────────────────────
+  # config.mail.delivery = :smtp               # SMTP_URL=smtp://user:password@smtp.example.com:587
+  # config.mail.default_from = "App <hello@example.com>"      # or MAIL_FROM
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Test settings: applied after config/app.rb when tests run (`gemstack test`).
+# Each line shows the default value — uncomment one to change it.
+GemStack.configure do |config|
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :debug               # logs are discarded in tests unless this (or GEMSTACK_LOG_LEVEL) is set
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.show_exceptions = true         # a failing request's JSON includes the exception
+<% if database? -%>
+
+  # ── Database (connection: the test section of config/database.yml, or TEST_DATABASE_URL) ──
+  # config.db.log_queries = false
+<% end -%>
+
+  # ── Background work is recorded, not performed ──────────────────────────
+  # config.jobs.adapter = :test                # assert_enqueued / perform_enqueued_jobs; :inline runs jobs at once
+  # config.mail.delivery = :test               # assert_emails / last_email
+  # config.cache.store = :null                 # no caching, so tests can't leak into each other; :memory to test it
+end

data/templates/app/dot_env.example.tt

@@ -0,0 +1,19 @@
+# Copy to .env for local development overrides. Never commit real secrets.
+# Variables already set in your shell always take precedence.
+
+# PORT=3000                   # public development port (gemstack dev)
+# GEMSTACK_LOG_LEVEL=debug
+
+<% if database? -%>
+# Database: config/database.yml. A URL here overrides it (hosting platforms set DATABASE_URL).
+<% if database_adapter == "sqlite3" -%>
+# DATABASE_URL=sqlite3:db/development.sqlite3
+<% elsif database_adapter == "postgresql" -%>
+# DATABASE_URL=postgres://user:password@localhost:5432/<%= database_name %>_development
+# TEST_DATABASE_URL=postgres://user:password@localhost:5432/<%= database_name %>_test
+<% else -%>
+# DATABASE_PASSWORD=
+# DATABASE_URL=<%= database_adapter %>://root:password@127.0.0.1:3306/<%= database_name %>_development
+# TEST_DATABASE_URL=<%= database_adapter %>://root:password@127.0.0.1:3306/<%= database_name %>_test
+<% end -%>
+<% end -%>

data/templates/app/dot_gitignore

@@ -1,6 +1,8 @@
 /.bundle/
 /log/
 /tmp/
+/db/*.sqlite3
+/db/*.sqlite3-*
 .env
 .env.local
 .env.*.local

data/templates/auth/app/mailers/auth_mailer.rb

@@ -2,7 +2,7 @@
 
 # Account emails. Templates: app/mailers/templates/auth_mailer/*.erb.
 # Links point at the Next.js pages (config.auth.app_url, APP_URL in production).
-class AuthMailer < GemStack::Mailer
+class AuthMailer < ApplicationMailer
   def password_reset(user_id)
     @user = User[user_id] or return
     token, = GemStack::Auth::Tokens.issue(@user.id, purpose: "password_reset")

data/templates/auth/app/models/auth_token.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # API tokens (and single-use reset/verification tokens) — see GemStack::Auth::Tokens.
-class AuthToken < GemStack::Model
+class AuthToken < ApplicationModel
   field :purpose, :string, null: false
   field :name, :string, size: 100
   field :last_used_at, :datetime

data/templates/auth/app/models/user.rb

@@ -2,7 +2,7 @@
 
 # Accounts. GemStack::Auth::User adds password hashing (Argon2id), email
 # normalization, validations and User.authenticate_by(email:, password:).
-class User < GemStack::Model
+class User < ApplicationModel
   include GemStack::Auth::User
 
   field :email, :string, null: false, size: 254

data/templates/auth/app/serializers/api_token_serializer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class ApiTokenSerializer < GemStack::Serializer
+class ApiTokenSerializer < ApplicationSerializer
   model AuthToken
   attributes :id, :name, :last_used_at, :expires_at, :created_at
 end

data/templates/auth/app/serializers/new_api_token_serializer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # The response to creating an API token: the only time the token itself is shown.
-class NewApiTokenSerializer < GemStack::Serializer
+class NewApiTokenSerializer < ApplicationSerializer
   Result = Data.define(:token, :api_token)
 
   attribute :token, :string

data/templates/auth/app/serializers/user_serializer.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 # What the API shows about the signed-in user. Never add password_digest.
-class UserSerializer < GemStack::Serializer
+class UserSerializer < ApplicationSerializer
   attributes :id, :email, :email_verified_at, :created_at
 end

data/templates/auth/db/migrations/%timestamp%_create_auth_tables.rb

@@ -5,8 +5,8 @@ Sequel.migration do
   change do
     create_table(:users) do
       primary_key :id, type: :Bignum
-      column :email, :text, null: false, unique: true # stored lowercased
-      column :password_digest, :text, null: false     # Argon2id
+      String :email, null: false, unique: true # stored lowercased
+      String :password_digest, null: false     # Argon2id
       column :email_verified_at, :timestamptz
       column :created_at, :timestamptz, null: false
       column :updated_at, :timestamptz, null: false
@@ -17,9 +17,9 @@ Sequel.migration do
     create_table(:sessions) do
       primary_key :id, type: :Bignum
       foreign_key :user_id, :users, type: :Bignum, null: false, on_delete: :cascade, index: true
-      column :token_digest, :text, null: false, unique: true
+      String :token_digest, size: 64, null: false, unique: true
       column :ip, :inet
-      column :user_agent, :text
+      String :user_agent
       column :created_at, :timestamptz, null: false
       column :last_seen_at, :timestamptz, null: false
       column :expires_at, :timestamptz, null: false, index: true
@@ -29,10 +29,10 @@ Sequel.migration do
     create_table(:auth_tokens) do
       primary_key :id, type: :Bignum
       foreign_key :user_id, :users, type: :Bignum, null: false, on_delete: :cascade, index: true
-      column :purpose, :text, null: false
-      column :token_digest, :text, null: false, unique: true
-      column :name, :text
-      column :email, :text
+      String :purpose, size: 30, null: false
+      String :token_digest, size: 64, null: false, unique: true
+      String :name
+      String :email
       column :created_at, :timestamptz, null: false
       column :last_used_at, :timestamptz
       column :expires_at, :timestamptz

data/templates/deploy/Dockerfile.tt

@@ -14,7 +14,7 @@ ARG NODE_VERSION=<%= node_version %>
 
 # ── Ruby API ────────────────────────────────────────────────────────────────
 FROM ruby:${RUBY_VERSION}-slim AS api-build
-RUN apt-get update -qq && apt-get install --no-install-recommends -y build-essential libpq-dev libyaml-dev git \
+RUN apt-get update -qq && apt-get install --no-install-recommends -y <%= build_packages %> \
     && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 ENV BUNDLE_DEPLOYMENT=1 BUNDLE_WITHOUT="development:test" BUNDLE_PATH=/usr/local/bundle
@@ -25,9 +25,10 @@ COPY . .
 RUN rm -rf frontend tmp/* log/* .env*
 
 FROM ruby:${RUBY_VERSION}-slim AS api
-RUN apt-get update -qq && apt-get install --no-install-recommends -y libpq5 libyaml-0-2 curl \
+RUN apt-get update -qq && apt-get install --no-install-recommends -y <%= runtime_packages %> \
     && rm -rf /var/lib/apt/lists/* \
-    && groupadd --system --gid 1000 app && useradd --system --uid 1000 --gid app --create-home app
+    && groupadd --system --gid 1000 app && useradd --system --uid 1000 --gid app --create-home app<% if sqlite? %> \
+    && mkdir -p /data && chown app:app /data<% end %>
 WORKDIR /app
 ENV GEMSTACK_ENV=production BUNDLE_DEPLOYMENT=1 BUNDLE_WITHOUT="development:test" BUNDLE_PATH=/usr/local/bundle \
     GEMSTACK_API_HOST=0.0.0.0 GEMSTACK_API_PORT=4000

data/templates/deploy/compose.yaml.tt

@@ -1,16 +1,25 @@
 # Runs <%= app_name %> in production mode on this machine, behind Caddy on https://localhost:
 #
-#   export SECRET_KEY_BASE=$(openssl rand -hex 64) POSTGRES_PASSWORD=$(openssl rand -hex 16)
+#   export SECRET_KEY_BASE=$(openssl rand -hex 64)<% if postgresql? %> POSTGRES_PASSWORD=$(openssl rand -hex 16)<% elsif mysql? %> MYSQL_PASSWORD=$(openssl rand -hex 16)<% end %>
 #   docker compose up --build
 #
 # It's also a map of what a real deploy needs: one image per process type,
 # migrations before the API starts, and a proxy sending /api to Ruby.
+<% if sqlite? -%>
+# SQLite: the database file lives on the `data` volume, shared by the API, the
+# jobs worker and migrations — keep them on one host.
+<% end -%>
 name: <%= app_name.tr("_", "-") %>
 
 x-api-env: &api-env
   GEMSTACK_ENV: production
   SECRET_KEY_BASE: ${SECRET_KEY_BASE:?set SECRET_KEY_BASE (openssl rand -hex 64)}
-  DATABASE_URL: postgres://app:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@db:5432/app
+<% if database? -%>
+  DATABASE_URL: <%= database_url %>
+<% end -%>
+<% if redis? -%>
+  REDIS_URL: redis://redis:6379/0 # realtime fan-out between the API and the jobs worker
+<% end -%>
   APP_URL: ${APP_URL:-https://localhost}
 <% if mail? -%>
   SMTP_URL: ${SMTP_URL:-}   # e.g. smtp://user:pass@smtp.example.com:587 — emails retry until it is set
@@ -18,6 +27,7 @@ x-api-env: &api-env
 <% end -%>
 
 services:
+<% if postgresql? -%>
   db:
     image: postgres:17
     environment:
@@ -30,21 +40,53 @@ services:
       interval: 2s
       retries: 30
 
+<% elsif mysql? -%>
+  db:
+    image: mysql:8.4
+    environment:
+      MYSQL_DATABASE: app
+      MYSQL_USER: app
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:?set MYSQL_PASSWORD}
+      MYSQL_RANDOM_ROOT_PASSWORD: "yes"
+    volumes: [db:/var/lib/mysql]
+    healthcheck:
+      test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uapp -p$$MYSQL_PASSWORD --silent"]
+      interval: 3s
+      retries: 40
+
+<% end -%>
+<% if redis? -%>
+  redis:
+    image: redis:7
+    command: ["redis-server", "--save", "", "--appendonly", "no"]
+
+<% end -%>
+<% if database? -%>
   migrate:
     image: <%= app_name %>-api
     build: { context: ., target: api }
     healthcheck: { disable: true }
     command: ["bundle", "exec", "gemstack", "db:migrate"]
     environment: *api-env
+<% if sqlite? -%>
+    volumes: [data:/data]
+<% else -%>
     depends_on: { db: { condition: service_healthy } }
+<% end -%>
 
+<% end -%>
   api:
     image: <%= app_name %>-api
     build: { context: ., target: api }
     environment:
       <<: *api-env
       WEB_CONCURRENCY: ${WEB_CONCURRENCY:-2}
+<% if sqlite? -%>
+    volumes: [data:/data]
+<% end -%>
+<% if database? -%>
     depends_on: { migrate: { condition: service_completed_successfully } }
+<% end -%>
 <% if jobs? -%>
 
   jobs:
@@ -53,6 +95,9 @@ services:
     healthcheck: { disable: true }
     command: ["bundle", "exec", "gemstack", "jobs"]
     environment: *api-env
+<% if sqlite? -%>
+    volumes: [data:/data]
+<% end -%>
     depends_on: { migrate: { condition: service_completed_successfully } }
 <% end -%>
 <% if frontend? -%>
@@ -76,5 +121,9 @@ services:
     depends_on: [api<%= ", web" if frontend? %>]
 
 volumes:
+<% if sqlite? -%>
+  data:
+<% elsif database? -%>
   db:
+<% end -%>
   caddy:

data/templates/job/app/jobs/%file_name%.rb.tt

@@ -2,7 +2,7 @@
 
 # Enqueue with <%= class_name %>.perform_later(...) — arguments must be JSON values (pass ids, not records).
 # Runs in `gemstack jobs` (and in `gemstack dev`). Delivery is at-least-once: keep perform idempotent.
-class <%= class_name %> < GemStack::Job
+class <%= class_name %> < ApplicationJob
 <% if queue_name -%>
   queue :<%= queue_name %>
 <% end -%>

data/templates/resource/model/app/models/%file_name%.rb.tt

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class <%= class_name %> < GemStack::Model
+class <%= class_name %> < ApplicationModel
 <% fields.each do |field| -%>
   <%= model_field(field) %>
 <% end -%>

data/templates/resource/serializer/app/serializers/%file_name%_serializer.rb.tt

@@ -2,6 +2,6 @@
 
 # What the API returns for a <%= class_name %>. Only listed attributes are exposed;
 # their types (from <%= class_name %>'s fields) drive the generated TypeScript types.
-class <%= class_name %>Serializer < GemStack::Serializer
+class <%= class_name %>Serializer < ApplicationSerializer
   attributes :id, <%= fields.map { |f| ":#{f.column}" }.join(", ") %>, :created_at, :updated_at
 end

data/templates/storage/app/serializers/upload_serializer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Where and how the browser sends the file (see UploadsController).
-class UploadSerializer < GemStack::Serializer
+class UploadSerializer < ApplicationSerializer
   Result = Data.define(:signed_id, :url, :http_method, :headers)
 
   attribute :signed_id, :string

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Shoaib Malik
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: gemstack-dev
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.2.1
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -80,17 +80,23 @@ files:
 - templates/app/Gemfile.tt
 - templates/app/README.md.tt
 - templates/app/app/controllers/application_controller.rb
+- templates/app/app/jobs/application_job.rb
+- templates/app/app/mailers/application_mailer.rb
+- templates/app/app/mailers/templates/dot_keep
+- templates/app/app/models/application_model.rb
+- templates/app/app/serializers/application_serializer.rb
 - templates/app/bin/gemstack
 - templates/app/config.ru
 - templates/app/config/app.rb.tt
-- templates/app/config/environments/development.rb
-- templates/app/config/environments/production.rb
-- templates/app/config/environments/test.rb
+- templates/app/config/database.yml.tt
+- templates/app/config/environments/development.rb.tt
+- templates/app/config/environments/production.rb.tt
+- templates/app/config/environments/test.rb.tt
 - templates/app/config/puma.rb
 - templates/app/config/routes.rb
 - templates/app/db/migrations/dot_keep
 - templates/app/db/seeds.rb
-- templates/app/dot_env.example
+- templates/app/dot_env.example.tt
 - templates/app/dot_gitignore
 - templates/app/dot_ruby-version.tt
 - templates/app/dot_tool-versions.tt

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

@@ -1,6 +0,0 @@
-# frozen_string_literal: true
-
-# Development-only settings. config/app.rb applies to every environment.
-GemStack.configure do |config|
-  # config.http.show_exceptions = true   # exception details in 500 responses (default in development)
-end

data/templates/app/config/environments/production.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-# Production-only settings. Defaults here: JSON logs, no exception details in
-# responses, eager loading, HSTS on HTTPS requests.
-GemStack.configure do |config|
-  # config.logger.level = :info
-  # config.http.cors.origins = ["https://app.example.com"]   # only if the frontend is on another domain
-end

data/templates/app/config/environments/test.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-# Test-only settings. config/app.rb applies to every environment.
-GemStack.configure do |config|
-  # Logs are discarded in tests unless GEMSTACK_LOG_LEVEL is set, e.g.:
-  # config.logger.level = :debug
-end

data/templates/app/dot_env.example

@@ -1,9 +0,0 @@
-# Copy to .env for local development overrides. Never commit real secrets.
-# Variables already set in your shell always take precedence.
-
-# PORT=3000                   # public development port (gemstack dev)
-# GEMSTACK_LOG_LEVEL=debug
-
-# PostgreSQL. Defaults: postgres:///<app>_development locally (current OS user).
-# DATABASE_URL=postgres://user:password@localhost:5432/myapp_development
-# TEST_DATABASE_URL=postgres://user:password@localhost:5432/myapp_test