seams 0.1.0

data/lib/generators/seams/teams/templates/app/controllers/invitations_controller.rb.tt

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Teams
+  class InvitationsController < ApplicationController
+    include Teams::Authorization
+
+    before_action :set_team,             only: %i[index create destroy]
+    before_action :require_team_admin!,  only: %i[create destroy]
+
+    def index
+      @invitations = @team.invitations.pending
+    end
+
+    def create
+      invitation = @team.invitations.create!(invitation_params)
+      Seams::Events::Publisher.publish(
+        "invitation.sent.teams",
+        invitation_id: invitation.id,
+        team_id:       @team.id,
+        email:         invitation.email,
+        role:          invitation.role,
+        token:         invitation.token
+      )
+      redirect_to team_invitations_path(@team), notice: "Invitation sent"
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to team_invitations_path(@team), alert: e.message
+    end
+
+    def destroy
+      invitation = @team.invitations.find(params[:id])
+      invitation.destroy
+      redirect_to team_invitations_path(@team), notice: "Invitation revoked"
+    end
+
+    # GET /invitations/accept/:token — show the confirmation page.
+    def accept_form
+      @invitation = Teams::Invitation.find_by!(token: params[:token])
+    end
+
+    # POST /invitations/accept/:token — perform the accept.
+    # Wraps the lookup in a row lock and short-circuits if the
+    # invitation has already been accepted, so a double-click on the
+    # email link returns a friendly redirect instead of a 500.
+    def accept
+      Teams::Invitation.transaction do
+        @invitation = Teams::Invitation.lock.find_by!(token: params[:token])
+
+        if @invitation.accepted?
+          return redirect_to team_path(@invitation.team), notice: "You're already a member"
+        end
+
+        if @invitation.expired?
+          return redirect_to root_path, alert: "Invitation expired"
+        end
+
+        @invitation.team.memberships.create!(identity_id: current_identity_id, role: @invitation.role)
+        @invitation.update!(accepted_at: Time.current)
+      end
+
+      Seams::Events::Publisher.publish(
+        "invitation.accepted.teams",
+        team_id:       @invitation.team_id,
+        identity_id:   current_identity_id,
+        invitation_id: @invitation.id
+      )
+      redirect_to team_path(@invitation.team), notice: "Joined #{@invitation.team.name}"
+    rescue ActiveRecord::RecordNotUnique
+      redirect_to team_path(@invitation.team), notice: "You're already a member"
+    end
+
+    private
+
+    def set_team
+      @team = Teams::Team.find(params[:team_id])
+    end
+
+    # `permit` deliberately omits `:role` — Brakeman flags it as
+    # mass-assignment, and even with server-side coercion the
+    # permit-list reads as "we accept whatever role the form posts".
+    # Role is extracted separately via `safe_role` and merged in.
+    def invitation_params
+      params.require(:invitation).permit(:email).merge(role: safe_role)
+    end
+
+    def safe_role
+      candidate = params.dig(:invitation, :role).to_s
+      Teams::Membership::ROLES.include?(candidate) ? candidate : "member"
+    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 it's safe in hosts that don't ship
+    # auth. Override in your host if you wire auth differently.
+    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/app/controllers/memberships_controller.rb.tt

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Teams
+  class MembershipsController < ApplicationController
+    include Teams::Authorization
+
+    before_action :set_team
+    before_action :require_team_member!, only: %i[index]
+    before_action :require_team_admin!,  only: %i[create destroy]
+
+    def index
+      @memberships = @team.memberships
+    end
+
+    def create
+      membership = @team.memberships.create!(membership_params)
+      Seams::Events::Publisher.publish(
+        "team.member_joined.teams",
+        team_id: @team.id, identity_id: membership.identity_id, role: membership.role
+      )
+      redirect_to team_memberships_path(@team), notice: "Member added"
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to team_memberships_path(@team), alert: e.message
+    end
+
+    def destroy
+      membership = @team.memberships.find(params[:id])
+      membership.destroy
+      Seams::Events::Publisher.publish(
+        "team.member_left.teams", team_id: @team.id, identity_id: membership.identity_id
+      )
+      redirect_to team_memberships_path(@team), notice: "Member removed"
+    end
+
+    private
+
+    def set_team
+      @team = Teams::Team.find(params[:team_id])
+    end
+
+    # `permit` deliberately omits `:role` — Brakeman flags it as
+    # mass-assignment, and even with server-side coercion the
+    # permit-list reads as "we accept whatever role the form posts".
+    # Role is extracted separately via `safe_role` and merged in.
+    def membership_params
+      params.require(:membership).permit(:identity_id).merge(role: safe_role)
+    end
+
+    def safe_role
+      candidate = params.dig(:membership, :role).to_s
+      Teams::Membership::ROLES.include?(candidate) ? candidate : "member"
+    end
+  end
+end

