seams 0.1.0

data/lib/generators/seams/core/core_generator.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "rails/generators"
+require "seams"
+require "generators/seams/engine/engine_generator"
+require "seams/generators/host_injector"
+require "seams/generators/eject_aware"
+require "seams/generators/dummy_app_writer"
+
+module Seams
+  module Generators
+    # Generates a canonical Core engine on top of the generic engine
+    # scaffold. Ships the seven primitive concerns + AuditLog model
+    # other engines lean on:
+    #
+    #   - Core::Auditable          — records create/update/destroy in audit_logs
+    #   - Core::SoftDeletable      — deleted_at column + default_scope
+    #   - Core::Sluggable          — auto-generated URL slug from a configurable field
+    #   - Core::TenantScoped       — scopes records to Current.team
+    #   - Core::HasCurrentAttributes — Current.user / Current.team
+    #   - Core::EventPublisher     — convenience wrapper around Seams::Events::Publisher
+    #   - Core::EmailFormatValidator — custom validator
+    #
+    # Run with: bin/rails generate seams:core
+    class CoreGenerator < Rails::Generators::Base
+      include Seams::Generators::HostInjector
+      include Seams::Generators::EjectAware
+
+      source_root File.expand_path("templates", __dir__)
+
+      ENGINE_NAME = "core"
+
+      def create_base_engine
+        EngineGenerator.start([ENGINE_NAME], destination_root: destination_root)
+      end
+
+      def overwrite_engine_entry_point
+        # engine.rb / lib/core.rb stay framework-managed.
+        template "lib/engine.rb.tt", engine_path("lib/core/engine.rb"), force: true
+        template "lib/core.rb.tt",   engine_path("lib/core.rb"),        force: true
+      end
+
+      def create_models
+        template_unless_ejected "app/models/application_record.rb.tt",
+                                engine_path("app/models/core/application_record.rb")
+        template_unless_ejected "app/models/audit_log.rb.tt",
+                                engine_path("app/models/core/audit_log.rb")
+      end
+
+      def create_concerns
+        template_unless_ejected "app/models/concerns/auditable.rb.tt",
+                                engine_path("app/models/concerns/core/auditable.rb")
+        template_unless_ejected "app/models/concerns/soft_deletable.rb.tt",
+                                engine_path("app/models/concerns/core/soft_deletable.rb")
+        template_unless_ejected "app/models/concerns/sluggable.rb.tt",
+                                engine_path("app/models/concerns/core/sluggable.rb")
+        template_unless_ejected "app/models/concerns/tenant_scoped.rb.tt",
+                                engine_path("app/models/concerns/core/tenant_scoped.rb")
+        template_unless_ejected "app/controllers/concerns/has_current_attributes.rb.tt",
+                                engine_path("app/controllers/concerns/core/has_current_attributes.rb")
+      end
+
+      def create_services_and_validators
+        template_unless_ejected "app/services/event_publisher.rb.tt",
+                                engine_path("app/services/core/event_publisher.rb")
+        template_unless_ejected "app/validators/email_format_validator.rb.tt",
+                                engine_path("app/validators/core/email_format_validator.rb")
+      end
+
+      def create_current
+        template_unless_ejected "app/models/current.rb.tt",
+                                engine_path("app/models/core/current.rb")
+      end
+
+      def create_migration
+        template "db/migrate/create_core_audit_logs.rb.tt",
+                 engine_path("db/migrate/#{timestamp}_create_core_audit_logs.rb")
+      end
+
+      def create_specs
+        template_unless_ejected "spec/models/audit_log_spec.rb.tt",
+                                engine_path("spec/models/core/audit_log_spec.rb")
+        template_unless_ejected "spec/concerns/auditable_spec.rb.tt",
+                                engine_path("spec/concerns/core/auditable_spec.rb")
+        template_unless_ejected "spec/concerns/sluggable_spec.rb.tt",
+                                engine_path("spec/concerns/core/sluggable_spec.rb")
+        template_unless_ejected "spec/validators/email_format_validator_spec.rb.tt",
+                                engine_path("spec/validators/core/email_format_validator_spec.rb")
+      end
+
+      def overwrite_readme
+        template "README.md.tt", engine_path("README.md"), force: true
+      end
+
+      def update_exposed_concerns
+        rubocop_path = engine_path(".rubocop.yml")
+        return unless File.exist?(rubocop_path)
+
+        contents = File.read(rubocop_path)
+        replacement = "  ExposedConcerns:\n    " \
+                      "- Core::Auditable\n    " \
+                      "- Core::SoftDeletable\n    " \
+                      "- Core::Sluggable\n    " \
+                      "- Core::TenantScoped\n    " \
+                      "- Core::HasCurrentAttributes"
+        contents.sub!(/^  ExposedConcerns: \[\]$/, replacement)
+        File.write(rubocop_path, contents)
+      end
+
+      def create_dummy_app
+        # Post Wave 9: the dummy app does NOT ship a host User model.
+        # The auditable spec stubs its own `Article` (via stub_const)
+        # and the tenant_scoped/sluggable specs work against the
+        # `articles`/`teams` tables in dummy_schema. There is no
+        # remaining caller for a top-level User class.
+        Seams::Generators::DummyAppWriter.write!(
+          engine_path: File.join(destination_root, "engines", ENGINE_NAME),
+          engine_module: "Core",
+          schema: dummy_schema
+        )
+        template "spec/runtime/boot_spec.rb.tt",
+                 engine_path("spec/runtime/core_boot_spec.rb")
+      end
+
+      def wire_into_host
+        host_inject_mount(engine_class: "Core::Engine", at: "/")
+      end
+
+      def report_summary
+        say ""
+        say "  Core engine generated at engines/core/", :green
+        say ""
+        say "  Next steps:", :yellow
+        say "    1. bin/rails db:migrate"
+        say "    2. Mix concerns into your models as needed:"
+        say "         include Core::Auditable, Core::SoftDeletable, Core::Sluggable, etc."
+        say "    3. Run the engine specs: bin/rails seams:test[core]"
+        say ""
+      end
+
+      private
+
+      def engine_path(relative)
+        File.join(destination_root, "engines", ENGINE_NAME, relative)
+      end
+
+      def dummy_schema
+        <<~SCHEMA
+          create_table :core_audit_logs do |t|
+            t.string  :action,         null: false
+            t.string  :auditable_type
+            t.string  :auditable_id
+            t.bigint  :actor_id
+            t.jsonb   :payload,        null: false, default: {}
+            t.timestamps
+          end
+          add_index :core_audit_logs, %i[auditable_type auditable_id]
+
+          create_table :articles do |t|
+            t.string   :title
+            t.string   :slug
+            t.datetime :deleted_at
+            t.bigint   :team_id
+            t.timestamps
+          end
+          add_index :articles, :slug, unique: true
+
+          create_table :teams do |t|
+            t.string :name
+            t.string :slug
+            t.timestamps
+          end
+          add_index :teams, :slug, unique: true
+        SCHEMA
+      end
+
+      # Core's migration sits AHEAD of the canonical engine offsets
+      # (auth +0/+1, notifications +100, billing +200..+202, teams
+      # +300..+302) so other engines' tables can reference audit_logs
+      # if they ever need to.
+      def timestamp
+        base = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        # Use a NEGATIVE offset (subtract 1000) so core migrates first
+        # in the standard ordering. This is safe because timestamps are
+        # just sortable strings.
+        (base - 1000).to_s
+      end
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# Core
+
+> Foundation primitives every Seams engine can build on. Concerns for
+> auditing, soft delete, slugs, multi-tenancy, plus shared services
+> and validators.
+
+## Events emitted
+
+| Event name | Payload | Emitted when |
+| --- | --- | --- |
+| `record.audited.core` | `{ action:, type:, id:, actor_id: }` | `Core::Auditable` records an entry on create/update/destroy |
+
+## Events consumed
+
+This engine does not subscribe to any other engine's events.
+
+## Exposed concerns
+
+| Concern                                | Purpose                                              |
+| ---                                    | ---                                                  |
+| `Core::Auditable`                      | Records audit entries for the model on CRUD.         |
+| `Core::SoftDeletable`                  | `deleted_at` tombstone + default scope.              |
+| `Core::Sluggable`                      | Auto-generated URL slug with collision suffixing.    |
+| `Core::TenantScoped`                   | Auto-scopes records to `Core::Current.team`.         |
+| `Core::HasCurrentAttributes`           | Populates `Core::Current` on every request.          |
+
+## Services + validators
+
+| Symbol                              | Purpose                                                                   |
+| ---                                 | ---                                                                       |
+| `Core::EventPublisher.publish`      | Wraps `Seams::Events::Publisher.publish` and adds actor/team/request id. |
+| `Core::EmailFormatValidator`        | Stricter email-shape validator (`validates :email, email_format: true`). |
+| `Core::Current` (CurrentAttributes) | Per-request `user`, `team`, `request_id`.                                |
+
+## Mounting
+
+The engine has no routes — it ships shared code, not endpoints. The
+generator mounts at `/` for completeness; you can remove the mount
+line if you don't need any routing entry point.
+
+## Running the specs
+
+```bash
+bin/rails seams:test[core]
+```

