seams 0.1.0

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

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "seams/generators/host_injector"
+
+module Seams
+  module Generators
+    # Adds the Seams framework to a host Rails application:
+    #
+    #   - config/initializers/seams.rb        (configure adapters)
+    #   - config/initializers/seams_engines.rb (load engines/* into autoload)
+    #   - engines/.keep                       (where future engines live)
+    #   - lib/tasks/seams.rake                (rake namespace)
+    #
+    # Run with: bin/rails generate seams:install
+    class InstallGenerator < Rails::Generators::Base
+      include Seams::Generators::HostInjector
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "seams.rb.tt", "config/initializers/seams.rb"
+      end
+
+      def create_engines_directory
+        empty_directory "engines"
+        create_file "engines/.keep"
+      end
+
+      def create_rake_tasks
+        template "seams.rake.tt", "lib/tasks/seams.rake"
+      end
+
+      def append_engines_to_eager_load
+        template "seams_engines.rb.tt", "config/seams_engines.rb"
+      end
+
+      def wire_engines_into_application_rb
+        # Each engine under engines/ must be required BEFORE
+        # Rails.application.initialize! so its Railtie registers paths
+        # (db/migrate, app/*) and initializers with the host. The
+        # `require_relative` is injected directly after Bundler.require.
+        application_rb = File.join(destination_root, "config/application.rb")
+        return unless File.exist?(application_rb)
+
+        snippet = %(require_relative "seams_engines")
+        contents = File.read(application_rb)
+        return if contents.include?(snippet)
+
+        # The default Rails 8 application.rb contains
+        # `Bundler.require(*Rails.groups)` verbatim. If a host has
+        # customised it (Rails 4-style asset groups, multi-arg
+        # Bundler.require, brace-form do-block, trailing comment, ...),
+        # the regex misses and Thor silently warns "File unchanged!"
+        # — leaving the host bootable but with engines never required.
+        # That is the worst kind of failure: silent + production-bug.
+        # Print a loud red warning so the user knows to wire it by hand.
+        anchor = /Bundler\.require\(\*Rails\.groups\)\n/
+        unless contents.match?(anchor)
+          say "  WARNING config/application.rb has no `Bundler.require(*Rails.groups)` line — " \
+              "add `#{snippet}` manually after Bundler.require so engines load before initialize!",
+              :red
+          return
+        end
+
+        say "  inject  config/application.rb (require_relative \"seams_engines\")", :green
+        inject_into_file(application_rb, "\n#{snippet}\n", after: anchor)
+      end
+
+      def create_host_rubocop
+        # Three cases:
+        #   1. Host has no .rubocop.yml → write the seams baseline.
+        #   2. Host already has one → don't overwrite, but inject an
+        #      `engines/**/*` Exclude so host RuboCop (which may use
+        #      rubocop-rails-omakase or another flavor) doesn't lint
+        #      engine code under rules written for application code.
+        #      Engines have their own self-contained .rubocop.yml.
+        host_path = File.join(destination_root, ".rubocop.yml")
+        unless File.exist?(host_path)
+          template "rubocop.yml.tt", ".rubocop.yml"
+          return
+        end
+
+        return if File.read(host_path).include?("engines/**/*")
+
+        say "  inject  .rubocop.yml (Exclude engines + seams.rake)", :green
+        append_to_file(host_path, <<~YML)
+
+          # Engines have their own self-contained .rubocop.yml. Linting them
+          # from the host runs gem-style code under whatever flavor of rules
+          # the host uses (omakase / etc.) and produces noisy false positives.
+          # The gem-generated lib/tasks/seams.rake is excluded for the same
+          # reason.
+          AllCops:
+            Exclude:
+              - "engines/**/*"
+              - "lib/tasks/seams.rake"
+        YML
+      end
+
+      def create_ruby_version
+        # The host CI workflow does `ruby-version: ".ruby-version"`, so the
+        # host needs a `.ruby-version` file. Rails 8's `rails new` doesn't
+        # ship one. Don't overwrite if the host has pinned their own.
+        return if File.exist?(File.join(destination_root, ".ruby-version"))
+
+        template "ruby-version.tt", ".ruby-version"
+      end
+
+      def create_ci_workflow
+        template "ci.yml.tt", ".github/workflows/ci.yml"
+      end
+
+      def create_deployment_templates
+        # Skip any file the host already has — Rails 8 ships its own
+        # Dockerfile and bin/docker-entrypoint.
+        template_if_missing "Dockerfile.tt",         "Dockerfile"
+        template_if_missing "docker-entrypoint.tt",  "bin/docker-entrypoint"
+        template_if_missing "Procfile.tt",           "Procfile"
+        template_if_missing "deploy.yml.tt",         "config/deploy.yml"
+
+        full = File.join(destination_root, "bin/docker-entrypoint")
+        File.chmod(0o755, full) if File.exist?(full)
+      end
+
+      def create_bin_seams
+        template "bin_seams.tt", "bin/seams"
+        full_path = File.join(destination_root, "bin/seams")
+        File.chmod(0o755, full_path) if File.exist?(full_path)
+      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"
+        template_if_missing "script/run_affected_tests.sh.tt", "script/run_affected_tests.sh"
+
+        runner = File.join(destination_root, "script/run_affected_tests.sh")
+        File.chmod(0o755, runner) if File.exist?(runner)
+      end
+
+      def create_architecture_doc
+        template_if_missing "doc/ARCHITECTURE.md.tt", "doc/ARCHITECTURE.md"
+      end
+
+      def wire_into_host
+        # Auto-add seams to the host Gemfile if not already present —
+        # covers the `gem install seams` global-install path. Pinned to
+        # a pessimistic 0.x to keep major-version bumps explicit.
+        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)
+      end
+
+      private
+
+      def template_if_missing(source, destination_relative)
+        full = File.join(destination_root, destination_relative)
+        if File.exist?(full)
+          say "  exist   #{destination_relative} (kept)", :blue
+        else
+          template source, destination_relative
+        end
+      end
+
+      public
+
+      # rubocop:disable 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 "  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)"
+        say "    bin/seams accounts      - Accounts engine (tenant + Membership + system actor)"
+        say "    bin/seams notifications - Notifications engine"
+        say "    bin/seams billing       - Billing engine"
+        say "    bin/seams teams         - Teams engine"
+        say ""
+        say "  Optional engines (generate after the canonical six are in place):", :yellow
+        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 ""
+        say "  Follow-up generators (extend an already-installed engine):", :yellow
+        say "    bin/rails generate seams:auth:add_oauth_provider <name>"
+        say "                            - add a new OAuth provider adapter"
+        say "                              (e.g. linkedin, apple, microsoft)"
+        say ""
+        say "  Other useful commands:", :yellow
+        say "    bin/seams list                          - list engines + their events"
+        say "    bin/seams resolve --eject <engine>/<file>"
+        say "                                            - mark a host file as host-owned"
+        say "                                              (skipped on regenerate)"
+        say "    bin/seams resolve --list-markers <engine>"
+        say "                                            - list insertion-point markers"
+        say "    bin/seams resolve --list-ejected        - list every ejected file under engines/"
+        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 ""
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# 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
+# `--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
+FROM ruby:${RUBY_VERSION}-slim AS base
+
+ENV BUNDLE_PATH="/usr/local/bundle" \
+    BUNDLE_WITHOUT="development:test" \
+    BUNDLE_DEPLOYMENT="1" \
+    LANG=C.UTF-8 \
+    RAILS_ENV=production \
+    RAILS_LOG_TO_STDOUT=1
+
+WORKDIR /rails
+
+RUN apt-get update -qq && \
+    apt-get install --no-install-recommends -y \
+      build-essential libpq-dev libyaml-dev nodejs git curl && \
+    rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*
+
+# --- Bundle install layer ----------------------------------------------------
+FROM base AS gems
+
+# Copy the host's Gemfile + gem dependency manifests for the engines.
+# Add new engines by updating the COPY list once.
+COPY Gemfile Gemfile.lock ./
+COPY engines/ ./engines/
+
+RUN bundle install --jobs $(nproc) && \
+    bundle exec bootsnap precompile --gemfile
+
+# --- App layer ---------------------------------------------------------------
+FROM base AS app
+
+COPY --from=gems /usr/local/bundle /usr/local/bundle
+COPY . .
+
+RUN bundle exec bootsnap precompile app/ lib/ engines/ && \
+    SECRET_KEY_BASE_DUMMY=1 bundle exec rails assets:precompile
+
+RUN useradd rails --create-home --shell /bin/bash && \
+    chown -R rails:rails /rails db log storage tmp
+USER rails
+
+EXPOSE 3000
+ENTRYPOINT ["./bin/docker-entrypoint"]
+CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0"]

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

