seams 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '080facbda9aa03ebeec4885f3745dd0c100d698465dcfcd7bbf35c62dd634eff'
-  data.tar.gz: d9a6b438e0ff12c37ba4006e680a7d01f30358c1bb351cdf2e47fee9110f13be
+  metadata.gz: 3ef90aa737b9e8b791771fc08707df790b8a9b870b448cedc4a52824282881c9
+  data.tar.gz: caf6906f698570313cb0b22b90fa93cd917ea11de1e1ff05660a330149997e4d
 SHA512:
-  metadata.gz: 1e607f46a0b749397ad5b7f7a8a1927dcd267ca14dbf77107c938269bd17c17d426ac38b98f88ba734c7d7a27adceb150973fa331e2d1b302515102b96afdccd
-  data.tar.gz: b708e636f64a8502215b811102640df371ed57846ecd54a44dbd8ea0391f84848f4f42350b3111ddab113eb96a19a75d529f19c45b8a0726b7e6e0cd4c62b9cd
+  metadata.gz: b0193a281248bec66c49e53f3e34a9b278854f056cb63ad4174520b7973a826d3468e8317881b53eba28733f0090f33904372996d2adcb3e526c226d5cadc8a5
+  data.tar.gz: bc365fb8bffac2bb41cbc295fd8ebece8b10d998cef1135957eaba27a846bbcbfd138236c05297f6e308eeb359ad0b4ba323ad05b6fb7609315534b7c088cee7

data/CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] — 2026-09-28
+
+### Added
+
+- Docs: [Setting up the admin area](doc/how-to/SETTING_UP_ADMIN.md), a
+  step-by-step guide covering installation, the staff flag, tenant mode,
+  `before_admin_action`, ejecting, and adding your own dashboards. Every
+  step was checked in a generated app.
+- Docs: the Deploying guide covers Rails 8's four production databases
+  (`CACHE_/QUEUE_/CABLE_DATABASE_URL`) and the Active Record encryption
+  keys the auth engine needs. The generated Kamal `deploy.yml` lists the
+  three extra database URLs.
+
+### Fixed
+
+- Admin engine: an app without every canonical engine (for example only
+  `core` and `auth`) got a 500 on every admin page, because the
+  navigation loaded dashboards whose models don't exist. Those
+  dashboards are now hidden and their URLs return 404.
+- Design generator: the next-steps message now marks
+  `bin/rails tailwindcss:build` as required and names the error you get
+  without it.
+- Admin README: the "add your own dashboard" recipe now includes
+  `self.model`, the policies, the leading-slash route, and deleting
+  Administrate's generated host controller. It no longer claims
+  `theme_css_path` restyles the admin, since that setting is not
+  applied yet.
+- Docs: the onboarding path now works when followed literally. Both
+  tutorials and the README quick start were re-run in fresh apps from
+  the published gem. The 10-minute tutorial claimed SQLite works (the
+  migrations use `jsonb` and fail), sent readers to a nonexistent
+  `/auth/sign_up`, and had them add mount lines the generators already
+  write. All onboarding docs now cover PostgreSQL, `bundle install`
+  after each generator, `bin/rails db:encryption:init` (without it,
+  sign-up raises `Missing Active Record encryption credential`), and
+  `bin/rails tailwindcss:build` after `design --shell`. The Engine
+  Catalogue's wiring example now matches what the generators write.
+  Docs links point at davidslv.uk/seams.
+
 ## [0.2.0] — 2026-09-27
 
 > [!WARNING]

data/README.md