data/lib/generators/seams/core/templates/app/controllers/concerns/has_current_attributes.rb.tt

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Core
+  # Mix into ApplicationController to populate Core::Current at the
+  # start of every request. Hosts override #resolve_current_user and
+  # #resolve_current_team to plug in their own auth/tenant lookup —
+  # the default implementations look for `Auth::Current.identity`
+  # (the Auth engine's per-request namespace post-Wave-9) and
+  # `params[:team_id]` (the Teams engine).
+  #
+  # `Core::Current.user` is best read as "the current actor" — the
+  # auditable concern writes `actor_id = Core::Current.user&.id`. By
+  # default that's the signed-in Identity. Hosts that maintain a
+  # domain-specific User on top of Auth::Identity can override
+  # #resolve_current_user to point at that User instead.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Core::HasCurrentAttributes
+  #   end
+  module HasCurrentAttributes
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :populate_current_attributes
+    end
+
+    private
+
+    def populate_current_attributes
+      Core::Current.user       = resolve_current_user
+      Core::Current.team       = resolve_current_team
+      Core::Current.request_id = request.request_id if respond_to?(:request)
+    end
+
+    # Default resolution order (post-Wave-9):
+    #   1. `Auth::Current.identity` — the canonical signed-in human.
+    #   2. `current_identity`       — the helper Auth engine exposes.
+    #   3. `current_user`           — the legacy Wave-8 helper, kept
+    #      so hosts that maintain a User on top of Auth::Identity
+    #      stay working without overriding the concern.
+    # Hosts override this method to plug in a different actor.
+    def resolve_current_user
+      if defined?(Auth::Current) && Auth::Current.respond_to?(:identity) && Auth::Current.identity
+        return Auth::Current.identity
+      end
+      return current_identity if respond_to?(:current_identity)
+      return current_user     if respond_to?(:current_user)
+
+      nil
+    end
+
+    # Default: read `Teams::Current.team` (set by the host's teams
+    # before_action), which the boundary cop exempts as a per-request
+    # namespace. Hosts that want a different binding (e.g. resolving
+    # the team from `params[:team_id]` without delegating to teams)
+    # override this method in their ApplicationController.
+    #
+    # Why we no longer reach into `Teams::Team` here: doing so makes
+    # core depend on teams, which inverts the dependency direction
+    # (teams may include core's concerns; core must not know about
+    # teams' models). Reading `Teams::Current.team` keeps the
+    # cross-engine surface to the documented per-request namespace.
+    def resolve_current_team
+      return nil unless defined?(Teams::Current) && Teams::Current.respond_to?(:team)
+
+      Teams::Current.team
+    end
+  end
+end

