seams 0.1.0

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/notification_policy.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Admin
+  module Tenant
+    # Tenant-mode policy for Notifications::Notification. Filters by
+    # `account_id`. The canonical seams `notifications` table is
+    # polymorphically owned (`owner_type`/`owner_id`) and doesn't
+    # carry `account_id`. The default falls back to `scope.none` if
+    # the column is absent — fail-closed. Hosts whose Notification
+    # model uses the polymorphic shape (or a custom direct
+    # `account_id` column) eject this policy and rewrite `resolve` to
+    # join through the owning model.
+    class NotificationPolicy < ApplicationPolicy
+      class Scope < ApplicationPolicy::Scope
+        def resolve
+          return scope.all if staff?
+          return scope.none if account_id.nil?
+          return scope.none unless account_id_column_present?
+
+          scope.where(account_id: account_id)
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/notification_preference_policy.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Admin
+  module Tenant
+    # Tenant-mode policy for Notifications::NotificationPreference.
+    # Filters by `account_id`. NotificationPreference rows are tied to
+    # an Identity, but Identities can span Accounts. Hosts that carry
+    # `account_id` directly on the preference row pick up this policy
+    # as-is; hosts whose schema lacks the column fall through to
+    # `scope.none` (fail-closed) and are expected to eject + rewrite.
+    class NotificationPreferencePolicy < ApplicationPolicy
+      class Scope < ApplicationPolicy::Scope
+        def resolve
+          return scope.all if staff?
+          return scope.none if account_id.nil?
+          return scope.none unless account_id_column_present?
+
+          scope.where(account_id: account_id)
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/plan_policy.rb.tt

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Admin
+  module Tenant
+    # Tenant-mode policy for Billing::Plan.
+    #
+    # Plans are global product rows, not account-scoped — the
+    # `billing_plans` table carries no `account_id` column. Tenant
+    # admins typically need to **see** the catalogue of available plans
+    # (so they can switch their Subscription) but should not create or
+    # edit them. The default here keeps the catalogue readable to any
+    # account-admin and falls back to the staff? gate for writes.
+    #
+    # `Scope#resolve` returns `scope.all` because the catalogue is
+    # global — there is no `account_id` to filter by. Hosts that mark
+    # plans private to specific accounts eject and add the filter.
+    class PlanPolicy < ApplicationPolicy
+      def create?
+        user&.identity&.staff?
+      end
+
+      def update?
+        user&.identity&.staff?
+      end
+
+      def destroy?
+        user&.identity&.staff?
+      end
+
+      class Scope < ApplicationPolicy::Scope
+        # Plans are global; tenant admins see the catalogue.
+        def resolve
+          scope.all
+        end
+      end
+
+      private
+
+      # Plans are global; per-record tenant guard always passes for
+      # the read actions, and the write actions short-circuit on the
+      # staff? predicates above.
+      def record_in_tenant_scope?
+        true
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/subscription_policy.rb.tt

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Admin
+  module Tenant
+    # Tenant-mode policy for Billing::Subscription. Filters by
+    # `account_id`. The `billing_subscriptions` table carries the
+    # column directly in the canonical seams schema. The
+    # column-presence guard is defensive for hosts whose schema
+    # differs.
+    class SubscriptionPolicy < ApplicationPolicy
+      class Scope < ApplicationPolicy::Scope
+        def resolve
+          return scope.all if staff?
+          return scope.none if account_id.nil?
+          return scope.none unless account_id_column_present?
+
+          scope.where(account_id: account_id)
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/team_policy.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Admin
+  module Tenant
+    # Tenant-mode policy for Teams::Team. Filters by `account_id`.
+    #
+    # Hosts whose Team model is NOT account-scoped (e.g. teams that
+    # span accounts, or whose schema has not been migrated to add
+    # `account_id` to `teams`) eject this policy and replace `resolve`
+    # with a join through Teams::Membership or whatever the host's
+    # tenant boundary is.
+    #
+    # Without an `account_id` column the default `Scope#resolve`
+    # returns `scope.none` rather than crashing on
+    # `PG::UndefinedColumn` — fail closed.
+    class TeamPolicy < ApplicationPolicy
+      class Scope < ApplicationPolicy::Scope
+        def resolve
+          return scope.all if staff?
+          return scope.none if account_id.nil?
+          return scope.none unless account_id_column_present?
+
+          scope.where(account_id: account_id)
+        end
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/app/policies/admin/tenant/teams_membership_policy.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Admin
+  module Tenant
+    # Tenant-mode policy for Teams::Membership. Filters by `account_id`.
+    #
+    # The canonical seams `team_memberships` table doesn't carry
+    # `account_id` directly (memberships are scoped through their
+    # Team). The default falls back to `scope.none` if the column is
+    # absent — fail-closed. Hosts whose schema differs eject this
+    # policy and replace `resolve` with a join through Teams::Team.
+    class TeamsMembershipPolicy < ApplicationPolicy
+      class Scope < ApplicationPolicy::Scope
+        def resolve
+          return scope.all if staff?
+          return scope.none if account_id.nil?
+          return scope.none unless account_id_column_present?
+
+          scope.where(account_id: account_id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Routes for the seams admin engine. Phase 2 ships full CRUD route
+# surfaces for the twelve canonical seams models. Each `resources`
+# line points at a controller under `app/controllers/admin/<plural>`
+# (single-namespace `Admin::*` controllers, matching Administrate's
+# convention) — the controllers themselves subclass
+# Seams::Admin::ApplicationController so the gate, the pundit_user
+# hook, and Phase 3's audit-log auto-write apply uniformly.
+Seams::Admin::Engine.routes.draw do
+  # Follow-up generators that add admin sections (impersonation, bulk-action endpoints, etc.) splice their routes here, ahead of the dashboard resources Phase 2 ships.
+  # seams:insertion-point admin.routes.before_resources
+
+  # Phase 2 dashboards. Per Administrate convention, each resource
+  # gets a full CRUD route surface (index, show, new, create, edit,
+  # update, destroy). The `controller:` option points at the
+  # engine-prefixed controllers under app/controllers/admin/.
+  resources :identities,             controller: "admin/identities"
+  resources :accounts,               controller: "admin/accounts"
+  resources :accounts_memberships,   controller: "admin/accounts_memberships"
+  resources :teams,                  controller: "admin/teams"
+  resources :teams_memberships,      controller: "admin/teams_memberships"
+  resources :invitations,            controller: "admin/invitations"
+  resources :notifications,          controller: "admin/notifications"
+  resources :notification_preferences, controller: "admin/notification_preferences"
+  resources :plans,                  controller: "admin/plans"
+  resources :subscriptions,          controller: "admin/subscriptions"
+  resources :invoices,               controller: "admin/invoices"
+  resources :lifetime_passes,        controller: "admin/lifetime_passes"
+
+  # Follow-up generators that add NEW route surfaces (custom collection routes, JSON-only endpoints) splice their resources here.
+  # seams:insertion-point admin.routes.after_resources
+
+  # Default landing page so visiting `/admin` lands somewhere
+  # meaningful. Identities is the natural index — the operator
+  # console use case starts with "find this user".
+  root to: "admin/identities#index"
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "admin/configuration"
+require "admin/context"
+require "admin/engine"
+require "admin/concerns/authenticator"
+
+# Engine root for the seams admin engine. Namespaces under
+# `Seams::Admin` (rather than top-level `Admin`) so the host's own
+# `app/admin/...` code does not collide with the engine's controllers,
+# dashboards, or policies. The path layout under engines/admin/lib/
+# uses the short `admin/...` form for grep-friendliness; constants
+# live under `Seams::Admin::*`.
+module Seams
+  module Admin
+    class Error < StandardError; end
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      # Convenience alias matching how the host reads it in
+      # initializers and controller before-actions:
+      #
+      #   Seams::Admin.config.authenticator.call(self)
+      def config
+        configuration
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/lib/concerns/authenticator.rb.tt

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Seams
+  module Admin
+    # Controller concern mixed into the admin engine's
+    # `Seams::Admin::ApplicationController`. Gates every admin request
+    # on `Seams::Admin.config.authenticator` and runs the optional
+    # `before_admin_action` hook (2FA, IP allow-list, etc.) before the
+    # action itself.
+    #
+    # This is the public seam Phase 3 builds Pundit policies on top of.
+    # Phase 1 ships the gate only; Phase 3 fills in the
+    # `pundit_user` / `policy_namespace` cooperation so resource-level
+    # authorisation kicks in after the gate.
+    module Authenticator
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :authenticate_admin!
+        before_action :run_before_admin_action_hook
+      end
+
+      private
+
+      def authenticate_admin!
+        return if admin_authenticator_call
+
+        respond_with_admin_forbidden(<<~MSG.strip)
+          Access denied. The seams admin surface is gated on
+          `Seams::Admin.config.authenticator`; the configured callable
+          returned a falsey value for this request. Default gate:
+          `current_identity&.staff?`. Override the authenticator in
+          config/initializers/seams_admin.rb if your host uses a
+          different signal.
+        MSG
+      end
+
+      def run_before_admin_action_hook
+        hook = ::Seams::Admin.config.before_admin_action
+        return if hook.nil?
+
+        hook.call(self)
+      end
+
+      def admin_authenticator_call
+        gate = ::Seams::Admin.config.authenticator
+        # Defensive: a misconfigured host that nils the gate locks
+        # admin closed rather than wide-open. "Fail-closed" is the
+        # only sane default for an admin surface.
+        return false unless gate.respond_to?(:call)
+
+        gate.call(self)
+      end
+
+      def respond_with_admin_forbidden(message)
+        if respond_to?(:render)
+          render plain: message, status: :forbidden
+        else
+          head :forbidden
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Seams
+  module Admin
+    # Engine-scoped configuration for the admin surface. Override in
+    # config/initializers/seams_admin.rb of the host application:
+    #
+    #   Seams::Admin.configure do |c|
+    #     c.authenticator       = ->(ctrl) { ctrl.current_identity&.platform_admin? }
+    #     c.tenancy_scope       = :tenant       # default :platform
+    #     c.theme_css_path      = "admin/seams_brand.css"
+    #     c.before_admin_action = ->(ctrl) { ctrl.require_2fa! }
+    #   end
+    #
+    # Four knobs, deliberately small:
+    #
+    # - `authenticator` — callable taking the controller, returning
+    #   truthy when the request is allowed into the admin engine.
+    #   Default: `staff?` on the current Identity. Hosts that don't
+    #   carry `staff?` on Identity (custom flags, role tables, etc.)
+    #   override this.
+    #
+    # - `tenancy_scope` — `:platform` (Wave 11A default — see all
+    #   accounts) or `:tenant` (scope to `current_membership.account_id`,
+    #   wired in Phase 3 via Pundit policy_namespace). Phase 1 only
+    #   stores the value; Phase 3 reads it.
+    #
+    # - `theme_css_path` — host-supplied admin restyle. Loaded on top
+    #   of Administrate's stock CSS so the admin UI carries the host's
+    #   brand. nil means "use Administrate's defaults".
+    #
+    # - `before_admin_action` — callable that runs before every admin
+    #   action. The recommended hook for 2FA enforcement, IP allow-list
+    #   checks, audit-trail entry-point logging, etc. Phase 1 calls it
+    #   if set; Phase 1 ships no default behaviour beyond the gate.
+    #
+    # - `current_membership_resolver` — callable taking the controller,
+    #   returning the active `Accounts::Membership` for tenant-mode
+    #   policy decisions. Default reads `Accounts::Current.membership`
+    #   (Wave 9's CurrentAttributes object). Hosts that resolve the
+    #   active membership differently (custom membership classes, a
+    #   Devise/Doorkeeper-style "current_account" pattern, multiple
+    #   memberships per request, etc.) override this in the host
+    #   initializer rather than ejecting the application controller.
+    class Configuration
+      attr_accessor :authenticator,
+                    :tenancy_scope,
+                    :theme_css_path,
+                    :before_admin_action,
+                    :current_membership_resolver
+      # Follow-up generators that add knobs (impersonation_audit_logger,
+      # session_timeout, etc.) declare their attr_accessor here.
+      # seams:insertion-point admin.configuration.attributes
+
+      def initialize
+        # Default authenticator: the current Identity must carry the
+        # `staff` flag. Hosts that need a finer-grained gate (per-
+        # account admin role, IP allow-list, etc.) override this.
+        @authenticator = ->(controller) { controller.current_identity&.staff? }
+
+        # :platform → admins see every Account's data. :tenant → admins
+        # are scoped to the Account they're a member of. Phase 3 reads
+        # this; Phase 1 just stores it.
+        @tenancy_scope = :platform
+
+        # nil → Administrate's stock CSS only.
+        @theme_css_path = nil
+
+        # nil → no extra before-action; only the authenticator gate
+        # runs. Hosts wire 2FA / IP allow-list here.
+        @before_admin_action = nil
+
+        # Default current-membership resolver: read
+        # `Accounts::Current.membership` (Wave 9). Returns nil when
+        # the constant isn't loaded so platform-only hosts (no accounts
+        # engine) don't NameError. Hosts that store the active
+        # membership elsewhere assign their own callable here.
+        @current_membership_resolver = lambda do |_controller|
+          next nil unless defined?(::Accounts::Current)
+
+          ::Accounts::Current.membership
+        rescue NoMethodError
+          nil
+        end
+        # Follow-up generators that add defaults for new attributes (matching admin.configuration.attributes) splice them here.
+        # seams:insertion-point admin.configuration.defaults
+      end
+    end
+  end
+end

data/lib/generators/seams/admin/templates/lib/context.rb.tt

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Seams
+  module Admin
+    # The value `Seams::Admin::ApplicationController#pundit_user`
+    # returns. Wraps the current Auth::Identity together with the
+    # current Accounts::Membership so a Pundit policy can read both
+    # signals (staff? on the Identity, role/account_id on the
+    # Membership) without the policy having to know how to fish either
+    # out of the controller.
+    #
+    # Why a Struct, not the raw Identity? In tenant mode the policies
+    # need to filter by `account_id`, which lives on the Membership,
+    # not the Identity. Pundit's `pundit_user` is a single value, so
+    # we wrap. Hosts that don't carry an Accounts::Membership concept
+    # (single-tenant apps, platform-only admins) leave `membership` nil
+    # and the Identity's `staff?` carries the gate alone.
+    #
+    # Both fields are nil-safe in every policy — the platform policies
+    # only read `identity&.staff?`, the tenant policies fall through to
+    # `scope.none` when membership is nil.
+    Context = Struct.new(:identity, :membership) do
+      # Convenience: a policy that wants to call `user.staff?` rather
+      # than `user.identity&.staff?` can. Mirrors the bare-Identity
+      # surface so policies stay readable when only the Identity
+      # matters.
+      def staff?
+        identity&.staff?
+      end
+
+      # Convenience: same idea on the Membership side. A policy that
+      # only cares about the role can call `user.role` instead of
+      # `user.membership&.role`.
+      def role
+        membership&.role
+      end
+
+      # Convenience: same idea on the Membership side for account_id.
+      def account_id
+        membership&.account_id
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Seams
+  module Admin
+    class Engine < ::Rails::Engine
+      isolate_namespace Seams::Admin
+
+      # Engine is rooted at engines/admin/. Rails picks up app/, config/,
+      # db/migrate/ etc. from the engine root by convention. lib/ is on
+      # $LOAD_PATH but not Zeitwerk-managed — sub-files under lib/admin/
+      # are explicit `require`s from lib/admin.rb.
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      initializer "admin.register_events" do
+        # Phase 1 ships no admin-specific events. Phase 3 adds an
+        # `admin.action.taken.admin` event when the audit-log auto-write
+        # lands. Follow-up generators (e.g. seams:admin:add_dashboard)
+        # may register events here.
+        # Follow-up generators that emit new admin events register them here.
+        # seams:insertion-point admin.engine.events
+      end
+
+      initializer "admin.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
+
+      # Boot-time dependency assertion. The admin engine's default
+      # authenticator reads `current_identity&.staff?`, and Phase 2
+      # dashboards target Auth::Identity / Accounts::Account /
+      # Accounts::Membership. Without auth, the engine cannot gate; we
+      # fail loud at boot rather than at first request so the operator
+      # gets a clear "install seams:auth" error instead of a deep
+      # NameError mid-request.
+      #
+      # Administrate is checked too: the engine's ApplicationController
+      # subclasses Administrate::ApplicationController — without the
+      # gem in the host's Gemfile the constant doesn't exist.
+      config.after_initialize do
+        missing = []
+        missing << "Auth::Identity (run: bin/rails generate seams:auth)" unless defined?(::Auth::Identity)
+        missing << "Administrate (add `gem \"administrate\"` to Gemfile)" unless defined?(::Administrate)
+        missing << "Pundit (add `gem \"pundit\"` to Gemfile)" unless defined?(::Pundit)
+
+        if missing.any?
+          raise <<~MSG
+            [seams admin] missing required dependency:
+                #{missing.join("\n              ")}
+
+            The admin engine builds dashboards on top of Administrate,
+            gates them on Auth::Identity#staff?, and authorises
+            individual records via Pundit policies under
+            Admin::Platform::* and Admin::Tenant::*. It cannot run
+            without all three. Generate the auth engine and ensure
+            both administrate + pundit are in the host Gemfile, or
+            remove admin with
+            `bin/rails generate seams:remove admin --force`.
+          MSG
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Factories for the seams admin engine. Phase 1 ships no factories —
+# the boot spec uses Auth::Identity directly via `create!`. Phase 2
+# adds factories per dashboard if specs need fixture variants
+# (an Identity with staff: true, a Membership with role: admin, etc.)
+# beyond what the auth + accounts engines already ship.
+FactoryBot.define do
+  # Phase 2: factories go here.
+end