seams 0.1.0 → 0.2.0

data/lib/generators/seams/engine/engine_generator.rb

@@ -23,6 +23,10 @@ module Seams
 
       NAME_PATTERN = /\A[a-z][a-z0-9_]*\z/
 
+      class_option :skip_host_wiring, type: :boolean, default: false,
+                                      desc: "Do not mount the engine or add a host initializer " \
+                                            "(for canonical generators that wire the host themselves)"
+
       def validate_name
         unless NAME_PATTERN.match?(name)
           raise Seams::GeneratorError,
@@ -107,6 +111,8 @@ module Seams
       end
 
       def wire_into_host
+        return if options[:skip_host_wiring]
+
         # Mount the engine into the host's routes (idempotent — skips
         # if the line already exists, so canonical generators that
         # call this and ALSO mount themselves are safe).

data/lib/generators/seams/engine/templates/Gemfile.tt

@@ -12,7 +12,7 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
-  gem "rspec-rails", "~> 7.1"
+  gem "rspec-rails", ">= 7.1", "< 9"
   gem "rubocop",     require: false
   gem "rubocop-rails", require: false
   gem "rubocop-rspec", require: false

data/lib/generators/seams/engine/templates/app/application_controller.rb.tt

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 module <%= module_name %>
+  # Enforces authentication on every action by default. Mount points
+  # that should be reachable while signed out (e.g. password reset,
+  # invitation accept-via-token) must opt out explicitly:
+  #
+  #   skip_before_action :authenticate_identity!, only: %i[accept_form accept]
   class ApplicationController < ::ApplicationController
+    before_action :authenticate_identity!
   end
 end

data/lib/generators/seams/engine/templates/rubocop.yml.tt

@@ -32,16 +32,25 @@ Metrics/MethodLength:
 # host application here so this engine cannot reach into them
 # accidentally. Add concerns the other engines expose (e.g.
 # `Billing::Billable`) to ExposedConcerns to allow `include` calls.
+#
+# Both boundary cops exclude spec/**/*: boundaries are a
+# production-code contract, and integration specs legitimately need to
+# create real sibling records (e.g. `Auth::Identity.create!` in test
+# setup) to exercise cross-engine behaviour.
 Seams/NoCrossEngineModelAccess:
   Enabled: true
   OwnEngine: <%= module_name %>
   OtherEngines: []
   ExposedConcerns: []
+  Exclude:
+    - "spec/**/*"
 
 Seams/NoCrossEngineDependency:
   Enabled: true
   OwnEngine: <%= name %>
   OtherEngines: []
+  Exclude:
+    - "spec/**/*"
 
 Seams/KnownQueueNames:
   Enabled: true

data/lib/generators/seams/install/install_generator.rb

@@ -18,6 +18,23 @@ module Seams
 
       source_root File.expand_path("templates", __dir__)
 
+      # The quality toolchain is installed by DEFAULT — Seams is opinionated and
+      # sets a host up for success from the first CLI run. Opt out per tool with
+      # --no-strong-migrations / --no-lefthook.
+      #
+      # herb is the exception and is OPT-IN: it ships an arm64-darwin-only native
+      # gem with no Linux build, so on a Rails 8 multi-platform lock (which lists
+      # the Linux deploy platforms) `bundle` fails and the host won't boot. A
+      # fresh install booting matters more than a linter being on, so enable it
+      # explicitly with --herb once your lock can resolve it.
+      class_option :herb, type: :boolean, default: false,
+                          desc: "Install herb (HTML+ERB linter) + .herb.yml + CI/hook lint step. " \
+                                "Off by default: herb is arm64-darwin-only and breaks multi-platform locks."
+      class_option :strong_migrations, type: :boolean, default: true,
+                                       desc: "Install strong_migrations + initializer + CI migration-safety step"
+      class_option :lefthook, type: :boolean, default: true,
+                              desc: "Install lefthook + lefthook.yml (pre-commit lint, pre-push specs)"
+
       def create_initializer
         template "seams.rb.tt", "config/initializers/seams.rb"
       end
@@ -129,6 +146,41 @@ module Seams
         File.chmod(0o755, full_path) if File.exist?(full_path)
       end
 