data/lib/generators/seams/core/templates/app/models/application_record.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Core
+  class ApplicationRecord < ::ApplicationRecord
+    self.abstract_class = true
+  end
+end

data/lib/generators/seams/core/templates/app/models/audit_log.rb.tt

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Core
+  # Records create/update/destroy events for any model that includes
+  # Core::Auditable. Schema is intentionally polymorphic so the audit
+  # table can serve every engine.
+  class AuditLog < ApplicationRecord
+    self.table_name = "core_audit_logs"
+
+    ACTIONS = %w[create update destroy].freeze
+
+    belongs_to :auditable, polymorphic: true, optional: true
+
+    validates :action, inclusion: { in: ACTIONS }
+
+    scope :for, ->(record) { where(auditable_type: record.class.name, auditable_id: record.id) }
+    scope :recent, -> { order(created_at: :desc) }
+  end
+end

data/lib/generators/seams/core/templates/app/models/concerns/auditable.rb.tt

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Core
+  # Mix into any model to get an audit log entry on every
+  # create/update/destroy. Records the actor from Current.user and
+  # the changed attributes for updates.
+  #
+  #   class Article < ApplicationRecord
+  #     include Core::Auditable
+  #   end
+  module Auditable
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :audit_logs, class_name: "Core::AuditLog",
+                            as: :auditable, dependent: :nullify
+
+      # after_commit (not after_create / after_update / after_destroy)
+      # so the publish doesn't fire inside the host model's open
+      # transaction. Subscribers run synchronously; an in-transaction
+      # publish lets a slow subscriber hold the table lock.
+      after_commit :record_audit_create,  on: :create
+      after_commit :record_audit_update,  on: :update
+      after_commit :record_audit_destroy, on: :destroy
+    end
+
+    private
+
+    def record_audit_create
+      record_audit("create", attributes_snapshot)
+    end
+
+    def record_audit_update
+      changed = saved_changes.transform_values(&:last)
+      return if changed.empty?
+
+      record_audit("update", changed)
+    end
+
+    def record_audit_destroy
+      record_audit("destroy", attributes_snapshot)
+    end
+
+    def record_audit(action, payload)
+      Core::AuditLog.create!(
+        action:         action,
+        auditable_type: self.class.name,
+        auditable_id:   id,
+        actor_id:       Core::Current.user&.id,
+        payload:        payload
+      )
+      Seams::Events::Publisher.publish(
+        "record.audited.core",
+        action: action, type: self.class.name, id: id, actor_id: Core::Current.user&.id
+      )
+    end
+
+    def attributes_snapshot
+      attributes.except("created_at", "updated_at")
+    end
+  end
+end

