seams 0.1.0

data/lib/generators/seams/teams/templates/db/migrate/create_team_memberships.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# What: creates the team_memberships join table.
+# Why:  many-to-many between teams and Auth::Identity rows, plus a
+#       role column (owner / admin / member) for cheap RBAC. Teams
+#       are peers to Accounts post-Wave-9, so the join is to Identity
+#       directly — not to an Accounts::Membership.
+# Risk: append-mostly. Unique index on (team_id, identity_id) prevents
+#       duplicate memberships. No FK to auth_identities because the
+#       auth and teams engines may live in different schemas /
+#       databases in production — cross-engine integrity is enforced
+#       at the application layer.
+class CreateTeamMemberships < ActiveRecord::Migration[7.1]
+  def change
+    create_table :team_memberships do |t|
+      t.references :team,        null: false, foreign_key: { to_table: :teams }, index: true
+      t.bigint     :identity_id, null: false
+      t.string     :role,        null: false, default: "member"
+      t.timestamps
+    end
+
+    add_index :team_memberships, %i[team_id identity_id], unique: true
+    add_index :team_memberships, :identity_id
+  end
+end

data/lib/generators/seams/teams/templates/db/migrate/create_teams.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# What: creates the teams table for the Teams engine.
+# Why:  the Team is the unit of multi-tenant ownership (billing
+#       customer, project scope, RBAC root) — every host that mounts
+#       Teams::Engine needs it.
+# Risk: empty on creation, append-mostly thereafter.
+class CreateTeams < ActiveRecord::Migration[7.1]
+  def change
+    create_table :teams do |t|
+      t.string :name, null: false
+      t.string :slug, null: false
+      t.timestamps
+    end
+
+    add_index :teams, :slug, unique: true
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Teams
+  # Mix into any model whose rows belong to a single team. Sets up
+  # the belongs_to + a default_scope that filters to
+  # `Teams::Current.team`. When `Teams::Current.team` is unset the
+  # scope returns `none` (an empty relation) — see "fail-closed"
+  # below.
+  #
+  #   class Project < ApplicationRecord
+  #     include Teams::AccountScoped
+  #   end
+  #
+  #   Teams::Current.team = team
+  #   Project.create!(name: "...")  # team_id auto-assigned to team.id
+  #   Project.all                   # only team's projects
+  #
+  # Pairs with Core's `TenantScoped` — same shape, different ownership
+  # model: TenantScoped binds to the host's tenant abstraction;
+  # AccountScoped binds specifically to a Teams::Team.
+  #
+  # ### Fail-closed default
+  #
+  # When `Teams::Current.team` is nil, the default_scope returns
+  # `none` rather than `all`. Same rationale as Accounts::AccountScoped:
+  # the alternative (return all rows across all teams when no team is
+  # bound) is the canonical multi-team data-leak bug. 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.
+  #   * `.with_no_team_scope`     — drops the team_id filter only,
+  #                                 preserves any other default_scopes.
+  #
+  # Background jobs MUST set `Teams::Current.team =` before querying,
+  # or call `.with_no_team_scope` explicitly.
+  module AccountScoped
+    extend ActiveSupport::Concern
+
+    included do
+      belongs_to :team, class_name: "Teams::Team"
+
+      # The default_scope ALWAYS applies a where(:team_id) clause —
+      # either filtered to the current team, or filtered to a
+      # never-matching sentinel (`team_id IS NULL`). This shape lets
+      # `unscope(where: :team_id)` in `with_no_team_scope` reverse the
+      # filter cleanly; using `none` here would create a NullRelation
+      # that `unscope` cannot un-do.
+      default_scope -> {
+        team = Teams::Current.team
+        if team
+          where(team_id: team.id)
+        else
+          where(team_id: nil)
+        end
+      }
+      before_validation :assign_current_team, on: :create
+    end
+
+    class_methods do
+      # Returns the relation as it would be without the team_id
+      # filter, 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_team_scope
+        unscope(where: :team_id)
+      end
+    end
+
+    private
+
+    def assign_current_team
+      self.team_id ||= Teams::Current.team&.id if Teams::Current.team
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Teams
+  # Helpers for controllers that need to enforce team-membership
+  # checks. Mix in by default in TeamsController/MembershipsController/
+  # InvitationsController so the engine ships with safe defaults.
+  # Hosts can override the predicates by re-opening the concern.
+  #
+  # Resolves the current Identity via `current_identity_id`, which by
+  # default reads `Auth::Current.identity` (the Auth engine's
+  # per-request namespace). Hosts can override `current_identity_id`
+  # to plug in a different resolver.
+  module Authorization
+    extend ActiveSupport::Concern
+
+    private
+
+    def require_team_member!
+      head :forbidden and return false unless team_member?
+      true
+    end
+
+    def require_team_admin!
+      head :forbidden and return false unless team_admin?
+      true
+    end
+
+    def team_member?
+      return false unless current_identity_id && @team
+
+      Teams::Membership.exists?(team_id: @team.id, identity_id: current_identity_id)
+    end
+
+    def team_admin?
+      return false unless current_identity_id && @team
+
+      Teams::Membership.where(team_id: @team.id, identity_id: current_identity_id, role: %w[owner admin]).exists?
+    end
+
+    # Resolves the signed-in human's id from `Auth::Current.identity`
+    # (the Auth engine's per-request namespace). Gated on
+    # `defined?(Auth::Current)` so the concern remains include-safe in
+    # hosts that don't ship the auth engine. Hosts that wire auth
+    # differently override this method.
+    def current_identity_id
+      if defined?(Auth::Current) && Auth::Current.respond_to?(:identity) && Auth::Current.identity
+        return Auth::Current.identity.id
+      end
+
+      nil
+    end
+  end
+end

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Teams
+  # Engine-scoped configuration. Override in
+  # config/initializers/teams.rb of the host application.
+  class Configuration
+    attr_accessor :invitation_ttl, :max_members_per_team
+    attr_writer   :host_url, :invitation_mailer_from
+    # Follow-up generators that add knobs (slug_generator, archive_grace_period) declare their attr_accessor here.
+    # seams:insertion-point teams.configuration.attributes
+
+    def initialize
+      @invitation_ttl         = 7 * 24 * 60 * 60  # 7 days, in seconds
+      @max_members_per_team   = nil               # nil = unlimited
+      @invitation_mailer_from = nil
+      @host_url               = nil
+    end
+
+    # `host_url` is used to build the invitation accept link. Without
+    # it, invitation emails would carry a link to nowhere, so we raise
+    # at the first read rather than ship a broken email. Set in
+    # config/initializers/teams.rb.
+    def host_url
+      return @host_url if @host_url
+
+      raise Teams::ConfigurationError,
+            "Teams.configuration.host_url is not set. Add\n" \
+            "  Teams.configure { |c| c.host_url = \"https://your-app.com\" }\n" \
+            "to config/initializers/teams.rb so invitation emails can " \
+            "build the accept URL."
+    end
+
+    # `invitation_mailer_from` is the From: header on invitation emails.
+    # Same shape as `host_url` — nil-default, raises on read so the
+    # host can't accidentally ship mail from "no-reply@example.com".
+    def invitation_mailer_from
+      return @invitation_mailer_from if @invitation_mailer_from
+
+      raise Teams::ConfigurationError,
+            "Teams.configuration.invitation_mailer_from is not set. Add\n" \
+            "  Teams.configure { |c| c.invitation_mailer_from = \"team@your-app.com\" }\n" \
+            "to config/initializers/teams.rb."
+    end
+  end
+end

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

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Teams
+  class Engine < ::Rails::Engine
+    isolate_namespace Teams
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    initializer "teams.register_events" do
+      Seams::EventRegistry.register("team.created.teams",          emitted_by: "Teams")
+      Seams::EventRegistry.register("team.member_joined.teams",    emitted_by: "Teams")
+      Seams::EventRegistry.register("team.member_left.teams",      emitted_by: "Teams")
+      Seams::EventRegistry.register("invitation.sent.teams",       emitted_by: "Teams")
+      Seams::EventRegistry.register("invitation.accepted.teams",   emitted_by: "Teams")
+      # Follow-up generators that emit new teams events (team.archived.teams, invitation.revoked.teams) register them here.
+      # seams:insertion-point teams.engine.events
+    end
+
+    initializer "teams.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
+
+    config.after_initialize do
+      # Boot-time dependency assertion. Teams::Membership.identity_id
+      # references auth_identities; without auth the team membership
+      # rows are dangling. We enforce at boot so the operator gets a
+      # clear "install seams:auth" error rather than a NULL identity_id
+      # surprise on first query.
+      unless defined?(::Auth::Identity)
+        raise <<~MSG
+          [seams teams] missing required cross-engine dependency:
+              Auth::Identity (run: bin/rails generate seams:auth)
+
+          The teams engine joins identity_id to auth_identities; it
+          cannot run without auth. Generate the auth engine, or
+          remove teams with `bin/rails generate seams:remove teams --force`.
+        MSG
+      end
+
+      Teams::InvitationSubscriber.attach!
+      # Follow-up generators that ship subscribers (Teams::AccountSubscriber.attach!, etc.) splice their attach! calls here.
+      # seams:insertion-point teams.engine.subscribers
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "teams/version"
+require "teams/configuration"
+require "teams/engine"
+require "teams/concerns/authorization"
+
+module Teams
+  class Error               < StandardError; end
+  class AuthorizationError  < Error; end
+  class ConfigurationError  < Error; end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Factories for Teams engine specs. Sequences keep names unique
+# across the spec run so uniqueness validations don't trip.
+#
+# `:team_membership` associates with the auth engine's
+# `:auth_identity` factory — ensure the auth_identities table is
+# present in the engine's dummy schema (it is, see
+# `TeamsGenerator#dummy_schema`).
+FactoryBot.define do
+  factory :team, class: "Teams::Team" do
+    sequence(:name) { |n| "Team #{n}" }
+    sequence(:slug) { |n| "team-#{n}" }
+  end
+
+  factory :team_membership, class: "Teams::Membership" do
+    association :team
+    role { "member" }
+
+    # Denormalises identity_id from a built/created :auth_identity
+    # rather than relying on belongs_to magic — Membership has no
+    # `belongs_to :identity` because Auth::Identity lives in a peer
+    # engine (no cross-engine model access at the ActiveRecord level,
+    # per the Seams/NoCrossEngineModelAccess cop). Hosts call
+    # `create(:team_membership, identity: existing_identity)` or pass
+    # `identity_id:` directly.
+    transient do
+      identity { nil }
+    end
+
+    after(:build) do |membership, evaluator|
+      membership.identity_id ||= evaluator.identity&.id || FactoryBot.create(:auth_identity).id
+    end
+
+    factory :team_admin_membership do
+      role { "admin" }
+    end
+  end
+
+  factory :team_invitation, class: "Teams::Invitation" do
+    association :team
+    sequence(:email) { |n| "invitee-#{n}@example.com" }
+    role       { "member" }
+    token      { SecureRandom.hex(16) }
+    expires_at { 7.days.from_now }
+  end
+end