data/lib/generators/seams/teams/templates/app/controllers/teams_controller.rb.tt

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Teams
+  class TeamsController < ApplicationController
+    before_action :set_team, only: %i[show edit update destroy]
+
+    def index
+      @teams = Teams::Team.joins(:memberships).where(memberships: { identity_id: current_identity_id })
+    end
+
+    def show; end
+    def new
+      @team = Teams::Team.new
+    end
+
+    def edit; end
+
+    def create
+      @team = Teams::Team.new(team_params)
+      Teams::Team.transaction do
+        @team.save!
+        @team.memberships.create!(identity_id: current_identity_id, role: "owner")
+      end
+
+      Seams::Events::Publisher.publish(
+        "team.created.teams", team_id: @team.id, creator_identity_id: current_identity_id
+      )
+      redirect_to @team, notice: "Team created"
+    rescue ActiveRecord::RecordInvalid
+      render :new, status: :unprocessable_entity
+    end
+
+    def update
+      if @team.update(team_params)
+        redirect_to @team, notice: "Team updated"
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      @team.destroy
+      redirect_to teams_path, notice: "Team deleted"
+    end
+
+    private
+
+    def set_team
+      @team = Teams::Team.find(params[:id])
+    end
+
+    def team_params
+      params.require(:team).permit(:name, :slug)
+    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 it's safe in hosts that don't ship
+    # auth. Override in your host if you wire auth differently.
+    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/app/jobs/application_job.rb.tt

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Teams
+  class ApplicationJob < ::ApplicationJob
+  end
+end

data/lib/generators/seams/teams/templates/app/mailers/invitation_mailer.rb.tt

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Teams
+  # Sends the email a team invitation generates. The default invocation
+  # is `InvitationMailer.invite(invitation_id)` from
+  # `Teams::InvitationSubscriber` — both the controller and any other
+  # caller can also invoke it directly.
+  #
+  # Override the body by dropping a file at
+  # `app/views/teams/invitation_mailer/invite.text.erb` (or .html.erb)
+  # in the host application.
+  class InvitationMailer < ActionMailer::Base
+    default from: -> { Teams.configuration.invitation_mailer_from }
+
+    def invite(invitation_id)
+      @invitation = Teams::Invitation.find(invitation_id)
+      @team       = @invitation.team
+      @accept_url = build_accept_url(@invitation.token)
+
+      mail(
+        to:      @invitation.email,
+        subject: "You're invited to join #{@team.name}"
+      )
+    end
+
+    private
+
+    def build_accept_url(token)
+      base = Teams.configuration.host_url.to_s
+      base = base.sub(/\/+\z/, "")
+      "#{base}/teams/invitations/accept/#{token}"
+    end
+  end
+end

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

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

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Teams
+  # ActiveSupport::CurrentAttributes namespace for the Teams engine.
+  # Set once per request by the host (typically a before_action that
+  # resolves the team from the URL or session); readable from anywhere
+  # downstream without explicit threading.
+  #
+  # `Teams::AccountScoped` reads `Teams::Current.team` to filter rows
+  # to the current team. When unset, the default_scope short-circuits
+  # to a no-op so background jobs that don't bind a team still see
+  # their full set — wire `Teams::Current.team =` into your job's
+  # #perform if you need scoping there.
+  #
+  # Peer to `Auth::Current` and `Accounts::Current`. No cross-engine
+  # cascade — Teams::Current owns only the current team. The
+  # signed-in identity lives in `Auth::Current.identity`; the active
+  # tenant account lives in `Accounts::Current.account`.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :team
+
+    def with_team(value, &)
+      with(team: value, &)
+    end
+
+    def without_team(&)
+      with(team: nil, &)
+    end
+  end
+end