data/lib/generators/seams/core/templates/app/models/concerns/sluggable.rb.tt

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Core
+  # Auto-generates a URL slug from a configured source attribute on
+  # create. Appends a numeric suffix on collision (acme, acme-2,
+  # acme-3, ...) so users see "creating Acme" succeed even when the
+  # name is taken.
+  #
+  #   class Team < ApplicationRecord
+  #     include Core::Sluggable
+  #     sluggable_from :name
+  #   end
+  module Sluggable
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def sluggable_from(attribute)
+        @slug_source = attribute
+      end
+
+      def slug_source
+        @slug_source || :name
+      end
+    end
+
+    included do
+      validates :slug, presence: true, uniqueness: true,
+                       format: { with: /\A[a-z0-9-]+\z/ }
+      before_validation :assign_slug, on: :create
+    end
+
+    private
+
+    def assign_slug
+      return if slug.present?
+
+      base    = slug_base
+      candidate = base
+      counter = 2
+      while self.class.where.not(id: id).exists?(slug: candidate)
+        candidate = "#{base}-#{counter}"
+        counter += 1
+      end
+      self.slug = candidate
+    end
+
+    def slug_base
+      send(self.class.slug_source).to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/(^-|-$)/, "")
+    end
+  end
+end

data/lib/generators/seams/core/templates/app/models/concerns/soft_deletable.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Core
+  # Tombstone-style soft delete. Sets `deleted_at` instead of actually
+  # destroying the row, and adds a default scope that hides deleted
+  # records. Use `unscoped` to query them.
+  #
+  #   class Article < ApplicationRecord
+  #     include Core::SoftDeletable
+  #   end
+  #
+  # Requires a `deleted_at` timestamp column on the model's table.
+  module SoftDeletable
+    extend ActiveSupport::Concern
+
+    included do
+      default_scope { where(deleted_at: nil) }
+
+      scope :deleted, -> { unscoped.where.not(deleted_at: nil) }
+      scope :with_deleted, -> { unscoped }
+    end
+
+    def soft_delete!
+      update!(deleted_at: Time.current)
+    end
+
+    def restore!
+      update!(deleted_at: nil)
+    end
+
+    def deleted?
+      deleted_at.present?
+    end
+  end
+end

data/lib/generators/seams/core/templates/app/models/concerns/tenant_scoped.rb.tt

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Core
+  # Multi-tenant row scoping. Auto-fills team_id from Core::Current.team
+  # on create and adds a default scope that filters to the current
+  # team's rows.
+  #
+  #   class Article < ApplicationRecord
+  #     include Core::TenantScoped
+  #   end
+  #
+  # Requires a `team_id` column on the model's table. Pair with the
+  # Teams engine, or any model that exposes Core::Current.team.
+  module TenantScoped
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :team, optional: true
+
+      default_scope do
+        if Core::Current.team
+          where(team_id: Core::Current.team.id)
+        else
+          all
+        end
+      end
+
+      before_validation :assign_team, on: :create
+    end
+
+    private
+
+    def assign_team
+      self.team_id ||= Core::Current.team&.id
+    end
+  end
+end