data/lib/generators/seams/teams/templates/spec/models/invitation_spec.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Teams::Invitation do
+  let(:team) { Teams::Team.create!(name: "Acme") }
+
+  it "auto-assigns a token and expiry" do
+    inv = team.invitations.create!(email: "x@y.com", role: "member")
+    expect(inv.token).to be_present
+    expect(inv.expires_at).to be > Time.current
+  end
+
+  it "is expired once expires_at passes" do
+    inv = team.invitations.create!(email: "x@y.com", role: "member", expires_at: 1.minute.ago)
+    expect(inv).to be_expired
+  end
+
+  it "rejects two pending invitations to the same email for the same team" do
+    team.invitations.create!(email: "x@y.com", role: "member")
+    expect do
+      team.invitations.create!(email: "x@y.com", role: "admin")
+    end.to raise_error(ActiveRecord::RecordNotUnique)
+  end
+end

data/lib/generators/seams/teams/templates/spec/models/membership_spec.rb.tt

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Teams::Membership do
+  let(:team) { Teams::Team.create!(name: "Acme") }
+
+  it "rejects unknown roles" do
+    m = described_class.new(team: team, identity_id: 1, role: "made_up")
+    expect(m).not_to be_valid
+  end
+
+  it "is unique on (team_id, identity_id)" do
+    described_class.create!(team: team, identity_id: 1, role: "member")
+    dup = described_class.new(team: team, identity_id: 1, role: "admin")
+    expect(dup).not_to be_valid
+  end
+
+  describe "#admin?" do
+    it "is true for owner and admin roles" do
+      expect(described_class.new(role: "owner")).to be_admin
+      expect(described_class.new(role: "admin")).to be_admin
+    end
+
+    it "is false for member" do
+      expect(described_class.new(role: "member")).not_to be_admin
+    end
+  end
+end