data/lib/generators/seams/teams/templates/app/models/invitation.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Teams
+  class Invitation < ApplicationRecord
+    self.table_name = "team_invitations"
+
+    belongs_to :team, class_name: "Teams::Team"
+
+    validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
+    validates :token, presence: true, uniqueness: true
+    validates :role, inclusion: { in: Teams::Membership::ROLES }
+
+    before_validation :assign_token, on: :create
+    before_validation :assign_expiry, on: :create
+
+    scope :pending, -> { where(accepted_at: nil).where("expires_at > ?", Time.current) }
+
+    def expired?
+      expires_at <= Time.current
+    end
+
+    def accepted?
+      accepted_at.present?
+    end
+
+    private
+
+    def assign_token
+      self.token ||= SecureRandom.urlsafe_base64(32)
+    end
+
+    def assign_expiry
+      self.expires_at ||= Time.current + Teams.configuration.invitation_ttl
+    end
+  end
+end

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Teams
+  # Joins a Teams::Team to an Auth::Identity with a role. Wave 9 made
+  # teams a peer engine to accounts: the join is direct to Identity
+  # (not to an Accounts::Membership). `identity_id` is a bare bigint
+  # FK with no `belongs_to :identity` because Auth::Identity lives in
+  # a sibling engine and cross-engine ActiveRecord access is forbidden
+  # by the Seams/NoCrossEngineModelAccess cop. Look up the human via
+  # the auth engine's API or by `Auth::Identity.find(identity_id)` from
+  # host code.
+  class Membership < ApplicationRecord
+    self.table_name = "team_memberships"
+
+    # Teams roles are independent of Accounts roles by design — a
+    # team is its own RBAC unit. Hosts that want a single role across
+    # both should denormalise that themselves.
+    ROLES = %w[owner admin member].freeze
+
+    belongs_to :team, class_name: "Teams::Team"
+
+    validates :identity_id, presence: true, uniqueness: { scope: :team_id }
+    validates :role, inclusion: { in: ROLES }
+
+    scope :owners, -> { where(role: "owner") }
+    scope :admins, -> { where(role: %w[owner admin]) }
+
+    def owner?
+      role == "owner"
+    end
+
+    def admin?
+      %w[owner admin].include?(role)
+    end
+  end
+end

data/lib/generators/seams/teams/templates/app/models/team.rb.tt

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Teams
+  class Team < ApplicationRecord
+    self.table_name = "teams"
+
+    has_many :memberships, class_name: "Teams::Membership", foreign_key: :team_id, dependent: :destroy
+    has_many :invitations, class_name: "Teams::Invitation", dependent: :destroy
+
+    validates :name, presence: true, length: { maximum: 100 }
+    validates :slug, presence: true, uniqueness: true,
+                     format: { with: /\A[a-z0-9-]+\z/, message: "may only contain lowercase letters, digits and dashes" }
+
+    before_validation :assign_slug, on: :create
+
+    def owner_membership
+      memberships.find_by(role: "owner")
+    end
+
+    # Predicate for "is this Identity a member of this team?". Pass the
+    # Auth::Identity's id (the team_memberships.identity_id column).
+    def member?(identity_id)
+      memberships.exists?(identity_id: identity_id)
+    end
+
+    private
+
+    def assign_slug
+      self.slug ||= name.to_s.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/(^-|-$)/, "")
+    end
+  end
+end

data/lib/generators/seams/teams/templates/app/subscribers/invitation_subscriber.rb.tt

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Teams
+  # Consumes Teams events. On +invitation.sent.teams+:
+  #   1. Resolves the Teams::Invitation by id from the payload.
+  #   2. Enqueues Teams::InvitationMailer.invite — `deliver_later` so
+  #      the publisher's transaction isn't blocked on SMTP.
+  #
+  # +.attach!+ is idempotent — Rails reload won't double-subscribe, and
+  # because we register the subscriber CLASS by its String name via
+  # +attach_class+, dispatch re-resolves the constant on every event so
+  # edits to +handle_invitation_sent+ take effect without a server restart.
+  class InvitationSubscriber
+    SUBSCRIBER_KEY = :teams_invitation_subscriber
+
+    class << self
+      def attach!
+        Seams::Events::Publisher.attach_class(
+          SUBSCRIBER_KEY,
+          "invitation.sent.teams",
+          class_name:  "Teams::InvitationSubscriber",
+          method_name: :handle_invitation_sent
+        )
+      end
+
+      private
+
+      def handle_invitation_sent(payload)
+        invitation_id = payload[:invitation_id]
+        return unless invitation_id
+
+        Teams::InvitationMailer.invite(invitation_id).deliver_later
+      end
+    end
+  end
+end