data/lib/generators/seams/core/templates/app/models/current.rb.tt

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Core
+  # Per-request global state. Hosts set Current.user (typically from
+  # an Auth before-action) and Current.team (from a tenant-scope
+  # before-action) so deeper layers — concerns, jobs invoked from
+  # the request, etc. — can read them without threading args through.
+  #
+  # Backed by ActiveSupport::CurrentAttributes which clears between
+  # requests automatically.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :user, :team, :request_id
+
+    resets { Time.zone = nil }
+  end
+end

data/lib/generators/seams/core/templates/app/services/event_publisher.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Core
+  # Thin convenience wrapper around Seams::Events::Publisher. Adds
+  # the request id, actor id, and team id from Core::Current to every
+  # payload so subscribers don't have to thread that context through
+  # by hand.
+  #
+  #   Core::EventPublisher.publish("subscription.created.billing", id: 42)
+  module EventPublisher
+    module_function
+
+    def publish(event_name, payload = {})
+      enriched = payload.merge(
+        actor_id:   Core::Current.user&.id,
+        team_id:    Core::Current.team&.id,
+        request_id: Core::Current.request_id
+      ).compact
+
+      Seams::Events::Publisher.publish(event_name, enriched)
+    end
+  end
+end

data/lib/generators/seams/core/templates/app/validators/email_format_validator.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Core
+  # ActiveModel validator. Use as `validates :email, "core/email_format": true`
+  # or via the convenience: `validates :email, email_format: true` (Rails
+  # auto-discovers `EmailFormatValidator`).
+  #
+  # Stricter than URI::MailTo::EMAIL_REGEXP — also rejects consecutive
+  # dots, leading/trailing dots in the local part, and trailing dots
+  # in the domain.
+  class EmailFormatValidator < ActiveModel::EachValidator
+    PATTERN = /\A[^\s@]+@[^\s@]+\.[^\s@]+\z/
+
+    def validate_each(record, attribute, value)
+      return if value.blank?
+
+      record.errors.add(attribute, :invalid) unless PATTERN.match?(value.to_s)
+      record.errors.add(attribute, :invalid) if value.to_s.include?("..")
+    end
+  end
+end

data/lib/generators/seams/core/templates/db/migrate/create_core_audit_logs.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# What: creates the core_audit_logs table.
+# Why:  every engine that mixes Core::Auditable into a model needs
+#       somewhere to write audit entries. Single shared table keeps
+#       cross-engine queries trivial ("show me everything actor X did
+#       last week" doesn't have to UNION across N tables).
+# Risk: append-only writes from after_create/update/destroy hooks.
+#       Indexed by auditable + actor for the common queries.
+class CreateCoreAuditLogs < ActiveRecord::Migration[7.1]
+  def change
+    create_table :core_audit_logs do |t|
+      t.string  :action,          null: false
+      t.string  :auditable_type
+      # String, not bigint — auditable can be a Wave-9 UUID-PK Account
+      # or Membership, OR a bigint-PK Identity / Notification / Plan.
+      # Polymorphic over both ID-types means the column has to be
+      # widest-of (string). Actors stay bigint (Identity is bigint-PK).
+      t.string  :auditable_id
+      t.bigint  :actor_id
+      t.jsonb   :payload,         null: false, default: {}
+      t.timestamps
+    end
+
+    add_index :core_audit_logs, %i[auditable_type auditable_id]
+    add_index :core_audit_logs, :actor_id
+    add_index :core_audit_logs, %i[action created_at]
+  end
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "core/version"
+require "core/engine"
+
+module Core
+  class Error < StandardError; end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Core
+  class Engine < ::Rails::Engine
+    isolate_namespace Core
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "core.register_events" do
+      Seams::EventRegistry.register("record.audited.core", emitted_by: "Core")
+      # Follow-up generators that emit new core events (e.g. record.soft_deleted.core) register them here.
+      # seams:insertion-point core.engine.events
+    end
+
+    initializer "core.append_migrations" do |app|
+      unless app.root == root
+        config.paths["db/migrate"].expanded.each do |expanded_path|
+          app.config.paths["db/migrate"] << expanded_path
+        end
+      end
+    end
+
+    # Follow-up generators that need their own initializer block (audit subscribers, validators) declare them here.
+    # seams:insertion-point core.engine.initializers
+  end
+end