seams 0.1.0

data/lib/generators/seams/accounts/templates/app/models/membership.rb.tt

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Accounts
+  # Joins an Auth::Identity to an Accounts::Account with a role.
+  #
+  # `identity_id` is **nullable**: when set, the row represents a real
+  # human in this Account (an owner, admin, or member). When NULL, the
+  # row is a system actor — the audit-log writer for changes that
+  # don't have a human behind them (background jobs, webhook
+  # ingestion, scheduled tasks). Every Account ships with exactly one
+  # `role: :system, identity_id: nil` row, created by
+  # `Account.create_with_owner`.
+  #
+  # An Identity can have at most one Membership per Account
+  # (enforced by the unique compound index in the migration); the
+  # role lives on the Membership, not the Identity.
+  class Membership < ApplicationRecord
+    self.table_name           = "accounts_memberships"
+    self.primary_key          = "id"
+    self.implicit_order_column = "created_at"
+
+    ROLES = %w[owner admin member system].freeze
+
+    belongs_to :account, class_name: "Accounts::Account"
+
+    validates :name, presence: true
+    validates :role, inclusion: { in: ROLES }
+    validates :identity_id,
+              uniqueness: { scope: :account_id, allow_nil: true,
+                            message: "already has a membership in this account" }
+
+    scope :owner,  -> { where(role: "owner") }
+    scope :admin,  -> { where(role: %w[owner admin]) }
+    scope :member, -> { where(role: "member") }
+    # `:active` excludes the system actor — callers that want every
+    # actor (including system) should query without the scope.
+    scope :active, -> { where(active: true).where.not(role: "system") }
+    scope :system_actors, -> { where(role: "system") }
+
+    after_create_commit :publish_membership_created
+    after_update_commit :publish_role_changed, if: :saved_change_to_role?
+    after_destroy_commit :publish_membership_removed
+
+    def owner?
+      role == "owner"
+    end
+
+    def admin?
+      %w[owner admin].include?(role)
+    end
+
+    def system?
+      role == "system"
+    end
+
+    # Can `self` perform admin-level changes against `other` (another
+    # Membership)? Owners can change anyone, admins can change anyone
+    # except an owner, members and the system actor cannot change
+    # anyone. Pairs with `can_change?` for the slightly more
+    # permissive change-anything-non-destructive rule.
+    def can_administer?(other)
+      return false if system?
+      return false unless admin?
+      return true  if owner?
+
+      !other.owner?
+    end
+
+    # Like `can_administer?` but allows admins to change other admins
+    # (just not owners). Used for invite/remove flows where two
+    # admins should be able to manage each other.
+    def can_change?(other)
+      return false if system?
+      return false unless admin?
+      return true  if owner?
+
+      !other.owner?
+    end
+
+    private
+
+    def publish_membership_created
+      Seams::Events::Publisher.publish(
+        "membership.created.accounts",
+        account_id:    account_id,
+        membership_id: id,
+        identity_id:   identity_id,
+        role:          role
+      )
+    end
+
+    def publish_role_changed
+      from_role, to_role = saved_change_to_role
+      Seams::Events::Publisher.publish(
+        "membership.role_changed.accounts",
+        account_id:                account_id,
+        membership_id:             id,
+        from_role:                 from_role,
+        to_role:                   to_role,
+        changed_by_identity_id:    Accounts::Current.membership&.identity_id
+      )
+    end
+
+    def publish_membership_removed
+      Seams::Events::Publisher.publish(
+        "membership.removed.accounts",
+        account_id:                  account_id,
+        membership_id:               id,
+        identity_id:                 identity_id,
+        removed_by_identity_id:      Accounts::Current.membership&.identity_id
+      )
+    end
+  end
+end

data/lib/generators/seams/accounts/templates/config/routes.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Intentionally empty. The Accounts engine ships no controllers in
+# Wave 9 — hosts wire their own account-creation flows; the engine
+# provides models + concerns. Future waves may add a thin controller
+# surface.
+Accounts::Engine.routes.draw do
+end

