seams 0.1.0

data/lib/generators/seams/accounts/accounts_generator.rb

@@ -0,0 +1,272 @@
+# 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 Accounts engine on top of the generic engine
+    # scaffold. Adds:
+    #
+    #   - Accounts::Account model. Tenant boundary. UUID PK.
+    #   - Accounts::Membership model. Joins Auth::Identity to Account
+    #     with a role enum (owner/admin/member/system); identity_id is
+    #     nullable for system actors used by audit-log writes.
+    #   - Accounts::Current per-request namespace.
+    #   - Accounts::AccountScoped model concern (default_scope to
+    #     Current.account, opt-out via .unscoped).
+    #   - Accounts::Authorization controller concern (default-on
+    #     ensure_account_access; opt out via disallow_account_scope or
+    #     require_access_without_membership; helpers ensure_admin /
+    #     ensure_staff).
+    #   - Migrations for accounts + accounts_memberships (pgcrypto).
+    #   - lib/accounts/engine.rb registers the canonical events:
+    #     account.created.accounts, account.cancelled.accounts,
+    #     membership.created.accounts, membership.role_changed.accounts,
+    #     membership.removed.accounts.
+    #
+    # The engine ships NO controllers in Wave 9 — hosts drive their
+    # own account-creation flows; this engine is the model + concern
+    # layer.
+    #
+    # Run with: bin/rails generate seams:accounts
+    class AccountsGenerator < Rails::Generators::Base
+      include Seams::Generators::HostInjector
+      include Seams::Generators::EjectAware
+
+      source_root File.expand_path("templates", __dir__)
+
+      ENGINE_NAME = "accounts"
+
+      def create_engine_skeleton
+        EngineGenerator.start([ENGINE_NAME], destination_root: destination_root)
+      end
+
+      def overwrite_engine_entry_point
+        # engine.rb / lib/accounts.rb stay framework-managed.
+        template "lib/engine.rb.tt",                 engine_path("lib/accounts/engine.rb"),        force: true
+        template "lib/accounts.rb.tt",               engine_path("lib/accounts.rb"),               force: true
+        template_unless_ejected "lib/configuration.rb.tt",
+                                engine_path("lib/accounts/configuration.rb")
+      end
+
+      def overwrite_routes
+        template_unless_ejected "config/routes.rb.tt", engine_path("config/routes.rb"), force: true
+      end
+
+      def create_models
+        template_unless_ejected "app/models/application_record.rb.tt",
+                                engine_path("app/models/accounts/application_record.rb")
+        template_unless_ejected "app/models/account.rb.tt",
+                                engine_path("app/models/accounts/account.rb")
+        template_unless_ejected "app/models/membership.rb.tt",
+                                engine_path("app/models/accounts/membership.rb")
+        template_unless_ejected "app/models/current.rb.tt",
+                                engine_path("app/models/accounts/current.rb")
+      end
+
+      def create_concerns
+        template_unless_ejected "lib/concerns/account_scoped.rb.tt",
+                                engine_path("lib/accounts/concerns/account_scoped.rb")
+        template_unless_ejected "lib/concerns/authorization.rb.tt",
+                                engine_path("lib/accounts/concerns/authorization.rb")
+      end
+
+      def create_migrations
+        template "db/migrate/create_accounts.rb.tt",
+                 engine_path("db/migrate/#{timestamp(0)}_create_accounts.rb")
+        template "db/migrate/create_accounts_memberships.rb.tt",
+                 engine_path("db/migrate/#{timestamp(1)}_create_accounts_memberships.rb")
+      end
+
+      def create_factories
+        template_unless_ejected "spec/factories/accounts.rb.tt",
+                                engine_path("spec/factories/accounts.rb")
+      end
+
+      def create_unit_specs
+        template_unless_ejected "spec/models/accounts/account_spec.rb.tt",
+                                engine_path("spec/models/accounts/account_spec.rb")
+        template_unless_ejected "spec/models/accounts/membership_spec.rb.tt",
+                                engine_path("spec/models/accounts/membership_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    - Accounts::AccountScoped\n    - Accounts::Authorization"
+        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.
+        # Auth::Identity is the canonical human; accounts membership
+        # is the per-tenant role row. The accounts engine specs DO
+        # exercise Auth::Identity directly (a Membership without an
+        # Identity to point at is meaningless), so we ship a slim
+        # stub at app/models/auth/identity.rb the same way the
+        # notifications engine does.
+        Seams::Generators::DummyAppWriter.write!(
+          engine_path: File.join(destination_root, "engines", ENGINE_NAME),
+          engine_module: "Accounts",
+          mount_at: "/accounts",
+          schema: dummy_schema,
+          host_user: dummy_host_identity,
+          host_user_path: "app/models/auth/identity.rb"
+        )
+        write_auth_current_stub
+        template "spec/runtime/accounts_boot_spec.rb.tt",
+                 engine_path("spec/runtime/accounts_boot_spec.rb")
+      end
+
+      # Write a tiny `Auth::Current` stub so the accounts engine specs
+      # (which read Current.identity) can run without pulling in the
+      # full auth engine.
+      def write_auth_current_stub
+        path = File.join(destination_root, "engines", ENGINE_NAME,
+                         "spec/dummy/app/models/auth/current.rb")
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, <<~RB)
+          # frozen_string_literal: true
+          # Slim Auth::Current stub for the accounts dummy app. Stands in
+          # for the real Auth::Current (which lives in the auth engine,
+          # not loaded by the dummy) so accounts specs can wire
+          # `Current.identity = identity` against the same surface area
+          # the canonical seams host uses.
+          module Auth
+            class Current < ActiveSupport::CurrentAttributes
+              attribute :identity
+            end
+          end
+        RB
+      end
+
+      def create_runtime_specs
+        # Currently a single runtime boot spec covers events, schema,
+        # create_with_owner, and Accounts::Current. Split into multiple
+        # files in a later phase if the file grows past ~120 lines.
+      end
+
+      def wire_into_host
+        # factory_bot_rails powers spec/factories/accounts.rb. Lives
+        # in the host's test group only.
+        host_inject_gem("factory_bot_rails", "~> 6.4", group: :test)
+        host_inject_mount(engine_class: "Accounts::Engine", at: "/accounts")
+        # NB: no host_inject_include_in_user — the host User is going
+        # away in Wave 9. Hosts that DO keep a User model wire it up
+        # themselves.
+      end
+
+      def report_summary
+        say ""
+        say "  Accounts engine generated at engines/accounts/", :green
+        say ""
+        say "  Next steps:", :yellow
+        say "    1. bin/rails db:migrate"
+        say "    2. Include Accounts::Authorization in your ApplicationController"
+        say "    3. Wire Accounts::Current.account in a before_action"
+        say "    4. Run the engine specs: bin/rails seams:test[accounts]"
+        say ""
+      end
+
+      private
+
+      def engine_path(relative)
+        File.join(destination_root, "engines", ENGINE_NAME, relative)
+      end
+
+      def timestamp(offset)
+        # Microsecond-resolution timestamp so migrations generated
+        # back-to-back don't collide. Offset by +50 so accounts'
+        # `accounts` + `accounts_memberships` tables migrate AFTER
+        # auth's `auth_identities` (+0..+3, since memberships address
+        # an Identity at the application layer) but BEFORE engines
+        # whose schemas depend on `accounts.id` semantically:
+        # notifications +100, billing +200, teams +300. Without this,
+        # billing's `subscriptions.account_id` would migrate before
+        # the `accounts` table existed — no DB-level FK so it's
+        # silent, but ordering matters if a host ever tightens to a
+        # real foreign-key constraint.
+        base = Time.now.utc.strftime("%Y%m%d%H%M%S").to_i
+        (base + 50 + offset).to_s
+      end
+
+      # Slim Auth::Identity stub for the dummy app. Stands in for the
+      # real Auth::Identity (which lives in the auth engine, not loaded
+      # by the dummy) so accounts specs can build an Identity for the
+      # owner-membership join. Includes has_secure_password so spec
+      # fixtures can pass `password:` like the real Identity accepts.
+      def dummy_host_identity
+        <<~RB
+          # frozen_string_literal: true
+          module Auth
+            class Identity < ApplicationRecord
+              self.table_name = "auth_identities"
+              has_secure_password
+            end
+          end
+        RB
+      end
+
+      def dummy_schema
+        # Includes auth_identities so factories that link memberships
+        # to an Identity can `create(:auth_identity)` against a real
+        # row. Match the auth engine's schema for that table so
+        # cross-engine specs don't drift.
+        <<~SCHEMA
+          enable_extension "pgcrypto"
+
+          create_table :auth_identities do |t|
+            t.text    :email,            null: false
+            t.string  :password_digest,  null: false
+            t.boolean :staff,            null: false, default: false
+            t.timestamps
+          end
+          add_index :auth_identities, :email, unique: true
+          add_index :auth_identities, :staff, where: "staff = true"
+
+          create_table :accounts, id: :uuid do |t|
+            t.string   :name,                 null: false
+            t.bigint   :external_account_id,  null: false
+            t.datetime :cancelled_at
+            t.datetime :incinerated_at
+            t.timestamps
+          end
+          add_index :accounts, :external_account_id, unique: true
+          add_index :accounts, :cancelled_at
+
+          create_table :accounts_memberships, id: :uuid do |t|
+            t.references :account, type: :uuid, null: false,
+                                   foreign_key: { to_table: :accounts }, index: false
+            t.bigint     :identity_id, null: true
+            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
+          # Wave 9 invariant: exactly one system actor per Account.
+          add_index :accounts_memberships, :account_id, unique: true,
+                    where: "role = 'system'",
+                    name: "index_accounts_memberships_one_system_per_account"
+        SCHEMA
+      end
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+# Accounts
+
+> Tenant boundary for a Seams-powered host application. Owns the
+> `Accounts::Account` (the workspace), `Accounts::Membership`
+> (Identity ↔ Account, with role), per-request `Accounts::Current`,
+> and the two concerns hosts need to scope their own data and
+> controllers to a tenant. Identity stays in the auth engine — this
+> engine never owns credentials.
+
+**Requires:** the `auth` engine. `Accounts::Membership.identity_id`
+joins to `auth_identities`; `Accounts::Current.account=` reads
+`Auth::Current.identity` to derive the matching Membership. Install
+auth before accounts.
+
+## Identity, Account, and Membership
+
+Three peer concepts, three tables, one clear responsibility each:
+
+| Model              | Owns                                                | Lives in                |
+| ---                | ---                                                 | ---                     |
+| `Auth::Identity`   | The human. Credentials, sessions, OAuth, API tokens. | `auth_identities` (auth engine) |
+| `Accounts::Account`| The workspace / tenant. Name + soft-cancel state.   | `accounts` (this engine) |
+| `Accounts::Membership` | The join. Says "Identity X is a Y in Account Z". | `accounts_memberships` (this engine) |
+
+The same `Auth::Identity` can have memberships in multiple Accounts
+with different roles. A Membership belongs to exactly one Account.
+
+## Why is `identity_id` nullable on Membership?
+
+System actors. Every Account ships with a `role: "system"` row whose
+`identity_id` is NULL. That row is the audit-log writer for changes
+that don't have a human behind them — background jobs syncing data
+from a webhook, scheduled tasks expiring trials, billing-engine
+hooks reconciling a subscription, etc.
+
+Without a system actor, every audit entry would either need a
+nullable `actor_id` (which is what the system row neatly avoids) or
+a fake "robot" Identity that lives nowhere else and confuses
+everything from email lookup to billing customer mapping.
+
+## Roles
+
+| Role     | identity_id   | Powers                                              |
+| ---      | ---           | ---                                                 |
+| `owner`  | required      | Full admin. Can manage members, billing, cancel the account. |
+| `admin`  | required      | Manages members and most settings; cannot remove an owner. |
+| `member` | required      | Default role. Read + write within the account's data scope. |
+| `system` | NULL          | Audit-log actor only. Never logs in. One per account.        |
+
+Every Account has exactly one system row (created automatically by
+`Account.create_with_owner`); humans get `owner` / `admin` /
+`member` rows.
+
+## `staff` vs `admin` — platform admin vs in-account admin
+
+These are different powers:
+
+- `Auth::Identity#staff?` — a boolean on the Identity row. Platform-level
+  super-user. Bypasses account scoping for support tooling
+  (impersonation, cross-account search). Set by an out-of-band admin
+  process; never via sign-up params.
+- `Accounts::Membership#admin?` — true when role is `owner` OR `admin`.
+  In-account admin. Manages the workspace's members and settings
+  but has no power outside this account.
+
+Use `ensure_staff` in controllers that span accounts.
+Use `ensure_admin` in controllers that manage one account.
+
+## Events emitted
+
+| Event name                       | Payload                                                                    |
+| ---                              | ---                                                                        |
+| `account.created.accounts`       | `{ account_id:, owner_identity_id: }`                                      |
+| `account.cancelled.accounts`     | `{ account_id:, cancelled_by_identity_id: }`                               |
+| `membership.created.accounts`    | `{ account_id:, membership_id:, identity_id:, role: }`                     |
+| `membership.role_changed.accounts` | `{ account_id:, membership_id:, from_role:, to_role:, changed_by_identity_id: }` |
+| `membership.removed.accounts`    | `{ account_id:, membership_id:, identity_id:, removed_by_identity_id: }`   |
+
+`identity_id` is the row id in the auth engine's `auth_identities`
+table. Subscribers (notifications, billing, etc.) resolve the human
+via Identity, never via a host User.
+
+## Events consumed
+
+This engine does not subscribe to any other engine's events.
+Downstream engines (notifications, billing, teams) publish and
+subscribe via `account_id` / `identity_id` carried on their event
+payloads.
+
+## Exposed concerns
+
+### `Accounts::AccountScoped` — model concern
+
+Mix into any model whose rows belong to a single Account:
+
+```ruby
+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 (default_scope)
+AuditEntry.unscoped.all            # opt out for cross-tenant queries
+```
+
+The default_scope is a no-op when `Accounts::Current.account` is
+unset, so background jobs that haven't bound a Current account see
+every row — wire `Accounts::Current.account =` into your job's
+`#perform` if you need scoping there.
+
+### `Accounts::Authorization` — controller concern
+
+Mix into the host's `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Accounts::Authorization
+  # default-on `before_action :ensure_account_access`
+end
+```
+
+Then opt out per-controller:
+
+```ruby
+class PublicPagesController < ApplicationController
+  disallow_account_scope          # public marketing
+end
+
+class OnboardingController < ApplicationController
+  require_access_without_membership  # signed in, no membership yet
+end
+```
+
+Plus two opt-in helpers any controller can call from its own `before_action`:
+
+- `ensure_admin` — checks `Accounts::Current.membership&.admin?`
+  (in-account owner OR admin)
+- `ensure_staff` — checks `Auth::Current.identity&.staff?`
+  (platform admin)
+
+## Per-request state — `Accounts::Current`
+
+The host wires `Accounts::Current.account` in a controller
+before_action. Setting `account=` automatically derives the
+matching `Membership` for the currently signed-in identity (read
+from `Auth::Current.identity`):
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :resolve_current_account
+
+  private
+
+  def resolve_current_account
+    Accounts::Current.account = current_account_from_url_or_session
+  end
+end
+
+# Anywhere downstream:
+Accounts::Current.account     # => Accounts::Account
+Accounts::Current.membership  # => Accounts::Membership for the signed-in human
+```
+
+## Account creation
+
+```ruby
+identity = Auth::Identity.create!(email: "ada@example.com", password: "...")
+owner    = Struct.new(:identity, :name).new(identity, "Ada Lovelace")
+
+account = Accounts::Account.create_with_owner(
+  account: { name: "Acme Corp" },
+  owner:   owner
+)
+
+account.memberships.pluck(:role) # => ["system", "owner"]
+```
+
+The system membership is mandatory — it's the audit-log actor for
+non-human changes. The owner membership is the human creating the
+account. Wrapped in a transaction; if any of the three inserts
+fail, all roll back.
+
+## Migration / setup steps
+
+1. Run the generator:
+   ```bash
+   bin/rails generate seams:accounts
+   ```
+2. Bundle install (no new gems, but locks the engine into the host).
+3. Migrate:
+   ```bash
+   bin/rails db:migrate
+   ```
+4. Mount in `config/routes.rb` (the generator does this automatically):
+   ```ruby
+   mount Accounts::Engine, at: "/accounts"
+   ```
+5. Wire `Accounts::Authorization` into your `ApplicationController`.
+
+## Mounting
+
+```ruby
+# config/routes.rb (host application)
+Rails.application.routes.draw do
+  mount Accounts::Engine, at: "/accounts"
+end
+```
+
+This engine ships **no controllers** intentionally. Hosts drive
+account-creation flows themselves (the shape of the sign-up wizard
+varies too much to template). Use `Accounts::Account.create_with_owner`
+from your own controller.
+
+## Running the specs
+
+```bash
+bin/rails seams:test[accounts]
+```

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

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Accounts
+  # The tenant boundary. One Account per "workspace" / "company" /
+  # "tenant" — every other engine that wants to scope its data to a
+  # tenant binds to this row.
+  #
+  # Identity (Auth::Identity) is the human; Account is the workspace;
+  # Membership joins them. The same human (Identity) can have
+  # memberships in multiple Accounts.
+  #
+  # UUID primary key (not bigint) so account ids can appear in
+  # shareable URLs without leaking row counts. The host User is gone
+  # post-Wave-9; downstream engines reference Identity (`identity_id`)
+  # or Account (`account_id`).
+  class Account < ApplicationRecord
+    self.table_name        = "accounts"
+    self.primary_key       = "id"
+    self.implicit_order_column = "created_at"
+
+    has_many :memberships, class_name: "Accounts::Membership",
+                           foreign_key: :account_id, dependent: :destroy
+
+    validates :name, presence: true
+
+    scope :active,    -> { where(cancelled_at: nil) }
+    scope :cancelled, -> { where.not(cancelled_at: nil) }
+
+    before_create :assign_external_account_id
+
+    after_create_commit :publish_account_created
+    after_update_commit :publish_account_cancelled, if: :saved_change_to_cancelled_at?
+
+    # Returns self so polymorphic helpers that expect `record.account`
+    # work uniformly across an Account row and any account-scoped row.
+    def account
+      self
+    end
+
+    def system_membership
+      memberships.find_by(role: "system")
+    end
+
+    def active?
+      cancelled_at.nil? && incinerated_at.nil?
+    end
+
+    def cancelled?
+      cancelled_at.present?
+    end
+
+    # Hard-delete grace period: a cancelled account becomes
+    # incinerated when the host job decides the grace window is up.
+    def incinerated?
+      incinerated_at.present?
+    end
+
+    # Wraps Account creation + System + Owner membership in a single
+    # transaction so the audit trail always has a System actor and the
+    # human creating the account has an Owner row.
+    #
+    #   Accounts::Account.create_with_owner(
+    #     account: { name: "Acme" },
+    #     owner:   identity_or_owner_struct
+    #   )
+    #
+    # `owner` must respond to `identity` and `name`. The Identity link
+    # is the human's row in `auth_identities`.
+    def self.create_with_owner(account:, owner:)
+      transaction do
+        record = create!(**account)
+        record.memberships.create!(
+          role:        "system",
+          name:        "System",
+          identity_id: nil,
+          active:      true
+        )
+        record.memberships.create!(
+          role:        "owner",
+          name:        owner.name,
+          identity_id: owner.identity.id,
+          verified_at: Time.current,
+          active:      true
+        )
+        record
+      end
+    end
+
+    private
+
+    def assign_external_account_id
+      self.external_account_id ||= self.class.next_external_account_id
+    end
+
+    # Per-class sequence so external_account_id stays unique without a
+    # DB-side sequence (UUID PKs make per-row IDs cheap, but
+    # external_account_id is a slug-friendly bigint). Hosts that want
+    # a different sequence can override this method.
+    def self.next_external_account_id
+      loop do
+        candidate = SecureRandom.random_number(2**62)
+        break candidate unless exists?(external_account_id: candidate)
+      end
+    end
+
+    def publish_account_created
+      Seams::Events::Publisher.publish(
+        "account.created.accounts",
+        account_id:        id,
+        owner_identity_id: memberships.where(role: "owner").pick(:identity_id)
+      )
+    end
+
+    def publish_account_cancelled
+      return if cancelled_at.nil?
+
+      Seams::Events::Publisher.publish(
+        "account.cancelled.accounts",
+        account_id:                  id,
+        cancelled_by_identity_id:    Accounts::Current.membership&.identity_id
+      )
+    end
+  end
+end

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

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

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Accounts
+  # ActiveSupport::CurrentAttributes namespace for the Accounts engine.
+  # Set once per request by the host (typically a before_action that
+  # resolves the account from the URL or session); readable from
+  # anywhere downstream without explicit threading.
+  #
+  # Setting `account=` automatically derives the matching Membership
+  # for the currently signed-in identity (read from `Auth::Current`).
+  # The cross-engine read into `Auth::Current.identity` is intentional:
+  # the auth and accounts engines each own a per-request namespace;
+  # the accounts engine reads identity to figure out which membership
+  # is "current" but never writes to `Auth::Current`.
+  #
+  # Contract: `Auth::Current.identity` MUST be set before
+  # `Accounts::Current.account =`. Hosts wire this in their
+  # ApplicationController after their authentication concern runs.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :account, :membership
+
+    def account=(value)
+      super(value)
+      self.membership =
+        if value && defined?(Auth::Current) && Auth::Current.identity
+          value.memberships.find_by(identity_id: Auth::Current.identity.id)
+        end
+    end
+
+    def with_account(value, &)
+      with(account: value, &)
+    end
+
+    def without_account(&)
+      with(account: nil, membership: nil, &)
+    end
+  end
+end