+      # --- Quality toolchain (default on; opt out per tool) -----------------
+
+      def create_herb_config
+        return unless options[:herb]
+
+        template_if_missing "herb.yml.tt", ".herb.yml"
+      end
+
+      def create_strong_migrations_initializer
+        return unless options[:strong_migrations]
+
+        template_if_missing "strong_migrations.rb.tt", "config/initializers/strong_migrations.rb"
+      end
+
+      def create_lefthook_config
+        return unless options[:lefthook]
+
+        template_if_missing "lefthook.yml.tt", "lefthook.yml"
+      end
+
+      def install_quality_gems
+        # The CI workflow (and lefthook) shell out to these, so make sure the
+        # gems are in the host Gemfile. All idempotent — skipped if present.
+        host_inject_gem("rubocop", group: :development)
+        host_inject_gem("brakeman", group: :development)
+        host_inject_gem("bundler-audit", group: :development)
+        host_inject_gem("herb", group: :development) if options[:herb]
+        host_inject_gem("lefthook", group: :development) if options[:lefthook]
+        # strong_migrations is a dev/CI guard — it vets migrations where they're
+        # written and in CI, and is kept OUT of the production path. The
+        # initializer is guarded with `if defined?(StrongMigrations)` so a
+        # production boot (where the gem isn't loaded) is unaffected.
+        host_inject_gem("strong_migrations", group: %i[development test]) if options[:strong_migrations]
+      end
+
       # Phase 1.5 — per-host helper scripts and architecture doc.
       def create_helper_scripts
         template_if_missing "script/collate_coverage.rb.tt",   "script/collate_coverage.rb"
@@ -149,8 +201,9 @@ module Seams
         host_inject_gem("seams", "~> #{Seams::VERSION}")
         # Every Seams host needs rspec-rails so the per-engine
         # spec/dummy specs can actually run. Idempotent — skipped if
-        # the host already has these gems.
-        host_inject_gem("rspec-rails", "~> 7.1", group: :test)
+        # the host already has these gems. The range lets bundler pick
+        # rspec-rails 8.x on Rails 7.2+ and fall back to 7.1.x on Rails 7.1.
+        host_inject_gem("rspec-rails", ">= 7.1", "< 9", group: :test)
       end
 
       private
@@ -166,12 +219,23 @@ module Seams
 
       public
 
-      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength
       def post_install_message
         say ""
         say "  Seams is installed. Generate your first engine with:", :green
         say "    bin/seams core          (or bin/rails generate seams:core)"
         say ""
+        say "  Quality toolchain (installed by default — opt out with --no-<tool>):", :yellow
+        say "    rubocop + brakeman + bundle-audit (in CI)" \
+            "#{", herb (HTML+ERB lint)" if options[:herb]}" \
+            "#{", strong_migrations" if options[:strong_migrations]}"
+        say "    HTML+ERB linting (herb) is opt-in — add --herb (arm64-darwin only).", :yellow unless options[:herb]
+        say "    bundle install   then   bin/rails db:prepare"
+        if options[:lefthook]
+          say "    Activate the git hooks (pre-commit lint, pre-push specs):", :yellow
+          say "    bundle exec lefthook install"
+        end
+        say ""
         say "  Canonical generators (run in this order):", :yellow
         say "    bin/seams core          - Core engine (concerns, audit log)"
         say "    bin/seams auth          - Auth engine (Identity, sessions, OAuth)"
@@ -184,6 +248,9 @@ module Seams
         say "    bin/seams admin         - Admin engine (Administrate-backed dashboards"
         say "                              for the canonical models, Pundit-gated,"
         say "                              audit-log auto-write). Requires auth + accounts."
+        say "    bin/seams design        - Design engine (ui_* component partials,"
+        say "                              Tailwind v4 tokens, Design::FormBuilder)."
+        say "                              Non-isolated: ui_* helpers resolve host-wide."
         say ""
         say "  Follow-up generators (extend an already-installed engine):", :yellow
         say "    bin/rails generate seams:auth:add_oauth_provider <name>"
@@ -201,11 +268,10 @@ module Seams
         say ""
         say "  Recommended order: core -> auth -> accounts -> notifications -> billing -> teams.", :yellow
         say "  Optional: append `admin` last for an Administrate-backed admin surface.", :yellow