data/lib/generators/seams/accounts/templates/db/migrate/create_accounts.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# What: creates the accounts table for the Accounts engine.
+# Why:  Accounts::Account is the tenant boundary. Every other engine
+#       that scopes its data to a tenant binds to this row.
+# Risk: empty table on creation — no data migration needed.
+#
+# UUID primary key (not bigint): account ids appear in shareable URLs
+# and we don't want to leak row counts. external_account_id is a
+# bigint kept alongside for slug encoding so URL slugs stay short.
+class CreateAccounts < ActiveRecord::Migration[7.1]
+  def change
+    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
+
+    create_table :accounts, id: :uuid do |t|
+      t.string   :name,                 null: false
+      t.bigint   :external_account_id,  null: false
+      # Soft cancel: account is unusable but data is still recoverable.
+      t.datetime :cancelled_at
+      # Hard delete grace marker: when set, the host's incinerator job
+      # permanently destroys the row + cascade.
+      t.datetime :incinerated_at
+      t.timestamps
+    end
+
+    add_index :accounts, :external_account_id, unique: true
+    add_index :accounts, :cancelled_at
+  end
+end

data/lib/generators/seams/accounts/templates/db/migrate/create_accounts_memberships.rb.tt

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# What: creates the accounts_memberships join table.
+# Why:  joins Auth::Identity to Accounts::Account with a role.
+#       identity_id is NULLABLE: rows with NULL identity_id are
+#       system actors used for audit-log writes that don't have a
+#       human behind them (background jobs, webhook ingestion).
+# Risk: append-mostly. Unique compound index on (account_id,
+#       identity_id) ensures an Identity has at most one Membership
+#       per Account; system rows (NULL identity_id) bypass that
+#       constraint by virtue of the NULL.
+class CreateAccountsMemberships < ActiveRecord::Migration[7.1]
+  def change
+    enable_extension "pgcrypto" unless extension_enabled?("pgcrypto")
+
+    create_table :accounts_memberships, id: :uuid do |t|
+      t.references :account,      type: :uuid, null: false,
+                                  foreign_key: { to_table: :accounts }, index: false
+      # NULL = system actor. Otherwise references Auth::Identity. No
+      # FK to auth_identities because the auth and accounts engines
+      # may live in different schemas / databases in production —
+      # cross-engine integrity is enforced at the application layer.
+      # bigint to match auth_identities' default integer PK (the same
+      # convention every other engine — billing, teams — follows).
+      t.bigint     :identity_id,  null: true
+      # Denormalised display name so the Identity (and its email)
+      # can be soft-deleted / anonymised without breaking the
+      # account's audit trail.
+      t.string     :name,         null: false
+      t.string     :role,         null: false, default: "member"
+      t.boolean    :active,       null: false, default: true
+      t.datetime   :verified_at
+      t.timestamps
+    end
+
+    add_index :accounts_memberships, %i[account_id identity_id], unique: true,
+                                                                 name: "index_accounts_memberships_unique"
+    add_index :accounts_memberships, %i[account_id role]
+    add_index :accounts_memberships, :identity_id
+    # Postgres treats NULLs as distinct in unique indexes, so the
+    # compound index above does NOT prevent two `(account_id, NULL)`
+    # rows. Wave 9 invariant: every Account has EXACTLY ONE system
+    # actor (created by `Account.create_with_owner`). Enforce it at
+    # the DB level with a partial unique index over the system rows.
+    add_index :accounts_memberships, :account_id, unique: true,
+              where: "role = 'system'",
+              name: "index_accounts_memberships_one_system_per_account"
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "accounts/version"
+require "accounts/configuration"
+require "accounts/engine"
+require "accounts/concerns/account_scoped"
+require "accounts/concerns/authorization"
+
+module Accounts
+  class Error < StandardError; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

