trek 2.0.1 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 36520ed5aaf6b1c69a1b34ffc8d2bf89bf225c0548edbb62909edf18fa54c16a
-  data.tar.gz: '05296e71c1df00a73fe624ac48e5c0631f048480c643fe01a194c077405bed16'
+  metadata.gz: 5a2b7ab45c51c036cab94f7ab2f6119b84cfccf501d1133cd4f390e320d40aa6
+  data.tar.gz: '0803283b1a6283983d174c9797d5ea753f97ffc1ce458e0285ab2ac681257ecf'
 SHA512:
-  metadata.gz: 796b4ecad9967d6d800ba0ffe37bd3b0e9eb51bbcbfe9d27c1c9e95a0ea6b7393561edf423dfdc2dcf16fda0402097bd83e9a30b2cacf3588133bdf66526502e
-  data.tar.gz: 791afe1a759ffe45012cd98c6d49bf766d72233b65d8b51106eb77a9bd11a1fb45f3fe2a7a2d4247ebf5209807d46094494b3745d94d282a3f811553aac6a05a
+  metadata.gz: 10aea34299dba23456b3f687c6e450996d5473e8d34d9a12200373c2e3f394025e6e5fc2aab4d2dfe00628133113171354780ab3123c6628dc5480e75ed87987
+  data.tar.gz: 966a6004dc2aaa1b7ff21c4db7c87d00e3eb4054ea3dbaec780c62823b0d297f8736be2d93216dc438820375aa3487063882325fd55cb8f612ec831a9179c830

data/.prettierignore

@@ -0,0 +1,2 @@
+# esbuild output (gitignored), present locally after `yarn build`
+app/assets/builds/

data/.rubocop.yml

@@ -33,6 +33,17 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
 
+# rubocop-rails-omakase disables both so it can indent methods under
+# `private`; we use the normal style (methods at the class-body level,
+# `private` included) and want `rubocop --autocorrect` to fix indentation,
+# generated files included.
+Layout/IndentationWidth:
+  Enabled: true
+
+Layout/IndentationConsistency:
+  Enabled: true
+  EnforcedStyle: normal
+
 Gemspec/RequiredRubyVersion:
   Enabled: false
 

data/AGENTS.md

@@ -21,11 +21,13 @@ bin/setup                 # bundle install + yarn install (dev setup)
 bin/console               # IRB with trek loaded
 rake                      # default: spec + rubocop
 rake spec                 # run tests (or: bundle exec rspec)
+make lint                 # all linters below
+make fix                  # rubocop/eslint/stylelint/prettier autocorrect
 make release              # bump version (version.rb + package.json), stamp CHANGELOG, tag, push gem + npm
 yarn docs:dev             # VitePress docs locally
 ```
 
-Linters (also run automatically via lefthook on pre-commit):
+Linters (`make lint`; also run automatically via lefthook on pre-commit):
 
 ```bash
 bundle exec rubocop
@@ -51,5 +53,6 @@ Security: `bundle exec brakeman` · `bundle exec bundle-audit check --update`
 - **Slim** linted via slim_lint; **JS/CSS** via ESLint + Stylelint + Prettier 2.8.8
 - **i18n**: keep English + French locales in sync (`config/locales/trek.*.yml`); DeepL auto-translation via `DEEPL_AUTH_KEY`
 - **Versioning**: version lives in both `lib/trek/version.rb` and `package.json` — keep in sync via `make release`
-- **CHANGELOG.md**: Keep-a-Changelog format. **Every MR must add an `[Unreleased]` entry.** When the change requires action in the host app on upgrade, add an "Upgrade note" describing what to do. When the change lets host apps remove or simplify existing patches or custom implementations, mention that too (e.g. "you can now drop your custom …").
+- **CHANGELOG.md**: Keep-a-Changelog format. **Every MR must add an `[Unreleased]` entry.** When the change requires action in the host app on upgrade, end the entry with a bold `**Upgrade note:**` label followed by what to do. Use the same label when the change lets host apps remove or simplify existing patches or custom implementations (e.g. "**Upgrade note:** you can now drop your custom …") — never as an unlabelled trailing sentence.
+- **Public code**: Trek ships publicly (gem, npm, docs), so nothing committed may mention a client or project name, nor a client's domain models or business logic — not in code, comments, specs, templates, docs, CHANGELOG or commit messages. Use neutral examples (`Page`, `Shop::Product`, an engine's `Blog::Post`). Client context belongs in GitLab issues and MR descriptions only.
 - **CI**: GitLab CI (`.gitlab-ci.yml`), stages build → lint → security → test → deploy; docs deploy to Netlify; deps via Renovate

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## [Unreleased]
 