@@ -0,0 +1,14 @@
+# Foreman / Kamal Procfile for a Seams-powered host.
+#
+# The worker process expects Solid Queue tables to already exist.
+# If you haven't installed Solid Queue's migrations yet:
+#
+#   bin/rails solid_queue:install:migrations
+#   bin/rails db:migrate
+#
+# Solid Queue Recurring is also needed if you ship the Notifications
+# engine (it relies on the recurring sweeper). After installing,
+# add the engine's recurring entries to config/recurring.yml — see
+# the engine's README for the schedule.
+web:    bundle exec rails server -p ${PORT:-3000} -b 0.0.0.0
+worker: bundle exec rails solid_queue:start

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Convenience wrapper around the seams:* generators and rake tasks.
+#
+#   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 remove billing              # bin/rails generate seams:remove billing
+#   bin/seams list                        # bin/rails seams:list
+#   bin/seams test billing                # bin/rails seams:test[billing]
+#   bin/seams quality billing             # bin/rails seams:quality[billing]
+#   bin/seams resolve --eject <engine>/<file>
+#   bin/seams resolve --list-markers <engine>
+#   bin/seams resolve --list-ejected
+
+require "shellwords"
+
+CANONICAL = %w[install core auth accounts notifications billing teams admin].freeze
+GENERIC   = %w[engine remove].freeze
+TASKS     = %w[list].freeze
+ENGINE_TASKS = %w[test quality].freeze
+
+# `resolve` runs in-process — it doesn't need bin/rails because it
+# doesn't need the Rails environment. We require seams from the host
+# bundle and dispatch directly. This keeps `bin/seams resolve` fast
+# (~50ms) compared to ~3s for any bin/rails invocation.
+def run_resolve(rest)
+  if rest.empty? || %w[--help -h help].include?(rest.first)
+    puts <<~HELP
+      Usage:
+        bin/seams resolve --eject <engine>/<file_relative>
+            Mark a single host file as host-owned (skipped on regenerate).
+            Example: bin/seams resolve --eject auth/app/mailers/auth/passwords_mailer.rb
+
+        bin/seams resolve --list-markers <engine>
+            List every insertion-point marker the engine ships.
+
+        bin/seams resolve --list-ejected
+            List every ejected file under engines/.
+    HELP
+    exit 0
+  end
+
+  flag = rest.shift
+  argument = rest.shift
+
+  mode =
+    case flag
+    when "--eject"        then :eject
+    when "--list-markers" then :list_markers
+    when "--list-ejected" then :list_ejected
+    else
+      abort "Unknown resolve flag: #{flag.inspect}. Run `bin/seams resolve --help` for usage."
+    end
+
+  require "bundler/setup"
+  require "seams/cli"
+  ok = Seams::CLI.resolve(mode: mode, argument: argument)
+  exit(ok ? 0 : 1)
+end
+
+cmd, *rest = ARGV
+case cmd
+when nil, "help", "-h", "--help"
+  puts <<~HELP
+    Usage: bin/seams <command> [args]
+
+    Canonical generators:
+      install                       Install the framework
+      engine <name>                 Generate a generic engine
+      core | auth | accounts | notifications | billing | teams | admin
+                                    Generate a canonical engine
+      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.
+
+    Diagnostics + escape hatch:
+      list                          List engines + their events
+      test <engine>                 Run an engine's specs
+      quality <engine>              Run rubocop on an engine
+      resolve --eject <engine>/<file>
+                                    Mark a host file as host-owned (skipped on regenerate)
+      resolve --list-markers <engine>
+                                    List insertion-point markers in the engine
+      resolve --list-ejected        List every ejected file under engines/
+      resolve --help                Detail on each resolve mode
+  HELP
+  exit 0
+when "resolve"
+  run_resolve(rest)
+when *CANONICAL
+  exec "bin/rails", "generate", "seams:#{cmd}", *rest
+when *GENERIC
+  exec "bin/rails", "generate", "seams:#{cmd}", *rest
+when *TASKS
+  exec "bin/rails", "seams:#{cmd}"
+when *ENGINE_TASKS
+  abort "Usage: bin/seams #{cmd} <engine>" if rest.empty?
+  exec "bin/rails", "seams:#{cmd}[#{rest.first}]"
+else
+  abort "Unknown command: #{cmd.inspect}. Run `bin/seams help` for the list."
+end

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

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CI: "true"
+  BUNDLE_JOBS: 4
+  BUNDLE_RETRY: 3
+
+jobs:
+  lint:
+    name: RuboCop
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ".ruby-version"
+          bundler-cache: true
+      - run: bundle exec rubocop --parallel
+
+  security:
+    name: Security (brakeman + bundle-audit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ".ruby-version"
+          bundler-cache: true
+      - run: bundle exec brakeman --no-pager --no-progress --quiet
+      - run: bundle exec bundle-audit check --update
+
+  # Discover engines once and fan out — every engine's specs run in
+  # parallel under its own job. Seams custom RuboCop cops still run
+  # against engine code (in the lint job above) but unit specs run
+  # per engine for fast signal.
+  discover:
+    name: Discover engines
+    runs-on: ubuntu-latest
+    outputs:
+      engines: ${{ steps.set.outputs.engines }}
+    steps:
+      - uses: actions/checkout@v4
+      - id: set
+        run: |
+          if [ -d engines ]; then
+            engines=$(find engines -mindepth 1 -maxdepth 1 -type d \
+                      -not -name '.*' -printf '%f\n' \
+                      | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          else
+            engines='[]'
+          fi
+          echo "engines=$engines" >> "$GITHUB_OUTPUT"
+
+  test_engine:
+    name: Test ${{ matrix.engine }}
+    needs: discover
+    if: needs.discover.outputs.engines != '[]'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        engine: ${{ fromJson(needs.discover.outputs.engines) }}
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DATABASE_URL: "postgres://postgres:postgres@localhost:5432"
+      PGHOST:     "localhost"
+      PGPORT:     "5432"
+      PGUSER:     "postgres"
+      PGPASSWORD: "postgres"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ".ruby-version"
+          bundler-cache: true
+      - run: bundle exec rspec --default-path engines/${{ matrix.engine }}/spec engines/${{ matrix.engine }}/spec
+
+  test_app:
+    name: Test host app
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_PASSWORD: postgres
+        ports: ["5432:5432"]
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    env:
+      DATABASE_URL: "postgres://postgres:postgres@localhost:5432"
+      PGHOST:     "localhost"
+      PGPORT:     "5432"
+      PGUSER:     "postgres"
+      PGPASSWORD: "postgres"
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ".ruby-version"
+          bundler-cache: true
+      - run: bundle exec rspec spec

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

@@ -0,0 +1,63 @@
+# Kamal deploy config — TEMPLATE. Every value below is a placeholder
+# and `kamal setup` will fail until you replace them. Reference:
+# https://kamal-deploy.org
+#
+# Required edits before first deploy:
+#   - service / image — your app + container registry repo
+#   - servers.web / servers.worker hosts — real IPs or hostnames
+#   - registry.username + KAMAL_REGISTRY_PASSWORD secret in .kamal/secrets
+#   - accessories.postgres — choose between Kamal-managed Postgres
+#     (uncomment + size the volume) or a managed service (delete the
+#     accessory + provide DATABASE_URL via env.secret)
+#   - solid_queue migrations: run `bin/rails solid_queue:install:migrations`
+#     once locally, commit the migrations, and they'll apply on first deploy
+#     via bin/docker-entrypoint.
+
+# TODO: replace placeholders before running `kamal setup`.
+service: TODO_my_app
+image: TODO_org/TODO_my_app
+
+servers:
+  web:
+    - TODO.web.example.com
+  worker:
+    cmd: bundle exec rails solid_queue:start
+    hosts:
+      - TODO.worker.example.com
+
+registry:
+  username: TODO_registry_user
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+env:
+  clear:
+    RAILS_LOG_TO_STDOUT: "1"
+    RAILS_SERVE_STATIC_FILES: "1"
+  secret:
+    - RAILS_MASTER_KEY
+    - DATABASE_URL
+    - REDIS_URL
+    - STRIPE_SECRET_KEY
+    - STRIPE_WEBHOOK_SECRET
+
+# Uncomment + size if you want Kamal to manage Postgres for you.
+# Otherwise delete this block and provide DATABASE_URL via env.secret.
+# accessories:
+#   postgres:
+#     image: postgres:16
+#     host: TODO.web.example.com
+#     port: "127.0.0.1:5432:5432"
+#     env:
+#       clear:
+#         POSTGRES_USER: TODO_app
+#         POSTGRES_DB: TODO_app_production
+#       secret:
+#         - POSTGRES_PASSWORD
+#     volumes:
+#       - /var/lib/postgresql/data:/var/lib/postgresql/data
+
+asset_path: /rails/public/assets
+
+# Engines run in the same container — no per-engine deployment.
+# Migrations apply automatically via bin/docker-entrypoint.

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

@@ -0,0 +1,86 @@
+# 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 seams gem source) for framework-level details.
+
+## The model
+
+```
++-------------------+        +---------------------+
+|  This Rails app   |        |   engines/auth/     |
+|                   |        |   engines/billing/  |
+|  routes.rb mounts | -----> |   engines/teams/    |
+|  every engine     |        |   engines/notifs/   |
+|                   |        |   engines/<your>/   |
++-------------------+        +---------------------+
+        |                              ^
+        |  events (Seams::Events       |
+        |  ::Publisher)                |
+        v                              |
++-------------------+                  |
+| Subscribers in    | -----------------+
+| engines/*/        |
++-------------------+
+```
+
+Every engine is a real `Rails::Engine` with `isolate_namespace`. The
+host application loads them all in one process. There are NO HTTP
+calls between engines — they communicate via the in-process event
+bus.
+
+## Where things live
+
+| Concern                  | Lives under            |
+| ---                      | ---                    |
+| Domain logic per concern | `engines/<name>/`      |
+| Cross-engine events      | `engines/<name>/lib/<name>/engine.rb` (Publisher.subscribe) |
+| Routing                  | host `config/routes.rb` (mount lines) + each engine's own |
+| Migrations               | each engine ships its own; the host's `db/migrate/` carries the timestamps |
+| Tests                    | each engine has its own `spec/dummy/` + `spec/runtime/` |
+
+## Cross-engine rules
+
+The seams gem ships four RuboCop cops (`require: seams/cops`) that
+enforce these. CI fails if you break them:
+
+1. **No cross-engine model access.** `Engines::A` cannot
+   `::B::Model.find(...)` directly. Subscribe to events instead.
+2. **No cross-engine constant references** other than concerns
+   exposed via `ExposedConcerns:` in the engine's `.rubocop.yml`.
+3. **No cross-engine database joins.** Engines must own their tables.
+4. **No cross-engine factories** in tests.
+
+If you find yourself wanting to break one of these — that's usually a
+signal the boundary is wrong. Either the responsibility belongs in
+the other engine, or there's a missing third engine.
+
+## Adding a new engine
+
+```bash
+bin/seams engine reporting             # generic
+bin/rails generate seams:auth          # canonical
+```
+
+The generator wires up the host (mount line, initializer,
+gem dependencies). See `doc/ADDING_AN_ENGINE.md` (if your team has
+extracted it from the seams gem) for the full conventions.
+
+## Removing an engine
+
+```bash
+bin/seams remove reporting --force
+bin/rails db:migrate                   # applies the auto-generated drop migration
+```
+
+The remover writes a drop-table migration into `db/migrate/` for the
+tables that engine created. Run `db:migrate` to apply.
+
+## Testing
+
+```bash
+bundle exec rspec                       # everything
+script/run_affected_tests.sh            # only engines changed vs main
+script/run_affected_tests.sh --all      # every engine, no diff filtering
+ruby script/collate_coverage.rb         # merge coverage reports across engines
+```

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

@@ -0,0 +1,27 @@
+#!/bin/bash
+# bin/docker-entrypoint
+#
+# Runs db:prepare on the WEB container only — workers skip it. With
+# Kamal, web boots before workers, so by the time worker starts the
+# migrations are already applied.
+#
+# If you want stricter migration control (CI-driven, separate job),
+# comment the db:prepare branch out and run migrations from a Kamal
+# pre-deploy hook:
+#
+#   kamal app exec --reuse "bin/rails db:migrate"
+#
+# Then redeploy the web image. The race-free pattern.
+
+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"*)
+    bundle exec rails db:prepare
+    ;;
+esac
+
+exec "$@"