data/lib/generators/seams/accounts/templates/lib/concerns/account_scoped.rb.tt

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Accounts
+  # Mix into any model whose rows belong to a single Account. Adds:
+  #
+  #   - `belongs_to :account, class_name: "Accounts::Account"`
+  #   - a default_scope filtered to `Accounts::Current.account`. When
+  #     `Accounts::Current.account` is unset, the scope returns `none`
+  #     (an empty relation) — see "fail-closed" below.
+  #   - presence validation on `account`
+  #
+  #   class AuditEntry < ApplicationRecord
+  #     include Accounts::AccountScoped
+  #   end
+  #
+  #   Accounts::Current.account = account
+  #   AuditEntry.create!(action: "...")  # account_id auto-assigned
+  #   AuditEntry.all                     # only this account's rows
+  #
+  # ### Fail-closed default
+  #
+  # When `Accounts::Current.account` is nil, the default_scope returns
+  # `none` rather than `all`. Rationale: the alternative (return all
+  # rows across all tenants when no account is bound) is the canonical
+  # multi-tenant data-leak bug. A forgotten `Current.account=` in a
+  # background job, an admin tool, or a Rails console session would
+  # otherwise hand the operator another tenant's data without warning.
+  # Fail-closed surfaces "I have no rows" — a noisy symptom the
+  # developer fixes immediately — instead of a silent leak.
+  #
+  # Opt-out paths (use deliberately):
+  #   * `.unscoped` — full Active Record bypass; loses every default
+  #     scope including soft-delete + sluggable; reserved for
+  #     platform-admin / impersonation flows gated on
+  #     `Auth::Current.identity.staff?`.
+  #   * `.with_no_account_scope` — returns the relation as if the
+  #     model were not account-scoped; preserves any other
+  #     default_scopes the model declares; intended for seed scripts,
+  #     migrations, and platform tooling.
+  #
+  # Background jobs MUST set `Accounts::Current.account =` before
+  # querying, or use `.with_no_account_scope` explicitly. The shape:
+  #
+  #   class IngestionJob < ApplicationJob
+  #     def perform(account_id, payload)
+  #       Accounts::Current.account = Accounts::Account.find(account_id)
+  #       AuditEntry.create!(...)   # auto-scoped
+  #     end
+  #   end
+  module AccountScoped
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :account, class_name: "Accounts::Account"
+
+      # The default_scope ALWAYS applies a where(:account_id) clause —
+      # either filtered to the current account or to NULL. The model
+      # validates `account` presence and the `belongs_to` adds a NOT
+      # NULL guard at the application layer, so `where(account_id: nil)`
+      # is a never-matching sentinel — fail-closed without using
+      # `none`. The shape is deliberate: `unscope(where: :account_id)`
+      # in `with_no_account_scope` cleanly reverses this. Using
+      # `none` would create a NullRelation that `unscope` cannot un-do,
+      # which would defeat the documented opt-out path.
+      default_scope -> {
+        account = Accounts::Current.account
+        if account
+          where(account_id: account.id)
+        else
+          where(account_id: nil)
+        end
+      }
+
+      validates :account, presence: true
+
+      before_validation :assign_current_account, on: :create
+    end
+
+    class_methods do
+      # Returns the relation as it would be without the AccountScoped
+      # default_scope, preserving any other default_scopes the model
+      # declares. Use deliberately — name-it-loud opt-out for seed
+      # scripts, migrations, and platform tooling.
+      def with_no_account_scope
+        unscope(where: :account_id)
+      end
+    end
+
+    private
+
+    def assign_current_account
+      self.account_id ||= Accounts::Current.account&.id if Accounts::Current.account
+    end
+  end
+end