+## [2.1.0] - 2026-08-25
+
+### Added
+
+- Docs: a [Deploying to Scalingo](https://trek.etamin.studio/deploy) guide covering the trek-buildpack setup, the environment to configure, and how to migrate an app from the stock buildpacks.
+- `trek:install:prosopite` generator (wired into `trek:install`) sets up [Prosopite](https://github.com/charkost/prosopite) N+1 query detection (#211): adds `prosopite` and `pg_query` to the `development`/`test` Gemfile group and a `config/initializers/prosopite.rb` that mounts the Rack middleware — so every request is scanned, Trek's engine controllers included — raising `Prosopite::NPlusOneQueriesError` in test and logging in development. It also generates `spec/requests/admin/n_plus_one_spec.rb`, a smoke request spec rendering the dashboard, pages index and fragments index as an admin (extend it with the app's other admin routes). Documented under [Controllers › N+1 detection](https://trek.etamin.studio/reference/controllers#n-1-detection) with the `Prosopite.pause` escape hatch. **Upgrade note:** existing apps can run `rails g trek:install:prosopite`; apps that already wired Prosopite by hand can keep their setup (the generator skips the gems when `prosopite` is already in the Gemfile and won't overwrite an existing initializer).
+- `make lint` and `make fix` targets in Trek's own Makefile, mirroring the ones generated for host apps (RuboCop, slim-lint, ESLint, Stylelint, Prettier — the `fix` variant autocorrects all but slim-lint). A `.prettierignore` excludes the gitignored esbuild output in `app/assets/builds/`, which made the Prettier check fail on a local checkout that had run `yarn build`.
+- `Trek::MenuComponent` items accept an `active:` option for menu entries whose pages live under other controllers: a `String` is matched as a `controller_path` prefix, a `Regexp` against the whole path, and a boolean forces (or clears) the state — e.g. `s.with_item(text: …, href: [:admin, Shop], active: "admin/shop")` keeps _Shop_ highlighted while editing its products. Without it, the item stays active when its href matches the current controller, as before.
+- `content_editor` accepts an `autofocus:` option (default `false`): when true, the editor grabs focus on mount with the cursor at the end of the content — useful when the editor is the primary field of a side panel.
+
+### Changed
+
+- The shared `.rubocop.yml` (Trek's own, and the one `trek:install:rubocop` copies into host apps) re-enables `Layout/IndentationWidth` and `Layout/IndentationConsistency` with `EnforcedStyle: normal`. rubocop-rails-omakase disables both to allow its house style of indenting methods under `private`; Trek's style keeps methods at the class-body level, and a plain `rubocop --autocorrect` now fixes indentation — in generated files too. **Upgrade note:** copy the two cop blocks from the template (`rails g trek:install:rubocop` will prompt to overwrite) into your app's `.rubocop.yml`, then run `bundle exec rubocop --autocorrect` once; methods indented under `private` and mis-indented generated files get fixed.
+- `trek:install:scalingo` now targets the dedicated [trek-buildpack](https://github.com/etaminstudio/trek-buildpack) (#193) instead of the stock apt + ruby buildpack pair: it no longer generates `.buildpacks` (and removes an existing one) and prints the `env-set` commands to run (`BUILDPACK_URL` pinned to the buildpack's release tag, and the `DATABASE_URL=$SCALINGO_POSTGRESQL_URL` mapping). The buildpack pins Ruby/Node/Yarn from `.ruby-version`, the `.node-version` that `rails new` already generates, and `package.json`'s `packageManager`, runs `yarn install` once, and ships a slimmed image (~40% smaller, measured deploys down from ~3min to ~1min35) — see the buildpack README for details. **Upgrade note:** on each Scalingo app, set `BUILDPACK_URL=https://github.com/etaminstudio/trek-buildpack#v0.1.0`, delete `.buildpacks`, make sure `.node-version` exists (apps generated with `rails new -j esbuild` have it), and check that `config/database.yml` reads `DATABASE_URL` in production (mapped with `scalingo env-set 'DATABASE_URL=$SCALINGO_POSTGRESQL_URL'`).
+- `Trek::Form::FieldsetComponent`: the fieldset title (`.c-trek--form--fieldset-title`) now shares the form group label style (`--slate-12`, semibold, `1.2rem` bottom margin) so a titled fieldset reads like a labelled group; the `section` modifier only adds its larger font size on top. Hosts that restyled the plain fieldset title themselves can drop that override.
+- `trek:install:yarn` now installs **Yarn 4.18.0** (was 4.17.0). **Upgrade note:** existing apps can upgrade with `yarn set version 4.18.0` followed by `yarn install`.
+
+### Fixed
+
+- `trek:scaffold` now references the model top-level qualified (`::Shop::Product`) in the generated controller's `model` and in the `Admin::Dashboard::MODELS_IN_MENU` entry: once the scaffold creates the `Admin::Shop` namespace, a bare `Shop` under `module Admin` resolves to that module instead of the model — the scaffolded controller raised `NameError`, and previously generated code referencing a `Shop` model silently got the module. The generator also warns when a namespace segment matches an existing model file that `rails g model` would replace with a namespace module. (#201) **Upgrade note:** if a scaffold introduced a namespace named like an existing model, qualify that model as `::Shop` in the existing `Admin::…Controller#model` and `MODELS_IN_MENU` entries.
+- `Trek::Entries::ItemComponent`: the details list (`.c-trek--entries--item-details`) now wraps (`flex-wrap: wrap`) instead of overflowing or squeezing its items when an entry has many details or a narrow container.
+- `trek:install:postmark` is idempotent again: re-running it on an app where it had already run appended a second `config.action_mailer.delivery_method = :postmark` / `postmark_settings` block to `config/environments/production.rb` (the gem, credentials and mailer steps were already guarded). The config injection is now skipped when the file already sets `delivery_method = :postmark`. (#210)
+- Namespaced models (e.g. `Shop::Product`, routed under `namespace :shop`) now work out of the box with `Trek::ResourceController` (#212): `object_params` requires `model_name.param_key` (`shop_product`) instead of the demodulized element, so create/update no longer 400; `model_element_route` no longer prefixes the namespace when the route key already carries it (`shop_product`), so the delete button and list item links build `admin_shop_product_path` instead of the double-namespaced `admin_shop_shop_product_path` — models from isolated engines with relative naming (e.g. an engine's `Blog::Post`, route key `post`) keep the `[:blog, :post]` form; the controller defines `implicit_authorization_target` (`@object || model`) so `authorized(params)` and `Trek::Reorderable#reorder`'s bare `authorize!` find the policy; and `i18n_model_gender` reads `activerecord.models.<i18n_key>.gender` (`shop/product`), so `i18n_resource_label` picks the declared gender instead of the neutral fallback. **Upgrade note:** hosts that worked around this with a controller concern overriding `implicit_authorization_target`/`object_params`/`model_element_route`, or a prepend on `Trek::I18nHelper#i18n_model_gender`, can drop them.
+- `Trek::Form::GroupComponent` now styles `input[type="time"]` like `input[type="date"]` (field frame, 16rem max width, lighter picker colour); `time_field`s used to render as bare browser inputs.
+- Removed the dangling `sourceMappingURL` comment from the vendored `tom_select/css/tom-select.custom.css`: the referenced `.map` file is not shipped, so every host-app esbuild build (including `assets:precompile` on deploy) logged a `missing-source-map` debug warning. (#209)
+- `trek:scaffold` now re-indents the generated controller and policy: for a namespaced model the nested `module` wrappers were emitted without indenting the class body, tripping the host app's linters. The generator runs a targeted `rubocop --autocorrect --only Layout/IndentationWidth,Layout/IndentationConsistency` on both files (forced with `--only` since rubocop-rails-omakase leaves those cops disabled). (#199)
+- The `config/initializers/host.rb` generated by `trek:install:config` no longer references `ActionMailer::Base` during the initializer phase: doing so fires Action Mailer's load hook before the app's autoloader can resolve app classes, so an app configuring a custom `config.action_mailer.delivery_job` (e.g. `"MailDeliveryJob"`) crashed with a `NameError` on every production boot — breaking `assets:precompile` on deploy. The assignment is now deferred with `ActiveSupport.on_load(:action_mailer)`. (#208) **Upgrade note:** apply the same change to your app's `config/initializers/host.rb` — replace the `ActionMailer::Base.default_url_options = … if Rails.env.production?` line with the deferred block (see the generator template).
+- `trek:scaffold` now generates the right controller class for a namespaced model (e.g. `rails g trek:scaffold Shop::Product`): the template used the still-namespaced `controller_class_name` inside the per-namespace `module` wrappers, defining `Admin::Shop::Shop::ProductsController` while the generated route expected `Admin::Shop::ProductsController` — every request 404ed with an uninitialized constant. The class name is now demodulized, like the policy template already did. (#200)
+- The `show.html.slim` generated by `trek:scaffold` no longer ends with a trailing blank line: the attribute loop emitted its separator after every item instead of between items, so slim-lint failed in host apps with `TrailingBlankLines: Multiple empty lines in the end of file`. (#205)
+- `trek:upgrade:v2` now upgrades Yarn to 4.18.0 first (applying the 0.1.26 upgrade note: `yarn set version` + dropping the `interactive-tools` plugin) when the app still runs Yarn 3. Previously the generator wrote `npmPreapprovedPackages` — a Yarn 4-only setting — unconditionally, which under Yarn 3 is a hard error that breaks every yarn command, including the generator's own `yarn add` step.
+- Clarified the 0.1.26 changelog upgrade note about the Yarn minimal-age-gate exemption: it only applied to the pre-2.0.0 private GitLab distribution — since 2.0.0 the (Yarn 4-only) `npmPreapprovedPackages` entry, set up automatically by `trek:install` and `trek:upgrade:v2`, replaces it.
+- Fixed whitespace in `model.en.yml.tt` which caused prettier to fail.
+
 ## [2.0.1] - 2026-08-18
 
 ### Fixed
@@ -41,7 +74,7 @@
 ### Fixed
 
 - Added the missing French translations that fell back to English: `admin.dialog_component.{title,text}` (the confirmation dialog shown on every destroy action) and `admin.{pages,fragments}.{show.intro,reorder.success,search.alert}`. Also added the English `admin.section`/`admin.sections` flash messages that previously existed only in French. (#194)
-- `trek:install:yarn` now exempts the `@etaminstudio` scope from Yarn's minimal-age gate (`npmMinimalAgeGate: 0` under `npmScopes.etaminstudio` in the generated `.yarnrc.yml`), so a freshly published `@etaminstudio/trek` release installs without being quarantined; the gate still applies to public packages. **Upgrade note:** existing apps can add `npmMinimalAgeGate: 0` under `npmScopes.etaminstudio` in their `.yarnrc.yml`.
+- `trek:install:yarn` now exempts the `@etaminstudio` scope from Yarn's minimal-age gate (`npmMinimalAgeGate: 0` under `npmScopes.etaminstudio` in the generated `.yarnrc.yml`), so a freshly published `@etaminstudio/trek` release installs without being quarantined; the gate still applies to public packages. **Upgrade note:** existing apps can add `npmMinimalAgeGate: 0` under `npmScopes.etaminstudio` in their `.yarnrc.yml`. _(Only relevant to the private GitLab distribution used before 2.0.0: the `@etaminstudio` scope is retired since then, so this scope exemption does nothing for the public unscoped `trek` package. From 2.0.0 the equivalent is `trek` listed under `npmPreapprovedPackages` — a Yarn 4-only setting, hence the Yarn upgrade above — which `trek:install` generates and `trek:upgrade:v2` adds during migration, so no manual step is needed.)_
 - `trek:install:locales` no longer generates an invalid `config/initializers/locales.rb` (`I18n.available_locales = [:]` / `I18n.default_locale = :`) when passed no or blank locales. A blank option/env now falls back to the default (`en, fr`), blank entries are dropped, and the list can never end up empty. (#169)
 
 ## [0.1.25] - 2026-07-01

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trek (2.0.1)
+    trek (2.1.0)
       action_policy (~> 0.6)
       actioncable
       acts_as_list (~> 1.1)

data/Makefile

@@ -1,5 +1,18 @@
 .PHONY: *
 
+lint:
+	bundle exec rubocop
+	bundle exec slim-lint "app/**/*.slim"
+	yarn eslint "app/**/*.js"
+	yarn stylelint "app/**/*.css"
+	yarn prettier --check "{app,config,lib,spec}/**/*.{css,js,json,md,yml}"
+
+fix:
+	bundle exec rubocop --autocorrect
+	yarn eslint "app/**/*.js" --fix
+	yarn stylelint "app/**/*.css" --fix
+	yarn prettier --write "{app,config,lib,spec}/**/*.{css,js,json,md,yml}"
+
 release:
 	@read -p "New version (current: $$(sed -n 's/.*VERSION = "\(.*\)"/\1/p' lib/trek/version.rb)): " version; \
 	if [ -z "$$version" ]; then echo "Version cannot be empty"; exit 1; fi; \

data/app/components/trek/entries/item_component/item_component.css

@@ -92,6 +92,7 @@ table .root {
 .details {
   color: var(--slate-9);
   display: flex;
+  flex-wrap: wrap;
   font-size: 1.3rem;
   line-height: 1.2;
   list-style: none;

data/app/components/trek/form/content_editor_component/content_editor_component.js

@@ -23,6 +23,7 @@ export class Controller extends BaseController {
   ];
   static values = {
     placeholder: String,
+    autofocus: Boolean,
   };
 
   connect() {
@@ -55,6 +56,7 @@ export class Controller extends BaseController {
         PromptsBlock,
       ],
       content: this.contentJson,
+      autofocus: this.autofocusValue ? "end" : false,
     });
 
     this.editor.on("update", () => this.updateContent());

data/app/components/trek/form/content_editor_component.rb

@@ -8,7 +8,7 @@ module Trek
       include Turbo::FramesHelper
       include ViewComponent::Translatable
 
-      attr_reader :nodes, :blocks, :floating
+      attr_reader :nodes, :blocks, :floating, :autofocus
 
       def initialize(form, object_name, method_name, options = {})
         @nodes = options.delete(:nodes)
@@ -17,6 +17,7 @@ module Trek
         @blocks = true if @blocks.nil?
         @floating = options.delete(:floating)
         @floating = true if @floating.nil?
+        @autofocus = options.delete(:autofocus) || false
 
         super
       end
@@ -29,7 +30,8 @@ module Trek
         }.merge(
           stimulus_class_hash("active", class_for("is-active")),
           stimulus_class_hash("empty", class_for("is-empty")),
-          stimulus_value_hash("placeholder", t(".placeholder"))
+          stimulus_value_hash("placeholder", t(".placeholder")),
+          stimulus_value_hash("autofocus", autofocus)
         )
       end
 

data/app/components/trek/form/fieldset_component/fieldset_component.css

@@ -10,6 +10,10 @@
 }
 
 .title {
+  color: var(--slate-12);
+  display: block;
+  font-weight: var(--semibold);
+  margin-bottom: 1.2rem;
   margin-left: -1rem;
   padding: 0 1rem;
 }
@@ -35,8 +39,5 @@
 }
 
 .root.section .title {
-  color: var(--slate-12);
   font-size: 1.2em;
-  font-weight: var(--semibold);
-  margin-bottom: 1.2rem;
 }

data/app/components/trek/form/group_component/group_component.css

@@ -32,6 +32,7 @@
 .root input[type="text"],
 .root input[type="url"],
 .root input[type="date"],
+.root input[type="time"],
 .root select,
 .root textarea {
   background-color: var(--slate-2);
@@ -55,7 +56,8 @@
 
 .root input[type="number"],
 .root input[name*="color"],
-.root input[type="date"] {
+.root input[type="date"],
+.root input[type="time"] {
   max-width: 16rem;
 }
 
@@ -63,7 +65,8 @@
   max-width: 19rem;
 }
 
-.root input[type="date"] {
+.root input[type="date"],
+.root input[type="time"] {
   color: var(--slate-11);
   font-weight: var(--light);
 }

data/app/components/trek/menu_component.rb

@@ -57,6 +57,11 @@ module Trek
         option :href
         option :text
         option :allowed_to, default: -> { true }
+        # Overrides the active state for a section whose sub-resources live under other
+        # controllers: a String is a controller_path prefix ("admin/shop"), a Regexp is matched
+        # against it, a boolean forces the state. By default the item is active when its href
+        # matches the current controller.
+        option :active, optional: true
 
         def call
           tag.li(
@@ -79,10 +84,18 @@ module Trek
         private
 
         def active?
-          href_path = Array.wrap(href).map do |part|
+          case active
+          when nil then href_path == controller_path
+          when String then controller_path.start_with?(active)
+          when Regexp then active.match?(controller_path)
+          else active
+          end
+        end
+
+        def href_path
+          Array.wrap(href).map do |part|
             part.respond_to?(:model_name) ? part.model_name.collection : part
           end.join("/").sub("root", "dashboards")
-          href_path == controller_path
         end
       end
     end

data/app/controllers/concerns/trek/model.rb

@@ -21,7 +21,7 @@ module Trek
     end
 
     # Returns model collection as an array of symbols for route building.
-    # For namespaced models like Missive::List, returns [:missive, :lists].
+    # For namespaced models like Shop::Product, returns [:shop, :products].
     # For non-namespaced models like Page, returns [:pages].
     def model_collection_route
       model_name.collection.split("/").map(&:to_sym)
@@ -32,13 +32,20 @@ module Trek
     end
 
     # Returns model element as an array of symbols for route building.
-    # For namespaced models like Missive::List, returns [:missive, :list].
     # For non-namespaced models like Page, returns [:page].
-    # Derived from collection (which preserves namespace) rather than element
-    # (which demodulizes).
+    # For namespaced models, it depends on the route key: callers build member
+    # routes as `[:admin, *model_element_route[0...-1], record]`, and the
+    # record's route key must not carry the namespace twice.
+    # - Shop::Product (plain app namespace, route key `shop_product`)
+    #   returns [:shop_product] — a [:shop, :product] prefix would yield
+    #   `admin_shop_shop_product_path`.
+    # - Blog::Post from an isolated engine (`isolate_namespace` → relative
+    #   model naming, route key `post`) returns [:blog, :post], since the
+    #   namespace segment is needed for `admin_blog_post_path`.
     def model_element_route
-      parts = model_name.collection.split("/")
-      (parts[0...-1] + [parts.last.singularize]).map(&:to_sym)
+      element = model_name.singular_route_key
+      namespace = element == model_name.element ? model_name.collection.split("/")[0...-1] : []
+      (namespace + [element]).map(&:to_sym)
     end
 
     def model_intro(action: nil)

data/app/controllers/trek/resource_controller.rb

@@ -79,8 +79,16 @@ module Trek
       authorize! @object
     end
 
+    # The form posts under model_name.param_key, which keeps the namespace
+    # (shop_product for Shop::Product) unlike model_element (product).
     def object_params
-      authorized(params.require(model_element))
+      authorized(params.require(model_name.param_key))
+    end
+
+    # action_policy infers the target from controller_name.classify, which
+    # doesn't exist for a namespaced model (Product for Shop::Product).
+    def implicit_authorization_target
+      @object || model
     end
   end
 end

data/app/helpers/trek/i18n_helper.rb

@@ -11,7 +11,7 @@ module Trek
     end
 
     def i18n_model_gender(model_name)
-      t("activerecord.models.#{model_name.element}.gender", default: "n")
+      t("activerecord.models.#{model_name.i18n_key}.gender", default: "n")
     end
 
     def boolean_collection(key: "boolean_labels")

data/docs/.vitepress/config.mjs

@@ -33,7 +33,8 @@ export default defineConfig({
         {
           text: 'Guides',
           items: [
-            { text: 'How to customize Trek', link: '/customize' }
+            { text: 'How to customize Trek', link: '/customize' },
+            { text: 'Deploying to Scalingo', link: '/deploy' }
           ]
         },
         {

data/docs/deploy.md

@@ -0,0 +1,57 @@
+# Deploying to Scalingo
+
+Trek apps deploy to [Scalingo](https://scalingo.com) with the dedicated [trek-buildpack](https://github.com/etaminstudio/trek-buildpack), a single buildpack that replaces the usual `apt` + `ruby` buildpack pair and knows how a Trek app is built.
+
+## What the buildpack does
+
+- installs the APT packages listed in `Aptfile` (image processing libraries, jemalloc), skipping `apt-get update` and package resolution entirely when the `Aptfile` is unchanged
+- installs Ruby with [rv](https://rv.dev) — precompiled, in seconds — using the version pinned in `.ruby-version`
+- installs Node.js pinned by `.node-version` (generated by `rails new`), and the exact Yarn release pinned by `package.json`'s `packageManager` field — no unpinned defaults
+- runs `yarn install` exactly once, with a persistent cache, before `assets:precompile`
+- slims the shipped image: `node_modules`, Yarn caches and Node.js itself are dropped after the build, roughly halving the image size of a typical Trek app — faster deploys, restarts and scaling
+
+Compared with the stock buildpacks, deploys typically go from around 3 minutes to about 1 minute 30 with a warm cache.
+
+## Set up the app
+
+Generate the Scalingo files (an `Aptfile` and a `Procfile` with the web process and post-deploy migrations):
+
+```sh
+rails g trek:install:scalingo
+```
+
+Then configure the Scalingo app's environment, pinning the buildpack to a release tag:
+
+```sh
+scalingo --app <app> env-set BUILDPACK_URL=https://github.com/etaminstudio/trek-buildpack#v0.1.0
+scalingo --app <app> env-set 'DATABASE_URL=$SCALINGO_POSTGRESQL_URL'
+scalingo --app <app> env-set RAILS_MASTER_KEY=$(cat config/master.key)
+```
+
+Make sure `config/database.yml` reads `DATABASE_URL` in production — the section `rails new` generates targets a local socket with a password variable instead:
+
+```yml
+production:
+  primary: &primary_production
+    <<: *default
+    url: <%= ENV["DATABASE_URL"] %>
+```
+
+Provision a PostgreSQL addon (`scalingo --app <app> addons-add postgresql <plan>`), push, and the app boots with `RAILS_ENV`, `RAILS_LOG_TO_STDOUT` and `RAILS_SERVE_STATIC_FILES` already set by the buildpack.
+
+## Options
+
+| Variable | Effect |
+| --- | --- |
+| `TREK_BUILDPACK_RUNTIME_NODE=1` | Ship Node.js in the image (only if the app runs JavaScript at runtime, e.g. execjs) |
+| `TREK_BUILDPACK_PRUNE_SOURCEMAPS=1` | Also remove `.map` files from the compiled assets |
+
+## Migrating an existing app
+
+Apps deployed with the stock `.buildpacks` (apt + ruby) migrate in three steps:
+
+1. delete `.buildpacks` (re-running `rails g trek:install:scalingo` does it) and check that `.node-version` exists — apps generated with `rails new -j esbuild` have it
+2. set `BUILDPACK_URL` as above, and map `DATABASE_URL` if the app doesn't read it yet
+3. deploy — the first build fills the caches, the next ones benefit from them
+
+The buildpack's [README](https://github.com/etaminstudio/trek-buildpack#readme) details the cache layout and the `Aptfile` syntax.

data/docs/getting-started.md

@@ -132,3 +132,4 @@ Next steps:
 
 - [Customize Trek](/customize) — branding, favicon, components
 - [Reference manual](/reference/) — generators, models, components and more
+- [Deploying to Scalingo](/deploy) — `trek:install:scalingo`, a few environment variables, and the dedicated trek-buildpack handles the rest

data/docs/reference/controllers.md

@@ -93,3 +93,26 @@ end
 ```
 
 Like `Trek::Filters`, forgetting to call `apply_scopes!` raises `Trek::Scopes::NotAppliedError` outside production.
+
+## N+1 detection
+
+`trek:install:prosopite` (part of `trek:install`) sets up [Prosopite](https://github.com/charkost/prosopite)
+in development and test: `config/initializers/prosopite.rb` mounts its Rack middleware, so **every request** —
+including Trek's own engine controllers — is scanned. A detected N+1 raises `Prosopite::NPlusOneQueriesError`
+in test (so request specs fail) and is logged in development.
+
+The generator also adds `spec/requests/admin/n_plus_one_spec.rb`, a smoke request spec that renders the
+dashboard, the pages index and the fragments index as an admin — extend its route table with the app's other
+admin pages (scaffolded indexes and edit pages in particular), with a few records created beforehand, since an
+empty list can't reveal an N+1.
+
+Legitimate repeated queries (e.g. one `COUNT` per row) can be exempted with the escape hatch:
+
+```ruby
+Prosopite.pause do
+  scopes.index_with { |scope| relation.public_send(scope).count }
+end
+```
+
+Trek's own concerns already do this where needed (`Trek::Scopes#scope_counts`). Guard with
+`if defined?(Prosopite)` in code that must also run in production, where the gem isn't loaded.

data/docs/reference/generators/install.md

@@ -32,7 +32,9 @@ The installer orchestrates dedicated sub-generators, all under the `trek:install
 | Tooling | esbuild, PostCSS, EditorConfig, Procfiles, Makefile, health check endpoint |
 | Linting | Standard, ESLint, Stylelint, Prettier, Slim Lint, Lefthook git hooks |
 | Security | Brakeman, bundler-audit, ruby_audit |
+| N+1 detection | Prosopite (development/test), scanning every request — see [Controllers › N+1 detection](/reference/controllers#n-1-detection) |
 | CI | GitLab CI configuration |
+| Deployment | Scalingo files (`trek:install:scalingo`, run on demand) — see [Deploying to Scalingo](/deploy) |
 
 ## ENV variables read by the installer
 

data/docs/reference/generators/scaffold.md

@@ -18,6 +18,18 @@ Akin to Rails', Trek's scaffold generates, with a single command:
 
 Standard Rails attribute types are supported (`string`, `text`, `integer`, `float`, `decimal`, `boolean`, `date`, `datetime`, `references`…) and mapped to the matching [form helpers](/reference/forms): `text` renders the content editor, `boolean` a switch box, `references` a collection select, and so on.
 
+## Namespaced models
+
+```sh
+rails g trek:scaffold Shop::Product name price:decimal
+```
+
+The controller and policy are nested accordingly (`Admin::Shop::ProductsController`, `Admin::Shop::ProductPolicy`), the routes go under `namespace :shop`, and everything else follows the namespace.
+
+The generated code references the model as `::Shop::Product`, top-level qualified, and the dashboard menu entry is `::Shop::Product` too. This is deliberate: once `Admin::Shop` exists, a bare `Shop` written anywhere under `module Admin` resolves to that namespace instead of the `Shop` model. Existing admin code that references such a model — an `Admin::ShopsController#model` returning `Shop`, or a `Shop` entry in `Admin::Dashboard::MODELS_IN_MENU` — must be updated to `::Shop` once a scaffold introduces a namespace with the same name (the menu would otherwise silently list the module).
+
+Also note that `rails g model Shop::Product` (which the scaffold runs) writes `app/models/shop.rb` as a `module Shop` namespace file; if a `Shop` model already lives there, the generator warns and Rails asks before overwriting it — move the model or answer `n`.
+
 ## Opt-in concerns
 
 The generated model ships with commented-out hooks for Trek's most useful [concerns](/reference/), ready to be enabled when needed:

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

@@ -25,7 +25,15 @@ module Trek
 
               # Mailers run outside a request, so in production they need the same host for
               # link helpers. Development and test keep the host from their environment files.
-              ActionMailer::Base.default_url_options = Rails.application.routes.default_url_options if Rails.env.production?
+              # Deferred with on_load: referencing ActionMailer::Base here would load it
+              # before the app's autoloader can resolve app classes, and its load hook
+              # constantizes config.action_mailer.delivery_job — NameError at boot when
+              # the app configures a custom delivery job.
+              if Rails.env.production?
+                ActiveSupport.on_load(:action_mailer) do
+                  self.default_url_options = Rails.application.routes.default_url_options
+                end
+              end
             RUBY
           end
         end

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

@@ -28,6 +28,8 @@ module Trek
         end
 
         def inject_postmark_to_config
+          return if File.read("config/environments/production.rb").include?("delivery_method = :postmark")
+
           inject_into_file "config/environments/production.rb",
             config_injection,
             after: %r{# Specify outgoing SMTP server\. Remember to add smtp/\* credentials via (?:bin/)?rails credentials:edit\.\n}

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

@@ -0,0 +1,56 @@
+require "rails/generators/actions"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    module Install
+      class ProsopiteGenerator < Rails::Generators::Base
+        include Trek::Generators::Helpers
+
+        desc "Install Prosopite (N+1 query detection)."
+
+        source_root File.expand_path("../templates", __dir__)
+
+        def add_gems
+          return if in_gemfile?("prosopite")
+
+          gem "prosopite", group: [:development, :test],
+            comment: "N+1 query detection (raises in test, logs in development) [https://github.com/charkost/prosopite]"
+          gem "pg_query", group: [:development, :test]
+          bundle_install
+        end
+
+        def create_initializer
+          return if File.exist?("config/initializers/prosopite.rb")
+
+          create_file "config/initializers/prosopite.rb" do
+            <<~RUBY
+              # N+1 query detection with Prosopite, in development and test only (the gem is not loaded in production).
+              # Every request is scanned by the Rack middleware, which also covers Trek's engine controllers.
+              # Detected N+1s raise Prosopite::NPlusOneQueriesError in test and are logged in development.
+              # Legitimate repeated queries can be wrapped in `Prosopite.pause { … }`.
+              if defined?(Prosopite)
+                require "prosopite/middleware/rack"
+
+                Rails.application.configure do
+                  config.middleware.use(Prosopite::Middleware::Rack)
+                end
+
+                Rails.application.config.after_initialize do
+                  Prosopite.rails_logger = true
+                  Prosopite.raise = Rails.env.test?
+                end
+              end
+            RUBY
+          end
+        end
+
+        def create_smoke_spec
+          return if File.exist?("spec/requests/admin/n_plus_one_spec.rb")
+
+          copy_file "spec/requests/admin/n_plus_one_spec.rb", "spec/requests/admin/n_plus_one_spec.rb"
+        end
+      end
+    end
+  end
+end

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

@@ -5,17 +5,16 @@ module Trek
   module Generators
     module Install
       class ScalingoGenerator < Rails::Generators::Base
+        BUILDPACK_URL = "https://github.com/etaminstudio/trek-buildpack#v0.1.0".freeze
+
         include Trek::Generators::Helpers
 
         desc "Create Scalingo files."
 
-        def create_buildpacks
-          create_file ".buildpacks" do
-            <<~TEXT
-              https://github.com/Scalingo/apt-buildpack.git
-              https://github.com/Scalingo/ruby-buildpack.git
-            TEXT
-          end
+        # 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
@@ -37,6 +36,19 @@ module Trek
             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 ""
+        end
       end
     end
   end

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

@@ -5,7 +5,7 @@ module Trek
   module Generators
     module Install
       class YarnGenerator < Rails::Generators::Base
-        YARN_VERSION = "4.17.0"
+        YARN_VERSION = "4.18.0"
 
         include Trek::Generators::Helpers
 

data/lib/generators/trek/install_generator.rb

@@ -25,6 +25,7 @@ module Trek
         generate "trek:install:postcss"
         generate "trek:install:prettier"
         generate "trek:install:procfiles"
+        generate "trek:install:prosopite"
         generate "trek:install:rubocop"
         generate "trek:install:slim_lint"
         generate "trek:install:stylelint"

data/lib/generators/trek/scaffold_generator.rb

@@ -15,6 +15,18 @@ module Trek
 
       source_root File.expand_path("templates", __dir__)
 
+      # `rails g model Shop::Product` writes app/models/shop.rb as a `module Shop`
+      # namespace file; if a `Shop` model already lives there, it gets replaced.
+      def warn_about_shadowed_models
+        model_namespaces.each do |ns|
+          path = "app/models/#{ns}.rb"
+          next unless File.exist?(path) && File.read(path).match?(/^class #{ns.camelize}\b/)
+
+          say_status :warning, "#{path} defines the #{ns.camelize} model, which the #{ns.camelize} namespace " \
+            "would replace — answer 'n' below to keep it, or move the model first", :red
+        end
+      end
+
       def create_model
         generate :model, class_name, attributes.map { |a| "#{a.name}:#{a.type}" }
       end
@@ -32,7 +44,8 @@ module Trek
 
       def create_controller
         template "controllers/admin/scaffold_controller.rb",
-          "app/controllers/admin/#{namespaced_plural}_controller.rb"
+          controller_file_path
+        reindent controller_file_path
       end
 
       def create_views
@@ -42,9 +55,11 @@ module Trek
         end
       end
 
+      # Top-level qualified: once an Admin::Shop namespace exists (scaffolded
+      # controller/policy), a bare `Shop` under `module Admin` resolves to it.
       def add_models_to_menu
         inject_into_file dashboard_file_path,
-          "\n#{class_name},",
+          "\n::#{class_name},",
           after: "MODELS_IN_MENU = ["
         run "rubocop --autocorrect #{dashboard_file_path}", abort_on_failure: true
       end
@@ -67,7 +82,8 @@ module Trek
 
       def add_policy
         template "policies/admin/scaffold_policy.rb",
-          "app/policies/admin/#{file_path}_policy.rb"
+          policy_file_path
+        reindent policy_file_path
       end
 
       def add_default_locale_files
@@ -114,6 +130,22 @@ module Trek
         "app/models/admin/dashboard.rb"
       end
 
+      # The templates wrap the class in one `module` per namespace segment
+      # without re-indenting the body; the indentation cops are forced with
+      # --only because rubocop-rails-omakase leaves them disabled.
+      def reindent(path)
+        run "rubocop --autocorrect --only Layout/IndentationWidth,Layout/IndentationConsistency #{path}",
+          abort_on_failure: true
+      end
+
+      def controller_file_path
+        "app/controllers/admin/#{namespaced_plural}_controller.rb"
+      end
+
+      def policy_file_path
+        "app/policies/admin/#{file_path}_policy.rb"
+      end
+
       def model_injection
         <<~RUBY
           # TODO: uncomment to format some attributes, or remove if not needed
@@ -160,12 +192,12 @@ module Trek
         "config/locales/admin/#{file_path}.#{locale}.yml"
       end
 
-      # Returns namespace segments from file_path (e.g., ["missive"] for "missive/list")
+      # Returns namespace segments from file_path (e.g., ["shop"] for "shop/product")
       def model_namespaces
         file_path.split("/")[0...-1]
       end
 
-      # Returns the pluralized path preserving namespaces (e.g., "missive/lists" for "missive/list")
+      # Returns the pluralized path preserving namespaces (e.g., "shop/products" for "shop/product")
       def namespaced_plural
         parts = file_path.split("/")
         parts[-1] = parts[-1].pluralize

data/lib/generators/trek/templates/controllers/admin/scaffold_controller.rb.tt

@@ -2,13 +2,13 @@ module Admin
 <% model_namespaces.each do |ns| -%>
   module <%= ns.camelize %>
 <% end -%>
-  class <%= controller_class_name %>Controller < Trek::ResourceController
+  class <%= controller_class_name.demodulize %>Controller < Trek::ResourceController
     # include Trek::Pagination
 
     private
 
     def model
-      <%= class_name %>
+      ::<%= class_name %>
     end
   end
 <% model_namespaces.each do |_ns| -%>

data/lib/generators/trek/templates/locales/scaffold/model.en.yml.tt

@@ -2,10 +2,11 @@ en:
   activerecord:
     models:
       <%= file_path %>:
-        gender: 'n'
+        gender: "n"
         one: <%= human_name %>
         other: <%= plural_name.humanize %>
     attributes:
-      <%= file_path %>:<%- attributes.each do |attr| %>
+      <%= file_path %>:
+<%- attributes.each do |attr| -%>
         <%= attr.name %>: <%= attr.name.humanize -%>
-      <% end %>
+<%- end -%>

data/lib/generators/trek/templates/spec/requests/admin/n_plus_one_spec.rb

@@ -0,0 +1,28 @@
+require "rails_helper"
+
+# Smoke test for Prosopite (config/initializers/prosopite.rb): each admin page below is rendered
+# as an admin, and any N+1 query raises Prosopite::NPlusOneQueriesError.
+#
+# TODO: add the other admin routes (index and edit pages of scaffolded models in particular), and
+# create a few records first so the per-row queries have something to loop over — an empty list
+# can't reveal an N+1.
+RSpec.describe "Admin pages N+1 queries", type: :request do
+  let(:password) { "secret-password-123" }
+  let(:admin) { User.create!(email: "admin@example.com", password:, role: "admin") }
+
+  before do
+    post admin_user_session_path, params: { email: admin.email, password: }
+  end
+
+  {
+    "dashboard" => -> { admin_root_path },
+    "pages index" => -> { admin_pages_path },
+    "fragments index" => -> { admin_fragments_path }
+  }.each do |page, path|
+    it "renders the #{page} without N+1 queries" do
+      get instance_exec(&path)
+
+      expect(response).to have_http_status(:ok)
+    end
+  end
+end

data/lib/generators/trek/templates/views/admin/scaffold/show.html.slim.tt

@@ -3,8 +3,8 @@
 = render Trek::TabsComponent.new do |c|
   - c.with_item(id: :content, label: t("admin.content"))
     = render Trek::PropertiesComponent.new(model:) do |p|
-<% attributes.each do |attribute| -%>
+<% attributes.each_with_index do |attribute, i| -%>
+<%= "\n" unless i.zero? -%>
       = p.with_item :<%= attribute.column_name %>
         = @object.<%= attribute.column_name %>
-
 <% end -%>

data/lib/generators/trek/upgrade/v2_generator.rb

@@ -1,5 +1,6 @@
 require "rails/generators/actions"
 require "generators/trek/helpers"
+require "generators/trek/install/yarn_generator"
 require "yaml"
 
 module Trek
@@ -66,10 +67,28 @@ module Trek
             "and the etaminstudio scope manually.", :yellow
         end
 
+        def upgrade_yarn
+          return if yarn_major_version >= 4
+
+          # The npmPreapprovedPackages setting below requires Yarn 4 (Yarn 3
+          # hard-errors on it), so apply the 0.1.26 upgrade note as part of the
+          # migration: bump Yarn and drop the interactive-tools plugin, whose
+          # upgrade-interactive command is built into Yarn 4.
+          if File.exist?(".yarnrc.yml") && File.read(".yarnrc.yml").include?("plugin-interactive-tools")
+            run "yarn plugin remove @yarnpkg/plugin-interactive-tools"
+          end
+          run "yarn set version #{Install::YarnGenerator::YARN_VERSION}", abort_on_failure: true
+          @yarn_version = nil
+        end
+
         def preapprove_npm_package
           return unless File.exist?(".yarnrc.yml")
           return if File.read(".yarnrc.yml").include?("npmPreapprovedPackages")
 
+          # Defensive: never write the (Yarn 4-only) setting under Yarn 3,
+          # where it is a hard error that breaks every yarn command.
+          return if yarn_major_version < 4
+
           append_to_file ".yarnrc.yml", <<~YAML
 
             # Trek is our own package — exempt it from Yarn's package gates
@@ -98,6 +117,18 @@ module Trek
               * Revoke this project's Trek deploy token on GitLab.
           SUMMARY
         end
+
+        private
+
+        def yarn_version
+          @yarn_version ||= `yarn --version`.strip
+        rescue Errno::ENOENT
+          @yarn_version = "0"
+        end
+
+        def yarn_major_version
+          yarn_version.to_i
+        end
       end
     end
   end

data/lib/trek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Trek
-  VERSION = "2.0.1"
+  VERSION = "2.1.0"
 end

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trek",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A modern content management & back-office system for Ruby on Rails",
   "homepage": "https://trek.etamin.studio",
   "license": "MIT",

data/vendor/tom_select/css/tom-select.custom.css

@@ -459,4 +459,3 @@
 .ts-dropdown .optgroup:first-child {
   border-top: 0 none;
 }
-/*# sourceMappingURL=tom-select.default.css.map */

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trek
 version: !ruby/object:Gem::Version
-  version: 2.0.1
+  version: 2.1.0
 platform: ruby
 authors:
 - Mohamed Bengrich
@@ -434,6 +434,7 @@ files:
 - ".eslintrc.json"
 - ".node-version"
 - ".npmignore"
+- ".prettierignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".slim-lint.yml"
@@ -737,6 +738,7 @@ files:
 - docs/.vitepress/theme/index.js
 - docs/.vitepress/theme/style.css
 - docs/customize.md
+- docs/deploy.md
 - docs/getting-started.md
 - docs/index.md
 - docs/public/logo.svg
@@ -821,6 +823,7 @@ files:
 - lib/generators/trek/install/postmark_generator.rb
 - lib/generators/trek/install/prettier_generator.rb
 - lib/generators/trek/install/procfiles_generator.rb
+- lib/generators/trek/install/prosopite_generator.rb
 - lib/generators/trek/install/readme_generator.rb
 - lib/generators/trek/install/rubocop_generator.rb
 - lib/generators/trek/install/ruby_generator.rb
@@ -902,6 +905,7 @@ files:
 - lib/generators/trek/templates/policies/page.rb
 - lib/generators/trek/templates/policies/preview.rb
 - lib/generators/trek/templates/policies/user.rb
+- lib/generators/trek/templates/spec/requests/admin/n_plus_one_spec.rb
 - lib/generators/trek/templates/views/admin/dashboards/index.html.slim
 - lib/generators/trek/templates/views/admin/fragments/_form.html.slim
 - lib/generators/trek/templates/views/admin/fragments/_fragment.json.jb