data/lib/generators/seams/teams/templates/spec/models/team_spec.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Teams::Team do
+  describe "validations" do
+    it "requires a name" do
+      expect(described_class.new(name: "")).not_to be_valid
+    end
+
+    it "auto-assigns slug from name" do
+      team = described_class.new(name: "My Team!")
+      team.valid?
+      expect(team.slug).to eq("my-team")
+    end
+
+    it "rejects duplicate slugs" do
+      described_class.create!(name: "Acme")
+      dup = described_class.new(name: "Acme")
+      expect(dup).not_to be_valid
+    end
+  end
+end

data/lib/generators/seams/teams/templates/spec/runtime/boot_spec.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "../rails_helper"
+
+RSpec.describe "Teams engine boot", type: :integration do
+  it "loads the engine" do
+    expect(defined?(Teams::Engine)).to eq("constant")
+  end
+
+  it "registers the five canonical team events" do
+    %w[
+      team.created.teams
+      team.member_joined.teams
+      team.member_left.teams
+      invitation.sent.teams
+      invitation.accepted.teams
+    ].each do |event|
+      expect(Seams::EventRegistry.registered?(event)).to be(true)
+    end
+  end
+
+  it "creates the team tables from the dummy schema" do
+    %i[teams team_memberships team_invitations].each do |t|
+      expect(ActiveRecord::Base.connection.table_exists?(t)).to be(true), "missing #{t}"
+    end
+  end
+
+  it "creates a Team and auto-assigns a slug" do
+    team = Teams::Team.create!(name: "Acme Corp")
+    expect(team.slug).to eq("acme-corp")
+  end
+end

