trek 0.1.24 → 0.1.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac23b0f2968a03be59d307c19c62632c761cde58846a324dddd3f745a2bc5e8d
-  data.tar.gz: 30b95227f9369edb137c5208e1b1a390e9fd56efaf6e75143020af418007b7b3
+  metadata.gz: 71867750da0cef4ae1928a4245e69742d7d32c6614c54da4d107f992da5e0e23
+  data.tar.gz: 71cb0d0b2ce4098030705245aaf92b50eefec11b4491bc0180e145eeb2f6a8e3
 SHA512:
-  metadata.gz: d5572d3b2d99a149ae840b7b04643e10bece86e6664f6595349a596b116dc33f07cb988f197d6c8ffc0c47aff9511fcacb328224d7ec9b7590d8a7f9490ee9a5
-  data.tar.gz: 2ac6db32ec1818397cbfd1e321164861d4e1bd0078296a7d37fe71f1a54e92d20793c0c435818eafdbbb489240ec812c4e22dd8e41d201614587a8b08164ac32
+  metadata.gz: 0e3a672cb3ebf8abee38d436832d92d3cc5c8bd5502f37344bda47275d4bd090a7326920cd823ed84e30990cd9feb453dddc2e62bfc1d43967de230498fd8287
+  data.tar.gz: aa4c5e9ee652804fc0361b8ac9e459863f67ff42441484e26fd8387312d8ba70517809b04d81fb68d9b9cab0ea6e6c7a27b943486c80c94b1544678841806fab

