trek 2.5.0 → 2.6.0

data/docs/reference/generators/public-accounts.md

@@ -0,0 +1,141 @@
+# Public accounts
+
+```sh
+rails g trek:public_accounts Customer [--sign-in=code|password] [--api] [--path=customers] [--model-only]
+bin/rails db:migrate
+```
+
+Accounts for the people using the site or the mobile app (customers, members, readers…), apart from the admin's [`User`](/reference/models/user). They have their own model, table, sessions and sign-in, so nothing public can reach a staff account: signing up, deleting inactive accounts or merging duplicates only ever sees public accounts, and a public session never opens the admin.
+
+The name is required, and is the app's own: `User` is the admin's account, so the generator refuses it, a namespaced name, and the names of Trek's models. Pick the word of the app's domain (`Customer`, `Member`, `Reader`…).
+
+| Option | Effect |
+| --- | --- |
+| `--sign-in=code` (default) | Accounts sign in with a code emailed to them, which creates the account the first time: there is no password, nor sign-up form |
+| `--sign-in=password` | Accounts sign up with an email and a password, confirm the email by a link, and reset a forgotten password by one: there are no codes |
+| `--api` | A mobile app: JSON endpoints under `/api/v1`, and a session held through a JWT, with no pages. Without it, a website: pages, and a session kept in a cookie |
+| `--path=customers` | Puts the routes under a path, e.g. `/customers/sign-in`: for an app with two kinds of public accounts |
+| `--model-only` | Neither pages nor endpoints: see [Model only](#model-only). Can't be combined with `--api` or `--path` |
+
+## Model only
+
+With `--model-only`, the generator adds the models, their migration, `Current.customer_session` and `Current.customer`, the mailer, its job for codes, the locales and the model specs, but no controllers, pages, routes nor JWT. It's for an app whose sign-in is its own, e.g. an API ported from another app that its mobile app already calls: the app keeps its endpoints and tokens, on top of `Customer` and its rules (passwords, lockout, sessions, inactive accounts).
+
+The app then creates and finds the `Customer::Session` rows itself, or ignores them, and sets `Current.customer_session`. With passwords, the emailed links point at the app's domain (`https://<host>/account/confirm?token=…`, `/password-reset?token=…`, `/account/email?token=…`), or at `CUSTOMERS_APP_LINKS_URL`, as for the API: the app's own pages or mobile app handle them.
+
+## Signing in with an emailed code
+
+1. The person types their email; the app emails them a 6-digit code. It answers the same whether or not the email has an account (ANSSI guide on passwords, R14).
+2. They type the code: it signs them in to the email's account, created the first time. Signing up is signing in.
+
+A code is valid for 10 minutes, for 5 tries (the right one included), and once. A new code replaces the earlier one. Only an HMAC of the code is stored, keyed on the app's `secret_key_base`, and the code is created in the job sending the email, so it's never in the job queue either. Change `validity` and `max_attempts` on `Customer::SignInCode`.
+
+A new email address is confirmed the same way: a code sent to it.
+
+## Signing in with a password
+
+- **Signing up** takes an email and a password, following the same rules as the admin's (`Trek::Users::PasswordPolicy`: 12 characters, a digit and a symbol below 20…, configurable), and signs in at once. A link confirming the email is sent, valid a day; following it sets `confirmed_at`. The app decides what an unconfirmed account may do (`customer.confirmed?`), and the account page sends the link again.
+- **Failed sign-ins** lock signing in as for the admin (`Trek::Users::SignInLockout`), and `CustomerMailer#sign_in_locked` tells the account.
+- **A forgotten password** is reset by a link, valid 15 minutes and used up by the new password (`has_secure_password`'s `password_reset_token`), which signs out every session. Asking for one answers the same whether or not the email has an account.
+- **Changing the password** needs a recent sign-in (15 minutes, `Customer::Session::RECENT`), and signs out the other sessions.
+- **A new email address** is kept in `unconfirmed_email` until the link sent to it, valid an hour, is followed.
+
+## Rate limits
+
+Against guessing and flooding, each IP address may try to sign in 10 times in 3 minutes (5 with a password) and fail 20 times an hour, and ask for 10 emails (codes, links) in 15 minutes; each address gets at most 5 emails an hour. The limits are counted in `Rails.cache`, which must be shared between servers (see [Failed sign-ins](/reference/models/user#failed-sign-ins)).
+
+## Sessions
+
+| | Website | API (`--api`) |
+| --- | --- | --- |
+| Held by | a signed `customer_session_id` cookie (`HttpOnly`, `SameSite=Lax`) | a JWT the app sends as `Authorization: Bearer …` |
+| Expires | after 30 days without a request, and a year after signing in | the same, checked on the session row: the JWT only names it |
+| Signing out | deletes the session and the cookie | deletes the session, and the JWT stops working |
+
+Both are `Customer::Session` rows (`customer_sessions`), listed on the account, where the person can sign out the others. Change `idle_timeout` and `lifetime` on `Customer::Session` ([Trek::Users::SessionLifetime](/reference/models/user#sessions)). The JWT is signed with HS256 and a key derived from `secret_key_base`, and carries the session's id (`sub`) and the end of its lifetime (`exp`): unlike a self-contained token, it can be revoked.
+
+Deleting the account, and changing the password, need a sign-in less than 15 minutes old; otherwise the website sends the person to sign in again, and the API answers 403 with `recent_sign_in_needed`.
+
+Schedule the purge of expired sessions daily, as for the admin's: `Trek::PurgeExpiredSessionsJob.perform_later("Customer::Session")`.
+
+The admin's own session (`session_id`, `User::Session`) is untouched: someone may be signed in to both, as two accounts that can share an email address.
+
+## What the generator adds
+
+- `Customer` and `Customer::Session`, `Customer::SignInCode` for codes, and a migration creating their tables
+- `Current.customer_session`, and `Current.customer`
+- `Customers::Authentication`, and the controllers: under `Customers::` with pages for a website, under `Api::V1::Customers::` for the API
+- `CustomerMailer` with its views in English and French, and `Customers::SignInCodeJob` for codes
+- `config/locales/customers.{en,fr}.yml`
+- the routes, on paths of their own (below), so renaming the model keeps them
+- specs, when the app has a `spec` directory
+
+### Website
+
+`Customers::Authentication` is included in `ApplicationController`, so every page may use:
+
+| Helper | Returns |
+| --- | --- |
+| `current_customer`, `customer_signed_in?` | the signed-in customer, if any |
+| `staff_user` | the admin's user signed in in this browser, when privileged, for previews and links to the admin on the site. Read only: it neither extends nor ends their admin session, and never signs a customer in |
+
+A page for customers only calls `before_action :require_customer`, which sends the others to sign in and brings them back after.
+
+| Path | Page |
+| --- | --- |
+| `GET /sign-in` | the sign-in form (`customer_sign_in_path`): the email for a code, or the email and password |
+| `GET /sign-in/code` | the code form (codes) |
+| `GET /sign-up` | the sign-up form (passwords) |
+| `GET /password-reset/new` | asking for a link to choose a new password (passwords) |
+| `GET /account/confirm?token=…` | the link confirming the email (passwords) |
+| `DELETE /sign-out` | signs out |
+| `GET /account` | the account: name, email, password, signed-in browsers, deletion (`customer_account_path`) |
+| `GET /account/email/new` | changing the email, confirmed by a code or a link sent to the new address |
+| `GET /account/password/edit` | changing the password (passwords) |
+
+The pages render in the site's layout, unstyled, with their notices in `app/views/customers/_flash.html.slim`: move those to the layout if it shows flash messages.
+
+### API
+
+The endpoints are the API's first version, under `/api/v1`, so that a later version can be served next to them while older releases of the mobile app still call these. Every endpoint answers JSON; an error comes as `{ "error": "invalid_code", "message": "…" }`, the message in the request's locale.
+
+| Endpoint | Body | Answer |
+| --- | --- | --- |
+| `POST /api/v1/sign-in` | codes: `email`; passwords: `email`, `password` | codes: 202, a code is emailed; passwords: 201, `{ token, customer }` |
+| `POST /api/v1/sign-in/code` | `email`, `otp` | 201, `{ token, customer }` (codes) |
+| `POST /api/v1/sign-up` | `email`, `password`, `name` | 201, `{ token, customer }` (passwords) |
+| `POST /api/v1/password-reset` | `email` | 202, a link is emailed if the email has an account (passwords) |
+| `PATCH /api/v1/password-reset` | `token`, `password` | 204 (passwords) |
+| `POST`, `PATCH /api/v1/account/confirmation` | `token` for `PATCH` | sends the confirmation link again; confirms the email (passwords) |
+| `DELETE /api/v1/session` | | 204, signs out |
+| `GET`, `PATCH`, `DELETE /api/v1/account` | `name` | the account; deleting needs a recent sign-in |
+| `POST /api/v1/account/email` | `email` | 202, a code or a link is emailed to the new address |
+| `PATCH /api/v1/account/email` | codes: `email`, `otp`; passwords: `token` | the account, with its new email; 409 when another account has it |
+| `PATCH /api/v1/account/password` | `password` | 204 (passwords); needs a recent sign-in |
+| `GET /api/v1/account/sessions` | | the signed-in devices, `current` for this one |
+| `DELETE /api/v1/account/sessions/:id`, `/others` | | 204 |
+
+With passwords, the emailed links point at the app's domain (`https://<host>/account/confirm?token=…`, `/password-reset?token=…`, `/account/email?token=…`), or at `CUSTOMERS_APP_LINKS_URL`: the mobile app opens them (iOS universal links, Android app links) and sends their `token` to the endpoints above.
+
+## Audit log
+
+When the app has the [audit log](/reference/generators/audit-log), the account controllers write to it too: sign-ins, failed or not, sign-ups, code and link requests (with no actor), and account changes, the customer being the actor.
+
+## Inactive accounts
+
+`Customer.inactive_since(time)` lists the accounts with no request since `time` (`last_activity_at`, written at most every 5 minutes), e.g. for a job deleting them. It can only ever list customers.
+
+## Upgrading Trek
+
+The generated files are the app's own: upgrading Trek never changes them. On each upgrade, check:
+
+- **The CHANGELOG,** for entries on what the generated code relies on in the gem: `Trek::Users::SessionLifetime`, `Trek::Users::SignInCode` (codes), `Trek::Users::SignInLockout` and `Trek::Users::PasswordPolicy` (passwords), `Trek::PurgeExpiredSessionsJob`, `Trek::ResolveSessionHostnameJob` and `Trek::Auditable`.
+- **The generator's own changes,** a security fix among them, which reach the app only by running it again. On a clean working tree, run it with the same name and options, then review `git diff` and restore the app's own changes:
+
+  ```sh
+  rails g trek:public_accounts Customer --force # plus the options it was generated with
+  git diff
+  ```
+
+  Running it again adds nothing already there: no second migration, route or `Current` attribute.
+- **The admin's session,** which `staff_user` reads: its `session_id` cookie and `User::Session`, in `Customers::Authentication#staff_user`. An upgrade note says when they change.

data/docs/reference/generators/security-headers.md

@@ -41,7 +41,7 @@ The policy only **reports** violations at first (`config.content_security_policy
 
 ### Violation reports
 
-Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. It logs each one too (`[CSP] script-src-elem blocked https://cdn.example.net on /pages/team (report)`), which is all an app without AppSignal gets.
+Browsers send each violation to the policy's `report-uri`: `/csp-reports`, which `Trek::CspReportsController` answers (the generator adds `post "csp-reports"` to the routes). It reports each violation to **AppSignal**, when the app uses it, in a `csp` namespace: one incident per directive and blocked origin (e.g. `script-src-elem https://cdn.example.net`), tagged with the page and whether the policy was enforced, so a new violation is notified once and closed once fixed. To tell what was blocked, each report is also tagged with the browser's user agent and, when the browser gives them, where it happened (`source`: the file's URL, without its query, and the line) and the `sample`: the first 40 characters of an inline script, which the policy asks for with `'report-sample'` (`policy.script_src :self, :report_sample`). Tags are cut to 255 characters, as AppSignal drops longer ones. It logs each one too (`[CSP] script-src-elem blocked inline on /pages/team (report) at https://www.example.com/pages/team:12: "alert(1)"`), which is all an app without AppSignal gets.
 
 It keeps the reports about the app's own pages only, and drops what browser extensions load or inject, which makes most reports and says nothing about the app. It keeps the page's path, not its query, which may carry a token, and the blocked resource's origin, not its URL. Browsers send no CSRF token nor cookie: the endpoint needs neither, and answers `204`.
 

data/docs/reference/index.md

@@ -8,7 +8,8 @@ A comprehensive list of features and settings included in Trek.
 - [Admin user](/reference/generators/admin-user) — `rails g trek:admin:user`
 - [Scaffold](/reference/generators/scaffold) — `rails g trek:scaffold`
 - [Taxonomies](/reference/generators/taxonomies) — `rails g trek:taxonomies`
-- [Audit log](/reference/generators/audit-log) — `rails g trek:install:audit_log`
+- [Audit log](/reference/generators/audit-log) — `rails g trek:audit_log`
+- [Public accounts](/reference/generators/public-accounts) — `rails g trek:public_accounts`
 - [Security headers](/reference/generators/security-headers) — `rails g trek:install:security_headers`
 
 ## Models

data/docs/reference/models/user.md

@@ -2,6 +2,8 @@
 
 The host application's `User` model, into which Trek injects authentication (`has_secure_password` and database-backed sessions), roles, theme & locale preferences and the invitation workflow.
 
+It is the admin's account. The site's or the mobile app's users (customers, members…) get a model of their own, apart from it: see [Public accounts](/reference/generators/public-accounts).
+
 ## Columns added by Trek
 
 | Column | Type | Notes |
@@ -68,7 +70,7 @@ Users see their **active sessions** in a tab of their own profile: browser and s
 `Trek::Users::SignIns` helps users spot a sign-in that wasn't theirs:
 
 - the **Active sessions** tab of their profile shows their **previous sign-in**: its date, browser and IP address. It's kept on the user (`last_sign_in_at`, `last_sign_in_ip`, `last_sign_in_user_agent`, with their `current_sign_in_*` counterparts), as sessions are deleted when they end;
-- a sign-in from a **browser that never signed in as the user** emails them (`AdminMailer#new_sign_in`): date, browser, IP address, with links to change their password and to their active sessions. A browser is recognized by a signed cookie, kept for years, listing the users who signed in from it. Their very first sign-in sends nothing.
+- a sign-in from a **browser that never signed in as the user** emails them (`AdminMailer#new_sign_in`): date, browser, IP address and its host name (as on the active sessions), with links to change their password and to their active sessions. A browser is recognized by a signed cookie, kept for years, listing the users who signed in from it. Their very first sign-in sends nothing.
 
 Set `self.new_sign_in_email = false` in the `User` model to turn the email off.
 

data/docs/what-is-trek.md

@@ -9,7 +9,7 @@ Trek ships as a Rails engine (a gem plus an NPM package) that integrates into yo
 - **A complete admin panel** — layout, navigation, search, pagination, light & dark themes, all built with [ViewComponent](https://viewcomponent.org), [Stimulus](https://stimulus.hotwired.dev) and [Turbo](https://turbo.hotwired.dev).
 - **Pages** — hierarchical, translatable pages with version history, SEO metadata and stable, redirect-aware URL paths.
 - **Fragments** — reusable chunks of content (a footer text, a hero tagline…) editable from the admin and usable anywhere in your views.
-- **A rich text editor** — based on [Tiptap](https://tiptap.dev), with image uploads (Uppy), link insertion and content stored as structured ProseMirror JSON.
+- **A content editor** — based on [Tiptap](https://tiptap.dev), with image uploads (Uppy), link insertion and content stored as structured ProseMirror JSON and rendered safely to HTML (see [Content editor](/content-editor)).
 - **Authentication & authorization** — sign in built on Rails' [`has_secure_password`](https://api.rubyonrails.org/classes/ActiveModel/SecurePassword/ClassMethods.html) with database-backed sessions, password resets, invitations, and [ActionPolicy](https://actionpolicy.evilmartians.io) policies with `admin`, `editor`, `user`, `reader` and `guest` roles.
 - **Internationalization** — content translations with [Mobility](https://github.com/shioyama/mobility), locale management with [i18n-tasks](https://github.com/glebm/i18n-tasks), and optional automatic translation through DeepL.
 - **File uploads** — [Shrine](https://shrinerb.com)-backed attachments with S3 or local storage, image processing via libvips, and blurhash placeholders.

data/lib/generators/trek/audit_log_generator.rb

@@ -0,0 +1,54 @@
+require "rails/generators/actions"
+require "rails/generators/migration"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    class AuditLogGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+      include Trek::Generators::Helpers
+
+      desc "Create the AuditLog model, record the admin's requests, and list them in the admin."
+
+      source_root File.expand_path("templates", __dir__)
+
+      def copy_model
+        template "models/audit_log.rb", "app/models/audit_log.rb"
+      end
+
+      def copy_migration_file
+        return unless defined?(ActiveRecord)
+
+        migration_template("migrations/audit_logs.rb.erb",
+          "db/migrate/trek_audit_logs.rb",
+          migration_class_name:)
+      end
+
+      def copy_initializer
+        template "initializers/audit_log.rb", "config/initializers/audit_log.rb"
+      end
+
+      def copy_controller
+        template "controllers/admin/audit_logs_controller.rb",
+          "app/controllers/admin/audit_logs_controller.rb"
+      end
+
+      def copy_views
+        directory "views/admin/audit_logs", "app/views/admin/audit_logs"
+      end
+
+      def copy_policy
+        template "policies/audit_log.rb", "app/policies/admin/audit_log_policy.rb"
+      end
+
+      def add_routes
+        route "resources :audit_logs, only: %i[index show]", namespace: :admin
+      end
+
+      def copy_specs
+        template "spec/models/audit_log_spec.rb", "spec/models/audit_log_spec.rb"
+        template "spec/requests/admin/audit_logs_spec.rb", "spec/requests/admin/audit_logs_spec.rb"
+      end
+    end
+  end
+end

data/lib/generators/trek/install/admin/users_generator.rb

@@ -25,10 +25,10 @@ module Trek
                 get :options, on: :collection
               end
             RUBY
+            route "resource :password_renewal, only: :create", namespace: :admin
             route <<~RUBY, namespace: :admin
               resources :users do
                 patch :theme, on: :collection
-                post :require_password_renewal, on: :collection
               end
             RUBY
           end
@@ -52,6 +52,11 @@ module Trek
             template "controllers/admin/passkeys_controller.rb",
               "app/controllers/admin/passkeys_controller.rb"
           end
+
+          def copy_password_renewals
+            template "controllers/admin/password_renewals_controller.rb",
+              "app/controllers/admin/password_renewals_controller.rb"
+          end
         end
       end
     end

data/lib/generators/trek/install/audit_log_generator.rb

@@ -1,54 +1,18 @@
-require "rails/generators/actions"
-require "rails/generators/migration"
-require "generators/trek/helpers"
+require "generators/trek/audit_log_generator"
 
 module Trek
   module Generators
     module Install
-      class AuditLogGenerator < Rails::Generators::Base
-        include Rails::Generators::Migration
-        include Trek::Generators::Helpers
+      # The audit log's generator under its former name: `trek:install` doesn't run it, so it's `trek:audit_log` now.
+      # Removed in Trek 3.
+      class AuditLogGenerator < Trek::Generators::AuditLogGenerator
+        hide!
 
-        desc "Create the AuditLog model, record the admin's requests, and list them in the admin."
+        # Not inherited: Rails derives it from the generator's own path.
+        source_root Trek::Generators::AuditLogGenerator.source_root
 
-        source_root File.expand_path("../templates", __dir__)
-
-        def copy_model
-          template "models/audit_log.rb", "app/models/audit_log.rb"
-        end
-
-        def copy_migration_file
-          return unless defined?(ActiveRecord)
-
-          migration_template("migrations/audit_logs.rb.erb",
-            "db/migrate/trek_audit_logs.rb",
-            migration_class_name:)
-        end
-
-        def copy_initializer
-          template "initializers/audit_log.rb", "config/initializers/audit_log.rb"
-        end
-
-        def copy_controller
-          template "controllers/admin/audit_logs_controller.rb",
-            "app/controllers/admin/audit_logs_controller.rb"
-        end
-
-        def copy_views
-          directory "views/admin/audit_logs", "app/views/admin/audit_logs"
-        end
-
-        def copy_policy
-          template "policies/audit_log.rb", "app/policies/admin/audit_log_policy.rb"
-        end
-
-        def add_routes
-          route "resources :audit_logs, only: %i[index show]", namespace: :admin
-        end
-
-        def copy_specs
-          template "spec/models/audit_log_spec.rb", "spec/models/audit_log_spec.rb"
-          template "spec/requests/admin/audit_logs_spec.rb", "spec/requests/admin/audit_logs_spec.rb"
+        def deprecation_warning
+          say "`trek:install:audit_log` is deprecated and will be removed in Trek 3: run `trek:audit_log`.", :yellow
         end
       end
     end

data/lib/generators/trek/install/good_job_generator.rb

@@ -0,0 +1,161 @@
+require "rails/generators/actions"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    module Install
+      # Replaces the Solid Queue backend `rails new` sets up with GoodJob: one PostgreSQL
+      # database instead of two, jobs running inside Puma, and a dashboard in the admin.
+      class GoodJobGenerator < Rails::Generators::Base
+        GOOD_JOB_VERSION = "~> 4.13".freeze
+        GEM_COMMENT = "Active Job backend on PostgreSQL, with a dashboard [https://github.com/bensheldon/good_job]".freeze
+
+        # The line `rails new` writes to size the connection pool: `max_connections` since
+        # Rails 8.1, `pool` before it. Whichever it is, it keeps its name.
+        POOL_LINE = /^(\s*)(max_connections|pool): <%= ENV\.fetch\("RAILS_MAX_THREADS"\)[^\n]*%>\n/
+
+        include Trek::Generators::Helpers
+
+        desc "Install GoodJob as the Active Job backend."
+
+        source_root File.expand_path("../templates", __dir__)
+
+        def swap_gems
+          return if in_gemfile?("good_job")
+
+          # Solid Queue wants a second database, which a Trek app does not provision (Solid
+          # Cache stays: its table lives in the primary database). GoodJob takes over its line,
+          # under the Active Job adapter comment it belongs to.
+          if in_gemfile?("solid_queue")
+            gsub_file "Gemfile", /^gem "solid_queue".*\n/,
+              %(# #{GEM_COMMENT}\ngem "good_job", "#{GOOD_JOB_VERSION}"\n)
+          else
+            gem "good_job", GOOD_JOB_VERSION, comment: GEM_COMMENT
+          end
+          bundle_install
+        end
+
+        def remove_solid_queue_files
+          %w[config/queue.yml config/recurring.yml db/queue_schema.rb bin/jobs].each do |file|
+            remove_file file
+          end
+        end
+
+        def remove_solid_queue_from_puma
+          gsub_file "config/puma.rb",
+            /^(?:#[^\n]*Solid Queue[^\n]*\n)?plugin :solid_queue if ENV\["SOLID_QUEUE_IN_PUMA"\]\n\n?/,
+            ""
+        end
+
+        def remove_queue_database
+          gsub_file "config/database.yml", /^  queue:\n(?:    [^\n]*\n)+/, ""
+        end
+
+        # GoodJob runs in the web container's process, so its threads need connections of their
+        # own — the pool `rails new` sizes for the web threads alone would starve them.
+        def size_connection_pool
+          gsub_file "config/database.yml", POOL_LINE, <<~'YAML'
+            \1# Web threads and job threads each check out their own connections, plus one for
+            \1# GoodJob's LISTEN/NOTIFY listener. GOOD_JOB_MAX_THREADS falls back to
+            \1# RAILS_MAX_THREADS inside GoodJob, so both shares match unless it is set.
+            \1\2: <%= web = ENV.fetch("RAILS_MAX_THREADS", 5).to_i; 1 + web + ENV.fetch("GOOD_JOB_MAX_THREADS", web).to_i %>
+          YAML
+        end
+
+        # Kamal's file is not what a Trek app deploys with, but leaving Solid Queue's variables
+        # in it would describe a backend the app no longer runs.
+        def clean_kamal_deploy_file
+          return unless File.exist?("config/deploy.yml")
+
+          gsub_file "config/deploy.yml",
+            /^(?:[ \t]*#[^\n]*\n)*([ \t]*)SOLID_QUEUE_IN_PUMA: true\n/,
+            <<~'YAML'
+              \1# Jobs run inside Puma (config.good_job.execution_mode = :async), so there is no
+              \1# separate job process to start. GOOD_JOB_MAX_THREADS sizes its thread pool.
+              \1# GOOD_JOB_MAX_THREADS: 5
+            YAML
+          gsub_file "config/deploy.yml",
+            /^[ \t]*# Set number of processes dedicated to Solid Queue[^\n]*\n[ \t]*# JOB_CONCURRENCY:[^\n]*\n\n?/,
+            ""
+        end
+
+        def configure_adapter
+          return if File.read("config/application.rb").include?("queue_adapter = :good_job")
+
+          inject_into_file "config/application.rb", adapter_configuration,
+            after: /^\s*config\.load_defaults [^\n]*\n/
+        end
+
+        # Active Job's test helper only swaps in its test adapter for a job class with no adapter
+        # configured, and config/application.rb now sets GoodJob: give the specs the test adapter
+        # back, for have_enqueued_job and the like.
+        def configure_test_adapter
+          return unless File.exist?("config/environments/test.rb")
+          return if File.read("config/environments/test.rb").include?("queue_adapter = :test")
+
+          inject_into_file "config/environments/test.rb", <<-RUBY, after: /^Rails\.application\.configure do\n/
+  # Jobs go to Active Job's test adapter, not GoodJob (config/application.rb), so specs can check
+  # what was enqueued.
+  config.active_job.queue_adapter = :test
+
+          RUBY
+        end
+
+        def configure_production
+          gsub_file "config/environments/production.rb", /^\s*config\.solid_queue\.connects_to[^\n]*\n/, ""
+          gsub_file "config/environments/production.rb",
+            /^(\s*)(?:# )?config\.active_job\.queue_adapter\s*=[^\n]*\n/,
+            <<~'RUBY'
+              \1# Jobs run in the web container's own threads: no worker process to pay for, and a
+              \1# deploy that drains them (shutdown_timeout) rather than dropping them.
+              \1config.good_job.execution_mode = :async
+              \1config.good_job.shutdown_timeout = 25
+            RUBY
+        end
+
+        def create_initializer
+          template "initializers/good_job.rb.tt", "config/initializers/good_job.rb"
+        end
+
+        def create_mail_delivery_job
+          copy_file "jobs/mail_delivery_job.rb", "app/jobs/mail_delivery_job.rb"
+        end
+
+        def mount_dashboard
+          route 'mount GoodJob::Engine => "good_job"', namespace: :admin
+        end
+
+        def create_migration
+          generate "good_job:install"
+        end
+
+        def create_specs
+          return unless File.directory?("spec")
+
+          copy_file "spec/requests/admin/good_job_spec.rb", "spec/requests/admin/good_job_spec.rb"
+          copy_file "spec/jobs/mail_delivery_job_spec.rb", "spec/jobs/mail_delivery_job_spec.rb"
+        end
+
+        private
+
+        # The model of a signed-in browser, which the dashboard's guard looks the session cookie up
+        # in: User::Session, or UserSession in an app generated before Trek nested it.
+        def session_model
+          File.exist?("app/models/user_session.rb") ? "UserSession" : "User::Session"
+        end
+
+        def adapter_configuration
+          <<-RUBY
+
+    # Use GoodJob as the Active Job backend (see config/initializers/good_job.rb).
+    config.active_job.queue_adapter = :good_job
+
+    # Every `deliver_later` email goes through MailDeliveryJob, which retries a failed
+    # delivery — GoodJob discards a failed job (see app/jobs/mail_delivery_job.rb).
+    config.action_mailer.delivery_job = "MailDeliveryJob"
+          RUBY
+        end
+      end
+    end
+  end
+end

data/lib/generators/trek/install/model_specs_generator.rb

@@ -51,11 +51,11 @@ module Trek
           directory "db/seeds", "db/seeds"
         end
 
-        # The audit log's specs come with it, from `trek:install:audit_log`, and the tags' (model and policies) from
-        # `trek:taxonomies`.
+        # The audit log's specs come with it, from `trek:audit_log`, the GoodJob dashboard's from
+        # `trek:install:good_job`, and the tags' (model and policies) from `trek:taxonomies`.
         def copy_specs
           directory "spec/models", "spec/models", exclude_pattern: /audit_log|tag_spec/
-          directory "spec/requests", "spec/requests", exclude_pattern: /audit_log/
+          directory "spec/requests", "spec/requests", exclude_pattern: /audit_log|good_job_spec/
           directory "spec/mailers", "spec/mailers"
           directory "spec/fixtures", "spec/fixtures"
           directory "spec/policies", "spec/policies", exclude_pattern: /tag(_category)?_policy_spec/

data/lib/generators/trek/install/ruby_generator.rb

@@ -5,7 +5,7 @@ module Trek
   module Generators
     module Install
       class RubyGenerator < Rails::Generators::Base
-        RUBY_VERSION = "4.0.7"
+        RUBY_VERSION = "4.0.9"
 
         include Trek::Generators::Helpers
 

data/lib/generators/trek/install/scalingo_generator.rb

@@ -1,53 +1,15 @@
-require "rails/generators/actions"
-require "generators/trek/helpers"
+require "generators/trek/scalingo_generator"
 
 module Trek
   module Generators
     module Install
-      class ScalingoGenerator < Rails::Generators::Base
-        BUILDPACK_URL = "https://github.com/etaminstudio/trek-buildpack/archive/refs/tags/v0.1.0.tar.gz".freeze
+      # The Scalingo generator under its former name: `trek:install` doesn't run it, so it's `trek:scalingo` now.
+      # Removed in Trek 3.
+      class ScalingoGenerator < Trek::Generators::ScalingoGenerator
+        hide!
 
-        include Trek::Generators::Helpers
-
-        desc "Create Scalingo files."
-
-        # The trek-buildpack replaces the apt + ruby buildpack combination. It
-        # pins Node from the .node-version that `rails new` already generates.
-        def remove_buildpacks
-          remove_file ".buildpacks"
-        end
-
-        def create_aptfile
-          create_file "Aptfile" do
-            <<~TEXT
-              libjemalloc2
-              libvips-tools --no-install-recommends
-              libwebp-dev
-            TEXT
-          end
-        end
-
-        def create_procfile
-          create_file "Procfile" do
-            <<~TEXT
-              web: bundle exec rails server -p $PORT -e $RAILS_ENV -b 0.0.0.0
-              # worker: bundle exec sidekiq -C config/sidekiq.yml
-              postdeploy: bundle exec rails db:migrate
-            TEXT
-          end
-        end
-
-        def final_instructions
-          say ""
-          say "Configure the Scalingo app environment:"
-          say ""
-          say "    scalingo --app <app> env-set BUILDPACK_URL=#{BUILDPACK_URL}"
-          say "    scalingo --app <app> env-set 'DATABASE_URL=$SCALINGO_POSTGRESQL_URL'"
-          say ""
-          say "and make sure config/database.yml reads DATABASE_URL in production."
-          say ""
-          say "See https://trek.etamin.studio/deploy for details."
-          say ""
+        def deprecation_warning
+          say "`trek:install:scalingo` is deprecated and will be removed in Trek 3: run `trek:scalingo`.", :yellow
         end
       end
     end

data/lib/generators/trek/install_generator.rb

@@ -72,6 +72,11 @@ module Trek
         generate_inline "trek:install:strip_attributes"
       end
 
+      # Before the emails: the mailer configuration points at MailDeliveryJob.
+      def install_jobs
+        generate_inline "trek:install:good_job"
+      end
+
       def install_emails
         generate_inline "trek:install:postmark"
         generate_inline "trek:install:mailer"
@@ -180,6 +185,16 @@ module Trek
         say ""
         say "    make dev"
         say ""
+        say "More generators, to run when the app needs them:"
+        say ""
+        say "    rails g trek:scaffold Book title intro:text   # a model and its admin panel"
+        say "    rails g trek:taxonomies                       # tags and their categories"
+        say "    rails g trek:audit_log                        # a log of the admin's requests"
+        say "    rails g trek:public_accounts Customer         # accounts for the site's users, apart from the admin's"
+        say "    rails g trek:scalingo                         # the files deploying to Scalingo"
+        say ""
+        say "All of Trek's generators and their options: https://trek.etamin.studio/reference/#generators"
+        say ""
       end
 
       private