-        say "  See doc/CURRENT_ATTRIBUTES.md (after install) for the per-request namespace cascade.", :yellow
-        say "  See doc/WRITING_FOLLOW_UP_GENERATORS.md to write your own follow-up generator.", :yellow
+        say "  See doc/reference/CURRENT_ATTRIBUTES.md (after install) for the per-request namespace cascade.", :yellow
+        say "  See doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md to write your own follow-up generator.", :yellow
         say ""
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
     end
   end
 end

data/lib/generators/seams/install/templates/Dockerfile.tt

@@ -1,12 +1,12 @@
 # Multi-stage Dockerfile tuned for a Seams-powered Rails app.
 #
 # RUBY_VERSION is read from the host's `.ruby-version` at build time
-# (default 4.0.3 — bump when you bump .ruby-version). Override with
+# (default 4.0.7 — bump when you bump .ruby-version). Override with
 # `--build-arg RUBY_VERSION=...` if you need to.
 #
 # This file is compatible with Rails 8's `bin/docker-build`.
 
-ARG RUBY_VERSION=4.0.3
+ARG RUBY_VERSION=4.0.7
 FROM ruby:${RUBY_VERSION}-slim AS base
 
 ENV BUNDLE_PATH="/usr/local/bundle" \

data/lib/generators/seams/install/templates/bin_seams.tt

@@ -5,7 +5,8 @@
 #
 #   bin/seams install                     # bin/rails generate seams:install
 #   bin/seams engine billing              # bin/rails generate seams:engine billing
-#   bin/seams core | auth | accounts | notifications | billing | teams | admin
+#   bin/seams core | auth | accounts | notifications | billing | teams | admin | design
+#   bin/seams permissions                 # bin/rails generate seams:permissions
 #   bin/seams remove billing              # bin/rails generate seams:remove billing
 #   bin/seams list                        # bin/rails seams:list
 #   bin/seams test billing                # bin/rails seams:test[billing]
@@ -16,7 +17,7 @@
 
 require "shellwords"
 
-CANONICAL = %w[install core auth accounts notifications billing teams admin].freeze
+CANONICAL = %w[install core auth accounts notifications billing teams admin design permissions].freeze
 GENERIC   = %w[engine remove].freeze
 TASKS     = %w[list].freeze
 ENGINE_TASKS = %w[test quality].freeze
@@ -69,15 +70,17 @@ when nil, "help", "-h", "--help"
     Canonical generators:
       install                       Install the framework
       engine <name>                 Generate a generic engine
-      core | auth | accounts | notifications | billing | teams | admin
+      core | auth | accounts | notifications | billing | teams | admin | design
                                     Generate a canonical engine
+      permissions                   Generate the host-editable role -> ability
+                                    grant map (config/initializers/seams_permissions.rb)
       remove <name>                 Remove an engine
 
     Follow-up generators (extend an already-installed engine):
       bin/rails generate seams:auth:add_oauth_provider <name>
                                     Add a new OAuth provider adapter
                                     (e.g. linkedin, apple, microsoft)
-      See doc/WRITING_FOLLOW_UP_GENERATORS.md for how to write your own.
+      See doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md for how to write your own.
 
     Diagnostics + escape hatch:
       list                          List engines + their events

data/lib/generators/seams/install/templates/ci.yml.tt

@@ -16,21 +16,25 @@ env:
 
 jobs:
   lint:
-    name: RuboCop
+    name: Lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ".ruby-version"
           bundler-cache: true
       - run: bundle exec rubocop --parallel
+<% if options[:herb] -%>
+      - name: Lint HTML+ERB (herb)
+        run: bundle exec herb lint "**/*.html.erb"
+<% end -%>
 
   security:
     name: Security (brakeman + bundle-audit)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ".ruby-version"