data/AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository. Keep it accurate — update it when commands or conventions change.
+
+## What is Trek
+
+Trek is a customizable CMS for Ruby on Rails, shipped as a **Ruby gem** (`trek`) plus a companion **NPM package** (`@etaminstudio/trek`). It's a Rails **engine** (`lib/trek/engine.rb`) that installs a back-office/admin into a host app. Installation and features are driven by Rails generators (`rails g trek:install`, `trek:scaffold`, `trek:admin:user`, …). Authored by Etamin Studio. Private gem hosted on self-hosted GitLab (`git.etaminstud.io`), not public RubyGems.
+
+## Tech stack
+
+- **Ruby** `>= 3.1` (RuboCop targets 3.4) · **Rails** `>= 6.0, < 8.2` (lockfile 8.1.3; host apps need 7.0+)
+- **Node** 22.21.1 (`.node-version`) · **Yarn** 3.8.0 (berry) · **PostgreSQL** 12+ · **libvips** for images
+- Backend: `action_policy`, `closure_tree`, `acts_as_list`, `mobility` + `i18n-tasks`, `shrine` (+ blurhash/image_processing/aws-sdk-s3), `view_component` + `slim-rails` + `lookbook`, `kaminari`, `deepl-rb`
+- Frontend: **esbuild** (`esbuild.config.js`) + **PostCSS** (`postcss.config.js`); Stimulus/Turbo, TipTap, Uppy, Tom Select, SortableJS
+- Tests: **RSpec** (`rspec-rails`, capybara, simplecov) · Docs: **VitePress** (`docs/`)
+
+## Commands
+
+```bash
+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 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):
+
+```bash
+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}"
+```
+
+Security: `bundle exec brakeman` · `bundle exec bundle-audit check --update`
+
+## Structure
+
+- `app/` — engine code, namespaced under `trek/`: `components/` (ViewComponents), `controllers/`, `forms/`, `models/`, `policies/` (ActionPolicy), `uploaders/` (Shrine), `views/`, `javascript/` (Stimulus)
+- `lib/generators/trek/` — the heart of the gem: `install/` (~30 generators), `scaffold_generator.rb`, `admin/`, `templates/`
+- `lib/trek/` — `engine.rb`, `version.rb`, `i18n_keys_resolver.rb`, `typography_formatter.rb`
+- `config/locales/` — `trek.en.yml`, `trek.fr.yml`
+- `spec/` — RSpec suite · `docs/` — VitePress site
+
+## Conventions
+
+- **Ruby**: rubocop-rails-omakase + rubocop-rspec (`.rubocop.yml`) — double-quoted strings, line length 120, target 3.4
+- **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 …").
+- **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,25 @@
 ## [Unreleased]
 
+## [0.1.25] - 2026-07-01
+
+### Added
+
+- Invitation and password-reset emails now tell the recipient when the link expires. Invitations get their own `:invite` token purpose (1 week) — distinct from the 15-minute `:password_reset` token — and the generated `Admin::UserPasswordResetsController` accepts either purpose, so the shared "set your password" form works from both emails. Each mailer reads its window from the model's token definition (`User.token_definitions[:purpose].expires_in`) rather than a hardcoded constant. **Upgrade note:** add `generates_token_for :invite, expires_in: 1.week do password_salt&.last(10) end` to your `User`; have `AdminMailer#invite` issue an `:invite` token (and `include ActionView::Helpers::DateHelper`); and update `Admin::UserPasswordResetsController#set_user_by_token` to try both purposes, e.g. `User.privileged.find_by_token_for(:invite, @token) || User.privileged.find_by_token_for!(:password_reset, @token)`.
+- `trek:install` now generates an `AGENTS.md` (onboarding guidance for AI coding agents: commands, conventions, and a "read the changelog on every upgrade" checklist) plus a `CLAUDE.md` that imports it via `See @AGENTS.md`, so Claude Code and other agents share one source of truth. **Upgrade note:** existing apps can add both files by running `rails g trek:install:agents`.
+- `Trek::Filters` controller concern: filter the index by `params[:filters]` (attribute equality via `where`). Call `apply_filters!` in your `index`.
+- Pedagogical `NotAppliedError` guard on `Trek::Filters` and `Trek::Scopes`: raises (outside production) when the concern is included but `index` never calls `apply_filters!` / `apply_scopes!`.
+- `trek:install:scalingo` now adds `libjemalloc2` to the generated `Aptfile`, enabling the jemalloc allocator to reduce Ruby memory usage on Scalingo.
+
+### Fixed
+
+- The generated dashboard's "search a user" tile now links to the users index (`href: %i[admin users]`) instead of a dead `#`, and gates on `allowed_to: allowed_to?(:index?, User)` so roles that can't reach user management no longer see it (matching the sidebar's Users entry). **Upgrade note:** existing apps can set `href: %i[admin users]` and add `allowed_to: allowed_to?(:index?, User)` on that tile in `app/views/admin/dashboards/index.html.slim`.
+- `trek:install` now points Action Mailer at the same host as the routes' `default_url_options` (driven by `DEFAULT_HOSTNAME`) in the generated `config/initializers/host.rb`, in production only (development and test keep the host from their environment files). Previously the mailer kept Rails' `example.com` default, so invitation and password-reset email links pointed to `https://example.com/...` in production. **Upgrade note:** existing apps can add `ActionMailer::Base.default_url_options = Rails.application.routes.default_url_options if Rails.env.production?` to their `config/initializers/host.rb` (and drop any hardcoded `config.action_mailer.default_url_options` host).
+- The generated `Admin::UsersController` (`trek:install`) seeds a random password in `create_hook`, so users created via the admin form — which never collects one — satisfy `has_secure_password` and the non-null `password_digest` column. Invitees set their real password via the invite email; others via password reset. (Password seeding lives in the controller rather than `Trek::Users::Invitable` so it also covers users created without an invite.) **Upgrade note:** ensure your `Admin::UsersController#create_hook` seeds a password when blank: `@object.password = SecureRandom.alphanumeric(24) if @object.password.blank?`.
+- `trek:install:ci` now sets `POSTGRES_DB` in `.gitlab-ci.yml` from the application name (e.g. `myapp_test`) instead of the hardcoded `project_test`.
+- `trek:install:yarn` now rewrites `bin/setup`'s `yarn install --check-files` to `yarn install`, since `--check-files` is not a valid flag under Yarn berry and was breaking `bin/setup` (and therefore CI).
+- `trek:install` now adds a `!/.env.example` exception to `.gitignore` so the generated `.env.example` template stays tracked (Rails ignores all `/.env*` files by default).
+- `trek:install:postmark` now matches the production.rb SMTP comment with or without the `bin/` prefix, so the Postmark config is injected on Rails 8.0 as well as 8.1 (previously the injection silently did nothing when the anchor did not match).
+
 ## [0.0.1] - 2023-01-24
 
 - Initial release

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    trek (0.1.24)
+    trek (0.1.25)
       action_policy (~> 0.6)
       actioncable
       acts_as_list (~> 1.1)
@@ -161,7 +161,7 @@ GEM
     concurrent-ruby (1.3.7)
     connection_pool (3.0.2)
     content_disposition (1.0.0)
-    crass (1.0.6)
+    crass (1.0.7)
     css_parser (3.0.0)
       addressable
       ssrf_filter (~> 1.5)
@@ -516,7 +516,7 @@ GEM
       zeitwerk (>= 2.7)
     xpath (3.2.0)
       nokogiri (~> 1.8)
-    yard (0.9.43)
+    yard (0.9.44)
     zeitwerk (2.7.5)
 
 PLATFORMS

data/Makefile

@@ -5,6 +5,7 @@ release:
 	if [ -z "$$version" ]; then echo "Version cannot be empty"; exit 1; fi; \
 	sed -i '' "s/VERSION = \".*\"/VERSION = \"$$version\"/" lib/trek/version.rb; \
 	sed -i '' "s/\"version\": \".*\"/\"version\": \"$$version\"/" package.json; \
+	awk -v v="$$version" -v d="$$(date +%F)" '!done && /^## \[Unreleased\]/ {print; print ""; print "## [" v "] - " d; done=1; next} {print}' CHANGELOG.md > CHANGELOG.md.tmp && mv CHANGELOG.md.tmp CHANGELOG.md; \
 	bundle; \
 	git add -A; \
 	git commit -m "Version $$version"; \

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Trek
+  module Filters
+    extend ActiveSupport::Concern
+
+    # Raised when a controller includes Trek::Filters but its #index never
+    # calls apply_filters! — to teach the developer to wire up filtering.
+    class NotAppliedError < StandardError
+      DEFAULT_MESSAGE = <<~MSG.squish
+        Trek::Filters is included but #index never called `apply_filters!`.
+        Add `apply_filters!` to your index action (or `@objects = apply_filters(@objects, params[:filters])`).
+        See https://trek.etamin.studio/reference/controllers#mixins
+      MSG
+
+      def initialize(message = DEFAULT_MESSAGE) = super
+    end
+
+    included do
+      # rubocop:disable Rails/LexicallyScopedActionFilter
+      after_action :ensure_filters_applied, only: :index
+      # rubocop:enable Rails/LexicallyScopedActionFilter
+    end
+
+    def apply_filters(scope, filters)
+      return scope if filters.blank?
+
+      filters.each do |filter, value|
+        next if value.blank?
+        value = nil if value == "nil"
+
+        scope = scope.where(filter => value)
+      end
+
+      scope
+    end
+
+    def apply_filters!
+      @filters_applied = true
+      @objects = apply_filters(@objects, params[:filters])
+    end
+
+    private
+
+    def ensure_filters_applied
+      return if @filters_applied
+      return if Rails.env.production?
+
+      raise NotAppliedError
+    end
+  end
+end

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

@@ -4,6 +4,18 @@ module Trek
   module Scopes
     extend ActiveSupport::Concern
 
+    # Raised when a controller includes Trek::Scopes but its #index never
+    # calls apply_scopes! — to teach the developer to wire up scoping.
+    class NotAppliedError < StandardError
+      DEFAULT_MESSAGE = <<~MSG.squish
+        Trek::Scopes is included but #index never called `apply_scopes!`.
+        Add `apply_scopes!` to your index action.
+        See https://trek.etamin.studio/reference/controllers#mixins
+      MSG
+
+      def initialize(message = DEFAULT_MESSAGE) = super
+    end
+
     def apply_scopes(scope, filters)
       return scope if filters.blank?
 
@@ -17,12 +29,17 @@ module Trek
     end
 
     def apply_scopes!
+      @scopes_applied = true
       @unscoped_objects = @objects
       @objects = apply_scopes(@objects, params[:scopes])
       scope_counts
     end
 
     included do
+      # rubocop:disable Rails/LexicallyScopedActionFilter
+      after_action :ensure_scopes_applied, only: :index
+      # rubocop:enable Rails/LexicallyScopedActionFilter
+
       helper_method :available_scopes
       helper_method :scope_params
       helper_method :unscoped_objects
@@ -51,5 +68,12 @@ module Trek
     def scope_params
       params[:scopes]&.permit(*available_scopes)
     end
+
+    private def ensure_scopes_applied
+      return if @scopes_applied
+      return if Rails.env.production?
+
+      raise NotAppliedError
+    end
   end
 end

data/app/models/concerns/trek/users/invitable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Trek
   module Users
     module Invitable

data/config/locales/trek.fr.yml

@@ -143,6 +143,9 @@ fr:
           success: Action ajoutée
         form:
           title: Action
+    passwords_mailer:
+      reset:
+        subject: Nouveau mot de passe
     search_component:
       search: Rechercher
       search_user: Rechercher un utilisateur par e-mail
@@ -252,9 +255,6 @@ fr:
   admin_mailer:
     invite:
       subject: Votre invitation
-  passwords_mailer:
-    reset:
-      subject: Nouveau mot de passe
   notices:
     authentication_needed: Veuillez vous connecter
     rate_limited: Trop de tentatives, veuillez réessayer plus tard

data/docs/reference/controllers.md

@@ -21,3 +21,75 @@ end
 
 - `include Trek::Pagination` — paginates the index with Kaminari
 - `include Trek::Search` — filters the index by `params[:search]` when the model is [Searchable](/reference/concerns/searchable)
+- `include Trek::Filters` — filters the index by attribute equality (`where(column => value)`) from `params[:filters]`
+- `include Trek::Scopes` — filters the index by **named scopes** from `params[:scopes]`
+
+### Filters
+
+`Trek::Filters` lets users narrow an index by attribute values. Call `apply_filters!` in your `index` action — it
+rewrites `@objects` from `params[:filters]`, applying a `where(column => value)` per non-blank filter (a value of
+`"nil"` matches `NULL`):
+
+```ruby
+module Admin
+  class CitiesController < Trek::ResourceController
+    include Trek::Filters
+
+    helper_method :countries
+
+    def index
+      super
+      apply_filters!
+    end
+
+    private
+
+    def countries
+      City.distinct.pluck(:country_code).index_with { |code| I18n.t("countries.#{code}") }
+    end
+  end
+end
+```
+
+Render the choices with a [`ButtonGroupComponent`](/reference/components), each button linking back to the index
+with the chosen filter:
+
+```slim
+= render Trek::ButtonGroupComponent.new do |g|
+  - g.with_button text: t("admin.actions.all"), \
+      href: [:admin, model], active: params.dig(:filters, :country_code).nil?
+  - countries.each do |code, name|
+    - g.with_button text: name, \
+        href: polymorphic_path([:admin, model], filters: { country_code: code }), \
+        active: code == params.dig(:filters, :country_code)
+```
+
+> If a controller includes `Trek::Filters` but its `index` never calls `apply_filters!`, an
+> `after_action` raises `Trek::Filters::NotAppliedError` (outside production) to flag the missing wiring.
+
+### Scopes
+
+`Trek::Scopes` filters by **named model scopes** rather than raw attributes. Declare the allowed scopes via
+`available_scopes`, then call `apply_scopes!` in your `index`. It also exposes `scope_counts` and
+`unscoped_objects` helpers (the per-scope match counts and the pre-scope collection) for building scope tabs:
+
+```ruby
+module Admin
+  class ArticlesController < Trek::ResourceController
+    include Trek::Scopes
+
+    def index
+      super
+      apply_scopes!
+    end
+
+    private
+
+    def available_scopes
+      %i[published draft]
+    end
+  end
+end
+```
+
+Like `Trek::Filters`, forgetting to call `apply_scopes!` raises `Trek::Scopes::NotAppliedError` outside production.

data/lib/generators/trek/helpers.rb

@@ -63,6 +63,21 @@ module Trek
       def install_npm_dependencies(dependencies, dev: false)
         run "yarn add #{dependencies.map { |name, version| "#{name}@#{version}" }.join(" ")} #{dev ? "--dev" : ""}", abort_on_failure: true
       end
+
+      # Run "bundle install" outside the parent process's bundler environment.
+      # The generators run under `bundle exec`, so the child `bundle` process
+      # would otherwise auto-load `bundler/setup` against the Gemfile we just
+      # modified and raise GemNotFound for the not-yet-installed gem.
+      #
+      # We use with_original_env (not with_unbundled_env): both restore the
+      # pre-`bundle exec` environment, but with_unbundled_env also scrubs every
+      # BUNDLE_* var, which drops the credentials (e.g. BUNDLE_GIT__ETAMINSTUD__IO)
+      # needed to fetch trek itself from its private git source.
+      def bundle_install
+        Bundler.with_original_env do
+          run "bundle install --quiet", abort_on_failure: true
+        end
+      end
     end
   end
 end

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

@@ -0,0 +1,26 @@
+require "rails/generators/actions"
+require "generators/trek/helpers"
+
+module Trek
+  module Generators
+    module Install
+      class AgentsGenerator < Rails::Generators::Base
+        include Trek::Generators::Helpers
+
+        desc "Create AGENTS.md and CLAUDE.md guidance files for AI coding agents."
+
+        source_root File.expand_path("../templates", __dir__)
+
+        def create_agents_md
+          copy_file "AGENTS.md", "AGENTS.md"
+        end
+
+        # CLAUDE.md imports AGENTS.md so Claude Code (which reads CLAUDE.md) and
+        # other agents (which read AGENTS.md) share a single source of truth.
+        def create_claude_md
+          create_file "CLAUDE.md", "See @AGENTS.md\n"
+        end
+      end
+    end
+  end
+end

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

@@ -13,13 +13,15 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
+          install_needed = %w[aws-sdk-s3 blurhash fastimage image_processing shrine shrine-blurhash].any? { |name| !in_gemfile?(name) }
+
           gem "aws-sdk-s3", "~> 1.117" unless in_gemfile?("aws-sdk-s3")
           gem "blurhash", "~> 0.1.7" unless in_gemfile?("blurhash")
           gem "fastimage", "~> 2.2" unless in_gemfile?("fastimage")
           gem "image_processing", "~> 1.8" unless in_gemfile?("image_processing")
           gem "shrine", "~> 3.0" unless in_gemfile?("shrine")
           gem "shrine-blurhash", "~> 0.2.0" unless in_gemfile?("shrine-blurhash")
-          run "bundle install --quiet", abort_on_failure: true
+          bundle_install if install_needed
         end
 
         def add_initializer

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

@@ -16,8 +16,10 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_bcrypt_gem
-          gem "bcrypt", "~> 3.1.7" unless in_gemfile?("bcrypt")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("bcrypt")
+
+          gem "bcrypt", "~> 3.1.7"
+          bundle_install
         end
 
         def copy_admin_authentication_concern
@@ -66,10 +68,16 @@ module Trek
   has_secure_password
   has_many :user_sessions, dependent: :destroy
 
+  # Both tokens invalidate once the password changes (password_salt). Invites
+  # get a longer window than a password reset, so they are a distinct purpose.
   generates_token_for :password_reset, expires_in: 15.minutes do
     password_salt&.last(10)
   end
 
+  generates_token_for :invite, expires_in: 1.week do
+    password_salt&.last(10)
+  end
+
   scope :privileged, -> { where(role: Trek::Users::Roles::PRIVILEGED_ROLES) }
 
           RUBY

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

@@ -13,8 +13,10 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
-          gem "action_policy" unless in_gemfile?("action_policy")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("action_policy")
+
+          gem "action_policy"
+          bundle_install
         end
 
         def run_install

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

@@ -12,8 +12,10 @@ module Trek
         source_root File.expand_path("../../../../", __dir__)
 
         def add_gem
-          gem "brakeman", group: [:development, :test] unless in_gemfile?("brakeman")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("brakeman")
+
+          gem "brakeman", group: [:development, :test]
+          bundle_install
         end
       end
     end

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

@@ -12,8 +12,10 @@ module Trek
         source_root File.expand_path("../../../../", __dir__)
 
         def add_gem
-          gem "bundler-audit", group: [:development, :test] unless in_gemfile?("bundler-audit")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("bundler-audit")
+
+          gem "bundler-audit", group: [:development, :test]
+          bundle_install
         end
       end
     end

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

@@ -22,6 +22,10 @@ module Trek
               Rails.application.routes.default_url_options[:protocol] = Rails.application.config.force_ssl ? "https" : "http"
               Rails.application.routes.default_url_options[:host] = ENV.fetch("DEFAULT_HOSTNAME", "localhost:3000")
               Rails.application.config.canonical_url = "\#{Rails.application.routes.default_url_options[:protocol]}://\#{Rails.application.routes.default_url_options[:host]}"
+
+              # 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?
             RUBY
           end
         end

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

@@ -12,8 +12,10 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
-          gem "rails-healthcheck" unless in_gemfile?("rails-healthcheck")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("rails-healthcheck")
+
+          gem "rails-healthcheck"
+          bundle_install
         end
 
         def add_initializer

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

@@ -10,8 +10,10 @@ module Trek
         desc "Install Kaminari."
 
         def add_gem
-          gem "kaminari" unless in_gemfile?("kaminari")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("kaminari")
+
+          gem "kaminari"
+          bundle_install
         end
       end
     end

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

@@ -13,11 +13,13 @@ module Trek
         source_root File.expand_path("../../../../", __dir__)
 
         def add_gem
+          install_needed = %w[lookbook listen actioncable].any? { |name| !in_gemfile?(name) }
+
           gem "lookbook", ">= 2.3.13", group: :development unless in_gemfile?("lookbook")
           gem "listen", group: :development unless in_gemfile?("listen")
           gem "actioncable", group: :development unless in_gemfile?("actioncable")
 
-          run "bundle install --quiet", abort_on_failure: true
+          bundle_install if install_needed
         end
       end
     end

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

@@ -55,8 +55,10 @@ module Trek
         end
 
         def install_closure_tree
-          gem "closure_tree", "~> 9.0" unless in_gemfile?("closure_tree")
-          run "bundle install --quiet", abort_on_failure: true
+          unless in_gemfile?("closure_tree")
+            gem "closure_tree", "~> 9.0"
+            bundle_install
+          end
           rails_command "db:migrate" # `pages` table must exist
           generate "closure_tree:migration Page"
         end

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

@@ -13,8 +13,10 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
-          gem "postmark-rails" unless in_gemfile?("postmark-rails")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("postmark-rails")
+
+          gem "postmark-rails"
+          bundle_install
         end
 
         def inject_postmark_to_application_mailer
@@ -28,7 +30,7 @@ module Trek
         def inject_postmark_to_config
           inject_into_file "config/environments/production.rb",
             config_injection,
-            after: "# Specify outgoing SMTP server. Remember to add smtp/* credentials via bin/rails credentials:edit.\n"
+            after: %r{# Specify outgoing SMTP server\. Remember to add smtp/\* credentials via (?:bin/)?rails credentials:edit\.\n}
           run "rubocop --autocorrect config/environments/production.rb", abort_on_failure: true
         end
 

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

@@ -12,8 +12,10 @@ module Trek
         source_root File.expand_path("../../../../", __dir__)
 
         def add_gem
-          gem "rubocop-rspec", group: [:development, :test], require: false unless in_gemfile?("rubocop-rspec")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("rubocop-rspec")
+
+          gem "rubocop-rspec", group: [:development, :test], require: false
+          bundle_install
         end
 
         def copy_rubocop_config

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

@@ -21,8 +21,9 @@ module Trek
         def create_aptfile
           create_file "Aptfile" do
             <<~TEXT
-              libwebp-dev
+              libjemalloc2
               libvips-tools --no-install-recommends
+              libwebp-dev
             TEXT
           end
         end

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

@@ -12,8 +12,10 @@ module Trek
         source_root File.expand_path("../../../../", __dir__)
 
         def add_gem
-          gem "slim_lint", group: [:development, :test] unless in_gemfile?("slim_lint")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("slim_lint")
+
+          gem "slim_lint", group: [:development, :test]
+          bundle_install
         end
 
         def copy_slim_lint_config

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

@@ -13,13 +13,14 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gems
+          install_needed = %w[rspec-rails capybara rspec_junit_formatter rspec-html-matchers simplecov].any? { |name| !in_gemfile?(name) }
+
           gem "rspec-rails", "~> 8.0", group: [:development, :test] unless in_gemfile?("rspec-rails")
           gem "capybara", "~> 3.38", group: [:test] unless in_gemfile?("capybara")
           gem "rspec_junit_formatter", "~> 0.6.0", group: [:test] unless in_gemfile?("rspec_junit_formatter")
           gem "rspec-html-matchers", "~> 0.10.0", group: [:test] unless in_gemfile?("rspec-html-matchers")
           gem "simplecov", "~> 0.22.0", group: [:test] unless in_gemfile?("simplecov")
-
-          run "bundle install --quiet", abort_on_failure: true
+          bundle_install if install_needed
         end
 
         def run_install

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

@@ -12,8 +12,10 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
-          gem "strip_attributes" unless in_gemfile?("strip_attributes")
-          run "bundle install --quiet", abort_on_failure: true
+          return if in_gemfile?("strip_attributes")
+
+          gem "strip_attributes"
+          bundle_install
         end
       end
     end

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

@@ -13,11 +13,13 @@ module Trek
         source_root File.expand_path("../templates", __dir__)
 
         def add_gem
+          install_needed = %w[rails-i18n i18n-tasks deepl-rb mobility].any? { |name| !in_gemfile?(name) }
+
           gem "rails-i18n", ">= 6.0.0" unless in_gemfile?("rails-i18n")
           gem "i18n-tasks", "~> 1.0" unless in_gemfile?("i18n-tasks")
           gem "deepl-rb", "~> 3.0" unless in_gemfile?("deepl-rb")
           gem "mobility", "~> 1.3.2" unless in_gemfile?("mobility")
-          run "bundle install --quiet", abort_on_failure: true
+          bundle_install if install_needed
         end
 
         def run_install

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

@@ -45,6 +45,14 @@ module Trek
           run "yarn plugin import interactive-tools"
         end
 
+        # The default bin/setup (generated by `rails new -j esbuild`) runs
+        # `yarn install --check-files`, but `--check-files` is not a valid flag
+        # under Yarn berry (the version we pin above), so it breaks `bin/setup`
+        # in CI. Drop the flag.
+        def fix_bin_setup
+          gsub_file "bin/setup", "yarn install --check-files", "yarn install"
+        end
+
         private
 
         def yarnrc_content

data/lib/generators/trek/install_generator.rb

@@ -52,6 +52,9 @@ module Trek
           <<~GITIGNORE
 
             .DS_Store
+
+            # Keep the .env template tracked (Rails ignores all /.env* files).
+            !/.env.example
           GITIGNORE
       end
 
@@ -121,6 +124,10 @@ module Trek
         generate "trek:install:readme"
       end
 
+      def install_agents
+        generate "trek:install:agents"
+      end
+
       def install_admin
         generate "trek:install:admin"
         generate "trek:install:admin:routes"

data/lib/generators/trek/templates/.gitlab-ci.yml

@@ -3,7 +3,7 @@
 
 # Variables
 variables:
-  POSTGRES_DB: "project_test"
+  POSTGRES_DB: "<%= application_name %>_test"
   POSTGRES_HOST_AUTH_METHOD: "trust"
   DATABASE_URL: "postgresql://postgres:postgres@postgres:5432/$POSTGRES_DB"
   RAILS_ENV: "test"

data/lib/generators/trek/templates/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## About this project
+
+This is a Ruby on Rails application whose back-office/admin is built with **Trek**, a Rails CMS engine. Trek was installed via `rails g trek:install` and provides the admin UI, authentication, authorization, attachments, and base content models. Project-specific work lives in `app/` — admin controllers under `app/controllers/admin/`, plus your own models, policies, and components. Prefer Trek's generators (`rails g trek:scaffold`, `rails g trek:admin:user`, …) over hand-writing admin plumbing.
+
+## Commands
+
+    make setup    # install dependencies (yarn + bin/setup)
+    make dev      # start the server (overmind)
+    make admin    # create an admin user
+    make seed     # seed the database
+    make test     # run the RSpec suite (alias: make spec)
+    make lint     # rubocop + slim-lint + eslint + stylelint + prettier
+    make fix      # auto-correct lint/format issues
+    make scan     # brakeman + bundle-audit
+
+## Conventions
+
+- **Ruby**: RuboCop with rubocop-rails-omakase — double-quoted strings, 120-col lines.
+- **Views**: Slim templates + ViewComponents (linted with slim-lint).
+- **Assets**: esbuild + PostCSS; Stimulus/Turbo (Hotwired).
+- **i18n**: keep every locale file in `config/locales/` in sync across languages.
+- **Git hooks**: lefthook auto-formats staged files on pre-commit — let it run.
+
+## Upgrading Trek
+
+**Whenever you bump the `trek` gem — and its companion `@etaminstudio/trek` npm package — always:**
+
+1. **Read Trek's `CHANGELOG.md`** for every version between the installed and target version, not just the latest.
+2. **Apply every "Upgrade note".** These are the manual steps host apps must perform (config tweaks, new initializers, regenerated files, data migrations). Do not skip them — the upgrade is not complete until each is applied.
+3. **Remove now-redundant local code.** Where the changelog says a Trek change lets host apps drop or simplify a local patch, monkey-patch, or custom implementation, delete that code as part of the upgrade.
+4. **Keep versions aligned**: the `trek` gem version and the `@etaminstudio/trek` npm version must match.
+5. **Verify**: run `make lint` and `make test` before committing the upgrade.

data/lib/generators/trek/templates/controllers/admin/user_password_resets_controller.rb

@@ -42,8 +42,11 @@ module Admin
       @token = params[:token]
     end
 
+    # The same edit/update flow is reached from a password-reset email and from
+    # an invitation email, which carry different token purposes (and expiries).
     def set_user_by_token
-      @user = User.privileged.find_by_token_for!(:password_reset, @token)
+      @user = User.privileged.find_by_token_for(:invite, @token) ||
+        User.privileged.find_by_token_for!(:password_reset, @token)
     rescue ActiveRecord::RecordNotFound
       redirect_to new_admin_user_session_path, alert: t("admin.user_password_resets.not_found")
     rescue ActiveSupport::MessageVerifier::InvalidSignature

data/lib/generators/trek/templates/controllers/admin/users_controller.rb

@@ -5,6 +5,13 @@ module Admin
       @object.role = "editor"
     end
 
+    # The form never collects a password — created users set their own through
+    # the invite/reset email — so seed a random one to satisfy
+    # has_secure_password and the non-null password_digest column.
+    def create_hook
+      @object.password = SecureRandom.alphanumeric(24) if @object.password.blank?
+    end
+
     def theme
       value = params[:theme].to_s
       Current.user.update!(theme: value) if User.themes.key?(value)

data/lib/generators/trek/templates/mailers/admin/passwords_mailer.rb

@@ -4,7 +4,7 @@ class Admin::PasswordsMailer < ApplicationMailer
   def reset(user)
     @user = user
     @url = edit_admin_user_password_reset_url(@user.generate_token_for(:password_reset))
-    @expiration_delay = distance_of_time_in_words(0, 15.minutes)
+    @expiration_delay = distance_of_time_in_words(0, User.token_definitions[:password_reset].expires_in)
 
     I18n.with_locale(@user.locale || I18n.default_locale) do
       mail to: @user.email

data/lib/generators/trek/templates/mailers/admin_mailer.rb

@@ -1,7 +1,10 @@
 class AdminMailer < ApplicationMailer
+  include ActionView::Helpers::DateHelper
+
   def invite(user)
     @user = user
-    @url = edit_admin_user_password_reset_url(@user.generate_token_for(:password_reset))
+    @url = edit_admin_user_password_reset_url(@user.generate_token_for(:invite))
+    @expiration_delay = distance_of_time_in_words(0, User.token_definitions[:invite].expires_in)
 
     I18n.with_locale(@user.locale || I18n.default_locale) do
       mail to: @user.email

data/lib/generators/trek/templates/views/admin/dashboards/index.html.slim

@@ -25,5 +25,6 @@
       text: i18n_resource_label(:search, User).sub(" ", "\n"),
       icon: "trek/search",
       color: "purple",
-      href: "#", # %i[admin users],
+      href: %i[admin users],
+      allowed_to: allowed_to?(:index?, User),
     )

data/lib/generators/trek/templates/views/admin_mailer/invite.en.html.slim

@@ -4,5 +4,6 @@ p = link_to "Choose your password",
       @url,
       target: "_blank",
       rel: "noopener"
+p This link will expire in #{@expiration_delay}.
 p Have a great day!
 p The #{t("application_name")} team

data/lib/generators/trek/templates/views/admin_mailer/invite.en.text.erb

@@ -5,5 +5,7 @@ You have been invited to <%%= t("application_name") %>.
 To choose your password, just follow this link:
 <%%= @url %>
 
+This link will expire in <%%= @expiration_delay %>.
+
 Have a great day!
 The <%%= t("application_name") %> team

data/lib/generators/trek/templates/views/admin_mailer/invite.fr.html.slim

@@ -4,5 +4,6 @@ p = link_to "Choisir votre mot de passe",
       @url,
       target: "_blank",
       rel: "noopener"
+p Ce lien expire dans #{@expiration_delay}.
 p Bonne journée !
 p L'équipe #{t("application_name")}

data/lib/generators/trek/templates/views/admin_mailer/invite.fr.text.erb

@@ -5,5 +5,7 @@ Vous avez été invité·e sur <%%= t("application_name") %>.
 Pour choisir votre mot de passe, suivez ce lien :
 <%%= @url %>
 
+Ce lien expire dans <%%= @expiration_delay %>.
+
 Bonne journée !
 L'équipe <%%= t("application_name") %>

data/lib/trek/version.rb

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

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etaminstudio/trek",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "A modern CMS for Ruby on Rails",
   "main": "app/javascript/trek.js",
   "repository": {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trek
 version: !ruby/object:Gem::Version
-  version: 0.1.24
+  version: 0.1.25
 platform: ruby
 authors:
 - Mohamed Bengrich
@@ -441,7 +441,9 @@ files:
 - ".yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs"
 - ".yarn/releases/yarn-3.8.0.cjs"
 - ".yarnrc.yml"
+- AGENTS.md
 - CHANGELOG.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -635,6 +637,7 @@ files:
 - app/components/trek/toaster_component/toaster_component.js
 - app/controllers/concerns/trek/authentication.rb
 - app/controllers/concerns/trek/authorization.rb
+- app/controllers/concerns/trek/filters.rb
 - app/controllers/concerns/trek/hooks.rb
 - app/controllers/concerns/trek/localization.rb
 - app/controllers/concerns/trek/model.rb
@@ -786,6 +789,7 @@ files:
 - lib/generators/trek/install/admin/user_sessions_generator.rb
 - lib/generators/trek/install/admin/users_generator.rb
 - lib/generators/trek/install/admin_generator.rb
+- lib/generators/trek/install/agents_generator.rb
 - lib/generators/trek/install/application_generator.rb
 - lib/generators/trek/install/assets_generator.rb
 - lib/generators/trek/install/attachments_generator.rb
@@ -832,6 +836,7 @@ files:
 - lib/generators/trek/scaffold_generator.rb
 - lib/generators/trek/taxonomies_generator.rb
 - lib/generators/trek/templates/.gitlab-ci.yml
+- lib/generators/trek/templates/AGENTS.md
 - lib/generators/trek/templates/Makefile
 - lib/generators/trek/templates/README.md
 - lib/generators/trek/templates/components/index.js