data/lib/generators/seams/accounts/templates/lib/concerns/authorization.rb.tt

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Accounts
+  # Controller concern that enforces tenant access on every action by
+  # default. Mix into the host's ApplicationController (or a base
+  # account-scoped controller) and use the class-method helpers to
+  # opt out per-controller.
+  #
+  #   class ApplicationController < ActionController::Base
+  #     include Accounts::Authorization
+  #   end
+  #
+  #   class PublicPagesController < ApplicationController
+  #     disallow_account_scope          # no membership check
+  #   end
+  #
+  #   class OnboardingController < ApplicationController
+  #     require_access_without_membership
+  #   end
+  #
+  # Default-on `before_action :ensure_account_access` checks that the
+  # current Account is active AND the current Membership is active.
+  # Otherwise: 403 (or redirects on HTML).
+  #
+  # `ensure_admin` and `ensure_staff` are opt-in helpers controllers
+  # call from their own `before_action` — they don't run by default.
+  # `ensure_admin` checks the per-Account role (owner/admin);
+  # `ensure_staff` checks the platform-admin flag on Identity (set
+  # via `Auth::Identity#staff?`). Two different powers — keep them
+  # distinct.
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :ensure_account_access if respond_to?(:before_action)
+    end
+
+    class_methods do
+      # Skip the default tenant access check for this controller. Use
+      # for public pages (sign-in, marketing, OAuth callbacks).
+      def disallow_account_scope(**options)
+        skip_before_action :ensure_account_access, **options
+      end
+
+      # Sign-up + onboarding flows: the Identity is signed in but
+      # doesn't have a Membership yet. Skip the access check, but
+      # redirect away if a Membership IS present (otherwise the user
+      # bounces between sign-up and the dashboard).
+      def require_access_without_membership(**options)
+        skip_before_action :ensure_account_access, **options
+        before_action :redirect_existing_membership, **options
+      end
+    end
+
+    private
+
+    def ensure_account_access
+      return if account_access_allowed?
+
+      respond_to do |format|
+        format.html { redirect_to(authorization_redirect_path) }
+        format.json { head :forbidden }
+        format.any  { head :forbidden }
+      end
+    end
+
+    def account_access_allowed?
+      return false unless Accounts::Current.account&.active?
+
+      membership = Accounts::Current.membership
+      membership.present? && membership.active && !membership.system?
+    end
+
+    # Per-account admin (owner OR admin). Use as a controller
+    # `before_action :ensure_admin` for in-account admin tooling
+    # (member management, billing settings, etc.).
+    def ensure_admin
+      head :forbidden unless Accounts::Current.membership&.admin?
+    end
+
+    # Platform admin (Identity#staff?). Use as a controller
+    # `before_action :ensure_staff` for support tooling that has to
+    # bypass the per-account scope (e.g. impersonation, cross-account
+    # search). Distinct from `ensure_admin`.
+    def ensure_staff
+      identity = defined?(Auth::Current) ? Auth::Current.identity : nil
+      head :forbidden unless identity&.staff?
+    end
+
+    def redirect_existing_membership
+      return unless Accounts::Current.membership
+
+      respond_to do |format|
+        format.html { redirect_to(Accounts.configuration.after_account_create_url) }
+        format.any  { head :found }
+      end
+    end
+
+    def authorization_redirect_path
+      Accounts.configuration.after_account_create_url
+    end
+  end
+end

data/lib/generators/seams/accounts/templates/lib/configuration.rb.tt

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Accounts
+  # Engine-scoped configuration. Override in
+  # config/initializers/accounts.rb of the host application:
+  #
+  #   Accounts.configure do |c|
+  #     c.incineration_grace_period = 30.days
+  #     c.after_account_create_url  = "/dashboard"
+  #   end
+  class Configuration
+    attr_accessor :incineration_grace_period,
+                  :after_account_create_url
+    # Follow-up generators that add knobs (account_owner_role, default_account_locale) declare their attr_accessor here.
+    # seams:insertion-point accounts.configuration.attributes
+
+    def initialize
+      # How long a cancelled account lingers before incineration (hard
+      # delete). Hosts use this to power dunning + grace-period UX.
+      @incineration_grace_period = 30 * 24 * 60 * 60   # 30 days
+      @after_account_create_url  = "/"
+      # Follow-up generators that add defaults for new attributes (matching accounts.configuration.attributes) splice them here.
+      # seams:insertion-point accounts.configuration.defaults
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Accounts
+  class Engine < ::Rails::Engine
+    isolate_namespace Accounts
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "accounts.register_events" do
+      Seams::EventRegistry.register("account.created.accounts",            emitted_by: "Accounts")
+      Seams::EventRegistry.register("account.cancelled.accounts",          emitted_by: "Accounts")
+      Seams::EventRegistry.register("membership.created.accounts",         emitted_by: "Accounts")
+      Seams::EventRegistry.register("membership.role_changed.accounts",    emitted_by: "Accounts")
+      Seams::EventRegistry.register("membership.removed.accounts",         emitted_by: "Accounts")
+      # Follow-up generators that emit new accounts events (account.upgraded.accounts, etc.) register them here.
+      # seams:insertion-point accounts.engine.events
+    end
+
+    initializer "accounts.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 declare it here, ahead of the cross-engine dependency check.
+    # seams:insertion-point accounts.engine.initializers
+
+    # Boot-time dependency assertion. Accounts requires Auth: an
+    # Accounts::Membership with an `identity_id` is meaningless
+    # without an `auth_identities` row to point at. We enforce this
+    # at app boot rather than at first failed query so the operator
+    # gets a clear "install seams:auth" error instead of a deep stack
+    # trace mid-request.
+    config.after_initialize do
+      missing = []
+      missing << "Auth::Identity (run: bin/rails generate seams:auth)" unless defined?(::Auth::Identity)
+
+      if missing.any?
+        raise <<~MSG
+          [seams accounts] missing required cross-engine dependency:
+              #{missing.join("\n              ")}
+
+          The accounts engine joins Auth::Identity rows to
+          Accounts::Account rows; it cannot run without auth. Generate
+          the auth engine and re-run db:migrate, or remove accounts
+          with `bin/rails generate seams:remove accounts --force`.
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/seams/accounts/templates/spec/factories/accounts.rb.tt

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Factories for Accounts engine specs. Sequences keep names unique
+# across the full spec run. The :membership factory associates with
+# the auth engine's :auth_identity factory — ensure both engines
+# are loaded in the dummy app or include the auth_identities table
+# in this engine's dummy schema.
+FactoryBot.define do
+  factory :account, class: "Accounts::Account" do
+    sequence(:name) { |n| "Account #{n}" }
+    sequence(:external_account_id) { |n| 1_000_000 + n }
+  end
+
+  factory :membership, class: "Accounts::Membership" do
+    association :account
+    association :identity, factory: :auth_identity
+    sequence(:name) { |n| "Member #{n}" }
+    role   { "member" }
+    active { true }
+
+    # Denormalises identity_id from the association rather than
+    # relying on belongs_to magic — Membership has no `belongs_to
+    # :identity` because the auth engine and accounts engine are
+    # peer engines (no cross-engine model access at the
+    # ActiveRecord level).
+    after(:build) do |membership, evaluator|
+      membership.identity_id = evaluator.identity&.id
+    end
+
+    transient do
+      identity { nil }
+    end
+
+    factory :owner_membership do
+      role { "owner" }
+    end
+
+    factory :admin_membership do
+      role { "admin" }
+    end
+
+    factory :system_membership do
+      role        { "system" }
+      identity    { nil }
+      identity_id { nil }
+      name        { "System" }
+    end
+  end
+end