@@ -48,7 +52,7 @@ jobs:
     outputs:
       engines: ${{ steps.set.outputs.engines }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - id: set
         run: |
           if [ -d engines ]; then
@@ -71,7 +75,7 @@ jobs:
         engine: ${{ fromJson(needs.discover.outputs.engines) }}
     services:
       postgres:
-        image: postgres:16
+        image: postgres:18
         env:
           POSTGRES_PASSWORD: postgres
         ports: ["5432:5432"]
@@ -87,7 +91,7 @@ jobs:
       PGUSER:     "postgres"
       PGPASSWORD: "postgres"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ".ruby-version"
@@ -99,7 +103,7 @@ jobs:
     runs-on: ubuntu-latest
     services:
       postgres:
-        image: postgres:16
+        image: postgres:18
         env:
           POSTGRES_PASSWORD: postgres
         ports: ["5432:5432"]
@@ -115,9 +119,15 @@ jobs:
       PGUSER:     "postgres"
       PGPASSWORD: "postgres"
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ".ruby-version"
           bundler-cache: true
+<% if options[:strong_migrations] -%>
+      - name: Migrations are safe (strong_migrations runs every migration from an empty database)
+        env:
+          RAILS_ENV: test
+        run: bundle exec rails db:create db:migrate
+<% end -%>
       - run: bundle exec rspec spec

data/lib/generators/seams/install/templates/deploy.yml.tt

@@ -45,7 +45,7 @@ env:
 # Otherwise delete this block and provide DATABASE_URL via env.secret.
 # accessories:
 #   postgres:
-#     image: postgres:16
+#     image: postgres:18
 #     host: TODO.web.example.com
 #     port: "127.0.0.1:5432:5432"
 #     env:
@@ -55,7 +55,9 @@ env:
 #       secret:
 #         - POSTGRES_PASSWORD
 #     volumes:
-#       - /var/lib/postgresql/data:/var/lib/postgresql/data
+#       # postgres:18+ keeps data under /var/lib/postgresql/<major>/docker,
+#       # so mount the parent directory (not .../data as in 17 and older).
+#       - /var/lib/postgresql:/var/lib/postgresql
 
 asset_path: /rails/public/assets
 

data/lib/generators/seams/install/templates/doc/ARCHITECTURE.md.tt

@@ -1,7 +1,7 @@
 # Architecture (host)
 
 > Generated by `seams:install`. Edit freely — this is YOUR doc, not
-> the gem's. Cross-reference the gem's own `doc/ARCHITECTURE.md` (in
+> the gem's. Cross-reference the gem's own `doc/explanation/ARCHITECTURE.md` (in
 > the seams gem source) for framework-level details.
 
 ## The model

data/lib/generators/seams/install/templates/docker-entrypoint.tt

@@ -18,8 +18,10 @@ set -e
 # Web command is `bundle exec rails server` (or `./bin/rails server`).
 # Workers use `bundle exec rails solid_queue:start` — never run
 # db:prepare from a worker, two containers racing CREATE TABLE breaks.
-case "${1}${2}${3}" in
-  *server*|*"./bin/rails"*"server"*|*"bin/rails"*"server"*)
+# Match `server` as a whole word anywhere in the command: in
+# `bundle exec rails server` it is the 4th argument.
+case " $* " in
+  *" server "*|*" s "*)
     bundle exec rails db:prepare
     ;;
 esac

data/lib/generators/seams/install/templates/herb.yml.tt

@@ -0,0 +1,10 @@
+# Herb config for this Seams host. Herb lints HTML+ERB templates (host views
+# AND generated engine views) for invalid nesting, accessibility, and unsafe
+# raw output. Run with `bundle exec herb lint "**/*.html.erb"`; CI runs it too.
+#
+# Pin the version so a herb upgrade can't enable new rules mid-CI without a
+# deliberate bump. Regenerate the full default with `bundle exec herb-lint --init`.
+#
+# Docs: https://herb-tools.dev/configuration
+
+framework: actionview

data/lib/generators/seams/install/templates/lefthook.yml.tt

@@ -0,0 +1,25 @@
+# Git hooks for this Seams host. Install once with:
+#
+#   bundle exec lefthook install
+#
+# These run the same quality gates as CI, but locally — before a push, so
+# issues surface immediately instead of in CI. Bypass with `git ... --no-verify`.
+
+pre-commit:
+  parallel: true
+  commands:
+    rubocop:
+      glob: "*.rb"
+      # --force-exclusion honours the engines/ exclude in .rubocop.yml even
+      # when files are passed explicitly (engines lint themselves).
+      run: bundle exec rubocop --force-exclusion {staged_files}
+<% if options[:herb] -%>
+    herb:
+      glob: "*.html.erb"
+      run: bundle exec herb lint {staged_files}
+<% end -%>
+
+pre-push:
+  commands:
+    specs:
+      run: bundle exec rspec

data/lib/generators/seams/install/templates/ruby-version.tt