data/lib/seams/cli/list.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "seams"
+
+module Seams
+  module CLI
+    # Implementation behind `bin/rails seams:list` — discovers every
+    # engine under engines/, looks up its registered events in
+    # Seams::EventRegistry, and prints a summary.
+    class List
+      DEFAULT_ENGINES_ROOT = "engines"
+
+      MODULE_DECLARATION = /\bmodule\s+([A-Z][A-Za-z0-9_]*)\b/
+
+      def initialize(engines_root: DEFAULT_ENGINES_ROOT, output: $stdout)
+        @engines_root = engines_root
+        @output       = output
+      end
+
+      def call
+        engines = discover_engines
+        @output.puts("seams: #{engines.size} engine(s) installed")
+
+        if engines.empty?
+          @output.puts("  (no engines — generate one with `bin/rails generate seams:engine <name>`)")
+          return
+        end
+
+        engines.each { |engine| print_engine(engine) }
+      end
+
+      private
+
+      def discover_engines
+        return [] unless Dir.exist?(@engines_root)
+
+        Dir.children(@engines_root)
+           .select { |child| File.directory?(File.join(@engines_root, child)) }
+           .reject { |child| child.start_with?(".") }
+           .sort
+      end
+
+      def print_engine(name)
+        @output.puts("  - #{name}")
+        events_for(name).each        { |event| @output.puts("      emits:      #{event}") }
+        subscriptions_for(name).each { |event| @output.puts("      subscribes: #{event}") }
+        depends_on(name).each        { |dep|   @output.puts("      depends on: #{dep}") }
+      end
+
+      def events_for(name)
+        module_name = module_name_for(name)
+        events      = Seams::EventRegistry.all.select { |_, owner| owner.to_s == module_name }.keys
+        events.empty? ? ["(no events)"] : events
+      end
+
+      # Returns the event names this engine subscribes to. Looks in
+      # both the engine.rb itself AND in `app/subscribers/**/*.rb` —
+      # the canonical seams convention, where each subscriber class
+      # calls `Publisher.attach_class(KEY, "event.name", ...)` (or the
+      # legacy `attach_once`) from an `attach!` class method that the
+      # engine's `config.after_initialize` block invokes. Without
+      # scanning `app/subscribers/` this method silently reported zero
+      # subscribers for every generated engine, hiding the
+      # cross-engine dependency graph this command exists to surface.
+      def subscriptions_for(name)
+        subscription_sources_for(name)
+          .filter_map { |path| File.read(path) if File.exist?(path) }
+          .flat_map do |content|
+            content.scan(/Publisher\.(?:subscribe|attach_once|attach_class)\([^"']*["']([^"']+)["']/m)
+                   .flatten
+          end
+          .uniq
+      end
+
+      def subscription_sources_for(name)
+        engine_rb       = File.join(@engines_root, name, "lib", name, "engine.rb")
+        subscriber_glob = File.join(@engines_root, name, "app", "subscribers", "**", "*.rb")
+
+        # Dir.glob is already sorted on every supported Ruby version.
+        [engine_rb, *Dir.glob(subscriber_glob)]
+      end
+
+      # Walks the subscribe-list and resolves each event back to the
+      # engine that emits it (via the canonical "name.action.<engine>"
+      # naming convention). Returns the set of distinct engine names
+      # this one depends on.
+      def depends_on(name)
+        subscriptions_for(name)
+          .map { |event| event.split(".").last }
+          .reject { |dep| dep.nil? || dep == name }
+          .uniq
+          .sort
+      end
+
+      # Tries to find the engine's actual Ruby module name by reading
+      # its lib/<name>.rb. Falls back to a CamelCase conversion of the
+      # directory name (so `oauth2` becomes `Oauth2` rather than
+      # crashing) when the file is missing or doesn't declare a module.
+      def module_name_for(name)
+        root_file = File.join(@engines_root, name, "lib", "#{name}.rb")
+
+        if File.exist?(root_file)
+          match = File.read(root_file).match(MODULE_DECLARATION)
+          return match[1] if match
+        end
+
+        name.split("_").map(&:capitalize).join
+      end
+    end
+  end
+end

data/lib/seams/cli/quality.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "seams"
+
+module Seams
+  module CLI
+    # Runs the four quality gates the host's `bin/audit` script also
+    # runs (RuboCop, Brakeman, bundler-audit, SimpleCov collation), in
+    # one shot, and reports a unified summary. Each tool that is not
+    # installed in the host's bundle is skipped with a note rather
+    # than failing — hosts opt in by adding the gem.
+    #
+    #   bin/rails seams:quality:all
+    #
+    # Returns true when every gate that ran passed; false otherwise.
+    class Quality
+      DEFAULT_ENGINES_ROOT = "engines"
+
+      def initialize(engines_root: DEFAULT_ENGINES_ROOT, output: $stdout)
+        @engines_root = engines_root
+        @output       = output
+        @results      = {}
+      end
+
+      def call
+        run_rubocop
+        run_brakeman
+        run_bundler_audit
+        run_simplecov_collation
+
+        print_summary
+        @results.values.all? { |status| %i[pass skipped].include?(status) }
+      end
+
+      private
+
+      def run_rubocop
+        if gem_installed?("rubocop")
+          @output.puts("=== rubocop --parallel ===")
+          @results[:rubocop] = system("bundle", "exec", "rubocop", "--parallel") ? :pass : :fail
+        else
+          @output.puts("rubocop not installed — skipping.")
+          @results[:rubocop] = :skipped
+        end
+      end
+
+      def run_brakeman
+        if gem_installed?("brakeman")
+          @output.puts("=== brakeman ===")
+          @results[:brakeman] =
+            system("bundle", "exec", "brakeman", "--no-pager", "--no-progress", "--quiet") ? :pass : :fail
+        else
+          @output.puts("brakeman not installed — skipping.")
+          @results[:brakeman] = :skipped
+        end
+      end
+
+      def run_bundler_audit
+        if gem_installed?("bundler-audit")
+          @output.puts("=== bundle-audit check --update ===")
+          @results[:bundler_audit] = system("bundle", "exec", "bundle-audit", "check", "--update") ? :pass : :fail
+        else
+          @output.puts("bundler-audit not installed — skipping.")
+          @results[:bundler_audit] = :skipped
+        end
+      end
+
+      # Calls the host's script/collate_coverage.rb (shipped by
+      # Phase 1.5). Skipped if the script is not present (older host)
+      # or no per-engine resultset files exist yet.
+      def run_simplecov_collation
+        script = "script/collate_coverage.rb"
+        unless File.exist?(script)
+          @output.puts("script/collate_coverage.rb not present — skipping coverage collation.")
+          @results[:coverage] = :skipped
+          return
+        end
+
+        @output.puts("=== ruby script/collate_coverage.rb ===")
+        @results[:coverage] = system("ruby", script) ? :pass : :fail
+      end
+
+      def gem_installed?(gem_name)
+        Gem::Specification.find_by_name(gem_name)
+        true
+      rescue Gem::LoadError
+        false
+      end
+
+      def print_summary
+        @output.puts("")
+        @output.puts("seams:quality summary")
+        @results.each do |gate, status|
+          @output.puts("  #{gate.to_s.ljust(15)} #{status}")
+        end
+      end
+    end
+  end
+end