data/lib/generators/seams/teams/templates/app/views/invitation_mailer/invite.text.erb.tt

@@ -0,0 +1,8 @@
+<%%# Default invitation email body. Override at %>
+<%%# app/views/teams/invitation_mailer/invite.text.erb in your host. %>
+You've been invited to join <%%= @team.name %>.
+
+Accept the invitation here:
+<%%= @accept_url %>
+
+If you don't recognise this team, you can ignore this email.

data/lib/generators/seams/teams/templates/app/views/invitations/index.html.erb.tt

@@ -0,0 +1,44 @@
+<%%# Pending + sent invitations for a team. Owners + admins can %>
+<%%# revoke pending invitations; the recipient accepts via the %>
+<%%# token-keyed top-level route (/invitations/accept/:token). %>
+<h1>Invitations — <%%= @team.name %></h1>
+
+<%%= link_to "← Back to team", @team %>
+
+<h2>Send a new invitation</h2>
+<%%= form_with url: team_invitations_path(@team) do |form| %>
+  <p>
+    <%%= form.label :email %>
+    <%%= form.email_field :email, required: true %>
+  </p>
+  <p>
+    <%%= form.label :role %>
+    <%%= form.select :role, %w[member admin] %>
+  </p>
+  <%%= form.submit "Send invite" %>
+<%% end %>
+
+<h2>Pending</h2>
+<%% if @invitations.empty? %>
+  <p>No pending invitations.</p>
+<%% else %>
+  <table>
+    <thead>
+      <tr><th>Email</th><th>Role</th><th>Expires</th><th></th></tr>
+    </thead>
+    <tbody>
+      <%% @invitations.each do |invitation| %>
+        <tr>
+          <td><%%= invitation.email %></td>
+          <td><%%= invitation.role.titleize %></td>
+          <td><%%= invitation.expires_at.to_date %></td>
+          <td>
+            <%%= button_to "Revoke",
+                          team_invitation_path(@team, invitation),
+                          method: :delete %>
+          </td>
+        </tr>
+      <%% end %>
+    </tbody>
+  </table>
+<%% end %>

data/lib/generators/seams/teams/templates/app/views/memberships/index.html.erb.tt

@@ -0,0 +1,32 @@
+<%%# Members table. Owners + admins can remove a member or change %>
+<%%# their role; members read-only see the list. The Identity column %>
+<%%# shows the raw identity_id — hosts that want to render the human's %>
+<%%# email/name should override this view and look the Identity up %>
+<%%# themselves (cross-engine boundary keeps Teams from joining to %>
+<%%# auth_identities at the data layer). %>
+<h1>Members of <%%= @team.name %></h1>
+
+<%%= link_to "← Back to team", @team %>
+
+<table>
+  <thead>
+    <tr><th>Identity</th><th>Role</th><th>Joined</th><th></th></tr>
+  </thead>
+  <tbody>
+    <%% @memberships.each do |membership| %>
+      <tr>
+        <td><%%= membership.identity_id %></td>
+        <td><%%= membership.role.titleize %></td>
+        <td><%%= membership.created_at.to_date %></td>
+        <td>
+          <%% if can_manage_team_members? %>
+            <%%= button_to "Remove",
+                          team_membership_path(@team, membership),
+                          method: :delete,
+                          data: { confirm: "Remove this member?" } %>
+          <%% end %>
+        </td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>

data/lib/generators/seams/teams/templates/app/views/teams/edit.html.erb.tt

@@ -0,0 +1,28 @@
+<%%# Team settings — name + slug. Roles + member operations live %>
+<%%# under the memberships endpoint, not here. %>
+<h1>Settings — <%%= @team.name %></h1>
+
+<%%= form_with model: @team, url: team_path(@team), method: :patch do |form| %>
+  <%% if @team.errors.any? %>
+    <ul class="errors">
+      <%% @team.errors.full_messages.each do |message| %>
+        <li><%%= message %></li>
+      <%% end %>
+    </ul>
+  <%% end %>
+
+  <p>
+    <%%= form.label :name %>
+    <%%= form.text_field :name, required: true %>
+  </p>
+
+  <p>
+    <%%= form.label :slug %>
+    <%%= form.text_field :slug, required: true %>
+  </p>
+
+  <%%= form.submit "Save" %>
+<%% end %>
+
+<%%= button_to "Delete team", team_path(@team), method: :delete,
+                                                data: { confirm: "This is irreversible. Continue?" } %>