@@ -1 +1 @@
-4.0.3
+4.0.7

data/lib/generators/seams/install/templates/seams.rake.tt

@@ -21,7 +21,12 @@ namespace :seams do
   task :quality, [:engine] => :environment do |_t, args|
     name = args[:engine] or abort("Usage: rake seams:quality[billing]")
     abort("Invalid engine name: #{name.inspect}") unless ENGINE_NAME_PATTERN.match?(name)
-    sh "bundle", "exec", "rubocop", "engines/#{name}"
+    # Run from inside the engine directory with --ignore-parent-exclusion:
+    # the host .rubocop.yml excludes engines/**/* (engines lint
+    # themselves), and RuboCop merges that parent exclusion into any run
+    # unless told not to — `rubocop engines/#{name}` from the host root
+    # inspects zero files and reports a false pass.
+    sh "bundle", "exec", "rubocop", "--ignore-parent-exclusion", chdir: "engines/#{name}"
   end
 
   namespace :test do
@@ -45,6 +50,13 @@ namespace :seams do
   task audit: :environment do
     Rake::Task["environment"].invoke
     sh "bundle", "exec", "rubocop", "--parallel"
+    # Per-engine RuboCop: the host run above excludes engines/**/*, so
+    # each engine with its own .rubocop.yml is linted from inside its
+    # directory (--ignore-parent-exclusion stops the host's exclusion
+    # from turning these runs into 0-file no-ops).
+    Dir["engines/*"].select { |d| File.directory?(d) && File.exist?("#{d}/.rubocop.yml") }.sort.each do |dir|
+      sh "bundle", "exec", "rubocop", "--ignore-parent-exclusion", chdir: dir
+    end
     sh "bundle", "exec", "rspec", "spec"
     Dir["engines/*"].select { |d| File.directory?(d) }.sort.each do |dir|
       next if Dir.glob("#{dir}/spec/**/*_spec.rb").empty?

data/lib/generators/seams/install/templates/strong_migrations.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# strong_migrations rejects unsafe database migrations (lock-heavy ALTERs,
+# non-concurrent indexes, add_column with a volatile default on an existing
+# table, …) before they reach production. It is a development/CI guard — the
+# gem lives in the :development, :test groups and is NOT loaded in production,
+# so this initializer is guarded accordingly. CI runs every migration from an
+# empty database, which is where the checks actually fire.
+return unless defined?(StrongMigrations)
+
+# A fresh host has nothing in production yet, so audit ALL migrations rather
+# than grandfathering them. Once you go live, set this to the latest applied
+# version so a from-scratch migrate doesn't re-check historical migrations.
+StrongMigrations.start_after = 0
+
+# Match your production Postgres major version so the right checks run in
+# development and CI. Uncomment and set:
+# StrongMigrations.target_version = 16
+
+# Safety timeouts. If you use PgBouncer in transaction mode, remove these and
+# set timeouts on the database user instead.
+StrongMigrations.lock_timeout = 10.seconds
+StrongMigrations.statement_timeout = 1.hour
+
+# Refresh planner statistics after an index is added.
+StrongMigrations.auto_analyze = true

data/lib/generators/seams/notifications/notifications_generator.rb

@@ -21,7 +21,7 @@ module Seams
     # reads from.
     #
     # Run with: bin/rails generate seams:notifications
-    # rubocop:disable Metrics/ClassLength
+    # rubocop:disable-next Metrics/ClassLength
     class NotificationsGenerator < Rails::Generators::Base
       include Seams::Generators::HostInjector
       include Seams::Generators::EjectAware
@@ -67,6 +67,8 @@ module Seams
                                 engine_path("lib/notifications/configuration.rb")
         template_unless_ejected "lib/type_registry.rb.tt",
                                 engine_path("lib/notifications/type_registry.rb")
+        template_unless_ejected "lib/preferences.rb.tt",
+                                engine_path("lib/notifications/preferences.rb")
         # lib/notifications.rb stays framework-managed (root require file).
         template "lib/notifications.rb.tt", engine_path("lib/notifications.rb"), force: true
       end
@@ -390,6 +392,5 @@ module Seams
         RB
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/generators/seams/notifications/templates/app/controllers/preferences_controller.rb.tt

@@ -7,15 +7,8 @@ module Notifications
     end
 
     def update
