gemstack-cli 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a7919922a3f8ef313ffffa34f0a8884905d6f552772d99ef38908696640de5a
+  data.tar.gz: 65dc878039db71201b6ab2514649e52d1f0b1ede7d4d0c52299cfa7c8e68b8c8
+SHA512:
+  metadata.gz: 6d00e50a3e84430210d7810dba99a89ebce41a7c9ddac5ede6dfe15f76d78f96ad60f15fa2ad4b24fcb2f5e8e49da602f3f7d81f736c72d2239fb92b8b3f9a68
+  data.tar.gz: 62a0bf6f9e50c21a636d27964a478aafd465f4ccf51f1012c94d57d8ad6e02e4822191bc87f928c5f3d76135ca968d55439a6adaefd801be94aa7555494d55c0

data/CHANGELOG.md

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shoaib Malik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,24 @@
+# gemstack-cli
+
+GemStack command-line interface and generators.
+
+Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
+applications. All GemStack gems are developed together in that repository and released with the same
+version.
+
+## Installation
+
+Installed with the `gemstack` gem; you rarely need to add it yourself.
+
+## Documentation
+
+- [Guide](https://github.com/gemstack-rb/gemstack/blob/main/docs/getting-started.md)
+- [All guides](https://github.com/gemstack-rb/gemstack/tree/main/docs) ·
+  [Architecture](https://github.com/gemstack-rb/gemstack/blob/main/ARCHITECTURE.md)
+
+Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gemstack-rb/gemstack)
+(this gem lives in `gems/gemstack-cli`).
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/exe/gemstack

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "gemstack/cli"
+
+GemStack::CLI.start(ARGV)

data/lib/gemstack/cli/add_generator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack add FEATURE` — opt-in modules, so apps that don't use them
+    # pay nothing: realtime, auth, storage.
+    class AddGenerator < Generator
+      FEATURES = %w[realtime auth storage].freeze
+
+      AUTH_ROUTES = <<~RUBY
+        # Authentication (gemstack add auth) — docs/authentication.md
+        post "/auth/signup", to: "registrations#create"
+        post "/auth/login", to: "sessions#create"
+        get "/auth/me", to: "sessions#show"
+        delete "/auth/logout", to: "sessions#destroy"
+        post "/auth/password/forgot", to: "password_resets#create"
+        post "/auth/password/reset", to: "password_resets#update"
+        post "/auth/email/resend", to: "email_verifications#create"
+        post "/auth/email/verify", to: "email_verifications#update"
+        get "/auth/tokens", to: "api_tokens#index"
+        post "/auth/tokens", to: "api_tokens#create"
+        delete "/auth/tokens/:id", to: "api_tokens#destroy"
+      RUBY
+
+      MAIL_ENV = <<~ENV
+
+        # Email. In development messages are saved to tmp/mail instead of being sent.
+        # SMTP_URL=smtp://user:password@smtp.example.com:587
+        # MAIL_FROM="My App <hello@example.com>"
+        # APP_URL=https://example.com   # the frontend, for links in emails (default http://localhost:3000)
+      ENV
+
+      def initialize(feature, root:, output: $stdout, install: true)
+        super(output: output)
+        unless FEATURES.include?(feature)
+          raise Thor::Error,
+                "Unknown feature #{feature.inspect}. Available: #{FEATURES.join(", ")}"
+        end
+
+        @feature = feature
+        @root = root
+        @install = install
+      end
+
+      def run
+        public_send(:"add_#{@feature}")
+        self
+      end
+
+      def add_realtime
+        add_gem("gemstack-realtime")
+        template_files("realtime", override_root: @root).each do |rel, source|
+          next if rel.start_with?("frontend/") && !File.directory?(File.join(@root, "frontend"))
+
+          write(File.join(@root, rel), File.read(source))
+        end
+        add_test_support('require "gemstack/realtime/testing"', "GemStack::Realtime::Testing")
+        bundle_install
+      end
+
+      STORAGE_ENV = <<~ENV
+
+        # File storage. Development and tests store files under storage/ (git-ignored).
+        # STORAGE_SERVICE=s3            # production default
+        # S3_BUCKET=my-app-uploads
+        # AWS_REGION=eu-west-3
+        # AWS_ACCESS_KEY_ID=...  AWS_SECRET_ACCESS_KEY=...   (or an instance role)
+        # S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com   # S3-compatible services
+      ENV
+
+      def add_storage
+        add_gem("gemstack-storage")
+        copy_feature_templates("storage")
+        add_routes(%(post "/uploads", to: "uploads#create" # direct uploads (gemstack add storage)\n),
+                   marker: "uploads#create")
+        append_env_example(STORAGE_ENV, marker: "STORAGE_SERVICE")
+        append_line(".gitignore", "/storage/")
+        add_test_support('require "gemstack/storage/testing"', "GemStack::Storage::Testing")
+        status("note", "Gemfile", "add gem \"aws-sdk-s3\" for S3 in production (docs/storage.md)")
+        bundle_install
+      end
+
+      # For templates: whether `gemstack add auth` ran.
+      def auth? = File.read(File.join(@root, "Gemfile")).match?(/^\s*gem "gemstack-auth"/)
+
+      def add_auth
+        require_database!("auth")
+        user_model = File.join(@root, "app/models/user.rb")
+        if File.file?(user_model) && !File.read(user_model).include?("GemStack::Auth::User")
+          raise Thor::Error, "app/models/user.rb already exists. Add `include GemStack::Auth::User` to it and " \
+                             "see docs/authentication.md (\"Existing users table\") instead."
+        end
+
+        add_gem("gemstack-mail")
+        add_gem("gemstack-auth")
+        JobGenerator.install_migration(@root, output: @output) # emails are sent from background jobs
+        copy_feature_templates("auth", skip_migration: "*_create_auth_tables.rb")
+        include_in_application_controller("GemStack::Auth::Controller")
+        add_routes(AUTH_ROUTES, marker: "/auth/login")
+        append_env_example(MAIL_ENV, marker: "SMTP_URL")
+        add_test_support('require "gemstack/mail/testing"', "GemStack::Mail::Testing")
+        add_test_support('require "gemstack/auth/testing"', "GemStack::Auth::Testing")
+        bundle_install
+      end
+
+      private
+
+      def frontend? = File.directory?(File.join(@root, "frontend"))
+
+      def require_database!(feature)
+        return if File.read(File.join(@root, "Gemfile")).match?(/^\s*gem "gemstack-db"/)
+
+        raise Thor::Error, "#{feature} stores its data in PostgreSQL; this app was created without a database " \
+                           "(add gem \"gemstack-db\" first — docs/database.md)"
+      end
+
+      # Writes a feature's templates (frontend/ files only when the app has
+      # one). %timestamp% in a path becomes a fresh migration version, unless a
+      # migration matching skip_migration already exists.
+      def copy_feature_templates(name, skip_migration: nil)
+        has_migration = skip_migration && !Dir.glob(File.join(@root, "db/migrations", skip_migration)).empty?
+        template_files(name, override_root: @root).sort.each do |rel, source|
+          next if rel.start_with?("frontend/") && !frontend?
+
+          if rel.include?("%timestamp%")
+            next status("identical", rel, "migration already present") if has_migration
+
+            rel = rel.sub("%timestamp%", Generator.migration_timestamp(@root))
+          end
+          content = File.read(source)
+          content = render(content, source) if rel.end_with?(".tt")
+          write(File.join(@root, rel.delete_suffix(".tt")), content)
+        end
+      end
+
+      def include_in_application_controller(mixin)
+        path = File.join(@root, "app/controllers/application_controller.rb")
+        return status("skip", path, "not found — add `include #{mixin}` yourself") unless File.file?(path)
+
+        content = File.read(path)
+        return status("identical", path, mixin) if content.include?(mixin)
+
+        updated = content.sub(/^class ApplicationController < .*\n/) { |line| "#{line}  include #{mixin}\n" }
+        return status("skip", path, "add `include #{mixin}` yourself") if updated == content
+
+        File.write(path, updated)
+        status("update", path, mixin)
+      end
+
+      def add_routes(block, marker:)
+        path = File.join(@root, "config/routes.rb")
+        content = File.file?(path) ? File.read(path) : ""
+        return status("identical", path, "routes") if content.include?(marker)
+        return status("skip", path, "no `GemStack.routes do` block — add the routes yourself") unless
+          content.match?(ControllerGenerator::ROUTES_BLOCK)
+
+        File.write(path, content.sub(ControllerGenerator::ROUTES_BLOCK) { |open| open + block.gsub(/^/, "  ") })
+        status("route", path)
+      end
+
+      def append_line(file, line)
+        path = File.join(@root, file)
+        return unless File.file?(path)
+
+        content = File.read(path)
+        return if content.lines.map(&:strip).include?(line)
+
+        File.write(path, "#{content.rstrip}\n#{line}\n")
+        status("update", path, line)
+      end
+
+      def append_env_example(text, marker:)
+        path = File.join(@root, ".env.example")
+        return unless File.file?(path)
+
+        content = File.read(path)
+        return if content.include?(marker)
+
+        File.write(path, "#{content.rstrip}\n#{text}")
+        status("update", path)
+      end
+
+      # Adds the gem inside the GemStack `path` block (checkout apps) or as a
+      # versioned dependency next to gem "gemstack".
+      def add_gem(name)
+        path = File.join(@root, "Gemfile")
+        content = File.read(path)
+        return status("identical", path, name) if content.match?(/^\s*gem "#{name}"/)
+
+        updated = content.match?(/^path ".*" do\n/) ? add_to_path_block(content, name) : add_versioned(content, name)
+        if updated == content
+          raise Thor::Error,
+                "couldn't find where to add #{name} in the Gemfile; add `gem \"#{name}\"` yourself"
+        end
+
+        File.write(path, updated)
+        status("gemfile", path, name)
+      end
+
+      # Keeps the block's gems in alphabetical order (Bundler/OrderedGems).
+      def add_to_path_block(content, name)
+        content.sub(/^(path ".*" do\n)((?:  gem .*\n)*)/) do
+          opening = ::Regexp.last_match(1)
+          lines = ::Regexp.last_match(2) # before sort_by's regexes reset last_match
+          gems = (lines.lines + ["  gem \"#{name}\"\n"]).sort_by { |line| line[/"([^"]+)"/, 1] }
+          opening + gems.join
+        end
+      end
+
+      def add_versioned(content, name)
+        content.sub(/^gem "gemstack",.*\n/) { |line| "#{line}gem \"#{name}\", \"~> #{GemStack::VERSION}\"\n" }
+      end
+
+      def add_test_support(require_line, mixin)
+        path = File.join(@root, "test/test_helper.rb")
+        return unless File.file?(path)
+
+        content = File.read(path)
+        return status("identical", path) if content.include?(mixin)
+
+        content = content.sub(%(require "gemstack/testing"\n)) { |line| "#{line}#{require_line}\n" }
+        content = "#{content.rstrip}\nGemStack::TestCase.include #{mixin}\n"
+        File.write(path, content)
+        status("update", path, mixin)
+      end
+
+      def bundle_install
+        return unless @install
+
+        status("run", "bundle install")
+        install = -> { system("bundle", "install", "--quiet", chdir: @root) }
+        ok = defined?(Bundler) ? Bundler.with_unbundled_env(&install) : install.call
+        status("warning", "bundle install failed — run it yourself") unless ok
+      end
+    end
+  end
+end

data/lib/gemstack/cli/app_generator.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    # `gemstack new NAME` — a Ruby API + Next.js application containing the
+    # framework infrastructure and deliberately no business resources.
+    class AppGenerator < Generator
+      NAME = /\A[a-z][a-z0-9_-]*\z/
+
+      # The gems/ directory of the GemStack checkout this CLI runs from, if any.
+      CHECKOUT = File.expand_path("../../../..", __dir__)
+
+      attr_reader :name, :module_name, :destination, :gemstack_path, :api_path
+
+      def initialize(name, options = {}, output: $stdout)
+        super(output: output)
+        @name = File.basename(name.to_s)
+        @destination = File.expand_path(name.to_s)
+        @options = options
+        @module_name = Inflector.camelize(@name.tr("-", "_"))
+        @gemstack_path = options[:gemstack_path] ? File.expand_path(options[:gemstack_path]) : detect_checkout
+        @api_path = "/api"
+      end
+
+      def version = GemStack::VERSION
+
+      # Pins the app to the Ruby that generated it (.ruby-version, .tool-versions).
+      def ruby_version = RUBY_VERSION
+      def frontend? = !@options[:skip_frontend]
+      def database? = !@options[:skip_database]
+
+      def run
+        validate!
+        @output.puts("Creating GemStack application #{name} in #{destination}")
+        render_directory("app", destination, skip: ->(rel) { !database? && rel.start_with?("db/") })
+        render_directory("frontend", File.join(destination, "frontend")) if frontend?
+        install unless @options[:skip_install]
+        git_init unless @options[:skip_git]
+        summary
+        self
+      end
+
+      private
+
+      def validate!
+        unless NAME.match?(name)
+          raise Thor::Error,
+                "Invalid name #{name.inspect}: use lowercase letters, digits, - and _, starting with a letter"
+        end
+        return unless File.exist?(destination) && !Dir.empty?(destination)
+
+        raise Thor::Error, "#{destination} already exists and is not empty"
+      end
+
+      def detect_checkout
+        File.file?(File.join(CHECKOUT, "gemstack", "gemstack.gemspec")) ? CHECKOUT : nil
+      end
+
+      def install
+        bundled = run_step("bundle install", destination, "bundle", "install", "--quiet")
+        create_database if bundled && database?
+        return unless frontend?
+
+        run_step("npm install", File.join(destination, "frontend"), "npm", "install", "--no-fund",
+                 "--no-audit")
+      end
+
+      # Best effort: a missing or password-protected PostgreSQL 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`")
+      end
+
+      def git_init
+        return if File.directory?(File.join(destination, ".git")) || !system("git --version", out: File::NULL)
+
+        run_step("git init", destination, "git", "init", "--quiet")
+      end
+
+      def run_step(label, dir, *command)
+        @output.puts("  #{"run".rjust(9)}  #{label}")
+        ok = unbundled { system(*command, chdir: dir) }
+        @output.puts("  #{"warning".rjust(9)}  `#{label}` failed — run it manually in #{dir}") unless ok
+        ok
+      end
+
+      # Run child commands with the new app's bundle, not the CLI's.
+      def unbundled(&)
+        defined?(Bundler) ? Bundler.with_unbundled_env(&) : yield
+      end
+
+      def summary
+        @output.puts <<~TEXT
+
+          GemStack application #{name} created.
+
+            cd #{name}
+            gemstack dev        # → http://localhost:3000
+
+          Next: gemstack generate resource Product name:string price:decimal
+          Useful commands: gemstack routes · gemstack test · gemstack console · gemstack db:migrate
+        TEXT
+      end
+    end
+  end
+end

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

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    map "db:create" => :db_create, "db:drop" => :db_drop, "db:migrate" => :db_migrate,
+        "db:rollback" => :db_rollback, "db:seed" => :db_seed, "db:setup" => :db_setup,
+        "db:status" => :db_status, "db:reset" => :db_reset
+
+    class_option :environment, aliases: "-e", type: :string, desc: "Environment (default: GEMSTACK_ENV or development)"
+
+    desc "db:create", "Create the database (config.db.url)"
+    def db_create
+      with_database do
+        result = DB::Tasks.create
+        say("#{result == :created ? "Created" : "Already exists"}: #{DB::Tasks.database_name}")
+      end
+    end
+
+    desc "db:drop", "Drop the database (refused in production unless GEMSTACK_ALLOW_DB_DROP=1)"
+    def db_drop
+      with_database do
+        result = DB::Tasks.drop
+        say("#{result == :dropped ? "Dropped" : "Does not exist"}: #{DB::Tasks.database_name}")
+      end
+    end
+
+    desc "db:migrate", "Apply pending migrations (--target VERSION to migrate up or down to a version)"
+    method_option :target, type: :numeric
+    def db_migrate
+      with_database do
+        changed = DB::Migrator.new.migrate(target: options[:target])
+        changed.empty? ? say("No pending migrations.") : changed.sort.each { |file| say("  migrated  #{file}") }
+      end
+    end
+
+    desc "db:rollback", "Revert the last migration (--steps N for more)"
+    method_option :steps, type: :numeric, default: 1
+    def db_rollback
+      with_database do
+        reverted = DB::Migrator.new.rollback(steps: options[:steps])
+        if reverted.empty?
+          say("Nothing to roll back.")
+        else
+          reverted.sort.reverse_each do |file|
+            say("  reverted  #{file}")
+          end
+        end
+      end
+    end
+
+    desc "db:status", "List migrations and whether they are applied"
+    def db_status
+      with_database do
+        rows = DB::Migrator.new.status.map { |m| [m.applied ? "up" : "down", m.version.to_s, m.name] }
+        if rows.empty?
+          say("No migrations in #{DB.config.migrations_path}.")
+        else
+          print_table([%w[Status Version Name],
+                       *rows])
+        end
+      end
+    end
+
+    desc "db:seed", "Load db/seeds.rb"
+    def db_seed
+      with_database(boot: true) do
+        DB::Tasks.seed ? say("Seeded from #{DB.config.seeds_path}.") : say("No #{DB.config.seeds_path} found.")
+      end
+    end
+
+    desc "db:setup", "Create the database, migrate and seed"
+    def db_setup
+      db_create
+      db_migrate
+      db_seed
+    end
+
+    desc "db:reset", "Drop, recreate, migrate and seed (development/test only)"
+    def db_reset
+      db_drop
+      db_setup
+    end
+
+    desc "contract", "Generate TypeScript types, API clients and OpenAPI from the backend"
+    method_option :quiet, type: :boolean, default: false
+    def contract
+      root = Project.ensure_bundle!(self.class.argv)
+      ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+      Project.load_config!(root)
+      require "gemstack/contract"
+      GemStack.config.reload_code = false
+      GemStack.config.logger.level = :warn
+      GemStack.config.db.log_queries = false if GemStack.config.respond_to?(:db)
+      contract = Contract.build(GemStack.boot!)
+      report = Contract.write(contract, root: root, typescript: File.directory?(File.join(root, "frontend")))
+      print_contract_report(report, contract, root)
+    rescue Sequel::DatabaseConnectionError => e
+      abort("gemstack contract: database unreachable (#{e.message.lines.first.strip}). Models need it to load.")
+    end
+
+    no_commands do
+      def with_database(boot: false)
+        root = Project.ensure_bundle!(self.class.argv)
+        ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+        Project.load_config!(root)
+        unless defined?(GemStack::DB)
+          abort("This app doesn't use gemstack-db. Add `gem \"gemstack-db\"` to the Gemfile.")
+        end
+        GemStack.config.reload_code = false
+        GemStack.config.db.log_queries = false
+        GemStack.config.logger.level = :warn # these commands print their own summary
+        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.")
+      rescue GemStack::Error => e
+        abort(e.message)
+      end
+
+      def redact(url) = url.sub(%r{//([^:/@]+):[^@]+@}, '//\1:***@')
+
+      def print_contract_report(report, contract, root)
+        rel = ->(path) { path.delete_prefix("#{root}/") }
+        report[:written].each { |path| say("  #{"write".rjust(9)}  #{rel.call(path)}") }
+        report[:removed].each { |path| say("  #{"remove".rjust(9)}  #{rel.call(path)}") }
+        contract[:warnings].each { |w| say("  #{"warning".rjust(9)}  #{w}", :yellow) } unless options[:quiet]
+        return if options[:quiet] || !report[:written].empty? || !report[:removed].empty?
+
+        say("Contract up to date (#{contract[:resources].size} resources, #{contract[:types].size} types).")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module GemStack
+  class CLI < Thor
+    map "jobs:status" => :jobs_status, "jobs:retry" => :jobs_retry, "jobs:discard" => :jobs_discard,
+        "jobs:install" => :jobs_install, "jobs:failed" => :jobs_failed
+
+    desc "jobs", "Run a background job worker (PostgreSQL queue)"
+    method_option :queues, aliases: "-q", type: :string, desc: "Comma-separated queues (default: all)"
+    method_option :concurrency, aliases: "-c", type: :numeric,
+                                desc: "Worker threads (default: GEMSTACK_JOB_CONCURRENCY or 5)"
+    def jobs
+      with_jobs do |config|
+        config.jobs.queues = options[:queues].split(",").map(&:strip) if options[:queues]
+        config.jobs.concurrency = options[:concurrency] if options[:concurrency]
+        # Each worker thread holds a connection, plus LISTEN and the reaper.
+        config.db.pool_size = [config.db.pool_size, config.jobs.concurrency + 2].max
+        GemStack.boot!
+        GemStack.application.eager_load!
+        require "gemstack/jobs/worker"
+        Jobs::Worker.new.run
+      end
+    end
+
+    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
+        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) }
+        print_table([%w[Queue Ready Scheduled Running Failed], *rows])
+      end
+    end
+
+    desc "jobs:failed", "List recently failed jobs"
+    method_option :limit, type: :numeric, default: 20
+    def jobs_failed
+      with_jobs(quiet: true) do
+        failed = Jobs::Adapters::Postgres.new.failed(limit: options[:limit])
+        return say("No failed jobs.") if failed.empty?
+
+        failed.each do |job|
+          say("##{job[:id]} #{job[:job_class]} (#{job[:queue]}) " \
+              "attempts=#{job[:attempts]} failed_at=#{job[:failed_at]}")
+          say("    #{job[:last_error].to_s.lines.first&.strip}")
+        end
+      end
+    end
+
+    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))
+        say("Re-queued #{count} job(s).")
+      end
+    end
+
+    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))
+        say("Deleted #{count} failed job(s).")
+      end
+    end
+
+    desc "jobs:install", "Add the gemstack_jobs table migration (done automatically by `generate job`)"
+    def jobs_install
+      JobGenerator.install_migration(Project.root!, output: $stdout)
+    end
+
+    no_commands do
+      def with_jobs(quiet: false)
+        root = Project.ensure_bundle!(self.class.argv)
+        ENV["GEMSTACK_ENV"] = options[:environment] || ENV["GEMSTACK_ENV"] || "development"
+        Project.load_config!(root)
+        unless defined?(GemStack::Jobs)
+          abort('This app doesn\'t use gemstack-jobs. Add `gem "gemstack-jobs"` to the Gemfile.')
+        end
+        config = GemStack.config
+        config.reload_code = false
+        if quiet
+          config.logger.level = :warn
+          config.db.log_queries = false if config.respond_to?(:db)
+        end
+        yield config
+      rescue Sequel::DatabaseError => e
+        raise unless e.message.include?("gemstack_jobs")
+
+        abort("The gemstack_jobs table doesn't exist yet. Run `gemstack jobs:install && gemstack db:migrate`.")
+      rescue Sequel::DatabaseConnectionError => e
+        abort("Can't connect to the database: #{e.message.lines.first.strip}")
+      end
+    end
+  end
+end