data/lib/generators/seams/teams/templates/app/views/teams/index.html.erb.tt

@@ -0,0 +1,15 @@
+<%%# Lists every team the signed-in user is a member of. Override at %>
+<%%# app/views/teams/teams/index.html.erb in your host. %>
+<h1>Your teams</h1>
+
+<%%= link_to "New team", new_team_path %>
+
+<%% if @teams.empty? %>
+  <p>You're not on any teams yet.</p>
+<%% else %>
+  <ul>
+    <%% @teams.each do |team| %>
+      <li><%%= link_to team.name, team %> <small>(<%%= team.slug %>)</small></li>
+    <%% end %>
+  </ul>
+<%% end %>

data/lib/generators/seams/teams/templates/app/views/teams/new.html.erb.tt

@@ -0,0 +1,24 @@
+<%%# New team form — the creator becomes the owner via TeamsController#create. %>
+<h1>New team</h1>
+
+<%%= form_with model: @team, url: teams_path do |form| %>
+  <%% if @team.errors.any? %>
+    <ul class="errors">
+      <%% @team.errors.full_messages.each do |message| %>
+        <li><%%= message %></li>
+      <%% end %>
+    </ul>
+  <%% end %>
+
+  <p>
+    <%%= form.label :name %>
+    <%%= form.text_field :name, required: true %>
+  </p>
+
+  <p>
+    <%%= form.label :slug %>
+    <%%= form.text_field :slug, required: true %>
+  </p>
+
+  <%%= form.submit "Create team" %>
+<%% end %>

data/lib/generators/seams/teams/templates/app/views/teams/show.html.erb.tt

@@ -0,0 +1,17 @@
+<%%# Single team page. Top section = team metadata + edit link. %>
+<%%# Members table linked to the memberships endpoint. Invitations %>
+<%%# linked to the invitations endpoint when the engine ships them. %>
+<h1><%%= @team.name %></h1>
+<p><small><%%= @team.slug %></small></p>
+
+<%%= link_to "Settings", edit_team_path(@team) %>
+
+<h2>Members</h2>
+<%%= link_to "Manage members", team_memberships_path(@team) %>
+
+<h2>Invitations</h2>
+<%% if defined?(team_invitations_path) %>
+  <%%= link_to "Manage invitations", team_invitations_path(@team) %>
+<%% else %>
+  <p><em>Invitation feature not enabled (regenerate with --with=invitations).</em></p>
+<%% end %>

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Teams::Engine.routes.draw do
+  # Follow-up generators that add admin-only or token-only routes splice them here, ahead of the canonical teams resource.
+  # seams:insertion-point teams.routes.before_teams
+  resources :teams, only: %i[index show new create edit update destroy] do
+    resources :memberships, only: %i[index create destroy]
+    resources :invitations, only: %i[index create destroy]
+  end
+
+  # Token-only accept route — the recipient clicks a link from the
+  # invitation email and doesn't know the team_id. Lives at the top
+  # level so the URL is short and shareable.
+  get  "/invitations/accept/:token", to: "invitations#accept_form", as: :accept_invitation
+  post "/invitations/accept/:token", to: "invitations#accept",      as: :confirm_invitation
+
+  # Follow-up generators that add new top-level team routes (transfer, archive) splice them here.
+  # seams:insertion-point teams.routes.after_invitations
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# What: creates the team_invitations table.
+# Why:  invitation lifecycle (sent / accepted / expired / revoked) is
+#       distinct from membership and we want to keep the audit trail
+#       even after the recipient joins.
+# Risk: append-mostly. Token uniqueness is the security guarantee.
+class CreateTeamInvitations < ActiveRecord::Migration[7.1]
+  def change
+    create_table :team_invitations do |t|
+      t.references :team,        null: false, foreign_key: { to_table: :teams }, index: true
+      t.string     :email,       null: false
+      t.string     :token,       null: false
+      t.string     :role,        null: false, default: "member"
+      t.datetime   :expires_at,  null: false
+      t.datetime   :accepted_at
+      t.timestamps
+    end
+
+    add_index :team_invitations, :token, unique: true
+    add_index :team_invitations, %i[team_id email], unique: true,
+                                                    where: "accepted_at IS NULL"
+  end
+end