-      # Whitelist the keys we accept. The form posts
-      # `preferences[<channel>:<type>] = "1" | "0"`. Allowed channels
-      # are the canonical CHANNELS list; type is either "any" (→ nil)
-      # or a NotificationPreference::TYPE-style identifier ([a-z0-9_]).
       preference_params.each do |key, enabled|
         channel, type = key.split(":", 2)
-        next unless Notifications::NotificationPreference::CHANNELS.include?(channel)
-        next unless type.nil? || type == "any" || type.match?(/\A[a-z0-9_]+\z/)
-
         type = nil if type == "any"
         pref = Notifications::NotificationPreference.find_or_initialize_by(
           identity_id:       current_identity_id,
@@ -29,13 +22,12 @@ module Notifications
 
     private
 
-    # `params[:preferences].to_h` raises ActionController::UnfilteredParameters
-    # in Rails default config. Use permit! after filtering to the
-    # `:preferences` key — the per-key channel/type validation above
-    # is the real safety net.
+    # Permit only the keys the channel/type registry allows. The closed
+    # list is derived at request time from NotificationPreference::CHANNELS
+    # and Notifications::TypeRegistry, so brakeman sees no mass-assignment
+    # risk and unknown keys are rejected by Rails rather than silently dropped.
     def preference_params
-      raw = params.require(:preferences)
-      raw.respond_to?(:permit!) ? raw.permit!.to_h : raw.to_h
+      params.require(:preferences).permit(*Notifications::Preferences.allowed_keys)
     end
 
     # Resolves the signed-in identity's id from `Auth::Current.identity`

data/lib/generators/seams/notifications/templates/lib/engine.rb.tt

@@ -16,6 +16,18 @@ module Notifications
       # seams:insertion-point notifications.engine.events
     end
 
+    initializer "notifications.register_abilities" do
+      # Ability codes this engine owns, registered exactly like events
+      # (resource.action.engine). `read` is the member-level view;
+      # `manage` is the admin-level mutate. Host grant maps reference
+      # these codes; see Seams::Permissions::DEFAULT_GRANTS.
+      Seams::PermissionRegistry.register("notification.read.notifications",   owned_by: "Notifications")
+      Seams::PermissionRegistry.register("notification.manage.notifications", owned_by: "Notifications")
+      Seams::PermissionRegistry.register("preference.manage.notifications",   owned_by: "Notifications")
+      # Follow-up generators that ship new notifications abilities register them here.
+      # seams:insertion-point notifications.engine.abilities
+    end
+
     initializer "notifications.append_migrations" do |app|
       unless app.root == root
         config.paths["db/migrate"].expanded.each do |expanded_path|

data/lib/generators/seams/notifications/templates/lib/notifications.rb.tt

@@ -3,6 +3,7 @@
 require "notifications/version"
 require "notifications/configuration"
 require "notifications/type_registry"
+require "notifications/preferences"
 require "notifications/engine"
 require "notifications/concerns/notifiable"
 require "notifications/adapters/abstract"

data/lib/generators/seams/notifications/templates/lib/preferences.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Notifications
+  # Channel/type key registry for the preferences surface.
+  #
+  # The preferences form posts flat keys of the form
+  # +<channel>:<type>+ (e.g. +in_app:billing.invoice_paid+) or
+  # +<channel>:any+ for the channel-wide catch-all row. This module
+  # derives the closed set of acceptable keys from:
+  #
+  # * +NotificationPreference::CHANNELS+ — the canonical delivery
+  #   channels compiled into the engine.
+  # * +Notifications::TypeRegistry.names+ — the notification types the
+  #   host has registered (seeded by +Notifications.seed_default_types!+
+  #   and extended via the initializer).
+  #
+  # PreferencesController passes the result to +params.permit(...)+ so
+  # Rails rejects unknown keys without relying on +permit!+.
+  module Preferences
+    module_function
+
+    # Returns every key the preferences form is allowed to post.
+    # Format: +["in_app:any", "in_app:welcome", "email:any", ...]+
+    def allowed_keys
+      channels = Notifications::NotificationPreference::CHANNELS
+      types    = Notifications::TypeRegistry.names
+
+      channels.flat_map do |channel|
+        [
+          "#{channel}:any",
+          *types.map { |type| "#{channel}:#{type}" }
+        ]
+      end
+    end
+  end
+end