@@ -2,7 +2,7 @@
 
 [![Gem Version](https://img.shields.io/gem/v/seams.svg)](https://rubygems.org/gems/seams)
 [![CI](https://github.com/Davidslv/seams/actions/workflows/ci.yml/badge.svg)](https://github.com/Davidslv/seams/actions/workflows/ci.yml)
-[![Docs site](https://img.shields.io/badge/docs-davidslv.github.io%2Fseams-blue.svg)](https://davidslv.github.io/seams/)
+[![Docs site](https://img.shields.io/badge/docs-davidslv.uk%2Fseams-blue.svg)](https://davidslv.uk/seams/)
 [![API docs](https://img.shields.io/badge/api-rubydoc.info-blue.svg)](https://rubydoc.info/gems/seams)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
@@ -13,7 +13,7 @@ You ship one Rails app. Inside it, each feature (auth, accounts, billing, teams,
 Every generated file is plain Rails code in your repo. You can read it, change it, or delete it. Nothing is hidden behind the gem.
 
 > [!NOTE]
-> Seams is the executable companion to the book **[Modular Rails: Architecture for the Long Game](https://davidslv.uk/modular-rails/)**. The full guides live on the **[documentation site](https://davidslv.github.io/seams/)**. [seams-example](https://github.com/Davidslv/seams-example) is a reference host with every engine wired up.
+> Seams is the executable companion to the book **[Modular Rails: Architecture for the Long Game](https://davidslv.uk/modular-rails/)**. The full guides live on the **[documentation site](https://davidslv.uk/seams/)**. [seams-example](https://github.com/Davidslv/seams-example) is a reference host with every engine wired up.
 
 ## Requirements
 
@@ -28,43 +28,55 @@ Every generated file is plain Rails code in your repo. You can read it, change i
 
 ## Installation
 
+Add Seams to your Gemfile:
+
+```ruby
+# Gemfile
+gem "seams", "~> 0.2"
+```
+
 > [!WARNING]
-> **Install from GitHub for now.** The only release on RubyGems is `0.1.0` (May 2026). It requires Ruby 4.0 or newer and predates many fixes, including the admin engine working at all and Ruby 3.3 support. Until a new version is released, point your Gemfile at the repository:
->
-> ```ruby
-> # Gemfile
-> gem "seams", github: "Davidslv/seams"
-> ```
->
-> Once a newer version is on RubyGems, use `gem "seams"` instead.
+> **Use 0.2.0 or newer.** Version `0.1.0` requires Ruby 4.0 and predates many fixes, including the admin engine working and Ruby 3.3 support.
 
 Then install the framework:
 
 ```bash
 bundle install
 bin/rails generate seams:install
+bundle install
 ```
 
-`seams:install` adds the framework files, a CI workflow, and a `bin/seams` command. Every step after this uses `bin/seams`.
+`seams:install` adds the framework files, a CI workflow, a `bin/seams` command, and a few development gems (hence the second `bundle install`). Every step after this uses `bin/seams`.
 
 ## Quick start
 
-Generate the engines you need. The order matters, because later engines build on earlier ones:
+Generate the engines you need. The order matters, because later engines build on earlier ones. Each generator can add gems to your Gemfile, so run `bundle install` after each one, before the next:
 
 ```bash
-bin/seams core            # shared building blocks (always first)
-bin/seams auth            # sign-in, sessions, OAuth, API tokens
-bin/seams accounts        # the tenant (Account) and its members
-bin/seams notifications   # in-app, email, and SMS notifications
-bin/seams billing         # Stripe subscriptions
-bin/seams teams           # optional teams inside an account
-bin/seams design --shell  # UI components and an app layout
+bin/seams core && bundle install            # shared building blocks (always first)
+bin/seams auth && bundle install            # sign-in, sessions, OAuth, API tokens
+bin/seams accounts && bundle install        # the tenant (Account) and its members
+bin/seams notifications && bundle install   # in-app, email, and SMS notifications
+bin/seams billing && bundle install         # Stripe subscriptions
+bin/seams teams && bundle install           # optional teams inside an account
+bin/seams design --shell && bundle install  # UI components and an app layout
+```
 
-bundle install
+Then finish the setup:
+
+```bash
+bin/rails tailwindcss:build     # the design layout loads the compiled CSS
+bin/rails db:encryption:init    # auth encrypts personal data; paste the printed
+bin/rails credentials:edit      #   active_record_encryption block into credentials
 bin/rails db:migrate
-bin/seams list            # show engines, their events, and subscribers
+bin/seams list                  # show engines, their events, and subscribers
 ```
 
+> [!IMPORTANT]
+> Skip the encryption keys and sign-up fails with `Missing Active Record encryption credential`. Skip the Tailwind build and every page using the design layout fails with `The asset 'tailwind.css' was not found`.
+
+Start the app with `bin/rails server`. Sign up at `/auth/registration/new` and sign in at `/auth/session/new`.
+
 > [!TIP]
 > New to Seams? Follow **[Getting Started](doc/tutorials/GETTING_STARTED.md)**. It goes step by step from `bundle install` to a running app.
 
@@ -150,7 +162,7 @@ With these set:
 - Requests for another account's records return 404.
 - A `member` gets a 403.
 
-The generated `engines/admin/README.md` has the full reference.
+Step-by-step guide: [Setting up the admin area](doc/how-to/SETTING_UP_ADMIN.md). The generated `engines/admin/README.md` has the full reference.
 
 </details>
 
@@ -168,7 +180,7 @@ Seams writes code into your app. So updating the gem does not change engines you
 
 ## Documentation
 
-The **[documentation site](https://davidslv.github.io/seams/)** has every guide below, with search. The API reference is on **[rubydoc.info](https://rubydoc.info/gems/seams)**.
+The **[documentation site](https://davidslv.uk/seams/)** has every guide below, with search. The API reference is on **[rubydoc.info](https://rubydoc.info/gems/seams)**.
 
 <details>
 <summary><strong>Start here</strong></summary>
@@ -186,6 +198,7 @@ The **[documentation site](https://davidslv.github.io/seams/)** has every guide
 - [Removing an engine](doc/how-to/REMOVING_AN_ENGINE.md)
 - [Writing an adapter](doc/how-to/WRITING_AN_ADAPTER.md): swap in Mailgun, Twilio, Paddle, and others
 - [Writing follow-up generators](doc/how-to/WRITING_FOLLOW_UP_GENERATORS.md)
+- [Setting up the admin area](doc/how-to/SETTING_UP_ADMIN.md)
 - [Insertion points](doc/reference/INSERTION_POINTS.md) and the [catalogue of markers](doc/reference/INSERTION_POINTS_CATALOGUE.md)
 - [Deploying](doc/how-to/DEPLOYING.md)
 

data/lib/generators/seams/admin/templates/README.md.tt

@@ -136,9 +136,8 @@ Seams::Admin.configure do |c|
   # at request time. See "Two-mode operation" above.
   c.tenancy_scope = :platform
 
-  # 3. theme_css_path — Optional path to a host-supplied CSS file loaded
-  # on top of Administrate's stock styling. nil = use Administrate's
-  # defaults.
+  # 3. theme_css_path — Reserved for a host-supplied CSS file on top of
+  # Administrate's stock styling. Accepted but not applied yet.
   c.theme_css_path = nil
 
   # 4. before_admin_action — Optional callable that runs before every
@@ -192,18 +191,51 @@ bin/seams resolve --eject admin/app/dashboards/admin/identity_dashboard.rb
 # Now edit engines/admin/app/dashboards/admin/identity_dashboard.rb freely.
 ```
 
-For new dashboards covering host-specific models, generate via
-Administrate, then move the result under the `Admin::*` namespace:
-
-```bash
-bin/rails generate administrate:dashboard MyHost::Project
-# Move app/dashboards/my_host/project_dashboard.rb to
-# engines/admin/app/dashboards/admin/project_dashboard.rb
-# Move the controller similarly under app/controllers/admin/.
-# Add `resources :projects, controller: "/admin/projects"` to
-# engines/admin/config/routes.rb (or splice via the
-# admin.routes.after_resources insertion point in a follow-up generator).
-```
+To add a dashboard for one of your own models, e.g. `Project`:
+
+1. **Dashboard:** `engines/admin/app/dashboards/admin/project_dashboard.rb`.
+   Generate a starting point with `bin/rails generate administrate:dashboard Project`,
+   then move it here, rename it to `Admin::ProjectDashboard`, and declare
+   its model. Administrate would otherwise guess `Admin::Project`:
+
+   ```ruby
+   module Admin
+     class ProjectDashboard < Administrate::BaseDashboard
+       def self.model
+         ::Project
+       end
+       # ATTRIBUTE_TYPES, COLLECTION_ATTRIBUTES, ... as generated
+     end
+   end
+   ```
+
+2. **Controller:** `engines/admin/app/controllers/admin/projects_controller.rb`,
+   subclassing the gated base controller. Delete the controller
+   Administrate generated in your app's `app/controllers/admin/`, because
+   it bypasses the gate:
+
+   ```ruby
+   module Admin
+     class ProjectsController < ::Seams::Admin::ApplicationController
+       def resource_class = ::Project
+       def dashboard = (@dashboard ||= ProjectDashboard.new)
+     end
+   end
+   ```
+
+3. **Policies:** `Admin::Platform::ProjectPolicy` and `Admin::Tenant::ProjectPolicy`
+   under `engines/admin/app/policies/admin/{platform,tenant}/`. Subclass the
+   namespace's `ApplicationPolicy`. The controller name picks the policy, and
+   an action with no policy is denied.
+
+4. **Route:** add this to `engines/admin/config/routes.rb`, inside the
+   `scope as: :admin do` block:
+
+   ```ruby
+   resources :projects, controller: "/admin/projects"
+   ```
+
+   The leading slash is required. The sidebar picks the dashboard up automatically.
 
 Administrate's full dashboard / field / controller surface is documented
 at <https://administrate-demo.herokuapp.com/>.
@@ -222,8 +254,9 @@ at <https://administrate-demo.herokuapp.com/>.
 
 - **2FA / IP allow-list for `/admin`.** Not shipped. Wire your own via
   `Seams::Admin.config.before_admin_action`.
-- **Branded UI.** Stock Administrate CSS only in v1. Override via
-  `theme_css_path`.
+- **Branded UI.** Stock Administrate CSS only. `theme_css_path` is
+  accepted but not applied yet. To restyle, override Administrate's
+  views (see Administrate's documentation).
 - **Search beyond Administrate's stock.** Administrate ships a basic
   Ransack-backed search; rich filtering / faceted search is your job.
 - **Batch actions.** Not in Administrate's surface; not shipped here.

data/lib/generators/seams/admin/templates/app/controllers/admin/application_controller.rb.tt

@@ -73,11 +73,21 @@ module Seams
       # declared model so follow-up dashboards are picked up too.
       def self.admin_route_keys_by_model
         admin_routes.map(&:first).uniq.each_with_object({}) do |key, map|
-          dashboard = "Admin::#{key.classify}Dashboard".safe_constantize
-          map[dashboard.model.name] = key if dashboard.respond_to?(:model)
+          model = admin_model_for(key)
+          map[model.name] = key if model
         end
       end
 
+      # The model behind a dashboard route key, or nil when its engine is
+      # not installed (a host with auth but no billing has no
+      # Billing::Plan). Those dashboards are hidden and answer 404.
+      def self.admin_model_for(key)
+        dashboard = "Admin::#{key.classify}Dashboard".safe_constantize
+        dashboard.model if dashboard.respond_to?(:model)
+      rescue NameError
+        nil
+      end
+
       # Accounts::Membership and Teams::Membership both have the route
       # key `memberships` (isolated-engine model naming), so
       # Administrate's polymorphic `[:admin, membership]` calls
@@ -153,6 +163,10 @@ module Seams
       helper_method :seams_admin_tenancy_scope
       helper_method :seams_admin_navigation
 
+      # Runs after the authentication gate, so signed-out visitors are
+      # still redirected to sign-in rather than told what exists.
+      before_action :ensure_admin_model_installed
+
       def seams_admin_tenancy_scope
         ::Seams::Admin.config.tenancy_scope
       end
@@ -219,6 +233,12 @@ module Seams
         t("administrate.controller.#{key}", resource: resource_class.model_name.human)
       end
 
+      def ensure_admin_model_installed
+        return if self.class.admin_model_for(controller_name)
+
+        raise ActionController::RoutingError, "#{controller_name} is not installed in this app"
+      end
+
       def membership_route_key(record)
         MEMBERSHIP_ROUTE_KEYS[record.class.name] || controller_name.singularize
       end
@@ -270,11 +290,11 @@ module Seams
       # an index route that the current user may list.
       def seams_admin_navigation
         self.class.admin_routes.select { |_key, action| action == "index" }.map(&:first).uniq.filter_map do |key|
-          dashboard = "Admin::#{key.classify}Dashboard".safe_constantize
-          next unless dashboard.respond_to?(:model) && authorized_action?(dashboard.model, :index)
+          model = self.class.admin_model_for(key)
+          next unless model && authorized_action?(model, :index)
 
           { key: key,
-            label: dashboard.model.model_name.human(count: 2),
+            label: model.model_name.human(count: 2),
             path: url_for(controller: "/admin/#{key}", action: :index),
             active: key == controller_name }
         end

data/lib/generators/seams/design/design_generator.rb

@@ -620,8 +620,12 @@ module Seams
             1. bundle install
                (picks up tailwindcss-rails, injected into the host Gemfile)
 
-            2. bin/rails tailwindcss:install   (if Tailwind isn't set up yet)
-               then build it:  bin/rails tailwindcss:build
+            2. bin/rails tailwindcss:build   (required)
+               Pages using the layout fail with "The asset 'tailwind.css' was
+               not found" until the CSS is built. Rebuild after style changes,
+               or keep `bin/rails tailwindcss:watch` running.
+               Without --shell, if your layout doesn't load Tailwind yet, run
+               `bin/rails tailwindcss:install` first.
 
             3. Use the components anywhere in the host or another engine's views:
                  <%= ui_button(variant: :primary) { "Save" } %>

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

@@ -37,6 +37,12 @@ env:
   secret:
     - RAILS_MASTER_KEY
     - DATABASE_URL
+    # Rails 8 has separate cache/queue/cable databases; DATABASE_URL only
+    # covers the primary. Point these at the same server with different
+    # database names, or configure them in config/database.yml and drop them.
+    - CACHE_DATABASE_URL
+    - QUEUE_DATABASE_URL
+    - CABLE_DATABASE_URL
     - REDIS_URL
     - STRIPE_SECRET_KEY
     - STRIPE_WEBHOOK_SECRET

data/lib/seams/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Seams
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: seams
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - David Silva