data/lib/generators/seams/accounts/templates/spec/models/accounts/account_spec.rb.tt

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Accounts::Account do
+  describe "validations" do
+    it "requires a name" do
+      account = described_class.new
+      expect(account).not_to be_valid
+      expect(account.errors[:name]).to include("can't be blank")
+    end
+  end
+
+  describe "scopes" do
+    it ".active excludes cancelled accounts" do
+      live      = described_class.create!(name: "Live")
+      cancelled = described_class.create!(name: "Cancelled", cancelled_at: 1.day.ago)
+
+      expect(described_class.active).to     include(live)
+      expect(described_class.active).not_to include(cancelled)
+    end
+  end
+
+  describe "#active?" do
+    it "is true when not cancelled and not incinerated" do
+      expect(described_class.new).to be_active
+    end
+
+    it "is false when cancelled_at is set" do
+      expect(described_class.new(cancelled_at: 1.day.ago)).not_to be_active
+    end
+
+    it "is false when incinerated_at is set" do
+      expect(described_class.new(incinerated_at: 1.day.ago)).not_to be_active
+    end
+  end
+
+  describe "#assign_external_account_id" do
+    it "auto-assigns external_account_id on create when blank" do
+      account = described_class.create!(name: "Acme")
+      expect(account.external_account_id).to be_a(Integer)
+      expect(account.external_account_id).to be > 0
+    end
+  end
+
+  describe ".create_with_owner" do
+    let(:identity) { Auth::Identity.create!(email: "owner-#{SecureRandom.hex(4)}@example.com", password: "verysecret") }
+    let(:owner)    { Struct.new(:identity, :name).new(identity, "Ada") }
+
+    it "creates an account, a system membership, and an owner membership" do
+      account = described_class.create_with_owner(account: { name: "Acme" }, owner: owner)
+      expect(account.memberships.pluck(:role)).to match_array(%w[system owner])
+    end
+
+    it "rolls back the account when the owner membership fails to save" do
+      bad_owner = Struct.new(:identity, :name).new(identity, nil)
+
+      expect {
+        described_class.create_with_owner(account: { name: "Bad" }, owner: bad_owner)
+      }.to raise_error(ActiveRecord::RecordInvalid)
+       .and(change(described_class, :count).by(0))
+    end
+  end
+end